1 This is gdb.info, produced by makeinfo version 4.13 from
2 /home/jingyu/projects/gcc/android-toolchainsrc/build/../gdb/gdb-7.1.x/gdb/doc/gdb.texinfo.
4 INFO-DIR-SECTION Software development
6 * Gdb: (gdb). The GNU debugger.
9 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
10 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
11 2010 Free Software Foundation, Inc.
13 Permission is granted to copy, distribute and/or modify this document
14 under the terms of the GNU Free Documentation License, Version 1.1 or
15 any later version published by the Free Software Foundation; with the
16 Invariant Sections being "Free Software" and "Free Software Needs Free
17 Documentation", with the Front-Cover Texts being "A GNU Manual," and
18 with the Back-Cover Texts as in (a) below.
20 (a) The FSF's Back-Cover Text is: "You are free to copy and modify
21 this GNU Manual. Buying copies from GNU Press supports the FSF in
22 developing GNU and promoting software freedom."
24 This file documents the GNU debugger GDB.
26 This is the Ninth Edition, of `Debugging with GDB: the GNU
27 Source-Level Debugger' for GDB (GDB) Version 7.1-android-gg2.
29 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
30 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
31 2010 Free Software Foundation, Inc.
33 Permission is granted to copy, distribute and/or modify this document
34 under the terms of the GNU Free Documentation License, Version 1.1 or
35 any later version published by the Free Software Foundation; with the
36 Invariant Sections being "Free Software" and "Free Software Needs Free
37 Documentation", with the Front-Cover Texts being "A GNU Manual," and
38 with the Back-Cover Texts as in (a) below.
40 (a) The FSF's Back-Cover Text is: "You are free to copy and modify
41 this GNU Manual. Buying copies from GNU Press supports the FSF in
42 developing GNU and promoting software freedom."
45 File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir)
50 This file describes GDB, the GNU symbolic debugger.
52 This is the Ninth Edition, for GDB (GDB) Version 7.1-android-gg2.
54 Copyright (C) 1988-2010 Free Software Foundation, Inc.
56 This edition of the GDB manual is dedicated to the memory of Fred
57 Fish. Fred was a long-standing contributor to GDB and to Free software
58 in general. We will miss him.
62 * Summary:: Summary of GDB
63 * Sample Session:: A sample GDB session
65 * Invocation:: Getting in and out of GDB
66 * Commands:: GDB commands
67 * Running:: Running programs under GDB
68 * Stopping:: Stopping and continuing
69 * Reverse Execution:: Running programs backward
70 * Process Record and Replay:: Recording inferior's execution and replaying it
71 * Stack:: Examining the stack
72 * Source:: Examining source files
73 * Data:: Examining data
74 * Optimized Code:: Debugging optimized code
75 * Macros:: Preprocessor Macros
76 * Tracepoints:: Debugging remote targets non-intrusively
77 * Overlays:: Debugging programs that use overlays
79 * Languages:: Using GDB with different languages
81 * Symbols:: Examining the symbol table
82 * Altering:: Altering execution
83 * GDB Files:: GDB files
84 * Targets:: Specifying a debugging target
85 * Remote Debugging:: Debugging remote programs
86 * Configurations:: Configuration-specific information
87 * Controlling GDB:: Controlling GDB
88 * Extending GDB:: Extending GDB
89 * Interpreters:: Command Interpreters
90 * TUI:: GDB Text User Interface
91 * Emacs:: Using GDB under GNU Emacs
92 * GDB/MI:: GDB's Machine Interface.
93 * Annotations:: GDB's annotation interface.
94 * JIT Interface:: Using the JIT debugging interface.
96 * GDB Bugs:: Reporting bugs in GDB
98 * Command Line Editing:: Command Line Editing
99 * Using History Interactively:: Using History Interactively
100 * Formatting Documentation:: How to format and print GDB documentation
101 * Installing GDB:: Installing GDB
102 * Maintenance Commands:: Maintenance Commands
103 * Remote Protocol:: GDB Remote Serial Protocol
104 * Agent Expressions:: The GDB Agent Expression Mechanism
105 * Target Descriptions:: How targets can describe themselves to
107 * Operating System Information:: Getting additional information from
109 * Trace File Format:: GDB trace file format
110 * Copying:: GNU General Public License says
111 how you can copy and share GDB
112 * GNU Free Documentation License:: The license for this documentation
116 File: gdb.info, Node: Summary, Next: Sample Session, Prev: Top, Up: Top
121 The purpose of a debugger such as GDB is to allow you to see what is
122 going on "inside" another program while it executes--or what another
123 program was doing at the moment it crashed.
125 GDB can do four main kinds of things (plus other things in support of
126 these) to help you catch bugs in the act:
128 * Start your program, specifying anything that might affect its
131 * Make your program stop on specified conditions.
133 * Examine what has happened, when your program has stopped.
135 * Change things in your program, so you can experiment with
136 correcting the effects of one bug and go on to learn about another.
138 You can use GDB to debug programs written in C and C++. For more
139 information, see *note Supported Languages: Supported Languages. For
140 more information, see *note C and C++: C.
142 Support for Modula-2 is partial. For information on Modula-2, see
143 *note Modula-2: Modula-2.
145 Debugging Pascal programs which use sets, subranges, file variables,
146 or nested functions does not currently work. GDB does not support
147 entering expressions, printing values, or similar features using Pascal
150 GDB can be used to debug programs written in Fortran, although it
151 may be necessary to refer to some variables with a trailing underscore.
153 GDB can be used to debug programs written in Objective-C, using
154 either the Apple/NeXT or the GNU Objective-C runtime.
158 * Free Software:: Freely redistributable software
159 * Contributors:: Contributors to GDB
162 File: gdb.info, Node: Free Software, Next: Contributors, Up: Summary
167 GDB is "free software", protected by the GNU General Public License
168 (GPL). The GPL gives you the freedom to copy or adapt a licensed
169 program--but every person getting a copy also gets with it the freedom
170 to modify that copy (which means that they must get access to the
171 source code), and the freedom to distribute further copies. Typical
172 software companies use copyrights to limit your freedoms; the Free
173 Software Foundation uses the GPL to preserve these freedoms.
175 Fundamentally, the General Public License is a license which says
176 that you have these freedoms and that you cannot take these freedoms
177 away from anyone else.
179 Free Software Needs Free Documentation
180 ======================================
182 The biggest deficiency in the free software community today is not in
183 the software--it is the lack of good free documentation that we can
184 include with the free software. Many of our most important programs do
185 not come with free reference manuals and free introductory texts.
186 Documentation is an essential part of any software package; when an
187 important free software package does not come with a free manual and a
188 free tutorial, that is a major gap. We have many such gaps today.
190 Consider Perl, for instance. The tutorial manuals that people
191 normally use are non-free. How did this come about? Because the
192 authors of those manuals published them with restrictive terms--no
193 copying, no modification, source files not available--which exclude
194 them from the free software world.
196 That wasn't the first time this sort of thing happened, and it was
197 far from the last. Many times we have heard a GNU user eagerly
198 describe a manual that he is writing, his intended contribution to the
199 community, only to learn that he had ruined everything by signing a
200 publication contract to make it non-free.
202 Free documentation, like free software, is a matter of freedom, not
203 price. The problem with the non-free manual is not that publishers
204 charge a price for printed copies--that in itself is fine. (The Free
205 Software Foundation sells printed copies of manuals, too.) The problem
206 is the restrictions on the use of the manual. Free manuals are
207 available in source code form, and give you permission to copy and
208 modify. Non-free manuals do not allow this.
210 The criteria of freedom for a free manual are roughly the same as for
211 free software. Redistribution (including the normal kinds of
212 commercial redistribution) must be permitted, so that the manual can
213 accompany every copy of the program, both on-line and on paper.
215 Permission for modification of the technical content is crucial too.
216 When people modify the software, adding or changing features, if they
217 are conscientious they will change the manual too--so they can provide
218 accurate and clear documentation for the modified program. A manual
219 that leaves you no choice but to write a new manual to document a
220 changed version of the program is not really available to our community.
222 Some kinds of limits on the way modification is handled are
223 acceptable. For example, requirements to preserve the original
224 author's copyright notice, the distribution terms, or the list of
225 authors, are ok. It is also no problem to require modified versions to
226 include notice that they were modified. Even entire sections that may
227 not be deleted or changed are acceptable, as long as they deal with
228 nontechnical topics (like this one). These kinds of restrictions are
229 acceptable because they don't obstruct the community's normal use of
232 However, it must be possible to modify all the _technical_ content
233 of the manual, and then distribute the result in all the usual media,
234 through all the usual channels. Otherwise, the restrictions obstruct
235 the use of the manual, it is not free, and we need another manual to
238 Please spread the word about this issue. Our community continues to
239 lose manuals to proprietary publishing. If we spread the word that
240 free software needs free reference manuals and free tutorials, perhaps
241 the next person who wants to contribute by writing documentation will
242 realize, before it is too late, that only free manuals contribute to
243 the free software community.
245 If you are writing documentation, please insist on publishing it
246 under the GNU Free Documentation License or another free documentation
247 license. Remember that this decision requires your approval--you don't
248 have to let the publisher decide. Some commercial publishers will use
249 a free license if you insist, but they will not propose the option; it
250 is up to you to raise the issue and say firmly that this is what you
251 want. If the publisher you are dealing with refuses, please try other
252 publishers. If you're not sure whether a proposed license is free,
253 write to <licensing@gnu.org>.
255 You can encourage commercial publishers to sell more free, copylefted
256 manuals and tutorials by buying them, and particularly by buying copies
257 from the publishers that paid for their writing or for major
258 improvements. Meanwhile, try to avoid buying non-free documentation at
259 all. Check the distribution terms of a manual before you buy it, and
260 insist that whoever seeks your business must respect your freedom.
261 Check the history of the book, and try to reward the publishers that
262 have paid or pay the authors to work on it.
264 The Free Software Foundation maintains a list of free documentation
265 published by other publishers, at
266 `http://www.fsf.org/doc/other-free-books.html'.
269 File: gdb.info, Node: Contributors, Prev: Free Software, Up: Summary
274 Richard Stallman was the original author of GDB, and of many other GNU
275 programs. Many others have contributed to its development. This
276 section attempts to credit major contributors. One of the virtues of
277 free software is that everyone is free to contribute to it; with
278 regret, we cannot actually acknowledge everyone here. The file
279 `ChangeLog' in the GDB distribution approximates a blow-by-blow account.
281 Changes much prior to version 2.0 are lost in the mists of time.
283 _Plea:_ Additions to this section are particularly welcome. If you
284 or your friends (or enemies, to be evenhanded) have been unfairly
285 omitted from this list, we would like to add your names!
287 So that they may not regard their many labors as thankless, we
288 particularly thank those who shepherded GDB through major releases:
289 Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim
290 Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs
291 (release 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10,
292 and 4.9); Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5,
293 and 4.4); John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim
294 Kingdon (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2,
297 Richard Stallman, assisted at various times by Peter TerMaat, Chris
298 Hanson, and Richard Mlynarik, handled releases through 2.8.
300 Michael Tiemann is the author of most of the GNU C++ support in GDB,
301 with significant additional contributions from Per Bothner and Daniel
302 Berlin. James Clark wrote the GNU C++ demangler. Early work on C++
303 was by Peter TerMaat (who also did much general update work leading to
306 GDB uses the BFD subroutine library to examine multiple object-file
307 formats; BFD was a joint project of David V. Henkel-Wallace, Rich
308 Pixley, Steve Chamberlain, and John Gilmore.
310 David Johnson wrote the original COFF support; Pace Willison did the
311 original support for encapsulated COFF.
313 Brent Benson of Harris Computer Systems contributed DWARF 2 support.
315 Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
316 Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
317 support. Jean-Daniel Fekete contributed Sun 386i support. Chris
318 Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki
319 Hasei contributed Sony/News OS 3 support. David Johnson contributed
320 Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support.
321 Jeff Law contributed HP PA and SOM support. Keith Packard contributed
322 NS32K support. Doug Rabson contributed Acorn Risc Machine support.
323 Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith
324 contributed Convex support (and Fortran debugging). Jonathan Stone
325 contributed Pyramid support. Michael Tiemann contributed SPARC support.
326 Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
327 Pace Willison contributed Intel 386 support. Jay Vosburgh contributed
328 Symmetry support. Marko Mlinar contributed OpenRISC 1000 support.
330 Andreas Schwab contributed M68K GNU/Linux support.
332 Rich Schaefer and Peter Schauer helped with support of SunOS shared
335 Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about
336 several machine instruction sets.
338 Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped
339 develop remote debugging. Intel Corporation, Wind River Systems, AMD,
340 and ARM contributed remote debugging modules for the i960, VxWorks,
341 A29K UDI, and RDI targets, respectively.
343 Brian Fox is the author of the readline libraries providing
344 command-line editing and command history.
346 Andrew Beers of SUNY Buffalo wrote the language-switching code, the
347 Modula-2 support, and contributed the Languages chapter of this manual.
349 Fred Fish wrote most of the support for Unix System Vr4. He also
350 enhanced the command-completion support to cover C++ overloaded symbols.
352 Hitachi America (now Renesas America), Ltd. sponsored the support for
353 H8/300, H8/500, and Super-H processors.
355 NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx
358 Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and
361 Toshiba sponsored the support for the TX39 Mips processor.
363 Matsushita sponsored the support for the MN10200 and MN10300
366 Fujitsu sponsored the support for SPARClite and FR30 processors.
368 Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
371 Michael Snyder added support for tracepoints.
373 Stu Grossman wrote gdbserver.
375 Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly
376 innumerable bug fixes and cleanups throughout GDB.
378 The following people at the Hewlett-Packard Company contributed
379 support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
380 (narrow mode), HP's implementation of kernel threads, HP's aC++
381 compiler, and the Text User Interface (nee Terminal User Interface):
382 Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann,
383 Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase
384 provided HP-specific information in this manual.
386 DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert
387 Hoehne made significant contributions to the DJGPP port.
389 Cygnus Solutions has sponsored GDB maintenance and much of its
390 development since 1991. Cygnus engineers who have worked on GDB
391 fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
392 Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
393 Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
394 Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek
395 Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In
396 addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,
397 JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug
398 Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
399 Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,
400 Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin
401 Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela
402 Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
403 Zuhn have made contributions both large and small.
405 Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for
406 Cygnus Solutions, implemented the original GDB/MI interface.
408 Jim Blandy added support for preprocessor macros, while working for
411 Andrew Cagney designed GDB's architecture vector. Many people
412 including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek,
413 Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto,
414 Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna
415 Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration
416 of old architectures to this new framework.
418 Andrew Cagney completely re-designed and re-implemented GDB's
419 unwinder framework, this consisting of a fresh new design featuring
420 frame IDs, independent frame sniffers, and the sentinel frame. Mark
421 Kettenis implemented the DWARF 2 unwinder, Jeff Johnston the libunwind
422 unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad
423 unwinders. The architecture-specific changes, each involving a
424 complete rewrite of the architecture's frame code, were carried out by
425 Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane
426 Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel
427 Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei
428 Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich
431 Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from
432 Tensilica, Inc. contributed support for Xtensa processors. Others who
433 have worked on the Xtensa port of GDB in the past include Steve Tjiang,
434 John Newlin, and Scott Foehner.
436 Michael Eager and staff of Xilinx, Inc., contributed support for the
437 Xilinx MicroBlaze architecture.
440 File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top
442 1 A Sample GDB Session
443 **********************
445 You can use this manual at your leisure to read all about GDB.
446 However, a handful of commands are enough to get started using the
447 debugger. This chapter illustrates those commands.
449 One of the preliminary versions of GNU `m4' (a generic macro
450 processor) exhibits the following bug: sometimes, when we change its
451 quote strings from the default, the commands used to capture one macro
452 definition within another stop working. In the following short `m4'
453 session, we define a macro `foo' which expands to `0000'; we then use
454 the `m4' built-in `defn' to define `bar' as the same thing. However,
455 when we change the open quote string to `<QUOTE>' and the close quote
456 string to `<UNQUOTE>', the same procedure fails to define a new synonym
465 define(bar,defn(`foo'))
469 changequote(<QUOTE>,<UNQUOTE>)
471 define(baz,defn(<QUOTE>foo<UNQUOTE>))
474 m4: End of input: 0: fatal error: EOF in string
476 Let us use GDB to try to see what is going on.
479 GDB is free software and you are welcome to distribute copies
480 of it under certain conditions; type "show copying" to see
482 There is absolutely no warranty for GDB; type "show warranty"
485 GDB 7.1-android-gg2, Copyright 1999 Free Software Foundation, Inc...
488 GDB reads only enough symbol data to know where to find the rest when
489 needed; as a result, the first prompt comes up very quickly. We now
490 tell GDB to use a narrower display width than usual, so that examples
495 We need to see how the `m4' built-in `changequote' works. Having
496 looked at the source, we know the relevant subroutine is
497 `m4_changequote', so we set a breakpoint there with the GDB `break'
500 (gdb) break m4_changequote
501 Breakpoint 1 at 0x62f4: file builtin.c, line 879.
503 Using the `run' command, we start `m4' running under GDB control; as
504 long as control does not reach the `m4_changequote' subroutine, the
505 program runs as usual:
508 Starting program: /work/Editorial/gdb/gnu/m4/m4
514 To trigger the breakpoint, we call `changequote'. GDB suspends
515 execution of `m4', displaying information about the context where it
518 changequote(<QUOTE>,<UNQUOTE>)
520 Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
522 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
524 Now we use the command `n' (`next') to advance execution to the next
525 line of the current function.
528 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
531 `set_quotes' looks like a promising subroutine. We can go into it by
532 using the command `s' (`step') instead of `next'. `step' goes to the
533 next line to be executed in _any_ subroutine, so it steps into
537 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
539 530 if (lquote != def_lquote)
541 The display that shows the subroutine where `m4' is now suspended (and
542 its arguments) is called a stack frame display. It shows a summary of
543 the stack. We can use the `backtrace' command (which can also be
544 spelled `bt'), to see where we are in the stack as a whole: the
545 `backtrace' command displays a stack frame for each active subroutine.
548 #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
550 #1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
552 #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
553 #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
555 #4 0x79dc in expand_input () at macro.c:40
556 #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
558 We step through a few more lines to see what happens. The first two
559 times, we can use `s'; the next two times we use `n' to avoid falling
560 into the `xstrdup' subroutine.
563 0x3b5c 532 if (rquote != def_rquote)
565 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
566 def_lquote : xstrdup(lq);
568 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
571 538 len_lquote = strlen(rquote);
573 The last line displayed looks a little odd; we can examine the variables
574 `lquote' and `rquote' to see if they are in fact the new left and right
575 quotes we specified. We use the command `p' (`print') to see their
579 $1 = 0x35d40 "<QUOTE>"
581 $2 = 0x35d50 "<UNQUOTE>"
583 `lquote' and `rquote' are indeed the new left and right quotes. To
584 look at some context, we can display ten lines of source surrounding
585 the current line with the `l' (`list') command.
590 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
592 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
595 538 len_lquote = strlen(rquote);
596 539 len_rquote = strlen(lquote);
601 Let us step past the two lines that set `len_lquote' and `len_rquote',
602 and then examine the values of those variables.
605 539 len_rquote = strlen(lquote);
613 That certainly looks wrong, assuming `len_lquote' and `len_rquote' are
614 meant to be the lengths of `lquote' and `rquote' respectively. We can
615 set them to better values using the `p' command, since it can print the
616 value of any expression--and that expression can include subroutine
617 calls and assignments.
619 (gdb) p len_lquote=strlen(lquote)
621 (gdb) p len_rquote=strlen(rquote)
624 Is that enough to fix the problem of using the new quotes with the `m4'
625 built-in `defn'? We can allow `m4' to continue executing with the `c'
626 (`continue') command, and then try the example that caused trouble
632 define(baz,defn(<QUOTE>foo<UNQUOTE>))
637 Success! The new quotes now work just as well as the default ones. The
638 problem seems to have been just the two typos defining the wrong
639 lengths. We allow `m4' exit by giving it an EOF as input:
642 Program exited normally.
644 The message `Program exited normally.' is from GDB; it indicates `m4'
645 has finished executing. We can end our GDB session with the GDB `quit'
651 File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top
653 2 Getting In and Out of GDB
654 ***************************
656 This chapter discusses how to start GDB, and how to get out of it. The
658 * type `gdb' to start GDB.
660 * type `quit' or `Ctrl-d' to exit.
664 * Invoking GDB:: How to start GDB
665 * Quitting GDB:: How to quit GDB
666 * Shell Commands:: How to use shell commands inside GDB
667 * Logging Output:: How to log GDB's output to a file
670 File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation
675 Invoke GDB by running the program `gdb'. Once started, GDB reads
676 commands from the terminal until you tell it to exit.
678 You can also run `gdb' with a variety of arguments and options, to
679 specify more of your debugging environment at the outset.
681 The command-line options described here are designed to cover a
682 variety of situations; in some environments, some of these options may
683 effectively be unavailable.
685 The most usual way to start GDB is with one argument, specifying an
690 You can also start with both an executable program and a core file
695 You can, instead, specify a process ID as a second argument, if you
696 want to debug a running process:
700 would attach GDB to process `1234' (unless you also have a file named
701 `1234'; GDB does check for a core file first).
703 Taking advantage of the second command-line argument requires a
704 fairly complete operating system; when you use GDB as a remote debugger
705 attached to a bare board, there may not be any notion of "process", and
706 there is often no way to get a core dump. GDB will warn you if it is
707 unable to attach or to read core dumps.
709 You can optionally have `gdb' pass any arguments after the
710 executable file to the inferior using `--args'. This option stops
712 gdb --args gcc -O2 -c foo.c
713 This will cause `gdb' to debug `gcc', and to set `gcc''s
714 command-line arguments (*note Arguments::) to `-O2 -c foo.c'.
716 You can run `gdb' without printing the front material, which
717 describes GDB's non-warranty, by specifying `-silent':
721 You can further control how GDB starts up by using command-line
722 options. GDB itself can remind you of the options available.
728 to display all available options and briefly describe their use (`gdb
729 -h' is a shorter equivalent).
731 All options and command line arguments you give are processed in
732 sequential order. The order makes a difference when the `-x' option is
737 * File Options:: Choosing files
738 * Mode Options:: Choosing modes
739 * Startup:: What GDB does during startup
742 File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB
747 When GDB starts, it reads any arguments other than options as
748 specifying an executable file and core file (or process ID). This is
749 the same as if the arguments were specified by the `-se' and `-c' (or
750 `-p') options respectively. (GDB reads the first argument that does
751 not have an associated option flag as equivalent to the `-se' option
752 followed by that argument; and the second argument that does not have
753 an associated option flag, if any, as equivalent to the `-c'/`-p'
754 option followed by that argument.) If the second argument begins with
755 a decimal digit, GDB will first attempt to attach to it as a process,
756 and if that fails, attempt to open it as a corefile. If you have a
757 corefile whose name begins with a digit, you can prevent GDB from
758 treating it as a pid by prefixing it with `./', e.g. `./12345'.
760 If GDB has not been configured to included core file support, such
761 as for most embedded targets, then it will complain about a second
762 argument and ignore it.
764 Many options have both long and short forms; both are shown in the
765 following list. GDB also recognizes the long forms if you truncate
766 them, so long as enough of the option is present to be unambiguous.
767 (If you prefer, you can flag option arguments with `--' rather than
768 `-', though we illustrate the more usual convention.)
772 Read symbol table from file FILE.
776 Use file FILE as the executable file to execute when appropriate,
777 and for examining pure data in conjunction with a core dump.
780 Read symbol table from file FILE and use it as the executable file.
784 Use file FILE as a core dump to examine.
788 Connect to process ID NUMBER, as with the `attach' command.
792 Execute commands from file FILE. The contents of this file is
793 evaluated exactly as the `source' command would. *Note Command
794 files: Command Files.
796 `-eval-command COMMAND'
798 Execute a single GDB command.
800 This option may be used multiple times to call multiple commands.
801 It may also be interleaved with `-command' as required.
803 gdb -ex 'target sim' -ex 'load' \
804 -x setbreakpoints -ex 'run' a.out
806 `-directory DIRECTORY'
808 Add DIRECTORY to the path to search for source and script files.
812 Read each symbol file's entire symbol table immediately, rather
813 than the default, which is to read it incrementally as it is
814 needed. This makes startup slower, but makes future operations
819 File: gdb.info, Node: Mode Options, Next: Startup, Prev: File Options, Up: Invoking GDB
824 You can run GDB in various alternative modes--for example, in batch
829 Do not execute commands found in any initialization files.
830 Normally, GDB executes the commands in these files after all the
831 command options and arguments have been processed. *Note Command
832 Files: Command Files.
837 "Quiet". Do not print the introductory and copyright messages.
838 These messages are also suppressed in batch mode.
841 Run in batch mode. Exit with status `0' after processing all the
842 command files specified with `-x' (and all commands from
843 initialization files, if not inhibited with `-n'). Exit with
844 nonzero status if an error occurs in executing the GDB commands in
847 Batch mode may be useful for running GDB as a filter, for example
848 to download and run a program on another computer; in order to
849 make this more useful, the message
851 Program exited normally.
853 (which is ordinarily issued whenever a program running under GDB
854 control terminates) is not issued when running in batch mode.
857 Run in batch mode exactly like `-batch', but totally silently. All
858 GDB output to `stdout' is prevented (`stderr' is unaffected).
859 This is much quieter than `-silent' and would be useless for an
862 This is particularly useful when using targets that give `Loading
863 section' messages, for example.
865 Note that targets that give their output via GDB, as opposed to
866 writing directly to `stdout', will also be made silent.
868 `-return-child-result'
869 The return code from GDB will be the return code from the child
870 process (the process being debugged), with the following
873 * GDB exits abnormally. E.g., due to an incorrect argument or
874 an internal error. In this case the exit code is the same as
875 it would have been without `-return-child-result'.
877 * The user quits with an explicit value. E.g., `quit 1'.
879 * The child process never runs, or is not allowed to terminate,
880 in which case the exit code will be -1.
882 This option is useful in conjunction with `-batch' or
883 `-batch-silent', when GDB is being used as a remote program loader
884 or simulator interface.
888 "No windows". If GDB comes with a graphical user interface (GUI)
889 built in, then this option tells GDB to only use the command-line
890 interface. If no GUI is available, this option has no effect.
894 If GDB includes a GUI, then this option requires it to be used if
898 Run GDB using DIRECTORY as its working directory, instead of the
903 GNU Emacs sets this option when it runs GDB as a subprocess. It
904 tells GDB to output the full file name and line number in a
905 standard, recognizable fashion each time a stack frame is
906 displayed (which includes each time your program stops). This
907 recognizable format looks like two `\032' characters, followed by
908 the file name, line number and character position separated by
909 colons, and a newline. The Emacs-to-GDB interface program uses
910 the two `\032' characters as a signal to display the source code
914 The Epoch Emacs-GDB interface sets this option when it runs GDB as
915 a subprocess. It tells GDB to modify its print routines so as to
916 allow Epoch to display values of expressions in a separate window.
919 This option sets the "annotation level" inside GDB. Its effect is
920 identical to using `set annotate LEVEL' (*note Annotations::).
921 The annotation LEVEL controls how much information GDB prints
922 together with its prompt, values of expressions, source lines, and
923 other types of output. Level 0 is the normal, level 1 is for use
924 when GDB is run as a subprocess of GNU Emacs, level 3 is the
925 maximum annotation suitable for programs that control GDB, and
926 level 2 has been deprecated.
928 The annotation mechanism has largely been superseded by GDB/MI
932 Change interpretation of command line so that arguments following
933 the executable file are passed as command line arguments to the
934 inferior. This option stops option processing.
938 Set the line speed (baud rate or bits per second) of any serial
939 interface used by GDB for remote debugging.
942 Set the timeout (in seconds) of any communication used by GDB for
947 Run using DEVICE for your program's standard input and output.
950 Activate the "Text User Interface" when starting. The Text User
951 Interface manages several text windows on the terminal, showing
952 source, assembly, registers and GDB command outputs (*note GDB
953 Text User Interface: TUI.). Alternatively, the Text User
954 Interface can be enabled by invoking the program `gdbtui'. Do not
955 use this option if you run GDB from Emacs (*note Using GDB under
958 `-interpreter INTERP'
959 Use the interpreter INTERP for interface with the controlling
960 program or device. This option is meant to be set by programs
961 which communicate with GDB using it as a back end. *Note Command
962 Interpreters: Interpreters.
964 `--interpreter=mi' (or `--interpreter=mi2') causes GDB to use the
965 "GDB/MI interface" (*note The GDB/MI Interface: GDB/MI.) included
966 since GDB version 6.0. The previous GDB/MI interface, included in
967 GDB version 5.3 and selected with `--interpreter=mi1', is
968 deprecated. Earlier GDB/MI interfaces are no longer supported.
971 Open the executable and core files for both reading and writing.
972 This is equivalent to the `set write on' command inside GDB (*note
976 This option causes GDB to print statistics about time and memory
977 usage after it completes each command and returns to the prompt.
980 This option causes GDB to print its version number and no-warranty
985 File: gdb.info, Node: Startup, Prev: Mode Options, Up: Invoking GDB
987 2.1.3 What GDB Does During Startup
988 ----------------------------------
990 Here's the description of what GDB does during session startup:
992 1. Sets up the command interpreter as specified by the command line
993 (*note interpreter: Mode Options.).
995 2. Reads the system-wide "init file" (if `--with-system-gdbinit' was
996 used when building GDB; *note System-wide configuration and
997 settings: System-wide configuration.) and executes all the
998 commands in that file.
1000 3. Reads the init file (if any) in your home directory(1) and
1001 executes all the commands in that file.
1003 4. Processes command line options and operands.
1005 5. Reads and executes the commands from init file (if any) in the
1006 current working directory. This is only done if the current
1007 directory is different from your home directory. Thus, you can
1008 have more than one init file, one generic in your home directory,
1009 and another, specific to the program you are debugging, in the
1010 directory where you invoke GDB.
1012 6. Reads command files specified by the `-x' option. *Note Command
1013 Files::, for more details about GDB command files.
1015 7. Reads the command history recorded in the "history file". *Note
1016 Command History::, for more details about the command history and
1017 the files where GDB records it.
1019 Init files use the same syntax as "command files" (*note Command
1020 Files::) and are processed by GDB in the same way. The init file in
1021 your home directory can set options (such as `set complaints') that
1022 affect subsequent processing of command line options and operands.
1023 Init files are not executed if you use the `-nx' option (*note Choosing
1024 Modes: Mode Options.).
1026 To display the list of init files loaded by gdb at startup, you can
1029 The GDB init files are normally called `.gdbinit'. The DJGPP port
1030 of GDB uses the name `gdb.ini', due to the limitations of file names
1031 imposed by DOS filesystems. The Windows ports of GDB use the standard
1032 name, but if they find a `gdb.ini' file, they warn you about that and
1033 suggest to rename the file to the standard name.
1035 ---------- Footnotes ----------
1037 (1) On DOS/Windows systems, the home directory is the one pointed to
1038 by the `HOME' environment variable.
1041 File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation
1048 To exit GDB, use the `quit' command (abbreviated `q'), or type an
1049 end-of-file character (usually `Ctrl-d'). If you do not supply
1050 EXPRESSION, GDB will terminate normally; otherwise it will
1051 terminate using the result of EXPRESSION as the error code.
1053 An interrupt (often `Ctrl-c') does not exit from GDB, but rather
1054 terminates the action of any GDB command that is in progress and
1055 returns to GDB command level. It is safe to type the interrupt
1056 character at any time because GDB does not allow it to take effect
1057 until a time when it is safe.
1059 If you have been using GDB to control an attached process or device,
1060 you can release it with the `detach' command (*note Debugging an
1061 Already-running Process: Attach.).
1064 File: gdb.info, Node: Shell Commands, Next: Logging Output, Prev: Quitting GDB, Up: Invocation
1069 If you need to execute occasional shell commands during your debugging
1070 session, there is no need to leave or suspend GDB; you can just use the
1073 `shell COMMAND STRING'
1074 Invoke a standard shell to execute COMMAND STRING. If it exists,
1075 the environment variable `SHELL' determines which shell to run.
1076 Otherwise GDB uses the default shell (`/bin/sh' on Unix systems,
1077 `COMMAND.COM' on MS-DOS, etc.).
1079 The utility `make' is often needed in development environments. You
1080 do not have to use the `shell' command for this purpose in GDB:
1083 Execute the `make' program with the specified arguments. This is
1084 equivalent to `shell make MAKE-ARGS'.
1087 File: gdb.info, Node: Logging Output, Prev: Shell Commands, Up: Invocation
1092 You may want to save the output of GDB commands to a file. There are
1093 several commands to control GDB's logging.
1101 `set logging file FILE'
1102 Change the name of the current logfile. The default logfile is
1105 `set logging overwrite [on|off]'
1106 By default, GDB will append to the logfile. Set `overwrite' if
1107 you want `set logging on' to overwrite the logfile instead.
1109 `set logging redirect [on|off]'
1110 By default, GDB output will go to both the terminal and the
1111 logfile. Set `redirect' if you want output to go only to the log
1115 Show the current values of the logging settings.
1118 File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top
1123 You can abbreviate a GDB command to the first few letters of the command
1124 name, if that abbreviation is unambiguous; and you can repeat certain
1125 GDB commands by typing just <RET>. You can also use the <TAB> key to
1126 get GDB to fill out the rest of a word in a command (or to show you the
1127 alternatives available, if there is more than one possibility).
1131 * Command Syntax:: How to give commands to GDB
1132 * Completion:: Command completion
1133 * Help:: How to ask GDB for help
1136 File: gdb.info, Node: Command Syntax, Next: Completion, Up: Commands
1141 A GDB command is a single line of input. There is no limit on how long
1142 it can be. It starts with a command name, which is followed by
1143 arguments whose meaning depends on the command name. For example, the
1144 command `step' accepts an argument which is the number of times to
1145 step, as in `step 5'. You can also use the `step' command with no
1146 arguments. Some commands do not allow any arguments.
1148 GDB command names may always be truncated if that abbreviation is
1149 unambiguous. Other possible command abbreviations are listed in the
1150 documentation for individual commands. In some cases, even ambiguous
1151 abbreviations are allowed; for example, `s' is specially defined as
1152 equivalent to `step' even though there are other commands whose names
1153 start with `s'. You can test abbreviations by using them as arguments
1154 to the `help' command.
1156 A blank line as input to GDB (typing just <RET>) means to repeat the
1157 previous command. Certain commands (for example, `run') will not
1158 repeat this way; these are commands whose unintentional repetition
1159 might cause trouble and which you are unlikely to want to repeat.
1160 User-defined commands can disable this feature; see *note dont-repeat:
1163 The `list' and `x' commands, when you repeat them with <RET>,
1164 construct new arguments rather than repeating exactly as typed. This
1165 permits easy scanning of source or memory.
1167 GDB can also use <RET> in another way: to partition lengthy output,
1168 in a way similar to the common utility `more' (*note Screen Size:
1169 Screen Size.). Since it is easy to press one <RET> too many in this
1170 situation, GDB disables command repetition after any command that
1171 generates this sort of display.
1173 Any text from a `#' to the end of the line is a comment; it does
1174 nothing. This is useful mainly in command files (*note Command Files:
1177 The `Ctrl-o' binding is useful for repeating a complex sequence of
1178 commands. This command accepts the current line, like <RET>, and then
1179 fetches the next line relative to the current line from the history for
1183 File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands
1185 3.2 Command Completion
1186 ======================
1188 GDB can fill in the rest of a word in a command for you, if there is
1189 only one possibility; it can also show you what the valid possibilities
1190 are for the next word in a command, at any time. This works for GDB
1191 commands, GDB subcommands, and the names of symbols in your program.
1193 Press the <TAB> key whenever you want GDB to fill out the rest of a
1194 word. If there is only one possibility, GDB fills in the word, and
1195 waits for you to finish the command (or press <RET> to enter it). For
1196 example, if you type
1198 (gdb) info bre <TAB>
1200 GDB fills in the rest of the word `breakpoints', since that is the only
1201 `info' subcommand beginning with `bre':
1203 (gdb) info breakpoints
1205 You can either press <RET> at this point, to run the `info breakpoints'
1206 command, or backspace and enter something else, if `breakpoints' does
1207 not look like the command you expected. (If you were sure you wanted
1208 `info breakpoints' in the first place, you might as well just type
1209 <RET> immediately after `info bre', to exploit command abbreviations
1210 rather than command completion).
1212 If there is more than one possibility for the next word when you
1213 press <TAB>, GDB sounds a bell. You can either supply more characters
1214 and try again, or just press <TAB> a second time; GDB displays all the
1215 possible completions for that word. For example, you might want to set
1216 a breakpoint on a subroutine whose name begins with `make_', but when
1217 you type `b make_<TAB>' GDB just sounds the bell. Typing <TAB> again
1218 displays all the function names in your program that begin with those
1219 characters, for example:
1222 GDB sounds bell; press <TAB> again, to see:
1223 make_a_section_from_file make_environ
1224 make_abs_section make_function_type
1225 make_blockvector make_pointer_type
1226 make_cleanup make_reference_type
1227 make_command make_symbol_completion_list
1230 After displaying the available possibilities, GDB copies your partial
1231 input (`b make_' in the example) so you can finish the command.
1233 If you just want to see the list of alternatives in the first place,
1234 you can press `M-?' rather than pressing <TAB> twice. `M-?' means
1235 `<META> ?'. You can type this either by holding down a key designated
1236 as the <META> shift on your keyboard (if there is one) while typing
1237 `?', or as <ESC> followed by `?'.
1239 Sometimes the string you need, while logically a "word", may contain
1240 parentheses or other characters that GDB normally excludes from its
1241 notion of a word. To permit word completion to work in this situation,
1242 you may enclose words in `'' (single quote marks) in GDB commands.
1244 The most likely situation where you might need this is in typing the
1245 name of a C++ function. This is because C++ allows function
1246 overloading (multiple definitions of the same function, distinguished
1247 by argument type). For example, when you want to set a breakpoint you
1248 may need to distinguish whether you mean the version of `name' that
1249 takes an `int' parameter, `name(int)', or the version that takes a
1250 `float' parameter, `name(float)'. To use the word-completion
1251 facilities in this situation, type a single quote `'' at the beginning
1252 of the function name. This alerts GDB that it may need to consider
1253 more information than usual when you press <TAB> or `M-?' to request
1256 (gdb) b 'bubble( M-?
1257 bubble(double,double) bubble(int,int)
1260 In some cases, GDB can tell that completing a name requires using
1261 quotes. When this happens, GDB inserts the quote for you (while
1262 completing as much as it can) if you do not type the quote in the first
1266 GDB alters your input line to the following, and rings a bell:
1269 In general, GDB can tell that a quote is needed (and inserts it) if you
1270 have not yet started typing the argument list when you ask for
1271 completion on an overloaded symbol.
1273 For more information about overloaded functions, see *note C++
1274 Expressions: C Plus Plus Expressions. You can use the command `set
1275 overload-resolution off' to disable overload resolution; see *note GDB
1276 Features for C++: Debugging C Plus Plus.
1278 When completing in an expression which looks up a field in a
1279 structure, GDB also tries(1) to limit completions to the field names
1280 available in the type of the left-hand-side:
1282 (gdb) p gdb_stdout.M-?
1283 magic to_delete to_fputs to_put to_rewind
1284 to_data to_flush to_isatty to_read to_write
1286 This is because the `gdb_stdout' is a variable of the type `struct
1287 ui_file' that is defined in GDB sources as follows:
1292 ui_file_flush_ftype *to_flush;
1293 ui_file_write_ftype *to_write;
1294 ui_file_fputs_ftype *to_fputs;
1295 ui_file_read_ftype *to_read;
1296 ui_file_delete_ftype *to_delete;
1297 ui_file_isatty_ftype *to_isatty;
1298 ui_file_rewind_ftype *to_rewind;
1299 ui_file_put_ftype *to_put;
1303 ---------- Footnotes ----------
1305 (1) The completer can be confused by certain kinds of invalid
1306 expressions. Also, it only examines the static type of the expression,
1307 not the dynamic type.
1310 File: gdb.info, Node: Help, Prev: Completion, Up: Commands
1315 You can always ask GDB itself for information on its commands, using
1320 You can use `help' (abbreviated `h') with no arguments to display
1321 a short list of named classes of commands:
1324 List of classes of commands:
1326 aliases -- Aliases of other commands
1327 breakpoints -- Making program stop at certain points
1328 data -- Examining data
1329 files -- Specifying and examining files
1330 internals -- Maintenance commands
1331 obscure -- Obscure features
1332 running -- Running the program
1333 stack -- Examining the stack
1334 status -- Status inquiries
1335 support -- Support facilities
1336 tracepoints -- Tracing of program execution without
1337 stopping the program
1338 user-defined -- User-defined commands
1340 Type "help" followed by a class name for a list of
1341 commands in that class.
1342 Type "help" followed by command name for full
1344 Command name abbreviations are allowed if unambiguous.
1348 Using one of the general help classes as an argument, you can get a
1349 list of the individual commands in that class. For example, here
1350 is the help display for the class `status':
1357 info -- Generic command for showing things
1358 about the program being debugged
1359 show -- Generic command for showing things
1362 Type "help" followed by command name for full
1364 Command name abbreviations are allowed if unambiguous.
1368 With a command name as `help' argument, GDB displays a short
1369 paragraph on how to use that command.
1372 The `apropos' command searches through all of the GDB commands,
1373 and their documentation, for the regular expression specified in
1374 ARGS. It prints out all matches found. For example:
1380 set symbol-reloading -- Set dynamic symbol table reloading
1381 multiple times in one run
1382 show symbol-reloading -- Show dynamic symbol table reloading
1383 multiple times in one run
1386 The `complete ARGS' command lists all the possible completions for
1387 the beginning of a command. Use ARGS to specify the beginning of
1388 the command you want completed. For example:
1399 This is intended for use by GNU Emacs.
1401 In addition to `help', you can use the GDB commands `info' and
1402 `show' to inquire about the state of your program, or the state of GDB
1403 itself. Each command supports many topics of inquiry; this manual
1404 introduces each of them in the appropriate context. The listings under
1405 `info' and under `show' in the Index point to all the sub-commands.
1409 This command (abbreviated `i') is for describing the state of your
1410 program. For example, you can show the arguments passed to a
1411 function with `info args', list the registers currently in use
1412 with `info registers', or list the breakpoints you have set with
1413 `info breakpoints'. You can get a complete list of the `info'
1414 sub-commands with `help info'.
1417 You can assign the result of an expression to an environment
1418 variable with `set'. For example, you can set the GDB prompt to a
1419 $-sign with `set prompt $'.
1422 In contrast to `info', `show' is for describing the state of GDB
1423 itself. You can change most of the things you can `show', by
1424 using the related command `set'; for example, you can control what
1425 number system is used for displays with `set radix', or simply
1426 inquire which is currently in use with `show radix'.
1428 To display all the settable parameters and their current values,
1429 you can use `show' with no arguments; you may also use `info set'.
1430 Both commands produce the same display.
1432 Here are three miscellaneous `show' subcommands, all of which are
1433 exceptional in lacking corresponding `set' commands:
1436 Show what version of GDB is running. You should include this
1437 information in GDB bug-reports. If multiple versions of GDB are
1438 in use at your site, you may need to determine which version of
1439 GDB you are running; as GDB evolves, new commands are introduced,
1440 and old ones may wither away. Also, many system vendors ship
1441 variant versions of GDB, and there are variant versions of GDB in
1442 GNU/Linux distributions as well. The version number is the same
1443 as the one announced when you start GDB.
1447 Display information about permission for copying GDB.
1451 Display the GNU "NO WARRANTY" statement, or a warranty, if your
1452 version of GDB comes with one.
1456 File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top
1458 4 Running Programs Under GDB
1459 ****************************
1461 When you run a program under GDB, you must first generate debugging
1462 information when you compile it.
1464 You may start GDB with its arguments, if any, in an environment of
1465 your choice. If you are doing native debugging, you may redirect your
1466 program's input and output, debug an already running process, or kill a
1471 * Compilation:: Compiling for debugging
1472 * Starting:: Starting your program
1473 * Arguments:: Your program's arguments
1474 * Environment:: Your program's environment
1476 * Working Directory:: Your program's working directory
1477 * Input/Output:: Your program's input and output
1478 * Attach:: Debugging an already-running process
1479 * Kill Process:: Killing the child process
1481 * Inferiors and Programs:: Debugging multiple inferiors and programs
1482 * Threads:: Debugging programs with multiple threads
1483 * Forks:: Debugging forks
1484 * Checkpoint/Restart:: Setting a _bookmark_ to return to later
1487 File: gdb.info, Node: Compilation, Next: Starting, Up: Running
1489 4.1 Compiling for Debugging
1490 ===========================
1492 In order to debug a program effectively, you need to generate debugging
1493 information when you compile it. This debugging information is stored
1494 in the object file; it describes the data type of each variable or
1495 function and the correspondence between source line numbers and
1496 addresses in the executable code.
1498 To request debugging information, specify the `-g' option when you
1501 Programs that are to be shipped to your customers are compiled with
1502 optimizations, using the `-O' compiler option. However, some compilers
1503 are unable to handle the `-g' and `-O' options together. Using those
1504 compilers, you cannot generate optimized executables containing
1505 debugging information.
1507 GCC, the GNU C/C++ compiler, supports `-g' with or without `-O',
1508 making it possible to debug optimized code. We recommend that you
1509 _always_ use `-g' whenever you compile a program. You may think your
1510 program is correct, but there is no sense in pushing your luck. For
1511 more information, see *note Optimized Code::.
1513 Older versions of the GNU C compiler permitted a variant option
1514 `-gg' for debugging information. GDB no longer supports this format;
1515 if your GNU C compiler has this option, do not use it.
1517 GDB knows about preprocessor macros and can show you their expansion
1518 (*note Macros::). Most compilers do not include information about
1519 preprocessor macros in the debugging information if you specify the
1520 `-g' flag alone, because this information is rather large. Version 3.1
1521 and later of GCC, the GNU C compiler, provides macro information if you
1522 specify the options `-gdwarf-2' and `-g3'; the former option requests
1523 debugging information in the Dwarf 2 format, and the latter requests
1524 "extra information". In the future, we hope to find more compact ways
1525 to represent macro information, so that it can be included with `-g'
1529 File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running
1531 4.2 Starting your Program
1532 =========================
1536 Use the `run' command to start your program under GDB. You must
1537 first specify the program name (except on VxWorks) with an
1538 argument to GDB (*note Getting In and Out of GDB: Invocation.), or
1539 by using the `file' or `exec-file' command (*note Commands to
1540 Specify Files: Files.).
1543 If you are running your program in an execution environment that
1544 supports processes, `run' creates an inferior process and makes that
1545 process run your program. In some environments without processes,
1546 `run' jumps to the start of your program. Other targets, like
1547 `remote', are always running. If you get an error message like this
1550 The "remote" target does not support "run".
1551 Try "help target" or "continue".
1553 then use `continue' to run your program. You may need `load' first
1556 The execution of a program is affected by certain information it
1557 receives from its superior. GDB provides ways to specify this
1558 information, which you must do _before_ starting your program. (You
1559 can change it after starting your program, but such changes only affect
1560 your program the next time you start it.) This information may be
1561 divided into four categories:
1564 Specify the arguments to give your program as the arguments of the
1565 `run' command. If a shell is available on your target, the shell
1566 is used to pass the arguments, so that you may use normal
1567 conventions (such as wildcard expansion or variable substitution)
1568 in describing the arguments. In Unix systems, you can control
1569 which shell is used with the `SHELL' environment variable. *Note
1570 Your Program's Arguments: Arguments.
1573 Your program normally inherits its environment from GDB, but you
1574 can use the GDB commands `set environment' and `unset environment'
1575 to change parts of the environment that affect your program.
1576 *Note Your Program's Environment: Environment.
1578 The _working directory._
1579 Your program inherits its working directory from GDB. You can set
1580 the GDB working directory with the `cd' command in GDB. *Note
1581 Your Program's Working Directory: Working Directory.
1583 The _standard input and output._
1584 Your program normally uses the same device for standard input and
1585 standard output as GDB is using. You can redirect input and output
1586 in the `run' command line, or you can use the `tty' command to set
1587 a different device for your program. *Note Your Program's Input
1588 and Output: Input/Output.
1590 _Warning:_ While input and output redirection work, you cannot use
1591 pipes to pass the output of the program you are debugging to
1592 another program; if you attempt this, GDB is likely to wind up
1593 debugging the wrong program.
1595 When you issue the `run' command, your program begins to execute
1596 immediately. *Note Stopping and Continuing: Stopping, for discussion
1597 of how to arrange for your program to stop. Once your program has
1598 stopped, you may call functions in your program, using the `print' or
1599 `call' commands. *Note Examining Data: Data.
1601 If the modification time of your symbol file has changed since the
1602 last time GDB read its symbols, GDB discards its symbol table, and
1603 reads it again. When it does this, GDB tries to retain your current
1607 The name of the main procedure can vary from language to language.
1608 With C or C++, the main procedure name is always `main', but other
1609 languages such as Ada do not require a specific name for their
1610 main procedure. The debugger provides a convenient way to start
1611 the execution of the program and to stop at the beginning of the
1612 main procedure, depending on the language used.
1614 The `start' command does the equivalent of setting a temporary
1615 breakpoint at the beginning of the main procedure and then invoking
1618 Some programs contain an "elaboration" phase where some startup
1619 code is executed before the main procedure is called. This
1620 depends on the languages used to write your program. In C++, for
1621 instance, constructors for static and global objects are executed
1622 before `main' is called. It is therefore possible that the
1623 debugger stops before reaching the main procedure. However, the
1624 temporary breakpoint will remain to halt execution.
1626 Specify the arguments to give to your program as arguments to the
1627 `start' command. These arguments will be given verbatim to the
1628 underlying `run' command. Note that the same arguments will be
1629 reused if no argument is provided during subsequent calls to
1632 It is sometimes necessary to debug the program during elaboration.
1633 In these cases, using the `start' command would stop the execution
1634 of your program too late, as the program would have already
1635 completed the elaboration phase. Under these circumstances,
1636 insert breakpoints in your elaboration code before running your
1639 `set exec-wrapper WRAPPER'
1641 `unset exec-wrapper'
1642 When `exec-wrapper' is set, the specified wrapper is used to
1643 launch programs for debugging. GDB starts your program with a
1644 shell command of the form `exec WRAPPER PROGRAM'. Quoting is
1645 added to PROGRAM and its arguments, but not to WRAPPER, so you
1646 should add quotes if appropriate for your shell. The wrapper runs
1647 until it executes your program, and then GDB takes control.
1649 You can use any program that eventually calls `execve' with its
1650 arguments as a wrapper. Several standard Unix utilities do this,
1651 e.g. `env' and `nohup'. Any Unix shell script ending with `exec
1652 "$@"' will also work.
1654 For example, you can use `env' to pass an environment variable to
1655 the debugged program, without setting the variable in your shell's
1658 (gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so'
1661 This command is available when debugging locally on most targets,
1662 excluding DJGPP, Cygwin, MS Windows, and QNX Neutrino.
1664 `set disable-randomization'
1665 `set disable-randomization on'
1666 This option (enabled by default in GDB) will turn off the native
1667 randomization of the virtual address space of the started program.
1668 This option is useful for multiple debugging sessions to make the
1669 execution better reproducible and memory addresses reusable across
1672 This feature is implemented only on GNU/Linux. You can get the
1675 (gdb) set exec-wrapper setarch `uname -m` -R
1677 `set disable-randomization off'
1678 Leave the behavior of the started executable unchanged. Some bugs
1679 rear their ugly heads only when the program is loaded at certain
1680 addresses. If your bug disappears when you run the program under
1681 GDB, that might be because GDB by default disables the address
1682 randomization on platforms, such as GNU/Linux, which do that for
1683 stand-alone programs. Use `set disable-randomization off' to try
1684 to reproduce such elusive bugs.
1686 The virtual address space randomization is implemented only on
1687 GNU/Linux. It protects the programs against some kinds of
1688 security attacks. In these cases the attacker needs to know the
1689 exact location of a concrete executable code. Randomizing its
1690 location makes it impossible to inject jumps misusing a code at
1691 its expected addresses.
1693 Prelinking shared libraries provides a startup performance
1694 advantage but it makes addresses in these libraries predictable
1695 for privileged processes by having just unprivileged access at the
1696 target system. Reading the shared library binary gives enough
1697 information for assembling the malicious code misusing it. Still
1698 even a prelinked shared library can get loaded at a new random
1699 address just requiring the regular relocation process during the
1700 startup. Shared libraries not already prelinked are always loaded
1701 at a randomly chosen address.
1703 Position independent executables (PIE) contain position
1704 independent code similar to the shared libraries and therefore
1705 such executables get loaded at a randomly chosen address upon
1706 startup. PIE executables always load even already prelinked
1707 shared libraries at a random address. You can build such
1708 executable using `gcc -fPIE -pie'.
1710 Heap (malloc storage), stack and custom mmap areas are always
1711 placed randomly (as long as the randomization is enabled).
1713 `show disable-randomization'
1714 Show the current setting of the explicit disable of the native
1715 randomization of the virtual address space of the started program.
1719 File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running
1721 4.3 Your Program's Arguments
1722 ============================
1724 The arguments to your program can be specified by the arguments of the
1725 `run' command. They are passed to a shell, which expands wildcard
1726 characters and performs redirection of I/O, and thence to your program.
1727 Your `SHELL' environment variable (if it exists) specifies what shell
1728 GDB uses. If you do not define `SHELL', GDB uses the default shell
1729 (`/bin/sh' on Unix).
1731 On non-Unix systems, the program is usually invoked directly by GDB,
1732 which emulates I/O redirection via the appropriate system calls, and
1733 the wildcard characters are expanded by the startup code of the
1734 program, not by the shell.
1736 `run' with no arguments uses the same arguments used by the previous
1737 `run', or those set by the `set args' command.
1740 Specify the arguments to be used the next time your program is
1741 run. If `set args' has no arguments, `run' executes your program
1742 with no arguments. Once you have run your program with arguments,
1743 using `set args' before the next `run' is the only way to run it
1744 again without arguments.
1747 Show the arguments to give your program when it is started.
1750 File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running
1752 4.4 Your Program's Environment
1753 ==============================
1755 The "environment" consists of a set of environment variables and their
1756 values. Environment variables conventionally record such things as
1757 your user name, your home directory, your terminal type, and your search
1758 path for programs to run. Usually you set up environment variables with
1759 the shell and they are inherited by all the other programs you run.
1760 When debugging, it can be useful to try running your program with a
1761 modified environment without having to start GDB over again.
1764 Add DIRECTORY to the front of the `PATH' environment variable (the
1765 search path for executables) that will be passed to your program.
1766 The value of `PATH' used by GDB does not change. You may specify
1767 several directory names, separated by whitespace or by a
1768 system-dependent separator character (`:' on Unix, `;' on MS-DOS
1769 and MS-Windows). If DIRECTORY is already in the path, it is moved
1770 to the front, so it is searched sooner.
1772 You can use the string `$cwd' to refer to whatever is the current
1773 working directory at the time GDB searches the path. If you use
1774 `.' instead, it refers to the directory where you executed the
1775 `path' command. GDB replaces `.' in the DIRECTORY argument (with
1776 the current path) before adding DIRECTORY to the search path.
1779 Display the list of search paths for executables (the `PATH'
1780 environment variable).
1782 `show environment [VARNAME]'
1783 Print the value of environment variable VARNAME to be given to
1784 your program when it starts. If you do not supply VARNAME, print
1785 the names and values of all environment variables to be given to
1786 your program. You can abbreviate `environment' as `env'.
1788 `set environment VARNAME [=VALUE]'
1789 Set environment variable VARNAME to VALUE. The value changes for
1790 your program only, not for GDB itself. VALUE may be any string;
1791 the values of environment variables are just strings, and any
1792 interpretation is supplied by your program itself. The VALUE
1793 parameter is optional; if it is eliminated, the variable is set to
1796 For example, this command:
1800 tells the debugged program, when subsequently run, that its user
1801 is named `foo'. (The spaces around `=' are used for clarity here;
1802 they are not actually required.)
1804 `unset environment VARNAME'
1805 Remove variable VARNAME from the environment to be passed to your
1806 program. This is different from `set env VARNAME ='; `unset
1807 environment' removes the variable from the environment, rather
1808 than assigning it an empty value.
1810 _Warning:_ On Unix systems, GDB runs your program using the shell
1811 indicated by your `SHELL' environment variable if it exists (or
1812 `/bin/sh' if not). If your `SHELL' variable names a shell that runs an
1813 initialization file--such as `.cshrc' for C-shell, or `.bashrc' for
1814 BASH--any variables you set in that file affect your program. You may
1815 wish to move setting of environment variables to files that are only
1816 run when you sign on, such as `.login' or `.profile'.
1819 File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running
1821 4.5 Your Program's Working Directory
1822 ====================================
1824 Each time you start your program with `run', it inherits its working
1825 directory from the current working directory of GDB. The GDB working
1826 directory is initially whatever it inherited from its parent process
1827 (typically the shell), but you can specify a new working directory in
1828 GDB with the `cd' command.
1830 The GDB working directory also serves as a default for the commands
1831 that specify files for GDB to operate on. *Note Commands to Specify
1835 Set the GDB working directory to DIRECTORY.
1838 Print the GDB working directory.
1840 It is generally impossible to find the current working directory of
1841 the process being debugged (since a program can change its directory
1842 during its run). If you work on a system where GDB is configured with
1843 the `/proc' support, you can use the `info proc' command (*note SVR4
1844 Process Information::) to find out the current working directory of the
1848 File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running
1850 4.6 Your Program's Input and Output
1851 ===================================
1853 By default, the program you run under GDB does input and output to the
1854 same terminal that GDB uses. GDB switches the terminal to its own
1855 terminal modes to interact with you, but it records the terminal modes
1856 your program was using and switches back to them when you continue
1857 running your program.
1860 Displays information recorded by GDB about the terminal modes your
1863 You can redirect your program's input and/or output using shell
1864 redirection with the `run' command. For example,
1868 starts your program, diverting its output to the file `outfile'.
1870 Another way to specify where your program should do input and output
1871 is with the `tty' command. This command accepts a file name as
1872 argument, and causes this file to be the default for future `run'
1873 commands. It also resets the controlling terminal for the child
1874 process, for future `run' commands. For example,
1878 directs that processes started with subsequent `run' commands default
1879 to do input and output on the terminal `/dev/ttyb' and have that as
1880 their controlling terminal.
1882 An explicit redirection in `run' overrides the `tty' command's
1883 effect on the input/output device, but not its effect on the controlling
1886 When you use the `tty' command or redirect input in the `run'
1887 command, only the input _for your program_ is affected. The input for
1888 GDB still comes from your terminal. `tty' is an alias for `set
1891 You can use the `show inferior-tty' command to tell GDB to display
1892 the name of the terminal that will be used for future runs of your
1895 `set inferior-tty /dev/ttyb'
1896 Set the tty for the program being debugged to /dev/ttyb.
1899 Show the current tty for the program being debugged.
1902 File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running
1904 4.7 Debugging an Already-running Process
1905 ========================================
1908 This command attaches to a running process--one that was started
1909 outside GDB. (`info files' shows your active targets.) The
1910 command takes as argument a process ID. The usual way to find out
1911 the PROCESS-ID of a Unix process is with the `ps' utility, or with
1912 the `jobs -l' shell command.
1914 `attach' does not repeat if you press <RET> a second time after
1915 executing the command.
1917 To use `attach', your program must be running in an environment
1918 which supports processes; for example, `attach' does not work for
1919 programs on bare-board targets that lack an operating system. You must
1920 also have permission to send the process a signal.
1922 When you use `attach', the debugger finds the program running in the
1923 process first by looking in the current working directory, then (if the
1924 program is not found) by using the source file search path (*note
1925 Specifying Source Directories: Source Path.). You can also use the
1926 `file' command to load the program. *Note Commands to Specify Files:
1929 The first thing GDB does after arranging to debug the specified
1930 process is to stop it. You can examine and modify an attached process
1931 with all the GDB commands that are ordinarily available when you start
1932 processes with `run'. You can insert breakpoints; you can step and
1933 continue; you can modify storage. If you would rather the process
1934 continue running, you may use the `continue' command after attaching
1938 When you have finished debugging the attached process, you can use
1939 the `detach' command to release it from GDB control. Detaching
1940 the process continues its execution. After the `detach' command,
1941 that process and GDB become completely independent once more, and
1942 you are ready to `attach' another process or start one with `run'.
1943 `detach' does not repeat if you press <RET> again after executing
1946 If you exit GDB while you have an attached process, you detach that
1947 process. If you use the `run' command, you kill that process. By
1948 default, GDB asks for confirmation if you try to do either of these
1949 things; you can control whether or not you need to confirm by using the
1950 `set confirm' command (*note Optional Warnings and Messages:
1951 Messages/Warnings.).
1954 File: gdb.info, Node: Kill Process, Next: Inferiors and Programs, Prev: Attach, Up: Running
1956 4.8 Killing the Child Process
1957 =============================
1960 Kill the child process in which your program is running under GDB.
1962 This command is useful if you wish to debug a core dump instead of a
1963 running process. GDB ignores any core dump file while your program is
1966 On some operating systems, a program cannot be executed outside GDB
1967 while you have breakpoints set on it inside GDB. You can use the
1968 `kill' command in this situation to permit running your program outside
1971 The `kill' command is also useful if you wish to recompile and
1972 relink your program, since on many systems it is impossible to modify an
1973 executable file while it is running in a process. In this case, when
1974 you next type `run', GDB notices that the file has changed, and reads
1975 the symbol table again (while trying to preserve your current
1976 breakpoint settings).
1979 File: gdb.info, Node: Inferiors and Programs, Next: Threads, Prev: Kill Process, Up: Running
1981 4.9 Debugging Multiple Inferiors and Programs
1982 =============================================
1984 GDB lets you run and debug multiple programs in a single session. In
1985 addition, GDB on some systems may let you run several programs
1986 simultaneously (otherwise you have to exit from one before starting
1987 another). In the most general case, you can have multiple threads of
1988 execution in each of multiple processes, launched from multiple
1991 GDB represents the state of each program execution with an object
1992 called an "inferior". An inferior typically corresponds to a process,
1993 but is more general and applies also to targets that do not have
1994 processes. Inferiors may be created before a process runs, and may be
1995 retained after a process exits. Inferiors have unique identifiers that
1996 are different from process ids. Usually each inferior will also have
1997 its own distinct address space, although some embedded targets may have
1998 several inferiors running in different parts of a single address space.
1999 Each inferior may in turn have multiple threads running in it.
2001 To find out what inferiors exist at any moment, use `info inferiors':
2004 Print a list of all inferiors currently being managed by GDB.
2006 GDB displays for each inferior (in this order):
2008 1. the inferior number assigned by GDB
2010 2. the target system's inferior identifier
2012 3. the name of the executable the inferior is running.
2015 An asterisk `*' preceding the GDB inferior number indicates the
2020 (gdb) info inferiors
2021 Num Description Executable
2022 2 process 2307 hello
2023 * 1 process 3401 goodbye
2025 To switch focus between inferiors, use the `inferior' command:
2028 Make inferior number INFNO the current inferior. The argument
2029 INFNO is the inferior number assigned by GDB, as shown in the
2030 first field of the `info inferiors' display.
2032 You can get multiple executables into a debugging session via the
2033 `add-inferior' and `clone-inferior' commands. On some systems GDB can
2034 add inferiors to the debug session automatically by following calls to
2035 `fork' and `exec'. To remove inferiors from the debugging session use
2036 the `remove-inferior' command.
2038 `add-inferior [ -copies N ] [ -exec EXECUTABLE ]'
2039 Adds N inferiors to be run using EXECUTABLE as the executable. N
2040 defaults to 1. If no executable is specified, the inferiors
2041 begins empty, with no program. You can still assign or change the
2042 program assigned to the inferior at any time by using the `file'
2043 command with the executable name as its argument.
2045 `clone-inferior [ -copies N ] [ INFNO ]'
2046 Adds N inferiors ready to execute the same program as inferior
2047 INFNO. N defaults to 1. INFNO defaults to the number of the
2048 current inferior. This is a convenient command when you want to
2049 run another instance of the inferior you are debugging.
2051 (gdb) info inferiors
2052 Num Description Executable
2053 * 1 process 29964 helloworld
2054 (gdb) clone-inferior
2057 (gdb) info inferiors
2058 Num Description Executable
2060 * 1 process 29964 helloworld
2062 You can now simply switch focus to inferior 2 and run it.
2064 `remove-inferior INFNO'
2065 Removes the inferior INFNO. It is not possible to remove an
2066 inferior that is running with this command. For those, use the
2067 `kill' or `detach' command first.
2070 To quit debugging one of the running inferiors that is not the
2071 current inferior, you can either detach from it by using the
2072 `detach inferior' command (allowing it to run independently), or kill it
2073 using the `kill inferior' command:
2075 `detach inferior INFNO'
2076 Detach from the inferior identified by GDB inferior number INFNO,
2077 and remove it from the inferior list.
2079 `kill inferior INFNO'
2080 Kill the inferior identified by GDB inferior number INFNO, and
2081 remove it from the inferior list.
2083 After the successful completion of a command such as `detach',
2084 `detach inferior', `kill' or `kill inferior', or after a normal process
2085 exit, the inferior is still valid and listed with `info inferiors',
2086 ready to be restarted.
2088 To be notified when inferiors are started or exit under GDB's
2089 control use `set print inferior-events':
2091 `set print inferior-events'
2092 `set print inferior-events on'
2093 `set print inferior-events off'
2094 The `set print inferior-events' command allows you to enable or
2095 disable printing of messages when GDB notices that new inferiors
2096 have started or that inferiors have exited or have been detached.
2097 By default, these messages will not be printed.
2099 `show print inferior-events'
2100 Show whether messages will be printed when GDB detects that
2101 inferiors have started, exited or have been detached.
2103 Many commands will work the same with multiple programs as with a
2104 single program: e.g., `print myglobal' will simply display the value of
2105 `myglobal' in the current inferior.
2107 Occasionaly, when debugging GDB itself, it may be useful to get more
2108 info about the relationship of inferiors, programs, address spaces in a
2109 debug session. You can do that with the `maint info program-spaces'
2112 `maint info program-spaces'
2113 Print a list of all program spaces currently being managed by GDB.
2115 GDB displays for each program space (in this order):
2117 1. the program space number assigned by GDB
2119 2. the name of the executable loaded into the program space,
2120 with e.g., the `file' command.
2123 An asterisk `*' preceding the GDB program space number indicates
2124 the current program space.
2126 In addition, below each program space line, GDB prints extra
2127 information that isn't suitable to display in tabular form. For
2128 example, the list of inferiors bound to the program space.
2130 (gdb) maint info program-spaces
2133 Bound inferiors: ID 1 (process 21561)
2136 Here we can see that no inferior is running the program `hello',
2137 while `process 21561' is running the program `goodbye'. On some
2138 targets, it is possible that multiple inferiors are bound to the
2139 same program space. The most common example is that of debugging
2140 both the parent and child processes of a `vfork' call. For
2143 (gdb) maint info program-spaces
2146 Bound inferiors: ID 2 (process 18050), ID 1 (process 18045)
2148 Here, both inferior 2 and inferior 1 are running in the same
2149 program space as a result of inferior 1 having executed a `vfork'
2153 File: gdb.info, Node: Threads, Next: Forks, Prev: Inferiors and Programs, Up: Running
2155 4.10 Debugging Programs with Multiple Threads
2156 =============================================
2158 In some operating systems, such as HP-UX and Solaris, a single program
2159 may have more than one "thread" of execution. The precise semantics of
2160 threads differ from one operating system to another, but in general the
2161 threads of a single program are akin to multiple processes--except that
2162 they share one address space (that is, they can all examine and modify
2163 the same variables). On the other hand, each thread has its own
2164 registers and execution stack, and perhaps private memory.
2166 GDB provides these facilities for debugging multi-thread programs:
2168 * automatic notification of new threads
2170 * `thread THREADNO', a command to switch among threads
2172 * `info threads', a command to inquire about existing threads
2174 * `thread apply [THREADNO] [ALL] ARGS', a command to apply a command
2175 to a list of threads
2177 * thread-specific breakpoints
2179 * `set print thread-events', which controls printing of messages on
2180 thread start and exit.
2182 * `set libthread-db-search-path PATH', which lets the user specify
2183 which `libthread_db' to use if the default choice isn't compatible
2186 _Warning:_ These facilities are not yet available on every GDB
2187 configuration where the operating system supports threads. If
2188 your GDB does not support threads, these commands have no effect.
2189 For example, a system without thread support shows no output from
2190 `info threads', and always rejects the `thread' command, like this:
2194 Thread ID 1 not known. Use the "info threads" command to
2195 see the IDs of currently known threads.
2197 The GDB thread debugging facility allows you to observe all threads
2198 while your program runs--but whenever GDB takes control, one thread in
2199 particular is always the focus of debugging. This thread is called the
2200 "current thread". Debugging commands show program information from the
2201 perspective of the current thread.
2203 Whenever GDB detects a new thread in your program, it displays the
2204 target system's identification for the thread with a message in the
2205 form `[New SYSTAG]'. SYSTAG is a thread identifier whose form varies
2206 depending on the particular system. For example, on GNU/Linux, you
2209 [New Thread 46912507313328 (LWP 25582)]
2211 when GDB notices a new thread. In contrast, on an SGI system, the
2212 SYSTAG is simply something like `process 368', with no further
2215 For debugging purposes, GDB associates its own thread number--always
2216 a single integer--with each thread in your program.
2219 Display a summary of all threads currently in your program. GDB
2220 displays for each thread (in this order):
2222 1. the thread number assigned by GDB
2224 2. the target system's thread identifier (SYSTAG)
2226 3. the current stack frame summary for that thread
2228 An asterisk `*' to the left of the GDB thread number indicates the
2234 3 process 35 thread 27 0x34e5 in sigpause ()
2235 2 process 35 thread 23 0x34e5 in sigpause ()
2236 * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
2241 For debugging purposes, GDB associates its own thread number--a
2242 small integer assigned in thread-creation order--with each thread in
2245 Whenever GDB detects a new thread in your program, it displays both
2246 GDB's thread number and the target system's identification for the
2247 thread with a message in the form `[New SYSTAG]'. SYSTAG is a thread
2248 identifier whose form varies depending on the particular system. For
2249 example, on HP-UX, you see
2251 [New thread 2 (system thread 26594)]
2253 when GDB notices a new thread.
2256 Display a summary of all threads currently in your program. GDB
2257 displays for each thread (in this order):
2259 1. the thread number assigned by GDB
2261 2. the target system's thread identifier (SYSTAG)
2263 3. the current stack frame summary for that thread
2265 An asterisk `*' to the left of the GDB thread number indicates the
2271 * 3 system thread 26607 worker (wptr=0x7b09c318 "@") \
2274 2 system thread 26606 0x7b0030d8 in __ksleep () \
2276 from /usr/lib/libc.2
2277 1 system thread 27905 0x7b003498 in _brk () \
2279 from /usr/lib/libc.2
2281 On Solaris, you can display more information about user threads with
2282 a Solaris-specific command:
2284 `maint info sol-threads'
2285 Display info on Solaris user threads.
2288 Make thread number THREADNO the current thread. The command
2289 argument THREADNO is the internal GDB thread number, as shown in
2290 the first field of the `info threads' display. GDB responds by
2291 displaying the system identifier of the thread you selected, and
2292 its current stack frame summary:
2295 [Switching to process 35 thread 23]
2296 0x34e5 in sigpause ()
2298 As with the `[New ...]' message, the form of the text after
2299 `Switching to' depends on your system's conventions for identifying
2302 `thread apply [THREADNO] [ALL] COMMAND'
2303 The `thread apply' command allows you to apply the named COMMAND
2304 to one or more threads. Specify the numbers of the threads that
2305 you want affected with the command argument THREADNO. It can be a
2306 single thread number, one of the numbers shown in the first field
2307 of the `info threads' display; or it could be a range of thread
2308 numbers, as in `2-4'. To apply a command to all threads, type
2309 `thread apply all COMMAND'.
2311 `set print thread-events'
2312 `set print thread-events on'
2313 `set print thread-events off'
2314 The `set print thread-events' command allows you to enable or
2315 disable printing of messages when GDB notices that new threads have
2316 started or that threads have exited. By default, these messages
2317 will be printed if detection of these events is supported by the
2318 target. Note that these messages cannot be disabled on all
2321 `show print thread-events'
2322 Show whether messages will be printed when GDB detects that threads
2323 have started and exited.
2325 *Note Stopping and Starting Multi-thread Programs: Thread Stops, for
2326 more information about how GDB behaves when you stop and start programs
2327 with multiple threads.
2329 *Note Setting Watchpoints: Set Watchpoints, for information about
2330 watchpoints in programs with multiple threads.
2332 `set libthread-db-search-path [PATH]'
2333 If this variable is set, PATH is a colon-separated list of
2334 directories GDB will use to search for `libthread_db'. If you
2335 omit PATH, `libthread-db-search-path' will be reset to an empty
2338 On GNU/Linux and Solaris systems, GDB uses a "helper"
2339 `libthread_db' library to obtain information about threads in the
2340 inferior process. GDB will use `libthread-db-search-path' to find
2341 `libthread_db'. If that fails, GDB will continue with default
2342 system shared library directories, and finally the directory from
2343 which `libpthread' was loaded in the inferior process.
2345 For any `libthread_db' library GDB finds in above directories, GDB
2346 attempts to initialize it with the current inferior process. If
2347 this initialization fails (which could happen because of a version
2348 mismatch between `libthread_db' and `libpthread'), GDB will unload
2349 `libthread_db', and continue with the next directory. If none of
2350 `libthread_db' libraries initialize successfully, GDB will issue a
2351 warning and thread debugging will be disabled.
2353 Setting `libthread-db-search-path' is currently implemented only
2356 `show libthread-db-search-path'
2357 Display current libthread_db search path.
2360 File: gdb.info, Node: Forks, Next: Checkpoint/Restart, Prev: Threads, Up: Running
2362 4.11 Debugging Forks
2363 ====================
2365 On most systems, GDB has no special support for debugging programs
2366 which create additional processes using the `fork' function. When a
2367 program forks, GDB will continue to debug the parent process and the
2368 child process will run unimpeded. If you have set a breakpoint in any
2369 code which the child then executes, the child will get a `SIGTRAP'
2370 signal which (unless it catches the signal) will cause it to terminate.
2372 However, if you want to debug the child process there is a workaround
2373 which isn't too painful. Put a call to `sleep' in the code which the
2374 child process executes after the fork. It may be useful to sleep only
2375 if a certain environment variable is set, or a certain file exists, so
2376 that the delay need not occur when you don't want to run GDB on the
2377 child. While the child is sleeping, use the `ps' program to get its
2378 process ID. Then tell GDB (a new invocation of GDB if you are also
2379 debugging the parent process) to attach to the child process (*note
2380 Attach::). From that point on you can debug the child process just
2381 like any other process which you attached to.
2383 On some systems, GDB provides support for debugging programs that
2384 create additional processes using the `fork' or `vfork' functions.
2385 Currently, the only platforms with this feature are HP-UX (11.x and
2386 later only?) and GNU/Linux (kernel version 2.5.60 and later).
2388 By default, when a program forks, GDB will continue to debug the
2389 parent process and the child process will run unimpeded.
2391 If you want to follow the child process instead of the parent
2392 process, use the command `set follow-fork-mode'.
2394 `set follow-fork-mode MODE'
2395 Set the debugger response to a program call of `fork' or `vfork'.
2396 A call to `fork' or `vfork' creates a new process. The MODE
2400 The original process is debugged after a fork. The child
2401 process runs unimpeded. This is the default.
2404 The new process is debugged after a fork. The parent process
2408 `show follow-fork-mode'
2409 Display the current debugger response to a `fork' or `vfork' call.
2411 On Linux, if you want to debug both the parent and child processes,
2412 use the command `set detach-on-fork'.
2414 `set detach-on-fork MODE'
2415 Tells gdb whether to detach one of the processes after a fork, or
2416 retain debugger control over them both.
2419 The child process (or parent process, depending on the value
2420 of `follow-fork-mode') will be detached and allowed to run
2421 independently. This is the default.
2424 Both processes will be held under the control of GDB. One
2425 process (child or parent, depending on the value of
2426 `follow-fork-mode') is debugged as usual, while the other is
2430 `show detach-on-fork'
2431 Show whether detach-on-fork mode is on/off.
2433 If you choose to set `detach-on-fork' mode off, then GDB will retain
2434 control of all forked processes (including nested forks). You can list
2435 the forked processes under the control of GDB by using the
2436 `info inferiors' command, and switch from one fork to another by using
2437 the `inferior' command (*note Debugging Multiple Inferiors and
2438 Programs: Inferiors and Programs.).
2440 To quit debugging one of the forked processes, you can either detach
2441 from it by using the `detach inferior' command (allowing it to run
2442 independently), or kill it using the `kill inferior' command. *Note
2443 Debugging Multiple Inferiors and Programs: Inferiors and Programs.
2445 If you ask to debug a child process and a `vfork' is followed by an
2446 `exec', GDB executes the new target up to the first breakpoint in the
2447 new target. If you have a breakpoint set on `main' in your original
2448 program, the breakpoint will also be set on the child process's `main'.
2450 On some systems, when a child process is spawned by `vfork', you
2451 cannot debug the child or parent until an `exec' call completes.
2453 If you issue a `run' command to GDB after an `exec' call executes,
2454 the new target restarts. To restart the parent process, use the `file'
2455 command with the parent executable name as its argument. By default,
2456 after an `exec' call executes, GDB discards the symbols of the previous
2457 executable image. You can change this behaviour with the
2458 `set follow-exec-mode' command.
2460 `set follow-exec-mode MODE'
2461 Set debugger response to a program call of `exec'. An `exec' call
2462 replaces the program image of a process.
2464 `follow-exec-mode' can be:
2467 GDB creates a new inferior and rebinds the process to this
2468 new inferior. The program the process was running before the
2469 `exec' call can be restarted afterwards by restarting the
2474 (gdb) info inferiors
2476 Id Description Executable
2479 process 12020 is executing new program: prog2
2480 Program exited normally.
2481 (gdb) info inferiors
2482 Id Description Executable
2487 GDB keeps the process bound to the same inferior. The new
2488 executable image replaces the previous executable loaded in
2489 the inferior. Restarting the inferior after the `exec' call,
2490 with e.g., the `run' command, restarts the executable the
2491 process was running after the `exec' call. This is the
2496 (gdb) info inferiors
2497 Id Description Executable
2500 process 12020 is executing new program: prog2
2501 Program exited normally.
2502 (gdb) info inferiors
2503 Id Description Executable
2507 You can use the `catch' command to make GDB stop whenever a `fork',
2508 `vfork', or `exec' call is made. *Note Setting Catchpoints: Set
2512 File: gdb.info, Node: Checkpoint/Restart, Prev: Forks, Up: Running
2514 4.12 Setting a _Bookmark_ to Return to Later
2515 ============================================
2517 On certain operating systems(1), GDB is able to save a "snapshot" of a
2518 program's state, called a "checkpoint", and come back to it later.
2520 Returning to a checkpoint effectively undoes everything that has
2521 happened in the program since the `checkpoint' was saved. This
2522 includes changes in memory, registers, and even (within some limits)
2523 system state. Effectively, it is like going back in time to the moment
2524 when the checkpoint was saved.
2526 Thus, if you're stepping thru a program and you think you're getting
2527 close to the point where things go wrong, you can save a checkpoint.
2528 Then, if you accidentally go too far and miss the critical statement,
2529 instead of having to restart your program from the beginning, you can
2530 just go back to the checkpoint and start again from there.
2532 This can be especially useful if it takes a lot of time or steps to
2533 reach the point where you think the bug occurs.
2535 To use the `checkpoint'/`restart' method of debugging:
2538 Save a snapshot of the debugged program's current execution state.
2539 The `checkpoint' command takes no arguments, but each checkpoint
2540 is assigned a small integer id, similar to a breakpoint id.
2543 List the checkpoints that have been saved in the current debugging
2544 session. For each checkpoint, the following information will be
2553 `Source line, or label'
2555 `restart CHECKPOINT-ID'
2556 Restore the program state that was saved as checkpoint number
2557 CHECKPOINT-ID. All program variables, registers, stack frames
2558 etc. will be returned to the values that they had when the
2559 checkpoint was saved. In essence, gdb will "wind back the clock"
2560 to the point in time when the checkpoint was saved.
2562 Note that breakpoints, GDB variables, command history etc. are
2563 not affected by restoring a checkpoint. In general, a checkpoint
2564 only restores things that reside in the program being debugged,
2565 not in the debugger.
2567 `delete checkpoint CHECKPOINT-ID'
2568 Delete the previously-saved checkpoint identified by CHECKPOINT-ID.
2571 Returning to a previously saved checkpoint will restore the user
2572 state of the program being debugged, plus a significant subset of the
2573 system (OS) state, including file pointers. It won't "un-write" data
2574 from a file, but it will rewind the file pointer to the previous
2575 location, so that the previously written data can be overwritten. For
2576 files opened in read mode, the pointer will also be restored so that the
2577 previously read data can be read again.
2579 Of course, characters that have been sent to a printer (or other
2580 external device) cannot be "snatched back", and characters received
2581 from eg. a serial device can be removed from internal program buffers,
2582 but they cannot be "pushed back" into the serial pipeline, ready to be
2583 received again. Similarly, the actual contents of files that have been
2584 changed cannot be restored (at this time).
2586 However, within those constraints, you actually can "rewind" your
2587 program to a previously saved point in time, and begin debugging it
2588 again -- and you can change the course of events so as to debug a
2589 different execution path this time.
2591 Finally, there is one bit of internal program state that will be
2592 different when you return to a checkpoint -- the program's process id.
2593 Each checkpoint will have a unique process id (or PID), and each will
2594 be different from the program's original PID. If your program has
2595 saved a local copy of its process id, this could potentially pose a
2598 4.12.1 A Non-obvious Benefit of Using Checkpoints
2599 -------------------------------------------------
2601 On some systems such as GNU/Linux, address space randomization is
2602 performed on new processes for security reasons. This makes it
2603 difficult or impossible to set a breakpoint, or watchpoint, on an
2604 absolute address if you have to restart the program, since the absolute
2605 location of a symbol will change from one execution to the next.
2607 A checkpoint, however, is an _identical_ copy of a process.
2608 Therefore if you create a checkpoint at (eg.) the start of main, and
2609 simply return to that checkpoint instead of restarting the process, you
2610 can avoid the effects of address randomization and your symbols will
2611 all stay in the same place.
2613 ---------- Footnotes ----------
2615 (1) Currently, only GNU/Linux.
2618 File: gdb.info, Node: Stopping, Next: Reverse Execution, Prev: Running, Up: Top
2620 5 Stopping and Continuing
2621 *************************
2623 The principal purposes of using a debugger are so that you can stop your
2624 program before it terminates; or so that, if your program runs into
2625 trouble, you can investigate and find out why.
2627 Inside GDB, your program may stop for any of several reasons, such
2628 as a signal, a breakpoint, or reaching a new line after a GDB command
2629 such as `step'. You may then examine and change variables, set new
2630 breakpoints or remove old ones, and then continue execution. Usually,
2631 the messages shown by GDB provide ample explanation of the status of
2632 your program--but you can also explicitly request this information at
2636 Display information about the status of your program: whether it is
2637 running or not, what process it is, and why it stopped.
2641 * Breakpoints:: Breakpoints, watchpoints, and catchpoints
2642 * Continuing and Stepping:: Resuming execution
2644 * Thread Stops:: Stopping and starting multi-thread programs
2647 File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping
2649 5.1 Breakpoints, Watchpoints, and Catchpoints
2650 =============================================
2652 A "breakpoint" makes your program stop whenever a certain point in the
2653 program is reached. For each breakpoint, you can add conditions to
2654 control in finer detail whether your program stops. You can set
2655 breakpoints with the `break' command and its variants (*note Setting
2656 Breakpoints: Set Breaks.), to specify the place where your program
2657 should stop by line number, function name or exact address in the
2660 On some systems, you can set breakpoints in shared libraries before
2661 the executable is run. There is a minor limitation on HP-UX systems:
2662 you must wait until the executable is run in order to set breakpoints
2663 in shared library routines that are not called directly by the program
2664 (for example, routines that are arguments in a `pthread_create' call).
2666 A "watchpoint" is a special breakpoint that stops your program when
2667 the value of an expression changes. The expression may be a value of a
2668 variable, or it could involve values of one or more variables combined
2669 by operators, such as `a + b'. This is sometimes called "data
2670 breakpoints". You must use a different command to set watchpoints
2671 (*note Setting Watchpoints: Set Watchpoints.), but aside from that, you
2672 can manage a watchpoint like any other breakpoint: you enable, disable,
2673 and delete both breakpoints and watchpoints using the same commands.
2675 You can arrange to have values from your program displayed
2676 automatically whenever GDB stops at a breakpoint. *Note Automatic
2677 Display: Auto Display.
2679 A "catchpoint" is another special breakpoint that stops your program
2680 when a certain kind of event occurs, such as the throwing of a C++
2681 exception or the loading of a library. As with watchpoints, you use a
2682 different command to set a catchpoint (*note Setting Catchpoints: Set
2683 Catchpoints.), but aside from that, you can manage a catchpoint like any
2684 other breakpoint. (To stop when your program receives a signal, use the
2685 `handle' command; see *note Signals: Signals.)
2687 GDB assigns a number to each breakpoint, watchpoint, or catchpoint
2688 when you create it; these numbers are successive integers starting with
2689 one. In many of the commands for controlling various features of
2690 breakpoints you use the breakpoint number to say which breakpoint you
2691 want to change. Each breakpoint may be "enabled" or "disabled"; if
2692 disabled, it has no effect on your program until you enable it again.
2694 Some GDB commands accept a range of breakpoints on which to operate.
2695 A breakpoint range is either a single breakpoint number, like `5', or
2696 two such numbers, in increasing order, separated by a hyphen, like
2697 `5-7'. When a breakpoint range is given to a command, all breakpoints
2698 in that range are operated on.
2702 * Set Breaks:: Setting breakpoints
2703 * Set Watchpoints:: Setting watchpoints
2704 * Set Catchpoints:: Setting catchpoints
2705 * Delete Breaks:: Deleting breakpoints
2706 * Disabling:: Disabling breakpoints
2707 * Conditions:: Break conditions
2708 * Break Commands:: Breakpoint command lists
2709 * Error in Breakpoints:: ``Cannot insert breakpoints''
2710 * Breakpoint-related Warnings:: ``Breakpoint address adjusted...''
2713 File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints
2715 5.1.1 Setting Breakpoints
2716 -------------------------
2718 Breakpoints are set with the `break' command (abbreviated `b'). The
2719 debugger convenience variable `$bpnum' records the number of the
2720 breakpoint you've set most recently; see *note Convenience Variables:
2721 Convenience Vars, for a discussion of what you can do with convenience
2725 Set a breakpoint at the given LOCATION, which can specify a
2726 function name, a line number, or an address of an instruction.
2727 (*Note Specify Location::, for a list of all the possible ways to
2728 specify a LOCATION.) The breakpoint will stop your program just
2729 before it executes any of the code in the specified LOCATION.
2731 When using source languages that permit overloading of symbols,
2732 such as C++, a function name may refer to more than one possible
2733 place to break. *Note Ambiguous Expressions: Ambiguous
2734 Expressions, for a discussion of that situation.
2736 It is also possible to insert a breakpoint that will stop the
2737 program only if a specific thread (*note Thread-Specific
2738 Breakpoints::) or a specific task (*note Ada Tasks::) hits that
2742 When called without any arguments, `break' sets a breakpoint at
2743 the next instruction to be executed in the selected stack frame
2744 (*note Examining the Stack: Stack.). In any selected frame but the
2745 innermost, this makes your program stop as soon as control returns
2746 to that frame. This is similar to the effect of a `finish'
2747 command in the frame inside the selected frame--except that
2748 `finish' does not leave an active breakpoint. If you use `break'
2749 without an argument in the innermost frame, GDB stops the next
2750 time it reaches the current location; this may be useful inside
2753 GDB normally ignores breakpoints when it resumes execution, until
2754 at least one instruction has been executed. If it did not do
2755 this, you would be unable to proceed past a breakpoint without
2756 first disabling the breakpoint. This rule applies whether or not
2757 the breakpoint already existed when your program stopped.
2760 Set a breakpoint with condition COND; evaluate the expression COND
2761 each time the breakpoint is reached, and stop only if the value is
2762 nonzero--that is, if COND evaluates as true. `...' stands for one
2763 of the possible arguments described above (or no argument)
2764 specifying where to break. *Note Break Conditions: Conditions,
2765 for more information on breakpoint conditions.
2768 Set a breakpoint enabled only for one stop. ARGS are the same as
2769 for the `break' command, and the breakpoint is set in the same
2770 way, but the breakpoint is automatically deleted after the first
2771 time your program stops there. *Note Disabling Breakpoints:
2775 Set a hardware-assisted breakpoint. ARGS are the same as for the
2776 `break' command and the breakpoint is set in the same way, but the
2777 breakpoint requires hardware support and some target hardware may
2778 not have this support. The main purpose of this is EPROM/ROM code
2779 debugging, so you can set a breakpoint at an instruction without
2780 changing the instruction. This can be used with the new
2781 trap-generation provided by SPARClite DSU and most x86-based
2782 targets. These targets will generate traps when a program
2783 accesses some data or instruction address that is assigned to the
2784 debug registers. However the hardware breakpoint registers can
2785 take a limited number of breakpoints. For example, on the DSU,
2786 only two data breakpoints can be set at a time, and GDB will
2787 reject this command if more than two are used. Delete or disable
2788 unused hardware breakpoints before setting new ones (*note
2789 Disabling Breakpoints: Disabling.). *Note Break Conditions:
2790 Conditions. For remote targets, you can restrict the number of
2791 hardware breakpoints GDB will use, see *note set remote
2792 hardware-breakpoint-limit::.
2795 Set a hardware-assisted breakpoint enabled only for one stop. ARGS
2796 are the same as for the `hbreak' command and the breakpoint is set
2797 in the same way. However, like the `tbreak' command, the
2798 breakpoint is automatically deleted after the first time your
2799 program stops there. Also, like the `hbreak' command, the
2800 breakpoint requires hardware support and some target hardware may
2801 not have this support. *Note Disabling Breakpoints: Disabling.
2802 See also *note Break Conditions: Conditions.
2805 Set breakpoints on all functions matching the regular expression
2806 REGEX. This command sets an unconditional breakpoint on all
2807 matches, printing a list of all breakpoints it set. Once these
2808 breakpoints are set, they are treated just like the breakpoints
2809 set with the `break' command. You can delete them, disable them,
2810 or make them conditional the same way as any other breakpoint.
2812 The syntax of the regular expression is the standard one used with
2813 tools like `grep'. Note that this is different from the syntax
2814 used by shells, so for instance `foo*' matches all functions that
2815 include an `fo' followed by zero or more `o's. There is an
2816 implicit `.*' leading and trailing the regular expression you
2817 supply, so to match only functions that begin with `foo', use
2820 When debugging C++ programs, `rbreak' is useful for setting
2821 breakpoints on overloaded functions that are not members of any
2824 The `rbreak' command can be used to set breakpoints in *all* the
2825 functions in a program, like this:
2829 `info breakpoints [N]'
2831 `info watchpoints [N]'
2832 Print a table of all breakpoints, watchpoints, and catchpoints set
2833 and not deleted. Optional argument N means print information only
2834 about the specified breakpoint (or watchpoint or catchpoint). For
2835 each breakpoint, following columns are printed:
2837 _Breakpoint Numbers_
2840 Breakpoint, watchpoint, or catchpoint.
2843 Whether the breakpoint is marked to be disabled or deleted
2846 _Enabled or Disabled_
2847 Enabled breakpoints are marked with `y'. `n' marks
2848 breakpoints that are not enabled.
2851 Where the breakpoint is in your program, as a memory address.
2852 For a pending breakpoint whose address is not yet known, this
2853 field will contain `<PENDING>'. Such breakpoint won't fire
2854 until a shared library that has the symbol or line referred
2855 by breakpoint is loaded. See below for details. A
2856 breakpoint with several locations will have `<MULTIPLE>' in
2857 this field--see below for details.
2860 Where the breakpoint is in the source for your program, as a
2861 file and line number. For a pending breakpoint, the original
2862 string passed to the breakpoint command will be listed as it
2863 cannot be resolved until the appropriate shared library is
2864 loaded in the future.
2866 If a breakpoint is conditional, `info break' shows the condition on
2867 the line following the affected breakpoint; breakpoint commands,
2868 if any, are listed after that. A pending breakpoint is allowed to
2869 have a condition specified for it. The condition is not parsed
2870 for validity until a shared library is loaded that allows the
2871 pending breakpoint to resolve to a valid location.
2873 `info break' with a breakpoint number N as argument lists only
2874 that breakpoint. The convenience variable `$_' and the default
2875 examining-address for the `x' command are set to the address of
2876 the last breakpoint listed (*note Examining Memory: Memory.).
2878 `info break' displays a count of the number of times the breakpoint
2879 has been hit. This is especially useful in conjunction with the
2880 `ignore' command. You can ignore a large number of breakpoint
2881 hits, look at the breakpoint info to see how many times the
2882 breakpoint was hit, and then run again, ignoring one less than
2883 that number. This will get you quickly to the last hit of that
2886 GDB allows you to set any number of breakpoints at the same place in
2887 your program. There is nothing silly or meaningless about this. When
2888 the breakpoints are conditional, this is even useful (*note Break
2889 Conditions: Conditions.).
2891 It is possible that a breakpoint corresponds to several locations in
2892 your program. Examples of this situation are:
2894 * For a C++ constructor, the GCC compiler generates several
2895 instances of the function body, used in different cases.
2897 * For a C++ template function, a given line in the function can
2898 correspond to any number of instantiations.
2900 * For an inlined function, a given source line can correspond to
2901 several places where that function is inlined.
2903 In all those cases, GDB will insert a breakpoint at all the relevant
2906 A breakpoint with multiple locations is displayed in the breakpoint
2907 table using several rows--one header row, followed by one row for each
2908 breakpoint location. The header row has `<MULTIPLE>' in the address
2909 column. The rows for individual locations contain the actual addresses
2910 for locations, and show the functions to which those locations belong.
2911 The number column for a location is of the form
2912 BREAKPOINT-NUMBER.LOCATION-NUMBER.
2916 Num Type Disp Enb Address What
2917 1 breakpoint keep y <MULTIPLE>
2919 breakpoint already hit 1 time
2920 1.1 y 0x080486a2 in void foo<int>() at t.cc:8
2921 1.2 y 0x080486ca in void foo<double>() at t.cc:8
2923 Each location can be individually enabled or disabled by passing
2924 BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the `enable' and
2925 `disable' commands. Note that you cannot delete the individual
2926 locations from the list, you can only delete the entire list of
2927 locations that belong to their parent breakpoint (with the `delete NUM'
2928 command, where NUM is the number of the parent breakpoint, 1 in the
2929 above example). Disabling or enabling the parent breakpoint (*note
2930 Disabling::) affects all of the locations that belong to that
2933 It's quite common to have a breakpoint inside a shared library.
2934 Shared libraries can be loaded and unloaded explicitly, and possibly
2935 repeatedly, as the program is executed. To support this use case, GDB
2936 updates breakpoint locations whenever any shared library is loaded or
2937 unloaded. Typically, you would set a breakpoint in a shared library at
2938 the beginning of your debugging session, when the library is not
2939 loaded, and when the symbols from the library are not available. When
2940 you try to set breakpoint, GDB will ask you if you want to set a so
2941 called "pending breakpoint"--breakpoint whose address is not yet
2944 After the program is run, whenever a new shared library is loaded,
2945 GDB reevaluates all the breakpoints. When a newly loaded shared
2946 library contains the symbol or line referred to by some pending
2947 breakpoint, that breakpoint is resolved and becomes an ordinary
2948 breakpoint. When a library is unloaded, all breakpoints that refer to
2949 its symbols or source lines become pending again.
2951 This logic works for breakpoints with multiple locations, too. For
2952 example, if you have a breakpoint in a C++ template function, and a
2953 newly loaded shared library has an instantiation of that template, a
2954 new location is added to the list of locations for the breakpoint.
2956 Except for having unresolved address, pending breakpoints do not
2957 differ from regular breakpoints. You can set conditions or commands,
2958 enable and disable them and perform other breakpoint operations.
2960 GDB provides some additional commands for controlling what happens
2961 when the `break' command cannot resolve breakpoint address
2962 specification to an address:
2964 `set breakpoint pending auto'
2965 This is the default behavior. When GDB cannot find the breakpoint
2966 location, it queries you whether a pending breakpoint should be
2969 `set breakpoint pending on'
2970 This indicates that an unrecognized breakpoint location should
2971 automatically result in a pending breakpoint being created.
2973 `set breakpoint pending off'
2974 This indicates that pending breakpoints are not to be created. Any
2975 unrecognized breakpoint location results in an error. This
2976 setting does not affect any pending breakpoints previously created.
2978 `show breakpoint pending'
2979 Show the current behavior setting for creating pending breakpoints.
2981 The settings above only affect the `break' command and its variants.
2982 Once breakpoint is set, it will be automatically updated as shared
2983 libraries are loaded and unloaded.
2985 For some targets, GDB can automatically decide if hardware or
2986 software breakpoints should be used, depending on whether the
2987 breakpoint address is read-only or read-write. This applies to
2988 breakpoints set with the `break' command as well as to internal
2989 breakpoints set by commands like `next' and `finish'. For breakpoints
2990 set with `hbreak', GDB will always use hardware breakpoints.
2992 You can control this automatic behaviour with the following
2995 `set breakpoint auto-hw on'
2996 This is the default behavior. When GDB sets a breakpoint, it will
2997 try to use the target memory map to decide if software or hardware
2998 breakpoint must be used.
3000 `set breakpoint auto-hw off'
3001 This indicates GDB should not automatically select breakpoint
3002 type. If the target provides a memory map, GDB will warn when
3003 trying to set software breakpoint at a read-only address.
3005 GDB normally implements breakpoints by replacing the program code at
3006 the breakpoint address with a special instruction, which, when
3007 executed, given control to the debugger. By default, the program code
3008 is so modified only when the program is resumed. As soon as the
3009 program stops, GDB restores the original instructions. This behaviour
3010 guards against leaving breakpoints inserted in the target should gdb
3011 abrubptly disconnect. However, with slow remote targets, inserting and
3012 removing breakpoint can reduce the performance. This behavior can be
3013 controlled with the following commands::
3015 `set breakpoint always-inserted off'
3016 All breakpoints, including newly added by the user, are inserted in
3017 the target only when the target is resumed. All breakpoints are
3018 removed from the target when it stops.
3020 `set breakpoint always-inserted on'
3021 Causes all breakpoints to be inserted in the target at all times.
3022 If the user adds a new breakpoint, or changes an existing
3023 breakpoint, the breakpoints in the target are updated immediately.
3024 A breakpoint is removed from the target only when breakpoint
3027 `set breakpoint always-inserted auto'
3028 This is the default mode. If GDB is controlling the inferior in
3029 non-stop mode (*note Non-Stop Mode::), gdb behaves as if
3030 `breakpoint always-inserted' mode is on. If GDB is controlling
3031 the inferior in all-stop mode, GDB behaves as if `breakpoint
3032 always-inserted' mode is off.
3034 GDB itself sometimes sets breakpoints in your program for special
3035 purposes, such as proper handling of `longjmp' (in C programs). These
3036 internal breakpoints are assigned negative numbers, starting with `-1';
3037 `info breakpoints' does not display them. You can see these
3038 breakpoints with the GDB maintenance command `maint info breakpoints'
3039 (*note maint info breakpoints::).
3041 ---------- Footnotes ----------
3043 (1) As of this writing, multiple-location breakpoints work only if
3044 there's line number information for all the locations. This means that
3045 they will generally not work in system libraries, unless you have debug
3046 info with line numbers for them.
3049 File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints
3051 5.1.2 Setting Watchpoints
3052 -------------------------
3054 You can use a watchpoint to stop execution whenever the value of an
3055 expression changes, without having to predict a particular place where
3056 this may happen. (This is sometimes called a "data breakpoint".) The
3057 expression may be as simple as the value of a single variable, or as
3058 complex as many variables combined by operators. Examples include:
3060 * A reference to the value of a single variable.
3062 * An address cast to an appropriate data type. For example, `*(int
3063 *)0x12345678' will watch a 4-byte region at the specified address
3064 (assuming an `int' occupies 4 bytes).
3066 * An arbitrarily complex expression, such as `a*b + c/d'. The
3067 expression can use any operators valid in the program's native
3068 language (*note Languages::).
3070 You can set a watchpoint on an expression even if the expression can
3071 not be evaluated yet. For instance, you can set a watchpoint on
3072 `*global_ptr' before `global_ptr' is initialized. GDB will stop when
3073 your program sets `global_ptr' and the expression produces a valid
3074 value. If the expression becomes valid in some other way than changing
3075 a variable (e.g. if the memory pointed to by `*global_ptr' becomes
3076 readable as the result of a `malloc' call), GDB may not stop until the
3077 next time the expression changes.
3079 Depending on your system, watchpoints may be implemented in software
3080 or hardware. GDB does software watchpointing by single-stepping your
3081 program and testing the variable's value each time, which is hundreds of
3082 times slower than normal execution. (But this may still be worth it, to
3083 catch errors where you have no clue what part of your program is the
3086 On some systems, such as HP-UX, PowerPC, GNU/Linux and most other
3087 x86-based targets, GDB includes support for hardware watchpoints, which
3088 do not slow down the running of your program.
3090 `watch EXPR [thread THREADNUM]'
3091 Set a watchpoint for an expression. GDB will break when the
3092 expression EXPR is written into by the program and its value
3093 changes. The simplest (and the most popular) use of this command
3094 is to watch the value of a single variable:
3098 If the command includes a `[thread THREADNUM]' clause, GDB breaks
3099 only when the thread identified by THREADNUM changes the value of
3100 EXPR. If any other threads change the value of EXPR, GDB will not
3101 break. Note that watchpoints restricted to a single thread in
3102 this way only work with Hardware Watchpoints.
3104 `rwatch EXPR [thread THREADNUM]'
3105 Set a watchpoint that will break when the value of EXPR is read by
3108 `awatch EXPR [thread THREADNUM]'
3109 Set a watchpoint that will break when EXPR is either read from or
3110 written into by the program.
3113 This command prints a list of watchpoints, breakpoints, and
3114 catchpoints; it is the same as `info break' (*note Set Breaks::).
3116 GDB sets a "hardware watchpoint" if possible. Hardware watchpoints
3117 execute very quickly, and the debugger reports a change in value at the
3118 exact instruction where the change occurs. If GDB cannot set a
3119 hardware watchpoint, it sets a software watchpoint, which executes more
3120 slowly and reports the change in value at the next _statement_, not the
3121 instruction, after the change occurs.
3123 You can force GDB to use only software watchpoints with the `set
3124 can-use-hw-watchpoints 0' command. With this variable set to zero, GDB
3125 will never try to use hardware watchpoints, even if the underlying
3126 system supports them. (Note that hardware-assisted watchpoints that
3127 were set _before_ setting `can-use-hw-watchpoints' to zero will still
3128 use the hardware mechanism of watching expression values.)
3130 `set can-use-hw-watchpoints'
3131 Set whether or not to use hardware watchpoints.
3133 `show can-use-hw-watchpoints'
3134 Show the current mode of using hardware watchpoints.
3136 For remote targets, you can restrict the number of hardware
3137 watchpoints GDB will use, see *note set remote
3138 hardware-breakpoint-limit::.
3140 When you issue the `watch' command, GDB reports
3142 Hardware watchpoint NUM: EXPR
3144 if it was able to set a hardware watchpoint.
3146 Currently, the `awatch' and `rwatch' commands can only set hardware
3147 watchpoints, because accesses to data that don't change the value of
3148 the watched expression cannot be detected without examining every
3149 instruction as it is being executed, and GDB does not do that
3150 currently. If GDB finds that it is unable to set a hardware breakpoint
3151 with the `awatch' or `rwatch' command, it will print a message like
3154 Expression cannot be implemented with read/access watchpoint.
3156 Sometimes, GDB cannot set a hardware watchpoint because the data
3157 type of the watched expression is wider than what a hardware watchpoint
3158 on the target machine can handle. For example, some systems can only
3159 watch regions that are up to 4 bytes wide; on such systems you cannot
3160 set hardware watchpoints for an expression that yields a
3161 double-precision floating-point number (which is typically 8 bytes
3162 wide). As a work-around, it might be possible to break the large region
3163 into a series of smaller ones and watch them with separate watchpoints.
3165 If you set too many hardware watchpoints, GDB might be unable to
3166 insert all of them when you resume the execution of your program.
3167 Since the precise number of active watchpoints is unknown until such
3168 time as the program is about to be resumed, GDB might not be able to
3169 warn you about this when you set the watchpoints, and the warning will
3170 be printed only when the program is resumed:
3172 Hardware watchpoint NUM: Could not insert watchpoint
3174 If this happens, delete or disable some of the watchpoints.
3176 Watching complex expressions that reference many variables can also
3177 exhaust the resources available for hardware-assisted watchpoints.
3178 That's because GDB needs to watch every variable in the expression with
3179 separately allocated resources.
3181 If you call a function interactively using `print' or `call', any
3182 watchpoints you have set will be inactive until GDB reaches another
3183 kind of breakpoint or the call completes.
3185 GDB automatically deletes watchpoints that watch local (automatic)
3186 variables, or expressions that involve such variables, when they go out
3187 of scope, that is, when the execution leaves the block in which these
3188 variables were defined. In particular, when the program being debugged
3189 terminates, _all_ local variables go out of scope, and so only
3190 watchpoints that watch global variables remain set. If you rerun the
3191 program, you will need to set all such watchpoints again. One way of
3192 doing that would be to set a code breakpoint at the entry to the `main'
3193 function and when it breaks, set all the watchpoints.
3195 In multi-threaded programs, watchpoints will detect changes to the
3196 watched expression from every thread.
3198 _Warning:_ In multi-threaded programs, software watchpoints have
3199 only limited usefulness. If GDB creates a software watchpoint, it
3200 can only watch the value of an expression _in a single thread_.
3201 If you are confident that the expression can only change due to
3202 the current thread's activity (and if you are also confident that
3203 no other thread can become current), then you can use software
3204 watchpoints as usual. However, GDB may not notice when a
3205 non-current thread's activity changes the expression. (Hardware
3206 watchpoints, in contrast, watch an expression in all threads.)
3208 *Note set remote hardware-watchpoint-limit::.
3211 File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints
3213 5.1.3 Setting Catchpoints
3214 -------------------------
3216 You can use "catchpoints" to cause the debugger to stop for certain
3217 kinds of program events, such as C++ exceptions or the loading of a
3218 shared library. Use the `catch' command to set a catchpoint.
3221 Stop when EVENT occurs. EVENT can be any of the following:
3223 The throwing of a C++ exception.
3226 The catching of a C++ exception.
3229 An Ada exception being raised. If an exception name is
3230 specified at the end of the command (eg `catch exception
3231 Program_Error'), the debugger will stop only when this
3232 specific exception is raised. Otherwise, the debugger stops
3233 execution when any Ada exception is raised.
3235 When inserting an exception catchpoint on a user-defined
3236 exception whose name is identical to one of the exceptions
3237 defined by the language, the fully qualified name must be
3238 used as the exception name. Otherwise, GDB will assume that
3239 it should stop on the pre-defined exception rather than the
3240 user-defined one. For instance, assuming an exception called
3241 `Constraint_Error' is defined in package `Pck', then the
3242 command to use to catch such exceptions is `catch exception
3243 Pck.Constraint_Error'.
3245 `exception unhandled'
3246 An exception that was raised but is not handled by the
3250 A failed Ada assertion.
3253 A call to `exec'. This is currently only available for HP-UX
3257 `syscall [NAME | NUMBER] ...'
3258 A call to or return from a system call, a.k.a. "syscall". A
3259 syscall is a mechanism for application programs to request a
3260 service from the operating system (OS) or one of the OS
3261 system services. GDB can catch some or all of the syscalls
3262 issued by the debuggee, and show the related information for
3263 each syscall. If no argument is specified, calls to and
3264 returns from all system calls will be caught.
3266 NAME can be any system call name that is valid for the
3267 underlying OS. Just what syscalls are valid depends on the
3268 OS. On GNU and Unix systems, you can find the full list of
3269 valid syscall names on `/usr/include/asm/unistd.h'.
3271 Normally, GDB knows in advance which syscalls are valid for
3272 each OS, so you can use the GDB command-line completion
3273 facilities (*note command completion: Completion.) to list the
3276 You may also specify the system call numerically. A syscall's
3277 number is the value passed to the OS's syscall dispatcher to
3278 identify the requested service. When you specify the syscall
3279 by its name, GDB uses its database of syscalls to convert the
3280 name into the corresponding numeric code, but using the
3281 number directly may be useful if GDB's database does not have
3282 the complete list of syscalls on your system (e.g., because
3283 GDB lags behind the OS upgrades).
3285 The example below illustrates how this command works if you
3286 don't provide arguments to it:
3289 Catchpoint 1 (syscall)
3291 Starting program: /tmp/catch-syscall
3293 Catchpoint 1 (call to syscall 'close'), \
3294 0xffffe424 in __kernel_vsyscall ()
3298 Catchpoint 1 (returned from syscall 'close'), \
3299 0xffffe424 in __kernel_vsyscall ()
3302 Here is an example of catching a system call by name:
3304 (gdb) catch syscall chroot
3305 Catchpoint 1 (syscall 'chroot' [61])
3307 Starting program: /tmp/catch-syscall
3309 Catchpoint 1 (call to syscall 'chroot'), \
3310 0xffffe424 in __kernel_vsyscall ()
3314 Catchpoint 1 (returned from syscall 'chroot'), \
3315 0xffffe424 in __kernel_vsyscall ()
3318 An example of specifying a system call numerically. In the
3319 case below, the syscall number has a corresponding entry in
3320 the XML file, so GDB finds its name and prints it:
3322 (gdb) catch syscall 252
3323 Catchpoint 1 (syscall(s) 'exit_group')
3325 Starting program: /tmp/catch-syscall
3327 Catchpoint 1 (call to syscall 'exit_group'), \
3328 0xffffe424 in __kernel_vsyscall ()
3332 Program exited normally.
3335 However, there can be situations when there is no
3336 corresponding name in XML file for that syscall number. In
3337 this case, GDB prints a warning message saying that it was
3338 not able to find the syscall name, but the catchpoint will be
3339 set anyway. See the example below:
3341 (gdb) catch syscall 764
3342 warning: The number '764' does not represent a known syscall.
3343 Catchpoint 2 (syscall 764)
3346 If you configure GDB using the `--without-expat' option, it
3347 will not be able to display syscall names. Also, if your
3348 architecture does not have an XML file describing its system
3349 calls, you will not be able to see the syscall names. It is
3350 important to notice that these two features are used for
3351 accessing the syscall name database. In either case, you
3352 will see a warning like this:
3355 warning: Could not open "syscalls/i386-linux.xml"
3356 warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'.
3357 GDB will not be able to display syscall names.
3358 Catchpoint 1 (syscall)
3361 Of course, the file name will change depending on your
3362 architecture and system.
3364 Still using the example above, you can also try to catch a
3365 syscall by its number. In this case, you would see something
3368 (gdb) catch syscall 252
3369 Catchpoint 1 (syscall(s) 252)
3371 Again, in this case GDB would not be able to display
3375 A call to `fork'. This is currently only available for HP-UX
3379 A call to `vfork'. This is currently only available for HP-UX
3384 Set a catchpoint that is enabled only for one stop. The
3385 catchpoint is automatically deleted after the first time the event
3389 Use the `info break' command to list the current catchpoints.
3391 There are currently some limitations to C++ exception handling
3392 (`catch throw' and `catch catch') in GDB:
3394 * If you call a function interactively, GDB normally returns control
3395 to you when the function has finished executing. If the call
3396 raises an exception, however, the call may bypass the mechanism
3397 that returns control to you and cause your program either to abort
3398 or to simply continue running until it hits a breakpoint, catches
3399 a signal that GDB is listening for, or exits. This is the case
3400 even if you set a catchpoint for the exception; catchpoints on
3401 exceptions are disabled within interactive calls.
3403 * You cannot raise an exception interactively.
3405 * You cannot install an exception handler interactively.
3407 Sometimes `catch' is not the best way to debug exception handling:
3408 if you need to know exactly where an exception is raised, it is better
3409 to stop _before_ the exception handler is called, since that way you
3410 can see the stack before any unwinding takes place. If you set a
3411 breakpoint in an exception handler instead, it may not be easy to find
3412 out where the exception was raised.
3414 To stop just before an exception handler is called, you need some
3415 knowledge of the implementation. In the case of GNU C++, exceptions are
3416 raised by calling a library function named `__raise_exception' which
3417 has the following ANSI C interface:
3419 /* ADDR is where the exception identifier is stored.
3420 ID is the exception identifier. */
3421 void __raise_exception (void **addr, void *id);
3423 To make the debugger catch all exceptions before any stack unwinding
3424 takes place, set a breakpoint on `__raise_exception' (*note
3425 Breakpoints; Watchpoints; and Exceptions: Breakpoints.).
3427 With a conditional breakpoint (*note Break Conditions: Conditions.)
3428 that depends on the value of ID, you can stop your program when a
3429 specific exception is raised. You can use multiple conditional
3430 breakpoints to stop your program when any of a number of exceptions are
3434 File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints
3436 5.1.4 Deleting Breakpoints
3437 --------------------------
3439 It is often necessary to eliminate a breakpoint, watchpoint, or
3440 catchpoint once it has done its job and you no longer want your program
3441 to stop there. This is called "deleting" the breakpoint. A breakpoint
3442 that has been deleted no longer exists; it is forgotten.
3444 With the `clear' command you can delete breakpoints according to
3445 where they are in your program. With the `delete' command you can
3446 delete individual breakpoints, watchpoints, or catchpoints by specifying
3447 their breakpoint numbers.
3449 It is not necessary to delete a breakpoint to proceed past it. GDB
3450 automatically ignores breakpoints on the first instruction to be
3451 executed when you continue execution without changing the execution
3455 Delete any breakpoints at the next instruction to be executed in
3456 the selected stack frame (*note Selecting a Frame: Selection.).
3457 When the innermost frame is selected, this is a good way to delete
3458 a breakpoint where your program just stopped.
3461 Delete any breakpoints set at the specified LOCATION. *Note
3462 Specify Location::, for the various forms of LOCATION; the most
3463 useful ones are listed below:
3466 `clear FILENAME:FUNCTION'
3467 Delete any breakpoints set at entry to the named FUNCTION.
3470 `clear FILENAME:LINENUM'
3471 Delete any breakpoints set at or within the code of the
3472 specified LINENUM of the specified FILENAME.
3474 `delete [breakpoints] [RANGE...]'
3475 Delete the breakpoints, watchpoints, or catchpoints of the
3476 breakpoint ranges specified as arguments. If no argument is
3477 specified, delete all breakpoints (GDB asks confirmation, unless
3478 you have `set confirm off'). You can abbreviate this command as
3482 File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints
3484 5.1.5 Disabling Breakpoints
3485 ---------------------------
3487 Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
3488 prefer to "disable" it. This makes the breakpoint inoperative as if it
3489 had been deleted, but remembers the information on the breakpoint so
3490 that you can "enable" it again later.
3492 You disable and enable breakpoints, watchpoints, and catchpoints with
3493 the `enable' and `disable' commands, optionally specifying one or more
3494 breakpoint numbers as arguments. Use `info break' or `info watch' to
3495 print a list of breakpoints, watchpoints, and catchpoints if you do not
3496 know which numbers to use.
3498 Disabling and enabling a breakpoint that has multiple locations
3499 affects all of its locations.
3501 A breakpoint, watchpoint, or catchpoint can have any of four
3502 different states of enablement:
3504 * Enabled. The breakpoint stops your program. A breakpoint set
3505 with the `break' command starts out in this state.
3507 * Disabled. The breakpoint has no effect on your program.
3509 * Enabled once. The breakpoint stops your program, but then becomes
3512 * Enabled for deletion. The breakpoint stops your program, but
3513 immediately after it does so it is deleted permanently. A
3514 breakpoint set with the `tbreak' command starts out in this state.
3516 You can use the following commands to enable or disable breakpoints,
3517 watchpoints, and catchpoints:
3519 `disable [breakpoints] [RANGE...]'
3520 Disable the specified breakpoints--or all breakpoints, if none are
3521 listed. A disabled breakpoint has no effect but is not forgotten.
3522 All options such as ignore-counts, conditions and commands are
3523 remembered in case the breakpoint is enabled again later. You may
3524 abbreviate `disable' as `dis'.
3526 `enable [breakpoints] [RANGE...]'
3527 Enable the specified breakpoints (or all defined breakpoints).
3528 They become effective once again in stopping your program.
3530 `enable [breakpoints] once RANGE...'
3531 Enable the specified breakpoints temporarily. GDB disables any of
3532 these breakpoints immediately after stopping your program.
3534 `enable [breakpoints] delete RANGE...'
3535 Enable the specified breakpoints to work once, then die. GDB
3536 deletes any of these breakpoints as soon as your program stops
3537 there. Breakpoints set by the `tbreak' command start out in this
3540 Except for a breakpoint set with `tbreak' (*note Setting
3541 Breakpoints: Set Breaks.), breakpoints that you set are initially
3542 enabled; subsequently, they become disabled or enabled only when you
3543 use one of the commands above. (The command `until' can set and delete
3544 a breakpoint of its own, but it does not change the state of your other
3545 breakpoints; see *note Continuing and Stepping: Continuing and
3549 File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints
3551 5.1.6 Break Conditions
3552 ----------------------
3554 The simplest sort of breakpoint breaks every time your program reaches a
3555 specified place. You can also specify a "condition" for a breakpoint.
3556 A condition is just a Boolean expression in your programming language
3557 (*note Expressions: Expressions.). A breakpoint with a condition
3558 evaluates the expression each time your program reaches it, and your
3559 program stops only if the condition is _true_.
3561 This is the converse of using assertions for program validation; in
3562 that situation, you want to stop when the assertion is violated--that
3563 is, when the condition is false. In C, if you want to test an
3564 assertion expressed by the condition ASSERT, you should set the
3565 condition `! ASSERT' on the appropriate breakpoint.
3567 Conditions are also accepted for watchpoints; you may not need them,
3568 since a watchpoint is inspecting the value of an expression anyhow--but
3569 it might be simpler, say, to just set a watchpoint on a variable name,
3570 and specify a condition that tests whether the new value is an
3573 Break conditions can have side effects, and may even call functions
3574 in your program. This can be useful, for example, to activate functions
3575 that log program progress, or to use your own print functions to format
3576 special data structures. The effects are completely predictable unless
3577 there is another enabled breakpoint at the same address. (In that
3578 case, GDB might see the other breakpoint first and stop your program
3579 without checking the condition of this one.) Note that breakpoint
3580 commands are usually more convenient and flexible than break conditions
3581 for the purpose of performing side effects when a breakpoint is reached
3582 (*note Breakpoint Command Lists: Break Commands.).
3584 Break conditions can be specified when a breakpoint is set, by using
3585 `if' in the arguments to the `break' command. *Note Setting
3586 Breakpoints: Set Breaks. They can also be changed at any time with the
3587 `condition' command.
3589 You can also use the `if' keyword with the `watch' command. The
3590 `catch' command does not recognize the `if' keyword; `condition' is the
3591 only way to impose a further condition on a catchpoint.
3593 `condition BNUM EXPRESSION'
3594 Specify EXPRESSION as the break condition for breakpoint,
3595 watchpoint, or catchpoint number BNUM. After you set a condition,
3596 breakpoint BNUM stops your program only if the value of EXPRESSION
3597 is true (nonzero, in C). When you use `condition', GDB checks
3598 EXPRESSION immediately for syntactic correctness, and to determine
3599 whether symbols in it have referents in the context of your
3600 breakpoint. If EXPRESSION uses symbols not referenced in the
3601 context of the breakpoint, GDB prints an error message:
3603 No symbol "foo" in current context.
3605 GDB does not actually evaluate EXPRESSION at the time the
3606 `condition' command (or a command that sets a breakpoint with a
3607 condition, like `break if ...') is given, however. *Note
3608 Expressions: Expressions.
3611 Remove the condition from breakpoint number BNUM. It becomes an
3612 ordinary unconditional breakpoint.
3614 A special case of a breakpoint condition is to stop only when the
3615 breakpoint has been reached a certain number of times. This is so
3616 useful that there is a special way to do it, using the "ignore count"
3617 of the breakpoint. Every breakpoint has an ignore count, which is an
3618 integer. Most of the time, the ignore count is zero, and therefore has
3619 no effect. But if your program reaches a breakpoint whose ignore count
3620 is positive, then instead of stopping, it just decrements the ignore
3621 count by one and continues. As a result, if the ignore count value is
3622 N, the breakpoint does not stop the next N times your program reaches
3626 Set the ignore count of breakpoint number BNUM to COUNT. The next
3627 COUNT times the breakpoint is reached, your program's execution
3628 does not stop; other than to decrement the ignore count, GDB takes
3631 To make the breakpoint stop the next time it is reached, specify a
3634 When you use `continue' to resume execution of your program from a
3635 breakpoint, you can specify an ignore count directly as an
3636 argument to `continue', rather than using `ignore'. *Note
3637 Continuing and Stepping: Continuing and Stepping.
3639 If a breakpoint has a positive ignore count and a condition, the
3640 condition is not checked. Once the ignore count reaches zero, GDB
3641 resumes checking the condition.
3643 You could achieve the effect of the ignore count with a condition
3644 such as `$foo-- <= 0' using a debugger convenience variable that
3645 is decremented each time. *Note Convenience Variables:
3648 Ignore counts apply to breakpoints, watchpoints, and catchpoints.
3651 File: gdb.info, Node: Break Commands, Next: Error in Breakpoints, Prev: Conditions, Up: Breakpoints
3653 5.1.7 Breakpoint Command Lists
3654 ------------------------------
3656 You can give any breakpoint (or watchpoint or catchpoint) a series of
3657 commands to execute when your program stops due to that breakpoint. For
3658 example, you might want to print the values of certain expressions, or
3659 enable other breakpoints.
3662 `... COMMAND-LIST ...'
3664 Specify a list of commands for breakpoint number BNUM. The
3665 commands themselves appear on the following lines. Type a line
3666 containing just `end' to terminate the commands.
3668 To remove all commands from a breakpoint, type `commands' and
3669 follow it immediately with `end'; that is, give no commands.
3671 With no BNUM argument, `commands' refers to the last breakpoint,
3672 watchpoint, or catchpoint set (not to the breakpoint most recently
3675 Pressing <RET> as a means of repeating the last GDB command is
3676 disabled within a COMMAND-LIST.
3678 You can use breakpoint commands to start your program up again.
3679 Simply use the `continue' command, or `step', or any other command that
3682 Any other commands in the command list, after a command that resumes
3683 execution, are ignored. This is because any time you resume execution
3684 (even with a simple `next' or `step'), you may encounter another
3685 breakpoint--which could have its own command list, leading to
3686 ambiguities about which list to execute.
3688 If the first command you specify in a command list is `silent', the
3689 usual message about stopping at a breakpoint is not printed. This may
3690 be desirable for breakpoints that are to print a specific message and
3691 then continue. If none of the remaining commands print anything, you
3692 see no sign that the breakpoint was reached. `silent' is meaningful
3693 only at the beginning of a breakpoint command list.
3695 The commands `echo', `output', and `printf' allow you to print
3696 precisely controlled output, and are often useful in silent
3697 breakpoints. *Note Commands for Controlled Output: Output.
3699 For example, here is how you could use breakpoint commands to print
3700 the value of `x' at entry to `foo' whenever `x' is positive.
3705 printf "x is %d\n",x
3709 One application for breakpoint commands is to compensate for one bug
3710 so you can test for another. Put a breakpoint just after the erroneous
3711 line of code, give it a condition to detect the case in which something
3712 erroneous has been done, and give it commands to assign correct values
3713 to any variables that need them. End with the `continue' command so
3714 that your program does not stop, and start with the `silent' command so
3715 that no output is produced. Here is an example:
3725 File: gdb.info, Node: Error in Breakpoints, Next: Breakpoint-related Warnings, Prev: Break Commands, Up: Breakpoints
3727 5.1.8 "Cannot insert breakpoints"
3728 ---------------------------------
3730 If you request too many active hardware-assisted breakpoints and
3731 watchpoints, you will see this error message:
3733 Stopped; cannot insert breakpoints.
3734 You may have requested too many hardware breakpoints and watchpoints.
3736 This message is printed when you attempt to resume the program, since
3737 only then GDB knows exactly how many hardware breakpoints and
3738 watchpoints it needs to insert.
3740 When this message is printed, you need to disable or remove some of
3741 the hardware-assisted breakpoints and watchpoints, and then continue.
3744 File: gdb.info, Node: Breakpoint-related Warnings, Prev: Error in Breakpoints, Up: Breakpoints
3746 5.1.9 "Breakpoint address adjusted..."
3747 --------------------------------------
3749 Some processor architectures place constraints on the addresses at
3750 which breakpoints may be placed. For architectures thus constrained,
3751 GDB will attempt to adjust the breakpoint's address to comply with the
3752 constraints dictated by the architecture.
3754 One example of such an architecture is the Fujitsu FR-V. The FR-V is
3755 a VLIW architecture in which a number of RISC-like instructions may be
3756 bundled together for parallel execution. The FR-V architecture
3757 constrains the location of a breakpoint instruction within such a
3758 bundle to the instruction with the lowest address. GDB honors this
3759 constraint by adjusting a breakpoint's address to the first in the
3762 It is not uncommon for optimized code to have bundles which contain
3763 instructions from different source statements, thus it may happen that
3764 a breakpoint's address will be adjusted from one source statement to
3765 another. Since this adjustment may significantly alter GDB's
3766 breakpoint related behavior from what the user expects, a warning is
3767 printed when the breakpoint is first set and also when the breakpoint
3770 A warning like the one below is printed when setting a breakpoint
3771 that's been subject to address adjustment:
3773 warning: Breakpoint address adjusted from 0x00010414 to 0x00010410.
3775 Such warnings are printed both for user settable and GDB's internal
3776 breakpoints. If you see one of these warnings, you should verify that
3777 a breakpoint set at the adjusted address will have the desired affect.
3778 If not, the breakpoint in question may be removed and other breakpoints
3779 may be set which will have the desired behavior. E.g., it may be
3780 sufficient to place the breakpoint at a later instruction. A
3781 conditional breakpoint may also be useful in some cases to prevent the
3782 breakpoint from triggering too often.
3784 GDB will also issue a warning when stopping at one of these adjusted
3787 warning: Breakpoint 1 address previously adjusted from 0x00010414
3790 When this warning is encountered, it may be too late to take remedial
3791 action except in cases where the breakpoint is hit earlier or more
3792 frequently than expected.
3795 File: gdb.info, Node: Continuing and Stepping, Next: Signals, Prev: Breakpoints, Up: Stopping
3797 5.2 Continuing and Stepping
3798 ===========================
3800 "Continuing" means resuming program execution until your program
3801 completes normally. In contrast, "stepping" means executing just one
3802 more "step" of your program, where "step" may mean either one line of
3803 source code, or one machine instruction (depending on what particular
3804 command you use). Either when continuing or when stepping, your
3805 program may stop even sooner, due to a breakpoint or a signal. (If it
3806 stops due to a signal, you may want to use `handle', or use `signal 0'
3807 to resume execution. *Note Signals: Signals.)
3809 `continue [IGNORE-COUNT]'
3812 Resume program execution, at the address where your program last
3813 stopped; any breakpoints set at that address are bypassed. The
3814 optional argument IGNORE-COUNT allows you to specify a further
3815 number of times to ignore a breakpoint at this location; its
3816 effect is like that of `ignore' (*note Break Conditions:
3819 The argument IGNORE-COUNT is meaningful only when your program
3820 stopped due to a breakpoint. At other times, the argument to
3821 `continue' is ignored.
3823 The synonyms `c' and `fg' (for "foreground", as the debugged
3824 program is deemed to be the foreground program) are provided
3825 purely for convenience, and have exactly the same behavior as
3828 To resume execution at a different place, you can use `return'
3829 (*note Returning from a Function: Returning.) to go back to the calling
3830 function; or `jump' (*note Continuing at a Different Address: Jumping.)
3831 to go to an arbitrary location in your program.
3833 A typical technique for using stepping is to set a breakpoint (*note
3834 Breakpoints; Watchpoints; and Catchpoints: Breakpoints.) at the
3835 beginning of the function or the section of your program where a problem
3836 is believed to lie, run your program until it stops at that breakpoint,
3837 and then step through the suspect area, examining the variables that are
3838 interesting, until you see the problem happen.
3841 Continue running your program until control reaches a different
3842 source line, then stop it and return control to GDB. This command
3845 _Warning:_ If you use the `step' command while control is
3846 within a function that was compiled without debugging
3847 information, execution proceeds until control reaches a
3848 function that does have debugging information. Likewise, it
3849 will not step into a function which is compiled without
3850 debugging information. To step through functions without
3851 debugging information, use the `stepi' command, described
3854 The `step' command only stops at the first instruction of a source
3855 line. This prevents the multiple stops that could otherwise occur
3856 in `switch' statements, `for' loops, etc. `step' continues to
3857 stop if a function that has debugging information is called within
3858 the line. In other words, `step' _steps inside_ any functions
3859 called within the line.
3861 Also, the `step' command only enters a function if there is line
3862 number information for the function. Otherwise it acts like the
3863 `next' command. This avoids problems when using `cc -gl' on MIPS
3864 machines. Previously, `step' entered subroutines if there was any
3865 debugging information about the routine.
3868 Continue running as in `step', but do so COUNT times. If a
3869 breakpoint is reached, or a signal not related to stepping occurs
3870 before COUNT steps, stepping stops right away.
3873 Continue to the next source line in the current (innermost) stack
3874 frame. This is similar to `step', but function calls that appear
3875 within the line of code are executed without stopping. Execution
3876 stops when control reaches a different line of code at the
3877 original stack level that was executing when you gave the `next'
3878 command. This command is abbreviated `n'.
3880 An argument COUNT is a repeat count, as for `step'.
3882 The `next' command only stops at the first instruction of a source
3883 line. This prevents multiple stops that could otherwise occur in
3884 `switch' statements, `for' loops, etc.
3888 The `set step-mode on' command causes the `step' command to stop
3889 at the first instruction of a function which contains no debug line
3890 information rather than stepping over it.
3892 This is useful in cases where you may be interested in inspecting
3893 the machine instructions of a function which has no symbolic info
3894 and do not want GDB to automatically skip over this function.
3897 Causes the `step' command to step over any functions which
3898 contains no debug information. This is the default.
3901 Show whether GDB will stop in or step over functions without
3902 source line debug information.
3905 Continue running until just after function in the selected stack
3906 frame returns. Print the returned value (if any). This command
3907 can be abbreviated as `fin'.
3909 Contrast this with the `return' command (*note Returning from a
3910 Function: Returning.).
3914 Continue running until a source line past the current line, in the
3915 current stack frame, is reached. This command is used to avoid
3916 single stepping through a loop more than once. It is like the
3917 `next' command, except that when `until' encounters a jump, it
3918 automatically continues execution until the program counter is
3919 greater than the address of the jump.
3921 This means that when you reach the end of a loop after single
3922 stepping though it, `until' makes your program continue execution
3923 until it exits the loop. In contrast, a `next' command at the end
3924 of a loop simply steps back to the beginning of the loop, which
3925 forces you to step through the next iteration.
3927 `until' always stops your program if it attempts to exit the
3928 current stack frame.
3930 `until' may produce somewhat counterintuitive results if the order
3931 of machine code does not match the order of the source lines. For
3932 example, in the following excerpt from a debugging session, the `f'
3933 (`frame') command shows that execution is stopped at line `206';
3934 yet when we use `until', we get to line `195':
3937 #0 main (argc=4, argv=0xf7fffae8) at m4.c:206
3940 195 for ( ; argc > 0; NEXTARG) {
3942 This happened because, for execution efficiency, the compiler had
3943 generated code for the loop closure test at the end, rather than
3944 the start, of the loop--even though the test in a C `for'-loop is
3945 written before the body of the loop. The `until' command appeared
3946 to step back to the beginning of the loop when it advanced to this
3947 expression; however, it has not really gone to an earlier
3948 statement--not in terms of the actual machine code.
3950 `until' with no argument works by means of single instruction
3951 stepping, and hence is slower than `until' with an argument.
3955 Continue running your program until either the specified location
3956 is reached, or the current stack frame returns. LOCATION is any of
3957 the forms described in *note Specify Location::. This form of the
3958 command uses temporary breakpoints, and hence is quicker than
3959 `until' without an argument. The specified location is actually
3960 reached only if it is in the current frame. This implies that
3961 `until' can be used to skip over recursive function invocations.
3962 For instance in the code below, if the current location is line
3963 `96', issuing `until 99' will execute the program up to line `99'
3964 in the same invocation of factorial, i.e., after the inner
3965 invocations have returned.
3967 94 int factorial (int value)
3970 97 value *= factorial (value - 1);
3976 Continue running the program up to the given LOCATION. An
3977 argument is required, which should be of one of the forms
3978 described in *note Specify Location::. Execution will also stop
3979 upon exit from the current stack frame. This command is similar
3980 to `until', but `advance' will not skip over recursive function
3981 calls, and the target location doesn't have to be in the same
3982 frame as the current one.
3987 Execute one machine instruction, then stop and return to the
3990 It is often useful to do `display/i $pc' when stepping by machine
3991 instructions. This makes GDB automatically display the next
3992 instruction to be executed, each time your program stops. *Note
3993 Automatic Display: Auto Display.
3995 An argument is a repeat count, as in `step'.
4000 Execute one machine instruction, but if it is a function call,
4001 proceed until the function returns.
4003 An argument is a repeat count, as in `next'.
4006 File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Continuing and Stepping, Up: Stopping
4011 A signal is an asynchronous event that can happen in a program. The
4012 operating system defines the possible kinds of signals, and gives each
4013 kind a name and a number. For example, in Unix `SIGINT' is the signal
4014 a program gets when you type an interrupt character (often `Ctrl-c');
4015 `SIGSEGV' is the signal a program gets from referencing a place in
4016 memory far away from all the areas in use; `SIGALRM' occurs when the
4017 alarm clock timer goes off (which happens only if your program has
4018 requested an alarm).
4020 Some signals, including `SIGALRM', are a normal part of the
4021 functioning of your program. Others, such as `SIGSEGV', indicate
4022 errors; these signals are "fatal" (they kill your program immediately)
4023 if the program has not specified in advance some other way to handle
4024 the signal. `SIGINT' does not indicate an error in your program, but
4025 it is normally fatal so it can carry out the purpose of the interrupt:
4026 to kill the program.
4028 GDB has the ability to detect any occurrence of a signal in your
4029 program. You can tell GDB in advance what to do for each kind of
4032 Normally, GDB is set up to let the non-erroneous signals like
4033 `SIGALRM' be silently passed to your program (so as not to interfere
4034 with their role in the program's functioning) but to stop your program
4035 immediately whenever an error signal happens. You can change these
4036 settings with the `handle' command.
4040 Print a table of all the kinds of signals and how GDB has been
4041 told to handle each one. You can use this to see the signal
4042 numbers of all the defined types of signals.
4045 Similar, but print information only about the specified signal
4048 `info handle' is an alias for `info signals'.
4050 `handle SIGNAL [KEYWORDS...]'
4051 Change the way GDB handles signal SIGNAL. SIGNAL can be the
4052 number of a signal or its name (with or without the `SIG' at the
4053 beginning); a list of signal numbers of the form `LOW-HIGH'; or
4054 the word `all', meaning all the known signals. Optional arguments
4055 KEYWORDS, described below, say what change to make.
4057 The keywords allowed by the `handle' command can be abbreviated.
4058 Their full names are:
4061 GDB should not stop your program when this signal happens. It may
4062 still print a message telling you that the signal has come in.
4065 GDB should stop your program when this signal happens. This
4066 implies the `print' keyword as well.
4069 GDB should print a message when this signal happens.
4072 GDB should not mention the occurrence of the signal at all. This
4073 implies the `nostop' keyword as well.
4077 GDB should allow your program to see this signal; your program can
4078 handle the signal, or else it may terminate if the signal is fatal
4079 and not handled. `pass' and `noignore' are synonyms.
4083 GDB should not allow your program to see this signal. `nopass'
4084 and `ignore' are synonyms.
4086 When a signal stops your program, the signal is not visible to the
4087 program until you continue. Your program sees the signal then, if
4088 `pass' is in effect for the signal in question _at that time_. In
4089 other words, after GDB reports a signal, you can use the `handle'
4090 command with `pass' or `nopass' to control whether your program sees
4091 that signal when you continue.
4093 The default is set to `nostop', `noprint', `pass' for non-erroneous
4094 signals such as `SIGALRM', `SIGWINCH' and `SIGCHLD', and to `stop',
4095 `print', `pass' for the erroneous signals.
4097 You can also use the `signal' command to prevent your program from
4098 seeing a signal, or cause it to see a signal it normally would not see,
4099 or to give it any signal at any time. For example, if your program
4100 stopped due to some sort of memory reference error, you might store
4101 correct values into the erroneous variables and continue, hoping to see
4102 more execution; but your program would probably terminate immediately as
4103 a result of the fatal signal once it saw the signal. To prevent this,
4104 you can continue with `signal 0'. *Note Giving your Program a Signal:
4107 On some targets, GDB can inspect extra signal information associated
4108 with the intercepted signal, before it is actually delivered to the
4109 program being debugged. This information is exported by the
4110 convenience variable `$_siginfo', and consists of data that is passed
4111 by the kernel to the signal handler at the time of the receipt of a
4112 signal. The data type of the information itself is target dependent.
4113 You can see the data type using the `ptype $_siginfo' command. On Unix
4114 systems, it typically corresponds to the standard `siginfo_t' type, as
4115 defined in the `signal.h' system header.
4117 Here's an example, on a GNU/Linux system, printing the stray
4118 referenced address that raised a segmentation fault.
4121 Program received signal SIGSEGV, Segmentation fault.
4122 0x0000000000400766 in main ()
4124 (gdb) ptype $_siginfo
4132 struct {...} _timer;
4134 struct {...} _sigchld;
4135 struct {...} _sigfault;
4136 struct {...} _sigpoll;
4139 (gdb) ptype $_siginfo._sifields._sigfault
4143 (gdb) p $_siginfo._sifields._sigfault.si_addr
4144 $1 = (void *) 0x7ffff7ff7000
4146 Depending on target support, `$_siginfo' may also be writable.
4149 File: gdb.info, Node: Thread Stops, Prev: Signals, Up: Stopping
4151 5.4 Stopping and Starting Multi-thread Programs
4152 ===============================================
4154 GDB supports debugging programs with multiple threads (*note Debugging
4155 Programs with Multiple Threads: Threads.). There are two modes of
4156 controlling execution of your program within the debugger. In the
4157 default mode, referred to as "all-stop mode", when any thread in your
4158 program stops (for example, at a breakpoint or while being stepped),
4159 all other threads in the program are also stopped by GDB. On some
4160 targets, GDB also supports "non-stop mode", in which other threads can
4161 continue to run freely while you examine the stopped thread in the
4166 * All-Stop Mode:: All threads stop when GDB takes control
4167 * Non-Stop Mode:: Other threads continue to execute
4168 * Background Execution:: Running your program asynchronously
4169 * Thread-Specific Breakpoints:: Controlling breakpoints
4170 * Interrupted System Calls:: GDB may interfere with system calls
4173 File: gdb.info, Node: All-Stop Mode, Next: Non-Stop Mode, Up: Thread Stops
4178 In all-stop mode, whenever your program stops under GDB for any reason,
4179 _all_ threads of execution stop, not just the current thread. This
4180 allows you to examine the overall state of the program, including
4181 switching between threads, without worrying that things may change
4184 Conversely, whenever you restart the program, _all_ threads start
4185 executing. _This is true even when single-stepping_ with commands like
4188 In particular, GDB cannot single-step all threads in lockstep.
4189 Since thread scheduling is up to your debugging target's operating
4190 system (not controlled by GDB), other threads may execute more than one
4191 statement while the current thread completes a single step. Moreover,
4192 in general other threads stop in the middle of a statement, rather than
4193 at a clean statement boundary, when the program stops.
4195 You might even find your program stopped in another thread after
4196 continuing or even single-stepping. This happens whenever some other
4197 thread runs into a breakpoint, a signal, or an exception before the
4198 first thread completes whatever you requested.
4200 Whenever GDB stops your program, due to a breakpoint or a signal, it
4201 automatically selects the thread where that breakpoint or signal
4202 happened. GDB alerts you to the context switch with a message such as
4203 `[Switching to Thread N]' to identify the thread.
4205 On some OSes, you can modify GDB's default behavior by locking the
4206 OS scheduler to allow only a single thread to run.
4208 `set scheduler-locking MODE'
4209 Set the scheduler locking mode. If it is `off', then there is no
4210 locking and any thread may run at any time. If `on', then only the
4211 current thread may run when the inferior is resumed. The `step'
4212 mode optimizes for single-stepping; it prevents other threads from
4213 preempting the current thread while you are stepping, so that the
4214 focus of debugging does not change unexpectedly. Other threads
4215 only rarely (or never) get a chance to run when you step. They
4216 are more likely to run when you `next' over a function call, and
4217 they are completely free to run when you use commands like
4218 `continue', `until', or `finish'. However, unless another thread
4219 hits a breakpoint during its timeslice, GDB does not change the
4220 current thread away from the thread that you are debugging.
4222 `show scheduler-locking'
4223 Display the current scheduler locking mode.
4225 By default, when you issue one of the execution commands such as
4226 `continue', `next' or `step', GDB allows only threads of the current
4227 inferior to run. For example, if GDB is attached to two inferiors,
4228 each with two threads, the `continue' command resumes only the two
4229 threads of the current inferior. This is useful, for example, when you
4230 debug a program that forks and you want to hold the parent stopped (so
4231 that, for instance, it doesn't run to exit), while you debug the child.
4232 In other situations, you may not be interested in inspecting the
4233 current state of any of the processes GDB is attached to, and you may
4234 want to resume them all until some breakpoint is hit. In the latter
4235 case, you can instruct GDB to allow all threads of all the inferiors to
4236 run with the `set schedule-multiple' command.
4238 `set schedule-multiple'
4239 Set the mode for allowing threads of multiple processes to be
4240 resumed when an execution command is issued. When `on', all
4241 threads of all processes are allowed to run. When `off', only the
4242 threads of the current process are resumed. The default is `off'.
4243 The `scheduler-locking' mode takes precedence when set to `on', or
4244 while you are stepping and set to `step'.
4246 `show schedule-multiple'
4247 Display the current mode for resuming the execution of threads of
4251 File: gdb.info, Node: Non-Stop Mode, Next: Background Execution, Prev: All-Stop Mode, Up: Thread Stops
4256 For some multi-threaded targets, GDB supports an optional mode of
4257 operation in which you can examine stopped program threads in the
4258 debugger while other threads continue to execute freely. This
4259 minimizes intrusion when debugging live systems, such as programs where
4260 some threads have real-time constraints or must continue to respond to
4261 external events. This is referred to as "non-stop" mode.
4263 In non-stop mode, when a thread stops to report a debugging event,
4264 _only_ that thread is stopped; GDB does not stop other threads as well,
4265 in contrast to the all-stop mode behavior. Additionally, execution
4266 commands such as `continue' and `step' apply by default only to the
4267 current thread in non-stop mode, rather than all threads as in all-stop
4268 mode. This allows you to control threads explicitly in ways that are
4269 not possible in all-stop mode -- for example, stepping one thread while
4270 allowing others to run freely, stepping one thread while holding all
4271 others stopped, or stepping several threads independently and
4274 To enter non-stop mode, use this sequence of commands before you run
4275 or attach to your program:
4277 # Enable the async interface.
4280 # If using the CLI, pagination breaks non-stop.
4283 # Finally, turn it on!
4286 You can use these commands to manipulate the non-stop mode setting:
4289 Enable selection of non-stop mode.
4292 Disable selection of non-stop mode.
4295 Show the current non-stop enablement setting.
4297 Note these commands only reflect whether non-stop mode is enabled,
4298 not whether the currently-executing program is being run in non-stop
4299 mode. In particular, the `set non-stop' preference is only consulted
4300 when GDB starts or connects to the target program, and it is generally
4301 not possible to switch modes once debugging has started. Furthermore,
4302 since not all targets support non-stop mode, even when you have enabled
4303 non-stop mode, GDB may still fall back to all-stop operation by default.
4305 In non-stop mode, all execution commands apply only to the current
4306 thread by default. That is, `continue' only continues one thread. To
4307 continue all threads, issue `continue -a' or `c -a'.
4309 You can use GDB's background execution commands (*note Background
4310 Execution::) to run some threads in the background while you continue
4311 to examine or step others from GDB. The MI execution commands (*note
4312 GDB/MI Program Execution::) are always executed asynchronously in
4315 Suspending execution is done with the `interrupt' command when
4316 running in the background, or `Ctrl-c' during foreground execution. In
4317 all-stop mode, this stops the whole process; but in non-stop mode the
4318 interrupt applies only to the current thread. To stop the whole
4319 program, use `interrupt -a'.
4321 Other execution commands do not currently support the `-a' option.
4323 In non-stop mode, when a thread stops, GDB doesn't automatically make
4324 that thread current, as it does in all-stop mode. This is because the
4325 thread stop notifications are asynchronous with respect to GDB's
4326 command interpreter, and it would be confusing if GDB unexpectedly
4327 changed to a different thread just as you entered a command to operate
4328 on the previously current thread.
4331 File: gdb.info, Node: Background Execution, Next: Thread-Specific Breakpoints, Prev: Non-Stop Mode, Up: Thread Stops
4333 5.4.3 Background Execution
4334 --------------------------
4336 GDB's execution commands have two variants: the normal foreground
4337 (synchronous) behavior, and a background (asynchronous) behavior. In
4338 foreground execution, GDB waits for the program to report that some
4339 thread has stopped before prompting for another command. In background
4340 execution, GDB immediately gives a command prompt so that you can issue
4341 other commands while your program runs.
4343 You need to explicitly enable asynchronous mode before you can use
4344 background execution commands. You can use these commands to
4345 manipulate the asynchronous mode setting:
4347 `set target-async on'
4348 Enable asynchronous mode.
4350 `set target-async off'
4351 Disable asynchronous mode.
4354 Show the current target-async setting.
4356 If the target doesn't support async mode, GDB issues an error
4357 message if you attempt to use the background execution commands.
4359 To specify background execution, add a `&' to the command. For
4360 example, the background form of the `continue' command is `continue&',
4361 or just `c&'. The execution commands that accept background execution
4365 *Note Starting your Program: Starting.
4368 *Note Debugging an Already-running Process: Attach.
4371 *Note step: Continuing and Stepping.
4374 *Note stepi: Continuing and Stepping.
4377 *Note next: Continuing and Stepping.
4380 *Note nexti: Continuing and Stepping.
4383 *Note continue: Continuing and Stepping.
4386 *Note finish: Continuing and Stepping.
4389 *Note until: Continuing and Stepping.
4392 Background execution is especially useful in conjunction with
4393 non-stop mode for debugging programs with multiple threads; see *note
4394 Non-Stop Mode::. However, you can also use these commands in the
4395 normal all-stop mode with the restriction that you cannot issue another
4396 execution command until the previous one finishes. Examples of
4397 commands that are valid in all-stop mode while the program is running
4398 include `help' and `info break'.
4400 You can interrupt your program while it is running in the background
4401 by using the `interrupt' command.
4405 Suspend execution of the running program. In all-stop mode,
4406 `interrupt' stops the whole process, but in non-stop mode, it stops
4407 only the current thread. To stop the whole program in non-stop
4408 mode, use `interrupt -a'.
4411 File: gdb.info, Node: Thread-Specific Breakpoints, Next: Interrupted System Calls, Prev: Background Execution, Up: Thread Stops
4413 5.4.4 Thread-Specific Breakpoints
4414 ---------------------------------
4416 When your program has multiple threads (*note Debugging Programs with
4417 Multiple Threads: Threads.), you can choose whether to set breakpoints
4418 on all threads, or on a particular thread.
4420 `break LINESPEC thread THREADNO'
4421 `break LINESPEC thread THREADNO if ...'
4422 LINESPEC specifies source lines; there are several ways of writing
4423 them (*note Specify Location::), but the effect is always to
4424 specify some source line.
4426 Use the qualifier `thread THREADNO' with a breakpoint command to
4427 specify that you only want GDB to stop the program when a
4428 particular thread reaches this breakpoint. THREADNO is one of the
4429 numeric thread identifiers assigned by GDB, shown in the first
4430 column of the `info threads' display.
4432 If you do not specify `thread THREADNO' when you set a breakpoint,
4433 the breakpoint applies to _all_ threads of your program.
4435 You can use the `thread' qualifier on conditional breakpoints as
4436 well; in this case, place `thread THREADNO' before or after the
4437 breakpoint condition, like this:
4439 (gdb) break frik.c:13 thread 28 if bartab > lim
4443 File: gdb.info, Node: Interrupted System Calls, Prev: Thread-Specific Breakpoints, Up: Thread Stops
4445 5.4.5 Interrupted System Calls
4446 ------------------------------
4448 There is an unfortunate side effect when using GDB to debug
4449 multi-threaded programs. If one thread stops for a breakpoint, or for
4450 some other reason, and another thread is blocked in a system call, then
4451 the system call may return prematurely. This is a consequence of the
4452 interaction between multiple threads and the signals that GDB uses to
4453 implement breakpoints and other events that stop execution.
4455 To handle this problem, your program should check the return value of
4456 each system call and react appropriately. This is good programming
4459 For example, do not write code like this:
4463 The call to `sleep' will return early if a different thread stops at
4464 a breakpoint or for some other reason.
4466 Instead, write this:
4470 unslept = sleep (unslept);
4472 A system call is allowed to return early, so the system is still
4473 conforming to its specification. But GDB does cause your
4474 multi-threaded program to behave differently than it would without GDB.
4476 Also, GDB uses internal breakpoints in the thread library to monitor
4477 certain events such as thread creation and thread destruction. When
4478 such an event happens, a system call in another thread may return
4479 prematurely, even though your program does not appear to stop.
4482 File: gdb.info, Node: Reverse Execution, Next: Process Record and Replay, Prev: Stopping, Up: Top
4484 6 Running programs backward
4485 ***************************
4487 When you are debugging a program, it is not unusual to realize that you
4488 have gone too far, and some event of interest has already happened. If
4489 the target environment supports it, GDB can allow you to "rewind" the
4490 program by running it backward.
4492 A target environment that supports reverse execution should be able
4493 to "undo" the changes in machine state that have taken place as the
4494 program was executing normally. Variables, registers etc. should
4495 revert to their previous values. Obviously this requires a great deal
4496 of sophistication on the part of the target environment; not all target
4497 environments can support reverse execution.
4499 When a program is executed in reverse, the instructions that have
4500 most recently been executed are "un-executed", in reverse order. The
4501 program counter runs backward, following the previous thread of
4502 execution in reverse. As each instruction is "un-executed", the values
4503 of memory and/or registers that were changed by that instruction are
4504 reverted to their previous states. After executing a piece of source
4505 code in reverse, all side effects of that code should be "undone", and
4506 all variables should be returned to their prior values(1).
4508 If you are debugging in a target environment that supports reverse
4509 execution, GDB provides the following commands.
4511 `reverse-continue [IGNORE-COUNT]'
4513 Beginning at the point where your program last stopped, start
4514 executing in reverse. Reverse execution will stop for breakpoints
4515 and synchronous exceptions (signals), just like normal execution.
4516 Behavior of asynchronous signals depends on the target environment.
4518 `reverse-step [COUNT]'
4519 Run the program backward until control reaches the start of a
4520 different source line; then stop it, and return control to GDB.
4522 Like the `step' command, `reverse-step' will only stop at the
4523 beginning of a source line. It "un-executes" the previously
4524 executed source line. If the previous source line included calls
4525 to debuggable functions, `reverse-step' will step (backward) into
4526 the called function, stopping at the beginning of the _last_
4527 statement in the called function (typically a return statement).
4529 Also, as with the `step' command, if non-debuggable functions are
4530 called, `reverse-step' will run thru them backward without
4533 `reverse-stepi [COUNT]'
4534 Reverse-execute one machine instruction. Note that the instruction
4535 to be reverse-executed is _not_ the one pointed to by the program
4536 counter, but the instruction executed prior to that one. For
4537 instance, if the last instruction was a jump, `reverse-stepi' will
4538 take you back from the destination of the jump to the jump
4541 `reverse-next [COUNT]'
4542 Run backward to the beginning of the previous line executed in the
4543 current (innermost) stack frame. If the line contains function
4544 calls, they will be "un-executed" without stopping. Starting from
4545 the first line of a function, `reverse-next' will take you back to
4546 the caller of that function, _before_ the function was called,
4547 just as the normal `next' command would take you from the last
4548 line of a function back to its return to its caller (2).
4550 `reverse-nexti [COUNT]'
4551 Like `nexti', `reverse-nexti' executes a single instruction in
4552 reverse, except that called functions are "un-executed" atomically.
4553 That is, if the previously executed instruction was a return from
4554 another function, `reverse-nexti' will continue to execute in
4555 reverse until the call to that function (from the current stack
4559 Just as the `finish' command takes you to the point where the
4560 current function returns, `reverse-finish' takes you to the point
4561 where it was called. Instead of ending up at the end of the
4562 current function invocation, you end up at the beginning.
4564 `set exec-direction'
4565 Set the direction of target execution.
4567 `set exec-direction reverse'
4568 GDB will perform all execution commands in reverse, until the
4569 exec-direction mode is changed to "forward". Affected commands
4570 include `step, stepi, next, nexti, continue, and finish'. The
4571 `return' command cannot be used in reverse mode.
4573 `set exec-direction forward'
4574 GDB will perform all execution commands in the normal fashion.
4575 This is the default.
4577 ---------- Footnotes ----------
4579 (1) Note that some side effects are easier to undo than others. For
4580 instance, memory and registers are relatively easy, but device I/O is
4581 hard. Some targets may be able undo things like device I/O, and some
4584 The contract between GDB and the reverse executing target requires
4585 only that the target do something reasonable when GDB tells it to
4586 execute backwards, and then report the results back to GDB. Whatever
4587 the target reports back to GDB, GDB will report back to the user. GDB
4588 assumes that the memory and registers that the target reports are in a
4589 consistant state, but GDB accepts whatever it is given.
4591 (2) Unless the code is too heavily optimized.
4594 File: gdb.info, Node: Process Record and Replay, Next: Stack, Prev: Reverse Execution, Up: Top
4596 7 Recording Inferior's Execution and Replaying It
4597 *************************************************
4599 On some platforms, GDB provides a special "process record and replay"
4600 target that can record a log of the process execution, and replay it
4601 later with both forward and reverse execution commands.
4603 When this target is in use, if the execution log includes the record
4604 for the next instruction, GDB will debug in "replay mode". In the
4605 replay mode, the inferior does not really execute code instructions.
4606 Instead, all the events that normally happen during code execution are
4607 taken from the execution log. While code is not really executed in
4608 replay mode, the values of registers (including the program counter
4609 register) and the memory of the inferior are still changed as they
4610 normally would. Their contents are taken from the execution log.
4612 If the record for the next instruction is not in the execution log,
4613 GDB will debug in "record mode". In this mode, the inferior executes
4614 normally, and GDB records the execution log for future replay.
4616 The process record and replay target supports reverse execution
4617 (*note Reverse Execution::), even if the platform on which the inferior
4618 runs does not. However, the reverse execution is limited in this case
4619 by the range of the instructions recorded in the execution log. In
4620 other words, reverse execution on platforms that don't support it
4621 directly can only be done in the replay mode.
4623 When debugging in the reverse direction, GDB will work in replay
4624 mode as long as the execution log includes the record for the previous
4625 instruction; otherwise, it will work in record mode, if the platform
4626 supports reverse execution, or stop if not.
4628 For architecture environments that support process record and replay,
4629 GDB provides the following commands:
4632 This command starts the process record and replay target. The
4633 process record and replay target can only debug a process that is
4634 already running. Therefore, you need first to start the process
4635 with the `run' or `start' commands, and then start the recording
4636 with the `target record' command.
4638 Both `record' and `rec' are aliases of `target record'.
4640 Displaced stepping (*note displaced stepping: Maintenance
4641 Commands.) will be automatically disabled when process record and
4642 replay target is started. That's because the process record and
4643 replay target doesn't support displaced stepping.
4645 If the inferior is in the non-stop mode (*note Non-Stop Mode::) or
4646 in the asynchronous execution mode (*note Background Execution::),
4647 the process record and replay target cannot be started because it
4648 doesn't support these two modes.
4651 Stop the process record and replay target. When process record and
4652 replay target stops, the entire execution log will be deleted and
4653 the inferior will either be terminated, or will remain in its
4656 When you stop the process record and replay target in record mode
4657 (at the end of the execution log), the inferior will be stopped at
4658 the next instruction that would have been recorded. In other
4659 words, if you record for a while and then stop recording, the
4660 inferior process will be left in the same state as if the
4661 recording never happened.
4663 On the other hand, if the process record and replay target is
4664 stopped while in replay mode (that is, not at the end of the
4665 execution log, but at some earlier point), the inferior process
4666 will become "live" at that earlier state, and it will then be
4667 possible to continue the usual "live" debugging of the process
4670 When the inferior process exits, or GDB detaches from it, process
4671 record and replay target will automatically stop itself.
4673 `set record insn-number-max LIMIT'
4674 Set the limit of instructions to be recorded. Default value is
4677 If LIMIT is a positive number, then GDB will start deleting
4678 instructions from the log once the number of the record
4679 instructions becomes greater than LIMIT. For every new recorded
4680 instruction, GDB will delete the earliest recorded instruction to
4681 keep the number of recorded instructions at the limit. (Since
4682 deleting recorded instructions loses information, GDB lets you
4683 control what happens when the limit is reached, by means of the
4684 `stop-at-limit' option, described below.)
4686 If LIMIT is zero, GDB will never delete recorded instructions from
4687 the execution log. The number of recorded instructions is
4688 unlimited in this case.
4690 `show record insn-number-max'
4691 Show the limit of instructions to be recorded.
4693 `set record stop-at-limit'
4694 Control the behavior when the number of recorded instructions
4695 reaches the limit. If ON (the default), GDB will stop when the
4696 limit is reached for the first time and ask you whether you want
4697 to stop the inferior or continue running it and recording the
4698 execution log. If you decide to continue recording, each new
4699 recorded instruction will cause the oldest one to be deleted.
4701 If this option is OFF, GDB will automatically delete the oldest
4702 record to make room for each new one, without asking.
4704 `show record stop-at-limit'
4705 Show the current setting of `stop-at-limit'.
4708 Show various statistics about the state of process record and its
4709 in-memory execution log buffer, including:
4711 * Whether in record mode or replay mode.
4713 * Lowest recorded instruction number (counting from when the
4714 current execution log started recording instructions).
4716 * Highest recorded instruction number.
4718 * Current instruction about to be replayed (if in replay mode).
4720 * Number of instructions contained in the execution log.
4722 * Maximum number of instructions that may be contained in the
4726 When record target runs in replay mode ("in the past"), delete the
4727 subsequent execution log and begin to record a new execution log
4728 starting from the current address. This means you will abandon
4729 the previously recorded "future" and begin recording a new
4733 File: gdb.info, Node: Stack, Next: Source, Prev: Process Record and Replay, Up: Top
4735 8 Examining the Stack
4736 *********************
4738 When your program has stopped, the first thing you need to know is
4739 where it stopped and how it got there.
4741 Each time your program performs a function call, information about
4742 the call is generated. That information includes the location of the
4743 call in your program, the arguments of the call, and the local
4744 variables of the function being called. The information is saved in a
4745 block of data called a "stack frame". The stack frames are allocated
4746 in a region of memory called the "call stack".
4748 When your program stops, the GDB commands for examining the stack
4749 allow you to see all of this information.
4751 One of the stack frames is "selected" by GDB and many GDB commands
4752 refer implicitly to the selected frame. In particular, whenever you
4753 ask GDB for the value of a variable in your program, the value is found
4754 in the selected frame. There are special GDB commands to select
4755 whichever frame you are interested in. *Note Selecting a Frame:
4758 When your program stops, GDB automatically selects the currently
4759 executing frame and describes it briefly, similar to the `frame'
4760 command (*note Information about a Frame: Frame Info.).
4764 * Frames:: Stack frames
4765 * Backtrace:: Backtraces
4766 * Selection:: Selecting a frame
4767 * Frame Info:: Information on a frame
4770 File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack
4775 The call stack is divided up into contiguous pieces called "stack
4776 frames", or "frames" for short; each frame is the data associated with
4777 one call to one function. The frame contains the arguments given to
4778 the function, the function's local variables, and the address at which
4779 the function is executing.
4781 When your program is started, the stack has only one frame, that of
4782 the function `main'. This is called the "initial" frame or the
4783 "outermost" frame. Each time a function is called, a new frame is
4784 made. Each time a function returns, the frame for that function
4785 invocation is eliminated. If a function is recursive, there can be
4786 many frames for the same function. The frame for the function in which
4787 execution is actually occurring is called the "innermost" frame. This
4788 is the most recently created of all the stack frames that still exist.
4790 Inside your program, stack frames are identified by their addresses.
4791 A stack frame consists of many bytes, each of which has its own
4792 address; each kind of computer has a convention for choosing one byte
4793 whose address serves as the address of the frame. Usually this address
4794 is kept in a register called the "frame pointer register" (*note $fp:
4795 Registers.) while execution is going on in that frame.
4797 GDB assigns numbers to all existing stack frames, starting with zero
4798 for the innermost frame, one for the frame that called it, and so on
4799 upward. These numbers do not really exist in your program; they are
4800 assigned by GDB to give you a way of designating stack frames in GDB
4803 Some compilers provide a way to compile functions so that they
4804 operate without stack frames. (For example, the GCC option
4805 `-fomit-frame-pointer'
4806 generates functions without a frame.) This is occasionally done
4807 with heavily used library functions to save the frame setup time. GDB
4808 has limited facilities for dealing with these function invocations. If
4809 the innermost function invocation has no stack frame, GDB nevertheless
4810 regards it as though it had a separate frame, which is numbered zero as
4811 usual, allowing correct tracing of the function call chain. However,
4812 GDB has no provision for frameless functions elsewhere in the stack.
4815 The `frame' command allows you to move from one stack frame to
4816 another, and to print the stack frame you select. ARGS may be
4817 either the address of the frame or the stack frame number.
4818 Without an argument, `frame' prints the current stack frame.
4821 The `select-frame' command allows you to move from one stack frame
4822 to another without printing the frame. This is the silent version
4826 File: gdb.info, Node: Backtrace, Next: Selection, Prev: Frames, Up: Stack
4831 A backtrace is a summary of how your program got where it is. It shows
4832 one line per frame, for many frames, starting with the currently
4833 executing frame (frame zero), followed by its caller (frame one), and
4838 Print a backtrace of the entire stack: one line per frame for all
4839 frames in the stack.
4841 You can stop the backtrace at any time by typing the system
4842 interrupt character, normally `Ctrl-c'.
4846 Similar, but print only the innermost N frames.
4850 Similar, but print only the outermost N frames.
4856 Print the values of the local variables also. N specifies the
4857 number of frames to print, as described above.
4859 The names `where' and `info stack' (abbreviated `info s') are
4860 additional aliases for `backtrace'.
4862 In a multi-threaded program, GDB by default shows the backtrace only
4863 for the current thread. To display the backtrace for several or all of
4864 the threads, use the command `thread apply' (*note thread apply:
4865 Threads.). For example, if you type `thread apply all backtrace', GDB
4866 will display the backtrace for all the threads; this is handy when you
4867 debug a core dump of a multi-threaded program.
4869 Each line in the backtrace shows the frame number and the function
4870 name. The program counter value is also shown--unless you use `set
4871 print address off'. The backtrace also shows the source file name and
4872 line number, as well as the arguments to the function. The program
4873 counter value is omitted if it is at the beginning of the code for that
4876 Here is an example of a backtrace. It was made with the command `bt
4877 3', so it shows the innermost three frames.
4879 #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
4881 #1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242
4882 #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
4884 (More stack frames follow...)
4886 The display for frame zero does not begin with a program counter value,
4887 indicating that your program has stopped at the beginning of the code
4888 for line `993' of `builtin.c'.
4890 The value of parameter `data' in frame 1 has been replaced by `...'.
4891 By default, GDB prints the value of a parameter only if it is a scalar
4892 (integer, pointer, enumeration, etc). See command `set print
4893 frame-arguments' in *note Print Settings:: for more details on how to
4894 configure the way function parameter values are printed.
4896 If your program was compiled with optimizations, some compilers will
4897 optimize away arguments passed to functions if those arguments are
4898 never used after the call. Such optimizations generate code that
4899 passes arguments through registers, but doesn't store those arguments
4900 in the stack frame. GDB has no way of displaying such arguments in
4901 stack frames other than the innermost one. Here's what such a
4902 backtrace might look like:
4904 #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
4906 #1 0x6e38 in expand_macro (sym=<value optimized out>) at macro.c:242
4907 #2 0x6840 in expand_token (obs=0x0, t=<value optimized out>, td=0xf7fffb08)
4909 (More stack frames follow...)
4911 The values of arguments that were not saved in their stack frames are
4912 shown as `<value optimized out>'.
4914 If you need to display the values of such optimized-out arguments,
4915 either deduce that from other variables whose values depend on the one
4916 you are interested in, or recompile without optimizations.
4918 Most programs have a standard user entry point--a place where system
4919 libraries and startup code transition into user code. For C this is
4920 `main'(1). When GDB finds the entry function in a backtrace it will
4921 terminate the backtrace, to avoid tracing into highly system-specific
4922 (and generally uninteresting) code.
4924 If you need to examine the startup code, or limit the number of
4925 levels in a backtrace, you can change this behavior:
4927 `set backtrace past-main'
4928 `set backtrace past-main on'
4929 Backtraces will continue past the user entry point.
4931 `set backtrace past-main off'
4932 Backtraces will stop when they encounter the user entry point.
4933 This is the default.
4935 `show backtrace past-main'
4936 Display the current user entry point backtrace policy.
4938 `set backtrace past-entry'
4939 `set backtrace past-entry on'
4940 Backtraces will continue past the internal entry point of an
4941 application. This entry point is encoded by the linker when the
4942 application is built, and is likely before the user entry point
4943 `main' (or equivalent) is called.
4945 `set backtrace past-entry off'
4946 Backtraces will stop when they encounter the internal entry point
4947 of an application. This is the default.
4949 `show backtrace past-entry'
4950 Display the current internal entry point backtrace policy.
4952 `set backtrace limit N'
4953 `set backtrace limit 0'
4954 Limit the backtrace to N levels. A value of zero means unlimited.
4956 `show backtrace limit'
4957 Display the current limit on backtrace levels.
4959 ---------- Footnotes ----------
4961 (1) Note that embedded programs (the so-called "free-standing"
4962 environment) are not required to have a `main' function as the entry
4963 point. They could even have multiple entry points.
4966 File: gdb.info, Node: Selection, Next: Frame Info, Prev: Backtrace, Up: Stack
4968 8.3 Selecting a Frame
4969 =====================
4971 Most commands for examining the stack and other data in your program
4972 work on whichever stack frame is selected at the moment. Here are the
4973 commands for selecting a stack frame; all of them finish by printing a
4974 brief description of the stack frame just selected.
4978 Select frame number N. Recall that frame zero is the innermost
4979 (currently executing) frame, frame one is the frame that called the
4980 innermost one, and so on. The highest-numbered frame is the one
4985 Select the frame at address ADDR. This is useful mainly if the
4986 chaining of stack frames has been damaged by a bug, making it
4987 impossible for GDB to assign numbers properly to all frames. In
4988 addition, this can be useful when your program has multiple stacks
4989 and switches between them.
4991 On the SPARC architecture, `frame' needs two addresses to select
4992 an arbitrary frame: a frame pointer and a stack pointer.
4994 On the MIPS and Alpha architecture, it needs two addresses: a stack
4995 pointer and a program counter.
4997 On the 29k architecture, it needs three addresses: a register stack
4998 pointer, a program counter, and a memory stack pointer.
5001 Move N frames up the stack. For positive numbers N, this advances
5002 toward the outermost frame, to higher frame numbers, to frames
5003 that have existed longer. N defaults to one.
5006 Move N frames down the stack. For positive numbers N, this
5007 advances toward the innermost frame, to lower frame numbers, to
5008 frames that were created more recently. N defaults to one. You
5009 may abbreviate `down' as `do'.
5011 All of these commands end by printing two lines of output describing
5012 the frame. The first line shows the frame number, the function name,
5013 the arguments, and the source file and line number of execution in that
5014 frame. The second line shows the text of that source line.
5019 #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
5021 10 read_input_file (argv[i]);
5023 After such a printout, the `list' command with no arguments prints
5024 ten lines centered on the point of execution in the frame. You can
5025 also edit the program at the point of execution with your favorite
5026 editing program by typing `edit'. *Note Printing Source Lines: List,
5031 These two commands are variants of `up' and `down', respectively;
5032 they differ in that they do their work silently, without causing
5033 display of the new frame. They are intended primarily for use in
5034 GDB command scripts, where the output might be unnecessary and
5038 File: gdb.info, Node: Frame Info, Prev: Selection, Up: Stack
5040 8.4 Information About a Frame
5041 =============================
5043 There are several other commands to print information about the selected
5048 When used without any argument, this command does not change which
5049 frame is selected, but prints a brief description of the currently
5050 selected stack frame. It can be abbreviated `f'. With an
5051 argument, this command is used to select a stack frame. *Note
5052 Selecting a Frame: Selection.
5056 This command prints a verbose description of the selected stack
5059 * the address of the frame
5061 * the address of the next frame down (called by this frame)
5063 * the address of the next frame up (caller of this frame)
5065 * the language in which the source code corresponding to this
5068 * the address of the frame's arguments
5070 * the address of the frame's local variables
5072 * the program counter saved in it (the address of execution in
5075 * which registers were saved in the frame
5077 The verbose description is useful when something has gone wrong
5078 that has made the stack format fail to fit the usual conventions.
5082 Print a verbose description of the frame at address ADDR, without
5083 selecting that frame. The selected frame remains unchanged by this
5084 command. This requires the same kind of address (more than one
5085 for some architectures) that you specify in the `frame' command.
5086 *Note Selecting a Frame: Selection.
5089 Print the arguments of the selected frame, each on a separate line.
5092 Print the local variables of the selected frame, each on a separate
5093 line. These are all variables (declared either static or
5094 automatic) accessible at the point of execution of the selected
5098 Print a list of all the exception handlers that are active in the
5099 current stack frame at the current point of execution. To see
5100 other exception handlers, visit the associated frame (using the
5101 `up', `down', or `frame' commands); then type `info catch'. *Note
5102 Setting Catchpoints: Set Catchpoints.
5106 File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top
5108 9 Examining Source Files
5109 ************************
5111 GDB can print parts of your program's source, since the debugging
5112 information recorded in the program tells GDB what source files were
5113 used to build it. When your program stops, GDB spontaneously prints
5114 the line where it stopped. Likewise, when you select a stack frame
5115 (*note Selecting a Frame: Selection.), GDB prints the line where
5116 execution in that frame has stopped. You can print other portions of
5117 source files by explicit command.
5119 If you use GDB through its GNU Emacs interface, you may prefer to
5120 use Emacs facilities to view source; see *note Using GDB under GNU
5125 * List:: Printing source lines
5126 * Specify Location:: How to specify code locations
5127 * Edit:: Editing source files
5128 * Search:: Searching source files
5129 * Source Path:: Specifying source directories
5130 * Machine Code:: Source and machine code
5133 File: gdb.info, Node: List, Next: Specify Location, Up: Source
5135 9.1 Printing Source Lines
5136 =========================
5138 To print lines from a source file, use the `list' command (abbreviated
5139 `l'). By default, ten lines are printed. There are several ways to
5140 specify what part of the file you want to print; see *note Specify
5141 Location::, for the full list.
5143 Here are the forms of the `list' command most commonly used:
5146 Print lines centered around line number LINENUM in the current
5150 Print lines centered around the beginning of function FUNCTION.
5153 Print more lines. If the last lines printed were printed with a
5154 `list' command, this prints lines following the last lines
5155 printed; however, if the last line printed was a solitary line
5156 printed as part of displaying a stack frame (*note Examining the
5157 Stack: Stack.), this prints lines centered around that line.
5160 Print lines just before the lines last printed.
5162 By default, GDB prints ten source lines with any of these forms of
5163 the `list' command. You can change this using `set listsize':
5165 `set listsize COUNT'
5166 Make the `list' command display COUNT source lines (unless the
5167 `list' argument explicitly specifies some other number).
5170 Display the number of lines that `list' prints.
5172 Repeating a `list' command with <RET> discards the argument, so it
5173 is equivalent to typing just `list'. This is more useful than listing
5174 the same lines again. An exception is made for an argument of `-';
5175 that argument is preserved in repetition so that each repetition moves
5176 up in the source file.
5178 In general, the `list' command expects you to supply zero, one or two
5179 "linespecs". Linespecs specify source lines; there are several ways of
5180 writing them (*note Specify Location::), but the effect is always to
5181 specify some source line.
5183 Here is a complete description of the possible arguments for `list':
5186 Print lines centered around the line specified by LINESPEC.
5189 Print lines from FIRST to LAST. Both arguments are linespecs.
5190 When a `list' command has two linespecs, and the source file of
5191 the second linespec is omitted, this refers to the same source
5192 file as the first linespec.
5195 Print lines ending with LAST.
5198 Print lines starting with FIRST.
5201 Print lines just after the lines last printed.
5204 Print lines just before the lines last printed.
5207 As described in the preceding table.
5210 File: gdb.info, Node: Specify Location, Next: Edit, Prev: List, Up: Source
5212 9.2 Specifying a Location
5213 =========================
5215 Several GDB commands accept arguments that specify a location of your
5216 program's code. Since GDB is a source-level debugger, a location
5217 usually specifies some line in the source code; for that reason,
5218 locations are also known as "linespecs".
5220 Here are all the different ways of specifying a code location that
5224 Specifies the line number LINENUM of the current source file.
5228 Specifies the line OFFSET lines before or after the "current
5229 line". For the `list' command, the current line is the last one
5230 printed; for the breakpoint commands, this is the line at which
5231 execution stopped in the currently selected "stack frame" (*note
5232 Frames: Frames, for a description of stack frames.) When used as
5233 the second of the two linespecs in a `list' command, this
5234 specifies the line OFFSET lines up or down from the first linespec.
5237 Specifies the line LINENUM in the source file FILENAME.
5240 Specifies the line that begins the body of the function FUNCTION.
5241 For example, in C, this is the line with the open brace.
5244 Specifies the line that begins the body of the function FUNCTION
5245 in the file FILENAME. You only need the file name with a function
5246 name to avoid ambiguity when there are identically named functions
5247 in different source files.
5250 Specifies the program address ADDRESS. For line-oriented
5251 commands, such as `list' and `edit', this specifies a source line
5252 that contains ADDRESS. For `break' and other breakpoint oriented
5253 commands, this can be used to set breakpoints in parts of your
5254 program which do not have debugging information or source files.
5256 Here ADDRESS may be any expression valid in the current working
5257 language (*note working language: Languages.) that specifies a code
5258 address. In addition, as a convenience, GDB extends the semantics
5259 of expressions used in locations to cover the situations that
5260 frequently happen during debugging. Here are the various forms of
5264 Any expression valid in the current working language.
5267 An address of a function or procedure derived from its name.
5268 In C, C++, Java, Objective-C, Fortran, minimal, and assembly,
5269 this is simply the function's name FUNCTION (and actually a
5270 special case of a valid expression). In Pascal and Modula-2,
5271 this is `&FUNCTION'. In Ada, this is `FUNCTION'Address'
5272 (although the Pascal form also works).
5274 This form specifies the address of the function's first
5275 instruction, before the stack frame and arguments have been
5278 `'FILENAME'::FUNCADDR'
5279 Like FUNCADDR above, but also specifies the name of the source
5280 file explicitly. This is useful if the name of the function
5281 does not specify the function unambiguously, e.g., if there
5282 are several functions with identical names in different
5287 File: gdb.info, Node: Edit, Next: Search, Prev: Specify Location, Up: Source
5289 9.3 Editing Source Files
5290 ========================
5292 To edit the lines in a source file, use the `edit' command. The
5293 editing program of your choice is invoked with the current line set to
5294 the active line in the program. Alternatively, there are several ways
5295 to specify what part of the file you want to print if you want to see
5296 other parts of the program:
5299 Edit the source file specified by `location'. Editing starts at
5300 that LOCATION, e.g., at the specified source line of the specified
5301 file. *Note Specify Location::, for all the possible forms of the
5302 LOCATION argument; here are the forms of the `edit' command most
5306 Edit the current source file with NUMBER as the active line
5310 Edit the file containing FUNCTION at the beginning of its
5314 9.3.1 Choosing your Editor
5315 --------------------------
5317 You can customize GDB to use any editor you want (1). By default, it
5318 is `/bin/ex', but you can change this by setting the environment
5319 variable `EDITOR' before using GDB. For example, to configure GDB to
5320 use the `vi' editor, you could use these commands with the `sh' shell:
5324 or in the `csh' shell,
5325 setenv EDITOR /usr/bin/vi
5328 ---------- Footnotes ----------
5330 (1) The only restriction is that your editor (say `ex'), recognizes
5331 the following command-line syntax:
5333 The optional numeric value +NUMBER specifies the number of the line
5334 in the file where to start editing.
5337 File: gdb.info, Node: Search, Next: Source Path, Prev: Edit, Up: Source
5339 9.4 Searching Source Files
5340 ==========================
5342 There are two commands for searching through the current source file
5343 for a regular expression.
5345 `forward-search REGEXP'
5347 The command `forward-search REGEXP' checks each line, starting
5348 with the one following the last line listed, for a match for
5349 REGEXP. It lists the line that is found. You can use the synonym
5350 `search REGEXP' or abbreviate the command name as `fo'.
5352 `reverse-search REGEXP'
5353 The command `reverse-search REGEXP' checks each line, starting
5354 with the one before the last line listed and going backward, for a
5355 match for REGEXP. It lists the line that is found. You can
5356 abbreviate this command as `rev'.
5359 File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source
5361 9.5 Specifying Source Directories
5362 =================================
5364 Executable programs sometimes do not record the directories of the
5365 source files from which they were compiled, just the names. Even when
5366 they do, the directories could be moved between the compilation and
5367 your debugging session. GDB has a list of directories to search for
5368 source files; this is called the "source path". Each time GDB wants a
5369 source file, it tries all the directories in the list, in the order
5370 they are present in the list, until it finds a file with the desired
5373 For example, suppose an executable references the file
5374 `/usr/src/foo-1.0/lib/foo.c', and our source path is `/mnt/cross'. The
5375 file is first looked up literally; if this fails,
5376 `/mnt/cross/usr/src/foo-1.0/lib/foo.c' is tried; if this fails,
5377 `/mnt/cross/foo.c' is opened; if this fails, an error message is
5378 printed. GDB does not look up the parts of the source file name, such
5379 as `/mnt/cross/src/foo-1.0/lib/foo.c'. Likewise, the subdirectories of
5380 the source path are not searched: if the source path is `/mnt/cross',
5381 and the binary refers to `foo.c', GDB would not find it under
5382 `/mnt/cross/usr/src/foo-1.0/lib'.
5384 Plain file names, relative file names with leading directories, file
5385 names containing dots, etc. are all treated as described above; for
5386 instance, if the source path is `/mnt/cross', and the source file is
5387 recorded as `../lib/foo.c', GDB would first try `../lib/foo.c', then
5388 `/mnt/cross/../lib/foo.c', and after that--`/mnt/cross/foo.c'.
5390 Note that the executable search path is _not_ used to locate the
5393 Whenever you reset or rearrange the source path, GDB clears out any
5394 information it has cached about where source files are found and where
5395 each line is in the file.
5397 When you start GDB, its source path includes only `cdir' and `cwd',
5398 in that order. To add other directories, use the `directory' command.
5400 The search path is used to find both program source files and GDB
5401 script files (read using the `-command' option and `source' command).
5403 In addition to the source path, GDB provides a set of commands that
5404 manage a list of source path substitution rules. A "substitution rule"
5405 specifies how to rewrite source directories stored in the program's
5406 debug information in case the sources were moved to a different
5407 directory between compilation and debugging. A rule is made of two
5408 strings, the first specifying what needs to be rewritten in the path,
5409 and the second specifying how it should be rewritten. In *note set
5410 substitute-path::, we name these two parts FROM and TO respectively.
5411 GDB does a simple string replacement of FROM with TO at the start of
5412 the directory part of the source file name, and uses that result
5413 instead of the original file name to look up the sources.
5415 Using the previous example, suppose the `foo-1.0' tree has been
5416 moved from `/usr/src' to `/mnt/cross', then you can tell GDB to replace
5417 `/usr/src' in all source path names with `/mnt/cross'. The first
5418 lookup will then be `/mnt/cross/foo-1.0/lib/foo.c' in place of the
5419 original location of `/usr/src/foo-1.0/lib/foo.c'. To define a source
5420 path substitution rule, use the `set substitute-path' command (*note
5421 set substitute-path::).
5423 To avoid unexpected substitution results, a rule is applied only if
5424 the FROM part of the directory name ends at a directory separator. For
5425 instance, a rule substituting `/usr/source' into `/mnt/cross' will be
5426 applied to `/usr/source/foo-1.0' but not to `/usr/sourceware/foo-2.0'.
5427 And because the substitution is applied only at the beginning of the
5428 directory name, this rule will not be applied to
5429 `/root/usr/source/baz.c' either.
5431 In many cases, you can achieve the same result using the `directory'
5432 command. However, `set substitute-path' can be more efficient in the
5433 case where the sources are organized in a complex tree with multiple
5434 subdirectories. With the `directory' command, you need to add each
5435 subdirectory of your project. If you moved the entire tree while
5436 preserving its internal organization, then `set substitute-path' allows
5437 you to direct the debugger to all the sources with one single command.
5439 `set substitute-path' is also more than just a shortcut command.
5440 The source path is only used if the file at the original location no
5441 longer exists. On the other hand, `set substitute-path' modifies the
5442 debugger behavior to look at the rewritten location instead. So, if
5443 for any reason a source file that is not relevant to your executable is
5444 located at the original location, a substitution rule is the only
5445 method available to point GDB at the new location.
5447 You can configure a default source path substitution rule by
5448 configuring GDB with the `--with-relocated-sources=DIR' option. The DIR
5449 should be the name of a directory under GDB's configured prefix (set
5450 with `--prefix' or `--exec-prefix'), and directory names in debug
5451 information under DIR will be adjusted automatically if the installed
5452 GDB is moved to a new location. This is useful if GDB, libraries or
5453 executables with debug information and corresponding source code are
5454 being moved together.
5456 `directory DIRNAME ...'
5459 Add directory DIRNAME to the front of the source path. Several
5460 directory names may be given to this command, separated by `:'
5461 (`;' on MS-DOS and MS-Windows, where `:' usually appears as part
5462 of absolute file names) or whitespace. You may specify a
5463 directory that is already in the source path; this moves it
5464 forward, so GDB searches it sooner.
5466 You can use the string `$cdir' to refer to the compilation
5467 directory (if one is recorded), and `$cwd' to refer to the current
5468 working directory. `$cwd' is not the same as `.'--the former
5469 tracks the current working directory as it changes during your GDB
5470 session, while the latter is immediately expanded to the current
5471 directory at the time you add an entry to the source path.
5474 Reset the source path to its default value (`$cdir:$cwd' on Unix
5475 systems). This requires confirmation.
5478 Print the source path: show which directories it contains.
5480 `set substitute-path FROM TO'
5481 Define a source path substitution rule, and add it at the end of
5482 the current list of existing substitution rules. If a rule with
5483 the same FROM was already defined, then the old rule is also
5486 For example, if the file `/foo/bar/baz.c' was moved to
5487 `/mnt/cross/baz.c', then the command
5489 (gdb) set substitute-path /usr/src /mnt/cross
5491 will tell GDB to replace `/usr/src' with `/mnt/cross', which will
5492 allow GDB to find the file `baz.c' even though it was moved.
5494 In the case when more than one substitution rule have been defined,
5495 the rules are evaluated one by one in the order where they have
5496 been defined. The first one matching, if any, is selected to
5497 perform the substitution.
5499 For instance, if we had entered the following commands:
5501 (gdb) set substitute-path /usr/src/include /mnt/include
5502 (gdb) set substitute-path /usr/src /mnt/src
5504 GDB would then rewrite `/usr/src/include/defs.h' into
5505 `/mnt/include/defs.h' by using the first rule. However, it would
5506 use the second rule to rewrite `/usr/src/lib/foo.c' into
5507 `/mnt/src/lib/foo.c'.
5509 `unset substitute-path [path]'
5510 If a path is specified, search the current list of substitution
5511 rules for a rule that would rewrite that path. Delete that rule
5512 if found. A warning is emitted by the debugger if no rule could
5515 If no path is specified, then all substitution rules are deleted.
5517 `show substitute-path [path]'
5518 If a path is specified, then print the source path substitution
5519 rule which would rewrite that path, if any.
5521 If no path is specified, then print all existing source path
5525 If your source path is cluttered with directories that are no longer
5526 of interest, GDB may sometimes cause confusion by finding the wrong
5527 versions of source. You can correct the situation as follows:
5529 1. Use `directory' with no argument to reset the source path to its
5532 2. Use `directory' with suitable arguments to reinstall the
5533 directories you want in the source path. You can add all the
5534 directories in one command.
5537 File: gdb.info, Node: Machine Code, Prev: Source Path, Up: Source
5539 9.6 Source and Machine Code
5540 ===========================
5542 You can use the command `info line' to map source lines to program
5543 addresses (and vice versa), and the command `disassemble' to display a
5544 range of addresses as machine instructions. You can use the command
5545 `set disassemble-next-line' to set whether to disassemble next source
5546 line when execution stops. When run under GNU Emacs mode, the `info
5547 line' command causes the arrow to point to the line specified. Also,
5548 `info line' prints addresses in symbolic form as well as hex.
5550 `info line LINESPEC'
5551 Print the starting and ending addresses of the compiled code for
5552 source line LINESPEC. You can specify source lines in any of the
5553 ways documented in *note Specify Location::.
5555 For example, we can use `info line' to discover the location of the
5556 object code for the first line of function `m4_changequote':
5558 (gdb) info line m4_changequote
5559 Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
5561 We can also inquire (using `*ADDR' as the form for LINESPEC) what
5562 source line covers a particular address:
5563 (gdb) info line *0x63ff
5564 Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
5566 After `info line', the default address for the `x' command is
5567 changed to the starting address of the line, so that `x/i' is
5568 sufficient to begin examining the machine code (*note Examining Memory:
5569 Memory.). Also, this address is saved as the value of the convenience
5570 variable `$_' (*note Convenience Variables: Convenience Vars.).
5575 This specialized command dumps a range of memory as machine
5576 instructions. It can also print mixed source+disassembly by
5577 specifying the `/m' modifier and print the raw instructions in hex
5578 as well as in symbolic form by specifying the `/r'. The default
5579 memory range is the function surrounding the program counter of
5580 the selected frame. A single argument to this command is a
5581 program counter value; GDB dumps the function surrounding this
5582 value. When two arguments are given, they should be separated by
5583 a comma, possibly surrounded by whitespace. The arguments specify
5584 a range of addresses (first inclusive, second exclusive) to dump.
5585 In that case, the name of the function is also printed (since
5586 there could be several functions in the given range).
5588 The argument(s) can be any expression yielding a numeric value,
5589 such as `0x32c4', `&main+10' or `$pc - 8'.
5591 If the range of memory being disassembled contains current program
5592 counter, the instruction at that location is shown with a `=>'
5595 The following example shows the disassembly of a range of addresses
5596 of HP PA-RISC 2.0 code:
5598 (gdb) disas 0x32c4, 0x32e4
5599 Dump of assembler code from 0x32c4 to 0x32e4:
5600 0x32c4 <main+204>: addil 0,dp
5601 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26
5602 0x32cc <main+212>: ldil 0x3000,r31
5603 0x32d0 <main+216>: ble 0x3f8(sr4,r31)
5604 0x32d4 <main+220>: ldo 0(r31),rp
5605 0x32d8 <main+224>: addil -0x800,dp
5606 0x32dc <main+228>: ldo 0x588(r1),r26
5607 0x32e0 <main+232>: ldil 0x3000,r31
5608 End of assembler dump.
5610 Here is an example showing mixed source+assembly for Intel x86, when
5611 the program is stopped just after function prologue:
5614 Dump of assembler code for function main:
5616 0x08048330 <+0>: push %ebp
5617 0x08048331 <+1>: mov %esp,%ebp
5618 0x08048333 <+3>: sub $0x8,%esp
5619 0x08048336 <+6>: and $0xfffffff0,%esp
5620 0x08048339 <+9>: sub $0x10,%esp
5622 6 printf ("Hello.\n");
5623 => 0x0804833c <+12>: movl $0x8048440,(%esp)
5624 0x08048343 <+19>: call 0x8048284 <puts@plt>
5628 0x08048348 <+24>: mov $0x0,%eax
5629 0x0804834d <+29>: leave
5630 0x0804834e <+30>: ret
5632 End of assembler dump.
5634 Some architectures have more than one commonly-used set of
5635 instruction mnemonics or other syntax.
5637 For programs that were dynamically linked and use shared libraries,
5638 instructions that call functions or branch to locations in the shared
5639 libraries might show a seemingly bogus location--it's actually a
5640 location of the relocation table. On some architectures, GDB might be
5641 able to resolve these to actual function names.
5643 `set disassembly-flavor INSTRUCTION-SET'
5644 Select the instruction set to use when disassembling the program
5645 via the `disassemble' or `x/i' commands.
5647 Currently this command is only defined for the Intel x86 family.
5648 You can set INSTRUCTION-SET to either `intel' or `att'. The
5649 default is `att', the AT&T flavor used by default by Unix
5650 assemblers for x86-based targets.
5652 `show disassembly-flavor'
5653 Show the current setting of the disassembly flavor.
5655 `set disassemble-next-line'
5656 `show disassemble-next-line'
5657 Control whether or not GDB will disassemble the next source line
5658 or instruction when execution stops. If ON, GDB will display
5659 disassembly of the next source line when execution of the program
5660 being debugged stops. This is _in addition_ to displaying the
5661 source line itself, which GDB always does if possible. If the
5662 next source line cannot be displayed for some reason (e.g., if GDB
5663 cannot find the source file, or there's no line info in the debug
5664 info), GDB will display disassembly of the next _instruction_
5665 instead of showing the next source line. If AUTO, GDB will
5666 display disassembly of next instruction only if the source line
5667 cannot be displayed. This setting causes GDB to display some
5668 feedback when you step through a function with no line info or
5669 whose source file is unavailable. The default is OFF, which means
5670 never display the disassembly of the next line or instruction.
5673 File: gdb.info, Node: Data, Next: Optimized Code, Prev: Source, Up: Top
5678 The usual way to examine data in your program is with the `print'
5679 command (abbreviated `p'), or its synonym `inspect'. It evaluates and
5680 prints the value of an expression of the language your program is
5681 written in (*note Using GDB with Different Languages: Languages.).
5685 EXPR is an expression (in the source language). By default the
5686 value of EXPR is printed in a format appropriate to its data type;
5687 you can choose a different format by specifying `/F', where F is a
5688 letter specifying the format; see *note Output Formats: Output
5693 If you omit EXPR, GDB displays the last value again (from the
5694 "value history"; *note Value History: Value History.). This
5695 allows you to conveniently inspect the same value in an
5698 A more low-level way of examining data is with the `x' command. It
5699 examines data in memory at a specified address and prints it in a
5700 specified format. *Note Examining Memory: Memory.
5702 If you are interested in information about types, or about how the
5703 fields of a struct or a class are declared, use the `ptype EXP' command
5704 rather than `print'. *Note Examining the Symbol Table: Symbols.
5708 * Expressions:: Expressions
5709 * Ambiguous Expressions:: Ambiguous Expressions
5710 * Variables:: Program variables
5711 * Arrays:: Artificial arrays
5712 * Output Formats:: Output formats
5713 * Memory:: Examining memory
5714 * Auto Display:: Automatic display
5715 * Print Settings:: Print settings
5716 * Value History:: Value history
5717 * Convenience Vars:: Convenience variables
5718 * Registers:: Registers
5719 * Floating Point Hardware:: Floating point hardware
5720 * Vector Unit:: Vector Unit
5721 * OS Information:: Auxiliary data provided by operating system
5722 * Memory Region Attributes:: Memory region attributes
5723 * Dump/Restore Files:: Copy between memory and a file
5724 * Core File Generation:: Cause a program dump its core
5725 * Character Sets:: Debugging programs that use a different
5726 character set than GDB does
5727 * Caching Remote Data:: Data caching for remote targets
5728 * Searching Memory:: Searching memory for a sequence of bytes
5731 File: gdb.info, Node: Expressions, Next: Ambiguous Expressions, Up: Data
5736 `print' and many other GDB commands accept an expression and compute
5737 its value. Any kind of constant, variable or operator defined by the
5738 programming language you are using is valid in an expression in GDB.
5739 This includes conditional expressions, function calls, casts, and
5740 string constants. It also includes preprocessor macros, if you
5741 compiled your program to include this information; see *note
5744 GDB supports array constants in expressions input by the user. The
5745 syntax is {ELEMENT, ELEMENT...}. For example, you can use the command
5746 `print {1, 2, 3}' to create an array of three integers. If you pass an
5747 array to a function or assign it to a program variable, GDB copies the
5748 array to memory that is `malloc'ed in the target program.
5750 Because C is so widespread, most of the expressions shown in
5751 examples in this manual are in C. *Note Using GDB with Different
5752 Languages: Languages, for information on how to use expressions in other
5755 In this section, we discuss operators that you can use in GDB
5756 expressions regardless of your programming language.
5758 Casts are supported in all languages, not just in C, because it is so
5759 useful to cast a number into a pointer in order to examine a structure
5760 at that address in memory.
5762 GDB supports these operators, in addition to those common to
5763 programming languages:
5766 `@' is a binary operator for treating parts of memory as arrays.
5767 *Note Artificial Arrays: Arrays, for more information.
5770 `::' allows you to specify a variable in terms of the file or
5771 function where it is defined. *Note Program Variables: Variables.
5774 Refers to an object of type TYPE stored at address ADDR in memory.
5775 ADDR may be any expression whose value is an integer or pointer
5776 (but parentheses are required around binary operators, just as in
5777 a cast). This construct is allowed regardless of what kind of
5778 data is normally supposed to reside at ADDR.
5781 File: gdb.info, Node: Ambiguous Expressions, Next: Variables, Prev: Expressions, Up: Data
5783 10.2 Ambiguous Expressions
5784 ==========================
5786 Expressions can sometimes contain some ambiguous elements. For
5787 instance, some programming languages (notably Ada, C++ and Objective-C)
5788 permit a single function name to be defined several times, for
5789 application in different contexts. This is called "overloading".
5790 Another example involving Ada is generics. A "generic package" is
5791 similar to C++ templates and is typically instantiated several times,
5792 resulting in the same function name being defined in different contexts.
5794 In some cases and depending on the language, it is possible to adjust
5795 the expression to remove the ambiguity. For instance in C++, you can
5796 specify the signature of the function you want to break on, as in
5797 `break FUNCTION(TYPES)'. In Ada, using the fully qualified name of
5798 your function often makes the expression unambiguous as well.
5800 When an ambiguity that needs to be resolved is detected, the debugger
5801 has the capability to display a menu of numbered choices for each
5802 possibility, and then waits for the selection with the prompt `>'. The
5803 first option is always `[0] cancel', and typing `0 <RET>' aborts the
5804 current command. If the command in which the expression was used
5805 allows more than one choice to be selected, the next option in the menu
5806 is `[1] all', and typing `1 <RET>' selects all possible choices.
5808 For example, the following session excerpt shows an attempt to set a
5809 breakpoint at the overloaded symbol `String::after'. We choose three
5810 particular definitions of that function name:
5812 (gdb) b String::after
5815 [2] file:String.cc; line number:867
5816 [3] file:String.cc; line number:860
5817 [4] file:String.cc; line number:875
5818 [5] file:String.cc; line number:853
5819 [6] file:String.cc; line number:846
5820 [7] file:String.cc; line number:735
5822 Breakpoint 1 at 0xb26c: file String.cc, line 867.
5823 Breakpoint 2 at 0xb344: file String.cc, line 875.
5824 Breakpoint 3 at 0xafcc: file String.cc, line 846.
5825 Multiple breakpoints were set.
5826 Use the "delete" command to delete unwanted
5830 `set multiple-symbols MODE'
5831 This option allows you to adjust the debugger behavior when an
5832 expression is ambiguous.
5834 By default, MODE is set to `all'. If the command with which the
5835 expression is used allows more than one choice, then GDB
5836 automatically selects all possible choices. For instance,
5837 inserting a breakpoint on a function using an ambiguous name
5838 results in a breakpoint inserted on each possible match. However,
5839 if a unique choice must be made, then GDB uses the menu to help
5840 you disambiguate the expression. For instance, printing the
5841 address of an overloaded function will result in the use of the
5844 When MODE is set to `ask', the debugger always uses the menu when
5845 an ambiguity is detected.
5847 Finally, when MODE is set to `cancel', the debugger reports an
5848 error due to the ambiguity and the command is aborted.
5850 `show multiple-symbols'
5851 Show the current value of the `multiple-symbols' setting.
5854 File: gdb.info, Node: Variables, Next: Arrays, Prev: Ambiguous Expressions, Up: Data
5856 10.3 Program Variables
5857 ======================
5859 The most common kind of expression to use is the name of a variable in
5862 Variables in expressions are understood in the selected stack frame
5863 (*note Selecting a Frame: Selection.); they must be either:
5865 * global (or file-static)
5869 * visible according to the scope rules of the programming language
5870 from the point of execution in that frame
5872 This means that in the function
5884 you can examine and use the variable `a' whenever your program is
5885 executing within the function `foo', but you can only use or examine
5886 the variable `b' while your program is executing inside the block where
5889 There is an exception: you can refer to a variable or function whose
5890 scope is a single source file even if the current execution point is not
5891 in this file. But it is possible to have more than one such variable or
5892 function with the same name (in different source files). If that
5893 happens, referring to that name has unpredictable effects. If you wish,
5894 you can specify a static variable in a particular function or file,
5895 using the colon-colon (`::') notation:
5900 Here FILE or FUNCTION is the name of the context for the static
5901 VARIABLE. In the case of file names, you can use quotes to make sure
5902 GDB parses the file name as a single word--for example, to print a
5903 global value of `x' defined in `f2.c':
5907 This use of `::' is very rarely in conflict with the very similar
5908 use of the same notation in C++. GDB also supports use of the C++
5909 scope resolution operator in GDB expressions.
5911 _Warning:_ Occasionally, a local variable may appear to have the
5912 wrong value at certain points in a function--just after entry to a
5913 new scope, and just before exit.
5914 You may see this problem when you are stepping by machine
5915 instructions. This is because, on most machines, it takes more than
5916 one instruction to set up a stack frame (including local variable
5917 definitions); if you are stepping by machine instructions, variables
5918 may appear to have the wrong values until the stack frame is completely
5919 built. On exit, it usually also takes more than one machine
5920 instruction to destroy a stack frame; after you begin stepping through
5921 that group of instructions, local variable definitions may be gone.
5923 This may also happen when the compiler does significant
5924 optimizations. To be sure of always seeing accurate values, turn off
5925 all optimization when compiling.
5927 Another possible effect of compiler optimizations is to optimize
5928 unused variables out of existence, or assign variables to registers (as
5929 opposed to memory addresses). Depending on the support for such cases
5930 offered by the debug info format used by the compiler, GDB might not be
5931 able to display values for such local variables. If that happens, GDB
5932 will print a message like this:
5934 No symbol "foo" in current context.
5936 To solve such problems, either recompile without optimizations, or
5937 use a different debug info format, if the compiler supports several such
5938 formats. For example, GCC, the GNU C/C++ compiler, usually supports
5939 the `-gstabs+' option. `-gstabs+' produces debug info in a format that
5940 is superior to formats such as COFF. You may be able to use DWARF 2
5941 (`-gdwarf-2'), which is also an effective form for debug info. *Note
5942 Options for Debugging Your Program or GCC: (gcc.info)Debugging Options.
5943 *Note C and C++: C, for more information about debug info formats that
5944 are best suited to C++ programs.
5946 If you ask to print an object whose contents are unknown to GDB,
5947 e.g., because its data type is not completely specified by the debug
5948 information, GDB will say `<incomplete type>'. *Note incomplete type:
5949 Symbols, for more about this.
5951 Strings are identified as arrays of `char' values without specified
5952 signedness. Arrays of either `signed char' or `unsigned char' get
5953 printed as arrays of 1 byte sized integers. `-fsigned-char' or
5954 `-funsigned-char' GCC options have no effect as GDB defines literal
5955 string type `"char"' as `char' without a sign. For program code
5958 signed char var1[] = "A";
5960 You get during debugging
5964 $2 = {65 'A', 0 '\0'}
5967 File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data
5969 10.4 Artificial Arrays
5970 ======================
5972 It is often useful to print out several successive objects of the same
5973 type in memory; a section of an array, or an array of dynamically
5974 determined size for which only a pointer exists in the program.
5976 You can do this by referring to a contiguous span of memory as an
5977 "artificial array", using the binary operator `@'. The left operand of
5978 `@' should be the first element of the desired array and be an
5979 individual object. The right operand should be the desired length of
5980 the array. The result is an array value whose elements are all of the
5981 type of the left argument. The first element is actually the left
5982 argument; the second element comes from bytes of memory immediately
5983 following those that hold the first element, and so on. Here is an
5984 example. If a program says
5986 int *array = (int *) malloc (len * sizeof (int));
5988 you can print the contents of `array' with
5992 The left operand of `@' must reside in memory. Array values made
5993 with `@' in this way behave just like other arrays in terms of
5994 subscripting, and are coerced to pointers when used in expressions.
5995 Artificial arrays most often appear in expressions via the value history
5996 (*note Value History: Value History.), after printing one out.
5998 Another way to create an artificial array is to use a cast. This
5999 re-interprets a value as if it were an array. The value need not be in
6001 (gdb) p/x (short[2])0x12345678
6002 $1 = {0x1234, 0x5678}
6004 As a convenience, if you leave the array length out (as in
6005 `(TYPE[])VALUE') GDB calculates the size to fill the value (as
6006 `sizeof(VALUE)/sizeof(TYPE)':
6007 (gdb) p/x (short[])0x12345678
6008 $2 = {0x1234, 0x5678}
6010 Sometimes the artificial array mechanism is not quite enough; in
6011 moderately complex data structures, the elements of interest may not
6012 actually be adjacent--for example, if you are interested in the values
6013 of pointers in an array. One useful work-around in this situation is
6014 to use a convenience variable (*note Convenience Variables: Convenience
6015 Vars.) as a counter in an expression that prints the first interesting
6016 value, and then repeat that expression via <RET>. For instance,
6017 suppose you have an array `dtab' of pointers to structures, and you are
6018 interested in the values of a field `fv' in each structure. Here is an
6019 example of what you might type:
6028 File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data
6033 By default, GDB prints a value according to its data type. Sometimes
6034 this is not what you want. For example, you might want to print a
6035 number in hex, or a pointer in decimal. Or you might want to view data
6036 in memory at a certain address as a character string or as an
6037 instruction. To do these things, specify an "output format" when you
6040 The simplest use of output formats is to say how to print a value
6041 already computed. This is done by starting the arguments of the
6042 `print' command with a slash and a format letter. The format letters
6046 Regard the bits of the value as an integer, and print the integer
6050 Print as integer in signed decimal.
6053 Print as integer in unsigned decimal.
6056 Print as integer in octal.
6059 Print as integer in binary. The letter `t' stands for "two". (1)
6062 Print as an address, both absolute in hexadecimal and as an offset
6063 from the nearest preceding symbol. You can use this format used
6064 to discover where (in what function) an unknown address is located:
6067 $3 = 0x54320 <_initialize_vx+396>
6069 The command `info symbol 0x54320' yields similar results. *Note
6070 info symbol: Symbols.
6073 Regard as an integer and print it as a character constant. This
6074 prints both the numerical value and its character representation.
6075 The character representation is replaced with the octal escape
6076 `\nnn' for characters outside the 7-bit ASCII range.
6078 Without this format, GDB displays `char', `unsigned char', and
6079 `signed char' data as character constants. Single-byte members of
6080 vectors are displayed as integer data.
6083 Regard the bits of the value as a floating point number and print
6084 using typical floating point syntax.
6087 Regard as a string, if possible. With this format, pointers to
6088 single-byte data are displayed as null-terminated strings and
6089 arrays of single-byte data are displayed as fixed-length strings.
6090 Other values are displayed in their natural types.
6092 Without this format, GDB displays pointers to and arrays of
6093 `char', `unsigned char', and `signed char' as strings.
6094 Single-byte members of a vector are displayed as an integer array.
6097 Print using the `raw' formatting. By default, GDB will use a
6098 type-specific pretty-printer. The `r' format bypasses any
6099 pretty-printer which might exist for the value's type.
6101 For example, to print the program counter in hex (*note
6106 Note that no space is required before the slash; this is because command
6107 names in GDB cannot contain a slash.
6109 To reprint the last value in the value history with a different
6110 format, you can use the `print' command with just a format and no
6111 expression. For example, `p/x' reprints the last value in hex.
6113 ---------- Footnotes ----------
6115 (1) `b' cannot be used because these format letters are also used
6116 with the `x' command, where `b' stands for "byte"; see *note Examining
6120 File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data
6122 10.6 Examining Memory
6123 =====================
6125 You can use the command `x' (for "examine") to examine memory in any of
6126 several formats, independently of your program's data types.
6131 Use the `x' command to examine memory.
6133 N, F, and U are all optional parameters that specify how much memory
6134 to display and how to format it; ADDR is an expression giving the
6135 address where you want to start displaying memory. If you use defaults
6136 for NFU, you need not type the slash `/'. Several commands set
6137 convenient defaults for ADDR.
6140 The repeat count is a decimal integer; the default is 1. It
6141 specifies how much memory (counting by units U) to display.
6143 F, the display format
6144 The display format is one of the formats used by `print' (`x',
6145 `d', `u', `o', `t', `a', `c', `f', `s'), and in addition `i' (for
6146 machine instructions). The default is `x' (hexadecimal)
6147 initially. The default changes each time you use either `x' or
6151 The unit size is any of
6157 Halfwords (two bytes).
6160 Words (four bytes). This is the initial default.
6163 Giant words (eight bytes).
6165 Each time you specify a unit size with `x', that size becomes the
6166 default unit the next time you use `x'. (For the `s' and `i'
6167 formats, the unit size is ignored and is normally not written.)
6169 ADDR, starting display address
6170 ADDR is the address where you want GDB to begin displaying memory.
6171 The expression need not have a pointer value (though it may); it
6172 is always interpreted as an integer address of a byte of memory.
6173 *Note Expressions: Expressions, for more information on
6174 expressions. The default for ADDR is usually just after the last
6175 address examined--but several other commands also set the default
6176 address: `info breakpoints' (to the address of the last breakpoint
6177 listed), `info line' (to the starting address of a line), and
6178 `print' (if you use it to display a value from memory).
6180 For example, `x/3uh 0x54320' is a request to display three halfwords
6181 (`h') of memory, formatted as unsigned decimal integers (`u'), starting
6182 at address `0x54320'. `x/4xw $sp' prints the four words (`w') of
6183 memory above the stack pointer (here, `$sp'; *note Registers:
6184 Registers.) in hexadecimal (`x').
6186 Since the letters indicating unit sizes are all distinct from the
6187 letters specifying output formats, you do not have to remember whether
6188 unit size or format comes first; either order works. The output
6189 specifications `4xw' and `4wx' mean exactly the same thing. (However,
6190 the count N must come first; `wx4' does not work.)
6192 Even though the unit size U is ignored for the formats `s' and `i',
6193 you might still want to use a count N; for example, `3i' specifies that
6194 you want to see three machine instructions, including any operands.
6195 For convenience, especially when used with the `display' command, the
6196 `i' format also prints branch delay slot instructions, if any, beyond
6197 the count specified, which immediately follow the last instruction that
6198 is within the count. The command `disassemble' gives an alternative
6199 way of inspecting machine instructions; see *note Source and Machine
6202 All the defaults for the arguments to `x' are designed to make it
6203 easy to continue scanning memory with minimal specifications each time
6204 you use `x'. For example, after you have inspected three machine
6205 instructions with `x/3i ADDR', you can inspect the next seven with just
6206 `x/7'. If you use <RET> to repeat the `x' command, the repeat count N
6207 is used again; the other arguments default as for successive uses of
6210 When examining machine instructions, the instruction at current
6211 program counter is shown with a `=>' marker. For example:
6214 0x804837f <main+11>: mov %esp,%ebp
6215 0x8048381 <main+13>: push %ecx
6216 0x8048382 <main+14>: sub $0x4,%esp
6217 => 0x8048385 <main+17>: movl $0x8048460,(%esp)
6218 0x804838c <main+24>: call 0x80482d4 <puts@plt>
6220 The addresses and contents printed by the `x' command are not saved
6221 in the value history because there is often too much of them and they
6222 would get in the way. Instead, GDB makes these values available for
6223 subsequent use in expressions as values of the convenience variables
6224 `$_' and `$__'. After an `x' command, the last address examined is
6225 available for use in expressions in the convenience variable `$_'. The
6226 contents of that address, as examined, are available in the convenience
6229 If the `x' command has a repeat count, the address and contents saved
6230 are from the last memory unit printed; this is not the same as the last
6231 address printed if several units were printed on the last line of
6234 When you are debugging a program running on a remote target machine
6235 (*note Remote Debugging::), you may wish to verify the program's image
6236 in the remote machine's memory against the executable file you
6237 downloaded to the target. The `compare-sections' command is provided
6238 for such situations.
6240 `compare-sections [SECTION-NAME]'
6241 Compare the data of a loadable section SECTION-NAME in the
6242 executable file of the program being debugged with the same
6243 section in the remote machine's memory, and report any mismatches.
6244 With no arguments, compares all loadable sections. This command's
6245 availability depends on the target's support for the `"qCRC"'
6249 File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data
6251 10.7 Automatic Display
6252 ======================
6254 If you find that you want to print the value of an expression frequently
6255 (to see how it changes), you might want to add it to the "automatic
6256 display list" so that GDB prints its value each time your program stops.
6257 Each expression added to the list is given a number to identify it; to
6258 remove an expression from the list, you specify that number. The
6259 automatic display looks like this:
6262 3: bar[5] = (struct hack *) 0x3804
6264 This display shows item numbers, expressions and their current values.
6265 As with displays you request manually using `x' or `print', you can
6266 specify the output format you prefer; in fact, `display' decides
6267 whether to use `print' or `x' depending your format specification--it
6268 uses `x' if you specify either the `i' or `s' format, or a unit size;
6269 otherwise it uses `print'.
6272 Add the expression EXPR to the list of expressions to display each
6273 time your program stops. *Note Expressions: Expressions.
6275 `display' does not repeat if you press <RET> again after using it.
6278 For FMT specifying only a display format and not a size or count,
6279 add the expression EXPR to the auto-display list but arrange to
6280 display it each time in the specified format FMT. *Note Output
6281 Formats: Output Formats.
6284 For FMT `i' or `s', or including a unit-size or a number of units,
6285 add the expression ADDR as a memory address to be examined each
6286 time your program stops. Examining means in effect doing `x/FMT
6287 ADDR'. *Note Examining Memory: Memory.
6289 For example, `display/i $pc' can be helpful, to see the machine
6290 instruction about to be executed each time execution stops (`$pc' is a
6291 common name for the program counter; *note Registers: Registers.).
6293 `undisplay DNUMS...'
6294 `delete display DNUMS...'
6295 Remove item numbers DNUMS from the list of expressions to display.
6297 `undisplay' does not repeat if you press <RET> after using it.
6298 (Otherwise you would just get the error `No display number ...'.)
6300 `disable display DNUMS...'
6301 Disable the display of item numbers DNUMS. A disabled display
6302 item is not printed automatically, but is not forgotten. It may be
6303 enabled again later.
6305 `enable display DNUMS...'
6306 Enable display of item numbers DNUMS. It becomes effective once
6307 again in auto display of its expression, until you specify
6311 Display the current values of the expressions on the list, just as
6312 is done when your program stops.
6315 Print the list of expressions previously set up to display
6316 automatically, each one with its item number, but without showing
6317 the values. This includes disabled expressions, which are marked
6318 as such. It also includes expressions which would not be
6319 displayed right now because they refer to automatic variables not
6320 currently available.
6322 If a display expression refers to local variables, then it does not
6323 make sense outside the lexical context for which it was set up. Such an
6324 expression is disabled when execution enters a context where one of its
6325 variables is not defined. For example, if you give the command
6326 `display last_char' while inside a function with an argument
6327 `last_char', GDB displays this argument while your program continues to
6328 stop inside that function. When it stops elsewhere--where there is no
6329 variable `last_char'--the display is disabled automatically. The next
6330 time your program stops where `last_char' is meaningful, you can enable
6331 the display expression once again.
6334 File: gdb.info, Node: Print Settings, Next: Value History, Prev: Auto Display, Up: Data
6339 GDB provides the following ways to control how arrays, structures, and
6340 symbols are printed.
6342 These settings are useful for debugging programs in any language:
6345 `set print address on'
6346 GDB prints memory addresses showing the location of stack traces,
6347 structure values, pointer values, breakpoints, and so forth, even
6348 when it also displays the contents of those addresses. The default
6349 is `on'. For example, this is what a stack frame display looks
6350 like with `set print address on':
6353 #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
6355 530 if (lquote != def_lquote)
6357 `set print address off'
6358 Do not print addresses when displaying their contents. For
6359 example, this is the same stack frame displayed with `set print
6362 (gdb) set print addr off
6364 #0 set_quotes (lq="<<", rq=">>") at input.c:530
6365 530 if (lquote != def_lquote)
6367 You can use `set print address off' to eliminate all machine
6368 dependent displays from the GDB interface. For example, with
6369 `print address off', you should get the same text for backtraces on
6370 all machines--whether or not they involve pointer arguments.
6372 `show print address'
6373 Show whether or not addresses are to be printed.
6375 When GDB prints a symbolic address, it normally prints the closest
6376 earlier symbol plus an offset. If that symbol does not uniquely
6377 identify the address (for example, it is a name whose scope is a single
6378 source file), you may need to clarify. One way to do this is with
6379 `info line', for example `info line *0x4537'. Alternately, you can set
6380 GDB to print the source file and line number when it prints a symbolic
6383 `set print symbol-filename on'
6384 Tell GDB to print the source file name and line number of a symbol
6385 in the symbolic form of an address.
6387 `set print symbol-filename off'
6388 Do not print source file name and line number of a symbol. This
6391 `show print symbol-filename'
6392 Show whether or not GDB will print the source file name and line
6393 number of a symbol in the symbolic form of an address.
6395 Another situation where it is helpful to show symbol filenames and
6396 line numbers is when disassembling code; GDB shows you the line number
6397 and source file that corresponds to each instruction.
6399 Also, you may wish to see the symbolic form only if the address being
6400 printed is reasonably close to the closest earlier symbol:
6402 `set print max-symbolic-offset MAX-OFFSET'
6403 Tell GDB to only display the symbolic form of an address if the
6404 offset between the closest earlier symbol and the address is less
6405 than MAX-OFFSET. The default is 0, which tells GDB to always
6406 print the symbolic form of an address if any symbol precedes it.
6408 `show print max-symbolic-offset'
6409 Ask how large the maximum offset is that GDB prints in a symbolic
6412 If you have a pointer and you are not sure where it points, try `set
6413 print symbol-filename on'. Then you can determine the name and source
6414 file location of the variable where it points, using `p/a POINTER'.
6415 This interprets the address in symbolic form. For example, here GDB
6416 shows that a variable `ptt' points at another variable `t', defined in
6419 (gdb) set print symbol-filename on
6421 $4 = 0xe008 <t in hi2.c>
6423 _Warning:_ For pointers that point to a local variable, `p/a' does
6424 not show the symbol name and filename of the referent, even with
6425 the appropriate `set print' options turned on.
6427 Other settings control how different kinds of objects are printed:
6430 `set print array on'
6431 Pretty print arrays. This format is more convenient to read, but
6432 uses more space. The default is off.
6434 `set print array off'
6435 Return to compressed format for arrays.
6438 Show whether compressed or pretty format is selected for displaying
6441 `set print array-indexes'
6442 `set print array-indexes on'
6443 Print the index of each element when displaying arrays. May be
6444 more convenient to locate a given element in the array or quickly
6445 find the index of a given element in that printed array. The
6448 `set print array-indexes off'
6449 Stop printing element indexes when displaying arrays.
6451 `show print array-indexes'
6452 Show whether the index of each element is printed when displaying
6455 `set print elements NUMBER-OF-ELEMENTS'
6456 Set a limit on how many elements of an array GDB will print. If
6457 GDB is printing a large array, it stops printing after it has
6458 printed the number of elements set by the `set print elements'
6459 command. This limit also applies to the display of strings. When
6460 GDB starts, this limit is set to 200. Setting NUMBER-OF-ELEMENTS
6461 to zero means that the printing is unlimited.
6463 `show print elements'
6464 Display the number of elements of a large array that GDB will
6465 print. If the number is 0, then the printing is unlimited.
6467 `set print frame-arguments VALUE'
6468 This command allows to control how the values of arguments are
6469 printed when the debugger prints a frame (*note Frames::). The
6470 possible values are:
6473 The values of all arguments are printed.
6476 Print the value of an argument only if it is a scalar. The
6477 value of more complex arguments such as arrays, structures,
6478 unions, etc, is replaced by `...'. This is the default.
6479 Here is an example where only scalar arguments are shown:
6481 #1 0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green)
6485 None of the argument values are printed. Instead, the value
6486 of each argument is replaced by `...'. In this case, the
6487 example above now becomes:
6489 #1 0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...)
6492 By default, only scalar arguments are printed. This command can
6493 be used to configure the debugger to print the value of all
6494 arguments, regardless of their type. However, it is often
6495 advantageous to not print the value of more complex parameters.
6496 For instance, it reduces the amount of information printed in each
6497 frame, making the backtrace more readable. Also, it improves
6498 performance when displaying Ada frames, because the computation of
6499 large arguments can sometimes be CPU-intensive, especially in
6500 large applications. Setting `print frame-arguments' to `scalars'
6501 (the default) or `none' avoids this computation, thus speeding up
6502 the display of each Ada frame.
6504 `show print frame-arguments'
6505 Show how the value of arguments should be displayed when printing
6509 Set the threshold for suppressing display of repeated array
6510 elements. When the number of consecutive identical elements of an
6511 array exceeds the threshold, GDB prints the string `"<repeats N
6512 times>"', where N is the number of identical repetitions, instead
6513 of displaying the identical elements themselves. Setting the
6514 threshold to zero will cause all elements to be individually
6515 printed. The default threshold is 10.
6517 `show print repeats'
6518 Display the current threshold for printing repeated identical
6521 `set print null-stop'
6522 Cause GDB to stop printing the characters of an array when the
6523 first NULL is encountered. This is useful when large arrays
6524 actually contain only short strings. The default is off.
6526 `show print null-stop'
6527 Show whether GDB stops printing an array on the first NULL
6530 `set print pretty on'
6531 Cause GDB to print structures in an indented format with one member
6532 per line, like this:
6543 `set print pretty off'
6544 Cause GDB to print structures in a compact format, like this:
6546 $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \
6549 This is the default format.
6552 Show which format GDB is using to print structures.
6554 `set print sevenbit-strings on'
6555 Print using only seven-bit characters; if this option is set, GDB
6556 displays any eight-bit characters (in strings or character values)
6557 using the notation `\'NNN. This setting is best if you are
6558 working in English (ASCII) and you use the high-order bit of
6559 characters as a marker or "meta" bit.
6561 `set print sevenbit-strings off'
6562 Print full eight-bit characters. This allows the use of more
6563 international character sets, and is the default.
6565 `show print sevenbit-strings'
6566 Show whether or not GDB is printing only seven-bit characters.
6568 `set print union on'
6569 Tell GDB to print unions which are contained in structures and
6570 other unions. This is the default setting.
6572 `set print union off'
6573 Tell GDB not to print unions which are contained in structures and
6574 other unions. GDB will print `"{...}"' instead.
6577 Ask GDB whether or not it will print unions which are contained in
6578 structures and other unions.
6580 For example, given the declarations
6582 typedef enum {Tree, Bug} Species;
6583 typedef enum {Big_tree, Acorn, Seedling} Tree_forms;
6584 typedef enum {Caterpillar, Cocoon, Butterfly}
6595 struct thing foo = {Tree, {Acorn}};
6597 with `set print union on' in effect `p foo' would print
6599 $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}}
6601 and with `set print union off' in effect it would print
6603 $1 = {it = Tree, form = {...}}
6605 `set print union' affects programs written in C-like languages and
6608 These settings are of interest when debugging C++ programs:
6610 `set print demangle'
6611 `set print demangle on'
6612 Print C++ names in their source form rather than in the encoded
6613 ("mangled") form passed to the assembler and linker for type-safe
6614 linkage. The default is on.
6616 `show print demangle'
6617 Show whether C++ names are printed in mangled or demangled form.
6619 `set print asm-demangle'
6620 `set print asm-demangle on'
6621 Print C++ names in their source form rather than their mangled
6622 form, even in assembler code printouts such as instruction
6623 disassemblies. The default is off.
6625 `show print asm-demangle'
6626 Show whether C++ names in assembly listings are printed in mangled
6629 `set demangle-style STYLE'
6630 Choose among several encoding schemes used by different compilers
6631 to represent C++ names. The choices for STYLE are currently:
6634 Allow GDB to choose a decoding style by inspecting your
6638 Decode based on the GNU C++ compiler (`g++') encoding
6639 algorithm. This is the default.
6642 Decode based on the HP ANSI C++ (`aCC') encoding algorithm.
6645 Decode based on the Lucid C++ compiler (`lcc') encoding
6649 Decode using the algorithm in the `C++ Annotated Reference
6650 Manual'. *Warning:* this setting alone is not sufficient to
6651 allow debugging `cfront'-generated executables. GDB would
6652 require further enhancement to permit that.
6654 If you omit STYLE, you will see a list of possible formats.
6656 `show demangle-style'
6657 Display the encoding style currently in use for decoding C++
6661 `set print object on'
6662 When displaying a pointer to an object, identify the _actual_
6663 (derived) type of the object rather than the _declared_ type, using
6664 the virtual function table.
6666 `set print object off'
6667 Display only the declared type of objects, without reference to the
6668 virtual function table. This is the default setting.
6671 Show whether actual, or declared, object types are displayed.
6673 `set print static-members'
6674 `set print static-members on'
6675 Print static members when displaying a C++ object. The default is
6678 `set print static-members off'
6679 Do not print static members when displaying a C++ object.
6681 `show print static-members'
6682 Show whether C++ static members are printed or not.
6684 `set print pascal_static-members'
6685 `set print pascal_static-members on'
6686 Print static members when displaying a Pascal object. The default
6689 `set print pascal_static-members off'
6690 Do not print static members when displaying a Pascal object.
6692 `show print pascal_static-members'
6693 Show whether Pascal static members are printed or not.
6697 Pretty print C++ virtual function tables. The default is off.
6698 (The `vtbl' commands do not work on programs compiled with the HP
6699 ANSI C++ compiler (`aCC').)
6701 `set print vtbl off'
6702 Do not pretty print C++ virtual function tables.
6705 Show whether C++ virtual function tables are pretty printed, or
6709 File: gdb.info, Node: Value History, Next: Convenience Vars, Prev: Print Settings, Up: Data
6714 Values printed by the `print' command are saved in the GDB "value
6715 history". This allows you to refer to them in other expressions.
6716 Values are kept until the symbol table is re-read or discarded (for
6717 example with the `file' or `symbol-file' commands). When the symbol
6718 table changes, the value history is discarded, since the values may
6719 contain pointers back to the types defined in the symbol table.
6721 The values printed are given "history numbers" by which you can
6722 refer to them. These are successive integers starting with one.
6723 `print' shows you the history number assigned to a value by printing
6724 `$NUM = ' before the value; here NUM is the history number.
6726 To refer to any previous value, use `$' followed by the value's
6727 history number. The way `print' labels its output is designed to
6728 remind you of this. Just `$' refers to the most recent value in the
6729 history, and `$$' refers to the value before that. `$$N' refers to the
6730 Nth value from the end; `$$2' is the value just prior to `$$', `$$1' is
6731 equivalent to `$$', and `$$0' is equivalent to `$'.
6733 For example, suppose you have just printed a pointer to a structure
6734 and want to see the contents of the structure. It suffices to type
6738 If you have a chain of structures where the component `next' points
6739 to the next one, you can print the contents of the next one with this:
6743 You can print successive links in the chain by repeating this
6744 command--which you can do by just typing <RET>.
6746 Note that the history records values, not expressions. If the value
6747 of `x' is 4 and you type these commands:
6752 then the value recorded in the value history by the `print' command
6753 remains 4 even though the value of `x' has changed.
6756 Print the last ten values in the value history, with their item
6757 numbers. This is like `p $$9' repeated ten times, except that
6758 `show values' does not change the history.
6761 Print ten history values centered on history item number N.
6764 Print ten history values just after the values last printed. If
6765 no more values are available, `show values +' produces no display.
6767 Pressing <RET> to repeat `show values N' has exactly the same effect
6771 File: gdb.info, Node: Convenience Vars, Next: Registers, Prev: Value History, Up: Data
6773 10.10 Convenience Variables
6774 ===========================
6776 GDB provides "convenience variables" that you can use within GDB to
6777 hold on to a value and refer to it later. These variables exist
6778 entirely within GDB; they are not part of your program, and setting a
6779 convenience variable has no direct effect on further execution of your
6780 program. That is why you can use them freely.
6782 Convenience variables are prefixed with `$'. Any name preceded by
6783 `$' can be used for a convenience variable, unless it is one of the
6784 predefined machine-specific register names (*note Registers:
6785 Registers.). (Value history references, in contrast, are _numbers_
6786 preceded by `$'. *Note Value History: Value History.)
6788 You can save a value in a convenience variable with an assignment
6789 expression, just as you would set a variable in your program. For
6792 set $foo = *object_ptr
6794 would save in `$foo' the value contained in the object pointed to by
6797 Using a convenience variable for the first time creates it, but its
6798 value is `void' until you assign a new value. You can alter the value
6799 with another assignment at any time.
6801 Convenience variables have no fixed types. You can assign a
6802 convenience variable any type of value, including structures and
6803 arrays, even if that variable already has a value of a different type.
6804 The convenience variable, when used as an expression, has the type of
6808 Print a list of convenience variables used so far, and their
6809 values. Abbreviated `show conv'.
6811 `init-if-undefined $VARIABLE = EXPRESSION'
6812 Set a convenience variable if it has not already been set. This
6813 is useful for user-defined commands that keep some state. It is
6814 similar, in concept, to using local static variables with
6815 initializers in C (except that convenience variables are global).
6816 It can also be used to allow users to override default values used
6817 in a command script.
6819 If the variable is already defined then the expression is not
6820 evaluated so any side-effects do not occur.
6822 One of the ways to use a convenience variable is as a counter to be
6823 incremented or a pointer to be advanced. For example, to print a field
6824 from successive elements of an array of structures:
6827 print bar[$i++]->contents
6829 Repeat that command by typing <RET>.
6831 Some convenience variables are created automatically by GDB and given
6832 values likely to be useful.
6835 The variable `$_' is automatically set by the `x' command to the
6836 last address examined (*note Examining Memory: Memory.). Other
6837 commands which provide a default address for `x' to examine also
6838 set `$_' to that address; these commands include `info line' and
6839 `info breakpoint'. The type of `$_' is `void *' except when set
6840 by the `x' command, in which case it is a pointer to the type of
6844 The variable `$__' is automatically set by the `x' command to the
6845 value found in the last address examined. Its type is chosen to
6846 match the format in which the data was printed.
6849 The variable `$_exitcode' is automatically set to the exit code
6850 when the program being debugged terminates.
6853 The variable `$_siginfo' contains extra signal information (*note
6854 extra signal information::). Note that `$_siginfo' could be
6855 empty, if the application has not yet received any signals. For
6856 example, it will be empty before you execute the `run' command.
6858 On HP-UX systems, if you refer to a function or variable name that
6859 begins with a dollar sign, GDB searches for a user or system name
6860 first, before it searches for a convenience variable.
6862 GDB also supplies some "convenience functions". These have a syntax
6863 similar to convenience variables. A convenience function can be used
6864 in an expression just like an ordinary function; however, a convenience
6865 function is implemented internally to GDB.
6868 Print a list of all convenience functions.
6871 File: gdb.info, Node: Registers, Next: Floating Point Hardware, Prev: Convenience Vars, Up: Data
6876 You can refer to machine register contents, in expressions, as variables
6877 with names starting with `$'. The names of registers are different for
6878 each machine; use `info registers' to see the names used on your
6882 Print the names and values of all registers except floating-point
6883 and vector registers (in the selected stack frame).
6885 `info all-registers'
6886 Print the names and values of all registers, including
6887 floating-point and vector registers (in the selected stack frame).
6889 `info registers REGNAME ...'
6890 Print the "relativized" value of each specified register REGNAME.
6891 As discussed in detail below, register values are normally
6892 relative to the selected stack frame. REGNAME may be any register
6893 name valid on the machine you are using, with or without the
6896 GDB has four "standard" register names that are available (in
6897 expressions) on most machines--whenever they do not conflict with an
6898 architecture's canonical mnemonics for registers. The register names
6899 `$pc' and `$sp' are used for the program counter register and the stack
6900 pointer. `$fp' is used for a register that contains a pointer to the
6901 current stack frame, and `$ps' is used for a register that contains the
6902 processor status. For example, you could print the program counter in
6907 or print the instruction to be executed next with
6911 or add four to the stack pointer(1) with
6915 Whenever possible, these four standard register names are available
6916 on your machine even though the machine has different canonical
6917 mnemonics, so long as there is no conflict. The `info registers'
6918 command shows the canonical names. For example, on the SPARC, `info
6919 registers' displays the processor status register as `$psr' but you can
6920 also refer to it as `$ps'; and on x86-based machines `$ps' is an alias
6921 for the EFLAGS register.
6923 GDB always considers the contents of an ordinary register as an
6924 integer when the register is examined in this way. Some machines have
6925 special registers which can hold nothing but floating point; these
6926 registers are considered to have floating point values. There is no way
6927 to refer to the contents of an ordinary register as floating point value
6928 (although you can _print_ it as a floating point value with `print/f
6931 Some registers have distinct "raw" and "virtual" data formats. This
6932 means that the data format in which the register contents are saved by
6933 the operating system is not the same one that your program normally
6934 sees. For example, the registers of the 68881 floating point
6935 coprocessor are always saved in "extended" (raw) format, but all C
6936 programs expect to work with "double" (virtual) format. In such cases,
6937 GDB normally works with the virtual format only (the format that makes
6938 sense for your program), but the `info registers' command prints the
6939 data in both formats.
6941 Some machines have special registers whose contents can be
6942 interpreted in several different ways. For example, modern x86-based
6943 machines have SSE and MMX registers that can hold several values packed
6944 together in several different formats. GDB refers to such registers in
6949 v4_float = {0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044},
6950 v2_double = {9.92129282474342e-303, 2.7585945287983262e-313},
6951 v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000",
6952 v8_int16 = {0, 0, 14072, 315, 11, 0, 13, 0},
6953 v4_int32 = {0, 20657912, 11, 13},
6954 v2_int64 = {88725056443645952, 55834574859},
6955 uint128 = 0x0000000d0000000b013b36f800000000
6958 To set values of such registers, you need to tell GDB which view of the
6959 register you wish to change, as if you were assigning value to a
6962 (gdb) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF
6964 Normally, register values are relative to the selected stack frame
6965 (*note Selecting a Frame: Selection.). This means that you get the
6966 value that the register would contain if all stack frames farther in
6967 were exited and their saved registers restored. In order to see the
6968 true contents of hardware registers, you must select the innermost
6969 frame (with `frame 0').
6971 However, GDB must deduce where registers are saved, from the machine
6972 code generated by your compiler. If some registers are not saved, or if
6973 GDB is unable to locate the saved registers, the selected stack frame
6974 makes no difference.
6976 ---------- Footnotes ----------
6978 (1) This is a way of removing one word from the stack, on machines
6979 where stacks grow downward in memory (most machines, nowadays). This
6980 assumes that the innermost stack frame is selected; setting `$sp' is
6981 not allowed when other stack frames are selected. To pop entire frames
6982 off the stack, regardless of machine architecture, use `return'; see
6983 *note Returning from a Function: Returning.
6986 File: gdb.info, Node: Floating Point Hardware, Next: Vector Unit, Prev: Registers, Up: Data
6988 10.12 Floating Point Hardware
6989 =============================
6991 Depending on the configuration, GDB may be able to give you more
6992 information about the status of the floating point hardware.
6995 Display hardware-dependent information about the floating point
6996 unit. The exact contents and layout vary depending on the
6997 floating point chip. Currently, `info float' is supported on the
6998 ARM and x86 machines.
7001 File: gdb.info, Node: Vector Unit, Next: OS Information, Prev: Floating Point Hardware, Up: Data
7006 Depending on the configuration, GDB may be able to give you more
7007 information about the status of the vector unit.
7010 Display information about the vector unit. The exact contents and
7011 layout vary depending on the hardware.
7014 File: gdb.info, Node: OS Information, Next: Memory Region Attributes, Prev: Vector Unit, Up: Data
7016 10.14 Operating System Auxiliary Information
7017 ============================================
7019 GDB provides interfaces to useful OS facilities that can help you debug
7022 When GDB runs on a "Posix system" (such as GNU or Unix machines), it
7023 interfaces with the inferior via the `ptrace' system call. The
7024 operating system creates a special sata structure, called `struct
7025 user', for this interface. You can use the command `info udot' to
7026 display the contents of this data structure.
7029 Display the contents of the `struct user' maintained by the OS
7030 kernel for the program being debugged. GDB displays the contents
7031 of `struct user' as a list of hex numbers, similar to the
7034 Some operating systems supply an "auxiliary vector" to programs at
7035 startup. This is akin to the arguments and environment that you
7036 specify for a program, but contains a system-dependent variety of
7037 binary values that tell system libraries important details about the
7038 hardware, operating system, and process. Each value's purpose is
7039 identified by an integer tag; the meanings are well-known but
7040 system-specific. Depending on the configuration and operating system
7041 facilities, GDB may be able to show you this information. For remote
7042 targets, this functionality may further depend on the remote stub's
7043 support of the `qXfer:auxv:read' packet, see *note qXfer auxiliary
7047 Display the auxiliary vector of the inferior, which can be either a
7048 live process or a core dump file. GDB prints each tag value
7049 numerically, and also shows names and text descriptions for
7050 recognized tags. Some values in the vector are numbers, some bit
7051 masks, and some pointers to strings or other data. GDB displays
7052 each value in the most appropriate form for a recognized tag, and
7053 in hexadecimal for an unrecognized tag.
7055 On some targets, GDB can access operating-system-specific information
7056 and display it to user, without interpretation. For remote targets,
7057 this functionality depends on the remote stub's support of the
7058 `qXfer:osdata:read' packet, see *note qXfer osdata read::.
7061 Display the list of processes on the target. For each process,
7062 GDB prints the process identifier, the name of the user, and the
7063 command corresponding to the process.
7066 File: gdb.info, Node: Memory Region Attributes, Next: Dump/Restore Files, Prev: OS Information, Up: Data
7068 10.15 Memory Region Attributes
7069 ==============================
7071 "Memory region attributes" allow you to describe special handling
7072 required by regions of your target's memory. GDB uses attributes to
7073 determine whether to allow certain types of memory accesses; whether to
7074 use specific width accesses; and whether to cache target memory. By
7075 default the description of memory regions is fetched from the target
7076 (if the current target supports this), but the user can override the
7079 Defined memory regions can be individually enabled and disabled.
7080 When a memory region is disabled, GDB uses the default attributes when
7081 accessing memory in that region. Similarly, if no memory regions have
7082 been defined, GDB uses the default attributes when accessing all memory.
7084 When a memory region is defined, it is given a number to identify it;
7085 to enable, disable, or remove a memory region, you specify that number.
7087 `mem LOWER UPPER ATTRIBUTES...'
7088 Define a memory region bounded by LOWER and UPPER with attributes
7089 ATTRIBUTES..., and add it to the list of regions monitored by GDB.
7090 Note that UPPER == 0 is a special case: it is treated as the
7091 target's maximum memory address. (0xffff on 16 bit targets,
7092 0xffffffff on 32 bit targets, etc.)
7095 Discard any user changes to the memory regions and use
7096 target-supplied regions, if available, or no regions if the target
7099 `delete mem NUMS...'
7100 Remove memory regions NUMS... from the list of regions monitored
7103 `disable mem NUMS...'
7104 Disable monitoring of memory regions NUMS.... A disabled memory
7105 region is not forgotten. It may be enabled again later.
7107 `enable mem NUMS...'
7108 Enable monitoring of memory regions NUMS....
7111 Print a table of all defined memory regions, with the following
7112 columns for each region:
7114 _Memory Region Number_
7116 _Enabled or Disabled._
7117 Enabled memory regions are marked with `y'. Disabled memory
7118 regions are marked with `n'.
7121 The address defining the inclusive lower bound of the memory
7125 The address defining the exclusive upper bound of the memory
7129 The list of attributes set for this memory region.
7134 10.15.1.1 Memory Access Mode
7135 ............................
7137 The access mode attributes set whether GDB may make read or write
7138 accesses to a memory region.
7140 While these attributes prevent GDB from performing invalid memory
7141 accesses, they do nothing to prevent the target system, I/O DMA, etc.
7142 from accessing memory.
7145 Memory is read only.
7148 Memory is write only.
7151 Memory is read/write. This is the default.
7153 10.15.1.2 Memory Access Size
7154 ............................
7156 The access size attribute tells GDB to use specific sized accesses in
7157 the memory region. Often memory mapped device registers require
7158 specific sized accesses. If no access size attribute is specified, GDB
7159 may use accesses of any size.
7162 Use 8 bit memory accesses.
7165 Use 16 bit memory accesses.
7168 Use 32 bit memory accesses.
7171 Use 64 bit memory accesses.
7173 10.15.1.3 Data Cache
7174 ....................
7176 The data cache attributes set whether GDB will cache target memory.
7177 While this generally improves performance by reducing debug protocol
7178 overhead, it can lead to incorrect results because GDB does not know
7179 about volatile variables or memory mapped device registers.
7182 Enable GDB to cache target memory.
7185 Disable GDB from caching target memory. This is the default.
7187 10.15.2 Memory Access Checking
7188 ------------------------------
7190 GDB can be instructed to refuse accesses to memory that is not
7191 explicitly described. This can be useful if accessing such regions has
7192 undesired effects for a specific target, or to provide better error
7193 checking. The following commands control this behaviour.
7195 `set mem inaccessible-by-default [on|off]'
7196 If `on' is specified, make GDB treat memory not explicitly
7197 described by the memory ranges as non-existent and refuse accesses
7198 to such memory. The checks are only performed if there's at least
7199 one memory range defined. If `off' is specified, make GDB treat
7200 the memory not explicitly described by the memory ranges as RAM.
7201 The default value is `on'.
7203 `show mem inaccessible-by-default'
7204 Show the current handling of accesses to unknown memory.
7207 File: gdb.info, Node: Dump/Restore Files, Next: Core File Generation, Prev: Memory Region Attributes, Up: Data
7209 10.16 Copy Between Memory and a File
7210 ====================================
7212 You can use the commands `dump', `append', and `restore' to copy data
7213 between target memory and a file. The `dump' and `append' commands
7214 write data to a file, and the `restore' command reads data from a file
7215 back into the inferior's memory. Files may be in binary, Motorola
7216 S-record, Intel hex, or Tektronix Hex format; however, GDB can only
7217 append to binary files.
7219 `dump [FORMAT] memory FILENAME START_ADDR END_ADDR'
7220 `dump [FORMAT] value FILENAME EXPR'
7221 Dump the contents of memory from START_ADDR to END_ADDR, or the
7222 value of EXPR, to FILENAME in the given format.
7224 The FORMAT parameter may be any one of:
7232 Motorola S-record format.
7235 Tektronix Hex format.
7237 GDB uses the same definitions of these formats as the GNU binary
7238 utilities, like `objdump' and `objcopy'. If FORMAT is omitted,
7239 GDB dumps the data in raw binary form.
7241 `append [binary] memory FILENAME START_ADDR END_ADDR'
7242 `append [binary] value FILENAME EXPR'
7243 Append the contents of memory from START_ADDR to END_ADDR, or the
7244 value of EXPR, to the file FILENAME, in raw binary form. (GDB can
7245 only append data to files in raw binary form.)
7247 `restore FILENAME [binary] BIAS START END'
7248 Restore the contents of file FILENAME into memory. The `restore'
7249 command can automatically recognize any known BFD file format,
7250 except for raw binary. To restore a raw binary file you must
7251 specify the optional keyword `binary' after the filename.
7253 If BIAS is non-zero, its value will be added to the addresses
7254 contained in the file. Binary files always start at address zero,
7255 so they will be restored at address BIAS. Other bfd files have a
7256 built-in location; they will be restored at offset BIAS from that
7259 If START and/or END are non-zero, then only data between file
7260 offset START and file offset END will be restored. These offsets
7261 are relative to the addresses in the file, before the BIAS
7262 argument is applied.
7266 File: gdb.info, Node: Core File Generation, Next: Character Sets, Prev: Dump/Restore Files, Up: Data
7268 10.17 How to Produce a Core File from Your Program
7269 ==================================================
7271 A "core file" or "core dump" is a file that records the memory image of
7272 a running process and its process status (register values etc.). Its
7273 primary use is post-mortem debugging of a program that crashed while it
7274 ran outside a debugger. A program that crashes automatically produces
7275 a core file, unless this feature is disabled by the user. *Note
7276 Files::, for information on invoking GDB in the post-mortem debugging
7279 Occasionally, you may wish to produce a core file of the program you
7280 are debugging in order to preserve a snapshot of its state. GDB has a
7281 special command for that.
7283 `generate-core-file [FILE]'
7285 Produce a core dump of the inferior process. The optional argument
7286 FILE specifies the file name where to put the core dump. If not
7287 specified, the file name defaults to `core.PID', where PID is the
7288 inferior process ID.
7290 Note that this command is implemented only for some systems (as of
7291 this writing, GNU/Linux, FreeBSD, Solaris, Unixware, and S390).
7294 File: gdb.info, Node: Character Sets, Next: Caching Remote Data, Prev: Core File Generation, Up: Data
7296 10.18 Character Sets
7297 ====================
7299 If the program you are debugging uses a different character set to
7300 represent characters and strings than the one GDB uses itself, GDB can
7301 automatically translate between the character sets for you. The
7302 character set GDB uses we call the "host character set"; the one the
7303 inferior program uses we call the "target character set".
7305 For example, if you are running GDB on a GNU/Linux system, which
7306 uses the ISO Latin 1 character set, but you are using GDB's remote
7307 protocol (*note Remote Debugging::) to debug a program running on an
7308 IBM mainframe, which uses the EBCDIC character set, then the host
7309 character set is Latin-1, and the target character set is EBCDIC. If
7310 you give GDB the command `set target-charset EBCDIC-US', then GDB
7311 translates between EBCDIC and Latin 1 as you print character or string
7312 values, or use character and string literals in expressions.
7314 GDB has no way to automatically recognize which character set the
7315 inferior program uses; you must tell it, using the `set target-charset'
7316 command, described below.
7318 Here are the commands for controlling GDB's character set support:
7320 `set target-charset CHARSET'
7321 Set the current target character set to CHARSET. To display the
7322 list of supported target character sets, type
7323 `set target-charset <TAB><TAB>'.
7325 `set host-charset CHARSET'
7326 Set the current host character set to CHARSET.
7328 By default, GDB uses a host character set appropriate to the
7329 system it is running on; you can override that default using the
7330 `set host-charset' command. On some systems, GDB cannot
7331 automatically determine the appropriate host character set. In
7332 this case, GDB uses `UTF-8'.
7334 GDB can only use certain character sets as its host character set.
7335 If you type `set target-charset <TAB><TAB>', GDB will list the
7336 host character sets it supports.
7338 `set charset CHARSET'
7339 Set the current host and target character sets to CHARSET. As
7340 above, if you type `set charset <TAB><TAB>', GDB will list the
7341 names of the character sets that can be used for both host and
7345 Show the names of the current host and target character sets.
7348 Show the name of the current host character set.
7350 `show target-charset'
7351 Show the name of the current target character set.
7353 `set target-wide-charset CHARSET'
7354 Set the current target's wide character set to CHARSET. This is
7355 the character set used by the target's `wchar_t' type. To display
7356 the list of supported wide character sets, type
7357 `set target-wide-charset <TAB><TAB>'.
7359 `show target-wide-charset'
7360 Show the name of the current target's wide character set.
7362 Here is an example of GDB's character set support in action. Assume
7363 that the following source code has been placed in the file
7369 = {72, 101, 108, 108, 111, 44, 32, 119,
7370 111, 114, 108, 100, 33, 10, 0};
7371 char ibm1047_hello[]
7372 = {200, 133, 147, 147, 150, 107, 64, 166,
7373 150, 153, 147, 132, 90, 37, 0};
7377 printf ("Hello, world!\n");
7380 In this program, `ascii_hello' and `ibm1047_hello' are arrays
7381 containing the string `Hello, world!' followed by a newline, encoded in
7382 the ASCII and IBM1047 character sets.
7384 We compile the program, and invoke the debugger on it:
7386 $ gcc -g charset-test.c -o charset-test
7387 $ gdb -nw charset-test
7388 GNU gdb 2001-12-19-cvs
7389 Copyright 2001 Free Software Foundation, Inc.
7393 We can use the `show charset' command to see what character sets GDB
7394 is currently using to interpret and display characters and strings:
7397 The current host and target character set is `ISO-8859-1'.
7400 For the sake of printing this manual, let's use ASCII as our initial
7402 (gdb) set charset ASCII
7404 The current host and target character set is `ASCII'.
7407 Let's assume that ASCII is indeed the correct character set for our
7408 host system -- in other words, let's assume that if GDB prints
7409 characters using the ASCII character set, our terminal will display
7410 them properly. Since our current target character set is also ASCII,
7411 the contents of `ascii_hello' print legibly:
7413 (gdb) print ascii_hello
7414 $1 = 0x401698 "Hello, world!\n"
7415 (gdb) print ascii_hello[0]
7419 GDB uses the target character set for character and string literals
7420 you use in expressions:
7426 The ASCII character set uses the number 43 to encode the `+'
7429 GDB relies on the user to tell it which character set the target
7430 program uses. If we print `ibm1047_hello' while our target character
7431 set is still ASCII, we get jibberish:
7433 (gdb) print ibm1047_hello
7434 $4 = 0x4016a8 "\310\205\223\223\226k@\246\226\231\223\204Z%"
7435 (gdb) print ibm1047_hello[0]
7439 If we invoke the `set target-charset' followed by <TAB><TAB>, GDB
7440 tells us the character sets it supports:
7442 (gdb) set target-charset
7443 ASCII EBCDIC-US IBM1047 ISO-8859-1
7444 (gdb) set target-charset
7446 We can select IBM1047 as our target character set, and examine the
7447 program's strings again. Now the ASCII string is wrong, but GDB
7448 translates the contents of `ibm1047_hello' from the target character
7449 set, IBM1047, to the host character set, ASCII, and they display
7452 (gdb) set target-charset IBM1047
7454 The current host character set is `ASCII'.
7455 The current target character set is `IBM1047'.
7456 (gdb) print ascii_hello
7457 $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012"
7458 (gdb) print ascii_hello[0]
7460 (gdb) print ibm1047_hello
7461 $8 = 0x4016a8 "Hello, world!\n"
7462 (gdb) print ibm1047_hello[0]
7466 As above, GDB uses the target character set for character and string
7467 literals you use in expressions:
7473 The IBM1047 character set uses the number 78 to encode the `+'
7477 File: gdb.info, Node: Caching Remote Data, Next: Searching Memory, Prev: Character Sets, Up: Data
7479 10.19 Caching Data of Remote Targets
7480 ====================================
7482 GDB caches data exchanged between the debugger and a remote target
7483 (*note Remote Debugging::). Such caching generally improves
7484 performance, because it reduces the overhead of the remote protocol by
7485 bundling memory reads and writes into large chunks. Unfortunately,
7486 simply caching everything would lead to incorrect results, since GDB
7487 does not necessarily know anything about volatile values, memory-mapped
7488 I/O addresses, etc. Furthermore, in non-stop mode (*note Non-Stop
7489 Mode::) memory can be changed _while_ a gdb command is executing.
7490 Therefore, by default, GDB only caches data known to be on the stack(1).
7491 Other regions of memory can be explicitly marked as cacheable; see
7492 *note Memory Region Attributes::.
7494 `set remotecache on'
7495 `set remotecache off'
7496 This option no longer does anything; it exists for compatibility
7500 Show the current state of the obsolete remotecache flag.
7502 `set stack-cache on'
7503 `set stack-cache off'
7504 Enable or disable caching of stack accesses. When `ON', use
7505 caching. By default, this option is `ON'.
7508 Show the current state of data caching for memory accesses.
7510 `info dcache [line]'
7511 Print the information about the data cache performance. The
7512 information displayed includes the dcache width and depth, and for
7513 each cache line, its number, address, and how many times it was
7514 referenced. This command is useful for debugging the data cache
7517 If a line number is specified, the contents of that line will be
7520 ---------- Footnotes ----------
7522 (1) In non-stop mode, it is moderately rare for a running thread to
7523 modify the stack of a stopped thread in a way that would interfere with
7524 a backtrace, and caching of stack reads provides a significant speed up
7525 of remote backtraces.
7528 File: gdb.info, Node: Searching Memory, Prev: Caching Remote Data, Up: Data
7533 Memory can be searched for a particular sequence of bytes with the
7536 `find [/SN] START_ADDR, +LEN, VAL1 [, VAL2, ...]'
7537 `find [/SN] START_ADDR, END_ADDR, VAL1 [, VAL2, ...]'
7538 Search memory for the sequence of bytes specified by VAL1, VAL2,
7539 etc. The search begins at address START_ADDR and continues for
7540 either LEN bytes or through to END_ADDR inclusive.
7542 S and N are optional parameters. They may be specified in either
7543 order, apart or together.
7545 S, search query size
7546 The size of each search query value.
7552 halfwords (two bytes)
7558 giant words (eight bytes)
7560 All values are interpreted in the current language. This means,
7561 for example, that if the current source language is C/C++ then
7562 searching for the string "hello" includes the trailing '\0'.
7564 If the value size is not specified, it is taken from the value's
7565 type in the current language. This is useful when one wants to
7566 specify the search pattern as a mixture of types. Note that this
7567 means, for example, that in the case of C-like languages a search
7568 for an untyped 0x42 will search for `(int) 0x42' which is
7569 typically four bytes.
7571 N, maximum number of finds
7572 The maximum number of matches to print. The default is to print
7575 You can use strings as search values. Quote them with double-quotes
7576 (`"'). The string value is copied into the search pattern byte by byte,
7577 regardless of the endianness of the target and the size specification.
7579 The address of each match found is printed as well as a count of the
7580 number of matches found.
7582 The address of the last value found is stored in convenience variable
7583 `$_'. A count of the number of matches is stored in `$numfound'.
7585 For example, if stopped at the `printf' in this function:
7590 static char hello[] = "hello-hello";
7591 static struct { char c; short s; int i; }
7592 __attribute__ ((packed)) mixed
7593 = { 'c', 0x1234, 0x87654321 };
7594 printf ("%s\n", hello);
7597 you get during debugging:
7599 (gdb) find &hello[0], +sizeof(hello), "hello"
7600 0x804956d <hello.1620+6>
7602 (gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'
7603 0x8049567 <hello.1620>
7604 0x804956d <hello.1620+6>
7606 (gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'
7607 0x8049567 <hello.1620>
7609 (gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321
7610 0x8049560 <mixed.1625>
7612 (gdb) print $numfound
7615 $2 = (void *) 0x8049560
7618 File: gdb.info, Node: Optimized Code, Next: Macros, Prev: Data, Up: Top
7620 11 Debugging Optimized Code
7621 ***************************
7623 Almost all compilers support optimization. With optimization disabled,
7624 the compiler generates assembly code that corresponds directly to your
7625 source code, in a simplistic way. As the compiler applies more
7626 powerful optimizations, the generated assembly code diverges from your
7627 original source code. With help from debugging information generated
7628 by the compiler, GDB can map from the running program back to
7629 constructs from your original source.
7631 GDB is more accurate with optimization disabled. If you can
7632 recompile without optimization, it is easier to follow the progress of
7633 your program during debugging. But, there are many cases where you may
7634 need to debug an optimized version.
7636 When you debug a program compiled with `-g -O', remember that the
7637 optimizer has rearranged your code; the debugger shows you what is
7638 really there. Do not be too surprised when the execution path does not
7639 exactly match your source file! An extreme example: if you define a
7640 variable, but never use it, GDB never sees that variable--because the
7641 compiler optimizes it out of existence.
7643 Some things do not work as well with `-g -O' as with just `-g',
7644 particularly on machines with instruction scheduling. If in doubt,
7645 recompile with `-g' alone, and if this fixes the problem, please report
7646 it to us as a bug (including a test case!). *Note Variables::, for
7647 more information about debugging optimized code.
7651 * Inline Functions:: How GDB presents inlining
7654 File: gdb.info, Node: Inline Functions, Up: Optimized Code
7656 11.1 Inline Functions
7657 =====================
7659 "Inlining" is an optimization that inserts a copy of the function body
7660 directly at each call site, instead of jumping to a shared routine.
7661 GDB displays inlined functions just like non-inlined functions. They
7662 appear in backtraces. You can view their arguments and local
7663 variables, step into them with `step', skip them with `next', and
7664 escape from them with `finish'. You can check whether a function was
7665 inlined by using the `info frame' command.
7667 For GDB to support inlined functions, the compiler must record
7668 information about inlining in the debug information -- GCC using the
7669 DWARF 2 format does this, and several other compilers do also. GDB
7670 only supports inlined functions when using DWARF 2. Versions of GCC
7671 before 4.1 do not emit two required attributes (`DW_AT_call_file' and
7672 `DW_AT_call_line'); GDB does not display inlined function calls with
7673 earlier versions of GCC. It instead displays the arguments and local
7674 variables of inlined functions as local variables in the caller.
7676 The body of an inlined function is directly included at its call
7677 site; unlike a non-inlined function, there are no instructions devoted
7678 to the call. GDB still pretends that the call site and the start of
7679 the inlined function are different instructions. Stepping to the call
7680 site shows the call site, and then stepping again shows the first line
7681 of the inlined function, even though no additional instructions are
7684 This makes source-level debugging much clearer; you can see both the
7685 context of the call and then the effect of the call. Only stepping by
7686 a single instruction using `stepi' or `nexti' does not do this; single
7687 instruction steps always show the inlined body.
7689 There are some ways that GDB does not pretend that inlined function
7690 calls are the same as normal calls:
7692 * You cannot set breakpoints on inlined functions. GDB either
7693 reports that there is no symbol with that name, or else sets the
7694 breakpoint only on non-inlined copies of the function. This
7695 limitation will be removed in a future version of GDB; until then,
7696 set a breakpoint by line number on the first line of the inlined
7699 * Setting breakpoints at the call site of an inlined function may not
7700 work, because the call site does not contain any code. GDB may
7701 incorrectly move the breakpoint to the next line of the enclosing
7702 function, after the call. This limitation will be removed in a
7703 future version of GDB; until then, set a breakpoint on an earlier
7704 line or inside the inlined function instead.
7706 * GDB cannot locate the return value of inlined calls after using
7707 the `finish' command. This is a limitation of compiler-generated
7708 debugging information; after `finish', you can step to the next
7709 line and print a variable where your program stored the return
7714 File: gdb.info, Node: Macros, Next: Tracepoints, Prev: Optimized Code, Up: Top
7716 12 C Preprocessor Macros
7717 ************************
7719 Some languages, such as C and C++, provide a way to define and invoke
7720 "preprocessor macros" which expand into strings of tokens. GDB can
7721 evaluate expressions containing macro invocations, show the result of
7722 macro expansion, and show a macro's definition, including where it was
7725 You may need to compile your program specially to provide GDB with
7726 information about preprocessor macros. Most compilers do not include
7727 macros in their debugging information, even when you compile with the
7728 `-g' flag. *Note Compilation::.
7730 A program may define a macro at one point, remove that definition
7731 later, and then provide a different definition after that. Thus, at
7732 different points in the program, a macro may have different
7733 definitions, or have no definition at all. If there is a current stack
7734 frame, GDB uses the macros in scope at that frame's source code line.
7735 Otherwise, GDB uses the macros in scope at the current listing location;
7738 Whenever GDB evaluates an expression, it always expands any macro
7739 invocations present in the expression. GDB also provides the following
7740 commands for working with macros explicitly.
7742 `macro expand EXPRESSION'
7743 `macro exp EXPRESSION'
7744 Show the results of expanding all preprocessor macro invocations in
7745 EXPRESSION. Since GDB simply expands macros, but does not parse
7746 the result, EXPRESSION need not be a valid expression; it can be
7747 any string of tokens.
7749 `macro expand-once EXPRESSION'
7750 `macro exp1 EXPRESSION'
7751 (This command is not yet implemented.) Show the results of
7752 expanding those preprocessor macro invocations that appear
7753 explicitly in EXPRESSION. Macro invocations appearing in that
7754 expansion are left unchanged. This command allows you to see the
7755 effect of a particular macro more clearly, without being confused
7756 by further expansions. Since GDB simply expands macros, but does
7757 not parse the result, EXPRESSION need not be a valid expression; it
7758 can be any string of tokens.
7761 Show the definition of the macro named MACRO, and describe the
7762 source location or compiler command-line where that definition was
7765 `macro define MACRO REPLACEMENT-LIST'
7766 `macro define MACRO(ARGLIST) REPLACEMENT-LIST'
7767 Introduce a definition for a preprocessor macro named MACRO,
7768 invocations of which are replaced by the tokens given in
7769 REPLACEMENT-LIST. The first form of this command defines an
7770 "object-like" macro, which takes no arguments; the second form
7771 defines a "function-like" macro, which takes the arguments given in
7774 A definition introduced by this command is in scope in every
7775 expression evaluated in GDB, until it is removed with the `macro
7776 undef' command, described below. The definition overrides all
7777 definitions for MACRO present in the program being debugged, as
7778 well as any previous user-supplied definition.
7781 Remove any user-supplied definition for the macro named MACRO.
7782 This command only affects definitions provided with the `macro
7783 define' command, described above; it cannot remove definitions
7784 present in the program being debugged.
7787 List all the macros defined using the `macro define' command.
7789 Here is a transcript showing the above commands in action. First, we
7790 show our source files:
7797 #define ADD(x) (M + x)
7802 printf ("Hello, world!\n");
7804 printf ("We're so creative.\n");
7806 printf ("Goodbye, world!\n");
7812 Now, we compile the program using the GNU C compiler, GCC. We pass
7813 the `-gdwarf-2' and `-g3' flags to ensure the compiler includes
7814 information about preprocessor macros in the debugging information.
7816 $ gcc -gdwarf-2 -g3 sample.c -o sample
7819 Now, we start GDB on our sample program:
7822 GNU gdb 2002-05-06-cvs
7823 Copyright 2002 Free Software Foundation, Inc.
7824 GDB is free software, ...
7827 We can expand macros and examine their definitions, even when the
7828 program is not running. GDB uses the current listing position to
7829 decide which macro definitions are in scope:
7834 5 #define ADD(x) (M + x)
7839 10 printf ("Hello, world!\n");
7841 12 printf ("We're so creative.\n");
7842 (gdb) info macro ADD
7843 Defined at /home/jimb/gdb/macros/play/sample.c:5
7844 #define ADD(x) (M + x)
7846 Defined at /home/jimb/gdb/macros/play/sample.h:1
7847 included at /home/jimb/gdb/macros/play/sample.c:2
7849 (gdb) macro expand ADD(1)
7850 expands to: (42 + 1)
7851 (gdb) macro expand-once ADD(1)
7852 expands to: once (M + 1)
7855 In the example above, note that `macro expand-once' expands only the
7856 macro invocation explicit in the original text -- the invocation of
7857 `ADD' -- but does not expand the invocation of the macro `M', which was
7858 introduced by `ADD'.
7860 Once the program is running, GDB uses the macro definitions in force
7861 at the source line of the current stack frame:
7864 Breakpoint 1 at 0x8048370: file sample.c, line 10.
7866 Starting program: /home/jimb/gdb/macros/play/sample
7868 Breakpoint 1, main () at sample.c:10
7869 10 printf ("Hello, world!\n");
7872 At line 10, the definition of the macro `N' at line 9 is in force:
7875 Defined at /home/jimb/gdb/macros/play/sample.c:9
7877 (gdb) macro expand N Q M
7883 As we step over directives that remove `N''s definition, and then
7884 give it a new definition, GDB finds the definition (or lack thereof) in
7885 force at each point:
7889 12 printf ("We're so creative.\n");
7891 The symbol `N' has no definition as a C/C++ preprocessor macro
7892 at /home/jimb/gdb/macros/play/sample.c:12
7895 14 printf ("Goodbye, world!\n");
7897 Defined at /home/jimb/gdb/macros/play/sample.c:13
7899 (gdb) macro expand N Q M
7900 expands to: 1729 < 42
7905 In addition to source files, macros can be defined on the
7906 compilation command line using the `-DNAME=VALUE' syntax. For macros
7907 defined in such a way, GDB displays the location of their definition as
7908 line zero of the source file submitted to the compiler.
7910 (gdb) info macro __STDC__
7911 Defined at /home/jimb/gdb/macros/play/sample.c:0
7916 File: gdb.info, Node: Tracepoints, Next: Overlays, Prev: Macros, Up: Top
7921 In some applications, it is not feasible for the debugger to interrupt
7922 the program's execution long enough for the developer to learn anything
7923 helpful about its behavior. If the program's correctness depends on
7924 its real-time behavior, delays introduced by a debugger might cause the
7925 program to change its behavior drastically, or perhaps fail, even when
7926 the code itself is correct. It is useful to be able to observe the
7927 program's behavior without interrupting it.
7929 Using GDB's `trace' and `collect' commands, you can specify
7930 locations in the program, called "tracepoints", and arbitrary
7931 expressions to evaluate when those tracepoints are reached. Later,
7932 using the `tfind' command, you can examine the values those expressions
7933 had when the program hit the tracepoints. The expressions may also
7934 denote objects in memory--structures or arrays, for example--whose
7935 values GDB should record; while visiting a particular tracepoint, you
7936 may inspect those objects as if they were in memory at that moment.
7937 However, because GDB records these values without interacting with you,
7938 it can do so quickly and unobtrusively, hopefully not disturbing the
7941 The tracepoint facility is currently available only for remote
7942 targets. *Note Targets::. In addition, your remote target must know
7943 how to collect trace data. This functionality is implemented in the
7944 remote stub; however, none of the stubs distributed with GDB support
7945 tracepoints as of this writing. The format of the remote packets used
7946 to implement tracepoints are described in *note Tracepoint Packets::.
7948 It is also possible to get trace data from a file, in a manner
7949 reminiscent of corefiles; you specify the filename, and use `tfind' to
7950 search through the file. *Note Trace Files::, for more details.
7952 This chapter describes the tracepoint commands and features.
7957 * Analyze Collected Data::
7958 * Tracepoint Variables::
7962 File: gdb.info, Node: Set Tracepoints, Next: Analyze Collected Data, Up: Tracepoints
7964 13.1 Commands to Set Tracepoints
7965 ================================
7967 Before running such a "trace experiment", an arbitrary number of
7968 tracepoints can be set. A tracepoint is actually a special type of
7969 breakpoint (*note Set Breaks::), so you can manipulate it using
7970 standard breakpoint commands. For instance, as with breakpoints,
7971 tracepoint numbers are successive integers starting from one, and many
7972 of the commands associated with tracepoints take the tracepoint number
7973 as their argument, to identify which tracepoint to work on.
7975 For each tracepoint, you can specify, in advance, some arbitrary set
7976 of data that you want the target to collect in the trace buffer when it
7977 hits that tracepoint. The collected data can include registers, local
7978 variables, or global data. Later, you can use GDB commands to examine
7979 the values these data had at the time the tracepoint was hit.
7981 Tracepoints do not support every breakpoint feature. Conditional
7982 expressions and ignore counts on tracepoints have no effect, and
7983 tracepoints cannot run GDB commands when they are hit. Tracepoints may
7984 not be thread-specific either.
7986 Some targets may support "fast tracepoints", which are inserted in a
7987 different way (such as with a jump instead of a trap), that is faster
7988 but possibly restricted in where they may be installed.
7990 This section describes commands to set tracepoints and associated
7991 conditions and actions.
7995 * Create and Delete Tracepoints::
7996 * Enable and Disable Tracepoints::
7997 * Tracepoint Passcounts::
7998 * Tracepoint Conditions::
7999 * Trace State Variables::
8000 * Tracepoint Actions::
8001 * Listing Tracepoints::
8002 * Starting and Stopping Trace Experiments::
8005 File: gdb.info, Node: Create and Delete Tracepoints, Next: Enable and Disable Tracepoints, Up: Set Tracepoints
8007 13.1.1 Create and Delete Tracepoints
8008 ------------------------------------
8011 The `trace' command is very similar to the `break' command. Its
8012 argument LOCATION can be a source line, a function name, or an
8013 address in the target program. *Note Specify Location::. The
8014 `trace' command defines a tracepoint, which is a point in the
8015 target program where the debugger will briefly stop, collect some
8016 data, and then allow the program to continue. Setting a
8017 tracepoint or changing its actions doesn't take effect until the
8018 next `tstart' command, and once a trace experiment is running,
8019 further changes will not have any effect until the next trace
8022 Here are some examples of using the `trace' command:
8024 (gdb) trace foo.c:121 // a source file and line number
8026 (gdb) trace +2 // 2 lines forward
8028 (gdb) trace my_function // first source line of function
8030 (gdb) trace *my_function // EXACT start address of function
8032 (gdb) trace *0x2117c4 // an address
8034 You can abbreviate `trace' as `tr'.
8036 `trace LOCATION if COND'
8037 Set a tracepoint with condition COND; evaluate the expression COND
8038 each time the tracepoint is reached, and collect data only if the
8039 value is nonzero--that is, if COND evaluates as true. *Note
8040 Tracepoint Conditions: Tracepoint Conditions, for more information
8041 on tracepoint conditions.
8043 `ftrace LOCATION [ if COND ]'
8044 The `ftrace' command sets a fast tracepoint. For targets that
8045 support them, fast tracepoints will use a more efficient but
8046 possibly less general technique to trigger data collection, such
8047 as a jump instruction instead of a trap, or some sort of hardware
8048 support. It may not be possible to create a fast tracepoint at
8049 the desired location, in which case the command will exit with an
8050 explanatory message.
8052 GDB handles arguments to `ftrace' exactly as for `trace'.
8054 The convenience variable `$tpnum' records the tracepoint number of
8055 the most recently set tracepoint.
8057 `delete tracepoint [NUM]'
8058 Permanently delete one or more tracepoints. With no argument, the
8059 default is to delete all tracepoints. Note that the regular
8060 `delete' command can remove tracepoints also.
8064 (gdb) delete trace 1 2 3 // remove three tracepoints
8066 (gdb) delete trace // remove all tracepoints
8068 You can abbreviate this command as `del tr'.
8071 File: gdb.info, Node: Enable and Disable Tracepoints, Next: Tracepoint Passcounts, Prev: Create and Delete Tracepoints, Up: Set Tracepoints
8073 13.1.2 Enable and Disable Tracepoints
8074 -------------------------------------
8076 These commands are deprecated; they are equivalent to plain `disable'
8079 `disable tracepoint [NUM]'
8080 Disable tracepoint NUM, or all tracepoints if no argument NUM is
8081 given. A disabled tracepoint will have no effect during the next
8082 trace experiment, but it is not forgotten. You can re-enable a
8083 disabled tracepoint using the `enable tracepoint' command.
8085 `enable tracepoint [NUM]'
8086 Enable tracepoint NUM, or all tracepoints. The enabled
8087 tracepoints will become effective the next time a trace experiment
8091 File: gdb.info, Node: Tracepoint Passcounts, Next: Tracepoint Conditions, Prev: Enable and Disable Tracepoints, Up: Set Tracepoints
8093 13.1.3 Tracepoint Passcounts
8094 ----------------------------
8096 `passcount [N [NUM]]'
8097 Set the "passcount" of a tracepoint. The passcount is a way to
8098 automatically stop a trace experiment. If a tracepoint's
8099 passcount is N, then the trace experiment will be automatically
8100 stopped on the N'th time that tracepoint is hit. If the
8101 tracepoint number NUM is not specified, the `passcount' command
8102 sets the passcount of the most recently defined tracepoint. If no
8103 passcount is given, the trace experiment will run until stopped
8104 explicitly by the user.
8108 (gdb) passcount 5 2 // Stop on the 5th execution of
8111 (gdb) passcount 12 // Stop on the 12th execution of the
8112 `// most recently defined tracepoint.'
8118 (gdb) pass 1 // Stop tracing when foo has been
8119 `// executed 3 times OR when bar has'
8120 `// been executed 2 times'
8121 `// OR when baz has been executed 1 time.'
8125 File: gdb.info, Node: Tracepoint Conditions, Next: Trace State Variables, Prev: Tracepoint Passcounts, Up: Set Tracepoints
8127 13.1.4 Tracepoint Conditions
8128 ----------------------------
8130 The simplest sort of tracepoint collects data every time your program
8131 reaches a specified place. You can also specify a "condition" for a
8132 tracepoint. A condition is just a Boolean expression in your
8133 programming language (*note Expressions: Expressions.). A tracepoint
8134 with a condition evaluates the expression each time your program
8135 reaches it, and data collection happens only if the condition is true.
8137 Tracepoint conditions can be specified when a tracepoint is set, by
8138 using `if' in the arguments to the `trace' command. *Note Setting
8139 Tracepoints: Create and Delete Tracepoints. They can also be set or
8140 changed at any time with the `condition' command, just as with
8143 Unlike breakpoint conditions, GDB does not actually evaluate the
8144 conditional expression itself. Instead, GDB encodes the expression
8145 into an agent expression (*note Agent Expressions:: suitable for
8146 execution on the target, independently of GDB. Global variables become
8147 raw memory locations, locals become stack accesses, and so forth.
8149 For instance, suppose you have a function that is usually called
8150 frequently, but should not be called after an error has occurred. You
8151 could use the following tracepoint command to collect data about calls
8152 of that function that happen while the error code is propagating
8153 through the program; an unconditional tracepoint could end up
8154 collecting thousands of useless trace frames that you would have to
8157 (gdb) trace normal_operation if errcode > 0
8160 File: gdb.info, Node: Trace State Variables, Next: Tracepoint Actions, Prev: Tracepoint Conditions, Up: Set Tracepoints
8162 13.1.5 Trace State Variables
8163 ----------------------------
8165 A "trace state variable" is a special type of variable that is created
8166 and managed by target-side code. The syntax is the same as that for
8167 GDB's convenience variables (a string prefixed with "$"), but they are
8168 stored on the target. They must be created explicitly, using a
8169 `tvariable' command. They are always 64-bit signed integers.
8171 Trace state variables are remembered by GDB, and downloaded to the
8172 target along with tracepoint information when the trace experiment
8173 starts. There are no intrinsic limits on the number of trace state
8174 variables, beyond memory limitations of the target.
8176 Although trace state variables are managed by the target, you can use
8177 them in print commands and expressions as if they were convenience
8178 variables; GDB will get the current value from the target while the
8179 trace experiment is running. Trace state variables share the same
8180 namespace as other "$" variables, which means that you cannot have
8181 trace state variables with names like `$23' or `$pc', nor can you have
8182 a trace state variable and a convenience variable with the same name.
8184 `tvariable $NAME [ = EXPRESSION ]'
8185 The `tvariable' command creates a new trace state variable named
8186 `$NAME', and optionally gives it an initial value of EXPRESSION.
8187 EXPRESSION is evaluated when this command is entered; the result
8188 will be converted to an integer if possible, otherwise GDB will
8189 report an error. A subsequent `tvariable' command specifying the
8190 same name does not create a variable, but instead assigns the
8191 supplied initial value to the existing variable of that name,
8192 overwriting any previous initial value. The default initial value
8196 List all the trace state variables along with their initial values.
8197 Their current values may also be displayed, if the trace
8198 experiment is currently running.
8200 `delete tvariable [ $NAME ... ]'
8201 Delete the given trace state variables, or all of them if no
8202 arguments are specified.
8206 File: gdb.info, Node: Tracepoint Actions, Next: Listing Tracepoints, Prev: Trace State Variables, Up: Set Tracepoints
8208 13.1.6 Tracepoint Action Lists
8209 ------------------------------
8212 This command will prompt for a list of actions to be taken when the
8213 tracepoint is hit. If the tracepoint number NUM is not specified,
8214 this command sets the actions for the one that was most recently
8215 defined (so that you can define a tracepoint and then say
8216 `actions' without bothering about its number). You specify the
8217 actions themselves on the following lines, one action at a time,
8218 and terminate the actions list with a line containing just `end'.
8219 So far, the only defined actions are `collect' and
8222 To remove all actions from a tracepoint, type `actions NUM' and
8223 follow it immediately with `end'.
8225 (gdb) collect DATA // collect some data
8227 (gdb) while-stepping 5 // single-step 5 times, collect data
8229 (gdb) end // signals the end of actions.
8231 In the following example, the action list begins with `collect'
8232 commands indicating the things to be collected when the tracepoint
8233 is hit. Then, in order to single-step and collect additional data
8234 following the tracepoint, a `while-stepping' command is used,
8235 followed by the list of things to be collected while stepping. The
8236 `while-stepping' command is terminated by its own separate `end'
8237 command. Lastly, the action list is terminated by an `end'
8242 Enter actions for tracepoint 1, one per line:
8250 `collect EXPR1, EXPR2, ...'
8251 Collect values of the given expressions when the tracepoint is hit.
8252 This command accepts a comma-separated list of any valid
8253 expressions. In addition to global, static, or local variables,
8254 the following special arguments are supported:
8257 collect all registers
8260 collect all function arguments
8263 collect all local variables.
8265 You can give several consecutive `collect' commands, each one with
8266 a single argument, or one `collect' command with several arguments
8267 separated by commas: the effect is the same.
8269 The command `info scope' (*note info scope: Symbols.) is
8270 particularly useful for figuring out what data to collect.
8272 `teval EXPR1, EXPR2, ...'
8273 Evaluate the given expressions when the tracepoint is hit. This
8274 command accepts a comma-separated list of expressions. The results
8275 are discarded, so this is mainly useful for assigning values to
8276 trace state variables (*note Trace State Variables::) without
8277 adding those values to the trace buffer, as would be the case if
8278 the `collect' action were used.
8281 Perform N single-step traces after the tracepoint, collecting new
8282 data at each step. The `while-stepping' command is followed by
8283 the list of what to collect while stepping (followed by its own
8287 > collect $regs, myglobal
8291 You may abbreviate `while-stepping' as `ws' or `stepping'.
8293 `set default-collect EXPR1, EXPR2, ...'
8294 This variable is a list of expressions to collect at each
8295 tracepoint hit. It is effectively an additional `collect' action
8296 prepended to every tracepoint action list. The expressions are
8297 parsed individually for each tracepoint, so for instance a
8298 variable named `xyz' may be interpreted as a global for one
8299 tracepoint, and a local for another, as appropriate to the
8300 tracepoint's location.
8302 `show default-collect'
8303 Show the list of expressions that are collected by default at each
8308 File: gdb.info, Node: Listing Tracepoints, Next: Starting and Stopping Trace Experiments, Prev: Tracepoint Actions, Up: Set Tracepoints
8310 13.1.7 Listing Tracepoints
8311 --------------------------
8313 `info tracepoints [NUM]'
8314 Display information about the tracepoint NUM. If you don't
8315 specify a tracepoint number, displays information about all the
8316 tracepoints defined so far. The format is similar to that used for
8317 `info breakpoints'; in fact, `info tracepoints' is the same
8318 command, simply restricting itself to tracepoints.
8320 A tracepoint's listing may include additional information specific
8323 * its passcount as given by the `passcount N' command
8325 * its step count as given by the `while-stepping N' command
8327 * its action list as given by the `actions' command. The
8328 actions are prefixed with an `A' so as to distinguish them
8332 Num Type Disp Enb Address What
8333 1 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7
8337 A collect globfoo, $regs
8343 This command can be abbreviated `info tp'.
8346 File: gdb.info, Node: Starting and Stopping Trace Experiments, Prev: Listing Tracepoints, Up: Set Tracepoints
8348 13.1.8 Starting and Stopping Trace Experiments
8349 ----------------------------------------------
8352 This command takes no arguments. It starts the trace experiment,
8353 and begins collecting data. This has the side effect of
8354 discarding all the data collected in the trace buffer during the
8355 previous trace experiment.
8358 This command takes no arguments. It ends the trace experiment, and
8359 stops collecting data.
8361 *Note*: a trace experiment and data collection may stop
8362 automatically if any tracepoint's passcount is reached (*note
8363 Tracepoint Passcounts::), or if the trace buffer becomes full.
8366 This command displays the status of the current trace data
8369 Here is an example of the commands we described so far:
8371 (gdb) trace gdb_c_test
8373 Enter actions for tracepoint #1, one per line.
8374 > collect $regs,$locals,$args
8383 You can choose to continue running the trace experiment even if GDB
8384 disconnects from the target, voluntarily or involuntarily. For
8385 commands such as `detach', the debugger will ask what you want to do
8386 with the trace. But for unexpected terminations (GDB crash, network
8387 outage), it would be unfortunate to lose hard-won trace data, so the
8388 variable `disconnected-tracing' lets you decide whether the trace should
8389 continue running without GDB.
8391 `set disconnected-tracing on'
8392 `set disconnected-tracing off'
8393 Choose whether a tracing run should continue to run if GDB has
8394 disconnected from the target. Note that `detach' or `quit' will
8395 ask you directly what to do about a running trace no matter what
8396 this variable's setting, so the variable is mainly useful for
8397 handling unexpected situations, such as loss of the network.
8399 `show disconnected-tracing'
8400 Show the current choice for disconnected tracing.
8403 When you reconnect to the target, the trace experiment may or may not
8404 still be running; it might have filled the trace buffer in the
8405 meantime, or stopped for one of the other reasons. If it is running,
8406 it will continue after reconnection.
8408 Upon reconnection, the target will upload information about the
8409 tracepoints in effect. GDB will then compare that information to the
8410 set of tracepoints currently defined, and attempt to match them up,
8411 allowing for the possibility that the numbers may have changed due to
8412 creation and deletion in the meantime. If one of the target's
8413 tracepoints does not match any in GDB, the debugger will create a new
8414 tracepoint, so that you have a number with which to specify that
8415 tracepoint. This matching-up process is necessarily heuristic, and it
8416 may result in useless tracepoints being created; you may simply delete
8417 them if they are of no use.
8420 File: gdb.info, Node: Analyze Collected Data, Next: Tracepoint Variables, Prev: Set Tracepoints, Up: Tracepoints
8422 13.2 Using the Collected Data
8423 =============================
8425 After the tracepoint experiment ends, you use GDB commands for
8426 examining the trace data. The basic idea is that each tracepoint
8427 collects a trace "snapshot" every time it is hit and another snapshot
8428 every time it single-steps. All these snapshots are consecutively
8429 numbered from zero and go into a buffer, and you can examine them
8430 later. The way you examine them is to "focus" on a specific trace
8431 snapshot. When the remote stub is focused on a trace snapshot, it will
8432 respond to all GDB requests for memory and registers by reading from
8433 the buffer which belongs to that snapshot, rather than from _real_
8434 memory or registers of the program being debugged. This means that
8435 *all* GDB commands (`print', `info registers', `backtrace', etc.) will
8436 behave as if we were currently debugging the program state as it was
8437 when the tracepoint occurred. Any requests for data that are not in
8438 the buffer will fail.
8442 * tfind:: How to select a trace snapshot
8443 * tdump:: How to display all data for a snapshot
8444 * save-tracepoints:: How to save tracepoints for a future run
8447 File: gdb.info, Node: tfind, Next: tdump, Up: Analyze Collected Data
8452 The basic command for selecting a trace snapshot from the buffer is
8453 `tfind N', which finds trace snapshot number N, counting from zero. If
8454 no argument N is given, the next snapshot is selected.
8456 Here are the various forms of using the `tfind' command.
8459 Find the first snapshot in the buffer. This is a synonym for
8460 `tfind 0' (since 0 is the number of the first snapshot).
8463 Stop debugging trace snapshots, resume _live_ debugging.
8466 Same as `tfind none'.
8469 No argument means find the next trace snapshot.
8472 Find the previous trace snapshot before the current one. This
8473 permits retracing earlier steps.
8475 `tfind tracepoint NUM'
8476 Find the next snapshot associated with tracepoint NUM. Search
8477 proceeds forward from the last examined trace snapshot. If no
8478 argument NUM is given, it means find the next snapshot collected
8479 for the same tracepoint as the current snapshot.
8482 Find the next snapshot associated with the value ADDR of the
8483 program counter. Search proceeds forward from the last examined
8484 trace snapshot. If no argument ADDR is given, it means find the
8485 next snapshot with the same value of PC as the current snapshot.
8487 `tfind outside ADDR1, ADDR2'
8488 Find the next snapshot whose PC is outside the given range of
8489 addresses (exclusive).
8491 `tfind range ADDR1, ADDR2'
8492 Find the next snapshot whose PC is between ADDR1 and ADDR2
8495 `tfind line [FILE:]N'
8496 Find the next snapshot associated with the source line N. If the
8497 optional argument FILE is given, refer to line N in that source
8498 file. Search proceeds forward from the last examined trace
8499 snapshot. If no argument N is given, it means find the next line
8500 other than the one currently being examined; thus saying `tfind
8501 line' repeatedly can appear to have the same effect as stepping
8502 from line to line in a _live_ debugging session.
8504 The default arguments for the `tfind' commands are specifically
8505 designed to make it easy to scan through the trace buffer. For
8506 instance, `tfind' with no argument selects the next trace snapshot, and
8507 `tfind -' with no argument selects the previous trace snapshot. So, by
8508 giving one `tfind' command, and then simply hitting <RET> repeatedly
8509 you can examine all the trace snapshots in order. Or, by saying `tfind
8510 -' and then hitting <RET> repeatedly you can examine the snapshots in
8511 reverse order. The `tfind line' command with no argument selects the
8512 snapshot for the next source line executed. The `tfind pc' command with
8513 no argument selects the next snapshot with the same program counter
8514 (PC) as the current frame. The `tfind tracepoint' command with no
8515 argument selects the next trace snapshot collected by the same
8516 tracepoint as the current one.
8518 In addition to letting you scan through the trace buffer manually,
8519 these commands make it easy to construct GDB scripts that scan through
8520 the trace buffer and print out whatever collected data you are
8521 interested in. Thus, if we want to examine the PC, FP, and SP
8522 registers from each trace frame in the buffer, we can say this:
8525 (gdb) while ($trace_frame != -1)
8526 > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \
8527 $trace_frame, $pc, $sp, $fp
8531 Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44
8532 Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44
8533 Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44
8534 Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44
8535 Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44
8536 Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44
8537 Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44
8538 Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44
8539 Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44
8540 Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44
8541 Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14
8543 Or, if we want to examine the variable `X' at each source line in
8547 (gdb) while ($trace_frame != -1)
8548 > printf "Frame %d, X == %d\n", $trace_frame, X
8557 File: gdb.info, Node: tdump, Next: save-tracepoints, Prev: tfind, Up: Analyze Collected Data
8562 This command takes no arguments. It prints all the data collected at
8563 the current trace snapshot.
8567 Enter actions for tracepoint #2, one per line:
8568 > collect $regs, $locals, $args, gdb_long_test
8573 (gdb) tfind line 444
8574 #0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66)
8576 444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", )
8579 Data collected at tracepoint 2, trace frame 1:
8580 d0 0xc4aa0085 -995491707
8584 d4 0x71aea3d 119204413
8589 a1 0x3000668 50333288
8592 a4 0x3000698 50333336
8594 fp 0x30bf3c 0x30bf3c
8595 sp 0x30bf34 0x30bf34
8597 pc 0x20b2c8 0x20b2c8
8601 p = 0x20e5b4 "gdb-test"
8608 gdb_long_test = 17 '\021'
8613 File: gdb.info, Node: save-tracepoints, Prev: tdump, Up: Analyze Collected Data
8615 13.2.3 `save-tracepoints FILENAME'
8616 ----------------------------------
8618 This command saves all current tracepoint definitions together with
8619 their actions and passcounts, into a file `FILENAME' suitable for use
8620 in a later debugging session. To read the saved tracepoint
8621 definitions, use the `source' command (*note Command Files::).
8624 File: gdb.info, Node: Tracepoint Variables, Next: Trace Files, Prev: Analyze Collected Data, Up: Tracepoints
8626 13.3 Convenience Variables for Tracepoints
8627 ==========================================
8629 `(int) $trace_frame'
8630 The current trace snapshot (a.k.a. "frame") number, or -1 if no
8631 snapshot is selected.
8634 The tracepoint for the current trace snapshot.
8637 The line number for the current trace snapshot.
8639 `(char []) $trace_file'
8640 The source file for the current trace snapshot.
8642 `(char []) $trace_func'
8643 The name of the function containing `$tracepoint'.
8645 Note: `$trace_file' is not suitable for use in `printf', use
8648 Here's a simple example of using these convenience variables for
8649 stepping through all the trace snapshots and printing some of their
8650 data. Note that these are not the same as trace state variables, which
8651 are managed by the target.
8655 (gdb) while $trace_frame != -1
8656 > output $trace_file
8657 > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint
8662 File: gdb.info, Node: Trace Files, Prev: Tracepoint Variables, Up: Tracepoints
8664 13.4 Using Trace Files
8665 ======================
8667 In some situations, the target running a trace experiment may no longer
8668 be available; perhaps it crashed, or the hardware was needed for a
8669 different activity. To handle these cases, you can arrange to dump the
8670 trace data into a file, and later use that file as a source of trace
8671 data, via the `target tfile' command.
8673 `tsave [ -r ] FILENAME'
8674 Save the trace data to FILENAME. By default, this command assumes
8675 that FILENAME refers to the host filesystem, so if necessary GDB
8676 will copy raw trace data up from the target and then save it. If
8677 the target supports it, you can also supply the optional argument
8678 `-r' ("remote") to direct the target to save the data directly
8679 into FILENAME in its own filesystem, which may be more efficient
8680 if the trace buffer is very large. (Note, however, that `target
8681 tfile' can only read from files accessible to the host.)
8683 `target tfile FILENAME'
8684 Use the file named FILENAME as a source of trace data. Commands
8685 that examine data work as they do with a live target, but it is not
8686 possible to run any new trace experiments. `tstatus' will report
8687 the state of the trace run at the moment the data was saved, as
8688 well as the current trace frame you are examining. FILENAME must
8689 be on a filesystem accessible to the host.
8693 File: gdb.info, Node: Overlays, Next: Languages, Prev: Tracepoints, Up: Top
8695 14 Debugging Programs That Use Overlays
8696 ***************************************
8698 If your program is too large to fit completely in your target system's
8699 memory, you can sometimes use "overlays" to work around this problem.
8700 GDB provides some support for debugging programs that use overlays.
8704 * How Overlays Work:: A general explanation of overlays.
8705 * Overlay Commands:: Managing overlays in GDB.
8706 * Automatic Overlay Debugging:: GDB can find out which overlays are
8707 mapped by asking the inferior.
8708 * Overlay Sample Program:: A sample program using overlays.
8711 File: gdb.info, Node: How Overlays Work, Next: Overlay Commands, Up: Overlays
8713 14.1 How Overlays Work
8714 ======================
8716 Suppose you have a computer whose instruction address space is only 64
8717 kilobytes long, but which has much more memory which can be accessed by
8718 other means: special instructions, segment registers, or memory
8719 management hardware, for example. Suppose further that you want to
8720 adapt a program which is larger than 64 kilobytes to run on this system.
8722 One solution is to identify modules of your program which are
8723 relatively independent, and need not call each other directly; call
8724 these modules "overlays". Separate the overlays from the main program,
8725 and place their machine code in the larger memory. Place your main
8726 program in instruction memory, but leave at least enough space there to
8727 hold the largest overlay as well.
8729 Now, to call a function located in an overlay, you must first copy
8730 that overlay's machine code from the large memory into the space set
8731 aside for it in the instruction memory, and then jump to its entry point
8734 Data Instruction Larger
8735 Address Space Address Space Address Space
8736 +-----------+ +-----------+ +-----------+
8738 +-----------+ +-----------+ +-----------+<-- overlay 1
8739 | program | | main | .----| overlay 1 | load address
8740 | variables | | program | | +-----------+
8741 | and heap | | | | | |
8742 +-----------+ | | | +-----------+<-- overlay 2
8743 | | +-----------+ | | | load address
8744 +-----------+ | | | .-| overlay 2 |
8746 mapped --->+-----------+ | | +-----------+
8748 | overlay | <-' | | |
8749 | area | <---' +-----------+<-- overlay 3
8750 | | <---. | | load address
8751 +-----------+ `--| overlay 3 |
8760 The diagram (*note A code overlay::) shows a system with separate
8761 data and instruction address spaces. To map an overlay, the program
8762 copies its code from the larger address space to the instruction
8763 address space. Since the overlays shown here all use the same mapped
8764 address, only one may be mapped at a time. For a system with a single
8765 address space for data and instructions, the diagram would be similar,
8766 except that the program variables and heap would share an address space
8767 with the main program and the overlay area.
8769 An overlay loaded into instruction memory and ready for use is
8770 called a "mapped" overlay; its "mapped address" is its address in the
8771 instruction memory. An overlay not present (or only partially present)
8772 in instruction memory is called "unmapped"; its "load address" is its
8773 address in the larger memory. The mapped address is also called the
8774 "virtual memory address", or "VMA"; the load address is also called the
8775 "load memory address", or "LMA".
8777 Unfortunately, overlays are not a completely transparent way to
8778 adapt a program to limited instruction memory. They introduce a new
8779 set of global constraints you must keep in mind as you design your
8782 * Before calling or returning to a function in an overlay, your
8783 program must make sure that overlay is actually mapped.
8784 Otherwise, the call or return will transfer control to the right
8785 address, but in the wrong overlay, and your program will probably
8788 * If the process of mapping an overlay is expensive on your system,
8789 you will need to choose your overlays carefully to minimize their
8790 effect on your program's performance.
8792 * The executable file you load onto your system must contain each
8793 overlay's instructions, appearing at the overlay's load address,
8794 not its mapped address. However, each overlay's instructions must
8795 be relocated and its symbols defined as if the overlay were at its
8796 mapped address. You can use GNU linker scripts to specify
8797 different load and relocation addresses for pieces of your
8798 program; see *note Overlay Description: (ld.info)Overlay
8801 * The procedure for loading executable files onto your system must
8802 be able to load their contents into the larger address space as
8803 well as the instruction and data spaces.
8806 The overlay system described above is rather simple, and could be
8807 improved in many ways:
8809 * If your system has suitable bank switch registers or memory
8810 management hardware, you could use those facilities to make an
8811 overlay's load area contents simply appear at their mapped address
8812 in instruction space. This would probably be faster than copying
8813 the overlay to its mapped area in the usual way.
8815 * If your overlays are small enough, you could set aside more than
8816 one overlay area, and have more than one overlay mapped at a time.
8818 * You can use overlays to manage data, as well as instructions. In
8819 general, data overlays are even less transparent to your design
8820 than code overlays: whereas code overlays only require care when
8821 you call or return to functions, data overlays require care every
8822 time you access the data. Also, if you change the contents of a
8823 data overlay, you must copy its contents back out to its load
8824 address before you can copy a different data overlay into the same
8829 File: gdb.info, Node: Overlay Commands, Next: Automatic Overlay Debugging, Prev: How Overlays Work, Up: Overlays
8831 14.2 Overlay Commands
8832 =====================
8834 To use GDB's overlay support, each overlay in your program must
8835 correspond to a separate section of the executable file. The section's
8836 virtual memory address and load memory address must be the overlay's
8837 mapped and load addresses. Identifying overlays with sections allows
8838 GDB to determine the appropriate address of a function or variable,
8839 depending on whether the overlay is mapped or not.
8841 GDB's overlay commands all start with the word `overlay'; you can
8842 abbreviate this as `ov' or `ovly'. The commands are:
8845 Disable GDB's overlay support. When overlay support is disabled,
8846 GDB assumes that all functions and variables are always present at
8847 their mapped addresses. By default, GDB's overlay support is
8851 Enable "manual" overlay debugging. In this mode, GDB relies on
8852 you to tell it which overlays are mapped, and which are not, using
8853 the `overlay map-overlay' and `overlay unmap-overlay' commands
8856 `overlay map-overlay OVERLAY'
8857 `overlay map OVERLAY'
8858 Tell GDB that OVERLAY is now mapped; OVERLAY must be the name of
8859 the object file section containing the overlay. When an overlay
8860 is mapped, GDB assumes it can find the overlay's functions and
8861 variables at their mapped addresses. GDB assumes that any other
8862 overlays whose mapped ranges overlap that of OVERLAY are now
8865 `overlay unmap-overlay OVERLAY'
8866 `overlay unmap OVERLAY'
8867 Tell GDB that OVERLAY is no longer mapped; OVERLAY must be the
8868 name of the object file section containing the overlay. When an
8869 overlay is unmapped, GDB assumes it can find the overlay's
8870 functions and variables at their load addresses.
8873 Enable "automatic" overlay debugging. In this mode, GDB consults
8874 a data structure the overlay manager maintains in the inferior to
8875 see which overlays are mapped. For details, see *note Automatic
8876 Overlay Debugging::.
8878 `overlay load-target'
8880 Re-read the overlay table from the inferior. Normally, GDB
8881 re-reads the table GDB automatically each time the inferior stops,
8882 so this command should only be necessary if you have changed the
8883 overlay mapping yourself using GDB. This command is only useful
8884 when using automatic overlay debugging.
8886 `overlay list-overlays'
8888 Display a list of the overlays currently mapped, along with their
8889 mapped addresses, load addresses, and sizes.
8892 Normally, when GDB prints a code address, it includes the name of
8893 the function the address falls in:
8896 $3 = {int ()} 0x11a0 <main>
8897 When overlay debugging is enabled, GDB recognizes code in unmapped
8898 overlays, and prints the names of unmapped functions with asterisks
8899 around them. For example, if `foo' is a function in an unmapped
8900 overlay, GDB prints it this way:
8903 No sections are mapped.
8905 $5 = {int (int)} 0x100000 <*foo*>
8906 When `foo''s overlay is mapped, GDB prints the function's name
8910 Section .ov.foo.text, loaded at 0x100000 - 0x100034,
8911 mapped at 0x1016 - 0x104a
8913 $6 = {int (int)} 0x1016 <foo>
8915 When overlay debugging is enabled, GDB can find the correct address
8916 for functions and variables in an overlay, whether or not the overlay
8917 is mapped. This allows most GDB commands, like `break' and
8918 `disassemble', to work normally, even on unmapped code. However, GDB's
8919 breakpoint support has some limitations:
8921 * You can set breakpoints in functions in unmapped overlays, as long
8922 as GDB can write to the overlay at its load address.
8924 * GDB can not set hardware or simulator-based breakpoints in
8925 unmapped overlays. However, if you set a breakpoint at the end of
8926 your overlay manager (and tell GDB which overlays are now mapped,
8927 if you are using manual overlay management), GDB will re-set its
8928 breakpoints properly.
8931 File: gdb.info, Node: Automatic Overlay Debugging, Next: Overlay Sample Program, Prev: Overlay Commands, Up: Overlays
8933 14.3 Automatic Overlay Debugging
8934 ================================
8936 GDB can automatically track which overlays are mapped and which are
8937 not, given some simple co-operation from the overlay manager in the
8938 inferior. If you enable automatic overlay debugging with the `overlay
8939 auto' command (*note Overlay Commands::), GDB looks in the inferior's
8940 memory for certain variables describing the current state of the
8943 Here are the variables your overlay manager must define to support
8944 GDB's automatic overlay debugging:
8947 This variable must be an array of the following structures:
8951 /* The overlay's mapped address. */
8954 /* The size of the overlay, in bytes. */
8957 /* The overlay's load address. */
8960 /* Non-zero if the overlay is currently mapped;
8962 unsigned long mapped;
8966 This variable must be a four-byte signed integer, holding the total
8967 number of elements in `_ovly_table'.
8970 To decide whether a particular overlay is mapped or not, GDB looks
8971 for an entry in `_ovly_table' whose `vma' and `lma' members equal the
8972 VMA and LMA of the overlay's section in the executable file. When GDB
8973 finds a matching entry, it consults the entry's `mapped' member to
8974 determine whether the overlay is currently mapped.
8976 In addition, your overlay manager may define a function called
8977 `_ovly_debug_event'. If this function is defined, GDB will silently
8978 set a breakpoint there. If the overlay manager then calls this
8979 function whenever it has changed the overlay table, this will enable
8980 GDB to accurately keep track of which overlays are in program memory,
8981 and update any breakpoints that may be set in overlays. This will
8982 allow breakpoints to work even if the overlays are kept in ROM or other
8983 non-writable memory while they are not being executed.
8986 File: gdb.info, Node: Overlay Sample Program, Prev: Automatic Overlay Debugging, Up: Overlays
8988 14.4 Overlay Sample Program
8989 ===========================
8991 When linking a program which uses overlays, you must place the overlays
8992 at their load addresses, while relocating them to run at their mapped
8993 addresses. To do this, you must write a linker script (*note Overlay
8994 Description: (ld.info)Overlay Description.). Unfortunately, since
8995 linker scripts are specific to a particular host system, target
8996 architecture, and target memory layout, this manual cannot provide
8997 portable sample code demonstrating GDB's overlay support.
8999 However, the GDB source distribution does contain an overlaid
9000 program, with linker scripts for a few systems, as part of its test
9001 suite. The program consists of the following files from
9002 `gdb/testsuite/gdb.base':
9005 The main program file.
9008 A simple overlay manager, used by `overlays.c'.
9014 Overlay modules, loaded and used by `overlays.c'.
9018 Linker scripts for linking the test program on the `d10v-elf' and
9021 You can build the test program using the `d10v-elf' GCC
9022 cross-compiler like this:
9024 $ d10v-elf-gcc -g -c overlays.c
9025 $ d10v-elf-gcc -g -c ovlymgr.c
9026 $ d10v-elf-gcc -g -c foo.c
9027 $ d10v-elf-gcc -g -c bar.c
9028 $ d10v-elf-gcc -g -c baz.c
9029 $ d10v-elf-gcc -g -c grbx.c
9030 $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \
9031 baz.o grbx.o -Wl,-Td10v.ld -o overlays
9033 The build process is identical for any other architecture, except
9034 that you must substitute the appropriate compiler and linker script for
9035 the target system for `d10v-elf-gcc' and `d10v.ld'.
9038 File: gdb.info, Node: Languages, Next: Symbols, Prev: Overlays, Up: Top
9040 15 Using GDB with Different Languages
9041 *************************************
9043 Although programming languages generally have common aspects, they are
9044 rarely expressed in the same manner. For instance, in ANSI C,
9045 dereferencing a pointer `p' is accomplished by `*p', but in Modula-2,
9046 it is accomplished by `p^'. Values can also be represented (and
9047 displayed) differently. Hex numbers in C appear as `0x1ae', while in
9048 Modula-2 they appear as `1AEH'.
9050 Language-specific information is built into GDB for some languages,
9051 allowing you to express operations like the above in your program's
9052 native language, and allowing GDB to output values in a manner
9053 consistent with the syntax of your program's native language. The
9054 language you use to build expressions is called the "working language".
9058 * Setting:: Switching between source languages
9059 * Show:: Displaying the language
9060 * Checks:: Type and range checks
9061 * Supported Languages:: Supported languages
9062 * Unsupported Languages:: Unsupported languages
9065 File: gdb.info, Node: Setting, Next: Show, Up: Languages
9067 15.1 Switching Between Source Languages
9068 =======================================
9070 There are two ways to control the working language--either have GDB set
9071 it automatically, or select it manually yourself. You can use the `set
9072 language' command for either purpose. On startup, GDB defaults to
9073 setting the language automatically. The working language is used to
9074 determine how expressions you type are interpreted, how values are
9077 In addition to the working language, every source file that GDB
9078 knows about has its own working language. For some object file
9079 formats, the compiler might indicate which language a particular source
9080 file is in. However, most of the time GDB infers the language from the
9081 name of the file. The language of a source file controls whether C++
9082 names are demangled--this way `backtrace' can show each frame
9083 appropriately for its own language. There is no way to set the
9084 language of a source file from within GDB, but you can set the language
9085 associated with a filename extension. *Note Displaying the Language:
9088 This is most commonly a problem when you use a program, such as
9089 `cfront' or `f2c', that generates C but is written in another language.
9090 In that case, make the program use `#line' directives in its C output;
9091 that way GDB will know the correct language of the source code of the
9092 original program, and will display that source code, not the generated
9097 * Filenames:: Filename extensions and languages.
9098 * Manually:: Setting the working language manually
9099 * Automatically:: Having GDB infer the source language
9102 File: gdb.info, Node: Filenames, Next: Manually, Up: Setting
9104 15.1.1 List of Filename Extensions and Languages
9105 ------------------------------------------------
9107 If a source file name ends in one of the following extensions, then GDB
9108 infers that its language is the one indicated.
9128 Objective-C source file
9135 Modula-2 source file
9139 Assembler source file. This actually behaves almost like C, but
9140 GDB does not skip over function prologues when stepping.
9142 In addition, you may set the language associated with a filename
9143 extension. *Note Displaying the Language: Show.
9146 File: gdb.info, Node: Manually, Next: Automatically, Prev: Filenames, Up: Setting
9148 15.1.2 Setting the Working Language
9149 -----------------------------------
9151 If you allow GDB to set the language automatically, expressions are
9152 interpreted the same way in your debugging session and your program.
9154 If you wish, you may set the language manually. To do this, issue
9155 the command `set language LANG', where LANG is the name of a language,
9156 such as `c' or `modula-2'. For a list of the supported languages, type
9159 Setting the language manually prevents GDB from updating the working
9160 language automatically. This can lead to confusion if you try to debug
9161 a program when the working language is not the same as the source
9162 language, when an expression is acceptable to both languages--but means
9163 different things. For instance, if the current source file were
9164 written in C, and GDB was parsing Modula-2, a command such as:
9168 might not have the effect you intended. In C, this means to add `b'
9169 and `c' and place the result in `a'. The result printed would be the
9170 value of `a'. In Modula-2, this means to compare `a' to the result of
9171 `b+c', yielding a `BOOLEAN' value.
9174 File: gdb.info, Node: Automatically, Prev: Manually, Up: Setting
9176 15.1.3 Having GDB Infer the Source Language
9177 -------------------------------------------
9179 To have GDB set the working language automatically, use `set language
9180 local' or `set language auto'. GDB then infers the working language.
9181 That is, when your program stops in a frame (usually by encountering a
9182 breakpoint), GDB sets the working language to the language recorded for
9183 the function in that frame. If the language for a frame is unknown
9184 (that is, if the function or block corresponding to the frame was
9185 defined in a source file that does not have a recognized extension),
9186 the current working language is not changed, and GDB issues a warning.
9188 This may not seem necessary for most programs, which are written
9189 entirely in one source language. However, program modules and libraries
9190 written in one source language can be used by a main program written in
9191 a different source language. Using `set language auto' in this case
9192 frees you from having to set the working language manually.
9195 File: gdb.info, Node: Show, Next: Checks, Prev: Setting, Up: Languages
9197 15.2 Displaying the Language
9198 ============================
9200 The following commands help you find out which language is the working
9201 language, and also what language source files were written in.
9204 Display the current working language. This is the language you
9205 can use with commands such as `print' to build and compute
9206 expressions that may involve variables in your program.
9209 Display the source language for this frame. This language becomes
9210 the working language if you use an identifier from this frame.
9211 *Note Information about a Frame: Frame Info, to identify the other
9212 information listed here.
9215 Display the source language of this source file. *Note Examining
9216 the Symbol Table: Symbols, to identify the other information
9219 In unusual circumstances, you may have source files with extensions
9220 not in the standard list. You can then set the extension associated
9221 with a language explicitly:
9223 `set extension-language EXT LANGUAGE'
9224 Tell GDB that source files with extension EXT are to be assumed as
9225 written in the source language LANGUAGE.
9228 List all the filename extensions and the associated languages.
9231 File: gdb.info, Node: Checks, Next: Supported Languages, Prev: Show, Up: Languages
9233 15.3 Type and Range Checking
9234 ============================
9236 _Warning:_ In this release, the GDB commands for type and range
9237 checking are included, but they do not yet have any effect. This
9238 section documents the intended facilities.
9240 Some languages are designed to guard you against making seemingly
9241 common errors through a series of compile- and run-time checks. These
9242 include checking the type of arguments to functions and operators, and
9243 making sure mathematical overflows are caught at run time. Checks such
9244 as these help to ensure a program's correctness once it has been
9245 compiled by eliminating type mismatches, and providing active checks
9246 for range errors when your program is running.
9248 GDB can check for conditions like the above if you wish. Although
9249 GDB does not check the statements in your program, it can check
9250 expressions entered directly into GDB for evaluation via the `print'
9251 command, for example. As with the working language, GDB can also
9252 decide whether or not to check automatically based on your program's
9253 source language. *Note Supported Languages: Supported Languages, for
9254 the default settings of supported languages.
9258 * Type Checking:: An overview of type checking
9259 * Range Checking:: An overview of range checking
9262 File: gdb.info, Node: Type Checking, Next: Range Checking, Up: Checks
9264 15.3.1 An Overview of Type Checking
9265 -----------------------------------
9267 Some languages, such as Modula-2, are strongly typed, meaning that the
9268 arguments to operators and functions have to be of the correct type,
9269 otherwise an error occurs. These checks prevent type mismatch errors
9270 from ever causing any run-time problems. For example,
9276 The second example fails because the `CARDINAL' 1 is not
9277 type-compatible with the `REAL' 2.3.
9279 For the expressions you use in GDB commands, you can tell the GDB
9280 type checker to skip checking; to treat any mismatches as errors and
9281 abandon the expression; or to only issue warnings when type mismatches
9282 occur, but evaluate the expression anyway. When you choose the last of
9283 these, GDB evaluates expressions like the second example above, but
9284 also issues a warning.
9286 Even if you turn type checking off, there may be other reasons
9287 related to type that prevent GDB from evaluating an expression. For
9288 instance, GDB does not know how to add an `int' and a `struct foo'.
9289 These particular type errors have nothing to do with the language in
9290 use, and usually arise from expressions, such as the one described
9291 above, which make little sense to evaluate anyway.
9293 Each language defines to what degree it is strict about type. For
9294 instance, both Modula-2 and C require the arguments to arithmetical
9295 operators to be numbers. In C, enumerated types and pointers can be
9296 represented as numbers, so that they are valid arguments to mathematical
9297 operators. *Note Supported Languages: Supported Languages, for further
9298 details on specific languages.
9300 GDB provides some additional commands for controlling the type
9303 `set check type auto'
9304 Set type checking on or off based on the current working language.
9305 *Note Supported Languages: Supported Languages, for the default
9306 settings for each language.
9309 `set check type off'
9310 Set type checking on or off, overriding the default setting for the
9311 current working language. Issue a warning if the setting does not
9312 match the language default. If any type mismatches occur in
9313 evaluating an expression while type checking is on, GDB prints a
9314 message and aborts evaluation of the expression.
9316 `set check type warn'
9317 Cause the type checker to issue warnings, but to always attempt to
9318 evaluate the expression. Evaluating the expression may still be
9319 impossible for other reasons. For example, GDB cannot add numbers
9323 Show the current setting of the type checker, and whether or not
9324 GDB is setting it automatically.
9327 File: gdb.info, Node: Range Checking, Prev: Type Checking, Up: Checks
9329 15.3.2 An Overview of Range Checking
9330 ------------------------------------
9332 In some languages (such as Modula-2), it is an error to exceed the
9333 bounds of a type; this is enforced with run-time checks. Such range
9334 checking is meant to ensure program correctness by making sure
9335 computations do not overflow, or indices on an array element access do
9336 not exceed the bounds of the array.
9338 For expressions you use in GDB commands, you can tell GDB to treat
9339 range errors in one of three ways: ignore them, always treat them as
9340 errors and abandon the expression, or issue warnings but evaluate the
9343 A range error can result from numerical overflow, from exceeding an
9344 array index bound, or when you type a constant that is not a member of
9345 any type. Some languages, however, do not treat overflows as an error.
9346 In many implementations of C, mathematical overflow causes the result
9347 to "wrap around" to lower values--for example, if M is the largest
9348 integer value, and S is the smallest, then
9352 This, too, is specific to individual languages, and in some cases
9353 specific to individual compilers or machines. *Note Supported
9354 Languages: Supported Languages, for further details on specific
9357 GDB provides some additional commands for controlling the range
9360 `set check range auto'
9361 Set range checking on or off based on the current working language.
9362 *Note Supported Languages: Supported Languages, for the default
9363 settings for each language.
9365 `set check range on'
9366 `set check range off'
9367 Set range checking on or off, overriding the default setting for
9368 the current working language. A warning is issued if the setting
9369 does not match the language default. If a range error occurs and
9370 range checking is on, then a message is printed and evaluation of
9371 the expression is aborted.
9373 `set check range warn'
9374 Output messages when the GDB range checker detects a range error,
9375 but attempt to evaluate the expression anyway. Evaluating the
9376 expression may still be impossible for other reasons, such as
9377 accessing memory that the process does not own (a typical example
9378 from many Unix systems).
9381 Show the current setting of the range checker, and whether or not
9382 it is being set automatically by GDB.
9385 File: gdb.info, Node: Supported Languages, Next: Unsupported Languages, Prev: Checks, Up: Languages
9387 15.4 Supported Languages
9388 ========================
9390 GDB supports C, C++, Objective-C, Fortran, Java, Pascal, assembly,
9391 Modula-2, and Ada. Some GDB features may be used in expressions
9392 regardless of the language you use: the GDB `@' and `::' operators, and
9393 the `{type}addr' construct (*note Expressions: Expressions.) can be
9394 used with the constructs of any supported language.
9396 The following sections detail to what degree each source language is
9397 supported by GDB. These sections are not meant to be language
9398 tutorials or references, but serve only as a reference guide to what the
9399 GDB expression parser accepts, and what input and output formats should
9400 look like for different languages. There are many good books written
9401 on each of these languages; please look to these for a language
9402 reference or tutorial.
9407 * Objective-C:: Objective-C
9410 * Modula-2:: Modula-2
9414 File: gdb.info, Node: C, Next: Objective-C, Up: Supported Languages
9419 Since C and C++ are so closely related, many features of GDB apply to
9420 both languages. Whenever this is the case, we discuss those languages
9423 The C++ debugging facilities are jointly implemented by the C++
9424 compiler and GDB. Therefore, to debug your C++ code effectively, you
9425 must compile your C++ programs with a supported C++ compiler, such as
9426 GNU `g++', or the HP ANSI C++ compiler (`aCC').
9428 For best results when using GNU C++, use the DWARF 2 debugging
9429 format; if it doesn't work on your system, try the stabs+ debugging
9430 format. You can select those formats explicitly with the `g++'
9431 command-line options `-gdwarf-2' and `-gstabs+'. *Note Options for
9432 Debugging Your Program or GCC: (gcc.info)Debugging Options.
9436 * C Operators:: C and C++ operators
9437 * C Constants:: C and C++ constants
9438 * C Plus Plus Expressions:: C++ expressions
9439 * C Defaults:: Default settings for C and C++
9440 * C Checks:: C and C++ type and range checks
9441 * Debugging C:: GDB and C
9442 * Debugging C Plus Plus:: GDB features for C++
9443 * Decimal Floating Point:: Numbers in Decimal Floating Point format
9446 File: gdb.info, Node: C Operators, Next: C Constants, Up: C
9448 15.4.1.1 C and C++ Operators
9449 ............................
9451 Operators must be defined on values of specific types. For instance,
9452 `+' is defined on numbers, but not on structures. Operators are often
9453 defined on groups of types.
9455 For the purposes of C and C++, the following definitions hold:
9457 * _Integral types_ include `int' with any of its storage-class
9458 specifiers; `char'; `enum'; and, for C++, `bool'.
9460 * _Floating-point types_ include `float', `double', and `long
9461 double' (if supported by the target platform).
9463 * _Pointer types_ include all types defined as `(TYPE *)'.
9465 * _Scalar types_ include all of the above.
9468 The following operators are supported. They are listed here in order
9469 of increasing precedence:
9472 The comma or sequencing operator. Expressions in a
9473 comma-separated list are evaluated from left to right, with the
9474 result of the entire expression being the last expression
9478 Assignment. The value of an assignment expression is the value
9479 assigned. Defined on scalar types.
9482 Used in an expression of the form `A OP= B', and translated to
9483 `A = A OP B'. `OP=' and `=' have the same precedence. OP is any
9484 one of the operators `|', `^', `&', `<<', `>>', `+', `-', `*',
9488 The ternary operator. `A ? B : C' can be thought of as: if A
9489 then B else C. A should be of an integral type.
9492 Logical OR. Defined on integral types.
9495 Logical AND. Defined on integral types.
9498 Bitwise OR. Defined on integral types.
9501 Bitwise exclusive-OR. Defined on integral types.
9504 Bitwise AND. Defined on integral types.
9507 Equality and inequality. Defined on scalar types. The value of
9508 these expressions is 0 for false and non-zero for true.
9511 Less than, greater than, less than or equal, greater than or equal.
9512 Defined on scalar types. The value of these expressions is 0 for
9513 false and non-zero for true.
9516 left shift, and right shift. Defined on integral types.
9519 The GDB "artificial array" operator (*note Expressions:
9523 Addition and subtraction. Defined on integral types,
9524 floating-point types and pointer types.
9527 Multiplication, division, and modulus. Multiplication and
9528 division are defined on integral and floating-point types.
9529 Modulus is defined on integral types.
9532 Increment and decrement. When appearing before a variable, the
9533 operation is performed before the variable is used in an
9534 expression; when appearing after it, the variable's value is used
9535 before the operation takes place.
9538 Pointer dereferencing. Defined on pointer types. Same precedence
9542 Address operator. Defined on variables. Same precedence as `++'.
9544 For debugging C++, GDB implements a use of `&' beyond what is
9545 allowed in the C++ language itself: you can use `&(&REF)' to
9546 examine the address where a C++ reference variable (declared with
9550 Negative. Defined on integral and floating-point types. Same
9554 Logical negation. Defined on integral types. Same precedence as
9558 Bitwise complement operator. Defined on integral types. Same
9562 Structure member, and pointer-to-structure member. For
9563 convenience, GDB regards the two as equivalent, choosing whether
9564 to dereference a pointer based on the stored type information.
9565 Defined on `struct' and `union' data.
9568 Dereferences of pointers to members.
9571 Array indexing. `A[I]' is defined as `*(A+I)'. Same precedence
9575 Function parameter list. Same precedence as `->'.
9578 C++ scope resolution operator. Defined on `struct', `union', and
9582 Doubled colons also represent the GDB scope operator (*note
9583 Expressions: Expressions.). Same precedence as `::', above.
9585 If an operator is redefined in the user code, GDB usually attempts
9586 to invoke the redefined version instead of using the operator's
9590 File: gdb.info, Node: C Constants, Next: C Plus Plus Expressions, Prev: C Operators, Up: C
9592 15.4.1.2 C and C++ Constants
9593 ............................
9595 GDB allows you to express the constants of C and C++ in the following
9598 * Integer constants are a sequence of digits. Octal constants are
9599 specified by a leading `0' (i.e. zero), and hexadecimal constants
9600 by a leading `0x' or `0X'. Constants may also end with a letter
9601 `l', specifying that the constant should be treated as a `long'
9604 * Floating point constants are a sequence of digits, followed by a
9605 decimal point, followed by a sequence of digits, and optionally
9606 followed by an exponent. An exponent is of the form:
9607 `e[[+]|-]NNN', where NNN is another sequence of digits. The `+'
9608 is optional for positive exponents. A floating-point constant may
9609 also end with a letter `f' or `F', specifying that the constant
9610 should be treated as being of the `float' (as opposed to the
9611 default `double') type; or with a letter `l' or `L', which
9612 specifies a `long double' constant.
9614 * Enumerated constants consist of enumerated identifiers, or their
9615 integral equivalents.
9617 * Character constants are a single character surrounded by single
9618 quotes (`''), or a number--the ordinal value of the corresponding
9619 character (usually its ASCII value). Within quotes, the single
9620 character may be represented by a letter or by "escape sequences",
9621 which are of the form `\NNN', where NNN is the octal representation
9622 of the character's ordinal value; or of the form `\X', where `X'
9623 is a predefined special character--for example, `\n' for newline.
9625 * String constants are a sequence of character constants surrounded
9626 by double quotes (`"'). Any valid character constant (as described
9627 above) may appear. Double quotes within the string must be
9628 preceded by a backslash, so for instance `"a\"b'c"' is a string of
9631 * Pointer constants are an integral value. You can also write
9632 pointers to constants using the C operator `&'.
9634 * Array constants are comma-separated lists surrounded by braces `{'
9635 and `}'; for example, `{1,2,3}' is a three-element array of
9636 integers, `{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and
9637 `{&"hi", &"there", &"fred"}' is a three-element array of pointers.
9640 File: gdb.info, Node: C Plus Plus Expressions, Next: C Defaults, Prev: C Constants, Up: C
9642 15.4.1.3 C++ Expressions
9643 ........................
9645 GDB expression handling can interpret most C++ expressions.
9647 _Warning:_ GDB can only debug C++ code if you use the proper
9648 compiler and the proper debug format. Currently, GDB works best
9649 when debugging C++ code that is compiled with GCC 2.95.3 or with
9650 GCC 3.1 or newer, using the options `-gdwarf-2' or `-gstabs+'.
9651 DWARF 2 is preferred over stabs+. Most configurations of GCC emit
9652 either DWARF 2 or stabs+ as their default debug format, so you
9653 usually don't need to specify a debug format explicitly. Other
9654 compilers and/or debug formats are likely to work badly or not at
9655 all when using GDB to debug C++ code.
9657 1. Member function calls are allowed; you can use expressions like
9659 count = aml->GetOriginal(x, y)
9661 2. While a member function is active (in the selected stack frame),
9662 your expressions have the same namespace available as the member
9663 function; that is, GDB allows implicit references to the class
9664 instance pointer `this' following the same rules as C++.
9666 3. You can call overloaded functions; GDB resolves the function call
9667 to the right definition, with some restrictions. GDB does not
9668 perform overload resolution involving user-defined type
9669 conversions, calls to constructors, or instantiations of templates
9670 that do not exist in the program. It also cannot handle ellipsis
9671 argument lists or default arguments.
9673 It does perform integral conversions and promotions, floating-point
9674 promotions, arithmetic conversions, pointer conversions,
9675 conversions of class objects to base classes, and standard
9676 conversions such as those of functions or arrays to pointers; it
9677 requires an exact match on the number of function arguments.
9679 Overload resolution is always performed, unless you have specified
9680 `set overload-resolution off'. *Note GDB Features for C++:
9681 Debugging C Plus Plus.
9683 You must specify `set overload-resolution off' in order to use an
9684 explicit function signature to call an overloaded function, as in
9685 p 'foo(char,int)'('x', 13)
9687 The GDB command-completion facility can simplify this; see *note
9688 Command Completion: Completion.
9690 4. GDB understands variables declared as C++ references; you can use
9691 them in expressions just as you do in C++ source--they are
9692 automatically dereferenced.
9694 In the parameter list shown when GDB displays a frame, the values
9695 of reference variables are not displayed (unlike other variables);
9696 this avoids clutter, since references are often used for large
9697 structures. The _address_ of a reference variable is always
9698 shown, unless you have specified `set print address off'.
9700 5. GDB supports the C++ name resolution operator `::'--your
9701 expressions can use it just as expressions in your program do.
9702 Since one scope may be defined in another, you can use `::'
9703 repeatedly if necessary, for example in an expression like
9704 `SCOPE1::SCOPE2::NAME'. GDB also allows resolving name scope by
9705 reference to source files, in both C and C++ debugging (*note
9706 Program Variables: Variables.).
9708 In addition, when used with HP's C++ compiler, GDB supports calling
9709 virtual functions correctly, printing out virtual bases of objects,
9710 calling functions in a base subobject, casting objects, and invoking
9711 user-defined operators.
9714 File: gdb.info, Node: C Defaults, Next: C Checks, Prev: C Plus Plus Expressions, Up: C
9716 15.4.1.4 C and C++ Defaults
9717 ...........................
9719 If you allow GDB to set type and range checking automatically, they
9720 both default to `off' whenever the working language changes to C or
9721 C++. This happens regardless of whether you or GDB selects the working
9724 If you allow GDB to set the language automatically, it recognizes
9725 source files whose names end with `.c', `.C', or `.cc', etc, and when
9726 GDB enters code compiled from one of these files, it sets the working
9727 language to C or C++. *Note Having GDB Infer the Source Language:
9728 Automatically, for further details.
9731 File: gdb.info, Node: C Checks, Next: Debugging C, Prev: C Defaults, Up: C
9733 15.4.1.5 C and C++ Type and Range Checks
9734 ........................................
9736 By default, when GDB parses C or C++ expressions, type checking is not
9737 used. However, if you turn type checking on, GDB considers two
9738 variables type equivalent if:
9740 * The two variables are structured and have the same structure,
9741 union, or enumerated tag.
9743 * The two variables have the same type name, or types that have been
9744 declared equivalent through `typedef'.
9747 Range checking, if turned on, is done on mathematical operations.
9748 Array indices are not checked, since they are often used to index a
9749 pointer that is not itself an array.
9752 File: gdb.info, Node: Debugging C, Next: Debugging C Plus Plus, Prev: C Checks, Up: C
9757 The `set print union' and `show print union' commands apply to the
9758 `union' type. When set to `on', any `union' that is inside a `struct'
9759 or `class' is also printed. Otherwise, it appears as `{...}'.
9761 The `@' operator aids in the debugging of dynamic arrays, formed
9762 with pointers and a memory allocation function. *Note Expressions:
9766 File: gdb.info, Node: Debugging C Plus Plus, Next: Decimal Floating Point, Prev: Debugging C, Up: C
9768 15.4.1.7 GDB Features for C++
9769 .............................
9771 Some GDB commands are particularly useful with C++, and some are
9772 designed specifically for use with C++. Here is a summary:
9775 When you want a breakpoint in a function whose name is overloaded,
9776 GDB has the capability to display a menu of possible breakpoint
9777 locations to help you specify which function definition you want.
9778 *Note Ambiguous Expressions: Ambiguous Expressions.
9781 Setting breakpoints using regular expressions is helpful for
9782 setting breakpoints on overloaded functions that are not members
9783 of any special classes. *Note Setting Breakpoints: Set Breaks.
9787 Debug C++ exception handling using these commands. *Note Setting
9788 Catchpoints: Set Catchpoints.
9791 Print inheritance relationships as well as other information for
9792 type TYPENAME. *Note Examining the Symbol Table: Symbols.
9794 `set print demangle'
9795 `show print demangle'
9796 `set print asm-demangle'
9797 `show print asm-demangle'
9798 Control whether C++ symbols display in their source form, both when
9799 displaying code as C++ source and when displaying disassemblies.
9800 *Note Print Settings: Print Settings.
9804 Choose whether to print derived (actual) or declared types of
9805 objects. *Note Print Settings: Print Settings.
9809 Control the format for printing virtual function tables. *Note
9810 Print Settings: Print Settings. (The `vtbl' commands do not work
9811 on programs compiled with the HP ANSI C++ compiler (`aCC').)
9813 `set overload-resolution on'
9814 Enable overload resolution for C++ expression evaluation. The
9815 default is on. For overloaded functions, GDB evaluates the
9816 arguments and searches for a function whose signature matches the
9817 argument types, using the standard C++ conversion rules (see *note
9818 C++ Expressions: C Plus Plus Expressions, for details). If it
9819 cannot find a match, it emits a message.
9821 `set overload-resolution off'
9822 Disable overload resolution for C++ expression evaluation. For
9823 overloaded functions that are not class member functions, GDB
9824 chooses the first function of the specified name that it finds in
9825 the symbol table, whether or not its arguments are of the correct
9826 type. For overloaded functions that are class member functions,
9827 GDB searches for a function whose signature _exactly_ matches the
9830 `show overload-resolution'
9831 Show the current setting of overload resolution.
9833 `Overloaded symbol names'
9834 You can specify a particular definition of an overloaded symbol,
9835 using the same notation that is used to declare such symbols in
9836 C++: type `SYMBOL(TYPES)' rather than just SYMBOL. You can also
9837 use the GDB command-line word completion facilities to list the
9838 available choices, or to finish the type list for you. *Note
9839 Command Completion: Completion, for details on how to do this.
9842 File: gdb.info, Node: Decimal Floating Point, Prev: Debugging C Plus Plus, Up: C
9844 15.4.1.8 Decimal Floating Point format
9845 ......................................
9847 GDB can examine, set and perform computations with numbers in decimal
9848 floating point format, which in the C language correspond to the
9849 `_Decimal32', `_Decimal64' and `_Decimal128' types as specified by the
9850 extension to support decimal floating-point arithmetic.
9852 There are two encodings in use, depending on the architecture: BID
9853 (Binary Integer Decimal) for x86 and x86-64, and DPD (Densely Packed
9854 Decimal) for PowerPC. GDB will use the appropriate encoding for the
9857 Because of a limitation in `libdecnumber', the library used by GDB
9858 to manipulate decimal floating point numbers, it is not possible to
9859 convert (using a cast, for example) integers wider than 32-bit to
9862 In addition, in order to imitate GDB's behaviour with binary floating
9863 point computations, error checking in decimal float operations ignores
9864 underflow, overflow and divide by zero exceptions.
9866 In the PowerPC architecture, GDB provides a set of pseudo-registers
9867 to inspect `_Decimal128' values stored in floating point registers.
9868 See *note PowerPC: PowerPC. for more details.
9871 File: gdb.info, Node: Objective-C, Next: Fortran, Prev: C, Up: Supported Languages
9876 This section provides information about some commands and command
9877 options that are useful for debugging Objective-C code. See also *note
9878 info classes: Symbols, and *note info selectors: Symbols, for a few
9879 more commands specific to Objective-C support.
9883 * Method Names in Commands::
9884 * The Print Command with Objective-C::
9887 File: gdb.info, Node: Method Names in Commands, Next: The Print Command with Objective-C, Up: Objective-C
9889 15.4.2.1 Method Names in Commands
9890 .................................
9892 The following commands have been extended to accept Objective-C method
9893 names as line specifications:
9905 A fully qualified Objective-C method name is specified as
9909 where the minus sign is used to indicate an instance method and a
9910 plus sign (not shown) is used to indicate a class method. The class
9911 name CLASS and method name METHODNAME are enclosed in brackets, similar
9912 to the way messages are specified in Objective-C source code. For
9913 example, to set a breakpoint at the `create' instance method of class
9914 `Fruit' in the program currently being debugged, enter:
9916 break -[Fruit create]
9918 To list ten program lines around the `initialize' class method,
9921 list +[NSText initialize]
9923 In the current version of GDB, the plus or minus sign is required.
9924 In future versions of GDB, the plus or minus sign will be optional, but
9925 you can use it to narrow the search. It is also possible to specify
9930 You must specify the complete method name, including any colons. If
9931 your program's source files contain more than one `create' method,
9932 you'll be presented with a numbered list of classes that implement that
9933 method. Indicate your choice by number, or type `0' to exit if none
9936 As another example, to clear a breakpoint established at the
9937 `makeKeyAndOrderFront:' method of the `NSWindow' class, enter:
9939 clear -[NSWindow makeKeyAndOrderFront:]
9942 File: gdb.info, Node: The Print Command with Objective-C, Prev: Method Names in Commands, Up: Objective-C
9944 15.4.2.2 The Print Command With Objective-C
9945 ...........................................
9947 The print command has also been extended to accept methods. For
9950 print -[OBJECT hash]
9952 will tell GDB to send the `hash' message to OBJECT and print the
9953 result. Also, an additional command has been added, `print-object' or
9954 `po' for short, which is meant to print the description of an object.
9955 However, this command may only work with certain Objective-C libraries
9956 that have a particular hook function, `_NSPrintForDebugger', defined.
9959 File: gdb.info, Node: Fortran, Next: Pascal, Prev: Objective-C, Up: Supported Languages
9964 GDB can be used to debug programs written in Fortran, but it currently
9965 supports only the features of Fortran 77 language.
9967 Some Fortran compilers (GNU Fortran 77 and Fortran 95 compilers
9968 among them) append an underscore to the names of variables and
9969 functions. When you debug programs compiled by those compilers, you
9970 will need to refer to variables and functions with a trailing
9975 * Fortran Operators:: Fortran operators and expressions
9976 * Fortran Defaults:: Default settings for Fortran
9977 * Special Fortran Commands:: Special GDB commands for Fortran
9980 File: gdb.info, Node: Fortran Operators, Next: Fortran Defaults, Up: Fortran
9982 15.4.3.1 Fortran Operators and Expressions
9983 ..........................................
9985 Operators must be defined on values of specific types. For instance,
9986 `+' is defined on numbers, but not on characters or other non-
9987 arithmetic types. Operators are often defined on groups of types.
9990 The exponentiation operator. It raises the first operand to the
9991 power of the second one.
9994 The range operator. Normally used in the form of array(low:high)
9995 to represent a section of array.
9998 The access component operator. Normally used to access elements
9999 in derived types. Also suitable for unions. As unions aren't
10000 part of regular Fortran, this can only happen when accessing a
10001 register that uses a gdbarch-defined union type.
10004 File: gdb.info, Node: Fortran Defaults, Next: Special Fortran Commands, Prev: Fortran Operators, Up: Fortran
10006 15.4.3.2 Fortran Defaults
10007 .........................
10009 Fortran symbols are usually case-insensitive, so GDB by default uses
10010 case-insensitive matches for Fortran symbols. You can change that with
10011 the `set case-insensitive' command, see *note Symbols::, for the
10015 File: gdb.info, Node: Special Fortran Commands, Prev: Fortran Defaults, Up: Fortran
10017 15.4.3.3 Special Fortran Commands
10018 .................................
10020 GDB has some commands to support Fortran-specific features, such as
10021 displaying common blocks.
10023 `info common [COMMON-NAME]'
10024 This command prints the values contained in the Fortran `COMMON'
10025 block whose name is COMMON-NAME. With no argument, the names of
10026 all `COMMON' blocks visible at the current program location are
10030 File: gdb.info, Node: Pascal, Next: Modula-2, Prev: Fortran, Up: Supported Languages
10035 Debugging Pascal programs which use sets, subranges, file variables, or
10036 nested functions does not currently work. GDB does not support
10037 entering expressions, printing values, or similar features using Pascal
10040 The Pascal-specific command `set print pascal_static-members'
10041 controls whether static members of Pascal objects are displayed. *Note
10042 pascal_static-members: Print Settings.
10045 File: gdb.info, Node: Modula-2, Next: Ada, Prev: Pascal, Up: Supported Languages
10050 The extensions made to GDB to support Modula-2 only support output from
10051 the GNU Modula-2 compiler (which is currently being developed). Other
10052 Modula-2 compilers are not currently supported, and attempting to debug
10053 executables produced by them is most likely to give an error as GDB
10054 reads in the executable's symbol table.
10058 * M2 Operators:: Built-in operators
10059 * Built-In Func/Proc:: Built-in functions and procedures
10060 * M2 Constants:: Modula-2 constants
10061 * M2 Types:: Modula-2 types
10062 * M2 Defaults:: Default settings for Modula-2
10063 * Deviations:: Deviations from standard Modula-2
10064 * M2 Checks:: Modula-2 type and range checks
10065 * M2 Scope:: The scope operators `::' and `.'
10066 * GDB/M2:: GDB and Modula-2
10069 File: gdb.info, Node: M2 Operators, Next: Built-In Func/Proc, Up: Modula-2
10074 Operators must be defined on values of specific types. For instance,
10075 `+' is defined on numbers, but not on structures. Operators are often
10076 defined on groups of types. For the purposes of Modula-2, the
10077 following definitions hold:
10079 * _Integral types_ consist of `INTEGER', `CARDINAL', and their
10082 * _Character types_ consist of `CHAR' and its subranges.
10084 * _Floating-point types_ consist of `REAL'.
10086 * _Pointer types_ consist of anything declared as `POINTER TO TYPE'.
10088 * _Scalar types_ consist of all of the above.
10090 * _Set types_ consist of `SET' and `BITSET' types.
10092 * _Boolean types_ consist of `BOOLEAN'.
10094 The following operators are supported, and appear in order of
10095 increasing precedence:
10098 Function argument or array index separator.
10101 Assignment. The value of VAR `:=' VALUE is VALUE.
10104 Less than, greater than on integral, floating-point, or enumerated
10108 Less than or equal to, greater than or equal to on integral,
10109 floating-point and enumerated types, or set inclusion on set
10110 types. Same precedence as `<'.
10113 Equality and two ways of expressing inequality, valid on scalar
10114 types. Same precedence as `<'. In GDB scripts, only `<>' is
10115 available for inequality, since `#' conflicts with the script
10119 Set membership. Defined on set types and the types of their
10120 members. Same precedence as `<'.
10123 Boolean disjunction. Defined on boolean types.
10126 Boolean conjunction. Defined on boolean types.
10129 The GDB "artificial array" operator (*note Expressions:
10133 Addition and subtraction on integral and floating-point types, or
10134 union and difference on set types.
10137 Multiplication on integral and floating-point types, or set
10138 intersection on set types.
10141 Division on floating-point types, or symmetric set difference on
10142 set types. Same precedence as `*'.
10145 Integer division and remainder. Defined on integral types. Same
10149 Negative. Defined on `INTEGER' and `REAL' data.
10152 Pointer dereferencing. Defined on pointer types.
10155 Boolean negation. Defined on boolean types. Same precedence as
10159 `RECORD' field selector. Defined on `RECORD' data. Same
10163 Array indexing. Defined on `ARRAY' data. Same precedence as `^'.
10166 Procedure argument list. Defined on `PROCEDURE' objects. Same
10170 GDB and Modula-2 scope operators.
10172 _Warning:_ Set expressions and their operations are not yet
10173 supported, so GDB treats the use of the operator `IN', or the use
10174 of operators `+', `-', `*', `/', `=', , `<>', `#', `<=', and `>='
10175 on sets as an error.
10178 File: gdb.info, Node: Built-In Func/Proc, Next: M2 Constants, Prev: M2 Operators, Up: Modula-2
10180 15.4.5.2 Built-in Functions and Procedures
10181 ..........................................
10183 Modula-2 also makes available several built-in procedures and functions.
10184 In describing these, the following metavariables are used:
10187 represents an `ARRAY' variable.
10190 represents a `CHAR' constant or variable.
10193 represents a variable or constant of integral type.
10196 represents an identifier that belongs to a set. Generally used in
10197 the same function with the metavariable S. The type of S should
10198 be `SET OF MTYPE' (where MTYPE is the type of M).
10201 represents a variable or constant of integral or floating-point
10205 represents a variable or constant of floating-point type.
10211 represents a variable.
10214 represents a variable or constant of one of many types. See the
10215 explanation of the function for details.
10217 All Modula-2 built-in procedures also return a result, described
10221 Returns the absolute value of N.
10224 If C is a lower case letter, it returns its upper case equivalent,
10225 otherwise it returns its argument.
10228 Returns the character whose ordinal value is I.
10231 Decrements the value in the variable V by one. Returns the new
10235 Decrements the value in the variable V by I. Returns the new
10239 Removes the element M from the set S. Returns the new set.
10242 Returns the floating point equivalent of the integer I.
10245 Returns the index of the last member of A.
10248 Increments the value in the variable V by one. Returns the new
10252 Increments the value in the variable V by I. Returns the new
10256 Adds the element M to the set S if it is not already there.
10257 Returns the new set.
10260 Returns the maximum value of the type T.
10263 Returns the minimum value of the type T.
10266 Returns boolean TRUE if I is an odd number.
10269 Returns the ordinal value of its argument. For example, the
10270 ordinal value of a character is its ASCII value (on machines
10271 supporting the ASCII character set). X must be of an ordered
10272 type, which include integral, character and enumerated types.
10275 Returns the size of its argument. X can be a variable or a type.
10278 Returns the integral part of R.
10281 Returns the size of its argument. X can be a variable or a type.
10284 Returns the member of the type T whose ordinal value is I.
10286 _Warning:_ Sets and their operations are not yet supported, so
10287 GDB treats the use of procedures `INCL' and `EXCL' as an error.
10290 File: gdb.info, Node: M2 Constants, Next: M2 Types, Prev: Built-In Func/Proc, Up: Modula-2
10295 GDB allows you to express the constants of Modula-2 in the following
10298 * Integer constants are simply a sequence of digits. When used in an
10299 expression, a constant is interpreted to be type-compatible with
10300 the rest of the expression. Hexadecimal integers are specified by
10301 a trailing `H', and octal integers by a trailing `B'.
10303 * Floating point constants appear as a sequence of digits, followed
10304 by a decimal point and another sequence of digits. An optional
10305 exponent can then be specified, in the form `E[+|-]NNN', where
10306 `[+|-]NNN' is the desired exponent. All of the digits of the
10307 floating point constant must be valid decimal (base 10) digits.
10309 * Character constants consist of a single character enclosed by a
10310 pair of like quotes, either single (`'') or double (`"'). They may
10311 also be expressed by their ordinal value (their ASCII value,
10312 usually) followed by a `C'.
10314 * String constants consist of a sequence of characters enclosed by a
10315 pair of like quotes, either single (`'') or double (`"'). Escape
10316 sequences in the style of C are also allowed. *Note C and C++
10317 Constants: C Constants, for a brief explanation of escape
10320 * Enumerated constants consist of an enumerated identifier.
10322 * Boolean constants consist of the identifiers `TRUE' and `FALSE'.
10324 * Pointer constants consist of integral values only.
10326 * Set constants are not yet supported.
10329 File: gdb.info, Node: M2 Types, Next: M2 Defaults, Prev: M2 Constants, Up: Modula-2
10331 15.4.5.4 Modula-2 Types
10332 .......................
10334 Currently GDB can print the following data types in Modula-2 syntax:
10335 array types, record types, set types, pointer types, procedure types,
10336 enumerated types, subrange types and base types. You can also print
10337 the contents of variables declared using these type. This section
10338 gives a number of simple source code examples together with sample GDB
10341 The first example contains the following section of code:
10347 and you can request GDB to interrogate the type and value of `r' and
10359 Likewise if your source code declares `s' as:
10362 s: SET ['A'..'Z'] ;
10364 then you may query the type of `s' by:
10367 type = SET ['A'..'Z']
10369 Note that at present you cannot interactively manipulate set
10370 expressions using the debugger.
10372 The following example shows how you might declare an array in
10373 Modula-2 and how you can interact with GDB to print its type and
10377 s: ARRAY [-10..10] OF CHAR ;
10380 ARRAY [-10..10] OF CHAR
10382 Note that the array handling is not yet complete and although the
10383 type is printed correctly, expression handling still assumes that all
10384 arrays have a lower bound of zero and not `-10' as in the example above.
10386 Here are some more type related Modula-2 examples:
10389 colour = (blue, red, yellow, green) ;
10390 t = [blue..yellow] ;
10396 The GDB interaction shows how you can query the data type and value of
10402 type = [blue..yellow]
10404 In this example a Modula-2 array is declared and its contents
10405 displayed. Observe that the contents are written in the same way as
10406 their `C' counterparts.
10409 s: ARRAY [1..5] OF CARDINAL ;
10414 $1 = {1, 0, 0, 0, 0}
10416 type = ARRAY [1..5] OF CARDINAL
10418 The Modula-2 language interface to GDB also understands pointer
10419 types as shown in this example:
10422 s: POINTER TO ARRAY [1..5] OF CARDINAL ;
10427 and you can request that GDB describes the type of `s'.
10430 type = POINTER TO ARRAY [1..5] OF CARDINAL
10432 GDB handles compound types as we can see in this example. Here we
10433 combine array types, record types, pointer types and subrange types:
10442 myarray = ARRAY myrange OF CARDINAL ;
10443 myrange = [-2..2] ;
10445 s: POINTER TO ARRAY myrange OF foo ;
10447 and you can ask GDB to describe the type of `s' as shown below.
10450 type = POINTER TO ARRAY [-2..2] OF foo = RECORD
10453 f3 : ARRAY [-2..2] OF CARDINAL;
10457 File: gdb.info, Node: M2 Defaults, Next: Deviations, Prev: M2 Types, Up: Modula-2
10459 15.4.5.5 Modula-2 Defaults
10460 ..........................
10462 If type and range checking are set automatically by GDB, they both
10463 default to `on' whenever the working language changes to Modula-2.
10464 This happens regardless of whether you or GDB selected the working
10467 If you allow GDB to set the language automatically, then entering
10468 code compiled from a file whose name ends with `.mod' sets the working
10469 language to Modula-2. *Note Having GDB Infer the Source Language:
10470 Automatically, for further details.
10473 File: gdb.info, Node: Deviations, Next: M2 Checks, Prev: M2 Defaults, Up: Modula-2
10475 15.4.5.6 Deviations from Standard Modula-2
10476 ..........................................
10478 A few changes have been made to make Modula-2 programs easier to debug.
10479 This is done primarily via loosening its type strictness:
10481 * Unlike in standard Modula-2, pointer constants can be formed by
10482 integers. This allows you to modify pointer variables during
10483 debugging. (In standard Modula-2, the actual address contained in
10484 a pointer variable is hidden from you; it can only be modified
10485 through direct assignment to another pointer variable or
10486 expression that returned a pointer.)
10488 * C escape sequences can be used in strings and characters to
10489 represent non-printable characters. GDB prints out strings with
10490 these escape sequences embedded. Single non-printable characters
10491 are printed using the `CHR(NNN)' format.
10493 * The assignment operator (`:=') returns the value of its right-hand
10496 * All built-in procedures both modify _and_ return their argument.
10499 File: gdb.info, Node: M2 Checks, Next: M2 Scope, Prev: Deviations, Up: Modula-2
10501 15.4.5.7 Modula-2 Type and Range Checks
10502 .......................................
10504 _Warning:_ in this release, GDB does not yet perform type or range
10507 GDB considers two Modula-2 variables type equivalent if:
10509 * They are of types that have been declared equivalent via a `TYPE
10512 * They have been declared on the same line. (Note: This is true of
10513 the GNU Modula-2 compiler, but it may not be true of other
10516 As long as type checking is enabled, any attempt to combine variables
10517 whose types are not equivalent is an error.
10519 Range checking is done on all mathematical operations, assignment,
10520 array index bounds, and all built-in functions and procedures.
10523 File: gdb.info, Node: M2 Scope, Next: GDB/M2, Prev: M2 Checks, Up: Modula-2
10525 15.4.5.8 The Scope Operators `::' and `.'
10526 .........................................
10528 There are a few subtle differences between the Modula-2 scope operator
10529 (`.') and the GDB scope operator (`::'). The two have similar syntax:
10535 where SCOPE is the name of a module or a procedure, MODULE the name of
10536 a module, and ID is any declared identifier within your program, except
10539 Using the `::' operator makes GDB search the scope specified by
10540 SCOPE for the identifier ID. If it is not found in the specified
10541 scope, then GDB searches all scopes enclosing the one specified by
10544 Using the `.' operator makes GDB search the current scope for the
10545 identifier specified by ID that was imported from the definition module
10546 specified by MODULE. With this operator, it is an error if the
10547 identifier ID was not imported from definition module MODULE, or if ID
10548 is not an identifier in MODULE.
10551 File: gdb.info, Node: GDB/M2, Prev: M2 Scope, Up: Modula-2
10553 15.4.5.9 GDB and Modula-2
10554 .........................
10556 Some GDB commands have little use when debugging Modula-2 programs.
10557 Five subcommands of `set print' and `show print' apply specifically to
10558 C and C++: `vtbl', `demangle', `asm-demangle', `object', and `union'.
10559 The first four apply to C++, and the last to the C `union' type, which
10560 has no direct analogue in Modula-2.
10562 The `@' operator (*note Expressions: Expressions.), while available
10563 with any language, is not useful with Modula-2. Its intent is to aid
10564 the debugging of "dynamic arrays", which cannot be created in Modula-2
10565 as they can in C or C++. However, because an address can be specified
10566 by an integral constant, the construct `{TYPE}ADREXP' is still useful.
10568 In GDB scripts, the Modula-2 inequality operator `#' is interpreted
10569 as the beginning of a comment. Use `<>' instead.
10572 File: gdb.info, Node: Ada, Prev: Modula-2, Up: Supported Languages
10577 The extensions made to GDB for Ada only support output from the GNU Ada
10578 (GNAT) compiler. Other Ada compilers are not currently supported, and
10579 attempting to debug executables produced by them is most likely to be
10584 * Ada Mode Intro:: General remarks on the Ada syntax
10585 and semantics supported by Ada mode
10587 * Omissions from Ada:: Restrictions on the Ada expression syntax.
10588 * Additions to Ada:: Extensions of the Ada expression syntax.
10589 * Stopping Before Main Program:: Debugging the program during elaboration.
10590 * Ada Tasks:: Listing and setting breakpoints in tasks.
10591 * Ada Tasks and Core Files:: Tasking Support when Debugging Core Files
10592 * Ada Glitches:: Known peculiarities of Ada mode.
10595 File: gdb.info, Node: Ada Mode Intro, Next: Omissions from Ada, Up: Ada
10597 15.4.6.1 Introduction
10598 .....................
10600 The Ada mode of GDB supports a fairly large subset of Ada expression
10601 syntax, with some extensions. The philosophy behind the design of this
10604 * That GDB should provide basic literals and access to operations for
10605 arithmetic, dereferencing, field selection, indexing, and
10606 subprogram calls, leaving more sophisticated computations to
10607 subprograms written into the program (which therefore may be
10610 * That type safety and strict adherence to Ada language restrictions
10611 are not particularly important to the GDB user.
10613 * That brevity is important to the GDB user.
10615 Thus, for brevity, the debugger acts as if all names declared in
10616 user-written packages are directly visible, even if they are not visible
10617 according to Ada rules, thus making it unnecessary to fully qualify most
10618 names with their packages, regardless of context. Where this causes
10619 ambiguity, GDB asks the user's intent.
10621 The debugger will start in Ada mode if it detects an Ada main
10622 program. As for other languages, it will enter Ada mode when stopped
10623 in a program that was translated from an Ada source file.
10625 While in Ada mode, you may use `-' for comments. This is useful
10626 mostly for documenting command files. The standard GDB comment (`#')
10627 still works at the beginning of a line in Ada mode, but not in the
10628 middle (to allow based literals).
10630 The debugger supports limited overloading. Given a subprogram call
10631 in which the function symbol has multiple definitions, it will use the
10632 number of actual parameters and some information about their types to
10633 attempt to narrow the set of definitions. It also makes very limited
10634 use of context, preferring procedures to functions in the context of
10635 the `call' command, and functions to procedures elsewhere.
10638 File: gdb.info, Node: Omissions from Ada, Next: Additions to Ada, Prev: Ada Mode Intro, Up: Ada
10640 15.4.6.2 Omissions from Ada
10641 ...........................
10643 Here are the notable omissions from the subset:
10645 * Only a subset of the attributes are supported:
10647 - 'First, 'Last, and 'Length on array objects (not on types
10656 - 'Range on array objects (not subtypes), but only as the right
10657 operand of the membership (`in') operator.
10659 - 'Access, 'Unchecked_Access, and 'Unrestricted_Access (a GNAT
10664 * The names in `Characters.Latin_1' are not available and
10665 concatenation is not implemented. Thus, escape characters in
10666 strings are not currently available.
10668 * Equality tests (`=' and `/=') on arrays test for bitwise equality
10669 of representations. They will generally work correctly for
10670 strings and arrays whose elements have integer or enumeration
10671 types. They may not work correctly for arrays whose element types
10672 have user-defined equality, for arrays of real values (in
10673 particular, IEEE-conformant floating point, because of negative
10674 zeroes and NaNs), and for arrays whose elements contain unused
10675 bits with indeterminate values.
10677 * The other component-by-component array operations (`and', `or',
10678 `xor', `not', and relational tests other than equality) are not
10681 * There is limited support for array and record aggregates. They are
10682 permitted only on the right sides of assignments, as in these
10685 (gdb) set An_Array := (1, 2, 3, 4, 5, 6)
10686 (gdb) set An_Array := (1, others => 0)
10687 (gdb) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6)
10688 (gdb) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9))
10689 (gdb) set A_Record := (1, "Peter", True);
10690 (gdb) set A_Record := (Name => "Peter", Id => 1, Alive => True)
10692 Changing a discriminant's value by assigning an aggregate has an
10693 undefined effect if that discriminant is used within the record.
10694 However, you can first modify discriminants by directly assigning
10695 to them (which normally would not be allowed in Ada), and then
10696 performing an aggregate assignment. For example, given a variable
10697 `A_Rec' declared to have a type such as:
10699 type Rec (Len : Small_Integer := 0) is record
10701 Vals : IntArray (1 .. Len);
10704 you can assign a value with a different size of `Vals' with two
10707 (gdb) set A_Rec.Len := 4
10708 (gdb) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4))
10710 As this example also illustrates, GDB is very loose about the usual
10711 rules concerning aggregates. You may leave out some of the
10712 components of an array or record aggregate (such as the `Len'
10713 component in the assignment to `A_Rec' above); they will retain
10714 their original values upon assignment. You may freely use dynamic
10715 values as indices in component associations. You may even use
10716 overlapping or redundant component associations, although which
10717 component values are assigned in such cases is not defined.
10719 * Calls to dispatching subprograms are not implemented.
10721 * The overloading algorithm is much more limited (i.e., less
10722 selective) than that of real Ada. It makes only limited use of
10723 the context in which a subexpression appears to resolve its
10724 meaning, and it is much looser in its rules for allowing type
10725 matches. As a result, some function calls will be ambiguous, and
10726 the user will be asked to choose the proper resolution.
10728 * The `new' operator is not implemented.
10730 * Entry calls are not implemented.
10732 * Aside from printing, arithmetic operations on the native VAX
10733 floating-point formats are not supported.
10735 * It is not possible to slice a packed array.
10737 * The names `True' and `False', when not part of a qualified name,
10738 are interpreted as if implicitly prefixed by `Standard',
10739 regardless of context. Should your program redefine these names
10740 in a package or procedure (at best a dubious practice), you will
10741 have to use fully qualified names to access their new definitions.
10744 File: gdb.info, Node: Additions to Ada, Next: Stopping Before Main Program, Prev: Omissions from Ada, Up: Ada
10746 15.4.6.3 Additions to Ada
10747 .........................
10749 As it does for other languages, GDB makes certain generic extensions to
10750 Ada (*note Expressions::):
10752 * If the expression E is a variable residing in memory (typically a
10753 local variable or array element) and N is a positive integer, then
10754 `E@N' displays the values of E and the N-1 adjacent variables
10755 following it in memory as an array. In Ada, this operator is
10756 generally not necessary, since its prime use is in displaying
10757 parts of an array, and slicing will usually do this in Ada.
10758 However, there are occasional uses when debugging programs in
10759 which certain debugging information has been optimized away.
10761 * `B::VAR' means "the variable named VAR that appears in function or
10762 file B." When B is a file name, you must typically surround it in
10765 * The expression `{TYPE} ADDR' means "the variable of type TYPE that
10766 appears at address ADDR."
10768 * A name starting with `$' is a convenience variable (*note
10769 Convenience Vars::) or a machine register (*note Registers::).
10771 In addition, GDB provides a few other shortcuts and outright
10772 additions specific to Ada:
10774 * The assignment statement is allowed as an expression, returning
10775 its right-hand operand as its value. Thus, you may enter
10777 (gdb) set x := y + 3
10778 (gdb) print A(tmp := y + 1)
10780 * The semicolon is allowed as an "operator," returning as its value
10781 the value of its right-hand operand. This allows, for example,
10782 complex conditional breaks:
10785 (gdb) condition 1 (report(i); k += 1; A(k) > 100)
10787 * Rather than use catenation and symbolic character names to
10788 introduce special characters into strings, one may instead use a
10789 special bracket notation, which is also used to print strings. A
10790 sequence of characters of the form `["XX"]' within a string or
10791 character literal denotes the (single) character whose numeric
10792 encoding is XX in hexadecimal. The sequence of characters `["""]'
10793 also denotes a single quotation mark in strings. For example,
10794 "One line.["0a"]Next line.["0a"]"
10795 contains an ASCII newline character (`Ada.Characters.Latin_1.LF')
10798 * The subtype used as a prefix for the attributes 'Pos, 'Min, and
10799 'Max is optional (and is ignored in any case). For example, it is
10802 (gdb) print 'max(x, y)
10804 * When printing arrays, GDB uses positional notation when the array
10805 has a lower bound of 1, and uses a modified named notation
10806 otherwise. For example, a one-dimensional array of three integers
10807 with a lower bound of 3 might print as
10811 That is, in contrast to valid Ada, only the first component has a
10814 * You may abbreviate attributes in expressions with any unique,
10815 multi-character subsequence of their names (an exact match gets
10816 preference). For example, you may use a'len, a'gth, or a'lh in
10819 * Since Ada is case-insensitive, the debugger normally maps
10820 identifiers you type to lower case. The GNAT compiler uses
10821 upper-case characters for some of its internal identifiers, which
10822 are normally of no interest to users. For the rare occasions when
10823 you actually have to look at them, enclose them in angle brackets
10824 to avoid the lower-case mapping. For example,
10825 (gdb) print <JMPBUF_SAVE>[0]
10827 * Printing an object of class-wide type or dereferencing an
10828 access-to-class-wide value will display all the components of the
10829 object's specific type (as indicated by its run-time tag).
10830 Likewise, component selection on such a value will operate on the
10831 specific type of the object.
10835 File: gdb.info, Node: Stopping Before Main Program, Next: Ada Tasks, Prev: Additions to Ada, Up: Ada
10837 15.4.6.4 Stopping at the Very Beginning
10838 .......................................
10840 It is sometimes necessary to debug the program during elaboration, and
10841 before reaching the main procedure. As defined in the Ada Reference
10842 Manual, the elaboration code is invoked from a procedure called
10843 `adainit'. To run your program up to the beginning of elaboration,
10844 simply use the following two commands: `tbreak adainit' and `run'.
10847 File: gdb.info, Node: Ada Tasks, Next: Ada Tasks and Core Files, Prev: Stopping Before Main Program, Up: Ada
10849 15.4.6.5 Extensions for Ada Tasks
10850 .................................
10852 Support for Ada tasks is analogous to that for threads (*note
10853 Threads::). GDB provides the following task-related commands:
10856 This command shows a list of current Ada tasks, as in the
10860 ID TID P-ID Pri State Name
10861 1 8088000 0 15 Child Activation Wait main_task
10862 2 80a4000 1 15 Accept Statement b
10863 3 809a800 1 15 Child Activation Wait a
10864 * 4 80ae800 3 15 Runnable c
10866 In this listing, the asterisk before the last task indicates it to
10867 be the task currently being inspected.
10870 Represents GDB's internal task number.
10876 The parent's task ID (GDB's internal task number).
10879 The base priority of the task.
10882 Current state of the task.
10885 The task has been created but has not been activated.
10886 It cannot be executing.
10889 The task is not blocked for any reason known to Ada.
10890 (It may be waiting for a mutex, though.) It is
10891 conceptually "executing" in normal mode.
10894 The task is terminated, in the sense of ARM 9.3 (5).
10895 Any dependents that were waiting on terminate
10896 alternatives have been awakened and have terminated
10899 `Child Activation Wait'
10900 The task is waiting for created tasks to complete
10904 The task is waiting on an accept or selective wait
10907 `Waiting on entry call'
10908 The task is waiting on an entry call.
10910 `Async Select Wait'
10911 The task is waiting to start the abortable part of an
10912 asynchronous select statement.
10915 The task is waiting on a select statement with only a
10916 delay alternative open.
10918 `Child Termination Wait'
10919 The task is sleeping having completed a master within
10920 itself, and is waiting for the tasks dependent on that
10921 master to become terminated or waiting on a terminate
10924 `Wait Child in Term Alt'
10925 The task is sleeping waiting for tasks on terminate
10926 alternatives to finish terminating.
10928 `Accepting RV with TASKNO'
10929 The task is accepting a rendez-vous with the task TASKNO.
10932 Name of the task in the program.
10936 This command shows detailled informations on the specified task,
10937 as in the following example:
10939 ID TID P-ID Pri State Name
10940 1 8077880 0 15 Child Activation Wait main_task
10941 * 2 807c468 1 15 Runnable task_1
10943 Ada Task: 0x807c468
10946 Parent: 1 (main_task)
10951 This command prints the ID of the current task.
10954 ID TID P-ID Pri State Name
10955 1 8077870 0 15 Child Activation Wait main_task
10956 * 2 807c458 1 15 Runnable t
10958 [Current task is 2]
10961 This command is like the `thread THREADNO' command (*note
10962 Threads::). It switches the context of debugging from the current
10963 task to the given task.
10966 ID TID P-ID Pri State Name
10967 1 8077870 0 15 Child Activation Wait main_task
10968 * 2 807c458 1 15 Runnable t
10970 [Switching to task 1]
10971 #0 0x8067726 in pthread_cond_wait ()
10973 #0 0x8067726 in pthread_cond_wait ()
10974 #1 0x8056714 in system.os_interface.pthread_cond_wait ()
10975 #2 0x805cb63 in system.task_primitives.operations.sleep ()
10976 #3 0x806153e in system.tasking.stages.activate_tasks ()
10977 #4 0x804aacc in un () at un.adb:5
10979 `break LINESPEC task TASKNO'
10980 `break LINESPEC task TASKNO if ...'
10981 These commands are like the `break ... thread ...' command (*note
10982 Thread Stops::). LINESPEC specifies source lines, as described in
10983 *note Specify Location::.
10985 Use the qualifier `task TASKNO' with a breakpoint command to
10986 specify that you only want GDB to stop the program when a
10987 particular Ada task reaches this breakpoint. TASKNO is one of the
10988 numeric task identifiers assigned by GDB, shown in the first
10989 column of the `info tasks' display.
10991 If you do not specify `task TASKNO' when you set a breakpoint, the
10992 breakpoint applies to _all_ tasks of your program.
10994 You can use the `task' qualifier on conditional breakpoints as
10995 well; in this case, place `task TASKNO' before the breakpoint
10996 condition (before the `if').
11001 ID TID P-ID Pri State Name
11002 1 140022020 0 15 Child Activation Wait main_task
11003 2 140045060 1 15 Accept/Select Wait t2
11004 3 140044840 1 15 Runnable t1
11005 * 4 140056040 1 15 Runnable t3
11007 Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15.
11013 Breakpoint 5, test_task_debug () at test_task_debug.adb:15
11016 ID TID P-ID Pri State Name
11017 1 140022020 0 15 Child Activation Wait main_task
11018 * 2 140045060 1 15 Runnable t2
11019 3 140044840 1 15 Runnable t1
11020 4 140056040 1 15 Delay Sleep t3
11023 File: gdb.info, Node: Ada Tasks and Core Files, Next: Ada Glitches, Prev: Ada Tasks, Up: Ada
11025 15.4.6.6 Tasking Support when Debugging Core Files
11026 ..................................................
11028 When inspecting a core file, as opposed to debugging a live program,
11029 tasking support may be limited or even unavailable, depending on the
11030 platform being used. For instance, on x86-linux, the list of tasks is
11031 available, but task switching is not supported. On Tru64, however,
11032 task switching will work as usual.
11034 On certain platforms, including Tru64, the debugger needs to perform
11035 some memory writes in order to provide Ada tasking support. When
11036 inspecting a core file, this means that the core file must be opened
11037 with read-write privileges, using the command `"set write on"' (*note
11038 Patching::). Under these circumstances, you should make a backup copy
11039 of the core file before inspecting it with GDB.
11042 File: gdb.info, Node: Ada Glitches, Prev: Ada Tasks and Core Files, Up: Ada
11044 15.4.6.7 Known Peculiarities of Ada Mode
11045 ........................................
11047 Besides the omissions listed previously (*note Omissions from Ada::),
11048 we know of several problems with and limitations of Ada mode in GDB,
11049 some of which will be fixed with planned future releases of the debugger
11050 and the GNU Ada compiler.
11052 * Currently, the debugger has insufficient information to determine
11053 whether certain pointers represent pointers to objects or the
11054 objects themselves. Thus, the user may have to tack an extra
11055 `.all' after an expression to get it printed properly.
11057 * Static constants that the compiler chooses not to materialize as
11058 objects in storage are invisible to the debugger.
11060 * Named parameter associations in function argument lists are
11061 ignored (the argument lists are treated as positional).
11063 * Many useful library packages are currently invisible to the
11066 * Fixed-point arithmetic, conversions, input, and output is carried
11067 out using floating-point arithmetic, and may give results that
11068 only approximate those on the host machine.
11070 * The GNAT compiler never generates the prefix `Standard' for any of
11071 the standard symbols defined by the Ada language. GDB knows about
11072 this: it will strip the prefix from names when you use it, and
11073 will never look for a name you have so qualified among local
11074 symbols, nor match against symbols in other packages or
11075 subprograms. If you have defined entities anywhere in your
11076 program other than parameters and local variables whose simple
11077 names match names in `Standard', GNAT's lack of qualification here
11078 can cause confusion. When this happens, you can usually resolve
11079 the confusion by qualifying the problematic names with package
11080 `Standard' explicitly.
11082 Older versions of the compiler sometimes generate erroneous debugging
11083 information, resulting in the debugger incorrectly printing the value
11084 of affected entities. In some cases, the debugger is able to work
11085 around an issue automatically. In other cases, the debugger is able to
11086 work around the issue, but the work-around has to be specifically
11089 `set ada trust-PAD-over-XVS on'
11090 Configure GDB to strictly follow the GNAT encoding when computing
11091 the value of Ada entities, particularly when `PAD' and `PAD___XVS'
11092 types are involved (see `ada/exp_dbug.ads' in the GCC sources for
11093 a complete description of the encoding used by the GNAT compiler).
11094 This is the default.
11096 `set ada trust-PAD-over-XVS off'
11097 This is related to the encoding using by the GNAT compiler. If
11098 GDB sometimes prints the wrong value for certain entities,
11099 changing `ada trust-PAD-over-XVS' to `off' activates a work-around
11100 which may fix the issue. It is always safe to set `ada
11101 trust-PAD-over-XVS' to `off', but this incurs a slight performance
11102 penalty, so it is recommended to leave this setting to `on' unless
11107 File: gdb.info, Node: Unsupported Languages, Prev: Supported Languages, Up: Languages
11109 15.5 Unsupported Languages
11110 ==========================
11112 In addition to the other fully-supported programming languages, GDB
11113 also provides a pseudo-language, called `minimal'. It does not
11114 represent a real programming language, but provides a set of
11115 capabilities close to what the C or assembly languages provide. This
11116 should allow most simple operations to be performed while debugging an
11117 application that uses a language currently not supported by GDB.
11119 If the language is set to `auto', GDB will automatically select this
11120 language if the current frame corresponds to an unsupported language.
11123 File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top
11125 16 Examining the Symbol Table
11126 *****************************
11128 The commands described in this chapter allow you to inquire about the
11129 symbols (names of variables, functions and types) defined in your
11130 program. This information is inherent in the text of your program and
11131 does not change as your program executes. GDB finds it in your
11132 program's symbol table, in the file indicated when you started GDB
11133 (*note Choosing Files: File Options.), or by one of the file-management
11134 commands (*note Commands to Specify Files: Files.).
11136 Occasionally, you may need to refer to symbols that contain unusual
11137 characters, which GDB ordinarily treats as word delimiters. The most
11138 frequent case is in referring to static variables in other source files
11139 (*note Program Variables: Variables.). File names are recorded in
11140 object files as debugging symbols, but GDB would ordinarily parse a
11141 typical file name, like `foo.c', as the three words `foo' `.' `c'. To
11142 allow GDB to recognize `foo.c' as a single symbol, enclose it in single
11143 quotes; for example,
11147 looks up the value of `x' in the scope of the file `foo.c'.
11149 `set case-sensitive on'
11150 `set case-sensitive off'
11151 `set case-sensitive auto'
11152 Normally, when GDB looks up symbols, it matches their names with
11153 case sensitivity determined by the current source language.
11154 Occasionally, you may wish to control that. The command `set
11155 case-sensitive' lets you do that by specifying `on' for
11156 case-sensitive matches or `off' for case-insensitive ones. If you
11157 specify `auto', case sensitivity is reset to the default suitable
11158 for the source language. The default is case-sensitive matches
11159 for all languages except for Fortran, for which the default is
11160 case-insensitive matches.
11162 `show case-sensitive'
11163 This command shows the current setting of case sensitivity for
11166 `info address SYMBOL'
11167 Describe where the data for SYMBOL is stored. For a register
11168 variable, this says which register it is kept in. For a
11169 non-register local variable, this prints the stack-frame offset at
11170 which the variable is always stored.
11172 Note the contrast with `print &SYMBOL', which does not work at all
11173 for a register variable, and for a stack local variable prints the
11174 exact address of the current instantiation of the variable.
11177 Print the name of a symbol which is stored at the address ADDR.
11178 If no symbol is stored exactly at ADDR, GDB prints the nearest
11179 symbol and an offset from it:
11181 (gdb) info symbol 0x54320
11182 _initialize_vx + 396 in section .text
11184 This is the opposite of the `info address' command. You can use
11185 it to find out the name of a variable or a function given its
11188 For dynamically linked executables, the name of executable or
11189 shared library containing the symbol is also printed:
11191 (gdb) info symbol 0x400225
11192 _start + 5 in section .text of /tmp/a.out
11193 (gdb) info symbol 0x2aaaac2811cf
11194 __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6
11197 Print the data type of ARG, which can be either an expression or a
11198 data type. With no argument, print the data type of `$', the last
11199 value in the value history. If ARG is an expression, it is not
11200 actually evaluated, and any side-effecting operations (such as
11201 assignments or function calls) inside it do not take place. If
11202 ARG is a type name, it may be the name of a type or typedef, or
11203 for C code it may have the form `class CLASS-NAME', `struct
11204 STRUCT-TAG', `union UNION-TAG' or `enum ENUM-TAG'. *Note
11205 Expressions: Expressions.
11208 `ptype' accepts the same arguments as `whatis', but prints a
11209 detailed description of the type, instead of just the name of the
11210 type. *Note Expressions: Expressions.
11212 For example, for this variable declaration:
11214 struct complex {double real; double imag;} v;
11216 the two commands give this output:
11219 type = struct complex
11221 type = struct complex {
11226 As with `whatis', using `ptype' without an argument refers to the
11227 type of `$', the last value in the value history.
11229 Sometimes, programs use opaque data types or incomplete
11230 specifications of complex data structure. If the debug
11231 information included in the program does not allow GDB to display
11232 a full declaration of the data type, it will say `<incomplete
11233 type>'. For example, given these declarations:
11236 struct foo *fooptr;
11238 but no definition for `struct foo' itself, GDB will say:
11241 $1 = <incomplete type>
11243 "Incomplete type" is C terminology for data types that are not
11244 completely specified.
11246 `info types REGEXP'
11248 Print a brief description of all types whose names match the
11249 regular expression REGEXP (or all types in your program, if you
11250 supply no argument). Each complete typename is matched as though
11251 it were a complete line; thus, `i type value' gives information on
11252 all types in your program whose names include the string `value',
11253 but `i type ^value$' gives information only on types whose complete
11256 This command differs from `ptype' in two ways: first, like
11257 `whatis', it does not print a detailed description; second, it
11258 lists all source files where a type is defined.
11260 `info scope LOCATION'
11261 List all the variables local to a particular scope. This command
11262 accepts a LOCATION argument--a function name, a source line, or an
11263 address preceded by a `*', and prints all the variables local to
11264 the scope defined by that location. (*Note Specify Location::, for
11265 details about supported forms of LOCATION.) For example:
11267 (gdb) info scope command_line_handler
11268 Scope for command_line_handler:
11269 Symbol rl is an argument at stack/frame offset 8, length 4.
11270 Symbol linebuffer is in static storage at address 0x150a18, length 4.
11271 Symbol linelength is in static storage at address 0x150a1c, length 4.
11272 Symbol p is a local variable in register $esi, length 4.
11273 Symbol p1 is a local variable in register $ebx, length 4.
11274 Symbol nline is a local variable in register $edx, length 4.
11275 Symbol repeat is a local variable at frame offset -8, length 4.
11277 This command is especially useful for determining what data to
11278 collect during a "trace experiment", see *note collect: Tracepoint
11282 Show information about the current source file--that is, the
11283 source file for the function containing the current point of
11285 * the name of the source file, and the directory containing it,
11287 * the directory it was compiled in,
11289 * its length, in lines,
11291 * which programming language it is written in,
11293 * whether the executable includes debugging information for
11294 that file, and if so, what format the information is in
11295 (e.g., STABS, Dwarf 2, etc.), and
11297 * whether the debugging information includes information about
11298 preprocessor macros.
11301 Print the names of all source files in your program for which
11302 there is debugging information, organized into two lists: files
11303 whose symbols have already been read, and files whose symbols will
11304 be read when needed.
11307 Print the names and data types of all defined functions.
11309 `info functions REGEXP'
11310 Print the names and data types of all defined functions whose
11311 names contain a match for regular expression REGEXP. Thus, `info
11312 fun step' finds all functions whose names include `step'; `info
11313 fun ^step' finds those whose names start with `step'. If a
11314 function name contains characters that conflict with the regular
11315 expression language (e.g. `operator*()'), they may be quoted with
11319 Print the names and data types of all variables that are defined
11320 outside of functions (i.e. excluding local variables).
11322 `info variables REGEXP'
11323 Print the names and data types of all variables (except for local
11324 variables) whose names contain a match for regular expression
11328 `info classes REGEXP'
11329 Display all Objective-C classes in your program, or (with the
11330 REGEXP argument) all those matching a particular regular
11334 `info selectors REGEXP'
11335 Display all Objective-C selectors in your program, or (with the
11336 REGEXP argument) all those matching a particular regular
11339 Some systems allow individual object files that make up your
11340 program to be replaced without stopping and restarting your
11341 program. For example, in VxWorks you can simply recompile a
11342 defective object file and keep on running. If you are running on
11343 one of these systems, you can allow GDB to reload the symbols for
11344 automatically relinked modules:
11346 `set symbol-reloading on'
11347 Replace symbol definitions for the corresponding source file
11348 when an object file with a particular name is seen again.
11350 `set symbol-reloading off'
11351 Do not replace symbol definitions when encountering object
11352 files of the same name more than once. This is the default
11353 state; if you are not running on a system that permits
11354 automatic relinking of modules, you should leave
11355 `symbol-reloading' off, since otherwise GDB may discard
11356 symbols when linking large programs, that may contain several
11357 modules (from different directories or libraries) with the
11360 `show symbol-reloading'
11361 Show the current `on' or `off' setting.
11363 `set opaque-type-resolution on'
11364 Tell GDB to resolve opaque types. An opaque type is a type
11365 declared as a pointer to a `struct', `class', or `union'--for
11366 example, `struct MyType *'--that is used in one source file
11367 although the full declaration of `struct MyType' is in another
11368 source file. The default is on.
11370 A change in the setting of this subcommand will not take effect
11371 until the next time symbols for a file are loaded.
11373 `set opaque-type-resolution off'
11374 Tell GDB not to resolve opaque types. In this case, the type is
11375 printed as follows:
11378 `show opaque-type-resolution'
11379 Show whether opaque types are resolved or not.
11381 `maint print symbols FILENAME'
11382 `maint print psymbols FILENAME'
11383 `maint print msymbols FILENAME'
11384 Write a dump of debugging symbol data into the file FILENAME.
11385 These commands are used to debug the GDB symbol-reading code. Only
11386 symbols with debugging data are included. If you use `maint print
11387 symbols', GDB includes all the symbols for which it has already
11388 collected full details: that is, FILENAME reflects symbols for
11389 only those files whose symbols GDB has read. You can use the
11390 command `info sources' to find out which files these are. If you
11391 use `maint print psymbols' instead, the dump shows information
11392 about symbols that GDB only knows partially--that is, symbols
11393 defined in files that GDB has skimmed, but not yet read
11394 completely. Finally, `maint print msymbols' dumps just the
11395 minimal symbol information required for each object file from
11396 which GDB has read some symbols. *Note Commands to Specify Files:
11397 Files, for a discussion of how GDB reads symbols (in the
11398 description of `symbol-file').
11400 `maint info symtabs [ REGEXP ]'
11401 `maint info psymtabs [ REGEXP ]'
11402 List the `struct symtab' or `struct partial_symtab' structures
11403 whose names match REGEXP. If REGEXP is not given, list them all.
11404 The output includes expressions which you can copy into a GDB
11405 debugging this one to examine a particular structure in more
11406 detail. For example:
11408 (gdb) maint info psymtabs dwarf2read
11409 { objfile /home/gnu/build/gdb/gdb
11410 ((struct objfile *) 0x82e69d0)
11411 { psymtab /home/gnu/src/gdb/dwarf2read.c
11412 ((struct partial_symtab *) 0x8474b10)
11415 text addresses 0x814d3c8 -- 0x8158074
11416 globals (* (struct partial_symbol **) 0x8507a08 @ 9)
11417 statics (* (struct partial_symbol **) 0x40e95b78 @ 2882)
11418 dependencies (none)
11421 (gdb) maint info symtabs
11423 We see that there is one partial symbol table whose filename
11424 contains the string `dwarf2read', belonging to the `gdb'
11425 executable; and we see that GDB has not read in any symtabs yet at
11426 all. If we set a breakpoint on a function, that will cause GDB to
11427 read the symtab for the compilation unit containing that function:
11429 (gdb) break dwarf2_psymtab_to_symtab
11430 Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c,
11432 (gdb) maint info symtabs
11433 { objfile /home/gnu/build/gdb/gdb
11434 ((struct objfile *) 0x82e69d0)
11435 { symtab /home/gnu/src/gdb/dwarf2read.c
11436 ((struct symtab *) 0x86c1f38)
11439 blockvector ((struct blockvector *) 0x86c1bd0) (primary)
11440 linetable ((struct linetable *) 0x8370fa0)
11441 debugformat DWARF 2
11447 File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top
11449 17 Altering Execution
11450 *********************
11452 Once you think you have found an error in your program, you might want
11453 to find out for certain whether correcting the apparent error would
11454 lead to correct results in the rest of the run. You can find the
11455 answer by experiment, using the GDB features for altering execution of
11458 For example, you can store new values into variables or memory
11459 locations, give your program a signal, restart it at a different
11460 address, or even return prematurely from a function.
11464 * Assignment:: Assignment to variables
11465 * Jumping:: Continuing at a different address
11466 * Signaling:: Giving your program a signal
11467 * Returning:: Returning from a function
11468 * Calling:: Calling your program's functions
11469 * Patching:: Patching your program
11472 File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering
11474 17.1 Assignment to Variables
11475 ============================
11477 To alter the value of a variable, evaluate an assignment expression.
11478 *Note Expressions: Expressions. For example,
11482 stores the value 4 into the variable `x', and then prints the value of
11483 the assignment expression (which is 4). *Note Using GDB with Different
11484 Languages: Languages, for more information on operators in supported
11487 If you are not interested in seeing the value of the assignment, use
11488 the `set' command instead of the `print' command. `set' is really the
11489 same as `print' except that the expression's value is not printed and
11490 is not put in the value history (*note Value History: Value History.).
11491 The expression is evaluated only for its effects.
11493 If the beginning of the argument string of the `set' command appears
11494 identical to a `set' subcommand, use the `set variable' command instead
11495 of just `set'. This command is identical to `set' except for its lack
11496 of subcommands. For example, if your program has a variable `width',
11497 you get an error if you try to set a new value with just `set
11498 width=13', because GDB has the command `set width':
11505 Invalid syntax in expression.
11507 The invalid expression, of course, is `=47'. In order to actually set
11508 the program's variable `width', use
11510 (gdb) set var width=47
11512 Because the `set' command has many subcommands that can conflict
11513 with the names of program variables, it is a good idea to use the `set
11514 variable' command instead of just `set'. For example, if your program
11515 has a variable `g', you run into problems if you try to set a new value
11516 with just `set g=4', because GDB has the command `set gnutarget',
11517 abbreviated `set g':
11527 The program being debugged has been started already.
11528 Start it from the beginning? (y or n) y
11529 Starting program: /home/smith/cc_progs/a.out
11530 "/home/smith/cc_progs/a.out": can't open to read symbols:
11531 Invalid bfd target.
11533 The current BFD target is "=4".
11535 The program variable `g' did not change, and you silently set the
11536 `gnutarget' to an invalid value. In order to set the variable `g', use
11540 GDB allows more implicit conversions in assignments than C; you can
11541 freely store an integer value into a pointer variable or vice versa,
11542 and you can convert any structure to any other structure that is the
11543 same length or shorter.
11545 To store values into arbitrary places in memory, use the `{...}'
11546 construct to generate a value of specified type at a specified address
11547 (*note Expressions: Expressions.). For example, `{int}0x83040' refers
11548 to memory location `0x83040' as an integer (which implies a certain size
11549 and representation in memory), and
11551 set {int}0x83040 = 4
11553 stores the value 4 into that memory location.
11556 File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering
11558 17.2 Continuing at a Different Address
11559 ======================================
11561 Ordinarily, when you continue your program, you do so at the place where
11562 it stopped, with the `continue' command. You can instead continue at
11563 an address of your own choosing, with the following commands:
11567 Resume execution at line LINESPEC or at address given by LOCATION.
11568 Execution stops again immediately if there is a breakpoint there.
11569 *Note Specify Location::, for a description of the different forms
11570 of LINESPEC and LOCATION. It is common practice to use the
11571 `tbreak' command in conjunction with `jump'. *Note Setting
11572 Breakpoints: Set Breaks.
11574 The `jump' command does not change the current stack frame, or the
11575 stack pointer, or the contents of any memory location or any
11576 register other than the program counter. If line LINESPEC is in a
11577 different function from the one currently executing, the results
11578 may be bizarre if the two functions expect different patterns of
11579 arguments or of local variables. For this reason, the `jump'
11580 command requests confirmation if the specified line is not in the
11581 function currently executing. However, even bizarre results are
11582 predictable if you are well acquainted with the machine-language
11583 code of your program.
11585 On many systems, you can get much the same effect as the `jump'
11586 command by storing a new value into the register `$pc'. The difference
11587 is that this does not start your program running; it only changes the
11588 address of where it _will_ run when you continue. For example,
11592 makes the next `continue' command or stepping command execute at
11593 address `0x485', rather than at the address where your program stopped.
11594 *Note Continuing and Stepping: Continuing and Stepping.
11596 The most common occasion to use the `jump' command is to back
11597 up--perhaps with more breakpoints set--over a portion of a program that
11598 has already executed, in order to examine its execution in more detail.
11601 File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering
11603 17.3 Giving your Program a Signal
11604 =================================
11607 Resume execution where your program stopped, but immediately give
11608 it the signal SIGNAL. SIGNAL can be the name or the number of a
11609 signal. For example, on many systems `signal 2' and `signal
11610 SIGINT' are both ways of sending an interrupt signal.
11612 Alternatively, if SIGNAL is zero, continue execution without
11613 giving a signal. This is useful when your program stopped on
11614 account of a signal and would ordinary see the signal when resumed
11615 with the `continue' command; `signal 0' causes it to resume
11618 `signal' does not repeat when you press <RET> a second time after
11619 executing the command.
11621 Invoking the `signal' command is not the same as invoking the `kill'
11622 utility from the shell. Sending a signal with `kill' causes GDB to
11623 decide what to do with the signal depending on the signal handling
11624 tables (*note Signals::). The `signal' command passes the signal
11625 directly to your program.
11628 File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering
11630 17.4 Returning from a Function
11631 ==============================
11634 `return EXPRESSION'
11635 You can cancel execution of a function call with the `return'
11636 command. If you give an EXPRESSION argument, its value is used as
11637 the function's return value.
11639 When you use `return', GDB discards the selected stack frame (and
11640 all frames within it). You can think of this as making the discarded
11641 frame return prematurely. If you wish to specify a value to be
11642 returned, give that value as the argument to `return'.
11644 This pops the selected stack frame (*note Selecting a Frame:
11645 Selection.), and any other frames inside of it, leaving its caller as
11646 the innermost remaining frame. That frame becomes selected. The
11647 specified value is stored in the registers used for returning values of
11650 The `return' command does not resume execution; it leaves the
11651 program stopped in the state that would exist if the function had just
11652 returned. In contrast, the `finish' command (*note Continuing and
11653 Stepping: Continuing and Stepping.) resumes execution until the
11654 selected stack frame returns naturally.
11656 GDB needs to know how the EXPRESSION argument should be set for the
11657 inferior. The concrete registers assignment depends on the OS ABI and
11658 the type being returned by the selected stack frame. For example it is
11659 common for OS ABI to return floating point values in FPU registers
11660 while integer values in CPU registers. Still some ABIs return even
11661 floating point values in CPU registers. Larger integer widths (such as
11662 `long long int') also have specific placement rules. GDB already knows
11663 the OS ABI from its current target so it needs to find out also the
11664 type being returned to make the assignment into the right register(s).
11666 Normally, the selected stack frame has debug info. GDB will always
11667 use the debug info instead of the implicit type of EXPRESSION when the
11668 debug info is available. For example, if you type `return -1', and the
11669 function in the current stack frame is declared to return a `long long
11670 int', GDB transparently converts the implicit `int' value of -1 into a
11673 Breakpoint 1, func () at gdb.base/return-nodebug.c:29
11676 Make func return now? (y or n) y
11677 #0 0x004004f6 in main () at gdb.base/return-nodebug.c:43
11678 43 printf ("result=%lld\n", func ());
11681 However, if the selected stack frame does not have a debug info,
11682 e.g., if the function was compiled without debug info, GDB has to find
11683 out the type to return from user. Specifying a different type by
11684 mistake may set the value in different inferior registers than the
11685 caller code expects. For example, typing `return -1' with its implicit
11686 type `int' would set only a part of a `long long int' result for a
11687 debug info less function (on 32-bit architectures). Therefore the user
11688 is required to specify the return type by an appropriate cast
11691 Breakpoint 2, 0x0040050b in func ()
11693 Return value type not available for selected stack frame.
11694 Please use an explicit cast of the value to return.
11695 (gdb) return (long long int) -1
11696 Make selected stack frame return now? (y or n) y
11697 #0 0x00400526 in main ()
11701 File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering
11703 17.5 Calling Program Functions
11704 ==============================
11707 Evaluate the expression EXPR and display the resulting value.
11708 EXPR may include calls to functions in the program being debugged.
11711 Evaluate the expression EXPR without displaying `void' returned
11714 You can use this variant of the `print' command if you want to
11715 execute a function from your program that does not return anything
11716 (a.k.a. "a void function"), but without cluttering the output with
11717 `void' returned values that GDB will otherwise print. If the
11718 result is not void, it is printed and saved in the value history.
11720 It is possible for the function you call via the `print' or `call'
11721 command to generate a signal (e.g., if there's a bug in the function,
11722 or if you passed it incorrect arguments). What happens in that case is
11723 controlled by the `set unwindonsignal' command.
11725 Similarly, with a C++ program it is possible for the function you
11726 call via the `print' or `call' command to generate an exception that is
11727 not handled due to the constraints of the dummy frame. In this case,
11728 any exception that is raised in the frame, but has an out-of-frame
11729 exception handler will not be found. GDB builds a dummy-frame for the
11730 inferior function call, and the unwinder cannot seek for exception
11731 handlers outside of this dummy-frame. What happens in that case is
11732 controlled by the `set unwind-on-terminating-exception' command.
11734 `set unwindonsignal'
11735 Set unwinding of the stack if a signal is received while in a
11736 function that GDB called in the program being debugged. If set to
11737 on, GDB unwinds the stack it created for the call and restores the
11738 context to what it was before the call. If set to off (the
11739 default), GDB stops in the frame where the signal was received.
11741 `show unwindonsignal'
11742 Show the current setting of stack unwinding in the functions
11745 `set unwind-on-terminating-exception'
11746 Set unwinding of the stack if a C++ exception is raised, but left
11747 unhandled while in a function that GDB called in the program being
11748 debugged. If set to on (the default), GDB unwinds the stack it
11749 created for the call and restores the context to what it was before
11750 the call. If set to off, GDB the exception is delivered to the
11751 default C++ exception handler and the inferior terminated.
11753 `show unwind-on-terminating-exception'
11754 Show the current setting of stack unwinding in the functions
11758 Sometimes, a function you wish to call is actually a "weak alias"
11759 for another function. In such case, GDB might not pick up the type
11760 information, including the types of the function arguments, which
11761 causes GDB to call the inferior function incorrectly. As a result, the
11762 called function will function erroneously and may even crash. A
11763 solution to that is to use the name of the aliased function instead.
11766 File: gdb.info, Node: Patching, Prev: Calling, Up: Altering
11768 17.6 Patching Programs
11769 ======================
11771 By default, GDB opens the file containing your program's executable
11772 code (or the corefile) read-only. This prevents accidental alterations
11773 to machine code; but it also prevents you from intentionally patching
11774 your program's binary.
11776 If you'd like to be able to patch the binary, you can specify that
11777 explicitly with the `set write' command. For example, you might want
11778 to turn on internal debugging flags, or even to make emergency repairs.
11782 If you specify `set write on', GDB opens executable and core files
11783 for both reading and writing; if you specify `set write off' (the
11784 default), GDB opens them read-only.
11786 If you have already loaded a file, you must load it again (using
11787 the `exec-file' or `core-file' command) after changing `set
11788 write', for your new setting to take effect.
11791 Display whether executable files and core files are opened for
11792 writing as well as reading.
11795 File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top
11800 GDB needs to know the file name of the program to be debugged, both in
11801 order to read its symbol table and in order to start your program. To
11802 debug a core dump of a previous run, you must also tell GDB the name of
11803 the core dump file.
11807 * Files:: Commands to specify files
11808 * Separate Debug Files:: Debugging information in separate files
11809 * Symbol Errors:: Errors reading symbol files
11810 * Data Files:: GDB data files
11813 File: gdb.info, Node: Files, Next: Separate Debug Files, Up: GDB Files
11815 18.1 Commands to Specify Files
11816 ==============================
11818 You may want to specify executable and core dump file names. The usual
11819 way to do this is at start-up time, using the arguments to GDB's
11820 start-up commands (*note Getting In and Out of GDB: Invocation.).
11822 Occasionally it is necessary to change to a different file during a
11823 GDB session. Or you may run GDB and forget to specify a file you want
11824 to use. Or you are debugging a remote target via `gdbserver' (*note
11825 file: Server.). In these situations the GDB commands to specify new
11829 Use FILENAME as the program to be debugged. It is read for its
11830 symbols and for the contents of pure memory. It is also the
11831 program executed when you use the `run' command. If you do not
11832 specify a directory and the file is not found in the GDB working
11833 directory, GDB uses the environment variable `PATH' as a list of
11834 directories to search, just as the shell does when looking for a
11835 program to run. You can change the value of this variable, for
11836 both GDB and your program, using the `path' command.
11838 You can load unlinked object `.o' files into GDB using the `file'
11839 command. You will not be able to "run" an object file, but you
11840 can disassemble functions and inspect variables. Also, if the
11841 underlying BFD functionality supports it, you could use `gdb
11842 -write' to patch object files using this technique. Note that GDB
11843 can neither interpret nor modify relocations in this case, so
11844 branches and some initialized variables will appear to go to the
11845 wrong place. But this feature is still handy from time to time.
11848 `file' with no argument makes GDB discard any information it has
11849 on both executable file and the symbol table.
11851 `exec-file [ FILENAME ]'
11852 Specify that the program to be run (but not the symbol table) is
11853 found in FILENAME. GDB searches the environment variable `PATH'
11854 if necessary to locate your program. Omitting FILENAME means to
11855 discard information on the executable file.
11857 `symbol-file [ FILENAME ]'
11858 Read symbol table information from file FILENAME. `PATH' is
11859 searched when necessary. Use the `file' command to get both symbol
11860 table and program to run from the same file.
11862 `symbol-file' with no argument clears out GDB information on your
11863 program's symbol table.
11865 The `symbol-file' command causes GDB to forget the contents of
11866 some breakpoints and auto-display expressions. This is because
11867 they may contain pointers to the internal data recording symbols
11868 and data types, which are part of the old symbol table data being
11869 discarded inside GDB.
11871 `symbol-file' does not repeat if you press <RET> again after
11874 When GDB is configured for a particular environment, it
11875 understands debugging information in whatever format is the
11876 standard generated for that environment; you may use either a GNU
11877 compiler, or other compilers that adhere to the local conventions.
11878 Best results are usually obtained from GNU compilers; for example,
11879 using `GCC' you can generate debugging information for optimized
11882 For most kinds of object files, with the exception of old SVR3
11883 systems using COFF, the `symbol-file' command does not normally
11884 read the symbol table in full right away. Instead, it scans the
11885 symbol table quickly to find which source files and which symbols
11886 are present. The details are read later, one source file at a
11887 time, as they are needed.
11889 The purpose of this two-stage reading strategy is to make GDB
11890 start up faster. For the most part, it is invisible except for
11891 occasional pauses while the symbol table details for a particular
11892 source file are being read. (The `set verbose' command can turn
11893 these pauses into messages if desired. *Note Optional Warnings
11894 and Messages: Messages/Warnings.)
11896 We have not implemented the two-stage strategy for COFF yet. When
11897 the symbol table is stored in COFF format, `symbol-file' reads the
11898 symbol table data in full right away. Note that "stabs-in-COFF"
11899 still does the two-stage strategy, since the debug info is actually
11902 `symbol-file [ -readnow ] FILENAME'
11903 `file [ -readnow ] FILENAME'
11904 You can override the GDB two-stage strategy for reading symbol
11905 tables by using the `-readnow' option with any of the commands that
11906 load symbol table information, if you want to be sure GDB has the
11907 entire symbol table available.
11909 `core-file [FILENAME]'
11911 Specify the whereabouts of a core dump file to be used as the
11912 "contents of memory". Traditionally, core files contain only some
11913 parts of the address space of the process that generated them; GDB
11914 can access the executable file itself for other parts.
11916 `core-file' with no argument specifies that no core file is to be
11919 Note that the core file is ignored when your program is actually
11920 running under GDB. So, if you have been running your program and
11921 you wish to debug a core file instead, you must kill the
11922 subprocess in which the program is running. To do this, use the
11923 `kill' command (*note Killing the Child Process: Kill Process.).
11925 `add-symbol-file FILENAME ADDRESS'
11926 `add-symbol-file FILENAME ADDRESS [ -readnow ]'
11927 `add-symbol-file FILENAME -sSECTION ADDRESS ...'
11928 The `add-symbol-file' command reads additional symbol table
11929 information from the file FILENAME. You would use this command
11930 when FILENAME has been dynamically loaded (by some other means)
11931 into the program that is running. ADDRESS should be the memory
11932 address at which the file has been loaded; GDB cannot figure this
11933 out for itself. You can additionally specify an arbitrary number
11934 of `-sSECTION ADDRESS' pairs, to give an explicit section name and
11935 base address for that section. You can specify any ADDRESS as an
11938 The symbol table of the file FILENAME is added to the symbol table
11939 originally read with the `symbol-file' command. You can use the
11940 `add-symbol-file' command any number of times; the new symbol data
11941 thus read keeps adding to the old. To discard all old symbol data
11942 instead, use the `symbol-file' command without any arguments.
11944 Although FILENAME is typically a shared library file, an
11945 executable file, or some other object file which has been fully
11946 relocated for loading into a process, you can also load symbolic
11947 information from relocatable `.o' files, as long as:
11949 * the file's symbolic information refers only to linker symbols
11950 defined in that file, not to symbols defined by other object
11953 * every section the file's symbolic information refers to has
11954 actually been loaded into the inferior, as it appears in the
11957 * you can determine the address at which every section was
11958 loaded, and provide these to the `add-symbol-file' command.
11960 Some embedded operating systems, like Sun Chorus and VxWorks, can
11961 load relocatable files into an already running program; such
11962 systems typically make the requirements above easy to meet.
11963 However, it's important to recognize that many native systems use
11964 complex link procedures (`.linkonce' section factoring and C++
11965 constructor table assembly, for example) that make the
11966 requirements difficult to meet. In general, one cannot assume
11967 that using `add-symbol-file' to read a relocatable object file's
11968 symbolic information will have the same effect as linking the
11969 relocatable object file into the program in the normal way.
11971 `add-symbol-file' does not repeat if you press <RET> after using
11974 `add-symbol-file-from-memory ADDRESS'
11975 Load symbols from the given ADDRESS in a dynamically loaded object
11976 file whose image is mapped directly into the inferior's memory.
11977 For example, the Linux kernel maps a `syscall DSO' into each
11978 process's address space; this DSO provides kernel-specific code for
11979 some system calls. The argument can be any expression whose
11980 evaluation yields the address of the file's shared object file
11981 header. For this command to work, you must have used
11982 `symbol-file' or `exec-file' commands in advance.
11984 `add-shared-symbol-files LIBRARY-FILE'
11985 `assf LIBRARY-FILE'
11986 The `add-shared-symbol-files' command can currently be used only
11987 in the Cygwin build of GDB on MS-Windows OS, where it is an alias
11988 for the `dll-symbols' command (*note Cygwin Native::). GDB
11989 automatically looks for shared libraries, however if GDB does not
11990 find yours, you can invoke `add-shared-symbol-files'. It takes
11991 one argument: the shared library's file name. `assf' is a
11992 shorthand alias for `add-shared-symbol-files'.
11994 `section SECTION ADDR'
11995 The `section' command changes the base address of the named
11996 SECTION of the exec file to ADDR. This can be used if the exec
11997 file does not contain section addresses, (such as in the `a.out'
11998 format), or when the addresses specified in the file itself are
11999 wrong. Each section must be changed separately. The `info files'
12000 command, described below, lists all the sections and their
12005 `info files' and `info target' are synonymous; both print the
12006 current target (*note Specifying a Debugging Target: Targets.),
12007 including the names of the executable and core dump files
12008 currently in use by GDB, and the files from which symbols were
12009 loaded. The command `help target' lists all possible targets
12010 rather than current ones.
12012 `maint info sections'
12013 Another command that can give you extra information about program
12014 sections is `maint info sections'. In addition to the section
12015 information displayed by `info files', this command displays the
12016 flags and file offset of each section in the executable and core
12017 dump files. In addition, `maint info sections' provides the
12018 following command options (which may be arbitrarily combined):
12021 Display sections for all loaded object files, including
12025 Display info only for named SECTIONS.
12028 Display info only for sections for which SECTION-FLAGS are
12029 true. The section flags that GDB currently knows about are:
12031 Section will have space allocated in the process when
12032 loaded. Set for all sections except those containing
12036 Section will be loaded from the file into the child
12037 process memory. Set for pre-initialized code and data,
12038 clear for `.bss' sections.
12041 Section needs to be relocated before loading.
12044 Section cannot be modified by the child process.
12047 Section contains executable code only.
12050 Section contains data only (no executable code).
12053 Section will reside in ROM.
12056 Section contains data for constructor/destructor lists.
12059 Section is not empty.
12062 An instruction to the linker to not output the section.
12064 `COFF_SHARED_LIBRARY'
12065 A notification to the linker that the section contains
12066 COFF shared library information.
12069 Section contains common symbols.
12071 `set trust-readonly-sections on'
12072 Tell GDB that readonly sections in your object file really are
12073 read-only (i.e. that their contents will not change). In that
12074 case, GDB can fetch values from these sections out of the object
12075 file, rather than from the target program. For some targets
12076 (notably embedded ones), this can be a significant enhancement to
12077 debugging performance.
12079 The default is off.
12081 `set trust-readonly-sections off'
12082 Tell GDB not to trust readonly sections. This means that the
12083 contents of the section might change while the program is running,
12084 and must therefore be fetched from the target when needed.
12086 `show trust-readonly-sections'
12087 Show the current setting of trusting readonly sections.
12089 All file-specifying commands allow both absolute and relative file
12090 names as arguments. GDB always converts the file name to an absolute
12091 file name and remembers it that way.
12093 GDB supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, and
12094 IBM RS/6000 AIX shared libraries.
12096 On MS-Windows GDB must be linked with the Expat library to support
12097 shared libraries. *Note Expat::.
12099 GDB automatically loads symbol definitions from shared libraries
12100 when you use the `run' command, or when you examine a core file.
12101 (Before you issue the `run' command, GDB does not understand references
12102 to a function in a shared library, however--unless you are debugging a
12105 On HP-UX, if the program loads a library explicitly, GDB
12106 automatically loads the symbols at the time of the `shl_load' call.
12108 There are times, however, when you may wish to not automatically load
12109 symbol definitions from shared libraries, such as when they are
12110 particularly large or there are many of them.
12112 To control the automatic loading of shared library symbols, use the
12115 `set auto-solib-add MODE'
12116 If MODE is `on', symbols from all shared object libraries will be
12117 loaded automatically when the inferior begins execution, you
12118 attach to an independently started inferior, or when the dynamic
12119 linker informs GDB that a new library has been loaded. If MODE is
12120 `off', symbols must be loaded manually, using the `sharedlibrary'
12121 command. The default value is `on'.
12123 If your program uses lots of shared libraries with debug info that
12124 takes large amounts of memory, you can decrease the GDB memory
12125 footprint by preventing it from automatically loading the symbols
12126 from shared libraries. To that end, type `set auto-solib-add off'
12127 before running the inferior, then load each library whose debug
12128 symbols you do need with `sharedlibrary REGEXP', where REGEXP is a
12129 regular expression that matches the libraries whose symbols you
12132 `show auto-solib-add'
12133 Display the current autoloading mode.
12135 To explicitly load shared library symbols, use the `sharedlibrary'
12139 `info sharedlibrary REGEX'
12140 Print the names of the shared libraries which are currently loaded
12141 that match REGEX. If REGEX is omitted then print all shared
12142 libraries that are loaded.
12144 `sharedlibrary REGEX'
12146 Load shared object library symbols for files matching a Unix
12147 regular expression. As with files loaded automatically, it only
12148 loads shared libraries required by your program for a core file or
12149 after typing `run'. If REGEX is omitted all shared libraries
12150 required by your program are loaded.
12153 Unload all shared object library symbols. This discards all
12154 symbols that have been loaded from all shared libraries. Symbols
12155 from shared libraries that were loaded by explicit user requests
12158 Sometimes you may wish that GDB stops and gives you control when any
12159 of shared library events happen. Use the `set stop-on-solib-events'
12162 `set stop-on-solib-events'
12163 This command controls whether GDB should give you control when the
12164 dynamic linker notifies it about some shared library event. The
12165 most common event of interest is loading or unloading of a new
12168 `show stop-on-solib-events'
12169 Show whether GDB stops and gives you control when shared library
12172 Shared libraries are also supported in many cross or remote debugging
12173 configurations. GDB needs to have access to the target's libraries;
12174 this can be accomplished either by providing copies of the libraries on
12175 the host system, or by asking GDB to automatically retrieve the
12176 libraries from the target. If copies of the target libraries are
12177 provided, they need to be the same as the target libraries, although the
12178 copies on the target can be stripped as long as the copies on the host
12181 For remote debugging, you need to tell GDB where the target
12182 libraries are, so that it can load the correct copies--otherwise, it
12183 may try to load the host's libraries. GDB has two variables to specify
12184 the search directories for target libraries.
12187 Use PATH as the system root for the program being debugged. Any
12188 absolute shared library paths will be prefixed with PATH; many
12189 runtime loaders store the absolute paths to the shared library in
12190 the target program's memory. If you use `set sysroot' to find
12191 shared libraries, they need to be laid out in the same way that
12192 they are on the target, with e.g. a `/lib' and `/usr/lib' hierarchy
12195 If PATH starts with the sequence `remote:', GDB will retrieve the
12196 target libraries from the remote system. This is only supported
12197 when using a remote target that supports the `remote get' command
12198 (*note Sending files to a remote system: File Transfer.). The
12199 part of PATH following the initial `remote:' (if present) is used
12200 as system root prefix on the remote file system. (1)
12202 The `set solib-absolute-prefix' command is an alias for `set
12205 You can set the default system root by using the configure-time
12206 `--with-sysroot' option. If the system root is inside GDB's
12207 configured binary prefix (set with `--prefix' or `--exec-prefix'),
12208 then the default system root will be updated automatically if the
12209 installed GDB is moved to a new location.
12212 Display the current shared library prefix.
12214 `set solib-search-path PATH'
12215 If this variable is set, PATH is a colon-separated list of
12216 directories to search for shared libraries. `solib-search-path'
12217 is used after `sysroot' fails to locate the library, or if the
12218 path to the library is relative instead of absolute. If you want
12219 to use `solib-search-path' instead of `sysroot', be sure to set
12220 `sysroot' to a nonexistent directory to prevent GDB from finding
12221 your host's libraries. `sysroot' is preferred; setting it to a
12222 nonexistent directory may interfere with automatic loading of
12223 shared library symbols.
12225 `show solib-search-path'
12226 Display the current shared library search path.
12228 ---------- Footnotes ----------
12230 (1) If you want to specify a local system root using a directory
12231 that happens to be named `remote:', you need to use some equivalent
12232 variant of the name like `./remote:'.
12235 File: gdb.info, Node: Separate Debug Files, Next: Symbol Errors, Prev: Files, Up: GDB Files
12237 18.2 Debugging Information in Separate Files
12238 ============================================
12240 GDB allows you to put a program's debugging information in a file
12241 separate from the executable itself, in a way that allows GDB to find
12242 and load the debugging information automatically. Since debugging
12243 information can be very large--sometimes larger than the executable
12244 code itself--some systems distribute debugging information for their
12245 executables in separate files, which users can install only when they
12246 need to debug a problem.
12248 GDB supports two ways of specifying the separate debug info file:
12250 * The executable contains a "debug link" that specifies the name of
12251 the separate debug info file. The separate debug file's name is
12252 usually `EXECUTABLE.debug', where EXECUTABLE is the name of the
12253 corresponding executable file without leading directories (e.g.,
12254 `ls.debug' for `/usr/bin/ls'). In addition, the debug link
12255 specifies a 32-bit "Cyclic Redundancy Check" (CRC) checksum for
12256 the debug file, which GDB uses to validate that the executable and
12257 the debug file came from the same build.
12259 * The executable contains a "build ID", a unique bit string that is
12260 also present in the corresponding debug info file. (This is
12261 supported only on some operating systems, notably those which use
12262 the ELF format for binary files and the GNU Binutils.) For more
12263 details about this feature, see the description of the `--build-id'
12264 command-line option in *note Command Line Options:
12265 (ld.info)Options. The debug info file's name is not specified
12266 explicitly by the build ID, but can be computed from the build ID,
12269 Depending on the way the debug info file is specified, GDB uses two
12270 different methods of looking for the debug file:
12272 * For the "debug link" method, GDB looks up the named file in the
12273 directory of the executable file, then in a subdirectory of that
12274 directory named `.debug', and finally under the global debug
12275 directory, in a subdirectory whose name is identical to the leading
12276 directories of the executable's absolute file name.
12278 * For the "build ID" method, GDB looks in the `.build-id'
12279 subdirectory of the global debug directory for a file named
12280 `NN/NNNNNNNN.debug', where NN are the first 2 hex characters of
12281 the build ID bit string, and NNNNNNNN are the rest of the bit
12282 string. (Real build ID strings are 32 or more hex characters, not
12285 So, for example, suppose you ask GDB to debug `/usr/bin/ls', which
12286 has a debug link that specifies the file `ls.debug', and a build ID
12287 whose value in hex is `abcdef1234'. If the global debug directory is
12288 `/usr/lib/debug', then GDB will look for the following debug
12289 information files, in the indicated order:
12291 - `/usr/lib/debug/.build-id/ab/cdef1234.debug'
12293 - `/usr/bin/ls.debug'
12295 - `/usr/bin/.debug/ls.debug'
12297 - `/usr/lib/debug/usr/bin/ls.debug'.
12299 You can set the global debugging info directory's name, and view the
12300 name GDB is currently using.
12302 `set debug-file-directory DIRECTORIES'
12303 Set the directories which GDB searches for separate debugging
12304 information files to DIRECTORY. Multiple directory components can
12305 be set concatenating them by a directory separator.
12307 `show debug-file-directory'
12308 Show the directories GDB searches for separate debugging
12312 A debug link is a special section of the executable file named
12313 `.gnu_debuglink'. The section must contain:
12315 * A filename, with any leading directory components removed,
12316 followed by a zero byte,
12318 * zero to three bytes of padding, as needed to reach the next
12319 four-byte boundary within the section, and
12321 * a four-byte CRC checksum, stored in the same endianness used for
12322 the executable file itself. The checksum is computed on the
12323 debugging information file's full contents by the function given
12324 below, passing zero as the CRC argument.
12326 Any executable file format can carry a debug link, as long as it can
12327 contain a section named `.gnu_debuglink' with the contents described
12330 The build ID is a special section in the executable file (and in
12331 other ELF binary files that GDB may consider). This section is often
12332 named `.note.gnu.build-id', but that name is not mandatory. It
12333 contains unique identification for the built files--the ID remains the
12334 same across multiple builds of the same build tree. The default
12335 algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the
12336 content for the build ID string. The same section with an identical
12337 value is present in the original built binary with symbols, in its
12338 stripped variant, and in the separate debugging information file.
12340 The debugging information file itself should be an ordinary
12341 executable, containing a full set of linker symbols, sections, and
12342 debugging information. The sections of the debugging information file
12343 should have the same names, addresses, and sizes as the original file,
12344 but they need not contain any data--much like a `.bss' section in an
12345 ordinary executable.
12347 The GNU binary utilities (Binutils) package includes the `objcopy'
12348 utility that can produce the separated executable / debugging
12349 information file pairs using the following commands:
12351 objcopy --only-keep-debug foo foo.debug
12354 These commands remove the debugging information from the executable
12355 file `foo' and place it in the file `foo.debug'. You can use the
12356 first, second or both methods to link the two files:
12358 * The debug link method needs the following additional command to
12359 also leave behind a debug link in `foo':
12361 objcopy --add-gnu-debuglink=foo.debug foo
12363 Ulrich Drepper's `elfutils' package, starting with version 0.53,
12364 contains a version of the `strip' command such that the command
12365 `strip foo -f foo.debug' has the same functionality as the two
12366 `objcopy' commands and the `ln -s' command above, together.
12368 * Build ID gets embedded into the main executable using `ld
12369 --build-id' or the GCC counterpart `gcc -Wl,--build-id'. Build ID
12370 support plus compatibility fixes for debug files separation are
12371 present in GNU binary utilities (Binutils) package since version
12374 The CRC used in `.gnu_debuglink' is the CRC-32 defined in IEEE 802.3
12375 using the polynomial:
12377 x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11
12378 + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1
12380 The function is computed byte at a time, taking the least
12381 significant bit of each byte first. The initial pattern `0xffffffff'
12382 is used, to ensure leading zeros affect the CRC and the final result is
12383 inverted to ensure trailing zeros also affect the CRC.
12385 _Note:_ This is the same CRC polynomial as used in handling the
12386 "Remote Serial Protocol" `qCRC' packet (*note GDB Remote Serial
12387 Protocol: Remote Protocol.). However in the case of the Remote Serial
12388 Protocol, the CRC is computed _most_ significant bit first, and the
12389 result is not inverted, so trailing zeros have no effect on the CRC
12392 To complete the description, we show below the code of the function
12393 which produces the CRC used in `.gnu_debuglink'. Inverting the
12394 initially supplied `crc' argument means that an initial call to this
12395 function passing in zero will start computing the CRC using
12399 gnu_debuglink_crc32 (unsigned long crc,
12400 unsigned char *buf, size_t len)
12402 static const unsigned long crc32_table[256] =
12404 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419,
12405 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4,
12406 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07,
12407 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,
12408 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856,
12409 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
12410 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4,
12411 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,
12412 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3,
12413 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a,
12414 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599,
12415 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
12416 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190,
12417 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f,
12418 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e,
12419 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,
12420 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed,
12421 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
12422 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3,
12423 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,
12424 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a,
12425 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5,
12426 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010,
12427 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
12428 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17,
12429 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6,
12430 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615,
12431 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,
12432 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344,
12433 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
12434 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a,
12435 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,
12436 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1,
12437 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c,
12438 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef,
12439 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
12440 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe,
12441 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31,
12442 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c,
12443 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,
12444 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b,
12445 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
12446 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1,
12447 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,
12448 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278,
12449 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7,
12450 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66,
12451 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
12452 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605,
12453 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8,
12454 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b,
12457 unsigned char *end;
12459 crc = ~crc & 0xffffffff;
12460 for (end = buf + len; buf < end; ++buf)
12461 crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);
12462 return ~crc & 0xffffffff;
12465 This computation does not apply to the "build ID" method.
12468 File: gdb.info, Node: Symbol Errors, Next: Data Files, Prev: Separate Debug Files, Up: GDB Files
12470 18.3 Errors Reading Symbol Files
12471 ================================
12473 While reading a symbol file, GDB occasionally encounters problems, such
12474 as symbol types it does not recognize, or known bugs in compiler
12475 output. By default, GDB does not notify you of such problems, since
12476 they are relatively common and primarily of interest to people
12477 debugging compilers. If you are interested in seeing information about
12478 ill-constructed symbol tables, you can either ask GDB to print only one
12479 message about each such type of problem, no matter how many times the
12480 problem occurs; or you can ask GDB to print more messages, to see how
12481 many times the problems occur, with the `set complaints' command (*note
12482 Optional Warnings and Messages: Messages/Warnings.).
12484 The messages currently printed, and their meanings, include:
12486 `inner block not inside outer block in SYMBOL'
12487 The symbol information shows where symbol scopes begin and end
12488 (such as at the start of a function or a block of statements).
12489 This error indicates that an inner scope block is not fully
12490 contained in its outer scope blocks.
12492 GDB circumvents the problem by treating the inner block as if it
12493 had the same scope as the outer block. In the error message,
12494 SYMBOL may be shown as "`(don't know)'" if the outer block is not a
12497 `block at ADDRESS out of order'
12498 The symbol information for symbol scope blocks should occur in
12499 order of increasing addresses. This error indicates that it does
12502 GDB does not circumvent this problem, and has trouble locating
12503 symbols in the source file whose symbols it is reading. (You can
12504 often determine what source file is affected by specifying `set
12505 verbose on'. *Note Optional Warnings and Messages:
12506 Messages/Warnings.)
12508 `bad block start address patched'
12509 The symbol information for a symbol scope block has a start address
12510 smaller than the address of the preceding source line. This is
12511 known to occur in the SunOS 4.1.1 (and earlier) C compiler.
12513 GDB circumvents the problem by treating the symbol scope block as
12514 starting on the previous source line.
12516 `bad string table offset in symbol N'
12517 Symbol number N contains a pointer into the string table which is
12518 larger than the size of the string table.
12520 GDB circumvents the problem by considering the symbol to have the
12521 name `foo', which may cause other problems if many symbols end up
12524 `unknown symbol type `0xNN''
12525 The symbol information contains new data types that GDB does not
12526 yet know how to read. `0xNN' is the symbol type of the
12527 uncomprehended information, in hexadecimal.
12529 GDB circumvents the error by ignoring this symbol information.
12530 This usually allows you to debug your program, though certain
12531 symbols are not accessible. If you encounter such a problem and
12532 feel like debugging it, you can debug `gdb' with itself, breakpoint
12533 on `complain', then go up to the function `read_dbx_symtab' and
12534 examine `*bufp' to see the symbol.
12536 `stub type has NULL name'
12537 GDB could not find the full definition for a struct or class.
12539 `const/volatile indicator missing (ok if using g++ v1.x), got...'
12540 The symbol information for a C++ member function is missing some
12541 information that recent versions of the compiler should have
12544 `info mismatch between compiler and debugger'
12545 GDB could not parse a type specification output by the compiler.
12549 File: gdb.info, Node: Data Files, Prev: Symbol Errors, Up: GDB Files
12551 18.4 GDB Data Files
12552 ===================
12554 GDB will sometimes read an auxiliary data file. These files are kept
12555 in a directory known as the "data directory".
12557 You can set the data directory's name, and view the name GDB is
12560 `set data-directory DIRECTORY'
12561 Set the directory which GDB searches for auxiliary data files to
12564 `show data-directory'
12565 Show the directory GDB searches for auxiliary data files.
12567 You can set the default data directory by using the configure-time
12568 `--with-gdb-datadir' option. If the data directory is inside GDB's
12569 configured binary prefix (set with `--prefix' or `--exec-prefix'), then
12570 the default data directory will be updated automatically if the
12571 installed GDB is moved to a new location.
12574 File: gdb.info, Node: Targets, Next: Remote Debugging, Prev: GDB Files, Up: Top
12576 19 Specifying a Debugging Target
12577 ********************************
12579 A "target" is the execution environment occupied by your program.
12581 Often, GDB runs in the same host environment as your program; in
12582 that case, the debugging target is specified as a side effect when you
12583 use the `file' or `core' commands. When you need more flexibility--for
12584 example, running GDB on a physically separate host, or controlling a
12585 standalone system over a serial port or a realtime system over a TCP/IP
12586 connection--you can use the `target' command to specify one of the
12587 target types configured for GDB (*note Commands for Managing Targets:
12590 It is possible to build GDB for several different "target
12591 architectures". When GDB is built like that, you can choose one of the
12592 available architectures with the `set architecture' command.
12594 `set architecture ARCH'
12595 This command sets the current target architecture to ARCH. The
12596 value of ARCH can be `"auto"', in addition to one of the supported
12599 `show architecture'
12600 Show the current target architecture.
12604 These are alias commands for, respectively, `set architecture' and
12605 `show architecture'.
12609 * Active Targets:: Active targets
12610 * Target Commands:: Commands for managing targets
12611 * Byte Order:: Choosing target byte order
12614 File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets
12616 19.1 Active Targets
12617 ===================
12619 There are three classes of targets: processes, core files, and
12620 executable files. GDB can work concurrently on up to three active
12621 targets, one in each class. This allows you to (for example) start a
12622 process and inspect its activity without abandoning your work on a core
12625 For example, if you execute `gdb a.out', then the executable file
12626 `a.out' is the only active target. If you designate a core file as
12627 well--presumably from a prior run that crashed and coredumped--then GDB
12628 has two active targets and uses them in tandem, looking first in the
12629 corefile target, then in the executable file, to satisfy requests for
12630 memory addresses. (Typically, these two classes of target are
12631 complementary, since core files contain only a program's read-write
12632 memory--variables and so on--plus machine status, while executable
12633 files contain only the program text and initialized data.)
12635 When you type `run', your executable file becomes an active process
12636 target as well. When a process target is active, all GDB commands
12637 requesting memory addresses refer to that target; addresses in an
12638 active core file or executable file target are obscured while the
12639 process target is active.
12641 Use the `core-file' and `exec-file' commands to select a new core
12642 file or executable target (*note Commands to Specify Files: Files.).
12643 To specify as a target a process that is already running, use the
12644 `attach' command (*note Debugging an Already-running Process: Attach.).
12647 File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets
12649 19.2 Commands for Managing Targets
12650 ==================================
12652 `target TYPE PARAMETERS'
12653 Connects the GDB host environment to a target machine or process.
12654 A target is typically a protocol for talking to debugging
12655 facilities. You use the argument TYPE to specify the type or
12656 protocol of the target machine.
12658 Further PARAMETERS are interpreted by the target protocol, but
12659 typically include things like device names or host names to connect
12660 with, process numbers, and baud rates.
12662 The `target' command does not repeat if you press <RET> again
12663 after executing the command.
12666 Displays the names of all targets available. To display targets
12667 currently selected, use either `info target' or `info files'
12668 (*note Commands to Specify Files: Files.).
12671 Describe a particular target, including any parameters necessary to
12674 `set gnutarget ARGS'
12675 GDB uses its own library BFD to read your files. GDB knows
12676 whether it is reading an "executable", a "core", or a ".o" file;
12677 however, you can specify the file format with the `set gnutarget'
12678 command. Unlike most `target' commands, with `gnutarget' the
12679 `target' refers to a program, not a machine.
12681 _Warning:_ To specify a file format with `set gnutarget', you
12682 must know the actual BFD name.
12684 *Note Commands to Specify Files: Files.
12687 Use the `show gnutarget' command to display what file format
12688 `gnutarget' is set to read. If you have not set `gnutarget', GDB
12689 will determine the file format for each file automatically, and
12690 `show gnutarget' displays `The current BDF target is "auto"'.
12692 Here are some common targets (available, or not, depending on the GDB
12695 `target exec PROGRAM'
12696 An executable file. `target exec PROGRAM' is the same as
12697 `exec-file PROGRAM'.
12699 `target core FILENAME'
12700 A core dump file. `target core FILENAME' is the same as
12701 `core-file FILENAME'.
12703 `target remote MEDIUM'
12704 A remote system connected to GDB via a serial line or network
12705 connection. This command tells GDB to use its own remote protocol
12706 over MEDIUM for debugging. *Note Remote Debugging::.
12708 For example, if you have a board connected to `/dev/ttya' on the
12709 machine running GDB, you could say:
12711 target remote /dev/ttya
12713 `target remote' supports the `load' command. This is only useful
12714 if you have some other way of getting the stub to the target
12715 system, and you can put it somewhere in memory where it won't get
12716 clobbered by the download.
12719 Builtin CPU simulator. GDB includes simulators for most
12720 architectures. In general,
12724 works; however, you cannot assume that a specific memory map,
12725 device drivers, or even basic I/O is available, although some
12726 simulators do provide these. For info about any
12727 processor-specific simulator details, see the appropriate section
12728 in *note Embedded Processors: Embedded Processors.
12731 Some configurations may include these targets as well:
12734 NetROM ROM emulator. This target only supports downloading.
12737 Different targets are available on different configurations of GDB;
12738 your configuration may have more or fewer targets.
12740 Many remote targets require you to download the executable's code
12741 once you've successfully established a connection. You may wish to
12742 control various aspects of this process.
12745 This command controls whether a hash mark `#' is displayed while
12746 downloading a file to the remote monitor. If on, a hash mark is
12747 displayed after each S-record is successfully downloaded to the
12751 Show the current status of displaying the hash mark.
12753 `set debug monitor'
12754 Enable or disable display of communications messages between GDB
12755 and the remote monitor.
12757 `show debug monitor'
12758 Show the current status of displaying communications between GDB
12759 and the remote monitor.
12762 Depending on what remote debugging facilities are configured into
12763 GDB, the `load' command may be available. Where it exists, it is
12764 meant to make FILENAME (an executable) available for debugging on
12765 the remote system--by downloading, or dynamic linking, for example.
12766 `load' also records the FILENAME symbol table in GDB, like the
12767 `add-symbol-file' command.
12769 If your GDB does not have a `load' command, attempting to execute
12770 it gets the error message "`You can't do that when your target is
12773 The file is loaded at whatever address is specified in the
12774 executable. For some object file formats, you can specify the
12775 load address when you link the program; for other formats, like
12776 a.out, the object file format specifies a fixed address.
12778 Depending on the remote side capabilities, GDB may be able to load
12779 programs into flash memory.
12781 `load' does not repeat if you press <RET> again after using it.
12784 File: gdb.info, Node: Byte Order, Prev: Target Commands, Up: Targets
12786 19.3 Choosing Target Byte Order
12787 ===============================
12789 Some types of processors, such as the MIPS, PowerPC, and Renesas SH,
12790 offer the ability to run either big-endian or little-endian byte
12791 orders. Usually the executable or symbol will include a bit to
12792 designate the endian-ness, and you will not need to worry about which
12793 to use. However, you may still find it useful to adjust GDB's idea of
12794 processor endian-ness manually.
12797 Instruct GDB to assume the target is big-endian.
12799 `set endian little'
12800 Instruct GDB to assume the target is little-endian.
12803 Instruct GDB to use the byte order associated with the executable.
12806 Display GDB's current idea of the target byte order.
12809 Note that these commands merely adjust interpretation of symbolic
12810 data on the host, and that they have absolutely no effect on the target
12814 File: gdb.info, Node: Remote Debugging, Next: Configurations, Prev: Targets, Up: Top
12816 20 Debugging Remote Programs
12817 ****************************
12819 If you are trying to debug a program running on a machine that cannot
12820 run GDB in the usual way, it is often useful to use remote debugging.
12821 For example, you might use remote debugging on an operating system
12822 kernel, or on a small system which does not have a general purpose
12823 operating system powerful enough to run a full-featured debugger.
12825 Some configurations of GDB have special serial or TCP/IP interfaces
12826 to make this work with particular debugging targets. In addition, GDB
12827 comes with a generic serial protocol (specific to GDB, but not specific
12828 to any particular target system) which you can use if you write the
12829 remote stubs--the code that runs on the remote system to communicate
12832 Other remote targets may be available in your configuration of GDB;
12833 use `help target' to list them.
12837 * Connecting:: Connecting to a remote target
12838 * File Transfer:: Sending files to a remote system
12839 * Server:: Using the gdbserver program
12840 * Remote Configuration:: Remote configuration
12841 * Remote Stub:: Implementing a remote stub
12844 File: gdb.info, Node: Connecting, Next: File Transfer, Up: Remote Debugging
12846 20.1 Connecting to a Remote Target
12847 ==================================
12849 On the GDB host machine, you will need an unstripped copy of your
12850 program, since GDB needs symbol and debugging information. Start up
12851 GDB as usual, using the name of the local copy of your program as the
12854 GDB can communicate with the target over a serial line, or over an
12855 IP network using TCP or UDP. In each case, GDB uses the same protocol
12856 for debugging your program; only the medium carrying the debugging
12857 packets varies. The `target remote' command establishes a connection
12858 to the target. Its arguments indicate which medium to use:
12860 `target remote SERIAL-DEVICE'
12861 Use SERIAL-DEVICE to communicate with the target. For example, to
12862 use a serial line connected to the device named `/dev/ttyb':
12864 target remote /dev/ttyb
12866 If you're using a serial line, you may want to give GDB the
12867 `--baud' option, or use the `set remotebaud' command (*note set
12868 remotebaud: Remote Configuration.) before the `target' command.
12870 `target remote `HOST:PORT''
12871 `target remote `tcp:HOST:PORT''
12872 Debug using a TCP connection to PORT on HOST. The HOST may be
12873 either a host name or a numeric IP address; PORT must be a decimal
12874 number. The HOST could be the target machine itself, if it is
12875 directly connected to the net, or it might be a terminal server
12876 which in turn has a serial line to the target.
12878 For example, to connect to port 2828 on a terminal server named
12881 target remote manyfarms:2828
12883 If your remote target is actually running on the same machine as
12884 your debugger session (e.g. a simulator for your target running on
12885 the same host), you can omit the hostname. For example, to
12886 connect to port 1234 on your local machine:
12888 target remote :1234
12889 Note that the colon is still required here.
12891 `target remote `udp:HOST:PORT''
12892 Debug using UDP packets to PORT on HOST. For example, to connect
12893 to UDP port 2828 on a terminal server named `manyfarms':
12895 target remote udp:manyfarms:2828
12897 When using a UDP connection for remote debugging, you should keep
12898 in mind that the `U' stands for "Unreliable". UDP can silently
12899 drop packets on busy or unreliable networks, which will cause
12900 havoc with your debugging session.
12902 `target remote | COMMAND'
12903 Run COMMAND in the background and communicate with it using a
12904 pipe. The COMMAND is a shell command, to be parsed and expanded
12905 by the system's command shell, `/bin/sh'; it should expect remote
12906 protocol packets on its standard input, and send replies on its
12907 standard output. You could use this to run a stand-alone simulator
12908 that speaks the remote debugging protocol, to make net connections
12909 using programs like `ssh', or for other similar tricks.
12911 If COMMAND closes its standard output (perhaps by exiting), GDB
12912 will try to send it a `SIGTERM' signal. (If the program has
12913 already exited, this will have no effect.)
12916 Once the connection has been established, you can use all the usual
12917 commands to examine and change data. The remote program is already
12918 running; you can use `step' and `continue', and you do not need to use
12921 Whenever GDB is waiting for the remote program, if you type the
12922 interrupt character (often `Ctrl-c'), GDB attempts to stop the program.
12923 This may or may not succeed, depending in part on the hardware and the
12924 serial drivers the remote system uses. If you type the interrupt
12925 character once again, GDB displays this prompt:
12927 Interrupted while waiting for the program.
12928 Give up (and stop debugging it)? (y or n)
12930 If you type `y', GDB abandons the remote debugging session. (If you
12931 decide you want to try again later, you can use `target remote' again
12932 to connect once more.) If you type `n', GDB goes back to waiting.
12935 When you have finished debugging the remote program, you can use
12936 the `detach' command to release it from GDB control. Detaching
12937 from the target normally resumes its execution, but the results
12938 will depend on your particular remote stub. After the `detach'
12939 command, GDB is free to connect to another target.
12942 The `disconnect' command behaves like `detach', except that the
12943 target is generally not resumed. It will wait for GDB (this
12944 instance or another one) to connect and continue debugging. After
12945 the `disconnect' command, GDB is again free to connect to another
12949 This command allows you to send arbitrary commands directly to the
12950 remote monitor. Since GDB doesn't care about the commands it
12951 sends like this, this command is the way to extend GDB--you can
12952 add new commands that only the external monitor will understand
12956 File: gdb.info, Node: File Transfer, Next: Server, Prev: Connecting, Up: Remote Debugging
12958 20.2 Sending files to a remote system
12959 =====================================
12961 Some remote targets offer the ability to transfer files over the same
12962 connection used to communicate with GDB. This is convenient for
12963 targets accessible through other means, e.g. GNU/Linux systems running
12964 `gdbserver' over a network interface. For other targets, e.g. embedded
12965 devices with only a single serial port, this may be the only way to
12966 upload or download files.
12968 Not all remote targets support these commands.
12970 `remote put HOSTFILE TARGETFILE'
12971 Copy file HOSTFILE from the host system (the machine running GDB)
12972 to TARGETFILE on the target system.
12974 `remote get TARGETFILE HOSTFILE'
12975 Copy file TARGETFILE from the target system to HOSTFILE on the
12978 `remote delete TARGETFILE'
12979 Delete TARGETFILE from the target system.
12983 File: gdb.info, Node: Server, Next: Remote Configuration, Prev: File Transfer, Up: Remote Debugging
12985 20.3 Using the `gdbserver' Program
12986 ==================================
12988 `gdbserver' is a control program for Unix-like systems, which allows
12989 you to connect your program with a remote GDB via `target remote'--but
12990 without linking in the usual debugging stub.
12992 `gdbserver' is not a complete replacement for the debugging stubs,
12993 because it requires essentially the same operating-system facilities
12994 that GDB itself does. In fact, a system that can run `gdbserver' to
12995 connect to a remote GDB could also run GDB locally! `gdbserver' is
12996 sometimes useful nevertheless, because it is a much smaller program
12997 than GDB itself. It is also easier to port than all of GDB, so you may
12998 be able to get started more quickly on a new system by using
12999 `gdbserver'. Finally, if you develop code for real-time systems, you
13000 may find that the tradeoffs involved in real-time operation make it
13001 more convenient to do as much development work as possible on another
13002 system, for example by cross-compiling. You can use `gdbserver' to
13003 make a similar choice for debugging.
13005 GDB and `gdbserver' communicate via either a serial line or a TCP
13006 connection, using the standard GDB remote serial protocol.
13008 _Warning:_ `gdbserver' does not have any built-in security. Do
13009 not run `gdbserver' connected to any public network; a GDB
13010 connection to `gdbserver' provides access to the target system
13011 with the same privileges as the user running `gdbserver'.
13013 20.3.1 Running `gdbserver'
13014 --------------------------
13016 Run `gdbserver' on the target system. You need a copy of the program
13017 you want to debug, including any libraries it requires. `gdbserver'
13018 does not need your program's symbol table, so you can strip the program
13019 if necessary to save space. GDB on the host system does all the symbol
13022 To use the server, you must tell it how to communicate with GDB; the
13023 name of your program; and the arguments for your program. The usual
13026 target> gdbserver COMM PROGRAM [ ARGS ... ]
13028 COMM is either a device name (to use a serial line) or a TCP
13029 hostname and portnumber. For example, to debug Emacs with the argument
13030 `foo.txt' and communicate with GDB over the serial port `/dev/com1':
13032 target> gdbserver /dev/com1 emacs foo.txt
13034 `gdbserver' waits passively for the host GDB to communicate with it.
13036 To use a TCP connection instead of a serial line:
13038 target> gdbserver host:2345 emacs foo.txt
13040 The only difference from the previous example is the first argument,
13041 specifying that you are communicating with the host GDB via TCP. The
13042 `host:2345' argument means that `gdbserver' is to expect a TCP
13043 connection from machine `host' to local TCP port 2345. (Currently, the
13044 `host' part is ignored.) You can choose any number you want for the
13045 port number as long as it does not conflict with any TCP ports already
13046 in use on the target system (for example, `23' is reserved for
13047 `telnet').(1) You must use the same port number with the host GDB
13048 `target remote' command.
13050 20.3.1.1 Attaching to a Running Program
13051 .......................................
13053 On some targets, `gdbserver' can also attach to running programs. This
13054 is accomplished via the `--attach' argument. The syntax is:
13056 target> gdbserver --attach COMM PID
13058 PID is the process ID of a currently running process. It isn't
13059 necessary to point `gdbserver' at a binary for the running process.
13061 You can debug processes by name instead of process ID if your target
13062 has the `pidof' utility:
13064 target> gdbserver --attach COMM `pidof PROGRAM`
13066 In case more than one copy of PROGRAM is running, or PROGRAM has
13067 multiple threads, most versions of `pidof' support the `-s' option to
13068 only return the first process ID.
13070 20.3.1.2 Multi-Process Mode for `gdbserver'
13071 ...........................................
13073 When you connect to `gdbserver' using `target remote', `gdbserver'
13074 debugs the specified program only once. When the program exits, or you
13075 detach from it, GDB closes the connection and `gdbserver' exits.
13077 If you connect using `target extended-remote', `gdbserver' enters
13078 multi-process mode. When the debugged program exits, or you detach
13079 from it, GDB stays connected to `gdbserver' even though no program is
13080 running. The `run' and `attach' commands instruct `gdbserver' to run
13081 or attach to a new program. The `run' command uses `set remote
13082 exec-file' (*note set remote exec-file::) to select the program to run.
13083 Command line arguments are supported, except for wildcard expansion and
13084 I/O redirection (*note Arguments::).
13086 To start `gdbserver' without supplying an initial command to run or
13087 process ID to attach, use the `--multi' command line option. Then you
13088 can connect using `target extended-remote' and start the program you
13091 `gdbserver' does not automatically exit in multi-process mode. You
13092 can terminate it by using `monitor exit' (*note Monitor Commands for
13095 20.3.1.3 Other Command-Line Arguments for `gdbserver'
13096 .....................................................
13098 The `--debug' option tells `gdbserver' to display extra status
13099 information about the debugging process. The `--remote-debug' option
13100 tells `gdbserver' to display remote protocol debug output. These
13101 options are intended for `gdbserver' development and for bug reports to
13104 The `--wrapper' option specifies a wrapper to launch programs for
13105 debugging. The option should be followed by the name of the wrapper,
13106 then any command-line arguments to pass to the wrapper, then `--'
13107 indicating the end of the wrapper arguments.
13109 `gdbserver' runs the specified wrapper program with a combined
13110 command line including the wrapper arguments, then the name of the
13111 program to debug, then any arguments to the program. The wrapper runs
13112 until it executes your program, and then GDB gains control.
13114 You can use any program that eventually calls `execve' with its
13115 arguments as a wrapper. Several standard Unix utilities do this, e.g.
13116 `env' and `nohup'. Any Unix shell script ending with `exec "$@"' will
13119 For example, you can use `env' to pass an environment variable to
13120 the debugged program, without setting the variable in `gdbserver''s
13123 $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog
13125 20.3.2 Connecting to `gdbserver'
13126 --------------------------------
13128 Run GDB on the host system.
13130 First make sure you have the necessary symbol files. Load symbols
13131 for your application using the `file' command before you connect. Use
13132 `set sysroot' to locate target libraries (unless your GDB was compiled
13133 with the correct sysroot using `--with-sysroot').
13135 The symbol file and target libraries must exactly match the
13136 executable and libraries on the target, with one exception: the files
13137 on the host system should not be stripped, even if the files on the
13138 target system are. Mismatched or missing files will lead to confusing
13139 results during debugging. On GNU/Linux targets, mismatched or missing
13140 files may also prevent `gdbserver' from debugging multi-threaded
13143 Connect to your target (*note Connecting to a Remote Target:
13144 Connecting.). For TCP connections, you must start up `gdbserver' prior
13145 to using the `target remote' command. Otherwise you may get an error
13146 whose text depends on the host system, but which usually looks
13147 something like `Connection refused'. Don't use the `load' command in
13148 GDB when using `gdbserver', since the program is already on the target.
13150 20.3.3 Monitor Commands for `gdbserver'
13151 ---------------------------------------
13153 During a GDB session using `gdbserver', you can use the `monitor'
13154 command to send special requests to `gdbserver'. Here are the
13155 available commands.
13158 List the available monitor commands.
13160 `monitor set debug 0'
13161 `monitor set debug 1'
13162 Disable or enable general debugging messages.
13164 `monitor set remote-debug 0'
13165 `monitor set remote-debug 1'
13166 Disable or enable specific debugging messages associated with the
13167 remote protocol (*note Remote Protocol::).
13169 `monitor set libthread-db-search-path [PATH]'
13170 When this command is issued, PATH is a colon-separated list of
13171 directories to search for `libthread_db' (*note set
13172 libthread-db-search-path: Threads.). If you omit PATH,
13173 `libthread-db-search-path' will be reset to an empty list.
13176 Tell gdbserver to exit immediately. This command should be
13177 followed by `disconnect' to close the debugging session.
13178 `gdbserver' will detach from any attached processes and kill any
13179 processes it created. Use `monitor exit' to terminate `gdbserver'
13180 at the end of a multi-process mode debug session.
13183 ---------- Footnotes ----------
13185 (1) If you choose a port number that conflicts with another service,
13186 `gdbserver' prints an error message and exits.
13189 File: gdb.info, Node: Remote Configuration, Next: Remote Stub, Prev: Server, Up: Remote Debugging
13191 20.4 Remote Configuration
13192 =========================
13194 This section documents the configuration options available when
13195 debugging remote programs. For the options related to the File I/O
13196 extensions of the remote protocol, see *note system-call-allowed:
13199 `set remoteaddresssize BITS'
13200 Set the maximum size of address in a memory packet to the specified
13201 number of bits. GDB will mask off the address bits above that
13202 number, when it passes addresses to the remote target. The
13203 default value is the number of bits in the target's address.
13205 `show remoteaddresssize'
13206 Show the current value of remote address size in bits.
13209 Set the baud rate for the remote serial I/O to N baud. The value
13210 is used to set the speed of the serial port used for debugging
13214 Show the current speed of the remote connection.
13217 If set to on, GDB sends a `BREAK' signal to the remote when you
13218 type `Ctrl-c' to interrupt the program running on the remote. If
13219 set to off, GDB sends the `Ctrl-C' character instead. The default
13220 is off, since most remote systems expect to see `Ctrl-C' as the
13224 Show whether GDB sends `BREAK' or `Ctrl-C' to interrupt the remote
13227 `set remoteflow on'
13228 `set remoteflow off'
13229 Enable or disable hardware flow control (`RTS'/`CTS') on the
13230 serial port used to communicate to the remote target.
13233 Show the current setting of hardware flow control.
13235 `set remotelogbase BASE'
13236 Set the base (a.k.a. radix) of logging serial protocol
13237 communications to BASE. Supported values of BASE are: `ascii',
13238 `octal', and `hex'. The default is `ascii'.
13240 `show remotelogbase'
13241 Show the current setting of the radix for logging remote serial
13244 `set remotelogfile FILE'
13245 Record remote serial communications on the named FILE. The
13246 default is not to record at all.
13248 `show remotelogfile.'
13249 Show the current setting of the file name on which to record the
13250 serial communications.
13252 `set remotetimeout NUM'
13253 Set the timeout limit to wait for the remote target to respond to
13254 NUM seconds. The default is 2 seconds.
13256 `show remotetimeout'
13257 Show the current number of seconds to wait for the remote target
13260 `set remote hardware-watchpoint-limit LIMIT'
13261 `set remote hardware-breakpoint-limit LIMIT'
13262 Restrict GDB to using LIMIT remote hardware breakpoint or
13263 watchpoints. A limit of -1, the default, is treated as unlimited.
13265 `set remote exec-file FILENAME'
13266 `show remote exec-file'
13267 Select the file used for `run' with `target extended-remote'.
13268 This should be set to a filename valid on the target system. If
13269 it is not set, the target will use a default filename (e.g. the
13272 `set remote interrupt-sequence'
13273 Allow the user to select one of `Ctrl-C', a `BREAK' or `BREAK-g'
13274 as the sequence to the remote target in order to interrupt the
13275 execution. `Ctrl-C' is a default. Some system prefers `BREAK'
13276 which is high level of serial line for some certain time. Linux
13277 kernel prefers `BREAK-g', a.k.a Magic SysRq g. It is `BREAK'
13278 signal followed by character `g'.
13280 `show interrupt-sequence'
13281 Show which of `Ctrl-C', `BREAK' or `BREAK-g' is sent by GDB to
13282 interrupt the remote program. `BREAK-g' is BREAK signal followed
13283 by `g' and also known as Magic SysRq g.
13285 `set remote interrupt-on-connect'
13286 Specify whether interrupt-sequence is sent to remote target when
13287 GDB connects to it. This is mostly needed when you debug Linux
13288 kernel. Linux kernel expects `BREAK' followed by `g' which is
13289 known as Magic SysRq g in order to connect GDB.
13291 `show interrupt-on-connect'
13292 Show whether interrupt-sequence is sent to remote target when GDB
13295 `set tcp auto-retry on'
13296 Enable auto-retry for remote TCP connections. This is useful if
13297 the remote debugging agent is launched in parallel with GDB; there
13298 is a race condition because the agent may not become ready to
13299 accept the connection before GDB attempts to connect. When
13300 auto-retry is enabled, if the initial attempt to connect fails,
13301 GDB reattempts to establish the connection using the timeout
13302 specified by `set tcp connect-timeout'.
13304 `set tcp auto-retry off'
13305 Do not auto-retry failed TCP connections.
13307 `show tcp auto-retry'
13308 Show the current auto-retry setting.
13310 `set tcp connect-timeout SECONDS'
13311 Set the timeout for establishing a TCP connection to the remote
13312 target to SECONDS. The timeout affects both polling to retry
13313 failed connections (enabled by `set tcp auto-retry on') and
13314 waiting for connections that are merely slow to complete, and
13315 represents an approximate cumulative value.
13317 `show tcp connect-timeout'
13318 Show the current connection timeout setting.
13320 The GDB remote protocol autodetects the packets supported by your
13321 debugging stub. If you need to override the autodetection, you can use
13322 these commands to enable or disable individual packets. Each packet
13323 can be set to `on' (the remote target supports this packet), `off' (the
13324 remote target does not support this packet), or `auto' (detect remote
13325 target support for this packet). They all default to `auto'. For more
13326 information about each packet, see *note Remote Protocol::.
13328 During normal use, you should not have to use any of these commands.
13329 If you do, that may be a bug in your remote debugging stub, or a bug in
13330 GDB. You may want to report the problem to the GDB developers.
13332 For each packet NAME, the command to enable or disable the packet is
13333 `set remote NAME-packet'. The available settings are:
13335 Command Name Remote Packet Related Features
13336 `fetch-register' `p' `info registers'
13337 `set-register' `P' `set'
13338 `binary-download' `X' `load', `set'
13339 `read-aux-vector' `qXfer:auxv:read' `info auxv'
13340 `symbol-lookup' `qSymbol' Detecting
13342 `attach' `vAttach' `attach'
13343 `verbose-resume' `vCont' Stepping or
13347 `software-breakpoint'`Z0' `break'
13348 `hardware-breakpoint'`Z1' `hbreak'
13349 `write-watchpoint' `Z2' `watch'
13350 `read-watchpoint' `Z3' `rwatch'
13351 `access-watchpoint' `Z4' `awatch'
13352 `target-features' `qXfer:features:read' `set architecture'
13353 `library-info' `qXfer:libraries:read' `info
13355 `memory-map' `qXfer:memory-map:read' `info mem'
13356 `read-spu-object' `qXfer:spu:read' `info spu'
13357 `write-spu-object' `qXfer:spu:write' `info spu'
13358 `read-siginfo-object'`qXfer:siginfo:read' `print $_siginfo'
13359 `write-siginfo-object'`qXfer:siginfo:write' `set $_siginfo'
13360 `threads' `qXfer:threads:read' `info threads'
13361 `get-thread-local- `qGetTLSAddr' Displaying
13362 storage-address' `__thread'
13364 `search-memory' `qSearch:memory' `find'
13365 `supported-packets' `qSupported' Remote
13368 `pass-signals' `QPassSignals' `handle SIGNAL'
13369 `hostio-close-packet'`vFile:close' `remote get',
13371 `hostio-open-packet' `vFile:open' `remote get',
13373 `hostio-pread-packet'`vFile:pread' `remote get',
13375 `hostio-pwrite-packet'`vFile:pwrite' `remote get',
13377 `hostio-unlink-packet'`vFile:unlink' `remote delete'
13378 `noack-packet' `QStartNoAckMode' Packet
13380 `osdata' `qXfer:osdata:read' `info os'
13381 `query-attached' `qAttached' Querying remote
13386 File: gdb.info, Node: Remote Stub, Prev: Remote Configuration, Up: Remote Debugging
13388 20.5 Implementing a Remote Stub
13389 ===============================
13391 The stub files provided with GDB implement the target side of the
13392 communication protocol, and the GDB side is implemented in the GDB
13393 source file `remote.c'. Normally, you can simply allow these
13394 subroutines to communicate, and ignore the details. (If you're
13395 implementing your own stub file, you can still ignore the details: start
13396 with one of the existing stub files. `sparc-stub.c' is the best
13397 organized, and therefore the easiest to read.)
13399 To debug a program running on another machine (the debugging
13400 "target" machine), you must first arrange for all the usual
13401 prerequisites for the program to run by itself. For example, for a C
13404 1. A startup routine to set up the C runtime environment; these
13405 usually have a name like `crt0'. The startup routine may be
13406 supplied by your hardware supplier, or you may have to write your
13409 2. A C subroutine library to support your program's subroutine calls,
13410 notably managing input and output.
13412 3. A way of getting your program to the other machine--for example, a
13413 download program. These are often supplied by the hardware
13414 manufacturer, but you may have to write your own from hardware
13417 The next step is to arrange for your program to use a serial port to
13418 communicate with the machine where GDB is running (the "host" machine).
13419 In general terms, the scheme looks like this:
13422 GDB already understands how to use this protocol; when everything
13423 else is set up, you can simply use the `target remote' command
13424 (*note Specifying a Debugging Target: Targets.).
13427 you must link with your program a few special-purpose subroutines
13428 that implement the GDB remote serial protocol. The file
13429 containing these subroutines is called a "debugging stub".
13431 On certain remote targets, you can use an auxiliary program
13432 `gdbserver' instead of linking a stub into your program. *Note
13433 Using the `gdbserver' Program: Server, for details.
13435 The debugging stub is specific to the architecture of the remote
13436 machine; for example, use `sparc-stub.c' to debug programs on SPARC
13439 These working remote stubs are distributed with GDB:
13442 For Intel 386 and compatible architectures.
13445 For Motorola 680x0 architectures.
13448 For Renesas SH architectures.
13451 For SPARC architectures.
13454 For Fujitsu SPARCLITE architectures.
13457 The `README' file in the GDB distribution may list other recently
13462 * Stub Contents:: What the stub can do for you
13463 * Bootstrapping:: What you must do for the stub
13464 * Debug Session:: Putting it all together
13467 File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Stub
13469 20.5.1 What the Stub Can Do for You
13470 -----------------------------------
13472 The debugging stub for your architecture supplies these three
13476 This routine arranges for `handle_exception' to run when your
13477 program stops. You must call this subroutine explicitly near the
13478 beginning of your program.
13481 This is the central workhorse, but your program never calls it
13482 explicitly--the setup code arranges for `handle_exception' to run
13483 when a trap is triggered.
13485 `handle_exception' takes control when your program stops during
13486 execution (for example, on a breakpoint), and mediates
13487 communications with GDB on the host machine. This is where the
13488 communications protocol is implemented; `handle_exception' acts as
13489 the GDB representative on the target machine. It begins by
13490 sending summary information on the state of your program, then
13491 continues to execute, retrieving and transmitting any information
13492 GDB needs, until you execute a GDB command that makes your program
13493 resume; at that point, `handle_exception' returns control to your
13494 own code on the target machine.
13497 Use this auxiliary subroutine to make your program contain a
13498 breakpoint. Depending on the particular situation, this may be
13499 the only way for GDB to get control. For instance, if your target
13500 machine has some sort of interrupt button, you won't need to call
13501 this; pressing the interrupt button transfers control to
13502 `handle_exception'--in effect, to GDB. On some machines, simply
13503 receiving characters on the serial port may also trigger a trap;
13504 again, in that situation, you don't need to call `breakpoint' from
13505 your own program--simply running `target remote' from the host GDB
13506 session gets control.
13508 Call `breakpoint' if none of these is true, or if you simply want
13509 to make certain your program stops at a predetermined point for the
13510 start of your debugging session.
13513 File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: Remote Stub
13515 20.5.2 What You Must Do for the Stub
13516 ------------------------------------
13518 The debugging stubs that come with GDB are set up for a particular chip
13519 architecture, but they have no information about the rest of your
13520 debugging target machine.
13522 First of all you need to tell the stub how to communicate with the
13525 `int getDebugChar()'
13526 Write this subroutine to read a single character from the serial
13527 port. It may be identical to `getchar' for your target system; a
13528 different name is used to allow you to distinguish the two if you
13531 `void putDebugChar(int)'
13532 Write this subroutine to write a single character to the serial
13533 port. It may be identical to `putchar' for your target system; a
13534 different name is used to allow you to distinguish the two if you
13537 If you want GDB to be able to stop your program while it is running,
13538 you need to use an interrupt-driven serial driver, and arrange for it
13539 to stop when it receives a `^C' (`\003', the control-C character).
13540 That is the character which GDB uses to tell the remote system to stop.
13542 Getting the debugging target to return the proper status to GDB
13543 probably requires changes to the standard stub; one quick and dirty way
13544 is to just execute a breakpoint instruction (the "dirty" part is that
13545 GDB reports a `SIGTRAP' instead of a `SIGINT').
13547 Other routines you need to supply are:
13549 `void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)'
13550 Write this function to install EXCEPTION_ADDRESS in the exception
13551 handling tables. You need to do this because the stub does not
13552 have any way of knowing what the exception handling tables on your
13553 target system are like (for example, the processor's table might
13554 be in ROM, containing entries which point to a table in RAM).
13555 EXCEPTION_NUMBER is the exception number which should be changed;
13556 its meaning is architecture-dependent (for example, different
13557 numbers might represent divide by zero, misaligned access, etc).
13558 When this exception occurs, control should be transferred directly
13559 to EXCEPTION_ADDRESS, and the processor state (stack, registers,
13560 and so on) should be just as it is when a processor exception
13561 occurs. So if you want to use a jump instruction to reach
13562 EXCEPTION_ADDRESS, it should be a simple jump, not a jump to
13565 For the 386, EXCEPTION_ADDRESS should be installed as an interrupt
13566 gate so that interrupts are masked while the handler runs. The
13567 gate should be at privilege level 0 (the most privileged level).
13568 The SPARC and 68k stubs are able to mask interrupts themselves
13569 without help from `exceptionHandler'.
13571 `void flush_i_cache()'
13572 On SPARC and SPARCLITE only, write this subroutine to flush the
13573 instruction cache, if any, on your target machine. If there is no
13574 instruction cache, this subroutine may be a no-op.
13576 On target machines that have instruction caches, GDB requires this
13577 function to make certain that the state of your program is stable.
13579 You must also make sure this library routine is available:
13581 `void *memset(void *, int, int)'
13582 This is the standard library function `memset' that sets an area of
13583 memory to a known value. If you have one of the free versions of
13584 `libc.a', `memset' can be found there; otherwise, you must either
13585 obtain it from your hardware manufacturer, or write your own.
13587 If you do not use the GNU C compiler, you may need other standard
13588 library subroutines as well; this varies from one stub to another, but
13589 in general the stubs are likely to use any of the common library
13590 subroutines which `GCC' generates as inline code.
13593 File: gdb.info, Node: Debug Session, Prev: Bootstrapping, Up: Remote Stub
13595 20.5.3 Putting it All Together
13596 ------------------------------
13598 In summary, when your program is ready to debug, you must follow these
13601 1. Make sure you have defined the supporting low-level routines
13602 (*note What You Must Do for the Stub: Bootstrapping.):
13603 `getDebugChar', `putDebugChar',
13604 `flush_i_cache', `memset', `exceptionHandler'.
13606 2. Insert these lines near the top of your program:
13611 3. For the 680x0 stub only, you need to provide a variable called
13612 `exceptionHook'. Normally you just use:
13614 void (*exceptionHook)() = 0;
13616 but if before calling `set_debug_traps', you set it to point to a
13617 function in your program, that function is called when `GDB'
13618 continues after stopping on a trap (for example, bus error). The
13619 function indicated by `exceptionHook' is called with one
13620 parameter: an `int' which is the exception number.
13622 4. Compile and link together: your program, the GDB debugging stub for
13623 your target architecture, and the supporting subroutines.
13625 5. Make sure you have a serial connection between your target machine
13626 and the GDB host, and identify the serial port on the host.
13628 6. Download your program to your target machine (or get it there by
13629 whatever means the manufacturer provides), and start it.
13631 7. Start GDB on the host, and connect to the target (*note Connecting
13632 to a Remote Target: Connecting.).
13636 File: gdb.info, Node: Configurations, Next: Controlling GDB, Prev: Remote Debugging, Up: Top
13638 21 Configuration-Specific Information
13639 *************************************
13641 While nearly all GDB commands are available for all native and cross
13642 versions of the debugger, there are some exceptions. This chapter
13643 describes things that are only available in certain configurations.
13645 There are three major categories of configurations: native
13646 configurations, where the host and target are the same, embedded
13647 operating system configurations, which are usually the same for several
13648 different processor architectures, and bare embedded processors, which
13649 are quite different from each other.
13655 * Embedded Processors::
13659 File: gdb.info, Node: Native, Next: Embedded OS, Up: Configurations
13664 This section describes details specific to particular native
13670 * BSD libkvm Interface:: Debugging BSD kernel memory images
13671 * SVR4 Process Information:: SVR4 process information
13672 * DJGPP Native:: Features specific to the DJGPP port
13673 * Cygwin Native:: Features specific to the Cygwin port
13674 * Hurd Native:: Features specific to GNU Hurd
13675 * Neutrino:: Features specific to QNX Neutrino
13676 * Darwin:: Features specific to Darwin
13679 File: gdb.info, Node: HP-UX, Next: BSD libkvm Interface, Up: Native
13684 On HP-UX systems, if you refer to a function or variable name that
13685 begins with a dollar sign, GDB searches for a user or system name
13686 first, before it searches for a convenience variable.
13689 File: gdb.info, Node: BSD libkvm Interface, Next: SVR4 Process Information, Prev: HP-UX, Up: Native
13691 21.1.2 BSD libkvm Interface
13692 ---------------------------
13694 BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory
13695 interface that provides a uniform interface for accessing kernel virtual
13696 memory images, including live systems and crash dumps. GDB uses this
13697 interface to allow you to debug live kernels and kernel crash dumps on
13698 many native BSD configurations. This is implemented as a special `kvm'
13699 debugging target. For debugging a live system, load the currently
13700 running kernel into GDB and connect to the `kvm' target:
13704 For debugging crash dumps, provide the file name of the crash dump
13707 (gdb) target kvm /var/crash/bsd.0
13709 Once connected to the `kvm' target, the following commands are
13713 Set current context from the "Process Control Block" (PCB) address.
13716 Set current context from proc address. This command isn't
13717 available on modern FreeBSD systems.
13720 File: gdb.info, Node: SVR4 Process Information, Next: DJGPP Native, Prev: BSD libkvm Interface, Up: Native
13722 21.1.3 SVR4 Process Information
13723 -------------------------------
13725 Many versions of SVR4 and compatible systems provide a facility called
13726 `/proc' that can be used to examine the image of a running process
13727 using file-system subroutines. If GDB is configured for an operating
13728 system with this facility, the command `info proc' is available to
13729 report information about the process running your program, or about any
13730 process running on your system. `info proc' works only on SVR4 systems
13731 that include the `procfs' code. This includes, as of this writing,
13732 GNU/Linux, OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not
13733 HP-UX, for example.
13736 `info proc PROCESS-ID'
13737 Summarize available information about any running process. If a
13738 process ID is specified by PROCESS-ID, display information about
13739 that process; otherwise display information about the program being
13740 debugged. The summary includes the debugged process ID, the
13741 command line used to invoke it, its current working directory, and
13742 its executable file's absolute file name.
13744 On some systems, PROCESS-ID can be of the form `[PID]/TID' which
13745 specifies a certain thread ID within a process. If the optional
13746 PID part is missing, it means a thread from the process being
13747 debugged (the leading `/' still needs to be present, or else GDB
13748 will interpret the number as a process ID rather than a thread ID).
13750 `info proc mappings'
13751 Report the memory address space ranges accessible in the program,
13752 with information on whether the process has read, write, or
13753 execute access rights to each range. On GNU/Linux systems, each
13754 memory range includes the object file which is mapped to that
13755 range, instead of the memory access rights to that range.
13759 These subcommands are specific to GNU/Linux systems. They show
13760 the process-related information, including the user ID and group
13761 ID; how many threads are there in the process; its virtual memory
13762 usage; the signals that are pending, blocked, and ignored; its
13763 TTY; its consumption of system and user time; its stack size; its
13764 `nice' value; etc. For more information, see the `proc' man page
13765 (type `man 5 proc' from your shell prompt).
13768 Show all the information about the process described under all of
13769 the above `info proc' subcommands.
13772 This command enables and disables tracing of `procfs' API calls.
13774 `show procfs-trace'
13775 Show the current state of `procfs' API call tracing.
13777 `set procfs-file FILE'
13778 Tell GDB to write `procfs' API trace to the named FILE. GDB
13779 appends the trace info to the previous contents of the file. The
13780 default is to display the trace on the standard output.
13783 Show the file to which `procfs' API trace is written.
13787 `proc-untrace-entry'
13788 `proc-untrace-exit'
13789 These commands enable and disable tracing of entries into and exits
13790 from the `syscall' interface.
13793 For QNX Neutrino only, this command displays the list of all the
13794 processes and all the threads within each process.
13797 For QNX Neutrino only, this command displays the list of all
13801 File: gdb.info, Node: DJGPP Native, Next: Cygwin Native, Prev: SVR4 Process Information, Up: Native
13803 21.1.4 Features for Debugging DJGPP Programs
13804 --------------------------------------------
13806 DJGPP is a port of the GNU development tools to MS-DOS and MS-Windows.
13807 DJGPP programs are 32-bit protected-mode programs that use the "DPMI"
13808 (DOS Protected-Mode Interface) API to run on top of real-mode DOS
13809 systems and their emulations.
13811 GDB supports native debugging of DJGPP programs, and defines a few
13812 commands specific to the DJGPP port. This subsection describes those
13816 This is a prefix of DJGPP-specific commands which print
13817 information about the target system and important OS structures.
13820 This command displays assorted information about the underlying
13821 platform: the CPU type and features, the OS version and flavor, the
13822 DPMI version, and the available conventional and DPMI memory.
13827 These 3 commands display entries from, respectively, Global, Local,
13828 and Interrupt Descriptor Tables (GDT, LDT, and IDT). The
13829 descriptor tables are data structures which store a descriptor for
13830 each segment that is currently in use. The segment's selector is
13831 an index into a descriptor table; the table entry for that index
13832 holds the descriptor's base address and limit, and its attributes
13835 A typical DJGPP program uses 3 segments: a code segment, a data
13836 segment (used for both data and the stack), and a DOS segment
13837 (which allows access to DOS/BIOS data structures and absolute
13838 addresses in conventional memory). However, the DPMI host will
13839 usually define additional segments in order to support the DPMI
13842 These commands allow to display entries from the descriptor tables.
13843 Without an argument, all entries from the specified table are
13844 displayed. An argument, which should be an integer expression,
13845 means display a single entry whose index is given by the argument.
13846 For example, here's a convenient way to display information about
13847 the debugged program's data segment:
13849 `(gdb) info dos ldt $ds'
13850 `0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)'
13853 This comes in handy when you want to see whether a pointer is
13854 outside the data segment's limit (i.e. "garbled").
13858 These two commands display entries from, respectively, the Page
13859 Directory and the Page Tables. Page Directories and Page Tables
13860 are data structures which control how virtual memory addresses are
13861 mapped into physical addresses. A Page Table includes an entry
13862 for every page of memory that is mapped into the program's address
13863 space; there may be several Page Tables, each one holding up to
13864 4096 entries. A Page Directory has up to 4096 entries, one each
13865 for every Page Table that is currently in use.
13867 Without an argument, `info dos pde' displays the entire Page
13868 Directory, and `info dos pte' displays all the entries in all of
13869 the Page Tables. An argument, an integer expression, given to the
13870 `info dos pde' command means display only that entry from the Page
13871 Directory table. An argument given to the `info dos pte' command
13872 means display entries from a single Page Table, the one pointed to
13873 by the specified entry in the Page Directory.
13875 These commands are useful when your program uses "DMA" (Direct
13876 Memory Access), which needs physical addresses to program the DMA
13879 These commands are supported only with some DPMI servers.
13881 `info dos address-pte ADDR'
13882 This command displays the Page Table entry for a specified linear
13883 address. The argument ADDR is a linear address which should
13884 already have the appropriate segment's base address added to it,
13885 because this command accepts addresses which may belong to _any_
13886 segment. For example, here's how to display the Page Table entry
13887 for the page where a variable `i' is stored:
13889 `(gdb) info dos address-pte __djgpp_base_address + (char *)&i'
13890 `Page Table entry for address 0x11a00d30:'
13891 `Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30'
13894 This says that `i' is stored at offset `0xd30' from the page whose
13895 physical base address is `0x02698000', and shows all the
13896 attributes of that page.
13898 Note that you must cast the addresses of variables to a `char *',
13899 since otherwise the value of `__djgpp_base_address', the base
13900 address of all variables and functions in a DJGPP program, will be
13901 added using the rules of C pointer arithmetics: if `i' is declared
13902 an `int', GDB will add 4 times the value of `__djgpp_base_address'
13903 to the address of `i'.
13905 Here's another example, it displays the Page Table entry for the
13908 `(gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3)'
13909 `Page Table entry for address 0x29110:'
13910 `Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110'
13913 (The `+ 3' offset is because the transfer buffer's address is the
13914 3rd member of the `_go32_info_block' structure.) The output
13915 clearly shows that this DPMI server maps the addresses in
13916 conventional memory 1:1, i.e. the physical (`0x00029000' +
13917 `0x110') and linear (`0x29110') addresses are identical.
13919 This command is supported only with some DPMI servers.
13921 In addition to native debugging, the DJGPP port supports remote
13922 debugging via a serial data link. The following commands are specific
13923 to remote serial debugging in the DJGPP port of GDB.
13925 `set com1base ADDR'
13926 This command sets the base I/O port address of the `COM1' serial
13930 This command sets the "Interrupt Request" (`IRQ') line to use for
13931 the `COM1' serial port.
13933 There are similar commands `set com2base', `set com3irq', etc. for
13934 setting the port address and the `IRQ' lines for the other 3 COM
13937 The related commands `show com1base', `show com1irq' etc. display
13938 the current settings of the base address and the `IRQ' lines used
13942 This command prints the status of the 4 DOS serial ports. For each
13943 port, it prints whether it's active or not, its I/O base address
13944 and IRQ number, whether it uses a 16550-style FIFO, its baudrate,
13945 and the counts of various errors encountered so far.
13948 File: gdb.info, Node: Cygwin Native, Next: Hurd Native, Prev: DJGPP Native, Up: Native
13950 21.1.5 Features for Debugging MS Windows PE Executables
13951 -------------------------------------------------------
13953 GDB supports native debugging of MS Windows programs, including DLLs
13954 with and without symbolic debugging information.
13956 MS-Windows programs that call `SetConsoleMode' to switch off the
13957 special meaning of the `Ctrl-C' keystroke cannot be interrupted by
13958 typing `C-c'. For this reason, GDB on MS-Windows supports `C-<BREAK>'
13959 as an alternative interrupt key sequence, which can be used to
13960 interrupt the debuggee even if it ignores `C-c'.
13962 There are various additional Cygwin-specific commands, described in
13963 this section. Working with DLLs that have no debugging symbols is
13964 described in *note Non-debug DLL Symbols::.
13967 This is a prefix of MS Windows-specific commands which print
13968 information about the target system and important OS structures.
13970 `info w32 selector'
13971 This command displays information returned by the Win32 API
13972 `GetThreadSelectorEntry' function. It takes an optional argument
13973 that is evaluated to a long value to give the information about
13974 this given selector. Without argument, this command displays
13975 information about the six segment registers.
13978 This is a Cygwin-specific alias of `info shared'.
13981 This command loads symbols from a dll similarly to add-sym command
13982 but without the need to specify a base address.
13984 `set cygwin-exceptions MODE'
13985 If MODE is `on', GDB will break on exceptions that happen inside
13986 the Cygwin DLL. If MODE is `off', GDB will delay recognition of
13987 exceptions, and may ignore some exceptions which seem to be caused
13988 by internal Cygwin DLL "bookkeeping". This option is meant
13989 primarily for debugging the Cygwin DLL itself; the default value
13990 is `off' to avoid annoying GDB users with false `SIGSEGV' signals.
13992 `show cygwin-exceptions'
13993 Displays whether GDB will break on exceptions that happen inside
13994 the Cygwin DLL itself.
13996 `set new-console MODE'
13997 If MODE is `on' the debuggee will be started in a new console on
13998 next start. If MODE is `off'i, the debuggee will be started in
13999 the same console as the debugger.
14002 Displays whether a new console is used when the debuggee is
14005 `set new-group MODE'
14006 This boolean value controls whether the debuggee should start a
14007 new group or stay in the same group as the debugger. This affects
14008 the way the Windows OS handles `Ctrl-C'.
14011 Displays current value of new-group boolean.
14014 This boolean value adds debug output concerning kernel events
14015 related to the debuggee seen by the debugger. This includes
14016 events that signal thread and process creation and exit, DLL
14017 loading and unloading, console interrupts, and debugging messages
14018 produced by the Windows `OutputDebugString' API call.
14021 This boolean value adds debug output concerning execute events
14022 (such as resume thread) seen by the debugger.
14024 `set debugexceptions'
14025 This boolean value adds debug output concerning exceptions in the
14026 debuggee seen by the debugger.
14029 This boolean value adds debug output concerning debuggee memory
14030 reads and writes by the debugger.
14033 This boolean values specifies whether the debuggee is called via a
14034 shell or directly (default value is on).
14037 Displays if the debuggee will be started with a shell.
14042 * Non-debug DLL Symbols:: Support for DLLs without debugging symbols
14045 File: gdb.info, Node: Non-debug DLL Symbols, Up: Cygwin Native
14047 21.1.5.1 Support for DLLs without Debugging Symbols
14048 ...................................................
14050 Very often on windows, some of the DLLs that your program relies on do
14051 not include symbolic debugging information (for example,
14052 `kernel32.dll'). When GDB doesn't recognize any debugging symbols in a
14053 DLL, it relies on the minimal amount of symbolic information contained
14054 in the DLL's export table. This section describes working with such
14055 symbols, known internally to GDB as "minimal symbols".
14057 Note that before the debugged program has started execution, no DLLs
14058 will have been loaded. The easiest way around this problem is simply to
14059 start the program -- either by setting a breakpoint or letting the
14060 program run once to completion. It is also possible to force GDB to
14061 load a particular DLL before starting the executable -- see the shared
14062 library information in *note Files::, or the `dll-symbols' command in
14063 *note Cygwin Native::. Currently, explicitly loading symbols from a
14064 DLL with no debugging information will cause the symbol names to be
14065 duplicated in GDB's lookup table, which may adversely affect symbol
14066 lookup performance.
14068 21.1.5.2 DLL Name Prefixes
14069 ..........................
14071 In keeping with the naming conventions used by the Microsoft debugging
14072 tools, DLL export symbols are made available with a prefix based on the
14073 DLL name, for instance `KERNEL32!CreateFileA'. The plain name is also
14074 entered into the symbol table, so `CreateFileA' is often sufficient.
14075 In some cases there will be name clashes within a program (particularly
14076 if the executable itself includes full debugging symbols) necessitating
14077 the use of the fully qualified name when referring to the contents of
14078 the DLL. Use single-quotes around the name to avoid the exclamation
14079 mark ("!") being interpreted as a language operator.
14081 Note that the internal name of the DLL may be all upper-case, even
14082 though the file name of the DLL is lower-case, or vice-versa. Since
14083 symbols within GDB are _case-sensitive_ this may cause some confusion.
14084 If in doubt, try the `info functions' and `info variables' commands or
14085 even `maint print msymbols' (*note Symbols::). Here's an example:
14087 (gdb) info function CreateFileA
14088 All functions matching regular expression "CreateFileA":
14090 Non-debugging symbols:
14091 0x77e885f4 CreateFileA
14092 0x77e885f4 KERNEL32!CreateFileA
14094 (gdb) info function !
14095 All functions matching regular expression "!":
14097 Non-debugging symbols:
14098 0x6100114c cygwin1!__assert
14099 0x61004034 cygwin1!_dll_crt0@0
14100 0x61004240 cygwin1!dll_crt0(per_process *)
14103 21.1.5.3 Working with Minimal Symbols
14104 .....................................
14106 Symbols extracted from a DLL's export table do not contain very much
14107 type information. All that GDB can do is guess whether a symbol refers
14108 to a function or variable depending on the linker section that contains
14109 the symbol. Also note that the actual contents of the memory contained
14110 in a DLL are not available unless the program is running. This means
14111 that you cannot examine the contents of a variable or disassemble a
14112 function within a DLL without a running program.
14114 Variables are generally treated as pointers and dereferenced
14115 automatically. For this reason, it is often necessary to prefix a
14116 variable name with the address-of operator ("&") and provide explicit
14117 type information in the command. Here's an example of the type of
14120 (gdb) print 'cygwin1!__argv'
14123 (gdb) x 'cygwin1!__argv'
14124 0x10021610: "\230y\""
14126 And two possible solutions:
14128 (gdb) print ((char **)'cygwin1!__argv')[0]
14129 $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram"
14131 (gdb) x/2x &'cygwin1!__argv'
14132 0x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000
14133 (gdb) x/x 0x10021608
14134 0x10021608: 0x0022fd98
14135 (gdb) x/s 0x0022fd98
14136 0x22fd98: "/cygdrive/c/mydirectory/myprogram"
14138 Setting a break point within a DLL is possible even before the
14139 program starts execution. However, under these circumstances, GDB can't
14140 examine the initial instructions of the function in order to skip the
14141 function's frame set-up code. You can work around this by using "*&" to
14142 set the breakpoint at a raw memory address:
14144 (gdb) break *&'python22!PyOS_Readline'
14145 Breakpoint 1 at 0x1e04eff0
14147 The author of these extensions is not entirely convinced that
14148 setting a break point within a shared DLL like `kernel32.dll' is
14152 File: gdb.info, Node: Hurd Native, Next: Neutrino, Prev: Cygwin Native, Up: Native
14154 21.1.6 Commands Specific to GNU Hurd Systems
14155 --------------------------------------------
14157 This subsection describes GDB commands specific to the GNU Hurd native
14162 This command toggles the state of inferior signal interception by
14163 GDB. Mach exceptions, such as breakpoint traps, are not affected
14164 by this command. `sigs' is a shorthand alias for `signals'.
14168 Show the current state of intercepting inferior's signals.
14170 `set signal-thread'
14172 This command tells GDB which thread is the `libc' signal thread.
14173 That thread is run when a signal is delivered to a running
14174 process. `set sigthread' is the shorthand alias of `set
14177 `show signal-thread'
14179 These two commands show which thread will run when the inferior is
14180 delivered a signal.
14183 This commands tells GDB that the inferior process is stopped, as
14184 with the `SIGSTOP' signal. The stopped process can be continued
14185 by delivering a signal to it.
14188 This command shows whether GDB thinks the debuggee is stopped.
14191 Use this command to turn off trapping of exceptions in the
14192 inferior. When exception trapping is off, neither breakpoints nor
14193 single-stepping will work. To restore the default, set exception
14197 Show the current state of trapping exceptions in the inferior.
14200 This command toggles task suspension when GDB has control.
14201 Setting it to on takes effect immediately, and the task is
14202 suspended whenever GDB gets control. Setting it to off will take
14203 effect the next time the inferior is continued. If this option is
14204 set to off, you can use `set thread default pause on' or `set
14205 thread pause on' (see below) to pause individual threads.
14208 Show the current state of task suspension.
14210 `set task detach-suspend-count'
14211 This command sets the suspend count the task will be left with when
14212 GDB detaches from it.
14214 `show task detach-suspend-count'
14215 Show the suspend count the task will be left with when detaching.
14217 `set task exception-port'
14219 This command sets the task exception port to which GDB will
14220 forward exceptions. The argument should be the value of the "send
14221 rights" of the task. `set task excp' is a shorthand alias.
14224 This command switches GDB to a mode that is the least invasive as
14225 far as interfering with the inferior is concerned. This is the
14226 same as using `set task pause', `set exceptions', and `set
14227 signals' to values opposite to the defaults.
14230 `info receive-rights'
14236 These commands display information about, respectively, send
14237 rights, receive rights, port rights, port sets, and dead names of
14238 a task. There are also shorthand aliases: `info ports' for `info
14239 port-rights' and `info psets' for `info port-sets'.
14242 This command toggles current thread suspension when GDB has
14243 control. Setting it to on takes effect immediately, and the
14244 current thread is suspended whenever GDB gets control. Setting it
14245 to off will take effect the next time the inferior is continued.
14246 Normally, this command has no effect, since when GDB has control,
14247 the whole task is suspended. However, if you used `set task pause
14248 off' (see above), this command comes in handy to suspend only the
14251 `show thread pause'
14252 This command shows the state of current thread suspension.
14255 This command sets whether the current thread is allowed to run.
14258 Show whether the current thread is allowed to run.
14260 `set thread detach-suspend-count'
14261 This command sets the suspend count GDB will leave on a thread
14262 when detaching. This number is relative to the suspend count
14263 found by GDB when it notices the thread; use `set thread
14264 takeover-suspend-count' to force it to an absolute value.
14266 `show thread detach-suspend-count'
14267 Show the suspend count GDB will leave on the thread when detaching.
14269 `set thread exception-port'
14271 Set the thread exception port to which to forward exceptions. This
14272 overrides the port set by `set task exception-port' (see above).
14273 `set thread excp' is the shorthand alias.
14275 `set thread takeover-suspend-count'
14276 Normally, GDB's thread suspend counts are relative to the value
14277 GDB finds when it notices each thread. This command changes the
14278 suspend counts to be absolute instead.
14280 `set thread default'
14281 `show thread default'
14282 Each of the above `set thread' commands has a `set thread default'
14283 counterpart (e.g., `set thread default pause', `set thread default
14284 exception-port', etc.). The `thread default' variety of commands
14285 sets the default thread properties for all threads; you can then
14286 change the properties of individual threads with the non-default
14290 File: gdb.info, Node: Neutrino, Next: Darwin, Prev: Hurd Native, Up: Native
14292 21.1.7 QNX Neutrino
14293 -------------------
14295 GDB provides the following commands specific to the QNX Neutrino target:
14297 `set debug nto-debug'
14298 When set to on, enables debugging messages specific to the QNX
14301 `show debug nto-debug'
14302 Show the current state of QNX Neutrino messages.
14305 File: gdb.info, Node: Darwin, Prev: Neutrino, Up: Native
14310 GDB provides the following commands specific to the Darwin target:
14312 `set debug darwin NUM'
14313 When set to a non zero value, enables debugging messages specific
14314 to the Darwin support. Higher values produce more verbose output.
14316 `show debug darwin'
14317 Show the current state of Darwin messages.
14319 `set debug mach-o NUM'
14320 When set to a non zero value, enables debugging messages while GDB
14321 is reading Darwin object files. ("Mach-O" is the file format used
14322 on Darwin for object and executable files.) Higher values produce
14323 more verbose output. This is a command to diagnose problems
14324 internal to GDB and should not be needed in normal usage.
14326 `show debug mach-o'
14327 Show the current state of Mach-O file messages.
14329 `set mach-exceptions on'
14330 `set mach-exceptions off'
14331 On Darwin, faults are first reported as a Mach exception and are
14332 then mapped to a Posix signal. Use this command to turn on
14333 trapping of Mach exceptions in the inferior. This might be
14334 sometimes useful to better understand the cause of a fault. The
14337 `show mach-exceptions'
14338 Show the current state of exceptions trapping.
14341 File: gdb.info, Node: Embedded OS, Next: Embedded Processors, Prev: Native, Up: Configurations
14343 21.2 Embedded Operating Systems
14344 ===============================
14346 This section describes configurations involving the debugging of
14347 embedded operating systems that are available for several different
14352 * VxWorks:: Using GDB with VxWorks
14354 GDB includes the ability to debug programs running on various
14355 real-time operating systems.
14358 File: gdb.info, Node: VxWorks, Up: Embedded OS
14360 21.2.1 Using GDB with VxWorks
14361 -----------------------------
14363 `target vxworks MACHINENAME'
14364 A VxWorks system, attached via TCP/IP. The argument MACHINENAME
14365 is the target system's machine name or IP address.
14368 On VxWorks, `load' links FILENAME dynamically on the current target
14369 system as well as adding its symbols in GDB.
14371 GDB enables developers to spawn and debug tasks running on networked
14372 VxWorks targets from a Unix host. Already-running tasks spawned from
14373 the VxWorks shell can also be debugged. GDB uses code that runs on
14374 both the Unix host and on the VxWorks target. The program `gdb' is
14375 installed and executed on the Unix host. (It may be installed with the
14376 name `vxgdb', to distinguish it from a GDB for debugging programs on
14379 `VxWorks-timeout ARGS'
14380 All VxWorks-based targets now support the option `vxworks-timeout'.
14381 This option is set by the user, and ARGS represents the number of
14382 seconds GDB waits for responses to rpc's. You might use this if
14383 your VxWorks target is a slow software simulator or is on the far
14384 side of a thin network line.
14386 The following information on connecting to VxWorks was current when
14387 this manual was produced; newer releases of VxWorks may use revised
14390 To use GDB with VxWorks, you must rebuild your VxWorks kernel to
14391 include the remote debugging interface routines in the VxWorks library
14392 `rdb.a'. To do this, define `INCLUDE_RDB' in the VxWorks configuration
14393 file `configAll.h' and rebuild your VxWorks kernel. The resulting
14394 kernel contains `rdb.a', and spawns the source debugging task
14395 `tRdbTask' when VxWorks is booted. For more information on configuring
14396 and remaking VxWorks, see the manufacturer's manual.
14398 Once you have included `rdb.a' in your VxWorks system image and set
14399 your Unix execution search path to find GDB, you are ready to run GDB.
14400 From your Unix host, run `gdb' (or `vxgdb', depending on your
14403 GDB comes up showing the prompt:
14409 * VxWorks Connection:: Connecting to VxWorks
14410 * VxWorks Download:: VxWorks download
14411 * VxWorks Attach:: Running tasks
14414 File: gdb.info, Node: VxWorks Connection, Next: VxWorks Download, Up: VxWorks
14416 21.2.1.1 Connecting to VxWorks
14417 ..............................
14419 The GDB command `target' lets you connect to a VxWorks target on the
14420 network. To connect to a target whose host name is "`tt'", type:
14422 (vxgdb) target vxworks tt
14424 GDB displays messages like these:
14426 Attaching remote machine across net...
14429 GDB then attempts to read the symbol tables of any object modules
14430 loaded into the VxWorks target since it was last booted. GDB locates
14431 these files by searching the directories listed in the command search
14432 path (*note Your Program's Environment: Environment.); if it fails to
14433 find an object file, it displays a message such as:
14435 prog.o: No such file or directory.
14437 When this happens, add the appropriate directory to the search path
14438 with the GDB command `path', and execute the `target' command again.
14441 File: gdb.info, Node: VxWorks Download, Next: VxWorks Attach, Prev: VxWorks Connection, Up: VxWorks
14443 21.2.1.2 VxWorks Download
14444 .........................
14446 If you have connected to the VxWorks target and you want to debug an
14447 object that has not yet been loaded, you can use the GDB `load' command
14448 to download a file from Unix to VxWorks incrementally. The object file
14449 given as an argument to the `load' command is actually opened twice:
14450 first by the VxWorks target in order to download the code, then by GDB
14451 in order to read the symbol table. This can lead to problems if the
14452 current working directories on the two systems differ. If both systems
14453 have NFS mounted the same filesystems, you can avoid these problems by
14454 using absolute paths. Otherwise, it is simplest to set the working
14455 directory on both systems to the directory in which the object file
14456 resides, and then to reference the file by its name, without any path.
14457 For instance, a program `prog.o' may reside in `VXPATH/vw/demo/rdb' in
14458 VxWorks and in `HOSTPATH/vw/demo/rdb' on the host. To load this
14459 program, type this on VxWorks:
14461 -> cd "VXPATH/vw/demo/rdb"
14463 Then, in GDB, type:
14465 (vxgdb) cd HOSTPATH/vw/demo/rdb
14466 (vxgdb) load prog.o
14468 GDB displays a response similar to this:
14470 Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
14472 You can also use the `load' command to reload an object module after
14473 editing and recompiling the corresponding source file. Note that this
14474 makes GDB delete all currently-defined breakpoints, auto-displays, and
14475 convenience variables, and to clear the value history. (This is
14476 necessary in order to preserve the integrity of debugger's data
14477 structures that reference the target system's symbol table.)
14480 File: gdb.info, Node: VxWorks Attach, Prev: VxWorks Download, Up: VxWorks
14482 21.2.1.3 Running Tasks
14483 ......................
14485 You can also attach to an existing task using the `attach' command as
14488 (vxgdb) attach TASK
14490 where TASK is the VxWorks hexadecimal task ID. The task can be running
14491 or suspended when you attach to it. Running tasks are suspended at the
14492 time of attachment.
14495 File: gdb.info, Node: Embedded Processors, Next: Architectures, Prev: Embedded OS, Up: Configurations
14497 21.3 Embedded Processors
14498 ========================
14500 This section goes into details specific to particular embedded
14503 Whenever a specific embedded processor has a simulator, GDB allows
14504 to send an arbitrary command to the simulator.
14507 Send an arbitrary COMMAND string to the simulator. Consult the
14508 documentation for the specific simulator in use for information
14509 about acceptable commands.
14514 * M32R/D:: Renesas M32R/D
14515 * M68K:: Motorola M68K
14516 * MicroBlaze:: Xilinx MicroBlaze
14517 * MIPS Embedded:: MIPS Embedded
14518 * OpenRISC 1000:: OpenRisc 1000
14519 * PA:: HP PA Embedded
14520 * PowerPC Embedded:: PowerPC Embedded
14521 * Sparclet:: Tsqware Sparclet
14522 * Sparclite:: Fujitsu Sparclite
14523 * Z8000:: Zilog Z8000
14526 * Super-H:: Renesas Super-H
14529 File: gdb.info, Node: ARM, Next: M32R/D, Up: Embedded Processors
14535 ARM Angel monitor, via RDI library interface to ADP protocol. You
14536 may use this target to communicate with both boards running the
14537 Angel monitor, or with the EmbeddedICE JTAG debug device.
14543 GDB provides the following ARM-specific commands:
14545 `set arm disassembler'
14546 This commands selects from a list of disassembly styles. The
14547 `"std"' style is the standard style.
14549 `show arm disassembler'
14550 Show the current disassembly style.
14553 This command toggles ARM operation mode between 32-bit and 26-bit.
14556 Display the current usage of the ARM 32-bit mode.
14558 `set arm fpu FPUTYPE'
14559 This command sets the ARM floating-point unit (FPU) type. The
14560 argument FPUTYPE can be one of these:
14563 Determine the FPU type by querying the OS ABI.
14566 Software FPU, with mixed-endian doubles on little-endian ARM
14570 GCC-compiled FPA co-processor.
14573 Software FPU with pure-endian doubles.
14579 Show the current type of the FPU.
14582 This command forces GDB to use the specified ABI.
14585 Show the currently used ABI.
14587 `set arm fallback-mode (arm|thumb|auto)'
14588 GDB uses the symbol table, when available, to determine whether
14589 instructions are ARM or Thumb. This command controls GDB's
14590 default behavior when the symbol table is not available. The
14591 default is `auto', which causes GDB to use the current execution
14592 mode (from the `T' bit in the `CPSR' register).
14594 `show arm fallback-mode'
14595 Show the current fallback instruction mode.
14597 `set arm force-mode (arm|thumb|auto)'
14598 This command overrides use of the symbol table to determine whether
14599 instructions are ARM or Thumb. The default is `auto', which
14600 causes GDB to use the symbol table and then the setting of `set
14601 arm fallback-mode'.
14603 `show arm force-mode'
14604 Show the current forced instruction mode.
14607 Toggle whether to display ARM-specific debugging messages from the
14608 ARM target support subsystem.
14611 Show whether ARM-specific debugging messages are enabled.
14613 The following commands are available when an ARM target is debugged
14614 using the RDI interface:
14616 `rdilogfile [FILE]'
14617 Set the filename for the ADP (Angel Debugger Protocol) packet log.
14618 With an argument, sets the log file to the specified FILE. With
14619 no argument, show the current log file name. The default log file
14622 `rdilogenable [ARG]'
14623 Control logging of ADP packets. With an argument of 1 or `"yes"'
14624 enables logging, with an argument 0 or `"no"' disables it. With
14625 no arguments displays the current setting. When logging is
14626 enabled, ADP packets exchanged between GDB and the RDI target
14627 device are logged to a file.
14630 Tell GDB whether the target has ROM at address 0. If on, vector
14631 catching is disabled, so that zero address can be used. If off
14632 (the default), vector catching is enabled. For this command to
14633 take effect, it needs to be invoked prior to the `target rdi'
14636 `show rdiromatzero'
14637 Show the current setting of ROM at zero address.
14640 Enable or disable RDI heartbeat packets. It is not recommended to
14641 turn on this option, since it confuses ARM and EPI JTAG interface,
14642 as well as the Angel monitor.
14644 `show rdiheartbeat'
14645 Show the setting of RDI heartbeat packets.
14648 File: gdb.info, Node: M32R/D, Next: M68K, Prev: ARM, Up: Embedded Processors
14650 21.3.2 Renesas M32R/D and M32R/SDI
14651 ----------------------------------
14654 Renesas M32R/D ROM monitor.
14656 `target m32rsdi DEV'
14657 Renesas M32R SDI server, connected via parallel port to the board.
14659 The following GDB commands are specific to the M32R monitor:
14661 `set download-path PATH'
14662 Set the default path for finding downloadable SREC files.
14664 `show download-path'
14665 Show the default path for downloadable SREC files.
14667 `set board-address ADDR'
14668 Set the IP address for the M32R-EVA target board.
14670 `show board-address'
14671 Show the current IP address of the target board.
14673 `set server-address ADDR'
14674 Set the IP address for the download server, which is the GDB's
14677 `show server-address'
14678 Display the IP address of the download server.
14681 Upload the specified SREC FILE via the monitor's Ethernet upload
14682 capability. If no FILE argument is given, the current executable
14686 Test the `upload' command.
14688 The following commands are available for M32R/SDI:
14691 This command resets the SDI connection.
14694 This command shows the SDI connection status.
14697 Instructs the remote that M32R/Chaos debugging is to be used.
14700 Instructs the remote to use the DEBUG_DMA method of accessing
14704 Instructs the remote to use the MON_CODE method of accessing
14708 Instructs the remote to set breakpoints by IB break.
14711 Instructs the remote to set breakpoints by DBT.
14714 File: gdb.info, Node: M68K, Next: MicroBlaze, Prev: M32R/D, Up: Embedded Processors
14719 The Motorola m68k configuration includes ColdFire support, and a target
14720 command for the following ROM monitor.
14723 dBUG ROM monitor for Motorola ColdFire.
14727 File: gdb.info, Node: MicroBlaze, Next: MIPS Embedded, Prev: M68K, Up: Embedded Processors
14732 The MicroBlaze is a soft-core processor supported on various Xilinx
14733 FPGAs, such as Spartan or Virtex series. Boards with these processors
14734 usually have JTAG ports which connect to a host system running the
14735 Xilinx Embedded Development Kit (EDK) or Software Development Kit (SDK).
14736 This host system is used to download the configuration bitstream to the
14737 target FPGA. The Xilinx Microprocessor Debugger (XMD) program
14738 communicates with the target board using the JTAG interface and
14739 presents a `gdbserver' interface to the board. By default `xmd' uses
14740 port `1234'. (While it is possible to change this default port, it
14741 requires the use of undocumented `xmd' commands. Contact Xilinx
14742 support if you need to do this.)
14744 Use these GDB commands to connect to the MicroBlaze target processor.
14746 `target remote :1234'
14747 Use this command to connect to the target if you are running GDB
14748 on the same system as `xmd'.
14750 `target remote XMD-HOST:1234'
14751 Use this command to connect to the target if it is connected to
14752 `xmd' running on a different system named XMD-HOST.
14755 Use this command to download a program to the MicroBlaze target.
14757 `set debug microblaze N'
14758 Enable MicroBlaze-specific debugging messages if non-zero.
14760 `show debug microblaze N'
14761 Show MicroBlaze-specific debugging level.
14764 File: gdb.info, Node: MIPS Embedded, Next: OpenRISC 1000, Prev: MicroBlaze, Up: Embedded Processors
14766 21.3.5 MIPS Embedded
14767 --------------------
14769 GDB can use the MIPS remote debugging protocol to talk to a MIPS board
14770 attached to a serial line. This is available when you configure GDB
14771 with `--target=mips-idt-ecoff'.
14773 Use these GDB commands to specify the connection to your target
14777 To run a program on the board, start up `gdb' with the name of
14778 your program as the argument. To connect to the board, use the
14779 command `target mips PORT', where PORT is the name of the serial
14780 port connected to the board. If the program has not already been
14781 downloaded to the board, you may use the `load' command to
14782 download it. You can then use all the usual GDB commands.
14784 For example, this sequence connects to the target board through a
14785 serial port, and loads and runs a program called PROG through the
14789 GDB is free software and ...
14790 (gdb) target mips /dev/ttyb
14794 `target mips HOSTNAME:PORTNUMBER'
14795 On some GDB host configurations, you can specify a TCP connection
14796 (for instance, to a serial line managed by a terminal
14797 concentrator) instead of a serial port, using the syntax
14798 `HOSTNAME:PORTNUMBER'.
14804 NEC's DDB variant of PMON for Vr4300.
14807 LSI variant of PMON.
14810 Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
14813 Array Tech LSI33K RAID controller board.
14816 GDB also supports these special commands for MIPS targets:
14818 `set mipsfpu double'
14819 `set mipsfpu single'
14823 If your target board does not support the MIPS floating point
14824 coprocessor, you should use the command `set mipsfpu none' (if you
14825 need this, you may wish to put the command in your GDB init file).
14826 This tells GDB how to find the return value of functions which
14827 return floating point values. It also allows GDB to avoid saving
14828 the floating point registers when calling functions on the board.
14829 If you are using a floating point coprocessor with only single
14830 precision floating point support, as on the R4650 processor, use
14831 the command `set mipsfpu single'. The default double precision
14832 floating point coprocessor may be selected using `set mipsfpu
14835 In previous versions the only choices were double precision or no
14836 floating point, so `set mipsfpu on' will select double precision
14837 and `set mipsfpu off' will select no floating point.
14839 As usual, you can inquire about the `mipsfpu' variable with `show
14842 `set timeout SECONDS'
14843 `set retransmit-timeout SECONDS'
14845 `show retransmit-timeout'
14846 You can control the timeout used while waiting for a packet, in
14847 the MIPS remote protocol, with the `set timeout SECONDS' command.
14848 The default is 5 seconds. Similarly, you can control the timeout
14849 used while waiting for an acknowledgment of a packet with the `set
14850 retransmit-timeout SECONDS' command. The default is 3 seconds.
14851 You can inspect both values with `show timeout' and `show
14852 retransmit-timeout'. (These commands are _only_ available when
14853 GDB is configured for `--target=mips-idt-ecoff'.)
14855 The timeout set by `set timeout' does not apply when GDB is
14856 waiting for your program to stop. In that case, GDB waits forever
14857 because it has no way of knowing how long the program is going to
14858 run before stopping.
14860 `set syn-garbage-limit NUM'
14861 Limit the maximum number of characters GDB should ignore when it
14862 tries to synchronize with the remote target. The default is 10
14863 characters. Setting the limit to -1 means there's no limit.
14865 `show syn-garbage-limit'
14866 Show the current limit on the number of characters to ignore when
14867 trying to synchronize with the remote system.
14869 `set monitor-prompt PROMPT'
14870 Tell GDB to expect the specified PROMPT string from the remote
14871 monitor. The default depends on the target:
14881 `show monitor-prompt'
14882 Show the current strings GDB expects as the prompt from the remote
14885 `set monitor-warnings'
14886 Enable or disable monitor warnings about hardware breakpoints.
14887 This has effect only for the `lsi' target. When on, GDB will
14888 display warning messages whose codes are returned by the `lsi'
14889 PMON monitor for breakpoint commands.
14891 `show monitor-warnings'
14892 Show the current setting of printing monitor warnings.
14895 This command allows sending an arbitrary COMMAND string to the
14896 monitor. The monitor must be in debug mode for this to work.
14899 File: gdb.info, Node: OpenRISC 1000, Next: PA, Prev: MIPS Embedded, Up: Embedded Processors
14901 21.3.6 OpenRISC 1000
14902 --------------------
14904 See OR1k Architecture document (`www.opencores.org') for more
14905 information about platform and commands.
14907 `target jtag jtag://HOST:PORT'
14908 Connects to remote JTAG server. JTAG remote server can be either
14909 an or1ksim or JTAG server, connected via parallel port to the
14912 Example: `target jtag jtag://localhost:9999'
14915 If connected to `or1ksim' OpenRISC 1000 Architectural Simulator,
14916 proprietary commands can be executed.
14919 Displays spr groups.
14921 `info or1k spr GROUP'
14922 `info or1k spr GROUPNO'
14923 Displays register names in selected group.
14925 `info or1k spr GROUP REGISTER'
14926 `info or1k spr REGISTER'
14927 `info or1k spr GROUPNO REGISTERNO'
14928 `info or1k spr REGISTERNO'
14929 Shows information about specified spr register.
14931 `spr GROUP REGISTER VALUE'
14932 `spr REGISTER VALUE'
14933 `spr GROUPNO REGISTERNO VALUE'
14934 `spr REGISTERNO VALUE'
14935 Writes VALUE to specified spr register.
14937 Some implementations of OpenRISC 1000 Architecture also have
14938 hardware trace. It is very similar to GDB trace, except it does not
14939 interfere with normal program execution and is thus much faster.
14940 Hardware breakpoints/watchpoint triggers can be set using:
14942 Load effective address/data
14945 Store effective address/data
14948 Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA)
14953 When triggered, it can capture low level data, like: `PC', `LSEA',
14954 `LDATA', `SDATA', `READSPR', `WRITESPR', `INSTR'.
14957 `hwatch CONDITIONAL'
14958 Set hardware watchpoint on combination of Load/Store Effective
14959 Address(es) or Data. For example:
14961 `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) &&
14964 `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) &&
14968 Display information about current HW trace configuration.
14970 `htrace trigger CONDITIONAL'
14971 Set starting criteria for HW trace.
14973 `htrace qualifier CONDITIONAL'
14974 Set acquisition qualifier for HW trace.
14976 `htrace stop CONDITIONAL'
14977 Set HW trace stopping criteria.
14979 `htrace record [DATA]*'
14980 Selects the data to be recorded, when qualifier is met and HW
14981 trace was triggered.
14985 Enables/disables the HW trace.
14987 `htrace rewind [FILENAME]'
14988 Clears currently recorded trace data.
14990 If filename is specified, new trace file is made and any newly
14991 collected data will be written there.
14993 `htrace print [START [LEN]]'
14994 Prints trace buffer, using current record configuration.
14996 `htrace mode continuous'
14997 Set continuous trace mode.
14999 `htrace mode suspend'
15000 Set suspend trace mode.
15004 File: gdb.info, Node: PowerPC Embedded, Next: Sparclet, Prev: PA, Up: Embedded Processors
15006 21.3.7 PowerPC Embedded
15007 -----------------------
15009 GDB provides the following PowerPC-specific commands:
15011 `set powerpc soft-float'
15012 `show powerpc soft-float'
15013 Force GDB to use (or not use) a software floating point calling
15014 convention. By default, GDB selects the calling convention based
15015 on the selected architecture and the provided executable file.
15017 `set powerpc vector-abi'
15018 `show powerpc vector-abi'
15019 Force GDB to use the specified calling convention for vector
15020 arguments and return values. The valid options are `auto';
15021 `generic', to avoid vector registers even if they are present;
15022 `altivec', to use AltiVec registers; and `spe' to use SPE
15023 registers. By default, GDB selects the calling convention based
15024 on the selected architecture and the provided executable file.
15026 `target dink32 DEV'
15027 DINK32 ROM monitor.
15029 `target ppcbug DEV'
15031 `target ppcbug1 DEV'
15032 PPCBUG ROM monitor for PowerPC.
15035 SDS monitor, running on a PowerPC board (such as Motorola's ADS).
15037 The following commands specific to the SDS protocol are supported by
15040 `set sdstimeout NSEC'
15041 Set the timeout for SDS protocol reads to be NSEC seconds. The
15042 default is 2 seconds.
15045 Show the current value of the SDS timeout.
15048 Send the specified COMMAND string to the SDS monitor.
15051 File: gdb.info, Node: PA, Next: PowerPC Embedded, Prev: OpenRISC 1000, Up: Embedded Processors
15053 21.3.8 HP PA Embedded
15054 ---------------------
15057 OP50N monitor, running on an OKI HPPA board.
15060 W89K monitor, running on a Winbond HPPA board.
15064 File: gdb.info, Node: Sparclet, Next: Sparclite, Prev: PowerPC Embedded, Up: Embedded Processors
15066 21.3.9 Tsqware Sparclet
15067 -----------------------
15069 GDB enables developers to debug tasks running on Sparclet targets from
15070 a Unix host. GDB uses code that runs on both the Unix host and on the
15071 Sparclet target. The program `gdb' is installed and executed on the
15074 `remotetimeout ARGS'
15075 GDB supports the option `remotetimeout'. This option is set by
15076 the user, and ARGS represents the number of seconds GDB waits for
15079 When compiling for debugging, include the options `-g' to get debug
15080 information and `-Ttext' to relocate the program to where you wish to
15081 load it on the target. You may also want to add the options `-n' or
15082 `-N' in order to reduce the size of the sections. Example:
15084 sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
15086 You can use `objdump' to verify that the addresses are what you
15089 sparclet-aout-objdump --headers --syms prog
15091 Once you have set your Unix execution search path to find GDB, you
15092 are ready to run GDB. From your Unix host, run `gdb' (or
15093 `sparclet-aout-gdb', depending on your installation).
15095 GDB comes up showing the prompt:
15101 * Sparclet File:: Setting the file to debug
15102 * Sparclet Connection:: Connecting to Sparclet
15103 * Sparclet Download:: Sparclet download
15104 * Sparclet Execution:: Running and debugging
15107 File: gdb.info, Node: Sparclet File, Next: Sparclet Connection, Up: Sparclet
15109 21.3.9.1 Setting File to Debug
15110 ..............................
15112 The GDB command `file' lets you choose with program to debug.
15114 (gdbslet) file prog
15116 GDB then attempts to read the symbol table of `prog'. GDB locates
15117 the file by searching the directories listed in the command search path.
15118 If the file was compiled with debug information (option `-g'), source
15119 files will be searched as well. GDB locates the source files by
15120 searching the directories listed in the directory search path (*note
15121 Your Program's Environment: Environment.). If it fails to find a file,
15122 it displays a message such as:
15124 prog: No such file or directory.
15126 When this happens, add the appropriate directories to the search
15127 paths with the GDB commands `path' and `dir', and execute the `target'
15131 File: gdb.info, Node: Sparclet Connection, Next: Sparclet Download, Prev: Sparclet File, Up: Sparclet
15133 21.3.9.2 Connecting to Sparclet
15134 ...............................
15136 The GDB command `target' lets you connect to a Sparclet target. To
15137 connect to a target on serial port "`ttya'", type:
15139 (gdbslet) target sparclet /dev/ttya
15140 Remote target sparclet connected to /dev/ttya
15141 main () at ../prog.c:3
15143 GDB displays messages like these:
15148 File: gdb.info, Node: Sparclet Download, Next: Sparclet Execution, Prev: Sparclet Connection, Up: Sparclet
15150 21.3.9.3 Sparclet Download
15151 ..........................
15153 Once connected to the Sparclet target, you can use the GDB `load'
15154 command to download the file from the host to the target. The file
15155 name and load offset should be given as arguments to the `load' command.
15156 Since the file format is aout, the program must be loaded to the
15157 starting address. You can use `objdump' to find out what this value
15158 is. The load offset is an offset which is added to the VMA (virtual
15159 memory address) of each of the file's sections. For instance, if the
15160 program `prog' was linked to text address 0x1201000, with data at
15161 0x12010160 and bss at 0x12010170, in GDB, type:
15163 (gdbslet) load prog 0x12010000
15164 Loading section .text, size 0xdb0 vma 0x12010000
15166 If the code is loaded at a different address then what the program
15167 was linked to, you may need to use the `section' and `add-symbol-file'
15168 commands to tell GDB where to map the symbol table.
15171 File: gdb.info, Node: Sparclet Execution, Prev: Sparclet Download, Up: Sparclet
15173 21.3.9.4 Running and Debugging
15174 ..............................
15176 You can now begin debugging the task using GDB's execution control
15177 commands, `b', `step', `run', etc. See the GDB manual for the list of
15181 Breakpoint 1 at 0x12010000: file prog.c, line 3.
15183 Starting program: prog
15184 Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
15185 3 char *symarg = 0;
15187 4 char *execarg = "hello!";
15191 File: gdb.info, Node: Sparclite, Next: Z8000, Prev: Sparclet, Up: Embedded Processors
15193 21.3.10 Fujitsu Sparclite
15194 -------------------------
15196 `target sparclite DEV'
15197 Fujitsu sparclite boards, used only for the purpose of loading.
15198 You must use an additional command to debug the program. For
15199 example: target remote DEV using GDB standard remote protocol.
15203 File: gdb.info, Node: Z8000, Next: AVR, Prev: Sparclite, Up: Embedded Processors
15205 21.3.11 Zilog Z8000
15206 -------------------
15208 When configured for debugging Zilog Z8000 targets, GDB includes a Z8000
15211 For the Z8000 family, `target sim' simulates either the Z8002 (the
15212 unsegmented variant of the Z8000 architecture) or the Z8001 (the
15213 segmented variant). The simulator recognizes which architecture is
15214 appropriate by inspecting the object code.
15217 Debug programs on a simulated CPU. If the simulator supports setup
15218 options, specify them via ARGS.
15220 After specifying this target, you can debug programs for the simulated
15221 CPU in the same style as programs for your host computer; use the
15222 `file' command to load a new program image, the `run' command to run
15223 your program, and so on.
15225 As well as making available all the usual machine registers (*note
15226 Registers: Registers.), the Z8000 simulator provides three additional
15227 items of information as specially named registers:
15230 Counts clock-ticks in the simulator.
15233 Counts instructions run in the simulator.
15236 Execution time in 60ths of a second.
15239 You can refer to these values in GDB expressions with the usual
15240 conventions; for example, `b fputc if $cycles>5000' sets a conditional
15241 breakpoint that suspends only after at least 5000 simulated clock ticks.
15244 File: gdb.info, Node: AVR, Next: CRIS, Prev: Z8000, Up: Embedded Processors
15249 When configured for debugging the Atmel AVR, GDB supports the following
15250 AVR-specific commands:
15252 `info io_registers'
15253 This command displays information about the AVR I/O registers. For
15254 each register, GDB prints its number and value.
15257 File: gdb.info, Node: CRIS, Next: Super-H, Prev: AVR, Up: Embedded Processors
15262 When configured for debugging CRIS, GDB provides the following
15263 CRIS-specific commands:
15265 `set cris-version VER'
15266 Set the current CRIS version to VER, either `10' or `32'. The
15267 CRIS version affects register names and sizes. This command is
15268 useful in case autodetection of the CRIS version fails.
15270 `show cris-version'
15271 Show the current CRIS version.
15273 `set cris-dwarf2-cfi'
15274 Set the usage of DWARF-2 CFI for CRIS debugging. The default is
15275 `on'. Change to `off' when using `gcc-cris' whose version is below
15278 `show cris-dwarf2-cfi'
15279 Show the current state of using DWARF-2 CFI.
15281 `set cris-mode MODE'
15282 Set the current CRIS mode to MODE. It should only be changed when
15283 debugging in guru mode, in which case it should be set to `guru'
15284 (the default is `normal').
15287 Show the current CRIS mode.
15290 File: gdb.info, Node: Super-H, Prev: CRIS, Up: Embedded Processors
15292 21.3.14 Renesas Super-H
15293 -----------------------
15295 For the Renesas Super-H processor, GDB provides these commands:
15298 Show the values of all Super-H registers.
15300 `set sh calling-convention CONVENTION'
15301 Set the calling-convention used when calling functions from GDB.
15302 Allowed values are `gcc', which is the default setting, and
15303 `renesas'. With the `gcc' setting, functions are called using the
15304 GCC calling convention. If the DWARF-2 information of the called
15305 function specifies that the function follows the Renesas calling
15306 convention, the function is called using the Renesas calling
15307 convention. If the calling convention is set to `renesas', the
15308 Renesas calling convention is always used, regardless of the
15309 DWARF-2 information. This can be used to override the default of
15310 `gcc' if debug information is missing, or the compiler does not
15311 emit the DWARF-2 calling convention entry for a function.
15313 `show sh calling-convention'
15314 Show the current calling convention setting.
15318 File: gdb.info, Node: Architectures, Prev: Embedded Processors, Up: Configurations
15323 This section describes characteristics of architectures that affect all
15324 uses of GDB with the architecture, both native and cross.
15332 * HPPA:: HP PA architecture
15333 * SPU:: Cell Broadband Engine SPU architecture
15337 File: gdb.info, Node: i386, Next: A29K, Up: Architectures
15339 21.4.1 x86 Architecture-specific Issues
15340 ---------------------------------------
15342 `set struct-convention MODE'
15343 Set the convention used by the inferior to return `struct's and
15344 `union's from functions to MODE. Possible values of MODE are
15345 `"pcc"', `"reg"', and `"default"' (the default). `"default"' or
15346 `"pcc"' means that `struct's are returned on the stack, while
15347 `"reg"' means that a `struct' or a `union' whose size is 1, 2, 4,
15348 or 8 bytes will be returned in a register.
15350 `show struct-convention'
15351 Show the current setting of the convention to return `struct's
15355 File: gdb.info, Node: A29K, Next: Alpha, Prev: i386, Up: Architectures
15360 `set rstack_high_address ADDRESS'
15361 On AMD 29000 family processors, registers are saved in a separate
15362 "register stack". There is no way for GDB to determine the extent
15363 of this stack. Normally, GDB just assumes that the stack is
15364 "large enough". This may result in GDB referencing memory
15365 locations that do not exist. If necessary, you can get around
15366 this problem by specifying the ending address of the register
15367 stack with the `set rstack_high_address' command. The argument
15368 should be an address, which you probably want to precede with `0x'
15369 to specify in hexadecimal.
15371 `show rstack_high_address'
15372 Display the current limit of the register stack, on AMD 29000
15377 File: gdb.info, Node: Alpha, Next: MIPS, Prev: A29K, Up: Architectures
15382 See the following section.
15385 File: gdb.info, Node: MIPS, Next: HPPA, Prev: Alpha, Up: Architectures
15390 Alpha- and MIPS-based computers use an unusual stack frame, which
15391 sometimes requires GDB to search backward in the object code to find
15392 the beginning of a function.
15394 To improve response time (especially for embedded applications, where
15395 GDB may be restricted to a slow serial line for this search) you may
15396 want to limit the size of this search, using one of these commands:
15398 `set heuristic-fence-post LIMIT'
15399 Restrict GDB to examining at most LIMIT bytes in its search for
15400 the beginning of a function. A value of 0 (the default) means
15401 there is no limit. However, except for 0, the larger the limit
15402 the more bytes `heuristic-fence-post' must search and therefore
15403 the longer it takes to run. You should only need to use this
15404 command when debugging a stripped executable.
15406 `show heuristic-fence-post'
15407 Display the current limit.
15409 These commands are available _only_ when GDB is configured for
15410 debugging programs on Alpha or MIPS processors.
15412 Several MIPS-specific commands are available when debugging MIPS
15416 Tell GDB which MIPS ABI is used by the inferior. Possible values
15420 The default ABI associated with the current binary (this is
15438 Show the MIPS ABI used by GDB to debug the inferior.
15442 *Note set mipsfpu: MIPS Embedded.
15444 `set mips mask-address ARG'
15445 This command determines whether the most-significant 32 bits of
15446 64-bit MIPS addresses are masked off. The argument ARG can be
15447 `on', `off', or `auto'. The latter is the default setting, which
15448 lets GDB determine the correct value.
15450 `show mips mask-address'
15451 Show whether the upper 32 bits of MIPS addresses are masked off or
15454 `set remote-mips64-transfers-32bit-regs'
15455 This command controls compatibility with 64-bit MIPS targets that
15456 transfer data in 32-bit quantities. If you have an old MIPS 64
15457 target that transfers 32 bits for some registers, like SR and FSR,
15458 and 64 bits for other registers, set this option to `on'.
15460 `show remote-mips64-transfers-32bit-regs'
15461 Show the current setting of compatibility with older MIPS 64
15465 This command turns on and off debugging messages for the
15466 MIPS-specific target code in GDB.
15469 Show the current setting of MIPS debugging messages.
15472 File: gdb.info, Node: HPPA, Next: SPU, Prev: MIPS, Up: Architectures
15477 When GDB is debugging the HP PA architecture, it provides the following
15481 This command determines whether HPPA architecture-specific
15482 debugging messages are to be displayed.
15485 Show whether HPPA debugging messages are displayed.
15487 `maint print unwind ADDRESS'
15488 This command displays the contents of the unwind table entry at the
15493 File: gdb.info, Node: SPU, Next: PowerPC, Prev: HPPA, Up: Architectures
15495 21.4.6 Cell Broadband Engine SPU architecture
15496 ---------------------------------------------
15498 When GDB is debugging the Cell Broadband Engine SPU architecture, it
15499 provides the following special commands:
15502 Display SPU event facility status. Shows current event mask and
15503 pending event status.
15506 Display SPU signal notification facility status. Shows pending
15507 signal-control word and signal notification mode of both signal
15508 notification channels.
15511 Display SPU mailbox facility status. Shows all pending entries,
15512 in order of processing, in each of the SPU Write Outbound, SPU
15513 Write Outbound Interrupt, and SPU Read Inbound mailboxes.
15516 Display MFC DMA status. Shows all pending commands in the MFC DMA
15517 queue. For each entry, opcode, tag, class IDs, effective and
15518 local store addresses and transfer size are shown.
15520 `info spu proxydma'
15521 Display MFC Proxy-DMA status. Shows all pending commands in the
15522 MFC Proxy-DMA queue. For each entry, opcode, tag, class IDs,
15523 effective and local store addresses and transfer size are shown.
15526 When GDB is debugging a combined PowerPC/SPU application on the Cell
15527 Broadband Engine, it provides in addition the following special
15530 `set spu stop-on-load ARG'
15531 Set whether to stop for new SPE threads. When set to `on', GDB
15532 will give control to the user when a new SPE thread enters its
15533 `main' function. The default is `off'.
15535 `show spu stop-on-load'
15536 Show whether to stop for new SPE threads.
15538 `set spu auto-flush-cache ARG'
15539 Set whether to automatically flush the software-managed cache.
15540 When set to `on', GDB will automatically cause the SPE
15541 software-managed cache to be flushed whenever SPE execution stops.
15542 This provides a consistent view of PowerPC memory that is accessed
15543 via the cache. If an application does not use the
15544 software-managed cache, this option has no effect.
15546 `show spu auto-flush-cache'
15547 Show whether to automatically flush the software-managed cache.
15551 File: gdb.info, Node: PowerPC, Prev: SPU, Up: Architectures
15556 When GDB is debugging the PowerPC architecture, it provides a set of
15557 pseudo-registers to enable inspection of 128-bit wide Decimal Floating
15558 Point numbers stored in the floating point registers. These values must
15559 be stored in two consecutive registers, always starting at an even
15560 register like `f0' or `f2'.
15562 The pseudo-registers go from `$dl0' through `$dl15', and are formed
15563 by joining the even/odd register pairs `f0' and `f1' for `$dl0', `f2'
15564 and `f3' for `$dl1' and so on.
15566 For POWER7 processors, GDB provides a set of pseudo-registers, the
15567 64-bit wide Extended Floating Point Registers (`f32' through `f63').
15570 File: gdb.info, Node: Controlling GDB, Next: Extending GDB, Prev: Configurations, Up: Top
15575 You can alter the way GDB interacts with you by using the `set'
15576 command. For commands controlling how GDB displays data, see *note
15577 Print Settings: Print Settings. Other settings are described here.
15582 * Editing:: Command editing
15583 * Command History:: Command history
15584 * Screen Size:: Screen size
15585 * Numbers:: Numbers
15586 * ABI:: Configuring the current ABI
15587 * Messages/Warnings:: Optional warnings and messages
15588 * Debugging Output:: Optional messages about internal happenings
15589 * Other Misc Settings:: Other Miscellaneous Settings
15592 File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB
15597 GDB indicates its readiness to read a command by printing a string
15598 called the "prompt". This string is normally `(gdb)'. You can change
15599 the prompt string with the `set prompt' command. For instance, when
15600 debugging GDB with GDB, it is useful to change the prompt in one of the
15601 GDB sessions so that you can always tell which one you are talking to.
15603 _Note:_ `set prompt' does not add a space for you after the prompt
15604 you set. This allows you to set a prompt which ends in a space or a
15605 prompt that does not.
15607 `set prompt NEWPROMPT'
15608 Directs GDB to use NEWPROMPT as its prompt string henceforth.
15611 Prints a line of the form: `Gdb's prompt is: YOUR-PROMPT'
15614 File: gdb.info, Node: Editing, Next: Command History, Prev: Prompt, Up: Controlling GDB
15616 22.2 Command Editing
15617 ====================
15619 GDB reads its input commands via the "Readline" interface. This GNU
15620 library provides consistent behavior for programs which provide a
15621 command line interface to the user. Advantages are GNU Emacs-style or
15622 "vi"-style inline editing of commands, `csh'-like history substitution,
15623 and a storage and recall of command history across debugging sessions.
15625 You may control the behavior of command line editing in GDB with the
15630 Enable command line editing (enabled by default).
15633 Disable command line editing.
15636 Show whether command line editing is enabled.
15638 *Note Command Line Editing::, for more details about the Readline
15639 interface. Users unfamiliar with GNU Emacs or `vi' are encouraged to
15643 File: gdb.info, Node: Command History, Next: Screen Size, Prev: Editing, Up: Controlling GDB
15645 22.3 Command History
15646 ====================
15648 GDB can keep track of the commands you type during your debugging
15649 sessions, so that you can be certain of precisely what happened. Use
15650 these commands to manage the GDB command history facility.
15652 GDB uses the GNU History library, a part of the Readline package, to
15653 provide the history facility. *Note Using History Interactively::, for
15654 the detailed description of the History library.
15656 To issue a command to GDB without affecting certain aspects of the
15657 state which is seen by users, prefix it with `server ' (*note Server
15658 Prefix::). This means that this command will not affect the command
15659 history, nor will it affect GDB's notion of which command to repeat if
15660 <RET> is pressed on a line by itself.
15662 The server prefix does not affect the recording of values into the
15663 value history; to print a value without recording it into the value
15664 history, use the `output' command instead of the `print' command.
15666 Here is the description of GDB commands related to command history.
15668 `set history filename FNAME'
15669 Set the name of the GDB command history file to FNAME. This is
15670 the file where GDB reads an initial command history list, and
15671 where it writes the command history from this session when it
15672 exits. You can access this list through history expansion or
15673 through the history command editing characters listed below. This
15674 file defaults to the value of the environment variable
15675 `GDBHISTFILE', or to `./.gdb_history' (`./_gdb_history' on MS-DOS)
15676 if this variable is not set.
15679 `set history save on'
15680 Record command history in a file, whose name may be specified with
15681 the `set history filename' command. By default, this option is
15684 `set history save off'
15685 Stop recording command history in a file.
15687 `set history size SIZE'
15688 Set the number of commands which GDB keeps in its history list.
15689 This defaults to the value of the environment variable `HISTSIZE',
15690 or to 256 if this variable is not set.
15692 History expansion assigns special meaning to the character `!'.
15693 *Note Event Designators::, for more details.
15695 Since `!' is also the logical not operator in C, history expansion
15696 is off by default. If you decide to enable history expansion with the
15697 `set history expansion on' command, you may sometimes need to follow
15698 `!' (when it is used as logical not, in an expression) with a space or
15699 a tab to prevent it from being expanded. The readline history
15700 facilities do not attempt substitution on the strings `!=' and `!(',
15701 even when history expansion is enabled.
15703 The commands to control history expansion are:
15705 `set history expansion on'
15706 `set history expansion'
15707 Enable history expansion. History expansion is off by default.
15709 `set history expansion off'
15710 Disable history expansion.
15713 `show history filename'
15714 `show history save'
15715 `show history size'
15716 `show history expansion'
15717 These commands display the state of the GDB history parameters.
15718 `show history' by itself displays all four states.
15721 Display the last ten commands in the command history.
15724 Print ten commands centered on command number N.
15727 Print ten commands just after the commands last printed.
15730 File: gdb.info, Node: Screen Size, Next: Numbers, Prev: Command History, Up: Controlling GDB
15735 Certain commands to GDB may produce large amounts of information output
15736 to the screen. To help you read all of it, GDB pauses and asks you for
15737 input at the end of each page of output. Type <RET> when you want to
15738 continue the output, or `q' to discard the remaining output. Also, the
15739 screen width setting determines when to wrap lines of output.
15740 Depending on what is being printed, GDB tries to break the line at a
15741 readable place, rather than simply letting it overflow onto the
15744 Normally GDB knows the size of the screen from the terminal driver
15745 software. For example, on Unix GDB uses the termcap data base together
15746 with the value of the `TERM' environment variable and the `stty rows'
15747 and `stty cols' settings. If this is not correct, you can override it
15748 with the `set height' and `set width' commands:
15754 These `set' commands specify a screen height of LPP lines and a
15755 screen width of CPL characters. The associated `show' commands
15756 display the current settings.
15758 If you specify a height of zero lines, GDB does not pause during
15759 output no matter how long the output is. This is useful if output
15760 is to a file or to an editor buffer.
15762 Likewise, you can specify `set width 0' to prevent GDB from
15763 wrapping its output.
15765 `set pagination on'
15766 `set pagination off'
15767 Turn the output pagination on or off; the default is on. Turning
15768 pagination off is the alternative to `set height 0'.
15771 Show the current pagination mode.
15774 File: gdb.info, Node: Numbers, Next: ABI, Prev: Screen Size, Up: Controlling GDB
15779 You can always enter numbers in octal, decimal, or hexadecimal in GDB
15780 by the usual conventions: octal numbers begin with `0', decimal numbers
15781 end with `.', and hexadecimal numbers begin with `0x'. Numbers that
15782 neither begin with `0' or `0x', nor end with a `.' are, by default,
15783 entered in base 10; likewise, the default display for numbers--when no
15784 particular format is specified--is base 10. You can change the default
15785 base for both input and output with the commands described below.
15787 `set input-radix BASE'
15788 Set the default base for numeric input. Supported choices for
15789 BASE are decimal 8, 10, or 16. BASE must itself be specified
15790 either unambiguously or using the current input radix; for
15793 set input-radix 012
15794 set input-radix 10.
15795 set input-radix 0xa
15797 sets the input base to decimal. On the other hand, `set
15798 input-radix 10' leaves the input radix unchanged, no matter what
15799 it was, since `10', being without any leading or trailing signs of
15800 its base, is interpreted in the current radix. Thus, if the
15801 current radix is 16, `10' is interpreted in hex, i.e. as 16
15802 decimal, which doesn't change the radix.
15804 `set output-radix BASE'
15805 Set the default base for numeric display. Supported choices for
15806 BASE are decimal 8, 10, or 16. BASE must itself be specified
15807 either unambiguously or using the current input radix.
15810 Display the current default base for numeric input.
15812 `show output-radix'
15813 Display the current default base for numeric display.
15817 These commands set and show the default base for both input and
15818 output of numbers. `set radix' sets the radix of input and output
15819 to the same base; without an argument, it resets the radix back to
15820 its default value of 10.
15824 File: gdb.info, Node: ABI, Next: Messages/Warnings, Prev: Numbers, Up: Controlling GDB
15826 22.6 Configuring the Current ABI
15827 ================================
15829 GDB can determine the "ABI" (Application Binary Interface) of your
15830 application automatically. However, sometimes you need to override its
15831 conclusions. Use these commands to manage GDB's view of the current
15834 One GDB configuration can debug binaries for multiple operating
15835 system targets, either via remote debugging or native emulation. GDB
15836 will autodetect the "OS ABI" (Operating System ABI) in use, but you can
15837 override its conclusion using the `set osabi' command. One example
15838 where this is useful is in debugging of binaries which use an alternate
15839 C library (e.g. UCLIBC for GNU/Linux) which does not have the same
15840 identifying marks that the standard C library for your platform
15844 Show the OS ABI currently in use.
15847 With no argument, show the list of registered available OS ABI's.
15850 Set the current OS ABI to ABI.
15852 Generally, the way that an argument of type `float' is passed to a
15853 function depends on whether the function is prototyped. For a
15854 prototyped (i.e. ANSI/ISO style) function, `float' arguments are passed
15855 unchanged, according to the architecture's convention for `float'. For
15856 unprototyped (i.e. K&R style) functions, `float' arguments are first
15857 promoted to type `double' and then passed.
15859 Unfortunately, some forms of debug information do not reliably
15860 indicate whether a function is prototyped. If GDB calls a function
15861 that is not marked as prototyped, it consults `set
15862 coerce-float-to-double'.
15864 `set coerce-float-to-double'
15865 `set coerce-float-to-double on'
15866 Arguments of type `float' will be promoted to `double' when passed
15867 to an unprototyped function. This is the default setting.
15869 `set coerce-float-to-double off'
15870 Arguments of type `float' will be passed directly to unprototyped
15873 `show coerce-float-to-double'
15874 Show the current setting of promoting `float' to `double'.
15876 GDB needs to know the ABI used for your program's C++ objects. The
15877 correct C++ ABI depends on which C++ compiler was used to build your
15878 application. GDB only fully supports programs with a single C++ ABI;
15879 if your program contains code using multiple C++ ABI's or if GDB can
15880 not identify your program's ABI correctly, you can tell GDB which ABI
15881 to use. Currently supported ABI's include "gnu-v2", for `g++' versions
15882 before 3.0, "gnu-v3", for `g++' versions 3.0 and later, and "hpaCC" for
15883 the HP ANSI C++ compiler. Other C++ compilers may use the "gnu-v2" or
15884 "gnu-v3" ABI's as well. The default setting is "auto".
15887 Show the C++ ABI currently in use.
15890 With no argument, show the list of supported C++ ABI's.
15894 Set the current C++ ABI to ABI, or return to automatic detection.
15897 File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: ABI, Up: Controlling GDB
15899 22.7 Optional Warnings and Messages
15900 ===================================
15902 By default, GDB is silent about its inner workings. If you are running
15903 on a slow machine, you may want to use the `set verbose' command. This
15904 makes GDB tell you when it does a lengthy internal operation, so you
15905 will not think it has crashed.
15907 Currently, the messages controlled by `set verbose' are those which
15908 announce that the symbol table for a source file is being read; see
15909 `symbol-file' in *note Commands to Specify Files: Files.
15912 Enables GDB output of certain informational messages.
15915 Disables GDB output of certain informational messages.
15918 Displays whether `set verbose' is on or off.
15920 By default, if GDB encounters bugs in the symbol table of an object
15921 file, it is silent; but if you are debugging a compiler, you may find
15922 this information useful (*note Errors Reading Symbol Files: Symbol
15925 `set complaints LIMIT'
15926 Permits GDB to output LIMIT complaints about each type of unusual
15927 symbols before becoming silent about the problem. Set LIMIT to
15928 zero to suppress all complaints; set it to a large number to
15929 prevent complaints from being suppressed.
15932 Displays how many symbol complaints GDB is permitted to produce.
15935 By default, GDB is cautious, and asks what sometimes seems to be a
15936 lot of stupid questions to confirm certain commands. For example, if
15937 you try to run a program which is already running:
15940 The program being debugged has been started already.
15941 Start it from the beginning? (y or n)
15943 If you are willing to unflinchingly face the consequences of your own
15944 commands, you can disable this "feature":
15947 Disables confirmation requests.
15950 Enables confirmation requests (the default).
15953 Displays state of confirmation requests.
15956 If you need to debug user-defined commands or sourced files you may
15957 find it useful to enable "command tracing". In this mode each command
15958 will be printed as it is executed, prefixed with one or more `+'
15959 symbols, the quantity denoting the call depth of each command.
15961 `set trace-commands on'
15962 Enable command tracing.
15964 `set trace-commands off'
15965 Disable command tracing.
15967 `show trace-commands'
15968 Display the current state of command tracing.
15971 File: gdb.info, Node: Debugging Output, Next: Other Misc Settings, Prev: Messages/Warnings, Up: Controlling GDB
15973 22.8 Optional Messages about Internal Happenings
15974 ================================================
15976 GDB has commands that enable optional debugging messages from various
15977 GDB subsystems; normally these commands are of interest to GDB
15978 maintainers, or when reporting a bug. This section documents those
15981 `set exec-done-display'
15982 Turns on or off the notification of asynchronous commands'
15983 completion. When on, GDB will print a message when an
15984 asynchronous command finishes its execution. The default is off.
15986 `show exec-done-display'
15987 Displays the current setting of asynchronous command completion
15991 Turns on or off display of gdbarch debugging info. The default is
15995 Displays the current state of displaying gdbarch debugging info.
15997 `set debug aix-thread'
15998 Display debugging messages about inner workings of the AIX thread
16001 `show debug aix-thread'
16002 Show the current state of AIX thread debugging info display.
16004 `set debug dwarf2-die'
16005 Dump DWARF2 DIEs after they are read in. The value is the number
16006 of nesting levels to print. A value of zero turns off the display.
16008 `show debug dwarf2-die'
16009 Show the current state of DWARF2 DIE debugging.
16011 `set debug displaced'
16012 Turns on or off display of GDB debugging info for the displaced
16013 stepping support. The default is off.
16015 `show debug displaced'
16016 Displays the current state of displaying GDB debugging info
16017 related to displaced stepping.
16020 Turns on or off display of GDB event debugging info. The default
16024 Displays the current state of displaying GDB event debugging info.
16026 `set debug expression'
16027 Turns on or off display of debugging info about GDB expression
16028 parsing. The default is off.
16030 `show debug expression'
16031 Displays the current state of displaying debugging info about GDB
16032 expression parsing.
16035 Turns on or off display of GDB frame debugging info. The default
16039 Displays the current state of displaying GDB frame debugging info.
16041 `set debug gnu-nat'
16042 Turns on or off debugging messages from the GNU/Hurd debug support.
16044 `show debug gnu-nat'
16045 Show the current state of GNU/Hurd debugging messages.
16048 Turns on or off display of GDB debugging info for running the
16049 inferior. The default is off. `infrun.c' contains GDB's runtime
16050 state machine used for implementing operations such as
16051 single-stepping the inferior.
16053 `show debug infrun'
16054 Displays the current state of GDB inferior debugging.
16056 `set debug lin-lwp'
16057 Turns on or off debugging messages from the Linux LWP debug
16060 `show debug lin-lwp'
16061 Show the current state of Linux LWP debugging messages.
16063 `set debug lin-lwp-async'
16064 Turns on or off debugging messages from the Linux LWP async debug
16067 `show debug lin-lwp-async'
16068 Show the current state of Linux LWP async debugging messages.
16070 `set debug observer'
16071 Turns on or off display of GDB observer debugging. This includes
16072 info such as the notification of observable events.
16074 `show debug observer'
16075 Displays the current state of observer debugging.
16077 `set debug overload'
16078 Turns on or off display of GDB C++ overload debugging info. This
16079 includes info such as ranking of functions, etc. The default is
16082 `show debug overload'
16083 Displays the current state of displaying GDB C++ overload
16087 Turns on or off the display of expression parser debugging output.
16088 Internally, this sets the `yydebug' variable in the expression
16089 parser. *Note Tracing Your Parser: (bison)Tracing, for details.
16090 The default is off.
16092 `show debug parser'
16093 Show the current state of expression parser debugging.
16096 Turns on or off display of reports on all packets sent back and
16097 forth across the serial line to the remote machine. The info is
16098 printed on the GDB standard output stream. The default is off.
16100 `show debug remote'
16101 Displays the state of display of remote packets.
16104 Turns on or off display of GDB serial debugging info. The default
16107 `show debug serial'
16108 Displays the current state of displaying GDB serial debugging info.
16110 `set debug solib-frv'
16111 Turns on or off debugging messages for FR-V shared-library code.
16113 `show debug solib-frv'
16114 Display the current state of FR-V shared-library code debugging
16118 Turns on or off display of GDB target debugging info. This info
16119 includes what is going on at the target level of GDB, as it
16120 happens. The default is 0. Set it to 1 to track events, and to 2
16121 to also track the value of large memory transfers. Changes to
16122 this flag do not take effect until the next time you connect to a
16123 target or use the `run' command.
16125 `show debug target'
16126 Displays the current state of displaying GDB target debugging info.
16128 `set debug timestamp'
16129 Turns on or off display of timestamps with GDB debugging info.
16130 When enabled, seconds and microseconds are displayed before each
16133 `show debug timestamp'
16134 Displays the current state of displaying timestamps with GDB
16138 Turns on or off display of GDB variable object debugging info. The
16142 Displays the current state of displaying GDB variable object
16146 Turns on or off debugging messages for built-in XML parsers.
16149 Displays the current state of XML debugging messages.
16152 File: gdb.info, Node: Other Misc Settings, Prev: Debugging Output, Up: Controlling GDB
16154 22.9 Other Miscellaneous Settings
16155 =================================
16157 `set interactive-mode'
16158 If `on', forces GDB to operate interactively. If `off', forces
16159 GDB to operate non-interactively, If `auto' (the default), GDB
16160 guesses which mode to use, based on whether the debugger was
16161 started in a terminal or not.
16163 In the vast majority of cases, the debugger should be able to guess
16164 correctly which mode should be used. But this setting can be
16165 useful in certain specific cases, such as running a MinGW GDB
16166 inside a cygwin window.
16168 `show interactive-mode'
16169 Displays whether the debugger is operating in interactive mode or
16173 File: gdb.info, Node: Extending GDB, Next: Interpreters, Prev: Controlling GDB, Up: Top
16178 GDB provides two mechanisms for extension. The first is based on
16179 composition of GDB commands, and the second is based on the Python
16180 scripting language.
16182 To facilitate the use of these extensions, GDB is capable of
16183 evaluating the contents of a file. When doing so, GDB can recognize
16184 which scripting language is being used by looking at the filename
16185 extension. Files with an unrecognized filename extension are always
16186 treated as a GDB Command Files. *Note Command files: Command Files.
16188 You can control how GDB evaluates these files with the following
16191 `set script-extension off'
16192 All scripts are always evaluated as GDB Command Files.
16194 `set script-extension soft'
16195 The debugger determines the scripting language based on filename
16196 extension. If this scripting language is supported, GDB evaluates
16197 the script using that language. Otherwise, it evaluates the file
16198 as a GDB Command File.
16200 `set script-extension strict'
16201 The debugger determines the scripting language based on filename
16202 extension, and evaluates the script using that language. If the
16203 language is not supported, then the evaluation fails.
16205 `show script-extension'
16206 Display the current value of the `script-extension' option.
16211 * Sequences:: Canned Sequences of Commands
16212 * Python:: Scripting GDB using Python
16215 File: gdb.info, Node: Sequences, Next: Python, Up: Extending GDB
16217 23.1 Canned Sequences of Commands
16218 =================================
16220 Aside from breakpoint commands (*note Breakpoint Command Lists: Break
16221 Commands.), GDB provides two ways to store sequences of commands for
16222 execution as a unit: user-defined commands and command files.
16226 * Define:: How to define your own commands
16227 * Hooks:: Hooks for user-defined commands
16228 * Command Files:: How to write scripts of commands to be stored in a file
16229 * Output:: Commands for controlled output
16232 File: gdb.info, Node: Define, Next: Hooks, Up: Sequences
16234 23.1.1 User-defined Commands
16235 ----------------------------
16237 A "user-defined command" is a sequence of GDB commands to which you
16238 assign a new name as a command. This is done with the `define'
16239 command. User commands may accept up to 10 arguments separated by
16240 whitespace. Arguments are accessed within the user command via
16241 `$arg0...$arg9'. A trivial example:
16244 print $arg0 + $arg1 + $arg2
16247 To execute the command use:
16251 This defines the command `adder', which prints the sum of its three
16252 arguments. Note the arguments are text substitutions, so they may
16253 reference variables, use complex expressions, or even perform inferior
16256 In addition, `$argc' may be used to find out how many arguments have
16257 been passed. This expands to a number in the range 0...10.
16261 print $arg0 + $arg1
16264 print $arg0 + $arg1 + $arg2
16268 `define COMMANDNAME'
16269 Define a command named COMMANDNAME. If there is already a command
16270 by that name, you are asked to confirm that you want to redefine
16271 it. COMMANDNAME may be a bare command name consisting of letters,
16272 numbers, dashes, and underscores. It may also start with any
16273 predefined prefix command. For example, `define target my-target'
16274 creates a user-defined `target my-target' command.
16276 The definition of the command is made up of other GDB command
16277 lines, which are given following the `define' command. The end of
16278 these commands is marked by a line containing `end'.
16280 `document COMMANDNAME'
16281 Document the user-defined command COMMANDNAME, so that it can be
16282 accessed by `help'. The command COMMANDNAME must already be
16283 defined. This command reads lines of documentation just as
16284 `define' reads the lines of the command definition, ending with
16285 `end'. After the `document' command is finished, `help' on command
16286 COMMANDNAME displays the documentation you have written.
16288 You may use the `document' command again to change the
16289 documentation of a command. Redefining the command with `define'
16290 does not change the documentation.
16293 Used inside a user-defined command, this tells GDB that this
16294 command should not be repeated when the user hits <RET> (*note
16295 repeat last command: Command Syntax.).
16297 `help user-defined'
16298 List all user-defined commands, with the first line of the
16299 documentation (if any) for each.
16302 `show user COMMANDNAME'
16303 Display the GDB commands used to define COMMANDNAME (but not its
16304 documentation). If no COMMANDNAME is given, display the
16305 definitions for all user-defined commands.
16307 `show max-user-call-depth'
16308 `set max-user-call-depth'
16309 The value of `max-user-call-depth' controls how many recursion
16310 levels are allowed in user-defined commands before GDB suspects an
16311 infinite recursion and aborts the command.
16313 In addition to the above commands, user-defined commands frequently
16314 use control flow commands, described in *note Command Files::.
16316 When user-defined commands are executed, the commands of the
16317 definition are not printed. An error in any command stops execution of
16318 the user-defined command.
16320 If used interactively, commands that would ask for confirmation
16321 proceed without asking when used inside a user-defined command. Many
16322 GDB commands that normally print messages to say what they are doing
16323 omit the messages when used in a user-defined command.
16326 File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences
16328 23.1.2 User-defined Command Hooks
16329 ---------------------------------
16331 You may define "hooks", which are a special kind of user-defined
16332 command. Whenever you run the command `foo', if the user-defined
16333 command `hook-foo' exists, it is executed (with no arguments) before
16336 A hook may also be defined which is run after the command you
16337 executed. Whenever you run the command `foo', if the user-defined
16338 command `hookpost-foo' exists, it is executed (with no arguments) after
16339 that command. Post-execution hooks may exist simultaneously with
16340 pre-execution hooks, for the same command.
16342 It is valid for a hook to call the command which it hooks. If this
16343 occurs, the hook is not re-executed, thereby avoiding infinite
16346 In addition, a pseudo-command, `stop' exists. Defining
16347 (`hook-stop') makes the associated commands execute every time
16348 execution stops in your program: before breakpoint commands are run,
16349 displays are printed, or the stack frame is printed.
16351 For example, to ignore `SIGALRM' signals while single-stepping, but
16352 treat them normally during normal execution, you could define:
16355 handle SIGALRM nopass
16359 handle SIGALRM pass
16362 define hook-continue
16363 handle SIGALRM pass
16366 As a further example, to hook at the beginning and end of the `echo'
16367 command, and to add extra text to the beginning and end of the message,
16374 define hookpost-echo
16378 (gdb) echo Hello World
16379 <<<---Hello World--->>>
16382 You can define a hook for any single-word command in GDB, but not
16383 for command aliases; you should define a hook for the basic command
16384 name, e.g. `backtrace' rather than `bt'. You can hook a multi-word
16385 command by adding `hook-' or `hookpost-' to the last word of the
16386 command, e.g. `define target hook-remote' to add a hook to `target
16389 If an error occurs during the execution of your hook, execution of
16390 GDB commands stops and GDB issues a prompt (before the command that you
16391 actually typed had a chance to run).
16393 If you try to define a hook which does not match any known command,
16394 you get a warning from the `define' command.
16397 File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences
16399 23.1.3 Command Files
16400 --------------------
16402 A command file for GDB is a text file made of lines that are GDB
16403 commands. Comments (lines starting with `#') may also be included. An
16404 empty line in a command file does nothing; it does not mean to repeat
16405 the last command, as it would from the terminal.
16407 You can request the execution of a command file with the `source'
16408 command. Note that the `source' command is also used to evaluate
16409 scripts that are not Command Files. The exact behavior can be
16410 configured using the `script-extension' setting. *Note Extending GDB:
16413 `source [`-v'] FILENAME'
16414 Execute the command file FILENAME.
16416 The lines in a command file are generally executed sequentially,
16417 unless the order of execution is changed by one of the _flow-control
16418 commands_ described below. The commands are not printed as they are
16419 executed. An error in any command terminates execution of the command
16420 file and control is returned to the console.
16422 GDB searches for FILENAME in the current directory and then on the
16423 search path (specified with the `directory' command).
16425 If `-v', for verbose mode, is given then GDB displays each command
16426 as it is executed. The option must be given before FILENAME, and is
16427 interpreted as part of the filename anywhere else.
16429 Commands that would ask for confirmation if used interactively
16430 proceed without asking when used in a command file. Many GDB commands
16431 that normally print messages to say what they are doing omit the
16432 messages when called from command files.
16434 GDB also accepts command input from standard input. In this mode,
16435 normal output goes to standard output and error output goes to standard
16436 error. Errors in a command file supplied on standard input do not
16437 terminate execution of the command file--execution continues with the
16440 gdb < cmds > log 2>&1
16442 (The syntax above will vary depending on the shell used.) This
16443 example will execute commands from the file `cmds'. All output and
16444 errors would be directed to `log'.
16446 Since commands stored on command files tend to be more general than
16447 commands typed interactively, they frequently need to deal with
16448 complicated situations, such as different or unexpected values of
16449 variables and symbols, changes in how the program being debugged is
16450 built, etc. GDB provides a set of flow-control commands to deal with
16451 these complexities. Using these commands, you can write complex
16452 scripts that loop over data structures, execute commands conditionally,
16457 This command allows to include in your script conditionally
16458 executed commands. The `if' command takes a single argument, which
16459 is an expression to evaluate. It is followed by a series of
16460 commands that are executed only if the expression is true (its
16461 value is nonzero). There can then optionally be an `else' line,
16462 followed by a series of commands that are only executed if the
16463 expression was false. The end of the list is marked by a line
16467 This command allows to write loops. Its syntax is similar to
16468 `if': the command takes a single argument, which is an expression
16469 to evaluate, and must be followed by the commands to execute, one
16470 per line, terminated by an `end'. These commands are called the
16471 "body" of the loop. The commands in the body of `while' are
16472 executed repeatedly as long as the expression evaluates to true.
16475 This command exits the `while' loop in whose body it is included.
16476 Execution of the script continues after that `while's `end' line.
16479 This command skips the execution of the rest of the body of
16480 commands in the `while' loop in whose body it is included.
16481 Execution branches to the beginning of the `while' loop, where it
16482 evaluates the controlling expression.
16485 Terminate the block of commands that are the body of `if', `else',
16486 or `while' flow-control commands.
16489 File: gdb.info, Node: Output, Prev: Command Files, Up: Sequences
16491 23.1.4 Commands for Controlled Output
16492 -------------------------------------
16494 During the execution of a command file or a user-defined command, normal
16495 GDB output is suppressed; the only output that appears is what is
16496 explicitly printed by the commands in the definition. This section
16497 describes three commands useful for generating exactly the output you
16501 Print TEXT. Nonprinting characters can be included in TEXT using
16502 C escape sequences, such as `\n' to print a newline. *No newline
16503 is printed unless you specify one.* In addition to the standard C
16504 escape sequences, a backslash followed by a space stands for a
16505 space. This is useful for displaying a string with spaces at the
16506 beginning or the end, since leading and trailing spaces are
16507 otherwise trimmed from all arguments. To print ` and foo = ', use
16508 the command `echo \ and foo = \ '.
16510 A backslash at the end of TEXT can be used, as in C, to continue
16511 the command onto subsequent lines. For example,
16513 echo This is some text\n\
16514 which is continued\n\
16515 onto several lines.\n
16517 produces the same output as
16519 echo This is some text\n
16520 echo which is continued\n
16521 echo onto several lines.\n
16523 `output EXPRESSION'
16524 Print the value of EXPRESSION and nothing but that value: no
16525 newlines, no `$NN = '. The value is not entered in the value
16526 history either. *Note Expressions: Expressions, for more
16527 information on expressions.
16529 `output/FMT EXPRESSION'
16530 Print the value of EXPRESSION in format FMT. You can use the same
16531 formats as for `print'. *Note Output Formats: Output Formats, for
16534 `printf TEMPLATE, EXPRESSIONS...'
16535 Print the values of one or more EXPRESSIONS under the control of
16536 the string TEMPLATE. To print several values, make EXPRESSIONS be
16537 a comma-separated list of individual expressions, which may be
16538 either numbers or pointers. Their values are printed as specified
16539 by TEMPLATE, exactly as a C program would do by executing the code
16542 printf (TEMPLATE, EXPRESSIONS...);
16544 As in `C' `printf', ordinary characters in TEMPLATE are printed
16545 verbatim, while "conversion specification" introduced by the `%'
16546 character cause subsequent EXPRESSIONS to be evaluated, their
16547 values converted and formatted according to type and style
16548 information encoded in the conversion specifications, and then
16551 For example, you can print two values in hex like this:
16553 printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
16555 `printf' supports all the standard `C' conversion specifications,
16556 including the flags and modifiers between the `%' character and
16557 the conversion letter, with the following exceptions:
16559 * The argument-ordering modifiers, such as `2$', are not
16562 * The modifier `*' is not supported for specifying precision or
16565 * The `'' flag (for separation of digits into groups according
16566 to `LC_NUMERIC'') is not supported.
16568 * The type modifiers `hh', `j', `t', and `z' are not supported.
16570 * The conversion letter `n' (as in `%n') is not supported.
16572 * The conversion letters `a' and `A' are not supported.
16574 Note that the `ll' type modifier is supported only if the
16575 underlying `C' implementation used to build GDB supports the `long
16576 long int' type, and the `L' type modifier is supported only if
16577 `long double' type is available.
16579 As in `C', `printf' supports simple backslash-escape sequences,
16580 such as `\n', `\t', `\\', `\"', `\a', and `\f', that consist of
16581 backslash followed by a single character. Octal and hexadecimal
16582 escape sequences are not supported.
16584 Additionally, `printf' supports conversion specifications for DFP
16585 ("Decimal Floating Point") types using the following length
16586 modifiers together with a floating point specifier. letters:
16588 * `H' for printing `Decimal32' types.
16590 * `D' for printing `Decimal64' types.
16592 * `DD' for printing `Decimal128' types.
16594 If the underlying `C' implementation used to build GDB has support
16595 for the three length modifiers for DFP types, other modifiers such
16596 as width and precision will also be available for GDB to use.
16598 In case there is no such `C' support, no additional modifiers will
16599 be available and the value will be printed in the standard way.
16601 Here's an example of printing DFP types using the above conversion
16603 printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl
16607 File: gdb.info, Node: Python, Prev: Sequences, Up: Extending GDB
16609 23.2 Scripting GDB using Python
16610 ===============================
16612 You can script GDB using the Python programming language
16613 (http://www.python.org/). This feature is available only if GDB was
16614 configured using `--with-python'.
16618 * Python Commands:: Accessing Python from GDB.
16619 * Python API:: Accessing GDB from Python.
16622 File: gdb.info, Node: Python Commands, Next: Python API, Up: Python
16624 23.2.1 Python Commands
16625 ----------------------
16627 GDB provides one command for accessing the Python interpreter, and one
16631 The `python' command can be used to evaluate Python code.
16633 If given an argument, the `python' command will evaluate the
16634 argument as a Python command. For example:
16636 (gdb) python print 23
16639 If you do not provide an argument to `python', it will act as a
16640 multi-line command, like `define'. In this case, the Python
16641 script is made up of subsequent command lines, given after the
16642 `python' command. This command list is terminated using a line
16643 containing `end'. For example:
16647 End with a line saying just "end".
16652 `maint set python print-stack'
16653 By default, GDB will print a stack trace when an error occurs in a
16654 Python script. This can be controlled using `maint set python
16655 print-stack': if `on', the default, then Python stack printing is
16656 enabled; if `off', then Python stack printing is disabled.
16658 It is also possible to execute a Python script from the GDB
16661 `source `script-name''
16662 The script name must end with `.py' and GDB must be configured to
16663 recognize the script language based on filename extension using
16664 the `script-extension' setting. *Note Extending GDB: Extending
16667 `python execfile ("script-name")'
16668 This method is based on the `execfile' Python built-in function,
16669 and thus is always available.
16672 File: gdb.info, Node: Python API, Prev: Python Commands, Up: Python
16677 At startup, GDB overrides Python's `sys.stdout' and `sys.stderr' to
16678 print using GDB's output-paging streams. A Python program which
16679 outputs to one of these streams may have its output interrupted by the
16680 user (*note Screen Size::). In this situation, a Python
16681 `KeyboardInterrupt' exception is thrown.
16685 * Basic Python:: Basic Python Functions.
16686 * Exception Handling::
16687 * Auto-loading:: Automatically loading Python code.
16688 * Values From Inferior::
16689 * Types In Python:: Python representation of types.
16690 * Pretty Printing:: Pretty-printing values.
16691 * Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
16692 * Commands In Python:: Implementing new commands in Python.
16693 * Functions In Python:: Writing new convenience functions.
16694 * Objfiles In Python:: Object files.
16695 * Frames In Python:: Acessing inferior stack frames from Python.
16696 * Lazy Strings In Python:: Python representation of lazy strings.
16699 File: gdb.info, Node: Basic Python, Next: Exception Handling, Up: Python API
16701 23.2.2.1 Basic Python
16702 .....................
16704 GDB introduces a new Python module, named `gdb'. All methods and
16705 classes added by GDB are placed in this module. GDB automatically
16706 `import's the `gdb' module for use in all scripts evaluated by the
16709 -- Function: execute command [from_tty]
16710 Evaluate COMMAND, a string, as a GDB CLI command. If a GDB
16711 exception happens while COMMAND runs, it is translated as
16712 described in *note Exception Handling: Exception Handling. If no
16713 exceptions occur, this function returns `None'.
16715 FROM_TTY specifies whether GDB ought to consider this command as
16716 having originated from the user invoking it interactively. It
16717 must be a boolean value. If omitted, it defaults to `False'.
16719 -- Function: parameter parameter
16720 Return the value of a GDB parameter. PARAMETER is a string naming
16721 the parameter to look up; PARAMETER may contain spaces if the
16722 parameter has a multi-part name. For example, `print object' is a
16723 valid parameter name.
16725 If the named parameter does not exist, this function throws a
16726 `RuntimeError'. Otherwise, the parameter's value is converted to
16727 a Python value of the appropriate type, and returned.
16729 -- Function: history number
16730 Return a value from GDB's value history (*note Value History::).
16731 NUMBER indicates which history element to return. If NUMBER is
16732 negative, then GDB will take its absolute value and count backward
16733 from the last element (i.e., the most recent element) to find the
16734 value to return. If NUMBER is zero, then GDB will return the most
16735 recent element. If the element specified by NUMBER doesn't exist
16736 in the value history, a `RuntimeError' exception will be raised.
16738 If no exception is raised, the return value is always an instance
16739 of `gdb.Value' (*note Values From Inferior::).
16741 -- Function: parse_and_eval expression
16742 Parse EXPRESSION as an expression in the current language,
16743 evaluate it, and return the result as a `gdb.Value'. EXPRESSION
16746 This function can be useful when implementing a new command (*note
16747 Commands In Python::), as it provides a way to parse the command's
16748 argument as an expression. It is also useful simply to compute
16749 values, for example, it is the only way to get the value of a
16750 convenience variable (*note Convenience Vars::) as a `gdb.Value'.
16752 -- Function: write string
16753 Print a string to GDB's paginated standard output stream. Writing
16754 to `sys.stdout' or `sys.stderr' will automatically call this
16758 Flush GDB's paginated standard output stream. Flushing
16759 `sys.stdout' or `sys.stderr' will automatically call this function.
16762 File: gdb.info, Node: Exception Handling, Next: Auto-loading, Prev: Basic Python, Up: Python API
16764 23.2.2.2 Exception Handling
16765 ...........................
16767 When executing the `python' command, Python exceptions uncaught within
16768 the Python code are translated to calls to GDB error-reporting
16769 mechanism. If the command that called `python' does not handle the
16770 error, GDB will terminate it and print an error message containing the
16771 Python exception name, the associated value, and the Python call stack
16772 backtrace at the point where the exception was raised. Example:
16774 (gdb) python print foo
16775 Traceback (most recent call last):
16776 File "<string>", line 1, in <module>
16777 NameError: name 'foo' is not defined
16779 GDB errors that happen in GDB commands invoked by Python code are
16780 converted to Python `RuntimeError' exceptions. User interrupt (via
16781 `C-c' or by typing `q' at a pagination prompt) is translated to a
16782 Python `KeyboardInterrupt' exception. If you catch these exceptions in
16783 your Python code, your exception handler will see `RuntimeError' or
16784 `KeyboardInterrupt' as the exception type, the GDB error message as its
16785 value, and the Python call stack backtrace at the Python statement
16786 closest to where the GDB error occured as the traceback.
16789 File: gdb.info, Node: Auto-loading, Next: Values From Inferior, Prev: Exception Handling, Up: Python API
16791 23.2.2.3 Auto-loading
16792 .....................
16794 When a new object file is read (for example, due to the `file' command,
16795 or because the inferior has loaded a shared library), GDB will look for
16796 a file named `OBJFILE-gdb.py', where OBJFILE is the object file's real
16797 name, formed by ensuring that the file name is absolute, following all
16798 symlinks, and resolving `.' and `..' components. If this file exists
16799 and is readable, GDB will evaluate it as a Python script.
16801 If this file does not exist, and if the parameter
16802 `debug-file-directory' is set (*note Separate Debug Files::), then GDB
16803 will use for its each separated directory component `component' the
16804 file named ``component'/REAL-NAME', where REAL-NAME is the object
16805 file's real name, as described above.
16807 Finally, if this file does not exist, then GDB will look for a file
16808 named `DATA-DIRECTORY/python/auto-load/REAL-NAME', where DATA-DIRECTORY
16809 is GDB's data directory (available via `show data-directory', *note
16810 Data Files::), and REAL-NAME is the object file's real name, as
16813 When reading an auto-loaded file, GDB sets the "current objfile".
16814 This is available via the `gdb.current_objfile' function (*note
16815 Objfiles In Python::). This can be useful for registering
16816 objfile-specific pretty-printers.
16818 The auto-loading feature is useful for supplying application-specific
16819 debugging commands and scripts. You can enable or disable this
16820 feature, and view its current state.
16822 `maint set python auto-load [yes|no]'
16823 Enable or disable the Python auto-loading feature.
16825 `show python auto-load'
16826 Show whether Python auto-loading is enabled or disabled.
16828 GDB does not track which files it has already auto-loaded. So, your
16829 `-gdb.py' file should take care to ensure that it may be evaluated
16830 multiple times without error.
16833 File: gdb.info, Node: Values From Inferior, Next: Types In Python, Prev: Auto-loading, Up: Python API
16835 23.2.2.4 Values From Inferior
16836 .............................
16838 GDB provides values it obtains from the inferior program in an object
16839 of type `gdb.Value'. GDB uses this object for its internal bookkeeping
16840 of the inferior's values, and for fetching values when necessary.
16842 Inferior values that are simple scalars can be used directly in
16843 Python expressions that are valid for the value's data type. Here's an
16844 example for an integer or floating-point value `some_val':
16848 As result of this, `bar' will also be a `gdb.Value' object whose values
16849 are of the same type as those of `some_val'.
16851 Inferior values that are structures or instances of some class can
16852 be accessed using the Python "dictionary syntax". For example, if
16853 `some_val' is a `gdb.Value' instance holding a structure, you can
16854 access its `foo' element with:
16856 bar = some_val['foo']
16858 Again, `bar' will also be a `gdb.Value' object.
16860 The following attributes are provided:
16862 -- Instance Variable of Value: address
16863 If this object is addressable, this read-only attribute holds
16864 a `gdb.Value' object representing the address. Otherwise,
16865 this attribute holds `None'.
16867 -- Instance Variable of Value: is_optimized_out
16868 This read-only boolean attribute is true if the compiler
16869 optimized out this value, thus it is not available for
16870 fetching from the inferior.
16872 -- Instance Variable of Value: type
16873 The type of this `gdb.Value'. The value of this attribute is
16874 a `gdb.Type' object.
16876 The following methods are provided:
16878 -- Method on Value: cast type
16879 Return a new instance of `gdb.Value' that is the result of
16880 casting this instance to the type described by TYPE, which
16881 must be a `gdb.Type' object. If the cast cannot be performed
16882 for some reason, this method throws an exception.
16884 -- Method on Value: dereference
16885 For pointer data types, this method returns a new `gdb.Value'
16886 object whose contents is the object pointed to by the
16887 pointer. For example, if `foo' is a C pointer to an `int',
16888 declared in your C program as
16892 then you can use the corresponding `gdb.Value' to access what
16893 `foo' points to like this:
16895 bar = foo.dereference ()
16897 The result `bar' will be a `gdb.Value' object holding the
16898 value pointed to by `foo'.
16900 -- Method on Value: string [encoding] [errors] [length]
16901 If this `gdb.Value' represents a string, then this method
16902 converts the contents to a Python string. Otherwise, this
16903 method will throw an exception.
16905 Strings are recognized in a language-specific way; whether a
16906 given `gdb.Value' represents a string is determined by the
16909 For C-like languages, a value is a string if it is a pointer
16910 to or an array of characters or ints. The string is assumed
16911 to be terminated by a zero of the appropriate width. However
16912 if the optional length argument is given, the string will be
16913 converted to that given length, ignoring any embedded zeros
16914 that the string may contain.
16916 If the optional ENCODING argument is given, it must be a
16917 string naming the encoding of the string in the `gdb.Value',
16918 such as `"ascii"', `"iso-8859-6"' or `"utf-8"'. It accepts
16919 the same encodings as the corresponding argument to Python's
16920 `string.decode' method, and the Python codec machinery will
16921 be used to convert the string. If ENCODING is not given, or
16922 if ENCODING is the empty string, then either the
16923 `target-charset' (*note Character Sets::) will be used, or a
16924 language-specific encoding will be used, if the current
16925 language is able to supply one.
16927 The optional ERRORS argument is the same as the corresponding
16928 argument to Python's `string.decode' method.
16930 If the optional LENGTH argument is given, the string will be
16931 fetched and converted to the given length.
16933 -- Method on Value: lazy_string [encoding] [length]
16934 If this `gdb.Value' represents a string, then this method
16935 converts the contents to a `gdb.LazyString' (*note Lazy
16936 Strings In Python::). Otherwise, this method will throw an
16939 If the optional ENCODING argument is given, it must be a
16940 string naming the encoding of the `gdb.LazyString'. Some
16941 examples are: `ascii', `iso-8859-6' or `utf-8'. If the
16942 ENCODING argument is an encoding that GDB does recognize, GDB
16943 will raise an error.
16945 When a lazy string is printed, the GDB encoding machinery is
16946 used to convert the string during printing. If the optional
16947 ENCODING argument is not provided, or is an empty string, GDB
16948 will automatically select the encoding most suitable for the
16949 string type. For further information on encoding in GDB
16950 please see *note Character Sets::.
16952 If the optional LENGTH argument is given, the string will be
16953 fetched and encoded to the length of characters specified. If
16954 the LENGTH argument is not provided, the string will be
16955 fetched and encoded until a null of appropriate width is
16959 File: gdb.info, Node: Types In Python, Next: Pretty Printing, Prev: Values From Inferior, Up: Python API
16961 23.2.2.5 Types In Python
16962 ........................
16964 GDB represents types from the inferior using the class `gdb.Type'.
16966 The following type-related functions are available in the `gdb'
16969 -- Function: lookup_type name [block]
16970 This function looks up a type by name. NAME is the name of the
16971 type to look up. It must be a string.
16973 Ordinarily, this function will return an instance of `gdb.Type'.
16974 If the named type cannot be found, it will throw an exception.
16976 An instance of `Type' has the following attributes:
16978 -- Instance Variable of Type: code
16979 The type code for this type. The type code will be one of the
16980 `TYPE_CODE_' constants defined below.
16982 -- Instance Variable of Type: sizeof
16983 The size of this type, in target `char' units. Usually, a
16984 target's `char' type will be an 8-bit byte. However, on some
16985 unusual platforms, this type may have a different size.
16987 -- Instance Variable of Type: tag
16988 The tag name for this type. The tag name is the name after
16989 `struct', `union', or `enum' in C and C++; not all languages
16990 have this concept. If this type has no tag name, then `None'
16993 The following methods are provided:
16995 -- Method on Type: fields
16996 For structure and union types, this method returns the
16997 fields. Range types have two fields, the minimum and maximum
16998 values. Enum types have one field per enum constant.
16999 Function and method types have one field per parameter. The
17000 base types of C++ classes are also represented as fields. If
17001 the type has no fields, or does not fit into one of these
17002 categories, an empty sequence will be returned.
17004 Each field is an object, with some pre-defined attributes:
17006 This attribute is not available for `static' fields (as
17007 in C++ or Java). For non-`static' fields, the value is
17008 the bit position of the field.
17011 The name of the field, or `None' for anonymous fields.
17014 This is `True' if the field is artificial, usually
17015 meaning that it was provided by the compiler and not the
17016 user. This attribute is always provided, and is `False'
17017 if the field is not artificial.
17020 This is `True' if the field represents a base class of a
17021 C++ structure. This attribute is always provided, and
17022 is `False' if the field is not a base class of the type
17023 that is the argument of `fields', or if that type was
17027 If the field is packed, or is a bitfield, then this will
17028 have a non-zero value, which is the size of the field in
17029 bits. Otherwise, this will be zero; in this case the
17030 field's size is given by its type.
17033 The type of the field. This is usually an instance of
17034 `Type', but it can be `None' in some situations.
17036 -- Method on Type: const
17037 Return a new `gdb.Type' object which represents a
17038 `const'-qualified variant of this type.
17040 -- Method on Type: volatile
17041 Return a new `gdb.Type' object which represents a
17042 `volatile'-qualified variant of this type.
17044 -- Method on Type: unqualified
17045 Return a new `gdb.Type' object which represents an unqualified
17046 variant of this type. That is, the result is neither `const'
17049 -- Method on Type: range
17050 Return a Python `Tuple' object that contains two elements: the
17051 low bound of the argument type and the high bound of that
17052 type. If the type does not have a range, GDB will raise a
17053 `RuntimeError' exception.
17055 -- Method on Type: reference
17056 Return a new `gdb.Type' object which represents a reference
17059 -- Method on Type: pointer
17060 Return a new `gdb.Type' object which represents a pointer to
17063 -- Method on Type: strip_typedefs
17064 Return a new `gdb.Type' that represents the real type, after
17065 removing all layers of typedefs.
17067 -- Method on Type: target
17068 Return a new `gdb.Type' object which represents the target
17071 For a pointer type, the target type is the type of the
17072 pointed-to object. For an array type (meaning C-like
17073 arrays), the target type is the type of the elements of the
17074 array. For a function or method type, the target type is the
17075 type of the return value. For a complex type, the target
17076 type is the type of the elements. For a typedef, the target
17077 type is the aliased type.
17079 If the type does not have a target, this method will throw an
17082 -- Method on Type: template_argument n
17083 If this `gdb.Type' is an instantiation of a template, this
17084 will return a new `gdb.Type' which represents the type of the
17085 Nth template argument.
17087 If this `gdb.Type' is not a template type, this will throw an
17088 exception. Ordinarily, only C++ code will have template
17091 NAME is searched for globally.
17093 Each type has a code, which indicates what category this type falls
17094 into. The available type categories are represented by constants
17095 defined in the `gdb' module:
17098 The type is a pointer.
17101 The type is an array.
17104 The type is a structure.
17107 The type is a union.
17110 The type is an enum.
17113 A bit flags type, used for things such as status registers.
17116 The type is a function.
17119 The type is an integer type.
17122 A floating point type.
17125 The special type `void'.
17131 A range type, that is, an integer type with bounds.
17134 A string type. Note that this is only used for certain languages
17135 with language-defined string types; C strings are not represented
17138 `TYPE_CODE_BITSTRING'
17142 An unknown or erroneous type.
17145 A method type, as found in C++ or Java.
17147 `TYPE_CODE_METHODPTR'
17148 A pointer-to-member-function.
17150 `TYPE_CODE_MEMBERPTR'
17151 A pointer-to-member.
17162 `TYPE_CODE_COMPLEX'
17163 A complex float type.
17165 `TYPE_CODE_TYPEDEF'
17166 A typedef to some other type.
17168 `TYPE_CODE_NAMESPACE'
17171 `TYPE_CODE_DECFLOAT'
17172 A decimal floating point type.
17174 `TYPE_CODE_INTERNAL_FUNCTION'
17175 A function internal to GDB. This is the type used to represent
17176 convenience functions.
17179 File: gdb.info, Node: Pretty Printing, Next: Selecting Pretty-Printers, Prev: Types In Python, Up: Python API
17181 23.2.2.6 Pretty Printing
17182 ........................
17184 GDB provides a mechanism to allow pretty-printing of values using
17185 Python code. The pretty-printer API allows application-specific code
17186 to greatly simplify the display of complex objects. This mechanism
17187 works for both MI and the CLI.
17189 For example, here is how a C++ `std::string' looks without a
17194 static npos = 4294967295,
17196 <std::allocator<char>> = {
17197 <__gnu_cxx::new_allocator<char>> = {<No data fields>}, <No data fields>},
17198 members of std::basic_string<char, std::char_traits<char>, std::allocator<char> >::_Alloc_hider:
17199 _M_p = 0x804a014 "abcd"
17203 After a pretty-printer for `std::string' has been installed, only
17204 the contents are printed:
17209 A pretty-printer is just an object that holds a value and implements
17210 a specific interface, defined here.
17212 -- Operation on pretty printer: children (self)
17213 GDB will call this method on a pretty-printer to compute the
17214 children of the pretty-printer's value.
17216 This method must return an object conforming to the Python iterator
17217 protocol. Each item returned by the iterator must be a tuple
17218 holding two elements. The first element is the "name" of the
17219 child; the second element is the child's value. The value can be
17220 any Python object which is convertible to a GDB value.
17222 This method is optional. If it does not exist, GDB will act as
17223 though the value has no children.
17225 -- Operation on pretty printer: display_hint (self)
17226 The CLI may call this method and use its result to change the
17227 formatting of a value. The result will also be supplied to an MI
17228 consumer as a `displayhint' attribute of the variable being
17231 This method is optional. If it does exist, this method must
17234 Some display hints are predefined by GDB:
17237 Indicate that the object being printed is "array-like". The
17238 CLI uses this to respect parameters such as `set print
17239 elements' and `set print array'.
17242 Indicate that the object being printed is "map-like", and
17243 that the children of this value can be assumed to alternate
17244 between keys and values.
17247 Indicate that the object being printed is "string-like". If
17248 the printer's `to_string' method returns a Python string of
17249 some kind, then GDB will call its internal language-specific
17250 string-printing function to format the string. For the CLI
17251 this means adding quotation marks, possibly escaping some
17252 characters, respecting `set print elements', and the like.
17254 -- Operation on pretty printer: to_string (self)
17255 GDB will call this method to display the string representation of
17256 the value passed to the object's constructor.
17258 When printing from the CLI, if the `to_string' method exists, then
17259 GDB will prepend its result to the values returned by `children'.
17260 Exactly how this formatting is done is dependent on the display
17261 hint, and may change as more hints are added. Also, depending on
17262 the print settings (*note Print Settings::), the CLI may print
17263 just the result of `to_string' in a stack trace, omitting the
17264 result of `children'.
17266 If this method returns a string, it is printed verbatim.
17268 Otherwise, if this method returns an instance of `gdb.Value', then
17269 GDB prints this value. This may result in a call to another
17272 If instead the method returns a Python value which is convertible
17273 to a `gdb.Value', then GDB performs the conversion and prints the
17274 resulting value. Again, this may result in a call to another
17275 pretty-printer. Python scalars (integers, floats, and booleans)
17276 and strings are convertible to `gdb.Value'; other types are not.
17278 If the result is not one of these types, an exception is raised.
17281 File: gdb.info, Node: Selecting Pretty-Printers, Next: Commands In Python, Prev: Pretty Printing, Up: Python API
17283 23.2.2.7 Selecting Pretty-Printers
17284 ..................................
17286 The Python list `gdb.pretty_printers' contains an array of functions
17287 that have been registered via addition as a pretty-printer. Each
17288 `gdb.Objfile' also contains a `pretty_printers' attribute.
17290 A function on one of these lists is passed a single `gdb.Value'
17291 argument and should return a pretty-printer object conforming to the
17292 interface definition above (*note Pretty Printing::). If a function
17293 cannot create a pretty-printer for the value, it should return `None'.
17295 GDB first checks the `pretty_printers' attribute of each
17296 `gdb.Objfile' and iteratively calls each function in the list for that
17297 `gdb.Objfile' until it receives a pretty-printer object. After these
17298 lists have been exhausted, it tries the global `gdb.pretty-printers'
17299 list, again calling each function until an object is returned.
17301 The order in which the objfiles are searched is not specified. For a
17302 given list, functions are always invoked from the head of the list, and
17303 iterated over sequentially until the end of the list, or a printer
17304 object is returned.
17306 Here is an example showing how a `std::string' printer might be
17309 class StdStringPrinter:
17310 "Print a std::string"
17312 def __init__ (self, val):
17315 def to_string (self):
17316 return self.val['_M_dataplus']['_M_p']
17318 def display_hint (self):
17321 And here is an example showing how a lookup function for the printer
17322 example above might be written.
17324 def str_lookup_function (val):
17326 lookup_tag = val.type.tag
17327 regex = re.compile ("^std::basic_string<char,.*>$")
17328 if lookup_tag == None:
17330 if regex.match (lookup_tag):
17331 return StdStringPrinter (val)
17335 The example lookup function extracts the value's type, and attempts
17336 to match it to a type that it can pretty-print. If it is a type the
17337 printer can pretty-print, it will return a printer object. If not, it
17340 We recommend that you put your core pretty-printers into a Python
17341 package. If your pretty-printers are for use with a library, we
17342 further recommend embedding a version number into the package name.
17343 This practice will enable GDB to load multiple versions of your
17344 pretty-printers at the same time, because they will have different
17347 You should write auto-loaded code (*note Auto-loading::) such that it
17348 can be evaluated multiple times without changing its meaning. An ideal
17349 auto-load file will consist solely of `import's of your printer
17350 modules, followed by a call to a register pretty-printers with the
17353 Taken as a whole, this approach will scale nicely to multiple
17354 inferiors, each potentially using a different library version.
17355 Embedding a version number in the Python package name will ensure that
17356 GDB is able to load both sets of printers simultaneously. Then,
17357 because the search for pretty-printers is done by objfile, and because
17358 your auto-loaded code took care to register your library's printers
17359 with a specific objfile, GDB will find the correct printers for the
17360 specific version of the library used by each inferior.
17362 To continue the `std::string' example (*note Pretty Printing::),
17363 this code might appear in `gdb.libstdcxx.v6':
17365 def register_printers (objfile):
17366 objfile.pretty_printers.add (str_lookup_function)
17368 And then the corresponding contents of the auto-load file would be:
17370 import gdb.libstdcxx.v6
17371 gdb.libstdcxx.v6.register_printers (gdb.current_objfile ())
17374 File: gdb.info, Node: Commands In Python, Next: Functions In Python, Prev: Selecting Pretty-Printers, Up: Python API
17376 23.2.2.8 Commands In Python
17377 ...........................
17379 You can implement new GDB CLI commands in Python. A CLI command is
17380 implemented using an instance of the `gdb.Command' class, most commonly
17383 -- Method on Command: __init__ name COMMAND_CLASS [COMPLETER_CLASS]
17385 The object initializer for `Command' registers the new command
17386 with GDB. This initializer is normally invoked from the subclass'
17387 own `__init__' method.
17389 NAME is the name of the command. If NAME consists of multiple
17390 words, then the initial words are looked for as prefix commands.
17391 In this case, if one of the prefix commands does not exist, an
17392 exception is raised.
17394 There is no support for multi-line commands.
17396 COMMAND_CLASS should be one of the `COMMAND_' constants defined
17397 below. This argument tells GDB how to categorize the new command
17398 in the help system.
17400 COMPLETER_CLASS is an optional argument. If given, it should be
17401 one of the `COMPLETE_' constants defined below. This argument
17402 tells GDB how to perform completion for this command. If not
17403 given, GDB will attempt to complete using the object's `complete'
17404 method (see below); if no such method is found, an error will
17405 occur when completion is attempted.
17407 PREFIX is an optional argument. If `True', then the new command
17408 is a prefix command; sub-commands of this command may be
17411 The help text for the new command is taken from the Python
17412 documentation string for the command's class, if there is one. If
17413 no documentation string is provided, the default value "This
17414 command is not documented." is used.
17416 -- Method on Command: dont_repeat
17417 By default, a GDB command is repeated when the user enters a blank
17418 line at the command prompt. A command can suppress this behavior
17419 by invoking the `dont_repeat' method. This is similar to the user
17420 command `dont-repeat', see *note dont-repeat: Define.
17422 -- Method on Command: invoke argument from_tty
17423 This method is called by GDB when this command is invoked.
17425 ARGUMENT is a string. It is the argument to the command, after
17426 leading and trailing whitespace has been stripped.
17428 FROM_TTY is a boolean argument. When true, this means that the
17429 command was entered by the user at the terminal; when false it
17430 means that the command came from elsewhere.
17432 If this method throws an exception, it is turned into a GDB
17433 `error' call. Otherwise, the return value is ignored.
17435 -- Method on Command: complete text word
17436 This method is called by GDB when the user attempts completion on
17437 this command. All forms of completion are handled by this method,
17438 that is, the <TAB> and <M-?> key bindings (*note Completion::),
17439 and the `complete' command (*note complete: Help.).
17441 The arguments TEXT and WORD are both strings. TEXT holds the
17442 complete command line up to the cursor's location. WORD holds the
17443 last word of the command line; this is computed using a
17444 word-breaking heuristic.
17446 The `complete' method can return several values:
17447 * If the return value is a sequence, the contents of the
17448 sequence are used as the completions. It is up to `complete'
17449 to ensure that the contents actually do complete the word. A
17450 zero-length sequence is allowed, it means that there were no
17451 completions available. Only string elements of the sequence
17452 are used; other elements in the sequence are ignored.
17454 * If the return value is one of the `COMPLETE_' constants
17455 defined below, then the corresponding GDB-internal completion
17456 function is invoked, and its result is used.
17458 * All other results are treated as though there were no
17459 available completions.
17461 When a new command is registered, it must be declared as a member of
17462 some general class of commands. This is used to classify top-level
17463 commands in the on-line help system; note that prefix commands are not
17464 listed under their own category but rather that of their top-level
17465 command. The available classifications are represented by constants
17466 defined in the `gdb' module:
17469 The command does not belong to any particular class. A command in
17470 this category will not be displayed in any of the help categories.
17473 The command is related to running the inferior. For example,
17474 `start', `step', and `continue' are in this category. Type `help
17475 running' at the GDB prompt to see a list of commands in this
17479 The command is related to data or variables. For example, `call',
17480 `find', and `print' are in this category. Type `help data' at the
17481 GDB prompt to see a list of commands in this category.
17484 The command has to do with manipulation of the stack. For example,
17485 `backtrace', `frame', and `return' are in this category. Type
17486 `help stack' at the GDB prompt to see a list of commands in this
17490 This class is used for file-related commands. For example,
17491 `file', `list' and `section' are in this category. Type `help
17492 files' at the GDB prompt to see a list of commands in this
17496 This should be used for "support facilities", generally meaning
17497 things that are useful to the user when interacting with GDB, but
17498 not related to the state of the inferior. For example, `help',
17499 `make', and `shell' are in this category. Type `help support' at
17500 the GDB prompt to see a list of commands in this category.
17503 The command is an `info'-related command, that is, related to the
17504 state of GDB itself. For example, `info', `macro', and `show' are
17505 in this category. Type `help status' at the GDB prompt to see a
17506 list of commands in this category.
17508 `COMMAND_BREAKPOINTS'
17509 The command has to do with breakpoints. For example, `break',
17510 `clear', and `delete' are in this category. Type `help
17511 breakpoints' at the GDB prompt to see a list of commands in this
17514 `COMMAND_TRACEPOINTS'
17515 The command has to do with tracepoints. For example, `trace',
17516 `actions', and `tfind' are in this category. Type `help
17517 tracepoints' at the GDB prompt to see a list of commands in this
17521 The command is only used in unusual circumstances, or is not of
17522 general interest to users. For example, `checkpoint', `fork', and
17523 `stop' are in this category. Type `help obscure' at the GDB
17524 prompt to see a list of commands in this category.
17526 `COMMAND_MAINTENANCE'
17527 The command is only useful to GDB maintainers. The `maintenance'
17528 and `flushregs' commands are in this category. Type `help
17529 internals' at the GDB prompt to see a list of commands in this
17532 A new command can use a predefined completion function, either by
17533 specifying it via an argument at initialization, or by returning it
17534 from the `complete' method. These predefined completion constants are
17535 all defined in the `gdb' module:
17538 This constant means that no completion should be done.
17540 `COMPLETE_FILENAME'
17541 This constant means that filename completion should be performed.
17543 `COMPLETE_LOCATION'
17544 This constant means that location completion should be done.
17545 *Note Specify Location::.
17548 This constant means that completion should examine GDB command
17552 This constant means that completion should be done using symbol
17553 names as the source.
17555 The following code snippet shows how a trivial CLI command can be
17556 implemented in Python:
17558 class HelloWorld (gdb.Command):
17559 """Greet the whole world."""
17561 def __init__ (self):
17562 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE)
17564 def invoke (self, arg, from_tty):
17565 print "Hello, World!"
17569 The last line instantiates the class, and is necessary to trigger the
17570 registration of the command with GDB. Depending on how the Python code
17571 is read into GDB, you may need to import the `gdb' module explicitly.
17574 File: gdb.info, Node: Functions In Python, Next: Objfiles In Python, Prev: Commands In Python, Up: Python API
17576 23.2.2.9 Writing new convenience functions
17577 ..........................................
17579 You can implement new convenience functions (*note Convenience Vars::)
17580 in Python. A convenience function is an instance of a subclass of the
17581 class `gdb.Function'.
17583 -- Method on Function: __init__ name
17584 The initializer for `Function' registers the new function with
17585 GDB. The argument NAME is the name of the function, a string.
17586 The function will be visible to the user as a convenience variable
17587 of type `internal function', whose name is the same as the given
17590 The documentation for the new function is taken from the
17591 documentation string for the new class.
17593 -- Method on Function: invoke *ARGS
17594 When a convenience function is evaluated, its arguments are
17595 converted to instances of `gdb.Value', and then the function's
17596 `invoke' method is called. Note that GDB does not predetermine
17597 the arity of convenience functions. Instead, all available
17598 arguments are passed to `invoke', following the standard Python
17599 calling convention. In particular, a convenience function can
17600 have default values for parameters without ill effect.
17602 The return value of this method is used as its value in the
17603 enclosing expression. If an ordinary Python value is returned, it
17604 is converted to a `gdb.Value' following the usual rules.
17606 The following code snippet shows how a trivial convenience function
17607 can be implemented in Python:
17609 class Greet (gdb.Function):
17610 """Return string to greet someone.
17611 Takes a name as argument."""
17613 def __init__ (self):
17614 super (Greet, self).__init__ ("greet")
17616 def invoke (self, name):
17617 return "Hello, %s!" % name.string ()
17621 The last line instantiates the class, and is necessary to trigger the
17622 registration of the function with GDB. Depending on how the Python
17623 code is read into GDB, you may need to import the `gdb' module
17627 File: gdb.info, Node: Objfiles In Python, Next: Frames In Python, Prev: Functions In Python, Up: Python API
17629 23.2.2.10 Objfiles In Python
17630 ............................
17632 GDB loads symbols for an inferior from various symbol-containing files
17633 (*note Files::). These include the primary executable file, any shared
17634 libraries used by the inferior, and any separate debug info files
17635 (*note Separate Debug Files::). GDB calls these symbol-containing
17638 The following objfile-related functions are available in the `gdb'
17641 -- Function: current_objfile
17642 When auto-loading a Python script (*note Auto-loading::), GDB sets
17643 the "current objfile" to the corresponding objfile. This function
17644 returns the current objfile. If there is no current objfile, this
17645 function returns `None'.
17647 -- Function: objfiles
17648 Return a sequence of all the objfiles current known to GDB. *Note
17649 Objfiles In Python::.
17651 Each objfile is represented by an instance of the `gdb.Objfile'
17654 -- Instance Variable of Objfile: filename
17655 The file name of the objfile as a string.
17657 -- Instance Variable of Objfile: pretty_printers
17658 The `pretty_printers' attribute is a list of functions. It is
17659 used to look up pretty-printers. A `Value' is passed to each
17660 function in order; if the function returns `None', then the search
17661 continues. Otherwise, the return value should be an object which
17662 is used to format the value. *Note Pretty Printing::, for more
17666 File: gdb.info, Node: Frames In Python, Next: Lazy Strings In Python, Prev: Objfiles In Python, Up: Python API
17668 23.2.2.11 Acessing inferior stack frames from Python.
17669 .....................................................
17671 When the debugged program stops, GDB is able to analyze its call stack
17672 (*note Stack frames: Frames.). The `gdb.Frame' class represents a
17673 frame in the stack. A `gdb.Frame' object is only valid while its
17674 corresponding frame exists in the inferior's stack. If you try to use
17675 an invalid frame object, GDB will throw a `RuntimeError' exception.
17677 Two `gdb.Frame' objects can be compared for equality with the `=='
17680 (gdb) python print gdb.newest_frame() == gdb.selected_frame ()
17683 The following frame-related functions are available in the `gdb'
17686 -- Function: selected_frame
17687 Return the selected frame object. (*note Selecting a Frame:
17690 -- Function: frame_stop_reason_string reason
17691 Return a string explaining the reason why GDB stopped unwinding
17692 frames, as expressed by the given REASON code (an integer, see the
17693 `unwind_stop_reason' method further down in this section).
17695 A `gdb.Frame' object has the following methods:
17697 -- Method on Frame: is_valid
17698 Returns true if the `gdb.Frame' object is valid, false if not.
17699 A frame object can become invalid if the frame it refers to
17700 doesn't exist anymore in the inferior. All `gdb.Frame'
17701 methods will throw an exception if it is invalid at the time
17702 the method is called.
17704 -- Method on Frame: name
17705 Returns the function name of the frame, or `None' if it can't
17708 -- Method on Frame: type
17709 Returns the type of the frame. The value can be one of
17710 `gdb.NORMAL_FRAME', `gdb.DUMMY_FRAME', `gdb.SIGTRAMP_FRAME'
17711 or `gdb.SENTINEL_FRAME'.
17713 -- Method on Frame: unwind_stop_reason
17714 Return an integer representing the reason why it's not
17715 possible to find more frames toward the outermost frame. Use
17716 `gdb.frame_stop_reason_string' to convert the value returned
17717 by this function to a string.
17719 -- Method on Frame: pc
17720 Returns the frame's resume address.
17722 -- Method on Frame: older
17723 Return the frame that called this frame.
17725 -- Method on Frame: newer
17726 Return the frame called by this frame.
17728 -- Method on Frame: read_var variable
17729 Return the value of the given variable in this frame.
17730 VARIABLE must be a string.
17733 File: gdb.info, Node: Lazy Strings In Python, Prev: Frames In Python, Up: Python API
17735 23.2.2.12 Python representation of lazy strings.
17736 ................................................
17738 A "lazy string" is a string whose contents is not retrieved or encoded
17739 until it is needed.
17741 A `gdb.LazyString' is represented in GDB as an `address' that points
17742 to a region of memory, an `encoding' that will be used to encode that
17743 region of memory, and a `length' to delimit the region of memory that
17744 represents the string. The difference between a `gdb.LazyString' and a
17745 string wrapped within a `gdb.Value' is that a `gdb.LazyString' will be
17746 treated differently by GDB when printing. A `gdb.LazyString' is
17747 retrieved and encoded during printing, while a `gdb.Value' wrapping a
17748 string is immediately retrieved and encoded on creation.
17750 A `gdb.LazyString' object has the following functions:
17752 -- Method on LazyString: value
17753 Convert the `gdb.LazyString' to a `gdb.Value'. This value will
17754 point to the string in memory, but will lose all the delayed
17755 retrieval, encoding and handling that GDB applies to a
17758 -- Instance Variable of LazyString: address
17759 This attribute holds the address of the string. This attribute is
17762 -- Instance Variable of LazyString: length
17763 This attribute holds the length of the string in characters. If
17764 the length is -1, then the string will be fetched and encoded up
17765 to the first null of appropriate width. This attribute is not
17768 -- Instance Variable of LazyString: encoding
17769 This attribute holds the encoding that will be applied to the
17770 string when the string is printed by GDB. If the encoding is not
17771 set, or contains an empty string, then GDB will select the most
17772 appropriate encoding when the string is printed. This attribute
17775 -- Instance Variable of LazyString: type
17776 This attribute holds the type that is represented by the lazy
17777 string's type. For a lazy string this will always be a pointer
17778 type. To resolve this to the lazy string's character type, use
17779 the type's `target' method. *Note Types In Python::. This
17780 attribute is not writable.
17783 File: gdb.info, Node: Interpreters, Next: TUI, Prev: Extending GDB, Up: Top
17785 24 Command Interpreters
17786 ***********************
17788 GDB supports multiple command interpreters, and some command
17789 infrastructure to allow users or user interface writers to switch
17790 between interpreters or run commands in other interpreters.
17792 GDB currently supports two command interpreters, the console
17793 interpreter (sometimes called the command-line interpreter or CLI) and
17794 the machine interface interpreter (or GDB/MI). This manual describes
17795 both of these interfaces in great detail.
17797 By default, GDB will start with the console interpreter. However,
17798 the user may choose to start GDB with another interpreter by specifying
17799 the `-i' or `--interpreter' startup options. Defined interpreters
17803 The traditional console or command-line interpreter. This is the
17804 most often used interpreter with GDB. With no interpreter
17805 specified at runtime, GDB will use this interpreter.
17808 The newest GDB/MI interface (currently `mi2'). Used primarily by
17809 programs wishing to use GDB as a backend for a debugger GUI or an
17810 IDE. For more information, see *note The GDB/MI Interface: GDB/MI.
17813 The current GDB/MI interface.
17816 The GDB/MI interface included in GDB 5.1, 5.2, and 5.3.
17819 The interpreter being used by GDB may not be dynamically switched at
17820 runtime. Although possible, this could lead to a very precarious
17821 situation. Consider an IDE using GDB/MI. If a user enters the command
17822 "interpreter-set console" in a console view, GDB would switch to using
17823 the console interpreter, rendering the IDE inoperable!
17825 Although you may only choose a single interpreter at startup, you
17826 may execute commands in any interpreter from the current interpreter
17827 using the appropriate command. If you are running the console
17828 interpreter, simply use the `interpreter-exec' command:
17830 interpreter-exec mi "-data-list-register-names"
17832 GDB/MI has a similar command, although it is only available in
17833 versions of GDB which support GDB/MI version 2 (or greater).
17836 File: gdb.info, Node: TUI, Next: Emacs, Prev: Interpreters, Up: Top
17838 25 GDB Text User Interface
17839 **************************
17843 * TUI Overview:: TUI overview
17844 * TUI Keys:: TUI key bindings
17845 * TUI Single Key Mode:: TUI single key mode
17846 * TUI Commands:: TUI-specific commands
17847 * TUI Configuration:: TUI configuration variables
17849 The GDB Text User Interface (TUI) is a terminal interface which uses
17850 the `curses' library to show the source file, the assembly output, the
17851 program registers and GDB commands in separate text windows. The TUI
17852 mode is supported only on platforms where a suitable version of the
17853 `curses' library is available.
17855 The TUI mode is enabled by default when you invoke GDB as either
17856 `gdbtui' or `gdb -tui'. You can also switch in and out of TUI mode
17857 while GDB runs by using various TUI commands and key bindings, such as
17858 `C-x C-a'. *Note TUI Key Bindings: TUI Keys.
17861 File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI
17866 In TUI mode, GDB can display several text windows:
17869 This window is the GDB command window with the GDB prompt and the
17870 GDB output. The GDB input is still managed using readline.
17873 The source window shows the source file of the program. The
17874 current line and active breakpoints are displayed in this window.
17877 The assembly window shows the disassembly output of the program.
17880 This window shows the processor registers. Registers are
17881 highlighted when their values change.
17883 The source and assembly windows show the current program position by
17884 highlighting the current line and marking it with a `>' marker.
17885 Breakpoints are indicated with two markers. The first marker indicates
17886 the breakpoint type:
17889 Breakpoint which was hit at least once.
17892 Breakpoint which was never hit.
17895 Hardware breakpoint which was hit at least once.
17898 Hardware breakpoint which was never hit.
17900 The second marker indicates whether the breakpoint is enabled or not:
17903 Breakpoint is enabled.
17906 Breakpoint is disabled.
17908 The source, assembly and register windows are updated when the
17909 current thread changes, when the frame changes, or when the program
17912 These windows are not all visible at the same time. The command
17913 window is always visible. The others can be arranged in several
17920 * source and assembly,
17922 * source and registers, or
17924 * assembly and registers.
17926 A status line above the command window shows the following
17930 Indicates the current GDB target. (*note Specifying a Debugging
17934 Gives the current process or thread number. When no process is
17935 being debugged, this field is set to `No process'.
17938 Gives the current function name for the selected frame. The name
17939 is demangled if demangling is turned on (*note Print Settings::).
17940 When there is no symbol corresponding to the current program
17941 counter, the string `??' is displayed.
17944 Indicates the current line number for the selected frame. When
17945 the current line number is not known, the string `??' is displayed.
17948 Indicates the current program counter address.
17951 File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview, Up: TUI
17953 25.2 TUI Key Bindings
17954 =====================
17956 The TUI installs several key bindings in the readline keymaps (*note
17957 Command Line Editing::). The following key bindings are installed for
17958 both TUI mode and the GDB standard mode.
17963 Enter or leave the TUI mode. When leaving the TUI mode, the
17964 curses window management stops and GDB operates using its standard
17965 mode, writing on the terminal directly. When reentering the TUI
17966 mode, control is given back to the curses windows. The screen is
17970 Use a TUI layout with only one window. The layout will either be
17971 `source' or `assembly'. When the TUI mode is not active, it will
17972 switch to the TUI mode.
17974 Think of this key binding as the Emacs `C-x 1' binding.
17977 Use a TUI layout with at least two windows. When the current
17978 layout already has two windows, the next layout with two windows
17979 is used. When a new layout is chosen, one window will always be
17980 common to the previous layout and the new one.
17982 Think of it as the Emacs `C-x 2' binding.
17985 Change the active window. The TUI associates several key bindings
17986 (like scrolling and arrow keys) with the active window. This
17987 command gives the focus to the next TUI window.
17989 Think of it as the Emacs `C-x o' binding.
17992 Switch in and out of the TUI SingleKey mode that binds single keys
17993 to GDB commands (*note TUI Single Key Mode::).
17995 The following key bindings only work in the TUI mode:
17998 Scroll the active window one page up.
18001 Scroll the active window one page down.
18004 Scroll the active window one line up.
18007 Scroll the active window one line down.
18010 Scroll the active window one column left.
18013 Scroll the active window one column right.
18016 Refresh the screen.
18018 Because the arrow keys scroll the active window in the TUI mode, they
18019 are not available for their normal use by readline unless the command
18020 window has the focus. When another window is active, you must use
18021 other readline key bindings such as `C-p', `C-n', `C-b' and `C-f' to
18022 control the command window.
18025 File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys, Up: TUI
18027 25.3 TUI Single Key Mode
18028 ========================
18030 The TUI also provides a "SingleKey" mode, which binds several
18031 frequently used GDB commands to single keys. Type `C-x s' to switch
18032 into this mode, where the following key bindings are used:
18047 exit the SingleKey mode.
18064 Other keys temporarily switch to the GDB command prompt. The key
18065 that was pressed is inserted in the editing buffer so that it is
18066 possible to type most GDB commands without interaction with the TUI
18067 SingleKey mode. Once the command is entered the TUI SingleKey mode is
18068 restored. The only way to permanently leave this mode is by typing `q'
18072 File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Single Key Mode, Up: TUI
18074 25.4 TUI-specific Commands
18075 ==========================
18077 The TUI has specific commands to control the text windows. These
18078 commands are always available, even when GDB is not in the TUI mode.
18079 When GDB is in the standard mode, most of these commands will
18080 automatically switch to the TUI mode.
18083 List and give the size of all displayed windows.
18086 Display the next layout.
18089 Display the previous layout.
18092 Display the source window only.
18095 Display the assembly window only.
18098 Display the source and assembly window.
18101 Display the register window together with the source or assembly
18105 Make the next window active for scrolling.
18108 Make the previous window active for scrolling.
18111 Make the source window active for scrolling.
18114 Make the assembly window active for scrolling.
18117 Make the register window active for scrolling.
18120 Make the command window active for scrolling.
18123 Refresh the screen. This is similar to typing `C-L'.
18126 Show the floating point registers in the register window.
18129 Show the general registers in the register window.
18132 Show the next register group. The list of register groups as well
18133 as their order is target specific. The predefined register groups
18134 are the following: `general', `float', `system', `vector', `all',
18138 Show the system registers in the register window.
18141 Update the source window and the current execution point.
18143 `winheight NAME +COUNT'
18144 `winheight NAME -COUNT'
18145 Change the height of the window NAME by COUNT lines. Positive
18146 counts increase the height, while negative counts decrease it.
18149 Set the width of tab stops to be NCHARS characters.
18152 File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI
18154 25.5 TUI Configuration Variables
18155 ================================
18157 Several configuration variables control the appearance of TUI windows.
18159 `set tui border-kind KIND'
18160 Select the border appearance for the source, assembly and register
18161 windows. The possible values are the following:
18163 Use a space character to draw the border.
18166 Use ASCII characters `+', `-' and `|' to draw the border.
18169 Use the Alternate Character Set to draw the border. The
18170 border is drawn using character line graphics if the terminal
18173 `set tui border-mode MODE'
18174 `set tui active-border-mode MODE'
18175 Select the display attributes for the borders of the inactive
18176 windows or the active window. The MODE can be one of the
18179 Use normal attributes to display the border.
18185 Use reverse video mode.
18188 Use half bright mode.
18191 Use half bright and standout mode.
18194 Use extra bright or bold mode.
18197 Use extra bright or bold and standout mode.
18200 File: gdb.info, Node: Emacs, Next: GDB/MI, Prev: TUI, Up: Top
18202 26 Using GDB under GNU Emacs
18203 ****************************
18205 A special interface allows you to use GNU Emacs to view (and edit) the
18206 source files for the program you are debugging with GDB.
18208 To use this interface, use the command `M-x gdb' in Emacs. Give the
18209 executable file you want to debug as an argument. This command starts
18210 GDB as a subprocess of Emacs, with input and output through a newly
18211 created Emacs buffer.
18213 Running GDB under Emacs can be just like running GDB normally except
18216 * All "terminal" input and output goes through an Emacs buffer,
18217 called the GUD buffer.
18219 This applies both to GDB commands and their output, and to the
18220 input and output done by the program you are debugging.
18222 This is useful because it means that you can copy the text of
18223 previous commands and input them again; you can even use parts of
18224 the output in this way.
18226 All the facilities of Emacs' Shell mode are available for
18227 interacting with your program. In particular, you can send
18228 signals the usual way--for example, `C-c C-c' for an interrupt,
18229 `C-c C-z' for a stop.
18231 * GDB displays source code through Emacs.
18233 Each time GDB displays a stack frame, Emacs automatically finds the
18234 source file for that frame and puts an arrow (`=>') at the left
18235 margin of the current line. Emacs uses a separate buffer for
18236 source display, and splits the screen to show both your GDB session
18239 Explicit GDB `list' or search commands still produce output as
18240 usual, but you probably have no reason to use them from Emacs.
18242 We call this "text command mode". Emacs 22.1, and later, also uses
18243 a graphical mode, enabled by default, which provides further buffers
18244 that can control the execution and describe the state of your program.
18245 *Note GDB Graphical Interface: (Emacs)GDB Graphical Interface.
18247 If you specify an absolute file name when prompted for the `M-x gdb'
18248 argument, then Emacs sets your current working directory to where your
18249 program resides. If you only specify the file name, then Emacs sets
18250 your current working directory to to the directory associated with the
18251 previous buffer. In this case, GDB may find your program by searching
18252 your environment's `PATH' variable, but on some operating systems it
18253 might not find the source. So, although the GDB input and output
18254 session proceeds normally, the auxiliary buffer does not display the
18255 current source and line of execution.
18257 The initial working directory of GDB is printed on the top line of
18258 the GUD buffer and this serves as a default for the commands that
18259 specify files for GDB to operate on. *Note Commands to Specify Files:
18262 By default, `M-x gdb' calls the program called `gdb'. If you need
18263 to call GDB by a different name (for example, if you keep several
18264 configurations around, with different names) you can customize the
18265 Emacs variable `gud-gdb-command-name' to run the one you want.
18267 In the GUD buffer, you can use these special Emacs commands in
18268 addition to the standard Shell mode commands:
18271 Describe the features of Emacs' GUD Mode.
18274 Execute to another source line, like the GDB `step' command; also
18275 update the display window to show the current file and location.
18278 Execute to next source line in this function, skipping all function
18279 calls, like the GDB `next' command. Then update the display window
18280 to show the current file and location.
18283 Execute one instruction, like the GDB `stepi' command; update
18284 display window accordingly.
18287 Execute until exit from the selected stack frame, like the GDB
18291 Continue execution of your program, like the GDB `continue'
18295 Go up the number of frames indicated by the numeric argument
18296 (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up'
18300 Go down the number of frames indicated by the numeric argument,
18301 like the GDB `down' command.
18303 In any source file, the Emacs command `C-x <SPC>' (`gud-break')
18304 tells GDB to set a breakpoint on the source line point is on.
18306 In text command mode, if you type `M-x speedbar', Emacs displays a
18307 separate frame which shows a backtrace when the GUD buffer is current.
18308 Move point to any frame in the stack and type <RET> to make it become
18309 the current frame and display the associated source in the source
18310 buffer. Alternatively, click `Mouse-2' to make the selected frame
18311 become the current one. In graphical mode, the speedbar displays watch
18314 If you accidentally delete the source-display buffer, an easy way to
18315 get it back is to type the command `f' in the GDB buffer, to request a
18316 frame display; when you run under Emacs, this recreates the source
18317 buffer if necessary to show you the context of the current frame.
18319 The source files displayed in Emacs are in ordinary Emacs buffers
18320 which are visiting the source files in the usual way. You can edit the
18321 files with these buffers if you wish; but keep in mind that GDB
18322 communicates with Emacs in terms of line numbers. If you add or delete
18323 lines from the text, the line numbers that GDB knows cease to
18324 correspond properly with the code.
18326 A more detailed description of Emacs' interaction with GDB is given
18327 in the Emacs manual (*note Debuggers: (Emacs)Debuggers.).
18330 File: gdb.info, Node: GDB/MI, Next: Annotations, Prev: Emacs, Up: Top
18332 27 The GDB/MI Interface
18333 ***********************
18335 Function and Purpose
18336 ====================
18338 GDB/MI is a line based machine oriented text interface to GDB and is
18339 activated by specifying using the `--interpreter' command line option
18340 (*note Mode Options::). It is specifically intended to support the
18341 development of systems which use the debugger as just one small
18342 component of a larger system.
18344 This chapter is a specification of the GDB/MI interface. It is
18345 written in the form of a reference manual.
18347 Note that GDB/MI is still under construction, so some of the
18348 features described below are incomplete and subject to change (*note
18349 GDB/MI Development and Front Ends: GDB/MI Development and Front Ends.).
18351 Notation and Terminology
18352 ========================
18354 This chapter uses the following notation:
18356 * `|' separates two alternatives.
18358 * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or
18361 * `( GROUP )*' means that GROUP inside the parentheses may repeat
18362 zero or more times.
18364 * `( GROUP )+' means that GROUP inside the parentheses may repeat
18367 * `"STRING"' means a literal STRING.
18371 * GDB/MI General Design::
18372 * GDB/MI Command Syntax::
18373 * GDB/MI Compatibility with CLI::
18374 * GDB/MI Development and Front Ends::
18375 * GDB/MI Output Records::
18376 * GDB/MI Simple Examples::
18377 * GDB/MI Command Description Format::
18378 * GDB/MI Breakpoint Commands::
18379 * GDB/MI Program Context::
18380 * GDB/MI Thread Commands::
18381 * GDB/MI Program Execution::
18382 * GDB/MI Stack Manipulation::
18383 * GDB/MI Variable Objects::
18384 * GDB/MI Data Manipulation::
18385 * GDB/MI Tracepoint Commands::
18386 * GDB/MI Symbol Query::
18387 * GDB/MI File Commands::
18388 * GDB/MI Target Manipulation::
18389 * GDB/MI File Transfer Commands::
18390 * GDB/MI Miscellaneous Commands::
18393 File: gdb.info, Node: GDB/MI General Design, Next: GDB/MI Command Syntax, Up: GDB/MI
18395 27.1 GDB/MI General Design
18396 ==========================
18398 Interaction of a GDB/MI frontend with GDB involves three
18399 parts--commands sent to GDB, responses to those commands and
18400 notifications. Each command results in exactly one response,
18401 indicating either successful completion of the command, or an error.
18402 For the commands that do not resume the target, the response contains
18403 the requested information. For the commands that resume the target, the
18404 response only indicates whether the target was successfully resumed.
18405 Notifications is the mechanism for reporting changes in the state of the
18406 target, or in GDB state, that cannot conveniently be associated with a
18407 command and reported as part of that command response.
18409 The important examples of notifications are:
18410 * Exec notifications. These are used to report changes in target
18411 state--when a target is resumed, or stopped. It would not be
18412 feasible to include this information in response of resuming
18413 commands, because one resume commands can result in multiple
18414 events in different threads. Also, quite some time may pass
18415 before any event happens in the target, while a frontend needs to
18416 know whether the resuming command itself was successfully executed.
18418 * Console output, and status notifications. Console output
18419 notifications are used to report output of CLI commands, as well as
18420 diagnostics for other commands. Status notifications are used to
18421 report the progress of a long-running operation. Naturally,
18422 including this information in command response would mean no
18423 output is produced until the command is finished, which is
18426 * General notifications. Commands may have various side effects on
18427 the GDB or target state beyond their official purpose. For
18428 example, a command may change the selected thread. Although such
18429 changes can be included in command response, using notification
18430 allows for more orthogonal frontend design.
18433 There's no guarantee that whenever an MI command reports an error,
18434 GDB or the target are in any specific state, and especially, the state
18435 is not reverted to the state before the MI command was processed.
18436 Therefore, whenever an MI command results in an error, we recommend
18437 that the frontend refreshes all the information shown in the user
18442 * Context management::
18443 * Asynchronous and non-stop modes::
18447 File: gdb.info, Node: Context management, Next: Asynchronous and non-stop modes, Up: GDB/MI General Design
18449 27.1.1 Context management
18450 -------------------------
18452 In most cases when GDB accesses the target, this access is done in
18453 context of a specific thread and frame (*note Frames::). Often, even
18454 when accessing global data, the target requires that a thread be
18455 specified. The CLI interface maintains the selected thread and frame,
18456 and supplies them to target on each command. This is convenient,
18457 because a command line user would not want to specify that information
18458 explicitly on each command, and because user interacts with GDB via a
18459 single terminal, so no confusion is possible as to what thread and
18460 frame are the current ones.
18462 In the case of MI, the concept of selected thread and frame is less
18463 useful. First, a frontend can easily remember this information itself.
18464 Second, a graphical frontend can have more than one window, each one
18465 used for debugging a different thread, and the frontend might want to
18466 access additional threads for internal purposes. This increases the
18467 risk that by relying on implicitly selected thread, the frontend may be
18468 operating on a wrong one. Therefore, each MI command should explicitly
18469 specify which thread and frame to operate on. To make it possible,
18470 each MI command accepts the `--thread' and `--frame' options, the value
18471 to each is GDB identifier for thread and frame to operate on.
18473 Usually, each top-level window in a frontend allows the user to
18474 select a thread and a frame, and remembers the user selection for
18475 further operations. However, in some cases GDB may suggest that the
18476 current thread be changed. For example, when stopping on a breakpoint
18477 it is reasonable to switch to the thread where breakpoint is hit. For
18478 another example, if the user issues the CLI `thread' command via the
18479 frontend, it is desirable to change the frontend's selected thread to
18480 the one specified by user. GDB communicates the suggestion to change
18481 current thread using the `=thread-selected' notification. No such
18482 notification is available for the selected frame at the moment.
18484 Note that historically, MI shares the selected thread with CLI, so
18485 frontends used the `-thread-select' to execute commands in the right
18486 context. However, getting this to work right is cumbersome. The
18487 simplest way is for frontend to emit `-thread-select' command before
18488 every command. This doubles the number of commands that need to be
18489 sent. The alternative approach is to suppress `-thread-select' if the
18490 selected thread in GDB is supposed to be identical to the thread the
18491 frontend wants to operate on. However, getting this optimization right
18492 can be tricky. In particular, if the frontend sends several commands
18493 to GDB, and one of the commands changes the selected thread, then the
18494 behaviour of subsequent commands will change. So, a frontend should
18495 either wait for response from such problematic commands, or explicitly
18496 add `-thread-select' for all subsequent commands. No frontend is known
18497 to do this exactly right, so it is suggested to just always pass the
18498 `--thread' and `--frame' options.
18501 File: gdb.info, Node: Asynchronous and non-stop modes, Next: Thread groups, Prev: Context management, Up: GDB/MI General Design
18503 27.1.2 Asynchronous command execution and non-stop mode
18504 -------------------------------------------------------
18506 On some targets, GDB is capable of processing MI commands even while
18507 the target is running. This is called "asynchronous command execution"
18508 (*note Background Execution::). The frontend may specify a preferrence
18509 for asynchronous execution using the `-gdb-set target-async 1' command,
18510 which should be emitted before either running the executable or
18511 attaching to the target. After the frontend has started the executable
18512 or attached to the target, it can find if asynchronous execution is
18513 enabled using the `-list-target-features' command.
18515 Even if GDB can accept a command while target is running, many
18516 commands that access the target do not work when the target is running.
18517 Therefore, asynchronous command execution is most useful when combined
18518 with non-stop mode (*note Non-Stop Mode::). Then, it is possible to
18519 examine the state of one thread, while other threads are running.
18521 When a given thread is running, MI commands that try to access the
18522 target in the context of that thread may not work, or may work only on
18523 some targets. In particular, commands that try to operate on thread's
18524 stack will not work, on any target. Commands that read memory, or
18525 modify breakpoints, may work or not work, depending on the target. Note
18526 that even commands that operate on global state, such as `print',
18527 `set', and breakpoint commands, still access the target in the context
18528 of a specific thread, so frontend should try to find a stopped thread
18529 and perform the operation on that thread (using the `--thread' option).
18531 Which commands will work in the context of a running thread is
18532 highly target dependent. However, the two commands `-exec-interrupt',
18533 to stop a thread, and `-thread-info', to find the state of a thread,
18537 File: gdb.info, Node: Thread groups, Prev: Asynchronous and non-stop modes, Up: GDB/MI General Design
18539 27.1.3 Thread groups
18540 --------------------
18542 GDB may be used to debug several processes at the same time. On some
18543 platfroms, GDB may support debugging of several hardware systems, each
18544 one having several cores with several different processes running on
18545 each core. This section describes the MI mechanism to support such
18546 debugging scenarios.
18548 The key observation is that regardless of the structure of the
18549 target, MI can have a global list of threads, because most commands that
18550 accept the `--thread' option do not need to know what process that
18551 thread belongs to. Therefore, it is not necessary to introduce neither
18552 additional `--process' option, nor an notion of the current process in
18553 the MI interface. The only strictly new feature that is required is
18554 the ability to find how the threads are grouped into processes.
18556 To allow the user to discover such grouping, and to support arbitrary
18557 hierarchy of machines/cores/processes, MI introduces the concept of a
18558 "thread group". Thread group is a collection of threads and other
18559 thread groups. A thread group always has a string identifier, a type,
18560 and may have additional attributes specific to the type. A new
18561 command, `-list-thread-groups', returns the list of top-level thread
18562 groups, which correspond to processes that GDB is debugging at the
18563 moment. By passing an identifier of a thread group to the
18564 `-list-thread-groups' command, it is possible to obtain the members of
18565 specific thread group.
18567 To allow the user to easily discover processes, and other objects, he
18568 wishes to debug, a concept of "available thread group" is introduced.
18569 Available thread group is an thread group that GDB is not debugging,
18570 but that can be attached to, using the `-target-attach' command. The
18571 list of available top-level thread groups can be obtained using
18572 `-list-thread-groups --available'. In general, the content of a thread
18573 group may be only retrieved only after attaching to that thread group.
18576 File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Prev: GDB/MI General Design, Up: GDB/MI
18578 27.2 GDB/MI Command Syntax
18579 ==========================
18583 * GDB/MI Input Syntax::
18584 * GDB/MI Output Syntax::
18587 File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax
18589 27.2.1 GDB/MI Input Syntax
18590 --------------------------
18593 `CLI-COMMAND | MI-COMMAND'
18596 `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB
18600 `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " "
18604 "any sequence of digits"
18607 `"-" PARAMETER [ " " PARAMETER ]'
18610 `NON-BLANK-SEQUENCE | C-STRING'
18613 _any of the operations described in this chapter_
18615 `NON-BLANK-SEQUENCE ==>'
18616 _anything, provided it doesn't contain special characters such as
18617 "-", NL, """ and of course " "_
18620 `""" SEVEN-BIT-ISO-C-STRING-CONTENT """'
18627 * The CLI commands are still handled by the MI interpreter; their
18628 output is described below.
18630 * The `TOKEN', when present, is passed back when the command
18633 * Some MI commands accept optional arguments as part of the parameter
18634 list. Each option is identified by a leading `-' (dash) and may be
18635 followed by an optional argument parameter. Options occur first
18636 in the parameter list and can be delimited from normal parameters
18637 using `--' (this is useful when some parameters begin with a dash).
18641 * We want easy access to the existing CLI syntax (for debugging).
18643 * We want it to be easy to spot a MI operation.
18646 File: gdb.info, Node: GDB/MI Output Syntax, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax
18648 27.2.2 GDB/MI Output Syntax
18649 ---------------------------
18651 The output from GDB/MI consists of zero or more out-of-band records
18652 followed, optionally, by a single result record. This result record is
18653 for the most recent command. The sequence of output records is
18654 terminated by `(gdb)'.
18656 If an input command was prefixed with a `TOKEN' then the
18657 corresponding output for that command will also be prefixed by that same
18661 `( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL'
18663 `RESULT-RECORD ==>'
18664 ` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL'
18666 `OUT-OF-BAND-RECORD ==>'
18667 `ASYNC-RECORD | STREAM-RECORD'
18670 `EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT'
18672 `EXEC-ASYNC-OUTPUT ==>'
18673 `[ TOKEN ] "*" ASYNC-OUTPUT'
18675 `STATUS-ASYNC-OUTPUT ==>'
18676 `[ TOKEN ] "+" ASYNC-OUTPUT'
18678 `NOTIFY-ASYNC-OUTPUT ==>'
18679 `[ TOKEN ] "=" ASYNC-OUTPUT'
18682 `ASYNC-CLASS ( "," RESULT )* NL'
18685 `"done" | "running" | "connected" | "error" | "exit"'
18688 `"stopped" | OTHERS' (where OTHERS will be added depending on the
18689 needs--this is still in development).
18692 ` VARIABLE "=" VALUE'
18698 ` CONST | TUPLE | LIST '
18704 ` "{}" | "{" RESULT ( "," RESULT )* "}" '
18707 ` "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )*
18710 `STREAM-RECORD ==>'
18711 `CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT'
18713 `CONSOLE-STREAM-OUTPUT ==>'
18716 `TARGET-STREAM-OUTPUT ==>'
18719 `LOG-STREAM-OUTPUT ==>'
18726 _any sequence of digits_.
18730 * All output sequences end in a single line containing a period.
18732 * The `TOKEN' is from the corresponding request. Note that for all
18733 async output, while the token is allowed by the grammar and may be
18734 output by future versions of GDB for select async output messages,
18735 it is generally omitted. Frontends should treat all async output
18736 as reporting general changes in the state of the target and there
18737 should be no need to associate async output to any prior command.
18739 * STATUS-ASYNC-OUTPUT contains on-going status information about the
18740 progress of a slow operation. It can be discarded. All status
18741 output is prefixed by `+'.
18743 * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target
18744 (stopped, started, disappeared). All async output is prefixed by
18747 * NOTIFY-ASYNC-OUTPUT contains supplementary information that the
18748 client should handle (e.g., a new breakpoint information). All
18749 notify output is prefixed by `='.
18751 * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in
18752 the console. It is the textual response to a CLI command. All
18753 the console output is prefixed by `~'.
18755 * TARGET-STREAM-OUTPUT is the output produced by the target program.
18756 All the target output is prefixed by `@'.
18758 * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for
18759 instance messages that should be displayed as part of an error
18760 log. All the log output is prefixed by `&'.
18762 * New GDB/MI commands should only output LISTS containing VALUES.
18765 *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details
18766 about the various output records.
18769 File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Development and Front Ends, Prev: GDB/MI Command Syntax, Up: GDB/MI
18771 27.3 GDB/MI Compatibility with CLI
18772 ==================================
18774 For the developers convenience CLI commands can be entered directly,
18775 but there may be some unexpected behaviour. For example, commands that
18776 query the user will behave as if the user replied yes, breakpoint
18777 command lists are not executed and some CLI commands, such as `if',
18778 `when' and `define', prompt for further input with `>', which is not
18781 This feature may be removed at some stage in the future and it is
18782 recommended that front ends use the `-interpreter-exec' command (*note
18783 -interpreter-exec::).
18786 File: gdb.info, Node: GDB/MI Development and Front Ends, Next: GDB/MI Output Records, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI
18788 27.4 GDB/MI Development and Front Ends
18789 ======================================
18791 The application which takes the MI output and presents the state of the
18792 program being debugged to the user is called a "front end".
18794 Although GDB/MI is still incomplete, it is currently being used by a
18795 variety of front ends to GDB. This makes it difficult to introduce new
18796 functionality without breaking existing usage. This section tries to
18797 minimize the problems by describing how the protocol might change.
18799 Some changes in MI need not break a carefully designed front end, and
18800 for these the MI version will remain unchanged. The following is a
18801 list of changes that may occur within one level, so front ends should
18802 parse MI output in a way that can handle them:
18804 * New MI commands may be added.
18806 * New fields may be added to the output of any MI command.
18808 * The range of values for fields with specified values, e.g.,
18809 `in_scope' (*note -var-update::) may be extended.
18812 If the changes are likely to break front ends, the MI version level
18813 will be increased by one. This will allow the front end to parse the
18814 output according to the MI version. Apart from mi0, new versions of
18815 GDB will not support old versions of MI and it will be the
18816 responsibility of the front end to work with the new one.
18818 The best way to avoid unexpected changes in MI that might break your
18819 front end is to make your project known to GDB developers and follow
18820 development on <gdb@sourceware.org> and <gdb-patches@sourceware.org>.
18823 File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI
18825 27.5 GDB/MI Output Records
18826 ==========================
18830 * GDB/MI Result Records::
18831 * GDB/MI Stream Records::
18832 * GDB/MI Async Records::
18833 * GDB/MI Frame Information::
18834 * GDB/MI Thread Information::
18837 File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records
18839 27.5.1 GDB/MI Result Records
18840 ----------------------------
18842 In addition to a number of out-of-band notifications, the response to a
18843 GDB/MI command includes one of the following result indications:
18845 `"^done" [ "," RESULTS ]'
18846 The synchronous operation was successful, `RESULTS' are the return
18850 This result record is equivalent to `^done'. Historically, it was
18851 output instead of `^done' if the command has resumed the target.
18852 This behaviour is maintained for backward compatibility, but all
18853 frontends should treat `^done' and `^running' identically and rely
18854 on the `*running' output record to determine which threads are
18858 GDB has connected to a remote target.
18860 `"^error" "," C-STRING'
18861 The operation failed. The `C-STRING' contains the corresponding
18865 GDB has terminated.
18869 File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Async Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records
18871 27.5.2 GDB/MI Stream Records
18872 ----------------------------
18874 GDB internally maintains a number of output streams: the console, the
18875 target, and the log. The output intended for each of these streams is
18876 funneled through the GDB/MI interface using "stream records".
18878 Each stream record begins with a unique "prefix character" which
18879 identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output
18880 Syntax.). In addition to the prefix, each stream record contains a
18881 `STRING-OUTPUT'. This is either raw text (with an implicit new line)
18882 or a quoted C string (which does not contain an implicit newline).
18884 `"~" STRING-OUTPUT'
18885 The console output stream contains text that should be displayed
18886 in the CLI console window. It contains the textual responses to
18889 `"@" STRING-OUTPUT'
18890 The target output stream contains any textual output from the
18891 running target. This is only present when GDB's event loop is
18892 truly asynchronous, which is currently only the case for remote
18895 `"&" STRING-OUTPUT'
18896 The log stream contains debugging messages being produced by GDB's
18900 File: gdb.info, Node: GDB/MI Async Records, Next: GDB/MI Frame Information, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records
18902 27.5.3 GDB/MI Async Records
18903 ---------------------------
18905 "Async" records are used to notify the GDB/MI client of additional
18906 changes that have occurred. Those changes can either be a consequence
18907 of GDB/MI commands (e.g., a breakpoint modified) or a result of target
18908 activity (e.g., target stopped).
18910 The following is the list of possible async records:
18912 `*running,thread-id="THREAD"'
18913 The target is now running. The THREAD field tells which specific
18914 thread is now running, and can be `all' if all threads are
18915 running. The frontend should assume that no interaction with a
18916 running thread is possible after this notification is produced.
18917 The frontend should not assume that this notification is output
18918 only once for any command. GDB may emit this notification several
18919 times, either for different threads, because it cannot resume all
18920 threads together, or even for a single thread, if the thread must
18921 be stepped though some code before letting it run freely.
18923 `*stopped,reason="REASON",thread-id="ID",stopped-threads="STOPPED",core="CORE"'
18924 The target has stopped. The REASON field can have one of the
18928 A breakpoint was reached.
18930 `watchpoint-trigger'
18931 A watchpoint was triggered.
18933 `read-watchpoint-trigger'
18934 A read watchpoint was triggered.
18936 `access-watchpoint-trigger'
18937 An access watchpoint was triggered.
18939 `function-finished'
18940 An -exec-finish or similar CLI command was accomplished.
18943 An -exec-until or similar CLI command was accomplished.
18946 A watchpoint has gone out of scope.
18948 `end-stepping-range'
18949 An -exec-next, -exec-next-instruction, -exec-step,
18950 -exec-step-instruction or similar CLI command was
18954 The inferior exited because of a signal.
18957 The inferior exited.
18960 The inferior exited normally.
18963 A signal was received by the inferior.
18965 The ID field identifies the thread that directly caused the stop -
18966 for example by hitting a breakpoint. Depending on whether all-stop
18967 mode is in effect (*note All-Stop Mode::), GDB may either stop all
18968 threads, or only the thread that directly triggered the stop. If
18969 all threads are stopped, the STOPPED field will have the value of
18970 `"all"'. Otherwise, the value of the STOPPED field will be a list
18971 of thread identifiers. Presently, this list will always include a
18972 single thread, but frontend should be prepared to see several
18973 threads in the list. The CORE field reports the processor core on
18974 which the stop event has happened. This field may be absent if
18975 such information is not available.
18977 `=thread-group-created,id="ID"'
18978 `=thread-group-exited,id="ID"'
18979 A thread thread group either was attached to, or has
18980 exited/detached from. The ID field contains the GDB identifier of
18983 `=thread-created,id="ID",group-id="GID"'
18984 `=thread-exited,id="ID",group-id="GID"'
18985 A thread either was created, or has exited. The ID field contains
18986 the GDB identifier of the thread. The GID field identifies the
18987 thread group this thread belongs to.
18989 `=thread-selected,id="ID"'
18990 Informs that the selected thread was changed as result of the last
18991 command. This notification is not emitted as result of
18992 `-thread-select' command but is emitted whenever an MI command
18993 that is not documented to change the selected thread actually
18994 changes it. In particular, invoking, directly or indirectly (via
18995 user-defined command), the CLI `thread' command, will generate
18998 We suggest that in response to this notification, front ends
18999 highlight the selected thread and cause subsequent commands to
19000 apply to that thread.
19002 `=library-loaded,...'
19003 Reports that a new library file was loaded by the program. This
19004 notification has 4 fields--ID, TARGET-NAME, HOST-NAME, and
19005 SYMBOLS-LOADED. The ID field is an opaque identifier of the
19006 library. For remote debugging case, TARGET-NAME and HOST-NAME
19007 fields give the name of the library file on the target, and on the
19008 host respectively. For native debugging, both those fields have
19009 the same value. The SYMBOLS-LOADED field reports if the debug
19010 symbols for this library are loaded.
19012 `=library-unloaded,...'
19013 Reports that a library was unloaded by the program. This
19014 notification has 3 fields--ID, TARGET-NAME and HOST-NAME with the
19015 same meaning as for the `=library-loaded' notification
19019 File: gdb.info, Node: GDB/MI Frame Information, Next: GDB/MI Thread Information, Prev: GDB/MI Async Records, Up: GDB/MI Output Records
19021 27.5.4 GDB/MI Frame Information
19022 -------------------------------
19024 Response from many MI commands includes an information about stack
19025 frame. This information is a tuple that may have the following fields:
19028 The level of the stack frame. The innermost frame has the level of
19029 zero. This field is always present.
19032 The name of the function corresponding to the frame. This field
19033 may be absent if GDB is unable to determine the function name.
19036 The code address for the frame. This field is always present.
19039 The name of the source files that correspond to the frame's code
19040 address. This field may be absent.
19043 The source line corresponding to the frames' code address. This
19044 field may be absent.
19047 The name of the binary file (either executable or shared library)
19048 the corresponds to the frame's code address. This field may be
19053 File: gdb.info, Node: GDB/MI Thread Information, Prev: GDB/MI Frame Information, Up: GDB/MI Output Records
19055 27.5.5 GDB/MI Thread Information
19056 --------------------------------
19058 Whenever GDB has to report an information about a thread, it uses a
19059 tuple with the following fields:
19062 The numeric id assigned to the thread by GDB. This field is
19066 Target-specific string identifying the thread. This field is
19070 Additional information about the thread provided by the target.
19071 It is supposed to be human-readable and not interpreted by the
19072 frontend. This field is optional.
19075 Either `stopped' or `running', depending on whether the thread is
19076 presently running. This field is always present.
19079 The value of this field is an integer number of the processor core
19080 the thread was last seen on. This field is optional.
19083 File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI
19085 27.6 Simple Examples of GDB/MI Interaction
19086 ==========================================
19088 This subsection presents several simple examples of interaction using
19089 the GDB/MI interface. In these examples, `->' means that the following
19090 line is passed to GDB/MI as input, while `<-' means the output received
19093 Note the line breaks shown in the examples are here only for
19094 readability, they don't appear in the real output.
19096 Setting a Breakpoint
19097 --------------------
19099 Setting a breakpoint generates synchronous output which contains
19100 detailed information of the breakpoint.
19102 -> -break-insert main
19103 <- ^done,bkpt={number="1",type="breakpoint",disp="keep",
19104 enabled="y",addr="0x08048564",func="main",file="myprog.c",
19105 fullname="/home/nickrob/myprog.c",line="68",times="0"}
19111 Program execution generates asynchronous records and MI gives the
19112 reason that execution stopped.
19117 <- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
19118 frame={addr="0x08048564",func="main",
19119 args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}],
19120 file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"}
19125 <- *stopped,reason="exited-normally"
19131 Quitting GDB just prints the result class `^exit'.
19137 Please note that `^exit' is printed immediately, but it might take
19138 some time for GDB to actually exit. During that time, GDB performs
19139 necessary cleanups, including killing programs being debugged or
19140 disconnecting from debug hardware, so the frontend should wait till GDB
19141 exits and should only forcibly kill GDB if it fails to exit in
19147 Here's what happens if you pass a non-existent command:
19150 <- ^error,msg="Undefined MI command: rubbish"
19154 File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI
19156 27.7 GDB/MI Command Description Format
19157 ======================================
19159 The remaining sections describe blocks of commands. Each block of
19160 commands is laid out in a fashion similar to this section.
19165 The motivation for this collection of commands.
19170 A brief introduction to this collection of commands as a whole.
19175 For each command in the block, the following is described:
19188 The corresponding GDB CLI command(s), if any.
19193 Example(s) formatted for readability. Some of the described commands
19194 have not been implemented yet and these are labeled N.A. (not
19198 File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Command Description Format, Up: GDB/MI
19200 27.8 GDB/MI Breakpoint Commands
19201 ===============================
19203 This section documents GDB/MI commands for manipulating breakpoints.
19205 The `-break-after' Command
19206 --------------------------
19211 -break-after NUMBER COUNT
19213 The breakpoint number NUMBER is not in effect until it has been hit
19214 COUNT times. To see how this is reflected in the output of the
19215 `-break-list' command, see the description of the `-break-list' command
19221 The corresponding GDB command is `ignore'.
19228 ^done,bkpt={number="1",type="breakpoint",disp="keep",
19229 enabled="y",addr="0x000100d0",func="main",file="hello.c",
19230 fullname="/home/foo/hello.c",line="5",times="0"}
19237 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
19238 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
19239 {width="14",alignment="-1",col_name="type",colhdr="Type"},
19240 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
19241 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
19242 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
19243 {width="40",alignment="2",col_name="what",colhdr="What"}],
19244 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
19245 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
19246 line="5",times="0",ignore="3"}]}
19249 The `-break-commands' Command
19250 -----------------------------
19255 -break-commands NUMBER [ COMMAND1 ... COMMANDN ]
19257 Specifies the CLI commands that should be executed when breakpoint
19258 NUMBER is hit. The parameters COMMAND1 to COMMANDN are the commands.
19259 If no command is specified, any previously-set commands are cleared.
19260 *Note Break Commands::. Typical use of this functionality is tracing a
19261 program, that is, printing of values of some variables whenever
19262 breakpoint is hit and then continuing.
19267 The corresponding GDB command is `commands'.
19274 ^done,bkpt={number="1",type="breakpoint",disp="keep",
19275 enabled="y",addr="0x000100d0",func="main",file="hello.c",
19276 fullname="/home/foo/hello.c",line="5",times="0"}
19278 -break-commands 1 "print v" "continue"
19282 The `-break-condition' Command
19283 ------------------------------
19288 -break-condition NUMBER EXPR
19290 Breakpoint NUMBER will stop the program only if the condition in
19291 EXPR is true. The condition becomes part of the `-break-list' output
19292 (see the description of the `-break-list' command below).
19297 The corresponding GDB command is `condition'.
19303 -break-condition 1 1
19307 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
19308 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
19309 {width="14",alignment="-1",col_name="type",colhdr="Type"},
19310 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
19311 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
19312 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
19313 {width="40",alignment="2",col_name="what",colhdr="What"}],
19314 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
19315 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
19316 line="5",cond="1",times="0",ignore="3"}]}
19319 The `-break-delete' Command
19320 ---------------------------
19325 -break-delete ( BREAKPOINT )+
19327 Delete the breakpoint(s) whose number(s) are specified in the
19328 argument list. This is obviously reflected in the breakpoint list.
19333 The corresponding GDB command is `delete'.
19343 ^done,BreakpointTable={nr_rows="0",nr_cols="6",
19344 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
19345 {width="14",alignment="-1",col_name="type",colhdr="Type"},
19346 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
19347 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
19348 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
19349 {width="40",alignment="2",col_name="what",colhdr="What"}],
19353 The `-break-disable' Command
19354 ----------------------------
19359 -break-disable ( BREAKPOINT )+
19361 Disable the named BREAKPOINT(s). The field `enabled' in the break
19362 list is now set to `n' for the named BREAKPOINT(s).
19367 The corresponding GDB command is `disable'.
19377 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
19378 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
19379 {width="14",alignment="-1",col_name="type",colhdr="Type"},
19380 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
19381 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
19382 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
19383 {width="40",alignment="2",col_name="what",colhdr="What"}],
19384 body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n",
19385 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
19386 line="5",times="0"}]}
19389 The `-break-enable' Command
19390 ---------------------------
19395 -break-enable ( BREAKPOINT )+
19397 Enable (previously disabled) BREAKPOINT(s).
19402 The corresponding GDB command is `enable'.
19412 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
19413 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
19414 {width="14",alignment="-1",col_name="type",colhdr="Type"},
19415 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
19416 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
19417 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
19418 {width="40",alignment="2",col_name="what",colhdr="What"}],
19419 body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
19420 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
19421 line="5",times="0"}]}
19424 The `-break-info' Command
19425 -------------------------
19430 -break-info BREAKPOINT
19432 Get information about a single breakpoint.
19437 The corresponding GDB command is `info break BREAKPOINT'.
19444 The `-break-insert' Command
19445 ---------------------------
19450 -break-insert [ -t ] [ -h ] [ -f ] [ -d ]
19451 [ -c CONDITION ] [ -i IGNORE-COUNT ]
19452 [ -p THREAD ] [ LOCATION ]
19454 If specified, LOCATION, can be one of:
19460 * filename:function
19464 The possible optional parameters of this command are:
19467 Insert a temporary breakpoint.
19470 Insert a hardware breakpoint.
19473 Make the breakpoint conditional on CONDITION.
19476 Initialize the IGNORE-COUNT.
19479 If LOCATION cannot be parsed (for example if it refers to unknown
19480 files or functions), create a pending breakpoint. Without this
19481 flag, GDB will report an error, and won't create a breakpoint, if
19482 LOCATION cannot be parsed.
19485 Create a disabled breakpoint.
19490 The result is in the form:
19492 ^done,bkpt={number="NUMBER",type="TYPE",disp="del"|"keep",
19493 enabled="y"|"n",addr="HEX",func="FUNCNAME",file="FILENAME",
19494 fullname="FULL_FILENAME",line="LINENO",[thread="THREADNO,]
19497 where NUMBER is the GDB number for this breakpoint, FUNCNAME is the
19498 name of the function where the breakpoint was inserted, FILENAME is the
19499 name of the source file which contains this function, LINENO is the
19500 source line number within that file and TIMES the number of times that
19501 the breakpoint has been hit (always 0 for -break-insert but may be
19502 greater for -break-info or -break-list which use the same output).
19504 Note: this format is open to change.
19509 The corresponding GDB commands are `break', `tbreak', `hbreak',
19510 `thbreak', and `rbreak'.
19517 ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",
19518 fullname="/home/foo/recursive2.c,line="4",times="0"}
19520 -break-insert -t foo
19521 ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",
19522 fullname="/home/foo/recursive2.c,line="11",times="0"}
19525 ^done,BreakpointTable={nr_rows="2",nr_cols="6",
19526 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
19527 {width="14",alignment="-1",col_name="type",colhdr="Type"},
19528 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
19529 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
19530 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
19531 {width="40",alignment="2",col_name="what",colhdr="What"}],
19532 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
19533 addr="0x0001072c", func="main",file="recursive2.c",
19534 fullname="/home/foo/recursive2.c,"line="4",times="0"},
19535 bkpt={number="2",type="breakpoint",disp="del",enabled="y",
19536 addr="0x00010774",func="foo",file="recursive2.c",
19537 fullname="/home/foo/recursive2.c",line="11",times="0"}]}
19539 -break-insert -r foo.*
19540 ~int foo(int, int);
19541 ^done,bkpt={number="3",addr="0x00010774",file="recursive2.c,
19542 "fullname="/home/foo/recursive2.c",line="11",times="0"}
19545 The `-break-list' Command
19546 -------------------------
19553 Displays the list of inserted breakpoints, showing the following
19557 number of the breakpoint
19560 type of the breakpoint: `breakpoint' or `watchpoint'
19563 should the breakpoint be deleted or disabled when it is hit: `keep'
19567 is the breakpoint enabled or no: `y' or `n'
19570 memory location at which the breakpoint is set
19573 logical location of the breakpoint, expressed by function name,
19574 file name, line number
19577 number of times the breakpoint has been hit
19579 If there are no breakpoints or watchpoints, the `BreakpointTable'
19580 `body' field is an empty list.
19585 The corresponding GDB command is `info break'.
19592 ^done,BreakpointTable={nr_rows="2",nr_cols="6",
19593 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
19594 {width="14",alignment="-1",col_name="type",colhdr="Type"},
19595 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
19596 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
19597 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
19598 {width="40",alignment="2",col_name="what",colhdr="What"}],
19599 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
19600 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"},
19601 bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
19602 addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
19603 line="13",times="0"}]}
19606 Here's an example of the result when there are no breakpoints:
19610 ^done,BreakpointTable={nr_rows="0",nr_cols="6",
19611 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
19612 {width="14",alignment="-1",col_name="type",colhdr="Type"},
19613 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
19614 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
19615 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
19616 {width="40",alignment="2",col_name="what",colhdr="What"}],
19620 The `-break-watch' Command
19621 --------------------------
19626 -break-watch [ -a | -r ]
19628 Create a watchpoint. With the `-a' option it will create an
19629 "access" watchpoint, i.e., a watchpoint that triggers either on a read
19630 from or on a write to the memory location. With the `-r' option, the
19631 watchpoint created is a "read" watchpoint, i.e., it will trigger only
19632 when the memory location is accessed for reading. Without either of
19633 the options, the watchpoint created is a regular watchpoint, i.e., it
19634 will trigger when the memory location is accessed for writing. *Note
19635 Setting Watchpoints: Set Watchpoints.
19637 Note that `-break-list' will report a single list of watchpoints and
19638 breakpoints inserted.
19643 The corresponding GDB commands are `watch', `awatch', and `rwatch'.
19648 Setting a watchpoint on a variable in the `main' function:
19652 ^done,wpt={number="2",exp="x"}
19657 *stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"},
19658 value={old="-268439212",new="55"},
19659 frame={func="main",args=[],file="recursive2.c",
19660 fullname="/home/foo/bar/recursive2.c",line="5"}
19663 Setting a watchpoint on a variable local to a function. GDB will
19664 stop the program execution twice: first for the variable changing
19665 value, then for the watchpoint going out of scope.
19669 ^done,wpt={number="5",exp="C"}
19674 *stopped,reason="watchpoint-trigger",
19675 wpt={number="5",exp="C"},value={old="-276895068",new="3"},
19676 frame={func="callee4",args=[],
19677 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
19678 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
19683 *stopped,reason="watchpoint-scope",wpnum="5",
19684 frame={func="callee3",args=[{name="strarg",
19685 value="0x11940 \"A string argument.\""}],
19686 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
19687 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
19690 Listing breakpoints and watchpoints, at different points in the
19691 program execution. Note that once the watchpoint goes out of scope, it
19696 ^done,wpt={number="2",exp="C"}
19699 ^done,BreakpointTable={nr_rows="2",nr_cols="6",
19700 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
19701 {width="14",alignment="-1",col_name="type",colhdr="Type"},
19702 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
19703 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
19704 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
19705 {width="40",alignment="2",col_name="what",colhdr="What"}],
19706 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
19707 addr="0x00010734",func="callee4",
19708 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
19709 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"},
19710 bkpt={number="2",type="watchpoint",disp="keep",
19711 enabled="y",addr="",what="C",times="0"}]}
19716 *stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"},
19717 value={old="-276895068",new="3"},
19718 frame={func="callee4",args=[],
19719 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
19720 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
19723 ^done,BreakpointTable={nr_rows="2",nr_cols="6",
19724 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
19725 {width="14",alignment="-1",col_name="type",colhdr="Type"},
19726 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
19727 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
19728 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
19729 {width="40",alignment="2",col_name="what",colhdr="What"}],
19730 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
19731 addr="0x00010734",func="callee4",
19732 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
19733 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"},
19734 bkpt={number="2",type="watchpoint",disp="keep",
19735 enabled="y",addr="",what="C",times="-5"}]}
19739 ^done,reason="watchpoint-scope",wpnum="2",
19740 frame={func="callee3",args=[{name="strarg",
19741 value="0x11940 \"A string argument.\""}],
19742 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
19743 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
19746 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
19747 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
19748 {width="14",alignment="-1",col_name="type",colhdr="Type"},
19749 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
19750 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
19751 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
19752 {width="40",alignment="2",col_name="what",colhdr="What"}],
19753 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
19754 addr="0x00010734",func="callee4",
19755 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
19756 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
19761 File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI
19763 27.9 GDB/MI Program Context
19764 ============================
19766 The `-exec-arguments' Command
19767 -----------------------------
19772 -exec-arguments ARGS
19774 Set the inferior program arguments, to be used in the next
19780 The corresponding GDB command is `set args'.
19786 -exec-arguments -v word
19790 The `-environment-cd' Command
19791 -----------------------------
19796 -environment-cd PATHDIR
19798 Set GDB's working directory.
19803 The corresponding GDB command is `cd'.
19809 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
19813 The `-environment-directory' Command
19814 ------------------------------------
19819 -environment-directory [ -r ] [ PATHDIR ]+
19821 Add directories PATHDIR to beginning of search path for source files.
19822 If the `-r' option is used, the search path is reset to the default
19823 search path. If directories PATHDIR are supplied in addition to the
19824 `-r' option, the search path is first reset and then addition occurs as
19825 normal. Multiple directories may be specified, separated by blanks.
19826 Specifying multiple directories in a single command results in the
19827 directories added to the beginning of the search path in the same order
19828 they were presented in the command. If blanks are needed as part of a
19829 directory name, double-quotes should be used around the name. In the
19830 command output, the path will show up separated by the system
19831 directory-separator character. The directory-separator character must
19832 not be used in any directory name. If no directories are specified,
19833 the current search path is displayed.
19838 The corresponding GDB command is `dir'.
19844 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
19845 ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
19847 -environment-directory ""
19848 ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
19850 -environment-directory -r /home/jjohnstn/src/gdb /usr/src
19851 ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
19853 -environment-directory -r
19854 ^done,source-path="$cdir:$cwd"
19857 The `-environment-path' Command
19858 -------------------------------
19863 -environment-path [ -r ] [ PATHDIR ]+
19865 Add directories PATHDIR to beginning of search path for object files.
19866 If the `-r' option is used, the search path is reset to the original
19867 search path that existed at gdb start-up. If directories PATHDIR are
19868 supplied in addition to the `-r' option, the search path is first reset
19869 and then addition occurs as normal. Multiple directories may be
19870 specified, separated by blanks. Specifying multiple directories in a
19871 single command results in the directories added to the beginning of the
19872 search path in the same order they were presented in the command. If
19873 blanks are needed as part of a directory name, double-quotes should be
19874 used around the name. In the command output, the path will show up
19875 separated by the system directory-separator character. The
19876 directory-separator character must not be used in any directory name.
19877 If no directories are specified, the current path is displayed.
19882 The corresponding GDB command is `path'.
19889 ^done,path="/usr/bin"
19891 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
19892 ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
19894 -environment-path -r /usr/local/bin
19895 ^done,path="/usr/local/bin:/usr/bin"
19898 The `-environment-pwd' Command
19899 ------------------------------
19906 Show the current working directory.
19911 The corresponding GDB command is `pwd'.
19918 ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
19922 File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Program Context, Up: GDB/MI
19924 27.10 GDB/MI Thread Commands
19925 ============================
19927 The `-thread-info' Command
19928 --------------------------
19933 -thread-info [ THREAD-ID ]
19935 Reports information about either a specific thread, if the THREAD-ID
19936 parameter is present, or about all threads. When printing information
19937 about all threads, also reports the current thread.
19942 The `info thread' command prints the same information about all threads.
19949 {id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
19950 frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"},
19951 {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
19952 frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}],
19953 file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}],
19954 current-thread-id="1"
19957 The `state' field may have the following values:
19960 The thread is stopped. Frame information is available for stopped
19964 The thread is running. There's no frame information for running
19968 The `-thread-list-ids' Command
19969 ------------------------------
19976 Produces a list of the currently known GDB thread ids. At the end
19977 of the list it also prints the total number of such threads.
19979 This command is retained for historical reasons, the `-thread-info'
19980 command should be used instead.
19985 Part of `info threads' supplies the same information.
19992 ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"},
19993 current-thread-id="1",number-of-threads="3"
19996 The `-thread-select' Command
19997 ----------------------------
20002 -thread-select THREADNUM
20004 Make THREADNUM the current thread. It prints the number of the new
20005 current thread, and the topmost frame for that thread.
20007 This command is deprecated in favor of explicitly using the
20008 `--thread' option to each command.
20013 The corresponding GDB command is `thread'.
20022 *stopped,reason="end-stepping-range",thread-id="2",line="187",
20023 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
20027 thread-ids={thread-id="3",thread-id="2",thread-id="1"},
20028 number-of-threads="3"
20031 ^done,new-thread-id="3",
20032 frame={level="0",func="vprintf",
20033 args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""},
20034 {name="arg",value="0x2"}],file="vprintf.c",line="31"}
20038 File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Thread Commands, Up: GDB/MI
20040 27.11 GDB/MI Program Execution
20041 ==============================
20043 These are the asynchronous commands which generate the out-of-band
20044 record `*stopped'. Currently GDB only really executes asynchronously
20045 with remote targets and this interaction is mimicked in other cases.
20047 The `-exec-continue' Command
20048 ----------------------------
20053 -exec-continue [--reverse] [--all|--thread-group N]
20055 Resumes the execution of the inferior program, which will continue
20056 to execute until it reaches a debugger stop event. If the `--reverse'
20057 option is specified, execution resumes in reverse until it reaches a
20058 stop event. Stop events may include
20059 * breakpoints or watchpoints
20061 * signals or exceptions
20063 * the end of the process (or its beginning under `--reverse')
20065 * the end or beginning of a replay log if one is being used.
20066 In all-stop mode (*note All-Stop Mode::), may resume only one
20067 thread, or all threads, depending on the value of the
20068 `scheduler-locking' variable. If `--all' is specified, all threads
20069 will be resumed. The `--all' option is ignored in all-stop mode. If
20070 the `--thread-group' options is specified, then all threads in that
20071 thread group are resumed.
20076 The corresponding GDB corresponding is `continue'.
20085 *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame={
20086 func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c",
20090 The `-exec-finish' Command
20091 --------------------------
20096 -exec-finish [--reverse]
20098 Resumes the execution of the inferior program until the current
20099 function is exited. Displays the results returned by the function. If
20100 the `--reverse' option is specified, resumes the reverse execution of
20101 the inferior program until the point where current function was called.
20106 The corresponding GDB command is `finish'.
20111 Function returning `void'.
20117 *stopped,reason="function-finished",frame={func="main",args=[],
20118 file="hello.c",fullname="/home/foo/bar/hello.c",line="7"}
20121 Function returning other than `void'. The name of the internal GDB
20122 variable storing the result is printed, together with the value itself.
20127 *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo",
20128 args=[{name="a",value="1"],{name="b",value="9"}},
20129 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
20130 gdb-result-var="$1",return-value="0"
20133 The `-exec-interrupt' Command
20134 -----------------------------
20139 -exec-interrupt [--all|--thread-group N]
20141 Interrupts the background execution of the target. Note how the
20142 token associated with the stop message is the one for the execution
20143 command that has been interrupted. The token for the interrupt itself
20144 only appears in the `^done' output. If the user is trying to interrupt
20145 a non-running program, an error message will be printed.
20147 Note that when asynchronous execution is enabled, this command is
20148 asynchronous just like other execution commands. That is, first the
20149 `^done' response will be printed, and the target stop will be reported
20150 after that using the `*stopped' notification.
20152 In non-stop mode, only the context thread is interrupted by default.
20153 All threads will be interrupted if the `--all' option is specified. If
20154 the `--thread-group' option is specified, all threads in that group
20155 will be interrupted.
20160 The corresponding GDB command is `interrupt'.
20173 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
20174 frame={addr="0x00010140",func="foo",args=[],file="try.c",
20175 fullname="/home/foo/bar/try.c",line="13"}
20180 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
20183 The `-exec-jump' Command
20184 ------------------------
20189 -exec-jump LOCATION
20191 Resumes execution of the inferior program at the location specified
20192 by parameter. *Note Specify Location::, for a description of the
20193 different forms of LOCATION.
20198 The corresponding GDB command is `jump'.
20203 -exec-jump foo.c:10
20204 *running,thread-id="all"
20207 The `-exec-next' Command
20208 ------------------------
20213 -exec-next [--reverse]
20215 Resumes execution of the inferior program, stopping when the
20216 beginning of the next source line is reached.
20218 If the `--reverse' option is specified, resumes reverse execution of
20219 the inferior program, stopping at the beginning of the previous source
20220 line. If you issue this command on the first line of a function, it
20221 will take you back to the caller of that function, to the source line
20222 where the function was called.
20227 The corresponding GDB command is `next'.
20235 *stopped,reason="end-stepping-range",line="8",file="hello.c"
20238 The `-exec-next-instruction' Command
20239 ------------------------------------
20244 -exec-next-instruction [--reverse]
20246 Executes one machine instruction. If the instruction is a function
20247 call, continues until the function returns. If the program stops at an
20248 instruction in the middle of a source line, the address will be printed
20251 If the `--reverse' option is specified, resumes reverse execution of
20252 the inferior program, stopping at the previous instruction. If the
20253 previously executed instruction was a return from another function, it
20254 will continue to execute in reverse until the call to that function
20255 (from the current stack frame) is reached.
20260 The corresponding GDB command is `nexti'.
20266 -exec-next-instruction
20270 *stopped,reason="end-stepping-range",
20271 addr="0x000100d4",line="5",file="hello.c"
20274 The `-exec-return' Command
20275 --------------------------
20282 Makes current function return immediately. Doesn't execute the
20283 inferior. Displays the new current frame.
20288 The corresponding GDB command is `return'.
20294 200-break-insert callee4
20295 200^done,bkpt={number="1",addr="0x00010734",
20296 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
20301 000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
20302 frame={func="callee4",args=[],
20303 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
20304 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
20310 111^done,frame={level="0",func="callee3",
20311 args=[{name="strarg",
20312 value="0x11940 \"A string argument.\""}],
20313 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
20314 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
20317 The `-exec-run' Command
20318 -----------------------
20325 Starts execution of the inferior from the beginning. The inferior
20326 executes until either a breakpoint is encountered or the program exits.
20327 In the latter case the output will include an exit code, if the program
20328 has exited exceptionally.
20333 The corresponding GDB command is `run'.
20340 ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}
20345 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
20346 frame={func="main",args=[],file="recursive2.c",
20347 fullname="/home/foo/bar/recursive2.c",line="4"}
20350 Program exited normally:
20357 *stopped,reason="exited-normally"
20360 Program exited exceptionally:
20367 *stopped,reason="exited",exit-code="01"
20370 Another way the program can terminate is if it receives a signal
20371 such as `SIGINT'. In this case, GDB/MI displays this:
20374 *stopped,reason="exited-signalled",signal-name="SIGINT",
20375 signal-meaning="Interrupt"
20377 The `-exec-step' Command
20378 ------------------------
20383 -exec-step [--reverse]
20385 Resumes execution of the inferior program, stopping when the
20386 beginning of the next source line is reached, if the next source line
20387 is not a function call. If it is, stop at the first instruction of the
20388 called function. If the `--reverse' option is specified, resumes
20389 reverse execution of the inferior program, stopping at the beginning of
20390 the previously executed source line.
20395 The corresponding GDB command is `step'.
20400 Stepping into a function:
20405 *stopped,reason="end-stepping-range",
20406 frame={func="foo",args=[{name="a",value="10"},
20407 {name="b",value="0"}],file="recursive2.c",
20408 fullname="/home/foo/bar/recursive2.c",line="11"}
20416 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
20419 The `-exec-step-instruction' Command
20420 ------------------------------------
20425 -exec-step-instruction [--reverse]
20427 Resumes the inferior which executes one machine instruction. If the
20428 `--reverse' option is specified, resumes reverse execution of the
20429 inferior program, stopping at the previously executed instruction. The
20430 output, once GDB has stopped, will vary depending on whether we have
20431 stopped in the middle of a source line or not. In the former case, the
20432 address at which the program stopped will be printed as well.
20437 The corresponding GDB command is `stepi'.
20443 -exec-step-instruction
20447 *stopped,reason="end-stepping-range",
20448 frame={func="foo",args=[],file="try.c",
20449 fullname="/home/foo/bar/try.c",line="10"}
20451 -exec-step-instruction
20455 *stopped,reason="end-stepping-range",
20456 frame={addr="0x000100f4",func="foo",args=[],file="try.c",
20457 fullname="/home/foo/bar/try.c",line="10"}
20460 The `-exec-until' Command
20461 -------------------------
20466 -exec-until [ LOCATION ]
20468 Executes the inferior until the LOCATION specified in the argument
20469 is reached. If there is no argument, the inferior executes until a
20470 source line greater than the current one is reached. The reason for
20471 stopping in this case will be `location-reached'.
20476 The corresponding GDB command is `until'.
20482 -exec-until recursive2.c:6
20486 *stopped,reason="location-reached",frame={func="main",args=[],
20487 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"}
20491 File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI
20493 27.12 GDB/MI Stack Manipulation Commands
20494 ========================================
20496 The `-stack-info-frame' Command
20497 -------------------------------
20504 Get info on the selected frame.
20509 The corresponding GDB command is `info frame' or `frame' (without
20517 ^done,frame={level="1",addr="0x0001076c",func="callee3",
20518 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
20519 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}
20522 The `-stack-info-depth' Command
20523 -------------------------------
20528 -stack-info-depth [ MAX-DEPTH ]
20530 Return the depth of the stack. If the integer argument MAX-DEPTH is
20531 specified, do not count beyond MAX-DEPTH frames.
20536 There's no equivalent GDB command.
20541 For a stack with frame levels 0 through 11:
20547 -stack-info-depth 4
20550 -stack-info-depth 12
20553 -stack-info-depth 11
20556 -stack-info-depth 13
20560 The `-stack-list-arguments' Command
20561 -----------------------------------
20566 -stack-list-arguments PRINT-VALUES
20567 [ LOW-FRAME HIGH-FRAME ]
20569 Display a list of the arguments for the frames between LOW-FRAME and
20570 HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided,
20571 list the arguments for the whole call stack. If the two arguments are
20572 equal, show the single frame at the corresponding level. It is an
20573 error if LOW-FRAME is larger than the actual number of frames. On the
20574 other hand, HIGH-FRAME may be larger than the actual number of frames,
20575 in which case only existing frames will be returned.
20577 If PRINT-VALUES is 0 or `--no-values', print only the names of the
20578 variables; if it is 1 or `--all-values', print also their values; and
20579 if it is 2 or `--simple-values', print the name, type and value for
20580 simple data types, and the name and type for arrays, structures and
20583 Use of this command to obtain arguments in a single frame is
20584 deprecated in favor of the `-stack-list-variables' command.
20589 GDB does not have an equivalent command. `gdbtk' has a `gdb_get_args'
20590 command which partially overlaps with the functionality of
20591 `-stack-list-arguments'.
20600 frame={level="0",addr="0x00010734",func="callee4",
20601 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
20602 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"},
20603 frame={level="1",addr="0x0001076c",func="callee3",
20604 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
20605 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"},
20606 frame={level="2",addr="0x0001078c",func="callee2",
20607 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
20608 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"},
20609 frame={level="3",addr="0x000107b4",func="callee1",
20610 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
20611 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"},
20612 frame={level="4",addr="0x000107e0",func="main",
20613 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
20614 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}]
20616 -stack-list-arguments 0
20619 frame={level="0",args=[]},
20620 frame={level="1",args=[name="strarg"]},
20621 frame={level="2",args=[name="intarg",name="strarg"]},
20622 frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]},
20623 frame={level="4",args=[]}]
20625 -stack-list-arguments 1
20628 frame={level="0",args=[]},
20630 args=[{name="strarg",value="0x11940 \"A string argument.\""}]},
20631 frame={level="2",args=[
20632 {name="intarg",value="2"},
20633 {name="strarg",value="0x11940 \"A string argument.\""}]},
20634 {frame={level="3",args=[
20635 {name="intarg",value="2"},
20636 {name="strarg",value="0x11940 \"A string argument.\""},
20637 {name="fltarg",value="3.5"}]},
20638 frame={level="4",args=[]}]
20640 -stack-list-arguments 0 2 2
20641 ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}]
20643 -stack-list-arguments 1 2 2
20644 ^done,stack-args=[frame={level="2",
20645 args=[{name="intarg",value="2"},
20646 {name="strarg",value="0x11940 \"A string argument.\""}]}]
20649 The `-stack-list-frames' Command
20650 --------------------------------
20655 -stack-list-frames [ LOW-FRAME HIGH-FRAME ]
20657 List the frames currently on the stack. For each frame it displays
20658 the following info:
20661 The frame number, 0 being the topmost frame, i.e., the innermost
20665 The `$pc' value for that frame.
20671 File name of the source file where the function lives.
20674 Line number corresponding to the `$pc'.
20676 If invoked without arguments, this command prints a backtrace for the
20677 whole stack. If given two integer arguments, it shows the frames whose
20678 levels are between the two arguments (inclusive). If the two arguments
20679 are equal, it shows the single frame at the corresponding level. It is
20680 an error if LOW-FRAME is larger than the actual number of frames. On
20681 the other hand, HIGH-FRAME may be larger than the actual number of
20682 frames, in which case only existing frames will be returned.
20687 The corresponding GDB commands are `backtrace' and `where'.
20692 Full stack backtrace:
20697 [frame={level="0",addr="0x0001076c",func="foo",
20698 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"},
20699 frame={level="1",addr="0x000107a4",func="foo",
20700 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
20701 frame={level="2",addr="0x000107a4",func="foo",
20702 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
20703 frame={level="3",addr="0x000107a4",func="foo",
20704 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
20705 frame={level="4",addr="0x000107a4",func="foo",
20706 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
20707 frame={level="5",addr="0x000107a4",func="foo",
20708 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
20709 frame={level="6",addr="0x000107a4",func="foo",
20710 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
20711 frame={level="7",addr="0x000107a4",func="foo",
20712 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
20713 frame={level="8",addr="0x000107a4",func="foo",
20714 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
20715 frame={level="9",addr="0x000107a4",func="foo",
20716 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
20717 frame={level="10",addr="0x000107a4",func="foo",
20718 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
20719 frame={level="11",addr="0x00010738",func="main",
20720 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}]
20723 Show frames between LOW_FRAME and HIGH_FRAME:
20726 -stack-list-frames 3 5
20728 [frame={level="3",addr="0x000107a4",func="foo",
20729 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
20730 frame={level="4",addr="0x000107a4",func="foo",
20731 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
20732 frame={level="5",addr="0x000107a4",func="foo",
20733 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}]
20736 Show a single frame:
20739 -stack-list-frames 3 3
20741 [frame={level="3",addr="0x000107a4",func="foo",
20742 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}]
20745 The `-stack-list-locals' Command
20746 --------------------------------
20751 -stack-list-locals PRINT-VALUES
20753 Display the local variable names for the selected frame. If
20754 PRINT-VALUES is 0 or `--no-values', print only the names of the
20755 variables; if it is 1 or `--all-values', print also their values; and
20756 if it is 2 or `--simple-values', print the name, type and value for
20757 simple data types, and the name and type for arrays, structures and
20758 unions. In this last case, a frontend can immediately display the
20759 value of simple data types and create variable objects for other data
20760 types when the user wishes to explore their values in more detail.
20762 This command is deprecated in favor of the `-stack-list-variables'
20768 `info locals' in GDB, `gdb_get_locals' in `gdbtk'.
20774 -stack-list-locals 0
20775 ^done,locals=[name="A",name="B",name="C"]
20777 -stack-list-locals --all-values
20778 ^done,locals=[{name="A",value="1"},{name="B",value="2"},
20779 {name="C",value="{1, 2, 3}"}]
20780 -stack-list-locals --simple-values
20781 ^done,locals=[{name="A",type="int",value="1"},
20782 {name="B",type="int",value="2"},{name="C",type="int [3]"}]
20785 The `-stack-list-variables' Command
20786 -----------------------------------
20791 -stack-list-variables PRINT-VALUES
20793 Display the names of local variables and function arguments for the
20794 selected frame. If PRINT-VALUES is 0 or `--no-values', print only the
20795 names of the variables; if it is 1 or `--all-values', print also their
20796 values; and if it is 2 or `--simple-values', print the name, type and
20797 value for simple data types, and the name and type for arrays,
20798 structures and unions.
20804 -stack-list-variables --thread 1 --frame 0 --all-values
20805 ^done,variables=[{name="x",value="11"},{name="s",value="{a = 1, b = 2}"}]
20808 The `-stack-select-frame' Command
20809 ---------------------------------
20814 -stack-select-frame FRAMENUM
20816 Change the selected frame. Select a different frame FRAMENUM on the
20819 This command in deprecated in favor of passing the `--frame' option
20825 The corresponding GDB commands are `frame', `up', `down',
20826 `select-frame', `up-silent', and `down-silent'.
20832 -stack-select-frame 2
20837 File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI
20839 27.13 GDB/MI Variable Objects
20840 =============================
20842 Introduction to Variable Objects
20843 --------------------------------
20845 Variable objects are "object-oriented" MI interface for examining and
20846 changing values of expressions. Unlike some other MI interfaces that
20847 work with expressions, variable objects are specifically designed for
20848 simple and efficient presentation in the frontend. A variable object
20849 is identified by string name. When a variable object is created, the
20850 frontend specifies the expression for that variable object. The
20851 expression can be a simple variable, or it can be an arbitrary complex
20852 expression, and can even involve CPU registers. After creating a
20853 variable object, the frontend can invoke other variable object
20854 operations--for example to obtain or change the value of a variable
20855 object, or to change display format.
20857 Variable objects have hierarchical tree structure. Any variable
20858 object that corresponds to a composite type, such as structure in C, has
20859 a number of child variable objects, for example corresponding to each
20860 element of a structure. A child variable object can itself have
20861 children, recursively. Recursion ends when we reach leaf variable
20862 objects, which always have built-in types. Child variable objects are
20863 created only by explicit request, so if a frontend is not interested in
20864 the children of a particular variable object, no child will be created.
20866 For a leaf variable object it is possible to obtain its value as a
20867 string, or set the value from a string. String value can be also
20868 obtained for a non-leaf variable object, but it's generally a string
20869 that only indicates the type of the object, and does not list its
20870 contents. Assignment to a non-leaf variable object is not allowed.
20872 A frontend does not need to read the values of all variable objects
20873 each time the program stops. Instead, MI provides an update command
20874 that lists all variable objects whose values has changed since the last
20875 update operation. This considerably reduces the amount of data that
20876 must be transferred to the frontend. As noted above, children variable
20877 objects are created on demand, and only leaf variable objects have a
20878 real value. As result, gdb will read target memory only for leaf
20879 variables that frontend has created.
20881 The automatic update is not always desirable. For example, a
20882 frontend might want to keep a value of some expression for future
20883 reference, and never update it. For another example, fetching memory
20884 is relatively slow for embedded targets, so a frontend might want to
20885 disable automatic update for the variables that are either not visible
20886 on the screen, or "closed". This is possible using so called "frozen
20887 variable objects". Such variable objects are never implicitly updated.
20889 Variable objects can be either "fixed" or "floating". For the fixed
20890 variable object, the expression is parsed when the variable object is
20891 created, including associating identifiers to specific variables. The
20892 meaning of expression never changes. For a floating variable object
20893 the values of variables whose names appear in the expressions are
20894 re-evaluated every time in the context of the current frame. Consider
20899 struct work_state state;
20905 If a fixed variable object for the `state' variable is created in
20906 this function, and we enter the recursive call, the the variable object
20907 will report the value of `state' in the top-level `do_work' invocation.
20908 On the other hand, a floating variable object will report the value of
20909 `state' in the current frame.
20911 If an expression specified when creating a fixed variable object
20912 refers to a local variable, the variable object becomes bound to the
20913 thread and frame in which the variable object is created. When such
20914 variable object is updated, GDB makes sure that the thread/frame
20915 combination the variable object is bound to still exists, and
20916 re-evaluates the variable object in context of that thread/frame.
20918 The following is the complete set of GDB/MI operations defined to
20919 access this functionality:
20921 *Operation* *Description*
20922 `-enable-pretty-printing' enable Python-based pretty-printing
20923 `-var-create' create a variable object
20924 `-var-delete' delete the variable object and/or its
20926 `-var-set-format' set the display format of this variable
20927 `-var-show-format' show the display format of this variable
20928 `-var-info-num-children' tells how many children this object has
20929 `-var-list-children' return a list of the object's children
20930 `-var-info-type' show the type of this variable object
20931 `-var-info-expression' print parent-relative expression that this
20932 variable object represents
20933 `-var-info-path-expression' print full expression that this variable
20935 `-var-show-attributes' is this variable editable? does it exist
20937 `-var-evaluate-expression' get the value of this variable
20938 `-var-assign' set the value of this variable
20939 `-var-update' update the variable and its children
20940 `-var-set-frozen' set frozeness attribute
20941 `-var-set-update-range' set range of children to display on update
20943 In the next subsection we describe each operation in detail and
20944 suggest how it can be used.
20946 Description And Use of Operations on Variable Objects
20947 -----------------------------------------------------
20949 The `-enable-pretty-printing' Command
20950 -------------------------------------
20952 -enable-pretty-printing
20954 GDB allows Python-based visualizers to affect the output of the MI
20955 variable object commands. However, because there was no way to
20956 implement this in a fully backward-compatible way, a front end must
20957 request that this functionality be enabled.
20959 Once enabled, this feature cannot be disabled.
20961 Note that if Python support has not been compiled into GDB, this
20962 command will still succeed (and do nothing).
20964 This feature is currently (as of GDB 7.0) experimental, and may work
20965 differently in future versions of GDB.
20967 The `-var-create' Command
20968 -------------------------
20973 -var-create {NAME | "-"}
20974 {FRAME-ADDR | "*" | "@"} EXPRESSION
20976 This operation creates a variable object, which allows the
20977 monitoring of a variable, the result of an expression, a memory cell or
20980 The NAME parameter is the string by which the object can be
20981 referenced. It must be unique. If `-' is specified, the varobj system
20982 will generate a string "varNNNNNN" automatically. It will be unique
20983 provided that one does not specify NAME of that format. The command
20984 fails if a duplicate name is found.
20986 The frame under which the expression should be evaluated can be
20987 specified by FRAME-ADDR. A `*' indicates that the current frame should
20988 be used. A `@' indicates that a floating variable object must be
20991 EXPRESSION is any expression valid on the current language set (must
20992 not begin with a `*'), or one of the following:
20994 * `*ADDR', where ADDR is the address of a memory cell
20996 * `*ADDR-ADDR' -- a memory address range (TBD)
20998 * `$REGNAME' -- a CPU register name
21000 A varobj's contents may be provided by a Python-based
21001 pretty-printer. In this case the varobj is known as a "dynamic
21002 varobj". Dynamic varobjs have slightly different semantics in some
21003 cases. If the `-enable-pretty-printing' command is not sent, then GDB
21004 will never create a dynamic varobj. This ensures backward
21005 compatibility for existing clients.
21010 This operation returns attributes of the newly-created varobj. These
21014 The name of the varobj.
21017 The number of children of the varobj. This number is not
21018 necessarily reliable for a dynamic varobj. Instead, you must
21019 examine the `has_more' attribute.
21022 The varobj's scalar value. For a varobj whose type is some sort of
21023 aggregate (e.g., a `struct'), or for a dynamic varobj, this value
21024 will not be interesting.
21027 The varobj's type. This is a string representation of the type, as
21028 would be printed by the GDB CLI.
21031 If a variable object is bound to a specific thread, then this is
21032 the thread's identifier.
21035 For a dynamic varobj, this indicates whether there appear to be any
21036 children available. For a non-dynamic varobj, this will be 0.
21039 This attribute will be present and have the value `1' if the
21040 varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
21041 then this attribute will not be present.
21044 A dynamic varobj can supply a display hint to the front end. The
21045 value comes directly from the Python pretty-printer object's
21046 `display_hint' method. *Note Pretty Printing::.
21048 Typical output will look like this:
21050 name="NAME",numchild="N",type="TYPE",thread-id="M",
21051 has_more="HAS_MORE"
21053 The `-var-delete' Command
21054 -------------------------
21059 -var-delete [ -c ] NAME
21061 Deletes a previously created variable object and all of its children.
21062 With the `-c' option, just deletes the children.
21064 Returns an error if the object NAME is not found.
21066 The `-var-set-format' Command
21067 -----------------------------
21072 -var-set-format NAME FORMAT-SPEC
21074 Sets the output format for the value of the object NAME to be
21077 The syntax for the FORMAT-SPEC is as follows:
21080 {binary | decimal | hexadecimal | octal | natural}
21082 The natural format is the default format choosen automatically based
21083 on the variable type (like decimal for an `int', hex for pointers,
21086 For a variable with children, the format is set only on the variable
21087 itself, and the children are not affected.
21089 The `-var-show-format' Command
21090 ------------------------------
21095 -var-show-format NAME
21097 Returns the format used to display the value of the object NAME.
21102 The `-var-info-num-children' Command
21103 ------------------------------------
21108 -var-info-num-children NAME
21110 Returns the number of children of a variable object NAME:
21114 Note that this number is not completely reliable for a dynamic
21115 varobj. It will return the current number of children, but more
21116 children may be available.
21118 The `-var-list-children' Command
21119 --------------------------------
21124 -var-list-children [PRINT-VALUES] NAME [FROM TO]
21125 Return a list of the children of the specified variable object and
21126 create variable objects for them, if they do not already exist. With a
21127 single argument or if PRINT-VALUES has a value for of 0 or
21128 `--no-values', print only the names of the variables; if PRINT-VALUES
21129 is 1 or `--all-values', also print their values; and if it is 2 or
21130 `--simple-values' print the name and value for simple data types and
21131 just the name for arrays, structures and unions.
21133 FROM and TO, if specified, indicate the range of children to report.
21134 If FROM or TO is less than zero, the range is reset and all children
21135 will be reported. Otherwise, children starting at FROM (zero-based)
21136 and up to and excluding TO will be reported.
21138 If a child range is requested, it will only affect the current call
21139 to `-var-list-children', but not future calls to `-var-update'. For
21140 this, you must instead use `-var-set-update-range'. The intent of this
21141 approach is to enable a front end to implement any update approach it
21142 likes; for example, scrolling a view may cause the front end to request
21143 more children with `-var-list-children', and then the front end could
21144 call `-var-set-update-range' with a different range to ensure that
21145 future updates are restricted to just the visible items.
21147 For each child the following results are returned:
21150 Name of the variable object created for this child.
21153 The expression to be shown to the user by the front end to
21154 designate this child. For example this may be the name of a
21157 For a dynamic varobj, this value cannot be used to form an
21158 expression. There is no way to do this at all with a dynamic
21161 For C/C++ structures there are several pseudo children returned to
21162 designate access qualifiers. For these pseudo children EXP is
21163 `public', `private', or `protected'. In this case the type and
21164 value are not present.
21166 A dynamic varobj will not report the access qualifying
21167 pseudo-children, regardless of the language. This information is
21168 not available at all with a dynamic varobj.
21171 Number of children this child has. For a dynamic varobj, this
21175 The type of the child.
21178 If values were requested, this is the value.
21181 If this variable object is associated with a thread, this is the
21182 thread id. Otherwise this result is not present.
21185 If the variable object is frozen, this variable will be present
21188 The result may have its own attributes:
21191 A dynamic varobj can supply a display hint to the front end. The
21192 value comes directly from the Python pretty-printer object's
21193 `display_hint' method. *Note Pretty Printing::.
21196 This is an integer attribute which is nonzero if there are children
21197 remaining after the end of the selected range.
21203 -var-list-children n
21204 ^done,numchild=N,children=[child={name=NAME,exp=EXP,
21205 numchild=N,type=TYPE},(repeats N times)]
21207 -var-list-children --all-values n
21208 ^done,numchild=N,children=[child={name=NAME,exp=EXP,
21209 numchild=N,value=VALUE,type=TYPE},(repeats N times)]
21211 The `-var-info-type' Command
21212 ----------------------------
21217 -var-info-type NAME
21219 Returns the type of the specified variable NAME. The type is
21220 returned as a string in the same format as it is output by the GDB CLI:
21224 The `-var-info-expression' Command
21225 ----------------------------------
21230 -var-info-expression NAME
21232 Returns a string that is suitable for presenting this variable
21233 object in user interface. The string is generally not valid expression
21234 in the current language, and cannot be evaluated.
21236 For example, if `a' is an array, and variable object `A' was created
21237 for `a', then we'll get this output:
21239 (gdb) -var-info-expression A.1
21240 ^done,lang="C",exp="1"
21242 Here, the values of `lang' can be `{"C" | "C++" | "Java"}'.
21244 Note that the output of the `-var-list-children' command also
21245 includes those expressions, so the `-var-info-expression' command is of
21248 The `-var-info-path-expression' Command
21249 ---------------------------------------
21254 -var-info-path-expression NAME
21256 Returns an expression that can be evaluated in the current context
21257 and will yield the same value that a variable object has. Compare this
21258 with the `-var-info-expression' command, which result can be used only
21259 for UI presentation. Typical use of the `-var-info-path-expression'
21260 command is creating a watchpoint from a variable object.
21262 This command is currently not valid for children of a dynamic varobj,
21263 and will give an error when invoked on one.
21265 For example, suppose `C' is a C++ class, derived from class `Base',
21266 and that the `Base' class has a member called `m_size'. Assume a
21267 variable `c' is has the type of `C' and a variable object `C' was
21268 created for variable `c'. Then, we'll get this output:
21269 (gdb) -var-info-path-expression C.Base.public.m_size
21270 ^done,path_expr=((Base)c).m_size)
21272 The `-var-show-attributes' Command
21273 ----------------------------------
21278 -var-show-attributes NAME
21280 List attributes of the specified variable object NAME:
21282 status=ATTR [ ( ,ATTR )* ]
21284 where ATTR is `{ { editable | noneditable } | TBD }'.
21286 The `-var-evaluate-expression' Command
21287 --------------------------------------
21292 -var-evaluate-expression [-f FORMAT-SPEC] NAME
21294 Evaluates the expression that is represented by the specified
21295 variable object and returns its value as a string. The format of the
21296 string can be specified with the `-f' option. The possible values of
21297 this option are the same as for `-var-set-format' (*note
21298 -var-set-format::). If the `-f' option is not specified, the current
21299 display format will be used. The current display format can be changed
21300 using the `-var-set-format' command.
21304 Note that one must invoke `-var-list-children' for a variable before
21305 the value of a child variable can be evaluated.
21307 The `-var-assign' Command
21308 -------------------------
21313 -var-assign NAME EXPRESSION
21315 Assigns the value of EXPRESSION to the variable object specified by
21316 NAME. The object must be `editable'. If the variable's value is
21317 altered by the assign, the variable will show up in any subsequent
21318 `-var-update' list.
21328 ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}]
21331 The `-var-update' Command
21332 -------------------------
21337 -var-update [PRINT-VALUES] {NAME | "*"}
21339 Reevaluate the expressions corresponding to the variable object NAME
21340 and all its direct and indirect children, and return the list of
21341 variable objects whose values have changed; NAME must be a root
21342 variable object. Here, "changed" means that the result of
21343 `-var-evaluate-expression' before and after the `-var-update' is
21344 different. If `*' is used as the variable object names, all existing
21345 variable objects are updated, except for frozen ones (*note
21346 -var-set-frozen::). The option PRINT-VALUES determines whether both
21347 names and values, or just names are printed. The possible values of
21348 this option are the same as for `-var-list-children' (*note
21349 -var-list-children::). It is recommended to use the `--all-values'
21350 option, to reduce the number of MI commands needed on each program stop.
21352 With the `*' parameter, if a variable object is bound to a currently
21353 running thread, it will not be updated, without any diagnostic.
21355 If `-var-set-update-range' was previously used on a varobj, then
21356 only the selected range of children will be reported.
21358 `-var-update' reports all the changed varobjs in a tuple named
21361 Each item in the change list is itself a tuple holding:
21364 The name of the varobj.
21367 If values were requested for this update, then this field will be
21368 present and will hold the value of the varobj.
21371 This field is a string which may take one of three values:
21374 The variable object's current value is valid.
21377 The variable object does not currently hold a valid value but
21378 it may hold one in the future if its associated expression
21379 comes back into scope.
21382 The variable object no longer holds a valid value. This can
21383 occur when the executable file being debugged has changed,
21384 either through recompilation or by using the GDB `file'
21385 command. The front end should normally choose to delete
21386 these variable objects.
21388 In the future new values may be added to this list so the front
21389 should be prepared for this possibility. *Note GDB/MI Development
21390 and Front Ends: GDB/MI Development and Front Ends.
21393 This is only present if the varobj is still valid. If the type
21394 changed, then this will be the string `true'; otherwise it will be
21398 If the varobj's type changed, then this field will be present and
21399 will hold the new type.
21402 For a dynamic varobj, if the number of children changed, or if the
21403 type changed, this will be the new number of children.
21405 The `numchild' field in other varobj responses is generally not
21406 valid for a dynamic varobj - it will show the number of children
21407 that GDB knows about, but because dynamic varobjs lazily
21408 instantiate their children, this will not reflect the number of
21409 children which may be available.
21411 The `new_num_children' attribute only reports changes to the
21412 number of children known by GDB. This is the only way to detect
21413 whether an update has removed children (which necessarily can only
21414 happen at the end of the update range).
21417 The display hint, if any.
21420 This is an integer value, which will be 1 if there are more
21421 children available outside the varobj's update range.
21424 This attribute will be present and have the value `1' if the
21425 varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
21426 then this attribute will not be present.
21429 If new children were added to a dynamic varobj within the selected
21430 update range (as set by `-var-set-update-range'), then they will
21431 be listed in this attribute.
21440 -var-update --all-values var1
21441 ^done,changelist=[{name="var1",value="3",in_scope="true",
21442 type_changed="false"}]
21445 The `-var-set-frozen' Command
21446 -----------------------------
21451 -var-set-frozen NAME FLAG
21453 Set the frozenness flag on the variable object NAME. The FLAG
21454 parameter should be either `1' to make the variable frozen or `0' to
21455 make it unfrozen. If a variable object is frozen, then neither itself,
21456 nor any of its children, are implicitly updated by `-var-update' of a
21457 parent variable or by `-var-update *'. Only `-var-update' of the
21458 variable itself will update its value and values of its children.
21459 After a variable object is unfrozen, it is implicitly updated by all
21460 subsequent `-var-update' operations. Unfreezing a variable does not
21461 update it, only subsequent `-var-update' does.
21467 -var-set-frozen V 1
21471 The `-var-set-update-range' command
21472 -----------------------------------
21477 -var-set-update-range NAME FROM TO
21479 Set the range of children to be returned by future invocations of
21482 FROM and TO indicate the range of children to report. If FROM or TO
21483 is less than zero, the range is reset and all children will be
21484 reported. Otherwise, children starting at FROM (zero-based) and up to
21485 and excluding TO will be reported.
21491 -var-set-update-range V 1 2
21494 The `-var-set-visualizer' command
21495 ---------------------------------
21500 -var-set-visualizer NAME VISUALIZER
21502 Set a visualizer for the variable object NAME.
21504 VISUALIZER is the visualizer to use. The special value `None' means
21505 to disable any visualizer in use.
21507 If not `None', VISUALIZER must be a Python expression. This
21508 expression must evaluate to a callable object which accepts a single
21509 argument. GDB will call this object with the value of the varobj NAME
21510 as an argument (this is done so that the same Python pretty-printing
21511 code can be used for both the CLI and MI). When called, this object
21512 must return an object which conforms to the pretty-printing interface
21513 (*note Pretty Printing::).
21515 The pre-defined function `gdb.default_visualizer' may be used to
21516 select a visualizer by following the built-in process (*note Selecting
21517 Pretty-Printers::). This is done automatically when a varobj is
21518 created, and so ordinarily is not needed.
21520 This feature is only available if Python support is enabled. The MI
21521 command `-list-features' (*note GDB/MI Miscellaneous Commands::) can be
21522 used to check this.
21527 Resetting the visualizer:
21530 -var-set-visualizer V None
21533 Reselecting the default (type-based) visualizer:
21536 -var-set-visualizer V gdb.default_visualizer
21539 Suppose `SomeClass' is a visualizer class. A lambda expression can
21540 be used to instantiate this class for a varobj:
21543 -var-set-visualizer V "lambda val: SomeClass()"
21547 File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI
21549 27.14 GDB/MI Data Manipulation
21550 ==============================
21552 This section describes the GDB/MI commands that manipulate data:
21553 examine memory and registers, evaluate expressions, etc.
21555 The `-data-disassemble' Command
21556 -------------------------------
21562 [ -s START-ADDR -e END-ADDR ]
21563 | [ -f FILENAME -l LINENUM [ -n LINES ] ]
21569 is the beginning address (or `$pc')
21575 is the name of the file to disassemble
21578 is the line number to disassemble around
21581 is the number of disassembly lines to be produced. If it is -1,
21582 the whole function will be disassembled, in case no END-ADDR is
21583 specified. If END-ADDR is specified as a non-zero value, and
21584 LINES is lower than the number of disassembly lines between
21585 START-ADDR and END-ADDR, only LINES lines are displayed; if LINES
21586 is higher than the number of lines between START-ADDR and
21587 END-ADDR, only the lines up to END-ADDR are displayed.
21590 is either 0 (meaning only disassembly) or 1 (meaning mixed source
21596 The output for each instruction is composed of four fields:
21606 Note that whatever included in the instruction field, is not
21607 manipulated directly by GDB/MI, i.e., it is not possible to adjust its
21613 There's no direct mapping from this command to the CLI.
21618 Disassemble from the current value of `$pc' to `$pc + 20':
21621 -data-disassemble -s $pc -e "$pc + 20" -- 0
21624 {address="0x000107c0",func-name="main",offset="4",
21625 inst="mov 2, %o0"},
21626 {address="0x000107c4",func-name="main",offset="8",
21627 inst="sethi %hi(0x11800), %o2"},
21628 {address="0x000107c8",func-name="main",offset="12",
21629 inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"},
21630 {address="0x000107cc",func-name="main",offset="16",
21631 inst="sethi %hi(0x11800), %o2"},
21632 {address="0x000107d0",func-name="main",offset="20",
21633 inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}]
21636 Disassemble the whole `main' function. Line 32 is part of `main'.
21638 -data-disassemble -f basics.c -l 32 -- 0
21640 {address="0x000107bc",func-name="main",offset="0",
21641 inst="save %sp, -112, %sp"},
21642 {address="0x000107c0",func-name="main",offset="4",
21643 inst="mov 2, %o0"},
21644 {address="0x000107c4",func-name="main",offset="8",
21645 inst="sethi %hi(0x11800), %o2"},
21647 {address="0x0001081c",func-name="main",offset="96",inst="ret "},
21648 {address="0x00010820",func-name="main",offset="100",inst="restore "}]
21651 Disassemble 3 instructions from the start of `main':
21654 -data-disassemble -f basics.c -l 32 -n 3 -- 0
21656 {address="0x000107bc",func-name="main",offset="0",
21657 inst="save %sp, -112, %sp"},
21658 {address="0x000107c0",func-name="main",offset="4",
21659 inst="mov 2, %o0"},
21660 {address="0x000107c4",func-name="main",offset="8",
21661 inst="sethi %hi(0x11800), %o2"}]
21664 Disassemble 3 instructions from the start of `main' in mixed mode:
21667 -data-disassemble -f basics.c -l 32 -n 3 -- 1
21669 src_and_asm_line={line="31",
21670 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
21671 testsuite/gdb.mi/basics.c",line_asm_insn=[
21672 {address="0x000107bc",func-name="main",offset="0",
21673 inst="save %sp, -112, %sp"}]},
21674 src_and_asm_line={line="32",
21675 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
21676 testsuite/gdb.mi/basics.c",line_asm_insn=[
21677 {address="0x000107c0",func-name="main",offset="4",
21678 inst="mov 2, %o0"},
21679 {address="0x000107c4",func-name="main",offset="8",
21680 inst="sethi %hi(0x11800), %o2"}]}]
21683 The `-data-evaluate-expression' Command
21684 ---------------------------------------
21689 -data-evaluate-expression EXPR
21691 Evaluate EXPR as an expression. The expression could contain an
21692 inferior function call. The function call will execute synchronously.
21693 If the expression contains spaces, it must be enclosed in double quotes.
21698 The corresponding GDB commands are `print', `output', and `call'. In
21699 `gdbtk' only, there's a corresponding `gdb_eval' command.
21704 In the following example, the numbers that precede the commands are the
21705 "tokens" described in *note GDB/MI Command Syntax: GDB/MI Command
21706 Syntax. Notice how GDB/MI returns the same tokens in its output.
21708 211-data-evaluate-expression A
21711 311-data-evaluate-expression &A
21712 311^done,value="0xefffeb7c"
21714 411-data-evaluate-expression A+3
21717 511-data-evaluate-expression "A + 3"
21721 The `-data-list-changed-registers' Command
21722 ------------------------------------------
21727 -data-list-changed-registers
21729 Display a list of the registers that have changed.
21734 GDB doesn't have a direct analog for this command; `gdbtk' has the
21735 corresponding command `gdb_changed_register_list'.
21740 On a PPC MBX board:
21747 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame={
21748 func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c",
21751 -data-list-changed-registers
21752 ^done,changed-registers=["0","1","2","4","5","6","7","8","9",
21753 "10","11","13","14","15","16","17","18","19","20","21","22","23",
21754 "24","25","26","27","28","30","31","64","65","66","67","69"]
21757 The `-data-list-register-names' Command
21758 ---------------------------------------
21763 -data-list-register-names [ ( REGNO )+ ]
21765 Show a list of register names for the current target. If no
21766 arguments are given, it shows a list of the names of all the registers.
21767 If integer numbers are given as arguments, it will print a list of the
21768 names of the registers corresponding to the arguments. To ensure
21769 consistency between a register name and its number, the output list may
21770 include empty register names.
21775 GDB does not have a command which corresponds to
21776 `-data-list-register-names'. In `gdbtk' there is a corresponding
21777 command `gdb_regnames'.
21782 For the PPC MBX board:
21784 -data-list-register-names
21785 ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
21786 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
21787 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
21788 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
21789 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
21790 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
21791 "", "pc","ps","cr","lr","ctr","xer"]
21793 -data-list-register-names 1 2 3
21794 ^done,register-names=["r1","r2","r3"]
21797 The `-data-list-register-values' Command
21798 ----------------------------------------
21803 -data-list-register-values FMT [ ( REGNO )*]
21805 Display the registers' contents. FMT is the format according to
21806 which the registers' contents are to be returned, followed by an
21807 optional list of numbers specifying the registers to display. A
21808 missing list of numbers indicates that the contents of all the
21809 registers must be returned.
21811 Allowed formats for FMT are:
21834 The corresponding GDB commands are `info reg', `info all-reg', and (in
21835 `gdbtk') `gdb_fetch_registers'.
21840 For a PPC MBX board (note: line breaks are for readability only, they
21841 don't appear in the actual output):
21844 -data-list-register-values r 64 65
21845 ^done,register-values=[{number="64",value="0xfe00a300"},
21846 {number="65",value="0x00029002"}]
21848 -data-list-register-values x
21849 ^done,register-values=[{number="0",value="0xfe0043c8"},
21850 {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"},
21851 {number="3",value="0x0"},{number="4",value="0xa"},
21852 {number="5",value="0x3fff68"},{number="6",value="0x3fff58"},
21853 {number="7",value="0xfe011e98"},{number="8",value="0x2"},
21854 {number="9",value="0xfa202820"},{number="10",value="0xfa202808"},
21855 {number="11",value="0x1"},{number="12",value="0x0"},
21856 {number="13",value="0x4544"},{number="14",value="0xffdfffff"},
21857 {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"},
21858 {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"},
21859 {number="19",value="0xffffffff"},{number="20",value="0xffffffff"},
21860 {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"},
21861 {number="23",value="0xffffffff"},{number="24",value="0xffffffff"},
21862 {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"},
21863 {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"},
21864 {number="29",value="0x0"},{number="30",value="0xfe010000"},
21865 {number="31",value="0x0"},{number="32",value="0x0"},
21866 {number="33",value="0x0"},{number="34",value="0x0"},
21867 {number="35",value="0x0"},{number="36",value="0x0"},
21868 {number="37",value="0x0"},{number="38",value="0x0"},
21869 {number="39",value="0x0"},{number="40",value="0x0"},
21870 {number="41",value="0x0"},{number="42",value="0x0"},
21871 {number="43",value="0x0"},{number="44",value="0x0"},
21872 {number="45",value="0x0"},{number="46",value="0x0"},
21873 {number="47",value="0x0"},{number="48",value="0x0"},
21874 {number="49",value="0x0"},{number="50",value="0x0"},
21875 {number="51",value="0x0"},{number="52",value="0x0"},
21876 {number="53",value="0x0"},{number="54",value="0x0"},
21877 {number="55",value="0x0"},{number="56",value="0x0"},
21878 {number="57",value="0x0"},{number="58",value="0x0"},
21879 {number="59",value="0x0"},{number="60",value="0x0"},
21880 {number="61",value="0x0"},{number="62",value="0x0"},
21881 {number="63",value="0x0"},{number="64",value="0xfe00a300"},
21882 {number="65",value="0x29002"},{number="66",value="0x202f04b5"},
21883 {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"},
21884 {number="69",value="0x20002b03"}]
21887 The `-data-read-memory' Command
21888 -------------------------------
21893 -data-read-memory [ -o BYTE-OFFSET ]
21894 ADDRESS WORD-FORMAT WORD-SIZE
21895 NR-ROWS NR-COLS [ ASCHAR ]
21900 An expression specifying the address of the first memory word to be
21901 read. Complex expressions containing embedded white space should
21902 be quoted using the C convention.
21905 The format to be used to print the memory words. The notation is
21906 the same as for GDB's `print' command (*note Output Formats:
21910 The size of each memory word in bytes.
21913 The number of rows in the output table.
21916 The number of columns in the output table.
21919 If present, indicates that each row should include an ASCII dump.
21920 The value of ASCHAR is used as a padding character when a byte is
21921 not a member of the printable ASCII character set (printable ASCII
21922 characters are those whose code is between 32 and 126,
21926 An offset to add to the ADDRESS before fetching memory.
21928 This command displays memory contents as a table of NR-ROWS by
21929 NR-COLS words, each word being WORD-SIZE bytes. In total, `NR-ROWS *
21930 NR-COLS * WORD-SIZE' bytes are read (returned as `total-bytes').
21931 Should less than the requested number of bytes be returned by the
21932 target, the missing words are identified using `N/A'. The number of
21933 bytes read from the target is returned in `nr-bytes' and the starting
21934 address used to read memory in `addr'.
21936 The address of the next/previous row or page is available in
21937 `next-row' and `prev-row', `next-page' and `prev-page'.
21942 The corresponding GDB command is `x'. `gdbtk' has `gdb_get_mem' memory
21948 Read six bytes of memory starting at `bytes+6' but then offset by `-6'
21949 bytes. Format as three rows of two columns. One byte per word.
21950 Display each word in hex.
21953 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
21954 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
21955 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
21956 prev-page="0x0000138a",memory=[
21957 {addr="0x00001390",data=["0x00","0x01"]},
21958 {addr="0x00001392",data=["0x02","0x03"]},
21959 {addr="0x00001394",data=["0x04","0x05"]}]
21962 Read two bytes of memory starting at address `shorts + 64' and
21963 display as a single word formatted in decimal.
21966 5-data-read-memory shorts+64 d 2 1 1
21967 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
21968 next-row="0x00001512",prev-row="0x0000150e",
21969 next-page="0x00001512",prev-page="0x0000150e",memory=[
21970 {addr="0x00001510",data=["128"]}]
21973 Read thirty two bytes of memory starting at `bytes+16' and format as
21974 eight rows of four columns. Include a string encoding with `x' used as
21975 the non-printable character.
21978 4-data-read-memory bytes+16 x 1 8 4 x
21979 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
21980 next-row="0x000013c0",prev-row="0x0000139c",
21981 next-page="0x000013c0",prev-page="0x00001380",memory=[
21982 {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"},
21983 {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"},
21984 {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"},
21985 {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"},
21986 {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"},
21987 {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"},
21988 {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"},
21989 {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}]
21993 File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI
21995 27.15 GDB/MI Tracepoint Commands
21996 ================================
21998 The tracepoint commands are not yet implemented.
22001 File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI
22003 27.16 GDB/MI Symbol Query Commands
22004 ==================================
22006 The `-symbol-list-lines' Command
22007 --------------------------------
22012 -symbol-list-lines FILENAME
22014 Print the list of lines that contain code and their associated
22015 program addresses for the given source filename. The entries are
22016 sorted in ascending PC order.
22021 There is no corresponding GDB command.
22027 -symbol-list-lines basics.c
22028 ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}]
22032 File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI
22034 27.17 GDB/MI File Commands
22035 ==========================
22037 This section describes the GDB/MI commands to specify executable file
22038 names and to read in and obtain symbol table information.
22040 The `-file-exec-and-symbols' Command
22041 ------------------------------------
22046 -file-exec-and-symbols FILE
22048 Specify the executable file to be debugged. This file is the one
22049 from which the symbol table is also read. If no file is specified, the
22050 command clears the executable and symbol information. If breakpoints
22051 are set when using this command with no arguments, GDB will produce
22052 error messages. Otherwise, no output is produced, except a completion
22058 The corresponding GDB command is `file'.
22064 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
22068 The `-file-exec-file' Command
22069 -----------------------------
22074 -file-exec-file FILE
22076 Specify the executable file to be debugged. Unlike
22077 `-file-exec-and-symbols', the symbol table is _not_ read from this
22078 file. If used without argument, GDB clears the information about the
22079 executable file. No output is produced, except a completion
22085 The corresponding GDB command is `exec-file'.
22091 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
22095 The `-file-list-exec-source-file' Command
22096 -----------------------------------------
22101 -file-list-exec-source-file
22103 List the line number, the current source file, and the absolute path
22104 to the current source file for the current executable. The macro
22105 information field has a value of `1' or `0' depending on whether or not
22106 the file includes preprocessor macro information.
22111 The GDB equivalent is `info source'
22117 123-file-list-exec-source-file
22118 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1"
22121 The `-file-list-exec-source-files' Command
22122 ------------------------------------------
22127 -file-list-exec-source-files
22129 List the source files for the current executable.
22131 It will always output the filename, but only when GDB can find the
22132 absolute file name of a source file, will it output the fullname.
22137 The GDB equivalent is `info sources'. `gdbtk' has an analogous command
22144 -file-list-exec-source-files
22146 {file=foo.c,fullname=/home/foo.c},
22147 {file=/home/bar.c,fullname=/home/bar.c},
22148 {file=gdb_could_not_find_fullpath.c}]
22151 The `-file-symbol-file' Command
22152 -------------------------------
22157 -file-symbol-file FILE
22159 Read symbol table info from the specified FILE argument. When used
22160 without arguments, clears GDB's symbol table info. No output is
22161 produced, except for a completion notification.
22166 The corresponding GDB command is `symbol-file'.
22172 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
22177 File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI
22179 27.18 GDB/MI Target Manipulation Commands
22180 =========================================
22182 The `-target-attach' Command
22183 ----------------------------
22188 -target-attach PID | GID | FILE
22190 Attach to a process PID or a file FILE outside of GDB, or a thread
22191 group GID. If attaching to a thread group, the id previously returned
22192 by `-list-thread-groups --available' must be used.
22197 The corresponding GDB command is `attach'.
22204 =thread-created,id="1"
22205 *stopped,thread-id="1",frame={addr="0xb7f7e410",func="bar",args=[]}
22209 The `-target-detach' Command
22210 ----------------------------
22215 -target-detach [ PID | GID ]
22217 Detach from the remote target which normally resumes its execution.
22218 If either PID or GID is specified, detaches from either the specified
22219 process, or specified thread group. There's no output.
22224 The corresponding GDB command is `detach'.
22234 The `-target-disconnect' Command
22235 --------------------------------
22242 Disconnect from the remote target. There's no output and the target
22243 is generally not resumed.
22248 The corresponding GDB command is `disconnect'.
22258 The `-target-download' Command
22259 ------------------------------
22266 Loads the executable onto the remote target. It prints out an
22267 update message every half second, which includes the fields:
22270 The name of the section.
22273 The size of what has been sent so far for that section.
22276 The size of the section.
22279 The total size of what was sent so far (the current and the
22280 previous sections).
22283 The size of the overall executable to download.
22285 Each message is sent as status record (*note GDB/MI Output Syntax:
22286 GDB/MI Output Syntax.).
22288 In addition, it prints the name and size of the sections, as they are
22289 downloaded. These messages include the following fields:
22292 The name of the section.
22295 The size of the section.
22298 The size of the overall executable to download.
22300 At the end, a summary is printed.
22305 The corresponding GDB command is `load'.
22310 Note: each status message appears on a single line. Here the messages
22311 have been broken down so that they can fit onto a page.
22315 +download,{section=".text",section-size="6668",total-size="9880"}
22316 +download,{section=".text",section-sent="512",section-size="6668",
22317 total-sent="512",total-size="9880"}
22318 +download,{section=".text",section-sent="1024",section-size="6668",
22319 total-sent="1024",total-size="9880"}
22320 +download,{section=".text",section-sent="1536",section-size="6668",
22321 total-sent="1536",total-size="9880"}
22322 +download,{section=".text",section-sent="2048",section-size="6668",
22323 total-sent="2048",total-size="9880"}
22324 +download,{section=".text",section-sent="2560",section-size="6668",
22325 total-sent="2560",total-size="9880"}
22326 +download,{section=".text",section-sent="3072",section-size="6668",
22327 total-sent="3072",total-size="9880"}
22328 +download,{section=".text",section-sent="3584",section-size="6668",
22329 total-sent="3584",total-size="9880"}
22330 +download,{section=".text",section-sent="4096",section-size="6668",
22331 total-sent="4096",total-size="9880"}
22332 +download,{section=".text",section-sent="4608",section-size="6668",
22333 total-sent="4608",total-size="9880"}
22334 +download,{section=".text",section-sent="5120",section-size="6668",
22335 total-sent="5120",total-size="9880"}
22336 +download,{section=".text",section-sent="5632",section-size="6668",
22337 total-sent="5632",total-size="9880"}
22338 +download,{section=".text",section-sent="6144",section-size="6668",
22339 total-sent="6144",total-size="9880"}
22340 +download,{section=".text",section-sent="6656",section-size="6668",
22341 total-sent="6656",total-size="9880"}
22342 +download,{section=".init",section-size="28",total-size="9880"}
22343 +download,{section=".fini",section-size="28",total-size="9880"}
22344 +download,{section=".data",section-size="3156",total-size="9880"}
22345 +download,{section=".data",section-sent="512",section-size="3156",
22346 total-sent="7236",total-size="9880"}
22347 +download,{section=".data",section-sent="1024",section-size="3156",
22348 total-sent="7748",total-size="9880"}
22349 +download,{section=".data",section-sent="1536",section-size="3156",
22350 total-sent="8260",total-size="9880"}
22351 +download,{section=".data",section-sent="2048",section-size="3156",
22352 total-sent="8772",total-size="9880"}
22353 +download,{section=".data",section-sent="2560",section-size="3156",
22354 total-sent="9284",total-size="9880"}
22355 +download,{section=".data",section-sent="3072",section-size="3156",
22356 total-sent="9796",total-size="9880"}
22357 ^done,address="0x10004",load-size="9880",transfer-rate="6586",
22371 The `-target-select' Command
22372 ----------------------------
22377 -target-select TYPE PARAMETERS ...
22379 Connect GDB to the remote target. This command takes two args:
22382 The type of target, for instance `remote', etc.
22385 Device names, host names and the like. *Note Commands for
22386 Managing Targets: Target Commands, for more details.
22388 The output is a connection notification, followed by the address at
22389 which the target program is, in the following form:
22391 ^connected,addr="ADDRESS",func="FUNCTION NAME",
22397 The corresponding GDB command is `target'.
22403 -target-select remote /dev/ttya
22404 ^connected,addr="0xfe00a300",func="??",args=[]
22408 File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI
22410 27.19 GDB/MI File Transfer Commands
22411 ===================================
22413 The `-target-file-put' Command
22414 ------------------------------
22419 -target-file-put HOSTFILE TARGETFILE
22421 Copy file HOSTFILE from the host system (the machine running GDB) to
22422 TARGETFILE on the target system.
22427 The corresponding GDB command is `remote put'.
22433 -target-file-put localfile remotefile
22437 The `-target-file-get' Command
22438 ------------------------------
22443 -target-file-get TARGETFILE HOSTFILE
22445 Copy file TARGETFILE from the target system to HOSTFILE on the host
22451 The corresponding GDB command is `remote get'.
22457 -target-file-get remotefile localfile
22461 The `-target-file-delete' Command
22462 ---------------------------------
22467 -target-file-delete TARGETFILE
22469 Delete TARGETFILE from the target system.
22474 The corresponding GDB command is `remote delete'.
22480 -target-file-delete remotefile
22485 File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI
22487 27.20 Miscellaneous GDB/MI Commands
22488 ===================================
22490 The `-gdb-exit' Command
22491 -----------------------
22498 Exit GDB immediately.
22503 Approximately corresponds to `quit'.
22512 The `-gdb-set' Command
22513 ----------------------
22520 Set an internal GDB variable.
22525 The corresponding GDB command is `set'.
22535 The `-gdb-show' Command
22536 -----------------------
22543 Show the current value of a GDB variable.
22548 The corresponding GDB command is `show'.
22558 The `-gdb-version' Command
22559 --------------------------
22566 Show version information for GDB. Used mostly in testing.
22571 The GDB equivalent is `show version'. GDB by default shows this
22572 information when you start an interactive session.
22580 ~Copyright 2000 Free Software Foundation, Inc.
22581 ~GDB is free software, covered by the GNU General Public License, and
22582 ~you are welcome to change it and/or distribute copies of it under
22583 ~ certain conditions.
22584 ~Type "show copying" to see the conditions.
22585 ~There is absolutely no warranty for GDB. Type "show warranty" for
22587 ~This GDB was configured as
22588 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
22592 The `-list-features' Command
22593 ----------------------------
22595 Returns a list of particular features of the MI protocol that this
22596 version of gdb implements. A feature can be a command, or a new field
22597 in an output of some command, or even an important bugfix. While a
22598 frontend can sometimes detect presence of a feature at runtime, it is
22599 easier to perform detection at debugger startup.
22601 The command returns a list of strings, with each string naming an
22602 available feature. Each returned string is just a name, it does not
22603 have any internal structure. The list of possible feature names is
22608 (gdb) -list-features
22609 ^done,result=["feature1","feature2"]
22611 The current list of features is:
22614 Indicates presence of the `-var-set-frozen' command, as well as
22615 possible presense of the `frozen' field in the output of
22618 `pending-breakpoints'
22619 Indicates presence of the `-f' option to the `-break-insert'
22623 Indicates presence of Python scripting support, Python-based
22624 pretty-printing commands, and possible presence of the
22625 `display_hint' field in the output of `-var-list-children'
22628 Indicates presence of the `-thread-info' command.
22631 The `-list-target-features' Command
22632 -----------------------------------
22634 Returns a list of particular features that are supported by the target.
22635 Those features affect the permitted MI commands, but unlike the
22636 features reported by the `-list-features' command, the features depend
22637 on which target GDB is using at the moment. Whenever a target can
22638 change, due to commands such as `-target-select', `-target-attach' or
22639 `-exec-run', the list of target features may change, and the frontend
22640 should obtain it again. Example output:
22642 (gdb) -list-features
22643 ^done,result=["async"]
22645 The current list of features is:
22648 Indicates that the target is capable of asynchronous command
22649 execution, which means that GDB will accept further commands while
22650 the target is running.
22653 The `-list-thread-groups' Command
22654 ---------------------------------
22659 -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ]
22661 Lists thread groups (*note Thread groups::). When a single thread
22662 group is passed as the argument, lists the children of that group.
22663 When several thread group are passed, lists information about those
22664 thread groups. Without any parameters, lists information about all
22665 top-level thread groups.
22667 Normally, thread groups that are being debugged are reported. With
22668 the `--available' option, GDB reports thread groups available on the
22671 The output of this command may have either a `threads' result or a
22672 `groups' result. The `thread' result has a list of tuples as value,
22673 with each tuple describing a thread (*note GDB/MI Thread
22674 Information::). The `groups' result has a list of tuples as value,
22675 each tuple describing a thread group. If top-level groups are
22676 requested (that is, no parameter is passed), or when several groups are
22677 passed, the output always has a `groups' result. The format of the
22678 `group' result is described below.
22680 To reduce the number of roundtrips it's possible to list thread
22681 groups together with their children, by passing the `--recurse' option
22682 and the recursion depth. Presently, only recursion depth of 1 is
22683 permitted. If this option is present, then every reported thread group
22684 will also include its children, either as `group' or `threads' field.
22686 In general, any combination of option and parameters is permitted,
22687 with the following caveats:
22689 * When a single thread group is passed, the output will typically be
22690 the `threads' result. Because threads may not contain anything,
22691 the `recurse' option will be ignored.
22693 * When the `--available' option is passed, limited information may
22694 be available. In particular, the list of threads of a process
22695 might be inaccessible. Further, specifying specific thread groups
22696 might not give any performance advantage over listing all thread
22697 groups. The frontend should assume that `-list-thread-groups
22698 --available' is always an expensive operation and cache the
22702 The `groups' result is a list of tuples, where each tuple may have
22703 the following fields:
22706 Identifier of the thread group. This field is always present.
22709 The type of the thread group. At present, only `process' is a
22713 The target-specific process identifier. This field is only present
22714 for thread groups of type `process'.
22717 The number of children this thread group has. This field may be
22718 absent for an available thread group.
22721 This field has a list of tuples as value, each tuple describing a
22722 thread. It may be present if the `--recurse' option is specified,
22723 and it's actually possible to obtain the threads.
22726 This field is a list of integers, each identifying a core that one
22727 thread of the group is running on. This field may be absent if
22728 such information is not available.
22735 -list-thread-groups
22736 ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}]
22737 -list-thread-groups 17
22738 ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
22739 frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"},
22740 {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
22741 frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}],
22742 file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}]]
22743 -list-thread-groups --available
22744 ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}]
22745 -list-thread-groups --available --recurse 1
22746 ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
22747 threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},
22748 {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..]
22749 -list-thread-groups --available --recurse 1 17 18
22750 ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
22751 threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},
22752 {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...]
22754 The `-interpreter-exec' Command
22755 -------------------------------
22760 -interpreter-exec INTERPRETER COMMAND
22761 Execute the specified COMMAND in the given INTERPRETER.
22766 The corresponding GDB command is `interpreter-exec'.
22772 -interpreter-exec console "break main"
22773 &"During symbol reading, couldn't parse type; debugger out of date?.\n"
22774 &"During symbol reading, bad structure-type format.\n"
22775 ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
22779 The `-inferior-tty-set' Command
22780 -------------------------------
22785 -inferior-tty-set /dev/pts/1
22787 Set terminal for future runs of the program being debugged.
22792 The corresponding GDB command is `set inferior-tty' /dev/pts/1.
22798 -inferior-tty-set /dev/pts/1
22802 The `-inferior-tty-show' Command
22803 --------------------------------
22810 Show terminal for future runs of program being debugged.
22815 The corresponding GDB command is `show inferior-tty'.
22821 -inferior-tty-set /dev/pts/1
22825 ^done,inferior_tty_terminal="/dev/pts/1"
22828 The `-enable-timings' Command
22829 -----------------------------
22834 -enable-timings [yes | no]
22836 Toggle the printing of the wallclock, user and system times for an MI
22837 command as a field in its output. This command is to help frontend
22838 developers optimize the performance of their code. No argument is
22839 equivalent to `yes'.
22854 ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
22855 addr="0x080484ed",func="main",file="myprog.c",
22856 fullname="/home/nickrob/myprog.c",line="73",times="0"},
22857 time={wallclock="0.05185",user="0.00800",system="0.00000"}
22865 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
22866 frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"},
22867 {name="argv",value="0xbfb60364"}],file="myprog.c",
22868 fullname="/home/nickrob/myprog.c",line="73"}
22872 File: gdb.info, Node: Annotations, Next: JIT Interface, Prev: GDB/MI, Up: Top
22877 This chapter describes annotations in GDB. Annotations were designed
22878 to interface GDB to graphical user interfaces or other similar programs
22879 which want to interact with GDB at a relatively high level.
22881 The annotation mechanism has largely been superseded by GDB/MI
22886 * Annotations Overview:: What annotations are; the general syntax.
22887 * Server Prefix:: Issuing a command without affecting user state.
22888 * Prompting:: Annotations marking GDB's need for input.
22889 * Errors:: Annotations for error messages.
22890 * Invalidation:: Some annotations describe things now invalid.
22891 * Annotations for Running::
22892 Whether the program is running, how it stopped, etc.
22893 * Source Annotations:: Annotations describing source code.
22896 File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations
22898 28.1 What is an Annotation?
22899 ===========================
22901 Annotations start with a newline character, two `control-z' characters,
22902 and the name of the annotation. If there is no additional information
22903 associated with this annotation, the name of the annotation is followed
22904 immediately by a newline. If there is additional information, the name
22905 of the annotation is followed by a space, the additional information,
22906 and a newline. The additional information cannot contain newline
22909 Any output not beginning with a newline and two `control-z'
22910 characters denotes literal output from GDB. Currently there is no need
22911 for GDB to output a newline followed by two `control-z' characters, but
22912 if there was such a need, the annotations could be extended with an
22913 `escape' annotation which means those three characters as output.
22915 The annotation LEVEL, which is specified using the `--annotate'
22916 command line option (*note Mode Options::), controls how much
22917 information GDB prints together with its prompt, values of expressions,
22918 source lines, and other types of output. Level 0 is for no
22919 annotations, level 1 is for use when GDB is run as a subprocess of GNU
22920 Emacs, level 3 is the maximum annotation suitable for programs that
22921 control GDB, and level 2 annotations have been made obsolete (*note
22922 Limitations of the Annotation Interface: (annotate)Limitations.).
22924 `set annotate LEVEL'
22925 The GDB command `set annotate' sets the level of annotations to
22926 the specified LEVEL.
22929 Show the current annotation level.
22931 This chapter describes level 3 annotations.
22933 A simple example of starting up GDB with annotations is:
22937 Copyright 2003 Free Software Foundation, Inc.
22938 GDB is free software, covered by the GNU General Public License,
22939 and you are welcome to change it and/or distribute copies of it
22940 under certain conditions.
22941 Type "show copying" to see the conditions.
22942 There is absolutely no warranty for GDB. Type "show warranty"
22944 This GDB was configured as "i386-pc-linux-gnu"
22954 Here `quit' is input to GDB; the rest is output from GDB. The three
22955 lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are
22956 annotations; the rest is output from GDB.
22959 File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations
22961 28.2 The Server Prefix
22962 ======================
22964 If you prefix a command with `server ' then it will not affect the
22965 command history, nor will it affect GDB's notion of which command to
22966 repeat if <RET> is pressed on a line by itself. This means that
22967 commands can be run behind a user's back by a front-end in a
22968 transparent manner.
22970 The `server ' prefix does not affect the recording of values into
22971 the value history; to print a value without recording it into the value
22972 history, use the `output' command instead of the `print' command.
22974 Using this prefix also disables confirmation requests (*note
22975 confirmation requests::).
22978 File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations
22980 28.3 Annotation for GDB Input
22981 =============================
22983 When GDB prompts for input, it annotates this fact so it is possible to
22984 know when to send output, when the output from a given command is over,
22987 Different kinds of input each have a different "input type". Each
22988 input type has three annotations: a `pre-' annotation, which denotes
22989 the beginning of any prompt which is being output, a plain annotation,
22990 which denotes the end of the prompt, and then a `post-' annotation
22991 which denotes the end of any echo which may (or may not) be associated
22992 with the input. For example, the `prompt' input type features the
22993 following annotations:
22999 The input types are
23002 When GDB is prompting for a command (the main GDB prompt).
23005 When GDB prompts for a set of commands, like in the `commands'
23006 command. The annotations are repeated for each command which is
23010 When GDB wants the user to select between various overloaded
23014 When GDB wants the user to confirm a potentially dangerous
23017 `prompt-for-continue'
23018 When GDB is asking the user to press return to continue. Note:
23019 Don't expect this to work well; instead use `set height 0' to
23020 disable prompting. This is because the counting of lines is buggy
23021 in the presence of annotations.
23024 File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations
23031 This annotation occurs right before GDB responds to an interrupt.
23035 This annotation occurs right before GDB responds to an error.
23037 Quit and error annotations indicate that any annotations which GDB
23038 was in the middle of may end abruptly. For example, if a
23039 `value-history-begin' annotation is followed by a `error', one cannot
23040 expect to receive the matching `value-history-end'. One cannot expect
23041 not to receive it either, however; an error annotation does not
23042 necessarily mean that GDB is immediately returning all the way to the
23045 A quit or error annotation may be preceded by
23049 Any output between that and the quit or error annotation is the error
23052 Warning messages are not yet annotated.
23055 File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations
23057 28.5 Invalidation Notices
23058 =========================
23060 The following annotations say that certain pieces of state may have
23063 `^Z^Zframes-invalid'
23064 The frames (for example, output from the `backtrace' command) may
23067 `^Z^Zbreakpoints-invalid'
23068 The breakpoints may have changed. For example, the user just
23069 added or deleted a breakpoint.
23072 File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations
23074 28.6 Running the Program
23075 ========================
23077 When the program starts executing due to a GDB command such as `step'
23082 is output. When the program stops,
23086 is output. Before the `stopped' annotation, a variety of
23087 annotations describe how the program stopped.
23089 `^Z^Zexited EXIT-STATUS'
23090 The program exited, and EXIT-STATUS is the exit status (zero for
23091 successful exit, otherwise nonzero).
23094 The program exited with a signal. After the `^Z^Zsignalled', the
23095 annotation continues:
23100 ^Z^Zsignal-name-end
23104 ^Z^Zsignal-string-end
23107 where NAME is the name of the signal, such as `SIGILL' or
23108 `SIGSEGV', and STRING is the explanation of the signal, such as
23109 `Illegal Instruction' or `Segmentation fault'. INTRO-TEXT,
23110 MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no
23114 The syntax of this annotation is just like `signalled', but GDB is
23115 just saying that the program received the signal, not that it was
23116 terminated with it.
23118 `^Z^Zbreakpoint NUMBER'
23119 The program hit breakpoint number NUMBER.
23121 `^Z^Zwatchpoint NUMBER'
23122 The program hit watchpoint number NUMBER.
23125 File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations
23127 28.7 Displaying Source
23128 ======================
23130 The following annotation is used instead of displaying source code:
23132 ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
23134 where FILENAME is an absolute file name indicating which source
23135 file, LINE is the line number within that file (where 1 is the first
23136 line in the file), CHARACTER is the character position within the file
23137 (where 0 is the first character in the file) (for most debug formats
23138 this will necessarily point to the beginning of a line), MIDDLE is
23139 `middle' if ADDR is in the middle of the line, or `beg' if ADDR is at
23140 the beginning of the line, and ADDR is the address in the target
23141 program associated with the source which is being displayed. ADDR is
23142 in the form `0x' followed by one or more lowercase hex digits (note
23143 that this does not depend on the language).
23146 File: gdb.info, Node: JIT Interface, Next: GDB Bugs, Prev: Annotations, Up: Top
23148 29 JIT Compilation Interface
23149 ****************************
23151 This chapter documents GDB's "just-in-time" (JIT) compilation
23152 interface. A JIT compiler is a program or library that generates native
23153 executable code at runtime and executes it, usually in order to achieve
23154 good performance while maintaining platform independence.
23156 Programs that use JIT compilation are normally difficult to debug
23157 because portions of their code are generated at runtime, instead of
23158 being loaded from object files, which is where GDB normally finds the
23159 program's symbols and debug information. In order to debug programs
23160 that use JIT compilation, GDB has an interface that allows the program
23161 to register in-memory symbol files with GDB at runtime.
23163 If you are using GDB to debug a program that uses this interface,
23164 then it should work transparently so long as you have not stripped the
23165 binary. If you are developing a JIT compiler, then the interface is
23166 documented in the rest of this chapter. At this time, the only known
23167 client of this interface is the LLVM JIT.
23169 Broadly speaking, the JIT interface mirrors the dynamic loader
23170 interface. The JIT compiler communicates with GDB by writing data into
23171 a global variable and calling a fuction at a well-known symbol. When
23172 GDB attaches, it reads a linked list of symbol files from the global
23173 variable to find existing code, and puts a breakpoint in the function
23174 so that it can find out about additional code.
23178 * Declarations:: Relevant C struct declarations
23179 * Registering Code:: Steps to register code
23180 * Unregistering Code:: Steps to unregister code
23183 File: gdb.info, Node: Declarations, Next: Registering Code, Up: JIT Interface
23185 29.1 JIT Declarations
23186 =====================
23188 These are the relevant struct declarations that a C program should
23189 include to implement the interface:
23198 struct jit_code_entry
23200 struct jit_code_entry *next_entry;
23201 struct jit_code_entry *prev_entry;
23202 const char *symfile_addr;
23203 uint64_t symfile_size;
23206 struct jit_descriptor
23209 /* This type should be jit_actions_t, but we use uint32_t
23210 to be explicit about the bitwidth. */
23211 uint32_t action_flag;
23212 struct jit_code_entry *relevant_entry;
23213 struct jit_code_entry *first_entry;
23216 /* GDB puts a breakpoint in this function. */
23217 void __attribute__((noinline)) __jit_debug_register_code() { };
23219 /* Make sure to specify the version statically, because the
23220 debugger may check the version before we can set it. */
23221 struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 };
23223 If the JIT is multi-threaded, then it is important that the JIT
23224 synchronize any modifications to this global data properly, which can
23225 easily be done by putting a global mutex around modifications to these
23229 File: gdb.info, Node: Registering Code, Next: Unregistering Code, Prev: Declarations, Up: JIT Interface
23231 29.2 Registering Code
23232 =====================
23234 To register code with GDB, the JIT should follow this protocol:
23236 * Generate an object file in memory with symbols and other desired
23237 debug information. The file must include the virtual addresses of
23240 * Create a code entry for the file, which gives the start and size
23241 of the symbol file.
23243 * Add it to the linked list in the JIT descriptor.
23245 * Point the relevant_entry field of the descriptor at the entry.
23247 * Set `action_flag' to `JIT_REGISTER' and call
23248 `__jit_debug_register_code'.
23250 When GDB is attached and the breakpoint fires, GDB uses the
23251 `relevant_entry' pointer so it doesn't have to walk the list looking for
23252 new code. However, the linked list must still be maintained in order
23253 to allow GDB to attach to a running process and still find the symbol
23257 File: gdb.info, Node: Unregistering Code, Prev: Registering Code, Up: JIT Interface
23259 29.3 Unregistering Code
23260 =======================
23262 If code is freed, then the JIT should use the following protocol:
23264 * Remove the code entry corresponding to the code from the linked
23267 * Point the `relevant_entry' field of the descriptor at the code
23270 * Set `action_flag' to `JIT_UNREGISTER' and call
23271 `__jit_debug_register_code'.
23273 If the JIT frees or recompiles code without unregistering it, then
23274 GDB and the JIT will leak the memory used for the associated symbol
23278 File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: JIT Interface, Up: Top
23280 30 Reporting Bugs in GDB
23281 ************************
23283 Your bug reports play an essential role in making GDB reliable.
23285 Reporting a bug may help you by bringing a solution to your problem,
23286 or it may not. But in any case the principal function of a bug report
23287 is to help the entire community by making the next version of GDB work
23288 better. Bug reports are your contribution to the maintenance of GDB.
23290 In order for a bug report to serve its purpose, you must include the
23291 information that enables us to fix the bug.
23295 * Bug Criteria:: Have you found a bug?
23296 * Bug Reporting:: How to report bugs
23299 File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs
23301 30.1 Have You Found a Bug?
23302 ==========================
23304 If you are not sure whether you have found a bug, here are some
23307 * If the debugger gets a fatal signal, for any input whatever, that
23308 is a GDB bug. Reliable debuggers never crash.
23310 * If GDB produces an error message for valid input, that is a bug.
23311 (Note that if you're cross debugging, the problem may also be
23312 somewhere in the connection to the target.)
23314 * If GDB does not produce an error message for invalid input, that
23315 is a bug. However, you should note that your idea of "invalid
23316 input" might be our idea of "an extension" or "support for
23317 traditional practice".
23319 * If you are an experienced user of debugging tools, your suggestions
23320 for improvement of GDB are welcome in any case.
23323 File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs
23325 30.2 How to Report Bugs
23326 =======================
23328 A number of companies and individuals offer support for GNU products.
23329 If you obtained GDB from a support organization, we recommend you
23330 contact that organization first.
23332 You can find contact information for many support companies and
23333 individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
23335 In any event, we also recommend that you submit bug reports for GDB.
23336 The preferred method is to submit them directly using GDB's Bugs web
23337 page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the
23338 e-mail gateway <bug-gdb@gnu.org> can be used.
23340 *Do not send bug reports to `info-gdb', or to `help-gdb', or to any
23341 newsgroups.* Most users of GDB do not want to receive bug reports.
23342 Those that do have arranged to receive `bug-gdb'.
23344 The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which
23345 serves as a repeater. The mailing list and the newsgroup carry exactly
23346 the same messages. Often people think of posting bug reports to the
23347 newsgroup instead of mailing them. This appears to work, but it has one
23348 problem which can be crucial: a newsgroup posting often lacks a mail
23349 path back to the sender. Thus, if we need to ask for more information,
23350 we may be unable to reach you. For this reason, it is better to send
23351 bug reports to the mailing list.
23353 The fundamental principle of reporting bugs usefully is this:
23354 *report all the facts*. If you are not sure whether to state a fact or
23355 leave it out, state it!
23357 Often people omit facts because they think they know what causes the
23358 problem and assume that some details do not matter. Thus, you might
23359 assume that the name of the variable you use in an example does not
23360 matter. Well, probably it does not, but one cannot be sure. Perhaps
23361 the bug is a stray memory reference which happens to fetch from the
23362 location where that name is stored in memory; perhaps, if the name were
23363 different, the contents of that location would fool the debugger into
23364 doing the right thing despite the bug. Play it safe and give a
23365 specific, complete example. That is the easiest thing for you to do,
23366 and the most helpful.
23368 Keep in mind that the purpose of a bug report is to enable us to fix
23369 the bug. It may be that the bug has been reported previously, but
23370 neither you nor we can know that unless your bug report is complete and
23373 Sometimes people give a few sketchy facts and ask, "Does this ring a
23374 bell?" Those bug reports are useless, and we urge everyone to _refuse
23375 to respond to them_ except to chide the sender to report bugs properly.
23377 To enable us to fix the bug, you should include all these things:
23379 * The version of GDB. GDB announces it if you start with no
23380 arguments; you can also print it at any time using `show version'.
23382 Without this, we will not know whether there is any point in
23383 looking for the bug in the current version of GDB.
23385 * The type of machine you are using, and the operating system name
23386 and version number.
23388 * What compiler (and its version) was used to compile GDB--e.g.
23391 * What compiler (and its version) was used to compile the program
23392 you are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP
23393 C Compiler". For GCC, you can say `gcc --version' to get this
23394 information; for other compilers, see the documentation for those
23397 * The command arguments you gave the compiler to compile your
23398 example and observe the bug. For example, did you use `-O'? To
23399 guarantee you will not omit something important, list them all. A
23400 copy of the Makefile (or the output from make) is sufficient.
23402 If we were to try to guess the arguments, we would probably guess
23403 wrong and then we might not encounter the bug.
23405 * A complete input script, and all necessary source files, that will
23408 * A description of what behavior you observe that you believe is
23409 incorrect. For example, "It gets a fatal signal."
23411 Of course, if the bug is that GDB gets a fatal signal, then we
23412 will certainly notice it. But if the bug is incorrect output, we
23413 might not notice unless it is glaringly wrong. You might as well
23414 not give us a chance to make a mistake.
23416 Even if the problem you experience is a fatal signal, you should
23417 still say so explicitly. Suppose something strange is going on,
23418 such as, your copy of GDB is out of synch, or you have encountered
23419 a bug in the C library on your system. (This has happened!) Your
23420 copy might crash and ours would not. If you told us to expect a
23421 crash, then when ours fails to crash, we would know that the bug
23422 was not happening for us. If you had not told us to expect a
23423 crash, then we would not be able to draw any conclusion from our
23426 To collect all this information, you can use a session recording
23427 program such as `script', which is available on many Unix systems.
23428 Just run your GDB session inside `script' and then include the
23429 `typescript' file with your bug report.
23431 Another way to record a GDB session is to run GDB inside Emacs and
23432 then save the entire buffer to a file.
23434 * If you wish to suggest changes to the GDB source, send us context
23435 diffs. If you even discuss something in the GDB source, refer to
23436 it by context, not by line number.
23438 The line numbers in our development sources will not match those
23439 in your sources. Your line numbers would convey no useful
23443 Here are some things that are not necessary:
23445 * A description of the envelope of the bug.
23447 Often people who encounter a bug spend a lot of time investigating
23448 which changes to the input file will make the bug go away and which
23449 changes will not affect it.
23451 This is often time consuming and not very useful, because the way
23452 we will find the bug is by running a single example under the
23453 debugger with breakpoints, not by pure deduction from a series of
23454 examples. We recommend that you save your time for something else.
23456 Of course, if you can find a simpler example to report _instead_
23457 of the original one, that is a convenience for us. Errors in the
23458 output will be easier to spot, running under the debugger will take
23459 less time, and so on.
23461 However, simplification is not vital; if you do not want to do
23462 this, report the bug anyway and send us the entire test case you
23465 * A patch for the bug.
23467 A patch for the bug does help us if it is a good one. But do not
23468 omit the necessary information, such as the test case, on the
23469 assumption that a patch is all we need. We might see problems
23470 with your patch and decide to fix the problem another way, or we
23471 might not understand it at all.
23473 Sometimes with a program as complicated as GDB it is very hard to
23474 construct an example that will make the program follow a certain
23475 path through the code. If you do not send us the example, we will
23476 not be able to construct one, so we will not be able to verify
23477 that the bug is fixed.
23479 And if we cannot understand what bug you are trying to fix, or why
23480 your patch should be an improvement, we will not install it. A
23481 test case will help us to understand.
23483 * A guess about what the bug is or what it depends on.
23485 Such guesses are usually wrong. Even we cannot guess right about
23486 such things without first using the debugger to find the facts.
23489 File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top
23491 31 Command Line Editing
23492 ***********************
23494 This chapter describes the basic features of the GNU command line
23499 * Introduction and Notation:: Notation used in this text.
23500 * Readline Interaction:: The minimum set of commands for editing a line.
23501 * Readline Init File:: Customizing Readline from a user's view.
23502 * Bindable Readline Commands:: A description of most of the Readline commands
23503 available for binding
23504 * Readline vi Mode:: A short description of how to make Readline
23505 behave like the vi editor.
23508 File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
23510 31.1 Introduction to Line Editing
23511 =================================
23513 The following paragraphs describe the notation used to represent
23516 The text `C-k' is read as `Control-K' and describes the character
23517 produced when the <k> key is pressed while the Control key is depressed.
23519 The text `M-k' is read as `Meta-K' and describes the character
23520 produced when the Meta key (if you have one) is depressed, and the <k>
23521 key is pressed. The Meta key is labeled <ALT> on many keyboards. On
23522 keyboards with two keys labeled <ALT> (usually to either side of the
23523 space bar), the <ALT> on the left side is generally set to work as a
23524 Meta key. The <ALT> key on the right may also be configured to work as
23525 a Meta key or may be configured as some other modifier, such as a
23526 Compose key for typing accented characters.
23528 If you do not have a Meta or <ALT> key, or another key working as a
23529 Meta key, the identical keystroke can be generated by typing <ESC>
23530 _first_, and then typing <k>. Either process is known as "metafying"
23533 The text `M-C-k' is read as `Meta-Control-k' and describes the
23534 character produced by "metafying" `C-k'.
23536 In addition, several keys have their own names. Specifically,
23537 <DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves
23538 when seen in this text, or in an init file (*note Readline Init File::).
23539 If your keyboard lacks a <LFD> key, typing <C-j> will produce the
23540 desired character. The <RET> key may be labeled <Return> or <Enter> on
23544 File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
23546 31.2 Readline Interaction
23547 =========================
23549 Often during an interactive session you type in a long line of text,
23550 only to notice that the first word on the line is misspelled. The
23551 Readline library gives you a set of commands for manipulating the text
23552 as you type it in, allowing you to just fix your typo, and not forcing
23553 you to retype the majority of the line. Using these editing commands,
23554 you move the cursor to the place that needs correction, and delete or
23555 insert the text of the corrections. Then, when you are satisfied with
23556 the line, you simply press <RET>. You do not have to be at the end of
23557 the line to press <RET>; the entire line is accepted regardless of the
23558 location of the cursor within the line.
23562 * Readline Bare Essentials:: The least you need to know about Readline.
23563 * Readline Movement Commands:: Moving about the input line.
23564 * Readline Killing Commands:: How to delete text, and how to get it back!
23565 * Readline Arguments:: Giving numeric arguments to commands.
23566 * Searching:: Searching through previous lines.
23569 File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
23571 31.2.1 Readline Bare Essentials
23572 -------------------------------
23574 In order to enter characters into the line, simply type them. The typed
23575 character appears where the cursor was, and then the cursor moves one
23576 space to the right. If you mistype a character, you can use your erase
23577 character to back up and delete the mistyped character.
23579 Sometimes you may mistype a character, and not notice the error
23580 until you have typed several other characters. In that case, you can
23581 type `C-b' to move the cursor to the left, and then correct your
23582 mistake. Afterwards, you can move the cursor to the right with `C-f'.
23584 When you add text in the middle of a line, you will notice that
23585 characters to the right of the cursor are `pushed over' to make room
23586 for the text that you have inserted. Likewise, when you delete text
23587 behind the cursor, characters to the right of the cursor are `pulled
23588 back' to fill in the blank space created by the removal of the text. A
23589 list of the bare essentials for editing the text of an input line
23593 Move back one character.
23596 Move forward one character.
23598 <DEL> or <Backspace>
23599 Delete the character to the left of the cursor.
23602 Delete the character underneath the cursor.
23604 Printing characters
23605 Insert the character into the line at the cursor.
23608 Undo the last editing command. You can undo all the way back to an
23611 (Depending on your configuration, the <Backspace> key be set to delete
23612 the character to the left of the cursor and the <DEL> key set to delete
23613 the character underneath the cursor, like `C-d', rather than the
23614 character to the left of the cursor.)
23617 File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
23619 31.2.2 Readline Movement Commands
23620 ---------------------------------
23622 The above table describes the most basic keystrokes that you need in
23623 order to do editing of the input line. For your convenience, many
23624 other commands have been added in addition to `C-b', `C-f', `C-d', and
23625 <DEL>. Here are some commands for moving more rapidly about the line.
23628 Move to the start of the line.
23631 Move to the end of the line.
23634 Move forward a word, where a word is composed of letters and
23638 Move backward a word.
23641 Clear the screen, reprinting the current line at the top.
23643 Notice how `C-f' moves forward a character, while `M-f' moves
23644 forward a word. It is a loose convention that control keystrokes
23645 operate on characters while meta keystrokes operate on words.
23648 File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
23650 31.2.3 Readline Killing Commands
23651 --------------------------------
23653 "Killing" text means to delete the text from the line, but to save it
23654 away for later use, usually by "yanking" (re-inserting) it back into
23655 the line. (`Cut' and `paste' are more recent jargon for `kill' and
23658 If the description for a command says that it `kills' text, then you
23659 can be sure that you can get the text back in a different (or the same)
23662 When you use a kill command, the text is saved in a "kill-ring".
23663 Any number of consecutive kills save all of the killed text together, so
23664 that when you yank it back, you get it all. The kill ring is not line
23665 specific; the text that you killed on a previously typed line is
23666 available to be yanked back later, when you are typing another line.
23668 Here is the list of commands for killing text.
23671 Kill the text from the current cursor position to the end of the
23675 Kill from the cursor to the end of the current word, or, if between
23676 words, to the end of the next word. Word boundaries are the same
23677 as those used by `M-f'.
23680 Kill from the cursor the start of the current word, or, if between
23681 words, to the start of the previous word. Word boundaries are the
23682 same as those used by `M-b'.
23685 Kill from the cursor to the previous whitespace. This is
23686 different than `M-<DEL>' because the word boundaries differ.
23689 Here is how to "yank" the text back into the line. Yanking means to
23690 copy the most-recently-killed text from the kill buffer.
23693 Yank the most recently killed text back into the buffer at the
23697 Rotate the kill-ring, and yank the new top. You can only do this
23698 if the prior command is `C-y' or `M-y'.
23701 File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
23703 31.2.4 Readline Arguments
23704 -------------------------
23706 You can pass numeric arguments to Readline commands. Sometimes the
23707 argument acts as a repeat count, other times it is the sign of the
23708 argument that is significant. If you pass a negative argument to a
23709 command which normally acts in a forward direction, that command will
23710 act in a backward direction. For example, to kill text back to the
23711 start of the line, you might type `M-- C-k'.
23713 The general way to pass numeric arguments to a command is to type
23714 meta digits before the command. If the first `digit' typed is a minus
23715 sign (`-'), then the sign of the argument will be negative. Once you
23716 have typed one meta digit to get the argument started, you can type the
23717 remainder of the digits, and then the command. For example, to give
23718 the `C-d' command an argument of 10, you could type `M-1 0 C-d', which
23719 will delete the next ten characters on the input line.
23722 File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
23724 31.2.5 Searching for Commands in the History
23725 --------------------------------------------
23727 Readline provides commands for searching through the command history
23728 for lines containing a specified string. There are two search modes:
23729 "incremental" and "non-incremental".
23731 Incremental searches begin before the user has finished typing the
23732 search string. As each character of the search string is typed,
23733 Readline displays the next entry from the history matching the string
23734 typed so far. An incremental search requires only as many characters
23735 as needed to find the desired history entry. To search backward in the
23736 history for a particular string, type `C-r'. Typing `C-s' searches
23737 forward through the history. The characters present in the value of
23738 the `isearch-terminators' variable are used to terminate an incremental
23739 search. If that variable has not been assigned a value, the <ESC> and
23740 `C-J' characters will terminate an incremental search. `C-g' will
23741 abort an incremental search and restore the original line. When the
23742 search is terminated, the history entry containing the search string
23743 becomes the current line.
23745 To find other matching entries in the history list, type `C-r' or
23746 `C-s' as appropriate. This will search backward or forward in the
23747 history for the next entry matching the search string typed so far.
23748 Any other key sequence bound to a Readline command will terminate the
23749 search and execute that command. For instance, a <RET> will terminate
23750 the search and accept the line, thereby executing the command from the
23751 history list. A movement command will terminate the search, make the
23752 last line found the current line, and begin editing.
23754 Readline remembers the last incremental search string. If two
23755 `C-r's are typed without any intervening characters defining a new
23756 search string, any remembered search string is used.
23758 Non-incremental searches read the entire search string before
23759 starting to search for matching history lines. The search string may be
23760 typed by the user or be part of the contents of the current line.
23763 File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
23765 31.3 Readline Init File
23766 =======================
23768 Although the Readline library comes with a set of Emacs-like
23769 keybindings installed by default, it is possible to use a different set
23770 of keybindings. Any user can customize programs that use Readline by
23771 putting commands in an "inputrc" file, conventionally in his home
23772 directory. The name of this file is taken from the value of the
23773 environment variable `INPUTRC'. If that variable is unset, the default
23776 When a program which uses the Readline library starts up, the init
23777 file is read, and the key bindings are set.
23779 In addition, the `C-x C-r' command re-reads this init file, thus
23780 incorporating any changes that you might have made to it.
23784 * Readline Init File Syntax:: Syntax for the commands in the inputrc file.
23786 * Conditional Init Constructs:: Conditional key bindings in the inputrc file.
23788 * Sample Init File:: An example inputrc file.
23791 File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
23793 31.3.1 Readline Init File Syntax
23794 --------------------------------
23796 There are only a few basic constructs allowed in the Readline init
23797 file. Blank lines are ignored. Lines beginning with a `#' are
23798 comments. Lines beginning with a `$' indicate conditional constructs
23799 (*note Conditional Init Constructs::). Other lines denote variable
23800 settings and key bindings.
23803 You can modify the run-time behavior of Readline by altering the
23804 values of variables in Readline using the `set' command within the
23805 init file. The syntax is simple:
23809 Here, for example, is how to change from the default Emacs-like
23810 key binding to use `vi' line editing commands:
23812 set editing-mode vi
23814 Variable names and values, where appropriate, are recognized
23815 without regard to case. Unrecognized variable names are ignored.
23817 Boolean variables (those that can be set to on or off) are set to
23818 on if the value is null or empty, ON (case-insensitive), or 1.
23819 Any other value results in the variable being set to off.
23821 A great deal of run-time behavior is changeable with the following
23825 Controls what happens when Readline wants to ring the
23826 terminal bell. If set to `none', Readline never rings the
23827 bell. If set to `visible', Readline uses a visible bell if
23828 one is available. If set to `audible' (the default),
23829 Readline attempts to ring the terminal's bell.
23831 `bind-tty-special-chars'
23832 If set to `on', Readline attempts to bind the control
23833 characters treated specially by the kernel's terminal driver
23834 to their Readline equivalents.
23837 The string to insert at the beginning of the line when the
23838 `insert-comment' command is executed. The default value is
23841 `completion-ignore-case'
23842 If set to `on', Readline performs filename matching and
23843 completion in a case-insensitive fashion. The default value
23846 `completion-query-items'
23847 The number of possible completions that determines when the
23848 user is asked whether the list of possibilities should be
23849 displayed. If the number of possible completions is greater
23850 than this value, Readline will ask the user whether or not he
23851 wishes to view them; otherwise, they are simply listed. This
23852 variable must be set to an integer value greater than or
23853 equal to 0. A negative value means Readline should never ask.
23854 The default limit is `100'.
23857 If set to `on', Readline will convert characters with the
23858 eighth bit set to an ASCII key sequence by stripping the
23859 eighth bit and prefixing an <ESC> character, converting them
23860 to a meta-prefixed key sequence. The default value is `on'.
23862 `disable-completion'
23863 If set to `On', Readline will inhibit word completion.
23864 Completion characters will be inserted into the line as if
23865 they had been mapped to `self-insert'. The default is `off'.
23868 The `editing-mode' variable controls which default set of key
23869 bindings is used. By default, Readline starts up in Emacs
23870 editing mode, where the keystrokes are most similar to Emacs.
23871 This variable can be set to either `emacs' or `vi'.
23874 When set to `on', Readline will try to enable the application
23875 keypad when it is called. Some systems need this to enable
23876 the arrow keys. The default is `off'.
23879 If set to `on', tilde expansion is performed when Readline
23880 attempts word completion. The default is `off'.
23882 `history-preserve-point'
23883 If set to `on', the history code attempts to place point at
23884 the same location on each history line retrieved with
23885 `previous-history' or `next-history'. The default is `off'.
23887 `horizontal-scroll-mode'
23888 This variable can be set to either `on' or `off'. Setting it
23889 to `on' means that the text of the lines being edited will
23890 scroll horizontally on a single screen line when they are
23891 longer than the width of the screen, instead of wrapping onto
23892 a new screen line. By default, this variable is set to `off'.
23895 If set to `on', Readline will enable eight-bit input (it will
23896 not clear the eighth bit in the characters it reads),
23897 regardless of what the terminal claims it can support. The
23898 default value is `off'. The name `meta-flag' is a synonym
23901 `isearch-terminators'
23902 The string of characters that should terminate an incremental
23903 search without subsequently executing the character as a
23904 command (*note Searching::). If this variable has not been
23905 given a value, the characters <ESC> and `C-J' will terminate
23906 an incremental search.
23909 Sets Readline's idea of the current keymap for key binding
23910 commands. Acceptable `keymap' names are `emacs',
23911 `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move',
23912 `vi-command', and `vi-insert'. `vi' is equivalent to
23913 `vi-command'; `emacs' is equivalent to `emacs-standard'. The
23914 default value is `emacs'. The value of the `editing-mode'
23915 variable also affects the default keymap.
23918 If set to `on', completed directory names have a slash
23919 appended. The default is `on'.
23921 `mark-modified-lines'
23922 This variable, when set to `on', causes Readline to display an
23923 asterisk (`*') at the start of history lines which have been
23924 modified. This variable is `off' by default.
23926 `mark-symlinked-directories'
23927 If set to `on', completed names which are symbolic links to
23928 directories have a slash appended (subject to the value of
23929 `mark-directories'). The default is `off'.
23931 `match-hidden-files'
23932 This variable, when set to `on', causes Readline to match
23933 files whose names begin with a `.' (hidden files) when
23934 performing filename completion, unless the leading `.' is
23935 supplied by the user in the filename to be completed. This
23936 variable is `on' by default.
23939 If set to `on', Readline will display characters with the
23940 eighth bit set directly rather than as a meta-prefixed escape
23941 sequence. The default is `off'.
23944 If set to `on', Readline uses an internal `more'-like pager
23945 to display a screenful of possible completions at a time.
23946 This variable is `on' by default.
23948 `print-completions-horizontally'
23949 If set to `on', Readline will display completions with matches
23950 sorted horizontally in alphabetical order, rather than down
23951 the screen. The default is `off'.
23953 `show-all-if-ambiguous'
23954 This alters the default behavior of the completion functions.
23955 If set to `on', words which have more than one possible
23956 completion cause the matches to be listed immediately instead
23957 of ringing the bell. The default value is `off'.
23959 `show-all-if-unmodified'
23960 This alters the default behavior of the completion functions
23961 in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to
23962 `on', words which have more than one possible completion
23963 without any possible partial completion (the possible
23964 completions don't share a common prefix) cause the matches to
23965 be listed immediately instead of ringing the bell. The
23966 default value is `off'.
23969 If set to `on', a character denoting a file's type is
23970 appended to the filename when listing possible completions.
23971 The default is `off'.
23975 The syntax for controlling key bindings in the init file is
23976 simple. First you need to find the name of the command that you
23977 want to change. The following sections contain tables of the
23978 command name, the default keybinding, if any, and a short
23979 description of what the command does.
23981 Once you know the name of the command, simply place on a line in
23982 the init file the name of the key you wish to bind the command to,
23983 a colon, and then the name of the command. The name of the key
23984 can be expressed in different ways, depending on what you find most
23987 In addition to command names, readline allows keys to be bound to
23988 a string that is inserted when the key is pressed (a MACRO).
23990 KEYNAME: FUNCTION-NAME or MACRO
23991 KEYNAME is the name of a key spelled out in English. For
23993 Control-u: universal-argument
23994 Meta-Rubout: backward-kill-word
23995 Control-o: "> output"
23997 In the above example, `C-u' is bound to the function
23998 `universal-argument', `M-DEL' is bound to the function
23999 `backward-kill-word', and `C-o' is bound to run the macro
24000 expressed on the right hand side (that is, to insert the text
24001 `> output' into the line).
24003 A number of symbolic character names are recognized while
24004 processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
24005 NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
24007 "KEYSEQ": FUNCTION-NAME or MACRO
24008 KEYSEQ differs from KEYNAME above in that strings denoting an
24009 entire key sequence can be specified, by placing the key
24010 sequence in double quotes. Some GNU Emacs style key escapes
24011 can be used, as in the following example, but the special
24012 character names are not recognized.
24014 "\C-u": universal-argument
24015 "\C-x\C-r": re-read-init-file
24016 "\e[11~": "Function Key 1"
24018 In the above example, `C-u' is again bound to the function
24019 `universal-argument' (just as it was in the first example),
24020 `C-x C-r' is bound to the function `re-read-init-file', and
24021 `<ESC> <[> <1> <1> <~>' is bound to insert the text `Function
24025 The following GNU Emacs style escape sequences are available when
24026 specifying key sequences:
24035 an escape character
24041 <">, a double quotation mark
24044 <'>, a single quote or apostrophe
24046 In addition to the GNU Emacs style escape sequences, a second set
24047 of backslash escapes is available:
24074 the eight-bit character whose value is the octal value NNN
24075 (one to three digits)
24078 the eight-bit character whose value is the hexadecimal value
24079 HH (one or two hex digits)
24081 When entering the text of a macro, single or double quotes must be
24082 used to indicate a macro definition. Unquoted text is assumed to
24083 be a function name. In the macro body, the backslash escapes
24084 described above are expanded. Backslash will quote any other
24085 character in the macro text, including `"' and `''. For example,
24086 the following binding will make `C-x \' insert a single `\' into
24092 File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
24094 31.3.2 Conditional Init Constructs
24095 ----------------------------------
24097 Readline implements a facility similar in spirit to the conditional
24098 compilation features of the C preprocessor which allows key bindings
24099 and variable settings to be performed as the result of tests. There
24100 are four parser directives used.
24103 The `$if' construct allows bindings to be made based on the
24104 editing mode, the terminal being used, or the application using
24105 Readline. The text of the test extends to the end of the line; no
24106 characters are required to isolate it.
24109 The `mode=' form of the `$if' directive is used to test
24110 whether Readline is in `emacs' or `vi' mode. This may be
24111 used in conjunction with the `set keymap' command, for
24112 instance, to set bindings in the `emacs-standard' and
24113 `emacs-ctlx' keymaps only if Readline is starting out in
24117 The `term=' form may be used to include terminal-specific key
24118 bindings, perhaps to bind the key sequences output by the
24119 terminal's function keys. The word on the right side of the
24120 `=' is tested against both the full name of the terminal and
24121 the portion of the terminal name before the first `-'. This
24122 allows `sun' to match both `sun' and `sun-cmd', for instance.
24125 The APPLICATION construct is used to include
24126 application-specific settings. Each program using the
24127 Readline library sets the APPLICATION NAME, and you can test
24128 for a particular value. This could be used to bind key
24129 sequences to functions useful for a specific program. For
24130 instance, the following command adds a key sequence that
24131 quotes the current or previous word in Bash:
24133 # Quote the current or previous word
24134 "\C-xq": "\eb\"\ef\""
24138 This command, as seen in the previous example, terminates an `$if'
24142 Commands in this branch of the `$if' directive are executed if the
24146 This directive takes a single filename as an argument and reads
24147 commands and bindings from that file. For example, the following
24148 directive reads from `/etc/inputrc':
24149 $include /etc/inputrc
24152 File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
24154 31.3.3 Sample Init File
24155 -----------------------
24157 Here is an example of an INPUTRC file. This illustrates key binding,
24158 variable assignment, and conditional syntax.
24161 # This file controls the behaviour of line input editing for
24162 # programs that use the GNU Readline library. Existing
24163 # programs include FTP, Bash, and GDB.
24165 # You can re-read the inputrc file with C-x C-r.
24166 # Lines beginning with '#' are comments.
24168 # First, include any systemwide bindings and variable
24169 # assignments from /etc/Inputrc
24170 $include /etc/Inputrc
24173 # Set various bindings for emacs mode.
24175 set editing-mode emacs
24179 Meta-Control-h: backward-kill-word Text after the function name is ignored
24182 # Arrow keys in keypad mode
24184 #"\M-OD": backward-char
24185 #"\M-OC": forward-char
24186 #"\M-OA": previous-history
24187 #"\M-OB": next-history
24189 # Arrow keys in ANSI mode
24191 "\M-[D": backward-char
24192 "\M-[C": forward-char
24193 "\M-[A": previous-history
24194 "\M-[B": next-history
24196 # Arrow keys in 8 bit keypad mode
24198 #"\M-\C-OD": backward-char
24199 #"\M-\C-OC": forward-char
24200 #"\M-\C-OA": previous-history
24201 #"\M-\C-OB": next-history
24203 # Arrow keys in 8 bit ANSI mode
24205 #"\M-\C-[D": backward-char
24206 #"\M-\C-[C": forward-char
24207 #"\M-\C-[A": previous-history
24208 #"\M-\C-[B": next-history
24214 # An old-style binding. This happens to be the default.
24217 # Macros that are convenient for shell interaction
24220 "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
24221 # prepare to type a quoted word --
24222 # insert open and close double quotes
24223 # and move to just after the open quote
24224 "\C-x\"": "\"\"\C-b"
24225 # insert a backslash (testing backslash escapes
24226 # in sequences and macros)
24228 # Quote the current or previous word
24229 "\C-xq": "\eb\"\ef\""
24230 # Add a binding to refresh the line, which is unbound
24231 "\C-xr": redraw-current-line
24232 # Edit variable on current line.
24233 "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
24236 # use a visible bell if one is available
24237 set bell-style visible
24239 # don't strip characters to 7 bits when reading
24242 # allow iso-latin1 characters to be inserted rather
24243 # than converted to prefix-meta sequences
24244 set convert-meta off
24246 # display characters with the eighth bit set directly
24247 # rather than as meta-prefixed characters
24250 # if there are more than 150 possible completions for
24251 # a word, ask the user if he wants to see all of them
24252 set completion-query-items 150
24256 "\C-xg": "get \M-?"
24257 "\C-xt": "put \M-?"
24258 "\M-.": yank-last-arg
24262 File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
24264 31.4 Bindable Readline Commands
24265 ===============================
24269 * Commands For Moving:: Moving about the line.
24270 * Commands For History:: Getting at previous lines.
24271 * Commands For Text:: Commands for changing text.
24272 * Commands For Killing:: Commands for killing and yanking.
24273 * Numeric Arguments:: Specifying numeric arguments, repeat counts.
24274 * Commands For Completion:: Getting Readline to do the typing for you.
24275 * Keyboard Macros:: Saving and re-executing typed characters
24276 * Miscellaneous Commands:: Other miscellaneous commands.
24278 This section describes Readline commands that may be bound to key
24279 sequences. Command names without an accompanying key sequence are
24280 unbound by default.
24282 In the following descriptions, "point" refers to the current cursor
24283 position, and "mark" refers to a cursor position saved by the
24284 `set-mark' command. The text between the point and mark is referred to
24288 File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
24290 31.4.1 Commands For Moving
24291 --------------------------
24293 `beginning-of-line (C-a)'
24294 Move to the start of the current line.
24296 `end-of-line (C-e)'
24297 Move to the end of the line.
24299 `forward-char (C-f)'
24300 Move forward a character.
24302 `backward-char (C-b)'
24303 Move back a character.
24305 `forward-word (M-f)'
24306 Move forward to the end of the next word. Words are composed of
24307 letters and digits.
24309 `backward-word (M-b)'
24310 Move back to the start of the current or previous word. Words are
24311 composed of letters and digits.
24313 `clear-screen (C-l)'
24314 Clear the screen and redraw the current line, leaving the current
24315 line at the top of the screen.
24317 `redraw-current-line ()'
24318 Refresh the current line. By default, this is unbound.
24322 File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
24324 31.4.2 Commands For Manipulating The History
24325 --------------------------------------------
24327 `accept-line (Newline or Return)'
24328 Accept the line regardless of where the cursor is. If this line is
24329 non-empty, it may be added to the history list for future recall
24330 with `add_history()'. If this line is a modified history line,
24331 the history line is restored to its original state.
24333 `previous-history (C-p)'
24334 Move `back' through the history list, fetching the previous
24337 `next-history (C-n)'
24338 Move `forward' through the history list, fetching the next command.
24340 `beginning-of-history (M-<)'
24341 Move to the first line in the history.
24343 `end-of-history (M->)'
24344 Move to the end of the input history, i.e., the line currently
24347 `reverse-search-history (C-r)'
24348 Search backward starting at the current line and moving `up'
24349 through the history as necessary. This is an incremental search.
24351 `forward-search-history (C-s)'
24352 Search forward starting at the current line and moving `down'
24353 through the the history as necessary. This is an incremental
24356 `non-incremental-reverse-search-history (M-p)'
24357 Search backward starting at the current line and moving `up'
24358 through the history as necessary using a non-incremental search
24359 for a string supplied by the user.
24361 `non-incremental-forward-search-history (M-n)'
24362 Search forward starting at the current line and moving `down'
24363 through the the history as necessary using a non-incremental search
24364 for a string supplied by the user.
24366 `history-search-forward ()'
24367 Search forward through the history for the string of characters
24368 between the start of the current line and the point. This is a
24369 non-incremental search. By default, this command is unbound.
24371 `history-search-backward ()'
24372 Search backward through the history for the string of characters
24373 between the start of the current line and the point. This is a
24374 non-incremental search. By default, this command is unbound.
24376 `yank-nth-arg (M-C-y)'
24377 Insert the first argument to the previous command (usually the
24378 second word on the previous line) at point. With an argument N,
24379 insert the Nth word from the previous command (the words in the
24380 previous command begin with word 0). A negative argument inserts
24381 the Nth word from the end of the previous command. Once the
24382 argument N is computed, the argument is extracted as if the `!N'
24383 history expansion had been specified.
24385 `yank-last-arg (M-. or M-_)'
24386 Insert last argument to the previous command (the last word of the
24387 previous history entry). With an argument, behave exactly like
24388 `yank-nth-arg'. Successive calls to `yank-last-arg' move back
24389 through the history list, inserting the last argument of each line
24390 in turn. The history expansion facilities are used to extract the
24391 last argument, as if the `!$' history expansion had been specified.
24395 File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
24397 31.4.3 Commands For Changing Text
24398 ---------------------------------
24400 `delete-char (C-d)'
24401 Delete the character at point. If point is at the beginning of
24402 the line, there are no characters in the line, and the last
24403 character typed was not bound to `delete-char', then return EOF.
24405 `backward-delete-char (Rubout)'
24406 Delete the character behind the cursor. A numeric argument means
24407 to kill the characters instead of deleting them.
24409 `forward-backward-delete-char ()'
24410 Delete the character under the cursor, unless the cursor is at the
24411 end of the line, in which case the character behind the cursor is
24412 deleted. By default, this is not bound to a key.
24414 `quoted-insert (C-q or C-v)'
24415 Add the next character typed to the line verbatim. This is how to
24416 insert key sequences like `C-q', for example.
24418 `tab-insert (M-<TAB>)'
24419 Insert a tab character.
24421 `self-insert (a, b, A, 1, !, ...)'
24424 `transpose-chars (C-t)'
24425 Drag the character before the cursor forward over the character at
24426 the cursor, moving the cursor forward as well. If the insertion
24427 point is at the end of the line, then this transposes the last two
24428 characters of the line. Negative arguments have no effect.
24430 `transpose-words (M-t)'
24431 Drag the word before point past the word after point, moving point
24432 past that word as well. If the insertion point is at the end of
24433 the line, this transposes the last two words on the line.
24435 `upcase-word (M-u)'
24436 Uppercase the current (or following) word. With a negative
24437 argument, uppercase the previous word, but do not move the cursor.
24439 `downcase-word (M-l)'
24440 Lowercase the current (or following) word. With a negative
24441 argument, lowercase the previous word, but do not move the cursor.
24443 `capitalize-word (M-c)'
24444 Capitalize the current (or following) word. With a negative
24445 argument, capitalize the previous word, but do not move the cursor.
24447 `overwrite-mode ()'
24448 Toggle overwrite mode. With an explicit positive numeric argument,
24449 switches to overwrite mode. With an explicit non-positive numeric
24450 argument, switches to insert mode. This command affects only
24451 `emacs' mode; `vi' mode does overwrite differently. Each call to
24452 `readline()' starts in insert mode.
24454 In overwrite mode, characters bound to `self-insert' replace the
24455 text at point rather than pushing the text to the right.
24456 Characters bound to `backward-delete-char' replace the character
24457 before point with a space.
24459 By default, this command is unbound.
24463 File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
24465 31.4.4 Killing And Yanking
24466 --------------------------
24469 Kill the text from point to the end of the line.
24471 `backward-kill-line (C-x Rubout)'
24472 Kill backward to the beginning of the line.
24474 `unix-line-discard (C-u)'
24475 Kill backward from the cursor to the beginning of the current line.
24477 `kill-whole-line ()'
24478 Kill all characters on the current line, no matter where point is.
24479 By default, this is unbound.
24482 Kill from point to the end of the current word, or if between
24483 words, to the end of the next word. Word boundaries are the same
24486 `backward-kill-word (M-<DEL>)'
24487 Kill the word behind point. Word boundaries are the same as
24490 `unix-word-rubout (C-w)'
24491 Kill the word behind point, using white space as a word boundary.
24492 The killed text is saved on the kill-ring.
24494 `unix-filename-rubout ()'
24495 Kill the word behind point, using white space and the slash
24496 character as the word boundaries. The killed text is saved on the
24499 `delete-horizontal-space ()'
24500 Delete all spaces and tabs around point. By default, this is
24504 Kill the text in the current region. By default, this command is
24507 `copy-region-as-kill ()'
24508 Copy the text in the region to the kill buffer, so it can be yanked
24509 right away. By default, this command is unbound.
24511 `copy-backward-word ()'
24512 Copy the word before point to the kill buffer. The word
24513 boundaries are the same as `backward-word'. By default, this
24514 command is unbound.
24516 `copy-forward-word ()'
24517 Copy the word following point to the kill buffer. The word
24518 boundaries are the same as `forward-word'. By default, this
24519 command is unbound.
24522 Yank the top of the kill ring into the buffer at point.
24525 Rotate the kill-ring, and yank the new top. You can only do this
24526 if the prior command is `yank' or `yank-pop'.
24529 File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
24531 31.4.5 Specifying Numeric Arguments
24532 -----------------------------------
24534 `digit-argument (M-0, M-1, ... M--)'
24535 Add this digit to the argument already accumulating, or start a new
24536 argument. `M--' starts a negative argument.
24538 `universal-argument ()'
24539 This is another way to specify an argument. If this command is
24540 followed by one or more digits, optionally with a leading minus
24541 sign, those digits define the argument. If the command is
24542 followed by digits, executing `universal-argument' again ends the
24543 numeric argument, but is otherwise ignored. As a special case, if
24544 this command is immediately followed by a character that is
24545 neither a digit or minus sign, the argument count for the next
24546 command is multiplied by four. The argument count is initially
24547 one, so executing this function the first time makes the argument
24548 count four, a second time makes the argument count sixteen, and so
24549 on. By default, this is not bound to a key.
24552 File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
24554 31.4.6 Letting Readline Type For You
24555 ------------------------------------
24558 Attempt to perform completion on the text before point. The
24559 actual completion performed is application-specific. The default
24560 is filename completion.
24562 `possible-completions (M-?)'
24563 List the possible completions of the text before point.
24565 `insert-completions (M-*)'
24566 Insert all completions of the text before point that would have
24567 been generated by `possible-completions'.
24570 Similar to `complete', but replaces the word to be completed with
24571 a single match from the list of possible completions. Repeated
24572 execution of `menu-complete' steps through the list of possible
24573 completions, inserting each match in turn. At the end of the list
24574 of completions, the bell is rung (subject to the setting of
24575 `bell-style') and the original text is restored. An argument of N
24576 moves N positions forward in the list of matches; a negative
24577 argument may be used to move backward through the list. This
24578 command is intended to be bound to <TAB>, but is unbound by
24581 `delete-char-or-list ()'
24582 Deletes the character under the cursor if not at the beginning or
24583 end of the line (like `delete-char'). If at the end of the line,
24584 behaves identically to `possible-completions'. This command is
24585 unbound by default.
24589 File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
24591 31.4.7 Keyboard Macros
24592 ----------------------
24594 `start-kbd-macro (C-x ()'
24595 Begin saving the characters typed into the current keyboard macro.
24597 `end-kbd-macro (C-x ))'
24598 Stop saving the characters typed into the current keyboard macro
24599 and save the definition.
24601 `call-last-kbd-macro (C-x e)'
24602 Re-execute the last keyboard macro defined, by making the
24603 characters in the macro appear as if typed at the keyboard.
24607 File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
24609 31.4.8 Some Miscellaneous Commands
24610 ----------------------------------
24612 `re-read-init-file (C-x C-r)'
24613 Read in the contents of the INPUTRC file, and incorporate any
24614 bindings or variable assignments found there.
24617 Abort the current editing command and ring the terminal's bell
24618 (subject to the setting of `bell-style').
24620 `do-uppercase-version (M-a, M-b, M-X, ...)'
24621 If the metafied character X is lowercase, run the command that is
24622 bound to the corresponding uppercase character.
24624 `prefix-meta (<ESC>)'
24625 Metafy the next character typed. This is for keyboards without a
24626 meta key. Typing `<ESC> f' is equivalent to typing `M-f'.
24628 `undo (C-_ or C-x C-u)'
24629 Incremental undo, separately remembered for each line.
24631 `revert-line (M-r)'
24632 Undo all changes made to this line. This is like executing the
24633 `undo' command enough times to get back to the beginning.
24635 `tilde-expand (M-~)'
24636 Perform tilde expansion on the current word.
24639 Set the mark to the point. If a numeric argument is supplied, the
24640 mark is set to that position.
24642 `exchange-point-and-mark (C-x C-x)'
24643 Swap the point with the mark. The current cursor position is set
24644 to the saved position, and the old cursor position is saved as the
24647 `character-search (C-])'
24648 A character is read and point is moved to the next occurrence of
24649 that character. A negative count searches for previous
24652 `character-search-backward (M-C-])'
24653 A character is read and point is moved to the previous occurrence
24654 of that character. A negative count searches for subsequent
24657 `insert-comment (M-#)'
24658 Without a numeric argument, the value of the `comment-begin'
24659 variable is inserted at the beginning of the current line. If a
24660 numeric argument is supplied, this command acts as a toggle: if
24661 the characters at the beginning of the line do not match the value
24662 of `comment-begin', the value is inserted, otherwise the
24663 characters in `comment-begin' are deleted from the beginning of
24664 the line. In either case, the line is accepted as if a newline
24667 `dump-functions ()'
24668 Print all of the functions and their key bindings to the Readline
24669 output stream. If a numeric argument is supplied, the output is
24670 formatted in such a way that it can be made part of an INPUTRC
24671 file. This command is unbound by default.
24673 `dump-variables ()'
24674 Print all of the settable variables and their values to the
24675 Readline output stream. If a numeric argument is supplied, the
24676 output is formatted in such a way that it can be made part of an
24677 INPUTRC file. This command is unbound by default.
24680 Print all of the Readline key sequences bound to macros and the
24681 strings they output. If a numeric argument is supplied, the
24682 output is formatted in such a way that it can be made part of an
24683 INPUTRC file. This command is unbound by default.
24685 `emacs-editing-mode (C-e)'
24686 When in `vi' command mode, this causes a switch to `emacs' editing
24689 `vi-editing-mode (M-C-j)'
24690 When in `emacs' editing mode, this causes a switch to `vi' editing
24695 File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
24697 31.5 Readline vi Mode
24698 =====================
24700 While the Readline library does not have a full set of `vi' editing
24701 functions, it does contain enough to allow simple editing of the line.
24702 The Readline `vi' mode behaves as specified in the POSIX 1003.2
24705 In order to switch interactively between `emacs' and `vi' editing
24706 modes, use the command `M-C-j' (bound to emacs-editing-mode when in
24707 `vi' mode and to vi-editing-mode in `emacs' mode). The Readline
24708 default is `emacs' mode.
24710 When you enter a line in `vi' mode, you are already placed in
24711 `insertion' mode, as if you had typed an `i'. Pressing <ESC> switches
24712 you into `command' mode, where you can edit the text of the line with
24713 the standard `vi' movement keys, move to previous history lines with
24714 `k' and subsequent lines with `j', and so forth.
24717 File: gdb.info, Node: Using History Interactively, Next: Formatting Documentation, Prev: Command Line Editing, Up: Top
24719 32 Using History Interactively
24720 ******************************
24722 This chapter describes how to use the GNU History Library interactively,
24723 from a user's standpoint. It should be considered a user's guide. For
24724 information on using the GNU History Library in other programs, see the
24725 GNU Readline Library Manual.
24729 * History Interaction:: What it feels like using History as a user.
24732 File: gdb.info, Node: History Interaction, Up: Using History Interactively
24734 32.1 History Expansion
24735 ======================
24737 The History library provides a history expansion feature that is similar
24738 to the history expansion provided by `csh'. This section describes the
24739 syntax used to manipulate the history information.
24741 History expansions introduce words from the history list into the
24742 input stream, making it easy to repeat commands, insert the arguments
24743 to a previous command into the current input line, or fix errors in
24744 previous commands quickly.
24746 History expansion takes place in two parts. The first is to
24747 determine which line from the history list should be used during
24748 substitution. The second is to select portions of that line for
24749 inclusion into the current one. The line selected from the history is
24750 called the "event", and the portions of that line that are acted upon
24751 are called "words". Various "modifiers" are available to manipulate
24752 the selected words. The line is broken into words in the same fashion
24753 that Bash does, so that several words surrounded by quotes are
24754 considered one word. History expansions are introduced by the
24755 appearance of the history expansion character, which is `!' by default.
24759 * Event Designators:: How to specify which history line to use.
24760 * Word Designators:: Specifying which words are of interest.
24761 * Modifiers:: Modifying the results of substitution.
24764 File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
24766 32.1.1 Event Designators
24767 ------------------------
24769 An event designator is a reference to a command line entry in the
24773 Start a history substitution, except when followed by a space, tab,
24774 the end of the line, or `='.
24777 Refer to command line N.
24780 Refer to the command N lines back.
24783 Refer to the previous command. This is a synonym for `!-1'.
24786 Refer to the most recent command starting with STRING.
24789 Refer to the most recent command containing STRING. The trailing
24790 `?' may be omitted if the STRING is followed immediately by a
24793 `^STRING1^STRING2^'
24794 Quick Substitution. Repeat the last command, replacing STRING1
24795 with STRING2. Equivalent to `!!:s/STRING1/STRING2/'.
24798 The entire command line typed so far.
24802 File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
24804 32.1.2 Word Designators
24805 -----------------------
24807 Word designators are used to select desired words from the event. A
24808 `:' separates the event specification from the word designator. It may
24809 be omitted if the word designator begins with a `^', `$', `*', `-', or
24810 `%'. Words are numbered from the beginning of the line, with the first
24811 word being denoted by 0 (zero). Words are inserted into the current
24812 line separated by single spaces.
24817 designates the preceding command. When you type this, the
24818 preceding command is repeated in toto.
24821 designates the last argument of the preceding command. This may be
24825 designates the second argument of the most recent command starting
24826 with the letters `fi'.
24828 Here are the word designators:
24831 The `0'th word. For many applications, this is the command word.
24837 The first argument; that is, word 1.
24843 The word matched by the most recent `?STRING?' search.
24846 A range of words; `-Y' abbreviates `0-Y'.
24849 All of the words, except the `0'th. This is a synonym for `1-$'.
24850 It is not an error to use `*' if there is just one word in the
24851 event; the empty string is returned in that case.
24857 Abbreviates `X-$' like `X*', but omits the last word.
24860 If a word designator is supplied without an event specification, the
24861 previous command is used as the event.
24864 File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
24869 After the optional word designator, you can add a sequence of one or
24870 more of the following modifiers, each preceded by a `:'.
24873 Remove a trailing pathname component, leaving only the head.
24876 Remove all leading pathname components, leaving the tail.
24879 Remove a trailing suffix of the form `.SUFFIX', leaving the
24883 Remove all but the trailing suffix.
24886 Print the new command but do not execute it.
24889 Substitute NEW for the first occurrence of OLD in the event line.
24890 Any delimiter may be used in place of `/'. The delimiter may be
24891 quoted in OLD and NEW with a single backslash. If `&' appears in
24892 NEW, it is replaced by OLD. A single backslash will quote the
24893 `&'. The final delimiter is optional if it is the last character
24897 Repeat the previous substitution.
24901 Cause changes to be applied over the entire event line. Used in
24902 conjunction with `s', as in `gs/OLD/NEW/', or with `&'.
24905 Apply the following `s' modifier once to each word in the event.
24909 File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: Using History Interactively, Up: Top
24911 Appendix A Formatting Documentation
24912 ***********************************
24914 The GDB 4 release includes an already-formatted reference card, ready
24915 for printing with PostScript or Ghostscript, in the `gdb' subdirectory
24916 of the main source directory(1). If you can use PostScript or
24917 Ghostscript with your printer, you can print the reference card
24918 immediately with `refcard.ps'.
24920 The release also includes the source for the reference card. You
24921 can format it, using TeX, by typing:
24925 The GDB reference card is designed to print in "landscape" mode on
24926 US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches
24927 high. You will need to specify this form of printing as an option to
24928 your DVI output program.
24930 All the documentation for GDB comes as part of the machine-readable
24931 distribution. The documentation is written in Texinfo format, which is
24932 a documentation system that uses a single source file to produce both
24933 on-line information and a printed manual. You can use one of the Info
24934 formatting commands to create the on-line version of the documentation
24935 and TeX (or `texi2roff') to typeset the printed version.
24937 GDB includes an already formatted copy of the on-line Info version
24938 of this manual in the `gdb' subdirectory. The main Info file is
24939 `gdb-7.1-android-gg2/gdb/gdb.info', and it refers to subordinate files
24940 matching `gdb.info*' in the same directory. If necessary, you can
24941 print out these files, or read them with any editor; but they are
24942 easier to read using the `info' subsystem in GNU Emacs or the
24943 standalone `info' program, available as part of the GNU Texinfo
24946 If you want to format these Info files yourself, you need one of the
24947 Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.
24949 If you have `makeinfo' installed, and are in the top level GDB
24950 source directory (`gdb-7.1-android-gg2', in the case of version
24951 7.1-android-gg2), you can make the Info file by typing:
24956 If you want to typeset and print copies of this manual, you need TeX,
24957 a program to print its DVI output files, and `texinfo.tex', the Texinfo
24960 TeX is a typesetting program; it does not print files directly, but
24961 produces output files called DVI files. To print a typeset document,
24962 you need a program to print DVI files. If your system has TeX
24963 installed, chances are it has such a program. The precise command to
24964 use depends on your system; `lpr -d' is common; another (for PostScript
24965 devices) is `dvips'. The DVI print command may require a file name
24966 without any extension or a `.dvi' extension.
24968 TeX also requires a macro definitions file called `texinfo.tex'.
24969 This file tells TeX how to typeset a document written in Texinfo
24970 format. On its own, TeX cannot either read or typeset a Texinfo file.
24971 `texinfo.tex' is distributed with GDB and is located in the
24972 `gdb-VERSION-NUMBER/texinfo' directory.
24974 If you have TeX and a DVI printer program installed, you can typeset
24975 and print this manual. First switch to the `gdb' subdirectory of the
24976 main source directory (for example, to `gdb-7.1-android-gg2/gdb') and
24981 Then give `gdb.dvi' to your DVI printing program.
24983 ---------- Footnotes ----------
24985 (1) In `gdb-7.1-android-gg2/gdb/refcard.ps' of the version
24986 7.1-android-gg2 release.
24989 File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top
24991 Appendix B Installing GDB
24992 *************************
24996 * Requirements:: Requirements for building GDB
24997 * Running Configure:: Invoking the GDB `configure' script
24998 * Separate Objdir:: Compiling GDB in another directory
24999 * Config Names:: Specifying names for hosts and targets
25000 * Configure Options:: Summary of options for configure
25001 * System-wide configuration:: Having a system-wide init file
25004 File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB
25006 B.1 Requirements for Building GDB
25007 =================================
25009 Building GDB requires various tools and packages to be available.
25010 Other packages will be used only if they are found.
25012 Tools/Packages Necessary for Building GDB
25013 =========================================
25016 GDB is written in ISO C90. It should be buildable with any
25017 working C90 compiler, e.g. GCC.
25020 Tools/Packages Optional for Building GDB
25021 ========================================
25024 GDB can use the Expat XML parsing library. This library may be
25025 included with your operating system distribution; if it is not, you
25026 can get the latest version from `http://expat.sourceforge.net'.
25027 The `configure' script will search for this library in several
25028 standard locations; if it is installed in an unusual path, you can
25029 use the `--with-libexpat-prefix' option to specify its location.
25033 * Remote protocol memory maps (*note Memory Map Format::)
25035 * Target descriptions (*note Target Descriptions::)
25037 * Remote shared library lists (*note Library List Format::)
25039 * MS-Windows shared libraries (*note Shared Libraries::)
25042 GDB will use the `zlib' library, if available, to read compressed
25043 debug sections. Some linkers, such as GNU gold, are capable of
25044 producing binaries with compressed debug sections. If GDB is
25045 compiled with `zlib', it will be able to read the debug
25046 information in such binaries.
25048 The `zlib' library is likely included with your operating system
25049 distribution; if it is not, you can get the latest version from
25053 GDB's features related to character sets (*note Character Sets::)
25054 require a functioning `iconv' implementation. If you are on a GNU
25055 system, then this is provided by the GNU C Library. Some other
25056 systems also provide a working `iconv'.
25058 On systems with `iconv', you can install GNU Libiconv. If you
25059 have previously installed Libiconv, you can use the
25060 `--with-libiconv-prefix' option to configure.
25062 GDB's top-level `configure' and `Makefile' will arrange to build
25063 Libiconv if a directory named `libiconv' appears in the top-most
25064 source directory. If Libiconv is built this way, and if the
25065 operating system does not provide a suitable `iconv'
25066 implementation, then the just-built library will automatically be
25067 used by GDB. One easy way to set this up is to download GNU
25068 Libiconv, unpack it, and then rename the directory holding the
25069 Libiconv source code to `libiconv'.
25072 File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB
25074 B.2 Invoking the GDB `configure' Script
25075 =======================================
25077 GDB comes with a `configure' script that automates the process of
25078 preparing GDB for installation; you can then use `make' to build the
25081 The GDB distribution includes all the source code you need for GDB
25082 in a single directory, whose name is usually composed by appending the
25083 version number to `gdb'.
25085 For example, the GDB version 7.1-android-gg2 distribution is in the
25086 `gdb-7.1-android-gg2' directory. That directory contains:
25088 `gdb-7.1-android-gg2/configure (and supporting files)'
25089 script for configuring GDB and all its supporting libraries
25091 `gdb-7.1-android-gg2/gdb'
25092 the source specific to GDB itself
25094 `gdb-7.1-android-gg2/bfd'
25095 source for the Binary File Descriptor library
25097 `gdb-7.1-android-gg2/include'
25100 `gdb-7.1-android-gg2/libiberty'
25101 source for the `-liberty' free software library
25103 `gdb-7.1-android-gg2/opcodes'
25104 source for the library of opcode tables and disassemblers
25106 `gdb-7.1-android-gg2/readline'
25107 source for the GNU command-line interface
25109 `gdb-7.1-android-gg2/glob'
25110 source for the GNU filename pattern-matching subroutine
25112 `gdb-7.1-android-gg2/mmalloc'
25113 source for the GNU memory-mapped malloc package
25115 The simplest way to configure and build GDB is to run `configure'
25116 from the `gdb-VERSION-NUMBER' source directory, which in this example
25117 is the `gdb-7.1-android-gg2' directory.
25119 First switch to the `gdb-VERSION-NUMBER' source directory if you are
25120 not already in it; then run `configure'. Pass the identifier for the
25121 platform on which GDB will run as an argument.
25125 cd gdb-7.1-android-gg2
25129 where HOST is an identifier such as `sun4' or `decstation', that
25130 identifies the platform where GDB will run. (You can often leave off
25131 HOST; `configure' tries to guess the correct value by examining your
25134 Running `configure HOST' and then running `make' builds the `bfd',
25135 `readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
25136 The configured source files, and the binaries, are left in the
25137 corresponding source directories.
25139 `configure' is a Bourne-shell (`/bin/sh') script; if your system
25140 does not recognize this automatically when you run a different shell,
25141 you may need to run `sh' on it explicitly:
25145 If you run `configure' from a directory that contains source
25146 directories for multiple libraries or programs, such as the
25147 `gdb-7.1-android-gg2' source directory for version 7.1-android-gg2,
25148 `configure' creates configuration files for every directory level
25149 underneath (unless you tell it not to, with the `--norecursion' option).
25151 You should run the `configure' script from the top directory in the
25152 source tree, the `gdb-VERSION-NUMBER' directory. If you run
25153 `configure' from one of the subdirectories, you will configure only
25154 that subdirectory. That is usually not what you want. In particular,
25155 if you run the first `configure' from the `gdb' subdirectory of the
25156 `gdb-VERSION-NUMBER' directory, you will omit the configuration of
25157 `bfd', `readline', and other sibling directories of the `gdb'
25158 subdirectory. This leads to build errors about missing include files
25159 such as `bfd/bfd.h'.
25161 You can install `gdb' anywhere; it has no hardwired paths. However,
25162 you should make sure that the shell on your path (named by the `SHELL'
25163 environment variable) is publicly readable. Remember that GDB uses the
25164 shell to start your program--some systems refuse to let GDB debug child
25165 processes whose programs are not readable.
25168 File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB
25170 B.3 Compiling GDB in Another Directory
25171 ======================================
25173 If you want to run GDB versions for several host or target machines,
25174 you need a different `gdb' compiled for each combination of host and
25175 target. `configure' is designed to make this easy by allowing you to
25176 generate each configuration in a separate subdirectory, rather than in
25177 the source directory. If your `make' program handles the `VPATH'
25178 feature (GNU `make' does), running `make' in each of these directories
25179 builds the `gdb' program specified there.
25181 To build `gdb' in a separate directory, run `configure' with the
25182 `--srcdir' option to specify where to find the source. (You also need
25183 to specify a path to find `configure' itself from your working
25184 directory. If the path to `configure' would be the same as the
25185 argument to `--srcdir', you can leave out the `--srcdir' option; it is
25188 For example, with version 7.1-android-gg2, you can build GDB in a
25189 separate directory for a Sun 4 like this:
25191 cd gdb-7.1-android-gg2
25194 ../gdb-7.1-android-gg2/configure sun4
25197 When `configure' builds a configuration using a remote source
25198 directory, it creates a tree for the binaries with the same structure
25199 (and using the same names) as the tree under the source directory. In
25200 the example, you'd find the Sun 4 library `libiberty.a' in the
25201 directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
25203 Make sure that your path to the `configure' script has just one
25204 instance of `gdb' in it. If your path to `configure' looks like
25205 `../gdb-7.1-android-gg2/gdb/configure', you are configuring only one
25206 subdirectory of GDB, not the whole package. This leads to build errors
25207 about missing include files such as `bfd/bfd.h'.
25209 One popular reason to build several GDB configurations in separate
25210 directories is to configure GDB for cross-compiling (where GDB runs on
25211 one machine--the "host"--while debugging programs that run on another
25212 machine--the "target"). You specify a cross-debugging target by giving
25213 the `--target=TARGET' option to `configure'.
25215 When you run `make' to build a program or library, you must run it
25216 in a configured directory--whatever directory you were in when you
25217 called `configure' (or one of its subdirectories).
25219 The `Makefile' that `configure' generates in each source directory
25220 also runs recursively. If you type `make' in a source directory such
25221 as `gdb-7.1-android-gg2' (or in a separate configured directory
25222 configured with `--srcdir=DIRNAME/gdb-7.1-android-gg2'), you will build
25223 all the required libraries, and then build GDB.
25225 When you have multiple hosts or targets configured in separate
25226 directories, you can run `make' on them in parallel (for example, if
25227 they are NFS-mounted on each of the hosts); they will not interfere
25231 File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB
25233 B.4 Specifying Names for Hosts and Targets
25234 ==========================================
25236 The specifications used for hosts and targets in the `configure' script
25237 are based on a three-part naming scheme, but some short predefined
25238 aliases are also supported. The full naming scheme encodes three pieces
25239 of information in the following pattern:
25241 ARCHITECTURE-VENDOR-OS
25243 For example, you can use the alias `sun4' as a HOST argument, or as
25244 the value for TARGET in a `--target=TARGET' option. The equivalent
25245 full name is `sparc-sun-sunos4'.
25247 The `configure' script accompanying GDB does not provide any query
25248 facility to list all supported host and target names or aliases.
25249 `configure' calls the Bourne shell script `config.sub' to map
25250 abbreviations to full names; you can read the script, if you wish, or
25251 you can use it to test your guesses on abbreviations--for example:
25253 % sh config.sub i386-linux
25255 % sh config.sub alpha-linux
25256 alpha-unknown-linux-gnu
25257 % sh config.sub hp9k700
25259 % sh config.sub sun4
25260 sparc-sun-sunos4.1.1
25261 % sh config.sub sun3
25262 m68k-sun-sunos4.1.1
25263 % sh config.sub i986v
25264 Invalid configuration `i986v': machine `i986v' not recognized
25266 `config.sub' is also distributed in the GDB source directory
25267 (`gdb-7.1-android-gg2', for version 7.1-android-gg2).
25270 File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB
25272 B.5 `configure' Options
25273 =======================
25275 Here is a summary of the `configure' options and arguments that are
25276 most often useful for building GDB. `configure' also has several other
25277 options not listed here. *note (configure.info)What Configure Does::,
25278 for a full explanation of `configure'.
25282 [--exec-prefix=DIR]
25284 [--norecursion] [--rm]
25288 You may introduce options with a single `-' rather than `--' if you
25289 prefer; but you may abbreviate option names if you use `--'.
25292 Display a quick summary of how to invoke `configure'.
25295 Configure the source to install programs and files under directory
25298 `--exec-prefix=DIR'
25299 Configure the source to install programs under directory `DIR'.
25302 *Warning: using this option requires GNU `make', or another `make'
25303 that implements the `VPATH' feature.*
25304 Use this option to make configurations in directories separate
25305 from the GDB source directories. Among other things, you can use
25306 this to build (or maintain) several configurations simultaneously,
25307 in separate directories. `configure' writes
25308 configuration-specific files in the current directory, but
25309 arranges for them to use the source in the directory DIRNAME.
25310 `configure' creates directories under the working directory in
25311 parallel to the source directories below DIRNAME.
25314 Configure only the directory level where `configure' is executed;
25315 do not propagate configuration to subdirectories.
25318 Configure GDB for cross-debugging programs running on the specified
25319 TARGET. Without this option, GDB is configured to debug programs
25320 that run on the same machine (HOST) as GDB itself.
25322 There is no convenient way to generate a list of all available
25326 Configure GDB to run on the specified HOST.
25328 There is no convenient way to generate a list of all available
25331 There are many other options available as well, but they are
25332 generally needed for special purposes only.
25335 File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB
25337 B.6 System-wide configuration and settings
25338 ==========================================
25340 GDB can be configured to have a system-wide init file; this file will
25341 be read and executed at startup (*note What GDB does during startup:
25344 Here is the corresponding configure option:
25346 `--with-system-gdbinit=FILE'
25347 Specify that the default location of the system-wide init file is
25350 If GDB has been configured with the option `--prefix=$prefix', it
25351 may be subject to relocation. Two possible cases:
25353 * If the default location of this init file contains `$prefix', it
25354 will be subject to relocation. Suppose that the configure options
25355 are `--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit';
25356 if GDB is moved from `$prefix' to `$install', the system init file
25357 is looked for as `$install/etc/gdbinit' instead of
25358 `$prefix/etc/gdbinit'.
25360 * By contrast, if the default location does not contain the prefix,
25361 it will not be relocated. E.g. if GDB has been configured with
25362 `--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit',
25363 then GDB will always look for `/usr/share/gdb/gdbinit', wherever
25367 File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top
25369 Appendix C Maintenance Commands
25370 *******************************
25372 In addition to commands intended for GDB users, GDB includes a number
25373 of commands intended for GDB developers, that are not documented
25374 elsewhere in this manual. These commands are provided here for
25375 reference. (For commands that turn on debugging messages, see *note
25376 Debugging Output::.)
25378 `maint agent EXPRESSION'
25379 `maint agent-eval EXPRESSION'
25380 Translate the given EXPRESSION into remote agent bytecodes. This
25381 command is useful for debugging the Agent Expression mechanism
25382 (*note Agent Expressions::). The `agent' version produces an
25383 expression useful for data collection, such as by tracepoints,
25384 while `maint agent-eval' produces an expression that evaluates
25385 directly to a result. For instance, a collection expression for
25386 `globa + globb' will include bytecodes to record four bytes of
25387 memory at each of the addresses of `globa' and `globb', while
25388 discarding the result of the addition, while an evaluation
25389 expression will do the addition and return the sum.
25391 `maint info breakpoints'
25392 Using the same format as `info breakpoints', display both the
25393 breakpoints you've set explicitly, and those GDB is using for
25394 internal purposes. Internal breakpoints are shown with negative
25395 breakpoint numbers. The type column identifies what kind of
25396 breakpoint is shown:
25399 Normal, explicitly set breakpoint.
25402 Normal, explicitly set watchpoint.
25405 Internal breakpoint, used to handle correctly stepping through
25409 Internal breakpoint at the target of a `longjmp'.
25412 Temporary internal breakpoint used by the GDB `until' command.
25415 Temporary internal breakpoint used by the GDB `finish'
25419 Shared library events.
25422 `set displaced-stepping'
25423 `show displaced-stepping'
25424 Control whether or not GDB will do "displaced stepping" if the
25425 target supports it. Displaced stepping is a way to single-step
25426 over breakpoints without removing them from the inferior, by
25427 executing an out-of-line copy of the instruction that was
25428 originally at the breakpoint location. It is also known as
25429 out-of-line single-stepping.
25431 `set displaced-stepping on'
25432 If the target architecture supports it, GDB will use
25433 displaced stepping to step over breakpoints.
25435 `set displaced-stepping off'
25436 GDB will not use displaced stepping to step over breakpoints,
25437 even if such is supported by the target architecture.
25439 `set displaced-stepping auto'
25440 This is the default mode. GDB will use displaced stepping
25441 only if non-stop mode is active (*note Non-Stop Mode::) and
25442 the target architecture supports displaced stepping.
25444 `maint check-symtabs'
25445 Check the consistency of psymtabs and symtabs.
25447 `maint cplus first_component NAME'
25448 Print the first C++ class/namespace component of NAME.
25450 `maint cplus namespace'
25451 Print the list of possible C++ namespaces.
25453 `maint demangle NAME'
25454 Demangle a C++ or Objective-C mangled NAME.
25456 `maint deprecate COMMAND [REPLACEMENT]'
25457 `maint undeprecate COMMAND'
25458 Deprecate or undeprecate the named COMMAND. Deprecated commands
25459 cause GDB to issue a warning when you use them. The optional
25460 argument REPLACEMENT says which newer command should be used in
25461 favor of the deprecated one; if it is given, GDB will mention the
25462 replacement as part of the warning.
25465 Cause a fatal signal in the debugger and force it to dump its core.
25466 This is supported only on systems which support aborting a program
25467 with the `SIGQUIT' signal.
25469 `maint internal-error [MESSAGE-TEXT]'
25470 `maint internal-warning [MESSAGE-TEXT]'
25471 Cause GDB to call the internal function `internal_error' or
25472 `internal_warning' and hence behave as though an internal error or
25473 internal warning has been detected. In addition to reporting the
25474 internal problem, these functions give the user the opportunity to
25475 either quit GDB or create a core file of the current GDB session.
25477 These commands take an optional parameter MESSAGE-TEXT that is
25478 used as the text of the error or warning message.
25480 Here's an example of using `internal-error':
25482 (gdb) maint internal-error testing, 1, 2
25483 .../maint.c:121: internal-error: testing, 1, 2
25484 A problem internal to GDB has been detected. Further
25485 debugging may prove unreliable.
25486 Quit this debugging session? (y or n) n
25487 Create a core file? (y or n) n
25490 `maint set internal-error ACTION [ask|yes|no]'
25491 `maint show internal-error ACTION'
25492 `maint set internal-warning ACTION [ask|yes|no]'
25493 `maint show internal-warning ACTION'
25494 When GDB reports an internal problem (error or warning) it gives
25495 the user the opportunity to both quit GDB and create a core file
25496 of the current GDB session. These commands let you override the
25497 default behaviour for each particular ACTION, described in the
25501 You can specify that GDB should always (yes) or never (no)
25502 quit. The default is to ask the user what to do.
25505 You can specify that GDB should always (yes) or never (no)
25506 create a core file. The default is to ask the user what to
25509 `maint packet TEXT'
25510 If GDB is talking to an inferior via the serial protocol, then
25511 this command sends the string TEXT to the inferior, and displays
25512 the response packet. GDB supplies the initial `$' character, the
25513 terminating `#' character, and the checksum.
25515 `maint print architecture [FILE]'
25516 Print the entire architecture configuration. The optional argument
25517 FILE names the file where the output goes.
25519 `maint print c-tdesc'
25520 Print the current target description (*note Target Descriptions::)
25521 as a C source file. The created source file can be used in GDB
25522 when an XML parser is not available to parse the description.
25524 `maint print dummy-frames'
25525 Prints the contents of GDB's internal dummy-frame stack.
25529 (gdb) print add(2,3)
25530 Breakpoint 2, add (a=2, b=3) at ...
25532 The program being debugged stopped while in a function called from GDB.
25534 (gdb) maint print dummy-frames
25535 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
25536 top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c}
25537 call_lo=0x01014000 call_hi=0x01014001
25540 Takes an optional file parameter.
25542 `maint print registers [FILE]'
25543 `maint print raw-registers [FILE]'
25544 `maint print cooked-registers [FILE]'
25545 `maint print register-groups [FILE]'
25546 Print GDB's internal register data structures.
25548 The command `maint print raw-registers' includes the contents of
25549 the raw register cache; the command `maint print cooked-registers'
25550 includes the (cooked) value of all registers; and the command
25551 `maint print register-groups' includes the groups that each
25552 register is a member of. *Note Registers: (gdbint)Registers.
25554 These commands take an optional parameter, a file name to which to
25555 write the information.
25557 `maint print reggroups [FILE]'
25558 Print GDB's internal register group data structures. The optional
25559 argument FILE tells to what file to write the information.
25561 The register groups info looks like this:
25563 (gdb) maint print reggroups
25574 This command forces GDB to flush its internal register cache.
25576 `maint print objfiles'
25577 Print a dump of all known object files. For each object file, this
25578 command prints its name, address in memory, and all of its psymtabs
25581 `maint print statistics'
25582 This command prints, for each object file in the program, various
25583 data about that object file followed by the byte cache ("bcache")
25584 statistics for the object file. The objfile data includes the
25585 number of minimal, partial, full, and stabs symbols, the number of
25586 types defined by the objfile, the number of as yet unexpanded psym
25587 tables, the number of line tables and string tables, and the
25588 amount of memory used by the various tables. The bcache
25589 statistics include the counts, sizes, and counts of duplicates of
25590 all and unique objects, max, average, and median entry size, total
25591 memory used and its overhead and savings, and various measures of
25592 the hash table size and chain lengths.
25594 `maint print target-stack'
25595 A "target" is an interface between the debugger and a particular
25596 kind of file or process. Targets can be stacked in "strata", so
25597 that more than one target can potentially respond to a request.
25598 In particular, memory accesses will walk down the stack of targets
25599 until they find a target that is interested in handling that
25600 particular address.
25602 This command prints a short description of each layer that was
25603 pushed on the "target stack", starting from the top layer down to
25606 `maint print type EXPR'
25607 Print the type chain for a type specified by EXPR. The argument
25608 can be either a type name or a symbol. If it is a symbol, the
25609 type of that symbol is described. The type chain produced by this
25610 command is a recursive definition of the data type as stored in
25611 GDB's data structures, including its flags and contained types.
25613 `maint set dwarf2 max-cache-age'
25614 `maint show dwarf2 max-cache-age'
25615 Control the DWARF 2 compilation unit cache.
25617 In object files with inter-compilation-unit references, such as
25618 those produced by the GCC option `-feliminate-dwarf2-dups', the
25619 DWARF 2 reader needs to frequently refer to previously read
25620 compilation units. This setting controls how long a compilation
25621 unit will remain in the cache if it is not referenced. A higher
25622 limit means that cached compilation units will be stored in memory
25623 longer, and more total memory will be used. Setting it to zero
25624 disables caching, which will slow down GDB startup, but reduce
25625 memory consumption.
25627 `maint set profile'
25628 `maint show profile'
25629 Control profiling of GDB.
25631 Profiling will be disabled until you use the `maint set profile'
25632 command to enable it. When you enable profiling, the system will
25633 begin collecting timing and execution count data; when you disable
25634 profiling or exit GDB, the results will be written to a log file.
25635 Remember that if you use profiling, GDB will overwrite the
25636 profiling log file (often called `gmon.out'). If you have a
25637 record of important profiling data in a `gmon.out' file, be sure
25638 to move it to a safe location.
25640 Configuring with `--enable-profiling' arranges for GDB to be
25641 compiled with the `-pg' compiler option.
25643 `maint set show-debug-regs'
25644 `maint show show-debug-regs'
25645 Control whether to show variables that mirror the hardware debug
25646 registers. Use `ON' to enable, `OFF' to disable. If enabled, the
25647 debug registers values are shown when GDB inserts or removes a
25648 hardware breakpoint or watchpoint, and when the inferior triggers
25649 a hardware-assisted breakpoint or watchpoint.
25652 Control whether to display memory usage for each command. If set
25653 to a nonzero value, GDB will display how much memory each command
25654 took, following the command's own output. This can also be
25655 requested by invoking GDB with the `--statistics' command-line
25656 switch (*note Mode Options::).
25659 Control whether to display the execution time for each command. If
25660 set to a nonzero value, GDB will display how much time it took to
25661 execute each command, following the command's own output. The
25662 time is not printed for the commands that run the target, since
25663 there's no mechanism currently to compute how much time was spend
25664 by GDB and how much time was spend by the program been debugged.
25665 it's not possibly currently This can also be requested by invoking
25666 GDB with the `--statistics' command-line switch (*note Mode
25669 `maint translate-address [SECTION] ADDR'
25670 Find the symbol stored at the location specified by the address
25671 ADDR and an optional section name SECTION. If found, GDB prints
25672 the name of the closest symbol and an offset from the symbol's
25673 location to the specified address. This is similar to the `info
25674 address' command (*note Symbols::), except that this command also
25675 allows to find symbols in other sections.
25677 If section was not specified, the section in which the symbol was
25678 found is also printed. For dynamically linked executables, the
25679 name of executable or shared library containing the symbol is
25683 The following command is useful for non-interactive invocations of
25684 GDB, such as in the test suite.
25686 `set watchdog NSEC'
25687 Set the maximum number of seconds GDB will wait for the target
25688 operation to finish. If this time expires, GDB reports and error
25689 and the command is aborted.
25692 Show the current setting of the target wait timeout.
25695 File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top
25697 Appendix D GDB Remote Serial Protocol
25698 *************************************
25704 * Stop Reply Packets::
25705 * General Query Packets::
25706 * Architecture-Specific Protocol Details::
25707 * Tracepoint Packets::
25708 * Host I/O Packets::
25710 * Notification Packets::
25711 * Remote Non-Stop::
25712 * Packet Acknowledgment::
25714 * File-I/O Remote Protocol Extension::
25715 * Library List Format::
25716 * Memory Map Format::
25717 * Thread List Format::
25720 File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol
25725 There may be occasions when you need to know something about the
25726 protocol--for example, if there is only one serial port to your target
25727 machine, you might want your program to do something special if it
25728 recognizes a packet meant for GDB.
25730 In the examples below, `->' and `<-' are used to indicate
25731 transmitted and received data, respectively.
25733 All GDB commands and responses (other than acknowledgments and
25734 notifications, see *note Notification Packets::) are sent as a PACKET.
25735 A PACKET is introduced with the character `$', the actual PACKET-DATA,
25736 and the terminating character `#' followed by a two-digit CHECKSUM:
25738 `$'PACKET-DATA`#'CHECKSUM
25739 The two-digit CHECKSUM is computed as the modulo 256 sum of all
25740 characters between the leading `$' and the trailing `#' (an eight bit
25741 unsigned checksum).
25743 Implementors should note that prior to GDB 5.0 the protocol
25744 specification also included an optional two-digit SEQUENCE-ID:
25746 `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM
25748 That SEQUENCE-ID was appended to the acknowledgment. GDB has never
25749 output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0
25750 must not accept SEQUENCE-ID.
25752 When either the host or the target machine receives a packet, the
25753 first response expected is an acknowledgment: either `+' (to indicate
25754 the package was received correctly) or `-' (to request retransmission):
25756 -> `$'PACKET-DATA`#'CHECKSUM
25758 The `+'/`-' acknowledgments can be disabled once a connection is
25759 established. *Note Packet Acknowledgment::, for details.
25761 The host (GDB) sends COMMANDs, and the target (the debugging stub
25762 incorporated in your program) sends a RESPONSE. In the case of step
25763 and continue COMMANDs, the response is only sent when the operation has
25764 completed, and the target has again stopped all threads in all attached
25765 processes. This is the default all-stop mode behavior, but the remote
25766 protocol also supports GDB's non-stop execution mode; see *note Remote
25767 Non-Stop::, for details.
25769 PACKET-DATA consists of a sequence of characters with the exception
25770 of `#' and `$' (see `X' packet for additional exceptions).
25772 Fields within the packet should be separated using `,' `;' or `:'.
25773 Except where otherwise noted all numbers are represented in HEX with
25774 leading zeros suppressed.
25776 Implementors should note that prior to GDB 5.0, the character `:'
25777 could not appear as the third character in a packet (as it would
25778 potentially conflict with the SEQUENCE-ID).
25780 Binary data in most packets is encoded either as two hexadecimal
25781 digits per byte of binary data. This allowed the traditional remote
25782 protocol to work over connections which were only seven-bit clean.
25783 Some packets designed more recently assume an eight-bit clean
25784 connection, and use a more efficient encoding to send and receive
25787 The binary data representation uses `7d' (ASCII `}') as an escape
25788 character. Any escaped byte is transmitted as the escape character
25789 followed by the original character XORed with `0x20'. For example, the
25790 byte `0x7d' would be transmitted as the two bytes `0x7d 0x5d'. The
25791 bytes `0x23' (ASCII `#'), `0x24' (ASCII `$'), and `0x7d' (ASCII `}')
25792 must always be escaped. Responses sent by the stub must also escape
25793 `0x2a' (ASCII `*'), so that it is not interpreted as the start of a
25794 run-length encoded sequence (described next).
25796 Response DATA can be run-length encoded to save space. Run-length
25797 encoding replaces runs of identical characters with one instance of the
25798 repeated character, followed by a `*' and a repeat count. The repeat
25799 count is itself sent encoded, to avoid binary characters in DATA: a
25800 value of N is sent as `N+29'. For a repeat count greater or equal to
25801 3, this produces a printable ASCII character, e.g. a space (ASCII code
25802 32) for a repeat count of 3. (This is because run-length encoding
25803 starts to win for counts 3 or more.) Thus, for example, `0* ' is a
25804 run-length encoding of "0000": the space character after `*' means
25805 repeat the leading `0' `32 - 29 = 3' more times.
25807 The printable characters `#' and `$' or with a numeric value greater
25808 than 126 must not be used. Runs of six repeats (`#') or seven repeats
25809 (`$') can be expanded using a repeat count of only five (`"'). For
25810 example, `00000000' can be encoded as `0*"00'.
25812 The error response returned for some packets includes a two character
25813 error number. That number is not well defined.
25815 For any COMMAND not supported by the stub, an empty response
25816 (`$#00') should be returned. That way it is possible to extend the
25817 protocol. A newer GDB can tell if a packet is supported based on that
25820 A stub is required to support the `g', `G', `m', `M', `c', and `s'
25821 COMMANDs. All other COMMANDs are optional.
25824 File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol
25829 The following table provides a complete list of all currently defined
25830 COMMANDs and their corresponding response DATA. *Note File-I/O Remote
25831 Protocol Extension::, for details about the File I/O extension of the
25834 Each packet's description has a template showing the packet's overall
25835 syntax, followed by an explanation of the packet's meaning. We include
25836 spaces in some of the templates for clarity; these are not part of the
25837 packet's syntax. No GDB packet uses spaces to separate its components.
25838 For example, a template like `foo BAR BAZ' describes a packet beginning
25839 with the three ASCII bytes `foo', followed by a BAR, followed directly
25840 by a BAZ. GDB does not transmit a space character between the `foo'
25841 and the BAR, or between the BAR and the BAZ.
25843 Several packets and replies include a THREAD-ID field to identify a
25844 thread. Normally these are positive numbers with a target-specific
25845 interpretation, formatted as big-endian hex strings. A THREAD-ID can
25846 also be a literal `-1' to indicate all threads, or `0' to pick any
25849 In addition, the remote protocol supports a multiprocess feature in
25850 which the THREAD-ID syntax is extended to optionally include both
25851 process and thread ID fields, as `pPID.TID'. The PID (process) and TID
25852 (thread) components each have the format described above: a positive
25853 number with target-specific interpretation formatted as a big-endian
25854 hex string, literal `-1' to indicate all processes or threads
25855 (respectively), or `0' to indicate an arbitrary process or thread.
25856 Specifying just a process, as `pPID', is equivalent to `pPID.-1'. It
25857 is an error to specify all processes but a specific thread, such as
25858 `p-1.TID'. Note that the `p' prefix is _not_ used for those packets
25859 and replies explicitly documented to include a process ID, rather than
25862 The multiprocess THREAD-ID syntax extensions are only used if both
25863 GDB and the stub report support for the `multiprocess' feature using
25864 `qSupported'. *Note multiprocess extensions::, for more information.
25866 Note that all packet forms beginning with an upper- or lower-case
25867 letter, other than those described here, are reserved for future use.
25869 Here are the packet descriptions.
25872 Enable extended mode. In extended mode, the remote server is made
25873 persistent. The `R' packet is used to restart the program being
25878 The remote target both supports and has enabled extended mode.
25881 Indicate the reason the target halted. The reply is the same as
25882 for step and continue. This packet has a special interpretation
25883 when the target is in non-stop mode; see *note Remote Non-Stop::.
25885 Reply: *Note Stop Reply Packets::, for the reply specifications.
25887 `A ARGLEN,ARGNUM,ARG,...'
25888 Initialized `argv[]' array passed into program. ARGLEN specifies
25889 the number of bytes in the hex encoded byte stream ARG. See
25890 `gdbserver' for more details.
25894 The arguments were set.
25900 (Don't use this packet; its behavior is not well-defined.) Change
25901 the serial line speed to BAUD.
25903 JTC: _When does the transport layer state change? When it's
25904 received, or after the ACK is transmitted. In either case, there
25905 are problems if the command or the acknowledgment packet is
25908 Stan: _If people really wanted to add something like this, and get
25909 it working for the first time, they ought to modify ser-unix.c to
25910 send some kind of out-of-band message to a specially-setup stub
25911 and have the switch happen "in between" packets, so that from
25912 remote protocol's point of view, nothing actually happened._
25915 Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR.
25917 Don't use this packet. Use the `Z' and `z' packets instead (*note
25918 insert breakpoint or watchpoint packet::).
25921 Backward continue. Execute the target system in reverse. No
25922 parameter. *Note Reverse Execution::, for more information.
25924 Reply: *Note Stop Reply Packets::, for the reply specifications.
25927 Backward single step. Execute one instruction in reverse. No
25928 parameter. *Note Reverse Execution::, for more information.
25930 Reply: *Note Stop Reply Packets::, for the reply specifications.
25933 Continue. ADDR is address to resume. If ADDR is omitted, resume
25934 at current address.
25936 Reply: *Note Stop Reply Packets::, for the reply specifications.
25939 Continue with signal SIG (hex signal number). If `;ADDR' is
25940 omitted, resume at same address.
25942 Reply: *Note Stop Reply Packets::, for the reply specifications.
25947 Don't use this packet; instead, define a general set packet (*note
25948 General Query Packets::).
25952 The first form of the packet is used to detach GDB from the remote
25953 system. It is sent to the remote target before GDB disconnects
25954 via the `detach' command.
25956 The second form, including a process ID, is used when multiprocess
25957 protocol extensions are enabled (*note multiprocess extensions::),
25958 to detach only a specific process. The PID is specified as a
25959 big-endian hex string.
25969 A reply from GDB to an `F' packet sent by the target. This is
25970 part of the File-I/O protocol extension. *Note File-I/O Remote
25971 Protocol Extension::, for the specification.
25974 Read general registers.
25978 Each byte of register data is described by two hex digits.
25979 The bytes with the register are transmitted in target byte
25980 order. The size of each register and their position within
25981 the `g' packet are determined by the GDB internal gdbarch
25982 functions `DEPRECATED_REGISTER_RAW_SIZE' and
25983 `gdbarch_register_name'. The specification of several
25984 standard `g' packets is specified below.
25990 Write general registers. *Note read registers packet::, for a
25991 description of the XX... data.
26001 Set thread for subsequent operations (`m', `M', `g', `G', et.al.).
26002 C depends on the operation to be performed: it should be `c' for
26003 step and continue operations, `g' for other operations. The
26004 thread designator THREAD-ID has the format and interpretation
26005 described in *note thread-id syntax::.
26015 Step the remote target by a single clock cycle. If `,NNN' is
26016 present, cycle step NNN cycles. If ADDR is present, cycle step
26017 starting at that address.
26020 Signal, then cycle step. *Note step with signal packet::. *Note
26021 cycle step packet::.
26026 FIXME: _There is no description of how to operate when a specific
26027 thread context has been selected (i.e. does 'k' kill only that
26031 Read LENGTH bytes of memory starting at address ADDR. Note that
26032 ADDR may not be aligned to any particular boundary.
26034 The stub need not use any particular size or alignment when
26035 gathering data from memory for the response; even if ADDR is
26036 word-aligned and LENGTH is a multiple of the word size, the stub
26037 is free to use byte accesses, or not. For this reason, this
26038 packet may not be suitable for accessing memory-mapped I/O devices.
26042 Memory contents; each byte is transmitted as a two-digit
26043 hexadecimal number. The reply may contain fewer bytes than
26044 requested if the server was able to read only part of the
26050 `M ADDR,LENGTH:XX...'
26051 Write LENGTH bytes of memory starting at address ADDR. XX... is
26052 the data; each byte is transmitted as a two-digit hexadecimal
26060 for an error (this includes the case where only part of the
26064 Read the value of register N; N is in hex. *Note read registers
26065 packet::, for a description of how the returned register value is
26070 the register's value
26076 Indicating an unrecognized QUERY.
26079 Write register N... with value R.... The register number N is in
26080 hexadecimal, and R... contains two hex digits for each byte in the
26081 register (target byte order).
26092 General query (`q') and set (`Q'). These packets are described
26093 fully in *note General Query Packets::.
26096 Reset the entire system.
26098 Don't use this packet; use the `R' packet instead.
26101 Restart the program being debugged. XX, while needed, is ignored.
26102 This packet is only available in extended mode (*note extended
26105 The `R' packet has no reply.
26108 Single step. ADDR is the address at which to resume. If ADDR is
26109 omitted, resume at same address.
26111 Reply: *Note Stop Reply Packets::, for the reply specifications.
26114 Step with signal. This is analogous to the `C' packet, but
26115 requests a single-step, rather than a normal resumption of
26118 Reply: *Note Stop Reply Packets::, for the reply specifications.
26121 Search backwards starting at address ADDR for a match with pattern
26122 PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3
26126 Find out if the thread THREAD-ID is alive. *Note thread-id
26131 thread is still alive
26137 Packets starting with `v' are identified by a multi-letter name,
26138 up to the first `;' or `?' (or the end of the packet).
26141 Attach to a new process with the specified process ID PID. The
26142 process ID is a hexadecimal integer identifying the process. In
26143 all-stop mode, all threads in the attached process are stopped; in
26144 non-stop mode, it may be attached without being stopped if that is
26145 supported by the target.
26147 This packet is only available in extended mode (*note extended
26155 for success in all-stop mode (*note Stop Reply Packets::)
26158 for success in non-stop mode (*note Remote Non-Stop::)
26160 `vCont[;ACTION[:THREAD-ID]]...'
26161 Resume the inferior, specifying different actions for each thread.
26162 If an action is specified with no THREAD-ID, then it is applied to
26163 any threads that don't have a specific action specified; if no
26164 default action is specified then other threads should remain
26165 stopped in all-stop mode and in their current state in non-stop
26166 mode. Specifying multiple default actions is an error; specifying
26167 no actions is also an error. Thread IDs are specified using the
26168 syntax described in *note thread-id syntax::.
26170 Currently supported actions are:
26176 Continue with signal SIG. The signal SIG should be two hex
26183 Step with signal SIG. The signal SIG should be two hex
26189 The optional argument ADDR normally associated with the `c', `C',
26190 `s', and `S' packets is not supported in `vCont'.
26192 The `t' action is only relevant in non-stop mode (*note Remote
26193 Non-Stop::) and may be ignored by the stub otherwise. A stop
26194 reply should be generated for any affected thread not already
26195 stopped. When a thread is stopped by means of a `t' action, the
26196 corresponding stop reply should indicate that the thread has
26197 stopped with signal `0', regardless of whether the target uses
26198 some other signal as an implementation detail.
26200 Reply: *Note Stop Reply Packets::, for the reply specifications.
26203 Request a list of actions supported by the `vCont' packet.
26206 `vCont[;ACTION...]'
26207 The `vCont' packet is supported. Each ACTION is a supported
26208 command in the `vCont' packet.
26211 The `vCont' packet is not supported.
26213 `vFile:OPERATION:PARAMETER...'
26214 Perform a file operation on the target system. For details, see
26215 *note Host I/O Packets::.
26217 `vFlashErase:ADDR,LENGTH'
26218 Direct the stub to erase LENGTH bytes of flash starting at ADDR.
26219 The region may enclose any number of flash blocks, but its start
26220 and end must fall on block boundaries, as indicated by the flash
26221 block size appearing in the memory map (*note Memory Map
26222 Format::). GDB groups flash memory programming operations
26223 together, and sends a `vFlashDone' request after each group; the
26224 stub is allowed to delay erase operation until the `vFlashDone'
26225 packet is received.
26227 The stub must support `vCont' if it reports support for
26228 multiprocess extensions (*note multiprocess extensions::). Note
26229 that in this case `vCont' actions can be specified to apply to all
26230 threads in a process by using the `pPID.-1' form of the THREAD-ID.
26239 `vFlashWrite:ADDR:XX...'
26240 Direct the stub to write data to flash address ADDR. The data is
26241 passed in binary form using the same encoding as for the `X'
26242 packet (*note Binary Data::). The memory ranges specified by
26243 `vFlashWrite' packets preceding a `vFlashDone' packet must not
26244 overlap, and must appear in order of increasing addresses
26245 (although `vFlashErase' packets for higher addresses may already
26246 have been received; the ordering is guaranteed only between
26247 `vFlashWrite' packets). If a packet writes to an address that was
26248 neither erased by a preceding `vFlashErase' packet nor by some
26249 other target-specific method, the results are unpredictable.
26256 for vFlashWrite addressing non-flash memory
26262 Indicate to the stub that flash programming operation is finished.
26263 The stub is permitted to delay or batch the effects of a group of
26264 `vFlashErase' and `vFlashWrite' packets until a `vFlashDone'
26265 packet is received. The contents of the affected regions of flash
26266 memory are unpredictable until the `vFlashDone' request is
26270 Kill the process with the specified process ID. PID is a
26271 hexadecimal integer identifying the process. This packet is used
26272 in preference to `k' when multiprocess protocol extensions are
26273 supported; see *note multiprocess extensions::.
26282 `vRun;FILENAME[;ARGUMENT]...'
26283 Run the program FILENAME, passing it each ARGUMENT on its command
26284 line. The file and arguments are hex-encoded strings. If
26285 FILENAME is an empty string, the stub may use a default program
26286 (e.g. the last program run). The program is created in the stopped
26289 This packet is only available in extended mode (*note extended
26297 for success (*note Stop Reply Packets::)
26300 In non-stop mode (*note Remote Non-Stop::), acknowledge a previous
26301 stop reply and prompt for the stub to report another one.
26305 if there is another unreported stop event (*note Stop Reply
26309 if there are no unreported stop events
26311 `X ADDR,LENGTH:XX...'
26312 Write data to memory, where the data is transmitted in binary.
26313 ADDR is address, LENGTH is number of bytes, `XX...' is binary data
26314 (*note Binary Data::).
26325 Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint
26326 starting at address ADDRESS of kind KIND.
26328 Each breakpoint and watchpoint packet TYPE is documented
26331 _Implementation notes: A remote target shall return an empty string
26332 for an unrecognized breakpoint or watchpoint packet TYPE. A
26333 remote target shall support either both or neither of a given
26334 `ZTYPE...' and `zTYPE...' packet pair. To avoid potential
26335 problems with duplicate packets, the operations should be
26336 implemented in an idempotent way._
26340 Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR
26343 A memory breakpoint is implemented by replacing the instruction at
26344 ADDR with a software breakpoint or trap instruction. The KIND is
26345 target-specific and typically indicates the size of the breakpoint
26346 in bytes that should be inserted. E.g., the ARM and MIPS can
26347 insert either a 2 or 4 byte breakpoint. Some architectures have
26348 additional meanings for KIND; see *note Architecture-Specific
26349 Protocol Details::.
26351 _Implementation note: It is possible for a target to copy or move
26352 code that contains memory breakpoints (e.g., when implementing
26353 overlays). The behavior of this packet, in the presence of such a
26354 target, is not defined._
26368 Insert (`Z1') or remove (`z1') a hardware breakpoint at address
26371 A hardware breakpoint is implemented using a mechanism that is not
26372 dependant on being able to modify the target's memory. KIND has
26373 the same meaning as in `Z0' packets.
26375 _Implementation note: A hardware breakpoint is not affected by code
26390 Insert (`Z2') or remove (`z2') a write watchpoint at ADDR. KIND
26391 is interpreted as the number of bytes to watch.
26405 Insert (`Z3') or remove (`z3') a read watchpoint at ADDR. KIND is
26406 interpreted as the number of bytes to watch.
26420 Insert (`Z4') or remove (`z4') an access watchpoint at ADDR. KIND
26421 is interpreted as the number of bytes to watch.
26435 File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol
26437 D.3 Stop Reply Packets
26438 ======================
26440 The `C', `c', `S', `s', `vCont', `vAttach', `vRun', `vStopped', and `?'
26441 packets can receive any of the below as a reply. Except for `?' and
26442 `vStopped', that reply is only returned when the target halts. In the
26443 below the exact meaning of "signal number" is defined by the header
26444 `include/gdb/signals.h' in the GDB source code.
26446 As in the description of request packets, we include spaces in the
26447 reply templates for clarity; these are not part of the reply packet's
26448 syntax. No GDB stop reply packet uses spaces to separate its
26452 The program received signal number AA (a two-digit hexadecimal
26453 number). This is equivalent to a `T' response with no N:R pairs.
26455 `T AA N1:R1;N2:R2;...'
26456 The program received signal number AA (a two-digit hexadecimal
26457 number). This is equivalent to an `S' response, except that the
26458 `N:R' pairs can carry values of important registers and other
26459 information directly in the stop reply packet, reducing round-trip
26460 latency. Single-step and breakpoint traps are reported this way.
26461 Each `N:R' pair is interpreted as follows:
26463 * If N is a hexadecimal number, it is a register number, and the
26464 corresponding R gives that register's value. R is a series
26465 of bytes in target byte order, with each byte given by a
26466 two-digit hex number.
26468 * If N is `thread', then R is the THREAD-ID of the stopped
26469 thread, as specified in *note thread-id syntax::.
26471 * If N is `core', then R is the hexadecimal number of the core
26472 on which the stop event was detected.
26474 * If N is a recognized "stop reason", it describes a more
26475 specific event that stopped the target. The currently
26476 defined stop reasons are listed below. AA should be `05',
26477 the trap signal. At most one stop reason should be present.
26479 * Otherwise, GDB should ignore this `N:R' pair and go on to the
26480 next; this allows us to extend the protocol in the future.
26482 The currently defined stop reasons are:
26487 The packet indicates a watchpoint hit, and R is the data
26491 The packet indicates that the loaded libraries have changed.
26492 GDB should use `qXfer:libraries:read' to fetch a new list of
26493 loaded libraries. R is ignored.
26496 The packet indicates that the target cannot continue replaying
26497 logged execution events, because it has reached the end (or
26498 the beginning when executing backward) of the log. The value
26499 of R will be either `begin' or `end'. *Note Reverse
26500 Execution::, for more information.
26503 `W AA ; process:PID'
26504 The process exited, and AA is the exit status. This is only
26505 applicable to certain targets.
26507 The second form of the response, including the process ID of the
26508 exited process, can be used only when GDB has reported support for
26509 multiprocess protocol extensions; see *note multiprocess
26510 extensions::. The PID is formatted as a big-endian hex string.
26513 `X AA ; process:PID'
26514 The process terminated with signal AA.
26516 The second form of the response, including the process ID of the
26517 terminated process, can be used only when GDB has reported support
26518 for multiprocess protocol extensions; see *note multiprocess
26519 extensions::. The PID is formatted as a big-endian hex string.
26522 `XX...' is hex encoding of ASCII data, to be written as the
26523 program's console output. This can happen at any time while the
26524 program is running and the debugger should continue to wait for
26525 `W', `T', etc. This reply is not permitted in non-stop mode.
26527 `F CALL-ID,PARAMETER...'
26528 CALL-ID is the identifier which says which host system call should
26529 be called. This is just the name of the function. Translation
26530 into the correct system call is only applicable as it's defined in
26531 GDB. *Note File-I/O Remote Protocol Extension::, for a list of
26532 implemented system calls.
26534 `PARAMETER...' is a list of parameters as defined for this very
26537 The target replies with this packet when it expects GDB to call a
26538 host system call on behalf of the target. GDB replies with an
26539 appropriate `F' packet and keeps up waiting for the next reply
26540 packet from the target. The latest `C', `c', `S' or `s' action is
26541 expected to be continued. *Note File-I/O Remote Protocol
26542 Extension::, for more details.
26546 File: gdb.info, Node: General Query Packets, Next: Architecture-Specific Protocol Details, Prev: Stop Reply Packets, Up: Remote Protocol
26548 D.4 General Query Packets
26549 =========================
26551 Packets starting with `q' are "general query packets"; packets starting
26552 with `Q' are "general set packets". General query and set packets are
26553 a semi-unified form for retrieving and sending information to and from
26556 The initial letter of a query or set packet is followed by a name
26557 indicating what sort of thing the packet applies to. For example, GDB
26558 may use a `qSymbol' packet to exchange symbol definitions with the
26559 stub. These packet names follow some conventions:
26561 * The name must not contain commas, colons or semicolons.
26563 * Most GDB query and set packets have a leading upper case letter.
26565 * The names of custom vendor packets should use a company prefix, in
26566 lower case, followed by a period. For example, packets designed at
26567 the Acme Corporation might begin with `qacme.foo' (for querying
26568 foos) or `Qacme.bar' (for setting bars).
26570 The name of a query or set packet should be separated from any
26571 parameters by a `:'; the parameters themselves should be separated by
26572 `,' or `;'. Stubs must be careful to match the full packet name, and
26573 check for a separator or the end of the packet, in case two packet
26574 names share a common prefix. New packets should not begin with `qC',
26577 Like the descriptions of the other packets, each description here
26578 has a template showing the packet's overall syntax, followed by an
26579 explanation of the packet's meaning. We include spaces in some of the
26580 templates for clarity; these are not part of the packet's syntax. No
26581 GDB packet uses spaces to separate its components.
26583 Here are the currently defined query and set packets:
26586 Return the current thread ID.
26590 Where THREAD-ID is a thread ID as documented in *note
26591 thread-id syntax::.
26594 Any other reply implies the old thread ID.
26597 Compute the CRC checksum of a block of memory using CRC-32 defined
26598 in IEEE 802.3. The CRC is computed byte at a time, taking the most
26599 significant bit of each byte first. The initial pattern code
26600 `0xffffffff' is used to ensure leading zeros affect the CRC.
26602 _Note:_ This is the same CRC used in validating separate debug
26603 files (*note Debugging Information in Separate Files: Separate
26604 Debug Files.). However the algorithm is slightly different. When
26605 validating separate debug files, the CRC is computed taking the
26606 _least_ significant bit of each byte first, and the final result
26607 is inverted to detect trailing zeros.
26611 An error (such as memory fault)
26614 The specified memory region's checksum is CRC32.
26618 Obtain a list of all active thread IDs from the target (OS).
26619 Since there may be too many active threads to fit into one reply
26620 packet, this query works iteratively: it may require more than one
26621 query/reply sequence to obtain the entire list of threads. The
26622 first query of the sequence will be the `qfThreadInfo' query;
26623 subsequent queries in the sequence will be the `qsThreadInfo'
26626 NOTE: This packet replaces the `qL' query (see below).
26632 `m THREAD-ID,THREAD-ID...'
26633 a comma-separated list of thread IDs
26636 (lower case letter `L') denotes end of list.
26638 In response to each query, the target will reply with a list of
26639 one or more thread IDs, separated by commas. GDB will respond to
26640 each reply with a request for more thread ids (using the `qs' form
26641 of the query), until the target responds with `l' (lower-case el,
26642 for "last"). Refer to *note thread-id syntax::, for the format of
26643 the THREAD-ID fields.
26645 `qGetTLSAddr:THREAD-ID,OFFSET,LM'
26646 Fetch the address associated with thread local storage specified
26647 by THREAD-ID, OFFSET, and LM.
26649 THREAD-ID is the thread ID associated with the thread for which to
26650 fetch the TLS address. *Note thread-id syntax::.
26652 OFFSET is the (big endian, hex encoded) offset associated with the
26653 thread local variable. (This offset is obtained from the debug
26654 information associated with the variable.)
26656 LM is the (big endian, hex encoded) OS/ABI-specific encoding of the
26657 the load module associated with the thread local storage. For
26658 example, a GNU/Linux system will pass the link map address of the
26659 shared object associated with the thread local storage under
26660 consideration. Other operating environments may choose to
26661 represent the load module differently, so the precise meaning of
26662 this parameter will vary.
26666 Hex encoded (big endian) bytes representing the address of
26667 the thread local storage requested.
26670 An error occurred. NN are hex digits.
26673 An empty reply indicates that `qGetTLSAddr' is not supported
26676 `qL STARTFLAG THREADCOUNT NEXTTHREAD'
26677 Obtain thread information from RTOS. Where: STARTFLAG (one hex
26678 digit) is one to indicate the first query and zero to indicate a
26679 subsequent query; THREADCOUNT (two hex digits) is the maximum
26680 number of threads the response packet can contain; and NEXTTHREAD
26681 (eight hex digits), for subsequent queries (STARTFLAG is zero), is
26682 returned in the response as ARGTHREAD.
26684 Don't use this packet; use the `qfThreadInfo' query instead (see
26688 `qM COUNT DONE ARGTHREAD THREAD...'
26689 Where: COUNT (two hex digits) is the number of threads being
26690 returned; DONE (one hex digit) is zero to indicate more
26691 threads and one indicates no further threads; ARGTHREADID
26692 (eight hex digits) is NEXTTHREAD from the request packet;
26693 THREAD... is a sequence of thread IDs from the target.
26694 THREADID (eight hex digits). See
26695 `remote.c:parse_threadlist_response()'.
26698 Get section offsets that the target used when relocating the
26702 `Text=XXX;Data=YYY[;Bss=ZZZ]'
26703 Relocate the `Text' section by XXX from its original address.
26704 Relocate the `Data' section by YYY from its original address.
26705 If the object file format provides segment information (e.g.
26706 ELF `PT_LOAD' program headers), GDB will relocate entire
26707 segments by the supplied offsets.
26709 _Note: while a `Bss' offset may be included in the response,
26710 GDB ignores this and instead applies the `Data' offset to the
26713 `TextSeg=XXX[;DataSeg=YYY]'
26714 Relocate the first segment of the object file, which
26715 conventionally contains program code, to a starting address
26716 of XXX. If `DataSeg' is specified, relocate the second
26717 segment, which conventionally contains modifiable data, to a
26718 starting address of YYY. GDB will report an error if the
26719 object file does not contain segment information, or does not
26720 contain at least as many segments as mentioned in the reply.
26721 Extra segments are kept at fixed offsets relative to the last
26724 `qP MODE THREAD-ID'
26725 Returns information on THREAD-ID. Where: MODE is a hex encoded 32
26726 bit mode; THREAD-ID is a thread ID (*note thread-id syntax::).
26728 Don't use this packet; use the `qThreadExtraInfo' query instead
26731 Reply: see `remote.c:remote_unpack_thread_info_response()'.
26736 Enter non-stop (`QNonStop:1') or all-stop (`QNonStop:0') mode.
26737 *Note Remote Non-Stop::, for more information.
26741 The request succeeded.
26744 An error occurred. NN are hex digits.
26747 An empty reply indicates that `QNonStop' is not supported by
26750 This packet is not probed by default; the remote stub must request
26751 it, by supplying an appropriate `qSupported' response (*note
26752 qSupported::). Use of this packet is controlled by the `set
26753 non-stop' command; *note Non-Stop Mode::.
26755 `QPassSignals: SIGNAL [;SIGNAL]...'
26756 Each listed SIGNAL should be passed directly to the inferior
26757 process. Signals are numbered identically to continue packets and
26758 stop replies (*note Stop Reply Packets::). Each SIGNAL list item
26759 should be strictly greater than the previous item. These signals
26760 do not need to stop the inferior, or be reported to GDB. All
26761 other signals should be reported to GDB. Multiple `QPassSignals'
26762 packets do not combine; any earlier `QPassSignals' list is
26763 completely replaced by the new list. This packet improves
26764 performance when using `handle SIGNAL nostop noprint pass'.
26768 The request succeeded.
26771 An error occurred. NN are hex digits.
26774 An empty reply indicates that `QPassSignals' is not supported
26777 Use of this packet is controlled by the `set remote pass-signals'
26778 command (*note set remote pass-signals: Remote Configuration.).
26779 This packet is not probed by default; the remote stub must request
26780 it, by supplying an appropriate `qSupported' response (*note
26784 COMMAND (hex encoded) is passed to the local interpreter for
26785 execution. Invalid commands should be reported using the output
26786 string. Before the final result packet, the target may also
26787 respond with a number of intermediate `OOUTPUT' console output
26788 packets. _Implementors should note that providing access to a
26789 stubs's interpreter may have security implications_.
26793 A command response with no output.
26796 A command response with the hex encoded output string OUTPUT.
26799 Indicate a badly formed request.
26802 An empty reply indicates that `qRcmd' is not recognized.
26804 (Note that the `qRcmd' packet's name is separated from the command
26805 by a `,', not a `:', contrary to the naming conventions above.
26806 Please don't use this packet as a model for new packets.)
26808 `qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN'
26809 Search LENGTH bytes at ADDRESS for SEARCH-PATTERN. ADDRESS and
26810 LENGTH are encoded in hex. SEARCH-PATTERN is a sequence of bytes,
26815 The pattern was not found.
26818 The pattern was found at ADDRESS.
26821 A badly formed request or an error was encountered while
26825 An empty reply indicates that `qSearch:memory' is not
26829 Request that the remote stub disable the normal `+'/`-' protocol
26830 acknowledgments (*note Packet Acknowledgment::).
26834 The stub has switched to no-acknowledgment mode. GDB
26835 acknowledges this reponse, but neither the stub nor GDB shall
26836 send or expect further `+'/`-' acknowledgments in the current
26840 An empty reply indicates that the stub does not support
26841 no-acknowledgment mode.
26843 `qSupported [:GDBFEATURE [;GDBFEATURE]... ]'
26844 Tell the remote stub about features supported by GDB, and query
26845 the stub for features it supports. This packet allows GDB and the
26846 remote stub to take advantage of each others' features.
26847 `qSupported' also consolidates multiple feature probes at startup,
26848 to improve GDB performance--a single larger packet performs better
26849 than multiple smaller probe packets on high-latency links. Some
26850 features may enable behavior which must not be on by default, e.g.
26851 because it would confuse older clients or stubs. Other features
26852 may describe packets which could be automatically probed for, but
26853 are not. These features must be reported before GDB will use
26854 them. This "default unsupported" behavior is not appropriate for
26855 all packets, but it helps to keep the initial connection time
26856 under control with new versions of GDB which support increasing
26857 numbers of packets.
26860 `STUBFEATURE [;STUBFEATURE]...'
26861 The stub supports or does not support each returned
26862 STUBFEATURE, depending on the form of each STUBFEATURE (see
26863 below for the possible forms).
26866 An empty reply indicates that `qSupported' is not recognized,
26867 or that no features needed to be reported to GDB.
26869 The allowed forms for each feature (either a GDBFEATURE in the
26870 `qSupported' packet, or a STUBFEATURE in the response) are:
26873 The remote protocol feature NAME is supported, and associated
26874 with the specified VALUE. The format of VALUE depends on the
26875 feature, but it must not include a semicolon.
26878 The remote protocol feature NAME is supported, and does not
26879 need an associated value.
26882 The remote protocol feature NAME is not supported.
26885 The remote protocol feature NAME may be supported, and GDB
26886 should auto-detect support in some other way when it is
26887 needed. This form will not be used for GDBFEATURE
26888 notifications, but may be used for STUBFEATURE responses.
26890 Whenever the stub receives a `qSupported' request, the supplied
26891 set of GDB features should override any previous request. This
26892 allows GDB to put the stub in a known state, even if the stub had
26893 previously been communicating with a different version of GDB.
26895 The following values of GDBFEATURE (for the packet sent by GDB)
26899 This feature indicates whether GDB supports multiprocess
26900 extensions to the remote protocol. GDB does not use such
26901 extensions unless the stub also reports that it supports them
26902 by including `multiprocess+' in its `qSupported' reply.
26903 *Note multiprocess extensions::, for details.
26905 Stubs should ignore any unknown values for GDBFEATURE. Any GDB
26906 which sends a `qSupported' packet supports receiving packets of
26907 unlimited length (earlier versions of GDB may reject overly long
26908 responses). Additional values for GDBFEATURE may be defined in
26909 the future to let the stub take advantage of new features in GDB,
26910 e.g. incompatible improvements in the remote protocol--the
26911 `multiprocess' feature is an example of such a feature. The
26912 stub's reply should be independent of the GDBFEATURE entries sent
26913 by GDB; first GDB describes all the features it supports, and then
26914 the stub replies with all the features it supports.
26916 Similarly, GDB will silently ignore unrecognized stub feature
26917 responses, as long as each response uses one of the standard forms.
26919 Some features are flags. A stub which supports a flag feature
26920 should respond with a `+' form response. Other features require
26921 values, and the stub should respond with an `=' form response.
26923 Each feature has a default value, which GDB will use if
26924 `qSupported' is not available or if the feature is not mentioned
26925 in the `qSupported' response. The default values are fixed; a
26926 stub is free to omit any feature responses that match the defaults.
26928 Not all features can be probed, but for those which can, the
26929 probing mechanism is useful: in some cases, a stub's internal
26930 architecture may not allow the protocol layer to know some
26931 information about the underlying target in advance. This is
26932 especially common in stubs which may be configured for multiple
26935 These are the currently defined stub features and their properties:
26937 Feature Name Value Default Probe Allowed
26939 `PacketSize' Yes `-' No
26940 `qXfer:auxv:read' No `-' Yes
26941 `qXfer:features:read' No `-' Yes
26942 `qXfer:libraries:read' No `-' Yes
26943 `qXfer:memory-map:read' No `-' Yes
26944 `qXfer:spu:read' No `-' Yes
26945 `qXfer:spu:write' No `-' Yes
26946 `qXfer:siginfo:read' No `-' Yes
26947 `qXfer:siginfo:write' No `-' Yes
26948 `qXfer:threads:read' No `-' Yes
26949 `QNonStop' No `-' Yes
26950 `QPassSignals' No `-' Yes
26951 `QStartNoAckMode' No `-' Yes
26952 `multiprocess' No `-' No
26953 `ConditionalTracepoints'No `-' No
26954 `ReverseContinue' No `-' No
26955 `ReverseStep' No `-' No
26957 These are the currently defined stub features, in more detail:
26960 The remote stub can accept packets up to at least BYTES in
26961 length. GDB will send packets up to this size for bulk
26962 transfers, and will never send larger packets. This is a
26963 limit on the data characters in the packet, including the
26964 frame and checksum. There is no trailing NUL byte in a
26965 remote protocol packet; if the stub stores packets in a
26966 NUL-terminated format, it should allow an extra byte in its
26967 buffer for the NUL. If this stub feature is not supported,
26968 GDB guesses based on the size of the `g' packet response.
26971 The remote stub understands the `qXfer:auxv:read' packet
26972 (*note qXfer auxiliary vector read::).
26974 `qXfer:features:read'
26975 The remote stub understands the `qXfer:features:read' packet
26976 (*note qXfer target description read::).
26978 `qXfer:libraries:read'
26979 The remote stub understands the `qXfer:libraries:read' packet
26980 (*note qXfer library list read::).
26982 `qXfer:memory-map:read'
26983 The remote stub understands the `qXfer:memory-map:read' packet
26984 (*note qXfer memory map read::).
26987 The remote stub understands the `qXfer:spu:read' packet
26988 (*note qXfer spu read::).
26991 The remote stub understands the `qXfer:spu:write' packet
26992 (*note qXfer spu write::).
26994 `qXfer:siginfo:read'
26995 The remote stub understands the `qXfer:siginfo:read' packet
26996 (*note qXfer siginfo read::).
26998 `qXfer:siginfo:write'
26999 The remote stub understands the `qXfer:siginfo:write' packet
27000 (*note qXfer siginfo write::).
27002 `qXfer:threads:read'
27003 The remote stub understands the `qXfer:threads:read' packet
27004 (*note qXfer threads read::).
27007 The remote stub understands the `QNonStop' packet (*note
27011 The remote stub understands the `QPassSignals' packet (*note
27015 The remote stub understands the `QStartNoAckMode' packet and
27016 prefers to operate in no-acknowledgment mode. *Note Packet
27020 The remote stub understands the multiprocess extensions to
27021 the remote protocol syntax. The multiprocess extensions
27022 affect the syntax of thread IDs in both packets and replies
27023 (*note thread-id syntax::), and add process IDs to the `D'
27024 packet and `W' and `X' replies. Note that reporting this
27025 feature indicates support for the syntactic extensions only,
27026 not that the stub necessarily supports debugging of more than
27027 one process at a time. The stub must not use multiprocess
27028 extensions in packet replies unless GDB has also indicated it
27029 supports them in its `qSupported' request.
27031 `qXfer:osdata:read'
27032 The remote stub understands the `qXfer:osdata:read' packet
27033 ((*note qXfer osdata read::).
27035 `ConditionalTracepoints'
27036 The remote stub accepts and implements conditional
27037 expressions defined for tracepoints (*note Tracepoint
27041 The remote stub accepts and implements the reverse continue
27042 packet (*note bc::).
27045 The remote stub accepts and implements the reverse step packet
27050 Notify the target that GDB is prepared to serve symbol lookup
27051 requests. Accept requests from the target for the values of
27056 The target does not need to look up any (more) symbols.
27059 The target requests the value of symbol SYM_NAME (hex
27060 encoded). GDB may provide the value by using the
27061 `qSymbol:SYM_VALUE:SYM_NAME' message, described below.
27063 `qSymbol:SYM_VALUE:SYM_NAME'
27064 Set the value of SYM_NAME to SYM_VALUE.
27066 SYM_NAME (hex encoded) is the name of a symbol whose value the
27067 target has previously requested.
27069 SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot
27070 supply a value for SYM_NAME, then this field will be empty.
27074 The target does not need to look up any (more) symbols.
27077 The target requests the value of a new symbol SYM_NAME (hex
27078 encoded). GDB will continue to supply the values of symbols
27079 (if available), until the target ceases to request them.
27089 *Note Tracepoint Packets::.
27091 `qThreadExtraInfo,THREAD-ID'
27092 Obtain a printable string description of a thread's attributes from
27093 the target OS. THREAD-ID is a thread ID; see *note thread-id
27094 syntax::. This string may contain anything that the target OS
27095 thinks is interesting for GDB to tell the user about the thread.
27096 The string is displayed in GDB's `info threads' display. Some
27097 examples of possible thread extra info strings are `Runnable', or
27098 `Blocked on Mutex'.
27102 Where `XX...' is a hex encoding of ASCII data, comprising the
27103 printable string containing the extra information about the
27104 thread's attributes.
27106 (Note that the `qThreadExtraInfo' packet's name is separated from
27107 the command by a `,', not a `:', contrary to the naming
27108 conventions above. Please don't use this packet as a model for new
27122 *Note Tracepoint Packets::.
27124 `qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH'
27125 Read uninterpreted bytes from the target's special data area
27126 identified by the keyword OBJECT. Request LENGTH bytes starting
27127 at OFFSET bytes into the data. The content and encoding of ANNEX
27128 is specific to OBJECT; it can supply additional details about what
27131 Here are the specific requests of this form defined so far. All
27132 `qXfer:OBJECT:read:...' requests use the same reply formats,
27135 `qXfer:auxv:read::OFFSET,LENGTH'
27136 Access the target's "auxiliary vector". *Note auxiliary
27137 vector: OS Information. Note ANNEX must be empty.
27139 This packet is not probed by default; the remote stub must
27140 request it, by supplying an appropriate `qSupported' response
27141 (*note qSupported::).
27143 `qXfer:features:read:ANNEX:OFFSET,LENGTH'
27144 Access the "target description". *Note Target
27145 Descriptions::. The annex specifies which XML document to
27146 access. The main description is always loaded from the
27147 `target.xml' annex.
27149 This packet is not probed by default; the remote stub must
27150 request it, by supplying an appropriate `qSupported' response
27151 (*note qSupported::).
27153 `qXfer:libraries:read:ANNEX:OFFSET,LENGTH'
27154 Access the target's list of loaded libraries. *Note Library
27155 List Format::. The annex part of the generic `qXfer' packet
27156 must be empty (*note qXfer read::).
27158 Targets which maintain a list of libraries in the program's
27159 memory do not need to implement this packet; it is designed
27160 for platforms where the operating system manages the list of
27163 This packet is not probed by default; the remote stub must
27164 request it, by supplying an appropriate `qSupported' response
27165 (*note qSupported::).
27167 `qXfer:memory-map:read::OFFSET,LENGTH'
27168 Access the target's "memory-map". *Note Memory Map Format::.
27169 The annex part of the generic `qXfer' packet must be empty
27170 (*note qXfer read::).
27172 This packet is not probed by default; the remote stub must
27173 request it, by supplying an appropriate `qSupported' response
27174 (*note qSupported::).
27176 `qXfer:siginfo:read::OFFSET,LENGTH'
27177 Read contents of the extra signal information on the target
27178 system. The annex part of the generic `qXfer' packet must be
27179 empty (*note qXfer read::).
27181 This packet is not probed by default; the remote stub must
27182 request it, by supplying an appropriate `qSupported' response
27183 (*note qSupported::).
27185 `qXfer:spu:read:ANNEX:OFFSET,LENGTH'
27186 Read contents of an `spufs' file on the target system. The
27187 annex specifies which file to read; it must be of the form
27188 `ID/NAME', where ID specifies an SPU context ID in the target
27189 process, and NAME identifes the `spufs' file in that context
27192 This packet is not probed by default; the remote stub must
27193 request it, by supplying an appropriate `qSupported' response
27194 (*note qSupported::).
27196 `qXfer:threads:read::OFFSET,LENGTH'
27197 Access the list of threads on target. *Note Thread List
27198 Format::. The annex part of the generic `qXfer' packet must
27199 be empty (*note qXfer read::).
27201 This packet is not probed by default; the remote stub must
27202 request it, by supplying an appropriate `qSupported' response
27203 (*note qSupported::).
27205 `qXfer:osdata:read::OFFSET,LENGTH'
27206 Access the target's "operating system information". *Note
27207 Operating System Information::.
27212 Data DATA (*note Binary Data::) has been read from the
27213 target. There may be more data at a higher address (although
27214 it is permitted to return `m' even for the last valid block
27215 of data, as long as at least one byte of data was read).
27216 DATA may have fewer bytes than the LENGTH in the request.
27219 Data DATA (*note Binary Data::) has been read from the target.
27220 There is no more data to be read. DATA may have fewer bytes
27221 than the LENGTH in the request.
27224 The OFFSET in the request is at the end of the data. There
27225 is no more data to be read.
27228 The request was malformed, or ANNEX was invalid.
27231 The offset was invalid, or there was an error encountered
27232 reading the data. NN is a hex-encoded `errno' value.
27235 An empty reply indicates the OBJECT string was not recognized
27236 by the stub, or that the object does not support reading.
27238 `qXfer:OBJECT:write:ANNEX:OFFSET:DATA...'
27239 Write uninterpreted bytes into the target's special data area
27240 identified by the keyword OBJECT, starting at OFFSET bytes into
27241 the data. DATA... is the binary-encoded data (*note Binary
27242 Data::) to be written. The content and encoding of ANNEX is
27243 specific to OBJECT; it can supply additional details about what
27246 Here are the specific requests of this form defined so far. All
27247 `qXfer:OBJECT:write:...' requests use the same reply formats,
27250 `qXfer:siginfo:write::OFFSET:DATA...'
27251 Write DATA to the extra signal information on the target
27252 system. The annex part of the generic `qXfer' packet must be
27253 empty (*note qXfer write::).
27255 This packet is not probed by default; the remote stub must
27256 request it, by supplying an appropriate `qSupported' response
27257 (*note qSupported::).
27259 `qXfer:spu:write:ANNEX:OFFSET:DATA...'
27260 Write DATA to an `spufs' file on the target system. The
27261 annex specifies which file to write; it must be of the form
27262 `ID/NAME', where ID specifies an SPU context ID in the target
27263 process, and NAME identifes the `spufs' file in that context
27266 This packet is not probed by default; the remote stub must
27267 request it, by supplying an appropriate `qSupported' response
27268 (*note qSupported::).
27272 NN (hex encoded) is the number of bytes written. This may be
27273 fewer bytes than supplied in the request.
27276 The request was malformed, or ANNEX was invalid.
27279 The offset was invalid, or there was an error encountered
27280 writing the data. NN is a hex-encoded `errno' value.
27283 An empty reply indicates the OBJECT string was not recognized
27284 by the stub, or that the object does not support writing.
27286 `qXfer:OBJECT:OPERATION:...'
27287 Requests of this form may be added in the future. When a stub does
27288 not recognize the OBJECT keyword, or its support for OBJECT does
27289 not recognize the OPERATION keyword, the stub must respond with an
27293 Return an indication of whether the remote server attached to an
27294 existing process or created a new process. When the multiprocess
27295 protocol extensions are supported (*note multiprocess
27296 extensions::), PID is an integer in hexadecimal format identifying
27297 the target process. Otherwise, GDB will omit the PID field and
27298 the query packet will be simplified as `qAttached'.
27300 This query is used, for example, to know whether the remote process
27301 should be detached or killed when a GDB session is ended with the
27306 The remote server attached to an existing process.
27309 The remote server created a new process.
27312 A badly formed request or an error was encountered.
27315 ---------- Footnotes ----------
27317 (1) The `qP' and `qL' packets predate these conventions, and have
27318 arguments without any terminator for the packet name; we suspect they
27319 are in widespread use in places that are difficult to upgrade. The
27320 `qC' packet has no arguments, but some existing stubs (e.g. RedBoot)
27321 are known to not check for the end of the packet.
27324 File: gdb.info, Node: Architecture-Specific Protocol Details, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol
27326 D.5 Architecture-Specific Protocol Details
27327 ==========================================
27329 This section describes how the remote protocol is applied to specific
27330 target architectures. Also see *note Standard Target Features::, for
27331 details of XML target descriptions for each architecture.
27336 D.5.1.1 Breakpoint Kinds
27337 ........................
27339 These breakpoint kinds are defined for the `Z0' and `Z1' packets.
27342 16-bit Thumb mode breakpoint.
27345 32-bit Thumb mode (Thumb-2) breakpoint.
27348 32-bit ARM mode breakpoint.
27354 D.5.2.1 Register Packet Format
27355 ..............................
27357 The following `g'/`G' packets have previously been defined. In the
27358 below, some thirty-two bit registers are transferred as sixty-four
27359 bits. Those registers should be zero/sign extended (which?) to fill
27360 the space allocated. Register bytes are transferred in target byte
27361 order. The two nibbles within a register byte are transferred
27362 most-significant - least-significant.
27365 All registers are transferred as thirty-two bit quantities in the
27366 order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32
27367 floating-point registers; fsr; fir; fp.
27370 All registers are transferred as sixty-four bit quantities
27371 (including thirty-two bit registers such as `sr'). The ordering
27372 is the same as `MIPS32'.
27376 File: gdb.info, Node: Tracepoint Packets, Next: Host I/O Packets, Prev: Architecture-Specific Protocol Details, Up: Remote Protocol
27378 D.6 Tracepoint Packets
27379 ======================
27381 Here we describe the packets GDB uses to implement tracepoints (*note
27384 `QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]'
27385 Create a new tracepoint, number N, at ADDR. If ENA is `E', then
27386 the tracepoint is enabled; if it is `D', then the tracepoint is
27387 disabled. STEP is the tracepoint's step count, and PASS is its
27388 pass count. If an `F' is present, then the tracepoint is to be a
27389 fast tracepoint, and the FLEN is the number of bytes that the
27390 target should copy elsewhere to make room for the tracepoint. If
27391 an `X' is present, it introduces a tracepoint condition, which
27392 consists of a hexadecimal length, followed by a comma and
27393 hex-encoded bytes, in a manner similar to action encodings as
27394 described below. If the trailing `-' is present, further `QTDP'
27395 packets will follow to specify this tracepoint's actions.
27399 The packet was understood and carried out.
27402 The packet was not recognized.
27404 `QTDP:-N:ADDR:[S]ACTION...[-]'
27405 Define actions to be taken when a tracepoint is hit. N and ADDR
27406 must be the same as in the initial `QTDP' packet for this
27407 tracepoint. This packet may only be sent immediately after
27408 another `QTDP' packet that ended with a `-'. If the trailing `-'
27409 is present, further `QTDP' packets will follow, specifying more
27410 actions for this tracepoint.
27412 In the series of action packets for a given tracepoint, at most one
27413 can have an `S' before its first ACTION. If such a packet is
27414 sent, it and the following packets define "while-stepping"
27415 actions. Any prior packets define ordinary actions -- that is,
27416 those taken when the tracepoint is first hit. If no action packet
27417 has an `S', then all the packets in the series specify ordinary
27418 tracepoint actions.
27420 The `ACTION...' portion of the packet is a series of actions,
27421 concatenated without separators. Each action has one of the
27425 Collect the registers whose bits are set in MASK. MASK is a
27426 hexadecimal number whose I'th bit is set if register number I
27427 should be collected. (The least significant bit is numbered
27428 zero.) Note that MASK may be any number of digits long; it
27429 may not fit in a 32-bit word.
27431 `M BASEREG,OFFSET,LEN'
27432 Collect LEN bytes of memory starting at the address in
27433 register number BASEREG, plus OFFSET. If BASEREG is `-1',
27434 then the range has a fixed address: OFFSET is the address of
27435 the lowest byte to collect. The BASEREG, OFFSET, and LEN
27436 parameters are all unsigned hexadecimal values (the `-1'
27437 value for BASEREG is a special case).
27440 Evaluate EXPR, whose length is LEN, and collect memory as it
27441 directs. EXPR is an agent expression, as described in *note
27442 Agent Expressions::. Each byte of the expression is encoded
27443 as a two-digit hex number in the packet; LEN is the number of
27444 bytes in the expression (and thus one-half the number of hex
27445 digits in the packet).
27448 Any number of actions may be packed together in a single `QTDP'
27449 packet, as long as the packet does not exceed the maximum packet
27450 length (400 bytes, for many stubs). There may be only one `R'
27451 action per tracepoint, and it must precede any `M' or `X' actions.
27452 Any registers referred to by `M' and `X' actions must be collected
27453 by a preceding `R' action. (The "while-stepping" actions are
27454 treated as if they were attached to a separate tracepoint, as far
27455 as these restrictions are concerned.)
27459 The packet was understood and carried out.
27462 The packet was not recognized.
27465 Create a new trace state variable, number N, with an initial value
27466 of VALUE, which is a 64-bit signed integer. Both N and VALUE are
27467 encoded as hexadecimal values. GDB has the option of not using
27468 this packet for initial values of zero; the target should simply
27469 create the trace state variables as they are mentioned in
27473 Select the N'th tracepoint frame from the buffer, and use the
27474 register and memory contents recorded there to answer subsequent
27475 request packets from GDB.
27477 A successful reply from the stub indicates that the stub has found
27478 the requested frame. The response is a series of parts,
27479 concatenated without separators, describing the frame we selected.
27480 Each part has one of the following forms:
27483 The selected frame is number N in the trace frame buffer; F
27484 is a hexadecimal number. If F is `-1', then there was no
27485 frame matching the criteria in the request packet.
27488 The selected trace frame records a hit of tracepoint number T;
27489 T is a hexadecimal number.
27493 Like `QTFrame:N', but select the first tracepoint frame after the
27494 currently selected frame whose PC is ADDR; ADDR is a hexadecimal
27498 Like `QTFrame:N', but select the first tracepoint frame after the
27499 currently selected frame that is a hit of tracepoint T; T is a
27500 hexadecimal number.
27502 `QTFrame:range:START:END'
27503 Like `QTFrame:N', but select the first tracepoint frame after the
27504 currently selected frame whose PC is between START (inclusive) and
27505 END (inclusive); START and END are hexadecimal numbers.
27507 `QTFrame:outside:START:END'
27508 Like `QTFrame:range:START:END', but select the first frame
27509 _outside_ the given range of addresses (exclusive).
27512 Begin the tracepoint experiment. Begin collecting data from
27513 tracepoint hits in the trace frame buffer.
27516 End the tracepoint experiment. Stop collecting trace frames.
27519 Clear the table of tracepoints, and empty the trace frame buffer.
27521 `QTro:START1,END1:START2,END2:...'
27522 Establish the given ranges of memory as "transparent". The stub
27523 will answer requests for these ranges from memory's current
27524 contents, if they were not collected as part of the tracepoint hit.
27526 GDB uses this to mark read-only regions of memory, like those
27527 containing program code. Since these areas never change, they
27528 should still have the same contents they did when the tracepoint
27529 was hit, so there's no reason for the stub to refuse to provide
27532 `QTDisconnected:VALUE'
27533 Set the choice to what to do with the tracing run when GDB
27534 disconnects from the target. A VALUE of 1 directs the target to
27535 continue the tracing run, while 0 tells the target to stop tracing
27536 if GDB is no longer in the picture.
27539 Ask the stub if there is a trace experiment running right now.
27543 There is no trace experiment running.
27546 There is a trace experiment running.
27549 Ask the stub for the value of the trace state variable number VAR.
27553 The value of the variable is VALUE. This will be the current
27554 value of the variable if the user is examining a running
27555 target, or a saved value if the variable was collected in the
27556 trace frame that the user is looking at. Note that multiple
27557 requests may result in different reply values, such as when
27558 requesting values while the program is running.
27561 The value of the variable is unknown. This would occur, for
27562 example, if the user is examining a trace frame in which the
27563 requested variable was not collected.
27567 These packets request data about tracepoints that are being used by
27568 the target. GDB sends `qTfP' to get the first piece of data, and
27569 multiple `qTsP' to get additional pieces. Replies to these
27570 packets generally take the form of the `QTDP' packets that define
27571 tracepoints. (FIXME add detailed syntax)
27575 These packets request data about trace state variables that are on
27576 the target. GDB sends `qTfV' to get the first vari of data, and
27577 multiple `qTsV' to get additional variables. Replies to these
27578 packets follow the syntax of the `QTDV' packets that define trace
27582 This packet directs the target to save trace data to the file name
27583 FILENAME in the target's filesystem. FILENAME is encoded as a hex
27584 string; the interpretation of the file name (relative vs absolute,
27585 wild cards, etc) is up to the target.
27587 `qTBuffer:OFFSET,LEN'
27588 Return up to LEN bytes of the current contents of trace buffer,
27589 starting at OFFSET. The trace buffer is treated as if it were a
27590 contiguous collection of traceframes, as per the trace file format.
27591 The reply consists as many hex-encoded bytes as the target can
27592 deliver in a packet; it is not an error to return fewer than were
27593 asked for. A reply consisting of just `l' indicates that no bytes
27598 File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol
27600 D.7 Host I/O Packets
27601 ====================
27603 The "Host I/O" packets allow GDB to perform I/O operations on the far
27604 side of a remote link. For example, Host I/O is used to upload and
27605 download files to a remote target with its own filesystem. Host I/O
27606 uses the same constant values and data structure layout as the
27607 target-initiated File-I/O protocol. However, the Host I/O packets are
27608 structured differently. The target-initiated protocol relies on target
27609 memory to store parameters and buffers. Host I/O requests are
27610 initiated by GDB, and the target's memory is not involved. *Note
27611 File-I/O Remote Protocol Extension::, for more details on the
27612 target-initiated protocol.
27614 The Host I/O request packets all encode a single operation along with
27615 its arguments. They have this format:
27617 `vFile:OPERATION: PARAMETER...'
27618 OPERATION is the name of the particular request; the target should
27619 compare the entire packet name up to the second colon when checking
27620 for a supported operation. The format of PARAMETER depends on the
27621 operation. Numbers are always passed in hexadecimal. Negative
27622 numbers have an explicit minus sign (i.e. two's complement is not
27623 used). Strings (e.g. filenames) are encoded as a series of
27624 hexadecimal bytes. The last argument to a system call may be a
27625 buffer of escaped binary data (*note Binary Data::).
27628 The valid responses to Host I/O packets are:
27630 `F RESULT [, ERRNO] [; ATTACHMENT]'
27631 RESULT is the integer value returned by this operation, usually
27632 non-negative for success and -1 for errors. If an error has
27633 occured, ERRNO will be included in the result. ERRNO will have a
27634 value defined by the File-I/O protocol (*note Errno Values::). For
27635 operations which return data, ATTACHMENT supplies the data as a
27636 binary buffer. Binary buffers in response packets are escaped in
27637 the normal way (*note Binary Data::). See the individual packet
27638 documentation for the interpretation of RESULT and ATTACHMENT.
27641 An empty response indicates that this operation is not recognized.
27644 These are the supported Host I/O operations:
27646 `vFile:open: PATHNAME, FLAGS, MODE'
27647 Open a file at PATHNAME and return a file descriptor for it, or
27648 return -1 if an error occurs. PATHNAME is a string, FLAGS is an
27649 integer indicating a mask of open flags (*note Open Flags::), and
27650 MODE is an integer indicating a mask of mode bits to use if the
27651 file is created (*note mode_t Values::). *Note open::, for
27652 details of the open flags and mode values.
27655 Close the open file corresponding to FD and return 0, or -1 if an
27658 `vFile:pread: FD, COUNT, OFFSET'
27659 Read data from the open file corresponding to FD. Up to COUNT
27660 bytes will be read from the file, starting at OFFSET relative to
27661 the start of the file. The target may read fewer bytes; common
27662 reasons include packet size limits and an end-of-file condition.
27663 The number of bytes read is returned. Zero should only be
27664 returned for a successful read at the end of the file, or if COUNT
27667 The data read should be returned as a binary attachment on success.
27668 If zero bytes were read, the response should include an empty
27669 binary attachment (i.e. a trailing semicolon). The return value
27670 is the number of target bytes read; the binary attachment may be
27671 longer if some characters were escaped.
27673 `vFile:pwrite: FD, OFFSET, DATA'
27674 Write DATA (a binary buffer) to the open file corresponding to FD.
27675 Start the write at OFFSET from the start of the file. Unlike many
27676 `write' system calls, there is no separate COUNT argument; the
27677 length of DATA in the packet is used. `vFile:write' returns the
27678 number of bytes written, which may be shorter than the length of
27679 DATA, or -1 if an error occurred.
27681 `vFile:unlink: PATHNAME'
27682 Delete the file at PATHNAME on the target. Return 0, or -1 if an
27683 error occurs. PATHNAME is a string.
27687 File: gdb.info, Node: Interrupts, Next: Notification Packets, Prev: Host I/O Packets, Up: Remote Protocol
27692 When a program on the remote target is running, GDB may attempt to
27693 interrupt it by sending a `Ctrl-C', `BREAK' or a `BREAK' followed by
27694 `g', control of which is specified via GDB's `interrupt-sequence'.
27696 The precise meaning of `BREAK' is defined by the transport mechanism
27697 and may, in fact, be undefined. GDB does not currently define a
27698 `BREAK' mechanism for any of the network interfaces except for TCP, in
27699 which case GDB sends the `telnet' BREAK sequence.
27701 `Ctrl-C', on the other hand, is defined and implemented for all
27702 transport mechanisms. It is represented by sending the single byte
27703 `0x03' without any of the usual packet overhead described in the
27704 Overview section (*note Overview::). When a `0x03' byte is transmitted
27705 as part of a packet, it is considered to be packet data and does _not_
27706 represent an interrupt. E.g., an `X' packet (*note X packet::), used
27707 for binary downloads, may include an unescaped `0x03' as part of its
27710 `BREAK' followed by `g' is also known as Magic SysRq g. When Linux
27711 kernel receives this sequence from serial port, it stops execution and
27714 Stubs are not required to recognize these interrupt mechanisms and
27715 the precise meaning associated with receipt of the interrupt is
27716 implementation defined. If the target supports debugging of multiple
27717 threads and/or processes, it should attempt to interrupt all
27718 currently-executing threads and processes. If the stub is successful
27719 at interrupting the running program, it should send one of the stop
27720 reply packets (*note Stop Reply Packets::) to GDB as a result of
27721 successfully stopping the program in all-stop mode, and a stop reply
27722 for each stopped thread in non-stop mode. Interrupts received while the
27723 program is stopped are discarded.
27726 File: gdb.info, Node: Notification Packets, Next: Remote Non-Stop, Prev: Interrupts, Up: Remote Protocol
27728 D.9 Notification Packets
27729 ========================
27731 The GDB remote serial protocol includes "notifications", packets that
27732 require no acknowledgment. Both the GDB and the stub may send
27733 notifications (although the only notifications defined at present are
27734 sent by the stub). Notifications carry information without incurring
27735 the round-trip latency of an acknowledgment, and so are useful for
27736 low-impact communications where occasional packet loss is not a problem.
27738 A notification packet has the form `% DATA # CHECKSUM', where DATA
27739 is the content of the notification, and CHECKSUM is a checksum of DATA,
27740 computed and formatted as for ordinary GDB packets. A notification's
27741 DATA never contains `$', `%' or `#' characters. Upon receiving a
27742 notification, the recipient sends no `+' or `-' to acknowledge the
27743 notification's receipt or to report its corruption.
27745 Every notification's DATA begins with a name, which contains no
27746 colon characters, followed by a colon character.
27748 Recipients should silently ignore corrupted notifications and
27749 notifications they do not understand. Recipients should restart
27750 timeout periods on receipt of a well-formed notification, whether or
27751 not they understand it.
27753 Senders should only send the notifications described here when this
27754 protocol description specifies that they are permitted. In the future,
27755 we may extend the protocol to permit existing notifications in new
27756 contexts; this rule helps older senders avoid confusing newer
27759 (Older versions of GDB ignore bytes received until they see the `$'
27760 byte that begins an ordinary packet, so new stubs may transmit
27761 notifications without fear of confusing older clients. There are no
27762 notifications defined for GDB to send at the moment, but we assume that
27763 most older stubs would ignore them, as well.)
27765 The following notification packets from the stub to GDB are defined:
27768 Report an asynchronous stop event in non-stop mode. The REPLY has
27769 the form of a stop reply, as described in *note Stop Reply
27770 Packets::. Refer to *note Remote Non-Stop::, for information on
27771 how these notifications are acknowledged by GDB.
27774 File: gdb.info, Node: Remote Non-Stop, Next: Packet Acknowledgment, Prev: Notification Packets, Up: Remote Protocol
27776 D.10 Remote Protocol Support for Non-Stop Mode
27777 ==============================================
27779 GDB's remote protocol supports non-stop debugging of multi-threaded
27780 programs, as described in *note Non-Stop Mode::. If the stub supports
27781 non-stop mode, it should report that to GDB by including `QNonStop+' in
27782 its `qSupported' response (*note qSupported::).
27784 GDB typically sends a `QNonStop' packet only when establishing a new
27785 connection with the stub. Entering non-stop mode does not alter the
27786 state of any currently-running threads, but targets must stop all
27787 threads in any already-attached processes when entering all-stop mode.
27788 GDB uses the `?' packet as necessary to probe the target state after a
27791 In non-stop mode, when an attached process encounters an event that
27792 would otherwise be reported with a stop reply, it uses the asynchronous
27793 notification mechanism (*note Notification Packets::) to inform GDB.
27794 In contrast to all-stop mode, where all threads in all processes are
27795 stopped when a stop reply is sent, in non-stop mode only the thread
27796 reporting the stop event is stopped. That is, when reporting a `S' or
27797 `T' response to indicate completion of a step operation, hitting a
27798 breakpoint, or a fault, only the affected thread is stopped; any other
27799 still-running threads continue to run. When reporting a `W' or `X'
27800 response, all running threads belonging to other attached processes
27803 Only one stop reply notification at a time may be pending; if
27804 additional stop events occur before GDB has acknowledged the previous
27805 notification, they must be queued by the stub for later synchronous
27806 transmission in response to `vStopped' packets from GDB. Because the
27807 notification mechanism is unreliable, the stub is permitted to resend a
27808 stop reply notification if it believes GDB may not have received it.
27809 GDB ignores additional stop reply notifications received before it has
27810 finished processing a previous notification and the stub has completed
27811 sending any queued stop events.
27813 Otherwise, GDB must be prepared to receive a stop reply notification
27814 at any time. Specifically, they may appear when GDB is not otherwise
27815 reading input from the stub, or when GDB is expecting to read a normal
27816 synchronous response or a `+'/`-' acknowledgment to a packet it has
27817 sent. Notification packets are distinct from any other communication
27818 from the stub so there is no ambiguity.
27820 After receiving a stop reply notification, GDB shall acknowledge it
27821 by sending a `vStopped' packet (*note vStopped packet::) as a regular,
27822 synchronous request to the stub. Such acknowledgment is not required
27823 to happen immediately, as GDB is permitted to send other, unrelated
27824 packets to the stub first, which the stub should process normally.
27826 Upon receiving a `vStopped' packet, if the stub has other queued
27827 stop events to report to GDB, it shall respond by sending a normal stop
27828 reply response. GDB shall then send another `vStopped' packet to
27829 solicit further responses; again, it is permitted to send other,
27830 unrelated packets as well which the stub should process normally.
27832 If the stub receives a `vStopped' packet and there are no additional
27833 stop events to report, the stub shall return an `OK' response. At this
27834 point, if further stop events occur, the stub shall send a new stop
27835 reply notification, GDB shall accept the notification, and the process
27838 In non-stop mode, the target shall respond to the `?' packet as
27839 follows. First, any incomplete stop reply notification/`vStopped'
27840 sequence in progress is abandoned. The target must begin a new
27841 sequence reporting stop events for all stopped threads, whether or not
27842 it has previously reported those events to GDB. The first stop reply
27843 is sent as a synchronous reply to the `?' packet, and subsequent stop
27844 replies are sent as responses to `vStopped' packets using the mechanism
27845 described above. The target must not send asynchronous stop reply
27846 notifications until the sequence is complete. If all threads are
27847 running when the target receives the `?' packet, or if the target is
27848 not attached to any process, it shall respond `OK'.
27851 File: gdb.info, Node: Packet Acknowledgment, Next: Examples, Prev: Remote Non-Stop, Up: Remote Protocol
27853 D.11 Packet Acknowledgment
27854 ==========================
27856 By default, when either the host or the target machine receives a
27857 packet, the first response expected is an acknowledgment: either `+'
27858 (to indicate the package was received correctly) or `-' (to request
27859 retransmission). This mechanism allows the GDB remote protocol to
27860 operate over unreliable transport mechanisms, such as a serial line.
27862 In cases where the transport mechanism is itself reliable (such as a
27863 pipe or TCP connection), the `+'/`-' acknowledgments are redundant. It
27864 may be desirable to disable them in that case to reduce communication
27865 overhead, or for other reasons. This can be accomplished by means of
27866 the `QStartNoAckMode' packet; *note QStartNoAckMode::.
27868 When in no-acknowledgment mode, neither the stub nor GDB shall send
27869 or expect `+'/`-' protocol acknowledgments. The packet and response
27870 format still includes the normal checksum, as described in *note
27871 Overview::, but the checksum may be ignored by the receiver.
27873 If the stub supports `QStartNoAckMode' and prefers to operate in
27874 no-acknowledgment mode, it should report that to GDB by including
27875 `QStartNoAckMode+' in its response to `qSupported'; *note qSupported::.
27876 If GDB also supports `QStartNoAckMode' and it has not been disabled via
27877 the `set remote noack-packet off' command (*note Remote
27878 Configuration::), GDB may then send a `QStartNoAckMode' packet to the
27879 stub. Only then may the stub actually turn off packet acknowledgments.
27880 GDB sends a final `+' acknowledgment of the stub's `OK' response, which
27881 can be safely ignored by the stub.
27883 Note that `set remote noack-packet' command only affects negotiation
27884 between GDB and the stub when subsequent connections are made; it does
27885 not affect the protocol acknowledgment state for any current connection.
27886 Since `+'/`-' acknowledgments are enabled by default when a new
27887 connection is established, there is also no protocol request to
27888 re-enable the acknowledgments for the current connection, once disabled.
27891 File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Packet Acknowledgment, Up: Remote Protocol
27896 Example sequence of a target being re-started. Notice how the restart
27897 does not get any direct output:
27904 <- `T001:1234123412341234'
27907 Example sequence of a target being stepped by a single instruction:
27914 <- `T001:1234123412341234'
27922 File: gdb.info, Node: File-I/O Remote Protocol Extension, Next: Library List Format, Prev: Examples, Up: Remote Protocol
27924 D.13 File-I/O Remote Protocol Extension
27925 =======================================
27929 * File-I/O Overview::
27930 * Protocol Basics::
27931 * The F Request Packet::
27932 * The F Reply Packet::
27933 * The Ctrl-C Message::
27935 * List of Supported Calls::
27936 * Protocol-specific Representation of Datatypes::
27938 * File-I/O Examples::
27941 File: gdb.info, Node: File-I/O Overview, Next: Protocol Basics, Up: File-I/O Remote Protocol Extension
27943 D.13.1 File-I/O Overview
27944 ------------------------
27946 The "File I/O remote protocol extension" (short: File-I/O) allows the
27947 target to use the host's file system and console I/O to perform various
27948 system calls. System calls on the target system are translated into a
27949 remote protocol packet to the host system, which then performs the
27950 needed actions and returns a response packet to the target system.
27951 This simulates file system operations even on targets that lack file
27954 The protocol is defined to be independent of both the host and
27955 target systems. It uses its own internal representation of datatypes
27956 and values. Both GDB and the target's GDB stub are responsible for
27957 translating the system-dependent value representations into the internal
27958 protocol representations when data is transmitted.
27960 The communication is synchronous. A system call is possible only
27961 when GDB is waiting for a response from the `C', `c', `S' or `s'
27962 packets. While GDB handles the request for a system call, the target
27963 is stopped to allow deterministic access to the target's memory.
27964 Therefore File-I/O is not interruptible by target signals. On the
27965 other hand, it is possible to interrupt File-I/O by a user interrupt
27966 (`Ctrl-C') within GDB.
27968 The target's request to perform a host system call does not finish
27969 the latest `C', `c', `S' or `s' action. That means, after finishing
27970 the system call, the target returns to continuing the previous activity
27971 (continue, step). No additional continue or step request from GDB is
27975 <- target requests 'system call X'
27976 target is stopped, GDB executes system call
27977 -> GDB returns result
27978 ... target continues, GDB returns to wait for the target
27979 <- target hits breakpoint and sends a Txx packet
27981 The protocol only supports I/O on the console and to regular files on
27982 the host file system. Character or block special devices, pipes, named
27983 pipes, sockets or any other communication method on the host system are
27984 not supported by this protocol.
27986 File I/O is not supported in non-stop mode.
27989 File: gdb.info, Node: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension
27991 D.13.2 Protocol Basics
27992 ----------------------
27994 The File-I/O protocol uses the `F' packet as the request as well as
27995 reply packet. Since a File-I/O system call can only occur when GDB is
27996 waiting for a response from the continuing or stepping target, the
27997 File-I/O request is a reply that GDB has to expect as a result of a
27998 previous `C', `c', `S' or `s' packet. This `F' packet contains all
27999 information needed to allow GDB to call the appropriate host system
28002 * A unique identifier for the requested system call.
28004 * All parameters to the system call. Pointers are given as addresses
28005 in the target memory address space. Pointers to strings are given
28006 as pointer/length pair. Numerical values are given as they are.
28007 Numerical control flags are given in a protocol-specific
28011 At this point, GDB has to perform the following actions.
28013 * If the parameters include pointer values to data needed as input
28014 to a system call, GDB requests this data from the target with a
28015 standard `m' packet request. This additional communication has to
28016 be expected by the target implementation and is handled as any
28019 * GDB translates all value from protocol representation to host
28020 representation as needed. Datatypes are coerced into the host
28023 * GDB calls the system call.
28025 * It then coerces datatypes back to protocol representation.
28027 * If the system call is expected to return data in buffer space
28028 specified by pointer parameters to the call, the data is
28029 transmitted to the target using a `M' or `X' packet. This packet
28030 has to be expected by the target implementation and is handled as
28031 any other `M' or `X' packet.
28034 Eventually GDB replies with another `F' packet which contains all
28035 necessary information for the target to continue. This at least
28040 * `errno', if has been changed by the system call.
28045 After having done the needed type and value coercion, the target
28046 continues the latest continue or step action.
28049 File: gdb.info, Node: The F Request Packet, Next: The F Reply Packet, Prev: Protocol Basics, Up: File-I/O Remote Protocol Extension
28051 D.13.3 The `F' Request Packet
28052 -----------------------------
28054 The `F' request packet has the following format:
28056 `FCALL-ID,PARAMETER...'
28057 CALL-ID is the identifier to indicate the host system call to be
28058 called. This is just the name of the function.
28060 PARAMETER... are the parameters to the system call. Parameters
28061 are hexadecimal integer values, either the actual values in case
28062 of scalar datatypes, pointers to target buffer space in case of
28063 compound datatypes and unspecified memory areas, or pointer/length
28064 pairs in case of string parameters. These are appended to the
28065 CALL-ID as a comma-delimited list. All values are transmitted in
28066 ASCII string representation, pointer/length pairs separated by a
28071 File: gdb.info, Node: The F Reply Packet, Next: The Ctrl-C Message, Prev: The F Request Packet, Up: File-I/O Remote Protocol Extension
28073 D.13.4 The `F' Reply Packet
28074 ---------------------------
28076 The `F' reply packet has the following format:
28078 `FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT'
28079 RETCODE is the return code of the system call as hexadecimal value.
28081 ERRNO is the `errno' set by the call, in protocol-specific
28082 representation. This parameter can be omitted if the call was
28085 CTRL-C FLAG is only sent if the user requested a break. In this
28086 case, ERRNO must be sent as well, even if the call was successful.
28087 The CTRL-C FLAG itself consists of the character `C':
28091 or, if the call was interrupted before the host call has been
28096 assuming 4 is the protocol-specific representation of `EINTR'.
28100 File: gdb.info, Node: The Ctrl-C Message, Next: Console I/O, Prev: The F Reply Packet, Up: File-I/O Remote Protocol Extension
28102 D.13.5 The `Ctrl-C' Message
28103 ---------------------------
28105 If the `Ctrl-C' flag is set in the GDB reply packet (*note The F Reply
28106 Packet::), the target should behave as if it had gotten a break
28107 message. The meaning for the target is "system call interrupted by
28108 `SIGINT'". Consequentially, the target should actually stop (as with a
28109 break message) and return to GDB with a `T02' packet.
28111 It's important for the target to know in which state the system call
28112 was interrupted. There are two possible cases:
28114 * The system call hasn't been performed on the host yet.
28116 * The system call on the host has been finished.
28119 These two states can be distinguished by the target by the value of
28120 the returned `errno'. If it's the protocol representation of `EINTR',
28121 the system call hasn't been performed. This is equivalent to the
28122 `EINTR' handling on POSIX systems. In any other case, the target may
28123 presume that the system call has been finished -- successfully or not
28124 -- and should behave as if the break message arrived right after the
28127 GDB must behave reliably. If the system call has not been called
28128 yet, GDB may send the `F' reply immediately, setting `EINTR' as `errno'
28129 in the packet. If the system call on the host has been finished before
28130 the user requests a break, the full action must be finished by GDB.
28131 This requires sending `M' or `X' packets as necessary. The `F' packet
28132 may only be sent when either nothing has happened or the full action
28133 has been completed.
28136 File: gdb.info, Node: Console I/O, Next: List of Supported Calls, Prev: The Ctrl-C Message, Up: File-I/O Remote Protocol Extension
28141 By default and if not explicitly closed by the target system, the file
28142 descriptors 0, 1 and 2 are connected to the GDB console. Output on the
28143 GDB console is handled as any other file output operation (`write(1,
28144 ...)' or `write(2, ...)'). Console input is handled by GDB so that
28145 after the target read request from file descriptor 0 all following
28146 typing is buffered until either one of the following conditions is met:
28148 * The user types `Ctrl-c'. The behaviour is as explained above, and
28149 the `read' system call is treated as finished.
28151 * The user presses <RET>. This is treated as end of input with a
28154 * The user types `Ctrl-d'. This is treated as end of input. No
28155 trailing character (neither newline nor `Ctrl-D') is appended to
28159 If the user has typed more characters than fit in the buffer given to
28160 the `read' call, the trailing characters are buffered in GDB until
28161 either another `read(0, ...)' is requested by the target, or debugging
28162 is stopped at the user's request.
28165 File: gdb.info, Node: List of Supported Calls, Next: Protocol-specific Representation of Datatypes, Prev: Console I/O, Up: File-I/O Remote Protocol Extension
28167 D.13.7 List of Supported Calls
28168 ------------------------------
28185 File: gdb.info, Node: open, Next: close, Up: List of Supported Calls
28191 int open(const char *pathname, int flags);
28192 int open(const char *pathname, int flags, mode_t mode);
28195 `Fopen,PATHPTR/LEN,FLAGS,MODE'
28197 FLAGS is the bitwise `OR' of the following values:
28200 If the file does not exist it will be created. The host
28201 rules apply as far as file ownership and time stamps are
28205 When used with `O_CREAT', if the file already exists it is an
28206 error and open() fails.
28209 If the file already exists and the open mode allows writing
28210 (`O_RDWR' or `O_WRONLY' is given) it will be truncated to
28214 The file is opened in append mode.
28217 The file is opened for reading only.
28220 The file is opened for writing only.
28223 The file is opened for reading and writing.
28225 Other bits are silently ignored.
28227 MODE is the bitwise `OR' of the following values:
28230 User has read permission.
28233 User has write permission.
28236 Group has read permission.
28239 Group has write permission.
28242 Others have read permission.
28245 Others have write permission.
28247 Other bits are silently ignored.
28250 `open' returns the new file descriptor or -1 if an error occurred.
28255 PATHNAME already exists and `O_CREAT' and `O_EXCL' were used.
28258 PATHNAME refers to a directory.
28261 The requested access is not allowed.
28264 PATHNAME was too long.
28267 A directory component in PATHNAME does not exist.
28270 PATHNAME refers to a device, pipe, named pipe or socket.
28273 PATHNAME refers to a file on a read-only filesystem and write
28274 access was requested.
28277 PATHNAME is an invalid pointer value.
28280 No space on device to create the file.
28283 The process already has the maximum number of files open.
28286 The limit on the total number of files open on the system has
28290 The call was interrupted by the user.
28294 File: gdb.info, Node: close, Next: read, Prev: open, Up: List of Supported Calls
28306 `close' returns zero on success, or -1 if an error occurred.
28311 FD isn't a valid open file descriptor.
28314 The call was interrupted by the user.
28318 File: gdb.info, Node: read, Next: write, Prev: close, Up: List of Supported Calls
28324 int read(int fd, void *buf, unsigned int count);
28327 `Fread,FD,BUFPTR,COUNT'
28330 On success, the number of bytes read is returned. Zero indicates
28331 end of file. If count is zero, read returns zero as well. On
28332 error, -1 is returned.
28337 FD is not a valid file descriptor or is not open for reading.
28340 BUFPTR is an invalid pointer value.
28343 The call was interrupted by the user.
28347 File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of Supported Calls
28353 int write(int fd, const void *buf, unsigned int count);
28356 `Fwrite,FD,BUFPTR,COUNT'
28359 On success, the number of bytes written are returned. Zero
28360 indicates nothing was written. On error, -1 is returned.
28365 FD is not a valid file descriptor or is not open for writing.
28368 BUFPTR is an invalid pointer value.
28371 An attempt was made to write a file that exceeds the
28372 host-specific maximum file size allowed.
28375 No space on device to write the data.
28378 The call was interrupted by the user.
28382 File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of Supported Calls
28388 long lseek (int fd, long offset, int flag);
28391 `Flseek,FD,OFFSET,FLAG'
28396 The offset is set to OFFSET bytes.
28399 The offset is set to its current location plus OFFSET bytes.
28402 The offset is set to the size of the file plus OFFSET bytes.
28405 On success, the resulting unsigned offset in bytes from the
28406 beginning of the file is returned. Otherwise, a value of -1 is
28412 FD is not a valid open file descriptor.
28415 FD is associated with the GDB console.
28418 FLAG is not a proper value.
28421 The call was interrupted by the user.
28425 File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of Supported Calls
28431 int rename(const char *oldpath, const char *newpath);
28434 `Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN'
28437 On success, zero is returned. On error, -1 is returned.
28442 NEWPATH is an existing directory, but OLDPATH is not a
28446 NEWPATH is a non-empty directory.
28449 OLDPATH or NEWPATH is a directory that is in use by some
28453 An attempt was made to make a directory a subdirectory of
28457 A component used as a directory in OLDPATH or new path is
28458 not a directory. Or OLDPATH is a directory and NEWPATH
28459 exists but is not a directory.
28462 OLDPATHPTR or NEWPATHPTR are invalid pointer values.
28465 No access to the file or the path of the file.
28468 OLDPATH or NEWPATH was too long.
28471 A directory component in OLDPATH or NEWPATH does not exist.
28474 The file is on a read-only filesystem.
28477 The device containing the file has no room for the new
28481 The call was interrupted by the user.
28485 File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of Supported Calls
28491 int unlink(const char *pathname);
28494 `Funlink,PATHNAMEPTR/LEN'
28497 On success, zero is returned. On error, -1 is returned.
28502 No access to the file or the path of the file.
28505 The system does not allow unlinking of directories.
28508 The file PATHNAME cannot be unlinked because it's being used
28509 by another process.
28512 PATHNAMEPTR is an invalid pointer value.
28515 PATHNAME was too long.
28518 A directory component in PATHNAME does not exist.
28521 A component of the path is not a directory.
28524 The file is on a read-only filesystem.
28527 The call was interrupted by the user.
28531 File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of Supported Calls
28537 int stat(const char *pathname, struct stat *buf);
28538 int fstat(int fd, struct stat *buf);
28541 `Fstat,PATHNAMEPTR/LEN,BUFPTR'
28545 On success, zero is returned. On error, -1 is returned.
28550 FD is not a valid open file.
28553 A directory component in PATHNAME does not exist or the path
28554 is an empty string.
28557 A component of the path is not a directory.
28560 PATHNAMEPTR is an invalid pointer value.
28563 No access to the file or the path of the file.
28566 PATHNAME was too long.
28569 The call was interrupted by the user.
28573 File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of Supported Calls
28579 int gettimeofday(struct timeval *tv, void *tz);
28582 `Fgettimeofday,TVPTR,TZPTR'
28585 On success, 0 is returned, -1 otherwise.
28590 TZ is a non-NULL pointer.
28593 TVPTR and/or TZPTR is an invalid pointer value.
28597 File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of Supported Calls
28603 int isatty(int fd);
28609 Returns 1 if FD refers to the GDB console, 0 otherwise.
28614 The call was interrupted by the user.
28617 Note that the `isatty' call is treated as a special case: it returns
28618 1 to the target if the file descriptor is attached to the GDB console,
28619 0 otherwise. Implementing through system calls would require
28620 implementing `ioctl' and would be more complex than needed.
28623 File: gdb.info, Node: system, Prev: isatty, Up: List of Supported Calls
28629 int system(const char *command);
28632 `Fsystem,COMMANDPTR/LEN'
28635 If LEN is zero, the return value indicates whether a shell is
28636 available. A zero return value indicates a shell is not available.
28637 For non-zero LEN, the value returned is -1 on error and the return
28638 status of the command otherwise. Only the exit status of the
28639 command is returned, which is extracted from the host's `system'
28640 return value by calling `WEXITSTATUS(retval)'. In case `/bin/sh'
28641 could not be executed, 127 is returned.
28646 The call was interrupted by the user.
28649 GDB takes over the full task of calling the necessary host calls to
28650 perform the `system' call. The return value of `system' on the host is
28651 simplified before it's returned to the target. Any termination signal
28652 information from the child process is discarded, and the return value
28653 consists entirely of the exit status of the called command.
28655 Due to security concerns, the `system' call is by default refused by
28656 GDB. The user has to allow this call explicitly with the `set remote
28657 system-call-allowed 1' command.
28659 `set remote system-call-allowed'
28660 Control whether to allow the `system' calls in the File I/O
28661 protocol for the remote target. The default is zero (disabled).
28663 `show remote system-call-allowed'
28664 Show whether the `system' calls are allowed in the File I/O
28668 File: gdb.info, Node: Protocol-specific Representation of Datatypes, Next: Constants, Prev: List of Supported Calls, Up: File-I/O Remote Protocol Extension
28670 D.13.8 Protocol-specific Representation of Datatypes
28671 ----------------------------------------------------
28675 * Integral Datatypes::
28677 * Memory Transfer::
28682 File: gdb.info, Node: Integral Datatypes, Next: Pointer Values, Up: Protocol-specific Representation of Datatypes
28687 The integral datatypes used in the system calls are `int', `unsigned
28688 int', `long', `unsigned long', `mode_t', and `time_t'.
28690 `int', `unsigned int', `mode_t' and `time_t' are implemented as 32
28691 bit values in this protocol.
28693 `long' and `unsigned long' are implemented as 64 bit types.
28695 *Note Limits::, for corresponding MIN and MAX values (similar to
28696 those in `limits.h') to allow range checking on host and target.
28698 `time_t' datatypes are defined as seconds since the Epoch.
28700 All integral datatypes transferred as part of a memory read or write
28701 of a structured datatype e.g. a `struct stat' have to be given in big
28705 File: gdb.info, Node: Pointer Values, Next: Memory Transfer, Prev: Integral Datatypes, Up: Protocol-specific Representation of Datatypes
28710 Pointers to target data are transmitted as they are. An exception is
28711 made for pointers to buffers for which the length isn't transmitted as
28712 part of the function call, namely strings. Strings are transmitted as
28713 a pointer/length pair, both as hex values, e.g.
28717 which is a pointer to data of length 18 bytes at position 0x1aaf. The
28718 length is defined as the full string length in bytes, including the
28719 trailing null byte. For example, the string `"hello world"' at address
28720 0x123456 is transmitted as
28725 File: gdb.info, Node: Memory Transfer, Next: struct stat, Prev: Pointer Values, Up: Protocol-specific Representation of Datatypes
28730 Structured data which is transferred using a memory read or write (for
28731 example, a `struct stat') is expected to be in a protocol-specific
28732 format with all scalar multibyte datatypes being big endian.
28733 Translation to this representation needs to be done both by the target
28734 before the `F' packet is sent, and by GDB before it transfers memory to
28735 the target. Transferred pointers to structured data should point to
28736 the already-coerced data at any time.
28739 File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory Transfer, Up: Protocol-specific Representation of Datatypes
28744 The buffer of type `struct stat' used by the target and GDB is defined
28748 unsigned int st_dev; /* device */
28749 unsigned int st_ino; /* inode */
28750 mode_t st_mode; /* protection */
28751 unsigned int st_nlink; /* number of hard links */
28752 unsigned int st_uid; /* user ID of owner */
28753 unsigned int st_gid; /* group ID of owner */
28754 unsigned int st_rdev; /* device type (if inode device) */
28755 unsigned long st_size; /* total size, in bytes */
28756 unsigned long st_blksize; /* blocksize for filesystem I/O */
28757 unsigned long st_blocks; /* number of blocks allocated */
28758 time_t st_atime; /* time of last access */
28759 time_t st_mtime; /* time of last modification */
28760 time_t st_ctime; /* time of last change */
28763 The integral datatypes conform to the definitions given in the
28764 appropriate section (see *note Integral Datatypes::, for details) so
28765 this structure is of size 64 bytes.
28767 The values of several fields have a restricted meaning and/or range
28771 A value of 0 represents a file, 1 the console.
28774 No valid meaning for the target. Transmitted unchanged.
28777 Valid mode bits are described in *note Constants::. Any other
28778 bits have currently no meaning for the target.
28783 No valid meaning for the target. Transmitted unchanged.
28788 These values have a host and file system dependent accuracy.
28789 Especially on Windows hosts, the file system may not support exact
28792 The target gets a `struct stat' of the above representation and is
28793 responsible for coercing it to the target representation before
28796 Note that due to size differences between the host, target, and
28797 protocol representations of `struct stat' members, these members could
28798 eventually get truncated on the target.
28801 File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol-specific Representation of Datatypes
28806 The buffer of type `struct timeval' used by the File-I/O protocol is
28807 defined as follows:
28810 time_t tv_sec; /* second */
28811 long tv_usec; /* microsecond */
28814 The integral datatypes conform to the definitions given in the
28815 appropriate section (see *note Integral Datatypes::, for details) so
28816 this structure is of size 8 bytes.
28819 File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol-specific Representation of Datatypes, Up: File-I/O Remote Protocol Extension
28824 The following values are used for the constants inside of the protocol.
28825 GDB and target are responsible for translating these values before and
28826 after the call as needed.
28837 File: gdb.info, Node: Open Flags, Next: mode_t Values, Up: Constants
28842 All values are given in hexadecimal representation.
28853 File: gdb.info, Node: mode_t Values, Next: Errno Values, Prev: Open Flags, Up: Constants
28858 All values are given in octal representation.
28873 File: gdb.info, Node: Errno Values, Next: Lseek Flags, Prev: mode_t Values, Up: Constants
28878 All values are given in decimal representation.
28901 `EUNKNOWN' is used as a fallback error value if a host system returns
28902 any error value not in the list of supported error numbers.
28905 File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants
28915 File: gdb.info, Node: Limits, Prev: Lseek Flags, Up: Constants
28920 All values are given in decimal representation.
28922 INT_MIN -2147483648
28924 UINT_MAX 4294967295
28925 LONG_MIN -9223372036854775808
28926 LONG_MAX 9223372036854775807
28927 ULONG_MAX 18446744073709551615
28930 File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O Remote Protocol Extension
28932 D.13.10 File-I/O Examples
28933 -------------------------
28935 Example sequence of a write call, file descriptor 3, buffer is at target
28936 address 0x1234, 6 bytes should be written:
28938 <- `Fwrite,3,1234,6'
28939 _request memory read from target_
28942 _return "6 bytes written"_
28945 Example sequence of a read call, file descriptor 3, buffer is at
28946 target address 0x1234, 6 bytes should be read:
28948 <- `Fread,3,1234,6'
28949 _request memory write to target_
28950 -> `X1234,6:XXXXXX'
28951 _return "6 bytes read"_
28954 Example sequence of a read call, call fails on the host due to
28955 invalid file descriptor (`EBADF'):
28957 <- `Fread,3,1234,6'
28960 Example sequence of a read call, user presses `Ctrl-c' before
28961 syscall on host is called:
28963 <- `Fread,3,1234,6'
28967 Example sequence of a read call, user presses `Ctrl-c' after syscall
28970 <- `Fread,3,1234,6'
28971 -> `X1234,6:XXXXXX'
28975 File: gdb.info, Node: Library List Format, Next: Memory Map Format, Prev: File-I/O Remote Protocol Extension, Up: Remote Protocol
28977 D.14 Library List Format
28978 ========================
28980 On some platforms, a dynamic loader (e.g. `ld.so') runs in the same
28981 process as your application to manage libraries. In this case, GDB can
28982 use the loader's symbol table and normal memory operations to maintain
28983 a list of shared libraries. On other platforms, the operating system
28984 manages loaded libraries. GDB can not retrieve the list of currently
28985 loaded libraries through memory operations, so it uses the
28986 `qXfer:libraries:read' packet (*note qXfer library list read::)
28987 instead. The remote stub queries the target's operating system and
28988 reports which libraries are loaded.
28990 The `qXfer:libraries:read' packet returns an XML document which
28991 lists loaded libraries and their offsets. Each library has an
28992 associated name and one or more segment or section base addresses,
28993 which report where the library was loaded in memory.
28995 For the common case of libraries that are fully linked binaries, the
28996 library should have a list of segments. If the target supports dynamic
28997 linking of a relocatable object file, its library XML element should
28998 instead include a list of allocated sections. The segment or section
28999 bases are start addresses, not relocation offsets; they do not depend
29000 on the library's link-time base addresses.
29002 GDB must be linked with the Expat library to support XML library
29003 lists. *Note Expat::.
29005 A simple memory map, with one loaded library relocated by a single
29006 offset, looks like this:
29009 <library name="/lib/libc.so.6">
29010 <segment address="0x10000000"/>
29014 Another simple memory map, with one loaded library with three
29015 allocated sections (.text, .data, .bss), looks like this:
29018 <library name="sharedlib.o">
29019 <section address="0x10000000"/>
29020 <section address="0x20000000"/>
29021 <section address="0x30000000"/>
29025 The format of a library list is described by this DTD:
29027 <!-- library-list: Root element with versioning -->
29028 <!ELEMENT library-list (library)*>
29029 <!ATTLIST library-list version CDATA #FIXED "1.0">
29030 <!ELEMENT library (segment*, section*)>
29031 <!ATTLIST library name CDATA #REQUIRED>
29032 <!ELEMENT segment EMPTY>
29033 <!ATTLIST segment address CDATA #REQUIRED>
29034 <!ELEMENT section EMPTY>
29035 <!ATTLIST section address CDATA #REQUIRED>
29037 In addition, segments and section descriptors cannot be mixed within
29038 a single library element, and you must supply at least one segment or
29039 section for each library.
29042 File: gdb.info, Node: Memory Map Format, Next: Thread List Format, Prev: Library List Format, Up: Remote Protocol
29044 D.15 Memory Map Format
29045 ======================
29047 To be able to write into flash memory, GDB needs to obtain a memory map
29048 from the target. This section describes the format of the memory map.
29050 The memory map is obtained using the `qXfer:memory-map:read' (*note
29051 qXfer memory map read::) packet and is an XML document that lists
29054 GDB must be linked with the Expat library to support XML memory
29055 maps. *Note Expat::.
29057 The top-level structure of the document is shown below:
29059 <?xml version="1.0"?>
29060 <!DOCTYPE memory-map
29061 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
29062 "http://sourceware.org/gdb/gdb-memory-map.dtd">
29067 Each region can be either:
29069 * A region of RAM starting at ADDR and extending for LENGTH bytes
29072 <memory type="ram" start="ADDR" length="LENGTH"/>
29074 * A region of read-only memory:
29076 <memory type="rom" start="ADDR" length="LENGTH"/>
29078 * A region of flash memory, with erasure blocks BLOCKSIZE bytes in
29081 <memory type="flash" start="ADDR" length="LENGTH">
29082 <property name="blocksize">BLOCKSIZE</property>
29086 Regions must not overlap. GDB assumes that areas of memory not
29087 covered by the memory map are RAM, and uses the ordinary `M' and `X'
29088 packets to write to addresses in such ranges.
29090 The formal DTD for memory map format is given below:
29092 <!-- ................................................... -->
29093 <!-- Memory Map XML DTD ................................ -->
29094 <!-- File: memory-map.dtd .............................. -->
29095 <!-- .................................... .............. -->
29096 <!-- memory-map.dtd -->
29097 <!-- memory-map: Root element with versioning -->
29098 <!ELEMENT memory-map (memory | property)>
29099 <!ATTLIST memory-map version CDATA #FIXED "1.0.0">
29100 <!ELEMENT memory (property)>
29101 <!-- memory: Specifies a memory region,
29102 and its type, or device. -->
29103 <!ATTLIST memory type CDATA #REQUIRED
29104 start CDATA #REQUIRED
29105 length CDATA #REQUIRED
29106 device CDATA #IMPLIED>
29107 <!-- property: Generic attribute tag -->
29108 <!ELEMENT property (#PCDATA | property)*>
29109 <!ATTLIST property name CDATA #REQUIRED>
29112 File: gdb.info, Node: Thread List Format, Prev: Memory Map Format, Up: Remote Protocol
29114 D.16 Thread List Format
29115 =======================
29117 To efficiently update the list of threads and their attributes, GDB
29118 issues the `qXfer:threads:read' packet (*note qXfer threads read::) and
29119 obtains the XML document with the following structure:
29121 <?xml version="1.0"?>
29123 <thread id="id" core="0">
29124 ... description ...
29128 Each `thread' element must have the `id' attribute that identifies
29129 the thread (*note thread-id syntax::). The `core' attribute, if
29130 present, specifies which processor core the thread was last executing
29131 on. The content of the of `thread' element is interpreted as
29132 human-readable auxilliary information.
29135 File: gdb.info, Node: Agent Expressions, Next: Target Descriptions, Prev: Remote Protocol, Up: Top
29137 Appendix E The GDB Agent Expression Mechanism
29138 *********************************************
29140 In some applications, it is not feasible for the debugger to interrupt
29141 the program's execution long enough for the developer to learn anything
29142 helpful about its behavior. If the program's correctness depends on its
29143 real-time behavior, delays introduced by a debugger might cause the
29144 program to fail, even when the code itself is correct. It is useful to
29145 be able to observe the program's behavior without interrupting it.
29147 Using GDB's `trace' and `collect' commands, the user can specify
29148 locations in the program, and arbitrary expressions to evaluate when
29149 those locations are reached. Later, using the `tfind' command, she can
29150 examine the values those expressions had when the program hit the trace
29151 points. The expressions may also denote objects in memory --
29152 structures or arrays, for example -- whose values GDB should record;
29153 while visiting a particular tracepoint, the user may inspect those
29154 objects as if they were in memory at that moment. However, because GDB
29155 records these values without interacting with the user, it can do so
29156 quickly and unobtrusively, hopefully not disturbing the program's
29159 When GDB is debugging a remote target, the GDB "agent" code running
29160 on the target computes the values of the expressions itself. To avoid
29161 having a full symbolic expression evaluator on the agent, GDB translates
29162 expressions in the source language into a simpler bytecode language, and
29163 then sends the bytecode to the agent; the agent then executes the
29164 bytecode, and records the values for GDB to retrieve later.
29166 The bytecode language is simple; there are forty-odd opcodes, the
29167 bulk of which are the usual vocabulary of C operands (addition,
29168 subtraction, shifts, and so on) and various sizes of literals and
29169 memory reference operations. The bytecode interpreter operates
29170 strictly on machine-level values -- various sizes of integers and
29171 floating point numbers -- and requires no information about types or
29172 symbols; thus, the interpreter's internal data structures are simple,
29173 and each bytecode requires only a few native machine instructions to
29174 implement it. The interpreter is small, and strict limits on the
29175 memory and time required to evaluate an expression are easy to
29176 determine, making it suitable for use by the debugging agent in
29177 real-time applications.
29181 * General Bytecode Design:: Overview of the interpreter.
29182 * Bytecode Descriptions:: What each one does.
29183 * Using Agent Expressions:: How agent expressions fit into the big picture.
29184 * Varying Target Capabilities:: How to discover what the target can do.
29185 * Rationale:: Why we did it this way.
29188 File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions
29190 E.1 General Bytecode Design
29191 ===========================
29193 The agent represents bytecode expressions as an array of bytes. Each
29194 instruction is one byte long (thus the term "bytecode"). Some
29195 instructions are followed by operand bytes; for example, the `goto'
29196 instruction is followed by a destination for the jump.
29198 The bytecode interpreter is a stack-based machine; most instructions
29199 pop their operands off the stack, perform some operation, and push the
29200 result back on the stack for the next instruction to consume. Each
29201 element of the stack may contain either a integer or a floating point
29202 value; these values are as many bits wide as the largest integer that
29203 can be directly manipulated in the source language. Stack elements
29204 carry no record of their type; bytecode could push a value as an
29205 integer, then pop it as a floating point value. However, GDB will not
29206 generate code which does this. In C, one might define the type of a
29207 stack element as follows:
29212 where `LONGEST' and `DOUBLEST' are `typedef' names for the largest
29213 integer and floating point types on the machine.
29215 By the time the bytecode interpreter reaches the end of the
29216 expression, the value of the expression should be the only value left
29217 on the stack. For tracing applications, `trace' bytecodes in the
29218 expression will have recorded the necessary data, and the value on the
29219 stack may be discarded. For other applications, like conditional
29220 breakpoints, the value may be useful.
29222 Separate from the stack, the interpreter has two registers:
29224 The address of the next bytecode to execute.
29227 The address of the start of the bytecode expression, necessary for
29228 interpreting the `goto' and `if_goto' instructions.
29230 Neither of these registers is directly visible to the bytecode
29231 language itself, but they are useful for defining the meanings of the
29232 bytecode operations.
29234 There are no instructions to perform side effects on the running
29235 program, or call the program's functions; we assume that these
29236 expressions are only used for unobtrusive debugging, not for patching
29239 Most bytecode instructions do not distinguish between the various
29240 sizes of values, and operate on full-width values; the upper bits of the
29241 values are simply ignored, since they do not usually make a difference
29242 to the value computed. The exceptions to this rule are:
29243 memory reference instructions (`ref'N)
29244 There are distinct instructions to fetch different word sizes from
29245 memory. Once on the stack, however, the values are treated as
29246 full-size integers. They may need to be sign-extended; the `ext'
29247 instruction exists for this purpose.
29249 the sign-extension instruction (`ext' N)
29250 These clearly need to know which portion of their operand is to be
29251 extended to occupy the full length of the word.
29254 If the interpreter is unable to evaluate an expression completely for
29255 some reason (a memory location is inaccessible, or a divisor is zero,
29256 for example), we say that interpretation "terminates with an error".
29257 This means that the problem is reported back to the interpreter's caller
29258 in some helpful way. In general, code using agent expressions should
29259 assume that they may attempt to divide by zero, fetch arbitrary memory
29260 locations, and misbehave in other ways.
29262 Even complicated C expressions compile to a few bytecode
29263 instructions; for example, the expression `x + y * z' would typically
29264 produce code like the following, assuming that `x' and `y' live in
29265 registers, and `z' is a global variable holding a 32-bit `int':
29268 const32 address of z
29275 In detail, these mean:
29277 Push the value of register 1 (presumably holding `x') onto the
29281 Push the value of register 2 (holding `y').
29283 `const32 address of z'
29284 Push the address of `z' onto the stack.
29287 Fetch a 32-bit word from the address at the top of the stack;
29288 replace the address on the stack with the value. Thus, we replace
29289 the address of `z' with `z''s value.
29292 Sign-extend the value on the top of the stack from 32 bits to full
29293 length. This is necessary because `z' is a signed integer.
29296 Pop the top two numbers on the stack, multiply them, and push their
29297 product. Now the top of the stack contains the value of the
29298 expression `y * z'.
29301 Pop the top two numbers, add them, and push the sum. Now the top
29302 of the stack contains the value of `x + y * z'.
29305 Stop executing; the value left on the stack top is the value to be
29310 File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions
29312 E.2 Bytecode Descriptions
29313 =========================
29315 Each bytecode description has the following form:
29317 `add' (0x02): A B => A+B
29318 Pop the top two stack items, A and B, as integers; push their sum,
29322 In this example, `add' is the name of the bytecode, and `(0x02)' is
29323 the one-byte value used to encode the bytecode, in hexadecimal. The
29324 phrase "A B => A+B" shows the stack before and after the bytecode
29325 executes. Beforehand, the stack must contain at least two values, A
29326 and B; since the top of the stack is to the right, B is on the top of
29327 the stack, and A is underneath it. After execution, the bytecode will
29328 have popped A and B from the stack, and replaced them with a single
29329 value, A+B. There may be other values on the stack below those shown,
29330 but the bytecode affects only those shown.
29332 Here is another example:
29334 `const8' (0x22) N: => N
29335 Push the 8-bit integer constant N on the stack, without sign
29339 In this example, the bytecode `const8' takes an operand N directly
29340 from the bytecode stream; the operand follows the `const8' bytecode
29341 itself. We write any such operands immediately after the name of the
29342 bytecode, before the colon, and describe the exact encoding of the
29343 operand in the bytecode stream in the body of the bytecode description.
29345 For the `const8' bytecode, there are no stack items given before the
29346 =>; this simply means that the bytecode consumes no values from the
29347 stack. If a bytecode consumes no values, or produces no values, the
29348 list on either side of the => may be empty.
29350 If a value is written as A, B, or N, then the bytecode treats it as
29351 an integer. If a value is written is ADDR, then the bytecode treats it
29354 We do not fully describe the floating point operations here; although
29355 this design can be extended in a clean way to handle floating point
29356 values, they are not of immediate interest to the customer, so we avoid
29357 describing them, to save time.
29360 Prefix for floating-point bytecodes. Not implemented yet.
29362 `add' (0x02): A B => A+B
29363 Pop two integers from the stack, and push their sum, as an integer.
29365 `sub' (0x03): A B => A-B
29366 Pop two integers from the stack, subtract the top value from the
29367 next-to-top value, and push the difference.
29369 `mul' (0x04): A B => A*B
29370 Pop two integers from the stack, multiply them, and push the
29371 product on the stack. Note that, when one multiplies two N-bit
29372 numbers yielding another N-bit number, it is irrelevant whether the
29373 numbers are signed or not; the results are the same.
29375 `div_signed' (0x05): A B => A/B
29376 Pop two signed integers from the stack; divide the next-to-top
29377 value by the top value, and push the quotient. If the divisor is
29378 zero, terminate with an error.
29380 `div_unsigned' (0x06): A B => A/B
29381 Pop two unsigned integers from the stack; divide the next-to-top
29382 value by the top value, and push the quotient. If the divisor is
29383 zero, terminate with an error.
29385 `rem_signed' (0x07): A B => A MODULO B
29386 Pop two signed integers from the stack; divide the next-to-top
29387 value by the top value, and push the remainder. If the divisor is
29388 zero, terminate with an error.
29390 `rem_unsigned' (0x08): A B => A MODULO B
29391 Pop two unsigned integers from the stack; divide the next-to-top
29392 value by the top value, and push the remainder. If the divisor is
29393 zero, terminate with an error.
29395 `lsh' (0x09): A B => A<<B
29396 Pop two integers from the stack; let A be the next-to-top value,
29397 and B be the top value. Shift A left by B bits, and push the
29400 `rsh_signed' (0x0a): A B => `(signed)'A>>B
29401 Pop two integers from the stack; let A be the next-to-top value,
29402 and B be the top value. Shift A right by B bits, inserting copies
29403 of the top bit at the high end, and push the result.
29405 `rsh_unsigned' (0x0b): A B => A>>B
29406 Pop two integers from the stack; let A be the next-to-top value,
29407 and B be the top value. Shift A right by B bits, inserting zero
29408 bits at the high end, and push the result.
29410 `log_not' (0x0e): A => !A
29411 Pop an integer from the stack; if it is zero, push the value one;
29412 otherwise, push the value zero.
29414 `bit_and' (0x0f): A B => A&B
29415 Pop two integers from the stack, and push their bitwise `and'.
29417 `bit_or' (0x10): A B => A|B
29418 Pop two integers from the stack, and push their bitwise `or'.
29420 `bit_xor' (0x11): A B => A^B
29421 Pop two integers from the stack, and push their bitwise
29424 `bit_not' (0x12): A => ~A
29425 Pop an integer from the stack, and push its bitwise complement.
29427 `equal' (0x13): A B => A=B
29428 Pop two integers from the stack; if they are equal, push the value
29429 one; otherwise, push the value zero.
29431 `less_signed' (0x14): A B => A<B
29432 Pop two signed integers from the stack; if the next-to-top value
29433 is less than the top value, push the value one; otherwise, push
29436 `less_unsigned' (0x15): A B => A<B
29437 Pop two unsigned integers from the stack; if the next-to-top value
29438 is less than the top value, push the value one; otherwise, push
29441 `ext' (0x16) N: A => A, sign-extended from N bits
29442 Pop an unsigned value from the stack; treating it as an N-bit
29443 twos-complement value, extend it to full length. This means that
29444 all bits to the left of bit N-1 (where the least significant bit
29445 is bit 0) are set to the value of bit N-1. Note that N may be
29446 larger than or equal to the width of the stack elements of the
29447 bytecode engine; in this case, the bytecode should have no effect.
29449 The number of source bits to preserve, N, is encoded as a single
29450 byte unsigned integer following the `ext' bytecode.
29452 `zero_ext' (0x2a) N: A => A, zero-extended from N bits
29453 Pop an unsigned value from the stack; zero all but the bottom N
29454 bits. This means that all bits to the left of bit N-1 (where the
29455 least significant bit is bit 0) are set to the value of bit N-1.
29457 The number of source bits to preserve, N, is encoded as a single
29458 byte unsigned integer following the `zero_ext' bytecode.
29460 `ref8' (0x17): ADDR => A
29461 `ref16' (0x18): ADDR => A
29462 `ref32' (0x19): ADDR => A
29463 `ref64' (0x1a): ADDR => A
29464 Pop an address ADDR from the stack. For bytecode `ref'N, fetch an
29465 N-bit value from ADDR, using the natural target endianness. Push
29466 the fetched value as an unsigned integer.
29468 Note that ADDR may not be aligned in any particular way; the
29469 `refN' bytecodes should operate correctly for any address.
29471 If attempting to access memory at ADDR would cause a processor
29472 exception of some sort, terminate with an error.
29474 `ref_float' (0x1b): ADDR => D
29475 `ref_double' (0x1c): ADDR => D
29476 `ref_long_double' (0x1d): ADDR => D
29477 `l_to_d' (0x1e): A => D
29478 `d_to_l' (0x1f): D => A
29479 Not implemented yet.
29481 `dup' (0x28): A => A A
29482 Push another copy of the stack's top element.
29484 `swap' (0x2b): A B => B A
29485 Exchange the top two items on the stack.
29488 Discard the top value on the stack.
29490 `if_goto' (0x20) OFFSET: A =>
29491 Pop an integer off the stack; if it is non-zero, branch to the
29492 given offset in the bytecode string. Otherwise, continue to the
29493 next instruction in the bytecode stream. In other words, if A is
29494 non-zero, set the `pc' register to `start' + OFFSET. Thus, an
29495 offset of zero denotes the beginning of the expression.
29497 The OFFSET is stored as a sixteen-bit unsigned value, stored
29498 immediately following the `if_goto' bytecode. It is always stored
29499 most significant byte first, regardless of the target's normal
29500 endianness. The offset is not guaranteed to fall at any particular
29501 alignment within the bytecode stream; thus, on machines where
29502 fetching a 16-bit on an unaligned address raises an exception, you
29503 should fetch the offset one byte at a time.
29505 `goto' (0x21) OFFSET: =>
29506 Branch unconditionally to OFFSET; in other words, set the `pc'
29507 register to `start' + OFFSET.
29509 The offset is stored in the same way as for the `if_goto' bytecode.
29511 `const8' (0x22) N: => N
29512 `const16' (0x23) N: => N
29513 `const32' (0x24) N: => N
29514 `const64' (0x25) N: => N
29515 Push the integer constant N on the stack, without sign extension.
29516 To produce a small negative value, push a small twos-complement
29517 value, and then sign-extend it using the `ext' bytecode.
29519 The constant N is stored in the appropriate number of bytes
29520 following the `const'B bytecode. The constant N is always stored
29521 most significant byte first, regardless of the target's normal
29522 endianness. The constant is not guaranteed to fall at any
29523 particular alignment within the bytecode stream; thus, on machines
29524 where fetching a 16-bit on an unaligned address raises an
29525 exception, you should fetch N one byte at a time.
29527 `reg' (0x26) N: => A
29528 Push the value of register number N, without sign extension. The
29529 registers are numbered following GDB's conventions.
29531 The register number N is encoded as a 16-bit unsigned integer
29532 immediately following the `reg' bytecode. It is always stored most
29533 significant byte first, regardless of the target's normal
29534 endianness. The register number is not guaranteed to fall at any
29535 particular alignment within the bytecode stream; thus, on machines
29536 where fetching a 16-bit on an unaligned address raises an
29537 exception, you should fetch the register number one byte at a time.
29539 `getv' (0x2c) N: => V
29540 Push the value of trace state variable number N, without sign
29543 The variable number N is encoded as a 16-bit unsigned integer
29544 immediately following the `getv' bytecode. It is always stored
29545 most significant byte first, regardless of the target's normal
29546 endianness. The variable number is not guaranteed to fall at any
29547 particular alignment within the bytecode stream; thus, on machines
29548 where fetching a 16-bit on an unaligned address raises an
29549 exception, you should fetch the register number one byte at a time.
29551 `setv' (0x2d) N: => V
29552 Set trace state variable number N to the value found on the top of
29553 the stack. The stack is unchanged, so that the value is readily
29554 available if the assignment is part of a larger expression. The
29555 handling of N is as described for `getv'.
29557 `trace' (0x0c): ADDR SIZE =>
29558 Record the contents of the SIZE bytes at ADDR in a trace buffer,
29559 for later retrieval by GDB.
29561 `trace_quick' (0x0d) SIZE: ADDR => ADDR
29562 Record the contents of the SIZE bytes at ADDR in a trace buffer,
29563 for later retrieval by GDB. SIZE is a single byte unsigned
29564 integer following the `trace' opcode.
29566 This bytecode is equivalent to the sequence `dup const8 SIZE
29567 trace', but we provide it anyway to save space in bytecode strings.
29569 `trace16' (0x30) SIZE: ADDR => ADDR
29570 Identical to trace_quick, except that SIZE is a 16-bit big-endian
29571 unsigned integer, not a single byte. This should probably have
29572 been named `trace_quick16', for consistency.
29574 `tracev' (0x2e) N: => A
29575 Record the value of trace state variable number N in the trace
29576 buffer. The handling of N is as described for `getv'.
29579 Stop executing bytecode; the result should be the top element of
29580 the stack. If the purpose of the expression was to compute an
29581 lvalue or a range of memory, then the next-to-top of the stack is
29582 the lvalue's address, and the top of the stack is the lvalue's
29587 File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions
29589 E.3 Using Agent Expressions
29590 ===========================
29592 Agent expressions can be used in several different ways by GDB, and the
29593 debugger can generate different bytecode sequences as appropriate.
29595 One possibility is to do expression evaluation on the target rather
29596 than the host, such as for the conditional of a conditional tracepoint.
29597 In such a case, GDB compiles the source expression into a bytecode
29598 sequence that simply gets values from registers or memory, does
29599 arithmetic, and returns a result.
29601 Another way to use agent expressions is for tracepoint data
29602 collection. GDB generates a different bytecode sequence for
29603 collection; in addition to bytecodes that do the calculation, GDB adds
29604 `trace' bytecodes to save the pieces of memory that were used.
29606 * The user selects trace points in the program's code at which GDB
29607 should collect data.
29609 * The user specifies expressions to evaluate at each trace point.
29610 These expressions may denote objects in memory, in which case
29611 those objects' contents are recorded as the program runs, or
29612 computed values, in which case the values themselves are recorded.
29614 * GDB transmits the tracepoints and their associated expressions to
29615 the GDB agent, running on the debugging target.
29617 * The agent arranges to be notified when a trace point is hit.
29619 * When execution on the target reaches a trace point, the agent
29620 evaluates the expressions associated with that trace point, and
29621 records the resulting values and memory ranges.
29623 * Later, when the user selects a given trace event and inspects the
29624 objects and expression values recorded, GDB talks to the agent to
29625 retrieve recorded data as necessary to meet the user's requests.
29626 If the user asks to see an object whose contents have not been
29627 recorded, GDB reports an error.
29631 File: gdb.info, Node: Varying Target Capabilities, Next: Rationale, Prev: Using Agent Expressions, Up: Agent Expressions
29633 E.4 Varying Target Capabilities
29634 ===============================
29636 Some targets don't support floating-point, and some would rather not
29637 have to deal with `long long' operations. Also, different targets will
29638 have different stack sizes, and different bytecode buffer lengths.
29640 Thus, GDB needs a way to ask the target about itself. We haven't
29641 worked out the details yet, but in general, GDB should be able to send
29642 the target a packet asking it to describe itself. The reply should be a
29643 packet whose length is explicit, so we can add new information to the
29644 packet in future revisions of the agent, without confusing old versions
29645 of GDB, and it should contain a version number. It should contain at
29646 least the following information:
29648 * whether floating point is supported
29650 * whether `long long' is supported
29652 * maximum acceptable size of bytecode stack
29654 * maximum acceptable length of bytecode expressions
29656 * which registers are actually available for collection
29658 * whether the target supports disabled tracepoints
29662 File: gdb.info, Node: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions
29667 Some of the design decisions apparent above are arguable.
29669 What about stack overflow/underflow?
29670 GDB should be able to query the target to discover its stack size.
29671 Given that information, GDB can determine at translation time
29672 whether a given expression will overflow the stack. But this spec
29673 isn't about what kinds of error-checking GDB ought to do.
29675 Why are you doing everything in LONGEST?
29676 Speed isn't important, but agent code size is; using LONGEST
29677 brings in a bunch of support code to do things like division, etc.
29678 So this is a serious concern.
29680 First, note that you don't need different bytecodes for different
29681 operand sizes. You can generate code without _knowing_ how big the
29682 stack elements actually are on the target. If the target only
29683 supports 32-bit ints, and you don't send any 64-bit bytecodes,
29684 everything just works. The observation here is that the MIPS and
29685 the Alpha have only fixed-size registers, and you can still get
29686 C's semantics even though most instructions only operate on
29687 full-sized words. You just need to make sure everything is
29688 properly sign-extended at the right times. So there is no need
29689 for 32- and 64-bit variants of the bytecodes. Just implement
29690 everything using the largest size you support.
29692 GDB should certainly check to see what sizes the target supports,
29693 so the user can get an error earlier, rather than later. But this
29694 information is not necessary for correctness.
29696 Why don't you have `>' or `<=' operators?
29697 I want to keep the interpreter small, and we don't need them. We
29698 can combine the `less_' opcodes with `log_not', and swap the order
29699 of the operands, yielding all four asymmetrical comparison
29700 operators. For example, `(x <= y)' is `! (x > y)', which is `! (y
29703 Why do you have `log_not'?
29704 Why do you have `ext'?
29705 Why do you have `zero_ext'?
29706 These are all easily synthesized from other instructions, but I
29707 expect them to be used frequently, and they're simple, so I
29708 include them to keep bytecode strings short.
29710 `log_not' is equivalent to `const8 0 equal'; it's used in half the
29711 relational operators.
29713 `ext N' is equivalent to `const8 S-N lsh const8 S-N rsh_signed',
29714 where S is the size of the stack elements; it follows `refM' and
29715 REG bytecodes when the value should be signed. See the next
29718 `zero_ext N' is equivalent to `constM MASK log_and'; it's used
29719 whenever we push the value of a register, because we can't assume
29720 the upper bits of the register aren't garbage.
29722 Why not have sign-extending variants of the `ref' operators?
29723 Because that would double the number of `ref' operators, and we
29724 need the `ext' bytecode anyway for accessing bitfields.
29726 Why not have constant-address variants of the `ref' operators?
29727 Because that would double the number of `ref' operators again, and
29728 `const32 ADDRESS ref32' is only one byte longer.
29730 Why do the `refN' operators have to support unaligned fetches?
29731 GDB will generate bytecode that fetches multi-byte values at
29732 unaligned addresses whenever the executable's debugging
29733 information tells it to. Furthermore, GDB does not know the value
29734 the pointer will have when GDB generates the bytecode, so it
29735 cannot determine whether a particular fetch will be aligned or not.
29737 In particular, structure bitfields may be several bytes long, but
29738 follow no alignment rules; members of packed structures are not
29739 necessarily aligned either.
29741 In general, there are many cases where unaligned references occur
29742 in correct C code, either at the programmer's explicit request, or
29743 at the compiler's discretion. Thus, it is simpler to make the GDB
29744 agent bytecodes work correctly in all circumstances than to make
29745 GDB guess in each case whether the compiler did the usual thing.
29747 Why are there no side-effecting operators?
29748 Because our current client doesn't want them? That's a cheap
29749 answer. I think the real answer is that I'm afraid of
29750 implementing function calls. We should re-visit this issue after
29751 the present contract is delivered.
29753 Why aren't the `goto' ops PC-relative?
29754 The interpreter has the base address around anyway for PC bounds
29755 checking, and it seemed simpler.
29757 Why is there only one offset size for the `goto' ops?
29758 Offsets are currently sixteen bits. I'm not happy with this
29761 Suppose we have multiple branch ops with different offset sizes.
29762 As I generate code left-to-right, all my jumps are forward jumps
29763 (there are no loops in expressions), so I never know the target
29764 when I emit the jump opcode. Thus, I have to either always assume
29765 the largest offset size, or do jump relaxation on the code after I
29766 generate it, which seems like a big waste of time.
29768 I can imagine a reasonable expression being longer than 256 bytes.
29769 I can't imagine one being longer than 64k. Thus, we need 16-bit
29770 offsets. This kind of reasoning is so bogus, but relaxation is
29773 The other approach would be to generate code right-to-left. Then
29774 I'd always know my offset size. That might be fun.
29776 Where is the function call bytecode?
29777 When we add side-effects, we should add this.
29779 Why does the `reg' bytecode take a 16-bit register number?
29780 Intel's IA-64 architecture has 128 general-purpose registers, and
29781 128 floating-point registers, and I'm sure it has some random
29784 Why do we need `trace' and `trace_quick'?
29785 Because GDB needs to record all the memory contents and registers
29786 an expression touches. If the user wants to evaluate an expression
29787 `x->y->z', the agent must record the values of `x' and `x->y' as
29788 well as the value of `x->y->z'.
29790 Don't the `trace' bytecodes make the interpreter less general?
29791 They do mean that the interpreter contains special-purpose code,
29792 but that doesn't mean the interpreter can only be used for that
29793 purpose. If an expression doesn't use the `trace' bytecodes, they
29794 don't get in its way.
29796 Why doesn't `trace_quick' consume its arguments the way everything else does?
29797 In general, you do want your operators to consume their arguments;
29798 it's consistent, and generally reduces the amount of stack
29799 rearrangement necessary. However, `trace_quick' is a kludge to
29800 save space; it only exists so we needn't write `dup const8 SIZE
29801 trace' before every memory reference. Therefore, it's okay for it
29802 not to consume its arguments; it's meant for a specific context in
29803 which we know exactly what it should do with the stack. If we're
29804 going to have a kludge, it should be an effective kludge.
29806 Why does `trace16' exist?
29807 That opcode was added by the customer that contracted Cygnus for
29808 the data tracing work. I personally think it is unnecessary;
29809 objects that large will be quite rare, so it is okay to use `dup
29810 const16 SIZE trace' in those cases.
29812 Whatever we decide to do with `trace16', we should at least leave
29813 opcode 0x30 reserved, to remain compatible with the customer who
29818 File: gdb.info, Node: Trace File Format, Next: Copying, Prev: Operating System Information, Up: Top
29820 Appendix F Trace File Format
29821 ****************************
29823 The trace file comes in three parts: a header, a textual description
29824 section, and a trace frame section with binary data.
29826 The header has the form `\x7fTRACE0\n'. The first byte is `0x7f' so
29827 as to indicate that the file contains binary data, while the `0' is a
29828 version number that may have different values in the future.
29830 The description section consists of multiple lines of ASCII text
29831 separated by newline characters (`0xa'). The lines may include a
29832 variety of optional descriptive or context-setting information, such as
29833 tracepoint definitions or register set size. GDB will ignore any line
29834 that it does not recognize. An empty line marks the end of this
29837 The trace frame section consists of a number of consecutive frames.
29838 Each frame begins with a two-byte tracepoint number, followed by a
29839 four-byte size giving the amount of data in the frame. The data in the
29840 frame consists of a number of blocks, each introduced by a character
29841 indicating its type (at least register, memory, and trace state
29842 variable). The data in this section is raw binary, not a hexadecimal
29843 or other encoding; its endianness matches the target's endianness.
29846 Register block. The number and ordering of bytes matches that of a
29847 `g' packet in the remote protocol. Note that these are the actual
29848 bytes, in target order and GDB register order, not a hexadecimal
29851 `M ADDRESS LENGTH BYTES...'
29852 Memory block. This is a contiguous block of memory, at the 8-byte
29853 address ADDRESS, with a 2-byte length LENGTH, followed by LENGTH
29857 Trace state variable block. This records the 8-byte signed value
29858 VALUE of trace state variable numbered NUMBER.
29861 Future enhancements of the trace file format may include additional
29865 File: gdb.info, Node: Target Descriptions, Next: Operating System Information, Prev: Agent Expressions, Up: Top
29867 Appendix G Target Descriptions
29868 ******************************
29870 *Warning:* target descriptions are still under active development, and
29871 the contents and format may change between GDB releases. The format is
29872 expected to stabilize in the future.
29874 One of the challenges of using GDB to debug embedded systems is that
29875 there are so many minor variants of each processor architecture in use.
29876 It is common practice for vendors to start with a standard processor
29877 core -- ARM, PowerPC, or MIPS, for example -- and then make changes to
29878 adapt it to a particular market niche. Some architectures have
29879 hundreds of variants, available from dozens of vendors. This leads to
29880 a number of problems:
29882 * With so many different customized processors, it is difficult for
29883 the GDB maintainers to keep up with the changes.
29885 * Since individual variants may have short lifetimes or limited
29886 audiences, it may not be worthwhile to carry information about
29887 every variant in the GDB source tree.
29889 * When GDB does support the architecture of the embedded system at
29890 hand, the task of finding the correct architecture name to give the
29891 `set architecture' command can be error-prone.
29893 To address these problems, the GDB remote protocol allows a target
29894 system to not only identify itself to GDB, but to actually describe its
29895 own features. This lets GDB support processor variants it has never
29896 seen before -- to the extent that the descriptions are accurate, and
29897 that GDB understands them.
29899 GDB must be linked with the Expat library to support XML target
29900 descriptions. *Note Expat::.
29904 * Retrieving Descriptions:: How descriptions are fetched from a target.
29905 * Target Description Format:: The contents of a target description.
29906 * Predefined Target Types:: Standard types available for target
29908 * Standard Target Features:: Features GDB knows about.
29911 File: gdb.info, Node: Retrieving Descriptions, Next: Target Description Format, Up: Target Descriptions
29913 G.1 Retrieving Descriptions
29914 ===========================
29916 Target descriptions can be read from the target automatically, or
29917 specified by the user manually. The default behavior is to read the
29918 description from the target. GDB retrieves it via the remote protocol
29919 using `qXfer' requests (*note qXfer: General Query Packets.). The
29920 ANNEX in the `qXfer' packet will be `target.xml'. The contents of the
29921 `target.xml' annex are an XML document, of the form described in *note
29922 Target Description Format::.
29924 Alternatively, you can specify a file to read for the target
29925 description. If a file is set, the target will not be queried. The
29926 commands to specify a file are:
29928 `set tdesc filename PATH'
29929 Read the target description from PATH.
29931 `unset tdesc filename'
29932 Do not read the XML target description from a file. GDB will use
29933 the description supplied by the current target.
29935 `show tdesc filename'
29936 Show the filename to read for a target description, if any.
29939 File: gdb.info, Node: Target Description Format, Next: Predefined Target Types, Prev: Retrieving Descriptions, Up: Target Descriptions
29941 G.2 Target Description Format
29942 =============================
29944 A target description annex is an XML (http://www.w3.org/XML/) document
29945 which complies with the Document Type Definition provided in the GDB
29946 sources in `gdb/features/gdb-target.dtd'. This means you can use
29947 generally available tools like `xmllint' to check that your feature
29948 descriptions are well-formed and valid. However, to help people
29949 unfamiliar with XML write descriptions for their targets, we also
29950 describe the grammar here.
29952 Target descriptions can identify the architecture of the remote
29953 target and (for some architectures) provide information about custom
29954 register sets. They can also identify the OS ABI of the remote target.
29955 GDB can use this information to autoconfigure for your target, or to
29956 warn you if you connect to an unsupported target.
29958 Here is a simple target description:
29960 <target version="1.0">
29961 <architecture>i386:x86-64</architecture>
29964 This minimal description only says that the target uses the x86-64
29967 A target description has the following overall form, with [ ] marking
29968 optional elements and ... marking repeatable elements. The elements
29969 are explained further below.
29971 <?xml version="1.0"?>
29972 <!DOCTYPE target SYSTEM "gdb-target.dtd">
29973 <target version="1.0">
29980 The description is generally insensitive to whitespace and line breaks,
29981 under the usual common-sense rules. The XML version declaration and
29982 document type declaration can generally be omitted (GDB does not
29983 require them), but specifying them may be useful for XML validation
29984 tools. The `version' attribute for `<target>' may also be omitted, but
29985 we recommend including it; if future versions of GDB use an incompatible
29986 revision of `gdb-target.dtd', they will detect and report the version
29992 It can sometimes be valuable to split a target description up into
29993 several different annexes, either for organizational purposes, or to
29994 share files between different possible target descriptions. You can
29995 divide a description into multiple files by replacing any element of
29996 the target description with an inclusion directive of the form:
29998 <xi:include href="DOCUMENT"/>
30000 When GDB encounters an element of this form, it will retrieve the named
30001 XML DOCUMENT, and replace the inclusion directive with the contents of
30002 that document. If the current description was read using `qXfer', then
30003 so will be the included document; DOCUMENT will be interpreted as the
30004 name of an annex. If the current description was read from a file, GDB
30005 will look for DOCUMENT as a file in the same directory where it found
30006 the original description.
30011 An `<architecture>' element has this form:
30013 <architecture>ARCH</architecture>
30015 ARCH is one of the architectures from the set accepted by `set
30016 architecture' (*note Specifying a Debugging Target: Targets.).
30021 This optional field was introduced in GDB version 7.0. Previous
30022 versions of GDB ignore it.
30024 An `<osabi>' element has this form:
30026 <osabi>ABI-NAME</osabi>
30028 ABI-NAME is an OS ABI name from the same selection accepted by
30029 `set osabi' (*note Configuring the Current ABI: ABI.).
30031 G.2.4 Compatible Architecture
30032 -----------------------------
30034 This optional field was introduced in GDB version 7.0. Previous
30035 versions of GDB ignore it.
30037 A `<compatible>' element has this form:
30039 <compatible>ARCH</compatible>
30041 ARCH is one of the architectures from the set accepted by `set
30042 architecture' (*note Specifying a Debugging Target: Targets.).
30044 A `<compatible>' element is used to specify that the target is able
30045 to run binaries in some other than the main target architecture given
30046 by the `<architecture>' element. For example, on the Cell Broadband
30047 Engine, the main architecture is `powerpc:common' or
30048 `powerpc:common64', but the system is able to run binaries in the `spu'
30049 architecture as well. The way to describe this capability with
30050 `<compatible>' is as follows:
30052 <architecture>powerpc:common</architecture>
30053 <compatible>spu</compatible>
30058 Each `<feature>' describes some logical portion of the target system.
30059 Features are currently used to describe available CPU registers and the
30060 types of their contents. A `<feature>' element has this form:
30062 <feature name="NAME">
30067 Each feature's name should be unique within the description. The name
30068 of a feature does not matter unless GDB has some special knowledge of
30069 the contents of that feature; if it does, the feature should have its
30070 standard name. *Note Standard Target Features::.
30075 Any register's value is a collection of bits which GDB must interpret.
30076 The default interpretation is a two's complement integer, but other
30077 types can be requested by name in the register description. Some
30078 predefined types are provided by GDB (*note Predefined Target Types::),
30079 and the description can define additional composite types.
30081 Each type element must have an `id' attribute, which gives a unique
30082 (within the containing `<feature>') name to the type. Types must be
30083 defined before they are used.
30085 Some targets offer vector registers, which can be treated as arrays
30086 of scalar elements. These types are written as `<vector>' elements,
30087 specifying the array element type, TYPE, and the number of elements,
30090 <vector id="ID" type="TYPE" count="COUNT"/>
30092 If a register's value is usefully viewed in multiple ways, define it
30093 with a union type containing the useful representations. The `<union>'
30094 element contains one or more `<field>' elements, each of which has a
30098 <field name="NAME" type="TYPE"/>
30105 Each register is represented as an element with this form:
30110 [save-restore="SAVE-RESTORE"]
30114 The components are as follows:
30117 The register's name; it must be unique within the target
30121 The register's size, in bits.
30124 The register's number. If omitted, a register's number is one
30125 greater than that of the previous register (either in the current
30126 feature or in a preceeding feature); the first register in the
30127 target description defaults to zero. This register number is used
30128 to read or write the register; e.g. it is used in the remote `p'
30129 and `P' packets, and registers appear in the `g' and `G' packets
30130 in order of increasing register number.
30133 Whether the register should be preserved across inferior function
30134 calls; this must be either `yes' or `no'. The default is `yes',
30135 which is appropriate for most registers except for some system
30136 control registers; this is not related to the target's ABI.
30139 The type of the register. TYPE may be a predefined type, a type
30140 defined in the current feature, or one of the special types `int'
30141 and `float'. `int' is an integer type of the correct size for
30142 BITSIZE, and `float' is a floating point type (in the
30143 architecture's normal floating point format) of the correct size
30144 for BITSIZE. The default is `int'.
30147 The register group to which this register belongs. GROUP must be
30148 either `general', `float', or `vector'. If no GROUP is specified,
30149 GDB will not display the register in `info registers'.
30153 File: gdb.info, Node: Predefined Target Types, Next: Standard Target Features, Prev: Target Description Format, Up: Target Descriptions
30155 G.3 Predefined Target Types
30156 ===========================
30158 Type definitions in the self-description can build up composite types
30159 from basic building blocks, but can not define fundamental types.
30160 Instead, standard identifiers are provided by GDB for the fundamental
30161 types. The currently supported types are:
30168 Signed integer types holding the specified number of bits.
30175 Unsigned integer types holding the specified number of bits.
30179 Pointers to unspecified code and data. The program counter and
30180 any dedicated return address register may be marked as code
30181 pointers; printing a code pointer converts it into a symbolic
30182 address. The stack pointer and any dedicated address registers
30183 may be marked as data pointers.
30186 Single precision IEEE floating point.
30189 Double precision IEEE floating point.
30192 The 12-byte extended precision format used by ARM FPA registers.
30195 The 10-byte extended precision format used by x87 registers.
30198 32bit EFLAGS register used by x86.
30201 32bit MXCSR register used by x86.
30205 File: gdb.info, Node: Standard Target Features, Prev: Predefined Target Types, Up: Target Descriptions
30207 G.4 Standard Target Features
30208 ============================
30210 A target description must contain either no registers or all the
30211 target's registers. If the description contains no registers, then GDB
30212 will assume a default register layout, selected based on the
30213 architecture. If the description contains any registers, the default
30214 layout will not be used; the standard registers must be described in
30215 the target description, in such a way that GDB can recognize them.
30217 This is accomplished by giving specific names to feature elements
30218 which contain standard registers. GDB will look for features with
30219 those names and verify that they contain the expected registers; if any
30220 known feature is missing required registers, or if any required feature
30221 is missing, GDB will reject the target description. You can add
30222 additional registers to any of the standard features -- GDB will
30223 display them just as if they were added to an unrecognized feature.
30225 This section lists the known features and their expected contents.
30226 Sample XML documents for these features are included in the GDB source
30227 tree, in the directory `gdb/features'.
30229 Names recognized by GDB should include the name of the company or
30230 organization which selected the name, and the overall architecture to
30231 which the feature applies; so e.g. the feature containing ARM core
30232 registers is named `org.gnu.gdb.arm.core'.
30234 The names of registers are not case sensitive for the purpose of
30235 recognizing standard features, but GDB will only display registers
30236 using the capitalization used in the description.
30244 * PowerPC Features::
30247 File: gdb.info, Node: ARM Features, Next: i386 Features, Up: Standard Target Features
30252 The `org.gnu.gdb.arm.core' feature is required for ARM targets. It
30253 should contain registers `r0' through `r13', `sp', `lr', `pc', and
30256 The `org.gnu.gdb.arm.fpa' feature is optional. If present, it
30257 should contain registers `f0' through `f7' and `fps'.
30259 The `org.gnu.gdb.xscale.iwmmxt' feature is optional. If present, it
30260 should contain at least registers `wR0' through `wR15' and `wCGR0'
30261 through `wCGR3'. The `wCID', `wCon', `wCSSF', and `wCASF' registers
30264 The `org.gnu.gdb.arm.vfp' feature is optional. If present, it
30265 should contain at least registers `d0' through `d15'. If they are
30266 present, `d16' through `d31' should also be included. GDB will
30267 synthesize the single-precision registers from halves of the
30268 double-precision registers.
30270 The `org.gnu.gdb.arm.neon' feature is optional. It does not need to
30271 contain registers; it instructs GDB to display the VFP double-precision
30272 registers as vectors and to synthesize the quad-precision registers
30273 from pairs of double-precision registers. If this feature is present,
30274 `org.gnu.gdb.arm.vfp' must also be present and include 32
30275 double-precision registers.
30278 File: gdb.info, Node: i386 Features, Next: MIPS Features, Prev: ARM Features, Up: Standard Target Features
30280 G.4.2 i386 Features
30281 -------------------
30283 The `org.gnu.gdb.i386.core' feature is required for i386/amd64 targets.
30284 It should describe the following registers:
30286 - `eax' through `edi' plus `eip' for i386
30288 - `rax' through `r15' plus `rip' for amd64
30290 - `eflags', `cs', `ss', `ds', `es', `fs', `gs'
30292 - `st0' through `st7'
30294 - `fctrl', `fstat', `ftag', `fiseg', `fioff', `foseg', `fooff' and
30297 The register sets may be different, depending on the target.
30299 The `org.gnu.gdb.i386.sse' feature is required. It should describe
30302 - `xmm0' through `xmm7' for i386
30304 - `xmm0' through `xmm15' for amd64
30308 The `org.gnu.gdb.i386.linux' feature is optional. It should
30309 describe a single register, `orig_eax'.
30312 File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: i386 Features, Up: Standard Target Features
30314 G.4.3 MIPS Features
30315 -------------------
30317 The `org.gnu.gdb.mips.cpu' feature is required for MIPS targets. It
30318 should contain registers `r0' through `r31', `lo', `hi', and `pc'.
30319 They may be 32-bit or 64-bit depending on the target.
30321 The `org.gnu.gdb.mips.cp0' feature is also required. It should
30322 contain at least the `status', `badvaddr', and `cause' registers. They
30323 may be 32-bit or 64-bit depending on the target.
30325 The `org.gnu.gdb.mips.fpu' feature is currently required, though it
30326 may be optional in a future version of GDB. It should contain
30327 registers `f0' through `f31', `fcsr', and `fir'. They may be 32-bit or
30328 64-bit depending on the target.
30330 The `org.gnu.gdb.mips.linux' feature is optional. It should contain
30331 a single register, `restart', which is used by the Linux kernel to
30332 control restartable syscalls.
30335 File: gdb.info, Node: M68K Features, Next: PowerPC Features, Prev: MIPS Features, Up: Standard Target Features
30337 G.4.4 M68K Features
30338 -------------------
30340 ``org.gnu.gdb.m68k.core''
30341 ``org.gnu.gdb.coldfire.core''
30342 ``org.gnu.gdb.fido.core''
30343 One of those features must be always present. The feature that is
30344 present determines which flavor of m68k is used. The feature that
30345 is present should contain registers `d0' through `d7', `a0'
30346 through `a5', `fp', `sp', `ps' and `pc'.
30348 ``org.gnu.gdb.coldfire.fp''
30349 This feature is optional. If present, it should contain registers
30350 `fp0' through `fp7', `fpcontrol', `fpstatus' and `fpiaddr'.
30353 File: gdb.info, Node: PowerPC Features, Prev: M68K Features, Up: Standard Target Features
30355 G.4.5 PowerPC Features
30356 ----------------------
30358 The `org.gnu.gdb.power.core' feature is required for PowerPC targets.
30359 It should contain registers `r0' through `r31', `pc', `msr', `cr',
30360 `lr', `ctr', and `xer'. They may be 32-bit or 64-bit depending on the
30363 The `org.gnu.gdb.power.fpu' feature is optional. It should contain
30364 registers `f0' through `f31' and `fpscr'.
30366 The `org.gnu.gdb.power.altivec' feature is optional. It should
30367 contain registers `vr0' through `vr31', `vscr', and `vrsave'.
30369 The `org.gnu.gdb.power.vsx' feature is optional. It should contain
30370 registers `vs0h' through `vs31h'. GDB will combine these registers
30371 with the floating point registers (`f0' through `f31') and the altivec
30372 registers (`vr0' through `vr31') to present the 128-bit wide registers
30373 `vs0' through `vs63', the set of vector registers for POWER7.
30375 The `org.gnu.gdb.power.spe' feature is optional. It should contain
30376 registers `ev0h' through `ev31h', `acc', and `spefscr'. SPE targets
30377 should provide 32-bit registers in `org.gnu.gdb.power.core' and provide
30378 the upper halves in `ev0h' through `ev31h'. GDB will combine these to
30379 present registers `ev0' through `ev31' to the user.
30382 File: gdb.info, Node: Operating System Information, Next: Trace File Format, Prev: Target Descriptions, Up: Top
30384 Appendix H Operating System Information
30385 ***************************************
30391 Users of GDB often wish to obtain information about the state of the
30392 operating system running on the target--for example the list of
30393 processes, or the list of open files. This section describes the
30394 mechanism that makes it possible. This mechanism is similar to the
30395 target features mechanism (*note Target Descriptions::), but focuses on
30396 a different aspect of target.
30398 Operating system information is retrived from the target via the
30399 remote protocol, using `qXfer' requests (*note qXfer osdata read::).
30400 The object name in the request should be `osdata', and the ANNEX
30401 identifies the data to be fetched.
30404 File: gdb.info, Node: Process list, Up: Operating System Information
30409 When requesting the process list, the ANNEX field in the `qXfer'
30410 request should be `processes'. The returned data is an XML document.
30411 The formal syntax of this document is defined in
30412 `gdb/features/osdata.dtd'.
30414 An example document is:
30416 <?xml version="1.0"?>
30417 <!DOCTYPE target SYSTEM "osdata.dtd">
30418 <osdata type="processes">
30420 <column name="pid">1</column>
30421 <column name="user">root</column>
30422 <column name="command">/sbin/init</column>
30423 <column name="cores">1,2,3</column>
30427 Each item should include a column whose name is `pid'. The value of
30428 that column should identify the process on the target. The `user' and
30429 `command' columns are optional, and will be displayed by GDB. The
30430 `cores' column, if present, should contain a comma-separated list of
30431 cores that this process is running on. Target may provide additional
30432 columns, which GDB currently ignores.
30435 File: gdb.info, Node: Copying, Next: GNU Free Documentation License, Prev: Trace File Format, Up: Top
30437 Appendix I GNU GENERAL PUBLIC LICENSE
30438 *************************************
30440 Version 3, 29 June 2007
30442 Copyright (C) 2007 Free Software Foundation, Inc. `http://fsf.org/'
30444 Everyone is permitted to copy and distribute verbatim copies of this
30445 license document, but changing it is not allowed.
30450 The GNU General Public License is a free, copyleft license for software
30451 and other kinds of works.
30453 The licenses for most software and other practical works are designed
30454 to take away your freedom to share and change the works. By contrast,
30455 the GNU General Public License is intended to guarantee your freedom to
30456 share and change all versions of a program--to make sure it remains
30457 free software for all its users. We, the Free Software Foundation, use
30458 the GNU General Public License for most of our software; it applies
30459 also to any other work released this way by its authors. You can apply
30460 it to your programs, too.
30462 When we speak of free software, we are referring to freedom, not
30463 price. Our General Public Licenses are designed to make sure that you
30464 have the freedom to distribute copies of free software (and charge for
30465 them if you wish), that you receive source code or can get it if you
30466 want it, that you can change the software or use pieces of it in new
30467 free programs, and that you know you can do these things.
30469 To protect your rights, we need to prevent others from denying you
30470 these rights or asking you to surrender the rights. Therefore, you
30471 have certain responsibilities if you distribute copies of the software,
30472 or if you modify it: responsibilities to respect the freedom of others.
30474 For example, if you distribute copies of such a program, whether
30475 gratis or for a fee, you must pass on to the recipients the same
30476 freedoms that you received. You must make sure that they, too, receive
30477 or can get the source code. And you must show them these terms so they
30480 Developers that use the GNU GPL protect your rights with two steps:
30481 (1) assert copyright on the software, and (2) offer you this License
30482 giving you legal permission to copy, distribute and/or modify it.
30484 For the developers' and authors' protection, the GPL clearly explains
30485 that there is no warranty for this free software. For both users' and
30486 authors' sake, the GPL requires that modified versions be marked as
30487 changed, so that their problems will not be attributed erroneously to
30488 authors of previous versions.
30490 Some devices are designed to deny users access to install or run
30491 modified versions of the software inside them, although the
30492 manufacturer can do so. This is fundamentally incompatible with the
30493 aim of protecting users' freedom to change the software. The
30494 systematic pattern of such abuse occurs in the area of products for
30495 individuals to use, which is precisely where it is most unacceptable.
30496 Therefore, we have designed this version of the GPL to prohibit the
30497 practice for those products. If such problems arise substantially in
30498 other domains, we stand ready to extend this provision to those domains
30499 in future versions of the GPL, as needed to protect the freedom of
30502 Finally, every program is threatened constantly by software patents.
30503 States should not allow patents to restrict development and use of
30504 software on general-purpose computers, but in those that do, we wish to
30505 avoid the special danger that patents applied to a free program could
30506 make it effectively proprietary. To prevent this, the GPL assures that
30507 patents cannot be used to render the program non-free.
30509 The precise terms and conditions for copying, distribution and
30510 modification follow.
30512 TERMS AND CONDITIONS
30513 ====================
30517 "This License" refers to version 3 of the GNU General Public
30520 "Copyright" also means copyright-like laws that apply to other
30521 kinds of works, such as semiconductor masks.
30523 "The Program" refers to any copyrightable work licensed under this
30524 License. Each licensee is addressed as "you". "Licensees" and
30525 "recipients" may be individuals or organizations.
30527 To "modify" a work means to copy from or adapt all or part of the
30528 work in a fashion requiring copyright permission, other than the
30529 making of an exact copy. The resulting work is called a "modified
30530 version" of the earlier work or a work "based on" the earlier work.
30532 A "covered work" means either the unmodified Program or a work
30533 based on the Program.
30535 To "propagate" a work means to do anything with it that, without
30536 permission, would make you directly or secondarily liable for
30537 infringement under applicable copyright law, except executing it
30538 on a computer or modifying a private copy. Propagation includes
30539 copying, distribution (with or without modification), making
30540 available to the public, and in some countries other activities as
30543 To "convey" a work means any kind of propagation that enables other
30544 parties to make or receive copies. Mere interaction with a user
30545 through a computer network, with no transfer of a copy, is not
30548 An interactive user interface displays "Appropriate Legal Notices"
30549 to the extent that it includes a convenient and prominently visible
30550 feature that (1) displays an appropriate copyright notice, and (2)
30551 tells the user that there is no warranty for the work (except to
30552 the extent that warranties are provided), that licensees may
30553 convey the work under this License, and how to view a copy of this
30554 License. If the interface presents a list of user commands or
30555 options, such as a menu, a prominent item in the list meets this
30560 The "source code" for a work means the preferred form of the work
30561 for making modifications to it. "Object code" means any
30562 non-source form of a work.
30564 A "Standard Interface" means an interface that either is an
30565 official standard defined by a recognized standards body, or, in
30566 the case of interfaces specified for a particular programming
30567 language, one that is widely used among developers working in that
30570 The "System Libraries" of an executable work include anything,
30571 other than the work as a whole, that (a) is included in the normal
30572 form of packaging a Major Component, but which is not part of that
30573 Major Component, and (b) serves only to enable use of the work
30574 with that Major Component, or to implement a Standard Interface
30575 for which an implementation is available to the public in source
30576 code form. A "Major Component", in this context, means a major
30577 essential component (kernel, window system, and so on) of the
30578 specific operating system (if any) on which the executable work
30579 runs, or a compiler used to produce the work, or an object code
30580 interpreter used to run it.
30582 The "Corresponding Source" for a work in object code form means all
30583 the source code needed to generate, install, and (for an executable
30584 work) run the object code and to modify the work, including
30585 scripts to control those activities. However, it does not include
30586 the work's System Libraries, or general-purpose tools or generally
30587 available free programs which are used unmodified in performing
30588 those activities but which are not part of the work. For example,
30589 Corresponding Source includes interface definition files
30590 associated with source files for the work, and the source code for
30591 shared libraries and dynamically linked subprograms that the work
30592 is specifically designed to require, such as by intimate data
30593 communication or control flow between those subprograms and other
30596 The Corresponding Source need not include anything that users can
30597 regenerate automatically from other parts of the Corresponding
30600 The Corresponding Source for a work in source code form is that
30603 2. Basic Permissions.
30605 All rights granted under this License are granted for the term of
30606 copyright on the Program, and are irrevocable provided the stated
30607 conditions are met. This License explicitly affirms your unlimited
30608 permission to run the unmodified Program. The output from running
30609 a covered work is covered by this License only if the output,
30610 given its content, constitutes a covered work. This License
30611 acknowledges your rights of fair use or other equivalent, as
30612 provided by copyright law.
30614 You may make, run and propagate covered works that you do not
30615 convey, without conditions so long as your license otherwise
30616 remains in force. You may convey covered works to others for the
30617 sole purpose of having them make modifications exclusively for
30618 you, or provide you with facilities for running those works,
30619 provided that you comply with the terms of this License in
30620 conveying all material for which you do not control copyright.
30621 Those thus making or running the covered works for you must do so
30622 exclusively on your behalf, under your direction and control, on
30623 terms that prohibit them from making any copies of your
30624 copyrighted material outside their relationship with you.
30626 Conveying under any other circumstances is permitted solely under
30627 the conditions stated below. Sublicensing is not allowed; section
30628 10 makes it unnecessary.
30630 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
30632 No covered work shall be deemed part of an effective technological
30633 measure under any applicable law fulfilling obligations under
30634 article 11 of the WIPO copyright treaty adopted on 20 December
30635 1996, or similar laws prohibiting or restricting circumvention of
30638 When you convey a covered work, you waive any legal power to forbid
30639 circumvention of technological measures to the extent such
30640 circumvention is effected by exercising rights under this License
30641 with respect to the covered work, and you disclaim any intention
30642 to limit operation or modification of the work as a means of
30643 enforcing, against the work's users, your or third parties' legal
30644 rights to forbid circumvention of technological measures.
30646 4. Conveying Verbatim Copies.
30648 You may convey verbatim copies of the Program's source code as you
30649 receive it, in any medium, provided that you conspicuously and
30650 appropriately publish on each copy an appropriate copyright notice;
30651 keep intact all notices stating that this License and any
30652 non-permissive terms added in accord with section 7 apply to the
30653 code; keep intact all notices of the absence of any warranty; and
30654 give all recipients a copy of this License along with the Program.
30656 You may charge any price or no price for each copy that you convey,
30657 and you may offer support or warranty protection for a fee.
30659 5. Conveying Modified Source Versions.
30661 You may convey a work based on the Program, or the modifications to
30662 produce it from the Program, in the form of source code under the
30663 terms of section 4, provided that you also meet all of these
30666 a. The work must carry prominent notices stating that you
30667 modified it, and giving a relevant date.
30669 b. The work must carry prominent notices stating that it is
30670 released under this License and any conditions added under
30671 section 7. This requirement modifies the requirement in
30672 section 4 to "keep intact all notices".
30674 c. You must license the entire work, as a whole, under this
30675 License to anyone who comes into possession of a copy. This
30676 License will therefore apply, along with any applicable
30677 section 7 additional terms, to the whole of the work, and all
30678 its parts, regardless of how they are packaged. This License
30679 gives no permission to license the work in any other way, but
30680 it does not invalidate such permission if you have separately
30683 d. If the work has interactive user interfaces, each must display
30684 Appropriate Legal Notices; however, if the Program has
30685 interactive interfaces that do not display Appropriate Legal
30686 Notices, your work need not make them do so.
30688 A compilation of a covered work with other separate and independent
30689 works, which are not by their nature extensions of the covered
30690 work, and which are not combined with it such as to form a larger
30691 program, in or on a volume of a storage or distribution medium, is
30692 called an "aggregate" if the compilation and its resulting
30693 copyright are not used to limit the access or legal rights of the
30694 compilation's users beyond what the individual works permit.
30695 Inclusion of a covered work in an aggregate does not cause this
30696 License to apply to the other parts of the aggregate.
30698 6. Conveying Non-Source Forms.
30700 You may convey a covered work in object code form under the terms
30701 of sections 4 and 5, provided that you also convey the
30702 machine-readable Corresponding Source under the terms of this
30703 License, in one of these ways:
30705 a. Convey the object code in, or embodied in, a physical product
30706 (including a physical distribution medium), accompanied by the
30707 Corresponding Source fixed on a durable physical medium
30708 customarily used for software interchange.
30710 b. Convey the object code in, or embodied in, a physical product
30711 (including a physical distribution medium), accompanied by a
30712 written offer, valid for at least three years and valid for
30713 as long as you offer spare parts or customer support for that
30714 product model, to give anyone who possesses the object code
30715 either (1) a copy of the Corresponding Source for all the
30716 software in the product that is covered by this License, on a
30717 durable physical medium customarily used for software
30718 interchange, for a price no more than your reasonable cost of
30719 physically performing this conveying of source, or (2) access
30720 to copy the Corresponding Source from a network server at no
30723 c. Convey individual copies of the object code with a copy of
30724 the written offer to provide the Corresponding Source. This
30725 alternative is allowed only occasionally and noncommercially,
30726 and only if you received the object code with such an offer,
30727 in accord with subsection 6b.
30729 d. Convey the object code by offering access from a designated
30730 place (gratis or for a charge), and offer equivalent access
30731 to the Corresponding Source in the same way through the same
30732 place at no further charge. You need not require recipients
30733 to copy the Corresponding Source along with the object code.
30734 If the place to copy the object code is a network server, the
30735 Corresponding Source may be on a different server (operated
30736 by you or a third party) that supports equivalent copying
30737 facilities, provided you maintain clear directions next to
30738 the object code saying where to find the Corresponding Source.
30739 Regardless of what server hosts the Corresponding Source, you
30740 remain obligated to ensure that it is available for as long
30741 as needed to satisfy these requirements.
30743 e. Convey the object code using peer-to-peer transmission,
30744 provided you inform other peers where the object code and
30745 Corresponding Source of the work are being offered to the
30746 general public at no charge under subsection 6d.
30749 A separable portion of the object code, whose source code is
30750 excluded from the Corresponding Source as a System Library, need
30751 not be included in conveying the object code work.
30753 A "User Product" is either (1) a "consumer product", which means
30754 any tangible personal property which is normally used for personal,
30755 family, or household purposes, or (2) anything designed or sold for
30756 incorporation into a dwelling. In determining whether a product
30757 is a consumer product, doubtful cases shall be resolved in favor of
30758 coverage. For a particular product received by a particular user,
30759 "normally used" refers to a typical or common use of that class of
30760 product, regardless of the status of the particular user or of the
30761 way in which the particular user actually uses, or expects or is
30762 expected to use, the product. A product is a consumer product
30763 regardless of whether the product has substantial commercial,
30764 industrial or non-consumer uses, unless such uses represent the
30765 only significant mode of use of the product.
30767 "Installation Information" for a User Product means any methods,
30768 procedures, authorization keys, or other information required to
30769 install and execute modified versions of a covered work in that
30770 User Product from a modified version of its Corresponding Source.
30771 The information must suffice to ensure that the continued
30772 functioning of the modified object code is in no case prevented or
30773 interfered with solely because modification has been made.
30775 If you convey an object code work under this section in, or with,
30776 or specifically for use in, a User Product, and the conveying
30777 occurs as part of a transaction in which the right of possession
30778 and use of the User Product is transferred to the recipient in
30779 perpetuity or for a fixed term (regardless of how the transaction
30780 is characterized), the Corresponding Source conveyed under this
30781 section must be accompanied by the Installation Information. But
30782 this requirement does not apply if neither you nor any third party
30783 retains the ability to install modified object code on the User
30784 Product (for example, the work has been installed in ROM).
30786 The requirement to provide Installation Information does not
30787 include a requirement to continue to provide support service,
30788 warranty, or updates for a work that has been modified or
30789 installed by the recipient, or for the User Product in which it
30790 has been modified or installed. Access to a network may be denied
30791 when the modification itself materially and adversely affects the
30792 operation of the network or violates the rules and protocols for
30793 communication across the network.
30795 Corresponding Source conveyed, and Installation Information
30796 provided, in accord with this section must be in a format that is
30797 publicly documented (and with an implementation available to the
30798 public in source code form), and must require no special password
30799 or key for unpacking, reading or copying.
30801 7. Additional Terms.
30803 "Additional permissions" are terms that supplement the terms of
30804 this License by making exceptions from one or more of its
30805 conditions. Additional permissions that are applicable to the
30806 entire Program shall be treated as though they were included in
30807 this License, to the extent that they are valid under applicable
30808 law. If additional permissions apply only to part of the Program,
30809 that part may be used separately under those permissions, but the
30810 entire Program remains governed by this License without regard to
30811 the additional permissions.
30813 When you convey a copy of a covered work, you may at your option
30814 remove any additional permissions from that copy, or from any part
30815 of it. (Additional permissions may be written to require their own
30816 removal in certain cases when you modify the work.) You may place
30817 additional permissions on material, added by you to a covered work,
30818 for which you have or can give appropriate copyright permission.
30820 Notwithstanding any other provision of this License, for material
30821 you add to a covered work, you may (if authorized by the copyright
30822 holders of that material) supplement the terms of this License
30825 a. Disclaiming warranty or limiting liability differently from
30826 the terms of sections 15 and 16 of this License; or
30828 b. Requiring preservation of specified reasonable legal notices
30829 or author attributions in that material or in the Appropriate
30830 Legal Notices displayed by works containing it; or
30832 c. Prohibiting misrepresentation of the origin of that material,
30833 or requiring that modified versions of such material be
30834 marked in reasonable ways as different from the original
30837 d. Limiting the use for publicity purposes of names of licensors
30838 or authors of the material; or
30840 e. Declining to grant rights under trademark law for use of some
30841 trade names, trademarks, or service marks; or
30843 f. Requiring indemnification of licensors and authors of that
30844 material by anyone who conveys the material (or modified
30845 versions of it) with contractual assumptions of liability to
30846 the recipient, for any liability that these contractual
30847 assumptions directly impose on those licensors and authors.
30849 All other non-permissive additional terms are considered "further
30850 restrictions" within the meaning of section 10. If the Program as
30851 you received it, or any part of it, contains a notice stating that
30852 it is governed by this License along with a term that is a further
30853 restriction, you may remove that term. If a license document
30854 contains a further restriction but permits relicensing or
30855 conveying under this License, you may add to a covered work
30856 material governed by the terms of that license document, provided
30857 that the further restriction does not survive such relicensing or
30860 If you add terms to a covered work in accord with this section, you
30861 must place, in the relevant source files, a statement of the
30862 additional terms that apply to those files, or a notice indicating
30863 where to find the applicable terms.
30865 Additional terms, permissive or non-permissive, may be stated in
30866 the form of a separately written license, or stated as exceptions;
30867 the above requirements apply either way.
30871 You may not propagate or modify a covered work except as expressly
30872 provided under this License. Any attempt otherwise to propagate or
30873 modify it is void, and will automatically terminate your rights
30874 under this License (including any patent licenses granted under
30875 the third paragraph of section 11).
30877 However, if you cease all violation of this License, then your
30878 license from a particular copyright holder is reinstated (a)
30879 provisionally, unless and until the copyright holder explicitly
30880 and finally terminates your license, and (b) permanently, if the
30881 copyright holder fails to notify you of the violation by some
30882 reasonable means prior to 60 days after the cessation.
30884 Moreover, your license from a particular copyright holder is
30885 reinstated permanently if the copyright holder notifies you of the
30886 violation by some reasonable means, this is the first time you have
30887 received notice of violation of this License (for any work) from
30888 that copyright holder, and you cure the violation prior to 30 days
30889 after your receipt of the notice.
30891 Termination of your rights under this section does not terminate
30892 the licenses of parties who have received copies or rights from
30893 you under this License. If your rights have been terminated and
30894 not permanently reinstated, you do not qualify to receive new
30895 licenses for the same material under section 10.
30897 9. Acceptance Not Required for Having Copies.
30899 You are not required to accept this License in order to receive or
30900 run a copy of the Program. Ancillary propagation of a covered work
30901 occurring solely as a consequence of using peer-to-peer
30902 transmission to receive a copy likewise does not require
30903 acceptance. However, nothing other than this License grants you
30904 permission to propagate or modify any covered work. These actions
30905 infringe copyright if you do not accept this License. Therefore,
30906 by modifying or propagating a covered work, you indicate your
30907 acceptance of this License to do so.
30909 10. Automatic Licensing of Downstream Recipients.
30911 Each time you convey a covered work, the recipient automatically
30912 receives a license from the original licensors, to run, modify and
30913 propagate that work, subject to this License. You are not
30914 responsible for enforcing compliance by third parties with this
30917 An "entity transaction" is a transaction transferring control of an
30918 organization, or substantially all assets of one, or subdividing an
30919 organization, or merging organizations. If propagation of a
30920 covered work results from an entity transaction, each party to that
30921 transaction who receives a copy of the work also receives whatever
30922 licenses to the work the party's predecessor in interest had or
30923 could give under the previous paragraph, plus a right to
30924 possession of the Corresponding Source of the work from the
30925 predecessor in interest, if the predecessor has it or can get it
30926 with reasonable efforts.
30928 You may not impose any further restrictions on the exercise of the
30929 rights granted or affirmed under this License. For example, you
30930 may not impose a license fee, royalty, or other charge for
30931 exercise of rights granted under this License, and you may not
30932 initiate litigation (including a cross-claim or counterclaim in a
30933 lawsuit) alleging that any patent claim is infringed by making,
30934 using, selling, offering for sale, or importing the Program or any
30939 A "contributor" is a copyright holder who authorizes use under this
30940 License of the Program or a work on which the Program is based.
30941 The work thus licensed is called the contributor's "contributor
30944 A contributor's "essential patent claims" are all patent claims
30945 owned or controlled by the contributor, whether already acquired or
30946 hereafter acquired, that would be infringed by some manner,
30947 permitted by this License, of making, using, or selling its
30948 contributor version, but do not include claims that would be
30949 infringed only as a consequence of further modification of the
30950 contributor version. For purposes of this definition, "control"
30951 includes the right to grant patent sublicenses in a manner
30952 consistent with the requirements of this License.
30954 Each contributor grants you a non-exclusive, worldwide,
30955 royalty-free patent license under the contributor's essential
30956 patent claims, to make, use, sell, offer for sale, import and
30957 otherwise run, modify and propagate the contents of its
30958 contributor version.
30960 In the following three paragraphs, a "patent license" is any
30961 express agreement or commitment, however denominated, not to
30962 enforce a patent (such as an express permission to practice a
30963 patent or covenant not to sue for patent infringement). To
30964 "grant" such a patent license to a party means to make such an
30965 agreement or commitment not to enforce a patent against the party.
30967 If you convey a covered work, knowingly relying on a patent
30968 license, and the Corresponding Source of the work is not available
30969 for anyone to copy, free of charge and under the terms of this
30970 License, through a publicly available network server or other
30971 readily accessible means, then you must either (1) cause the
30972 Corresponding Source to be so available, or (2) arrange to deprive
30973 yourself of the benefit of the patent license for this particular
30974 work, or (3) arrange, in a manner consistent with the requirements
30975 of this License, to extend the patent license to downstream
30976 recipients. "Knowingly relying" means you have actual knowledge
30977 that, but for the patent license, your conveying the covered work
30978 in a country, or your recipient's use of the covered work in a
30979 country, would infringe one or more identifiable patents in that
30980 country that you have reason to believe are valid.
30982 If, pursuant to or in connection with a single transaction or
30983 arrangement, you convey, or propagate by procuring conveyance of, a
30984 covered work, and grant a patent license to some of the parties
30985 receiving the covered work authorizing them to use, propagate,
30986 modify or convey a specific copy of the covered work, then the
30987 patent license you grant is automatically extended to all
30988 recipients of the covered work and works based on it.
30990 A patent license is "discriminatory" if it does not include within
30991 the scope of its coverage, prohibits the exercise of, or is
30992 conditioned on the non-exercise of one or more of the rights that
30993 are specifically granted under this License. You may not convey a
30994 covered work if you are a party to an arrangement with a third
30995 party that is in the business of distributing software, under
30996 which you make payment to the third party based on the extent of
30997 your activity of conveying the work, and under which the third
30998 party grants, to any of the parties who would receive the covered
30999 work from you, a discriminatory patent license (a) in connection
31000 with copies of the covered work conveyed by you (or copies made
31001 from those copies), or (b) primarily for and in connection with
31002 specific products or compilations that contain the covered work,
31003 unless you entered into that arrangement, or that patent license
31004 was granted, prior to 28 March 2007.
31006 Nothing in this License shall be construed as excluding or limiting
31007 any implied license or other defenses to infringement that may
31008 otherwise be available to you under applicable patent law.
31010 12. No Surrender of Others' Freedom.
31012 If conditions are imposed on you (whether by court order,
31013 agreement or otherwise) that contradict the conditions of this
31014 License, they do not excuse you from the conditions of this
31015 License. If you cannot convey a covered work so as to satisfy
31016 simultaneously your obligations under this License and any other
31017 pertinent obligations, then as a consequence you may not convey it
31018 at all. For example, if you agree to terms that obligate you to
31019 collect a royalty for further conveying from those to whom you
31020 convey the Program, the only way you could satisfy both those
31021 terms and this License would be to refrain entirely from conveying
31024 13. Use with the GNU Affero General Public License.
31026 Notwithstanding any other provision of this License, you have
31027 permission to link or combine any covered work with a work licensed
31028 under version 3 of the GNU Affero General Public License into a
31029 single combined work, and to convey the resulting work. The terms
31030 of this License will continue to apply to the part which is the
31031 covered work, but the special requirements of the GNU Affero
31032 General Public License, section 13, concerning interaction through
31033 a network will apply to the combination as such.
31035 14. Revised Versions of this License.
31037 The Free Software Foundation may publish revised and/or new
31038 versions of the GNU General Public License from time to time.
31039 Such new versions will be similar in spirit to the present
31040 version, but may differ in detail to address new problems or
31043 Each version is given a distinguishing version number. If the
31044 Program specifies that a certain numbered version of the GNU
31045 General Public License "or any later version" applies to it, you
31046 have the option of following the terms and conditions either of
31047 that numbered version or of any later version published by the
31048 Free Software Foundation. If the Program does not specify a
31049 version number of the GNU General Public License, you may choose
31050 any version ever published by the Free Software Foundation.
31052 If the Program specifies that a proxy can decide which future
31053 versions of the GNU General Public License can be used, that
31054 proxy's public statement of acceptance of a version permanently
31055 authorizes you to choose that version for the Program.
31057 Later license versions may give you additional or different
31058 permissions. However, no additional obligations are imposed on any
31059 author or copyright holder as a result of your choosing to follow a
31062 15. Disclaimer of Warranty.
31064 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
31065 APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
31066 COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS"
31067 WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
31068 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
31069 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE
31070 RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
31071 SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
31072 NECESSARY SERVICING, REPAIR OR CORRECTION.
31074 16. Limitation of Liability.
31076 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
31077 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES
31078 AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
31079 FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
31080 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
31081 THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
31082 BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
31083 PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
31084 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
31085 THE POSSIBILITY OF SUCH DAMAGES.
31087 17. Interpretation of Sections 15 and 16.
31089 If the disclaimer of warranty and limitation of liability provided
31090 above cannot be given local legal effect according to their terms,
31091 reviewing courts shall apply local law that most closely
31092 approximates an absolute waiver of all civil liability in
31093 connection with the Program, unless a warranty or assumption of
31094 liability accompanies a copy of the Program in return for a fee.
31097 END OF TERMS AND CONDITIONS
31098 ===========================
31100 How to Apply These Terms to Your New Programs
31101 =============================================
31103 If you develop a new program, and you want it to be of the greatest
31104 possible use to the public, the best way to achieve this is to make it
31105 free software which everyone can redistribute and change under these
31108 To do so, attach the following notices to the program. It is safest
31109 to attach them to the start of each source file to most effectively
31110 state the exclusion of warranty; and each file should have at least the
31111 "copyright" line and a pointer to where the full notice is found.
31113 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
31114 Copyright (C) YEAR NAME OF AUTHOR
31116 This program is free software: you can redistribute it and/or modify
31117 it under the terms of the GNU General Public License as published by
31118 the Free Software Foundation, either version 3 of the License, or (at
31119 your option) any later version.
31121 This program is distributed in the hope that it will be useful, but
31122 WITHOUT ANY WARRANTY; without even the implied warranty of
31123 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
31124 General Public License for more details.
31126 You should have received a copy of the GNU General Public License
31127 along with this program. If not, see `http://www.gnu.org/licenses/'.
31129 Also add information on how to contact you by electronic and paper
31132 If the program does terminal interaction, make it output a short
31133 notice like this when it starts in an interactive mode:
31135 PROGRAM Copyright (C) YEAR NAME OF AUTHOR
31136 This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
31137 This is free software, and you are welcome to redistribute it
31138 under certain conditions; type `show c' for details.
31140 The hypothetical commands `show w' and `show c' should show the
31141 appropriate parts of the General Public License. Of course, your
31142 program's commands might be different; for a GUI interface, you would
31143 use an "about box".
31145 You should also get your employer (if you work as a programmer) or
31146 school, if any, to sign a "copyright disclaimer" for the program, if
31147 necessary. For more information on this, and how to apply and follow
31148 the GNU GPL, see `http://www.gnu.org/licenses/'.
31150 The GNU General Public License does not permit incorporating your
31151 program into proprietary programs. If your program is a subroutine
31152 library, you may consider it more useful to permit linking proprietary
31153 applications with the library. If this is what you want to do, use the
31154 GNU Lesser General Public License instead of this License. But first,
31155 please read `http://www.gnu.org/philosophy/why-not-lgpl.html'.
31158 File: gdb.info, Node: GNU Free Documentation License, Next: Index, Prev: Copying, Up: Top
31160 Appendix J GNU Free Documentation License
31161 *****************************************
31163 Version 1.2, November 2002
31165 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
31166 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
31168 Everyone is permitted to copy and distribute verbatim copies
31169 of this license document, but changing it is not allowed.
31173 The purpose of this License is to make a manual, textbook, or other
31174 functional and useful document "free" in the sense of freedom: to
31175 assure everyone the effective freedom to copy and redistribute it,
31176 with or without modifying it, either commercially or
31177 noncommercially. Secondarily, this License preserves for the
31178 author and publisher a way to get credit for their work, while not
31179 being considered responsible for modifications made by others.
31181 This License is a kind of "copyleft", which means that derivative
31182 works of the document must themselves be free in the same sense.
31183 It complements the GNU General Public License, which is a copyleft
31184 license designed for free software.
31186 We have designed this License in order to use it for manuals for
31187 free software, because free software needs free documentation: a
31188 free program should come with manuals providing the same freedoms
31189 that the software does. But this License is not limited to
31190 software manuals; it can be used for any textual work, regardless
31191 of subject matter or whether it is published as a printed book.
31192 We recommend this License principally for works whose purpose is
31193 instruction or reference.
31195 1. APPLICABILITY AND DEFINITIONS
31197 This License applies to any manual or other work, in any medium,
31198 that contains a notice placed by the copyright holder saying it
31199 can be distributed under the terms of this License. Such a notice
31200 grants a world-wide, royalty-free license, unlimited in duration,
31201 to use that work under the conditions stated herein. The
31202 "Document", below, refers to any such manual or work. Any member
31203 of the public is a licensee, and is addressed as "you". You
31204 accept the license if you copy, modify or distribute the work in a
31205 way requiring permission under copyright law.
31207 A "Modified Version" of the Document means any work containing the
31208 Document or a portion of it, either copied verbatim, or with
31209 modifications and/or translated into another language.
31211 A "Secondary Section" is a named appendix or a front-matter section
31212 of the Document that deals exclusively with the relationship of the
31213 publishers or authors of the Document to the Document's overall
31214 subject (or to related matters) and contains nothing that could
31215 fall directly within that overall subject. (Thus, if the Document
31216 is in part a textbook of mathematics, a Secondary Section may not
31217 explain any mathematics.) The relationship could be a matter of
31218 historical connection with the subject or with related matters, or
31219 of legal, commercial, philosophical, ethical or political position
31222 The "Invariant Sections" are certain Secondary Sections whose
31223 titles are designated, as being those of Invariant Sections, in
31224 the notice that says that the Document is released under this
31225 License. If a section does not fit the above definition of
31226 Secondary then it is not allowed to be designated as Invariant.
31227 The Document may contain zero Invariant Sections. If the Document
31228 does not identify any Invariant Sections then there are none.
31230 The "Cover Texts" are certain short passages of text that are
31231 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
31232 that says that the Document is released under this License. A
31233 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
31234 be at most 25 words.
31236 A "Transparent" copy of the Document means a machine-readable copy,
31237 represented in a format whose specification is available to the
31238 general public, that is suitable for revising the document
31239 straightforwardly with generic text editors or (for images
31240 composed of pixels) generic paint programs or (for drawings) some
31241 widely available drawing editor, and that is suitable for input to
31242 text formatters or for automatic translation to a variety of
31243 formats suitable for input to text formatters. A copy made in an
31244 otherwise Transparent file format whose markup, or absence of
31245 markup, has been arranged to thwart or discourage subsequent
31246 modification by readers is not Transparent. An image format is
31247 not Transparent if used for any substantial amount of text. A
31248 copy that is not "Transparent" is called "Opaque".
31250 Examples of suitable formats for Transparent copies include plain
31251 ASCII without markup, Texinfo input format, LaTeX input format,
31252 SGML or XML using a publicly available DTD, and
31253 standard-conforming simple HTML, PostScript or PDF designed for
31254 human modification. Examples of transparent image formats include
31255 PNG, XCF and JPG. Opaque formats include proprietary formats that
31256 can be read and edited only by proprietary word processors, SGML or
31257 XML for which the DTD and/or processing tools are not generally
31258 available, and the machine-generated HTML, PostScript or PDF
31259 produced by some word processors for output purposes only.
31261 The "Title Page" means, for a printed book, the title page itself,
31262 plus such following pages as are needed to hold, legibly, the
31263 material this License requires to appear in the title page. For
31264 works in formats which do not have any title page as such, "Title
31265 Page" means the text near the most prominent appearance of the
31266 work's title, preceding the beginning of the body of the text.
31268 A section "Entitled XYZ" means a named subunit of the Document
31269 whose title either is precisely XYZ or contains XYZ in parentheses
31270 following text that translates XYZ in another language. (Here XYZ
31271 stands for a specific section name mentioned below, such as
31272 "Acknowledgements", "Dedications", "Endorsements", or "History".)
31273 To "Preserve the Title" of such a section when you modify the
31274 Document means that it remains a section "Entitled XYZ" according
31275 to this definition.
31277 The Document may include Warranty Disclaimers next to the notice
31278 which states that this License applies to the Document. These
31279 Warranty Disclaimers are considered to be included by reference in
31280 this License, but only as regards disclaiming warranties: any other
31281 implication that these Warranty Disclaimers may have is void and
31282 has no effect on the meaning of this License.
31284 2. VERBATIM COPYING
31286 You may copy and distribute the Document in any medium, either
31287 commercially or noncommercially, provided that this License, the
31288 copyright notices, and the license notice saying this License
31289 applies to the Document are reproduced in all copies, and that you
31290 add no other conditions whatsoever to those of this License. You
31291 may not use technical measures to obstruct or control the reading
31292 or further copying of the copies you make or distribute. However,
31293 you may accept compensation in exchange for copies. If you
31294 distribute a large enough number of copies you must also follow
31295 the conditions in section 3.
31297 You may also lend copies, under the same conditions stated above,
31298 and you may publicly display copies.
31300 3. COPYING IN QUANTITY
31302 If you publish printed copies (or copies in media that commonly
31303 have printed covers) of the Document, numbering more than 100, and
31304 the Document's license notice requires Cover Texts, you must
31305 enclose the copies in covers that carry, clearly and legibly, all
31306 these Cover Texts: Front-Cover Texts on the front cover, and
31307 Back-Cover Texts on the back cover. Both covers must also clearly
31308 and legibly identify you as the publisher of these copies. The
31309 front cover must present the full title with all words of the
31310 title equally prominent and visible. You may add other material
31311 on the covers in addition. Copying with changes limited to the
31312 covers, as long as they preserve the title of the Document and
31313 satisfy these conditions, can be treated as verbatim copying in
31316 If the required texts for either cover are too voluminous to fit
31317 legibly, you should put the first ones listed (as many as fit
31318 reasonably) on the actual cover, and continue the rest onto
31321 If you publish or distribute Opaque copies of the Document
31322 numbering more than 100, you must either include a
31323 machine-readable Transparent copy along with each Opaque copy, or
31324 state in or with each Opaque copy a computer-network location from
31325 which the general network-using public has access to download
31326 using public-standard network protocols a complete Transparent
31327 copy of the Document, free of added material. If you use the
31328 latter option, you must take reasonably prudent steps, when you
31329 begin distribution of Opaque copies in quantity, to ensure that
31330 this Transparent copy will remain thus accessible at the stated
31331 location until at least one year after the last time you
31332 distribute an Opaque copy (directly or through your agents or
31333 retailers) of that edition to the public.
31335 It is requested, but not required, that you contact the authors of
31336 the Document well before redistributing any large number of
31337 copies, to give them a chance to provide you with an updated
31338 version of the Document.
31342 You may copy and distribute a Modified Version of the Document
31343 under the conditions of sections 2 and 3 above, provided that you
31344 release the Modified Version under precisely this License, with
31345 the Modified Version filling the role of the Document, thus
31346 licensing distribution and modification of the Modified Version to
31347 whoever possesses a copy of it. In addition, you must do these
31348 things in the Modified Version:
31350 A. Use in the Title Page (and on the covers, if any) a title
31351 distinct from that of the Document, and from those of
31352 previous versions (which should, if there were any, be listed
31353 in the History section of the Document). You may use the
31354 same title as a previous version if the original publisher of
31355 that version gives permission.
31357 B. List on the Title Page, as authors, one or more persons or
31358 entities responsible for authorship of the modifications in
31359 the Modified Version, together with at least five of the
31360 principal authors of the Document (all of its principal
31361 authors, if it has fewer than five), unless they release you
31362 from this requirement.
31364 C. State on the Title page the name of the publisher of the
31365 Modified Version, as the publisher.
31367 D. Preserve all the copyright notices of the Document.
31369 E. Add an appropriate copyright notice for your modifications
31370 adjacent to the other copyright notices.
31372 F. Include, immediately after the copyright notices, a license
31373 notice giving the public permission to use the Modified
31374 Version under the terms of this License, in the form shown in
31375 the Addendum below.
31377 G. Preserve in that license notice the full lists of Invariant
31378 Sections and required Cover Texts given in the Document's
31381 H. Include an unaltered copy of this License.
31383 I. Preserve the section Entitled "History", Preserve its Title,
31384 and add to it an item stating at least the title, year, new
31385 authors, and publisher of the Modified Version as given on
31386 the Title Page. If there is no section Entitled "History" in
31387 the Document, create one stating the title, year, authors,
31388 and publisher of the Document as given on its Title Page,
31389 then add an item describing the Modified Version as stated in
31390 the previous sentence.
31392 J. Preserve the network location, if any, given in the Document
31393 for public access to a Transparent copy of the Document, and
31394 likewise the network locations given in the Document for
31395 previous versions it was based on. These may be placed in
31396 the "History" section. You may omit a network location for a
31397 work that was published at least four years before the
31398 Document itself, or if the original publisher of the version
31399 it refers to gives permission.
31401 K. For any section Entitled "Acknowledgements" or "Dedications",
31402 Preserve the Title of the section, and preserve in the
31403 section all the substance and tone of each of the contributor
31404 acknowledgements and/or dedications given therein.
31406 L. Preserve all the Invariant Sections of the Document,
31407 unaltered in their text and in their titles. Section numbers
31408 or the equivalent are not considered part of the section
31411 M. Delete any section Entitled "Endorsements". Such a section
31412 may not be included in the Modified Version.
31414 N. Do not retitle any existing section to be Entitled
31415 "Endorsements" or to conflict in title with any Invariant
31418 O. Preserve any Warranty Disclaimers.
31420 If the Modified Version includes new front-matter sections or
31421 appendices that qualify as Secondary Sections and contain no
31422 material copied from the Document, you may at your option
31423 designate some or all of these sections as invariant. To do this,
31424 add their titles to the list of Invariant Sections in the Modified
31425 Version's license notice. These titles must be distinct from any
31426 other section titles.
31428 You may add a section Entitled "Endorsements", provided it contains
31429 nothing but endorsements of your Modified Version by various
31430 parties--for example, statements of peer review or that the text
31431 has been approved by an organization as the authoritative
31432 definition of a standard.
31434 You may add a passage of up to five words as a Front-Cover Text,
31435 and a passage of up to 25 words as a Back-Cover Text, to the end
31436 of the list of Cover Texts in the Modified Version. Only one
31437 passage of Front-Cover Text and one of Back-Cover Text may be
31438 added by (or through arrangements made by) any one entity. If the
31439 Document already includes a cover text for the same cover,
31440 previously added by you or by arrangement made by the same entity
31441 you are acting on behalf of, you may not add another; but you may
31442 replace the old one, on explicit permission from the previous
31443 publisher that added the old one.
31445 The author(s) and publisher(s) of the Document do not by this
31446 License give permission to use their names for publicity for or to
31447 assert or imply endorsement of any Modified Version.
31449 5. COMBINING DOCUMENTS
31451 You may combine the Document with other documents released under
31452 this License, under the terms defined in section 4 above for
31453 modified versions, provided that you include in the combination
31454 all of the Invariant Sections of all of the original documents,
31455 unmodified, and list them all as Invariant Sections of your
31456 combined work in its license notice, and that you preserve all
31457 their Warranty Disclaimers.
31459 The combined work need only contain one copy of this License, and
31460 multiple identical Invariant Sections may be replaced with a single
31461 copy. If there are multiple Invariant Sections with the same name
31462 but different contents, make the title of each such section unique
31463 by adding at the end of it, in parentheses, the name of the
31464 original author or publisher of that section if known, or else a
31465 unique number. Make the same adjustment to the section titles in
31466 the list of Invariant Sections in the license notice of the
31469 In the combination, you must combine any sections Entitled
31470 "History" in the various original documents, forming one section
31471 Entitled "History"; likewise combine any sections Entitled
31472 "Acknowledgements", and any sections Entitled "Dedications". You
31473 must delete all sections Entitled "Endorsements."
31475 6. COLLECTIONS OF DOCUMENTS
31477 You may make a collection consisting of the Document and other
31478 documents released under this License, and replace the individual
31479 copies of this License in the various documents with a single copy
31480 that is included in the collection, provided that you follow the
31481 rules of this License for verbatim copying of each of the
31482 documents in all other respects.
31484 You may extract a single document from such a collection, and
31485 distribute it individually under this License, provided you insert
31486 a copy of this License into the extracted document, and follow
31487 this License in all other respects regarding verbatim copying of
31490 7. AGGREGATION WITH INDEPENDENT WORKS
31492 A compilation of the Document or its derivatives with other
31493 separate and independent documents or works, in or on a volume of
31494 a storage or distribution medium, is called an "aggregate" if the
31495 copyright resulting from the compilation is not used to limit the
31496 legal rights of the compilation's users beyond what the individual
31497 works permit. When the Document is included in an aggregate, this
31498 License does not apply to the other works in the aggregate which
31499 are not themselves derivative works of the Document.
31501 If the Cover Text requirement of section 3 is applicable to these
31502 copies of the Document, then if the Document is less than one half
31503 of the entire aggregate, the Document's Cover Texts may be placed
31504 on covers that bracket the Document within the aggregate, or the
31505 electronic equivalent of covers if the Document is in electronic
31506 form. Otherwise they must appear on printed covers that bracket
31507 the whole aggregate.
31511 Translation is considered a kind of modification, so you may
31512 distribute translations of the Document under the terms of section
31513 4. Replacing Invariant Sections with translations requires special
31514 permission from their copyright holders, but you may include
31515 translations of some or all Invariant Sections in addition to the
31516 original versions of these Invariant Sections. You may include a
31517 translation of this License, and all the license notices in the
31518 Document, and any Warranty Disclaimers, provided that you also
31519 include the original English version of this License and the
31520 original versions of those notices and disclaimers. In case of a
31521 disagreement between the translation and the original version of
31522 this License or a notice or disclaimer, the original version will
31525 If a section in the Document is Entitled "Acknowledgements",
31526 "Dedications", or "History", the requirement (section 4) to
31527 Preserve its Title (section 1) will typically require changing the
31532 You may not copy, modify, sublicense, or distribute the Document
31533 except as expressly provided for under this License. Any other
31534 attempt to copy, modify, sublicense or distribute the Document is
31535 void, and will automatically terminate your rights under this
31536 License. However, parties who have received copies, or rights,
31537 from you under this License will not have their licenses
31538 terminated so long as such parties remain in full compliance.
31540 10. FUTURE REVISIONS OF THIS LICENSE
31542 The Free Software Foundation may publish new, revised versions of
31543 the GNU Free Documentation License from time to time. Such new
31544 versions will be similar in spirit to the present version, but may
31545 differ in detail to address new problems or concerns. See
31546 `http://www.gnu.org/copyleft/'.
31548 Each version of the License is given a distinguishing version
31549 number. If the Document specifies that a particular numbered
31550 version of this License "or any later version" applies to it, you
31551 have the option of following the terms and conditions either of
31552 that specified version or of any later version that has been
31553 published (not as a draft) by the Free Software Foundation. If
31554 the Document does not specify a version number of this License,
31555 you may choose any version ever published (not as a draft) by the
31556 Free Software Foundation.
31558 J.1 ADDENDUM: How to use this License for your documents
31559 ========================================================
31561 To use this License in a document you have written, include a copy of
31562 the License in the document and put the following copyright and license
31563 notices just after the title page:
31565 Copyright (C) YEAR YOUR NAME.
31566 Permission is granted to copy, distribute and/or modify this document
31567 under the terms of the GNU Free Documentation License, Version 1.2
31568 or any later version published by the Free Software Foundation;
31569 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
31570 Texts. A copy of the license is included in the section entitled ``GNU
31571 Free Documentation License''.
31573 If you have Invariant Sections, Front-Cover Texts and Back-Cover
31574 Texts, replace the "with...Texts." line with this:
31576 with the Invariant Sections being LIST THEIR TITLES, with
31577 the Front-Cover Texts being LIST, and with the Back-Cover Texts
31580 If you have Invariant Sections without Cover Texts, or some other
31581 combination of the three, merge those two alternatives to suit the
31584 If your document contains nontrivial examples of program code, we
31585 recommend releasing these examples in parallel under your choice of
31586 free software license, such as the GNU General Public License, to
31587 permit their use in free software.
31590 File: gdb.info, Node: Index, Prev: GNU Free Documentation License, Up: Top
31598 * ! packet: Packets. (line 49)
31599 * "No symbol "foo" in current context": Variables. (line 74)
31600 * # (a comment): Command Syntax. (line 38)
31601 * # in Modula-2: GDB/M2. (line 18)
31602 * $: Value History. (line 13)
31603 * $$: Value History. (line 13)
31604 * $_ and info breakpoints: Set Breaks. (line 117)
31605 * $_ and info line: Machine Code. (line 30)
31606 * $_, $__, and value history: Memory. (line 101)
31607 * $_, convenience variable: Convenience Vars. (line 64)
31608 * $__, convenience variable: Convenience Vars. (line 73)
31609 * $_exitcode, convenience variable: Convenience Vars. (line 79)
31610 * $_siginfo, convenience variable: Convenience Vars. (line 83)
31611 * $bpnum, convenience variable: Set Breaks. (line 6)
31612 * $cdir, convenience variable: Source Path. (line 108)
31613 * $cwd, convenience variable: Source Path. (line 108)
31614 * $tpnum: Create and Delete Tracepoints.
31616 * $trace_file: Tracepoint Variables.
31618 * $trace_frame: Tracepoint Variables.
31620 * $trace_func: Tracepoint Variables.
31622 * $trace_line: Tracepoint Variables.
31624 * $tracepoint: Tracepoint Variables.
31626 * --annotate: Mode Options. (line 101)
31627 * --args: Mode Options. (line 114)
31628 * --batch: Mode Options. (line 23)
31629 * --batch-silent: Mode Options. (line 39)
31630 * --baud: Mode Options. (line 120)
31631 * --cd: Mode Options. (line 80)
31632 * --command: File Options. (line 51)
31633 * --core: File Options. (line 43)
31634 * --directory: File Options. (line 67)
31635 * --epoch: Mode Options. (line 96)
31636 * --eval-command: File Options. (line 57)
31637 * --exec: File Options. (line 35)
31638 * --fullname: Mode Options. (line 85)
31639 * --interpreter: Mode Options. (line 141)
31640 * --nowindows: Mode Options. (line 70)
31641 * --nx: Mode Options. (line 11)
31642 * --pid: File Options. (line 47)
31643 * --quiet: Mode Options. (line 19)
31644 * --readnow: File Options. (line 71)
31645 * --return-child-result: Mode Options. (line 51)
31646 * --se: File Options. (line 39)
31647 * --silent: Mode Options. (line 19)
31648 * --statistics: Mode Options. (line 158)
31649 * --symbols: File Options. (line 31)
31650 * --tty: Mode Options. (line 129)
31651 * --tui: Mode Options. (line 132)
31652 * --version: Mode Options. (line 162)
31653 * --windows: Mode Options. (line 76)
31654 * --with-gdb-datadir: Data Files. (line 19)
31655 * --with-relocated-sources: Source Path. (line 89)
31656 * --with-sysroot: Files. (line 393)
31657 * --write: Mode Options. (line 153)
31658 * -b: Mode Options. (line 120)
31659 * -break-after: GDB/MI Breakpoint Commands.
31661 * -break-commands: GDB/MI Breakpoint Commands.
31663 * -break-condition: GDB/MI Breakpoint Commands.
31665 * -break-delete: GDB/MI Breakpoint Commands.
31667 * -break-disable: GDB/MI Breakpoint Commands.
31669 * -break-enable: GDB/MI Breakpoint Commands.
31671 * -break-info: GDB/MI Breakpoint Commands.
31673 * -break-insert: GDB/MI Breakpoint Commands.
31675 * -break-list: GDB/MI Breakpoint Commands.
31677 * -break-watch: GDB/MI Breakpoint Commands.
31679 * -c: File Options. (line 43)
31680 * -d: File Options. (line 67)
31681 * -data-disassemble: GDB/MI Data Manipulation.
31683 * -data-evaluate-expression: GDB/MI Data Manipulation.
31685 * -data-list-changed-registers: GDB/MI Data Manipulation.
31687 * -data-list-register-names: GDB/MI Data Manipulation.
31689 * -data-list-register-values: GDB/MI Data Manipulation.
31691 * -data-read-memory: GDB/MI Data Manipulation.
31693 * -e: File Options. (line 35)
31694 * -enable-pretty-printing: GDB/MI Variable Objects.
31696 * -enable-timings: GDB/MI Miscellaneous Commands.
31698 * -environment-cd: GDB/MI Program Context.
31700 * -environment-directory: GDB/MI Program Context.
31702 * -environment-path: GDB/MI Program Context.
31704 * -environment-pwd: GDB/MI Program Context.
31706 * -ex: File Options. (line 57)
31707 * -exec-arguments: GDB/MI Program Context.
31709 * -exec-continue: GDB/MI Program Execution.
31711 * -exec-finish: GDB/MI Program Execution.
31713 * -exec-interrupt: GDB/MI Program Execution.
31715 * -exec-jump: GDB/MI Program Execution.
31717 * -exec-next: GDB/MI Program Execution.
31719 * -exec-next-instruction: GDB/MI Program Execution.
31721 * -exec-return: GDB/MI Program Execution.
31723 * -exec-run: GDB/MI Program Execution.
31725 * -exec-step: GDB/MI Program Execution.
31727 * -exec-step-instruction: GDB/MI Program Execution.
31729 * -exec-until: GDB/MI Program Execution.
31731 * -f: Mode Options. (line 85)
31732 * -file-exec-and-symbols: GDB/MI File Commands.
31734 * -file-exec-file: GDB/MI File Commands.
31736 * -file-list-exec-source-file: GDB/MI File Commands.
31738 * -file-list-exec-source-files: GDB/MI File Commands.
31740 * -file-symbol-file: GDB/MI File Commands.
31742 * -gdb-exit: GDB/MI Miscellaneous Commands.
31744 * -gdb-set: GDB/MI Miscellaneous Commands.
31746 * -gdb-show: GDB/MI Miscellaneous Commands.
31748 * -gdb-version: GDB/MI Miscellaneous Commands.
31750 * -inferior-tty-set: GDB/MI Miscellaneous Commands.
31752 * -inferior-tty-show: GDB/MI Miscellaneous Commands.
31754 * -interpreter-exec: GDB/MI Miscellaneous Commands.
31756 * -l: Mode Options. (line 124)
31757 * -list-features: GDB/MI Miscellaneous Commands.
31759 * -list-target-features: GDB/MI Miscellaneous Commands.
31761 * -list-thread-groups: GDB/MI Miscellaneous Commands.
31763 * -n: Mode Options. (line 11)
31764 * -nw: Mode Options. (line 70)
31765 * -p: File Options. (line 47)
31766 * -q: Mode Options. (line 19)
31767 * -r: File Options. (line 71)
31768 * -s: File Options. (line 31)
31769 * -stack-info-depth: GDB/MI Stack Manipulation.
31771 * -stack-info-frame: GDB/MI Stack Manipulation.
31773 * -stack-list-arguments: GDB/MI Stack Manipulation.
31775 * -stack-list-frames: GDB/MI Stack Manipulation.
31777 * -stack-list-locals: GDB/MI Stack Manipulation.
31779 * -stack-list-variables: GDB/MI Stack Manipulation.
31781 * -stack-select-frame: GDB/MI Stack Manipulation.
31783 * -symbol-list-lines: GDB/MI Symbol Query. (line 9)
31784 * -t: Mode Options. (line 129)
31785 * -target-attach: GDB/MI Target Manipulation.
31787 * -target-detach: GDB/MI Target Manipulation.
31789 * -target-disconnect: GDB/MI Target Manipulation.
31791 * -target-download: GDB/MI Target Manipulation.
31793 * -target-file-delete: GDB/MI File Transfer Commands.
31795 * -target-file-get: GDB/MI File Transfer Commands.
31797 * -target-file-put: GDB/MI File Transfer Commands.
31799 * -target-select: GDB/MI Target Manipulation.
31801 * -thread-info: GDB/MI Thread Commands.
31803 * -thread-list-ids: GDB/MI Thread Commands.
31805 * -thread-select: GDB/MI Thread Commands.
31807 * -var-assign: GDB/MI Variable Objects.
31809 * -var-create: GDB/MI Variable Objects.
31811 * -var-delete: GDB/MI Variable Objects.
31813 * -var-evaluate-expression: GDB/MI Variable Objects.
31815 * -var-info-expression: GDB/MI Variable Objects.
31817 * -var-info-num-children: GDB/MI Variable Objects.
31819 * -var-info-path-expression: GDB/MI Variable Objects.
31821 * -var-info-type: GDB/MI Variable Objects.
31823 * -var-list-children: GDB/MI Variable Objects.
31825 * -var-set-format: GDB/MI Variable Objects.
31827 * -var-set-frozen: GDB/MI Variable Objects.
31829 * -var-set-update-range: GDB/MI Variable Objects.
31831 * -var-set-visualizer: GDB/MI Variable Objects.
31833 * -var-show-attributes: GDB/MI Variable Objects.
31835 * -var-show-format: GDB/MI Variable Objects.
31837 * -var-update: GDB/MI Variable Objects.
31839 * -w: Mode Options. (line 76)
31840 * -x: File Options. (line 51)
31841 * ., Modula-2 scope operator: M2 Scope. (line 6)
31842 * .build-id directory: Separate Debug Files.
31844 * .debug subdirectories: Separate Debug Files.
31846 * .gdbinit: Startup. (line 45)
31847 * .gnu_debuglink sections: Separate Debug Files.
31849 * .note.gnu.build-id sections: Separate Debug Files.
31851 * .o files, reading symbols from: Files. (line 132)
31852 * /proc: SVR4 Process Information.
31854 * <architecture>: Target Description Format.
31856 * <compatible>: Target Description Format.
31858 * <feature>: Target Description Format.
31860 * <osabi>: Target Description Format.
31862 * <reg>: Target Description Format.
31864 * <union>: Target Description Format.
31866 * <vector>: Target Description Format.
31868 * ? packet: Packets. (line 58)
31869 * @, referencing memory as an array: Arrays. (line 6)
31870 * ^connected: GDB/MI Result Records.
31872 * ^done: GDB/MI Result Records.
31874 * ^error: GDB/MI Result Records.
31876 * ^exit: GDB/MI Result Records.
31878 * ^running: GDB/MI Result Records.
31880 * __init__ on Command: Commands In Python. (line 12)
31881 * __init__ on Function: Functions In Python. (line 11)
31882 * _NSPrintForDebugger, and printing Objective-C objects: The Print Command with Objective-C.
31884 * A packet: Packets. (line 65)
31885 * abbreviation: Command Syntax. (line 13)
31886 * abort (C-g): Miscellaneous Commands.
31888 * accept-line (Newline or Return): Commands For History.
31890 * acknowledgment, for GDB remote: Packet Acknowledgment.
31892 * actions: Tracepoint Actions. (line 6)
31893 * active targets: Active Targets. (line 6)
31894 * Ada: Ada. (line 6)
31895 * Ada exception catching: Set Catchpoints. (line 19)
31896 * Ada mode, general: Ada Mode Intro. (line 6)
31897 * Ada task switching: Ada Tasks. (line 115)
31898 * Ada tasking and core file debugging: Ada Tasks and Core Files.
31900 * Ada, deviations from: Additions to Ada. (line 6)
31901 * Ada, omissions from: Omissions from Ada. (line 6)
31902 * Ada, problems: Ada Glitches. (line 6)
31903 * Ada, tasking: Ada Tasks. (line 6)
31904 * add new commands for external monitor: Connecting. (line 105)
31905 * add-inferior: Inferiors and Programs.
31907 * add-shared-symbol-files: Files. (line 172)
31908 * add-symbol-file: Files. (line 113)
31909 * add-symbol-file-from-memory: Files. (line 162)
31910 * address <1>: Lazy Strings In Python.
31912 * address: Values From Inferior.
31914 * address of a symbol: Symbols. (line 44)
31915 * address size for remote targets: Remote Configuration.
31917 * ADP (Angel Debugger Protocol) logging: ARM. (line 89)
31918 * advance LOCATION: Continuing and Stepping.
31920 * aggregates (Ada): Omissions from Ada. (line 44)
31921 * AIX threads: Debugging Output. (line 28)
31922 * alignment of remote memory accesses: Packets. (line 215)
31923 * all-stop mode: All-Stop Mode. (line 6)
31924 * Alpha stack: MIPS. (line 6)
31925 * ambiguous expressions: Ambiguous Expressions.
31927 * AMD 29K register stack: A29K. (line 6)
31928 * annotations: Annotations Overview.
31930 * annotations for errors, warnings and interrupts: Errors. (line 6)
31931 * annotations for invalidation messages: Invalidation. (line 6)
31932 * annotations for prompts: Prompting. (line 6)
31933 * annotations for running programs: Annotations for Running.
31935 * annotations for source display: Source Annotations. (line 6)
31936 * append: Dump/Restore Files. (line 35)
31937 * append data to a file: Dump/Restore Files. (line 6)
31938 * apply command to several threads: Threads. (line 150)
31939 * apropos: Help. (line 62)
31940 * architecture debugging info: Debugging Output. (line 18)
31941 * argument count in user-defined commands: Define. (line 25)
31942 * arguments (to your program): Arguments. (line 6)
31943 * arguments, to gdbserver: Server. (line 34)
31944 * arguments, to user-defined commands: Define. (line 6)
31945 * ARM 32-bit mode: ARM. (line 25)
31946 * ARM RDI: ARM. (line 6)
31947 * array aggregates (Ada): Omissions from Ada. (line 44)
31948 * arrays: Arrays. (line 6)
31949 * arrays in expressions: Expressions. (line 14)
31950 * artificial array: Arrays. (line 6)
31951 * assembly instructions: Machine Code. (line 36)
31952 * assf: Files. (line 172)
31953 * assignment: Assignment. (line 6)
31954 * async output in GDB/MI: GDB/MI Output Syntax.
31956 * async records in GDB/MI: GDB/MI Async Records.
31958 * asynchronous execution: Background Execution.
31960 * asynchronous execution, and process record and replay: Process Record and Replay.
31962 * AT&T disassembly flavor: Machine Code. (line 107)
31963 * attach: Attach. (line 6)
31964 * attach to a program by name: Server. (line 79)
31965 * attach&: Background Execution.
31967 * auto-loading, Python: Auto-loading. (line 6)
31968 * auto-retry, for remote TCP target: Remote Configuration.
31970 * automatic display: Auto Display. (line 6)
31971 * automatic hardware breakpoints: Set Breaks. (line 273)
31972 * automatic overlay debugging: Automatic Overlay Debugging.
31974 * automatic thread selection: All-Stop Mode. (line 28)
31975 * auxiliary vector: OS Information. (line 21)
31976 * AVR: AVR. (line 6)
31977 * awatch: Set Watchpoints. (line 60)
31978 * b (break): Set Breaks. (line 6)
31979 * B packet: Packets. (line 92)
31980 * b packet: Packets. (line 77)
31981 * background execution: Background Execution.
31983 * backtrace: Backtrace. (line 11)
31984 * backtrace beyond main function: Backtrace. (line 93)
31985 * backtrace limit: Backtrace. (line 129)
31986 * backward-char (C-b): Commands For Moving. (line 15)
31987 * backward-delete-char (Rubout): Commands For Text. (line 11)
31988 * backward-kill-line (C-x Rubout): Commands For Killing.
31990 * backward-kill-word (M-<DEL>): Commands For Killing.
31992 * backward-word (M-b): Commands For Moving. (line 22)
31993 * baud rate for remote targets: Remote Configuration.
31995 * bc packet: Packets. (line 97)
31996 * bcache statistics: Maintenance Commands.
31998 * beginning-of-history (M-<): Commands For History.
32000 * beginning-of-line (C-a): Commands For Moving. (line 6)
32001 * bell-style: Readline Init File Syntax.
32003 * bind-tty-special-chars: Readline Init File Syntax.
32005 * bits in remote address: Remote Configuration.
32007 * bookmark: Checkpoint/Restart. (line 6)
32008 * break: Set Breaks. (line 6)
32009 * break ... task TASKNO (Ada): Ada Tasks. (line 135)
32010 * break ... thread THREADNO: Thread-Specific Breakpoints.
32012 * break in overloaded functions: Debugging C Plus Plus.
32014 * break on a system call.: Set Catchpoints. (line 48)
32015 * break on fork/exec: Set Catchpoints. (line 43)
32016 * BREAK signal instead of Ctrl-C: Remote Configuration.
32018 * break, and Objective-C: Method Names in Commands.
32020 * breakpoint address adjusted: Breakpoint-related Warnings.
32022 * breakpoint annotation: Annotations for Running.
32024 * breakpoint commands: Break Commands. (line 6)
32025 * breakpoint commands for GDB/MI: GDB/MI Breakpoint Commands.
32027 * breakpoint conditions: Conditions. (line 6)
32028 * breakpoint numbers: Breakpoints. (line 41)
32029 * breakpoint on events: Breakpoints. (line 33)
32030 * breakpoint on memory address: Breakpoints. (line 20)
32031 * breakpoint on variable modification: Breakpoints. (line 20)
32032 * breakpoint ranges: Breakpoints. (line 48)
32033 * breakpoint subroutine, remote: Stub Contents. (line 31)
32034 * breakpointing Ada elaboration code: Stopping Before Main Program.
32036 * breakpoints: Breakpoints. (line 6)
32037 * breakpoints and tasks, in Ada: Ada Tasks. (line 135)
32038 * breakpoints and threads: Thread-Specific Breakpoints.
32040 * breakpoints in functions matching a regexp: Set Breaks. (line 92)
32041 * breakpoints in overlays: Overlay Commands. (line 93)
32042 * breakpoints, multiple locations: Set Breaks. (line 179)
32043 * breakpoints-invalid annotation: Invalidation. (line 13)
32044 * bs packet: Packets. (line 103)
32045 * bt (backtrace): Backtrace. (line 11)
32046 * bug criteria: Bug Criteria. (line 6)
32047 * bug reports: Bug Reporting. (line 6)
32048 * bugs in GDB: GDB Bugs. (line 6)
32049 * build ID sections: Separate Debug Files.
32051 * build ID, and separate debugging files: Separate Debug Files.
32053 * building GDB, requirements for: Requirements. (line 6)
32054 * built-in simulator target: Target Commands. (line 73)
32055 * c (continue): Continuing and Stepping.
32057 * c (SingleKey TUI key): TUI Single Key Mode. (line 10)
32058 * C and C++: C. (line 6)
32059 * C and C++ checks: C Checks. (line 6)
32060 * C and C++ constants: C Constants. (line 6)
32061 * C and C++ defaults: C Defaults. (line 6)
32062 * C and C++ operators: C Operators. (line 6)
32063 * C packet: Packets. (line 116)
32064 * c packet: Packets. (line 110)
32065 * C++: C. (line 10)
32066 * C++ compilers: C Plus Plus Expressions.
32068 * C++ exception handling: Debugging C Plus Plus.
32070 * C++ overload debugging info: Debugging Output. (line 108)
32071 * C++ scope resolution: Variables. (line 54)
32072 * C++ symbol decoding style: Print Settings. (line 296)
32073 * C++ symbol display: Debugging C Plus Plus.
32075 * C-L: TUI Keys. (line 65)
32076 * C-x 1: TUI Keys. (line 19)
32077 * C-x 2: TUI Keys. (line 26)
32078 * C-x A: TUI Keys. (line 12)
32079 * C-x a: TUI Keys. (line 11)
32080 * C-x C-a: TUI Keys. (line 10)
32081 * C-x o: TUI Keys. (line 34)
32082 * C-x s: TUI Keys. (line 41)
32083 * caching data of remote targets: Caching Remote Data. (line 6)
32084 * call: Calling. (line 10)
32085 * call dummy stack unwinding: Calling. (line 35)
32086 * call dummy stack unwinding on unhandled exception.: Calling.
32088 * call overloaded functions: C Plus Plus Expressions.
32090 * call stack: Stack. (line 9)
32091 * call stack traces: Backtrace. (line 6)
32092 * call-last-kbd-macro (C-x e): Keyboard Macros. (line 13)
32093 * calling functions: Calling. (line 6)
32094 * calling make: Shell Commands. (line 19)
32095 * capitalize-word (M-c): Commands For Text. (line 49)
32096 * case sensitivity in symbol names: Symbols. (line 27)
32097 * case-insensitive symbol names: Symbols. (line 27)
32098 * cast on Value: Values From Inferior.
32100 * casts, in expressions: Expressions. (line 28)
32101 * casts, to view memory: Expressions. (line 43)
32102 * catch: Set Catchpoints. (line 10)
32103 * catch Ada exceptions: Set Catchpoints. (line 19)
32104 * catch exceptions, list active handlers: Frame Info. (line 60)
32105 * catchpoints: Breakpoints. (line 33)
32106 * catchpoints, setting: Set Catchpoints. (line 6)
32107 * cd: Working Directory. (line 16)
32108 * cdir: Source Path. (line 108)
32109 * Cell Broadband Engine: SPU. (line 6)
32110 * change working directory: Working Directory. (line 16)
32111 * character sets: Character Sets. (line 6)
32112 * character-search (C-]): Miscellaneous Commands.
32114 * character-search-backward (M-C-]): Miscellaneous Commands.
32116 * charset: Character Sets. (line 6)
32117 * checkpoint: Checkpoint/Restart. (line 6)
32118 * checkpoints and process id: Checkpoint/Restart. (line 80)
32119 * checks, range: Type Checking. (line 65)
32120 * checks, type: Checks. (line 31)
32121 * checksum, for GDB remote: Overview. (line 20)
32122 * children on pretty printer: Pretty Printing. (line 35)
32123 * choosing target byte order: Byte Order. (line 6)
32124 * clear: Delete Breaks. (line 21)
32125 * clear, and Objective-C: Method Names in Commands.
32127 * clear-screen (C-l): Commands For Moving. (line 26)
32128 * clearing breakpoints, watchpoints, catchpoints: Delete Breaks.
32130 * clone-inferior: Inferiors and Programs.
32132 * close, file-i/o system call: close. (line 6)
32133 * closest symbol and offset for an address: Symbols. (line 54)
32134 * code: Types In Python. (line 21)
32135 * code address and its source line: Machine Code. (line 25)
32136 * collect (tracepoints): Tracepoint Actions. (line 45)
32137 * collected data discarded: Starting and Stopping Trace Experiments.
32139 * colon, doubled as scope operator: M2 Scope. (line 6)
32140 * colon-colon, context for variables/functions: Variables. (line 44)
32141 * colon-colon, in Modula-2: M2 Scope. (line 6)
32142 * command editing: Readline Bare Essentials.
32144 * command files: Command Files. (line 6)
32145 * command history: Command History. (line 6)
32146 * command hooks: Hooks. (line 6)
32147 * command interpreters: Interpreters. (line 6)
32148 * command line editing: Editing. (line 6)
32149 * command scripts, debugging: Messages/Warnings. (line 65)
32150 * command tracing: Messages/Warnings. (line 60)
32151 * COMMAND_BREAKPOINTS: Commands In Python. (line 135)
32152 * COMMAND_DATA: Commands In Python. (line 105)
32153 * COMMAND_FILES: Commands In Python. (line 116)
32154 * COMMAND_MAINTENANCE: Commands In Python. (line 153)
32155 * COMMAND_NONE: Commands In Python. (line 95)
32156 * COMMAND_OBSCURE: Commands In Python. (line 147)
32157 * COMMAND_RUNNING: Commands In Python. (line 99)
32158 * COMMAND_STACK: Commands In Python. (line 110)
32159 * COMMAND_STATUS: Commands In Python. (line 129)
32160 * COMMAND_SUPPORT: Commands In Python. (line 122)
32161 * COMMAND_TRACEPOINTS: Commands In Python. (line 141)
32162 * commands: Break Commands. (line 11)
32163 * commands annotation: Prompting. (line 27)
32164 * commands for C++: Debugging C Plus Plus.
32166 * commands in python: Commands In Python. (line 6)
32167 * commands to access python: Python Commands. (line 6)
32168 * comment: Command Syntax. (line 38)
32169 * comment-begin: Readline Init File Syntax.
32171 * COMMON blocks, Fortran: Special Fortran Commands.
32173 * common targets: Target Commands. (line 46)
32174 * compare-sections: Memory. (line 121)
32175 * compatibility, GDB/MI and CLI: GDB/MI Compatibility with CLI.
32177 * compilation directory: Source Path. (line 108)
32178 * compiling, on Sparclet: Sparclet. (line 16)
32179 * complete: Help. (line 76)
32180 * complete (<TAB>): Commands For Completion.
32182 * complete on Command: Commands In Python. (line 63)
32183 * COMPLETE_COMMAND: Commands In Python. (line 174)
32184 * COMPLETE_FILENAME: Commands In Python. (line 167)
32185 * COMPLETE_LOCATION: Commands In Python. (line 170)
32186 * COMPLETE_NONE: Commands In Python. (line 164)
32187 * COMPLETE_SYMBOL: Commands In Python. (line 178)
32188 * completion: Completion. (line 6)
32189 * completion of Python commands: Commands In Python. (line 62)
32190 * completion of quoted strings: Completion. (line 57)
32191 * completion of structure field names: Completion. (line 96)
32192 * completion of union field names: Completion. (line 96)
32193 * completion-query-items: Readline Init File Syntax.
32195 * compressed debug sections: Requirements. (line 39)
32196 * condition: Conditions. (line 45)
32197 * conditional breakpoints: Conditions. (line 6)
32198 * conditional tracepoints: Tracepoint Conditions.
32200 * configuring GDB: Running Configure. (line 6)
32201 * confirmation: Messages/Warnings. (line 50)
32202 * connection timeout, for remote TCP target: Remote Configuration.
32204 * console i/o as part of file-i/o: Console I/O. (line 6)
32205 * console interpreter: Interpreters. (line 21)
32206 * console output in GDB/MI: GDB/MI Output Syntax.
32208 * const on Type: Types In Python. (line 79)
32209 * constants, in file-i/o protocol: Constants. (line 6)
32210 * continue: Continuing and Stepping.
32212 * continue&: Background Execution.
32214 * continuing: Continuing and Stepping.
32216 * continuing threads: Thread Stops. (line 6)
32217 * control C, and remote debugging: Bootstrapping. (line 25)
32218 * controlling terminal: Input/Output. (line 23)
32219 * convenience functions: Convenience Vars. (line 92)
32220 * convenience functions in python: Functions In Python. (line 6)
32221 * convenience variables: Convenience Vars. (line 6)
32222 * convenience variables for tracepoints: Tracepoint Variables.
32224 * convenience variables, and trace state variables: Trace State Variables.
32226 * convenience variables, initializing: Convenience Vars. (line 41)
32227 * convert-meta: Readline Init File Syntax.
32229 * copy-backward-word (): Commands For Killing.
32231 * copy-forward-word (): Commands For Killing.
32233 * copy-region-as-kill (): Commands For Killing.
32235 * core dump file: Files. (line 6)
32236 * core dump file target: Target Commands. (line 54)
32237 * core-file: Files. (line 97)
32238 * crash of debugger: Bug Criteria. (line 9)
32239 * CRC algorithm definition: Separate Debug Files.
32241 * CRC of memory block, remote request: General Query Packets.
32243 * CRIS: CRIS. (line 6)
32244 * CRIS mode: CRIS. (line 26)
32245 * CRIS version: CRIS. (line 10)
32246 * Ctrl-BREAK, MS-Windows: Cygwin Native. (line 9)
32247 * ctrl-c message, in file-i/o protocol: The Ctrl-C Message. (line 6)
32248 * Ctrl-o (operate-and-get-next): Command Syntax. (line 42)
32249 * current Ada task ID: Ada Tasks. (line 105)
32250 * current directory: Source Path. (line 108)
32251 * current stack frame: Frames. (line 45)
32252 * current thread: Threads. (line 45)
32253 * current thread, remote request: General Query Packets.
32255 * current_objfile: Objfiles In Python. (line 16)
32256 * cwd: Source Path. (line 108)
32257 * Cygwin DLL, debugging: Cygwin Native. (line 37)
32258 * Cygwin-specific commands: Cygwin Native. (line 6)
32259 * d (delete): Delete Breaks. (line 41)
32260 * d (SingleKey TUI key): TUI Single Key Mode. (line 13)
32261 * D packet: Packets. (line 129)
32262 * d packet: Packets. (line 122)
32263 * Darwin: Darwin. (line 6)
32264 * data breakpoints: Breakpoints. (line 20)
32265 * data manipulation, in GDB/MI: GDB/MI Data Manipulation.
32267 * dead names, GNU Hurd: Hurd Native. (line 85)
32268 * debug expression parser: Debugging Output. (line 114)
32269 * debug formats and C++: C Plus Plus Expressions.
32271 * debug link sections: Separate Debug Files.
32273 * debug remote protocol: Debugging Output. (line 123)
32274 * debug_chaos: M32R/D. (line 50)
32275 * debugger crash: Bug Criteria. (line 9)
32276 * debugging C++ programs: C Plus Plus Expressions.
32278 * debugging information directory, global: Separate Debug Files.
32280 * debugging information in separate files: Separate Debug Files.
32282 * debugging multiple processes: Forks. (line 52)
32283 * debugging multithreaded programs (on HP-UX): Threads. (line 89)
32284 * debugging optimized code: Optimized Code. (line 6)
32285 * debugging stub, example: Remote Stub. (line 6)
32286 * debugging target: Targets. (line 6)
32287 * debugging the Cygwin DLL: Cygwin Native. (line 37)
32288 * decimal floating point format: Decimal Floating Point.
32290 * default collection action: Tracepoint Actions. (line 89)
32291 * default data directory: Data Files. (line 19)
32292 * default source path substitution: Source Path. (line 89)
32293 * default system root: Files. (line 393)
32294 * define: Define. (line 37)
32295 * define trace state variable, remote request: Tracepoint Packets.
32297 * defining macros interactively: Macros. (line 52)
32298 * definition, showing a macro's: Macros. (line 47)
32299 * delete: Delete Breaks. (line 41)
32300 * delete breakpoints: Delete Breaks. (line 41)
32301 * delete checkpoint CHECKPOINT-ID: Checkpoint/Restart. (line 56)
32302 * delete display: Auto Display. (line 45)
32303 * delete mem: Memory Region Attributes.
32305 * delete tracepoint: Create and Delete Tracepoints.
32307 * delete tvariable: Trace State Variables.
32309 * delete-char (C-d): Commands For Text. (line 6)
32310 * delete-char-or-list (): Commands For Completion.
32312 * delete-horizontal-space (): Commands For Killing.
32314 * deleting breakpoints, watchpoints, catchpoints: Delete Breaks.
32316 * deliver a signal to a program: Signaling. (line 6)
32317 * demangling C++ names: Print Settings. (line 277)
32318 * deprecated commands: Maintenance Commands.
32320 * dereference on Value: Values From Inferior.
32322 * derived type of an object, printing: Print Settings. (line 329)
32323 * descriptor tables display: DJGPP Native. (line 24)
32324 * detach: Attach. (line 36)
32325 * detach (remote): Connecting. (line 91)
32326 * detach from task, GNU Hurd: Hurd Native. (line 60)
32327 * detach from thread, GNU Hurd: Hurd Native. (line 110)
32328 * detach inferior INFNO: Inferiors and Programs.
32330 * digit-argument (M-0, M-1, ... M--): Numeric Arguments. (line 6)
32331 * dir: Source Path. (line 39)
32332 * direct memory access (DMA) on MS-DOS: DJGPP Native. (line 75)
32333 * directories for source files: Source Path. (line 6)
32334 * directory: Source Path. (line 39)
32335 * directory, compilation: Source Path. (line 108)
32336 * directory, current: Source Path. (line 108)
32337 * dis (disable): Disabling. (line 38)
32338 * disable: Disabling. (line 38)
32339 * disable display: Auto Display. (line 52)
32340 * disable mem: Memory Region Attributes.
32342 * disable tracepoint: Enable and Disable Tracepoints.
32344 * disable-completion: Readline Init File Syntax.
32346 * disassemble: Machine Code. (line 36)
32347 * disconnect: Connecting. (line 98)
32348 * disconnected tracing: Starting and Stopping Trace Experiments.
32350 * displaced stepping debugging info: Debugging Output. (line 42)
32351 * displaced stepping support: Maintenance Commands.
32353 * displaced stepping, and process record and replay: Process Record and Replay.
32355 * display: Auto Display. (line 23)
32356 * display command history: Command History. (line 78)
32357 * display derived types: Print Settings. (line 329)
32358 * display disabled out of scope: Auto Display. (line 74)
32359 * display GDB copyright: Help. (line 136)
32360 * display of expressions: Auto Display. (line 6)
32361 * display remote monitor communications: Target Commands. (line 108)
32362 * display remote packets: Debugging Output. (line 123)
32363 * display_hint on pretty printer: Pretty Printing. (line 48)
32364 * DJGPP debugging: DJGPP Native. (line 6)
32365 * dll-symbols: Cygwin Native. (line 33)
32366 * DLLs with no debugging symbols: Non-debug DLL Symbols.
32368 * do (down): Selection. (line 40)
32369 * do not print frame argument values: Print Settings. (line 135)
32370 * do-uppercase-version (M-a, M-b, M-X, ...): Miscellaneous Commands.
32372 * document: Define. (line 49)
32373 * documentation: Formatting Documentation.
32375 * don't repeat command: Define. (line 61)
32376 * don't repeat Python command: Commands In Python. (line 43)
32377 * dont-repeat: Define. (line 61)
32378 * dont_repeat on Command: Commands In Python. (line 44)
32379 * DOS serial data link, remote debugging: DJGPP Native. (line 121)
32380 * DOS serial port status: DJGPP Native. (line 142)
32381 * Down: TUI Keys. (line 56)
32382 * down: Selection. (line 40)
32383 * down-silently: Selection. (line 64)
32384 * downcase-word (M-l): Commands For Text. (line 45)
32385 * download server address (M32R): M32R/D. (line 27)
32386 * download to Sparclet: Sparclet Download. (line 6)
32387 * download to VxWorks: VxWorks Download. (line 6)
32388 * DPMI: DJGPP Native. (line 6)
32389 * dump: Dump/Restore Files. (line 13)
32390 * dump all data collected at tracepoint: tdump. (line 6)
32391 * dump core from inferior: Core File Generation.
32393 * dump data to a file: Dump/Restore Files. (line 6)
32394 * dump-functions (): Miscellaneous Commands.
32396 * dump-macros (): Miscellaneous Commands.
32398 * dump-variables (): Miscellaneous Commands.
32400 * dump/restore files: Dump/Restore Files. (line 6)
32401 * DWARF 2 compilation units cache: Maintenance Commands.
32403 * DWARF-2 CFI and CRIS: CRIS. (line 18)
32404 * DWARF2 DIEs: Debugging Output. (line 35)
32405 * dynamic linking: Files. (line 113)
32406 * dynamic varobj: GDB/MI Variable Objects.
32408 * e (edit): Edit. (line 6)
32409 * echo: Output. (line 12)
32410 * edit: Edit. (line 6)
32411 * editing: Editing. (line 15)
32412 * editing command lines: Readline Bare Essentials.
32414 * editing source files: Edit. (line 6)
32415 * editing-mode: Readline Init File Syntax.
32417 * eight-bit characters in strings: Print Settings. (line 222)
32418 * elaboration phase: Starting. (line 90)
32419 * else: Command Files. (line 59)
32420 * Emacs: Emacs. (line 6)
32421 * empty response, for unsupported packets: Overview. (line 96)
32422 * enable: Disabling. (line 45)
32423 * enable display: Auto Display. (line 57)
32424 * enable mem: Memory Region Attributes.
32426 * enable tracepoint: Enable and Disable Tracepoints.
32428 * enable-keypad: Readline Init File Syntax.
32430 * enable/disable a breakpoint: Disabling. (line 6)
32431 * encoding: Lazy Strings In Python.
32433 * end (breakpoint commands): Break Commands. (line 11)
32434 * end (if/else/while commands): Command Files. (line 88)
32435 * end (user-defined commands): Define. (line 49)
32436 * end-kbd-macro (C-x )): Keyboard Macros. (line 9)
32437 * end-of-history (M->): Commands For History.
32439 * end-of-line (C-e): Commands For Moving. (line 9)
32440 * entering numbers: Numbers. (line 6)
32441 * environment (of your program): Environment. (line 6)
32442 * errno values, in file-i/o protocol: Errno Values. (line 6)
32443 * error annotation: Errors. (line 10)
32444 * error on valid input: Bug Criteria. (line 12)
32445 * error-begin annotation: Errors. (line 22)
32446 * event debugging info: Debugging Output. (line 50)
32447 * event designators: Event Designators. (line 6)
32448 * event handling: Set Catchpoints. (line 6)
32449 * examine process image: SVR4 Process Information.
32451 * examining data: Data. (line 6)
32452 * examining memory: Memory. (line 9)
32453 * exception handlers: Set Catchpoints. (line 6)
32454 * exception handlers, how to list: Frame Info. (line 60)
32455 * exceptionHandler: Bootstrapping. (line 38)
32456 * exceptions, python: Exception Handling. (line 6)
32457 * exchange-point-and-mark (C-x C-x): Miscellaneous Commands.
32459 * exec-file: Files. (line 39)
32460 * executable file: Files. (line 16)
32461 * executable file target: Target Commands. (line 50)
32462 * executable file, for remote target: Remote Configuration.
32464 * execute: Basic Python. (line 12)
32465 * execute commands from a file: Command Files. (line 17)
32466 * execute forward or backward in time: Reverse Execution. (line 87)
32467 * execute remote command, remote request: General Query Packets.
32469 * execution, foreground, background and asynchronous: Background Execution.
32471 * exited annotation: Annotations for Running.
32473 * exiting GDB: Quitting GDB. (line 6)
32474 * expand macro once: Macros. (line 38)
32475 * expand-tilde: Readline Init File Syntax.
32477 * expanding preprocessor macros: Macros. (line 29)
32478 * expression debugging info: Debugging Output. (line 57)
32479 * expression parser, debugging info: Debugging Output. (line 114)
32480 * expressions: Expressions. (line 6)
32481 * expressions in Ada: Ada. (line 11)
32482 * expressions in C or C++: C. (line 6)
32483 * expressions in C++: C Plus Plus Expressions.
32485 * expressions in Modula-2: Modula-2. (line 12)
32486 * extend GDB for remote targets: Connecting. (line 105)
32487 * extending GDB: Extending GDB. (line 6)
32488 * extra signal information: Signals. (line 102)
32489 * f (frame): Selection. (line 11)
32490 * f (SingleKey TUI key): TUI Single Key Mode. (line 16)
32491 * F packet: Packets. (line 146)
32492 * F reply packet: The F Reply Packet. (line 6)
32493 * F request packet: The F Request Packet.
32495 * fast tracepoints: Set Tracepoints. (line 25)
32496 * fatal signal: Bug Criteria. (line 9)
32497 * fatal signals: Signals. (line 15)
32498 * FDL, GNU Free Documentation License: GNU Free Documentation License.
32500 * features of the remote protocol: General Query Packets.
32502 * fg (resume foreground execution): Continuing and Stepping.
32504 * fields on Type: Types In Python. (line 38)
32505 * file: Files. (line 16)
32506 * file transfer: File Transfer. (line 6)
32507 * file transfer, remote protocol: Host I/O Packets. (line 6)
32508 * file-i/o examples: File-I/O Examples. (line 6)
32509 * file-i/o overview: File-I/O Overview. (line 6)
32510 * File-I/O remote protocol extension: File-I/O Remote Protocol Extension.
32512 * file-i/o reply packet: The F Reply Packet. (line 6)
32513 * file-i/o request packet: The F Request Packet.
32515 * filename: Objfiles In Python. (line 29)
32516 * fin (finish): Continuing and Stepping.
32518 * find: Searching Memory. (line 9)
32519 * find downloadable SREC files (M32R): M32R/D. (line 15)
32520 * find trace snapshot: tfind. (line 6)
32521 * finish: Continuing and Stepping.
32523 * finish&: Background Execution.
32525 * flinching: Messages/Warnings. (line 50)
32526 * float promotion: ABI. (line 29)
32527 * floating point: Floating Point Hardware.
32529 * floating point registers: Registers. (line 15)
32530 * floating point, MIPS remote: MIPS Embedded. (line 60)
32531 * flush: Basic Python. (line 60)
32532 * flush_i_cache: Bootstrapping. (line 60)
32533 * flushregs: Maintenance Commands.
32535 * focus: TUI Commands. (line 34)
32536 * focus of debugging: Threads. (line 45)
32537 * foo: Symbol Errors. (line 50)
32538 * foreground execution: Background Execution.
32540 * fork, debugging programs which call: Forks. (line 6)
32541 * format options: Print Settings. (line 6)
32542 * formatted output: Output Formats. (line 6)
32543 * Fortran: Summary. (line 35)
32544 * Fortran Defaults: Fortran Defaults. (line 6)
32545 * Fortran operators and expressions: Fortran Operators. (line 6)
32546 * Fortran-specific support in GDB: Fortran. (line 6)
32547 * forward-backward-delete-char (): Commands For Text. (line 15)
32548 * forward-char (C-f): Commands For Moving. (line 12)
32549 * forward-search: Search. (line 9)
32550 * forward-search-history (C-s): Commands For History.
32552 * forward-word (M-f): Commands For Moving. (line 18)
32553 * FR-V shared-library debugging: Debugging Output. (line 141)
32554 * frame debugging info: Debugging Output. (line 65)
32555 * frame number: Frames. (line 28)
32556 * frame pointer: Frames. (line 21)
32557 * frame pointer register: Registers. (line 26)
32558 * frame, command: Frames. (line 45)
32559 * frame, definition: Frames. (line 6)
32560 * frame, selecting: Selection. (line 11)
32561 * frame_stop_reason_string: Frames In Python. (line 26)
32562 * frameless execution: Frames. (line 34)
32563 * frames in python: Frames In Python. (line 6)
32564 * frames-invalid annotation: Invalidation. (line 9)
32565 * free memory information (MS-DOS): DJGPP Native. (line 19)
32566 * fstat, file-i/o system call: stat/fstat. (line 6)
32567 * ftrace: Create and Delete Tracepoints.
32569 * Fujitsu: Remote Stub. (line 69)
32570 * full symbol tables, listing GDB's internal: Symbols. (line 278)
32571 * Function: Functions In Python. (line 6)
32572 * function call arguments, optimized out: Backtrace. (line 71)
32573 * function entry/exit, wrong values of variables: Variables. (line 58)
32574 * functions without line info, and stepping: Continuing and Stepping.
32576 * G packet: Packets. (line 167)
32577 * g packet: Packets. (line 151)
32578 * g++, GNU C++ compiler: C. (line 10)
32579 * garbled pointers: DJGPP Native. (line 42)
32580 * GCC and C++: C Plus Plus Expressions.
32582 * gcore: Core File Generation.
32584 * GDB bugs, reporting: Bug Reporting. (line 6)
32585 * GDB internal error: Maintenance Commands.
32587 * gdb module: Basic Python. (line 6)
32588 * GDB reference card: Formatting Documentation.
32590 * GDB startup: Startup. (line 6)
32591 * GDB version number: Help. (line 126)
32592 * gdb.COMMAND_BREAKPOINTS: Commands In Python. (line 135)
32593 * gdb.COMMAND_DATA: Commands In Python. (line 105)
32594 * gdb.COMMAND_FILES: Commands In Python. (line 116)
32595 * gdb.COMMAND_MAINTENANCE: Commands In Python. (line 153)
32596 * gdb.COMMAND_NONE: Commands In Python. (line 95)
32597 * gdb.COMMAND_OBSCURE: Commands In Python. (line 147)
32598 * gdb.COMMAND_RUNNING: Commands In Python. (line 99)
32599 * gdb.COMMAND_STACK: Commands In Python. (line 110)
32600 * gdb.COMMAND_STATUS: Commands In Python. (line 129)
32601 * gdb.COMMAND_SUPPORT: Commands In Python. (line 122)
32602 * gdb.COMMAND_TRACEPOINTS: Commands In Python. (line 141)
32603 * gdb.COMPLETE_COMMAND: Commands In Python. (line 174)
32604 * gdb.COMPLETE_FILENAME: Commands In Python. (line 167)
32605 * gdb.COMPLETE_LOCATION: Commands In Python. (line 170)
32606 * gdb.COMPLETE_NONE: Commands In Python. (line 164)
32607 * gdb.COMPLETE_SYMBOL: Commands In Python. (line 178)
32608 * gdb.current_objfile: Objfiles In Python. (line 15)
32609 * gdb.execute: Basic Python. (line 11)
32610 * gdb.flush: Basic Python. (line 59)
32611 * gdb.Function: Functions In Python. (line 6)
32612 * gdb.history: Basic Python. (line 31)
32613 * gdb.ini: Startup. (line 45)
32614 * gdb.LazyString: Lazy Strings In Python.
32616 * gdb.lookup_type: Types In Python. (line 11)
32617 * gdb.Objfile: Objfiles In Python. (line 6)
32618 * gdb.objfiles: Objfiles In Python. (line 21)
32619 * gdb.parameter: Basic Python. (line 21)
32620 * gdb.parse_and_eval: Basic Python. (line 43)
32621 * gdb.selected_frame: Frames In Python. (line 21)
32622 * gdb.Type: Types In Python. (line 6)
32623 * gdb.TYPE_CODE_ARRAY: Types In Python. (line 142)
32624 * gdb.TYPE_CODE_BITSTRING: Types In Python. (line 180)
32625 * gdb.TYPE_CODE_BOOL: Types In Python. (line 201)
32626 * gdb.TYPE_CODE_CHAR: Types In Python. (line 198)
32627 * gdb.TYPE_CODE_COMPLEX: Types In Python. (line 204)
32628 * gdb.TYPE_CODE_DECFLOAT: Types In Python. (line 213)
32629 * gdb.TYPE_CODE_ENUM: Types In Python. (line 151)
32630 * gdb.TYPE_CODE_ERROR: Types In Python. (line 183)
32631 * gdb.TYPE_CODE_FLAGS: Types In Python. (line 154)
32632 * gdb.TYPE_CODE_FLT: Types In Python. (line 163)
32633 * gdb.TYPE_CODE_FUNC: Types In Python. (line 157)
32634 * gdb.TYPE_CODE_INT: Types In Python. (line 160)
32635 * gdb.TYPE_CODE_INTERNAL_FUNCTION: Types In Python. (line 216)
32636 * gdb.TYPE_CODE_MEMBERPTR: Types In Python. (line 192)
32637 * gdb.TYPE_CODE_METHOD: Types In Python. (line 186)
32638 * gdb.TYPE_CODE_METHODPTR: Types In Python. (line 189)
32639 * gdb.TYPE_CODE_NAMESPACE: Types In Python. (line 210)
32640 * gdb.TYPE_CODE_PTR: Types In Python. (line 139)
32641 * gdb.TYPE_CODE_RANGE: Types In Python. (line 172)
32642 * gdb.TYPE_CODE_REF: Types In Python. (line 195)
32643 * gdb.TYPE_CODE_SET: Types In Python. (line 169)
32644 * gdb.TYPE_CODE_STRING: Types In Python. (line 175)
32645 * gdb.TYPE_CODE_STRUCT: Types In Python. (line 145)
32646 * gdb.TYPE_CODE_TYPEDEF: Types In Python. (line 207)
32647 * gdb.TYPE_CODE_UNION: Types In Python. (line 148)
32648 * gdb.TYPE_CODE_VOID: Types In Python. (line 166)
32649 * gdb.Value: Values From Inferior.
32651 * gdb.write: Basic Python. (line 54)
32652 * GDB/MI development: GDB/MI Development and Front Ends.
32654 * GDB/MI General Design: GDB/MI General Design.
32656 * GDB/MI, async records: GDB/MI Async Records.
32658 * GDB/MI, breakpoint commands: GDB/MI Breakpoint Commands.
32660 * GDB/MI, compatibility with CLI: GDB/MI Compatibility with CLI.
32662 * GDB/MI, data manipulation: GDB/MI Data Manipulation.
32664 * GDB/MI, input syntax: GDB/MI Input Syntax. (line 6)
32665 * GDB/MI, its purpose: GDB/MI. (line 9)
32666 * GDB/MI, output syntax: GDB/MI Output Syntax.
32668 * GDB/MI, result records: GDB/MI Result Records.
32670 * GDB/MI, simple examples: GDB/MI Simple Examples.
32672 * GDB/MI, stream records: GDB/MI Stream Records.
32674 * gdbarch debugging info: Debugging Output. (line 18)
32675 * GDBHISTFILE, environment variable: Command History. (line 26)
32676 * gdbserver: Server. (line 6)
32677 * gdbserver, multiple processes: Server. (line 91)
32678 * gdbserver, search path for libthread_db: Server. (line 188)
32679 * GDT: DJGPP Native. (line 24)
32680 * generate-core-file: Core File Generation.
32682 * get thread-local storage address, remote request: General Query Packets.
32684 * getDebugChar: Bootstrapping. (line 14)
32685 * gettimeofday, file-i/o system call: gettimeofday. (line 6)
32686 * global debugging information directory: Separate Debug Files.
32688 * GNU C++: C. (line 10)
32689 * GNU Emacs: Emacs. (line 6)
32690 * GNU Hurd debugging: Hurd Native. (line 6)
32691 * GNU/Hurd debug messages: Debugging Output. (line 72)
32692 * GNU/Linux LWP async debug messages: Debugging Output. (line 94)
32693 * GNU/Linux LWP debug messages: Debugging Output. (line 87)
32694 * gnu_debuglink_crc32: Separate Debug Files.
32696 * h (help): Help. (line 9)
32697 * H packet: Packets. (line 178)
32698 * handle: Signals. (line 45)
32699 * handle_exception: Stub Contents. (line 15)
32700 * handling signals: Signals. (line 27)
32701 * hardware breakpoints: Set Breaks. (line 62)
32702 * hardware debug registers: Maintenance Commands.
32704 * hardware watchpoints: Set Watchpoints. (line 31)
32705 * hash mark while downloading: Target Commands. (line 99)
32706 * hbreak: Set Breaks. (line 62)
32707 * help: Help. (line 6)
32708 * help function: Convenience Vars. (line 98)
32709 * help target: Target Commands. (line 19)
32710 * help user-defined: Define. (line 66)
32711 * heuristic-fence-post (Alpha, MIPS): MIPS. (line 14)
32712 * history: Basic Python. (line 32)
32713 * history events: Event Designators. (line 7)
32714 * history expansion: History Interaction. (line 6)
32715 * history expansion, turn on/off: Command History. (line 53)
32716 * history file: Command History. (line 26)
32717 * history number: Value History. (line 13)
32718 * history of values printed by GDB: Value History. (line 6)
32719 * history size: Command History. (line 45)
32720 * history substitution: Command History. (line 26)
32721 * history-preserve-point: Readline Init File Syntax.
32723 * history-search-backward (): Commands For History.
32725 * history-search-forward (): Commands For History.
32727 * HISTSIZE, environment variable: Command History. (line 45)
32728 * hook: Hooks. (line 6)
32729 * hookpost: Hooks. (line 11)
32730 * hooks, for commands: Hooks. (line 6)
32731 * hooks, post-command: Hooks. (line 11)
32732 * hooks, pre-command: Hooks. (line 6)
32733 * horizontal-scroll-mode: Readline Init File Syntax.
32735 * host character set: Character Sets. (line 6)
32736 * Host I/O, remote protocol: Host I/O Packets. (line 6)
32737 * how many arguments (user-defined commands): Define. (line 25)
32738 * HPPA support: HPPA. (line 6)
32739 * htrace: OpenRISC 1000. (line 69)
32740 * hwatch: OpenRISC 1000. (line 59)
32741 * i (info): Help. (line 99)
32742 * I packet: Packets. (line 197)
32743 * i packet: Packets. (line 192)
32744 * i/o: Input/Output. (line 6)
32745 * I/O registers (Atmel AVR): AVR. (line 10)
32746 * i386: Remote Stub. (line 57)
32747 * i386-stub.c: Remote Stub. (line 57)
32748 * IDT: DJGPP Native. (line 24)
32749 * if: Command Files. (line 59)
32750 * ignore: Conditions. (line 77)
32751 * ignore count (of breakpoint): Conditions. (line 66)
32752 * INCLUDE_RDB: VxWorks. (line 33)
32753 * incomplete type: Symbols. (line 107)
32754 * indentation in structure display: Print Settings. (line 198)
32755 * inferior: Inferiors and Programs.
32757 * inferior debugging info: Debugging Output. (line 78)
32758 * inferior functions, calling: Calling. (line 6)
32759 * inferior INFNO: Inferiors and Programs.
32761 * inferior tty: Input/Output. (line 44)
32762 * infinite recursion in user-defined commands: Define. (line 76)
32763 * info: Help. (line 99)
32764 * info address: Symbols. (line 44)
32765 * info all-registers: Registers. (line 15)
32766 * info args: Frame Info. (line 51)
32767 * info auxv: OS Information. (line 33)
32768 * info breakpoints: Set Breaks. (line 117)
32769 * info catch: Frame Info. (line 60)
32770 * info checkpoints: Checkpoint/Restart. (line 31)
32771 * info classes: Symbols. (line 205)
32772 * info common: Special Fortran Commands.
32774 * info copying: Help. (line 136)
32775 * info dcache: Caching Remote Data. (line 34)
32776 * info display: Auto Display. (line 66)
32777 * info dll: Cygwin Native. (line 30)
32778 * info dos: DJGPP Native. (line 15)
32779 * info extensions: Show. (line 34)
32780 * info f (info frame): Frame Info. (line 17)
32781 * info files: Files. (line 191)
32782 * info float: Floating Point Hardware.
32784 * info for known object files: Maintenance Commands.
32786 * info frame: Frame Info. (line 17)
32787 * info frame, show the source language: Show. (line 15)
32788 * info functions: Symbols. (line 184)
32789 * info handle: Signals. (line 33)
32790 * info inferiors: Inferiors and Programs.
32792 * info io_registers, AVR: AVR. (line 10)
32793 * info line: Machine Code. (line 14)
32794 * info line, and Objective-C: Method Names in Commands.
32796 * info locals: Frame Info. (line 55)
32797 * info macro: Macros. (line 47)
32798 * info mem: Memory Region Attributes.
32800 * info meminfo: SVR4 Process Information.
32802 * info or1k spr: OpenRISC 1000. (line 20)
32803 * info os processes: OS Information. (line 47)
32804 * info pidlist: SVR4 Process Information.
32806 * info proc: SVR4 Process Information.
32808 * info program: Stopping. (line 18)
32809 * info record: Process Record and Replay.
32811 * info registers: Registers. (line 11)
32812 * info scope: Symbols. (line 138)
32813 * info selectors: Symbols. (line 211)
32814 * info serial: DJGPP Native. (line 142)
32815 * info set: Help. (line 119)
32816 * info share: Files. (line 326)
32817 * info sharedlibrary: Files. (line 326)
32818 * info signals: Signals. (line 33)
32819 * info source: Symbols. (line 159)
32820 * info source, show the source language: Show. (line 21)
32821 * info sources: Symbols. (line 178)
32822 * info spu: SPU. (line 10)
32823 * info stack: Backtrace. (line 34)
32824 * info symbol: Symbols. (line 54)
32825 * info target: Files. (line 191)
32826 * info task TASKNO: Ada Tasks. (line 89)
32827 * info tasks: Ada Tasks. (line 9)
32828 * info terminal: Input/Output. (line 12)
32829 * info threads: Threads. (line 66)
32830 * info threads (HP-UX): Threads. (line 103)
32831 * info tp: Listing Tracepoints. (line 6)
32832 * info tracepoints: Listing Tracepoints. (line 6)
32833 * info tvariables: Trace State Variables.
32835 * info types: Symbols. (line 124)
32836 * info udot: OS Information. (line 16)
32837 * info variables: Symbols. (line 196)
32838 * info vector: Vector Unit. (line 9)
32839 * info w32: Cygwin Native. (line 19)
32840 * info warranty: Help. (line 140)
32841 * info watchpoints [N]: Set Watchpoints. (line 64)
32842 * info win: TUI Commands. (line 12)
32843 * information about tracepoints: Listing Tracepoints. (line 6)
32844 * inheritance: Debugging C Plus Plus.
32846 * init file: Startup. (line 11)
32847 * init file name: Startup. (line 45)
32848 * init-if-undefined: Convenience Vars. (line 41)
32849 * initial frame: Frames. (line 12)
32850 * initialization file, readline: Readline Init File. (line 6)
32851 * inline functions, debugging: Inline Functions. (line 6)
32852 * innermost frame: Frames. (line 12)
32853 * input syntax for GDB/MI: GDB/MI Input Syntax. (line 6)
32854 * input-meta: Readline Init File Syntax.
32856 * insert-comment (M-#): Miscellaneous Commands.
32858 * insert-completions (M-*): Commands For Completion.
32860 * inspect: Data. (line 6)
32861 * installation: Installing GDB. (line 6)
32862 * instructions, assembly: Machine Code. (line 36)
32863 * integral datatypes, in file-i/o protocol: Integral Datatypes.
32865 * Intel: Remote Stub. (line 57)
32866 * Intel disassembly flavor: Machine Code. (line 107)
32867 * interaction, readline: Readline Interaction.
32869 * internal commands: Maintenance Commands.
32871 * internal errors, control of GDB behavior: Maintenance Commands.
32873 * internal GDB breakpoints: Set Breaks. (line 322)
32874 * interpreter-exec: Interpreters. (line 43)
32875 * interrupt <1>: Background Execution.
32877 * interrupt: Quitting GDB. (line 13)
32878 * interrupt debuggee on MS-Windows: Cygwin Native. (line 9)
32879 * interrupt remote programs: Remote Configuration.
32881 * interrupting remote programs: Connecting. (line 78)
32882 * interrupting remote targets: Bootstrapping. (line 25)
32883 * interrupts (remote protocol): Interrupts. (line 6)
32884 * invalid input: Bug Criteria. (line 16)
32885 * invoke another interpreter: Interpreters. (line 37)
32886 * invoke on Command: Commands In Python. (line 50)
32887 * invoke on Function: Functions In Python. (line 21)
32888 * is_optimized_out: Values From Inferior.
32890 * is_valid on Frame: Frames In Python. (line 33)
32891 * isatty, file-i/o system call: isatty. (line 6)
32892 * isearch-terminators: Readline Init File Syntax.
32894 * JIT compilation interface: JIT Interface. (line 6)
32895 * jump: Jumping. (line 10)
32896 * jump, and Objective-C: Method Names in Commands.
32898 * just-in-time compilation: JIT Interface. (line 6)
32899 * k packet: Packets. (line 201)
32900 * kernel crash dump: BSD libkvm Interface.
32902 * kernel memory image: BSD libkvm Interface.
32904 * keymap: Readline Init File Syntax.
32906 * kill: Kill Process. (line 6)
32907 * kill inferior INFNO: Inferiors and Programs.
32909 * kill ring: Readline Killing Commands.
32911 * kill-line (C-k): Commands For Killing.
32913 * kill-region (): Commands For Killing.
32915 * kill-whole-line (): Commands For Killing.
32917 * kill-word (M-d): Commands For Killing.
32919 * killing text: Readline Killing Commands.
32921 * kvm: BSD libkvm Interface.
32923 * l (list): List. (line 6)
32924 * languages: Languages. (line 6)
32925 * last tracepoint number: Create and Delete Tracepoints.
32927 * latest breakpoint: Set Breaks. (line 6)
32928 * layout: TUI Commands. (line 15)
32929 * lazy strings in python: Lazy Strings In Python.
32931 * lazy_string on Value: Values From Inferior.
32933 * LDT: DJGPP Native. (line 24)
32934 * leaving GDB: Quitting GDB. (line 6)
32935 * Left: TUI Keys. (line 59)
32936 * length: Lazy Strings In Python.
32938 * libkvm: BSD libkvm Interface.
32940 * library list format, remote protocol: Library List Format. (line 6)
32941 * limit hardware breakpoints and watchpoints: Remote Configuration.
32943 * limit on number of printed array elements: Print Settings. (line 123)
32944 * limits, in file-i/o protocol: Limits. (line 6)
32945 * linespec: Specify Location. (line 6)
32946 * Linux lightweight processes: Debugging Output. (line 87)
32947 * list: List. (line 6)
32948 * list active threads, remote request: General Query Packets.
32950 * list of supported file-i/o calls: List of Supported Calls.
32952 * list output in GDB/MI: GDB/MI Output Syntax.
32954 * list, and Objective-C: Method Names in Commands.
32956 * list, how many lines to display: List. (line 30)
32957 * listing GDB's internal symbol tables: Symbols. (line 278)
32958 * listing machine instructions: Machine Code. (line 36)
32959 * listing mapped overlays: Overlay Commands. (line 60)
32960 * load address, overlay's: How Overlays Work. (line 6)
32961 * load FILENAME: Target Commands. (line 115)
32962 * load shared library: Files. (line 323)
32963 * load symbols from memory: Files. (line 162)
32964 * local variables: Symbols. (line 138)
32965 * locate address: Output Formats. (line 35)
32966 * lock scheduler: All-Stop Mode. (line 37)
32967 * log output in GDB/MI: GDB/MI Output Syntax.
32969 * logging file name: Logging Output. (line 13)
32970 * logging GDB output: Logging Output. (line 6)
32971 * lookup_type: Types In Python. (line 12)
32972 * loop_break: Command Files. (line 78)
32973 * loop_continue: Command Files. (line 82)
32974 * lseek flags, in file-i/o protocol: Lseek Flags. (line 6)
32975 * lseek, file-i/o system call: lseek. (line 6)
32976 * M packet: Packets. (line 228)
32977 * m packet: Packets. (line 208)
32978 * M32-EVA target board address: M32R/D. (line 21)
32979 * M32R/Chaos debugging: M32R/D. (line 50)
32980 * m680x0: Remote Stub. (line 60)
32981 * m68k-stub.c: Remote Stub. (line 60)
32982 * machine instructions: Machine Code. (line 36)
32983 * macro define: Macros. (line 52)
32984 * macro definition, showing: Macros. (line 47)
32985 * macro exp1: Macros. (line 36)
32986 * macro expand: Macros. (line 29)
32987 * macro expansion, showing the results of preprocessor: Macros.
32989 * macro list: Macros. (line 73)
32990 * macro undef: Macros. (line 67)
32991 * macros, example of debugging with: Macros. (line 76)
32992 * macros, user-defined: Macros. (line 52)
32993 * mailing lists: GDB/MI Development and Front Ends.
32995 * maint agent: Maintenance Commands.
32997 * maint agent-eval: Maintenance Commands.
32999 * maint check-symtabs: Maintenance Commands.
33001 * maint cplus first_component: Maintenance Commands.
33003 * maint cplus namespace: Maintenance Commands.
33005 * maint demangle: Maintenance Commands.
33007 * maint deprecate: Maintenance Commands.
33009 * maint dump-me: Maintenance Commands.
33011 * maint info breakpoints: Maintenance Commands.
33013 * maint info program-spaces: Inferiors and Programs.
33015 * maint info psymtabs: Symbols. (line 278)
33016 * maint info sections: Files. (line 200)
33017 * maint info sol-threads: Threads. (line 133)
33018 * maint info symtabs: Symbols. (line 278)
33019 * maint internal-error: Maintenance Commands.
33021 * maint internal-warning: Maintenance Commands.
33023 * maint packet: Maintenance Commands.
33025 * maint print architecture: Maintenance Commands.
33027 * maint print c-tdesc: Maintenance Commands.
33029 * maint print cooked-registers: Maintenance Commands.
33031 * maint print dummy-frames: Maintenance Commands.
33033 * maint print objfiles: Maintenance Commands.
33035 * maint print psymbols: Symbols. (line 259)
33036 * maint print raw-registers: Maintenance Commands.
33038 * maint print reggroups: Maintenance Commands.
33040 * maint print register-groups: Maintenance Commands.
33042 * maint print registers: Maintenance Commands.
33044 * maint print statistics: Maintenance Commands.
33046 * maint print symbols: Symbols. (line 259)
33047 * maint print target-stack: Maintenance Commands.
33049 * maint print type: Maintenance Commands.
33051 * maint print unwind, HPPA: HPPA. (line 17)
33052 * maint set dwarf2 max-cache-age: Maintenance Commands.
33054 * maint set internal-error: Maintenance Commands.
33056 * maint set internal-warning: Maintenance Commands.
33058 * maint set profile: Maintenance Commands.
33060 * maint set python auto-load: Auto-loading. (line 34)
33061 * maint set python print-stack: Python Commands. (line 31)
33062 * maint set show-debug-regs: Maintenance Commands.
33064 * maint show dwarf2 max-cache-age: Maintenance Commands.
33066 * maint show internal-error: Maintenance Commands.
33068 * maint show internal-warning: Maintenance Commands.
33070 * maint show profile: Maintenance Commands.
33072 * maint show show-debug-regs: Maintenance Commands.
33074 * maint space: Maintenance Commands.
33076 * maint time: Maintenance Commands.
33078 * maint translate-address: Maintenance Commands.
33080 * maint undeprecate: Maintenance Commands.
33082 * maintenance commands: Maintenance Commands.
33084 * make: Shell Commands. (line 19)
33085 * manual overlay debugging: Overlay Commands. (line 23)
33086 * map an overlay: Overlay Commands. (line 30)
33087 * mapinfo list, QNX Neutrino: SVR4 Process Information.
33089 * mapped address: How Overlays Work. (line 6)
33090 * mapped overlays: How Overlays Work. (line 6)
33091 * mark-modified-lines: Readline Init File Syntax.
33093 * mark-symlinked-directories: Readline Init File Syntax.
33095 * match-hidden-files: Readline Init File Syntax.
33097 * maximum value for offset of closest symbol: Print Settings. (line 70)
33098 * mem: Memory Region Attributes.
33100 * member functions: C Plus Plus Expressions.
33102 * memory address space mappings: SVR4 Process Information.
33104 * memory map format: Memory Map Format. (line 6)
33105 * memory region attributes: Memory Region Attributes.
33107 * memory tracing: Breakpoints. (line 20)
33108 * memory transfer, in file-i/o protocol: Memory Transfer. (line 6)
33109 * memory used by commands: Maintenance Commands.
33111 * memory used for symbol tables: Files. (line 311)
33112 * memory, alignment and size of remote accesses: Packets. (line 215)
33113 * memory, viewing as typed object: Expressions. (line 43)
33114 * memset: Bootstrapping. (line 70)
33115 * menu-complete (): Commands For Completion.
33117 * meta-flag: Readline Init File Syntax.
33119 * mi interpreter: Interpreters. (line 26)
33120 * mi1 interpreter: Interpreters. (line 34)
33121 * mi2 interpreter: Interpreters. (line 31)
33122 * minimal language: Unsupported Languages.
33124 * Minimal symbols and DLLs: Non-debug DLL Symbols.
33126 * MIPS addresses, masking: MIPS. (line 61)
33127 * MIPS boards: MIPS Embedded. (line 6)
33128 * MIPS remote floating point: MIPS Embedded. (line 60)
33129 * MIPS stack: MIPS. (line 6)
33130 * miscellaneous settings: Other Misc Settings. (line 6)
33131 * MMX registers (x86): Registers. (line 71)
33132 * mode_t values, in file-i/o protocol: mode_t Values. (line 6)
33133 * Modula-2: Summary. (line 27)
33134 * Modula-2 built-ins: Built-In Func/Proc. (line 6)
33135 * Modula-2 checks: M2 Checks. (line 6)
33136 * Modula-2 constants: Built-In Func/Proc. (line 112)
33137 * Modula-2 defaults: M2 Defaults. (line 6)
33138 * Modula-2 operators: M2 Operators. (line 6)
33139 * Modula-2 types: M2 Types. (line 6)
33140 * Modula-2, deviations from: Deviations. (line 6)
33141 * Modula-2, GDB support: Modula-2. (line 6)
33142 * monitor: Connecting. (line 105)
33143 * monitor commands, for gdbserver: Server. (line 171)
33144 * Motorola 680x0: Remote Stub. (line 60)
33145 * MS Windows debugging: Cygwin Native. (line 6)
33146 * MS-DOS system info: DJGPP Native. (line 19)
33147 * MS-DOS-specific commands: DJGPP Native. (line 6)
33148 * multiple locations, breakpoints: Set Breaks. (line 179)
33149 * multiple processes: Forks. (line 6)
33150 * multiple processes with gdbserver: Server. (line 91)
33151 * multiple targets: Active Targets. (line 6)
33152 * multiple threads: Threads. (line 6)
33153 * multiple threads, backtrace: Backtrace. (line 37)
33154 * multiple-symbols menu: Ambiguous Expressions.
33156 * multiprocess extensions, in remote protocol: General Query Packets.
33158 * n (next): Continuing and Stepping.
33160 * n (SingleKey TUI key): TUI Single Key Mode. (line 19)
33161 * name on Frame: Frames In Python. (line 40)
33162 * names of symbols: Symbols. (line 14)
33163 * namespace in C++: C Plus Plus Expressions.
33165 * native Cygwin debugging: Cygwin Native. (line 6)
33166 * native DJGPP debugging: DJGPP Native. (line 6)
33167 * negative breakpoint numbers: Set Breaks. (line 322)
33168 * NetROM ROM emulator target: Target Commands. (line 88)
33169 * New SYSTAG message: Threads. (line 51)
33170 * New SYSTAG message, on HP-UX: Threads. (line 93)
33171 * newer on Frame: Frames In Python. (line 61)
33172 * next: Continuing and Stepping.
33174 * next&: Background Execution.
33176 * next-history (C-n): Commands For History.
33178 * nexti: Continuing and Stepping.
33180 * nexti&: Background Execution.
33182 * ni (nexti): Continuing and Stepping.
33184 * non-incremental-forward-search-history (M-n): Commands For History.
33186 * non-incremental-reverse-search-history (M-p): Commands For History.
33188 * non-member C++ functions, set breakpoint in: Set Breaks. (line 108)
33189 * non-stop mode: Non-Stop Mode. (line 6)
33190 * non-stop mode, and breakpoint always-inserted: Set Breaks. (line 315)
33191 * non-stop mode, and process record and replay: Process Record and Replay.
33193 * non-stop mode, and set displaced-stepping: Maintenance Commands.
33195 * non-stop mode, remote request: General Query Packets.
33197 * noninvasive task options: Hurd Native. (line 73)
33198 * nosharedlibrary: Files. (line 341)
33199 * notation, readline: Readline Bare Essentials.
33201 * notational conventions, for GDB/MI: GDB/MI. (line 25)
33202 * notification packets: Notification Packets.
33204 * notify output in GDB/MI: GDB/MI Output Syntax.
33206 * NULL elements in arrays: Print Settings. (line 189)
33207 * number of array elements to print: Print Settings. (line 123)
33208 * number representation: Numbers. (line 6)
33209 * numbers for breakpoints: Breakpoints. (line 41)
33210 * object files, relocatable, reading symbols from: Files. (line 132)
33211 * Objective-C: Objective-C. (line 6)
33212 * Objective-C, classes and selectors: Symbols. (line 205)
33213 * Objective-C, print objects: The Print Command with Objective-C.
33215 * Objfile: Objfiles In Python. (line 6)
33216 * objfiles: Objfiles In Python. (line 22)
33217 * objfiles in python: Objfiles In Python. (line 6)
33218 * observer debugging info: Debugging Output. (line 101)
33219 * octal escapes in strings: Print Settings. (line 222)
33220 * older on Frame: Frames In Python. (line 58)
33221 * online documentation: Help. (line 6)
33222 * opaque data types: Symbols. (line 241)
33223 * open flags, in file-i/o protocol: Open Flags. (line 6)
33224 * open, file-i/o system call: open. (line 6)
33225 * OpenRISC 1000: OpenRISC 1000. (line 6)
33226 * OpenRISC 1000 htrace: OpenRISC 1000. (line 58)
33227 * operating system information: Operating System Information.
33229 * operating system information, process list: Process list. (line 6)
33230 * optimized code, debugging: Optimized Code. (line 6)
33231 * optimized code, wrong values of variables: Variables. (line 58)
33232 * optimized out value in Python: Values From Inferior.
33234 * optional debugging messages: Debugging Output. (line 6)
33235 * optional warnings: Messages/Warnings. (line 6)
33236 * or1k boards: OpenRISC 1000. (line 6)
33237 * or1ksim: OpenRISC 1000. (line 16)
33238 * OS ABI: ABI. (line 11)
33239 * OS information: OS Information. (line 6)
33240 * out-of-line single-stepping: Maintenance Commands.
33242 * outermost frame: Frames. (line 12)
33243 * output: Output. (line 35)
33244 * output formats: Output Formats. (line 6)
33245 * output syntax of GDB/MI: GDB/MI Output Syntax.
33247 * output-meta: Readline Init File Syntax.
33249 * overlay: Overlay Commands. (line 17)
33250 * overlay area: How Overlays Work. (line 6)
33251 * overlay example program: Overlay Sample Program.
33253 * overlays: Overlays. (line 6)
33254 * overlays, setting breakpoints in: Overlay Commands. (line 93)
33255 * overload-choice annotation: Prompting. (line 32)
33256 * overloaded functions, calling: C Plus Plus Expressions.
33258 * overloaded functions, overload resolution: Debugging C Plus Plus.
33260 * overloading in C++: Debugging C Plus Plus.
33262 * overwrite-mode (): Commands For Text. (line 53)
33263 * P packet: Packets. (line 256)
33264 * p packet: Packets. (line 241)
33265 * packet acknowledgment, for GDB remote: Packet Acknowledgment.
33267 * packet size, remote protocol: General Query Packets.
33269 * packets, notification: Notification Packets.
33271 * packets, reporting on stdout: Debugging Output. (line 123)
33272 * packets, tracepoint: Tracepoint Packets. (line 6)
33273 * page tables display (MS-DOS): DJGPP Native. (line 56)
33274 * page-completions: Readline Init File Syntax.
33276 * parameter: Basic Python. (line 22)
33277 * parse_and_eval: Basic Python. (line 44)
33278 * partial symbol dump: Symbols. (line 259)
33279 * partial symbol tables, listing GDB's internal: Symbols. (line 278)
33280 * Pascal: Summary. (line 30)
33281 * Pascal objects, static members display: Print Settings. (line 353)
33282 * Pascal support in GDB, limitations: Pascal. (line 6)
33283 * pass signals to inferior, remote request: General Query Packets.
33285 * passcount: Tracepoint Passcounts.
33287 * patching binaries: Patching. (line 6)
33288 * patching object files: Files. (line 26)
33289 * path: Environment. (line 14)
33290 * pause current task (GNU Hurd): Hurd Native. (line 49)
33291 * pause current thread (GNU Hurd): Hurd Native. (line 91)
33292 * pauses in output: Screen Size. (line 6)
33293 * pc on Frame: Frames In Python. (line 55)
33294 * pending breakpoints: Set Breaks. (line 221)
33295 * PgDn: TUI Keys. (line 50)
33296 * PgUp: TUI Keys. (line 47)
33297 * physical address from linear address: DJGPP Native. (line 81)
33298 * pipe, target remote to: Connecting. (line 60)
33299 * pipes: Starting. (line 62)
33300 * pmon, MIPS remote: MIPS Embedded. (line 132)
33301 * po (print-object): The Print Command with Objective-C.
33303 * pointer on Type: Types In Python. (line 102)
33304 * pointer values, in file-i/o protocol: Pointer Values. (line 6)
33305 * pointer, finding referent: Print Settings. (line 79)
33306 * port rights, GNU Hurd: Hurd Native. (line 85)
33307 * port sets, GNU Hurd: Hurd Native. (line 85)
33308 * possible-completions (M-?): Commands For Completion.
33310 * post-commands annotation: Prompting. (line 27)
33311 * post-overload-choice annotation: Prompting. (line 32)
33312 * post-prompt annotation: Prompting. (line 24)
33313 * post-prompt-for-continue annotation: Prompting. (line 40)
33314 * post-query annotation: Prompting. (line 36)
33315 * PowerPC architecture: PowerPC. (line 6)
33316 * pre-commands annotation: Prompting. (line 27)
33317 * pre-overload-choice annotation: Prompting. (line 32)
33318 * pre-prompt annotation: Prompting. (line 24)
33319 * pre-prompt-for-continue annotation: Prompting. (line 40)
33320 * pre-query annotation: Prompting. (line 36)
33321 * prefix for data files: Data Files. (line 6)
33322 * prefix for shared library file names: Files. (line 374)
33323 * prefix-meta (<ESC>): Miscellaneous Commands.
33325 * premature return from system calls: Interrupted System Calls.
33327 * preprocessor macro expansion, showing the results of: Macros.
33329 * pretty print arrays: Print Settings. (line 98)
33330 * pretty print C++ virtual function tables: Print Settings. (line 364)
33331 * pretty_printers: Objfiles In Python. (line 32)
33332 * previous-history (C-p): Commands For History.
33334 * print: Data. (line 6)
33335 * print all frame argument values: Print Settings. (line 135)
33336 * print an Objective-C object description: The Print Command with Objective-C.
33338 * print array indexes: Print Settings. (line 108)
33339 * print frame argument values for scalars only: Print Settings.
33341 * print messages on inferior start and exit: Inferiors and Programs.
33343 * print messages on thread start and exit: Threads. (line 159)
33344 * print settings: Print Settings. (line 6)
33345 * print structures in indented form: Print Settings. (line 198)
33346 * print-object: The Print Command with Objective-C.
33348 * print/don't print memory addresses: Print Settings. (line 13)
33349 * printf: Output. (line 46)
33350 * printing byte arrays: Output Formats. (line 60)
33351 * printing data: Data. (line 6)
33352 * printing frame argument values: Print Settings. (line 135)
33353 * printing strings: Output Formats. (line 60)
33354 * proc-trace-entry: SVR4 Process Information.
33356 * proc-trace-exit: SVR4 Process Information.
33358 * proc-untrace-entry: SVR4 Process Information.
33360 * proc-untrace-exit: SVR4 Process Information.
33362 * process detailed status information: SVR4 Process Information.
33364 * process ID: SVR4 Process Information.
33366 * process info via /proc: SVR4 Process Information.
33368 * process list, QNX Neutrino: SVR4 Process Information.
33370 * process record and replay: Process Record and Replay.
33372 * process status register: Registers. (line 26)
33373 * processes, multiple: Forks. (line 6)
33374 * procfs API calls: SVR4 Process Information.
33376 * profiling GDB: Maintenance Commands.
33378 * program counter register: Registers. (line 26)
33379 * program entry point: Backtrace. (line 93)
33380 * programming in python: Python API. (line 6)
33381 * prompt: Prompt. (line 6)
33382 * prompt annotation: Prompting. (line 24)
33383 * prompt-for-continue annotation: Prompting. (line 40)
33384 * protocol basics, file-i/o: Protocol Basics. (line 6)
33385 * protocol, GDB remote serial: Overview. (line 14)
33386 * protocol-specific representation of datatypes, in file-i/o protocol: Protocol-specific Representation of Datatypes.
33388 * ptrace system call: OS Information. (line 9)
33389 * ptype: Symbols. (line 85)
33390 * putDebugChar: Bootstrapping. (line 20)
33391 * pwd: Working Directory. (line 19)
33392 * python: Python Commands. (line 9)
33393 * python api: Python API. (line 6)
33394 * python commands <1>: Commands In Python. (line 6)
33395 * python commands: Python Commands. (line 6)
33396 * python convenience functions: Functions In Python. (line 6)
33397 * python exceptions: Exception Handling. (line 6)
33398 * python functions: Basic Python. (line 6)
33399 * python module: Basic Python. (line 6)
33400 * python pagination: Python API. (line 6)
33401 * python scripting: Python. (line 6)
33402 * python stdout: Python API. (line 6)
33403 * Python, working with types: Types In Python. (line 6)
33404 * python, working with values from inferior: Values From Inferior.
33406 * q (quit): Quitting GDB. (line 6)
33407 * q (SingleKey TUI key): TUI Single Key Mode. (line 22)
33408 * Q packet: Packets. (line 269)
33409 * q packet: Packets. (line 269)
33410 * qAttached packet: General Query Packets.
33412 * qC packet: General Query Packets.
33414 * qCRC packet: General Query Packets.
33416 * qfThreadInfo packet: General Query Packets.
33418 * qGetTLSAddr packet: General Query Packets.
33420 * QNonStop packet: General Query Packets.
33422 * QNX Neutrino: Neutrino. (line 6)
33423 * qOffsets packet: General Query Packets.
33425 * qP packet: General Query Packets.
33427 * QPassSignals packet: General Query Packets.
33429 * qRcmd packet: General Query Packets.
33431 * qSearch:memory packet: General Query Packets.
33433 * QStartNoAckMode packet: General Query Packets.
33435 * qsThreadInfo packet: General Query Packets.
33437 * qSupported packet: General Query Packets.
33439 * qSymbol packet: General Query Packets.
33441 * QTDV packet: Tracepoint Packets. (line 90)
33442 * qThreadExtraInfo packet: General Query Packets.
33444 * qTV packet: Tracepoint Packets. (line 174)
33445 * query annotation: Prompting. (line 36)
33446 * query attached, remote request: General Query Packets.
33448 * quit [EXPRESSION]: Quitting GDB. (line 6)
33449 * quit annotation: Errors. (line 6)
33450 * quoted-insert (C-q or C-v): Commands For Text. (line 20)
33451 * quotes in commands: Completion. (line 57)
33452 * quoting Ada internal identifiers: Additions to Ada. (line 76)
33453 * quoting names: Symbols. (line 14)
33454 * qXfer packet: General Query Packets.
33456 * r (run): Starting. (line 6)
33457 * r (SingleKey TUI key): TUI Single Key Mode. (line 25)
33458 * R packet: Packets. (line 278)
33459 * r packet: Packets. (line 273)
33460 * raise exceptions: Set Catchpoints. (line 197)
33461 * range checking: Type Checking. (line 65)
33462 * range on Type: Types In Python. (line 92)
33463 * ranges of breakpoints: Breakpoints. (line 48)
33464 * raw printing: Output Formats. (line 70)
33465 * rbreak: Set Breaks. (line 92)
33466 * rc (reverse-continue): Reverse Execution. (line 30)
33467 * RDI heartbeat: ARM. (line 112)
33468 * rdilogenable: ARM. (line 95)
33469 * rdilogfile: ARM. (line 89)
33470 * re-read-init-file (C-x C-r): Miscellaneous Commands.
33472 * read special object, remote request: General Query Packets.
33474 * read, file-i/o system call: read. (line 6)
33475 * read-only sections: Files. (line 258)
33476 * read_var on Frame: Frames In Python. (line 64)
33477 * reading symbols from relocatable object files: Files. (line 132)
33478 * reading symbols immediately: Files. (line 90)
33479 * readline: Editing. (line 6)
33480 * readnow: Files. (line 90)
33481 * rec: Process Record and Replay.
33483 * rec del: Process Record and Replay.
33485 * rec s: Process Record and Replay.
33487 * receive rights, GNU Hurd: Hurd Native. (line 85)
33488 * recent tracepoint number: Create and Delete Tracepoints.
33490 * record: Process Record and Replay.
33492 * record aggregates (Ada): Omissions from Ada. (line 44)
33493 * record delete: Process Record and Replay.
33495 * record mode: Process Record and Replay.
33497 * record serial communications on file: Remote Configuration.
33499 * record stop: Process Record and Replay.
33501 * recording a session script: Bug Reporting. (line 104)
33502 * recording inferior's execution and replaying it: Process Record and Replay.
33504 * redirection: Input/Output. (line 6)
33505 * redraw-current-line (): Commands For Moving. (line 30)
33506 * reference card: Formatting Documentation.
33508 * reference declarations: C Plus Plus Expressions.
33510 * reference on Type: Types In Python. (line 98)
33511 * refresh: TUI Commands. (line 52)
33512 * register stack, AMD29K: A29K. (line 6)
33513 * registers: Registers. (line 6)
33514 * regs, Super-H: Super-H. (line 9)
33515 * regular expression: Set Breaks. (line 92)
33516 * reloading symbols: Symbols. (line 217)
33517 * reloading the overlay table: Overlay Commands. (line 52)
33518 * relocatable object files, reading symbols from: Files. (line 132)
33519 * remote connection without stubs: Server. (line 6)
33520 * remote debugging: Remote Debugging. (line 6)
33521 * remote delete: File Transfer. (line 23)
33522 * remote get: File Transfer. (line 19)
33523 * remote memory comparison: Memory. (line 115)
33524 * remote monitor prompt: MIPS Embedded. (line 107)
33525 * remote packets, enabling and disabling: Remote Configuration.
33527 * remote programs, interrupting: Connecting. (line 78)
33528 * remote protocol debugging: Debugging Output. (line 123)
33529 * remote protocol, binary data: Overview. (line 61)
33530 * remote protocol, field separator: Overview. (line 53)
33531 * remote put: File Transfer. (line 15)
33532 * remote query requests: General Query Packets.
33534 * remote serial debugging summary: Debug Session. (line 6)
33535 * remote serial debugging, overview: Remote Stub. (line 14)
33536 * remote serial protocol: Overview. (line 14)
33537 * remote serial stub: Stub Contents. (line 6)
33538 * remote serial stub list: Remote Stub. (line 54)
33539 * remote serial stub, initialization: Stub Contents. (line 10)
33540 * remote serial stub, main routine: Stub Contents. (line 15)
33541 * remote stub, example: Remote Stub. (line 6)
33542 * remote stub, support routines: Bootstrapping. (line 6)
33543 * remote target: Target Commands. (line 58)
33544 * remote target, file transfer: File Transfer. (line 6)
33545 * remote target, limit break- and watchpoints: Remote Configuration.
33547 * remote timeout: Remote Configuration.
33549 * remotetimeout: Sparclet. (line 12)
33550 * remove actions from a tracepoint: Tracepoint Actions. (line 17)
33551 * remove-inferior: Inferiors and Programs.
33553 * rename, file-i/o system call: rename. (line 6)
33554 * Renesas: Remote Stub. (line 63)
33555 * repeated array elements: Print Settings. (line 176)
33556 * repeating command sequences: Command Syntax. (line 42)
33557 * repeating commands: Command Syntax. (line 21)
33558 * replay log events, remote reply: Stop Reply Packets. (line 61)
33559 * replay mode: Process Record and Replay.
33561 * reporting bugs in GDB: GDB Bugs. (line 6)
33562 * reprint the last value: Data. (line 21)
33563 * reset SDI connection, M32R: M32R/D. (line 44)
33564 * response time, MIPS debugging: MIPS. (line 10)
33565 * restart: Checkpoint/Restart. (line 6)
33566 * restart CHECKPOINT-ID: Checkpoint/Restart. (line 44)
33567 * restore: Dump/Restore Files. (line 41)
33568 * restore data from a file: Dump/Restore Files. (line 6)
33569 * result records in GDB/MI: GDB/MI Result Records.
33571 * resume threads of multiple processes simultaneously: All-Stop Mode.
33573 * resuming execution: Continuing and Stepping.
33575 * RET (repeat last command): Command Syntax. (line 21)
33576 * retransmit-timeout, MIPS protocol: MIPS Embedded. (line 83)
33577 * return: Returning. (line 6)
33578 * returning from a function: Returning. (line 6)
33579 * reverse execution: Reverse Execution. (line 6)
33580 * reverse-continue: Reverse Execution. (line 30)
33581 * reverse-finish: Reverse Execution. (line 77)
33582 * reverse-next: Reverse Execution. (line 60)
33583 * reverse-nexti: Reverse Execution. (line 69)
33584 * reverse-search: Search. (line 16)
33585 * reverse-search-history (C-r): Commands For History.
33587 * reverse-step: Reverse Execution. (line 37)
33588 * reverse-stepi: Reverse Execution. (line 52)
33589 * revert-line (M-r): Miscellaneous Commands.
33591 * rewind program state: Checkpoint/Restart. (line 6)
33592 * Right: TUI Keys. (line 62)
33593 * rn (reverse-next): Reverse Execution. (line 60)
33594 * rni (reverse-nexti): Reverse Execution. (line 69)
33595 * ROM at zero address, RDI: ARM. (line 102)
33596 * rs (step): Reverse Execution. (line 37)
33597 * rsi (reverse-stepi): Reverse Execution. (line 52)
33598 * run: Starting. (line 6)
33599 * run to main procedure: Starting. (line 79)
33600 * run until specified location: Continuing and Stepping.
33602 * run&: Background Execution.
33604 * running: Starting. (line 6)
33605 * running and debugging Sparclet programs: Sparclet Execution.
33607 * running programs backward: Reverse Execution. (line 6)
33608 * running VxWorks tasks: VxWorks Attach. (line 6)
33609 * running, on Sparclet: Sparclet. (line 28)
33610 * rwatch: Set Watchpoints. (line 56)
33611 * s (SingleKey TUI key): TUI Single Key Mode. (line 28)
33612 * s (step): Continuing and Stepping.
33614 * S packet: Packets. (line 291)
33615 * s packet: Packets. (line 285)
33616 * save command history: Command History. (line 36)
33617 * save GDB output to a file: Logging Output. (line 6)
33618 * save tracepoints for future sessions: save-tracepoints. (line 6)
33619 * save-tracepoints: save-tracepoints. (line 6)
33620 * scheduler locking mode: All-Stop Mode. (line 37)
33621 * scope: M2 Scope. (line 6)
33622 * scripting commands: Command Files. (line 6)
33623 * scripting with python: Python. (line 6)
33624 * sdireset: M32R/D. (line 44)
33625 * sdistatus: M32R/D. (line 47)
33626 * SDS protocol: PowerPC Embedded. (line 34)
33627 * sds, a command: PowerPC Embedded. (line 45)
33628 * search: Search. (line 9)
33629 * search path for libthread_db: Threads. (line 180)
33630 * searching memory: Searching Memory. (line 6)
33631 * searching memory, in remote debugging: General Query Packets.
33633 * searching source files: Search. (line 6)
33634 * section: Files. (line 182)
33635 * section offsets, remote request: General Query Packets.
33637 * segment descriptor tables: DJGPP Native. (line 24)
33638 * select Ctrl-C, BREAK or BREAK-g: Remote Configuration.
33640 * select trace snapshot: tfind. (line 6)
33641 * select-frame: Frames. (line 51)
33642 * selected frame: Stack. (line 19)
33643 * selected_frame: Frames In Python. (line 22)
33644 * selecting frame silently: Frames. (line 51)
33645 * self-insert (a, b, A, 1, !, ...): Commands For Text. (line 27)
33646 * send command to remote monitor: Connecting. (line 105)
33647 * send command to simulator: Embedded Processors. (line 9)
33648 * send interrupt-sequence on start: Remote Configuration.
33650 * send PMON command: MIPS Embedded. (line 132)
33651 * send rights, GNU Hurd: Hurd Native. (line 85)
33652 * sending files to remote systems: File Transfer. (line 6)
33653 * separate debugging information files: Separate Debug Files.
33655 * sequence-id, for GDB remote: Overview. (line 29)
33656 * serial connections, debugging: Debugging Output. (line 123)
33657 * serial line, target remote: Connecting. (line 18)
33658 * serial protocol, GDB remote: Overview. (line 14)
33659 * server prefix: Server Prefix. (line 6)
33660 * server, command prefix: Command History. (line 20)
33661 * set: Help. (line 107)
33662 * set ABI for MIPS: MIPS. (line 32)
33663 * set ada trust-PAD-over-XVS: Ada Glitches. (line 48)
33664 * set annotate: Annotations Overview.
33666 * set architecture: Targets. (line 21)
33667 * set args: Arguments. (line 21)
33668 * set arm: ARM. (line 18)
33669 * set auto-solib-add: Files. (line 303)
33670 * set backtrace: Backtrace. (line 104)
33671 * set board-address: M32R/D. (line 21)
33672 * set breakpoint always-inserted: Set Breaks. (line 303)
33673 * set breakpoint auto-hw: Set Breaks. (line 283)
33674 * set breakpoint pending: Set Breaks. (line 252)
33675 * set breakpoints in many functions: Set Breaks. (line 92)
33676 * set breakpoints on all functions: Set Breaks. (line 112)
33677 * set can-use-hw-watchpoints: Set Watchpoints. (line 83)
33678 * set case-sensitive: Symbols. (line 27)
33679 * set charset: Character Sets. (line 46)
33680 * set check range: Range Checking. (line 34)
33681 * set check type: Type Checking. (line 42)
33682 * set coerce-float-to-double: ABI. (line 41)
33683 * set com1base: DJGPP Native. (line 125)
33684 * set com1irq: DJGPP Native. (line 125)
33685 * set com2base: DJGPP Native. (line 125)
33686 * set com2irq: DJGPP Native. (line 125)
33687 * set com3base: DJGPP Native. (line 125)
33688 * set com3irq: DJGPP Native. (line 125)
33689 * set com4base: DJGPP Native. (line 125)
33690 * set com4irq: DJGPP Native. (line 125)
33691 * set complaints: Messages/Warnings. (line 29)
33692 * set confirm: Messages/Warnings. (line 50)
33693 * set cp-abi: ABI. (line 53)
33694 * set cygwin-exceptions: Cygwin Native. (line 37)
33695 * set data-directory: Data Files. (line 12)
33696 * set debug: Debugging Output. (line 18)
33697 * set debug darwin: Darwin. (line 9)
33698 * set debug hppa: HPPA. (line 10)
33699 * set debug mach-o: Darwin. (line 16)
33700 * set debug mips: MIPS. (line 81)
33701 * set debug monitor: Target Commands. (line 108)
33702 * set debug nto-debug: Neutrino. (line 9)
33703 * set debug-file-directory: Separate Debug Files.
33705 * set debugevents: Cygwin Native. (line 66)
33706 * set debugexceptions: Cygwin Native. (line 77)
33707 * set debugexec: Cygwin Native. (line 73)
33708 * set debugmemory: Cygwin Native. (line 81)
33709 * set default-collect: Tracepoint Actions. (line 89)
33710 * set demangle-style: Print Settings. (line 296)
33711 * set detach-on-fork: Forks. (line 55)
33712 * set disable-randomization: Starting. (line 136)
33713 * set disassemble-next-line: Machine Code. (line 119)
33714 * set disassembly-flavor: Machine Code. (line 107)
33715 * set disconnected-tracing: Starting and Stopping Trace Experiments.
33717 * set displaced-stepping: Maintenance Commands.
33719 * set download-path: M32R/D. (line 15)
33720 * set editing: Editing. (line 15)
33721 * set endian: Byte Order. (line 13)
33722 * set environment: Environment. (line 39)
33723 * set exceptions, Hurd command: Hurd Native. (line 40)
33724 * set exec-direction: Reverse Execution. (line 83)
33725 * set exec-done-display: Debugging Output. (line 11)
33726 * set exec-wrapper: Starting. (line 111)
33727 * set extension-language: Show. (line 30)
33728 * set fast tracepoint: Create and Delete Tracepoints.
33730 * set follow-exec-mode: Forks. (line 101)
33731 * set follow-fork-mode: Forks. (line 35)
33732 * set gnutarget: Target Commands. (line 28)
33733 * set hash, for remote monitors: Target Commands. (line 99)
33734 * set height: Screen Size. (line 21)
33735 * set history expansion: Command History. (line 65)
33736 * set history filename: Command History. (line 26)
33737 * set history save: Command History. (line 36)
33738 * set history size: Command History. (line 45)
33739 * set host-charset: Character Sets. (line 33)
33740 * set inferior controlling terminal: Input/Output. (line 44)
33741 * set inferior-tty: Input/Output. (line 49)
33742 * set input-radix: Numbers. (line 14)
33743 * set interactive-mode: Other Misc Settings. (line 6)
33744 * set language: Manually. (line 9)
33745 * set libthread-db-search-path: Threads. (line 180)
33746 * set listsize: List. (line 33)
33747 * set logging: Logging Output. (line 9)
33748 * set mach-exceptions: Darwin. (line 27)
33749 * set max-user-call-depth: Define. (line 76)
33750 * set mem inaccessible-by-default: Memory Region Attributes.
33752 * set mips abi: MIPS. (line 32)
33753 * set mips mask-address: MIPS. (line 61)
33754 * set mipsfpu: MIPS Embedded. (line 60)
33755 * set monitor-prompt, MIPS remote: MIPS Embedded. (line 107)
33756 * set monitor-warnings, MIPS remote: MIPS Embedded. (line 123)
33757 * set multiple-symbols: Ambiguous Expressions.
33759 * set new-console: Cygwin Native. (line 49)
33760 * set new-group: Cygwin Native. (line 58)
33761 * set non-stop: Non-Stop Mode. (line 38)
33762 * set opaque-type-resolution: Symbols. (line 241)
33763 * set osabi: ABI. (line 11)
33764 * set output-radix: Numbers. (line 31)
33765 * set overload-resolution: Debugging C Plus Plus.
33767 * set pagination: Screen Size. (line 38)
33768 * set powerpc: PowerPC Embedded. (line 8)
33769 * set print: Print Settings. (line 11)
33770 * set print frame-arguments: Print Settings. (line 135)
33771 * set print inferior-events: Inferiors and Programs.
33773 * set print thread-events: Threads. (line 159)
33774 * set processor: Targets. (line 31)
33775 * set procfs-file: SVR4 Process Information.
33777 * set procfs-trace: SVR4 Process Information.
33779 * set prompt: Prompt. (line 16)
33780 * set radix: Numbers. (line 44)
33781 * set rdiheartbeat: ARM. (line 112)
33782 * set rdiromatzero: ARM. (line 102)
33783 * set record insn-number-max: Process Record and Replay.
33785 * set record stop-at-limit: Process Record and Replay.
33787 * set remote: Remote Configuration.
33789 * set remote system-call-allowed: system. (line 38)
33790 * set remote-mips64-transfers-32bit-regs: MIPS. (line 71)
33791 * set remotecache: Caching Remote Data. (line 18)
33792 * set remoteflow: Remote Configuration.
33794 * set retransmit-timeout: MIPS Embedded. (line 83)
33795 * set rstack_high_address: A29K. (line 6)
33796 * set schedule-multiple: All-Stop Mode. (line 66)
33797 * set script-extension: Extending GDB. (line 19)
33798 * set sdstimeout: PowerPC Embedded. (line 38)
33799 * set server-address: M32R/D. (line 27)
33800 * set sh calling-convention: Super-H. (line 12)
33801 * set shell: Cygwin Native. (line 85)
33802 * set signal-thread: Hurd Native. (line 21)
33803 * set signals, Hurd command: Hurd Native. (line 11)
33804 * set sigs, Hurd command: Hurd Native. (line 11)
33805 * set sigthread: Hurd Native. (line 21)
33806 * set solib-absolute-prefix: Files. (line 374)
33807 * set solib-search-path: Files. (line 402)
33808 * set spu: SPU. (line 39)
33809 * set stack-cache: Caching Remote Data. (line 26)
33810 * set step-mode: Continuing and Stepping.
33812 * set stop-on-solib-events: Files. (line 351)
33813 * set stopped, Hurd command: Hurd Native. (line 32)
33814 * set struct-convention: i386. (line 7)
33815 * set substitute-path: Source Path. (line 123)
33816 * set symbol-reloading: Symbols. (line 224)
33817 * set syn-garbage-limit, MIPS remote: MIPS Embedded. (line 98)
33818 * set sysroot: Files. (line 374)
33819 * set target-async: Background Execution.
33821 * set target-charset: Character Sets. (line 28)
33822 * set target-wide-charset: Character Sets. (line 61)
33823 * set task, Hurd commands: Hurd Native. (line 49)
33824 * set tcp: Remote Configuration.
33826 * set tdesc filename: Retrieving Descriptions.
33828 * set thread, Hurd command: Hurd Native. (line 91)
33829 * set timeout: MIPS Embedded. (line 83)
33830 * set trace-commands: Messages/Warnings. (line 65)
33831 * set tracepoint: Create and Delete Tracepoints.
33833 * set trust-readonly-sections: Files. (line 258)
33834 * set tui active-border-mode: TUI Configuration. (line 24)
33835 * set tui border-kind: TUI Configuration. (line 9)
33836 * set tui border-mode: TUI Configuration. (line 23)
33837 * set unwind-on-terminating-exception: Calling. (line 46)
33838 * set unwindonsignal: Calling. (line 35)
33839 * set variable: Assignment. (line 16)
33840 * set verbose: Messages/Warnings. (line 15)
33841 * set watchdog: Maintenance Commands.
33843 * set width: Screen Size. (line 21)
33844 * set write: Patching. (line 15)
33845 * set-mark (C-@): Miscellaneous Commands.
33847 * set_debug_traps: Stub Contents. (line 10)
33848 * setting variables: Assignment. (line 6)
33849 * setting watchpoints: Set Watchpoints. (line 6)
33850 * SH: Remote Stub. (line 63)
33851 * sh-stub.c: Remote Stub. (line 63)
33852 * share: Files. (line 332)
33853 * shared libraries: Files. (line 281)
33854 * shared library events, remote reply: Stop Reply Packets. (line 56)
33855 * sharedlibrary: Files. (line 332)
33856 * shell: Shell Commands. (line 10)
33857 * shell escape: Shell Commands. (line 10)
33858 * show: Help. (line 112)
33859 * show ada trust-PAD-over-XVS: Ada Glitches. (line 48)
33860 * show all convenience functions: Convenience Vars. (line 98)
33861 * show all user variables: Convenience Vars. (line 37)
33862 * show annotate: Annotations Overview.
33864 * show architecture: Targets. (line 21)
33865 * show args: Arguments. (line 28)
33866 * show arm: ARM. (line 22)
33867 * show auto-solib-add: Files. (line 320)
33868 * show backtrace: Backtrace. (line 111)
33869 * show board-address: M32R/D. (line 24)
33870 * show breakpoint always-inserted: Set Breaks. (line 303)
33871 * show breakpoint auto-hw: Set Breaks. (line 283)
33872 * show breakpoint pending: Set Breaks. (line 252)
33873 * show can-use-hw-watchpoints: Set Watchpoints. (line 86)
33874 * show case-sensitive: Symbols. (line 40)
33875 * show charset: Character Sets. (line 52)
33876 * show check range: Range Checking. (line 34)
33877 * show check type: Type Checking. (line 42)
33878 * show coerce-float-to-double: ABI. (line 50)
33879 * show com1base: DJGPP Native. (line 137)
33880 * show com1irq: DJGPP Native. (line 137)
33881 * show com2base: DJGPP Native. (line 137)
33882 * show com2irq: DJGPP Native. (line 137)
33883 * show com3base: DJGPP Native. (line 137)
33884 * show com3irq: DJGPP Native. (line 137)
33885 * show com4base: DJGPP Native. (line 137)
33886 * show com4irq: DJGPP Native. (line 137)
33887 * show commands: Command History. (line 78)
33888 * show complaints: Messages/Warnings. (line 35)
33889 * show confirm: Messages/Warnings. (line 56)
33890 * show convenience: Convenience Vars. (line 37)
33891 * show copying: Help. (line 136)
33892 * show cp-abi: ABI. (line 53)
33893 * show cygwin-exceptions: Cygwin Native. (line 45)
33894 * show data-directory: Data Files. (line 16)
33895 * show debug: Debugging Output. (line 22)
33896 * show debug darwin: Darwin. (line 13)
33897 * show debug mach-o: Darwin. (line 23)
33898 * show debug mips: MIPS. (line 85)
33899 * show debug monitor: Target Commands. (line 112)
33900 * show debug nto-debug: Neutrino. (line 13)
33901 * show debug-file-directory: Separate Debug Files.
33903 * show default-collect: Tracepoint Actions. (line 98)
33904 * show detach-on-fork: Forks. (line 71)
33905 * show directories: Source Path. (line 120)
33906 * show disassemble-next-line: Machine Code. (line 119)
33907 * show disassembly-flavor: Machine Code. (line 116)
33908 * show disconnected-tracing: Starting and Stopping Trace Experiments.
33910 * show displaced-stepping: Maintenance Commands.
33912 * show download-path: M32R/D. (line 18)
33913 * show editing: Editing. (line 22)
33914 * show environment: Environment. (line 33)
33915 * show exceptions, Hurd command: Hurd Native. (line 46)
33916 * show exec-done-display: Debugging Output. (line 14)
33917 * show follow-fork-mode: Forks. (line 49)
33918 * show gnutarget: Target Commands. (line 40)
33919 * show hash, for remote monitors: Target Commands. (line 105)
33920 * show height: Screen Size. (line 21)
33921 * show history: Command History. (line 70)
33922 * show host-charset: Character Sets. (line 55)
33923 * show inferior-tty: Input/Output. (line 52)
33924 * show input-radix: Numbers. (line 36)
33925 * show interactive-mode: Other Misc Settings. (line 17)
33926 * show language: Show. (line 10)
33927 * show last commands: Command History. (line 78)
33928 * show libthread-db-search-path: Threads. (line 204)
33929 * show listsize: List. (line 37)
33930 * show logging: Logging Output. (line 26)
33931 * show mach-exceptions: Darwin. (line 34)
33932 * show max-user-call-depth: Define. (line 76)
33933 * show mem inaccessible-by-default: Memory Region Attributes.
33935 * show mips abi: MIPS. (line 54)
33936 * show mips mask-address: MIPS. (line 67)
33937 * show mipsfpu: MIPS Embedded. (line 60)
33938 * show monitor-prompt, MIPS remote: MIPS Embedded. (line 119)
33939 * show monitor-warnings, MIPS remote: MIPS Embedded. (line 129)
33940 * show multiple-symbols: Ambiguous Expressions.
33942 * show new-console: Cygwin Native. (line 54)
33943 * show new-group: Cygwin Native. (line 63)
33944 * show non-stop: Non-Stop Mode. (line 42)
33945 * show opaque-type-resolution: Symbols. (line 256)
33946 * show osabi: ABI. (line 11)
33947 * show output-radix: Numbers. (line 39)
33948 * show overload-resolution: Debugging C Plus Plus.
33950 * show pagination: Screen Size. (line 42)
33951 * show paths: Environment. (line 29)
33952 * show print: Print Settings. (line 39)
33953 * show print inferior-events: Inferiors and Programs.
33955 * show print thread-events: Threads. (line 169)
33956 * show processor: Targets. (line 31)
33957 * show procfs-file: SVR4 Process Information.
33959 * show procfs-trace: SVR4 Process Information.
33961 * show prompt: Prompt. (line 19)
33962 * show python auto-load: Auto-loading. (line 37)
33963 * show radix: Numbers. (line 44)
33964 * show rdiheartbeat: ARM. (line 117)
33965 * show rdiromatzero: ARM. (line 109)
33966 * show record insn-number-max: Process Record and Replay.
33968 * show record stop-at-limit: Process Record and Replay.
33970 * show remote: Remote Configuration.
33972 * show remote system-call-allowed: system. (line 42)
33973 * show remote-mips64-transfers-32bit-regs: MIPS. (line 77)
33974 * show remotecache: Caching Remote Data. (line 23)
33975 * show remoteflow: Remote Configuration.
33977 * show retransmit-timeout: MIPS Embedded. (line 83)
33978 * show rstack_high_address: A29K. (line 17)
33979 * show script-extension: Extending GDB. (line 19)
33980 * show sdstimeout: PowerPC Embedded. (line 42)
33981 * show server-address: M32R/D. (line 31)
33982 * show sh calling-convention: Super-H. (line 25)
33983 * show shell: Cygwin Native. (line 89)
33984 * show signal-thread: Hurd Native. (line 28)
33985 * show signals, Hurd command: Hurd Native. (line 17)
33986 * show sigs, Hurd command: Hurd Native. (line 17)
33987 * show sigthread: Hurd Native. (line 28)
33988 * show solib-search-path: Files. (line 413)
33989 * show spu: SPU. (line 44)
33990 * show stack-cache: Caching Remote Data. (line 31)
33991 * show stop-on-solib-events: Files. (line 357)
33992 * show stopped, Hurd command: Hurd Native. (line 37)
33993 * show struct-convention: i386. (line 15)
33994 * show substitute-path: Source Path. (line 160)
33995 * show symbol-reloading: Symbols. (line 238)
33996 * show syn-garbage-limit, MIPS remote: MIPS Embedded. (line 103)
33997 * show sysroot: Files. (line 399)
33998 * show target-async: Background Execution.
34000 * show target-charset: Character Sets. (line 58)
34001 * show target-wide-charset: Character Sets. (line 67)
34002 * show task, Hurd commands: Hurd Native. (line 57)
34003 * show tcp: Remote Configuration.
34005 * show tdesc filename: Retrieving Descriptions.
34007 * show thread, Hurd command: Hurd Native. (line 101)
34008 * show timeout: MIPS Embedded. (line 83)
34009 * show unwind-on-terminating-exception: Calling. (line 54)
34010 * show unwindonsignal: Calling. (line 42)
34011 * show user: Define. (line 70)
34012 * show values: Value History. (line 47)
34013 * show verbose: Messages/Warnings. (line 21)
34014 * show version: Help. (line 126)
34015 * show warranty: Help. (line 140)
34016 * show width: Screen Size. (line 21)
34017 * show write: Patching. (line 26)
34018 * show-all-if-ambiguous: Readline Init File Syntax.
34020 * show-all-if-unmodified: Readline Init File Syntax.
34022 * si (stepi): Continuing and Stepping.
34024 * signal: Signaling. (line 6)
34025 * signal annotation: Annotations for Running.
34027 * signal-name annotation: Annotations for Running.
34029 * signal-name-end annotation: Annotations for Running.
34031 * signal-string annotation: Annotations for Running.
34033 * signal-string-end annotation: Annotations for Running.
34035 * signalled annotation: Annotations for Running.
34037 * signals: Signals. (line 6)
34038 * SIGQUIT signal, dump core of GDB: Maintenance Commands.
34040 * silent: Break Commands. (line 38)
34041 * sim: Z8000. (line 15)
34042 * sim, a command: Embedded Processors. (line 13)
34043 * simulator, Z8000: Z8000. (line 6)
34044 * size of remote memory accesses: Packets. (line 215)
34045 * size of screen: Screen Size. (line 6)
34046 * sizeof: Types In Python. (line 25)
34047 * snapshot of a process: Checkpoint/Restart. (line 6)
34048 * software watchpoints: Set Watchpoints. (line 31)
34049 * source: Command Files. (line 17)
34050 * source annotation: Source Annotations. (line 6)
34051 * source file and line of a symbol: Print Settings. (line 51)
34052 * source line and its code address: Machine Code. (line 6)
34053 * source path: Source Path. (line 6)
34054 * Sparc: Remote Stub. (line 66)
34055 * sparc-stub.c: Remote Stub. (line 66)
34056 * sparcl-stub.c: Remote Stub. (line 69)
34057 * Sparclet: Sparclet. (line 6)
34058 * SparcLite: Remote Stub. (line 69)
34059 * Special Fortran commands: Special Fortran Commands.
34061 * specifying location: Specify Location. (line 6)
34062 * spr: OpenRISC 1000. (line 33)
34063 * SPU: SPU. (line 6)
34064 * SSE registers (x86): Registers. (line 71)
34065 * stack frame: Frames. (line 6)
34066 * stack on Alpha: MIPS. (line 6)
34067 * stack on MIPS: MIPS. (line 6)
34068 * stack pointer register: Registers. (line 26)
34069 * stacking targets: Active Targets. (line 6)
34070 * standard registers: Registers. (line 26)
34071 * start: Starting. (line 78)
34072 * start a new trace experiment: Starting and Stopping Trace Experiments.
34074 * start-kbd-macro (C-x (): Keyboard Macros. (line 6)
34075 * starting: Starting. (line 6)
34076 * starting annotation: Annotations for Running.
34078 * startup code, and backtrace: Backtrace. (line 93)
34079 * stat, file-i/o system call: stat/fstat. (line 6)
34080 * static members of C++ objects: Print Settings. (line 342)
34081 * static members of Pascal objects: Print Settings. (line 353)
34082 * status of trace data collection: Starting and Stopping Trace Experiments.
34084 * status output in GDB/MI: GDB/MI Output Syntax.
34086 * step: Continuing and Stepping.
34088 * step&: Background Execution.
34090 * stepi: Continuing and Stepping.
34092 * stepi&: Background Execution.
34094 * stepping: Continuing and Stepping.
34096 * stepping into functions with no line info: Continuing and Stepping.
34098 * stop a running trace experiment: Starting and Stopping Trace Experiments.
34100 * stop on C++ exceptions: Set Catchpoints. (line 13)
34101 * stop reply packets: Stop Reply Packets. (line 6)
34102 * stop, a pseudo-command: Hooks. (line 21)
34103 * stopped threads: Thread Stops. (line 6)
34104 * stopping annotation: Annotations for Running.
34106 * stream records in GDB/MI: GDB/MI Stream Records.
34108 * string on Value: Values From Inferior.
34110 * strip_typedefs on Type: Types In Python. (line 106)
34111 * struct return convention: i386. (line 7)
34112 * struct stat, in file-i/o protocol: struct stat. (line 6)
34113 * struct timeval, in file-i/o protocol: struct timeval. (line 6)
34114 * struct user contents: OS Information. (line 9)
34115 * struct/union returned in registers: i386. (line 7)
34116 * structure field name completion: Completion. (line 96)
34117 * stub example, remote debugging: Remote Stub. (line 6)
34118 * stupid questions: Messages/Warnings. (line 50)
34119 * Super-H: Super-H. (line 6)
34120 * supported packets, remote query: General Query Packets.
34122 * switching threads: Threads. (line 6)
34123 * switching threads automatically: All-Stop Mode. (line 28)
34124 * symbol decoding style, C++: Print Settings. (line 296)
34125 * symbol dump: Symbols. (line 259)
34126 * symbol from address: Symbols. (line 54)
34127 * symbol lookup, remote request: General Query Packets.
34129 * symbol names: Symbols. (line 14)
34130 * symbol table: Files. (line 6)
34131 * symbol tables, listing GDB's internal: Symbols. (line 278)
34132 * symbol, source file and line: Print Settings. (line 51)
34133 * symbol-file: Files. (line 45)
34134 * symbols, reading from relocatable object files: Files. (line 132)
34135 * symbols, reading immediately: Files. (line 90)
34136 * synchronize with remote MIPS target: MIPS Embedded. (line 98)
34137 * syscall DSO: Files. (line 162)
34138 * sysinfo: DJGPP Native. (line 19)
34139 * system calls and thread breakpoints: Interrupted System Calls.
34141 * system root, alternate: Files. (line 374)
34142 * system, file-i/o system call: system. (line 6)
34143 * system-wide init file: System-wide configuration.
34145 * T packet: Packets. (line 303)
34146 * t packet: Packets. (line 298)
34147 * T packet reply: Stop Reply Packets. (line 22)
34148 * tabset: TUI Commands. (line 78)
34149 * tag: Types In Python. (line 30)
34150 * target: Target Commands. (line 49)
34151 * target architecture: Targets. (line 17)
34152 * target array: MIPS Embedded. (line 49)
34153 * target byte order: Byte Order. (line 6)
34154 * target character set: Character Sets. (line 6)
34155 * target dbug: M68K. (line 9)
34156 * target ddb PORT: MIPS Embedded. (line 41)
34157 * target debugging info: Debugging Output. (line 148)
34158 * target descriptions: Target Descriptions. (line 6)
34159 * target descriptions, ARM features: ARM Features. (line 6)
34160 * target descriptions, i386 features: i386 Features. (line 6)
34161 * target descriptions, inclusion: Target Description Format.
34163 * target descriptions, M68K features: M68K Features. (line 6)
34164 * target descriptions, MIPS features: MIPS Features. (line 6)
34165 * target descriptions, PowerPC features: PowerPC Features. (line 6)
34166 * target descriptions, predefined types: Predefined Target Types.
34168 * target descriptions, standard features: Standard Target Features.
34170 * target descriptions, XML format: Target Description Format.
34172 * target dink32: PowerPC Embedded. (line 23)
34173 * target jtag: OpenRISC 1000. (line 9)
34174 * target lsi PORT: MIPS Embedded. (line 44)
34175 * target m32r: M32R/D. (line 6)
34176 * target m32rsdi: M32R/D. (line 9)
34177 * target mips PORT: MIPS Embedded. (line 14)
34178 * target on Type: Types In Python. (line 110)
34179 * target op50n: PA. (line 6)
34180 * target output in GDB/MI: GDB/MI Output Syntax.
34182 * target pmon PORT: MIPS Embedded. (line 38)
34183 * target ppcbug: PowerPC Embedded. (line 26)
34184 * target ppcbug1: PowerPC Embedded. (line 27)
34185 * target r3900: MIPS Embedded. (line 46)
34186 * target rdi: ARM. (line 6)
34187 * target rdp: ARM. (line 11)
34188 * target record: Process Record and Replay.
34190 * target remote: Connecting. (line 11)
34191 * target sds: PowerPC Embedded. (line 31)
34192 * target sim, with Z8000: Z8000. (line 15)
34193 * target sparclite: Sparclite. (line 6)
34194 * target stack description: Maintenance Commands.
34196 * target tfile: Trace Files. (line 22)
34197 * target vxworks: VxWorks. (line 6)
34198 * target w89k: PA. (line 9)
34199 * task (Ada): Ada Tasks. (line 105)
34200 * task attributes (GNU Hurd): Hurd Native. (line 49)
34201 * task breakpoints, in Ada: Ada Tasks. (line 135)
34202 * task exception port, GNU Hurd: Hurd Native. (line 68)
34203 * task suspend count: Hurd Native. (line 60)
34204 * tbreak: Set Breaks. (line 55)
34205 * TCP port, target remote: Connecting. (line 29)
34206 * tdump: tdump. (line 6)
34207 * template_argument on Type: Types In Python. (line 125)
34208 * terminal: Input/Output. (line 6)
34209 * teval (tracepoints): Tracepoint Actions. (line 67)
34210 * Text User Interface: TUI. (line 6)
34211 * tfile: Trace Files. (line 22)
34212 * tfind: tfind. (line 6)
34213 * thbreak: Set Breaks. (line 82)
34214 * this, inside C++ member functions: C Plus Plus Expressions.
34216 * thread apply: Threads. (line 150)
34217 * thread attributes info, remote request: General Query Packets.
34219 * thread breakpoints: Thread-Specific Breakpoints.
34221 * thread breakpoints and system calls: Interrupted System Calls.
34223 * thread default settings, GNU Hurd: Hurd Native. (line 131)
34224 * thread identifier (GDB): Threads. (line 63)
34225 * thread identifier (GDB), on HP-UX: Threads. (line 89)
34226 * thread identifier (system): Threads. (line 51)
34227 * thread identifier (system), on HP-UX: Threads. (line 93)
34228 * thread info (Solaris): Threads. (line 133)
34229 * thread information, remote request: General Query Packets.
34231 * thread list format: Thread List Format. (line 6)
34232 * thread number: Threads. (line 63)
34233 * thread properties, GNU Hurd: Hurd Native. (line 91)
34234 * thread suspend count, GNU Hurd: Hurd Native. (line 110)
34235 * thread THREADNO: Threads. (line 135)
34236 * THREAD-ID, in remote protocol: Packets. (line 20)
34237 * threads and watchpoints: Set Watchpoints. (line 147)
34238 * threads of execution: Threads. (line 6)
34239 * threads, automatic switching: All-Stop Mode. (line 28)
34240 * threads, continuing: Thread Stops. (line 6)
34241 * threads, stopped: Thread Stops. (line 6)
34242 * time of command execution: Maintenance Commands.
34244 * timeout for commands: Maintenance Commands.
34246 * timeout for serial communications: Remote Configuration.
34248 * timeout, for remote target connection: Remote Configuration.
34250 * timeout, MIPS protocol: MIPS Embedded. (line 83)
34251 * timestampping debugging info: Debugging Output. (line 159)
34252 * tload, M32R: M32R/D. (line 39)
34253 * to_string on pretty printer: Pretty Printing. (line 77)
34254 * trace: Create and Delete Tracepoints.
34256 * trace experiment, status of: Starting and Stopping Trace Experiments.
34258 * trace file format: Trace File Format. (line 6)
34259 * trace files: Trace Files. (line 6)
34260 * trace state variable value, remote request: Tracepoint Packets.
34262 * trace state variables: Trace State Variables.
34264 * traceback: Backtrace. (line 6)
34265 * tracepoint actions: Tracepoint Actions. (line 6)
34266 * tracepoint conditions: Tracepoint Conditions.
34268 * tracepoint data, display: tdump. (line 6)
34269 * tracepoint deletion: Create and Delete Tracepoints.
34271 * tracepoint number: Create and Delete Tracepoints.
34273 * tracepoint packets: Tracepoint Packets. (line 6)
34274 * tracepoint pass count: Tracepoint Passcounts.
34276 * tracepoint variables: Tracepoint Variables.
34278 * tracepoints: Tracepoints. (line 6)
34279 * trailing underscore, in Fortran symbols: Fortran. (line 9)
34280 * translating between character sets: Character Sets. (line 6)
34281 * transpose-chars (C-t): Commands For Text. (line 30)
34282 * transpose-words (M-t): Commands For Text. (line 36)
34283 * tsave: Trace Files. (line 12)
34284 * tstart: Starting and Stopping Trace Experiments.
34286 * tstatus: Starting and Stopping Trace Experiments.
34288 * tstop: Starting and Stopping Trace Experiments.
34290 * tty: Input/Output. (line 23)
34291 * TUI: TUI. (line 6)
34292 * TUI commands: TUI Commands. (line 6)
34293 * TUI configuration variables: TUI Configuration. (line 6)
34294 * TUI key bindings: TUI Keys. (line 6)
34295 * tui reg: TUI Commands. (line 55)
34296 * TUI single key mode: TUI Single Key Mode. (line 6)
34297 * tvariable: Trace State Variables.
34299 * type <1>: Lazy Strings In Python.
34301 * type: Values From Inferior.
34303 * type casting memory: Expressions. (line 43)
34304 * type chain of a data type: Maintenance Commands.
34306 * type checking: Checks. (line 31)
34307 * type conversions in C++: C Plus Plus Expressions.
34309 * type on Frame: Frames In Python. (line 44)
34310 * TYPE_CODE_ARRAY: Types In Python. (line 142)
34311 * TYPE_CODE_BITSTRING: Types In Python. (line 180)
34312 * TYPE_CODE_BOOL: Types In Python. (line 201)
34313 * TYPE_CODE_CHAR: Types In Python. (line 198)
34314 * TYPE_CODE_COMPLEX: Types In Python. (line 204)
34315 * TYPE_CODE_DECFLOAT: Types In Python. (line 213)
34316 * TYPE_CODE_ENUM: Types In Python. (line 151)
34317 * TYPE_CODE_ERROR: Types In Python. (line 183)
34318 * TYPE_CODE_FLAGS: Types In Python. (line 154)
34319 * TYPE_CODE_FLT: Types In Python. (line 163)
34320 * TYPE_CODE_FUNC: Types In Python. (line 157)
34321 * TYPE_CODE_INT: Types In Python. (line 160)
34322 * TYPE_CODE_INTERNAL_FUNCTION: Types In Python. (line 216)
34323 * TYPE_CODE_MEMBERPTR: Types In Python. (line 192)
34324 * TYPE_CODE_METHOD: Types In Python. (line 186)
34325 * TYPE_CODE_METHODPTR: Types In Python. (line 189)
34326 * TYPE_CODE_NAMESPACE: Types In Python. (line 210)
34327 * TYPE_CODE_PTR: Types In Python. (line 139)
34328 * TYPE_CODE_RANGE: Types In Python. (line 172)
34329 * TYPE_CODE_REF: Types In Python. (line 195)
34330 * TYPE_CODE_SET: Types In Python. (line 169)
34331 * TYPE_CODE_STRING: Types In Python. (line 175)
34332 * TYPE_CODE_STRUCT: Types In Python. (line 145)
34333 * TYPE_CODE_TYPEDEF: Types In Python. (line 207)
34334 * TYPE_CODE_UNION: Types In Python. (line 148)
34335 * TYPE_CODE_VOID: Types In Python. (line 166)
34336 * types in Python: Types In Python. (line 6)
34337 * u (SingleKey TUI key): TUI Single Key Mode. (line 31)
34338 * u (until): Continuing and Stepping.
34340 * UDP port, target remote: Connecting. (line 49)
34341 * undisplay: Auto Display. (line 45)
34342 * undo (C-_ or C-x C-u): Miscellaneous Commands.
34344 * union field name completion: Completion. (line 96)
34345 * unions in structures, printing: Print Settings. (line 236)
34346 * universal-argument (): Numeric Arguments. (line 10)
34347 * unix-filename-rubout (): Commands For Killing.
34349 * unix-line-discard (C-u): Commands For Killing.
34351 * unix-word-rubout (C-w): Commands For Killing.
34353 * unknown address, locating: Output Formats. (line 35)
34354 * unlink, file-i/o system call: unlink. (line 6)
34355 * unlinked object files: Files. (line 26)
34356 * unload symbols from shared libraries: Files. (line 341)
34357 * unmap an overlay: Overlay Commands. (line 39)
34358 * unmapped overlays: How Overlays Work. (line 6)
34359 * unqualified on Type: Types In Python. (line 87)
34360 * unset environment: Environment. (line 55)
34361 * unset substitute-path: Source Path. (line 152)
34362 * unset tdesc filename: Retrieving Descriptions.
34364 * unsupported languages: Unsupported Languages.
34366 * until: Continuing and Stepping.
34368 * until&: Background Execution.
34370 * unwind stack in called functions: Calling. (line 35)
34371 * unwind stack in called functions with unhandled exceptions: Calling.
34373 * unwind_stop_reason on Frame: Frames In Python. (line 49)
34374 * Up: TUI Keys. (line 53)
34375 * up: Selection. (line 35)
34376 * up-silently: Selection. (line 64)
34377 * upcase-word (M-u): Commands For Text. (line 41)
34378 * update: TUI Commands. (line 70)
34379 * upload, M32R: M32R/D. (line 34)
34380 * use only software watchpoints: Set Watchpoints. (line 75)
34381 * use_dbt_break: M32R/D. (line 64)
34382 * use_debug_dma: M32R/D. (line 53)
34383 * use_ib_break: M32R/D. (line 61)
34384 * use_mon_code: M32R/D. (line 57)
34385 * user-defined command: Define. (line 6)
34386 * user-defined macros: Macros. (line 52)
34387 * user-defined variables: Convenience Vars. (line 6)
34388 * v (SingleKey TUI key): TUI Single Key Mode. (line 34)
34389 * value history: Value History. (line 6)
34390 * value on LazyString: Lazy Strings In Python.
34392 * value optimized out, in backtrace: Backtrace. (line 71)
34393 * values from inferior, with Python: Values From Inferior.
34395 * variable name conflict: Variables. (line 36)
34396 * variable object debugging info: Debugging Output. (line 168)
34397 * variable objects in GDB/MI: GDB/MI Variable Objects.
34399 * variable values, wrong: Variables. (line 58)
34400 * variables, readline: Readline Init File Syntax.
34402 * variables, setting: Assignment. (line 16)
34403 * vAttach packet: Packets. (line 318)
34404 * vCont packet: Packets. (line 338)
34405 * vCont? packet: Packets. (line 380)
34406 * vector unit: Vector Unit. (line 6)
34407 * vector, auxiliary: OS Information. (line 21)
34408 * verbose operation: Messages/Warnings. (line 6)
34409 * verify remote memory image: Memory. (line 115)
34410 * vFile packet: Packets. (line 391)
34411 * vFlashDone packet: Packets. (line 439)
34412 * vFlashErase packet: Packets. (line 395)
34413 * vFlashWrite packet: Packets. (line 417)
34414 * virtual functions (C++) display: Print Settings. (line 364)
34415 * visible-stats: Readline Init File Syntax.
34417 * vKill packet: Packets. (line 447)
34418 * volatile on Type: Types In Python. (line 83)
34419 * vRun packet: Packets. (line 460)
34420 * vStopped packet: Packets. (line 477)
34421 * VTBL display: Print Settings. (line 364)
34422 * VxWorks: VxWorks. (line 6)
34423 * vxworks-timeout: VxWorks. (line 23)
34424 * w (SingleKey TUI key): TUI Single Key Mode. (line 37)
34425 * watch: Set Watchpoints. (line 42)
34426 * watchdog timer: Maintenance Commands.
34428 * watchpoint annotation: Annotations for Running.
34430 * watchpoints: Breakpoints. (line 20)
34431 * watchpoints and threads: Set Watchpoints. (line 147)
34432 * weak alias functions: Calling. (line 58)
34433 * whatis: Symbols. (line 74)
34434 * where: Backtrace. (line 34)
34435 * where to look for shared libraries: Files. (line 369)
34436 * while: Command Files. (line 70)
34437 * while-stepping (tracepoints): Tracepoint Actions. (line 75)
34438 * wild pointer, interpreting: Print Settings. (line 79)
34439 * winheight: TUI Commands. (line 74)
34440 * word completion: Completion. (line 6)
34441 * working directory: Source Path. (line 108)
34442 * working directory (of your program): Working Directory. (line 6)
34443 * working language: Languages. (line 13)
34444 * write: Basic Python. (line 55)
34445 * write data into object, remote request: General Query Packets.
34447 * write, file-i/o system call: write. (line 6)
34448 * writing convenience functions: Functions In Python. (line 6)
34449 * writing into corefiles: Patching. (line 6)
34450 * writing into executables: Patching. (line 6)
34451 * wrong values: Variables. (line 58)
34452 * x (examine memory): Memory. (line 9)
34453 * x command, default address: Machine Code. (line 30)
34454 * X packet: Packets. (line 489)
34455 * x(examine), and info line: Machine Code. (line 30)
34456 * Xilinx MicroBlaze: MicroBlaze. (line 6)
34457 * XInclude: Target Description Format.
34459 * XMD, Xilinx Microprocessor Debugger: MicroBlaze. (line 6)
34460 * XML parser debugging: Debugging Output. (line 176)
34461 * yank (C-y): Commands For Killing.
34463 * yank-last-arg (M-. or M-_): Commands For History.
34465 * yank-nth-arg (M-C-y): Commands For History.
34467 * yank-pop (M-y): Commands For Killing.
34469 * yanking text: Readline Killing Commands.
34471 * z packet: Packets. (line 502)
34472 * Z packets: Packets. (line 502)
34473 * Z0 packet: Packets. (line 517)
34474 * z0 packet: Packets. (line 517)
34475 * Z1 packet: Packets. (line 545)
34476 * z1 packet: Packets. (line 545)
34477 * Z2 packet: Packets. (line 567)
34478 * z2 packet: Packets. (line 567)
34479 * Z3 packet: Packets. (line 582)
34480 * z3 packet: Packets. (line 582)
34481 * Z4 packet: Packets. (line 597)
34482 * z4 packet: Packets. (line 597)
34483 * Z8000: Z8000. (line 6)
34484 * Zilog Z8000 simulator: Z8000. (line 6)
34485 * {TYPE}: Expressions. (line 43)
34491 Node: Summary
\7f5116
34492 Node: Free Software
\7f6752
34493 Node: Contributors
\7f12320
34494 Node: Sample Session
\7f20409
34495 Node: Invocation
\7f27257
34496 Node: Invoking GDB
\7f27801
34497 Node: File Options
\7f30114
34498 Node: Mode Options
\7f32851
34499 Node: Startup
\7f39263
34500 Ref: Startup-Footnote-1
\7f41485
34501 Node: Quitting GDB
\7f41594
34502 Node: Shell Commands
\7f42491
34503 Node: Logging Output
\7f43333
34504 Node: Commands
\7f44179
34505 Node: Command Syntax
\7f44817
34506 Node: Completion
\7f46983
34507 Ref: Completion-Footnote-1
\7f52189
34509 Node: Running
\7f57590
34510 Node: Compilation
\7f58819
34511 Node: Starting
\7f60796
34512 Node: Arguments
\7f69686
34513 Node: Environment
\7f70956
34514 Node: Working Directory
\7f74224
34515 Node: Input/Output
\7f75332
34516 Node: Attach
\7f77303
34517 Node: Kill Process
\7f79770
34518 Node: Inferiors and Programs
\7f80751
34519 Node: Threads
\7f87711
34520 Node: Forks
\7f95770
34521 Node: Checkpoint/Restart
\7f102078
34522 Ref: Checkpoint/Restart-Footnote-1
\7f106607
34523 Node: Stopping
\7f106642
34524 Node: Breakpoints
\7f107801
34525 Node: Set Breaks
\7f111171
34526 Ref: Set Breaks-Footnote-1
\7f127067
34527 Node: Set Watchpoints
\7f127315
34528 Node: Set Catchpoints
\7f134969
34529 Node: Delete Breaks
\7f144165
34530 Node: Disabling
\7f146101
34531 Node: Conditions
\7f148966
34532 Node: Break Commands
\7f153915
34533 Node: Error in Breakpoints
\7f156804
34534 Node: Breakpoint-related Warnings
\7f157533
34535 Node: Continuing and Stepping
\7f159858
34536 Node: Signals
\7f169218
34537 Ref: extra signal information
\7f173490
34538 Node: Thread Stops
\7f174993
34539 Node: All-Stop Mode
\7f176024
34540 Node: Non-Stop Mode
\7f179922
34541 Node: Background Execution
\7f183399
34542 Node: Thread-Specific Breakpoints
\7f185968
34543 Node: Interrupted System Calls
\7f187290
34544 Node: Reverse Execution
\7f188782
34545 Ref: Reverse Execution-Footnote-1
\7f193409
34546 Ref: Reverse Execution-Footnote-2
\7f194036
34547 Node: Process Record and Replay
\7f194086
34548 Node: Stack
\7f200455
34549 Node: Frames
\7f201948
34550 Node: Backtrace
\7f204700
34551 Ref: Backtrace-Footnote-1
\7f209931
34552 Node: Selection
\7f210119
34553 Node: Frame Info
\7f212983
34554 Node: Source
\7f215314
34555 Node: List
\7f216380
34556 Node: Specify Location
\7f218993
34557 Node: Edit
\7f222243
34558 Ref: Edit-Footnote-1
\7f223718
34559 Node: Search
\7f223953
34560 Node: Source Path
\7f224761
34561 Ref: set substitute-path
\7f231019
34562 Node: Machine Code
\7f233240
34563 Node: Data
\7f239272
34564 Node: Expressions
\7f241790
34565 Node: Ambiguous Expressions
\7f243882
34566 Node: Variables
\7f247116
34567 Node: Arrays
\7f251619
34568 Node: Output Formats
\7f254150
34569 Ref: Output Formats-Footnote-1
\7f257221
34570 Node: Memory
\7f257378
34571 Node: Auto Display
\7f263020
34572 Node: Print Settings
\7f266735
34573 Node: Value History
\7f280337
34574 Node: Convenience Vars
\7f282755
34575 Node: Registers
\7f286895
34576 Ref: Registers-Footnote-1
\7f291572
34577 Node: Floating Point Hardware
\7f291967
34578 Node: Vector Unit
\7f292499
34579 Node: OS Information
\7f292886
34580 Node: Memory Region Attributes
\7f295354
34581 Node: Dump/Restore Files
\7f300024
34582 Node: Core File Generation
\7f302329
34583 Node: Character Sets
\7f303563
34584 Node: Caching Remote Data
\7f309930
34585 Ref: Caching Remote Data-Footnote-1
\7f311731
34586 Node: Searching Memory
\7f311969
34587 Node: Optimized Code
\7f314846
34588 Node: Inline Functions
\7f316456
34589 Node: Macros
\7f319426
34590 Node: Tracepoints
\7f326529
34591 Node: Set Tracepoints
\7f328590
34592 Node: Create and Delete Tracepoints
\7f330342
34593 Node: Enable and Disable Tracepoints
\7f332997
34594 Node: Tracepoint Passcounts
\7f333781
34595 Node: Tracepoint Conditions
\7f335208
34596 Node: Trace State Variables
\7f336901
34597 Node: Tracepoint Actions
\7f339091
34598 Node: Listing Tracepoints
\7f343087
34599 Node: Starting and Stopping Trace Experiments
\7f344471
34600 Node: Analyze Collected Data
\7f347474
34601 Node: tfind
\7f348779
34602 Node: tdump
\7f353201
34603 Node: save-tracepoints
\7f354860
34604 Node: Tracepoint Variables
\7f355279
34605 Node: Trace Files
\7f356407
34606 Node: Overlays
\7f357865
34607 Node: How Overlays Work
\7f358585
34608 Ref: A code overlay
\7f361145
34609 Node: Overlay Commands
\7f364583
34610 Node: Automatic Overlay Debugging
\7f368773
34611 Node: Overlay Sample Program
\7f370914
34612 Node: Languages
\7f372674
34613 Node: Setting
\7f373837
34614 Node: Filenames
\7f375539
34615 Node: Manually
\7f376325
34616 Node: Automatically
\7f377534
34617 Node: Show
\7f378595
34618 Node: Checks
\7f379917
34619 Node: Type Checking
\7f381307
34620 Node: Range Checking
\7f384040
34621 Node: Supported Languages
\7f386441
34623 Node: C Operators
\7f388915
34624 Node: C Constants
\7f393234
34625 Node: C Plus Plus Expressions
\7f395638
34626 Node: C Defaults
\7f399181
34627 Node: C Checks
\7f399864
34628 Node: Debugging C
\7f400587
34629 Node: Debugging C Plus Plus
\7f401071
34630 Node: Decimal Floating Point
\7f404258
34631 Node: Objective-C
\7f405517
34632 Node: Method Names in Commands
\7f405978
34633 Node: The Print Command with Objective-C
\7f407673
34634 Node: Fortran
\7f408324
34635 Node: Fortran Operators
\7f409049
34636 Node: Fortran Defaults
\7f409905
34637 Node: Special Fortran Commands
\7f410290
34638 Node: Pascal
\7f410796
34639 Node: Modula-2
\7f411311
34640 Node: M2 Operators
\7f412286
34641 Node: Built-In Func/Proc
\7f415285
34642 Node: M2 Constants
\7f418146
34643 Node: M2 Types
\7f419747
34644 Node: M2 Defaults
\7f422966
34645 Node: Deviations
\7f423566
34646 Node: M2 Checks
\7f424667
34647 Node: M2 Scope
\7f425485
34648 Node: GDB/M2
\7f426509
34650 Node: Ada Mode Intro
\7f428368
34651 Node: Omissions from Ada
\7f430278
34652 Node: Additions to Ada
\7f434632
34653 Node: Stopping Before Main Program
\7f438562
34654 Node: Ada Tasks
\7f439091
34655 Node: Ada Tasks and Core Files
\7f445504
34656 Node: Ada Glitches
\7f446417
34657 Node: Unsupported Languages
\7f449484
34658 Node: Symbols
\7f450174
34659 Node: Altering
\7f464003
34660 Node: Assignment
\7f464972
34661 Node: Jumping
\7f468077
34662 Node: Signaling
\7f470212
34663 Node: Returning
\7f471343
34664 Node: Calling
\7f474695
34665 Node: Patching
\7f477722
34666 Node: GDB Files
\7f478799
34667 Node: Files
\7f479387
34668 Ref: Shared Libraries
\7f492222
34669 Ref: Files-Footnote-1
\7f498366
34670 Node: Separate Debug Files
\7f498541
34671 Node: Symbol Errors
\7f510113
34672 Node: Data Files
\7f513735
34673 Node: Targets
\7f514574
34674 Node: Active Targets
\7f516054
34675 Node: Target Commands
\7f517633
34677 Node: Byte Order
\7f522873
34678 Node: Remote Debugging
\7f523850
34679 Node: Connecting
\7f525112
34680 Node: File Transfer
\7f530052
34681 Node: Server
\7f530992
34682 Ref: Monitor Commands for gdbserver
\7f538642
34683 Ref: Server-Footnote-1
\7f539798
34684 Node: Remote Configuration
\7f539918
34685 Ref: set remotebreak
\7f540942
34686 Ref: set remote hardware-watchpoint-limit
\7f542406
34687 Ref: set remote hardware-breakpoint-limit
\7f542406
34688 Ref: set remote exec-file
\7f542688
34689 Node: Remote Stub
\7f548633
34690 Node: Stub Contents
\7f551530
34691 Node: Bootstrapping
\7f553641
34692 Node: Debug Session
\7f557450
34693 Node: Configurations
\7f559010
34694 Node: Native
\7f559779
34695 Node: HP-UX
\7f560414
34696 Node: BSD libkvm Interface
\7f560703
34697 Node: SVR4 Process Information
\7f561774
34698 Node: DJGPP Native
\7f565204
34699 Node: Cygwin Native
\7f571784
34700 Node: Non-debug DLL Symbols
\7f575488
34701 Node: Hurd Native
\7f580036
34702 Node: Neutrino
\7f585299
34703 Node: Darwin
\7f585689
34704 Node: Embedded OS
\7f586947
34705 Node: VxWorks
\7f587423
34706 Node: VxWorks Connection
\7f589640
34707 Node: VxWorks Download
\7f590574
34708 Node: VxWorks Attach
\7f592309
34709 Node: Embedded Processors
\7f592707
34711 Node: M32R/D
\7f597623
34712 Node: M68K
\7f599325
34713 Node: MicroBlaze
\7f599618
34714 Node: MIPS Embedded
\7f601068
34715 Node: OpenRISC 1000
\7f606018
34716 Node: PowerPC Embedded
\7f608873
34718 Node: Sparclet
\7f610628
34719 Node: Sparclet File
\7f612112
34720 Node: Sparclet Connection
\7f612992
34721 Node: Sparclet Download
\7f613470
34722 Node: Sparclet Execution
\7f614519
34723 Node: Sparclite
\7f615110
34724 Node: Z8000
\7f615485
34726 Node: CRIS
\7f617232
34727 Node: Super-H
\7f618210
34728 Node: Architectures
\7f619325
34729 Node: i386
\7f619747
34730 Node: A29K
\7f620429
34731 Node: Alpha
\7f621268
34732 Node: MIPS
\7f621401
34733 Node: HPPA
\7f624025
34735 Node: PowerPC
\7f626732
34736 Node: Controlling GDB
\7f627450
34737 Node: Prompt
\7f628276
34738 Node: Editing
\7f629055
34739 Node: Command History
\7f629998
34740 Node: Screen Size
\7f633402
34741 Node: Numbers
\7f635107
34743 Node: Messages/Warnings
\7f640013
34744 Ref: confirmation requests
\7f641439
34745 Node: Debugging Output
\7f642506
34746 Node: Other Misc Settings
\7f648425
34747 Node: Extending GDB
\7f649192
34748 Node: Sequences
\7f650683
34749 Node: Define
\7f651278
34750 Node: Hooks
\7f654891
34751 Node: Command Files
\7f657258
34752 Node: Output
\7f661321
34753 Node: Python
\7f666092
34754 Node: Python Commands
\7f666517
34755 Node: Python API
\7f668192
34756 Node: Basic Python
\7f669280
34757 Node: Exception Handling
\7f672133
34758 Node: Auto-loading
\7f673399
34759 Node: Values From Inferior
\7f675316
34760 Node: Types In Python
\7f680907
34761 Node: Pretty Printing
\7f688185
34762 Node: Selecting Pretty-Printers
\7f692365
34763 Node: Commands In Python
\7f696111
34764 Node: Functions In Python
\7f704532
34765 Node: Objfiles In Python
\7f706639
34766 Node: Frames In Python
\7f708169
34767 Node: Lazy Strings In Python
\7f710761
34768 Node: Interpreters
\7f712998
34770 Node: TUI Overview
\7f716064
34771 Node: TUI Keys
\7f718497
34772 Node: TUI Single Key Mode
\7f720801
34773 Node: TUI Commands
\7f721676
34774 Node: TUI Configuration
\7f723764
34775 Node: Emacs
\7f725060
34776 Node: GDB/MI
\7f730537
34777 Node: GDB/MI General Design
\7f732385
34778 Node: Context management
\7f734908
34779 Node: Asynchronous and non-stop modes
\7f738043
34780 Node: Thread groups
\7f740035
34781 Node: GDB/MI Command Syntax
\7f742094
34782 Node: GDB/MI Input Syntax
\7f742337
34783 Node: GDB/MI Output Syntax
\7f743891
34784 Node: GDB/MI Compatibility with CLI
\7f747463
34785 Node: GDB/MI Development and Front Ends
\7f748200
34786 Node: GDB/MI Output Records
\7f749857
34787 Node: GDB/MI Result Records
\7f750192
34788 Node: GDB/MI Stream Records
\7f751198
34789 Node: GDB/MI Async Records
\7f752463
34790 Node: GDB/MI Frame Information
\7f757350
34791 Node: GDB/MI Thread Information
\7f758428
34792 Node: GDB/MI Simple Examples
\7f759366
34793 Node: GDB/MI Command Description Format
\7f761543
34794 Node: GDB/MI Breakpoint Commands
\7f762423
34795 Node: GDB/MI Program Context
\7f779934
34796 Node: GDB/MI Thread Commands
\7f784202
34797 Node: GDB/MI Program Execution
\7f787080
34798 Node: GDB/MI Stack Manipulation
\7f798519
34799 Node: GDB/MI Variable Objects
\7f809213
34800 Ref: -var-set-format
\7f818941
34801 Ref: -var-list-children
\7f820059
34802 Ref: -var-update
\7f828236
34803 Ref: -var-set-frozen
\7f830933
34804 Ref: -var-set-update-range
\7f831729
34805 Ref: -var-set-visualizer
\7f832259
34806 Node: GDB/MI Data Manipulation
\7f833752
34807 Node: GDB/MI Tracepoint Commands
\7f848132
34808 Node: GDB/MI Symbol Query
\7f848376
34809 Node: GDB/MI File Commands
\7f849065
34810 Node: GDB/MI Target Manipulation
\7f852402
34811 Node: GDB/MI File Transfer Commands
\7f858624
34812 Node: GDB/MI Miscellaneous Commands
\7f859946
34813 Ref: -interpreter-exec
\7f868283
34814 Node: Annotations
\7f870592
34815 Node: Annotations Overview
\7f871511
34816 Node: Server Prefix
\7f873974
34817 Node: Prompting
\7f874708
34818 Node: Errors
\7f876225
34819 Node: Invalidation
\7f877121
34820 Node: Annotations for Running
\7f877598
34821 Node: Source Annotations
\7f879118
34822 Node: JIT Interface
\7f880043
34823 Node: Declarations
\7f881761
34824 Node: Registering Code
\7f883148
34825 Node: Unregistering Code
\7f884120
34826 Node: GDB Bugs
\7f884721
34827 Node: Bug Criteria
\7f885450
34828 Node: Bug Reporting
\7f886327
34829 Node: Command Line Editing
\7f893950
34830 Node: Introduction and Notation
\7f894602
34831 Node: Readline Interaction
\7f896222
34832 Node: Readline Bare Essentials
\7f897411
34833 Node: Readline Movement Commands
\7f899198
34834 Node: Readline Killing Commands
\7f900161
34835 Node: Readline Arguments
\7f902079
34836 Node: Searching
\7f903121
34837 Node: Readline Init File
\7f905270
34838 Node: Readline Init File Syntax
\7f906333
34839 Node: Conditional Init Constructs
\7f918265
34840 Node: Sample Init File
\7f920796
34841 Node: Bindable Readline Commands
\7f923911
34842 Node: Commands For Moving
\7f924966
34843 Node: Commands For History
\7f925825
34844 Node: Commands For Text
\7f928947
34845 Node: Commands For Killing
\7f931671
34846 Node: Numeric Arguments
\7f933811
34847 Node: Commands For Completion
\7f934948
34848 Node: Keyboard Macros
\7f936490
34849 Node: Miscellaneous Commands
\7f937059
34850 Node: Readline vi Mode
\7f940418
34851 Node: Using History Interactively
\7f941335
34852 Node: History Interaction
\7f941850
34853 Node: Event Designators
\7f943272
34854 Node: Word Designators
\7f944205
34855 Node: Modifiers
\7f945842
34856 Node: Formatting Documentation
\7f947067
34857 Ref: Formatting Documentation-Footnote-1
\7f950444
34858 Node: Installing GDB
\7f950532
34859 Node: Requirements
\7f951104
34860 Ref: Expat
\7f951673
34861 Node: Running Configure
\7f953808
34862 Node: Separate Objdir
\7f957527
34863 Node: Config Names
\7f960483
34864 Node: Configure Options
\7f961952
34865 Node: System-wide configuration
\7f964322
34866 Node: Maintenance Commands
\7f965617
34867 Ref: maint info breakpoints
\7f966801
34868 Node: Remote Protocol
\7f979357
34869 Node: Overview
\7f979919
34870 Ref: Binary Data
\7f982481
34871 Node: Packets
\7f984740
34872 Ref: thread-id syntax
\7f985640
34873 Ref: extended mode
\7f987085
34876 Ref: read registers packet
\7f990442
34877 Ref: cycle step packet
\7f991606
34878 Ref: write register packet
\7f993482
34879 Ref: step with signal packet
\7f994389
34880 Ref: vStopped packet
\7f1000670
34881 Ref: X packet
\7f1001013
34882 Ref: insert breakpoint or watchpoint packet
\7f1001299
34883 Node: Stop Reply Packets
\7f1004061
34884 Node: General Query Packets
\7f1008801
34885 Ref: QNonStop
\7f1016606
34886 Ref: QPassSignals
\7f1017230
34887 Ref: qSearch memory
\7f1019307
34888 Ref: QStartNoAckMode
\7f1019805
34889 Ref: qSupported
\7f1020335
34890 Ref: multiprocess extensions
\7f1028330
34891 Ref: qXfer read
\7f1031808
34892 Ref: qXfer auxiliary vector read
\7f1032302
34893 Ref: qXfer target description read
\7f1032651
34894 Ref: qXfer library list read
\7f1033095
34895 Ref: qXfer memory map read
\7f1033741
34896 Ref: qXfer siginfo read
\7f1034129
34897 Ref: qXfer spu read
\7f1034525
34898 Ref: qXfer threads read
\7f1035048
34899 Ref: qXfer osdata read
\7f1035441
34900 Ref: qXfer write
\7f1036643
34901 Ref: qXfer siginfo write
\7f1037200
34902 Ref: qXfer spu write
\7f1037596
34903 Ref: General Query Packets-Footnote-1
\7f1039683
34904 Node: Architecture-Specific Protocol Details
\7f1040010
34905 Node: Tracepoint Packets
\7f1041523
34906 Node: Host I/O Packets
\7f1050851
34907 Node: Interrupts
\7f1054993
34908 Node: Notification Packets
\7f1056896
34909 Node: Remote Non-Stop
\7f1059167
34910 Node: Packet Acknowledgment
\7f1063426
34911 Node: Examples
\7f1065541
34912 Node: File-I/O Remote Protocol Extension
\7f1066167
34913 Node: File-I/O Overview
\7f1066629
34914 Node: Protocol Basics
\7f1068826
34915 Node: The F Request Packet
\7f1071058
34916 Node: The F Reply Packet
\7f1071959
34917 Node: The Ctrl-C Message
\7f1072877
34918 Node: Console I/O
\7f1074506
34919 Node: List of Supported Calls
\7f1075723
34920 Node: open
\7f1076085
34921 Node: close
\7f1078579
34922 Node: read
\7f1078961
34923 Node: write
\7f1079568
34924 Node: lseek
\7f1080335
34925 Node: rename
\7f1081213
34926 Node: unlink
\7f1082609
34927 Node: stat/fstat
\7f1083548
34928 Node: gettimeofday
\7f1084435
34929 Node: isatty
\7f1084870
34930 Node: system
\7f1085466
34931 Node: Protocol-specific Representation of Datatypes
\7f1087008
34932 Node: Integral Datatypes
\7f1087385
34933 Node: Pointer Values
\7f1088192
34934 Node: Memory Transfer
\7f1088900
34935 Node: struct stat
\7f1089520
34936 Node: struct timeval
\7f1091722
34937 Node: Constants
\7f1092239
34938 Node: Open Flags
\7f1092688
34939 Node: mode_t Values
\7f1093029
34940 Node: Errno Values
\7f1093521
34941 Node: Lseek Flags
\7f1094332
34942 Node: Limits
\7f1094517
34943 Node: File-I/O Examples
\7f1094877
34944 Node: Library List Format
\7f1095993
34945 Node: Memory Map Format
\7f1098757
34946 Node: Thread List Format
\7f1101317
34947 Node: Agent Expressions
\7f1102104
34948 Node: General Bytecode Design
\7f1104925
34949 Node: Bytecode Descriptions
\7f1109725
34950 Node: Using Agent Expressions
\7f1121436
34951 Node: Varying Target Capabilities
\7f1123414
34952 Node: Rationale
\7f1124576
34953 Node: Trace File Format
\7f1131962
34954 Node: Target Descriptions
\7f1133943
34955 Node: Retrieving Descriptions
\7f1136003
34956 Node: Target Description Format
\7f1137088
34957 Node: Predefined Target Types
\7f1144917
34958 Node: Standard Target Features
\7f1146302
34959 Node: ARM Features
\7f1148073
34960 Node: i386 Features
\7f1149349
34961 Node: MIPS Features
\7f1150216
34962 Node: M68K Features
\7f1151161
34963 Node: PowerPC Features
\7f1151824
34964 Node: Operating System Information
\7f1153108
34965 Node: Process list
\7f1153946
34966 Node: Copying
\7f1155008
34967 Node: GNU Free Documentation License
\7f1192595
34968 Node: Index
\7f1215030