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