1 This is gdb.info, produced by makeinfo version 4.8 from 2 ../../../../toolchain/android-toolchain/gdb-6.6/gdb/doc/gdb.texinfo. 3 4 INFO-DIR-SECTION Software development 5 START-INFO-DIR-ENTRY 6 * Gdb: (gdb). The GNU debugger. 7 END-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 12 Source-Level Debugger' for GDB Version 6.6. 13 14 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 15 1998, 16 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 17 Free Software Foundation, Inc. 18 19 Permission is granted to copy, distribute and/or modify this document 20 under the terms of the GNU Free Documentation License, Version 1.1 or 21 any later version published by the Free Software Foundation; with the 22 Invariant Sections being "Free Software" and "Free Software Needs Free 23 Documentation", with the Front-Cover Texts being "A GNU Manual," and 24 with the Back-Cover Texts as in (a) below. 25 26 (a) The Free Software Foundation's Back-Cover Text is: "You have 27 freedom to copy and modify this GNU Manual, like GNU software. Copies 28 published by the Free Software Foundation raise funds for GNU 29 development." 30 31 32 File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir) 33 34 Debugging with GDB 35 ****************** 36 37 This file describes GDB, the GNU symbolic debugger. 38 39 This is the Ninth Edition, for GDB Version 6.6. 40 41 Copyright (C) 1988-2006 Free Software Foundation, Inc. 42 43 * Menu: 44 45 * Summary:: Summary of GDB 46 * Sample Session:: A sample GDB session 47 48 * Invocation:: Getting in and out of GDB 49 * Commands:: GDB commands 50 * Running:: Running programs under GDB 51 * Stopping:: Stopping and continuing 52 * Stack:: Examining the stack 53 * Source:: Examining source files 54 * Data:: Examining data 55 * Macros:: Preprocessor Macros 56 * Tracepoints:: Debugging remote targets non-intrusively 57 * Overlays:: Debugging programs that use overlays 58 59 * Languages:: Using GDB with different languages 60 61 * Symbols:: Examining the symbol table 62 * Altering:: Altering execution 63 * GDB Files:: GDB files 64 * Targets:: Specifying a debugging target 65 * Remote Debugging:: Debugging remote programs 66 * Configurations:: Configuration-specific information 67 * Controlling GDB:: Controlling GDB 68 * Sequences:: Canned sequences of commands 69 * TUI:: GDB Text User Interface 70 * Interpreters:: Command Interpreters 71 * Emacs:: Using GDB under GNU Emacs 72 * Annotations:: GDB's annotation interface. 73 * GDB/MI:: GDB's Machine Interface. 74 75 * GDB Bugs:: Reporting bugs in GDB 76 * Formatting Documentation:: How to format and print GDB documentation 77 78 * Command Line Editing:: Command Line Editing 79 * Using History Interactively:: Using History Interactively 80 * Installing GDB:: Installing GDB 81 * Maintenance Commands:: Maintenance Commands 82 * Remote Protocol:: GDB Remote Serial Protocol 83 * Agent Expressions:: The GDB Agent Expression Mechanism 84 * Copying:: GNU General Public License says 85 how you can copy and share GDB 86 * GNU Free Documentation License:: The license for this documentation 87 * Index:: Index 88 89 90 File: gdb.info, Node: Summary, Next: Sample Session, Prev: Top, Up: Top 91 92 Summary of GDB 93 ************** 94 95 The purpose of a debugger such as GDB is to allow you to see what is 96 going on "inside" another program while it executes--or what another 97 program was doing at the moment it crashed. 98 99 GDB can do four main kinds of things (plus other things in support of 100 these) to help you catch bugs in the act: 101 102 * Start your program, specifying anything that might affect its 103 behavior. 104 105 * Make your program stop on specified conditions. 106 107 * Examine what has happened, when your program has stopped. 108 109 * Change things in your program, so you can experiment with 110 correcting the effects of one bug and go on to learn about another. 111 112 You can use GDB to debug programs written in C and C++. For more 113 information, see *Note Supported languages: Supported languages. For 114 more information, see *Note C and C++: C. 115 116 Support for Modula-2 is partial. For information on Modula-2, see 117 *Note Modula-2: Modula-2. 118 119 Debugging Pascal programs which use sets, subranges, file variables, 120 or nested functions does not currently work. GDB does not support 121 entering expressions, printing values, or similar features using Pascal 122 syntax. 123 124 GDB can be used to debug programs written in Fortran, although it 125 may be necessary to refer to some variables with a trailing underscore. 126 127 GDB can be used to debug programs written in Objective-C, using 128 either the Apple/NeXT or the GNU Objective-C runtime. 129 130 * Menu: 131 132 * Free Software:: Freely redistributable software 133 * Contributors:: Contributors to GDB 134 135 136 File: gdb.info, Node: Free Software, Next: Contributors, Up: Summary 137 138 Free software 139 ============= 140 141 GDB is "free software", protected by the GNU General Public License 142 (GPL). The GPL gives you the freedom to copy or adapt a licensed 143 program--but every person getting a copy also gets with it the freedom 144 to modify that copy (which means that they must get access to the 145 source code), and the freedom to distribute further copies. Typical 146 software companies use copyrights to limit your freedoms; the Free 147 Software Foundation uses the GPL to preserve these freedoms. 148 149 Fundamentally, the General Public License is a license which says 150 that you have these freedoms and that you cannot take these freedoms 151 away from anyone else. 152 153 Free Software Needs Free Documentation 154 ====================================== 155 156 The biggest deficiency in the free software community today is not in 157 the software--it is the lack of good free documentation that we can 158 include with the free software. Many of our most important programs do 159 not come with free reference manuals and free introductory texts. 160 Documentation is an essential part of any software package; when an 161 important free software package does not come with a free manual and a 162 free tutorial, that is a major gap. We have many such gaps today. 163 164 Consider Perl, for instance. The tutorial manuals that people 165 normally use are non-free. How did this come about? Because the 166 authors of those manuals published them with restrictive terms--no 167 copying, no modification, source files not available--which exclude 168 them from the free software world. 169 170 That wasn't the first time this sort of thing happened, and it was 171 far from the last. Many times we have heard a GNU user eagerly 172 describe a manual that he is writing, his intended contribution to the 173 community, only to learn that he had ruined everything by signing a 174 publication contract to make it non-free. 175 176 Free documentation, like free software, is a matter of freedom, not 177 price. The problem with the non-free manual is not that publishers 178 charge a price for printed copies--that in itself is fine. (The Free 179 Software Foundation sells printed copies of manuals, too.) The problem 180 is the restrictions on the use of the manual. Free manuals are 181 available in source code form, and give you permission to copy and 182 modify. Non-free manuals do not allow this. 183 184 The criteria of freedom for a free manual are roughly the same as for 185 free software. Redistribution (including the normal kinds of 186 commercial redistribution) must be permitted, so that the manual can 187 accompany every copy of the program, both on-line and on paper. 188 189 Permission for modification of the technical content is crucial too. 190 When people modify the software, adding or changing features, if they 191 are conscientious they will change the manual too--so they can provide 192 accurate and clear documentation for the modified program. A manual 193 that leaves you no choice but to write a new manual to document a 194 changed version of the program is not really available to our community. 195 196 Some kinds of limits on the way modification is handled are 197 acceptable. For example, requirements to preserve the original 198 author's copyright notice, the distribution terms, or the list of 199 authors, are ok. It is also no problem to require modified versions to 200 include notice that they were modified. Even entire sections that may 201 not be deleted or changed are acceptable, as long as they deal with 202 nontechnical topics (like this one). These kinds of restrictions are 203 acceptable because they don't obstruct the community's normal use of 204 the manual. 205 206 However, it must be possible to modify all the _technical_ content 207 of the manual, and then distribute the result in all the usual media, 208 through all the usual channels. Otherwise, the restrictions obstruct 209 the use of the manual, it is not free, and we need another manual to 210 replace it. 211 212 Please spread the word about this issue. Our community continues to 213 lose manuals to proprietary publishing. If we spread the word that 214 free software needs free reference manuals and free tutorials, perhaps 215 the next person who wants to contribute by writing documentation will 216 realize, before it is too late, that only free manuals contribute to 217 the free software community. 218 219 If you are writing documentation, please insist on publishing it 220 under the GNU Free Documentation License or another free documentation 221 license. Remember that this decision requires your approval--you don't 222 have to let the publisher decide. Some commercial publishers will use 223 a free license if you insist, but they will not propose the option; it 224 is up to you to raise the issue and say firmly that this is what you 225 want. If the publisher you are dealing with refuses, please try other 226 publishers. If you're not sure whether a proposed license is free, 227 write to <licensing (a] gnu.org>. 228 229 You can encourage commercial publishers to sell more free, copylefted 230 manuals and tutorials by buying them, and particularly by buying copies 231 from the publishers that paid for their writing or for major 232 improvements. Meanwhile, try to avoid buying non-free documentation at 233 all. Check the distribution terms of a manual before you buy it, and 234 insist that whoever seeks your business must respect your freedom. 235 Check the history of the book, and try to reward the publishers that 236 have paid or pay the authors to work on it. 237 238 The Free Software Foundation maintains a list of free documentation 239 published by other publishers, at 240 `http://www.fsf.org/doc/other-free-books.html'. 241 242 243 File: gdb.info, Node: Contributors, Prev: Free Software, Up: Summary 244 245 Contributors to GDB 246 =================== 247 248 Richard Stallman was the original author of GDB, and of many other GNU 249 programs. Many others have contributed to its development. This 250 section attempts to credit major contributors. One of the virtues of 251 free software is that everyone is free to contribute to it; with 252 regret, we cannot actually acknowledge everyone here. The file 253 `ChangeLog' in the GDB distribution approximates a blow-by-blow account. 254 255 Changes much prior to version 2.0 are lost in the mists of time. 256 257 _Plea:_ Additions to this section are particularly welcome. If you 258 or your friends (or enemies, to be evenhanded) have been unfairly 259 omitted from this list, we would like to add your names! 260 261 So that they may not regard their many labors as thankless, we 262 particularly thank those who shepherded GDB through major releases: 263 Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim 264 Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs 265 (release 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, 266 and 4.9); Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, 267 and 4.4); John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim 268 Kingdon (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, 269 3.1, and 3.0). 270 271 Richard Stallman, assisted at various times by Peter TerMaat, Chris 272 Hanson, and Richard Mlynarik, handled releases through 2.8. 273 274 Michael Tiemann is the author of most of the GNU C++ support in GDB, 275 with significant additional contributions from Per Bothner and Daniel 276 Berlin. James Clark wrote the GNU C++ demangler. Early work on C++ 277 was by Peter TerMaat (who also did much general update work leading to 278 release 3.0). 279 280 GDB uses the BFD subroutine library to examine multiple object-file 281 formats; BFD was a joint project of David V. Henkel-Wallace, Rich 282 Pixley, Steve Chamberlain, and John Gilmore. 283 284 David Johnson wrote the original COFF support; Pace Willison did the 285 original support for encapsulated COFF. 286 287 Brent Benson of Harris Computer Systems contributed DWARF 2 support. 288 289 Adam de Boor and Bradley Davis contributed the ISI Optimum V support. 290 Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS 291 support. Jean-Daniel Fekete contributed Sun 386i support. Chris 292 Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki 293 Hasei contributed Sony/News OS 3 support. David Johnson contributed 294 Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support. 295 Jeff Law contributed HP PA and SOM support. Keith Packard contributed 296 NS32K support. Doug Rabson contributed Acorn Risc Machine support. 297 Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith 298 contributed Convex support (and Fortran debugging). Jonathan Stone 299 contributed Pyramid support. Michael Tiemann contributed SPARC support. 300 Tim Tucker contributed support for the Gould NP1 and Gould Powernode. 301 Pace Willison contributed Intel 386 support. Jay Vosburgh contributed 302 Symmetry support. Marko Mlinar contributed OpenRISC 1000 support. 303 304 Andreas Schwab contributed M68K GNU/Linux support. 305 306 Rich Schaefer and Peter Schauer helped with support of SunOS shared 307 libraries. 308 309 Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about 310 several machine instruction sets. 311 312 Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped 313 develop remote debugging. Intel Corporation, Wind River Systems, AMD, 314 and ARM contributed remote debugging modules for the i960, VxWorks, 315 A29K UDI, and RDI targets, respectively. 316 317 Brian Fox is the author of the readline libraries providing 318 command-line editing and command history. 319 320 Andrew Beers of SUNY Buffalo wrote the language-switching code, the 321 Modula-2 support, and contributed the Languages chapter of this manual. 322 323 Fred Fish wrote most of the support for Unix System Vr4. He also 324 enhanced the command-completion support to cover C++ overloaded symbols. 325 326 Hitachi America (now Renesas America), Ltd. sponsored the support for 327 H8/300, H8/500, and Super-H processors. 328 329 NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx 330 processors. 331 332 Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and 333 M32R/D processors. 334 335 Toshiba sponsored the support for the TX39 Mips processor. 336 337 Matsushita sponsored the support for the MN10200 and MN10300 338 processors. 339 340 Fujitsu sponsored the support for SPARClite and FR30 processors. 341 342 Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware 343 watchpoints. 344 345 Michael Snyder added support for tracepoints. 346 347 Stu Grossman wrote gdbserver. 348 349 Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly 350 innumerable bug fixes and cleanups throughout GDB. 351 352 The following people at the Hewlett-Packard Company contributed 353 support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 354 (narrow mode), HP's implementation of kernel threads, HP's aC++ 355 compiler, and the Text User Interface (nee Terminal User Interface): 356 Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, 357 Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase 358 provided HP-specific information in this manual. 359 360 DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert 361 Hoehne made significant contributions to the DJGPP port. 362 363 Cygnus Solutions has sponsored GDB maintenance and much of its 364 development since 1991. Cygnus engineers who have worked on GDB 365 fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin 366 Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim 367 Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, 368 Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek 369 Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In 370 addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, 371 JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug 372 Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff 373 Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, 374 Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin 375 Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela 376 Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David 377 Zuhn have made contributions both large and small. 378 379 Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for 380 Cygnus Solutions, implemented the original GDB/MI interface. 381 382 Jim Blandy added support for preprocessor macros, while working for 383 Red Hat. 384 385 Andrew Cagney designed GDB's architecture vector. Many people 386 including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek, 387 Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto, 388 Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna 389 Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration 390 of old architectures to this new framework. 391 392 Andrew Cagney completely re-designed and re-implemented GDB's 393 unwinder framework, this consisting of a fresh new design featuring 394 frame IDs, independent frame sniffers, and the sentinel frame. Mark 395 Kettenis implemented the DWARF 2 unwinder, Jeff Johnston the libunwind 396 unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad 397 unwinders. The architecture specific changes, each involving a 398 complete rewrite of the architecture's frame code, were carried out by 399 Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane 400 Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel 401 Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei 402 Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich 403 Weigand. 404 405 Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from 406 Tensilica, Inc. contributed support for Xtensa processors. Others who 407 have worked on the Xtensa port of GDB in the past include Steve Tjiang, 408 John Newlin, and Scott Foehner. 409 410 411 File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top 412 413 1 A Sample GDB Session 414 ********************** 415 416 You can use this manual at your leisure to read all about GDB. 417 However, a handful of commands are enough to get started using the 418 debugger. This chapter illustrates those commands. 419 420 One of the preliminary versions of GNU `m4' (a generic macro 421 processor) exhibits the following bug: sometimes, when we change its 422 quote strings from the default, the commands used to capture one macro 423 definition within another stop working. In the following short `m4' 424 session, we define a macro `foo' which expands to `0000'; we then use 425 the `m4' built-in `defn' to define `bar' as the same thing. However, 426 when we change the open quote string to `<QUOTE>' and the close quote 427 string to `<UNQUOTE>', the same procedure fails to define a new synonym 428 `baz': 429 430 $ cd gnu/m4 431 $ ./m4 432 define(foo,0000) 433 434 foo 435 0000 436 define(bar,defn(`foo')) 437 438 bar 439 0000 440 changequote(<QUOTE>,<UNQUOTE>) 441 442 define(baz,defn(<QUOTE>foo<UNQUOTE>)) 443 baz 444 Ctrl-d 445 m4: End of input: 0: fatal error: EOF in string 446 447 Let us use GDB to try to see what is going on. 448 449 $ gdb m4 450 GDB is free software and you are welcome to distribute copies 451 of it under certain conditions; type "show copying" to see 452 the conditions. 453 There is absolutely no warranty for GDB; type "show warranty" 454 for details. 455 456 GDB 6.6, Copyright 1999 Free Software Foundation, Inc... 457 (gdb) 458 459 GDB reads only enough symbol data to know where to find the rest when 460 needed; as a result, the first prompt comes up very quickly. We now 461 tell GDB to use a narrower display width than usual, so that examples 462 fit in this manual. 463 464 (gdb) set width 70 465 466 We need to see how the `m4' built-in `changequote' works. Having 467 looked at the source, we know the relevant subroutine is 468 `m4_changequote', so we set a breakpoint there with the GDB `break' 469 command. 470 471 (gdb) break m4_changequote 472 Breakpoint 1 at 0x62f4: file builtin.c, line 879. 473 474 Using the `run' command, we start `m4' running under GDB control; as 475 long as control does not reach the `m4_changequote' subroutine, the 476 program runs as usual: 477 478 (gdb) run 479 Starting program: /work/Editorial/gdb/gnu/m4/m4 480 define(foo,0000) 481 482 foo 483 0000 484 485 To trigger the breakpoint, we call `changequote'. GDB suspends 486 execution of `m4', displaying information about the context where it 487 stops. 488 489 changequote(<QUOTE>,<UNQUOTE>) 490 491 Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) 492 at builtin.c:879 493 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) 494 495 Now we use the command `n' (`next') to advance execution to the next 496 line of the current function. 497 498 (gdb) n 499 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ 500 : nil, 501 502 `set_quotes' looks like a promising subroutine. We can go into it by 503 using the command `s' (`step') instead of `next'. `step' goes to the 504 next line to be executed in _any_ subroutine, so it steps into 505 `set_quotes'. 506 507 (gdb) s 508 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 509 at input.c:530 510 530 if (lquote != def_lquote) 511 512 The display that shows the subroutine where `m4' is now suspended (and 513 its arguments) is called a stack frame display. It shows a summary of 514 the stack. We can use the `backtrace' command (which can also be 515 spelled `bt'), to see where we are in the stack as a whole: the 516 `backtrace' command displays a stack frame for each active subroutine. 517 518 (gdb) bt 519 #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 520 at input.c:530 521 #1 0x6344 in m4_changequote (argc=3, argv=0x33c70) 522 at builtin.c:882 523 #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 524 #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) 525 at macro.c:71 526 #4 0x79dc in expand_input () at macro.c:40 527 #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 528 529 We step through a few more lines to see what happens. The first two 530 times, we can use `s'; the next two times we use `n' to avoid falling 531 into the `xstrdup' subroutine. 532 533 (gdb) s 534 0x3b5c 532 if (rquote != def_rquote) 535 (gdb) s 536 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ 537 def_lquote : xstrdup(lq); 538 (gdb) n 539 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 540 : xstrdup(rq); 541 (gdb) n 542 538 len_lquote = strlen(rquote); 543 544 The last line displayed looks a little odd; we can examine the variables 545 `lquote' and `rquote' to see if they are in fact the new left and right 546 quotes we specified. We use the command `p' (`print') to see their 547 values. 548 549 (gdb) p lquote 550 $1 = 0x35d40 "<QUOTE>" 551 (gdb) p rquote 552 $2 = 0x35d50 "<UNQUOTE>" 553 554 `lquote' and `rquote' are indeed the new left and right quotes. To 555 look at some context, we can display ten lines of source surrounding 556 the current line with the `l' (`list') command. 557 558 (gdb) l 559 533 xfree(rquote); 560 534 561 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ 562 : xstrdup (lq); 563 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 564 : xstrdup (rq); 565 537 566 538 len_lquote = strlen(rquote); 567 539 len_rquote = strlen(lquote); 568 540 } 569 541 570 542 void 571 572 Let us step past the two lines that set `len_lquote' and `len_rquote', 573 and then examine the values of those variables. 574 575 (gdb) n 576 539 len_rquote = strlen(lquote); 577 (gdb) n 578 540 } 579 (gdb) p len_lquote 580 $3 = 9 581 (gdb) p len_rquote 582 $4 = 7 583 584 That certainly looks wrong, assuming `len_lquote' and `len_rquote' are 585 meant to be the lengths of `lquote' and `rquote' respectively. We can 586 set them to better values using the `p' command, since it can print the 587 value of any expression--and that expression can include subroutine 588 calls and assignments. 589 590 (gdb) p len_lquote=strlen(lquote) 591 $5 = 7 592 (gdb) p len_rquote=strlen(rquote) 593 $6 = 9 594 595 Is that enough to fix the problem of using the new quotes with the `m4' 596 built-in `defn'? We can allow `m4' to continue executing with the `c' 597 (`continue') command, and then try the example that caused trouble 598 initially: 599 600 (gdb) c 601 Continuing. 602 603 define(baz,defn(<QUOTE>foo<UNQUOTE>)) 604 605 baz 606 0000 607 608 Success! The new quotes now work just as well as the default ones. The 609 problem seems to have been just the two typos defining the wrong 610 lengths. We allow `m4' exit by giving it an EOF as input: 611 612 Ctrl-d 613 Program exited normally. 614 615 The message `Program exited normally.' is from GDB; it indicates `m4' 616 has finished executing. We can end our GDB session with the GDB `quit' 617 command. 618 619 (gdb) quit 620 621 622 File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top 623 624 2 Getting In and Out of GDB 625 *************************** 626 627 This chapter discusses how to start GDB, and how to get out of it. The 628 essentials are: 629 * type `gdb' to start GDB. 630 631 * type `quit' or `Ctrl-d' to exit. 632 633 * Menu: 634 635 * Invoking GDB:: How to start GDB 636 * Quitting GDB:: How to quit GDB 637 * Shell Commands:: How to use shell commands inside GDB 638 * Logging output:: How to log GDB's output to a file 639 640 641 File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation 642 643 2.1 Invoking GDB 644 ================ 645 646 Invoke GDB by running the program `gdb'. Once started, GDB reads 647 commands from the terminal until you tell it to exit. 648 649 You can also run `gdb' with a variety of arguments and options, to 650 specify more of your debugging environment at the outset. 651 652 The command-line options described here are designed to cover a 653 variety of situations; in some environments, some of these options may 654 effectively be unavailable. 655 656 The most usual way to start GDB is with one argument, specifying an 657 executable program: 658 659 gdb PROGRAM 660 661 You can also start with both an executable program and a core file 662 specified: 663 664 gdb PROGRAM CORE 665 666 You can, instead, specify a process ID as a second argument, if you 667 want to debug a running process: 668 669 gdb PROGRAM 1234 670 671 would attach GDB to process `1234' (unless you also have a file named 672 `1234'; GDB does check for a core file first). 673 674 Taking advantage of the second command-line argument requires a 675 fairly complete operating system; when you use GDB as a remote debugger 676 attached to a bare board, there may not be any notion of "process", and 677 there is often no way to get a core dump. GDB will warn you if it is 678 unable to attach or to read core dumps. 679 680 You can optionally have `gdb' pass any arguments after the 681 executable file to the inferior using `--args'. This option stops 682 option processing. 683 gdb --args gcc -O2 -c foo.c 684 This will cause `gdb' to debug `gcc', and to set `gcc''s 685 command-line arguments (*note Arguments::) to `-O2 -c foo.c'. 686 687 You can run `gdb' without printing the front material, which 688 describes GDB's non-warranty, by specifying `-silent': 689 690 gdb -silent 691 692 You can further control how GDB starts up by using command-line 693 options. GDB itself can remind you of the options available. 694 695 Type 696 697 gdb -help 698 699 to display all available options and briefly describe their use (`gdb 700 -h' is a shorter equivalent). 701 702 All options and command line arguments you give are processed in 703 sequential order. The order makes a difference when the `-x' option is 704 used. 705 706 * Menu: 707 708 * File Options:: Choosing files 709 * Mode Options:: Choosing modes 710 * Startup:: What GDB does during startup 711 712 713 File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB 714 715 2.1.1 Choosing files 716 -------------------- 717 718 When GDB starts, it reads any arguments other than options as 719 specifying an executable file and core file (or process ID). This is 720 the same as if the arguments were specified by the `-se' and `-c' (or 721 `-p' options respectively. (GDB reads the first argument that does not 722 have an associated option flag as equivalent to the `-se' option 723 followed by that argument; and the second argument that does not have 724 an associated option flag, if any, as equivalent to the `-c'/`-p' 725 option followed by that argument.) If the second argument begins with 726 a decimal digit, GDB will first attempt to attach to it as a process, 727 and if that fails, attempt to open it as a corefile. If you have a 728 corefile whose name begins with a digit, you can prevent GDB from 729 treating it as a pid by prefixing it with `./', e.g. `./12345'. 730 731 If GDB has not been configured to included core file support, such 732 as for most embedded targets, then it will complain about a second 733 argument and ignore it. 734 735 Many options have both long and short forms; both are shown in the 736 following list. GDB also recognizes the long forms if you truncate 737 them, so long as enough of the option is present to be unambiguous. 738 (If you prefer, you can flag option arguments with `--' rather than 739 `-', though we illustrate the more usual convention.) 740 741 `-symbols FILE' 742 `-s FILE' 743 Read symbol table from file FILE. 744 745 `-exec FILE' 746 `-e FILE' 747 Use file FILE as the executable file to execute when appropriate, 748 and for examining pure data in conjunction with a core dump. 749 750 `-se FILE' 751 Read symbol table from file FILE and use it as the executable file. 752 753 `-core FILE' 754 `-c FILE' 755 Use file FILE as a core dump to examine. 756 757 `-c NUMBER' 758 759 `-pid NUMBER' 760 `-p NUMBER' 761 Connect to process ID NUMBER, as with the `attach' command. If 762 there is no such process, GDB will attempt to open a core file 763 named NUMBER. 764 765 `-command FILE' 766 `-x FILE' 767 Execute GDB commands from file FILE. *Note Command files: Command 768 Files. 769 770 `-eval-command COMMAND' 771 `-ex COMMAND' 772 Execute a single GDB command. 773 774 This option may be used multiple times to call multiple commands. 775 It may also be interleaved with `-command' as required. 776 777 gdb -ex 'target sim' -ex 'load' \ 778 -x setbreakpoints -ex 'run' a.out 779 780 `-directory DIRECTORY' 781 `-d DIRECTORY' 782 Add DIRECTORY to the path to search for source and script files. 783 784 `-r' 785 `-readnow' 786 Read each symbol file's entire symbol table immediately, rather 787 than the default, which is to read it incrementally as it is 788 needed. This makes startup slower, but makes future operations 789 faster. 790 791 792 793 File: gdb.info, Node: Mode Options, Next: Startup, Prev: File Options, Up: Invoking GDB 794 795 2.1.2 Choosing modes 796 -------------------- 797 798 You can run GDB in various alternative modes--for example, in batch 799 mode or quiet mode. 800 801 `-nx' 802 `-n' 803 Do not execute commands found in any initialization files. 804 Normally, GDB executes the commands in these files after all the 805 command options and arguments have been processed. *Note Command 806 files: Command Files. 807 808 `-quiet' 809 `-silent' 810 `-q' 811 "Quiet". Do not print the introductory and copyright messages. 812 These messages are also suppressed in batch mode. 813 814 `-batch' 815 Run in batch mode. Exit with status `0' after processing all the 816 command files specified with `-x' (and all commands from 817 initialization files, if not inhibited with `-n'). Exit with 818 nonzero status if an error occurs in executing the GDB commands in 819 the command files. 820 821 Batch mode may be useful for running GDB as a filter, for example 822 to download and run a program on another computer; in order to 823 make this more useful, the message 824 825 Program exited normally. 826 827 (which is ordinarily issued whenever a program running under GDB 828 control terminates) is not issued when running in batch mode. 829 830 `-batch-silent' 831 Run in batch mode exactly like `-batch', but totally silently. All 832 GDB output to `stdout' is prevented (`stderr' is unaffected). 833 This is much quieter than `-silent' and would be useless for an 834 interactive session. 835 836 This is particularly useful when using targets that give `Loading 837 section' messages, for example. 838 839 Note that targets that give their output via GDB, as opposed to 840 writing directly to `stdout', will also be made silent. 841 842 `-return-child-result' 843 The return code from GDB will be the return code from the child 844 process (the process being debugged), with the following 845 exceptions: 846 847 * GDB exits abnormally. E.g., due to an incorrect argument or 848 an internal error. In this case the exit code is the same as 849 it would have been without `-return-child-result'. 850 851 * The user quits with an explicit value. E.g., `quit 1'. 852 853 * The child process never runs, or is not allowed to terminate, 854 in which case the exit code will be -1. 855 856 This option is useful in conjunction with `-batch' or 857 `-batch-silent', when GDB is being used as a remote program loader 858 or simulator interface. 859 860 `-nowindows' 861 `-nw' 862 "No windows". If GDB comes with a graphical user interface (GUI) 863 built in, then this option tells GDB to only use the command-line 864 interface. If no GUI is available, this option has no effect. 865 866 `-windows' 867 `-w' 868 If GDB includes a GUI, then this option requires it to be used if 869 possible. 870 871 `-cd DIRECTORY' 872 Run GDB using DIRECTORY as its working directory, instead of the 873 current directory. 874 875 `-fullname' 876 `-f' 877 GNU Emacs sets this option when it runs GDB as a subprocess. It 878 tells GDB to output the full file name and line number in a 879 standard, recognizable fashion each time a stack frame is 880 displayed (which includes each time your program stops). This 881 recognizable format looks like two `\032' characters, followed by 882 the file name, line number and character position separated by 883 colons, and a newline. The Emacs-to-GDB interface program uses 884 the two `\032' characters as a signal to display the source code 885 for the frame. 886 887 `-epoch' 888 The Epoch Emacs-GDB interface sets this option when it runs GDB as 889 a subprocess. It tells GDB to modify its print routines so as to 890 allow Epoch to display values of expressions in a separate window. 891 892 `-annotate LEVEL' 893 This option sets the "annotation level" inside GDB. Its effect is 894 identical to using `set annotate LEVEL' (*note Annotations::). 895 The annotation LEVEL controls how much information GDB prints 896 together with its prompt, values of expressions, source lines, and 897 other types of output. Level 0 is the normal, level 1 is for use 898 when GDB is run as a subprocess of GNU Emacs, level 3 is the 899 maximum annotation suitable for programs that control GDB, and 900 level 2 has been deprecated. 901 902 The annotation mechanism has largely been superseded by GDB/MI 903 (*note GDB/MI::). 904 905 `--args' 906 Change interpretation of command line so that arguments following 907 the executable file are passed as command line arguments to the 908 inferior. This option stops option processing. 909 910 `-baud BPS' 911 `-b BPS' 912 Set the line speed (baud rate or bits per second) of any serial 913 interface used by GDB for remote debugging. 914 915 `-l TIMEOUT' 916 Set the timeout (in seconds) of any communication used by GDB for 917 remote debugging. 918 919 `-tty DEVICE' 920 `-t DEVICE' 921 Run using DEVICE for your program's standard input and output. 922 923 `-tui' 924 Activate the "Text User Interface" when starting. The Text User 925 Interface manages several text windows on the terminal, showing 926 source, assembly, registers and GDB command outputs (*note GDB 927 Text User Interface: TUI.). Alternatively, the Text User 928 Interface can be enabled by invoking the program `gdbtui'. Do not 929 use this option if you run GDB from Emacs (*note Using GDB under 930 GNU Emacs: Emacs.). 931 932 `-interpreter INTERP' 933 Use the interpreter INTERP for interface with the controlling 934 program or device. This option is meant to be set by programs 935 which communicate with GDB using it as a back end. *Note Command 936 Interpreters: Interpreters. 937 938 `--interpreter=mi' (or `--interpreter=mi2') causes GDB to use the 939 "GDB/MI interface" (*note The GDB/MI Interface: GDB/MI.) included 940 since GDB version 6.0. The previous GDB/MI interface, included in 941 GDB version 5.3 and selected with `--interpreter=mi1', is 942 deprecated. Earlier GDB/MI interfaces are no longer supported. 943 944 `-write' 945 Open the executable and core files for both reading and writing. 946 This is equivalent to the `set write on' command inside GDB (*note 947 Patching::). 948 949 `-statistics' 950 This option causes GDB to print statistics about time and memory 951 usage after it completes each command and returns to the prompt. 952 953 `-version' 954 This option causes GDB to print its version number and no-warranty 955 blurb, and exit. 956 957 958 959 File: gdb.info, Node: Startup, Prev: Mode Options, Up: Invoking GDB 960 961 2.1.3 What GDB does during startup 962 ---------------------------------- 963 964 Here's the description of what GDB does during session startup: 965 966 1. Sets up the command interpreter as specified by the command line 967 (*note interpreter: Mode Options.). 968 969 2. Reads the "init file" (if any) in your home directory(1) and 970 executes all the commands in that file. 971 972 3. Processes command line options and operands. 973 974 4. Reads and executes the commands from init file (if any) in the 975 current working directory. This is only done if the current 976 directory is different from your home directory. Thus, you can 977 have more than one init file, one generic in your home directory, 978 and another, specific to the program you are debugging, in the 979 directory where you invoke GDB. 980 981 5. Reads command files specified by the `-x' option. *Note Command 982 Files::, for more details about GDB command files. 983 984 6. Reads the command history recorded in the "history file". *Note 985 Command History::, for more details about the command history and 986 the files where GDB records it. 987 988 Init files use the same syntax as "command files" (*note Command 989 Files::) and are processed by GDB in the same way. The init file in 990 your home directory can set options (such as `set complaints') that 991 affect subsequent processing of command line options and operands. 992 Init files are not executed if you use the `-nx' option (*note Choosing 993 modes: Mode Options.). 994 995 The GDB init files are normally called `.gdbinit'. On some 996 configurations of GDB, the init file is known by a different name 997 (these are typically environments where a specialized form of GDB may 998 need to coexist with other forms, hence a different name for the 999 specialized version's init file). These are the environments with 1000 special init file names: 1001 1002 * The DJGPP port of GDB uses the name `gdb.ini', due to the 1003 limitations of file names imposed by DOS filesystems. The Windows 1004 ports of GDB use the standard name, but if they find a `gdb.ini' 1005 file, they warn you about that and suggest to rename the file to 1006 the standard name. 1007 1008 * VxWorks (Wind River Systems real-time OS): `.vxgdbinit' 1009 1010 * OS68K (Enea Data Systems real-time OS): `.os68gdbinit' 1011 1012 * ES-1800 (Ericsson Telecom AB M68000 emulator): `.esgdbinit' 1013 1014 * CISCO 68k: `.cisco-gdbinit' 1015 1016 ---------- Footnotes ---------- 1017 1018 (1) On DOS/Windows systems, the home directory is the one pointed to 1019 by the `HOME' environment variable. 1020 1021 1022 File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation 1023 1024 2.2 Quitting GDB 1025 ================ 1026 1027 `quit [EXPRESSION]' 1028 `q' 1029 To exit GDB, use the `quit' command (abbreviated `q'), or type an 1030 end-of-file character (usually `Ctrl-d'). If you do not supply 1031 EXPRESSION, GDB will terminate normally; otherwise it will 1032 terminate using the result of EXPRESSION as the error code. 1033 1034 An interrupt (often `Ctrl-c') does not exit from GDB, but rather 1035 terminates the action of any GDB command that is in progress and 1036 returns to GDB command level. It is safe to type the interrupt 1037 character at any time because GDB does not allow it to take effect 1038 until a time when it is safe. 1039 1040 If you have been using GDB to control an attached process or device, 1041 you can release it with the `detach' command (*note Debugging an 1042 already-running process: Attach.). 1043 1044 1045 File: gdb.info, Node: Shell Commands, Next: Logging output, Prev: Quitting GDB, Up: Invocation 1046 1047 2.3 Shell commands 1048 ================== 1049 1050 If you need to execute occasional shell commands during your debugging 1051 session, there is no need to leave or suspend GDB; you can just use the 1052 `shell' command. 1053 1054 `shell COMMAND STRING' 1055 Invoke a standard shell to execute COMMAND STRING. If it exists, 1056 the environment variable `SHELL' determines which shell to run. 1057 Otherwise GDB uses the default shell (`/bin/sh' on Unix systems, 1058 `COMMAND.COM' on MS-DOS, etc.). 1059 1060 The utility `make' is often needed in development environments. You 1061 do not have to use the `shell' command for this purpose in GDB: 1062 1063 `make MAKE-ARGS' 1064 Execute the `make' program with the specified arguments. This is 1065 equivalent to `shell make MAKE-ARGS'. 1066 1067 1068 File: gdb.info, Node: Logging output, Prev: Shell Commands, Up: Invocation 1069 1070 2.4 Logging output 1071 ================== 1072 1073 You may want to save the output of GDB commands to a file. There are 1074 several commands to control GDB's logging. 1075 1076 `set logging on' 1077 Enable logging. 1078 1079 `set logging off' 1080 Disable logging. 1081 1082 `set logging file FILE' 1083 Change the name of the current logfile. The default logfile is 1084 `gdb.txt'. 1085 1086 `set logging overwrite [on|off]' 1087 By default, GDB will append to the logfile. Set `overwrite' if 1088 you want `set logging on' to overwrite the logfile instead. 1089 1090 `set logging redirect [on|off]' 1091 By default, GDB output will go to both the terminal and the 1092 logfile. Set `redirect' if you want output to go only to the log 1093 file. 1094 1095 `show logging' 1096 Show the current values of the logging settings. 1097 1098 1099 File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top 1100 1101 3 GDB Commands 1102 ************** 1103 1104 You can abbreviate a GDB command to the first few letters of the command 1105 name, if that abbreviation is unambiguous; and you can repeat certain 1106 GDB commands by typing just <RET>. You can also use the <TAB> key to 1107 get GDB to fill out the rest of a word in a command (or to show you the 1108 alternatives available, if there is more than one possibility). 1109 1110 * Menu: 1111 1112 * Command Syntax:: How to give commands to GDB 1113 * Completion:: Command completion 1114 * Help:: How to ask GDB for help 1115 1116 1117 File: gdb.info, Node: Command Syntax, Next: Completion, Up: Commands 1118 1119 3.1 Command syntax 1120 ================== 1121 1122 A GDB command is a single line of input. There is no limit on how long 1123 it can be. It starts with a command name, which is followed by 1124 arguments whose meaning depends on the command name. For example, the 1125 command `step' accepts an argument which is the number of times to 1126 step, as in `step 5'. You can also use the `step' command with no 1127 arguments. Some commands do not allow any arguments. 1128 1129 GDB command names may always be truncated if that abbreviation is 1130 unambiguous. Other possible command abbreviations are listed in the 1131 documentation for individual commands. In some cases, even ambiguous 1132 abbreviations are allowed; for example, `s' is specially defined as 1133 equivalent to `step' even though there are other commands whose names 1134 start with `s'. You can test abbreviations by using them as arguments 1135 to the `help' command. 1136 1137 A blank line as input to GDB (typing just <RET>) means to repeat the 1138 previous command. Certain commands (for example, `run') will not 1139 repeat this way; these are commands whose unintentional repetition 1140 might cause trouble and which you are unlikely to want to repeat. 1141 User-defined commands can disable this feature; see *Note dont-repeat: 1142 Define. 1143 1144 The `list' and `x' commands, when you repeat them with <RET>, 1145 construct new arguments rather than repeating exactly as typed. This 1146 permits easy scanning of source or memory. 1147 1148 GDB can also use <RET> in another way: to partition lengthy output, 1149 in a way similar to the common utility `more' (*note Screen size: 1150 Screen Size.). Since it is easy to press one <RET> too many in this 1151 situation, GDB disables command repetition after any command that 1152 generates this sort of display. 1153 1154 Any text from a `#' to the end of the line is a comment; it does 1155 nothing. This is useful mainly in command files (*note Command files: 1156 Command Files.). 1157 1158 The `Ctrl-o' binding is useful for repeating a complex sequence of 1159 commands. This command accepts the current line, like <RET>, and then 1160 fetches the next line relative to the current line from the history for 1161 editing. 1162 1163 1164 File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands 1165 1166 3.2 Command completion 1167 ====================== 1168 1169 GDB can fill in the rest of a word in a command for you, if there is 1170 only one possibility; it can also show you what the valid possibilities 1171 are for the next word in a command, at any time. This works for GDB 1172 commands, GDB subcommands, and the names of symbols in your program. 1173 1174 Press the <TAB> key whenever you want GDB to fill out the rest of a 1175 word. If there is only one possibility, GDB fills in the word, and 1176 waits for you to finish the command (or press <RET> to enter it). For 1177 example, if you type 1178 1179 (gdb) info bre <TAB> 1180 1181 GDB fills in the rest of the word `breakpoints', since that is the only 1182 `info' subcommand beginning with `bre': 1183 1184 (gdb) info breakpoints 1185 1186 You can either press <RET> at this point, to run the `info breakpoints' 1187 command, or backspace and enter something else, if `breakpoints' does 1188 not look like the command you expected. (If you were sure you wanted 1189 `info breakpoints' in the first place, you might as well just type 1190 <RET> immediately after `info bre', to exploit command abbreviations 1191 rather than command completion). 1192 1193 If there is more than one possibility for the next word when you 1194 press <TAB>, GDB sounds a bell. You can either supply more characters 1195 and try again, or just press <TAB> a second time; GDB displays all the 1196 possible completions for that word. For example, you might want to set 1197 a breakpoint on a subroutine whose name begins with `make_', but when 1198 you type `b make_<TAB>' GDB just sounds the bell. Typing <TAB> again 1199 displays all the function names in your program that begin with those 1200 characters, for example: 1201 1202 (gdb) b make_ <TAB> 1203 GDB sounds bell; press <TAB> again, to see: 1204 make_a_section_from_file make_environ 1205 make_abs_section make_function_type 1206 make_blockvector make_pointer_type 1207 make_cleanup make_reference_type 1208 make_command make_symbol_completion_list 1209 (gdb) b make_ 1210 1211 After displaying the available possibilities, GDB copies your partial 1212 input (`b make_' in the example) so you can finish the command. 1213 1214 If you just want to see the list of alternatives in the first place, 1215 you can press `M-?' rather than pressing <TAB> twice. `M-?' means 1216 `<META> ?'. You can type this either by holding down a key designated 1217 as the <META> shift on your keyboard (if there is one) while typing 1218 `?', or as <ESC> followed by `?'. 1219 1220 Sometimes the string you need, while logically a "word", may contain 1221 parentheses or other characters that GDB normally excludes from its 1222 notion of a word. To permit word completion to work in this situation, 1223 you may enclose words in `'' (single quote marks) in GDB commands. 1224 1225 The most likely situation where you might need this is in typing the 1226 name of a C++ function. This is because C++ allows function 1227 overloading (multiple definitions of the same function, distinguished 1228 by argument type). For example, when you want to set a breakpoint you 1229 may need to distinguish whether you mean the version of `name' that 1230 takes an `int' parameter, `name(int)', or the version that takes a 1231 `float' parameter, `name(float)'. To use the word-completion 1232 facilities in this situation, type a single quote `'' at the beginning 1233 of the function name. This alerts GDB that it may need to consider 1234 more information than usual when you press <TAB> or `M-?' to request 1235 word completion: 1236 1237 (gdb) b 'bubble( M-? 1238 bubble(double,double) bubble(int,int) 1239 (gdb) b 'bubble( 1240 1241 In some cases, GDB can tell that completing a name requires using 1242 quotes. When this happens, GDB inserts the quote for you (while 1243 completing as much as it can) if you do not type the quote in the first 1244 place: 1245 1246 (gdb) b bub <TAB> 1247 GDB alters your input line to the following, and rings a bell: 1248 (gdb) b 'bubble( 1249 1250 In general, GDB can tell that a quote is needed (and inserts it) if you 1251 have not yet started typing the argument list when you ask for 1252 completion on an overloaded symbol. 1253 1254 For more information about overloaded functions, see *Note C++ 1255 expressions: C plus plus expressions. You can use the command `set 1256 overload-resolution off' to disable overload resolution; see *Note GDB 1257 features for C++: Debugging C plus plus. 1258 1259 1260 File: gdb.info, Node: Help, Prev: Completion, Up: Commands 1261 1262 3.3 Getting help 1263 ================ 1264 1265 You can always ask GDB itself for information on its commands, using 1266 the command `help'. 1267 1268 `help' 1269 `h' 1270 You can use `help' (abbreviated `h') with no arguments to display 1271 a short list of named classes of commands: 1272 1273 (gdb) help 1274 List of classes of commands: 1275 1276 aliases -- Aliases of other commands 1277 breakpoints -- Making program stop at certain points 1278 data -- Examining data 1279 files -- Specifying and examining files 1280 internals -- Maintenance commands 1281 obscure -- Obscure features 1282 running -- Running the program 1283 stack -- Examining the stack 1284 status -- Status inquiries 1285 support -- Support facilities 1286 tracepoints -- Tracing of program execution without 1287 1288 stopping the program 1289 user-defined -- User-defined commands 1290 1291 Type "help" followed by a class name for a list of 1292 commands in that class. 1293 Type "help" followed by command name for full 1294 documentation. 1295 Command name abbreviations are allowed if unambiguous. 1296 (gdb) 1297 1298 `help CLASS' 1299 Using one of the general help classes as an argument, you can get a 1300 list of the individual commands in that class. For example, here 1301 is the help display for the class `status': 1302 1303 (gdb) help status 1304 Status inquiries. 1305 1306 List of commands: 1307 1308 info -- Generic command for showing things 1309 about the program being debugged 1310 show -- Generic command for showing things 1311 about the debugger 1312 1313 Type "help" followed by command name for full 1314 documentation. 1315 Command name abbreviations are allowed if unambiguous. 1316 (gdb) 1317 1318 `help COMMAND' 1319 With a command name as `help' argument, GDB displays a short 1320 paragraph on how to use that command. 1321 1322 `apropos ARGS' 1323 The `apropos' command searches through all of the GDB commands, 1324 and their documentation, for the regular expression specified in 1325 ARGS. It prints out all matches found. For example: 1326 1327 apropos reload 1328 1329 results in: 1330 1331 set symbol-reloading -- Set dynamic symbol table reloading 1332 multiple times in one run 1333 show symbol-reloading -- Show dynamic symbol table reloading 1334 multiple times in one run 1335 1336 `complete ARGS' 1337 The `complete ARGS' command lists all the possible completions for 1338 the beginning of a command. Use ARGS to specify the beginning of 1339 the command you want completed. For example: 1340 1341 complete i 1342 1343 results in: 1344 1345 if 1346 ignore 1347 info 1348 inspect 1349 1350 This is intended for use by GNU Emacs. 1351 1352 In addition to `help', you can use the GDB commands `info' and 1353 `show' to inquire about the state of your program, or the state of GDB 1354 itself. Each command supports many topics of inquiry; this manual 1355 introduces each of them in the appropriate context. The listings under 1356 `info' and under `show' in the Index point to all the sub-commands. 1357 *Note Index::. 1358 1359 `info' 1360 This command (abbreviated `i') is for describing the state of your 1361 program. For example, you can list the arguments given to your 1362 program with `info args', list the registers currently in use with 1363 `info registers', or list the breakpoints you have set with `info 1364 breakpoints'. You can get a complete list of the `info' 1365 sub-commands with `help info'. 1366 1367 `set' 1368 You can assign the result of an expression to an environment 1369 variable with `set'. For example, you can set the GDB prompt to a 1370 $-sign with `set prompt $'. 1371 1372 `show' 1373 In contrast to `info', `show' is for describing the state of GDB 1374 itself. You can change most of the things you can `show', by 1375 using the related command `set'; for example, you can control what 1376 number system is used for displays with `set radix', or simply 1377 inquire which is currently in use with `show radix'. 1378 1379 To display all the settable parameters and their current values, 1380 you can use `show' with no arguments; you may also use `info set'. 1381 Both commands produce the same display. 1382 1383 Here are three miscellaneous `show' subcommands, all of which are 1384 exceptional in lacking corresponding `set' commands: 1385 1386 `show version' 1387 Show what version of GDB is running. You should include this 1388 information in GDB bug-reports. If multiple versions of GDB are 1389 in use at your site, you may need to determine which version of 1390 GDB you are running; as GDB evolves, new commands are introduced, 1391 and old ones may wither away. Also, many system vendors ship 1392 variant versions of GDB, and there are variant versions of GDB in 1393 GNU/Linux distributions as well. The version number is the same 1394 as the one announced when you start GDB. 1395 1396 `show copying' 1397 `info copying' 1398 Display information about permission for copying GDB. 1399 1400 `show warranty' 1401 `info warranty' 1402 Display the GNU "NO WARRANTY" statement, or a warranty, if your 1403 version of GDB comes with one. 1404 1405 1406 1407 File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top 1408 1409 4 Running Programs Under GDB 1410 **************************** 1411 1412 When you run a program under GDB, you must first generate debugging 1413 information when you compile it. 1414 1415 You may start GDB with its arguments, if any, in an environment of 1416 your choice. If you are doing native debugging, you may redirect your 1417 program's input and output, debug an already running process, or kill a 1418 child process. 1419 1420 * Menu: 1421 1422 * Compilation:: Compiling for debugging 1423 * Starting:: Starting your program 1424 * Arguments:: Your program's arguments 1425 * Environment:: Your program's environment 1426 1427 * Working Directory:: Your program's working directory 1428 * Input/Output:: Your program's input and output 1429 * Attach:: Debugging an already-running process 1430 * Kill Process:: Killing the child process 1431 1432 * Threads:: Debugging programs with multiple threads 1433 * Processes:: Debugging programs with multiple processes 1434 * Checkpoint/Restart:: Setting a _bookmark_ to return to later 1435 1436 1437 File: gdb.info, Node: Compilation, Next: Starting, Up: Running 1438 1439 4.1 Compiling for debugging 1440 =========================== 1441 1442 In order to debug a program effectively, you need to generate debugging 1443 information when you compile it. This debugging information is stored 1444 in the object file; it describes the data type of each variable or 1445 function and the correspondence between source line numbers and 1446 addresses in the executable code. 1447 1448 To request debugging information, specify the `-g' option when you 1449 run the compiler. 1450 1451 Programs that are to be shipped to your customers are compiled with 1452 optimizations, using the `-O' compiler option. However, many compilers 1453 are unable to handle the `-g' and `-O' options together. Using those 1454 compilers, you cannot generate optimized executables containing 1455 debugging information. 1456 1457 GCC, the GNU C/C++ compiler, supports `-g' with or without `-O', 1458 making it possible to debug optimized code. We recommend that you 1459 _always_ use `-g' whenever you compile a program. You may think your 1460 program is correct, but there is no sense in pushing your luck. 1461 1462 When you debug a program compiled with `-g -O', remember that the 1463 optimizer is rearranging your code; the debugger shows you what is 1464 really there. Do not be too surprised when the execution path does not 1465 exactly match your source file! An extreme example: if you define a 1466 variable, but never use it, GDB never sees that variable--because the 1467 compiler optimizes it out of existence. 1468 1469 Some things do not work as well with `-g -O' as with just `-g', 1470 particularly on machines with instruction scheduling. If in doubt, 1471 recompile with `-g' alone, and if this fixes the problem, please report 1472 it to us as a bug (including a test case!). *Note Variables::, for 1473 more information about debugging optimized code. 1474 1475 Older versions of the GNU C compiler permitted a variant option 1476 `-gg' for debugging information. GDB no longer supports this format; 1477 if your GNU C compiler has this option, do not use it. 1478 1479 GDB knows about preprocessor macros and can show you their expansion 1480 (*note Macros::). Most compilers do not include information about 1481 preprocessor macros in the debugging information if you specify the 1482 `-g' flag alone, because this information is rather large. Version 3.1 1483 and later of GCC, the GNU C compiler, provides macro information if you 1484 specify the options `-gdwarf-2' and `-g3'; the former option requests 1485 debugging information in the Dwarf 2 format, and the latter requests 1486 "extra information". In the future, we hope to find more compact ways 1487 to represent macro information, so that it can be included with `-g' 1488 alone. 1489 1490 1491 File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running 1492 1493 4.2 Starting your program 1494 ========================= 1495 1496 `run' 1497 `r' 1498 Use the `run' command to start your program under GDB. You must 1499 first specify the program name (except on VxWorks) with an 1500 argument to GDB (*note Getting In and Out of GDB: Invocation.), or 1501 by using the `file' or `exec-file' command (*note Commands to 1502 specify files: Files.). 1503 1504 1505 If you are running your program in an execution environment that 1506 supports processes, `run' creates an inferior process and makes that 1507 process run your program. (In environments without processes, `run' 1508 jumps to the start of your program.) 1509 1510 The execution of a program is affected by certain information it 1511 receives from its superior. GDB provides ways to specify this 1512 information, which you must do _before_ starting your program. (You 1513 can change it after starting your program, but such changes only affect 1514 your program the next time you start it.) This information may be 1515 divided into four categories: 1516 1517 The _arguments._ 1518 Specify the arguments to give your program as the arguments of the 1519 `run' command. If a shell is available on your target, the shell 1520 is used to pass the arguments, so that you may use normal 1521 conventions (such as wildcard expansion or variable substitution) 1522 in describing the arguments. In Unix systems, you can control 1523 which shell is used with the `SHELL' environment variable. *Note 1524 Your program's arguments: Arguments. 1525 1526 The _environment._ 1527 Your program normally inherits its environment from GDB, but you 1528 can use the GDB commands `set environment' and `unset environment' 1529 to change parts of the environment that affect your program. 1530 *Note Your program's environment: Environment. 1531 1532 The _working directory._ 1533 Your program inherits its working directory from GDB. You can set 1534 the GDB working directory with the `cd' command in GDB. *Note 1535 Your program's working directory: Working Directory. 1536 1537 The _standard input and output._ 1538 Your program normally uses the same device for standard input and 1539 standard output as GDB is using. You can redirect input and output 1540 in the `run' command line, or you can use the `tty' command to set 1541 a different device for your program. *Note Your program's input 1542 and output: Input/Output. 1543 1544 _Warning:_ While input and output redirection work, you cannot use 1545 pipes to pass the output of the program you are debugging to 1546 another program; if you attempt this, GDB is likely to wind up 1547 debugging the wrong program. 1548 1549 When you issue the `run' command, your program begins to execute 1550 immediately. *Note Stopping and continuing: Stopping, for discussion 1551 of how to arrange for your program to stop. Once your program has 1552 stopped, you may call functions in your program, using the `print' or 1553 `call' commands. *Note Examining Data: Data. 1554 1555 If the modification time of your symbol file has changed since the 1556 last time GDB read its symbols, GDB discards its symbol table, and 1557 reads it again. When it does this, GDB tries to retain your current 1558 breakpoints. 1559 1560 `start' 1561 The name of the main procedure can vary from language to language. 1562 With C or C++, the main procedure name is always `main', but other 1563 languages such as Ada do not require a specific name for their 1564 main procedure. The debugger provides a convenient way to start 1565 the execution of the program and to stop at the beginning of the 1566 main procedure, depending on the language used. 1567 1568 The `start' command does the equivalent of setting a temporary 1569 breakpoint at the beginning of the main procedure and then invoking 1570 the `run' command. 1571 1572 Some programs contain an "elaboration" phase where some startup 1573 code is executed before the main procedure is called. This 1574 depends on the languages used to write your program. In C++, for 1575 instance, constructors for static and global objects are executed 1576 before `main' is called. It is therefore possible that the 1577 debugger stops before reaching the main procedure. However, the 1578 temporary breakpoint will remain to halt execution. 1579 1580 Specify the arguments to give to your program as arguments to the 1581 `start' command. These arguments will be given verbatim to the 1582 underlying `run' command. Note that the same arguments will be 1583 reused if no argument is provided during subsequent calls to 1584 `start' or `run'. 1585 1586 It is sometimes necessary to debug the program during elaboration. 1587 In these cases, using the `start' command would stop the 1588 execution of your program too late, as the program would have 1589 already completed the elaboration phase. Under these 1590 circumstances, insert breakpoints in your elaboration code before 1591 running your program. 1592 1593 1594 File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running 1595 1596 4.3 Your program's arguments 1597 ============================ 1598 1599 The arguments to your program can be specified by the arguments of the 1600 `run' command. They are passed to a shell, which expands wildcard 1601 characters and performs redirection of I/O, and thence to your program. 1602 Your `SHELL' environment variable (if it exists) specifies what shell 1603 GDB uses. If you do not define `SHELL', GDB uses the default shell 1604 (`/bin/sh' on Unix). 1605 1606 On non-Unix systems, the program is usually invoked directly by GDB, 1607 which emulates I/O redirection via the appropriate system calls, and 1608 the wildcard characters are expanded by the startup code of the 1609 program, not by the shell. 1610 1611 `run' with no arguments uses the same arguments used by the previous 1612 `run', or those set by the `set args' command. 1613 1614 `set args' 1615 Specify the arguments to be used the next time your program is 1616 run. If `set args' has no arguments, `run' executes your program 1617 with no arguments. Once you have run your program with arguments, 1618 using `set args' before the next `run' is the only way to run it 1619 again without arguments. 1620 1621 `show args' 1622 Show the arguments to give your program when it is started. 1623 1624 1625 File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running 1626 1627 4.4 Your program's environment 1628 ============================== 1629 1630 The "environment" consists of a set of environment variables and their 1631 values. Environment variables conventionally record such things as 1632 your user name, your home directory, your terminal type, and your search 1633 path for programs to run. Usually you set up environment variables with 1634 the shell and they are inherited by all the other programs you run. 1635 When debugging, it can be useful to try running your program with a 1636 modified environment without having to start GDB over again. 1637 1638 `path DIRECTORY' 1639 Add DIRECTORY to the front of the `PATH' environment variable (the 1640 search path for executables) that will be passed to your program. 1641 The value of `PATH' used by GDB does not change. You may specify 1642 several directory names, separated by whitespace or by a 1643 system-dependent separator character (`:' on Unix, `;' on MS-DOS 1644 and MS-Windows). If DIRECTORY is already in the path, it is moved 1645 to the front, so it is searched sooner. 1646 1647 You can use the string `$cwd' to refer to whatever is the current 1648 working directory at the time GDB searches the path. If you use 1649 `.' instead, it refers to the directory where you executed the 1650 `path' command. GDB replaces `.' in the DIRECTORY argument (with 1651 the current path) before adding DIRECTORY to the search path. 1652 1653 `show paths' 1654 Display the list of search paths for executables (the `PATH' 1655 environment variable). 1656 1657 `show environment [VARNAME]' 1658 Print the value of environment variable VARNAME to be given to 1659 your program when it starts. If you do not supply VARNAME, print 1660 the names and values of all environment variables to be given to 1661 your program. You can abbreviate `environment' as `env'. 1662 1663 `set environment VARNAME [=VALUE]' 1664 Set environment variable VARNAME to VALUE. The value changes for 1665 your program only, not for GDB itself. VALUE may be any string; 1666 the values of environment variables are just strings, and any 1667 interpretation is supplied by your program itself. The VALUE 1668 parameter is optional; if it is eliminated, the variable is set to 1669 a null value. 1670 1671 For example, this command: 1672 1673 set env USER = foo 1674 1675 tells the debugged program, when subsequently run, that its user 1676 is named `foo'. (The spaces around `=' are used for clarity here; 1677 they are not actually required.) 1678 1679 `unset environment VARNAME' 1680 Remove variable VARNAME from the environment to be passed to your 1681 program. This is different from `set env VARNAME ='; `unset 1682 environment' removes the variable from the environment, rather 1683 than assigning it an empty value. 1684 1685 _Warning:_ On Unix systems, GDB runs your program using the shell 1686 indicated by your `SHELL' environment variable if it exists (or 1687 `/bin/sh' if not). If your `SHELL' variable names a shell that runs an 1688 initialization file--such as `.cshrc' for C-shell, or `.bashrc' for 1689 BASH--any variables you set in that file affect your program. You may 1690 wish to move setting of environment variables to files that are only 1691 run when you sign on, such as `.login' or `.profile'. 1692 1693 1694 File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running 1695 1696 4.5 Your program's working directory 1697 ==================================== 1698 1699 Each time you start your program with `run', it inherits its working 1700 directory from the current working directory of GDB. The GDB working 1701 directory is initially whatever it inherited from its parent process 1702 (typically the shell), but you can specify a new working directory in 1703 GDB with the `cd' command. 1704 1705 The GDB working directory also serves as a default for the commands 1706 that specify files for GDB to operate on. *Note Commands to specify 1707 files: Files. 1708 1709 `cd DIRECTORY' 1710 Set the GDB working directory to DIRECTORY. 1711 1712 `pwd' 1713 Print the GDB working directory. 1714 1715 It is generally impossible to find the current working directory of 1716 the process being debugged (since a program can change its directory 1717 during its run). If you work on a system where GDB is configured with 1718 the `/proc' support, you can use the `info proc' command (*note SVR4 1719 Process Information::) to find out the current working directory of the 1720 debuggee. 1721 1722 1723 File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running 1724 1725 4.6 Your program's input and output 1726 =================================== 1727 1728 By default, the program you run under GDB does input and output to the 1729 same terminal that GDB uses. GDB switches the terminal to its own 1730 terminal modes to interact with you, but it records the terminal modes 1731 your program was using and switches back to them when you continue 1732 running your program. 1733 1734 `info terminal' 1735 Displays information recorded by GDB about the terminal modes your 1736 program is using. 1737 1738 You can redirect your program's input and/or output using shell 1739 redirection with the `run' command. For example, 1740 1741 run > outfile 1742 1743 starts your program, diverting its output to the file `outfile'. 1744 1745 Another way to specify where your program should do input and output 1746 is with the `tty' command. This command accepts a file name as 1747 argument, and causes this file to be the default for future `run' 1748 commands. It also resets the controlling terminal for the child 1749 process, for future `run' commands. For example, 1750 1751 tty /dev/ttyb 1752 1753 directs that processes started with subsequent `run' commands default 1754 to do input and output on the terminal `/dev/ttyb' and have that as 1755 their controlling terminal. 1756 1757 An explicit redirection in `run' overrides the `tty' command's 1758 effect on the input/output device, but not its effect on the controlling 1759 terminal. 1760 1761 When you use the `tty' command or redirect input in the `run' 1762 command, only the input _for your program_ is affected. The input for 1763 GDB still comes from your terminal. `tty' is an alias for `set 1764 inferior-tty'. 1765 1766 You can use the `show inferior-tty' command to tell GDB to display 1767 the name of the terminal that will be used for future runs of your 1768 program. 1769 1770 `set inferior-tty /dev/ttyb' 1771 Set the tty for the program being debugged to /dev/ttyb. 1772 1773 `show inferior-tty' 1774 Show the current tty for the program being debugged. 1775 1776 1777 File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running 1778 1779 4.7 Debugging an already-running process 1780 ======================================== 1781 1782 `attach PROCESS-ID' 1783 This command attaches to a running process--one that was started 1784 outside GDB. (`info files' shows your active targets.) The 1785 command takes as argument a process ID. The usual way to find out 1786 the PROCESS-ID of a Unix process is with the `ps' utility, or with 1787 the `jobs -l' shell command. 1788 1789 `attach' does not repeat if you press <RET> a second time after 1790 executing the command. 1791 1792 To use `attach', your program must be running in an environment 1793 which supports processes; for example, `attach' does not work for 1794 programs on bare-board targets that lack an operating system. You must 1795 also have permission to send the process a signal. 1796 1797 When you use `attach', the debugger finds the program running in the 1798 process first by looking in the current working directory, then (if the 1799 program is not found) by using the source file search path (*note 1800 Specifying source directories: Source Path.). You can also use the 1801 `file' command to load the program. *Note Commands to Specify Files: 1802 Files. 1803 1804 The first thing GDB does after arranging to debug the specified 1805 process is to stop it. You can examine and modify an attached process 1806 with all the GDB commands that are ordinarily available when you start 1807 processes with `run'. You can insert breakpoints; you can step and 1808 continue; you can modify storage. If you would rather the process 1809 continue running, you may use the `continue' command after attaching 1810 GDB to the process. 1811 1812 `detach' 1813 When you have finished debugging the attached process, you can use 1814 the `detach' command to release it from GDB control. Detaching 1815 the process continues its execution. After the `detach' command, 1816 that process and GDB become completely independent once more, and 1817 you are ready to `attach' another process or start one with `run'. 1818 `detach' does not repeat if you press <RET> again after executing 1819 the command. 1820 1821 If you exit GDB or use the `run' command while you have an attached 1822 process, you kill that process. By default, GDB asks for confirmation 1823 if you try to do either of these things; you can control whether or not 1824 you need to confirm by using the `set confirm' command (*note Optional 1825 warnings and messages: Messages/Warnings.). 1826 1827 1828 File: gdb.info, Node: Kill Process, Next: Threads, Prev: Attach, Up: Running 1829 1830 4.8 Killing the child process 1831 ============================= 1832 1833 `kill' 1834 Kill the child process in which your program is running under GDB. 1835 1836 This command is useful if you wish to debug a core dump instead of a 1837 running process. GDB ignores any core dump file while your program is 1838 running. 1839 1840 On some operating systems, a program cannot be executed outside GDB 1841 while you have breakpoints set on it inside GDB. You can use the 1842 `kill' command in this situation to permit running your program outside 1843 the debugger. 1844 1845 The `kill' command is also useful if you wish to recompile and 1846 relink your program, since on many systems it is impossible to modify an 1847 executable file while it is running in a process. In this case, when 1848 you next type `run', GDB notices that the file has changed, and reads 1849 the symbol table again (while trying to preserve your current 1850 breakpoint settings). 1851 1852 1853 File: gdb.info, Node: Threads, Next: Processes, Prev: Kill Process, Up: Running 1854 1855 4.9 Debugging programs with multiple threads 1856 ============================================ 1857 1858 In some operating systems, such as HP-UX and Solaris, a single program 1859 may have more than one "thread" of execution. The precise semantics of 1860 threads differ from one operating system to another, but in general the 1861 threads of a single program are akin to multiple processes--except that 1862 they share one address space (that is, they can all examine and modify 1863 the same variables). On the other hand, each thread has its own 1864 registers and execution stack, and perhaps private memory. 1865 1866 GDB provides these facilities for debugging multi-thread programs: 1867 1868 * automatic notification of new threads 1869 1870 * `thread THREADNO', a command to switch among threads 1871 1872 * `info threads', a command to inquire about existing threads 1873 1874 * `thread apply [THREADNO] [ALL] ARGS', a command to apply a command 1875 to a list of threads 1876 1877 * thread-specific breakpoints 1878 1879 _Warning:_ These facilities are not yet available on every GDB 1880 configuration where the operating system supports threads. If 1881 your GDB does not support threads, these commands have no effect. 1882 For example, a system without thread support shows no output from 1883 `info threads', and always rejects the `thread' command, like this: 1884 1885 (gdb) info threads 1886 (gdb) thread 1 1887 Thread ID 1 not known. Use the "info threads" command to 1888 see the IDs of currently known threads. 1889 1890 The GDB thread debugging facility allows you to observe all threads 1891 while your program runs--but whenever GDB takes control, one thread in 1892 particular is always the focus of debugging. This thread is called the 1893 "current thread". Debugging commands show program information from the 1894 perspective of the current thread. 1895 1896 Whenever GDB detects a new thread in your program, it displays the 1897 target system's identification for the thread with a message in the 1898 form `[New SYSTAG]'. SYSTAG is a thread identifier whose form varies 1899 depending on the particular system. For example, on LynxOS, you might 1900 see 1901 1902 [New process 35 thread 27] 1903 1904 when GDB notices a new thread. In contrast, on an SGI system, the 1905 SYSTAG is simply something like `process 368', with no further 1906 qualifier. 1907 1908 For debugging purposes, GDB associates its own thread number--always 1909 a single integer--with each thread in your program. 1910 1911 `info threads' 1912 Display a summary of all threads currently in your program. GDB 1913 displays for each thread (in this order): 1914 1915 1. the thread number assigned by GDB 1916 1917 2. the target system's thread identifier (SYSTAG) 1918 1919 3. the current stack frame summary for that thread 1920 1921 An asterisk `*' to the left of the GDB thread number indicates the 1922 current thread. 1923 1924 For example, 1925 1926 (gdb) info threads 1927 3 process 35 thread 27 0x34e5 in sigpause () 1928 2 process 35 thread 23 0x34e5 in sigpause () 1929 * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) 1930 at threadtest.c:68 1931 1932 On HP-UX systems: 1933 1934 For debugging purposes, GDB associates its own thread number--a 1935 small integer assigned in thread-creation order--with each thread in 1936 your program. 1937 1938 Whenever GDB detects a new thread in your program, it displays both 1939 GDB's thread number and the target system's identification for the 1940 thread with a message in the form `[New SYSTAG]'. SYSTAG is a thread 1941 identifier whose form varies depending on the particular system. For 1942 example, on HP-UX, you see 1943 1944 [New thread 2 (system thread 26594)] 1945 1946 when GDB notices a new thread. 1947 1948 `info threads' 1949 Display a summary of all threads currently in your program. GDB 1950 displays for each thread (in this order): 1951 1952 1. the thread number assigned by GDB 1953 1954 2. the target system's thread identifier (SYSTAG) 1955 1956 3. the current stack frame summary for that thread 1957 1958 An asterisk `*' to the left of the GDB thread number indicates the 1959 current thread. 1960 1961 For example, 1962 1963 (gdb) info threads 1964 * 3 system thread 26607 worker (wptr=0x7b09c318 "@") \ 1965 1966 at quicksort.c:137 1967 2 system thread 26606 0x7b0030d8 in __ksleep () \ 1968 1969 from /usr/lib/libc.2 1970 1 system thread 27905 0x7b003498 in _brk () \ 1971 1972 from /usr/lib/libc.2 1973 1974 On Solaris, you can display more information about user threads with 1975 a Solaris-specific command: 1976 1977 `maint info sol-threads' 1978 Display info on Solaris user threads. 1979 1980 `thread THREADNO' 1981 Make thread number THREADNO the current thread. The command 1982 argument THREADNO is the internal GDB thread number, as shown in 1983 the first field of the `info threads' display. GDB responds by 1984 displaying the system identifier of the thread you selected, and 1985 its current stack frame summary: 1986 1987 (gdb) thread 2 1988 [Switching to process 35 thread 23] 1989 0x34e5 in sigpause () 1990 1991 As with the `[New ...]' message, the form of the text after 1992 `Switching to' depends on your system's conventions for identifying 1993 threads. 1994 1995 `thread apply [THREADNO] [ALL] COMMAND' 1996 The `thread apply' command allows you to apply the named COMMAND 1997 to one or more threads. Specify the numbers of the threads that 1998 you want affected with the command argument THREADNO. It can be a 1999 single thread number, one of the numbers shown in the first field 2000 of the `info threads' display; or it could be a range of thread 2001 numbers, as in `2-4'. To apply a command to all threads, type 2002 `thread apply all COMMAND'. 2003 2004 Whenever GDB stops your program, due to a breakpoint or a signal, it 2005 automatically selects the thread where that breakpoint or signal 2006 happened. GDB alerts you to the context switch with a message of the 2007 form `[Switching to SYSTAG]' to identify the thread. 2008 2009 *Note Stopping and starting multi-thread programs: Thread Stops, for 2010 more information about how GDB behaves when you stop and start programs 2011 with multiple threads. 2012 2013 *Note Setting watchpoints: Set Watchpoints, for information about 2014 watchpoints in programs with multiple threads. 2015 2016 2017 File: gdb.info, Node: Processes, Next: Checkpoint/Restart, Prev: Threads, Up: Running 2018 2019 4.10 Debugging programs with multiple processes 2020 =============================================== 2021 2022 On most systems, GDB has no special support for debugging programs 2023 which create additional processes using the `fork' function. When a 2024 program forks, GDB will continue to debug the parent process and the 2025 child process will run unimpeded. If you have set a breakpoint in any 2026 code which the child then executes, the child will get a `SIGTRAP' 2027 signal which (unless it catches the signal) will cause it to terminate. 2028 2029 However, if you want to debug the child process there is a workaround 2030 which isn't too painful. Put a call to `sleep' in the code which the 2031 child process executes after the fork. It may be useful to sleep only 2032 if a certain environment variable is set, or a certain file exists, so 2033 that the delay need not occur when you don't want to run GDB on the 2034 child. While the child is sleeping, use the `ps' program to get its 2035 process ID. Then tell GDB (a new invocation of GDB if you are also 2036 debugging the parent process) to attach to the child process (*note 2037 Attach::). From that point on you can debug the child process just 2038 like any other process which you attached to. 2039 2040 On some systems, GDB provides support for debugging programs that 2041 create additional processes using the `fork' or `vfork' functions. 2042 Currently, the only platforms with this feature are HP-UX (11.x and 2043 later only?) and GNU/Linux (kernel version 2.5.60 and later). 2044 2045 By default, when a program forks, GDB will continue to debug the 2046 parent process and the child process will run unimpeded. 2047 2048 If you want to follow the child process instead of the parent 2049 process, use the command `set follow-fork-mode'. 2050 2051 `set follow-fork-mode MODE' 2052 Set the debugger response to a program call of `fork' or `vfork'. 2053 A call to `fork' or `vfork' creates a new process. The MODE 2054 argument can be: 2055 2056 `parent' 2057 The original process is debugged after a fork. The child 2058 process runs unimpeded. This is the default. 2059 2060 `child' 2061 The new process is debugged after a fork. The parent process 2062 runs unimpeded. 2063 2064 2065 `show follow-fork-mode' 2066 Display the current debugger response to a `fork' or `vfork' call. 2067 2068 On Linux, if you want to debug both the parent and child processes, 2069 use the command `set detach-on-fork'. 2070 2071 `set detach-on-fork MODE' 2072 Tells gdb whether to detach one of the processes after a fork, or 2073 retain debugger control over them both. 2074 2075 `on' 2076 The child process (or parent process, depending on the value 2077 of `follow-fork-mode') will be detached and allowed to run 2078 independently. This is the default. 2079 2080 `off' 2081 Both processes will be held under the control of GDB. One 2082 process (child or parent, depending on the value of 2083 `follow-fork-mode') is debugged as usual, while the other is 2084 held suspended. 2085 2086 2087 `show detach-on-follow' 2088 Show whether detach-on-follow mode is on/off. 2089 2090 If you choose to set DETACH-ON-FOLLOW mode off, then GDB will retain 2091 control of all forked processes (including nested forks). You can list 2092 the forked processes under the control of GDB by using the `info forks' 2093 command, and switch from one fork to another by using the `fork' 2094 command. 2095 2096 `info forks' 2097 Print a list of all forked processes under the control of GDB. 2098 The listing will include a fork id, a process id, and the current 2099 position (program counter) of the process. 2100 2101 `fork FORK-ID' 2102 Make fork number FORK-ID the current process. The argument 2103 FORK-ID is the internal fork number assigned by GDB, as shown in 2104 the first field of the `info forks' display. 2105 2106 2107 To quit debugging one of the forked processes, you can either detach 2108 from it by using the `detach fork' command (allowing it to run 2109 independently), or delete (and kill) it using the `delete fork' command. 2110 2111 `detach fork FORK-ID' 2112 Detach from the process identified by GDB fork number FORK-ID, and 2113 remove it from the fork list. The process will be allowed to run 2114 independently. 2115 2116 `delete fork FORK-ID' 2117 Kill the process identified by GDB fork number FORK-ID, and remove 2118 it from the fork list. 2119 2120 2121 If you ask to debug a child process and a `vfork' is followed by an 2122 `exec', GDB executes the new target up to the first breakpoint in the 2123 new target. If you have a breakpoint set on `main' in your original 2124 program, the breakpoint will also be set on the child process's `main'. 2125 2126 When a child process is spawned by `vfork', you cannot debug the 2127 child or parent until an `exec' call completes. 2128 2129 If you issue a `run' command to GDB after an `exec' call executes, 2130 the new target restarts. To restart the parent process, use the `file' 2131 command with the parent executable name as its argument. 2132 2133 You can use the `catch' command to make GDB stop whenever a `fork', 2134 `vfork', or `exec' call is made. *Note Setting catchpoints: Set 2135 Catchpoints. 2136 2137 2138 File: gdb.info, Node: Checkpoint/Restart, Prev: Processes, Up: Running 2139 2140 4.11 Setting a _bookmark_ to return to later 2141 ============================================ 2142 2143 On certain operating systems(1), GDB is able to save a "snapshot" of a 2144 program's state, called a "checkpoint", and come back to it later. 2145 2146 Returning to a checkpoint effectively undoes everything that has 2147 happened in the program since the `checkpoint' was saved. This 2148 includes changes in memory, registers, and even (within some limits) 2149 system state. Effectively, it is like going back in time to the moment 2150 when the checkpoint was saved. 2151 2152 Thus, if you're stepping thru a program and you think you're getting 2153 close to the point where things go wrong, you can save a checkpoint. 2154 Then, if you accidentally go too far and miss the critical statement, 2155 instead of having to restart your program from the beginning, you can 2156 just go back to the checkpoint and start again from there. 2157 2158 This can be especially useful if it takes a lot of time or steps to 2159 reach the point where you think the bug occurs. 2160 2161 To use the `checkpoint'/`restart' method of debugging: 2162 2163 `checkpoint' 2164 Save a snapshot of the debugged program's current execution state. 2165 The `checkpoint' command takes no arguments, but each checkpoint 2166 is assigned a small integer id, similar to a breakpoint id. 2167 2168 `info checkpoints' 2169 List the checkpoints that have been saved in the current debugging 2170 session. For each checkpoint, the following information will be 2171 listed: 2172 2173 `Checkpoint ID' 2174 2175 `Process ID' 2176 2177 `Code Address' 2178 2179 `Source line, or label' 2180 2181 `restart CHECKPOINT-ID' 2182 Restore the program state that was saved as checkpoint number 2183 CHECKPOINT-ID. All program variables, registers, stack frames 2184 etc. will be returned to the values that they had when the 2185 checkpoint was saved. In essence, gdb will "wind back the clock" 2186 to the point in time when the checkpoint was saved. 2187 2188 Note that breakpoints, GDB variables, command history etc. are 2189 not affected by restoring a checkpoint. In general, a checkpoint 2190 only restores things that reside in the program being debugged, 2191 not in the debugger. 2192 2193 `delete checkpoint CHECKPOINT-ID' 2194 Delete the previously-saved checkpoint identified by CHECKPOINT-ID. 2195 2196 2197 Returning to a previously saved checkpoint will restore the user 2198 state of the program being debugged, plus a significant subset of the 2199 system (OS) state, including file pointers. It won't "un-write" data 2200 from a file, but it will rewind the file pointer to the previous 2201 location, so that the previously written data can be overwritten. For 2202 files opened in read mode, the pointer will also be restored so that the 2203 previously read data can be read again. 2204 2205 Of course, characters that have been sent to a printer (or other 2206 external device) cannot be "snatched back", and characters received 2207 from eg. a serial device can be removed from internal program buffers, 2208 but they cannot be "pushed back" into the serial pipeline, ready to be 2209 received again. Similarly, the actual contents of files that have been 2210 changed cannot be restored (at this time). 2211 2212 However, within those constraints, you actually can "rewind" your 2213 program to a previously saved point in time, and begin debugging it 2214 again -- and you can change the course of events so as to debug a 2215 different execution path this time. 2216 2217 Finally, there is one bit of internal program state that will be 2218 different when you return to a checkpoint -- the program's process id. 2219 Each checkpoint will have a unique process id (or PID), and each will 2220 be different from the program's original PID. If your program has 2221 saved a local copy of its process id, this could potentially pose a 2222 problem. 2223 2224 4.11.1 A non-obvious benefit of using checkpoints 2225 ------------------------------------------------- 2226 2227 On some systems such as GNU/Linux, address space randomization is 2228 performed on new processes for security reasons. This makes it 2229 difficult or impossible to set a breakpoint, or watchpoint, on an 2230 absolute address if you have to restart the program, since the absolute 2231 location of a symbol will change from one execution to the next. 2232 2233 A checkpoint, however, is an _identical_ copy of a process. 2234 Therefore if you create a checkpoint at (eg.) the start of main, and 2235 simply return to that checkpoint instead of restarting the process, you 2236 can avoid the effects of address randomization and your symbols will 2237 all stay in the same place. 2238 2239 ---------- Footnotes ---------- 2240 2241 (1) Currently, only GNU/Linux. 2242 2243 2244 File: gdb.info, Node: Stopping, Next: Stack, Prev: Running, Up: Top 2245 2246 5 Stopping and Continuing 2247 ************************* 2248 2249 The principal purposes of using a debugger are so that you can stop your 2250 program before it terminates; or so that, if your program runs into 2251 trouble, you can investigate and find out why. 2252 2253 Inside GDB, your program may stop for any of several reasons, such 2254 as a signal, a breakpoint, or reaching a new line after a GDB command 2255 such as `step'. You may then examine and change variables, set new 2256 breakpoints or remove old ones, and then continue execution. Usually, 2257 the messages shown by GDB provide ample explanation of the status of 2258 your program--but you can also explicitly request this information at 2259 any time. 2260 2261 `info program' 2262 Display information about the status of your program: whether it is 2263 running or not, what process it is, and why it stopped. 2264 2265 * Menu: 2266 2267 * Breakpoints:: Breakpoints, watchpoints, and catchpoints 2268 * Continuing and Stepping:: Resuming execution 2269 * Signals:: Signals 2270 * Thread Stops:: Stopping and starting multi-thread programs 2271 2272 2273 File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping 2274 2275 5.1 Breakpoints, watchpoints, and catchpoints 2276 ============================================= 2277 2278 A "breakpoint" makes your program stop whenever a certain point in the 2279 program is reached. For each breakpoint, you can add conditions to 2280 control in finer detail whether your program stops. You can set 2281 breakpoints with the `break' command and its variants (*note Setting 2282 breakpoints: Set Breaks.), to specify the place where your program 2283 should stop by line number, function name or exact address in the 2284 program. 2285 2286 On some systems, you can set breakpoints in shared libraries before 2287 the executable is run. There is a minor limitation on HP-UX systems: 2288 you must wait until the executable is run in order to set breakpoints 2289 in shared library routines that are not called directly by the program 2290 (for example, routines that are arguments in a `pthread_create' call). 2291 2292 A "watchpoint" is a special breakpoint that stops your program when 2293 the value of an expression changes. The expression may be a value of a 2294 variable, or it could involve values of one or more variables combined 2295 by operators, such as `a + b'. This is sometimes called "data 2296 breakpoints". You must use a different command to set watchpoints 2297 (*note Setting watchpoints: Set Watchpoints.), but aside from that, you 2298 can manage a watchpoint like any other breakpoint: you enable, disable, 2299 and delete both breakpoints and watchpoints using the same commands. 2300 2301 You can arrange to have values from your program displayed 2302 automatically whenever GDB stops at a breakpoint. *Note Automatic 2303 display: Auto Display. 2304 2305 A "catchpoint" is another special breakpoint that stops your program 2306 when a certain kind of event occurs, such as the throwing of a C++ 2307 exception or the loading of a library. As with watchpoints, you use a 2308 different command to set a catchpoint (*note Setting catchpoints: Set 2309 Catchpoints.), but aside from that, you can manage a catchpoint like any 2310 other breakpoint. (To stop when your program receives a signal, use the 2311 `handle' command; see *Note Signals: Signals.) 2312 2313 GDB assigns a number to each breakpoint, watchpoint, or catchpoint 2314 when you create it; these numbers are successive integers starting with 2315 one. In many of the commands for controlling various features of 2316 breakpoints you use the breakpoint number to say which breakpoint you 2317 want to change. Each breakpoint may be "enabled" or "disabled"; if 2318 disabled, it has no effect on your program until you enable it again. 2319 2320 Some GDB commands accept a range of breakpoints on which to operate. 2321 A breakpoint range is either a single breakpoint number, like `5', or 2322 two such numbers, in increasing order, separated by a hyphen, like 2323 `5-7'. When a breakpoint range is given to a command, all breakpoint 2324 in that range are operated on. 2325 2326 * Menu: 2327 2328 * Set Breaks:: Setting breakpoints 2329 * Set Watchpoints:: Setting watchpoints 2330 * Set Catchpoints:: Setting catchpoints 2331 * Delete Breaks:: Deleting breakpoints 2332 * Disabling:: Disabling breakpoints 2333 * Conditions:: Break conditions 2334 * Break Commands:: Breakpoint command lists 2335 * Breakpoint Menus:: Breakpoint menus 2336 * Error in Breakpoints:: ``Cannot insert breakpoints'' 2337 * Breakpoint related warnings:: ``Breakpoint address adjusted...'' 2338 2339 2340 File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints 2341 2342 5.1.1 Setting breakpoints 2343 ------------------------- 2344 2345 Breakpoints are set with the `break' command (abbreviated `b'). The 2346 debugger convenience variable `$bpnum' records the number of the 2347 breakpoint you've set most recently; see *Note Convenience variables: 2348 Convenience Vars, for a discussion of what you can do with convenience 2349 variables. 2350 2351 You have several ways to say where the breakpoint should go. 2352 2353 `break FUNCTION' 2354 Set a breakpoint at entry to function FUNCTION. When using source 2355 languages that permit overloading of symbols, such as C++, 2356 FUNCTION may refer to more than one possible place to break. 2357 *Note Breakpoint menus: Breakpoint Menus, for a discussion of that 2358 situation. 2359 2360 `break +OFFSET' 2361 `break -OFFSET' 2362 Set a breakpoint some number of lines forward or back from the 2363 position at which execution stopped in the currently selected 2364 "stack frame". (*Note Frames: Frames, for a description of stack 2365 frames.) 2366 2367 `break LINENUM' 2368 Set a breakpoint at line LINENUM in the current source file. The 2369 current source file is the last file whose source text was printed. 2370 The breakpoint will stop your program just before it executes any 2371 of the code on that line. 2372 2373 `break FILENAME:LINENUM' 2374 Set a breakpoint at line LINENUM in source file FILENAME. 2375 2376 `break FILENAME:FUNCTION' 2377 Set a breakpoint at entry to function FUNCTION found in file 2378 FILENAME. Specifying a file name as well as a function name is 2379 superfluous except when multiple files contain similarly named 2380 functions. 2381 2382 `break *ADDRESS' 2383 Set a breakpoint at address ADDRESS. You can use this to set 2384 breakpoints in parts of your program which do not have debugging 2385 information or source files. 2386 2387 `break' 2388 When called without any arguments, `break' sets a breakpoint at 2389 the next instruction to be executed in the selected stack frame 2390 (*note Examining the Stack: Stack.). In any selected frame but the 2391 innermost, this makes your program stop as soon as control returns 2392 to that frame. This is similar to the effect of a `finish' 2393 command in the frame inside the selected frame--except that 2394 `finish' does not leave an active breakpoint. If you use `break' 2395 without an argument in the innermost frame, GDB stops the next 2396 time it reaches the current location; this may be useful inside 2397 loops. 2398 2399 GDB normally ignores breakpoints when it resumes execution, until 2400 at least one instruction has been executed. If it did not do 2401 this, you would be unable to proceed past a breakpoint without 2402 first disabling the breakpoint. This rule applies whether or not 2403 the breakpoint already existed when your program stopped. 2404 2405 `break ... if COND' 2406 Set a breakpoint with condition COND; evaluate the expression COND 2407 each time the breakpoint is reached, and stop only if the value is 2408 nonzero--that is, if COND evaluates as true. `...' stands for one 2409 of the possible arguments described above (or no argument) 2410 specifying where to break. *Note Break conditions: Conditions, 2411 for more information on breakpoint conditions. 2412 2413 `tbreak ARGS' 2414 Set a breakpoint enabled only for one stop. ARGS are the same as 2415 for the `break' command, and the breakpoint is set in the same 2416 way, but the breakpoint is automatically deleted after the first 2417 time your program stops there. *Note Disabling breakpoints: 2418 Disabling. 2419 2420 `hbreak ARGS' 2421 Set a hardware-assisted breakpoint. ARGS are the same as for the 2422 `break' command and the breakpoint is set in the same way, but the 2423 breakpoint requires hardware support and some target hardware may 2424 not have this support. The main purpose of this is EPROM/ROM code 2425 debugging, so you can set a breakpoint at an instruction without 2426 changing the instruction. This can be used with the new 2427 trap-generation provided by SPARClite DSU and most x86-based 2428 targets. These targets will generate traps when a program 2429 accesses some data or instruction address that is assigned to the 2430 debug registers. However the hardware breakpoint registers can 2431 take a limited number of breakpoints. For example, on the DSU, 2432 only two data breakpoints can be set at a time, and GDB will 2433 reject this command if more than two are used. Delete or disable 2434 unused hardware breakpoints before setting new ones (*note 2435 Disabling: Disabling.). *Note Break conditions: Conditions. For 2436 remote targets, you can restrict the number of hardware 2437 breakpoints GDB will use, see *Note set remote 2438 hardware-breakpoint-limit::. 2439 2440 `thbreak ARGS' 2441 Set a hardware-assisted breakpoint enabled only for one stop. ARGS 2442 are the same as for the `hbreak' command and the breakpoint is set 2443 in the same way. However, like the `tbreak' command, the 2444 breakpoint is automatically deleted after the first time your 2445 program stops there. Also, like the `hbreak' command, the 2446 breakpoint requires hardware support and some target hardware may 2447 not have this support. *Note Disabling breakpoints: Disabling. 2448 See also *Note Break conditions: Conditions. 2449 2450 `rbreak REGEX' 2451 Set breakpoints on all functions matching the regular expression 2452 REGEX. This command sets an unconditional breakpoint on all 2453 matches, printing a list of all breakpoints it set. Once these 2454 breakpoints are set, they are treated just like the breakpoints 2455 set with the `break' command. You can delete them, disable them, 2456 or make them conditional the same way as any other breakpoint. 2457 2458 The syntax of the regular expression is the standard one used with 2459 tools like `grep'. Note that this is different from the syntax 2460 used by shells, so for instance `foo*' matches all functions that 2461 include an `fo' followed by zero or more `o's. There is an 2462 implicit `.*' leading and trailing the regular expression you 2463 supply, so to match only functions that begin with `foo', use 2464 `^foo'. 2465 2466 When debugging C++ programs, `rbreak' is useful for setting 2467 breakpoints on overloaded functions that are not members of any 2468 special classes. 2469 2470 The `rbreak' command can be used to set breakpoints in *all* the 2471 functions in a program, like this: 2472 2473 (gdb) rbreak . 2474 2475 `info breakpoints [N]' 2476 `info break [N]' 2477 `info watchpoints [N]' 2478 Print a table of all breakpoints, watchpoints, and catchpoints set 2479 and not deleted. Optional argument N means print information only 2480 about the specified breakpoint (or watchpoint or catchpoint). For 2481 each breakpoint, following columns are printed: 2482 2483 _Breakpoint Numbers_ 2484 2485 _Type_ 2486 Breakpoint, watchpoint, or catchpoint. 2487 2488 _Disposition_ 2489 Whether the breakpoint is marked to be disabled or deleted 2490 when hit. 2491 2492 _Enabled or Disabled_ 2493 Enabled breakpoints are marked with `y'. `n' marks 2494 breakpoints that are not enabled. 2495 2496 _Address_ 2497 Where the breakpoint is in your program, as a memory address. 2498 If the breakpoint is pending (see below for details) on a 2499 future load of a shared library, the address will be listed 2500 as `<PENDING>'. 2501 2502 _What_ 2503 Where the breakpoint is in the source for your program, as a 2504 file and line number. For a pending breakpoint, the original 2505 string passed to the breakpoint command will be listed as it 2506 cannot be resolved until the appropriate shared library is 2507 loaded in the future. 2508 2509 If a breakpoint is conditional, `info break' shows the condition on 2510 the line following the affected breakpoint; breakpoint commands, 2511 if any, are listed after that. A pending breakpoint is allowed to 2512 have a condition specified for it. The condition is not parsed 2513 for validity until a shared library is loaded that allows the 2514 pending breakpoint to resolve to a valid location. 2515 2516 `info break' with a breakpoint number N as argument lists only 2517 that breakpoint. The convenience variable `$_' and the default 2518 examining-address for the `x' command are set to the address of 2519 the last breakpoint listed (*note Examining memory: Memory.). 2520 2521 `info break' displays a count of the number of times the breakpoint 2522 has been hit. This is especially useful in conjunction with the 2523 `ignore' command. You can ignore a large number of breakpoint 2524 hits, look at the breakpoint info to see how many times the 2525 breakpoint was hit, and then run again, ignoring one less than 2526 that number. This will get you quickly to the last hit of that 2527 breakpoint. 2528 2529 GDB allows you to set any number of breakpoints at the same place in 2530 your program. There is nothing silly or meaningless about this. When 2531 the breakpoints are conditional, this is even useful (*note Break 2532 conditions: Conditions.). 2533 2534 If a specified breakpoint location cannot be found, it may be due to 2535 the fact that the location is in a shared library that is yet to be 2536 loaded. In such a case, you may want GDB to create a special 2537 breakpoint (known as a "pending breakpoint") that attempts to resolve 2538 itself in the future when an appropriate shared library gets loaded. 2539 2540 Pending breakpoints are useful to set at the start of your GDB 2541 session for locations that you know will be dynamically loaded later by 2542 the program being debugged. When shared libraries are loaded, a check 2543 is made to see if the load resolves any pending breakpoint locations. 2544 If a pending breakpoint location gets resolved, a regular breakpoint is 2545 created and the original pending breakpoint is removed. 2546 2547 GDB provides some additional commands for controlling pending 2548 breakpoint support: 2549 2550 `set breakpoint pending auto' 2551 This is the default behavior. When GDB cannot find the breakpoint 2552 location, it queries you whether a pending breakpoint should be 2553 created. 2554 2555 `set breakpoint pending on' 2556 This indicates that an unrecognized breakpoint location should 2557 automatically result in a pending breakpoint being created. 2558 2559 `set breakpoint pending off' 2560 This indicates that pending breakpoints are not to be created. Any 2561 unrecognized breakpoint location results in an error. This 2562 setting does not affect any pending breakpoints previously created. 2563 2564 `show breakpoint pending' 2565 Show the current behavior setting for creating pending breakpoints. 2566 2567 Normal breakpoint operations apply to pending breakpoints as well. 2568 You may specify a condition for a pending breakpoint and/or commands to 2569 run when the breakpoint is reached. You can also enable or disable the 2570 pending breakpoint. When you specify a condition for a pending 2571 breakpoint, the parsing of the condition will be deferred until the 2572 point where the pending breakpoint location is resolved. Disabling a 2573 pending breakpoint tells GDB to not attempt to resolve the breakpoint 2574 on any subsequent shared library load. When a pending breakpoint is 2575 re-enabled, GDB checks to see if the location is already resolved. 2576 This is done because any number of shared library loads could have 2577 occurred since the time the breakpoint was disabled and one or more of 2578 these loads could resolve the location. 2579 2580 GDB itself sometimes sets breakpoints in your program for special 2581 purposes, such as proper handling of `longjmp' (in C programs). These 2582 internal breakpoints are assigned negative numbers, starting with `-1'; 2583 `info breakpoints' does not display them. You can see these 2584 breakpoints with the GDB maintenance command `maint info breakpoints' 2585 (*note maint info breakpoints::). 2586 2587 2588 File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints 2589 2590 5.1.2 Setting watchpoints 2591 ------------------------- 2592 2593 You can use a watchpoint to stop execution whenever the value of an 2594 expression changes, without having to predict a particular place where 2595 this may happen. (This is sometimes called a "data breakpoint".) The 2596 expression may be as simple as the value of a single variable, or as 2597 complex as many variables combined by operators. Examples include: 2598 2599 * A reference to the value of a single variable. 2600 2601 * An address cast to an appropriate data type. For example, `*(int 2602 *)0x12345678' will watch a 4-byte region at the specified address 2603 (assuming an `int' occupies 4 bytes). 2604 2605 * An arbitrarily complex expression, such as `a*b + c/d'. The 2606 expression can use any operators valid in the program's native 2607 language (*note Languages::). 2608 2609 Depending on your system, watchpoints may be implemented in software 2610 or hardware. GDB does software watchpointing by single-stepping your 2611 program and testing the variable's value each time, which is hundreds of 2612 times slower than normal execution. (But this may still be worth it, to 2613 catch errors where you have no clue what part of your program is the 2614 culprit.) 2615 2616 On some systems, such as HP-UX, GNU/Linux and most other x86-based 2617 targets, GDB includes support for hardware watchpoints, which do not 2618 slow down the running of your program. 2619 2620 `watch EXPR' 2621 Set a watchpoint for an expression. GDB will break when the 2622 expression EXPR is written into by the program and its value 2623 changes. The simplest (and the most popular) use of this command 2624 is to watch the value of a single variable: 2625 2626 (gdb) watch foo 2627 2628 `rwatch EXPR' 2629 Set a watchpoint that will break when the value of EXPR is read by 2630 the program. 2631 2632 `awatch EXPR' 2633 Set a watchpoint that will break when EXPR is either read from or 2634 written into by the program. 2635 2636 `info watchpoints' 2637 This command prints a list of watchpoints, breakpoints, and 2638 catchpoints; it is the same as `info break' (*note Set Breaks::). 2639 2640 GDB sets a "hardware watchpoint" if possible. Hardware watchpoints 2641 execute very quickly, and the debugger reports a change in value at the 2642 exact instruction where the change occurs. If GDB cannot set a 2643 hardware watchpoint, it sets a software watchpoint, which executes more 2644 slowly and reports the change in value at the next _statement_, not the 2645 instruction, after the change occurs. 2646 2647 You can force GDB to use only software watchpoints with the `set 2648 can-use-hw-watchpoints 0' command. With this variable set to zero, GDB 2649 will never try to use hardware watchpoints, even if the underlying 2650 system supports them. (Note that hardware-assisted watchpoints that 2651 were set _before_ setting `can-use-hw-watchpoints' to zero will still 2652 use the hardware mechanism of watching expressiion values.) 2653 2654 `set can-use-hw-watchpoints' 2655 Set whether or not to use hardware watchpoints. 2656 2657 `show can-use-hw-watchpoints' 2658 Show the current mode of using hardware watchpoints. 2659 2660 For remote targets, you can restrict the number of hardware 2661 watchpoints GDB will use, see *Note set remote 2662 hardware-breakpoint-limit::. 2663 2664 When you issue the `watch' command, GDB reports 2665 2666 Hardware watchpoint NUM: EXPR 2667 2668 if it was able to set a hardware watchpoint. 2669 2670 Currently, the `awatch' and `rwatch' commands can only set hardware 2671 watchpoints, because accesses to data that don't change the value of 2672 the watched expression cannot be detected without examining every 2673 instruction as it is being executed, and GDB does not do that 2674 currently. If GDB finds that it is unable to set a hardware breakpoint 2675 with the `awatch' or `rwatch' command, it will print a message like 2676 this: 2677 2678 Expression cannot be implemented with read/access watchpoint. 2679 2680 Sometimes, GDB cannot set a hardware watchpoint because the data 2681 type of the watched expression is wider than what a hardware watchpoint 2682 on the target machine can handle. For example, some systems can only 2683 watch regions that are up to 4 bytes wide; on such systems you cannot 2684 set hardware watchpoints for an expression that yields a 2685 double-precision floating-point number (which is typically 8 bytes 2686 wide). As a work-around, it might be possible to break the large region 2687 into a series of smaller ones and watch them with separate watchpoints. 2688 2689 If you set too many hardware watchpoints, GDB might be unable to 2690 insert all of them when you resume the execution of your program. 2691 Since the precise number of active watchpoints is unknown until such 2692 time as the program is about to be resumed, GDB might not be able to 2693 warn you about this when you set the watchpoints, and the warning will 2694 be printed only when the program is resumed: 2695 2696 Hardware watchpoint NUM: Could not insert watchpoint 2697 2698 If this happens, delete or disable some of the watchpoints. 2699 2700 Watching complex expressions that reference many variables can also 2701 exhaust the resources available for hardware-assisted watchpoints. 2702 That's because GDB needs to watch every variable in the expression with 2703 separately allocated resources. 2704 2705 The SPARClite DSU will generate traps when a program accesses some 2706 data or instruction address that is assigned to the debug registers. 2707 For the data addresses, DSU facilitates the `watch' command. However 2708 the hardware breakpoint registers can only take two data watchpoints, 2709 and both watchpoints must be the same kind. For example, you can set 2710 two watchpoints with `watch' commands, two with `rwatch' commands, *or* 2711 two with `awatch' commands, but you cannot set one watchpoint with one 2712 command and the other with a different command. GDB will reject the 2713 command if you try to mix watchpoints. Delete or disable unused 2714 watchpoint commands before setting new ones. 2715 2716 If you call a function interactively using `print' or `call', any 2717 watchpoints you have set will be inactive until GDB reaches another 2718 kind of breakpoint or the call completes. 2719 2720 GDB automatically deletes watchpoints that watch local (automatic) 2721 variables, or expressions that involve such variables, when they go out 2722 of scope, that is, when the execution leaves the block in which these 2723 variables were defined. In particular, when the program being debugged 2724 terminates, _all_ local variables go out of scope, and so only 2725 watchpoints that watch global variables remain set. If you rerun the 2726 program, you will need to set all such watchpoints again. One way of 2727 doing that would be to set a code breakpoint at the entry to the `main' 2728 function and when it breaks, set all the watchpoints. 2729 2730 _Warning:_ In multi-thread programs, watchpoints have only limited 2731 usefulness. With the current watchpoint implementation, GDB can 2732 only watch the value of an expression _in a single thread_. If 2733 you are confident that the expression can only change due to the 2734 current thread's activity (and if you are also confident that no 2735 other thread can become current), then you can use watchpoints as 2736 usual. However, GDB may not notice when a non-current thread's 2737 activity changes the expression. 2738 2739 _HP-UX Warning:_ In multi-thread programs, software watchpoints 2740 have only limited usefulness. If GDB creates a software 2741 watchpoint, it can only watch the value of an expression _in a 2742 single thread_. If you are confident that the expression can only 2743 change due to the current thread's activity (and if you are also 2744 confident that no other thread can become current), then you can 2745 use software watchpoints as usual. However, GDB may not notice 2746 when a non-current thread's activity changes the expression. 2747 (Hardware watchpoints, in contrast, watch an expression in all 2748 threads.) 2749 2750 *Note set remote hardware-watchpoint-limit::. 2751 2752 2753 File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints 2754 2755 5.1.3 Setting catchpoints 2756 ------------------------- 2757 2758 You can use "catchpoints" to cause the debugger to stop for certain 2759 kinds of program events, such as C++ exceptions or the loading of a 2760 shared library. Use the `catch' command to set a catchpoint. 2761 2762 `catch EVENT' 2763 Stop when EVENT occurs. EVENT can be any of the following: 2764 `throw' 2765 The throwing of a C++ exception. 2766 2767 `catch' 2768 The catching of a C++ exception. 2769 2770 `exec' 2771 A call to `exec'. This is currently only available for HP-UX. 2772 2773 `fork' 2774 A call to `fork'. This is currently only available for HP-UX. 2775 2776 `vfork' 2777 A call to `vfork'. This is currently only available for 2778 HP-UX. 2779 2780 `load' 2781 `load LIBNAME' 2782 The dynamic loading of any shared library, or the loading of 2783 the library LIBNAME. This is currently only available for 2784 HP-UX. 2785 2786 `unload' 2787 `unload LIBNAME' 2788 The unloading of any dynamically loaded shared library, or 2789 the unloading of the library LIBNAME. This is currently only 2790 available for HP-UX. 2791 2792 `tcatch EVENT' 2793 Set a catchpoint that is enabled only for one stop. The 2794 catchpoint is automatically deleted after the first time the event 2795 is caught. 2796 2797 2798 Use the `info break' command to list the current catchpoints. 2799 2800 There are currently some limitations to C++ exception handling 2801 (`catch throw' and `catch catch') in GDB: 2802 2803 * If you call a function interactively, GDB normally returns control 2804 to you when the function has finished executing. If the call 2805 raises an exception, however, the call may bypass the mechanism 2806 that returns control to you and cause your program either to abort 2807 or to simply continue running until it hits a breakpoint, catches 2808 a signal that GDB is listening for, or exits. This is the case 2809 even if you set a catchpoint for the exception; catchpoints on 2810 exceptions are disabled within interactive calls. 2811 2812 * You cannot raise an exception interactively. 2813 2814 * You cannot install an exception handler interactively. 2815 2816 Sometimes `catch' is not the best way to debug exception handling: 2817 if you need to know exactly where an exception is raised, it is better 2818 to stop _before_ the exception handler is called, since that way you 2819 can see the stack before any unwinding takes place. If you set a 2820 breakpoint in an exception handler instead, it may not be easy to find 2821 out where the exception was raised. 2822 2823 To stop just before an exception handler is called, you need some 2824 knowledge of the implementation. In the case of GNU C++, exceptions are 2825 raised by calling a library function named `__raise_exception' which 2826 has the following ANSI C interface: 2827 2828 /* ADDR is where the exception identifier is stored. 2829 ID is the exception identifier. */ 2830 void __raise_exception (void **addr, void *id); 2831 2832 To make the debugger catch all exceptions before any stack unwinding 2833 takes place, set a breakpoint on `__raise_exception' (*note 2834 Breakpoints; watchpoints; and exceptions: Breakpoints.). 2835 2836 With a conditional breakpoint (*note Break conditions: Conditions.) 2837 that depends on the value of ID, you can stop your program when a 2838 specific exception is raised. You can use multiple conditional 2839 breakpoints to stop your program when any of a number of exceptions are 2840 raised. 2841 2842 2843 File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints 2844 2845 5.1.4 Deleting breakpoints 2846 -------------------------- 2847 2848 It is often necessary to eliminate a breakpoint, watchpoint, or 2849 catchpoint once it has done its job and you no longer want your program 2850 to stop there. This is called "deleting" the breakpoint. A breakpoint 2851 that has been deleted no longer exists; it is forgotten. 2852 2853 With the `clear' command you can delete breakpoints according to 2854 where they are in your program. With the `delete' command you can 2855 delete individual breakpoints, watchpoints, or catchpoints by specifying 2856 their breakpoint numbers. 2857 2858 It is not necessary to delete a breakpoint to proceed past it. GDB 2859 automatically ignores breakpoints on the first instruction to be 2860 executed when you continue execution without changing the execution 2861 address. 2862 2863 `clear' 2864 Delete any breakpoints at the next instruction to be executed in 2865 the selected stack frame (*note Selecting a frame: Selection.). 2866 When the innermost frame is selected, this is a good way to delete 2867 a breakpoint where your program just stopped. 2868 2869 `clear FUNCTION' 2870 `clear FILENAME:FUNCTION' 2871 Delete any breakpoints set at entry to the named FUNCTION. 2872 2873 `clear LINENUM' 2874 `clear FILENAME:LINENUM' 2875 Delete any breakpoints set at or within the code of the specified 2876 LINENUM of the specified FILENAME. 2877 2878 `delete [breakpoints] [RANGE...]' 2879 Delete the breakpoints, watchpoints, or catchpoints of the 2880 breakpoint ranges specified as arguments. If no argument is 2881 specified, delete all breakpoints (GDB asks confirmation, unless 2882 you have `set confirm off'). You can abbreviate this command as 2883 `d'. 2884 2885 2886 File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints 2887 2888 5.1.5 Disabling breakpoints 2889 --------------------------- 2890 2891 Rather than deleting a breakpoint, watchpoint, or catchpoint, you might 2892 prefer to "disable" it. This makes the breakpoint inoperative as if it 2893 had been deleted, but remembers the information on the breakpoint so 2894 that you can "enable" it again later. 2895 2896 You disable and enable breakpoints, watchpoints, and catchpoints with 2897 the `enable' and `disable' commands, optionally specifying one or more 2898 breakpoint numbers as arguments. Use `info break' or `info watch' to 2899 print a list of breakpoints, watchpoints, and catchpoints if you do not 2900 know which numbers to use. 2901 2902 A breakpoint, watchpoint, or catchpoint can have any of four 2903 different states of enablement: 2904 2905 * Enabled. The breakpoint stops your program. A breakpoint set 2906 with the `break' command starts out in this state. 2907 2908 * Disabled. The breakpoint has no effect on your program. 2909 2910 * Enabled once. The breakpoint stops your program, but then becomes 2911 disabled. 2912 2913 * Enabled for deletion. The breakpoint stops your program, but 2914 immediately after it does so it is deleted permanently. A 2915 breakpoint set with the `tbreak' command starts out in this state. 2916 2917 You can use the following commands to enable or disable breakpoints, 2918 watchpoints, and catchpoints: 2919 2920 `disable [breakpoints] [RANGE...]' 2921 Disable the specified breakpoints--or all breakpoints, if none are 2922 listed. A disabled breakpoint has no effect but is not forgotten. 2923 All options such as ignore-counts, conditions and commands are 2924 remembered in case the breakpoint is enabled again later. You may 2925 abbreviate `disable' as `dis'. 2926 2927 `enable [breakpoints] [RANGE...]' 2928 Enable the specified breakpoints (or all defined breakpoints). 2929 They become effective once again in stopping your program. 2930 2931 `enable [breakpoints] once RANGE...' 2932 Enable the specified breakpoints temporarily. GDB disables any of 2933 these breakpoints immediately after stopping your program. 2934 2935 `enable [breakpoints] delete RANGE...' 2936 Enable the specified breakpoints to work once, then die. GDB 2937 deletes any of these breakpoints as soon as your program stops 2938 there. Breakpoints set by the `tbreak' command start out in this 2939 state. 2940 2941 Except for a breakpoint set with `tbreak' (*note Setting 2942 breakpoints: Set Breaks.), breakpoints that you set are initially 2943 enabled; subsequently, they become disabled or enabled only when you 2944 use one of the commands above. (The command `until' can set and delete 2945 a breakpoint of its own, but it does not change the state of your other 2946 breakpoints; see *Note Continuing and stepping: Continuing and 2947 Stepping.) 2948 2949 2950 File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints 2951 2952 5.1.6 Break conditions 2953 ---------------------- 2954 2955 The simplest sort of breakpoint breaks every time your program reaches a 2956 specified place. You can also specify a "condition" for a breakpoint. 2957 A condition is just a Boolean expression in your programming language 2958 (*note Expressions: Expressions.). A breakpoint with a condition 2959 evaluates the expression each time your program reaches it, and your 2960 program stops only if the condition is _true_. 2961 2962 This is the converse of using assertions for program validation; in 2963 that situation, you want to stop when the assertion is violated--that 2964 is, when the condition is false. In C, if you want to test an 2965 assertion expressed by the condition ASSERT, you should set the 2966 condition `! ASSERT' on the appropriate breakpoint. 2967 2968 Conditions are also accepted for watchpoints; you may not need them, 2969 since a watchpoint is inspecting the value of an expression anyhow--but 2970 it might be simpler, say, to just set a watchpoint on a variable name, 2971 and specify a condition that tests whether the new value is an 2972 interesting one. 2973 2974 Break conditions can have side effects, and may even call functions 2975 in your program. This can be useful, for example, to activate functions 2976 that log program progress, or to use your own print functions to format 2977 special data structures. The effects are completely predictable unless 2978 there is another enabled breakpoint at the same address. (In that 2979 case, GDB might see the other breakpoint first and stop your program 2980 without checking the condition of this one.) Note that breakpoint 2981 commands are usually more convenient and flexible than break conditions 2982 for the purpose of performing side effects when a breakpoint is reached 2983 (*note Breakpoint command lists: Break Commands.). 2984 2985 Break conditions can be specified when a breakpoint is set, by using 2986 `if' in the arguments to the `break' command. *Note Setting 2987 breakpoints: Set Breaks. They can also be changed at any time with the 2988 `condition' command. 2989 2990 You can also use the `if' keyword with the `watch' command. The 2991 `catch' command does not recognize the `if' keyword; `condition' is the 2992 only way to impose a further condition on a catchpoint. 2993 2994 `condition BNUM EXPRESSION' 2995 Specify EXPRESSION as the break condition for breakpoint, 2996 watchpoint, or catchpoint number BNUM. After you set a condition, 2997 breakpoint BNUM stops your program only if the value of EXPRESSION 2998 is true (nonzero, in C). When you use `condition', GDB checks 2999 EXPRESSION immediately for syntactic correctness, and to determine 3000 whether symbols in it have referents in the context of your 3001 breakpoint. If EXPRESSION uses symbols not referenced in the 3002 context of the breakpoint, GDB prints an error message: 3003 3004 No symbol "foo" in current context. 3005 3006 GDB does not actually evaluate EXPRESSION at the time the 3007 `condition' command (or a command that sets a breakpoint with a 3008 condition, like `break if ...') is given, however. *Note 3009 Expressions: Expressions. 3010 3011 `condition BNUM' 3012 Remove the condition from breakpoint number BNUM. It becomes an 3013 ordinary unconditional breakpoint. 3014 3015 A special case of a breakpoint condition is to stop only when the 3016 breakpoint has been reached a certain number of times. This is so 3017 useful that there is a special way to do it, using the "ignore count" 3018 of the breakpoint. Every breakpoint has an ignore count, which is an 3019 integer. Most of the time, the ignore count is zero, and therefore has 3020 no effect. But if your program reaches a breakpoint whose ignore count 3021 is positive, then instead of stopping, it just decrements the ignore 3022 count by one and continues. As a result, if the ignore count value is 3023 N, the breakpoint does not stop the next N times your program reaches 3024 it. 3025 3026 `ignore BNUM COUNT' 3027 Set the ignore count of breakpoint number BNUM to COUNT. The next 3028 COUNT times the breakpoint is reached, your program's execution 3029 does not stop; other than to decrement the ignore count, GDB takes 3030 no action. 3031 3032 To make the breakpoint stop the next time it is reached, specify a 3033 count of zero. 3034 3035 When you use `continue' to resume execution of your program from a 3036 breakpoint, you can specify an ignore count directly as an 3037 argument to `continue', rather than using `ignore'. *Note 3038 Continuing and stepping: Continuing and Stepping. 3039 3040 If a breakpoint has a positive ignore count and a condition, the 3041 condition is not checked. Once the ignore count reaches zero, GDB 3042 resumes checking the condition. 3043 3044 You could achieve the effect of the ignore count with a condition 3045 such as `$foo-- <= 0' using a debugger convenience variable that 3046 is decremented each time. *Note Convenience variables: 3047 Convenience Vars. 3048 3049 Ignore counts apply to breakpoints, watchpoints, and catchpoints. 3050 3051 3052 File: gdb.info, Node: Break Commands, Next: Breakpoint Menus, Prev: Conditions, Up: Breakpoints 3053 3054 5.1.7 Breakpoint command lists 3055 ------------------------------ 3056 3057 You can give any breakpoint (or watchpoint or catchpoint) a series of 3058 commands to execute when your program stops due to that breakpoint. For 3059 example, you might want to print the values of certain expressions, or 3060 enable other breakpoints. 3061 3062 `commands [BNUM]' 3063 `... COMMAND-LIST ...' 3064 `end' 3065 Specify a list of commands for breakpoint number BNUM. The 3066 commands themselves appear on the following lines. Type a line 3067 containing just `end' to terminate the commands. 3068 3069 To remove all commands from a breakpoint, type `commands' and 3070 follow it immediately with `end'; that is, give no commands. 3071 3072 With no BNUM argument, `commands' refers to the last breakpoint, 3073 watchpoint, or catchpoint set (not to the breakpoint most recently 3074 encountered). 3075 3076 Pressing <RET> as a means of repeating the last GDB command is 3077 disabled within a COMMAND-LIST. 3078 3079 You can use breakpoint commands to start your program up again. 3080 Simply use the `continue' command, or `step', or any other command that 3081 resumes execution. 3082 3083 Any other commands in the command list, after a command that resumes 3084 execution, are ignored. This is because any time you resume execution 3085 (even with a simple `next' or `step'), you may encounter another 3086 breakpoint--which could have its own command list, leading to 3087 ambiguities about which list to execute. 3088 3089 If the first command you specify in a command list is `silent', the 3090 usual message about stopping at a breakpoint is not printed. This may 3091 be desirable for breakpoints that are to print a specific message and 3092 then continue. If none of the remaining commands print anything, you 3093 see no sign that the breakpoint was reached. `silent' is meaningful 3094 only at the beginning of a breakpoint command list. 3095 3096 The commands `echo', `output', and `printf' allow you to print 3097 precisely controlled output, and are often useful in silent 3098 breakpoints. *Note Commands for controlled output: Output. 3099 3100 For example, here is how you could use breakpoint commands to print 3101 the value of `x' at entry to `foo' whenever `x' is positive. 3102 3103 break foo if x>0 3104 commands 3105 silent 3106 printf "x is %d\n",x 3107 cont 3108 end 3109 3110 One application for breakpoint commands is to compensate for one bug 3111 so you can test for another. Put a breakpoint just after the erroneous 3112 line of code, give it a condition to detect the case in which something 3113 erroneous has been done, and give it commands to assign correct values 3114 to any variables that need them. End with the `continue' command so 3115 that your program does not stop, and start with the `silent' command so 3116 that no output is produced. Here is an example: 3117 3118 break 403 3119 commands 3120 silent 3121 set x = y + 4 3122 cont 3123 end 3124 3125 3126 File: gdb.info, Node: Breakpoint Menus, Next: Error in Breakpoints, Prev: Break Commands, Up: Breakpoints 3127 3128 5.1.8 Breakpoint menus 3129 ---------------------- 3130 3131 Some programming languages (notably C++ and Objective-C) permit a 3132 single function name to be defined several times, for application in 3133 different contexts. This is called "overloading". When a function 3134 name is overloaded, `break FUNCTION' is not enough to tell GDB where 3135 you want a breakpoint. If you realize this is a problem, you can use 3136 something like `break FUNCTION(TYPES)' to specify which particular 3137 version of the function you want. Otherwise, GDB offers you a menu of 3138 numbered choices for different possible breakpoints, and waits for your 3139 selection with the prompt `>'. The first two options are always `[0] 3140 cancel' and `[1] all'. Typing `1' sets a breakpoint at each definition 3141 of FUNCTION, and typing `0' aborts the `break' command without setting 3142 any new breakpoints. 3143 3144 For example, the following session excerpt shows an attempt to set a 3145 breakpoint at the overloaded symbol `String::after'. We choose three 3146 particular definitions of that function name: 3147 3148 (gdb) b String::after 3149 [0] cancel 3150 [1] all 3151 [2] file:String.cc; line number:867 3152 [3] file:String.cc; line number:860 3153 [4] file:String.cc; line number:875 3154 [5] file:String.cc; line number:853 3155 [6] file:String.cc; line number:846 3156 [7] file:String.cc; line number:735 3157 > 2 4 6 3158 Breakpoint 1 at 0xb26c: file String.cc, line 867. 3159 Breakpoint 2 at 0xb344: file String.cc, line 875. 3160 Breakpoint 3 at 0xafcc: file String.cc, line 846. 3161 Multiple breakpoints were set. 3162 Use the "delete" command to delete unwanted 3163 breakpoints. 3164 (gdb) 3165 3166 3167 File: gdb.info, Node: Error in Breakpoints, Next: Breakpoint related warnings, Prev: Breakpoint Menus, Up: Breakpoints 3168 3169 5.1.9 "Cannot insert breakpoints" 3170 --------------------------------- 3171 3172 Under some operating systems, breakpoints cannot be used in a program if 3173 any other process is running that program. In this situation, 3174 attempting to run or continue a program with a breakpoint causes GDB to 3175 print an error message: 3176 3177 Cannot insert breakpoints. 3178 The same program may be running in another process. 3179 3180 When this happens, you have three ways to proceed: 3181 3182 1. Remove or disable the breakpoints, then continue. 3183 3184 2. Suspend GDB, and copy the file containing your program to a new 3185 name. Resume GDB and use the `exec-file' command to specify that 3186 GDB should run your program under that name. Then start your 3187 program again. 3188 3189 3. Relink your program so that the text segment is nonsharable, using 3190 the linker option `-N'. The operating system limitation may not 3191 apply to nonsharable executables. 3192 3193 A similar message can be printed if you request too many active 3194 hardware-assisted breakpoints and watchpoints: 3195 3196 Stopped; cannot insert breakpoints. 3197 You may have requested too many hardware breakpoints and watchpoints. 3198 3199 This message is printed when you attempt to resume the program, since 3200 only then GDB knows exactly how many hardware breakpoints and 3201 watchpoints it needs to insert. 3202 3203 When this message is printed, you need to disable or remove some of 3204 the hardware-assisted breakpoints and watchpoints, and then continue. 3205 3206 3207 File: gdb.info, Node: Breakpoint related warnings, Prev: Error in Breakpoints, Up: Breakpoints 3208 3209 5.1.10 "Breakpoint address adjusted..." 3210 --------------------------------------- 3211 3212 Some processor architectures place constraints on the addresses at 3213 which breakpoints may be placed. For architectures thus constrained, 3214 GDB will attempt to adjust the breakpoint's address to comply with the 3215 constraints dictated by the architecture. 3216 3217 One example of such an architecture is the Fujitsu FR-V. The FR-V is 3218 a VLIW architecture in which a number of RISC-like instructions may be 3219 bun