1This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo. 2 3INFO-DIR-SECTION Software development 4START-INFO-DIR-ENTRY 5* Gdb: (gdb). The GNU debugger. 6END-INFO-DIR-ENTRY 7 8 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 91998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 102010 Free Software Foundation, Inc. 11 12 Permission is granted to copy, distribute and/or modify this document 13under the terms of the GNU Free Documentation License, Version 1.3 or 14any later version published by the Free Software Foundation; with the 15Invariant Sections being "Free Software" and "Free Software Needs Free 16Documentation", with the Front-Cover Texts being "A GNU Manual," and 17with the Back-Cover Texts as in (a) below. 18 19 (a) The FSF's Back-Cover Text is: "You are free to copy and modify 20this GNU Manual. Buying copies from GNU Press supports the FSF in 21developing GNU and promoting software freedom." 22 23 This file documents the GNU debugger GDB. 24 25 This is the Tenth Edition, of `Debugging with GDB: the GNU 26Source-Level Debugger' for GDB (GDB) Version 7.3.1. 27 28 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 291998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 302010 Free Software Foundation, Inc. 31 32 Permission is granted to copy, distribute and/or modify this document 33under the terms of the GNU Free Documentation License, Version 1.3 or 34any later version published by the Free Software Foundation; with the 35Invariant Sections being "Free Software" and "Free Software Needs Free 36Documentation", with the Front-Cover Texts being "A GNU Manual," and 37with the Back-Cover Texts as in (a) below. 38 39 (a) The FSF's Back-Cover Text is: "You are free to copy and modify 40this GNU Manual. Buying copies from GNU Press supports the FSF in 41developing GNU and promoting software freedom." 42 43 44File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir) 45 46Debugging with GDB 47****************** 48 49This file describes GDB, the GNU symbolic debugger. 50 51 This is the Tenth Edition, for GDB (GDB) Version 7.3.1. 52 53 Copyright (C) 1988-2010 Free Software Foundation, Inc. 54 55 This edition of the GDB manual is dedicated to the memory of Fred 56Fish. Fred was a long-standing contributor to GDB and to Free software 57in general. We will miss him. 58 59* Menu: 60 61* Summary:: Summary of GDB 62* Sample Session:: A sample GDB session 63 64* Invocation:: Getting in and out of GDB 65* Commands:: GDB commands 66* Running:: Running programs under GDB 67* Stopping:: Stopping and continuing 68* Reverse Execution:: Running programs backward 69* Process Record and Replay:: Recording inferior's execution and replaying it 70* Stack:: Examining the stack 71* Source:: Examining source files 72* Data:: Examining data 73* Optimized Code:: Debugging optimized code 74* Macros:: Preprocessor Macros 75* Tracepoints:: Debugging remote targets non-intrusively 76* Overlays:: Debugging programs that use overlays 77 78* Languages:: Using GDB with different languages 79 80* Symbols:: Examining the symbol table 81* Altering:: Altering execution 82* GDB Files:: GDB files 83* Targets:: Specifying a debugging target 84* Remote Debugging:: Debugging remote programs 85* Configurations:: Configuration-specific information 86* Controlling GDB:: Controlling GDB 87* Extending GDB:: Extending GDB 88* Interpreters:: Command Interpreters 89* TUI:: GDB Text User Interface 90* Emacs:: Using GDB under GNU Emacs 91* GDB/MI:: GDB's Machine Interface. 92* Annotations:: GDB's annotation interface. 93* JIT Interface:: Using the JIT debugging interface. 94 95* GDB Bugs:: Reporting bugs in GDB 96 97 98* Command Line Editing:: Command Line Editing 99* Using History Interactively:: Using History Interactively 100* In Memoriam:: In Memoriam 101* Formatting Documentation:: How to format and print GDB documentation 102* Installing GDB:: Installing GDB 103* Maintenance Commands:: Maintenance Commands 104* Remote Protocol:: GDB Remote Serial Protocol 105* Agent Expressions:: The GDB Agent Expression Mechanism 106* Target Descriptions:: How targets can describe themselves to 107 GDB 108* Operating System Information:: Getting additional information from 109 the operating system 110* Trace File Format:: GDB trace file format 111* Copying:: GNU General Public License says 112 how you can copy and share GDB 113* GNU Free Documentation License:: The license for this documentation 114* Index:: Index 115 116 117File: gdb.info, Node: Summary, Next: Sample Session, Prev: Top, Up: Top 118 119Summary of GDB 120************** 121 122The purpose of a debugger such as GDB is to allow you to see what is 123going on "inside" another program while it executes--or what another 124program was doing at the moment it crashed. 125 126 GDB can do four main kinds of things (plus other things in support of 127these) to help you catch bugs in the act: 128 129 * Start your program, specifying anything that might affect its 130 behavior. 131 132 * Make your program stop on specified conditions. 133 134 * Examine what has happened, when your program has stopped. 135 136 * Change things in your program, so you can experiment with 137 correcting the effects of one bug and go on to learn about another. 138 139 You can use GDB to debug programs written in C and C++. For more 140information, see *Note Supported Languages: Supported Languages. For 141more information, see *Note C and C++: C. 142 143 Support for D is partial. For information on D, see *Note D: D. 144 145 Support for Modula-2 is partial. For information on Modula-2, see 146*Note Modula-2: Modula-2. 147 148 Support for OpenCL C is partial. For information on OpenCL C, see 149*Note OpenCL C: OpenCL C. 150 151 Debugging Pascal programs which use sets, subranges, file variables, 152or nested functions does not currently work. GDB does not support 153entering expressions, printing values, or similar features using Pascal 154syntax. 155 156 GDB can be used to debug programs written in Fortran, although it 157may be necessary to refer to some variables with a trailing underscore. 158 159 GDB can be used to debug programs written in Objective-C, using 160either the Apple/NeXT or the GNU Objective-C runtime. 161 162* Menu: 163 164* Free Software:: Freely redistributable software 165* Contributors:: Contributors to GDB 166 167 168File: gdb.info, Node: Free Software, Next: Contributors, Up: Summary 169 170Free Software 171============= 172 173GDB is "free software", protected by the GNU General Public License 174(GPL). The GPL gives you the freedom to copy or adapt a licensed 175program--but every person getting a copy also gets with it the freedom 176to modify that copy (which means that they must get access to the 177source code), and the freedom to distribute further copies. Typical 178software companies use copyrights to limit your freedoms; the Free 179Software Foundation uses the GPL to preserve these freedoms. 180 181 Fundamentally, the General Public License is a license which says 182that you have these freedoms and that you cannot take these freedoms 183away from anyone else. 184 185Free Software Needs Free Documentation 186====================================== 187 188The biggest deficiency in the free software community today is not in 189the software--it is the lack of good free documentation that we can 190include with the free software. Many of our most important programs do 191not come with free reference manuals and free introductory texts. 192Documentation is an essential part of any software package; when an 193important free software package does not come with a free manual and a 194free tutorial, that is a major gap. We have many such gaps today. 195 196 Consider Perl, for instance. The tutorial manuals that people 197normally use are non-free. How did this come about? Because the 198authors of those manuals published them with restrictive terms--no 199copying, no modification, source files not available--which exclude 200them from the free software world. 201 202 That wasn't the first time this sort of thing happened, and it was 203far from the last. Many times we have heard a GNU user eagerly 204describe a manual that he is writing, his intended contribution to the 205community, only to learn that he had ruined everything by signing a 206publication contract to make it non-free. 207 208 Free documentation, like free software, is a matter of freedom, not 209price. The problem with the non-free manual is not that publishers 210charge a price for printed copies--that in itself is fine. (The Free 211Software Foundation sells printed copies of manuals, too.) The problem 212is the restrictions on the use of the manual. Free manuals are 213available in source code form, and give you permission to copy and 214modify. Non-free manuals do not allow this. 215 216 The criteria of freedom for a free manual are roughly the same as for 217free software. Redistribution (including the normal kinds of 218commercial redistribution) must be permitted, so that the manual can 219accompany every copy of the program, both on-line and on paper. 220 221 Permission for modification of the technical content is crucial too. 222When people modify the software, adding or changing features, if they 223are conscientious they will change the manual too--so they can provide 224accurate and clear documentation for the modified program. A manual 225that leaves you no choice but to write a new manual to document a 226changed version of the program is not really available to our community. 227 228 Some kinds of limits on the way modification is handled are 229acceptable. For example, requirements to preserve the original 230author's copyright notice, the distribution terms, or the list of 231authors, are ok. It is also no problem to require modified versions to 232include notice that they were modified. Even entire sections that may 233not be deleted or changed are acceptable, as long as they deal with 234nontechnical topics (like this one). These kinds of restrictions are 235acceptable because they don't obstruct the community's normal use of 236the manual. 237 238 However, it must be possible to modify all the _technical_ content 239of the manual, and then distribute the result in all the usual media, 240through all the usual channels. Otherwise, the restrictions obstruct 241the use of the manual, it is not free, and we need another manual to 242replace it. 243 244 Please spread the word about this issue. Our community continues to 245lose manuals to proprietary publishing. If we spread the word that 246free software needs free reference manuals and free tutorials, perhaps 247the next person who wants to contribute by writing documentation will 248realize, before it is too late, that only free manuals contribute to 249the free software community. 250 251 If you are writing documentation, please insist on publishing it 252under the GNU Free Documentation License or another free documentation 253license. Remember that this decision requires your approval--you don't 254have to let the publisher decide. Some commercial publishers will use 255a free license if you insist, but they will not propose the option; it 256is up to you to raise the issue and say firmly that this is what you 257want. If the publisher you are dealing with refuses, please try other 258publishers. If you're not sure whether a proposed license is free, 259write to <licensing@gnu.org>. 260 261 You can encourage commercial publishers to sell more free, copylefted 262manuals and tutorials by buying them, and particularly by buying copies 263from the publishers that paid for their writing or for major 264improvements. Meanwhile, try to avoid buying non-free documentation at 265all. Check the distribution terms of a manual before you buy it, and 266insist that whoever seeks your business must respect your freedom. 267Check the history of the book, and try to reward the publishers that 268have paid or pay the authors to work on it. 269 270 The Free Software Foundation maintains a list of free documentation 271published by other publishers, at 272`http://www.fsf.org/doc/other-free-books.html'. 273 274 275File: gdb.info, Node: Contributors, Prev: Free Software, Up: Summary 276 277Contributors to GDB 278=================== 279 280Richard Stallman was the original author of GDB, and of many other GNU 281programs. Many others have contributed to its development. This 282section attempts to credit major contributors. One of the virtues of 283free software is that everyone is free to contribute to it; with 284regret, we cannot actually acknowledge everyone here. The file 285`ChangeLog' in the GDB distribution approximates a blow-by-blow account. 286 287 Changes much prior to version 2.0 are lost in the mists of time. 288 289 _Plea:_ Additions to this section are particularly welcome. If you 290 or your friends (or enemies, to be evenhanded) have been unfairly 291 omitted from this list, we would like to add your names! 292 293 So that they may not regard their many labors as thankless, we 294particularly thank those who shepherded GDB through major releases: 295Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim 296Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs 297(release 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, 298and 4.9); Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, 299and 4.4); John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim 300Kingdon (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, 3013.1, and 3.0). 302 303 Richard Stallman, assisted at various times by Peter TerMaat, Chris 304Hanson, and Richard Mlynarik, handled releases through 2.8. 305 306 Michael Tiemann is the author of most of the GNU C++ support in GDB, 307with significant additional contributions from Per Bothner and Daniel 308Berlin. James Clark wrote the GNU C++ demangler. Early work on C++ 309was by Peter TerMaat (who also did much general update work leading to 310release 3.0). 311 312 GDB uses the BFD subroutine library to examine multiple object-file 313formats; BFD was a joint project of David V. Henkel-Wallace, Rich 314Pixley, Steve Chamberlain, and John Gilmore. 315 316 David Johnson wrote the original COFF support; Pace Willison did the 317original support for encapsulated COFF. 318 319 Brent Benson of Harris Computer Systems contributed DWARF 2 support. 320 321 Adam de Boor and Bradley Davis contributed the ISI Optimum V support. 322Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS 323support. Jean-Daniel Fekete contributed Sun 386i support. Chris 324Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki 325Hasei contributed Sony/News OS 3 support. David Johnson contributed 326Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support. 327Jeff Law contributed HP PA and SOM support. Keith Packard contributed 328NS32K support. Doug Rabson contributed Acorn Risc Machine support. 329Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith 330contributed Convex support (and Fortran debugging). Jonathan Stone 331contributed Pyramid support. Michael Tiemann contributed SPARC support. 332Tim Tucker contributed support for the Gould NP1 and Gould Powernode. 333Pace Willison contributed Intel 386 support. Jay Vosburgh contributed 334Symmetry support. Marko Mlinar contributed OpenRISC 1000 support. 335 336 Andreas Schwab contributed M68K GNU/Linux support. 337 338 Rich Schaefer and Peter Schauer helped with support of SunOS shared 339libraries. 340 341 Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about 342several machine instruction sets. 343 344 Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped 345develop remote debugging. Intel Corporation, Wind River Systems, AMD, 346and ARM contributed remote debugging modules for the i960, VxWorks, 347A29K UDI, and RDI targets, respectively. 348 349 Brian Fox is the author of the readline libraries providing 350command-line editing and command history. 351 352 Andrew Beers of SUNY Buffalo wrote the language-switching code, the 353Modula-2 support, and contributed the Languages chapter of this manual. 354 355 Fred Fish wrote most of the support for Unix System Vr4. He also 356enhanced the command-completion support to cover C++ overloaded symbols. 357 358 Hitachi America (now Renesas America), Ltd. sponsored the support for 359H8/300, H8/500, and Super-H processors. 360 361 NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx 362processors. 363 364 Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and 365M32R/D processors. 366 367 Toshiba sponsored the support for the TX39 Mips processor. 368 369 Matsushita sponsored the support for the MN10200 and MN10300 370processors. 371 372 Fujitsu sponsored the support for SPARClite and FR30 processors. 373 374 Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware 375watchpoints. 376 377 Michael Snyder added support for tracepoints. 378 379 Stu Grossman wrote gdbserver. 380 381 Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly 382innumerable bug fixes and cleanups throughout GDB. 383 384 The following people at the Hewlett-Packard Company contributed 385support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 386(narrow mode), HP's implementation of kernel threads, HP's aC++ 387compiler, and the Text User Interface (nee Terminal User Interface): 388Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, 389Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase 390provided HP-specific information in this manual. 391 392 DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert 393Hoehne made significant contributions to the DJGPP port. 394 395 Cygnus Solutions has sponsored GDB maintenance and much of its 396development since 1991. Cygnus engineers who have worked on GDB 397fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin 398Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim 399Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, 400Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek 401Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In 402addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, 403JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug 404Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff 405Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, 406Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin 407Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela 408Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David 409Zuhn have made contributions both large and small. 410 411 Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for 412Cygnus Solutions, implemented the original GDB/MI interface. 413 414 Jim Blandy added support for preprocessor macros, while working for 415Red Hat. 416 417 Andrew Cagney designed GDB's architecture vector. Many people 418including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek, 419Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto, 420Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna 421Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration 422of old architectures to this new framework. 423 424 Andrew Cagney completely re-designed and re-implemented GDB's 425unwinder framework, this consisting of a fresh new design featuring 426frame IDs, independent frame sniffers, and the sentinel frame. Mark 427Kettenis implemented the DWARF 2 unwinder, Jeff Johnston the libunwind 428unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad 429unwinders. The architecture-specific changes, each involving a 430complete rewrite of the architecture's frame code, were carried out by 431Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane 432Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel 433Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei 434Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich 435Weigand. 436 437 Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from 438Tensilica, Inc. contributed support for Xtensa processors. Others who 439have worked on the Xtensa port of GDB in the past include Steve Tjiang, 440John Newlin, and Scott Foehner. 441 442 Michael Eager and staff of Xilinx, Inc., contributed support for the 443Xilinx MicroBlaze architecture. 444 445 446File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top 447 4481 A Sample GDB Session 449********************** 450 451You can use this manual at your leisure to read all about GDB. 452However, a handful of commands are enough to get started using the 453debugger. This chapter illustrates those commands. 454 455 One of the preliminary versions of GNU `m4' (a generic macro 456processor) exhibits the following bug: sometimes, when we change its 457quote strings from the default, the commands used to capture one macro 458definition within another stop working. In the following short `m4' 459session, we define a macro `foo' which expands to `0000'; we then use 460the `m4' built-in `defn' to define `bar' as the same thing. However, 461when we change the open quote string to `<QUOTE>' and the close quote 462string to `<UNQUOTE>', the same procedure fails to define a new synonym 463`baz': 464 465 $ cd gnu/m4 466 $ ./m4 467 define(foo,0000) 468 469 foo 470 0000 471 define(bar,defn(`foo')) 472 473 bar 474 0000 475 changequote(<QUOTE>,<UNQUOTE>) 476 477 define(baz,defn(<QUOTE>foo<UNQUOTE>)) 478 baz 479 Ctrl-d 480 m4: End of input: 0: fatal error: EOF in string 481 482Let us use GDB to try to see what is going on. 483 484 $ gdb m4 485 GDB is free software and you are welcome to distribute copies 486 of it under certain conditions; type "show copying" to see 487 the conditions. 488 There is absolutely no warranty for GDB; type "show warranty" 489 for details. 490 491 GDB 7.3.1, Copyright 1999 Free Software Foundation, Inc... 492 (gdb) 493 494GDB reads only enough symbol data to know where to find the rest when 495needed; as a result, the first prompt comes up very quickly. We now 496tell GDB to use a narrower display width than usual, so that examples 497fit in this manual. 498 499 (gdb) set width 70 500 501We need to see how the `m4' built-in `changequote' works. Having 502looked at the source, we know the relevant subroutine is 503`m4_changequote', so we set a breakpoint there with the GDB `break' 504command. 505 506 (gdb) break m4_changequote 507 Breakpoint 1 at 0x62f4: file builtin.c, line 879. 508 509Using the `run' command, we start `m4' running under GDB control; as 510long as control does not reach the `m4_changequote' subroutine, the 511program runs as usual: 512 513 (gdb) run 514 Starting program: /work/Editorial/gdb/gnu/m4/m4 515 define(foo,0000) 516 517 foo 518 0000 519 520To trigger the breakpoint, we call `changequote'. GDB suspends 521execution of `m4', displaying information about the context where it 522stops. 523 524 changequote(<QUOTE>,<UNQUOTE>) 525 526 Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) 527 at builtin.c:879 528 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) 529 530Now we use the command `n' (`next') to advance execution to the next 531line of the current function. 532 533 (gdb) n 534 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ 535 : nil, 536 537`set_quotes' looks like a promising subroutine. We can go into it by 538using the command `s' (`step') instead of `next'. `step' goes to the 539next line to be executed in _any_ subroutine, so it steps into 540`set_quotes'. 541 542 (gdb) s 543 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 544 at input.c:530 545 530 if (lquote != def_lquote) 546 547The display that shows the subroutine where `m4' is now suspended (and 548its arguments) is called a stack frame display. It shows a summary of 549the stack. We can use the `backtrace' command (which can also be 550spelled `bt'), to see where we are in the stack as a whole: the 551`backtrace' command displays a stack frame for each active subroutine. 552 553 (gdb) bt 554 #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 555 at input.c:530 556 #1 0x6344 in m4_changequote (argc=3, argv=0x33c70) 557 at builtin.c:882 558 #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 559 #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) 560 at macro.c:71 561 #4 0x79dc in expand_input () at macro.c:40 562 #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 563 564We step through a few more lines to see what happens. The first two 565times, we can use `s'; the next two times we use `n' to avoid falling 566into the `xstrdup' subroutine. 567 568 (gdb) s 569 0x3b5c 532 if (rquote != def_rquote) 570 (gdb) s 571 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ 572 def_lquote : xstrdup(lq); 573 (gdb) n 574 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 575 : xstrdup(rq); 576 (gdb) n 577 538 len_lquote = strlen(rquote); 578 579The last line displayed looks a little odd; we can examine the variables 580`lquote' and `rquote' to see if they are in fact the new left and right 581quotes we specified. We use the command `p' (`print') to see their 582values. 583 584 (gdb) p lquote 585 $1 = 0x35d40 "<QUOTE>" 586 (gdb) p rquote 587 $2 = 0x35d50 "<UNQUOTE>" 588 589`lquote' and `rquote' are indeed the new left and right quotes. To 590look at some context, we can display ten lines of source surrounding 591the current line with the `l' (`list') command. 592 593 (gdb) l 594 533 xfree(rquote); 595 534 596 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ 597 : xstrdup (lq); 598 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 599 : xstrdup (rq); 600 537 601 538 len_lquote = strlen(rquote); 602 539 len_rquote = strlen(lquote); 603 540 } 604 541 605 542 void 606 607Let us step past the two lines that set `len_lquote' and `len_rquote', 608and then examine the values of those variables. 609 610 (gdb) n 611 539 len_rquote = strlen(lquote); 612 (gdb) n 613 540 } 614 (gdb) p len_lquote 615 $3 = 9 616 (gdb) p len_rquote 617 $4 = 7 618 619That certainly looks wrong, assuming `len_lquote' and `len_rquote' are 620meant to be the lengths of `lquote' and `rquote' respectively. We can 621set them to better values using the `p' command, since it can print the 622value of any expression--and that expression can include subroutine 623calls and assignments. 624 625 (gdb) p len_lquote=strlen(lquote) 626 $5 = 7 627 (gdb) p len_rquote=strlen(rquote) 628 $6 = 9 629 630Is that enough to fix the problem of using the new quotes with the `m4' 631built-in `defn'? We can allow `m4' to continue executing with the `c' 632(`continue') command, and then try the example that caused trouble 633initially: 634 635 (gdb) c 636 Continuing. 637 638 define(baz,defn(<QUOTE>foo<UNQUOTE>)) 639 640 baz 641 0000 642 643Success! The new quotes now work just as well as the default ones. The 644problem seems to have been just the two typos defining the wrong 645lengths. We allow `m4' exit by giving it an EOF as input: 646 647 Ctrl-d 648 Program exited normally. 649 650The message `Program exited normally.' is from GDB; it indicates `m4' 651has finished executing. We can end our GDB session with the GDB `quit' 652command. 653 654 (gdb) quit 655 656 657File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top 658 6592 Getting In and Out of GDB 660*************************** 661 662This chapter discusses how to start GDB, and how to get out of it. The 663essentials are: 664 * type `gdb' to start GDB. 665 666 * type `quit' or `Ctrl-d' to exit. 667 668* Menu: 669 670* Invoking GDB:: How to start GDB 671* Quitting GDB:: How to quit GDB 672* Shell Commands:: How to use shell commands inside GDB 673* Logging Output:: How to log GDB's output to a file 674 675 676File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation 677 6782.1 Invoking GDB 679================ 680 681Invoke GDB by running the program `gdb'. Once started, GDB reads 682commands from the terminal until you tell it to exit. 683 684 You can also run `gdb' with a variety of arguments and options, to 685specify more of your debugging environment at the outset. 686 687 The command-line options described here are designed to cover a 688variety of situations; in some environments, some of these options may 689effectively be unavailable. 690 691 The most usual way to start GDB is with one argument, specifying an 692executable program: 693 694 gdb PROGRAM 695 696You can also start with both an executable program and a core file 697specified: 698 699 gdb PROGRAM CORE 700 701 You can, instead, specify a process ID as a second argument, if you 702want to debug a running process: 703 704 gdb PROGRAM 1234 705 706would attach GDB to process `1234' (unless you also have a file named 707`1234'; GDB does check for a core file first). 708 709 Taking advantage of the second command-line argument requires a 710fairly complete operating system; when you use GDB as a remote debugger 711attached to a bare board, there may not be any notion of "process", and 712there is often no way to get a core dump. GDB will warn you if it is 713unable to attach or to read core dumps. 714 715 You can optionally have `gdb' pass any arguments after the 716executable file to the inferior using `--args'. This option stops 717option processing. 718 gdb --args gcc -O2 -c foo.c 719 This will cause `gdb' to debug `gcc', and to set `gcc''s 720command-line arguments (*note Arguments::) to `-O2 -c foo.c'. 721 722 You can run `gdb' without printing the front material, which 723describes GDB's non-warranty, by specifying `-silent': 724 725 gdb -silent 726 727You can further control how GDB starts up by using command-line 728options. GDB itself can remind you of the options available. 729 730Type 731 732 gdb -help 733 734to display all available options and briefly describe their use (`gdb 735-h' is a shorter equivalent). 736 737 All options and command line arguments you give are processed in 738sequential order. The order makes a difference when the `-x' option is 739used. 740 741* Menu: 742 743* File Options:: Choosing files 744* Mode Options:: Choosing modes 745* Startup:: What GDB does during startup 746 747 748File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB 749 7502.1.1 Choosing Files 751-------------------- 752 753When GDB starts, it reads any arguments other than options as 754specifying an executable file and core file (or process ID). This is 755the same as if the arguments were specified by the `-se' and `-c' (or 756`-p') options respectively. (GDB reads the first argument that does 757not have an associated option flag as equivalent to the `-se' option 758followed by that argument; and the second argument that does not have 759an associated option flag, if any, as equivalent to the `-c'/`-p' 760option followed by that argument.) If the second argument begins with 761a decimal digit, GDB will first attempt to attach to it as a process, 762and if that fails, attempt to open it as a corefile. If you have a 763corefile whose name begins with a digit, you can prevent GDB from 764treating it as a pid by prefixing it with `./', e.g. `./12345'. 765 766 If GDB has not been configured to included core file support, such 767as for most embedded targets, then it will complain about a second 768argument and ignore it. 769 770 Many options have both long and short forms; both are shown in the 771following list. GDB also recognizes the long forms if you truncate 772them, so long as enough of the option is present to be unambiguous. 773(If you prefer, you can flag option arguments with `--' rather than 774`-', though we illustrate the more usual convention.) 775 776`-symbols FILE' 777`-s FILE' 778 Read symbol table from file FILE. 779 780`-exec FILE' 781`-e FILE' 782 Use file FILE as the executable file to execute when appropriate, 783 and for examining pure data in conjunction with a core dump. 784 785`-se FILE' 786 Read symbol table from file FILE and use it as the executable file. 787 788`-core FILE' 789`-c FILE' 790 Use file FILE as a core dump to examine. 791 792`-pid NUMBER' 793`-p NUMBER' 794 Connect to process ID NUMBER, as with the `attach' command. 795 796`-command FILE' 797`-x FILE' 798 Execute commands from file FILE. The contents of this file is 799 evaluated exactly as the `source' command would. *Note Command 800 files: Command Files. 801 802`-eval-command COMMAND' 803`-ex COMMAND' 804 Execute a single GDB command. 805 806 This option may be used multiple times to call multiple commands. 807 It may also be interleaved with `-command' as required. 808 809 gdb -ex 'target sim' -ex 'load' \ 810 -x setbreakpoints -ex 'run' a.out 811 812`-directory DIRECTORY' 813`-d DIRECTORY' 814 Add DIRECTORY to the path to search for source and script files. 815 816`-r' 817`-readnow' 818 Read each symbol file's entire symbol table immediately, rather 819 than the default, which is to read it incrementally as it is 820 needed. This makes startup slower, but makes future operations 821 faster. 822 823 824 825File: gdb.info, Node: Mode Options, Next: Startup, Prev: File Options, Up: Invoking GDB 826 8272.1.2 Choosing Modes 828-------------------- 829 830You can run GDB in various alternative modes--for example, in batch 831mode or quiet mode. 832 833`-nx' 834`-n' 835 Do not execute commands found in any initialization files. 836 Normally, GDB executes the commands in these files after all the 837 command options and arguments have been processed. *Note Command 838 Files: Command Files. 839 840`-quiet' 841`-silent' 842`-q' 843 "Quiet". Do not print the introductory and copyright messages. 844 These messages are also suppressed in batch mode. 845 846`-batch' 847 Run in batch mode. Exit with status `0' after processing all the 848 command files specified with `-x' (and all commands from 849 initialization files, if not inhibited with `-n'). Exit with 850 nonzero status if an error occurs in executing the GDB commands in 851 the command files. Batch mode also disables pagination, sets 852 unlimited terminal width and height *note Screen Size::, and acts 853 as if `set confirm off' were in effect (*note Messages/Warnings::). 854 855 Batch mode may be useful for running GDB as a filter, for example 856 to download and run a program on another computer; in order to 857 make this more useful, the message 858 859 Program exited normally. 860 861 (which is ordinarily issued whenever a program running under GDB 862 control terminates) is not issued when running in batch mode. 863 864`-batch-silent' 865 Run in batch mode exactly like `-batch', but totally silently. All 866 GDB output to `stdout' is prevented (`stderr' is unaffected). 867 This is much quieter than `-silent' and would be useless for an 868 interactive session. 869 870 This is particularly useful when using targets that give `Loading 871 section' messages, for example. 872 873 Note that targets that give their output via GDB, as opposed to 874 writing directly to `stdout', will also be made silent. 875 876`-return-child-result' 877 The return code from GDB will be the return code from the child 878 process (the process being debugged), with the following 879 exceptions: 880 881 * GDB exits abnormally. E.g., due to an incorrect argument or 882 an internal error. In this case the exit code is the same as 883 it would have been without `-return-child-result'. 884 885 * The user quits with an explicit value. E.g., `quit 1'. 886 887 * The child process never runs, or is not allowed to terminate, 888 in which case the exit code will be -1. 889 890 This option is useful in conjunction with `-batch' or 891 `-batch-silent', when GDB is being used as a remote program loader 892 or simulator interface. 893 894`-nowindows' 895`-nw' 896 "No windows". If GDB comes with a graphical user interface (GUI) 897 built in, then this option tells GDB to only use the command-line 898 interface. If no GUI is available, this option has no effect. 899 900`-windows' 901`-w' 902 If GDB includes a GUI, then this option requires it to be used if 903 possible. 904 905`-cd DIRECTORY' 906 Run GDB using DIRECTORY as its working directory, instead of the 907 current directory. 908 909`-data-directory DIRECTORY' 910 Run GDB using DIRECTORY as its data directory. The data directory 911 is where GDB searches for its auxiliary files. *Note Data Files::. 912 913`-fullname' 914`-f' 915 GNU Emacs sets this option when it runs GDB as a subprocess. It 916 tells GDB to output the full file name and line number in a 917 standard, recognizable fashion each time a stack frame is 918 displayed (which includes each time your program stops). This 919 recognizable format looks like two `\032' characters, followed by 920 the file name, line number and character position separated by 921 colons, and a newline. The Emacs-to-GDB interface program uses 922 the two `\032' characters as a signal to display the source code 923 for the frame. 924 925`-epoch' 926 The Epoch Emacs-GDB interface sets this option when it runs GDB as 927 a subprocess. It tells GDB to modify its print routines so as to 928 allow Epoch to display values of expressions in a separate window. 929 930`-annotate LEVEL' 931 This option sets the "annotation level" inside GDB. Its effect is 932 identical to using `set annotate LEVEL' (*note Annotations::). 933 The annotation LEVEL controls how much information GDB prints 934 together with its prompt, values of expressions, source lines, and 935 other types of output. Level 0 is the normal, level 1 is for use 936 when GDB is run as a subprocess of GNU Emacs, level 3 is the 937 maximum annotation suitable for programs that control GDB, and 938 level 2 has been deprecated. 939 940 The annotation mechanism has largely been superseded by GDB/MI 941 (*note GDB/MI::). 942 943`--args' 944 Change interpretation of command line so that arguments following 945 the executable file are passed as command line arguments to the 946 inferior. This option stops option processing. 947 948`-baud BPS' 949`-b BPS' 950 Set the line speed (baud rate or bits per second) of any serial 951 interface used by GDB for remote debugging. 952 953`-l TIMEOUT' 954 Set the timeout (in seconds) of any communication used by GDB for 955 remote debugging. 956 957`-tty DEVICE' 958`-t DEVICE' 959 Run using DEVICE for your program's standard input and output. 960 961`-tui' 962 Activate the "Text User Interface" when starting. The Text User 963 Interface manages several text windows on the terminal, showing 964 source, assembly, registers and GDB command outputs (*note GDB 965 Text User Interface: TUI.). Alternatively, the Text User 966 Interface can be enabled by invoking the program `gdbtui'. Do not 967 use this option if you run GDB from Emacs (*note Using GDB under 968 GNU Emacs: Emacs.). 969 970`-interpreter INTERP' 971 Use the interpreter INTERP for interface with the controlling 972 program or device. This option is meant to be set by programs 973 which communicate with GDB using it as a back end. *Note Command 974 Interpreters: Interpreters. 975 976 `--interpreter=mi' (or `--interpreter=mi2') causes GDB to use the 977 "GDB/MI interface" (*note The GDB/MI Interface: GDB/MI.) included 978 since GDB version 6.0. The previous GDB/MI interface, included in 979 GDB version 5.3 and selected with `--interpreter=mi1', is 980 deprecated. Earlier GDB/MI interfaces are no longer supported. 981 982`-write' 983 Open the executable and core files for both reading and writing. 984 This is equivalent to the `set write on' command inside GDB (*note 985 Patching::). 986 987`-statistics' 988 This option causes GDB to print statistics about time and memory 989 usage after it completes each command and returns to the prompt. 990 991`-version' 992 This option causes GDB to print its version number and no-warranty 993 blurb, and exit. 994 995 996 997File: gdb.info, Node: Startup, Prev: Mode Options, Up: Invoking GDB 998 9992.1.3 What GDB Does During Startup 1000---------------------------------- 1001 1002Here's the description of what GDB does during session startup: 1003 1004 1. Sets up the command interpreter as specified by the command line 1005 (*note interpreter: Mode Options.). 1006 1007 2. Reads the system-wide "init file" (if `--with-system-gdbinit' was 1008 used when building GDB; *note System-wide configuration and 1009 settings: System-wide configuration.) and executes all the 1010 commands in that file. 1011 1012 3. Reads the init file (if any) in your home directory(1) and 1013 executes all the commands in that file. 1014 1015 4. Processes command line options and operands. 1016 1017 5. Reads and executes the commands from init file (if any) in the 1018 current working directory. This is only done if the current 1019 directory is different from your home directory. Thus, you can 1020 have more than one init file, one generic in your home directory, 1021 and another, specific to the program you are debugging, in the 1022 directory where you invoke GDB. 1023 1024 6. If the command line specified a program to debug, or a process to 1025 attach to, or a core file, GDB loads any auto-loaded scripts 1026 provided for the program or for its loaded shared libraries. 1027 *Note Auto-loading::. 1028 1029 If you wish to disable the auto-loading during startup, you must 1030 do something like the following: 1031 1032 $ gdb -ex "set auto-load-scripts off" -ex "file myprogram" 1033 1034 The following does not work because the auto-loading is turned off 1035 too late: 1036 1037 $ gdb -ex "set auto-load-scripts off" myprogram 1038 1039 7. Reads command files specified by the `-x' option. *Note Command 1040 Files::, for more details about GDB command files. 1041 1042 8. Reads the command history recorded in the "history file". *Note 1043 Command History::, for more details about the command history and 1044 the files where GDB records it. 1045 1046 Init files use the same syntax as "command files" (*note Command 1047Files::) and are processed by GDB in the same way. The init file in 1048your home directory can set options (such as `set complaints') that 1049affect subsequent processing of command line options and operands. 1050Init files are not executed if you use the `-nx' option (*note Choosing 1051Modes: Mode Options.). 1052 1053 To display the list of init files loaded by gdb at startup, you can 1054use `gdb --help'. 1055 1056 The GDB init files are normally called `.gdbinit'. The DJGPP port 1057of GDB uses the name `gdb.ini', due to the limitations of file names 1058imposed by DOS filesystems. The Windows ports of GDB use the standard 1059name, but if they find a `gdb.ini' file, they warn you about that and 1060suggest to rename the file to the standard name. 1061 1062 ---------- Footnotes ---------- 1063 1064 (1) On DOS/Windows systems, the home directory is the one pointed to 1065by the `HOME' environment variable. 1066 1067 1068File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation 1069 10702.2 Quitting GDB 1071================ 1072 1073`quit [EXPRESSION]' 1074`q' 1075 To exit GDB, use the `quit' command (abbreviated `q'), or type an 1076 end-of-file character (usually `Ctrl-d'). If you do not supply 1077 EXPRESSION, GDB will terminate normally; otherwise it will 1078 terminate using the result of EXPRESSION as the error code. 1079 1080 An interrupt (often `Ctrl-c') does not exit from GDB, but rather 1081terminates the action of any GDB command that is in progress and 1082returns to GDB command level. It is safe to type the interrupt 1083character at any time because GDB does not allow it to take effect 1084until a time when it is safe. 1085 1086 If you have been using GDB to control an attached process or device, 1087you can release it with the `detach' command (*note Debugging an 1088Already-running Process: Attach.). 1089 1090 1091File: gdb.info, Node: Shell Commands, Next: Logging Output, Prev: Quitting GDB, Up: Invocation 1092 10932.3 Shell Commands 1094================== 1095 1096If you need to execute occasional shell commands during your debugging 1097session, there is no need to leave or suspend GDB; you can just use the 1098`shell' command. 1099 1100`shell COMMAND STRING' 1101 Invoke a standard shell to execute COMMAND STRING. If it exists, 1102 the environment variable `SHELL' determines which shell to run. 1103 Otherwise GDB uses the default shell (`/bin/sh' on Unix systems, 1104 `COMMAND.COM' on MS-DOS, etc.). 1105 1106 The utility `make' is often needed in development environments. You 1107do not have to use the `shell' command for this purpose in GDB: 1108 1109`make MAKE-ARGS' 1110 Execute the `make' program with the specified arguments. This is 1111 equivalent to `shell make MAKE-ARGS'. 1112 1113 1114File: gdb.info, Node: Logging Output, Prev: Shell Commands, Up: Invocation 1115 11162.4 Logging Output 1117================== 1118 1119You may want to save the output of GDB commands to a file. There are 1120several commands to control GDB's logging. 1121 1122`set logging on' 1123 Enable logging. 1124 1125`set logging off' 1126 Disable logging. 1127 1128`set logging file FILE' 1129 Change the name of the current logfile. The default logfile is 1130 `gdb.txt'. 1131 1132`set logging overwrite [on|off]' 1133 By default, GDB will append to the logfile. Set `overwrite' if 1134 you want `set logging on' to overwrite the logfile instead. 1135 1136`set logging redirect [on|off]' 1137 By default, GDB output will go to both the terminal and the 1138 logfile. Set `redirect' if you want output to go only to the log 1139 file. 1140 1141`show logging' 1142 Show the current values of the logging settings. 1143 1144 1145File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top 1146 11473 GDB Commands 1148************** 1149 1150You can abbreviate a GDB command to the first few letters of the command 1151name, if that abbreviation is unambiguous; and you can repeat certain 1152GDB commands by typing just <RET>. You can also use the <TAB> key to 1153get GDB to fill out the rest of a word in a command (or to show you the 1154alternatives available, if there is more than one possibility). 1155 1156* Menu: 1157 1158* Command Syntax:: How to give commands to GDB 1159* Completion:: Command completion 1160* Help:: How to ask GDB for help 1161 1162 1163File: gdb.info, Node: Command Syntax, Next: Completion, Up: Commands 1164 11653.1 Command Syntax 1166================== 1167 1168A GDB command is a single line of input. There is no limit on how long 1169it can be. It starts with a command name, which is followed by 1170arguments whose meaning depends on the command name. For example, the 1171command `step' accepts an argument which is the number of times to 1172step, as in `step 5'. You can also use the `step' command with no 1173arguments. Some commands do not allow any arguments. 1174 1175 GDB command names may always be truncated if that abbreviation is 1176unambiguous. Other possible command abbreviations are listed in the 1177documentation for individual commands. In some cases, even ambiguous 1178abbreviations are allowed; for example, `s' is specially defined as 1179equivalent to `step' even though there are other commands whose names 1180start with `s'. You can test abbreviations by using them as arguments 1181to the `help' command. 1182 1183 A blank line as input to GDB (typing just <RET>) means to repeat the 1184previous command. Certain commands (for example, `run') will not 1185repeat this way; these are commands whose unintentional repetition 1186might cause trouble and which you are unlikely to want to repeat. 1187User-defined commands can disable this feature; see *Note dont-repeat: 1188Define. 1189 1190 The `list' and `x' commands, when you repeat them with <RET>, 1191construct new arguments rather than repeating exactly as typed. This 1192permits easy scanning of source or memory. 1193 1194 GDB can also use <RET> in another way: to partition lengthy output, 1195in a way similar to the common utility `more' (*note Screen Size: 1196Screen Size.). Since it is easy to press one <RET> too many in this 1197situation, GDB disables command repetition after any command that 1198generates this sort of display. 1199 1200 Any text from a `#' to the end of the line is a comment; it does 1201nothing. This is useful mainly in command files (*note Command Files: 1202Command Files.). 1203 1204 The `Ctrl-o' binding is useful for repeating a complex sequence of 1205commands. This command accepts the current line, like <RET>, and then 1206fetches the next line relative to the current line from the history for 1207editing. 1208 1209 1210File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands 1211 12123.2 Command Completion 1213====================== 1214 1215GDB can fill in the rest of a word in a command for you, if there is 1216only one possibility; it can also show you what the valid possibilities 1217are for the next word in a command, at any time. This works for GDB 1218commands, GDB subcommands, and the names of symbols in your program. 1219 1220 Press the <TAB> key whenever you want GDB to fill out the rest of a 1221word. If there is only one possibility, GDB fills in the word, and 1222waits for you to finish the command (or press <RET> to enter it). For 1223example, if you type 1224 1225 (gdb) info bre <TAB> 1226 1227GDB fills in the rest of the word `breakpoints', since that is the only 1228`info' subcommand beginning with `bre': 1229 1230 (gdb) info breakpoints 1231 1232You can either press <RET> at this point, to run the `info breakpoints' 1233command, or backspace and enter something else, if `breakpoints' does 1234not look like the command you expected. (If you were sure you wanted 1235`info breakpoints' in the first place, you might as well just type 1236<RET> immediately after `info bre', to exploit command abbreviations 1237rather than command completion). 1238 1239 If there is more than one possibility for the next word when you 1240press <TAB>, GDB sounds a bell. You can either supply more characters 1241and try again, or just press <TAB> a second time; GDB displays all the 1242possible completions for that word. For example, you might want to set 1243a breakpoint on a subroutine whose name begins with `make_', but when 1244you type `b make_<TAB>' GDB just sounds the bell. Typing <TAB> again 1245displays all the function names in your program that begin with those 1246characters, for example: 1247 1248 (gdb) b make_ <TAB> 1249GDB sounds bell; press <TAB> again, to see: 1250 make_a_section_from_file make_environ 1251 make_abs_section make_function_type 1252 make_blockvector make_pointer_type 1253 make_cleanup make_reference_type 1254 make_command make_symbol_completion_list 1255 (gdb) b make_ 1256 1257After displaying the available possibilities, GDB copies your partial 1258input (`b make_' in the example) so you can finish the command. 1259 1260 If you just want to see the list of alternatives in the first place, 1261you can press `M-?' rather than pressing <TAB> twice. `M-?' means 1262`<META> ?'. You can type this either by holding down a key designated 1263as the <META> shift on your keyboard (if there is one) while typing 1264`?', or as <ESC> followed by `?'. 1265 1266 Sometimes the string you need, while logically a "word", may contain 1267parentheses or other characters that GDB normally excludes from its 1268notion of a word. To permit word completion to work in this situation, 1269you may enclose words in `'' (single quote marks) in GDB commands. 1270 1271 The most likely situation where you might need this is in typing the 1272name of a C++ function. This is because C++ allows function 1273overloading (multiple definitions of the same function, distinguished 1274by argument type). For example, when you want to set a breakpoint you 1275may need to distinguish whether you mean the version of `name' that 1276takes an `int' parameter, `name(int)', or the version that takes a 1277`float' parameter, `name(float)'. To use the word-completion 1278facilities in this situation, type a single quote `'' at the beginning 1279of the function name. This alerts GDB that it may need to consider 1280more information than usual when you press <TAB> or `M-?' to request 1281word completion: 1282 1283 (gdb) b 'bubble( M-? 1284 bubble(double,double) bubble(int,int) 1285 (gdb) b 'bubble( 1286 1287 In some cases, GDB can tell that completing a name requires using 1288quotes. When this happens, GDB inserts the quote for you (while 1289completing as much as it can) if you do not type the quote in the first 1290place: 1291 1292 (gdb) b bub <TAB> 1293GDB alters your input line to the following, and rings a bell: 1294 (gdb) b 'bubble( 1295 1296In general, GDB can tell that a quote is needed (and inserts it) if you 1297have not yet started typing the argument list when you ask for 1298completion on an overloaded symbol. 1299 1300 For more information about overloaded functions, see *Note C++ 1301Expressions: C Plus Plus Expressions. You can use the command `set 1302overload-resolution off' to disable overload resolution; see *Note GDB 1303Features for C++: Debugging C Plus Plus. 1304 1305 When completing in an expression which looks up a field in a 1306structure, GDB also tries(1) to limit completions to the field names 1307available in the type of the left-hand-side: 1308 1309 (gdb) p gdb_stdout.M-? 1310 magic to_delete to_fputs to_put to_rewind 1311 to_data to_flush to_isatty to_read to_write 1312 1313This is because the `gdb_stdout' is a variable of the type `struct 1314ui_file' that is defined in GDB sources as follows: 1315 1316 struct ui_file 1317 { 1318 int *magic; 1319 ui_file_flush_ftype *to_flush; 1320 ui_file_write_ftype *to_write; 1321 ui_file_fputs_ftype *to_fputs; 1322 ui_file_read_ftype *to_read; 1323 ui_file_delete_ftype *to_delete; 1324 ui_file_isatty_ftype *to_isatty; 1325 ui_file_rewind_ftype *to_rewind; 1326 ui_file_put_ftype *to_put; 1327 void *to_data; 1328 } 1329 1330 ---------- Footnotes ---------- 1331 1332 (1) The completer can be confused by certain kinds of invalid 1333expressions. Also, it only examines the static type of the expression, 1334not the dynamic type. 1335 1336 1337File: gdb.info, Node: Help, Prev: Completion, Up: Commands 1338 13393.3 Getting Help 1340================ 1341 1342You can always ask GDB itself for information on its commands, using 1343the command `help'. 1344 1345`help' 1346`h' 1347 You can use `help' (abbreviated `h') with no arguments to display 1348 a short list of named classes of commands: 1349 1350 (gdb) help 1351 List of classes of commands: 1352 1353 aliases -- Aliases of other commands 1354 breakpoints -- Making program stop at certain points 1355 data -- Examining data 1356 files -- Specifying and examining files 1357 internals -- Maintenance commands 1358 obscure -- Obscure features 1359 running -- Running the program 1360 stack -- Examining the stack 1361 status -- Status inquiries 1362 support -- Support facilities 1363 tracepoints -- Tracing of program execution without 1364 stopping the program 1365 user-defined -- User-defined commands 1366 1367 Type "help" followed by a class name for a list of 1368 commands in that class. 1369 Type "help" followed by command name for full 1370 documentation. 1371 Command name abbreviations are allowed if unambiguous. 1372 (gdb) 1373 1374`help CLASS' 1375 Using one of the general help classes as an argument, you can get a 1376 list of the individual commands in that class. For example, here 1377 is the help display for the class `status': 1378 1379 (gdb) help status 1380 Status inquiries. 1381 1382 List of commands: 1383 1384 info -- Generic command for showing things 1385 about the program being debugged 1386 show -- Generic command for showing things 1387 about the debugger 1388 1389 Type "help" followed by command name for full 1390 documentation. 1391 Command name abbreviations are allowed if unambiguous. 1392 (gdb) 1393 1394`help COMMAND' 1395 With a command name as `help' argument, GDB displays a short 1396 paragraph on how to use that command. 1397 1398`apropos ARGS' 1399 The `apropos' command searches through all of the GDB commands, 1400 and their documentation, for the regular expression specified in 1401 ARGS. It prints out all matches found. For example: 1402 1403 apropos reload 1404 1405 results in: 1406 1407 set symbol-reloading -- Set dynamic symbol table reloading 1408 multiple times in one run 1409 show symbol-reloading -- Show dynamic symbol table reloading 1410 multiple times in one run 1411 1412`complete ARGS' 1413 The `complete ARGS' command lists all the possible completions for 1414 the beginning of a command. Use ARGS to specify the beginning of 1415 the command you want completed. For example: 1416 1417 complete i 1418 1419 results in: 1420 1421 if 1422 ignore 1423 info 1424 inspect 1425 1426 This is intended for use by GNU Emacs. 1427 1428 In addition to `help', you can use the GDB commands `info' and 1429`show' to inquire about the state of your program, or the state of GDB 1430itself. Each command supports many topics of inquiry; this manual 1431introduces each of them in the appropriate context. The listings under 1432`info' and under `show' in the Index point to all the sub-commands. 1433*Note Index::. 1434 1435`info' 1436 This command (abbreviated `i') is for describing the state of your 1437 program. For example, you can show the arguments passed to a 1438 function with `info args', list the registers currently in use 1439 with `info registers', or list the breakpoints you have set with 1440 `info breakpoints'. You can get a complete list of the `info' 1441 sub-commands with `help info'. 1442 1443`set' 1444 You can assign the result of an expression to an environment 1445 variable with `set'. For example, you can set the GDB prompt to a 1446 $-sign with `set prompt $'. 1447 1448`show' 1449 In contrast to `info', `show' is for describing the state of GDB 1450 itself. You can change most of the things you can `show', by 1451 using the related command `set'; for example, you can control what 1452 number system is used for displays with `set radix', or simply 1453 inquire which is currently in use with `show radix'. 1454 1455 To display all the settable parameters and their current values, 1456 you can use `show' with no arguments; you may also use `info set'. 1457 Both commands produce the same display. 1458 1459 Here are three miscellaneous `show' subcommands, all of which are 1460exceptional in lacking corresponding `set' commands: 1461 1462`show version' 1463 Show what version of GDB is running. You should include this 1464 information in GDB bug-reports. If multiple versions of GDB are 1465 in use at your site, you may need to determine which version of 1466 GDB you are running; as GDB evolves, new commands are introduced, 1467 and old ones may wither away. Also, many system vendors ship 1468 variant versions of GDB, and there are variant versions of GDB in 1469 GNU/Linux distributions as well. The version number is the same 1470 as the one announced when you start GDB. 1471 1472`show copying' 1473`info copying' 1474 Display information about permission for copying GDB. 1475 1476`show warranty' 1477`info warranty' 1478 Display the GNU "NO WARRANTY" statement, or a warranty, if your 1479 version of GDB comes with one. 1480 1481 1482 1483File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top 1484 14854 Running Programs Under GDB 1486**************************** 1487 1488When you run a program under GDB, you must first generate debugging 1489information when you compile it. 1490 1491 You may start GDB with its arguments, if any, in an environment of 1492your choice. If you are doing native debugging, you may redirect your 1493program's input and output, debug an already running process, or kill a 1494child process. 1495 1496* Menu: 1497 1498* Compilation:: Compiling for debugging 1499* Starting:: Starting your program 1500* Arguments:: Your program's arguments 1501* Environment:: Your program's environment 1502 1503* Working Directory:: Your program's working directory 1504* Input/Output:: Your program's input and output 1505* Attach:: Debugging an already-running process 1506* Kill Process:: Killing the child process 1507 1508* Inferiors and Programs:: Debugging multiple inferiors and programs 1509* Threads:: Debugging programs with multiple threads 1510* Forks:: Debugging forks 1511* Checkpoint/Restart:: Setting a _bookmark_ to return to later 1512 1513 1514File: gdb.info, Node: Compilation, Next: Starting, Up: Running 1515 15164.1 Compiling for Debugging 1517=========================== 1518 1519In order to debug a program effectively, you need to generate debugging 1520information when you compile it. This debugging information is stored 1521in the object file; it describes the data type of each variable or 1522function and the correspondence between source line numbers and 1523addresses in the executable code. 1524 1525 To request debugging information, specify the `-g' option when you 1526run the compiler. 1527 1528 Programs that are to be shipped to your customers are compiled with 1529optimizations, using the `-O' compiler option. However, some compilers 1530are unable to handle the `-g' and `-O' options together. Using those 1531compilers, you cannot generate optimized executables containing 1532debugging information. 1533 1534 GCC, the GNU C/C++ compiler, supports `-g' with or without `-O', 1535making it possible to debug optimized code. We recommend that you 1536_always_ use `-g' whenever you compile a program. You may think your 1537program is correct, but there is no sense in pushing your luck. For 1538more information, see *Note Optimized Code::. 1539 1540 Older versions of the GNU C compiler permitted a variant option 1541`-gg' for debugging information. GDB no longer supports this format; 1542if your GNU C compiler has this option, do not use it. 1543 1544 GDB knows about preprocessor macros and can show you their expansion 1545(*note Macros::). Most compilers do not include information about 1546preprocessor macros in the debugging information if you specify the 1547`-g' flag alone, because this information is rather large. Version 3.1 1548and later of GCC, the GNU C compiler, provides macro information if you 1549specify the options `-gdwarf-2' and `-g3'; the former option requests 1550debugging information in the Dwarf 2 format, and the latter requests 1551"extra information". In the future, we hope to find more compact ways 1552to represent macro information, so that it can be included with `-g' 1553alone. 1554 1555 1556File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running 1557 15584.2 Starting your Program 1559========================= 1560 1561`run' 1562`r' 1563 Use the `run' command to start your program under GDB. You must 1564 first specify the program name (except on VxWorks) with an 1565 argument to GDB (*note Getting In and Out of GDB: Invocation.), or 1566 by using the `file' or `exec-file' command (*note Commands to 1567 Specify Files: Files.). 1568 1569 1570 If you are running your program in an execution environment that 1571supports processes, `run' creates an inferior process and makes that 1572process run your program. In some environments without processes, 1573`run' jumps to the start of your program. Other targets, like 1574`remote', are always running. If you get an error message like this 1575one: 1576 1577 The "remote" target does not support "run". 1578 Try "help target" or "continue". 1579 1580then use `continue' to run your program. You may need `load' first 1581(*note load::). 1582 1583 The execution of a program is affected by certain information it 1584receives from its superior. GDB provides ways to specify this 1585information, which you must do _before_ starting your program. (You 1586can change it after starting your program, but such changes only affect 1587your program the next time you start it.) This information may be 1588divided into four categories: 1589 1590The _arguments._ 1591 Specify the arguments to give your program as the arguments of the 1592 `run' command. If a shell is available on your target, the shell 1593 is used to pass the arguments, so that you may use normal 1594 conventions (such as wildcard expansion or variable substitution) 1595 in describing the arguments. In Unix systems, you can control 1596 which shell is used with the `SHELL' environment variable. *Note 1597 Your Program's Arguments: Arguments. 1598 1599The _environment._ 1600 Your program normally inherits its environment from GDB, but you 1601 can use the GDB commands `set environment' and `unset environment' 1602 to change parts of the environment that affect your program. 1603 *Note Your Program's Environment: Environment. 1604 1605The _working directory._ 1606 Your program inherits its working directory from GDB. You can set 1607 the GDB working directory with the `cd' command in GDB. *Note 1608 Your Program's Working Directory: Working Directory. 1609 1610The _standard input and output._ 1611 Your program normally uses the same device for standard input and 1612 standard output as GDB is using. You can redirect input and output 1613 in the `run' command line, or you can use the `tty' command to set 1614 a different device for your program. *Note Your Program's Input 1615 and Output: Input/Output. 1616 1617 _Warning:_ While input and output redirection work, you cannot use 1618 pipes to pass the output of the program you are debugging to 1619 another program; if you attempt this, GDB is likely to wind up 1620 debugging the wrong program. 1621 1622 When you issue the `run' command, your program begins to execute 1623immediately. *Note Stopping and Continuing: Stopping, for discussion 1624of how to arrange for your program to stop. Once your program has 1625stopped, you may call functions in your program, using the `print' or 1626`call' commands. *Note Examining Data: Data. 1627 1628 If the modification time of your symbol file has changed since the 1629last time GDB read its symbols, GDB discards its symbol table, and 1630reads it again. When it does this, GDB tries to retain your current 1631breakpoints. 1632 1633`start' 1634 The name of the main procedure can vary from language to language. 1635 With C or C++, the main procedure name is always `main', but other 1636 languages such as Ada do not require a specific name for their 1637 main procedure. The debugger provides a convenient way to start 1638 the execution of the program and to stop at the beginning of the 1639 main procedure, depending on the language used. 1640 1641 The `start' command does the equivalent of setting a temporary 1642 breakpoint at the beginning of the main procedure and then invoking 1643 the `run' command. 1644 1645 Some programs contain an "elaboration" phase where some startup 1646 code is executed before the main procedure is called. This 1647 depends on the languages used to write your program. In C++, for 1648 instance, constructors for static and global objects are executed 1649 before `main' is called. It is therefore possible that the 1650 debugger stops before reaching the main procedure. However, the 1651 temporary breakpoint will remain to halt execution. 1652 1653 Specify the arguments to give to your program as arguments to the 1654 `start' command. These arguments will be given verbatim to the 1655 underlying `run' command. Note that the same arguments will be 1656 reused if no argument is provided during subsequent calls to 1657 `start' or `run'. 1658 1659 It is sometimes necessary to debug the program during elaboration. 1660 In these cases, using the `start' command would stop the 1661 execution of your program too late, as the program would have 1662 already completed the elaboration phase. Under these 1663 circumstances, insert breakpoints in your elaboration code before 1664 running your program. 1665 1666`set exec-wrapper WRAPPER' 1667`show exec-wrapper' 1668`unset exec-wrapper' 1669 When `exec-wrapper' is set, the specified wrapper is used to 1670 launch programs for debugging. GDB starts your program with a 1671 shell command of the form `exec WRAPPER PROGRAM'. Quoting is 1672 added to PROGRAM and its arguments, but not to WRAPPER, so you 1673 should add quotes if appropriate for your shell. The wrapper runs 1674 until it executes your program, and then GDB takes control. 1675 1676 You can use any program that eventually calls `execve' with its 1677 arguments as a wrapper. Several standard Unix utilities do this, 1678 e.g. `env' and `nohup'. Any Unix shell script ending with `exec 1679 "$@"' will also work. 1680 1681 For example, you can use `env' to pass an environment variable to 1682 the debugged program, without setting the variable in your shell's 1683 environment: 1684 1685 (gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so' 1686 (gdb) run 1687 1688 This command is available when debugging locally on most targets, 1689 excluding DJGPP, Cygwin, MS Windows, and QNX Neutrino. 1690 1691`set disable-randomization' 1692`set disable-randomization on' 1693 This option (enabled by default in GDB) will turn off the native 1694 randomization of the virtual address space of the started program. 1695 This option is useful for multiple debugging sessions to make the 1696 execution better reproducible and memory addresses reusable across 1697 debugging sessions. 1698 1699 This feature is implemented only on GNU/Linux. You can get the 1700 same behavior using 1701 1702 (gdb) set exec-wrapper setarch `uname -m` -R 1703 1704`set disable-randomization off' 1705 Leave the behavior of the started executable unchanged. Some bugs 1706 rear their ugly heads only when the program is loaded at certain 1707 addresses. If your bug disappears when you run the program under 1708 GDB, that might be because GDB by default disables the address 1709 randomization on platforms, such as GNU/Linux, which do that for 1710 stand-alone programs. Use `set disable-randomization off' to try 1711 to reproduce such elusive bugs. 1712 1713 The virtual address space randomization is implemented only on 1714 GNU/Linux. It protects the programs against some kinds of 1715 security attacks. In these cases the attacker needs to know the 1716 exact location of a concrete executable code. Randomizing its 1717 location makes it impossible to inject jumps misusing a code at 1718 its expected addresses. 1719 1720 Prelinking shared libraries provides a startup performance 1721 advantage but it makes addresses in these libraries predictable 1722 for privileged processes by having just unprivileged access at the 1723 target system. Reading the shared library binary gives enough 1724 information for assembling the malicious code misusing it. Still 1725 even a prelinked shared library can get loaded at a new random 1726 address just requiring the regular relocation process during the 1727 startup. Shared libraries not already prelinked are always loaded 1728 at a randomly chosen address. 1729 1730 Position independent executables (PIE) contain position 1731 independent code similar to the shared libraries and therefore 1732 such executables get loaded at a randomly chosen address upon 1733 startup. PIE executables always load even already prelinked 1734 shared libraries at a random address. You can build such 1735 executable using `gcc -fPIE -pie'. 1736 1737 Heap (malloc storage), stack and custom mmap areas are always 1738 placed randomly (as long as the randomization is enabled). 1739 1740`show disable-randomization' 1741 Show the current setting of the explicit disable of the native 1742 randomization of the virtual address space of the started program. 1743 1744 1745 1746File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running 1747 17484.3 Your Program's Arguments 1749============================ 1750 1751The arguments to your program can be specified by the arguments of the 1752`run' command. They are passed to a shell, which expands wildcard 1753characters and performs redirection of I/O, and thence to your program. 1754Your `SHELL' environment variable (if it exists) specifies what shell 1755GDB uses. If you do not define `SHELL', GDB uses the default shell 1756(`/bin/sh' on Unix). 1757 1758 On non-Unix systems, the program is usually invoked directly by GDB, 1759which emulates I/O redirection via the appropriate system calls, and 1760the wildcard characters are expanded by the startup code of the 1761program, not by the shell. 1762 1763 `run' with no arguments uses the same arguments used by the previous 1764`run', or those set by the `set args' command. 1765 1766`set args' 1767 Specify the arguments to be used the next time your program is 1768 run. If `set args' has no arguments, `run' executes your program 1769 with no arguments. Once you have run your program with arguments, 1770 using `set args' before the next `run' is the only way to run it 1771 again without arguments. 1772 1773`show args' 1774 Show the arguments to give your program when it is started. 1775 1776 1777File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running 1778 17794.4 Your Program's Environment 1780============================== 1781 1782The "environment" consists of a set of environment variables and their 1783values. Environment variables conventionally record such things as 1784your user name, your home directory, your terminal type, and your search 1785path for programs to run. Usually you set up environment variables with 1786the shell and they are inherited by all the other programs you run. 1787When debugging, it can be useful to try running your program with a 1788modified environment without having to start GDB over again. 1789 1790`path DIRECTORY' 1791 Add DIRECTORY to the front of the `PATH' environment variable (the 1792 search path for executables) that will be passed to your program. 1793 The value of `PATH' used by GDB does not change. You may specify 1794 several directory names, separated by whitespace or by a 1795 system-dependent separator character (`:' on Unix, `;' on MS-DOS 1796 and MS-Windows). If DIRECTORY is already in the path, it is moved 1797 to the front, so it is searched sooner. 1798 1799 You can use the string `$cwd' to refer to whatever is the current 1800 working directory at the time GDB searches the path. If you use 1801 `.' instead, it refers to the directory where you executed the 1802 `path' command. GDB replaces `.' in the DIRECTORY argument (with 1803 the current path) before adding DIRECTORY to the search path. 1804 1805`show paths' 1806 Display the list of search paths for executables (the `PATH' 1807 environment variable). 1808 1809`show environment [VARNAME]' 1810 Print the value of environment variable VARNAME to be given to 1811 your program when it starts. If you do not supply VARNAME, print 1812 the names and values of all environment variables to be given to 1813 your program. You can abbreviate `environment' as `env'. 1814 1815`set environment VARNAME [=VALUE]' 1816 Set environment variable VARNAME to VALUE. The value changes for 1817 your program only, not for GDB itself. VALUE may be any string; 1818 the values of environment variables are just strings, and any 1819 interpretation is supplied by your program itself. The VALUE 1820 parameter is optional; if it is eliminated, the variable is set to 1821 a null value. 1822 1823 For example, this command: 1824 1825 set env USER = foo 1826 1827 tells the debugged program, when subsequently run, that its user 1828 is named `foo'. (The spaces around `=' are used for clarity here; 1829 they are not actually required.) 1830 1831`unset environment VARNAME' 1832 Remove variable VARNAME from the environment to be passed to your 1833 program. This is different from `set env VARNAME ='; `unset 1834 environment' removes the variable from the environment, rather 1835 than assigning it an empty value. 1836 1837 _Warning:_ On Unix systems, GDB runs your program using the shell 1838indicated by your `SHELL' environment variable if it exists (or 1839`/bin/sh' if not). If your `SHELL' variable names a shell that runs an 1840initialization file--such as `.cshrc' for C-shell, or `.bashrc' for 1841BASH--any variables you set in that file affect your program. You may 1842wish to move setting of environment variables to files that are only 1843run when you sign on, such as `.login' or `.profile'. 1844 1845 1846File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running 1847 18484.5 Your Program's Working Directory 1849==================================== 1850 1851Each time you start your program with `run', it inherits its working 1852directory from the current working directory of GDB. The GDB working 1853directory is initially whatever it inherited from its parent process 1854(typically the shell), but you can specify a new working directory in 1855GDB with the `cd' command. 1856 1857 The GDB working directory also serves as a default for the commands 1858that specify files for GDB to operate on. *Note Commands to Specify 1859Files: Files. 1860 1861`cd DIRECTORY' 1862 Set the GDB working directory to DIRECTORY. 1863 1864`pwd' 1865 Print the GDB working directory. 1866 1867 It is generally impossible to find the current working directory of 1868the process being debugged (since a program can change its directory 1869during its run). If you work on a system where GDB is configured with 1870the `/proc' support, you can use the `info proc' command (*note SVR4 1871Process Information::) to find out the current working directory of the 1872debuggee. 1873 1874 1875File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running 1876 18774.6 Your Program's Input and Output 1878=================================== 1879 1880By default, the program you run under GDB does input and output to the 1881same terminal that GDB uses. GDB switches the terminal to its own 1882terminal modes to interact with you, but it records the terminal modes 1883your program was using and switches back to them when you continue 1884running your program. 1885 1886`info terminal' 1887 Displays information recorded by GDB about the terminal modes your 1888 program is using. 1889 1890 You can redirect your program's input and/or output using shell 1891redirection with the `run' command. For example, 1892 1893 run > outfile 1894 1895starts your program, diverting its output to the file `outfile'. 1896 1897 Another way to specify where your program should do input and output 1898is with the `tty' command. This command accepts a file name as 1899argument, and causes this file to be the default for future `run' 1900commands. It also resets the controlling terminal for the child 1901process, for future `run' commands. For example, 1902 1903 tty /dev/ttyb 1904 1905directs that processes started with subsequent `run' commands default 1906to do input and output on the terminal `/dev/ttyb' and have that as 1907their controlling terminal. 1908 1909 An explicit redirection in `run' overrides the `tty' command's 1910effect on the input/output device, but not its effect on the controlling 1911terminal. 1912 1913 When you use the `tty' command or redirect input in the `run' 1914command, only the input _for your program_ is affected. The input for 1915GDB still comes from your terminal. `tty' is an alias for `set 1916inferior-tty'. 1917 1918 You can use the `show inferior-tty' command to tell GDB to display 1919the name of the terminal that will be used for future runs of your 1920program. 1921 1922`set inferior-tty /dev/ttyb' 1923 Set the tty for the program being debugged to /dev/ttyb. 1924 1925`show inferior-tty' 1926 Show the current tty for the program being debugged. 1927 1928 1929File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running 1930 19314.7 Debugging an Already-running Process 1932======================================== 1933 1934`attach PROCESS-ID' 1935 This command attaches to a running process--one that was started 1936 outside GDB. (`info files' shows your active targets.) The 1937 command takes as argument a process ID. The usual way to find out 1938 the PROCESS-ID of a Unix process is with the `ps' utility, or with 1939 the `jobs -l' shell command. 1940 1941 `attach' does not repeat if you press <RET> a second time after 1942 executing the command. 1943 1944 To use `attach', your program must be running in an environment 1945which supports processes; for example, `attach' does not work for 1946programs on bare-board targets that lack an operating system. You must 1947also have permission to send the process a signal. 1948 1949 When you use `attach', the debugger finds the program running in the 1950process first by looking in the current working directory, then (if the 1951program is not found) by using the source file search path (*note 1952Specifying Source Directories: Source Path.). You can also use the 1953`file' command to load the program. *Note Commands to Specify Files: 1954Files. 1955 1956 The first thing GDB does after arranging to debug the specified 1957process is to stop it. You can examine and modify an attached process 1958with all the GDB commands that are ordinarily available when you start 1959processes with `run'. You can insert breakpoints; you can step and 1960continue; you can modify storage. If you would rather the process 1961continue running, you may use the `continue' command after attaching 1962GDB to the process. 1963 1964`detach' 1965 When you have finished debugging the attached process, you can use 1966 the `detach' command to release it from GDB control. Detaching 1967 the process continues its execution. After the `detach' command, 1968 that process and GDB become completely independent once more, and 1969 you are ready to `attach' another process or start one with `run'. 1970 `detach' does not repeat if you press <RET> again after executing 1971 the command. 1972 1973 If you exit GDB while you have an attached process, you detach that 1974process. If you use the `run' command, you kill that process. By 1975default, GDB asks for confirmation if you try to do either of these 1976things; you can control whether or not you need to confirm by using the 1977`set confirm' command (*note Optional Warnings and Messages: 1978Messages/Warnings.). 1979 1980 1981File: gdb.info, Node: Kill Process, Next: Inferiors and Programs, Prev: Attach, Up: Running 1982 19834.8 Killing the Child Process 1984============================= 1985 1986`kill' 1987 Kill the child process in which your program is running under GDB. 1988 1989 This command is useful if you wish to debug a core dump instead of a 1990running process. GDB ignores any core dump file while your program is 1991running. 1992 1993 On some operating systems, a program cannot be executed outside GDB 1994while you have breakpoints set on it inside GDB. You can use the 1995`kill' command in this situation to permit running your program outside 1996the debugger. 1997 1998 The `kill' command is also useful if you wish to recompile and 1999relink your program, since on many systems it is impossible to modify an 2000executable file while it is running in a process. In this case, when 2001you next type `run', GDB notices that the file has changed, and reads 2002the symbol table again (while trying to preserve your current 2003breakpoint settings). 2004 2005 2006File: gdb.info, Node: Inferiors and Programs, Next: Threads, Prev: Kill Process, Up: Running 2007 20084.9 Debugging Multiple Inferiors and Programs 2009============================================= 2010 2011GDB lets you run and debug multiple programs in a single session. In 2012addition, GDB on some systems may let you run several programs 2013simultaneously (otherwise you have to exit from one before starting 2014another). In the most general case, you can have multiple threads of 2015execution in each of multiple processes, launched from multiple 2016executables. 2017 2018 GDB represents the state of each program execution with an object 2019called an "inferior". An inferior typically corresponds to a process, 2020but is more general and applies also to targets that do not have 2021processes. Inferiors may be created before a process runs, and may be 2022retained after a process exits. Inferiors have unique identifiers that 2023are different from process ids. Usually each inferior will also have 2024its own distinct address space, although some embedded targets may have 2025several inferiors running in different parts of a single address space. 2026Each inferior may in turn have multiple threads running in it. 2027 2028 To find out what inferiors exist at any moment, use `info inferiors': 2029 2030`info inferiors' 2031 Print a list of all inferiors currently being managed by GDB. 2032 2033 GDB displays for each inferior (in this order): 2034 2035 1. the inferior number assigned by GDB 2036 2037 2. the target system's inferior identifier 2038 2039 3. the name of the executable the inferior is running. 2040 2041 2042 An asterisk `*' preceding the GDB inferior number indicates the 2043 current inferior. 2044 2045 For example, 2046 2047 (gdb) info inferiors 2048 Num Description Executable 2049 2 process 2307 hello 2050 * 1 process 3401 goodbye 2051 2052 To switch focus between inferiors, use the `inferior' command: 2053 2054`inferior INFNO' 2055 Make inferior number INFNO the current inferior. The argument 2056 INFNO is the inferior number assigned by GDB, as shown in the 2057 first field of the `info inferiors' display. 2058 2059 You can get multiple executables into a debugging session via the 2060`add-inferior' and `clone-inferior' commands. On some systems GDB can 2061add inferiors to the debug session automatically by following calls to 2062`fork' and `exec'. To remove inferiors from the debugging session use 2063the `remove-inferiors' command. 2064 2065`add-inferior [ -copies N ] [ -exec EXECUTABLE ]' 2066 Adds N inferiors to be run using EXECUTABLE as the executable. N 2067 defaults to 1. If no executable is specified, the inferiors 2068 begins empty, with no program. You can still assign or change the 2069 program assigned to the inferior at any time by using the `file' 2070 command with the executable name as its argument. 2071 2072`clone-inferior [ -copies N ] [ INFNO ]' 2073 Adds N inferiors ready to execute the same program as inferior 2074 INFNO. N defaults to 1. INFNO defaults to the number of the 2075 current inferior. This is a convenient command when you want to 2076 run another instance of the inferior you are debugging. 2077 2078 (gdb) info inferiors 2079 Num Description Executable 2080 * 1 process 29964 helloworld 2081 (gdb) clone-inferior 2082 Added inferior 2. 2083 1 inferiors added. 2084 (gdb) info inferiors 2085 Num Description Executable 2086 2 <null> helloworld 2087 * 1 process 29964 helloworld 2088 2089 You can now simply switch focus to inferior 2 and run it. 2090 2091`remove-inferiors INFNO...' 2092 Removes the inferior or inferiors INFNO.... It is not possible to 2093 remove an inferior that is running with this command. For those, 2094 use the `kill' or `detach' command first. 2095 2096 2097 To quit debugging one of the running inferiors that is not the 2098current inferior, you can either detach from it by using the 2099`detach inferior' command (allowing it to run independently), or kill it 2100using the `kill inferiors' command: 2101 2102`detach inferior INFNO...' 2103 Detach from the inferior or inferiors identified by GDB inferior 2104 number(s) INFNO.... Note that the inferior's entry still stays on 2105 the list of inferiors shown by `info inferiors', but its 2106 Description will show `<null>'. 2107 2108`kill inferiors INFNO...' 2109 Kill the inferior or inferiors identified by GDB inferior 2110 number(s) INFNO.... Note that the inferior's entry still stays on 2111 the list of inferiors shown by `info inferiors', but its 2112 Description will show `<null>'. 2113 2114 After the successful completion of a command such as `detach', 2115`detach inferiors', `kill' or `kill inferiors', or after a normal 2116process exit, the inferior is still valid and listed with `info 2117inferiors', ready to be restarted. 2118 2119 To be notified when inferiors are started or exit under GDB's 2120control use `set print inferior-events': 2121 2122`set print inferior-events' 2123`set print inferior-events on' 2124`set print inferior-events off' 2125 The `set print inferior-events' command allows you to enable or 2126 disable printing of messages when GDB notices that new inferiors 2127 have started or that inferiors have exited or have been detached. 2128 By default, these messages will not be printed. 2129 2130`show print inferior-events' 2131 Show whether messages will be printed when GDB detects that 2132 inferiors have started, exited or have been detached. 2133 2134 Many commands will work the same with multiple programs as with a 2135single program: e.g., `print myglobal' will simply display the value of 2136`myglobal' in the current inferior. 2137 2138 Occasionaly, when debugging GDB itself, it may be useful to get more 2139info about the relationship of inferiors, programs, address spaces in a 2140debug session. You can do that with the `maint info program-spaces' 2141command. 2142 2143`maint info program-spaces' 2144 Print a list of all program spaces currently being managed by GDB. 2145 2146 GDB displays for each program space (in this order): 2147 2148 1. the program space number assigned by GDB 2149 2150 2. the name of the executable loaded into the program space, 2151 with e.g., the `file' command. 2152 2153 2154 An asterisk `*' preceding the GDB program space number indicates 2155 the current program space. 2156 2157 In addition, below each program space line, GDB prints extra 2158 information that isn't suitable to display in tabular form. For 2159 example, the list of inferiors bound to the program space. 2160 2161 (gdb) maint info program-spaces 2162 Id Executable 2163 2 goodbye 2164 Bound inferiors: ID 1 (process 21561) 2165 * 1 hello 2166 2167 Here we can see that no inferior is running the program `hello', 2168 while `process 21561' is running the program `goodbye'. On some 2169 targets, it is possible that multiple inferiors are bound to the 2170 same program space. The most common example is that of debugging 2171 both the parent and child processes of a `vfork' call. For 2172 example, 2173 2174 (gdb) maint info program-spaces 2175 Id Executable 2176 * 1 vfork-test 2177 Bound inferiors: ID 2 (process 18050), ID 1 (process 18045) 2178 2179 Here, both inferior 2 and inferior 1 are running in the same 2180 program space as a result of inferior 1 having executed a `vfork' 2181 call. 2182 2183 2184File: gdb.info, Node: Threads, Next: Forks, Prev: Inferiors and Programs, Up: Running 2185 21864.10 Debugging Programs with Multiple Threads 2187============================================= 2188 2189In some operating systems, such as HP-UX and Solaris, a single program 2190may have more than one "thread" of execution. The precise semantics of 2191threads differ from one operating system to another, but in general the 2192threads of a single program are akin to multiple processes--except that 2193they share one address space (that is, they can all examine and modify 2194the same variables). On the other hand, each thread has its own 2195registers and execution stack, and perhaps private memory. 2196 2197 GDB provides these facilities for debugging multi-thread programs: 2198 2199 * automatic notification of new threads 2200 2201 * `thread THREADNO', a command to switch among threads 2202 2203 * `info threads', a command to inquire about existing threads 2204 2205 * `thread apply [THREADNO] [ALL] ARGS', a command to apply a command 2206 to a list of threads 2207 2208 * thread-specific breakpoints 2209 2210 * `set print thread-events', which controls printing of messages on 2211 thread start and exit. 2212 2213 * `set libthread-db-search-path PATH', which lets the user specify 2214 which `libthread_db' to use if the default choice isn't compatible 2215 with the program. 2216 2217 _Warning:_ These facilities are not yet available on every GDB 2218 configuration where the operating system supports threads. If 2219 your GDB does not support threads, these commands have no effect. 2220 For example, a system without thread support shows no output from 2221 `info threads', and always rejects the `thread' command, like this: 2222 2223 (gdb) info threads 2224 (gdb) thread 1 2225 Thread ID 1 not known. Use the "info threads" command to 2226 see the IDs of currently known threads. 2227 2228 The GDB thread debugging facility allows you to observe all threads 2229while your program runs--but whenever GDB takes control, one thread in 2230particular is always the focus of debugging. This thread is called the 2231"current thread". Debugging commands show program information from the 2232perspective of the current thread. 2233 2234 Whenever GDB detects a new thread in your program, it displays the 2235target system's identification for the thread with a message in the 2236form `[New SYSTAG]'. SYSTAG is a thread identifier whose form varies 2237depending on the particular system. For example, on GNU/Linux, you 2238might see 2239 2240 [New Thread 0x41e02940 (LWP 25582)] 2241 2242when GDB notices a new thread. In contrast, on an SGI system, the 2243SYSTAG is simply something like `process 368', with no further 2244qualifier. 2245 2246 For debugging purposes, GDB associates its own thread number--always 2247a single integer--with each thread in your program. 2248 2249`info threads [ID...]' 2250 Display a summary of all threads currently in your program. 2251 Optional argument ID... is one or more thread ids separated by 2252 spaces, and means to print information only about the specified 2253 thread or threads. GDB displays for each thread (in this order): 2254 2255 1. the thread number assigned by GDB 2256 2257 2. the target system's thread identifier (SYSTAG) 2258 2259 3. the thread's name, if one is known. A thread can either be 2260 named by the user (see `thread name', below), or, in some 2261 cases, by the program itself. 2262 2263 4. the current stack frame summary for that thread 2264 2265 An asterisk `*' to the left of the GDB thread number indicates the 2266 current thread. 2267 2268 For example, 2269 2270 (gdb) info threads 2271 Id Target Id Frame 2272 3 process 35 thread 27 0x34e5 in sigpause () 2273 2 process 35 thread 23 0x34e5 in sigpause () 2274 * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) 2275 at threadtest.c:68 2276 2277 On Solaris, you can display more information about user threads with 2278a Solaris-specific command: 2279 2280`maint info sol-threads' 2281 Display info on Solaris user threads. 2282 2283`thread THREADNO' 2284 Make thread number THREADNO the current thread. The command 2285 argument THREADNO is the internal GDB thread number, as shown in 2286 the first field of the `info threads' display. GDB responds by 2287 displaying the system identifier of the thread you selected, and 2288 its current stack frame summary: 2289 2290 (gdb) thread 2 2291 [Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))] 2292 #0 some_function (ignore=0x0) at example.c:8 2293 8 printf ("hello\n"); 2294 2295 As with the `[New ...]' message, the form of the text after 2296 `Switching to' depends on your system's conventions for identifying 2297 threads. 2298 2299 The debugger convenience variable `$_thread' contains the number 2300 of the current thread. You may find this useful in writing 2301 breakpoint conditional expressions, command scripts, and so forth. 2302 See *Note Convenience Variables: Convenience Vars, for general 2303 information on convenience variables. 2304 2305`thread apply [THREADNO | all] COMMAND' 2306 The `thread apply' command allows you to apply the named COMMAND 2307 to one or more threads. Specify the numbers of the threads that 2308 you want affected with the command argument THREADNO. It can be a 2309 single thread number, one of the numbers shown in the first field 2310 of the `info threads' display; or it could be a range of thread 2311 numbers, as in `2-4'. To apply a command to all threads, type 2312 `thread apply all COMMAND'. 2313 2314`thread name [NAME]' 2315 This command assigns a name to the current thread. If no argument 2316 is given, any existing user-specified name is removed. The thread 2317 name appears in the `info threads' display. 2318 2319 On some systems, such as GNU/Linux, GDB is able to determine the 2320 name of the thread as given by the OS. On these systems, a name 2321 specified with `thread name' will override the system-give name, 2322 and removing the user-specified name will cause GDB to once again 2323 display the system-specified name. 2324 2325`thread find [REGEXP]' 2326 Search for and display thread ids whose name or SYSTAG matches the 2327 supplied regular expression. 2328 2329 As well as being the complement to the `thread name' command, this 2330 command also allows you to identify a thread by its target SYSTAG. 2331 For instance, on GNU/Linux, the target SYSTAG is the LWP id. 2332 2333 (GDB) thread find 26688 2334 Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)' 2335 (GDB) info thread 4 2336 Id Target Id Frame 2337 4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select () 2338 2339`set print thread-events' 2340`set print thread-events on' 2341`set print thread-events off' 2342 The `set print thread-events' command allows you to enable or 2343 disable printing of messages when GDB notices that new threads have 2344 started or that threads have exited. By default, these messages 2345 will be printed if detection of these events is supported by the 2346 target. Note that these messages cannot be disabled on all 2347 targets. 2348 2349`show print thread-events' 2350 Show whether messages will be printed when GDB detects that threads 2351 have started and exited. 2352 2353 *Note Stopping and Starting Multi-thread Programs: Thread Stops, for 2354more information about how GDB behaves when you stop and start programs 2355with multiple threads. 2356 2357 *Note Setting Watchpoints: Set Watchpoints, for information about 2358watchpoints in programs with multiple threads. 2359 2360`set libthread-db-search-path [PATH]' 2361 If this variable is set, PATH is a colon-separated list of 2362 directories GDB will use to search for `libthread_db'. If you 2363 omit PATH, `libthread-db-search-path' will be reset to an empty 2364 list. 2365 2366 On GNU/Linux and Solaris systems, GDB uses a "helper" 2367 `libthread_db' library to obtain information about threads in the 2368 inferior process. GDB will use `libthread-db-search-path' to find 2369 `libthread_db'. If that fails, GDB will continue with default 2370 system shared library directories, and finally the directory from 2371 which `libpthread' was loaded in the inferior process. 2372 2373 For any `libthread_db' library GDB finds in above directories, GDB 2374 attempts to initialize it with the current inferior process. If 2375 this initialization fails (which could happen because of a version 2376 mismatch between `libthread_db' and `libpthread'), GDB will unload 2377 `libthread_db', and continue with the next directory. If none of 2378 `libthread_db' libraries initialize successfully, GDB will issue a 2379 warning and thread debugging will be disabled. 2380 2381 Setting `libthread-db-search-path' is currently implemented only 2382 on some platforms. 2383 2384`show libthread-db-search-path' 2385 Display current libthread_db search path. 2386 2387`set debug libthread-db' 2388`show debug libthread-db' 2389 Turns on or off display of `libthread_db'-related events. Use `1' 2390 to enable, `0' to disable. 2391 2392 2393File: gdb.info, Node: Forks, Next: Checkpoint/Restart, Prev: Threads, Up: Running 2394 23954.11 Debugging Forks 2396==================== 2397 2398On most systems, GDB has no special support for debugging programs 2399which create additional processes using the `fork' function. When a 2400program forks, GDB will continue to debug the parent process and the 2401child process will run unimpeded. If you have set a breakpoint in any 2402code which the child then executes, the child will get a `SIGTRAP' 2403signal which (unless it catches the signal) will cause it to terminate. 2404 2405 However, if you want to debug the child process there is a workaround 2406which isn't too painful. Put a call to `sleep' in the code which the 2407child process executes after the fork. It may be useful to sleep only 2408if a certain environment variable is set, or a certain file exists, so 2409that the delay need not occur when you don't want to run GDB on the 2410child. While the child is sleeping, use the `ps' program to get its 2411process ID. Then tell GDB (a new invocation of GDB if you are also 2412debugging the parent process) to attach to the child process (*note 2413Attach::). From that point on you can debug the child process just 2414like any other process which you attached to. 2415 2416 On some systems, GDB provides support for debugging programs that 2417create additional processes using the `fork' or `vfork' functions. 2418Currently, the only platforms with this feature are HP-UX (11.x and 2419later only?) and GNU/Linux (kernel version 2.5.60 and later). 2420 2421 By default, when a program forks, GDB will continue to debug the 2422parent process and the child process will run unimpeded. 2423 2424 If you want to follow the child process instead of the parent 2425process, use the command `set follow-fork-mode'. 2426 2427`set follow-fork-mode MODE' 2428 Set the debugger response to a program call of `fork' or `vfork'. 2429 A call to `fork' or `vfork' creates a new process. The MODE 2430 argument can be: 2431 2432 `parent' 2433 The original process is debugged after a fork. The child 2434 process runs unimpeded. This is the default. 2435 2436 `child' 2437 The new process is debugged after a fork. The parent process 2438 runs unimpeded. 2439 2440 2441`show follow-fork-mode' 2442 Display the current debugger response to a `fork' or `vfork' call. 2443 2444 On Linux, if you want to debug both the parent and child processes, 2445use the command `set detach-on-fork'. 2446 2447`set detach-on-fork MODE' 2448 Tells gdb whether to detach one of the processes after a fork, or 2449 retain debugger control over them both. 2450 2451 `on' 2452 The child process (or parent process, depending on the value 2453 of `follow-fork-mode') will be detached and allowed to run 2454 independently. This is the default. 2455 2456 `off' 2457 Both processes will be held under the control of GDB. One 2458 process (child or parent, depending on the value of 2459 `follow-fork-mode') is debugged as usual, while the other is 2460 held suspended. 2461 2462 2463`show detach-on-fork' 2464 Show whether detach-on-fork mode is on/off. 2465 2466 If you choose to set `detach-on-fork' mode off, then GDB will retain 2467control of all forked processes (including nested forks). You can list 2468the forked processes under the control of GDB by using the 2469`info inferiors' command, and switch from one fork to another by using 2470the `inferior' command (*note Debugging Multiple Inferiors and 2471Programs: Inferiors and Programs.). 2472 2473 To quit debugging one of the forked processes, you can either detach 2474from it by using the `detach inferiors' command (allowing it to run 2475independently), or kill it using the `kill inferiors' command. *Note 2476Debugging Multiple Inferiors and Programs: Inferiors and Programs. 2477 2478 If you ask to debug a child process and a `vfork' is followed by an 2479`exec', GDB executes the new target up to the first breakpoint in the 2480new target. If you have a breakpoint set on `main' in your original 2481program, the breakpoint will also be set on the child process's `main'. 2482 2483 On some systems, when a child process is spawned by `vfork', you 2484cannot debug the child or parent until an `exec' call completes. 2485 2486 If you issue a `run' command to GDB after an `exec' call executes, 2487the new target restarts. To restart the parent process, use the `file' 2488command with the parent executable name as its argument. By default, 2489after an `exec' call executes, GDB discards the symbols of the previous 2490executable image. You can change this behaviour with the 2491`set follow-exec-mode' command. 2492 2493`set follow-exec-mode MODE' 2494 Set debugger response to a program call of `exec'. An `exec' call 2495 replaces the program image of a process. 2496 2497 `follow-exec-mode' can be: 2498 2499 `new' 2500 GDB creates a new inferior and rebinds the process to this 2501 new inferior. The program the process was running before the 2502 `exec' call can be restarted afterwards by restarting the 2503 original inferior. 2504 2505 For example: 2506 2507 (gdb) info inferiors 2508 (gdb) info inferior 2509 Id Description Executable 2510 * 1 <null> prog1 2511 (gdb) run 2512 process 12020 is executing new program: prog2 2513 Program exited normally. 2514 (gdb) info inferiors 2515 Id Description Executable 2516 * 2 <null> prog2 2517 1 <null> prog1 2518 2519 `same' 2520 GDB keeps the process bound to the same inferior. The new 2521 executable image replaces the previous executable loaded in 2522 the inferior. Restarting the inferior after the `exec' call, 2523 with e.g., the `run' command, restarts the executable the 2524 process was running after the `exec' call. This is the 2525 default mode. 2526 2527 For example: 2528 2529 (gdb) info inferiors 2530 Id Description Executable 2531 * 1 <null> prog1 2532 (gdb) run 2533 process 12020 is executing new program: prog2 2534 Program exited normally. 2535 (gdb) info inferiors 2536 Id Description Executable 2537 * 1 <null> prog2 2538 2539 2540 You can use the `catch' command to make GDB stop whenever a `fork', 2541`vfork', or `exec' call is made. *Note Setting Catchpoints: Set 2542Catchpoints. 2543 2544 2545File: gdb.info, Node: Checkpoint/Restart, Prev: Forks, Up: Running 2546 25474.12 Setting a _Bookmark_ to Return to Later 2548============================================ 2549 2550On certain operating systems(1), GDB is able to save a "snapshot" of a 2551program's state, called a "checkpoint", and come back to it later. 2552 2553 Returning to a checkpoint effectively undoes everything that has 2554happened in the program since the `checkpoint' was saved. This 2555includes changes in memory, registers, and even (within some limits) 2556system state. Effectively, it is like going back in time to the moment 2557when the checkpoint was saved. 2558 2559 Thus, if you're stepping thru a program and you think you're getting 2560close to the point where things go wrong, you can save a checkpoint. 2561Then, if you accidentally go too far and miss the critical statement, 2562instead of having to restart your program from the beginning, you can 2563just go back to the checkpoint and start again from there. 2564 2565 This can be especially useful if it takes a lot of time or steps to 2566reach the point where you think the bug occurs. 2567 2568 To use the `checkpoint'/`restart' method of debugging: 2569 2570`checkpoint' 2571 Save a snapshot of the debugged program's current execution state. 2572 The `checkpoint' command takes no arguments, but each checkpoint 2573 is assigned a small integer id, similar to a breakpoint id. 2574 2575`info checkpoints' 2576 List the checkpoints that have been saved in the current debugging 2577 session. For each checkpoint, the following information will be 2578 listed: 2579 2580 `Checkpoint ID' 2581 2582 `Process ID' 2583 2584 `Code Address' 2585 2586 `Source line, or label' 2587 2588`restart CHECKPOINT-ID' 2589 Restore the program state that was saved as checkpoint number 2590 CHECKPOINT-ID. All program variables, registers, stack frames 2591 etc. will be returned to the values that they had when the 2592 checkpoint was saved. In essence, gdb will "wind back the clock" 2593 to the point in time when the checkpoint was saved. 2594 2595 Note that breakpoints, GDB variables, command history etc. are 2596 not affected by restoring a checkpoint. In general, a checkpoint 2597 only restores things that reside in the program being debugged, 2598 not in the debugger. 2599 2600`delete checkpoint CHECKPOINT-ID' 2601 Delete the previously-saved checkpoint identified by CHECKPOINT-ID. 2602 2603 2604 Returning to a previously saved checkpoint will restore the user 2605state of the program being debugged, plus a significant subset of the 2606system (OS) state, including file pointers. It won't "un-write" data 2607from a file, but it will rewind the file pointer to the previous 2608location, so that the previously written data can be overwritten. For 2609files opened in read mode, the pointer will also be restored so that the 2610previously read data can be read again. 2611 2612 Of course, characters that have been sent to a printer (or other 2613external device) cannot be "snatched back", and characters received 2614from eg. a serial device can be removed from internal program buffers, 2615but they cannot be "pushed back" into the serial pipeline, ready to be 2616received again. Similarly, the actual contents of files that have been 2617changed cannot be restored (at this time). 2618 2619 However, within those constraints, you actually can "rewind" your 2620program to a previously saved point in time, and begin debugging it 2621again -- and you can change the course of events so as to debug a 2622different execution path this time. 2623 2624 Finally, there is one bit of internal program state that will be 2625different when you return to a checkpoint -- the program's process id. 2626Each checkpoint will have a unique process id (or PID), and each will 2627be different from the program's original PID. If your program has 2628saved a local copy of its process id, this could potentially pose a 2629problem. 2630 26314.12.1 A Non-obvious Benefit of Using Checkpoints 2632------------------------------------------------- 2633 2634On some systems such as GNU/Linux, address space randomization is 2635performed on new processes for security reasons. This makes it 2636difficult or impossible to set a breakpoint, or watchpoint, on an 2637absolute address if you have to restart the program, since the absolute 2638location of a symbol will change from one execution to the next. 2639 2640 A checkpoint, however, is an _identical_ copy of a process. 2641Therefore if you create a checkpoint at (eg.) the start of main, and 2642simply return to that checkpoint instead of restarting the process, you 2643can avoid the effects of address randomization and your symbols will 2644all stay in the same place. 2645 2646 ---------- Footnotes ---------- 2647 2648 (1) Currently, only GNU/Linux. 2649 2650 2651File: gdb.info, Node: Stopping, Next: Reverse Execution, Prev: Running, Up: Top 2652 26535 Stopping and Continuing 2654************************* 2655 2656The principal purposes of using a debugger are so that you can stop your 2657program before it terminates; or so that, if your program runs into 2658trouble, you can investigate and find out why. 2659 2660 Inside GDB, your program may stop for any of several reasons, such 2661as a signal, a breakpoint, or reaching a new line after a GDB command 2662such as `step'. You may then examine and change variables, set new 2663breakpoints or remove old ones, and then continue execution. Usually, 2664the messages shown by GDB provide ample explanation of the status of 2665your program--but you can also explicitly request this information at 2666any time. 2667 2668`info program' 2669 Display information about the status of your program: whether it is 2670 running or not, what process it is, and why it stopped. 2671 2672* Menu: 2673 2674* Breakpoints:: Breakpoints, watchpoints, and catchpoints 2675* Continuing and Stepping:: Resuming execution 2676* Signals:: Signals 2677* Thread Stops:: Stopping and starting multi-thread programs 2678 2679 2680File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping 2681 26825.1 Breakpoints, Watchpoints, and Catchpoints 2683============================================= 2684 2685A "breakpoint" makes your program stop whenever a certain point in the 2686program is reached. For each breakpoint, you can add conditions to 2687control in finer detail whether your program stops. You can set 2688breakpoints with the `break' command and its variants (*note Setting 2689Breakpoints: Set Breaks.), to specify the place where your program 2690should stop by line number, function name or exact address in the 2691program. 2692 2693 On some systems, you can set breakpoints in shared libraries before 2694the executable is run. There is a minor limitation on HP-UX systems: 2695you must wait until the executable is run in order to set breakpoints 2696in shared library routines that are not called directly by the program 2697(for example, routines that are arguments in a `pthread_create' call). 2698 2699 A "watchpoint" is a special breakpoint that stops your program when 2700the value of an expression changes. The expression may be a value of a 2701variable, or it could involve values of one or more variables combined 2702by operators, such as `a + b'. This is sometimes called "data 2703breakpoints". You must use a different command to set watchpoints 2704(*note Setting Watchpoints: Set Watchpoints.), but aside from that, you 2705can manage a watchpoint like any other breakpoint: you enable, disable, 2706and delete both breakpoints and watchpoints using the same commands. 2707 2708 You can arrange to have values from your program displayed 2709automatically whenever GDB stops at a breakpoint. *Note Automatic 2710Display: Auto Display. 2711 2712 A "catchpoint" is another special breakpoint that stops your program 2713when a certain kind of event occurs, such as the throwing of a C++ 2714exception or the loading of a library. As with watchpoints, you use a 2715different command to set a catchpoint (*note Setting Catchpoints: Set 2716Catchpoints.), but aside from that, you can manage a catchpoint like any 2717other breakpoint. (To stop when your program receives a signal, use the 2718`handle' command; see *Note Signals: Signals.) 2719 2720 GDB assigns a number to each breakpoint, watchpoint, or catchpoint 2721when you create it; these numbers are successive integers starting with 2722one. In many of the commands for controlling various features of 2723breakpoints you use the breakpoint number to say which breakpoint you 2724want to change. Each breakpoint may be "enabled" or "disabled"; if 2725disabled, it has no effect on your program until you enable it again. 2726 2727 Some GDB commands accept a range of breakpoints on which to operate. 2728A breakpoint range is either a single breakpoint number, like `5', or 2729two such numbers, in increasing order, separated by a hyphen, like 2730`5-7'. When a breakpoint range is given to a command, all breakpoints 2731in that range are operated on. 2732 2733* Menu: 2734 2735* Set Breaks:: Setting breakpoints 2736* Set Watchpoints:: Setting watchpoints 2737* Set Catchpoints:: Setting catchpoints 2738* Delete Breaks:: Deleting breakpoints 2739* Disabling:: Disabling breakpoints 2740* Conditions:: Break conditions 2741* Break Commands:: Breakpoint command lists 2742* Save Breakpoints:: How to save breakpoints in a file 2743* Error in Breakpoints:: ``Cannot insert breakpoints'' 2744* Breakpoint-related Warnings:: ``Breakpoint address adjusted...'' 2745 2746 2747File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints 2748 27495.1.1 Setting Breakpoints 2750------------------------- 2751 2752Breakpoints are set with the `break' command (abbreviated `b'). The 2753debugger convenience variable `$bpnum' records the number of the 2754breakpoint you've set most recently; see *Note Convenience Variables: 2755Convenience Vars, for a discussion of what you can do with convenience 2756variables. 2757 2758`break LOCATION' 2759 Set a breakpoint at the given LOCATION, which can specify a 2760 function name, a line number, or an address of an instruction. 2761 (*Note Specify Location::, for a list of all the possible ways to 2762 specify a LOCATION.) The breakpoint will stop your program just 2763 before it executes any of the code in the specified LOCATION. 2764 2765 When using source languages that permit overloading of symbols, 2766 such as C++, a function name may refer to more than one possible 2767 place to break. *Note Ambiguous Expressions: Ambiguous 2768 Expressions, for a discussion of that situation. 2769 2770 It is also possible to insert a breakpoint that will stop the 2771 program only if a specific thread (*note Thread-Specific 2772 Breakpoints::) or a specific task (*note Ada Tasks::) hits that 2773 breakpoint. 2774 2775`break' 2776 When called without any arguments, `break' sets a breakpoint at 2777 the next instruction to be executed in the selected stack frame 2778 (*note Examining the Stack: Stack.). In any selected frame but the 2779 innermost, this makes your program stop as soon as control returns 2780 to that frame. This is similar to the effect of a `finish' 2781 command in the frame inside the selected frame--except that 2782 `finish' does not leave an active breakpoint. If you use `break' 2783 without an argument in the innermost frame, GDB stops the next 2784 time it reaches the current location; this may be useful inside 2785 loops. 2786 2787 GDB normally ignores breakpoints when it resumes execution, until 2788 at least one instruction has been executed. If it did not do 2789 this, you would be unable to proceed past a breakpoint without 2790 first disabling the breakpoint. This rule applies whether or not 2791 the breakpoint already existed when your program stopped. 2792 2793`break ... if COND' 2794 Set a breakpoint with condition COND; evaluate the expression COND 2795 each time the breakpoint is reached, and stop only if the value is 2796 nonzero--that is, if COND evaluates as true. `...' stands for one 2797 of the possible arguments described above (or no argument) 2798 specifying where to break. *Note Break Conditions: Conditions, 2799 for more information on breakpoint conditions. 2800 2801`tbreak ARGS' 2802 Set a breakpoint enabled only for one stop. ARGS are the same as 2803 for the `break' command, and the breakpoint is set in the same 2804 way, but the breakpoint is automatically deleted after the first 2805 time your program stops there. *Note Disabling Breakpoints: 2806 Disabling. 2807 2808`hbreak ARGS' 2809 Set a hardware-assisted breakpoint. ARGS are the same as for the 2810 `break' command and the breakpoint is set in the same way, but the 2811 breakpoint requires hardware support and some target hardware may 2812 not have this support. The main purpose of this is EPROM/ROM code 2813 debugging, so you can set a breakpoint at an instruction without 2814 changing the instruction. This can be used with the new 2815 trap-generation provided by SPARClite DSU and most x86-based 2816 targets. These targets will generate traps when a program 2817 accesses some data or instruction address that is assigned to the 2818 debug registers. However the hardware breakpoint registers can 2819 take a limited number of breakpoints. For example, on the DSU, 2820 only two data breakpoints can be set at a time, and GDB will 2821 reject this command if more than two are used. Delete or disable 2822 unused hardware breakpoints before setting new ones (*note 2823 Disabling Breakpoints: Disabling.). *Note Break Conditions: 2824 Conditions. For remote targets, you can restrict the number of 2825 hardware breakpoints GDB will use, see *Note set remote 2826 hardware-breakpoint-limit::. 2827 2828`thbreak ARGS' 2829 Set a hardware-assisted breakpoint enabled only for one stop. ARGS 2830 are the same as for the `hbreak' command and the breakpoint is set 2831 in the same way. However, like the `tbreak' command, the 2832 breakpoint is automatically deleted after the first time your 2833 program stops there. Also, like the `hbreak' command, the 2834 breakpoint requires hardware support and some target hardware may 2835 not have this support. *Note Disabling Breakpoints: Disabling. 2836 See also *Note Break Conditions: Conditions. 2837 2838`rbreak REGEX' 2839 Set breakpoints on all functions matching the regular expression 2840 REGEX. This command sets an unconditional breakpoint on all 2841 matches, printing a list of all breakpoints it set. Once these 2842 breakpoints are set, they are treated just like the breakpoints 2843 set with the `break' command. You can delete them, disable them, 2844 or make them conditional the same way as any other breakpoint. 2845 2846 The syntax of the regular expression is the standard one used with 2847 tools like `grep'. Note that this is different from the syntax 2848 used by shells, so for instance `foo*' matches all functions that 2849 include an `fo' followed by zero or more `o's. There is an 2850 implicit `.*' leading and trailing the regular expression you 2851 supply, so to match only functions that begin with `foo', use 2852 `^foo'. 2853 2854 When debugging C++ programs, `rbreak' is useful for setting 2855 breakpoints on overloaded functions that are not members of any 2856 special classes. 2857 2858 The `rbreak' command can be used to set breakpoints in *all* the 2859 functions in a program, like this: 2860 2861 (gdb) rbreak . 2862 2863`rbreak FILE:REGEX' 2864 If `rbreak' is called with a filename qualification, it limits the 2865 search for functions matching the given regular expression to the 2866 specified FILE. This can be used, for example, to set breakpoints 2867 on every function in a given file: 2868 2869 (gdb) rbreak file.c:. 2870 2871 The colon separating the filename qualifier from the regex may 2872 optionally be surrounded by spaces. 2873 2874`info breakpoints [N...]' 2875`info break [N...]' 2876 Print a table of all breakpoints, watchpoints, and catchpoints set 2877 and not deleted. Optional argument N means print information only 2878 about the specified breakpoint(s) (or watchpoint(s) or 2879 catchpoint(s)). For each breakpoint, following columns are 2880 printed: 2881 2882 _Breakpoint Numbers_ 2883 2884 _Type_ 2885 Breakpoint, watchpoint, or catchpoint. 2886 2887 _Disposition_ 2888 Whether the breakpoint is marked to be disabled or deleted 2889 when hit. 2890 2891 _Enabled or Disabled_ 2892 Enabled breakpoints are marked with `y'. `n' marks 2893 breakpoints that are not enabled. 2894 2895 _Address_ 2896 Where the breakpoint is in your program, as a memory address. 2897 For a pending breakpoint whose address is not yet known, 2898 this field will contain `<PENDING>'. Such breakpoint won't 2899 fire until a shared library that has the symbol or line 2900 referred by breakpoint is loaded. See below for details. A 2901 breakpoint with several locations will have `<MULTIPLE>' in 2902 this field--see below for details. 2903 2904 _What_ 2905 Where the breakpoint is in the source for your program, as a 2906 file and line number. For a pending breakpoint, the original 2907 string passed to the breakpoint command will be listed as it 2908 cannot be resolved until the appropriate shared library is 2909 loaded in the future. 2910 2911 If a breakpoint is conditional, `info break' shows the condition on 2912 the line following the affected breakpoint; breakpoint commands, 2913 if any, are listed after that. A pending breakpoint is allowed to 2914 have a condition specified for it. The condition is not parsed 2915 for validity until a shared library is loaded that allows the 2916 pending breakpoint to resolve to a valid location. 2917 2918 `info break' with a breakpoint number N as argument lists only 2919 that breakpoint. The convenience variable `$_' and the default 2920 examining-address for the `x' command are set to the address of 2921 the last breakpoint listed (*note Examining Memory: Memory.). 2922 2923 `info break' displays a count of the number of times the breakpoint 2924 has been hit. This is especially useful in conjunction with the 2925 `ignore' command. You can ignore a large number of breakpoint 2926 hits, look at the breakpoint info to see how many times the 2927 breakpoint was hit, and then run again, ignoring one less than 2928 that number. This will get you quickly to the last hit of that 2929 breakpoint. 2930 2931 GDB allows you to set any number of breakpoints at the same place in 2932your program. There is nothing silly or meaningless about this. When 2933the breakpoints are conditional, this is even useful (*note Break 2934Conditions: Conditions.). 2935 2936 It is possible that a breakpoint corresponds to several locations in 2937your program. Examples of this situation are: 2938 2939 * For a C++ constructor, the GCC compiler generates several 2940 instances of the function body, used in different cases. 2941 2942 * For a C++ template function, a given line in the function can 2943 correspond to any number of instantiations. 2944 2945 * For an inlined function, a given source line can correspond to 2946 several places where that function is inlined. 2947 2948 In all those cases, GDB will insert a breakpoint at all the relevant 2949locations(1). 2950 2951 A breakpoint with multiple locations is displayed in the breakpoint 2952table using several rows--one header row, followed by one row for each 2953breakpoint location. The header row has `<MULTIPLE>' in the address 2954column. The rows for individual locations contain the actual addresses 2955for locations, and show the functions to which those locations belong. 2956The number column for a location is of the form 2957BREAKPOINT-NUMBER.LOCATION-NUMBER. 2958 2959 For example: 2960 2961 Num Type Disp Enb Address What 2962 1 breakpoint keep y <MULTIPLE> 2963 stop only if i==1 2964 breakpoint already hit 1 time 2965 1.1 y 0x080486a2 in void foo<int>() at t.cc:8 2966 1.2 y 0x080486ca in void foo<double>() at t.cc:8 2967 2968 Each location can be individually enabled or disabled by passing 2969BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the `enable' and 2970`disable' commands. Note that you cannot delete the individual 2971locations from the list, you can only delete the entire list of 2972locations that belong to their parent breakpoint (with the `delete NUM' 2973command, where NUM is the number of the parent breakpoint, 1 in the 2974above example). Disabling or enabling the parent breakpoint (*note 2975Disabling::) affects all of the locations that belong to that 2976breakpoint. 2977 2978 It's quite common to have a breakpoint inside a shared library. 2979Shared libraries can be loaded and unloaded explicitly, and possibly 2980repeatedly, as the program is executed. To support this use case, GDB 2981updates breakpoint locations whenever any shared library is loaded or 2982unloaded. Typically, you would set a breakpoint in a shared library at 2983the beginning of your debugging session, when the library is not 2984loaded, and when the symbols from the library are not available. When 2985you try to set breakpoint, GDB will ask you if you want to set a so 2986called "pending breakpoint"--breakpoint whose address is not yet 2987resolved. 2988 2989 After the program is run, whenever a new shared library is loaded, 2990GDB reevaluates all the breakpoints. When a newly loaded shared 2991library contains the symbol or line referred to by some pending 2992breakpoint, that breakpoint is resolved and becomes an ordinary 2993breakpoint. When a library is unloaded, all breakpoints that refer to 2994its symbols or source lines become pending again. 2995 2996 This logic works for breakpoints with multiple locations, too. For 2997example, if you have a breakpoint in a C++ template function, and a 2998newly loaded shared library has an instantiation of that template, a 2999new location is added to the list of locations for the breakpoint. 3000 3001 Except for having unresolved address, pending breakpoints do not 3002differ from regular breakpoints. You can set conditions or commands, 3003enable and disable them and perform other breakpoint operations. 3004 3005 GDB provides some additional commands for controlling what happens 3006when the `break' command cannot resolve breakpoint address 3007specification to an address: 3008 3009`set breakpoint pending auto' 3010 This is the default behavior. When GDB cannot find the breakpoint 3011 location, it queries you whether a pending breakpoint should be 3012 created. 3013 3014`set breakpoint pending on' 3015 This indicates that an unrecognized breakpoint location should 3016 automatically result in a pending breakpoint being created. 3017 3018`set breakpoint pending off' 3019 This indicates that pending breakpoints are not to be created. Any 3020 unrecognized breakpoint location results in an error. This 3021 setting does not affect any pending breakpoints previously created. 3022 3023`show breakpoint pending' 3024 Show the current behavior setting for creating pending breakpoints. 3025 3026 The settings above only affect the `break' command and its variants. 3027Once breakpoint is set, it will be automatically updated as shared 3028libraries are loaded and unloaded. 3029 3030 For some targets, GDB can automatically decide if hardware or 3031software breakpoints should be used, depending on whether the 3032breakpoint address is read-only or read-write. This applies to 3033breakpoints set with the `break' command as well as to internal 3034breakpoints set by commands like `next' and `finish'. For breakpoints 3035set with `hbreak', GDB will always use hardware breakpoints. 3036 3037 You can control this automatic behaviour with the following 3038commands:: 3039 3040`set breakpoint auto-hw on' 3041 This is the default behavior. When GDB sets a breakpoint, it will 3042 try to use the target memory map to decide if software or hardware 3043 breakpoint must be used. 3044 3045`set breakpoint auto-hw off' 3046 This indicates GDB should not automatically select breakpoint 3047 type. If the target provides a memory map, GDB will warn when 3048 trying to set software breakpoint at a read-only address. 3049 3050 GDB normally implements breakpoints by replacing the program code at 3051the breakpoint address with a special instruction, which, when 3052executed, given control to the debugger. By default, the program code 3053is so modified only when the program is resumed. As soon as the 3054program stops, GDB restores the original instructions. This behaviour 3055guards against leaving breakpoints inserted in the target should gdb 3056abrubptly disconnect. However, with slow remote targets, inserting and 3057removing breakpoint can reduce the performance. This behavior can be 3058controlled with the following commands:: 3059 3060`set breakpoint always-inserted off' 3061 All breakpoints, including newly added by the user, are inserted in 3062 the target only when the target is resumed. All breakpoints are 3063 removed from the target when it stops. 3064 3065`set breakpoint always-inserted on' 3066 Causes all breakpoints to be inserted in the target at all times. 3067 If the user adds a new breakpoint, or changes an existing 3068 breakpoint, the breakpoints in the target are updated immediately. 3069 A breakpoint is removed from the target only when breakpoint 3070 itself is removed. 3071 3072`set breakpoint always-inserted auto' 3073 This is the default mode. If GDB is controlling the inferior in 3074 non-stop mode (*note Non-Stop Mode::), gdb behaves as if 3075 `breakpoint always-inserted' mode is on. If GDB is controlling 3076 the inferior in all-stop mode, GDB behaves as if `breakpoint 3077 always-inserted' mode is off. 3078 3079 GDB itself sometimes sets breakpoints in your program for special 3080purposes, such as proper handling of `longjmp' (in C programs). These 3081internal breakpoints are assigned negative numbers, starting with `-1'; 3082`info breakpoints' does not display them. You can see these 3083breakpoints with the GDB maintenance command `maint info breakpoints' 3084(*note maint info breakpoints::). 3085 3086 ---------- Footnotes ---------- 3087 3088 (1) As of this writing, multiple-location breakpoints work only if 3089there's line number information for all the locations. This means that 3090they will generally not work in system libraries, unless you have debug 3091info with line numbers for them. 3092 3093 3094File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints 3095 30965.1.2 Setting Watchpoints 3097------------------------- 3098 3099You can use a watchpoint to stop execution whenever the value of an 3100expression changes, without having to predict a particular place where 3101this may happen. (This is sometimes called a "data breakpoint".) The 3102expression may be as simple as the value of a single variable, or as 3103complex as many variables combined by operators. Examples include: 3104 3105 * A reference to the value of a single variable. 3106 3107 * An address cast to an appropriate data type. For example, `*(int 3108 *)0x12345678' will watch a 4-byte region at the specified address 3109 (assuming an `int' occupies 4 bytes). 3110 3111 * An arbitrarily complex expression, such as `a*b + c/d'. The 3112 expression can use any operators valid in the program's native 3113 language (*note Languages::). 3114 3115 You can set a watchpoint on an expression even if the expression can 3116not be evaluated yet. For instance, you can set a watchpoint on 3117`*global_ptr' before `global_ptr' is initialized. GDB will stop when 3118your program sets `global_ptr' and the expression produces a valid 3119value. If the expression becomes valid in some other way than changing 3120a variable (e.g. if the memory pointed to by `*global_ptr' becomes 3121readable as the result of a `malloc' call), GDB may not stop until the 3122next time the expression changes. 3123 3124 Depending on your system, watchpoints may be implemented in software 3125or hardware. GDB does software watchpointing by single-stepping your 3126program and testing the variable's value each time, which is hundreds of 3127times slower than normal execution. (But this may still be worth it, to 3128catch errors where you have no clue what part of your program is the 3129culprit.) 3130 3131 On some systems, such as HP-UX, PowerPC, GNU/Linux and most other 3132x86-based targets, GDB includes support for hardware watchpoints, which 3133do not slow down the running of your program. 3134 3135`watch [-l|-location] EXPR [thread THREADNUM]' 3136 Set a watchpoint for an expression. GDB will break when the 3137 expression EXPR is written into by the program and its value 3138 changes. The simplest (and the most popular) use of this command 3139 is to watch the value of a single variable: 3140 3141 (gdb) watch foo 3142 3143 If the command includes a `[thread THREADNUM]' clause, GDB breaks 3144 only when the thread identified by THREADNUM changes the value of 3145 EXPR. If any other threads change the value of EXPR, GDB will not 3146 break. Note that watchpoints restricted to a single thread in 3147 this way only work with Hardware Watchpoints. 3148 3149 Ordinarily a watchpoint respects the scope of variables in EXPR 3150 (see below). The `-location' argument tells GDB to instead watch 3151 the memory referred to by EXPR. In this case, GDB will evaluate 3152 EXPR, take the address of the result, and watch the memory at that 3153 address. The type of the result is used to determine the size of 3154 the watched memory. If the expression's result does not have an 3155 address, then GDB will print an error. 3156 3157`rwatch [-l|-location] EXPR [thread THREADNUM]' 3158 Set a watchpoint that will break when the value of EXPR is read by 3159 the program. 3160 3161`awatch [-l|-location] EXPR [thread THREADNUM]' 3162 Set a watchpoint that will break when EXPR is either read from or 3163 written into by the program. 3164 3165`info watchpoints [N...]' 3166 This command prints a list of watchpoints, using the same format as 3167 `info break' (*note Set Breaks::). 3168 3169 If you watch for a change in a numerically entered address you need 3170to dereference it, as the address itself is just a constant number 3171which will never change. GDB refuses to create a watchpoint that 3172watches a never-changing value: 3173 3174 (gdb) watch 0x600850 3175 Cannot watch constant value 0x600850. 3176 (gdb) watch *(int *) 0x600850 3177 Watchpoint 1: *(int *) 6293584 3178 3179 GDB sets a "hardware watchpoint" if possible. Hardware watchpoints 3180execute very quickly, and the debugger reports a change in value at the 3181exact instruction where the change occurs. If GDB cannot set a 3182hardware watchpoint, it sets a software watchpoint, which executes more 3183slowly and reports the change in value at the next _statement_, not the 3184instruction, after the change occurs. 3185 3186 You can force GDB to use only software watchpoints with the `set 3187can-use-hw-watchpoints 0' command. With this variable set to zero, GDB 3188will never try to use hardware watchpoints, even if the underlying 3189system supports them. (Note that hardware-assisted watchpoints that 3190were set _before_ setting `can-use-hw-watchpoints' to zero will still 3191use the hardware mechanism of watching expression values.) 3192 3193`set can-use-hw-watchpoints' 3194 Set whether or not to use hardware watchpoints. 3195 3196`show can-use-hw-watchpoints' 3197 Show the current mode of using hardware watchpoints. 3198 3199 For remote targets, you can restrict the number of hardware 3200watchpoints GDB will use, see *Note set remote 3201hardware-breakpoint-limit::. 3202 3203 When you issue the `watch' command, GDB reports 3204 3205 Hardware watchpoint NUM: EXPR 3206 3207if it was able to set a hardware watchpoint. 3208 3209 Currently, the `awatch' and `rwatch' commands can only set hardware 3210watchpoints, because accesses to data that don't change the value of 3211the watched expression cannot be detected without examining every 3212instruction as it is being executed, and GDB does not do that 3213currently. If GDB finds that it is unable to set a hardware breakpoint 3214with the `awatch' or `rwatch' command, it will print a message like 3215this: 3216 3217 Expression cannot be implemented with read/access watchpoint. 3218 3219 Sometimes, GDB cannot set a hardware watchpoint because the data 3220type of the watched expression is wider than what a hardware watchpoint 3221on the target machine can handle. For example, some systems can only 3222watch regions that are up to 4 bytes wide; on such systems you cannot 3223set hardware watchpoints for an expression that yields a 3224double-precision floating-point number (which is typically 8 bytes 3225wide). As a work-around, it might be possible to break the large region 3226into a series of smaller ones and watch them with separate watchpoints. 3227 3228 If you set too many hardware watchpoints, GDB might be unable to 3229insert all of them when you resume the execution of your program. 3230Since the precise number of active watchpoints is unknown until such 3231time as the program is about to be resumed, GDB might not be able to 3232warn you about this when you set the watchpoints, and the warning will 3233be printed only when the program is resumed: 3234 3235 Hardware watchpoint NUM: Could not insert watchpoint 3236 3237If this happens, delete or disable some of the watchpoints. 3238 3239 Watching complex expressions that reference many variables can also 3240exhaust the resources available for hardware-assisted watchpoints. 3241That's because GDB needs to watch every variable in the expression with 3242separately allocated resources. 3243 3244 If you call a function interactively using `print' or `call', any 3245watchpoints you have set will be inactive until GDB reaches another 3246kind of breakpoint or the call completes. 3247 3248 GDB automatically deletes watchpoints that watch local (automatic) 3249variables, or expressions that involve such variables, when they go out 3250of scope, that is, when the execution leaves the block in which these 3251variables were defined. In particular, when the program being debugged 3252terminates, _all_ local variables go out of scope, and so only 3253watchpoints that watch global variables remain set. If you rerun the 3254program, you will need to set all such watchpoints again. One way of 3255doing that would be to set a code breakpoint at the entry to the `main' 3256function and when it breaks, set all the watchpoints. 3257 3258 In multi-threaded programs, watchpoints will detect changes to the 3259watched expression from every thread. 3260 3261 _Warning:_ In multi-threaded programs, software watchpoints have 3262 only limited usefulness. If GDB creates a software watchpoint, it 3263 can only watch the value of an expression _in a single thread_. 3264 If you are confident that the expression can only change due to 3265 the current thread's activity (and if you are also confident that 3266 no other thread can become current), then you can use software 3267 watchpoints as usual. However, GDB may not notice when a 3268 non-current thread's activity changes the expression. (Hardware 3269 watchpoints, in contrast, watch an expression in all threads.) 3270 3271 *Note set remote hardware-watchpoint-limit::. 3272 3273 3274File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints 3275 32765.1.3 Setting Catchpoints 3277------------------------- 3278 3279You can use "catchpoints" to cause the debugger to stop for certain 3280kinds of program events, such as C++ exceptions or the loading of a 3281shared library. Use the `catch' command to set a catchpoint. 3282 3283`catch EVENT' 3284 Stop when EVENT occurs. EVENT can be any of the following: 3285 `throw' 3286 The throwing of a C++ exception. 3287 3288 `catch' 3289 The catching of a C++ exception. 3290 3291 `exception' 3292 An Ada exception being raised. If an exception name is 3293 specified at the end of the command (eg `catch exception 3294 Program_Error'), the debugger will stop only when this 3295 specific exception is raised. Otherwise, the debugger stops 3296 execution when any Ada exception is raised. 3297 3298 When inserting an exception catchpoint on a user-defined 3299 exception whose name is identical to one of the exceptions 3300 defined by the language, the fully qualified name must be 3301 used as the exception name. Otherwise, GDB will assume that 3302 it should stop on the pre-defined exception rather than the 3303 user-defined one. For instance, assuming an exception called 3304 `Constraint_Error' is defined in package `Pck', then the 3305 command to use to catch such exceptions is `catch exception 3306 Pck.Constraint_Error'. 3307 3308 `exception unhandled' 3309 An exception that was raised but is not handled by the 3310 program. 3311 3312 `assert' 3313 A failed Ada assertion. 3314 3315 `exec' 3316 A call to `exec'. This is currently only available for HP-UX 3317 and GNU/Linux. 3318 3319 `syscall' 3320 `syscall [NAME | NUMBER] ...' 3321 A call to or return from a system call, a.k.a. "syscall". A 3322 syscall is a mechanism for application programs to request a 3323 service from the operating system (OS) or one of the OS 3324 system services. GDB can catch some or all of the syscalls 3325 issued by the debuggee, and show the related information for 3326 each syscall. If no argument is specified, calls to and 3327 returns from all system calls will be caught. 3328 3329 NAME can be any system call name that is valid for the 3330 underlying OS. Just what syscalls are valid depends on the 3331 OS. On GNU and Unix systems, you can find the full list of 3332 valid syscall names on `/usr/include/asm/unistd.h'. 3333 3334 Normally, GDB knows in advance which syscalls are valid for 3335 each OS, so you can use the GDB command-line completion 3336 facilities (*note command completion: Completion.) to list the 3337 available choices. 3338 3339 You may also specify the system call numerically. A syscall's 3340 number is the value passed to the OS's syscall dispatcher to 3341 identify the requested service. When you specify the syscall 3342 by its name, GDB uses its database of syscalls to convert the 3343 name into the corresponding numeric code, but using the 3344 number directly may be useful if GDB's database does not have 3345 the complete list of syscalls on your system (e.g., because 3346 GDB lags behind the OS upgrades). 3347 3348 The example below illustrates how this command works if you 3349 don't provide arguments to it: 3350 3351 (gdb) catch syscall 3352 Catchpoint 1 (syscall) 3353 (gdb) r 3354 Starting program: /tmp/catch-syscall 3355 3356 Catchpoint 1 (call to syscall 'close'), \ 3357 0xffffe424 in __kernel_vsyscall () 3358 (gdb) c 3359 Continuing. 3360 3361 Catchpoint 1 (returned from syscall 'close'), \ 3362 0xffffe424 in __kernel_vsyscall () 3363 (gdb) 3364 3365 Here is an example of catching a system call by name: 3366 3367 (gdb) catch syscall chroot 3368 Catchpoint 1 (syscall 'chroot' [61]) 3369 (gdb) r 3370 Starting program: /tmp/catch-syscall 3371 3372 Catchpoint 1 (call to syscall 'chroot'), \ 3373 0xffffe424 in __kernel_vsyscall () 3374 (gdb) c 3375 Continuing. 3376 3377 Catchpoint 1 (returned from syscall 'chroot'), \ 3378 0xffffe424 in __kernel_vsyscall () 3379 (gdb) 3380 3381 An example of specifying a system call numerically. In the 3382 case below, the syscall number has a corresponding entry in 3383 the XML file, so GDB finds its name and prints it: 3384 3385 (gdb) catch syscall 252 3386 Catchpoint 1 (syscall(s) 'exit_group') 3387 (gdb) r 3388 Starting program: /tmp/catch-syscall 3389 3390 Catchpoint 1 (call to syscall 'exit_group'), \ 3391 0xffffe424 in __kernel_vsyscall () 3392 (gdb) c 3393 Continuing. 3394 3395 Program exited normally. 3396 (gdb) 3397 3398 However, there can be situations when there is no 3399 corresponding name in XML file for that syscall number. In 3400 this case, GDB prints a warning message saying that it was 3401 not able to find the syscall name, but the catchpoint will be 3402 set anyway. See the example below: 3403 3404 (gdb) catch syscall 764 3405 warning: The number '764' does not represent a known syscall. 3406 Catchpoint 2 (syscall 764) 3407 (gdb) 3408 3409 If you configure GDB using the `--without-expat' option, it 3410 will not be able to display syscall names. Also, if your 3411 architecture does not have an XML file describing its system 3412 calls, you will not be able to see the syscall names. It is 3413 important to notice that these two features are used for 3414 accessing the syscall name database. In either case, you 3415 will see a warning like this: 3416 3417 (gdb) catch syscall 3418 warning: Could not open "syscalls/i386-linux.xml" 3419 warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'. 3420 GDB will not be able to display syscall names. 3421 Catchpoint 1 (syscall) 3422 (gdb) 3423 3424 Of course, the file name will change depending on your 3425 architecture and system. 3426 3427 Still using the example above, you can also try to catch a 3428 syscall by its number. In this case, you would see something 3429 like: 3430 3431 (gdb) catch syscall 252 3432 Catchpoint 1 (syscall(s) 252) 3433 3434 Again, in this case GDB would not be able to display 3435 syscall's names. 3436 3437 `fork' 3438 A call to `fork'. This is currently only available for HP-UX 3439 and GNU/Linux. 3440 3441 `vfork' 3442 A call to `vfork'. This is currently only available for HP-UX 3443 and GNU/Linux. 3444 3445 3446`tcatch EVENT' 3447 Set a catchpoint that is enabled only for one stop. The 3448 catchpoint is automatically deleted after the first time the event 3449 is caught. 3450 3451 3452 Use the `info break' command to list the current catchpoints. 3453 3454 There are currently some limitations to C++ exception handling 3455(`catch throw' and `catch catch') in GDB: 3456 3457 * If you call a function interactively, GDB normally returns control 3458 to you when the function has finished executing. If the call 3459 raises an exception, however, the call may bypass the mechanism 3460 that returns control to you and cause your program either to abort 3461 or to simply continue running until it hits a breakpoint, catches 3462 a signal that GDB is listening for, or exits. This is the case 3463 even if you set a catchpoint for the exception; catchpoints on 3464 exceptions are disabled within interactive calls. 3465 3466 * You cannot raise an exception interactively. 3467 3468 * You cannot install an exception handler interactively. 3469 3470 Sometimes `catch' is not the best way to debug exception handling: 3471if you need to know exactly where an exception is raised, it is better 3472to stop _before_ the exception handler is called, since that way you 3473can see the stack before any unwinding takes place. If you set a 3474breakpoint in an exception handler instead, it may not be easy to find 3475out where the exception was raised. 3476 3477 To stop just before an exception handler is called, you need some 3478knowledge of the implementation. In the case of GNU C++, exceptions are 3479raised by calling a library function named `__raise_exception' which 3480has the following ANSI C interface: 3481 3482 /* ADDR is where the exception identifier is stored. 3483 ID is the exception identifier. */ 3484 void __raise_exception (void **addr, void *id); 3485 3486To make the debugger catch all exceptions before any stack unwinding 3487takes place, set a breakpoint on `__raise_exception' (*note 3488Breakpoints; Watchpoints; and Exceptions: Breakpoints.). 3489 3490 With a conditional breakpoint (*note Break Conditions: Conditions.) 3491that depends on the value of ID, you can stop your program when a 3492specific exception is raised. You can use multiple conditional 3493breakpoints to stop your program when any of a number of exceptions are 3494raised. 3495 3496 3497File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints 3498 34995.1.4 Deleting Breakpoints 3500-------------------------- 3501 3502It is often necessary to eliminate a breakpoint, watchpoint, or 3503catchpoint once it has done its job and you no longer want your program 3504to stop there. This is called "deleting" the breakpoint. A breakpoint 3505that has been deleted no longer exists; it is forgotten. 3506 3507 With the `clear' command you can delete breakpoints according to 3508where they are in your program. With the `delete' command you can 3509delete individual breakpoints, watchpoints, or catchpoints by specifying 3510their breakpoint numbers. 3511 3512 It is not necessary to delete a breakpoint to proceed past it. GDB 3513automatically ignores breakpoints on the first instruction to be 3514executed when you continue execution without changing the execution 3515address. 3516 3517`clear' 3518 Delete any breakpoints at the next instruction to be executed in 3519 the selected stack frame (*note Selecting a Frame: Selection.). 3520 When the innermost frame is selected, this is a good way to delete 3521 a breakpoint where your program just stopped. 3522 3523`clear LOCATION' 3524 Delete any breakpoints set at the specified LOCATION. *Note 3525 Specify Location::, for the various forms of LOCATION; the most 3526 useful ones are listed below: 3527 3528 `clear FUNCTION' 3529 `clear FILENAME:FUNCTION' 3530 Delete any breakpoints set at entry to the named FUNCTION. 3531 3532 `clear LINENUM' 3533 `clear FILENAME:LINENUM' 3534 Delete any breakpoints set at or within the code of the 3535 specified LINENUM of the specified FILENAME. 3536 3537`delete [breakpoints] [RANGE...]' 3538 Delete the breakpoints, watchpoints, or catchpoints of the 3539 breakpoint ranges specified as arguments. If no argument is 3540 specified, delete all breakpoints (GDB asks confirmation, unless 3541 you have `set confirm off'). You can abbreviate this command as 3542 `d'. 3543 3544 3545File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints 3546 35475.1.5 Disabling Breakpoints 3548--------------------------- 3549 3550Rather than deleting a breakpoint, watchpoint, or catchpoint, you might 3551prefer to "disable" it. This makes the breakpoint inoperative as if it 3552had been deleted, but remembers the information on the breakpoint so 3553that you can "enable" it again later. 3554 3555 You disable and enable breakpoints, watchpoints, and catchpoints with 3556the `enable' and `disable' commands, optionally specifying one or more 3557breakpoint numbers as arguments. Use `info break' to print a list of 3558all breakpoints, watchpoints, and catchpoints if you do not know which 3559numbers to use. 3560 3561 Disabling and enabling a breakpoint that has multiple locations 3562affects all of its locations. 3563 3564 A breakpoint, watchpoint, or catchpoint can have any of four 3565different states of enablement: 3566 3567 * Enabled. The breakpoint stops your program. A breakpoint set 3568 with the `break' command starts out in this state. 3569 3570 * Disabled. The breakpoint has no effect on your program. 3571 3572 * Enabled once. The breakpoint stops your program, but then becomes 3573 disabled. 3574 3575 * Enabled for deletion. The breakpoint stops your program, but 3576 immediately after it does so it is deleted permanently. A 3577 breakpoint set with the `tbreak' command starts out in this state. 3578 3579 You can use the following commands to enable or disable breakpoints, 3580watchpoints, and catchpoints: 3581 3582`disable [breakpoints] [RANGE...]' 3583 Disable the specified breakpoints--or all breakpoints, if none are 3584 listed. A disabled breakpoint has no effect but is not forgotten. 3585 All options such as ignore-counts, conditions and commands are 3586 remembered in case the breakpoint is enabled again later. You may 3587 abbreviate `disable' as `dis'. 3588 3589`enable [breakpoints] [RANGE...]' 3590 Enable the specified breakpoints (or all defined breakpoints). 3591 They become effective once again in stopping your program. 3592 3593`enable [breakpoints] once RANGE...' 3594 Enable the specified breakpoints temporarily. GDB disables any of 3595 these breakpoints immediately after stopping your program. 3596 3597`enable [breakpoints] delete RANGE...' 3598 Enable the specified breakpoints to work once, then die. GDB 3599 deletes any of these breakpoints as soon as your program stops 3600 there. Breakpoints set by the `tbreak' command start out in this 3601 state. 3602 3603 Except for a breakpoint set with `tbreak' (*note Setting 3604Breakpoints: Set Breaks.), breakpoints that you set are initially 3605enabled; subsequently, they become disabled or enabled only when you 3606use one of the commands above. (The command `until' can set and delete 3607a breakpoint of its own, but it does not change the state of your other 3608breakpoints; see *Note Continuing and Stepping: Continuing and 3609Stepping.) 3610 3611 3612File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints 3613 36145.1.6 Break Conditions 3615---------------------- 3616 3617The simplest sort of breakpoint breaks every time your program reaches a 3618specified place. You can also specify a "condition" for a breakpoint. 3619A condition is just a Boolean expression in your programming language 3620(*note Expressions: Expressions.). A breakpoint with a condition 3621evaluates the expression each time your program reaches it, and your 3622program stops only if the condition is _true_. 3623 3624 This is the converse of using assertions for program validation; in 3625that situation, you want to stop when the assertion is violated--that 3626is, when the condition is false. In C, if you want to test an 3627assertion expressed by the condition ASSERT, you should set the 3628condition `! ASSERT' on the appropriate breakpoint. 3629 3630 Conditions are also accepted for watchpoints; you may not need them, 3631since a watchpoint is inspecting the value of an expression anyhow--but 3632it might be simpler, say, to just set a watchpoint on a variable name, 3633and specify a condition that tests whether the new value is an 3634interesting one. 3635 3636 Break conditions can have side effects, and may even call functions 3637in your program. This can be useful, for example, to activate functions 3638that log program progress, or to use your own print functions to format 3639special data structures. The effects are completely predictable unless 3640there is another enabled breakpoint at the same address. (In that 3641case, GDB might see the other breakpoint first and stop your program 3642without checking the condition of this one.) Note that breakpoint 3643commands are usually more convenient and flexible than break conditions 3644for the purpose of performing side effects when a breakpoint is reached 3645(*note Breakpoint Command Lists: Break Commands.). 3646 3647 Break conditions can be specified when a breakpoint is set, by using 3648`if' in the arguments to the `break' command. *Note Setting 3649Breakpoints: Set Breaks. They can also be changed at any time with the 3650`condition' command. 3651 3652 You can also use the `if' keyword with the `watch' command. The 3653`catch' command does not recognize the `if' keyword; `condition' is the 3654only way to impose a further condition on a catchpoint. 3655 3656`condition BNUM EXPRESSION' 3657 Specify EXPRESSION as the break condition for breakpoint, 3658 watchpoint, or catchpoint number BNUM. After you set a condition, 3659 breakpoint BNUM stops your program only if the value of EXPRESSION 3660 is true (nonzero, in C). When you use `condition', GDB checks 3661 EXPRESSION immediately for syntactic correctness, and to determine 3662 whether symbols in it have referents in the context of your 3663 breakpoint. If EXPRESSION uses symbols not referenced in the 3664 context of the breakpoint, GDB prints an error message: 3665 3666 No symbol "foo" in current context. 3667 3668 GDB does not actually evaluate EXPRESSION at the time the 3669 `condition' command (or a command that sets a breakpoint with a 3670 condition, like `break if ...') is given, however. *Note 3671 Expressions: Expressions. 3672 3673`condition BNUM' 3674 Remove the condition from breakpoint number BNUM. It becomes an 3675 ordinary unconditional breakpoint. 3676 3677 A special case of a breakpoint condition is to stop only when the 3678breakpoint has been reached a certain number of times. This is so 3679useful that there is a special way to do it, using the "ignore count" 3680of the breakpoint. Every breakpoint has an ignore count, which is an 3681integer. Most of the time, the ignore count is zero, and therefore has 3682no effect. But if your program reaches a breakpoint whose ignore count 3683is positive, then instead of stopping, it just decrements the ignore 3684count by one and continues. As a result, if the ignore count value is 3685N, the breakpoint does not stop the next N times your program reaches 3686it. 3687 3688`ignore BNUM COUNT' 3689 Set the ignore count of breakpoint number BNUM to COUNT. The next 3690 COUNT times the breakpoint is reached, your program's execution 3691 does not stop; other than to decrement the ignore count, GDB takes 3692 no action. 3693 3694 To make the breakpoint stop the next time it is reached, specify a 3695 count of zero. 3696 3697 When you use `continue' to resume execution of your program from a 3698 breakpoint, you can specify an ignore count directly as an 3699 argument to `continue', rather than using `ignore'. *Note 3700 Continuing and Stepping: Continuing and Stepping. 3701 3702 If a breakpoint has a positive ignore count and a condition, the 3703 condition is not checked. Once the ignore count reaches zero, GDB 3704 resumes checking the condition. 3705 3706 You could achieve the effect of the ignore count with a condition 3707 such as `$foo-- <= 0' using a debugger convenience variable that 3708 is decremented each time. *Note Convenience Variables: 3709 Convenience Vars. 3710 3711 Ignore counts apply to breakpoints, watchpoints, and catchpoints. 3712 3713 3714File: gdb.info, Node: Break Commands, Next: Save Breakpoints, Prev: Conditions, Up: Breakpoints 3715 37165.1.7 Breakpoint Command Lists 3717------------------------------ 3718 3719You can give any breakpoint (or watchpoint or catchpoint) a series of 3720commands to execute when your program stops due to that breakpoint. For 3721example, you might want to print the values of certain expressions, or 3722enable other breakpoints. 3723 3724`commands [RANGE...]' 3725`... COMMAND-LIST ...' 3726`end' 3727 Specify a list of commands for the given breakpoints. The commands 3728 themselves appear on the following lines. Type a line containing 3729 just `end' to terminate the commands. 3730 3731 To remove all commands from a breakpoint, type `commands' and 3732 follow it immediately with `end'; that is, give no commands. 3733 3734 With no argument, `commands' refers to the last breakpoint, 3735 watchpoint, or catchpoint set (not to the breakpoint most recently 3736 encountered). If the most recent breakpoints were set with a 3737 single command, then the `commands' will apply to all the 3738 breakpoints set by that command. This applies to breakpoints set 3739 by `rbreak', and also applies when a single `break' command 3740 creates multiple breakpoints (*note Ambiguous Expressions: 3741 Ambiguous Expressions.). 3742 3743 Pressing <RET> as a means of repeating the last GDB command is 3744disabled within a COMMAND-LIST. 3745 3746 You can use breakpoint commands to start your program up again. 3747Simply use the `continue' command, or `step', or any other command that 3748resumes execution. 3749 3750 Any other commands in the command list, after a command that resumes 3751execution, are ignored. This is because any time you resume execution 3752(even with a simple `next' or `step'), you may encounter another 3753breakpoint--which could have its own command list, leading to 3754ambiguities about which list to execute. 3755 3756 If the first command you specify in a command list is `silent', the 3757usual message about stopping at a breakpoint is not printed. This may 3758be desirable for breakpoints that are to print a specific message and 3759then continue. If none of the remaining commands print anything, you 3760see no sign that the breakpoint was reached. `silent' is meaningful 3761only at the beginning of a breakpoint command list. 3762 3763 The commands `echo', `output', and `printf' allow you to print 3764precisely controlled output, and are often useful in silent 3765breakpoints. *Note Commands for Controlled Output: Output. 3766 3767 For example, here is how you could use breakpoint commands to print 3768the value of `x' at entry to `foo' whenever `x' is positive. 3769 3770 break foo if x>0 3771 commands 3772 silent 3773 printf "x is %d\n",x 3774 cont 3775 end 3776 3777 One application for breakpoint commands is to compensate for one bug 3778so you can test for another. Put a breakpoint just after the erroneous 3779line of code, give it a condition to detect the case in which something 3780erroneous has been done, and give it commands to assign correct values 3781to any variables that need them. End with the `continue' command so 3782that your program does not stop, and start with the `silent' command so 3783that no output is produced. Here is an example: 3784 3785 break 403 3786 commands 3787 silent 3788 set x = y + 4 3789 cont 3790 end 3791 3792 3793File: gdb.info, Node: Save Breakpoints, Next: Error in Breakpoints, Prev: Break Commands, Up: Breakpoints 3794 37955.1.8 How to save breakpoints to a file 3796--------------------------------------- 3797 3798To save breakpoint definitions to a file use the `save breakpoints' 3799command. 3800 3801`save breakpoints [FILENAME]' 3802 This command saves all current breakpoint definitions together with 3803 their commands and ignore counts, into a file `FILENAME' suitable 3804 for use in a later debugging session. This includes all types of 3805 breakpoints (breakpoints, watchpoints, catchpoints, tracepoints). 3806 To read the saved breakpoint definitions, use the `source' command 3807 (*note Command Files::). Note that watchpoints with expressions 3808 involving local variables may fail to be recreated because it may 3809 not be possible to access the context where the watchpoint is 3810 valid anymore. Because the saved breakpoint definitions are 3811 simply a sequence of GDB commands that recreate the breakpoints, 3812 you can edit the file in your favorite editing program, and remove 3813 the breakpoint definitions you're not interested in, or that can 3814 no longer be recreated. 3815 3816 3817File: gdb.info, Node: Error in Breakpoints, Next: Breakpoint-related Warnings, Prev: Save Breakpoints, Up: Breakpoints 3818 38195.1.9 "Cannot insert breakpoints" 3820--------------------------------- 3821 3822If you request too many active hardware-assisted breakpoints and 3823watchpoints, you will see this error message: 3824 3825 Stopped; cannot insert breakpoints. 3826 You may have requested too many hardware breakpoints and watchpoints. 3827 3828This message is printed when you attempt to resume the program, since 3829only then GDB knows exactly how many hardware breakpoints and 3830watchpoints it needs to insert. 3831 3832 When this message is printed, you need to disable or remove some of 3833the hardware-assisted breakpoints and watchpoints, and then continue. 3834 3835 3836File: gdb.info, Node: Breakpoint-related Warnings, Prev: Error in Breakpoints, Up: Breakpoints 3837 38385.1.10 "Breakpoint address adjusted..." 3839--------------------------------------- 3840 3841Some processor architectures place constraints on the addresses at 3842which breakpoints may be placed. For architectures thus constrained, 3843GDB will attempt to adjust the breakpoint's address to comply with the 3844constraints dictated by the architecture. 3845 3846 One example of such an architecture is the Fujitsu FR-V. The FR-V is 3847a VLIW architecture in which a number of RISC-like instructions may be 3848bundled together for parallel execution. The FR-V architecture 3849constrains the location of a breakpoint instruction within such a 3850bundle to the instruction with the lowest address. GDB honors this 3851constraint by adjusting a breakpoint's address to the first in the 3852bundle. 3853 3854 It is not uncommon for optimized code to have bundles which contain 3855instructions from different source statements, thus it may happen that 3856a breakpoint's address will be adjusted from one source statement to 3857another. Since this adjustment may significantly alter GDB's 3858breakpoint related behavior from what the user expects, a warning is 3859printed when the breakpoint is first set and also when the breakpoint 3860is hit. 3861 3862 A warning like the one below is printed when setting a breakpoint 3863that's been subject to address adjustment: 3864 3865 warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. 3866 3867 Such warnings are printed both for user settable and GDB's internal 3868breakpoints. If you see one of these warnings, you should verify that 3869a breakpoint set at the adjusted address will have the desired affect. 3870If not, the breakpoint in question may be removed and other breakpoints 3871may be set which will have the desired behavior. E.g., it may be 3872sufficient to place the breakpoint at a later instruction. A 3873conditional breakpoint may also be useful in some cases to prevent the 3874breakpoint from triggering too often. 3875 3876 GDB will also issue a warning when stopping at one of these adjusted 3877breakpoints: 3878 3879 warning: Breakpoint 1 address previously adjusted from 0x00010414 3880 to 0x00010410. 3881 3882 When this warning is encountered, it may be too late to take remedial 3883action except in cases where the breakpoint is hit earlier or more 3884frequently than expected. 3885 3886 3887File: gdb.info, Node: Continuing and Stepping, Next: Signals, Prev: Breakpoints, Up: Stopping 3888 38895.2 Continuing and Stepping 3890=========================== 3891 3892"Continuing" means resuming program execution until your program 3893completes normally. In contrast, "stepping" means executing just one 3894more "step" of your program, where "step" may mean either one line of 3895source code, or one machine instruction (depending on what particular 3896command you use). Either when continuing or when stepping, your 3897program may stop even sooner, due to a breakpoint or a signal. (If it 3898stops due to a signal, you may want to use `handle', or use `signal 0' 3899to resume execution. *Note Signals: Signals.) 3900 3901`continue [IGNORE-COUNT]' 3902`c [IGNORE-COUNT]' 3903`fg [IGNORE-COUNT]' 3904 Resume program execution, at the address where your program last 3905 stopped; any breakpoints set at that address are bypassed. The 3906 optional argument IGNORE-COUNT allows you to specify a further 3907 number of times to ignore a breakpoint at this location; its 3908 effect is like that of `ignore' (*note Break Conditions: 3909 Conditions.). 3910 3911 The argument IGNORE-COUNT is meaningful only when your program 3912 stopped due to a breakpoint. At other times, the argument to 3913 `continue' is ignored. 3914 3915 The synonyms `c' and `fg' (for "foreground", as the debugged 3916 program is deemed to be the foreground program) are provided 3917 purely for convenience, and have exactly the same behavior as 3918 `continue'. 3919 3920 To resume execution at a different place, you can use `return' 3921(*note Returning from a Function: Returning.) to go back to the calling 3922function; or `jump' (*note Continuing at a Different Address: Jumping.) 3923to go to an arbitrary location in your program. 3924 3925 A typical technique for using stepping is to set a breakpoint (*note 3926Breakpoints; Watchpoints; and Catchpoints: Breakpoints.) at the 3927beginning of the function or the section of your program where a problem 3928is believed to lie, run your program until it stops at that breakpoint, 3929and then step through the suspect area, examining the variables that are 3930interesting, until you see the problem happen. 3931 3932`step' 3933 Continue running your program until control reaches a different 3934 source line, then stop it and return control to GDB. This command 3935 is abbreviated `s'. 3936 3937 _Warning:_ If you use the `step' command while control is 3938 within a function that was compiled without debugging 3939 information, execution proceeds until control reaches a 3940 function that does have debugging information. Likewise, it 3941 will not step into a function which is compiled without 3942 debugging information. To step through functions without 3943 debugging information, use the `stepi' command, described 3944 below. 3945 3946 The `step' command only stops at the first instruction of a source 3947 line. This prevents the multiple stops that could otherwise occur 3948 in `switch' statements, `for' loops, etc. `step' continues to 3949 stop if a function that has debugging information is called within 3950 the line. In other words, `step' _steps inside_ any functions 3951 called within the line. 3952 3953 Also, the `step' command only enters a function if there is line 3954 number information for the function. Otherwise it acts like the 3955 `next' command. This avoids problems when using `cc -gl' on MIPS 3956 machines. Previously, `step' entered subroutines if there was any 3957 debugging information about the routine. 3958 3959`step COUNT' 3960 Continue running as in `step', but do so COUNT times. If a 3961 breakpoint is reached, or a signal not related to stepping occurs 3962 before COUNT steps, stepping stops right away. 3963 3964`next [COUNT]' 3965 Continue to the next source line in the current (innermost) stack 3966 frame. This is similar to `step', but function calls that appear 3967 within the line of code are executed without stopping. Execution 3968 stops when control reaches a different line of code at the 3969 original stack level that was executing when you gave the `next' 3970 command. This command is abbreviated `n'. 3971 3972 An argument COUNT is a repeat count, as for `step'. 3973 3974 The `next' command only stops at the first instruction of a source 3975 line. This prevents multiple stops that could otherwise occur in 3976 `switch' statements, `for' loops, etc. 3977 3978`set step-mode' 3979`set step-mode on' 3980 The `set step-mode on' command causes the `step' command to stop 3981 at the first instruction of a function which contains no debug line 3982 information rather than stepping over it. 3983 3984 This is useful in cases where you may be interested in inspecting 3985 the machine instructions of a function which has no symbolic info 3986 and do not want GDB to automatically skip over this function. 3987 3988`set step-mode off' 3989 Causes the `step' command to step over any functions which 3990 contains no debug information. This is the default. 3991 3992`show step-mode' 3993 Show whether GDB will stop in or step over functions without 3994 source line debug information. 3995 3996`finish' 3997 Continue running until just after function in the selected stack 3998 frame returns. Print the returned value (if any). This command 3999 can be abbreviated as `fin'. 4000 4001 Contrast this with the `return' command (*note Returning from a 4002 Function: Returning.). 4003 4004`until' 4005`u' 4006 Continue running until a source line past the current line, in the 4007 current stack frame, is reached. This command is used to avoid 4008 single stepping through a loop more than once. It is like the 4009 `next' command, except that when `until' encounters a jump, it 4010 automatically continues execution until the program counter is 4011 greater than the address of the jump. 4012 4013 This means that when you reach the end of a loop after single 4014 stepping though it, `until' makes your program continue execution 4015 until it exits the loop. In contrast, a `next' command at the end 4016 of a loop simply steps back to the beginning of the loop, which 4017 forces you to step through the next iteration. 4018 4019 `until' always stops your program if it attempts to exit the 4020 current stack frame. 4021 4022 `until' may produce somewhat counterintuitive results if the order 4023 of machine code does not match the order of the source lines. For 4024 example, in the following excerpt from a debugging session, the `f' 4025 (`frame') command shows that execution is stopped at line `206'; 4026 yet when we use `until', we get to line `195': 4027 4028 (gdb) f 4029 #0 main (argc=4, argv=0xf7fffae8) at m4.c:206 4030 206 expand_input(); 4031 (gdb) until 4032 195 for ( ; argc > 0; NEXTARG) { 4033 4034 This happened because, for execution efficiency, the compiler had 4035 generated code for the loop closure test at the end, rather than 4036 the start, of the loop--even though the test in a C `for'-loop is 4037 written before the body of the loop. The `until' command appeared 4038 to step back to the beginning of the loop when it advanced to this 4039 expression; however, it has not really gone to an earlier 4040 statement--not in terms of the actual machine code. 4041 4042 `until' with no argument works by means of single instruction 4043 stepping, and hence is slower than `until' with an argument. 4044 4045`until LOCATION' 4046`u LOCATION' 4047 Continue running your program until either the specified location 4048 is reached, or the current stack frame returns. LOCATION is any of 4049 the forms described in *Note Specify Location::. This form of the 4050 command uses temporary breakpoints, and hence is quicker than 4051 `until' without an argument. The specified location is actually 4052 reached only if it is in the current frame. This implies that 4053 `until' can be used to skip over recursive function invocations. 4054 For instance in the code below, if the current location is line 4055 `96', issuing `until 99' will execute the program up to line `99' 4056 in the same invocation of factorial, i.e., after the inner 4057 invocations have returned. 4058 4059 94 int factorial (int value) 4060 95 { 4061 96 if (value > 1) { 4062 97 value *= factorial (value - 1); 4063 98 } 4064 99 return (value); 4065 100 } 4066 4067`advance LOCATION' 4068 Continue running the program up to the given LOCATION. An 4069 argument is required, which should be of one of the forms 4070 described in *Note Specify Location::. Execution will also stop 4071 upon exit from the current stack frame. This command is similar 4072 to `until', but `advance' will not skip over recursive function 4073 calls, and the target location doesn't have to be in the same 4074 frame as the current one. 4075 4076`stepi' 4077`stepi ARG' 4078`si' 4079 Execute one machine instruction, then stop and return to the 4080 debugger. 4081 4082 It is often useful to do `display/i $pc' when stepping by machine 4083 instructions. This makes GDB automatically display the next 4084 instruction to be executed, each time your program stops. *Note 4085 Automatic Display: Auto Display. 4086 4087 An argument is a repeat count, as in `step'. 4088 4089`nexti' 4090`nexti ARG' 4091`ni' 4092 Execute one machine instruction, but if it is a function call, 4093 proceed until the function returns. 4094 4095 An argument is a repeat count, as in `next'. 4096 4097 4098File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Continuing and Stepping, Up: Stopping 4099 41005.3 Signals 4101=========== 4102 4103A signal is an asynchronous event that can happen in a program. The 4104operating system defines the possible kinds of signals, and gives each 4105kind a name and a number. For example, in Unix `SIGINT' is the signal 4106a program gets when you type an interrupt character (often `Ctrl-c'); 4107`SIGSEGV' is the signal a program gets from referencing a place in 4108memory far away from all the areas in use; `SIGALRM' occurs when the 4109alarm clock timer goes off (which happens only if your program has 4110requested an alarm). 4111 4112 Some signals, including `SIGALRM', are a normal part of the 4113functioning of your program. Others, such as `SIGSEGV', indicate 4114errors; these signals are "fatal" (they kill your program immediately) 4115if the program has not specified in advance some other way to handle 4116the signal. `SIGINT' does not indicate an error in your program, but 4117it is normally fatal so it can carry out the purpose of the interrupt: 4118to kill the program. 4119 4120 GDB has the ability to detect any occurrence of a signal in your 4121program. You can tell GDB in advance what to do for each kind of 4122signal. 4123 4124 Normally, GDB is set up to let the non-erroneous signals like 4125`SIGALRM' be silently passed to your program (so as not to interfere 4126with their role in the program's functioning) but to stop your program 4127immediately whenever an error signal happens. You can change these 4128settings with the `handle' command. 4129 4130`info signals' 4131`info handle' 4132 Print a table of all the kinds of signals and how GDB has been 4133 told to handle each one. You can use this to see the signal 4134 numbers of all the defined types of signals. 4135 4136`info signals SIG' 4137 Similar, but print information only about the specified signal 4138 number. 4139 4140 `info handle' is an alias for `info signals'. 4141 4142`handle SIGNAL [KEYWORDS...]' 4143 Change the way GDB handles signal SIGNAL. SIGNAL can be the 4144 number of a signal or its name (with or without the `SIG' at the 4145 beginning); a list of signal numbers of the form `LOW-HIGH'; or 4146 the word `all', meaning all the known signals. Optional arguments 4147 KEYWORDS, described below, say what change to make. 4148 4149 The keywords allowed by the `handle' command can be abbreviated. 4150Their full names are: 4151 4152`nostop' 4153 GDB should not stop your program when this signal happens. It may 4154 still print a message telling you that the signal has come in. 4155 4156`stop' 4157 GDB should stop your program when this signal happens. This 4158 implies the `print' keyword as well. 4159 4160`print' 4161 GDB should print a message when this signal happens. 4162 4163`noprint' 4164 GDB should not mention the occurrence of the signal at all. This 4165 implies the `nostop' keyword as well. 4166 4167`pass' 4168`noignore' 4169 GDB should allow your program to see this signal; your program can 4170 handle the signal, or else it may terminate if the signal is fatal 4171 and not handled. `pass' and `noignore' are synonyms. 4172 4173`nopass' 4174`ignore' 4175 GDB should not allow your program to see this signal. `nopass' 4176 and `ignore' are synonyms. 4177 4178 When a signal stops your program, the signal is not visible to the 4179program until you continue. Your program sees the signal then, if 4180`pass' is in effect for the signal in question _at that time_. In 4181other words, after GDB reports a signal, you can use the `handle' 4182command with `pass' or `nopass' to control whether your program sees 4183that signal when you continue. 4184 4185 The default is set to `nostop', `noprint', `pass' for non-erroneous 4186signals such as `SIGALRM', `SIGWINCH' and `SIGCHLD', and to `stop', 4187`print', `pass' for the erroneous signals. 4188 4189 You can also use the `signal' command to prevent your program from 4190seeing a signal, or cause it to see a signal it normally would not see, 4191or to give it any signal at any time. For example, if your program 4192stopped due to some sort of memory reference error, you might store 4193correct values into the erroneous variables and continue, hoping to see 4194more execution; but your program would probably terminate immediately as 4195a result of the fatal signal once it saw the signal. To prevent this, 4196you can continue with `signal 0'. *Note Giving your Program a Signal: 4197Signaling. 4198 4199 On some targets, GDB can inspect extra signal information associated 4200with the intercepted signal, before it is actually delivered to the 4201program being debugged. This information is exported by the 4202convenience variable `$_siginfo', and consists of data that is passed 4203by the kernel to the signal handler at the time of the receipt of a 4204signal. The data type of the information itself is target dependent. 4205You can see the data type using the `ptype $_siginfo' command. On Unix 4206systems, it typically corresponds to the standard `siginfo_t' type, as 4207defined in the `signal.h' system header. 4208 4209 Here's an example, on a GNU/Linux system, printing the stray 4210referenced address that raised a segmentation fault. 4211 4212 (gdb) continue 4213 Program received signal SIGSEGV, Segmentation fault. 4214 0x0000000000400766 in main () 4215 69 *(int *)p = 0; 4216 (gdb) ptype $_siginfo 4217 type = struct { 4218 int si_signo; 4219 int si_errno; 4220 int si_code; 4221 union { 4222 int _pad[28]; 4223 struct {...} _kill; 4224 struct {...} _timer; 4225 struct {...} _rt; 4226 struct {...} _sigchld; 4227 struct {...} _sigfault; 4228 struct {...} _sigpoll; 4229 } _sifields; 4230 } 4231 (gdb) ptype $_siginfo._sifields._sigfault 4232 type = struct { 4233 void *si_addr; 4234 } 4235 (gdb) p $_siginfo._sifields._sigfault.si_addr 4236 $1 = (void *) 0x7ffff7ff7000 4237 4238 Depending on target support, `$_siginfo' may also be writable. 4239 4240 4241File: gdb.info, Node: Thread Stops, Prev: Signals, Up: Stopping 4242 42435.4 Stopping and Starting Multi-thread Programs 4244=============================================== 4245 4246GDB supports debugging programs with multiple threads (*note Debugging 4247Programs with Multiple Threads: Threads.). There are two modes of 4248controlling execution of your program within the debugger. In the 4249default mode, referred to as "all-stop mode", when any thread in your 4250program stops (for example, at a breakpoint or while being stepped), 4251all other threads in the program are also stopped by GDB. On some 4252targets, GDB also supports "non-stop mode", in which other threads can 4253continue to run freely while you examine the stopped thread in the 4254debugger. 4255 4256* Menu: 4257 4258* All-Stop Mode:: All threads stop when GDB takes control 4259* Non-Stop Mode:: Other threads continue to execute 4260* Background Execution:: Running your program asynchronously 4261* Thread-Specific Breakpoints:: Controlling breakpoints 4262* Interrupted System Calls:: GDB may interfere with system calls 4263* Observer Mode:: GDB does not alter program behavior 4264 4265 4266File: gdb.info, Node: All-Stop Mode, Next: Non-Stop Mode, Up: Thread Stops 4267 42685.4.1 All-Stop Mode 4269------------------- 4270 4271In all-stop mode, whenever your program stops under GDB for any reason, 4272_all_ threads of execution stop, not just the current thread. This 4273allows you to examine the overall state of the program, including 4274switching between threads, without worrying that things may change 4275underfoot. 4276 4277 Conversely, whenever you restart the program, _all_ threads start 4278executing. _This is true even when single-stepping_ with commands like 4279`step' or `next'. 4280 4281 In particular, GDB cannot single-step all threads in lockstep. 4282Since thread scheduling is up to your debugging target's operating 4283system (not controlled by GDB), other threads may execute more than one 4284statement while the current thread completes a single step. Moreover, 4285in general other threads stop in the middle of a statement, rather than 4286at a clean statement boundary, when the program stops. 4287 4288 You might even find your program stopped in another thread after 4289continuing or even single-stepping. This happens whenever some other 4290thread runs into a breakpoint, a signal, or an exception before the 4291first thread completes whatever you requested. 4292 4293 Whenever GDB stops your program, due to a breakpoint or a signal, it 4294automatically selects the thread where that breakpoint or signal 4295happened. GDB alerts you to the context switch with a message such as 4296`[Switching to Thread N]' to identify the thread. 4297 4298 On some OSes, you can modify GDB's default behavior by locking the 4299OS scheduler to allow only a single thread to run. 4300 4301`set scheduler-locking MODE' 4302 Set the scheduler locking mode. If it is `off', then there is no 4303 locking and any thread may run at any time. If `on', then only the 4304 current thread may run when the inferior is resumed. The `step' 4305 mode optimizes for single-stepping; it prevents other threads from 4306 preempting the current thread while you are stepping, so that the 4307 focus of debugging does not change unexpectedly. Other threads 4308 only rarely (or never) get a chance to run when you step. They 4309 are more likely to run when you `next' over a function call, and 4310 they are completely free to run when you use commands like 4311 `continue', `until', or `finish'. However, unless another thread 4312 hits a breakpoint during its timeslice, GDB does not change the 4313 current thread away from the thread that you are debugging. 4314 4315`show scheduler-locking' 4316 Display the current scheduler locking mode. 4317 4318 By default, when you issue one of the execution commands such as 4319`continue', `next' or `step', GDB allows only threads of the current 4320inferior to run. For example, if GDB is attached to two inferiors, 4321each with two threads, the `continue' command resumes only the two 4322threads of the current inferior. This is useful, for example, when you 4323debug a program that forks and you want to hold the parent stopped (so 4324that, for instance, it doesn't run to exit), while you debug the child. 4325In other situations, you may not be interested in inspecting the 4326current state of any of the processes GDB is attached to, and you may 4327want to resume them all until some breakpoint is hit. In the latter 4328case, you can instruct GDB to allow all threads of all the inferiors to 4329run with the `set schedule-multiple' command. 4330 4331`set schedule-multiple' 4332 Set the mode for allowing threads of multiple processes to be 4333 resumed when an execution command is issued. When `on', all 4334 threads of all processes are allowed to run. When `off', only the 4335 threads of the current process are resumed. The default is `off'. 4336 The `scheduler-locking' mode takes precedence when set to `on', 4337 or while you are stepping and set to `step'. 4338 4339`show schedule-multiple' 4340 Display the current mode for resuming the execution of threads of 4341 multiple processes. 4342 4343 4344File: gdb.info, Node: Non-Stop Mode, Next: Background Execution, Prev: All-Stop Mode, Up: Thread Stops 4345 43465.4.2 Non-Stop Mode 4347------------------- 4348 4349For some multi-threaded targets, GDB supports an optional mode of 4350operation in which you can examine stopped program threads in the 4351debugger while other threads continue to execute freely. This 4352minimizes intrusion when debugging live systems, such as programs where 4353some threads have real-time constraints or must continue to respond to 4354external events. This is referred to as "non-stop" mode. 4355 4356 In non-stop mode, when a thread stops to report a debugging event, 4357_only_ that thread is stopped; GDB does not stop other threads as well, 4358in contrast to the all-stop mode behavior. Additionally, execution 4359commands such as `continue' and `step' apply by default only to the 4360current thread in non-stop mode, rather than all threads as in all-stop 4361mode. This allows you to control threads explicitly in ways that are 4362not possible in all-stop mode -- for example, stepping one thread while 4363allowing others to run freely, stepping one thread while holding all 4364others stopped, or stepping several threads independently and 4365simultaneously. 4366 4367 To enter non-stop mode, use this sequence of commands before you run 4368or attach to your program: 4369 4370 # Enable the async interface. 4371 set target-async 1 4372 4373 # If using the CLI, pagination breaks non-stop. 4374 set pagination off 4375 4376 # Finally, turn it on! 4377 set non-stop on 4378 4379 You can use these commands to manipulate the non-stop mode setting: 4380 4381`set non-stop on' 4382 Enable selection of non-stop mode. 4383 4384`set non-stop off' 4385 Disable selection of non-stop mode. 4386 4387`show non-stop' 4388 Show the current non-stop enablement setting. 4389 4390 Note these commands only reflect whether non-stop mode is enabled, 4391not whether the currently-executing program is being run in non-stop 4392mode. In particular, the `set non-stop' preference is only consulted 4393when GDB starts or connects to the target program, and it is generally 4394not possible to switch modes once debugging has started. Furthermore, 4395since not all targets support non-stop mode, even when you have enabled 4396non-stop mode, GDB may still fall back to all-stop operation by default. 4397 4398 In non-stop mode, all execution commands apply only to the current 4399thread by default. That is, `continue' only continues one thread. To 4400continue all threads, issue `continue -a' or `c -a'. 4401 4402 You can use GDB's background execution commands (*note Background 4403Execution::) to run some threads in the background while you continue 4404to examine or step others from GDB. The MI execution commands (*note 4405GDB/MI Program Execution::) are always executed asynchronously in 4406non-stop mode. 4407 4408 Suspending execution is done with the `interrupt' command when 4409running in the background, or `Ctrl-c' during foreground execution. In 4410all-stop mode, this stops the whole process; but in non-stop mode the 4411interrupt applies only to the current thread. To stop the whole 4412program, use `interrupt -a'. 4413 4414 Other execution commands do not currently support the `-a' option. 4415 4416 In non-stop mode, when a thread stops, GDB doesn't automatically make 4417that thread current, as it does in all-stop mode. This is because the 4418thread stop notifications are asynchronous with respect to GDB's 4419command interpreter, and it would be confusing if GDB unexpectedly 4420changed to a different thread just as you entered a command to operate 4421on the previously current thread. 4422 4423 4424File: gdb.info, Node: Background Execution, Next: Thread-Specific Breakpoints, Prev: Non-Stop Mode, Up: Thread Stops 4425 44265.4.3 Background Execution 4427-------------------------- 4428 4429GDB's execution commands have two variants: the normal foreground 4430(synchronous) behavior, and a background (asynchronous) behavior. In 4431foreground execution, GDB waits for the program to report that some 4432thread has stopped before prompting for another command. In background 4433execution, GDB immediately gives a command prompt so that you can issue 4434other commands while your program runs. 4435 4436 You need to explicitly enable asynchronous mode before you can use 4437background execution commands. You can use these commands to 4438manipulate the asynchronous mode setting: 4439 4440`set target-async on' 4441 Enable asynchronous mode. 4442 4443`set target-async off' 4444 Disable asynchronous mode. 4445 4446`show target-async' 4447 Show the current target-async setting. 4448 4449 If the target doesn't support async mode, GDB issues an error 4450message if you attempt to use the background execution commands. 4451 4452 To specify background execution, add a `&' to the command. For 4453example, the background form of the `continue' command is `continue&', 4454or just `c&'. The execution commands that accept background execution 4455are: 4456 4457`run' 4458 *Note Starting your Program: Starting. 4459 4460`attach' 4461 *Note Debugging an Already-running Process: Attach. 4462 4463`step' 4464 *Note step: Continuing and Stepping. 4465 4466`stepi' 4467 *Note stepi: Continuing and Stepping. 4468 4469`next' 4470 *Note next: Continuing and Stepping. 4471 4472`nexti' 4473 *Note nexti: Continuing and Stepping. 4474 4475`continue' 4476 *Note continue: Continuing and Stepping. 4477 4478`finish' 4479 *Note finish: Continuing and Stepping. 4480 4481`until' 4482 *Note until: Continuing and Stepping. 4483 4484 4485 Background execution is especially useful in conjunction with 4486non-stop mode for debugging programs with multiple threads; see *Note 4487Non-Stop Mode::. However, you can also use these commands in the 4488normal all-stop mode with the restriction that you cannot issue another 4489execution command until the previous one finishes. Examples of 4490commands that are valid in all-stop mode while the program is running 4491include `help' and `info break'. 4492 4493 You can interrupt your program while it is running in the background 4494by using the `interrupt' command. 4495 4496`interrupt' 4497`interrupt -a' 4498 Suspend execution of the running program. In all-stop mode, 4499 `interrupt' stops the whole process, but in non-stop mode, it stops 4500 only the current thread. To stop the whole program in non-stop 4501 mode, use `interrupt -a'. 4502 4503 4504File: gdb.info, Node: Thread-Specific Breakpoints, Next: Interrupted System Calls, Prev: Background Execution, Up: Thread Stops 4505 45065.4.4 Thread-Specific Breakpoints 4507--------------------------------- 4508 4509When your program has multiple threads (*note Debugging Programs with 4510Multiple Threads: Threads.), you can choose whether to set breakpoints 4511on all threads, or on a particular thread. 4512 4513`break LINESPEC thread THREADNO' 4514`break LINESPEC thread THREADNO if ...' 4515 LINESPEC specifies source lines; there are several ways of writing 4516 them (*note Specify Location::), but the effect is always to 4517 specify some source line. 4518 4519 Use the qualifier `thread THREADNO' with a breakpoint command to 4520 specify that you only want GDB to stop the program when a 4521 particular thread reaches this breakpoint. THREADNO is one of the 4522 numeric thread identifiers assigned by GDB, shown in the first 4523 column of the `info threads' display. 4524 4525 If you do not specify `thread THREADNO' when you set a breakpoint, 4526 the breakpoint applies to _all_ threads of your program. 4527 4528 You can use the `thread' qualifier on conditional breakpoints as 4529 well; in this case, place `thread THREADNO' before or after the 4530 breakpoint condition, like this: 4531 4532 (gdb) break frik.c:13 thread 28 if bartab > lim 4533 4534 4535 4536File: gdb.info, Node: Interrupted System Calls, Next: Observer Mode, Prev: Thread-Specific Breakpoints, Up: Thread Stops 4537 45385.4.5 Interrupted System Calls 4539------------------------------ 4540 4541There is an unfortunate side effect when using GDB to debug 4542multi-threaded programs. If one thread stops for a breakpoint, or for 4543some other reason, and another thread is blocked in a system call, then 4544the system call may return prematurely. This is a consequence of the 4545interaction between multiple threads and the signals that GDB uses to 4546implement breakpoints and other events that stop execution. 4547 4548 To handle this problem, your program should check the return value of 4549each system call and react appropriately. This is good programming 4550style anyways. 4551 4552 For example, do not write code like this: 4553 4554 sleep (10); 4555 4556 The call to `sleep' will return early if a different thread stops at 4557a breakpoint or for some other reason. 4558 4559 Instead, write this: 4560 4561 int unslept = 10; 4562 while (unslept > 0) 4563 unslept = sleep (unslept); 4564 4565 A system call is allowed to return early, so the system is still 4566conforming to its specification. But GDB does cause your 4567multi-threaded program to behave differently than it would without GDB. 4568 4569 Also, GDB uses internal breakpoints in the thread library to monitor 4570certain events such as thread creation and thread destruction. When 4571such an event happens, a system call in another thread may return 4572prematurely, even though your program does not appear to stop. 4573 4574 4575File: gdb.info, Node: Observer Mode, Prev: Interrupted System Calls, Up: Thread Stops 4576 45775.4.6 Observer Mode 4578------------------- 4579 4580If you want to build on non-stop mode and observe program behavior 4581without any chance of disruption by GDB, you can set variables to 4582disable all of the debugger's attempts to modify state, whether by 4583writing memory, inserting breakpoints, etc. These operate at a low 4584level, intercepting operations from all commands. 4585 4586 When all of these are set to `off', then GDB is said to be "observer 4587mode". As a convenience, the variable `observer' can be set to disable 4588these, plus enable non-stop mode. 4589 4590 Note that GDB will not prevent you from making nonsensical 4591combinations of these settings. For instance, if you have enabled 4592`may-insert-breakpoints' but disabled `may-write-memory', then 4593breakpoints that work by writing trap instructions into the code stream 4594will still not be able to be placed. 4595 4596`set observer on' 4597`set observer off' 4598 When set to `on', this disables all the permission variables below 4599 (except for `insert-fast-tracepoints'), plus enables non-stop 4600 debugging. Setting this to `off' switches back to normal 4601 debugging, though remaining in non-stop mode. 4602 4603`show observer' 4604 Show whether observer mode is on or off. 4605 4606`set may-write-registers on' 4607`set may-write-registers off' 4608 This controls whether GDB will attempt to alter the values of 4609 registers, such as with assignment expressions in `print', or the 4610 `jump' command. It defaults to `on'. 4611 4612`show may-write-registers' 4613 Show the current permission to write registers. 4614 4615`set may-write-memory on' 4616`set may-write-memory off' 4617 This controls whether GDB will attempt to alter the contents of 4618 memory, such as with assignment expressions in `print'. It 4619 defaults to `on'. 4620 4621`show may-write-memory' 4622 Show the current permission to write memory. 4623 4624`set may-insert-breakpoints on' 4625`set may-insert-breakpoints off' 4626 This controls whether GDB will attempt to insert breakpoints. 4627 This affects all breakpoints, including internal breakpoints 4628 defined by GDB. It defaults to `on'. 4629 4630`show may-insert-breakpoints' 4631 Show the current permission to insert breakpoints. 4632 4633`set may-insert-tracepoints on' 4634`set may-insert-tracepoints off' 4635 This controls whether GDB will attempt to insert (regular) 4636 tracepoints at the beginning of a tracing experiment. It affects 4637 only non-fast tracepoints, fast tracepoints being under the 4638 control of `may-insert-fast-tracepoints'. It defaults to `on'. 4639 4640`show may-insert-tracepoints' 4641 Show the current permission to insert tracepoints. 4642 4643`set may-insert-fast-tracepoints on' 4644`set may-insert-fast-tracepoints off' 4645 This controls whether GDB will attempt to insert fast tracepoints 4646 at the beginning of a tracing experiment. It affects only fast 4647 tracepoints, regular (non-fast) tracepoints being under the 4648 control of `may-insert-tracepoints'. It defaults to `on'. 4649 4650`show may-insert-fast-tracepoints' 4651 Show the current permission to insert fast tracepoints. 4652 4653`set may-interrupt on' 4654`set may-interrupt off' 4655 This controls whether GDB will attempt to interrupt or stop 4656 program execution. When this variable is `off', the `interrupt' 4657 command will have no effect, nor will `Ctrl-c'. It defaults to 4658 `on'. 4659 4660`show may-interrupt' 4661 Show the current permission to interrupt or stop the program. 4662 4663 4664 4665File: gdb.info, Node: Reverse Execution, Next: Process Record and Replay, Prev: Stopping, Up: Top 4666 46676 Running programs backward 4668*************************** 4669 4670When you are debugging a program, it is not unusual to realize that you 4671have gone too far, and some event of interest has already happened. If 4672the target environment supports it, GDB can allow you to "rewind" the 4673program by running it backward. 4674 4675 A target environment that supports reverse execution should be able 4676to "undo" the changes in machine state that have taken place as the 4677program was executing normally. Variables, registers etc. should 4678revert to their previous values. Obviously this requires a great deal 4679of sophistication on the part of the target environment; not all target 4680environments can support reverse execution. 4681 4682 When a program is executed in reverse, the instructions that have 4683most recently been executed are "un-executed", in reverse order. The 4684program counter runs backward, following the previous thread of 4685execution in reverse. As each instruction is "un-executed", the values 4686of memory and/or registers that were changed by that instruction are 4687reverted to their previous states. After executing a piece of source 4688code in reverse, all side effects of that code should be "undone", and 4689all variables should be returned to their prior values(1). 4690 4691 If you are debugging in a target environment that supports reverse 4692execution, GDB provides the following commands. 4693 4694`reverse-continue [IGNORE-COUNT]' 4695`rc [IGNORE-COUNT]' 4696 Beginning at the point where your program last stopped, start 4697 executing in reverse. Reverse execution will stop for breakpoints 4698 and synchronous exceptions (signals), just like normal execution. 4699 Behavior of asynchronous signals depends on the target environment. 4700 4701`reverse-step [COUNT]' 4702 Run the program backward until control reaches the start of a 4703 different source line; then stop it, and return control to GDB. 4704 4705 Like the `step' command, `reverse-step' will only stop at the 4706 beginning of a source line. It "un-executes" the previously 4707 executed source line. If the previous source line included calls 4708 to debuggable functions, `reverse-step' will step (backward) into 4709 the called function, stopping at the beginning of the _last_ 4710 statement in the called function (typically a return statement). 4711 4712 Also, as with the `step' command, if non-debuggable functions are 4713 called, `reverse-step' will run thru them backward without 4714 stopping. 4715 4716`reverse-stepi [COUNT]' 4717 Reverse-execute one machine instruction. Note that the instruction 4718 to be reverse-executed is _not_ the one pointed to by the program 4719 counter, but the instruction executed prior to that one. For 4720 instance, if the last instruction was a jump, `reverse-stepi' will 4721 take you back from the destination of the jump to the jump 4722 instruction itself. 4723 4724`reverse-next [COUNT]' 4725 Run backward to the beginning of the previous line executed in the 4726 current (innermost) stack frame. If the line contains function 4727 calls, they will be "un-executed" without stopping. Starting from 4728 the first line of a function, `reverse-next' will take you back to 4729 the caller of that function, _before_ the function was called, 4730 just as the normal `next' command would take you from the last 4731 line of a function back to its return to its caller (2). 4732 4733`reverse-nexti [COUNT]' 4734 Like `nexti', `reverse-nexti' executes a single instruction in 4735 reverse, except that called functions are "un-executed" atomically. 4736 That is, if the previously executed instruction was a return from 4737 another function, `reverse-nexti' will continue to execute in 4738 reverse until the call to that function (from the current stack 4739 frame) is reached. 4740 4741`reverse-finish' 4742 Just as the `finish' command takes you to the point where the 4743 current function returns, `reverse-finish' takes you to the point 4744 where it was called. Instead of ending up at the end of the 4745 current function invocation, you end up at the beginning. 4746 4747`set exec-direction' 4748 Set the direction of target execution. 4749 4750`set exec-direction reverse' 4751 GDB will perform all execution commands in reverse, until the 4752 exec-direction mode is changed to "forward". Affected commands 4753 include `step, stepi, next, nexti, continue, and finish'. The 4754 `return' command cannot be used in reverse mode. 4755 4756`set exec-direction forward' 4757 GDB will perform all execution commands in the normal fashion. 4758 This is the default. 4759 4760 ---------- Footnotes ---------- 4761 4762 (1) Note that some side effects are easier to undo than others. For 4763instance, memory and registers are relatively easy, but device I/O is 4764hard. Some targets may be able undo things like device I/O, and some 4765may not. 4766 4767 The contract between GDB and the reverse executing target requires 4768only that the target do something reasonable when GDB tells it to 4769execute backwards, and then report the results back to GDB. Whatever 4770the target reports back to GDB, GDB will report back to the user. GDB 4771assumes that the memory and registers that the target reports are in a 4772consistant state, but GDB accepts whatever it is given. 4773 4774 (2) Unless the code is too heavily optimized. 4775 4776 4777File: gdb.info, Node: Process Record and Replay, Next: Stack, Prev: Reverse Execution, Up: Top 4778 47797 Recording Inferior's Execution and Replaying It 4780************************************************* 4781 4782On some platforms, GDB provides a special "process record and replay" 4783target that can record a log of the process execution, and replay it 4784later with both forward and reverse execution commands. 4785 4786 When this target is in use, if the execution log includes the record 4787for the next instruction, GDB will debug in "replay mode". In the 4788replay mode, the inferior does not really execute code instructions. 4789Instead, all the events that normally happen during code execution are 4790taken from the execution log. While code is not really executed in 4791replay mode, the values of registers (including the program counter 4792register) and the memory of the inferior are still changed as they 4793normally would. Their contents are taken from the execution log. 4794 4795 If the record for the next instruction is not in the execution log, 4796GDB will debug in "record mode". In this mode, the inferior executes 4797normally, and GDB records the execution log for future replay. 4798 4799 The process record and replay target supports reverse execution 4800(*note Reverse Execution::), even if the platform on which the inferior 4801runs does not. However, the reverse execution is limited in this case 4802by the range of the instructions recorded in the execution log. In 4803other words, reverse execution on platforms that don't support it 4804directly can only be done in the replay mode. 4805 4806 When debugging in the reverse direction, GDB will work in replay 4807mode as long as the execution log includes the record for the previous 4808instruction; otherwise, it will work in record mode, if the platform 4809supports reverse execution, or stop if not. 4810 4811 For architecture environments that support process record and replay, 4812GDB provides the following commands: 4813 4814`target record' 4815 This command starts the process record and replay target. The 4816 process record and replay target can only debug a process that is 4817 already running. Therefore, you need first to start the process 4818 with the `run' or `start' commands, and then start the recording 4819 with the `target record' command. 4820 4821 Both `record' and `rec' are aliases of `target record'. 4822 4823 Displaced stepping (*note displaced stepping: Maintenance 4824 Commands.) will be automatically disabled when process record and 4825 replay target is started. That's because the process record and 4826 replay target doesn't support displaced stepping. 4827 4828 If the inferior is in the non-stop mode (*note Non-Stop Mode::) or 4829 in the asynchronous execution mode (*note Background Execution::), 4830 the process record and replay target cannot be started because it 4831 doesn't support these two modes. 4832 4833`record stop' 4834 Stop the process record and replay target. When process record and 4835 replay target stops, the entire execution log will be deleted and 4836 the inferior will either be terminated, or will remain in its 4837 final state. 4838 4839 When you stop the process record and replay target in record mode 4840 (at the end of the execution log), the inferior will be stopped at 4841 the next instruction that would have been recorded. In other 4842 words, if you record for a while and then stop recording, the 4843 inferior process will be left in the same state as if the 4844 recording never happened. 4845 4846 On the other hand, if the process record and replay target is 4847 stopped while in replay mode (that is, not at the end of the 4848 execution log, but at some earlier point), the inferior process 4849 will become "live" at that earlier state, and it will then be 4850 possible to continue the usual "live" debugging of the process 4851 from that state. 4852 4853 When the inferior process exits, or GDB detaches from it, process 4854 record and replay target will automatically stop itself. 4855 4856`record save FILENAME' 4857 Save the execution log to a file `FILENAME'. Default filename is 4858 `gdb_record.PROCESS_ID', where PROCESS_ID is the process ID of the 4859 inferior. 4860 4861`record restore FILENAME' 4862 Restore the execution log from a file `FILENAME'. File must have 4863 been created with `record save'. 4864 4865`set record insn-number-max LIMIT' 4866 Set the limit of instructions to be recorded. Default value is 4867 200000. 4868 4869 If LIMIT is a positive number, then GDB will start deleting 4870 instructions from the log once the number of the record 4871 instructions becomes greater than LIMIT. For every new recorded 4872 instruction, GDB will delete the earliest recorded instruction to 4873 keep the number of recorded instructions at the limit. (Since 4874 deleting recorded instructions loses information, GDB lets you 4875 control what happens when the limit is reached, by means of the 4876 `stop-at-limit' option, described below.) 4877 4878 If LIMIT is zero, GDB will never delete recorded instructions from 4879 the execution log. The number of recorded instructions is 4880 unlimited in this case. 4881 4882`show record insn-number-max' 4883 Show the limit of instructions to be recorded. 4884 4885`set record stop-at-limit' 4886 Control the behavior when the number of recorded instructions 4887 reaches the limit. If ON (the default), GDB will stop when the 4888 limit is reached for the first time and ask you whether you want 4889 to stop the inferior or continue running it and recording the 4890 execution log. If you decide to continue recording, each new 4891 recorded instruction will cause the oldest one to be deleted. 4892 4893 If this option is OFF, GDB will automatically delete the oldest 4894 record to make room for each new one, without asking. 4895 4896`show record stop-at-limit' 4897 Show the current setting of `stop-at-limit'. 4898 4899`set record memory-query' 4900 Control the behavior when GDB is unable to record memory changes 4901 caused by an instruction. If ON, GDB will query whether to stop 4902 the inferior in that case. 4903 4904 If this option is OFF (the default), GDB will automatically ignore 4905 the effect of such instructions on memory. Later, when GDB 4906 replays this execution log, it will mark the log of this 4907 instruction as not accessible, and it will not affect the replay 4908 results. 4909 4910`show record memory-query' 4911 Show the current setting of `memory-query'. 4912 4913`info record' 4914 Show various statistics about the state of process record and its 4915 in-memory execution log buffer, including: 4916 4917 * Whether in record mode or replay mode. 4918 4919 * Lowest recorded instruction number (counting from when the 4920 current execution log started recording instructions). 4921 4922 * Highest recorded instruction number. 4923 4924 * Current instruction about to be replayed (if in replay mode). 4925 4926 * Number of instructions contained in the execution log. 4927 4928 * Maximum number of instructions that may be contained in the 4929 execution log. 4930 4931`record delete' 4932 When record target runs in replay mode ("in the past"), delete the 4933 subsequent execution log and begin to record a new execution log 4934 starting from the current address. This means you will abandon 4935 the previously recorded "future" and begin recording a new 4936 "future". 4937 4938 4939File: gdb.info, Node: Stack, Next: Source, Prev: Process Record and Replay, Up: Top 4940 49418 Examining the Stack 4942********************* 4943 4944When your program has stopped, the first thing you need to know is 4945where it stopped and how it got there. 4946 4947 Each time your program performs a function call, information about 4948the call is generated. That information includes the location of the 4949call in your program, the arguments of the call, and the local 4950variables of the function being called. The information is saved in a 4951block of data called a "stack frame". The stack frames are allocated 4952in a region of memory called the "call stack". 4953 4954 When your program stops, the GDB commands for examining the stack 4955allow you to see all of this information. 4956 4957 One of the stack frames is "selected" by GDB and many GDB commands 4958refer implicitly to the selected frame. In particular, whenever you 4959ask GDB for the value of a variable in your program, the value is found 4960in the selected frame. There are special GDB commands to select 4961whichever frame you are interested in. *Note Selecting a Frame: 4962Selection. 4963 4964 When your program stops, GDB automatically selects the currently 4965executing frame and describes it briefly, similar to the `frame' 4966command (*note Information about a Frame: Frame Info.). 4967 4968* Menu: 4969 4970* Frames:: Stack frames 4971* Backtrace:: Backtraces 4972* Selection:: Selecting a frame 4973* Frame Info:: Information on a frame 4974 4975 4976File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack 4977 49788.1 Stack Frames 4979================ 4980 4981The call stack is divided up into contiguous pieces called "stack 4982frames", or "frames" for short; each frame is the data associated with 4983one call to one function. The frame contains the arguments given to 4984the function, the function's local variables, and the address at which 4985the function is executing. 4986 4987 When your program is started, the stack has only one frame, that of 4988the function `main'. This is called the "initial" frame or the 4989"outermost" frame. Each time a function is called, a new frame is 4990made. Each time a function returns, the frame for that function 4991invocation is eliminated. If a function is recursive, there can be 4992many frames for the same function. The frame for the function in which 4993execution is actually occurring is called the "innermost" frame. This 4994is the most recently created of all the stack frames that still exist. 4995 4996 Inside your program, stack frames are identified by their addresses. 4997A stack frame consists of many bytes, each of which has its own 4998address; each kind of computer has a convention for choosing one byte 4999whose address serves as the address of the frame. Usually this address 5000is kept in a register called the "frame pointer register" (*note $fp: 5001Registers.) while execution is going on in that frame. 5002 5003 GDB assigns numbers to all existing stack frames, starting with zero 5004for the innermost frame, one for the frame that called it, and so on 5005upward. These numbers do not really exist in your program; they are 5006assigned by GDB to give you a way of designating stack frames in GDB 5007commands. 5008 5009 Some compilers provide a way to compile functions so that they 5010operate without stack frames. (For example, the GCC option 5011 `-fomit-frame-pointer' 5012 generates functions without a frame.) This is occasionally done 5013with heavily used library functions to save the frame setup time. GDB 5014has limited facilities for dealing with these function invocations. If 5015the innermost function invocation has no stack frame, GDB nevertheless 5016regards it as though it had a separate frame, which is numbered zero as 5017usual, allowing correct tracing of the function call chain. However, 5018GDB has no provision for frameless functions elsewhere in the stack. 5019 5020`frame ARGS' 5021 The `frame' command allows you to move from one stack frame to 5022 another, and to print the stack frame you select. ARGS may be 5023 either the address of the frame or the stack frame number. 5024 Without an argument, `frame' prints the current stack frame. 5025 5026`select-frame' 5027 The `select-frame' command allows you to move from one stack frame 5028 to another without printing the frame. This is the silent version 5029 of `frame'. 5030 5031 5032File: gdb.info, Node: Backtrace, Next: Selection, Prev: Frames, Up: Stack 5033 50348.2 Backtraces 5035============== 5036 5037A backtrace is a summary of how your program got where it is. It shows 5038one line per frame, for many frames, starting with the currently 5039executing frame (frame zero), followed by its caller (frame one), and 5040on up the stack. 5041 5042`backtrace' 5043`bt' 5044 Print a backtrace of the entire stack: one line per frame for all 5045 frames in the stack. 5046 5047 You can stop the backtrace at any time by typing the system 5048 interrupt character, normally `Ctrl-c'. 5049 5050`backtrace N' 5051`bt N' 5052 Similar, but print only the innermost N frames. 5053 5054`backtrace -N' 5055`bt -N' 5056 Similar, but print only the outermost N frames. 5057 5058`backtrace full' 5059`bt full' 5060`bt full N' 5061`bt full -N' 5062 Print the values of the local variables also. N specifies the 5063 number of frames to print, as described above. 5064 5065 The names `where' and `info stack' (abbreviated `info s') are 5066additional aliases for `backtrace'. 5067 5068 In a multi-threaded program, GDB by default shows the backtrace only 5069for the current thread. To display the backtrace for several or all of 5070the threads, use the command `thread apply' (*note thread apply: 5071Threads.). For example, if you type `thread apply all backtrace', GDB 5072will display the backtrace for all the threads; this is handy when you 5073debug a core dump of a multi-threaded program. 5074 5075 Each line in the backtrace shows the frame number and the function 5076name. The program counter value is also shown--unless you use `set 5077print address off'. The backtrace also shows the source file name and 5078line number, as well as the arguments to the function. The program 5079counter value is omitted if it is at the beginning of the code for that 5080line number. 5081 5082 Here is an example of a backtrace. It was made with the command `bt 50833', so it shows the innermost three frames. 5084 5085 #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) 5086 at builtin.c:993 5087 #1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242 5088 #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) 5089 at macro.c:71 5090 (More stack frames follow...) 5091 5092The display for frame zero does not begin with a program counter value, 5093indicating that your program has stopped at the beginning of the code 5094for line `993' of `builtin.c'. 5095 5096The value of parameter `data' in frame 1 has been replaced by `...'. 5097By default, GDB prints the value of a parameter only if it is a scalar 5098(integer, pointer, enumeration, etc). See command `set print 5099frame-arguments' in *Note Print Settings:: for more details on how to 5100configure the way function parameter values are printed. 5101 5102 If your program was compiled with optimizations, some compilers will 5103optimize away arguments passed to functions if those arguments are 5104never used after the call. Such optimizations generate code that 5105passes arguments through registers, but doesn't store those arguments 5106in the stack frame. GDB has no way of displaying such arguments in 5107stack frames other than the innermost one. Here's what such a 5108backtrace might look like: 5109 5110 #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) 5111 at builtin.c:993 5112 #1 0x6e38 in expand_macro (sym=<optimized out>) at macro.c:242 5113 #2 0x6840 in expand_token (obs=0x0, t=<optimized out>, td=0xf7fffb08) 5114 at macro.c:71 5115 (More stack frames follow...) 5116 5117The values of arguments that were not saved in their stack frames are 5118shown as `<optimized out>'. 5119 5120 If you need to display the values of such optimized-out arguments, 5121either deduce that from other variables whose values depend on the one 5122you are interested in, or recompile without optimizations. 5123 5124 Most programs have a standard user entry point--a place where system 5125libraries and startup code transition into user code. For C this is 5126`main'(1). When GDB finds the entry function in a backtrace it will 5127terminate the backtrace, to avoid tracing into highly system-specific 5128(and generally uninteresting) code. 5129 5130 If you need to examine the startup code, or limit the number of 5131levels in a backtrace, you can change this behavior: 5132 5133`set backtrace past-main' 5134`set backtrace past-main on' 5135 Backtraces will continue past the user entry point. 5136 5137`set backtrace past-main off' 5138 Backtraces will stop when they encounter the user entry point. 5139 This is the default. 5140 5141`show backtrace past-main' 5142 Display the current user entry point backtrace policy. 5143 5144`set backtrace past-entry' 5145`set backtrace past-entry on' 5146 Backtraces will continue past the internal entry point of an 5147 application. This entry point is encoded by the linker when the 5148 application is built, and is likely before the user entry point 5149 `main' (or equivalent) is called. 5150 5151`set backtrace past-entry off' 5152 Backtraces will stop when they encounter the internal entry point 5153 of an application. This is the default. 5154 5155`show backtrace past-entry' 5156 Display the current internal entry point backtrace policy. 5157 5158`set backtrace limit N' 5159`set backtrace limit 0' 5160 Limit the backtrace to N levels. A value of zero means unlimited. 5161 5162`show backtrace limit' 5163 Display the current limit on backtrace levels. 5164 5165 ---------- Footnotes ---------- 5166 5167 (1) Note that embedded programs (the so-called "free-standing" 5168environment) are not required to have a `main' function as the entry 5169point. They could even have multiple entry points. 5170 5171 5172File: gdb.info, Node: Selection, Next: Frame Info, Prev: Backtrace, Up: Stack 5173 51748.3 Selecting a Frame 5175===================== 5176 5177Most commands for examining the stack and other data in your program 5178work on whichever stack frame is selected at the moment. Here are the 5179commands for selecting a stack frame; all of them finish by printing a 5180brief description of the stack frame just selected. 5181 5182`frame N' 5183`f N' 5184 Select frame number N. Recall that frame zero is the innermost 5185 (currently executing) frame, frame one is the frame that called the 5186 innermost one, and so on. The highest-numbered frame is the one 5187 for `main'. 5188 5189`frame ADDR' 5190`f ADDR' 5191 Select the frame at address ADDR. This is useful mainly if the 5192 chaining of stack frames has been damaged by a bug, making it 5193 impossible for GDB to assign numbers properly to all frames. In 5194 addition, this can be useful when your program has multiple stacks 5195 and switches between them. 5196 5197 On the SPARC architecture, `frame' needs two addresses to select 5198 an arbitrary frame: a frame pointer and a stack pointer. 5199 5200 On the MIPS and Alpha architecture, it needs two addresses: a stack 5201 pointer and a program counter. 5202 5203 On the 29k architecture, it needs three addresses: a register stack 5204 pointer, a program counter, and a memory stack pointer. 5205 5206`up N' 5207 Move N frames up the stack. For positive numbers N, this advances 5208 toward the outermost frame, to higher frame numbers, to frames 5209 that have existed longer. N defaults to one. 5210 5211`down N' 5212 Move N frames down the stack. For positive numbers N, this 5213 advances toward the innermost frame, to lower frame numbers, to 5214 frames that were created more recently. N defaults to one. You 5215 may abbreviate `down' as `do'. 5216 5217 All of these commands end by printing two lines of output describing 5218the frame. The first line shows the frame number, the function name, 5219the arguments, and the source file and line number of execution in that 5220frame. The second line shows the text of that source line. 5221 5222 For example: 5223 5224 (gdb) up 5225 #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) 5226 at env.c:10 5227 10 read_input_file (argv[i]); 5228 5229 After such a printout, the `list' command with no arguments prints 5230ten lines centered on the point of execution in the frame. You can 5231also edit the program at the point of execution with your favorite 5232editing program by typing `edit'. *Note Printing Source Lines: List, 5233for details. 5234 5235`up-silently N' 5236`down-silently N' 5237 These two commands are variants of `up' and `down', respectively; 5238 they differ in that they do their work silently, without causing 5239 display of the new frame. They are intended primarily for use in 5240 GDB command scripts, where the output might be unnecessary and 5241 distracting. 5242 5243 5244File: gdb.info, Node: Frame Info, Prev: Selection, Up: Stack 5245 52468.4 Information About a Frame 5247============================= 5248 5249There are several other commands to print information about the selected 5250stack frame. 5251 5252`frame' 5253`f' 5254 When used without any argument, this command does not change which 5255 frame is selected, but prints a brief description of the currently 5256 selected stack frame. It can be abbreviated `f'. With an 5257 argument, this command is used to select a stack frame. *Note 5258 Selecting a Frame: Selection. 5259 5260`info frame' 5261`info f' 5262 This command prints a verbose description of the selected stack 5263 frame, including: 5264 5265 * the address of the frame 5266 5267 * the address of the next frame down (called by this frame) 5268 5269 * the address of the next frame up (caller of this frame) 5270 5271 * the language in which the source code corresponding to this 5272 frame is written 5273 5274 * the address of the frame's arguments 5275 5276 * the address of the frame's local variables 5277 5278 * the program counter saved in it (the address of execution in 5279 the caller frame) 5280 5281 * which registers were saved in the frame 5282 5283 The verbose description is useful when something has gone wrong 5284 that has made the stack format fail to fit the usual conventions. 5285 5286`info frame ADDR' 5287`info f ADDR' 5288 Print a verbose description of the frame at address ADDR, without 5289 selecting that frame. The selected frame remains unchanged by this 5290 command. This requires the same kind of address (more than one 5291 for some architectures) that you specify in the `frame' command. 5292 *Note Selecting a Frame: Selection. 5293 5294`info args' 5295 Print the arguments of the selected frame, each on a separate line. 5296 5297`info locals' 5298 Print the local variables of the selected frame, each on a separate 5299 line. These are all variables (declared either static or 5300 automatic) accessible at the point of execution of the selected 5301 frame. 5302 5303`info catch' 5304 Print a list of all the exception handlers that are active in the 5305 current stack frame at the current point of execution. To see 5306 other exception handlers, visit the associated frame (using the 5307 `up', `down', or `frame' commands); then type `info catch'. *Note 5308 Setting Catchpoints: Set Catchpoints. 5309 5310 5311 5312File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top 5313 53149 Examining Source Files 5315************************ 5316 5317GDB can print parts of your program's source, since the debugging 5318information recorded in the program tells GDB what source files were 5319used to build it. When your program stops, GDB spontaneously prints 5320the line where it stopped. Likewise, when you select a stack frame 5321(*note Selecting a Frame: Selection.), GDB prints the line where 5322execution in that frame has stopped. You can print other portions of 5323source files by explicit command. 5324 5325 If you use GDB through its GNU Emacs interface, you may prefer to 5326use Emacs facilities to view source; see *Note Using GDB under GNU 5327Emacs: Emacs. 5328 5329* Menu: 5330 5331* List:: Printing source lines 5332* Specify Location:: How to specify code locations 5333* Edit:: Editing source files 5334* Search:: Searching source files 5335* Source Path:: Specifying source directories 5336* Machine Code:: Source and machine code 5337 5338 5339File: gdb.info, Node: List, Next: Specify Location, Up: Source 5340 53419.1 Printing Source Lines 5342========================= 5343 5344To print lines from a source file, use the `list' command (abbreviated 5345`l'). By default, ten lines are printed. There are several ways to 5346specify what part of the file you want to print; see *Note Specify 5347Location::, for the full list. 5348 5349 Here are the forms of the `list' command most commonly used: 5350 5351`list LINENUM' 5352 Print lines centered around line number LINENUM in the current 5353 source file. 5354 5355`list FUNCTION' 5356 Print lines centered around the beginning of function FUNCTION. 5357 5358`list' 5359 Print more lines. If the last lines printed were printed with a 5360 `list' command, this prints lines following the last lines 5361 printed; however, if the last line printed was a solitary line 5362 printed as part of displaying a stack frame (*note Examining the 5363 Stack: Stack.), this prints lines centered around that line. 5364 5365`list -' 5366 Print lines just before the lines last printed. 5367 5368 By default, GDB prints ten source lines with any of these forms of 5369the `list' command. You can change this using `set listsize': 5370 5371`set listsize COUNT' 5372 Make the `list' command display COUNT source lines (unless the 5373 `list' argument explicitly specifies some other number). 5374 5375`show listsize' 5376 Display the number of lines that `list' prints. 5377 5378 Repeating a `list' command with <RET> discards the argument, so it 5379is equivalent to typing just `list'. This is more useful than listing 5380the same lines again. An exception is made for an argument of `-'; 5381that argument is preserved in repetition so that each repetition moves 5382up in the source file. 5383 5384 In general, the `list' command expects you to supply zero, one or two 5385"linespecs". Linespecs specify source lines; there are several ways of 5386writing them (*note Specify Location::), but the effect is always to 5387specify some source line. 5388 5389 Here is a complete description of the possible arguments for `list': 5390 5391`list LINESPEC' 5392 Print lines centered around the line specified by LINESPEC. 5393 5394`list FIRST,LAST' 5395 Print lines from FIRST to LAST. Both arguments are linespecs. 5396 When a `list' command has two linespecs, and the source file of 5397 the second linespec is omitted, this refers to the same source 5398 file as the first linespec. 5399 5400`list ,LAST' 5401 Print lines ending with LAST. 5402 5403`list FIRST,' 5404 Print lines starting with FIRST. 5405 5406`list +' 5407 Print lines just after the lines last printed. 5408 5409`list -' 5410 Print lines just before the lines last printed. 5411 5412`list' 5413 As described in the preceding table. 5414 5415 5416File: gdb.info, Node: Specify Location, Next: Edit, Prev: List, Up: Source 5417 54189.2 Specifying a Location 5419========================= 5420 5421Several GDB commands accept arguments that specify a location of your 5422program's code. Since GDB is a source-level debugger, a location 5423usually specifies some line in the source code; for that reason, 5424locations are also known as "linespecs". 5425 5426 Here are all the different ways of specifying a code location that 5427GDB understands: 5428 5429`LINENUM' 5430 Specifies the line number LINENUM of the current source file. 5431 5432`-OFFSET' 5433`+OFFSET' 5434 Specifies the line OFFSET lines before or after the "current 5435 line". For the `list' command, the current line is the last one 5436 printed; for the breakpoint commands, this is the line at which 5437 execution stopped in the currently selected "stack frame" (*note 5438 Frames: Frames, for a description of stack frames.) When used as 5439 the second of the two linespecs in a `list' command, this 5440 specifies the line OFFSET lines up or down from the first linespec. 5441 5442`FILENAME:LINENUM' 5443 Specifies the line LINENUM in the source file FILENAME. 5444 5445`FUNCTION' 5446 Specifies the line that begins the body of the function FUNCTION. 5447 For example, in C, this is the line with the open brace. 5448 5449`FUNCTION:LABEL' 5450 Specifies the line where LABEL appears in FUNCTION. 5451 5452`FILENAME:FUNCTION' 5453 Specifies the line that begins the body of the function FUNCTION 5454 in the file FILENAME. You only need the file name with a function 5455 name to avoid ambiguity when there are identically named functions 5456 in different source files. 5457 5458`LABEL' 5459 Specifies the line at which the label named LABEL appears. GDB 5460 searches for the label in the function corresponding to the 5461 currently selected stack frame. If there is no current selected 5462 stack frame (for instance, if the inferior is not running), then 5463 GDB will not search for a label. 5464 5465`*ADDRESS' 5466 Specifies the program address ADDRESS. For line-oriented 5467 commands, such as `list' and `edit', this specifies a source line 5468 that contains ADDRESS. For `break' and other breakpoint oriented 5469 commands, this can be used to set breakpoints in parts of your 5470 program which do not have debugging information or source files. 5471 5472 Here ADDRESS may be any expression valid in the current working 5473 language (*note working language: Languages.) that specifies a code 5474 address. In addition, as a convenience, GDB extends the semantics 5475 of expressions used in locations to cover the situations that 5476 frequently happen during debugging. Here are the various forms of 5477 ADDRESS: 5478 5479 `EXPRESSION' 5480 Any expression valid in the current working language. 5481 5482 `FUNCADDR' 5483 An address of a function or procedure derived from its name. 5484 In C, C++, Java, Objective-C, Fortran, minimal, and assembly, 5485 this is simply the function's name FUNCTION (and actually a 5486 special case of a valid expression). In Pascal and Modula-2, 5487 this is `&FUNCTION'. In Ada, this is `FUNCTION'Address' 5488 (although the Pascal form also works). 5489 5490 This form specifies the address of the function's first 5491 instruction, before the stack frame and arguments have been 5492 set up. 5493 5494 `'FILENAME'::FUNCADDR' 5495 Like FUNCADDR above, but also specifies the name of the source 5496 file explicitly. This is useful if the name of the function 5497 does not specify the function unambiguously, e.g., if there 5498 are several functions with identical names in different 5499 source files. 5500 5501 5502 5503File: gdb.info, Node: Edit, Next: Search, Prev: Specify Location, Up: Source 5504 55059.3 Editing Source Files 5506======================== 5507 5508To edit the lines in a source file, use the `edit' command. The 5509editing program of your choice is invoked with the current line set to 5510the active line in the program. Alternatively, there are several ways 5511to specify what part of the file you want to print if you want to see 5512other parts of the program: 5513 5514`edit LOCATION' 5515 Edit the source file specified by `location'. Editing starts at 5516 that LOCATION, e.g., at the specified source line of the specified 5517 file. *Note Specify Location::, for all the possible forms of the 5518 LOCATION argument; here are the forms of the `edit' command most 5519 commonly used: 5520 5521 `edit NUMBER' 5522 Edit the current source file with NUMBER as the active line 5523 number. 5524 5525 `edit FUNCTION' 5526 Edit the file containing FUNCTION at the beginning of its 5527 definition. 5528 5529 55309.3.1 Choosing your Editor 5531-------------------------- 5532 5533You can customize GDB to use any editor you want (1). By default, it 5534is `/bin/ex', but you can change this by setting the environment 5535variable `EDITOR' before using GDB. For example, to configure GDB to 5536use the `vi' editor, you could use these commands with the `sh' shell: 5537 EDITOR=/usr/bin/vi 5538 export EDITOR 5539 gdb ... 5540 or in the `csh' shell, 5541 setenv EDITOR /usr/bin/vi 5542 gdb ... 5543 5544 ---------- Footnotes ---------- 5545 5546 (1) The only restriction is that your editor (say `ex'), recognizes 5547the following command-line syntax: 5548 ex +NUMBER file 5549 The optional numeric value +NUMBER specifies the number of the line 5550in the file where to start editing. 5551 5552 5553File: gdb.info, Node: Search, Next: Source Path, Prev: Edit, Up: Source 5554 55559.4 Searching Source Files 5556========================== 5557 5558There are two commands for searching through the current source file 5559for a regular expression. 5560 5561`forward-search REGEXP' 5562`search REGEXP' 5563 The command `forward-search REGEXP' checks each line, starting 5564 with the one following the last line listed, for a match for 5565 REGEXP. It lists the line that is found. You can use the synonym 5566 `search REGEXP' or abbreviate the command name as `fo'. 5567 5568`reverse-search REGEXP' 5569 The command `reverse-search REGEXP' checks each line, starting 5570 with the one before the last line listed and going backward, for a 5571 match for REGEXP. It lists the line that is found. You can 5572 abbreviate this command as `rev'. 5573 5574 5575File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source 5576 55779.5 Specifying Source Directories 5578================================= 5579 5580Executable programs sometimes do not record the directories of the 5581source files from which they were compiled, just the names. Even when 5582they do, the directories could be moved between the compilation and 5583your debugging session. GDB has a list of directories to search for 5584source files; this is called the "source path". Each time GDB wants a 5585source file, it tries all the directories in the list, in the order 5586they are present in the list, until it finds a file with the desired 5587name. 5588 5589 For example, suppose an executable references the file 5590`/usr/src/foo-1.0/lib/foo.c', and our source path is `/mnt/cross'. The 5591file is first looked up literally; if this fails, 5592`/mnt/cross/usr/src/foo-1.0/lib/foo.c' is tried; if this fails, 5593`/mnt/cross/foo.c' is opened; if this fails, an error message is 5594printed. GDB does not look up the parts of the source file name, such 5595as `/mnt/cross/src/foo-1.0/lib/foo.c'. Likewise, the subdirectories of 5596the source path are not searched: if the source path is `/mnt/cross', 5597and the binary refers to `foo.c', GDB would not find it under 5598`/mnt/cross/usr/src/foo-1.0/lib'. 5599 5600 Plain file names, relative file names with leading directories, file 5601names containing dots, etc. are all treated as described above; for 5602instance, if the source path is `/mnt/cross', and the source file is 5603recorded as `../lib/foo.c', GDB would first try `../lib/foo.c', then 5604`/mnt/cross/../lib/foo.c', and after that--`/mnt/cross/foo.c'. 5605 5606 Note that the executable search path is _not_ used to locate the 5607source files. 5608 5609 Whenever you reset or rearrange the source path, GDB clears out any 5610information it has cached about where source files are found and where 5611each line is in the file. 5612 5613 When you start GDB, its source path includes only `cdir' and `cwd', 5614in that order. To add other directories, use the `directory' command. 5615 5616 The search path is used to find both program source files and GDB 5617script files (read using the `-command' option and `source' command). 5618 5619 In addition to the source path, GDB provides a set of commands that 5620manage a list of source path substitution rules. A "substitution rule" 5621specifies how to rewrite source directories stored in the program's 5622debug information in case the sources were moved to a different 5623directory between compilation and debugging. A rule is made of two 5624strings, the first specifying what needs to be rewritten in the path, 5625and the second specifying how it should be rewritten. In *Note set 5626substitute-path::, we name these two parts FROM and TO respectively. 5627GDB does a simple string replacement of FROM with TO at the start of 5628the directory part of the source file name, and uses that result 5629instead of the original file name to look up the sources. 5630 5631 Using the previous example, suppose the `foo-1.0' tree has been 5632moved from `/usr/src' to `/mnt/cross', then you can tell GDB to replace 5633`/usr/src' in all source path names with `/mnt/cross'. The first 5634lookup will then be `/mnt/cross/foo-1.0/lib/foo.c' in place of the 5635original location of `/usr/src/foo-1.0/lib/foo.c'. To define a source 5636path substitution rule, use the `set substitute-path' command (*note 5637set substitute-path::). 5638 5639 To avoid unexpected substitution results, a rule is applied only if 5640the FROM part of the directory name ends at a directory separator. For 5641instance, a rule substituting `/usr/source' into `/mnt/cross' will be 5642applied to `/usr/source/foo-1.0' but not to `/usr/sourceware/foo-2.0'. 5643And because the substitution is applied only at the beginning of the 5644directory name, this rule will not be applied to 5645`/root/usr/source/baz.c' either. 5646 5647 In many cases, you can achieve the same result using the `directory' 5648command. However, `set substitute-path' can be more efficient in the 5649case where the sources are organized in a complex tree with multiple 5650subdirectories. With the `directory' command, you need to add each 5651subdirectory of your project. If you moved the entire tree while 5652preserving its internal organization, then `set substitute-path' allows 5653you to direct the debugger to all the sources with one single command. 5654 5655 `set substitute-path' is also more than just a shortcut command. 5656The source path is only used if the file at the original location no 5657longer exists. On the other hand, `set substitute-path' modifies the 5658debugger behavior to look at the rewritten location instead. So, if 5659for any reason a source file that is not relevant to your executable is 5660located at the original location, a substitution rule is the only 5661method available to point GDB at the new location. 5662 5663 You can configure a default source path substitution rule by 5664configuring GDB with the `--with-relocated-sources=DIR' option. The DIR 5665should be the name of a directory under GDB's configured prefix (set 5666with `--prefix' or `--exec-prefix'), and directory names in debug 5667information under DIR will be adjusted automatically if the installed 5668GDB is moved to a new location. This is useful if GDB, libraries or 5669executables with debug information and corresponding source code are 5670being moved together. 5671 5672`directory DIRNAME ...' 5673 5674`dir DIRNAME ...' 5675 Add directory DIRNAME to the front of the source path. Several 5676 directory names may be given to this command, separated by `:' 5677 (`;' on MS-DOS and MS-Windows, where `:' usually appears as part 5678 of absolute file names) or whitespace. You may specify a 5679 directory that is already in the source path; this moves it 5680 forward, so GDB searches it sooner. 5681 5682 You can use the string `$cdir' to refer to the compilation 5683 directory (if one is recorded), and `$cwd' to refer to the current 5684 working directory. `$cwd' is not the same as `.'--the former 5685 tracks the current working directory as it changes during your GDB 5686 session, while the latter is immediately expanded to the current 5687 directory at the time you add an entry to the source path. 5688 5689`directory' 5690 Reset the source path to its default value (`$cdir:$cwd' on Unix 5691 systems). This requires confirmation. 5692 5693`set directories PATH-LIST' 5694 Set the source path to PATH-LIST. `$cdir:$cwd' are added if 5695 missing. 5696 5697`show directories' 5698 Print the source path: show which directories it contains. 5699 5700`set substitute-path FROM TO' 5701 Define a source path substitution rule, and add it at the end of 5702 the current list of existing substitution rules. If a rule with 5703 the same FROM was already defined, then the old rule is also 5704 deleted. 5705 5706 For example, if the file `/foo/bar/baz.c' was moved to 5707 `/mnt/cross/baz.c', then the command 5708 5709 (gdb) set substitute-path /usr/src /mnt/cross 5710 5711 will tell GDB to replace `/usr/src' with `/mnt/cross', which will 5712 allow GDB to find the file `baz.c' even though it was moved. 5713 5714 In the case when more than one substitution rule have been defined, 5715 the rules are evaluated one by one in the order where they have 5716 been defined. The first one matching, if any, is selected to 5717 perform the substitution. 5718 5719 For instance, if we had entered the following commands: 5720 5721 (gdb) set substitute-path /usr/src/include /mnt/include 5722 (gdb) set substitute-path /usr/src /mnt/src 5723 5724 GDB would then rewrite `/usr/src/include/defs.h' into 5725 `/mnt/include/defs.h' by using the first rule. However, it would 5726 use the second rule to rewrite `/usr/src/lib/foo.c' into 5727 `/mnt/src/lib/foo.c'. 5728 5729`unset substitute-path [path]' 5730 If a path is specified, search the current list of substitution 5731 rules for a rule that would rewrite that path. Delete that rule 5732 if found. A warning is emitted by the debugger if no rule could 5733 be found. 5734 5735 If no path is specified, then all substitution rules are deleted. 5736 5737`show substitute-path [path]' 5738 If a path is specified, then print the source path substitution 5739 rule which would rewrite that path, if any. 5740 5741 If no path is specified, then print all existing source path 5742 substitution rules. 5743 5744 5745 If your source path is cluttered with directories that are no longer 5746of interest, GDB may sometimes cause confusion by finding the wrong 5747versions of source. You can correct the situation as follows: 5748 5749 1. Use `directory' with no argument to reset the source path to its 5750 default value. 5751 5752 2. Use `directory' with suitable arguments to reinstall the 5753 directories you want in the source path. You can add all the 5754 directories in one command. 5755 5756 5757File: gdb.info, Node: Machine Code, Prev: Source Path, Up: Source 5758 57599.6 Source and Machine Code 5760=========================== 5761 5762You can use the command `info line' to map source lines to program 5763addresses (and vice versa), and the command `disassemble' to display a 5764range of addresses as machine instructions. You can use the command 5765`set disassemble-next-line' to set whether to disassemble next source 5766line when execution stops. When run under GNU Emacs mode, the `info 5767line' command causes the arrow to point to the line specified. Also, 5768`info line' prints addresses in symbolic form as well as hex. 5769 5770`info line LINESPEC' 5771 Print the starting and ending addresses of the compiled code for 5772 source line LINESPEC. You can specify source lines in any of the 5773 ways documented in *Note Specify Location::. 5774 5775 For example, we can use `info line' to discover the location of the 5776object code for the first line of function `m4_changequote': 5777 5778 (gdb) info line m4_changequote 5779 Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. 5780 5781We can also inquire (using `*ADDR' as the form for LINESPEC) what 5782source line covers a particular address: 5783 (gdb) info line *0x63ff 5784 Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. 5785 5786 After `info line', the default address for the `x' command is 5787changed to the starting address of the line, so that `x/i' is 5788sufficient to begin examining the machine code (*note Examining Memory: 5789Memory.). Also, this address is saved as the value of the convenience 5790variable `$_' (*note Convenience Variables: Convenience Vars.). 5791 5792`disassemble' 5793`disassemble /m' 5794`disassemble /r' 5795 This specialized command dumps a range of memory as machine 5796 instructions. It can also print mixed source+disassembly by 5797 specifying the `/m' modifier and print the raw instructions in hex 5798 as well as in symbolic form by specifying the `/r'. The default 5799 memory range is the function surrounding the program counter of 5800 the selected frame. A single argument to this command is a 5801 program counter value; GDB dumps the function surrounding this 5802 value. When two arguments are given, they should be separated by 5803 a comma, possibly surrounded by whitespace. The arguments specify 5804 a range of addresses to dump, in one of two forms: 5805 5806 `START,END' 5807 the addresses from START (inclusive) to END (exclusive) 5808 5809 `START,+LENGTH' 5810 the addresses from START (inclusive) to `START+LENGTH' 5811 (exclusive). 5812 5813 When 2 arguments are specified, the name of the function is also 5814 printed (since there could be several functions in the given 5815 range). 5816 5817 The argument(s) can be any expression yielding a numeric value, 5818 such as `0x32c4', `&main+10' or `$pc - 8'. 5819 5820 If the range of memory being disassembled contains current program 5821 counter, the instruction at that location is shown with a `=>' 5822 marker. 5823 5824 The following example shows the disassembly of a range of addresses 5825of HP PA-RISC 2.0 code: 5826 5827 (gdb) disas 0x32c4, 0x32e4 5828 Dump of assembler code from 0x32c4 to 0x32e4: 5829 0x32c4 <main+204>: addil 0,dp 5830 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 5831 0x32cc <main+212>: ldil 0x3000,r31 5832 0x32d0 <main+216>: ble 0x3f8(sr4,r31) 5833 0x32d4 <main+220>: ldo 0(r31),rp 5834 0x32d8 <main+224>: addil -0x800,dp 5835 0x32dc <main+228>: ldo 0x588(r1),r26 5836 0x32e0 <main+232>: ldil 0x3000,r31 5837 End of assembler dump. 5838 5839 Here is an example showing mixed source+assembly for Intel x86, when 5840the program is stopped just after function prologue: 5841 5842 (gdb) disas /m main 5843 Dump of assembler code for function main: 5844 5 { 5845 0x08048330 <+0>: push %ebp 5846 0x08048331 <+1>: mov %esp,%ebp 5847 0x08048333 <+3>: sub $0x8,%esp 5848 0x08048336 <+6>: and $0xfffffff0,%esp 5849 0x08048339 <+9>: sub $0x10,%esp 5850 5851 6 printf ("Hello.\n"); 5852 => 0x0804833c <+12>: movl $0x8048440,(%esp) 5853 0x08048343 <+19>: call 0x8048284 <puts@plt> 5854 5855 7 return 0; 5856 8 } 5857 0x08048348 <+24>: mov $0x0,%eax 5858 0x0804834d <+29>: leave 5859 0x0804834e <+30>: ret 5860 5861 End of assembler dump. 5862 5863 Here is another example showing raw instructions in hex for AMD 5864x86-64, 5865 5866 (gdb) disas /r 0x400281,+10 5867 Dump of assembler code from 0x400281 to 0x40028b: 5868 0x0000000000400281: 38 36 cmp %dh,(%rsi) 5869 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax 5870 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx) 5871 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al 5872 End of assembler dump. 5873 5874 Some architectures have more than one commonly-used set of 5875instruction mnemonics or other syntax. 5876 5877 For programs that were dynamically linked and use shared libraries, 5878instructions that call functions or branch to locations in the shared 5879libraries might show a seemingly bogus location--it's actually a 5880location of the relocation table. On some architectures, GDB might be 5881able to resolve these to actual function names. 5882 5883`set disassembly-flavor INSTRUCTION-SET' 5884 Select the instruction set to use when disassembling the program 5885 via the `disassemble' or `x/i' commands. 5886 5887 Currently this command is only defined for the Intel x86 family. 5888 You can set INSTRUCTION-SET to either `intel' or `att'. The 5889 default is `att', the AT&T flavor used by default by Unix 5890 assemblers for x86-based targets. 5891 5892`show disassembly-flavor' 5893 Show the current setting of the disassembly flavor. 5894 5895`set disassemble-next-line' 5896`show disassemble-next-line' 5897 Control whether or not GDB will disassemble the next source line 5898 or instruction when execution stops. If ON, GDB will display 5899 disassembly of the next source line when execution of the program 5900 being debugged stops. This is _in addition_ to displaying the 5901 source line itself, which GDB always does if possible. If the 5902 next source line cannot be displayed for some reason (e.g., if GDB 5903 cannot find the source file, or there's no line info in the debug 5904 info), GDB will display disassembly of the next _instruction_ 5905 instead of showing the next source line. If AUTO, GDB will 5906 display disassembly of next instruction only if the source line 5907 cannot be displayed. This setting causes GDB to display some 5908 feedback when you step through a function with no line info or 5909 whose source file is unavailable. The default is OFF, which means 5910 never display the disassembly of the next line or instruction. 5911 5912 5913File: gdb.info, Node: Data, Next: Optimized Code, Prev: Source, Up: Top 5914 591510 Examining Data 5916***************** 5917 5918The usual way to examine data in your program is with the `print' 5919command (abbreviated `p'), or its synonym `inspect'. It evaluates and 5920prints the value of an expression of the language your program is 5921written in (*note Using GDB with Different Languages: Languages.). It 5922may also print the expression using a Python-based pretty-printer 5923(*note Pretty Printing::). 5924 5925`print EXPR' 5926`print /F EXPR' 5927 EXPR is an expression (in the source language). By default the 5928 value of EXPR is printed in a format appropriate to its data type; 5929 you can choose a different format by specifying `/F', where F is a 5930 letter specifying the format; see *Note Output Formats: Output 5931 Formats. 5932 5933`print' 5934`print /F' 5935 If you omit EXPR, GDB displays the last value again (from the 5936 "value history"; *note Value History: Value History.). This 5937 allows you to conveniently inspect the same value in an 5938 alternative format. 5939 5940 A more low-level way of examining data is with the `x' command. It 5941examines data in memory at a specified address and prints it in a 5942specified format. *Note Examining Memory: Memory. 5943 5944 If you are interested in information about types, or about how the 5945fields of a struct or a class are declared, use the `ptype EXP' command 5946rather than `print'. *Note Examining the Symbol Table: Symbols. 5947 5948* Menu: 5949 5950* Expressions:: Expressions 5951* Ambiguous Expressions:: Ambiguous Expressions 5952* Variables:: Program variables 5953* Arrays:: Artificial arrays 5954* Output Formats:: Output formats 5955* Memory:: Examining memory 5956* Auto Display:: Automatic display 5957* Print Settings:: Print settings 5958* Pretty Printing:: Python pretty printing 5959* Value History:: Value history 5960* Convenience Vars:: Convenience variables 5961* Registers:: Registers 5962* Floating Point Hardware:: Floating point hardware 5963* Vector Unit:: Vector Unit 5964* OS Information:: Auxiliary data provided by operating system 5965* Memory Region Attributes:: Memory region attributes 5966* Dump/Restore Files:: Copy between memory and a file 5967* Core File Generation:: Cause a program dump its core 5968* Character Sets:: Debugging programs that use a different 5969 character set than GDB does 5970* Caching Remote Data:: Data caching for remote targets 5971* Searching Memory:: Searching memory for a sequence of bytes 5972 5973 5974File: gdb.info, Node: Expressions, Next: Ambiguous Expressions, Up: Data 5975 597610.1 Expressions 5977================ 5978 5979`print' and many other GDB commands accept an expression and compute 5980its value. Any kind of constant, variable or operator defined by the 5981programming language you are using is valid in an expression in GDB. 5982This includes conditional expressions, function calls, casts, and 5983string constants. It also includes preprocessor macros, if you 5984compiled your program to include this information; see *Note 5985Compilation::. 5986 5987 GDB supports array constants in expressions input by the user. The 5988syntax is {ELEMENT, ELEMENT...}. For example, you can use the command 5989`print {1, 2, 3}' to create an array of three integers. If you pass an 5990array to a function or assign it to a program variable, GDB copies the 5991array to memory that is `malloc'ed in the target program. 5992 5993 Because C is so widespread, most of the expressions shown in 5994examples in this manual are in C. *Note Using GDB with Different 5995Languages: Languages, for information on how to use expressions in other 5996languages. 5997 5998 In this section, we discuss operators that you can use in GDB 5999expressions regardless of your programming language. 6000 6001 Casts are supported in all languages, not just in C, because it is so 6002useful to cast a number into a pointer in order to examine a structure 6003at that address in memory. 6004 6005 GDB supports these operators, in addition to those common to 6006programming languages: 6007 6008`@' 6009 `@' is a binary operator for treating parts of memory as arrays. 6010 *Note Artificial Arrays: Arrays, for more information. 6011 6012`::' 6013 `::' allows you to specify a variable in terms of the file or 6014 function where it is defined. *Note Program Variables: Variables. 6015 6016`{TYPE} ADDR' 6017 Refers to an object of type TYPE stored at address ADDR in memory. 6018 ADDR may be any expression whose value is an integer or pointer 6019 (but parentheses are required around binary operators, just as in 6020 a cast). This construct is allowed regardless of what kind of 6021 data is normally supposed to reside at ADDR. 6022 6023 6024File: gdb.info, Node: Ambiguous Expressions, Next: Variables, Prev: Expressions, Up: Data 6025 602610.2 Ambiguous Expressions 6027========================== 6028 6029Expressions can sometimes contain some ambiguous elements. For 6030instance, some programming languages (notably Ada, C++ and Objective-C) 6031permit a single function name to be defined several times, for 6032application in different contexts. This is called "overloading". 6033Another example involving Ada is generics. A "generic package" is 6034similar to C++ templates and is typically instantiated several times, 6035resulting in the same function name being defined in different contexts. 6036 6037 In some cases and depending on the language, it is possible to adjust 6038the expression to remove the ambiguity. For instance in C++, you can 6039specify the signature of the function you want to break on, as in 6040`break FUNCTION(TYPES)'. In Ada, using the fully qualified name of 6041your function often makes the expression unambiguous as well. 6042 6043 When an ambiguity that needs to be resolved is detected, the debugger 6044has the capability to display a menu of numbered choices for each 6045possibility, and then waits for the selection with the prompt `>'. The 6046first option is always `[0] cancel', and typing `0 <RET>' aborts the 6047current command. If the command in which the expression was used 6048allows more than one choice to be selected, the next option in the menu 6049is `[1] all', and typing `1 <RET>' selects all possible choices. 6050 6051 For example, the following session excerpt shows an attempt to set a 6052breakpoint at the overloaded symbol `String::after'. We choose three 6053particular definitions of that function name: 6054 6055 (gdb) b String::after 6056 [0] cancel 6057 [1] all 6058 [2] file:String.cc; line number:867 6059 [3] file:String.cc; line number:860 6060 [4] file:String.cc; line number:875 6061 [5] file:String.cc; line number:853 6062 [6] file:String.cc; line number:846 6063 [7] file:String.cc; line number:735 6064 > 2 4 6 6065 Breakpoint 1 at 0xb26c: file String.cc, line 867. 6066 Breakpoint 2 at 0xb344: file String.cc, line 875. 6067 Breakpoint 3 at 0xafcc: file String.cc, line 846. 6068 Multiple breakpoints were set. 6069 Use the "delete" command to delete unwanted 6070 breakpoints. 6071 (gdb) 6072 6073`set multiple-symbols MODE' 6074 This option allows you to adjust the debugger behavior when an 6075 expression is ambiguous. 6076 6077 By default, MODE is set to `all'. If the command with which the 6078 expression is used allows more than one choice, then GDB 6079 automatically selects all possible choices. For instance, 6080 inserting a breakpoint on a function using an ambiguous name 6081 results in a breakpoint inserted on each possible match. However, 6082 if a unique choice must be made, then GDB uses the menu to help 6083 you disambiguate the expression. For instance, printing the 6084 address of an overloaded function will result in the use of the 6085 menu. 6086 6087 When MODE is set to `ask', the debugger always uses the menu when 6088 an ambiguity is detected. 6089 6090 Finally, when MODE is set to `cancel', the debugger reports an 6091 error due to the ambiguity and the command is aborted. 6092 6093`show multiple-symbols' 6094 Show the current value of the `multiple-symbols' setting. 6095 6096 6097File: gdb.info, Node: Variables, Next: Arrays, Prev: Ambiguous Expressions, Up: Data 6098 609910.3 Program Variables 6100====================== 6101 6102The most common kind of expression to use is the name of a variable in 6103your program. 6104 6105 Variables in expressions are understood in the selected stack frame 6106(*note Selecting a Frame: Selection.); they must be either: 6107 6108 * global (or file-static) 6109 6110or 6111 6112 * visible according to the scope rules of the programming language 6113 from the point of execution in that frame 6114 6115This means that in the function 6116 6117 foo (a) 6118 int a; 6119 { 6120 bar (a); 6121 { 6122 int b = test (); 6123 bar (b); 6124 } 6125 } 6126 6127you can examine and use the variable `a' whenever your program is 6128executing within the function `foo', but you can only use or examine 6129the variable `b' while your program is executing inside the block where 6130`b' is declared. 6131 6132 There is an exception: you can refer to a variable or function whose 6133scope is a single source file even if the current execution point is not 6134in this file. But it is possible to have more than one such variable or 6135function with the same name (in different source files). If that 6136happens, referring to that name has unpredictable effects. If you wish, 6137you can specify a static variable in a particular function or file, 6138using the colon-colon (`::') notation: 6139 6140 FILE::VARIABLE 6141 FUNCTION::VARIABLE 6142 6143Here FILE or FUNCTION is the name of the context for the static 6144VARIABLE. In the case of file names, you can use quotes to make sure 6145GDB parses the file name as a single word--for example, to print a 6146global value of `x' defined in `f2.c': 6147 6148 (gdb) p 'f2.c'::x 6149 6150 This use of `::' is very rarely in conflict with the very similar 6151use of the same notation in C++. GDB also supports use of the C++ 6152scope resolution operator in GDB expressions. 6153 6154 _Warning:_ Occasionally, a local variable may appear to have the 6155 wrong value at certain points in a function--just after entry to a 6156 new scope, and just before exit. 6157 You may see this problem when you are stepping by machine 6158instructions. This is because, on most machines, it takes more than 6159one instruction to set up a stack frame (including local variable 6160definitions); if you are stepping by machine instructions, variables 6161may appear to have the wrong values until the stack frame is completely 6162built. On exit, it usually also takes more than one machine 6163instruction to destroy a stack frame; after you begin stepping through 6164that group of instructions, local variable definitions may be gone. 6165 6166 This may also happen when the compiler does significant 6167optimizations. To be sure of always seeing accurate values, turn off 6168all optimization when compiling. 6169 6170 Another possible effect of compiler optimizations is to optimize 6171unused variables out of existence, or assign variables to registers (as 6172opposed to memory addresses). Depending on the support for such cases 6173offered by the debug info format used by the compiler, GDB might not be 6174able to display values for such local variables. If that happens, GDB 6175will print a message like this: 6176 6177 No symbol "foo" in current context. 6178 6179 To solve such problems, either recompile without optimizations, or 6180use a different debug info format, if the compiler supports several such 6181formats. For example, GCC, the GNU C/C++ compiler, usually supports 6182the `-gstabs+' option. `-gstabs+' produces debug info in a format that 6183is superior to formats such as COFF. You may be able to use DWARF 2 6184(`-gdwarf-2'), which is also an effective form for debug info. *Note 6185Options for Debugging Your Program or GCC: (gcc.info)Debugging Options. 6186*Note C and C++: C, for more information about debug info formats that 6187are best suited to C++ programs. 6188 6189 If you ask to print an object whose contents are unknown to GDB, 6190e.g., because its data type is not completely specified by the debug 6191information, GDB will say `<incomplete type>'. *Note incomplete type: 6192Symbols, for more about this. 6193 6194 Strings are identified as arrays of `char' values without specified 6195signedness. Arrays of either `signed char' or `unsigned char' get 6196printed as arrays of 1 byte sized integers. `-fsigned-char' or 6197`-funsigned-char' GCC options have no effect as GDB defines literal 6198string type `"char"' as `char' without a sign. For program code 6199 6200 char var0[] = "A"; 6201 signed char var1[] = "A"; 6202 6203 You get during debugging 6204 (gdb) print var0 6205 $1 = "A" 6206 (gdb) print var1 6207 $2 = {65 'A', 0 '\0'} 6208 6209 6210File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data 6211 621210.4 Artificial Arrays 6213====================== 6214 6215It is often useful to print out several successive objects of the same 6216type in memory; a section of an array, or an array of dynamically 6217determined size for which only a pointer exists in the program. 6218 6219 You can do this by referring to a contiguous span of memory as an 6220"artificial array", using the binary operator `@'. The left operand of 6221`@' should be the first element of the desired array and be an 6222individual object. The right operand should be the desired length of 6223the array. The result is an array value whose elements are all of the 6224type of the left argument. The first element is actually the left 6225argument; the second element comes from bytes of memory immediately 6226following those that hold the first element, and so on. Here is an 6227example. If a program says 6228 6229 int *array = (int *) malloc (len * sizeof (int)); 6230 6231you can print the contents of `array' with 6232 6233 p *array@len 6234 6235 The left operand of `@' must reside in memory. Array values made 6236with `@' in this way behave just like other arrays in terms of 6237subscripting, and are coerced to pointers when used in expressions. 6238Artificial arrays most often appear in expressions via the value history 6239(*note Value History: Value History.), after printing one out. 6240 6241 Another way to create an artificial array is to use a cast. This 6242re-interprets a value as if it were an array. The value need not be in 6243memory: 6244 (gdb) p/x (short[2])0x12345678 6245 $1 = {0x1234, 0x5678} 6246 6247 As a convenience, if you leave the array length out (as in 6248`(TYPE[])VALUE') GDB calculates the size to fill the value (as 6249`sizeof(VALUE)/sizeof(TYPE)': 6250 (gdb) p/x (short[])0x12345678 6251 $2 = {0x1234, 0x5678} 6252 6253 Sometimes the artificial array mechanism is not quite enough; in 6254moderately complex data structures, the elements of interest may not 6255actually be adjacent--for example, if you are interested in the values 6256of pointers in an array. One useful work-around in this situation is 6257to use a convenience variable (*note Convenience Variables: Convenience 6258Vars.) as a counter in an expression that prints the first interesting 6259value, and then repeat that expression via <RET>. For instance, 6260suppose you have an array `dtab' of pointers to structures, and you are 6261interested in the values of a field `fv' in each structure. Here is an 6262example of what you might type: 6263 6264 set $i = 0 6265 p dtab[$i++]->fv 6266 <RET> 6267 <RET> 6268 ... 6269 6270 6271File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data 6272 627310.5 Output Formats 6274=================== 6275 6276By default, GDB prints a value according to its data type. Sometimes 6277this is not what you want. For example, you might want to print a 6278number in hex, or a pointer in decimal. Or you might want to view data 6279in memory at a certain address as a character string or as an 6280instruction. To do these things, specify an "output format" when you 6281print a value. 6282 6283 The simplest use of output formats is to say how to print a value 6284already computed. This is done by starting the arguments of the 6285`print' command with a slash and a format letter. The format letters 6286supported are: 6287 6288`x' 6289 Regard the bits of the value as an integer, and print the integer 6290 in hexadecimal. 6291 6292`d' 6293 Print as integer in signed decimal. 6294 6295`u' 6296 Print as integer in unsigned decimal. 6297 6298`o' 6299 Print as integer in octal. 6300 6301`t' 6302 Print as integer in binary. The letter `t' stands for "two". (1) 6303 6304`a' 6305 Print as an address, both absolute in hexadecimal and as an offset 6306 from the nearest preceding symbol. You can use this format used 6307 to discover where (in what function) an unknown address is located: 6308 6309 (gdb) p/a 0x54320 6310 $3 = 0x54320 <_initialize_vx+396> 6311 6312 The command `info symbol 0x54320' yields similar results. *Note 6313 info symbol: Symbols. 6314 6315`c' 6316 Regard as an integer and print it as a character constant. This 6317 prints both the numerical value and its character representation. 6318 The character representation is replaced with the octal escape 6319 `\nnn' for characters outside the 7-bit ASCII range. 6320 6321 Without this format, GDB displays `char', `unsigned char', and 6322 `signed char' data as character constants. Single-byte members of 6323 vectors are displayed as integer data. 6324 6325`f' 6326 Regard the bits of the value as a floating point number and print 6327 using typical floating point syntax. 6328 6329`s' 6330 Regard as a string, if possible. With this format, pointers to 6331 single-byte data are displayed as null-terminated strings and 6332 arrays of single-byte data are displayed as fixed-length strings. 6333 Other values are displayed in their natural types. 6334 6335 Without this format, GDB displays pointers to and arrays of 6336 `char', `unsigned char', and `signed char' as strings. 6337 Single-byte members of a vector are displayed as an integer array. 6338 6339`r' 6340 Print using the `raw' formatting. By default, GDB will use a 6341 Python-based pretty-printer, if one is available (*note Pretty 6342 Printing::). This typically results in a higher-level display of 6343 the value's contents. The `r' format bypasses any Python 6344 pretty-printer which might exist. 6345 6346 For example, to print the program counter in hex (*note 6347Registers::), type 6348 6349 p/x $pc 6350 6351Note that no space is required before the slash; this is because command 6352names in GDB cannot contain a slash. 6353 6354 To reprint the last value in the value history with a different 6355format, you can use the `print' command with just a format and no 6356expression. For example, `p/x' reprints the last value in hex. 6357 6358 ---------- Footnotes ---------- 6359 6360 (1) `b' cannot be used because these format letters are also used 6361with the `x' command, where `b' stands for "byte"; see *Note Examining 6362Memory: Memory. 6363 6364 6365File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data 6366 636710.6 Examining Memory 6368===================== 6369 6370You can use the command `x' (for "examine") to examine memory in any of 6371several formats, independently of your program's data types. 6372 6373`x/NFU ADDR' 6374`x ADDR' 6375`x' 6376 Use the `x' command to examine memory. 6377 6378 N, F, and U are all optional parameters that specify how much memory 6379to display and how to format it; ADDR is an expression giving the 6380address where you want to start displaying memory. If you use defaults 6381for NFU, you need not type the slash `/'. Several commands set 6382convenient defaults for ADDR. 6383 6384N, the repeat count 6385 The repeat count is a decimal integer; the default is 1. It 6386 specifies how much memory (counting by units U) to display. 6387 6388F, the display format 6389 The display format is one of the formats used by `print' (`x', 6390 `d', `u', `o', `t', `a', `c', `f', `s'), and in addition `i' (for 6391 machine instructions). The default is `x' (hexadecimal) 6392 initially. The default changes each time you use either `x' or 6393 `print'. 6394 6395U, the unit size 6396 The unit size is any of 6397 6398 `b' 6399 Bytes. 6400 6401 `h' 6402 Halfwords (two bytes). 6403 6404 `w' 6405 Words (four bytes). This is the initial default. 6406 6407 `g' 6408 Giant words (eight bytes). 6409 6410 Each time you specify a unit size with `x', that size becomes the 6411 default unit the next time you use `x'. For the `i' format, the 6412 unit size is ignored and is normally not written. For the `s' 6413 format, the unit size defaults to `b', unless it is explicitly 6414 given. Use `x /hs' to display 16-bit char strings and `x /ws' to 6415 display 32-bit strings. The next use of `x /s' will again display 6416 8-bit strings. Note that the results depend on the programming 6417 language of the current compilation unit. If the language is C, 6418 the `s' modifier will use the UTF-16 encoding while `w' will use 6419 UTF-32. The encoding is set by the programming language and cannot 6420 be altered. 6421 6422ADDR, starting display address 6423 ADDR is the address where you want GDB to begin displaying memory. 6424 The expression need not have a pointer value (though it may); it 6425 is always interpreted as an integer address of a byte of memory. 6426 *Note Expressions: Expressions, for more information on 6427 expressions. The default for ADDR is usually just after the last 6428 address examined--but several other commands also set the default 6429 address: `info breakpoints' (to the address of the last breakpoint 6430 listed), `info line' (to the starting address of a line), and 6431 `print' (if you use it to display a value from memory). 6432 6433 For example, `x/3uh 0x54320' is a request to display three halfwords 6434(`h') of memory, formatted as unsigned decimal integers (`u'), starting 6435at address `0x54320'. `x/4xw $sp' prints the four words (`w') of 6436memory above the stack pointer (here, `$sp'; *note Registers: 6437Registers.) in hexadecimal (`x'). 6438 6439 Since the letters indicating unit sizes are all distinct from the 6440letters specifying output formats, you do not have to remember whether 6441unit size or format comes first; either order works. The output 6442specifications `4xw' and `4wx' mean exactly the same thing. (However, 6443the count N must come first; `wx4' does not work.) 6444 6445 Even though the unit size U is ignored for the formats `s' and `i', 6446you might still want to use a count N; for example, `3i' specifies that 6447you want to see three machine instructions, including any operands. 6448For convenience, especially when used with the `display' command, the 6449`i' format also prints branch delay slot instructions, if any, beyond 6450the count specified, which immediately follow the last instruction that 6451is within the count. The command `disassemble' gives an alternative 6452way of inspecting machine instructions; see *Note Source and Machine 6453Code: Machine Code. 6454 6455 All the defaults for the arguments to `x' are designed to make it 6456easy to continue scanning memory with minimal specifications each time 6457you use `x'. For example, after you have inspected three machine 6458instructions with `x/3i ADDR', you can inspect the next seven with just 6459`x/7'. If you use <RET> to repeat the `x' command, the repeat count N 6460is used again; the other arguments default as for successive uses of 6461`x'. 6462 6463 When examining machine instructions, the instruction at current 6464program counter is shown with a `=>' marker. For example: 6465 6466 (gdb) x/5i $pc-6 6467 0x804837f <main+11>: mov %esp,%ebp 6468 0x8048381 <main+13>: push %ecx 6469 0x8048382 <main+14>: sub $0x4,%esp 6470 => 0x8048385 <main+17>: movl $0x8048460,(%esp) 6471 0x804838c <main+24>: call 0x80482d4 <puts@plt> 6472 6473 The addresses and contents printed by the `x' command are not saved 6474in the value history because there is often too much of them and they 6475would get in the way. Instead, GDB makes these values available for 6476subsequent use in expressions as values of the convenience variables 6477`$_' and `$__'. After an `x' command, the last address examined is 6478available for use in expressions in the convenience variable `$_'. The 6479contents of that address, as examined, are available in the convenience 6480variable `$__'. 6481 6482 If the `x' command has a repeat count, the address and contents saved 6483are from the last memory unit printed; this is not the same as the last 6484address printed if several units were printed on the last line of 6485output. 6486 6487 When you are debugging a program running on a remote target machine 6488(*note Remote Debugging::), you may wish to verify the program's image 6489in the remote machine's memory against the executable file you 6490downloaded to the target. The `compare-sections' command is provided 6491for such situations. 6492 6493`compare-sections [SECTION-NAME]' 6494 Compare the data of a loadable section SECTION-NAME in the 6495 executable file of the program being debugged with the same 6496 section in the remote machine's memory, and report any mismatches. 6497 With no arguments, compares all loadable sections. This command's 6498 availability depends on the target's support for the `"qCRC"' 6499 remote request. 6500 6501 6502File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data 6503 650410.7 Automatic Display 6505====================== 6506 6507If you find that you want to print the value of an expression frequently 6508(to see how it changes), you might want to add it to the "automatic 6509display list" so that GDB prints its value each time your program stops. 6510Each expression added to the list is given a number to identify it; to 6511remove an expression from the list, you specify that number. The 6512automatic display looks like this: 6513 6514 2: foo = 38 6515 3: bar[5] = (struct hack *) 0x3804 6516 6517This display shows item numbers, expressions and their current values. 6518As with displays you request manually using `x' or `print', you can 6519specify the output format you prefer; in fact, `display' decides 6520whether to use `print' or `x' depending your format specification--it 6521uses `x' if you specify either the `i' or `s' format, or a unit size; 6522otherwise it uses `print'. 6523 6524`display EXPR' 6525 Add the expression EXPR to the list of expressions to display each 6526 time your program stops. *Note Expressions: Expressions. 6527 6528 `display' does not repeat if you press <RET> again after using it. 6529 6530`display/FMT EXPR' 6531 For FMT specifying only a display format and not a size or count, 6532 add the expression EXPR to the auto-display list but arrange to 6533 display it each time in the specified format FMT. *Note Output 6534 Formats: Output Formats. 6535 6536`display/FMT ADDR' 6537 For FMT `i' or `s', or including a unit-size or a number of units, 6538 add the expression ADDR as a memory address to be examined each 6539 time your program stops. Examining means in effect doing `x/FMT 6540 ADDR'. *Note Examining Memory: Memory. 6541 6542 For example, `display/i $pc' can be helpful, to see the machine 6543instruction about to be executed each time execution stops (`$pc' is a 6544common name for the program counter; *note Registers: Registers.). 6545 6546`undisplay DNUMS...' 6547`delete display DNUMS...' 6548 Remove items from the list of expressions to display. Specify the 6549 numbers of the displays that you want affected with the command 6550 argument DNUMS. It can be a single display number, one of the 6551 numbers shown in the first field of the `info display' display; or 6552 it could be a range of display numbers, as in `2-4'. 6553 6554 `undisplay' does not repeat if you press <RET> after using it. 6555 (Otherwise you would just get the error `No display number ...'.) 6556 6557`disable display DNUMS...' 6558 Disable the display of item numbers DNUMS. A disabled display 6559 item is not printed automatically, but is not forgotten. It may be 6560 enabled again later. Specify the numbers of the displays that you 6561 want affected with the command argument DNUMS. It can be a single 6562 display number, one of the numbers shown in the first field of the 6563 `info display' display; or it could be a range of display numbers, 6564 as in `2-4'. 6565 6566`enable display DNUMS...' 6567 Enable display of item numbers DNUMS. It becomes effective once 6568 again in auto display of its expression, until you specify 6569 otherwise. Specify the numbers of the displays that you want 6570 affected with the command argument DNUMS. It can be a single 6571 display number, one of the numbers shown in the first field of the 6572 `info display' display; or it could be a range of display numbers, 6573 as in `2-4'. 6574 6575`display' 6576 Display the current values of the expressions on the list, just as 6577 is done when your program stops. 6578 6579`info display' 6580 Print the list of expressions previously set up to display 6581 automatically, each one with its item number, but without showing 6582 the values. This includes disabled expressions, which are marked 6583 as such. It also includes expressions which would not be 6584 displayed right now because they refer to automatic variables not 6585 currently available. 6586 6587 If a display expression refers to local variables, then it does not 6588make sense outside the lexical context for which it was set up. Such an 6589expression is disabled when execution enters a context where one of its 6590variables is not defined. For example, if you give the command 6591`display last_char' while inside a function with an argument 6592`last_char', GDB displays this argument while your program continues to 6593stop inside that function. When it stops elsewhere--where there is no 6594variable `last_char'--the display is disabled automatically. The next 6595time your program stops where `last_char' is meaningful, you can enable 6596the display expression once again. 6597 6598 6599File: gdb.info, Node: Print Settings, Next: Pretty Printing, Prev: Auto Display, Up: Data 6600 660110.8 Print Settings 6602=================== 6603 6604GDB provides the following ways to control how arrays, structures, and 6605symbols are printed. 6606 6607These settings are useful for debugging programs in any language: 6608 6609`set print address' 6610`set print address on' 6611 GDB prints memory addresses showing the location of stack traces, 6612 structure values, pointer values, breakpoints, and so forth, even 6613 when it also displays the contents of those addresses. The default 6614 is `on'. For example, this is what a stack frame display looks 6615 like with `set print address on': 6616 6617 (gdb) f 6618 #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") 6619 at input.c:530 6620 530 if (lquote != def_lquote) 6621 6622`set print address off' 6623 Do not print addresses when displaying their contents. For 6624 example, this is the same stack frame displayed with `set print 6625 address off': 6626 6627 (gdb) set print addr off 6628 (gdb) f 6629 #0 set_quotes (lq="<<", rq=">>") at input.c:530 6630 530 if (lquote != def_lquote) 6631 6632 You can use `set print address off' to eliminate all machine 6633 dependent displays from the GDB interface. For example, with 6634 `print address off', you should get the same text for backtraces on 6635 all machines--whether or not they involve pointer arguments. 6636 6637`show print address' 6638 Show whether or not addresses are to be printed. 6639 6640 When GDB prints a symbolic address, it normally prints the closest 6641earlier symbol plus an offset. If that symbol does not uniquely 6642identify the address (for example, it is a name whose scope is a single 6643source file), you may need to clarify. One way to do this is with 6644`info line', for example `info line *0x4537'. Alternately, you can set 6645GDB to print the source file and line number when it prints a symbolic 6646address: 6647 6648`set print symbol-filename on' 6649 Tell GDB to print the source file name and line number of a symbol 6650 in the symbolic form of an address. 6651 6652`set print symbol-filename off' 6653 Do not print source file name and line number of a symbol. This 6654 is the default. 6655 6656`show print symbol-filename' 6657 Show whether or not GDB will print the source file name and line 6658 number of a symbol in the symbolic form of an address. 6659 6660 Another situation where it is helpful to show symbol filenames and 6661line numbers is when disassembling code; GDB shows you the line number 6662and source file that corresponds to each instruction. 6663 6664 Also, you may wish to see the symbolic form only if the address being 6665printed is reasonably close to the closest earlier symbol: 6666 6667`set print max-symbolic-offset MAX-OFFSET' 6668 Tell GDB to only display the symbolic form of an address if the 6669 offset between the closest earlier symbol and the address is less 6670 than MAX-OFFSET. The default is 0, which tells GDB to always 6671 print the symbolic form of an address if any symbol precedes it. 6672 6673`show print max-symbolic-offset' 6674 Ask how large the maximum offset is that GDB prints in a symbolic 6675 address. 6676 6677 If you have a pointer and you are not sure where it points, try `set 6678print symbol-filename on'. Then you can determine the name and source 6679file location of the variable where it points, using `p/a POINTER'. 6680This interprets the address in symbolic form. For example, here GDB 6681shows that a variable `ptt' points at another variable `t', defined in 6682`hi2.c': 6683 6684 (gdb) set print symbol-filename on 6685 (gdb) p/a ptt 6686 $4 = 0xe008 <t in hi2.c> 6687 6688 _Warning:_ For pointers that point to a local variable, `p/a' does 6689 not show the symbol name and filename of the referent, even with 6690 the appropriate `set print' options turned on. 6691 6692 Other settings control how different kinds of objects are printed: 6693 6694`set print array' 6695`set print array on' 6696 Pretty print arrays. This format is more convenient to read, but 6697 uses more space. The default is off. 6698 6699`set print array off' 6700 Return to compressed format for arrays. 6701 6702`show print array' 6703 Show whether compressed or pretty format is selected for displaying 6704 arrays. 6705 6706`set print array-indexes' 6707`set print array-indexes on' 6708 Print the index of each element when displaying arrays. May be 6709 more convenient to locate a given element in the array or quickly 6710 find the index of a given element in that printed array. The 6711 default is off. 6712 6713`set print array-indexes off' 6714 Stop printing element indexes when displaying arrays. 6715 6716`show print array-indexes' 6717 Show whether the index of each element is printed when displaying 6718 arrays. 6719 6720`set print elements NUMBER-OF-ELEMENTS' 6721 Set a limit on how many elements of an array GDB will print. If 6722 GDB is printing a large array, it stops printing after it has 6723 printed the number of elements set by the `set print elements' 6724 command. This limit also applies to the display of strings. When 6725 GDB starts, this limit is set to 200. Setting NUMBER-OF-ELEMENTS 6726 to zero means that the printing is unlimited. 6727 6728`show print elements' 6729 Display the number of elements of a large array that GDB will 6730 print. If the number is 0, then the printing is unlimited. 6731 6732`set print frame-arguments VALUE' 6733 This command allows to control how the values of arguments are 6734 printed when the debugger prints a frame (*note Frames::). The 6735 possible values are: 6736 6737 `all' 6738 The values of all arguments are printed. 6739 6740 `scalars' 6741 Print the value of an argument only if it is a scalar. The 6742 value of more complex arguments such as arrays, structures, 6743 unions, etc, is replaced by `...'. This is the default. 6744 Here is an example where only scalar arguments are shown: 6745 6746 #1 0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green) 6747 at frame-args.c:23 6748 6749 `none' 6750 None of the argument values are printed. Instead, the value 6751 of each argument is replaced by `...'. In this case, the 6752 example above now becomes: 6753 6754 #1 0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...) 6755 at frame-args.c:23 6756 6757 By default, only scalar arguments are printed. This command can 6758 be used to configure the debugger to print the value of all 6759 arguments, regardless of their type. However, it is often 6760 advantageous to not print the value of more complex parameters. 6761 For instance, it reduces the amount of information printed in each 6762 frame, making the backtrace more readable. Also, it improves 6763 performance when displaying Ada frames, because the computation of 6764 large arguments can sometimes be CPU-intensive, especially in 6765 large applications. Setting `print frame-arguments' to `scalars' 6766 (the default) or `none' avoids this computation, thus speeding up 6767 the display of each Ada frame. 6768 6769`show print frame-arguments' 6770 Show how the value of arguments should be displayed when printing 6771 a frame. 6772 6773`set print repeats' 6774 Set the threshold for suppressing display of repeated array 6775 elements. When the number of consecutive identical elements of an 6776 array exceeds the threshold, GDB prints the string `"<repeats N 6777 times>"', where N is the number of identical repetitions, instead 6778 of displaying the identical elements themselves. Setting the 6779 threshold to zero will cause all elements to be individually 6780 printed. The default threshold is 10. 6781 6782`show print repeats' 6783 Display the current threshold for printing repeated identical 6784 elements. 6785 6786`set print null-stop' 6787 Cause GDB to stop printing the characters of an array when the 6788 first NULL is encountered. This is useful when large arrays 6789 actually contain only short strings. The default is off. 6790 6791`show print null-stop' 6792 Show whether GDB stops printing an array on the first NULL 6793 character. 6794 6795`set print pretty on' 6796 Cause GDB to print structures in an indented format with one member 6797 per line, like this: 6798 6799 $1 = { 6800 next = 0x0, 6801 flags = { 6802 sweet = 1, 6803 sour = 1 6804 }, 6805 meat = 0x54 "Pork" 6806 } 6807 6808`set print pretty off' 6809 Cause GDB to print structures in a compact format, like this: 6810 6811 $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \ 6812 meat = 0x54 "Pork"} 6813 6814 This is the default format. 6815 6816`show print pretty' 6817 Show which format GDB is using to print structures. 6818 6819`set print sevenbit-strings on' 6820 Print using only seven-bit characters; if this option is set, GDB 6821 displays any eight-bit characters (in strings or character values) 6822 using the notation `\'NNN. This setting is best if you are 6823 working in English (ASCII) and you use the high-order bit of 6824 characters as a marker or "meta" bit. 6825 6826`set print sevenbit-strings off' 6827 Print full eight-bit characters. This allows the use of more 6828 international character sets, and is the default. 6829 6830`show print sevenbit-strings' 6831 Show whether or not GDB is printing only seven-bit characters. 6832 6833`set print union on' 6834 Tell GDB to print unions which are contained in structures and 6835 other unions. This is the default setting. 6836 6837`set print union off' 6838 Tell GDB not to print unions which are contained in structures and 6839 other unions. GDB will print `"{...}"' instead. 6840 6841`show print union' 6842 Ask GDB whether or not it will print unions which are contained in 6843 structures and other unions. 6844 6845 For example, given the declarations 6846 6847 typedef enum {Tree, Bug} Species; 6848 typedef enum {Big_tree, Acorn, Seedling} Tree_forms; 6849 typedef enum {Caterpillar, Cocoon, Butterfly} 6850 Bug_forms; 6851 6852 struct thing { 6853 Species it; 6854 union { 6855 Tree_forms tree; 6856 Bug_forms bug; 6857 } form; 6858 }; 6859 6860 struct thing foo = {Tree, {Acorn}}; 6861 6862 with `set print union on' in effect `p foo' would print 6863 6864 $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}} 6865 6866 and with `set print union off' in effect it would print 6867 6868 $1 = {it = Tree, form = {...}} 6869 6870 `set print union' affects programs written in C-like languages and 6871 in Pascal. 6872 6873These settings are of interest when debugging C++ programs: 6874 6875`set print demangle' 6876`set print demangle on' 6877 Print C++ names in their source form rather than in the encoded 6878 ("mangled") form passed to the assembler and linker for type-safe 6879 linkage. The default is on. 6880 6881`show print demangle' 6882 Show whether C++ names are printed in mangled or demangled form. 6883 6884`set print asm-demangle' 6885`set print asm-demangle on' 6886 Print C++ names in their source form rather than their mangled 6887 form, even in assembler code printouts such as instruction 6888 disassemblies. The default is off. 6889 6890`show print asm-demangle' 6891 Show whether C++ names in assembly listings are printed in mangled 6892 or demangled form. 6893 6894`set demangle-style STYLE' 6895 Choose among several encoding schemes used by different compilers 6896 to represent C++ names. The choices for STYLE are currently: 6897 6898 `auto' 6899 Allow GDB to choose a decoding style by inspecting your 6900 program. 6901 6902 `gnu' 6903 Decode based on the GNU C++ compiler (`g++') encoding 6904 algorithm. This is the default. 6905 6906 `hp' 6907 Decode based on the HP ANSI C++ (`aCC') encoding algorithm. 6908 6909 `lucid' 6910 Decode based on the Lucid C++ compiler (`lcc') encoding 6911 algorithm. 6912 6913 `arm' 6914 Decode using the algorithm in the `C++ Annotated Reference 6915 Manual'. *Warning:* this setting alone is not sufficient to 6916 allow debugging `cfront'-generated executables. GDB would 6917 require further enhancement to permit that. 6918 6919 If you omit STYLE, you will see a list of possible formats. 6920 6921`show demangle-style' 6922 Display the encoding style currently in use for decoding C++ 6923 symbols. 6924 6925`set print object' 6926`set print object on' 6927 When displaying a pointer to an object, identify the _actual_ 6928 (derived) type of the object rather than the _declared_ type, using 6929 the virtual function table. 6930 6931`set print object off' 6932 Display only the declared type of objects, without reference to the 6933 virtual function table. This is the default setting. 6934 6935`show print object' 6936 Show whether actual, or declared, object types are displayed. 6937 6938`set print static-members' 6939`set print static-members on' 6940 Print static members when displaying a C++ object. The default is 6941 on. 6942 6943`set print static-members off' 6944 Do not print static members when displaying a C++ object. 6945 6946`show print static-members' 6947 Show whether C++ static members are printed or not. 6948 6949`set print pascal_static-members' 6950`set print pascal_static-members on' 6951 Print static members when displaying a Pascal object. The default 6952 is on. 6953 6954`set print pascal_static-members off' 6955 Do not print static members when displaying a Pascal object. 6956 6957`show print pascal_static-members' 6958 Show whether Pascal static members are printed or not. 6959 6960`set print vtbl' 6961`set print vtbl on' 6962 Pretty print C++ virtual function tables. The default is off. 6963 (The `vtbl' commands do not work on programs compiled with the HP 6964 ANSI C++ compiler (`aCC').) 6965 6966`set print vtbl off' 6967 Do not pretty print C++ virtual function tables. 6968 6969`show print vtbl' 6970 Show whether C++ virtual function tables are pretty printed, or 6971 not. 6972 6973 6974File: gdb.info, Node: Pretty Printing, Next: Value History, Prev: Print Settings, Up: Data 6975 697610.9 Pretty Printing 6977==================== 6978 6979GDB provides a mechanism to allow pretty-printing of values using 6980Python code. It greatly simplifies the display of complex objects. 6981This mechanism works for both MI and the CLI. 6982 6983* Menu: 6984 6985* Pretty-Printer Introduction:: Introduction to pretty-printers 6986* Pretty-Printer Example:: An example pretty-printer 6987* Pretty-Printer Commands:: Pretty-printer commands 6988 6989 6990File: gdb.info, Node: Pretty-Printer Introduction, Next: Pretty-Printer Example, Up: Pretty Printing 6991 699210.9.1 Pretty-Printer Introduction 6993---------------------------------- 6994 6995When GDB prints a value, it first sees if there is a pretty-printer 6996registered for the value. If there is then GDB invokes the 6997pretty-printer to print the value. Otherwise the value is printed 6998normally. 6999 7000 Pretty-printers are normally named. This makes them easy to manage. 7001The `info pretty-printer' command will list all the installed 7002pretty-printers with their names. If a pretty-printer can handle 7003multiple data types, then its "subprinters" are the printers for the 7004individual data types. Each such subprinter has its own name. The 7005format of the name is PRINTER-NAME;SUBPRINTER-NAME. 7006 7007 Pretty-printers are installed by "registering" them with GDB. 7008Typically they are automatically loaded and registered when the 7009corresponding debug information is loaded, thus making them available 7010without having to do anything special. 7011 7012 There are three places where a pretty-printer can be registered. 7013 7014 * Pretty-printers registered globally are available when debugging 7015 all inferiors. 7016 7017 * Pretty-printers registered with a program space are available only 7018 when debugging that program. *Note Progspaces In Python::, for 7019 more details on program spaces in Python. 7020 7021 * Pretty-printers registered with an objfile are loaded and unloaded 7022 with the corresponding objfile (e.g., shared library). *Note 7023 Objfiles In Python::, for more details on objfiles in Python. 7024 7025 *Note Selecting Pretty-Printers::, for further information on how 7026pretty-printers are selected, 7027 7028 *Note Writing a Pretty-Printer::, for implementing pretty printers 7029for new types. 7030 7031 7032File: gdb.info, Node: Pretty-Printer Example, Next: Pretty-Printer Commands, Prev: Pretty-Printer Introduction, Up: Pretty Printing 7033 703410.9.2 Pretty-Printer Example 7035----------------------------- 7036 7037Here is how a C++ `std::string' looks without a pretty-printer: 7038 7039 (gdb) print s 7040 $1 = { 7041 static npos = 4294967295, 7042 _M_dataplus = { 7043 <std::allocator<char>> = { 7044 <__gnu_cxx::new_allocator<char>> = { 7045 <No data fields>}, <No data fields> 7046 }, 7047 members of std::basic_string<char, std::char_traits<char>, 7048 std::allocator<char> >::_Alloc_hider: 7049 _M_p = 0x804a014 "abcd" 7050 } 7051 } 7052 7053 With a pretty-printer for `std::string' only the contents are 7054printed: 7055 7056 (gdb) print s 7057 $2 = "abcd" 7058 7059 7060File: gdb.info, Node: Pretty-Printer Commands, Prev: Pretty-Printer Example, Up: Pretty Printing 7061 706210.9.3 Pretty-Printer Commands 7063------------------------------ 7064 7065`info pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' 7066 Print the list of installed pretty-printers. This includes 7067 disabled pretty-printers, which are marked as such. 7068 7069 OBJECT-REGEXP is a regular expression matching the objects whose 7070 pretty-printers to list. Objects can be `global', the program 7071 space's file (*note Progspaces In Python::), and the object files 7072 within that program space (*note Objfiles In Python::). *Note 7073 Selecting Pretty-Printers::, for details on how GDB looks up a 7074 printer from these three objects. 7075 7076 NAME-REGEXP is a regular expression matching the name of the 7077 printers to list. 7078 7079`disable pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' 7080 Disable pretty-printers matching OBJECT-REGEXP and NAME-REGEXP. A 7081 disabled pretty-printer is not forgotten, it may be enabled again 7082 later. 7083 7084`enable pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' 7085 Enable pretty-printers matching OBJECT-REGEXP and NAME-REGEXP. 7086 7087 Example: 7088 7089 Suppose we have three pretty-printers installed: one from library1.so 7090named `foo' that prints objects of type `foo', and another from 7091library2.so named `bar' that prints two types of objects, `bar1' and 7092`bar2'. 7093 7094 (gdb) info pretty-printer 7095 library1.so: 7096 foo 7097 library2.so: 7098 bar 7099 bar1 7100 bar2 7101 (gdb) info pretty-printer library2 7102 library2.so: 7103 bar 7104 bar1 7105 bar2 7106 (gdb) disable pretty-printer library1 7107 1 printer disabled 7108 2 of 3 printers enabled 7109 (gdb) info pretty-printer 7110 library1.so: 7111 foo [disabled] 7112 library2.so: 7113 bar 7114 bar1 7115 bar2 7116 (gdb) disable pretty-printer library2 bar:bar1 7117 1 printer disabled 7118 1 of 3 printers enabled 7119 (gdb) info pretty-printer library2 7120 library1.so: 7121 foo [disabled] 7122 library2.so: 7123 bar 7124 bar1 [disabled] 7125 bar2 7126 (gdb) disable pretty-printer library2 bar 7127 1 printer disabled 7128 0 of 3 printers enabled 7129 (gdb) info pretty-printer library2 7130 library1.so: 7131 foo [disabled] 7132 library2.so: 7133 bar [disabled] 7134 bar1 [disabled] 7135 bar2 7136 7137 Note that for `bar' the entire printer can be disabled, as can each 7138individual subprinter. 7139 7140 7141File: gdb.info, Node: Value History, Next: Convenience Vars, Prev: Pretty Printing, Up: Data 7142 714310.10 Value History 7144=================== 7145 7146Values printed by the `print' command are saved in the GDB "value 7147history". This allows you to refer to them in other expressions. 7148Values are kept until the symbol table is re-read or discarded (for 7149example with the `file' or `symbol-file' commands). When the symbol 7150table changes, the value history is discarded, since the values may 7151contain pointers back to the types defined in the symbol table. 7152 7153 The values printed are given "history numbers" by which you can 7154refer to them. These are successive integers starting with one. 7155`print' shows you the history number assigned to a value by printing 7156`$NUM = ' before the value; here NUM is the history number. 7157 7158 To refer to any previous value, use `$' followed by the value's 7159history number. The way `print' labels its output is designed to 7160remind you of this. Just `$' refers to the most recent value in the 7161history, and `$$' refers to the value before that. `$$N' refers to the 7162Nth value from the end; `$$2' is the value just prior to `$$', `$$1' is 7163equivalent to `$$', and `$$0' is equivalent to `$'. 7164 7165 For example, suppose you have just printed a pointer to a structure 7166and want to see the contents of the structure. It suffices to type 7167 7168 p *$ 7169 7170 If you have a chain of structures where the component `next' points 7171to the next one, you can print the contents of the next one with this: 7172 7173 p *$.next 7174 7175You can print successive links in the chain by repeating this 7176command--which you can do by just typing <RET>. 7177 7178 Note that the history records values, not expressions. If the value 7179of `x' is 4 and you type these commands: 7180 7181 print x 7182 set x=5 7183 7184then the value recorded in the value history by the `print' command 7185remains 4 even though the value of `x' has changed. 7186 7187`show values' 7188 Print the last ten values in the value history, with their item 7189 numbers. This is like `p $$9' repeated ten times, except that 7190 `show values' does not change the history. 7191 7192`show values N' 7193 Print ten history values centered on history item number N. 7194 7195`show values +' 7196 Print ten history values just after the values last printed. If 7197 no more values are available, `show values +' produces no display. 7198 7199 Pressing <RET> to repeat `show values N' has exactly the same effect 7200as `show values +'. 7201 7202