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