1\input texinfo @c -*-texinfo-*- 2@c Copyright (C) 1988--2021 Free Software Foundation, Inc. 3@c 4@c %**start of header 5@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use 6@c of @set vars. However, you can override filename with makeinfo -o. 7@setfilename gdb.info 8@c 9@c man begin INCLUDE 10@include gdb-cfg.texi 11@c man end 12@c 13@settitle Debugging with @value{GDBN} 14@setchapternewpage odd 15@c %**end of header 16 17@iftex 18@c @smallbook 19@c @cropmarks 20@end iftex 21 22@finalout 23@c To avoid file-name clashes between index.html and Index.html, when 24@c the manual is produced on a Posix host and then moved to a 25@c case-insensitive filesystem (e.g., MS-Windows), we separate the 26@c indices into two: Concept Index and all the rest. 27@syncodeindex ky fn 28@syncodeindex tp fn 29 30@c readline appendices use @vindex, @findex and @ftable, 31@c annotate.texi and gdbmi use @findex. 32@syncodeindex vr fn 33 34@c !!set GDB manual's edition---not the same as GDB version! 35@c This is updated by GNU Press. 36@set EDITION Tenth 37 38@c !!set GDB edit command default editor 39@set EDITOR /bin/ex 40 41@c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER. 42 43@c This is a dir.info fragment to support semi-automated addition of 44@c manuals to an info tree. 45@dircategory Software development 46@direntry 47* Gdb: (gdb). The GNU debugger. 48* gdbserver: (gdb) Server. The GNU debugging server. 49@end direntry 50 51@copying 52@c man begin COPYRIGHT 53Copyright @copyright{} 1988-2021 Free Software Foundation, Inc. 54 55Permission is granted to copy, distribute and/or modify this document 56under the terms of the GNU Free Documentation License, Version 1.3 or 57any later version published by the Free Software Foundation; with the 58Invariant Sections being ``Free Software'' and ``Free Software Needs 59Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 60and with the Back-Cover Texts as in (a) below. 61 62(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 63this GNU Manual. Buying copies from GNU Press supports the FSF in 64developing GNU and promoting software freedom.'' 65@c man end 66@end copying 67 68@ifnottex 69This file documents the @sc{gnu} debugger @value{GDBN}. 70 71This is the @value{EDITION} Edition, of @cite{Debugging with 72@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN} 73@ifset VERSION_PACKAGE 74@value{VERSION_PACKAGE} 75@end ifset 76Version @value{GDBVN}. 77 78@insertcopying 79@end ifnottex 80 81@titlepage 82@title Debugging with @value{GDBN} 83@subtitle The @sc{gnu} Source-Level Debugger 84@sp 1 85@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN} 86@ifset VERSION_PACKAGE 87@sp 1 88@subtitle @value{VERSION_PACKAGE} 89@end ifset 90@author Richard Stallman, Roland Pesch, Stan Shebs, et al. 91@page 92@tex 93{\parskip=0pt 94\hfill (Send bugs and comments on @value{GDBN} to @value{BUGURL}.)\par 95\hfill {\it Debugging with @value{GDBN}}\par 96\hfill \TeX{}info \texinfoversion\par 97} 98@end tex 99 100@vskip 0pt plus 1filll 101Published by the Free Software Foundation @* 10251 Franklin Street, Fifth Floor, 103Boston, MA 02110-1301, USA@* 104ISBN 978-0-9831592-3-0 @* 105 106@insertcopying 107@end titlepage 108@page 109 110@ifnottex 111@node Top, Summary 112 113@top Debugging with @value{GDBN} 114 115This file describes @value{GDBN}, the @sc{gnu} symbolic debugger. 116 117This is the @value{EDITION} Edition, for @value{GDBN} 118@ifset VERSION_PACKAGE 119@value{VERSION_PACKAGE} 120@end ifset 121Version @value{GDBVN}. 122 123Copyright (C) 1988-2021 Free Software Foundation, Inc. 124 125This edition of the GDB manual is dedicated to the memory of Fred 126Fish. Fred was a long-standing contributor to GDB and to Free 127software in general. We will miss him. 128 129@menu 130* Summary:: Summary of @value{GDBN} 131* Sample Session:: A sample @value{GDBN} session 132 133* Invocation:: Getting in and out of @value{GDBN} 134* Commands:: @value{GDBN} commands 135* Running:: Running programs under @value{GDBN} 136* Stopping:: Stopping and continuing 137* Reverse Execution:: Running programs backward 138* Process Record and Replay:: Recording inferior's execution and replaying it 139* Stack:: Examining the stack 140* Source:: Examining source files 141* Data:: Examining data 142* Optimized Code:: Debugging optimized code 143* Macros:: Preprocessor Macros 144* Tracepoints:: Debugging remote targets non-intrusively 145* Overlays:: Debugging programs that use overlays 146 147* Languages:: Using @value{GDBN} with different languages 148 149* Symbols:: Examining the symbol table 150* Altering:: Altering execution 151* GDB Files:: @value{GDBN} files 152* Targets:: Specifying a debugging target 153* Remote Debugging:: Debugging remote programs 154* Configurations:: Configuration-specific information 155* Controlling GDB:: Controlling @value{GDBN} 156* Extending GDB:: Extending @value{GDBN} 157* Interpreters:: Command Interpreters 158* TUI:: @value{GDBN} Text User Interface 159* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs 160* GDB/MI:: @value{GDBN}'s Machine Interface. 161* Annotations:: @value{GDBN}'s annotation interface. 162* JIT Interface:: Using the JIT debugging interface. 163* In-Process Agent:: In-Process Agent 164 165* GDB Bugs:: Reporting bugs in @value{GDBN} 166 167@ifset SYSTEM_READLINE 168* Command Line Editing: (rluserman). Command Line Editing 169* Using History Interactively: (history). Using History Interactively 170@end ifset 171@ifclear SYSTEM_READLINE 172* Command Line Editing:: Command Line Editing 173* Using History Interactively:: Using History Interactively 174@end ifclear 175* In Memoriam:: In Memoriam 176* Formatting Documentation:: How to format and print @value{GDBN} documentation 177* Installing GDB:: Installing GDB 178* Maintenance Commands:: Maintenance Commands 179* Remote Protocol:: GDB Remote Serial Protocol 180* Agent Expressions:: The GDB Agent Expression Mechanism 181* Target Descriptions:: How targets can describe themselves to 182 @value{GDBN} 183* Operating System Information:: Getting additional information from 184 the operating system 185* Trace File Format:: GDB trace file format 186* Index Section Format:: .gdb_index section format 187* Man Pages:: Manual pages 188* Copying:: GNU General Public License says 189 how you can copy and share GDB 190* GNU Free Documentation License:: The license for this documentation 191* Concept Index:: Index of @value{GDBN} concepts 192* Command and Variable Index:: Index of @value{GDBN} commands, variables, 193 functions, and Python data types 194@end menu 195 196@end ifnottex 197 198@contents 199 200@node Summary 201@unnumbered Summary of @value{GDBN} 202 203The purpose of a debugger such as @value{GDBN} is to allow you to see what is 204going on ``inside'' another program while it executes---or what another 205program was doing at the moment it crashed. 206 207@value{GDBN} can do four main kinds of things (plus other things in support of 208these) to help you catch bugs in the act: 209 210@itemize @bullet 211@item 212Start your program, specifying anything that might affect its behavior. 213 214@item 215Make your program stop on specified conditions. 216 217@item 218Examine what has happened, when your program has stopped. 219 220@item 221Change things in your program, so you can experiment with correcting the 222effects of one bug and go on to learn about another. 223@end itemize 224 225You can use @value{GDBN} to debug programs written in C and C@t{++}. 226For more information, see @ref{Supported Languages,,Supported Languages}. 227For more information, see @ref{C,,C and C++}. 228 229Support for D is partial. For information on D, see 230@ref{D,,D}. 231 232@cindex Modula-2 233Support for Modula-2 is partial. For information on Modula-2, see 234@ref{Modula-2,,Modula-2}. 235 236Support for OpenCL C is partial. For information on OpenCL C, see 237@ref{OpenCL C,,OpenCL C}. 238 239@cindex Pascal 240Debugging Pascal programs which use sets, subranges, file variables, or 241nested functions does not currently work. @value{GDBN} does not support 242entering expressions, printing values, or similar features using Pascal 243syntax. 244 245@cindex Fortran 246@value{GDBN} can be used to debug programs written in Fortran, although 247it may be necessary to refer to some variables with a trailing 248underscore. 249 250@value{GDBN} can be used to debug programs written in Objective-C, 251using either the Apple/NeXT or the GNU Objective-C runtime. 252 253@menu 254* Free Software:: Freely redistributable software 255* Free Documentation:: Free Software Needs Free Documentation 256* Contributors:: Contributors to GDB 257@end menu 258 259@node Free Software 260@unnumberedsec Free Software 261 262@value{GDBN} is @dfn{free software}, protected by the @sc{gnu} 263General Public License 264(GPL). The GPL gives you the freedom to copy or adapt a licensed 265program---but every person getting a copy also gets with it the 266freedom to modify that copy (which means that they must get access to 267the source code), and the freedom to distribute further copies. 268Typical software companies use copyrights to limit your freedoms; the 269Free Software Foundation uses the GPL to preserve these freedoms. 270 271Fundamentally, the General Public License is a license which says that 272you have these freedoms and that you cannot take these freedoms away 273from anyone else. 274 275@node Free Documentation 276@unnumberedsec Free Software Needs Free Documentation 277 278The biggest deficiency in the free software community today is not in 279the software---it is the lack of good free documentation that we can 280include with the free software. Many of our most important 281programs do not come with free reference manuals and free introductory 282texts. Documentation is an essential part of any software package; 283when an important free software package does not come with a free 284manual and a free tutorial, that is a major gap. We have many such 285gaps today. 286 287Consider Perl, for instance. The tutorial manuals that people 288normally use are non-free. How did this come about? Because the 289authors of those manuals published them with restrictive terms---no 290copying, no modification, source files not available---which exclude 291them from the free software world. 292 293That wasn't the first time this sort of thing happened, and it was far 294from the last. Many times we have heard a GNU user eagerly describe a 295manual that he is writing, his intended contribution to the community, 296only to learn that he had ruined everything by signing a publication 297contract to make it non-free. 298 299Free documentation, like free software, is a matter of freedom, not 300price. The problem with the non-free manual is not that publishers 301charge a price for printed copies---that in itself is fine. (The Free 302Software Foundation sells printed copies of manuals, too.) The 303problem is the restrictions on the use of the manual. Free manuals 304are available in source code form, and give you permission to copy and 305modify. Non-free manuals do not allow this. 306 307The criteria of freedom for a free manual are roughly the same as for 308free software. Redistribution (including the normal kinds of 309commercial redistribution) must be permitted, so that the manual can 310accompany every copy of the program, both on-line and on paper. 311 312Permission for modification of the technical content is crucial too. 313When people modify the software, adding or changing features, if they 314are conscientious they will change the manual too---so they can 315provide accurate and clear documentation for the modified program. A 316manual that leaves you no choice but to write a new manual to document 317a changed version of the program is not really available to our 318community. 319 320Some kinds of limits on the way modification is handled are 321acceptable. For example, requirements to preserve the original 322author's copyright notice, the distribution terms, or the list of 323authors, are ok. It is also no problem to require modified versions 324to include notice that they were modified. Even entire sections that 325may not be deleted or changed are acceptable, as long as they deal 326with nontechnical topics (like this one). These kinds of restrictions 327are acceptable because they don't obstruct the community's normal use 328of the manual. 329 330However, it must be possible to modify all the @emph{technical} 331content of the manual, and then distribute the result in all the usual 332media, through all the usual channels. Otherwise, the restrictions 333obstruct the use of the manual, it is not free, and we need another 334manual to replace it. 335 336Please spread the word about this issue. Our community continues to 337lose manuals to proprietary publishing. If we spread the word that 338free software needs free reference manuals and free tutorials, perhaps 339the next person who wants to contribute by writing documentation will 340realize, before it is too late, that only free manuals contribute to 341the free software community. 342 343If you are writing documentation, please insist on publishing it under 344the GNU Free Documentation License or another free documentation 345license. Remember that this decision requires your approval---you 346don't have to let the publisher decide. Some commercial publishers 347will use a free license if you insist, but they will not propose the 348option; it is up to you to raise the issue and say firmly that this is 349what you want. If the publisher you are dealing with refuses, please 350try other publishers. If you're not sure whether a proposed license 351is free, write to @email{licensing@@gnu.org}. 352 353You can encourage commercial publishers to sell more free, copylefted 354manuals and tutorials by buying them, and particularly by buying 355copies from the publishers that paid for their writing or for major 356improvements. Meanwhile, try to avoid buying non-free documentation 357at all. Check the distribution terms of a manual before you buy it, 358and insist that whoever seeks your business must respect your freedom. 359Check the history of the book, and try to reward the publishers that 360have paid or pay the authors to work on it. 361 362The Free Software Foundation maintains a list of free documentation 363published by other publishers, at 364@url{http://www.fsf.org/doc/other-free-books.html}. 365 366@node Contributors 367@unnumberedsec Contributors to @value{GDBN} 368 369Richard Stallman was the original author of @value{GDBN}, and of many 370other @sc{gnu} programs. Many others have contributed to its 371development. This section attempts to credit major contributors. One 372of the virtues of free software is that everyone is free to contribute 373to it; with regret, we cannot actually acknowledge everyone here. The 374file @file{ChangeLog} in the @value{GDBN} distribution approximates a 375blow-by-blow account. 376 377Changes much prior to version 2.0 are lost in the mists of time. 378 379@quotation 380@emph{Plea:} Additions to this section are particularly welcome. If you 381or your friends (or enemies, to be evenhanded) have been unfairly 382omitted from this list, we would like to add your names! 383@end quotation 384 385So that they may not regard their many labors as thankless, we 386particularly thank those who shepherded @value{GDBN} through major 387releases: 388Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); 389Jim Blandy (release 4.18); 390Jason Molenda (release 4.17); 391Stan Shebs (release 4.14); 392Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9); 393Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4); 394John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); 395Jim Kingdon (releases 3.5, 3.4, and 3.3); 396and Randy Smith (releases 3.2, 3.1, and 3.0). 397 398Richard Stallman, assisted at various times by Peter TerMaat, Chris 399Hanson, and Richard Mlynarik, handled releases through 2.8. 400 401Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support 402in @value{GDBN}, with significant additional contributions from Per 403Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++} 404demangler. Early work on C@t{++} was by Peter TerMaat (who also did 405much general update work leading to release 3.0). 406 407@value{GDBN} uses the BFD subroutine library to examine multiple 408object-file formats; BFD was a joint project of David V. 409Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore. 410 411David Johnson wrote the original COFF support; Pace Willison did 412the original support for encapsulated COFF. 413 414Brent Benson of Harris Computer Systems contributed DWARF 2 support. 415 416Adam de Boor and Bradley Davis contributed the ISI Optimum V support. 417Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS 418support. 419Jean-Daniel Fekete contributed Sun 386i support. 420Chris Hanson improved the HP9000 support. 421Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support. 422David Johnson contributed Encore Umax support. 423Jyrki Kuoppala contributed Altos 3068 support. 424Jeff Law contributed HP PA and SOM support. 425Keith Packard contributed NS32K support. 426Doug Rabson contributed Acorn Risc Machine support. 427Bob Rusk contributed Harris Nighthawk CX-UX support. 428Chris Smith contributed Convex support (and Fortran debugging). 429Jonathan Stone contributed Pyramid support. 430Michael Tiemann contributed SPARC support. 431Tim Tucker contributed support for the Gould NP1 and Gould Powernode. 432Pace Willison contributed Intel 386 support. 433Jay Vosburgh contributed Symmetry support. 434Marko Mlinar contributed OpenRISC 1000 support. 435 436Andreas Schwab contributed M68K @sc{gnu}/Linux support. 437 438Rich Schaefer and Peter Schauer helped with support of SunOS shared 439libraries. 440 441Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree 442about several machine instruction sets. 443 444Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop 445remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM 446contributed remote debugging modules for the i960, VxWorks, A29K UDI, 447and RDI targets, respectively. 448 449Brian Fox is the author of the readline libraries providing 450command-line editing and command history. 451 452Andrew Beers of SUNY Buffalo wrote the language-switching code, the 453Modula-2 support, and contributed the Languages chapter of this manual. 454 455Fred Fish wrote most of the support for Unix System Vr4. 456He also enhanced the command-completion support to cover C@t{++} overloaded 457symbols. 458 459Hitachi America (now Renesas America), Ltd. sponsored the support for 460H8/300, H8/500, and Super-H processors. 461 462NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors. 463 464Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D 465processors. 466 467Toshiba sponsored the support for the TX39 Mips processor. 468 469Matsushita sponsored the support for the MN10200 and MN10300 processors. 470 471Fujitsu sponsored the support for SPARClite and FR30 processors. 472 473Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware 474watchpoints. 475 476Michael Snyder added support for tracepoints. 477 478Stu Grossman wrote gdbserver. 479 480Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made 481nearly innumerable bug fixes and cleanups throughout @value{GDBN}. 482 483The following people at the Hewlett-Packard Company contributed 484support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 485(narrow mode), HP's implementation of kernel threads, HP's aC@t{++} 486compiler, and the Text User Interface (nee Terminal User Interface): 487Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, 488Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase 489provided HP-specific information in this manual. 490 491DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project. 492Robert Hoehne made significant contributions to the DJGPP port. 493 494Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its 495development since 1991. Cygnus engineers who have worked on @value{GDBN} 496fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin 497Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim 498Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, 499Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek 500Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In 501addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, 502JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug 503Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff 504Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, 505Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin 506Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela 507Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David 508Zuhn have made contributions both large and small. 509 510Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for 511Cygnus Solutions, implemented the original @sc{gdb/mi} interface. 512 513Jim Blandy added support for preprocessor macros, while working for Red 514Hat. 515 516Andrew Cagney designed @value{GDBN}'s architecture vector. Many 517people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick 518Duffek, Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei 519Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason 520Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped 521with the migration of old architectures to this new framework. 522 523Andrew Cagney completely re-designed and re-implemented @value{GDBN}'s 524unwinder framework, this consisting of a fresh new design featuring 525frame IDs, independent frame sniffers, and the sentinel frame. Mark 526Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the 527libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and 528trad unwinders. The architecture-specific changes, each involving a 529complete rewrite of the architecture's frame code, were carried out by 530Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane 531Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel 532Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei 533Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich 534Weigand. 535 536Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from 537Tensilica, Inc.@: contributed support for Xtensa processors. Others 538who have worked on the Xtensa port of @value{GDBN} in the past include 539Steve Tjiang, John Newlin, and Scott Foehner. 540 541Michael Eager and staff of Xilinx, Inc., contributed support for the 542Xilinx MicroBlaze architecture. 543 544Initial support for the FreeBSD/mips target and native configuration 545was developed by SRI International and the University of Cambridge 546Computer Laboratory under DARPA/AFRL contract FA8750-10-C-0237 547("CTSRD"), as part of the DARPA CRASH research programme. 548 549Initial support for the FreeBSD/riscv target and native configuration 550was developed by SRI International and the University of Cambridge 551Computer Laboratory (Department of Computer Science and Technology) 552under DARPA contract HR0011-18-C-0016 ("ECATS"), as part of the DARPA 553SSITH research programme. 554 555The original port to the OpenRISC 1000 is believed to be due to 556Alessandro Forin and Per Bothner. More recent ports have been the work 557of Jeremy Bennett, Franck Jullien, Stefan Wallentowitz and 558Stafford Horne. 559 560Weimin Pan, David Faust and Jose E. Marchesi contributed support for 561the Linux kernel BPF virtual architecture. This work was sponsored by 562Oracle. 563 564@node Sample Session 565@chapter A Sample @value{GDBN} Session 566 567You can use this manual at your leisure to read all about @value{GDBN}. 568However, a handful of commands are enough to get started using the 569debugger. This chapter illustrates those commands. 570 571@iftex 572In this sample session, we emphasize user input like this: @b{input}, 573to make it easier to pick out from the surrounding output. 574@end iftex 575 576@c FIXME: this example may not be appropriate for some configs, where 577@c FIXME...primary interest is in remote use. 578 579One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro 580processor) exhibits the following bug: sometimes, when we change its 581quote strings from the default, the commands used to capture one macro 582definition within another stop working. In the following short @code{m4} 583session, we define a macro @code{foo} which expands to @code{0000}; we 584then use the @code{m4} built-in @code{defn} to define @code{bar} as the 585same thing. However, when we change the open quote string to 586@code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same 587procedure fails to define a new synonym @code{baz}: 588 589@smallexample 590$ @b{cd gnu/m4} 591$ @b{./m4} 592@b{define(foo,0000)} 593 594@b{foo} 5950000 596@b{define(bar,defn(`foo'))} 597 598@b{bar} 5990000 600@b{changequote(<QUOTE>,<UNQUOTE>)} 601 602@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))} 603@b{baz} 604@b{Ctrl-d} 605m4: End of input: 0: fatal error: EOF in string 606@end smallexample 607 608@noindent 609Let us use @value{GDBN} to try to see what is going on. 610 611@smallexample 612$ @b{@value{GDBP} m4} 613@c FIXME: this falsifies the exact text played out, to permit smallbook 614@c FIXME... format to come out better. 615@value{GDBN} is free software and you are welcome to distribute copies 616 of it under certain conditions; type "show copying" to see 617 the conditions. 618There is absolutely no warranty for @value{GDBN}; type "show warranty" 619 for details. 620 621@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc... 622(@value{GDBP}) 623@end smallexample 624 625@noindent 626@value{GDBN} reads only enough symbol data to know where to find the 627rest when needed; as a result, the first prompt comes up very quickly. 628We now tell @value{GDBN} to use a narrower display width than usual, so 629that examples fit in this manual. 630 631@smallexample 632(@value{GDBP}) @b{set width 70} 633@end smallexample 634 635@noindent 636We need to see how the @code{m4} built-in @code{changequote} works. 637Having looked at the source, we know the relevant subroutine is 638@code{m4_changequote}, so we set a breakpoint there with the @value{GDBN} 639@code{break} command. 640 641@smallexample 642(@value{GDBP}) @b{break m4_changequote} 643Breakpoint 1 at 0x62f4: file builtin.c, line 879. 644@end smallexample 645 646@noindent 647Using the @code{run} command, we start @code{m4} running under @value{GDBN} 648control; as long as control does not reach the @code{m4_changequote} 649subroutine, the program runs as usual: 650 651@smallexample 652(@value{GDBP}) @b{run} 653Starting program: /work/Editorial/gdb/gnu/m4/m4 654@b{define(foo,0000)} 655 656@b{foo} 6570000 658@end smallexample 659 660@noindent 661To trigger the breakpoint, we call @code{changequote}. @value{GDBN} 662suspends execution of @code{m4}, displaying information about the 663context where it stops. 664 665@smallexample 666@b{changequote(<QUOTE>,<UNQUOTE>)} 667 668Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) 669 at builtin.c:879 670879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) 671@end smallexample 672 673@noindent 674Now we use the command @code{n} (@code{next}) to advance execution to 675the next line of the current function. 676 677@smallexample 678(@value{GDBP}) @b{n} 679882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ 680 : nil, 681@end smallexample 682 683@noindent 684@code{set_quotes} looks like a promising subroutine. We can go into it 685by using the command @code{s} (@code{step}) instead of @code{next}. 686@code{step} goes to the next line to be executed in @emph{any} 687subroutine, so it steps into @code{set_quotes}. 688 689@smallexample 690(@value{GDBP}) @b{s} 691set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 692 at input.c:530 693530 if (lquote != def_lquote) 694@end smallexample 695 696@noindent 697The display that shows the subroutine where @code{m4} is now 698suspended (and its arguments) is called a stack frame display. It 699shows a summary of the stack. We can use the @code{backtrace} 700command (which can also be spelled @code{bt}), to see where we are 701in the stack as a whole: the @code{backtrace} command displays a 702stack frame for each active subroutine. 703 704@smallexample 705(@value{GDBP}) @b{bt} 706#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 707 at input.c:530 708#1 0x6344 in m4_changequote (argc=3, argv=0x33c70) 709 at builtin.c:882 710#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 711#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) 712 at macro.c:71 713#4 0x79dc in expand_input () at macro.c:40 714#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 715@end smallexample 716 717@noindent 718We step through a few more lines to see what happens. The first two 719times, we can use @samp{s}; the next two times we use @code{n} to avoid 720falling into the @code{xstrdup} subroutine. 721 722@smallexample 723(@value{GDBP}) @b{s} 7240x3b5c 532 if (rquote != def_rquote) 725(@value{GDBP}) @b{s} 7260x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ 727def_lquote : xstrdup(lq); 728(@value{GDBP}) @b{n} 729536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 730 : xstrdup(rq); 731(@value{GDBP}) @b{n} 732538 len_lquote = strlen(rquote); 733@end smallexample 734 735@noindent 736The last line displayed looks a little odd; we can examine the variables 737@code{lquote} and @code{rquote} to see if they are in fact the new left 738and right quotes we specified. We use the command @code{p} 739(@code{print}) to see their values. 740 741@smallexample 742(@value{GDBP}) @b{p lquote} 743$1 = 0x35d40 "<QUOTE>" 744(@value{GDBP}) @b{p rquote} 745$2 = 0x35d50 "<UNQUOTE>" 746@end smallexample 747 748@noindent 749@code{lquote} and @code{rquote} are indeed the new left and right quotes. 750To look at some context, we can display ten lines of source 751surrounding the current line with the @code{l} (@code{list}) command. 752 753@smallexample 754(@value{GDBP}) @b{l} 755533 xfree(rquote); 756534 757535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ 758 : xstrdup (lq); 759536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 760 : xstrdup (rq); 761537 762538 len_lquote = strlen(rquote); 763539 len_rquote = strlen(lquote); 764540 @} 765541 766542 void 767@end smallexample 768 769@noindent 770Let us step past the two lines that set @code{len_lquote} and 771@code{len_rquote}, and then examine the values of those variables. 772 773@smallexample 774(@value{GDBP}) @b{n} 775539 len_rquote = strlen(lquote); 776(@value{GDBP}) @b{n} 777540 @} 778(@value{GDBP}) @b{p len_lquote} 779$3 = 9 780(@value{GDBP}) @b{p len_rquote} 781$4 = 7 782@end smallexample 783 784@noindent 785That certainly looks wrong, assuming @code{len_lquote} and 786@code{len_rquote} are meant to be the lengths of @code{lquote} and 787@code{rquote} respectively. We can set them to better values using 788the @code{p} command, since it can print the value of 789any expression---and that expression can include subroutine calls and 790assignments. 791 792@smallexample 793(@value{GDBP}) @b{p len_lquote=strlen(lquote)} 794$5 = 7 795(@value{GDBP}) @b{p len_rquote=strlen(rquote)} 796$6 = 9 797@end smallexample 798 799@noindent 800Is that enough to fix the problem of using the new quotes with the 801@code{m4} built-in @code{defn}? We can allow @code{m4} to continue 802executing with the @code{c} (@code{continue}) command, and then try the 803example that caused trouble initially: 804 805@smallexample 806(@value{GDBP}) @b{c} 807Continuing. 808 809@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))} 810 811baz 8120000 813@end smallexample 814 815@noindent 816Success! The new quotes now work just as well as the default ones. The 817problem seems to have been just the two typos defining the wrong 818lengths. We allow @code{m4} exit by giving it an EOF as input: 819 820@smallexample 821@b{Ctrl-d} 822Program exited normally. 823@end smallexample 824 825@noindent 826The message @samp{Program exited normally.} is from @value{GDBN}; it 827indicates @code{m4} has finished executing. We can end our @value{GDBN} 828session with the @value{GDBN} @code{quit} command. 829 830@smallexample 831(@value{GDBP}) @b{quit} 832@end smallexample 833 834@node Invocation 835@chapter Getting In and Out of @value{GDBN} 836 837This chapter discusses how to start @value{GDBN}, and how to get out of it. 838The essentials are: 839@itemize @bullet 840@item 841type @samp{@value{GDBP}} to start @value{GDBN}. 842@item 843type @kbd{quit} or @kbd{Ctrl-d} to exit. 844@end itemize 845 846@menu 847* Invoking GDB:: How to start @value{GDBN} 848* Quitting GDB:: How to quit @value{GDBN} 849* Shell Commands:: How to use shell commands inside @value{GDBN} 850* Logging Output:: How to log @value{GDBN}'s output to a file 851@end menu 852 853@node Invoking GDB 854@section Invoking @value{GDBN} 855 856Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started, 857@value{GDBN} reads commands from the terminal until you tell it to exit. 858 859You can also run @code{@value{GDBP}} with a variety of arguments and options, 860to specify more of your debugging environment at the outset. 861 862The command-line options described here are designed 863to cover a variety of situations; in some environments, some of these 864options may effectively be unavailable. 865 866The most usual way to start @value{GDBN} is with one argument, 867specifying an executable program: 868 869@smallexample 870@value{GDBP} @var{program} 871@end smallexample 872 873@noindent 874You can also start with both an executable program and a core file 875specified: 876 877@smallexample 878@value{GDBP} @var{program} @var{core} 879@end smallexample 880 881You can, instead, specify a process ID as a second argument or use option 882@code{-p}, if you want to debug a running process: 883 884@smallexample 885@value{GDBP} @var{program} 1234 886@value{GDBP} -p 1234 887@end smallexample 888 889@noindent 890would attach @value{GDBN} to process @code{1234}. With option @option{-p} you 891can omit the @var{program} filename. 892 893Taking advantage of the second command-line argument requires a fairly 894complete operating system; when you use @value{GDBN} as a remote 895debugger attached to a bare board, there may not be any notion of 896``process'', and there is often no way to get a core dump. @value{GDBN} 897will warn you if it is unable to attach or to read core dumps. 898 899You can optionally have @code{@value{GDBP}} pass any arguments after the 900executable file to the inferior using @code{--args}. This option stops 901option processing. 902@smallexample 903@value{GDBP} --args gcc -O2 -c foo.c 904@end smallexample 905This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set 906@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}. 907 908You can run @code{@value{GDBP}} without printing the front material, which describes 909@value{GDBN}'s non-warranty, by specifying @code{--silent} 910(or @code{-q}/@code{--quiet}): 911 912@smallexample 913@value{GDBP} --silent 914@end smallexample 915 916@noindent 917You can further control how @value{GDBN} starts up by using command-line 918options. @value{GDBN} itself can remind you of the options available. 919 920@noindent 921Type 922 923@smallexample 924@value{GDBP} -help 925@end smallexample 926 927@noindent 928to display all available options and briefly describe their use 929(@samp{@value{GDBP} -h} is a shorter equivalent). 930 931All options and command line arguments you give are processed 932in sequential order. The order makes a difference when the 933@samp{-x} option is used. 934 935 936@menu 937* File Options:: Choosing files 938* Mode Options:: Choosing modes 939* Startup:: What @value{GDBN} does during startup 940* Initialization Files:: Initialization Files 941@end menu 942 943@node File Options 944@subsection Choosing Files 945 946When @value{GDBN} starts, it reads any arguments other than options as 947specifying an executable file and core file (or process ID). This is 948the same as if the arguments were specified by the @samp{-se} and 949@samp{-c} (or @samp{-p}) options respectively. (@value{GDBN} reads the 950first argument that does not have an associated option flag as 951equivalent to the @samp{-se} option followed by that argument; and the 952second argument that does not have an associated option flag, if any, as 953equivalent to the @samp{-c}/@samp{-p} option followed by that argument.) 954If the second argument begins with a decimal digit, @value{GDBN} will 955first attempt to attach to it as a process, and if that fails, attempt 956to open it as a corefile. If you have a corefile whose name begins with 957a digit, you can prevent @value{GDBN} from treating it as a pid by 958prefixing it with @file{./}, e.g.@: @file{./12345}. 959 960If @value{GDBN} has not been configured to included core file support, 961such as for most embedded targets, then it will complain about a second 962argument and ignore it. 963 964Many options have both long and short forms; both are shown in the 965following list. @value{GDBN} also recognizes the long forms if you truncate 966them, so long as enough of the option is present to be unambiguous. 967(If you prefer, you can flag option arguments with @samp{--} rather 968than @samp{-}, though we illustrate the more usual convention.) 969 970@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This 971@c way, both those who look for -foo and --foo in the index, will find 972@c it. 973 974@table @code 975@item -symbols @var{file} 976@itemx -s @var{file} 977@cindex @code{--symbols} 978@cindex @code{-s} 979Read symbol table from file @var{file}. 980 981@item -exec @var{file} 982@itemx -e @var{file} 983@cindex @code{--exec} 984@cindex @code{-e} 985Use file @var{file} as the executable file to execute when appropriate, 986and for examining pure data in conjunction with a core dump. 987 988@item -se @var{file} 989@cindex @code{--se} 990Read symbol table from file @var{file} and use it as the executable 991file. 992 993@item -core @var{file} 994@itemx -c @var{file} 995@cindex @code{--core} 996@cindex @code{-c} 997Use file @var{file} as a core dump to examine. 998 999@item -pid @var{number} 1000@itemx -p @var{number} 1001@cindex @code{--pid} 1002@cindex @code{-p} 1003Connect to process ID @var{number}, as with the @code{attach} command. 1004 1005@item -command @var{file} 1006@itemx -x @var{file} 1007@cindex @code{--command} 1008@cindex @code{-x} 1009Execute commands from file @var{file}. The contents of this file is 1010evaluated exactly as the @code{source} command would. 1011@xref{Command Files,, Command files}. 1012 1013@item -eval-command @var{command} 1014@itemx -ex @var{command} 1015@cindex @code{--eval-command} 1016@cindex @code{-ex} 1017Execute a single @value{GDBN} command. 1018 1019This option may be used multiple times to call multiple commands. It may 1020also be interleaved with @samp{-command} as required. 1021 1022@smallexample 1023@value{GDBP} -ex 'target sim' -ex 'load' \ 1024 -x setbreakpoints -ex 'run' a.out 1025@end smallexample 1026 1027@item -init-command @var{file} 1028@itemx -ix @var{file} 1029@cindex @code{--init-command} 1030@cindex @code{-ix} 1031Execute commands from file @var{file} before loading the inferior (but 1032after loading gdbinit files). 1033@xref{Startup}. 1034 1035@item -init-eval-command @var{command} 1036@itemx -iex @var{command} 1037@cindex @code{--init-eval-command} 1038@cindex @code{-iex} 1039Execute a single @value{GDBN} command before loading the inferior (but 1040after loading gdbinit files). 1041@xref{Startup}. 1042 1043@item -early-init-command @var{file} 1044@itemx -eix @var{file} 1045@cindex @code{--early-init-command} 1046@cindex @code{-eix} 1047Execute commands from @var{file} very early in the initialization 1048process, before any output is produced. @xref{Startup}. 1049 1050@item -early-init-eval-command @var{command} 1051@itemx -eiex @var{command} 1052@cindex @code{--early-init-eval-command} 1053@cindex @code{-eiex} 1054Execute a single @value{GDBN} command very early in the initialization 1055process, before any output is produced. 1056 1057@item -directory @var{directory} 1058@itemx -d @var{directory} 1059@cindex @code{--directory} 1060@cindex @code{-d} 1061Add @var{directory} to the path to search for source and script files. 1062 1063@item -r 1064@itemx -readnow 1065@cindex @code{--readnow} 1066@cindex @code{-r} 1067Read each symbol file's entire symbol table immediately, rather than 1068the default, which is to read it incrementally as it is needed. 1069This makes startup slower, but makes future operations faster. 1070 1071@item --readnever 1072@anchor{--readnever} 1073@cindex @code{--readnever}, command-line option 1074Do not read each symbol file's symbolic debug information. This makes 1075startup faster but at the expense of not being able to perform 1076symbolic debugging. DWARF unwind information is also not read, 1077meaning backtraces may become incomplete or inaccurate. One use of 1078this is when a user simply wants to do the following sequence: attach, 1079dump core, detach. Loading the debugging information in this case is 1080an unnecessary cause of delay. 1081@end table 1082 1083@node Mode Options 1084@subsection Choosing Modes 1085 1086You can run @value{GDBN} in various alternative modes---for example, in 1087batch mode or quiet mode. 1088 1089@table @code 1090@anchor{-nx} 1091@item -nx 1092@itemx -n 1093@cindex @code{--nx} 1094@cindex @code{-n} 1095Do not execute commands found in any initialization files 1096(@pxref{Initialization Files}). 1097 1098@anchor{-nh} 1099@item -nh 1100@cindex @code{--nh} 1101Do not execute commands found in any home directory initialization 1102file (@pxref{Initialization Files,,Home directory initialization 1103file}). The system wide and current directory initialization files 1104are still loaded. 1105 1106@item -quiet 1107@itemx -silent 1108@itemx -q 1109@cindex @code{--quiet} 1110@cindex @code{--silent} 1111@cindex @code{-q} 1112``Quiet''. Do not print the introductory and copyright messages. These 1113messages are also suppressed in batch mode. 1114 1115@kindex set startup-quietly 1116@kindex show startup-quietly 1117This can also be enabled using @code{set startup-quietly on}. The 1118default is @code{off}. Use @code{show startup-quietly} to see the 1119current setting. Place @code{set startup-quietly on} into your early 1120initialization file (@pxref{Initialization Files,,Initialization 1121Files}) to have future @value{GDBN} sessions startup quietly. 1122 1123@item -batch 1124@cindex @code{--batch} 1125Run in batch mode. Exit with status @code{0} after processing all the 1126command files specified with @samp{-x} (and all commands from 1127initialization files, if not inhibited with @samp{-n}). Exit with 1128nonzero status if an error occurs in executing the @value{GDBN} commands 1129in the command files. Batch mode also disables pagination, sets unlimited 1130terminal width and height @pxref{Screen Size}, and acts as if @kbd{set confirm 1131off} were in effect (@pxref{Messages/Warnings}). 1132 1133Batch mode may be useful for running @value{GDBN} as a filter, for 1134example to download and run a program on another computer; in order to 1135make this more useful, the message 1136 1137@smallexample 1138Program exited normally. 1139@end smallexample 1140 1141@noindent 1142(which is ordinarily issued whenever a program running under 1143@value{GDBN} control terminates) is not issued when running in batch 1144mode. 1145 1146@item -batch-silent 1147@cindex @code{--batch-silent} 1148Run in batch mode exactly like @samp{-batch}, but totally silently. All 1149@value{GDBN} output to @code{stdout} is prevented (@code{stderr} is 1150unaffected). This is much quieter than @samp{-silent} and would be useless 1151for an interactive session. 1152 1153This is particularly useful when using targets that give @samp{Loading section} 1154messages, for example. 1155 1156Note that targets that give their output via @value{GDBN}, as opposed to 1157writing directly to @code{stdout}, will also be made silent. 1158 1159@item -return-child-result 1160@cindex @code{--return-child-result} 1161The return code from @value{GDBN} will be the return code from the child 1162process (the process being debugged), with the following exceptions: 1163 1164@itemize @bullet 1165@item 1166@value{GDBN} exits abnormally. E.g., due to an incorrect argument or an 1167internal error. In this case the exit code is the same as it would have been 1168without @samp{-return-child-result}. 1169@item 1170The user quits with an explicit value. E.g., @samp{quit 1}. 1171@item 1172The child process never runs, or is not allowed to terminate, in which case 1173the exit code will be -1. 1174@end itemize 1175 1176This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent}, 1177when @value{GDBN} is being used as a remote program loader or simulator 1178interface. 1179 1180@item -nowindows 1181@itemx -nw 1182@cindex @code{--nowindows} 1183@cindex @code{-nw} 1184``No windows''. If @value{GDBN} comes with a graphical user interface 1185(GUI) built in, then this option tells @value{GDBN} to only use the command-line 1186interface. If no GUI is available, this option has no effect. 1187 1188@item -windows 1189@itemx -w 1190@cindex @code{--windows} 1191@cindex @code{-w} 1192If @value{GDBN} includes a GUI, then this option requires it to be 1193used if possible. 1194 1195@item -cd @var{directory} 1196@cindex @code{--cd} 1197Run @value{GDBN} using @var{directory} as its working directory, 1198instead of the current directory. 1199 1200@item -data-directory @var{directory} 1201@itemx -D @var{directory} 1202@cindex @code{--data-directory} 1203@cindex @code{-D} 1204Run @value{GDBN} using @var{directory} as its data directory. 1205The data directory is where @value{GDBN} searches for its 1206auxiliary files. @xref{Data Files}. 1207 1208@item -fullname 1209@itemx -f 1210@cindex @code{--fullname} 1211@cindex @code{-f} 1212@sc{gnu} Emacs sets this option when it runs @value{GDBN} as a 1213subprocess. It tells @value{GDBN} to output the full file name and line 1214number in a standard, recognizable fashion each time a stack frame is 1215displayed (which includes each time your program stops). This 1216recognizable format looks like two @samp{\032} characters, followed by 1217the file name, line number and character position separated by colons, 1218and a newline. The Emacs-to-@value{GDBN} interface program uses the two 1219@samp{\032} characters as a signal to display the source code for the 1220frame. 1221 1222@item -annotate @var{level} 1223@cindex @code{--annotate} 1224This option sets the @dfn{annotation level} inside @value{GDBN}. Its 1225effect is identical to using @samp{set annotate @var{level}} 1226(@pxref{Annotations}). The annotation @var{level} controls how much 1227information @value{GDBN} prints together with its prompt, values of 1228expressions, source lines, and other types of output. Level 0 is the 1229normal, level 1 is for use when @value{GDBN} is run as a subprocess of 1230@sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs 1231that control @value{GDBN}, and level 2 has been deprecated. 1232 1233The annotation mechanism has largely been superseded by @sc{gdb/mi} 1234(@pxref{GDB/MI}). 1235 1236@item --args 1237@cindex @code{--args} 1238Change interpretation of command line so that arguments following the 1239executable file are passed as command line arguments to the inferior. 1240This option stops option processing. 1241 1242@item -baud @var{bps} 1243@itemx -b @var{bps} 1244@cindex @code{--baud} 1245@cindex @code{-b} 1246Set the line speed (baud rate or bits per second) of any serial 1247interface used by @value{GDBN} for remote debugging. 1248 1249@item -l @var{timeout} 1250@cindex @code{-l} 1251Set the timeout (in seconds) of any communication used by @value{GDBN} 1252for remote debugging. 1253 1254@item -tty @var{device} 1255@itemx -t @var{device} 1256@cindex @code{--tty} 1257@cindex @code{-t} 1258Run using @var{device} for your program's standard input and output. 1259@c FIXME: kingdon thinks there is more to -tty. Investigate. 1260 1261@c resolve the situation of these eventually 1262@item -tui 1263@cindex @code{--tui} 1264Activate the @dfn{Text User Interface} when starting. The Text User 1265Interface manages several text windows on the terminal, showing 1266source, assembly, registers and @value{GDBN} command outputs 1267(@pxref{TUI, ,@value{GDBN} Text User Interface}). Do not use this 1268option if you run @value{GDBN} from Emacs (@pxref{Emacs, , 1269Using @value{GDBN} under @sc{gnu} Emacs}). 1270 1271@item -interpreter @var{interp} 1272@cindex @code{--interpreter} 1273Use the interpreter @var{interp} for interface with the controlling 1274program or device. This option is meant to be set by programs which 1275communicate with @value{GDBN} using it as a back end. 1276@xref{Interpreters, , Command Interpreters}. 1277 1278@samp{--interpreter=mi} (or @samp{--interpreter=mi3}) causes 1279@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} version 3 (@pxref{GDB/MI, , 1280The @sc{gdb/mi} Interface}) included since @value{GDBN} version 9.1. @sc{gdb/mi} 1281version 2 (@code{mi2}), included in @value{GDBN} 6.0 and version 1 (@code{mi1}), 1282included in @value{GDBN} 5.3, are also available. Earlier @sc{gdb/mi} 1283interfaces are no longer supported. 1284 1285@item -write 1286@cindex @code{--write} 1287Open the executable and core files for both reading and writing. This 1288is equivalent to the @samp{set write on} command inside @value{GDBN} 1289(@pxref{Patching}). 1290 1291@item -statistics 1292@cindex @code{--statistics} 1293This option causes @value{GDBN} to print statistics about time and 1294memory usage after it completes each command and returns to the prompt. 1295 1296@item -version 1297@cindex @code{--version} 1298This option causes @value{GDBN} to print its version number and 1299no-warranty blurb, and exit. 1300 1301@item -configuration 1302@cindex @code{--configuration} 1303This option causes @value{GDBN} to print details about its build-time 1304configuration parameters, and then exit. These details can be 1305important when reporting @value{GDBN} bugs (@pxref{GDB Bugs}). 1306 1307@end table 1308 1309@node Startup 1310@subsection What @value{GDBN} Does During Startup 1311@cindex @value{GDBN} startup 1312 1313Here's the description of what @value{GDBN} does during session startup: 1314 1315@enumerate 1316 1317@item 1318Performs minimal setup required to initialize basic internal state. 1319 1320@item 1321@cindex early initialization file 1322Reads commands from the early initialization file (if any) in your 1323home directory. Only a restricted set of commands can be placed into 1324an early initialization file, see @ref{Initialization Files}, for 1325details. 1326 1327@item 1328Executes commands and command files specified by the @samp{-eiex} and 1329@samp{-eix} command line options in their specified order. Only a 1330restricted set of commands can be used with @samp{-eiex} and 1331@samp{eix}, see @ref{Initialization Files}, for details. 1332 1333@item 1334Sets up the command interpreter as specified by the command line 1335(@pxref{Mode Options, interpreter}). 1336 1337@item 1338@cindex init file 1339Reads the system wide initialization file and the files from the 1340system wide initialization directory, @pxref{System Wide Init Files}. 1341 1342@item 1343Reads the initialization file (if any) in your home directory and 1344executes all the commands in that file, @pxref{Home Directory Init 1345File}. 1346 1347@anchor{Option -init-eval-command} 1348@item 1349Executes commands and command files specified by the @samp{-iex} and 1350@samp{-ix} options in their specified order. Usually you should use the 1351@samp{-ex} and @samp{-x} options instead, but this way you can apply 1352settings before @value{GDBN} init files get executed and before inferior 1353gets loaded. 1354 1355@item 1356Processes command line options and operands. 1357 1358@item 1359Reads and executes the commands from the initialization file (if any) 1360in the current working directory as long as @samp{set auto-load 1361local-gdbinit} is set to @samp{on} (@pxref{Init File in the Current 1362Directory}). This is only done if the current directory is different 1363from your home directory. Thus, you can have more than one init file, 1364one generic in your home directory, and another, specific to the 1365program you are debugging, in the directory where you invoke 1366@value{GDBN}. @xref{Init File in the Current Directory during 1367Startup}. 1368 1369@item 1370If the command line specified a program to debug, or a process to 1371attach to, or a core file, @value{GDBN} loads any auto-loaded 1372scripts provided for the program or for its loaded shared libraries. 1373@xref{Auto-loading}. 1374 1375If you wish to disable the auto-loading during startup, 1376you must do something like the following: 1377 1378@smallexample 1379$ gdb -iex "set auto-load python-scripts off" myprogram 1380@end smallexample 1381 1382Option @samp{-ex} does not work because the auto-loading is then turned 1383off too late. 1384 1385@item 1386Executes commands and command files specified by the @samp{-ex} and 1387@samp{-x} options in their specified order. @xref{Command Files}, for 1388more details about @value{GDBN} command files. 1389 1390@item 1391Reads the command history recorded in the @dfn{history file}. 1392@xref{Command History}, for more details about the command history and the 1393files where @value{GDBN} records it. 1394@end enumerate 1395 1396@node Initialization Files 1397@subsection Initialization Files 1398@cindex init file name 1399 1400During startup (@pxref{Startup}) @value{GDBN} will execute commands 1401from several initialization files. These initialization files use the 1402same syntax as @dfn{command files} (@pxref{Command Files}) and are 1403processed by @value{GDBN} in the same way. 1404 1405To display the list of initialization files loaded by @value{GDBN} at 1406startup, in the order they will be loaded, you can use @kbd{gdb 1407--help}. 1408 1409@cindex early initialization 1410The @dfn{early initialization} file is loaded very early in 1411@value{GDBN}'s initialization process, before the interpreter 1412(@pxref{Interpreters}) has been initialized, and before the default 1413target (@pxref{Targets}) is initialized. Only @code{set} or 1414@code{source} commands should be placed into an early initialization 1415file, and the only @code{set} commands that can be used are those that 1416control how @value{GDBN} starts up. 1417 1418Commands that can be placed into an early initialization file will be 1419documented as such throughout this manual. Any command that is not 1420documented as being suitable for an early initialization file should 1421instead be placed into a general initialization file. Command files 1422passed to @code{--early-init-command} or @code{-eix} are also early 1423initialization files, with the same command restrictions. Only 1424commands that can appear in an early initialization file should be 1425passed to @code{--early-init-eval-command} or @code{-eiex}. 1426 1427@cindex general initialization 1428In contrast, the @dfn{general initialization} files are processed 1429later, after @value{GDBN} has finished its own internal initialization 1430process, any valid command can be used in these files. 1431 1432@cindex initialization file 1433Throughout the rest of this document the term @dfn{initialization 1434file} refers to one of the general initialization files, not the early 1435initialization file. Any discussion of the early initialization file 1436will specifically mention that it is the early initialization file 1437being discussed. 1438 1439As the system wide and home directory initialization files are 1440processed before most command line options, changes to settings 1441(e.g.@: @samp{set complaints}) can affect subsequent processing of 1442command line options and operands. 1443 1444The following sections describe where @value{GDBN} looks for the early 1445initialization and initialization files, and the order that the files 1446are searched for. 1447 1448@subsubsection Home directory early initialization files 1449 1450@value{GDBN} initially looks for an early initialization file in the 1451users home directory@footnote{On DOS/Windows systems, the home 1452directory is the one pointed to by the @env{HOME} environment 1453variable.}. There are a number of locations that @value{GDBN} will 1454search in the home directory, these locations are searched in order 1455and @value{GDBN} will load the first file that it finds, and 1456subsequent locations will not be checked. 1457 1458On non-macOS hosts the locations searched are: 1459@itemize 1460@item 1461The file @file{gdb/gdbearlyinit} within the directory pointed to by the 1462environment variable @env{XDG_CONFIG_HOME}, if it is defined. 1463@item 1464The file @file{.config/gdb/gdbearlyinit} within the directory pointed to 1465by the environment variable @env{HOME}, if it is defined. 1466@item 1467The file @file{.gdbearlyinit} within the directory pointed to by the 1468environment variable @env{HOME}, if it is defined. 1469@end itemize 1470 1471By contrast, on macOS hosts the locations searched are: 1472@itemize 1473@item 1474The file @file{Library/Preferences/gdb/gdbearlyinit} within the 1475directory pointed to by the environment variable @env{HOME}, if it is 1476defined. 1477@item 1478The file @file{.gdbearlyinit} within the directory pointed to by the 1479environment variable @env{HOME}, if it is defined. 1480@end itemize 1481 1482It is possible to prevent the home directory early initialization file 1483from being loaded using the @samp{-nx} or @samp{-nh} command line 1484options, @pxref{Mode Options,,Choosing Modes}. 1485 1486@anchor{System Wide Init Files} 1487@subsubsection System wide initialization files 1488 1489There are two locations that are searched for system wide 1490initialization files. Both of these locations are always checked: 1491 1492@table @code 1493 1494@item @file{system.gdbinit} 1495This is a single system-wide initialization file. Its location is 1496specified with the @code{--with-system-gdbinit} configure option 1497(@pxref{System-wide configuration}). It is loaded first when 1498@value{GDBN} starts, before command line options have been processed. 1499 1500@item @file{system.gdbinit.d} 1501This is the system-wide initialization directory. Its location is 1502specified with the @code{--with-system-gdbinit-dir} configure option 1503(@pxref{System-wide configuration}). Files in this directory are 1504loaded in alphabetical order immediately after @file{system.gdbinit} 1505(if enabled) when @value{GDBN} starts, before command line options 1506have been processed. Files need to have a recognized scripting 1507language extension (@file{.py}/@file{.scm}) or be named with a 1508@file{.gdb} extension to be interpreted as regular @value{GDBN} 1509commands. @value{GDBN} will not recurse into any subdirectories of 1510this directory. 1511 1512@end table 1513 1514It is possible to prevent the system wide initialization files from 1515being loaded using the @samp{-nx} command line option, @pxref{Mode 1516Options,,Choosing Modes}. 1517 1518@anchor{Home Directory Init File} 1519@subsubsection Home directory initialization file 1520@cindex @file{gdbinit} 1521@cindex @file{.gdbinit} 1522@cindex @file{gdb.ini} 1523 1524After loading the system wide initialization files @value{GDBN} will 1525look for an initialization file in the users home 1526directory@footnote{On DOS/Windows systems, the home directory is the 1527one pointed to by the @env{HOME} environment variable.}. There are a 1528number of locations that @value{GDBN} will search in the home 1529directory, these locations are searched in order and @value{GDBN} will 1530load the first file that it finds, and subsequent locations will not 1531be checked. 1532 1533On non-Apple hosts the locations searched are: 1534@table @file 1535@item $XDG_CONFIG_HOME/gdb/gdbinit 1536@item $HOME/.config/gdb/gdbinit 1537@item $HOME/.gdbinit 1538@end table 1539 1540While on Apple hosts the locations searched are: 1541@table @file 1542@item $HOME/Library/Preferences/gdb/gdbinit 1543@item $HOME/.gdbinit 1544@end table 1545 1546It is possible to prevent the home directory initialization file from 1547being loaded using the @samp{-nx} or @samp{-nh} command line options, 1548@pxref{Mode Options,,Choosing Modes}. 1549 1550The DJGPP port of @value{GDBN} uses the name @file{gdb.ini} instead of 1551@file{.gdbinit} or @file{gdbinit}, due to the limitations of file 1552names imposed by DOS filesystems. The Windows port of @value{GDBN} 1553uses the standard name, but if it finds a @file{gdb.ini} file in your 1554home directory, it warns you about that and suggests to rename the 1555file to the standard name. 1556 1557@anchor{Init File in the Current Directory during Startup} 1558@subsubsection Local directory initialization file 1559 1560@value{GDBN} will check the current directory for a file called 1561@file{.gdbinit}. It is loaded last, after command line options 1562other than @samp{-x} and @samp{-ex} have been processed. The command 1563line options @samp{-x} and @samp{-ex} are processed last, after 1564@file{.gdbinit} has been loaded, @pxref{File Options,,Choosing 1565Files}. 1566 1567If the file in the current directory was already loaded as the home 1568directory initialization file then it will not be loaded a second 1569time. 1570 1571It is possible to prevent the local directory initialization file from 1572being loaded using the @samp{-nx} command line option, @pxref{Mode 1573Options,,Choosing Modes}. 1574 1575@node Quitting GDB 1576@section Quitting @value{GDBN} 1577@cindex exiting @value{GDBN} 1578@cindex leaving @value{GDBN} 1579 1580@table @code 1581@kindex quit @r{[}@var{expression}@r{]} 1582@kindex q @r{(@code{quit})} 1583@item quit @r{[}@var{expression}@r{]} 1584@itemx q 1585To exit @value{GDBN}, use the @code{quit} command (abbreviated 1586@code{q}), or type an end-of-file character (usually @kbd{Ctrl-d}). If you 1587do not supply @var{expression}, @value{GDBN} will terminate normally; 1588otherwise it will terminate using the result of @var{expression} as the 1589error code. 1590@end table 1591 1592@cindex interrupt 1593An interrupt (often @kbd{Ctrl-c}) does not exit from @value{GDBN}, but rather 1594terminates the action of any @value{GDBN} command that is in progress and 1595returns to @value{GDBN} command level. It is safe to type the interrupt 1596character at any time because @value{GDBN} does not allow it to take effect 1597until a time when it is safe. 1598 1599If you have been using @value{GDBN} to control an attached process or 1600device, you can release it with the @code{detach} command 1601(@pxref{Attach, ,Debugging an Already-running Process}). 1602 1603@node Shell Commands 1604@section Shell Commands 1605 1606If you need to execute occasional shell commands during your 1607debugging session, there is no need to leave or suspend @value{GDBN}; you can 1608just use the @code{shell} command. 1609 1610@table @code 1611@kindex shell 1612@kindex ! 1613@cindex shell escape 1614@item shell @var{command-string} 1615@itemx !@var{command-string} 1616Invoke a standard shell to execute @var{command-string}. 1617Note that no space is needed between @code{!} and @var{command-string}. 1618On GNU and Unix systems, the environment variable @env{SHELL}, if it 1619exists, determines which shell to run. Otherwise @value{GDBN} uses 1620the default shell (@file{/bin/sh} on GNU and Unix systems, 1621@file{cmd.exe} on MS-Windows, @file{COMMAND.COM} on MS-DOS, etc.). 1622@end table 1623 1624The utility @code{make} is often needed in development environments. 1625You do not have to use the @code{shell} command for this purpose in 1626@value{GDBN}: 1627 1628@table @code 1629@kindex make 1630@cindex calling make 1631@item make @var{make-args} 1632Execute the @code{make} program with the specified 1633arguments. This is equivalent to @samp{shell make @var{make-args}}. 1634@end table 1635 1636@table @code 1637@kindex pipe 1638@kindex | 1639@cindex send the output of a gdb command to a shell command 1640@anchor{pipe} 1641@item pipe [@var{command}] | @var{shell_command} 1642@itemx | [@var{command}] | @var{shell_command} 1643@itemx pipe -d @var{delim} @var{command} @var{delim} @var{shell_command} 1644@itemx | -d @var{delim} @var{command} @var{delim} @var{shell_command} 1645Executes @var{command} and sends its output to @var{shell_command}. 1646Note that no space is needed around @code{|}. 1647If no @var{command} is provided, the last command executed is repeated. 1648 1649In case the @var{command} contains a @code{|}, the option @code{-d @var{delim}} 1650can be used to specify an alternate delimiter string @var{delim} that separates 1651the @var{command} from the @var{shell_command}. 1652 1653Example: 1654@smallexample 1655@group 1656(gdb) p var 1657$1 = @{ 1658 black = 144, 1659 red = 233, 1660 green = 377, 1661 blue = 610, 1662 white = 987 1663@} 1664@end group 1665@group 1666(gdb) pipe p var|wc 1667 7 19 80 1668(gdb) |p var|wc -l 16697 1670@end group 1671@group 1672(gdb) p /x var 1673$4 = @{ 1674 black = 0x90, 1675 red = 0xe9, 1676 green = 0x179, 1677 blue = 0x262, 1678 white = 0x3db 1679@} 1680(gdb) ||grep red 1681 red => 0xe9, 1682@end group 1683@group 1684(gdb) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/' 1685this contains a PIPE char 1686(gdb) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/' 1687this contains a PIPE char! 1688(gdb) 1689@end group 1690@end smallexample 1691@end table 1692 1693The convenience variables @code{$_shell_exitcode} and @code{$_shell_exitsignal} 1694can be used to examine the exit status of the last shell command launched 1695by @code{shell}, @code{make}, @code{pipe} and @code{|}. 1696@xref{Convenience Vars,, Convenience Variables}. 1697 1698@node Logging Output 1699@section Logging Output 1700@cindex logging @value{GDBN} output 1701@cindex save @value{GDBN} output to a file 1702 1703You may want to save the output of @value{GDBN} commands to a file. 1704There are several commands to control @value{GDBN}'s logging. 1705 1706@table @code 1707@kindex set logging 1708@item set logging on 1709Enable logging. 1710@item set logging off 1711Disable logging. 1712@cindex logging file name 1713@item set logging file @var{file} 1714Change the name of the current logfile. The default logfile is @file{gdb.txt}. 1715@item set logging overwrite [on|off] 1716By default, @value{GDBN} will append to the logfile. Set @code{overwrite} if 1717you want @code{set logging on} to overwrite the logfile instead. 1718@item set logging redirect [on|off] 1719By default, @value{GDBN} output will go to both the terminal and the logfile. 1720Set @code{redirect} if you want output to go only to the log file. 1721@item set logging debugredirect [on|off] 1722By default, @value{GDBN} debug output will go to both the terminal and the logfile. 1723Set @code{debugredirect} if you want debug output to go only to the log file. 1724@kindex show logging 1725@item show logging 1726Show the current values of the logging settings. 1727@end table 1728 1729You can also redirect the output of a @value{GDBN} command to a 1730shell command. @xref{pipe}. 1731@node Commands 1732@chapter @value{GDBN} Commands 1733 1734You can abbreviate a @value{GDBN} command to the first few letters of the command 1735name, if that abbreviation is unambiguous; and you can repeat certain 1736@value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB} 1737key to get @value{GDBN} to fill out the rest of a word in a command (or to 1738show you the alternatives available, if there is more than one possibility). 1739 1740@menu 1741* Command Syntax:: How to give commands to @value{GDBN} 1742* Command Settings:: How to change default behavior of commands 1743* Completion:: Command completion 1744* Command Options:: Command options 1745* Help:: How to ask @value{GDBN} for help 1746@end menu 1747 1748@node Command Syntax 1749@section Command Syntax 1750 1751A @value{GDBN} command is a single line of input. There is no limit on 1752how long it can be. It starts with a command name, which is followed by 1753arguments whose meaning depends on the command name. For example, the 1754command @code{step} accepts an argument which is the number of times to 1755step, as in @samp{step 5}. You can also use the @code{step} command 1756with no arguments. Some commands do not allow any arguments. 1757 1758@cindex abbreviation 1759@value{GDBN} command names may always be truncated if that abbreviation is 1760unambiguous. Other possible command abbreviations are listed in the 1761documentation for individual commands. In some cases, even ambiguous 1762abbreviations are allowed; for example, @code{s} is specially defined as 1763equivalent to @code{step} even though there are other commands whose 1764names start with @code{s}. You can test abbreviations by using them as 1765arguments to the @code{help} command. 1766 1767@cindex repeating commands 1768@kindex RET @r{(repeat last command)} 1769A blank line as input to @value{GDBN} (typing just @key{RET}) means to 1770repeat the previous command. Certain commands (for example, @code{run}) 1771will not repeat this way; these are commands whose unintentional 1772repetition might cause trouble and which you are unlikely to want to 1773repeat. User-defined commands can disable this feature; see 1774@ref{Define, dont-repeat}. 1775 1776The @code{list} and @code{x} commands, when you repeat them with 1777@key{RET}, construct new arguments rather than repeating 1778exactly as typed. This permits easy scanning of source or memory. 1779 1780@value{GDBN} can also use @key{RET} in another way: to partition lengthy 1781output, in a way similar to the common utility @code{more} 1782(@pxref{Screen Size,,Screen Size}). Since it is easy to press one 1783@key{RET} too many in this situation, @value{GDBN} disables command 1784repetition after any command that generates this sort of display. 1785 1786@kindex # @r{(a comment)} 1787@cindex comment 1788Any text from a @kbd{#} to the end of the line is a comment; it does 1789nothing. This is useful mainly in command files (@pxref{Command 1790Files,,Command Files}). 1791 1792@cindex repeating command sequences 1793@kindex Ctrl-o @r{(operate-and-get-next)} 1794The @kbd{Ctrl-o} binding is useful for repeating a complex sequence of 1795commands. This command accepts the current line, like @key{RET}, and 1796then fetches the next line relative to the current line from the history 1797for editing. 1798 1799 1800@node Command Settings 1801@section Command Settings 1802@cindex default behavior of commands, changing 1803@cindex default settings, changing 1804 1805Many commands change their behavior according to command-specific 1806variables or settings. These settings can be changed with the 1807@code{set} subcommands. For example, the @code{print} command 1808(@pxref{Data, ,Examining Data}) prints arrays differently depending on 1809settings changeable with the commands @code{set print elements 1810NUMBER-OF-ELEMENTS} and @code{set print array-indexes}, among others. 1811 1812You can change these settings to your preference in the gdbinit files 1813loaded at @value{GDBN} startup. @xref{Startup}. 1814 1815The settings can also be changed interactively during the debugging 1816session. For example, to change the limit of array elements to print, 1817you can do the following: 1818@smallexample 1819(@value{GDBN}) set print elements 10 1820(@value{GDBN}) print some_array 1821$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@} 1822@end smallexample 1823 1824The above @code{set print elements 10} command changes the number of 1825elements to print from the default of 200 to 10. If you only intend 1826this limit of 10 to be used for printing @code{some_array}, then you 1827must restore the limit back to 200, with @code{set print elements 1828200}. 1829 1830Some commands allow overriding settings with command options. For 1831example, the @code{print} command supports a number of options that 1832allow overriding relevant global print settings as set by @code{set 1833print} subcommands. @xref{print options}. The example above could be 1834rewritten as: 1835@smallexample 1836(@value{GDBN}) print -elements 10 -- some_array 1837$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@} 1838@end smallexample 1839 1840Alternatively, you can use the @code{with} command to change a setting 1841temporarily, for the duration of a command invocation. 1842 1843@table @code 1844@kindex with command 1845@kindex w @r{(@code{with})} 1846@cindex settings 1847@cindex temporarily change settings 1848@item with @var{setting} [@var{value}] [-- @var{command}] 1849@itemx w @var{setting} [@var{value}] [-- @var{command}] 1850Temporarily set @var{setting} to @var{value} for the duration of 1851@var{command}. 1852 1853@var{setting} is any setting you can change with the @code{set} 1854subcommands. @var{value} is the value to assign to @code{setting} 1855while running @code{command}. 1856 1857If no @var{command} is provided, the last command executed is 1858repeated. 1859 1860If a @var{command} is provided, it must be preceded by a double dash 1861(@code{--}) separator. This is required because some settings accept 1862free-form arguments, such as expressions or filenames. 1863 1864For example, the command 1865@smallexample 1866(@value{GDBN}) with print array on -- print some_array 1867@end smallexample 1868@noindent 1869is equivalent to the following 3 commands: 1870@smallexample 1871(@value{GDBN}) set print array on 1872(@value{GDBN}) print some_array 1873(@value{GDBN}) set print array off 1874@end smallexample 1875 1876The @code{with} command is particularly useful when you want to 1877override a setting while running user-defined commands, or commands 1878defined in Python or Guile. @xref{Extending GDB,, Extending GDB}. 1879 1880@smallexample 1881(@value{GDBN}) with print pretty on -- my_complex_command 1882@end smallexample 1883 1884To change several settings for the same command, you can nest 1885@code{with} commands. For example, @code{with language ada -- with 1886print elements 10} temporarily changes the language to Ada and sets a 1887limit of 10 elements to print for arrays and strings. 1888 1889@end table 1890 1891@node Completion 1892@section Command Completion 1893 1894@cindex completion 1895@cindex word completion 1896@value{GDBN} can fill in the rest of a word in a command for you, if there is 1897only one possibility; it can also show you what the valid possibilities 1898are for the next word in a command, at any time. This works for @value{GDBN} 1899commands, @value{GDBN} subcommands, command options, and the names of symbols 1900in your program. 1901 1902Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest 1903of a word. If there is only one possibility, @value{GDBN} fills in the 1904word, and waits for you to finish the command (or press @key{RET} to 1905enter it). For example, if you type 1906 1907@c FIXME "@key" does not distinguish its argument sufficiently to permit 1908@c complete accuracy in these examples; space introduced for clarity. 1909@c If texinfo enhancements make it unnecessary, it would be nice to 1910@c replace " @key" by "@key" in the following... 1911@smallexample 1912(@value{GDBP}) info bre @key{TAB} 1913@end smallexample 1914 1915@noindent 1916@value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is 1917the only @code{info} subcommand beginning with @samp{bre}: 1918 1919@smallexample 1920(@value{GDBP}) info breakpoints 1921@end smallexample 1922 1923@noindent 1924You can either press @key{RET} at this point, to run the @code{info 1925breakpoints} command, or backspace and enter something else, if 1926@samp{breakpoints} does not look like the command you expected. (If you 1927were sure you wanted @code{info breakpoints} in the first place, you 1928might as well just type @key{RET} immediately after @samp{info bre}, 1929to exploit command abbreviations rather than command completion). 1930 1931If there is more than one possibility for the next word when you press 1932@key{TAB}, @value{GDBN} sounds a bell. You can either supply more 1933characters and try again, or just press @key{TAB} a second time; 1934@value{GDBN} displays all the possible completions for that word. For 1935example, you might want to set a breakpoint on a subroutine whose name 1936begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN} 1937just sounds the bell. Typing @key{TAB} again displays all the 1938function names in your program that begin with those characters, for 1939example: 1940 1941@smallexample 1942(@value{GDBP}) b make_ @key{TAB} 1943@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see: 1944make_a_section_from_file make_environ 1945make_abs_section make_function_type 1946make_blockvector make_pointer_type 1947make_cleanup make_reference_type 1948make_command make_symbol_completion_list 1949(@value{GDBP}) b make_ 1950@end smallexample 1951 1952@noindent 1953After displaying the available possibilities, @value{GDBN} copies your 1954partial input (@samp{b make_} in the example) so you can finish the 1955command. 1956 1957If you just want to see the list of alternatives in the first place, you 1958can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?} 1959means @kbd{@key{META} ?}. You can type this either by holding down a 1960key designated as the @key{META} shift on your keyboard (if there is 1961one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}. 1962 1963If the number of possible completions is large, @value{GDBN} will 1964print as much of the list as it has collected, as well as a message 1965indicating that the list may be truncated. 1966 1967@smallexample 1968(@value{GDBP}) b m@key{TAB}@key{TAB} 1969main 1970<... the rest of the possible completions ...> 1971*** List may be truncated, max-completions reached. *** 1972(@value{GDBP}) b m 1973@end smallexample 1974 1975@noindent 1976This behavior can be controlled with the following commands: 1977 1978@table @code 1979@kindex set max-completions 1980@item set max-completions @var{limit} 1981@itemx set max-completions unlimited 1982Set the maximum number of completion candidates. @value{GDBN} will 1983stop looking for more completions once it collects this many candidates. 1984This is useful when completing on things like function names as collecting 1985all the possible candidates can be time consuming. 1986The default value is 200. A value of zero disables tab-completion. 1987Note that setting either no limit or a very large limit can make 1988completion slow. 1989@kindex show max-completions 1990@item show max-completions 1991Show the maximum number of candidates that @value{GDBN} will collect and show 1992during completion. 1993@end table 1994 1995@cindex quotes in commands 1996@cindex completion of quoted strings 1997Sometimes the string you need, while logically a ``word'', may contain 1998parentheses or other characters that @value{GDBN} normally excludes from 1999its notion of a word. To permit word completion to work in this 2000situation, you may enclose words in @code{'} (single quote marks) in 2001@value{GDBN} commands. 2002 2003A likely situation where you might need this is in typing an 2004expression that involves a C@t{++} symbol name with template 2005parameters. This is because when completing expressions, GDB treats 2006the @samp{<} character as word delimiter, assuming that it's the 2007less-than comparison operator (@pxref{C Operators, , C and C@t{++} 2008Operators}). 2009 2010For example, when you want to call a C@t{++} template function 2011interactively using the @code{print} or @code{call} commands, you may 2012need to distinguish whether you mean the version of @code{name} that 2013was specialized for @code{int}, @code{name<int>()}, or the version 2014that was specialized for @code{float}, @code{name<float>()}. To use 2015the word-completion facilities in this situation, type a single quote 2016@code{'} at the beginning of the function name. This alerts 2017@value{GDBN} that it may need to consider more information than usual 2018when you press @key{TAB} or @kbd{M-?} to request word completion: 2019 2020@smallexample 2021(@value{GDBP}) p 'func< @kbd{M-?} 2022func<int>() func<float>() 2023(@value{GDBP}) p 'func< 2024@end smallexample 2025 2026When setting breakpoints however (@pxref{Specify Location}), you don't 2027usually need to type a quote before the function name, because 2028@value{GDBN} understands that you want to set a breakpoint on a 2029function: 2030 2031@smallexample 2032(@value{GDBP}) b func< @kbd{M-?} 2033func<int>() func<float>() 2034(@value{GDBP}) b func< 2035@end smallexample 2036 2037This is true even in the case of typing the name of C@t{++} overloaded 2038functions (multiple definitions of the same function, distinguished by 2039argument type). For example, when you want to set a breakpoint you 2040don't need to distinguish whether you mean the version of @code{name} 2041that takes an @code{int} parameter, @code{name(int)}, or the version 2042that takes a @code{float} parameter, @code{name(float)}. 2043 2044@smallexample 2045(@value{GDBP}) b bubble( @kbd{M-?} 2046bubble(int) bubble(double) 2047(@value{GDBP}) b bubble(dou @kbd{M-?} 2048bubble(double) 2049@end smallexample 2050 2051See @ref{quoting names} for a description of other scenarios that 2052require quoting. 2053 2054For more information about overloaded functions, see @ref{C Plus Plus 2055Expressions, ,C@t{++} Expressions}. You can use the command @code{set 2056overload-resolution off} to disable overload resolution; 2057see @ref{Debugging C Plus Plus, ,@value{GDBN} Features for C@t{++}}. 2058 2059@cindex completion of structure field names 2060@cindex structure field name completion 2061@cindex completion of union field names 2062@cindex union field name completion 2063When completing in an expression which looks up a field in a 2064structure, @value{GDBN} also tries@footnote{The completer can be 2065confused by certain kinds of invalid expressions. Also, it only 2066examines the static type of the expression, not the dynamic type.} to 2067limit completions to the field names available in the type of the 2068left-hand-side: 2069 2070@smallexample 2071(@value{GDBP}) p gdb_stdout.@kbd{M-?} 2072magic to_fputs to_rewind 2073to_data to_isatty to_write 2074to_delete to_put to_write_async_safe 2075to_flush to_read 2076@end smallexample 2077 2078@noindent 2079This is because the @code{gdb_stdout} is a variable of the type 2080@code{struct ui_file} that is defined in @value{GDBN} sources as 2081follows: 2082 2083@smallexample 2084struct ui_file 2085@{ 2086 int *magic; 2087 ui_file_flush_ftype *to_flush; 2088 ui_file_write_ftype *to_write; 2089 ui_file_write_async_safe_ftype *to_write_async_safe; 2090 ui_file_fputs_ftype *to_fputs; 2091 ui_file_read_ftype *to_read; 2092 ui_file_delete_ftype *to_delete; 2093 ui_file_isatty_ftype *to_isatty; 2094 ui_file_rewind_ftype *to_rewind; 2095 ui_file_put_ftype *to_put; 2096 void *to_data; 2097@} 2098@end smallexample 2099 2100@node Command Options 2101@section Command options 2102 2103@cindex command options 2104Some commands accept options starting with a leading dash. For 2105example, @code{print -pretty}. Similarly to command names, you can 2106abbreviate a @value{GDBN} option to the first few letters of the 2107option name, if that abbreviation is unambiguous, and you can also use 2108the @key{TAB} key to get @value{GDBN} to fill out the rest of a word 2109in an option (or to show you the alternatives available, if there is 2110more than one possibility). 2111 2112@cindex command options, raw input 2113Some commands take raw input as argument. For example, the print 2114command processes arbitrary expressions in any of the languages 2115supported by @value{GDBN}. With such commands, because raw input may 2116start with a leading dash that would be confused with an option or any 2117of its abbreviations, e.g.@: @code{print -p} (short for @code{print 2118-pretty} or printing negative @code{p}?), if you specify any command 2119option, then you must use a double-dash (@code{--}) delimiter to 2120indicate the end of options. 2121 2122@cindex command options, boolean 2123 2124Some options are described as accepting an argument which can be 2125either @code{on} or @code{off}. These are known as @dfn{boolean 2126options}. Similarly to boolean settings commands---@code{on} and 2127@code{off} are the typical values, but any of @code{1}, @code{yes} and 2128@code{enable} can also be used as ``true'' value, and any of @code{0}, 2129@code{no} and @code{disable} can also be used as ``false'' value. You 2130can also omit a ``true'' value, as it is implied by default. 2131 2132For example, these are equivalent: 2133 2134@smallexample 2135(@value{GDBP}) print -object on -pretty off -element unlimited -- *myptr 2136(@value{GDBP}) p -o -p 0 -e u -- *myptr 2137@end smallexample 2138 2139You can discover the set of options some command accepts by completing 2140on @code{-} after the command name. For example: 2141 2142@smallexample 2143(@value{GDBP}) print -@key{TAB}@key{TAB} 2144-address -max-depth -raw-values -union 2145-array -null-stop -repeats -vtbl 2146-array-indexes -object -static-members 2147-elements -pretty -symbol 2148@end smallexample 2149 2150Completion will in some cases guide you with a suggestion of what kind 2151of argument an option expects. For example: 2152 2153@smallexample 2154(@value{GDBP}) print -elements @key{TAB}@key{TAB} 2155NUMBER unlimited 2156@end smallexample 2157 2158Here, the option expects a number (e.g., @code{100}), not literal 2159@code{NUMBER}. Such metasyntactical arguments are always presented in 2160uppercase. 2161 2162(For more on using the @code{print} command, see @ref{Data, ,Examining 2163Data}.) 2164 2165@node Help 2166@section Getting Help 2167@cindex online documentation 2168@kindex help 2169 2170You can always ask @value{GDBN} itself for information on its commands, 2171using the command @code{help}. 2172 2173@table @code 2174@kindex h @r{(@code{help})} 2175@item help 2176@itemx h 2177You can use @code{help} (abbreviated @code{h}) with no arguments to 2178display a short list of named classes of commands: 2179 2180@smallexample 2181(@value{GDBP}) help 2182List of classes of commands: 2183 2184aliases -- User-defined aliases of other commands 2185breakpoints -- Making program stop at certain points 2186data -- Examining data 2187files -- Specifying and examining files 2188internals -- Maintenance commands 2189obscure -- Obscure features 2190running -- Running the program 2191stack -- Examining the stack 2192status -- Status inquiries 2193support -- Support facilities 2194tracepoints -- Tracing of program execution without 2195 stopping the program 2196user-defined -- User-defined commands 2197 2198Type "help" followed by a class name for a list of 2199commands in that class. 2200Type "help" followed by command name for full 2201documentation. 2202Command name abbreviations are allowed if unambiguous. 2203(@value{GDBP}) 2204@end smallexample 2205@c the above line break eliminates huge line overfull... 2206 2207@item help @var{class} 2208Using one of the general help classes as an argument, you can get a 2209list of the individual commands in that class. If a command has 2210aliases, the aliases are given after the command name, separated by 2211commas. If an alias has default arguments, the full definition of 2212the alias is given after the first line. 2213For example, here is the help display for the class @code{status}: 2214 2215@smallexample 2216(@value{GDBP}) help status 2217Status inquiries. 2218 2219List of commands: 2220 2221@c Line break in "show" line falsifies real output, but needed 2222@c to fit in smallbook page size. 2223info, inf, i -- Generic command for showing things 2224 about the program being debugged 2225info address, iamain -- Describe where symbol SYM is stored. 2226 alias iamain = info address main 2227info all-registers -- List of all registers and their contents, 2228 for selected stack frame. 2229... 2230show, info set -- Generic command for showing things 2231 about the debugger 2232 2233Type "help" followed by command name for full 2234documentation. 2235Command name abbreviations are allowed if unambiguous. 2236(@value{GDBP}) 2237@end smallexample 2238 2239@item help @var{command} 2240With a command name as @code{help} argument, @value{GDBN} displays a 2241short paragraph on how to use that command. If that command has 2242one or more aliases, @value{GDBN} will display a first line with 2243the command name and all its aliases separated by commas. 2244This first line will be followed by the full definition of all aliases 2245having default arguments. 2246 2247@kindex apropos 2248@item apropos [-v] @var{regexp} 2249The @code{apropos} command searches through all of the @value{GDBN} 2250commands, and their documentation, for the regular expression specified in 2251@var{args}. It prints out all matches found. The optional flag @samp{-v}, 2252which stands for @samp{verbose}, indicates to output the full documentation 2253of the matching commands and highlight the parts of the documentation 2254matching @var{regexp}. For example: 2255 2256@smallexample 2257apropos alias 2258@end smallexample 2259 2260@noindent 2261results in: 2262 2263@smallexample 2264@group 2265alias -- Define a new command that is an alias of an existing command 2266aliases -- User-defined aliases of other commands 2267@end group 2268@end smallexample 2269 2270@noindent 2271while 2272 2273@smallexample 2274apropos -v cut.*thread apply 2275@end smallexample 2276 2277@noindent 2278results in the below output, where @samp{cut for 'thread apply} 2279is highlighted if styling is enabled. 2280 2281@smallexample 2282@group 2283taas -- Apply a command to all threads (ignoring errors 2284and empty output). 2285Usage: taas COMMAND 2286shortcut for 'thread apply all -s COMMAND' 2287 2288tfaas -- Apply a command to all frames of all threads 2289(ignoring errors and empty output). 2290Usage: tfaas COMMAND 2291shortcut for 'thread apply all -s frame apply all -s COMMAND' 2292@end group 2293@end smallexample 2294 2295@kindex complete 2296@item complete @var{args} 2297The @code{complete @var{args}} command lists all the possible completions 2298for the beginning of a command. Use @var{args} to specify the beginning of the 2299command you want completed. For example: 2300 2301@smallexample 2302complete i 2303@end smallexample 2304 2305@noindent results in: 2306 2307@smallexample 2308@group 2309if 2310ignore 2311info 2312inspect 2313@end group 2314@end smallexample 2315 2316@noindent This is intended for use by @sc{gnu} Emacs. 2317@end table 2318 2319In addition to @code{help}, you can use the @value{GDBN} commands @code{info} 2320and @code{show} to inquire about the state of your program, or the state 2321of @value{GDBN} itself. Each command supports many topics of inquiry; this 2322manual introduces each of them in the appropriate context. The listings 2323under @code{info} and under @code{show} in the Command, Variable, and 2324Function Index point to all the sub-commands. @xref{Command and Variable 2325Index}. 2326 2327@c @group 2328@table @code 2329@kindex info 2330@kindex i @r{(@code{info})} 2331@item info 2332This command (abbreviated @code{i}) is for describing the state of your 2333program. For example, you can show the arguments passed to a function 2334with @code{info args}, list the registers currently in use with @code{info 2335registers}, or list the breakpoints you have set with @code{info breakpoints}. 2336You can get a complete list of the @code{info} sub-commands with 2337@w{@code{help info}}. 2338 2339@kindex set 2340@item set 2341You can assign the result of an expression to an environment variable with 2342@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with 2343@code{set prompt $}. 2344 2345@kindex show 2346@item show 2347In contrast to @code{info}, @code{show} is for describing the state of 2348@value{GDBN} itself. 2349You can change most of the things you can @code{show}, by using the 2350related command @code{set}; for example, you can control what number 2351system is used for displays with @code{set radix}, or simply inquire 2352which is currently in use with @code{show radix}. 2353 2354@kindex info set 2355To display all the settable parameters and their current 2356values, you can use @code{show} with no arguments; you may also use 2357@code{info set}. Both commands produce the same display. 2358@c FIXME: "info set" violates the rule that "info" is for state of 2359@c FIXME...program. Ck w/ GNU: "info set" to be called something else, 2360@c FIXME...or change desc of rule---eg "state of prog and debugging session"? 2361@end table 2362@c @end group 2363 2364Here are several miscellaneous @code{show} subcommands, all of which are 2365exceptional in lacking corresponding @code{set} commands: 2366 2367@table @code 2368@kindex show version 2369@cindex @value{GDBN} version number 2370@item show version 2371Show what version of @value{GDBN} is running. You should include this 2372information in @value{GDBN} bug-reports. If multiple versions of 2373@value{GDBN} are in use at your site, you may need to determine which 2374version of @value{GDBN} you are running; as @value{GDBN} evolves, new 2375commands are introduced, and old ones may wither away. Also, many 2376system vendors ship variant versions of @value{GDBN}, and there are 2377variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well. 2378The version number is the same as the one announced when you start 2379@value{GDBN}. 2380 2381@kindex show copying 2382@kindex info copying 2383@cindex display @value{GDBN} copyright 2384@item show copying 2385@itemx info copying 2386Display information about permission for copying @value{GDBN}. 2387 2388@kindex show warranty 2389@kindex info warranty 2390@item show warranty 2391@itemx info warranty 2392Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty, 2393if your version of @value{GDBN} comes with one. 2394 2395@kindex show configuration 2396@item show configuration 2397Display detailed information about the way @value{GDBN} was configured 2398when it was built. This displays the optional arguments passed to the 2399@file{configure} script and also configuration parameters detected 2400automatically by @command{configure}. When reporting a @value{GDBN} 2401bug (@pxref{GDB Bugs}), it is important to include this information in 2402your report. 2403 2404@end table 2405 2406@node Running 2407@chapter Running Programs Under @value{GDBN} 2408 2409When you run a program under @value{GDBN}, you must first generate 2410debugging information when you compile it. 2411 2412You may start @value{GDBN} with its arguments, if any, in an environment 2413of your choice. If you are doing native debugging, you may redirect 2414your program's input and output, debug an already running process, or 2415kill a child process. 2416 2417@menu 2418* Compilation:: Compiling for debugging 2419* Starting:: Starting your program 2420* Arguments:: Your program's arguments 2421* Environment:: Your program's environment 2422 2423* Working Directory:: Your program's working directory 2424* Input/Output:: Your program's input and output 2425* Attach:: Debugging an already-running process 2426* Kill Process:: Killing the child process 2427* Inferiors Connections and Programs:: Debugging multiple inferiors 2428 connections and programs 2429* Threads:: Debugging programs with multiple threads 2430* Forks:: Debugging forks 2431* Checkpoint/Restart:: Setting a @emph{bookmark} to return to later 2432@end menu 2433 2434@node Compilation 2435@section Compiling for Debugging 2436 2437In order to debug a program effectively, you need to generate 2438debugging information when you compile it. This debugging information 2439is stored in the object file; it describes the data type of each 2440variable or function and the correspondence between source line numbers 2441and addresses in the executable code. 2442 2443To request debugging information, specify the @samp{-g} option when you run 2444the compiler. 2445 2446Programs that are to be shipped to your customers are compiled with 2447optimizations, using the @samp{-O} compiler option. However, some 2448compilers are unable to handle the @samp{-g} and @samp{-O} options 2449together. Using those compilers, you cannot generate optimized 2450executables containing debugging information. 2451 2452@value{NGCC}, the @sc{gnu} C/C@t{++} compiler, supports @samp{-g} with or 2453without @samp{-O}, making it possible to debug optimized code. We 2454recommend that you @emph{always} use @samp{-g} whenever you compile a 2455program. You may think your program is correct, but there is no sense 2456in pushing your luck. For more information, see @ref{Optimized Code}. 2457 2458Older versions of the @sc{gnu} C compiler permitted a variant option 2459@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this 2460format; if your @sc{gnu} C compiler has this option, do not use it. 2461 2462@value{GDBN} knows about preprocessor macros and can show you their 2463expansion (@pxref{Macros}). Most compilers do not include information 2464about preprocessor macros in the debugging information if you specify 2465the @option{-g} flag alone. Version 3.1 and later of @value{NGCC}, 2466the @sc{gnu} C compiler, provides macro information if you are using 2467the DWARF debugging format, and specify the option @option{-g3}. 2468 2469@xref{Debugging Options,,Options for Debugging Your Program or GCC, 2470gcc, Using the @sc{gnu} Compiler Collection (GCC)}, for more 2471information on @value{NGCC} options affecting debug information. 2472 2473You will have the best debugging experience if you use the latest 2474version of the DWARF debugging format that your compiler supports. 2475DWARF is currently the most expressive and best supported debugging 2476format in @value{GDBN}. 2477 2478@need 2000 2479@node Starting 2480@section Starting your Program 2481@cindex starting 2482@cindex running 2483 2484@table @code 2485@kindex run 2486@kindex r @r{(@code{run})} 2487@item run 2488@itemx r 2489Use the @code{run} command to start your program under @value{GDBN}. 2490You must first specify the program name with an argument to 2491@value{GDBN} (@pxref{Invocation, ,Getting In and Out of 2492@value{GDBN}}), or by using the @code{file} or @code{exec-file} 2493command (@pxref{Files, ,Commands to Specify Files}). 2494 2495@end table 2496 2497If you are running your program in an execution environment that 2498supports processes, @code{run} creates an inferior process and makes 2499that process run your program. In some environments without processes, 2500@code{run} jumps to the start of your program. Other targets, 2501like @samp{remote}, are always running. If you get an error 2502message like this one: 2503 2504@smallexample 2505The "remote" target does not support "run". 2506Try "help target" or "continue". 2507@end smallexample 2508 2509@noindent 2510then use @code{continue} to run your program. You may need @code{load} 2511first (@pxref{load}). 2512 2513The execution of a program is affected by certain information it 2514receives from its superior. @value{GDBN} provides ways to specify this 2515information, which you must do @emph{before} starting your program. (You 2516can change it after starting your program, but such changes only affect 2517your program the next time you start it.) This information may be 2518divided into four categories: 2519 2520@table @asis 2521@item The @emph{arguments.} 2522Specify the arguments to give your program as the arguments of the 2523@code{run} command. If a shell is available on your target, the shell 2524is used to pass the arguments, so that you may use normal conventions 2525(such as wildcard expansion or variable substitution) in describing 2526the arguments. 2527In Unix systems, you can control which shell is used with the 2528@env{SHELL} environment variable. If you do not define @env{SHELL}, 2529@value{GDBN} uses the default shell (@file{/bin/sh}). You can disable 2530use of any shell with the @code{set startup-with-shell} command (see 2531below for details). 2532 2533@item The @emph{environment.} 2534Your program normally inherits its environment from @value{GDBN}, but you can 2535use the @value{GDBN} commands @code{set environment} and @code{unset 2536environment} to change parts of the environment that affect 2537your program. @xref{Environment, ,Your Program's Environment}. 2538 2539@item The @emph{working directory.} 2540You can set your program's working directory with the command 2541@kbd{set cwd}. If you do not set any working directory with this 2542command, your program will inherit @value{GDBN}'s working directory if 2543native debugging, or the remote server's working directory if remote 2544debugging. @xref{Working Directory, ,Your Program's Working 2545Directory}. 2546 2547@item The @emph{standard input and output.} 2548Your program normally uses the same device for standard input and 2549standard output as @value{GDBN} is using. You can redirect input and output 2550in the @code{run} command line, or you can use the @code{tty} command to 2551set a different device for your program. 2552@xref{Input/Output, ,Your Program's Input and Output}. 2553 2554@cindex pipes 2555@emph{Warning:} While input and output redirection work, you cannot use 2556pipes to pass the output of the program you are debugging to another 2557program; if you attempt this, @value{GDBN} is likely to wind up debugging the 2558wrong program. 2559@end table 2560 2561When you issue the @code{run} command, your program begins to execute 2562immediately. @xref{Stopping, ,Stopping and Continuing}, for discussion 2563of how to arrange for your program to stop. Once your program has 2564stopped, you may call functions in your program, using the @code{print} 2565or @code{call} commands. @xref{Data, ,Examining Data}. 2566 2567If the modification time of your symbol file has changed since the last 2568time @value{GDBN} read its symbols, @value{GDBN} discards its symbol 2569table, and reads it again. When it does this, @value{GDBN} tries to retain 2570your current breakpoints. 2571 2572@table @code 2573@kindex start 2574@item start 2575@cindex run to main procedure 2576The name of the main procedure can vary from language to language. 2577With C or C@t{++}, the main procedure name is always @code{main}, but 2578other languages such as Ada do not require a specific name for their 2579main procedure. The debugger provides a convenient way to start the 2580execution of the program and to stop at the beginning of the main 2581procedure, depending on the language used. 2582 2583The @samp{start} command does the equivalent of setting a temporary 2584breakpoint at the beginning of the main procedure and then invoking 2585the @samp{run} command. 2586 2587@cindex elaboration phase 2588Some programs contain an @dfn{elaboration} phase where some startup code is 2589executed before the main procedure is called. This depends on the 2590languages used to write your program. In C@t{++}, for instance, 2591constructors for static and global objects are executed before 2592@code{main} is called. It is therefore possible that the debugger stops 2593before reaching the main procedure. However, the temporary breakpoint 2594will remain to halt execution. 2595 2596Specify the arguments to give to your program as arguments to the 2597@samp{start} command. These arguments will be given verbatim to the 2598underlying @samp{run} command. Note that the same arguments will be 2599reused if no argument is provided during subsequent calls to 2600@samp{start} or @samp{run}. 2601 2602It is sometimes necessary to debug the program during elaboration. In 2603these cases, using the @code{start} command would stop the execution 2604of your program too late, as the program would have already completed 2605the elaboration phase. Under these circumstances, either insert 2606breakpoints in your elaboration code before running your program or 2607use the @code{starti} command. 2608 2609@kindex starti 2610@item starti 2611@cindex run to first instruction 2612The @samp{starti} command does the equivalent of setting a temporary 2613breakpoint at the first instruction of a program's execution and then 2614invoking the @samp{run} command. For programs containing an 2615elaboration phase, the @code{starti} command will stop execution at 2616the start of the elaboration phase. 2617 2618@anchor{set exec-wrapper} 2619@kindex set exec-wrapper 2620@item set exec-wrapper @var{wrapper} 2621@itemx show exec-wrapper 2622@itemx unset exec-wrapper 2623When @samp{exec-wrapper} is set, the specified wrapper is used to 2624launch programs for debugging. @value{GDBN} starts your program 2625with a shell command of the form @kbd{exec @var{wrapper} 2626@var{program}}. Quoting is added to @var{program} and its 2627arguments, but not to @var{wrapper}, so you should add quotes if 2628appropriate for your shell. The wrapper runs until it executes 2629your program, and then @value{GDBN} takes control. 2630 2631You can use any program that eventually calls @code{execve} with 2632its arguments as a wrapper. Several standard Unix utilities do 2633this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending 2634with @code{exec "$@@"} will also work. 2635 2636For example, you can use @code{env} to pass an environment variable to 2637the debugged program, without setting the variable in your shell's 2638environment: 2639 2640@smallexample 2641(@value{GDBP}) set exec-wrapper env 'LD_PRELOAD=libtest.so' 2642(@value{GDBP}) run 2643@end smallexample 2644 2645This command is available when debugging locally on most targets, excluding 2646@sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino. 2647 2648@kindex set startup-with-shell 2649@anchor{set startup-with-shell} 2650@item set startup-with-shell 2651@itemx set startup-with-shell on 2652@itemx set startup-with-shell off 2653@itemx show startup-with-shell 2654On Unix systems, by default, if a shell is available on your target, 2655@value{GDBN}) uses it to start your program. Arguments of the 2656@code{run} command are passed to the shell, which does variable 2657substitution, expands wildcard characters and performs redirection of 2658I/O. In some circumstances, it may be useful to disable such use of a 2659shell, for example, when debugging the shell itself or diagnosing 2660startup failures such as: 2661 2662@smallexample 2663(@value{GDBP}) run 2664Starting program: ./a.out 2665During startup program terminated with signal SIGSEGV, Segmentation fault. 2666@end smallexample 2667 2668@noindent 2669which indicates the shell or the wrapper specified with 2670@samp{exec-wrapper} crashed, not your program. Most often, this is 2671caused by something odd in your shell's non-interactive mode 2672initialization file---such as @file{.cshrc} for C-shell, 2673$@file{.zshenv} for the Z shell, or the file specified in the 2674@env{BASH_ENV} environment variable for BASH. 2675 2676@anchor{set auto-connect-native-target} 2677@kindex set auto-connect-native-target 2678@item set auto-connect-native-target 2679@itemx set auto-connect-native-target on 2680@itemx set auto-connect-native-target off 2681@itemx show auto-connect-native-target 2682 2683By default, if the current inferior is not connected to any target yet 2684(e.g., with @code{target remote}), the @code{run} command starts your 2685program as a native process under @value{GDBN}, on your local machine. 2686If you're sure you don't want to debug programs on your local machine, 2687you can tell @value{GDBN} to not connect to the native target 2688automatically with the @code{set auto-connect-native-target off} 2689command. 2690 2691If @code{on}, which is the default, and if the current inferior is not 2692connected to a target already, the @code{run} command automaticaly 2693connects to the native target, if one is available. 2694 2695If @code{off}, and if the current inferior is not connected to a 2696target already, the @code{run} command fails with an error: 2697 2698@smallexample 2699(@value{GDBP}) run 2700Don't know how to run. Try "help target". 2701@end smallexample 2702 2703If the current inferior is already connected to a target, @value{GDBN} 2704always uses it with the @code{run} command. 2705 2706In any case, you can explicitly connect to the native target with the 2707@code{target native} command. For example, 2708 2709@smallexample 2710(@value{GDBP}) set auto-connect-native-target off 2711(@value{GDBP}) run 2712Don't know how to run. Try "help target". 2713(@value{GDBP}) target native 2714(@value{GDBP}) run 2715Starting program: ./a.out 2716[Inferior 1 (process 10421) exited normally] 2717@end smallexample 2718 2719In case you connected explicitly to the @code{native} target, 2720@value{GDBN} remains connected even if all inferiors exit, ready for 2721the next @code{run} command. Use the @code{disconnect} command to 2722disconnect. 2723 2724Examples of other commands that likewise respect the 2725@code{auto-connect-native-target} setting: @code{attach}, @code{info 2726proc}, @code{info os}. 2727 2728@kindex set disable-randomization 2729@item set disable-randomization 2730@itemx set disable-randomization on 2731This option (enabled by default in @value{GDBN}) will turn off the native 2732randomization of the virtual address space of the started program. This option 2733is useful for multiple debugging sessions to make the execution better 2734reproducible and memory addresses reusable across debugging sessions. 2735 2736This feature is implemented only on certain targets, including @sc{gnu}/Linux. 2737On @sc{gnu}/Linux you can get the same behavior using 2738 2739@smallexample 2740(@value{GDBP}) set exec-wrapper setarch `uname -m` -R 2741@end smallexample 2742 2743@item set disable-randomization off 2744Leave the behavior of the started executable unchanged. Some bugs rear their 2745ugly heads only when the program is loaded at certain addresses. If your bug 2746disappears when you run the program under @value{GDBN}, that might be because 2747@value{GDBN} by default disables the address randomization on platforms, such 2748as @sc{gnu}/Linux, which do that for stand-alone programs. Use @kbd{set 2749disable-randomization off} to try to reproduce such elusive bugs. 2750 2751On targets where it is available, virtual address space randomization 2752protects the programs against certain kinds of security attacks. In these 2753cases the attacker needs to know the exact location of a concrete executable 2754code. Randomizing its location makes it impossible to inject jumps misusing 2755a code at its expected addresses. 2756 2757Prelinking shared libraries provides a startup performance advantage but it 2758makes addresses in these libraries predictable for privileged processes by 2759having just unprivileged access at the target system. Reading the shared 2760library binary gives enough information for assembling the malicious code 2761misusing it. Still even a prelinked shared library can get loaded at a new 2762random address just requiring the regular relocation process during the 2763startup. Shared libraries not already prelinked are always loaded at 2764a randomly chosen address. 2765 2766Position independent executables (PIE) contain position independent code 2767similar to the shared libraries and therefore such executables get loaded at 2768a randomly chosen address upon startup. PIE executables always load even 2769already prelinked shared libraries at a random address. You can build such 2770executable using @command{gcc -fPIE -pie}. 2771 2772Heap (malloc storage), stack and custom mmap areas are always placed randomly 2773(as long as the randomization is enabled). 2774 2775@item show disable-randomization 2776Show the current setting of the explicit disable of the native randomization of 2777the virtual address space of the started program. 2778 2779@end table 2780 2781@node Arguments 2782@section Your Program's Arguments 2783 2784@cindex arguments (to your program) 2785The arguments to your program can be specified by the arguments of the 2786@code{run} command. 2787They are passed to a shell, which expands wildcard characters and 2788performs redirection of I/O, and thence to your program. Your 2789@env{SHELL} environment variable (if it exists) specifies what shell 2790@value{GDBN} uses. If you do not define @env{SHELL}, @value{GDBN} uses 2791the default shell (@file{/bin/sh} on Unix). 2792 2793On non-Unix systems, the program is usually invoked directly by 2794@value{GDBN}, which emulates I/O redirection via the appropriate system 2795calls, and the wildcard characters are expanded by the startup code of 2796the program, not by the shell. 2797 2798@code{run} with no arguments uses the same arguments used by the previous 2799@code{run}, or those set by the @code{set args} command. 2800 2801@table @code 2802@kindex set args 2803@item set args 2804Specify the arguments to be used the next time your program is run. If 2805@code{set args} has no arguments, @code{run} executes your program 2806with no arguments. Once you have run your program with arguments, 2807using @code{set args} before the next @code{run} is the only way to run 2808it again without arguments. 2809 2810@kindex show args 2811@item show args 2812Show the arguments to give your program when it is started. 2813@end table 2814 2815@node Environment 2816@section Your Program's Environment 2817 2818@cindex environment (of your program) 2819The @dfn{environment} consists of a set of environment variables and 2820their values. Environment variables conventionally record such things as 2821your user name, your home directory, your terminal type, and your search 2822path for programs to run. Usually you set up environment variables with 2823the shell and they are inherited by all the other programs you run. When 2824debugging, it can be useful to try running your program with a modified 2825environment without having to start @value{GDBN} over again. 2826 2827@table @code 2828@kindex path 2829@item path @var{directory} 2830Add @var{directory} to the front of the @env{PATH} environment variable 2831(the search path for executables) that will be passed to your program. 2832The value of @env{PATH} used by @value{GDBN} does not change. 2833You may specify several directory names, separated by whitespace or by a 2834system-dependent separator character (@samp{:} on Unix, @samp{;} on 2835MS-DOS and MS-Windows). If @var{directory} is already in the path, it 2836is moved to the front, so it is searched sooner. 2837 2838You can use the string @samp{$cwd} to refer to whatever is the current 2839working directory at the time @value{GDBN} searches the path. If you 2840use @samp{.} instead, it refers to the directory where you executed the 2841@code{path} command. @value{GDBN} replaces @samp{.} in the 2842@var{directory} argument (with the current path) before adding 2843@var{directory} to the search path. 2844@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to 2845@c document that, since repeating it would be a no-op. 2846 2847@kindex show paths 2848@item show paths 2849Display the list of search paths for executables (the @env{PATH} 2850environment variable). 2851 2852@kindex show environment 2853@item show environment @r{[}@var{varname}@r{]} 2854Print the value of environment variable @var{varname} to be given to 2855your program when it starts. If you do not supply @var{varname}, 2856print the names and values of all environment variables to be given to 2857your program. You can abbreviate @code{environment} as @code{env}. 2858 2859@kindex set environment 2860@anchor{set environment} 2861@item set environment @var{varname} @r{[}=@var{value}@r{]} 2862Set environment variable @var{varname} to @var{value}. The value 2863changes for your program (and the shell @value{GDBN} uses to launch 2864it), not for @value{GDBN} itself. The @var{value} may be any string; the 2865values of environment variables are just strings, and any 2866interpretation is supplied by your program itself. The @var{value} 2867parameter is optional; if it is eliminated, the variable is set to a 2868null value. 2869@c "any string" here does not include leading, trailing 2870@c blanks. Gnu asks: does anyone care? 2871 2872For example, this command: 2873 2874@smallexample 2875set env USER = foo 2876@end smallexample 2877 2878@noindent 2879tells the debugged program, when subsequently run, that its user is named 2880@samp{foo}. (The spaces around @samp{=} are used for clarity here; they 2881are not actually required.) 2882 2883Note that on Unix systems, @value{GDBN} runs your program via a shell, 2884which also inherits the environment set with @code{set environment}. 2885If necessary, you can avoid that by using the @samp{env} program as a 2886wrapper instead of using @code{set environment}. @xref{set 2887exec-wrapper}, for an example doing just that. 2888 2889Environment variables that are set by the user are also transmitted to 2890@command{gdbserver} to be used when starting the remote inferior. 2891@pxref{QEnvironmentHexEncoded}. 2892 2893@kindex unset environment 2894@anchor{unset environment} 2895@item unset environment @var{varname} 2896Remove variable @var{varname} from the environment to be passed to your 2897program. This is different from @samp{set env @var{varname} =}; 2898@code{unset environment} removes the variable from the environment, 2899rather than assigning it an empty value. 2900 2901Environment variables that are unset by the user are also unset on 2902@command{gdbserver} when starting the remote inferior. 2903@pxref{QEnvironmentUnset}. 2904@end table 2905 2906@emph{Warning:} On Unix systems, @value{GDBN} runs your program using 2907the shell indicated by your @env{SHELL} environment variable if it 2908exists (or @code{/bin/sh} if not). If your @env{SHELL} variable 2909names a shell that runs an initialization file when started 2910non-interactively---such as @file{.cshrc} for C-shell, $@file{.zshenv} 2911for the Z shell, or the file specified in the @env{BASH_ENV} 2912environment variable for BASH---any variables you set in that file 2913affect your program. You may wish to move setting of environment 2914variables to files that are only run when you sign on, such as 2915@file{.login} or @file{.profile}. 2916 2917@node Working Directory 2918@section Your Program's Working Directory 2919 2920@cindex working directory (of your program) 2921Each time you start your program with @code{run}, the inferior will be 2922initialized with the current working directory specified by the 2923@kbd{set cwd} command. If no directory has been specified by this 2924command, then the inferior will inherit @value{GDBN}'s current working 2925directory as its working directory if native debugging, or it will 2926inherit the remote server's current working directory if remote 2927debugging. 2928 2929@table @code 2930@kindex set cwd 2931@cindex change inferior's working directory 2932@anchor{set cwd command} 2933@item set cwd @r{[}@var{directory}@r{]} 2934Set the inferior's working directory to @var{directory}, which will be 2935@code{glob}-expanded in order to resolve tildes (@file{~}). If no 2936argument has been specified, the command clears the setting and resets 2937it to an empty state. This setting has no effect on @value{GDBN}'s 2938working directory, and it only takes effect the next time you start 2939the inferior. The @file{~} in @var{directory} is a short for the 2940@dfn{home directory}, usually pointed to by the @env{HOME} environment 2941variable. On MS-Windows, if @env{HOME} is not defined, @value{GDBN} 2942uses the concatenation of @env{HOMEDRIVE} and @env{HOMEPATH} as 2943fallback. 2944 2945You can also change @value{GDBN}'s current working directory by using 2946the @code{cd} command. 2947@xref{cd command}. 2948 2949@kindex show cwd 2950@cindex show inferior's working directory 2951@item show cwd 2952Show the inferior's working directory. If no directory has been 2953specified by @kbd{set cwd}, then the default inferior's working 2954directory is the same as @value{GDBN}'s working directory. 2955 2956@kindex cd 2957@cindex change @value{GDBN}'s working directory 2958@anchor{cd command} 2959@item cd @r{[}@var{directory}@r{]} 2960Set the @value{GDBN} working directory to @var{directory}. If not 2961given, @var{directory} uses @file{'~'}. 2962 2963The @value{GDBN} working directory serves as a default for the 2964commands that specify files for @value{GDBN} to operate on. 2965@xref{Files, ,Commands to Specify Files}. 2966@xref{set cwd command}. 2967 2968@kindex pwd 2969@item pwd 2970Print the @value{GDBN} working directory. 2971@end table 2972 2973It is generally impossible to find the current working directory of 2974the process being debugged (since a program can change its directory 2975during its run). If you work on a system where @value{GDBN} supports 2976the @code{info proc} command (@pxref{Process Information}), you can 2977use the @code{info proc} command to find out the 2978current working directory of the debuggee. 2979 2980@node Input/Output 2981@section Your Program's Input and Output 2982 2983@cindex redirection 2984@cindex i/o 2985@cindex terminal 2986By default, the program you run under @value{GDBN} does input and output to 2987the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal 2988to its own terminal modes to interact with you, but it records the terminal 2989modes your program was using and switches back to them when you continue 2990running your program. 2991 2992@table @code 2993@kindex info terminal 2994@item info terminal 2995Displays information recorded by @value{GDBN} about the terminal modes your 2996program is using. 2997@end table 2998 2999You can redirect your program's input and/or output using shell 3000redirection with the @code{run} command. For example, 3001 3002@smallexample 3003run > outfile 3004@end smallexample 3005 3006@noindent 3007starts your program, diverting its output to the file @file{outfile}. 3008 3009@kindex tty 3010@cindex controlling terminal 3011Another way to specify where your program should do input and output is 3012with the @code{tty} command. This command accepts a file name as 3013argument, and causes this file to be the default for future @code{run} 3014commands. It also resets the controlling terminal for the child 3015process, for future @code{run} commands. For example, 3016 3017@smallexample 3018tty /dev/ttyb 3019@end smallexample 3020 3021@noindent 3022directs that processes started with subsequent @code{run} commands 3023default to do input and output on the terminal @file{/dev/ttyb} and have 3024that as their controlling terminal. 3025 3026An explicit redirection in @code{run} overrides the @code{tty} command's 3027effect on the input/output device, but not its effect on the controlling 3028terminal. 3029 3030When you use the @code{tty} command or redirect input in the @code{run} 3031command, only the input @emph{for your program} is affected. The input 3032for @value{GDBN} still comes from your terminal. @code{tty} is an alias 3033for @code{set inferior-tty}. 3034 3035@cindex inferior tty 3036@cindex set inferior controlling terminal 3037You can use the @code{show inferior-tty} command to tell @value{GDBN} to 3038display the name of the terminal that will be used for future runs of your 3039program. 3040 3041@table @code 3042@item set inferior-tty [ @var{tty} ] 3043@kindex set inferior-tty 3044Set the tty for the program being debugged to @var{tty}. Omitting @var{tty} 3045restores the default behavior, which is to use the same terminal as 3046@value{GDBN}. 3047 3048@item show inferior-tty 3049@kindex show inferior-tty 3050Show the current tty for the program being debugged. 3051@end table 3052 3053@node Attach 3054@section Debugging an Already-running Process 3055@kindex attach 3056@cindex attach 3057 3058@table @code 3059@item attach @var{process-id} 3060This command attaches to a running process---one that was started 3061outside @value{GDBN}. (@code{info files} shows your active 3062targets.) The command takes as argument a process ID. The usual way to 3063find out the @var{process-id} of a Unix process is with the @code{ps} utility, 3064or with the @samp{jobs -l} shell command. 3065 3066@code{attach} does not repeat if you press @key{RET} a second time after 3067executing the command. 3068@end table 3069 3070To use @code{attach}, your program must be running in an environment 3071which supports processes; for example, @code{attach} does not work for 3072programs on bare-board targets that lack an operating system. You must 3073also have permission to send the process a signal. 3074 3075When you use @code{attach}, the debugger finds the program running in 3076the process first by looking in the current working directory, then (if 3077the program is not found) by using the source file search path 3078(@pxref{Source Path, ,Specifying Source Directories}). You can also use 3079the @code{file} command to load the program. @xref{Files, ,Commands to 3080Specify Files}. 3081 3082@anchor{set exec-file-mismatch} 3083If the debugger can determine that the executable file running in the 3084process it is attaching to does not match the current exec-file loaded 3085by @value{GDBN}, the option @code{exec-file-mismatch} specifies how to 3086handle the mismatch. @value{GDBN} tries to compare the files by 3087comparing their build IDs (@pxref{build ID}), if available. 3088 3089@table @code 3090@kindex exec-file-mismatch 3091@cindex set exec-file-mismatch 3092@item set exec-file-mismatch @samp{ask|warn|off} 3093 3094Whether to detect mismatch between the current executable file loaded 3095by @value{GDBN} and the executable file used to start the process. If 3096@samp{ask}, the default, display a warning and ask the user whether to 3097load the process executable file; if @samp{warn}, just display a 3098warning; if @samp{off}, don't attempt to detect a mismatch. 3099If the user confirms loading the process executable file, then its symbols 3100will be loaded as well. 3101 3102@cindex show exec-file-mismatch 3103@item show exec-file-mismatch 3104Show the current value of @code{exec-file-mismatch}. 3105 3106@end table 3107 3108The first thing @value{GDBN} does after arranging to debug the specified 3109process is to stop it. You can examine and modify an attached process 3110with all the @value{GDBN} commands that are ordinarily available when 3111you start processes with @code{run}. You can insert breakpoints; you 3112can step and continue; you can modify storage. If you would rather the 3113process continue running, you may use the @code{continue} command after 3114attaching @value{GDBN} to the process. 3115 3116@table @code 3117@kindex detach 3118@item detach 3119When you have finished debugging the attached process, you can use the 3120@code{detach} command to release it from @value{GDBN} control. Detaching 3121the process continues its execution. After the @code{detach} command, 3122that process and @value{GDBN} become completely independent once more, and you 3123are ready to @code{attach} another process or start one with @code{run}. 3124@code{detach} does not repeat if you press @key{RET} again after 3125executing the command. 3126@end table 3127 3128If you exit @value{GDBN} while you have an attached process, you detach 3129that process. If you use the @code{run} command, you kill that process. 3130By default, @value{GDBN} asks for confirmation if you try to do either of these 3131things; you can control whether or not you need to confirm by using the 3132@code{set confirm} command (@pxref{Messages/Warnings, ,Optional Warnings and 3133Messages}). 3134 3135@node Kill Process 3136@section Killing the Child Process 3137 3138@table @code 3139@kindex kill 3140@item kill 3141Kill the child process in which your program is running under @value{GDBN}. 3142@end table 3143 3144This command is useful if you wish to debug a core dump instead of a 3145running process. @value{GDBN} ignores any core dump file while your program 3146is running. 3147 3148On some operating systems, a program cannot be executed outside @value{GDBN} 3149while you have breakpoints set on it inside @value{GDBN}. You can use the 3150@code{kill} command in this situation to permit running your program 3151outside the debugger. 3152 3153The @code{kill} command is also useful if you wish to recompile and 3154relink your program, since on many systems it is impossible to modify an 3155executable file while it is running in a process. In this case, when you 3156next type @code{run}, @value{GDBN} notices that the file has changed, and 3157reads the symbol table again (while trying to preserve your current 3158breakpoint settings). 3159 3160@node Inferiors Connections and Programs 3161@section Debugging Multiple Inferiors Connections and Programs 3162 3163@value{GDBN} lets you run and debug multiple programs in a single 3164session. In addition, @value{GDBN} on some systems may let you run 3165several programs simultaneously (otherwise you have to exit from one 3166before starting another). On some systems @value{GDBN} may even let 3167you debug several programs simultaneously on different remote systems. 3168In the most general case, you can have multiple threads of execution 3169in each of multiple processes, launched from multiple executables, 3170running on different machines. 3171 3172@cindex inferior 3173@value{GDBN} represents the state of each program execution with an 3174object called an @dfn{inferior}. An inferior typically corresponds to 3175a process, but is more general and applies also to targets that do not 3176have processes. Inferiors may be created before a process runs, and 3177may be retained after a process exits. Inferiors have unique 3178identifiers that are different from process ids. Usually each 3179inferior will also have its own distinct address space, although some 3180embedded targets may have several inferiors running in different parts 3181of a single address space. Each inferior may in turn have multiple 3182threads running in it. 3183 3184To find out what inferiors exist at any moment, use @w{@code{info 3185inferiors}}: 3186 3187@table @code 3188@kindex info inferiors [ @var{id}@dots{} ] 3189@item info inferiors 3190Print a list of all inferiors currently being managed by @value{GDBN}. 3191By default all inferiors are printed, but the argument @var{id}@dots{} 3192-- a space separated list of inferior numbers -- can be used to limit 3193the display to just the requested inferiors. 3194 3195@value{GDBN} displays for each inferior (in this order): 3196 3197@enumerate 3198@item 3199the inferior number assigned by @value{GDBN} 3200 3201@item 3202the target system's inferior identifier 3203 3204@item 3205the target connection the inferior is bound to, including the unique 3206connection number assigned by @value{GDBN}, and the protocol used by 3207the connection. 3208 3209@item 3210the name of the executable the inferior is running. 3211 3212@end enumerate 3213 3214@noindent 3215An asterisk @samp{*} preceding the @value{GDBN} inferior number 3216indicates the current inferior. 3217 3218For example, 3219@end table 3220@c end table here to get a little more width for example 3221 3222@smallexample 3223(@value{GDBP}) info inferiors 3224 Num Description Connection Executable 3225* 1 process 3401 1 (native) goodbye 3226 2 process 2307 2 (extended-remote host:10000) hello 3227@end smallexample 3228 3229To get informations about the current inferior, use @code{inferior}: 3230 3231@table @code 3232@kindex inferior 3233@item inferior 3234Shows information about the current inferior. 3235 3236For example, 3237@end table 3238@c end table here to get a little more width for example 3239 3240@smallexample 3241(@value{GDBP}) inferior 3242[Current inferior is 1 [process 3401] (helloworld)] 3243@end smallexample 3244 3245To find out what open target connections exist at any moment, use 3246@w{@code{info connections}}: 3247 3248@table @code 3249@kindex info connections [ @var{id}@dots{} ] 3250@item info connections 3251Print a list of all open target connections currently being managed by 3252@value{GDBN}. By default all connections are printed, but the 3253argument @var{id}@dots{} -- a space separated list of connections 3254numbers -- can be used to limit the display to just the requested 3255connections. 3256 3257@value{GDBN} displays for each connection (in this order): 3258 3259@enumerate 3260@item 3261the connection number assigned by @value{GDBN}. 3262 3263@item 3264the protocol used by the connection. 3265 3266@item 3267a textual description of the protocol used by the connection. 3268 3269@end enumerate 3270 3271@noindent 3272An asterisk @samp{*} preceding the connection number indicates the 3273connection of the current inferior. 3274 3275For example, 3276@end table 3277@c end table here to get a little more width for example 3278 3279@smallexample 3280(@value{GDBP}) info connections 3281 Num What Description 3282* 1 extended-remote host:10000 Extended remote serial target in gdb-specific protocol 3283 2 native Native process 3284 3 core Local core dump file 3285@end smallexample 3286 3287To switch focus between inferiors, use the @code{inferior} command: 3288 3289@table @code 3290@kindex inferior @var{infno} 3291@item inferior @var{infno} 3292Make inferior number @var{infno} the current inferior. The argument 3293@var{infno} is the inferior number assigned by @value{GDBN}, as shown 3294in the first field of the @samp{info inferiors} display. 3295@end table 3296 3297@vindex $_inferior@r{, convenience variable} 3298The debugger convenience variable @samp{$_inferior} contains the 3299number of the current inferior. You may find this useful in writing 3300breakpoint conditional expressions, command scripts, and so forth. 3301@xref{Convenience Vars,, Convenience Variables}, for general 3302information on convenience variables. 3303 3304You can get multiple executables into a debugging session via the 3305@code{add-inferior} and @w{@code{clone-inferior}} commands. On some 3306systems @value{GDBN} can add inferiors to the debug session 3307automatically by following calls to @code{fork} and @code{exec}. To 3308remove inferiors from the debugging session use the 3309@w{@code{remove-inferiors}} command. 3310 3311@table @code 3312@kindex add-inferior 3313@item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ] [-no-connection ] 3314Adds @var{n} inferiors to be run using @var{executable} as the 3315executable; @var{n} defaults to 1. If no executable is specified, 3316the inferiors begins empty, with no program. You can still assign or 3317change the program assigned to the inferior at any time by using the 3318@code{file} command with the executable name as its argument. 3319 3320By default, the new inferior begins connected to the same target 3321connection as the current inferior. For example, if the current 3322inferior was connected to @code{gdbserver} with @code{target remote}, 3323then the new inferior will be connected to the same @code{gdbserver} 3324instance. The @samp{-no-connection} option starts the new inferior 3325with no connection yet. You can then for example use the @code{target 3326remote} command to connect to some other @code{gdbserver} instance, 3327use @code{run} to spawn a local program, etc. 3328 3329@kindex clone-inferior 3330@item clone-inferior [ -copies @var{n} ] [ @var{infno} ] 3331Adds @var{n} inferiors ready to execute the same program as inferior 3332@var{infno}; @var{n} defaults to 1, and @var{infno} defaults to the 3333number of the current inferior. This is a convenient command when you 3334want to run another instance of the inferior you are debugging. 3335 3336@smallexample 3337(@value{GDBP}) info inferiors 3338 Num Description Connection Executable 3339* 1 process 29964 1 (native) helloworld 3340(@value{GDBP}) clone-inferior 3341Added inferior 2. 33421 inferiors added. 3343(@value{GDBP}) info inferiors 3344 Num Description Connection Executable 3345* 1 process 29964 1 (native) helloworld 3346 2 <null> 1 (native) helloworld 3347@end smallexample 3348 3349You can now simply switch focus to inferior 2 and run it. 3350 3351@kindex remove-inferiors 3352@item remove-inferiors @var{infno}@dots{} 3353Removes the inferior or inferiors @var{infno}@dots{}. It is not 3354possible to remove an inferior that is running with this command. For 3355those, use the @code{kill} or @code{detach} command first. 3356 3357@end table 3358 3359To quit debugging one of the running inferiors that is not the current 3360inferior, you can either detach from it by using the @w{@code{detach 3361inferior}} command (allowing it to run independently), or kill it 3362using the @w{@code{kill inferiors}} command: 3363 3364@table @code 3365@kindex detach inferiors @var{infno}@dots{} 3366@item detach inferior @var{infno}@dots{} 3367Detach from the inferior or inferiors identified by @value{GDBN} 3368inferior number(s) @var{infno}@dots{}. Note that the inferior's entry 3369still stays on the list of inferiors shown by @code{info inferiors}, 3370but its Description will show @samp{<null>}. 3371 3372@kindex kill inferiors @var{infno}@dots{} 3373@item kill inferiors @var{infno}@dots{} 3374Kill the inferior or inferiors identified by @value{GDBN} inferior 3375number(s) @var{infno}@dots{}. Note that the inferior's entry still 3376stays on the list of inferiors shown by @code{info inferiors}, but its 3377Description will show @samp{<null>}. 3378@end table 3379 3380After the successful completion of a command such as @code{detach}, 3381@code{detach inferiors}, @code{kill} or @code{kill inferiors}, or after 3382a normal process exit, the inferior is still valid and listed with 3383@code{info inferiors}, ready to be restarted. 3384 3385 3386To be notified when inferiors are started or exit under @value{GDBN}'s 3387control use @w{@code{set print inferior-events}}: 3388 3389@table @code 3390@kindex set print inferior-events 3391@cindex print messages on inferior start and exit 3392@item set print inferior-events 3393@itemx set print inferior-events on 3394@itemx set print inferior-events off 3395The @code{set print inferior-events} command allows you to enable or 3396disable printing of messages when @value{GDBN} notices that new 3397inferiors have started or that inferiors have exited or have been 3398detached. By default, these messages will not be printed. 3399 3400@kindex show print inferior-events 3401@item show print inferior-events 3402Show whether messages will be printed when @value{GDBN} detects that 3403inferiors have started, exited or have been detached. 3404@end table 3405 3406Many commands will work the same with multiple programs as with a 3407single program: e.g., @code{print myglobal} will simply display the 3408value of @code{myglobal} in the current inferior. 3409 3410 3411Occasionally, when debugging @value{GDBN} itself, it may be useful to 3412get more info about the relationship of inferiors, programs, address 3413spaces in a debug session. You can do that with the @w{@code{maint 3414info program-spaces}} command. 3415 3416@table @code 3417@kindex maint info program-spaces 3418@item maint info program-spaces 3419Print a list of all program spaces currently being managed by 3420@value{GDBN}. 3421 3422@value{GDBN} displays for each program space (in this order): 3423 3424@enumerate 3425@item 3426the program space number assigned by @value{GDBN} 3427 3428@item 3429the name of the executable loaded into the program space, with e.g., 3430the @code{file} command. 3431 3432@end enumerate 3433 3434@noindent 3435An asterisk @samp{*} preceding the @value{GDBN} program space number 3436indicates the current program space. 3437 3438In addition, below each program space line, @value{GDBN} prints extra 3439information that isn't suitable to display in tabular form. For 3440example, the list of inferiors bound to the program space. 3441 3442@smallexample 3443(@value{GDBP}) maint info program-spaces 3444 Id Executable 3445* 1 hello 3446 2 goodbye 3447 Bound inferiors: ID 1 (process 21561) 3448@end smallexample 3449 3450Here we can see that no inferior is running the program @code{hello}, 3451while @code{process 21561} is running the program @code{goodbye}. On 3452some targets, it is possible that multiple inferiors are bound to the 3453same program space. The most common example is that of debugging both 3454the parent and child processes of a @code{vfork} call. For example, 3455 3456@smallexample 3457(@value{GDBP}) maint info program-spaces 3458 Id Executable 3459* 1 vfork-test 3460 Bound inferiors: ID 2 (process 18050), ID 1 (process 18045) 3461@end smallexample 3462 3463Here, both inferior 2 and inferior 1 are running in the same program 3464space as a result of inferior 1 having executed a @code{vfork} call. 3465@end table 3466 3467@node Threads 3468@section Debugging Programs with Multiple Threads 3469 3470@cindex threads of execution 3471@cindex multiple threads 3472@cindex switching threads 3473In some operating systems, such as GNU/Linux and Solaris, a single program 3474may have more than one @dfn{thread} of execution. The precise semantics 3475of threads differ from one operating system to another, but in general 3476the threads of a single program are akin to multiple processes---except 3477that they share one address space (that is, they can all examine and 3478modify the same variables). On the other hand, each thread has its own 3479registers and execution stack, and perhaps private memory. 3480 3481@value{GDBN} provides these facilities for debugging multi-thread 3482programs: 3483 3484@itemize @bullet 3485@item automatic notification of new threads 3486@item @samp{thread @var{thread-id}}, a command to switch among threads 3487@item @samp{info threads}, a command to inquire about existing threads 3488@item @samp{thread apply [@var{thread-id-list} | all] @var{args}}, 3489a command to apply a command to a list of threads 3490@item thread-specific breakpoints 3491@item @samp{set print thread-events}, which controls printing of 3492messages on thread start and exit. 3493@item @samp{set libthread-db-search-path @var{path}}, which lets 3494the user specify which @code{libthread_db} to use if the default choice 3495isn't compatible with the program. 3496@end itemize 3497 3498@cindex focus of debugging 3499@cindex current thread 3500The @value{GDBN} thread debugging facility allows you to observe all 3501threads while your program runs---but whenever @value{GDBN} takes 3502control, one thread in particular is always the focus of debugging. 3503This thread is called the @dfn{current thread}. Debugging commands show 3504program information from the perspective of the current thread. 3505 3506@cindex @code{New} @var{systag} message 3507@cindex thread identifier (system) 3508@c FIXME-implementors!! It would be more helpful if the [New...] message 3509@c included GDB's numeric thread handle, so you could just go to that 3510@c thread without first checking `info threads'. 3511Whenever @value{GDBN} detects a new thread in your program, it displays 3512the target system's identification for the thread with a message in the 3513form @samp{[New @var{systag}]}, where @var{systag} is a thread identifier 3514whose form varies depending on the particular system. For example, on 3515@sc{gnu}/Linux, you might see 3516 3517@smallexample 3518[New Thread 0x41e02940 (LWP 25582)] 3519@end smallexample 3520 3521@noindent 3522when @value{GDBN} notices a new thread. In contrast, on other systems, 3523the @var{systag} is simply something like @samp{process 368}, with no 3524further qualifier. 3525 3526@c FIXME!! (1) Does the [New...] message appear even for the very first 3527@c thread of a program, or does it only appear for the 3528@c second---i.e.@: when it becomes obvious we have a multithread 3529@c program? 3530@c (2) *Is* there necessarily a first thread always? Or do some 3531@c multithread systems permit starting a program with multiple 3532@c threads ab initio? 3533 3534@anchor{thread numbers} 3535@cindex thread number, per inferior 3536@cindex thread identifier (GDB) 3537For debugging purposes, @value{GDBN} associates its own thread number 3538---always a single integer---with each thread of an inferior. This 3539number is unique between all threads of an inferior, but not unique 3540between threads of different inferiors. 3541 3542@cindex qualified thread ID 3543You can refer to a given thread in an inferior using the qualified 3544@var{inferior-num}.@var{thread-num} syntax, also known as 3545@dfn{qualified thread ID}, with @var{inferior-num} being the inferior 3546number and @var{thread-num} being the thread number of the given 3547inferior. For example, thread @code{2.3} refers to thread number 3 of 3548inferior 2. If you omit @var{inferior-num} (e.g., @code{thread 3}), 3549then @value{GDBN} infers you're referring to a thread of the current 3550inferior. 3551 3552Until you create a second inferior, @value{GDBN} does not show the 3553@var{inferior-num} part of thread IDs, even though you can always use 3554the full @var{inferior-num}.@var{thread-num} form to refer to threads 3555of inferior 1, the initial inferior. 3556 3557@anchor{thread ID lists} 3558@cindex thread ID lists 3559Some commands accept a space-separated @dfn{thread ID list} as 3560argument. A list element can be: 3561 3562@enumerate 3563@item 3564A thread ID as shown in the first field of the @samp{info threads} 3565display, with or without an inferior qualifier. E.g., @samp{2.1} or 3566@samp{1}. 3567 3568@item 3569A range of thread numbers, again with or without an inferior 3570qualifier, as in @var{inf}.@var{thr1}-@var{thr2} or 3571@var{thr1}-@var{thr2}. E.g., @samp{1.2-4} or @samp{2-4}. 3572 3573@item 3574All threads of an inferior, specified with a star wildcard, with or 3575without an inferior qualifier, as in @var{inf}.@code{*} (e.g., 3576@samp{1.*}) or @code{*}. The former refers to all threads of the 3577given inferior, and the latter form without an inferior qualifier 3578refers to all threads of the current inferior. 3579 3580@end enumerate 3581 3582For example, if the current inferior is 1, and inferior 7 has one 3583thread with ID 7.1, the thread list @samp{1 2-3 4.5 6.7-9 7.*} 3584includes threads 1 to 3 of inferior 1, thread 5 of inferior 4, threads 35857 to 9 of inferior 6 and all threads of inferior 7. That is, in 3586expanded qualified form, the same as @samp{1.1 1.2 1.3 4.5 6.7 6.8 6.9 35877.1}. 3588 3589 3590@anchor{global thread numbers} 3591@cindex global thread number 3592@cindex global thread identifier (GDB) 3593In addition to a @emph{per-inferior} number, each thread is also 3594assigned a unique @emph{global} number, also known as @dfn{global 3595thread ID}, a single integer. Unlike the thread number component of 3596the thread ID, no two threads have the same global ID, even when 3597you're debugging multiple inferiors. 3598 3599From @value{GDBN}'s perspective, a process always has at least one 3600thread. In other words, @value{GDBN} assigns a thread number to the 3601program's ``main thread'' even if the program is not multi-threaded. 3602 3603@vindex $_thread@r{, convenience variable} 3604@vindex $_gthread@r{, convenience variable} 3605The debugger convenience variables @samp{$_thread} and 3606@samp{$_gthread} contain, respectively, the per-inferior thread number 3607and the global thread number of the current thread. You may find this 3608useful in writing breakpoint conditional expressions, command scripts, 3609and so forth. @xref{Convenience Vars,, Convenience Variables}, for 3610general information on convenience variables. 3611 3612If @value{GDBN} detects the program is multi-threaded, it augments the 3613usual message about stopping at a breakpoint with the ID and name of 3614the thread that hit the breakpoint. 3615 3616@smallexample 3617Thread 2 "client" hit Breakpoint 1, send_message () at client.c:68 3618@end smallexample 3619 3620Likewise when the program receives a signal: 3621 3622@smallexample 3623Thread 1 "main" received signal SIGINT, Interrupt. 3624@end smallexample 3625 3626@table @code 3627@kindex info threads 3628@item info threads @r{[}@var{thread-id-list}@r{]} 3629 3630Display information about one or more threads. With no arguments 3631displays information about all threads. You can specify the list of 3632threads that you want to display using the thread ID list syntax 3633(@pxref{thread ID lists}). 3634 3635@value{GDBN} displays for each thread (in this order): 3636 3637@enumerate 3638@item 3639the per-inferior thread number assigned by @value{GDBN} 3640 3641@item 3642the global thread number assigned by @value{GDBN}, if the @samp{-gid} 3643option was specified 3644 3645@item 3646the target system's thread identifier (@var{systag}) 3647 3648@item 3649the thread's name, if one is known. A thread can either be named by 3650the user (see @code{thread name}, below), or, in some cases, by the 3651program itself. 3652 3653@item 3654the current stack frame summary for that thread 3655@end enumerate 3656 3657@noindent 3658An asterisk @samp{*} to the left of the @value{GDBN} thread number 3659indicates the current thread. 3660 3661For example, 3662@end table 3663@c end table here to get a little more width for example 3664 3665@smallexample 3666(@value{GDBP}) info threads 3667 Id Target Id Frame 3668* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) 3669 2 process 35 thread 23 0x34e5 in sigpause () 3670 3 process 35 thread 27 0x34e5 in sigpause () 3671 at threadtest.c:68 3672@end smallexample 3673 3674If you're debugging multiple inferiors, @value{GDBN} displays thread 3675IDs using the qualified @var{inferior-num}.@var{thread-num} format. 3676Otherwise, only @var{thread-num} is shown. 3677 3678If you specify the @samp{-gid} option, @value{GDBN} displays a column 3679indicating each thread's global thread ID: 3680 3681@smallexample 3682(@value{GDBP}) info threads 3683 Id GId Target Id Frame 3684 1.1 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) 3685 1.2 3 process 35 thread 23 0x34e5 in sigpause () 3686 1.3 4 process 35 thread 27 0x34e5 in sigpause () 3687* 2.1 2 process 65 thread 1 main (argc=1, argv=0x7ffffff8) 3688@end smallexample 3689 3690On Solaris, you can display more information about user threads with a 3691Solaris-specific command: 3692 3693@table @code 3694@item maint info sol-threads 3695@kindex maint info sol-threads 3696@cindex thread info (Solaris) 3697Display info on Solaris user threads. 3698@end table 3699 3700@table @code 3701@kindex thread @var{thread-id} 3702@item thread @var{thread-id} 3703Make thread ID @var{thread-id} the current thread. The command 3704argument @var{thread-id} is the @value{GDBN} thread ID, as shown in 3705the first field of the @samp{info threads} display, with or without an 3706inferior qualifier (e.g., @samp{2.1} or @samp{1}). 3707 3708@value{GDBN} responds by displaying the system identifier of the 3709thread you selected, and its current stack frame summary: 3710 3711@smallexample 3712(@value{GDBP}) thread 2 3713[Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))] 3714#0 some_function (ignore=0x0) at example.c:8 37158 printf ("hello\n"); 3716@end smallexample 3717 3718@noindent 3719As with the @samp{[New @dots{}]} message, the form of the text after 3720@samp{Switching to} depends on your system's conventions for identifying 3721threads. 3722 3723@anchor{thread apply all} 3724@kindex thread apply 3725@cindex apply command to several threads 3726@item thread apply [@var{thread-id-list} | all [-ascending]] [@var{flag}]@dots{} @var{command} 3727The @code{thread apply} command allows you to apply the named 3728@var{command} to one or more threads. Specify the threads that you 3729want affected using the thread ID list syntax (@pxref{thread ID 3730lists}), or specify @code{all} to apply to all threads. To apply a 3731command to all threads in descending order, type @kbd{thread apply all 3732@var{command}}. To apply a command to all threads in ascending order, 3733type @kbd{thread apply all -ascending @var{command}}. 3734 3735The @var{flag} arguments control what output to produce and how to handle 3736errors raised when applying @var{command} to a thread. @var{flag} 3737must start with a @code{-} directly followed by one letter in 3738@code{qcs}. If several flags are provided, they must be given 3739individually, such as @code{-c -q}. 3740 3741By default, @value{GDBN} displays some thread information before the 3742output produced by @var{command}, and an error raised during the 3743execution of a @var{command} will abort @code{thread apply}. The 3744following flags can be used to fine-tune this behavior: 3745 3746@table @code 3747@item -c 3748The flag @code{-c}, which stands for @samp{continue}, causes any 3749errors in @var{command} to be displayed, and the execution of 3750@code{thread apply} then continues. 3751@item -s 3752The flag @code{-s}, which stands for @samp{silent}, causes any errors 3753or empty output produced by a @var{command} to be silently ignored. 3754That is, the execution continues, but the thread information and errors 3755are not printed. 3756@item -q 3757The flag @code{-q} (@samp{quiet}) disables printing the thread 3758information. 3759@end table 3760 3761Flags @code{-c} and @code{-s} cannot be used together. 3762 3763@kindex taas 3764@cindex apply command to all threads (ignoring errors and empty output) 3765@item taas [@var{option}]@dots{} @var{command} 3766Shortcut for @code{thread apply all -s [@var{option}]@dots{} @var{command}}. 3767Applies @var{command} on all threads, ignoring errors and empty output. 3768 3769The @code{taas} command accepts the same options as the @code{thread 3770apply all} command. @xref{thread apply all}. 3771 3772@kindex tfaas 3773@cindex apply a command to all frames of all threads (ignoring errors and empty output) 3774@item tfaas [@var{option}]@dots{} @var{command} 3775Shortcut for @code{thread apply all -s -- frame apply all -s [@var{option}]@dots{} @var{command}}. 3776Applies @var{command} on all frames of all threads, ignoring errors 3777and empty output. Note that the flag @code{-s} is specified twice: 3778The first @code{-s} ensures that @code{thread apply} only shows the thread 3779information of the threads for which @code{frame apply} produces 3780some output. The second @code{-s} is needed to ensure that @code{frame 3781apply} shows the frame information of a frame only if the 3782@var{command} successfully produced some output. 3783 3784It can for example be used to print a local variable or a function 3785argument without knowing the thread or frame where this variable or argument 3786is, using: 3787@smallexample 3788(@value{GDBP}) tfaas p some_local_var_i_do_not_remember_where_it_is 3789@end smallexample 3790 3791The @code{tfaas} command accepts the same options as the @code{frame 3792apply} command. @xref{Frame Apply,,frame apply}. 3793 3794@kindex thread name 3795@cindex name a thread 3796@item thread name [@var{name}] 3797This command assigns a name to the current thread. If no argument is 3798given, any existing user-specified name is removed. The thread name 3799appears in the @samp{info threads} display. 3800 3801On some systems, such as @sc{gnu}/Linux, @value{GDBN} is able to 3802determine the name of the thread as given by the OS. On these 3803systems, a name specified with @samp{thread name} will override the 3804system-give name, and removing the user-specified name will cause 3805@value{GDBN} to once again display the system-specified name. 3806 3807@kindex thread find 3808@cindex search for a thread 3809@item thread find [@var{regexp}] 3810Search for and display thread ids whose name or @var{systag} 3811matches the supplied regular expression. 3812 3813As well as being the complement to the @samp{thread name} command, 3814this command also allows you to identify a thread by its target 3815@var{systag}. For instance, on @sc{gnu}/Linux, the target @var{systag} 3816is the LWP id. 3817 3818@smallexample 3819(@value{GDBN}) thread find 26688 3820Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)' 3821(@value{GDBN}) info thread 4 3822 Id Target Id Frame 3823 4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select () 3824@end smallexample 3825 3826@kindex set print thread-events 3827@cindex print messages on thread start and exit 3828@item set print thread-events 3829@itemx set print thread-events on 3830@itemx set print thread-events off 3831The @code{set print thread-events} command allows you to enable or 3832disable printing of messages when @value{GDBN} notices that new threads have 3833started or that threads have exited. By default, these messages will 3834be printed if detection of these events is supported by the target. 3835Note that these messages cannot be disabled on all targets. 3836 3837@kindex show print thread-events 3838@item show print thread-events 3839Show whether messages will be printed when @value{GDBN} detects that threads 3840have started and exited. 3841@end table 3842 3843@xref{Thread Stops,,Stopping and Starting Multi-thread Programs}, for 3844more information about how @value{GDBN} behaves when you stop and start 3845programs with multiple threads. 3846 3847@xref{Set Watchpoints,,Setting Watchpoints}, for information about 3848watchpoints in programs with multiple threads. 3849 3850@anchor{set libthread-db-search-path} 3851@table @code 3852@kindex set libthread-db-search-path 3853@cindex search path for @code{libthread_db} 3854@item set libthread-db-search-path @r{[}@var{path}@r{]} 3855If this variable is set, @var{path} is a colon-separated list of 3856directories @value{GDBN} will use to search for @code{libthread_db}. 3857If you omit @var{path}, @samp{libthread-db-search-path} will be reset to 3858its default value (@code{$sdir:$pdir} on @sc{gnu}/Linux and Solaris systems). 3859Internally, the default value comes from the @code{LIBTHREAD_DB_SEARCH_PATH} 3860macro. 3861 3862On @sc{gnu}/Linux and Solaris systems, @value{GDBN} uses a ``helper'' 3863@code{libthread_db} library to obtain information about threads in the 3864inferior process. @value{GDBN} will use @samp{libthread-db-search-path} 3865to find @code{libthread_db}. @value{GDBN} also consults first if inferior 3866specific thread debugging library loading is enabled 3867by @samp{set auto-load libthread-db} (@pxref{libthread_db.so.1 file}). 3868 3869A special entry @samp{$sdir} for @samp{libthread-db-search-path} 3870refers to the default system directories that are 3871normally searched for loading shared libraries. The @samp{$sdir} entry 3872is the only kind not needing to be enabled by @samp{set auto-load libthread-db} 3873(@pxref{libthread_db.so.1 file}). 3874 3875A special entry @samp{$pdir} for @samp{libthread-db-search-path} 3876refers to the directory from which @code{libpthread} 3877was loaded in the inferior process. 3878 3879For any @code{libthread_db} library @value{GDBN} finds in above directories, 3880@value{GDBN} attempts to initialize it with the current inferior process. 3881If this initialization fails (which could happen because of a version 3882mismatch between @code{libthread_db} and @code{libpthread}), @value{GDBN} 3883will unload @code{libthread_db}, and continue with the next directory. 3884If none of @code{libthread_db} libraries initialize successfully, 3885@value{GDBN} will issue a warning and thread debugging will be disabled. 3886 3887Setting @code{libthread-db-search-path} is currently implemented 3888only on some platforms. 3889 3890@kindex show libthread-db-search-path 3891@item show libthread-db-search-path 3892Display current libthread_db search path. 3893 3894@kindex set debug libthread-db 3895@kindex show debug libthread-db 3896@cindex debugging @code{libthread_db} 3897@item set debug libthread-db 3898@itemx show debug libthread-db 3899Turns on or off display of @code{libthread_db}-related events. 3900Use @code{1} to enable, @code{0} to disable. 3901@end table 3902 3903@node Forks 3904@section Debugging Forks 3905 3906@cindex fork, debugging programs which call 3907@cindex multiple processes 3908@cindex processes, multiple 3909On most systems, @value{GDBN} has no special support for debugging 3910programs which create additional processes using the @code{fork} 3911function. When a program forks, @value{GDBN} will continue to debug the 3912parent process and the child process will run unimpeded. If you have 3913set a breakpoint in any code which the child then executes, the child 3914will get a @code{SIGTRAP} signal which (unless it catches the signal) 3915will cause it to terminate. 3916 3917However, if you want to debug the child process there is a workaround 3918which isn't too painful. Put a call to @code{sleep} in the code which 3919the child process executes after the fork. It may be useful to sleep 3920only if a certain environment variable is set, or a certain file exists, 3921so that the delay need not occur when you don't want to run @value{GDBN} 3922on the child. While the child is sleeping, use the @code{ps} program to 3923get its process ID. Then tell @value{GDBN} (a new invocation of 3924@value{GDBN} if you are also debugging the parent process) to attach to 3925the child process (@pxref{Attach}). From that point on you can debug 3926the child process just like any other process which you attached to. 3927 3928On some systems, @value{GDBN} provides support for debugging programs 3929that create additional processes using the @code{fork} or @code{vfork} 3930functions. On @sc{gnu}/Linux platforms, this feature is supported 3931with kernel version 2.5.46 and later. 3932 3933The fork debugging commands are supported in native mode and when 3934connected to @code{gdbserver} in either @code{target remote} mode or 3935@code{target extended-remote} mode. 3936 3937By default, when a program forks, @value{GDBN} will continue to debug 3938the parent process and the child process will run unimpeded. 3939 3940If you want to follow the child process instead of the parent process, 3941use the command @w{@code{set follow-fork-mode}}. 3942 3943@table @code 3944@kindex set follow-fork-mode 3945@item set follow-fork-mode @var{mode} 3946Set the debugger response to a program call of @code{fork} or 3947@code{vfork}. A call to @code{fork} or @code{vfork} creates a new 3948process. The @var{mode} argument can be: 3949 3950@table @code 3951@item parent 3952The original process is debugged after a fork. The child process runs 3953unimpeded. This is the default. 3954 3955@item child 3956The new process is debugged after a fork. The parent process runs 3957unimpeded. 3958 3959@end table 3960 3961@kindex show follow-fork-mode 3962@item show follow-fork-mode 3963Display the current debugger response to a @code{fork} or @code{vfork} call. 3964@end table 3965 3966@cindex debugging multiple processes 3967On Linux, if you want to debug both the parent and child processes, use the 3968command @w{@code{set detach-on-fork}}. 3969 3970@table @code 3971@kindex set detach-on-fork 3972@item set detach-on-fork @var{mode} 3973Tells gdb whether to detach one of the processes after a fork, or 3974retain debugger control over them both. 3975 3976@table @code 3977@item on 3978The child process (or parent process, depending on the value of 3979@code{follow-fork-mode}) will be detached and allowed to run 3980independently. This is the default. 3981 3982@item off 3983Both processes will be held under the control of @value{GDBN}. 3984One process (child or parent, depending on the value of 3985@code{follow-fork-mode}) is debugged as usual, while the other 3986is held suspended. 3987 3988@end table 3989 3990@kindex show detach-on-fork 3991@item show detach-on-fork 3992Show whether detach-on-fork mode is on/off. 3993@end table 3994 3995If you choose to set @samp{detach-on-fork} mode off, then @value{GDBN} 3996will retain control of all forked processes (including nested forks). 3997You can list the forked processes under the control of @value{GDBN} by 3998using the @w{@code{info inferiors}} command, and switch from one fork 3999to another by using the @code{inferior} command (@pxref{Inferiors Connections and 4000Programs, ,Debugging Multiple Inferiors Connections and Programs}). 4001 4002To quit debugging one of the forked processes, you can either detach 4003from it by using the @w{@code{detach inferiors}} command (allowing it 4004to run independently), or kill it using the @w{@code{kill inferiors}} 4005command. @xref{Inferiors Connections and Programs, ,Debugging 4006Multiple Inferiors Connections and Programs}. 4007 4008If you ask to debug a child process and a @code{vfork} is followed by an 4009@code{exec}, @value{GDBN} executes the new target up to the first 4010breakpoint in the new target. If you have a breakpoint set on 4011@code{main} in your original program, the breakpoint will also be set on 4012the child process's @code{main}. 4013 4014On some systems, when a child process is spawned by @code{vfork}, you 4015cannot debug the child or parent until an @code{exec} call completes. 4016 4017If you issue a @code{run} command to @value{GDBN} after an @code{exec} 4018call executes, the new target restarts. To restart the parent 4019process, use the @code{file} command with the parent executable name 4020as its argument. By default, after an @code{exec} call executes, 4021@value{GDBN} discards the symbols of the previous executable image. 4022You can change this behaviour with the @w{@code{set follow-exec-mode}} 4023command. 4024 4025@table @code 4026@kindex set follow-exec-mode 4027@item set follow-exec-mode @var{mode} 4028 4029Set debugger response to a program call of @code{exec}. An 4030@code{exec} call replaces the program image of a process. 4031 4032@code{follow-exec-mode} can be: 4033 4034@table @code 4035@item new 4036@value{GDBN} creates a new inferior and rebinds the process to this 4037new inferior. The program the process was running before the 4038@code{exec} call can be restarted afterwards by restarting the 4039original inferior. 4040 4041For example: 4042 4043@smallexample 4044(@value{GDBP}) info inferiors 4045(gdb) info inferior 4046 Id Description Executable 4047* 1 <null> prog1 4048(@value{GDBP}) run 4049process 12020 is executing new program: prog2 4050Program exited normally. 4051(@value{GDBP}) info inferiors 4052 Id Description Executable 4053 1 <null> prog1 4054* 2 <null> prog2 4055@end smallexample 4056 4057@item same 4058@value{GDBN} keeps the process bound to the same inferior. The new 4059executable image replaces the previous executable loaded in the 4060inferior. Restarting the inferior after the @code{exec} call, with 4061e.g., the @code{run} command, restarts the executable the process was 4062running after the @code{exec} call. This is the default mode. 4063 4064For example: 4065 4066@smallexample 4067(@value{GDBP}) info inferiors 4068 Id Description Executable 4069* 1 <null> prog1 4070(@value{GDBP}) run 4071process 12020 is executing new program: prog2 4072Program exited normally. 4073(@value{GDBP}) info inferiors 4074 Id Description Executable 4075* 1 <null> prog2 4076@end smallexample 4077 4078@end table 4079@end table 4080 4081@code{follow-exec-mode} is supported in native mode and 4082@code{target extended-remote} mode. 4083 4084You can use the @code{catch} command to make @value{GDBN} stop whenever 4085a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set 4086Catchpoints, ,Setting Catchpoints}. 4087 4088@node Checkpoint/Restart 4089@section Setting a @emph{Bookmark} to Return to Later 4090 4091@cindex checkpoint 4092@cindex restart 4093@cindex bookmark 4094@cindex snapshot of a process 4095@cindex rewind program state 4096 4097On certain operating systems@footnote{Currently, only 4098@sc{gnu}/Linux.}, @value{GDBN} is able to save a @dfn{snapshot} of a 4099program's state, called a @dfn{checkpoint}, and come back to it 4100later. 4101 4102Returning to a checkpoint effectively undoes everything that has 4103happened in the program since the @code{checkpoint} was saved. This 4104includes changes in memory, registers, and even (within some limits) 4105system state. Effectively, it is like going back in time to the 4106moment when the checkpoint was saved. 4107 4108Thus, if you're stepping thru a program and you think you're 4109getting close to the point where things go wrong, you can save 4110a checkpoint. Then, if you accidentally go too far and miss 4111the critical statement, instead of having to restart your program 4112from the beginning, you can just go back to the checkpoint and 4113start again from there. 4114 4115This can be especially useful if it takes a lot of time or 4116steps to reach the point where you think the bug occurs. 4117 4118To use the @code{checkpoint}/@code{restart} method of debugging: 4119 4120@table @code 4121@kindex checkpoint 4122@item checkpoint 4123Save a snapshot of the debugged program's current execution state. 4124The @code{checkpoint} command takes no arguments, but each checkpoint 4125is assigned a small integer id, similar to a breakpoint id. 4126 4127@kindex info checkpoints 4128@item info checkpoints 4129List the checkpoints that have been saved in the current debugging 4130session. For each checkpoint, the following information will be 4131listed: 4132 4133@table @code 4134@item Checkpoint ID 4135@item Process ID 4136@item Code Address 4137@item Source line, or label 4138@end table 4139 4140@kindex restart @var{checkpoint-id} 4141@item restart @var{checkpoint-id} 4142Restore the program state that was saved as checkpoint number 4143@var{checkpoint-id}. All program variables, registers, stack frames 4144etc.@: will be returned to the values that they had when the checkpoint 4145was saved. In essence, gdb will ``wind back the clock'' to the point 4146in time when the checkpoint was saved. 4147 4148Note that breakpoints, @value{GDBN} variables, command history etc. 4149are not affected by restoring a checkpoint. In general, a checkpoint 4150only restores things that reside in the program being debugged, not in 4151the debugger. 4152 4153@kindex delete checkpoint @var{checkpoint-id} 4154@item delete checkpoint @var{checkpoint-id} 4155Delete the previously-saved checkpoint identified by @var{checkpoint-id}. 4156 4157@end table 4158 4159Returning to a previously saved checkpoint will restore the user state 4160of the program being debugged, plus a significant subset of the system 4161(OS) state, including file pointers. It won't ``un-write'' data from 4162a file, but it will rewind the file pointer to the previous location, 4163so that the previously written data can be overwritten. For files 4164opened in read mode, the pointer will also be restored so that the 4165previously read data can be read again. 4166 4167Of course, characters that have been sent to a printer (or other 4168external device) cannot be ``snatched back'', and characters received 4169from eg.@: a serial device can be removed from internal program buffers, 4170but they cannot be ``pushed back'' into the serial pipeline, ready to 4171be received again. Similarly, the actual contents of files that have 4172been changed cannot be restored (at this time). 4173 4174However, within those constraints, you actually can ``rewind'' your 4175program to a previously saved point in time, and begin debugging it 4176again --- and you can change the course of events so as to debug a 4177different execution path this time. 4178 4179@cindex checkpoints and process id 4180Finally, there is one bit of internal program state that will be 4181different when you return to a checkpoint --- the program's process 4182id. Each checkpoint will have a unique process id (or @var{pid}), 4183and each will be different from the program's original @var{pid}. 4184If your program has saved a local copy of its process id, this could 4185potentially pose a problem. 4186 4187@subsection A Non-obvious Benefit of Using Checkpoints 4188 4189On some systems such as @sc{gnu}/Linux, address space randomization 4190is performed on new processes for security reasons. This makes it 4191difficult or impossible to set a breakpoint, or watchpoint, on an 4192absolute address if you have to restart the program, since the 4193absolute location of a symbol will change from one execution to the 4194next. 4195 4196A checkpoint, however, is an @emph{identical} copy of a process. 4197Therefore if you create a checkpoint at (eg.@:) the start of main, 4198and simply return to that checkpoint instead of restarting the 4199process, you can avoid the effects of address randomization and 4200your symbols will all stay in the same place. 4201 4202@node Stopping 4203@chapter Stopping and Continuing 4204 4205The principal purposes of using a debugger are so that you can stop your 4206program before it terminates; or so that, if your program runs into 4207trouble, you can investigate and find out why. 4208 4209Inside @value{GDBN}, your program may stop for any of several reasons, 4210such as a signal, a breakpoint, or reaching a new line after a 4211@value{GDBN} command such as @code{step}. You may then examine and 4212change variables, set new breakpoints or remove old ones, and then 4213continue execution. Usually, the messages shown by @value{GDBN} provide 4214ample explanation of the status of your program---but you can also 4215explicitly request this information at any time. 4216 4217@table @code 4218@kindex info program 4219@item info program 4220Display information about the status of your program: whether it is 4221running or not, what process it is, and why it stopped. 4222@end table 4223 4224@menu 4225* Breakpoints:: Breakpoints, watchpoints, and catchpoints 4226* Continuing and Stepping:: Resuming execution 4227* Skipping Over Functions and Files:: 4228 Skipping over functions and files 4229* Signals:: Signals 4230* Thread Stops:: Stopping and starting multi-thread programs 4231@end menu 4232 4233@node Breakpoints 4234@section Breakpoints, Watchpoints, and Catchpoints 4235 4236@cindex breakpoints 4237A @dfn{breakpoint} makes your program stop whenever a certain point in 4238the program is reached. For each breakpoint, you can add conditions to 4239control in finer detail whether your program stops. You can set 4240breakpoints with the @code{break} command and its variants (@pxref{Set 4241Breaks, ,Setting Breakpoints}), to specify the place where your program 4242should stop by line number, function name or exact address in the 4243program. 4244 4245On some systems, you can set breakpoints in shared libraries before 4246the executable is run. 4247 4248@cindex watchpoints 4249@cindex data breakpoints 4250@cindex memory tracing 4251@cindex breakpoint on memory address 4252@cindex breakpoint on variable modification 4253A @dfn{watchpoint} is a special breakpoint that stops your program 4254when the value of an expression changes. The expression may be a value 4255of a variable, or it could involve values of one or more variables 4256combined by operators, such as @samp{a + b}. This is sometimes called 4257@dfn{data breakpoints}. You must use a different command to set 4258watchpoints (@pxref{Set Watchpoints, ,Setting Watchpoints}), but aside 4259from that, you can manage a watchpoint like any other breakpoint: you 4260enable, disable, and delete both breakpoints and watchpoints using the 4261same commands. 4262 4263You can arrange to have values from your program displayed automatically 4264whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,, 4265Automatic Display}. 4266 4267@cindex catchpoints 4268@cindex breakpoint on events 4269A @dfn{catchpoint} is another special breakpoint that stops your program 4270when a certain kind of event occurs, such as the throwing of a C@t{++} 4271exception or the loading of a library. As with watchpoints, you use a 4272different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting 4273Catchpoints}), but aside from that, you can manage a catchpoint like any 4274other breakpoint. (To stop when your program receives a signal, use the 4275@code{handle} command; see @ref{Signals, ,Signals}.) 4276 4277@cindex breakpoint numbers 4278@cindex numbers for breakpoints 4279@value{GDBN} assigns a number to each breakpoint, watchpoint, or 4280catchpoint when you create it; these numbers are successive integers 4281starting with one. In many of the commands for controlling various 4282features of breakpoints you use the breakpoint number to say which 4283breakpoint you want to change. Each breakpoint may be @dfn{enabled} or 4284@dfn{disabled}; if disabled, it has no effect on your program until you 4285enable it again. 4286 4287@cindex breakpoint ranges 4288@cindex breakpoint lists 4289@cindex ranges of breakpoints 4290@cindex lists of breakpoints 4291Some @value{GDBN} commands accept a space-separated list of breakpoints 4292on which to operate. A list element can be either a single breakpoint number, 4293like @samp{5}, or a range of such numbers, like @samp{5-7}. 4294When a breakpoint list is given to a command, all breakpoints in that list 4295are operated on. 4296 4297@menu 4298* Set Breaks:: Setting breakpoints 4299* Set Watchpoints:: Setting watchpoints 4300* Set Catchpoints:: Setting catchpoints 4301* Delete Breaks:: Deleting breakpoints 4302* Disabling:: Disabling breakpoints 4303* Conditions:: Break conditions 4304* Break Commands:: Breakpoint command lists 4305* Dynamic Printf:: Dynamic printf 4306* Save Breakpoints:: How to save breakpoints in a file 4307* Static Probe Points:: Listing static probe points 4308* Error in Breakpoints:: ``Cannot insert breakpoints'' 4309* Breakpoint-related Warnings:: ``Breakpoint address adjusted...'' 4310@end menu 4311 4312@node Set Breaks 4313@subsection Setting Breakpoints 4314 4315@c FIXME LMB what does GDB do if no code on line of breakpt? 4316@c consider in particular declaration with/without initialization. 4317@c 4318@c FIXME 2 is there stuff on this already? break at fun start, already init? 4319 4320@kindex break 4321@kindex b @r{(@code{break})} 4322@vindex $bpnum@r{, convenience variable} 4323@cindex latest breakpoint 4324Breakpoints are set with the @code{break} command (abbreviated 4325@code{b}). The debugger convenience variable @samp{$bpnum} records the 4326number of the breakpoint you've set most recently; see @ref{Convenience 4327Vars,, Convenience Variables}, for a discussion of what you can do with 4328convenience variables. 4329 4330@table @code 4331@item break @var{location} 4332Set a breakpoint at the given @var{location}, which can specify a 4333function name, a line number, or an address of an instruction. 4334(@xref{Specify Location}, for a list of all the possible ways to 4335specify a @var{location}.) The breakpoint will stop your program just 4336before it executes any of the code in the specified @var{location}. 4337 4338When using source languages that permit overloading of symbols, such as 4339C@t{++}, a function name may refer to more than one possible place to break. 4340@xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of 4341that situation. 4342 4343It is also possible to insert a breakpoint that will stop the program 4344only if a specific thread (@pxref{Thread-Specific Breakpoints}) 4345or a specific task (@pxref{Ada Tasks}) hits that breakpoint. 4346 4347@item break 4348When called without any arguments, @code{break} sets a breakpoint at 4349the next instruction to be executed in the selected stack frame 4350(@pxref{Stack, ,Examining the Stack}). In any selected frame but the 4351innermost, this makes your program stop as soon as control 4352returns to that frame. This is similar to the effect of a 4353@code{finish} command in the frame inside the selected frame---except 4354that @code{finish} does not leave an active breakpoint. If you use 4355@code{break} without an argument in the innermost frame, @value{GDBN} stops 4356the next time it reaches the current location; this may be useful 4357inside loops. 4358 4359@value{GDBN} normally ignores breakpoints when it resumes execution, until at 4360least one instruction has been executed. If it did not do this, you 4361would be unable to proceed past a breakpoint without first disabling the 4362breakpoint. This rule applies whether or not the breakpoint already 4363existed when your program stopped. 4364 4365@item break @dots{} if @var{cond} 4366Set a breakpoint with condition @var{cond}; evaluate the expression 4367@var{cond} each time the breakpoint is reached, and stop only if the 4368value is nonzero---that is, if @var{cond} evaluates as true. 4369@samp{@dots{}} stands for one of the possible arguments described 4370above (or no argument) specifying where to break. @xref{Conditions, 4371,Break Conditions}, for more information on breakpoint conditions. 4372 4373The breakpoint may be mapped to multiple locations. If the breakpoint 4374condition @var{cond} is invalid at some but not all of the locations, 4375the locations for which the condition is invalid are disabled. For 4376example, @value{GDBN} reports below that two of the three locations 4377are disabled. 4378 4379@smallexample 4380(@value{GDBP}) break func if a == 10 4381warning: failed to validate condition at location 0x11ce, disabling: 4382 No symbol "a" in current context. 4383warning: failed to validate condition at location 0x11b6, disabling: 4384 No symbol "a" in current context. 4385Breakpoint 1 at 0x11b6: func. (3 locations) 4386@end smallexample 4387 4388Locations that are disabled because of the condition are denoted by an 4389uppercase @code{N} in the output of the @code{info breakpoints} 4390command: 4391 4392@smallexample 4393(@value{GDBP}) info breakpoints 4394Num Type Disp Enb Address What 43951 breakpoint keep y <MULTIPLE> 4396 stop only if a == 10 43971.1 N* 0x00000000000011b6 in ... 43981.2 y 0x00000000000011c2 in ... 43991.3 N* 0x00000000000011ce in ... 4400(*): Breakpoint condition is invalid at this location. 4401@end smallexample 4402 4403If the breakpoint condition @var{cond} is invalid in the context of 4404@emph{all} the locations of the breakpoint, @value{GDBN} refuses to 4405define the breakpoint. For example, if variable @code{foo} is an 4406undefined variable: 4407 4408@smallexample 4409(@value{GDBP}) break func if foo 4410No symbol "foo" in current context. 4411@end smallexample 4412 4413@item break @dots{} -force-condition if @var{cond} 4414There may be cases where the condition @var{cond} is invalid at all 4415the current locations, but the user knows that it will be valid at a 4416future location; for example, because of a library load. In such 4417cases, by using the @code{-force-condition} keyword before @samp{if}, 4418@value{GDBN} can be forced to define the breakpoint with the given 4419condition expression instead of refusing it. 4420 4421@smallexample 4422(@value{GDBP}) break func -force-condition if foo 4423warning: failed to validate condition at location 1, disabling: 4424 No symbol "foo" in current context. 4425warning: failed to validate condition at location 2, disabling: 4426 No symbol "foo" in current context. 4427warning: failed to validate condition at location 3, disabling: 4428 No symbol "foo" in current context. 4429Breakpoint 1 at 0x1158: test.c:18. (3 locations) 4430@end smallexample 4431 4432This causes all the present locations where the breakpoint would 4433otherwise be inserted, to be disabled, as seen in the example above. 4434However, if there exist locations at which the condition is valid, the 4435@code{-force-condition} keyword has no effect. 4436 4437@kindex tbreak 4438@item tbreak @var{args} 4439Set a breakpoint enabled only for one stop. The @var{args} are the 4440same as for the @code{break} command, and the breakpoint is set in the same 4441way, but the breakpoint is automatically deleted after the first time your 4442program stops there. @xref{Disabling, ,Disabling Breakpoints}. 4443 4444@kindex hbreak 4445@cindex hardware breakpoints 4446@item hbreak @var{args} 4447Set a hardware-assisted breakpoint. The @var{args} are the same as for the 4448@code{break} command and the breakpoint is set in the same way, but the 4449breakpoint requires hardware support and some target hardware may not 4450have this support. The main purpose of this is EPROM/ROM code 4451debugging, so you can set a breakpoint at an instruction without 4452changing the instruction. This can be used with the new trap-generation 4453provided by SPARClite DSU and most x86-based targets. These targets 4454will generate traps when a program accesses some data or instruction 4455address that is assigned to the debug registers. However the hardware 4456breakpoint registers can take a limited number of breakpoints. For 4457example, on the DSU, only two data breakpoints can be set at a time, and 4458@value{GDBN} will reject this command if more than two are used. Delete 4459or disable unused hardware breakpoints before setting new ones 4460(@pxref{Disabling, ,Disabling Breakpoints}). 4461@xref{Conditions, ,Break Conditions}. 4462For remote targets, you can restrict the number of hardware 4463breakpoints @value{GDBN} will use, see @ref{set remote 4464hardware-breakpoint-limit}. 4465 4466@kindex thbreak 4467@item thbreak @var{args} 4468Set a hardware-assisted breakpoint enabled only for one stop. The @var{args} 4469are the same as for the @code{hbreak} command and the breakpoint is set in 4470the same way. However, like the @code{tbreak} command, 4471the breakpoint is automatically deleted after the 4472first time your program stops there. Also, like the @code{hbreak} 4473command, the breakpoint requires hardware support and some target hardware 4474may not have this support. @xref{Disabling, ,Disabling Breakpoints}. 4475See also @ref{Conditions, ,Break Conditions}. 4476 4477@kindex rbreak 4478@cindex regular expression 4479@cindex breakpoints at functions matching a regexp 4480@cindex set breakpoints in many functions 4481@item rbreak @var{regex} 4482Set breakpoints on all functions matching the regular expression 4483@var{regex}. This command sets an unconditional breakpoint on all 4484matches, printing a list of all breakpoints it set. Once these 4485breakpoints are set, they are treated just like the breakpoints set with 4486the @code{break} command. You can delete them, disable them, or make 4487them conditional the same way as any other breakpoint. 4488 4489In programs using different languages, @value{GDBN} chooses the syntax 4490to print the list of all breakpoints it sets according to the 4491@samp{set language} value: using @samp{set language auto} 4492(see @ref{Automatically, ,Set Language Automatically}) means to use the 4493language of the breakpoint's function, other values mean to use 4494the manually specified language (see @ref{Manually, ,Set Language Manually}). 4495 4496The syntax of the regular expression is the standard one used with tools 4497like @file{grep}. Note that this is different from the syntax used by 4498shells, so for instance @code{foo*} matches all functions that include 4499an @code{fo} followed by zero or more @code{o}s. There is an implicit 4500@code{.*} leading and trailing the regular expression you supply, so to 4501match only functions that begin with @code{foo}, use @code{^foo}. 4502 4503@cindex non-member C@t{++} functions, set breakpoint in 4504When debugging C@t{++} programs, @code{rbreak} is useful for setting 4505breakpoints on overloaded functions that are not members of any special 4506classes. 4507 4508@cindex set breakpoints on all functions 4509The @code{rbreak} command can be used to set breakpoints in 4510@strong{all} the functions in a program, like this: 4511 4512@smallexample 4513(@value{GDBP}) rbreak . 4514@end smallexample 4515 4516@item rbreak @var{file}:@var{regex} 4517If @code{rbreak} is called with a filename qualification, it limits 4518the search for functions matching the given regular expression to the 4519specified @var{file}. This can be used, for example, to set breakpoints on 4520every function in a given file: 4521 4522@smallexample 4523(@value{GDBP}) rbreak file.c:. 4524@end smallexample 4525 4526The colon separating the filename qualifier from the regex may 4527optionally be surrounded by spaces. 4528 4529@kindex info breakpoints 4530@cindex @code{$_} and @code{info breakpoints} 4531@item info breakpoints @r{[}@var{list}@dots{}@r{]} 4532@itemx info break @r{[}@var{list}@dots{}@r{]} 4533Print a table of all breakpoints, watchpoints, and catchpoints set and 4534not deleted. Optional argument @var{n} means print information only 4535about the specified breakpoint(s) (or watchpoint(s) or catchpoint(s)). 4536For each breakpoint, following columns are printed: 4537 4538@table @emph 4539@item Breakpoint Numbers 4540@item Type 4541Breakpoint, watchpoint, or catchpoint. 4542@item Disposition 4543Whether the breakpoint is marked to be disabled or deleted when hit. 4544@item Enabled or Disabled 4545Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints 4546that are not enabled. 4547@item Address 4548Where the breakpoint is in your program, as a memory address. For a 4549pending breakpoint whose address is not yet known, this field will 4550contain @samp{<PENDING>}. Such breakpoint won't fire until a shared 4551library that has the symbol or line referred by breakpoint is loaded. 4552See below for details. A breakpoint with several locations will 4553have @samp{<MULTIPLE>} in this field---see below for details. 4554@item What 4555Where the breakpoint is in the source for your program, as a file and 4556line number. For a pending breakpoint, the original string passed to 4557the breakpoint command will be listed as it cannot be resolved until 4558the appropriate shared library is loaded in the future. 4559@end table 4560 4561@noindent 4562If a breakpoint is conditional, there are two evaluation modes: ``host'' and 4563``target''. If mode is ``host'', breakpoint condition evaluation is done by 4564@value{GDBN} on the host's side. If it is ``target'', then the condition 4565is evaluated by the target. The @code{info break} command shows 4566the condition on the line following the affected breakpoint, together with 4567its condition evaluation mode in between parentheses. 4568 4569Breakpoint commands, if any, are listed after that. A pending breakpoint is 4570allowed to have a condition specified for it. The condition is not parsed for 4571validity until a shared library is loaded that allows the pending 4572breakpoint to resolve to a valid location. 4573 4574@noindent 4575@code{info break} with a breakpoint 4576number @var{n} as argument lists only that breakpoint. The 4577convenience variable @code{$_} and the default examining-address for 4578the @code{x} command are set to the address of the last breakpoint 4579listed (@pxref{Memory, ,Examining Memory}). 4580 4581@noindent 4582@code{info break} displays a count of the number of times the breakpoint 4583has been hit. This is especially useful in conjunction with the 4584@code{ignore} command. You can ignore a large number of breakpoint 4585hits, look at the breakpoint info to see how many times the breakpoint 4586was hit, and then run again, ignoring one less than that number. This 4587will get you quickly to the last hit of that breakpoint. 4588 4589@noindent 4590For a breakpoints with an enable count (xref) greater than 1, 4591@code{info break} also displays that count. 4592 4593@end table 4594 4595@value{GDBN} allows you to set any number of breakpoints at the same place in 4596your program. There is nothing silly or meaningless about this. When 4597the breakpoints are conditional, this is even useful 4598(@pxref{Conditions, ,Break Conditions}). 4599 4600@cindex multiple locations, breakpoints 4601@cindex breakpoints, multiple locations 4602It is possible that a breakpoint corresponds to several locations 4603in your program. Examples of this situation are: 4604 4605@itemize @bullet 4606@item 4607Multiple functions in the program may have the same name. 4608 4609@item 4610For a C@t{++} constructor, the @value{NGCC} compiler generates several 4611instances of the function body, used in different cases. 4612 4613@item 4614For a C@t{++} template function, a given line in the function can 4615correspond to any number of instantiations. 4616 4617@item 4618For an inlined function, a given source line can correspond to 4619several places where that function is inlined. 4620@end itemize 4621 4622In all those cases, @value{GDBN} will insert a breakpoint at all 4623the relevant locations. 4624 4625A breakpoint with multiple locations is displayed in the breakpoint 4626table using several rows---one header row, followed by one row for 4627each breakpoint location. The header row has @samp{<MULTIPLE>} in the 4628address column. The rows for individual locations contain the actual 4629addresses for locations, and show the functions to which those 4630locations belong. The number column for a location is of the form 4631@var{breakpoint-number}.@var{location-number}. 4632 4633For example: 4634 4635@smallexample 4636Num Type Disp Enb Address What 46371 breakpoint keep y <MULTIPLE> 4638 stop only if i==1 4639 breakpoint already hit 1 time 46401.1 y 0x080486a2 in void foo<int>() at t.cc:8 46411.2 y 0x080486ca in void foo<double>() at t.cc:8 4642@end smallexample 4643 4644You cannot delete the individual locations from a breakpoint. However, 4645each location can be individually enabled or disabled by passing 4646@var{breakpoint-number}.@var{location-number} as argument to the 4647@code{enable} and @code{disable} commands. It's also possible to 4648@code{enable} and @code{disable} a range of @var{location-number} 4649locations using a @var{breakpoint-number} and two @var{location-number}s, 4650in increasing order, separated by a hyphen, like 4651@kbd{@var{breakpoint-number}.@var{location-number1}-@var{location-number2}}, 4652in which case @value{GDBN} acts on all the locations in the range (inclusive). 4653Disabling or enabling the parent breakpoint (@pxref{Disabling}) affects 4654all of the locations that belong to that breakpoint. 4655 4656@cindex pending breakpoints 4657It's quite common to have a breakpoint inside a shared library. 4658Shared libraries can be loaded and unloaded explicitly, 4659and possibly repeatedly, as the program is executed. To support 4660this use case, @value{GDBN} updates breakpoint locations whenever 4661any shared library is loaded or unloaded. Typically, you would 4662set a breakpoint in a shared library at the beginning of your 4663debugging session, when the library is not loaded, and when the 4664symbols from the library are not available. When you try to set 4665breakpoint, @value{GDBN} will ask you if you want to set 4666a so called @dfn{pending breakpoint}---breakpoint whose address 4667is not yet resolved. 4668 4669After the program is run, whenever a new shared library is loaded, 4670@value{GDBN} reevaluates all the breakpoints. When a newly loaded 4671shared library contains the symbol or line referred to by some 4672pending breakpoint, that breakpoint is resolved and becomes an 4673ordinary breakpoint. When a library is unloaded, all breakpoints 4674that refer to its symbols or source lines become pending again. 4675 4676This logic works for breakpoints with multiple locations, too. For 4677example, if you have a breakpoint in a C@t{++} template function, and 4678a newly loaded shared library has an instantiation of that template, 4679a new location is added to the list of locations for the breakpoint. 4680 4681Except for having unresolved address, pending breakpoints do not 4682differ from regular breakpoints. You can set conditions or commands, 4683enable and disable them and perform other breakpoint operations. 4684 4685@value{GDBN} provides some additional commands for controlling what 4686happens when the @samp{break} command cannot resolve breakpoint 4687address specification to an address: 4688 4689@kindex set breakpoint pending 4690@kindex show breakpoint pending 4691@table @code 4692@item set breakpoint pending auto 4693This is the default behavior. When @value{GDBN} cannot find the breakpoint 4694location, it queries you whether a pending breakpoint should be created. 4695 4696@item set breakpoint pending on 4697This indicates that an unrecognized breakpoint location should automatically 4698result in a pending breakpoint being created. 4699 4700@item set breakpoint pending off 4701This indicates that pending breakpoints are not to be created. Any 4702unrecognized breakpoint location results in an error. This setting does 4703not affect any pending breakpoints previously created. 4704 4705@item show breakpoint pending 4706Show the current behavior setting for creating pending breakpoints. 4707@end table 4708 4709The settings above only affect the @code{break} command and its 4710variants. Once breakpoint is set, it will be automatically updated 4711as shared libraries are loaded and unloaded. 4712 4713@cindex automatic hardware breakpoints 4714For some targets, @value{GDBN} can automatically decide if hardware or 4715software breakpoints should be used, depending on whether the 4716breakpoint address is read-only or read-write. This applies to 4717breakpoints set with the @code{break} command as well as to internal 4718breakpoints set by commands like @code{next} and @code{finish}. For 4719breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware 4720breakpoints. 4721 4722You can control this automatic behaviour with the following commands: 4723 4724@kindex set breakpoint auto-hw 4725@kindex show breakpoint auto-hw 4726@table @code 4727@item set breakpoint auto-hw on 4728This is the default behavior. When @value{GDBN} sets a breakpoint, it 4729will try to use the target memory map to decide if software or hardware 4730breakpoint must be used. 4731 4732@item set breakpoint auto-hw off 4733This indicates @value{GDBN} should not automatically select breakpoint 4734type. If the target provides a memory map, @value{GDBN} will warn when 4735trying to set software breakpoint at a read-only address. 4736@end table 4737 4738@value{GDBN} normally implements breakpoints by replacing the program code 4739at the breakpoint address with a special instruction, which, when 4740executed, given control to the debugger. By default, the program 4741code is so modified only when the program is resumed. As soon as 4742the program stops, @value{GDBN} restores the original instructions. This 4743behaviour guards against leaving breakpoints inserted in the 4744target should gdb abrubptly disconnect. However, with slow remote 4745targets, inserting and removing breakpoint can reduce the performance. 4746This behavior can be controlled with the following commands:: 4747 4748@kindex set breakpoint always-inserted 4749@kindex show breakpoint always-inserted 4750@table @code 4751@item set breakpoint always-inserted off 4752All breakpoints, including newly added by the user, are inserted in 4753the target only when the target is resumed. All breakpoints are 4754removed from the target when it stops. This is the default mode. 4755 4756@item set breakpoint always-inserted on 4757Causes all breakpoints to be inserted in the target at all times. If 4758the user adds a new breakpoint, or changes an existing breakpoint, the 4759breakpoints in the target are updated immediately. A breakpoint is 4760removed from the target only when breakpoint itself is deleted. 4761@end table 4762 4763@value{GDBN} handles conditional breakpoints by evaluating these conditions 4764when a breakpoint breaks. If the condition is true, then the process being 4765debugged stops, otherwise the process is resumed. 4766 4767If the target supports evaluating conditions on its end, @value{GDBN} may 4768download the breakpoint, together with its conditions, to it. 4769 4770This feature can be controlled via the following commands: 4771 4772@kindex set breakpoint condition-evaluation 4773@kindex show breakpoint condition-evaluation 4774@table @code 4775@item set breakpoint condition-evaluation host 4776This option commands @value{GDBN} to evaluate the breakpoint 4777conditions on the host's side. Unconditional breakpoints are sent to 4778the target which in turn receives the triggers and reports them back to GDB 4779for condition evaluation. This is the standard evaluation mode. 4780 4781@item set breakpoint condition-evaluation target 4782This option commands @value{GDBN} to download breakpoint conditions 4783to the target at the moment of their insertion. The target 4784is responsible for evaluating the conditional expression and reporting 4785breakpoint stop events back to @value{GDBN} whenever the condition 4786is true. Due to limitations of target-side evaluation, some conditions 4787cannot be evaluated there, e.g., conditions that depend on local data 4788that is only known to the host. Examples include 4789conditional expressions involving convenience variables, complex types 4790that cannot be handled by the agent expression parser and expressions 4791that are too long to be sent over to the target, specially when the 4792target is a remote system. In these cases, the conditions will be 4793evaluated by @value{GDBN}. 4794 4795@item set breakpoint condition-evaluation auto 4796This is the default mode. If the target supports evaluating breakpoint 4797conditions on its end, @value{GDBN} will download breakpoint conditions to 4798the target (limitations mentioned previously apply). If the target does 4799not support breakpoint condition evaluation, then @value{GDBN} will fallback 4800to evaluating all these conditions on the host's side. 4801@end table 4802 4803 4804@cindex negative breakpoint numbers 4805@cindex internal @value{GDBN} breakpoints 4806@value{GDBN} itself sometimes sets breakpoints in your program for 4807special purposes, such as proper handling of @code{longjmp} (in C 4808programs). These internal breakpoints are assigned negative numbers, 4809starting with @code{-1}; @samp{info breakpoints} does not display them. 4810You can see these breakpoints with the @value{GDBN} maintenance command 4811@samp{maint info breakpoints} (@pxref{maint info breakpoints}). 4812 4813 4814@node Set Watchpoints 4815@subsection Setting Watchpoints 4816 4817@cindex setting watchpoints 4818You can use a watchpoint to stop execution whenever the value of an 4819expression changes, without having to predict a particular place where 4820this may happen. (This is sometimes called a @dfn{data breakpoint}.) 4821The expression may be as simple as the value of a single variable, or 4822as complex as many variables combined by operators. Examples include: 4823 4824@itemize @bullet 4825@item 4826A reference to the value of a single variable. 4827 4828@item 4829An address cast to an appropriate data type. For example, 4830@samp{*(int *)0x12345678} will watch a 4-byte region at the specified 4831address (assuming an @code{int} occupies 4 bytes). 4832 4833@item 4834An arbitrarily complex expression, such as @samp{a*b + c/d}. The 4835expression can use any operators valid in the program's native 4836language (@pxref{Languages}). 4837@end itemize 4838 4839You can set a watchpoint on an expression even if the expression can 4840not be evaluated yet. For instance, you can set a watchpoint on 4841@samp{*global_ptr} before @samp{global_ptr} is initialized. 4842@value{GDBN} will stop when your program sets @samp{global_ptr} and 4843the expression produces a valid value. If the expression becomes 4844valid in some other way than changing a variable (e.g.@: if the memory 4845pointed to by @samp{*global_ptr} becomes readable as the result of a 4846@code{malloc} call), @value{GDBN} may not stop until the next time 4847the expression changes. 4848 4849@cindex software watchpoints 4850@cindex hardware watchpoints 4851Depending on your system, watchpoints may be implemented in software or 4852hardware. @value{GDBN} does software watchpointing by single-stepping your 4853program and testing the variable's value each time, which is hundreds of 4854times slower than normal execution. (But this may still be worth it, to 4855catch errors where you have no clue what part of your program is the 4856culprit.) 4857 4858On some systems, such as most PowerPC or x86-based targets, 4859@value{GDBN} includes support for hardware watchpoints, which do not 4860slow down the running of your program. 4861 4862@table @code 4863@kindex watch 4864@item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]} 4865Set a watchpoint for an expression. @value{GDBN} will break when the 4866expression @var{expr} is written into by the program and its value 4867changes. The simplest (and the most popular) use of this command is 4868to watch the value of a single variable: 4869 4870@smallexample 4871(@value{GDBP}) watch foo 4872@end smallexample 4873 4874If the command includes a @code{@r{[}thread @var{thread-id}@r{]}} 4875argument, @value{GDBN} breaks only when the thread identified by 4876@var{thread-id} changes the value of @var{expr}. If any other threads 4877change the value of @var{expr}, @value{GDBN} will not break. Note 4878that watchpoints restricted to a single thread in this way only work 4879with Hardware Watchpoints. 4880 4881Ordinarily a watchpoint respects the scope of variables in @var{expr} 4882(see below). The @code{-location} argument tells @value{GDBN} to 4883instead watch the memory referred to by @var{expr}. In this case, 4884@value{GDBN} will evaluate @var{expr}, take the address of the result, 4885and watch the memory at that address. The type of the result is used 4886to determine the size of the watched memory. If the expression's 4887result does not have an address, then @value{GDBN} will print an 4888error. 4889 4890The @code{@r{[}mask @var{maskvalue}@r{]}} argument allows creation 4891of masked watchpoints, if the current architecture supports this 4892feature (e.g., PowerPC Embedded architecture, see @ref{PowerPC 4893Embedded}.) A @dfn{masked watchpoint} specifies a mask in addition 4894to an address to watch. The mask specifies that some bits of an address 4895(the bits which are reset in the mask) should be ignored when matching 4896the address accessed by the inferior against the watchpoint address. 4897Thus, a masked watchpoint watches many addresses simultaneously---those 4898addresses whose unmasked bits are identical to the unmasked bits in the 4899watchpoint address. The @code{mask} argument implies @code{-location}. 4900Examples: 4901 4902@smallexample 4903(@value{GDBP}) watch foo mask 0xffff00ff 4904(@value{GDBP}) watch *0xdeadbeef mask 0xffffff00 4905@end smallexample 4906 4907@kindex rwatch 4908@item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]} 4909Set a watchpoint that will break when the value of @var{expr} is read 4910by the program. 4911 4912@kindex awatch 4913@item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]} 4914Set a watchpoint that will break when @var{expr} is either read from 4915or written into by the program. 4916 4917@kindex info watchpoints @r{[}@var{list}@dots{}@r{]} 4918@item info watchpoints @r{[}@var{list}@dots{}@r{]} 4919This command prints a list of watchpoints, using the same format as 4920@code{info break} (@pxref{Set Breaks}). 4921@end table 4922 4923If you watch for a change in a numerically entered address you need to 4924dereference it, as the address itself is just a constant number which will 4925never change. @value{GDBN} refuses to create a watchpoint that watches 4926a never-changing value: 4927 4928@smallexample 4929(@value{GDBP}) watch 0x600850 4930Cannot watch constant value 0x600850. 4931(@value{GDBP}) watch *(int *) 0x600850 4932Watchpoint 1: *(int *) 6293584 4933@end smallexample 4934 4935@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware 4936watchpoints execute very quickly, and the debugger reports a change in 4937value at the exact instruction where the change occurs. If @value{GDBN} 4938cannot set a hardware watchpoint, it sets a software watchpoint, which 4939executes more slowly and reports the change in value at the next 4940@emph{statement}, not the instruction, after the change occurs. 4941 4942@cindex use only software watchpoints 4943You can force @value{GDBN} to use only software watchpoints with the 4944@kbd{set can-use-hw-watchpoints 0} command. With this variable set to 4945zero, @value{GDBN} will never try to use hardware watchpoints, even if 4946the underlying system supports them. (Note that hardware-assisted 4947watchpoints that were set @emph{before} setting 4948@code{can-use-hw-watchpoints} to zero will still use the hardware 4949mechanism of watching expression values.) 4950 4951@table @code 4952@item set can-use-hw-watchpoints 4953@kindex set can-use-hw-watchpoints 4954Set whether or not to use hardware watchpoints. 4955 4956@item show can-use-hw-watchpoints 4957@kindex show can-use-hw-watchpoints 4958Show the current mode of using hardware watchpoints. 4959@end table 4960 4961For remote targets, you can restrict the number of hardware 4962watchpoints @value{GDBN} will use, see @ref{set remote 4963hardware-breakpoint-limit}. 4964 4965When you issue the @code{watch} command, @value{GDBN} reports 4966 4967@smallexample 4968Hardware watchpoint @var{num}: @var{expr} 4969@end smallexample 4970 4971@noindent 4972if it was able to set a hardware watchpoint. 4973 4974Currently, the @code{awatch} and @code{rwatch} commands can only set 4975hardware watchpoints, because accesses to data that don't change the 4976value of the watched expression cannot be detected without examining 4977every instruction as it is being executed, and @value{GDBN} does not do 4978that currently. If @value{GDBN} finds that it is unable to set a 4979hardware breakpoint with the @code{awatch} or @code{rwatch} command, it 4980will print a message like this: 4981 4982@smallexample 4983Expression cannot be implemented with read/access watchpoint. 4984@end smallexample 4985 4986Sometimes, @value{GDBN} cannot set a hardware watchpoint because the 4987data type of the watched expression is wider than what a hardware 4988watchpoint on the target machine can handle. For example, some systems 4989can only watch regions that are up to 4 bytes wide; on such systems you 4990cannot set hardware watchpoints for an expression that yields a 4991double-precision floating-point number (which is typically 8 bytes 4992wide). As a work-around, it might be possible to break the large region 4993into a series of smaller ones and watch them with separate watchpoints. 4994 4995If you set too many hardware watchpoints, @value{GDBN} might be unable 4996to insert all of them when you resume the execution of your program. 4997Since the precise number of active watchpoints is unknown until such 4998time as the program is about to be resumed, @value{GDBN} might not be 4999able to warn you about this when you set the watchpoints, and the 5000warning will be printed only when the program is resumed: 5001 5002@smallexample 5003Hardware watchpoint @var{num}: Could not insert watchpoint 5004@end smallexample 5005 5006@noindent 5007If this happens, delete or disable some of the watchpoints. 5008 5009Watching complex expressions that reference many variables can also 5010exhaust the resources available for hardware-assisted watchpoints. 5011That's because @value{GDBN} needs to watch every variable in the 5012expression with separately allocated resources. 5013 5014If you call a function interactively using @code{print} or @code{call}, 5015any watchpoints you have set will be inactive until @value{GDBN} reaches another 5016kind of breakpoint or the call completes. 5017 5018@value{GDBN} automatically deletes watchpoints that watch local 5019(automatic) variables, or expressions that involve such variables, when 5020they go out of scope, that is, when the execution leaves the block in 5021which these variables were defined. In particular, when the program 5022being debugged terminates, @emph{all} local variables go out of scope, 5023and so only watchpoints that watch global variables remain set. If you 5024rerun the program, you will need to set all such watchpoints again. One 5025way of doing that would be to set a code breakpoint at the entry to the 5026@code{main} function and when it breaks, set all the watchpoints. 5027 5028@cindex watchpoints and threads 5029@cindex threads and watchpoints 5030In multi-threaded programs, watchpoints will detect changes to the 5031watched expression from every thread. 5032 5033@quotation 5034@emph{Warning:} In multi-threaded programs, software watchpoints 5035have only limited usefulness. If @value{GDBN} creates a software 5036watchpoint, it can only watch the value of an expression @emph{in a 5037single thread}. If you are confident that the expression can only 5038change due to the current thread's activity (and if you are also 5039confident that no other thread can become current), then you can use 5040software watchpoints as usual. However, @value{GDBN} may not notice 5041when a non-current thread's activity changes the expression. (Hardware 5042watchpoints, in contrast, watch an expression in all threads.) 5043@end quotation 5044 5045@xref{set remote hardware-watchpoint-limit}. 5046 5047@node Set Catchpoints 5048@subsection Setting Catchpoints 5049@cindex catchpoints, setting 5050@cindex exception handlers 5051@cindex event handling 5052 5053You can use @dfn{catchpoints} to cause the debugger to stop for certain 5054kinds of program events, such as C@t{++} exceptions or the loading of a 5055shared library. Use the @code{catch} command to set a catchpoint. 5056 5057@table @code 5058@kindex catch 5059@item catch @var{event} 5060Stop when @var{event} occurs. The @var{event} can be any of the following: 5061 5062@table @code 5063@item throw @r{[}@var{regexp}@r{]} 5064@itemx rethrow @r{[}@var{regexp}@r{]} 5065@itemx catch @r{[}@var{regexp}@r{]} 5066@kindex catch throw 5067@kindex catch rethrow 5068@kindex catch catch 5069@cindex stop on C@t{++} exceptions 5070The throwing, re-throwing, or catching of a C@t{++} exception. 5071 5072If @var{regexp} is given, then only exceptions whose type matches the 5073regular expression will be caught. 5074 5075@vindex $_exception@r{, convenience variable} 5076The convenience variable @code{$_exception} is available at an 5077exception-related catchpoint, on some systems. This holds the 5078exception being thrown. 5079 5080There are currently some limitations to C@t{++} exception handling in 5081@value{GDBN}: 5082 5083@itemize @bullet 5084@item 5085The support for these commands is system-dependent. Currently, only 5086systems using the @samp{gnu-v3} C@t{++} ABI (@pxref{ABI}) are 5087supported. 5088 5089@item 5090The regular expression feature and the @code{$_exception} convenience 5091variable rely on the presence of some SDT probes in @code{libstdc++}. 5092If these probes are not present, then these features cannot be used. 5093These probes were first available in the GCC 4.8 release, but whether 5094or not they are available in your GCC also depends on how it was 5095built. 5096 5097@item 5098The @code{$_exception} convenience variable is only valid at the 5099instruction at which an exception-related catchpoint is set. 5100 5101@item 5102When an exception-related catchpoint is hit, @value{GDBN} stops at a 5103location in the system library which implements runtime exception 5104support for C@t{++}, usually @code{libstdc++}. You can use @code{up} 5105(@pxref{Selection}) to get to your code. 5106 5107@item 5108If you call a function interactively, @value{GDBN} normally returns 5109control to you when the function has finished executing. If the call 5110raises an exception, however, the call may bypass the mechanism that 5111returns control to you and cause your program either to abort or to 5112simply continue running until it hits a breakpoint, catches a signal 5113that @value{GDBN} is listening for, or exits. This is the case even if 5114you set a catchpoint for the exception; catchpoints on exceptions are 5115disabled within interactive calls. @xref{Calling}, for information on 5116controlling this with @code{set unwind-on-terminating-exception}. 5117 5118@item 5119You cannot raise an exception interactively. 5120 5121@item 5122You cannot install an exception handler interactively. 5123@end itemize 5124 5125@item exception @r{[}@var{name}@r{]} 5126@kindex catch exception 5127@cindex Ada exception catching 5128@cindex catch Ada exceptions 5129An Ada exception being raised. If an exception name is specified 5130at the end of the command (eg @code{catch exception Program_Error}), 5131the debugger will stop only when this specific exception is raised. 5132Otherwise, the debugger stops execution when any Ada exception is raised. 5133 5134When inserting an exception catchpoint on a user-defined exception whose 5135name is identical to one of the exceptions defined by the language, the 5136fully qualified name must be used as the exception name. Otherwise, 5137@value{GDBN} will assume that it should stop on the pre-defined exception 5138rather than the user-defined one. For instance, assuming an exception 5139called @code{Constraint_Error} is defined in package @code{Pck}, then 5140the command to use to catch such exceptions is @kbd{catch exception 5141Pck.Constraint_Error}. 5142 5143@vindex $_ada_exception@r{, convenience variable} 5144The convenience variable @code{$_ada_exception} holds the address of 5145the exception being thrown. This can be useful when setting a 5146condition for such a catchpoint. 5147 5148@item exception unhandled 5149@kindex catch exception unhandled 5150An exception that was raised but is not handled by the program. The 5151convenience variable @code{$_ada_exception} is set as for @code{catch 5152exception}. 5153 5154@item handlers @r{[}@var{name}@r{]} 5155@kindex catch handlers 5156@cindex Ada exception handlers catching 5157@cindex catch Ada exceptions when handled 5158An Ada exception being handled. If an exception name is 5159specified at the end of the command 5160 (eg @kbd{catch handlers Program_Error}), the debugger will stop 5161only when this specific exception is handled. 5162Otherwise, the debugger stops execution when any Ada exception is handled. 5163 5164When inserting a handlers catchpoint on a user-defined 5165exception whose name is identical to one of the exceptions 5166defined by the language, the fully qualified name must be used 5167as the exception name. Otherwise, @value{GDBN} will assume that it 5168should stop on the pre-defined exception rather than the 5169user-defined one. For instance, assuming an exception called 5170 @code{Constraint_Error} is defined in package @code{Pck}, then the 5171command to use to catch such exceptions handling is 5172@kbd{catch handlers Pck.Constraint_Error}. 5173 5174The convenience variable @code{$_ada_exception} is set as for 5175@code{catch exception}. 5176 5177@item assert 5178@kindex catch assert 5179A failed Ada assertion. Note that the convenience variable 5180@code{$_ada_exception} is @emph{not} set by this catchpoint. 5181 5182@item exec 5183@kindex catch exec 5184@cindex break on fork/exec 5185A call to @code{exec}. 5186 5187@anchor{catch syscall} 5188@item syscall 5189@itemx syscall @r{[}@var{name} @r{|} @var{number} @r{|} @r{group:}@var{groupname} @r{|} @r{g:}@var{groupname}@r{]} @dots{} 5190@kindex catch syscall 5191@cindex break on a system call. 5192A call to or return from a system call, a.k.a.@: @dfn{syscall}. A 5193syscall is a mechanism for application programs to request a service 5194from the operating system (OS) or one of the OS system services. 5195@value{GDBN} can catch some or all of the syscalls issued by the 5196debuggee, and show the related information for each syscall. If no 5197argument is specified, calls to and returns from all system calls 5198will be caught. 5199 5200@var{name} can be any system call name that is valid for the 5201underlying OS. Just what syscalls are valid depends on the OS. On 5202GNU and Unix systems, you can find the full list of valid syscall 5203names on @file{/usr/include/asm/unistd.h}. 5204 5205@c For MS-Windows, the syscall names and the corresponding numbers 5206@c can be found, e.g., on this URL: 5207@c http://www.metasploit.com/users/opcode/syscalls.html 5208@c but we don't support Windows syscalls yet. 5209 5210Normally, @value{GDBN} knows in advance which syscalls are valid for 5211each OS, so you can use the @value{GDBN} command-line completion 5212facilities (@pxref{Completion,, command completion}) to list the 5213available choices. 5214 5215You may also specify the system call numerically. A syscall's 5216number is the value passed to the OS's syscall dispatcher to 5217identify the requested service. When you specify the syscall by its 5218name, @value{GDBN} uses its database of syscalls to convert the name 5219into the corresponding numeric code, but using the number directly 5220may be useful if @value{GDBN}'s database does not have the complete 5221list of syscalls on your system (e.g., because @value{GDBN} lags 5222behind the OS upgrades). 5223 5224You may specify a group of related syscalls to be caught at once using 5225the @code{group:} syntax (@code{g:} is a shorter equivalent). For 5226instance, on some platforms @value{GDBN} allows you to catch all 5227network related syscalls, by passing the argument @code{group:network} 5228to @code{catch syscall}. Note that not all syscall groups are 5229available in every system. You can use the command completion 5230facilities (@pxref{Completion,, command completion}) to list the 5231syscall groups available on your environment. 5232 5233The example below illustrates how this command works if you don't provide 5234arguments to it: 5235 5236@smallexample 5237(@value{GDBP}) catch syscall 5238Catchpoint 1 (syscall) 5239(@value{GDBP}) r 5240Starting program: /tmp/catch-syscall 5241 5242Catchpoint 1 (call to syscall 'close'), \ 5243 0xffffe424 in __kernel_vsyscall () 5244(@value{GDBP}) c 5245Continuing. 5246 5247Catchpoint 1 (returned from syscall 'close'), \ 5248 0xffffe424 in __kernel_vsyscall () 5249(@value{GDBP}) 5250@end smallexample 5251 5252Here is an example of catching a system call by name: 5253 5254@smallexample 5255(@value{GDBP}) catch syscall chroot 5256Catchpoint 1 (syscall 'chroot' [61]) 5257(@value{GDBP}) r 5258Starting program: /tmp/catch-syscall 5259 5260Catchpoint 1 (call to syscall 'chroot'), \ 5261 0xffffe424 in __kernel_vsyscall () 5262(@value{GDBP}) c 5263Continuing. 5264 5265Catchpoint 1 (returned from syscall 'chroot'), \ 5266 0xffffe424 in __kernel_vsyscall () 5267(@value{GDBP}) 5268@end smallexample 5269 5270An example of specifying a system call numerically. In the case 5271below, the syscall number has a corresponding entry in the XML 5272file, so @value{GDBN} finds its name and prints it: 5273 5274@smallexample 5275(@value{GDBP}) catch syscall 252 5276Catchpoint 1 (syscall(s) 'exit_group') 5277(@value{GDBP}) r 5278Starting program: /tmp/catch-syscall 5279 5280Catchpoint 1 (call to syscall 'exit_group'), \ 5281 0xffffe424 in __kernel_vsyscall () 5282(@value{GDBP}) c 5283Continuing. 5284 5285Program exited normally. 5286(@value{GDBP}) 5287@end smallexample 5288 5289Here is an example of catching a syscall group: 5290 5291@smallexample 5292(@value{GDBP}) catch syscall group:process 5293Catchpoint 1 (syscalls 'exit' [1] 'fork' [2] 'waitpid' [7] 5294'execve' [11] 'wait4' [114] 'clone' [120] 'vfork' [190] 5295'exit_group' [252] 'waitid' [284] 'unshare' [310]) 5296(@value{GDBP}) r 5297Starting program: /tmp/catch-syscall 5298 5299Catchpoint 1 (call to syscall fork), 0x00007ffff7df4e27 in open64 () 5300 from /lib64/ld-linux-x86-64.so.2 5301 5302(@value{GDBP}) c 5303Continuing. 5304@end smallexample 5305 5306However, there can be situations when there is no corresponding name 5307in XML file for that syscall number. In this case, @value{GDBN} prints 5308a warning message saying that it was not able to find the syscall name, 5309but the catchpoint will be set anyway. See the example below: 5310 5311@smallexample 5312(@value{GDBP}) catch syscall 764 5313warning: The number '764' does not represent a known syscall. 5314Catchpoint 2 (syscall 764) 5315(@value{GDBP}) 5316@end smallexample 5317 5318If you configure @value{GDBN} using the @samp{--without-expat} option, 5319it will not be able to display syscall names. Also, if your 5320architecture does not have an XML file describing its system calls, 5321you will not be able to see the syscall names. It is important to 5322notice that these two features are used for accessing the syscall 5323name database. In either case, you will see a warning like this: 5324 5325@smallexample 5326(@value{GDBP}) catch syscall 5327warning: Could not open "syscalls/i386-linux.xml" 5328warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'. 5329GDB will not be able to display syscall names. 5330Catchpoint 1 (syscall) 5331(@value{GDBP}) 5332@end smallexample 5333 5334Of course, the file name will change depending on your architecture and system. 5335 5336Still using the example above, you can also try to catch a syscall by its 5337number. In this case, you would see something like: 5338 5339@smallexample 5340(@value{GDBP}) catch syscall 252 5341Catchpoint 1 (syscall(s) 252) 5342@end smallexample 5343 5344Again, in this case @value{GDBN} would not be able to display syscall's names. 5345 5346@item fork 5347@kindex catch fork 5348A call to @code{fork}. 5349 5350@item vfork 5351@kindex catch vfork 5352A call to @code{vfork}. 5353 5354@item load @r{[}@var{regexp}@r{]} 5355@itemx unload @r{[}@var{regexp}@r{]} 5356@kindex catch load 5357@kindex catch unload 5358The loading or unloading of a shared library. If @var{regexp} is 5359given, then the catchpoint will stop only if the regular expression 5360matches one of the affected libraries. 5361 5362@item signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]} 5363@kindex catch signal 5364The delivery of a signal. 5365 5366With no arguments, this catchpoint will catch any signal that is not 5367used internally by @value{GDBN}, specifically, all signals except 5368@samp{SIGTRAP} and @samp{SIGINT}. 5369 5370With the argument @samp{all}, all signals, including those used by 5371@value{GDBN}, will be caught. This argument cannot be used with other 5372signal names. 5373 5374Otherwise, the arguments are a list of signal names as given to 5375@code{handle} (@pxref{Signals}). Only signals specified in this list 5376will be caught. 5377 5378One reason that @code{catch signal} can be more useful than 5379@code{handle} is that you can attach commands and conditions to the 5380catchpoint. 5381 5382When a signal is caught by a catchpoint, the signal's @code{stop} and 5383@code{print} settings, as specified by @code{handle}, are ignored. 5384However, whether the signal is still delivered to the inferior depends 5385on the @code{pass} setting; this can be changed in the catchpoint's 5386commands. 5387 5388@end table 5389 5390@item tcatch @var{event} 5391@kindex tcatch 5392Set a catchpoint that is enabled only for one stop. The catchpoint is 5393automatically deleted after the first time the event is caught. 5394 5395@end table 5396 5397Use the @code{info break} command to list the current catchpoints. 5398 5399 5400@node Delete Breaks 5401@subsection Deleting Breakpoints 5402 5403@cindex clearing breakpoints, watchpoints, catchpoints 5404@cindex deleting breakpoints, watchpoints, catchpoints 5405It is often necessary to eliminate a breakpoint, watchpoint, or 5406catchpoint once it has done its job and you no longer want your program 5407to stop there. This is called @dfn{deleting} the breakpoint. A 5408breakpoint that has been deleted no longer exists; it is forgotten. 5409 5410With the @code{clear} command you can delete breakpoints according to 5411where they are in your program. With the @code{delete} command you can 5412delete individual breakpoints, watchpoints, or catchpoints by specifying 5413their breakpoint numbers. 5414 5415It is not necessary to delete a breakpoint to proceed past it. @value{GDBN} 5416automatically ignores breakpoints on the first instruction to be executed 5417when you continue execution without changing the execution address. 5418 5419@table @code 5420@kindex clear 5421@item clear 5422Delete any breakpoints at the next instruction to be executed in the 5423selected stack frame (@pxref{Selection, ,Selecting a Frame}). When 5424the innermost frame is selected, this is a good way to delete a 5425breakpoint where your program just stopped. 5426 5427@item clear @var{location} 5428Delete any breakpoints set at the specified @var{location}. 5429@xref{Specify Location}, for the various forms of @var{location}; the 5430most useful ones are listed below: 5431 5432@table @code 5433@item clear @var{function} 5434@itemx clear @var{filename}:@var{function} 5435Delete any breakpoints set at entry to the named @var{function}. 5436 5437@item clear @var{linenum} 5438@itemx clear @var{filename}:@var{linenum} 5439Delete any breakpoints set at or within the code of the specified 5440@var{linenum} of the specified @var{filename}. 5441@end table 5442 5443@cindex delete breakpoints 5444@kindex delete 5445@kindex d @r{(@code{delete})} 5446@item delete @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]} 5447Delete the breakpoints, watchpoints, or catchpoints of the breakpoint 5448list specified as argument. If no argument is specified, delete all 5449breakpoints (@value{GDBN} asks confirmation, unless you have @code{set 5450confirm off}). You can abbreviate this command as @code{d}. 5451@end table 5452 5453@node Disabling 5454@subsection Disabling Breakpoints 5455 5456@cindex enable/disable a breakpoint 5457Rather than deleting a breakpoint, watchpoint, or catchpoint, you might 5458prefer to @dfn{disable} it. This makes the breakpoint inoperative as if 5459it had been deleted, but remembers the information on the breakpoint so 5460that you can @dfn{enable} it again later. 5461 5462You disable and enable breakpoints, watchpoints, and catchpoints with 5463the @code{enable} and @code{disable} commands, optionally specifying 5464one or more breakpoint numbers as arguments. Use @code{info break} to 5465print a list of all breakpoints, watchpoints, and catchpoints if you 5466do not know which numbers to use. 5467 5468Disabling and enabling a breakpoint that has multiple locations 5469affects all of its locations. 5470 5471A breakpoint, watchpoint, or catchpoint can have any of several 5472different states of enablement: 5473 5474@itemize @bullet 5475@item 5476Enabled. The breakpoint stops your program. A breakpoint set 5477with the @code{break} command starts out in this state. 5478@item 5479Disabled. The breakpoint has no effect on your program. 5480@item 5481Enabled once. The breakpoint stops your program, but then becomes 5482disabled. 5483@item 5484Enabled for a count. The breakpoint stops your program for the next 5485N times, then becomes disabled. 5486@item 5487Enabled for deletion. The breakpoint stops your program, but 5488immediately after it does so it is deleted permanently. A breakpoint 5489set with the @code{tbreak} command starts out in this state. 5490@end itemize 5491 5492You can use the following commands to enable or disable breakpoints, 5493watchpoints, and catchpoints: 5494 5495@table @code 5496@kindex disable 5497@kindex dis @r{(@code{disable})} 5498@item disable @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]} 5499Disable the specified breakpoints---or all breakpoints, if none are 5500listed. A disabled breakpoint has no effect but is not forgotten. All 5501options such as ignore-counts, conditions and commands are remembered in 5502case the breakpoint is enabled again later. You may abbreviate 5503@code{disable} as @code{dis}. 5504 5505@kindex enable 5506@item enable @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]} 5507Enable the specified breakpoints (or all defined breakpoints). They 5508become effective once again in stopping your program. 5509 5510@item enable @r{[}breakpoints@r{]} once @var{list}@dots{} 5511Enable the specified breakpoints temporarily. @value{GDBN} disables any 5512of these breakpoints immediately after stopping your program. 5513 5514@item enable @r{[}breakpoints@r{]} count @var{count} @var{list}@dots{} 5515Enable the specified breakpoints temporarily. @value{GDBN} records 5516@var{count} with each of the specified breakpoints, and decrements a 5517breakpoint's count when it is hit. When any count reaches 0, 5518@value{GDBN} disables that breakpoint. If a breakpoint has an ignore 5519count (@pxref{Conditions, ,Break Conditions}), that will be 5520decremented to 0 before @var{count} is affected. 5521 5522@item enable @r{[}breakpoints@r{]} delete @var{list}@dots{} 5523Enable the specified breakpoints to work once, then die. @value{GDBN} 5524deletes any of these breakpoints as soon as your program stops there. 5525Breakpoints set by the @code{tbreak} command start out in this state. 5526@end table 5527 5528@c FIXME: I think the following ``Except for [...] @code{tbreak}'' is 5529@c confusing: tbreak is also initially enabled. 5530Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks, 5531,Setting Breakpoints}), breakpoints that you set are initially enabled; 5532subsequently, they become disabled or enabled only when you use one of 5533the commands above. (The command @code{until} can set and delete a 5534breakpoint of its own, but it does not change the state of your other 5535breakpoints; see @ref{Continuing and Stepping, ,Continuing and 5536Stepping}.) 5537 5538@node Conditions 5539@subsection Break Conditions 5540@cindex conditional breakpoints 5541@cindex breakpoint conditions 5542 5543@c FIXME what is scope of break condition expr? Context where wanted? 5544@c in particular for a watchpoint? 5545The simplest sort of breakpoint breaks every time your program reaches a 5546specified place. You can also specify a @dfn{condition} for a 5547breakpoint. A condition is just a Boolean expression in your 5548programming language (@pxref{Expressions, ,Expressions}). A breakpoint with 5549a condition evaluates the expression each time your program reaches it, 5550and your program stops only if the condition is @emph{true}. 5551 5552This is the converse of using assertions for program validation; in that 5553situation, you want to stop when the assertion is violated---that is, 5554when the condition is false. In C, if you want to test an assertion expressed 5555by the condition @var{assert}, you should set the condition 5556@samp{! @var{assert}} on the appropriate breakpoint. 5557 5558Conditions are also accepted for watchpoints; you may not need them, 5559since a watchpoint is inspecting the value of an expression anyhow---but 5560it might be simpler, say, to just set a watchpoint on a variable name, 5561and specify a condition that tests whether the new value is an interesting 5562one. 5563 5564Break conditions can have side effects, and may even call functions in 5565your program. This can be useful, for example, to activate functions 5566that log program progress, or to use your own print functions to 5567format special data structures. The effects are completely predictable 5568unless there is another enabled breakpoint at the same address. (In 5569that case, @value{GDBN} might see the other breakpoint first and stop your 5570program without checking the condition of this one.) Note that 5571breakpoint commands are usually more convenient and flexible than break 5572conditions for the 5573purpose of performing side effects when a breakpoint is reached 5574(@pxref{Break Commands, ,Breakpoint Command Lists}). 5575 5576Breakpoint conditions can also be evaluated on the target's side if 5577the target supports it. Instead of evaluating the conditions locally, 5578@value{GDBN} encodes the expression into an agent expression 5579(@pxref{Agent Expressions}) suitable for execution on the target, 5580independently of @value{GDBN}. Global variables become raw memory 5581locations, locals become stack accesses, and so forth. 5582 5583In this case, @value{GDBN} will only be notified of a breakpoint trigger 5584when its condition evaluates to true. This mechanism may provide faster 5585response times depending on the performance characteristics of the target 5586since it does not need to keep @value{GDBN} informed about 5587every breakpoint trigger, even those with false conditions. 5588 5589Break conditions can be specified when a breakpoint is set, by using 5590@samp{if} in the arguments to the @code{break} command. @xref{Set 5591Breaks, ,Setting Breakpoints}. They can also be changed at any time 5592with the @code{condition} command. 5593 5594You can also use the @code{if} keyword with the @code{watch} command. 5595The @code{catch} command does not recognize the @code{if} keyword; 5596@code{condition} is the only way to impose a further condition on a 5597catchpoint. 5598 5599@table @code 5600@kindex condition 5601@item condition @var{bnum} @var{expression} 5602Specify @var{expression} as the break condition for breakpoint, 5603watchpoint, or catchpoint number @var{bnum}. After you set a condition, 5604breakpoint @var{bnum} stops your program only if the value of 5605@var{expression} is true (nonzero, in C). When you use 5606@code{condition}, @value{GDBN} checks @var{expression} immediately for 5607syntactic correctness, and to determine whether symbols in it have 5608referents in the context of your breakpoint. If @var{expression} uses 5609symbols not referenced in the context of the breakpoint, @value{GDBN} 5610prints an error message: 5611 5612@smallexample 5613No symbol "foo" in current context. 5614@end smallexample 5615 5616@noindent 5617@value{GDBN} does 5618not actually evaluate @var{expression} at the time the @code{condition} 5619command (or a command that sets a breakpoint with a condition, like 5620@code{break if @dots{}}) is given, however. @xref{Expressions, ,Expressions}. 5621 5622@item condition -force @var{bnum} @var{expression} 5623When the @code{-force} flag is used, define the condition even if 5624@var{expression} is invalid at all the current locations of breakpoint 5625@var{bnum}. This is similar to the @code{-force-condition} option 5626of the @code{break} command. 5627 5628@item condition @var{bnum} 5629Remove the condition from breakpoint number @var{bnum}. It becomes 5630an ordinary unconditional breakpoint. 5631@end table 5632 5633@cindex ignore count (of breakpoint) 5634A special case of a breakpoint condition is to stop only when the 5635breakpoint has been reached a certain number of times. This is so 5636useful that there is a special way to do it, using the @dfn{ignore 5637count} of the breakpoint. Every breakpoint has an ignore count, which 5638is an integer. Most of the time, the ignore count is zero, and 5639therefore has no effect. But if your program reaches a breakpoint whose 5640ignore count is positive, then instead of stopping, it just decrements 5641the ignore count by one and continues. As a result, if the ignore count 5642value is @var{n}, the breakpoint does not stop the next @var{n} times 5643your program reaches it. 5644 5645@table @code 5646@kindex ignore 5647@item ignore @var{bnum} @var{count} 5648Set the ignore count of breakpoint number @var{bnum} to @var{count}. 5649The next @var{count} times the breakpoint is reached, your program's 5650execution does not stop; other than to decrement the ignore count, @value{GDBN} 5651takes no action. 5652 5653To make the breakpoint stop the next time it is reached, specify 5654a count of zero. 5655 5656When you use @code{continue} to resume execution of your program from a 5657breakpoint, you can specify an ignore count directly as an argument to 5658@code{continue}, rather than using @code{ignore}. @xref{Continuing and 5659Stepping,,Continuing and Stepping}. 5660 5661If a breakpoint has a positive ignore count and a condition, the 5662condition is not checked. Once the ignore count reaches zero, 5663@value{GDBN} resumes checking the condition. 5664 5665You could achieve the effect of the ignore count with a condition such 5666as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that 5667is decremented each time. @xref{Convenience Vars, ,Convenience 5668Variables}. 5669@end table 5670 5671Ignore counts apply to breakpoints, watchpoints, and catchpoints. 5672 5673 5674@node Break Commands 5675@subsection Breakpoint Command Lists 5676 5677@cindex breakpoint commands 5678You can give any breakpoint (or watchpoint or catchpoint) a series of 5679commands to execute when your program stops due to that breakpoint. For 5680example, you might want to print the values of certain expressions, or 5681enable other breakpoints. 5682 5683@table @code 5684@kindex commands 5685@kindex end@r{ (breakpoint commands)} 5686@item commands @r{[}@var{list}@dots{}@r{]} 5687@itemx @dots{} @var{command-list} @dots{} 5688@itemx end 5689Specify a list of commands for the given breakpoints. The commands 5690themselves appear on the following lines. Type a line containing just 5691@code{end} to terminate the commands. 5692 5693To remove all commands from a breakpoint, type @code{commands} and 5694follow it immediately with @code{end}; that is, give no commands. 5695 5696With no argument, @code{commands} refers to the last breakpoint, 5697watchpoint, or catchpoint set (not to the breakpoint most recently 5698encountered). If the most recent breakpoints were set with a single 5699command, then the @code{commands} will apply to all the breakpoints 5700set by that command. This applies to breakpoints set by 5701@code{rbreak}, and also applies when a single @code{break} command 5702creates multiple breakpoints (@pxref{Ambiguous Expressions,,Ambiguous 5703Expressions}). 5704@end table 5705 5706Pressing @key{RET} as a means of repeating the last @value{GDBN} command is 5707disabled within a @var{command-list}. 5708 5709You can use breakpoint commands to start your program up again. Simply 5710use the @code{continue} command, or @code{step}, or any other command 5711that resumes execution. 5712 5713Any other commands in the command list, after a command that resumes 5714execution, are ignored. This is because any time you resume execution 5715(even with a simple @code{next} or @code{step}), you may encounter 5716another breakpoint---which could have its own command list, leading to 5717ambiguities about which list to execute. 5718 5719@kindex silent 5720If the first command you specify in a command list is @code{silent}, the 5721usual message about stopping at a breakpoint is not printed. This may 5722be desirable for breakpoints that are to print a specific message and 5723then continue. If none of the remaining commands print anything, you 5724see no sign that the breakpoint was reached. @code{silent} is 5725meaningful only at the beginning of a breakpoint command list. 5726 5727The commands @code{echo}, @code{output}, and @code{printf} allow you to 5728print precisely controlled output, and are often useful in silent 5729breakpoints. @xref{Output, ,Commands for Controlled Output}. 5730 5731For example, here is how you could use breakpoint commands to print the 5732value of @code{x} at entry to @code{foo} whenever @code{x} is positive. 5733 5734@smallexample 5735break foo if x>0 5736commands 5737silent 5738printf "x is %d\n",x 5739cont 5740end 5741@end smallexample 5742 5743One application for breakpoint commands is to compensate for one bug so 5744you can test for another. Put a breakpoint just after the erroneous line 5745of code, give it a condition to detect the case in which something 5746erroneous has been done, and give it commands to assign correct values 5747to any variables that need them. End with the @code{continue} command 5748so that your program does not stop, and start with the @code{silent} 5749command so that no output is produced. Here is an example: 5750 5751@smallexample 5752break 403 5753commands 5754silent 5755set x = y + 4 5756cont 5757end 5758@end smallexample 5759 5760@node Dynamic Printf 5761@subsection Dynamic Printf 5762 5763@cindex dynamic printf 5764@cindex dprintf 5765The dynamic printf command @code{dprintf} combines a breakpoint with 5766formatted printing of your program's data to give you the effect of 5767inserting @code{printf} calls into your program on-the-fly, without 5768having to recompile it. 5769 5770In its most basic form, the output goes to the GDB console. However, 5771you can set the variable @code{dprintf-style} for alternate handling. 5772For instance, you can ask to format the output by calling your 5773program's @code{printf} function. This has the advantage that the 5774characters go to the program's output device, so they can recorded in 5775redirects to files and so forth. 5776 5777If you are doing remote debugging with a stub or agent, you can also 5778ask to have the printf handled by the remote agent. In addition to 5779ensuring that the output goes to the remote program's device along 5780with any other output the program might produce, you can also ask that 5781the dprintf remain active even after disconnecting from the remote 5782target. Using the stub/agent is also more efficient, as it can do 5783everything without needing to communicate with @value{GDBN}. 5784 5785@table @code 5786@kindex dprintf 5787@item dprintf @var{location},@var{template},@var{expression}[,@var{expression}@dots{}] 5788Whenever execution reaches @var{location}, print the values of one or 5789more @var{expressions} under the control of the string @var{template}. 5790To print several values, separate them with commas. 5791 5792@item set dprintf-style @var{style} 5793Set the dprintf output to be handled in one of several different 5794styles enumerated below. A change of style affects all existing 5795dynamic printfs immediately. (If you need individual control over the 5796print commands, simply define normal breakpoints with 5797explicitly-supplied command lists.) 5798 5799@table @code 5800@item gdb 5801@kindex dprintf-style gdb 5802Handle the output using the @value{GDBN} @code{printf} command. 5803 5804@item call 5805@kindex dprintf-style call 5806Handle the output by calling a function in your program (normally 5807@code{printf}). 5808 5809@item agent 5810@kindex dprintf-style agent 5811Have the remote debugging agent (such as @code{gdbserver}) handle 5812the output itself. This style is only available for agents that 5813support running commands on the target. 5814@end table 5815 5816@item set dprintf-function @var{function} 5817Set the function to call if the dprintf style is @code{call}. By 5818default its value is @code{printf}. You may set it to any expression. 5819that @value{GDBN} can evaluate to a function, as per the @code{call} 5820command. 5821 5822@item set dprintf-channel @var{channel} 5823Set a ``channel'' for dprintf. If set to a non-empty value, 5824@value{GDBN} will evaluate it as an expression and pass the result as 5825a first argument to the @code{dprintf-function}, in the manner of 5826@code{fprintf} and similar functions. Otherwise, the dprintf format 5827string will be the first argument, in the manner of @code{printf}. 5828 5829As an example, if you wanted @code{dprintf} output to go to a logfile 5830that is a standard I/O stream assigned to the variable @code{mylog}, 5831you could do the following: 5832 5833@example 5834(gdb) set dprintf-style call 5835(gdb) set dprintf-function fprintf 5836(gdb) set dprintf-channel mylog 5837(gdb) dprintf 25,"at line 25, glob=%d\n",glob 5838Dprintf 1 at 0x123456: file main.c, line 25. 5839(gdb) info break 58401 dprintf keep y 0x00123456 in main at main.c:25 5841 call (void) fprintf (mylog,"at line 25, glob=%d\n",glob) 5842 continue 5843(gdb) 5844@end example 5845 5846Note that the @code{info break} displays the dynamic printf commands 5847as normal breakpoint commands; you can thus easily see the effect of 5848the variable settings. 5849 5850@item set disconnected-dprintf on 5851@itemx set disconnected-dprintf off 5852@kindex set disconnected-dprintf 5853Choose whether @code{dprintf} commands should continue to run if 5854@value{GDBN} has disconnected from the target. This only applies 5855if the @code{dprintf-style} is @code{agent}. 5856 5857@item show disconnected-dprintf off 5858@kindex show disconnected-dprintf 5859Show the current choice for disconnected @code{dprintf}. 5860 5861@end table 5862 5863@value{GDBN} does not check the validity of function and channel, 5864relying on you to supply values that are meaningful for the contexts 5865in which they are being used. For instance, the function and channel 5866may be the values of local variables, but if that is the case, then 5867all enabled dynamic prints must be at locations within the scope of 5868those locals. If evaluation fails, @value{GDBN} will report an error. 5869 5870@node Save Breakpoints 5871@subsection How to save breakpoints to a file 5872 5873To save breakpoint definitions to a file use the @w{@code{save 5874breakpoints}} command. 5875 5876@table @code 5877@kindex save breakpoints 5878@cindex save breakpoints to a file for future sessions 5879@item save breakpoints [@var{filename}] 5880This command saves all current breakpoint definitions together with 5881their commands and ignore counts, into a file @file{@var{filename}} 5882suitable for use in a later debugging session. This includes all 5883types of breakpoints (breakpoints, watchpoints, catchpoints, 5884tracepoints). To read the saved breakpoint definitions, use the 5885@code{source} command (@pxref{Command Files}). Note that watchpoints 5886with expressions involving local variables may fail to be recreated 5887because it may not be possible to access the context where the 5888watchpoint is valid anymore. Because the saved breakpoint definitions 5889are simply a sequence of @value{GDBN} commands that recreate the 5890breakpoints, you can edit the file in your favorite editing program, 5891and remove the breakpoint definitions you're not interested in, or 5892that can no longer be recreated. 5893@end table 5894 5895@node Static Probe Points 5896@subsection Static Probe Points 5897 5898@cindex static probe point, SystemTap 5899@cindex static probe point, DTrace 5900@value{GDBN} supports @dfn{SDT} probes in the code. @acronym{SDT} stands 5901for Statically Defined Tracing, and the probes are designed to have a tiny 5902runtime code and data footprint, and no dynamic relocations. 5903 5904Currently, the following types of probes are supported on 5905ELF-compatible systems: 5906 5907@itemize @bullet 5908 5909@item @code{SystemTap} (@uref{http://sourceware.org/systemtap/}) 5910@acronym{SDT} probes@footnote{See 5911@uref{http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps} 5912for more information on how to add @code{SystemTap} @acronym{SDT} 5913probes in your applications.}. @code{SystemTap} probes are usable 5914from assembly, C and C@t{++} languages@footnote{See 5915@uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation} 5916for a good reference on how the @acronym{SDT} probes are implemented.}. 5917 5918@item @code{DTrace} (@uref{http://oss.oracle.com/projects/DTrace}) 5919@acronym{USDT} probes. @code{DTrace} probes are usable from C and 5920C@t{++} languages. 5921@end itemize 5922 5923@cindex semaphores on static probe points 5924Some @code{SystemTap} probes have an associated semaphore variable; 5925for instance, this happens automatically if you defined your probe 5926using a DTrace-style @file{.d} file. If your probe has a semaphore, 5927@value{GDBN} will automatically enable it when you specify a 5928breakpoint using the @samp{-probe-stap} notation. But, if you put a 5929breakpoint at a probe's location by some other method (e.g., 5930@code{break file:line}), then @value{GDBN} will not automatically set 5931the semaphore. @code{DTrace} probes do not support semaphores. 5932 5933You can examine the available static static probes using @code{info 5934probes}, with optional arguments: 5935 5936@table @code 5937@kindex info probes 5938@item info probes @r{[}@var{type}@r{]} @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]} 5939If given, @var{type} is either @code{stap} for listing 5940@code{SystemTap} probes or @code{dtrace} for listing @code{DTrace} 5941probes. If omitted all probes are listed regardless of their types. 5942 5943If given, @var{provider} is a regular expression used to match against provider 5944names when selecting which probes to list. If omitted, probes by all 5945probes from all providers are listed. 5946 5947If given, @var{name} is a regular expression to match against probe names 5948when selecting which probes to list. If omitted, probe names are not 5949considered when deciding whether to display them. 5950 5951If given, @var{objfile} is a regular expression used to select which 5952object files (executable or shared libraries) to examine. If not 5953given, all object files are considered. 5954 5955@item info probes all 5956List the available static probes, from all types. 5957@end table 5958 5959@cindex enabling and disabling probes 5960Some probe points can be enabled and/or disabled. The effect of 5961enabling or disabling a probe depends on the type of probe being 5962handled. Some @code{DTrace} probes can be enabled or 5963disabled, but @code{SystemTap} probes cannot be disabled. 5964 5965You can enable (or disable) one or more probes using the following 5966commands, with optional arguments: 5967 5968@table @code 5969@kindex enable probes 5970@item enable probes @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]} 5971If given, @var{provider} is a regular expression used to match against 5972provider names when selecting which probes to enable. If omitted, 5973all probes from all providers are enabled. 5974 5975If given, @var{name} is a regular expression to match against probe 5976names when selecting which probes to enable. If omitted, probe names 5977are not considered when deciding whether to enable them. 5978 5979If given, @var{objfile} is a regular expression used to select which 5980object files (executable or shared libraries) to examine. If not 5981given, all object files are considered. 5982 5983@kindex disable probes 5984@item disable probes @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]} 5985See the @code{enable probes} command above for a description of the 5986optional arguments accepted by this command. 5987@end table 5988 5989@vindex $_probe_arg@r{, convenience variable} 5990A probe may specify up to twelve arguments. These are available at the 5991point at which the probe is defined---that is, when the current PC is 5992at the probe's location. The arguments are available using the 5993convenience variables (@pxref{Convenience Vars}) 5994@code{$_probe_arg0}@dots{}@code{$_probe_arg11}. In @code{SystemTap} 5995probes each probe argument is an integer of the appropriate size; 5996types are not preserved. In @code{DTrace} probes types are preserved 5997provided that they are recognized as such by @value{GDBN}; otherwise 5998the value of the probe argument will be a long integer. The 5999convenience variable @code{$_probe_argc} holds the number of arguments 6000at the current probe point. 6001 6002These variables are always available, but attempts to access them at 6003any location other than a probe point will cause @value{GDBN} to give 6004an error message. 6005 6006 6007@c @ifclear BARETARGET 6008@node Error in Breakpoints 6009@subsection ``Cannot insert breakpoints'' 6010 6011If you request too many active hardware-assisted breakpoints and 6012watchpoints, you will see this error message: 6013 6014@c FIXME: the precise wording of this message may change; the relevant 6015@c source change is not committed yet (Sep 3, 1999). 6016@smallexample 6017Stopped; cannot insert breakpoints. 6018You may have requested too many hardware breakpoints and watchpoints. 6019@end smallexample 6020 6021@noindent 6022This message is printed when you attempt to resume the program, since 6023only then @value{GDBN} knows exactly how many hardware breakpoints and 6024watchpoints it needs to insert. 6025 6026When this message is printed, you need to disable or remove some of the 6027hardware-assisted breakpoints and watchpoints, and then continue. 6028 6029@node Breakpoint-related Warnings 6030@subsection ``Breakpoint address adjusted...'' 6031@cindex breakpoint address adjusted 6032 6033Some processor architectures place constraints on the addresses at 6034which breakpoints may be placed. For architectures thus constrained, 6035@value{GDBN} will attempt to adjust the breakpoint's address to comply 6036with the constraints dictated by the architecture. 6037 6038One example of such an architecture is the Fujitsu FR-V. The FR-V is 6039a VLIW architecture in which a number of RISC-like instructions may be 6040bundled together for parallel execution. The FR-V architecture 6041constrains the location of a breakpoint instruction within such a 6042bundle to the instruction with the lowest address. @value{GDBN} 6043honors this constraint by adjusting a breakpoint's address to the 6044first in the bundle. 6045 6046It is not uncommon for optimized code to have bundles which contain 6047instructions from different source statements, thus it may happen that 6048a breakpoint's address will be adjusted from one source statement to 6049another. Since this adjustment may significantly alter @value{GDBN}'s 6050breakpoint related behavior from what the user expects, a warning is 6051printed when the breakpoint is first set and also when the breakpoint 6052is hit. 6053 6054A warning like the one below is printed when setting a breakpoint 6055that's been subject to address adjustment: 6056 6057@smallexample 6058warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. 6059@end smallexample 6060 6061Such warnings are printed both for user settable and @value{GDBN}'s 6062internal breakpoints. If you see one of these warnings, you should 6063verify that a breakpoint set at the adjusted address will have the 6064desired affect. If not, the breakpoint in question may be removed and 6065other breakpoints may be set which will have the desired behavior. 6066E.g., it may be sufficient to place the breakpoint at a later 6067instruction. A conditional breakpoint may also be useful in some 6068cases to prevent the breakpoint from triggering too often. 6069 6070@value{GDBN} will also issue a warning when stopping at one of these 6071adjusted breakpoints: 6072 6073@smallexample 6074warning: Breakpoint 1 address previously adjusted from 0x00010414 6075to 0x00010410. 6076@end smallexample 6077 6078When this warning is encountered, it may be too late to take remedial 6079action except in cases where the breakpoint is hit earlier or more 6080frequently than expected. 6081 6082@node Continuing and Stepping 6083@section Continuing and Stepping 6084 6085@cindex stepping 6086@cindex continuing 6087@cindex resuming execution 6088@dfn{Continuing} means resuming program execution until your program 6089completes normally. In contrast, @dfn{stepping} means executing just 6090one more ``step'' of your program, where ``step'' may mean either one 6091line of source code, or one machine instruction (depending on what 6092particular command you use). Either when continuing or when stepping, 6093your program may stop even sooner, due to a breakpoint or a signal. (If 6094it stops due to a signal, you may want to use @code{handle}, or use 6095@samp{signal 0} to resume execution (@pxref{Signals, ,Signals}), 6096or you may step into the signal's handler (@pxref{stepping and signal 6097handlers}).) 6098 6099@table @code 6100@kindex continue 6101@kindex c @r{(@code{continue})} 6102@kindex fg @r{(resume foreground execution)} 6103@item continue @r{[}@var{ignore-count}@r{]} 6104@itemx c @r{[}@var{ignore-count}@r{]} 6105@itemx fg @r{[}@var{ignore-count}@r{]} 6106Resume program execution, at the address where your program last stopped; 6107any breakpoints set at that address are bypassed. The optional argument 6108@var{ignore-count} allows you to specify a further number of times to 6109ignore a breakpoint at this location; its effect is like that of 6110@code{ignore} (@pxref{Conditions, ,Break Conditions}). 6111 6112The argument @var{ignore-count} is meaningful only when your program 6113stopped due to a breakpoint. At other times, the argument to 6114@code{continue} is ignored. 6115 6116The synonyms @code{c} and @code{fg} (for @dfn{foreground}, as the 6117debugged program is deemed to be the foreground program) are provided 6118purely for convenience, and have exactly the same behavior as 6119@code{continue}. 6120@end table 6121 6122To resume execution at a different place, you can use @code{return} 6123(@pxref{Returning, ,Returning from a Function}) to go back to the 6124calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a 6125Different Address}) to go to an arbitrary location in your program. 6126 6127A typical technique for using stepping is to set a breakpoint 6128(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Catchpoints}) at the 6129beginning of the function or the section of your program where a problem 6130is believed to lie, run your program until it stops at that breakpoint, 6131and then step through the suspect area, examining the variables that are 6132interesting, until you see the problem happen. 6133 6134@table @code 6135@kindex step 6136@kindex s @r{(@code{step})} 6137@item step 6138Continue running your program until control reaches a different source 6139line, then stop it and return control to @value{GDBN}. This command is 6140abbreviated @code{s}. 6141 6142@quotation 6143@c "without debugging information" is imprecise; actually "without line 6144@c numbers in the debugging information". (gcc -g1 has debugging info but 6145@c not line numbers). But it seems complex to try to make that 6146@c distinction here. 6147@emph{Warning:} If you use the @code{step} command while control is 6148within a function that was compiled without debugging information, 6149execution proceeds until control reaches a function that does have 6150debugging information. Likewise, it will not step into a function which 6151is compiled without debugging information. To step through functions 6152without debugging information, use the @code{stepi} command, described 6153below. 6154@end quotation 6155 6156The @code{step} command only stops at the first instruction of a source 6157line. This prevents the multiple stops that could otherwise occur in 6158@code{switch} statements, @code{for} loops, etc. @code{step} continues 6159to stop if a function that has debugging information is called within 6160the line. In other words, @code{step} @emph{steps inside} any functions 6161called within the line. 6162 6163Also, the @code{step} command only enters a function if there is line 6164number information for the function. Otherwise it acts like the 6165@code{next} command. This avoids problems when using @code{cc -gl} 6166on @acronym{MIPS} machines. Previously, @code{step} entered subroutines if there 6167was any debugging information about the routine. 6168 6169@item step @var{count} 6170Continue running as in @code{step}, but do so @var{count} times. If a 6171breakpoint is reached, or a signal not related to stepping occurs before 6172@var{count} steps, stepping stops right away. 6173 6174@kindex next 6175@kindex n @r{(@code{next})} 6176@item next @r{[}@var{count}@r{]} 6177Continue to the next source line in the current (innermost) stack frame. 6178This is similar to @code{step}, but function calls that appear within 6179the line of code are executed without stopping. Execution stops when 6180control reaches a different line of code at the original stack level 6181that was executing when you gave the @code{next} command. This command 6182is abbreviated @code{n}. 6183 6184An argument @var{count} is a repeat count, as for @code{step}. 6185 6186 6187@c FIX ME!! Do we delete this, or is there a way it fits in with 6188@c the following paragraph? --- Vctoria 6189@c 6190@c @code{next} within a function that lacks debugging information acts like 6191@c @code{step}, but any function calls appearing within the code of the 6192@c function are executed without stopping. 6193 6194The @code{next} command only stops at the first instruction of a 6195source line. This prevents multiple stops that could otherwise occur in 6196@code{switch} statements, @code{for} loops, etc. 6197 6198@kindex set step-mode 6199@item set step-mode 6200@cindex functions without line info, and stepping 6201@cindex stepping into functions with no line info 6202@itemx set step-mode on 6203The @code{set step-mode on} command causes the @code{step} command to 6204stop at the first instruction of a function which contains no debug line 6205information rather than stepping over it. 6206 6207This is useful in cases where you may be interested in inspecting the 6208machine instructions of a function which has no symbolic info and do not 6209want @value{GDBN} to automatically skip over this function. 6210 6211@item set step-mode off 6212Causes the @code{step} command to step over any functions which contains no 6213debug information. This is the default. 6214 6215@item show step-mode 6216Show whether @value{GDBN} will stop in or step over functions without 6217source line debug information. 6218 6219@kindex finish 6220@kindex fin @r{(@code{finish})} 6221@item finish 6222Continue running until just after function in the selected stack frame 6223returns. Print the returned value (if any). This command can be 6224abbreviated as @code{fin}. 6225 6226Contrast this with the @code{return} command (@pxref{Returning, 6227,Returning from a Function}). 6228 6229@kindex set print finish 6230@kindex show print finish 6231@item set print finish @r{[}on|off@r{]} 6232@itemx show print finish 6233By default the @code{finish} command will show the value that is 6234returned by the function. This can be disabled using @code{set print 6235finish off}. When disabled, the value is still entered into the value 6236history (@pxref{Value History}), but not displayed. 6237 6238@kindex until 6239@kindex u @r{(@code{until})} 6240@cindex run until specified location 6241@item until 6242@itemx u 6243Continue running until a source line past the current line, in the 6244current stack frame, is reached. This command is used to avoid single 6245stepping through a loop more than once. It is like the @code{next} 6246command, except that when @code{until} encounters a jump, it 6247automatically continues execution until the program counter is greater 6248than the address of the jump. 6249 6250This means that when you reach the end of a loop after single stepping 6251though it, @code{until} makes your program continue execution until it 6252exits the loop. In contrast, a @code{next} command at the end of a loop 6253simply steps back to the beginning of the loop, which forces you to step 6254through the next iteration. 6255 6256@code{until} always stops your program if it attempts to exit the current 6257stack frame. 6258 6259@code{until} may produce somewhat counterintuitive results if the order 6260of machine code does not match the order of the source lines. For 6261example, in the following excerpt from a debugging session, the @code{f} 6262(@code{frame}) command shows that execution is stopped at line 6263@code{206}; yet when we use @code{until}, we get to line @code{195}: 6264 6265@smallexample 6266(@value{GDBP}) f 6267#0 main (argc=4, argv=0xf7fffae8) at m4.c:206 6268206 expand_input(); 6269(@value{GDBP}) until 6270195 for ( ; argc > 0; NEXTARG) @{ 6271@end smallexample 6272 6273This happened because, for execution efficiency, the compiler had 6274generated code for the loop closure test at the end, rather than the 6275start, of the loop---even though the test in a C @code{for}-loop is 6276written before the body of the loop. The @code{until} command appeared 6277to step back to the beginning of the loop when it advanced to this 6278expression; however, it has not really gone to an earlier 6279statement---not in terms of the actual machine code. 6280 6281@code{until} with no argument works by means of single 6282instruction stepping, and hence is slower than @code{until} with an 6283argument. 6284 6285@item until @var{location} 6286@itemx u @var{location} 6287Continue running your program until either the specified @var{location} is 6288reached, or the current stack frame returns. The location is any of 6289the forms described in @ref{Specify Location}. 6290This form of the command uses temporary breakpoints, and 6291hence is quicker than @code{until} without an argument. The specified 6292location is actually reached only if it is in the current frame. This 6293implies that @code{until} can be used to skip over recursive function 6294invocations. For instance in the code below, if the current location is 6295line @code{96}, issuing @code{until 99} will execute the program up to 6296line @code{99} in the same invocation of factorial, i.e., after the inner 6297invocations have returned. 6298 6299@smallexample 630094 int factorial (int value) 630195 @{ 630296 if (value > 1) @{ 630397 value *= factorial (value - 1); 630498 @} 630599 return (value); 6306100 @} 6307@end smallexample 6308 6309 6310@kindex advance @var{location} 6311@item advance @var{location} 6312Continue running the program up to the given @var{location}. An argument is 6313required, which should be of one of the forms described in 6314@ref{Specify Location}. 6315Execution will also stop upon exit from the current stack 6316frame. This command is similar to @code{until}, but @code{advance} will 6317not skip over recursive function calls, and the target location doesn't 6318have to be in the same frame as the current one. 6319 6320 6321@kindex stepi 6322@kindex si @r{(@code{stepi})} 6323@item stepi 6324@itemx stepi @var{arg} 6325@itemx si 6326Execute one machine instruction, then stop and return to the debugger. 6327 6328It is often useful to do @samp{display/i $pc} when stepping by machine 6329instructions. This makes @value{GDBN} automatically display the next 6330instruction to be executed, each time your program stops. @xref{Auto 6331Display,, Automatic Display}. 6332 6333An argument is a repeat count, as in @code{step}. 6334 6335@need 750 6336@kindex nexti 6337@kindex ni @r{(@code{nexti})} 6338@item nexti 6339@itemx nexti @var{arg} 6340@itemx ni 6341Execute one machine instruction, but if it is a function call, 6342proceed until the function returns. 6343 6344An argument is a repeat count, as in @code{next}. 6345 6346@end table 6347 6348@anchor{range stepping} 6349@cindex range stepping 6350@cindex target-assisted range stepping 6351By default, and if available, @value{GDBN} makes use of 6352target-assisted @dfn{range stepping}. In other words, whenever you 6353use a stepping command (e.g., @code{step}, @code{next}), @value{GDBN} 6354tells the target to step the corresponding range of instruction 6355addresses instead of issuing multiple single-steps. This speeds up 6356line stepping, particularly for remote targets. Ideally, there should 6357be no reason you would want to turn range stepping off. However, it's 6358possible that a bug in the debug info, a bug in the remote stub (for 6359remote targets), or even a bug in @value{GDBN} could make line 6360stepping behave incorrectly when target-assisted range stepping is 6361enabled. You can use the following command to turn off range stepping 6362if necessary: 6363 6364@table @code 6365@kindex set range-stepping 6366@kindex show range-stepping 6367@item set range-stepping 6368@itemx show range-stepping 6369Control whether range stepping is enabled. 6370 6371If @code{on}, and the target supports it, @value{GDBN} tells the 6372target to step a range of addresses itself, instead of issuing 6373multiple single-steps. If @code{off}, @value{GDBN} always issues 6374single-steps, even if range stepping is supported by the target. The 6375default is @code{on}. 6376 6377@end table 6378 6379@node Skipping Over Functions and Files 6380@section Skipping Over Functions and Files 6381@cindex skipping over functions and files 6382 6383The program you are debugging may contain some functions which are 6384uninteresting to debug. The @code{skip} command lets you tell @value{GDBN} to 6385skip a function, all functions in a file or a particular function in 6386a particular file when stepping. 6387 6388For example, consider the following C function: 6389 6390@smallexample 6391101 int func() 6392102 @{ 6393103 foo(boring()); 6394104 bar(boring()); 6395105 @} 6396@end smallexample 6397 6398@noindent 6399Suppose you wish to step into the functions @code{foo} and @code{bar}, but you 6400are not interested in stepping through @code{boring}. If you run @code{step} 6401at line 103, you'll enter @code{boring()}, but if you run @code{next}, you'll 6402step over both @code{foo} and @code{boring}! 6403 6404One solution is to @code{step} into @code{boring} and use the @code{finish} 6405command to immediately exit it. But this can become tedious if @code{boring} 6406is called from many places. 6407 6408A more flexible solution is to execute @kbd{skip boring}. This instructs 6409@value{GDBN} never to step into @code{boring}. Now when you execute 6410@code{step} at line 103, you'll step over @code{boring} and directly into 6411@code{foo}. 6412 6413Functions may be skipped by providing either a function name, linespec 6414(@pxref{Specify Location}), regular expression that matches the function's 6415name, file name or a @code{glob}-style pattern that matches the file name. 6416 6417On Posix systems the form of the regular expression is 6418``Extended Regular Expressions''. See for example @samp{man 7 regex} 6419on @sc{gnu}/Linux systems. On non-Posix systems the form of the regular 6420expression is whatever is provided by the @code{regcomp} function of 6421the underlying system. 6422See for example @samp{man 7 glob} on @sc{gnu}/Linux systems for a 6423description of @code{glob}-style patterns. 6424 6425@table @code 6426@kindex skip 6427@item skip @r{[}@var{options}@r{]} 6428The basic form of the @code{skip} command takes zero or more options 6429that specify what to skip. 6430The @var{options} argument is any useful combination of the following: 6431 6432@table @code 6433@item -file @var{file} 6434@itemx -fi @var{file} 6435Functions in @var{file} will be skipped over when stepping. 6436 6437@item -gfile @var{file-glob-pattern} 6438@itemx -gfi @var{file-glob-pattern} 6439@cindex skipping over files via glob-style patterns 6440Functions in files matching @var{file-glob-pattern} will be skipped 6441over when stepping. 6442 6443@smallexample 6444(gdb) skip -gfi utils/*.c 6445@end smallexample 6446 6447@item -function @var{linespec} 6448@itemx -fu @var{linespec} 6449Functions named by @var{linespec} or the function containing the line 6450named by @var{linespec} will be skipped over when stepping. 6451@xref{Specify Location}. 6452 6453@item -rfunction @var{regexp} 6454@itemx -rfu @var{regexp} 6455@cindex skipping over functions via regular expressions 6456Functions whose name matches @var{regexp} will be skipped over when stepping. 6457 6458This form is useful for complex function names. 6459For example, there is generally no need to step into C@t{++} @code{std::string} 6460constructors or destructors. Plus with C@t{++} templates it can be hard to 6461write out the full name of the function, and often it doesn't matter what 6462the template arguments are. Specifying the function to be skipped as a 6463regular expression makes this easier. 6464 6465@smallexample 6466(gdb) skip -rfu ^std::(allocator|basic_string)<.*>::~?\1 *\( 6467@end smallexample 6468 6469If you want to skip every templated C@t{++} constructor and destructor 6470in the @code{std} namespace you can do: 6471 6472@smallexample 6473(gdb) skip -rfu ^std::([a-zA-z0-9_]+)<.*>::~?\1 *\( 6474@end smallexample 6475@end table 6476 6477If no options are specified, the function you're currently debugging 6478will be skipped. 6479 6480@kindex skip function 6481@item skip function @r{[}@var{linespec}@r{]} 6482After running this command, the function named by @var{linespec} or the 6483function containing the line named by @var{linespec} will be skipped over when 6484stepping. @xref{Specify Location}. 6485 6486If you do not specify @var{linespec}, the function you're currently debugging 6487will be skipped. 6488 6489(If you have a function called @code{file} that you want to skip, use 6490@kbd{skip function file}.) 6491 6492@kindex skip file 6493@item skip file @r{[}@var{filename}@r{]} 6494After running this command, any function whose source lives in @var{filename} 6495will be skipped over when stepping. 6496 6497@smallexample 6498(gdb) skip file boring.c 6499File boring.c will be skipped when stepping. 6500@end smallexample 6501 6502If you do not specify @var{filename}, functions whose source lives in the file 6503you're currently debugging will be skipped. 6504@end table 6505 6506Skips can be listed, deleted, disabled, and enabled, much like breakpoints. 6507These are the commands for managing your list of skips: 6508 6509@table @code 6510@kindex info skip 6511@item info skip @r{[}@var{range}@r{]} 6512Print details about the specified skip(s). If @var{range} is not specified, 6513print a table with details about all functions and files marked for skipping. 6514@code{info skip} prints the following information about each skip: 6515 6516@table @emph 6517@item Identifier 6518A number identifying this skip. 6519@item Enabled or Disabled 6520Enabled skips are marked with @samp{y}. 6521Disabled skips are marked with @samp{n}. 6522@item Glob 6523If the file name is a @samp{glob} pattern this is @samp{y}. 6524Otherwise it is @samp{n}. 6525@item File 6526The name or @samp{glob} pattern of the file to be skipped. 6527If no file is specified this is @samp{<none>}. 6528@item RE 6529If the function name is a @samp{regular expression} this is @samp{y}. 6530Otherwise it is @samp{n}. 6531@item Function 6532The name or regular expression of the function to skip. 6533If no function is specified this is @samp{<none>}. 6534@end table 6535 6536@kindex skip delete 6537@item skip delete @r{[}@var{range}@r{]} 6538Delete the specified skip(s). If @var{range} is not specified, delete all 6539skips. 6540 6541@kindex skip enable 6542@item skip enable @r{[}@var{range}@r{]} 6543Enable the specified skip(s). If @var{range} is not specified, enable all 6544skips. 6545 6546@kindex skip disable 6547@item skip disable @r{[}@var{range}@r{]} 6548Disable the specified skip(s). If @var{range} is not specified, disable all 6549skips. 6550 6551@kindex set debug skip 6552@item set debug skip @r{[}on|off@r{]} 6553Set whether to print the debug output about skipping files and functions. 6554 6555@kindex show debug skip 6556@item show debug skip 6557Show whether the debug output about skipping files and functions is printed. 6558 6559@end table 6560 6561@node Signals 6562@section Signals 6563@cindex signals 6564 6565A signal is an asynchronous event that can happen in a program. The 6566operating system defines the possible kinds of signals, and gives each 6567kind a name and a number. For example, in Unix @code{SIGINT} is the 6568signal a program gets when you type an interrupt character (often @kbd{Ctrl-c}); 6569@code{SIGSEGV} is the signal a program gets from referencing a place in 6570memory far away from all the areas in use; @code{SIGALRM} occurs when 6571the alarm clock timer goes off (which happens only if your program has 6572requested an alarm). 6573 6574@cindex fatal signals 6575Some signals, including @code{SIGALRM}, are a normal part of the 6576functioning of your program. Others, such as @code{SIGSEGV}, indicate 6577errors; these signals are @dfn{fatal} (they kill your program immediately) if the 6578program has not specified in advance some other way to handle the signal. 6579@code{SIGINT} does not indicate an error in your program, but it is normally 6580fatal so it can carry out the purpose of the interrupt: to kill the program. 6581 6582@value{GDBN} has the ability to detect any occurrence of a signal in your 6583program. You can tell @value{GDBN} in advance what to do for each kind of 6584signal. 6585 6586@cindex handling signals 6587Normally, @value{GDBN} is set up to let the non-erroneous signals like 6588@code{SIGALRM} be silently passed to your program 6589(so as not to interfere with their role in the program's functioning) 6590but to stop your program immediately whenever an error signal happens. 6591You can change these settings with the @code{handle} command. 6592 6593@table @code 6594@kindex info signals 6595@kindex info handle 6596@item info signals 6597@itemx info handle 6598Print a table of all the kinds of signals and how @value{GDBN} has been told to 6599handle each one. You can use this to see the signal numbers of all 6600the defined types of signals. 6601 6602@item info signals @var{sig} 6603Similar, but print information only about the specified signal number. 6604 6605@code{info handle} is an alias for @code{info signals}. 6606 6607@item catch signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]} 6608Set a catchpoint for the indicated signals. @xref{Set Catchpoints}, 6609for details about this command. 6610 6611@kindex handle 6612@item handle @var{signal} @r{[}@var{keywords}@dots{}@r{]} 6613Change the way @value{GDBN} handles signal @var{signal}. The @var{signal} 6614can be the number of a signal or its name (with or without the 6615@samp{SIG} at the beginning); a list of signal numbers of the form 6616@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the 6617known signals. Optional arguments @var{keywords}, described below, 6618say what change to make. 6619@end table 6620 6621@c @group 6622The keywords allowed by the @code{handle} command can be abbreviated. 6623Their full names are: 6624 6625@table @code 6626@item nostop 6627@value{GDBN} should not stop your program when this signal happens. It may 6628still print a message telling you that the signal has come in. 6629 6630@item stop 6631@value{GDBN} should stop your program when this signal happens. This implies 6632the @code{print} keyword as well. 6633 6634@item print 6635@value{GDBN} should print a message when this signal happens. 6636 6637@item noprint 6638@value{GDBN} should not mention the occurrence of the signal at all. This 6639implies the @code{nostop} keyword as well. 6640 6641@item pass 6642@itemx noignore 6643@value{GDBN} should allow your program to see this signal; your program 6644can handle the signal, or else it may terminate if the signal is fatal 6645and not handled. @code{pass} and @code{noignore} are synonyms. 6646 6647@item nopass 6648@itemx ignore 6649@value{GDBN} should not allow your program to see this signal. 6650@code{nopass} and @code{ignore} are synonyms. 6651@end table 6652@c @end group 6653 6654When a signal stops your program, the signal is not visible to the 6655program until you 6656continue. Your program sees the signal then, if @code{pass} is in 6657effect for the signal in question @emph{at that time}. In other words, 6658after @value{GDBN} reports a signal, you can use the @code{handle} 6659command with @code{pass} or @code{nopass} to control whether your 6660program sees that signal when you continue. 6661 6662The default is set to @code{nostop}, @code{noprint}, @code{pass} for 6663non-erroneous signals such as @code{SIGALRM}, @code{SIGWINCH} and 6664@code{SIGCHLD}, and to @code{stop}, @code{print}, @code{pass} for the 6665erroneous signals. 6666 6667You can also use the @code{signal} command to prevent your program from 6668seeing a signal, or cause it to see a signal it normally would not see, 6669or to give it any signal at any time. For example, if your program stopped 6670due to some sort of memory reference error, you might store correct 6671values into the erroneous variables and continue, hoping to see more 6672execution; but your program would probably terminate immediately as 6673a result of the fatal signal once it saw the signal. To prevent this, 6674you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your 6675Program a Signal}. 6676 6677@cindex stepping and signal handlers 6678@anchor{stepping and signal handlers} 6679 6680@value{GDBN} optimizes for stepping the mainline code. If a signal 6681that has @code{handle nostop} and @code{handle pass} set arrives while 6682a stepping command (e.g., @code{stepi}, @code{step}, @code{next}) is 6683in progress, @value{GDBN} lets the signal handler run and then resumes 6684stepping the mainline code once the signal handler returns. In other 6685words, @value{GDBN} steps over the signal handler. This prevents 6686signals that you've specified as not interesting (with @code{handle 6687nostop}) from changing the focus of debugging unexpectedly. Note that 6688the signal handler itself may still hit a breakpoint, stop for another 6689signal that has @code{handle stop} in effect, or for any other event 6690that normally results in stopping the stepping command sooner. Also 6691note that @value{GDBN} still informs you that the program received a 6692signal if @code{handle print} is set. 6693 6694@anchor{stepping into signal handlers} 6695 6696If you set @code{handle pass} for a signal, and your program sets up a 6697handler for it, then issuing a stepping command, such as @code{step} 6698or @code{stepi}, when your program is stopped due to the signal will 6699step @emph{into} the signal handler (if the target supports that). 6700 6701Likewise, if you use the @code{queue-signal} command to queue a signal 6702to be delivered to the current thread when execution of the thread 6703resumes (@pxref{Signaling, ,Giving your Program a Signal}), then a 6704stepping command will step into the signal handler. 6705 6706Here's an example, using @code{stepi} to step to the first instruction 6707of @code{SIGUSR1}'s handler: 6708 6709@smallexample 6710(@value{GDBP}) handle SIGUSR1 6711Signal Stop Print Pass to program Description 6712SIGUSR1 Yes Yes Yes User defined signal 1 6713(@value{GDBP}) c 6714Continuing. 6715 6716Program received signal SIGUSR1, User defined signal 1. 6717main () sigusr1.c:28 671828 p = 0; 6719(@value{GDBP}) si 6720sigusr1_handler () at sigusr1.c:9 67219 @{ 6722@end smallexample 6723 6724The same, but using @code{queue-signal} instead of waiting for the 6725program to receive the signal first: 6726 6727@smallexample 6728(@value{GDBP}) n 672928 p = 0; 6730(@value{GDBP}) queue-signal SIGUSR1 6731(@value{GDBP}) si 6732sigusr1_handler () at sigusr1.c:9 67339 @{ 6734(@value{GDBP}) 6735@end smallexample 6736 6737@cindex extra signal information 6738@anchor{extra signal information} 6739 6740On some targets, @value{GDBN} can inspect extra signal information 6741associated with the intercepted signal, before it is actually 6742delivered to the program being debugged. This information is exported 6743by the convenience variable @code{$_siginfo}, and consists of data 6744that is passed by the kernel to the signal handler at the time of the 6745receipt of a signal. The data type of the information itself is 6746target dependent. You can see the data type using the @code{ptype 6747$_siginfo} command. On Unix systems, it typically corresponds to the 6748standard @code{siginfo_t} type, as defined in the @file{signal.h} 6749system header. 6750 6751Here's an example, on a @sc{gnu}/Linux system, printing the stray 6752referenced address that raised a segmentation fault. 6753 6754@smallexample 6755@group 6756(@value{GDBP}) continue 6757Program received signal SIGSEGV, Segmentation fault. 67580x0000000000400766 in main () 675969 *(int *)p = 0; 6760(@value{GDBP}) ptype $_siginfo 6761type = struct @{ 6762 int si_signo; 6763 int si_errno; 6764 int si_code; 6765 union @{ 6766 int _pad[28]; 6767 struct @{...@} _kill; 6768 struct @{...@} _timer; 6769 struct @{...@} _rt; 6770 struct @{...@} _sigchld; 6771 struct @{...@} _sigfault; 6772 struct @{...@} _sigpoll; 6773 @} _sifields; 6774@} 6775(@value{GDBP}) ptype $_siginfo._sifields._sigfault 6776type = struct @{ 6777 void *si_addr; 6778@} 6779(@value{GDBP}) p $_siginfo._sifields._sigfault.si_addr 6780$1 = (void *) 0x7ffff7ff7000 6781@end group 6782@end smallexample 6783 6784Depending on target support, @code{$_siginfo} may also be writable. 6785 6786@cindex Intel MPX boundary violations 6787@cindex boundary violations, Intel MPX 6788On some targets, a @code{SIGSEGV} can be caused by a boundary 6789violation, i.e., accessing an address outside of the allowed range. 6790In those cases @value{GDBN} may displays additional information, 6791depending on how @value{GDBN} has been told to handle the signal. 6792With @code{handle stop SIGSEGV}, @value{GDBN} displays the violation 6793kind: "Upper" or "Lower", the memory address accessed and the 6794bounds, while with @code{handle nostop SIGSEGV} no additional 6795information is displayed. 6796 6797The usual output of a segfault is: 6798@smallexample 6799Program received signal SIGSEGV, Segmentation fault 68000x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68 680168 value = *(p + len); 6802@end smallexample 6803 6804While a bound violation is presented as: 6805@smallexample 6806Program received signal SIGSEGV, Segmentation fault 6807Upper bound violation while accessing address 0x7fffffffc3b3 6808Bounds: [lower = 0x7fffffffc390, upper = 0x7fffffffc3a3] 68090x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68 681068 value = *(p + len); 6811@end smallexample 6812 6813@node Thread Stops 6814@section Stopping and Starting Multi-thread Programs 6815 6816@cindex stopped threads 6817@cindex threads, stopped 6818 6819@cindex continuing threads 6820@cindex threads, continuing 6821 6822@value{GDBN} supports debugging programs with multiple threads 6823(@pxref{Threads,, Debugging Programs with Multiple Threads}). There 6824are two modes of controlling execution of your program within the 6825debugger. In the default mode, referred to as @dfn{all-stop mode}, 6826when any thread in your program stops (for example, at a breakpoint 6827or while being stepped), all other threads in the program are also stopped by 6828@value{GDBN}. On some targets, @value{GDBN} also supports 6829@dfn{non-stop mode}, in which other threads can continue to run freely while 6830you examine the stopped thread in the debugger. 6831 6832@menu 6833* All-Stop Mode:: All threads stop when GDB takes control 6834* Non-Stop Mode:: Other threads continue to execute 6835* Background Execution:: Running your program asynchronously 6836* Thread-Specific Breakpoints:: Controlling breakpoints 6837* Interrupted System Calls:: GDB may interfere with system calls 6838* Observer Mode:: GDB does not alter program behavior 6839@end menu 6840 6841@node All-Stop Mode 6842@subsection All-Stop Mode 6843 6844@cindex all-stop mode 6845 6846In all-stop mode, whenever your program stops under @value{GDBN} for any reason, 6847@emph{all} threads of execution stop, not just the current thread. This 6848allows you to examine the overall state of the program, including 6849switching between threads, without worrying that things may change 6850underfoot. 6851 6852Conversely, whenever you restart the program, @emph{all} threads start 6853executing. @emph{This is true even when single-stepping} with commands 6854like @code{step} or @code{next}. 6855 6856In particular, @value{GDBN} cannot single-step all threads in lockstep. 6857Since thread scheduling is up to your debugging target's operating 6858system (not controlled by @value{GDBN}), other threads may 6859execute more than one statement while the current thread completes a 6860single step. Moreover, in general other threads stop in the middle of a 6861statement, rather than at a clean statement boundary, when the program 6862stops. 6863 6864You might even find your program stopped in another thread after 6865continuing or even single-stepping. This happens whenever some other 6866thread runs into a breakpoint, a signal, or an exception before the 6867first thread completes whatever you requested. 6868 6869@cindex automatic thread selection 6870@cindex switching threads automatically 6871@cindex threads, automatic switching 6872Whenever @value{GDBN} stops your program, due to a breakpoint or a 6873signal, it automatically selects the thread where that breakpoint or 6874signal happened. @value{GDBN} alerts you to the context switch with a 6875message such as @samp{[Switching to Thread @var{n}]} to identify the 6876thread. 6877 6878On some OSes, you can modify @value{GDBN}'s default behavior by 6879locking the OS scheduler to allow only a single thread to run. 6880 6881@table @code 6882@item set scheduler-locking @var{mode} 6883@cindex scheduler locking mode 6884@cindex lock scheduler 6885Set the scheduler locking mode. It applies to normal execution, 6886record mode, and replay mode. If it is @code{off}, then there is no 6887locking and any thread may run at any time. If @code{on}, then only 6888the current thread may run when the inferior is resumed. The 6889@code{step} mode optimizes for single-stepping; it prevents other 6890threads from preempting the current thread while you are stepping, so 6891that the focus of debugging does not change unexpectedly. Other 6892threads never get a chance to run when you step, and they are 6893completely free to run when you use commands like @samp{continue}, 6894@samp{until}, or @samp{finish}. However, unless another thread hits a 6895breakpoint during its timeslice, @value{GDBN} does not change the 6896current thread away from the thread that you are debugging. The 6897@code{replay} mode behaves like @code{off} in record mode and like 6898@code{on} in replay mode. 6899 6900@item show scheduler-locking 6901Display the current scheduler locking mode. 6902@end table 6903 6904@cindex resume threads of multiple processes simultaneously 6905By default, when you issue one of the execution commands such as 6906@code{continue}, @code{next} or @code{step}, @value{GDBN} allows only 6907threads of the current inferior to run. For example, if @value{GDBN} 6908is attached to two inferiors, each with two threads, the 6909@code{continue} command resumes only the two threads of the current 6910inferior. This is useful, for example, when you debug a program that 6911forks and you want to hold the parent stopped (so that, for instance, 6912it doesn't run to exit), while you debug the child. In other 6913situations, you may not be interested in inspecting the current state 6914of any of the processes @value{GDBN} is attached to, and you may want 6915to resume them all until some breakpoint is hit. In the latter case, 6916you can instruct @value{GDBN} to allow all threads of all the 6917inferiors to run with the @w{@code{set schedule-multiple}} command. 6918 6919@table @code 6920@kindex set schedule-multiple 6921@item set schedule-multiple 6922Set the mode for allowing threads of multiple processes to be resumed 6923when an execution command is issued. When @code{on}, all threads of 6924all processes are allowed to run. When @code{off}, only the threads 6925of the current process are resumed. The default is @code{off}. The 6926@code{scheduler-locking} mode takes precedence when set to @code{on}, 6927or while you are stepping and set to @code{step}. 6928 6929@item show schedule-multiple 6930Display the current mode for resuming the execution of threads of 6931multiple processes. 6932@end table 6933 6934@node Non-Stop Mode 6935@subsection Non-Stop Mode 6936 6937@cindex non-stop mode 6938 6939@c This section is really only a place-holder, and needs to be expanded 6940@c with more details. 6941 6942For some multi-threaded targets, @value{GDBN} supports an optional 6943mode of operation in which you can examine stopped program threads in 6944the debugger while other threads continue to execute freely. This 6945minimizes intrusion when debugging live systems, such as programs 6946where some threads have real-time constraints or must continue to 6947respond to external events. This is referred to as @dfn{non-stop} mode. 6948 6949In non-stop mode, when a thread stops to report a debugging event, 6950@emph{only} that thread is stopped; @value{GDBN} does not stop other 6951threads as well, in contrast to the all-stop mode behavior. Additionally, 6952execution commands such as @code{continue} and @code{step} apply by default 6953only to the current thread in non-stop mode, rather than all threads as 6954in all-stop mode. This allows you to control threads explicitly in 6955ways that are not possible in all-stop mode --- for example, stepping 6956one thread while allowing others to run freely, stepping 6957one thread while holding all others stopped, or stepping several threads 6958independently and simultaneously. 6959 6960To enter non-stop mode, use this sequence of commands before you run 6961or attach to your program: 6962 6963@smallexample 6964# If using the CLI, pagination breaks non-stop. 6965set pagination off 6966 6967# Finally, turn it on! 6968set non-stop on 6969@end smallexample 6970 6971You can use these commands to manipulate the non-stop mode setting: 6972 6973@table @code 6974@kindex set non-stop 6975@item set non-stop on 6976Enable selection of non-stop mode. 6977@item set non-stop off 6978Disable selection of non-stop mode. 6979@kindex show non-stop 6980@item show non-stop 6981Show the current non-stop enablement setting. 6982@end table 6983 6984Note these commands only reflect whether non-stop mode is enabled, 6985not whether the currently-executing program is being run in non-stop mode. 6986In particular, the @code{set non-stop} preference is only consulted when 6987@value{GDBN} starts or connects to the target program, and it is generally 6988not possible to switch modes once debugging has started. Furthermore, 6989since not all targets support non-stop mode, even when you have enabled 6990non-stop mode, @value{GDBN} may still fall back to all-stop operation by 6991default. 6992 6993In non-stop mode, all execution commands apply only to the current thread 6994by default. That is, @code{continue} only continues one thread. 6995To continue all threads, issue @code{continue -a} or @code{c -a}. 6996 6997You can use @value{GDBN}'s background execution commands 6998(@pxref{Background Execution}) to run some threads in the background 6999while you continue to examine or step others from @value{GDBN}. 7000The MI execution commands (@pxref{GDB/MI Program Execution}) are 7001always executed asynchronously in non-stop mode. 7002 7003Suspending execution is done with the @code{interrupt} command when 7004running in the background, or @kbd{Ctrl-c} during foreground execution. 7005In all-stop mode, this stops the whole process; 7006but in non-stop mode the interrupt applies only to the current thread. 7007To stop the whole program, use @code{interrupt -a}. 7008 7009Other execution commands do not currently support the @code{-a} option. 7010 7011In non-stop mode, when a thread stops, @value{GDBN} doesn't automatically make 7012that thread current, as it does in all-stop mode. This is because the 7013thread stop notifications are asynchronous with respect to @value{GDBN}'s 7014command interpreter, and it would be confusing if @value{GDBN} unexpectedly 7015changed to a different thread just as you entered a command to operate on the 7016previously current thread. 7017 7018@node Background Execution 7019@subsection Background Execution 7020 7021@cindex foreground execution 7022@cindex background execution 7023@cindex asynchronous execution 7024@cindex execution, foreground, background and asynchronous 7025 7026@value{GDBN}'s execution commands have two variants: the normal 7027foreground (synchronous) behavior, and a background 7028(asynchronous) behavior. In foreground execution, @value{GDBN} waits for 7029the program to report that some thread has stopped before prompting for 7030another command. In background execution, @value{GDBN} immediately gives 7031a command prompt so that you can issue other commands while your program runs. 7032 7033If the target doesn't support async mode, @value{GDBN} issues an error 7034message if you attempt to use the background execution commands. 7035 7036@cindex @code{&}, background execution of commands 7037To specify background execution, add a @code{&} to the command. For example, 7038the background form of the @code{continue} command is @code{continue&}, or 7039just @code{c&}. The execution commands that accept background execution 7040are: 7041 7042@table @code 7043@kindex run& 7044@item run 7045@xref{Starting, , Starting your Program}. 7046 7047@item attach 7048@kindex attach& 7049@xref{Attach, , Debugging an Already-running Process}. 7050 7051@item step 7052@kindex step& 7053@xref{Continuing and Stepping, step}. 7054 7055@item stepi 7056@kindex stepi& 7057@xref{Continuing and Stepping, stepi}. 7058 7059@item next 7060@kindex next& 7061@xref{Continuing and Stepping, next}. 7062 7063@item nexti 7064@kindex nexti& 7065@xref{Continuing and Stepping, nexti}. 7066 7067@item continue 7068@kindex continue& 7069@xref{Continuing and Stepping, continue}. 7070 7071@item finish 7072@kindex finish& 7073@xref{Continuing and Stepping, finish}. 7074 7075@item until 7076@kindex until& 7077@xref{Continuing and Stepping, until}. 7078 7079@end table 7080 7081Background execution is especially useful in conjunction with non-stop 7082mode for debugging programs with multiple threads; see @ref{Non-Stop Mode}. 7083However, you can also use these commands in the normal all-stop mode with 7084the restriction that you cannot issue another execution command until the 7085previous one finishes. Examples of commands that are valid in all-stop 7086mode while the program is running include @code{help} and @code{info break}. 7087 7088You can interrupt your program while it is running in the background by 7089using the @code{interrupt} command. 7090 7091@table @code 7092@kindex interrupt 7093@item interrupt 7094@itemx interrupt -a 7095 7096Suspend execution of the running program. In all-stop mode, 7097@code{interrupt} stops the whole process, but in non-stop mode, it stops 7098only the current thread. To stop the whole program in non-stop mode, 7099use @code{interrupt -a}. 7100@end table 7101 7102@node Thread-Specific Breakpoints 7103@subsection Thread-Specific Breakpoints 7104 7105When your program has multiple threads (@pxref{Threads,, Debugging 7106Programs with Multiple Threads}), you can choose whether to set 7107breakpoints on all threads, or on a particular thread. 7108 7109@table @code 7110@cindex breakpoints and threads 7111@cindex thread breakpoints 7112@kindex break @dots{} thread @var{thread-id} 7113@item break @var{location} thread @var{thread-id} 7114@itemx break @var{location} thread @var{thread-id} if @dots{} 7115@var{location} specifies source lines; there are several ways of 7116writing them (@pxref{Specify Location}), but the effect is always to 7117specify some source line. 7118 7119Use the qualifier @samp{thread @var{thread-id}} with a breakpoint command 7120to specify that you only want @value{GDBN} to stop the program when a 7121particular thread reaches this breakpoint. The @var{thread-id} specifier 7122is one of the thread identifiers assigned by @value{GDBN}, shown 7123in the first column of the @samp{info threads} display. 7124 7125If you do not specify @samp{thread @var{thread-id}} when you set a 7126breakpoint, the breakpoint applies to @emph{all} threads of your 7127program. 7128 7129You can use the @code{thread} qualifier on conditional breakpoints as 7130well; in this case, place @samp{thread @var{thread-id}} before or 7131after the breakpoint condition, like this: 7132 7133@smallexample 7134(@value{GDBP}) break frik.c:13 thread 28 if bartab > lim 7135@end smallexample 7136 7137@end table 7138 7139Thread-specific breakpoints are automatically deleted when 7140@value{GDBN} detects the corresponding thread is no longer in the 7141thread list. For example: 7142 7143@smallexample 7144(@value{GDBP}) c 7145Thread-specific breakpoint 3 deleted - thread 28 no longer in the thread list. 7146@end smallexample 7147 7148There are several ways for a thread to disappear, such as a regular 7149thread exit, but also when you detach from the process with the 7150@code{detach} command (@pxref{Attach, ,Debugging an Already-running 7151Process}), or if @value{GDBN} loses the remote connection 7152(@pxref{Remote Debugging}), etc. Note that with some targets, 7153@value{GDBN} is only able to detect a thread has exited when the user 7154explictly asks for the thread list with the @code{info threads} 7155command. 7156 7157@node Interrupted System Calls 7158@subsection Interrupted System Calls 7159 7160@cindex thread breakpoints and system calls 7161@cindex system calls and thread breakpoints 7162@cindex premature return from system calls 7163There is an unfortunate side effect when using @value{GDBN} to debug 7164multi-threaded programs. If one thread stops for a 7165breakpoint, or for some other reason, and another thread is blocked in a 7166system call, then the system call may return prematurely. This is a 7167consequence of the interaction between multiple threads and the signals 7168that @value{GDBN} uses to implement breakpoints and other events that 7169stop execution. 7170 7171To handle this problem, your program should check the return value of 7172each system call and react appropriately. This is good programming 7173style anyways. 7174 7175For example, do not write code like this: 7176 7177@smallexample 7178 sleep (10); 7179@end smallexample 7180 7181The call to @code{sleep} will return early if a different thread stops 7182at a breakpoint or for some other reason. 7183 7184Instead, write this: 7185 7186@smallexample 7187 int unslept = 10; 7188 while (unslept > 0) 7189 unslept = sleep (unslept); 7190@end smallexample 7191 7192A system call is allowed to return early, so the system is still 7193conforming to its specification. But @value{GDBN} does cause your 7194multi-threaded program to behave differently than it would without 7195@value{GDBN}. 7196 7197Also, @value{GDBN} uses internal breakpoints in the thread library to 7198monitor certain events such as thread creation and thread destruction. 7199When such an event happens, a system call in another thread may return 7200prematurely, even though your program does not appear to stop. 7201 7202@node Observer Mode 7203@subsection Observer Mode 7204 7205If you want to build on non-stop mode and observe program behavior 7206without any chance of disruption by @value{GDBN}, you can set 7207variables to disable all of the debugger's attempts to modify state, 7208whether by writing memory, inserting breakpoints, etc. These operate 7209at a low level, intercepting operations from all commands. 7210 7211When all of these are set to @code{off}, then @value{GDBN} is said to 7212be @dfn{observer mode}. As a convenience, the variable 7213@code{observer} can be set to disable these, plus enable non-stop 7214mode. 7215 7216Note that @value{GDBN} will not prevent you from making nonsensical 7217combinations of these settings. For instance, if you have enabled 7218@code{may-insert-breakpoints} but disabled @code{may-write-memory}, 7219then breakpoints that work by writing trap instructions into the code 7220stream will still not be able to be placed. 7221 7222@table @code 7223 7224@kindex observer 7225@item set observer on 7226@itemx set observer off 7227When set to @code{on}, this disables all the permission variables 7228below (except for @code{insert-fast-tracepoints}), plus enables 7229non-stop debugging. Setting this to @code{off} switches back to 7230normal debugging, though remaining in non-stop mode. 7231 7232@item show observer 7233Show whether observer mode is on or off. 7234 7235@kindex may-write-registers 7236@item set may-write-registers on 7237@itemx set may-write-registers off 7238This controls whether @value{GDBN} will attempt to alter the values of 7239registers, such as with assignment expressions in @code{print}, or the 7240@code{jump} command. It defaults to @code{on}. 7241 7242@item show may-write-registers 7243Show the current permission to write registers. 7244 7245@kindex may-write-memory 7246@item set may-write-memory on 7247@itemx set may-write-memory off 7248This controls whether @value{GDBN} will attempt to alter the contents 7249of memory, such as with assignment expressions in @code{print}. It 7250defaults to @code{on}. 7251 7252@item show may-write-memory 7253Show the current permission to write memory. 7254 7255@kindex may-insert-breakpoints 7256@item set may-insert-breakpoints on 7257@itemx set may-insert-breakpoints off 7258This controls whether @value{GDBN} will attempt to insert breakpoints. 7259This affects all breakpoints, including internal breakpoints defined 7260by @value{GDBN}. It defaults to @code{on}. 7261 7262@item show may-insert-breakpoints 7263Show the current permission to insert breakpoints. 7264 7265@kindex may-insert-tracepoints 7266@item set may-insert-tracepoints on 7267@itemx set may-insert-tracepoints off 7268This controls whether @value{GDBN} will attempt to insert (regular) 7269tracepoints at the beginning of a tracing experiment. It affects only 7270non-fast tracepoints, fast tracepoints being under the control of 7271@code{may-insert-fast-tracepoints}. It defaults to @code{on}. 7272 7273@item show may-insert-tracepoints 7274Show the current permission to insert tracepoints. 7275 7276@kindex may-insert-fast-tracepoints 7277@item set may-insert-fast-tracepoints on 7278@itemx set may-insert-fast-tracepoints off 7279This controls whether @value{GDBN} will attempt to insert fast 7280tracepoints at the beginning of a tracing experiment. It affects only 7281fast tracepoints, regular (non-fast) tracepoints being under the 7282control of @code{may-insert-tracepoints}. It defaults to @code{on}. 7283 7284@item show may-insert-fast-tracepoints 7285Show the current permission to insert fast tracepoints. 7286 7287@kindex may-interrupt 7288@item set may-interrupt on 7289@itemx set may-interrupt off 7290This controls whether @value{GDBN} will attempt to interrupt or stop 7291program execution. When this variable is @code{off}, the 7292@code{interrupt} command will have no effect, nor will 7293@kbd{Ctrl-c}. It defaults to @code{on}. 7294 7295@item show may-interrupt 7296Show the current permission to interrupt or stop the program. 7297 7298@end table 7299 7300@node Reverse Execution 7301@chapter Running programs backward 7302@cindex reverse execution 7303@cindex running programs backward 7304 7305When you are debugging a program, it is not unusual to realize that 7306you have gone too far, and some event of interest has already happened. 7307If the target environment supports it, @value{GDBN} can allow you to 7308``rewind'' the program by running it backward. 7309 7310A target environment that supports reverse execution should be able 7311to ``undo'' the changes in machine state that have taken place as the 7312program was executing normally. Variables, registers etc.@: should 7313revert to their previous values. Obviously this requires a great 7314deal of sophistication on the part of the target environment; not 7315all target environments can support reverse execution. 7316 7317When a program is executed in reverse, the instructions that 7318have most recently been executed are ``un-executed'', in reverse 7319order. The program counter runs backward, following the previous 7320thread of execution in reverse. As each instruction is ``un-executed'', 7321the values of memory and/or registers that were changed by that 7322instruction are reverted to their previous states. After executing 7323a piece of source code in reverse, all side effects of that code 7324should be ``undone'', and all variables should be returned to their 7325prior values@footnote{ 7326Note that some side effects are easier to undo than others. For instance, 7327memory and registers are relatively easy, but device I/O is hard. Some 7328targets may be able undo things like device I/O, and some may not. 7329 7330The contract between @value{GDBN} and the reverse executing target 7331requires only that the target do something reasonable when 7332@value{GDBN} tells it to execute backwards, and then report the 7333results back to @value{GDBN}. Whatever the target reports back to 7334@value{GDBN}, @value{GDBN} will report back to the user. @value{GDBN} 7335assumes that the memory and registers that the target reports are in a 7336consistent state, but @value{GDBN} accepts whatever it is given. 7337}. 7338 7339On some platforms, @value{GDBN} has built-in support for reverse 7340execution, activated with the @code{record} or @code{record btrace} 7341commands. @xref{Process Record and Replay}. Some remote targets, 7342typically full system emulators, support reverse execution directly 7343without requiring any special command. 7344 7345If you are debugging in a target environment that supports 7346reverse execution, @value{GDBN} provides the following commands. 7347 7348@table @code 7349@kindex reverse-continue 7350@kindex rc @r{(@code{reverse-continue})} 7351@item reverse-continue @r{[}@var{ignore-count}@r{]} 7352@itemx rc @r{[}@var{ignore-count}@r{]} 7353Beginning at the point where your program last stopped, start executing 7354in reverse. Reverse execution will stop for breakpoints and synchronous 7355exceptions (signals), just like normal execution. Behavior of 7356asynchronous signals depends on the target environment. 7357 7358@kindex reverse-step 7359@kindex rs @r{(@code{step})} 7360@item reverse-step @r{[}@var{count}@r{]} 7361Run the program backward until control reaches the start of a 7362different source line; then stop it, and return control to @value{GDBN}. 7363 7364Like the @code{step} command, @code{reverse-step} will only stop 7365at the beginning of a source line. It ``un-executes'' the previously 7366executed source line. If the previous source line included calls to 7367debuggable functions, @code{reverse-step} will step (backward) into 7368the called function, stopping at the beginning of the @emph{last} 7369statement in the called function (typically a return statement). 7370 7371Also, as with the @code{step} command, if non-debuggable functions are 7372called, @code{reverse-step} will run thru them backward without stopping. 7373 7374@kindex reverse-stepi 7375@kindex rsi @r{(@code{reverse-stepi})} 7376@item reverse-stepi @r{[}@var{count}@r{]} 7377Reverse-execute one machine instruction. Note that the instruction 7378to be reverse-executed is @emph{not} the one pointed to by the program 7379counter, but the instruction executed prior to that one. For instance, 7380if the last instruction was a jump, @code{reverse-stepi} will take you 7381back from the destination of the jump to the jump instruction itself. 7382 7383@kindex reverse-next 7384@kindex rn @r{(@code{reverse-next})} 7385@item reverse-next @r{[}@var{count}@r{]} 7386Run backward to the beginning of the previous line executed in 7387the current (innermost) stack frame. If the line contains function 7388calls, they will be ``un-executed'' without stopping. Starting from 7389the first line of a function, @code{reverse-next} will take you back 7390to the caller of that function, @emph{before} the function was called, 7391just as the normal @code{next} command would take you from the last 7392line of a function back to its return to its caller 7393@footnote{Unless the code is too heavily optimized.}. 7394 7395@kindex reverse-nexti 7396@kindex rni @r{(@code{reverse-nexti})} 7397@item reverse-nexti @r{[}@var{count}@r{]} 7398Like @code{nexti}, @code{reverse-nexti} executes a single instruction 7399in reverse, except that called functions are ``un-executed'' atomically. 7400That is, if the previously executed instruction was a return from 7401another function, @code{reverse-nexti} will continue to execute 7402in reverse until the call to that function (from the current stack 7403frame) is reached. 7404 7405@kindex reverse-finish 7406@item reverse-finish 7407Just as the @code{finish} command takes you to the point where the 7408current function returns, @code{reverse-finish} takes you to the point 7409where it was called. Instead of ending up at the end of the current 7410function invocation, you end up at the beginning. 7411 7412@kindex set exec-direction 7413@item set exec-direction 7414Set the direction of target execution. 7415@item set exec-direction reverse 7416@cindex execute forward or backward in time 7417@value{GDBN} will perform all execution commands in reverse, until the 7418exec-direction mode is changed to ``forward''. Affected commands include 7419@code{step, stepi, next, nexti, continue, and finish}. The @code{return} 7420command cannot be used in reverse mode. 7421@item set exec-direction forward 7422@value{GDBN} will perform all execution commands in the normal fashion. 7423This is the default. 7424@end table 7425 7426 7427@node Process Record and Replay 7428@chapter Recording Inferior's Execution and Replaying It 7429@cindex process record and replay 7430@cindex recording inferior's execution and replaying it 7431 7432On some platforms, @value{GDBN} provides a special @dfn{process record 7433and replay} target that can record a log of the process execution, and 7434replay it later with both forward and reverse execution commands. 7435 7436@cindex replay mode 7437When this target is in use, if the execution log includes the record 7438for the next instruction, @value{GDBN} will debug in @dfn{replay 7439mode}. In the replay mode, the inferior does not really execute code 7440instructions. Instead, all the events that normally happen during 7441code execution are taken from the execution log. While code is not 7442really executed in replay mode, the values of registers (including the 7443program counter register) and the memory of the inferior are still 7444changed as they normally would. Their contents are taken from the 7445execution log. 7446 7447@cindex record mode 7448If the record for the next instruction is not in the execution log, 7449@value{GDBN} will debug in @dfn{record mode}. In this mode, the 7450inferior executes normally, and @value{GDBN} records the execution log 7451for future replay. 7452 7453The process record and replay target supports reverse execution 7454(@pxref{Reverse Execution}), even if the platform on which the 7455inferior runs does not. However, the reverse execution is limited in 7456this case by the range of the instructions recorded in the execution 7457log. In other words, reverse execution on platforms that don't 7458support it directly can only be done in the replay mode. 7459 7460When debugging in the reverse direction, @value{GDBN} will work in 7461replay mode as long as the execution log includes the record for the 7462previous instruction; otherwise, it will work in record mode, if the 7463platform supports reverse execution, or stop if not. 7464 7465Currently, process record and replay is supported on ARM, Aarch64, 7466Moxie, PowerPC, PowerPC64, S/390, and x86 (i386/amd64) running 7467GNU/Linux. Process record and replay can be used both when native 7468debugging, and when remote debugging via @code{gdbserver}. 7469 7470For architecture environments that support process record and replay, 7471@value{GDBN} provides the following commands: 7472 7473@table @code 7474@kindex target record 7475@kindex target record-full 7476@kindex target record-btrace 7477@kindex record 7478@kindex record full 7479@kindex record btrace 7480@kindex record btrace bts 7481@kindex record btrace pt 7482@kindex record bts 7483@kindex record pt 7484@kindex rec 7485@kindex rec full 7486@kindex rec btrace 7487@kindex rec btrace bts 7488@kindex rec btrace pt 7489@kindex rec bts 7490@kindex rec pt 7491@item record @var{method} 7492This command starts the process record and replay target. The 7493recording method can be specified as parameter. Without a parameter 7494the command uses the @code{full} recording method. The following 7495recording methods are available: 7496 7497@table @code 7498@item full 7499Full record/replay recording using @value{GDBN}'s software record and 7500replay implementation. This method allows replaying and reverse 7501execution. 7502 7503@item btrace @var{format} 7504Hardware-supported instruction recording, supported on Intel 7505processors. This method does not record data. Further, the data is 7506collected in a ring buffer so old data will be overwritten when the 7507buffer is full. It allows limited reverse execution. Variables and 7508registers are not available during reverse execution. In remote 7509debugging, recording continues on disconnect. Recorded data can be 7510inspected after reconnecting. The recording may be stopped using 7511@code{record stop}. 7512 7513The recording format can be specified as parameter. Without a parameter 7514the command chooses the recording format. The following recording 7515formats are available: 7516 7517@table @code 7518@item bts 7519@cindex branch trace store 7520Use the @dfn{Branch Trace Store} (@acronym{BTS}) recording format. In 7521this format, the processor stores a from/to record for each executed 7522branch in the btrace ring buffer. 7523 7524@item pt 7525@cindex Intel Processor Trace 7526Use the @dfn{Intel Processor Trace} recording format. In this 7527format, the processor stores the execution trace in a compressed form 7528that is afterwards decoded by @value{GDBN}. 7529 7530The trace can be recorded with very low overhead. The compressed 7531trace format also allows small trace buffers to already contain a big 7532number of instructions compared to @acronym{BTS}. 7533 7534Decoding the recorded execution trace, on the other hand, is more 7535expensive than decoding @acronym{BTS} trace. This is mostly due to the 7536increased number of instructions to process. You should increase the 7537buffer-size with care. 7538@end table 7539 7540Not all recording formats may be available on all processors. 7541@end table 7542 7543The process record and replay target can only debug a process that is 7544already running. Therefore, you need first to start the process with 7545the @kbd{run} or @kbd{start} commands, and then start the recording 7546with the @kbd{record @var{method}} command. 7547 7548@cindex displaced stepping, and process record and replay 7549Displaced stepping (@pxref{Maintenance Commands,, displaced stepping}) 7550will be automatically disabled when process record and replay target 7551is started. That's because the process record and replay target 7552doesn't support displaced stepping. 7553 7554@cindex non-stop mode, and process record and replay 7555@cindex asynchronous execution, and process record and replay 7556If the inferior is in the non-stop mode (@pxref{Non-Stop Mode}) or in 7557the asynchronous execution mode (@pxref{Background Execution}), not 7558all recording methods are available. The @code{full} recording method 7559does not support these two modes. 7560 7561@kindex record stop 7562@kindex rec s 7563@item record stop 7564Stop the process record and replay target. When process record and 7565replay target stops, the entire execution log will be deleted and the 7566inferior will either be terminated, or will remain in its final state. 7567 7568When you stop the process record and replay target in record mode (at 7569the end of the execution log), the inferior will be stopped at the 7570next instruction that would have been recorded. In other words, if 7571you record for a while and then stop recording, the inferior process 7572will be left in the same state as if the recording never happened. 7573 7574On the other hand, if the process record and replay target is stopped 7575while in replay mode (that is, not at the end of the execution log, 7576but at some earlier point), the inferior process will become ``live'' 7577at that earlier state, and it will then be possible to continue the 7578usual ``live'' debugging of the process from that state. 7579 7580When the inferior process exits, or @value{GDBN} detaches from it, 7581process record and replay target will automatically stop itself. 7582 7583@kindex record goto 7584@item record goto 7585Go to a specific location in the execution log. There are several 7586ways to specify the location to go to: 7587 7588@table @code 7589@item record goto begin 7590@itemx record goto start 7591Go to the beginning of the execution log. 7592 7593@item record goto end 7594Go to the end of the execution log. 7595 7596@item record goto @var{n} 7597Go to instruction number @var{n} in the execution log. 7598@end table 7599 7600@kindex record save 7601@item record save @var{filename} 7602Save the execution log to a file @file{@var{filename}}. 7603Default filename is @file{gdb_record.@var{process_id}}, where 7604@var{process_id} is the process ID of the inferior. 7605 7606This command may not be available for all recording methods. 7607 7608@kindex record restore 7609@item record restore @var{filename} 7610Restore the execution log from a file @file{@var{filename}}. 7611File must have been created with @code{record save}. 7612 7613@kindex set record full 7614@item set record full insn-number-max @var{limit} 7615@itemx set record full insn-number-max unlimited 7616Set the limit of instructions to be recorded for the @code{full} 7617recording method. Default value is 200000. 7618 7619If @var{limit} is a positive number, then @value{GDBN} will start 7620deleting instructions from the log once the number of the record 7621instructions becomes greater than @var{limit}. For every new recorded 7622instruction, @value{GDBN} will delete the earliest recorded 7623instruction to keep the number of recorded instructions at the limit. 7624(Since deleting recorded instructions loses information, @value{GDBN} 7625lets you control what happens when the limit is reached, by means of 7626the @code{stop-at-limit} option, described below.) 7627 7628If @var{limit} is @code{unlimited} or zero, @value{GDBN} will never 7629delete recorded instructions from the execution log. The number of 7630recorded instructions is limited only by the available memory. 7631 7632@kindex show record full 7633@item show record full insn-number-max 7634Show the limit of instructions to be recorded with the @code{full} 7635recording method. 7636 7637@item set record full stop-at-limit 7638Control the behavior of the @code{full} recording method when the 7639number of recorded instructions reaches the limit. If ON (the 7640default), @value{GDBN} will stop when the limit is reached for the 7641first time and ask you whether you want to stop the inferior or 7642continue running it and recording the execution log. If you decide 7643to continue recording, each new recorded instruction will cause the 7644oldest one to be deleted. 7645 7646If this option is OFF, @value{GDBN} will automatically delete the 7647oldest record to make room for each new one, without asking. 7648 7649@item show record full stop-at-limit 7650Show the current setting of @code{stop-at-limit}. 7651 7652@item set record full memory-query 7653Control the behavior when @value{GDBN} is unable to record memory 7654changes caused by an instruction for the @code{full} recording method. 7655If ON, @value{GDBN} will query whether to stop the inferior in that 7656case. 7657 7658If this option is OFF (the default), @value{GDBN} will automatically 7659ignore the effect of such instructions on memory. Later, when 7660@value{GDBN} replays this execution log, it will mark the log of this 7661instruction as not accessible, and it will not affect the replay 7662results. 7663 7664@item show record full memory-query 7665Show the current setting of @code{memory-query}. 7666 7667@kindex set record btrace 7668The @code{btrace} record target does not trace data. As a 7669convenience, when replaying, @value{GDBN} reads read-only memory off 7670the live program directly, assuming that the addresses of the 7671read-only areas don't change. This for example makes it possible to 7672disassemble code while replaying, but not to print variables. 7673In some cases, being able to inspect variables might be useful. 7674You can use the following command for that: 7675 7676@item set record btrace replay-memory-access 7677Control the behavior of the @code{btrace} recording method when 7678accessing memory during replay. If @code{read-only} (the default), 7679@value{GDBN} will only allow accesses to read-only memory. 7680If @code{read-write}, @value{GDBN} will allow accesses to read-only 7681and to read-write memory. Beware that the accessed memory corresponds 7682to the live target and not necessarily to the current replay 7683position. 7684 7685@item set record btrace cpu @var{identifier} 7686Set the processor to be used for enabling workarounds for processor 7687errata when decoding the trace. 7688 7689Processor errata are defects in processor operation, caused by its 7690design or manufacture. They can cause a trace not to match the 7691specification. This, in turn, may cause trace decode to fail. 7692@value{GDBN} can detect erroneous trace packets and correct them, thus 7693avoiding the decoding failures. These corrections are known as 7694@dfn{errata workarounds}, and are enabled based on the processor on 7695which the trace was recorded. 7696 7697By default, @value{GDBN} attempts to detect the processor 7698automatically, and apply the necessary workarounds for it. However, 7699you may need to specify the processor if @value{GDBN} does not yet 7700support it. This command allows you to do that, and also allows to 7701disable the workarounds. 7702 7703The argument @var{identifier} identifies the @sc{cpu} and is of the 7704form: @code{@var{vendor}:@var{processor identifier}}. In addition, 7705there are two special identifiers, @code{none} and @code{auto} 7706(default). 7707 7708The following vendor identifiers and corresponding processor 7709identifiers are currently supported: 7710 7711@multitable @columnfractions .1 .9 7712 7713@item @code{intel} 7714@tab @var{family}/@var{model}[/@var{stepping}] 7715 7716@end multitable 7717 7718On GNU/Linux systems, the processor @var{family}, @var{model}, and 7719@var{stepping} can be obtained from @code{/proc/cpuinfo}. 7720 7721If @var{identifier} is @code{auto}, enable errata workarounds for the 7722processor on which the trace was recorded. If @var{identifier} is 7723@code{none}, errata workarounds are disabled. 7724 7725For example, when using an old @value{GDBN} on a new system, decode 7726may fail because @value{GDBN} does not support the new processor. It 7727often suffices to specify an older processor that @value{GDBN} 7728supports. 7729 7730@smallexample 7731(gdb) info record 7732Active record target: record-btrace 7733Recording format: Intel Processor Trace. 7734Buffer size: 16kB. 7735Failed to configure the Intel Processor Trace decoder: unknown cpu. 7736(gdb) set record btrace cpu intel:6/158 7737(gdb) info record 7738Active record target: record-btrace 7739Recording format: Intel Processor Trace. 7740Buffer size: 16kB. 7741Recorded 84872 instructions in 3189 functions (0 gaps) for thread 1 (...). 7742@end smallexample 7743 7744@kindex show record btrace 7745@item show record btrace replay-memory-access 7746Show the current setting of @code{replay-memory-access}. 7747 7748@item show record btrace cpu 7749Show the processor to be used for enabling trace decode errata 7750workarounds. 7751 7752@kindex set record btrace bts 7753@item set record btrace bts buffer-size @var{size} 7754@itemx set record btrace bts buffer-size unlimited 7755Set the requested ring buffer size for branch tracing in @acronym{BTS} 7756format. Default is 64KB. 7757 7758If @var{size} is a positive number, then @value{GDBN} will try to 7759allocate a buffer of at least @var{size} bytes for each new thread 7760that uses the btrace recording method and the @acronym{BTS} format. 7761The actually obtained buffer size may differ from the requested 7762@var{size}. Use the @code{info record} command to see the actual 7763buffer size for each thread that uses the btrace recording method and 7764the @acronym{BTS} format. 7765 7766If @var{limit} is @code{unlimited} or zero, @value{GDBN} will try to 7767allocate a buffer of 4MB. 7768 7769Bigger buffers mean longer traces. On the other hand, @value{GDBN} will 7770also need longer to process the branch trace data before it can be used. 7771 7772@item show record btrace bts buffer-size @var{size} 7773Show the current setting of the requested ring buffer size for branch 7774tracing in @acronym{BTS} format. 7775 7776@kindex set record btrace pt 7777@item set record btrace pt buffer-size @var{size} 7778@itemx set record btrace pt buffer-size unlimited 7779Set the requested ring buffer size for branch tracing in Intel 7780Processor Trace format. Default is 16KB. 7781 7782If @var{size} is a positive number, then @value{GDBN} will try to 7783allocate a buffer of at least @var{size} bytes for each new thread 7784that uses the btrace recording method and the Intel Processor Trace 7785format. The actually obtained buffer size may differ from the 7786requested @var{size}. Use the @code{info record} command to see the 7787actual buffer size for each thread. 7788 7789If @var{limit} is @code{unlimited} or zero, @value{GDBN} will try to 7790allocate a buffer of 4MB. 7791 7792Bigger buffers mean longer traces. On the other hand, @value{GDBN} will 7793also need longer to process the branch trace data before it can be used. 7794 7795@item show record btrace pt buffer-size @var{size} 7796Show the current setting of the requested ring buffer size for branch 7797tracing in Intel Processor Trace format. 7798 7799@kindex info record 7800@item info record 7801Show various statistics about the recording depending on the recording 7802method: 7803 7804@table @code 7805@item full 7806For the @code{full} recording method, it shows the state of process 7807record and its in-memory execution log buffer, including: 7808 7809@itemize @bullet 7810@item 7811Whether in record mode or replay mode. 7812@item 7813Lowest recorded instruction number (counting from when the current execution log started recording instructions). 7814@item 7815Highest recorded instruction number. 7816@item 7817Current instruction about to be replayed (if in replay mode). 7818@item 7819Number of instructions contained in the execution log. 7820@item 7821Maximum number of instructions that may be contained in the execution log. 7822@end itemize 7823 7824@item btrace 7825For the @code{btrace} recording method, it shows: 7826 7827@itemize @bullet 7828@item 7829Recording format. 7830@item 7831Number of instructions that have been recorded. 7832@item 7833Number of blocks of sequential control-flow formed by the recorded 7834instructions. 7835@item 7836Whether in record mode or replay mode. 7837@end itemize 7838 7839For the @code{bts} recording format, it also shows: 7840@itemize @bullet 7841@item 7842Size of the perf ring buffer. 7843@end itemize 7844 7845For the @code{pt} recording format, it also shows: 7846@itemize @bullet 7847@item 7848Size of the perf ring buffer. 7849@end itemize 7850@end table 7851 7852@kindex record delete 7853@kindex rec del 7854@item record delete 7855When record target runs in replay mode (``in the past''), delete the 7856subsequent execution log and begin to record a new execution log starting 7857from the current address. This means you will abandon the previously 7858recorded ``future'' and begin recording a new ``future''. 7859 7860@kindex record instruction-history 7861@kindex rec instruction-history 7862@item record instruction-history 7863Disassembles instructions from the recorded execution log. By 7864default, ten instructions are disassembled. This can be changed using 7865the @code{set record instruction-history-size} command. Instructions 7866are printed in execution order. 7867 7868It can also print mixed source+disassembly if you specify the the 7869@code{/m} or @code{/s} modifier, and print the raw instructions in hex 7870as well as in symbolic form by specifying the @code{/r} modifier. 7871 7872The current position marker is printed for the instruction at the 7873current program counter value. This instruction can appear multiple 7874times in the trace and the current position marker will be printed 7875every time. To omit the current position marker, specify the 7876@code{/p} modifier. 7877 7878To better align the printed instructions when the trace contains 7879instructions from more than one function, the function name may be 7880omitted by specifying the @code{/f} modifier. 7881 7882Speculatively executed instructions are prefixed with @samp{?}. This 7883feature is not available for all recording formats. 7884 7885There are several ways to specify what part of the execution log to 7886disassemble: 7887 7888@table @code 7889@item record instruction-history @var{insn} 7890Disassembles ten instructions starting from instruction number 7891@var{insn}. 7892 7893@item record instruction-history @var{insn}, +/-@var{n} 7894Disassembles @var{n} instructions around instruction number 7895@var{insn}. If @var{n} is preceded with @code{+}, disassembles 7896@var{n} instructions after instruction number @var{insn}. If 7897@var{n} is preceded with @code{-}, disassembles @var{n} 7898instructions before instruction number @var{insn}. 7899 7900@item record instruction-history 7901Disassembles ten more instructions after the last disassembly. 7902 7903@item record instruction-history - 7904Disassembles ten more instructions before the last disassembly. 7905 7906@item record instruction-history @var{begin}, @var{end} 7907Disassembles instructions beginning with instruction number 7908@var{begin} until instruction number @var{end}. The instruction 7909number @var{end} is included. 7910@end table 7911 7912This command may not be available for all recording methods. 7913 7914@kindex set record 7915@item set record instruction-history-size @var{size} 7916@itemx set record instruction-history-size unlimited 7917Define how many instructions to disassemble in the @code{record 7918instruction-history} command. The default value is 10. 7919A @var{size} of @code{unlimited} means unlimited instructions. 7920 7921@kindex show record 7922@item show record instruction-history-size 7923Show how many instructions to disassemble in the @code{record 7924instruction-history} command. 7925 7926@kindex record function-call-history 7927@kindex rec function-call-history 7928@item record function-call-history 7929Prints the execution history at function granularity. For each sequence 7930of instructions that belong to the same function, it prints the name of 7931that function, the source lines for this instruction sequence (if the 7932@code{/l} modifier is specified), and the instructions numbers that form 7933the sequence (if the @code{/i} modifier is specified). The function names 7934are indented to reflect the call stack depth if the @code{/c} modifier is 7935specified. The @code{/l}, @code{/i}, and @code{/c} modifiers can be given 7936together. 7937 7938@smallexample 7939(@value{GDBP}) @b{list 1, 10} 79401 void foo (void) 79412 @{ 79423 @} 79434 79445 void bar (void) 79456 @{ 79467 ... 79478 foo (); 79489 ... 794910 @} 7950(@value{GDBP}) @b{record function-call-history /ilc} 79511 bar inst 1,4 at foo.c:6,8 79522 foo inst 5,10 at foo.c:2,3 79533 bar inst 11,13 at foo.c:9,10 7954@end smallexample 7955 7956By default, ten functions are printed. This can be changed using the 7957@code{set record function-call-history-size} command. Functions are 7958printed in execution order. There are several ways to specify what 7959to print: 7960 7961@table @code 7962@item record function-call-history @var{func} 7963Prints ten functions starting from function number @var{func}. 7964 7965@item record function-call-history @var{func}, +/-@var{n} 7966Prints @var{n} functions around function number @var{func}. If 7967@var{n} is preceded with @code{+}, prints @var{n} functions after 7968function number @var{func}. If @var{n} is preceded with @code{-}, 7969prints @var{n} functions before function number @var{func}. 7970 7971@item record function-call-history 7972Prints ten more functions after the last ten-function print. 7973 7974@item record function-call-history - 7975Prints ten more functions before the last ten-function print. 7976 7977@item record function-call-history @var{begin}, @var{end} 7978Prints functions beginning with function number @var{begin} until 7979function number @var{end}. The function number @var{end} is included. 7980@end table 7981 7982This command may not be available for all recording methods. 7983 7984@item set record function-call-history-size @var{size} 7985@itemx set record function-call-history-size unlimited 7986Define how many functions to print in the 7987@code{record function-call-history} command. The default value is 10. 7988A size of @code{unlimited} means unlimited functions. 7989 7990@item show record function-call-history-size 7991Show how many functions to print in the 7992@code{record function-call-history} command. 7993@end table 7994 7995 7996@node Stack 7997@chapter Examining the Stack 7998 7999When your program has stopped, the first thing you need to know is where it 8000stopped and how it got there. 8001 8002@cindex call stack 8003Each time your program performs a function call, information about the call 8004is generated. 8005That information includes the location of the call in your program, 8006the arguments of the call, 8007and the local variables of the function being called. 8008The information is saved in a block of data called a @dfn{stack frame}. 8009The stack frames are allocated in a region of memory called the @dfn{call 8010stack}. 8011 8012When your program stops, the @value{GDBN} commands for examining the 8013stack allow you to see all of this information. 8014 8015@cindex selected frame 8016One of the stack frames is @dfn{selected} by @value{GDBN} and many 8017@value{GDBN} commands refer implicitly to the selected frame. In 8018particular, whenever you ask @value{GDBN} for the value of a variable in 8019your program, the value is found in the selected frame. There are 8020special @value{GDBN} commands to select whichever frame you are 8021interested in. @xref{Selection, ,Selecting a Frame}. 8022 8023When your program stops, @value{GDBN} automatically selects the 8024currently executing frame and describes it briefly, similar to the 8025@code{frame} command (@pxref{Frame Info, ,Information about a Frame}). 8026 8027@menu 8028* Frames:: Stack frames 8029* Backtrace:: Backtraces 8030* Selection:: Selecting a frame 8031* Frame Info:: Information on a frame 8032* Frame Apply:: Applying a command to several frames 8033* Frame Filter Management:: Managing frame filters 8034 8035@end menu 8036 8037@node Frames 8038@section Stack Frames 8039 8040@cindex frame, definition 8041@cindex stack frame 8042The call stack is divided up into contiguous pieces called @dfn{stack 8043frames}, or @dfn{frames} for short; each frame is the data associated 8044with one call to one function. The frame contains the arguments given 8045to the function, the function's local variables, and the address at 8046which the function is executing. 8047 8048@cindex initial frame 8049@cindex outermost frame 8050@cindex innermost frame 8051When your program is started, the stack has only one frame, that of the 8052function @code{main}. This is called the @dfn{initial} frame or the 8053@dfn{outermost} frame. Each time a function is called, a new frame is 8054made. Each time a function returns, the frame for that function invocation 8055is eliminated. If a function is recursive, there can be many frames for 8056the same function. The frame for the function in which execution is 8057actually occurring is called the @dfn{innermost} frame. This is the most 8058recently created of all the stack frames that still exist. 8059 8060@cindex frame pointer 8061Inside your program, stack frames are identified by their addresses. A 8062stack frame consists of many bytes, each of which has its own address; each 8063kind of computer has a convention for choosing one byte whose 8064address serves as the address of the frame. Usually this address is kept 8065in a register called the @dfn{frame pointer register} 8066(@pxref{Registers, $fp}) while execution is going on in that frame. 8067 8068@cindex frame level 8069@cindex frame number 8070@value{GDBN} labels each existing stack frame with a @dfn{level}, a 8071number that is zero for the innermost frame, one for the frame that 8072called it, and so on upward. These level numbers give you a way of 8073designating stack frames in @value{GDBN} commands. The terms 8074@dfn{frame number} and @dfn{frame level} can be used interchangeably to 8075describe this number. 8076 8077@c The -fomit-frame-pointer below perennially causes hbox overflow 8078@c underflow problems. 8079@cindex frameless execution 8080Some compilers provide a way to compile functions so that they operate 8081without stack frames. (For example, the @value{NGCC} option 8082@smallexample 8083@samp{-fomit-frame-pointer} 8084@end smallexample 8085generates functions without a frame.) 8086This is occasionally done with heavily used library functions to save 8087the frame setup time. @value{GDBN} has limited facilities for dealing 8088with these function invocations. If the innermost function invocation 8089has no stack frame, @value{GDBN} nevertheless regards it as though 8090it had a separate frame, which is numbered zero as usual, allowing 8091correct tracing of the function call chain. However, @value{GDBN} has 8092no provision for frameless functions elsewhere in the stack. 8093 8094@node Backtrace 8095@section Backtraces 8096 8097@cindex traceback 8098@cindex call stack traces 8099A backtrace is a summary of how your program got where it is. It shows one 8100line per frame, for many frames, starting with the currently executing 8101frame (frame zero), followed by its caller (frame one), and on up the 8102stack. 8103 8104@anchor{backtrace-command} 8105@kindex backtrace 8106@kindex bt @r{(@code{backtrace})} 8107To print a backtrace of the entire stack, use the @code{backtrace} 8108command, or its alias @code{bt}. This command will print one line per 8109frame for frames in the stack. By default, all stack frames are 8110printed. You can stop the backtrace at any time by typing the system 8111interrupt character, normally @kbd{Ctrl-c}. 8112 8113@table @code 8114@item backtrace [@var{option}]@dots{} [@var{qualifier}]@dots{} [@var{count}] 8115@itemx bt [@var{option}]@dots{} [@var{qualifier}]@dots{} [@var{count}] 8116Print the backtrace of the entire stack. 8117 8118The optional @var{count} can be one of the following: 8119 8120@table @code 8121@item @var{n} 8122@itemx @var{n} 8123Print only the innermost @var{n} frames, where @var{n} is a positive 8124number. 8125 8126@item -@var{n} 8127@itemx -@var{n} 8128Print only the outermost @var{n} frames, where @var{n} is a positive 8129number. 8130@end table 8131 8132Options: 8133 8134@table @code 8135@item -full 8136Print the values of the local variables also. This can be combined 8137with the optional @var{count} to limit the number of frames shown. 8138 8139@item -no-filters 8140Do not run Python frame filters on this backtrace. @xref{Frame 8141Filter API}, for more information. Additionally use @ref{disable 8142frame-filter all} to turn off all frame filters. This is only 8143relevant when @value{GDBN} has been configured with @code{Python} 8144support. 8145 8146@item -hide 8147A Python frame filter might decide to ``elide'' some frames. Normally 8148such elided frames are still printed, but they are indented relative 8149to the filtered frames that cause them to be elided. The @code{-hide} 8150option causes elided frames to not be printed at all. 8151@end table 8152 8153The @code{backtrace} command also supports a number of options that 8154allow overriding relevant global print settings as set by @code{set 8155backtrace} and @code{set print} subcommands: 8156 8157@table @code 8158@item -past-main [@code{on}|@code{off}] 8159Set whether backtraces should continue past @code{main}. Related setting: 8160@ref{set backtrace past-main}. 8161 8162@item -past-entry [@code{on}|@code{off}] 8163Set whether backtraces should continue past the entry point of a program. 8164Related setting: @ref{set backtrace past-entry}. 8165 8166@item -entry-values @code{no}|@code{only}|@code{preferred}|@code{if-needed}|@code{both}|@code{compact}|@code{default} 8167Set printing of function arguments at function entry. 8168Related setting: @ref{set print entry-values}. 8169 8170@item -frame-arguments @code{all}|@code{scalars}|@code{none} 8171Set printing of non-scalar frame arguments. 8172Related setting: @ref{set print frame-arguments}. 8173 8174@item -raw-frame-arguments [@code{on}|@code{off}] 8175Set whether to print frame arguments in raw form. 8176Related setting: @ref{set print raw-frame-arguments}. 8177 8178@item -frame-info @code{auto}|@code{source-line}|@code{location}|@code{source-and-location}|@code{location-and-address}|@code{short-location} 8179Set printing of frame information. 8180Related setting: @ref{set print frame-info}. 8181@end table 8182 8183The optional @var{qualifier} is maintained for backward compatibility. 8184It can be one of the following: 8185 8186@table @code 8187@item full 8188Equivalent to the @code{-full} option. 8189 8190@item no-filters 8191Equivalent to the @code{-no-filters} option. 8192 8193@item hide 8194Equivalent to the @code{-hide} option. 8195@end table 8196 8197@end table 8198 8199@kindex where 8200@kindex info stack 8201The names @code{where} and @code{info stack} (abbreviated @code{info s}) 8202are additional aliases for @code{backtrace}. 8203 8204@cindex multiple threads, backtrace 8205In a multi-threaded program, @value{GDBN} by default shows the 8206backtrace only for the current thread. To display the backtrace for 8207several or all of the threads, use the command @code{thread apply} 8208(@pxref{Threads, thread apply}). For example, if you type @kbd{thread 8209apply all backtrace}, @value{GDBN} will display the backtrace for all 8210the threads; this is handy when you debug a core dump of a 8211multi-threaded program. 8212 8213Each line in the backtrace shows the frame number and the function name. 8214The program counter value is also shown---unless you use @code{set 8215print address off}. The backtrace also shows the source file name and 8216line number, as well as the arguments to the function. The program 8217counter value is omitted if it is at the beginning of the code for that 8218line number. 8219 8220Here is an example of a backtrace. It was made with the command 8221@samp{bt 3}, so it shows the innermost three frames. 8222 8223@smallexample 8224@group 8225#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) 8226 at builtin.c:993 8227#1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242 8228#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) 8229 at macro.c:71 8230(More stack frames follow...) 8231@end group 8232@end smallexample 8233 8234@noindent 8235The display for frame zero does not begin with a program counter 8236value, indicating that your program has stopped at the beginning of the 8237code for line @code{993} of @code{builtin.c}. 8238 8239@noindent 8240The value of parameter @code{data} in frame 1 has been replaced by 8241@code{@dots{}}. By default, @value{GDBN} prints the value of a parameter 8242only if it is a scalar (integer, pointer, enumeration, etc). See command 8243@kbd{set print frame-arguments} in @ref{Print Settings} for more details 8244on how to configure the way function parameter values are printed. 8245The command @kbd{set print frame-info} (@pxref{Print Settings}) controls 8246what frame information is printed. 8247 8248@cindex optimized out, in backtrace 8249@cindex function call arguments, optimized out 8250If your program was compiled with optimizations, some compilers will 8251optimize away arguments passed to functions if those arguments are 8252never used after the call. Such optimizations generate code that 8253passes arguments through registers, but doesn't store those arguments 8254in the stack frame. @value{GDBN} has no way of displaying such 8255arguments in stack frames other than the innermost one. Here's what 8256such a backtrace might look like: 8257 8258@smallexample 8259@group 8260#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) 8261 at builtin.c:993 8262#1 0x6e38 in expand_macro (sym=<optimized out>) at macro.c:242 8263#2 0x6840 in expand_token (obs=0x0, t=<optimized out>, td=0xf7fffb08) 8264 at macro.c:71 8265(More stack frames follow...) 8266@end group 8267@end smallexample 8268 8269@noindent 8270The values of arguments that were not saved in their stack frames are 8271shown as @samp{<optimized out>}. 8272 8273If you need to display the values of such optimized-out arguments, 8274either deduce that from other variables whose values depend on the one 8275you are interested in, or recompile without optimizations. 8276 8277@cindex backtrace beyond @code{main} function 8278@cindex program entry point 8279@cindex startup code, and backtrace 8280Most programs have a standard user entry point---a place where system 8281libraries and startup code transition into user code. For C this is 8282@code{main}@footnote{ 8283Note that embedded programs (the so-called ``free-standing'' 8284environment) are not required to have a @code{main} function as the 8285entry point. They could even have multiple entry points.}. 8286When @value{GDBN} finds the entry function in a backtrace 8287it will terminate the backtrace, to avoid tracing into highly 8288system-specific (and generally uninteresting) code. 8289 8290If you need to examine the startup code, or limit the number of levels 8291in a backtrace, you can change this behavior: 8292 8293@table @code 8294@item set backtrace past-main 8295@itemx set backtrace past-main on 8296@anchor{set backtrace past-main} 8297@kindex set backtrace 8298Backtraces will continue past the user entry point. 8299 8300@item set backtrace past-main off 8301Backtraces will stop when they encounter the user entry point. This is the 8302default. 8303 8304@item show backtrace past-main 8305@kindex show backtrace 8306Display the current user entry point backtrace policy. 8307 8308@item set backtrace past-entry 8309@itemx set backtrace past-entry on 8310@anchor{set backtrace past-entry} 8311Backtraces will continue past the internal entry point of an application. 8312This entry point is encoded by the linker when the application is built, 8313and is likely before the user entry point @code{main} (or equivalent) is called. 8314 8315@item set backtrace past-entry off 8316Backtraces will stop when they encounter the internal entry point of an 8317application. This is the default. 8318 8319@item show backtrace past-entry 8320Display the current internal entry point backtrace policy. 8321 8322@item set backtrace limit @var{n} 8323@itemx set backtrace limit 0 8324@itemx set backtrace limit unlimited 8325@anchor{set backtrace limit} 8326@cindex backtrace limit 8327Limit the backtrace to @var{n} levels. A value of @code{unlimited} 8328or zero means unlimited levels. 8329 8330@item show backtrace limit 8331Display the current limit on backtrace levels. 8332@end table 8333 8334You can control how file names are displayed. 8335 8336@table @code 8337@item set filename-display 8338@itemx set filename-display relative 8339@cindex filename-display 8340Display file names relative to the compilation directory. This is the default. 8341 8342@item set filename-display basename 8343Display only basename of a filename. 8344 8345@item set filename-display absolute 8346Display an absolute filename. 8347 8348@item show filename-display 8349Show the current way to display filenames. 8350@end table 8351 8352@node Selection 8353@section Selecting a Frame 8354 8355Most commands for examining the stack and other data in your program work on 8356whichever stack frame is selected at the moment. Here are the commands for 8357selecting a stack frame; all of them finish by printing a brief description 8358of the stack frame just selected. 8359 8360@table @code 8361@kindex frame@r{, selecting} 8362@kindex f @r{(@code{frame})} 8363@item frame @r{[} @var{frame-selection-spec} @r{]} 8364@item f @r{[} @var{frame-selection-spec} @r{]} 8365The @command{frame} command allows different stack frames to be 8366selected. The @var{frame-selection-spec} can be any of the following: 8367 8368@table @code 8369@kindex frame level 8370@item @var{num} 8371@item level @var{num} 8372Select frame level @var{num}. Recall that frame zero is the innermost 8373(currently executing) frame, frame one is the frame that called the 8374innermost one, and so on. The highest level frame is usually the one 8375for @code{main}. 8376 8377As this is the most common method of navigating the frame stack, the 8378string @command{level} can be omitted. For example, the following two 8379commands are equivalent: 8380 8381@smallexample 8382(@value{GDBP}) frame 3 8383(@value{GDBP}) frame level 3 8384@end smallexample 8385 8386@kindex frame address 8387@item address @var{stack-address} 8388Select the frame with stack address @var{stack-address}. The 8389@var{stack-address} for a frame can be seen in the output of 8390@command{info frame}, for example: 8391 8392@smallexample 8393(gdb) info frame 8394Stack level 1, frame at 0x7fffffffda30: 8395 rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5 8396 tail call frame, caller of frame at 0x7fffffffda30 8397 source language c++. 8398 Arglist at unknown address. 8399 Locals at unknown address, Previous frame's sp is 0x7fffffffda30 8400@end smallexample 8401 8402The @var{stack-address} for this frame is @code{0x7fffffffda30} as 8403indicated by the line: 8404 8405@smallexample 8406Stack level 1, frame at 0x7fffffffda30: 8407@end smallexample 8408 8409@kindex frame function 8410@item function @var{function-name} 8411Select the stack frame for function @var{function-name}. If there are 8412multiple stack frames for function @var{function-name} then the inner 8413most stack frame is selected. 8414 8415@kindex frame view 8416@item view @var{stack-address} @r{[} @var{pc-addr} @r{]} 8417View a frame that is not part of @value{GDBN}'s backtrace. The frame 8418viewed has stack address @var{stack-addr}, and optionally, a program 8419counter address of @var{pc-addr}. 8420 8421This is useful mainly if the chaining of stack frames has been 8422damaged by a bug, making it impossible for @value{GDBN} to assign 8423numbers properly to all frames. In addition, this can be useful 8424when your program has multiple stacks and switches between them. 8425 8426When viewing a frame outside the current backtrace using 8427@command{frame view} then you can always return to the original 8428stack using one of the previous stack frame selection instructions, 8429for example @command{frame level 0}. 8430 8431@end table 8432 8433@kindex up 8434@item up @var{n} 8435Move @var{n} frames up the stack; @var{n} defaults to 1. For positive 8436numbers @var{n}, this advances toward the outermost frame, to higher 8437frame numbers, to frames that have existed longer. 8438 8439@kindex down 8440@kindex do @r{(@code{down})} 8441@item down @var{n} 8442Move @var{n} frames down the stack; @var{n} defaults to 1. For 8443positive numbers @var{n}, this advances toward the innermost frame, to 8444lower frame numbers, to frames that were created more recently. 8445You may abbreviate @code{down} as @code{do}. 8446@end table 8447 8448All of these commands end by printing two lines of output describing the 8449frame. The first line shows the frame number, the function name, the 8450arguments, and the source file and line number of execution in that 8451frame. The second line shows the text of that source line. 8452 8453@need 1000 8454For example: 8455 8456@smallexample 8457@group 8458(@value{GDBP}) up 8459#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) 8460 at env.c:10 846110 read_input_file (argv[i]); 8462@end group 8463@end smallexample 8464 8465After such a printout, the @code{list} command with no arguments 8466prints ten lines centered on the point of execution in the frame. 8467You can also edit the program at the point of execution with your favorite 8468editing program by typing @code{edit}. 8469@xref{List, ,Printing Source Lines}, 8470for details. 8471 8472@table @code 8473@kindex select-frame 8474@item select-frame @r{[} @var{frame-selection-spec} @r{]} 8475The @code{select-frame} command is a variant of @code{frame} that does 8476not display the new frame after selecting it. This command is 8477intended primarily for use in @value{GDBN} command scripts, where the 8478output might be unnecessary and distracting. The 8479@var{frame-selection-spec} is as for the @command{frame} command 8480described in @ref{Selection, ,Selecting a Frame}. 8481 8482@kindex down-silently 8483@kindex up-silently 8484@item up-silently @var{n} 8485@itemx down-silently @var{n} 8486These two commands are variants of @code{up} and @code{down}, 8487respectively; they differ in that they do their work silently, without 8488causing display of the new frame. They are intended primarily for use 8489in @value{GDBN} command scripts, where the output might be unnecessary and 8490distracting. 8491@end table 8492 8493@node Frame Info 8494@section Information About a Frame 8495 8496There are several other commands to print information about the selected 8497stack frame. 8498 8499@table @code 8500@item frame 8501@itemx f 8502When used without any argument, this command does not change which 8503frame is selected, but prints a brief description of the currently 8504selected stack frame. It can be abbreviated @code{f}. With an 8505argument, this command is used to select a stack frame. 8506@xref{Selection, ,Selecting a Frame}. 8507 8508@kindex info frame 8509@kindex info f @r{(@code{info frame})} 8510@item info frame 8511@itemx info f 8512This command prints a verbose description of the selected stack frame, 8513including: 8514 8515@itemize @bullet 8516@item 8517the address of the frame 8518@item 8519the address of the next frame down (called by this frame) 8520@item 8521the address of the next frame up (caller of this frame) 8522@item 8523the language in which the source code corresponding to this frame is written 8524@item 8525the address of the frame's arguments 8526@item 8527the address of the frame's local variables 8528@item 8529the program counter saved in it (the address of execution in the caller frame) 8530@item 8531which registers were saved in the frame 8532@end itemize 8533 8534@noindent The verbose description is useful when 8535something has gone wrong that has made the stack format fail to fit 8536the usual conventions. 8537 8538@item info frame @r{[} @var{frame-selection-spec} @r{]} 8539@itemx info f @r{[} @var{frame-selection-spec} @r{]} 8540Print a verbose description of the frame selected by 8541@var{frame-selection-spec}. The @var{frame-selection-spec} is the 8542same as for the @command{frame} command (@pxref{Selection, ,Selecting 8543a Frame}). The selected frame remains unchanged by this command. 8544 8545@kindex info args 8546@item info args [-q] 8547Print the arguments of the selected frame, each on a separate line. 8548 8549The optional flag @samp{-q}, which stands for @samp{quiet}, disables 8550printing header information and messages explaining why no argument 8551have been printed. 8552 8553@item info args [-q] [-t @var{type_regexp}] [@var{regexp}] 8554Like @kbd{info args}, but only print the arguments selected 8555with the provided regexp(s). 8556 8557If @var{regexp} is provided, print only the arguments whose names 8558match the regular expression @var{regexp}. 8559 8560If @var{type_regexp} is provided, print only the arguments whose 8561types, as printed by the @code{whatis} command, match 8562the regular expression @var{type_regexp}. 8563If @var{type_regexp} contains space(s), it should be enclosed in 8564quote characters. If needed, use backslash to escape the meaning 8565of special characters or quotes. 8566 8567If both @var{regexp} and @var{type_regexp} are provided, an argument 8568is printed only if its name matches @var{regexp} and its type matches 8569@var{type_regexp}. 8570 8571@item info locals [-q] 8572@kindex info locals 8573Print the local variables of the selected frame, each on a separate 8574line. These are all variables (declared either static or automatic) 8575accessible at the point of execution of the selected frame. 8576 8577The optional flag @samp{-q}, which stands for @samp{quiet}, disables 8578printing header information and messages explaining why no local variables 8579have been printed. 8580 8581@item info locals [-q] [-t @var{type_regexp}] [@var{regexp}] 8582Like @kbd{info locals}, but only print the local variables selected 8583with the provided regexp(s). 8584 8585If @var{regexp} is provided, print only the local variables whose names 8586match the regular expression @var{regexp}. 8587 8588If @var{type_regexp} is provided, print only the local variables whose 8589types, as printed by the @code{whatis} command, match 8590the regular expression @var{type_regexp}. 8591If @var{type_regexp} contains space(s), it should be enclosed in 8592quote characters. If needed, use backslash to escape the meaning 8593of special characters or quotes. 8594 8595If both @var{regexp} and @var{type_regexp} are provided, a local variable 8596is printed only if its name matches @var{regexp} and its type matches 8597@var{type_regexp}. 8598 8599The command @kbd{info locals -q -t @var{type_regexp}} can usefully be 8600combined with the commands @kbd{frame apply} and @kbd{thread apply}. 8601For example, your program might use Resource Acquisition Is 8602Initialization types (RAII) such as @code{lock_something_t}: each 8603local variable of type @code{lock_something_t} automatically places a 8604lock that is destroyed when the variable goes out of scope. You can 8605then list all acquired locks in your program by doing 8606@smallexample 8607thread apply all -s frame apply all -s info locals -q -t lock_something_t 8608@end smallexample 8609@noindent 8610or the equivalent shorter form 8611@smallexample 8612tfaas i lo -q -t lock_something_t 8613@end smallexample 8614 8615@end table 8616 8617@node Frame Apply 8618@section Applying a Command to Several Frames. 8619@kindex frame apply 8620@cindex apply command to several frames 8621@table @code 8622@item frame apply [all | @var{count} | @var{-count} | level @var{level}@dots{}] [@var{option}]@dots{} @var{command} 8623The @code{frame apply} command allows you to apply the named 8624@var{command} to one or more frames. 8625 8626@table @code 8627@item @code{all} 8628Specify @code{all} to apply @var{command} to all frames. 8629 8630@item @var{count} 8631Use @var{count} to apply @var{command} to the innermost @var{count} 8632frames, where @var{count} is a positive number. 8633 8634@item @var{-count} 8635Use @var{-count} to apply @var{command} to the outermost @var{count} 8636frames, where @var{count} is a positive number. 8637 8638@item @code{level} 8639Use @code{level} to apply @var{command} to the set of frames identified 8640by the @var{level} list. @var{level} is a frame level or a range of frame 8641levels as @var{level1}-@var{level2}. The frame level is the number shown 8642in the first field of the @samp{backtrace} command output. 8643E.g., @samp{2-4 6-8 3} indicates to apply @var{command} for the frames 8644at levels 2, 3, 4, 6, 7, 8, and then again on frame at level 3. 8645 8646@end table 8647 8648Note that the frames on which @code{frame apply} applies a command are 8649also influenced by the @code{set backtrace} settings such as @code{set 8650backtrace past-main} and @code{set backtrace limit N}. 8651@xref{Backtrace,,Backtraces}. 8652 8653The @code{frame apply} command also supports a number of options that 8654allow overriding relevant @code{set backtrace} settings: 8655 8656@table @code 8657@item -past-main [@code{on}|@code{off}] 8658Whether backtraces should continue past @code{main}. 8659Related setting: @ref{set backtrace past-main}. 8660 8661@item -past-entry [@code{on}|@code{off}] 8662Whether backtraces should continue past the entry point of a program. 8663Related setting: @ref{set backtrace past-entry}. 8664@end table 8665 8666By default, @value{GDBN} displays some frame information before the 8667output produced by @var{command}, and an error raised during the 8668execution of a @var{command} will abort @code{frame apply}. The 8669following options can be used to fine-tune these behaviors: 8670 8671@table @code 8672@item -c 8673The flag @code{-c}, which stands for @samp{continue}, causes any 8674errors in @var{command} to be displayed, and the execution of 8675@code{frame apply} then continues. 8676@item -s 8677The flag @code{-s}, which stands for @samp{silent}, causes any errors 8678or empty output produced by a @var{command} to be silently ignored. 8679That is, the execution continues, but the frame information and errors 8680are not printed. 8681@item -q 8682The flag @code{-q} (@samp{quiet}) disables printing the frame 8683information. 8684@end table 8685 8686The following example shows how the flags @code{-c} and @code{-s} are 8687working when applying the command @code{p j} to all frames, where 8688variable @code{j} can only be successfully printed in the outermost 8689@code{#1 main} frame. 8690 8691@smallexample 8692@group 8693(gdb) frame apply all p j 8694#0 some_function (i=5) at fun.c:4 8695No symbol "j" in current context. 8696(gdb) frame apply all -c p j 8697#0 some_function (i=5) at fun.c:4 8698No symbol "j" in current context. 8699#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11 8700$1 = 5 8701(gdb) frame apply all -s p j 8702#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11 8703$2 = 5 8704(gdb) 8705@end group 8706@end smallexample 8707 8708By default, @samp{frame apply}, prints the frame location 8709information before the command output: 8710 8711@smallexample 8712@group 8713(gdb) frame apply all p $sp 8714#0 some_function (i=5) at fun.c:4 8715$4 = (void *) 0xffffd1e0 8716#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11 8717$5 = (void *) 0xffffd1f0 8718(gdb) 8719@end group 8720@end smallexample 8721 8722If the flag @code{-q} is given, no frame information is printed: 8723@smallexample 8724@group 8725(gdb) frame apply all -q p $sp 8726$12 = (void *) 0xffffd1e0 8727$13 = (void *) 0xffffd1f0 8728(gdb) 8729@end group 8730@end smallexample 8731 8732@end table 8733 8734@table @code 8735 8736@kindex faas 8737@cindex apply a command to all frames (ignoring errors and empty output) 8738@item faas @var{command} 8739Shortcut for @code{frame apply all -s @var{command}}. 8740Applies @var{command} on all frames, ignoring errors and empty output. 8741 8742It can for example be used to print a local variable or a function 8743argument without knowing the frame where this variable or argument 8744is, using: 8745@smallexample 8746(@value{GDBP}) faas p some_local_var_i_do_not_remember_where_it_is 8747@end smallexample 8748 8749The @code{faas} command accepts the same options as the @code{frame 8750apply} command. @xref{Frame Apply,,frame apply}. 8751 8752Note that the command @code{tfaas @var{command}} applies @var{command} 8753on all frames of all threads. See @xref{Threads,,Threads}. 8754@end table 8755 8756 8757@node Frame Filter Management 8758@section Management of Frame Filters. 8759@cindex managing frame filters 8760 8761Frame filters are Python based utilities to manage and decorate the 8762output of frames. @xref{Frame Filter API}, for further information. 8763 8764Managing frame filters is performed by several commands available 8765within @value{GDBN}, detailed here. 8766 8767@table @code 8768@kindex info frame-filter 8769@item info frame-filter 8770Print a list of installed frame filters from all dictionaries, showing 8771their name, priority and enabled status. 8772 8773@kindex disable frame-filter 8774@anchor{disable frame-filter all} 8775@item disable frame-filter @var{filter-dictionary} @var{filter-name} 8776Disable a frame filter in the dictionary matching 8777@var{filter-dictionary} and @var{filter-name}. The 8778@var{filter-dictionary} may be @code{all}, @code{global}, 8779@code{progspace}, or the name of the object file where the frame filter 8780dictionary resides. When @code{all} is specified, all frame filters 8781across all dictionaries are disabled. The @var{filter-name} is the name 8782of the frame filter and is used when @code{all} is not the option for 8783@var{filter-dictionary}. A disabled frame-filter is not deleted, it 8784may be enabled again later. 8785 8786@kindex enable frame-filter 8787@item enable frame-filter @var{filter-dictionary} @var{filter-name} 8788Enable a frame filter in the dictionary matching 8789@var{filter-dictionary} and @var{filter-name}. The 8790@var{filter-dictionary} may be @code{all}, @code{global}, 8791@code{progspace} or the name of the object file where the frame filter 8792dictionary resides. When @code{all} is specified, all frame filters across 8793all dictionaries are enabled. The @var{filter-name} is the name of the frame 8794filter and is used when @code{all} is not the option for 8795@var{filter-dictionary}. 8796 8797Example: 8798 8799@smallexample 8800(gdb) info frame-filter 8801 8802global frame-filters: 8803 Priority Enabled Name 8804 1000 No PrimaryFunctionFilter 8805 100 Yes Reverse 8806 8807progspace /build/test frame-filters: 8808 Priority Enabled Name 8809 100 Yes ProgspaceFilter 8810 8811objfile /build/test frame-filters: 8812 Priority Enabled Name 8813 999 Yes BuildProgramFilter 8814 8815(gdb) disable frame-filter /build/test BuildProgramFilter 8816(gdb) info frame-filter 8817 8818global frame-filters: 8819 Priority Enabled Name 8820 1000 No PrimaryFunctionFilter 8821 100 Yes Reverse 8822 8823progspace /build/test frame-filters: 8824 Priority Enabled Name 8825 100 Yes ProgspaceFilter 8826 8827objfile /build/test frame-filters: 8828 Priority Enabled Name 8829 999 No BuildProgramFilter 8830 8831(gdb) enable frame-filter global PrimaryFunctionFilter 8832(gdb) info frame-filter 8833 8834global frame-filters: 8835 Priority Enabled Name 8836 1000 Yes PrimaryFunctionFilter 8837 100 Yes Reverse 8838 8839progspace /build/test frame-filters: 8840 Priority Enabled Name 8841 100 Yes ProgspaceFilter 8842 8843objfile /build/test frame-filters: 8844 Priority Enabled Name 8845 999 No BuildProgramFilter 8846@end smallexample 8847 8848@kindex set frame-filter priority 8849@item set frame-filter priority @var{filter-dictionary} @var{filter-name} @var{priority} 8850Set the @var{priority} of a frame filter in the dictionary matching 8851@var{filter-dictionary}, and the frame filter name matching 8852@var{filter-name}. The @var{filter-dictionary} may be @code{global}, 8853@code{progspace} or the name of the object file where the frame filter 8854dictionary resides. The @var{priority} is an integer. 8855 8856@kindex show frame-filter priority 8857@item show frame-filter priority @var{filter-dictionary} @var{filter-name} 8858Show the @var{priority} of a frame filter in the dictionary matching 8859@var{filter-dictionary}, and the frame filter name matching 8860@var{filter-name}. The @var{filter-dictionary} may be @code{global}, 8861@code{progspace} or the name of the object file where the frame filter 8862dictionary resides. 8863 8864Example: 8865 8866@smallexample 8867(gdb) info frame-filter 8868 8869global frame-filters: 8870 Priority Enabled Name 8871 1000 Yes PrimaryFunctionFilter 8872 100 Yes Reverse 8873 8874progspace /build/test frame-filters: 8875 Priority Enabled Name 8876 100 Yes ProgspaceFilter 8877 8878objfile /build/test frame-filters: 8879 Priority Enabled Name 8880 999 No BuildProgramFilter 8881 8882(gdb) set frame-filter priority global Reverse 50 8883(gdb) info frame-filter 8884 8885global frame-filters: 8886 Priority Enabled Name 8887 1000 Yes PrimaryFunctionFilter 8888 50 Yes Reverse 8889 8890progspace /build/test frame-filters: 8891 Priority Enabled Name 8892 100 Yes ProgspaceFilter 8893 8894objfile /build/test frame-filters: 8895 Priority Enabled Name 8896 999 No BuildProgramFilter 8897@end smallexample 8898@end table 8899 8900@node Source 8901@chapter Examining Source Files 8902 8903@value{GDBN} can print parts of your program's source, since the debugging 8904information recorded in the program tells @value{GDBN} what source files were 8905used to build it. When your program stops, @value{GDBN} spontaneously prints 8906the line where it stopped. Likewise, when you select a stack frame 8907(@pxref{Selection, ,Selecting a Frame}), @value{GDBN} prints the line where 8908execution in that frame has stopped. You can print other portions of 8909source files by explicit command. 8910 8911If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may 8912prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using 8913@value{GDBN} under @sc{gnu} Emacs}. 8914 8915@menu 8916* List:: Printing source lines 8917* Specify Location:: How to specify code locations 8918* Edit:: Editing source files 8919* Search:: Searching source files 8920* Source Path:: Specifying source directories 8921* Machine Code:: Source and machine code 8922@end menu 8923 8924@node List 8925@section Printing Source Lines 8926 8927@kindex list 8928@kindex l @r{(@code{list})} 8929To print lines from a source file, use the @code{list} command 8930(abbreviated @code{l}). By default, ten lines are printed. 8931There are several ways to specify what part of the file you want to 8932print; see @ref{Specify Location}, for the full list. 8933 8934Here are the forms of the @code{list} command most commonly used: 8935 8936@table @code 8937@item list @var{linenum} 8938Print lines centered around line number @var{linenum} in the 8939current source file. 8940 8941@item list @var{function} 8942Print lines centered around the beginning of function 8943@var{function}. 8944 8945@item list 8946Print more lines. If the last lines printed were printed with a 8947@code{list} command, this prints lines following the last lines 8948printed; however, if the last line printed was a solitary line printed 8949as part of displaying a stack frame (@pxref{Stack, ,Examining the 8950Stack}), this prints lines centered around that line. 8951 8952@item list - 8953Print lines just before the lines last printed. 8954@end table 8955 8956@cindex @code{list}, how many lines to display 8957By default, @value{GDBN} prints ten source lines with any of these forms of 8958the @code{list} command. You can change this using @code{set listsize}: 8959 8960@table @code 8961@kindex set listsize 8962@item set listsize @var{count} 8963@itemx set listsize unlimited 8964Make the @code{list} command display @var{count} source lines (unless 8965the @code{list} argument explicitly specifies some other number). 8966Setting @var{count} to @code{unlimited} or 0 means there's no limit. 8967 8968@kindex show listsize 8969@item show listsize 8970Display the number of lines that @code{list} prints. 8971@end table 8972 8973Repeating a @code{list} command with @key{RET} discards the argument, 8974so it is equivalent to typing just @code{list}. This is more useful 8975than listing the same lines again. An exception is made for an 8976argument of @samp{-}; that argument is preserved in repetition so that 8977each repetition moves up in the source file. 8978 8979In general, the @code{list} command expects you to supply zero, one or two 8980@dfn{locations}. Locations specify source lines; there are several ways 8981of writing them (@pxref{Specify Location}), but the effect is always 8982to specify some source line. 8983 8984Here is a complete description of the possible arguments for @code{list}: 8985 8986@table @code 8987@item list @var{location} 8988Print lines centered around the line specified by @var{location}. 8989 8990@item list @var{first},@var{last} 8991Print lines from @var{first} to @var{last}. Both arguments are 8992locations. When a @code{list} command has two locations, and the 8993source file of the second location is omitted, this refers to 8994the same source file as the first location. 8995 8996@item list ,@var{last} 8997Print lines ending with @var{last}. 8998 8999@item list @var{first}, 9000Print lines starting with @var{first}. 9001 9002@item list + 9003Print lines just after the lines last printed. 9004 9005@item list - 9006Print lines just before the lines last printed. 9007 9008@item list 9009As described in the preceding table. 9010@end table 9011 9012@node Specify Location 9013@section Specifying a Location 9014@cindex specifying location 9015@cindex location 9016@cindex source location 9017 9018Several @value{GDBN} commands accept arguments that specify a location 9019of your program's code. Since @value{GDBN} is a source-level 9020debugger, a location usually specifies some line in the source code. 9021Locations may be specified using three different formats: 9022linespec locations, explicit locations, or address locations. 9023 9024@menu 9025* Linespec Locations:: Linespec locations 9026* Explicit Locations:: Explicit locations 9027* Address Locations:: Address locations 9028@end menu 9029 9030@node Linespec Locations 9031@subsection Linespec Locations 9032@cindex linespec locations 9033 9034A @dfn{linespec} is a colon-separated list of source location parameters such 9035as file name, function name, etc. Here are all the different ways of 9036specifying a linespec: 9037 9038@table @code 9039@item @var{linenum} 9040Specifies the line number @var{linenum} of the current source file. 9041 9042@item -@var{offset} 9043@itemx +@var{offset} 9044Specifies the line @var{offset} lines before or after the @dfn{current 9045line}. For the @code{list} command, the current line is the last one 9046printed; for the breakpoint commands, this is the line at which 9047execution stopped in the currently selected @dfn{stack frame} 9048(@pxref{Frames, ,Frames}, for a description of stack frames.) When 9049used as the second of the two linespecs in a @code{list} command, 9050this specifies the line @var{offset} lines up or down from the first 9051linespec. 9052 9053@item @var{filename}:@var{linenum} 9054Specifies the line @var{linenum} in the source file @var{filename}. 9055If @var{filename} is a relative file name, then it will match any 9056source file name with the same trailing components. For example, if 9057@var{filename} is @samp{gcc/expr.c}, then it will match source file 9058name of @file{/build/trunk/gcc/expr.c}, but not 9059@file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}. 9060 9061@item @var{function} 9062Specifies the line that begins the body of the function @var{function}. 9063For example, in C, this is the line with the open brace. 9064 9065By default, in C@t{++} and Ada, @var{function} is interpreted as 9066specifying all functions named @var{function} in all scopes. For 9067C@t{++}, this means in all namespaces and classes. For Ada, this 9068means in all packages. 9069 9070For example, assuming a program with C@t{++} symbols named 9071@code{A::B::func} and @code{B::func}, both commands @w{@kbd{break 9072func}} and @w{@kbd{break B::func}} set a breakpoint on both symbols. 9073 9074Commands that accept a linespec let you override this with the 9075@code{-qualified} option. For example, @w{@kbd{break -qualified 9076func}} sets a breakpoint on a free-function named @code{func} ignoring 9077any C@t{++} class methods and namespace functions called @code{func}. 9078 9079@xref{Explicit Locations}. 9080 9081@item @var{function}:@var{label} 9082Specifies the line where @var{label} appears in @var{function}. 9083 9084@item @var{filename}:@var{function} 9085Specifies the line that begins the body of the function @var{function} 9086in the file @var{filename}. You only need the file name with a 9087function name to avoid ambiguity when there are identically named 9088functions in different source files. 9089 9090@item @var{label} 9091Specifies the line at which the label named @var{label} appears 9092in the function corresponding to the currently selected stack frame. 9093If there is no current selected stack frame (for instance, if the inferior 9094is not running), then @value{GDBN} will not search for a label. 9095 9096@cindex breakpoint at static probe point 9097@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name} 9098The @sc{gnu}/Linux tool @code{SystemTap} provides a way for 9099applications to embed static probes. @xref{Static Probe Points}, for more 9100information on finding and using static probes. This form of linespec 9101specifies the location of such a static probe. 9102 9103If @var{objfile} is given, only probes coming from that shared library 9104or executable matching @var{objfile} as a regular expression are considered. 9105If @var{provider} is given, then only probes from that provider are considered. 9106If several probes match the spec, @value{GDBN} will insert a breakpoint at 9107each one of those probes. 9108@end table 9109 9110@node Explicit Locations 9111@subsection Explicit Locations 9112@cindex explicit locations 9113 9114@dfn{Explicit locations} allow the user to directly specify the source 9115location's parameters using option-value pairs. 9116 9117Explicit locations are useful when several functions, labels, or 9118file names have the same name (base name for files) in the program's 9119sources. In these cases, explicit locations point to the source 9120line you meant more accurately and unambiguously. Also, using 9121explicit locations might be faster in large programs. 9122 9123For example, the linespec @samp{foo:bar} may refer to a function @code{bar} 9124defined in the file named @file{foo} or the label @code{bar} in a function 9125named @code{foo}. @value{GDBN} must search either the file system or 9126the symbol table to know. 9127 9128The list of valid explicit location options is summarized in the 9129following table: 9130 9131@table @code 9132@item -source @var{filename} 9133The value specifies the source file name. To differentiate between 9134files with the same base name, prepend as many directories as is necessary 9135to uniquely identify the desired file, e.g., @file{foo/bar/baz.c}. Otherwise 9136@value{GDBN} will use the first file it finds with the given base 9137name. This option requires the use of either @code{-function} or @code{-line}. 9138 9139@item -function @var{function} 9140The value specifies the name of a function. Operations 9141on function locations unmodified by other options (such as @code{-label} 9142or @code{-line}) refer to the line that begins the body of the function. 9143In C, for example, this is the line with the open brace. 9144 9145By default, in C@t{++} and Ada, @var{function} is interpreted as 9146specifying all functions named @var{function} in all scopes. For 9147C@t{++}, this means in all namespaces and classes. For Ada, this 9148means in all packages. 9149 9150For example, assuming a program with C@t{++} symbols named 9151@code{A::B::func} and @code{B::func}, both commands @w{@kbd{break 9152-function func}} and @w{@kbd{break -function B::func}} set a 9153breakpoint on both symbols. 9154 9155You can use the @kbd{-qualified} flag to override this (see below). 9156 9157@item -qualified 9158 9159This flag makes @value{GDBN} interpret a function name specified with 9160@kbd{-function} as a complete fully-qualified name. 9161 9162For example, assuming a C@t{++} program with symbols named 9163@code{A::B::func} and @code{B::func}, the @w{@kbd{break -qualified 9164-function B::func}} command sets a breakpoint on @code{B::func}, only. 9165 9166(Note: the @kbd{-qualified} option can precede a linespec as well 9167(@pxref{Linespec Locations}), so the particular example above could be 9168simplified as @w{@kbd{break -qualified B::func}}.) 9169 9170@item -label @var{label} 9171The value specifies the name of a label. When the function 9172name is not specified, the label is searched in the function of the currently 9173selected stack frame. 9174 9175@item -line @var{number} 9176The value specifies a line offset for the location. The offset may either 9177be absolute (@code{-line 3}) or relative (@code{-line +3}), depending on 9178the command. When specified without any other options, the line offset is 9179relative to the current line. 9180@end table 9181 9182Explicit location options may be abbreviated by omitting any non-unique 9183trailing characters from the option name, e.g., @w{@kbd{break -s main.c -li 3}}. 9184 9185@node Address Locations 9186@subsection Address Locations 9187@cindex address locations 9188 9189@dfn{Address locations} indicate a specific program address. They have 9190the generalized form *@var{address}. 9191 9192For line-oriented commands, such as @code{list} and @code{edit}, this 9193specifies a source line that contains @var{address}. For @code{break} and 9194other breakpoint-oriented commands, this can be used to set breakpoints in 9195parts of your program which do not have debugging information or 9196source files. 9197 9198Here @var{address} may be any expression valid in the current working 9199language (@pxref{Languages, working language}) that specifies a code 9200address. In addition, as a convenience, @value{GDBN} extends the 9201semantics of expressions used in locations to cover several situations 9202that frequently occur during debugging. Here are the various forms 9203of @var{address}: 9204 9205@table @code 9206@item @var{expression} 9207Any expression valid in the current working language. 9208 9209@item @var{funcaddr} 9210An address of a function or procedure derived from its name. In C, 9211C@t{++}, Objective-C, Fortran, minimal, and assembly, this is 9212simply the function's name @var{function} (and actually a special case 9213of a valid expression). In Pascal and Modula-2, this is 9214@code{&@var{function}}. In Ada, this is @code{@var{function}'Address} 9215(although the Pascal form also works). 9216 9217This form specifies the address of the function's first instruction, 9218before the stack frame and arguments have been set up. 9219 9220@item '@var{filename}':@var{funcaddr} 9221Like @var{funcaddr} above, but also specifies the name of the source 9222file explicitly. This is useful if the name of the function does not 9223specify the function unambiguously, e.g., if there are several 9224functions with identical names in different source files. 9225@end table 9226 9227@node Edit 9228@section Editing Source Files 9229@cindex editing source files 9230 9231@kindex edit 9232@kindex e @r{(@code{edit})} 9233To edit the lines in a source file, use the @code{edit} command. 9234The editing program of your choice 9235is invoked with the current line set to 9236the active line in the program. 9237Alternatively, there are several ways to specify what part of the file you 9238want to print if you want to see other parts of the program: 9239 9240@table @code 9241@item edit @var{location} 9242Edit the source file specified by @code{location}. Editing starts at 9243that @var{location}, e.g., at the specified source line of the 9244specified file. @xref{Specify Location}, for all the possible forms 9245of the @var{location} argument; here are the forms of the @code{edit} 9246command most commonly used: 9247 9248@table @code 9249@item edit @var{number} 9250Edit the current source file with @var{number} as the active line number. 9251 9252@item edit @var{function} 9253Edit the file containing @var{function} at the beginning of its definition. 9254@end table 9255 9256@end table 9257 9258@subsection Choosing your Editor 9259You can customize @value{GDBN} to use any editor you want 9260@footnote{ 9261The only restriction is that your editor (say @code{ex}), recognizes the 9262following command-line syntax: 9263@smallexample 9264ex +@var{number} file 9265@end smallexample 9266The optional numeric value +@var{number} specifies the number of the line in 9267the file where to start editing.}. 9268By default, it is @file{@value{EDITOR}}, but you can change this 9269by setting the environment variable @env{EDITOR} before using 9270@value{GDBN}. For example, to configure @value{GDBN} to use the 9271@code{vi} editor, you could use these commands with the @code{sh} shell: 9272@smallexample 9273EDITOR=/usr/bin/vi 9274export EDITOR 9275gdb @dots{} 9276@end smallexample 9277or in the @code{csh} shell, 9278@smallexample 9279setenv EDITOR /usr/bin/vi 9280gdb @dots{} 9281@end smallexample 9282 9283@node Search 9284@section Searching Source Files 9285@cindex searching source files 9286 9287There are two commands for searching through the current source file for a 9288regular expression. 9289 9290@table @code 9291@kindex search 9292@kindex forward-search 9293@kindex fo @r{(@code{forward-search})} 9294@item forward-search @var{regexp} 9295@itemx search @var{regexp} 9296The command @samp{forward-search @var{regexp}} checks each line, 9297starting with the one following the last line listed, for a match for 9298@var{regexp}. It lists the line that is found. You can use the 9299synonym @samp{search @var{regexp}} or abbreviate the command name as 9300@code{fo}. 9301 9302@kindex reverse-search 9303@item reverse-search @var{regexp} 9304The command @samp{reverse-search @var{regexp}} checks each line, starting 9305with the one before the last line listed and going backward, for a match 9306for @var{regexp}. It lists the line that is found. You can abbreviate 9307this command as @code{rev}. 9308@end table 9309 9310@node Source Path 9311@section Specifying Source Directories 9312 9313@cindex source path 9314@cindex directories for source files 9315Executable programs sometimes do not record the directories of the source 9316files from which they were compiled, just the names. Even when they do, 9317the directories could be moved between the compilation and your debugging 9318session. @value{GDBN} has a list of directories to search for source files; 9319this is called the @dfn{source path}. Each time @value{GDBN} wants a source file, 9320it tries all the directories in the list, in the order they are present 9321in the list, until it finds a file with the desired name. 9322 9323For example, suppose an executable references the file 9324@file{/usr/src/foo-1.0/lib/foo.c}, does not record a compilation 9325directory, and the @dfn{source path} is @file{/mnt/cross}. 9326@value{GDBN} would look for the source file in the following 9327locations: 9328 9329@enumerate 9330 9331@item @file{/usr/src/foo-1.0/lib/foo.c} 9332@item @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} 9333@item @file{/mnt/cross/foo.c} 9334 9335@end enumerate 9336 9337If the source file is not present at any of the above locations then 9338an error is printed. @value{GDBN} does not look up the parts of the 9339source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}. 9340Likewise, the subdirectories of the source path are not searched: if 9341the source path is @file{/mnt/cross}, and the binary refers to 9342@file{foo.c}, @value{GDBN} would not find it under 9343@file{/mnt/cross/usr/src/foo-1.0/lib}. 9344 9345Plain file names, relative file names with leading directories, file 9346names containing dots, etc.@: are all treated as described above, 9347except that non-absolute file names are not looked up literally. If 9348the @dfn{source path} is @file{/mnt/cross}, the source file is 9349recorded as @file{../lib/foo.c}, and no compilation directory is 9350recorded, then @value{GDBN} will search in the following locations: 9351 9352@enumerate 9353 9354@item @file{/mnt/cross/../lib/foo.c} 9355@item @file{/mnt/cross/foo.c} 9356 9357@end enumerate 9358 9359@kindex cdir 9360@kindex cwd 9361@vindex $cdir@r{, convenience variable} 9362@vindex $cwd@r{, convenience variable} 9363@cindex compilation directory 9364@cindex current directory 9365@cindex working directory 9366@cindex directory, current 9367@cindex directory, compilation 9368The @dfn{source path} will always include two special entries 9369@samp{$cdir} and @samp{$cwd}, these refer to the compilation directory 9370(if one is recorded) and the current working directory respectively. 9371 9372@samp{$cdir} causes @value{GDBN} to search within the compilation 9373directory, if one is recorded in the debug information. If no 9374compilation directory is recorded in the debug information then 9375@samp{$cdir} is ignored. 9376 9377@samp{$cwd} is not the same as @samp{.}---the former tracks the 9378current working directory as it changes during your @value{GDBN} 9379session, while the latter is immediately expanded to the current 9380directory at the time you add an entry to the source path. 9381 9382If a compilation directory is recorded in the debug information, and 9383@value{GDBN} has not found the source file after the first search 9384using @dfn{source path}, then @value{GDBN} will combine the 9385compilation directory and the filename, and then search for the source 9386file again using the @dfn{source path}. 9387 9388For example, if the executable records the source file as 9389@file{/usr/src/foo-1.0/lib/foo.c}, the compilation directory is 9390recorded as @file{/project/build}, and the @dfn{source path} is 9391@file{/mnt/cross:$cdir:$cwd} while the current working directory of 9392the @value{GDBN} session is @file{/home/user}, then @value{GDBN} will 9393search for the source file in the following locations: 9394 9395@enumerate 9396 9397@item @file{/usr/src/foo-1.0/lib/foo.c} 9398@item @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} 9399@item @file{/project/build/usr/src/foo-1.0/lib/foo.c} 9400@item @file{/home/user/usr/src/foo-1.0/lib/foo.c} 9401@item @file{/mnt/cross/project/build/usr/src/foo-1.0/lib/foo.c} 9402@item @file{/project/build/project/build/usr/src/foo-1.0/lib/foo.c} 9403@item @file{/home/user/project/build/usr/src/foo-1.0/lib/foo.c} 9404@item @file{/mnt/cross/foo.c} 9405@item @file{/project/build/foo.c} 9406@item @file{/home/user/foo.c} 9407 9408@end enumerate 9409 9410If the file name in the previous example had been recorded in the 9411executable as a relative path rather than an absolute path, then the 9412first look up would not have occurred, but all of the remaining steps 9413would be similar. 9414 9415When searching for source files on MS-DOS and MS-Windows, where 9416absolute paths start with a drive letter (e.g.@: 9417@file{C:/project/foo.c}), @value{GDBN} will remove the drive letter 9418from the file name before appending it to a search directory from 9419@dfn{source path}; for instance if the executable references the 9420source file @file{C:/project/foo.c} and @dfn{source path} is set to 9421@file{D:/mnt/cross}, then @value{GDBN} will search in the following 9422locations for the source file: 9423 9424@enumerate 9425 9426@item @file{C:/project/foo.c} 9427@item @file{D:/mnt/cross/project/foo.c} 9428@item @file{D:/mnt/cross/foo.c} 9429 9430@end enumerate 9431 9432Note that the executable search path is @emph{not} used to locate the 9433source files. 9434 9435Whenever you reset or rearrange the source path, @value{GDBN} clears out 9436any information it has cached about where source files are found and where 9437each line is in the file. 9438 9439@kindex directory 9440@kindex dir 9441When you start @value{GDBN}, its source path includes only @samp{$cdir} 9442and @samp{$cwd}, in that order. 9443To add other directories, use the @code{directory} command. 9444 9445The search path is used to find both program source files and @value{GDBN} 9446script files (read using the @samp{-command} option and @samp{source} command). 9447 9448In addition to the source path, @value{GDBN} provides a set of commands 9449that manage a list of source path substitution rules. A @dfn{substitution 9450rule} specifies how to rewrite source directories stored in the program's 9451debug information in case the sources were moved to a different 9452directory between compilation and debugging. A rule is made of 9453two strings, the first specifying what needs to be rewritten in 9454the path, and the second specifying how it should be rewritten. 9455In @ref{set substitute-path}, we name these two parts @var{from} and 9456@var{to} respectively. @value{GDBN} does a simple string replacement 9457of @var{from} with @var{to} at the start of the directory part of the 9458source file name, and uses that result instead of the original file 9459name to look up the sources. 9460 9461Using the previous example, suppose the @file{foo-1.0} tree has been 9462moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell 9463@value{GDBN} to replace @file{/usr/src} in all source path names with 9464@file{/mnt/cross}. The first lookup will then be 9465@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location 9466of @file{/usr/src/foo-1.0/lib/foo.c}. To define a source path 9467substitution rule, use the @code{set substitute-path} command 9468(@pxref{set substitute-path}). 9469 9470To avoid unexpected substitution results, a rule is applied only if the 9471@var{from} part of the directory name ends at a directory separator. 9472For instance, a rule substituting @file{/usr/source} into 9473@file{/mnt/cross} will be applied to @file{/usr/source/foo-1.0} but 9474not to @file{/usr/sourceware/foo-2.0}. And because the substitution 9475is applied only at the beginning of the directory name, this rule will 9476not be applied to @file{/root/usr/source/baz.c} either. 9477 9478In many cases, you can achieve the same result using the @code{directory} 9479command. However, @code{set substitute-path} can be more efficient in 9480the case where the sources are organized in a complex tree with multiple 9481subdirectories. With the @code{directory} command, you need to add each 9482subdirectory of your project. If you moved the entire tree while 9483preserving its internal organization, then @code{set substitute-path} 9484allows you to direct the debugger to all the sources with one single 9485command. 9486 9487@code{set substitute-path} is also more than just a shortcut command. 9488The source path is only used if the file at the original location no 9489longer exists. On the other hand, @code{set substitute-path} modifies 9490the debugger behavior to look at the rewritten location instead. So, if 9491for any reason a source file that is not relevant to your executable is 9492located at the original location, a substitution rule is the only 9493method available to point @value{GDBN} at the new location. 9494 9495@cindex @samp{--with-relocated-sources} 9496@cindex default source path substitution 9497You can configure a default source path substitution rule by 9498configuring @value{GDBN} with the 9499@samp{--with-relocated-sources=@var{dir}} option. The @var{dir} 9500should be the name of a directory under @value{GDBN}'s configured 9501prefix (set with @samp{--prefix} or @samp{--exec-prefix}), and 9502directory names in debug information under @var{dir} will be adjusted 9503automatically if the installed @value{GDBN} is moved to a new 9504location. This is useful if @value{GDBN}, libraries or executables 9505with debug information and corresponding source code are being moved 9506together. 9507 9508@table @code 9509@item directory @var{dirname} @dots{} 9510@item dir @var{dirname} @dots{} 9511Add directory @var{dirname} to the front of the source path. Several 9512directory names may be given to this command, separated by @samp{:} 9513(@samp{;} on MS-DOS and MS-Windows, where @samp{:} usually appears as 9514part of absolute file names) or 9515whitespace. You may specify a directory that is already in the source 9516path; this moves it forward, so @value{GDBN} searches it sooner. 9517 9518The special strings @samp{$cdir} (to refer to the compilation 9519directory, if one is recorded), and @samp{$cwd} (to refer to the 9520current working directory) can also be included in the list of 9521directories @var{dirname}. Though these will already be in the source 9522path they will be moved forward in the list so @value{GDBN} searches 9523them sooner. 9524 9525@item directory 9526Reset the source path to its default value (@samp{$cdir:$cwd} on Unix systems). This requires confirmation. 9527 9528@c RET-repeat for @code{directory} is explicitly disabled, but since 9529@c repeating it would be a no-op we do not say that. (thanks to RMS) 9530 9531@item set directories @var{path-list} 9532@kindex set directories 9533Set the source path to @var{path-list}. 9534@samp{$cdir:$cwd} are added if missing. 9535 9536@item show directories 9537@kindex show directories 9538Print the source path: show which directories it contains. 9539 9540@anchor{set substitute-path} 9541@item set substitute-path @var{from} @var{to} 9542@kindex set substitute-path 9543Define a source path substitution rule, and add it at the end of the 9544current list of existing substitution rules. If a rule with the same 9545@var{from} was already defined, then the old rule is also deleted. 9546 9547For example, if the file @file{/foo/bar/baz.c} was moved to 9548@file{/mnt/cross/baz.c}, then the command 9549 9550@smallexample 9551(@value{GDBP}) set substitute-path /foo/bar /mnt/cross 9552@end smallexample 9553 9554@noindent 9555will tell @value{GDBN} to replace @samp{/foo/bar} with 9556@samp{/mnt/cross}, which will allow @value{GDBN} to find the file 9557@file{baz.c} even though it was moved. 9558 9559In the case when more than one substitution rule have been defined, 9560the rules are evaluated one by one in the order where they have been 9561defined. The first one matching, if any, is selected to perform 9562the substitution. 9563 9564For instance, if we had entered the following commands: 9565 9566@smallexample 9567(@value{GDBP}) set substitute-path /usr/src/include /mnt/include 9568(@value{GDBP}) set substitute-path /usr/src /mnt/src 9569@end smallexample 9570 9571@noindent 9572@value{GDBN} would then rewrite @file{/usr/src/include/defs.h} into 9573@file{/mnt/include/defs.h} by using the first rule. However, it would 9574use the second rule to rewrite @file{/usr/src/lib/foo.c} into 9575@file{/mnt/src/lib/foo.c}. 9576 9577 9578@item unset substitute-path [path] 9579@kindex unset substitute-path 9580If a path is specified, search the current list of substitution rules 9581for a rule that would rewrite that path. Delete that rule if found. 9582A warning is emitted by the debugger if no rule could be found. 9583 9584If no path is specified, then all substitution rules are deleted. 9585 9586@item show substitute-path [path] 9587@kindex show substitute-path 9588If a path is specified, then print the source path substitution rule 9589which would rewrite that path, if any. 9590 9591If no path is specified, then print all existing source path substitution 9592rules. 9593 9594@end table 9595 9596If your source path is cluttered with directories that are no longer of 9597interest, @value{GDBN} may sometimes cause confusion by finding the wrong 9598versions of source. You can correct the situation as follows: 9599 9600@enumerate 9601@item 9602Use @code{directory} with no argument to reset the source path to its default value. 9603 9604@item 9605Use @code{directory} with suitable arguments to reinstall the 9606directories you want in the source path. You can add all the 9607directories in one command. 9608@end enumerate 9609 9610@node Machine Code 9611@section Source and Machine Code 9612@cindex source line and its code address 9613 9614You can use the command @code{info line} to map source lines to program 9615addresses (and vice versa), and the command @code{disassemble} to display 9616a range of addresses as machine instructions. You can use the command 9617@code{set disassemble-next-line} to set whether to disassemble next 9618source line when execution stops. When run under @sc{gnu} Emacs 9619mode, the @code{info line} command causes the arrow to point to the 9620line specified. Also, @code{info line} prints addresses in symbolic form as 9621well as hex. 9622 9623@table @code 9624@kindex info line 9625@item info line 9626@itemx info line @var{location} 9627Print the starting and ending addresses of the compiled code for 9628source line @var{location}. You can specify source lines in any of 9629the ways documented in @ref{Specify Location}. With no @var{location} 9630information about the current source line is printed. 9631@end table 9632 9633For example, we can use @code{info line} to discover the location of 9634the object code for the first line of function 9635@code{m4_changequote}: 9636 9637@smallexample 9638(@value{GDBP}) info line m4_changequote 9639Line 895 of "builtin.c" starts at pc 0x634c <m4_changequote> and \ 9640 ends at 0x6350 <m4_changequote+4>. 9641@end smallexample 9642 9643@noindent 9644@cindex code address and its source line 9645We can also inquire (using @code{*@var{addr}} as the form for 9646@var{location}) what source line covers a particular address: 9647@smallexample 9648(@value{GDBP}) info line *0x63ff 9649Line 926 of "builtin.c" starts at pc 0x63e4 <m4_changequote+152> and \ 9650 ends at 0x6404 <m4_changequote+184>. 9651@end smallexample 9652 9653@cindex @code{$_} and @code{info line} 9654@cindex @code{x} command, default address 9655@kindex x@r{(examine), and} info line 9656After @code{info line}, the default address for the @code{x} command 9657is changed to the starting address of the line, so that @samp{x/i} is 9658sufficient to begin examining the machine code (@pxref{Memory, 9659,Examining Memory}). Also, this address is saved as the value of the 9660convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience 9661Variables}). 9662 9663@cindex info line, repeated calls 9664After @code{info line}, using @code{info line} again without 9665specifying a location will display information about the next source 9666line. 9667 9668@table @code 9669@kindex disassemble 9670@cindex assembly instructions 9671@cindex instructions, assembly 9672@cindex machine instructions 9673@cindex listing machine instructions 9674@item disassemble 9675@itemx disassemble /m 9676@itemx disassemble /s 9677@itemx disassemble /r 9678This specialized command dumps a range of memory as machine 9679instructions. It can also print mixed source+disassembly by specifying 9680the @code{/m} or @code{/s} modifier and print the raw instructions in hex 9681as well as in symbolic form by specifying the @code{/r} modifier. 9682The default memory range is the function surrounding the 9683program counter of the selected frame. A single argument to this 9684command is a program counter value; @value{GDBN} dumps the function 9685surrounding this value. When two arguments are given, they should 9686be separated by a comma, possibly surrounded by whitespace. The 9687arguments specify a range of addresses to dump, in one of two forms: 9688 9689@table @code 9690@item @var{start},@var{end} 9691the addresses from @var{start} (inclusive) to @var{end} (exclusive) 9692@item @var{start},+@var{length} 9693the addresses from @var{start} (inclusive) to 9694@code{@var{start}+@var{length}} (exclusive). 9695@end table 9696 9697@noindent 9698When 2 arguments are specified, the name of the function is also 9699printed (since there could be several functions in the given range). 9700 9701The argument(s) can be any expression yielding a numeric value, such as 9702@samp{0x32c4}, @samp{&main+10} or @samp{$pc - 8}. 9703 9704If the range of memory being disassembled contains current program counter, 9705the instruction at that location is shown with a @code{=>} marker. 9706@end table 9707 9708The following example shows the disassembly of a range of addresses of 9709HP PA-RISC 2.0 code: 9710 9711@smallexample 9712(@value{GDBP}) disas 0x32c4, 0x32e4 9713Dump of assembler code from 0x32c4 to 0x32e4: 9714 0x32c4 <main+204>: addil 0,dp 9715 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 9716 0x32cc <main+212>: ldil 0x3000,r31 9717 0x32d0 <main+216>: ble 0x3f8(sr4,r31) 9718 0x32d4 <main+220>: ldo 0(r31),rp 9719 0x32d8 <main+224>: addil -0x800,dp 9720 0x32dc <main+228>: ldo 0x588(r1),r26 9721 0x32e0 <main+232>: ldil 0x3000,r31 9722End of assembler dump. 9723@end smallexample 9724 9725Here is an example showing mixed source+assembly for Intel x86 9726with @code{/m} or @code{/s}, when the program is stopped just after 9727function prologue in a non-optimized function with no inline code. 9728 9729@smallexample 9730(@value{GDBP}) disas /m main 9731Dump of assembler code for function main: 97325 @{ 9733 0x08048330 <+0>: push %ebp 9734 0x08048331 <+1>: mov %esp,%ebp 9735 0x08048333 <+3>: sub $0x8,%esp 9736 0x08048336 <+6>: and $0xfffffff0,%esp 9737 0x08048339 <+9>: sub $0x10,%esp 9738 97396 printf ("Hello.\n"); 9740=> 0x0804833c <+12>: movl $0x8048440,(%esp) 9741 0x08048343 <+19>: call 0x8048284 <puts@@plt> 9742 97437 return 0; 97448 @} 9745 0x08048348 <+24>: mov $0x0,%eax 9746 0x0804834d <+29>: leave 9747 0x0804834e <+30>: ret 9748 9749End of assembler dump. 9750@end smallexample 9751 9752The @code{/m} option is deprecated as its output is not useful when 9753there is either inlined code or re-ordered code. 9754The @code{/s} option is the preferred choice. 9755Here is an example for AMD x86-64 showing the difference between 9756@code{/m} output and @code{/s} output. 9757This example has one inline function defined in a header file, 9758and the code is compiled with @samp{-O2} optimization. 9759Note how the @code{/m} output is missing the disassembly of 9760several instructions that are present in the @code{/s} output. 9761 9762@file{foo.h}: 9763 9764@smallexample 9765int 9766foo (int a) 9767@{ 9768 if (a < 0) 9769 return a * 2; 9770 if (a == 0) 9771 return 1; 9772 return a + 10; 9773@} 9774@end smallexample 9775 9776@file{foo.c}: 9777 9778@smallexample 9779#include "foo.h" 9780volatile int x, y; 9781int 9782main () 9783@{ 9784 x = foo (y); 9785 return 0; 9786@} 9787@end smallexample 9788 9789@smallexample 9790(@value{GDBP}) disas /m main 9791Dump of assembler code for function main: 97925 @{ 9793 97946 x = foo (y); 9795 0x0000000000400400 <+0>: mov 0x200c2e(%rip),%eax # 0x601034 <y> 9796 0x0000000000400417 <+23>: mov %eax,0x200c13(%rip) # 0x601030 <x> 9797 97987 return 0; 97998 @} 9800 0x000000000040041d <+29>: xor %eax,%eax 9801 0x000000000040041f <+31>: retq 9802 0x0000000000400420 <+32>: add %eax,%eax 9803 0x0000000000400422 <+34>: jmp 0x400417 <main+23> 9804 9805End of assembler dump. 9806(@value{GDBP}) disas /s main 9807Dump of assembler code for function main: 9808foo.c: 98095 @{ 98106 x = foo (y); 9811 0x0000000000400400 <+0>: mov 0x200c2e(%rip),%eax # 0x601034 <y> 9812 9813foo.h: 98144 if (a < 0) 9815 0x0000000000400406 <+6>: test %eax,%eax 9816 0x0000000000400408 <+8>: js 0x400420 <main+32> 9817 98186 if (a == 0) 98197 return 1; 98208 return a + 10; 9821 0x000000000040040a <+10>: lea 0xa(%rax),%edx 9822 0x000000000040040d <+13>: test %eax,%eax 9823 0x000000000040040f <+15>: mov $0x1,%eax 9824 0x0000000000400414 <+20>: cmovne %edx,%eax 9825 9826foo.c: 98276 x = foo (y); 9828 0x0000000000400417 <+23>: mov %eax,0x200c13(%rip) # 0x601030 <x> 9829 98307 return 0; 98318 @} 9832 0x000000000040041d <+29>: xor %eax,%eax 9833 0x000000000040041f <+31>: retq 9834 9835foo.h: 98365 return a * 2; 9837 0x0000000000400420 <+32>: add %eax,%eax 9838 0x0000000000400422 <+34>: jmp 0x400417 <main+23> 9839End of assembler dump. 9840@end smallexample 9841 9842Here is another example showing raw instructions in hex for AMD x86-64, 9843 9844@smallexample 9845(gdb) disas /r 0x400281,+10 9846Dump of assembler code from 0x400281 to 0x40028b: 9847 0x0000000000400281: 38 36 cmp %dh,(%rsi) 9848 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax 9849 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx) 9850 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al 9851End of assembler dump. 9852@end smallexample 9853 9854Addresses cannot be specified as a location (@pxref{Specify Location}). 9855So, for example, if you want to disassemble function @code{bar} 9856in file @file{foo.c}, you must type @samp{disassemble 'foo.c'::bar} 9857and not @samp{disassemble foo.c:bar}. 9858 9859Some architectures have more than one commonly-used set of instruction 9860mnemonics or other syntax. 9861 9862For programs that were dynamically linked and use shared libraries, 9863instructions that call functions or branch to locations in the shared 9864libraries might show a seemingly bogus location---it's actually a 9865location of the relocation table. On some architectures, @value{GDBN} 9866might be able to resolve these to actual function names. 9867 9868@table @code 9869@kindex set disassembler-options 9870@cindex disassembler options 9871@item set disassembler-options @var{option1}[,@var{option2}@dots{}] 9872This command controls the passing of target specific information to 9873the disassembler. For a list of valid options, please refer to the 9874@code{-M}/@code{--disassembler-options} section of the @samp{objdump} 9875manual and/or the output of @kbd{objdump --help} 9876(@pxref{objdump,,objdump,binutils,The GNU Binary Utilities}). 9877The default value is the empty string. 9878 9879If it is necessary to specify more than one disassembler option, then 9880multiple options can be placed together into a comma separated list. 9881Currently this command is only supported on targets ARC, ARM, MIPS, 9882PowerPC and S/390. 9883 9884@kindex show disassembler-options 9885@item show disassembler-options 9886Show the current setting of the disassembler options. 9887@end table 9888 9889@table @code 9890@kindex set disassembly-flavor 9891@cindex Intel disassembly flavor 9892@cindex AT&T disassembly flavor 9893@item set disassembly-flavor @var{instruction-set} 9894Select the instruction set to use when disassembling the 9895program via the @code{disassemble} or @code{x/i} commands. 9896 9897Currently this command is only defined for the Intel x86 family. You 9898can set @var{instruction-set} to either @code{intel} or @code{att}. 9899The default is @code{att}, the AT&T flavor used by default by Unix 9900assemblers for x86-based targets. 9901 9902@kindex show disassembly-flavor 9903@item show disassembly-flavor 9904Show the current setting of the disassembly flavor. 9905@end table 9906 9907@table @code 9908@kindex set disassemble-next-line 9909@kindex show disassemble-next-line 9910@item set disassemble-next-line 9911@itemx show disassemble-next-line 9912Control whether or not @value{GDBN} will disassemble the next source 9913line or instruction when execution stops. If ON, @value{GDBN} will 9914display disassembly of the next source line when execution of the 9915program being debugged stops. This is @emph{in addition} to 9916displaying the source line itself, which @value{GDBN} always does if 9917possible. If the next source line cannot be displayed for some reason 9918(e.g., if @value{GDBN} cannot find the source file, or there's no line 9919info in the debug info), @value{GDBN} will display disassembly of the 9920next @emph{instruction} instead of showing the next source line. If 9921AUTO, @value{GDBN} will display disassembly of next instruction only 9922if the source line cannot be displayed. This setting causes 9923@value{GDBN} to display some feedback when you step through a function 9924with no line info or whose source file is unavailable. The default is 9925OFF, which means never display the disassembly of the next line or 9926instruction. 9927@end table 9928 9929 9930@node Data 9931@chapter Examining Data 9932 9933@cindex printing data 9934@cindex examining data 9935@kindex print 9936@kindex inspect 9937The usual way to examine data in your program is with the @code{print} 9938command (abbreviated @code{p}), or its synonym @code{inspect}. It 9939evaluates and prints the value of an expression of the language your 9940program is written in (@pxref{Languages, ,Using @value{GDBN} with 9941Different Languages}). It may also print the expression using a 9942Python-based pretty-printer (@pxref{Pretty Printing}). 9943 9944@table @code 9945@item print [[@var{options}] --] @var{expr} 9946@itemx print [[@var{options}] --] /@var{f} @var{expr} 9947@var{expr} is an expression (in the source language). By default the 9948value of @var{expr} is printed in a format appropriate to its data type; 9949you can choose a different format by specifying @samp{/@var{f}}, where 9950@var{f} is a letter specifying the format; see @ref{Output Formats,,Output 9951Formats}. 9952 9953@anchor{print options} 9954The @code{print} command supports a number of options that allow 9955overriding relevant global print settings as set by @code{set print} 9956subcommands: 9957 9958@table @code 9959@item -address [@code{on}|@code{off}] 9960Set printing of addresses. 9961Related setting: @ref{set print address}. 9962 9963@item -array [@code{on}|@code{off}] 9964Pretty formatting of arrays. 9965Related setting: @ref{set print array}. 9966 9967@item -array-indexes [@code{on}|@code{off}] 9968Set printing of array indexes. 9969Related setting: @ref{set print array-indexes}. 9970 9971@item -elements @var{number-of-elements}|@code{unlimited} 9972Set limit on string chars or array elements to print. The value 9973@code{unlimited} causes there to be no limit. Related setting: 9974@ref{set print elements}. 9975 9976@item -max-depth @var{depth}|@code{unlimited} 9977Set the threshold after which nested structures are replaced with 9978ellipsis. Related setting: @ref{set print max-depth}. 9979 9980@item -null-stop [@code{on}|@code{off}] 9981Set printing of char arrays to stop at first null char. Related 9982setting: @ref{set print null-stop}. 9983 9984@item -object [@code{on}|@code{off}] 9985Set printing C@t{++} virtual function tables. Related setting: 9986@ref{set print object}. 9987 9988@item -pretty [@code{on}|@code{off}] 9989Set pretty formatting of structures. Related setting: @ref{set print 9990pretty}. 9991 9992@item -raw-values [@code{on}|@code{off}] 9993Set whether to print values in raw form, bypassing any 9994pretty-printers for that value. Related setting: @ref{set print 9995raw-values}. 9996 9997@item -repeats @var{number-of-repeats}|@code{unlimited} 9998Set threshold for repeated print elements. @code{unlimited} causes 9999all elements to be individually printed. Related setting: @ref{set 10000print repeats}. 10001 10002@item -static-members [@code{on}|@code{off}] 10003Set printing C@t{++} static members. Related setting: @ref{set print 10004static-members}. 10005 10006@item -symbol [@code{on}|@code{off}] 10007Set printing of symbol names when printing pointers. Related setting: 10008@ref{set print symbol}. 10009 10010@item -union [@code{on}|@code{off}] 10011Set printing of unions interior to structures. Related setting: 10012@ref{set print union}. 10013 10014@item -vtbl [@code{on}|@code{off}] 10015Set printing of C++ virtual function tables. Related setting: 10016@ref{set print vtbl}. 10017@end table 10018 10019Because the @code{print} command accepts arbitrary expressions which 10020may look like options (including abbreviations), if you specify any 10021command option, then you must use a double dash (@code{--}) to mark 10022the end of option processing. 10023 10024For example, this prints the value of the @code{-p} expression: 10025 10026@smallexample 10027(@value{GDBP}) print -p 10028@end smallexample 10029 10030While this repeats the last value in the value history (see below) 10031with the @code{-pretty} option in effect: 10032 10033@smallexample 10034(@value{GDBP}) print -p -- 10035@end smallexample 10036 10037Here is an example including both on option and an expression: 10038 10039@smallexample 10040@group 10041(@value{GDBP}) print -pretty -- *myptr 10042$1 = @{ 10043 next = 0x0, 10044 flags = @{ 10045 sweet = 1, 10046 sour = 1 10047 @}, 10048 meat = 0x54 "Pork" 10049@} 10050@end group 10051@end smallexample 10052 10053@item print [@var{options}] 10054@itemx print [@var{options}] /@var{f} 10055@cindex reprint the last value 10056If you omit @var{expr}, @value{GDBN} displays the last value again (from the 10057@dfn{value history}; @pxref{Value History, ,Value History}). This allows you to 10058conveniently inspect the same value in an alternative format. 10059@end table 10060 10061If the architecture supports memory tagging, the @code{print} command will 10062display pointer/memory tag mismatches if what is being printed is a pointer 10063or reference type. @xref{Memory Tagging}. 10064 10065A more low-level way of examining data is with the @code{x} command. 10066It examines data in memory at a specified address and prints it in a 10067specified format. @xref{Memory, ,Examining Memory}. 10068 10069If you are interested in information about types, or about how the 10070fields of a struct or a class are declared, use the @code{ptype @var{exp}} 10071command rather than @code{print}. @xref{Symbols, ,Examining the Symbol 10072Table}. 10073 10074@cindex exploring hierarchical data structures 10075@kindex explore 10076Another way of examining values of expressions and type information is 10077through the Python extension command @code{explore} (available only if 10078the @value{GDBN} build is configured with @code{--with-python}). It 10079offers an interactive way to start at the highest level (or, the most 10080abstract level) of the data type of an expression (or, the data type 10081itself) and explore all the way down to leaf scalar values/fields 10082embedded in the higher level data types. 10083 10084@table @code 10085@item explore @var{arg} 10086@var{arg} is either an expression (in the source language), or a type 10087visible in the current context of the program being debugged. 10088@end table 10089 10090The working of the @code{explore} command can be illustrated with an 10091example. If a data type @code{struct ComplexStruct} is defined in your 10092C program as 10093 10094@smallexample 10095struct SimpleStruct 10096@{ 10097 int i; 10098 double d; 10099@}; 10100 10101struct ComplexStruct 10102@{ 10103 struct SimpleStruct *ss_p; 10104 int arr[10]; 10105@}; 10106@end smallexample 10107 10108@noindent 10109followed by variable declarations as 10110 10111@smallexample 10112struct SimpleStruct ss = @{ 10, 1.11 @}; 10113struct ComplexStruct cs = @{ &ss, @{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 @} @}; 10114@end smallexample 10115 10116@noindent 10117then, the value of the variable @code{cs} can be explored using the 10118@code{explore} command as follows. 10119 10120@smallexample 10121(gdb) explore cs 10122The value of `cs' is a struct/class of type `struct ComplexStruct' with 10123the following fields: 10124 10125 ss_p = <Enter 0 to explore this field of type `struct SimpleStruct *'> 10126 arr = <Enter 1 to explore this field of type `int [10]'> 10127 10128Enter the field number of choice: 10129@end smallexample 10130 10131@noindent 10132Since the fields of @code{cs} are not scalar values, you are being 10133prompted to chose the field you want to explore. Let's say you choose 10134the field @code{ss_p} by entering @code{0}. Then, since this field is a 10135pointer, you will be asked if it is pointing to a single value. From 10136the declaration of @code{cs} above, it is indeed pointing to a single 10137value, hence you enter @code{y}. If you enter @code{n}, then you will 10138be asked if it were pointing to an array of values, in which case this 10139field will be explored as if it were an array. 10140 10141@smallexample 10142`cs.ss_p' is a pointer to a value of type `struct SimpleStruct' 10143Continue exploring it as a pointer to a single value [y/n]: y 10144The value of `*(cs.ss_p)' is a struct/class of type `struct 10145SimpleStruct' with the following fields: 10146 10147 i = 10 .. (Value of type `int') 10148 d = 1.1100000000000001 .. (Value of type `double') 10149 10150Press enter to return to parent value: 10151@end smallexample 10152 10153@noindent 10154If the field @code{arr} of @code{cs} was chosen for exploration by 10155entering @code{1} earlier, then since it is as array, you will be 10156prompted to enter the index of the element in the array that you want 10157to explore. 10158 10159@smallexample 10160`cs.arr' is an array of `int'. 10161Enter the index of the element you want to explore in `cs.arr': 5 10162 10163`(cs.arr)[5]' is a scalar value of type `int'. 10164 10165(cs.arr)[5] = 4 10166 10167Press enter to return to parent value: 10168@end smallexample 10169 10170In general, at any stage of exploration, you can go deeper towards the 10171leaf values by responding to the prompts appropriately, or hit the 10172return key to return to the enclosing data structure (the @i{higher} 10173level data structure). 10174 10175Similar to exploring values, you can use the @code{explore} command to 10176explore types. Instead of specifying a value (which is typically a 10177variable name or an expression valid in the current context of the 10178program being debugged), you specify a type name. If you consider the 10179same example as above, your can explore the type 10180@code{struct ComplexStruct} by passing the argument 10181@code{struct ComplexStruct} to the @code{explore} command. 10182 10183@smallexample 10184(gdb) explore struct ComplexStruct 10185@end smallexample 10186 10187@noindent 10188By responding to the prompts appropriately in the subsequent interactive 10189session, you can explore the type @code{struct ComplexStruct} in a 10190manner similar to how the value @code{cs} was explored in the above 10191example. 10192 10193The @code{explore} command also has two sub-commands, 10194@code{explore value} and @code{explore type}. The former sub-command is 10195a way to explicitly specify that value exploration of the argument is 10196being invoked, while the latter is a way to explicitly specify that type 10197exploration of the argument is being invoked. 10198 10199@table @code 10200@item explore value @var{expr} 10201@cindex explore value 10202This sub-command of @code{explore} explores the value of the 10203expression @var{expr} (if @var{expr} is an expression valid in the 10204current context of the program being debugged). The behavior of this 10205command is identical to that of the behavior of the @code{explore} 10206command being passed the argument @var{expr}. 10207 10208@item explore type @var{arg} 10209@cindex explore type 10210This sub-command of @code{explore} explores the type of @var{arg} (if 10211@var{arg} is a type visible in the current context of program being 10212debugged), or the type of the value/expression @var{arg} (if @var{arg} 10213is an expression valid in the current context of the program being 10214debugged). If @var{arg} is a type, then the behavior of this command is 10215identical to that of the @code{explore} command being passed the 10216argument @var{arg}. If @var{arg} is an expression, then the behavior of 10217this command will be identical to that of the @code{explore} command 10218being passed the type of @var{arg} as the argument. 10219@end table 10220 10221@menu 10222* Expressions:: Expressions 10223* Ambiguous Expressions:: Ambiguous Expressions 10224* Variables:: Program variables 10225* Arrays:: Artificial arrays 10226* Output Formats:: Output formats 10227* Memory:: Examining memory 10228* Memory Tagging:: Memory Tagging 10229* Auto Display:: Automatic display 10230* Print Settings:: Print settings 10231* Pretty Printing:: Python pretty printing 10232* Value History:: Value history 10233* Convenience Vars:: Convenience variables 10234* Convenience Funs:: Convenience functions 10235* Registers:: Registers 10236* Floating Point Hardware:: Floating point hardware 10237* Vector Unit:: Vector Unit 10238* OS Information:: Auxiliary data provided by operating system 10239* Memory Region Attributes:: Memory region attributes 10240* Dump/Restore Files:: Copy between memory and a file 10241* Core File Generation:: Cause a program dump its core 10242* Character Sets:: Debugging programs that use a different 10243 character set than GDB does 10244* Caching Target Data:: Data caching for targets 10245* Searching Memory:: Searching memory for a sequence of bytes 10246* Value Sizes:: Managing memory allocated for values 10247@end menu 10248 10249@node Expressions 10250@section Expressions 10251 10252@cindex expressions 10253@code{print} and many other @value{GDBN} commands accept an expression and 10254compute its value. Any kind of constant, variable or operator defined 10255by the programming language you are using is valid in an expression in 10256@value{GDBN}. This includes conditional expressions, function calls, 10257casts, and string constants. It also includes preprocessor macros, if 10258you compiled your program to include this information; see 10259@ref{Compilation}. 10260 10261@cindex arrays in expressions 10262@value{GDBN} supports array constants in expressions input by 10263the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example, 10264you can use the command @code{print @{1, 2, 3@}} to create an array 10265of three integers. If you pass an array to a function or assign it 10266to a program variable, @value{GDBN} copies the array to memory that 10267is @code{malloc}ed in the target program. 10268 10269Because C is so widespread, most of the expressions shown in examples in 10270this manual are in C. @xref{Languages, , Using @value{GDBN} with Different 10271Languages}, for information on how to use expressions in other 10272languages. 10273 10274In this section, we discuss operators that you can use in @value{GDBN} 10275expressions regardless of your programming language. 10276 10277@cindex casts, in expressions 10278Casts are supported in all languages, not just in C, because it is so 10279useful to cast a number into a pointer in order to examine a structure 10280at that address in memory. 10281@c FIXME: casts supported---Mod2 true? 10282 10283@value{GDBN} supports these operators, in addition to those common 10284to programming languages: 10285 10286@table @code 10287@item @@ 10288@samp{@@} is a binary operator for treating parts of memory as arrays. 10289@xref{Arrays, ,Artificial Arrays}, for more information. 10290 10291@item :: 10292@samp{::} allows you to specify a variable in terms of the file or 10293function where it is defined. @xref{Variables, ,Program Variables}. 10294 10295@cindex @{@var{type}@} 10296@cindex type casting memory 10297@cindex memory, viewing as typed object 10298@cindex casts, to view memory 10299@item @{@var{type}@} @var{addr} 10300Refers to an object of type @var{type} stored at address @var{addr} in 10301memory. The address @var{addr} may be any expression whose value is 10302an integer or pointer (but parentheses are required around binary 10303operators, just as in a cast). This construct is allowed regardless 10304of what kind of data is normally supposed to reside at @var{addr}. 10305@end table 10306 10307@node Ambiguous Expressions 10308@section Ambiguous Expressions 10309@cindex ambiguous expressions 10310 10311Expressions can sometimes contain some ambiguous elements. For instance, 10312some programming languages (notably Ada, C@t{++} and Objective-C) permit 10313a single function name to be defined several times, for application in 10314different contexts. This is called @dfn{overloading}. Another example 10315involving Ada is generics. A @dfn{generic package} is similar to C@t{++} 10316templates and is typically instantiated several times, resulting in 10317the same function name being defined in different contexts. 10318 10319In some cases and depending on the language, it is possible to adjust 10320the expression to remove the ambiguity. For instance in C@t{++}, you 10321can specify the signature of the function you want to break on, as in 10322@kbd{break @var{function}(@var{types})}. In Ada, using the fully 10323qualified name of your function often makes the expression unambiguous 10324as well. 10325 10326When an ambiguity that needs to be resolved is detected, the debugger 10327has the capability to display a menu of numbered choices for each 10328possibility, and then waits for the selection with the prompt @samp{>}. 10329The first option is always @samp{[0] cancel}, and typing @kbd{0 @key{RET}} 10330aborts the current command. If the command in which the expression was 10331used allows more than one choice to be selected, the next option in the 10332menu is @samp{[1] all}, and typing @kbd{1 @key{RET}} selects all possible 10333choices. 10334 10335For example, the following session excerpt shows an attempt to set a 10336breakpoint at the overloaded symbol @code{String::after}. 10337We choose three particular definitions of that function name: 10338 10339@c FIXME! This is likely to change to show arg type lists, at least 10340@smallexample 10341@group 10342(@value{GDBP}) b String::after 10343[0] cancel 10344[1] all 10345[2] file:String.cc; line number:867 10346[3] file:String.cc; line number:860 10347[4] file:String.cc; line number:875 10348[5] file:String.cc; line number:853 10349[6] file:String.cc; line number:846 10350[7] file:String.cc; line number:735 10351> 2 4 6 10352Breakpoint 1 at 0xb26c: file String.cc, line 867. 10353Breakpoint 2 at 0xb344: file String.cc, line 875. 10354Breakpoint 3 at 0xafcc: file String.cc, line 846. 10355Multiple breakpoints were set. 10356Use the "delete" command to delete unwanted 10357 breakpoints. 10358(@value{GDBP}) 10359@end group 10360@end smallexample 10361 10362@table @code 10363@kindex set multiple-symbols 10364@item set multiple-symbols @var{mode} 10365@cindex multiple-symbols menu 10366 10367This option allows you to adjust the debugger behavior when an expression 10368is ambiguous. 10369 10370By default, @var{mode} is set to @code{all}. If the command with which 10371the expression is used allows more than one choice, then @value{GDBN} 10372automatically selects all possible choices. For instance, inserting 10373a breakpoint on a function using an ambiguous name results in a breakpoint 10374inserted on each possible match. However, if a unique choice must be made, 10375then @value{GDBN} uses the menu to help you disambiguate the expression. 10376For instance, printing the address of an overloaded function will result 10377in the use of the menu. 10378 10379When @var{mode} is set to @code{ask}, the debugger always uses the menu 10380when an ambiguity is detected. 10381 10382Finally, when @var{mode} is set to @code{cancel}, the debugger reports 10383an error due to the ambiguity and the command is aborted. 10384 10385@kindex show multiple-symbols 10386@item show multiple-symbols 10387Show the current value of the @code{multiple-symbols} setting. 10388@end table 10389 10390@node Variables 10391@section Program Variables 10392 10393The most common kind of expression to use is the name of a variable 10394in your program. 10395 10396Variables in expressions are understood in the selected stack frame 10397(@pxref{Selection, ,Selecting a Frame}); they must be either: 10398 10399@itemize @bullet 10400@item 10401global (or file-static) 10402@end itemize 10403 10404@noindent or 10405 10406@itemize @bullet 10407@item 10408visible according to the scope rules of the 10409programming language from the point of execution in that frame 10410@end itemize 10411 10412@noindent This means that in the function 10413 10414@smallexample 10415foo (a) 10416 int a; 10417@{ 10418 bar (a); 10419 @{ 10420 int b = test (); 10421 bar (b); 10422 @} 10423@} 10424@end smallexample 10425 10426@noindent 10427you can examine and use the variable @code{a} whenever your program is 10428executing within the function @code{foo}, but you can only use or 10429examine the variable @code{b} while your program is executing inside 10430the block where @code{b} is declared. 10431 10432@cindex variable name conflict 10433There is an exception: you can refer to a variable or function whose 10434scope is a single source file even if the current execution point is not 10435in this file. But it is possible to have more than one such variable or 10436function with the same name (in different source files). If that 10437happens, referring to that name has unpredictable effects. If you wish, 10438you can specify a static variable in a particular function or file by 10439using the colon-colon (@code{::}) notation: 10440 10441@cindex colon-colon, context for variables/functions 10442@ifnotinfo 10443@c info cannot cope with a :: index entry, but why deprive hard copy readers? 10444@cindex @code{::}, context for variables/functions 10445@end ifnotinfo 10446@smallexample 10447@var{file}::@var{variable} 10448@var{function}::@var{variable} 10449@end smallexample 10450 10451@noindent 10452Here @var{file} or @var{function} is the name of the context for the 10453static @var{variable}. In the case of file names, you can use quotes to 10454make sure @value{GDBN} parses the file name as a single word---for example, 10455to print a global value of @code{x} defined in @file{f2.c}: 10456 10457@smallexample 10458(@value{GDBP}) p 'f2.c'::x 10459@end smallexample 10460 10461The @code{::} notation is normally used for referring to 10462static variables, since you typically disambiguate uses of local variables 10463in functions by selecting the appropriate frame and using the 10464simple name of the variable. However, you may also use this notation 10465to refer to local variables in frames enclosing the selected frame: 10466 10467@smallexample 10468void 10469foo (int a) 10470@{ 10471 if (a < 10) 10472 bar (a); 10473 else 10474 process (a); /* Stop here */ 10475@} 10476 10477int 10478bar (int a) 10479@{ 10480 foo (a + 5); 10481@} 10482@end smallexample 10483 10484@noindent 10485For example, if there is a breakpoint at the commented line, 10486here is what you might see 10487when the program stops after executing the call @code{bar(0)}: 10488 10489@smallexample 10490(@value{GDBP}) p a 10491$1 = 10 10492(@value{GDBP}) p bar::a 10493$2 = 5 10494(@value{GDBP}) up 2 10495#2 0x080483d0 in foo (a=5) at foobar.c:12 10496(@value{GDBP}) p a 10497$3 = 5 10498(@value{GDBP}) p bar::a 10499$4 = 0 10500@end smallexample 10501 10502@cindex C@t{++} scope resolution 10503These uses of @samp{::} are very rarely in conflict with the very 10504similar use of the same notation in C@t{++}. When they are in 10505conflict, the C@t{++} meaning takes precedence; however, this can be 10506overridden by quoting the file or function name with single quotes. 10507 10508For example, suppose the program is stopped in a method of a class 10509that has a field named @code{includefile}, and there is also an 10510include file named @file{includefile} that defines a variable, 10511@code{some_global}. 10512 10513@smallexample 10514(@value{GDBP}) p includefile 10515$1 = 23 10516(@value{GDBP}) p includefile::some_global 10517A syntax error in expression, near `'. 10518(@value{GDBP}) p 'includefile'::some_global 10519$2 = 27 10520@end smallexample 10521 10522@cindex wrong values 10523@cindex variable values, wrong 10524@cindex function entry/exit, wrong values of variables 10525@cindex optimized code, wrong values of variables 10526@quotation 10527@emph{Warning:} Occasionally, a local variable may appear to have the 10528wrong value at certain points in a function---just after entry to a new 10529scope, and just before exit. 10530@end quotation 10531You may see this problem when you are stepping by machine instructions. 10532This is because, on most machines, it takes more than one instruction to 10533set up a stack frame (including local variable definitions); if you are 10534stepping by machine instructions, variables may appear to have the wrong 10535values until the stack frame is completely built. On exit, it usually 10536also takes more than one machine instruction to destroy a stack frame; 10537after you begin stepping through that group of instructions, local 10538variable definitions may be gone. 10539 10540This may also happen when the compiler does significant optimizations. 10541To be sure of always seeing accurate values, turn off all optimization 10542when compiling. 10543 10544@cindex ``No symbol "foo" in current context'' 10545Another possible effect of compiler optimizations is to optimize 10546unused variables out of existence, or assign variables to registers (as 10547opposed to memory addresses). Depending on the support for such cases 10548offered by the debug info format used by the compiler, @value{GDBN} 10549might not be able to display values for such local variables. If that 10550happens, @value{GDBN} will print a message like this: 10551 10552@smallexample 10553No symbol "foo" in current context. 10554@end smallexample 10555 10556To solve such problems, either recompile without optimizations, or use a 10557different debug info format, if the compiler supports several such 10558formats. @xref{Compilation}, for more information on choosing compiler 10559options. @xref{C, ,C and C@t{++}}, for more information about debug 10560info formats that are best suited to C@t{++} programs. 10561 10562If you ask to print an object whose contents are unknown to 10563@value{GDBN}, e.g., because its data type is not completely specified 10564by the debug information, @value{GDBN} will say @samp{<incomplete 10565type>}. @xref{Symbols, incomplete type}, for more about this. 10566 10567@cindex no debug info variables 10568If you try to examine or use the value of a (global) variable for 10569which @value{GDBN} has no type information, e.g., because the program 10570includes no debug information, @value{GDBN} displays an error message. 10571@xref{Symbols, unknown type}, for more about unknown types. If you 10572cast the variable to its declared type, @value{GDBN} gets the 10573variable's value using the cast-to type as the variable's type. For 10574example, in a C program: 10575 10576@smallexample 10577 (@value{GDBP}) p var 10578 'var' has unknown type; cast it to its declared type 10579 (@value{GDBP}) p (float) var 10580 $1 = 3.14 10581@end smallexample 10582 10583If you append @kbd{@@entry} string to a function parameter name you get its 10584value at the time the function got called. If the value is not available an 10585error message is printed. Entry values are available only with some compilers. 10586Entry values are normally also printed at the function parameter list according 10587to @ref{set print entry-values}. 10588 10589@smallexample 10590Breakpoint 1, d (i=30) at gdb.base/entry-value.c:29 1059129 i++; 10592(gdb) next 1059330 e (i); 10594(gdb) print i 10595$1 = 31 10596(gdb) print i@@entry 10597$2 = 30 10598@end smallexample 10599 10600Strings are identified as arrays of @code{char} values without specified 10601signedness. Arrays of either @code{signed char} or @code{unsigned char} get 10602printed as arrays of 1 byte sized integers. @code{-fsigned-char} or 10603@code{-funsigned-char} @value{NGCC} options have no effect as @value{GDBN} 10604defines literal string type @code{"char"} as @code{char} without a sign. 10605For program code 10606 10607@smallexample 10608char var0[] = "A"; 10609signed char var1[] = "A"; 10610@end smallexample 10611 10612You get during debugging 10613@smallexample 10614(gdb) print var0 10615$1 = "A" 10616(gdb) print var1 10617$2 = @{65 'A', 0 '\0'@} 10618@end smallexample 10619 10620@node Arrays 10621@section Artificial Arrays 10622 10623@cindex artificial array 10624@cindex arrays 10625@kindex @@@r{, referencing memory as an array} 10626It is often useful to print out several successive objects of the 10627same type in memory; a section of an array, or an array of 10628dynamically determined size for which only a pointer exists in the 10629program. 10630 10631You can do this by referring to a contiguous span of memory as an 10632@dfn{artificial array}, using the binary operator @samp{@@}. The left 10633operand of @samp{@@} should be the first element of the desired array 10634and be an individual object. The right operand should be the desired length 10635of the array. The result is an array value whose elements are all of 10636the type of the left argument. The first element is actually the left 10637argument; the second element comes from bytes of memory immediately 10638following those that hold the first element, and so on. Here is an 10639example. If a program says 10640 10641@smallexample 10642int *array = (int *) malloc (len * sizeof (int)); 10643@end smallexample 10644 10645@noindent 10646you can print the contents of @code{array} with 10647 10648@smallexample 10649p *array@@len 10650@end smallexample 10651 10652The left operand of @samp{@@} must reside in memory. Array values made 10653with @samp{@@} in this way behave just like other arrays in terms of 10654subscripting, and are coerced to pointers when used in expressions. 10655Artificial arrays most often appear in expressions via the value history 10656(@pxref{Value History, ,Value History}), after printing one out. 10657 10658Another way to create an artificial array is to use a cast. 10659This re-interprets a value as if it were an array. 10660The value need not be in memory: 10661@smallexample 10662(@value{GDBP}) p/x (short[2])0x12345678 10663$1 = @{0x1234, 0x5678@} 10664@end smallexample 10665 10666As a convenience, if you leave the array length out (as in 10667@samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill 10668the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}: 10669@smallexample 10670(@value{GDBP}) p/x (short[])0x12345678 10671$2 = @{0x1234, 0x5678@} 10672@end smallexample 10673 10674Sometimes the artificial array mechanism is not quite enough; in 10675moderately complex data structures, the elements of interest may not 10676actually be adjacent---for example, if you are interested in the values 10677of pointers in an array. One useful work-around in this situation is 10678to use a convenience variable (@pxref{Convenience Vars, ,Convenience 10679Variables}) as a counter in an expression that prints the first 10680interesting value, and then repeat that expression via @key{RET}. For 10681instance, suppose you have an array @code{dtab} of pointers to 10682structures, and you are interested in the values of a field @code{fv} 10683in each structure. Here is an example of what you might type: 10684 10685@smallexample 10686set $i = 0 10687p dtab[$i++]->fv 10688@key{RET} 10689@key{RET} 10690@dots{} 10691@end smallexample 10692 10693@node Output Formats 10694@section Output Formats 10695 10696@cindex formatted output 10697@cindex output formats 10698By default, @value{GDBN} prints a value according to its data type. Sometimes 10699this is not what you want. For example, you might want to print a number 10700in hex, or a pointer in decimal. Or you might want to view data in memory 10701at a certain address as a character string or as an instruction. To do 10702these things, specify an @dfn{output format} when you print a value. 10703 10704The simplest use of output formats is to say how to print a value 10705already computed. This is done by starting the arguments of the 10706@code{print} command with a slash and a format letter. The format 10707letters supported are: 10708 10709@table @code 10710@item x 10711Regard the bits of the value as an integer, and print the integer in 10712hexadecimal. 10713 10714@item d 10715Print as integer in signed decimal. 10716 10717@item u 10718Print as integer in unsigned decimal. 10719 10720@item o 10721Print as integer in octal. 10722 10723@item t 10724Print as integer in binary. The letter @samp{t} stands for ``two''. 10725@footnote{@samp{b} cannot be used because these format letters are also 10726used with the @code{x} command, where @samp{b} stands for ``byte''; 10727see @ref{Memory,,Examining Memory}.} 10728 10729@item a 10730@cindex unknown address, locating 10731@cindex locate address 10732Print as an address, both absolute in hexadecimal and as an offset from 10733the nearest preceding symbol. You can use this format used to discover 10734where (in what function) an unknown address is located: 10735 10736@smallexample 10737(@value{GDBP}) p/a 0x54320 10738$3 = 0x54320 <_initialize_vx+396> 10739@end smallexample 10740 10741@noindent 10742The command @code{info symbol 0x54320} yields similar results. 10743@xref{Symbols, info symbol}. 10744 10745@item c 10746Regard as an integer and print it as a character constant. This 10747prints both the numerical value and its character representation. The 10748character representation is replaced with the octal escape @samp{\nnn} 10749for characters outside the 7-bit @sc{ascii} range. 10750 10751Without this format, @value{GDBN} displays @code{char}, 10752@w{@code{unsigned char}}, and @w{@code{signed char}} data as character 10753constants. Single-byte members of vectors are displayed as integer 10754data. 10755 10756@item f 10757Regard the bits of the value as a floating point number and print 10758using typical floating point syntax. 10759 10760@item s 10761@cindex printing strings 10762@cindex printing byte arrays 10763Regard as a string, if possible. With this format, pointers to single-byte 10764data are displayed as null-terminated strings and arrays of single-byte data 10765are displayed as fixed-length strings. Other values are displayed in their 10766natural types. 10767 10768Without this format, @value{GDBN} displays pointers to and arrays of 10769@code{char}, @w{@code{unsigned char}}, and @w{@code{signed char}} as 10770strings. Single-byte members of a vector are displayed as an integer 10771array. 10772 10773@item z 10774Like @samp{x} formatting, the value is treated as an integer and 10775printed as hexadecimal, but leading zeros are printed to pad the value 10776to the size of the integer type. 10777 10778@item r 10779@cindex raw printing 10780Print using the @samp{raw} formatting. By default, @value{GDBN} will 10781use a Python-based pretty-printer, if one is available (@pxref{Pretty 10782Printing}). This typically results in a higher-level display of the 10783value's contents. The @samp{r} format bypasses any Python 10784pretty-printer which might exist. 10785@end table 10786 10787For example, to print the program counter in hex (@pxref{Registers}), type 10788 10789@smallexample 10790p/x $pc 10791@end smallexample 10792 10793@noindent 10794Note that no space is required before the slash; this is because command 10795names in @value{GDBN} cannot contain a slash. 10796 10797To reprint the last value in the value history with a different format, 10798you can use the @code{print} command with just a format and no 10799expression. For example, @samp{p/x} reprints the last value in hex. 10800 10801@node Memory 10802@section Examining Memory 10803 10804You can use the command @code{x} (for ``examine'') to examine memory in 10805any of several formats, independently of your program's data types. 10806 10807@cindex examining memory 10808@table @code 10809@kindex x @r{(examine memory)} 10810@item x/@var{nfu} @var{addr} 10811@itemx x @var{addr} 10812@itemx x 10813Use the @code{x} command to examine memory. 10814@end table 10815 10816@var{n}, @var{f}, and @var{u} are all optional parameters that specify how 10817much memory to display and how to format it; @var{addr} is an 10818expression giving the address where you want to start displaying memory. 10819If you use defaults for @var{nfu}, you need not type the slash @samp{/}. 10820Several commands set convenient defaults for @var{addr}. 10821 10822@table @r 10823@item @var{n}, the repeat count 10824The repeat count is a decimal integer; the default is 1. It specifies 10825how much memory (counting by units @var{u}) to display. If a negative 10826number is specified, memory is examined backward from @var{addr}. 10827@c This really is **decimal**; unaffected by 'set radix' as of GDB 10828@c 4.1.2. 10829 10830@item @var{f}, the display format 10831The display format is one of the formats used by @code{print} 10832(@samp{x}, @samp{d}, @samp{u}, @samp{o}, @samp{t}, @samp{a}, @samp{c}, 10833@samp{f}, @samp{s}), @samp{i} (for machine instructions) and 10834@samp{m} (for displaying memory tags). 10835The default is @samp{x} (hexadecimal) initially. The default changes 10836each time you use either @code{x} or @code{print}. 10837 10838@item @var{u}, the unit size 10839The unit size is any of 10840 10841@table @code 10842@item b 10843Bytes. 10844@item h 10845Halfwords (two bytes). 10846@item w 10847Words (four bytes). This is the initial default. 10848@item g 10849Giant words (eight bytes). 10850@end table 10851 10852Each time you specify a unit size with @code{x}, that size becomes the 10853default unit the next time you use @code{x}. For the @samp{i} format, 10854the unit size is ignored and is normally not written. For the @samp{s} format, 10855the unit size defaults to @samp{b}, unless it is explicitly given. 10856Use @kbd{x /hs} to display 16-bit char strings and @kbd{x /ws} to display 1085732-bit strings. The next use of @kbd{x /s} will again display 8-bit strings. 10858Note that the results depend on the programming language of the 10859current compilation unit. If the language is C, the @samp{s} 10860modifier will use the UTF-16 encoding while @samp{w} will use 10861UTF-32. The encoding is set by the programming language and cannot 10862be altered. 10863 10864@item @var{addr}, starting display address 10865@var{addr} is the address where you want @value{GDBN} to begin displaying 10866memory. The expression need not have a pointer value (though it may); 10867it is always interpreted as an integer address of a byte of memory. 10868@xref{Expressions, ,Expressions}, for more information on expressions. The default for 10869@var{addr} is usually just after the last address examined---but several 10870other commands also set the default address: @code{info breakpoints} (to 10871the address of the last breakpoint listed), @code{info line} (to the 10872starting address of a line), and @code{print} (if you use it to display 10873a value from memory). 10874@end table 10875 10876For example, @samp{x/3uh 0x54320} is a request to display three halfwords 10877(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}), 10878starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four 10879words (@samp{w}) of memory above the stack pointer (here, @samp{$sp}; 10880@pxref{Registers, ,Registers}) in hexadecimal (@samp{x}). 10881 10882You can also specify a negative repeat count to examine memory backward 10883from the given address. For example, @samp{x/-3uh 0x54320} prints three 10884halfwords (@code{h}) at @code{0x54314}, @code{0x54328}, and @code{0x5431c}. 10885 10886Since the letters indicating unit sizes are all distinct from the 10887letters specifying output formats, you do not have to remember whether 10888unit size or format comes first; either order works. The output 10889specifications @samp{4xw} and @samp{4wx} mean exactly the same thing. 10890(However, the count @var{n} must come first; @samp{wx4} does not work.) 10891 10892Even though the unit size @var{u} is ignored for the formats @samp{s} 10893and @samp{i}, you might still want to use a count @var{n}; for example, 10894@samp{3i} specifies that you want to see three machine instructions, 10895including any operands. For convenience, especially when used with 10896the @code{display} command, the @samp{i} format also prints branch delay 10897slot instructions, if any, beyond the count specified, which immediately 10898follow the last instruction that is within the count. The command 10899@code{disassemble} gives an alternative way of inspecting machine 10900instructions; see @ref{Machine Code,,Source and Machine Code}. 10901 10902If a negative repeat count is specified for the formats @samp{s} or @samp{i}, 10903the command displays null-terminated strings or instructions before the given 10904address as many as the absolute value of the given number. For the @samp{i} 10905format, we use line number information in the debug info to accurately locate 10906instruction boundaries while disassembling backward. If line info is not 10907available, the command stops examining memory with an error message. 10908 10909All the defaults for the arguments to @code{x} are designed to make it 10910easy to continue scanning memory with minimal specifications each time 10911you use @code{x}. For example, after you have inspected three machine 10912instructions with @samp{x/3i @var{addr}}, you can inspect the next seven 10913with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command, 10914the repeat count @var{n} is used again; the other arguments default as 10915for successive uses of @code{x}. 10916 10917When examining machine instructions, the instruction at current program 10918counter is shown with a @code{=>} marker. For example: 10919 10920@smallexample 10921(@value{GDBP}) x/5i $pc-6 10922 0x804837f <main+11>: mov %esp,%ebp 10923 0x8048381 <main+13>: push %ecx 10924 0x8048382 <main+14>: sub $0x4,%esp 10925=> 0x8048385 <main+17>: movl $0x8048460,(%esp) 10926 0x804838c <main+24>: call 0x80482d4 <puts@@plt> 10927@end smallexample 10928 10929If the architecture supports memory tagging, the tags can be displayed by 10930using @samp{m}. @xref{Memory Tagging}. 10931 10932The information will be displayed once per granule size 10933(the amount of bytes a particular memory tag covers). For example, AArch64 10934has a granule size of 16 bytes, so it will display a tag every 16 bytes. 10935 10936Due to the way @value{GDBN} prints information with the @code{x} command (not 10937aligned to a particular boundary), the tag information will refer to the 10938initial address displayed on a particular line. If a memory tag boundary 10939is crossed in the middle of a line displayed by the @code{x} command, it 10940will be displayed on the next line. 10941 10942The @samp{m} format doesn't affect any other specified formats that were 10943passed to the @code{x} command. 10944 10945@cindex @code{$_}, @code{$__}, and value history 10946The addresses and contents printed by the @code{x} command are not saved 10947in the value history because there is often too much of them and they 10948would get in the way. Instead, @value{GDBN} makes these values available for 10949subsequent use in expressions as values of the convenience variables 10950@code{$_} and @code{$__}. After an @code{x} command, the last address 10951examined is available for use in expressions in the convenience variable 10952@code{$_}. The contents of that address, as examined, are available in 10953the convenience variable @code{$__}. 10954 10955If the @code{x} command has a repeat count, the address and contents saved 10956are from the last memory unit printed; this is not the same as the last 10957address printed if several units were printed on the last line of output. 10958 10959@anchor{addressable memory unit} 10960@cindex addressable memory unit 10961Most targets have an addressable memory unit size of 8 bits. This means 10962that to each memory address are associated 8 bits of data. Some 10963targets, however, have other addressable memory unit sizes. 10964Within @value{GDBN} and this document, the term 10965@dfn{addressable memory unit} (or @dfn{memory unit} for short) is used 10966when explicitly referring to a chunk of data of that size. The word 10967@dfn{byte} is used to refer to a chunk of data of 8 bits, regardless of 10968the addressable memory unit size of the target. For most systems, 10969addressable memory unit is a synonym of byte. 10970 10971@cindex remote memory comparison 10972@cindex target memory comparison 10973@cindex verify remote memory image 10974@cindex verify target memory image 10975When you are debugging a program running on a remote target machine 10976(@pxref{Remote Debugging}), you may wish to verify the program's image 10977in the remote machine's memory against the executable file you 10978downloaded to the target. Or, on any target, you may want to check 10979whether the program has corrupted its own read-only sections. The 10980@code{compare-sections} command is provided for such situations. 10981 10982@table @code 10983@kindex compare-sections 10984@item compare-sections @r{[}@var{section-name}@r{|}@code{-r}@r{]} 10985Compare the data of a loadable section @var{section-name} in the 10986executable file of the program being debugged with the same section in 10987the target machine's memory, and report any mismatches. With no 10988arguments, compares all loadable sections. With an argument of 10989@code{-r}, compares all loadable read-only sections. 10990 10991Note: for remote targets, this command can be accelerated if the 10992target supports computing the CRC checksum of a block of memory 10993(@pxref{qCRC packet}). 10994@end table 10995 10996@node Memory Tagging 10997@section Memory Tagging 10998 10999Memory tagging is a memory protection technology that uses a pair of tags to 11000validate memory accesses through pointers. The tags are integer values 11001usually comprised of a few bits, depending on the architecture. 11002 11003There are two types of tags that are used in this setup: logical and 11004allocation. A logical tag is stored in the pointers themselves, usually at the 11005higher bits of the pointers. An allocation tag is the tag associated 11006with particular ranges of memory in the physical address space, against which 11007the logical tags from pointers are compared. 11008 11009The pointer tag (logical tag) must match the memory tag (allocation tag) 11010for the memory access to be valid. If the logical tag does not match the 11011allocation tag, that will raise a memory violation. 11012 11013Allocation tags cover multiple contiguous bytes of physical memory. This 11014range of bytes is called a memory tag granule and is architecture-specific. 11015For example, AArch64 has a tag granule of 16 bytes, meaning each allocation 11016tag spans 16 bytes of memory. 11017 11018If the underlying architecture supports memory tagging, like AArch64 MTE 11019or SPARC ADI do, @value{GDBN} can make use of it to validate pointers 11020against memory allocation tags. 11021 11022The @code{print} (@pxref{Data}) and @code{x} (@pxref{Memory}) commands will 11023display tag information when appropriate, and a command prefix of 11024@code{memory-tag} gives access to the various memory tagging commands. 11025 11026The @code{memory-tag} commands are the following: 11027 11028@table @code 11029@kindex memory-tag print-logical-tag 11030@item memory-tag print-logical-tag @var{pointer_expression} 11031Print the logical tag stored in @var{pointer_expression}. 11032@kindex memory-tag with-logical-tag 11033@item memory-tag with-logical-tag @var{pointer_expression} @var{tag_bytes} 11034Print the pointer given by @var{pointer_expression}, augmented with a logical 11035tag of @var{tag_bytes}. 11036@kindex memory-tag print-allocation-tag 11037@item memory-tag print-allocation-tag @var{address_expression} 11038Print the allocation tag associated with the memory address given by 11039@var{address_expression}. 11040@kindex memory-tag setatag 11041@item memory-tag setatag @var{starting_address} @var{length} @var{tag_bytes} 11042Set the allocation tag(s) for memory range @r{[}@var{starting_address}, 11043@var{starting_address} + @var{length}@r{)} to @var{tag_bytes}. 11044@kindex memory-tag check 11045@item memory-tag check @var{pointer_expression} 11046Check if the logical tag in the pointer given by @var{pointer_expression} 11047matches the allocation tag for the memory referenced by the pointer. 11048 11049This essentially emulates the hardware validation that is done when tagged 11050memory is accessed through a pointer, but does not cause a memory fault as 11051it would during hardware validation. 11052 11053It can be used to inspect potential memory tagging violations in the running 11054process, before any faults get triggered. 11055@end table 11056 11057@node Auto Display 11058@section Automatic Display 11059@cindex automatic display 11060@cindex display of expressions 11061 11062If you find that you want to print the value of an expression frequently 11063(to see how it changes), you might want to add it to the @dfn{automatic 11064display list} so that @value{GDBN} prints its value each time your program stops. 11065Each expression added to the list is given a number to identify it; 11066to remove an expression from the list, you specify that number. 11067The automatic display looks like this: 11068 11069@smallexample 110702: foo = 38 110713: bar[5] = (struct hack *) 0x3804 11072@end smallexample 11073 11074@noindent 11075This display shows item numbers, expressions and their current values. As with 11076displays you request manually using @code{x} or @code{print}, you can 11077specify the output format you prefer; in fact, @code{display} decides 11078whether to use @code{print} or @code{x} depending your format 11079specification---it uses @code{x} if you specify either the @samp{i} 11080or @samp{s} format, or a unit size; otherwise it uses @code{print}. 11081 11082@table @code 11083@kindex display 11084@item display @var{expr} 11085Add the expression @var{expr} to the list of expressions to display 11086each time your program stops. @xref{Expressions, ,Expressions}. 11087 11088@code{display} does not repeat if you press @key{RET} again after using it. 11089 11090@item display/@var{fmt} @var{expr} 11091For @var{fmt} specifying only a display format and not a size or 11092count, add the expression @var{expr} to the auto-display list but 11093arrange to display it each time in the specified format @var{fmt}. 11094@xref{Output Formats,,Output Formats}. 11095 11096@item display/@var{fmt} @var{addr} 11097For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a 11098number of units, add the expression @var{addr} as a memory address to 11099be examined each time your program stops. Examining means in effect 11100doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining Memory}. 11101@end table 11102 11103For example, @samp{display/i $pc} can be helpful, to see the machine 11104instruction about to be executed each time execution stops (@samp{$pc} 11105is a common name for the program counter; @pxref{Registers, ,Registers}). 11106 11107@table @code 11108@kindex delete display 11109@kindex undisplay 11110@item undisplay @var{dnums}@dots{} 11111@itemx delete display @var{dnums}@dots{} 11112Remove items from the list of expressions to display. Specify the 11113numbers of the displays that you want affected with the command 11114argument @var{dnums}. It can be a single display number, one of the 11115numbers shown in the first field of the @samp{info display} display; 11116or it could be a range of display numbers, as in @code{2-4}. 11117 11118@code{undisplay} does not repeat if you press @key{RET} after using it. 11119(Otherwise you would just get the error @samp{No display number @dots{}}.) 11120 11121@kindex disable display 11122@item disable display @var{dnums}@dots{} 11123Disable the display of item numbers @var{dnums}. A disabled display 11124item is not printed automatically, but is not forgotten. It may be 11125enabled again later. Specify the numbers of the displays that you 11126want affected with the command argument @var{dnums}. It can be a 11127single display number, one of the numbers shown in the first field of 11128the @samp{info display} display; or it could be a range of display 11129numbers, as in @code{2-4}. 11130 11131@kindex enable display 11132@item enable display @var{dnums}@dots{} 11133Enable display of item numbers @var{dnums}. It becomes effective once 11134again in auto display of its expression, until you specify otherwise. 11135Specify the numbers of the displays that you want affected with the 11136command argument @var{dnums}. It can be a single display number, one 11137of the numbers shown in the first field of the @samp{info display} 11138display; or it could be a range of display numbers, as in @code{2-4}. 11139 11140@item display 11141Display the current values of the expressions on the list, just as is 11142done when your program stops. 11143 11144@kindex info display 11145@item info display 11146Print the list of expressions previously set up to display 11147automatically, each one with its item number, but without showing the 11148values. This includes disabled expressions, which are marked as such. 11149It also includes expressions which would not be displayed right now 11150because they refer to automatic variables not currently available. 11151@end table 11152 11153@cindex display disabled out of scope 11154If a display expression refers to local variables, then it does not make 11155sense outside the lexical context for which it was set up. Such an 11156expression is disabled when execution enters a context where one of its 11157variables is not defined. For example, if you give the command 11158@code{display last_char} while inside a function with an argument 11159@code{last_char}, @value{GDBN} displays this argument while your program 11160continues to stop inside that function. When it stops elsewhere---where 11161there is no variable @code{last_char}---the display is disabled 11162automatically. The next time your program stops where @code{last_char} 11163is meaningful, you can enable the display expression once again. 11164 11165@node Print Settings 11166@section Print Settings 11167 11168@cindex format options 11169@cindex print settings 11170@value{GDBN} provides the following ways to control how arrays, structures, 11171and symbols are printed. 11172 11173@noindent 11174These settings are useful for debugging programs in any language: 11175 11176@table @code 11177@kindex set print 11178@anchor{set print address} 11179@item set print address 11180@itemx set print address on 11181@cindex print/don't print memory addresses 11182@value{GDBN} prints memory addresses showing the location of stack 11183traces, structure values, pointer values, breakpoints, and so forth, 11184even when it also displays the contents of those addresses. The default 11185is @code{on}. For example, this is what a stack frame display looks like with 11186@code{set print address on}: 11187 11188@smallexample 11189@group 11190(@value{GDBP}) f 11191#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") 11192 at input.c:530 11193530 if (lquote != def_lquote) 11194@end group 11195@end smallexample 11196 11197@item set print address off 11198Do not print addresses when displaying their contents. For example, 11199this is the same stack frame displayed with @code{set print address off}: 11200 11201@smallexample 11202@group 11203(@value{GDBP}) set print addr off 11204(@value{GDBP}) f 11205#0 set_quotes (lq="<<", rq=">>") at input.c:530 11206530 if (lquote != def_lquote) 11207@end group 11208@end smallexample 11209 11210You can use @samp{set print address off} to eliminate all machine 11211dependent displays from the @value{GDBN} interface. For example, with 11212@code{print address off}, you should get the same text for backtraces on 11213all machines---whether or not they involve pointer arguments. 11214 11215@kindex show print 11216@item show print address 11217Show whether or not addresses are to be printed. 11218@end table 11219 11220When @value{GDBN} prints a symbolic address, it normally prints the 11221closest earlier symbol plus an offset. If that symbol does not uniquely 11222identify the address (for example, it is a name whose scope is a single 11223source file), you may need to clarify. One way to do this is with 11224@code{info line}, for example @samp{info line *0x4537}. Alternately, 11225you can set @value{GDBN} to print the source file and line number when 11226it prints a symbolic address: 11227 11228@table @code 11229@item set print symbol-filename on 11230@cindex source file and line of a symbol 11231@cindex symbol, source file and line 11232Tell @value{GDBN} to print the source file name and line number of a 11233symbol in the symbolic form of an address. 11234 11235@item set print symbol-filename off 11236Do not print source file name and line number of a symbol. This is the 11237default. 11238 11239@item show print symbol-filename 11240Show whether or not @value{GDBN} will print the source file name and 11241line number of a symbol in the symbolic form of an address. 11242@end table 11243 11244Another situation where it is helpful to show symbol filenames and line 11245numbers is when disassembling code; @value{GDBN} shows you the line 11246number and source file that corresponds to each instruction. 11247 11248Also, you may wish to see the symbolic form only if the address being 11249printed is reasonably close to the closest earlier symbol: 11250 11251@table @code 11252@item set print max-symbolic-offset @var{max-offset} 11253@itemx set print max-symbolic-offset unlimited 11254@cindex maximum value for offset of closest symbol 11255Tell @value{GDBN} to only display the symbolic form of an address if the 11256offset between the closest earlier symbol and the address is less than 11257@var{max-offset}. The default is @code{unlimited}, which tells @value{GDBN} 11258to always print the symbolic form of an address if any symbol precedes 11259it. Zero is equivalent to @code{unlimited}. 11260 11261@item show print max-symbolic-offset 11262Ask how large the maximum offset is that @value{GDBN} prints in a 11263symbolic address. 11264@end table 11265 11266@cindex wild pointer, interpreting 11267@cindex pointer, finding referent 11268If you have a pointer and you are not sure where it points, try 11269@samp{set print symbol-filename on}. Then you can determine the name 11270and source file location of the variable where it points, using 11271@samp{p/a @var{pointer}}. This interprets the address in symbolic form. 11272For example, here @value{GDBN} shows that a variable @code{ptt} points 11273at another variable @code{t}, defined in @file{hi2.c}: 11274 11275@smallexample 11276(@value{GDBP}) set print symbol-filename on 11277(@value{GDBP}) p/a ptt 11278$4 = 0xe008 <t in hi2.c> 11279@end smallexample 11280 11281@quotation 11282@emph{Warning:} For pointers that point to a local variable, @samp{p/a} 11283does not show the symbol name and filename of the referent, even with 11284the appropriate @code{set print} options turned on. 11285@end quotation 11286 11287You can also enable @samp{/a}-like formatting all the time using 11288@samp{set print symbol on}: 11289 11290@anchor{set print symbol} 11291@table @code 11292@item set print symbol on 11293Tell @value{GDBN} to print the symbol corresponding to an address, if 11294one exists. 11295 11296@item set print symbol off 11297Tell @value{GDBN} not to print the symbol corresponding to an 11298address. In this mode, @value{GDBN} will still print the symbol 11299corresponding to pointers to functions. This is the default. 11300 11301@item show print symbol 11302Show whether @value{GDBN} will display the symbol corresponding to an 11303address. 11304@end table 11305 11306Other settings control how different kinds of objects are printed: 11307 11308@table @code 11309@anchor{set print array} 11310@item set print array 11311@itemx set print array on 11312@cindex pretty print arrays 11313Pretty print arrays. This format is more convenient to read, 11314but uses more space. The default is off. 11315 11316@item set print array off 11317Return to compressed format for arrays. 11318 11319@item show print array 11320Show whether compressed or pretty format is selected for displaying 11321arrays. 11322 11323@cindex print array indexes 11324@anchor{set print array-indexes} 11325@item set print array-indexes 11326@itemx set print array-indexes on 11327Print the index of each element when displaying arrays. May be more 11328convenient to locate a given element in the array or quickly find the 11329index of a given element in that printed array. The default is off. 11330 11331@item set print array-indexes off 11332Stop printing element indexes when displaying arrays. 11333 11334@item show print array-indexes 11335Show whether the index of each element is printed when displaying 11336arrays. 11337 11338@anchor{set print elements} 11339@item set print elements @var{number-of-elements} 11340@itemx set print elements unlimited 11341@cindex number of array elements to print 11342@cindex limit on number of printed array elements 11343Set a limit on how many elements of an array @value{GDBN} will print. 11344If @value{GDBN} is printing a large array, it stops printing after it has 11345printed the number of elements set by the @code{set print elements} command. 11346This limit also applies to the display of strings. 11347When @value{GDBN} starts, this limit is set to 200. 11348Setting @var{number-of-elements} to @code{unlimited} or zero means 11349that the number of elements to print is unlimited. 11350 11351@item show print elements 11352Display the number of elements of a large array that @value{GDBN} will print. 11353If the number is 0, then the printing is unlimited. 11354 11355@anchor{set print frame-arguments} 11356@item set print frame-arguments @var{value} 11357@kindex set print frame-arguments 11358@cindex printing frame argument values 11359@cindex print all frame argument values 11360@cindex print frame argument values for scalars only 11361@cindex do not print frame arguments 11362This command allows to control how the values of arguments are printed 11363when the debugger prints a frame (@pxref{Frames}). The possible 11364values are: 11365 11366@table @code 11367@item all 11368The values of all arguments are printed. 11369 11370@item scalars 11371Print the value of an argument only if it is a scalar. The value of more 11372complex arguments such as arrays, structures, unions, etc, is replaced 11373by @code{@dots{}}. This is the default. Here is an example where 11374only scalar arguments are shown: 11375 11376@smallexample 11377#1 0x08048361 in call_me (i=3, s=@dots{}, ss=0xbf8d508c, u=@dots{}, e=green) 11378 at frame-args.c:23 11379@end smallexample 11380 11381@item none 11382None of the argument values are printed. Instead, the value of each argument 11383is replaced by @code{@dots{}}. In this case, the example above now becomes: 11384 11385@smallexample 11386#1 0x08048361 in call_me (i=@dots{}, s=@dots{}, ss=@dots{}, u=@dots{}, e=@dots{}) 11387 at frame-args.c:23 11388@end smallexample 11389 11390@item presence 11391Only the presence of arguments is indicated by @code{@dots{}}. 11392The @code{@dots{}} are not printed for function without any arguments. 11393None of the argument names and values are printed. 11394In this case, the example above now becomes: 11395 11396@smallexample 11397#1 0x08048361 in call_me (@dots{}) at frame-args.c:23 11398@end smallexample 11399 11400@end table 11401 11402By default, only scalar arguments are printed. This command can be used 11403to configure the debugger to print the value of all arguments, regardless 11404of their type. However, it is often advantageous to not print the value 11405of more complex parameters. For instance, it reduces the amount of 11406information printed in each frame, making the backtrace more readable. 11407Also, it improves performance when displaying Ada frames, because 11408the computation of large arguments can sometimes be CPU-intensive, 11409especially in large applications. Setting @code{print frame-arguments} 11410to @code{scalars} (the default), @code{none} or @code{presence} avoids 11411this computation, thus speeding up the display of each Ada frame. 11412 11413@item show print frame-arguments 11414Show how the value of arguments should be displayed when printing a frame. 11415 11416@anchor{set print raw-frame-arguments} 11417@item set print raw-frame-arguments on 11418Print frame arguments in raw, non pretty-printed, form. 11419 11420@item set print raw-frame-arguments off 11421Print frame arguments in pretty-printed form, if there is a pretty-printer 11422for the value (@pxref{Pretty Printing}), 11423otherwise print the value in raw form. 11424This is the default. 11425 11426@item show print raw-frame-arguments 11427Show whether to print frame arguments in raw form. 11428 11429@anchor{set print entry-values} 11430@item set print entry-values @var{value} 11431@kindex set print entry-values 11432Set printing of frame argument values at function entry. In some cases 11433@value{GDBN} can determine the value of function argument which was passed by 11434the function caller, even if the value was modified inside the called function 11435and therefore is different. With optimized code, the current value could be 11436unavailable, but the entry value may still be known. 11437 11438The default value is @code{default} (see below for its description). Older 11439@value{GDBN} behaved as with the setting @code{no}. Compilers not supporting 11440this feature will behave in the @code{default} setting the same way as with the 11441@code{no} setting. 11442 11443This functionality is currently supported only by DWARF 2 debugging format and 11444the compiler has to produce @samp{DW_TAG_call_site} tags. With 11445@value{NGCC}, you need to specify @option{-O -g} during compilation, to get 11446this information. 11447 11448The @var{value} parameter can be one of the following: 11449 11450@table @code 11451@item no 11452Print only actual parameter values, never print values from function entry 11453point. 11454@smallexample 11455#0 equal (val=5) 11456#0 different (val=6) 11457#0 lost (val=<optimized out>) 11458#0 born (val=10) 11459#0 invalid (val=<optimized out>) 11460@end smallexample 11461 11462@item only 11463Print only parameter values from function entry point. The actual parameter 11464values are never printed. 11465@smallexample 11466#0 equal (val@@entry=5) 11467#0 different (val@@entry=5) 11468#0 lost (val@@entry=5) 11469#0 born (val@@entry=<optimized out>) 11470#0 invalid (val@@entry=<optimized out>) 11471@end smallexample 11472 11473@item preferred 11474Print only parameter values from function entry point. If value from function 11475entry point is not known while the actual value is known, print the actual 11476value for such parameter. 11477@smallexample 11478#0 equal (val@@entry=5) 11479#0 different (val@@entry=5) 11480#0 lost (val@@entry=5) 11481#0 born (val=10) 11482#0 invalid (val@@entry=<optimized out>) 11483@end smallexample 11484 11485@item if-needed 11486Print actual parameter values. If actual parameter value is not known while 11487value from function entry point is known, print the entry point value for such 11488parameter. 11489@smallexample 11490#0 equal (val=5) 11491#0 different (val=6) 11492#0 lost (val@@entry=5) 11493#0 born (val=10) 11494#0 invalid (val=<optimized out>) 11495@end smallexample 11496 11497@item both 11498Always print both the actual parameter value and its value from function entry 11499point, even if values of one or both are not available due to compiler 11500optimizations. 11501@smallexample 11502#0 equal (val=5, val@@entry=5) 11503#0 different (val=6, val@@entry=5) 11504#0 lost (val=<optimized out>, val@@entry=5) 11505#0 born (val=10, val@@entry=<optimized out>) 11506#0 invalid (val=<optimized out>, val@@entry=<optimized out>) 11507@end smallexample 11508 11509@item compact 11510Print the actual parameter value if it is known and also its value from 11511function entry point if it is known. If neither is known, print for the actual 11512value @code{<optimized out>}. If not in MI mode (@pxref{GDB/MI}) and if both 11513values are known and identical, print the shortened 11514@code{param=param@@entry=VALUE} notation. 11515@smallexample 11516#0 equal (val=val@@entry=5) 11517#0 different (val=6, val@@entry=5) 11518#0 lost (val@@entry=5) 11519#0 born (val=10) 11520#0 invalid (val=<optimized out>) 11521@end smallexample 11522 11523@item default 11524Always print the actual parameter value. Print also its value from function 11525entry point, but only if it is known. If not in MI mode (@pxref{GDB/MI}) and 11526if both values are known and identical, print the shortened 11527@code{param=param@@entry=VALUE} notation. 11528@smallexample 11529#0 equal (val=val@@entry=5) 11530#0 different (val=6, val@@entry=5) 11531#0 lost (val=<optimized out>, val@@entry=5) 11532#0 born (val=10) 11533#0 invalid (val=<optimized out>) 11534@end smallexample 11535@end table 11536 11537For analysis messages on possible failures of frame argument values at function 11538entry resolution see @ref{set debug entry-values}. 11539 11540@item show print entry-values 11541Show the method being used for printing of frame argument values at function 11542entry. 11543 11544@anchor{set print frame-info} 11545@item set print frame-info @var{value} 11546@kindex set print frame-info 11547@cindex printing frame information 11548@cindex frame information, printing 11549This command allows to control the information printed when 11550the debugger prints a frame. See @ref{Frames}, @ref{Backtrace}, 11551for a general explanation about frames and frame information. 11552Note that some other settings (such as @code{set print frame-arguments} 11553and @code{set print address}) are also influencing if and how some frame 11554information is displayed. In particular, the frame program counter is never 11555printed if @code{set print address} is off. 11556 11557The possible values for @code{set print frame-info} are: 11558@table @code 11559@item short-location 11560Print the frame level, the program counter (if not at the 11561beginning of the location source line), the function, the function 11562arguments. 11563@item location 11564Same as @code{short-location} but also print the source file and source line 11565number. 11566@item location-and-address 11567Same as @code{location} but print the program counter even if located at the 11568beginning of the location source line. 11569@item source-line 11570Print the program counter (if not at the beginning of the location 11571source line), the line number and the source line. 11572@item source-and-location 11573Print what @code{location} and @code{source-line} are printing. 11574@item auto 11575The information printed for a frame is decided automatically 11576by the @value{GDBN} command that prints a frame. 11577For example, @code{frame} prints the information printed by 11578@code{source-and-location} while @code{stepi} will switch between 11579@code{source-line} and @code{source-and-location} depending on the program 11580counter. 11581The default value is @code{auto}. 11582@end table 11583 11584@anchor{set print repeats} 11585@item set print repeats @var{number-of-repeats} 11586@itemx set print repeats unlimited 11587@cindex repeated array elements 11588Set the threshold for suppressing display of repeated array 11589elements. When the number of consecutive identical elements of an 11590array exceeds the threshold, @value{GDBN} prints the string 11591@code{"<repeats @var{n} times>"}, where @var{n} is the number of 11592identical repetitions, instead of displaying the identical elements 11593themselves. Setting the threshold to @code{unlimited} or zero will 11594cause all elements to be individually printed. The default threshold 11595is 10. 11596 11597@item show print repeats 11598Display the current threshold for printing repeated identical 11599elements. 11600 11601@anchor{set print max-depth} 11602@item set print max-depth @var{depth} 11603@item set print max-depth unlimited 11604@cindex printing nested structures 11605Set the threshold after which nested structures are replaced with 11606ellipsis, this can make visualising deeply nested structures easier. 11607 11608For example, given this C code 11609 11610@smallexample 11611typedef struct s1 @{ int a; @} s1; 11612typedef struct s2 @{ s1 b; @} s2; 11613typedef struct s3 @{ s2 c; @} s3; 11614typedef struct s4 @{ s3 d; @} s4; 11615 11616s4 var = @{ @{ @{ @{ 3 @} @} @} @}; 11617@end smallexample 11618 11619The following table shows how different values of @var{depth} will 11620effect how @code{var} is printed by @value{GDBN}: 11621 11622@multitable @columnfractions .3 .7 11623@headitem @var{depth} setting @tab Result of @samp{p var} 11624@item unlimited 11625@tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}} 11626@item @code{0} 11627@tab @code{$1 = @{...@}} 11628@item @code{1} 11629@tab @code{$1 = @{d = @{...@}@}} 11630@item @code{2} 11631@tab @code{$1 = @{d = @{c = @{...@}@}@}} 11632@item @code{3} 11633@tab @code{$1 = @{d = @{c = @{b = @{...@}@}@}@}} 11634@item @code{4} 11635@tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}} 11636@end multitable 11637 11638To see the contents of structures that have been hidden the user can 11639either increase the print max-depth, or they can print the elements of 11640the structure that are visible, for example 11641 11642@smallexample 11643(gdb) set print max-depth 2 11644(gdb) p var 11645$1 = @{d = @{c = @{...@}@}@} 11646(gdb) p var.d 11647$2 = @{c = @{b = @{...@}@}@} 11648(gdb) p var.d.c 11649$3 = @{b = @{a = 3@}@} 11650@end smallexample 11651 11652The pattern used to replace nested structures varies based on 11653language, for most languages @code{@{...@}} is used, but Fortran uses 11654@code{(...)}. 11655 11656@item show print max-depth 11657Display the current threshold after which nested structures are 11658replaces with ellipsis. 11659 11660@anchor{set print memory-tag-violations} 11661@cindex printing memory tag violation information 11662@item set print memory-tag-violations 11663@itemx set print memory-tag-violations on 11664Cause @value{GDBN} to display additional information about memory tag violations 11665when printing pointers and addresses. 11666 11667@item set print memory-tag-violations off 11668Stop printing memory tag violation information. 11669 11670@item show print memory-tag-violations 11671Show whether memory tag violation information is displayed when printing 11672pointers and addresses. 11673 11674@anchor{set print null-stop} 11675@item set print null-stop 11676@cindex @sc{null} elements in arrays 11677Cause @value{GDBN} to stop printing the characters of an array when the first 11678@sc{null} is encountered. This is useful when large arrays actually 11679contain only short strings. 11680The default is off. 11681 11682@item show print null-stop 11683Show whether @value{GDBN} stops printing an array on the first 11684@sc{null} character. 11685 11686@anchor{set print pretty} 11687@item set print pretty on 11688@cindex print structures in indented form 11689@cindex indentation in structure display 11690Cause @value{GDBN} to print structures in an indented format with one member 11691per line, like this: 11692 11693@smallexample 11694@group 11695$1 = @{ 11696 next = 0x0, 11697 flags = @{ 11698 sweet = 1, 11699 sour = 1 11700 @}, 11701 meat = 0x54 "Pork" 11702@} 11703@end group 11704@end smallexample 11705 11706@item set print pretty off 11707Cause @value{GDBN} to print structures in a compact format, like this: 11708 11709@smallexample 11710@group 11711$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \ 11712meat = 0x54 "Pork"@} 11713@end group 11714@end smallexample 11715 11716@noindent 11717This is the default format. 11718 11719@item show print pretty 11720Show which format @value{GDBN} is using to print structures. 11721 11722@anchor{set print raw-values} 11723@item set print raw-values on 11724Print values in raw form, without applying the pretty 11725printers for the value. 11726 11727@item set print raw-values off 11728Print values in pretty-printed form, if there is a pretty-printer 11729for the value (@pxref{Pretty Printing}), 11730otherwise print the value in raw form. 11731 11732The default setting is ``off''. 11733 11734@item show print raw-values 11735Show whether to print values in raw form. 11736 11737@item set print sevenbit-strings on 11738@cindex eight-bit characters in strings 11739@cindex octal escapes in strings 11740Print using only seven-bit characters; if this option is set, 11741@value{GDBN} displays any eight-bit characters (in strings or 11742character values) using the notation @code{\}@var{nnn}. This setting is 11743best if you are working in English (@sc{ascii}) and you use the 11744high-order bit of characters as a marker or ``meta'' bit. 11745 11746@item set print sevenbit-strings off 11747Print full eight-bit characters. This allows the use of more 11748international character sets, and is the default. 11749 11750@item show print sevenbit-strings 11751Show whether or not @value{GDBN} is printing only seven-bit characters. 11752 11753@anchor{set print union} 11754@item set print union on 11755@cindex unions in structures, printing 11756Tell @value{GDBN} to print unions which are contained in structures 11757and other unions. This is the default setting. 11758 11759@item set print union off 11760Tell @value{GDBN} not to print unions which are contained in 11761structures and other unions. @value{GDBN} will print @code{"@{...@}"} 11762instead. 11763 11764@item show print union 11765Ask @value{GDBN} whether or not it will print unions which are contained in 11766structures and other unions. 11767 11768For example, given the declarations 11769 11770@smallexample 11771typedef enum @{Tree, Bug@} Species; 11772typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms; 11773typedef enum @{Caterpillar, Cocoon, Butterfly@} 11774 Bug_forms; 11775 11776struct thing @{ 11777 Species it; 11778 union @{ 11779 Tree_forms tree; 11780 Bug_forms bug; 11781 @} form; 11782@}; 11783 11784struct thing foo = @{Tree, @{Acorn@}@}; 11785@end smallexample 11786 11787@noindent 11788with @code{set print union on} in effect @samp{p foo} would print 11789 11790@smallexample 11791$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@} 11792@end smallexample 11793 11794@noindent 11795and with @code{set print union off} in effect it would print 11796 11797@smallexample 11798$1 = @{it = Tree, form = @{...@}@} 11799@end smallexample 11800 11801@noindent 11802@code{set print union} affects programs written in C-like languages 11803and in Pascal. 11804@end table 11805 11806@need 1000 11807@noindent 11808These settings are of interest when debugging C@t{++} programs: 11809 11810@table @code 11811@cindex demangling C@t{++} names 11812@item set print demangle 11813@itemx set print demangle on 11814Print C@t{++} names in their source form rather than in the encoded 11815(``mangled'') form passed to the assembler and linker for type-safe 11816linkage. The default is on. 11817 11818@item show print demangle 11819Show whether C@t{++} names are printed in mangled or demangled form. 11820 11821@item set print asm-demangle 11822@itemx set print asm-demangle on 11823Print C@t{++} names in their source form rather than their mangled form, even 11824in assembler code printouts such as instruction disassemblies. 11825The default is off. 11826 11827@item show print asm-demangle 11828Show whether C@t{++} names in assembly listings are printed in mangled 11829or demangled form. 11830 11831@cindex C@t{++} symbol decoding style 11832@cindex symbol decoding style, C@t{++} 11833@kindex set demangle-style 11834@item set demangle-style @var{style} 11835Choose among several encoding schemes used by different compilers to represent 11836C@t{++} names. If you omit @var{style}, you will see a list of possible 11837formats. The default value is @var{auto}, which lets @value{GDBN} choose a 11838decoding style by inspecting your program. 11839 11840@item show demangle-style 11841Display the encoding style currently in use for decoding C@t{++} symbols. 11842 11843@anchor{set print object} 11844@item set print object 11845@itemx set print object on 11846@cindex derived type of an object, printing 11847@cindex display derived types 11848When displaying a pointer to an object, identify the @emph{actual} 11849(derived) type of the object rather than the @emph{declared} type, using 11850the virtual function table. Note that the virtual function table is 11851required---this feature can only work for objects that have run-time 11852type identification; a single virtual method in the object's declared 11853type is sufficient. Note that this setting is also taken into account when 11854working with variable objects via MI (@pxref{GDB/MI}). 11855 11856@item set print object off 11857Display only the declared type of objects, without reference to the 11858virtual function table. This is the default setting. 11859 11860@item show print object 11861Show whether actual, or declared, object types are displayed. 11862 11863@anchor{set print static-members} 11864@item set print static-members 11865@itemx set print static-members on 11866@cindex static members of C@t{++} objects 11867Print static members when displaying a C@t{++} object. The default is on. 11868 11869@item set print static-members off 11870Do not print static members when displaying a C@t{++} object. 11871 11872@item show print static-members 11873Show whether C@t{++} static members are printed or not. 11874 11875@item set print pascal_static-members 11876@itemx set print pascal_static-members on 11877@cindex static members of Pascal objects 11878@cindex Pascal objects, static members display 11879Print static members when displaying a Pascal object. The default is on. 11880 11881@item set print pascal_static-members off 11882Do not print static members when displaying a Pascal object. 11883 11884@item show print pascal_static-members 11885Show whether Pascal static members are printed or not. 11886 11887@c These don't work with HP ANSI C++ yet. 11888@anchor{set print vtbl} 11889@item set print vtbl 11890@itemx set print vtbl on 11891@cindex pretty print C@t{++} virtual function tables 11892@cindex virtual functions (C@t{++}) display 11893@cindex VTBL display 11894Pretty print C@t{++} virtual function tables. The default is off. 11895(The @code{vtbl} commands do not work on programs compiled with the HP 11896ANSI C@t{++} compiler (@code{aCC}).) 11897 11898@item set print vtbl off 11899Do not pretty print C@t{++} virtual function tables. 11900 11901@item show print vtbl 11902Show whether C@t{++} virtual function tables are pretty printed, or not. 11903@end table 11904 11905@node Pretty Printing 11906@section Pretty Printing 11907 11908@value{GDBN} provides a mechanism to allow pretty-printing of values using 11909Python code. It greatly simplifies the display of complex objects. This 11910mechanism works for both MI and the CLI. 11911 11912@menu 11913* Pretty-Printer Introduction:: Introduction to pretty-printers 11914* Pretty-Printer Example:: An example pretty-printer 11915* Pretty-Printer Commands:: Pretty-printer commands 11916@end menu 11917 11918@node Pretty-Printer Introduction 11919@subsection Pretty-Printer Introduction 11920 11921When @value{GDBN} prints a value, it first sees if there is a pretty-printer 11922registered for the value. If there is then @value{GDBN} invokes the 11923pretty-printer to print the value. Otherwise the value is printed normally. 11924 11925Pretty-printers are normally named. This makes them easy to manage. 11926The @samp{info pretty-printer} command will list all the installed 11927pretty-printers with their names. 11928If a pretty-printer can handle multiple data types, then its 11929@dfn{subprinters} are the printers for the individual data types. 11930Each such subprinter has its own name. 11931The format of the name is @var{printer-name};@var{subprinter-name}. 11932 11933Pretty-printers are installed by @dfn{registering} them with @value{GDBN}. 11934Typically they are automatically loaded and registered when the corresponding 11935debug information is loaded, thus making them available without having to 11936do anything special. 11937 11938There are three places where a pretty-printer can be registered. 11939 11940@itemize @bullet 11941@item 11942Pretty-printers registered globally are available when debugging 11943all inferiors. 11944 11945@item 11946Pretty-printers registered with a program space are available only 11947when debugging that program. 11948@xref{Progspaces In Python}, for more details on program spaces in Python. 11949 11950@item 11951Pretty-printers registered with an objfile are loaded and unloaded 11952with the corresponding objfile (e.g., shared library). 11953@xref{Objfiles In Python}, for more details on objfiles in Python. 11954@end itemize 11955 11956@xref{Selecting Pretty-Printers}, for further information on how 11957pretty-printers are selected, 11958 11959@xref{Writing a Pretty-Printer}, for implementing pretty printers 11960for new types. 11961 11962@node Pretty-Printer Example 11963@subsection Pretty-Printer Example 11964 11965Here is how a C@t{++} @code{std::string} looks without a pretty-printer: 11966 11967@smallexample 11968(@value{GDBP}) print s 11969$1 = @{ 11970 static npos = 4294967295, 11971 _M_dataplus = @{ 11972 <std::allocator<char>> = @{ 11973 <__gnu_cxx::new_allocator<char>> = @{ 11974 <No data fields>@}, <No data fields> 11975 @}, 11976 members of std::basic_string<char, std::char_traits<char>, 11977 std::allocator<char> >::_Alloc_hider: 11978 _M_p = 0x804a014 "abcd" 11979 @} 11980@} 11981@end smallexample 11982 11983With a pretty-printer for @code{std::string} only the contents are printed: 11984 11985@smallexample 11986(@value{GDBP}) print s 11987$2 = "abcd" 11988@end smallexample 11989 11990@node Pretty-Printer Commands 11991@subsection Pretty-Printer Commands 11992@cindex pretty-printer commands 11993 11994@table @code 11995@kindex info pretty-printer 11996@item info pretty-printer [@var{object-regexp} [@var{name-regexp}]] 11997Print the list of installed pretty-printers. 11998This includes disabled pretty-printers, which are marked as such. 11999 12000@var{object-regexp} is a regular expression matching the objects 12001whose pretty-printers to list. 12002Objects can be @code{global}, the program space's file 12003(@pxref{Progspaces In Python}), 12004and the object files within that program space (@pxref{Objfiles In Python}). 12005@xref{Selecting Pretty-Printers}, for details on how @value{GDBN} 12006looks up a printer from these three objects. 12007 12008@var{name-regexp} is a regular expression matching the name of the printers 12009to list. 12010 12011@kindex disable pretty-printer 12012@item disable pretty-printer [@var{object-regexp} [@var{name-regexp}]] 12013Disable pretty-printers matching @var{object-regexp} and @var{name-regexp}. 12014A disabled pretty-printer is not forgotten, it may be enabled again later. 12015 12016@kindex enable pretty-printer 12017@item enable pretty-printer [@var{object-regexp} [@var{name-regexp}]] 12018Enable pretty-printers matching @var{object-regexp} and @var{name-regexp}. 12019@end table 12020 12021Example: 12022 12023Suppose we have three pretty-printers installed: one from library1.so 12024named @code{foo} that prints objects of type @code{foo}, and 12025another from library2.so named @code{bar} that prints two types of objects, 12026@code{bar1} and @code{bar2}. 12027 12028@smallexample 12029(gdb) info pretty-printer 12030library1.so: 12031 foo 12032library2.so: 12033 bar 12034 bar1 12035 bar2 12036(gdb) info pretty-printer library2 12037library2.so: 12038 bar 12039 bar1 12040 bar2 12041(gdb) disable pretty-printer library1 120421 printer disabled 120432 of 3 printers enabled 12044(gdb) info pretty-printer 12045library1.so: 12046 foo [disabled] 12047library2.so: 12048 bar 12049 bar1 12050 bar2 12051(gdb) disable pretty-printer library2 bar;bar1 120521 printer disabled 120531 of 3 printers enabled 12054(gdb) info pretty-printer library2 12055library1.so: 12056 foo [disabled] 12057library2.so: 12058 bar 12059 bar1 [disabled] 12060 bar2 12061(gdb) disable pretty-printer library2 bar 120621 printer disabled 120630 of 3 printers enabled 12064(gdb) info pretty-printer library2 12065library1.so: 12066 foo [disabled] 12067library2.so: 12068 bar [disabled] 12069 bar1 [disabled] 12070 bar2 12071@end smallexample 12072 12073Note that for @code{bar} the entire printer can be disabled, 12074as can each individual subprinter. 12075 12076Printing values and frame arguments is done by default using 12077the enabled pretty printers. 12078 12079The print option @code{-raw-values} and @value{GDBN} setting 12080@code{set print raw-values} (@pxref{set print raw-values}) can be 12081used to print values without applying the enabled pretty printers. 12082 12083Similarly, the backtrace option @code{-raw-frame-arguments} and 12084@value{GDBN} setting @code{set print raw-frame-arguments} 12085(@pxref{set print raw-frame-arguments}) can be used to ignore the 12086enabled pretty printers when printing frame argument values. 12087 12088@node Value History 12089@section Value History 12090 12091@cindex value history 12092@cindex history of values printed by @value{GDBN} 12093Values printed by the @code{print} command are saved in the @value{GDBN} 12094@dfn{value history}. This allows you to refer to them in other expressions. 12095Values are kept until the symbol table is re-read or discarded 12096(for example with the @code{file} or @code{symbol-file} commands). 12097When the symbol table changes, the value history is discarded, 12098since the values may contain pointers back to the types defined in the 12099symbol table. 12100 12101@cindex @code{$} 12102@cindex @code{$$} 12103@cindex history number 12104The values printed are given @dfn{history numbers} by which you can 12105refer to them. These are successive integers starting with one. 12106@code{print} shows you the history number assigned to a value by 12107printing @samp{$@var{num} = } before the value; here @var{num} is the 12108history number. 12109 12110To refer to any previous value, use @samp{$} followed by the value's 12111history number. The way @code{print} labels its output is designed to 12112remind you of this. Just @code{$} refers to the most recent value in 12113the history, and @code{$$} refers to the value before that. 12114@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2} 12115is the value just prior to @code{$$}, @code{$$1} is equivalent to 12116@code{$$}, and @code{$$0} is equivalent to @code{$}. 12117 12118For example, suppose you have just printed a pointer to a structure and 12119want to see the contents of the structure. It suffices to type 12120 12121@smallexample 12122p *$ 12123@end smallexample 12124 12125If you have a chain of structures where the component @code{next} points 12126to the next one, you can print the contents of the next one with this: 12127 12128@smallexample 12129p *$.next 12130@end smallexample 12131 12132@noindent 12133You can print successive links in the chain by repeating this 12134command---which you can do by just typing @key{RET}. 12135 12136Note that the history records values, not expressions. If the value of 12137@code{x} is 4 and you type these commands: 12138 12139@smallexample 12140print x 12141set x=5 12142@end smallexample 12143 12144@noindent 12145then the value recorded in the value history by the @code{print} command 12146remains 4 even though the value of @code{x} has changed. 12147 12148@table @code 12149@kindex show values 12150@item show values 12151Print the last ten values in the value history, with their item numbers. 12152This is like @samp{p@ $$9} repeated ten times, except that @code{show 12153values} does not change the history. 12154 12155@item show values @var{n} 12156Print ten history values centered on history item number @var{n}. 12157 12158@item show values + 12159Print ten history values just after the values last printed. If no more 12160values are available, @code{show values +} produces no display. 12161@end table 12162 12163Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the 12164same effect as @samp{show values +}. 12165 12166@node Convenience Vars 12167@section Convenience Variables 12168 12169@cindex convenience variables 12170@cindex user-defined variables 12171@value{GDBN} provides @dfn{convenience variables} that you can use within 12172@value{GDBN} to hold on to a value and refer to it later. These variables 12173exist entirely within @value{GDBN}; they are not part of your program, and 12174setting a convenience variable has no direct effect on further execution 12175of your program. That is why you can use them freely. 12176 12177Convenience variables are prefixed with @samp{$}. Any name preceded by 12178@samp{$} can be used for a convenience variable, unless it is one of 12179the predefined machine-specific register names (@pxref{Registers, ,Registers}). 12180(Value history references, in contrast, are @emph{numbers} preceded 12181by @samp{$}. @xref{Value History, ,Value History}.) 12182 12183You can save a value in a convenience variable with an assignment 12184expression, just as you would set a variable in your program. 12185For example: 12186 12187@smallexample 12188set $foo = *object_ptr 12189@end smallexample 12190 12191@noindent 12192would save in @code{$foo} the value contained in the object pointed to by 12193@code{object_ptr}. 12194 12195Using a convenience variable for the first time creates it, but its 12196value is @code{void} until you assign a new value. You can alter the 12197value with another assignment at any time. 12198 12199Convenience variables have no fixed types. You can assign a convenience 12200variable any type of value, including structures and arrays, even if 12201that variable already has a value of a different type. The convenience 12202variable, when used as an expression, has the type of its current value. 12203 12204@table @code 12205@kindex show convenience 12206@cindex show all user variables and functions 12207@item show convenience 12208Print a list of convenience variables used so far, and their values, 12209as well as a list of the convenience functions. 12210Abbreviated @code{show conv}. 12211 12212@kindex init-if-undefined 12213@cindex convenience variables, initializing 12214@item init-if-undefined $@var{variable} = @var{expression} 12215Set a convenience variable if it has not already been set. This is useful 12216for user-defined commands that keep some state. It is similar, in concept, 12217to using local static variables with initializers in C (except that 12218convenience variables are global). It can also be used to allow users to 12219override default values used in a command script. 12220 12221If the variable is already defined then the expression is not evaluated so 12222any side-effects do not occur. 12223@end table 12224 12225One of the ways to use a convenience variable is as a counter to be 12226incremented or a pointer to be advanced. For example, to print 12227a field from successive elements of an array of structures: 12228 12229@smallexample 12230set $i = 0 12231print bar[$i++]->contents 12232@end smallexample 12233 12234@noindent 12235Repeat that command by typing @key{RET}. 12236 12237Some convenience variables are created automatically by @value{GDBN} and given 12238values likely to be useful. 12239 12240@table @code 12241@vindex $_@r{, convenience variable} 12242@item $_ 12243The variable @code{$_} is automatically set by the @code{x} command to 12244the last address examined (@pxref{Memory, ,Examining Memory}). Other 12245commands which provide a default address for @code{x} to examine also 12246set @code{$_} to that address; these commands include @code{info line} 12247and @code{info breakpoint}. The type of @code{$_} is @code{void *} 12248except when set by the @code{x} command, in which case it is a pointer 12249to the type of @code{$__}. 12250 12251@vindex $__@r{, convenience variable} 12252@item $__ 12253The variable @code{$__} is automatically set by the @code{x} command 12254to the value found in the last address examined. Its type is chosen 12255to match the format in which the data was printed. 12256 12257@item $_exitcode 12258@vindex $_exitcode@r{, convenience variable} 12259When the program being debugged terminates normally, @value{GDBN} 12260automatically sets this variable to the exit code of the program, and 12261resets @code{$_exitsignal} to @code{void}. 12262 12263@item $_exitsignal 12264@vindex $_exitsignal@r{, convenience variable} 12265When the program being debugged dies due to an uncaught signal, 12266@value{GDBN} automatically sets this variable to that signal's number, 12267and resets @code{$_exitcode} to @code{void}. 12268 12269To distinguish between whether the program being debugged has exited 12270(i.e., @code{$_exitcode} is not @code{void}) or signalled (i.e., 12271@code{$_exitsignal} is not @code{void}), the convenience function 12272@code{$_isvoid} can be used (@pxref{Convenience Funs,, Convenience 12273Functions}). For example, considering the following source code: 12274 12275@smallexample 12276#include <signal.h> 12277 12278int 12279main (int argc, char *argv[]) 12280@{ 12281 raise (SIGALRM); 12282 return 0; 12283@} 12284@end smallexample 12285 12286A valid way of telling whether the program being debugged has exited 12287or signalled would be: 12288 12289@smallexample 12290(@value{GDBP}) define has_exited_or_signalled 12291Type commands for definition of ``has_exited_or_signalled''. 12292End with a line saying just ``end''. 12293>if $_isvoid ($_exitsignal) 12294 >echo The program has exited\n 12295 >else 12296 >echo The program has signalled\n 12297 >end 12298>end 12299(@value{GDBP}) run 12300Starting program: 12301 12302Program terminated with signal SIGALRM, Alarm clock. 12303The program no longer exists. 12304(@value{GDBP}) has_exited_or_signalled 12305The program has signalled 12306@end smallexample 12307 12308As can be seen, @value{GDBN} correctly informs that the program being 12309debugged has signalled, since it calls @code{raise} and raises a 12310@code{SIGALRM} signal. If the program being debugged had not called 12311@code{raise}, then @value{GDBN} would report a normal exit: 12312 12313@smallexample 12314(@value{GDBP}) has_exited_or_signalled 12315The program has exited 12316@end smallexample 12317 12318@item $_exception 12319The variable @code{$_exception} is set to the exception object being 12320thrown at an exception-related catchpoint. @xref{Set Catchpoints}. 12321 12322@item $_ada_exception 12323The variable @code{$_ada_exception} is set to the address of the 12324exception being caught or thrown at an Ada exception-related 12325catchpoint. @xref{Set Catchpoints}. 12326 12327@item $_probe_argc 12328@itemx $_probe_arg0@dots{}$_probe_arg11 12329Arguments to a static probe. @xref{Static Probe Points}. 12330 12331@item $_sdata 12332@vindex $_sdata@r{, inspect, convenience variable} 12333The variable @code{$_sdata} contains extra collected static tracepoint 12334data. @xref{Tracepoint Actions,,Tracepoint Action Lists}. Note that 12335@code{$_sdata} could be empty, if not inspecting a trace buffer, or 12336if extra static tracepoint data has not been collected. 12337 12338@item $_siginfo 12339@vindex $_siginfo@r{, convenience variable} 12340The variable @code{$_siginfo} contains extra signal information 12341(@pxref{extra signal information}). Note that @code{$_siginfo} 12342could be empty, if the application has not yet received any signals. 12343For example, it will be empty before you execute the @code{run} command. 12344 12345@item $_tlb 12346@vindex $_tlb@r{, convenience variable} 12347The variable @code{$_tlb} is automatically set when debugging 12348applications running on MS-Windows in native mode or connected to 12349gdbserver that supports the @code{qGetTIBAddr} request. 12350@xref{General Query Packets}. 12351This variable contains the address of the thread information block. 12352 12353@item $_inferior 12354The number of the current inferior. @xref{Inferiors Connections and 12355Programs, ,Debugging Multiple Inferiors Connections and Programs}. 12356 12357@item $_thread 12358The thread number of the current thread. @xref{thread numbers}. 12359 12360@item $_gthread 12361The global number of the current thread. @xref{global thread numbers}. 12362 12363@item $_gdb_major 12364@itemx $_gdb_minor 12365@vindex $_gdb_major@r{, convenience variable} 12366@vindex $_gdb_minor@r{, convenience variable} 12367The major and minor version numbers of the running @value{GDBN}. 12368Development snapshots and pretest versions have their minor version 12369incremented by one; thus, @value{GDBN} pretest 9.11.90 will produce 12370the value 12 for @code{$_gdb_minor}. These variables allow you to 12371write scripts that work with different versions of @value{GDBN} 12372without errors caused by features unavailable in some of those 12373versions. 12374 12375@item $_shell_exitcode 12376@itemx $_shell_exitsignal 12377@vindex $_shell_exitcode@r{, convenience variable} 12378@vindex $_shell_exitsignal@r{, convenience variable} 12379@cindex shell command, exit code 12380@cindex shell command, exit signal 12381@cindex exit status of shell commands 12382@value{GDBN} commands such as @code{shell} and @code{|} are launching 12383shell commands. When a launched command terminates, @value{GDBN} 12384automatically maintains the variables @code{$_shell_exitcode} 12385and @code{$_shell_exitsignal} according to the exit status of the last 12386launched command. These variables are set and used similarly to 12387the variables @code{$_exitcode} and @code{$_exitsignal}. 12388 12389@end table 12390 12391@node Convenience Funs 12392@section Convenience Functions 12393 12394@cindex convenience functions 12395@value{GDBN} also supplies some @dfn{convenience functions}. These 12396have a syntax similar to convenience variables. A convenience 12397function can be used in an expression just like an ordinary function; 12398however, a convenience function is implemented internally to 12399@value{GDBN}. 12400 12401These functions do not require @value{GDBN} to be configured with 12402@code{Python} support, which means that they are always available. 12403 12404@table @code 12405 12406@item $_isvoid (@var{expr}) 12407@findex $_isvoid@r{, convenience function} 12408Return one if the expression @var{expr} is @code{void}. Otherwise it 12409returns zero. 12410 12411A @code{void} expression is an expression where the type of the result 12412is @code{void}. For example, you can examine a convenience variable 12413(see @ref{Convenience Vars,, Convenience Variables}) to check whether 12414it is @code{void}: 12415 12416@smallexample 12417(@value{GDBP}) print $_exitcode 12418$1 = void 12419(@value{GDBP}) print $_isvoid ($_exitcode) 12420$2 = 1 12421(@value{GDBP}) run 12422Starting program: ./a.out 12423[Inferior 1 (process 29572) exited normally] 12424(@value{GDBP}) print $_exitcode 12425$3 = 0 12426(@value{GDBP}) print $_isvoid ($_exitcode) 12427$4 = 0 12428@end smallexample 12429 12430In the example above, we used @code{$_isvoid} to check whether 12431@code{$_exitcode} is @code{void} before and after the execution of the 12432program being debugged. Before the execution there is no exit code to 12433be examined, therefore @code{$_exitcode} is @code{void}. After the 12434execution the program being debugged returned zero, therefore 12435@code{$_exitcode} is zero, which means that it is not @code{void} 12436anymore. 12437 12438The @code{void} expression can also be a call of a function from the 12439program being debugged. For example, given the following function: 12440 12441@smallexample 12442void 12443foo (void) 12444@{ 12445@} 12446@end smallexample 12447 12448The result of calling it inside @value{GDBN} is @code{void}: 12449 12450@smallexample 12451(@value{GDBP}) print foo () 12452$1 = void 12453(@value{GDBP}) print $_isvoid (foo ()) 12454$2 = 1 12455(@value{GDBP}) set $v = foo () 12456(@value{GDBP}) print $v 12457$3 = void 12458(@value{GDBP}) print $_isvoid ($v) 12459$4 = 1 12460@end smallexample 12461 12462@item $_gdb_setting_str (@var{setting}) 12463@findex $_gdb_setting_str@r{, convenience function} 12464Return the value of the @value{GDBN} @var{setting} as a string. 12465@var{setting} is any setting that can be used in a @code{set} or 12466@code{show} command (@pxref{Controlling GDB}). 12467 12468@smallexample 12469(@value{GDBP}) show print frame-arguments 12470Printing of non-scalar frame arguments is "scalars". 12471(@value{GDBP}) p $_gdb_setting_str("print frame-arguments") 12472$1 = "scalars" 12473(@value{GDBP}) p $_gdb_setting_str("height") 12474$2 = "30" 12475(@value{GDBP}) 12476@end smallexample 12477 12478@item $_gdb_setting (@var{setting}) 12479@findex $_gdb_setting@r{, convenience function} 12480Return the value of the @value{GDBN} @var{setting}. 12481The type of the returned value depends on the setting. 12482 12483The value type for boolean and auto boolean settings is @code{int}. 12484The boolean values @code{off} and @code{on} are converted to 12485the integer values @code{0} and @code{1}. The value @code{auto} is 12486converted to the value @code{-1}. 12487 12488The value type for integer settings is either @code{unsigned int} 12489or @code{int}, depending on the setting. 12490 12491Some integer settings accept an @code{unlimited} value. 12492Depending on the setting, the @code{set} command also accepts 12493the value @code{0} or the value @code{@minus{}1} as a synonym for 12494@code{unlimited}. 12495For example, @code{set height unlimited} is equivalent to 12496@code{set height 0}. 12497 12498Some other settings that accept the @code{unlimited} value 12499use the value @code{0} to literally mean zero. 12500For example, @code{set history size 0} indicates to not 12501record any @value{GDBN} commands in the command history. 12502For such settings, @code{@minus{}1} is the synonym 12503for @code{unlimited}. 12504 12505See the documentation of the corresponding @code{set} command for 12506the numerical value equivalent to @code{unlimited}. 12507 12508The @code{$_gdb_setting} function converts the unlimited value 12509to a @code{0} or a @code{@minus{}1} value according to what the 12510@code{set} command uses. 12511 12512@smallexample 12513@group 12514(@value{GDBP}) p $_gdb_setting_str("height") 12515$1 = "30" 12516(@value{GDBP}) p $_gdb_setting("height") 12517$2 = 30 12518(@value{GDBP}) set height unlimited 12519(@value{GDBP}) p $_gdb_setting_str("height") 12520$3 = "unlimited" 12521(@value{GDBP}) p $_gdb_setting("height") 12522$4 = 0 12523@end group 12524@group 12525(@value{GDBP}) p $_gdb_setting_str("history size") 12526$5 = "unlimited" 12527(@value{GDBP}) p $_gdb_setting("history size") 12528$6 = -1 12529(@value{GDBP}) p $_gdb_setting_str("disassemble-next-line") 12530$7 = "auto" 12531(@value{GDBP}) p $_gdb_setting("disassemble-next-line") 12532$8 = -1 12533(@value{GDBP}) 12534@end group 12535@end smallexample 12536 12537Other setting types (enum, filename, optional filename, string, string noescape) 12538are returned as string values. 12539 12540 12541@item $_gdb_maint_setting_str (@var{setting}) 12542@findex $_gdb_maint_setting_str@r{, convenience function} 12543Like the @code{$_gdb_setting_str} function, but works with 12544@code{maintenance set} variables. 12545 12546@item $_gdb_maint_setting (@var{setting}) 12547@findex $_gdb_maint_setting@r{, convenience function} 12548Like the @code{$_gdb_setting} function, but works with 12549@code{maintenance set} variables. 12550 12551@end table 12552 12553The following functions require @value{GDBN} to be configured with 12554@code{Python} support. 12555 12556@table @code 12557 12558@item $_memeq(@var{buf1}, @var{buf2}, @var{length}) 12559@findex $_memeq@r{, convenience function} 12560Returns one if the @var{length} bytes at the addresses given by 12561@var{buf1} and @var{buf2} are equal. 12562Otherwise it returns zero. 12563 12564@item $_regex(@var{str}, @var{regex}) 12565@findex $_regex@r{, convenience function} 12566Returns one if the string @var{str} matches the regular expression 12567@var{regex}. Otherwise it returns zero. 12568The syntax of the regular expression is that specified by @code{Python}'s 12569regular expression support. 12570 12571@item $_streq(@var{str1}, @var{str2}) 12572@findex $_streq@r{, convenience function} 12573Returns one if the strings @var{str1} and @var{str2} are equal. 12574Otherwise it returns zero. 12575 12576@item $_strlen(@var{str}) 12577@findex $_strlen@r{, convenience function} 12578Returns the length of string @var{str}. 12579 12580@item $_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]}) 12581@findex $_caller_is@r{, convenience function} 12582Returns one if the calling function's name is equal to @var{name}. 12583Otherwise it returns zero. 12584 12585If the optional argument @var{number_of_frames} is provided, 12586it is the number of frames up in the stack to look. 12587The default is 1. 12588 12589Example: 12590 12591@smallexample 12592(gdb) backtrace 12593#0 bottom_func () 12594 at testsuite/gdb.python/py-caller-is.c:21 12595#1 0x00000000004005a0 in middle_func () 12596 at testsuite/gdb.python/py-caller-is.c:27 12597#2 0x00000000004005ab in top_func () 12598 at testsuite/gdb.python/py-caller-is.c:33 12599#3 0x00000000004005b6 in main () 12600 at testsuite/gdb.python/py-caller-is.c:39 12601(gdb) print $_caller_is ("middle_func") 12602$1 = 1 12603(gdb) print $_caller_is ("top_func", 2) 12604$1 = 1 12605@end smallexample 12606 12607@item $_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]}) 12608@findex $_caller_matches@r{, convenience function} 12609Returns one if the calling function's name matches the regular expression 12610@var{regexp}. Otherwise it returns zero. 12611 12612If the optional argument @var{number_of_frames} is provided, 12613it is the number of frames up in the stack to look. 12614The default is 1. 12615 12616@item $_any_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]}) 12617@findex $_any_caller_is@r{, convenience function} 12618Returns one if any calling function's name is equal to @var{name}. 12619Otherwise it returns zero. 12620 12621If the optional argument @var{number_of_frames} is provided, 12622it is the number of frames up in the stack to look. 12623The default is 1. 12624 12625This function differs from @code{$_caller_is} in that this function 12626checks all stack frames from the immediate caller to the frame specified 12627by @var{number_of_frames}, whereas @code{$_caller_is} only checks the 12628frame specified by @var{number_of_frames}. 12629 12630@item $_any_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]}) 12631@findex $_any_caller_matches@r{, convenience function} 12632Returns one if any calling function's name matches the regular expression 12633@var{regexp}. Otherwise it returns zero. 12634 12635If the optional argument @var{number_of_frames} is provided, 12636it is the number of frames up in the stack to look. 12637The default is 1. 12638 12639This function differs from @code{$_caller_matches} in that this function 12640checks all stack frames from the immediate caller to the frame specified 12641by @var{number_of_frames}, whereas @code{$_caller_matches} only checks the 12642frame specified by @var{number_of_frames}. 12643 12644@item $_as_string(@var{value}) 12645@findex $_as_string@r{, convenience function} 12646Return the string representation of @var{value}. 12647 12648This function is useful to obtain the textual label (enumerator) of an 12649enumeration value. For example, assuming the variable @var{node} is of 12650an enumerated type: 12651 12652@smallexample 12653(gdb) printf "Visiting node of type %s\n", $_as_string(node) 12654Visiting node of type NODE_INTEGER 12655@end smallexample 12656 12657@item $_cimag(@var{value}) 12658@itemx $_creal(@var{value}) 12659@findex $_cimag@r{, convenience function} 12660@findex $_creal@r{, convenience function} 12661Return the imaginary (@code{$_cimag}) or real (@code{$_creal}) part of 12662the complex number @var{value}. 12663 12664The type of the imaginary or real part depends on the type of the 12665complex number, e.g., using @code{$_cimag} on a @code{float complex} 12666will return an imaginary part of type @code{float}. 12667 12668@end table 12669 12670@value{GDBN} provides the ability to list and get help on 12671convenience functions. 12672 12673@table @code 12674@item help function 12675@kindex help function 12676@cindex show all convenience functions 12677Print a list of all convenience functions. 12678@end table 12679 12680@node Registers 12681@section Registers 12682 12683@cindex registers 12684You can refer to machine register contents, in expressions, as variables 12685with names starting with @samp{$}. The names of registers are different 12686for each machine; use @code{info registers} to see the names used on 12687your machine. 12688 12689@table @code 12690@kindex info registers 12691@item info registers 12692Print the names and values of all registers except floating-point 12693and vector registers (in the selected stack frame). 12694 12695@kindex info all-registers 12696@cindex floating point registers 12697@item info all-registers 12698Print the names and values of all registers, including floating-point 12699and vector registers (in the selected stack frame). 12700 12701@anchor{info_registers_reggroup} 12702@item info registers @var{reggroup} @dots{} 12703Print the name and value of the registers in each of the specified 12704@var{reggroup}s. The @var{reggroup} can be any of those returned by 12705@code{maint print reggroups} (@pxref{Maintenance Commands}). 12706 12707@item info registers @var{regname} @dots{} 12708Print the @dfn{relativized} value of each specified register @var{regname}. 12709As discussed in detail below, register values are normally relative to 12710the selected stack frame. The @var{regname} may be any register name valid on 12711the machine you are using, with or without the initial @samp{$}. 12712@end table 12713 12714@anchor{standard registers} 12715@cindex stack pointer register 12716@cindex program counter register 12717@cindex process status register 12718@cindex frame pointer register 12719@cindex standard registers 12720@value{GDBN} has four ``standard'' register names that are available (in 12721expressions) on most machines---whenever they do not conflict with an 12722architecture's canonical mnemonics for registers. The register names 12723@code{$pc} and @code{$sp} are used for the program counter register and 12724the stack pointer. @code{$fp} is used for a register that contains a 12725pointer to the current stack frame, and @code{$ps} is used for a 12726register that contains the processor status. For example, 12727you could print the program counter in hex with 12728 12729@smallexample 12730p/x $pc 12731@end smallexample 12732 12733@noindent 12734or print the instruction to be executed next with 12735 12736@smallexample 12737x/i $pc 12738@end smallexample 12739 12740@noindent 12741or add four to the stack pointer@footnote{This is a way of removing 12742one word from the stack, on machines where stacks grow downward in 12743memory (most machines, nowadays). This assumes that the innermost 12744stack frame is selected; setting @code{$sp} is not allowed when other 12745stack frames are selected. To pop entire frames off the stack, 12746regardless of machine architecture, use @code{return}; 12747see @ref{Returning, ,Returning from a Function}.} with 12748 12749@smallexample 12750set $sp += 4 12751@end smallexample 12752 12753Whenever possible, these four standard register names are available on 12754your machine even though the machine has different canonical mnemonics, 12755so long as there is no conflict. The @code{info registers} command 12756shows the canonical names. For example, on the SPARC, @code{info 12757registers} displays the processor status register as @code{$psr} but you 12758can also refer to it as @code{$ps}; and on x86-based machines @code{$ps} 12759is an alias for the @sc{eflags} register. 12760 12761@value{GDBN} always considers the contents of an ordinary register as an 12762integer when the register is examined in this way. Some machines have 12763special registers which can hold nothing but floating point; these 12764registers are considered to have floating point values. There is no way 12765to refer to the contents of an ordinary register as floating point value 12766(although you can @emph{print} it as a floating point value with 12767@samp{print/f $@var{regname}}). 12768 12769Some registers have distinct ``raw'' and ``virtual'' data formats. This 12770means that the data format in which the register contents are saved by 12771the operating system is not the same one that your program normally 12772sees. For example, the registers of the 68881 floating point 12773coprocessor are always saved in ``extended'' (raw) format, but all C 12774programs expect to work with ``double'' (virtual) format. In such 12775cases, @value{GDBN} normally works with the virtual format only (the format 12776that makes sense for your program), but the @code{info registers} command 12777prints the data in both formats. 12778 12779@cindex SSE registers (x86) 12780@cindex MMX registers (x86) 12781Some machines have special registers whose contents can be interpreted 12782in several different ways. For example, modern x86-based machines 12783have SSE and MMX registers that can hold several values packed 12784together in several different formats. @value{GDBN} refers to such 12785registers in @code{struct} notation: 12786 12787@smallexample 12788(@value{GDBP}) print $xmm1 12789$1 = @{ 12790 v4_float = @{0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044@}, 12791 v2_double = @{9.92129282474342e-303, 2.7585945287983262e-313@}, 12792 v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000", 12793 v8_int16 = @{0, 0, 14072, 315, 11, 0, 13, 0@}, 12794 v4_int32 = @{0, 20657912, 11, 13@}, 12795 v2_int64 = @{88725056443645952, 55834574859@}, 12796 uint128 = 0x0000000d0000000b013b36f800000000 12797@} 12798@end smallexample 12799 12800@noindent 12801To set values of such registers, you need to tell @value{GDBN} which 12802view of the register you wish to change, as if you were assigning 12803value to a @code{struct} member: 12804 12805@smallexample 12806 (@value{GDBP}) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF 12807@end smallexample 12808 12809Normally, register values are relative to the selected stack frame 12810(@pxref{Selection, ,Selecting a Frame}). This means that you get the 12811value that the register would contain if all stack frames farther in 12812were exited and their saved registers restored. In order to see the 12813true contents of hardware registers, you must select the innermost 12814frame (with @samp{frame 0}). 12815 12816@cindex caller-saved registers 12817@cindex call-clobbered registers 12818@cindex volatile registers 12819@cindex <not saved> values 12820Usually ABIs reserve some registers as not needed to be saved by the 12821callee (a.k.a.: ``caller-saved'', ``call-clobbered'' or ``volatile'' 12822registers). It may therefore not be possible for @value{GDBN} to know 12823the value a register had before the call (in other words, in the outer 12824frame), if the register value has since been changed by the callee. 12825@value{GDBN} tries to deduce where the inner frame saved 12826(``callee-saved'') registers, from the debug info, unwind info, or the 12827machine code generated by your compiler. If some register is not 12828saved, and @value{GDBN} knows the register is ``caller-saved'' (via 12829its own knowledge of the ABI, or because the debug/unwind info 12830explicitly says the register's value is undefined), @value{GDBN} 12831displays @w{@samp{<not saved>}} as the register's value. With targets 12832that @value{GDBN} has no knowledge of the register saving convention, 12833if a register was not saved by the callee, then its value and location 12834in the outer frame are assumed to be the same of the inner frame. 12835This is usually harmless, because if the register is call-clobbered, 12836the caller either does not care what is in the register after the 12837call, or has code to restore the value that it does care about. Note, 12838however, that if you change such a register in the outer frame, you 12839may also be affecting the inner frame. Also, the more ``outer'' the 12840frame is you're looking at, the more likely a call-clobbered 12841register's value is to be wrong, in the sense that it doesn't actually 12842represent the value the register had just before the call. 12843 12844@node Floating Point Hardware 12845@section Floating Point Hardware 12846@cindex floating point 12847 12848Depending on the configuration, @value{GDBN} may be able to give 12849you more information about the status of the floating point hardware. 12850 12851@table @code 12852@kindex info float 12853@item info float 12854Display hardware-dependent information about the floating 12855point unit. The exact contents and layout vary depending on the 12856floating point chip. Currently, @samp{info float} is supported on 12857the ARM and x86 machines. 12858@end table 12859 12860@node Vector Unit 12861@section Vector Unit 12862@cindex vector unit 12863 12864Depending on the configuration, @value{GDBN} may be able to give you 12865more information about the status of the vector unit. 12866 12867@table @code 12868@kindex info vector 12869@item info vector 12870Display information about the vector unit. The exact contents and 12871layout vary depending on the hardware. 12872@end table 12873 12874@node OS Information 12875@section Operating System Auxiliary Information 12876@cindex OS information 12877 12878@value{GDBN} provides interfaces to useful OS facilities that can help 12879you debug your program. 12880 12881@cindex auxiliary vector 12882@cindex vector, auxiliary 12883Some operating systems supply an @dfn{auxiliary vector} to programs at 12884startup. This is akin to the arguments and environment that you 12885specify for a program, but contains a system-dependent variety of 12886binary values that tell system libraries important details about the 12887hardware, operating system, and process. Each value's purpose is 12888identified by an integer tag; the meanings are well-known but system-specific. 12889Depending on the configuration and operating system facilities, 12890@value{GDBN} may be able to show you this information. For remote 12891targets, this functionality may further depend on the remote stub's 12892support of the @samp{qXfer:auxv:read} packet, see 12893@ref{qXfer auxiliary vector read}. 12894 12895@table @code 12896@kindex info auxv 12897@item info auxv 12898Display the auxiliary vector of the inferior, which can be either a 12899live process or a core dump file. @value{GDBN} prints each tag value 12900numerically, and also shows names and text descriptions for recognized 12901tags. Some values in the vector are numbers, some bit masks, and some 12902pointers to strings or other data. @value{GDBN} displays each value in the 12903most appropriate form for a recognized tag, and in hexadecimal for 12904an unrecognized tag. 12905@end table 12906 12907On some targets, @value{GDBN} can access operating system-specific 12908information and show it to you. The types of information available 12909will differ depending on the type of operating system running on the 12910target. The mechanism used to fetch the data is described in 12911@ref{Operating System Information}. For remote targets, this 12912functionality depends on the remote stub's support of the 12913@samp{qXfer:osdata:read} packet, see @ref{qXfer osdata read}. 12914 12915@table @code 12916@kindex info os 12917@item info os @var{infotype} 12918 12919Display OS information of the requested type. 12920 12921On @sc{gnu}/Linux, the following values of @var{infotype} are valid: 12922 12923@anchor{linux info os infotypes} 12924@table @code 12925@kindex info os cpus 12926@item cpus 12927Display the list of all CPUs/cores. For each CPU/core, @value{GDBN} prints 12928the available fields from /proc/cpuinfo. For each supported architecture 12929different fields are available. Two common entries are processor which gives 12930CPU number and bogomips; a system constant that is calculated during 12931kernel initialization. 12932 12933@kindex info os files 12934@item files 12935Display the list of open file descriptors on the target. For each 12936file descriptor, @value{GDBN} prints the identifier of the process 12937owning the descriptor, the command of the owning process, the value 12938of the descriptor, and the target of the descriptor. 12939 12940@kindex info os modules 12941@item modules 12942Display the list of all loaded kernel modules on the target. For each 12943module, @value{GDBN} prints the module name, the size of the module in 12944bytes, the number of times the module is used, the dependencies of the 12945module, the status of the module, and the address of the loaded module 12946in memory. 12947 12948@kindex info os msg 12949@item msg 12950Display the list of all System V message queues on the target. For each 12951message queue, @value{GDBN} prints the message queue key, the message 12952queue identifier, the access permissions, the current number of bytes 12953on the queue, the current number of messages on the queue, the processes 12954that last sent and received a message on the queue, the user and group 12955of the owner and creator of the message queue, the times at which a 12956message was last sent and received on the queue, and the time at which 12957the message queue was last changed. 12958 12959@kindex info os processes 12960@item processes 12961Display the list of processes on the target. For each process, 12962@value{GDBN} prints the process identifier, the name of the user, the 12963command corresponding to the process, and the list of processor cores 12964that the process is currently running on. (To understand what these 12965properties mean, for this and the following info types, please consult 12966the general @sc{gnu}/Linux documentation.) 12967 12968@kindex info os procgroups 12969@item procgroups 12970Display the list of process groups on the target. For each process, 12971@value{GDBN} prints the identifier of the process group that it belongs 12972to, the command corresponding to the process group leader, the process 12973identifier, and the command line of the process. The list is sorted 12974first by the process group identifier, then by the process identifier, 12975so that processes belonging to the same process group are grouped together 12976and the process group leader is listed first. 12977 12978@kindex info os semaphores 12979@item semaphores 12980Display the list of all System V semaphore sets on the target. For each 12981semaphore set, @value{GDBN} prints the semaphore set key, the semaphore 12982set identifier, the access permissions, the number of semaphores in the 12983set, the user and group of the owner and creator of the semaphore set, 12984and the times at which the semaphore set was operated upon and changed. 12985 12986@kindex info os shm 12987@item shm 12988Display the list of all System V shared-memory regions on the target. 12989For each shared-memory region, @value{GDBN} prints the region key, 12990the shared-memory identifier, the access permissions, the size of the 12991region, the process that created the region, the process that last 12992attached to or detached from the region, the current number of live 12993attaches to the region, and the times at which the region was last 12994attached to, detach from, and changed. 12995 12996@kindex info os sockets 12997@item sockets 12998Display the list of Internet-domain sockets on the target. For each 12999socket, @value{GDBN} prints the address and port of the local and 13000remote endpoints, the current state of the connection, the creator of 13001the socket, the IP address family of the socket, and the type of the 13002connection. 13003 13004@kindex info os threads 13005@item threads 13006Display the list of threads running on the target. For each thread, 13007@value{GDBN} prints the identifier of the process that the thread 13008belongs to, the command of the process, the thread identifier, and the 13009processor core that it is currently running on. The main thread of a 13010process is not listed. 13011@end table 13012 13013@item info os 13014If @var{infotype} is omitted, then list the possible values for 13015@var{infotype} and the kind of OS information available for each 13016@var{infotype}. If the target does not return a list of possible 13017types, this command will report an error. 13018@end table 13019 13020@node Memory Region Attributes 13021@section Memory Region Attributes 13022@cindex memory region attributes 13023 13024@dfn{Memory region attributes} allow you to describe special handling 13025required by regions of your target's memory. @value{GDBN} uses 13026attributes to determine whether to allow certain types of memory 13027accesses; whether to use specific width accesses; and whether to cache 13028target memory. By default the description of memory regions is 13029fetched from the target (if the current target supports this), but the 13030user can override the fetched regions. 13031 13032Defined memory regions can be individually enabled and disabled. When a 13033memory region is disabled, @value{GDBN} uses the default attributes when 13034accessing memory in that region. Similarly, if no memory regions have 13035been defined, @value{GDBN} uses the default attributes when accessing 13036all memory. 13037 13038When a memory region is defined, it is given a number to identify it; 13039to enable, disable, or remove a memory region, you specify that number. 13040 13041@table @code 13042@kindex mem 13043@item mem @var{lower} @var{upper} @var{attributes}@dots{} 13044Define a memory region bounded by @var{lower} and @var{upper} with 13045attributes @var{attributes}@dots{}, and add it to the list of regions 13046monitored by @value{GDBN}. Note that @var{upper} == 0 is a special 13047case: it is treated as the target's maximum memory address. 13048(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.) 13049 13050@item mem auto 13051Discard any user changes to the memory regions and use target-supplied 13052regions, if available, or no regions if the target does not support. 13053 13054@kindex delete mem 13055@item delete mem @var{nums}@dots{} 13056Remove memory regions @var{nums}@dots{} from the list of regions 13057monitored by @value{GDBN}. 13058 13059@kindex disable mem 13060@item disable mem @var{nums}@dots{} 13061Disable monitoring of memory regions @var{nums}@dots{}. 13062A disabled memory region is not forgotten. 13063It may be enabled again later. 13064 13065@kindex enable mem 13066@item enable mem @var{nums}@dots{} 13067Enable monitoring of memory regions @var{nums}@dots{}. 13068 13069@kindex info mem 13070@item info mem 13071Print a table of all defined memory regions, with the following columns 13072for each region: 13073 13074@table @emph 13075@item Memory Region Number 13076@item Enabled or Disabled. 13077Enabled memory regions are marked with @samp{y}. 13078Disabled memory regions are marked with @samp{n}. 13079 13080@item Lo Address 13081The address defining the inclusive lower bound of the memory region. 13082 13083@item Hi Address 13084The address defining the exclusive upper bound of the memory region. 13085 13086@item Attributes 13087The list of attributes set for this memory region. 13088@end table 13089@end table 13090 13091 13092@subsection Attributes 13093 13094@subsubsection Memory Access Mode 13095The access mode attributes set whether @value{GDBN} may make read or 13096write accesses to a memory region. 13097 13098While these attributes prevent @value{GDBN} from performing invalid 13099memory accesses, they do nothing to prevent the target system, I/O DMA, 13100etc.@: from accessing memory. 13101 13102@table @code 13103@item ro 13104Memory is read only. 13105@item wo 13106Memory is write only. 13107@item rw 13108Memory is read/write. This is the default. 13109@end table 13110 13111@subsubsection Memory Access Size 13112The access size attribute tells @value{GDBN} to use specific sized 13113accesses in the memory region. Often memory mapped device registers 13114require specific sized accesses. If no access size attribute is 13115specified, @value{GDBN} may use accesses of any size. 13116 13117@table @code 13118@item 8 13119Use 8 bit memory accesses. 13120@item 16 13121Use 16 bit memory accesses. 13122@item 32 13123Use 32 bit memory accesses. 13124@item 64 13125Use 64 bit memory accesses. 13126@end table 13127 13128@c @subsubsection Hardware/Software Breakpoints 13129@c The hardware/software breakpoint attributes set whether @value{GDBN} 13130@c will use hardware or software breakpoints for the internal breakpoints 13131@c used by the step, next, finish, until, etc. commands. 13132@c 13133@c @table @code 13134@c @item hwbreak 13135@c Always use hardware breakpoints 13136@c @item swbreak (default) 13137@c @end table 13138 13139@subsubsection Data Cache 13140The data cache attributes set whether @value{GDBN} will cache target 13141memory. While this generally improves performance by reducing debug 13142protocol overhead, it can lead to incorrect results because @value{GDBN} 13143does not know about volatile variables or memory mapped device 13144registers. 13145 13146@table @code 13147@item cache 13148Enable @value{GDBN} to cache target memory. 13149@item nocache 13150Disable @value{GDBN} from caching target memory. This is the default. 13151@end table 13152 13153@subsection Memory Access Checking 13154@value{GDBN} can be instructed to refuse accesses to memory that is 13155not explicitly described. This can be useful if accessing such 13156regions has undesired effects for a specific target, or to provide 13157better error checking. The following commands control this behaviour. 13158 13159@table @code 13160@kindex set mem inaccessible-by-default 13161@item set mem inaccessible-by-default [on|off] 13162If @code{on} is specified, make @value{GDBN} treat memory not 13163explicitly described by the memory ranges as non-existent and refuse accesses 13164to such memory. The checks are only performed if there's at least one 13165memory range defined. If @code{off} is specified, make @value{GDBN} 13166treat the memory not explicitly described by the memory ranges as RAM. 13167The default value is @code{on}. 13168@kindex show mem inaccessible-by-default 13169@item show mem inaccessible-by-default 13170Show the current handling of accesses to unknown memory. 13171@end table 13172 13173 13174@c @subsubsection Memory Write Verification 13175@c The memory write verification attributes set whether @value{GDBN} 13176@c will re-reads data after each write to verify the write was successful. 13177@c 13178@c @table @code 13179@c @item verify 13180@c @item noverify (default) 13181@c @end table 13182 13183@node Dump/Restore Files 13184@section Copy Between Memory and a File 13185@cindex dump/restore files 13186@cindex append data to a file 13187@cindex dump data to a file 13188@cindex restore data from a file 13189 13190You can use the commands @code{dump}, @code{append}, and 13191@code{restore} to copy data between target memory and a file. The 13192@code{dump} and @code{append} commands write data to a file, and the 13193@code{restore} command reads data from a file back into the inferior's 13194memory. Files may be in binary, Motorola S-record, Intel hex, 13195Tektronix Hex, or Verilog Hex format; however, @value{GDBN} can only 13196append to binary files, and cannot read from Verilog Hex files. 13197 13198@table @code 13199 13200@kindex dump 13201@item dump @r{[}@var{format}@r{]} memory @var{filename} @var{start_addr} @var{end_addr} 13202@itemx dump @r{[}@var{format}@r{]} value @var{filename} @var{expr} 13203Dump the contents of memory from @var{start_addr} to @var{end_addr}, 13204or the value of @var{expr}, to @var{filename} in the given format. 13205 13206The @var{format} parameter may be any one of: 13207@table @code 13208@item binary 13209Raw binary form. 13210@item ihex 13211Intel hex format. 13212@item srec 13213Motorola S-record format. 13214@item tekhex 13215Tektronix Hex format. 13216@item verilog 13217Verilog Hex format. 13218@end table 13219 13220@value{GDBN} uses the same definitions of these formats as the 13221@sc{gnu} binary utilities, like @samp{objdump} and @samp{objcopy}. If 13222@var{format} is omitted, @value{GDBN} dumps the data in raw binary 13223form. 13224 13225@kindex append 13226@item append @r{[}binary@r{]} memory @var{filename} @var{start_addr} @var{end_addr} 13227@itemx append @r{[}binary@r{]} value @var{filename} @var{expr} 13228Append the contents of memory from @var{start_addr} to @var{end_addr}, 13229or the value of @var{expr}, to the file @var{filename}, in raw binary form. 13230(@value{GDBN} can only append data to files in raw binary form.) 13231 13232@kindex restore 13233@item restore @var{filename} @r{[}binary@r{]} @var{bias} @var{start} @var{end} 13234Restore the contents of file @var{filename} into memory. The 13235@code{restore} command can automatically recognize any known @sc{bfd} 13236file format, except for raw binary. To restore a raw binary file you 13237must specify the optional keyword @code{binary} after the filename. 13238 13239If @var{bias} is non-zero, its value will be added to the addresses 13240contained in the file. Binary files always start at address zero, so 13241they will be restored at address @var{bias}. Other bfd files have 13242a built-in location; they will be restored at offset @var{bias} 13243from that location. 13244 13245If @var{start} and/or @var{end} are non-zero, then only data between 13246file offset @var{start} and file offset @var{end} will be restored. 13247These offsets are relative to the addresses in the file, before 13248the @var{bias} argument is applied. 13249 13250@end table 13251 13252@node Core File Generation 13253@section How to Produce a Core File from Your Program 13254@cindex dump core from inferior 13255 13256A @dfn{core file} or @dfn{core dump} is a file that records the memory 13257image of a running process and its process status (register values 13258etc.). Its primary use is post-mortem debugging of a program that 13259crashed while it ran outside a debugger. A program that crashes 13260automatically produces a core file, unless this feature is disabled by 13261the user. @xref{Files}, for information on invoking @value{GDBN} in 13262the post-mortem debugging mode. 13263 13264Occasionally, you may wish to produce a core file of the program you 13265are debugging in order to preserve a snapshot of its state. 13266@value{GDBN} has a special command for that. 13267 13268@table @code 13269@kindex gcore 13270@kindex generate-core-file 13271@item generate-core-file [@var{file}] 13272@itemx gcore [@var{file}] 13273Produce a core dump of the inferior process. The optional argument 13274@var{file} specifies the file name where to put the core dump. If not 13275specified, the file name defaults to @file{core.@var{pid}}, where 13276@var{pid} is the inferior process ID. 13277 13278Note that this command is implemented only for some systems (as of 13279this writing, @sc{gnu}/Linux, FreeBSD, Solaris, and S390). 13280 13281On @sc{gnu}/Linux, this command can take into account the value of the 13282file @file{/proc/@var{pid}/coredump_filter} when generating the core 13283dump (@pxref{set use-coredump-filter}), and by default honors the 13284@code{VM_DONTDUMP} flag for mappings where it is present in the file 13285@file{/proc/@var{pid}/smaps} (@pxref{set dump-excluded-mappings}). 13286 13287@kindex set use-coredump-filter 13288@anchor{set use-coredump-filter} 13289@item set use-coredump-filter on 13290@itemx set use-coredump-filter off 13291Enable or disable the use of the file 13292@file{/proc/@var{pid}/coredump_filter} when generating core dump 13293files. This file is used by the Linux kernel to decide what types of 13294memory mappings will be dumped or ignored when generating a core dump 13295file. @var{pid} is the process ID of a currently running process. 13296 13297To make use of this feature, you have to write in the 13298@file{/proc/@var{pid}/coredump_filter} file a value, in hexadecimal, 13299which is a bit mask representing the memory mapping types. If a bit 13300is set in the bit mask, then the memory mappings of the corresponding 13301types will be dumped; otherwise, they will be ignored. This 13302configuration is inherited by child processes. For more information 13303about the bits that can be set in the 13304@file{/proc/@var{pid}/coredump_filter} file, please refer to the 13305manpage of @code{core(5)}. 13306 13307By default, this option is @code{on}. If this option is turned 13308@code{off}, @value{GDBN} does not read the @file{coredump_filter} file 13309and instead uses the same default value as the Linux kernel in order 13310to decide which pages will be dumped in the core dump file. This 13311value is currently @code{0x33}, which means that bits @code{0} 13312(anonymous private mappings), @code{1} (anonymous shared mappings), 13313@code{4} (ELF headers) and @code{5} (private huge pages) are active. 13314This will cause these memory mappings to be dumped automatically. 13315 13316@kindex set dump-excluded-mappings 13317@anchor{set dump-excluded-mappings} 13318@item set dump-excluded-mappings on 13319@itemx set dump-excluded-mappings off 13320If @code{on} is specified, @value{GDBN} will dump memory mappings 13321marked with the @code{VM_DONTDUMP} flag. This flag is represented in 13322the file @file{/proc/@var{pid}/smaps} with the acronym @code{dd}. 13323 13324The default value is @code{off}. 13325@end table 13326 13327@node Character Sets 13328@section Character Sets 13329@cindex character sets 13330@cindex charset 13331@cindex translating between character sets 13332@cindex host character set 13333@cindex target character set 13334 13335If the program you are debugging uses a different character set to 13336represent characters and strings than the one @value{GDBN} uses itself, 13337@value{GDBN} can automatically translate between the character sets for 13338you. The character set @value{GDBN} uses we call the @dfn{host 13339character set}; the one the inferior program uses we call the 13340@dfn{target character set}. 13341 13342For example, if you are running @value{GDBN} on a @sc{gnu}/Linux system, which 13343uses the ISO Latin 1 character set, but you are using @value{GDBN}'s 13344remote protocol (@pxref{Remote Debugging}) to debug a program 13345running on an IBM mainframe, which uses the @sc{ebcdic} character set, 13346then the host character set is Latin-1, and the target character set is 13347@sc{ebcdic}. If you give @value{GDBN} the command @code{set 13348target-charset EBCDIC-US}, then @value{GDBN} translates between 13349@sc{ebcdic} and Latin 1 as you print character or string values, or use 13350character and string literals in expressions. 13351 13352@value{GDBN} has no way to automatically recognize which character set 13353the inferior program uses; you must tell it, using the @code{set 13354target-charset} command, described below. 13355 13356Here are the commands for controlling @value{GDBN}'s character set 13357support: 13358 13359@table @code 13360@item set target-charset @var{charset} 13361@kindex set target-charset 13362Set the current target character set to @var{charset}. To display the 13363list of supported target character sets, type 13364@kbd{@w{set target-charset @key{TAB}@key{TAB}}}. 13365 13366@item set host-charset @var{charset} 13367@kindex set host-charset 13368Set the current host character set to @var{charset}. 13369 13370By default, @value{GDBN} uses a host character set appropriate to the 13371system it is running on; you can override that default using the 13372@code{set host-charset} command. On some systems, @value{GDBN} cannot 13373automatically determine the appropriate host character set. In this 13374case, @value{GDBN} uses @samp{UTF-8}. 13375 13376@value{GDBN} can only use certain character sets as its host character 13377set. If you type @kbd{@w{set host-charset @key{TAB}@key{TAB}}}, 13378@value{GDBN} will list the host character sets it supports. 13379 13380@item set charset @var{charset} 13381@kindex set charset 13382Set the current host and target character sets to @var{charset}. As 13383above, if you type @kbd{@w{set charset @key{TAB}@key{TAB}}}, 13384@value{GDBN} will list the names of the character sets that can be used 13385for both host and target. 13386 13387@item show charset 13388@kindex show charset 13389Show the names of the current host and target character sets. 13390 13391@item show host-charset 13392@kindex show host-charset 13393Show the name of the current host character set. 13394 13395@item show target-charset 13396@kindex show target-charset 13397Show the name of the current target character set. 13398 13399@item set target-wide-charset @var{charset} 13400@kindex set target-wide-charset 13401Set the current target's wide character set to @var{charset}. This is 13402the character set used by the target's @code{wchar_t} type. To 13403display the list of supported wide character sets, type 13404@kbd{@w{set target-wide-charset @key{TAB}@key{TAB}}}. 13405 13406@item show target-wide-charset 13407@kindex show target-wide-charset 13408Show the name of the current target's wide character set. 13409@end table 13410 13411Here is an example of @value{GDBN}'s character set support in action. 13412Assume that the following source code has been placed in the file 13413@file{charset-test.c}: 13414 13415@smallexample 13416#include <stdio.h> 13417 13418char ascii_hello[] 13419 = @{72, 101, 108, 108, 111, 44, 32, 119, 13420 111, 114, 108, 100, 33, 10, 0@}; 13421char ibm1047_hello[] 13422 = @{200, 133, 147, 147, 150, 107, 64, 166, 13423 150, 153, 147, 132, 90, 37, 0@}; 13424 13425main () 13426@{ 13427 printf ("Hello, world!\n"); 13428@} 13429@end smallexample 13430 13431In this program, @code{ascii_hello} and @code{ibm1047_hello} are arrays 13432containing the string @samp{Hello, world!} followed by a newline, 13433encoded in the @sc{ascii} and @sc{ibm1047} character sets. 13434 13435We compile the program, and invoke the debugger on it: 13436 13437@smallexample 13438$ gcc -g charset-test.c -o charset-test 13439$ gdb -nw charset-test 13440GNU gdb 2001-12-19-cvs 13441Copyright 2001 Free Software Foundation, Inc. 13442@dots{} 13443(@value{GDBP}) 13444@end smallexample 13445 13446We can use the @code{show charset} command to see what character sets 13447@value{GDBN} is currently using to interpret and display characters and 13448strings: 13449 13450@smallexample 13451(@value{GDBP}) show charset 13452The current host and target character set is `ISO-8859-1'. 13453(@value{GDBP}) 13454@end smallexample 13455 13456For the sake of printing this manual, let's use @sc{ascii} as our 13457initial character set: 13458@smallexample 13459(@value{GDBP}) set charset ASCII 13460(@value{GDBP}) show charset 13461The current host and target character set is `ASCII'. 13462(@value{GDBP}) 13463@end smallexample 13464 13465Let's assume that @sc{ascii} is indeed the correct character set for our 13466host system --- in other words, let's assume that if @value{GDBN} prints 13467characters using the @sc{ascii} character set, our terminal will display 13468them properly. Since our current target character set is also 13469@sc{ascii}, the contents of @code{ascii_hello} print legibly: 13470 13471@smallexample 13472(@value{GDBP}) print ascii_hello 13473$1 = 0x401698 "Hello, world!\n" 13474(@value{GDBP}) print ascii_hello[0] 13475$2 = 72 'H' 13476(@value{GDBP}) 13477@end smallexample 13478 13479@value{GDBN} uses the target character set for character and string 13480literals you use in expressions: 13481 13482@smallexample 13483(@value{GDBP}) print '+' 13484$3 = 43 '+' 13485(@value{GDBP}) 13486@end smallexample 13487 13488The @sc{ascii} character set uses the number 43 to encode the @samp{+} 13489character. 13490 13491@value{GDBN} relies on the user to tell it which character set the 13492target program uses. If we print @code{ibm1047_hello} while our target 13493character set is still @sc{ascii}, we get jibberish: 13494 13495@smallexample 13496(@value{GDBP}) print ibm1047_hello 13497$4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%" 13498(@value{GDBP}) print ibm1047_hello[0] 13499$5 = 200 '\310' 13500(@value{GDBP}) 13501@end smallexample 13502 13503If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB}, 13504@value{GDBN} tells us the character sets it supports: 13505 13506@smallexample 13507(@value{GDBP}) set target-charset 13508ASCII EBCDIC-US IBM1047 ISO-8859-1 13509(@value{GDBP}) set target-charset 13510@end smallexample 13511 13512We can select @sc{ibm1047} as our target character set, and examine the 13513program's strings again. Now the @sc{ascii} string is wrong, but 13514@value{GDBN} translates the contents of @code{ibm1047_hello} from the 13515target character set, @sc{ibm1047}, to the host character set, 13516@sc{ascii}, and they display correctly: 13517 13518@smallexample 13519(@value{GDBP}) set target-charset IBM1047 13520(@value{GDBP}) show charset 13521The current host character set is `ASCII'. 13522The current target character set is `IBM1047'. 13523(@value{GDBP}) print ascii_hello 13524$6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" 13525(@value{GDBP}) print ascii_hello[0] 13526$7 = 72 '\110' 13527(@value{GDBP}) print ibm1047_hello 13528$8 = 0x4016a8 "Hello, world!\n" 13529(@value{GDBP}) print ibm1047_hello[0] 13530$9 = 200 'H' 13531(@value{GDBP}) 13532@end smallexample 13533 13534As above, @value{GDBN} uses the target character set for character and 13535string literals you use in expressions: 13536 13537@smallexample 13538(@value{GDBP}) print '+' 13539$10 = 78 '+' 13540(@value{GDBP}) 13541@end smallexample 13542 13543The @sc{ibm1047} character set uses the number 78 to encode the @samp{+} 13544character. 13545 13546@node Caching Target Data 13547@section Caching Data of Targets 13548@cindex caching data of targets 13549 13550@value{GDBN} caches data exchanged between the debugger and a target. 13551Each cache is associated with the address space of the inferior. 13552@xref{Inferiors Connections and Programs}, about inferior and address space. 13553Such caching generally improves performance in remote debugging 13554(@pxref{Remote Debugging}), because it reduces the overhead of the 13555remote protocol by bundling memory reads and writes into large chunks. 13556Unfortunately, simply caching everything would lead to incorrect results, 13557since @value{GDBN} does not necessarily know anything about volatile 13558values, memory-mapped I/O addresses, etc. Furthermore, in non-stop mode 13559(@pxref{Non-Stop Mode}) memory can be changed @emph{while} a gdb command 13560is executing. 13561Therefore, by default, @value{GDBN} only caches data 13562known to be on the stack@footnote{In non-stop mode, it is moderately 13563rare for a running thread to modify the stack of a stopped thread 13564in a way that would interfere with a backtrace, and caching of 13565stack reads provides a significant speed up of remote backtraces.} or 13566in the code segment. 13567Other regions of memory can be explicitly marked as 13568cacheable; @pxref{Memory Region Attributes}. 13569 13570@table @code 13571@kindex set remotecache 13572@item set remotecache on 13573@itemx set remotecache off 13574This option no longer does anything; it exists for compatibility 13575with old scripts. 13576 13577@kindex show remotecache 13578@item show remotecache 13579Show the current state of the obsolete remotecache flag. 13580 13581@kindex set stack-cache 13582@item set stack-cache on 13583@itemx set stack-cache off 13584Enable or disable caching of stack accesses. When @code{on}, use 13585caching. By default, this option is @code{on}. 13586 13587@kindex show stack-cache 13588@item show stack-cache 13589Show the current state of data caching for memory accesses. 13590 13591@kindex set code-cache 13592@item set code-cache on 13593@itemx set code-cache off 13594Enable or disable caching of code segment accesses. When @code{on}, 13595use caching. By default, this option is @code{on}. This improves 13596performance of disassembly in remote debugging. 13597 13598@kindex show code-cache 13599@item show code-cache 13600Show the current state of target memory cache for code segment 13601accesses. 13602 13603@kindex info dcache 13604@item info dcache @r{[}line@r{]} 13605Print the information about the performance of data cache of the 13606current inferior's address space. The information displayed 13607includes the dcache width and depth, and for each cache line, its 13608number, address, and how many times it was referenced. This 13609command is useful for debugging the data cache operation. 13610 13611If a line number is specified, the contents of that line will be 13612printed in hex. 13613 13614@item set dcache size @var{size} 13615@cindex dcache size 13616@kindex set dcache size 13617Set maximum number of entries in dcache (dcache depth above). 13618 13619@item set dcache line-size @var{line-size} 13620@cindex dcache line-size 13621@kindex set dcache line-size 13622Set number of bytes each dcache entry caches (dcache width above). 13623Must be a power of 2. 13624 13625@item show dcache size 13626@kindex show dcache size 13627Show maximum number of dcache entries. @xref{Caching Target Data, info dcache}. 13628 13629@item show dcache line-size 13630@kindex show dcache line-size 13631Show default size of dcache lines. 13632 13633@item maint flush dcache 13634@cindex dcache, flushing 13635@kindex maint flush dcache 13636Flush the contents (if any) of the dcache. This maintainer command is 13637useful when debugging the dcache implementation. 13638 13639@end table 13640 13641@node Searching Memory 13642@section Search Memory 13643@cindex searching memory 13644 13645Memory can be searched for a particular sequence of bytes with the 13646@code{find} command. 13647 13648@table @code 13649@kindex find 13650@item find @r{[}/@var{sn}@r{]} @var{start_addr}, +@var{len}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]} 13651@itemx find @r{[}/@var{sn}@r{]} @var{start_addr}, @var{end_addr}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]} 13652Search memory for the sequence of bytes specified by @var{val1}, @var{val2}, 13653etc. The search begins at address @var{start_addr} and continues for either 13654@var{len} bytes or through to @var{end_addr} inclusive. 13655@end table 13656 13657@var{s} and @var{n} are optional parameters. 13658They may be specified in either order, apart or together. 13659 13660@table @r 13661@item @var{s}, search query size 13662The size of each search query value. 13663 13664@table @code 13665@item b 13666bytes 13667@item h 13668halfwords (two bytes) 13669@item w 13670words (four bytes) 13671@item g 13672giant words (eight bytes) 13673@end table 13674 13675All values are interpreted in the current language. 13676This means, for example, that if the current source language is C/C@t{++} 13677then searching for the string ``hello'' includes the trailing '\0'. 13678The null terminator can be removed from searching by using casts, 13679e.g.: @samp{@{char[5]@}"hello"}. 13680 13681If the value size is not specified, it is taken from the 13682value's type in the current language. 13683This is useful when one wants to specify the search 13684pattern as a mixture of types. 13685Note that this means, for example, that in the case of C-like languages 13686a search for an untyped 0x42 will search for @samp{(int) 0x42} 13687which is typically four bytes. 13688 13689@item @var{n}, maximum number of finds 13690The maximum number of matches to print. The default is to print all finds. 13691@end table 13692 13693You can use strings as search values. Quote them with double-quotes 13694 (@code{"}). 13695The string value is copied into the search pattern byte by byte, 13696regardless of the endianness of the target and the size specification. 13697 13698The address of each match found is printed as well as a count of the 13699number of matches found. 13700 13701The address of the last value found is stored in convenience variable 13702@samp{$_}. 13703A count of the number of matches is stored in @samp{$numfound}. 13704 13705For example, if stopped at the @code{printf} in this function: 13706 13707@smallexample 13708void 13709hello () 13710@{ 13711 static char hello[] = "hello-hello"; 13712 static struct @{ char c; short s; int i; @} 13713 __attribute__ ((packed)) mixed 13714 = @{ 'c', 0x1234, 0x87654321 @}; 13715 printf ("%s\n", hello); 13716@} 13717@end smallexample 13718 13719@noindent 13720you get during debugging: 13721 13722@smallexample 13723(gdb) find &hello[0], +sizeof(hello), "hello" 137240x804956d <hello.1620+6> 137251 pattern found 13726(gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o' 137270x8049567 <hello.1620> 137280x804956d <hello.1620+6> 137292 patterns found. 13730(gdb) find &hello[0], +sizeof(hello), @{char[5]@}"hello" 137310x8049567 <hello.1620> 137320x804956d <hello.1620+6> 137332 patterns found. 13734(gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l' 137350x8049567 <hello.1620> 137361 pattern found 13737(gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321 137380x8049560 <mixed.1625> 137391 pattern found 13740(gdb) print $numfound 13741$1 = 1 13742(gdb) print $_ 13743$2 = (void *) 0x8049560 13744@end smallexample 13745 13746@node Value Sizes 13747@section Value Sizes 13748 13749Whenever @value{GDBN} prints a value memory will be allocated within 13750@value{GDBN} to hold the contents of the value. It is possible in 13751some languages with dynamic typing systems, that an invalid program 13752may indicate a value that is incorrectly large, this in turn may cause 13753@value{GDBN} to try and allocate an overly large amount of memory. 13754 13755@table @code 13756@kindex set max-value-size 13757@item set max-value-size @var{bytes} 13758@itemx set max-value-size unlimited 13759Set the maximum size of memory that @value{GDBN} will allocate for the 13760contents of a value to @var{bytes}, trying to display a value that 13761requires more memory than that will result in an error. 13762 13763Setting this variable does not effect values that have already been 13764allocated within @value{GDBN}, only future allocations. 13765 13766There's a minimum size that @code{max-value-size} can be set to in 13767order that @value{GDBN} can still operate correctly, this minimum is 13768currently 16 bytes. 13769 13770The limit applies to the results of some subexpressions as well as to 13771complete expressions. For example, an expression denoting a simple 13772integer component, such as @code{x.y.z}, may fail if the size of 13773@var{x.y} is dynamic and exceeds @var{bytes}. On the other hand, 13774@value{GDBN} is sometimes clever; the expression @code{A[i]}, where 13775@var{A} is an array variable with non-constant size, will generally 13776succeed regardless of the bounds on @var{A}, as long as the component 13777size is less than @var{bytes}. 13778 13779The default value of @code{max-value-size} is currently 64k. 13780 13781@kindex show max-value-size 13782@item show max-value-size 13783Show the maximum size of memory, in bytes, that @value{GDBN} will 13784allocate for the contents of a value. 13785@end table 13786 13787@node Optimized Code 13788@chapter Debugging Optimized Code 13789@cindex optimized code, debugging 13790@cindex debugging optimized code 13791 13792Almost all compilers support optimization. With optimization 13793disabled, the compiler generates assembly code that corresponds 13794directly to your source code, in a simplistic way. As the compiler 13795applies more powerful optimizations, the generated assembly code 13796diverges from your original source code. With help from debugging 13797information generated by the compiler, @value{GDBN} can map from 13798the running program back to constructs from your original source. 13799 13800@value{GDBN} is more accurate with optimization disabled. If you 13801can recompile without optimization, it is easier to follow the 13802progress of your program during debugging. But, there are many cases 13803where you may need to debug an optimized version. 13804 13805When you debug a program compiled with @samp{-g -O}, remember that the 13806optimizer has rearranged your code; the debugger shows you what is 13807really there. Do not be too surprised when the execution path does not 13808exactly match your source file! An extreme example: if you define a 13809variable, but never use it, @value{GDBN} never sees that 13810variable---because the compiler optimizes it out of existence. 13811 13812Some things do not work as well with @samp{-g -O} as with just 13813@samp{-g}, particularly on machines with instruction scheduling. If in 13814doubt, recompile with @samp{-g} alone, and if this fixes the problem, 13815please report it to us as a bug (including a test case!). 13816@xref{Variables}, for more information about debugging optimized code. 13817 13818@menu 13819* Inline Functions:: How @value{GDBN} presents inlining 13820* Tail Call Frames:: @value{GDBN} analysis of jumps to functions 13821@end menu 13822 13823@node Inline Functions 13824@section Inline Functions 13825@cindex inline functions, debugging 13826 13827@dfn{Inlining} is an optimization that inserts a copy of the function 13828body directly at each call site, instead of jumping to a shared 13829routine. @value{GDBN} displays inlined functions just like 13830non-inlined functions. They appear in backtraces. You can view their 13831arguments and local variables, step into them with @code{step}, skip 13832them with @code{next}, and escape from them with @code{finish}. 13833You can check whether a function was inlined by using the 13834@code{info frame} command. 13835 13836For @value{GDBN} to support inlined functions, the compiler must 13837record information about inlining in the debug information --- 13838@value{NGCC} using the @sc{dwarf 2} format does this, and several 13839other compilers do also. @value{GDBN} only supports inlined functions 13840when using @sc{dwarf 2}. Versions of @value{NGCC} before 4.1 13841do not emit two required attributes (@samp{DW_AT_call_file} and 13842@samp{DW_AT_call_line}); @value{GDBN} does not display inlined 13843function calls with earlier versions of @value{NGCC}. It instead 13844displays the arguments and local variables of inlined functions as 13845local variables in the caller. 13846 13847The body of an inlined function is directly included at its call site; 13848unlike a non-inlined function, there are no instructions devoted to 13849the call. @value{GDBN} still pretends that the call site and the 13850start of the inlined function are different instructions. Stepping to 13851the call site shows the call site, and then stepping again shows 13852the first line of the inlined function, even though no additional 13853instructions are executed. 13854 13855This makes source-level debugging much clearer; you can see both the 13856context of the call and then the effect of the call. Only stepping by 13857a single instruction using @code{stepi} or @code{nexti} does not do 13858this; single instruction steps always show the inlined body. 13859 13860There are some ways that @value{GDBN} does not pretend that inlined 13861function calls are the same as normal calls: 13862 13863@itemize @bullet 13864@item 13865Setting breakpoints at the call site of an inlined function may not 13866work, because the call site does not contain any code. @value{GDBN} 13867may incorrectly move the breakpoint to the next line of the enclosing 13868function, after the call. This limitation will be removed in a future 13869version of @value{GDBN}; until then, set a breakpoint on an earlier line 13870or inside the inlined function instead. 13871 13872@item 13873@value{GDBN} cannot locate the return value of inlined calls after 13874using the @code{finish} command. This is a limitation of compiler-generated 13875debugging information; after @code{finish}, you can step to the next line 13876and print a variable where your program stored the return value. 13877 13878@end itemize 13879 13880@node Tail Call Frames 13881@section Tail Call Frames 13882@cindex tail call frames, debugging 13883 13884Function @code{B} can call function @code{C} in its very last statement. In 13885unoptimized compilation the call of @code{C} is immediately followed by return 13886instruction at the end of @code{B} code. Optimizing compiler may replace the 13887call and return in function @code{B} into one jump to function @code{C} 13888instead. Such use of a jump instruction is called @dfn{tail call}. 13889 13890During execution of function @code{C}, there will be no indication in the 13891function call stack frames that it was tail-called from @code{B}. If function 13892@code{A} regularly calls function @code{B} which tail-calls function @code{C}, 13893then @value{GDBN} will see @code{A} as the caller of @code{C}. However, in 13894some cases @value{GDBN} can determine that @code{C} was tail-called from 13895@code{B}, and it will then create fictitious call frame for that, with the 13896return address set up as if @code{B} called @code{C} normally. 13897 13898This functionality is currently supported only by DWARF 2 debugging format and 13899the compiler has to produce @samp{DW_TAG_call_site} tags. With 13900@value{NGCC}, you need to specify @option{-O -g} during compilation, to get 13901this information. 13902 13903@kbd{info frame} command (@pxref{Frame Info}) will indicate the tail call frame 13904kind by text @code{tail call frame} such as in this sample @value{GDBN} output: 13905 13906@smallexample 13907(gdb) x/i $pc - 2 13908 0x40066b <b(int, double)+11>: jmp 0x400640 <c(int, double)> 13909(gdb) info frame 13910Stack level 1, frame at 0x7fffffffda30: 13911 rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5 13912 tail call frame, caller of frame at 0x7fffffffda30 13913 source language c++. 13914 Arglist at unknown address. 13915 Locals at unknown address, Previous frame's sp is 0x7fffffffda30 13916@end smallexample 13917 13918The detection of all the possible code path executions can find them ambiguous. 13919There is no execution history stored (possible @ref{Reverse Execution} is never 13920used for this purpose) and the last known caller could have reached the known 13921callee by multiple different jump sequences. In such case @value{GDBN} still 13922tries to show at least all the unambiguous top tail callers and all the 13923unambiguous bottom tail calees, if any. 13924 13925@table @code 13926@anchor{set debug entry-values} 13927@item set debug entry-values 13928@kindex set debug entry-values 13929When set to on, enables printing of analysis messages for both frame argument 13930values at function entry and tail calls. It will show all the possible valid 13931tail calls code paths it has considered. It will also print the intersection 13932of them with the final unambiguous (possibly partial or even empty) code path 13933result. 13934 13935@item show debug entry-values 13936@kindex show debug entry-values 13937Show the current state of analysis messages printing for both frame argument 13938values at function entry and tail calls. 13939@end table 13940 13941The analysis messages for tail calls can for example show why the virtual tail 13942call frame for function @code{c} has not been recognized (due to the indirect 13943reference by variable @code{x}): 13944 13945@smallexample 13946static void __attribute__((noinline, noclone)) c (void); 13947void (*x) (void) = c; 13948static void __attribute__((noinline, noclone)) a (void) @{ x++; @} 13949static void __attribute__((noinline, noclone)) c (void) @{ a (); @} 13950int main (void) @{ x (); return 0; @} 13951 13952Breakpoint 1, DW_OP_entry_value resolving cannot find 13953DW_TAG_call_site 0x40039a in main 13954a () at t.c:3 139553 static void __attribute__((noinline, noclone)) a (void) @{ x++; @} 13956(gdb) bt 13957#0 a () at t.c:3 13958#1 0x000000000040039a in main () at t.c:5 13959@end smallexample 13960 13961Another possibility is an ambiguous virtual tail call frames resolution: 13962 13963@smallexample 13964int i; 13965static void __attribute__((noinline, noclone)) f (void) @{ i++; @} 13966static void __attribute__((noinline, noclone)) e (void) @{ f (); @} 13967static void __attribute__((noinline, noclone)) d (void) @{ f (); @} 13968static void __attribute__((noinline, noclone)) c (void) @{ d (); @} 13969static void __attribute__((noinline, noclone)) b (void) 13970@{ if (i) c (); else e (); @} 13971static void __attribute__((noinline, noclone)) a (void) @{ b (); @} 13972int main (void) @{ a (); return 0; @} 13973 13974tailcall: initial: 0x4004d2(a) 0x4004ce(b) 0x4004b2(c) 0x4004a2(d) 13975tailcall: compare: 0x4004d2(a) 0x4004cc(b) 0x400492(e) 13976tailcall: reduced: 0x4004d2(a) | 13977(gdb) bt 13978#0 f () at t.c:2 13979#1 0x00000000004004d2 in a () at t.c:8 13980#2 0x0000000000400395 in main () at t.c:9 13981@end smallexample 13982 13983@set CALLSEQ1A @code{main@value{ARROW}a@value{ARROW}b@value{ARROW}c@value{ARROW}d@value{ARROW}f} 13984@set CALLSEQ2A @code{main@value{ARROW}a@value{ARROW}b@value{ARROW}e@value{ARROW}f} 13985 13986@c Convert CALLSEQ#A to CALLSEQ#B depending on HAVE_MAKEINFO_CLICK. 13987@ifset HAVE_MAKEINFO_CLICK 13988@set ARROW @click{} 13989@set CALLSEQ1B @clicksequence{@value{CALLSEQ1A}} 13990@set CALLSEQ2B @clicksequence{@value{CALLSEQ2A}} 13991@end ifset 13992@ifclear HAVE_MAKEINFO_CLICK 13993@set ARROW -> 13994@set CALLSEQ1B @value{CALLSEQ1A} 13995@set CALLSEQ2B @value{CALLSEQ2A} 13996@end ifclear 13997 13998Frames #0 and #2 are real, #1 is a virtual tail call frame. 13999The code can have possible execution paths @value{CALLSEQ1B} or 14000@value{CALLSEQ2B}, @value{GDBN} cannot find which one from the inferior state. 14001 14002@code{initial:} state shows some random possible calling sequence @value{GDBN} 14003has found. It then finds another possible calling sequence - that one is 14004prefixed by @code{compare:}. The non-ambiguous intersection of these two is 14005printed as the @code{reduced:} calling sequence. That one could have many 14006further @code{compare:} and @code{reduced:} statements as long as there remain 14007any non-ambiguous sequence entries. 14008 14009For the frame of function @code{b} in both cases there are different possible 14010@code{$pc} values (@code{0x4004cc} or @code{0x4004ce}), therefore this frame is 14011also ambiguous. The only non-ambiguous frame is the one for function @code{a}, 14012therefore this one is displayed to the user while the ambiguous frames are 14013omitted. 14014 14015There can be also reasons why printing of frame argument values at function 14016entry may fail: 14017 14018@smallexample 14019int v; 14020static void __attribute__((noinline, noclone)) c (int i) @{ v++; @} 14021static void __attribute__((noinline, noclone)) a (int i); 14022static void __attribute__((noinline, noclone)) b (int i) @{ a (i); @} 14023static void __attribute__((noinline, noclone)) a (int i) 14024@{ if (i) b (i - 1); else c (0); @} 14025int main (void) @{ a (5); return 0; @} 14026 14027(gdb) bt 14028#0 c (i=i@@entry=0) at t.c:2 14029#1 0x0000000000400428 in a (DW_OP_entry_value resolving has found 14030function "a" at 0x400420 can call itself via tail calls 14031i=<optimized out>) at t.c:6 14032#2 0x000000000040036e in main () at t.c:7 14033@end smallexample 14034 14035@value{GDBN} cannot find out from the inferior state if and how many times did 14036function @code{a} call itself (via function @code{b}) as these calls would be 14037tail calls. Such tail calls would modify the @code{i} variable, therefore 14038@value{GDBN} cannot be sure the value it knows would be right - @value{GDBN} 14039prints @code{<optimized out>} instead. 14040 14041@node Macros 14042@chapter C Preprocessor Macros 14043 14044Some languages, such as C and C@t{++}, provide a way to define and invoke 14045``preprocessor macros'' which expand into strings of tokens. 14046@value{GDBN} can evaluate expressions containing macro invocations, show 14047the result of macro expansion, and show a macro's definition, including 14048where it was defined. 14049 14050You may need to compile your program specially to provide @value{GDBN} 14051with information about preprocessor macros. Most compilers do not 14052include macros in their debugging information, even when you compile 14053with the @option{-g} flag. @xref{Compilation}. 14054 14055A program may define a macro at one point, remove that definition later, 14056and then provide a different definition after that. Thus, at different 14057points in the program, a macro may have different definitions, or have 14058no definition at all. If there is a current stack frame, @value{GDBN} 14059uses the macros in scope at that frame's source code line. Otherwise, 14060@value{GDBN} uses the macros in scope at the current listing location; 14061see @ref{List}. 14062 14063Whenever @value{GDBN} evaluates an expression, it always expands any 14064macro invocations present in the expression. @value{GDBN} also provides 14065the following commands for working with macros explicitly. 14066 14067@table @code 14068 14069@kindex macro expand 14070@cindex macro expansion, showing the results of preprocessor 14071@cindex preprocessor macro expansion, showing the results of 14072@cindex expanding preprocessor macros 14073@item macro expand @var{expression} 14074@itemx macro exp @var{expression} 14075Show the results of expanding all preprocessor macro invocations in 14076@var{expression}. Since @value{GDBN} simply expands macros, but does 14077not parse the result, @var{expression} need not be a valid expression; 14078it can be any string of tokens. 14079 14080@kindex macro exp1 14081@item macro expand-once @var{expression} 14082@itemx macro exp1 @var{expression} 14083@cindex expand macro once 14084@i{(This command is not yet implemented.)} Show the results of 14085expanding those preprocessor macro invocations that appear explicitly in 14086@var{expression}. Macro invocations appearing in that expansion are 14087left unchanged. This command allows you to see the effect of a 14088particular macro more clearly, without being confused by further 14089expansions. Since @value{GDBN} simply expands macros, but does not 14090parse the result, @var{expression} need not be a valid expression; it 14091can be any string of tokens. 14092 14093@kindex info macro 14094@cindex macro definition, showing 14095@cindex definition of a macro, showing 14096@cindex macros, from debug info 14097@item info macro [-a|-all] [--] @var{macro} 14098Show the current definition or all definitions of the named @var{macro}, 14099and describe the source location or compiler command-line where that 14100definition was established. The optional double dash is to signify the end of 14101argument processing and the beginning of @var{macro} for non C-like macros where 14102the macro may begin with a hyphen. 14103 14104@kindex info macros 14105@item info macros @var{location} 14106Show all macro definitions that are in effect at the location specified 14107by @var{location}, and describe the source location or compiler 14108command-line where those definitions were established. 14109 14110@kindex macro define 14111@cindex user-defined macros 14112@cindex defining macros interactively 14113@cindex macros, user-defined 14114@item macro define @var{macro} @var{replacement-list} 14115@itemx macro define @var{macro}(@var{arglist}) @var{replacement-list} 14116Introduce a definition for a preprocessor macro named @var{macro}, 14117invocations of which are replaced by the tokens given in 14118@var{replacement-list}. The first form of this command defines an 14119``object-like'' macro, which takes no arguments; the second form 14120defines a ``function-like'' macro, which takes the arguments given in 14121@var{arglist}. 14122 14123A definition introduced by this command is in scope in every 14124expression evaluated in @value{GDBN}, until it is removed with the 14125@code{macro undef} command, described below. The definition overrides 14126all definitions for @var{macro} present in the program being debugged, 14127as well as any previous user-supplied definition. 14128 14129@kindex macro undef 14130@item macro undef @var{macro} 14131Remove any user-supplied definition for the macro named @var{macro}. 14132This command only affects definitions provided with the @code{macro 14133define} command, described above; it cannot remove definitions present 14134in the program being debugged. 14135 14136@kindex macro list 14137@item macro list 14138List all the macros defined using the @code{macro define} command. 14139@end table 14140 14141@cindex macros, example of debugging with 14142Here is a transcript showing the above commands in action. First, we 14143show our source files: 14144 14145@smallexample 14146$ cat sample.c 14147#include <stdio.h> 14148#include "sample.h" 14149 14150#define M 42 14151#define ADD(x) (M + x) 14152 14153main () 14154@{ 14155#define N 28 14156 printf ("Hello, world!\n"); 14157#undef N 14158 printf ("We're so creative.\n"); 14159#define N 1729 14160 printf ("Goodbye, world!\n"); 14161@} 14162$ cat sample.h 14163#define Q < 14164$ 14165@end smallexample 14166 14167Now, we compile the program using the @sc{gnu} C compiler, 14168@value{NGCC}. We pass the @option{-gdwarf-2}@footnote{This is the 14169minimum. Recent versions of @value{NGCC} support @option{-gdwarf-3} 14170and @option{-gdwarf-4}; we recommend always choosing the most recent 14171version of DWARF.} @emph{and} @option{-g3} flags to ensure the compiler 14172includes information about preprocessor macros in the debugging 14173information. 14174 14175@smallexample 14176$ gcc -gdwarf-2 -g3 sample.c -o sample 14177$ 14178@end smallexample 14179 14180Now, we start @value{GDBN} on our sample program: 14181 14182@smallexample 14183$ gdb -nw sample 14184GNU gdb 2002-05-06-cvs 14185Copyright 2002 Free Software Foundation, Inc. 14186GDB is free software, @dots{} 14187(@value{GDBP}) 14188@end smallexample 14189 14190We can expand macros and examine their definitions, even when the 14191program is not running. @value{GDBN} uses the current listing position 14192to decide which macro definitions are in scope: 14193 14194@smallexample 14195(@value{GDBP}) list main 141963 141974 #define M 42 141985 #define ADD(x) (M + x) 141996 142007 main () 142018 @{ 142029 #define N 28 1420310 printf ("Hello, world!\n"); 1420411 #undef N 1420512 printf ("We're so creative.\n"); 14206(@value{GDBP}) info macro ADD 14207Defined at /home/jimb/gdb/macros/play/sample.c:5 14208#define ADD(x) (M + x) 14209(@value{GDBP}) info macro Q 14210Defined at /home/jimb/gdb/macros/play/sample.h:1 14211 included at /home/jimb/gdb/macros/play/sample.c:2 14212#define Q < 14213(@value{GDBP}) macro expand ADD(1) 14214expands to: (42 + 1) 14215(@value{GDBP}) macro expand-once ADD(1) 14216expands to: once (M + 1) 14217(@value{GDBP}) 14218@end smallexample 14219 14220In the example above, note that @code{macro expand-once} expands only 14221the macro invocation explicit in the original text --- the invocation of 14222@code{ADD} --- but does not expand the invocation of the macro @code{M}, 14223which was introduced by @code{ADD}. 14224 14225Once the program is running, @value{GDBN} uses the macro definitions in 14226force at the source line of the current stack frame: 14227 14228@smallexample 14229(@value{GDBP}) break main 14230Breakpoint 1 at 0x8048370: file sample.c, line 10. 14231(@value{GDBP}) run 14232Starting program: /home/jimb/gdb/macros/play/sample 14233 14234Breakpoint 1, main () at sample.c:10 1423510 printf ("Hello, world!\n"); 14236(@value{GDBP}) 14237@end smallexample 14238 14239At line 10, the definition of the macro @code{N} at line 9 is in force: 14240 14241@smallexample 14242(@value{GDBP}) info macro N 14243Defined at /home/jimb/gdb/macros/play/sample.c:9 14244#define N 28 14245(@value{GDBP}) macro expand N Q M 14246expands to: 28 < 42 14247(@value{GDBP}) print N Q M 14248$1 = 1 14249(@value{GDBP}) 14250@end smallexample 14251 14252As we step over directives that remove @code{N}'s definition, and then 14253give it a new definition, @value{GDBN} finds the definition (or lack 14254thereof) in force at each point: 14255 14256@smallexample 14257(@value{GDBP}) next 14258Hello, world! 1425912 printf ("We're so creative.\n"); 14260(@value{GDBP}) info macro N 14261The symbol `N' has no definition as a C/C++ preprocessor macro 14262at /home/jimb/gdb/macros/play/sample.c:12 14263(@value{GDBP}) next 14264We're so creative. 1426514 printf ("Goodbye, world!\n"); 14266(@value{GDBP}) info macro N 14267Defined at /home/jimb/gdb/macros/play/sample.c:13 14268#define N 1729 14269(@value{GDBP}) macro expand N Q M 14270expands to: 1729 < 42 14271(@value{GDBP}) print N Q M 14272$2 = 0 14273(@value{GDBP}) 14274@end smallexample 14275 14276In addition to source files, macros can be defined on the compilation command 14277line using the @option{-D@var{name}=@var{value}} syntax. For macros defined in 14278such a way, @value{GDBN} displays the location of their definition as line zero 14279of the source file submitted to the compiler. 14280 14281@smallexample 14282(@value{GDBP}) info macro __STDC__ 14283Defined at /home/jimb/gdb/macros/play/sample.c:0 14284-D__STDC__=1 14285(@value{GDBP}) 14286@end smallexample 14287 14288 14289@node Tracepoints 14290@chapter Tracepoints 14291@c This chapter is based on the documentation written by Michael 14292@c Snyder, David Taylor, Jim Blandy, and Elena Zannoni. 14293 14294@cindex tracepoints 14295In some applications, it is not feasible for the debugger to interrupt 14296the program's execution long enough for the developer to learn 14297anything helpful about its behavior. If the program's correctness 14298depends on its real-time behavior, delays introduced by a debugger 14299might cause the program to change its behavior drastically, or perhaps 14300fail, even when the code itself is correct. It is useful to be able 14301to observe the program's behavior without interrupting it. 14302 14303Using @value{GDBN}'s @code{trace} and @code{collect} commands, you can 14304specify locations in the program, called @dfn{tracepoints}, and 14305arbitrary expressions to evaluate when those tracepoints are reached. 14306Later, using the @code{tfind} command, you can examine the values 14307those expressions had when the program hit the tracepoints. The 14308expressions may also denote objects in memory---structures or arrays, 14309for example---whose values @value{GDBN} should record; while visiting 14310a particular tracepoint, you may inspect those objects as if they were 14311in memory at that moment. However, because @value{GDBN} records these 14312values without interacting with you, it can do so quickly and 14313unobtrusively, hopefully not disturbing the program's behavior. 14314 14315The tracepoint facility is currently available only for remote 14316targets. @xref{Targets}. In addition, your remote target must know 14317how to collect trace data. This functionality is implemented in the 14318remote stub; however, none of the stubs distributed with @value{GDBN} 14319support tracepoints as of this writing. The format of the remote 14320packets used to implement tracepoints are described in @ref{Tracepoint 14321Packets}. 14322 14323It is also possible to get trace data from a file, in a manner reminiscent 14324of corefiles; you specify the filename, and use @code{tfind} to search 14325through the file. @xref{Trace Files}, for more details. 14326 14327This chapter describes the tracepoint commands and features. 14328 14329@menu 14330* Set Tracepoints:: 14331* Analyze Collected Data:: 14332* Tracepoint Variables:: 14333* Trace Files:: 14334@end menu 14335 14336@node Set Tracepoints 14337@section Commands to Set Tracepoints 14338 14339Before running such a @dfn{trace experiment}, an arbitrary number of 14340tracepoints can be set. A tracepoint is actually a special type of 14341breakpoint (@pxref{Set Breaks}), so you can manipulate it using 14342standard breakpoint commands. For instance, as with breakpoints, 14343tracepoint numbers are successive integers starting from one, and many 14344of the commands associated with tracepoints take the tracepoint number 14345as their argument, to identify which tracepoint to work on. 14346 14347For each tracepoint, you can specify, in advance, some arbitrary set 14348of data that you want the target to collect in the trace buffer when 14349it hits that tracepoint. The collected data can include registers, 14350local variables, or global data. Later, you can use @value{GDBN} 14351commands to examine the values these data had at the time the 14352tracepoint was hit. 14353 14354Tracepoints do not support every breakpoint feature. Ignore counts on 14355tracepoints have no effect, and tracepoints cannot run @value{GDBN} 14356commands when they are hit. Tracepoints may not be thread-specific 14357either. 14358 14359@cindex fast tracepoints 14360Some targets may support @dfn{fast tracepoints}, which are inserted in 14361a different way (such as with a jump instead of a trap), that is 14362faster but possibly restricted in where they may be installed. 14363 14364@cindex static tracepoints 14365@cindex markers, static tracepoints 14366@cindex probing markers, static tracepoints 14367Regular and fast tracepoints are dynamic tracing facilities, meaning 14368that they can be used to insert tracepoints at (almost) any location 14369in the target. Some targets may also support controlling @dfn{static 14370tracepoints} from @value{GDBN}. With static tracing, a set of 14371instrumentation points, also known as @dfn{markers}, are embedded in 14372the target program, and can be activated or deactivated by name or 14373address. These are usually placed at locations which facilitate 14374investigating what the target is actually doing. @value{GDBN}'s 14375support for static tracing includes being able to list instrumentation 14376points, and attach them with @value{GDBN} defined high level 14377tracepoints that expose the whole range of convenience of 14378@value{GDBN}'s tracepoints support. Namely, support for collecting 14379registers values and values of global or local (to the instrumentation 14380point) variables; tracepoint conditions and trace state variables. 14381The act of installing a @value{GDBN} static tracepoint on an 14382instrumentation point, or marker, is referred to as @dfn{probing} a 14383static tracepoint marker. 14384 14385@code{gdbserver} supports tracepoints on some target systems. 14386@xref{Server,,Tracepoints support in @code{gdbserver}}. 14387 14388This section describes commands to set tracepoints and associated 14389conditions and actions. 14390 14391@menu 14392* Create and Delete Tracepoints:: 14393* Enable and Disable Tracepoints:: 14394* Tracepoint Passcounts:: 14395* Tracepoint Conditions:: 14396* Trace State Variables:: 14397* Tracepoint Actions:: 14398* Listing Tracepoints:: 14399* Listing Static Tracepoint Markers:: 14400* Starting and Stopping Trace Experiments:: 14401* Tracepoint Restrictions:: 14402@end menu 14403 14404@node Create and Delete Tracepoints 14405@subsection Create and Delete Tracepoints 14406 14407@table @code 14408@cindex set tracepoint 14409@kindex trace 14410@item trace @var{location} 14411The @code{trace} command is very similar to the @code{break} command. 14412Its argument @var{location} can be any valid location. 14413@xref{Specify Location}. The @code{trace} command defines a tracepoint, 14414which is a point in the target program where the debugger will briefly stop, 14415collect some data, and then allow the program to continue. Setting a tracepoint 14416or changing its actions takes effect immediately if the remote stub 14417supports the @samp{InstallInTrace} feature (@pxref{install tracepoint 14418in tracing}). 14419If remote stub doesn't support the @samp{InstallInTrace} feature, all 14420these changes don't take effect until the next @code{tstart} 14421command, and once a trace experiment is running, further changes will 14422not have any effect until the next trace experiment starts. In addition, 14423@value{GDBN} supports @dfn{pending tracepoints}---tracepoints whose 14424address is not yet resolved. (This is similar to pending breakpoints.) 14425Pending tracepoints are not downloaded to the target and not installed 14426until they are resolved. The resolution of pending tracepoints requires 14427@value{GDBN} support---when debugging with the remote target, and 14428@value{GDBN} disconnects from the remote stub (@pxref{disconnected 14429tracing}), pending tracepoints can not be resolved (and downloaded to 14430the remote stub) while @value{GDBN} is disconnected. 14431 14432Here are some examples of using the @code{trace} command: 14433 14434@smallexample 14435(@value{GDBP}) @b{trace foo.c:121} // a source file and line number 14436 14437(@value{GDBP}) @b{trace +2} // 2 lines forward 14438 14439(@value{GDBP}) @b{trace my_function} // first source line of function 14440 14441(@value{GDBP}) @b{trace *my_function} // EXACT start address of function 14442 14443(@value{GDBP}) @b{trace *0x2117c4} // an address 14444@end smallexample 14445 14446@noindent 14447You can abbreviate @code{trace} as @code{tr}. 14448 14449@item trace @var{location} if @var{cond} 14450Set a tracepoint with condition @var{cond}; evaluate the expression 14451@var{cond} each time the tracepoint is reached, and collect data only 14452if the value is nonzero---that is, if @var{cond} evaluates as true. 14453@xref{Tracepoint Conditions, ,Tracepoint Conditions}, for more 14454information on tracepoint conditions. 14455 14456@item ftrace @var{location} [ if @var{cond} ] 14457@cindex set fast tracepoint 14458@cindex fast tracepoints, setting 14459@kindex ftrace 14460The @code{ftrace} command sets a fast tracepoint. For targets that 14461support them, fast tracepoints will use a more efficient but possibly 14462less general technique to trigger data collection, such as a jump 14463instruction instead of a trap, or some sort of hardware support. It 14464may not be possible to create a fast tracepoint at the desired 14465location, in which case the command will exit with an explanatory 14466message. 14467 14468@value{GDBN} handles arguments to @code{ftrace} exactly as for 14469@code{trace}. 14470 14471On 32-bit x86-architecture systems, fast tracepoints normally need to 14472be placed at an instruction that is 5 bytes or longer, but can be 14473placed at 4-byte instructions if the low 64K of memory of the target 14474program is available to install trampolines. Some Unix-type systems, 14475such as @sc{gnu}/Linux, exclude low addresses from the program's 14476address space; but for instance with the Linux kernel it is possible 14477to let @value{GDBN} use this area by doing a @command{sysctl} command 14478to set the @code{mmap_min_addr} kernel parameter, as in 14479 14480@example 14481sudo sysctl -w vm.mmap_min_addr=32768 14482@end example 14483 14484@noindent 14485which sets the low address to 32K, which leaves plenty of room for 14486trampolines. The minimum address should be set to a page boundary. 14487 14488@item strace @var{location} [ if @var{cond} ] 14489@cindex set static tracepoint 14490@cindex static tracepoints, setting 14491@cindex probe static tracepoint marker 14492@kindex strace 14493The @code{strace} command sets a static tracepoint. For targets that 14494support it, setting a static tracepoint probes a static 14495instrumentation point, or marker, found at @var{location}. It may not 14496be possible to set a static tracepoint at the desired location, in 14497which case the command will exit with an explanatory message. 14498 14499@value{GDBN} handles arguments to @code{strace} exactly as for 14500@code{trace}, with the addition that the user can also specify 14501@code{-m @var{marker}} as @var{location}. This probes the marker 14502identified by the @var{marker} string identifier. This identifier 14503depends on the static tracepoint backend library your program is 14504using. You can find all the marker identifiers in the @samp{ID} field 14505of the @code{info static-tracepoint-markers} command output. 14506@xref{Listing Static Tracepoint Markers,,Listing Static Tracepoint 14507Markers}. For example, in the following small program using the UST 14508tracing engine: 14509 14510@smallexample 14511main () 14512@{ 14513 trace_mark(ust, bar33, "str %s", "FOOBAZ"); 14514@} 14515@end smallexample 14516 14517@noindent 14518the marker id is composed of joining the first two arguments to the 14519@code{trace_mark} call with a slash, which translates to: 14520 14521@smallexample 14522(@value{GDBP}) info static-tracepoint-markers 14523Cnt Enb ID Address What 145241 n ust/bar33 0x0000000000400ddc in main at stexample.c:22 14525 Data: "str %s" 14526[etc...] 14527@end smallexample 14528 14529@noindent 14530so you may probe the marker above with: 14531 14532@smallexample 14533(@value{GDBP}) strace -m ust/bar33 14534@end smallexample 14535 14536Static tracepoints accept an extra collect action --- @code{collect 14537$_sdata}. This collects arbitrary user data passed in the probe point 14538call to the tracing library. In the UST example above, you'll see 14539that the third argument to @code{trace_mark} is a printf-like format 14540string. The user data is then the result of running that formatting 14541string against the following arguments. Note that @code{info 14542static-tracepoint-markers} command output lists that format string in 14543the @samp{Data:} field. 14544 14545You can inspect this data when analyzing the trace buffer, by printing 14546the $_sdata variable like any other variable available to 14547@value{GDBN}. @xref{Tracepoint Actions,,Tracepoint Action Lists}. 14548 14549@vindex $tpnum 14550@cindex last tracepoint number 14551@cindex recent tracepoint number 14552@cindex tracepoint number 14553The convenience variable @code{$tpnum} records the tracepoint number 14554of the most recently set tracepoint. 14555 14556@kindex delete tracepoint 14557@cindex tracepoint deletion 14558@item delete tracepoint @r{[}@var{num}@r{]} 14559Permanently delete one or more tracepoints. With no argument, the 14560default is to delete all tracepoints. Note that the regular 14561@code{delete} command can remove tracepoints also. 14562 14563Examples: 14564 14565@smallexample 14566(@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints 14567 14568(@value{GDBP}) @b{delete trace} // remove all tracepoints 14569@end smallexample 14570 14571@noindent 14572You can abbreviate this command as @code{del tr}. 14573@end table 14574 14575@node Enable and Disable Tracepoints 14576@subsection Enable and Disable Tracepoints 14577 14578These commands are deprecated; they are equivalent to plain @code{disable} and @code{enable}. 14579 14580@table @code 14581@kindex disable tracepoint 14582@item disable tracepoint @r{[}@var{num}@r{]} 14583Disable tracepoint @var{num}, or all tracepoints if no argument 14584@var{num} is given. A disabled tracepoint will have no effect during 14585a trace experiment, but it is not forgotten. You can re-enable 14586a disabled tracepoint using the @code{enable tracepoint} command. 14587If the command is issued during a trace experiment and the debug target 14588has support for disabling tracepoints during a trace experiment, then the 14589change will be effective immediately. Otherwise, it will be applied to the 14590next trace experiment. 14591 14592@kindex enable tracepoint 14593@item enable tracepoint @r{[}@var{num}@r{]} 14594Enable tracepoint @var{num}, or all tracepoints. If this command is 14595issued during a trace experiment and the debug target supports enabling 14596tracepoints during a trace experiment, then the enabled tracepoints will 14597become effective immediately. Otherwise, they will become effective the 14598next time a trace experiment is run. 14599@end table 14600 14601@node Tracepoint Passcounts 14602@subsection Tracepoint Passcounts 14603 14604@table @code 14605@kindex passcount 14606@cindex tracepoint pass count 14607@item passcount @r{[}@var{n} @r{[}@var{num}@r{]]} 14608Set the @dfn{passcount} of a tracepoint. The passcount is a way to 14609automatically stop a trace experiment. If a tracepoint's passcount is 14610@var{n}, then the trace experiment will be automatically stopped on 14611the @var{n}'th time that tracepoint is hit. If the tracepoint number 14612@var{num} is not specified, the @code{passcount} command sets the 14613passcount of the most recently defined tracepoint. If no passcount is 14614given, the trace experiment will run until stopped explicitly by the 14615user. 14616 14617Examples: 14618 14619@smallexample 14620(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of 14621@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2} 14622 14623(@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the 14624@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// most recently defined tracepoint.} 14625(@value{GDBP}) @b{trace foo} 14626(@value{GDBP}) @b{pass 3} 14627(@value{GDBP}) @b{trace bar} 14628(@value{GDBP}) @b{pass 2} 14629(@value{GDBP}) @b{trace baz} 14630(@value{GDBP}) @b{pass 1} // Stop tracing when foo has been 14631@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// executed 3 times OR when bar has} 14632@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// been executed 2 times} 14633@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// OR when baz has been executed 1 time.} 14634@end smallexample 14635@end table 14636 14637@node Tracepoint Conditions 14638@subsection Tracepoint Conditions 14639@cindex conditional tracepoints 14640@cindex tracepoint conditions 14641 14642The simplest sort of tracepoint collects data every time your program 14643reaches a specified place. You can also specify a @dfn{condition} for 14644a tracepoint. A condition is just a Boolean expression in your 14645programming language (@pxref{Expressions, ,Expressions}). A 14646tracepoint with a condition evaluates the expression each time your 14647program reaches it, and data collection happens only if the condition 14648is true. 14649 14650Tracepoint conditions can be specified when a tracepoint is set, by 14651using @samp{if} in the arguments to the @code{trace} command. 14652@xref{Create and Delete Tracepoints, ,Setting Tracepoints}. They can 14653also be set or changed at any time with the @code{condition} command, 14654just as with breakpoints. 14655 14656Unlike breakpoint conditions, @value{GDBN} does not actually evaluate 14657the conditional expression itself. Instead, @value{GDBN} encodes the 14658expression into an agent expression (@pxref{Agent Expressions}) 14659suitable for execution on the target, independently of @value{GDBN}. 14660Global variables become raw memory locations, locals become stack 14661accesses, and so forth. 14662 14663For instance, suppose you have a function that is usually called 14664frequently, but should not be called after an error has occurred. You 14665could use the following tracepoint command to collect data about calls 14666of that function that happen while the error code is propagating 14667through the program; an unconditional tracepoint could end up 14668collecting thousands of useless trace frames that you would have to 14669search through. 14670 14671@smallexample 14672(@value{GDBP}) @kbd{trace normal_operation if errcode > 0} 14673@end smallexample 14674 14675@node Trace State Variables 14676@subsection Trace State Variables 14677@cindex trace state variables 14678 14679A @dfn{trace state variable} is a special type of variable that is 14680created and managed by target-side code. The syntax is the same as 14681that for GDB's convenience variables (a string prefixed with ``$''), 14682but they are stored on the target. They must be created explicitly, 14683using a @code{tvariable} command. They are always 64-bit signed 14684integers. 14685 14686Trace state variables are remembered by @value{GDBN}, and downloaded 14687to the target along with tracepoint information when the trace 14688experiment starts. There are no intrinsic limits on the number of 14689trace state variables, beyond memory limitations of the target. 14690 14691@cindex convenience variables, and trace state variables 14692Although trace state variables are managed by the target, you can use 14693them in print commands and expressions as if they were convenience 14694variables; @value{GDBN} will get the current value from the target 14695while the trace experiment is running. Trace state variables share 14696the same namespace as other ``$'' variables, which means that you 14697cannot have trace state variables with names like @code{$23} or 14698@code{$pc}, nor can you have a trace state variable and a convenience 14699variable with the same name. 14700 14701@table @code 14702 14703@item tvariable $@var{name} [ = @var{expression} ] 14704@kindex tvariable 14705The @code{tvariable} command creates a new trace state variable named 14706@code{$@var{name}}, and optionally gives it an initial value of 14707@var{expression}. The @var{expression} is evaluated when this command is 14708entered; the result will be converted to an integer if possible, 14709otherwise @value{GDBN} will report an error. A subsequent 14710@code{tvariable} command specifying the same name does not create a 14711variable, but instead assigns the supplied initial value to the 14712existing variable of that name, overwriting any previous initial 14713value. The default initial value is 0. 14714 14715@item info tvariables 14716@kindex info tvariables 14717List all the trace state variables along with their initial values. 14718Their current values may also be displayed, if the trace experiment is 14719currently running. 14720 14721@item delete tvariable @r{[} $@var{name} @dots{} @r{]} 14722@kindex delete tvariable 14723Delete the given trace state variables, or all of them if no arguments 14724are specified. 14725 14726@end table 14727 14728@node Tracepoint Actions 14729@subsection Tracepoint Action Lists 14730 14731@table @code 14732@kindex actions 14733@cindex tracepoint actions 14734@item actions @r{[}@var{num}@r{]} 14735This command will prompt for a list of actions to be taken when the 14736tracepoint is hit. If the tracepoint number @var{num} is not 14737specified, this command sets the actions for the one that was most 14738recently defined (so that you can define a tracepoint and then say 14739@code{actions} without bothering about its number). You specify the 14740actions themselves on the following lines, one action at a time, and 14741terminate the actions list with a line containing just @code{end}. So 14742far, the only defined actions are @code{collect}, @code{teval}, and 14743@code{while-stepping}. 14744 14745@code{actions} is actually equivalent to @code{commands} (@pxref{Break 14746Commands, ,Breakpoint Command Lists}), except that only the defined 14747actions are allowed; any other @value{GDBN} command is rejected. 14748 14749@cindex remove actions from a tracepoint 14750To remove all actions from a tracepoint, type @samp{actions @var{num}} 14751and follow it immediately with @samp{end}. 14752 14753@smallexample 14754(@value{GDBP}) @b{collect @var{data}} // collect some data 14755 14756(@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data 14757 14758(@value{GDBP}) @b{end} // signals the end of actions. 14759@end smallexample 14760 14761In the following example, the action list begins with @code{collect} 14762commands indicating the things to be collected when the tracepoint is 14763hit. Then, in order to single-step and collect additional data 14764following the tracepoint, a @code{while-stepping} command is used, 14765followed by the list of things to be collected after each step in a 14766sequence of single steps. The @code{while-stepping} command is 14767terminated by its own separate @code{end} command. Lastly, the action 14768list is terminated by an @code{end} command. 14769 14770@smallexample 14771(@value{GDBP}) @b{trace foo} 14772(@value{GDBP}) @b{actions} 14773Enter actions for tracepoint 1, one per line: 14774> collect bar,baz 14775> collect $regs 14776> while-stepping 12 14777 > collect $pc, arr[i] 14778 > end 14779end 14780@end smallexample 14781 14782@kindex collect @r{(tracepoints)} 14783@item collect@r{[}/@var{mods}@r{]} @var{expr1}, @var{expr2}, @dots{} 14784Collect values of the given expressions when the tracepoint is hit. 14785This command accepts a comma-separated list of any valid expressions. 14786In addition to global, static, or local variables, the following 14787special arguments are supported: 14788 14789@table @code 14790@item $regs 14791Collect all registers. 14792 14793@item $args 14794Collect all function arguments. 14795 14796@item $locals 14797Collect all local variables. 14798 14799@item $_ret 14800Collect the return address. This is helpful if you want to see more 14801of a backtrace. 14802 14803@emph{Note:} The return address location can not always be reliably 14804determined up front, and the wrong address / registers may end up 14805collected instead. On some architectures the reliability is higher 14806for tracepoints at function entry, while on others it's the opposite. 14807When this happens, backtracing will stop because the return address is 14808found unavailable (unless another collect rule happened to match it). 14809 14810@item $_probe_argc 14811Collects the number of arguments from the static probe at which the 14812tracepoint is located. 14813@xref{Static Probe Points}. 14814 14815@item $_probe_arg@var{n} 14816@var{n} is an integer between 0 and 11. Collects the @var{n}th argument 14817from the static probe at which the tracepoint is located. 14818@xref{Static Probe Points}. 14819 14820@item $_sdata 14821@vindex $_sdata@r{, collect} 14822Collect static tracepoint marker specific data. Only available for 14823static tracepoints. @xref{Tracepoint Actions,,Tracepoint Action 14824Lists}. On the UST static tracepoints library backend, an 14825instrumentation point resembles a @code{printf} function call. The 14826tracing library is able to collect user specified data formatted to a 14827character string using the format provided by the programmer that 14828instrumented the program. Other backends have similar mechanisms. 14829Here's an example of a UST marker call: 14830 14831@smallexample 14832 const char master_name[] = "$your_name"; 14833 trace_mark(channel1, marker1, "hello %s", master_name) 14834@end smallexample 14835 14836In this case, collecting @code{$_sdata} collects the string 14837@samp{hello $yourname}. When analyzing the trace buffer, you can 14838inspect @samp{$_sdata} like any other variable available to 14839@value{GDBN}. 14840@end table 14841 14842You can give several consecutive @code{collect} commands, each one 14843with a single argument, or one @code{collect} command with several 14844arguments separated by commas; the effect is the same. 14845 14846The optional @var{mods} changes the usual handling of the arguments. 14847@code{s} requests that pointers to chars be handled as strings, in 14848particular collecting the contents of the memory being pointed at, up 14849to the first zero. The upper bound is by default the value of the 14850@code{print elements} variable; if @code{s} is followed by a decimal 14851number, that is the upper bound instead. So for instance 14852@samp{collect/s25 mystr} collects as many as 25 characters at 14853@samp{mystr}. 14854 14855The command @code{info scope} (@pxref{Symbols, info scope}) is 14856particularly useful for figuring out what data to collect. 14857 14858@kindex teval @r{(tracepoints)} 14859@item teval @var{expr1}, @var{expr2}, @dots{} 14860Evaluate the given expressions when the tracepoint is hit. This 14861command accepts a comma-separated list of expressions. The results 14862are discarded, so this is mainly useful for assigning values to trace 14863state variables (@pxref{Trace State Variables}) without adding those 14864values to the trace buffer, as would be the case if the @code{collect} 14865action were used. 14866 14867@kindex while-stepping @r{(tracepoints)} 14868@item while-stepping @var{n} 14869Perform @var{n} single-step instruction traces after the tracepoint, 14870collecting new data after each step. The @code{while-stepping} 14871command is followed by the list of what to collect while stepping 14872(followed by its own @code{end} command): 14873 14874@smallexample 14875> while-stepping 12 14876 > collect $regs, myglobal 14877 > end 14878> 14879@end smallexample 14880 14881@noindent 14882Note that @code{$pc} is not automatically collected by 14883@code{while-stepping}; you need to explicitly collect that register if 14884you need it. You may abbreviate @code{while-stepping} as @code{ws} or 14885@code{stepping}. 14886 14887@item set default-collect @var{expr1}, @var{expr2}, @dots{} 14888@kindex set default-collect 14889@cindex default collection action 14890This variable is a list of expressions to collect at each tracepoint 14891hit. It is effectively an additional @code{collect} action prepended 14892to every tracepoint action list. The expressions are parsed 14893individually for each tracepoint, so for instance a variable named 14894@code{xyz} may be interpreted as a global for one tracepoint, and a 14895local for another, as appropriate to the tracepoint's location. 14896 14897@item show default-collect 14898@kindex show default-collect 14899Show the list of expressions that are collected by default at each 14900tracepoint hit. 14901 14902@end table 14903 14904@node Listing Tracepoints 14905@subsection Listing Tracepoints 14906 14907@table @code 14908@kindex info tracepoints @r{[}@var{n}@dots{}@r{]} 14909@kindex info tp @r{[}@var{n}@dots{}@r{]} 14910@cindex information about tracepoints 14911@item info tracepoints @r{[}@var{num}@dots{}@r{]} 14912Display information about the tracepoint @var{num}. If you don't 14913specify a tracepoint number, displays information about all the 14914tracepoints defined so far. The format is similar to that used for 14915@code{info breakpoints}; in fact, @code{info tracepoints} is the same 14916command, simply restricting itself to tracepoints. 14917 14918A tracepoint's listing may include additional information specific to 14919tracing: 14920 14921@itemize @bullet 14922@item 14923its passcount as given by the @code{passcount @var{n}} command 14924 14925@item 14926the state about installed on target of each location 14927@end itemize 14928 14929@smallexample 14930(@value{GDBP}) @b{info trace} 14931Num Type Disp Enb Address What 149321 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7 14933 while-stepping 20 14934 collect globfoo, $regs 14935 end 14936 collect globfoo2 14937 end 14938 pass count 1200 149392 tracepoint keep y <MULTIPLE> 14940 collect $eip 149412.1 y 0x0804859c in func4 at change-loc.h:35 14942 installed on target 149432.2 y 0xb7ffc480 in func4 at change-loc.h:35 14944 installed on target 149452.3 y <PENDING> set_tracepoint 149463 tracepoint keep y 0x080485b1 in foo at change-loc.c:29 14947 not installed on target 14948(@value{GDBP}) 14949@end smallexample 14950 14951@noindent 14952This command can be abbreviated @code{info tp}. 14953@end table 14954 14955@node Listing Static Tracepoint Markers 14956@subsection Listing Static Tracepoint Markers 14957 14958@table @code 14959@kindex info static-tracepoint-markers 14960@cindex information about static tracepoint markers 14961@item info static-tracepoint-markers 14962Display information about all static tracepoint markers defined in the 14963program. 14964 14965For each marker, the following columns are printed: 14966 14967@table @emph 14968@item Count 14969An incrementing counter, output to help readability. This is not a 14970stable identifier. 14971@item ID 14972The marker ID, as reported by the target. 14973@item Enabled or Disabled 14974Probed markers are tagged with @samp{y}. @samp{n} identifies marks 14975that are not enabled. 14976@item Address 14977Where the marker is in your program, as a memory address. 14978@item What 14979Where the marker is in the source for your program, as a file and line 14980number. If the debug information included in the program does not 14981allow @value{GDBN} to locate the source of the marker, this column 14982will be left blank. 14983@end table 14984 14985@noindent 14986In addition, the following information may be printed for each marker: 14987 14988@table @emph 14989@item Data 14990User data passed to the tracing library by the marker call. In the 14991UST backend, this is the format string passed as argument to the 14992marker call. 14993@item Static tracepoints probing the marker 14994The list of static tracepoints attached to the marker. 14995@end table 14996 14997@smallexample 14998(@value{GDBP}) info static-tracepoint-markers 14999Cnt ID Enb Address What 150001 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25 15001 Data: number1 %d number2 %d 15002 Probed by static tracepoints: #2 150032 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24 15004 Data: str %s 15005(@value{GDBP}) 15006@end smallexample 15007@end table 15008 15009@node Starting and Stopping Trace Experiments 15010@subsection Starting and Stopping Trace Experiments 15011 15012@table @code 15013@kindex tstart [ @var{notes} ] 15014@cindex start a new trace experiment 15015@cindex collected data discarded 15016@item tstart 15017This command starts the trace experiment, and begins collecting data. 15018It has the side effect of discarding all the data collected in the 15019trace buffer during the previous trace experiment. If any arguments 15020are supplied, they are taken as a note and stored with the trace 15021experiment's state. The notes may be arbitrary text, and are 15022especially useful with disconnected tracing in a multi-user context; 15023the notes can explain what the trace is doing, supply user contact 15024information, and so forth. 15025 15026@kindex tstop [ @var{notes} ] 15027@cindex stop a running trace experiment 15028@item tstop 15029This command stops the trace experiment. If any arguments are 15030supplied, they are recorded with the experiment as a note. This is 15031useful if you are stopping a trace started by someone else, for 15032instance if the trace is interfering with the system's behavior and 15033needs to be stopped quickly. 15034 15035@strong{Note}: a trace experiment and data collection may stop 15036automatically if any tracepoint's passcount is reached 15037(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full. 15038 15039@kindex tstatus 15040@cindex status of trace data collection 15041@cindex trace experiment, status of 15042@item tstatus 15043This command displays the status of the current trace data 15044collection. 15045@end table 15046 15047Here is an example of the commands we described so far: 15048 15049@smallexample 15050(@value{GDBP}) @b{trace gdb_c_test} 15051(@value{GDBP}) @b{actions} 15052Enter actions for tracepoint #1, one per line. 15053> collect $regs,$locals,$args 15054> while-stepping 11 15055 > collect $regs 15056 > end 15057> end 15058(@value{GDBP}) @b{tstart} 15059 [time passes @dots{}] 15060(@value{GDBP}) @b{tstop} 15061@end smallexample 15062 15063@anchor{disconnected tracing} 15064@cindex disconnected tracing 15065You can choose to continue running the trace experiment even if 15066@value{GDBN} disconnects from the target, voluntarily or 15067involuntarily. For commands such as @code{detach}, the debugger will 15068ask what you want to do with the trace. But for unexpected 15069terminations (@value{GDBN} crash, network outage), it would be 15070unfortunate to lose hard-won trace data, so the variable 15071@code{disconnected-tracing} lets you decide whether the trace should 15072continue running without @value{GDBN}. 15073 15074@table @code 15075@item set disconnected-tracing on 15076@itemx set disconnected-tracing off 15077@kindex set disconnected-tracing 15078Choose whether a tracing run should continue to run if @value{GDBN} 15079has disconnected from the target. Note that @code{detach} or 15080@code{quit} will ask you directly what to do about a running trace no 15081matter what this variable's setting, so the variable is mainly useful 15082for handling unexpected situations, such as loss of the network. 15083 15084@item show disconnected-tracing 15085@kindex show disconnected-tracing 15086Show the current choice for disconnected tracing. 15087 15088@end table 15089 15090When you reconnect to the target, the trace experiment may or may not 15091still be running; it might have filled the trace buffer in the 15092meantime, or stopped for one of the other reasons. If it is running, 15093it will continue after reconnection. 15094 15095Upon reconnection, the target will upload information about the 15096tracepoints in effect. @value{GDBN} will then compare that 15097information to the set of tracepoints currently defined, and attempt 15098to match them up, allowing for the possibility that the numbers may 15099have changed due to creation and deletion in the meantime. If one of 15100the target's tracepoints does not match any in @value{GDBN}, the 15101debugger will create a new tracepoint, so that you have a number with 15102which to specify that tracepoint. This matching-up process is 15103necessarily heuristic, and it may result in useless tracepoints being 15104created; you may simply delete them if they are of no use. 15105 15106@cindex circular trace buffer 15107If your target agent supports a @dfn{circular trace buffer}, then you 15108can run a trace experiment indefinitely without filling the trace 15109buffer; when space runs out, the agent deletes already-collected trace 15110frames, oldest first, until there is enough room to continue 15111collecting. This is especially useful if your tracepoints are being 15112hit too often, and your trace gets terminated prematurely because the 15113buffer is full. To ask for a circular trace buffer, simply set 15114@samp{circular-trace-buffer} to on. You can set this at any time, 15115including during tracing; if the agent can do it, it will change 15116buffer handling on the fly, otherwise it will not take effect until 15117the next run. 15118 15119@table @code 15120@item set circular-trace-buffer on 15121@itemx set circular-trace-buffer off 15122@kindex set circular-trace-buffer 15123Choose whether a tracing run should use a linear or circular buffer 15124for trace data. A linear buffer will not lose any trace data, but may 15125fill up prematurely, while a circular buffer will discard old trace 15126data, but it will have always room for the latest tracepoint hits. 15127 15128@item show circular-trace-buffer 15129@kindex show circular-trace-buffer 15130Show the current choice for the trace buffer. Note that this may not 15131match the agent's current buffer handling, nor is it guaranteed to 15132match the setting that might have been in effect during a past run, 15133for instance if you are looking at frames from a trace file. 15134 15135@end table 15136 15137@table @code 15138@item set trace-buffer-size @var{n} 15139@itemx set trace-buffer-size unlimited 15140@kindex set trace-buffer-size 15141Request that the target use a trace buffer of @var{n} bytes. Not all 15142targets will honor the request; they may have a compiled-in size for 15143the trace buffer, or some other limitation. Set to a value of 15144@code{unlimited} or @code{-1} to let the target use whatever size it 15145likes. This is also the default. 15146 15147@item show trace-buffer-size 15148@kindex show trace-buffer-size 15149Show the current requested size for the trace buffer. Note that this 15150will only match the actual size if the target supports size-setting, 15151and was able to handle the requested size. For instance, if the 15152target can only change buffer size between runs, this variable will 15153not reflect the change until the next run starts. Use @code{tstatus} 15154to get a report of the actual buffer size. 15155@end table 15156 15157@table @code 15158@item set trace-user @var{text} 15159@kindex set trace-user 15160 15161@item show trace-user 15162@kindex show trace-user 15163 15164@item set trace-notes @var{text} 15165@kindex set trace-notes 15166Set the trace run's notes. 15167 15168@item show trace-notes 15169@kindex show trace-notes 15170Show the trace run's notes. 15171 15172@item set trace-stop-notes @var{text} 15173@kindex set trace-stop-notes 15174Set the trace run's stop notes. The handling of the note is as for 15175@code{tstop} arguments; the set command is convenient way to fix a 15176stop note that is mistaken or incomplete. 15177 15178@item show trace-stop-notes 15179@kindex show trace-stop-notes 15180Show the trace run's stop notes. 15181 15182@end table 15183 15184@node Tracepoint Restrictions 15185@subsection Tracepoint Restrictions 15186 15187@cindex tracepoint restrictions 15188There are a number of restrictions on the use of tracepoints. As 15189described above, tracepoint data gathering occurs on the target 15190without interaction from @value{GDBN}. Thus the full capabilities of 15191the debugger are not available during data gathering, and then at data 15192examination time, you will be limited by only having what was 15193collected. The following items describe some common problems, but it 15194is not exhaustive, and you may run into additional difficulties not 15195mentioned here. 15196 15197@itemize @bullet 15198 15199@item 15200Tracepoint expressions are intended to gather objects (lvalues). Thus 15201the full flexibility of GDB's expression evaluator is not available. 15202You cannot call functions, cast objects to aggregate types, access 15203convenience variables or modify values (except by assignment to trace 15204state variables). Some language features may implicitly call 15205functions (for instance Objective-C fields with accessors), and therefore 15206cannot be collected either. 15207 15208@item 15209Collection of local variables, either individually or in bulk with 15210@code{$locals} or @code{$args}, during @code{while-stepping} may 15211behave erratically. The stepping action may enter a new scope (for 15212instance by stepping into a function), or the location of the variable 15213may change (for instance it is loaded into a register). The 15214tracepoint data recorded uses the location information for the 15215variables that is correct for the tracepoint location. When the 15216tracepoint is created, it is not possible, in general, to determine 15217where the steps of a @code{while-stepping} sequence will advance the 15218program---particularly if a conditional branch is stepped. 15219 15220@item 15221Collection of an incompletely-initialized or partially-destroyed object 15222may result in something that @value{GDBN} cannot display, or displays 15223in a misleading way. 15224 15225@item 15226When @value{GDBN} displays a pointer to character it automatically 15227dereferences the pointer to also display characters of the string 15228being pointed to. However, collecting the pointer during tracing does 15229not automatically collect the string. You need to explicitly 15230dereference the pointer and provide size information if you want to 15231collect not only the pointer, but the memory pointed to. For example, 15232@code{*ptr@@50} can be used to collect the 50 element array pointed to 15233by @code{ptr}. 15234 15235@item 15236It is not possible to collect a complete stack backtrace at a 15237tracepoint. Instead, you may collect the registers and a few hundred 15238bytes from the stack pointer with something like @code{*(unsigned char *)$esp@@300} 15239(adjust to use the name of the actual stack pointer register on your 15240target architecture, and the amount of stack you wish to capture). 15241Then the @code{backtrace} command will show a partial backtrace when 15242using a trace frame. The number of stack frames that can be examined 15243depends on the sizes of the frames in the collected stack. Note that 15244if you ask for a block so large that it goes past the bottom of the 15245stack, the target agent may report an error trying to read from an 15246invalid address. 15247 15248@item 15249If you do not collect registers at a tracepoint, @value{GDBN} can 15250infer that the value of @code{$pc} must be the same as the address of 15251the tracepoint and use that when you are looking at a trace frame 15252for that tracepoint. However, this cannot work if the tracepoint has 15253multiple locations (for instance if it was set in a function that was 15254inlined), or if it has a @code{while-stepping} loop. In those cases 15255@value{GDBN} will warn you that it can't infer @code{$pc}, and default 15256it to zero. 15257 15258@end itemize 15259 15260@node Analyze Collected Data 15261@section Using the Collected Data 15262 15263After the tracepoint experiment ends, you use @value{GDBN} commands 15264for examining the trace data. The basic idea is that each tracepoint 15265collects a trace @dfn{snapshot} every time it is hit and another 15266snapshot every time it single-steps. All these snapshots are 15267consecutively numbered from zero and go into a buffer, and you can 15268examine them later. The way you examine them is to @dfn{focus} on a 15269specific trace snapshot. When the remote stub is focused on a trace 15270snapshot, it will respond to all @value{GDBN} requests for memory and 15271registers by reading from the buffer which belongs to that snapshot, 15272rather than from @emph{real} memory or registers of the program being 15273debugged. This means that @strong{all} @value{GDBN} commands 15274(@code{print}, @code{info registers}, @code{backtrace}, etc.) will 15275behave as if we were currently debugging the program state as it was 15276when the tracepoint occurred. Any requests for data that are not in 15277the buffer will fail. 15278 15279@menu 15280* tfind:: How to select a trace snapshot 15281* tdump:: How to display all data for a snapshot 15282* save tracepoints:: How to save tracepoints for a future run 15283@end menu 15284 15285@node tfind 15286@subsection @code{tfind @var{n}} 15287 15288@kindex tfind 15289@cindex select trace snapshot 15290@cindex find trace snapshot 15291The basic command for selecting a trace snapshot from the buffer is 15292@code{tfind @var{n}}, which finds trace snapshot number @var{n}, 15293counting from zero. If no argument @var{n} is given, the next 15294snapshot is selected. 15295 15296Here are the various forms of using the @code{tfind} command. 15297 15298@table @code 15299@item tfind start 15300Find the first snapshot in the buffer. This is a synonym for 15301@code{tfind 0} (since 0 is the number of the first snapshot). 15302 15303@item tfind none 15304Stop debugging trace snapshots, resume @emph{live} debugging. 15305 15306@item tfind end 15307Same as @samp{tfind none}. 15308 15309@item tfind 15310No argument means find the next trace snapshot or find the first 15311one if no trace snapshot is selected. 15312 15313@item tfind - 15314Find the previous trace snapshot before the current one. This permits 15315retracing earlier steps. 15316 15317@item tfind tracepoint @var{num} 15318Find the next snapshot associated with tracepoint @var{num}. Search 15319proceeds forward from the last examined trace snapshot. If no 15320argument @var{num} is given, it means find the next snapshot collected 15321for the same tracepoint as the current snapshot. 15322 15323@item tfind pc @var{addr} 15324Find the next snapshot associated with the value @var{addr} of the 15325program counter. Search proceeds forward from the last examined trace 15326snapshot. If no argument @var{addr} is given, it means find the next 15327snapshot with the same value of PC as the current snapshot. 15328 15329@item tfind outside @var{addr1}, @var{addr2} 15330Find the next snapshot whose PC is outside the given range of 15331addresses (exclusive). 15332 15333@item tfind range @var{addr1}, @var{addr2} 15334Find the next snapshot whose PC is between @var{addr1} and 15335@var{addr2} (inclusive). 15336 15337@item tfind line @r{[}@var{file}:@r{]}@var{n} 15338Find the next snapshot associated with the source line @var{n}. If 15339the optional argument @var{file} is given, refer to line @var{n} in 15340that source file. Search proceeds forward from the last examined 15341trace snapshot. If no argument @var{n} is given, it means find the 15342next line other than the one currently being examined; thus saying 15343@code{tfind line} repeatedly can appear to have the same effect as 15344stepping from line to line in a @emph{live} debugging session. 15345@end table 15346 15347The default arguments for the @code{tfind} commands are specifically 15348designed to make it easy to scan through the trace buffer. For 15349instance, @code{tfind} with no argument selects the next trace 15350snapshot, and @code{tfind -} with no argument selects the previous 15351trace snapshot. So, by giving one @code{tfind} command, and then 15352simply hitting @key{RET} repeatedly you can examine all the trace 15353snapshots in order. Or, by saying @code{tfind -} and then hitting 15354@key{RET} repeatedly you can examine the snapshots in reverse order. 15355The @code{tfind line} command with no argument selects the snapshot 15356for the next source line executed. The @code{tfind pc} command with 15357no argument selects the next snapshot with the same program counter 15358(PC) as the current frame. The @code{tfind tracepoint} command with 15359no argument selects the next trace snapshot collected by the same 15360tracepoint as the current one. 15361 15362In addition to letting you scan through the trace buffer manually, 15363these commands make it easy to construct @value{GDBN} scripts that 15364scan through the trace buffer and print out whatever collected data 15365you are interested in. Thus, if we want to examine the PC, FP, and SP 15366registers from each trace frame in the buffer, we can say this: 15367 15368@smallexample 15369(@value{GDBP}) @b{tfind start} 15370(@value{GDBP}) @b{while ($trace_frame != -1)} 15371> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ 15372 $trace_frame, $pc, $sp, $fp 15373> tfind 15374> end 15375 15376Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 15377Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 15378Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 15379Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 15380Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 15381Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 15382Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 15383Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 15384Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 15385Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 15386Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 15387@end smallexample 15388 15389Or, if we want to examine the variable @code{X} at each source line in 15390the buffer: 15391 15392@smallexample 15393(@value{GDBP}) @b{tfind start} 15394(@value{GDBP}) @b{while ($trace_frame != -1)} 15395> printf "Frame %d, X == %d\n", $trace_frame, X 15396> tfind line 15397> end 15398 15399Frame 0, X = 1 15400Frame 7, X = 2 15401Frame 13, X = 255 15402@end smallexample 15403 15404@node tdump 15405@subsection @code{tdump} 15406@kindex tdump 15407@cindex dump all data collected at tracepoint 15408@cindex tracepoint data, display 15409 15410This command takes no arguments. It prints all the data collected at 15411the current trace snapshot. 15412 15413@smallexample 15414(@value{GDBP}) @b{trace 444} 15415(@value{GDBP}) @b{actions} 15416Enter actions for tracepoint #2, one per line: 15417> collect $regs, $locals, $args, gdb_long_test 15418> end 15419 15420(@value{GDBP}) @b{tstart} 15421 15422(@value{GDBP}) @b{tfind line 444} 15423#0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) 15424at gdb_test.c:444 15425444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) 15426 15427(@value{GDBP}) @b{tdump} 15428Data collected at tracepoint 2, trace frame 1: 15429d0 0xc4aa0085 -995491707 15430d1 0x18 24 15431d2 0x80 128 15432d3 0x33 51 15433d4 0x71aea3d 119204413 15434d5 0x22 34 15435d6 0xe0 224 15436d7 0x380035 3670069 15437a0 0x19e24a 1696330 15438a1 0x3000668 50333288 15439a2 0x100 256 15440a3 0x322000 3284992 15441a4 0x3000698 50333336 15442a5 0x1ad3cc 1758156 15443fp 0x30bf3c 0x30bf3c 15444sp 0x30bf34 0x30bf34 15445ps 0x0 0 15446pc 0x20b2c8 0x20b2c8 15447fpcontrol 0x0 0 15448fpstatus 0x0 0 15449fpiaddr 0x0 0 15450p = 0x20e5b4 "gdb-test" 15451p1 = (void *) 0x11 15452p2 = (void *) 0x22 15453p3 = (void *) 0x33 15454p4 = (void *) 0x44 15455p5 = (void *) 0x55 15456p6 = (void *) 0x66 15457gdb_long_test = 17 '\021' 15458 15459(@value{GDBP}) 15460@end smallexample 15461 15462@code{tdump} works by scanning the tracepoint's current collection 15463actions and printing the value of each expression listed. So 15464@code{tdump} can fail, if after a run, you change the tracepoint's 15465actions to mention variables that were not collected during the run. 15466 15467Also, for tracepoints with @code{while-stepping} loops, @code{tdump} 15468uses the collected value of @code{$pc} to distinguish between trace 15469frames that were collected at the tracepoint hit, and frames that were 15470collected while stepping. This allows it to correctly choose whether 15471to display the basic list of collections, or the collections from the 15472body of the while-stepping loop. However, if @code{$pc} was not collected, 15473then @code{tdump} will always attempt to dump using the basic collection 15474list, and may fail if a while-stepping frame does not include all the 15475same data that is collected at the tracepoint hit. 15476@c This is getting pretty arcane, example would be good. 15477 15478@node save tracepoints 15479@subsection @code{save tracepoints @var{filename}} 15480@kindex save tracepoints 15481@kindex save-tracepoints 15482@cindex save tracepoints for future sessions 15483 15484This command saves all current tracepoint definitions together with 15485their actions and passcounts, into a file @file{@var{filename}} 15486suitable for use in a later debugging session. To read the saved 15487tracepoint definitions, use the @code{source} command (@pxref{Command 15488Files}). The @w{@code{save-tracepoints}} command is a deprecated 15489alias for @w{@code{save tracepoints}} 15490 15491@node Tracepoint Variables 15492@section Convenience Variables for Tracepoints 15493@cindex tracepoint variables 15494@cindex convenience variables for tracepoints 15495 15496@table @code 15497@vindex $trace_frame 15498@item (int) $trace_frame 15499The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no 15500snapshot is selected. 15501 15502@vindex $tracepoint 15503@item (int) $tracepoint 15504The tracepoint for the current trace snapshot. 15505 15506@vindex $trace_line 15507@item (int) $trace_line 15508The line number for the current trace snapshot. 15509 15510@vindex $trace_file 15511@item (char []) $trace_file 15512The source file for the current trace snapshot. 15513 15514@vindex $trace_func 15515@item (char []) $trace_func 15516The name of the function containing @code{$tracepoint}. 15517@end table 15518 15519Note: @code{$trace_file} is not suitable for use in @code{printf}, 15520use @code{output} instead. 15521 15522Here's a simple example of using these convenience variables for 15523stepping through all the trace snapshots and printing some of their 15524data. Note that these are not the same as trace state variables, 15525which are managed by the target. 15526 15527@smallexample 15528(@value{GDBP}) @b{tfind start} 15529 15530(@value{GDBP}) @b{while $trace_frame != -1} 15531> output $trace_file 15532> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint 15533> tfind 15534> end 15535@end smallexample 15536 15537@node Trace Files 15538@section Using Trace Files 15539@cindex trace files 15540 15541In some situations, the target running a trace experiment may no 15542longer be available; perhaps it crashed, or the hardware was needed 15543for a different activity. To handle these cases, you can arrange to 15544dump the trace data into a file, and later use that file as a source 15545of trace data, via the @code{target tfile} command. 15546 15547@table @code 15548 15549@kindex tsave 15550@item tsave [ -r ] @var{filename} 15551@itemx tsave [-ctf] @var{dirname} 15552Save the trace data to @var{filename}. By default, this command 15553assumes that @var{filename} refers to the host filesystem, so if 15554necessary @value{GDBN} will copy raw trace data up from the target and 15555then save it. If the target supports it, you can also supply the 15556optional argument @code{-r} (``remote'') to direct the target to save 15557the data directly into @var{filename} in its own filesystem, which may be 15558more efficient if the trace buffer is very large. (Note, however, that 15559@code{target tfile} can only read from files accessible to the host.) 15560By default, this command will save trace frame in tfile format. 15561You can supply the optional argument @code{-ctf} to save data in CTF 15562format. The @dfn{Common Trace Format} (CTF) is proposed as a trace format 15563that can be shared by multiple debugging and tracing tools. Please go to 15564@indicateurl{http://www.efficios.com/ctf} to get more information. 15565 15566@kindex target tfile 15567@kindex tfile 15568@kindex target ctf 15569@kindex ctf 15570@item target tfile @var{filename} 15571@itemx target ctf @var{dirname} 15572Use the file named @var{filename} or directory named @var{dirname} as 15573a source of trace data. Commands that examine data work as they do with 15574a live target, but it is not possible to run any new trace experiments. 15575@code{tstatus} will report the state of the trace run at the moment 15576the data was saved, as well as the current trace frame you are examining. 15577Both @var{filename} and @var{dirname} must be on a filesystem accessible to 15578the host. 15579 15580@smallexample 15581(@value{GDBP}) target ctf ctf.ctf 15582(@value{GDBP}) tfind 15583Found trace frame 0, tracepoint 2 1558439 ++a; /* set tracepoint 1 here */ 15585(@value{GDBP}) tdump 15586Data collected at tracepoint 2, trace frame 0: 15587i = 0 15588a = 0 15589b = 1 '\001' 15590c = @{"123", "456", "789", "123", "456", "789"@} 15591d = @{@{@{a = 1, b = 2@}, @{a = 3, b = 4@}@}, @{@{a = 5, b = 6@}, @{a = 7, b = 8@}@}@} 15592(@value{GDBP}) p b 15593$1 = 1 15594@end smallexample 15595 15596@end table 15597 15598@node Overlays 15599@chapter Debugging Programs That Use Overlays 15600@cindex overlays 15601 15602If your program is too large to fit completely in your target system's 15603memory, you can sometimes use @dfn{overlays} to work around this 15604problem. @value{GDBN} provides some support for debugging programs that 15605use overlays. 15606 15607@menu 15608* How Overlays Work:: A general explanation of overlays. 15609* Overlay Commands:: Managing overlays in @value{GDBN}. 15610* Automatic Overlay Debugging:: @value{GDBN} can find out which overlays are 15611 mapped by asking the inferior. 15612* Overlay Sample Program:: A sample program using overlays. 15613@end menu 15614 15615@node How Overlays Work 15616@section How Overlays Work 15617@cindex mapped overlays 15618@cindex unmapped overlays 15619@cindex load address, overlay's 15620@cindex mapped address 15621@cindex overlay area 15622 15623Suppose you have a computer whose instruction address space is only 64 15624kilobytes long, but which has much more memory which can be accessed by 15625other means: special instructions, segment registers, or memory 15626management hardware, for example. Suppose further that you want to 15627adapt a program which is larger than 64 kilobytes to run on this system. 15628 15629One solution is to identify modules of your program which are relatively 15630independent, and need not call each other directly; call these modules 15631@dfn{overlays}. Separate the overlays from the main program, and place 15632their machine code in the larger memory. Place your main program in 15633instruction memory, but leave at least enough space there to hold the 15634largest overlay as well. 15635 15636Now, to call a function located in an overlay, you must first copy that 15637overlay's machine code from the large memory into the space set aside 15638for it in the instruction memory, and then jump to its entry point 15639there. 15640 15641@c NB: In the below the mapped area's size is greater or equal to the 15642@c size of all overlays. This is intentional to remind the developer 15643@c that overlays don't necessarily need to be the same size. 15644 15645@smallexample 15646@group 15647 Data Instruction Larger 15648Address Space Address Space Address Space 15649+-----------+ +-----------+ +-----------+ 15650| | | | | | 15651+-----------+ +-----------+ +-----------+<-- overlay 1 15652| program | | main | .----| overlay 1 | load address 15653| variables | | program | | +-----------+ 15654| and heap | | | | | | 15655+-----------+ | | | +-----------+<-- overlay 2 15656| | +-----------+ | | | load address 15657+-----------+ | | | .-| overlay 2 | 15658 | | | | | | 15659 mapped --->+-----------+ | | +-----------+ 15660 address | | | | | | 15661 | overlay | <-' | | | 15662 | area | <---' +-----------+<-- overlay 3 15663 | | <---. | | load address 15664 +-----------+ `--| overlay 3 | 15665 | | | | 15666 +-----------+ | | 15667 +-----------+ 15668 | | 15669 +-----------+ 15670 15671 @anchor{A code overlay}A code overlay 15672@end group 15673@end smallexample 15674 15675The diagram (@pxref{A code overlay}) shows a system with separate data 15676and instruction address spaces. To map an overlay, the program copies 15677its code from the larger address space to the instruction address space. 15678Since the overlays shown here all use the same mapped address, only one 15679may be mapped at a time. For a system with a single address space for 15680data and instructions, the diagram would be similar, except that the 15681program variables and heap would share an address space with the main 15682program and the overlay area. 15683 15684An overlay loaded into instruction memory and ready for use is called a 15685@dfn{mapped} overlay; its @dfn{mapped address} is its address in the 15686instruction memory. An overlay not present (or only partially present) 15687in instruction memory is called @dfn{unmapped}; its @dfn{load address} 15688is its address in the larger memory. The mapped address is also called 15689the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also 15690called the @dfn{load memory address}, or @dfn{LMA}. 15691 15692Unfortunately, overlays are not a completely transparent way to adapt a 15693program to limited instruction memory. They introduce a new set of 15694global constraints you must keep in mind as you design your program: 15695 15696@itemize @bullet 15697 15698@item 15699Before calling or returning to a function in an overlay, your program 15700must make sure that overlay is actually mapped. Otherwise, the call or 15701return will transfer control to the right address, but in the wrong 15702overlay, and your program will probably crash. 15703 15704@item 15705If the process of mapping an overlay is expensive on your system, you 15706will need to choose your overlays carefully to minimize their effect on 15707your program's performance. 15708 15709@item 15710The executable file you load onto your system must contain each 15711overlay's instructions, appearing at the overlay's load address, not its 15712mapped address. However, each overlay's instructions must be relocated 15713and its symbols defined as if the overlay were at its mapped address. 15714You can use GNU linker scripts to specify different load and relocation 15715addresses for pieces of your program; see @ref{Overlay Description,,, 15716ld.info, Using ld: the GNU linker}. 15717 15718@item 15719The procedure for loading executable files onto your system must be able 15720to load their contents into the larger address space as well as the 15721instruction and data spaces. 15722 15723@end itemize 15724 15725The overlay system described above is rather simple, and could be 15726improved in many ways: 15727 15728@itemize @bullet 15729 15730@item 15731If your system has suitable bank switch registers or memory management 15732hardware, you could use those facilities to make an overlay's load area 15733contents simply appear at their mapped address in instruction space. 15734This would probably be faster than copying the overlay to its mapped 15735area in the usual way. 15736 15737@item 15738If your overlays are small enough, you could set aside more than one 15739overlay area, and have more than one overlay mapped at a time. 15740 15741@item 15742You can use overlays to manage data, as well as instructions. In 15743general, data overlays are even less transparent to your design than 15744code overlays: whereas code overlays only require care when you call or 15745return to functions, data overlays require care every time you access 15746the data. Also, if you change the contents of a data overlay, you 15747must copy its contents back out to its load address before you can copy a 15748different data overlay into the same mapped area. 15749 15750@end itemize 15751 15752 15753@node Overlay Commands 15754@section Overlay Commands 15755 15756To use @value{GDBN}'s overlay support, each overlay in your program must 15757correspond to a separate section of the executable file. The section's 15758virtual memory address and load memory address must be the overlay's 15759mapped and load addresses. Identifying overlays with sections allows 15760@value{GDBN} to determine the appropriate address of a function or 15761variable, depending on whether the overlay is mapped or not. 15762 15763@value{GDBN}'s overlay commands all start with the word @code{overlay}; 15764you can abbreviate this as @code{ov} or @code{ovly}. The commands are: 15765 15766@table @code 15767@item overlay off 15768@kindex overlay 15769Disable @value{GDBN}'s overlay support. When overlay support is 15770disabled, @value{GDBN} assumes that all functions and variables are 15771always present at their mapped addresses. By default, @value{GDBN}'s 15772overlay support is disabled. 15773 15774@item overlay manual 15775@cindex manual overlay debugging 15776Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN} 15777relies on you to tell it which overlays are mapped, and which are not, 15778using the @code{overlay map-overlay} and @code{overlay unmap-overlay} 15779commands described below. 15780 15781@item overlay map-overlay @var{overlay} 15782@itemx overlay map @var{overlay} 15783@cindex map an overlay 15784Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must 15785be the name of the object file section containing the overlay. When an 15786overlay is mapped, @value{GDBN} assumes it can find the overlay's 15787functions and variables at their mapped addresses. @value{GDBN} assumes 15788that any other overlays whose mapped ranges overlap that of 15789@var{overlay} are now unmapped. 15790 15791@item overlay unmap-overlay @var{overlay} 15792@itemx overlay unmap @var{overlay} 15793@cindex unmap an overlay 15794Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay} 15795must be the name of the object file section containing the overlay. 15796When an overlay is unmapped, @value{GDBN} assumes it can find the 15797overlay's functions and variables at their load addresses. 15798 15799@item overlay auto 15800Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN} 15801consults a data structure the overlay manager maintains in the inferior 15802to see which overlays are mapped. For details, see @ref{Automatic 15803Overlay Debugging}. 15804 15805@item overlay load-target 15806@itemx overlay load 15807@cindex reloading the overlay table 15808Re-read the overlay table from the inferior. Normally, @value{GDBN} 15809re-reads the table @value{GDBN} automatically each time the inferior 15810stops, so this command should only be necessary if you have changed the 15811overlay mapping yourself using @value{GDBN}. This command is only 15812useful when using automatic overlay debugging. 15813 15814@item overlay list-overlays 15815@itemx overlay list 15816@cindex listing mapped overlays 15817Display a list of the overlays currently mapped, along with their mapped 15818addresses, load addresses, and sizes. 15819 15820@end table 15821 15822Normally, when @value{GDBN} prints a code address, it includes the name 15823of the function the address falls in: 15824 15825@smallexample 15826(@value{GDBP}) print main 15827$3 = @{int ()@} 0x11a0 <main> 15828@end smallexample 15829@noindent 15830When overlay debugging is enabled, @value{GDBN} recognizes code in 15831unmapped overlays, and prints the names of unmapped functions with 15832asterisks around them. For example, if @code{foo} is a function in an 15833unmapped overlay, @value{GDBN} prints it this way: 15834 15835@smallexample 15836(@value{GDBP}) overlay list 15837No sections are mapped. 15838(@value{GDBP}) print foo 15839$5 = @{int (int)@} 0x100000 <*foo*> 15840@end smallexample 15841@noindent 15842When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's 15843name normally: 15844 15845@smallexample 15846(@value{GDBP}) overlay list 15847Section .ov.foo.text, loaded at 0x100000 - 0x100034, 15848 mapped at 0x1016 - 0x104a 15849(@value{GDBP}) print foo 15850$6 = @{int (int)@} 0x1016 <foo> 15851@end smallexample 15852 15853When overlay debugging is enabled, @value{GDBN} can find the correct 15854address for functions and variables in an overlay, whether or not the 15855overlay is mapped. This allows most @value{GDBN} commands, like 15856@code{break} and @code{disassemble}, to work normally, even on unmapped 15857code. However, @value{GDBN}'s breakpoint support has some limitations: 15858 15859@itemize @bullet 15860@item 15861@cindex breakpoints in overlays 15862@cindex overlays, setting breakpoints in 15863You can set breakpoints in functions in unmapped overlays, as long as 15864@value{GDBN} can write to the overlay at its load address. 15865@item 15866@value{GDBN} can not set hardware or simulator-based breakpoints in 15867unmapped overlays. However, if you set a breakpoint at the end of your 15868overlay manager (and tell @value{GDBN} which overlays are now mapped, if 15869you are using manual overlay management), @value{GDBN} will re-set its 15870breakpoints properly. 15871@end itemize 15872 15873 15874@node Automatic Overlay Debugging 15875@section Automatic Overlay Debugging 15876@cindex automatic overlay debugging 15877 15878@value{GDBN} can automatically track which overlays are mapped and which 15879are not, given some simple co-operation from the overlay manager in the 15880inferior. If you enable automatic overlay debugging with the 15881@code{overlay auto} command (@pxref{Overlay Commands}), @value{GDBN} 15882looks in the inferior's memory for certain variables describing the 15883current state of the overlays. 15884 15885Here are the variables your overlay manager must define to support 15886@value{GDBN}'s automatic overlay debugging: 15887 15888@table @asis 15889 15890@item @code{_ovly_table}: 15891This variable must be an array of the following structures: 15892 15893@smallexample 15894struct 15895@{ 15896 /* The overlay's mapped address. */ 15897 unsigned long vma; 15898 15899 /* The size of the overlay, in bytes. */ 15900 unsigned long size; 15901 15902 /* The overlay's load address. */ 15903 unsigned long lma; 15904 15905 /* Non-zero if the overlay is currently mapped; 15906 zero otherwise. */ 15907 unsigned long mapped; 15908@} 15909@end smallexample 15910 15911@item @code{_novlys}: 15912This variable must be a four-byte signed integer, holding the total 15913number of elements in @code{_ovly_table}. 15914 15915@end table 15916 15917To decide whether a particular overlay is mapped or not, @value{GDBN} 15918looks for an entry in @w{@code{_ovly_table}} whose @code{vma} and 15919@code{lma} members equal the VMA and LMA of the overlay's section in the 15920executable file. When @value{GDBN} finds a matching entry, it consults 15921the entry's @code{mapped} member to determine whether the overlay is 15922currently mapped. 15923 15924In addition, your overlay manager may define a function called 15925@code{_ovly_debug_event}. If this function is defined, @value{GDBN} 15926will silently set a breakpoint there. If the overlay manager then 15927calls this function whenever it has changed the overlay table, this 15928will enable @value{GDBN} to accurately keep track of which overlays 15929are in program memory, and update any breakpoints that may be set 15930in overlays. This will allow breakpoints to work even if the 15931overlays are kept in ROM or other non-writable memory while they 15932are not being executed. 15933 15934@node Overlay Sample Program 15935@section Overlay Sample Program 15936@cindex overlay example program 15937 15938When linking a program which uses overlays, you must place the overlays 15939at their load addresses, while relocating them to run at their mapped 15940addresses. To do this, you must write a linker script (@pxref{Overlay 15941Description,,, ld.info, Using ld: the GNU linker}). Unfortunately, 15942since linker scripts are specific to a particular host system, target 15943architecture, and target memory layout, this manual cannot provide 15944portable sample code demonstrating @value{GDBN}'s overlay support. 15945 15946However, the @value{GDBN} source distribution does contain an overlaid 15947program, with linker scripts for a few systems, as part of its test 15948suite. The program consists of the following files from 15949@file{gdb/testsuite/gdb.base}: 15950 15951@table @file 15952@item overlays.c 15953The main program file. 15954@item ovlymgr.c 15955A simple overlay manager, used by @file{overlays.c}. 15956@item foo.c 15957@itemx bar.c 15958@itemx baz.c 15959@itemx grbx.c 15960Overlay modules, loaded and used by @file{overlays.c}. 15961@item d10v.ld 15962@itemx m32r.ld 15963Linker scripts for linking the test program on the @code{d10v-elf} 15964and @code{m32r-elf} targets. 15965@end table 15966 15967You can build the test program using the @code{d10v-elf} GCC 15968cross-compiler like this: 15969 15970@smallexample 15971$ d10v-elf-gcc -g -c overlays.c 15972$ d10v-elf-gcc -g -c ovlymgr.c 15973$ d10v-elf-gcc -g -c foo.c 15974$ d10v-elf-gcc -g -c bar.c 15975$ d10v-elf-gcc -g -c baz.c 15976$ d10v-elf-gcc -g -c grbx.c 15977$ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ 15978 baz.o grbx.o -Wl,-Td10v.ld -o overlays 15979@end smallexample 15980 15981The build process is identical for any other architecture, except that 15982you must substitute the appropriate compiler and linker script for the 15983target system for @code{d10v-elf-gcc} and @code{d10v.ld}. 15984 15985 15986@node Languages 15987@chapter Using @value{GDBN} with Different Languages 15988@cindex languages 15989 15990Although programming languages generally have common aspects, they are 15991rarely expressed in the same manner. For instance, in ANSI C, 15992dereferencing a pointer @code{p} is accomplished by @code{*p}, but in 15993Modula-2, it is accomplished by @code{p^}. Values can also be 15994represented (and displayed) differently. Hex numbers in C appear as 15995@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}. 15996 15997@cindex working language 15998Language-specific information is built into @value{GDBN} for some languages, 15999allowing you to express operations like the above in your program's 16000native language, and allowing @value{GDBN} to output values in a manner 16001consistent with the syntax of your program's native language. The 16002language you use to build expressions is called the @dfn{working 16003language}. 16004 16005@menu 16006* Setting:: Switching between source languages 16007* Show:: Displaying the language 16008* Checks:: Type and range checks 16009* Supported Languages:: Supported languages 16010* Unsupported Languages:: Unsupported languages 16011@end menu 16012 16013@node Setting 16014@section Switching Between Source Languages 16015 16016There are two ways to control the working language---either have @value{GDBN} 16017set it automatically, or select it manually yourself. You can use the 16018@code{set language} command for either purpose. On startup, @value{GDBN} 16019defaults to setting the language automatically. The working language is 16020used to determine how expressions you type are interpreted, how values 16021are printed, etc. 16022 16023In addition to the working language, every source file that 16024@value{GDBN} knows about has its own working language. For some object 16025file formats, the compiler might indicate which language a particular 16026source file is in. However, most of the time @value{GDBN} infers the 16027language from the name of the file. The language of a source file 16028controls whether C@t{++} names are demangled---this way @code{backtrace} can 16029show each frame appropriately for its own language. There is no way to 16030set the language of a source file from within @value{GDBN}, but you can 16031set the language associated with a filename extension. @xref{Show, , 16032Displaying the Language}. 16033 16034This is most commonly a problem when you use a program, such 16035as @code{cfront} or @code{f2c}, that generates C but is written in 16036another language. In that case, make the 16037program use @code{#line} directives in its C output; that way 16038@value{GDBN} will know the correct language of the source code of the original 16039program, and will display that source code, not the generated C code. 16040 16041@menu 16042* Filenames:: Filename extensions and languages. 16043* Manually:: Setting the working language manually 16044* Automatically:: Having @value{GDBN} infer the source language 16045@end menu 16046 16047@node Filenames 16048@subsection List of Filename Extensions and Languages 16049 16050If a source file name ends in one of the following extensions, then 16051@value{GDBN} infers that its language is the one indicated. 16052 16053@table @file 16054@item .ada 16055@itemx .ads 16056@itemx .adb 16057@itemx .a 16058Ada source file. 16059 16060@item .c 16061C source file 16062 16063@item .C 16064@itemx .cc 16065@itemx .cp 16066@itemx .cpp 16067@itemx .cxx 16068@itemx .c++ 16069C@t{++} source file 16070 16071@item .d 16072D source file 16073 16074@item .m 16075Objective-C source file 16076 16077@item .f 16078@itemx .F 16079Fortran source file 16080 16081@item .mod 16082Modula-2 source file 16083 16084@item .s 16085@itemx .S 16086Assembler source file. This actually behaves almost like C, but 16087@value{GDBN} does not skip over function prologues when stepping. 16088@end table 16089 16090In addition, you may set the language associated with a filename 16091extension. @xref{Show, , Displaying the Language}. 16092 16093@node Manually 16094@subsection Setting the Working Language 16095 16096If you allow @value{GDBN} to set the language automatically, 16097expressions are interpreted the same way in your debugging session and 16098your program. 16099 16100@kindex set language 16101If you wish, you may set the language manually. To do this, issue the 16102command @samp{set language @var{lang}}, where @var{lang} is the name of 16103a language, such as 16104@code{c} or @code{modula-2}. 16105For a list of the supported languages, type @samp{set language}. 16106 16107Setting the language manually prevents @value{GDBN} from updating the working 16108language automatically. This can lead to confusion if you try 16109to debug a program when the working language is not the same as the 16110source language, when an expression is acceptable to both 16111languages---but means different things. For instance, if the current 16112source file were written in C, and @value{GDBN} was parsing Modula-2, a 16113command such as: 16114 16115@smallexample 16116print a = b + c 16117@end smallexample 16118 16119@noindent 16120might not have the effect you intended. In C, this means to add 16121@code{b} and @code{c} and place the result in @code{a}. The result 16122printed would be the value of @code{a}. In Modula-2, this means to compare 16123@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value. 16124 16125@node Automatically 16126@subsection Having @value{GDBN} Infer the Source Language 16127 16128To have @value{GDBN} set the working language automatically, use 16129@samp{set language local} or @samp{set language auto}. @value{GDBN} 16130then infers the working language. That is, when your program stops in a 16131frame (usually by encountering a breakpoint), @value{GDBN} sets the 16132working language to the language recorded for the function in that 16133frame. If the language for a frame is unknown (that is, if the function 16134or block corresponding to the frame was defined in a source file that 16135does not have a recognized extension), the current working language is 16136not changed, and @value{GDBN} issues a warning. 16137 16138This may not seem necessary for most programs, which are written 16139entirely in one source language. However, program modules and libraries 16140written in one source language can be used by a main program written in 16141a different source language. Using @samp{set language auto} in this 16142case frees you from having to set the working language manually. 16143 16144@node Show 16145@section Displaying the Language 16146 16147The following commands help you find out which language is the 16148working language, and also what language source files were written in. 16149 16150@table @code 16151@item show language 16152@anchor{show language} 16153@kindex show language 16154Display the current working language. This is the 16155language you can use with commands such as @code{print} to 16156build and compute expressions that may involve variables in your program. 16157 16158@item info frame 16159@kindex info frame@r{, show the source language} 16160Display the source language for this frame. This language becomes the 16161working language if you use an identifier from this frame. 16162@xref{Frame Info, ,Information about a Frame}, to identify the other 16163information listed here. 16164 16165@item info source 16166@kindex info source@r{, show the source language} 16167Display the source language of this source file. 16168@xref{Symbols, ,Examining the Symbol Table}, to identify the other 16169information listed here. 16170@end table 16171 16172In unusual circumstances, you may have source files with extensions 16173not in the standard list. You can then set the extension associated 16174with a language explicitly: 16175 16176@table @code 16177@item set extension-language @var{ext} @var{language} 16178@kindex set extension-language 16179Tell @value{GDBN} that source files with extension @var{ext} are to be 16180assumed as written in the source language @var{language}. 16181 16182@item info extensions 16183@kindex info extensions 16184List all the filename extensions and the associated languages. 16185@end table 16186 16187@node Checks 16188@section Type and Range Checking 16189 16190Some languages are designed to guard you against making seemingly common 16191errors through a series of compile- and run-time checks. These include 16192checking the type of arguments to functions and operators and making 16193sure mathematical overflows are caught at run time. Checks such as 16194these help to ensure a program's correctness once it has been compiled 16195by eliminating type mismatches and providing active checks for range 16196errors when your program is running. 16197 16198By default @value{GDBN} checks for these errors according to the 16199rules of the current source language. Although @value{GDBN} does not check 16200the statements in your program, it can check expressions entered directly 16201into @value{GDBN} for evaluation via the @code{print} command, for example. 16202 16203@menu 16204* Type Checking:: An overview of type checking 16205* Range Checking:: An overview of range checking 16206@end menu 16207 16208@cindex type checking 16209@cindex checks, type 16210@node Type Checking 16211@subsection An Overview of Type Checking 16212 16213Some languages, such as C and C@t{++}, are strongly typed, meaning that the 16214arguments to operators and functions have to be of the correct type, 16215otherwise an error occurs. These checks prevent type mismatch 16216errors from ever causing any run-time problems. For example, 16217 16218@smallexample 16219int klass::my_method(char *b) @{ return b ? 1 : 2; @} 16220 16221(@value{GDBP}) print obj.my_method (0) 16222$1 = 2 16223@exdent but 16224(@value{GDBP}) print obj.my_method (0x1234) 16225Cannot resolve method klass::my_method to any overloaded instance 16226@end smallexample 16227 16228The second example fails because in C@t{++} the integer constant 16229@samp{0x1234} is not type-compatible with the pointer parameter type. 16230 16231For the expressions you use in @value{GDBN} commands, you can tell 16232@value{GDBN} to not enforce strict type checking or 16233to treat any mismatches as errors and abandon the expression; 16234When type checking is disabled, @value{GDBN} successfully evaluates 16235expressions like the second example above. 16236 16237Even if type checking is off, there may be other reasons 16238related to type that prevent @value{GDBN} from evaluating an expression. 16239For instance, @value{GDBN} does not know how to add an @code{int} and 16240a @code{struct foo}. These particular type errors have nothing to do 16241with the language in use and usually arise from expressions which make 16242little sense to evaluate anyway. 16243 16244@value{GDBN} provides some additional commands for controlling type checking: 16245 16246@kindex set check type 16247@kindex show check type 16248@table @code 16249@item set check type on 16250@itemx set check type off 16251Set strict type checking on or off. If any type mismatches occur in 16252evaluating an expression while type checking is on, @value{GDBN} prints a 16253message and aborts evaluation of the expression. 16254 16255@item show check type 16256Show the current setting of type checking and whether @value{GDBN} 16257is enforcing strict type checking rules. 16258@end table 16259 16260@cindex range checking 16261@cindex checks, range 16262@node Range Checking 16263@subsection An Overview of Range Checking 16264 16265In some languages (such as Modula-2), it is an error to exceed the 16266bounds of a type; this is enforced with run-time checks. Such range 16267checking is meant to ensure program correctness by making sure 16268computations do not overflow, or indices on an array element access do 16269not exceed the bounds of the array. 16270 16271For expressions you use in @value{GDBN} commands, you can tell 16272@value{GDBN} to treat range errors in one of three ways: ignore them, 16273always treat them as errors and abandon the expression, or issue 16274warnings but evaluate the expression anyway. 16275 16276A range error can result from numerical overflow, from exceeding an 16277array index bound, or when you type a constant that is not a member 16278of any type. Some languages, however, do not treat overflows as an 16279error. In many implementations of C, mathematical overflow causes the 16280result to ``wrap around'' to lower values---for example, if @var{m} is 16281the largest integer value, and @var{s} is the smallest, then 16282 16283@smallexample 16284@var{m} + 1 @result{} @var{s} 16285@end smallexample 16286 16287This, too, is specific to individual languages, and in some cases 16288specific to individual compilers or machines. @xref{Supported Languages, , 16289Supported Languages}, for further details on specific languages. 16290 16291@value{GDBN} provides some additional commands for controlling the range checker: 16292 16293@kindex set check range 16294@kindex show check range 16295@table @code 16296@item set check range auto 16297Set range checking on or off based on the current working language. 16298@xref{Supported Languages, ,Supported Languages}, for the default settings for 16299each language. 16300 16301@item set check range on 16302@itemx set check range off 16303Set range checking on or off, overriding the default setting for the 16304current working language. A warning is issued if the setting does not 16305match the language default. If a range error occurs and range checking is on, 16306then a message is printed and evaluation of the expression is aborted. 16307 16308@item set check range warn 16309Output messages when the @value{GDBN} range checker detects a range error, 16310but attempt to evaluate the expression anyway. Evaluating the 16311expression may still be impossible for other reasons, such as accessing 16312memory that the process does not own (a typical example from many Unix 16313systems). 16314 16315@item show check range 16316Show the current setting of the range checker, and whether or not it is 16317being set automatically by @value{GDBN}. 16318@end table 16319 16320@node Supported Languages 16321@section Supported Languages 16322 16323@value{GDBN} supports C, C@t{++}, D, Go, Objective-C, Fortran, 16324OpenCL C, Pascal, Rust, assembly, Modula-2, and Ada. 16325@c This is false ... 16326Some @value{GDBN} features may be used in expressions regardless of the 16327language you use: the @value{GDBN} @code{@@} and @code{::} operators, 16328and the @samp{@{type@}addr} construct (@pxref{Expressions, 16329,Expressions}) can be used with the constructs of any supported 16330language. 16331 16332The following sections detail to what degree each source language is 16333supported by @value{GDBN}. These sections are not meant to be language 16334tutorials or references, but serve only as a reference guide to what the 16335@value{GDBN} expression parser accepts, and what input and output 16336formats should look like for different languages. There are many good 16337books written on each of these languages; please look to these for a 16338language reference or tutorial. 16339 16340@menu 16341* C:: C and C@t{++} 16342* D:: D 16343* Go:: Go 16344* Objective-C:: Objective-C 16345* OpenCL C:: OpenCL C 16346* Fortran:: Fortran 16347* Pascal:: Pascal 16348* Rust:: Rust 16349* Modula-2:: Modula-2 16350* Ada:: Ada 16351@end menu 16352 16353@node C 16354@subsection C and C@t{++} 16355 16356@cindex C and C@t{++} 16357@cindex expressions in C or C@t{++} 16358 16359Since C and C@t{++} are so closely related, many features of @value{GDBN} apply 16360to both languages. Whenever this is the case, we discuss those languages 16361together. 16362 16363@cindex C@t{++} 16364@cindex @code{g++}, @sc{gnu} C@t{++} compiler 16365@cindex @sc{gnu} C@t{++} 16366The C@t{++} debugging facilities are jointly implemented by the C@t{++} 16367compiler and @value{GDBN}. Therefore, to debug your C@t{++} code 16368effectively, you must compile your C@t{++} programs with a supported 16369C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++} 16370compiler (@code{aCC}). 16371 16372@menu 16373* C Operators:: C and C@t{++} operators 16374* C Constants:: C and C@t{++} constants 16375* C Plus Plus Expressions:: C@t{++} expressions 16376* C Defaults:: Default settings for C and C@t{++} 16377* C Checks:: C and C@t{++} type and range checks 16378* Debugging C:: @value{GDBN} and C 16379* Debugging C Plus Plus:: @value{GDBN} features for C@t{++} 16380* Decimal Floating Point:: Numbers in Decimal Floating Point format 16381@end menu 16382 16383@node C Operators 16384@subsubsection C and C@t{++} Operators 16385 16386@cindex C and C@t{++} operators 16387 16388Operators must be defined on values of specific types. For instance, 16389@code{+} is defined on numbers, but not on structures. Operators are 16390often defined on groups of types. 16391 16392For the purposes of C and C@t{++}, the following definitions hold: 16393 16394@itemize @bullet 16395 16396@item 16397@emph{Integral types} include @code{int} with any of its storage-class 16398specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}. 16399 16400@item 16401@emph{Floating-point types} include @code{float}, @code{double}, and 16402@code{long double} (if supported by the target platform). 16403 16404@item 16405@emph{Pointer types} include all types defined as @code{(@var{type} *)}. 16406 16407@item 16408@emph{Scalar types} include all of the above. 16409 16410@end itemize 16411 16412@noindent 16413The following operators are supported. They are listed here 16414in order of increasing precedence: 16415 16416@table @code 16417@item , 16418The comma or sequencing operator. Expressions in a comma-separated list 16419are evaluated from left to right, with the result of the entire 16420expression being the last expression evaluated. 16421 16422@item = 16423Assignment. The value of an assignment expression is the value 16424assigned. Defined on scalar types. 16425 16426@item @var{op}= 16427Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}}, 16428and translated to @w{@code{@var{a} = @var{a op b}}}. 16429@w{@code{@var{op}=}} and @code{=} have the same precedence. The operator 16430@var{op} is any one of the operators @code{|}, @code{^}, @code{&}, 16431@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}. 16432 16433@item ?: 16434The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought 16435of as: if @var{a} then @var{b} else @var{c}. The argument @var{a} 16436should be of an integral type. 16437 16438@item || 16439Logical @sc{or}. Defined on integral types. 16440 16441@item && 16442Logical @sc{and}. Defined on integral types. 16443 16444@item | 16445Bitwise @sc{or}. Defined on integral types. 16446 16447@item ^ 16448Bitwise exclusive-@sc{or}. Defined on integral types. 16449 16450@item & 16451Bitwise @sc{and}. Defined on integral types. 16452 16453@item ==@r{, }!= 16454Equality and inequality. Defined on scalar types. The value of these 16455expressions is 0 for false and non-zero for true. 16456 16457@item <@r{, }>@r{, }<=@r{, }>= 16458Less than, greater than, less than or equal, greater than or equal. 16459Defined on scalar types. The value of these expressions is 0 for false 16460and non-zero for true. 16461 16462@item <<@r{, }>> 16463left shift, and right shift. Defined on integral types. 16464 16465@item @@ 16466The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}). 16467 16468@item +@r{, }- 16469Addition and subtraction. Defined on integral types, floating-point types and 16470pointer types. 16471 16472@item *@r{, }/@r{, }% 16473Multiplication, division, and modulus. Multiplication and division are 16474defined on integral and floating-point types. Modulus is defined on 16475integral types. 16476 16477@item ++@r{, }-- 16478Increment and decrement. When appearing before a variable, the 16479operation is performed before the variable is used in an expression; 16480when appearing after it, the variable's value is used before the 16481operation takes place. 16482 16483@item * 16484Pointer dereferencing. Defined on pointer types. Same precedence as 16485@code{++}. 16486 16487@item & 16488Address operator. Defined on variables. Same precedence as @code{++}. 16489 16490For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is 16491allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})} 16492to examine the address 16493where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is 16494stored. 16495 16496@item - 16497Negative. Defined on integral and floating-point types. Same 16498precedence as @code{++}. 16499 16500@item ! 16501Logical negation. Defined on integral types. Same precedence as 16502@code{++}. 16503 16504@item ~ 16505Bitwise complement operator. Defined on integral types. Same precedence as 16506@code{++}. 16507 16508 16509@item .@r{, }-> 16510Structure member, and pointer-to-structure member. For convenience, 16511@value{GDBN} regards the two as equivalent, choosing whether to dereference a 16512pointer based on the stored type information. 16513Defined on @code{struct} and @code{union} data. 16514 16515@item .*@r{, }->* 16516Dereferences of pointers to members. 16517 16518@item [] 16519Array indexing. @code{@var{a}[@var{i}]} is defined as 16520@code{*(@var{a}+@var{i})}. Same precedence as @code{->}. 16521 16522@item () 16523Function parameter list. Same precedence as @code{->}. 16524 16525@item :: 16526C@t{++} scope resolution operator. Defined on @code{struct}, @code{union}, 16527and @code{class} types. 16528 16529@item :: 16530Doubled colons also represent the @value{GDBN} scope operator 16531(@pxref{Expressions, ,Expressions}). Same precedence as @code{::}, 16532above. 16533@end table 16534 16535If an operator is redefined in the user code, @value{GDBN} usually 16536attempts to invoke the redefined version instead of using the operator's 16537predefined meaning. 16538 16539@node C Constants 16540@subsubsection C and C@t{++} Constants 16541 16542@cindex C and C@t{++} constants 16543 16544@value{GDBN} allows you to express the constants of C and C@t{++} in the 16545following ways: 16546 16547@itemize @bullet 16548@item 16549Integer constants are a sequence of digits. Octal constants are 16550specified by a leading @samp{0} (i.e.@: zero), and hexadecimal constants 16551by a leading @samp{0x} or @samp{0X}. Constants may also end with a letter 16552@samp{l}, specifying that the constant should be treated as a 16553@code{long} value. 16554 16555@item 16556Floating point constants are a sequence of digits, followed by a decimal 16557point, followed by a sequence of digits, and optionally followed by an 16558exponent. An exponent is of the form: 16559@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another 16560sequence of digits. The @samp{+} is optional for positive exponents. 16561A floating-point constant may also end with a letter @samp{f} or 16562@samp{F}, specifying that the constant should be treated as being of 16563the @code{float} (as opposed to the default @code{double}) type; or with 16564a letter @samp{l} or @samp{L}, which specifies a @code{long double} 16565constant. 16566 16567@item 16568Enumerated constants consist of enumerated identifiers, or their 16569integral equivalents. 16570 16571@item 16572Character constants are a single character surrounded by single quotes 16573(@code{'}), or a number---the ordinal value of the corresponding character 16574(usually its @sc{ascii} value). Within quotes, the single character may 16575be represented by a letter or by @dfn{escape sequences}, which are of 16576the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation 16577of the character's ordinal value; or of the form @samp{\@var{x}}, where 16578@samp{@var{x}} is a predefined special character---for example, 16579@samp{\n} for newline. 16580 16581Wide character constants can be written by prefixing a character 16582constant with @samp{L}, as in C. For example, @samp{L'x'} is the wide 16583form of @samp{x}. The target wide character set is used when 16584computing the value of this constant (@pxref{Character Sets}). 16585 16586@item 16587String constants are a sequence of character constants surrounded by 16588double quotes (@code{"}). Any valid character constant (as described 16589above) may appear. Double quotes within the string must be preceded by 16590a backslash, so for instance @samp{"a\"b'c"} is a string of five 16591characters. 16592 16593Wide string constants can be written by prefixing a string constant 16594with @samp{L}, as in C. The target wide character set is used when 16595computing the value of this constant (@pxref{Character Sets}). 16596 16597@item 16598Pointer constants are an integral value. You can also write pointers 16599to constants using the C operator @samp{&}. 16600 16601@item 16602Array constants are comma-separated lists surrounded by braces @samp{@{} 16603and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of 16604integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array, 16605and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers. 16606@end itemize 16607 16608@node C Plus Plus Expressions 16609@subsubsection C@t{++} Expressions 16610 16611@cindex expressions in C@t{++} 16612@value{GDBN} expression handling can interpret most C@t{++} expressions. 16613 16614@cindex debugging C@t{++} programs 16615@cindex C@t{++} compilers 16616@cindex debug formats and C@t{++} 16617@cindex @value{NGCC} and C@t{++} 16618@quotation 16619@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use 16620the proper compiler and the proper debug format. Currently, 16621@value{GDBN} works best when debugging C@t{++} code that is compiled 16622with the most recent version of @value{NGCC} possible. The DWARF 16623debugging format is preferred; @value{NGCC} defaults to this on most 16624popular platforms. Other compilers and/or debug formats are likely to 16625work badly or not at all when using @value{GDBN} to debug C@t{++} 16626code. @xref{Compilation}. 16627@end quotation 16628 16629@enumerate 16630 16631@cindex member functions 16632@item 16633Member function calls are allowed; you can use expressions like 16634 16635@smallexample 16636count = aml->GetOriginal(x, y) 16637@end smallexample 16638 16639@vindex this@r{, inside C@t{++} member functions} 16640@cindex namespace in C@t{++} 16641@item 16642While a member function is active (in the selected stack frame), your 16643expressions have the same namespace available as the member function; 16644that is, @value{GDBN} allows implicit references to the class instance 16645pointer @code{this} following the same rules as C@t{++}. @code{using} 16646declarations in the current scope are also respected by @value{GDBN}. 16647 16648@cindex call overloaded functions 16649@cindex overloaded functions, calling 16650@cindex type conversions in C@t{++} 16651@item 16652You can call overloaded functions; @value{GDBN} resolves the function 16653call to the right definition, with some restrictions. @value{GDBN} does not 16654perform overload resolution involving user-defined type conversions, 16655calls to constructors, or instantiations of templates that do not exist 16656in the program. It also cannot handle ellipsis argument lists or 16657default arguments. 16658 16659It does perform integral conversions and promotions, floating-point 16660promotions, arithmetic conversions, pointer conversions, conversions of 16661class objects to base classes, and standard conversions such as those of 16662functions or arrays to pointers; it requires an exact match on the 16663number of function arguments. 16664 16665Overload resolution is always performed, unless you have specified 16666@code{set overload-resolution off}. @xref{Debugging C Plus Plus, 16667,@value{GDBN} Features for C@t{++}}. 16668 16669You must specify @code{set overload-resolution off} in order to use an 16670explicit function signature to call an overloaded function, as in 16671@smallexample 16672p 'foo(char,int)'('x', 13) 16673@end smallexample 16674 16675The @value{GDBN} command-completion facility can simplify this; 16676see @ref{Completion, ,Command Completion}. 16677 16678@cindex reference declarations 16679@item 16680@value{GDBN} understands variables declared as C@t{++} lvalue or rvalue 16681references; you can use them in expressions just as you do in C@t{++} 16682source---they are automatically dereferenced. 16683 16684In the parameter list shown when @value{GDBN} displays a frame, the values of 16685reference variables are not displayed (unlike other variables); this 16686avoids clutter, since references are often used for large structures. 16687The @emph{address} of a reference variable is always shown, unless 16688you have specified @samp{set print address off}. 16689 16690@item 16691@value{GDBN} supports the C@t{++} name resolution operator @code{::}---your 16692expressions can use it just as expressions in your program do. Since 16693one scope may be defined in another, you can use @code{::} repeatedly if 16694necessary, for example in an expression like 16695@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows 16696resolving name scope by reference to source files, in both C and C@t{++} 16697debugging (@pxref{Variables, ,Program Variables}). 16698 16699@item 16700@value{GDBN} performs argument-dependent lookup, following the C@t{++} 16701specification. 16702@end enumerate 16703 16704@node C Defaults 16705@subsubsection C and C@t{++} Defaults 16706 16707@cindex C and C@t{++} defaults 16708 16709If you allow @value{GDBN} to set range checking automatically, it 16710defaults to @code{off} whenever the working language changes to 16711C or C@t{++}. This happens regardless of whether you or @value{GDBN} 16712selects the working language. 16713 16714If you allow @value{GDBN} to set the language automatically, it 16715recognizes source files whose names end with @file{.c}, @file{.C}, or 16716@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of 16717these files, it sets the working language to C or C@t{++}. 16718@xref{Automatically, ,Having @value{GDBN} Infer the Source Language}, 16719for further details. 16720 16721@node C Checks 16722@subsubsection C and C@t{++} Type and Range Checks 16723 16724@cindex C and C@t{++} checks 16725 16726By default, when @value{GDBN} parses C or C@t{++} expressions, strict type 16727checking is used. However, if you turn type checking off, @value{GDBN} 16728will allow certain non-standard conversions, such as promoting integer 16729constants to pointers. 16730 16731Range checking, if turned on, is done on mathematical operations. Array 16732indices are not checked, since they are often used to index a pointer 16733that is not itself an array. 16734 16735@node Debugging C 16736@subsubsection @value{GDBN} and C 16737 16738The @code{set print union} and @code{show print union} commands apply to 16739the @code{union} type. When set to @samp{on}, any @code{union} that is 16740inside a @code{struct} or @code{class} is also printed. Otherwise, it 16741appears as @samp{@{...@}}. 16742 16743The @code{@@} operator aids in the debugging of dynamic arrays, formed 16744with pointers and a memory allocation function. @xref{Expressions, 16745,Expressions}. 16746 16747@node Debugging C Plus Plus 16748@subsubsection @value{GDBN} Features for C@t{++} 16749 16750@cindex commands for C@t{++} 16751 16752Some @value{GDBN} commands are particularly useful with C@t{++}, and some are 16753designed specifically for use with C@t{++}. Here is a summary: 16754 16755@table @code 16756@cindex break in overloaded functions 16757@item @r{breakpoint menus} 16758When you want a breakpoint in a function whose name is overloaded, 16759@value{GDBN} has the capability to display a menu of possible breakpoint 16760locations to help you specify which function definition you want. 16761@xref{Ambiguous Expressions,,Ambiguous Expressions}. 16762 16763@cindex overloading in C@t{++} 16764@item rbreak @var{regex} 16765Setting breakpoints using regular expressions is helpful for setting 16766breakpoints on overloaded functions that are not members of any special 16767classes. 16768@xref{Set Breaks, ,Setting Breakpoints}. 16769 16770@cindex C@t{++} exception handling 16771@item catch throw 16772@itemx catch rethrow 16773@itemx catch catch 16774Debug C@t{++} exception handling using these commands. @xref{Set 16775Catchpoints, , Setting Catchpoints}. 16776 16777@cindex inheritance 16778@item ptype @var{typename} 16779Print inheritance relationships as well as other information for type 16780@var{typename}. 16781@xref{Symbols, ,Examining the Symbol Table}. 16782 16783@item info vtbl @var{expression}. 16784The @code{info vtbl} command can be used to display the virtual 16785method tables of the object computed by @var{expression}. This shows 16786one entry per virtual table; there may be multiple virtual tables when 16787multiple inheritance is in use. 16788 16789@cindex C@t{++} demangling 16790@item demangle @var{name} 16791Demangle @var{name}. 16792@xref{Symbols}, for a more complete description of the @code{demangle} command. 16793 16794@cindex C@t{++} symbol display 16795@item set print demangle 16796@itemx show print demangle 16797@itemx set print asm-demangle 16798@itemx show print asm-demangle 16799Control whether C@t{++} symbols display in their source form, both when 16800displaying code as C@t{++} source and when displaying disassemblies. 16801@xref{Print Settings, ,Print Settings}. 16802 16803@item set print object 16804@itemx show print object 16805Choose whether to print derived (actual) or declared types of objects. 16806@xref{Print Settings, ,Print Settings}. 16807 16808@item set print vtbl 16809@itemx show print vtbl 16810Control the format for printing virtual function tables. 16811@xref{Print Settings, ,Print Settings}. 16812(The @code{vtbl} commands do not work on programs compiled with the HP 16813ANSI C@t{++} compiler (@code{aCC}).) 16814 16815@kindex set overload-resolution 16816@cindex overloaded functions, overload resolution 16817@item set overload-resolution on 16818Enable overload resolution for C@t{++} expression evaluation. The default 16819is on. For overloaded functions, @value{GDBN} evaluates the arguments 16820and searches for a function whose signature matches the argument types, 16821using the standard C@t{++} conversion rules (see @ref{C Plus Plus 16822Expressions, ,C@t{++} Expressions}, for details). 16823If it cannot find a match, it emits a message. 16824 16825@item set overload-resolution off 16826Disable overload resolution for C@t{++} expression evaluation. For 16827overloaded functions that are not class member functions, @value{GDBN} 16828chooses the first function of the specified name that it finds in the 16829symbol table, whether or not its arguments are of the correct type. For 16830overloaded functions that are class member functions, @value{GDBN} 16831searches for a function whose signature @emph{exactly} matches the 16832argument types. 16833 16834@kindex show overload-resolution 16835@item show overload-resolution 16836Show the current setting of overload resolution. 16837 16838@item @r{Overloaded symbol names} 16839You can specify a particular definition of an overloaded symbol, using 16840the same notation that is used to declare such symbols in C@t{++}: type 16841@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can 16842also use the @value{GDBN} command-line word completion facilities to list the 16843available choices, or to finish the type list for you. 16844@xref{Completion,, Command Completion}, for details on how to do this. 16845 16846@item @r{Breakpoints in functions with ABI tags} 16847 16848The GNU C@t{++} compiler introduced the notion of ABI ``tags'', which 16849correspond to changes in the ABI of a type, function, or variable that 16850would not otherwise be reflected in a mangled name. See 16851@url{https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/} 16852for more detail. 16853 16854The ABI tags are visible in C@t{++} demangled names. For example, a 16855function that returns a std::string: 16856 16857@smallexample 16858std::string function(int); 16859@end smallexample 16860 16861@noindent 16862when compiled for the C++11 ABI is marked with the @code{cxx11} ABI 16863tag, and @value{GDBN} displays the symbol like this: 16864 16865@smallexample 16866function[abi:cxx11](int) 16867@end smallexample 16868 16869You can set a breakpoint on such functions simply as if they had no 16870tag. For example: 16871 16872@smallexample 16873(gdb) b function(int) 16874Breakpoint 2 at 0x40060d: file main.cc, line 10. 16875(gdb) info breakpoints 16876Num Type Disp Enb Address What 168771 breakpoint keep y 0x0040060d in function[abi:cxx11](int) 16878 at main.cc:10 16879@end smallexample 16880 16881On the rare occasion you need to disambiguate between different ABI 16882tags, you can do so by simply including the ABI tag in the function 16883name, like: 16884 16885@smallexample 16886(@value{GDBP}) b ambiguous[abi:other_tag](int) 16887@end smallexample 16888@end table 16889 16890@node Decimal Floating Point 16891@subsubsection Decimal Floating Point format 16892@cindex decimal floating point format 16893 16894@value{GDBN} can examine, set and perform computations with numbers in 16895decimal floating point format, which in the C language correspond to the 16896@code{_Decimal32}, @code{_Decimal64} and @code{_Decimal128} types as 16897specified by the extension to support decimal floating-point arithmetic. 16898 16899There are two encodings in use, depending on the architecture: BID (Binary 16900Integer Decimal) for x86 and x86-64, and DPD (Densely Packed Decimal) for 16901PowerPC and S/390. @value{GDBN} will use the appropriate encoding for the 16902configured target. 16903 16904Because of a limitation in @file{libdecnumber}, the library used by @value{GDBN} 16905to manipulate decimal floating point numbers, it is not possible to convert 16906(using a cast, for example) integers wider than 32-bit to decimal float. 16907 16908In addition, in order to imitate @value{GDBN}'s behaviour with binary floating 16909point computations, error checking in decimal float operations ignores 16910underflow, overflow and divide by zero exceptions. 16911 16912In the PowerPC architecture, @value{GDBN} provides a set of pseudo-registers 16913to inspect @code{_Decimal128} values stored in floating point registers. 16914See @ref{PowerPC,,PowerPC} for more details. 16915 16916@node D 16917@subsection D 16918 16919@cindex D 16920@value{GDBN} can be used to debug programs written in D and compiled with 16921GDC, LDC or DMD compilers. Currently @value{GDBN} supports only one D 16922specific feature --- dynamic arrays. 16923 16924@node Go 16925@subsection Go 16926 16927@cindex Go (programming language) 16928@value{GDBN} can be used to debug programs written in Go and compiled with 16929@file{gccgo} or @file{6g} compilers. 16930 16931Here is a summary of the Go-specific features and restrictions: 16932 16933@table @code 16934@cindex current Go package 16935@item The current Go package 16936The name of the current package does not need to be specified when 16937specifying global variables and functions. 16938 16939For example, given the program: 16940 16941@example 16942package main 16943var myglob = "Shall we?" 16944func main () @{ 16945 // ... 16946@} 16947@end example 16948 16949When stopped inside @code{main} either of these work: 16950 16951@example 16952(gdb) p myglob 16953(gdb) p main.myglob 16954@end example 16955 16956@cindex builtin Go types 16957@item Builtin Go types 16958The @code{string} type is recognized by @value{GDBN} and is printed 16959as a string. 16960 16961@cindex builtin Go functions 16962@item Builtin Go functions 16963The @value{GDBN} expression parser recognizes the @code{unsafe.Sizeof} 16964function and handles it internally. 16965 16966@cindex restrictions on Go expressions 16967@item Restrictions on Go expressions 16968All Go operators are supported except @code{&^}. 16969The Go @code{_} ``blank identifier'' is not supported. 16970Automatic dereferencing of pointers is not supported. 16971@end table 16972 16973@node Objective-C 16974@subsection Objective-C 16975 16976@cindex Objective-C 16977This section provides information about some commands and command 16978options that are useful for debugging Objective-C code. See also 16979@ref{Symbols, info classes}, and @ref{Symbols, info selectors}, for a 16980few more commands specific to Objective-C support. 16981 16982@menu 16983* Method Names in Commands:: 16984* The Print Command with Objective-C:: 16985@end menu 16986 16987@node Method Names in Commands 16988@subsubsection Method Names in Commands 16989 16990The following commands have been extended to accept Objective-C method 16991names as line specifications: 16992 16993@kindex clear@r{, and Objective-C} 16994@kindex break@r{, and Objective-C} 16995@kindex info line@r{, and Objective-C} 16996@kindex jump@r{, and Objective-C} 16997@kindex list@r{, and Objective-C} 16998@itemize 16999@item @code{clear} 17000@item @code{break} 17001@item @code{info line} 17002@item @code{jump} 17003@item @code{list} 17004@end itemize 17005 17006A fully qualified Objective-C method name is specified as 17007 17008@smallexample 17009-[@var{Class} @var{methodName}] 17010@end smallexample 17011 17012where the minus sign is used to indicate an instance method and a 17013plus sign (not shown) is used to indicate a class method. The class 17014name @var{Class} and method name @var{methodName} are enclosed in 17015brackets, similar to the way messages are specified in Objective-C 17016source code. For example, to set a breakpoint at the @code{create} 17017instance method of class @code{Fruit} in the program currently being 17018debugged, enter: 17019 17020@smallexample 17021break -[Fruit create] 17022@end smallexample 17023 17024To list ten program lines around the @code{initialize} class method, 17025enter: 17026 17027@smallexample 17028list +[NSText initialize] 17029@end smallexample 17030 17031In the current version of @value{GDBN}, the plus or minus sign is 17032required. In future versions of @value{GDBN}, the plus or minus 17033sign will be optional, but you can use it to narrow the search. It 17034is also possible to specify just a method name: 17035 17036@smallexample 17037break create 17038@end smallexample 17039 17040You must specify the complete method name, including any colons. If 17041your program's source files contain more than one @code{create} method, 17042you'll be presented with a numbered list of classes that implement that 17043method. Indicate your choice by number, or type @samp{0} to exit if 17044none apply. 17045 17046As another example, to clear a breakpoint established at the 17047@code{makeKeyAndOrderFront:} method of the @code{NSWindow} class, enter: 17048 17049@smallexample 17050clear -[NSWindow makeKeyAndOrderFront:] 17051@end smallexample 17052 17053@node The Print Command with Objective-C 17054@subsubsection The Print Command With Objective-C 17055@cindex Objective-C, print objects 17056@kindex print-object 17057@kindex po @r{(@code{print-object})} 17058 17059The print command has also been extended to accept methods. For example: 17060 17061@smallexample 17062print -[@var{object} hash] 17063@end smallexample 17064 17065@cindex print an Objective-C object description 17066@cindex @code{_NSPrintForDebugger}, and printing Objective-C objects 17067@noindent 17068will tell @value{GDBN} to send the @code{hash} message to @var{object} 17069and print the result. Also, an additional command has been added, 17070@code{print-object} or @code{po} for short, which is meant to print 17071the description of an object. However, this command may only work 17072with certain Objective-C libraries that have a particular hook 17073function, @code{_NSPrintForDebugger}, defined. 17074 17075@node OpenCL C 17076@subsection OpenCL C 17077 17078@cindex OpenCL C 17079This section provides information about @value{GDBN}s OpenCL C support. 17080 17081@menu 17082* OpenCL C Datatypes:: 17083* OpenCL C Expressions:: 17084* OpenCL C Operators:: 17085@end menu 17086 17087@node OpenCL C Datatypes 17088@subsubsection OpenCL C Datatypes 17089 17090@cindex OpenCL C Datatypes 17091@value{GDBN} supports the builtin scalar and vector datatypes specified 17092by OpenCL 1.1. In addition the half- and double-precision floating point 17093data types of the @code{cl_khr_fp16} and @code{cl_khr_fp64} OpenCL 17094extensions are also known to @value{GDBN}. 17095 17096@node OpenCL C Expressions 17097@subsubsection OpenCL C Expressions 17098 17099@cindex OpenCL C Expressions 17100@value{GDBN} supports accesses to vector components including the access as 17101lvalue where possible. Since OpenCL C is based on C99 most C expressions 17102supported by @value{GDBN} can be used as well. 17103 17104@node OpenCL C Operators 17105@subsubsection OpenCL C Operators 17106 17107@cindex OpenCL C Operators 17108@value{GDBN} supports the operators specified by OpenCL 1.1 for scalar and 17109vector data types. 17110 17111@node Fortran 17112@subsection Fortran 17113@cindex Fortran-specific support in @value{GDBN} 17114 17115@value{GDBN} can be used to debug programs written in Fortran, but it 17116currently supports only the features of Fortran 77 language. 17117 17118@cindex trailing underscore, in Fortran symbols 17119Some Fortran compilers (@sc{gnu} Fortran 77 and Fortran 95 compilers 17120among them) append an underscore to the names of variables and 17121functions. When you debug programs compiled by those compilers, you 17122will need to refer to variables and functions with a trailing 17123underscore. 17124 17125@menu 17126* Fortran Operators:: Fortran operators and expressions 17127* Fortran Defaults:: Default settings for Fortran 17128* Special Fortran Commands:: Special @value{GDBN} commands for Fortran 17129@end menu 17130 17131@node Fortran Operators 17132@subsubsection Fortran Operators and Expressions 17133 17134@cindex Fortran operators and expressions 17135 17136Operators must be defined on values of specific types. For instance, 17137@code{+} is defined on numbers, but not on characters or other non- 17138arithmetic types. Operators are often defined on groups of types. 17139 17140@table @code 17141@item ** 17142The exponentiation operator. It raises the first operand to the power 17143of the second one. 17144 17145@item : 17146The range operator. Normally used in the form of array(low:high) to 17147represent a section of array. 17148 17149@item % 17150The access component operator. Normally used to access elements in derived 17151types. Also suitable for unions. As unions aren't part of regular Fortran, 17152this can only happen when accessing a register that uses a gdbarch-defined 17153union type. 17154@item :: 17155The scope operator. Normally used to access variables in modules or 17156to set breakpoints on subroutines nested in modules or in other 17157subroutines (internal subroutines). 17158@end table 17159 17160@node Fortran Defaults 17161@subsubsection Fortran Defaults 17162 17163@cindex Fortran Defaults 17164 17165Fortran symbols are usually case-insensitive, so @value{GDBN} by 17166default uses case-insensitive matches for Fortran symbols. You can 17167change that with the @samp{set case-insensitive} command, see 17168@ref{Symbols}, for the details. 17169 17170@node Special Fortran Commands 17171@subsubsection Special Fortran Commands 17172 17173@cindex Special Fortran commands 17174 17175@value{GDBN} has some commands to support Fortran-specific features, 17176such as displaying common blocks. 17177 17178@table @code 17179@cindex @code{COMMON} blocks, Fortran 17180@kindex info common 17181@item info common @r{[}@var{common-name}@r{]} 17182This command prints the values contained in the Fortran @code{COMMON} 17183block whose name is @var{common-name}. With no argument, the names of 17184all @code{COMMON} blocks visible at the current program location are 17185printed. 17186@cindex arrays slices (Fortran) 17187@kindex set fortran repack-array-slices 17188@kindex show fortran repack-array-slices 17189@item set fortran repack-array-slices [on|off] 17190@item show fortran repack-array-slices 17191When taking a slice from an array, a Fortran compiler can choose to 17192either produce an array descriptor that describes the slice in place, 17193or it may repack the slice, copying the elements of the slice into a 17194new region of memory. 17195 17196When this setting is on, then @value{GDBN} will also repack array 17197slices in some situations. When this setting is off, then 17198@value{GDBN} will create array descriptors for slices that reference 17199the original data in place. 17200 17201@value{GDBN} will never repack an array slice if the data for the 17202slice is contiguous within the original array. 17203 17204@value{GDBN} will always repack string slices if the data for the 17205slice is non-contiguous within the original string as @value{GDBN} 17206does not support printing non-contiguous strings. 17207 17208The default for this setting is @code{off}. 17209@end table 17210 17211@node Pascal 17212@subsection Pascal 17213 17214@cindex Pascal support in @value{GDBN}, limitations 17215Debugging Pascal programs which use sets, subranges, file variables, or 17216nested functions does not currently work. @value{GDBN} does not support 17217entering expressions, printing values, or similar features using Pascal 17218syntax. 17219 17220The Pascal-specific command @code{set print pascal_static-members} 17221controls whether static members of Pascal objects are displayed. 17222@xref{Print Settings, pascal_static-members}. 17223 17224@node Rust 17225@subsection Rust 17226 17227@value{GDBN} supports the @url{https://www.rust-lang.org/, Rust 17228Programming Language}. Type- and value-printing, and expression 17229parsing, are reasonably complete. However, there are a few 17230peculiarities and holes to be aware of. 17231 17232@itemize @bullet 17233@item 17234Linespecs (@pxref{Specify Location}) are never relative to the current 17235crate. Instead, they act as if there were a global namespace of 17236crates, somewhat similar to the way @code{extern crate} behaves. 17237 17238That is, if @value{GDBN} is stopped at a breakpoint in a function in 17239crate @samp{A}, module @samp{B}, then @code{break B::f} will attempt 17240to set a breakpoint in a function named @samp{f} in a crate named 17241@samp{B}. 17242 17243As a consequence of this approach, linespecs also cannot refer to 17244items using @samp{self::} or @samp{super::}. 17245 17246@item 17247Because @value{GDBN} implements Rust name-lookup semantics in 17248expressions, it will sometimes prepend the current crate to a name. 17249For example, if @value{GDBN} is stopped at a breakpoint in the crate 17250@samp{K}, then @code{print ::x::y} will try to find the symbol 17251@samp{K::x::y}. 17252 17253However, since it is useful to be able to refer to other crates when 17254debugging, @value{GDBN} provides the @code{extern} extension to 17255circumvent this. To use the extension, just put @code{extern} before 17256a path expression to refer to the otherwise unavailable ``global'' 17257scope. 17258 17259In the above example, if you wanted to refer to the symbol @samp{y} in 17260the crate @samp{x}, you would use @code{print extern x::y}. 17261 17262@item 17263The Rust expression evaluator does not support ``statement-like'' 17264expressions such as @code{if} or @code{match}, or lambda expressions. 17265 17266@item 17267Tuple expressions are not implemented. 17268 17269@item 17270The Rust expression evaluator does not currently implement the 17271@code{Drop} trait. Objects that may be created by the evaluator will 17272never be destroyed. 17273 17274@item 17275@value{GDBN} does not implement type inference for generics. In order 17276to call generic functions or otherwise refer to generic items, you 17277will have to specify the type parameters manually. 17278 17279@item 17280@value{GDBN} currently uses the C@t{++} demangler for Rust. In most 17281cases this does not cause any problems. However, in an expression 17282context, completing a generic function name will give syntactically 17283invalid results. This happens because Rust requires the @samp{::} 17284operator between the function name and its generic arguments. For 17285example, @value{GDBN} might provide a completion like 17286@code{crate::f<u32>}, where the parser would require 17287@code{crate::f::<u32>}. 17288 17289@item 17290As of this writing, the Rust compiler (version 1.8) has a few holes in 17291the debugging information it generates. These holes prevent certain 17292features from being implemented by @value{GDBN}: 17293@itemize @bullet 17294 17295@item 17296Method calls cannot be made via traits. 17297 17298@item 17299Operator overloading is not implemented. 17300 17301@item 17302When debugging in a monomorphized function, you cannot use the generic 17303type names. 17304 17305@item 17306The type @code{Self} is not available. 17307 17308@item 17309@code{use} statements are not available, so some names may not be 17310available in the crate. 17311@end itemize 17312@end itemize 17313 17314@node Modula-2 17315@subsection Modula-2 17316 17317@cindex Modula-2, @value{GDBN} support 17318 17319The extensions made to @value{GDBN} to support Modula-2 only support 17320output from the @sc{gnu} Modula-2 compiler (which is currently being 17321developed). Other Modula-2 compilers are not currently supported, and 17322attempting to debug executables produced by them is most likely 17323to give an error as @value{GDBN} reads in the executable's symbol 17324table. 17325 17326@cindex expressions in Modula-2 17327@menu 17328* M2 Operators:: Built-in operators 17329* Built-In Func/Proc:: Built-in functions and procedures 17330* M2 Constants:: Modula-2 constants 17331* M2 Types:: Modula-2 types 17332* M2 Defaults:: Default settings for Modula-2 17333* Deviations:: Deviations from standard Modula-2 17334* M2 Checks:: Modula-2 type and range checks 17335* M2 Scope:: The scope operators @code{::} and @code{.} 17336* GDB/M2:: @value{GDBN} and Modula-2 17337@end menu 17338 17339@node M2 Operators 17340@subsubsection Operators 17341@cindex Modula-2 operators 17342 17343Operators must be defined on values of specific types. For instance, 17344@code{+} is defined on numbers, but not on structures. Operators are 17345often defined on groups of types. For the purposes of Modula-2, the 17346following definitions hold: 17347 17348@itemize @bullet 17349 17350@item 17351@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and 17352their subranges. 17353 17354@item 17355@emph{Character types} consist of @code{CHAR} and its subranges. 17356 17357@item 17358@emph{Floating-point types} consist of @code{REAL}. 17359 17360@item 17361@emph{Pointer types} consist of anything declared as @code{POINTER TO 17362@var{type}}. 17363 17364@item 17365@emph{Scalar types} consist of all of the above. 17366 17367@item 17368@emph{Set types} consist of @code{SET} and @code{BITSET} types. 17369 17370@item 17371@emph{Boolean types} consist of @code{BOOLEAN}. 17372@end itemize 17373 17374@noindent 17375The following operators are supported, and appear in order of 17376increasing precedence: 17377 17378@table @code 17379@item , 17380Function argument or array index separator. 17381 17382@item := 17383Assignment. The value of @var{var} @code{:=} @var{value} is 17384@var{value}. 17385 17386@item <@r{, }> 17387Less than, greater than on integral, floating-point, or enumerated 17388types. 17389 17390@item <=@r{, }>= 17391Less than or equal to, greater than or equal to 17392on integral, floating-point and enumerated types, or set inclusion on 17393set types. Same precedence as @code{<}. 17394 17395@item =@r{, }<>@r{, }# 17396Equality and two ways of expressing inequality, valid on scalar types. 17397Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is 17398available for inequality, since @code{#} conflicts with the script 17399comment character. 17400 17401@item IN 17402Set membership. Defined on set types and the types of their members. 17403Same precedence as @code{<}. 17404 17405@item OR 17406Boolean disjunction. Defined on boolean types. 17407 17408@item AND@r{, }& 17409Boolean conjunction. Defined on boolean types. 17410 17411@item @@ 17412The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}). 17413 17414@item +@r{, }- 17415Addition and subtraction on integral and floating-point types, or union 17416and difference on set types. 17417 17418@item * 17419Multiplication on integral and floating-point types, or set intersection 17420on set types. 17421 17422@item / 17423Division on floating-point types, or symmetric set difference on set 17424types. Same precedence as @code{*}. 17425 17426@item DIV@r{, }MOD 17427Integer division and remainder. Defined on integral types. Same 17428precedence as @code{*}. 17429 17430@item - 17431Negative. Defined on @code{INTEGER} and @code{REAL} data. 17432 17433@item ^ 17434Pointer dereferencing. Defined on pointer types. 17435 17436@item NOT 17437Boolean negation. Defined on boolean types. Same precedence as 17438@code{^}. 17439 17440@item . 17441@code{RECORD} field selector. Defined on @code{RECORD} data. Same 17442precedence as @code{^}. 17443 17444@item [] 17445Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}. 17446 17447@item () 17448Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence 17449as @code{^}. 17450 17451@item ::@r{, }. 17452@value{GDBN} and Modula-2 scope operators. 17453@end table 17454 17455@quotation 17456@emph{Warning:} Set expressions and their operations are not yet supported, so @value{GDBN} 17457treats the use of the operator @code{IN}, or the use of operators 17458@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#}, 17459@code{<=}, and @code{>=} on sets as an error. 17460@end quotation 17461 17462 17463@node Built-In Func/Proc 17464@subsubsection Built-in Functions and Procedures 17465@cindex Modula-2 built-ins 17466 17467Modula-2 also makes available several built-in procedures and functions. 17468In describing these, the following metavariables are used: 17469 17470@table @var 17471 17472@item a 17473represents an @code{ARRAY} variable. 17474 17475@item c 17476represents a @code{CHAR} constant or variable. 17477 17478@item i 17479represents a variable or constant of integral type. 17480 17481@item m 17482represents an identifier that belongs to a set. Generally used in the 17483same function with the metavariable @var{s}. The type of @var{s} should 17484be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}). 17485 17486@item n 17487represents a variable or constant of integral or floating-point type. 17488 17489@item r 17490represents a variable or constant of floating-point type. 17491 17492@item t 17493represents a type. 17494 17495@item v 17496represents a variable. 17497 17498@item x 17499represents a variable or constant of one of many types. See the 17500explanation of the function for details. 17501@end table 17502 17503All Modula-2 built-in procedures also return a result, described below. 17504 17505@table @code 17506@item ABS(@var{n}) 17507Returns the absolute value of @var{n}. 17508 17509@item CAP(@var{c}) 17510If @var{c} is a lower case letter, it returns its upper case 17511equivalent, otherwise it returns its argument. 17512 17513@item CHR(@var{i}) 17514Returns the character whose ordinal value is @var{i}. 17515 17516@item DEC(@var{v}) 17517Decrements the value in the variable @var{v} by one. Returns the new value. 17518 17519@item DEC(@var{v},@var{i}) 17520Decrements the value in the variable @var{v} by @var{i}. Returns the 17521new value. 17522 17523@item EXCL(@var{m},@var{s}) 17524Removes the element @var{m} from the set @var{s}. Returns the new 17525set. 17526 17527@item FLOAT(@var{i}) 17528Returns the floating point equivalent of the integer @var{i}. 17529 17530@item HIGH(@var{a}) 17531Returns the index of the last member of @var{a}. 17532 17533@item INC(@var{v}) 17534Increments the value in the variable @var{v} by one. Returns the new value. 17535 17536@item INC(@var{v},@var{i}) 17537Increments the value in the variable @var{v} by @var{i}. Returns the 17538new value. 17539 17540@item INCL(@var{m},@var{s}) 17541Adds the element @var{m} to the set @var{s} if it is not already 17542there. Returns the new set. 17543 17544@item MAX(@var{t}) 17545Returns the maximum value of the type @var{t}. 17546 17547@item MIN(@var{t}) 17548Returns the minimum value of the type @var{t}. 17549 17550@item ODD(@var{i}) 17551Returns boolean TRUE if @var{i} is an odd number. 17552 17553@item ORD(@var{x}) 17554Returns the ordinal value of its argument. For example, the ordinal 17555value of a character is its @sc{ascii} value (on machines supporting 17556the @sc{ascii} character set). The argument @var{x} must be of an 17557ordered type, which include integral, character and enumerated types. 17558 17559@item SIZE(@var{x}) 17560Returns the size of its argument. The argument @var{x} can be a 17561variable or a type. 17562 17563@item TRUNC(@var{r}) 17564Returns the integral part of @var{r}. 17565 17566@item TSIZE(@var{x}) 17567Returns the size of its argument. The argument @var{x} can be a 17568variable or a type. 17569 17570@item VAL(@var{t},@var{i}) 17571Returns the member of the type @var{t} whose ordinal value is @var{i}. 17572@end table 17573 17574@quotation 17575@emph{Warning:} Sets and their operations are not yet supported, so 17576@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as 17577an error. 17578@end quotation 17579 17580@cindex Modula-2 constants 17581@node M2 Constants 17582@subsubsection Constants 17583 17584@value{GDBN} allows you to express the constants of Modula-2 in the following 17585ways: 17586 17587@itemize @bullet 17588 17589@item 17590Integer constants are simply a sequence of digits. When used in an 17591expression, a constant is interpreted to be type-compatible with the 17592rest of the expression. Hexadecimal integers are specified by a 17593trailing @samp{H}, and octal integers by a trailing @samp{B}. 17594 17595@item 17596Floating point constants appear as a sequence of digits, followed by a 17597decimal point and another sequence of digits. An optional exponent can 17598then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where 17599@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the 17600digits of the floating point constant must be valid decimal (base 10) 17601digits. 17602 17603@item 17604Character constants consist of a single character enclosed by a pair of 17605like quotes, either single (@code{'}) or double (@code{"}). They may 17606also be expressed by their ordinal value (their @sc{ascii} value, usually) 17607followed by a @samp{C}. 17608 17609@item 17610String constants consist of a sequence of characters enclosed by a 17611pair of like quotes, either single (@code{'}) or double (@code{"}). 17612Escape sequences in the style of C are also allowed. @xref{C 17613Constants, ,C and C@t{++} Constants}, for a brief explanation of escape 17614sequences. 17615 17616@item 17617Enumerated constants consist of an enumerated identifier. 17618 17619@item 17620Boolean constants consist of the identifiers @code{TRUE} and 17621@code{FALSE}. 17622 17623@item 17624Pointer constants consist of integral values only. 17625 17626@item 17627Set constants are not yet supported. 17628@end itemize 17629 17630@node M2 Types 17631@subsubsection Modula-2 Types 17632@cindex Modula-2 types 17633 17634Currently @value{GDBN} can print the following data types in Modula-2 17635syntax: array types, record types, set types, pointer types, procedure 17636types, enumerated types, subrange types and base types. You can also 17637print the contents of variables declared using these type. 17638This section gives a number of simple source code examples together with 17639sample @value{GDBN} sessions. 17640 17641The first example contains the following section of code: 17642 17643@smallexample 17644VAR 17645 s: SET OF CHAR ; 17646 r: [20..40] ; 17647@end smallexample 17648 17649@noindent 17650and you can request @value{GDBN} to interrogate the type and value of 17651@code{r} and @code{s}. 17652 17653@smallexample 17654(@value{GDBP}) print s 17655@{'A'..'C', 'Z'@} 17656(@value{GDBP}) ptype s 17657SET OF CHAR 17658(@value{GDBP}) print r 1765921 17660(@value{GDBP}) ptype r 17661[20..40] 17662@end smallexample 17663 17664@noindent 17665Likewise if your source code declares @code{s} as: 17666 17667@smallexample 17668VAR 17669 s: SET ['A'..'Z'] ; 17670@end smallexample 17671 17672@noindent 17673then you may query the type of @code{s} by: 17674 17675@smallexample 17676(@value{GDBP}) ptype s 17677type = SET ['A'..'Z'] 17678@end smallexample 17679 17680@noindent 17681Note that at present you cannot interactively manipulate set 17682expressions using the debugger. 17683 17684The following example shows how you might declare an array in Modula-2 17685and how you can interact with @value{GDBN} to print its type and contents: 17686 17687@smallexample 17688VAR 17689 s: ARRAY [-10..10] OF CHAR ; 17690@end smallexample 17691 17692@smallexample 17693(@value{GDBP}) ptype s 17694ARRAY [-10..10] OF CHAR 17695@end smallexample 17696 17697Note that the array handling is not yet complete and although the type 17698is printed correctly, expression handling still assumes that all 17699arrays have a lower bound of zero and not @code{-10} as in the example 17700above. 17701 17702Here are some more type related Modula-2 examples: 17703 17704@smallexample 17705TYPE 17706 colour = (blue, red, yellow, green) ; 17707 t = [blue..yellow] ; 17708VAR 17709 s: t ; 17710BEGIN 17711 s := blue ; 17712@end smallexample 17713 17714@noindent 17715The @value{GDBN} interaction shows how you can query the data type 17716and value of a variable. 17717 17718@smallexample 17719(@value{GDBP}) print s 17720$1 = blue 17721(@value{GDBP}) ptype t 17722type = [blue..yellow] 17723@end smallexample 17724 17725@noindent 17726In this example a Modula-2 array is declared and its contents 17727displayed. Observe that the contents are written in the same way as 17728their @code{C} counterparts. 17729 17730@smallexample 17731VAR 17732 s: ARRAY [1..5] OF CARDINAL ; 17733BEGIN 17734 s[1] := 1 ; 17735@end smallexample 17736 17737@smallexample 17738(@value{GDBP}) print s 17739$1 = @{1, 0, 0, 0, 0@} 17740(@value{GDBP}) ptype s 17741type = ARRAY [1..5] OF CARDINAL 17742@end smallexample 17743 17744The Modula-2 language interface to @value{GDBN} also understands 17745pointer types as shown in this example: 17746 17747@smallexample 17748VAR 17749 s: POINTER TO ARRAY [1..5] OF CARDINAL ; 17750BEGIN 17751 NEW(s) ; 17752 s^[1] := 1 ; 17753@end smallexample 17754 17755@noindent 17756and you can request that @value{GDBN} describes the type of @code{s}. 17757 17758@smallexample 17759(@value{GDBP}) ptype s 17760type = POINTER TO ARRAY [1..5] OF CARDINAL 17761@end smallexample 17762 17763@value{GDBN} handles compound types as we can see in this example. 17764Here we combine array types, record types, pointer types and subrange 17765types: 17766 17767@smallexample 17768TYPE 17769 foo = RECORD 17770 f1: CARDINAL ; 17771 f2: CHAR ; 17772 f3: myarray ; 17773 END ; 17774 17775 myarray = ARRAY myrange OF CARDINAL ; 17776 myrange = [-2..2] ; 17777VAR 17778 s: POINTER TO ARRAY myrange OF foo ; 17779@end smallexample 17780 17781@noindent 17782and you can ask @value{GDBN} to describe the type of @code{s} as shown 17783below. 17784 17785@smallexample 17786(@value{GDBP}) ptype s 17787type = POINTER TO ARRAY [-2..2] OF foo = RECORD 17788 f1 : CARDINAL; 17789 f2 : CHAR; 17790 f3 : ARRAY [-2..2] OF CARDINAL; 17791END 17792@end smallexample 17793 17794@node M2 Defaults 17795@subsubsection Modula-2 Defaults 17796@cindex Modula-2 defaults 17797 17798If type and range checking are set automatically by @value{GDBN}, they 17799both default to @code{on} whenever the working language changes to 17800Modula-2. This happens regardless of whether you or @value{GDBN} 17801selected the working language. 17802 17803If you allow @value{GDBN} to set the language automatically, then entering 17804code compiled from a file whose name ends with @file{.mod} sets the 17805working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} 17806Infer the Source Language}, for further details. 17807 17808@node Deviations 17809@subsubsection Deviations from Standard Modula-2 17810@cindex Modula-2, deviations from 17811 17812A few changes have been made to make Modula-2 programs easier to debug. 17813This is done primarily via loosening its type strictness: 17814 17815@itemize @bullet 17816@item 17817Unlike in standard Modula-2, pointer constants can be formed by 17818integers. This allows you to modify pointer variables during 17819debugging. (In standard Modula-2, the actual address contained in a 17820pointer variable is hidden from you; it can only be modified 17821through direct assignment to another pointer variable or expression that 17822returned a pointer.) 17823 17824@item 17825C escape sequences can be used in strings and characters to represent 17826non-printable characters. @value{GDBN} prints out strings with these 17827escape sequences embedded. Single non-printable characters are 17828printed using the @samp{CHR(@var{nnn})} format. 17829 17830@item 17831The assignment operator (@code{:=}) returns the value of its right-hand 17832argument. 17833 17834@item 17835All built-in procedures both modify @emph{and} return their argument. 17836@end itemize 17837 17838@node M2 Checks 17839@subsubsection Modula-2 Type and Range Checks 17840@cindex Modula-2 checks 17841 17842@quotation 17843@emph{Warning:} in this release, @value{GDBN} does not yet perform type or 17844range checking. 17845@end quotation 17846@c FIXME remove warning when type/range checks added 17847 17848@value{GDBN} considers two Modula-2 variables type equivalent if: 17849 17850@itemize @bullet 17851@item 17852They are of types that have been declared equivalent via a @code{TYPE 17853@var{t1} = @var{t2}} statement 17854 17855@item 17856They have been declared on the same line. (Note: This is true of the 17857@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.) 17858@end itemize 17859 17860As long as type checking is enabled, any attempt to combine variables 17861whose types are not equivalent is an error. 17862 17863Range checking is done on all mathematical operations, assignment, array 17864index bounds, and all built-in functions and procedures. 17865 17866@node M2 Scope 17867@subsubsection The Scope Operators @code{::} and @code{.} 17868@cindex scope 17869@cindex @code{.}, Modula-2 scope operator 17870@cindex colon, doubled as scope operator 17871@ifinfo 17872@vindex colon-colon@r{, in Modula-2} 17873@c Info cannot handle :: but TeX can. 17874@end ifinfo 17875@ifnotinfo 17876@vindex ::@r{, in Modula-2} 17877@end ifnotinfo 17878 17879There are a few subtle differences between the Modula-2 scope operator 17880(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have 17881similar syntax: 17882 17883@smallexample 17884 17885@var{module} . @var{id} 17886@var{scope} :: @var{id} 17887@end smallexample 17888 17889@noindent 17890where @var{scope} is the name of a module or a procedure, 17891@var{module} the name of a module, and @var{id} is any declared 17892identifier within your program, except another module. 17893 17894Using the @code{::} operator makes @value{GDBN} search the scope 17895specified by @var{scope} for the identifier @var{id}. If it is not 17896found in the specified scope, then @value{GDBN} searches all scopes 17897enclosing the one specified by @var{scope}. 17898 17899Using the @code{.} operator makes @value{GDBN} search the current scope for 17900the identifier specified by @var{id} that was imported from the 17901definition module specified by @var{module}. With this operator, it is 17902an error if the identifier @var{id} was not imported from definition 17903module @var{module}, or if @var{id} is not an identifier in 17904@var{module}. 17905 17906@node GDB/M2 17907@subsubsection @value{GDBN} and Modula-2 17908 17909Some @value{GDBN} commands have little use when debugging Modula-2 programs. 17910Five subcommands of @code{set print} and @code{show print} apply 17911specifically to C and C@t{++}: @samp{vtbl}, @samp{demangle}, 17912@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four 17913apply to C@t{++}, and the last to the C @code{union} type, which has no direct 17914analogue in Modula-2. 17915 17916The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available 17917with any language, is not useful with Modula-2. Its 17918intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be 17919created in Modula-2 as they can in C or C@t{++}. However, because an 17920address can be specified by an integral constant, the construct 17921@samp{@{@var{type}@}@var{adrexp}} is still useful. 17922 17923@cindex @code{#} in Modula-2 17924In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is 17925interpreted as the beginning of a comment. Use @code{<>} instead. 17926 17927@node Ada 17928@subsection Ada 17929@cindex Ada 17930 17931The extensions made to @value{GDBN} for Ada only support 17932output from the @sc{gnu} Ada (GNAT) compiler. 17933Other Ada compilers are not currently supported, and 17934attempting to debug executables produced by them is most likely 17935to be difficult. 17936 17937 17938@cindex expressions in Ada 17939@menu 17940* Ada Mode Intro:: General remarks on the Ada syntax 17941 and semantics supported by Ada mode 17942 in @value{GDBN}. 17943* Omissions from Ada:: Restrictions on the Ada expression syntax. 17944* Additions to Ada:: Extensions of the Ada expression syntax. 17945* Overloading support for Ada:: Support for expressions involving overloaded 17946 subprograms. 17947* Stopping Before Main Program:: Debugging the program during elaboration. 17948* Ada Exceptions:: Ada Exceptions 17949* Ada Tasks:: Listing and setting breakpoints in tasks. 17950* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files 17951* Ravenscar Profile:: Tasking Support when using the Ravenscar 17952 Profile 17953* Ada Settings:: New settable GDB parameters for Ada. 17954* Ada Glitches:: Known peculiarities of Ada mode. 17955@end menu 17956 17957@node Ada Mode Intro 17958@subsubsection Introduction 17959@cindex Ada mode, general 17960 17961The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression 17962syntax, with some extensions. 17963The philosophy behind the design of this subset is 17964 17965@itemize @bullet 17966@item 17967That @value{GDBN} should provide basic literals and access to operations for 17968arithmetic, dereferencing, field selection, indexing, and subprogram calls, 17969leaving more sophisticated computations to subprograms written into the 17970program (which therefore may be called from @value{GDBN}). 17971 17972@item 17973That type safety and strict adherence to Ada language restrictions 17974are not particularly important to the @value{GDBN} user. 17975 17976@item 17977That brevity is important to the @value{GDBN} user. 17978@end itemize 17979 17980Thus, for brevity, the debugger acts as if all names declared in 17981user-written packages are directly visible, even if they are not visible 17982according to Ada rules, thus making it unnecessary to fully qualify most 17983names with their packages, regardless of context. Where this causes 17984ambiguity, @value{GDBN} asks the user's intent. 17985 17986The debugger will start in Ada mode if it detects an Ada main program. 17987As for other languages, it will enter Ada mode when stopped in a program that 17988was translated from an Ada source file. 17989 17990While in Ada mode, you may use `@t{--}' for comments. This is useful 17991mostly for documenting command files. The standard @value{GDBN} comment 17992(@samp{#}) still works at the beginning of a line in Ada mode, but not in the 17993middle (to allow based literals). 17994 17995@node Omissions from Ada 17996@subsubsection Omissions from Ada 17997@cindex Ada, omissions from 17998 17999Here are the notable omissions from the subset: 18000 18001@itemize @bullet 18002@item 18003Only a subset of the attributes are supported: 18004 18005@itemize @minus 18006@item 18007@t{'First}, @t{'Last}, and @t{'Length} 18008 on array objects (not on types and subtypes). 18009 18010@item 18011@t{'Min} and @t{'Max}. 18012 18013@item 18014@t{'Pos} and @t{'Val}. 18015 18016@item 18017@t{'Tag}. 18018 18019@item 18020@t{'Range} on array objects (not subtypes), but only as the right 18021operand of the membership (@code{in}) operator. 18022 18023@item 18024@t{'Access}, @t{'Unchecked_Access}, and 18025@t{'Unrestricted_Access} (a GNAT extension). 18026 18027@item 18028@t{'Address}. 18029@end itemize 18030 18031@item 18032The names in 18033@code{Characters.Latin_1} are not available and 18034concatenation is not implemented. Thus, escape characters in strings are 18035not currently available. 18036 18037@item 18038Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise 18039equality of representations. They will generally work correctly 18040for strings and arrays whose elements have integer or enumeration types. 18041They may not work correctly for arrays whose element 18042types have user-defined equality, for arrays of real values 18043(in particular, IEEE-conformant floating point, because of negative 18044zeroes and NaNs), and for arrays whose elements contain unused bits with 18045indeterminate values. 18046 18047@item 18048The other component-by-component array operations (@code{and}, @code{or}, 18049@code{xor}, @code{not}, and relational tests other than equality) 18050are not implemented. 18051 18052@item 18053@cindex array aggregates (Ada) 18054@cindex record aggregates (Ada) 18055@cindex aggregates (Ada) 18056There is limited support for array and record aggregates. They are 18057permitted only on the right sides of assignments, as in these examples: 18058 18059@smallexample 18060(@value{GDBP}) set An_Array := (1, 2, 3, 4, 5, 6) 18061(@value{GDBP}) set An_Array := (1, others => 0) 18062(@value{GDBP}) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) 18063(@value{GDBP}) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) 18064(@value{GDBP}) set A_Record := (1, "Peter", True); 18065(@value{GDBP}) set A_Record := (Name => "Peter", Id => 1, Alive => True) 18066@end smallexample 18067 18068Changing a 18069discriminant's value by assigning an aggregate has an 18070undefined effect if that discriminant is used within the record. 18071However, you can first modify discriminants by directly assigning to 18072them (which normally would not be allowed in Ada), and then performing an 18073aggregate assignment. For example, given a variable @code{A_Rec} 18074declared to have a type such as: 18075 18076@smallexample 18077type Rec (Len : Small_Integer := 0) is record 18078 Id : Integer; 18079 Vals : IntArray (1 .. Len); 18080end record; 18081@end smallexample 18082 18083you can assign a value with a different size of @code{Vals} with two 18084assignments: 18085 18086@smallexample 18087(@value{GDBP}) set A_Rec.Len := 4 18088(@value{GDBP}) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) 18089@end smallexample 18090 18091As this example also illustrates, @value{GDBN} is very loose about the usual 18092rules concerning aggregates. You may leave out some of the 18093components of an array or record aggregate (such as the @code{Len} 18094component in the assignment to @code{A_Rec} above); they will retain their 18095original values upon assignment. You may freely use dynamic values as 18096indices in component associations. You may even use overlapping or 18097redundant component associations, although which component values are 18098assigned in such cases is not defined. 18099 18100@item 18101Calls to dispatching subprograms are not implemented. 18102 18103@item 18104The overloading algorithm is much more limited (i.e., less selective) 18105than that of real Ada. It makes only limited use of the context in 18106which a subexpression appears to resolve its meaning, and it is much 18107looser in its rules for allowing type matches. As a result, some 18108function calls will be ambiguous, and the user will be asked to choose 18109the proper resolution. 18110 18111@item 18112The @code{new} operator is not implemented. 18113 18114@item 18115Entry calls are not implemented. 18116 18117@item 18118Aside from printing, arithmetic operations on the native VAX floating-point 18119formats are not supported. 18120 18121@item 18122It is not possible to slice a packed array. 18123 18124@item 18125The names @code{True} and @code{False}, when not part of a qualified name, 18126are interpreted as if implicitly prefixed by @code{Standard}, regardless of 18127context. 18128Should your program 18129redefine these names in a package or procedure (at best a dubious practice), 18130you will have to use fully qualified names to access their new definitions. 18131@end itemize 18132 18133@node Additions to Ada 18134@subsubsection Additions to Ada 18135@cindex Ada, deviations from 18136 18137As it does for other languages, @value{GDBN} makes certain generic 18138extensions to Ada (@pxref{Expressions}): 18139 18140@itemize @bullet 18141@item 18142If the expression @var{E} is a variable residing in memory (typically 18143a local variable or array element) and @var{N} is a positive integer, 18144then @code{@var{E}@@@var{N}} displays the values of @var{E} and the 18145@var{N}-1 adjacent variables following it in memory as an array. In 18146Ada, this operator is generally not necessary, since its prime use is 18147in displaying parts of an array, and slicing will usually do this in 18148Ada. However, there are occasional uses when debugging programs in 18149which certain debugging information has been optimized away. 18150 18151@item 18152@code{@var{B}::@var{var}} means ``the variable named @var{var} that 18153appears in function or file @var{B}.'' When @var{B} is a file name, 18154you must typically surround it in single quotes. 18155 18156@item 18157The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type 18158@var{type} that appears at address @var{addr}.'' 18159 18160@item 18161A name starting with @samp{$} is a convenience variable 18162(@pxref{Convenience Vars}) or a machine register (@pxref{Registers}). 18163@end itemize 18164 18165In addition, @value{GDBN} provides a few other shortcuts and outright 18166additions specific to Ada: 18167 18168@itemize @bullet 18169@item 18170The assignment statement is allowed as an expression, returning 18171its right-hand operand as its value. Thus, you may enter 18172 18173@smallexample 18174(@value{GDBP}) set x := y + 3 18175(@value{GDBP}) print A(tmp := y + 1) 18176@end smallexample 18177 18178@item 18179The semicolon is allowed as an ``operator,'' returning as its value 18180the value of its right-hand operand. 18181This allows, for example, 18182complex conditional breaks: 18183 18184@smallexample 18185(@value{GDBP}) break f 18186(@value{GDBP}) condition 1 (report(i); k += 1; A(k) > 100) 18187@end smallexample 18188 18189@item 18190Rather than use catenation and symbolic character names to introduce special 18191characters into strings, one may instead use a special bracket notation, 18192which is also used to print strings. A sequence of characters of the form 18193@samp{["@var{XX}"]} within a string or character literal denotes the 18194(single) character whose numeric encoding is @var{XX} in hexadecimal. The 18195sequence of characters @samp{["""]} also denotes a single quotation mark 18196in strings. For example, 18197@smallexample 18198 "One line.["0a"]Next line.["0a"]" 18199@end smallexample 18200@noindent 18201contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF}) 18202after each period. 18203 18204@item 18205The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and 18206@t{'Max} is optional (and is ignored in any case). For example, it is valid 18207to write 18208 18209@smallexample 18210(@value{GDBP}) print 'max(x, y) 18211@end smallexample 18212 18213@item 18214When printing arrays, @value{GDBN} uses positional notation when the 18215array has a lower bound of 1, and uses a modified named notation otherwise. 18216For example, a one-dimensional array of three integers with a lower bound 18217of 3 might print as 18218 18219@smallexample 18220(3 => 10, 17, 1) 18221@end smallexample 18222 18223@noindent 18224That is, in contrast to valid Ada, only the first component has a @code{=>} 18225clause. 18226 18227@item 18228You may abbreviate attributes in expressions with any unique, 18229multi-character subsequence of 18230their names (an exact match gets preference). 18231For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh} 18232in place of @t{a'length}. 18233 18234@item 18235@cindex quoting Ada internal identifiers 18236Since Ada is case-insensitive, the debugger normally maps identifiers you type 18237to lower case. The GNAT compiler uses upper-case characters for 18238some of its internal identifiers, which are normally of no interest to users. 18239For the rare occasions when you actually have to look at them, 18240enclose them in angle brackets to avoid the lower-case mapping. 18241For example, 18242@smallexample 18243(@value{GDBP}) print <JMPBUF_SAVE>[0] 18244@end smallexample 18245 18246@item 18247Printing an object of class-wide type or dereferencing an 18248access-to-class-wide value will display all the components of the object's 18249specific type (as indicated by its run-time tag). Likewise, component 18250selection on such a value will operate on the specific type of the 18251object. 18252 18253@end itemize 18254 18255@node Overloading support for Ada 18256@subsubsection Overloading support for Ada 18257@cindex overloading, Ada 18258 18259The debugger supports limited overloading. Given a subprogram call in which 18260the function symbol has multiple definitions, it will use the number of 18261actual parameters and some information about their types to attempt to narrow 18262the set of definitions. It also makes very limited use of context, preferring 18263procedures to functions in the context of the @code{call} command, and 18264functions to procedures elsewhere. 18265 18266If, after narrowing, the set of matching definitions still contains more than 18267one definition, @value{GDBN} will display a menu to query which one it should 18268use, for instance: 18269 18270@smallexample 18271(@value{GDBP}) print f(1) 18272Multiple matches for f 18273[0] cancel 18274[1] foo.f (integer) return boolean at foo.adb:23 18275[2] foo.f (foo.new_integer) return boolean at foo.adb:28 18276> 18277@end smallexample 18278 18279In this case, just select one menu entry either to cancel expression evaluation 18280(type @kbd{0} and press @key{RET}) or to continue evaluation with a specific 18281instance (type the corresponding number and press @key{RET}). 18282 18283Here are a couple of commands to customize @value{GDBN}'s behavior in this 18284case: 18285 18286@table @code 18287 18288@kindex set ada print-signatures 18289@item set ada print-signatures 18290Control whether parameter types and return types are displayed in overloads 18291selection menus. It is @code{on} by default. 18292@xref{Overloading support for Ada}. 18293 18294@kindex show ada print-signatures 18295@item show ada print-signatures 18296Show the current setting for displaying parameter types and return types in 18297overloads selection menu. 18298@xref{Overloading support for Ada}. 18299 18300@end table 18301 18302@node Stopping Before Main Program 18303@subsubsection Stopping at the Very Beginning 18304 18305@cindex breakpointing Ada elaboration code 18306It is sometimes necessary to debug the program during elaboration, and 18307before reaching the main procedure. 18308As defined in the Ada Reference 18309Manual, the elaboration code is invoked from a procedure called 18310@code{adainit}. To run your program up to the beginning of 18311elaboration, simply use the following two commands: 18312@code{tbreak adainit} and @code{run}. 18313 18314@node Ada Exceptions 18315@subsubsection Ada Exceptions 18316 18317A command is provided to list all Ada exceptions: 18318 18319@table @code 18320@kindex info exceptions 18321@item info exceptions 18322@itemx info exceptions @var{regexp} 18323The @code{info exceptions} command allows you to list all Ada exceptions 18324defined within the program being debugged, as well as their addresses. 18325With a regular expression, @var{regexp}, as argument, only those exceptions 18326whose names match @var{regexp} are listed. 18327@end table 18328 18329Below is a small example, showing how the command can be used, first 18330without argument, and next with a regular expression passed as an 18331argument. 18332 18333@smallexample 18334(@value{GDBP}) info exceptions 18335All defined Ada exceptions: 18336constraint_error: 0x613da0 18337program_error: 0x613d20 18338storage_error: 0x613ce0 18339tasking_error: 0x613ca0 18340const.aint_global_e: 0x613b00 18341(@value{GDBP}) info exceptions const.aint 18342All Ada exceptions matching regular expression "const.aint": 18343constraint_error: 0x613da0 18344const.aint_global_e: 0x613b00 18345@end smallexample 18346 18347It is also possible to ask @value{GDBN} to stop your program's execution 18348when an exception is raised. For more details, see @ref{Set Catchpoints}. 18349 18350@node Ada Tasks 18351@subsubsection Extensions for Ada Tasks 18352@cindex Ada, tasking 18353 18354Support for Ada tasks is analogous to that for threads (@pxref{Threads}). 18355@value{GDBN} provides the following task-related commands: 18356 18357@table @code 18358@kindex info tasks 18359@item info tasks 18360This command shows a list of current Ada tasks, as in the following example: 18361 18362 18363@smallexample 18364@iftex 18365@leftskip=0.5cm 18366@end iftex 18367(@value{GDBP}) info tasks 18368 ID TID P-ID Pri State Name 18369 1 8088000 0 15 Child Activation Wait main_task 18370 2 80a4000 1 15 Accept Statement b 18371 3 809a800 1 15 Child Activation Wait a 18372* 4 80ae800 3 15 Runnable c 18373 18374@end smallexample 18375 18376@noindent 18377In this listing, the asterisk before the last task indicates it to be the 18378task currently being inspected. 18379 18380@table @asis 18381@item ID 18382Represents @value{GDBN}'s internal task number. 18383 18384@item TID 18385The Ada task ID. 18386 18387@item P-ID 18388The parent's task ID (@value{GDBN}'s internal task number). 18389 18390@item Pri 18391The base priority of the task. 18392 18393@item State 18394Current state of the task. 18395 18396@table @code 18397@item Unactivated 18398The task has been created but has not been activated. It cannot be 18399executing. 18400 18401@item Runnable 18402The task is not blocked for any reason known to Ada. (It may be waiting 18403for a mutex, though.) It is conceptually "executing" in normal mode. 18404 18405@item Terminated 18406The task is terminated, in the sense of ARM 9.3 (5). Any dependents 18407that were waiting on terminate alternatives have been awakened and have 18408terminated themselves. 18409 18410@item Child Activation Wait 18411The task is waiting for created tasks to complete activation. 18412 18413@item Accept Statement 18414The task is waiting on an accept or selective wait statement. 18415 18416@item Waiting on entry call 18417The task is waiting on an entry call. 18418 18419@item Async Select Wait 18420The task is waiting to start the abortable part of an asynchronous 18421select statement. 18422 18423@item Delay Sleep 18424The task is waiting on a select statement with only a delay 18425alternative open. 18426 18427@item Child Termination Wait 18428The task is sleeping having completed a master within itself, and is 18429waiting for the tasks dependent on that master to become terminated or 18430waiting on a terminate Phase. 18431 18432@item Wait Child in Term Alt 18433The task is sleeping waiting for tasks on terminate alternatives to 18434finish terminating. 18435 18436@item Accepting RV with @var{taskno} 18437The task is accepting a rendez-vous with the task @var{taskno}. 18438@end table 18439 18440@item Name 18441Name of the task in the program. 18442 18443@end table 18444 18445@kindex info task @var{taskno} 18446@item info task @var{taskno} 18447This command shows detailed informations on the specified task, as in 18448the following example: 18449@smallexample 18450@iftex 18451@leftskip=0.5cm 18452@end iftex 18453(@value{GDBP}) info tasks 18454 ID TID P-ID Pri State Name 18455 1 8077880 0 15 Child Activation Wait main_task 18456* 2 807c468 1 15 Runnable task_1 18457(@value{GDBP}) info task 2 18458Ada Task: 0x807c468 18459Name: "task_1" 18460Thread: 0 18461LWP: 0x1fac 18462Parent: 1 ("main_task") 18463Base Priority: 15 18464State: Runnable 18465@end smallexample 18466 18467@item task 18468@kindex task@r{ (Ada)} 18469@cindex current Ada task ID 18470This command prints the ID and name of the current task. 18471 18472@smallexample 18473@iftex 18474@leftskip=0.5cm 18475@end iftex 18476(@value{GDBP}) info tasks 18477 ID TID P-ID Pri State Name 18478 1 8077870 0 15 Child Activation Wait main_task 18479* 2 807c458 1 15 Runnable some_task 18480(@value{GDBP}) task 18481[Current task is 2 "some_task"] 18482@end smallexample 18483 18484@item task @var{taskno} 18485@cindex Ada task switching 18486This command is like the @code{thread @var{thread-id}} 18487command (@pxref{Threads}). It switches the context of debugging 18488from the current task to the given task. 18489 18490@smallexample 18491@iftex 18492@leftskip=0.5cm 18493@end iftex 18494(@value{GDBP}) info tasks 18495 ID TID P-ID Pri State Name 18496 1 8077870 0 15 Child Activation Wait main_task 18497* 2 807c458 1 15 Runnable some_task 18498(@value{GDBP}) task 1 18499[Switching to task 1 "main_task"] 18500#0 0x8067726 in pthread_cond_wait () 18501(@value{GDBP}) bt 18502#0 0x8067726 in pthread_cond_wait () 18503#1 0x8056714 in system.os_interface.pthread_cond_wait () 18504#2 0x805cb63 in system.task_primitives.operations.sleep () 18505#3 0x806153e in system.tasking.stages.activate_tasks () 18506#4 0x804aacc in un () at un.adb:5 18507@end smallexample 18508 18509@item break @var{location} task @var{taskno} 18510@itemx break @var{location} task @var{taskno} if @dots{} 18511@cindex breakpoints and tasks, in Ada 18512@cindex task breakpoints, in Ada 18513@kindex break @dots{} task @var{taskno}@r{ (Ada)} 18514These commands are like the @code{break @dots{} thread @dots{}} 18515command (@pxref{Thread Stops}). The 18516@var{location} argument specifies source lines, as described 18517in @ref{Specify Location}. 18518 18519Use the qualifier @samp{task @var{taskno}} with a breakpoint command 18520to specify that you only want @value{GDBN} to stop the program when a 18521particular Ada task reaches this breakpoint. The @var{taskno} is one of the 18522numeric task identifiers assigned by @value{GDBN}, shown in the first 18523column of the @samp{info tasks} display. 18524 18525If you do not specify @samp{task @var{taskno}} when you set a 18526breakpoint, the breakpoint applies to @emph{all} tasks of your 18527program. 18528 18529You can use the @code{task} qualifier on conditional breakpoints as 18530well; in this case, place @samp{task @var{taskno}} before the 18531breakpoint condition (before the @code{if}). 18532 18533For example, 18534 18535@smallexample 18536@iftex 18537@leftskip=0.5cm 18538@end iftex 18539(@value{GDBP}) info tasks 18540 ID TID P-ID Pri State Name 18541 1 140022020 0 15 Child Activation Wait main_task 18542 2 140045060 1 15 Accept/Select Wait t2 18543 3 140044840 1 15 Runnable t1 18544* 4 140056040 1 15 Runnable t3 18545(@value{GDBP}) b 15 task 2 18546Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15. 18547(@value{GDBP}) cont 18548Continuing. 18549task # 1 running 18550task # 2 running 18551 18552Breakpoint 5, test_task_debug () at test_task_debug.adb:15 1855315 flush; 18554(@value{GDBP}) info tasks 18555 ID TID P-ID Pri State Name 18556 1 140022020 0 15 Child Activation Wait main_task 18557* 2 140045060 1 15 Runnable t2 18558 3 140044840 1 15 Runnable t1 18559 4 140056040 1 15 Delay Sleep t3 18560@end smallexample 18561@end table 18562 18563@node Ada Tasks and Core Files 18564@subsubsection Tasking Support when Debugging Core Files 18565@cindex Ada tasking and core file debugging 18566 18567When inspecting a core file, as opposed to debugging a live program, 18568tasking support may be limited or even unavailable, depending on 18569the platform being used. 18570For instance, on x86-linux, the list of tasks is available, but task 18571switching is not supported. 18572 18573On certain platforms, the debugger needs to perform some 18574memory writes in order to provide Ada tasking support. When inspecting 18575a core file, this means that the core file must be opened with read-write 18576privileges, using the command @samp{"set write on"} (@pxref{Patching}). 18577Under these circumstances, you should make a backup copy of the core 18578file before inspecting it with @value{GDBN}. 18579 18580@node Ravenscar Profile 18581@subsubsection Tasking Support when using the Ravenscar Profile 18582@cindex Ravenscar Profile 18583 18584The @dfn{Ravenscar Profile} is a subset of the Ada tasking features, 18585specifically designed for systems with safety-critical real-time 18586requirements. 18587 18588@table @code 18589@kindex set ravenscar task-switching on 18590@cindex task switching with program using Ravenscar Profile 18591@item set ravenscar task-switching on 18592Allows task switching when debugging a program that uses the Ravenscar 18593Profile. This is the default. 18594 18595@kindex set ravenscar task-switching off 18596@item set ravenscar task-switching off 18597Turn off task switching when debugging a program that uses the Ravenscar 18598Profile. This is mostly intended to disable the code that adds support 18599for the Ravenscar Profile, in case a bug in either @value{GDBN} or in 18600the Ravenscar runtime is preventing @value{GDBN} from working properly. 18601To be effective, this command should be run before the program is started. 18602 18603@kindex show ravenscar task-switching 18604@item show ravenscar task-switching 18605Show whether it is possible to switch from task to task in a program 18606using the Ravenscar Profile. 18607 18608@end table 18609 18610@cindex Ravenscar thread 18611When Ravenscar task-switching is enabled, Ravenscar tasks are 18612announced by @value{GDBN} as if they were threads: 18613 18614@smallexample 18615(gdb) continue 18616[New Ravenscar Thread 0x2b8f0] 18617@end smallexample 18618 18619Both Ravenscar tasks and the underlying CPU threads will show up in 18620the output of @code{info threads}: 18621 18622@smallexample 18623(gdb) info threads 18624 Id Target Id Frame 18625 1 Thread 1 (CPU#0 [running]) simple () at simple.adb:10 18626 2 Thread 2 (CPU#1 [running]) 0x0000000000003d34 in __gnat_initialize_cpu_devices () 18627 3 Thread 3 (CPU#2 [running]) 0x0000000000003d28 in __gnat_initialize_cpu_devices () 18628 4 Thread 4 (CPU#3 [halted ]) 0x000000000000c6ec in system.task_primitives.operations.idle () 18629* 5 Ravenscar Thread 0x2b8f0 simple () at simple.adb:10 18630 6 Ravenscar Thread 0x2f150 0x000000000000c6ec in system.task_primitives.operations.idle () 18631@end smallexample 18632 18633One known limitation of the Ravenscar support in @value{GDBN} is that 18634it isn't currently possible to single-step through the runtime 18635initialization sequence. If you need to debug this code, you should 18636use @code{set ravenscar task-switching off}. 18637 18638@node Ada Settings 18639@subsubsection Ada Settings 18640@cindex Ada settings 18641 18642@table @code 18643@kindex set varsize-limit 18644@item set varsize-limit @var{size} 18645Prevent @value{GDBN} from attempting to evaluate objects whose size 18646is above the given limit (@var{size}) when those sizes are computed 18647from run-time quantities. This is typically the case when the object 18648has a variable size, such as an array whose bounds are not known at 18649compile time for example. Setting @var{size} to @code{unlimited} 18650removes the size limitation. By default, the limit is about 65KB. 18651 18652The purpose of having such a limit is to prevent @value{GDBN} from 18653trying to grab enormous chunks of virtual memory when asked to evaluate 18654a quantity whose bounds have been corrupted or have not yet been fully 18655initialized. The limit applies to the results of some subexpressions 18656as well as to complete expressions. For example, an expression denoting 18657a simple integer component, such as @code{x.y.z}, may fail if the size of 18658@code{x.y} is variable and exceeds @code{size}. On the other hand, 18659@value{GDBN} is sometimes clever; the expression @code{A(i)}, where 18660@code{A} is an array variable with non-constant size, will generally 18661succeed regardless of the bounds on @code{A}, as long as the component 18662size is less than @var{size}. 18663 18664@kindex show varsize-limit 18665@item show varsize-limit 18666Show the limit on types whose size is determined by run-time quantities. 18667@end table 18668 18669@node Ada Glitches 18670@subsubsection Known Peculiarities of Ada Mode 18671@cindex Ada, problems 18672 18673Besides the omissions listed previously (@pxref{Omissions from Ada}), 18674we know of several problems with and limitations of Ada mode in 18675@value{GDBN}, 18676some of which will be fixed with planned future releases of the debugger 18677and the GNU Ada compiler. 18678 18679@itemize @bullet 18680@item 18681Static constants that the compiler chooses not to materialize as objects in 18682storage are invisible to the debugger. 18683 18684@item 18685Named parameter associations in function argument lists are ignored (the 18686argument lists are treated as positional). 18687 18688@item 18689Many useful library packages are currently invisible to the debugger. 18690 18691@item 18692Fixed-point arithmetic, conversions, input, and output is carried out using 18693floating-point arithmetic, and may give results that only approximate those on 18694the host machine. 18695 18696@item 18697The GNAT compiler never generates the prefix @code{Standard} for any of 18698the standard symbols defined by the Ada language. @value{GDBN} knows about 18699this: it will strip the prefix from names when you use it, and will never 18700look for a name you have so qualified among local symbols, nor match against 18701symbols in other packages or subprograms. If you have 18702defined entities anywhere in your program other than parameters and 18703local variables whose simple names match names in @code{Standard}, 18704GNAT's lack of qualification here can cause confusion. When this happens, 18705you can usually resolve the confusion 18706by qualifying the problematic names with package 18707@code{Standard} explicitly. 18708@end itemize 18709 18710Older versions of the compiler sometimes generate erroneous debugging 18711information, resulting in the debugger incorrectly printing the value 18712of affected entities. In some cases, the debugger is able to work 18713around an issue automatically. In other cases, the debugger is able 18714to work around the issue, but the work-around has to be specifically 18715enabled. 18716 18717@kindex set ada trust-PAD-over-XVS 18718@kindex show ada trust-PAD-over-XVS 18719@table @code 18720 18721@item set ada trust-PAD-over-XVS on 18722Configure GDB to strictly follow the GNAT encoding when computing the 18723value of Ada entities, particularly when @code{PAD} and @code{PAD___XVS} 18724types are involved (see @code{ada/exp_dbug.ads} in the GCC sources for 18725a complete description of the encoding used by the GNAT compiler). 18726This is the default. 18727 18728@item set ada trust-PAD-over-XVS off 18729This is related to the encoding using by the GNAT compiler. If @value{GDBN} 18730sometimes prints the wrong value for certain entities, changing @code{ada 18731trust-PAD-over-XVS} to @code{off} activates a work-around which may fix 18732the issue. It is always safe to set @code{ada trust-PAD-over-XVS} to 18733@code{off}, but this incurs a slight performance penalty, so it is 18734recommended to leave this setting to @code{on} unless necessary. 18735 18736@end table 18737 18738@cindex GNAT descriptive types 18739@cindex GNAT encoding 18740Internally, the debugger also relies on the compiler following a number 18741of conventions known as the @samp{GNAT Encoding}, all documented in 18742@file{gcc/ada/exp_dbug.ads} in the GCC sources. This encoding describes 18743how the debugging information should be generated for certain types. 18744In particular, this convention makes use of @dfn{descriptive types}, 18745which are artificial types generated purely to help the debugger. 18746 18747These encodings were defined at a time when the debugging information 18748format used was not powerful enough to describe some of the more complex 18749types available in Ada. Since DWARF allows us to express nearly all 18750Ada features, the long-term goal is to slowly replace these descriptive 18751types by their pure DWARF equivalent. To facilitate that transition, 18752a new maintenance option is available to force the debugger to ignore 18753those descriptive types. It allows the user to quickly evaluate how 18754well @value{GDBN} works without them. 18755 18756@table @code 18757 18758@kindex maint ada set ignore-descriptive-types 18759@item maintenance ada set ignore-descriptive-types [on|off] 18760Control whether the debugger should ignore descriptive types. 18761The default is not to ignore descriptives types (@code{off}). 18762 18763@kindex maint ada show ignore-descriptive-types 18764@item maintenance ada show ignore-descriptive-types 18765Show if descriptive types are ignored by @value{GDBN}. 18766 18767@end table 18768 18769@node Unsupported Languages 18770@section Unsupported Languages 18771 18772@cindex unsupported languages 18773@cindex minimal language 18774In addition to the other fully-supported programming languages, 18775@value{GDBN} also provides a pseudo-language, called @code{minimal}. 18776It does not represent a real programming language, but provides a set 18777of capabilities close to what the C or assembly languages provide. 18778This should allow most simple operations to be performed while debugging 18779an application that uses a language currently not supported by @value{GDBN}. 18780 18781If the language is set to @code{auto}, @value{GDBN} will automatically 18782select this language if the current frame corresponds to an unsupported 18783language. 18784 18785@node Symbols 18786@chapter Examining the Symbol Table 18787 18788The commands described in this chapter allow you to inquire about the 18789symbols (names of variables, functions and types) defined in your 18790program. This information is inherent in the text of your program and 18791does not change as your program executes. @value{GDBN} finds it in your 18792program's symbol table, in the file indicated when you started @value{GDBN} 18793(@pxref{File Options, ,Choosing Files}), or by one of the 18794file-management commands (@pxref{Files, ,Commands to Specify Files}). 18795 18796@cindex symbol names 18797@cindex names of symbols 18798@cindex quoting names 18799@anchor{quoting names} 18800Occasionally, you may need to refer to symbols that contain unusual 18801characters, which @value{GDBN} ordinarily treats as word delimiters. The 18802most frequent case is in referring to static variables in other 18803source files (@pxref{Variables,,Program Variables}). File names 18804are recorded in object files as debugging symbols, but @value{GDBN} would 18805ordinarily parse a typical file name, like @file{foo.c}, as the three words 18806@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize 18807@samp{foo.c} as a single symbol, enclose it in single quotes; for example, 18808 18809@smallexample 18810p 'foo.c'::x 18811@end smallexample 18812 18813@noindent 18814looks up the value of @code{x} in the scope of the file @file{foo.c}. 18815 18816@table @code 18817@cindex case-insensitive symbol names 18818@cindex case sensitivity in symbol names 18819@kindex set case-sensitive 18820@item set case-sensitive on 18821@itemx set case-sensitive off 18822@itemx set case-sensitive auto 18823Normally, when @value{GDBN} looks up symbols, it matches their names 18824with case sensitivity determined by the current source language. 18825Occasionally, you may wish to control that. The command @code{set 18826case-sensitive} lets you do that by specifying @code{on} for 18827case-sensitive matches or @code{off} for case-insensitive ones. If 18828you specify @code{auto}, case sensitivity is reset to the default 18829suitable for the source language. The default is case-sensitive 18830matches for all languages except for Fortran, for which the default is 18831case-insensitive matches. 18832 18833@kindex show case-sensitive 18834@item show case-sensitive 18835This command shows the current setting of case sensitivity for symbols 18836lookups. 18837 18838@kindex set print type methods 18839@item set print type methods 18840@itemx set print type methods on 18841@itemx set print type methods off 18842Normally, when @value{GDBN} prints a class, it displays any methods 18843declared in that class. You can control this behavior either by 18844passing the appropriate flag to @code{ptype}, or using @command{set 18845print type methods}. Specifying @code{on} will cause @value{GDBN} to 18846display the methods; this is the default. Specifying @code{off} will 18847cause @value{GDBN} to omit the methods. 18848 18849@kindex show print type methods 18850@item show print type methods 18851This command shows the current setting of method display when printing 18852classes. 18853 18854@kindex set print type nested-type-limit 18855@item set print type nested-type-limit @var{limit} 18856@itemx set print type nested-type-limit unlimited 18857Set the limit of displayed nested types that the type printer will 18858show. A @var{limit} of @code{unlimited} or @code{-1} will show all 18859nested definitions. By default, the type printer will not show any nested 18860types defined in classes. 18861 18862@kindex show print type nested-type-limit 18863@item show print type nested-type-limit 18864This command shows the current display limit of nested types when 18865printing classes. 18866 18867@kindex set print type typedefs 18868@item set print type typedefs 18869@itemx set print type typedefs on 18870@itemx set print type typedefs off 18871 18872Normally, when @value{GDBN} prints a class, it displays any typedefs 18873defined in that class. You can control this behavior either by 18874passing the appropriate flag to @code{ptype}, or using @command{set 18875print type typedefs}. Specifying @code{on} will cause @value{GDBN} to 18876display the typedef definitions; this is the default. Specifying 18877@code{off} will cause @value{GDBN} to omit the typedef definitions. 18878Note that this controls whether the typedef definition itself is 18879printed, not whether typedef names are substituted when printing other 18880types. 18881 18882@kindex show print type typedefs 18883@item show print type typedefs 18884This command shows the current setting of typedef display when 18885printing classes. 18886 18887@kindex set print type hex 18888@item set print type hex 18889@itemx set print type hex on 18890@itemx set print type hex off 18891 18892When @value{GDBN} prints sizes and offsets of struct members, it can use 18893either the decimal or hexadecimal notation. You can select one or the 18894other either by passing the appropriate flag to @code{ptype}, or by using 18895the @command{set print type hex} command. 18896 18897@kindex show print type hex 18898@item show print type hex 18899This command shows whether the sizes and offsets of struct members are 18900printed in decimal or hexadecimal notation. 18901 18902@kindex info address 18903@cindex address of a symbol 18904@item info address @var{symbol} 18905Describe where the data for @var{symbol} is stored. For a register 18906variable, this says which register it is kept in. For a non-register 18907local variable, this prints the stack-frame offset at which the variable 18908is always stored. 18909 18910Note the contrast with @samp{print &@var{symbol}}, which does not work 18911at all for a register variable, and for a stack local variable prints 18912the exact address of the current instantiation of the variable. 18913 18914@kindex info symbol 18915@cindex symbol from address 18916@cindex closest symbol and offset for an address 18917@item info symbol @var{addr} 18918Print the name of a symbol which is stored at the address @var{addr}. 18919If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the 18920nearest symbol and an offset from it: 18921 18922@smallexample 18923(@value{GDBP}) info symbol 0x54320 18924_initialize_vx + 396 in section .text 18925@end smallexample 18926 18927@noindent 18928This is the opposite of the @code{info address} command. You can use 18929it to find out the name of a variable or a function given its address. 18930 18931For dynamically linked executables, the name of executable or shared 18932library containing the symbol is also printed: 18933 18934@smallexample 18935(@value{GDBP}) info symbol 0x400225 18936_start + 5 in section .text of /tmp/a.out 18937(@value{GDBP}) info symbol 0x2aaaac2811cf 18938__read_nocancel + 6 in section .text of /usr/lib64/libc.so.6 18939@end smallexample 18940 18941@kindex demangle 18942@cindex demangle 18943@item demangle @r{[}-l @var{language}@r{]} @r{[}@var{--}@r{]} @var{name} 18944Demangle @var{name}. 18945If @var{language} is provided it is the name of the language to demangle 18946@var{name} in. Otherwise @var{name} is demangled in the current language. 18947 18948The @samp{--} option specifies the end of options, 18949and is useful when @var{name} begins with a dash. 18950 18951The parameter @code{demangle-style} specifies how to interpret the kind 18952of mangling used. @xref{Print Settings}. 18953 18954@kindex whatis 18955@item whatis[/@var{flags}] [@var{arg}] 18956Print the data type of @var{arg}, which can be either an expression 18957or a name of a data type. With no argument, print the data type of 18958@code{$}, the last value in the value history. 18959 18960If @var{arg} is an expression (@pxref{Expressions, ,Expressions}), it 18961is not actually evaluated, and any side-effecting operations (such as 18962assignments or function calls) inside it do not take place. 18963 18964If @var{arg} is a variable or an expression, @code{whatis} prints its 18965literal type as it is used in the source code. If the type was 18966defined using a @code{typedef}, @code{whatis} will @emph{not} print 18967the data type underlying the @code{typedef}. If the type of the 18968variable or the expression is a compound data type, such as 18969@code{struct} or @code{class}, @code{whatis} never prints their 18970fields or methods. It just prints the @code{struct}/@code{class} 18971name (a.k.a.@: its @dfn{tag}). If you want to see the members of 18972such a compound data type, use @code{ptype}. 18973 18974If @var{arg} is a type name that was defined using @code{typedef}, 18975@code{whatis} @dfn{unrolls} only one level of that @code{typedef}. 18976Unrolling means that @code{whatis} will show the underlying type used 18977in the @code{typedef} declaration of @var{arg}. However, if that 18978underlying type is also a @code{typedef}, @code{whatis} will not 18979unroll it. 18980 18981For C code, the type names may also have the form @samp{class 18982@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union 18983@var{union-tag}} or @samp{enum @var{enum-tag}}. 18984 18985@var{flags} can be used to modify how the type is displayed. 18986Available flags are: 18987 18988@table @code 18989@item r 18990Display in ``raw'' form. Normally, @value{GDBN} substitutes template 18991parameters and typedefs defined in a class when printing the class' 18992members. The @code{/r} flag disables this. 18993 18994@item m 18995Do not print methods defined in the class. 18996 18997@item M 18998Print methods defined in the class. This is the default, but the flag 18999exists in case you change the default with @command{set print type methods}. 19000 19001@item t 19002Do not print typedefs defined in the class. Note that this controls 19003whether the typedef definition itself is printed, not whether typedef 19004names are substituted when printing other types. 19005 19006@item T 19007Print typedefs defined in the class. This is the default, but the flag 19008exists in case you change the default with @command{set print type typedefs}. 19009 19010@item o 19011Print the offsets and sizes of fields in a struct, similar to what the 19012@command{pahole} tool does. This option implies the @code{/tm} flags. 19013 19014@item x 19015Use hexadecimal notation when printing offsets and sizes of fields in a 19016struct. 19017 19018@item d 19019Use decimal notation when printing offsets and sizes of fields in a 19020struct. 19021 19022For example, given the following declarations: 19023 19024@smallexample 19025struct tuv 19026@{ 19027 int a1; 19028 char *a2; 19029 int a3; 19030@}; 19031 19032struct xyz 19033@{ 19034 int f1; 19035 char f2; 19036 void *f3; 19037 struct tuv f4; 19038@}; 19039 19040union qwe 19041@{ 19042 struct tuv fff1; 19043 struct xyz fff2; 19044@}; 19045 19046struct tyu 19047@{ 19048 int a1 : 1; 19049 int a2 : 3; 19050 int a3 : 23; 19051 char a4 : 2; 19052 int64_t a5; 19053 int a6 : 5; 19054 int64_t a7 : 3; 19055@}; 19056@end smallexample 19057 19058Issuing a @kbd{ptype /o struct tuv} command would print: 19059 19060@smallexample 19061(@value{GDBP}) ptype /o struct tuv 19062/* offset | size */ type = struct tuv @{ 19063/* 0 | 4 */ int a1; 19064/* XXX 4-byte hole */ 19065/* 8 | 8 */ char *a2; 19066/* 16 | 4 */ int a3; 19067 19068 /* total size (bytes): 24 */ 19069 @} 19070@end smallexample 19071 19072Notice the format of the first column of comments. There, you can 19073find two parts separated by the @samp{|} character: the @emph{offset}, 19074which indicates where the field is located inside the struct, in 19075bytes, and the @emph{size} of the field. Another interesting line is 19076the marker of a @emph{hole} in the struct, indicating that it may be 19077possible to pack the struct and make it use less space by reorganizing 19078its fields. 19079 19080It is also possible to print offsets inside an union: 19081 19082@smallexample 19083(@value{GDBP}) ptype /o union qwe 19084/* offset | size */ type = union qwe @{ 19085/* 24 */ struct tuv @{ 19086/* 0 | 4 */ int a1; 19087/* XXX 4-byte hole */ 19088/* 8 | 8 */ char *a2; 19089/* 16 | 4 */ int a3; 19090 19091 /* total size (bytes): 24 */ 19092 @} fff1; 19093/* 40 */ struct xyz @{ 19094/* 0 | 4 */ int f1; 19095/* 4 | 1 */ char f2; 19096/* XXX 3-byte hole */ 19097/* 8 | 8 */ void *f3; 19098/* 16 | 24 */ struct tuv @{ 19099/* 16 | 4 */ int a1; 19100/* XXX 4-byte hole */ 19101/* 24 | 8 */ char *a2; 19102/* 32 | 4 */ int a3; 19103 19104 /* total size (bytes): 24 */ 19105 @} f4; 19106 19107 /* total size (bytes): 40 */ 19108 @} fff2; 19109 19110 /* total size (bytes): 40 */ 19111 @} 19112@end smallexample 19113 19114In this case, since @code{struct tuv} and @code{struct xyz} occupy the 19115same space (because we are dealing with an union), the offset is not 19116printed for them. However, you can still examine the offset of each 19117of these structures' fields. 19118 19119Another useful scenario is printing the offsets of a struct containing 19120bitfields: 19121 19122@smallexample 19123(@value{GDBP}) ptype /o struct tyu 19124/* offset | size */ type = struct tyu @{ 19125/* 0:31 | 4 */ int a1 : 1; 19126/* 0:28 | 4 */ int a2 : 3; 19127/* 0: 5 | 4 */ int a3 : 23; 19128/* 3: 3 | 1 */ signed char a4 : 2; 19129/* XXX 3-bit hole */ 19130/* XXX 4-byte hole */ 19131/* 8 | 8 */ int64_t a5; 19132/* 16: 0 | 4 */ int a6 : 5; 19133/* 16: 5 | 8 */ int64_t a7 : 3; 19134/* XXX 7-byte padding */ 19135 19136 /* total size (bytes): 24 */ 19137 @} 19138@end smallexample 19139 19140Note how the offset information is now extended to also include the 19141first bit of the bitfield. 19142@end table 19143 19144@kindex ptype 19145@item ptype[/@var{flags}] [@var{arg}] 19146@code{ptype} accepts the same arguments as @code{whatis}, but prints a 19147detailed description of the type, instead of just the name of the type. 19148@xref{Expressions, ,Expressions}. 19149 19150Contrary to @code{whatis}, @code{ptype} always unrolls any 19151@code{typedef}s in its argument declaration, whether the argument is 19152a variable, expression, or a data type. This means that @code{ptype} 19153of a variable or an expression will not print literally its type as 19154present in the source code---use @code{whatis} for that. @code{typedef}s at 19155the pointer or reference targets are also unrolled. Only @code{typedef}s of 19156fields, methods and inner @code{class typedef}s of @code{struct}s, 19157@code{class}es and @code{union}s are not unrolled even with @code{ptype}. 19158 19159For example, for this variable declaration: 19160 19161@smallexample 19162typedef double real_t; 19163struct complex @{ real_t real; double imag; @}; 19164typedef struct complex complex_t; 19165complex_t var; 19166real_t *real_pointer_var; 19167@end smallexample 19168 19169@noindent 19170the two commands give this output: 19171 19172@smallexample 19173@group 19174(@value{GDBP}) whatis var 19175type = complex_t 19176(@value{GDBP}) ptype var 19177type = struct complex @{ 19178 real_t real; 19179 double imag; 19180@} 19181(@value{GDBP}) whatis complex_t 19182type = struct complex 19183(@value{GDBP}) whatis struct complex 19184type = struct complex 19185(@value{GDBP}) ptype struct complex 19186type = struct complex @{ 19187 real_t real; 19188 double imag; 19189@} 19190(@value{GDBP}) whatis real_pointer_var 19191type = real_t * 19192(@value{GDBP}) ptype real_pointer_var 19193type = double * 19194@end group 19195@end smallexample 19196 19197@noindent 19198As with @code{whatis}, using @code{ptype} without an argument refers to 19199the type of @code{$}, the last value in the value history. 19200 19201@cindex incomplete type 19202Sometimes, programs use opaque data types or incomplete specifications 19203of complex data structure. If the debug information included in the 19204program does not allow @value{GDBN} to display a full declaration of 19205the data type, it will say @samp{<incomplete type>}. For example, 19206given these declarations: 19207 19208@smallexample 19209 struct foo; 19210 struct foo *fooptr; 19211@end smallexample 19212 19213@noindent 19214but no definition for @code{struct foo} itself, @value{GDBN} will say: 19215 19216@smallexample 19217 (@value{GDBP}) ptype foo 19218 $1 = <incomplete type> 19219@end smallexample 19220 19221@noindent 19222``Incomplete type'' is C terminology for data types that are not 19223completely specified. 19224 19225@cindex unknown type 19226Othertimes, information about a variable's type is completely absent 19227from the debug information included in the program. This most often 19228happens when the program or library where the variable is defined 19229includes no debug information at all. @value{GDBN} knows the variable 19230exists from inspecting the linker/loader symbol table (e.g., the ELF 19231dynamic symbol table), but such symbols do not contain type 19232information. Inspecting the type of a (global) variable for which 19233@value{GDBN} has no type information shows: 19234 19235@smallexample 19236 (@value{GDBP}) ptype var 19237 type = <data variable, no debug info> 19238@end smallexample 19239 19240@xref{Variables, no debug info variables}, for how to print the values 19241of such variables. 19242 19243@kindex info types 19244@item info types [-q] [@var{regexp}] 19245Print a brief description of all types whose names match the regular 19246expression @var{regexp} (or all types in your program, if you supply 19247no argument). Each complete typename is matched as though it were a 19248complete line; thus, @samp{i type value} gives information on all 19249types in your program whose names include the string @code{value}, but 19250@samp{i type ^value$} gives information only on types whose complete 19251name is @code{value}. 19252 19253In programs using different languages, @value{GDBN} chooses the syntax 19254to print the type description according to the 19255@samp{set language} value: using @samp{set language auto} 19256(see @ref{Automatically, ,Set Language Automatically}) means to use the 19257language of the type, other values mean to use 19258the manually specified language (see @ref{Manually, ,Set Language Manually}). 19259 19260This command differs from @code{ptype} in two ways: first, like 19261@code{whatis}, it does not print a detailed description; second, it 19262lists all source files and line numbers where a type is defined. 19263 19264The output from @samp{into types} is proceeded with a header line 19265describing what types are being listed. The optional flag @samp{-q}, 19266which stands for @samp{quiet}, disables printing this header 19267information. 19268 19269@kindex info type-printers 19270@item info type-printers 19271Versions of @value{GDBN} that ship with Python scripting enabled may 19272have ``type printers'' available. When using @command{ptype} or 19273@command{whatis}, these printers are consulted when the name of a type 19274is needed. @xref{Type Printing API}, for more information on writing 19275type printers. 19276 19277@code{info type-printers} displays all the available type printers. 19278 19279@kindex enable type-printer 19280@kindex disable type-printer 19281@item enable type-printer @var{name}@dots{} 19282@item disable type-printer @var{name}@dots{} 19283These commands can be used to enable or disable type printers. 19284 19285@kindex info scope 19286@cindex local variables 19287@item info scope @var{location} 19288List all the variables local to a particular scope. This command 19289accepts a @var{location} argument---a function name, a source line, or 19290an address preceded by a @samp{*}, and prints all the variables local 19291to the scope defined by that location. (@xref{Specify Location}, for 19292details about supported forms of @var{location}.) For example: 19293 19294@smallexample 19295(@value{GDBP}) @b{info scope command_line_handler} 19296Scope for command_line_handler: 19297Symbol rl is an argument at stack/frame offset 8, length 4. 19298Symbol linebuffer is in static storage at address 0x150a18, length 4. 19299Symbol linelength is in static storage at address 0x150a1c, length 4. 19300Symbol p is a local variable in register $esi, length 4. 19301Symbol p1 is a local variable in register $ebx, length 4. 19302Symbol nline is a local variable in register $edx, length 4. 19303Symbol repeat is a local variable at frame offset -8, length 4. 19304@end smallexample 19305 19306@noindent 19307This command is especially useful for determining what data to collect 19308during a @dfn{trace experiment}, see @ref{Tracepoint Actions, 19309collect}. 19310 19311@kindex info source 19312@item info source 19313Show information about the current source file---that is, the source file for 19314the function containing the current point of execution: 19315@itemize @bullet 19316@item 19317the name of the source file, and the directory containing it, 19318@item 19319the directory it was compiled in, 19320@item 19321its length, in lines, 19322@item 19323which programming language it is written in, 19324@item 19325if the debug information provides it, the program that compiled the file 19326(which may include, e.g., the compiler version and command line arguments), 19327@item 19328whether the executable includes debugging information for that file, and 19329if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and 19330@item 19331whether the debugging information includes information about 19332preprocessor macros. 19333@end itemize 19334 19335 19336@kindex info sources 19337@item info sources @r{[}-dirname | -basename@r{]} @r{[}--@r{]} @r{[}@var{regexp}@r{]} 19338 19339 19340With no options @samp{info sources} prints the names of all source 19341files in your program for which there is debugging information. The 19342source files are presented based on a list of object files 19343(executables and libraries) currently loaded into @value{GDBN}. For 19344each object file all of the associated source files are listed. 19345 19346Each source file will only be printed once for each object file, but a 19347single source file can be repeated in the output if it is part of 19348multiple object files. 19349 19350If the optional @var{regexp} is provided, then only source files that 19351match the regular expression will be printed. The matching is 19352case-sensitive, except on operating systems that have case-insensitive 19353filesystem (e.g., MS-Windows). @samp{--} can be used before 19354@var{regexp} to prevent @value{GDBN} interpreting @var{regexp} as a 19355command option (e.g. if @var{regexp} starts with @samp{-}). 19356 19357By default, the @var{regexp} is used to match anywhere in the 19358filename. If @code{-dirname}, only files having a dirname matching 19359@var{regexp} are shown. If @code{-basename}, only files having a 19360basename matching @var{regexp} are shown. 19361 19362It is possible that an object file may be printed in the list with no 19363associated source files. This can happen when either no source files 19364match @var{regexp}, or, the object file was compiled without debug 19365information and so @value{GDBN} is unable to find any source file 19366names. 19367 19368@kindex info functions 19369@item info functions [-q] [-n] 19370Print the names and data types of all defined functions. 19371Similarly to @samp{info types}, this command groups its output by source 19372files and annotates each function definition with its source line 19373number. 19374 19375In programs using different languages, @value{GDBN} chooses the syntax 19376to print the function name and type according to the 19377@samp{set language} value: using @samp{set language auto} 19378(see @ref{Automatically, ,Set Language Automatically}) means to use the 19379language of the function, other values mean to use 19380the manually specified language (see @ref{Manually, ,Set Language Manually}). 19381 19382The @samp{-n} flag excludes @dfn{non-debugging symbols} from the 19383results. A non-debugging symbol is a symbol that comes from the 19384executable's symbol table, not from the debug information (for 19385example, DWARF) associated with the executable. 19386 19387The optional flag @samp{-q}, which stands for @samp{quiet}, disables 19388printing header information and messages explaining why no functions 19389have been printed. 19390 19391@item info functions [-q] [-n] [-t @var{type_regexp}] [@var{regexp}] 19392Like @samp{info functions}, but only print the names and data types 19393of the functions selected with the provided regexp(s). 19394 19395If @var{regexp} is provided, print only the functions whose names 19396match the regular expression @var{regexp}. 19397Thus, @samp{info fun step} finds all functions whose 19398names include @code{step}; @samp{info fun ^step} finds those whose names 19399start with @code{step}. If a function name contains characters that 19400conflict with the regular expression language (e.g.@: 19401@samp{operator*()}), they may be quoted with a backslash. 19402 19403If @var{type_regexp} is provided, print only the functions whose 19404types, as printed by the @code{whatis} command, match 19405the regular expression @var{type_regexp}. 19406If @var{type_regexp} contains space(s), it should be enclosed in 19407quote characters. If needed, use backslash to escape the meaning 19408of special characters or quotes. 19409Thus, @samp{info fun -t '^int ('} finds the functions that return 19410an integer; @samp{info fun -t '(.*int.*'} finds the functions that 19411have an argument type containing int; @samp{info fun -t '^int (' ^step} 19412finds the functions whose names start with @code{step} and that return 19413int. 19414 19415If both @var{regexp} and @var{type_regexp} are provided, a function 19416is printed only if its name matches @var{regexp} and its type matches 19417@var{type_regexp}. 19418 19419 19420@kindex info variables 19421@item info variables [-q] [-n] 19422Print the names and data types of all variables that are defined 19423outside of functions (i.e.@: excluding local variables). 19424The printed variables are grouped by source files and annotated with 19425their respective source line numbers. 19426 19427In programs using different languages, @value{GDBN} chooses the syntax 19428to print the variable name and type according to the 19429@samp{set language} value: using @samp{set language auto} 19430(see @ref{Automatically, ,Set Language Automatically}) means to use the 19431language of the variable, other values mean to use 19432the manually specified language (see @ref{Manually, ,Set Language Manually}). 19433 19434The @samp{-n} flag excludes non-debugging symbols from the results. 19435 19436The optional flag @samp{-q}, which stands for @samp{quiet}, disables 19437printing header information and messages explaining why no variables 19438have been printed. 19439 19440@item info variables [-q] [-n] [-t @var{type_regexp}] [@var{regexp}] 19441Like @kbd{info variables}, but only print the variables selected 19442with the provided regexp(s). 19443 19444If @var{regexp} is provided, print only the variables whose names 19445match the regular expression @var{regexp}. 19446 19447If @var{type_regexp} is provided, print only the variables whose 19448types, as printed by the @code{whatis} command, match 19449the regular expression @var{type_regexp}. 19450If @var{type_regexp} contains space(s), it should be enclosed in 19451quote characters. If needed, use backslash to escape the meaning 19452of special characters or quotes. 19453 19454If both @var{regexp} and @var{type_regexp} are provided, an argument 19455is printed only if its name matches @var{regexp} and its type matches 19456@var{type_regexp}. 19457 19458@kindex info modules 19459@cindex modules 19460@item info modules @r{[}-q@r{]} @r{[}@var{regexp}@r{]} 19461List all Fortran modules in the program, or all modules matching the 19462optional regular expression @var{regexp}. 19463 19464The optional flag @samp{-q}, which stands for @samp{quiet}, disables 19465printing header information and messages explaining why no modules 19466have been printed. 19467 19468@kindex info module 19469@cindex Fortran modules, information about 19470@cindex functions and variables by Fortran module 19471@cindex module functions and variables 19472@item info module functions @r{[}-q@r{]} @r{[}-m @var{module-regexp}@r{]} @r{[}-t @var{type-regexp}@r{]} @r{[}@var{regexp}@r{]} 19473@itemx info module variables @r{[}-q@r{]} @r{[}-m @var{module-regexp}@r{]} @r{[}-t @var{type-regexp}@r{]} @r{[}@var{regexp}@r{]} 19474List all functions or variables within all Fortran modules. The set 19475of functions or variables listed can be limited by providing some or 19476all of the optional regular expressions. If @var{module-regexp} is 19477provided, then only Fortran modules matching @var{module-regexp} will 19478be searched. Only functions or variables whose type matches the 19479optional regular expression @var{type-regexp} will be listed. And 19480only functions or variables whose name matches the optional regular 19481expression @var{regexp} will be listed. 19482 19483The optional flag @samp{-q}, which stands for @samp{quiet}, disables 19484printing header information and messages explaining why no functions 19485or variables have been printed. 19486 19487@kindex info classes 19488@cindex Objective-C, classes and selectors 19489@item info classes 19490@itemx info classes @var{regexp} 19491Display all Objective-C classes in your program, or 19492(with the @var{regexp} argument) all those matching a particular regular 19493expression. 19494 19495@kindex info selectors 19496@item info selectors 19497@itemx info selectors @var{regexp} 19498Display all Objective-C selectors in your program, or 19499(with the @var{regexp} argument) all those matching a particular regular 19500expression. 19501 19502@ignore 19503This was never implemented. 19504@kindex info methods 19505@item info methods 19506@itemx info methods @var{regexp} 19507The @code{info methods} command permits the user to examine all defined 19508methods within C@t{++} program, or (with the @var{regexp} argument) a 19509specific set of methods found in the various C@t{++} classes. Many 19510C@t{++} classes provide a large number of methods. Thus, the output 19511from the @code{ptype} command can be overwhelming and hard to use. The 19512@code{info-methods} command filters the methods, printing only those 19513which match the regular-expression @var{regexp}. 19514@end ignore 19515 19516@cindex opaque data types 19517@kindex set opaque-type-resolution 19518@item set opaque-type-resolution on 19519Tell @value{GDBN} to resolve opaque types. An opaque type is a type 19520declared as a pointer to a @code{struct}, @code{class}, or 19521@code{union}---for example, @code{struct MyType *}---that is used in one 19522source file although the full declaration of @code{struct MyType} is in 19523another source file. The default is on. 19524 19525A change in the setting of this subcommand will not take effect until 19526the next time symbols for a file are loaded. 19527 19528@item set opaque-type-resolution off 19529Tell @value{GDBN} not to resolve opaque types. In this case, the type 19530is printed as follows: 19531@smallexample 19532@{<no data fields>@} 19533@end smallexample 19534 19535@kindex show opaque-type-resolution 19536@item show opaque-type-resolution 19537Show whether opaque types are resolved or not. 19538 19539@kindex set print symbol-loading 19540@cindex print messages when symbols are loaded 19541@item set print symbol-loading 19542@itemx set print symbol-loading full 19543@itemx set print symbol-loading brief 19544@itemx set print symbol-loading off 19545The @code{set print symbol-loading} command allows you to control the 19546printing of messages when @value{GDBN} loads symbol information. 19547By default a message is printed for the executable and one for each 19548shared library, and normally this is what you want. However, when 19549debugging apps with large numbers of shared libraries these messages 19550can be annoying. 19551When set to @code{brief} a message is printed for each executable, 19552and when @value{GDBN} loads a collection of shared libraries at once 19553it will only print one message regardless of the number of shared 19554libraries. When set to @code{off} no messages are printed. 19555 19556@kindex show print symbol-loading 19557@item show print symbol-loading 19558Show whether messages will be printed when a @value{GDBN} command 19559entered from the keyboard causes symbol information to be loaded. 19560 19561@kindex maint print symbols 19562@cindex symbol dump 19563@kindex maint print psymbols 19564@cindex partial symbol dump 19565@kindex maint print msymbols 19566@cindex minimal symbol dump 19567@item maint print symbols @r{[}-pc @var{address}@r{]} @r{[}@var{filename}@r{]} 19568@itemx maint print symbols @r{[}-objfile @var{objfile}@r{]} @r{[}-source @var{source}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]} 19569@itemx maint print psymbols @r{[}-objfile @var{objfile}@r{]} @r{[}-pc @var{address}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]} 19570@itemx maint print psymbols @r{[}-objfile @var{objfile}@r{]} @r{[}-source @var{source}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]} 19571@itemx maint print msymbols @r{[}-objfile @var{objfile}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]} 19572Write a dump of debugging symbol data into the file @var{filename} or 19573the terminal if @var{filename} is unspecified. 19574If @code{-objfile @var{objfile}} is specified, only dump symbols for 19575that objfile. 19576If @code{-pc @var{address}} is specified, only dump symbols for the file 19577with code at that address. Note that @var{address} may be a symbol like 19578@code{main}. 19579If @code{-source @var{source}} is specified, only dump symbols for that 19580source file. 19581 19582These commands are used to debug the @value{GDBN} symbol-reading code. 19583These commands do not modify internal @value{GDBN} state, therefore 19584@samp{maint print symbols} will only print symbols for already expanded symbol 19585tables. 19586You can use the command @code{info sources} to find out which files these are. 19587If you use @samp{maint print psymbols} instead, the dump shows information 19588about symbols that @value{GDBN} only knows partially---that is, symbols 19589defined in files that @value{GDBN} has skimmed, but not yet read completely. 19590Finally, @samp{maint print msymbols} just dumps ``minimal symbols'', e.g., 19591``ELF symbols''. 19592 19593@xref{Files, ,Commands to Specify Files}, for a discussion of how 19594@value{GDBN} reads symbols (in the description of @code{symbol-file}). 19595 19596@kindex maint info symtabs 19597@kindex maint info psymtabs 19598@cindex listing @value{GDBN}'s internal symbol tables 19599@cindex symbol tables, listing @value{GDBN}'s internal 19600@cindex full symbol tables, listing @value{GDBN}'s internal 19601@cindex partial symbol tables, listing @value{GDBN}'s internal 19602@item maint info symtabs @r{[} @var{regexp} @r{]} 19603@itemx maint info psymtabs @r{[} @var{regexp} @r{]} 19604 19605List the @code{struct symtab} or @code{struct partial_symtab} 19606structures whose names match @var{regexp}. If @var{regexp} is not 19607given, list them all. The output includes expressions which you can 19608copy into a @value{GDBN} debugging this one to examine a particular 19609structure in more detail. For example: 19610 19611@smallexample 19612(@value{GDBP}) maint info psymtabs dwarf2read 19613@{ objfile /home/gnu/build/gdb/gdb 19614 ((struct objfile *) 0x82e69d0) 19615 @{ psymtab /home/gnu/src/gdb/dwarf2read.c 19616 ((struct partial_symtab *) 0x8474b10) 19617 readin no 19618 fullname (null) 19619 text addresses 0x814d3c8 -- 0x8158074 19620 globals (* (struct partial_symbol **) 0x8507a08 @@ 9) 19621 statics (* (struct partial_symbol **) 0x40e95b78 @@ 2882) 19622 dependencies (none) 19623 @} 19624@} 19625(@value{GDBP}) maint info symtabs 19626(@value{GDBP}) 19627@end smallexample 19628@noindent 19629We see that there is one partial symbol table whose filename contains 19630the string @samp{dwarf2read}, belonging to the @samp{gdb} executable; 19631and we see that @value{GDBN} has not read in any symtabs yet at all. 19632If we set a breakpoint on a function, that will cause @value{GDBN} to 19633read the symtab for the compilation unit containing that function: 19634 19635@smallexample 19636(@value{GDBP}) break dwarf2_psymtab_to_symtab 19637Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, 19638line 1574. 19639(@value{GDBP}) maint info symtabs 19640@{ objfile /home/gnu/build/gdb/gdb 19641 ((struct objfile *) 0x82e69d0) 19642 @{ symtab /home/gnu/src/gdb/dwarf2read.c 19643 ((struct symtab *) 0x86c1f38) 19644 dirname (null) 19645 fullname (null) 19646 blockvector ((struct blockvector *) 0x86c1bd0) (primary) 19647 linetable ((struct linetable *) 0x8370fa0) 19648 debugformat DWARF 2 19649 @} 19650@} 19651(@value{GDBP}) 19652@end smallexample 19653 19654@kindex maint info line-table 19655@cindex listing @value{GDBN}'s internal line tables 19656@cindex line tables, listing @value{GDBN}'s internal 19657@item maint info line-table @r{[} @var{regexp} @r{]} 19658 19659List the @code{struct linetable} from all @code{struct symtab} 19660instances whose name matches @var{regexp}. If @var{regexp} is not 19661given, list the @code{struct linetable} from all @code{struct symtab}. 19662 19663@kindex maint set symbol-cache-size 19664@cindex symbol cache size 19665@item maint set symbol-cache-size @var{size} 19666Set the size of the symbol cache to @var{size}. 19667The default size is intended to be good enough for debugging 19668most applications. This option exists to allow for experimenting 19669with different sizes. 19670 19671@kindex maint show symbol-cache-size 19672@item maint show symbol-cache-size 19673Show the size of the symbol cache. 19674 19675@kindex maint print symbol-cache 19676@cindex symbol cache, printing its contents 19677@item maint print symbol-cache 19678Print the contents of the symbol cache. 19679This is useful when debugging symbol cache issues. 19680 19681@kindex maint print symbol-cache-statistics 19682@cindex symbol cache, printing usage statistics 19683@item maint print symbol-cache-statistics 19684Print symbol cache usage statistics. 19685This helps determine how well the cache is being utilized. 19686 19687@kindex maint flush symbol-cache 19688@kindex maint flush-symbol-cache 19689@cindex symbol cache, flushing 19690@item maint flush symbol-cache 19691@itemx maint flush-symbol-cache 19692Flush the contents of the symbol cache, all entries are removed. This 19693command is useful when debugging the symbol cache. It is also useful 19694when collecting performance data. The command @code{maint 19695flush-symbol-cache} is deprecated in favor of @code{maint flush 19696symbol-cache}.. 19697 19698@end table 19699 19700@node Altering 19701@chapter Altering Execution 19702 19703Once you think you have found an error in your program, you might want to 19704find out for certain whether correcting the apparent error would lead to 19705correct results in the rest of the run. You can find the answer by 19706experiment, using the @value{GDBN} features for altering execution of the 19707program. 19708 19709For example, you can store new values into variables or memory 19710locations, give your program a signal, restart it at a different 19711address, or even return prematurely from a function. 19712 19713@menu 19714* Assignment:: Assignment to variables 19715* Jumping:: Continuing at a different address 19716* Signaling:: Giving your program a signal 19717* Returning:: Returning from a function 19718* Calling:: Calling your program's functions 19719* Patching:: Patching your program 19720* Compiling and Injecting Code:: Compiling and injecting code in @value{GDBN} 19721@end menu 19722 19723@node Assignment 19724@section Assignment to Variables 19725 19726@cindex assignment 19727@cindex setting variables 19728To alter the value of a variable, evaluate an assignment expression. 19729@xref{Expressions, ,Expressions}. For example, 19730 19731@smallexample 19732print x=4 19733@end smallexample 19734 19735@noindent 19736stores the value 4 into the variable @code{x}, and then prints the 19737value of the assignment expression (which is 4). 19738@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more 19739information on operators in supported languages. 19740 19741@kindex set variable 19742@cindex variables, setting 19743If you are not interested in seeing the value of the assignment, use the 19744@code{set} command instead of the @code{print} command. @code{set} is 19745really the same as @code{print} except that the expression's value is 19746not printed and is not put in the value history (@pxref{Value History, 19747,Value History}). The expression is evaluated only for its effects. 19748 19749If the beginning of the argument string of the @code{set} command 19750appears identical to a @code{set} subcommand, use the @code{set 19751variable} command instead of just @code{set}. This command is identical 19752to @code{set} except for its lack of subcommands. For example, if your 19753program has a variable @code{width}, you get an error if you try to set 19754a new value with just @samp{set width=13}, because @value{GDBN} has the 19755command @code{set width}: 19756 19757@smallexample 19758(@value{GDBP}) whatis width 19759type = double 19760(@value{GDBP}) p width 19761$4 = 13 19762(@value{GDBP}) set width=47 19763Invalid syntax in expression. 19764@end smallexample 19765 19766@noindent 19767The invalid expression, of course, is @samp{=47}. In 19768order to actually set the program's variable @code{width}, use 19769 19770@smallexample 19771(@value{GDBP}) set var width=47 19772@end smallexample 19773 19774Because the @code{set} command has many subcommands that can conflict 19775with the names of program variables, it is a good idea to use the 19776@code{set variable} command instead of just @code{set}. For example, if 19777your program has a variable @code{g}, you run into problems if you try 19778to set a new value with just @samp{set g=4}, because @value{GDBN} has 19779the command @code{set gnutarget}, abbreviated @code{set g}: 19780 19781@smallexample 19782@group 19783(@value{GDBP}) whatis g 19784type = double 19785(@value{GDBP}) p g 19786$1 = 1 19787(@value{GDBP}) set g=4 19788(@value{GDBP}) p g 19789$2 = 1 19790(@value{GDBP}) r 19791The program being debugged has been started already. 19792Start it from the beginning? (y or n) y 19793Starting program: /home/smith/cc_progs/a.out 19794"/home/smith/cc_progs/a.out": can't open to read symbols: 19795 Invalid bfd target. 19796(@value{GDBP}) show g 19797The current BFD target is "=4". 19798@end group 19799@end smallexample 19800 19801@noindent 19802The program variable @code{g} did not change, and you silently set the 19803@code{gnutarget} to an invalid value. In order to set the variable 19804@code{g}, use 19805 19806@smallexample 19807(@value{GDBP}) set var g=4 19808@end smallexample 19809 19810@value{GDBN} allows more implicit conversions in assignments than C; you can 19811freely store an integer value into a pointer variable or vice versa, 19812and you can convert any structure to any other structure that is the 19813same length or shorter. 19814@comment FIXME: how do structs align/pad in these conversions? 19815@comment /doc@cygnus.com 18dec1990 19816 19817To store values into arbitrary places in memory, use the @samp{@{@dots{}@}} 19818construct to generate a value of specified type at a specified address 19819(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers 19820to memory location @code{0x83040} as an integer (which implies a certain size 19821and representation in memory), and 19822 19823@smallexample 19824set @{int@}0x83040 = 4 19825@end smallexample 19826 19827@noindent 19828stores the value 4 into that memory location. 19829 19830@node Jumping 19831@section Continuing at a Different Address 19832 19833Ordinarily, when you continue your program, you do so at the place where 19834it stopped, with the @code{continue} command. You can instead continue at 19835an address of your own choosing, with the following commands: 19836 19837@table @code 19838@kindex jump 19839@kindex j @r{(@code{jump})} 19840@item jump @var{location} 19841@itemx j @var{location} 19842Resume execution at @var{location}. Execution stops again immediately 19843if there is a breakpoint there. @xref{Specify Location}, for a description 19844of the different forms of @var{location}. It is common 19845practice to use the @code{tbreak} command in conjunction with 19846@code{jump}. @xref{Set Breaks, ,Setting Breakpoints}. 19847 19848The @code{jump} command does not change the current stack frame, or 19849the stack pointer, or the contents of any memory location or any 19850register other than the program counter. If @var{location} is in 19851a different function from the one currently executing, the results may 19852be bizarre if the two functions expect different patterns of arguments or 19853of local variables. For this reason, the @code{jump} command requests 19854confirmation if the specified line is not in the function currently 19855executing. However, even bizarre results are predictable if you are 19856well acquainted with the machine-language code of your program. 19857@end table 19858 19859On many systems, you can get much the same effect as the @code{jump} 19860command by storing a new value into the register @code{$pc}. The 19861difference is that this does not start your program running; it only 19862changes the address of where it @emph{will} run when you continue. For 19863example, 19864 19865@smallexample 19866set $pc = 0x485 19867@end smallexample 19868 19869@noindent 19870makes the next @code{continue} command or stepping command execute at 19871address @code{0x485}, rather than at the address where your program stopped. 19872@xref{Continuing and Stepping, ,Continuing and Stepping}. 19873 19874The most common occasion to use the @code{jump} command is to back 19875up---perhaps with more breakpoints set---over a portion of a program 19876that has already executed, in order to examine its execution in more 19877detail. 19878 19879@c @group 19880@node Signaling 19881@section Giving your Program a Signal 19882@cindex deliver a signal to a program 19883 19884@table @code 19885@kindex signal 19886@item signal @var{signal} 19887Resume execution where your program is stopped, but immediately give it the 19888signal @var{signal}. The @var{signal} can be the name or the number of a 19889signal. For example, on many systems @code{signal 2} and @code{signal 19890SIGINT} are both ways of sending an interrupt signal. 19891 19892Alternatively, if @var{signal} is zero, continue execution without 19893giving a signal. This is useful when your program stopped on account of 19894a signal and would ordinarily see the signal when resumed with the 19895@code{continue} command; @samp{signal 0} causes it to resume without a 19896signal. 19897 19898@emph{Note:} When resuming a multi-threaded program, @var{signal} is 19899delivered to the currently selected thread, not the thread that last 19900reported a stop. This includes the situation where a thread was 19901stopped due to a signal. So if you want to continue execution 19902suppressing the signal that stopped a thread, you should select that 19903same thread before issuing the @samp{signal 0} command. If you issue 19904the @samp{signal 0} command with another thread as the selected one, 19905@value{GDBN} detects that and asks for confirmation. 19906 19907Invoking the @code{signal} command is not the same as invoking the 19908@code{kill} utility from the shell. Sending a signal with @code{kill} 19909causes @value{GDBN} to decide what to do with the signal depending on 19910the signal handling tables (@pxref{Signals}). The @code{signal} command 19911passes the signal directly to your program. 19912 19913@code{signal} does not repeat when you press @key{RET} a second time 19914after executing the command. 19915 19916@kindex queue-signal 19917@item queue-signal @var{signal} 19918Queue @var{signal} to be delivered immediately to the current thread 19919when execution of the thread resumes. The @var{signal} can be the name or 19920the number of a signal. For example, on many systems @code{signal 2} and 19921@code{signal SIGINT} are both ways of sending an interrupt signal. 19922The handling of the signal must be set to pass the signal to the program, 19923otherwise @value{GDBN} will report an error. 19924You can control the handling of signals from @value{GDBN} with the 19925@code{handle} command (@pxref{Signals}). 19926 19927Alternatively, if @var{signal} is zero, any currently queued signal 19928for the current thread is discarded and when execution resumes no signal 19929will be delivered. This is useful when your program stopped on account 19930of a signal and would ordinarily see the signal when resumed with the 19931@code{continue} command. 19932 19933This command differs from the @code{signal} command in that the signal 19934is just queued, execution is not resumed. And @code{queue-signal} cannot 19935be used to pass a signal whose handling state has been set to @code{nopass} 19936(@pxref{Signals}). 19937@end table 19938@c @end group 19939 19940@xref{stepping into signal handlers}, for information on how stepping 19941commands behave when the thread has a signal queued. 19942 19943@node Returning 19944@section Returning from a Function 19945 19946@table @code 19947@cindex returning from a function 19948@kindex return 19949@item return 19950@itemx return @var{expression} 19951You can cancel execution of a function call with the @code{return} 19952command. If you give an 19953@var{expression} argument, its value is used as the function's return 19954value. 19955@end table 19956 19957When you use @code{return}, @value{GDBN} discards the selected stack frame 19958(and all frames within it). You can think of this as making the 19959discarded frame return prematurely. If you wish to specify a value to 19960be returned, give that value as the argument to @code{return}. 19961 19962This pops the selected stack frame (@pxref{Selection, ,Selecting a 19963Frame}), and any other frames inside of it, leaving its caller as the 19964innermost remaining frame. That frame becomes selected. The 19965specified value is stored in the registers used for returning values 19966of functions. 19967 19968The @code{return} command does not resume execution; it leaves the 19969program stopped in the state that would exist if the function had just 19970returned. In contrast, the @code{finish} command (@pxref{Continuing 19971and Stepping, ,Continuing and Stepping}) resumes execution until the 19972selected stack frame returns naturally. 19973 19974@value{GDBN} needs to know how the @var{expression} argument should be set for 19975the inferior. The concrete registers assignment depends on the OS ABI and the 19976type being returned by the selected stack frame. For example it is common for 19977OS ABI to return floating point values in FPU registers while integer values in 19978CPU registers. Still some ABIs return even floating point values in CPU 19979registers. Larger integer widths (such as @code{long long int}) also have 19980specific placement rules. @value{GDBN} already knows the OS ABI from its 19981current target so it needs to find out also the type being returned to make the 19982assignment into the right register(s). 19983 19984Normally, the selected stack frame has debug info. @value{GDBN} will always 19985use the debug info instead of the implicit type of @var{expression} when the 19986debug info is available. For example, if you type @kbd{return -1}, and the 19987function in the current stack frame is declared to return a @code{long long 19988int}, @value{GDBN} transparently converts the implicit @code{int} value of -1 19989into a @code{long long int}: 19990 19991@smallexample 19992Breakpoint 1, func () at gdb.base/return-nodebug.c:29 1999329 return 31; 19994(@value{GDBP}) return -1 19995Make func return now? (y or n) y 19996#0 0x004004f6 in main () at gdb.base/return-nodebug.c:43 1999743 printf ("result=%lld\n", func ()); 19998(@value{GDBP}) 19999@end smallexample 20000 20001However, if the selected stack frame does not have a debug info, e.g., if the 20002function was compiled without debug info, @value{GDBN} has to find out the type 20003to return from user. Specifying a different type by mistake may set the value 20004in different inferior registers than the caller code expects. For example, 20005typing @kbd{return -1} with its implicit type @code{int} would set only a part 20006of a @code{long long int} result for a debug info less function (on 32-bit 20007architectures). Therefore the user is required to specify the return type by 20008an appropriate cast explicitly: 20009 20010@smallexample 20011Breakpoint 2, 0x0040050b in func () 20012(@value{GDBP}) return -1 20013Return value type not available for selected stack frame. 20014Please use an explicit cast of the value to return. 20015(@value{GDBP}) return (long long int) -1 20016Make selected stack frame return now? (y or n) y 20017#0 0x00400526 in main () 20018(@value{GDBP}) 20019@end smallexample 20020 20021@node Calling 20022@section Calling Program Functions 20023 20024@table @code 20025@cindex calling functions 20026@cindex inferior functions, calling 20027@item print @var{expr} 20028Evaluate the expression @var{expr} and display the resulting value. 20029The expression may include calls to functions in the program being 20030debugged. 20031 20032@kindex call 20033@item call @var{expr} 20034Evaluate the expression @var{expr} without displaying @code{void} 20035returned values. 20036 20037You can use this variant of the @code{print} command if you want to 20038execute a function from your program that does not return anything 20039(a.k.a.@: @dfn{a void function}), but without cluttering the output 20040with @code{void} returned values that @value{GDBN} will otherwise 20041print. If the result is not void, it is printed and saved in the 20042value history. 20043@end table 20044 20045It is possible for the function you call via the @code{print} or 20046@code{call} command to generate a signal (e.g., if there's a bug in 20047the function, or if you passed it incorrect arguments). What happens 20048in that case is controlled by the @code{set unwindonsignal} command. 20049 20050Similarly, with a C@t{++} program it is possible for the function you 20051call via the @code{print} or @code{call} command to generate an 20052exception that is not handled due to the constraints of the dummy 20053frame. In this case, any exception that is raised in the frame, but has 20054an out-of-frame exception handler will not be found. GDB builds a 20055dummy-frame for the inferior function call, and the unwinder cannot 20056seek for exception handlers outside of this dummy-frame. What happens 20057in that case is controlled by the 20058@code{set unwind-on-terminating-exception} command. 20059 20060@table @code 20061@item set unwindonsignal 20062@kindex set unwindonsignal 20063@cindex unwind stack in called functions 20064@cindex call dummy stack unwinding 20065Set unwinding of the stack if a signal is received while in a function 20066that @value{GDBN} called in the program being debugged. If set to on, 20067@value{GDBN} unwinds the stack it created for the call and restores 20068the context to what it was before the call. If set to off (the 20069default), @value{GDBN} stops in the frame where the signal was 20070received. 20071 20072@item show unwindonsignal 20073@kindex show unwindonsignal 20074Show the current setting of stack unwinding in the functions called by 20075@value{GDBN}. 20076 20077@item set unwind-on-terminating-exception 20078@kindex set unwind-on-terminating-exception 20079@cindex unwind stack in called functions with unhandled exceptions 20080@cindex call dummy stack unwinding on unhandled exception. 20081Set unwinding of the stack if a C@t{++} exception is raised, but left 20082unhandled while in a function that @value{GDBN} called in the program being 20083debugged. If set to on (the default), @value{GDBN} unwinds the stack 20084it created for the call and restores the context to what it was before 20085the call. If set to off, @value{GDBN} the exception is delivered to 20086the default C@t{++} exception handler and the inferior terminated. 20087 20088@item show unwind-on-terminating-exception 20089@kindex show unwind-on-terminating-exception 20090Show the current setting of stack unwinding in the functions called by 20091@value{GDBN}. 20092 20093@item set may-call-functions 20094@kindex set may-call-functions 20095@cindex disabling calling functions in the program 20096@cindex calling functions in the program, disabling 20097Set permission to call functions in the program. 20098This controls whether @value{GDBN} will attempt to call functions in 20099the program, such as with expressions in the @code{print} command. It 20100defaults to @code{on}. 20101 20102To call a function in the program, @value{GDBN} has to temporarily 20103modify the state of the inferior. This has potentially undesired side 20104effects. Also, having @value{GDBN} call nested functions is likely to 20105be erroneous and may even crash the program being debugged. You can 20106avoid such hazards by forbidding @value{GDBN} from calling functions 20107in the program being debugged. If calling functions in the program 20108is forbidden, GDB will throw an error when a command (such as printing 20109an expression) starts a function call in the program. 20110 20111@item show may-call-functions 20112@kindex show may-call-functions 20113Show permission to call functions in the program. 20114 20115@end table 20116 20117@subsection Calling functions with no debug info 20118 20119@cindex no debug info functions 20120Sometimes, a function you wish to call is missing debug information. 20121In such case, @value{GDBN} does not know the type of the function, 20122including the types of the function's parameters. To avoid calling 20123the inferior function incorrectly, which could result in the called 20124function functioning erroneously and even crash, @value{GDBN} refuses 20125to call the function unless you tell it the type of the function. 20126 20127For prototyped (i.e.@: ANSI/ISO style) functions, there are two ways 20128to do that. The simplest is to cast the call to the function's 20129declared return type. For example: 20130 20131@smallexample 20132(@value{GDBP}) p getenv ("PATH") 20133'getenv' has unknown return type; cast the call to its declared return type 20134(@value{GDBP}) p (char *) getenv ("PATH") 20135$1 = 0x7fffffffe7ba "/usr/local/bin:/"... 20136@end smallexample 20137 20138Casting the return type of a no-debug function is equivalent to 20139casting the function to a pointer to a prototyped function that has a 20140prototype that matches the types of the passed-in arguments, and 20141calling that. I.e., the call above is equivalent to: 20142 20143@smallexample 20144(@value{GDBP}) p ((char * (*) (const char *)) getenv) ("PATH") 20145@end smallexample 20146 20147@noindent 20148and given this prototyped C or C++ function with float parameters: 20149 20150@smallexample 20151float multiply (float v1, float v2) @{ return v1 * v2; @} 20152@end smallexample 20153 20154@noindent 20155these calls are equivalent: 20156 20157@smallexample 20158(@value{GDBP}) p (float) multiply (2.0f, 3.0f) 20159(@value{GDBP}) p ((float (*) (float, float)) multiply) (2.0f, 3.0f) 20160@end smallexample 20161 20162If the function you wish to call is declared as unprototyped (i.e.@: 20163old K&R style), you must use the cast-to-function-pointer syntax, so 20164that @value{GDBN} knows that it needs to apply default argument 20165promotions (promote float arguments to double). @xref{ABI, float 20166promotion}. For example, given this unprototyped C function with 20167float parameters, and no debug info: 20168 20169@smallexample 20170float 20171multiply_noproto (v1, v2) 20172 float v1, v2; 20173@{ 20174 return v1 * v2; 20175@} 20176@end smallexample 20177 20178@noindent 20179you call it like this: 20180 20181@smallexample 20182 (@value{GDBP}) p ((float (*) ()) multiply_noproto) (2.0f, 3.0f) 20183@end smallexample 20184 20185@node Patching 20186@section Patching Programs 20187 20188@cindex patching binaries 20189@cindex writing into executables 20190@cindex writing into corefiles 20191 20192By default, @value{GDBN} opens the file containing your program's 20193executable code (or the corefile) read-only. This prevents accidental 20194alterations to machine code; but it also prevents you from intentionally 20195patching your program's binary. 20196 20197If you'd like to be able to patch the binary, you can specify that 20198explicitly with the @code{set write} command. For example, you might 20199want to turn on internal debugging flags, or even to make emergency 20200repairs. 20201 20202@table @code 20203@kindex set write 20204@item set write on 20205@itemx set write off 20206If you specify @samp{set write on}, @value{GDBN} opens executable and 20207core files for both reading and writing; if you specify @kbd{set write 20208off} (the default), @value{GDBN} opens them read-only. 20209 20210If you have already loaded a file, you must load it again (using the 20211@code{exec-file} or @code{core-file} command) after changing @code{set 20212write}, for your new setting to take effect. 20213 20214@item show write 20215@kindex show write 20216Display whether executable files and core files are opened for writing 20217as well as reading. 20218@end table 20219 20220@node Compiling and Injecting Code 20221@section Compiling and injecting code in @value{GDBN} 20222@cindex injecting code 20223@cindex writing into executables 20224@cindex compiling code 20225 20226@value{GDBN} supports on-demand compilation and code injection into 20227programs running under @value{GDBN}. GCC 5.0 or higher built with 20228@file{libcc1.so} must be installed for this functionality to be enabled. 20229This functionality is implemented with the following commands. 20230 20231@table @code 20232@kindex compile code 20233@item compile code @var{source-code} 20234@itemx compile code -raw @var{--} @var{source-code} 20235Compile @var{source-code} with the compiler language found as the current 20236language in @value{GDBN} (@pxref{Languages}). If compilation and 20237injection is not supported with the current language specified in 20238@value{GDBN}, or the compiler does not support this feature, an error 20239message will be printed. If @var{source-code} compiles and links 20240successfully, @value{GDBN} will load the object-code emitted, 20241and execute it within the context of the currently selected inferior. 20242It is important to note that the compiled code is executed immediately. 20243After execution, the compiled code is removed from @value{GDBN} and any 20244new types or variables you have defined will be deleted. 20245 20246The command allows you to specify @var{source-code} in two ways. 20247The simplest method is to provide a single line of code to the command. 20248E.g.: 20249 20250@smallexample 20251compile code printf ("hello world\n"); 20252@end smallexample 20253 20254If you specify options on the command line as well as source code, they 20255may conflict. The @samp{--} delimiter can be used to separate options 20256from actual source code. E.g.: 20257 20258@smallexample 20259compile code -r -- printf ("hello world\n"); 20260@end smallexample 20261 20262Alternatively you can enter source code as multiple lines of text. To 20263enter this mode, invoke the @samp{compile code} command without any text 20264following the command. This will start the multiple-line editor and 20265allow you to type as many lines of source code as required. When you 20266have completed typing, enter @samp{end} on its own line to exit the 20267editor. 20268 20269@smallexample 20270compile code 20271>printf ("hello\n"); 20272>printf ("world\n"); 20273>end 20274@end smallexample 20275 20276Specifying @samp{-raw}, prohibits @value{GDBN} from wrapping the 20277provided @var{source-code} in a callable scope. In this case, you must 20278specify the entry point of the code by defining a function named 20279@code{_gdb_expr_}. The @samp{-raw} code cannot access variables of the 20280inferior. Using @samp{-raw} option may be needed for example when 20281@var{source-code} requires @samp{#include} lines which may conflict with 20282inferior symbols otherwise. 20283 20284@kindex compile file 20285@item compile file @var{filename} 20286@itemx compile file -raw @var{filename} 20287Like @code{compile code}, but take the source code from @var{filename}. 20288 20289@smallexample 20290compile file /home/user/example.c 20291@end smallexample 20292@end table 20293 20294@table @code 20295@item compile print [[@var{options}] --] @var{expr} 20296@itemx compile print [[@var{options}] --] /@var{f} @var{expr} 20297Compile and execute @var{expr} with the compiler language found as the 20298current language in @value{GDBN} (@pxref{Languages}). By default the 20299value of @var{expr} is printed in a format appropriate to its data type; 20300you can choose a different format by specifying @samp{/@var{f}}, where 20301@var{f} is a letter specifying the format; see @ref{Output Formats,,Output 20302Formats}. The @code{compile print} command accepts the same options 20303as the @code{print} command; see @ref{print options}. 20304 20305@item compile print [[@var{options}] --] 20306@itemx compile print [[@var{options}] --] /@var{f} 20307@cindex reprint the last value 20308Alternatively you can enter the expression (source code producing it) as 20309multiple lines of text. To enter this mode, invoke the @samp{compile print} 20310command without any text following the command. This will start the 20311multiple-line editor. 20312@end table 20313 20314@noindent 20315The process of compiling and injecting the code can be inspected using: 20316 20317@table @code 20318@anchor{set debug compile} 20319@item set debug compile 20320@cindex compile command debugging info 20321Turns on or off display of @value{GDBN} process of compiling and 20322injecting the code. The default is off. 20323 20324@item show debug compile 20325Displays the current state of displaying @value{GDBN} process of 20326compiling and injecting the code. 20327 20328@anchor{set debug compile-cplus-types} 20329@item set debug compile-cplus-types 20330@cindex compile C@t{++} type conversion 20331Turns on or off the display of C@t{++} type conversion debugging information. 20332The default is off. 20333 20334@item show debug compile-cplus-types 20335Displays the current state of displaying debugging information for 20336C@t{++} type conversion. 20337@end table 20338 20339@subsection Compilation options for the @code{compile} command 20340 20341@value{GDBN} needs to specify the right compilation options for the code 20342to be injected, in part to make its ABI compatible with the inferior 20343and in part to make the injected code compatible with @value{GDBN}'s 20344injecting process. 20345 20346@noindent 20347The options used, in increasing precedence: 20348 20349@table @asis 20350@item target architecture and OS options (@code{gdbarch}) 20351These options depend on target processor type and target operating 20352system, usually they specify at least 32-bit (@code{-m32}) or 64-bit 20353(@code{-m64}) compilation option. 20354 20355@item compilation options recorded in the target 20356@value{NGCC} (since version 4.7) stores the options used for compilation 20357into @code{DW_AT_producer} part of DWARF debugging information according 20358to the @value{NGCC} option @code{-grecord-gcc-switches}. One has to 20359explicitly specify @code{-g} during inferior compilation otherwise 20360@value{NGCC} produces no DWARF. This feature is only relevant for 20361platforms where @code{-g} produces DWARF by default, otherwise one may 20362try to enforce DWARF by using @code{-gdwarf-4}. 20363 20364@item compilation options set by @code{set compile-args} 20365@end table 20366 20367@noindent 20368You can override compilation options using the following command: 20369 20370@table @code 20371@item set compile-args 20372@cindex compile command options override 20373Set compilation options used for compiling and injecting code with the 20374@code{compile} commands. These options override any conflicting ones 20375from the target architecture and/or options stored during inferior 20376compilation. 20377 20378@item show compile-args 20379Displays the current state of compilation options override. 20380This does not show all the options actually used during compilation, 20381use @ref{set debug compile} for that. 20382@end table 20383 20384@subsection Caveats when using the @code{compile} command 20385 20386There are a few caveats to keep in mind when using the @code{compile} 20387command. As the caveats are different per language, the table below 20388highlights specific issues on a per language basis. 20389 20390@table @asis 20391@item C code examples and caveats 20392When the language in @value{GDBN} is set to @samp{C}, the compiler will 20393attempt to compile the source code with a @samp{C} compiler. The source 20394code provided to the @code{compile} command will have much the same 20395access to variables and types as it normally would if it were part of 20396the program currently being debugged in @value{GDBN}. 20397 20398Below is a sample program that forms the basis of the examples that 20399follow. This program has been compiled and loaded into @value{GDBN}, 20400much like any other normal debugging session. 20401 20402@smallexample 20403void function1 (void) 20404@{ 20405 int i = 42; 20406 printf ("function 1\n"); 20407@} 20408 20409void function2 (void) 20410@{ 20411 int j = 12; 20412 function1 (); 20413@} 20414 20415int main(void) 20416@{ 20417 int k = 6; 20418 int *p; 20419 function2 (); 20420 return 0; 20421@} 20422@end smallexample 20423 20424For the purposes of the examples in this section, the program above has 20425been compiled, loaded into @value{GDBN}, stopped at the function 20426@code{main}, and @value{GDBN} is awaiting input from the user. 20427 20428To access variables and types for any program in @value{GDBN}, the 20429program must be compiled and packaged with debug information. The 20430@code{compile} command is not an exception to this rule. Without debug 20431information, you can still use the @code{compile} command, but you will 20432be very limited in what variables and types you can access. 20433 20434So with that in mind, the example above has been compiled with debug 20435information enabled. The @code{compile} command will have access to 20436all variables and types (except those that may have been optimized 20437out). Currently, as @value{GDBN} has stopped the program in the 20438@code{main} function, the @code{compile} command would have access to 20439the variable @code{k}. You could invoke the @code{compile} command 20440and type some source code to set the value of @code{k}. You can also 20441read it, or do anything with that variable you would normally do in 20442@code{C}. Be aware that changes to inferior variables in the 20443@code{compile} command are persistent. In the following example: 20444 20445@smallexample 20446compile code k = 3; 20447@end smallexample 20448 20449@noindent 20450the variable @code{k} is now 3. It will retain that value until 20451something else in the example program changes it, or another 20452@code{compile} command changes it. 20453 20454Normal scope and access rules apply to source code compiled and 20455injected by the @code{compile} command. In the example, the variables 20456@code{j} and @code{k} are not accessible yet, because the program is 20457currently stopped in the @code{main} function, where these variables 20458are not in scope. Therefore, the following command 20459 20460@smallexample 20461compile code j = 3; 20462@end smallexample 20463 20464@noindent 20465will result in a compilation error message. 20466 20467Once the program is continued, execution will bring these variables in 20468scope, and they will become accessible; then the code you specify via 20469the @code{compile} command will be able to access them. 20470 20471You can create variables and types with the @code{compile} command as 20472part of your source code. Variables and types that are created as part 20473of the @code{compile} command are not visible to the rest of the program for 20474the duration of its run. This example is valid: 20475 20476@smallexample 20477compile code int ff = 5; printf ("ff is %d\n", ff); 20478@end smallexample 20479 20480However, if you were to type the following into @value{GDBN} after that 20481command has completed: 20482 20483@smallexample 20484compile code printf ("ff is %d\n'', ff); 20485@end smallexample 20486 20487@noindent 20488a compiler error would be raised as the variable @code{ff} no longer 20489exists. Object code generated and injected by the @code{compile} 20490command is removed when its execution ends. Caution is advised 20491when assigning to program variables values of variables created by the 20492code submitted to the @code{compile} command. This example is valid: 20493 20494@smallexample 20495compile code int ff = 5; k = ff; 20496@end smallexample 20497 20498The value of the variable @code{ff} is assigned to @code{k}. The variable 20499@code{k} does not require the existence of @code{ff} to maintain the value 20500it has been assigned. However, pointers require particular care in 20501assignment. If the source code compiled with the @code{compile} command 20502changed the address of a pointer in the example program, perhaps to a 20503variable created in the @code{compile} command, that pointer would point 20504to an invalid location when the command exits. The following example 20505would likely cause issues with your debugged program: 20506 20507@smallexample 20508compile code int ff = 5; p = &ff; 20509@end smallexample 20510 20511In this example, @code{p} would point to @code{ff} when the 20512@code{compile} command is executing the source code provided to it. 20513However, as variables in the (example) program persist with their 20514assigned values, the variable @code{p} would point to an invalid 20515location when the command exists. A general rule should be followed 20516in that you should either assign @code{NULL} to any assigned pointers, 20517or restore a valid location to the pointer before the command exits. 20518 20519Similar caution must be exercised with any structs, unions, and typedefs 20520defined in @code{compile} command. Types defined in the @code{compile} 20521command will no longer be available in the next @code{compile} command. 20522Therefore, if you cast a variable to a type defined in the 20523@code{compile} command, care must be taken to ensure that any future 20524need to resolve the type can be achieved. 20525 20526@smallexample 20527(gdb) compile code static struct a @{ int a; @} v = @{ 42 @}; argv = &v; 20528(gdb) compile code printf ("%d\n", ((struct a *) argv)->a); 20529gdb command line:1:36: error: dereferencing pointer to incomplete type ‘struct a’ 20530Compilation failed. 20531(gdb) compile code struct a @{ int a; @}; printf ("%d\n", ((struct a *) argv)->a); 2053242 20533@end smallexample 20534 20535Variables that have been optimized away by the compiler are not 20536accessible to the code submitted to the @code{compile} command. 20537Access to those variables will generate a compiler error which @value{GDBN} 20538will print to the console. 20539@end table 20540 20541@subsection Compiler search for the @code{compile} command 20542 20543@value{GDBN} needs to find @value{NGCC} for the inferior being debugged 20544which may not be obvious for remote targets of different architecture 20545than where @value{GDBN} is running. Environment variable @env{PATH} on 20546@value{GDBN} host is searched for @value{NGCC} binary matching the 20547target architecture and operating system. This search can be overriden 20548by @code{set compile-gcc} @value{GDBN} command below. @env{PATH} is 20549taken from shell that executed @value{GDBN}, it is not the value set by 20550@value{GDBN} command @code{set environment}). @xref{Environment}. 20551 20552 20553Specifically @env{PATH} is searched for binaries matching regular expression 20554@code{@var{arch}(-[^-]*)?-@var{os}-gcc} according to the inferior target being 20555debugged. @var{arch} is processor name --- multiarch is supported, so for 20556example both @code{i386} and @code{x86_64} targets look for pattern 20557@code{(x86_64|i.86)} and both @code{s390} and @code{s390x} targets look 20558for pattern @code{s390x?}. @var{os} is currently supported only for 20559pattern @code{linux(-gnu)?}. 20560 20561On Posix hosts the compiler driver @value{GDBN} needs to find also 20562shared library @file{libcc1.so} from the compiler. It is searched in 20563default shared library search path (overridable with usual environment 20564variable @env{LD_LIBRARY_PATH}), unrelated to @env{PATH} or @code{set 20565compile-gcc} settings. Contrary to it @file{libcc1plugin.so} is found 20566according to the installation of the found compiler --- as possibly 20567specified by the @code{set compile-gcc} command. 20568 20569@table @code 20570@item set compile-gcc 20571@cindex compile command driver filename override 20572Set compilation command used for compiling and injecting code with the 20573@code{compile} commands. If this option is not set (it is set to 20574an empty string), the search described above will occur --- that is the 20575default. 20576 20577@item show compile-gcc 20578Displays the current compile command @value{NGCC} driver filename. 20579If set, it is the main command @command{gcc}, found usually for example 20580under name @file{x86_64-linux-gnu-gcc}. 20581@end table 20582 20583@node GDB Files 20584@chapter @value{GDBN} Files 20585 20586@value{GDBN} needs to know the file name of the program to be debugged, 20587both in order to read its symbol table and in order to start your 20588program. To debug a core dump of a previous run, you must also tell 20589@value{GDBN} the name of the core dump file. 20590 20591@menu 20592* Files:: Commands to specify files 20593* File Caching:: Information about @value{GDBN}'s file caching 20594* Separate Debug Files:: Debugging information in separate files 20595* MiniDebugInfo:: Debugging information in a special section 20596* Index Files:: Index files speed up GDB 20597* Symbol Errors:: Errors reading symbol files 20598* Data Files:: GDB data files 20599@end menu 20600 20601@node Files 20602@section Commands to Specify Files 20603 20604@cindex symbol table 20605@cindex core dump file 20606 20607You may want to specify executable and core dump file names. The usual 20608way to do this is at start-up time, using the arguments to 20609@value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and 20610Out of @value{GDBN}}). 20611 20612Occasionally it is necessary to change to a different file during a 20613@value{GDBN} session. Or you may run @value{GDBN} and forget to 20614specify a file you want to use. Or you are debugging a remote target 20615via @code{gdbserver} (@pxref{Server, file, Using the @code{gdbserver} 20616Program}). In these situations the @value{GDBN} commands to specify 20617new files are useful. 20618 20619@table @code 20620@cindex executable file 20621@kindex file 20622@item file @var{filename} 20623Use @var{filename} as the program to be debugged. It is read for its 20624symbols and for the contents of pure memory. It is also the program 20625executed when you use the @code{run} command. If you do not specify a 20626directory and the file is not found in the @value{GDBN} working directory, 20627@value{GDBN} uses the environment variable @env{PATH} as a list of 20628directories to search, just as the shell does when looking for a program 20629to run. You can change the value of this variable, for both @value{GDBN} 20630and your program, using the @code{path} command. 20631 20632@cindex unlinked object files 20633@cindex patching object files 20634You can load unlinked object @file{.o} files into @value{GDBN} using 20635the @code{file} command. You will not be able to ``run'' an object 20636file, but you can disassemble functions and inspect variables. Also, 20637if the underlying BFD functionality supports it, you could use 20638@kbd{gdb -write} to patch object files using this technique. Note 20639that @value{GDBN} can neither interpret nor modify relocations in this 20640case, so branches and some initialized variables will appear to go to 20641the wrong place. But this feature is still handy from time to time. 20642 20643@item file 20644@code{file} with no argument makes @value{GDBN} discard any information it 20645has on both executable file and the symbol table. 20646 20647@kindex exec-file 20648@item exec-file @r{[} @var{filename} @r{]} 20649Specify that the program to be run (but not the symbol table) is found 20650in @var{filename}. @value{GDBN} searches the environment variable @env{PATH} 20651if necessary to locate your program. Omitting @var{filename} means to 20652discard information on the executable file. 20653 20654@kindex symbol-file 20655@item symbol-file @r{[} @var{filename} @r{[} -o @var{offset} @r{]]} 20656Read symbol table information from file @var{filename}. @env{PATH} is 20657searched when necessary. Use the @code{file} command to get both symbol 20658table and program to run from the same file. 20659 20660If an optional @var{offset} is specified, it is added to the start 20661address of each section in the symbol file. This is useful if the 20662program is relocated at runtime, such as the Linux kernel with kASLR 20663enabled. 20664 20665@code{symbol-file} with no argument clears out @value{GDBN} information on your 20666program's symbol table. 20667 20668The @code{symbol-file} command causes @value{GDBN} to forget the contents of 20669some breakpoints and auto-display expressions. This is because they may 20670contain pointers to the internal data recording symbols and data types, 20671which are part of the old symbol table data being discarded inside 20672@value{GDBN}. 20673 20674@code{symbol-file} does not repeat if you press @key{RET} again after 20675executing it once. 20676 20677When @value{GDBN} is configured for a particular environment, it 20678understands debugging information in whatever format is the standard 20679generated for that environment; you may use either a @sc{gnu} compiler, or 20680other compilers that adhere to the local conventions. 20681Best results are usually obtained from @sc{gnu} compilers; for example, 20682using @code{@value{NGCC}} you can generate debugging information for 20683optimized code. 20684 20685For most kinds of object files, with the exception of old SVR3 systems 20686using COFF, the @code{symbol-file} command does not normally read the 20687symbol table in full right away. Instead, it scans the symbol table 20688quickly to find which source files and which symbols are present. The 20689details are read later, one source file at a time, as they are needed. 20690 20691The purpose of this two-stage reading strategy is to make @value{GDBN} 20692start up faster. For the most part, it is invisible except for 20693occasional pauses while the symbol table details for a particular source 20694file are being read. (The @code{set verbose} command can turn these 20695pauses into messages if desired. @xref{Messages/Warnings, ,Optional 20696Warnings and Messages}.) 20697 20698We have not implemented the two-stage strategy for COFF yet. When the 20699symbol table is stored in COFF format, @code{symbol-file} reads the 20700symbol table data in full right away. Note that ``stabs-in-COFF'' 20701still does the two-stage strategy, since the debug info is actually 20702in stabs format. 20703 20704@kindex readnow 20705@cindex reading symbols immediately 20706@cindex symbols, reading immediately 20707@item symbol-file @r{[} -readnow @r{]} @var{filename} 20708@itemx file @r{[} -readnow @r{]} @var{filename} 20709You can override the @value{GDBN} two-stage strategy for reading symbol 20710tables by using the @samp{-readnow} option with any of the commands that 20711load symbol table information, if you want to be sure @value{GDBN} has the 20712entire symbol table available. 20713 20714@cindex @code{-readnever}, option for symbol-file command 20715@cindex never read symbols 20716@cindex symbols, never read 20717@item symbol-file @r{[} -readnever @r{]} @var{filename} 20718@itemx file @r{[} -readnever @r{]} @var{filename} 20719You can instruct @value{GDBN} to never read the symbolic information 20720contained in @var{filename} by using the @samp{-readnever} option. 20721@xref{--readnever}. 20722 20723@c FIXME: for now no mention of directories, since this seems to be in 20724@c flux. 13mar1992 status is that in theory GDB would look either in 20725@c current dir or in same dir as myprog; but issues like competing 20726@c GDB's, or clutter in system dirs, mean that in practice right now 20727@c only current dir is used. FFish says maybe a special GDB hierarchy 20728@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol 20729@c files. 20730 20731@kindex core-file 20732@item core-file @r{[}@var{filename}@r{]} 20733@itemx core 20734Specify the whereabouts of a core dump file to be used as the ``contents 20735of memory''. Traditionally, core files contain only some parts of the 20736address space of the process that generated them; @value{GDBN} can access the 20737executable file itself for other parts. 20738 20739@code{core-file} with no argument specifies that no core file is 20740to be used. 20741 20742Note that the core file is ignored when your program is actually running 20743under @value{GDBN}. So, if you have been running your program and you 20744wish to debug a core file instead, you must kill the subprocess in which 20745the program is running. To do this, use the @code{kill} command 20746(@pxref{Kill Process, ,Killing the Child Process}). 20747 20748@kindex add-symbol-file 20749@cindex dynamic linking 20750@item add-symbol-file @var{filename} @r{[} -readnow @r{|} -readnever @r{]} @r{[} -o @var{offset} @r{]} @r{[} @var{textaddress} @r{]} @r{[} -s @var{section} @var{address} @dots{} @r{]} 20751The @code{add-symbol-file} command reads additional symbol table 20752information from the file @var{filename}. You would use this command 20753when @var{filename} has been dynamically loaded (by some other means) 20754into the program that is running. The @var{textaddress} parameter gives 20755the memory address at which the file's text section has been loaded. 20756You can additionally specify the base address of other sections using 20757an arbitrary number of @samp{-s @var{section} @var{address}} pairs. 20758If a section is omitted, @value{GDBN} will use its default addresses 20759as found in @var{filename}. Any @var{address} or @var{textaddress} 20760can be given as an expression. 20761 20762If an optional @var{offset} is specified, it is added to the start 20763address of each section, except those for which the address was 20764specified explicitly. 20765 20766The symbol table of the file @var{filename} is added to the symbol table 20767originally read with the @code{symbol-file} command. You can use the 20768@code{add-symbol-file} command any number of times; the new symbol data 20769thus read is kept in addition to the old. 20770 20771Changes can be reverted using the command @code{remove-symbol-file}. 20772 20773@cindex relocatable object files, reading symbols from 20774@cindex object files, relocatable, reading symbols from 20775@cindex reading symbols from relocatable object files 20776@cindex symbols, reading from relocatable object files 20777@cindex @file{.o} files, reading symbols from 20778Although @var{filename} is typically a shared library file, an 20779executable file, or some other object file which has been fully 20780relocated for loading into a process, you can also load symbolic 20781information from relocatable @file{.o} files, as long as: 20782 20783@itemize @bullet 20784@item 20785the file's symbolic information refers only to linker symbols defined in 20786that file, not to symbols defined by other object files, 20787@item 20788every section the file's symbolic information refers to has actually 20789been loaded into the inferior, as it appears in the file, and 20790@item 20791you can determine the address at which every section was loaded, and 20792provide these to the @code{add-symbol-file} command. 20793@end itemize 20794 20795@noindent 20796Some embedded operating systems, like Sun Chorus and VxWorks, can load 20797relocatable files into an already running program; such systems 20798typically make the requirements above easy to meet. However, it's 20799important to recognize that many native systems use complex link 20800procedures (@code{.linkonce} section factoring and C@t{++} constructor table 20801assembly, for example) that make the requirements difficult to meet. In 20802general, one cannot assume that using @code{add-symbol-file} to read a 20803relocatable object file's symbolic information will have the same effect 20804as linking the relocatable object file into the program in the normal 20805way. 20806 20807@code{add-symbol-file} does not repeat if you press @key{RET} after using it. 20808 20809@kindex remove-symbol-file 20810@item remove-symbol-file @var{filename} 20811@item remove-symbol-file -a @var{address} 20812Remove a symbol file added via the @code{add-symbol-file} command. The 20813file to remove can be identified by its @var{filename} or by an @var{address} 20814that lies within the boundaries of this symbol file in memory. Example: 20815 20816@smallexample 20817(gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480 20818add symbol table from file "/home/user/gdb/mylib.so" at 20819 .text_addr = 0x7ffff7ff9480 20820(y or n) y 20821Reading symbols from /home/user/gdb/mylib.so... 20822(gdb) remove-symbol-file -a 0x7ffff7ff9480 20823Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y 20824(gdb) 20825@end smallexample 20826 20827 20828@code{remove-symbol-file} does not repeat if you press @key{RET} after using it. 20829 20830@kindex add-symbol-file-from-memory 20831@cindex @code{syscall DSO} 20832@cindex load symbols from memory 20833@item add-symbol-file-from-memory @var{address} 20834Load symbols from the given @var{address} in a dynamically loaded 20835object file whose image is mapped directly into the inferior's memory. 20836For example, the Linux kernel maps a @code{syscall DSO} into each 20837process's address space; this DSO provides kernel-specific code for 20838some system calls. The argument can be any expression whose 20839evaluation yields the address of the file's shared object file header. 20840For this command to work, you must have used @code{symbol-file} or 20841@code{exec-file} commands in advance. 20842 20843@kindex section 20844@item section @var{section} @var{addr} 20845The @code{section} command changes the base address of the named 20846@var{section} of the exec file to @var{addr}. This can be used if the 20847exec file does not contain section addresses, (such as in the 20848@code{a.out} format), or when the addresses specified in the file 20849itself are wrong. Each section must be changed separately. The 20850@code{info files} command, described below, lists all the sections and 20851their addresses. 20852 20853@kindex info files 20854@kindex info target 20855@item info files 20856@itemx info target 20857@code{info files} and @code{info target} are synonymous; both print the 20858current target (@pxref{Targets, ,Specifying a Debugging Target}), 20859including the names of the executable and core dump files currently in 20860use by @value{GDBN}, and the files from which symbols were loaded. The 20861command @code{help target} lists all possible targets rather than 20862current ones. 20863 20864@kindex maint info sections 20865@item maint info sections @r{[}-all-objects@r{]} @r{[}@var{filter-list}@r{]} 20866Another command that can give you extra information about program sections 20867is @code{maint info sections}. In addition to the section information 20868displayed by @code{info files}, this command displays the flags and file 20869offset of each section in the executable and core dump files. 20870 20871When @samp{-all-objects} is passed then sections from all loaded object 20872files, including shared libraries, are printed. 20873 20874The optional @var{filter-list} is a space separated list of filter 20875keywords. Sections that match any one of the filter criteria will be 20876printed. There are two types of filter: 20877 20878@table @code 20879@item @var{section-name} 20880Display information about any section named @var{section-name}. 20881@item @var{section-flag} 20882Display information for any section with @var{section-flag}. The 20883section flags that @value{GDBN} currently knows about are: 20884@table @code 20885@item ALLOC 20886Section will have space allocated in the process when loaded. 20887Set for all sections except those containing debug information. 20888@item LOAD 20889Section will be loaded from the file into the child process memory. 20890Set for pre-initialized code and data, clear for @code{.bss} sections. 20891@item RELOC 20892Section needs to be relocated before loading. 20893@item READONLY 20894Section cannot be modified by the child process. 20895@item CODE 20896Section contains executable code only. 20897@item DATA 20898Section contains data only (no executable code). 20899@item ROM 20900Section will reside in ROM. 20901@item CONSTRUCTOR 20902Section contains data for constructor/destructor lists. 20903@item HAS_CONTENTS 20904Section is not empty. 20905@item NEVER_LOAD 20906An instruction to the linker to not output the section. 20907@item COFF_SHARED_LIBRARY 20908A notification to the linker that the section contains 20909COFF shared library information. 20910@item IS_COMMON 20911Section contains common symbols. 20912@end table 20913@end table 20914 20915@kindex maint info target-sections 20916@item maint info target-sections 20917This command prints @value{GDBN}'s internal section table. For each 20918target @value{GDBN} maintains a table containing the allocatable 20919sections from all currently mapped objects, along with information 20920about where the section is mapped. 20921 20922@kindex set trust-readonly-sections 20923@cindex read-only sections 20924@item set trust-readonly-sections on 20925Tell @value{GDBN} that readonly sections in your object file 20926really are read-only (i.e.@: that their contents will not change). 20927In that case, @value{GDBN} can fetch values from these sections 20928out of the object file, rather than from the target program. 20929For some targets (notably embedded ones), this can be a significant 20930enhancement to debugging performance. 20931 20932The default is off. 20933 20934@item set trust-readonly-sections off 20935Tell @value{GDBN} not to trust readonly sections. This means that 20936the contents of the section might change while the program is running, 20937and must therefore be fetched from the target when needed. 20938 20939@item show trust-readonly-sections 20940Show the current setting of trusting readonly sections. 20941@end table 20942 20943All file-specifying commands allow both absolute and relative file names 20944as arguments. @value{GDBN} always converts the file name to an absolute file 20945name and remembers it that way. 20946 20947@cindex shared libraries 20948@anchor{Shared Libraries} 20949@value{GDBN} supports @sc{gnu}/Linux, MS-Windows, SunOS, 20950Darwin/Mach-O, SVr4, IBM RS/6000 AIX, QNX Neutrino, FDPIC (FR-V), and 20951DSBT (TIC6X) shared libraries. 20952 20953On MS-Windows @value{GDBN} must be linked with the Expat library to support 20954shared libraries. @xref{Expat}. 20955 20956@value{GDBN} automatically loads symbol definitions from shared libraries 20957when you use the @code{run} command, or when you examine a core file. 20958(Before you issue the @code{run} command, @value{GDBN} does not understand 20959references to a function in a shared library, however---unless you are 20960debugging a core file). 20961 20962@c FIXME: some @value{GDBN} release may permit some refs to undef 20963@c FIXME...symbols---eg in a break cmd---assuming they are from a shared 20964@c FIXME...lib; check this from time to time when updating manual 20965 20966There are times, however, when you may wish to not automatically load 20967symbol definitions from shared libraries, such as when they are 20968particularly large or there are many of them. 20969 20970To control the automatic loading of shared library symbols, use the 20971commands: 20972 20973@table @code 20974@kindex set auto-solib-add 20975@item set auto-solib-add @var{mode} 20976If @var{mode} is @code{on}, symbols from all shared object libraries 20977will be loaded automatically when the inferior begins execution, you 20978attach to an independently started inferior, or when the dynamic linker 20979informs @value{GDBN} that a new library has been loaded. If @var{mode} 20980is @code{off}, symbols must be loaded manually, using the 20981@code{sharedlibrary} command. The default value is @code{on}. 20982 20983@cindex memory used for symbol tables 20984If your program uses lots of shared libraries with debug info that 20985takes large amounts of memory, you can decrease the @value{GDBN} 20986memory footprint by preventing it from automatically loading the 20987symbols from shared libraries. To that end, type @kbd{set 20988auto-solib-add off} before running the inferior, then load each 20989library whose debug symbols you do need with @kbd{sharedlibrary 20990@var{regexp}}, where @var{regexp} is a regular expression that matches 20991the libraries whose symbols you want to be loaded. 20992 20993@kindex show auto-solib-add 20994@item show auto-solib-add 20995Display the current autoloading mode. 20996@end table 20997 20998@cindex load shared library 20999To explicitly load shared library symbols, use the @code{sharedlibrary} 21000command: 21001 21002@table @code 21003@kindex info sharedlibrary 21004@kindex info share 21005@item info share @var{regex} 21006@itemx info sharedlibrary @var{regex} 21007Print the names of the shared libraries which are currently loaded 21008that match @var{regex}. If @var{regex} is omitted then print 21009all shared libraries that are loaded. 21010 21011@kindex info dll 21012@item info dll @var{regex} 21013This is an alias of @code{info sharedlibrary}. 21014 21015@kindex sharedlibrary 21016@kindex share 21017@item sharedlibrary @var{regex} 21018@itemx share @var{regex} 21019Load shared object library symbols for files matching a 21020Unix regular expression. 21021As with files loaded automatically, it only loads shared libraries 21022required by your program for a core file or after typing @code{run}. If 21023@var{regex} is omitted all shared libraries required by your program are 21024loaded. 21025 21026@item nosharedlibrary 21027@kindex nosharedlibrary 21028@cindex unload symbols from shared libraries 21029Unload all shared object library symbols. This discards all symbols 21030that have been loaded from all shared libraries. Symbols from shared 21031libraries that were loaded by explicit user requests are not 21032discarded. 21033@end table 21034 21035Sometimes you may wish that @value{GDBN} stops and gives you control 21036when any of shared library events happen. The best way to do this is 21037to use @code{catch load} and @code{catch unload} (@pxref{Set 21038Catchpoints}). 21039 21040@value{GDBN} also supports the @code{set stop-on-solib-events} 21041command for this. This command exists for historical reasons. It is 21042less useful than setting a catchpoint, because it does not allow for 21043conditions or commands as a catchpoint does. 21044 21045@table @code 21046@item set stop-on-solib-events 21047@kindex set stop-on-solib-events 21048This command controls whether @value{GDBN} should give you control 21049when the dynamic linker notifies it about some shared library event. 21050The most common event of interest is loading or unloading of a new 21051shared library. 21052 21053@item show stop-on-solib-events 21054@kindex show stop-on-solib-events 21055Show whether @value{GDBN} stops and gives you control when shared 21056library events happen. 21057@end table 21058 21059Shared libraries are also supported in many cross or remote debugging 21060configurations. @value{GDBN} needs to have access to the target's libraries; 21061this can be accomplished either by providing copies of the libraries 21062on the host system, or by asking @value{GDBN} to automatically retrieve the 21063libraries from the target. If copies of the target libraries are 21064provided, they need to be the same as the target libraries, although the 21065copies on the target can be stripped as long as the copies on the host are 21066not. 21067 21068@cindex where to look for shared libraries 21069For remote debugging, you need to tell @value{GDBN} where the target 21070libraries are, so that it can load the correct copies---otherwise, it 21071may try to load the host's libraries. @value{GDBN} has two variables 21072to specify the search directories for target libraries. 21073 21074@table @code 21075@cindex prefix for executable and shared library file names 21076@cindex system root, alternate 21077@kindex set solib-absolute-prefix 21078@kindex set sysroot 21079@item set sysroot @var{path} 21080Use @var{path} as the system root for the program being debugged. Any 21081absolute shared library paths will be prefixed with @var{path}; many 21082runtime loaders store the absolute paths to the shared library in the 21083target program's memory. When starting processes remotely, and when 21084attaching to already-running processes (local or remote), their 21085executable filenames will be prefixed with @var{path} if reported to 21086@value{GDBN} as absolute by the operating system. If you use 21087@code{set sysroot} to find executables and shared libraries, they need 21088to be laid out in the same way that they are on the target, with 21089e.g.@: a @file{/bin}, @file{/lib} and @file{/usr/lib} hierarchy under 21090@var{path}. 21091 21092If @var{path} starts with the sequence @file{target:} and the target 21093system is remote then @value{GDBN} will retrieve the target binaries 21094from the remote system. This is only supported when using a remote 21095target that supports the @code{remote get} command (@pxref{File 21096Transfer,,Sending files to a remote system}). The part of @var{path} 21097following the initial @file{target:} (if present) is used as system 21098root prefix on the remote file system. If @var{path} starts with the 21099sequence @file{remote:} this is converted to the sequence 21100@file{target:} by @code{set sysroot}@footnote{Historically the 21101functionality to retrieve binaries from the remote system was 21102provided by prefixing @var{path} with @file{remote:}}. If you want 21103to specify a local system root using a directory that happens to be 21104named @file{target:} or @file{remote:}, you need to use some 21105equivalent variant of the name like @file{./target:}. 21106 21107For targets with an MS-DOS based filesystem, such as MS-Windows, 21108@value{GDBN} tries prefixing a few variants of the target 21109absolute file name with @var{path}. But first, on Unix hosts, 21110@value{GDBN} converts all backslash directory separators into forward 21111slashes, because the backslash is not a directory separator on Unix: 21112 21113@smallexample 21114 c:\foo\bar.dll @result{} c:/foo/bar.dll 21115@end smallexample 21116 21117Then, @value{GDBN} attempts prefixing the target file name with 21118@var{path}, and looks for the resulting file name in the host file 21119system: 21120 21121@smallexample 21122 c:/foo/bar.dll @result{} /path/to/sysroot/c:/foo/bar.dll 21123@end smallexample 21124 21125If that does not find the binary, @value{GDBN} tries removing 21126the @samp{:} character from the drive spec, both for convenience, and, 21127for the case of the host file system not supporting file names with 21128colons: 21129 21130@smallexample 21131 c:/foo/bar.dll @result{} /path/to/sysroot/c/foo/bar.dll 21132@end smallexample 21133 21134This makes it possible to have a system root that mirrors a target 21135with more than one drive. E.g., you may want to setup your local 21136copies of the target system shared libraries like so (note @samp{c} vs 21137@samp{z}): 21138 21139@smallexample 21140 @file{/path/to/sysroot/c/sys/bin/foo.dll} 21141 @file{/path/to/sysroot/c/sys/bin/bar.dll} 21142 @file{/path/to/sysroot/z/sys/bin/bar.dll} 21143@end smallexample 21144 21145@noindent 21146and point the system root at @file{/path/to/sysroot}, so that 21147@value{GDBN} can find the correct copies of both 21148@file{c:\sys\bin\foo.dll}, and @file{z:\sys\bin\bar.dll}. 21149 21150If that still does not find the binary, @value{GDBN} tries 21151removing the whole drive spec from the target file name: 21152 21153@smallexample 21154 c:/foo/bar.dll @result{} /path/to/sysroot/foo/bar.dll 21155@end smallexample 21156 21157This last lookup makes it possible to not care about the drive name, 21158if you don't want or need to. 21159 21160The @code{set solib-absolute-prefix} command is an alias for @code{set 21161sysroot}. 21162 21163@cindex default system root 21164@cindex @samp{--with-sysroot} 21165You can set the default system root by using the configure-time 21166@samp{--with-sysroot} option. If the system root is inside 21167@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or 21168@samp{--exec-prefix}), then the default system root will be updated 21169automatically if the installed @value{GDBN} is moved to a new 21170location. 21171 21172@kindex show sysroot 21173@item show sysroot 21174Display the current executable and shared library prefix. 21175 21176@kindex set solib-search-path 21177@item set solib-search-path @var{path} 21178If this variable is set, @var{path} is a colon-separated list of 21179directories to search for shared libraries. @samp{solib-search-path} 21180is used after @samp{sysroot} fails to locate the library, or if the 21181path to the library is relative instead of absolute. If you want to 21182use @samp{solib-search-path} instead of @samp{sysroot}, be sure to set 21183@samp{sysroot} to a nonexistent directory to prevent @value{GDBN} from 21184finding your host's libraries. @samp{sysroot} is preferred; setting 21185it to a nonexistent directory may interfere with automatic loading 21186of shared library symbols. 21187 21188@kindex show solib-search-path 21189@item show solib-search-path 21190Display the current shared library search path. 21191 21192@cindex DOS file-name semantics of file names. 21193@kindex set target-file-system-kind (unix|dos-based|auto) 21194@kindex show target-file-system-kind 21195@item set target-file-system-kind @var{kind} 21196Set assumed file system kind for target reported file names. 21197 21198Shared library file names as reported by the target system may not 21199make sense as is on the system @value{GDBN} is running on. For 21200example, when remote debugging a target that has MS-DOS based file 21201system semantics, from a Unix host, the target may be reporting to 21202@value{GDBN} a list of loaded shared libraries with file names such as 21203@file{c:\Windows\kernel32.dll}. On Unix hosts, there's no concept of 21204drive letters, so the @samp{c:\} prefix is not normally understood as 21205indicating an absolute file name, and neither is the backslash 21206normally considered a directory separator character. In that case, 21207the native file system would interpret this whole absolute file name 21208as a relative file name with no directory components. This would make 21209it impossible to point @value{GDBN} at a copy of the remote target's 21210shared libraries on the host using @code{set sysroot}, and impractical 21211with @code{set solib-search-path}. Setting 21212@code{target-file-system-kind} to @code{dos-based} tells @value{GDBN} 21213to interpret such file names similarly to how the target would, and to 21214map them to file names valid on @value{GDBN}'s native file system 21215semantics. The value of @var{kind} can be @code{"auto"}, in addition 21216to one of the supported file system kinds. In that case, @value{GDBN} 21217tries to determine the appropriate file system variant based on the 21218current target's operating system (@pxref{ABI, ,Configuring the 21219Current ABI}). The supported file system settings are: 21220 21221@table @code 21222@item unix 21223Instruct @value{GDBN} to assume the target file system is of Unix 21224kind. Only file names starting the forward slash (@samp{/}) character 21225are considered absolute, and the directory separator character is also 21226the forward slash. 21227 21228@item dos-based 21229Instruct @value{GDBN} to assume the target file system is DOS based. 21230File names starting with either a forward slash, or a drive letter 21231followed by a colon (e.g., @samp{c:}), are considered absolute, and 21232both the slash (@samp{/}) and the backslash (@samp{\\}) characters are 21233considered directory separators. 21234 21235@item auto 21236Instruct @value{GDBN} to use the file system kind associated with the 21237target operating system (@pxref{ABI, ,Configuring the Current ABI}). 21238This is the default. 21239@end table 21240@end table 21241 21242@cindex file name canonicalization 21243@cindex base name differences 21244When processing file names provided by the user, @value{GDBN} 21245frequently needs to compare them to the file names recorded in the 21246program's debug info. Normally, @value{GDBN} compares just the 21247@dfn{base names} of the files as strings, which is reasonably fast 21248even for very large programs. (The base name of a file is the last 21249portion of its name, after stripping all the leading directories.) 21250This shortcut in comparison is based upon the assumption that files 21251cannot have more than one base name. This is usually true, but 21252references to files that use symlinks or similar filesystem 21253facilities violate that assumption. If your program records files 21254using such facilities, or if you provide file names to @value{GDBN} 21255using symlinks etc., you can set @code{basenames-may-differ} to 21256@code{true} to instruct @value{GDBN} to completely canonicalize each 21257pair of file names it needs to compare. This will make file-name 21258comparisons accurate, but at a price of a significant slowdown. 21259 21260@table @code 21261@item set basenames-may-differ 21262@kindex set basenames-may-differ 21263Set whether a source file may have multiple base names. 21264 21265@item show basenames-may-differ 21266@kindex show basenames-may-differ 21267Show whether a source file may have multiple base names. 21268@end table 21269 21270@node File Caching 21271@section File Caching 21272@cindex caching of opened files 21273@cindex caching of bfd objects 21274 21275To speed up file loading, and reduce memory usage, @value{GDBN} will 21276reuse the @code{bfd} objects used to track open files. @xref{Top, , 21277BFD, bfd, The Binary File Descriptor Library}. The following commands 21278allow visibility and control of the caching behavior. 21279 21280@table @code 21281@kindex maint info bfds 21282@item maint info bfds 21283This prints information about each @code{bfd} object that is known to 21284@value{GDBN}. 21285 21286@kindex maint set bfd-sharing 21287@kindex maint show bfd-sharing 21288@kindex bfd caching 21289@item maint set bfd-sharing 21290@item maint show bfd-sharing 21291Control whether @code{bfd} objects can be shared. When sharing is 21292enabled @value{GDBN} reuses already open @code{bfd} objects rather 21293than reopening the same file. Turning sharing off does not cause 21294already shared @code{bfd} objects to be unshared, but all future files 21295that are opened will create a new @code{bfd} object. Similarly, 21296re-enabling sharing does not cause multiple existing @code{bfd} 21297objects to be collapsed into a single shared @code{bfd} object. 21298 21299@kindex set debug bfd-cache @var{level} 21300@kindex bfd caching 21301@item set debug bfd-cache @var{level} 21302Turns on debugging of the bfd cache, setting the level to @var{level}. 21303 21304@kindex show debug bfd-cache 21305@kindex bfd caching 21306@item show debug bfd-cache 21307Show the current debugging level of the bfd cache. 21308@end table 21309 21310@node Separate Debug Files 21311@section Debugging Information in Separate Files 21312@cindex separate debugging information files 21313@cindex debugging information in separate files 21314@cindex @file{.debug} subdirectories 21315@cindex debugging information directory, global 21316@cindex global debugging information directories 21317@cindex build ID, and separate debugging files 21318@cindex @file{.build-id} directory 21319 21320@value{GDBN} allows you to put a program's debugging information in a 21321file separate from the executable itself, in a way that allows 21322@value{GDBN} to find and load the debugging information automatically. 21323Since debugging information can be very large---sometimes larger 21324than the executable code itself---some systems distribute debugging 21325information for their executables in separate files, which users can 21326install only when they need to debug a problem. 21327 21328@value{GDBN} supports two ways of specifying the separate debug info 21329file: 21330 21331@itemize @bullet 21332@item 21333The executable contains a @dfn{debug link} that specifies the name of 21334the separate debug info file. The separate debug file's name is 21335usually @file{@var{executable}.debug}, where @var{executable} is the 21336name of the corresponding executable file without leading directories 21337(e.g., @file{ls.debug} for @file{/usr/bin/ls}). In addition, the 21338debug link specifies a 32-bit @dfn{Cyclic Redundancy Check} (CRC) 21339checksum for the debug file, which @value{GDBN} uses to validate that 21340the executable and the debug file came from the same build. 21341 21342@item 21343@anchor{build ID} 21344The executable contains a @dfn{build ID}, a unique bit string that is 21345also present in the corresponding debug info file. (This is supported 21346only on some operating systems, when using the ELF or PE file formats 21347for binary files and the @sc{gnu} Binutils.) For more details about 21348this feature, see the description of the @option{--build-id} 21349command-line option in @ref{Options, , Command Line Options, ld, 21350The GNU Linker}. The debug info file's name is not specified 21351explicitly by the build ID, but can be computed from the build ID, see 21352below. 21353@end itemize 21354 21355Depending on the way the debug info file is specified, @value{GDBN} 21356uses two different methods of looking for the debug file: 21357 21358@itemize @bullet 21359@item 21360For the ``debug link'' method, @value{GDBN} looks up the named file in 21361the directory of the executable file, then in a subdirectory of that 21362directory named @file{.debug}, and finally under each one of the 21363global debug directories, in a subdirectory whose name is identical to 21364the leading directories of the executable's absolute file name. (On 21365MS-Windows/MS-DOS, the drive letter of the executable's leading 21366directories is converted to a one-letter subdirectory, i.e.@: 21367@file{d:/usr/bin/} is converted to @file{/d/usr/bin/}, because Windows 21368filesystems disallow colons in file names.) 21369 21370@item 21371For the ``build ID'' method, @value{GDBN} looks in the 21372@file{.build-id} subdirectory of each one of the global debug directories for 21373a file named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the 21374first 2 hex characters of the build ID bit string, and @var{nnnnnnnn} 21375are the rest of the bit string. (Real build ID strings are 32 or more 21376hex characters, not 10.) 21377@end itemize 21378 21379So, for example, suppose you ask @value{GDBN} to debug 21380@file{/usr/bin/ls}, which has a debug link that specifies the 21381file @file{ls.debug}, and a build ID whose value in hex is 21382@code{abcdef1234}. If the list of the global debug directories includes 21383@file{/usr/lib/debug}, then @value{GDBN} will look for the following 21384debug information files, in the indicated order: 21385 21386@itemize @minus 21387@item 21388@file{/usr/lib/debug/.build-id/ab/cdef1234.debug} 21389@item 21390@file{/usr/bin/ls.debug} 21391@item 21392@file{/usr/bin/.debug/ls.debug} 21393@item 21394@file{/usr/lib/debug/usr/bin/ls.debug}. 21395@end itemize 21396 21397@anchor{debug-file-directory} 21398Global debugging info directories default to what is set by @value{GDBN} 21399configure option @option{--with-separate-debug-dir}. During @value{GDBN} run 21400you can also set the global debugging info directories, and view the list 21401@value{GDBN} is currently using. 21402 21403@table @code 21404 21405@kindex set debug-file-directory 21406@item set debug-file-directory @var{directories} 21407Set the directories which @value{GDBN} searches for separate debugging 21408information files to @var{directory}. Multiple path components can be set 21409concatenating them by a path separator. 21410 21411@kindex show debug-file-directory 21412@item show debug-file-directory 21413Show the directories @value{GDBN} searches for separate debugging 21414information files. 21415 21416@end table 21417 21418@cindex @code{.gnu_debuglink} sections 21419@cindex debug link sections 21420A debug link is a special section of the executable file named 21421@code{.gnu_debuglink}. The section must contain: 21422 21423@itemize 21424@item 21425A filename, with any leading directory components removed, followed by 21426a zero byte, 21427@item 21428zero to three bytes of padding, as needed to reach the next four-byte 21429boundary within the section, and 21430@item 21431a four-byte CRC checksum, stored in the same endianness used for the 21432executable file itself. The checksum is computed on the debugging 21433information file's full contents by the function given below, passing 21434zero as the @var{crc} argument. 21435@end itemize 21436 21437Any executable file format can carry a debug link, as long as it can 21438contain a section named @code{.gnu_debuglink} with the contents 21439described above. 21440 21441@cindex @code{.note.gnu.build-id} sections 21442@cindex build ID sections 21443The build ID is a special section in the executable file (and in other 21444ELF binary files that @value{GDBN} may consider). This section is 21445often named @code{.note.gnu.build-id}, but that name is not mandatory. 21446It contains unique identification for the built files---the ID remains 21447the same across multiple builds of the same build tree. The default 21448algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the 21449content for the build ID string. The same section with an identical 21450value is present in the original built binary with symbols, in its 21451stripped variant, and in the separate debugging information file. 21452 21453The debugging information file itself should be an ordinary 21454executable, containing a full set of linker symbols, sections, and 21455debugging information. The sections of the debugging information file 21456should have the same names, addresses, and sizes as the original file, 21457but they need not contain any data---much like a @code{.bss} section 21458in an ordinary executable. 21459 21460The @sc{gnu} binary utilities (Binutils) package includes the 21461@samp{objcopy} utility that can produce 21462the separated executable / debugging information file pairs using the 21463following commands: 21464 21465@smallexample 21466@kbd{objcopy --only-keep-debug foo foo.debug} 21467@kbd{strip -g foo} 21468@end smallexample 21469 21470@noindent 21471These commands remove the debugging 21472information from the executable file @file{foo} and place it in the file 21473@file{foo.debug}. You can use the first, second or both methods to link the 21474two files: 21475 21476@itemize @bullet 21477@item 21478The debug link method needs the following additional command to also leave 21479behind a debug link in @file{foo}: 21480 21481@smallexample 21482@kbd{objcopy --add-gnu-debuglink=foo.debug foo} 21483@end smallexample 21484 21485Ulrich Drepper's @file{elfutils} package, starting with version 0.53, contains 21486a version of the @code{strip} command such that the command @kbd{strip foo -f 21487foo.debug} has the same functionality as the two @code{objcopy} commands and 21488the @code{ln -s} command above, together. 21489 21490@item 21491Build ID gets embedded into the main executable using @code{ld --build-id} or 21492the @value{NGCC} counterpart @code{gcc -Wl,--build-id}. Build ID support plus 21493compatibility fixes for debug files separation are present in @sc{gnu} binary 21494utilities (Binutils) package since version 2.18. 21495@end itemize 21496 21497@noindent 21498 21499@cindex CRC algorithm definition 21500The CRC used in @code{.gnu_debuglink} is the CRC-32 defined in 21501IEEE 802.3 using the polynomial: 21502 21503@c TexInfo requires naked braces for multi-digit exponents for Tex 21504@c output, but this causes HTML output to barf. HTML has to be set using 21505@c raw commands. So we end up having to specify this equation in 2 21506@c different ways! 21507@ifhtml 21508@display 21509@html 21510 <em>x</em><sup>32</sup> + <em>x</em><sup>26</sup> + <em>x</em><sup>23</sup> + <em>x</em><sup>22</sup> + <em>x</em><sup>16</sup> + <em>x</em><sup>12</sup> + <em>x</em><sup>11</sup> 21511 + <em>x</em><sup>10</sup> + <em>x</em><sup>8</sup> + <em>x</em><sup>7</sup> + <em>x</em><sup>5</sup> + <em>x</em><sup>4</sup> + <em>x</em><sup>2</sup> + <em>x</em> + 1 21512@end html 21513@end display 21514@end ifhtml 21515@ifnothtml 21516@display 21517 @math{x^{32} + x^{26} + x^{23} + x^{22} + x^{16} + x^{12} + x^{11}} 21518 @math{+ x^{10} + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1} 21519@end display 21520@end ifnothtml 21521 21522The function is computed byte at a time, taking the least 21523significant bit of each byte first. The initial pattern 21524@code{0xffffffff} is used, to ensure leading zeros affect the CRC and 21525the final result is inverted to ensure trailing zeros also affect the 21526CRC. 21527 21528@emph{Note:} This is the same CRC polynomial as used in handling the 21529@dfn{Remote Serial Protocol} @code{qCRC} packet (@pxref{qCRC packet}). 21530However in the case of the Remote Serial Protocol, the CRC is computed 21531@emph{most} significant bit first, and the result is not inverted, so 21532trailing zeros have no effect on the CRC value. 21533 21534To complete the description, we show below the code of the function 21535which produces the CRC used in @code{.gnu_debuglink}. Inverting the 21536initially supplied @code{crc} argument means that an initial call to 21537this function passing in zero will start computing the CRC using 21538@code{0xffffffff}. 21539 21540@kindex gnu_debuglink_crc32 21541@smallexample 21542unsigned long 21543gnu_debuglink_crc32 (unsigned long crc, 21544 unsigned char *buf, size_t len) 21545@{ 21546 static const unsigned long crc32_table[256] = 21547 @{ 21548 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, 21549 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, 21550 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, 21551 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, 21552 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, 21553 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, 21554 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, 21555 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, 21556 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, 21557 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, 21558 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, 21559 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, 21560 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, 21561 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, 21562 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, 21563 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, 21564 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, 21565 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, 21566 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, 21567 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, 21568 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, 21569 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, 21570 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, 21571 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, 21572 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, 21573 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, 21574 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, 21575 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, 21576 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, 21577 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, 21578 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, 21579 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, 21580 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, 21581 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, 21582 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, 21583 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, 21584 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, 21585 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, 21586 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, 21587 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, 21588 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, 21589 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, 21590 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, 21591 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, 21592 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, 21593 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, 21594 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, 21595 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, 21596 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, 21597 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, 21598 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, 21599 0x2d02ef8d 21600 @}; 21601 unsigned char *end; 21602 21603 crc = ~crc & 0xffffffff; 21604 for (end = buf + len; buf < end; ++buf) 21605 crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); 21606 return ~crc & 0xffffffff; 21607@} 21608@end smallexample 21609 21610@noindent 21611This computation does not apply to the ``build ID'' method. 21612 21613@node MiniDebugInfo 21614@section Debugging information in a special section 21615@cindex separate debug sections 21616@cindex @samp{.gnu_debugdata} section 21617 21618Some systems ship pre-built executables and libraries that have a 21619special @samp{.gnu_debugdata} section. This feature is called 21620@dfn{MiniDebugInfo}. This section holds an LZMA-compressed object and 21621is used to supply extra symbols for backtraces. 21622 21623The intent of this section is to provide extra minimal debugging 21624information for use in simple backtraces. It is not intended to be a 21625replacement for full separate debugging information (@pxref{Separate 21626Debug Files}). The example below shows the intended use; however, 21627@value{GDBN} does not currently put restrictions on what sort of 21628debugging information might be included in the section. 21629 21630@value{GDBN} has support for this extension. If the section exists, 21631then it is used provided that no other source of debugging information 21632can be found, and that @value{GDBN} was configured with LZMA support. 21633 21634This section can be easily created using @command{objcopy} and other 21635standard utilities: 21636 21637@smallexample 21638# Extract the dynamic symbols from the main binary, there is no need 21639# to also have these in the normal symbol table. 21640nm -D @var{binary} --format=posix --defined-only \ 21641 | awk '@{ print $1 @}' | sort > dynsyms 21642 21643# Extract all the text (i.e. function) symbols from the debuginfo. 21644# (Note that we actually also accept "D" symbols, for the benefit 21645# of platforms like PowerPC64 that use function descriptors.) 21646nm @var{binary} --format=posix --defined-only \ 21647 | awk '@{ if ($2 == "T" || $2 == "t" || $2 == "D") print $1 @}' \ 21648 | sort > funcsyms 21649 21650# Keep all the function symbols not already in the dynamic symbol 21651# table. 21652comm -13 dynsyms funcsyms > keep_symbols 21653 21654# Separate full debug info into debug binary. 21655objcopy --only-keep-debug @var{binary} debug 21656 21657# Copy the full debuginfo, keeping only a minimal set of symbols and 21658# removing some unnecessary sections. 21659objcopy -S --remove-section .gdb_index --remove-section .comment \ 21660 --keep-symbols=keep_symbols debug mini_debuginfo 21661 21662# Drop the full debug info from the original binary. 21663strip --strip-all -R .comment @var{binary} 21664 21665# Inject the compressed data into the .gnu_debugdata section of the 21666# original binary. 21667xz mini_debuginfo 21668objcopy --add-section .gnu_debugdata=mini_debuginfo.xz @var{binary} 21669@end smallexample 21670 21671@node Index Files 21672@section Index Files Speed Up @value{GDBN} 21673@cindex index files 21674@cindex @samp{.gdb_index} section 21675 21676When @value{GDBN} finds a symbol file, it scans the symbols in the 21677file in order to construct an internal symbol table. This lets most 21678@value{GDBN} operations work quickly---at the cost of a delay early 21679on. For large programs, this delay can be quite lengthy, so 21680@value{GDBN} provides a way to build an index, which speeds up 21681startup. 21682 21683For convenience, @value{GDBN} comes with a program, 21684@command{gdb-add-index}, which can be used to add the index to a 21685symbol file. It takes the symbol file as its only argument: 21686 21687@smallexample 21688$ gdb-add-index symfile 21689@end smallexample 21690 21691@xref{gdb-add-index}. 21692 21693It is also possible to do the work manually. Here is what 21694@command{gdb-add-index} does behind the curtains. 21695 21696The index is stored as a section in the symbol file. @value{GDBN} can 21697write the index to a file, then you can put it into the symbol file 21698using @command{objcopy}. 21699 21700To create an index file, use the @code{save gdb-index} command: 21701 21702@table @code 21703@item save gdb-index [-dwarf-5] @var{directory} 21704@kindex save gdb-index 21705Create index files for all symbol files currently known by 21706@value{GDBN}. For each known @var{symbol-file}, this command by 21707default creates it produces a single file 21708@file{@var{symbol-file}.gdb-index}. If you invoke this command with 21709the @option{-dwarf-5} option, it produces 2 files: 21710@file{@var{symbol-file}.debug_names} and 21711@file{@var{symbol-file}.debug_str}. The files are created in the 21712given @var{directory}. 21713@end table 21714 21715Once you have created an index file you can merge it into your symbol 21716file, here named @file{symfile}, using @command{objcopy}: 21717 21718@smallexample 21719$ objcopy --add-section .gdb_index=symfile.gdb-index \ 21720 --set-section-flags .gdb_index=readonly symfile symfile 21721@end smallexample 21722 21723Or for @code{-dwarf-5}: 21724 21725@smallexample 21726$ objcopy --dump-section .debug_str=symfile.debug_str.new symfile 21727$ cat symfile.debug_str >>symfile.debug_str.new 21728$ objcopy --add-section .debug_names=symfile.gdb-index \ 21729 --set-section-flags .debug_names=readonly \ 21730 --update-section .debug_str=symfile.debug_str.new symfile symfile 21731@end smallexample 21732 21733@value{GDBN} will normally ignore older versions of @file{.gdb_index} 21734sections that have been deprecated. Usually they are deprecated because 21735they are missing a new feature or have performance issues. 21736To tell @value{GDBN} to use a deprecated index section anyway 21737specify @code{set use-deprecated-index-sections on}. 21738The default is @code{off}. 21739This can speed up startup, but may result in some functionality being lost. 21740@xref{Index Section Format}. 21741 21742@emph{Warning:} Setting @code{use-deprecated-index-sections} to @code{on} 21743must be done before gdb reads the file. The following will not work: 21744 21745@smallexample 21746$ gdb -ex "set use-deprecated-index-sections on" <program> 21747@end smallexample 21748 21749Instead you must do, for example, 21750 21751@smallexample 21752$ gdb -iex "set use-deprecated-index-sections on" <program> 21753@end smallexample 21754 21755Indices only work when using DWARF debugging information, not stabs. 21756 21757@subsection Automatic symbol index cache 21758 21759@cindex automatic symbol index cache 21760It is possible for @value{GDBN} to automatically save a copy of this index in a 21761cache on disk and retrieve it from there when loading the same binary in the 21762future. This feature can be turned on with @kbd{set index-cache on}. The 21763following commands can be used to tweak the behavior of the index cache. 21764 21765@table @code 21766 21767@kindex set index-cache 21768@item set index-cache on 21769@itemx set index-cache off 21770Enable or disable the use of the symbol index cache. 21771 21772@item set index-cache directory @var{directory} 21773@kindex show index-cache 21774@itemx show index-cache directory 21775Set/show the directory where index files will be saved. 21776 21777The default value for this directory depends on the host platform. On 21778most systems, the index is cached in the @file{gdb} subdirectory of 21779the directory pointed to by the @env{XDG_CACHE_HOME} environment 21780variable, if it is defined, else in the @file{.cache/gdb} subdirectory 21781of your home directory. However, on some systems, the default may 21782differ according to local convention. 21783 21784There is no limit on the disk space used by index cache. It is perfectly safe 21785to delete the content of that directory to free up disk space. 21786 21787@item show index-cache stats 21788Print the number of cache hits and misses since the launch of @value{GDBN}. 21789 21790@end table 21791 21792@node Symbol Errors 21793@section Errors Reading Symbol Files 21794 21795While reading a symbol file, @value{GDBN} occasionally encounters problems, 21796such as symbol types it does not recognize, or known bugs in compiler 21797output. By default, @value{GDBN} does not notify you of such problems, since 21798they are relatively common and primarily of interest to people 21799debugging compilers. If you are interested in seeing information 21800about ill-constructed symbol tables, you can either ask @value{GDBN} to print 21801only one message about each such type of problem, no matter how many 21802times the problem occurs; or you can ask @value{GDBN} to print more messages, 21803to see how many times the problems occur, with the @code{set 21804complaints} command (@pxref{Messages/Warnings, ,Optional Warnings and 21805Messages}). 21806 21807The messages currently printed, and their meanings, include: 21808 21809@table @code 21810@item inner block not inside outer block in @var{symbol} 21811 21812The symbol information shows where symbol scopes begin and end 21813(such as at the start of a function or a block of statements). This 21814error indicates that an inner scope block is not fully contained 21815in its outer scope blocks. 21816 21817@value{GDBN} circumvents the problem by treating the inner block as if it had 21818the same scope as the outer block. In the error message, @var{symbol} 21819may be shown as ``@code{(don't know)}'' if the outer block is not a 21820function. 21821 21822@item block at @var{address} out of order 21823 21824The symbol information for symbol scope blocks should occur in 21825order of increasing addresses. This error indicates that it does not 21826do so. 21827 21828@value{GDBN} does not circumvent this problem, and has trouble 21829locating symbols in the source file whose symbols it is reading. (You 21830can often determine what source file is affected by specifying 21831@code{set verbose on}. @xref{Messages/Warnings, ,Optional Warnings and 21832Messages}.) 21833 21834@item bad block start address patched 21835 21836The symbol information for a symbol scope block has a start address 21837smaller than the address of the preceding source line. This is known 21838to occur in the SunOS 4.1.1 (and earlier) C compiler. 21839 21840@value{GDBN} circumvents the problem by treating the symbol scope block as 21841starting on the previous source line. 21842 21843@item bad string table offset in symbol @var{n} 21844 21845@cindex foo 21846Symbol number @var{n} contains a pointer into the string table which is 21847larger than the size of the string table. 21848 21849@value{GDBN} circumvents the problem by considering the symbol to have the 21850name @code{foo}, which may cause other problems if many symbols end up 21851with this name. 21852 21853@item unknown symbol type @code{0x@var{nn}} 21854 21855The symbol information contains new data types that @value{GDBN} does 21856not yet know how to read. @code{0x@var{nn}} is the symbol type of the 21857uncomprehended information, in hexadecimal. 21858 21859@value{GDBN} circumvents the error by ignoring this symbol information. 21860This usually allows you to debug your program, though certain symbols 21861are not accessible. If you encounter such a problem and feel like 21862debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint 21863on @code{complain}, then go up to the function @code{read_dbx_symtab} 21864and examine @code{*bufp} to see the symbol. 21865 21866@item stub type has NULL name 21867 21868@value{GDBN} could not find the full definition for a struct or class. 21869 21870@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{} 21871The symbol information for a C@t{++} member function is missing some 21872information that recent versions of the compiler should have output for 21873it. 21874 21875@item info mismatch between compiler and debugger 21876 21877@value{GDBN} could not parse a type specification output by the compiler. 21878 21879@end table 21880 21881@node Data Files 21882@section GDB Data Files 21883 21884@cindex prefix for data files 21885@value{GDBN} will sometimes read an auxiliary data file. These files 21886are kept in a directory known as the @dfn{data directory}. 21887 21888You can set the data directory's name, and view the name @value{GDBN} 21889is currently using. 21890 21891@table @code 21892@kindex set data-directory 21893@item set data-directory @var{directory} 21894Set the directory which @value{GDBN} searches for auxiliary data files 21895to @var{directory}. 21896 21897@kindex show data-directory 21898@item show data-directory 21899Show the directory @value{GDBN} searches for auxiliary data files. 21900@end table 21901 21902@cindex default data directory 21903@cindex @samp{--with-gdb-datadir} 21904You can set the default data directory by using the configure-time 21905@samp{--with-gdb-datadir} option. If the data directory is inside 21906@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or 21907@samp{--exec-prefix}), then the default data directory will be updated 21908automatically if the installed @value{GDBN} is moved to a new 21909location. 21910 21911The data directory may also be specified with the 21912@code{--data-directory} command line option. 21913@xref{Mode Options}. 21914 21915@node Targets 21916@chapter Specifying a Debugging Target 21917 21918@cindex debugging target 21919A @dfn{target} is the execution environment occupied by your program. 21920 21921Often, @value{GDBN} runs in the same host environment as your program; 21922in that case, the debugging target is specified as a side effect when 21923you use the @code{file} or @code{core} commands. When you need more 21924flexibility---for example, running @value{GDBN} on a physically separate 21925host, or controlling a standalone system over a serial port or a 21926realtime system over a TCP/IP connection---you can use the @code{target} 21927command to specify one of the target types configured for @value{GDBN} 21928(@pxref{Target Commands, ,Commands for Managing Targets}). 21929 21930@cindex target architecture 21931It is possible to build @value{GDBN} for several different @dfn{target 21932architectures}. When @value{GDBN} is built like that, you can choose 21933one of the available architectures with the @kbd{set architecture} 21934command. 21935 21936@table @code 21937@kindex set architecture 21938@kindex show architecture 21939@item set architecture @var{arch} 21940This command sets the current target architecture to @var{arch}. The 21941value of @var{arch} can be @code{"auto"}, in addition to one of the 21942supported architectures. 21943 21944@item show architecture 21945Show the current target architecture. 21946 21947@item set processor 21948@itemx processor 21949@kindex set processor 21950@kindex show processor 21951These are alias commands for, respectively, @code{set architecture} 21952and @code{show architecture}. 21953@end table 21954 21955@menu 21956* Active Targets:: Active targets 21957* Target Commands:: Commands for managing targets 21958* Byte Order:: Choosing target byte order 21959@end menu 21960 21961@node Active Targets 21962@section Active Targets 21963 21964@cindex stacking targets 21965@cindex active targets 21966@cindex multiple targets 21967 21968There are multiple classes of targets such as: processes, executable files or 21969recording sessions. Core files belong to the process class, making core file 21970and process mutually exclusive. Otherwise, @value{GDBN} can work concurrently 21971on multiple active targets, one in each class. This allows you to (for 21972example) start a process and inspect its activity, while still having access to 21973the executable file after the process finishes. Or if you start process 21974recording (@pxref{Reverse Execution}) and @code{reverse-step} there, you are 21975presented a virtual layer of the recording target, while the process target 21976remains stopped at the chronologically last point of the process execution. 21977 21978Use the @code{core-file} and @code{exec-file} commands to select a new core 21979file or executable target (@pxref{Files, ,Commands to Specify Files}). To 21980specify as a target a process that is already running, use the @code{attach} 21981command (@pxref{Attach, ,Debugging an Already-running Process}). 21982 21983@node Target Commands 21984@section Commands for Managing Targets 21985 21986@table @code 21987@item target @var{type} @var{parameters} 21988Connects the @value{GDBN} host environment to a target machine or 21989process. A target is typically a protocol for talking to debugging 21990facilities. You use the argument @var{type} to specify the type or 21991protocol of the target machine. 21992 21993Further @var{parameters} are interpreted by the target protocol, but 21994typically include things like device names or host names to connect 21995with, process numbers, and baud rates. 21996 21997The @code{target} command does not repeat if you press @key{RET} again 21998after executing the command. 21999 22000@kindex help target 22001@item help target 22002Displays the names of all targets available. To display targets 22003currently selected, use either @code{info target} or @code{info files} 22004(@pxref{Files, ,Commands to Specify Files}). 22005 22006@item help target @var{name} 22007Describe a particular target, including any parameters necessary to 22008select it. 22009 22010@kindex set gnutarget 22011@item set gnutarget @var{args} 22012@value{GDBN} uses its own library BFD to read your files. @value{GDBN} 22013knows whether it is reading an @dfn{executable}, 22014a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format 22015with the @code{set gnutarget} command. Unlike most @code{target} commands, 22016with @code{gnutarget} the @code{target} refers to a program, not a machine. 22017 22018@quotation 22019@emph{Warning:} To specify a file format with @code{set gnutarget}, 22020you must know the actual BFD name. 22021@end quotation 22022 22023@noindent 22024@xref{Files, , Commands to Specify Files}. 22025 22026@kindex show gnutarget 22027@item show gnutarget 22028Use the @code{show gnutarget} command to display what file format 22029@code{gnutarget} is set to read. If you have not set @code{gnutarget}, 22030@value{GDBN} will determine the file format for each file automatically, 22031and @code{show gnutarget} displays @samp{The current BFD target is "auto"}. 22032@end table 22033 22034@cindex common targets 22035Here are some common targets (available, or not, depending on the GDB 22036configuration): 22037 22038@table @code 22039@kindex target 22040@item target exec @var{program} 22041@cindex executable file target 22042An executable file. @samp{target exec @var{program}} is the same as 22043@samp{exec-file @var{program}}. 22044 22045@item target core @var{filename} 22046@cindex core dump file target 22047A core dump file. @samp{target core @var{filename}} is the same as 22048@samp{core-file @var{filename}}. 22049 22050@item target remote @var{medium} 22051@cindex remote target 22052A remote system connected to @value{GDBN} via a serial line or network 22053connection. This command tells @value{GDBN} to use its own remote 22054protocol over @var{medium} for debugging. @xref{Remote Debugging}. 22055 22056For example, if you have a board connected to @file{/dev/ttya} on the 22057machine running @value{GDBN}, you could say: 22058 22059@smallexample 22060target remote /dev/ttya 22061@end smallexample 22062 22063@code{target remote} supports the @code{load} command. This is only 22064useful if you have some other way of getting the stub to the target 22065system, and you can put it somewhere in memory where it won't get 22066clobbered by the download. 22067 22068@item target sim @r{[}@var{simargs}@r{]} @dots{} 22069@cindex built-in simulator target 22070Builtin CPU simulator. @value{GDBN} includes simulators for most architectures. 22071In general, 22072@smallexample 22073 target sim 22074 load 22075 run 22076@end smallexample 22077@noindent 22078works; however, you cannot assume that a specific memory map, device 22079drivers, or even basic I/O is available, although some simulators do 22080provide these. For info about any processor-specific simulator details, 22081see the appropriate section in @ref{Embedded Processors, ,Embedded 22082Processors}. 22083 22084@item target native 22085@cindex native target 22086Setup for local/native process debugging. Useful to make the 22087@code{run} command spawn native processes (likewise @code{attach}, 22088etc.@:) even when @code{set auto-connect-native-target} is @code{off} 22089(@pxref{set auto-connect-native-target}). 22090 22091@end table 22092 22093Different targets are available on different configurations of @value{GDBN}; 22094your configuration may have more or fewer targets. 22095 22096Many remote targets require you to download the executable's code once 22097you've successfully established a connection. You may wish to control 22098various aspects of this process. 22099 22100@table @code 22101 22102@item set hash 22103@kindex set hash@r{, for remote monitors} 22104@cindex hash mark while downloading 22105This command controls whether a hash mark @samp{#} is displayed while 22106downloading a file to the remote monitor. If on, a hash mark is 22107displayed after each S-record is successfully downloaded to the 22108monitor. 22109 22110@item show hash 22111@kindex show hash@r{, for remote monitors} 22112Show the current status of displaying the hash mark. 22113 22114@item set debug monitor 22115@kindex set debug monitor 22116@cindex display remote monitor communications 22117Enable or disable display of communications messages between 22118@value{GDBN} and the remote monitor. 22119 22120@item show debug monitor 22121@kindex show debug monitor 22122Show the current status of displaying communications between 22123@value{GDBN} and the remote monitor. 22124@end table 22125 22126@table @code 22127 22128@kindex load @var{filename} @var{offset} 22129@item load @var{filename} @var{offset} 22130@anchor{load} 22131Depending on what remote debugging facilities are configured into 22132@value{GDBN}, the @code{load} command may be available. Where it exists, it 22133is meant to make @var{filename} (an executable) available for debugging 22134on the remote system---by downloading, or dynamic linking, for example. 22135@code{load} also records the @var{filename} symbol table in @value{GDBN}, like 22136the @code{add-symbol-file} command. 22137 22138If your @value{GDBN} does not have a @code{load} command, attempting to 22139execute it gets the error message ``@code{You can't do that when your 22140target is @dots{}}'' 22141 22142The file is loaded at whatever address is specified in the executable. 22143For some object file formats, you can specify the load address when you 22144link the program; for other formats, like a.out, the object file format 22145specifies a fixed address. 22146@c FIXME! This would be a good place for an xref to the GNU linker doc. 22147 22148It is also possible to tell @value{GDBN} to load the executable file at a 22149specific offset described by the optional argument @var{offset}. When 22150@var{offset} is provided, @var{filename} must also be provided. 22151 22152Depending on the remote side capabilities, @value{GDBN} may be able to 22153load programs into flash memory. 22154 22155@code{load} does not repeat if you press @key{RET} again after using it. 22156@end table 22157 22158@table @code 22159 22160@kindex flash-erase 22161@item flash-erase 22162@anchor{flash-erase} 22163 22164Erases all known flash memory regions on the target. 22165 22166@end table 22167 22168@node Byte Order 22169@section Choosing Target Byte Order 22170 22171@cindex choosing target byte order 22172@cindex target byte order 22173 22174Some types of processors, such as the @acronym{MIPS}, PowerPC, and Renesas SH, 22175offer the ability to run either big-endian or little-endian byte 22176orders. Usually the executable or symbol will include a bit to 22177designate the endian-ness, and you will not need to worry about 22178which to use. However, you may still find it useful to adjust 22179@value{GDBN}'s idea of processor endian-ness manually. 22180 22181@table @code 22182@kindex set endian 22183@item set endian big 22184Instruct @value{GDBN} to assume the target is big-endian. 22185 22186@item set endian little 22187Instruct @value{GDBN} to assume the target is little-endian. 22188 22189@item set endian auto 22190Instruct @value{GDBN} to use the byte order associated with the 22191executable. 22192 22193@item show endian 22194Display @value{GDBN}'s current idea of the target byte order. 22195 22196@end table 22197 22198If the @code{set endian auto} mode is in effect and no executable has 22199been selected, then the endianness used is the last one chosen either 22200by one of the @code{set endian big} and @code{set endian little} 22201commands or by inferring from the last executable used. If no 22202endianness has been previously chosen, then the default for this mode 22203is inferred from the target @value{GDBN} has been built for, and is 22204@code{little} if the name of the target CPU has an @code{el} suffix 22205and @code{big} otherwise. 22206 22207Note that these commands merely adjust interpretation of symbolic 22208data on the host, and that they have absolutely no effect on the 22209target system. 22210 22211 22212@node Remote Debugging 22213@chapter Debugging Remote Programs 22214@cindex remote debugging 22215 22216If you are trying to debug a program running on a machine that cannot run 22217@value{GDBN} in the usual way, it is often useful to use remote debugging. 22218For example, you might use remote debugging on an operating system kernel, 22219or on a small system which does not have a general purpose operating system 22220powerful enough to run a full-featured debugger. 22221 22222Some configurations of @value{GDBN} have special serial or TCP/IP interfaces 22223to make this work with particular debugging targets. In addition, 22224@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN}, 22225but not specific to any particular target system) which you can use if you 22226write the remote stubs---the code that runs on the remote system to 22227communicate with @value{GDBN}. 22228 22229Other remote targets may be available in your 22230configuration of @value{GDBN}; use @code{help target} to list them. 22231 22232@menu 22233* Connecting:: Connecting to a remote target 22234* File Transfer:: Sending files to a remote system 22235* Server:: Using the gdbserver program 22236* Remote Configuration:: Remote configuration 22237* Remote Stub:: Implementing a remote stub 22238@end menu 22239 22240@node Connecting 22241@section Connecting to a Remote Target 22242@cindex remote debugging, connecting 22243@cindex @code{gdbserver}, connecting 22244@cindex remote debugging, types of connections 22245@cindex @code{gdbserver}, types of connections 22246@cindex @code{gdbserver}, @code{target remote} mode 22247@cindex @code{gdbserver}, @code{target extended-remote} mode 22248 22249This section describes how to connect to a remote target, including the 22250types of connections and their differences, how to set up executable and 22251symbol files on the host and target, and the commands used for 22252connecting to and disconnecting from the remote target. 22253 22254@subsection Types of Remote Connections 22255 22256@value{GDBN} supports two types of remote connections, @code{target remote} 22257mode and @code{target extended-remote} mode. Note that many remote targets 22258support only @code{target remote} mode. There are several major 22259differences between the two types of connections, enumerated here: 22260 22261@table @asis 22262 22263@cindex remote debugging, detach and program exit 22264@item Result of detach or program exit 22265@strong{With target remote mode:} When the debugged program exits or you 22266detach from it, @value{GDBN} disconnects from the target. When using 22267@code{gdbserver}, @code{gdbserver} will exit. 22268 22269@strong{With target extended-remote mode:} When the debugged program exits or 22270you detach from it, @value{GDBN} remains connected to the target, even 22271though no program is running. You can rerun the program, attach to a 22272running program, or use @code{monitor} commands specific to the target. 22273 22274When using @code{gdbserver} in this case, it does not exit unless it was 22275invoked using the @option{--once} option. If the @option{--once} option 22276was not used, you can ask @code{gdbserver} to exit using the 22277@code{monitor exit} command (@pxref{Monitor Commands for gdbserver}). 22278 22279@item Specifying the program to debug 22280For both connection types you use the @code{file} command to specify the 22281program on the host system. If you are using @code{gdbserver} there are 22282some differences in how to specify the location of the program on the 22283target. 22284 22285@strong{With target remote mode:} You must either specify the program to debug 22286on the @code{gdbserver} command line or use the @option{--attach} option 22287(@pxref{Attaching to a program,,Attaching to a Running Program}). 22288 22289@cindex @option{--multi}, @code{gdbserver} option 22290@strong{With target extended-remote mode:} You may specify the program to debug 22291on the @code{gdbserver} command line, or you can load the program or attach 22292to it using @value{GDBN} commands after connecting to @code{gdbserver}. 22293 22294@anchor{--multi Option in Types of Remote Connnections} 22295You can start @code{gdbserver} without supplying an initial command to run 22296or process ID to attach. To do this, use the @option{--multi} command line 22297option. Then you can connect using @code{target extended-remote} and start 22298the program you want to debug (see below for details on using the 22299@code{run} command in this scenario). Note that the conditions under which 22300@code{gdbserver} terminates depend on how @value{GDBN} connects to it 22301(@code{target remote} or @code{target extended-remote}). The 22302@option{--multi} option to @code{gdbserver} has no influence on that. 22303 22304@item The @code{run} command 22305@strong{With target remote mode:} The @code{run} command is not 22306supported. Once a connection has been established, you can use all 22307the usual @value{GDBN} commands to examine and change data. The 22308remote program is already running, so you can use commands like 22309@kbd{step} and @kbd{continue}. 22310 22311@strong{With target extended-remote mode:} The @code{run} command is 22312supported. The @code{run} command uses the value set by 22313@code{set remote exec-file} (@pxref{set remote exec-file}) to select 22314the program to run. Command line arguments are supported, except for 22315wildcard expansion and I/O redirection (@pxref{Arguments}). 22316 22317If you specify the program to debug on the command line, then the 22318@code{run} command is not required to start execution, and you can 22319resume using commands like @kbd{step} and @kbd{continue} as with 22320@code{target remote} mode. 22321 22322@anchor{Attaching in Types of Remote Connections} 22323@item Attaching 22324@strong{With target remote mode:} The @value{GDBN} command @code{attach} is 22325not supported. To attach to a running program using @code{gdbserver}, you 22326must use the @option{--attach} option (@pxref{Running gdbserver}). 22327 22328@strong{With target extended-remote mode:} To attach to a running program, 22329you may use the @code{attach} command after the connection has been 22330established. If you are using @code{gdbserver}, you may also invoke 22331@code{gdbserver} using the @option{--attach} option 22332(@pxref{Running gdbserver}). 22333 22334Some remote targets allow @value{GDBN} to determine the executable file running 22335in the process the debugger is attaching to. In such a case, @value{GDBN} 22336uses the value of @code{exec-file-mismatch} to handle a possible mismatch 22337between the executable file name running in the process and the name of the 22338current exec-file loaded by @value{GDBN} (@pxref{set exec-file-mismatch}). 22339 22340@end table 22341 22342@anchor{Host and target files} 22343@subsection Host and Target Files 22344@cindex remote debugging, symbol files 22345@cindex symbol files, remote debugging 22346 22347@value{GDBN}, running on the host, needs access to symbol and debugging 22348information for your program running on the target. This requires 22349access to an unstripped copy of your program, and possibly any associated 22350symbol files. Note that this section applies equally to both @code{target 22351remote} mode and @code{target extended-remote} mode. 22352 22353Some remote targets (@pxref{qXfer executable filename read}, and 22354@pxref{Host I/O Packets}) allow @value{GDBN} to access program files over 22355the same connection used to communicate with @value{GDBN}. With such a 22356target, if the remote program is unstripped, the only command you need is 22357@code{target remote} (or @code{target extended-remote}). 22358 22359If the remote program is stripped, or the target does not support remote 22360program file access, start up @value{GDBN} using the name of the local 22361unstripped copy of your program as the first argument, or use the 22362@code{file} command. Use @code{set sysroot} to specify the location (on 22363the host) of target libraries (unless your @value{GDBN} was compiled with 22364the correct sysroot using @code{--with-sysroot}). Alternatively, you 22365may use @code{set solib-search-path} to specify how @value{GDBN} locates 22366target libraries. 22367 22368The symbol file and target libraries must exactly match the executable 22369and libraries on the target, with one exception: the files on the host 22370system should not be stripped, even if the files on the target system 22371are. Mismatched or missing files will lead to confusing results 22372during debugging. On @sc{gnu}/Linux targets, mismatched or missing 22373files may also prevent @code{gdbserver} from debugging multi-threaded 22374programs. 22375 22376@subsection Remote Connection Commands 22377@cindex remote connection commands 22378@value{GDBN} can communicate with the target over a serial line, a 22379local Unix domain socket, or 22380over an @acronym{IP} network using @acronym{TCP} or @acronym{UDP}. In 22381each case, @value{GDBN} uses the same protocol for debugging your 22382program; only the medium carrying the debugging packets varies. The 22383@code{target remote} and @code{target extended-remote} commands 22384establish a connection to the target. Both commands accept the same 22385arguments, which indicate the medium to use: 22386 22387@table @code 22388 22389@item target remote @var{serial-device} 22390@itemx target extended-remote @var{serial-device} 22391@cindex serial line, @code{target remote} 22392Use @var{serial-device} to communicate with the target. For example, 22393to use a serial line connected to the device named @file{/dev/ttyb}: 22394 22395@smallexample 22396target remote /dev/ttyb 22397@end smallexample 22398 22399If you're using a serial line, you may want to give @value{GDBN} the 22400@samp{--baud} option, or use the @code{set serial baud} command 22401(@pxref{Remote Configuration, set serial baud}) before the 22402@code{target} command. 22403 22404@item target remote @var{local-socket} 22405@itemx target extended-remote @var{local-socket} 22406@cindex local socket, @code{target remote} 22407@cindex Unix domain socket 22408Use @var{local-socket} to communicate with the target. For example, 22409to use a local Unix domain socket bound to the file system entry @file{/tmp/gdb-socket0}: 22410 22411@smallexample 22412target remote /tmp/gdb-socket0 22413@end smallexample 22414 22415Note that this command has the same form as the command to connect 22416to a serial line. @value{GDBN} will automatically determine which 22417kind of file you have specified and will make the appropriate kind 22418of connection. 22419This feature is not available if the host system does not support 22420Unix domain sockets. 22421 22422@item target remote @code{@var{host}:@var{port}} 22423@itemx target remote @code{[@var{host}]:@var{port}} 22424@itemx target remote @code{tcp:@var{host}:@var{port}} 22425@itemx target remote @code{tcp:[@var{host}]:@var{port}} 22426@itemx target remote @code{tcp4:@var{host}:@var{port}} 22427@itemx target remote @code{tcp6:@var{host}:@var{port}} 22428@itemx target remote @code{tcp6:[@var{host}]:@var{port}} 22429@itemx target extended-remote @code{@var{host}:@var{port}} 22430@itemx target extended-remote @code{[@var{host}]:@var{port}} 22431@itemx target extended-remote @code{tcp:@var{host}:@var{port}} 22432@itemx target extended-remote @code{tcp:[@var{host}]:@var{port}} 22433@itemx target extended-remote @code{tcp4:@var{host}:@var{port}} 22434@itemx target extended-remote @code{tcp6:@var{host}:@var{port}} 22435@itemx target extended-remote @code{tcp6:[@var{host}]:@var{port}} 22436@cindex @acronym{TCP} port, @code{target remote} 22437Debug using a @acronym{TCP} connection to @var{port} on @var{host}. 22438The @var{host} may be either a host name, a numeric @acronym{IPv4} 22439address, or a numeric @acronym{IPv6} address (with or without the 22440square brackets to separate the address from the port); @var{port} 22441must be a decimal number. The @var{host} could be the target machine 22442itself, if it is directly connected to the net, or it might be a 22443terminal server which in turn has a serial line to the target. 22444 22445For example, to connect to port 2828 on a terminal server named 22446@code{manyfarms}: 22447 22448@smallexample 22449target remote manyfarms:2828 22450@end smallexample 22451 22452To connect to port 2828 on a terminal server whose address is 22453@code{2001:0db8:85a3:0000:0000:8a2e:0370:7334}, you can either use the 22454square bracket syntax: 22455 22456@smallexample 22457target remote [2001:0db8:85a3:0000:0000:8a2e:0370:7334]:2828 22458@end smallexample 22459 22460@noindent 22461or explicitly specify the @acronym{IPv6} protocol: 22462 22463@smallexample 22464target remote tcp6:2001:0db8:85a3:0000:0000:8a2e:0370:7334:2828 22465@end smallexample 22466 22467This last example may be confusing to the reader, because there is no 22468visible separation between the hostname and the port number. 22469Therefore, we recommend the user to provide @acronym{IPv6} addresses 22470using square brackets for clarity. However, it is important to 22471mention that for @value{GDBN} there is no ambiguity: the number after 22472the last colon is considered to be the port number. 22473 22474If your remote target is actually running on the same machine as your 22475debugger session (e.g.@: a simulator for your target running on the 22476same host), you can omit the hostname. For example, to connect to 22477port 1234 on your local machine: 22478 22479@smallexample 22480target remote :1234 22481@end smallexample 22482@noindent 22483 22484Note that the colon is still required here. 22485 22486@item target remote @code{udp:@var{host}:@var{port}} 22487@itemx target remote @code{udp:[@var{host}]:@var{port}} 22488@itemx target remote @code{udp4:@var{host}:@var{port}} 22489@itemx target remote @code{udp6:[@var{host}]:@var{port}} 22490@itemx target extended-remote @code{udp:@var{host}:@var{port}} 22491@itemx target extended-remote @code{udp:@var{host}:@var{port}} 22492@itemx target extended-remote @code{udp:[@var{host}]:@var{port}} 22493@itemx target extended-remote @code{udp4:@var{host}:@var{port}} 22494@itemx target extended-remote @code{udp6:@var{host}:@var{port}} 22495@itemx target extended-remote @code{udp6:[@var{host}]:@var{port}} 22496@cindex @acronym{UDP} port, @code{target remote} 22497Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to 22498connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}: 22499 22500@smallexample 22501target remote udp:manyfarms:2828 22502@end smallexample 22503 22504When using a @acronym{UDP} connection for remote debugging, you should 22505keep in mind that the `U' stands for ``Unreliable''. @acronym{UDP} 22506can silently drop packets on busy or unreliable networks, which will 22507cause havoc with your debugging session. 22508 22509@item target remote | @var{command} 22510@itemx target extended-remote | @var{command} 22511@cindex pipe, @code{target remote} to 22512Run @var{command} in the background and communicate with it using a 22513pipe. The @var{command} is a shell command, to be parsed and expanded 22514by the system's command shell, @code{/bin/sh}; it should expect remote 22515protocol packets on its standard input, and send replies on its 22516standard output. You could use this to run a stand-alone simulator 22517that speaks the remote debugging protocol, to make net connections 22518using programs like @code{ssh}, or for other similar tricks. 22519 22520If @var{command} closes its standard output (perhaps by exiting), 22521@value{GDBN} will try to send it a @code{SIGTERM} signal. (If the 22522program has already exited, this will have no effect.) 22523 22524@end table 22525 22526@cindex interrupting remote programs 22527@cindex remote programs, interrupting 22528Whenever @value{GDBN} is waiting for the remote program, if you type the 22529interrupt character (often @kbd{Ctrl-c}), @value{GDBN} attempts to stop the 22530program. This may or may not succeed, depending in part on the hardware 22531and the serial drivers the remote system uses. If you type the 22532interrupt character once again, @value{GDBN} displays this prompt: 22533 22534@smallexample 22535Interrupted while waiting for the program. 22536Give up (and stop debugging it)? (y or n) 22537@end smallexample 22538 22539In @code{target remote} mode, if you type @kbd{y}, @value{GDBN} abandons 22540the remote debugging session. (If you decide you want to try again later, 22541you can use @kbd{target remote} again to connect once more.) If you type 22542@kbd{n}, @value{GDBN} goes back to waiting. 22543 22544In @code{target extended-remote} mode, typing @kbd{n} will leave 22545@value{GDBN} connected to the target. 22546 22547@table @code 22548@kindex detach (remote) 22549@item detach 22550When you have finished debugging the remote program, you can use the 22551@code{detach} command to release it from @value{GDBN} control. 22552Detaching from the target normally resumes its execution, but the results 22553will depend on your particular remote stub. After the @code{detach} 22554command in @code{target remote} mode, @value{GDBN} is free to connect to 22555another target. In @code{target extended-remote} mode, @value{GDBN} is 22556still connected to the target. 22557 22558@kindex disconnect 22559@item disconnect 22560The @code{disconnect} command closes the connection to the target, and 22561the target is generally not resumed. It will wait for @value{GDBN} 22562(this instance or another one) to connect and continue debugging. After 22563the @code{disconnect} command, @value{GDBN} is again free to connect to 22564another target. 22565 22566@cindex send command to remote monitor 22567@cindex extend @value{GDBN} for remote targets 22568@cindex add new commands for external monitor 22569@kindex monitor 22570@item monitor @var{cmd} 22571This command allows you to send arbitrary commands directly to the 22572remote monitor. Since @value{GDBN} doesn't care about the commands it 22573sends like this, this command is the way to extend @value{GDBN}---you 22574can add new commands that only the external monitor will understand 22575and implement. 22576@end table 22577 22578@node File Transfer 22579@section Sending files to a remote system 22580@cindex remote target, file transfer 22581@cindex file transfer 22582@cindex sending files to remote systems 22583 22584Some remote targets offer the ability to transfer files over the same 22585connection used to communicate with @value{GDBN}. This is convenient 22586for targets accessible through other means, e.g.@: @sc{gnu}/Linux systems 22587running @code{gdbserver} over a network interface. For other targets, 22588e.g.@: embedded devices with only a single serial port, this may be 22589the only way to upload or download files. 22590 22591Not all remote targets support these commands. 22592 22593@table @code 22594@kindex remote put 22595@item remote put @var{hostfile} @var{targetfile} 22596Copy file @var{hostfile} from the host system (the machine running 22597@value{GDBN}) to @var{targetfile} on the target system. 22598 22599@kindex remote get 22600@item remote get @var{targetfile} @var{hostfile} 22601Copy file @var{targetfile} from the target system to @var{hostfile} 22602on the host system. 22603 22604@kindex remote delete 22605@item remote delete @var{targetfile} 22606Delete @var{targetfile} from the target system. 22607 22608@end table 22609 22610@node Server 22611@section Using the @code{gdbserver} Program 22612 22613@kindex gdbserver 22614@cindex remote connection without stubs 22615@code{gdbserver} is a control program for Unix-like systems, which 22616allows you to connect your program with a remote @value{GDBN} via 22617@code{target remote} or @code{target extended-remote}---but without 22618linking in the usual debugging stub. 22619 22620@code{gdbserver} is not a complete replacement for the debugging stubs, 22621because it requires essentially the same operating-system facilities 22622that @value{GDBN} itself does. In fact, a system that can run 22623@code{gdbserver} to connect to a remote @value{GDBN} could also run 22624@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless, 22625because it is a much smaller program than @value{GDBN} itself. It is 22626also easier to port than all of @value{GDBN}, so you may be able to get 22627started more quickly on a new system by using @code{gdbserver}. 22628Finally, if you develop code for real-time systems, you may find that 22629the tradeoffs involved in real-time operation make it more convenient to 22630do as much development work as possible on another system, for example 22631by cross-compiling. You can use @code{gdbserver} to make a similar 22632choice for debugging. 22633 22634@value{GDBN} and @code{gdbserver} communicate via either a serial line 22635or a TCP connection, using the standard @value{GDBN} remote serial 22636protocol. 22637 22638@quotation 22639@emph{Warning:} @code{gdbserver} does not have any built-in security. 22640Do not run @code{gdbserver} connected to any public network; a 22641@value{GDBN} connection to @code{gdbserver} provides access to the 22642target system with the same privileges as the user running 22643@code{gdbserver}. 22644@end quotation 22645 22646@anchor{Running gdbserver} 22647@subsection Running @code{gdbserver} 22648@cindex arguments, to @code{gdbserver} 22649@cindex @code{gdbserver}, command-line arguments 22650 22651Run @code{gdbserver} on the target system. You need a copy of the 22652program you want to debug, including any libraries it requires. 22653@code{gdbserver} does not need your program's symbol table, so you can 22654strip the program if necessary to save space. @value{GDBN} on the host 22655system does all the symbol handling. 22656 22657To use the server, you must tell it how to communicate with @value{GDBN}; 22658the name of your program; and the arguments for your program. The usual 22659syntax is: 22660 22661@smallexample 22662target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ] 22663@end smallexample 22664 22665@var{comm} is either a device name (to use a serial line), or a TCP 22666hostname and portnumber, or @code{-} or @code{stdio} to use 22667stdin/stdout of @code{gdbserver}. 22668For example, to debug Emacs with the argument 22669@samp{foo.txt} and communicate with @value{GDBN} over the serial port 22670@file{/dev/com1}: 22671 22672@smallexample 22673target> gdbserver /dev/com1 emacs foo.txt 22674@end smallexample 22675 22676@code{gdbserver} waits passively for the host @value{GDBN} to communicate 22677with it. 22678 22679To use a TCP connection instead of a serial line: 22680 22681@smallexample 22682target> gdbserver host:2345 emacs foo.txt 22683@end smallexample 22684 22685The only difference from the previous example is the first argument, 22686specifying that you are communicating with the host @value{GDBN} via 22687TCP. The @samp{host:2345} argument means that @code{gdbserver} is to 22688expect a TCP connection from machine @samp{host} to local TCP port 2345. 22689(Currently, the @samp{host} part is ignored.) You can choose any number 22690you want for the port number as long as it does not conflict with any 22691TCP ports already in use on the target system (for example, @code{23} is 22692reserved for @code{telnet}).@footnote{If you choose a port number that 22693conflicts with another service, @code{gdbserver} prints an error message 22694and exits.} You must use the same port number with the host @value{GDBN} 22695@code{target remote} command. 22696 22697The @code{stdio} connection is useful when starting @code{gdbserver} 22698with ssh: 22699 22700@smallexample 22701(gdb) target remote | ssh -T hostname gdbserver - hello 22702@end smallexample 22703 22704The @samp{-T} option to ssh is provided because we don't need a remote pty, 22705and we don't want escape-character handling. Ssh does this by default when 22706a command is provided, the flag is provided to make it explicit. 22707You could elide it if you want to. 22708 22709Programs started with stdio-connected gdbserver have @file{/dev/null} for 22710@code{stdin}, and @code{stdout},@code{stderr} are sent back to gdb for 22711display through a pipe connected to gdbserver. 22712Both @code{stdout} and @code{stderr} use the same pipe. 22713 22714@anchor{Attaching to a program} 22715@subsubsection Attaching to a Running Program 22716@cindex attach to a program, @code{gdbserver} 22717@cindex @option{--attach}, @code{gdbserver} option 22718 22719On some targets, @code{gdbserver} can also attach to running programs. 22720This is accomplished via the @code{--attach} argument. The syntax is: 22721 22722@smallexample 22723target> gdbserver --attach @var{comm} @var{pid} 22724@end smallexample 22725 22726@var{pid} is the process ID of a currently running process. It isn't 22727necessary to point @code{gdbserver} at a binary for the running process. 22728 22729In @code{target extended-remote} mode, you can also attach using the 22730@value{GDBN} attach command 22731(@pxref{Attaching in Types of Remote Connections}). 22732 22733@pindex pidof 22734You can debug processes by name instead of process ID if your target has the 22735@code{pidof} utility: 22736 22737@smallexample 22738target> gdbserver --attach @var{comm} `pidof @var{program}` 22739@end smallexample 22740 22741In case more than one copy of @var{program} is running, or @var{program} 22742has multiple threads, most versions of @code{pidof} support the 22743@code{-s} option to only return the first process ID. 22744 22745@subsubsection TCP port allocation lifecycle of @code{gdbserver} 22746 22747This section applies only when @code{gdbserver} is run to listen on a TCP 22748port. 22749 22750@code{gdbserver} normally terminates after all of its debugged processes have 22751terminated in @kbd{target remote} mode. On the other hand, for @kbd{target 22752extended-remote}, @code{gdbserver} stays running even with no processes left. 22753@value{GDBN} normally terminates the spawned debugged process on its exit, 22754which normally also terminates @code{gdbserver} in the @kbd{target remote} 22755mode. Therefore, when the connection drops unexpectedly, and @value{GDBN} 22756cannot ask @code{gdbserver} to kill its debugged processes, @code{gdbserver} 22757stays running even in the @kbd{target remote} mode. 22758 22759When @code{gdbserver} stays running, @value{GDBN} can connect to it again later. 22760Such reconnecting is useful for features like @ref{disconnected tracing}. For 22761completeness, at most one @value{GDBN} can be connected at a time. 22762 22763@cindex @option{--once}, @code{gdbserver} option 22764By default, @code{gdbserver} keeps the listening TCP port open, so that 22765subsequent connections are possible. However, if you start @code{gdbserver} 22766with the @option{--once} option, it will stop listening for any further 22767connection attempts after connecting to the first @value{GDBN} session. This 22768means no further connections to @code{gdbserver} will be possible after the 22769first one. It also means @code{gdbserver} will terminate after the first 22770connection with remote @value{GDBN} has closed, even for unexpectedly closed 22771connections and even in the @kbd{target extended-remote} mode. The 22772@option{--once} option allows reusing the same port number for connecting to 22773multiple instances of @code{gdbserver} running on the same host, since each 22774instance closes its port after the first connection. 22775 22776@anchor{Other Command-Line Arguments for gdbserver} 22777@subsubsection Other Command-Line Arguments for @code{gdbserver} 22778 22779You can use the @option{--multi} option to start @code{gdbserver} without 22780specifying a program to debug or a process to attach to. Then you can 22781attach in @code{target extended-remote} mode and run or attach to a 22782program. For more information, 22783@pxref{--multi Option in Types of Remote Connnections}. 22784 22785@cindex @option{--debug}, @code{gdbserver} option 22786The @option{--debug} option tells @code{gdbserver} to display extra 22787status information about the debugging process. 22788@cindex @option{--remote-debug}, @code{gdbserver} option 22789The @option{--remote-debug} option tells @code{gdbserver} to display 22790remote protocol debug output. 22791@cindex @option{--debug-file}, @code{gdbserver} option 22792@cindex @code{gdbserver}, send all debug output to a single file 22793The @option{--debug-file=@var{filename}} option tells @code{gdbserver} to 22794write any debug output to the given @var{filename}. These options are intended 22795for @code{gdbserver} development and for bug reports to the developers. 22796 22797@cindex @option{--debug-format}, @code{gdbserver} option 22798The @option{--debug-format=option1[,option2,...]} option tells 22799@code{gdbserver} to include additional information in each output. 22800Possible options are: 22801 22802@table @code 22803@item none 22804Turn off all extra information in debugging output. 22805@item all 22806Turn on all extra information in debugging output. 22807@item timestamps 22808Include a timestamp in each line of debugging output. 22809@end table 22810 22811Options are processed in order. Thus, for example, if @option{none} 22812appears last then no additional information is added to debugging output. 22813 22814@cindex @option{--wrapper}, @code{gdbserver} option 22815The @option{--wrapper} option specifies a wrapper to launch programs 22816for debugging. The option should be followed by the name of the 22817wrapper, then any command-line arguments to pass to the wrapper, then 22818@kbd{--} indicating the end of the wrapper arguments. 22819 22820@code{gdbserver} runs the specified wrapper program with a combined 22821command line including the wrapper arguments, then the name of the 22822program to debug, then any arguments to the program. The wrapper 22823runs until it executes your program, and then @value{GDBN} gains control. 22824 22825You can use any program that eventually calls @code{execve} with 22826its arguments as a wrapper. Several standard Unix utilities do 22827this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending 22828with @code{exec "$@@"} will also work. 22829 22830For example, you can use @code{env} to pass an environment variable to 22831the debugged program, without setting the variable in @code{gdbserver}'s 22832environment: 22833 22834@smallexample 22835$ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog 22836@end smallexample 22837 22838@cindex @option{--selftest} 22839The @option{--selftest} option runs the self tests in @code{gdbserver}: 22840 22841@smallexample 22842$ gdbserver --selftest 22843Ran 2 unit tests, 0 failed 22844@end smallexample 22845 22846These tests are disabled in release. 22847@subsection Connecting to @code{gdbserver} 22848 22849The basic procedure for connecting to the remote target is: 22850@itemize 22851 22852@item 22853Run @value{GDBN} on the host system. 22854 22855@item 22856Make sure you have the necessary symbol files 22857(@pxref{Host and target files}). 22858Load symbols for your application using the @code{file} command before you 22859connect. Use @code{set sysroot} to locate target libraries (unless your 22860@value{GDBN} was compiled with the correct sysroot using 22861@code{--with-sysroot}). 22862 22863@item 22864Connect to your target (@pxref{Connecting,,Connecting to a Remote Target}). 22865For TCP connections, you must start up @code{gdbserver} prior to using 22866the @code{target} command. Otherwise you may get an error whose 22867text depends on the host system, but which usually looks something like 22868@samp{Connection refused}. Don't use the @code{load} 22869command in @value{GDBN} when using @code{target remote} mode, since the 22870program is already on the target. 22871 22872@end itemize 22873 22874@anchor{Monitor Commands for gdbserver} 22875@subsection Monitor Commands for @code{gdbserver} 22876@cindex monitor commands, for @code{gdbserver} 22877 22878During a @value{GDBN} session using @code{gdbserver}, you can use the 22879@code{monitor} command to send special requests to @code{gdbserver}. 22880Here are the available commands. 22881 22882@table @code 22883@item monitor help 22884List the available monitor commands. 22885 22886@item monitor set debug 0 22887@itemx monitor set debug 1 22888Disable or enable general debugging messages. 22889 22890@item monitor set remote-debug 0 22891@itemx monitor set remote-debug 1 22892Disable or enable specific debugging messages associated with the remote 22893protocol (@pxref{Remote Protocol}). 22894 22895@item monitor set debug-file filename 22896@itemx monitor set debug-file 22897Send any debug output to the given file, or to stderr. 22898 22899@item monitor set debug-format option1@r{[},option2,...@r{]} 22900Specify additional text to add to debugging messages. 22901Possible options are: 22902 22903@table @code 22904@item none 22905Turn off all extra information in debugging output. 22906@item all 22907Turn on all extra information in debugging output. 22908@item timestamps 22909Include a timestamp in each line of debugging output. 22910@end table 22911 22912Options are processed in order. Thus, for example, if @option{none} 22913appears last then no additional information is added to debugging output. 22914 22915@item monitor set libthread-db-search-path [PATH] 22916@cindex gdbserver, search path for @code{libthread_db} 22917When this command is issued, @var{path} is a colon-separated list of 22918directories to search for @code{libthread_db} (@pxref{Threads,,set 22919libthread-db-search-path}). If you omit @var{path}, 22920@samp{libthread-db-search-path} will be reset to its default value. 22921 22922The special entry @samp{$pdir} for @samp{libthread-db-search-path} is 22923not supported in @code{gdbserver}. 22924 22925@item monitor exit 22926Tell gdbserver to exit immediately. This command should be followed by 22927@code{disconnect} to close the debugging session. @code{gdbserver} will 22928detach from any attached processes and kill any processes it created. 22929Use @code{monitor exit} to terminate @code{gdbserver} at the end 22930of a multi-process mode debug session. 22931 22932@end table 22933 22934@subsection Tracepoints support in @code{gdbserver} 22935@cindex tracepoints support in @code{gdbserver} 22936 22937On some targets, @code{gdbserver} supports tracepoints, fast 22938tracepoints and static tracepoints. 22939 22940For fast or static tracepoints to work, a special library called the 22941@dfn{in-process agent} (IPA), must be loaded in the inferior process. 22942This library is built and distributed as an integral part of 22943@code{gdbserver}. In addition, support for static tracepoints 22944requires building the in-process agent library with static tracepoints 22945support. At present, the UST (LTTng Userspace Tracer, 22946@url{http://lttng.org/ust}) tracing engine is supported. This support 22947is automatically available if UST development headers are found in the 22948standard include path when @code{gdbserver} is built, or if 22949@code{gdbserver} was explicitly configured using @option{--with-ust} 22950to point at such headers. You can explicitly disable the support 22951using @option{--with-ust=no}. 22952 22953There are several ways to load the in-process agent in your program: 22954 22955@table @code 22956@item Specifying it as dependency at link time 22957 22958You can link your program dynamically with the in-process agent 22959library. On most systems, this is accomplished by adding 22960@code{-linproctrace} to the link command. 22961 22962@item Using the system's preloading mechanisms 22963 22964You can force loading the in-process agent at startup time by using 22965your system's support for preloading shared libraries. Many Unixes 22966support the concept of preloading user defined libraries. In most 22967cases, you do that by specifying @code{LD_PRELOAD=libinproctrace.so} 22968in the environment. See also the description of @code{gdbserver}'s 22969@option{--wrapper} command line option. 22970 22971@item Using @value{GDBN} to force loading the agent at run time 22972 22973On some systems, you can force the inferior to load a shared library, 22974by calling a dynamic loader function in the inferior that takes care 22975of dynamically looking up and loading a shared library. On most Unix 22976systems, the function is @code{dlopen}. You'll use the @code{call} 22977command for that. For example: 22978 22979@smallexample 22980(@value{GDBP}) call dlopen ("libinproctrace.so", ...) 22981@end smallexample 22982 22983Note that on most Unix systems, for the @code{dlopen} function to be 22984available, the program needs to be linked with @code{-ldl}. 22985@end table 22986 22987On systems that have a userspace dynamic loader, like most Unix 22988systems, when you connect to @code{gdbserver} using @code{target 22989remote}, you'll find that the program is stopped at the dynamic 22990loader's entry point, and no shared library has been loaded in the 22991program's address space yet, including the in-process agent. In that 22992case, before being able to use any of the fast or static tracepoints 22993features, you need to let the loader run and load the shared 22994libraries. The simplest way to do that is to run the program to the 22995main procedure. E.g., if debugging a C or C@t{++} program, start 22996@code{gdbserver} like so: 22997 22998@smallexample 22999$ gdbserver :9999 myprogram 23000@end smallexample 23001 23002Start GDB and connect to @code{gdbserver} like so, and run to main: 23003 23004@smallexample 23005$ gdb myprogram 23006(@value{GDBP}) target remote myhost:9999 230070x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2 23008(@value{GDBP}) b main 23009(@value{GDBP}) continue 23010@end smallexample 23011 23012The in-process tracing agent library should now be loaded into the 23013process; you can confirm it with the @code{info sharedlibrary} 23014command, which will list @file{libinproctrace.so} as loaded in the 23015process. You are now ready to install fast tracepoints, list static 23016tracepoint markers, probe static tracepoints markers, and start 23017tracing. 23018 23019@node Remote Configuration 23020@section Remote Configuration 23021 23022@kindex set remote 23023@kindex show remote 23024This section documents the configuration options available when 23025debugging remote programs. For the options related to the File I/O 23026extensions of the remote protocol, see @ref{system, 23027system-call-allowed}. 23028 23029@table @code 23030@item set remoteaddresssize @var{bits} 23031@cindex address size for remote targets 23032@cindex bits in remote address 23033Set the maximum size of address in a memory packet to the specified 23034number of bits. @value{GDBN} will mask off the address bits above 23035that number, when it passes addresses to the remote target. The 23036default value is the number of bits in the target's address. 23037 23038@item show remoteaddresssize 23039Show the current value of remote address size in bits. 23040 23041@item set serial baud @var{n} 23042@cindex baud rate for remote targets 23043Set the baud rate for the remote serial I/O to @var{n} baud. The 23044value is used to set the speed of the serial port used for debugging 23045remote targets. 23046 23047@item show serial baud 23048Show the current speed of the remote connection. 23049 23050@item set serial parity @var{parity} 23051Set the parity for the remote serial I/O. Supported values of @var{parity} are: 23052@code{even}, @code{none}, and @code{odd}. The default is @code{none}. 23053 23054@item show serial parity 23055Show the current parity of the serial port. 23056 23057@item set remotebreak 23058@cindex interrupt remote programs 23059@cindex BREAK signal instead of Ctrl-C 23060@anchor{set remotebreak} 23061If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote 23062when you type @kbd{Ctrl-c} to interrupt the program running 23063on the remote. If set to off, @value{GDBN} sends the @samp{Ctrl-C} 23064character instead. The default is off, since most remote systems 23065expect to see @samp{Ctrl-C} as the interrupt signal. 23066 23067@item show remotebreak 23068Show whether @value{GDBN} sends @code{BREAK} or @samp{Ctrl-C} to 23069interrupt the remote program. 23070 23071@item set remoteflow on 23072@itemx set remoteflow off 23073@kindex set remoteflow 23074Enable or disable hardware flow control (@code{RTS}/@code{CTS}) 23075on the serial port used to communicate to the remote target. 23076 23077@item show remoteflow 23078@kindex show remoteflow 23079Show the current setting of hardware flow control. 23080 23081@item set remotelogbase @var{base} 23082Set the base (a.k.a.@: radix) of logging serial protocol 23083communications to @var{base}. Supported values of @var{base} are: 23084@code{ascii}, @code{octal}, and @code{hex}. The default is 23085@code{ascii}. 23086 23087@item show remotelogbase 23088Show the current setting of the radix for logging remote serial 23089protocol. 23090 23091@item set remotelogfile @var{file} 23092@cindex record serial communications on file 23093Record remote serial communications on the named @var{file}. The 23094default is not to record at all. 23095 23096@item show remotelogfile 23097Show the current setting of the file name on which to record the 23098serial communications. 23099 23100@item set remotetimeout @var{num} 23101@cindex timeout for serial communications 23102@cindex remote timeout 23103Set the timeout limit to wait for the remote target to respond to 23104@var{num} seconds. The default is 2 seconds. 23105 23106@item show remotetimeout 23107Show the current number of seconds to wait for the remote target 23108responses. 23109 23110@cindex limit hardware breakpoints and watchpoints 23111@cindex remote target, limit break- and watchpoints 23112@anchor{set remote hardware-watchpoint-limit} 23113@anchor{set remote hardware-breakpoint-limit} 23114@item set remote hardware-watchpoint-limit @var{limit} 23115@itemx set remote hardware-breakpoint-limit @var{limit} 23116Restrict @value{GDBN} to using @var{limit} remote hardware watchpoints 23117or breakpoints. The @var{limit} can be set to 0 to disable hardware 23118watchpoints or breakpoints, and @code{unlimited} for unlimited 23119watchpoints or breakpoints. 23120 23121@item show remote hardware-watchpoint-limit 23122@itemx show remote hardware-breakpoint-limit 23123Show the current limit for the number of hardware watchpoints or 23124breakpoints that @value{GDBN} can use. 23125 23126@cindex limit hardware watchpoints length 23127@cindex remote target, limit watchpoints length 23128@anchor{set remote hardware-watchpoint-length-limit} 23129@item set remote hardware-watchpoint-length-limit @var{limit} 23130Restrict @value{GDBN} to using @var{limit} bytes for the maximum 23131length of a remote hardware watchpoint. A @var{limit} of 0 disables 23132hardware watchpoints and @code{unlimited} allows watchpoints of any 23133length. 23134 23135@item show remote hardware-watchpoint-length-limit 23136Show the current limit (in bytes) of the maximum length of 23137a remote hardware watchpoint. 23138 23139@item set remote exec-file @var{filename} 23140@itemx show remote exec-file 23141@anchor{set remote exec-file} 23142@cindex executable file, for remote target 23143Select the file used for @code{run} with @code{target 23144extended-remote}. This should be set to a filename valid on the 23145target system. If it is not set, the target will use a default 23146filename (e.g.@: the last program run). 23147 23148@item set remote interrupt-sequence 23149@cindex interrupt remote programs 23150@cindex select Ctrl-C, BREAK or BREAK-g 23151Allow the user to select one of @samp{Ctrl-C}, a @code{BREAK} or 23152@samp{BREAK-g} as the 23153sequence to the remote target in order to interrupt the execution. 23154@samp{Ctrl-C} is a default. Some system prefers @code{BREAK} which 23155is high level of serial line for some certain time. 23156Linux kernel prefers @samp{BREAK-g}, a.k.a Magic SysRq g. 23157It is @code{BREAK} signal followed by character @code{g}. 23158 23159@item show remote interrupt-sequence 23160Show which of @samp{Ctrl-C}, @code{BREAK} or @code{BREAK-g} 23161is sent by @value{GDBN} to interrupt the remote program. 23162@code{BREAK-g} is BREAK signal followed by @code{g} and 23163also known as Magic SysRq g. 23164 23165@item set remote interrupt-on-connect 23166@cindex send interrupt-sequence on start 23167Specify whether interrupt-sequence is sent to remote target when 23168@value{GDBN} connects to it. This is mostly needed when you debug 23169Linux kernel. Linux kernel expects @code{BREAK} followed by @code{g} 23170which is known as Magic SysRq g in order to connect @value{GDBN}. 23171 23172@item show remote interrupt-on-connect 23173Show whether interrupt-sequence is sent 23174to remote target when @value{GDBN} connects to it. 23175 23176@kindex set tcp 23177@kindex show tcp 23178@item set tcp auto-retry on 23179@cindex auto-retry, for remote TCP target 23180Enable auto-retry for remote TCP connections. This is useful if the remote 23181debugging agent is launched in parallel with @value{GDBN}; there is a race 23182condition because the agent may not become ready to accept the connection 23183before @value{GDBN} attempts to connect. When auto-retry is 23184enabled, if the initial attempt to connect fails, @value{GDBN} reattempts 23185to establish the connection using the timeout specified by 23186@code{set tcp connect-timeout}. 23187 23188@item set tcp auto-retry off 23189Do not auto-retry failed TCP connections. 23190 23191@item show tcp auto-retry 23192Show the current auto-retry setting. 23193 23194@item set tcp connect-timeout @var{seconds} 23195@itemx set tcp connect-timeout unlimited 23196@cindex connection timeout, for remote TCP target 23197@cindex timeout, for remote target connection 23198Set the timeout for establishing a TCP connection to the remote target to 23199@var{seconds}. The timeout affects both polling to retry failed connections 23200(enabled by @code{set tcp auto-retry on}) and waiting for connections 23201that are merely slow to complete, and represents an approximate cumulative 23202value. If @var{seconds} is @code{unlimited}, there is no timeout and 23203@value{GDBN} will keep attempting to establish a connection forever, 23204unless interrupted with @kbd{Ctrl-c}. The default is 15 seconds. 23205 23206@item show tcp connect-timeout 23207Show the current connection timeout setting. 23208@end table 23209 23210@cindex remote packets, enabling and disabling 23211The @value{GDBN} remote protocol autodetects the packets supported by 23212your debugging stub. If you need to override the autodetection, you 23213can use these commands to enable or disable individual packets. Each 23214packet can be set to @samp{on} (the remote target supports this 23215packet), @samp{off} (the remote target does not support this packet), 23216or @samp{auto} (detect remote target support for this packet). They 23217all default to @samp{auto}. For more information about each packet, 23218see @ref{Remote Protocol}. 23219 23220During normal use, you should not have to use any of these commands. 23221If you do, that may be a bug in your remote debugging stub, or a bug 23222in @value{GDBN}. You may want to report the problem to the 23223@value{GDBN} developers. 23224 23225For each packet @var{name}, the command to enable or disable the 23226packet is @code{set remote @var{name}-packet}. The available settings 23227are: 23228 23229@multitable @columnfractions 0.28 0.32 0.25 23230@item Command Name 23231@tab Remote Packet 23232@tab Related Features 23233 23234@item @code{fetch-register} 23235@tab @code{p} 23236@tab @code{info registers} 23237 23238@item @code{set-register} 23239@tab @code{P} 23240@tab @code{set} 23241 23242@item @code{binary-download} 23243@tab @code{X} 23244@tab @code{load}, @code{set} 23245 23246@item @code{read-aux-vector} 23247@tab @code{qXfer:auxv:read} 23248@tab @code{info auxv} 23249 23250@item @code{symbol-lookup} 23251@tab @code{qSymbol} 23252@tab Detecting multiple threads 23253 23254@item @code{attach} 23255@tab @code{vAttach} 23256@tab @code{attach} 23257 23258@item @code{verbose-resume} 23259@tab @code{vCont} 23260@tab Stepping or resuming multiple threads 23261 23262@item @code{run} 23263@tab @code{vRun} 23264@tab @code{run} 23265 23266@item @code{software-breakpoint} 23267@tab @code{Z0} 23268@tab @code{break} 23269 23270@item @code{hardware-breakpoint} 23271@tab @code{Z1} 23272@tab @code{hbreak} 23273 23274@item @code{write-watchpoint} 23275@tab @code{Z2} 23276@tab @code{watch} 23277 23278@item @code{read-watchpoint} 23279@tab @code{Z3} 23280@tab @code{rwatch} 23281 23282@item @code{access-watchpoint} 23283@tab @code{Z4} 23284@tab @code{awatch} 23285 23286@item @code{pid-to-exec-file} 23287@tab @code{qXfer:exec-file:read} 23288@tab @code{attach}, @code{run} 23289 23290@item @code{target-features} 23291@tab @code{qXfer:features:read} 23292@tab @code{set architecture} 23293 23294@item @code{library-info} 23295@tab @code{qXfer:libraries:read} 23296@tab @code{info sharedlibrary} 23297 23298@item @code{memory-map} 23299@tab @code{qXfer:memory-map:read} 23300@tab @code{info mem} 23301 23302@item @code{read-sdata-object} 23303@tab @code{qXfer:sdata:read} 23304@tab @code{print $_sdata} 23305 23306@item @code{read-siginfo-object} 23307@tab @code{qXfer:siginfo:read} 23308@tab @code{print $_siginfo} 23309 23310@item @code{write-siginfo-object} 23311@tab @code{qXfer:siginfo:write} 23312@tab @code{set $_siginfo} 23313 23314@item @code{threads} 23315@tab @code{qXfer:threads:read} 23316@tab @code{info threads} 23317 23318@item @code{get-thread-local-@*storage-address} 23319@tab @code{qGetTLSAddr} 23320@tab Displaying @code{__thread} variables 23321 23322@item @code{get-thread-information-block-address} 23323@tab @code{qGetTIBAddr} 23324@tab Display MS-Windows Thread Information Block. 23325 23326@item @code{search-memory} 23327@tab @code{qSearch:memory} 23328@tab @code{find} 23329 23330@item @code{supported-packets} 23331@tab @code{qSupported} 23332@tab Remote communications parameters 23333 23334@item @code{catch-syscalls} 23335@tab @code{QCatchSyscalls} 23336@tab @code{catch syscall} 23337 23338@item @code{pass-signals} 23339@tab @code{QPassSignals} 23340@tab @code{handle @var{signal}} 23341 23342@item @code{program-signals} 23343@tab @code{QProgramSignals} 23344@tab @code{handle @var{signal}} 23345 23346@item @code{hostio-close-packet} 23347@tab @code{vFile:close} 23348@tab @code{remote get}, @code{remote put} 23349 23350@item @code{hostio-open-packet} 23351@tab @code{vFile:open} 23352@tab @code{remote get}, @code{remote put} 23353 23354@item @code{hostio-pread-packet} 23355@tab @code{vFile:pread} 23356@tab @code{remote get}, @code{remote put} 23357 23358@item @code{hostio-pwrite-packet} 23359@tab @code{vFile:pwrite} 23360@tab @code{remote get}, @code{remote put} 23361 23362@item @code{hostio-unlink-packet} 23363@tab @code{vFile:unlink} 23364@tab @code{remote delete} 23365 23366@item @code{hostio-readlink-packet} 23367@tab @code{vFile:readlink} 23368@tab Host I/O 23369 23370@item @code{hostio-fstat-packet} 23371@tab @code{vFile:fstat} 23372@tab Host I/O 23373 23374@item @code{hostio-setfs-packet} 23375@tab @code{vFile:setfs} 23376@tab Host I/O 23377 23378@item @code{noack-packet} 23379@tab @code{QStartNoAckMode} 23380@tab Packet acknowledgment 23381 23382@item @code{osdata} 23383@tab @code{qXfer:osdata:read} 23384@tab @code{info os} 23385 23386@item @code{query-attached} 23387@tab @code{qAttached} 23388@tab Querying remote process attach state. 23389 23390@item @code{trace-buffer-size} 23391@tab @code{QTBuffer:size} 23392@tab @code{set trace-buffer-size} 23393 23394@item @code{trace-status} 23395@tab @code{qTStatus} 23396@tab @code{tstatus} 23397 23398@item @code{traceframe-info} 23399@tab @code{qXfer:traceframe-info:read} 23400@tab Traceframe info 23401 23402@item @code{install-in-trace} 23403@tab @code{InstallInTrace} 23404@tab Install tracepoint in tracing 23405 23406@item @code{disable-randomization} 23407@tab @code{QDisableRandomization} 23408@tab @code{set disable-randomization} 23409 23410@item @code{startup-with-shell} 23411@tab @code{QStartupWithShell} 23412@tab @code{set startup-with-shell} 23413 23414@item @code{environment-hex-encoded} 23415@tab @code{QEnvironmentHexEncoded} 23416@tab @code{set environment} 23417 23418@item @code{environment-unset} 23419@tab @code{QEnvironmentUnset} 23420@tab @code{unset environment} 23421 23422@item @code{environment-reset} 23423@tab @code{QEnvironmentReset} 23424@tab @code{Reset the inferior environment (i.e., unset user-set variables)} 23425 23426@item @code{set-working-dir} 23427@tab @code{QSetWorkingDir} 23428@tab @code{set cwd} 23429 23430@item @code{conditional-breakpoints-packet} 23431@tab @code{Z0 and Z1} 23432@tab @code{Support for target-side breakpoint condition evaluation} 23433 23434@item @code{multiprocess-extensions} 23435@tab @code{multiprocess extensions} 23436@tab Debug multiple processes and remote process PID awareness 23437 23438@item @code{swbreak-feature} 23439@tab @code{swbreak stop reason} 23440@tab @code{break} 23441 23442@item @code{hwbreak-feature} 23443@tab @code{hwbreak stop reason} 23444@tab @code{hbreak} 23445 23446@item @code{fork-event-feature} 23447@tab @code{fork stop reason} 23448@tab @code{fork} 23449 23450@item @code{vfork-event-feature} 23451@tab @code{vfork stop reason} 23452@tab @code{vfork} 23453 23454@item @code{exec-event-feature} 23455@tab @code{exec stop reason} 23456@tab @code{exec} 23457 23458@item @code{thread-events} 23459@tab @code{QThreadEvents} 23460@tab Tracking thread lifetime. 23461 23462@item @code{no-resumed-stop-reply} 23463@tab @code{no resumed thread left stop reply} 23464@tab Tracking thread lifetime. 23465 23466@end multitable 23467 23468@node Remote Stub 23469@section Implementing a Remote Stub 23470 23471@cindex debugging stub, example 23472@cindex remote stub, example 23473@cindex stub example, remote debugging 23474The stub files provided with @value{GDBN} implement the target side of the 23475communication protocol, and the @value{GDBN} side is implemented in the 23476@value{GDBN} source file @file{remote.c}. Normally, you can simply allow 23477these subroutines to communicate, and ignore the details. (If you're 23478implementing your own stub file, you can still ignore the details: start 23479with one of the existing stub files. @file{sparc-stub.c} is the best 23480organized, and therefore the easiest to read.) 23481 23482@cindex remote serial debugging, overview 23483To debug a program running on another machine (the debugging 23484@dfn{target} machine), you must first arrange for all the usual 23485prerequisites for the program to run by itself. For example, for a C 23486program, you need: 23487 23488@enumerate 23489@item 23490A startup routine to set up the C runtime environment; these usually 23491have a name like @file{crt0}. The startup routine may be supplied by 23492your hardware supplier, or you may have to write your own. 23493 23494@item 23495A C subroutine library to support your program's 23496subroutine calls, notably managing input and output. 23497 23498@item 23499A way of getting your program to the other machine---for example, a 23500download program. These are often supplied by the hardware 23501manufacturer, but you may have to write your own from hardware 23502documentation. 23503@end enumerate 23504 23505The next step is to arrange for your program to use a serial port to 23506communicate with the machine where @value{GDBN} is running (the @dfn{host} 23507machine). In general terms, the scheme looks like this: 23508 23509@table @emph 23510@item On the host, 23511@value{GDBN} already understands how to use this protocol; when everything 23512else is set up, you can simply use the @samp{target remote} command 23513(@pxref{Targets,,Specifying a Debugging Target}). 23514 23515@item On the target, 23516you must link with your program a few special-purpose subroutines that 23517implement the @value{GDBN} remote serial protocol. The file containing these 23518subroutines is called a @dfn{debugging stub}. 23519 23520On certain remote targets, you can use an auxiliary program 23521@code{gdbserver} instead of linking a stub into your program. 23522@xref{Server,,Using the @code{gdbserver} Program}, for details. 23523@end table 23524 23525The debugging stub is specific to the architecture of the remote 23526machine; for example, use @file{sparc-stub.c} to debug programs on 23527@sc{sparc} boards. 23528 23529@cindex remote serial stub list 23530These working remote stubs are distributed with @value{GDBN}: 23531 23532@table @code 23533 23534@item i386-stub.c 23535@cindex @file{i386-stub.c} 23536@cindex Intel 23537@cindex i386 23538For Intel 386 and compatible architectures. 23539 23540@item m68k-stub.c 23541@cindex @file{m68k-stub.c} 23542@cindex Motorola 680x0 23543@cindex m680x0 23544For Motorola 680x0 architectures. 23545 23546@item sh-stub.c 23547@cindex @file{sh-stub.c} 23548@cindex Renesas 23549@cindex SH 23550For Renesas SH architectures. 23551 23552@item sparc-stub.c 23553@cindex @file{sparc-stub.c} 23554@cindex Sparc 23555For @sc{sparc} architectures. 23556 23557@item sparcl-stub.c 23558@cindex @file{sparcl-stub.c} 23559@cindex Fujitsu 23560@cindex SparcLite 23561For Fujitsu @sc{sparclite} architectures. 23562 23563@end table 23564 23565The @file{README} file in the @value{GDBN} distribution may list other 23566recently added stubs. 23567 23568@menu 23569* Stub Contents:: What the stub can do for you 23570* Bootstrapping:: What you must do for the stub 23571* Debug Session:: Putting it all together 23572@end menu 23573 23574@node Stub Contents 23575@subsection What the Stub Can Do for You 23576 23577@cindex remote serial stub 23578The debugging stub for your architecture supplies these three 23579subroutines: 23580 23581@table @code 23582@item set_debug_traps 23583@findex set_debug_traps 23584@cindex remote serial stub, initialization 23585This routine arranges for @code{handle_exception} to run when your 23586program stops. You must call this subroutine explicitly in your 23587program's startup code. 23588 23589@item handle_exception 23590@findex handle_exception 23591@cindex remote serial stub, main routine 23592This is the central workhorse, but your program never calls it 23593explicitly---the setup code arranges for @code{handle_exception} to 23594run when a trap is triggered. 23595 23596@code{handle_exception} takes control when your program stops during 23597execution (for example, on a breakpoint), and mediates communications 23598with @value{GDBN} on the host machine. This is where the communications 23599protocol is implemented; @code{handle_exception} acts as the @value{GDBN} 23600representative on the target machine. It begins by sending summary 23601information on the state of your program, then continues to execute, 23602retrieving and transmitting any information @value{GDBN} needs, until you 23603execute a @value{GDBN} command that makes your program resume; at that point, 23604@code{handle_exception} returns control to your own code on the target 23605machine. 23606 23607@item breakpoint 23608@cindex @code{breakpoint} subroutine, remote 23609Use this auxiliary subroutine to make your program contain a 23610breakpoint. Depending on the particular situation, this may be the only 23611way for @value{GDBN} to get control. For instance, if your target 23612machine has some sort of interrupt button, you won't need to call this; 23613pressing the interrupt button transfers control to 23614@code{handle_exception}---in effect, to @value{GDBN}. On some machines, 23615simply receiving characters on the serial port may also trigger a trap; 23616again, in that situation, you don't need to call @code{breakpoint} from 23617your own program---simply running @samp{target remote} from the host 23618@value{GDBN} session gets control. 23619 23620Call @code{breakpoint} if none of these is true, or if you simply want 23621to make certain your program stops at a predetermined point for the 23622start of your debugging session. 23623@end table 23624 23625@node Bootstrapping 23626@subsection What You Must Do for the Stub 23627 23628@cindex remote stub, support routines 23629The debugging stubs that come with @value{GDBN} are set up for a particular 23630chip architecture, but they have no information about the rest of your 23631debugging target machine. 23632 23633First of all you need to tell the stub how to communicate with the 23634serial port. 23635 23636@table @code 23637@item int getDebugChar() 23638@findex getDebugChar 23639Write this subroutine to read a single character from the serial port. 23640It may be identical to @code{getchar} for your target system; a 23641different name is used to allow you to distinguish the two if you wish. 23642 23643@item void putDebugChar(int) 23644@findex putDebugChar 23645Write this subroutine to write a single character to the serial port. 23646It may be identical to @code{putchar} for your target system; a 23647different name is used to allow you to distinguish the two if you wish. 23648@end table 23649 23650@cindex control C, and remote debugging 23651@cindex interrupting remote targets 23652If you want @value{GDBN} to be able to stop your program while it is 23653running, you need to use an interrupt-driven serial driver, and arrange 23654for it to stop when it receives a @code{^C} (@samp{\003}, the control-C 23655character). That is the character which @value{GDBN} uses to tell the 23656remote system to stop. 23657 23658Getting the debugging target to return the proper status to @value{GDBN} 23659probably requires changes to the standard stub; one quick and dirty way 23660is to just execute a breakpoint instruction (the ``dirty'' part is that 23661@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}). 23662 23663Other routines you need to supply are: 23664 23665@table @code 23666@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address}) 23667@findex exceptionHandler 23668Write this function to install @var{exception_address} in the exception 23669handling tables. You need to do this because the stub does not have any 23670way of knowing what the exception handling tables on your target system 23671are like (for example, the processor's table might be in @sc{rom}, 23672containing entries which point to a table in @sc{ram}). 23673The @var{exception_number} specifies the exception which should be changed; 23674its meaning is architecture-dependent (for example, different numbers 23675might represent divide by zero, misaligned access, etc). When this 23676exception occurs, control should be transferred directly to 23677@var{exception_address}, and the processor state (stack, registers, 23678and so on) should be just as it is when a processor exception occurs. So if 23679you want to use a jump instruction to reach @var{exception_address}, it 23680should be a simple jump, not a jump to subroutine. 23681 23682For the 386, @var{exception_address} should be installed as an interrupt 23683gate so that interrupts are masked while the handler runs. The gate 23684should be at privilege level 0 (the most privileged level). The 23685@sc{sparc} and 68k stubs are able to mask interrupts themselves without 23686help from @code{exceptionHandler}. 23687 23688@item void flush_i_cache() 23689@findex flush_i_cache 23690On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the 23691instruction cache, if any, on your target machine. If there is no 23692instruction cache, this subroutine may be a no-op. 23693 23694On target machines that have instruction caches, @value{GDBN} requires this 23695function to make certain that the state of your program is stable. 23696@end table 23697 23698@noindent 23699You must also make sure this library routine is available: 23700 23701@table @code 23702@item void *memset(void *, int, int) 23703@findex memset 23704This is the standard library function @code{memset} that sets an area of 23705memory to a known value. If you have one of the free versions of 23706@code{libc.a}, @code{memset} can be found there; otherwise, you must 23707either obtain it from your hardware manufacturer, or write your own. 23708@end table 23709 23710If you do not use the GNU C compiler, you may need other standard 23711library subroutines as well; this varies from one stub to another, 23712but in general the stubs are likely to use any of the common library 23713subroutines which @code{@value{NGCC}} generates as inline code. 23714 23715 23716@node Debug Session 23717@subsection Putting it All Together 23718 23719@cindex remote serial debugging summary 23720In summary, when your program is ready to debug, you must follow these 23721steps. 23722 23723@enumerate 23724@item 23725Make sure you have defined the supporting low-level routines 23726(@pxref{Bootstrapping,,What You Must Do for the Stub}): 23727@display 23728@code{getDebugChar}, @code{putDebugChar}, 23729@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}. 23730@end display 23731 23732@item 23733Insert these lines in your program's startup code, before the main 23734procedure is called: 23735 23736@smallexample 23737set_debug_traps(); 23738breakpoint(); 23739@end smallexample 23740 23741On some machines, when a breakpoint trap is raised, the hardware 23742automatically makes the PC point to the instruction after the 23743breakpoint. If your machine doesn't do that, you may need to adjust 23744@code{handle_exception} to arrange for it to return to the instruction 23745after the breakpoint on this first invocation, so that your program 23746doesn't keep hitting the initial breakpoint instead of making 23747progress. 23748 23749@item 23750For the 680x0 stub only, you need to provide a variable called 23751@code{exceptionHook}. Normally you just use: 23752 23753@smallexample 23754void (*exceptionHook)() = 0; 23755@end smallexample 23756 23757@noindent 23758but if before calling @code{set_debug_traps}, you set it to point to a 23759function in your program, that function is called when 23760@code{@value{GDBN}} continues after stopping on a trap (for example, bus 23761error). The function indicated by @code{exceptionHook} is called with 23762one parameter: an @code{int} which is the exception number. 23763 23764@item 23765Compile and link together: your program, the @value{GDBN} debugging stub for 23766your target architecture, and the supporting subroutines. 23767 23768@item 23769Make sure you have a serial connection between your target machine and 23770the @value{GDBN} host, and identify the serial port on the host. 23771 23772@item 23773@c The "remote" target now provides a `load' command, so we should 23774@c document that. FIXME. 23775Download your program to your target machine (or get it there by 23776whatever means the manufacturer provides), and start it. 23777 23778@item 23779Start @value{GDBN} on the host, and connect to the target 23780(@pxref{Connecting,,Connecting to a Remote Target}). 23781 23782@end enumerate 23783 23784@node Configurations 23785@chapter Configuration-Specific Information 23786 23787While nearly all @value{GDBN} commands are available for all native and 23788cross versions of the debugger, there are some exceptions. This chapter 23789describes things that are only available in certain configurations. 23790 23791There are three major categories of configurations: native 23792configurations, where the host and target are the same, embedded 23793operating system configurations, which are usually the same for several 23794different processor architectures, and bare embedded processors, which 23795are quite different from each other. 23796 23797@menu 23798* Native:: 23799* Embedded OS:: 23800* Embedded Processors:: 23801* Architectures:: 23802@end menu 23803 23804@node Native 23805@section Native 23806 23807This section describes details specific to particular native 23808configurations. 23809 23810@menu 23811* BSD libkvm Interface:: Debugging BSD kernel memory images 23812* Process Information:: Process information 23813* DJGPP Native:: Features specific to the DJGPP port 23814* Cygwin Native:: Features specific to the Cygwin port 23815* Hurd Native:: Features specific to @sc{gnu} Hurd 23816* Darwin:: Features specific to Darwin 23817* FreeBSD:: Features specific to FreeBSD 23818@end menu 23819 23820@node BSD libkvm Interface 23821@subsection BSD libkvm Interface 23822 23823@cindex libkvm 23824@cindex kernel memory image 23825@cindex kernel crash dump 23826 23827BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory 23828interface that provides a uniform interface for accessing kernel virtual 23829memory images, including live systems and crash dumps. @value{GDBN} 23830uses this interface to allow you to debug live kernels and kernel crash 23831dumps on many native BSD configurations. This is implemented as a 23832special @code{kvm} debugging target. For debugging a live system, load 23833the currently running kernel into @value{GDBN} and connect to the 23834@code{kvm} target: 23835 23836@smallexample 23837(@value{GDBP}) @b{target kvm} 23838@end smallexample 23839 23840For debugging crash dumps, provide the file name of the crash dump as an 23841argument: 23842 23843@smallexample 23844(@value{GDBP}) @b{target kvm /var/crash/bsd.0} 23845@end smallexample 23846 23847Once connected to the @code{kvm} target, the following commands are 23848available: 23849 23850@table @code 23851@kindex kvm 23852@item kvm pcb 23853Set current context from the @dfn{Process Control Block} (PCB) address. 23854 23855@item kvm proc 23856Set current context from proc address. This command isn't available on 23857modern FreeBSD systems. 23858@end table 23859 23860@node Process Information 23861@subsection Process Information 23862@cindex /proc 23863@cindex examine process image 23864@cindex process info via @file{/proc} 23865 23866Some operating systems provide interfaces to fetch additional 23867information about running processes beyond memory and per-thread 23868register state. If @value{GDBN} is configured for an operating system 23869with a supported interface, the command @code{info proc} is available 23870to report information about the process running your program, or about 23871any process running on your system. 23872 23873One supported interface is a facility called @samp{/proc} that can be 23874used to examine the image of a running process using file-system 23875subroutines. This facility is supported on @sc{gnu}/Linux and Solaris 23876systems. 23877 23878On FreeBSD and NetBSD systems, system control nodes are used to query 23879process information. 23880 23881In addition, some systems may provide additional process information 23882in core files. Note that a core file may include a subset of the 23883information available from a live process. Process information is 23884currently available from cores created on @sc{gnu}/Linux and FreeBSD 23885systems. 23886 23887@table @code 23888@kindex info proc 23889@cindex process ID 23890@item info proc 23891@itemx info proc @var{process-id} 23892Summarize available information about a process. If a 23893process ID is specified by @var{process-id}, display information about 23894that process; otherwise display information about the program being 23895debugged. The summary includes the debugged process ID, the command 23896line used to invoke it, its current working directory, and its 23897executable file's absolute file name. 23898 23899On some systems, @var{process-id} can be of the form 23900@samp{[@var{pid}]/@var{tid}} which specifies a certain thread ID 23901within a process. If the optional @var{pid} part is missing, it means 23902a thread from the process being debugged (the leading @samp{/} still 23903needs to be present, or else @value{GDBN} will interpret the number as 23904a process ID rather than a thread ID). 23905 23906@item info proc cmdline 23907@cindex info proc cmdline 23908Show the original command line of the process. This command is 23909supported on @sc{gnu}/Linux, FreeBSD and NetBSD. 23910 23911@item info proc cwd 23912@cindex info proc cwd 23913Show the current working directory of the process. This command is 23914supported on @sc{gnu}/Linux, FreeBSD and NetBSD. 23915 23916@item info proc exe 23917@cindex info proc exe 23918Show the name of executable of the process. This command is supported 23919on @sc{gnu}/Linux, FreeBSD and NetBSD. 23920 23921@item info proc files 23922@cindex info proc files 23923Show the file descriptors open by the process. For each open file 23924descriptor, @value{GDBN} shows its number, type (file, directory, 23925character device, socket), file pointer offset, and the name of the 23926resource open on the descriptor. The resource name can be a file name 23927(for files, directories, and devices) or a protocol followed by socket 23928address (for network connections). This command is supported on 23929FreeBSD. 23930 23931This example shows the open file descriptors for a process using a 23932tty for standard input and output as well as two network sockets: 23933 23934@smallexample 23935(gdb) info proc files 22136 23936process 22136 23937Open files: 23938 23939 FD Type Offset Flags Name 23940 text file - r-------- /usr/bin/ssh 23941 ctty chr - rw------- /dev/pts/20 23942 cwd dir - r-------- /usr/home/john 23943 root dir - r-------- / 23944 0 chr 0x32933a4 rw------- /dev/pts/20 23945 1 chr 0x32933a4 rw------- /dev/pts/20 23946 2 chr 0x32933a4 rw------- /dev/pts/20 23947 3 socket 0x0 rw----n-- tcp4 10.0.1.2:53014 -> 10.0.1.10:22 23948 4 socket 0x0 rw------- unix stream:/tmp/ssh-FIt89oAzOn5f/agent.2456 23949@end smallexample 23950 23951@item info proc mappings 23952@cindex memory address space mappings 23953Report the memory address space ranges accessible in a process. On 23954Solaris, FreeBSD and NetBSD systems, each memory range includes information 23955on whether the process has read, write, or execute access rights to each 23956range. On @sc{gnu}/Linux, FreeBSD and NetBSD systems, each memory range 23957includes the object file which is mapped to that range. 23958 23959@item info proc stat 23960@itemx info proc status 23961@cindex process detailed status information 23962Show additional process-related information, including the user ID and 23963group ID; virtual memory usage; the signals that are pending, blocked, 23964and ignored; its TTY; its consumption of system and user time; its 23965stack size; its @samp{nice} value; etc. These commands are supported 23966on @sc{gnu}/Linux, FreeBSD and NetBSD. 23967 23968For @sc{gnu}/Linux systems, see the @samp{proc} man page for more 23969information (type @kbd{man 5 proc} from your shell prompt). 23970 23971For FreeBSD and NetBSD systems, @code{info proc stat} is an alias for 23972@code{info proc status}. 23973 23974@item info proc all 23975Show all the information about the process described under all of the 23976above @code{info proc} subcommands. 23977 23978@ignore 23979@comment These sub-options of 'info proc' were not included when 23980@comment procfs.c was re-written. Keep their descriptions around 23981@comment against the day when someone finds the time to put them back in. 23982@kindex info proc times 23983@item info proc times 23984Starting time, user CPU time, and system CPU time for your program and 23985its children. 23986 23987@kindex info proc id 23988@item info proc id 23989Report on the process IDs related to your program: its own process ID, 23990the ID of its parent, the process group ID, and the session ID. 23991@end ignore 23992 23993@item set procfs-trace 23994@kindex set procfs-trace 23995@cindex @code{procfs} API calls 23996This command enables and disables tracing of @code{procfs} API calls. 23997 23998@item show procfs-trace 23999@kindex show procfs-trace 24000Show the current state of @code{procfs} API call tracing. 24001 24002@item set procfs-file @var{file} 24003@kindex set procfs-file 24004Tell @value{GDBN} to write @code{procfs} API trace to the named 24005@var{file}. @value{GDBN} appends the trace info to the previous 24006contents of the file. The default is to display the trace on the 24007standard output. 24008 24009@item show procfs-file 24010@kindex show procfs-file 24011Show the file to which @code{procfs} API trace is written. 24012 24013@item proc-trace-entry 24014@itemx proc-trace-exit 24015@itemx proc-untrace-entry 24016@itemx proc-untrace-exit 24017@kindex proc-trace-entry 24018@kindex proc-trace-exit 24019@kindex proc-untrace-entry 24020@kindex proc-untrace-exit 24021These commands enable and disable tracing of entries into and exits 24022from the @code{syscall} interface. 24023 24024@item info pidlist 24025@kindex info pidlist 24026@cindex process list, QNX Neutrino 24027For QNX Neutrino only, this command displays the list of all the 24028processes and all the threads within each process. 24029 24030@item info meminfo 24031@kindex info meminfo 24032@cindex mapinfo list, QNX Neutrino 24033For QNX Neutrino only, this command displays the list of all mapinfos. 24034@end table 24035 24036@node DJGPP Native 24037@subsection Features for Debugging @sc{djgpp} Programs 24038@cindex @sc{djgpp} debugging 24039@cindex native @sc{djgpp} debugging 24040@cindex MS-DOS-specific commands 24041 24042@cindex DPMI 24043@sc{djgpp} is a port of the @sc{gnu} development tools to MS-DOS and 24044MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs 24045that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on 24046top of real-mode DOS systems and their emulations. 24047 24048@value{GDBN} supports native debugging of @sc{djgpp} programs, and 24049defines a few commands specific to the @sc{djgpp} port. This 24050subsection describes those commands. 24051 24052@table @code 24053@kindex info dos 24054@item info dos 24055This is a prefix of @sc{djgpp}-specific commands which print 24056information about the target system and important OS structures. 24057 24058@kindex sysinfo 24059@cindex MS-DOS system info 24060@cindex free memory information (MS-DOS) 24061@item info dos sysinfo 24062This command displays assorted information about the underlying 24063platform: the CPU type and features, the OS version and flavor, the 24064DPMI version, and the available conventional and DPMI memory. 24065 24066@cindex GDT 24067@cindex LDT 24068@cindex IDT 24069@cindex segment descriptor tables 24070@cindex descriptor tables display 24071@item info dos gdt 24072@itemx info dos ldt 24073@itemx info dos idt 24074These 3 commands display entries from, respectively, Global, Local, 24075and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor 24076tables are data structures which store a descriptor for each segment 24077that is currently in use. The segment's selector is an index into a 24078descriptor table; the table entry for that index holds the 24079descriptor's base address and limit, and its attributes and access 24080rights. 24081 24082A typical @sc{djgpp} program uses 3 segments: a code segment, a data 24083segment (used for both data and the stack), and a DOS segment (which 24084allows access to DOS/BIOS data structures and absolute addresses in 24085conventional memory). However, the DPMI host will usually define 24086additional segments in order to support the DPMI environment. 24087 24088@cindex garbled pointers 24089These commands allow to display entries from the descriptor tables. 24090Without an argument, all entries from the specified table are 24091displayed. An argument, which should be an integer expression, means 24092display a single entry whose index is given by the argument. For 24093example, here's a convenient way to display information about the 24094debugged program's data segment: 24095 24096@smallexample 24097@exdent @code{(@value{GDBP}) info dos ldt $ds} 24098@exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)} 24099@end smallexample 24100 24101@noindent 24102This comes in handy when you want to see whether a pointer is outside 24103the data segment's limit (i.e.@: @dfn{garbled}). 24104 24105@cindex page tables display (MS-DOS) 24106@item info dos pde 24107@itemx info dos pte 24108These two commands display entries from, respectively, the Page 24109Directory and the Page Tables. Page Directories and Page Tables are 24110data structures which control how virtual memory addresses are mapped 24111into physical addresses. A Page Table includes an entry for every 24112page of memory that is mapped into the program's address space; there 24113may be several Page Tables, each one holding up to 4096 entries. A 24114Page Directory has up to 4096 entries, one each for every Page Table 24115that is currently in use. 24116 24117Without an argument, @kbd{info dos pde} displays the entire Page 24118Directory, and @kbd{info dos pte} displays all the entries in all of 24119the Page Tables. An argument, an integer expression, given to the 24120@kbd{info dos pde} command means display only that entry from the Page 24121Directory table. An argument given to the @kbd{info dos pte} command 24122means display entries from a single Page Table, the one pointed to by 24123the specified entry in the Page Directory. 24124 24125@cindex direct memory access (DMA) on MS-DOS 24126These commands are useful when your program uses @dfn{DMA} (Direct 24127Memory Access), which needs physical addresses to program the DMA 24128controller. 24129 24130These commands are supported only with some DPMI servers. 24131 24132@cindex physical address from linear address 24133@item info dos address-pte @var{addr} 24134This command displays the Page Table entry for a specified linear 24135address. The argument @var{addr} is a linear address which should 24136already have the appropriate segment's base address added to it, 24137because this command accepts addresses which may belong to @emph{any} 24138segment. For example, here's how to display the Page Table entry for 24139the page where a variable @code{i} is stored: 24140 24141@smallexample 24142@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i} 24143@exdent @code{Page Table entry for address 0x11a00d30:} 24144@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30} 24145@end smallexample 24146 24147@noindent 24148This says that @code{i} is stored at offset @code{0xd30} from the page 24149whose physical base address is @code{0x02698000}, and shows all the 24150attributes of that page. 24151 24152Note that you must cast the addresses of variables to a @code{char *}, 24153since otherwise the value of @code{__djgpp_base_address}, the base 24154address of all variables and functions in a @sc{djgpp} program, will 24155be added using the rules of C pointer arithmetics: if @code{i} is 24156declared an @code{int}, @value{GDBN} will add 4 times the value of 24157@code{__djgpp_base_address} to the address of @code{i}. 24158 24159Here's another example, it displays the Page Table entry for the 24160transfer buffer: 24161 24162@smallexample 24163@exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)} 24164@exdent @code{Page Table entry for address 0x29110:} 24165@exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110} 24166@end smallexample 24167 24168@noindent 24169(The @code{+ 3} offset is because the transfer buffer's address is the 241703rd member of the @code{_go32_info_block} structure.) The output 24171clearly shows that this DPMI server maps the addresses in conventional 24172memory 1:1, i.e.@: the physical (@code{0x00029000} + @code{0x110}) and 24173linear (@code{0x29110}) addresses are identical. 24174 24175This command is supported only with some DPMI servers. 24176@end table 24177 24178@cindex DOS serial data link, remote debugging 24179In addition to native debugging, the DJGPP port supports remote 24180debugging via a serial data link. The following commands are specific 24181to remote serial debugging in the DJGPP port of @value{GDBN}. 24182 24183@table @code 24184@kindex set com1base 24185@kindex set com1irq 24186@kindex set com2base 24187@kindex set com2irq 24188@kindex set com3base 24189@kindex set com3irq 24190@kindex set com4base 24191@kindex set com4irq 24192@item set com1base @var{addr} 24193This command sets the base I/O port address of the @file{COM1} serial 24194port. 24195 24196@item set com1irq @var{irq} 24197This command sets the @dfn{Interrupt Request} (@code{IRQ}) line to use 24198for the @file{COM1} serial port. 24199 24200There are similar commands @samp{set com2base}, @samp{set com3irq}, 24201etc.@: for setting the port address and the @code{IRQ} lines for the 24202other 3 COM ports. 24203 24204@kindex show com1base 24205@kindex show com1irq 24206@kindex show com2base 24207@kindex show com2irq 24208@kindex show com3base 24209@kindex show com3irq 24210@kindex show com4base 24211@kindex show com4irq 24212The related commands @samp{show com1base}, @samp{show com1irq} etc.@: 24213display the current settings of the base address and the @code{IRQ} 24214lines used by the COM ports. 24215 24216@item info serial 24217@kindex info serial 24218@cindex DOS serial port status 24219This command prints the status of the 4 DOS serial ports. For each 24220port, it prints whether it's active or not, its I/O base address and 24221IRQ number, whether it uses a 16550-style FIFO, its baudrate, and the 24222counts of various errors encountered so far. 24223@end table 24224 24225 24226@node Cygwin Native 24227@subsection Features for Debugging MS Windows PE Executables 24228@cindex MS Windows debugging 24229@cindex native Cygwin debugging 24230@cindex Cygwin-specific commands 24231 24232@value{GDBN} supports native debugging of MS Windows programs, including 24233DLLs with and without symbolic debugging information. 24234 24235@cindex Ctrl-BREAK, MS-Windows 24236@cindex interrupt debuggee on MS-Windows 24237MS-Windows programs that call @code{SetConsoleMode} to switch off the 24238special meaning of the @samp{Ctrl-C} keystroke cannot be interrupted 24239by typing @kbd{C-c}. For this reason, @value{GDBN} on MS-Windows 24240supports @kbd{C-@key{BREAK}} as an alternative interrupt key 24241sequence, which can be used to interrupt the debuggee even if it 24242ignores @kbd{C-c}. 24243 24244There are various additional Cygwin-specific commands, described in 24245this section. Working with DLLs that have no debugging symbols is 24246described in @ref{Non-debug DLL Symbols}. 24247 24248@table @code 24249@kindex info w32 24250@item info w32 24251This is a prefix of MS Windows-specific commands which print 24252information about the target system and important OS structures. 24253 24254@item info w32 selector 24255This command displays information returned by 24256the Win32 API @code{GetThreadSelectorEntry} function. 24257It takes an optional argument that is evaluated to 24258a long value to give the information about this given selector. 24259Without argument, this command displays information 24260about the six segment registers. 24261 24262@item info w32 thread-information-block 24263This command displays thread specific information stored in the 24264Thread Information Block (readable on the X86 CPU family using @code{$fs} 24265selector for 32-bit programs and @code{$gs} for 64-bit programs). 24266 24267@kindex signal-event 24268@item signal-event @var{id} 24269This command signals an event with user-provided @var{id}. Used to resume 24270crashing process when attached to it using MS-Windows JIT debugging (AeDebug). 24271 24272To use it, create or edit the following keys in 24273@code{HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug} and/or 24274@code{HKLM\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\AeDebug} 24275(for x86_64 versions): 24276 24277@itemize @minus 24278@item 24279@code{Debugger} (REG_SZ) --- a command to launch the debugger. 24280Suggested command is: @code{@var{fully-qualified-path-to-gdb.exe} -ex 24281"attach %ld" -ex "signal-event %ld" -ex "continue"}. 24282 24283The first @code{%ld} will be replaced by the process ID of the 24284crashing process, the second @code{%ld} will be replaced by the ID of 24285the event that blocks the crashing process, waiting for @value{GDBN} 24286to attach. 24287 24288@item 24289@code{Auto} (REG_SZ) --- either @code{1} or @code{0}. @code{1} will 24290make the system run debugger specified by the Debugger key 24291automatically, @code{0} will cause a dialog box with ``OK'' and 24292``Cancel'' buttons to appear, which allows the user to either 24293terminate the crashing process (OK) or debug it (Cancel). 24294@end itemize 24295 24296@kindex set cygwin-exceptions 24297@cindex debugging the Cygwin DLL 24298@cindex Cygwin DLL, debugging 24299@item set cygwin-exceptions @var{mode} 24300If @var{mode} is @code{on}, @value{GDBN} will break on exceptions that 24301happen inside the Cygwin DLL. If @var{mode} is @code{off}, 24302@value{GDBN} will delay recognition of exceptions, and may ignore some 24303exceptions which seem to be caused by internal Cygwin DLL 24304``bookkeeping''. This option is meant primarily for debugging the 24305Cygwin DLL itself; the default value is @code{off} to avoid annoying 24306@value{GDBN} users with false @code{SIGSEGV} signals. 24307 24308@kindex show cygwin-exceptions 24309@item show cygwin-exceptions 24310Displays whether @value{GDBN} will break on exceptions that happen 24311inside the Cygwin DLL itself. 24312 24313@kindex set new-console 24314@item set new-console @var{mode} 24315If @var{mode} is @code{on} the debuggee will 24316be started in a new console on next start. 24317If @var{mode} is @code{off}, the debuggee will 24318be started in the same console as the debugger. 24319 24320@kindex show new-console 24321@item show new-console 24322Displays whether a new console is used 24323when the debuggee is started. 24324 24325@kindex set new-group 24326@item set new-group @var{mode} 24327This boolean value controls whether the debuggee should 24328start a new group or stay in the same group as the debugger. 24329This affects the way the Windows OS handles 24330@samp{Ctrl-C}. 24331 24332@kindex show new-group 24333@item show new-group 24334Displays current value of new-group boolean. 24335 24336@kindex set debugevents 24337@item set debugevents 24338This boolean value adds debug output concerning kernel events related 24339to the debuggee seen by the debugger. This includes events that 24340signal thread and process creation and exit, DLL loading and 24341unloading, console interrupts, and debugging messages produced by the 24342Windows @code{OutputDebugString} API call. 24343 24344@kindex set debugexec 24345@item set debugexec 24346This boolean value adds debug output concerning execute events 24347(such as resume thread) seen by the debugger. 24348 24349@kindex set debugexceptions 24350@item set debugexceptions 24351This boolean value adds debug output concerning exceptions in the 24352debuggee seen by the debugger. 24353 24354@kindex set debugmemory 24355@item set debugmemory 24356This boolean value adds debug output concerning debuggee memory reads 24357and writes by the debugger. 24358 24359@kindex set shell 24360@item set shell 24361This boolean values specifies whether the debuggee is called 24362via a shell or directly (default value is on). 24363 24364@kindex show shell 24365@item show shell 24366Displays if the debuggee will be started with a shell. 24367 24368@end table 24369 24370@menu 24371* Non-debug DLL Symbols:: Support for DLLs without debugging symbols 24372@end menu 24373 24374@node Non-debug DLL Symbols 24375@subsubsection Support for DLLs without Debugging Symbols 24376@cindex DLLs with no debugging symbols 24377@cindex Minimal symbols and DLLs 24378 24379Very often on windows, some of the DLLs that your program relies on do 24380not include symbolic debugging information (for example, 24381@file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging 24382symbols in a DLL, it relies on the minimal amount of symbolic 24383information contained in the DLL's export table. This section 24384describes working with such symbols, known internally to @value{GDBN} as 24385``minimal symbols''. 24386 24387Note that before the debugged program has started execution, no DLLs 24388will have been loaded. The easiest way around this problem is simply to 24389start the program --- either by setting a breakpoint or letting the 24390program run once to completion. 24391 24392@subsubsection DLL Name Prefixes 24393 24394In keeping with the naming conventions used by the Microsoft debugging 24395tools, DLL export symbols are made available with a prefix based on the 24396DLL name, for instance @code{KERNEL32!CreateFileA}. The plain name is 24397also entered into the symbol table, so @code{CreateFileA} is often 24398sufficient. In some cases there will be name clashes within a program 24399(particularly if the executable itself includes full debugging symbols) 24400necessitating the use of the fully qualified name when referring to the 24401contents of the DLL. Use single-quotes around the name to avoid the 24402exclamation mark (``!'') being interpreted as a language operator. 24403 24404Note that the internal name of the DLL may be all upper-case, even 24405though the file name of the DLL is lower-case, or vice-versa. Since 24406symbols within @value{GDBN} are @emph{case-sensitive} this may cause 24407some confusion. If in doubt, try the @code{info functions} and 24408@code{info variables} commands or even @code{maint print msymbols} 24409(@pxref{Symbols}). Here's an example: 24410 24411@smallexample 24412(@value{GDBP}) info function CreateFileA 24413All functions matching regular expression "CreateFileA": 24414 24415Non-debugging symbols: 244160x77e885f4 CreateFileA 244170x77e885f4 KERNEL32!CreateFileA 24418@end smallexample 24419 24420@smallexample 24421(@value{GDBP}) info function ! 24422All functions matching regular expression "!": 24423 24424Non-debugging symbols: 244250x6100114c cygwin1!__assert 244260x61004034 cygwin1!_dll_crt0@@0 244270x61004240 cygwin1!dll_crt0(per_process *) 24428[etc...] 24429@end smallexample 24430 24431@subsubsection Working with Minimal Symbols 24432 24433Symbols extracted from a DLL's export table do not contain very much 24434type information. All that @value{GDBN} can do is guess whether a symbol 24435refers to a function or variable depending on the linker section that 24436contains the symbol. Also note that the actual contents of the memory 24437contained in a DLL are not available unless the program is running. This 24438means that you cannot examine the contents of a variable or disassemble 24439a function within a DLL without a running program. 24440 24441Variables are generally treated as pointers and dereferenced 24442automatically. For this reason, it is often necessary to prefix a 24443variable name with the address-of operator (``&'') and provide explicit 24444type information in the command. Here's an example of the type of 24445problem: 24446 24447@smallexample 24448(@value{GDBP}) print 'cygwin1!__argv' 24449'cygwin1!__argv' has unknown type; cast it to its declared type 24450@end smallexample 24451 24452@smallexample 24453(@value{GDBP}) x 'cygwin1!__argv' 24454'cygwin1!__argv' has unknown type; cast it to its declared type 24455@end smallexample 24456 24457And two possible solutions: 24458 24459@smallexample 24460(@value{GDBP}) print ((char **)'cygwin1!__argv')[0] 24461$2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" 24462@end smallexample 24463 24464@smallexample 24465(@value{GDBP}) x/2x &'cygwin1!__argv' 244660x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000 24467(@value{GDBP}) x/x 0x10021608 244680x10021608: 0x0022fd98 24469(@value{GDBP}) x/s 0x0022fd98 244700x22fd98: "/cygdrive/c/mydirectory/myprogram" 24471@end smallexample 24472 24473Setting a break point within a DLL is possible even before the program 24474starts execution. However, under these circumstances, @value{GDBN} can't 24475examine the initial instructions of the function in order to skip the 24476function's frame set-up code. You can work around this by using ``*&'' 24477to set the breakpoint at a raw memory address: 24478 24479@smallexample 24480(@value{GDBP}) break *&'python22!PyOS_Readline' 24481Breakpoint 1 at 0x1e04eff0 24482@end smallexample 24483 24484The author of these extensions is not entirely convinced that setting a 24485break point within a shared DLL like @file{kernel32.dll} is completely 24486safe. 24487 24488@node Hurd Native 24489@subsection Commands Specific to @sc{gnu} Hurd Systems 24490@cindex @sc{gnu} Hurd debugging 24491 24492This subsection describes @value{GDBN} commands specific to the 24493@sc{gnu} Hurd native debugging. 24494 24495@table @code 24496@item set signals 24497@itemx set sigs 24498@kindex set signals@r{, Hurd command} 24499@kindex set sigs@r{, Hurd command} 24500This command toggles the state of inferior signal interception by 24501@value{GDBN}. Mach exceptions, such as breakpoint traps, are not 24502affected by this command. @code{sigs} is a shorthand alias for 24503@code{signals}. 24504 24505@item show signals 24506@itemx show sigs 24507@kindex show signals@r{, Hurd command} 24508@kindex show sigs@r{, Hurd command} 24509Show the current state of intercepting inferior's signals. 24510 24511@item set signal-thread 24512@itemx set sigthread 24513@kindex set signal-thread 24514@kindex set sigthread 24515This command tells @value{GDBN} which thread is the @code{libc} signal 24516thread. That thread is run when a signal is delivered to a running 24517process. @code{set sigthread} is the shorthand alias of @code{set 24518signal-thread}. 24519 24520@item show signal-thread 24521@itemx show sigthread 24522@kindex show signal-thread 24523@kindex show sigthread 24524These two commands show which thread will run when the inferior is 24525delivered a signal. 24526 24527@item set stopped 24528@kindex set stopped@r{, Hurd command} 24529This commands tells @value{GDBN} that the inferior process is stopped, 24530as with the @code{SIGSTOP} signal. The stopped process can be 24531continued by delivering a signal to it. 24532 24533@item show stopped 24534@kindex show stopped@r{, Hurd command} 24535This command shows whether @value{GDBN} thinks the debuggee is 24536stopped. 24537 24538@item set exceptions 24539@kindex set exceptions@r{, Hurd command} 24540Use this command to turn off trapping of exceptions in the inferior. 24541When exception trapping is off, neither breakpoints nor 24542single-stepping will work. To restore the default, set exception 24543trapping on. 24544 24545@item show exceptions 24546@kindex show exceptions@r{, Hurd command} 24547Show the current state of trapping exceptions in the inferior. 24548 24549@item set task pause 24550@kindex set task@r{, Hurd commands} 24551@cindex task attributes (@sc{gnu} Hurd) 24552@cindex pause current task (@sc{gnu} Hurd) 24553This command toggles task suspension when @value{GDBN} has control. 24554Setting it to on takes effect immediately, and the task is suspended 24555whenever @value{GDBN} gets control. Setting it to off will take 24556effect the next time the inferior is continued. If this option is set 24557to off, you can use @code{set thread default pause on} or @code{set 24558thread pause on} (see below) to pause individual threads. 24559 24560@item show task pause 24561@kindex show task@r{, Hurd commands} 24562Show the current state of task suspension. 24563 24564@item set task detach-suspend-count 24565@cindex task suspend count 24566@cindex detach from task, @sc{gnu} Hurd 24567This command sets the suspend count the task will be left with when 24568@value{GDBN} detaches from it. 24569 24570@item show task detach-suspend-count 24571Show the suspend count the task will be left with when detaching. 24572 24573@item set task exception-port 24574@itemx set task excp 24575@cindex task exception port, @sc{gnu} Hurd 24576This command sets the task exception port to which @value{GDBN} will 24577forward exceptions. The argument should be the value of the @dfn{send 24578rights} of the task. @code{set task excp} is a shorthand alias. 24579 24580@item set noninvasive 24581@cindex noninvasive task options 24582This command switches @value{GDBN} to a mode that is the least 24583invasive as far as interfering with the inferior is concerned. This 24584is the same as using @code{set task pause}, @code{set exceptions}, and 24585@code{set signals} to values opposite to the defaults. 24586 24587@item info send-rights 24588@itemx info receive-rights 24589@itemx info port-rights 24590@itemx info port-sets 24591@itemx info dead-names 24592@itemx info ports 24593@itemx info psets 24594@cindex send rights, @sc{gnu} Hurd 24595@cindex receive rights, @sc{gnu} Hurd 24596@cindex port rights, @sc{gnu} Hurd 24597@cindex port sets, @sc{gnu} Hurd 24598@cindex dead names, @sc{gnu} Hurd 24599These commands display information about, respectively, send rights, 24600receive rights, port rights, port sets, and dead names of a task. 24601There are also shorthand aliases: @code{info ports} for @code{info 24602port-rights} and @code{info psets} for @code{info port-sets}. 24603 24604@item set thread pause 24605@kindex set thread@r{, Hurd command} 24606@cindex thread properties, @sc{gnu} Hurd 24607@cindex pause current thread (@sc{gnu} Hurd) 24608This command toggles current thread suspension when @value{GDBN} has 24609control. Setting it to on takes effect immediately, and the current 24610thread is suspended whenever @value{GDBN} gets control. Setting it to 24611off will take effect the next time the inferior is continued. 24612Normally, this command has no effect, since when @value{GDBN} has 24613control, the whole task is suspended. However, if you used @code{set 24614task pause off} (see above), this command comes in handy to suspend 24615only the current thread. 24616 24617@item show thread pause 24618@kindex show thread@r{, Hurd command} 24619This command shows the state of current thread suspension. 24620 24621@item set thread run 24622This command sets whether the current thread is allowed to run. 24623 24624@item show thread run 24625Show whether the current thread is allowed to run. 24626 24627@item set thread detach-suspend-count 24628@cindex thread suspend count, @sc{gnu} Hurd 24629@cindex detach from thread, @sc{gnu} Hurd 24630This command sets the suspend count @value{GDBN} will leave on a 24631thread when detaching. This number is relative to the suspend count 24632found by @value{GDBN} when it notices the thread; use @code{set thread 24633takeover-suspend-count} to force it to an absolute value. 24634 24635@item show thread detach-suspend-count 24636Show the suspend count @value{GDBN} will leave on the thread when 24637detaching. 24638 24639@item set thread exception-port 24640@itemx set thread excp 24641Set the thread exception port to which to forward exceptions. This 24642overrides the port set by @code{set task exception-port} (see above). 24643@code{set thread excp} is the shorthand alias. 24644 24645@item set thread takeover-suspend-count 24646Normally, @value{GDBN}'s thread suspend counts are relative to the 24647value @value{GDBN} finds when it notices each thread. This command 24648changes the suspend counts to be absolute instead. 24649 24650@item set thread default 24651@itemx show thread default 24652@cindex thread default settings, @sc{gnu} Hurd 24653Each of the above @code{set thread} commands has a @code{set thread 24654default} counterpart (e.g., @code{set thread default pause}, @code{set 24655thread default exception-port}, etc.). The @code{thread default} 24656variety of commands sets the default thread properties for all 24657threads; you can then change the properties of individual threads with 24658the non-default commands. 24659@end table 24660 24661@node Darwin 24662@subsection Darwin 24663@cindex Darwin 24664 24665@value{GDBN} provides the following commands specific to the Darwin target: 24666 24667@table @code 24668@item set debug darwin @var{num} 24669@kindex set debug darwin 24670When set to a non zero value, enables debugging messages specific to 24671the Darwin support. Higher values produce more verbose output. 24672 24673@item show debug darwin 24674@kindex show debug darwin 24675Show the current state of Darwin messages. 24676 24677@item set debug mach-o @var{num} 24678@kindex set debug mach-o 24679When set to a non zero value, enables debugging messages while 24680@value{GDBN} is reading Darwin object files. (@dfn{Mach-O} is the 24681file format used on Darwin for object and executable files.) Higher 24682values produce more verbose output. This is a command to diagnose 24683problems internal to @value{GDBN} and should not be needed in normal 24684usage. 24685 24686@item show debug mach-o 24687@kindex show debug mach-o 24688Show the current state of Mach-O file messages. 24689 24690@item set mach-exceptions on 24691@itemx set mach-exceptions off 24692@kindex set mach-exceptions 24693On Darwin, faults are first reported as a Mach exception and are then 24694mapped to a Posix signal. Use this command to turn on trapping of 24695Mach exceptions in the inferior. This might be sometimes useful to 24696better understand the cause of a fault. The default is off. 24697 24698@item show mach-exceptions 24699@kindex show mach-exceptions 24700Show the current state of exceptions trapping. 24701@end table 24702 24703@node FreeBSD 24704@subsection FreeBSD 24705@cindex FreeBSD 24706 24707When the ABI of a system call is changed in the FreeBSD kernel, this 24708is implemented by leaving a compatibility system call using the old 24709ABI at the existing number and allocating a new system call number for 24710the version using the new ABI. As a convenience, when a system call 24711is caught by name (@pxref{catch syscall}), compatibility system calls 24712are also caught. 24713 24714For example, FreeBSD 12 introduced a new variant of the @code{kevent} 24715system call and catching the @code{kevent} system call by name catches 24716both variants: 24717 24718@smallexample 24719(@value{GDBP}) catch syscall kevent 24720Catchpoint 1 (syscalls 'freebsd11_kevent' [363] 'kevent' [560]) 24721(@value{GDBP}) 24722@end smallexample 24723 24724 24725@node Embedded OS 24726@section Embedded Operating Systems 24727 24728This section describes configurations involving the debugging of 24729embedded operating systems that are available for several different 24730architectures. 24731 24732@value{GDBN} includes the ability to debug programs running on 24733various real-time operating systems. 24734 24735@node Embedded Processors 24736@section Embedded Processors 24737 24738This section goes into details specific to particular embedded 24739configurations. 24740 24741@cindex send command to simulator 24742Whenever a specific embedded processor has a simulator, @value{GDBN} 24743allows to send an arbitrary command to the simulator. 24744 24745@table @code 24746@item sim @var{command} 24747@kindex sim@r{, a command} 24748Send an arbitrary @var{command} string to the simulator. Consult the 24749documentation for the specific simulator in use for information about 24750acceptable commands. 24751@end table 24752 24753 24754@menu 24755* ARC:: Synopsys ARC 24756* ARM:: ARM 24757* BPF:: eBPF 24758* M68K:: Motorola M68K 24759* MicroBlaze:: Xilinx MicroBlaze 24760* MIPS Embedded:: MIPS Embedded 24761* OpenRISC 1000:: OpenRISC 1000 (or1k) 24762* PowerPC Embedded:: PowerPC Embedded 24763* AVR:: Atmel AVR 24764* CRIS:: CRIS 24765* Super-H:: Renesas Super-H 24766@end menu 24767 24768@node ARC 24769@subsection Synopsys ARC 24770@cindex Synopsys ARC 24771@cindex ARC specific commands 24772@cindex ARC600 24773@cindex ARC700 24774@cindex ARC EM 24775@cindex ARC HS 24776 24777@value{GDBN} provides the following ARC-specific commands: 24778 24779@table @code 24780@item set debug arc 24781@kindex set debug arc 24782Control the level of ARC specific debug messages. Use 0 for no messages (the 24783default), 1 for debug messages, and 2 for even more debug messages. 24784 24785@item show debug arc 24786@kindex show debug arc 24787Show the level of ARC specific debugging in operation. 24788 24789@item maint print arc arc-instruction @var{address} 24790@kindex maint print arc arc-instruction 24791Print internal disassembler information about instruction at a given address. 24792 24793@end table 24794 24795@node ARM 24796@subsection ARM 24797 24798@value{GDBN} provides the following ARM-specific commands: 24799 24800@table @code 24801@item set arm disassembler 24802@kindex set arm 24803This commands selects from a list of disassembly styles. The 24804@code{"std"} style is the standard style. 24805 24806@item show arm disassembler 24807@kindex show arm 24808Show the current disassembly style. 24809 24810@item set arm apcs32 24811@cindex ARM 32-bit mode 24812This command toggles ARM operation mode between 32-bit and 26-bit. 24813 24814@item show arm apcs32 24815Display the current usage of the ARM 32-bit mode. 24816 24817@item set arm fpu @var{fputype} 24818This command sets the ARM floating-point unit (FPU) type. The 24819argument @var{fputype} can be one of these: 24820 24821@table @code 24822@item auto 24823Determine the FPU type by querying the OS ABI. 24824@item softfpa 24825Software FPU, with mixed-endian doubles on little-endian ARM 24826processors. 24827@item fpa 24828GCC-compiled FPA co-processor. 24829@item softvfp 24830Software FPU with pure-endian doubles. 24831@item vfp 24832VFP co-processor. 24833@end table 24834 24835@item show arm fpu 24836Show the current type of the FPU. 24837 24838@item set arm abi 24839This command forces @value{GDBN} to use the specified ABI. 24840 24841@item show arm abi 24842Show the currently used ABI. 24843 24844@item set arm fallback-mode (arm|thumb|auto) 24845@value{GDBN} uses the symbol table, when available, to determine 24846whether instructions are ARM or Thumb. This command controls 24847@value{GDBN}'s default behavior when the symbol table is not 24848available. The default is @samp{auto}, which causes @value{GDBN} to 24849use the current execution mode (from the @code{T} bit in the @code{CPSR} 24850register). 24851 24852@item show arm fallback-mode 24853Show the current fallback instruction mode. 24854 24855@item set arm force-mode (arm|thumb|auto) 24856This command overrides use of the symbol table to determine whether 24857instructions are ARM or Thumb. The default is @samp{auto}, which 24858causes @value{GDBN} to use the symbol table and then the setting 24859of @samp{set arm fallback-mode}. 24860 24861@item show arm force-mode 24862Show the current forced instruction mode. 24863 24864@item set debug arm 24865Toggle whether to display ARM-specific debugging messages from the ARM 24866target support subsystem. 24867 24868@item show debug arm 24869Show whether ARM-specific debugging messages are enabled. 24870@end table 24871 24872@table @code 24873@item target sim @r{[}@var{simargs}@r{]} @dots{} 24874The @value{GDBN} ARM simulator accepts the following optional arguments. 24875 24876@table @code 24877@item --swi-support=@var{type} 24878Tell the simulator which SWI interfaces to support. The argument 24879@var{type} may be a comma separated list of the following values. 24880The default value is @code{all}. 24881 24882@table @code 24883@item none 24884@item demon 24885@item angel 24886@item redboot 24887@item all 24888@end table 24889@end table 24890@end table 24891 24892@node BPF 24893@subsection BPF 24894 24895@table @code 24896@item target sim @r{[}@var{simargs}@r{]} @dots{} 24897The @value{GDBN} BPF simulator accepts the following optional arguments. 24898 24899@table @code 24900@item --skb-data-offset=@var{offset} 24901Tell the simulator the offset, measured in bytes, of the 24902@code{skb_data} field in the kernel @code{struct sk_buff} structure. 24903This offset is used by some BPF specific-purpose load/store 24904instructions. Defaults to 0. 24905@end table 24906@end table 24907 24908@node M68K 24909@subsection M68k 24910 24911The Motorola m68k configuration includes ColdFire support. 24912 24913@node MicroBlaze 24914@subsection MicroBlaze 24915@cindex Xilinx MicroBlaze 24916@cindex XMD, Xilinx Microprocessor Debugger 24917 24918The MicroBlaze is a soft-core processor supported on various Xilinx 24919FPGAs, such as Spartan or Virtex series. Boards with these processors 24920usually have JTAG ports which connect to a host system running the Xilinx 24921Embedded Development Kit (EDK) or Software Development Kit (SDK). 24922This host system is used to download the configuration bitstream to 24923the target FPGA. The Xilinx Microprocessor Debugger (XMD) program 24924communicates with the target board using the JTAG interface and 24925presents a @code{gdbserver} interface to the board. By default 24926@code{xmd} uses port @code{1234}. (While it is possible to change 24927this default port, it requires the use of undocumented @code{xmd} 24928commands. Contact Xilinx support if you need to do this.) 24929 24930Use these GDB commands to connect to the MicroBlaze target processor. 24931 24932@table @code 24933@item target remote :1234 24934Use this command to connect to the target if you are running @value{GDBN} 24935on the same system as @code{xmd}. 24936 24937@item target remote @var{xmd-host}:1234 24938Use this command to connect to the target if it is connected to @code{xmd} 24939running on a different system named @var{xmd-host}. 24940 24941@item load 24942Use this command to download a program to the MicroBlaze target. 24943 24944@item set debug microblaze @var{n} 24945Enable MicroBlaze-specific debugging messages if non-zero. 24946 24947@item show debug microblaze @var{n} 24948Show MicroBlaze-specific debugging level. 24949@end table 24950 24951@node MIPS Embedded 24952@subsection @acronym{MIPS} Embedded 24953 24954@noindent 24955@value{GDBN} supports these special commands for @acronym{MIPS} targets: 24956 24957@table @code 24958@item set mipsfpu double 24959@itemx set mipsfpu single 24960@itemx set mipsfpu none 24961@itemx set mipsfpu auto 24962@itemx show mipsfpu 24963@kindex set mipsfpu 24964@kindex show mipsfpu 24965@cindex @acronym{MIPS} remote floating point 24966@cindex floating point, @acronym{MIPS} remote 24967If your target board does not support the @acronym{MIPS} floating point 24968coprocessor, you should use the command @samp{set mipsfpu none} (if you 24969need this, you may wish to put the command in your @value{GDBN} init 24970file). This tells @value{GDBN} how to find the return value of 24971functions which return floating point values. It also allows 24972@value{GDBN} to avoid saving the floating point registers when calling 24973functions on the board. If you are using a floating point coprocessor 24974with only single precision floating point support, as on the @sc{r4650} 24975processor, use the command @samp{set mipsfpu single}. The default 24976double precision floating point coprocessor may be selected using 24977@samp{set mipsfpu double}. 24978 24979In previous versions the only choices were double precision or no 24980floating point, so @samp{set mipsfpu on} will select double precision 24981and @samp{set mipsfpu off} will select no floating point. 24982 24983As usual, you can inquire about the @code{mipsfpu} variable with 24984@samp{show mipsfpu}. 24985@end table 24986 24987@node OpenRISC 1000 24988@subsection OpenRISC 1000 24989@cindex OpenRISC 1000 24990 24991@noindent 24992The OpenRISC 1000 provides a free RISC instruction set architecture. It is 24993mainly provided as a soft-core which can run on Xilinx, Altera and other 24994FPGA's. 24995 24996@value{GDBN} for OpenRISC supports the below commands when connecting to 24997a target: 24998 24999@table @code 25000 25001@kindex target sim 25002@item target sim 25003 25004Runs the builtin CPU simulator which can run very basic 25005programs but does not support most hardware functions like MMU. 25006For more complex use cases the user is advised to run an external 25007target, and connect using @samp{target remote}. 25008 25009Example: @code{target sim} 25010 25011@item set debug or1k 25012Toggle whether to display OpenRISC-specific debugging messages from the 25013OpenRISC target support subsystem. 25014 25015@item show debug or1k 25016Show whether OpenRISC-specific debugging messages are enabled. 25017@end table 25018 25019@node PowerPC Embedded 25020@subsection PowerPC Embedded 25021 25022@cindex DVC register 25023@value{GDBN} supports using the DVC (Data Value Compare) register to 25024implement in hardware simple hardware watchpoint conditions of the form: 25025 25026@smallexample 25027(@value{GDBP}) watch @var{address|variable} \ 25028 if @var{address|variable} == @var{constant expression} 25029@end smallexample 25030 25031The DVC register will be automatically used when @value{GDBN} detects 25032such pattern in a condition expression, and the created watchpoint uses one 25033debug register (either the @code{exact-watchpoints} option is on and the 25034variable is scalar, or the variable has a length of one byte). This feature 25035is available in native @value{GDBN} running on a Linux kernel version 2.6.34 25036or newer. 25037 25038When running on PowerPC embedded processors, @value{GDBN} automatically uses 25039ranged hardware watchpoints, unless the @code{exact-watchpoints} option is on, 25040in which case watchpoints using only one debug register are created when 25041watching variables of scalar types. 25042 25043You can create an artificial array to watch an arbitrary memory 25044region using one of the following commands (@pxref{Expressions}): 25045 25046@smallexample 25047(@value{GDBP}) watch *((char *) @var{address})@@@var{length} 25048(@value{GDBP}) watch @{char[@var{length}]@} @var{address} 25049@end smallexample 25050 25051PowerPC embedded processors support masked watchpoints. See the discussion 25052about the @code{mask} argument in @ref{Set Watchpoints}. 25053 25054@cindex ranged breakpoint 25055PowerPC embedded processors support hardware accelerated 25056@dfn{ranged breakpoints}. A ranged breakpoint stops execution of 25057the inferior whenever it executes an instruction at any address within 25058the range it specifies. To set a ranged breakpoint in @value{GDBN}, 25059use the @code{break-range} command. 25060 25061@value{GDBN} provides the following PowerPC-specific commands: 25062 25063@table @code 25064@kindex break-range 25065@item break-range @var{start-location}, @var{end-location} 25066Set a breakpoint for an address range given by 25067@var{start-location} and @var{end-location}, which can specify a function name, 25068a line number, an offset of lines from the current line or from the start 25069location, or an address of an instruction (see @ref{Specify Location}, 25070for a list of all the possible ways to specify a @var{location}.) 25071The breakpoint will stop execution of the inferior whenever it 25072executes an instruction at any address within the specified range, 25073(including @var{start-location} and @var{end-location}.) 25074 25075@kindex set powerpc 25076@item set powerpc soft-float 25077@itemx show powerpc soft-float 25078Force @value{GDBN} to use (or not use) a software floating point calling 25079convention. By default, @value{GDBN} selects the calling convention based 25080on the selected architecture and the provided executable file. 25081 25082@item set powerpc vector-abi 25083@itemx show powerpc vector-abi 25084Force @value{GDBN} to use the specified calling convention for vector 25085arguments and return values. The valid options are @samp{auto}; 25086@samp{generic}, to avoid vector registers even if they are present; 25087@samp{altivec}, to use AltiVec registers; and @samp{spe} to use SPE 25088registers. By default, @value{GDBN} selects the calling convention 25089based on the selected architecture and the provided executable file. 25090 25091@item set powerpc exact-watchpoints 25092@itemx show powerpc exact-watchpoints 25093Allow @value{GDBN} to use only one debug register when watching a variable 25094of scalar type, thus assuming that the variable is accessed through the 25095address of its first byte. 25096 25097@end table 25098 25099@node AVR 25100@subsection Atmel AVR 25101@cindex AVR 25102 25103When configured for debugging the Atmel AVR, @value{GDBN} supports the 25104following AVR-specific commands: 25105 25106@table @code 25107@item info io_registers 25108@kindex info io_registers@r{, AVR} 25109@cindex I/O registers (Atmel AVR) 25110This command displays information about the AVR I/O registers. For 25111each register, @value{GDBN} prints its number and value. 25112@end table 25113 25114@node CRIS 25115@subsection CRIS 25116@cindex CRIS 25117 25118When configured for debugging CRIS, @value{GDBN} provides the 25119following CRIS-specific commands: 25120 25121@table @code 25122@item set cris-version @var{ver} 25123@cindex CRIS version 25124Set the current CRIS version to @var{ver}, either @samp{10} or @samp{32}. 25125The CRIS version affects register names and sizes. This command is useful in 25126case autodetection of the CRIS version fails. 25127 25128@item show cris-version 25129Show the current CRIS version. 25130 25131@item set cris-dwarf2-cfi 25132@cindex DWARF-2 CFI and CRIS 25133Set the usage of DWARF-2 CFI for CRIS debugging. The default is @samp{on}. 25134Change to @samp{off} when using @code{gcc-cris} whose version is below 25135@code{R59}. 25136 25137@item show cris-dwarf2-cfi 25138Show the current state of using DWARF-2 CFI. 25139 25140@item set cris-mode @var{mode} 25141@cindex CRIS mode 25142Set the current CRIS mode to @var{mode}. It should only be changed when 25143debugging in guru mode, in which case it should be set to 25144@samp{guru} (the default is @samp{normal}). 25145 25146@item show cris-mode 25147Show the current CRIS mode. 25148@end table 25149 25150@node Super-H 25151@subsection Renesas Super-H 25152@cindex Super-H 25153 25154For the Renesas Super-H processor, @value{GDBN} provides these 25155commands: 25156 25157@table @code 25158@item set sh calling-convention @var{convention} 25159@kindex set sh calling-convention 25160Set the calling-convention used when calling functions from @value{GDBN}. 25161Allowed values are @samp{gcc}, which is the default setting, and @samp{renesas}. 25162With the @samp{gcc} setting, functions are called using the @value{NGCC} calling 25163convention. If the DWARF-2 information of the called function specifies 25164that the function follows the Renesas calling convention, the function 25165is called using the Renesas calling convention. If the calling convention 25166is set to @samp{renesas}, the Renesas calling convention is always used, 25167regardless of the DWARF-2 information. This can be used to override the 25168default of @samp{gcc} if debug information is missing, or the compiler 25169does not emit the DWARF-2 calling convention entry for a function. 25170 25171@item show sh calling-convention 25172@kindex show sh calling-convention 25173Show the current calling convention setting. 25174 25175@end table 25176 25177 25178@node Architectures 25179@section Architectures 25180 25181This section describes characteristics of architectures that affect 25182all uses of @value{GDBN} with the architecture, both native and cross. 25183 25184@menu 25185* AArch64:: 25186* i386:: 25187* Alpha:: 25188* MIPS:: 25189* HPPA:: HP PA architecture 25190* PowerPC:: 25191* Nios II:: 25192* Sparc64:: 25193* S12Z:: 25194@end menu 25195 25196@node AArch64 25197@subsection AArch64 25198@cindex AArch64 support 25199 25200When @value{GDBN} is debugging the AArch64 architecture, it provides the 25201following special commands: 25202 25203@table @code 25204@item set debug aarch64 25205@kindex set debug aarch64 25206This command determines whether AArch64 architecture-specific debugging 25207messages are to be displayed. 25208 25209@item show debug aarch64 25210Show whether AArch64 debugging messages are displayed. 25211 25212@end table 25213 25214@subsubsection AArch64 SVE. 25215@cindex AArch64 SVE. 25216 25217When @value{GDBN} is debugging the AArch64 architecture, if the Scalable Vector 25218Extension (SVE) is present, then @value{GDBN} will provide the vector registers 25219@code{$z0} through @code{$z31}, vector predicate registers @code{$p0} through 25220@code{$p15}, and the @code{$ffr} register. In addition, the pseudo register 25221@code{$vg} will be provided. This is the vector granule for the current thread 25222and represents the number of 64-bit chunks in an SVE @code{z} register. 25223 25224If the vector length changes, then the @code{$vg} register will be updated, 25225but the lengths of the @code{z} and @code{p} registers will not change. This 25226is a known limitation of @value{GDBN} and does not affect the execution of the 25227target process. 25228 25229@subsubsection AArch64 Pointer Authentication. 25230@cindex AArch64 Pointer Authentication. 25231 25232When @value{GDBN} is debugging the AArch64 architecture, and the program is 25233using the v8.3-A feature Pointer Authentication (PAC), then whenever the link 25234register @code{$lr} is pointing to an PAC function its value will be masked. 25235When GDB prints a backtrace, any addresses that required unmasking will be 25236postfixed with the marker [PAC]. When using the MI, this is printed as part 25237of the @code{addr_flags} field. 25238 25239@subsubsection AArch64 Memory Tagging Extension. 25240@cindex AArch64 Memory Tagging Extension. 25241 25242When @value{GDBN} is debugging the AArch64 architecture, the program is 25243using the v8.5-A feature Memory Tagging Extension (MTE) and there is support 25244in the kernel for MTE, @value{GDBN} will make memory tagging functionality 25245available for inspection and editing of logical and allocation tags. 25246@xref{Memory Tagging}. 25247 25248To aid debugging, @value{GDBN} will output additional information when SIGSEGV 25249signals are generated as a result of memory tag failures. 25250 25251If the tag violation is synchronous, the following will be shown: 25252 25253@smallexample 25254Program received signal SIGSEGV, Segmentation fault 25255Memory tag violation while accessing address 0x0500fffff7ff8000 25256Allocation tag 0x1 25257Logical tag 0x5. 25258@end smallexample 25259 25260If the tag violation is asynchronous, the fault address is not available. 25261In this case @value{GDBN} will show the following: 25262 25263@smallexample 25264Program received signal SIGSEGV, Segmentation fault 25265Memory tag violation 25266Fault address unavailable. 25267@end smallexample 25268 25269A special register, @code{tag_ctl}, is made available through the 25270@code{org.gnu.gdb.aarch64.mte} feature. This register exposes some 25271options that can be controlled at runtime and emulates the @code{prctl} 25272option @code{PR_SET_TAGGED_ADDR_CTRL}. For further information, see the 25273documentation in the Linux kernel. 25274 25275@node i386 25276@subsection x86 Architecture-specific Issues 25277 25278@table @code 25279@item set struct-convention @var{mode} 25280@kindex set struct-convention 25281@cindex struct return convention 25282@cindex struct/union returned in registers 25283Set the convention used by the inferior to return @code{struct}s and 25284@code{union}s from functions to @var{mode}. Possible values of 25285@var{mode} are @code{"pcc"}, @code{"reg"}, and @code{"default"} (the 25286default). @code{"default"} or @code{"pcc"} means that @code{struct}s 25287are returned on the stack, while @code{"reg"} means that a 25288@code{struct} or a @code{union} whose size is 1, 2, 4, or 8 bytes will 25289be returned in a register. 25290 25291@item show struct-convention 25292@kindex show struct-convention 25293Show the current setting of the convention to return @code{struct}s 25294from functions. 25295@end table 25296 25297 25298@subsubsection Intel @dfn{Memory Protection Extensions} (MPX). 25299@cindex Intel Memory Protection Extensions (MPX). 25300 25301Memory Protection Extension (MPX) adds the bound registers @samp{BND0} 25302@footnote{The register named with capital letters represent the architecture 25303registers.} through @samp{BND3}. Bound registers store a pair of 64-bit values 25304which are the lower bound and upper bound. Bounds are effective addresses or 25305memory locations. The upper bounds are architecturally represented in 1's 25306complement form. A bound having lower bound = 0, and upper bound = 0 25307(1's complement of all bits set) will allow access to the entire address space. 25308 25309@samp{BND0} through @samp{BND3} are represented in @value{GDBN} as @samp{bnd0raw} 25310through @samp{bnd3raw}. Pseudo registers @samp{bnd0} through @samp{bnd3} 25311display the upper bound performing the complement of one operation on the 25312upper bound value, i.e.@ when upper bound in @samp{bnd0raw} is 0 in the 25313@value{GDBN} @samp{bnd0} it will be @code{0xfff@dots{}}. In this sense it 25314can also be noted that the upper bounds are inclusive. 25315 25316As an example, assume that the register BND0 holds bounds for a pointer having 25317access allowed for the range between 0x32 and 0x71. The values present on 25318bnd0raw and bnd registers are presented as follows: 25319 25320@smallexample 25321 bnd0raw = @{0x32, 0xffffffff8e@} 25322 bnd0 = @{lbound = 0x32, ubound = 0x71@} : size 64 25323@end smallexample 25324 25325This way the raw value can be accessed via bnd0raw@dots{}bnd3raw. Any 25326change on bnd0@dots{}bnd3 or bnd0raw@dots{}bnd3raw is reflect on its 25327counterpart. When the bnd0@dots{}bnd3 registers are displayed via 25328Python, the display includes the memory size, in bits, accessible to 25329the pointer. 25330 25331Bounds can also be stored in bounds tables, which are stored in 25332application memory. These tables store bounds for pointers by specifying 25333the bounds pointer's value along with its bounds. Evaluating and changing 25334bounds located in bound tables is therefore interesting while investigating 25335bugs on MPX context. @value{GDBN} provides commands for this purpose: 25336 25337@table @code 25338@item show mpx bound @var{pointer} 25339@kindex show mpx bound 25340Display bounds of the given @var{pointer}. 25341 25342@item set mpx bound @var{pointer}, @var{lbound}, @var{ubound} 25343@kindex set mpx bound 25344Set the bounds of a pointer in the bound table. 25345This command takes three parameters: @var{pointer} is the pointers 25346whose bounds are to be changed, @var{lbound} and @var{ubound} are new values 25347for lower and upper bounds respectively. 25348@end table 25349 25350When you call an inferior function on an Intel MPX enabled program, 25351GDB sets the inferior's bound registers to the init (disabled) state 25352before calling the function. As a consequence, bounds checks for the 25353pointer arguments passed to the function will always pass. 25354 25355This is necessary because when you call an inferior function, the 25356program is usually in the middle of the execution of other function. 25357Since at that point bound registers are in an arbitrary state, not 25358clearing them would lead to random bound violations in the called 25359function. 25360 25361You can still examine the influence of the bound registers on the 25362execution of the called function by stopping the execution of the 25363called function at its prologue, setting bound registers, and 25364continuing the execution. For example: 25365 25366@smallexample 25367 $ break *upper 25368 Breakpoint 2 at 0x4009de: file i386-mpx-call.c, line 47. 25369 $ print upper (a, b, c, d, 1) 25370 Breakpoint 2, upper (a=0x0, b=0x6e0000005b, c=0x0, d=0x0, len=48).... 25371 $ print $bnd0 25372 @{lbound = 0x0, ubound = ffffffff@} : size -1 25373@end smallexample 25374 25375At this last step the value of bnd0 can be changed for investigation of bound 25376violations caused along the execution of the call. In order to know how to 25377set the bound registers or bound table for the call consult the ABI. 25378 25379@node Alpha 25380@subsection Alpha 25381 25382See the following section. 25383 25384@node MIPS 25385@subsection @acronym{MIPS} 25386 25387@cindex stack on Alpha 25388@cindex stack on @acronym{MIPS} 25389@cindex Alpha stack 25390@cindex @acronym{MIPS} stack 25391Alpha- and @acronym{MIPS}-based computers use an unusual stack frame, which 25392sometimes requires @value{GDBN} to search backward in the object code to 25393find the beginning of a function. 25394 25395@cindex response time, @acronym{MIPS} debugging 25396To improve response time (especially for embedded applications, where 25397@value{GDBN} may be restricted to a slow serial line for this search) 25398you may want to limit the size of this search, using one of these 25399commands: 25400 25401@table @code 25402@cindex @code{heuristic-fence-post} (Alpha, @acronym{MIPS}) 25403@item set heuristic-fence-post @var{limit} 25404Restrict @value{GDBN} to examining at most @var{limit} bytes in its 25405search for the beginning of a function. A value of @var{0} (the 25406default) means there is no limit. However, except for @var{0}, the 25407larger the limit the more bytes @code{heuristic-fence-post} must search 25408and therefore the longer it takes to run. You should only need to use 25409this command when debugging a stripped executable. 25410 25411@item show heuristic-fence-post 25412Display the current limit. 25413@end table 25414 25415@noindent 25416These commands are available @emph{only} when @value{GDBN} is configured 25417for debugging programs on Alpha or @acronym{MIPS} processors. 25418 25419Several @acronym{MIPS}-specific commands are available when debugging @acronym{MIPS} 25420programs: 25421 25422@table @code 25423@item set mips abi @var{arg} 25424@kindex set mips abi 25425@cindex set ABI for @acronym{MIPS} 25426Tell @value{GDBN} which @acronym{MIPS} ABI is used by the inferior. Possible 25427values of @var{arg} are: 25428 25429@table @samp 25430@item auto 25431The default ABI associated with the current binary (this is the 25432default). 25433@item o32 25434@item o64 25435@item n32 25436@item n64 25437@item eabi32 25438@item eabi64 25439@end table 25440 25441@item show mips abi 25442@kindex show mips abi 25443Show the @acronym{MIPS} ABI used by @value{GDBN} to debug the inferior. 25444 25445@item set mips compression @var{arg} 25446@kindex set mips compression 25447@cindex code compression, @acronym{MIPS} 25448Tell @value{GDBN} which @acronym{MIPS} compressed 25449@acronym{ISA, Instruction Set Architecture} encoding is used by the 25450inferior. @value{GDBN} uses this for code disassembly and other 25451internal interpretation purposes. This setting is only referred to 25452when no executable has been associated with the debugging session or 25453the executable does not provide information about the encoding it uses. 25454Otherwise this setting is automatically updated from information 25455provided by the executable. 25456 25457Possible values of @var{arg} are @samp{mips16} and @samp{micromips}. 25458The default compressed @acronym{ISA} encoding is @samp{mips16}, as 25459executables containing @acronym{MIPS16} code frequently are not 25460identified as such. 25461 25462This setting is ``sticky''; that is, it retains its value across 25463debugging sessions until reset either explicitly with this command or 25464implicitly from an executable. 25465 25466The compiler and/or assembler typically add symbol table annotations to 25467identify functions compiled for the @acronym{MIPS16} or 25468@acronym{microMIPS} @acronym{ISA}s. If these function-scope annotations 25469are present, @value{GDBN} uses them in preference to the global 25470compressed @acronym{ISA} encoding setting. 25471 25472@item show mips compression 25473@kindex show mips compression 25474Show the @acronym{MIPS} compressed @acronym{ISA} encoding used by 25475@value{GDBN} to debug the inferior. 25476 25477@item set mipsfpu 25478@itemx show mipsfpu 25479@xref{MIPS Embedded, set mipsfpu}. 25480 25481@item set mips mask-address @var{arg} 25482@kindex set mips mask-address 25483@cindex @acronym{MIPS} addresses, masking 25484This command determines whether the most-significant 32 bits of 64-bit 25485@acronym{MIPS} addresses are masked off. The argument @var{arg} can be 25486@samp{on}, @samp{off}, or @samp{auto}. The latter is the default 25487setting, which lets @value{GDBN} determine the correct value. 25488 25489@item show mips mask-address 25490@kindex show mips mask-address 25491Show whether the upper 32 bits of @acronym{MIPS} addresses are masked off or 25492not. 25493 25494@item set remote-mips64-transfers-32bit-regs 25495@kindex set remote-mips64-transfers-32bit-regs 25496This command controls compatibility with 64-bit @acronym{MIPS} targets that 25497transfer data in 32-bit quantities. If you have an old @acronym{MIPS} 64 target 25498that transfers 32 bits for some registers, like @sc{sr} and @sc{fsr}, 25499and 64 bits for other registers, set this option to @samp{on}. 25500 25501@item show remote-mips64-transfers-32bit-regs 25502@kindex show remote-mips64-transfers-32bit-regs 25503Show the current setting of compatibility with older @acronym{MIPS} 64 targets. 25504 25505@item set debug mips 25506@kindex set debug mips 25507This command turns on and off debugging messages for the @acronym{MIPS}-specific 25508target code in @value{GDBN}. 25509 25510@item show debug mips 25511@kindex show debug mips 25512Show the current setting of @acronym{MIPS} debugging messages. 25513@end table 25514 25515 25516@node HPPA 25517@subsection HPPA 25518@cindex HPPA support 25519 25520When @value{GDBN} is debugging the HP PA architecture, it provides the 25521following special commands: 25522 25523@table @code 25524@item set debug hppa 25525@kindex set debug hppa 25526This command determines whether HPPA architecture-specific debugging 25527messages are to be displayed. 25528 25529@item show debug hppa 25530Show whether HPPA debugging messages are displayed. 25531 25532@item maint print unwind @var{address} 25533@kindex maint print unwind@r{, HPPA} 25534This command displays the contents of the unwind table entry at the 25535given @var{address}. 25536 25537@end table 25538 25539 25540@node PowerPC 25541@subsection PowerPC 25542@cindex PowerPC architecture 25543 25544When @value{GDBN} is debugging the PowerPC architecture, it provides a set of 25545pseudo-registers to enable inspection of 128-bit wide Decimal Floating Point 25546numbers stored in the floating point registers. These values must be stored 25547in two consecutive registers, always starting at an even register like 25548@code{f0} or @code{f2}. 25549 25550The pseudo-registers go from @code{$dl0} through @code{$dl15}, and are formed 25551by joining the even/odd register pairs @code{f0} and @code{f1} for @code{$dl0}, 25552@code{f2} and @code{f3} for @code{$dl1} and so on. 25553 25554For POWER7 processors, @value{GDBN} provides a set of pseudo-registers, the 64-bit 25555wide Extended Floating Point Registers (@samp{f32} through @samp{f63}). 25556 25557@node Nios II 25558@subsection Nios II 25559@cindex Nios II architecture 25560 25561When @value{GDBN} is debugging the Nios II architecture, 25562it provides the following special commands: 25563 25564@table @code 25565 25566@item set debug nios2 25567@kindex set debug nios2 25568This command turns on and off debugging messages for the Nios II 25569target code in @value{GDBN}. 25570 25571@item show debug nios2 25572@kindex show debug nios2 25573Show the current setting of Nios II debugging messages. 25574@end table 25575 25576@node Sparc64 25577@subsection Sparc64 25578@cindex Sparc64 support 25579@cindex Application Data Integrity 25580@subsubsection ADI Support 25581 25582The M7 processor supports an Application Data Integrity (ADI) feature that 25583detects invalid data accesses. When software allocates memory and enables 25584ADI on the allocated memory, it chooses a 4-bit version number, sets the 25585version in the upper 4 bits of the 64-bit pointer to that data, and stores 25586the 4-bit version in every cacheline of that data. Hardware saves the latter 25587in spare bits in the cache and memory hierarchy. On each load and store, 25588the processor compares the upper 4 VA (virtual address) bits to the 25589cacheline's version. If there is a mismatch, the processor generates a 25590version mismatch trap which can be either precise or disrupting. The trap 25591is an error condition which the kernel delivers to the process as a SIGSEGV 25592signal. 25593 25594Note that only 64-bit applications can use ADI and need to be built with 25595ADI-enabled. 25596 25597Values of the ADI version tags, which are in granularity of a 25598cacheline (64 bytes), can be viewed or modified. 25599 25600 25601@table @code 25602@kindex adi examine 25603@item adi (examine | x) [ / @var{n} ] @var{addr} 25604 25605The @code{adi examine} command displays the value of one ADI version tag per 25606cacheline. 25607 25608@var{n} is a decimal integer specifying the number in bytes; the default 25609is 1. It specifies how much ADI version information, at the ratio of 1:ADI 25610block size, to display. 25611 25612@var{addr} is the address in user address space where you want @value{GDBN} 25613to begin displaying the ADI version tags. 25614 25615Below is an example of displaying ADI versions of variable "shmaddr". 25616 25617@smallexample 25618(@value{GDBP}) adi x/100 shmaddr 25619 0xfff800010002c000: 0 0 25620@end smallexample 25621 25622@kindex adi assign 25623@item adi (assign | a) [ / @var{n} ] @var{addr} = @var{tag} 25624 25625The @code{adi assign} command is used to assign new ADI version tag 25626to an address. 25627 25628@var{n} is a decimal integer specifying the number in bytes; 25629the default is 1. It specifies how much ADI version information, at the 25630ratio of 1:ADI block size, to modify. 25631 25632@var{addr} is the address in user address space where you want @value{GDBN} 25633to begin modifying the ADI version tags. 25634 25635@var{tag} is the new ADI version tag. 25636 25637For example, do the following to modify then verify ADI versions of 25638variable "shmaddr": 25639 25640@smallexample 25641(@value{GDBP}) adi a/100 shmaddr = 7 25642(@value{GDBP}) adi x/100 shmaddr 25643 0xfff800010002c000: 7 7 25644@end smallexample 25645 25646@end table 25647 25648@node S12Z 25649@subsection S12Z 25650@cindex S12Z support 25651 25652When @value{GDBN} is debugging the S12Z architecture, 25653it provides the following special command: 25654 25655@table @code 25656@item maint info bdccsr 25657@kindex maint info bdccsr@r{, S12Z} 25658This command displays the current value of the microprocessor's 25659BDCCSR register. 25660@end table 25661 25662 25663@node Controlling GDB 25664@chapter Controlling @value{GDBN} 25665 25666You can alter the way @value{GDBN} interacts with you by using the 25667@code{set} command. For commands controlling how @value{GDBN} displays 25668data, see @ref{Print Settings, ,Print Settings}. Other settings are 25669described here. 25670 25671@menu 25672* Prompt:: Prompt 25673* Editing:: Command editing 25674* Command History:: Command history 25675* Screen Size:: Screen size 25676* Output Styling:: Output styling 25677* Numbers:: Numbers 25678* ABI:: Configuring the current ABI 25679* Auto-loading:: Automatically loading associated files 25680* Messages/Warnings:: Optional warnings and messages 25681* Debugging Output:: Optional messages about internal happenings 25682* Other Misc Settings:: Other Miscellaneous Settings 25683@end menu 25684 25685@node Prompt 25686@section Prompt 25687 25688@cindex prompt 25689 25690@value{GDBN} indicates its readiness to read a command by printing a string 25691called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You 25692can change the prompt string with the @code{set prompt} command. For 25693instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change 25694the prompt in one of the @value{GDBN} sessions so that you can always tell 25695which one you are talking to. 25696 25697@emph{Note:} @code{set prompt} does not add a space for you after the 25698prompt you set. This allows you to set a prompt which ends in a space 25699or a prompt that does not. 25700 25701@table @code 25702@kindex set prompt 25703@item set prompt @var{newprompt} 25704Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth. 25705 25706@kindex show prompt 25707@item show prompt 25708Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}} 25709@end table 25710 25711Versions of @value{GDBN} that ship with Python scripting enabled have 25712prompt extensions. The commands for interacting with these extensions 25713are: 25714 25715@table @code 25716@kindex set extended-prompt 25717@item set extended-prompt @var{prompt} 25718Set an extended prompt that allows for substitutions. 25719@xref{gdb.prompt}, for a list of escape sequences that can be used for 25720substitution. Any escape sequences specified as part of the prompt 25721string are replaced with the corresponding strings each time the prompt 25722is displayed. 25723 25724For example: 25725 25726@smallexample 25727set extended-prompt Current working directory: \w (gdb) 25728@end smallexample 25729 25730Note that when an extended-prompt is set, it takes control of the 25731@var{prompt_hook} hook. @xref{prompt_hook}, for further information. 25732 25733@kindex show extended-prompt 25734@item show extended-prompt 25735Prints the extended prompt. Any escape sequences specified as part of 25736the prompt string with @code{set extended-prompt}, are replaced with the 25737corresponding strings each time the prompt is displayed. 25738@end table 25739 25740@node Editing 25741@section Command Editing 25742@cindex readline 25743@cindex command line editing 25744 25745@value{GDBN} reads its input commands via the @dfn{Readline} interface. This 25746@sc{gnu} library provides consistent behavior for programs which provide a 25747command line interface to the user. Advantages are @sc{gnu} Emacs-style 25748or @dfn{vi}-style inline editing of commands, @code{csh}-like history 25749substitution, and a storage and recall of command history across 25750debugging sessions. 25751 25752You may control the behavior of command line editing in @value{GDBN} with the 25753command @code{set}. 25754 25755@table @code 25756@kindex set editing 25757@cindex editing 25758@item set editing 25759@itemx set editing on 25760Enable command line editing (enabled by default). 25761 25762@item set editing off 25763Disable command line editing. 25764 25765@kindex show editing 25766@item show editing 25767Show whether command line editing is enabled. 25768@end table 25769 25770@ifset SYSTEM_READLINE 25771@xref{Command Line Editing, , , rluserman, GNU Readline Library}, 25772@end ifset 25773@ifclear SYSTEM_READLINE 25774@xref{Command Line Editing}, 25775@end ifclear 25776for more details about the Readline 25777interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are 25778encouraged to read that chapter. 25779 25780@cindex Readline application name 25781@value{GDBN} sets the Readline application name to @samp{gdb}. This 25782is useful for conditions in @file{.inputrc}. 25783 25784@cindex operate-and-get-next 25785@value{GDBN} defines a bindable Readline command, 25786@code{operate-and-get-next}. This is bound to @kbd{C-o} by default. 25787This command accepts the current line for execution and fetches the 25788next line relative to the current line from the history for editing. 25789Any argument is ignored. 25790 25791@node Command History 25792@section Command History 25793@cindex command history 25794 25795@value{GDBN} can keep track of the commands you type during your 25796debugging sessions, so that you can be certain of precisely what 25797happened. Use these commands to manage the @value{GDBN} command 25798history facility. 25799 25800@value{GDBN} uses the @sc{gnu} History library, a part of the Readline 25801package, to provide the history facility. 25802@ifset SYSTEM_READLINE 25803@xref{Using History Interactively, , , history, GNU History Library}, 25804@end ifset 25805@ifclear SYSTEM_READLINE 25806@xref{Using History Interactively}, 25807@end ifclear 25808for the detailed description of the History library. 25809 25810To issue a command to @value{GDBN} without affecting certain aspects of 25811the state which is seen by users, prefix it with @samp{server } 25812(@pxref{Server Prefix}). This 25813means that this command will not affect the command history, nor will it 25814affect @value{GDBN}'s notion of which command to repeat if @key{RET} is 25815pressed on a line by itself. 25816 25817@cindex @code{server}, command prefix 25818The server prefix does not affect the recording of values into the value 25819history; to print a value without recording it into the value history, 25820use the @code{output} command instead of the @code{print} command. 25821 25822Here is the description of @value{GDBN} commands related to command 25823history. 25824 25825@table @code 25826@cindex history substitution 25827@cindex history file 25828@kindex set history filename 25829@cindex @env{GDBHISTFILE}, environment variable 25830@item set history filename @r{[}@var{fname}@r{]} 25831Set the name of the @value{GDBN} command history file to @var{fname}. 25832This is the file where @value{GDBN} reads an initial command history 25833list, and where it writes the command history from this session when it 25834exits. You can access this list through history expansion or through 25835the history command editing characters listed below. This file defaults 25836to the value of the environment variable @env{GDBHISTFILE}, or to 25837@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable 25838is not set. 25839 25840The @env{GDBHISTFILE} environment variable is read after processing 25841any @value{GDBN} initialization files (@pxref{Startup}) and after 25842processing any commands passed using command line options (for 25843example, @code{-ex}). 25844 25845If the @var{fname} argument is not given, or if the @env{GDBHISTFILE} 25846is the empty string then @value{GDBN} will neither try to load an 25847existing history file, nor will it try to save the history on exit. 25848 25849@cindex save command history 25850@kindex set history save 25851@item set history save 25852@itemx set history save on 25853Record command history in a file, whose name may be specified with the 25854@code{set history filename} command. By default, this option is 25855disabled. The command history will be recorded when @value{GDBN} 25856exits. If @code{set history filename} is set to the empty string then 25857history saving is disabled, even when @code{set history save} is 25858@code{on}. 25859 25860@item set history save off 25861Don't record the command history into the file specified by @code{set 25862history filename} when @value{GDBN} exits. 25863 25864@cindex history size 25865@kindex set history size 25866@cindex @env{GDBHISTSIZE}, environment variable 25867@item set history size @var{size} 25868@itemx set history size unlimited 25869Set the number of commands which @value{GDBN} keeps in its history list. 25870This defaults to the value of the environment variable @env{GDBHISTSIZE}, or 25871to 256 if this variable is not set. Non-numeric values of @env{GDBHISTSIZE} 25872are ignored. If @var{size} is @code{unlimited} or if @env{GDBHISTSIZE} is 25873either a negative number or the empty string, then the number of commands 25874@value{GDBN} keeps in the history list is unlimited. 25875 25876The @env{GDBHISTSIZE} environment variable is read after processing 25877any @value{GDBN} initialization files (@pxref{Startup}) and after 25878processing any commands passed using command line options (for 25879example, @code{-ex}). 25880 25881@cindex remove duplicate history 25882@kindex set history remove-duplicates 25883@item set history remove-duplicates @var{count} 25884@itemx set history remove-duplicates unlimited 25885Control the removal of duplicate history entries in the command history list. 25886If @var{count} is non-zero, @value{GDBN} will look back at the last @var{count} 25887history entries and remove the first entry that is a duplicate of the current 25888entry being added to the command history list. If @var{count} is 25889@code{unlimited} then this lookbehind is unbounded. If @var{count} is 0, then 25890removal of duplicate history entries is disabled. 25891 25892Only history entries added during the current session are considered for 25893removal. This option is set to 0 by default. 25894 25895@end table 25896 25897History expansion assigns special meaning to the character @kbd{!}. 25898@ifset SYSTEM_READLINE 25899@xref{Event Designators, , , history, GNU History Library}, 25900@end ifset 25901@ifclear SYSTEM_READLINE 25902@xref{Event Designators}, 25903@end ifclear 25904for more details. 25905 25906@cindex history expansion, turn on/off 25907Since @kbd{!} is also the logical not operator in C, history expansion 25908is off by default. If you decide to enable history expansion with the 25909@code{set history expansion on} command, you may sometimes need to 25910follow @kbd{!} (when it is used as logical not, in an expression) with 25911a space or a tab to prevent it from being expanded. The readline 25912history facilities do not attempt substitution on the strings 25913@kbd{!=} and @kbd{!(}, even when history expansion is enabled. 25914 25915The commands to control history expansion are: 25916 25917@table @code 25918@item set history expansion on 25919@itemx set history expansion 25920@kindex set history expansion 25921Enable history expansion. History expansion is off by default. 25922 25923@item set history expansion off 25924Disable history expansion. 25925 25926@c @group 25927@kindex show history 25928@item show history 25929@itemx show history filename 25930@itemx show history save 25931@itemx show history size 25932@itemx show history expansion 25933These commands display the state of the @value{GDBN} history parameters. 25934@code{show history} by itself displays all four states. 25935@c @end group 25936@end table 25937 25938@table @code 25939@kindex show commands 25940@cindex show last commands 25941@cindex display command history 25942@item show commands 25943Display the last ten commands in the command history. 25944 25945@item show commands @var{n} 25946Print ten commands centered on command number @var{n}. 25947 25948@item show commands + 25949Print ten commands just after the commands last printed. 25950@end table 25951 25952@node Screen Size 25953@section Screen Size 25954@cindex size of screen 25955@cindex screen size 25956@cindex pagination 25957@cindex page size 25958@cindex pauses in output 25959 25960Certain commands to @value{GDBN} may produce large amounts of 25961information output to the screen. To help you read all of it, 25962@value{GDBN} pauses and asks you for input at the end of each page of 25963output. Type @key{RET} when you want to see one more page of output, 25964@kbd{q} to discard the remaining output, or @kbd{c} to continue 25965without paging for the rest of the current command. Also, the screen 25966width setting determines when to wrap lines of output. Depending on 25967what is being printed, @value{GDBN} tries to break the line at a 25968readable place, rather than simply letting it overflow onto the 25969following line. 25970 25971Normally @value{GDBN} knows the size of the screen from the terminal 25972driver software. For example, on Unix @value{GDBN} uses the termcap data base 25973together with the value of the @env{TERM} environment variable and the 25974@code{stty rows} and @code{stty cols} settings. If this is not correct, 25975you can override it with the @code{set height} and @code{set 25976width} commands: 25977 25978@table @code 25979@kindex set height 25980@kindex set width 25981@kindex show width 25982@kindex show height 25983@item set height @var{lpp} 25984@itemx set height unlimited 25985@itemx show height 25986@itemx set width @var{cpl} 25987@itemx set width unlimited 25988@itemx show width 25989These @code{set} commands specify a screen height of @var{lpp} lines and 25990a screen width of @var{cpl} characters. The associated @code{show} 25991commands display the current settings. 25992 25993If you specify a height of either @code{unlimited} or zero lines, 25994@value{GDBN} does not pause during output no matter how long the 25995output is. This is useful if output is to a file or to an editor 25996buffer. 25997 25998Likewise, you can specify @samp{set width unlimited} or @samp{set 25999width 0} to prevent @value{GDBN} from wrapping its output. 26000 26001@item set pagination on 26002@itemx set pagination off 26003@kindex set pagination 26004Turn the output pagination on or off; the default is on. Turning 26005pagination off is the alternative to @code{set height unlimited}. Note that 26006running @value{GDBN} with the @option{--batch} option (@pxref{Mode 26007Options, -batch}) also automatically disables pagination. 26008 26009@item show pagination 26010@kindex show pagination 26011Show the current pagination mode. 26012@end table 26013 26014@node Output Styling 26015@section Output Styling 26016@cindex styling 26017@cindex colors 26018 26019@kindex set style 26020@kindex show style 26021@value{GDBN} can style its output on a capable terminal. This is 26022enabled by default on most systems, but disabled by default when in 26023batch mode (@pxref{Mode Options}). Various style settings are available; 26024and styles can also be disabled entirely. 26025 26026@table @code 26027@item set style enabled @samp{on|off} 26028Enable or disable all styling. The default is host-dependent, with 26029most hosts defaulting to @samp{on}. 26030 26031@item show style enabled 26032Show the current state of styling. 26033 26034@item set style sources @samp{on|off} 26035Enable or disable source code styling. This affects whether source 26036code, such as the output of the @code{list} command, is styled. The 26037default is @samp{on}. Note that source styling only works if styling 26038in general is enabled, and if a source highlighting library is 26039available to @value{GDBN}. 26040 26041There are two ways that highlighting can be done. First, if 26042@value{GDBN} was linked with the GNU Source Highlight library, then it 26043is used. Otherwise, if @value{GDBN} was configured with Python 26044scripting support, and if the Python Pygments package is available, 26045then it will be used. 26046 26047@item show style sources 26048Show the current state of source code styling. 26049@end table 26050 26051Subcommands of @code{set style} control specific forms of styling. 26052These subcommands all follow the same pattern: each style-able object 26053can be styled with a foreground color, a background color, and an 26054intensity. 26055 26056For example, the style of file names can be controlled using the 26057@code{set style filename} group of commands: 26058 26059@table @code 26060@item set style filename background @var{color} 26061Set the background to @var{color}. Valid colors are @samp{none} 26062(meaning the terminal's default color), @samp{black}, @samp{red}, 26063@samp{green}, @samp{yellow}, @samp{blue}, @samp{magenta}, @samp{cyan}, 26064and@samp{white}. 26065 26066@item set style filename foreground @var{color} 26067Set the foreground to @var{color}. Valid colors are @samp{none} 26068(meaning the terminal's default color), @samp{black}, @samp{red}, 26069@samp{green}, @samp{yellow}, @samp{blue}, @samp{magenta}, @samp{cyan}, 26070and@samp{white}. 26071 26072@item set style filename intensity @var{value} 26073Set the intensity to @var{value}. Valid intensities are @samp{normal} 26074(the default), @samp{bold}, and @samp{dim}. 26075@end table 26076 26077The @code{show style} command and its subcommands are styling 26078a style name in their output using its own style. 26079So, use @command{show style} to see the complete list of styles, 26080their characteristics and the visual aspect of each style. 26081 26082The style-able objects are: 26083@table @code 26084@item filename 26085Control the styling of file names. By default, this style's 26086foreground color is green. 26087 26088@item function 26089Control the styling of function names. These are managed with the 26090@code{set style function} family of commands. By default, this 26091style's foreground color is yellow. 26092 26093@item variable 26094Control the styling of variable names. These are managed with the 26095@code{set style variable} family of commands. By default, this style's 26096foreground color is cyan. 26097 26098@item address 26099Control the styling of addresses. These are managed with the 26100@code{set style address} family of commands. By default, this style's 26101foreground color is blue. 26102 26103@item version 26104Control the styling of @value{GDBN}'s version number text. By 26105default, this style's foreground color is magenta and it has bold 26106intensity. The version number is displayed in two places, the output 26107of @command{show version}, and when @value{GDBN} starts up. 26108 26109In order to control how @value{GDBN} styles the version number at 26110startup, add the @code{set style version} family of commands to the 26111early initialization command file (@pxref{Initialization 26112Files}). 26113 26114@item title 26115Control the styling of titles. These are managed with the 26116@code{set style title} family of commands. By default, this style's 26117intensity is bold. Commands are using the title style to improve 26118the readability of large output. For example, the commands 26119@command{apropos} and @command{help} are using the title style 26120for the command names. 26121 26122@item highlight 26123Control the styling of highlightings. These are managed with the 26124@code{set style highlight} family of commands. By default, this style's 26125foreground color is red. Commands are using the highlight style to draw 26126the user attention to some specific parts of their output. For example, 26127the command @command{apropos -v REGEXP} uses the highlight style to 26128mark the documentation parts matching @var{regexp}. 26129 26130@item tui-border 26131Control the styling of the TUI border. Note that, unlike other 26132styling options, only the color of the border can be controlled via 26133@code{set style}. This was done for compatibility reasons, as TUI 26134controls to set the border's intensity predated the addition of 26135general styling to @value{GDBN}. @xref{TUI Configuration}. 26136 26137@item tui-active-border 26138Control the styling of the active TUI border; that is, the TUI window 26139that has the focus. 26140 26141@end table 26142 26143@node Numbers 26144@section Numbers 26145@cindex number representation 26146@cindex entering numbers 26147 26148You can always enter numbers in octal, decimal, or hexadecimal in 26149@value{GDBN} by the usual conventions: octal numbers begin with 26150@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers 26151begin with @samp{0x}. Numbers that neither begin with @samp{0} or 26152@samp{0x}, nor end with a @samp{.} are, by default, entered in base 2615310; likewise, the default display for numbers---when no particular 26154format is specified---is base 10. You can change the default base for 26155both input and output with the commands described below. 26156 26157@table @code 26158@kindex set input-radix 26159@item set input-radix @var{base} 26160Set the default base for numeric input. Supported choices 26161for @var{base} are decimal 8, 10, or 16. The base must itself be 26162specified either unambiguously or using the current input radix; for 26163example, any of 26164 26165@smallexample 26166set input-radix 012 26167set input-radix 10. 26168set input-radix 0xa 26169@end smallexample 26170 26171@noindent 26172sets the input base to decimal. On the other hand, @samp{set input-radix 10} 26173leaves the input radix unchanged, no matter what it was, since 26174@samp{10}, being without any leading or trailing signs of its base, is 26175interpreted in the current radix. Thus, if the current radix is 16, 26176@samp{10} is interpreted in hex, i.e.@: as 16 decimal, which doesn't 26177change the radix. 26178 26179@kindex set output-radix 26180@item set output-radix @var{base} 26181Set the default base for numeric display. Supported choices 26182for @var{base} are decimal 8, 10, or 16. The base must itself be 26183specified either unambiguously or using the current input radix. 26184 26185@kindex show input-radix 26186@item show input-radix 26187Display the current default base for numeric input. 26188 26189@kindex show output-radix 26190@item show output-radix 26191Display the current default base for numeric display. 26192 26193@item set radix @r{[}@var{base}@r{]} 26194@itemx show radix 26195@kindex set radix 26196@kindex show radix 26197These commands set and show the default base for both input and output 26198of numbers. @code{set radix} sets the radix of input and output to 26199the same base; without an argument, it resets the radix back to its 26200default value of 10. 26201 26202@end table 26203 26204@node ABI 26205@section Configuring the Current ABI 26206 26207@value{GDBN} can determine the @dfn{ABI} (Application Binary Interface) of your 26208application automatically. However, sometimes you need to override its 26209conclusions. Use these commands to manage @value{GDBN}'s view of the 26210current ABI. 26211 26212@cindex OS ABI 26213@kindex set osabi 26214@kindex show osabi 26215@cindex Newlib OS ABI and its influence on the longjmp handling 26216 26217One @value{GDBN} configuration can debug binaries for multiple operating 26218system targets, either via remote debugging or native emulation. 26219@value{GDBN} will autodetect the @dfn{OS ABI} (Operating System ABI) in use, 26220but you can override its conclusion using the @code{set osabi} command. 26221One example where this is useful is in debugging of binaries which use 26222an alternate C library (e.g.@: @sc{uClibc} for @sc{gnu}/Linux) which does 26223not have the same identifying marks that the standard C library for your 26224platform provides. 26225 26226When @value{GDBN} is debugging the AArch64 architecture, it provides a 26227``Newlib'' OS ABI. This is useful for handling @code{setjmp} and 26228@code{longjmp} when debugging binaries that use the @sc{newlib} C library. 26229The ``Newlib'' OS ABI can be selected by @code{set osabi Newlib}. 26230 26231@table @code 26232@item show osabi 26233Show the OS ABI currently in use. 26234 26235@item set osabi 26236With no argument, show the list of registered available OS ABI's. 26237 26238@item set osabi @var{abi} 26239Set the current OS ABI to @var{abi}. 26240@end table 26241 26242@cindex float promotion 26243 26244Generally, the way that an argument of type @code{float} is passed to a 26245function depends on whether the function is prototyped. For a prototyped 26246(i.e.@: ANSI/ISO style) function, @code{float} arguments are passed unchanged, 26247according to the architecture's convention for @code{float}. For unprototyped 26248(i.e.@: K&R style) functions, @code{float} arguments are first promoted to type 26249@code{double} and then passed. 26250 26251Unfortunately, some forms of debug information do not reliably indicate whether 26252a function is prototyped. If @value{GDBN} calls a function that is not marked 26253as prototyped, it consults @kbd{set coerce-float-to-double}. 26254 26255@table @code 26256@kindex set coerce-float-to-double 26257@item set coerce-float-to-double 26258@itemx set coerce-float-to-double on 26259Arguments of type @code{float} will be promoted to @code{double} when passed 26260to an unprototyped function. This is the default setting. 26261 26262@item set coerce-float-to-double off 26263Arguments of type @code{float} will be passed directly to unprototyped 26264functions. 26265 26266@kindex show coerce-float-to-double 26267@item show coerce-float-to-double 26268Show the current setting of promoting @code{float} to @code{double}. 26269@end table 26270 26271@kindex set cp-abi 26272@kindex show cp-abi 26273@value{GDBN} needs to know the ABI used for your program's C@t{++} 26274objects. The correct C@t{++} ABI depends on which C@t{++} compiler was 26275used to build your application. @value{GDBN} only fully supports 26276programs with a single C@t{++} ABI; if your program contains code using 26277multiple C@t{++} ABI's or if @value{GDBN} can not identify your 26278program's ABI correctly, you can tell @value{GDBN} which ABI to use. 26279Currently supported ABI's include ``gnu-v2'', for @code{g++} versions 26280before 3.0, ``gnu-v3'', for @code{g++} versions 3.0 and later, and 26281``hpaCC'' for the HP ANSI C@t{++} compiler. Other C@t{++} compilers may 26282use the ``gnu-v2'' or ``gnu-v3'' ABI's as well. The default setting is 26283``auto''. 26284 26285@table @code 26286@item show cp-abi 26287Show the C@t{++} ABI currently in use. 26288 26289@item set cp-abi 26290With no argument, show the list of supported C@t{++} ABI's. 26291 26292@item set cp-abi @var{abi} 26293@itemx set cp-abi auto 26294Set the current C@t{++} ABI to @var{abi}, or return to automatic detection. 26295@end table 26296 26297@node Auto-loading 26298@section Automatically loading associated files 26299@cindex auto-loading 26300 26301@value{GDBN} sometimes reads files with commands and settings automatically, 26302without being explicitly told so by the user. We call this feature 26303@dfn{auto-loading}. While auto-loading is useful for automatically adapting 26304@value{GDBN} to the needs of your project, it can sometimes produce unexpected 26305results or introduce security risks (e.g., if the file comes from untrusted 26306sources). 26307 26308There are various kinds of files @value{GDBN} can automatically load. 26309In addition to these files, @value{GDBN} supports auto-loading code written 26310in various extension languages. @xref{Auto-loading extensions}. 26311 26312Note that loading of these associated files (including the local @file{.gdbinit} 26313file) requires accordingly configured @code{auto-load safe-path} 26314(@pxref{Auto-loading safe path}). 26315 26316For these reasons, @value{GDBN} includes commands and options to let you 26317control when to auto-load files and which files should be auto-loaded. 26318 26319@table @code 26320@anchor{set auto-load off} 26321@kindex set auto-load off 26322@item set auto-load off 26323Globally disable loading of all auto-loaded files. 26324You may want to use this command with the @samp{-iex} option 26325(@pxref{Option -init-eval-command}) such as: 26326@smallexample 26327$ @kbd{gdb -iex "set auto-load off" untrusted-executable corefile} 26328@end smallexample 26329 26330Be aware that system init file (@pxref{System-wide configuration}) 26331and init files from your home directory (@pxref{Home Directory Init File}) 26332still get read (as they come from generally trusted directories). 26333To prevent @value{GDBN} from auto-loading even those init files, use the 26334@option{-nx} option (@pxref{Mode Options}), in addition to 26335@code{set auto-load no}. 26336 26337@anchor{show auto-load} 26338@kindex show auto-load 26339@item show auto-load 26340Show whether auto-loading of each specific @samp{auto-load} file(s) is enabled 26341or disabled. 26342 26343@smallexample 26344(gdb) show auto-load 26345gdb-scripts: Auto-loading of canned sequences of commands scripts is on. 26346libthread-db: Auto-loading of inferior specific libthread_db is on. 26347local-gdbinit: Auto-loading of .gdbinit script from current directory 26348 is on. 26349python-scripts: Auto-loading of Python scripts is on. 26350safe-path: List of directories from which it is safe to auto-load files 26351 is $debugdir:$datadir/auto-load. 26352scripts-directory: List of directories from which to load auto-loaded scripts 26353 is $debugdir:$datadir/auto-load. 26354@end smallexample 26355 26356@anchor{info auto-load} 26357@kindex info auto-load 26358@item info auto-load 26359Print whether each specific @samp{auto-load} file(s) have been auto-loaded or 26360not. 26361 26362@smallexample 26363(gdb) info auto-load 26364gdb-scripts: 26365Loaded Script 26366Yes /home/user/gdb/gdb-gdb.gdb 26367libthread-db: No auto-loaded libthread-db. 26368local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been 26369 loaded. 26370python-scripts: 26371Loaded Script 26372Yes /home/user/gdb/gdb-gdb.py 26373@end smallexample 26374@end table 26375 26376These are @value{GDBN} control commands for the auto-loading: 26377 26378@multitable @columnfractions .5 .5 26379@item @xref{set auto-load off}. 26380@tab Disable auto-loading globally. 26381@item @xref{show auto-load}. 26382@tab Show setting of all kinds of files. 26383@item @xref{info auto-load}. 26384@tab Show state of all kinds of files. 26385@item @xref{set auto-load gdb-scripts}. 26386@tab Control for @value{GDBN} command scripts. 26387@item @xref{show auto-load gdb-scripts}. 26388@tab Show setting of @value{GDBN} command scripts. 26389@item @xref{info auto-load gdb-scripts}. 26390@tab Show state of @value{GDBN} command scripts. 26391@item @xref{set auto-load python-scripts}. 26392@tab Control for @value{GDBN} Python scripts. 26393@item @xref{show auto-load python-scripts}. 26394@tab Show setting of @value{GDBN} Python scripts. 26395@item @xref{info auto-load python-scripts}. 26396@tab Show state of @value{GDBN} Python scripts. 26397@item @xref{set auto-load guile-scripts}. 26398@tab Control for @value{GDBN} Guile scripts. 26399@item @xref{show auto-load guile-scripts}. 26400@tab Show setting of @value{GDBN} Guile scripts. 26401@item @xref{info auto-load guile-scripts}. 26402@tab Show state of @value{GDBN} Guile scripts. 26403@item @xref{set auto-load scripts-directory}. 26404@tab Control for @value{GDBN} auto-loaded scripts location. 26405@item @xref{show auto-load scripts-directory}. 26406@tab Show @value{GDBN} auto-loaded scripts location. 26407@item @xref{add-auto-load-scripts-directory}. 26408@tab Add directory for auto-loaded scripts location list. 26409@item @xref{set auto-load local-gdbinit}. 26410@tab Control for init file in the current directory. 26411@item @xref{show auto-load local-gdbinit}. 26412@tab Show setting of init file in the current directory. 26413@item @xref{info auto-load local-gdbinit}. 26414@tab Show state of init file in the current directory. 26415@item @xref{set auto-load libthread-db}. 26416@tab Control for thread debugging library. 26417@item @xref{show auto-load libthread-db}. 26418@tab Show setting of thread debugging library. 26419@item @xref{info auto-load libthread-db}. 26420@tab Show state of thread debugging library. 26421@item @xref{set auto-load safe-path}. 26422@tab Control directories trusted for automatic loading. 26423@item @xref{show auto-load safe-path}. 26424@tab Show directories trusted for automatic loading. 26425@item @xref{add-auto-load-safe-path}. 26426@tab Add directory trusted for automatic loading. 26427@end multitable 26428 26429@menu 26430* Init File in the Current Directory:: @samp{set/show/info auto-load local-gdbinit} 26431* libthread_db.so.1 file:: @samp{set/show/info auto-load libthread-db} 26432 26433* Auto-loading safe path:: @samp{set/show/info auto-load safe-path} 26434* Auto-loading verbose mode:: @samp{set/show debug auto-load} 26435@end menu 26436 26437@node Init File in the Current Directory 26438@subsection Automatically loading init file in the current directory 26439@cindex auto-loading init file in the current directory 26440 26441By default, @value{GDBN} reads and executes the canned sequences of commands 26442from init file (if any) in the current working directory, 26443see @ref{Init File in the Current Directory during Startup}. 26444 26445Note that loading of this local @file{.gdbinit} file also requires accordingly 26446configured @code{auto-load safe-path} (@pxref{Auto-loading safe path}). 26447 26448@table @code 26449@anchor{set auto-load local-gdbinit} 26450@kindex set auto-load local-gdbinit 26451@item set auto-load local-gdbinit [on|off] 26452Enable or disable the auto-loading of canned sequences of commands 26453(@pxref{Sequences}) found in init file in the current directory. 26454 26455@anchor{show auto-load local-gdbinit} 26456@kindex show auto-load local-gdbinit 26457@item show auto-load local-gdbinit 26458Show whether auto-loading of canned sequences of commands from init file in the 26459current directory is enabled or disabled. 26460 26461@anchor{info auto-load local-gdbinit} 26462@kindex info auto-load local-gdbinit 26463@item info auto-load local-gdbinit 26464Print whether canned sequences of commands from init file in the 26465current directory have been auto-loaded. 26466@end table 26467 26468@node libthread_db.so.1 file 26469@subsection Automatically loading thread debugging library 26470@cindex auto-loading libthread_db.so.1 26471 26472This feature is currently present only on @sc{gnu}/Linux native hosts. 26473 26474@value{GDBN} reads in some cases thread debugging library from places specific 26475to the inferior (@pxref{set libthread-db-search-path}). 26476 26477The special @samp{libthread-db-search-path} entry @samp{$sdir} is processed 26478without checking this @samp{set auto-load libthread-db} switch as system 26479libraries have to be trusted in general. In all other cases of 26480@samp{libthread-db-search-path} entries @value{GDBN} checks first if @samp{set 26481auto-load libthread-db} is enabled before trying to open such thread debugging 26482library. 26483 26484Note that loading of this debugging library also requires accordingly configured 26485@code{auto-load safe-path} (@pxref{Auto-loading safe path}). 26486 26487@table @code 26488@anchor{set auto-load libthread-db} 26489@kindex set auto-load libthread-db 26490@item set auto-load libthread-db [on|off] 26491Enable or disable the auto-loading of inferior specific thread debugging library. 26492 26493@anchor{show auto-load libthread-db} 26494@kindex show auto-load libthread-db 26495@item show auto-load libthread-db 26496Show whether auto-loading of inferior specific thread debugging library is 26497enabled or disabled. 26498 26499@anchor{info auto-load libthread-db} 26500@kindex info auto-load libthread-db 26501@item info auto-load libthread-db 26502Print the list of all loaded inferior specific thread debugging libraries and 26503for each such library print list of inferior @var{pid}s using it. 26504@end table 26505 26506@node Auto-loading safe path 26507@subsection Security restriction for auto-loading 26508@cindex auto-loading safe-path 26509 26510As the files of inferior can come from untrusted source (such as submitted by 26511an application user) @value{GDBN} does not always load any files automatically. 26512@value{GDBN} provides the @samp{set auto-load safe-path} setting to list 26513directories trusted for loading files not explicitly requested by user. 26514Each directory can also be a shell wildcard pattern. 26515 26516If the path is not set properly you will see a warning and the file will not 26517get loaded: 26518 26519@smallexample 26520$ ./gdb -q ./gdb 26521Reading symbols from /home/user/gdb/gdb... 26522warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been 26523 declined by your `auto-load safe-path' set 26524 to "$debugdir:$datadir/auto-load". 26525warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been 26526 declined by your `auto-load safe-path' set 26527 to "$debugdir:$datadir/auto-load". 26528@end smallexample 26529 26530@noindent 26531To instruct @value{GDBN} to go ahead and use the init files anyway, 26532invoke @value{GDBN} like this: 26533 26534@smallexample 26535$ gdb -q -iex "set auto-load safe-path /home/user/gdb" ./gdb 26536@end smallexample 26537 26538The list of trusted directories is controlled by the following commands: 26539 26540@table @code 26541@anchor{set auto-load safe-path} 26542@kindex set auto-load safe-path 26543@item set auto-load safe-path @r{[}@var{directories}@r{]} 26544Set the list of directories (and their subdirectories) trusted for automatic 26545loading and execution of scripts. You can also enter a specific trusted file. 26546Each directory can also be a shell wildcard pattern; wildcards do not match 26547directory separator - see @code{FNM_PATHNAME} for system function @code{fnmatch} 26548(@pxref{Wildcard Matching, fnmatch, , libc, GNU C Library Reference Manual}). 26549If you omit @var{directories}, @samp{auto-load safe-path} will be reset to 26550its default value as specified during @value{GDBN} compilation. 26551 26552The list of directories uses path separator (@samp{:} on GNU and Unix 26553systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly 26554to the @env{PATH} environment variable. 26555 26556@anchor{show auto-load safe-path} 26557@kindex show auto-load safe-path 26558@item show auto-load safe-path 26559Show the list of directories trusted for automatic loading and execution of 26560scripts. 26561 26562@anchor{add-auto-load-safe-path} 26563@kindex add-auto-load-safe-path 26564@item add-auto-load-safe-path 26565Add an entry (or list of entries) to the list of directories trusted for 26566automatic loading and execution of scripts. Multiple entries may be delimited 26567by the host platform path separator in use. 26568@end table 26569 26570This variable defaults to what @code{--with-auto-load-dir} has been configured 26571to (@pxref{with-auto-load-dir}). @file{$debugdir} and @file{$datadir} 26572substitution applies the same as for @ref{set auto-load scripts-directory}. 26573The default @code{set auto-load safe-path} value can be also overriden by 26574@value{GDBN} configuration option @option{--with-auto-load-safe-path}. 26575 26576Setting this variable to @file{/} disables this security protection, 26577corresponding @value{GDBN} configuration option is 26578@option{--without-auto-load-safe-path}. 26579This variable is supposed to be set to the system directories writable by the 26580system superuser only. Users can add their source directories in init files in 26581their home directories (@pxref{Home Directory Init File}). See also deprecated 26582init file in the current directory 26583(@pxref{Init File in the Current Directory during Startup}). 26584 26585To force @value{GDBN} to load the files it declined to load in the previous 26586example, you could use one of the following ways: 26587 26588@table @asis 26589@item @file{~/.gdbinit}: @samp{add-auto-load-safe-path ~/src/gdb} 26590Specify this trusted directory (or a file) as additional component of the list. 26591You have to specify also any existing directories displayed by 26592by @samp{show auto-load safe-path} (such as @samp{/usr:/bin} in this example). 26593 26594@item @kbd{gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" @dots{}} 26595Specify this directory as in the previous case but just for a single 26596@value{GDBN} session. 26597 26598@item @kbd{gdb -iex "set auto-load safe-path /" @dots{}} 26599Disable auto-loading safety for a single @value{GDBN} session. 26600This assumes all the files you debug during this @value{GDBN} session will come 26601from trusted sources. 26602 26603@item @kbd{./configure --without-auto-load-safe-path} 26604During compilation of @value{GDBN} you may disable any auto-loading safety. 26605This assumes all the files you will ever debug with this @value{GDBN} come from 26606trusted sources. 26607@end table 26608 26609On the other hand you can also explicitly forbid automatic files loading which 26610also suppresses any such warning messages: 26611 26612@table @asis 26613@item @kbd{gdb -iex "set auto-load no" @dots{}} 26614You can use @value{GDBN} command-line option for a single @value{GDBN} session. 26615 26616@item @file{~/.gdbinit}: @samp{set auto-load no} 26617Disable auto-loading globally for the user 26618(@pxref{Home Directory Init File}). While it is improbable, you could also 26619use system init file instead (@pxref{System-wide configuration}). 26620@end table 26621 26622This setting applies to the file names as entered by user. If no entry matches 26623@value{GDBN} tries as a last resort to also resolve all the file names into 26624their canonical form (typically resolving symbolic links) and compare the 26625entries again. @value{GDBN} already canonicalizes most of the filenames on its 26626own before starting the comparison so a canonical form of directories is 26627recommended to be entered. 26628 26629@node Auto-loading verbose mode 26630@subsection Displaying files tried for auto-load 26631@cindex auto-loading verbose mode 26632 26633For better visibility of all the file locations where you can place scripts to 26634be auto-loaded with inferior --- or to protect yourself against accidental 26635execution of untrusted scripts --- @value{GDBN} provides a feature for printing 26636all the files attempted to be loaded. Both existing and non-existing files may 26637be printed. 26638 26639For example the list of directories from which it is safe to auto-load files 26640(@pxref{Auto-loading safe path}) applies also to canonicalized filenames which 26641may not be too obvious while setting it up. 26642 26643@smallexample 26644(gdb) set debug auto-load on 26645(gdb) file ~/src/t/true 26646auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb" 26647 for objfile "/tmp/true". 26648auto-load: Updating directories of "/usr:/opt". 26649auto-load: Using directory "/usr". 26650auto-load: Using directory "/opt". 26651warning: File "/tmp/true-gdb.gdb" auto-loading has been declined 26652 by your `auto-load safe-path' set to "/usr:/opt". 26653@end smallexample 26654 26655@table @code 26656@anchor{set debug auto-load} 26657@kindex set debug auto-load 26658@item set debug auto-load [on|off] 26659Set whether to print the filenames attempted to be auto-loaded. 26660 26661@anchor{show debug auto-load} 26662@kindex show debug auto-load 26663@item show debug auto-load 26664Show whether printing of the filenames attempted to be auto-loaded is turned 26665on or off. 26666@end table 26667 26668@node Messages/Warnings 26669@section Optional Warnings and Messages 26670 26671@cindex verbose operation 26672@cindex optional warnings 26673By default, @value{GDBN} is silent about its inner workings. If you are 26674running on a slow machine, you may want to use the @code{set verbose} 26675command. This makes @value{GDBN} tell you when it does a lengthy 26676internal operation, so you will not think it has crashed. 26677 26678Currently, the messages controlled by @code{set verbose} are those 26679which announce that the symbol table for a source file is being read; 26680see @code{symbol-file} in @ref{Files, ,Commands to Specify Files}. 26681 26682@table @code 26683@kindex set verbose 26684@item set verbose on 26685Enables @value{GDBN} output of certain informational messages. 26686 26687@item set verbose off 26688Disables @value{GDBN} output of certain informational messages. 26689 26690@kindex show verbose 26691@item show verbose 26692Displays whether @code{set verbose} is on or off. 26693@end table 26694 26695By default, if @value{GDBN} encounters bugs in the symbol table of an 26696object file, it is silent; but if you are debugging a compiler, you may 26697find this information useful (@pxref{Symbol Errors, ,Errors Reading 26698Symbol Files}). 26699 26700@table @code 26701 26702@kindex set complaints 26703@item set complaints @var{limit} 26704Permits @value{GDBN} to output @var{limit} complaints about each type of 26705unusual symbols before becoming silent about the problem. Set 26706@var{limit} to zero to suppress all complaints; set it to a large number 26707to prevent complaints from being suppressed. 26708 26709@kindex show complaints 26710@item show complaints 26711Displays how many symbol complaints @value{GDBN} is permitted to produce. 26712 26713@end table 26714 26715@anchor{confirmation requests} 26716By default, @value{GDBN} is cautious, and asks what sometimes seems to be a 26717lot of stupid questions to confirm certain commands. For example, if 26718you try to run a program which is already running: 26719 26720@smallexample 26721(@value{GDBP}) run 26722The program being debugged has been started already. 26723Start it from the beginning? (y or n) 26724@end smallexample 26725 26726If you are willing to unflinchingly face the consequences of your own 26727commands, you can disable this ``feature'': 26728 26729@table @code 26730 26731@kindex set confirm 26732@cindex flinching 26733@cindex confirmation 26734@cindex stupid questions 26735@item set confirm off 26736Disables confirmation requests. Note that running @value{GDBN} with 26737the @option{--batch} option (@pxref{Mode Options, -batch}) also 26738automatically disables confirmation requests. 26739 26740@item set confirm on 26741Enables confirmation requests (the default). 26742 26743@kindex show confirm 26744@item show confirm 26745Displays state of confirmation requests. 26746 26747@end table 26748 26749@cindex command tracing 26750If you need to debug user-defined commands or sourced files you may find it 26751useful to enable @dfn{command tracing}. In this mode each command will be 26752printed as it is executed, prefixed with one or more @samp{+} symbols, the 26753quantity denoting the call depth of each command. 26754 26755@table @code 26756@kindex set trace-commands 26757@cindex command scripts, debugging 26758@item set trace-commands on 26759Enable command tracing. 26760@item set trace-commands off 26761Disable command tracing. 26762@item show trace-commands 26763Display the current state of command tracing. 26764@end table 26765 26766@node Debugging Output 26767@section Optional Messages about Internal Happenings 26768@cindex optional debugging messages 26769 26770@value{GDBN} has commands that enable optional debugging messages from 26771various @value{GDBN} subsystems; normally these commands are of 26772interest to @value{GDBN} maintainers, or when reporting a bug. This 26773section documents those commands. 26774 26775@table @code 26776@kindex set exec-done-display 26777@item set exec-done-display 26778Turns on or off the notification of asynchronous commands' 26779completion. When on, @value{GDBN} will print a message when an 26780asynchronous command finishes its execution. The default is off. 26781@kindex show exec-done-display 26782@item show exec-done-display 26783Displays the current setting of asynchronous command completion 26784notification. 26785 26786@kindex set debug 26787@cindex ARM AArch64 26788@item set debug aarch64 26789Turns on or off display of debugging messages related to ARM AArch64. 26790The default is off. 26791@kindex show debug 26792@item show debug aarch64 26793Displays the current state of displaying debugging messages related to 26794ARM AArch64. 26795 26796@cindex gdbarch debugging info 26797@cindex architecture debugging info 26798@item set debug arch 26799Turns on or off display of gdbarch debugging info. The default is off 26800@item show debug arch 26801Displays the current state of displaying gdbarch debugging info. 26802 26803@item set debug aix-solib 26804@cindex AIX shared library debugging 26805Control display of debugging messages from the AIX shared library 26806support module. The default is off. 26807@item show debug aix-solib 26808Show the current state of displaying AIX shared library debugging messages. 26809 26810@item set debug aix-thread 26811@cindex AIX threads 26812Display debugging messages about inner workings of the AIX thread 26813module. 26814@item show debug aix-thread 26815Show the current state of AIX thread debugging info display. 26816 26817@item set debug check-physname 26818@cindex physname 26819Check the results of the ``physname'' computation. When reading DWARF 26820debugging information for C@t{++}, @value{GDBN} attempts to compute 26821each entity's name. @value{GDBN} can do this computation in two 26822different ways, depending on exactly what information is present. 26823When enabled, this setting causes @value{GDBN} to compute the names 26824both ways and display any discrepancies. 26825@item show debug check-physname 26826Show the current state of ``physname'' checking. 26827 26828@item set debug coff-pe-read 26829@cindex COFF/PE exported symbols 26830Control display of debugging messages related to reading of COFF/PE 26831exported symbols. The default is off. 26832@item show debug coff-pe-read 26833Displays the current state of displaying debugging messages related to 26834reading of COFF/PE exported symbols. 26835 26836@item set debug dwarf-die 26837@cindex DWARF DIEs 26838Dump DWARF DIEs after they are read in. 26839The value is the number of nesting levels to print. 26840A value of zero turns off the display. 26841@item show debug dwarf-die 26842Show the current state of DWARF DIE debugging. 26843 26844@item set debug dwarf-line 26845@cindex DWARF Line Tables 26846Turns on or off display of debugging messages related to reading 26847DWARF line tables. The default is 0 (off). 26848A value of 1 provides basic information. 26849A value greater than 1 provides more verbose information. 26850@item show debug dwarf-line 26851Show the current state of DWARF line table debugging. 26852 26853@item set debug dwarf-read 26854@cindex DWARF Reading 26855Turns on or off display of debugging messages related to reading 26856DWARF debug info. The default is 0 (off). 26857A value of 1 provides basic information. 26858A value greater than 1 provides more verbose information. 26859@item show debug dwarf-read 26860Show the current state of DWARF reader debugging. 26861 26862@item set debug displaced 26863@cindex displaced stepping debugging info 26864Turns on or off display of @value{GDBN} debugging info for the 26865displaced stepping support. The default is off. 26866@item show debug displaced 26867Displays the current state of displaying @value{GDBN} debugging info 26868related to displaced stepping. 26869 26870@item set debug event 26871@cindex event debugging info 26872Turns on or off display of @value{GDBN} event debugging info. The 26873default is off. 26874@item show debug event 26875Displays the current state of displaying @value{GDBN} event debugging 26876info. 26877 26878@item set debug event-loop 26879@cindex event-loop debugging 26880Controls output of debugging info about the event loop. The possible 26881values are @samp{off}, @samp{all} (shows all debugging info) and 26882@samp{all-except-ui} (shows all debugging info except those about 26883UI-related events). 26884@item show debug event-loop 26885Shows the current state of displaying debugging info about the event 26886loop. 26887 26888@item set debug expression 26889@cindex expression debugging info 26890Turns on or off display of debugging info about @value{GDBN} 26891expression parsing. The default is off. 26892@item show debug expression 26893Displays the current state of displaying debugging info about 26894@value{GDBN} expression parsing. 26895 26896@item set debug fbsd-lwp 26897@cindex FreeBSD LWP debug messages 26898Turns on or off debugging messages from the FreeBSD LWP debug support. 26899@item show debug fbsd-lwp 26900Show the current state of FreeBSD LWP debugging messages. 26901 26902@item set debug fbsd-nat 26903@cindex FreeBSD native target debug messages 26904Turns on or off debugging messages from the FreeBSD native target. 26905@item show debug fbsd-nat 26906Show the current state of FreeBSD native target debugging messages. 26907 26908@item set debug fortran-array-slicing 26909@cindex fortran array slicing debugging info 26910Turns on or off display of @value{GDBN} Fortran array slicing 26911debugging info. The default is off. 26912 26913@item show debug fortran-array-slicing 26914Displays the current state of displaying @value{GDBN} Fortran array 26915slicing debugging info. 26916 26917@item set debug frame 26918@cindex frame debugging info 26919Turns on or off display of @value{GDBN} frame debugging info. The 26920default is off. 26921@item show debug frame 26922Displays the current state of displaying @value{GDBN} frame debugging 26923info. 26924 26925@item set debug gnu-nat 26926@cindex @sc{gnu}/Hurd debug messages 26927Turn on or off debugging messages from the @sc{gnu}/Hurd debug support. 26928@item show debug gnu-nat 26929Show the current state of @sc{gnu}/Hurd debugging messages. 26930 26931@item set debug infrun 26932@cindex inferior debugging info 26933Turns on or off display of @value{GDBN} debugging info for running the inferior. 26934The default is off. @file{infrun.c} contains GDB's runtime state machine used 26935for implementing operations such as single-stepping the inferior. 26936@item show debug infrun 26937Displays the current state of @value{GDBN} inferior debugging. 26938 26939@item set debug jit 26940@cindex just-in-time compilation, debugging messages 26941Turn on or off debugging messages from JIT debug support. 26942@item show debug jit 26943Displays the current state of @value{GDBN} JIT debugging. 26944 26945@item set debug lin-lwp 26946@cindex @sc{gnu}/Linux LWP debug messages 26947@cindex Linux lightweight processes 26948Turn on or off debugging messages from the Linux LWP debug support. 26949@item show debug lin-lwp 26950Show the current state of Linux LWP debugging messages. 26951 26952@item set debug linux-namespaces 26953@cindex @sc{gnu}/Linux namespaces debug messages 26954Turn on or off debugging messages from the Linux namespaces debug support. 26955@item show debug linux-namespaces 26956Show the current state of Linux namespaces debugging messages. 26957 26958@item set debug mach-o 26959@cindex Mach-O symbols processing 26960Control display of debugging messages related to Mach-O symbols 26961processing. The default is off. 26962@item show debug mach-o 26963Displays the current state of displaying debugging messages related to 26964reading of COFF/PE exported symbols. 26965 26966@item set debug notification 26967@cindex remote async notification debugging info 26968Turn on or off debugging messages about remote async notification. 26969The default is off. 26970@item show debug notification 26971Displays the current state of remote async notification debugging messages. 26972 26973@item set debug observer 26974@cindex observer debugging info 26975Turns on or off display of @value{GDBN} observer debugging. This 26976includes info such as the notification of observable events. 26977@item show debug observer 26978Displays the current state of observer debugging. 26979 26980@item set debug overload 26981@cindex C@t{++} overload debugging info 26982Turns on or off display of @value{GDBN} C@t{++} overload debugging 26983info. This includes info such as ranking of functions, etc. The default 26984is off. 26985@item show debug overload 26986Displays the current state of displaying @value{GDBN} C@t{++} overload 26987debugging info. 26988 26989@cindex expression parser, debugging info 26990@cindex debug expression parser 26991@item set debug parser 26992Turns on or off the display of expression parser debugging output. 26993Internally, this sets the @code{yydebug} variable in the expression 26994parser. @xref{Tracing, , Tracing Your Parser, bison, Bison}, for 26995details. The default is off. 26996@item show debug parser 26997Show the current state of expression parser debugging. 26998 26999@cindex packets, reporting on stdout 27000@cindex serial connections, debugging 27001@cindex debug remote protocol 27002@cindex remote protocol debugging 27003@cindex display remote packets 27004@item set debug remote 27005Turns on or off display of reports on all packets sent back and forth across 27006the serial line to the remote machine. The info is printed on the 27007@value{GDBN} standard output stream. The default is off. 27008@item show debug remote 27009Displays the state of display of remote packets. 27010 27011@item set debug remote-packet-max-chars 27012Sets the maximum number of characters to display for each remote packet when 27013@code{set debug remote} is on. This is useful to prevent @value{GDBN} from 27014displaying lengthy remote packets and polluting the console. 27015 27016The default value is @code{512}, which means @value{GDBN} will truncate each 27017remote packet after 512 bytes. 27018 27019Setting this option to @code{unlimited} will disable truncation and will output 27020the full length of the remote packets. 27021@item show debug remote-packet-max-chars 27022Displays the number of bytes to output for remote packet debugging. 27023 27024@item set debug separate-debug-file 27025Turns on or off display of debug output about separate debug file search. 27026@item show debug separate-debug-file 27027Displays the state of separate debug file search debug output. 27028 27029@item set debug serial 27030Turns on or off display of @value{GDBN} serial debugging info. The 27031default is off. 27032@item show debug serial 27033Displays the current state of displaying @value{GDBN} serial debugging 27034info. 27035 27036@item set debug solib-frv 27037@cindex FR-V shared-library debugging 27038Turn on or off debugging messages for FR-V shared-library code. 27039@item show debug solib-frv 27040Display the current state of FR-V shared-library code debugging 27041messages. 27042 27043@item set debug symbol-lookup 27044@cindex symbol lookup 27045Turns on or off display of debugging messages related to symbol lookup. 27046The default is 0 (off). 27047A value of 1 provides basic information. 27048A value greater than 1 provides more verbose information. 27049@item show debug symbol-lookup 27050Show the current state of symbol lookup debugging messages. 27051 27052@item set debug symfile 27053@cindex symbol file functions 27054Turns on or off display of debugging messages related to symbol file functions. 27055The default is off. @xref{Files}. 27056@item show debug symfile 27057Show the current state of symbol file debugging messages. 27058 27059@item set debug symtab-create 27060@cindex symbol table creation 27061Turns on or off display of debugging messages related to symbol table creation. 27062The default is 0 (off). 27063A value of 1 provides basic information. 27064A value greater than 1 provides more verbose information. 27065@item show debug symtab-create 27066Show the current state of symbol table creation debugging. 27067 27068@item set debug target 27069@cindex target debugging info 27070Turns on or off display of @value{GDBN} target debugging info. This info 27071includes what is going on at the target level of GDB, as it happens. The 27072default is 0. Set it to 1 to track events, and to 2 to also track the 27073value of large memory transfers. 27074@item show debug target 27075Displays the current state of displaying @value{GDBN} target debugging 27076info. 27077 27078@item set debug timestamp 27079@cindex timestamping debugging info 27080Turns on or off display of timestamps with @value{GDBN} debugging info. 27081When enabled, seconds and microseconds are displayed before each debugging 27082message. 27083@item show debug timestamp 27084Displays the current state of displaying timestamps with @value{GDBN} 27085debugging info. 27086 27087@item set debug varobj 27088@cindex variable object debugging info 27089Turns on or off display of @value{GDBN} variable object debugging 27090info. The default is off. 27091@item show debug varobj 27092Displays the current state of displaying @value{GDBN} variable object 27093debugging info. 27094 27095@item set debug xml 27096@cindex XML parser debugging 27097Turn on or off debugging messages for built-in XML parsers. 27098@item show debug xml 27099Displays the current state of XML debugging messages. 27100@end table 27101 27102@node Other Misc Settings 27103@section Other Miscellaneous Settings 27104@cindex miscellaneous settings 27105 27106@table @code 27107@kindex set interactive-mode 27108@item set interactive-mode 27109If @code{on}, forces @value{GDBN} to assume that GDB was started 27110in a terminal. In practice, this means that @value{GDBN} should wait 27111for the user to answer queries generated by commands entered at 27112the command prompt. If @code{off}, forces @value{GDBN} to operate 27113in the opposite mode, and it uses the default answers to all queries. 27114If @code{auto} (the default), @value{GDBN} tries to determine whether 27115its standard input is a terminal, and works in interactive-mode if it 27116is, non-interactively otherwise. 27117 27118In the vast majority of cases, the debugger should be able to guess 27119correctly which mode should be used. But this setting can be useful 27120in certain specific cases, such as running a MinGW @value{GDBN} 27121inside a cygwin window. 27122 27123@kindex show interactive-mode 27124@item show interactive-mode 27125Displays whether the debugger is operating in interactive mode or not. 27126@end table 27127 27128@node Extending GDB 27129@chapter Extending @value{GDBN} 27130@cindex extending GDB 27131 27132@value{GDBN} provides several mechanisms for extension. 27133@value{GDBN} also provides the ability to automatically load 27134extensions when it reads a file for debugging. This allows the 27135user to automatically customize @value{GDBN} for the program 27136being debugged. 27137 27138To facilitate the use of extension languages, @value{GDBN} is capable 27139of evaluating the contents of a file. When doing so, @value{GDBN} 27140can recognize which extension language is being used by looking at 27141the filename extension. Files with an unrecognized filename extension 27142are always treated as a @value{GDBN} Command Files. 27143@xref{Command Files,, Command files}. 27144 27145You can control how @value{GDBN} evaluates these files with the following 27146setting: 27147 27148@table @code 27149@kindex set script-extension 27150@kindex show script-extension 27151@item set script-extension off 27152All scripts are always evaluated as @value{GDBN} Command Files. 27153 27154@item set script-extension soft 27155The debugger determines the scripting language based on filename 27156extension. If this scripting language is supported, @value{GDBN} 27157evaluates the script using that language. Otherwise, it evaluates 27158the file as a @value{GDBN} Command File. 27159 27160@item set script-extension strict 27161The debugger determines the scripting language based on filename 27162extension, and evaluates the script using that language. If the 27163language is not supported, then the evaluation fails. 27164 27165@item show script-extension 27166Display the current value of the @code{script-extension} option. 27167 27168@end table 27169 27170@ifset SYSTEM_GDBINIT_DIR 27171This setting is not used for files in the system-wide gdbinit directory. 27172Files in that directory must have an extension matching their language, 27173or have a @file{.gdb} extension to be interpreted as regular @value{GDBN} 27174commands. @xref{Startup}. 27175@end ifset 27176 27177@menu 27178* Sequences:: Canned Sequences of @value{GDBN} Commands 27179* Aliases:: Command Aliases 27180* Python:: Extending @value{GDBN} using Python 27181* Guile:: Extending @value{GDBN} using Guile 27182* Auto-loading extensions:: Automatically loading extensions 27183* Multiple Extension Languages:: Working with multiple extension languages 27184@end menu 27185 27186@node Sequences 27187@section Canned Sequences of Commands 27188 27189Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint 27190Command Lists}), @value{GDBN} provides two ways to store sequences of 27191commands for execution as a unit: user-defined commands and command 27192files. 27193 27194@menu 27195* Define:: How to define your own commands 27196* Hooks:: Hooks for user-defined commands 27197* Command Files:: How to write scripts of commands to be stored in a file 27198* Output:: Commands for controlled output 27199* Auto-loading sequences:: Controlling auto-loaded command files 27200@end menu 27201 27202@node Define 27203@subsection User-defined Commands 27204 27205@cindex user-defined command 27206@cindex arguments, to user-defined commands 27207A @dfn{user-defined command} is a sequence of @value{GDBN} commands to 27208which you assign a new name as a command. This is done with the 27209@code{define} command. User commands may accept an unlimited number of arguments 27210separated by whitespace. Arguments are accessed within the user command 27211via @code{$arg0@dots{}$argN}. A trivial example: 27212 27213@smallexample 27214define adder 27215 print $arg0 + $arg1 + $arg2 27216end 27217@end smallexample 27218 27219@noindent 27220To execute the command use: 27221 27222@smallexample 27223adder 1 2 3 27224@end smallexample 27225 27226@noindent 27227This defines the command @code{adder}, which prints the sum of 27228its three arguments. Note the arguments are text substitutions, so they may 27229reference variables, use complex expressions, or even perform inferior 27230functions calls. 27231 27232@cindex argument count in user-defined commands 27233@cindex how many arguments (user-defined commands) 27234In addition, @code{$argc} may be used to find out how many arguments have 27235been passed. 27236 27237@smallexample 27238define adder 27239 if $argc == 2 27240 print $arg0 + $arg1 27241 end 27242 if $argc == 3 27243 print $arg0 + $arg1 + $arg2 27244 end 27245end 27246@end smallexample 27247 27248Combining with the @code{eval} command (@pxref{eval}) makes it easier 27249to process a variable number of arguments: 27250 27251@smallexample 27252define adder 27253 set $i = 0 27254 set $sum = 0 27255 while $i < $argc 27256 eval "set $sum = $sum + $arg%d", $i 27257 set $i = $i + 1 27258 end 27259 print $sum 27260end 27261@end smallexample 27262 27263@table @code 27264 27265@kindex define 27266@item define @var{commandname} 27267Define a command named @var{commandname}. If there is already a command 27268by that name, you are asked to confirm that you want to redefine it. 27269The argument @var{commandname} may be a bare command name consisting of letters, 27270numbers, dashes, dots, and underscores. It may also start with any 27271predefined or user-defined prefix command. 27272For example, @samp{define target my-target} creates 27273a user-defined @samp{target my-target} command. 27274 27275The definition of the command is made up of other @value{GDBN} command lines, 27276which are given following the @code{define} command. The end of these 27277commands is marked by a line containing @code{end}. 27278 27279@kindex document 27280@kindex end@r{ (user-defined commands)} 27281@item document @var{commandname} 27282Document the user-defined command @var{commandname}, so that it can be 27283accessed by @code{help}. The command @var{commandname} must already be 27284defined. This command reads lines of documentation just as @code{define} 27285reads the lines of the command definition, ending with @code{end}. 27286After the @code{document} command is finished, @code{help} on command 27287@var{commandname} displays the documentation you have written. 27288 27289You may use the @code{document} command again to change the 27290documentation of a command. Redefining the command with @code{define} 27291does not change the documentation. 27292 27293@kindex define-prefix 27294@item define-prefix @var{commandname} 27295Define or mark the command @var{commandname} as a user-defined prefix 27296command. Once marked, @var{commandname} can be used as prefix command 27297by the @code{define} command. 27298Note that @code{define-prefix} can be used with a not yet defined 27299@var{commandname}. In such a case, @var{commandname} is defined as 27300an empty user-defined command. 27301In case you redefine a command that was marked as a user-defined 27302prefix command, the subcommands of the redefined command are kept 27303(and @value{GDBN} indicates so to the user). 27304 27305Example: 27306@example 27307(gdb) define-prefix abc 27308(gdb) define-prefix abc def 27309(gdb) define abc def 27310Type commands for definition of "abc def". 27311End with a line saying just "end". 27312>echo command initial def\n 27313>end 27314(gdb) define abc def ghi 27315Type commands for definition of "abc def ghi". 27316End with a line saying just "end". 27317>echo command ghi\n 27318>end 27319(gdb) define abc def 27320Keeping subcommands of prefix command "def". 27321Redefine command "def"? (y or n) y 27322Type commands for definition of "abc def". 27323End with a line saying just "end". 27324>echo command def\n 27325>end 27326(gdb) abc def ghi 27327command ghi 27328(gdb) abc def 27329command def 27330(gdb) 27331@end example 27332 27333@kindex dont-repeat 27334@cindex don't repeat command 27335@item dont-repeat 27336Used inside a user-defined command, this tells @value{GDBN} that this 27337command should not be repeated when the user hits @key{RET} 27338(@pxref{Command Syntax, repeat last command}). 27339 27340@kindex help user-defined 27341@item help user-defined 27342List all user-defined commands and all python commands defined in class 27343COMMAND_USER. The first line of the documentation or docstring is 27344included (if any). 27345 27346@kindex show user 27347@item show user 27348@itemx show user @var{commandname} 27349Display the @value{GDBN} commands used to define @var{commandname} (but 27350not its documentation). If no @var{commandname} is given, display the 27351definitions for all user-defined commands. 27352This does not work for user-defined python commands. 27353 27354@cindex infinite recursion in user-defined commands 27355@kindex show max-user-call-depth 27356@kindex set max-user-call-depth 27357@item show max-user-call-depth 27358@itemx set max-user-call-depth 27359The value of @code{max-user-call-depth} controls how many recursion 27360levels are allowed in user-defined commands before @value{GDBN} suspects an 27361infinite recursion and aborts the command. 27362This does not apply to user-defined python commands. 27363@end table 27364 27365In addition to the above commands, user-defined commands frequently 27366use control flow commands, described in @ref{Command Files}. 27367 27368When user-defined commands are executed, the 27369commands of the definition are not printed. An error in any command 27370stops execution of the user-defined command. 27371 27372If used interactively, commands that would ask for confirmation proceed 27373without asking when used inside a user-defined command. Many @value{GDBN} 27374commands that normally print messages to say what they are doing omit the 27375messages when used in a user-defined command. 27376 27377@node Hooks 27378@subsection User-defined Command Hooks 27379@cindex command hooks 27380@cindex hooks, for commands 27381@cindex hooks, pre-command 27382 27383@kindex hook 27384You may define @dfn{hooks}, which are a special kind of user-defined 27385command. Whenever you run the command @samp{foo}, if the user-defined 27386command @samp{hook-foo} exists, it is executed (with no arguments) 27387before that command. 27388 27389@cindex hooks, post-command 27390@kindex hookpost 27391A hook may also be defined which is run after the command you executed. 27392Whenever you run the command @samp{foo}, if the user-defined command 27393@samp{hookpost-foo} exists, it is executed (with no arguments) after 27394that command. Post-execution hooks may exist simultaneously with 27395pre-execution hooks, for the same command. 27396 27397It is valid for a hook to call the command which it hooks. If this 27398occurs, the hook is not re-executed, thereby avoiding infinite recursion. 27399 27400@c It would be nice if hookpost could be passed a parameter indicating 27401@c if the command it hooks executed properly or not. FIXME! 27402 27403@kindex stop@r{, a pseudo-command} 27404In addition, a pseudo-command, @samp{stop} exists. Defining 27405(@samp{hook-stop}) makes the associated commands execute every time 27406execution stops in your program: before breakpoint commands are run, 27407displays are printed, or the stack frame is printed. 27408 27409For example, to ignore @code{SIGALRM} signals while 27410single-stepping, but treat them normally during normal execution, 27411you could define: 27412 27413@smallexample 27414define hook-stop 27415handle SIGALRM nopass 27416end 27417 27418define hook-run 27419handle SIGALRM pass 27420end 27421 27422define hook-continue 27423handle SIGALRM pass 27424end 27425@end smallexample 27426 27427As a further example, to hook at the beginning and end of the @code{echo} 27428command, and to add extra text to the beginning and end of the message, 27429you could define: 27430 27431@smallexample 27432define hook-echo 27433echo <<<--- 27434end 27435 27436define hookpost-echo 27437echo --->>>\n 27438end 27439 27440(@value{GDBP}) echo Hello World 27441<<<---Hello World--->>> 27442(@value{GDBP}) 27443 27444@end smallexample 27445 27446You can define a hook for any single-word command in @value{GDBN}, but 27447not for command aliases; you should define a hook for the basic command 27448name, e.g.@: @code{backtrace} rather than @code{bt}. 27449@c FIXME! So how does Joe User discover whether a command is an alias 27450@c or not? 27451You can hook a multi-word command by adding @code{hook-} or 27452@code{hookpost-} to the last word of the command, e.g.@: 27453@samp{define target hook-remote} to add a hook to @samp{target remote}. 27454 27455If an error occurs during the execution of your hook, execution of 27456@value{GDBN} commands stops and @value{GDBN} issues a prompt 27457(before the command that you actually typed had a chance to run). 27458 27459If you try to define a hook which does not match any known command, you 27460get a warning from the @code{define} command. 27461 27462@node Command Files 27463@subsection Command Files 27464 27465@cindex command files 27466@cindex scripting commands 27467A command file for @value{GDBN} is a text file made of lines that are 27468@value{GDBN} commands. Comments (lines starting with @kbd{#}) may 27469also be included. An empty line in a command file does nothing; it 27470does not mean to repeat the last command, as it would from the 27471terminal. 27472 27473You can request the execution of a command file with the @code{source} 27474command. Note that the @code{source} command is also used to evaluate 27475scripts that are not Command Files. The exact behavior can be configured 27476using the @code{script-extension} setting. 27477@xref{Extending GDB,, Extending GDB}. 27478 27479@table @code 27480@kindex source 27481@cindex execute commands from a file 27482@item source [-s] [-v] @var{filename} 27483Execute the command file @var{filename}. 27484@end table 27485 27486The lines in a command file are generally executed sequentially, 27487unless the order of execution is changed by one of the 27488@emph{flow-control commands} described below. The commands are not 27489printed as they are executed. An error in any command terminates 27490execution of the command file and control is returned to the console. 27491 27492@value{GDBN} first searches for @var{filename} in the current directory. 27493If the file is not found there, and @var{filename} does not specify a 27494directory, then @value{GDBN} also looks for the file on the source search path 27495(specified with the @samp{directory} command); 27496except that @file{$cdir} is not searched because the compilation directory 27497is not relevant to scripts. 27498 27499If @code{-s} is specified, then @value{GDBN} searches for @var{filename} 27500on the search path even if @var{filename} specifies a directory. 27501The search is done by appending @var{filename} to each element of the 27502search path. So, for example, if @var{filename} is @file{mylib/myscript} 27503and the search path contains @file{/home/user} then @value{GDBN} will 27504look for the script @file{/home/user/mylib/myscript}. 27505The search is also done if @var{filename} is an absolute path. 27506For example, if @var{filename} is @file{/tmp/myscript} and 27507the search path contains @file{/home/user} then @value{GDBN} will 27508look for the script @file{/home/user/tmp/myscript}. 27509For DOS-like systems, if @var{filename} contains a drive specification, 27510it is stripped before concatenation. For example, if @var{filename} is 27511@file{d:myscript} and the search path contains @file{c:/tmp} then @value{GDBN} 27512will look for the script @file{c:/tmp/myscript}. 27513 27514If @code{-v}, for verbose mode, is given then @value{GDBN} displays 27515each command as it is executed. The option must be given before 27516@var{filename}, and is interpreted as part of the filename anywhere else. 27517 27518Commands that would ask for confirmation if used interactively proceed 27519without asking when used in a command file. Many @value{GDBN} commands that 27520normally print messages to say what they are doing omit the messages 27521when called from command files. 27522 27523@value{GDBN} also accepts command input from standard input. In this 27524mode, normal output goes to standard output and error output goes to 27525standard error. Errors in a command file supplied on standard input do 27526not terminate execution of the command file---execution continues with 27527the next command. 27528 27529@smallexample 27530gdb < cmds > log 2>&1 27531@end smallexample 27532 27533(The syntax above will vary depending on the shell used.) This example 27534will execute commands from the file @file{cmds}. All output and errors 27535would be directed to @file{log}. 27536 27537Since commands stored on command files tend to be more general than 27538commands typed interactively, they frequently need to deal with 27539complicated situations, such as different or unexpected values of 27540variables and symbols, changes in how the program being debugged is 27541built, etc. @value{GDBN} provides a set of flow-control commands to 27542deal with these complexities. Using these commands, you can write 27543complex scripts that loop over data structures, execute commands 27544conditionally, etc. 27545 27546@table @code 27547@kindex if 27548@kindex else 27549@item if 27550@itemx else 27551This command allows to include in your script conditionally executed 27552commands. The @code{if} command takes a single argument, which is an 27553expression to evaluate. It is followed by a series of commands that 27554are executed only if the expression is true (its value is nonzero). 27555There can then optionally be an @code{else} line, followed by a series 27556of commands that are only executed if the expression was false. The 27557end of the list is marked by a line containing @code{end}. 27558 27559@kindex while 27560@item while 27561This command allows to write loops. Its syntax is similar to 27562@code{if}: the command takes a single argument, which is an expression 27563to evaluate, and must be followed by the commands to execute, one per 27564line, terminated by an @code{end}. These commands are called the 27565@dfn{body} of the loop. The commands in the body of @code{while} are 27566executed repeatedly as long as the expression evaluates to true. 27567 27568@kindex loop_break 27569@item loop_break 27570This command exits the @code{while} loop in whose body it is included. 27571Execution of the script continues after that @code{while}s @code{end} 27572line. 27573 27574@kindex loop_continue 27575@item loop_continue 27576This command skips the execution of the rest of the body of commands 27577in the @code{while} loop in whose body it is included. Execution 27578branches to the beginning of the @code{while} loop, where it evaluates 27579the controlling expression. 27580 27581@kindex end@r{ (if/else/while commands)} 27582@item end 27583Terminate the block of commands that are the body of @code{if}, 27584@code{else}, or @code{while} flow-control commands. 27585@end table 27586 27587 27588@node Output 27589@subsection Commands for Controlled Output 27590 27591During the execution of a command file or a user-defined command, normal 27592@value{GDBN} output is suppressed; the only output that appears is what is 27593explicitly printed by the commands in the definition. This section 27594describes three commands useful for generating exactly the output you 27595want. 27596 27597@table @code 27598@kindex echo 27599@item echo @var{text} 27600@c I do not consider backslash-space a standard C escape sequence 27601@c because it is not in ANSI. 27602Print @var{text}. Nonprinting characters can be included in 27603@var{text} using C escape sequences, such as @samp{\n} to print a 27604newline. @strong{No newline is printed unless you specify one.} 27605In addition to the standard C escape sequences, a backslash followed 27606by a space stands for a space. This is useful for displaying a 27607string with spaces at the beginning or the end, since leading and 27608trailing spaces are otherwise trimmed from all arguments. 27609To print @samp{@w{ }and foo =@w{ }}, use the command 27610@samp{echo \@w{ }and foo = \@w{ }}. 27611 27612A backslash at the end of @var{text} can be used, as in C, to continue 27613the command onto subsequent lines. For example, 27614 27615@smallexample 27616echo This is some text\n\ 27617which is continued\n\ 27618onto several lines.\n 27619@end smallexample 27620 27621produces the same output as 27622 27623@smallexample 27624echo This is some text\n 27625echo which is continued\n 27626echo onto several lines.\n 27627@end smallexample 27628 27629@kindex output 27630@item output @var{expression} 27631Print the value of @var{expression} and nothing but that value: no 27632newlines, no @samp{$@var{nn} = }. The value is not entered in the 27633value history either. @xref{Expressions, ,Expressions}, for more information 27634on expressions. 27635 27636@item output/@var{fmt} @var{expression} 27637Print the value of @var{expression} in format @var{fmt}. You can use 27638the same formats as for @code{print}. @xref{Output Formats,,Output 27639Formats}, for more information. 27640 27641@kindex printf 27642@item printf @var{template}, @var{expressions}@dots{} 27643Print the values of one or more @var{expressions} under the control of 27644the string @var{template}. To print several values, make 27645@var{expressions} be a comma-separated list of individual expressions, 27646which may be either numbers or pointers. Their values are printed as 27647specified by @var{template}, exactly as a C program would do by 27648executing the code below: 27649 27650@smallexample 27651printf (@var{template}, @var{expressions}@dots{}); 27652@end smallexample 27653 27654As in @code{C} @code{printf}, ordinary characters in @var{template} 27655are printed verbatim, while @dfn{conversion specification} introduced 27656by the @samp{%} character cause subsequent @var{expressions} to be 27657evaluated, their values converted and formatted according to type and 27658style information encoded in the conversion specifications, and then 27659printed. 27660 27661For example, you can print two values in hex like this: 27662 27663@smallexample 27664printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo 27665@end smallexample 27666 27667@code{printf} supports all the standard @code{C} conversion 27668specifications, including the flags and modifiers between the @samp{%} 27669character and the conversion letter, with the following exceptions: 27670 27671@itemize @bullet 27672@item 27673The argument-ordering modifiers, such as @samp{2$}, are not supported. 27674 27675@item 27676The modifier @samp{*} is not supported for specifying precision or 27677width. 27678 27679@item 27680The @samp{'} flag (for separation of digits into groups according to 27681@code{LC_NUMERIC'}) is not supported. 27682 27683@item 27684The type modifiers @samp{hh}, @samp{j}, @samp{t}, and @samp{z} are not 27685supported. 27686 27687@item 27688The conversion letter @samp{n} (as in @samp{%n}) is not supported. 27689 27690@item 27691The conversion letters @samp{a} and @samp{A} are not supported. 27692@end itemize 27693 27694@noindent 27695Note that the @samp{ll} type modifier is supported only if the 27696underlying @code{C} implementation used to build @value{GDBN} supports 27697the @code{long long int} type, and the @samp{L} type modifier is 27698supported only if @code{long double} type is available. 27699 27700As in @code{C}, @code{printf} supports simple backslash-escape 27701sequences, such as @code{\n}, @samp{\t}, @samp{\\}, @samp{\"}, 27702@samp{\a}, and @samp{\f}, that consist of backslash followed by a 27703single character. Octal and hexadecimal escape sequences are not 27704supported. 27705 27706Additionally, @code{printf} supports conversion specifications for DFP 27707(@dfn{Decimal Floating Point}) types using the following length modifiers 27708together with a floating point specifier. 27709letters: 27710 27711@itemize @bullet 27712@item 27713@samp{H} for printing @code{Decimal32} types. 27714 27715@item 27716@samp{D} for printing @code{Decimal64} types. 27717 27718@item 27719@samp{DD} for printing @code{Decimal128} types. 27720@end itemize 27721 27722If the underlying @code{C} implementation used to build @value{GDBN} has 27723support for the three length modifiers for DFP types, other modifiers 27724such as width and precision will also be available for @value{GDBN} to use. 27725 27726In case there is no such @code{C} support, no additional modifiers will be 27727available and the value will be printed in the standard way. 27728 27729Here's an example of printing DFP types using the above conversion letters: 27730@smallexample 27731printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl 27732@end smallexample 27733 27734@anchor{eval} 27735@kindex eval 27736@item eval @var{template}, @var{expressions}@dots{} 27737Convert the values of one or more @var{expressions} under the control of 27738the string @var{template} to a command line, and call it. 27739 27740@end table 27741 27742@node Auto-loading sequences 27743@subsection Controlling auto-loading native @value{GDBN} scripts 27744@cindex native script auto-loading 27745 27746When a new object file is read (for example, due to the @code{file} 27747command, or because the inferior has loaded a shared library), 27748@value{GDBN} will look for the command file @file{@var{objfile}-gdb.gdb}. 27749@xref{Auto-loading extensions}. 27750 27751Auto-loading can be enabled or disabled, 27752and the list of auto-loaded scripts can be printed. 27753 27754@table @code 27755@anchor{set auto-load gdb-scripts} 27756@kindex set auto-load gdb-scripts 27757@item set auto-load gdb-scripts [on|off] 27758Enable or disable the auto-loading of canned sequences of commands scripts. 27759 27760@anchor{show auto-load gdb-scripts} 27761@kindex show auto-load gdb-scripts 27762@item show auto-load gdb-scripts 27763Show whether auto-loading of canned sequences of commands scripts is enabled or 27764disabled. 27765 27766@anchor{info auto-load gdb-scripts} 27767@kindex info auto-load gdb-scripts 27768@cindex print list of auto-loaded canned sequences of commands scripts 27769@item info auto-load gdb-scripts [@var{regexp}] 27770Print the list of all canned sequences of commands scripts that @value{GDBN} 27771auto-loaded. 27772@end table 27773 27774If @var{regexp} is supplied only canned sequences of commands scripts with 27775matching names are printed. 27776 27777@node Aliases 27778@section Command Aliases 27779@cindex aliases for commands 27780 27781Aliases allow you to define alternate spellings for existing commands. 27782For example, if a new @value{GDBN} command defined in Python 27783(@pxref{Python}) has a long name, it is handy to have an abbreviated 27784version of it that involves less typing. 27785 27786@value{GDBN} itself uses aliases. For example @samp{s} is an alias 27787of the @samp{step} command even though it is otherwise an ambiguous 27788abbreviation of other commands like @samp{set} and @samp{show}. 27789 27790Aliases are also used to provide shortened or more common versions 27791of multi-word commands. For example, @value{GDBN} provides the 27792@samp{tty} alias of the @samp{set inferior-tty} command. 27793 27794You can define a new alias with the @samp{alias} command. 27795 27796@table @code 27797 27798@kindex alias 27799@item alias [-a] [--] @var{alias} = @var{command} [@var{default-args}] 27800 27801@end table 27802 27803@var{alias} specifies the name of the new alias. Each word of 27804@var{alias} must consist of letters, numbers, dashes and underscores. 27805 27806@var{command} specifies the name of an existing command 27807that is being aliased. 27808 27809@var{command} can also be the name of an existing alias. In this 27810case, @var{command} cannot be an alias that has default arguments. 27811 27812The @samp{-a} option specifies that the new alias is an abbreviation 27813of the command. Abbreviations are not used in command completion. 27814 27815The @samp{--} option specifies the end of options, 27816and is useful when @var{alias} begins with a dash. 27817 27818You can specify @var{default-args} for your alias. These 27819@var{default-args} will be automatically added before the alias 27820arguments typed explicitly on the command line. 27821 27822For example, the below defines an alias @code{btfullall} that shows all local 27823variables and all frame arguments: 27824@smallexample 27825(@value{GDBP}) alias btfullall = backtrace -full -frame-arguments all 27826@end smallexample 27827 27828For more information about @var{default-args}, see @ref{Command 27829aliases default args, ,Default Arguments}. 27830 27831Here is a simple example showing how to make an abbreviation of a 27832command so that there is less to type. Suppose you were tired of 27833typing @samp{disas}, the current shortest unambiguous abbreviation of 27834the @samp{disassemble} command and you wanted an even shorter version 27835named @samp{di}. The following will accomplish this. 27836 27837@smallexample 27838(gdb) alias -a di = disas 27839@end smallexample 27840 27841Note that aliases are different from user-defined commands. With a 27842user-defined command, you also need to write documentation for it with 27843the @samp{document} command. An alias automatically picks up the 27844documentation of the existing command. 27845 27846Here is an example where we make @samp{elms} an abbreviation of 27847@samp{elements} in the @samp{set print elements} command. 27848This is to show that you can make an abbreviation of any part 27849of a command. 27850 27851@smallexample 27852(gdb) alias -a set print elms = set print elements 27853(gdb) alias -a show print elms = show print elements 27854(gdb) set p elms 20 27855(gdb) show p elms 27856Limit on string chars or array elements to print is 200. 27857@end smallexample 27858 27859Note that if you are defining an alias of a @samp{set} command, 27860and you want to have an alias for the corresponding @samp{show} 27861command, then you need to define the latter separately. 27862 27863Unambiguously abbreviated commands are allowed in @var{command} and 27864@var{alias}, just as they are normally. 27865 27866@smallexample 27867(gdb) alias -a set pr elms = set p ele 27868@end smallexample 27869 27870Finally, here is an example showing the creation of a one word 27871alias for a more complex command. 27872This creates alias @samp{spe} of the command @samp{set print elements}. 27873 27874@smallexample 27875(gdb) alias spe = set print elements 27876(gdb) spe 20 27877@end smallexample 27878 27879@menu 27880* Command aliases default args:: Default arguments for aliases 27881@end menu 27882 27883@node Command aliases default args 27884@subsection Default Arguments 27885@cindex aliases for commands, default arguments 27886 27887You can tell @value{GDBN} to always prepend some default arguments to 27888the list of arguments provided explicitly by the user when using a 27889user-defined alias. 27890 27891If you repeatedly use the same arguments or options for a command, you 27892can define an alias for this command and tell @value{GDBN} to 27893automatically prepend these arguments or options to the list of 27894arguments you type explicitly when using the alias@footnote{@value{GDBN} 27895could easily accept default arguments for pre-defined commands and aliases, 27896but it was deemed this would be confusing, and so is not allowed.}. 27897 27898For example, if you often use the command @code{thread apply all} 27899specifying to work on the threads in ascending order and to continue in case it 27900encounters an error, you can tell @value{GDBN} to automatically preprend 27901the @code{-ascending} and @code{-c} options by using: 27902 27903@smallexample 27904(@value{GDBP}) alias thread apply asc-all = thread apply all -ascending -c 27905@end smallexample 27906 27907Once you have defined this alias with its default args, any time you type 27908the @code{thread apply asc-all} followed by @code{some arguments}, 27909@value{GDBN} will execute @code{thread apply all -ascending -c some arguments}. 27910 27911To have even less to type, you can also define a one word alias: 27912@smallexample 27913(@value{GDBP}) alias t_a_c = thread apply all -ascending -c 27914@end smallexample 27915 27916As usual, unambiguous abbreviations can be used for @var{alias} 27917and @var{default-args}. 27918 27919The different aliases of a command do not share their default args. 27920For example, you define a new alias @code{bt_ALL} showing all possible 27921information and another alias @code{bt_SMALL} showing very limited information 27922using: 27923@smallexample 27924(@value{GDBP}) alias bt_ALL = backtrace -entry-values both -frame-arg all \ 27925 -past-main -past-entry -full 27926(@value{GDBP}) alias bt_SMALL = backtrace -entry-values no -frame-arg none \ 27927 -past-main off -past-entry off 27928@end smallexample 27929 27930(For more on using the @code{alias} command, see @ref{Aliases}.) 27931 27932Default args are not limited to the arguments and options of @var{command}, 27933but can specify nested commands if @var{command} accepts such a nested command 27934as argument. 27935For example, the below defines @code{faalocalsoftype} that lists the 27936frames having locals of a certain type, together with the matching 27937local vars: 27938@smallexample 27939(@value{GDBP}) alias faalocalsoftype = frame apply all info locals -q -t 27940(@value{GDBP}) faalocalsoftype int 27941#1 0x55554f5e in sleeper_or_burner (v=0xdf50) at sleepers.c:86 27942i = 0 27943ret = 21845 27944@end smallexample 27945 27946This is also very useful to define an alias for a set of nested @code{with} 27947commands to have a particular combination of temporary settings. For example, 27948the below defines the alias @code{pp10} that pretty prints an expression 27949argument, with a maximum of 10 elements if the expression is a string or 27950an array: 27951@smallexample 27952(@value{GDBP}) alias pp10 = with print pretty -- with print elements 10 -- print 27953@end smallexample 27954This defines the alias @code{pp10} as being a sequence of 3 commands. 27955The first part @code{with print pretty --} temporarily activates the setting 27956@code{set print pretty}, then launches the command that follows the separator 27957@code{--}. 27958The command following the first part is also a @code{with} command that 27959temporarily changes the setting @code{set print elements} to 10, then 27960launches the command that follows the second separator @code{--}. 27961The third part @code{print} is the command the @code{pp10} alias will launch, 27962using the temporary values of the settings and the arguments explicitly given 27963by the user. 27964For more information about the @code{with} command usage, 27965see @ref{Command Settings}. 27966 27967@c Python docs live in a separate file. 27968@include python.texi 27969 27970@c Guile docs live in a separate file. 27971@include guile.texi 27972 27973@node Auto-loading extensions 27974@section Auto-loading extensions 27975@cindex auto-loading extensions 27976 27977@value{GDBN} provides two mechanisms for automatically loading 27978extensions when a new object file is read (for example, due to the 27979@code{file} command, or because the inferior has loaded a shared 27980library): @file{@var{objfile}-gdb.@var{ext}} (@pxref{objfile-gdbdotext 27981file,,The @file{@var{objfile}-gdb.@var{ext}} file}) and the 27982@code{.debug_gdb_scripts} section of modern file formats like ELF 27983(@pxref{dotdebug_gdb_scripts section,,The @code{.debug_gdb_scripts} 27984section}). For a discussion of the differences between these two 27985approaches see @ref{Which flavor to choose?}. 27986 27987The auto-loading feature is useful for supplying application-specific 27988debugging commands and features. 27989 27990Auto-loading can be enabled or disabled, 27991and the list of auto-loaded scripts can be printed. 27992See the @samp{auto-loading} section of each extension language 27993for more information. 27994For @value{GDBN} command files see @ref{Auto-loading sequences}. 27995For Python files see @ref{Python Auto-loading}. 27996 27997Note that loading of this script file also requires accordingly configured 27998@code{auto-load safe-path} (@pxref{Auto-loading safe path}). 27999 28000@menu 28001* objfile-gdbdotext file:: The @file{@var{objfile}-gdb.@var{ext}} file 28002* dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section 28003* Which flavor to choose?:: Choosing between these approaches 28004@end menu 28005 28006@node objfile-gdbdotext file 28007@subsection The @file{@var{objfile}-gdb.@var{ext}} file 28008@cindex @file{@var{objfile}-gdb.gdb} 28009@cindex @file{@var{objfile}-gdb.py} 28010@cindex @file{@var{objfile}-gdb.scm} 28011 28012When a new object file is read, @value{GDBN} looks for a file named 28013@file{@var{objfile}-gdb.@var{ext}} (we call it @var{script-name} below), 28014where @var{objfile} is the object file's name and 28015where @var{ext} is the file extension for the extension language: 28016 28017@table @code 28018@item @file{@var{objfile}-gdb.gdb} 28019GDB's own command language 28020@item @file{@var{objfile}-gdb.py} 28021Python 28022@item @file{@var{objfile}-gdb.scm} 28023Guile 28024@end table 28025 28026@var{script-name} is formed by ensuring that the file name of @var{objfile} 28027is absolute, following all symlinks, and resolving @code{.} and @code{..} 28028components, and appending the @file{-gdb.@var{ext}} suffix. 28029If this file exists and is readable, @value{GDBN} will evaluate it as a 28030script in the specified extension language. 28031 28032If this file does not exist, then @value{GDBN} will look for 28033@var{script-name} file in all of the directories as specified below. 28034(On MS-Windows/MS-DOS, the drive letter of the executable's leading 28035directories is converted to a one-letter subdirectory, i.e.@: 28036@file{d:/usr/bin/} is converted to @file{/d/usr/bin/}, because Windows 28037filesystems disallow colons in file names.) 28038 28039Note that loading of these files requires an accordingly configured 28040@code{auto-load safe-path} (@pxref{Auto-loading safe path}). 28041 28042For object files using @file{.exe} suffix @value{GDBN} tries to load first the 28043scripts normally according to its @file{.exe} filename. But if no scripts are 28044found @value{GDBN} also tries script filenames matching the object file without 28045its @file{.exe} suffix. This @file{.exe} stripping is case insensitive and it 28046is attempted on any platform. This makes the script filenames compatible 28047between Unix and MS-Windows hosts. 28048 28049@table @code 28050@anchor{set auto-load scripts-directory} 28051@kindex set auto-load scripts-directory 28052@item set auto-load scripts-directory @r{[}@var{directories}@r{]} 28053Control @value{GDBN} auto-loaded scripts location. Multiple directory entries 28054may be delimited by the host platform path separator in use 28055(@samp{:} on Unix, @samp{;} on MS-Windows and MS-DOS). 28056 28057Each entry here needs to be covered also by the security setting 28058@code{set auto-load safe-path} (@pxref{set auto-load safe-path}). 28059 28060@anchor{with-auto-load-dir} 28061This variable defaults to @file{$debugdir:$datadir/auto-load}. The default 28062@code{set auto-load safe-path} value can be also overriden by @value{GDBN} 28063configuration option @option{--with-auto-load-dir}. 28064 28065Any reference to @file{$debugdir} will get replaced by 28066@var{debug-file-directory} value (@pxref{Separate Debug Files}) and any 28067reference to @file{$datadir} will get replaced by @var{data-directory} which is 28068determined at @value{GDBN} startup (@pxref{Data Files}). @file{$debugdir} and 28069@file{$datadir} must be placed as a directory component --- either alone or 28070delimited by @file{/} or @file{\} directory separators, depending on the host 28071platform. 28072 28073The list of directories uses path separator (@samp{:} on GNU and Unix 28074systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly 28075to the @env{PATH} environment variable. 28076 28077@anchor{show auto-load scripts-directory} 28078@kindex show auto-load scripts-directory 28079@item show auto-load scripts-directory 28080Show @value{GDBN} auto-loaded scripts location. 28081 28082@anchor{add-auto-load-scripts-directory} 28083@kindex add-auto-load-scripts-directory 28084@item add-auto-load-scripts-directory @r{[}@var{directories}@dots{}@r{]} 28085Add an entry (or list of entries) to the list of auto-loaded scripts locations. 28086Multiple entries may be delimited by the host platform path separator in use. 28087@end table 28088 28089@value{GDBN} does not track which files it has already auto-loaded this way. 28090@value{GDBN} will load the associated script every time the corresponding 28091@var{objfile} is opened. 28092So your @file{-gdb.@var{ext}} file should be careful to avoid errors if it 28093is evaluated more than once. 28094 28095@node dotdebug_gdb_scripts section 28096@subsection The @code{.debug_gdb_scripts} section 28097@cindex @code{.debug_gdb_scripts} section 28098 28099For systems using file formats like ELF and COFF, 28100when @value{GDBN} loads a new object file 28101it will look for a special section named @code{.debug_gdb_scripts}. 28102If this section exists, its contents is a list of null-terminated entries 28103specifying scripts to load. Each entry begins with a non-null prefix byte that 28104specifies the kind of entry, typically the extension language and whether the 28105script is in a file or inlined in @code{.debug_gdb_scripts}. 28106 28107The following entries are supported: 28108 28109@table @code 28110@item SECTION_SCRIPT_ID_PYTHON_FILE = 1 28111@item SECTION_SCRIPT_ID_SCHEME_FILE = 3 28112@item SECTION_SCRIPT_ID_PYTHON_TEXT = 4 28113@item SECTION_SCRIPT_ID_SCHEME_TEXT = 6 28114@end table 28115 28116@subsubsection Script File Entries 28117 28118If the entry specifies a file, @value{GDBN} will look for the file first 28119in the current directory and then along the source search path 28120(@pxref{Source Path, ,Specifying Source Directories}), 28121except that @file{$cdir} is not searched, since the compilation 28122directory is not relevant to scripts. 28123 28124File entries can be placed in section @code{.debug_gdb_scripts} with, 28125for example, this GCC macro for Python scripts. 28126 28127@example 28128/* Note: The "MS" section flags are to remove duplicates. */ 28129#define DEFINE_GDB_PY_SCRIPT(script_name) \ 28130 asm("\ 28131.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\ 28132.byte 1 /* Python */\n\ 28133.asciz \"" script_name "\"\n\ 28134.popsection \n\ 28135"); 28136@end example 28137 28138@noindent 28139For Guile scripts, replace @code{.byte 1} with @code{.byte 3}. 28140Then one can reference the macro in a header or source file like this: 28141 28142@example 28143DEFINE_GDB_PY_SCRIPT ("my-app-scripts.py") 28144@end example 28145 28146The script name may include directories if desired. 28147 28148Note that loading of this script file also requires accordingly configured 28149@code{auto-load safe-path} (@pxref{Auto-loading safe path}). 28150 28151If the macro invocation is put in a header, any application or library 28152using this header will get a reference to the specified script, 28153and with the use of @code{"MS"} attributes on the section, the linker 28154will remove duplicates. 28155 28156@subsubsection Script Text Entries 28157 28158Script text entries allow to put the executable script in the entry 28159itself instead of loading it from a file. 28160The first line of the entry, everything after the prefix byte and up to 28161the first newline (@code{0xa}) character, is the script name, and must not 28162contain any kind of space character, e.g., spaces or tabs. 28163The rest of the entry, up to the trailing null byte, is the script to 28164execute in the specified language. The name needs to be unique among 28165all script names, as @value{GDBN} executes each script only once based 28166on its name. 28167 28168Here is an example from file @file{py-section-script.c} in the @value{GDBN} 28169testsuite. 28170 28171@example 28172#include "symcat.h" 28173#include "gdb/section-scripts.h" 28174asm( 28175".pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n" 28176".byte " XSTRING (SECTION_SCRIPT_ID_PYTHON_TEXT) "\n" 28177".ascii \"gdb.inlined-script\\n\"\n" 28178".ascii \"class test_cmd (gdb.Command):\\n\"\n" 28179".ascii \" def __init__ (self):\\n\"\n" 28180".ascii \" super (test_cmd, self).__init__ (" 28181 "\\\"test-cmd\\\", gdb.COMMAND_OBSCURE)\\n\"\n" 28182".ascii \" def invoke (self, arg, from_tty):\\n\"\n" 28183".ascii \" print (\\\"test-cmd output, arg = %s\\\" % arg)\\n\"\n" 28184".ascii \"test_cmd ()\\n\"\n" 28185".byte 0\n" 28186".popsection\n" 28187); 28188@end example 28189 28190Loading of inlined scripts requires a properly configured 28191@code{auto-load safe-path} (@pxref{Auto-loading safe path}). 28192The path to specify in @code{auto-load safe-path} is the path of the file 28193containing the @code{.debug_gdb_scripts} section. 28194 28195@node Which flavor to choose? 28196@subsection Which flavor to choose? 28197 28198Given the multiple ways of auto-loading extensions, it might not always 28199be clear which one to choose. This section provides some guidance. 28200 28201@noindent 28202Benefits of the @file{-gdb.@var{ext}} way: 28203 28204@itemize @bullet 28205@item 28206Can be used with file formats that don't support multiple sections. 28207 28208@item 28209Ease of finding scripts for public libraries. 28210 28211Scripts specified in the @code{.debug_gdb_scripts} section are searched for 28212in the source search path. 28213For publicly installed libraries, e.g., @file{libstdc++}, there typically 28214isn't a source directory in which to find the script. 28215 28216@item 28217Doesn't require source code additions. 28218@end itemize 28219 28220@noindent 28221Benefits of the @code{.debug_gdb_scripts} way: 28222 28223@itemize @bullet 28224@item 28225Works with static linking. 28226 28227Scripts for libraries done the @file{-gdb.@var{ext}} way require an objfile to 28228trigger their loading. When an application is statically linked the only 28229objfile available is the executable, and it is cumbersome to attach all the 28230scripts from all the input libraries to the executable's 28231@file{-gdb.@var{ext}} script. 28232 28233@item 28234Works with classes that are entirely inlined. 28235 28236Some classes can be entirely inlined, and thus there may not be an associated 28237shared library to attach a @file{-gdb.@var{ext}} script to. 28238 28239@item 28240Scripts needn't be copied out of the source tree. 28241 28242In some circumstances, apps can be built out of large collections of internal 28243libraries, and the build infrastructure necessary to install the 28244@file{-gdb.@var{ext}} scripts in a place where @value{GDBN} can find them is 28245cumbersome. It may be easier to specify the scripts in the 28246@code{.debug_gdb_scripts} section as relative paths, and add a path to the 28247top of the source tree to the source search path. 28248@end itemize 28249 28250@node Multiple Extension Languages 28251@section Multiple Extension Languages 28252 28253The Guile and Python extension languages do not share any state, 28254and generally do not interfere with each other. 28255There are some things to be aware of, however. 28256 28257@subsection Python comes first 28258 28259Python was @value{GDBN}'s first extension language, and to avoid breaking 28260existing behaviour Python comes first. This is generally solved by the 28261``first one wins'' principle. @value{GDBN} maintains a list of enabled 28262extension languages, and when it makes a call to an extension language, 28263(say to pretty-print a value), it tries each in turn until an extension 28264language indicates it has performed the request (e.g., has returned the 28265pretty-printed form of a value). 28266This extends to errors while performing such requests: If an error happens 28267while, for example, trying to pretty-print an object then the error is 28268reported and any following extension languages are not tried. 28269 28270@node Interpreters 28271@chapter Command Interpreters 28272@cindex command interpreters 28273 28274@value{GDBN} supports multiple command interpreters, and some command 28275infrastructure to allow users or user interface writers to switch 28276between interpreters or run commands in other interpreters. 28277 28278@value{GDBN} currently supports two command interpreters, the console 28279interpreter (sometimes called the command-line interpreter or @sc{cli}) 28280and the machine interface interpreter (or @sc{gdb/mi}). This manual 28281describes both of these interfaces in great detail. 28282 28283By default, @value{GDBN} will start with the console interpreter. 28284However, the user may choose to start @value{GDBN} with another 28285interpreter by specifying the @option{-i} or @option{--interpreter} 28286startup options. Defined interpreters include: 28287 28288@table @code 28289@item console 28290@cindex console interpreter 28291The traditional console or command-line interpreter. This is the most often 28292used interpreter with @value{GDBN}. With no interpreter specified at runtime, 28293@value{GDBN} will use this interpreter. 28294 28295@item mi 28296@cindex mi interpreter 28297The newest @sc{gdb/mi} interface (currently @code{mi3}). Used primarily 28298by programs wishing to use @value{GDBN} as a backend for a debugger GUI 28299or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi} 28300Interface}. 28301 28302@item mi3 28303@cindex mi3 interpreter 28304The @sc{gdb/mi} interface introduced in @value{GDBN} 9.1. 28305 28306@item mi2 28307@cindex mi2 interpreter 28308The @sc{gdb/mi} interface introduced in @value{GDBN} 6.0. 28309 28310@item mi1 28311@cindex mi1 interpreter 28312The @sc{gdb/mi} interface introduced in @value{GDBN} 5.1. 28313 28314@end table 28315 28316@cindex invoke another interpreter 28317 28318@kindex interpreter-exec 28319You may execute commands in any interpreter from the current 28320interpreter using the appropriate command. If you are running the 28321console interpreter, simply use the @code{interpreter-exec} command: 28322 28323@smallexample 28324interpreter-exec mi "-data-list-register-names" 28325@end smallexample 28326 28327@sc{gdb/mi} has a similar command, although it is only available in versions of 28328@value{GDBN} which support @sc{gdb/mi} version 2 (or greater). 28329 28330Note that @code{interpreter-exec} only changes the interpreter for the 28331duration of the specified command. It does not change the interpreter 28332permanently. 28333 28334@cindex start a new independent interpreter 28335 28336Although you may only choose a single interpreter at startup, it is 28337possible to run an independent interpreter on a specified input/output 28338device (usually a tty). 28339 28340For example, consider a debugger GUI or IDE that wants to provide a 28341@value{GDBN} console view. It may do so by embedding a terminal 28342emulator widget in its GUI, starting @value{GDBN} in the traditional 28343command-line mode with stdin/stdout/stderr redirected to that 28344terminal, and then creating an MI interpreter running on a specified 28345input/output device. The console interpreter created by @value{GDBN} 28346at startup handles commands the user types in the terminal widget, 28347while the GUI controls and synchronizes state with @value{GDBN} using 28348the separate MI interpreter. 28349 28350To start a new secondary @dfn{user interface} running MI, use the 28351@code{new-ui} command: 28352 28353@kindex new-ui 28354@cindex new user interface 28355@smallexample 28356new-ui @var{interpreter} @var{tty} 28357@end smallexample 28358 28359The @var{interpreter} parameter specifies the interpreter to run. 28360This accepts the same values as the @code{interpreter-exec} command. 28361For example, @samp{console}, @samp{mi}, @samp{mi2}, etc. The 28362@var{tty} parameter specifies the name of the bidirectional file the 28363interpreter uses for input/output, usually the name of a 28364pseudoterminal slave on Unix systems. For example: 28365 28366@smallexample 28367(@value{GDBP}) new-ui mi /dev/pts/9 28368@end smallexample 28369 28370@noindent 28371runs an MI interpreter on @file{/dev/pts/9}. 28372 28373@node TUI 28374@chapter @value{GDBN} Text User Interface 28375@cindex TUI 28376@cindex Text User Interface 28377 28378The @value{GDBN} Text User Interface (TUI) is a terminal 28379interface which uses the @code{curses} library to show the source 28380file, the assembly output, the program registers and @value{GDBN} 28381commands in separate text windows. The TUI mode is supported only 28382on platforms where a suitable version of the @code{curses} library 28383is available. 28384 28385The TUI mode is enabled by default when you invoke @value{GDBN} as 28386@samp{@value{GDBP} -tui}. 28387You can also switch in and out of TUI mode while @value{GDBN} runs by 28388using various TUI commands and key bindings, such as @command{tui 28389enable} or @kbd{C-x C-a}. @xref{TUI Commands, ,TUI Commands}, and 28390@ref{TUI Keys, ,TUI Key Bindings}. 28391 28392@menu 28393* TUI Overview:: TUI overview 28394* TUI Keys:: TUI key bindings 28395* TUI Single Key Mode:: TUI single key mode 28396* TUI Mouse Support:: TUI mouse support 28397* TUI Commands:: TUI-specific commands 28398* TUI Configuration:: TUI configuration variables 28399@end menu 28400 28401@node TUI Overview 28402@section TUI Overview 28403 28404In TUI mode, @value{GDBN} can display several text windows: 28405 28406@table @emph 28407@item command 28408This window is the @value{GDBN} command window with the @value{GDBN} 28409prompt and the @value{GDBN} output. The @value{GDBN} input is still 28410managed using readline. 28411 28412@item source 28413The source window shows the source file of the program. The current 28414line and active breakpoints are displayed in this window. 28415 28416@item assembly 28417The assembly window shows the disassembly output of the program. 28418 28419@item register 28420This window shows the processor registers. Registers are highlighted 28421when their values change. 28422@end table 28423 28424The source and assembly windows show the current program position 28425by highlighting the current line and marking it with a @samp{>} marker. 28426Breakpoints are indicated with two markers. The first marker 28427indicates the breakpoint type: 28428 28429@table @code 28430@item B 28431Breakpoint which was hit at least once. 28432 28433@item b 28434Breakpoint which was never hit. 28435 28436@item H 28437Hardware breakpoint which was hit at least once. 28438 28439@item h 28440Hardware breakpoint which was never hit. 28441@end table 28442 28443The second marker indicates whether the breakpoint is enabled or not: 28444 28445@table @code 28446@item + 28447Breakpoint is enabled. 28448 28449@item - 28450Breakpoint is disabled. 28451@end table 28452 28453The source, assembly and register windows are updated when the current 28454thread changes, when the frame changes, or when the program counter 28455changes. 28456 28457These windows are not all visible at the same time. The command 28458window is always visible. The others can be arranged in several 28459layouts: 28460 28461@itemize @bullet 28462@item 28463source only, 28464 28465@item 28466assembly only, 28467 28468@item 28469source and assembly, 28470 28471@item 28472source and registers, or 28473 28474@item 28475assembly and registers. 28476@end itemize 28477 28478These are the standard layouts, but other layouts can be defined. 28479 28480A status line above the command window shows the following information: 28481 28482@table @emph 28483@item target 28484Indicates the current @value{GDBN} target. 28485(@pxref{Targets, ,Specifying a Debugging Target}). 28486 28487@item process 28488Gives the current process or thread number. 28489When no process is being debugged, this field is set to @code{No process}. 28490 28491@item function 28492Gives the current function name for the selected frame. 28493The name is demangled if demangling is turned on (@pxref{Print Settings}). 28494When there is no symbol corresponding to the current program counter, 28495the string @code{??} is displayed. 28496 28497@item line 28498Indicates the current line number for the selected frame. 28499When the current line number is not known, the string @code{??} is displayed. 28500 28501@item pc 28502Indicates the current program counter address. 28503@end table 28504 28505@node TUI Keys 28506@section TUI Key Bindings 28507@cindex TUI key bindings 28508 28509The TUI installs several key bindings in the readline keymaps 28510@ifset SYSTEM_READLINE 28511(@pxref{Command Line Editing, , , rluserman, GNU Readline Library}). 28512@end ifset 28513@ifclear SYSTEM_READLINE 28514(@pxref{Command Line Editing}). 28515@end ifclear 28516The following key bindings are installed for both TUI mode and the 28517@value{GDBN} standard mode. 28518 28519@table @kbd 28520@kindex C-x C-a 28521@item C-x C-a 28522@kindex C-x a 28523@itemx C-x a 28524@kindex C-x A 28525@itemx C-x A 28526Enter or leave the TUI mode. When leaving the TUI mode, 28527the curses window management stops and @value{GDBN} operates using 28528its standard mode, writing on the terminal directly. When reentering 28529the TUI mode, control is given back to the curses windows. 28530The screen is then refreshed. 28531 28532This key binding uses the bindable Readline function 28533@code{tui-switch-mode}. 28534 28535@kindex C-x 1 28536@item C-x 1 28537Use a TUI layout with only one window. The layout will 28538either be @samp{source} or @samp{assembly}. When the TUI mode 28539is not active, it will switch to the TUI mode. 28540 28541Think of this key binding as the Emacs @kbd{C-x 1} binding. 28542 28543This key binding uses the bindable Readline function 28544@code{tui-delete-other-windows}. 28545 28546@kindex C-x 2 28547@item C-x 2 28548Use a TUI layout with at least two windows. When the current 28549layout already has two windows, the next layout with two windows is used. 28550When a new layout is chosen, one window will always be common to the 28551previous layout and the new one. 28552 28553Think of it as the Emacs @kbd{C-x 2} binding. 28554 28555This key binding uses the bindable Readline function 28556@code{tui-change-windows}. 28557 28558@kindex C-x o 28559@item C-x o 28560Change the active window. The TUI associates several key bindings 28561(like scrolling and arrow keys) with the active window. This command 28562gives the focus to the next TUI window. 28563 28564Think of it as the Emacs @kbd{C-x o} binding. 28565 28566This key binding uses the bindable Readline function 28567@code{tui-other-window}. 28568 28569@kindex C-x s 28570@item C-x s 28571Switch in and out of the TUI SingleKey mode that binds single 28572keys to @value{GDBN} commands (@pxref{TUI Single Key Mode}). 28573 28574This key binding uses the bindable Readline function 28575@code{next-keymap}. 28576@end table 28577 28578The following key bindings only work in the TUI mode: 28579 28580@table @asis 28581@kindex PgUp 28582@item @key{PgUp} 28583Scroll the active window one page up. 28584 28585@kindex PgDn 28586@item @key{PgDn} 28587Scroll the active window one page down. 28588 28589@kindex Up 28590@item @key{Up} 28591Scroll the active window one line up. 28592 28593@kindex Down 28594@item @key{Down} 28595Scroll the active window one line down. 28596 28597@kindex Left 28598@item @key{Left} 28599Scroll the active window one column left. 28600 28601@kindex Right 28602@item @key{Right} 28603Scroll the active window one column right. 28604 28605@kindex C-L 28606@item @kbd{C-L} 28607Refresh the screen. 28608@end table 28609 28610Because the arrow keys scroll the active window in the TUI mode, they 28611are not available for their normal use by readline unless the command 28612window has the focus. When another window is active, you must use 28613other readline key bindings such as @kbd{C-p}, @kbd{C-n}, @kbd{C-b} 28614and @kbd{C-f} to control the command window. 28615 28616@node TUI Single Key Mode 28617@section TUI Single Key Mode 28618@cindex TUI single key mode 28619 28620The TUI also provides a @dfn{SingleKey} mode, which binds several 28621frequently used @value{GDBN} commands to single keys. Type @kbd{C-x s} to 28622switch into this mode, where the following key bindings are used: 28623 28624@table @kbd 28625@kindex c @r{(SingleKey TUI key)} 28626@item c 28627continue 28628 28629@kindex d @r{(SingleKey TUI key)} 28630@item d 28631down 28632 28633@kindex f @r{(SingleKey TUI key)} 28634@item f 28635finish 28636 28637@kindex n @r{(SingleKey TUI key)} 28638@item n 28639next 28640 28641@kindex o @r{(SingleKey TUI key)} 28642@item o 28643nexti. The shortcut letter @samp{o} stands for ``step Over''. 28644 28645@kindex q @r{(SingleKey TUI key)} 28646@item q 28647exit the SingleKey mode. 28648 28649@kindex r @r{(SingleKey TUI key)} 28650@item r 28651run 28652 28653@kindex s @r{(SingleKey TUI key)} 28654@item s 28655step 28656 28657@kindex i @r{(SingleKey TUI key)} 28658@item i 28659stepi. The shortcut letter @samp{i} stands for ``step Into''. 28660 28661@kindex u @r{(SingleKey TUI key)} 28662@item u 28663up 28664 28665@kindex v @r{(SingleKey TUI key)} 28666@item v 28667info locals 28668 28669@kindex w @r{(SingleKey TUI key)} 28670@item w 28671where 28672@end table 28673 28674Other keys temporarily switch to the @value{GDBN} command prompt. 28675The key that was pressed is inserted in the editing buffer so that 28676it is possible to type most @value{GDBN} commands without interaction 28677with the TUI SingleKey mode. Once the command is entered the TUI 28678SingleKey mode is restored. The only way to permanently leave 28679this mode is by typing @kbd{q} or @kbd{C-x s}. 28680 28681@cindex SingleKey keymap name 28682If @value{GDBN} was built with Readline 8.0 or later, the TUI 28683SingleKey keymap will be named @samp{SingleKey}. This can be used in 28684@file{.inputrc} to add additional bindings to this keymap. 28685 28686@node TUI Mouse Support 28687@section TUI Mouse Support 28688@cindex TUI mouse support 28689 28690If the curses library supports the mouse, the TUI supports mouse 28691actions. 28692 28693The mouse wheel scrolls the appropriate window under the mouse cursor. 28694 28695The TUI itself does not directly support copying/pasting with the 28696mouse. However, on Unix terminals, you can typically press and hold 28697the @key{SHIFT} key on your keyboard to temporarily bypass 28698@value{GDBN}'s TUI and access the terminal's native mouse copy/paste 28699functionality (commonly, click-drag-release or double-click to select 28700text, middle-click to paste). This copy/paste works with the 28701terminal's selection buffer, as opposed to the TUI's buffer. 28702 28703@node TUI Commands 28704@section TUI-specific Commands 28705@cindex TUI commands 28706 28707The TUI has specific commands to control the text windows. 28708These commands are always available, even when @value{GDBN} is not in 28709the TUI mode. When @value{GDBN} is in the standard mode, most 28710of these commands will automatically switch to the TUI mode. 28711 28712Note that if @value{GDBN}'s @code{stdout} is not connected to a 28713terminal, or @value{GDBN} has been started with the machine interface 28714interpreter (@pxref{GDB/MI, ,The @sc{gdb/mi} Interface}), most of 28715these commands will fail with an error, because it would not be 28716possible or desirable to enable curses window management. 28717 28718@table @code 28719@item tui enable 28720@kindex tui enable 28721Activate TUI mode. The last active TUI window layout will be used if 28722TUI mode has previously been used in the current debugging session, 28723otherwise a default layout is used. 28724 28725@item tui disable 28726@kindex tui disable 28727Disable TUI mode, returning to the console interpreter. 28728 28729@item info win 28730@kindex info win 28731List and give the size of all displayed windows. 28732 28733@item tui new-layout @var{name} @var{window} @var{weight} @r{[}@var{window} @var{weight}@dots{}@r{]} 28734@kindex tui new-layout 28735Create a new TUI layout. The new layout will be named @var{name}, and 28736can be accessed using the @code{layout} command (see below). 28737 28738Each @var{window} parameter is either the name of a window to display, 28739or a window description. The windows will be displayed from top to 28740bottom in the order listed. 28741 28742The names of the windows are the same as the ones given to the 28743@code{focus} command (see below); additional, the @code{status} 28744window can be specified. Note that, because it is of fixed height, 28745the weight assigned to the status window is of no importance. It is 28746conventional to use @samp{0} here. 28747 28748A window description looks a bit like an invocation of @code{tui 28749new-layout}, and is of the form 28750@{@r{[}@code{-horizontal}@r{]}@var{window} @var{weight} @r{[}@var{window} @var{weight}@dots{}@r{]}@}. 28751 28752This specifies a sub-layout. If @code{-horizontal} is given, the 28753windows in this description will be arranged side-by-side, rather than 28754top-to-bottom. 28755 28756Each @var{weight} is an integer. It is the weight of this window 28757relative to all the other windows in the layout. These numbers are 28758used to calculate how much of the screen is given to each window. 28759 28760For example: 28761 28762@example 28763(gdb) tui new-layout example src 1 regs 1 status 0 cmd 1 28764@end example 28765 28766Here, the new layout is called @samp{example}. It shows the source 28767and register windows, followed by the status window, and then finally 28768the command window. The non-status windows all have the same weight, 28769so the terminal will be split into three roughly equal sections. 28770 28771Here is a more complex example, showing a horizontal layout: 28772 28773@example 28774(gdb) tui new-layout example @{-horizontal src 1 asm 1@} 2 status 0 cmd 1 28775@end example 28776 28777This will result in side-by-side source and assembly windows; with the 28778status and command window being beneath these, filling the entire 28779width of the terminal. Because they have weight 2, the source and 28780assembly windows will be twice the height of the command window. 28781 28782@item layout @var{name} 28783@kindex layout 28784Changes which TUI windows are displayed. The @var{name} parameter 28785controls which layout is shown. It can be either one of the built-in 28786layout names, or the name of a layout defined by the user using 28787@code{tui new-layout}. 28788 28789The built-in layouts are as follows: 28790 28791@table @code 28792@item next 28793Display the next layout. 28794 28795@item prev 28796Display the previous layout. 28797 28798@item src 28799Display the source and command windows. 28800 28801@item asm 28802Display the assembly and command windows. 28803 28804@item split 28805Display the source, assembly, and command windows. 28806 28807@item regs 28808When in @code{src} layout display the register, source, and command 28809windows. When in @code{asm} or @code{split} layout display the 28810register, assembler, and command windows. 28811@end table 28812 28813@item focus @var{name} 28814@kindex focus 28815Changes which TUI window is currently active for scrolling. The 28816@var{name} parameter can be any of the following: 28817 28818@table @code 28819@item next 28820Make the next window active for scrolling. 28821 28822@item prev 28823Make the previous window active for scrolling. 28824 28825@item src 28826Make the source window active for scrolling. 28827 28828@item asm 28829Make the assembly window active for scrolling. 28830 28831@item regs 28832Make the register window active for scrolling. 28833 28834@item cmd 28835Make the command window active for scrolling. 28836@end table 28837 28838@item refresh 28839@kindex refresh 28840Refresh the screen. This is similar to typing @kbd{C-L}. 28841 28842@item tui reg @var{group} 28843@kindex tui reg 28844Changes the register group displayed in the tui register window to 28845@var{group}. If the register window is not currently displayed this 28846command will cause the register window to be displayed. The list of 28847register groups, as well as their order is target specific. The 28848following groups are available on most targets: 28849@table @code 28850@item next 28851Repeatedly selecting this group will cause the display to cycle 28852through all of the available register groups. 28853 28854@item prev 28855Repeatedly selecting this group will cause the display to cycle 28856through all of the available register groups in the reverse order to 28857@var{next}. 28858 28859@item general 28860Display the general registers. 28861@item float 28862Display the floating point registers. 28863@item system 28864Display the system registers. 28865@item vector 28866Display the vector registers. 28867@item all 28868Display all registers. 28869@end table 28870 28871@item update 28872@kindex update 28873Update the source window and the current execution point. 28874 28875@item winheight @var{name} +@var{count} 28876@itemx winheight @var{name} -@var{count} 28877@kindex winheight 28878Change the height of the window @var{name} by @var{count} 28879lines. Positive counts increase the height, while negative counts 28880decrease it. The @var{name} parameter can be one of @code{src} (the 28881source window), @code{cmd} (the command window), @code{asm} (the 28882disassembly window), or @code{regs} (the register display window). 28883@end table 28884 28885@node TUI Configuration 28886@section TUI Configuration Variables 28887@cindex TUI configuration variables 28888 28889Several configuration variables control the appearance of TUI windows. 28890 28891@table @code 28892@item set tui border-kind @var{kind} 28893@kindex set tui border-kind 28894Select the border appearance for the source, assembly and register windows. 28895The possible values are the following: 28896@table @code 28897@item space 28898Use a space character to draw the border. 28899 28900@item ascii 28901Use @sc{ascii} characters @samp{+}, @samp{-} and @samp{|} to draw the border. 28902 28903@item acs 28904Use the Alternate Character Set to draw the border. The border is 28905drawn using character line graphics if the terminal supports them. 28906@end table 28907 28908@item set tui border-mode @var{mode} 28909@kindex set tui border-mode 28910@itemx set tui active-border-mode @var{mode} 28911@kindex set tui active-border-mode 28912Select the display attributes for the borders of the inactive windows 28913or the active window. The @var{mode} can be one of the following: 28914@table @code 28915@item normal 28916Use normal attributes to display the border. 28917 28918@item standout 28919Use standout mode. 28920 28921@item reverse 28922Use reverse video mode. 28923 28924@item half 28925Use half bright mode. 28926 28927@item half-standout 28928Use half bright and standout mode. 28929 28930@item bold 28931Use extra bright or bold mode. 28932 28933@item bold-standout 28934Use extra bright or bold and standout mode. 28935@end table 28936 28937@item set tui tab-width @var{nchars} 28938@kindex set tui tab-width 28939@kindex tabset 28940Set the width of tab stops to be @var{nchars} characters. This 28941setting affects the display of TAB characters in the source and 28942assembly windows. 28943 28944@item set tui compact-source @r{[}on@r{|}off@r{]} 28945@kindex set tui compact-source 28946Set whether the TUI source window is displayed in ``compact'' form. 28947The default display uses more space for line numbers and starts the 28948source text at the next tab stop; the compact display uses only as 28949much space as is needed for the line numbers in the current file, and 28950only a single space to separate the line numbers from the source. 28951@end table 28952 28953Note that the colors of the TUI borders can be controlled using the 28954appropriate @code{set style} commands. @xref{Output Styling}. 28955 28956@node Emacs 28957@chapter Using @value{GDBN} under @sc{gnu} Emacs 28958 28959@cindex Emacs 28960@cindex @sc{gnu} Emacs 28961A special interface allows you to use @sc{gnu} Emacs to view (and 28962edit) the source files for the program you are debugging with 28963@value{GDBN}. 28964 28965To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the 28966executable file you want to debug as an argument. This command starts 28967@value{GDBN} as a subprocess of Emacs, with input and output through a newly 28968created Emacs buffer. 28969@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.) 28970 28971Running @value{GDBN} under Emacs can be just like running @value{GDBN} normally except for two 28972things: 28973 28974@itemize @bullet 28975@item 28976All ``terminal'' input and output goes through an Emacs buffer, called 28977the GUD buffer. 28978 28979This applies both to @value{GDBN} commands and their output, and to the input 28980and output done by the program you are debugging. 28981 28982This is useful because it means that you can copy the text of previous 28983commands and input them again; you can even use parts of the output 28984in this way. 28985 28986All the facilities of Emacs' Shell mode are available for interacting 28987with your program. In particular, you can send signals the usual 28988way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a 28989stop. 28990 28991@item 28992@value{GDBN} displays source code through Emacs. 28993 28994Each time @value{GDBN} displays a stack frame, Emacs automatically finds the 28995source file for that frame and puts an arrow (@samp{=>}) at the 28996left margin of the current line. Emacs uses a separate buffer for 28997source display, and splits the screen to show both your @value{GDBN} session 28998and the source. 28999 29000Explicit @value{GDBN} @code{list} or search commands still produce output as 29001usual, but you probably have no reason to use them from Emacs. 29002@end itemize 29003 29004We call this @dfn{text command mode}. Emacs 22.1, and later, also uses 29005a graphical mode, enabled by default, which provides further buffers 29006that can control the execution and describe the state of your program. 29007@xref{GDB Graphical Interface,,, Emacs, The @sc{gnu} Emacs Manual}. 29008 29009If you specify an absolute file name when prompted for the @kbd{M-x 29010gdb} argument, then Emacs sets your current working directory to where 29011your program resides. If you only specify the file name, then Emacs 29012sets your current working directory to the directory associated 29013with the previous buffer. In this case, @value{GDBN} may find your 29014program by searching your environment's @env{PATH} variable, but on 29015some operating systems it might not find the source. So, although the 29016@value{GDBN} input and output session proceeds normally, the auxiliary 29017buffer does not display the current source and line of execution. 29018 29019The initial working directory of @value{GDBN} is printed on the top 29020line of the GUD buffer and this serves as a default for the commands 29021that specify files for @value{GDBN} to operate on. @xref{Files, 29022,Commands to Specify Files}. 29023 29024By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you 29025need to call @value{GDBN} by a different name (for example, if you 29026keep several configurations around, with different names) you can 29027customize the Emacs variable @code{gud-gdb-command-name} to run the 29028one you want. 29029 29030In the GUD buffer, you can use these special Emacs commands in 29031addition to the standard Shell mode commands: 29032 29033@table @kbd 29034@item C-h m 29035Describe the features of Emacs' GUD Mode. 29036 29037@item C-c C-s 29038Execute to another source line, like the @value{GDBN} @code{step} command; also 29039update the display window to show the current file and location. 29040 29041@item C-c C-n 29042Execute to next source line in this function, skipping all function 29043calls, like the @value{GDBN} @code{next} command. Then update the display window 29044to show the current file and location. 29045 29046@item C-c C-i 29047Execute one instruction, like the @value{GDBN} @code{stepi} command; update 29048display window accordingly. 29049 29050@item C-c C-f 29051Execute until exit from the selected stack frame, like the @value{GDBN} 29052@code{finish} command. 29053 29054@item C-c C-r 29055Continue execution of your program, like the @value{GDBN} @code{continue} 29056command. 29057 29058@item C-c < 29059Go up the number of frames indicated by the numeric argument 29060(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}), 29061like the @value{GDBN} @code{up} command. 29062 29063@item C-c > 29064Go down the number of frames indicated by the numeric argument, like the 29065@value{GDBN} @code{down} command. 29066@end table 29067 29068In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break}) 29069tells @value{GDBN} to set a breakpoint on the source line point is on. 29070 29071In text command mode, if you type @kbd{M-x speedbar}, Emacs displays a 29072separate frame which shows a backtrace when the GUD buffer is current. 29073Move point to any frame in the stack and type @key{RET} to make it 29074become the current frame and display the associated source in the 29075source buffer. Alternatively, click @kbd{Mouse-2} to make the 29076selected frame become the current one. In graphical mode, the 29077speedbar displays watch expressions. 29078 29079If you accidentally delete the source-display buffer, an easy way to get 29080it back is to type the command @code{f} in the @value{GDBN} buffer, to 29081request a frame display; when you run under Emacs, this recreates 29082the source buffer if necessary to show you the context of the current 29083frame. 29084 29085The source files displayed in Emacs are in ordinary Emacs buffers 29086which are visiting the source files in the usual way. You can edit 29087the files with these buffers if you wish; but keep in mind that @value{GDBN} 29088communicates with Emacs in terms of line numbers. If you add or 29089delete lines from the text, the line numbers that @value{GDBN} knows cease 29090to correspond properly with the code. 29091 29092A more detailed description of Emacs' interaction with @value{GDBN} is 29093given in the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} 29094Emacs Manual}). 29095 29096@node GDB/MI 29097@chapter The @sc{gdb/mi} Interface 29098 29099@unnumberedsec Function and Purpose 29100 29101@cindex @sc{gdb/mi}, its purpose 29102@sc{gdb/mi} is a line based machine oriented text interface to 29103@value{GDBN} and is activated by specifying using the 29104@option{--interpreter} command line option (@pxref{Mode Options}). It 29105is specifically intended to support the development of systems which 29106use the debugger as just one small component of a larger system. 29107 29108This chapter is a specification of the @sc{gdb/mi} interface. It is written 29109in the form of a reference manual. 29110 29111Note that @sc{gdb/mi} is still under construction, so some of the 29112features described below are incomplete and subject to change 29113(@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}). 29114 29115@unnumberedsec Notation and Terminology 29116 29117@cindex notational conventions, for @sc{gdb/mi} 29118This chapter uses the following notation: 29119 29120@itemize @bullet 29121@item 29122@code{|} separates two alternatives. 29123 29124@item 29125@code{[ @var{something} ]} indicates that @var{something} is optional: 29126it may or may not be given. 29127 29128@item 29129@code{( @var{group} )*} means that @var{group} inside the parentheses 29130may repeat zero or more times. 29131 29132@item 29133@code{( @var{group} )+} means that @var{group} inside the parentheses 29134may repeat one or more times. 29135 29136@item 29137@code{"@var{string}"} means a literal @var{string}. 29138@end itemize 29139 29140@ignore 29141@heading Dependencies 29142@end ignore 29143 29144@menu 29145* GDB/MI General Design:: 29146* GDB/MI Command Syntax:: 29147* GDB/MI Compatibility with CLI:: 29148* GDB/MI Development and Front Ends:: 29149* GDB/MI Output Records:: 29150* GDB/MI Simple Examples:: 29151* GDB/MI Command Description Format:: 29152* GDB/MI Breakpoint Commands:: 29153* GDB/MI Catchpoint Commands:: 29154* GDB/MI Program Context:: 29155* GDB/MI Thread Commands:: 29156* GDB/MI Ada Tasking Commands:: 29157* GDB/MI Program Execution:: 29158* GDB/MI Stack Manipulation:: 29159* GDB/MI Variable Objects:: 29160* GDB/MI Data Manipulation:: 29161* GDB/MI Tracepoint Commands:: 29162* GDB/MI Symbol Query:: 29163* GDB/MI File Commands:: 29164@ignore 29165* GDB/MI Kod Commands:: 29166* GDB/MI Memory Overlay Commands:: 29167* GDB/MI Signal Handling Commands:: 29168@end ignore 29169* GDB/MI Target Manipulation:: 29170* GDB/MI File Transfer Commands:: 29171* GDB/MI Ada Exceptions Commands:: 29172* GDB/MI Support Commands:: 29173* GDB/MI Miscellaneous Commands:: 29174@end menu 29175 29176@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 29177@node GDB/MI General Design 29178@section @sc{gdb/mi} General Design 29179@cindex GDB/MI General Design 29180 29181Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three 29182parts---commands sent to @value{GDBN}, responses to those commands 29183and notifications. Each command results in exactly one response, 29184indicating either successful completion of the command, or an error. 29185For the commands that do not resume the target, the response contains the 29186requested information. For the commands that resume the target, the 29187response only indicates whether the target was successfully resumed. 29188Notifications is the mechanism for reporting changes in the state of the 29189target, or in @value{GDBN} state, that cannot conveniently be associated with 29190a command and reported as part of that command response. 29191 29192The important examples of notifications are: 29193@itemize @bullet 29194 29195@item 29196Exec notifications. These are used to report changes in 29197target state---when a target is resumed, or stopped. It would not 29198be feasible to include this information in response of resuming 29199commands, because one resume commands can result in multiple events in 29200different threads. Also, quite some time may pass before any event 29201happens in the target, while a frontend needs to know whether the resuming 29202command itself was successfully executed. 29203 29204@item 29205Console output, and status notifications. Console output 29206notifications are used to report output of CLI commands, as well as 29207diagnostics for other commands. Status notifications are used to 29208report the progress of a long-running operation. Naturally, including 29209this information in command response would mean no output is produced 29210until the command is finished, which is undesirable. 29211 29212@item 29213General notifications. Commands may have various side effects on 29214the @value{GDBN} or target state beyond their official purpose. For example, 29215a command may change the selected thread. Although such changes can 29216be included in command response, using notification allows for more 29217orthogonal frontend design. 29218 29219@end itemize 29220 29221There's no guarantee that whenever an MI command reports an error, 29222@value{GDBN} or the target are in any specific state, and especially, 29223the state is not reverted to the state before the MI command was 29224processed. Therefore, whenever an MI command results in an error, 29225we recommend that the frontend refreshes all the information shown in 29226the user interface. 29227 29228 29229@menu 29230* Context management:: 29231* Asynchronous and non-stop modes:: 29232* Thread groups:: 29233@end menu 29234 29235@node Context management 29236@subsection Context management 29237 29238@subsubsection Threads and Frames 29239 29240In most cases when @value{GDBN} accesses the target, this access is 29241done in context of a specific thread and frame (@pxref{Frames}). 29242Often, even when accessing global data, the target requires that a thread 29243be specified. The CLI interface maintains the selected thread and frame, 29244and supplies them to target on each command. This is convenient, 29245because a command line user would not want to specify that information 29246explicitly on each command, and because user interacts with 29247@value{GDBN} via a single terminal, so no confusion is possible as 29248to what thread and frame are the current ones. 29249 29250In the case of MI, the concept of selected thread and frame is less 29251useful. First, a frontend can easily remember this information 29252itself. Second, a graphical frontend can have more than one window, 29253each one used for debugging a different thread, and the frontend might 29254want to access additional threads for internal purposes. This 29255increases the risk that by relying on implicitly selected thread, the 29256frontend may be operating on a wrong one. Therefore, each MI command 29257should explicitly specify which thread and frame to operate on. To 29258make it possible, each MI command accepts the @samp{--thread} and 29259@samp{--frame} options, the value to each is @value{GDBN} global 29260identifier for thread and frame to operate on. 29261 29262Usually, each top-level window in a frontend allows the user to select 29263a thread and a frame, and remembers the user selection for further 29264operations. However, in some cases @value{GDBN} may suggest that the 29265current thread or frame be changed. For example, when stopping on a 29266breakpoint it is reasonable to switch to the thread where breakpoint is 29267hit. For another example, if the user issues the CLI @samp{thread} or 29268@samp{frame} commands via the frontend, it is desirable to change the 29269frontend's selection to the one specified by user. @value{GDBN} 29270communicates the suggestion to change current thread and frame using the 29271@samp{=thread-selected} notification. 29272 29273Note that historically, MI shares the selected thread with CLI, so 29274frontends used the @code{-thread-select} to execute commands in the 29275right context. However, getting this to work right is cumbersome. The 29276simplest way is for frontend to emit @code{-thread-select} command 29277before every command. This doubles the number of commands that need 29278to be sent. The alternative approach is to suppress @code{-thread-select} 29279if the selected thread in @value{GDBN} is supposed to be identical to the 29280thread the frontend wants to operate on. However, getting this 29281optimization right can be tricky. In particular, if the frontend 29282sends several commands to @value{GDBN}, and one of the commands changes the 29283selected thread, then the behaviour of subsequent commands will 29284change. So, a frontend should either wait for response from such 29285problematic commands, or explicitly add @code{-thread-select} for 29286all subsequent commands. No frontend is known to do this exactly 29287right, so it is suggested to just always pass the @samp{--thread} and 29288@samp{--frame} options. 29289 29290@subsubsection Language 29291 29292The execution of several commands depends on which language is selected. 29293By default, the current language (@pxref{show language}) is used. 29294But for commands known to be language-sensitive, it is recommended 29295to use the @samp{--language} option. This option takes one argument, 29296which is the name of the language to use while executing the command. 29297For instance: 29298 29299@smallexample 29300-data-evaluate-expression --language c "sizeof (void*)" 29301^done,value="4" 29302(gdb) 29303@end smallexample 29304 29305The valid language names are the same names accepted by the 29306@samp{set language} command (@pxref{Manually}), excluding @samp{auto}, 29307@samp{local} or @samp{unknown}. 29308 29309@node Asynchronous and non-stop modes 29310@subsection Asynchronous command execution and non-stop mode 29311 29312On some targets, @value{GDBN} is capable of processing MI commands 29313even while the target is running. This is called @dfn{asynchronous 29314command execution} (@pxref{Background Execution}). The frontend may 29315specify a preference for asynchronous execution using the 29316@code{-gdb-set mi-async 1} command, which should be emitted before 29317either running the executable or attaching to the target. After the 29318frontend has started the executable or attached to the target, it can 29319find if asynchronous execution is enabled using the 29320@code{-list-target-features} command. 29321 29322@table @code 29323@item -gdb-set mi-async on 29324@item -gdb-set mi-async off 29325Set whether MI is in asynchronous mode. 29326 29327When @code{off}, which is the default, MI execution commands (e.g., 29328@code{-exec-continue}) are foreground commands, and @value{GDBN} waits 29329for the program to stop before processing further commands. 29330 29331When @code{on}, MI execution commands are background execution 29332commands (e.g., @code{-exec-continue} becomes the equivalent of the 29333@code{c&} CLI command), and so @value{GDBN} is capable of processing 29334MI commands even while the target is running. 29335 29336@item -gdb-show mi-async 29337Show whether MI asynchronous mode is enabled. 29338@end table 29339 29340Note: In @value{GDBN} version 7.7 and earlier, this option was called 29341@code{target-async} instead of @code{mi-async}, and it had the effect 29342of both putting MI in asynchronous mode and making CLI background 29343commands possible. CLI background commands are now always possible 29344``out of the box'' if the target supports them. The old spelling is 29345kept as a deprecated alias for backwards compatibility. 29346 29347Even if @value{GDBN} can accept a command while target is running, 29348many commands that access the target do not work when the target is 29349running. Therefore, asynchronous command execution is most useful 29350when combined with non-stop mode (@pxref{Non-Stop Mode}). Then, 29351it is possible to examine the state of one thread, while other threads 29352are running. 29353 29354When a given thread is running, MI commands that try to access the 29355target in the context of that thread may not work, or may work only on 29356some targets. In particular, commands that try to operate on thread's 29357stack will not work, on any target. Commands that read memory, or 29358modify breakpoints, may work or not work, depending on the target. Note 29359that even commands that operate on global state, such as @code{print}, 29360@code{set}, and breakpoint commands, still access the target in the 29361context of a specific thread, so frontend should try to find a 29362stopped thread and perform the operation on that thread (using the 29363@samp{--thread} option). 29364 29365Which commands will work in the context of a running thread is 29366highly target dependent. However, the two commands 29367@code{-exec-interrupt}, to stop a thread, and @code{-thread-info}, 29368to find the state of a thread, will always work. 29369 29370@node Thread groups 29371@subsection Thread groups 29372@value{GDBN} may be used to debug several processes at the same time. 29373On some platforms, @value{GDBN} may support debugging of several 29374hardware systems, each one having several cores with several different 29375processes running on each core. This section describes the MI 29376mechanism to support such debugging scenarios. 29377 29378The key observation is that regardless of the structure of the 29379target, MI can have a global list of threads, because most commands that 29380accept the @samp{--thread} option do not need to know what process that 29381thread belongs to. Therefore, it is not necessary to introduce 29382neither additional @samp{--process} option, nor an notion of the 29383current process in the MI interface. The only strictly new feature 29384that is required is the ability to find how the threads are grouped 29385into processes. 29386 29387To allow the user to discover such grouping, and to support arbitrary 29388hierarchy of machines/cores/processes, MI introduces the concept of a 29389@dfn{thread group}. Thread group is a collection of threads and other 29390thread groups. A thread group always has a string identifier, a type, 29391and may have additional attributes specific to the type. A new 29392command, @code{-list-thread-groups}, returns the list of top-level 29393thread groups, which correspond to processes that @value{GDBN} is 29394debugging at the moment. By passing an identifier of a thread group 29395to the @code{-list-thread-groups} command, it is possible to obtain 29396the members of specific thread group. 29397 29398To allow the user to easily discover processes, and other objects, he 29399wishes to debug, a concept of @dfn{available thread group} is 29400introduced. Available thread group is an thread group that 29401@value{GDBN} is not debugging, but that can be attached to, using the 29402@code{-target-attach} command. The list of available top-level thread 29403groups can be obtained using @samp{-list-thread-groups --available}. 29404In general, the content of a thread group may be only retrieved only 29405after attaching to that thread group. 29406 29407Thread groups are related to inferiors (@pxref{Inferiors Connections and 29408Programs}). Each inferior corresponds to a thread group of a special 29409type @samp{process}, and some additional operations are permitted on 29410such thread groups. 29411 29412@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 29413@node GDB/MI Command Syntax 29414@section @sc{gdb/mi} Command Syntax 29415 29416@menu 29417* GDB/MI Input Syntax:: 29418* GDB/MI Output Syntax:: 29419@end menu 29420 29421@node GDB/MI Input Syntax 29422@subsection @sc{gdb/mi} Input Syntax 29423 29424@cindex input syntax for @sc{gdb/mi} 29425@cindex @sc{gdb/mi}, input syntax 29426@table @code 29427@item @var{command} @expansion{} 29428@code{@var{cli-command} | @var{mi-command}} 29429 29430@item @var{cli-command} @expansion{} 29431@code{[ @var{token} ] @var{cli-command} @var{nl}}, where 29432@var{cli-command} is any existing @value{GDBN} CLI command. 29433 29434@item @var{mi-command} @expansion{} 29435@code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )* 29436@code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}} 29437 29438@item @var{token} @expansion{} 29439"any sequence of digits" 29440 29441@item @var{option} @expansion{} 29442@code{"-" @var{parameter} [ " " @var{parameter} ]} 29443 29444@item @var{parameter} @expansion{} 29445@code{@var{non-blank-sequence} | @var{c-string}} 29446 29447@item @var{operation} @expansion{} 29448@emph{any of the operations described in this chapter} 29449 29450@item @var{non-blank-sequence} @expansion{} 29451@emph{anything, provided it doesn't contain special characters such as 29452"-", @var{nl}, """ and of course " "} 29453 29454@item @var{c-string} @expansion{} 29455@code{""" @var{seven-bit-iso-c-string-content} """} 29456 29457@item @var{nl} @expansion{} 29458@code{CR | CR-LF} 29459@end table 29460 29461@noindent 29462Notes: 29463 29464@itemize @bullet 29465@item 29466The CLI commands are still handled by the @sc{mi} interpreter; their 29467output is described below. 29468 29469@item 29470The @code{@var{token}}, when present, is passed back when the command 29471finishes. 29472 29473@item 29474Some @sc{mi} commands accept optional arguments as part of the parameter 29475list. Each option is identified by a leading @samp{-} (dash) and may be 29476followed by an optional argument parameter. Options occur first in the 29477parameter list and can be delimited from normal parameters using 29478@samp{--} (this is useful when some parameters begin with a dash). 29479@end itemize 29480 29481Pragmatics: 29482 29483@itemize @bullet 29484@item 29485We want easy access to the existing CLI syntax (for debugging). 29486 29487@item 29488We want it to be easy to spot a @sc{mi} operation. 29489@end itemize 29490 29491@node GDB/MI Output Syntax 29492@subsection @sc{gdb/mi} Output Syntax 29493 29494@cindex output syntax of @sc{gdb/mi} 29495@cindex @sc{gdb/mi}, output syntax 29496The output from @sc{gdb/mi} consists of zero or more out-of-band records 29497followed, optionally, by a single result record. This result record 29498is for the most recent command. The sequence of output records is 29499terminated by @samp{(gdb)}. 29500 29501If an input command was prefixed with a @code{@var{token}} then the 29502corresponding output for that command will also be prefixed by that same 29503@var{token}. 29504 29505@table @code 29506@item @var{output} @expansion{} 29507@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}} 29508 29509@item @var{result-record} @expansion{} 29510@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}} 29511 29512@item @var{out-of-band-record} @expansion{} 29513@code{@var{async-record} | @var{stream-record}} 29514 29515@item @var{async-record} @expansion{} 29516@code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}} 29517 29518@item @var{exec-async-output} @expansion{} 29519@code{[ @var{token} ] "*" @var{async-output nl}} 29520 29521@item @var{status-async-output} @expansion{} 29522@code{[ @var{token} ] "+" @var{async-output nl}} 29523 29524@item @var{notify-async-output} @expansion{} 29525@code{[ @var{token} ] "=" @var{async-output nl}} 29526 29527@item @var{async-output} @expansion{} 29528@code{@var{async-class} ( "," @var{result} )*} 29529 29530@item @var{result-class} @expansion{} 29531@code{"done" | "running" | "connected" | "error" | "exit"} 29532 29533@item @var{async-class} @expansion{} 29534@code{"stopped" | @var{others}} (where @var{others} will be added 29535depending on the needs---this is still in development). 29536 29537@item @var{result} @expansion{} 29538@code{ @var{variable} "=" @var{value}} 29539 29540@item @var{variable} @expansion{} 29541@code{ @var{string} } 29542 29543@item @var{value} @expansion{} 29544@code{ @var{const} | @var{tuple} | @var{list} } 29545 29546@item @var{const} @expansion{} 29547@code{@var{c-string}} 29548 29549@item @var{tuple} @expansion{} 29550@code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" } 29551 29552@item @var{list} @expansion{} 29553@code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "[" 29554@var{result} ( "," @var{result} )* "]" } 29555 29556@item @var{stream-record} @expansion{} 29557@code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}} 29558 29559@item @var{console-stream-output} @expansion{} 29560@code{"~" @var{c-string nl}} 29561 29562@item @var{target-stream-output} @expansion{} 29563@code{"@@" @var{c-string nl}} 29564 29565@item @var{log-stream-output} @expansion{} 29566@code{"&" @var{c-string nl}} 29567 29568@item @var{nl} @expansion{} 29569@code{CR | CR-LF} 29570 29571@item @var{token} @expansion{} 29572@emph{any sequence of digits}. 29573@end table 29574 29575@noindent 29576Notes: 29577 29578@itemize @bullet 29579@item 29580All output sequences end in a single line containing a period. 29581 29582@item 29583The @code{@var{token}} is from the corresponding request. Note that 29584for all async output, while the token is allowed by the grammar and 29585may be output by future versions of @value{GDBN} for select async 29586output messages, it is generally omitted. Frontends should treat 29587all async output as reporting general changes in the state of the 29588target and there should be no need to associate async output to any 29589prior command. 29590 29591@item 29592@cindex status output in @sc{gdb/mi} 29593@var{status-async-output} contains on-going status information about the 29594progress of a slow operation. It can be discarded. All status output is 29595prefixed by @samp{+}. 29596 29597@item 29598@cindex async output in @sc{gdb/mi} 29599@var{exec-async-output} contains asynchronous state change on the target 29600(stopped, started, disappeared). All async output is prefixed by 29601@samp{*}. 29602 29603@item 29604@cindex notify output in @sc{gdb/mi} 29605@var{notify-async-output} contains supplementary information that the 29606client should handle (e.g., a new breakpoint information). All notify 29607output is prefixed by @samp{=}. 29608 29609@item 29610@cindex console output in @sc{gdb/mi} 29611@var{console-stream-output} is output that should be displayed as is in the 29612console. It is the textual response to a CLI command. All the console 29613output is prefixed by @samp{~}. 29614 29615@item 29616@cindex target output in @sc{gdb/mi} 29617@var{target-stream-output} is the output produced by the target program. 29618All the target output is prefixed by @samp{@@}. 29619 29620@item 29621@cindex log output in @sc{gdb/mi} 29622@var{log-stream-output} is output text coming from @value{GDBN}'s internals, for 29623instance messages that should be displayed as part of an error log. All 29624the log output is prefixed by @samp{&}. 29625 29626@item 29627@cindex list output in @sc{gdb/mi} 29628New @sc{gdb/mi} commands should only output @var{lists} containing 29629@var{values}. 29630 29631 29632@end itemize 29633 29634@xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more 29635details about the various output records. 29636 29637@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 29638@node GDB/MI Compatibility with CLI 29639@section @sc{gdb/mi} Compatibility with CLI 29640 29641@cindex compatibility, @sc{gdb/mi} and CLI 29642@cindex @sc{gdb/mi}, compatibility with CLI 29643 29644For the developers convenience CLI commands can be entered directly, 29645but there may be some unexpected behaviour. For example, commands 29646that query the user will behave as if the user replied yes, breakpoint 29647command lists are not executed and some CLI commands, such as 29648@code{if}, @code{when} and @code{define}, prompt for further input with 29649@samp{>}, which is not valid MI output. 29650 29651This feature may be removed at some stage in the future and it is 29652recommended that front ends use the @code{-interpreter-exec} command 29653(@pxref{-interpreter-exec}). 29654 29655@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 29656@node GDB/MI Development and Front Ends 29657@section @sc{gdb/mi} Development and Front Ends 29658@cindex @sc{gdb/mi} development 29659 29660The application which takes the MI output and presents the state of the 29661program being debugged to the user is called a @dfn{front end}. 29662 29663Since @sc{gdb/mi} is used by a variety of front ends to @value{GDBN}, changes 29664to the MI interface may break existing usage. This section describes how the 29665protocol changes and how to request previous version of the protocol when it 29666does. 29667 29668Some changes in MI need not break a carefully designed front end, and 29669for these the MI version will remain unchanged. The following is a 29670list of changes that may occur within one level, so front ends should 29671parse MI output in a way that can handle them: 29672 29673@itemize @bullet 29674@item 29675New MI commands may be added. 29676 29677@item 29678New fields may be added to the output of any MI command. 29679 29680@item 29681The range of values for fields with specified values, e.g., 29682@code{in_scope} (@pxref{-var-update}) may be extended. 29683 29684@c The format of field's content e.g type prefix, may change so parse it 29685@c at your own risk. Yes, in general? 29686 29687@c The order of fields may change? Shouldn't really matter but it might 29688@c resolve inconsistencies. 29689@end itemize 29690 29691If the changes are likely to break front ends, the MI version level 29692will be increased by one. The new versions of the MI protocol are not compatible 29693with the old versions. Old versions of MI remain available, allowing front ends 29694to keep using them until they are modified to use the latest MI version. 29695 29696Since @code{--interpreter=mi} always points to the latest MI version, it is 29697recommended that front ends request a specific version of MI when launching 29698@value{GDBN} (e.g.@: @code{--interpreter=mi2}) to make sure they get an 29699interpreter with the MI version they expect. 29700 29701The following table gives a summary of the released versions of the MI 29702interface: the version number, the version of GDB in which it first appeared 29703and the breaking changes compared to the previous version. 29704 29705@multitable @columnfractions .05 .05 .9 29706@headitem MI version @tab GDB version @tab Breaking changes 29707 29708@item 29709@center 1 29710@tab 29711@center 5.1 29712@tab 29713None 29714 29715@item 29716@center 2 29717@tab 29718@center 6.0 29719@tab 29720 29721@itemize 29722@item 29723The @code{-environment-pwd}, @code{-environment-directory} and 29724@code{-environment-path} commands now returns values using the MI output 29725syntax, rather than CLI output syntax. 29726 29727@item 29728@code{-var-list-children}'s @code{children} result field is now a list, rather 29729than a tuple. 29730 29731@item 29732@code{-var-update}'s @code{changelist} result field is now a list, rather than 29733a tuple. 29734@end itemize 29735 29736@item 29737@center 3 29738@tab 29739@center 9.1 29740@tab 29741 29742@itemize 29743@item 29744The output of information about multi-location breakpoints has changed in the 29745responses to the @code{-break-insert} and @code{-break-info} commands, as well 29746as in the @code{=breakpoint-created} and @code{=breakpoint-modified} events. 29747The multiple locations are now placed in a @code{locations} field, whose value 29748is a list. 29749@end itemize 29750 29751@end multitable 29752 29753If your front end cannot yet migrate to a more recent version of the 29754MI protocol, you can nevertheless selectively enable specific features 29755available in those recent MI versions, using the following commands: 29756 29757@table @code 29758 29759@item -fix-multi-location-breakpoint-output 29760Use the output for multi-location breakpoints which was introduced by 29761MI 3, even when using MI versions 2 or 1. This command has no 29762effect when using MI version 3 or later. 29763 29764@end table 29765 29766The best way to avoid unexpected changes in MI that might break your front 29767end is to make your project known to @value{GDBN} developers and 29768follow development on @email{gdb@@sourceware.org} and 29769@email{gdb-patches@@sourceware.org}. 29770@cindex mailing lists 29771 29772@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 29773@node GDB/MI Output Records 29774@section @sc{gdb/mi} Output Records 29775 29776@menu 29777* GDB/MI Result Records:: 29778* GDB/MI Stream Records:: 29779* GDB/MI Async Records:: 29780* GDB/MI Breakpoint Information:: 29781* GDB/MI Frame Information:: 29782* GDB/MI Thread Information:: 29783* GDB/MI Ada Exception Information:: 29784@end menu 29785 29786@node GDB/MI Result Records 29787@subsection @sc{gdb/mi} Result Records 29788 29789@cindex result records in @sc{gdb/mi} 29790@cindex @sc{gdb/mi}, result records 29791In addition to a number of out-of-band notifications, the response to a 29792@sc{gdb/mi} command includes one of the following result indications: 29793 29794@table @code 29795@findex ^done 29796@item "^done" [ "," @var{results} ] 29797The synchronous operation was successful, @code{@var{results}} are the return 29798values. 29799 29800@item "^running" 29801@findex ^running 29802This result record is equivalent to @samp{^done}. Historically, it 29803was output instead of @samp{^done} if the command has resumed the 29804target. This behaviour is maintained for backward compatibility, but 29805all frontends should treat @samp{^done} and @samp{^running} 29806identically and rely on the @samp{*running} output record to determine 29807which threads are resumed. 29808 29809@item "^connected" 29810@findex ^connected 29811@value{GDBN} has connected to a remote target. 29812 29813@item "^error" "," "msg=" @var{c-string} [ "," "code=" @var{c-string} ] 29814@findex ^error 29815The operation failed. The @code{msg=@var{c-string}} variable contains 29816the corresponding error message. 29817 29818If present, the @code{code=@var{c-string}} variable provides an error 29819code on which consumers can rely on to detect the corresponding 29820error condition. At present, only one error code is defined: 29821 29822@table @samp 29823@item "undefined-command" 29824Indicates that the command causing the error does not exist. 29825@end table 29826 29827@item "^exit" 29828@findex ^exit 29829@value{GDBN} has terminated. 29830 29831@end table 29832 29833@node GDB/MI Stream Records 29834@subsection @sc{gdb/mi} Stream Records 29835 29836@cindex @sc{gdb/mi}, stream records 29837@cindex stream records in @sc{gdb/mi} 29838@value{GDBN} internally maintains a number of output streams: the console, the 29839target, and the log. The output intended for each of these streams is 29840funneled through the @sc{gdb/mi} interface using @dfn{stream records}. 29841 29842Each stream record begins with a unique @dfn{prefix character} which 29843identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output 29844Syntax}). In addition to the prefix, each stream record contains a 29845@code{@var{string-output}}. This is either raw text (with an implicit new 29846line) or a quoted C string (which does not contain an implicit newline). 29847 29848@table @code 29849@item "~" @var{string-output} 29850The console output stream contains text that should be displayed in the 29851CLI console window. It contains the textual responses to CLI commands. 29852 29853@item "@@" @var{string-output} 29854The target output stream contains any textual output from the running 29855target. This is only present when GDB's event loop is truly 29856asynchronous, which is currently only the case for remote targets. 29857 29858@item "&" @var{string-output} 29859The log stream contains debugging messages being produced by @value{GDBN}'s 29860internals. 29861@end table 29862 29863@node GDB/MI Async Records 29864@subsection @sc{gdb/mi} Async Records 29865 29866@cindex async records in @sc{gdb/mi} 29867@cindex @sc{gdb/mi}, async records 29868@dfn{Async} records are used to notify the @sc{gdb/mi} client of 29869additional changes that have occurred. Those changes can either be a 29870consequence of @sc{gdb/mi} commands (e.g., a breakpoint modified) or a result of 29871target activity (e.g., target stopped). 29872 29873The following is the list of possible async records: 29874 29875@table @code 29876 29877@item *running,thread-id="@var{thread}" 29878The target is now running. The @var{thread} field can be the global 29879thread ID of the thread that is now running, and it can be 29880@samp{all} if all threads are running. The frontend should assume 29881that no interaction with a running thread is possible after this 29882notification is produced. The frontend should not assume that this 29883notification is output only once for any command. @value{GDBN} may 29884emit this notification several times, either for different threads, 29885because it cannot resume all threads together, or even for a single 29886thread, if the thread must be stepped though some code before letting 29887it run freely. 29888 29889@item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}",core="@var{core}" 29890The target has stopped. The @var{reason} field can have one of the 29891following values: 29892 29893@table @code 29894@item breakpoint-hit 29895A breakpoint was reached. 29896@item watchpoint-trigger 29897A watchpoint was triggered. 29898@item read-watchpoint-trigger 29899A read watchpoint was triggered. 29900@item access-watchpoint-trigger 29901An access watchpoint was triggered. 29902@item function-finished 29903An -exec-finish or similar CLI command was accomplished. 29904@item location-reached 29905An -exec-until or similar CLI command was accomplished. 29906@item watchpoint-scope 29907A watchpoint has gone out of scope. 29908@item end-stepping-range 29909An -exec-next, -exec-next-instruction, -exec-step, -exec-step-instruction or 29910similar CLI command was accomplished. 29911@item exited-signalled 29912The inferior exited because of a signal. 29913@item exited 29914The inferior exited. 29915@item exited-normally 29916The inferior exited normally. 29917@item signal-received 29918A signal was received by the inferior. 29919@item solib-event 29920The inferior has stopped due to a library being loaded or unloaded. 29921This can happen when @code{stop-on-solib-events} (@pxref{Files}) is 29922set or when a @code{catch load} or @code{catch unload} catchpoint is 29923in use (@pxref{Set Catchpoints}). 29924@item fork 29925The inferior has forked. This is reported when @code{catch fork} 29926(@pxref{Set Catchpoints}) has been used. 29927@item vfork 29928The inferior has vforked. This is reported in when @code{catch vfork} 29929(@pxref{Set Catchpoints}) has been used. 29930@item syscall-entry 29931The inferior entered a system call. This is reported when @code{catch 29932syscall} (@pxref{Set Catchpoints}) has been used. 29933@item syscall-return 29934The inferior returned from a system call. This is reported when 29935@code{catch syscall} (@pxref{Set Catchpoints}) has been used. 29936@item exec 29937The inferior called @code{exec}. This is reported when @code{catch exec} 29938(@pxref{Set Catchpoints}) has been used. 29939@end table 29940 29941The @var{id} field identifies the global thread ID of the thread 29942that directly caused the stop -- for example by hitting a breakpoint. 29943Depending on whether all-stop 29944mode is in effect (@pxref{All-Stop Mode}), @value{GDBN} may either 29945stop all threads, or only the thread that directly triggered the stop. 29946If all threads are stopped, the @var{stopped} field will have the 29947value of @code{"all"}. Otherwise, the value of the @var{stopped} 29948field will be a list of thread identifiers. Presently, this list will 29949always include a single thread, but frontend should be prepared to see 29950several threads in the list. The @var{core} field reports the 29951processor core on which the stop event has happened. This field may be absent 29952if such information is not available. 29953 29954@item =thread-group-added,id="@var{id}" 29955@itemx =thread-group-removed,id="@var{id}" 29956A thread group was either added or removed. The @var{id} field 29957contains the @value{GDBN} identifier of the thread group. When a thread 29958group is added, it generally might not be associated with a running 29959process. When a thread group is removed, its id becomes invalid and 29960cannot be used in any way. 29961 29962@item =thread-group-started,id="@var{id}",pid="@var{pid}" 29963A thread group became associated with a running program, 29964either because the program was just started or the thread group 29965was attached to a program. The @var{id} field contains the 29966@value{GDBN} identifier of the thread group. The @var{pid} field 29967contains process identifier, specific to the operating system. 29968 29969@item =thread-group-exited,id="@var{id}"[,exit-code="@var{code}"] 29970A thread group is no longer associated with a running program, 29971either because the program has exited, or because it was detached 29972from. The @var{id} field contains the @value{GDBN} identifier of the 29973thread group. The @var{code} field is the exit code of the inferior; it exists 29974only when the inferior exited with some code. 29975 29976@item =thread-created,id="@var{id}",group-id="@var{gid}" 29977@itemx =thread-exited,id="@var{id}",group-id="@var{gid}" 29978A thread either was created, or has exited. The @var{id} field 29979contains the global @value{GDBN} identifier of the thread. The @var{gid} 29980field identifies the thread group this thread belongs to. 29981 29982@item =thread-selected,id="@var{id}"[,frame="@var{frame}"] 29983Informs that the selected thread or frame were changed. This notification 29984is not emitted as result of the @code{-thread-select} or 29985@code{-stack-select-frame} commands, but is emitted whenever an MI command 29986that is not documented to change the selected thread and frame actually 29987changes them. In particular, invoking, directly or indirectly 29988(via user-defined command), the CLI @code{thread} or @code{frame} commands, 29989will generate this notification. Changing the thread or frame from another 29990user interface (see @ref{Interpreters}) will also generate this notification. 29991 29992The @var{frame} field is only present if the newly selected thread is 29993stopped. See @ref{GDB/MI Frame Information} for the format of its value. 29994 29995We suggest that in response to this notification, front ends 29996highlight the selected thread and cause subsequent commands to apply to 29997that thread. 29998 29999@item =library-loaded,... 30000Reports that a new library file was loaded by the program. This 30001notification has 5 fields---@var{id}, @var{target-name}, 30002@var{host-name}, @var{symbols-loaded} and @var{ranges}. The @var{id} field is an 30003opaque identifier of the library. For remote debugging case, 30004@var{target-name} and @var{host-name} fields give the name of the 30005library file on the target, and on the host respectively. For native 30006debugging, both those fields have the same value. The 30007@var{symbols-loaded} field is emitted only for backward compatibility 30008and should not be relied on to convey any useful information. The 30009@var{thread-group} field, if present, specifies the id of the thread 30010group in whose context the library was loaded. If the field is 30011absent, it means the library was loaded in the context of all present 30012thread groups. The @var{ranges} field specifies the ranges of addresses belonging 30013to this library. 30014 30015@item =library-unloaded,... 30016Reports that a library was unloaded by the program. This notification 30017has 3 fields---@var{id}, @var{target-name} and @var{host-name} with 30018the same meaning as for the @code{=library-loaded} notification. 30019The @var{thread-group} field, if present, specifies the id of the 30020thread group in whose context the library was unloaded. If the field is 30021absent, it means the library was unloaded in the context of all present 30022thread groups. 30023 30024@item =traceframe-changed,num=@var{tfnum},tracepoint=@var{tpnum} 30025@itemx =traceframe-changed,end 30026Reports that the trace frame was changed and its new number is 30027@var{tfnum}. The number of the tracepoint associated with this trace 30028frame is @var{tpnum}. 30029 30030@item =tsv-created,name=@var{name},initial=@var{initial} 30031Reports that the new trace state variable @var{name} is created with 30032initial value @var{initial}. 30033 30034@item =tsv-deleted,name=@var{name} 30035@itemx =tsv-deleted 30036Reports that the trace state variable @var{name} is deleted or all 30037trace state variables are deleted. 30038 30039@item =tsv-modified,name=@var{name},initial=@var{initial}[,current=@var{current}] 30040Reports that the trace state variable @var{name} is modified with 30041the initial value @var{initial}. The current value @var{current} of 30042trace state variable is optional and is reported if the current 30043value of trace state variable is known. 30044 30045@item =breakpoint-created,bkpt=@{...@} 30046@itemx =breakpoint-modified,bkpt=@{...@} 30047@itemx =breakpoint-deleted,id=@var{number} 30048Reports that a breakpoint was created, modified, or deleted, 30049respectively. Only user-visible breakpoints are reported to the MI 30050user. 30051 30052The @var{bkpt} argument is of the same form as returned by the various 30053breakpoint commands; @xref{GDB/MI Breakpoint Commands}. The 30054@var{number} is the ordinal number of the breakpoint. 30055 30056Note that if a breakpoint is emitted in the result record of a 30057command, then it will not also be emitted in an async record. 30058 30059@item =record-started,thread-group="@var{id}",method="@var{method}"[,format="@var{format}"] 30060@itemx =record-stopped,thread-group="@var{id}" 30061Execution log recording was either started or stopped on an 30062inferior. The @var{id} is the @value{GDBN} identifier of the thread 30063group corresponding to the affected inferior. 30064 30065The @var{method} field indicates the method used to record execution. If the 30066method in use supports multiple recording formats, @var{format} will be present 30067and contain the currently used format. @xref{Process Record and Replay}, 30068for existing method and format values. 30069 30070@item =cmd-param-changed,param=@var{param},value=@var{value} 30071Reports that a parameter of the command @code{set @var{param}} is 30072changed to @var{value}. In the multi-word @code{set} command, 30073the @var{param} is the whole parameter list to @code{set} command. 30074For example, In command @code{set check type on}, @var{param} 30075is @code{check type} and @var{value} is @code{on}. 30076 30077@item =memory-changed,thread-group=@var{id},addr=@var{addr},len=@var{len}[,type="code"] 30078Reports that bytes from @var{addr} to @var{data} + @var{len} were 30079written in an inferior. The @var{id} is the identifier of the 30080thread group corresponding to the affected inferior. The optional 30081@code{type="code"} part is reported if the memory written to holds 30082executable code. 30083@end table 30084 30085@node GDB/MI Breakpoint Information 30086@subsection @sc{gdb/mi} Breakpoint Information 30087 30088When @value{GDBN} reports information about a breakpoint, a 30089tracepoint, a watchpoint, or a catchpoint, it uses a tuple with the 30090following fields: 30091 30092@table @code 30093@item number 30094The breakpoint number. 30095 30096@item type 30097The type of the breakpoint. For ordinary breakpoints this will be 30098@samp{breakpoint}, but many values are possible. 30099 30100@item catch-type 30101If the type of the breakpoint is @samp{catchpoint}, then this 30102indicates the exact type of catchpoint. 30103 30104@item disp 30105This is the breakpoint disposition---either @samp{del}, meaning that 30106the breakpoint will be deleted at the next stop, or @samp{keep}, 30107meaning that the breakpoint will not be deleted. 30108 30109@item enabled 30110This indicates whether the breakpoint is enabled, in which case the 30111value is @samp{y}, or disabled, in which case the value is @samp{n}. 30112Note that this is not the same as the field @code{enable}. 30113 30114@item addr 30115The address of the breakpoint. This may be a hexidecimal number, 30116giving the address; or the string @samp{<PENDING>}, for a pending 30117breakpoint; or the string @samp{<MULTIPLE>}, for a breakpoint with 30118multiple locations. This field will not be present if no address can 30119be determined. For example, a watchpoint does not have an address. 30120 30121@item addr_flags 30122Optional field containing any flags related to the address. These flags are 30123architecture-dependent; see @ref{Architectures} for their meaning for a 30124particular CPU. 30125 30126@item func 30127If known, the function in which the breakpoint appears. 30128If not known, this field is not present. 30129 30130@item filename 30131The name of the source file which contains this function, if known. 30132If not known, this field is not present. 30133 30134@item fullname 30135The full file name of the source file which contains this function, if 30136known. If not known, this field is not present. 30137 30138@item line 30139The line number at which this breakpoint appears, if known. 30140If not known, this field is not present. 30141 30142@item at 30143If the source file is not known, this field may be provided. If 30144provided, this holds the address of the breakpoint, possibly followed 30145by a symbol name. 30146 30147@item pending 30148If this breakpoint is pending, this field is present and holds the 30149text used to set the breakpoint, as entered by the user. 30150 30151@item evaluated-by 30152Where this breakpoint's condition is evaluated, either @samp{host} or 30153@samp{target}. 30154 30155@item thread 30156If this is a thread-specific breakpoint, then this identifies the 30157thread in which the breakpoint can trigger. 30158 30159@item task 30160If this breakpoint is restricted to a particular Ada task, then this 30161field will hold the task identifier. 30162 30163@item cond 30164If the breakpoint is conditional, this is the condition expression. 30165 30166@item ignore 30167The ignore count of the breakpoint. 30168 30169@item enable 30170The enable count of the breakpoint. 30171 30172@item traceframe-usage 30173FIXME. 30174 30175@item static-tracepoint-marker-string-id 30176For a static tracepoint, the name of the static tracepoint marker. 30177 30178@item mask 30179For a masked watchpoint, this is the mask. 30180 30181@item pass 30182A tracepoint's pass count. 30183 30184@item original-location 30185The location of the breakpoint as originally specified by the user. 30186This field is optional. 30187 30188@item times 30189The number of times the breakpoint has been hit. 30190 30191@item installed 30192This field is only given for tracepoints. This is either @samp{y}, 30193meaning that the tracepoint is installed, or @samp{n}, meaning that it 30194is not. 30195 30196@item what 30197Some extra data, the exact contents of which are type-dependent. 30198 30199@item locations 30200This field is present if the breakpoint has multiple locations. It is also 30201exceptionally present if the breakpoint is enabled and has a single, disabled 30202location. 30203 30204The value is a list of locations. The format of a location is described below. 30205 30206@end table 30207 30208A location in a multi-location breakpoint is represented as a tuple with the 30209following fields: 30210 30211@table @code 30212 30213@item number 30214The location number as a dotted pair, like @samp{1.2}. The first digit is the 30215number of the parent breakpoint. The second digit is the number of the 30216location within that breakpoint. 30217 30218@item enabled 30219There are three possible values, with the following meanings: 30220@table @code 30221@item y 30222The location is enabled. 30223@item n 30224The location is disabled by the user. 30225@item N 30226The location is disabled because the breakpoint condition is invalid 30227at this location. 30228@end table 30229 30230@item addr 30231The address of this location as an hexidecimal number. 30232 30233@item addr_flags 30234Optional field containing any flags related to the address. These flags are 30235architecture-dependent; see @ref{Architectures} for their meaning for a 30236particular CPU. 30237 30238@item func 30239If known, the function in which the location appears. 30240If not known, this field is not present. 30241 30242@item file 30243The name of the source file which contains this location, if known. 30244If not known, this field is not present. 30245 30246@item fullname 30247The full file name of the source file which contains this location, if 30248known. If not known, this field is not present. 30249 30250@item line 30251The line number at which this location appears, if known. 30252If not known, this field is not present. 30253 30254@item thread-groups 30255The thread groups this location is in. 30256 30257@end table 30258 30259For example, here is what the output of @code{-break-insert} 30260(@pxref{GDB/MI Breakpoint Commands}) might be: 30261 30262@smallexample 30263-> -break-insert main 30264<- ^done,bkpt=@{number="1",type="breakpoint",disp="keep", 30265 enabled="y",addr="0x08048564",func="main",file="myprog.c", 30266 fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"], 30267 times="0"@} 30268<- (gdb) 30269@end smallexample 30270 30271@node GDB/MI Frame Information 30272@subsection @sc{gdb/mi} Frame Information 30273 30274Response from many MI commands includes an information about stack 30275frame. This information is a tuple that may have the following 30276fields: 30277 30278@table @code 30279@item level 30280The level of the stack frame. The innermost frame has the level of 30281zero. This field is always present. 30282 30283@item func 30284The name of the function corresponding to the frame. This field may 30285be absent if @value{GDBN} is unable to determine the function name. 30286 30287@item addr 30288The code address for the frame. This field is always present. 30289 30290@item addr_flags 30291Optional field containing any flags related to the address. These flags are 30292architecture-dependent; see @ref{Architectures} for their meaning for a 30293particular CPU. 30294 30295@item file 30296The name of the source files that correspond to the frame's code 30297address. This field may be absent. 30298 30299@item line 30300The source line corresponding to the frames' code address. This field 30301may be absent. 30302 30303@item from 30304The name of the binary file (either executable or shared library) the 30305corresponds to the frame's code address. This field may be absent. 30306 30307@end table 30308 30309@node GDB/MI Thread Information 30310@subsection @sc{gdb/mi} Thread Information 30311 30312Whenever @value{GDBN} has to report an information about a thread, it 30313uses a tuple with the following fields. The fields are always present unless 30314stated otherwise. 30315 30316@table @code 30317@item id 30318The global numeric id assigned to the thread by @value{GDBN}. 30319 30320@item target-id 30321The target-specific string identifying the thread. 30322 30323@item details 30324Additional information about the thread provided by the target. 30325It is supposed to be human-readable and not interpreted by the 30326frontend. This field is optional. 30327 30328@item name 30329The name of the thread. If the user specified a name using the 30330@code{thread name} command, then this name is given. Otherwise, if 30331@value{GDBN} can extract the thread name from the target, then that 30332name is given. If @value{GDBN} cannot find the thread name, then this 30333field is omitted. 30334 30335@item state 30336The execution state of the thread, either @samp{stopped} or @samp{running}, 30337depending on whether the thread is presently running. 30338 30339@item frame 30340The stack frame currently executing in the thread. This field is only present 30341if the thread is stopped. Its format is documented in 30342@ref{GDB/MI Frame Information}. 30343 30344@item core 30345The value of this field is an integer number of the processor core the 30346thread was last seen on. This field is optional. 30347@end table 30348 30349@node GDB/MI Ada Exception Information 30350@subsection @sc{gdb/mi} Ada Exception Information 30351 30352Whenever a @code{*stopped} record is emitted because the program 30353stopped after hitting an exception catchpoint (@pxref{Set Catchpoints}), 30354@value{GDBN} provides the name of the exception that was raised via 30355the @code{exception-name} field. Also, for exceptions that were raised 30356with an exception message, @value{GDBN} provides that message via 30357the @code{exception-message} field. 30358 30359@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 30360@node GDB/MI Simple Examples 30361@section Simple Examples of @sc{gdb/mi} Interaction 30362@cindex @sc{gdb/mi}, simple examples 30363 30364This subsection presents several simple examples of interaction using 30365the @sc{gdb/mi} interface. In these examples, @samp{->} means that the 30366following line is passed to @sc{gdb/mi} as input, while @samp{<-} means 30367the output received from @sc{gdb/mi}. 30368 30369Note the line breaks shown in the examples are here only for 30370readability, they don't appear in the real output. 30371 30372@subheading Setting a Breakpoint 30373 30374Setting a breakpoint generates synchronous output which contains detailed 30375information of the breakpoint. 30376 30377@smallexample 30378-> -break-insert main 30379<- ^done,bkpt=@{number="1",type="breakpoint",disp="keep", 30380 enabled="y",addr="0x08048564",func="main",file="myprog.c", 30381 fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"], 30382 times="0"@} 30383<- (gdb) 30384@end smallexample 30385 30386@subheading Program Execution 30387 30388Program execution generates asynchronous records and MI gives the 30389reason that execution stopped. 30390 30391@smallexample 30392-> -exec-run 30393<- ^running 30394<- (gdb) 30395<- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", 30396 frame=@{addr="0x08048564",func="main", 30397 args=[@{name="argc",value="1"@},@{name="argv",value="0xbfc4d4d4"@}], 30398 file="myprog.c",fullname="/home/nickrob/myprog.c",line="68", 30399 arch="i386:x86_64"@} 30400<- (gdb) 30401-> -exec-continue 30402<- ^running 30403<- (gdb) 30404<- *stopped,reason="exited-normally" 30405<- (gdb) 30406@end smallexample 30407 30408@subheading Quitting @value{GDBN} 30409 30410Quitting @value{GDBN} just prints the result class @samp{^exit}. 30411 30412@smallexample 30413-> (gdb) 30414<- -gdb-exit 30415<- ^exit 30416@end smallexample 30417 30418Please note that @samp{^exit} is printed immediately, but it might 30419take some time for @value{GDBN} to actually exit. During that time, @value{GDBN} 30420performs necessary cleanups, including killing programs being debugged 30421or disconnecting from debug hardware, so the frontend should wait till 30422@value{GDBN} exits and should only forcibly kill @value{GDBN} if it 30423fails to exit in reasonable time. 30424 30425@subheading A Bad Command 30426 30427Here's what happens if you pass a non-existent command: 30428 30429@smallexample 30430-> -rubbish 30431<- ^error,msg="Undefined MI command: rubbish" 30432<- (gdb) 30433@end smallexample 30434 30435 30436@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 30437@node GDB/MI Command Description Format 30438@section @sc{gdb/mi} Command Description Format 30439 30440The remaining sections describe blocks of commands. Each block of 30441commands is laid out in a fashion similar to this section. 30442 30443@subheading Motivation 30444 30445The motivation for this collection of commands. 30446 30447@subheading Introduction 30448 30449A brief introduction to this collection of commands as a whole. 30450 30451@subheading Commands 30452 30453For each command in the block, the following is described: 30454 30455@subsubheading Synopsis 30456 30457@smallexample 30458 -command @var{args}@dots{} 30459@end smallexample 30460 30461@subsubheading Result 30462 30463@subsubheading @value{GDBN} Command 30464 30465The corresponding @value{GDBN} CLI command(s), if any. 30466 30467@subsubheading Example 30468 30469Example(s) formatted for readability. Some of the described commands have 30470not been implemented yet and these are labeled N.A.@: (not available). 30471 30472 30473@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 30474@node GDB/MI Breakpoint Commands 30475@section @sc{gdb/mi} Breakpoint Commands 30476 30477@cindex breakpoint commands for @sc{gdb/mi} 30478@cindex @sc{gdb/mi}, breakpoint commands 30479This section documents @sc{gdb/mi} commands for manipulating 30480breakpoints. 30481 30482@subheading The @code{-break-after} Command 30483@findex -break-after 30484 30485@subsubheading Synopsis 30486 30487@smallexample 30488 -break-after @var{number} @var{count} 30489@end smallexample 30490 30491The breakpoint number @var{number} is not in effect until it has been 30492hit @var{count} times. To see how this is reflected in the output of 30493the @samp{-break-list} command, see the description of the 30494@samp{-break-list} command below. 30495 30496@subsubheading @value{GDBN} Command 30497 30498The corresponding @value{GDBN} command is @samp{ignore}. 30499 30500@subsubheading Example 30501 30502@smallexample 30503(gdb) 30504-break-insert main 30505^done,bkpt=@{number="1",type="breakpoint",disp="keep", 30506enabled="y",addr="0x000100d0",func="main",file="hello.c", 30507fullname="/home/foo/hello.c",line="5",thread-groups=["i1"], 30508times="0"@} 30509(gdb) 30510-break-after 1 3 30511~ 30512^done 30513(gdb) 30514-break-list 30515^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 30516hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 30517@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 30518@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 30519@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 30520@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 30521@{width="40",alignment="2",col_name="what",colhdr="What"@}], 30522body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 30523addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 30524line="5",thread-groups=["i1"],times="0",ignore="3"@}]@} 30525(gdb) 30526@end smallexample 30527 30528@ignore 30529@subheading The @code{-break-catch} Command 30530@findex -break-catch 30531@end ignore 30532 30533@subheading The @code{-break-commands} Command 30534@findex -break-commands 30535 30536@subsubheading Synopsis 30537 30538@smallexample 30539 -break-commands @var{number} [ @var{command1} ... @var{commandN} ] 30540@end smallexample 30541 30542Specifies the CLI commands that should be executed when breakpoint 30543@var{number} is hit. The parameters @var{command1} to @var{commandN} 30544are the commands. If no command is specified, any previously-set 30545commands are cleared. @xref{Break Commands}. Typical use of this 30546functionality is tracing a program, that is, printing of values of 30547some variables whenever breakpoint is hit and then continuing. 30548 30549@subsubheading @value{GDBN} Command 30550 30551The corresponding @value{GDBN} command is @samp{commands}. 30552 30553@subsubheading Example 30554 30555@smallexample 30556(gdb) 30557-break-insert main 30558^done,bkpt=@{number="1",type="breakpoint",disp="keep", 30559enabled="y",addr="0x000100d0",func="main",file="hello.c", 30560fullname="/home/foo/hello.c",line="5",thread-groups=["i1"], 30561times="0"@} 30562(gdb) 30563-break-commands 1 "print v" "continue" 30564^done 30565(gdb) 30566@end smallexample 30567 30568@subheading The @code{-break-condition} Command 30569@findex -break-condition 30570 30571@subsubheading Synopsis 30572 30573@smallexample 30574 -break-condition [ --force ] @var{number} [ @var{expr} ] 30575@end smallexample 30576 30577Breakpoint @var{number} will stop the program only if the condition in 30578@var{expr} is true. The condition becomes part of the 30579@samp{-break-list} output (see the description of the @samp{-break-list} 30580command below). If the @samp{--force} flag is passed, the condition 30581is forcibly defined even when it is invalid for all locations of 30582breakpoint @var{number}. If the @var{expr} argument is omitted, 30583breakpoint @var{number} becomes unconditional. 30584 30585@subsubheading @value{GDBN} Command 30586 30587The corresponding @value{GDBN} command is @samp{condition}. 30588 30589@subsubheading Example 30590 30591@smallexample 30592(gdb) 30593-break-condition 1 1 30594^done 30595(gdb) 30596-break-list 30597^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 30598hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 30599@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 30600@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 30601@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 30602@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 30603@{width="40",alignment="2",col_name="what",colhdr="What"@}], 30604body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 30605addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 30606line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"@}]@} 30607(gdb) 30608@end smallexample 30609 30610@subheading The @code{-break-delete} Command 30611@findex -break-delete 30612 30613@subsubheading Synopsis 30614 30615@smallexample 30616 -break-delete ( @var{breakpoint} )+ 30617@end smallexample 30618 30619Delete the breakpoint(s) whose number(s) are specified in the argument 30620list. This is obviously reflected in the breakpoint list. 30621 30622@subsubheading @value{GDBN} Command 30623 30624The corresponding @value{GDBN} command is @samp{delete}. 30625 30626@subsubheading Example 30627 30628@smallexample 30629(gdb) 30630-break-delete 1 30631^done 30632(gdb) 30633-break-list 30634^done,BreakpointTable=@{nr_rows="0",nr_cols="6", 30635hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 30636@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 30637@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 30638@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 30639@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 30640@{width="40",alignment="2",col_name="what",colhdr="What"@}], 30641body=[]@} 30642(gdb) 30643@end smallexample 30644 30645@subheading The @code{-break-disable} Command 30646@findex -break-disable 30647 30648@subsubheading Synopsis 30649 30650@smallexample 30651 -break-disable ( @var{breakpoint} )+ 30652@end smallexample 30653 30654Disable the named @var{breakpoint}(s). The field @samp{enabled} in the 30655break list is now set to @samp{n} for the named @var{breakpoint}(s). 30656 30657@subsubheading @value{GDBN} Command 30658 30659The corresponding @value{GDBN} command is @samp{disable}. 30660 30661@subsubheading Example 30662 30663@smallexample 30664(gdb) 30665-break-disable 2 30666^done 30667(gdb) 30668-break-list 30669^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 30670hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 30671@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 30672@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 30673@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 30674@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 30675@{width="40",alignment="2",col_name="what",colhdr="What"@}], 30676body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n", 30677addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 30678line="5",thread-groups=["i1"],times="0"@}]@} 30679(gdb) 30680@end smallexample 30681 30682@subheading The @code{-break-enable} Command 30683@findex -break-enable 30684 30685@subsubheading Synopsis 30686 30687@smallexample 30688 -break-enable ( @var{breakpoint} )+ 30689@end smallexample 30690 30691Enable (previously disabled) @var{breakpoint}(s). 30692 30693@subsubheading @value{GDBN} Command 30694 30695The corresponding @value{GDBN} command is @samp{enable}. 30696 30697@subsubheading Example 30698 30699@smallexample 30700(gdb) 30701-break-enable 2 30702^done 30703(gdb) 30704-break-list 30705^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 30706hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 30707@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 30708@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 30709@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 30710@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 30711@{width="40",alignment="2",col_name="what",colhdr="What"@}], 30712body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", 30713addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 30714line="5",thread-groups=["i1"],times="0"@}]@} 30715(gdb) 30716@end smallexample 30717 30718@subheading The @code{-break-info} Command 30719@findex -break-info 30720 30721@subsubheading Synopsis 30722 30723@smallexample 30724 -break-info @var{breakpoint} 30725@end smallexample 30726 30727@c REDUNDANT??? 30728Get information about a single breakpoint. 30729 30730The result is a table of breakpoints. @xref{GDB/MI Breakpoint 30731Information}, for details on the format of each breakpoint in the 30732table. 30733 30734@subsubheading @value{GDBN} Command 30735 30736The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}. 30737 30738@subsubheading Example 30739N.A. 30740 30741@subheading The @code{-break-insert} Command 30742@findex -break-insert 30743@anchor{-break-insert} 30744 30745@subsubheading Synopsis 30746 30747@smallexample 30748 -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] [ --qualified ] 30749 [ -c @var{condition} ] [ --force-condition ] [ -i @var{ignore-count} ] 30750 [ -p @var{thread-id} ] [ @var{location} ] 30751@end smallexample 30752 30753@noindent 30754If specified, @var{location}, can be one of: 30755 30756@table @var 30757@item linespec location 30758A linespec location. @xref{Linespec Locations}. 30759 30760@item explicit location 30761An explicit location. @sc{gdb/mi} explicit locations are 30762analogous to the CLI's explicit locations using the option names 30763listed below. @xref{Explicit Locations}. 30764 30765@table @samp 30766@item --source @var{filename} 30767The source file name of the location. This option requires the use 30768of either @samp{--function} or @samp{--line}. 30769 30770@item --function @var{function} 30771The name of a function or method. 30772 30773@item --label @var{label} 30774The name of a label. 30775 30776@item --line @var{lineoffset} 30777An absolute or relative line offset from the start of the location. 30778@end table 30779 30780@item address location 30781An address location, *@var{address}. @xref{Address Locations}. 30782@end table 30783 30784@noindent 30785The possible optional parameters of this command are: 30786 30787@table @samp 30788@item -t 30789Insert a temporary breakpoint. 30790@item -h 30791Insert a hardware breakpoint. 30792@item -f 30793If @var{location} cannot be parsed (for example if it 30794refers to unknown files or functions), create a pending 30795breakpoint. Without this flag, @value{GDBN} will report 30796an error, and won't create a breakpoint, if @var{location} 30797cannot be parsed. 30798@item -d 30799Create a disabled breakpoint. 30800@item -a 30801Create a tracepoint. @xref{Tracepoints}. When this parameter 30802is used together with @samp{-h}, a fast tracepoint is created. 30803@item -c @var{condition} 30804Make the breakpoint conditional on @var{condition}. 30805@item --force-condition 30806Forcibly define the breakpoint even if the condition is invalid at 30807all of the breakpoint locations. 30808@item -i @var{ignore-count} 30809Initialize the @var{ignore-count}. 30810@item -p @var{thread-id} 30811Restrict the breakpoint to the thread with the specified global 30812@var{thread-id}. 30813@item --qualified 30814This option makes @value{GDBN} interpret a function name specified as 30815a complete fully-qualified name. 30816@end table 30817 30818@subsubheading Result 30819 30820@xref{GDB/MI Breakpoint Information}, for details on the format of the 30821resulting breakpoint. 30822 30823Note: this format is open to change. 30824@c An out-of-band breakpoint instead of part of the result? 30825 30826@subsubheading @value{GDBN} Command 30827 30828The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak}, 30829@samp{hbreak}, and @samp{thbreak}. @c and @samp{rbreak}. 30830 30831@subsubheading Example 30832 30833@smallexample 30834(gdb) 30835-break-insert main 30836^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c", 30837fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"], 30838times="0"@} 30839(gdb) 30840-break-insert -t foo 30841^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c", 30842fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"], 30843times="0"@} 30844(gdb) 30845-break-list 30846^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 30847hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 30848@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 30849@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 30850@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 30851@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 30852@{width="40",alignment="2",col_name="what",colhdr="What"@}], 30853body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 30854addr="0x0001072c", func="main",file="recursive2.c", 30855fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"], 30856times="0"@}, 30857bkpt=@{number="2",type="breakpoint",disp="del",enabled="y", 30858addr="0x00010774",func="foo",file="recursive2.c", 30859fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"], 30860times="0"@}]@} 30861(gdb) 30862@c -break-insert -r foo.* 30863@c ~int foo(int, int); 30864@c ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c, 30865@c "fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"], 30866@c times="0"@} 30867@c (gdb) 30868@end smallexample 30869 30870@subheading The @code{-dprintf-insert} Command 30871@findex -dprintf-insert 30872 30873@subsubheading Synopsis 30874 30875@smallexample 30876 -dprintf-insert [ -t ] [ -f ] [ -d ] [ --qualified ] 30877 [ -c @var{condition} ] [--force-condition] [ -i @var{ignore-count} ] 30878 [ -p @var{thread-id} ] [ @var{location} ] [ @var{format} ] 30879 [ @var{argument} ] 30880@end smallexample 30881 30882@noindent 30883If supplied, @var{location} and @code{--qualified} may be specified 30884the same way as for the @code{-break-insert} command. 30885@xref{-break-insert}. 30886 30887The possible optional parameters of this command are: 30888 30889@table @samp 30890@item -t 30891Insert a temporary breakpoint. 30892@item -f 30893If @var{location} cannot be parsed (for example, if it 30894refers to unknown files or functions), create a pending 30895breakpoint. Without this flag, @value{GDBN} will report 30896an error, and won't create a breakpoint, if @var{location} 30897cannot be parsed. 30898@item -d 30899Create a disabled breakpoint. 30900@item -c @var{condition} 30901Make the breakpoint conditional on @var{condition}. 30902@item --force-condition 30903Forcibly define the breakpoint even if the condition is invalid at 30904all of the breakpoint locations. 30905@item -i @var{ignore-count} 30906Set the ignore count of the breakpoint (@pxref{Conditions, ignore count}) 30907to @var{ignore-count}. 30908@item -p @var{thread-id} 30909Restrict the breakpoint to the thread with the specified global 30910@var{thread-id}. 30911@end table 30912 30913@subsubheading Result 30914 30915@xref{GDB/MI Breakpoint Information}, for details on the format of the 30916resulting breakpoint. 30917 30918@c An out-of-band breakpoint instead of part of the result? 30919 30920@subsubheading @value{GDBN} Command 30921 30922The corresponding @value{GDBN} command is @samp{dprintf}. 30923 30924@subsubheading Example 30925 30926@smallexample 30927(gdb) 309284-dprintf-insert foo "At foo entry\n" 309294^done,bkpt=@{number="1",type="dprintf",disp="keep",enabled="y", 30930addr="0x000000000040061b",func="foo",file="mi-dprintf.c", 30931fullname="mi-dprintf.c",line="25",thread-groups=["i1"], 30932times="0",script=@{"printf \"At foo entry\\n\"","continue"@}, 30933original-location="foo"@} 30934(gdb) 309355-dprintf-insert 26 "arg=%d, g=%d\n" arg g 309365^done,bkpt=@{number="2",type="dprintf",disp="keep",enabled="y", 30937addr="0x000000000040062a",func="foo",file="mi-dprintf.c", 30938fullname="mi-dprintf.c",line="26",thread-groups=["i1"], 30939times="0",script=@{"printf \"arg=%d, g=%d\\n\", arg, g","continue"@}, 30940original-location="mi-dprintf.c:26"@} 30941(gdb) 30942@end smallexample 30943 30944@subheading The @code{-break-list} Command 30945@findex -break-list 30946 30947@subsubheading Synopsis 30948 30949@smallexample 30950 -break-list 30951@end smallexample 30952 30953Displays the list of inserted breakpoints, showing the following fields: 30954 30955@table @samp 30956@item Number 30957number of the breakpoint 30958@item Type 30959type of the breakpoint: @samp{breakpoint} or @samp{watchpoint} 30960@item Disposition 30961should the breakpoint be deleted or disabled when it is hit: @samp{keep} 30962or @samp{nokeep} 30963@item Enabled 30964is the breakpoint enabled or no: @samp{y} or @samp{n} 30965@item Address 30966memory location at which the breakpoint is set 30967@item What 30968logical location of the breakpoint, expressed by function name, file 30969name, line number 30970@item Thread-groups 30971list of thread groups to which this breakpoint applies 30972@item Times 30973number of times the breakpoint has been hit 30974@end table 30975 30976If there are no breakpoints or watchpoints, the @code{BreakpointTable} 30977@code{body} field is an empty list. 30978 30979@subsubheading @value{GDBN} Command 30980 30981The corresponding @value{GDBN} command is @samp{info break}. 30982 30983@subsubheading Example 30984 30985@smallexample 30986(gdb) 30987-break-list 30988^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 30989hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 30990@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 30991@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 30992@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 30993@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 30994@{width="40",alignment="2",col_name="what",colhdr="What"@}], 30995body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 30996addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"], 30997times="0"@}, 30998bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", 30999addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c", 31000line="13",thread-groups=["i1"],times="0"@}]@} 31001(gdb) 31002@end smallexample 31003 31004Here's an example of the result when there are no breakpoints: 31005 31006@smallexample 31007(gdb) 31008-break-list 31009^done,BreakpointTable=@{nr_rows="0",nr_cols="6", 31010hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 31011@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 31012@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 31013@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 31014@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 31015@{width="40",alignment="2",col_name="what",colhdr="What"@}], 31016body=[]@} 31017(gdb) 31018@end smallexample 31019 31020@subheading The @code{-break-passcount} Command 31021@findex -break-passcount 31022 31023@subsubheading Synopsis 31024 31025@smallexample 31026 -break-passcount @var{tracepoint-number} @var{passcount} 31027@end smallexample 31028 31029Set the passcount for tracepoint @var{tracepoint-number} to 31030@var{passcount}. If the breakpoint referred to by @var{tracepoint-number} 31031is not a tracepoint, error is emitted. This corresponds to CLI 31032command @samp{passcount}. 31033 31034@subheading The @code{-break-watch} Command 31035@findex -break-watch 31036 31037@subsubheading Synopsis 31038 31039@smallexample 31040 -break-watch [ -a | -r ] 31041@end smallexample 31042 31043Create a watchpoint. With the @samp{-a} option it will create an 31044@dfn{access} watchpoint, i.e., a watchpoint that triggers either on a 31045read from or on a write to the memory location. With the @samp{-r} 31046option, the watchpoint created is a @dfn{read} watchpoint, i.e., it will 31047trigger only when the memory location is accessed for reading. Without 31048either of the options, the watchpoint created is a regular watchpoint, 31049i.e., it will trigger when the memory location is accessed for writing. 31050@xref{Set Watchpoints, , Setting Watchpoints}. 31051 31052Note that @samp{-break-list} will report a single list of watchpoints and 31053breakpoints inserted. 31054 31055@subsubheading @value{GDBN} Command 31056 31057The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and 31058@samp{rwatch}. 31059 31060@subsubheading Example 31061 31062Setting a watchpoint on a variable in the @code{main} function: 31063 31064@smallexample 31065(gdb) 31066-break-watch x 31067^done,wpt=@{number="2",exp="x"@} 31068(gdb) 31069-exec-continue 31070^running 31071(gdb) 31072*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@}, 31073value=@{old="-268439212",new="55"@}, 31074frame=@{func="main",args=[],file="recursive2.c", 31075fullname="/home/foo/bar/recursive2.c",line="5",arch="i386:x86_64"@} 31076(gdb) 31077@end smallexample 31078 31079Setting a watchpoint on a variable local to a function. @value{GDBN} will stop 31080the program execution twice: first for the variable changing value, then 31081for the watchpoint going out of scope. 31082 31083@smallexample 31084(gdb) 31085-break-watch C 31086^done,wpt=@{number="5",exp="C"@} 31087(gdb) 31088-exec-continue 31089^running 31090(gdb) 31091*stopped,reason="watchpoint-trigger", 31092wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@}, 31093frame=@{func="callee4",args=[], 31094file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 31095fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13", 31096arch="i386:x86_64"@} 31097(gdb) 31098-exec-continue 31099^running 31100(gdb) 31101*stopped,reason="watchpoint-scope",wpnum="5", 31102frame=@{func="callee3",args=[@{name="strarg", 31103value="0x11940 \"A string argument.\""@}], 31104file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 31105fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18", 31106arch="i386:x86_64"@} 31107(gdb) 31108@end smallexample 31109 31110Listing breakpoints and watchpoints, at different points in the program 31111execution. Note that once the watchpoint goes out of scope, it is 31112deleted. 31113 31114@smallexample 31115(gdb) 31116-break-watch C 31117^done,wpt=@{number="2",exp="C"@} 31118(gdb) 31119-break-list 31120^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 31121hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 31122@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 31123@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 31124@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 31125@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 31126@{width="40",alignment="2",col_name="what",colhdr="What"@}], 31127body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 31128addr="0x00010734",func="callee4", 31129file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 31130fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"], 31131times="1"@}, 31132bkpt=@{number="2",type="watchpoint",disp="keep", 31133enabled="y",addr="",what="C",thread-groups=["i1"],times="0"@}]@} 31134(gdb) 31135-exec-continue 31136^running 31137(gdb) 31138*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@}, 31139value=@{old="-276895068",new="3"@}, 31140frame=@{func="callee4",args=[], 31141file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 31142fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13", 31143arch="i386:x86_64"@} 31144(gdb) 31145-break-list 31146^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 31147hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 31148@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 31149@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 31150@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 31151@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 31152@{width="40",alignment="2",col_name="what",colhdr="What"@}], 31153body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 31154addr="0x00010734",func="callee4", 31155file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 31156fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"], 31157times="1"@}, 31158bkpt=@{number="2",type="watchpoint",disp="keep", 31159enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"@}]@} 31160(gdb) 31161-exec-continue 31162^running 31163^done,reason="watchpoint-scope",wpnum="2", 31164frame=@{func="callee3",args=[@{name="strarg", 31165value="0x11940 \"A string argument.\""@}], 31166file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 31167fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18", 31168arch="i386:x86_64"@} 31169(gdb) 31170-break-list 31171^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 31172hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 31173@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 31174@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 31175@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 31176@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 31177@{width="40",alignment="2",col_name="what",colhdr="What"@}], 31178body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 31179addr="0x00010734",func="callee4", 31180file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 31181fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8", 31182thread-groups=["i1"],times="1"@}]@} 31183(gdb) 31184@end smallexample 31185 31186 31187@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 31188@node GDB/MI Catchpoint Commands 31189@section @sc{gdb/mi} Catchpoint Commands 31190 31191This section documents @sc{gdb/mi} commands for manipulating 31192catchpoints. 31193 31194@menu 31195* Shared Library GDB/MI Catchpoint Commands:: 31196* Ada Exception GDB/MI Catchpoint Commands:: 31197* C++ Exception GDB/MI Catchpoint Commands:: 31198@end menu 31199 31200@node Shared Library GDB/MI Catchpoint Commands 31201@subsection Shared Library @sc{gdb/mi} Catchpoints 31202 31203@subheading The @code{-catch-load} Command 31204@findex -catch-load 31205 31206@subsubheading Synopsis 31207 31208@smallexample 31209 -catch-load [ -t ] [ -d ] @var{regexp} 31210@end smallexample 31211 31212Add a catchpoint for library load events. If the @samp{-t} option is used, 31213the catchpoint is a temporary one (@pxref{Set Breaks, ,Setting 31214Breakpoints}). If the @samp{-d} option is used, the catchpoint is created 31215in a disabled state. The @samp{regexp} argument is a regular 31216expression used to match the name of the loaded library. 31217 31218 31219@subsubheading @value{GDBN} Command 31220 31221The corresponding @value{GDBN} command is @samp{catch load}. 31222 31223@subsubheading Example 31224 31225@smallexample 31226-catch-load -t foo.so 31227^done,bkpt=@{number="1",type="catchpoint",disp="del",enabled="y", 31228what="load of library matching foo.so",catch-type="load",times="0"@} 31229(gdb) 31230@end smallexample 31231 31232 31233@subheading The @code{-catch-unload} Command 31234@findex -catch-unload 31235 31236@subsubheading Synopsis 31237 31238@smallexample 31239 -catch-unload [ -t ] [ -d ] @var{regexp} 31240@end smallexample 31241 31242Add a catchpoint for library unload events. If the @samp{-t} option is 31243used, the catchpoint is a temporary one (@pxref{Set Breaks, ,Setting 31244Breakpoints}). If the @samp{-d} option is used, the catchpoint is 31245created in a disabled state. The @samp{regexp} argument is a regular 31246expression used to match the name of the unloaded library. 31247 31248@subsubheading @value{GDBN} Command 31249 31250The corresponding @value{GDBN} command is @samp{catch unload}. 31251 31252@subsubheading Example 31253 31254@smallexample 31255-catch-unload -d bar.so 31256^done,bkpt=@{number="2",type="catchpoint",disp="keep",enabled="n", 31257what="load of library matching bar.so",catch-type="unload",times="0"@} 31258(gdb) 31259@end smallexample 31260 31261@node Ada Exception GDB/MI Catchpoint Commands 31262@subsection Ada Exception @sc{gdb/mi} Catchpoints 31263 31264The following @sc{gdb/mi} commands can be used to create catchpoints 31265that stop the execution when Ada exceptions are being raised. 31266 31267@subheading The @code{-catch-assert} Command 31268@findex -catch-assert 31269 31270@subsubheading Synopsis 31271 31272@smallexample 31273 -catch-assert [ -c @var{condition}] [ -d ] [ -t ] 31274@end smallexample 31275 31276Add a catchpoint for failed Ada assertions. 31277 31278The possible optional parameters for this command are: 31279 31280@table @samp 31281@item -c @var{condition} 31282Make the catchpoint conditional on @var{condition}. 31283@item -d 31284Create a disabled catchpoint. 31285@item -t 31286Create a temporary catchpoint. 31287@end table 31288 31289@subsubheading @value{GDBN} Command 31290 31291The corresponding @value{GDBN} command is @samp{catch assert}. 31292 31293@subsubheading Example 31294 31295@smallexample 31296-catch-assert 31297^done,bkptno="5",bkpt=@{number="5",type="breakpoint",disp="keep", 31298enabled="y",addr="0x0000000000404888",what="failed Ada assertions", 31299thread-groups=["i1"],times="0", 31300original-location="__gnat_debug_raise_assert_failure"@} 31301(gdb) 31302@end smallexample 31303 31304@subheading The @code{-catch-exception} Command 31305@findex -catch-exception 31306 31307@subsubheading Synopsis 31308 31309@smallexample 31310 -catch-exception [ -c @var{condition}] [ -d ] [ -e @var{exception-name} ] 31311 [ -t ] [ -u ] 31312@end smallexample 31313 31314Add a catchpoint stopping when Ada exceptions are raised. 31315By default, the command stops the program when any Ada exception 31316gets raised. But it is also possible, by using some of the 31317optional parameters described below, to create more selective 31318catchpoints. 31319 31320The possible optional parameters for this command are: 31321 31322@table @samp 31323@item -c @var{condition} 31324Make the catchpoint conditional on @var{condition}. 31325@item -d 31326Create a disabled catchpoint. 31327@item -e @var{exception-name} 31328Only stop when @var{exception-name} is raised. This option cannot 31329be used combined with @samp{-u}. 31330@item -t 31331Create a temporary catchpoint. 31332@item -u 31333Stop only when an unhandled exception gets raised. This option 31334cannot be used combined with @samp{-e}. 31335@end table 31336 31337@subsubheading @value{GDBN} Command 31338 31339The corresponding @value{GDBN} commands are @samp{catch exception} 31340and @samp{catch exception unhandled}. 31341 31342@subsubheading Example 31343 31344@smallexample 31345-catch-exception -e Program_Error 31346^done,bkptno="4",bkpt=@{number="4",type="breakpoint",disp="keep", 31347enabled="y",addr="0x0000000000404874", 31348what="`Program_Error' Ada exception", thread-groups=["i1"], 31349times="0",original-location="__gnat_debug_raise_exception"@} 31350(gdb) 31351@end smallexample 31352 31353@subheading The @code{-catch-handlers} Command 31354@findex -catch-handlers 31355 31356@subsubheading Synopsis 31357 31358@smallexample 31359 -catch-handlers [ -c @var{condition}] [ -d ] [ -e @var{exception-name} ] 31360 [ -t ] 31361@end smallexample 31362 31363Add a catchpoint stopping when Ada exceptions are handled. 31364By default, the command stops the program when any Ada exception 31365gets handled. But it is also possible, by using some of the 31366optional parameters described below, to create more selective 31367catchpoints. 31368 31369The possible optional parameters for this command are: 31370 31371@table @samp 31372@item -c @var{condition} 31373Make the catchpoint conditional on @var{condition}. 31374@item -d 31375Create a disabled catchpoint. 31376@item -e @var{exception-name} 31377Only stop when @var{exception-name} is handled. 31378@item -t 31379Create a temporary catchpoint. 31380@end table 31381 31382@subsubheading @value{GDBN} Command 31383 31384The corresponding @value{GDBN} command is @samp{catch handlers}. 31385 31386@subsubheading Example 31387 31388@smallexample 31389-catch-handlers -e Constraint_Error 31390^done,bkptno="4",bkpt=@{number="4",type="breakpoint",disp="keep", 31391enabled="y",addr="0x0000000000402f68", 31392what="`Constraint_Error' Ada exception handlers",thread-groups=["i1"], 31393times="0",original-location="__gnat_begin_handler"@} 31394(gdb) 31395@end smallexample 31396 31397@node C++ Exception GDB/MI Catchpoint Commands 31398@subsection C@t{++} Exception @sc{gdb/mi} Catchpoints 31399 31400The following @sc{gdb/mi} commands can be used to create catchpoints 31401that stop the execution when C@t{++} exceptions are being throw, rethrown, 31402or caught. 31403 31404@subheading The @code{-catch-throw} Command 31405@findex -catch-throw 31406 31407@subsubheading Synopsis 31408 31409@smallexample 31410 -catch-throw [ -t ] [ -r @var{regexp}] 31411@end smallexample 31412 31413Stop when the debuggee throws a C@t{++} exception. If @var{regexp} is 31414given, then only exceptions whose type matches the regular expression 31415will be caught. 31416 31417If @samp{-t} is given, then the catchpoint is enabled only for one 31418stop, the catchpoint is automatically deleted after stopping once for 31419the event. 31420 31421@subsubheading @value{GDBN} Command 31422 31423The corresponding @value{GDBN} commands are @samp{catch throw} 31424and @samp{tcatch throw} (@pxref{Set Catchpoints}). 31425 31426@subsubheading Example 31427 31428@smallexample 31429-catch-throw -r exception_type 31430^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y", 31431 what="exception throw",catch-type="throw", 31432 thread-groups=["i1"], 31433 regexp="exception_type",times="0"@} 31434(gdb) 31435-exec-run 31436^running 31437(gdb) 31438~"\n" 31439~"Catchpoint 1 (exception thrown), 0x00007ffff7ae00ed 31440 in __cxa_throw () from /lib64/libstdc++.so.6\n" 31441*stopped,bkptno="1",reason="breakpoint-hit",disp="keep", 31442 frame=@{addr="0x00007ffff7ae00ed",func="__cxa_throw", 31443 args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@}, 31444 thread-id="1",stopped-threads="all",core="6" 31445(gdb) 31446@end smallexample 31447 31448@subheading The @code{-catch-rethrow} Command 31449@findex -catch-rethrow 31450 31451@subsubheading Synopsis 31452 31453@smallexample 31454 -catch-rethrow [ -t ] [ -r @var{regexp}] 31455@end smallexample 31456 31457Stop when a C@t{++} exception is re-thrown. If @var{regexp} is given, 31458then only exceptions whose type matches the regular expression will be 31459caught. 31460 31461If @samp{-t} is given, then the catchpoint is enabled only for one 31462stop, the catchpoint is automatically deleted after the first event is 31463caught. 31464 31465@subsubheading @value{GDBN} Command 31466 31467The corresponding @value{GDBN} commands are @samp{catch rethrow} 31468and @samp{tcatch rethrow} (@pxref{Set Catchpoints}). 31469 31470@subsubheading Example 31471 31472@smallexample 31473-catch-rethrow -r exception_type 31474^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y", 31475 what="exception rethrow",catch-type="rethrow", 31476 thread-groups=["i1"], 31477 regexp="exception_type",times="0"@} 31478(gdb) 31479-exec-run 31480^running 31481(gdb) 31482~"\n" 31483~"Catchpoint 1 (exception rethrown), 0x00007ffff7ae00ed 31484 in __cxa_rethrow () from /lib64/libstdc++.so.6\n" 31485*stopped,bkptno="1",reason="breakpoint-hit",disp="keep", 31486 frame=@{addr="0x00007ffff7ae00ed",func="__cxa_rethrow", 31487 args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@}, 31488 thread-id="1",stopped-threads="all",core="6" 31489(gdb) 31490@end smallexample 31491 31492@subheading The @code{-catch-catch} Command 31493@findex -catch-catch 31494 31495@subsubheading Synopsis 31496 31497@smallexample 31498 -catch-catch [ -t ] [ -r @var{regexp}] 31499@end smallexample 31500 31501Stop when the debuggee catches a C@t{++} exception. If @var{regexp} 31502is given, then only exceptions whose type matches the regular 31503expression will be caught. 31504 31505If @samp{-t} is given, then the catchpoint is enabled only for one 31506stop, the catchpoint is automatically deleted after the first event is 31507caught. 31508 31509@subsubheading @value{GDBN} Command 31510 31511The corresponding @value{GDBN} commands are @samp{catch catch} 31512and @samp{tcatch catch} (@pxref{Set Catchpoints}). 31513 31514@subsubheading Example 31515 31516@smallexample 31517-catch-catch -r exception_type 31518^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y", 31519 what="exception catch",catch-type="catch", 31520 thread-groups=["i1"], 31521 regexp="exception_type",times="0"@} 31522(gdb) 31523-exec-run 31524^running 31525(gdb) 31526~"\n" 31527~"Catchpoint 1 (exception caught), 0x00007ffff7ae00ed 31528 in __cxa_begin_catch () from /lib64/libstdc++.so.6\n" 31529*stopped,bkptno="1",reason="breakpoint-hit",disp="keep", 31530 frame=@{addr="0x00007ffff7ae00ed",func="__cxa_begin_catch", 31531 args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@}, 31532 thread-id="1",stopped-threads="all",core="6" 31533(gdb) 31534@end smallexample 31535 31536@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 31537@node GDB/MI Program Context 31538@section @sc{gdb/mi} Program Context 31539 31540@subheading The @code{-exec-arguments} Command 31541@findex -exec-arguments 31542 31543 31544@subsubheading Synopsis 31545 31546@smallexample 31547 -exec-arguments @var{args} 31548@end smallexample 31549 31550Set the inferior program arguments, to be used in the next 31551@samp{-exec-run}. 31552 31553@subsubheading @value{GDBN} Command 31554 31555The corresponding @value{GDBN} command is @samp{set args}. 31556 31557@subsubheading Example 31558 31559@smallexample 31560(gdb) 31561-exec-arguments -v word 31562^done 31563(gdb) 31564@end smallexample 31565 31566 31567@ignore 31568@subheading The @code{-exec-show-arguments} Command 31569@findex -exec-show-arguments 31570 31571@subsubheading Synopsis 31572 31573@smallexample 31574 -exec-show-arguments 31575@end smallexample 31576 31577Print the arguments of the program. 31578 31579@subsubheading @value{GDBN} Command 31580 31581The corresponding @value{GDBN} command is @samp{show args}. 31582 31583@subsubheading Example 31584N.A. 31585@end ignore 31586 31587 31588@subheading The @code{-environment-cd} Command 31589@findex -environment-cd 31590 31591@subsubheading Synopsis 31592 31593@smallexample 31594 -environment-cd @var{pathdir} 31595@end smallexample 31596 31597Set @value{GDBN}'s working directory. 31598 31599@subsubheading @value{GDBN} Command 31600 31601The corresponding @value{GDBN} command is @samp{cd}. 31602 31603@subsubheading Example 31604 31605@smallexample 31606(gdb) 31607-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb 31608^done 31609(gdb) 31610@end smallexample 31611 31612 31613@subheading The @code{-environment-directory} Command 31614@findex -environment-directory 31615 31616@subsubheading Synopsis 31617 31618@smallexample 31619 -environment-directory [ -r ] [ @var{pathdir} ]+ 31620@end smallexample 31621 31622Add directories @var{pathdir} to beginning of search path for source files. 31623If the @samp{-r} option is used, the search path is reset to the default 31624search path. If directories @var{pathdir} are supplied in addition to the 31625@samp{-r} option, the search path is first reset and then addition 31626occurs as normal. 31627Multiple directories may be specified, separated by blanks. Specifying 31628multiple directories in a single command 31629results in the directories added to the beginning of the 31630search path in the same order they were presented in the command. 31631If blanks are needed as 31632part of a directory name, double-quotes should be used around 31633the name. In the command output, the path will show up separated 31634by the system directory-separator character. The directory-separator 31635character must not be used 31636in any directory name. 31637If no directories are specified, the current search path is displayed. 31638 31639@subsubheading @value{GDBN} Command 31640 31641The corresponding @value{GDBN} command is @samp{dir}. 31642 31643@subsubheading Example 31644 31645@smallexample 31646(gdb) 31647-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb 31648^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" 31649(gdb) 31650-environment-directory "" 31651^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" 31652(gdb) 31653-environment-directory -r /home/jjohnstn/src/gdb /usr/src 31654^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" 31655(gdb) 31656-environment-directory -r 31657^done,source-path="$cdir:$cwd" 31658(gdb) 31659@end smallexample 31660 31661 31662@subheading The @code{-environment-path} Command 31663@findex -environment-path 31664 31665@subsubheading Synopsis 31666 31667@smallexample 31668 -environment-path [ -r ] [ @var{pathdir} ]+ 31669@end smallexample 31670 31671Add directories @var{pathdir} to beginning of search path for object files. 31672If the @samp{-r} option is used, the search path is reset to the original 31673search path that existed at gdb start-up. If directories @var{pathdir} are 31674supplied in addition to the 31675@samp{-r} option, the search path is first reset and then addition 31676occurs as normal. 31677Multiple directories may be specified, separated by blanks. Specifying 31678multiple directories in a single command 31679results in the directories added to the beginning of the 31680search path in the same order they were presented in the command. 31681If blanks are needed as 31682part of a directory name, double-quotes should be used around 31683the name. In the command output, the path will show up separated 31684by the system directory-separator character. The directory-separator 31685character must not be used 31686in any directory name. 31687If no directories are specified, the current path is displayed. 31688 31689 31690@subsubheading @value{GDBN} Command 31691 31692The corresponding @value{GDBN} command is @samp{path}. 31693 31694@subsubheading Example 31695 31696@smallexample 31697(gdb) 31698-environment-path 31699^done,path="/usr/bin" 31700(gdb) 31701-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin 31702^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" 31703(gdb) 31704-environment-path -r /usr/local/bin 31705^done,path="/usr/local/bin:/usr/bin" 31706(gdb) 31707@end smallexample 31708 31709 31710@subheading The @code{-environment-pwd} Command 31711@findex -environment-pwd 31712 31713@subsubheading Synopsis 31714 31715@smallexample 31716 -environment-pwd 31717@end smallexample 31718 31719Show the current working directory. 31720 31721@subsubheading @value{GDBN} Command 31722 31723The corresponding @value{GDBN} command is @samp{pwd}. 31724 31725@subsubheading Example 31726 31727@smallexample 31728(gdb) 31729-environment-pwd 31730^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" 31731(gdb) 31732@end smallexample 31733 31734@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 31735@node GDB/MI Thread Commands 31736@section @sc{gdb/mi} Thread Commands 31737 31738 31739@subheading The @code{-thread-info} Command 31740@findex -thread-info 31741 31742@subsubheading Synopsis 31743 31744@smallexample 31745 -thread-info [ @var{thread-id} ] 31746@end smallexample 31747 31748Reports information about either a specific thread, if the 31749@var{thread-id} parameter is present, or about all threads. 31750@var{thread-id} is the thread's global thread ID. When printing 31751information about all threads, also reports the global ID of the 31752current thread. 31753 31754@subsubheading @value{GDBN} Command 31755 31756The @samp{info thread} command prints the same information 31757about all threads. 31758 31759@subsubheading Result 31760 31761The result contains the following attributes: 31762 31763@table @samp 31764@item threads 31765A list of threads. The format of the elements of the list is described in 31766@ref{GDB/MI Thread Information}. 31767 31768@item current-thread-id 31769The global id of the currently selected thread. This field is omitted if there 31770is no selected thread (for example, when the selected inferior is not running, 31771and therefore has no threads) or if a @var{thread-id} argument was passed to 31772the command. 31773 31774@end table 31775 31776@subsubheading Example 31777 31778@smallexample 31779-thread-info 31780^done,threads=[ 31781@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", 31782 frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall", 31783 args=[]@},state="running"@}, 31784@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", 31785 frame=@{level="0",addr="0x0804891f",func="foo", 31786 args=[@{name="i",value="10"@}], 31787 file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"@}, 31788 state="running"@}], 31789current-thread-id="1" 31790(gdb) 31791@end smallexample 31792 31793@subheading The @code{-thread-list-ids} Command 31794@findex -thread-list-ids 31795 31796@subsubheading Synopsis 31797 31798@smallexample 31799 -thread-list-ids 31800@end smallexample 31801 31802Produces a list of the currently known global @value{GDBN} thread ids. 31803At the end of the list it also prints the total number of such 31804threads. 31805 31806This command is retained for historical reasons, the 31807@code{-thread-info} command should be used instead. 31808 31809@subsubheading @value{GDBN} Command 31810 31811Part of @samp{info threads} supplies the same information. 31812 31813@subsubheading Example 31814 31815@smallexample 31816(gdb) 31817-thread-list-ids 31818^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, 31819current-thread-id="1",number-of-threads="3" 31820(gdb) 31821@end smallexample 31822 31823 31824@subheading The @code{-thread-select} Command 31825@findex -thread-select 31826 31827@subsubheading Synopsis 31828 31829@smallexample 31830 -thread-select @var{thread-id} 31831@end smallexample 31832 31833Make thread with global thread number @var{thread-id} the current 31834thread. It prints the number of the new current thread, and the 31835topmost frame for that thread. 31836 31837This command is deprecated in favor of explicitly using the 31838@samp{--thread} option to each command. 31839 31840@subsubheading @value{GDBN} Command 31841 31842The corresponding @value{GDBN} command is @samp{thread}. 31843 31844@subsubheading Example 31845 31846@smallexample 31847(gdb) 31848-exec-next 31849^running 31850(gdb) 31851*stopped,reason="end-stepping-range",thread-id="2",line="187", 31852file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" 31853(gdb) 31854-thread-list-ids 31855^done, 31856thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, 31857number-of-threads="3" 31858(gdb) 31859-thread-select 3 31860^done,new-thread-id="3", 31861frame=@{level="0",func="vprintf", 31862args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@}, 31863@{name="arg",value="0x2"@}],file="vprintf.c",line="31",arch="i386:x86_64"@} 31864(gdb) 31865@end smallexample 31866 31867@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 31868@node GDB/MI Ada Tasking Commands 31869@section @sc{gdb/mi} Ada Tasking Commands 31870 31871@subheading The @code{-ada-task-info} Command 31872@findex -ada-task-info 31873 31874@subsubheading Synopsis 31875 31876@smallexample 31877 -ada-task-info [ @var{task-id} ] 31878@end smallexample 31879 31880Reports information about either a specific Ada task, if the 31881@var{task-id} parameter is present, or about all Ada tasks. 31882 31883@subsubheading @value{GDBN} Command 31884 31885The @samp{info tasks} command prints the same information 31886about all Ada tasks (@pxref{Ada Tasks}). 31887 31888@subsubheading Result 31889 31890The result is a table of Ada tasks. The following columns are 31891defined for each Ada task: 31892 31893@table @samp 31894@item current 31895This field exists only for the current thread. It has the value @samp{*}. 31896 31897@item id 31898The identifier that @value{GDBN} uses to refer to the Ada task. 31899 31900@item task-id 31901The identifier that the target uses to refer to the Ada task. 31902 31903@item thread-id 31904The global thread identifier of the thread corresponding to the Ada 31905task. 31906 31907This field should always exist, as Ada tasks are always implemented 31908on top of a thread. But if @value{GDBN} cannot find this corresponding 31909thread for any reason, the field is omitted. 31910 31911@item parent-id 31912This field exists only when the task was created by another task. 31913In this case, it provides the ID of the parent task. 31914 31915@item priority 31916The base priority of the task. 31917 31918@item state 31919The current state of the task. For a detailed description of the 31920possible states, see @ref{Ada Tasks}. 31921 31922@item name 31923The name of the task. 31924 31925@end table 31926 31927@subsubheading Example 31928 31929@smallexample 31930-ada-task-info 31931^done,tasks=@{nr_rows="3",nr_cols="8", 31932hdr=[@{width="1",alignment="-1",col_name="current",colhdr=""@}, 31933@{width="3",alignment="1",col_name="id",colhdr="ID"@}, 31934@{width="9",alignment="1",col_name="task-id",colhdr="TID"@}, 31935@{width="4",alignment="1",col_name="thread-id",colhdr=""@}, 31936@{width="4",alignment="1",col_name="parent-id",colhdr="P-ID"@}, 31937@{width="3",alignment="1",col_name="priority",colhdr="Pri"@}, 31938@{width="22",alignment="-1",col_name="state",colhdr="State"@}, 31939@{width="1",alignment="2",col_name="name",colhdr="Name"@}], 31940body=[@{current="*",id="1",task-id=" 644010",thread-id="1",priority="48", 31941state="Child Termination Wait",name="main_task"@}]@} 31942(gdb) 31943@end smallexample 31944 31945@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 31946@node GDB/MI Program Execution 31947@section @sc{gdb/mi} Program Execution 31948 31949These are the asynchronous commands which generate the out-of-band 31950record @samp{*stopped}. Currently @value{GDBN} only really executes 31951asynchronously with remote targets and this interaction is mimicked in 31952other cases. 31953 31954@subheading The @code{-exec-continue} Command 31955@findex -exec-continue 31956 31957@subsubheading Synopsis 31958 31959@smallexample 31960 -exec-continue [--reverse] [--all|--thread-group N] 31961@end smallexample 31962 31963Resumes the execution of the inferior program, which will continue 31964to execute until it reaches a debugger stop event. If the 31965@samp{--reverse} option is specified, execution resumes in reverse until 31966it reaches a stop event. Stop events may include 31967@itemize @bullet 31968@item 31969breakpoints or watchpoints 31970@item 31971signals or exceptions 31972@item 31973the end of the process (or its beginning under @samp{--reverse}) 31974@item 31975the end or beginning of a replay log if one is being used. 31976@end itemize 31977In all-stop mode (@pxref{All-Stop 31978Mode}), may resume only one thread, or all threads, depending on the 31979value of the @samp{scheduler-locking} variable. If @samp{--all} is 31980specified, all threads (in all inferiors) will be resumed. The @samp{--all} option is 31981ignored in all-stop mode. If the @samp{--thread-group} options is 31982specified, then all threads in that thread group are resumed. 31983 31984@subsubheading @value{GDBN} Command 31985 31986The corresponding @value{GDBN} corresponding is @samp{continue}. 31987 31988@subsubheading Example 31989 31990@smallexample 31991-exec-continue 31992^running 31993(gdb) 31994@@Hello world 31995*stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame=@{ 31996func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", 31997line="13",arch="i386:x86_64"@} 31998(gdb) 31999@end smallexample 32000 32001 32002@subheading The @code{-exec-finish} Command 32003@findex -exec-finish 32004 32005@subsubheading Synopsis 32006 32007@smallexample 32008 -exec-finish [--reverse] 32009@end smallexample 32010 32011Resumes the execution of the inferior program until the current 32012function is exited. Displays the results returned by the function. 32013If the @samp{--reverse} option is specified, resumes the reverse 32014execution of the inferior program until the point where current 32015function was called. 32016 32017@subsubheading @value{GDBN} Command 32018 32019The corresponding @value{GDBN} command is @samp{finish}. 32020 32021@subsubheading Example 32022 32023Function returning @code{void}. 32024 32025@smallexample 32026-exec-finish 32027^running 32028(gdb) 32029@@hello from foo 32030*stopped,reason="function-finished",frame=@{func="main",args=[], 32031file="hello.c",fullname="/home/foo/bar/hello.c",line="7",arch="i386:x86_64"@} 32032(gdb) 32033@end smallexample 32034 32035Function returning other than @code{void}. The name of the internal 32036@value{GDBN} variable storing the result is printed, together with the 32037value itself. 32038 32039@smallexample 32040-exec-finish 32041^running 32042(gdb) 32043*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo", 32044args=[@{name="a",value="1"],@{name="b",value="9"@}@}, 32045file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 32046arch="i386:x86_64"@}, 32047gdb-result-var="$1",return-value="0" 32048(gdb) 32049@end smallexample 32050 32051 32052@subheading The @code{-exec-interrupt} Command 32053@findex -exec-interrupt 32054 32055@subsubheading Synopsis 32056 32057@smallexample 32058 -exec-interrupt [--all|--thread-group N] 32059@end smallexample 32060 32061Interrupts the background execution of the target. Note how the token 32062associated with the stop message is the one for the execution command 32063that has been interrupted. The token for the interrupt itself only 32064appears in the @samp{^done} output. If the user is trying to 32065interrupt a non-running program, an error message will be printed. 32066 32067Note that when asynchronous execution is enabled, this command is 32068asynchronous just like other execution commands. That is, first the 32069@samp{^done} response will be printed, and the target stop will be 32070reported after that using the @samp{*stopped} notification. 32071 32072In non-stop mode, only the context thread is interrupted by default. 32073All threads (in all inferiors) will be interrupted if the 32074@samp{--all} option is specified. If the @samp{--thread-group} 32075option is specified, all threads in that group will be interrupted. 32076 32077@subsubheading @value{GDBN} Command 32078 32079The corresponding @value{GDBN} command is @samp{interrupt}. 32080 32081@subsubheading Example 32082 32083@smallexample 32084(gdb) 32085111-exec-continue 32086111^running 32087 32088(gdb) 32089222-exec-interrupt 32090222^done 32091(gdb) 32092111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", 32093frame=@{addr="0x00010140",func="foo",args=[],file="try.c", 32094fullname="/home/foo/bar/try.c",line="13",arch="i386:x86_64"@} 32095(gdb) 32096 32097(gdb) 32098-exec-interrupt 32099^error,msg="mi_cmd_exec_interrupt: Inferior not executing." 32100(gdb) 32101@end smallexample 32102 32103@subheading The @code{-exec-jump} Command 32104@findex -exec-jump 32105 32106@subsubheading Synopsis 32107 32108@smallexample 32109 -exec-jump @var{location} 32110@end smallexample 32111 32112Resumes execution of the inferior program at the location specified by 32113parameter. @xref{Specify Location}, for a description of the 32114different forms of @var{location}. 32115 32116@subsubheading @value{GDBN} Command 32117 32118The corresponding @value{GDBN} command is @samp{jump}. 32119 32120@subsubheading Example 32121 32122@smallexample 32123-exec-jump foo.c:10 32124*running,thread-id="all" 32125^running 32126@end smallexample 32127 32128 32129@subheading The @code{-exec-next} Command 32130@findex -exec-next 32131 32132@subsubheading Synopsis 32133 32134@smallexample 32135 -exec-next [--reverse] 32136@end smallexample 32137 32138Resumes execution of the inferior program, stopping when the beginning 32139of the next source line is reached. 32140 32141If the @samp{--reverse} option is specified, resumes reverse execution 32142of the inferior program, stopping at the beginning of the previous 32143source line. If you issue this command on the first line of a 32144function, it will take you back to the caller of that function, to the 32145source line where the function was called. 32146 32147 32148@subsubheading @value{GDBN} Command 32149 32150The corresponding @value{GDBN} command is @samp{next}. 32151 32152@subsubheading Example 32153 32154@smallexample 32155-exec-next 32156^running 32157(gdb) 32158*stopped,reason="end-stepping-range",line="8",file="hello.c" 32159(gdb) 32160@end smallexample 32161 32162 32163@subheading The @code{-exec-next-instruction} Command 32164@findex -exec-next-instruction 32165 32166@subsubheading Synopsis 32167 32168@smallexample 32169 -exec-next-instruction [--reverse] 32170@end smallexample 32171 32172Executes one machine instruction. If the instruction is a function 32173call, continues until the function returns. If the program stops at an 32174instruction in the middle of a source line, the address will be 32175printed as well. 32176 32177If the @samp{--reverse} option is specified, resumes reverse execution 32178of the inferior program, stopping at the previous instruction. If the 32179previously executed instruction was a return from another function, 32180it will continue to execute in reverse until the call to that function 32181(from the current stack frame) is reached. 32182 32183@subsubheading @value{GDBN} Command 32184 32185The corresponding @value{GDBN} command is @samp{nexti}. 32186 32187@subsubheading Example 32188 32189@smallexample 32190(gdb) 32191-exec-next-instruction 32192^running 32193 32194(gdb) 32195*stopped,reason="end-stepping-range", 32196addr="0x000100d4",line="5",file="hello.c" 32197(gdb) 32198@end smallexample 32199 32200 32201@subheading The @code{-exec-return} Command 32202@findex -exec-return 32203 32204@subsubheading Synopsis 32205 32206@smallexample 32207 -exec-return 32208@end smallexample 32209 32210Makes current function return immediately. Doesn't execute the inferior. 32211Displays the new current frame. 32212 32213@subsubheading @value{GDBN} Command 32214 32215The corresponding @value{GDBN} command is @samp{return}. 32216 32217@subsubheading Example 32218 32219@smallexample 32220(gdb) 32221200-break-insert callee4 32222200^done,bkpt=@{number="1",addr="0x00010734", 32223file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} 32224(gdb) 32225000-exec-run 32226000^running 32227(gdb) 32228000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", 32229frame=@{func="callee4",args=[], 32230file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 32231fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8", 32232arch="i386:x86_64"@} 32233(gdb) 32234205-break-delete 32235205^done 32236(gdb) 32237111-exec-return 32238111^done,frame=@{level="0",func="callee3", 32239args=[@{name="strarg", 32240value="0x11940 \"A string argument.\""@}], 32241file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 32242fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18", 32243arch="i386:x86_64"@} 32244(gdb) 32245@end smallexample 32246 32247 32248@subheading The @code{-exec-run} Command 32249@findex -exec-run 32250 32251@subsubheading Synopsis 32252 32253@smallexample 32254 -exec-run [ --all | --thread-group N ] [ --start ] 32255@end smallexample 32256 32257Starts execution of the inferior from the beginning. The inferior 32258executes until either a breakpoint is encountered or the program 32259exits. In the latter case the output will include an exit code, if 32260the program has exited exceptionally. 32261 32262When neither the @samp{--all} nor the @samp{--thread-group} option 32263is specified, the current inferior is started. If the 32264@samp{--thread-group} option is specified, it should refer to a thread 32265group of type @samp{process}, and that thread group will be started. 32266If the @samp{--all} option is specified, then all inferiors will be started. 32267 32268Using the @samp{--start} option instructs the debugger to stop 32269the execution at the start of the inferior's main subprogram, 32270following the same behavior as the @code{start} command 32271(@pxref{Starting}). 32272 32273@subsubheading @value{GDBN} Command 32274 32275The corresponding @value{GDBN} command is @samp{run}. 32276 32277@subsubheading Examples 32278 32279@smallexample 32280(gdb) 32281-break-insert main 32282^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} 32283(gdb) 32284-exec-run 32285^running 32286(gdb) 32287*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", 32288frame=@{func="main",args=[],file="recursive2.c", 32289fullname="/home/foo/bar/recursive2.c",line="4",arch="i386:x86_64"@} 32290(gdb) 32291@end smallexample 32292 32293@noindent 32294Program exited normally: 32295 32296@smallexample 32297(gdb) 32298-exec-run 32299^running 32300(gdb) 32301x = 55 32302*stopped,reason="exited-normally" 32303(gdb) 32304@end smallexample 32305 32306@noindent 32307Program exited exceptionally: 32308 32309@smallexample 32310(gdb) 32311-exec-run 32312^running 32313(gdb) 32314x = 55 32315*stopped,reason="exited",exit-code="01" 32316(gdb) 32317@end smallexample 32318 32319Another way the program can terminate is if it receives a signal such as 32320@code{SIGINT}. In this case, @sc{gdb/mi} displays this: 32321 32322@smallexample 32323(gdb) 32324*stopped,reason="exited-signalled",signal-name="SIGINT", 32325signal-meaning="Interrupt" 32326@end smallexample 32327 32328 32329@c @subheading -exec-signal 32330 32331 32332@subheading The @code{-exec-step} Command 32333@findex -exec-step 32334 32335@subsubheading Synopsis 32336 32337@smallexample 32338 -exec-step [--reverse] 32339@end smallexample 32340 32341Resumes execution of the inferior program, stopping when the beginning 32342of the next source line is reached, if the next source line is not a 32343function call. If it is, stop at the first instruction of the called 32344function. If the @samp{--reverse} option is specified, resumes reverse 32345execution of the inferior program, stopping at the beginning of the 32346previously executed source line. 32347 32348@subsubheading @value{GDBN} Command 32349 32350The corresponding @value{GDBN} command is @samp{step}. 32351 32352@subsubheading Example 32353 32354Stepping into a function: 32355 32356@smallexample 32357-exec-step 32358^running 32359(gdb) 32360*stopped,reason="end-stepping-range", 32361frame=@{func="foo",args=[@{name="a",value="10"@}, 32362@{name="b",value="0"@}],file="recursive2.c", 32363fullname="/home/foo/bar/recursive2.c",line="11",arch="i386:x86_64"@} 32364(gdb) 32365@end smallexample 32366 32367Regular stepping: 32368 32369@smallexample 32370-exec-step 32371^running 32372(gdb) 32373*stopped,reason="end-stepping-range",line="14",file="recursive2.c" 32374(gdb) 32375@end smallexample 32376 32377 32378@subheading The @code{-exec-step-instruction} Command 32379@findex -exec-step-instruction 32380 32381@subsubheading Synopsis 32382 32383@smallexample 32384 -exec-step-instruction [--reverse] 32385@end smallexample 32386 32387Resumes the inferior which executes one machine instruction. If the 32388@samp{--reverse} option is specified, resumes reverse execution of the 32389inferior program, stopping at the previously executed instruction. 32390The output, once @value{GDBN} has stopped, will vary depending on 32391whether we have stopped in the middle of a source line or not. In the 32392former case, the address at which the program stopped will be printed 32393as well. 32394 32395@subsubheading @value{GDBN} Command 32396 32397The corresponding @value{GDBN} command is @samp{stepi}. 32398 32399@subsubheading Example 32400 32401@smallexample 32402(gdb) 32403-exec-step-instruction 32404^running 32405 32406(gdb) 32407*stopped,reason="end-stepping-range", 32408frame=@{func="foo",args=[],file="try.c", 32409fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"@} 32410(gdb) 32411-exec-step-instruction 32412^running 32413 32414(gdb) 32415*stopped,reason="end-stepping-range", 32416frame=@{addr="0x000100f4",func="foo",args=[],file="try.c", 32417fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"@} 32418(gdb) 32419@end smallexample 32420 32421 32422@subheading The @code{-exec-until} Command 32423@findex -exec-until 32424 32425@subsubheading Synopsis 32426 32427@smallexample 32428 -exec-until [ @var{location} ] 32429@end smallexample 32430 32431Executes the inferior until the @var{location} specified in the 32432argument is reached. If there is no argument, the inferior executes 32433until a source line greater than the current one is reached. The 32434reason for stopping in this case will be @samp{location-reached}. 32435 32436@subsubheading @value{GDBN} Command 32437 32438The corresponding @value{GDBN} command is @samp{until}. 32439 32440@subsubheading Example 32441 32442@smallexample 32443(gdb) 32444-exec-until recursive2.c:6 32445^running 32446(gdb) 32447x = 55 32448*stopped,reason="location-reached",frame=@{func="main",args=[], 32449file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6", 32450arch="i386:x86_64"@} 32451(gdb) 32452@end smallexample 32453 32454@ignore 32455@subheading -file-clear 32456Is this going away???? 32457@end ignore 32458 32459@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 32460@node GDB/MI Stack Manipulation 32461@section @sc{gdb/mi} Stack Manipulation Commands 32462 32463@subheading The @code{-enable-frame-filters} Command 32464@findex -enable-frame-filters 32465 32466@smallexample 32467-enable-frame-filters 32468@end smallexample 32469 32470@value{GDBN} allows Python-based frame filters to affect the output of 32471the MI commands relating to stack traces. As there is no way to 32472implement this in a fully backward-compatible way, a front end must 32473request that this functionality be enabled. 32474 32475Once enabled, this feature cannot be disabled. 32476 32477Note that if Python support has not been compiled into @value{GDBN}, 32478this command will still succeed (and do nothing). 32479 32480@subheading The @code{-stack-info-frame} Command 32481@findex -stack-info-frame 32482 32483@subsubheading Synopsis 32484 32485@smallexample 32486 -stack-info-frame 32487@end smallexample 32488 32489Get info on the selected frame. 32490 32491@subsubheading @value{GDBN} Command 32492 32493The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame} 32494(without arguments). 32495 32496@subsubheading Example 32497 32498@smallexample 32499(gdb) 32500-stack-info-frame 32501^done,frame=@{level="1",addr="0x0001076c",func="callee3", 32502file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 32503fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17", 32504arch="i386:x86_64"@} 32505(gdb) 32506@end smallexample 32507 32508@subheading The @code{-stack-info-depth} Command 32509@findex -stack-info-depth 32510 32511@subsubheading Synopsis 32512 32513@smallexample 32514 -stack-info-depth [ @var{max-depth} ] 32515@end smallexample 32516 32517Return the depth of the stack. If the integer argument @var{max-depth} 32518is specified, do not count beyond @var{max-depth} frames. 32519 32520@subsubheading @value{GDBN} Command 32521 32522There's no equivalent @value{GDBN} command. 32523 32524@subsubheading Example 32525 32526For a stack with frame levels 0 through 11: 32527 32528@smallexample 32529(gdb) 32530-stack-info-depth 32531^done,depth="12" 32532(gdb) 32533-stack-info-depth 4 32534^done,depth="4" 32535(gdb) 32536-stack-info-depth 12 32537^done,depth="12" 32538(gdb) 32539-stack-info-depth 11 32540^done,depth="11" 32541(gdb) 32542-stack-info-depth 13 32543^done,depth="12" 32544(gdb) 32545@end smallexample 32546 32547@anchor{-stack-list-arguments} 32548@subheading The @code{-stack-list-arguments} Command 32549@findex -stack-list-arguments 32550 32551@subsubheading Synopsis 32552 32553@smallexample 32554 -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values} 32555 [ @var{low-frame} @var{high-frame} ] 32556@end smallexample 32557 32558Display a list of the arguments for the frames between @var{low-frame} 32559and @var{high-frame} (inclusive). If @var{low-frame} and 32560@var{high-frame} are not provided, list the arguments for the whole 32561call stack. If the two arguments are equal, show the single frame 32562at the corresponding level. It is an error if @var{low-frame} is 32563larger than the actual number of frames. On the other hand, 32564@var{high-frame} may be larger than the actual number of frames, in 32565which case only existing frames will be returned. 32566 32567If @var{print-values} is 0 or @code{--no-values}, print only the names of 32568the variables; if it is 1 or @code{--all-values}, print also their 32569values; and if it is 2 or @code{--simple-values}, print the name, 32570type and value for simple data types, and the name and type for arrays, 32571structures and unions. If the option @code{--no-frame-filters} is 32572supplied, then Python frame filters will not be executed. 32573 32574If the @code{--skip-unavailable} option is specified, arguments that 32575are not available are not listed. Partially available arguments 32576are still displayed, however. 32577 32578Use of this command to obtain arguments in a single frame is 32579deprecated in favor of the @samp{-stack-list-variables} command. 32580 32581@subsubheading @value{GDBN} Command 32582 32583@value{GDBN} does not have an equivalent command. @code{gdbtk} has a 32584@samp{gdb_get_args} command which partially overlaps with the 32585functionality of @samp{-stack-list-arguments}. 32586 32587@subsubheading Example 32588 32589@smallexample 32590(gdb) 32591-stack-list-frames 32592^done, 32593stack=[ 32594frame=@{level="0",addr="0x00010734",func="callee4", 32595file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 32596fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8", 32597arch="i386:x86_64"@}, 32598frame=@{level="1",addr="0x0001076c",func="callee3", 32599file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 32600fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17", 32601arch="i386:x86_64"@}, 32602frame=@{level="2",addr="0x0001078c",func="callee2", 32603file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 32604fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22", 32605arch="i386:x86_64"@}, 32606frame=@{level="3",addr="0x000107b4",func="callee1", 32607file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 32608fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27", 32609arch="i386:x86_64"@}, 32610frame=@{level="4",addr="0x000107e0",func="main", 32611file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 32612fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32", 32613arch="i386:x86_64"@}] 32614(gdb) 32615-stack-list-arguments 0 32616^done, 32617stack-args=[ 32618frame=@{level="0",args=[]@}, 32619frame=@{level="1",args=[name="strarg"]@}, 32620frame=@{level="2",args=[name="intarg",name="strarg"]@}, 32621frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@}, 32622frame=@{level="4",args=[]@}] 32623(gdb) 32624-stack-list-arguments 1 32625^done, 32626stack-args=[ 32627frame=@{level="0",args=[]@}, 32628frame=@{level="1", 32629 args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, 32630frame=@{level="2",args=[ 32631@{name="intarg",value="2"@}, 32632@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, 32633@{frame=@{level="3",args=[ 32634@{name="intarg",value="2"@}, 32635@{name="strarg",value="0x11940 \"A string argument.\""@}, 32636@{name="fltarg",value="3.5"@}]@}, 32637frame=@{level="4",args=[]@}] 32638(gdb) 32639-stack-list-arguments 0 2 2 32640^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}] 32641(gdb) 32642-stack-list-arguments 1 2 2 32643^done,stack-args=[frame=@{level="2", 32644args=[@{name="intarg",value="2"@}, 32645@{name="strarg",value="0x11940 \"A string argument.\""@}]@}] 32646(gdb) 32647@end smallexample 32648 32649@c @subheading -stack-list-exception-handlers 32650 32651 32652@anchor{-stack-list-frames} 32653@subheading The @code{-stack-list-frames} Command 32654@findex -stack-list-frames 32655 32656@subsubheading Synopsis 32657 32658@smallexample 32659 -stack-list-frames [ --no-frame-filters @var{low-frame} @var{high-frame} ] 32660@end smallexample 32661 32662List the frames currently on the stack. For each frame it displays the 32663following info: 32664 32665@table @samp 32666@item @var{level} 32667The frame number, 0 being the topmost frame, i.e., the innermost function. 32668@item @var{addr} 32669The @code{$pc} value for that frame. 32670@item @var{func} 32671Function name. 32672@item @var{file} 32673File name of the source file where the function lives. 32674@item @var{fullname} 32675The full file name of the source file where the function lives. 32676@item @var{line} 32677Line number corresponding to the @code{$pc}. 32678@item @var{from} 32679The shared library where this function is defined. This is only given 32680if the frame's function is not known. 32681@item @var{arch} 32682Frame's architecture. 32683@end table 32684 32685If invoked without arguments, this command prints a backtrace for the 32686whole stack. If given two integer arguments, it shows the frames whose 32687levels are between the two arguments (inclusive). If the two arguments 32688are equal, it shows the single frame at the corresponding level. It is 32689an error if @var{low-frame} is larger than the actual number of 32690frames. On the other hand, @var{high-frame} may be larger than the 32691actual number of frames, in which case only existing frames will be 32692returned. If the option @code{--no-frame-filters} is supplied, then 32693Python frame filters will not be executed. 32694 32695@subsubheading @value{GDBN} Command 32696 32697The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}. 32698 32699@subsubheading Example 32700 32701Full stack backtrace: 32702 32703@smallexample 32704(gdb) 32705-stack-list-frames 32706^done,stack= 32707[frame=@{level="0",addr="0x0001076c",func="foo", 32708 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11", 32709 arch="i386:x86_64"@}, 32710frame=@{level="1",addr="0x000107a4",func="foo", 32711 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 32712 arch="i386:x86_64"@}, 32713frame=@{level="2",addr="0x000107a4",func="foo", 32714 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 32715 arch="i386:x86_64"@}, 32716frame=@{level="3",addr="0x000107a4",func="foo", 32717 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 32718 arch="i386:x86_64"@}, 32719frame=@{level="4",addr="0x000107a4",func="foo", 32720 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 32721 arch="i386:x86_64"@}, 32722frame=@{level="5",addr="0x000107a4",func="foo", 32723 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 32724 arch="i386:x86_64"@}, 32725frame=@{level="6",addr="0x000107a4",func="foo", 32726 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 32727 arch="i386:x86_64"@}, 32728frame=@{level="7",addr="0x000107a4",func="foo", 32729 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 32730 arch="i386:x86_64"@}, 32731frame=@{level="8",addr="0x000107a4",func="foo", 32732 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 32733 arch="i386:x86_64"@}, 32734frame=@{level="9",addr="0x000107a4",func="foo", 32735 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 32736 arch="i386:x86_64"@}, 32737frame=@{level="10",addr="0x000107a4",func="foo", 32738 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 32739 arch="i386:x86_64"@}, 32740frame=@{level="11",addr="0x00010738",func="main", 32741 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4", 32742 arch="i386:x86_64"@}] 32743(gdb) 32744@end smallexample 32745 32746Show frames between @var{low_frame} and @var{high_frame}: 32747 32748@smallexample 32749(gdb) 32750-stack-list-frames 3 5 32751^done,stack= 32752[frame=@{level="3",addr="0x000107a4",func="foo", 32753 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 32754 arch="i386:x86_64"@}, 32755frame=@{level="4",addr="0x000107a4",func="foo", 32756 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 32757 arch="i386:x86_64"@}, 32758frame=@{level="5",addr="0x000107a4",func="foo", 32759 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 32760 arch="i386:x86_64"@}] 32761(gdb) 32762@end smallexample 32763 32764Show a single frame: 32765 32766@smallexample 32767(gdb) 32768-stack-list-frames 3 3 32769^done,stack= 32770[frame=@{level="3",addr="0x000107a4",func="foo", 32771 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 32772 arch="i386:x86_64"@}] 32773(gdb) 32774@end smallexample 32775 32776 32777@subheading The @code{-stack-list-locals} Command 32778@findex -stack-list-locals 32779@anchor{-stack-list-locals} 32780 32781@subsubheading Synopsis 32782 32783@smallexample 32784 -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values} 32785@end smallexample 32786 32787Display the local variable names for the selected frame. If 32788@var{print-values} is 0 or @code{--no-values}, print only the names of 32789the variables; if it is 1 or @code{--all-values}, print also their 32790values; and if it is 2 or @code{--simple-values}, print the name, 32791type and value for simple data types, and the name and type for arrays, 32792structures and unions. In this last case, a frontend can immediately 32793display the value of simple data types and create variable objects for 32794other data types when the user wishes to explore their values in 32795more detail. If the option @code{--no-frame-filters} is supplied, then 32796Python frame filters will not be executed. 32797 32798If the @code{--skip-unavailable} option is specified, local variables 32799that are not available are not listed. Partially available local 32800variables are still displayed, however. 32801 32802This command is deprecated in favor of the 32803@samp{-stack-list-variables} command. 32804 32805@subsubheading @value{GDBN} Command 32806 32807@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}. 32808 32809@subsubheading Example 32810 32811@smallexample 32812(gdb) 32813-stack-list-locals 0 32814^done,locals=[name="A",name="B",name="C"] 32815(gdb) 32816-stack-list-locals --all-values 32817^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@}, 32818 @{name="C",value="@{1, 2, 3@}"@}] 32819-stack-list-locals --simple-values 32820^done,locals=[@{name="A",type="int",value="1"@}, 32821 @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}] 32822(gdb) 32823@end smallexample 32824 32825@anchor{-stack-list-variables} 32826@subheading The @code{-stack-list-variables} Command 32827@findex -stack-list-variables 32828 32829@subsubheading Synopsis 32830 32831@smallexample 32832 -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values} 32833@end smallexample 32834 32835Display the names of local variables and function arguments for the selected frame. If 32836@var{print-values} is 0 or @code{--no-values}, print only the names of 32837the variables; if it is 1 or @code{--all-values}, print also their 32838values; and if it is 2 or @code{--simple-values}, print the name, 32839type and value for simple data types, and the name and type for arrays, 32840structures and unions. If the option @code{--no-frame-filters} is 32841supplied, then Python frame filters will not be executed. 32842 32843If the @code{--skip-unavailable} option is specified, local variables 32844and arguments that are not available are not listed. Partially 32845available arguments and local variables are still displayed, however. 32846 32847@subsubheading Example 32848 32849@smallexample 32850(gdb) 32851-stack-list-variables --thread 1 --frame 0 --all-values 32852^done,variables=[@{name="x",value="11"@},@{name="s",value="@{a = 1, b = 2@}"@}] 32853(gdb) 32854@end smallexample 32855 32856 32857@subheading The @code{-stack-select-frame} Command 32858@findex -stack-select-frame 32859 32860@subsubheading Synopsis 32861 32862@smallexample 32863 -stack-select-frame @var{framenum} 32864@end smallexample 32865 32866Change the selected frame. Select a different frame @var{framenum} on 32867the stack. 32868 32869This command in deprecated in favor of passing the @samp{--frame} 32870option to every command. 32871 32872@subsubheading @value{GDBN} Command 32873 32874The corresponding @value{GDBN} commands are @samp{frame}, @samp{up}, 32875@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}. 32876 32877@subsubheading Example 32878 32879@smallexample 32880(gdb) 32881-stack-select-frame 2 32882^done 32883(gdb) 32884@end smallexample 32885 32886@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 32887@node GDB/MI Variable Objects 32888@section @sc{gdb/mi} Variable Objects 32889 32890@ignore 32891 32892@subheading Motivation for Variable Objects in @sc{gdb/mi} 32893 32894For the implementation of a variable debugger window (locals, watched 32895expressions, etc.), we are proposing the adaptation of the existing code 32896used by @code{Insight}. 32897 32898The two main reasons for that are: 32899 32900@enumerate 1 32901@item 32902It has been proven in practice (it is already on its second generation). 32903 32904@item 32905It will shorten development time (needless to say how important it is 32906now). 32907@end enumerate 32908 32909The original interface was designed to be used by Tcl code, so it was 32910slightly changed so it could be used through @sc{gdb/mi}. This section 32911describes the @sc{gdb/mi} operations that will be available and gives some 32912hints about their use. 32913 32914@emph{Note}: In addition to the set of operations described here, we 32915expect the @sc{gui} implementation of a variable window to require, at 32916least, the following operations: 32917 32918@itemize @bullet 32919@item @code{-gdb-show} @code{output-radix} 32920@item @code{-stack-list-arguments} 32921@item @code{-stack-list-locals} 32922@item @code{-stack-select-frame} 32923@end itemize 32924 32925@end ignore 32926 32927@subheading Introduction to Variable Objects 32928 32929@cindex variable objects in @sc{gdb/mi} 32930 32931Variable objects are "object-oriented" MI interface for examining and 32932changing values of expressions. Unlike some other MI interfaces that 32933work with expressions, variable objects are specifically designed for 32934simple and efficient presentation in the frontend. A variable object 32935is identified by string name. When a variable object is created, the 32936frontend specifies the expression for that variable object. The 32937expression can be a simple variable, or it can be an arbitrary complex 32938expression, and can even involve CPU registers. After creating a 32939variable object, the frontend can invoke other variable object 32940operations---for example to obtain or change the value of a variable 32941object, or to change display format. 32942 32943Variable objects have hierarchical tree structure. Any variable object 32944that corresponds to a composite type, such as structure in C, has 32945a number of child variable objects, for example corresponding to each 32946element of a structure. A child variable object can itself have 32947children, recursively. Recursion ends when we reach 32948leaf variable objects, which always have built-in types. Child variable 32949objects are created only by explicit request, so if a frontend 32950is not interested in the children of a particular variable object, no 32951child will be created. 32952 32953For a leaf variable object it is possible to obtain its value as a 32954string, or set the value from a string. String value can be also 32955obtained for a non-leaf variable object, but it's generally a string 32956that only indicates the type of the object, and does not list its 32957contents. Assignment to a non-leaf variable object is not allowed. 32958 32959A frontend does not need to read the values of all variable objects each time 32960the program stops. Instead, MI provides an update command that lists all 32961variable objects whose values has changed since the last update 32962operation. This considerably reduces the amount of data that must 32963be transferred to the frontend. As noted above, children variable 32964objects are created on demand, and only leaf variable objects have a 32965real value. As result, gdb will read target memory only for leaf 32966variables that frontend has created. 32967 32968The automatic update is not always desirable. For example, a frontend 32969might want to keep a value of some expression for future reference, 32970and never update it. For another example, fetching memory is 32971relatively slow for embedded targets, so a frontend might want 32972to disable automatic update for the variables that are either not 32973visible on the screen, or ``closed''. This is possible using so 32974called ``frozen variable objects''. Such variable objects are never 32975implicitly updated. 32976 32977Variable objects can be either @dfn{fixed} or @dfn{floating}. For the 32978fixed variable object, the expression is parsed when the variable 32979object is created, including associating identifiers to specific 32980variables. The meaning of expression never changes. For a floating 32981variable object the values of variables whose names appear in the 32982expressions are re-evaluated every time in the context of the current 32983frame. Consider this example: 32984 32985@smallexample 32986void do_work(...) 32987@{ 32988 struct work_state state; 32989 32990 if (...) 32991 do_work(...); 32992@} 32993@end smallexample 32994 32995If a fixed variable object for the @code{state} variable is created in 32996this function, and we enter the recursive call, the variable 32997object will report the value of @code{state} in the top-level 32998@code{do_work} invocation. On the other hand, a floating variable 32999object will report the value of @code{state} in the current frame. 33000 33001If an expression specified when creating a fixed variable object 33002refers to a local variable, the variable object becomes bound to the 33003thread and frame in which the variable object is created. When such 33004variable object is updated, @value{GDBN} makes sure that the 33005thread/frame combination the variable object is bound to still exists, 33006and re-evaluates the variable object in context of that thread/frame. 33007 33008The following is the complete set of @sc{gdb/mi} operations defined to 33009access this functionality: 33010 33011@multitable @columnfractions .4 .6 33012@item @strong{Operation} 33013@tab @strong{Description} 33014 33015@item @code{-enable-pretty-printing} 33016@tab enable Python-based pretty-printing 33017@item @code{-var-create} 33018@tab create a variable object 33019@item @code{-var-delete} 33020@tab delete the variable object and/or its children 33021@item @code{-var-set-format} 33022@tab set the display format of this variable 33023@item @code{-var-show-format} 33024@tab show the display format of this variable 33025@item @code{-var-info-num-children} 33026@tab tells how many children this object has 33027@item @code{-var-list-children} 33028@tab return a list of the object's children 33029@item @code{-var-info-type} 33030@tab show the type of this variable object 33031@item @code{-var-info-expression} 33032@tab print parent-relative expression that this variable object represents 33033@item @code{-var-info-path-expression} 33034@tab print full expression that this variable object represents 33035@item @code{-var-show-attributes} 33036@tab is this variable editable? does it exist here? 33037@item @code{-var-evaluate-expression} 33038@tab get the value of this variable 33039@item @code{-var-assign} 33040@tab set the value of this variable 33041@item @code{-var-update} 33042@tab update the variable and its children 33043@item @code{-var-set-frozen} 33044@tab set frozenness attribute 33045@item @code{-var-set-update-range} 33046@tab set range of children to display on update 33047@end multitable 33048 33049In the next subsection we describe each operation in detail and suggest 33050how it can be used. 33051 33052@subheading Description And Use of Operations on Variable Objects 33053 33054@subheading The @code{-enable-pretty-printing} Command 33055@findex -enable-pretty-printing 33056 33057@smallexample 33058-enable-pretty-printing 33059@end smallexample 33060 33061@value{GDBN} allows Python-based visualizers to affect the output of the 33062MI variable object commands. However, because there was no way to 33063implement this in a fully backward-compatible way, a front end must 33064request that this functionality be enabled. 33065 33066Once enabled, this feature cannot be disabled. 33067 33068Note that if Python support has not been compiled into @value{GDBN}, 33069this command will still succeed (and do nothing). 33070 33071This feature is currently (as of @value{GDBN} 7.0) experimental, and 33072may work differently in future versions of @value{GDBN}. 33073 33074@subheading The @code{-var-create} Command 33075@findex -var-create 33076 33077@subsubheading Synopsis 33078 33079@smallexample 33080 -var-create @{@var{name} | "-"@} 33081 @{@var{frame-addr} | "*" | "@@"@} @var{expression} 33082@end smallexample 33083 33084This operation creates a variable object, which allows the monitoring of 33085a variable, the result of an expression, a memory cell or a CPU 33086register. 33087 33088The @var{name} parameter is the string by which the object can be 33089referenced. It must be unique. If @samp{-} is specified, the varobj 33090system will generate a string ``varNNNNNN'' automatically. It will be 33091unique provided that one does not specify @var{name} of that format. 33092The command fails if a duplicate name is found. 33093 33094The frame under which the expression should be evaluated can be 33095specified by @var{frame-addr}. A @samp{*} indicates that the current 33096frame should be used. A @samp{@@} indicates that a floating variable 33097object must be created. 33098 33099@var{expression} is any expression valid on the current language set (must not 33100begin with a @samp{*}), or one of the following: 33101 33102@itemize @bullet 33103@item 33104@samp{*@var{addr}}, where @var{addr} is the address of a memory cell 33105 33106@item 33107@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD) 33108 33109@item 33110@samp{$@var{regname}} --- a CPU register name 33111@end itemize 33112 33113@cindex dynamic varobj 33114A varobj's contents may be provided by a Python-based pretty-printer. In this 33115case the varobj is known as a @dfn{dynamic varobj}. Dynamic varobjs 33116have slightly different semantics in some cases. If the 33117@code{-enable-pretty-printing} command is not sent, then @value{GDBN} 33118will never create a dynamic varobj. This ensures backward 33119compatibility for existing clients. 33120 33121@subsubheading Result 33122 33123This operation returns attributes of the newly-created varobj. These 33124are: 33125 33126@table @samp 33127@item name 33128The name of the varobj. 33129 33130@item numchild 33131The number of children of the varobj. This number is not necessarily 33132reliable for a dynamic varobj. Instead, you must examine the 33133@samp{has_more} attribute. 33134 33135@item value 33136The varobj's scalar value. For a varobj whose type is some sort of 33137aggregate (e.g., a @code{struct}), or for a dynamic varobj, this value 33138will not be interesting. 33139 33140@item type 33141The varobj's type. This is a string representation of the type, as 33142would be printed by the @value{GDBN} CLI. If @samp{print object} 33143(@pxref{Print Settings, set print object}) is set to @code{on}, the 33144@emph{actual} (derived) type of the object is shown rather than the 33145@emph{declared} one. 33146 33147@item thread-id 33148If a variable object is bound to a specific thread, then this is the 33149thread's global identifier. 33150 33151@item has_more 33152For a dynamic varobj, this indicates whether there appear to be any 33153children available. For a non-dynamic varobj, this will be 0. 33154 33155@item dynamic 33156This attribute will be present and have the value @samp{1} if the 33157varobj is a dynamic varobj. If the varobj is not a dynamic varobj, 33158then this attribute will not be present. 33159 33160@item displayhint 33161A dynamic varobj can supply a display hint to the front end. The 33162value comes directly from the Python pretty-printer object's 33163@code{display_hint} method. @xref{Pretty Printing API}. 33164@end table 33165 33166Typical output will look like this: 33167 33168@smallexample 33169 name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}", 33170 has_more="@var{has_more}" 33171@end smallexample 33172 33173 33174@subheading The @code{-var-delete} Command 33175@findex -var-delete 33176 33177@subsubheading Synopsis 33178 33179@smallexample 33180 -var-delete [ -c ] @var{name} 33181@end smallexample 33182 33183Deletes a previously created variable object and all of its children. 33184With the @samp{-c} option, just deletes the children. 33185 33186Returns an error if the object @var{name} is not found. 33187 33188 33189@subheading The @code{-var-set-format} Command 33190@findex -var-set-format 33191 33192@subsubheading Synopsis 33193 33194@smallexample 33195 -var-set-format @var{name} @var{format-spec} 33196@end smallexample 33197 33198Sets the output format for the value of the object @var{name} to be 33199@var{format-spec}. 33200 33201@anchor{-var-set-format} 33202The syntax for the @var{format-spec} is as follows: 33203 33204@smallexample 33205 @var{format-spec} @expansion{} 33206 @{binary | decimal | hexadecimal | octal | natural | zero-hexadecimal@} 33207@end smallexample 33208 33209The natural format is the default format choosen automatically 33210based on the variable type (like decimal for an @code{int}, hex 33211for pointers, etc.). 33212 33213The zero-hexadecimal format has a representation similar to hexadecimal 33214but with padding zeroes to the left of the value. For example, a 32-bit 33215hexadecimal value of 0x1234 would be represented as 0x00001234 in the 33216zero-hexadecimal format. 33217 33218For a variable with children, the format is set only on the 33219variable itself, and the children are not affected. 33220 33221@subheading The @code{-var-show-format} Command 33222@findex -var-show-format 33223 33224@subsubheading Synopsis 33225 33226@smallexample 33227 -var-show-format @var{name} 33228@end smallexample 33229 33230Returns the format used to display the value of the object @var{name}. 33231 33232@smallexample 33233 @var{format} @expansion{} 33234 @var{format-spec} 33235@end smallexample 33236 33237 33238@subheading The @code{-var-info-num-children} Command 33239@findex -var-info-num-children 33240 33241@subsubheading Synopsis 33242 33243@smallexample 33244 -var-info-num-children @var{name} 33245@end smallexample 33246 33247Returns the number of children of a variable object @var{name}: 33248 33249@smallexample 33250 numchild=@var{n} 33251@end smallexample 33252 33253Note that this number is not completely reliable for a dynamic varobj. 33254It will return the current number of children, but more children may 33255be available. 33256 33257 33258@subheading The @code{-var-list-children} Command 33259@findex -var-list-children 33260 33261@subsubheading Synopsis 33262 33263@smallexample 33264 -var-list-children [@var{print-values}] @var{name} [@var{from} @var{to}] 33265@end smallexample 33266@anchor{-var-list-children} 33267 33268Return a list of the children of the specified variable object and 33269create variable objects for them, if they do not already exist. With 33270a single argument or if @var{print-values} has a value of 0 or 33271@code{--no-values}, print only the names of the variables; if 33272@var{print-values} is 1 or @code{--all-values}, also print their 33273values; and if it is 2 or @code{--simple-values} print the name and 33274value for simple data types and just the name for arrays, structures 33275and unions. 33276 33277@var{from} and @var{to}, if specified, indicate the range of children 33278to report. If @var{from} or @var{to} is less than zero, the range is 33279reset and all children will be reported. Otherwise, children starting 33280at @var{from} (zero-based) and up to and excluding @var{to} will be 33281reported. 33282 33283If a child range is requested, it will only affect the current call to 33284@code{-var-list-children}, but not future calls to @code{-var-update}. 33285For this, you must instead use @code{-var-set-update-range}. The 33286intent of this approach is to enable a front end to implement any 33287update approach it likes; for example, scrolling a view may cause the 33288front end to request more children with @code{-var-list-children}, and 33289then the front end could call @code{-var-set-update-range} with a 33290different range to ensure that future updates are restricted to just 33291the visible items. 33292 33293For each child the following results are returned: 33294 33295@table @var 33296 33297@item name 33298Name of the variable object created for this child. 33299 33300@item exp 33301The expression to be shown to the user by the front end to designate this child. 33302For example this may be the name of a structure member. 33303 33304For a dynamic varobj, this value cannot be used to form an 33305expression. There is no way to do this at all with a dynamic varobj. 33306 33307For C/C@t{++} structures there are several pseudo children returned to 33308designate access qualifiers. For these pseudo children @var{exp} is 33309@samp{public}, @samp{private}, or @samp{protected}. In this case the 33310type and value are not present. 33311 33312A dynamic varobj will not report the access qualifying 33313pseudo-children, regardless of the language. This information is not 33314available at all with a dynamic varobj. 33315 33316@item numchild 33317Number of children this child has. For a dynamic varobj, this will be 333180. 33319 33320@item type 33321The type of the child. If @samp{print object} 33322(@pxref{Print Settings, set print object}) is set to @code{on}, the 33323@emph{actual} (derived) type of the object is shown rather than the 33324@emph{declared} one. 33325 33326@item value 33327If values were requested, this is the value. 33328 33329@item thread-id 33330If this variable object is associated with a thread, this is the 33331thread's global thread id. Otherwise this result is not present. 33332 33333@item frozen 33334If the variable object is frozen, this variable will be present with a value of 1. 33335 33336@item displayhint 33337A dynamic varobj can supply a display hint to the front end. The 33338value comes directly from the Python pretty-printer object's 33339@code{display_hint} method. @xref{Pretty Printing API}. 33340 33341@item dynamic 33342This attribute will be present and have the value @samp{1} if the 33343varobj is a dynamic varobj. If the varobj is not a dynamic varobj, 33344then this attribute will not be present. 33345 33346@end table 33347 33348The result may have its own attributes: 33349 33350@table @samp 33351@item displayhint 33352A dynamic varobj can supply a display hint to the front end. The 33353value comes directly from the Python pretty-printer object's 33354@code{display_hint} method. @xref{Pretty Printing API}. 33355 33356@item has_more 33357This is an integer attribute which is nonzero if there are children 33358remaining after the end of the selected range. 33359@end table 33360 33361@subsubheading Example 33362 33363@smallexample 33364(gdb) 33365 -var-list-children n 33366 ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp}, 33367 numchild=@var{n},type=@var{type}@},@r{(repeats N times)}] 33368(gdb) 33369 -var-list-children --all-values n 33370 ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp}, 33371 numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}] 33372@end smallexample 33373 33374 33375@subheading The @code{-var-info-type} Command 33376@findex -var-info-type 33377 33378@subsubheading Synopsis 33379 33380@smallexample 33381 -var-info-type @var{name} 33382@end smallexample 33383 33384Returns the type of the specified variable @var{name}. The type is 33385returned as a string in the same format as it is output by the 33386@value{GDBN} CLI: 33387 33388@smallexample 33389 type=@var{typename} 33390@end smallexample 33391 33392 33393@subheading The @code{-var-info-expression} Command 33394@findex -var-info-expression 33395 33396@subsubheading Synopsis 33397 33398@smallexample 33399 -var-info-expression @var{name} 33400@end smallexample 33401 33402Returns a string that is suitable for presenting this 33403variable object in user interface. The string is generally 33404not valid expression in the current language, and cannot be evaluated. 33405 33406For example, if @code{a} is an array, and variable object 33407@code{A} was created for @code{a}, then we'll get this output: 33408 33409@smallexample 33410(gdb) -var-info-expression A.1 33411^done,lang="C",exp="1" 33412@end smallexample 33413 33414@noindent 33415Here, the value of @code{lang} is the language name, which can be 33416found in @ref{Supported Languages}. 33417 33418Note that the output of the @code{-var-list-children} command also 33419includes those expressions, so the @code{-var-info-expression} command 33420is of limited use. 33421 33422@subheading The @code{-var-info-path-expression} Command 33423@findex -var-info-path-expression 33424 33425@subsubheading Synopsis 33426 33427@smallexample 33428 -var-info-path-expression @var{name} 33429@end smallexample 33430 33431Returns an expression that can be evaluated in the current 33432context and will yield the same value that a variable object has. 33433Compare this with the @code{-var-info-expression} command, which 33434result can be used only for UI presentation. Typical use of 33435the @code{-var-info-path-expression} command is creating a 33436watchpoint from a variable object. 33437 33438This command is currently not valid for children of a dynamic varobj, 33439and will give an error when invoked on one. 33440 33441For example, suppose @code{C} is a C@t{++} class, derived from class 33442@code{Base}, and that the @code{Base} class has a member called 33443@code{m_size}. Assume a variable @code{c} is has the type of 33444@code{C} and a variable object @code{C} was created for variable 33445@code{c}. Then, we'll get this output: 33446@smallexample 33447(gdb) -var-info-path-expression C.Base.public.m_size 33448^done,path_expr=((Base)c).m_size) 33449@end smallexample 33450 33451@subheading The @code{-var-show-attributes} Command 33452@findex -var-show-attributes 33453 33454@subsubheading Synopsis 33455 33456@smallexample 33457 -var-show-attributes @var{name} 33458@end smallexample 33459 33460List attributes of the specified variable object @var{name}: 33461 33462@smallexample 33463 status=@var{attr} [ ( ,@var{attr} )* ] 33464@end smallexample 33465 33466@noindent 33467where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}. 33468 33469@subheading The @code{-var-evaluate-expression} Command 33470@findex -var-evaluate-expression 33471 33472@subsubheading Synopsis 33473 33474@smallexample 33475 -var-evaluate-expression [-f @var{format-spec}] @var{name} 33476@end smallexample 33477 33478Evaluates the expression that is represented by the specified variable 33479object and returns its value as a string. The format of the string 33480can be specified with the @samp{-f} option. The possible values of 33481this option are the same as for @code{-var-set-format} 33482(@pxref{-var-set-format}). If the @samp{-f} option is not specified, 33483the current display format will be used. The current display format 33484can be changed using the @code{-var-set-format} command. 33485 33486@smallexample 33487 value=@var{value} 33488@end smallexample 33489 33490Note that one must invoke @code{-var-list-children} for a variable 33491before the value of a child variable can be evaluated. 33492 33493@subheading The @code{-var-assign} Command 33494@findex -var-assign 33495 33496@subsubheading Synopsis 33497 33498@smallexample 33499 -var-assign @var{name} @var{expression} 33500@end smallexample 33501 33502Assigns the value of @var{expression} to the variable object specified 33503by @var{name}. The object must be @samp{editable}. If the variable's 33504value is altered by the assign, the variable will show up in any 33505subsequent @code{-var-update} list. 33506 33507@subsubheading Example 33508 33509@smallexample 33510(gdb) 33511-var-assign var1 3 33512^done,value="3" 33513(gdb) 33514-var-update * 33515^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}] 33516(gdb) 33517@end smallexample 33518 33519@subheading The @code{-var-update} Command 33520@findex -var-update 33521 33522@subsubheading Synopsis 33523 33524@smallexample 33525 -var-update [@var{print-values}] @{@var{name} | "*"@} 33526@end smallexample 33527 33528Reevaluate the expressions corresponding to the variable object 33529@var{name} and all its direct and indirect children, and return the 33530list of variable objects whose values have changed; @var{name} must 33531be a root variable object. Here, ``changed'' means that the result of 33532@code{-var-evaluate-expression} before and after the 33533@code{-var-update} is different. If @samp{*} is used as the variable 33534object names, all existing variable objects are updated, except 33535for frozen ones (@pxref{-var-set-frozen}). The option 33536@var{print-values} determines whether both names and values, or just 33537names are printed. The possible values of this option are the same 33538as for @code{-var-list-children} (@pxref{-var-list-children}). It is 33539recommended to use the @samp{--all-values} option, to reduce the 33540number of MI commands needed on each program stop. 33541 33542With the @samp{*} parameter, if a variable object is bound to a 33543currently running thread, it will not be updated, without any 33544diagnostic. 33545 33546If @code{-var-set-update-range} was previously used on a varobj, then 33547only the selected range of children will be reported. 33548 33549@code{-var-update} reports all the changed varobjs in a tuple named 33550@samp{changelist}. 33551 33552Each item in the change list is itself a tuple holding: 33553 33554@table @samp 33555@item name 33556The name of the varobj. 33557 33558@item value 33559If values were requested for this update, then this field will be 33560present and will hold the value of the varobj. 33561 33562@item in_scope 33563@anchor{-var-update} 33564This field is a string which may take one of three values: 33565 33566@table @code 33567@item "true" 33568The variable object's current value is valid. 33569 33570@item "false" 33571The variable object does not currently hold a valid value but it may 33572hold one in the future if its associated expression comes back into 33573scope. 33574 33575@item "invalid" 33576The variable object no longer holds a valid value. 33577This can occur when the executable file being debugged has changed, 33578either through recompilation or by using the @value{GDBN} @code{file} 33579command. The front end should normally choose to delete these variable 33580objects. 33581@end table 33582 33583In the future new values may be added to this list so the front should 33584be prepared for this possibility. @xref{GDB/MI Development and Front Ends, ,@sc{GDB/MI} Development and Front Ends}. 33585 33586@item type_changed 33587This is only present if the varobj is still valid. If the type 33588changed, then this will be the string @samp{true}; otherwise it will 33589be @samp{false}. 33590 33591When a varobj's type changes, its children are also likely to have 33592become incorrect. Therefore, the varobj's children are automatically 33593deleted when this attribute is @samp{true}. Also, the varobj's update 33594range, when set using the @code{-var-set-update-range} command, is 33595unset. 33596 33597@item new_type 33598If the varobj's type changed, then this field will be present and will 33599hold the new type. 33600 33601@item new_num_children 33602For a dynamic varobj, if the number of children changed, or if the 33603type changed, this will be the new number of children. 33604 33605The @samp{numchild} field in other varobj responses is generally not 33606valid for a dynamic varobj -- it will show the number of children that 33607@value{GDBN} knows about, but because dynamic varobjs lazily 33608instantiate their children, this will not reflect the number of 33609children which may be available. 33610 33611The @samp{new_num_children} attribute only reports changes to the 33612number of children known by @value{GDBN}. This is the only way to 33613detect whether an update has removed children (which necessarily can 33614only happen at the end of the update range). 33615 33616@item displayhint 33617The display hint, if any. 33618 33619@item has_more 33620This is an integer value, which will be 1 if there are more children 33621available outside the varobj's update range. 33622 33623@item dynamic 33624This attribute will be present and have the value @samp{1} if the 33625varobj is a dynamic varobj. If the varobj is not a dynamic varobj, 33626then this attribute will not be present. 33627 33628@item new_children 33629If new children were added to a dynamic varobj within the selected 33630update range (as set by @code{-var-set-update-range}), then they will 33631be listed in this attribute. 33632@end table 33633 33634@subsubheading Example 33635 33636@smallexample 33637(gdb) 33638-var-assign var1 3 33639^done,value="3" 33640(gdb) 33641-var-update --all-values var1 33642^done,changelist=[@{name="var1",value="3",in_scope="true", 33643type_changed="false"@}] 33644(gdb) 33645@end smallexample 33646 33647@subheading The @code{-var-set-frozen} Command 33648@findex -var-set-frozen 33649@anchor{-var-set-frozen} 33650 33651@subsubheading Synopsis 33652 33653@smallexample 33654 -var-set-frozen @var{name} @var{flag} 33655@end smallexample 33656 33657Set the frozenness flag on the variable object @var{name}. The 33658@var{flag} parameter should be either @samp{1} to make the variable 33659frozen or @samp{0} to make it unfrozen. If a variable object is 33660frozen, then neither itself, nor any of its children, are 33661implicitly updated by @code{-var-update} of 33662a parent variable or by @code{-var-update *}. Only 33663@code{-var-update} of the variable itself will update its value and 33664values of its children. After a variable object is unfrozen, it is 33665implicitly updated by all subsequent @code{-var-update} operations. 33666Unfreezing a variable does not update it, only subsequent 33667@code{-var-update} does. 33668 33669@subsubheading Example 33670 33671@smallexample 33672(gdb) 33673-var-set-frozen V 1 33674^done 33675(gdb) 33676@end smallexample 33677 33678@subheading The @code{-var-set-update-range} command 33679@findex -var-set-update-range 33680@anchor{-var-set-update-range} 33681 33682@subsubheading Synopsis 33683 33684@smallexample 33685 -var-set-update-range @var{name} @var{from} @var{to} 33686@end smallexample 33687 33688Set the range of children to be returned by future invocations of 33689@code{-var-update}. 33690 33691@var{from} and @var{to} indicate the range of children to report. If 33692@var{from} or @var{to} is less than zero, the range is reset and all 33693children will be reported. Otherwise, children starting at @var{from} 33694(zero-based) and up to and excluding @var{to} will be reported. 33695 33696@subsubheading Example 33697 33698@smallexample 33699(gdb) 33700-var-set-update-range V 1 2 33701^done 33702@end smallexample 33703 33704@subheading The @code{-var-set-visualizer} command 33705@findex -var-set-visualizer 33706@anchor{-var-set-visualizer} 33707 33708@subsubheading Synopsis 33709 33710@smallexample 33711 -var-set-visualizer @var{name} @var{visualizer} 33712@end smallexample 33713 33714Set a visualizer for the variable object @var{name}. 33715 33716@var{visualizer} is the visualizer to use. The special value 33717@samp{None} means to disable any visualizer in use. 33718 33719If not @samp{None}, @var{visualizer} must be a Python expression. 33720This expression must evaluate to a callable object which accepts a 33721single argument. @value{GDBN} will call this object with the value of 33722the varobj @var{name} as an argument (this is done so that the same 33723Python pretty-printing code can be used for both the CLI and MI). 33724When called, this object must return an object which conforms to the 33725pretty-printing interface (@pxref{Pretty Printing API}). 33726 33727The pre-defined function @code{gdb.default_visualizer} may be used to 33728select a visualizer by following the built-in process 33729(@pxref{Selecting Pretty-Printers}). This is done automatically when 33730a varobj is created, and so ordinarily is not needed. 33731 33732This feature is only available if Python support is enabled. The MI 33733command @code{-list-features} (@pxref{GDB/MI Support Commands}) 33734can be used to check this. 33735 33736@subsubheading Example 33737 33738Resetting the visualizer: 33739 33740@smallexample 33741(gdb) 33742-var-set-visualizer V None 33743^done 33744@end smallexample 33745 33746Reselecting the default (type-based) visualizer: 33747 33748@smallexample 33749(gdb) 33750-var-set-visualizer V gdb.default_visualizer 33751^done 33752@end smallexample 33753 33754Suppose @code{SomeClass} is a visualizer class. A lambda expression 33755can be used to instantiate this class for a varobj: 33756 33757@smallexample 33758(gdb) 33759-var-set-visualizer V "lambda val: SomeClass()" 33760^done 33761@end smallexample 33762 33763@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 33764@node GDB/MI Data Manipulation 33765@section @sc{gdb/mi} Data Manipulation 33766 33767@cindex data manipulation, in @sc{gdb/mi} 33768@cindex @sc{gdb/mi}, data manipulation 33769This section describes the @sc{gdb/mi} commands that manipulate data: 33770examine memory and registers, evaluate expressions, etc. 33771 33772For details about what an addressable memory unit is, 33773@pxref{addressable memory unit}. 33774 33775@c REMOVED FROM THE INTERFACE. 33776@c @subheading -data-assign 33777@c Change the value of a program variable. Plenty of side effects. 33778@c @subsubheading GDB Command 33779@c set variable 33780@c @subsubheading Example 33781@c N.A. 33782 33783@subheading The @code{-data-disassemble} Command 33784@findex -data-disassemble 33785 33786@subsubheading Synopsis 33787 33788@smallexample 33789 -data-disassemble 33790 [ -s @var{start-addr} -e @var{end-addr} ] 33791 | [ -a @var{addr} ] 33792 | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ] 33793 -- @var{mode} 33794@end smallexample 33795 33796@noindent 33797Where: 33798 33799@table @samp 33800@item @var{start-addr} 33801is the beginning address (or @code{$pc}) 33802@item @var{end-addr} 33803is the end address 33804@item @var{addr} 33805is an address anywhere within (or the name of) the function to 33806disassemble. If an address is specified, the whole function 33807surrounding that address will be disassembled. If a name is 33808specified, the whole function with that name will be disassembled. 33809@item @var{filename} 33810is the name of the file to disassemble 33811@item @var{linenum} 33812is the line number to disassemble around 33813@item @var{lines} 33814is the number of disassembly lines to be produced. If it is -1, 33815the whole function will be disassembled, in case no @var{end-addr} is 33816specified. If @var{end-addr} is specified as a non-zero value, and 33817@var{lines} is lower than the number of disassembly lines between 33818@var{start-addr} and @var{end-addr}, only @var{lines} lines are 33819displayed; if @var{lines} is higher than the number of lines between 33820@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr} 33821are displayed. 33822@item @var{mode} 33823is one of: 33824@itemize @bullet 33825@item 0 disassembly only 33826@item 1 mixed source and disassembly (deprecated) 33827@item 2 disassembly with raw opcodes 33828@item 3 mixed source and disassembly with raw opcodes (deprecated) 33829@item 4 mixed source and disassembly 33830@item 5 mixed source and disassembly with raw opcodes 33831@end itemize 33832 33833Modes 1 and 3 are deprecated. The output is ``source centric'' 33834which hasn't proved useful in practice. 33835@xref{Machine Code}, for a discussion of the difference between 33836@code{/m} and @code{/s} output of the @code{disassemble} command. 33837@end table 33838 33839@subsubheading Result 33840 33841The result of the @code{-data-disassemble} command will be a list named 33842@samp{asm_insns}, the contents of this list depend on the @var{mode} 33843used with the @code{-data-disassemble} command. 33844 33845For modes 0 and 2 the @samp{asm_insns} list contains tuples with the 33846following fields: 33847 33848@table @code 33849@item address 33850The address at which this instruction was disassembled. 33851 33852@item func-name 33853The name of the function this instruction is within. 33854 33855@item offset 33856The decimal offset in bytes from the start of @samp{func-name}. 33857 33858@item inst 33859The text disassembly for this @samp{address}. 33860 33861@item opcodes 33862This field is only present for modes 2, 3 and 5. This contains the raw opcode 33863bytes for the @samp{inst} field. 33864 33865@end table 33866 33867For modes 1, 3, 4 and 5 the @samp{asm_insns} list contains tuples named 33868@samp{src_and_asm_line}, each of which has the following fields: 33869 33870@table @code 33871@item line 33872The line number within @samp{file}. 33873 33874@item file 33875The file name from the compilation unit. This might be an absolute 33876file name or a relative file name depending on the compile command 33877used. 33878 33879@item fullname 33880Absolute file name of @samp{file}. It is converted to a canonical form 33881using the source file search path 33882(@pxref{Source Path, ,Specifying Source Directories}) 33883and after resolving all the symbolic links. 33884 33885If the source file is not found this field will contain the path as 33886present in the debug information. 33887 33888@item line_asm_insn 33889This is a list of tuples containing the disassembly for @samp{line} in 33890@samp{file}. The fields of each tuple are the same as for 33891@code{-data-disassemble} in @var{mode} 0 and 2, so @samp{address}, 33892@samp{func-name}, @samp{offset}, @samp{inst}, and optionally 33893@samp{opcodes}. 33894 33895@end table 33896 33897Note that whatever included in the @samp{inst} field, is not 33898manipulated directly by @sc{gdb/mi}, i.e., it is not possible to 33899adjust its format. 33900 33901@subsubheading @value{GDBN} Command 33902 33903The corresponding @value{GDBN} command is @samp{disassemble}. 33904 33905@subsubheading Example 33906 33907Disassemble from the current value of @code{$pc} to @code{$pc + 20}: 33908 33909@smallexample 33910(gdb) 33911-data-disassemble -s $pc -e "$pc + 20" -- 0 33912^done, 33913asm_insns=[ 33914@{address="0x000107c0",func-name="main",offset="4", 33915inst="mov 2, %o0"@}, 33916@{address="0x000107c4",func-name="main",offset="8", 33917inst="sethi %hi(0x11800), %o2"@}, 33918@{address="0x000107c8",func-name="main",offset="12", 33919inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@}, 33920@{address="0x000107cc",func-name="main",offset="16", 33921inst="sethi %hi(0x11800), %o2"@}, 33922@{address="0x000107d0",func-name="main",offset="20", 33923inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}] 33924(gdb) 33925@end smallexample 33926 33927Disassemble the whole @code{main} function. Line 32 is part of 33928@code{main}. 33929 33930@smallexample 33931-data-disassemble -f basics.c -l 32 -- 0 33932^done,asm_insns=[ 33933@{address="0x000107bc",func-name="main",offset="0", 33934inst="save %sp, -112, %sp"@}, 33935@{address="0x000107c0",func-name="main",offset="4", 33936inst="mov 2, %o0"@}, 33937@{address="0x000107c4",func-name="main",offset="8", 33938inst="sethi %hi(0x11800), %o2"@}, 33939[@dots{}] 33940@{address="0x0001081c",func-name="main",offset="96",inst="ret "@}, 33941@{address="0x00010820",func-name="main",offset="100",inst="restore "@}] 33942(gdb) 33943@end smallexample 33944 33945Disassemble 3 instructions from the start of @code{main}: 33946 33947@smallexample 33948(gdb) 33949-data-disassemble -f basics.c -l 32 -n 3 -- 0 33950^done,asm_insns=[ 33951@{address="0x000107bc",func-name="main",offset="0", 33952inst="save %sp, -112, %sp"@}, 33953@{address="0x000107c0",func-name="main",offset="4", 33954inst="mov 2, %o0"@}, 33955@{address="0x000107c4",func-name="main",offset="8", 33956inst="sethi %hi(0x11800), %o2"@}] 33957(gdb) 33958@end smallexample 33959 33960Disassemble 3 instructions from the start of @code{main} in mixed mode: 33961 33962@smallexample 33963(gdb) 33964-data-disassemble -f basics.c -l 32 -n 3 -- 1 33965^done,asm_insns=[ 33966src_and_asm_line=@{line="31", 33967file="../../../src/gdb/testsuite/gdb.mi/basics.c", 33968fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c", 33969line_asm_insn=[@{address="0x000107bc", 33970func-name="main",offset="0",inst="save %sp, -112, %sp"@}]@}, 33971src_and_asm_line=@{line="32", 33972file="../../../src/gdb/testsuite/gdb.mi/basics.c", 33973fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c", 33974line_asm_insn=[@{address="0x000107c0", 33975func-name="main",offset="4",inst="mov 2, %o0"@}, 33976@{address="0x000107c4",func-name="main",offset="8", 33977inst="sethi %hi(0x11800), %o2"@}]@}] 33978(gdb) 33979@end smallexample 33980 33981 33982@subheading The @code{-data-evaluate-expression} Command 33983@findex -data-evaluate-expression 33984 33985@subsubheading Synopsis 33986 33987@smallexample 33988 -data-evaluate-expression @var{expr} 33989@end smallexample 33990 33991Evaluate @var{expr} as an expression. The expression could contain an 33992inferior function call. The function call will execute synchronously. 33993If the expression contains spaces, it must be enclosed in double quotes. 33994 33995@subsubheading @value{GDBN} Command 33996 33997The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and 33998@samp{call}. In @code{gdbtk} only, there's a corresponding 33999@samp{gdb_eval} command. 34000 34001@subsubheading Example 34002 34003In the following example, the numbers that precede the commands are the 34004@dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi} 34005Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its 34006output. 34007 34008@smallexample 34009211-data-evaluate-expression A 34010211^done,value="1" 34011(gdb) 34012311-data-evaluate-expression &A 34013311^done,value="0xefffeb7c" 34014(gdb) 34015411-data-evaluate-expression A+3 34016411^done,value="4" 34017(gdb) 34018511-data-evaluate-expression "A + 3" 34019511^done,value="4" 34020(gdb) 34021@end smallexample 34022 34023 34024@subheading The @code{-data-list-changed-registers} Command 34025@findex -data-list-changed-registers 34026 34027@subsubheading Synopsis 34028 34029@smallexample 34030 -data-list-changed-registers 34031@end smallexample 34032 34033Display a list of the registers that have changed. 34034 34035@subsubheading @value{GDBN} Command 34036 34037@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk} 34038has the corresponding command @samp{gdb_changed_register_list}. 34039 34040@subsubheading Example 34041 34042On a PPC MBX board: 34043 34044@smallexample 34045(gdb) 34046-exec-continue 34047^running 34048 34049(gdb) 34050*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame=@{ 34051func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c", 34052line="5",arch="powerpc"@} 34053(gdb) 34054-data-list-changed-registers 34055^done,changed-registers=["0","1","2","4","5","6","7","8","9", 34056"10","11","13","14","15","16","17","18","19","20","21","22","23", 34057"24","25","26","27","28","30","31","64","65","66","67","69"] 34058(gdb) 34059@end smallexample 34060 34061 34062@subheading The @code{-data-list-register-names} Command 34063@findex -data-list-register-names 34064 34065@subsubheading Synopsis 34066 34067@smallexample 34068 -data-list-register-names [ ( @var{regno} )+ ] 34069@end smallexample 34070 34071Show a list of register names for the current target. If no arguments 34072are given, it shows a list of the names of all the registers. If 34073integer numbers are given as arguments, it will print a list of the 34074names of the registers corresponding to the arguments. To ensure 34075consistency between a register name and its number, the output list may 34076include empty register names. 34077 34078@subsubheading @value{GDBN} Command 34079 34080@value{GDBN} does not have a command which corresponds to 34081@samp{-data-list-register-names}. In @code{gdbtk} there is a 34082corresponding command @samp{gdb_regnames}. 34083 34084@subsubheading Example 34085 34086For the PPC MBX board: 34087@smallexample 34088(gdb) 34089-data-list-register-names 34090^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", 34091"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", 34092"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", 34093"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", 34094"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", 34095"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", 34096"", "pc","ps","cr","lr","ctr","xer"] 34097(gdb) 34098-data-list-register-names 1 2 3 34099^done,register-names=["r1","r2","r3"] 34100(gdb) 34101@end smallexample 34102 34103@subheading The @code{-data-list-register-values} Command 34104@findex -data-list-register-values 34105 34106@subsubheading Synopsis 34107 34108@smallexample 34109 -data-list-register-values 34110 [ @code{--skip-unavailable} ] @var{fmt} [ ( @var{regno} )*] 34111@end smallexample 34112 34113Display the registers' contents. The format according to which the 34114registers' contents are to be returned is given by @var{fmt}, followed 34115by an optional list of numbers specifying the registers to display. A 34116missing list of numbers indicates that the contents of all the 34117registers must be returned. The @code{--skip-unavailable} option 34118indicates that only the available registers are to be returned. 34119 34120Allowed formats for @var{fmt} are: 34121 34122@table @code 34123@item x 34124Hexadecimal 34125@item o 34126Octal 34127@item t 34128Binary 34129@item d 34130Decimal 34131@item r 34132Raw 34133@item N 34134Natural 34135@end table 34136 34137@subsubheading @value{GDBN} Command 34138 34139The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info 34140all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}. 34141 34142@subsubheading Example 34143 34144For a PPC MBX board (note: line breaks are for readability only, they 34145don't appear in the actual output): 34146 34147@smallexample 34148(gdb) 34149-data-list-register-values r 64 65 34150^done,register-values=[@{number="64",value="0xfe00a300"@}, 34151@{number="65",value="0x00029002"@}] 34152(gdb) 34153-data-list-register-values x 34154^done,register-values=[@{number="0",value="0xfe0043c8"@}, 34155@{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@}, 34156@{number="3",value="0x0"@},@{number="4",value="0xa"@}, 34157@{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@}, 34158@{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@}, 34159@{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@}, 34160@{number="11",value="0x1"@},@{number="12",value="0x0"@}, 34161@{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@}, 34162@{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@}, 34163@{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@}, 34164@{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@}, 34165@{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@}, 34166@{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@}, 34167@{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@}, 34168@{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@}, 34169@{number="29",value="0x0"@},@{number="30",value="0xfe010000"@}, 34170@{number="31",value="0x0"@},@{number="32",value="0x0"@}, 34171@{number="33",value="0x0"@},@{number="34",value="0x0"@}, 34172@{number="35",value="0x0"@},@{number="36",value="0x0"@}, 34173@{number="37",value="0x0"@},@{number="38",value="0x0"@}, 34174@{number="39",value="0x0"@},@{number="40",value="0x0"@}, 34175@{number="41",value="0x0"@},@{number="42",value="0x0"@}, 34176@{number="43",value="0x0"@},@{number="44",value="0x0"@}, 34177@{number="45",value="0x0"@},@{number="46",value="0x0"@}, 34178@{number="47",value="0x0"@},@{number="48",value="0x0"@}, 34179@{number="49",value="0x0"@},@{number="50",value="0x0"@}, 34180@{number="51",value="0x0"@},@{number="52",value="0x0"@}, 34181@{number="53",value="0x0"@},@{number="54",value="0x0"@}, 34182@{number="55",value="0x0"@},@{number="56",value="0x0"@}, 34183@{number="57",value="0x0"@},@{number="58",value="0x0"@}, 34184@{number="59",value="0x0"@},@{number="60",value="0x0"@}, 34185@{number="61",value="0x0"@},@{number="62",value="0x0"@}, 34186@{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@}, 34187@{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@}, 34188@{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@}, 34189@{number="69",value="0x20002b03"@}] 34190(gdb) 34191@end smallexample 34192 34193 34194@subheading The @code{-data-read-memory} Command 34195@findex -data-read-memory 34196 34197This command is deprecated, use @code{-data-read-memory-bytes} instead. 34198 34199@subsubheading Synopsis 34200 34201@smallexample 34202 -data-read-memory [ -o @var{byte-offset} ] 34203 @var{address} @var{word-format} @var{word-size} 34204 @var{nr-rows} @var{nr-cols} [ @var{aschar} ] 34205@end smallexample 34206 34207@noindent 34208where: 34209 34210@table @samp 34211@item @var{address} 34212An expression specifying the address of the first memory word to be 34213read. Complex expressions containing embedded white space should be 34214quoted using the C convention. 34215 34216@item @var{word-format} 34217The format to be used to print the memory words. The notation is the 34218same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats, 34219,Output Formats}). 34220 34221@item @var{word-size} 34222The size of each memory word in bytes. 34223 34224@item @var{nr-rows} 34225The number of rows in the output table. 34226 34227@item @var{nr-cols} 34228The number of columns in the output table. 34229 34230@item @var{aschar} 34231If present, indicates that each row should include an @sc{ascii} dump. The 34232value of @var{aschar} is used as a padding character when a byte is not a 34233member of the printable @sc{ascii} character set (printable @sc{ascii} 34234characters are those whose code is between 32 and 126, inclusively). 34235 34236@item @var{byte-offset} 34237An offset to add to the @var{address} before fetching memory. 34238@end table 34239 34240This command displays memory contents as a table of @var{nr-rows} by 34241@var{nr-cols} words, each word being @var{word-size} bytes. In total, 34242@code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read 34243(returned as @samp{total-bytes}). Should less than the requested number 34244of bytes be returned by the target, the missing words are identified 34245using @samp{N/A}. The number of bytes read from the target is returned 34246in @samp{nr-bytes} and the starting address used to read memory in 34247@samp{addr}. 34248 34249The address of the next/previous row or page is available in 34250@samp{next-row} and @samp{prev-row}, @samp{next-page} and 34251@samp{prev-page}. 34252 34253@subsubheading @value{GDBN} Command 34254 34255The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has 34256@samp{gdb_get_mem} memory read command. 34257 34258@subsubheading Example 34259 34260Read six bytes of memory starting at @code{bytes+6} but then offset by 34261@code{-6} bytes. Format as three rows of two columns. One byte per 34262word. Display each word in hex. 34263 34264@smallexample 34265(gdb) 342669-data-read-memory -o -6 -- bytes+6 x 1 3 2 342679^done,addr="0x00001390",nr-bytes="6",total-bytes="6", 34268next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", 34269prev-page="0x0000138a",memory=[ 34270@{addr="0x00001390",data=["0x00","0x01"]@}, 34271@{addr="0x00001392",data=["0x02","0x03"]@}, 34272@{addr="0x00001394",data=["0x04","0x05"]@}] 34273(gdb) 34274@end smallexample 34275 34276Read two bytes of memory starting at address @code{shorts + 64} and 34277display as a single word formatted in decimal. 34278 34279@smallexample 34280(gdb) 342815-data-read-memory shorts+64 d 2 1 1 342825^done,addr="0x00001510",nr-bytes="2",total-bytes="2", 34283next-row="0x00001512",prev-row="0x0000150e", 34284next-page="0x00001512",prev-page="0x0000150e",memory=[ 34285@{addr="0x00001510",data=["128"]@}] 34286(gdb) 34287@end smallexample 34288 34289Read thirty two bytes of memory starting at @code{bytes+16} and format 34290as eight rows of four columns. Include a string encoding with @samp{x} 34291used as the non-printable character. 34292 34293@smallexample 34294(gdb) 342954-data-read-memory bytes+16 x 1 8 4 x 342964^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", 34297next-row="0x000013c0",prev-row="0x0000139c", 34298next-page="0x000013c0",prev-page="0x00001380",memory=[ 34299@{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@}, 34300@{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@}, 34301@{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@}, 34302@{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@}, 34303@{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@}, 34304@{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@}, 34305@{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@}, 34306@{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}] 34307(gdb) 34308@end smallexample 34309 34310@subheading The @code{-data-read-memory-bytes} Command 34311@findex -data-read-memory-bytes 34312 34313@subsubheading Synopsis 34314 34315@smallexample 34316 -data-read-memory-bytes [ -o @var{offset} ] 34317 @var{address} @var{count} 34318@end smallexample 34319 34320@noindent 34321where: 34322 34323@table @samp 34324@item @var{address} 34325An expression specifying the address of the first addressable memory unit 34326to be read. Complex expressions containing embedded white space should be 34327quoted using the C convention. 34328 34329@item @var{count} 34330The number of addressable memory units to read. This should be an integer 34331literal. 34332 34333@item @var{offset} 34334The offset relative to @var{address} at which to start reading. This 34335should be an integer literal. This option is provided so that a frontend 34336is not required to first evaluate address and then perform address 34337arithmetics itself. 34338 34339@end table 34340 34341This command attempts to read all accessible memory regions in the 34342specified range. First, all regions marked as unreadable in the memory 34343map (if one is defined) will be skipped. @xref{Memory Region 34344Attributes}. Second, @value{GDBN} will attempt to read the remaining 34345regions. For each one, if reading full region results in an errors, 34346@value{GDBN} will try to read a subset of the region. 34347 34348In general, every single memory unit in the region may be readable or not, 34349and the only way to read every readable unit is to try a read at 34350every address, which is not practical. Therefore, @value{GDBN} will 34351attempt to read all accessible memory units at either beginning or the end 34352of the region, using a binary division scheme. This heuristic works 34353well for reading across a memory map boundary. Note that if a region 34354has a readable range that is neither at the beginning or the end, 34355@value{GDBN} will not read it. 34356 34357The result record (@pxref{GDB/MI Result Records}) that is output of 34358the command includes a field named @samp{memory} whose content is a 34359list of tuples. Each tuple represent a successfully read memory block 34360and has the following fields: 34361 34362@table @code 34363@item begin 34364The start address of the memory block, as hexadecimal literal. 34365 34366@item end 34367The end address of the memory block, as hexadecimal literal. 34368 34369@item offset 34370The offset of the memory block, as hexadecimal literal, relative to 34371the start address passed to @code{-data-read-memory-bytes}. 34372 34373@item contents 34374The contents of the memory block, in hex. 34375 34376@end table 34377 34378 34379 34380@subsubheading @value{GDBN} Command 34381 34382The corresponding @value{GDBN} command is @samp{x}. 34383 34384@subsubheading Example 34385 34386@smallexample 34387(gdb) 34388-data-read-memory-bytes &a 10 34389^done,memory=[@{begin="0xbffff154",offset="0x00000000", 34390 end="0xbffff15e", 34391 contents="01000000020000000300"@}] 34392(gdb) 34393@end smallexample 34394 34395 34396@subheading The @code{-data-write-memory-bytes} Command 34397@findex -data-write-memory-bytes 34398 34399@subsubheading Synopsis 34400 34401@smallexample 34402 -data-write-memory-bytes @var{address} @var{contents} 34403 -data-write-memory-bytes @var{address} @var{contents} @r{[}@var{count}@r{]} 34404@end smallexample 34405 34406@noindent 34407where: 34408 34409@table @samp 34410@item @var{address} 34411An expression specifying the address of the first addressable memory unit 34412to be written. Complex expressions containing embedded white space should 34413be quoted using the C convention. 34414 34415@item @var{contents} 34416The hex-encoded data to write. It is an error if @var{contents} does 34417not represent an integral number of addressable memory units. 34418 34419@item @var{count} 34420Optional argument indicating the number of addressable memory units to be 34421written. If @var{count} is greater than @var{contents}' length, 34422@value{GDBN} will repeatedly write @var{contents} until it fills 34423@var{count} memory units. 34424 34425@end table 34426 34427@subsubheading @value{GDBN} Command 34428 34429There's no corresponding @value{GDBN} command. 34430 34431@subsubheading Example 34432 34433@smallexample 34434(gdb) 34435-data-write-memory-bytes &a "aabbccdd" 34436^done 34437(gdb) 34438@end smallexample 34439 34440@smallexample 34441(gdb) 34442-data-write-memory-bytes &a "aabbccdd" 16e 34443^done 34444(gdb) 34445@end smallexample 34446 34447@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 34448@node GDB/MI Tracepoint Commands 34449@section @sc{gdb/mi} Tracepoint Commands 34450 34451The commands defined in this section implement MI support for 34452tracepoints. For detailed introduction, see @ref{Tracepoints}. 34453 34454@subheading The @code{-trace-find} Command 34455@findex -trace-find 34456 34457@subsubheading Synopsis 34458 34459@smallexample 34460 -trace-find @var{mode} [@var{parameters}@dots{}] 34461@end smallexample 34462 34463Find a trace frame using criteria defined by @var{mode} and 34464@var{parameters}. The following table lists permissible 34465modes and their parameters. For details of operation, see @ref{tfind}. 34466 34467@table @samp 34468 34469@item none 34470No parameters are required. Stops examining trace frames. 34471 34472@item frame-number 34473An integer is required as parameter. Selects tracepoint frame with 34474that index. 34475 34476@item tracepoint-number 34477An integer is required as parameter. Finds next 34478trace frame that corresponds to tracepoint with the specified number. 34479 34480@item pc 34481An address is required as parameter. Finds 34482next trace frame that corresponds to any tracepoint at the specified 34483address. 34484 34485@item pc-inside-range 34486Two addresses are required as parameters. Finds next trace 34487frame that corresponds to a tracepoint at an address inside the 34488specified range. Both bounds are considered to be inside the range. 34489 34490@item pc-outside-range 34491Two addresses are required as parameters. Finds 34492next trace frame that corresponds to a tracepoint at an address outside 34493the specified range. Both bounds are considered to be inside the range. 34494 34495@item line 34496Line specification is required as parameter. @xref{Specify Location}. 34497Finds next trace frame that corresponds to a tracepoint at 34498the specified location. 34499 34500@end table 34501 34502If @samp{none} was passed as @var{mode}, the response does not 34503have fields. Otherwise, the response may have the following fields: 34504 34505@table @samp 34506@item found 34507This field has either @samp{0} or @samp{1} as the value, depending 34508on whether a matching tracepoint was found. 34509 34510@item traceframe 34511The index of the found traceframe. This field is present iff 34512the @samp{found} field has value of @samp{1}. 34513 34514@item tracepoint 34515The index of the found tracepoint. This field is present iff 34516the @samp{found} field has value of @samp{1}. 34517 34518@item frame 34519The information about the frame corresponding to the found trace 34520frame. This field is present only if a trace frame was found. 34521@xref{GDB/MI Frame Information}, for description of this field. 34522 34523@end table 34524 34525@subsubheading @value{GDBN} Command 34526 34527The corresponding @value{GDBN} command is @samp{tfind}. 34528 34529@subheading -trace-define-variable 34530@findex -trace-define-variable 34531 34532@subsubheading Synopsis 34533 34534@smallexample 34535 -trace-define-variable @var{name} [ @var{value} ] 34536@end smallexample 34537 34538Create trace variable @var{name} if it does not exist. If 34539@var{value} is specified, sets the initial value of the specified 34540trace variable to that value. Note that the @var{name} should start 34541with the @samp{$} character. 34542 34543@subsubheading @value{GDBN} Command 34544 34545The corresponding @value{GDBN} command is @samp{tvariable}. 34546 34547@subheading The @code{-trace-frame-collected} Command 34548@findex -trace-frame-collected 34549 34550@subsubheading Synopsis 34551 34552@smallexample 34553 -trace-frame-collected 34554 [--var-print-values @var{var_pval}] 34555 [--comp-print-values @var{comp_pval}] 34556 [--registers-format @var{regformat}] 34557 [--memory-contents] 34558@end smallexample 34559 34560This command returns the set of collected objects, register names, 34561trace state variable names, memory ranges and computed expressions 34562that have been collected at a particular trace frame. The optional 34563parameters to the command affect the output format in different ways. 34564See the output description table below for more details. 34565 34566The reported names can be used in the normal manner to create 34567varobjs and inspect the objects themselves. The items returned by 34568this command are categorized so that it is clear which is a variable, 34569which is a register, which is a trace state variable, which is a 34570memory range and which is a computed expression. 34571 34572For instance, if the actions were 34573@smallexample 34574collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2 34575collect *(int*)0xaf02bef0@@40 34576@end smallexample 34577 34578@noindent 34579the object collected in its entirety would be @code{myVar}. The 34580object @code{myArray} would be partially collected, because only the 34581element at index @code{myIndex} would be collected. The remaining 34582objects would be computed expressions. 34583 34584An example output would be: 34585 34586@smallexample 34587(gdb) 34588-trace-frame-collected 34589^done, 34590 explicit-variables=[@{name="myVar",value="1"@}], 34591 computed-expressions=[@{name="myArray[myIndex]",value="0"@}, 34592 @{name="myObj.field",value="0"@}, 34593 @{name="myPtr->field",value="1"@}, 34594 @{name="myCount + 2",value="3"@}, 34595 @{name="$tvar1 + 1",value="43970027"@}], 34596 registers=[@{number="0",value="0x7fe2c6e79ec8"@}, 34597 @{number="1",value="0x0"@}, 34598 @{number="2",value="0x4"@}, 34599 ... 34600 @{number="125",value="0x0"@}], 34601 tvars=[@{name="$tvar1",current="43970026"@}], 34602 memory=[@{address="0x0000000000602264",length="4"@}, 34603 @{address="0x0000000000615bc0",length="4"@}] 34604(gdb) 34605@end smallexample 34606 34607Where: 34608 34609@table @code 34610@item explicit-variables 34611The set of objects that have been collected in their entirety (as 34612opposed to collecting just a few elements of an array or a few struct 34613members). For each object, its name and value are printed. 34614The @code{--var-print-values} option affects how or whether the value 34615field is output. If @var{var_pval} is 0, then print only the names; 34616if it is 1, print also their values; and if it is 2, print the name, 34617type and value for simple data types, and the name and type for 34618arrays, structures and unions. 34619 34620@item computed-expressions 34621The set of computed expressions that have been collected at the 34622current trace frame. The @code{--comp-print-values} option affects 34623this set like the @code{--var-print-values} option affects the 34624@code{explicit-variables} set. See above. 34625 34626@item registers 34627The registers that have been collected at the current trace frame. 34628For each register collected, the name and current value are returned. 34629The value is formatted according to the @code{--registers-format} 34630option. See the @command{-data-list-register-values} command for a 34631list of the allowed formats. The default is @samp{x}. 34632 34633@item tvars 34634The trace state variables that have been collected at the current 34635trace frame. For each trace state variable collected, the name and 34636current value are returned. 34637 34638@item memory 34639The set of memory ranges that have been collected at the current trace 34640frame. Its content is a list of tuples. Each tuple represents a 34641collected memory range and has the following fields: 34642 34643@table @code 34644@item address 34645The start address of the memory range, as hexadecimal literal. 34646 34647@item length 34648The length of the memory range, as decimal literal. 34649 34650@item contents 34651The contents of the memory block, in hex. This field is only present 34652if the @code{--memory-contents} option is specified. 34653 34654@end table 34655 34656@end table 34657 34658@subsubheading @value{GDBN} Command 34659 34660There is no corresponding @value{GDBN} command. 34661 34662@subsubheading Example 34663 34664@subheading -trace-list-variables 34665@findex -trace-list-variables 34666 34667@subsubheading Synopsis 34668 34669@smallexample 34670 -trace-list-variables 34671@end smallexample 34672 34673Return a table of all defined trace variables. Each element of the 34674table has the following fields: 34675 34676@table @samp 34677@item name 34678The name of the trace variable. This field is always present. 34679 34680@item initial 34681The initial value. This is a 64-bit signed integer. This 34682field is always present. 34683 34684@item current 34685The value the trace variable has at the moment. This is a 64-bit 34686signed integer. This field is absent iff current value is 34687not defined, for example if the trace was never run, or is 34688presently running. 34689 34690@end table 34691 34692@subsubheading @value{GDBN} Command 34693 34694The corresponding @value{GDBN} command is @samp{tvariables}. 34695 34696@subsubheading Example 34697 34698@smallexample 34699(gdb) 34700-trace-list-variables 34701^done,trace-variables=@{nr_rows="1",nr_cols="3", 34702hdr=[@{width="15",alignment="-1",col_name="name",colhdr="Name"@}, 34703 @{width="11",alignment="-1",col_name="initial",colhdr="Initial"@}, 34704 @{width="11",alignment="-1",col_name="current",colhdr="Current"@}], 34705body=[variable=@{name="$trace_timestamp",initial="0"@} 34706 variable=@{name="$foo",initial="10",current="15"@}]@} 34707(gdb) 34708@end smallexample 34709 34710@subheading -trace-save 34711@findex -trace-save 34712 34713@subsubheading Synopsis 34714 34715@smallexample 34716 -trace-save [ -r ] [ -ctf ] @var{filename} 34717@end smallexample 34718 34719Saves the collected trace data to @var{filename}. Without the 34720@samp{-r} option, the data is downloaded from the target and saved 34721in a local file. With the @samp{-r} option the target is asked 34722to perform the save. 34723 34724By default, this command will save the trace in the tfile format. You can 34725supply the optional @samp{-ctf} argument to save it the CTF format. See 34726@ref{Trace Files} for more information about CTF. 34727 34728@subsubheading @value{GDBN} Command 34729 34730The corresponding @value{GDBN} command is @samp{tsave}. 34731 34732 34733@subheading -trace-start 34734@findex -trace-start 34735 34736@subsubheading Synopsis 34737 34738@smallexample 34739 -trace-start 34740@end smallexample 34741 34742Starts a tracing experiment. The result of this command does not 34743have any fields. 34744 34745@subsubheading @value{GDBN} Command 34746 34747The corresponding @value{GDBN} command is @samp{tstart}. 34748 34749@subheading -trace-status 34750@findex -trace-status 34751 34752@subsubheading Synopsis 34753 34754@smallexample 34755 -trace-status 34756@end smallexample 34757 34758Obtains the status of a tracing experiment. The result may include 34759the following fields: 34760 34761@table @samp 34762 34763@item supported 34764May have a value of either @samp{0}, when no tracing operations are 34765supported, @samp{1}, when all tracing operations are supported, or 34766@samp{file} when examining trace file. In the latter case, examining 34767of trace frame is possible but new tracing experiement cannot be 34768started. This field is always present. 34769 34770@item running 34771May have a value of either @samp{0} or @samp{1} depending on whether 34772tracing experiement is in progress on target. This field is present 34773if @samp{supported} field is not @samp{0}. 34774 34775@item stop-reason 34776Report the reason why the tracing was stopped last time. This field 34777may be absent iff tracing was never stopped on target yet. The 34778value of @samp{request} means the tracing was stopped as result of 34779the @code{-trace-stop} command. The value of @samp{overflow} means 34780the tracing buffer is full. The value of @samp{disconnection} means 34781tracing was automatically stopped when @value{GDBN} has disconnected. 34782The value of @samp{passcount} means tracing was stopped when a 34783tracepoint was passed a maximal number of times for that tracepoint. 34784This field is present if @samp{supported} field is not @samp{0}. 34785 34786@item stopping-tracepoint 34787The number of tracepoint whose passcount as exceeded. This field is 34788present iff the @samp{stop-reason} field has the value of 34789@samp{passcount}. 34790 34791@item frames 34792@itemx frames-created 34793The @samp{frames} field is a count of the total number of trace frames 34794in the trace buffer, while @samp{frames-created} is the total created 34795during the run, including ones that were discarded, such as when a 34796circular trace buffer filled up. Both fields are optional. 34797 34798@item buffer-size 34799@itemx buffer-free 34800These fields tell the current size of the tracing buffer and the 34801remaining space. These fields are optional. 34802 34803@item circular 34804The value of the circular trace buffer flag. @code{1} means that the 34805trace buffer is circular and old trace frames will be discarded if 34806necessary to make room, @code{0} means that the trace buffer is linear 34807and may fill up. 34808 34809@item disconnected 34810The value of the disconnected tracing flag. @code{1} means that 34811tracing will continue after @value{GDBN} disconnects, @code{0} means 34812that the trace run will stop. 34813 34814@item trace-file 34815The filename of the trace file being examined. This field is 34816optional, and only present when examining a trace file. 34817 34818@end table 34819 34820@subsubheading @value{GDBN} Command 34821 34822The corresponding @value{GDBN} command is @samp{tstatus}. 34823 34824@subheading -trace-stop 34825@findex -trace-stop 34826 34827@subsubheading Synopsis 34828 34829@smallexample 34830 -trace-stop 34831@end smallexample 34832 34833Stops a tracing experiment. The result of this command has the same 34834fields as @code{-trace-status}, except that the @samp{supported} and 34835@samp{running} fields are not output. 34836 34837@subsubheading @value{GDBN} Command 34838 34839The corresponding @value{GDBN} command is @samp{tstop}. 34840 34841 34842@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 34843@node GDB/MI Symbol Query 34844@section @sc{gdb/mi} Symbol Query Commands 34845 34846 34847@ignore 34848@subheading The @code{-symbol-info-address} Command 34849@findex -symbol-info-address 34850 34851@subsubheading Synopsis 34852 34853@smallexample 34854 -symbol-info-address @var{symbol} 34855@end smallexample 34856 34857Describe where @var{symbol} is stored. 34858 34859@subsubheading @value{GDBN} Command 34860 34861The corresponding @value{GDBN} command is @samp{info address}. 34862 34863@subsubheading Example 34864N.A. 34865 34866 34867@subheading The @code{-symbol-info-file} Command 34868@findex -symbol-info-file 34869 34870@subsubheading Synopsis 34871 34872@smallexample 34873 -symbol-info-file 34874@end smallexample 34875 34876Show the file for the symbol. 34877 34878@subsubheading @value{GDBN} Command 34879 34880There's no equivalent @value{GDBN} command. @code{gdbtk} has 34881@samp{gdb_find_file}. 34882 34883@subsubheading Example 34884N.A. 34885@end ignore 34886 34887@subheading The @code{-symbol-info-functions} Command 34888@findex -symbol-info-functions 34889@anchor{-symbol-info-functions} 34890 34891@subsubheading Synopsis 34892 34893@smallexample 34894 -symbol-info-functions [--include-nondebug] 34895 [--type @var{type_regexp}] 34896 [--name @var{name_regexp}] 34897 [--max-results @var{limit}] 34898@end smallexample 34899 34900@noindent 34901Return a list containing the names and types for all global functions 34902taken from the debug information. The functions are grouped by source 34903file, and shown with the line number on which each function is 34904defined. 34905 34906The @code{--include-nondebug} option causes the output to include 34907code symbols from the symbol table. 34908 34909The options @code{--type} and @code{--name} allow the symbols returned 34910to be filtered based on either the name of the function, or the type 34911signature of the function. 34912 34913The option @code{--max-results} restricts the command to return no 34914more than @var{limit} results. If exactly @var{limit} results are 34915returned then there might be additional results available if a higher 34916limit is used. 34917 34918@subsubheading @value{GDBN} Command 34919 34920The corresponding @value{GDBN} command is @samp{info functions}. 34921 34922@subsubheading Example 34923@smallexample 34924@group 34925(gdb) 34926-symbol-info-functions 34927^done,symbols= 34928 @{debug= 34929 [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 34930 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 34931 symbols=[@{line="36", name="f4", type="void (int *)", 34932 description="void f4(int *);"@}, 34933 @{line="42", name="main", type="int ()", 34934 description="int main();"@}, 34935 @{line="30", name="f1", type="my_int_t (int, int)", 34936 description="static my_int_t f1(int, int);"@}]@}, 34937 @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 34938 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 34939 symbols=[@{line="33", name="f2", type="float (another_float_t)", 34940 description="float f2(another_float_t);"@}, 34941 @{line="39", name="f3", type="int (another_int_t)", 34942 description="int f3(another_int_t);"@}, 34943 @{line="27", name="f1", type="another_float_t (int)", 34944 description="static another_float_t f1(int);"@}]@}]@} 34945@end group 34946@group 34947(gdb) 34948-symbol-info-functions --name f1 34949^done,symbols= 34950 @{debug= 34951 [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 34952 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 34953 symbols=[@{line="30", name="f1", type="my_int_t (int, int)", 34954 description="static my_int_t f1(int, int);"@}]@}, 34955 @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 34956 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 34957 symbols=[@{line="27", name="f1", type="another_float_t (int)", 34958 description="static another_float_t f1(int);"@}]@}]@} 34959@end group 34960@group 34961(gdb) 34962-symbol-info-functions --type void 34963^done,symbols= 34964 @{debug= 34965 [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 34966 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 34967 symbols=[@{line="36", name="f4", type="void (int *)", 34968 description="void f4(int *);"@}]@}]@} 34969@end group 34970@group 34971(gdb) 34972-symbol-info-functions --include-nondebug 34973^done,symbols= 34974 @{debug= 34975 [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 34976 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 34977 symbols=[@{line="36", name="f4", type="void (int *)", 34978 description="void f4(int *);"@}, 34979 @{line="42", name="main", type="int ()", 34980 description="int main();"@}, 34981 @{line="30", name="f1", type="my_int_t (int, int)", 34982 description="static my_int_t f1(int, int);"@}]@}, 34983 @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 34984 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 34985 symbols=[@{line="33", name="f2", type="float (another_float_t)", 34986 description="float f2(another_float_t);"@}, 34987 @{line="39", name="f3", type="int (another_int_t)", 34988 description="int f3(another_int_t);"@}, 34989 @{line="27", name="f1", type="another_float_t (int)", 34990 description="static another_float_t f1(int);"@}]@}], 34991 nondebug= 34992 [@{address="0x0000000000400398",name="_init"@}, 34993 @{address="0x00000000004003b0",name="_start"@}, 34994 ... 34995 ]@} 34996@end group 34997@end smallexample 34998 34999@subheading The @code{-symbol-info-module-functions} Command 35000@findex -symbol-info-module-functions 35001@anchor{-symbol-info-module-functions} 35002 35003@subsubheading Synopsis 35004 35005@smallexample 35006 -symbol-info-module-functions [--module @var{module_regexp}] 35007 [--name @var{name_regexp}] 35008 [--type @var{type_regexp}] 35009@end smallexample 35010 35011@noindent 35012Return a list containing the names of all known functions within all 35013know Fortran modules. The functions are grouped by source file and 35014containing module, and shown with the line number on which each 35015function is defined. 35016 35017The option @code{--module} only returns results for modules matching 35018@var{module_regexp}. The option @code{--name} only returns functions 35019whose name matches @var{name_regexp}, and @code{--type} only returns 35020functions whose type matches @var{type_regexp}. 35021 35022@subsubheading @value{GDBN} Command 35023 35024The corresponding @value{GDBN} command is @samp{info module functions}. 35025 35026@subsubheading Example 35027 35028@smallexample 35029@group 35030(gdb) 35031-symbol-info-module-functions 35032^done,symbols= 35033 [@{module="mod1", 35034 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 35035 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 35036 symbols=[@{line="21",name="mod1::check_all",type="void (void)", 35037 description="void mod1::check_all(void);"@}]@}]@}, 35038 @{module="mod2", 35039 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 35040 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 35041 symbols=[@{line="30",name="mod2::check_var_i",type="void (void)", 35042 description="void mod2::check_var_i(void);"@}]@}]@}, 35043 @{module="mod3", 35044 files=[@{filename="/projec/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 35045 fullname="/projec/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 35046 symbols=[@{line="21",name="mod3::check_all",type="void (void)", 35047 description="void mod3::check_all(void);"@}, 35048 @{line="27",name="mod3::check_mod2",type="void (void)", 35049 description="void mod3::check_mod2(void);"@}]@}]@}, 35050 @{module="modmany", 35051 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 35052 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 35053 symbols=[@{line="35",name="modmany::check_some",type="void (void)", 35054 description="void modmany::check_some(void);"@}]@}]@}, 35055 @{module="moduse", 35056 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 35057 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 35058 symbols=[@{line="44",name="moduse::check_all",type="void (void)", 35059 description="void moduse::check_all(void);"@}, 35060 @{line="49",name="moduse::check_var_x",type="void (void)", 35061 description="void moduse::check_var_x(void);"@}]@}]@}] 35062@end group 35063@end smallexample 35064 35065@subheading The @code{-symbol-info-module-variables} Command 35066@findex -symbol-info-module-variables 35067@anchor{-symbol-info-module-variables} 35068 35069@subsubheading Synopsis 35070 35071@smallexample 35072 -symbol-info-module-variables [--module @var{module_regexp}] 35073 [--name @var{name_regexp}] 35074 [--type @var{type_regexp}] 35075@end smallexample 35076 35077@noindent 35078Return a list containing the names of all known variables within all 35079know Fortran modules. The variables are grouped by source file and 35080containing module, and shown with the line number on which each 35081variable is defined. 35082 35083The option @code{--module} only returns results for modules matching 35084@var{module_regexp}. The option @code{--name} only returns variables 35085whose name matches @var{name_regexp}, and @code{--type} only returns 35086variables whose type matches @var{type_regexp}. 35087 35088@subsubheading @value{GDBN} Command 35089 35090The corresponding @value{GDBN} command is @samp{info module variables}. 35091 35092@subsubheading Example 35093 35094@smallexample 35095@group 35096(gdb) 35097-symbol-info-module-variables 35098^done,symbols= 35099 [@{module="mod1", 35100 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 35101 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 35102 symbols=[@{line="18",name="mod1::var_const",type="integer(kind=4)", 35103 description="integer(kind=4) mod1::var_const;"@}, 35104 @{line="17",name="mod1::var_i",type="integer(kind=4)", 35105 description="integer(kind=4) mod1::var_i;"@}]@}]@}, 35106 @{module="mod2", 35107 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 35108 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 35109 symbols=[@{line="28",name="mod2::var_i",type="integer(kind=4)", 35110 description="integer(kind=4) mod2::var_i;"@}]@}]@}, 35111 @{module="mod3", 35112 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 35113 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 35114 symbols=[@{line="18",name="mod3::mod1",type="integer(kind=4)", 35115 description="integer(kind=4) mod3::mod1;"@}, 35116 @{line="17",name="mod3::mod2",type="integer(kind=4)", 35117 description="integer(kind=4) mod3::mod2;"@}, 35118 @{line="19",name="mod3::var_i",type="integer(kind=4)", 35119 description="integer(kind=4) mod3::var_i;"@}]@}]@}, 35120 @{module="modmany", 35121 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 35122 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 35123 symbols=[@{line="33",name="modmany::var_a",type="integer(kind=4)", 35124 description="integer(kind=4) modmany::var_a;"@}, 35125 @{line="33",name="modmany::var_b",type="integer(kind=4)", 35126 description="integer(kind=4) modmany::var_b;"@}, 35127 @{line="33",name="modmany::var_c",type="integer(kind=4)", 35128 description="integer(kind=4) modmany::var_c;"@}, 35129 @{line="33",name="modmany::var_i",type="integer(kind=4)", 35130 description="integer(kind=4) modmany::var_i;"@}]@}]@}, 35131 @{module="moduse", 35132 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 35133 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 35134 symbols=[@{line="42",name="moduse::var_x",type="integer(kind=4)", 35135 description="integer(kind=4) moduse::var_x;"@}, 35136 @{line="42",name="moduse::var_y",type="integer(kind=4)", 35137 description="integer(kind=4) moduse::var_y;"@}]@}]@}] 35138@end group 35139@end smallexample 35140 35141@subheading The @code{-symbol-info-modules} Command 35142@findex -symbol-info-modules 35143@anchor{-symbol-info-modules} 35144 35145@subsubheading Synopsis 35146 35147@smallexample 35148 -symbol-info-modules [--name @var{name_regexp}] 35149 [--max-results @var{limit}] 35150 35151@end smallexample 35152 35153@noindent 35154Return a list containing the names of all known Fortran modules. The 35155modules are grouped by source file, and shown with the line number on 35156which each modules is defined. 35157 35158The option @code{--name} allows the modules returned to be filtered 35159based the name of the module. 35160 35161The option @code{--max-results} restricts the command to return no 35162more than @var{limit} results. If exactly @var{limit} results are 35163returned then there might be additional results available if a higher 35164limit is used. 35165 35166@subsubheading @value{GDBN} Command 35167 35168The corresponding @value{GDBN} command is @samp{info modules}. 35169 35170@subsubheading Example 35171@smallexample 35172@group 35173(gdb) 35174-symbol-info-modules 35175^done,symbols= 35176 @{debug= 35177 [@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 35178 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 35179 symbols=[@{line="16",name="mod1"@}, 35180 @{line="22",name="mod2"@}]@}, 35181 @{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 35182 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 35183 symbols=[@{line="16",name="mod3"@}, 35184 @{line="22",name="modmany"@}, 35185 @{line="26",name="moduse"@}]@}]@} 35186@end group 35187@group 35188(gdb) 35189-symbol-info-modules --name mod[123] 35190^done,symbols= 35191 @{debug= 35192 [@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 35193 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 35194 symbols=[@{line="16",name="mod1"@}, 35195 @{line="22",name="mod2"@}]@}, 35196 @{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 35197 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 35198 symbols=[@{line="16",name="mod3"@}]@}]@} 35199@end group 35200@end smallexample 35201 35202@subheading The @code{-symbol-info-types} Command 35203@findex -symbol-info-types 35204@anchor{-symbol-info-types} 35205 35206@subsubheading Synopsis 35207 35208@smallexample 35209 -symbol-info-types [--name @var{name_regexp}] 35210 [--max-results @var{limit}] 35211 35212@end smallexample 35213 35214@noindent 35215Return a list of all defined types. The types are grouped by source 35216file, and shown with the line number on which each user defined type 35217is defined. Some base types are not defined in the source code but 35218are added to the debug information by the compiler, for example 35219@code{int}, @code{float}, etc.; these types do not have an associated 35220line number. 35221 35222The option @code{--name} allows the list of types returned to be 35223filtered by name. 35224 35225The option @code{--max-results} restricts the command to return no 35226more than @var{limit} results. If exactly @var{limit} results are 35227returned then there might be additional results available if a higher 35228limit is used. 35229 35230@subsubheading @value{GDBN} Command 35231 35232The corresponding @value{GDBN} command is @samp{info types}. 35233 35234@subsubheading Example 35235@smallexample 35236@group 35237(gdb) 35238-symbol-info-types 35239^done,symbols= 35240 @{debug= 35241 [@{filename="gdb.mi/mi-sym-info-1.c", 35242 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 35243 symbols=[@{name="float"@}, 35244 @{name="int"@}, 35245 @{line="27",name="typedef int my_int_t;"@}]@}, 35246 @{filename="gdb.mi/mi-sym-info-2.c", 35247 fullname="/project/gdb.mi/mi-sym-info-2.c", 35248 symbols=[@{line="24",name="typedef float another_float_t;"@}, 35249 @{line="23",name="typedef int another_int_t;"@}, 35250 @{name="float"@}, 35251 @{name="int"@}]@}]@} 35252@end group 35253@group 35254(gdb) 35255-symbol-info-types --name _int_ 35256^done,symbols= 35257 @{debug= 35258 [@{filename="gdb.mi/mi-sym-info-1.c", 35259 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 35260 symbols=[@{line="27",name="typedef int my_int_t;"@}]@}, 35261 @{filename="gdb.mi/mi-sym-info-2.c", 35262 fullname="/project/gdb.mi/mi-sym-info-2.c", 35263 symbols=[@{line="23",name="typedef int another_int_t;"@}]@}]@} 35264@end group 35265@end smallexample 35266 35267@subheading The @code{-symbol-info-variables} Command 35268@findex -symbol-info-variables 35269@anchor{-symbol-info-variables} 35270 35271@subsubheading Synopsis 35272 35273@smallexample 35274 -symbol-info-variables [--include-nondebug] 35275 [--type @var{type_regexp}] 35276 [--name @var{name_regexp}] 35277 [--max-results @var{limit}] 35278 35279@end smallexample 35280 35281@noindent 35282Return a list containing the names and types for all global variables 35283taken from the debug information. The variables are grouped by source 35284file, and shown with the line number on which each variable is 35285defined. 35286 35287The @code{--include-nondebug} option causes the output to include 35288data symbols from the symbol table. 35289 35290The options @code{--type} and @code{--name} allow the symbols returned 35291to be filtered based on either the name of the variable, or the type 35292of the variable. 35293 35294The option @code{--max-results} restricts the command to return no 35295more than @var{limit} results. If exactly @var{limit} results are 35296returned then there might be additional results available if a higher 35297limit is used. 35298 35299@subsubheading @value{GDBN} Command 35300 35301The corresponding @value{GDBN} command is @samp{info variables}. 35302 35303@subsubheading Example 35304@smallexample 35305@group 35306(gdb) 35307-symbol-info-variables 35308^done,symbols= 35309 @{debug= 35310 [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 35311 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 35312 symbols=[@{line="25",name="global_f1",type="float", 35313 description="static float global_f1;"@}, 35314 @{line="24",name="global_i1",type="int", 35315 description="static int global_i1;"@}]@}, 35316 @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 35317 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 35318 symbols=[@{line="21",name="global_f2",type="int", 35319 description="int global_f2;"@}, 35320 @{line="20",name="global_i2",type="int", 35321 description="int global_i2;"@}, 35322 @{line="19",name="global_f1",type="float", 35323 description="static float global_f1;"@}, 35324 @{line="18",name="global_i1",type="int", 35325 description="static int global_i1;"@}]@}]@} 35326@end group 35327@group 35328(gdb) 35329-symbol-info-variables --name f1 35330^done,symbols= 35331 @{debug= 35332 [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 35333 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 35334 symbols=[@{line="25",name="global_f1",type="float", 35335 description="static float global_f1;"@}]@}, 35336 @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 35337 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 35338 symbols=[@{line="19",name="global_f1",type="float", 35339 description="static float global_f1;"@}]@}]@} 35340@end group 35341@group 35342(gdb) 35343-symbol-info-variables --type float 35344^done,symbols= 35345 @{debug= 35346 [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 35347 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 35348 symbols=[@{line="25",name="global_f1",type="float", 35349 description="static float global_f1;"@}]@}, 35350 @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 35351 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 35352 symbols=[@{line="19",name="global_f1",type="float", 35353 description="static float global_f1;"@}]@}]@} 35354@end group 35355@group 35356(gdb) 35357-symbol-info-variables --include-nondebug 35358^done,symbols= 35359 @{debug= 35360 [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 35361 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 35362 symbols=[@{line="25",name="global_f1",type="float", 35363 description="static float global_f1;"@}, 35364 @{line="24",name="global_i1",type="int", 35365 description="static int global_i1;"@}]@}, 35366 @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 35367 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 35368 symbols=[@{line="21",name="global_f2",type="int", 35369 description="int global_f2;"@}, 35370 @{line="20",name="global_i2",type="int", 35371 description="int global_i2;"@}, 35372 @{line="19",name="global_f1",type="float", 35373 description="static float global_f1;"@}, 35374 @{line="18",name="global_i1",type="int", 35375 description="static int global_i1;"@}]@}], 35376 nondebug= 35377 [@{address="0x00000000004005d0",name="_IO_stdin_used"@}, 35378 @{address="0x00000000004005d8",name="__dso_handle"@} 35379 ... 35380 ]@} 35381@end group 35382@end smallexample 35383 35384@ignore 35385@subheading The @code{-symbol-info-line} Command 35386@findex -symbol-info-line 35387 35388@subsubheading Synopsis 35389 35390@smallexample 35391 -symbol-info-line 35392@end smallexample 35393 35394Show the core addresses of the code for a source line. 35395 35396@subsubheading @value{GDBN} Command 35397 35398The corresponding @value{GDBN} command is @samp{info line}. 35399@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands. 35400 35401@subsubheading Example 35402N.A. 35403 35404 35405@subheading The @code{-symbol-info-symbol} Command 35406@findex -symbol-info-symbol 35407 35408@subsubheading Synopsis 35409 35410@smallexample 35411 -symbol-info-symbol @var{addr} 35412@end smallexample 35413 35414Describe what symbol is at location @var{addr}. 35415 35416@subsubheading @value{GDBN} Command 35417 35418The corresponding @value{GDBN} command is @samp{info symbol}. 35419 35420@subsubheading Example 35421N.A. 35422 35423 35424@subheading The @code{-symbol-list-functions} Command 35425@findex -symbol-list-functions 35426 35427@subsubheading Synopsis 35428 35429@smallexample 35430 -symbol-list-functions 35431@end smallexample 35432 35433List the functions in the executable. 35434 35435@subsubheading @value{GDBN} Command 35436 35437@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and 35438@samp{gdb_search} in @code{gdbtk}. 35439 35440@subsubheading Example 35441N.A. 35442@end ignore 35443 35444 35445@subheading The @code{-symbol-list-lines} Command 35446@findex -symbol-list-lines 35447 35448@subsubheading Synopsis 35449 35450@smallexample 35451 -symbol-list-lines @var{filename} 35452@end smallexample 35453 35454Print the list of lines that contain code and their associated program 35455addresses for the given source filename. The entries are sorted in 35456ascending PC order. 35457 35458@subsubheading @value{GDBN} Command 35459 35460There is no corresponding @value{GDBN} command. 35461 35462@subsubheading Example 35463@smallexample 35464(gdb) 35465-symbol-list-lines basics.c 35466^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}] 35467(gdb) 35468@end smallexample 35469 35470 35471@ignore 35472@subheading The @code{-symbol-list-types} Command 35473@findex -symbol-list-types 35474 35475@subsubheading Synopsis 35476 35477@smallexample 35478 -symbol-list-types 35479@end smallexample 35480 35481List all the type names. 35482 35483@subsubheading @value{GDBN} Command 35484 35485The corresponding commands are @samp{info types} in @value{GDBN}, 35486@samp{gdb_search} in @code{gdbtk}. 35487 35488@subsubheading Example 35489N.A. 35490 35491 35492@subheading The @code{-symbol-list-variables} Command 35493@findex -symbol-list-variables 35494 35495@subsubheading Synopsis 35496 35497@smallexample 35498 -symbol-list-variables 35499@end smallexample 35500 35501List all the global and static variable names. 35502 35503@subsubheading @value{GDBN} Command 35504 35505@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}. 35506 35507@subsubheading Example 35508N.A. 35509 35510 35511@subheading The @code{-symbol-locate} Command 35512@findex -symbol-locate 35513 35514@subsubheading Synopsis 35515 35516@smallexample 35517 -symbol-locate 35518@end smallexample 35519 35520@subsubheading @value{GDBN} Command 35521 35522@samp{gdb_loc} in @code{gdbtk}. 35523 35524@subsubheading Example 35525N.A. 35526 35527 35528@subheading The @code{-symbol-type} Command 35529@findex -symbol-type 35530 35531@subsubheading Synopsis 35532 35533@smallexample 35534 -symbol-type @var{variable} 35535@end smallexample 35536 35537Show type of @var{variable}. 35538 35539@subsubheading @value{GDBN} Command 35540 35541The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has 35542@samp{gdb_obj_variable}. 35543 35544@subsubheading Example 35545N.A. 35546@end ignore 35547 35548 35549@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 35550@node GDB/MI File Commands 35551@section @sc{gdb/mi} File Commands 35552 35553This section describes the GDB/MI commands to specify executable file names 35554and to read in and obtain symbol table information. 35555 35556@subheading The @code{-file-exec-and-symbols} Command 35557@findex -file-exec-and-symbols 35558 35559@subsubheading Synopsis 35560 35561@smallexample 35562 -file-exec-and-symbols @var{file} 35563@end smallexample 35564 35565Specify the executable file to be debugged. This file is the one from 35566which the symbol table is also read. If no file is specified, the 35567command clears the executable and symbol information. If breakpoints 35568are set when using this command with no arguments, @value{GDBN} will produce 35569error messages. Otherwise, no output is produced, except a completion 35570notification. 35571 35572@subsubheading @value{GDBN} Command 35573 35574The corresponding @value{GDBN} command is @samp{file}. 35575 35576@subsubheading Example 35577 35578@smallexample 35579(gdb) 35580-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 35581^done 35582(gdb) 35583@end smallexample 35584 35585 35586@subheading The @code{-file-exec-file} Command 35587@findex -file-exec-file 35588 35589@subsubheading Synopsis 35590 35591@smallexample 35592 -file-exec-file @var{file} 35593@end smallexample 35594 35595Specify the executable file to be debugged. Unlike 35596@samp{-file-exec-and-symbols}, the symbol table is @emph{not} read 35597from this file. If used without argument, @value{GDBN} clears the information 35598about the executable file. No output is produced, except a completion 35599notification. 35600 35601@subsubheading @value{GDBN} Command 35602 35603The corresponding @value{GDBN} command is @samp{exec-file}. 35604 35605@subsubheading Example 35606 35607@smallexample 35608(gdb) 35609-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 35610^done 35611(gdb) 35612@end smallexample 35613 35614 35615@ignore 35616@subheading The @code{-file-list-exec-sections} Command 35617@findex -file-list-exec-sections 35618 35619@subsubheading Synopsis 35620 35621@smallexample 35622 -file-list-exec-sections 35623@end smallexample 35624 35625List the sections of the current executable file. 35626 35627@subsubheading @value{GDBN} Command 35628 35629The @value{GDBN} command @samp{info file} shows, among the rest, the same 35630information as this command. @code{gdbtk} has a corresponding command 35631@samp{gdb_load_info}. 35632 35633@subsubheading Example 35634N.A. 35635@end ignore 35636 35637 35638@subheading The @code{-file-list-exec-source-file} Command 35639@findex -file-list-exec-source-file 35640 35641@subsubheading Synopsis 35642 35643@smallexample 35644 -file-list-exec-source-file 35645@end smallexample 35646 35647List the line number, the current source file, and the absolute path 35648to the current source file for the current executable. The macro 35649information field has a value of @samp{1} or @samp{0} depending on 35650whether or not the file includes preprocessor macro information. 35651 35652@subsubheading @value{GDBN} Command 35653 35654The @value{GDBN} equivalent is @samp{info source} 35655 35656@subsubheading Example 35657 35658@smallexample 35659(gdb) 35660123-file-list-exec-source-file 35661123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1" 35662(gdb) 35663@end smallexample 35664 35665 35666@subheading The @code{-file-list-exec-source-files} Command 35667@kindex info sources 35668@findex -file-list-exec-source-files 35669 35670@subsubheading Synopsis 35671 35672@smallexample 35673 -file-list-exec-source-files @r{[} @var{--group-by-objfile} @r{]} 35674 @r{[} @var{--dirname} @r{|} @var{--basename} @r{]} 35675 @r{[} -- @r{]} 35676 @r{[} @var{regexp} @r{]} 35677@end smallexample 35678 35679This command returns information about the source files @value{GDBN} 35680knows about, it will output both the filename and fullname (absolute 35681file name) of a source file, though the fullname can be elided if this 35682information is not known to @value{GDBN}. 35683 35684With no arguments this command returns a list of source files. Each 35685source file is represented by a tuple with the fields; @var{file}, 35686@var{fullname}, and @var{debug-fully-read}. The @var{file} is the 35687display name for the file, while @var{fullname} is the absolute name 35688of the file. The @var{fullname} field can be elided if the absolute 35689name of the source file can't be computed. The field 35690@var{debug-fully-read} will be a string, either @code{true} or 35691@code{false}. When @code{true}, this indicates the full debug 35692information for the compilation unit describing this file has been 35693read in. When @code{false}, the full debug information has not yet 35694been read in. While reading in the full debug information it is 35695possible that @value{GDBN} could become aware of additional source 35696files. 35697 35698The optional @var{regexp} can be used to filter the list of source 35699files returned. The @var{regexp} will be matched against the full 35700source file name. The matching is case-sensitive, except on operating 35701systems that have case-insensitive filesystem (e.g., 35702MS-Windows). @samp{--} can be used before @var{regexp} to prevent 35703@value{GDBN} interpreting @var{regexp} as a command option (e.g.@: if 35704@var{regexp} starts with @samp{-}). 35705 35706If @code{--dirname} is provided, then @var{regexp} is matched only 35707against the directory name of each source file. If @code{--basename} 35708is provided, then @var{regexp} is matched against the basename of each 35709source file. Only one of @code{--dirname} or @code{--basename} may be 35710given, and if either is given then @var{regexp} is required. 35711 35712If @code{--group-by-objfile} is used then the format of the results is 35713changed. The results will now be a list of tuples, with each tuple 35714representing an object file (executable or shared library) loaded into 35715@value{GDBN}. The fields of these tuples are; @var{filename}, 35716@var{debug-info}, and @var{sources}. The @var{filename} is the 35717absolute name of the object file, @var{debug-info} is a string with 35718one of the following values: 35719 35720@table @code 35721@item none 35722This object file has no debug information. 35723@item partially-read 35724This object file has debug information, but it is not fully read in 35725yet. When it is read in later, GDB might become aware of additional 35726source files. 35727@item fully-read 35728This object file has debug information, and this information is fully 35729read into GDB. The list of source files is complete. 35730@end table 35731 35732The @var{sources} is a list or tuples, with each tuple describing a 35733single source file with the same fields as described previously. The 35734@var{sources} list can be empty for object files that have no debug 35735information. 35736 35737@subsubheading @value{GDBN} Command 35738 35739The @value{GDBN} equivalent is @samp{info sources}. 35740@code{gdbtk} has an analogous command @samp{gdb_listfiles}. 35741 35742@subsubheading Example 35743@smallexample 35744(@value{GDBP}) 35745-file-list-exec-source-files 35746^done,files=[@{file="foo.c",fullname="/home/foo.c",debug-fully-read="true"@}, 35747 @{file="/home/bar.c",fullname="/home/bar.c",debug-fully-read="true"@}, 35748 @{file="gdb_could_not_find_fullpath.c",debug-fully-read="true"@}] 35749(@value{GDBP}) 35750-file-list-exec-source-files 35751^done,files=[@{file="test.c", 35752 fullname="/tmp/info-sources/test.c", 35753 debug-fully-read="true"@}, 35754 @{file="/usr/include/stdc-predef.h", 35755 fullname="/usr/include/stdc-predef.h", 35756 debug-fully-read="true"@}, 35757 @{file="header.h", 35758 fullname="/tmp/info-sources/header.h", 35759 debug-fully-read="true"@}, 35760 @{file="helper.c", 35761 fullname="/tmp/info-sources/helper.c", 35762 debug-fully-read="true"@}] 35763(@value{GDBP}) 35764-file-list-exec-source-files -- \\.c 35765^done,files=[@{file="test.c", 35766 fullname="/tmp/info-sources/test.c", 35767 debug-fully-read="true"@}, 35768 @{file="helper.c", 35769 fullname="/tmp/info-sources/helper.c", 35770 debug-fully-read="true"@}] 35771(@value{GDBP}) 35772-file-list-exec-source-files --group-by-objfile 35773^done,files=[@{filename="/tmp/info-sources/test.x", 35774 debug-info="fully-read", 35775 sources=[@{file="test.c", 35776 fullname="/tmp/info-sources/test.c", 35777 debug-fully-read="true"@}, 35778 @{file="/usr/include/stdc-predef.h", 35779 fullname="/usr/include/stdc-predef.h", 35780 debug-fully-read="true"@}, 35781 @{file="header.h", 35782 fullname="/tmp/info-sources/header.h", 35783 debug-fully-read="true"@}]@}, 35784 @{filename="/lib64/ld-linux-x86-64.so.2", 35785 debug-info="none", 35786 sources=[]@}, 35787 @{filename="system-supplied DSO at 0x7ffff7fcf000", 35788 debug-info="none", 35789 sources=[]@}, 35790 @{filename="/tmp/info-sources/libhelper.so", 35791 debug-info="fully-read", 35792 sources=[@{file="helper.c", 35793 fullname="/tmp/info-sources/helper.c", 35794 debug-fully-read="true"@}, 35795 @{file="/usr/include/stdc-predef.h", 35796 fullname="/usr/include/stdc-predef.h", 35797 debug-fully-read="true"@}, 35798 @{file="header.h", 35799 fullname="/tmp/info-sources/header.h", 35800 debug-fully-read="true"@}]@}, 35801 @{filename="/lib64/libc.so.6", 35802 debug-info="none", 35803 sources=[]@}] 35804@end smallexample 35805 35806@subheading The @code{-file-list-shared-libraries} Command 35807@findex -file-list-shared-libraries 35808 35809@subsubheading Synopsis 35810 35811@smallexample 35812 -file-list-shared-libraries [ @var{regexp} ] 35813@end smallexample 35814 35815List the shared libraries in the program. 35816With a regular expression @var{regexp}, only those libraries whose 35817names match @var{regexp} are listed. 35818 35819@subsubheading @value{GDBN} Command 35820 35821The corresponding @value{GDBN} command is @samp{info shared}. The fields 35822have a similar meaning to the @code{=library-loaded} notification. 35823The @code{ranges} field specifies the multiple segments belonging to this 35824library. Each range has the following fields: 35825 35826@table @samp 35827@item from 35828The address defining the inclusive lower bound of the segment. 35829@item to 35830The address defining the exclusive upper bound of the segment. 35831@end table 35832 35833@subsubheading Example 35834@smallexample 35835(gdb) 35836-file-list-exec-source-files 35837^done,shared-libraries=[ 35838@{id="/lib/libfoo.so",target-name="/lib/libfoo.so",host-name="/lib/libfoo.so",symbols-loaded="1",thread-group="i1",ranges=[@{from="0x72815989",to="0x728162c0"@}]@}, 35839@{id="/lib/libbar.so",target-name="/lib/libbar.so",host-name="/lib/libbar.so",symbols-loaded="1",thread-group="i1",ranges=[@{from="0x76ee48c0",to="0x76ee9160"@}]@}] 35840(gdb) 35841@end smallexample 35842 35843 35844@ignore 35845@subheading The @code{-file-list-symbol-files} Command 35846@findex -file-list-symbol-files 35847 35848@subsubheading Synopsis 35849 35850@smallexample 35851 -file-list-symbol-files 35852@end smallexample 35853 35854List symbol files. 35855 35856@subsubheading @value{GDBN} Command 35857 35858The corresponding @value{GDBN} command is @samp{info file} (part of it). 35859 35860@subsubheading Example 35861N.A. 35862@end ignore 35863 35864 35865@subheading The @code{-file-symbol-file} Command 35866@findex -file-symbol-file 35867 35868@subsubheading Synopsis 35869 35870@smallexample 35871 -file-symbol-file @var{file} 35872@end smallexample 35873 35874Read symbol table info from the specified @var{file} argument. When 35875used without arguments, clears @value{GDBN}'s symbol table info. No output is 35876produced, except for a completion notification. 35877 35878@subsubheading @value{GDBN} Command 35879 35880The corresponding @value{GDBN} command is @samp{symbol-file}. 35881 35882@subsubheading Example 35883 35884@smallexample 35885(gdb) 35886-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 35887^done 35888(gdb) 35889@end smallexample 35890 35891@ignore 35892@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 35893@node GDB/MI Memory Overlay Commands 35894@section @sc{gdb/mi} Memory Overlay Commands 35895 35896The memory overlay commands are not implemented. 35897 35898@c @subheading -overlay-auto 35899 35900@c @subheading -overlay-list-mapping-state 35901 35902@c @subheading -overlay-list-overlays 35903 35904@c @subheading -overlay-map 35905 35906@c @subheading -overlay-off 35907 35908@c @subheading -overlay-on 35909 35910@c @subheading -overlay-unmap 35911 35912@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 35913@node GDB/MI Signal Handling Commands 35914@section @sc{gdb/mi} Signal Handling Commands 35915 35916Signal handling commands are not implemented. 35917 35918@c @subheading -signal-handle 35919 35920@c @subheading -signal-list-handle-actions 35921 35922@c @subheading -signal-list-signal-types 35923@end ignore 35924 35925 35926@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 35927@node GDB/MI Target Manipulation 35928@section @sc{gdb/mi} Target Manipulation Commands 35929 35930 35931@subheading The @code{-target-attach} Command 35932@findex -target-attach 35933 35934@subsubheading Synopsis 35935 35936@smallexample 35937 -target-attach @var{pid} | @var{gid} | @var{file} 35938@end smallexample 35939 35940Attach to a process @var{pid} or a file @var{file} outside of 35941@value{GDBN}, or a thread group @var{gid}. If attaching to a thread 35942group, the id previously returned by 35943@samp{-list-thread-groups --available} must be used. 35944 35945@subsubheading @value{GDBN} Command 35946 35947The corresponding @value{GDBN} command is @samp{attach}. 35948 35949@subsubheading Example 35950@smallexample 35951(gdb) 35952-target-attach 34 35953=thread-created,id="1" 35954*stopped,thread-id="1",frame=@{addr="0xb7f7e410",func="bar",args=[]@} 35955^done 35956(gdb) 35957@end smallexample 35958 35959@ignore 35960@subheading The @code{-target-compare-sections} Command 35961@findex -target-compare-sections 35962 35963@subsubheading Synopsis 35964 35965@smallexample 35966 -target-compare-sections [ @var{section} ] 35967@end smallexample 35968 35969Compare data of section @var{section} on target to the exec file. 35970Without the argument, all sections are compared. 35971 35972@subsubheading @value{GDBN} Command 35973 35974The @value{GDBN} equivalent is @samp{compare-sections}. 35975 35976@subsubheading Example 35977N.A. 35978@end ignore 35979 35980 35981@subheading The @code{-target-detach} Command 35982@findex -target-detach 35983 35984@subsubheading Synopsis 35985 35986@smallexample 35987 -target-detach [ @var{pid} | @var{gid} ] 35988@end smallexample 35989 35990Detach from the remote target which normally resumes its execution. 35991If either @var{pid} or @var{gid} is specified, detaches from either 35992the specified process, or specified thread group. There's no output. 35993 35994@subsubheading @value{GDBN} Command 35995 35996The corresponding @value{GDBN} command is @samp{detach}. 35997 35998@subsubheading Example 35999 36000@smallexample 36001(gdb) 36002-target-detach 36003^done 36004(gdb) 36005@end smallexample 36006 36007 36008@subheading The @code{-target-disconnect} Command 36009@findex -target-disconnect 36010 36011@subsubheading Synopsis 36012 36013@smallexample 36014 -target-disconnect 36015@end smallexample 36016 36017Disconnect from the remote target. There's no output and the target is 36018generally not resumed. 36019 36020@subsubheading @value{GDBN} Command 36021 36022The corresponding @value{GDBN} command is @samp{disconnect}. 36023 36024@subsubheading Example 36025 36026@smallexample 36027(gdb) 36028-target-disconnect 36029^done 36030(gdb) 36031@end smallexample 36032 36033 36034@subheading The @code{-target-download} Command 36035@findex -target-download 36036 36037@subsubheading Synopsis 36038 36039@smallexample 36040 -target-download 36041@end smallexample 36042 36043Loads the executable onto the remote target. 36044It prints out an update message every half second, which includes the fields: 36045 36046@table @samp 36047@item section 36048The name of the section. 36049@item section-sent 36050The size of what has been sent so far for that section. 36051@item section-size 36052The size of the section. 36053@item total-sent 36054The total size of what was sent so far (the current and the previous sections). 36055@item total-size 36056The size of the overall executable to download. 36057@end table 36058 36059@noindent 36060Each message is sent as status record (@pxref{GDB/MI Output Syntax, , 36061@sc{gdb/mi} Output Syntax}). 36062 36063In addition, it prints the name and size of the sections, as they are 36064downloaded. These messages include the following fields: 36065 36066@table @samp 36067@item section 36068The name of the section. 36069@item section-size 36070The size of the section. 36071@item total-size 36072The size of the overall executable to download. 36073@end table 36074 36075@noindent 36076At the end, a summary is printed. 36077 36078@subsubheading @value{GDBN} Command 36079 36080The corresponding @value{GDBN} command is @samp{load}. 36081 36082@subsubheading Example 36083 36084Note: each status message appears on a single line. Here the messages 36085have been broken down so that they can fit onto a page. 36086 36087@smallexample 36088(gdb) 36089-target-download 36090+download,@{section=".text",section-size="6668",total-size="9880"@} 36091+download,@{section=".text",section-sent="512",section-size="6668", 36092total-sent="512",total-size="9880"@} 36093+download,@{section=".text",section-sent="1024",section-size="6668", 36094total-sent="1024",total-size="9880"@} 36095+download,@{section=".text",section-sent="1536",section-size="6668", 36096total-sent="1536",total-size="9880"@} 36097+download,@{section=".text",section-sent="2048",section-size="6668", 36098total-sent="2048",total-size="9880"@} 36099+download,@{section=".text",section-sent="2560",section-size="6668", 36100total-sent="2560",total-size="9880"@} 36101+download,@{section=".text",section-sent="3072",section-size="6668", 36102total-sent="3072",total-size="9880"@} 36103+download,@{section=".text",section-sent="3584",section-size="6668", 36104total-sent="3584",total-size="9880"@} 36105+download,@{section=".text",section-sent="4096",section-size="6668", 36106total-sent="4096",total-size="9880"@} 36107+download,@{section=".text",section-sent="4608",section-size="6668", 36108total-sent="4608",total-size="9880"@} 36109+download,@{section=".text",section-sent="5120",section-size="6668", 36110total-sent="5120",total-size="9880"@} 36111+download,@{section=".text",section-sent="5632",section-size="6668", 36112total-sent="5632",total-size="9880"@} 36113+download,@{section=".text",section-sent="6144",section-size="6668", 36114total-sent="6144",total-size="9880"@} 36115+download,@{section=".text",section-sent="6656",section-size="6668", 36116total-sent="6656",total-size="9880"@} 36117+download,@{section=".init",section-size="28",total-size="9880"@} 36118+download,@{section=".fini",section-size="28",total-size="9880"@} 36119+download,@{section=".data",section-size="3156",total-size="9880"@} 36120+download,@{section=".data",section-sent="512",section-size="3156", 36121total-sent="7236",total-size="9880"@} 36122+download,@{section=".data",section-sent="1024",section-size="3156", 36123total-sent="7748",total-size="9880"@} 36124+download,@{section=".data",section-sent="1536",section-size="3156", 36125total-sent="8260",total-size="9880"@} 36126+download,@{section=".data",section-sent="2048",section-size="3156", 36127total-sent="8772",total-size="9880"@} 36128+download,@{section=".data",section-sent="2560",section-size="3156", 36129total-sent="9284",total-size="9880"@} 36130+download,@{section=".data",section-sent="3072",section-size="3156", 36131total-sent="9796",total-size="9880"@} 36132^done,address="0x10004",load-size="9880",transfer-rate="6586", 36133write-rate="429" 36134(gdb) 36135@end smallexample 36136 36137 36138@ignore 36139@subheading The @code{-target-exec-status} Command 36140@findex -target-exec-status 36141 36142@subsubheading Synopsis 36143 36144@smallexample 36145 -target-exec-status 36146@end smallexample 36147 36148Provide information on the state of the target (whether it is running or 36149not, for instance). 36150 36151@subsubheading @value{GDBN} Command 36152 36153There's no equivalent @value{GDBN} command. 36154 36155@subsubheading Example 36156N.A. 36157 36158 36159@subheading The @code{-target-list-available-targets} Command 36160@findex -target-list-available-targets 36161 36162@subsubheading Synopsis 36163 36164@smallexample 36165 -target-list-available-targets 36166@end smallexample 36167 36168List the possible targets to connect to. 36169 36170@subsubheading @value{GDBN} Command 36171 36172The corresponding @value{GDBN} command is @samp{help target}. 36173 36174@subsubheading Example 36175N.A. 36176 36177 36178@subheading The @code{-target-list-current-targets} Command 36179@findex -target-list-current-targets 36180 36181@subsubheading Synopsis 36182 36183@smallexample 36184 -target-list-current-targets 36185@end smallexample 36186 36187Describe the current target. 36188 36189@subsubheading @value{GDBN} Command 36190 36191The corresponding information is printed by @samp{info file} (among 36192other things). 36193 36194@subsubheading Example 36195N.A. 36196 36197 36198@subheading The @code{-target-list-parameters} Command 36199@findex -target-list-parameters 36200 36201@subsubheading Synopsis 36202 36203@smallexample 36204 -target-list-parameters 36205@end smallexample 36206 36207@c ???? 36208@end ignore 36209 36210@subsubheading @value{GDBN} Command 36211 36212No equivalent. 36213 36214@subsubheading Example 36215N.A. 36216 36217@subheading The @code{-target-flash-erase} Command 36218@findex -target-flash-erase 36219 36220@subsubheading Synopsis 36221 36222@smallexample 36223 -target-flash-erase 36224@end smallexample 36225 36226Erases all known flash memory regions on the target. 36227 36228The corresponding @value{GDBN} command is @samp{flash-erase}. 36229 36230The output is a list of flash regions that have been erased, with starting 36231addresses and memory region sizes. 36232 36233@smallexample 36234(gdb) 36235-target-flash-erase 36236^done,erased-regions=@{address="0x0",size="0x40000"@} 36237(gdb) 36238@end smallexample 36239 36240@subheading The @code{-target-select} Command 36241@findex -target-select 36242 36243@subsubheading Synopsis 36244 36245@smallexample 36246 -target-select @var{type} @var{parameters @dots{}} 36247@end smallexample 36248 36249Connect @value{GDBN} to the remote target. This command takes two args: 36250 36251@table @samp 36252@item @var{type} 36253The type of target, for instance @samp{remote}, etc. 36254@item @var{parameters} 36255Device names, host names and the like. @xref{Target Commands, , 36256Commands for Managing Targets}, for more details. 36257@end table 36258 36259The output is a connection notification, followed by the address at 36260which the target program is, in the following form: 36261 36262@smallexample 36263^connected,addr="@var{address}",func="@var{function name}", 36264 args=[@var{arg list}] 36265@end smallexample 36266 36267@subsubheading @value{GDBN} Command 36268 36269The corresponding @value{GDBN} command is @samp{target}. 36270 36271@subsubheading Example 36272 36273@smallexample 36274(gdb) 36275-target-select remote /dev/ttya 36276^connected,addr="0xfe00a300",func="??",args=[] 36277(gdb) 36278@end smallexample 36279 36280@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 36281@node GDB/MI File Transfer Commands 36282@section @sc{gdb/mi} File Transfer Commands 36283 36284 36285@subheading The @code{-target-file-put} Command 36286@findex -target-file-put 36287 36288@subsubheading Synopsis 36289 36290@smallexample 36291 -target-file-put @var{hostfile} @var{targetfile} 36292@end smallexample 36293 36294Copy file @var{hostfile} from the host system (the machine running 36295@value{GDBN}) to @var{targetfile} on the target system. 36296 36297@subsubheading @value{GDBN} Command 36298 36299The corresponding @value{GDBN} command is @samp{remote put}. 36300 36301@subsubheading Example 36302 36303@smallexample 36304(gdb) 36305-target-file-put localfile remotefile 36306^done 36307(gdb) 36308@end smallexample 36309 36310 36311@subheading The @code{-target-file-get} Command 36312@findex -target-file-get 36313 36314@subsubheading Synopsis 36315 36316@smallexample 36317 -target-file-get @var{targetfile} @var{hostfile} 36318@end smallexample 36319 36320Copy file @var{targetfile} from the target system to @var{hostfile} 36321on the host system. 36322 36323@subsubheading @value{GDBN} Command 36324 36325The corresponding @value{GDBN} command is @samp{remote get}. 36326 36327@subsubheading Example 36328 36329@smallexample 36330(gdb) 36331-target-file-get remotefile localfile 36332^done 36333(gdb) 36334@end smallexample 36335 36336 36337@subheading The @code{-target-file-delete} Command 36338@findex -target-file-delete 36339 36340@subsubheading Synopsis 36341 36342@smallexample 36343 -target-file-delete @var{targetfile} 36344@end smallexample 36345 36346Delete @var{targetfile} from the target system. 36347 36348@subsubheading @value{GDBN} Command 36349 36350The corresponding @value{GDBN} command is @samp{remote delete}. 36351 36352@subsubheading Example 36353 36354@smallexample 36355(gdb) 36356-target-file-delete remotefile 36357^done 36358(gdb) 36359@end smallexample 36360 36361 36362@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 36363@node GDB/MI Ada Exceptions Commands 36364@section Ada Exceptions @sc{gdb/mi} Commands 36365 36366@subheading The @code{-info-ada-exceptions} Command 36367@findex -info-ada-exceptions 36368 36369@subsubheading Synopsis 36370 36371@smallexample 36372 -info-ada-exceptions [ @var{regexp}] 36373@end smallexample 36374 36375List all Ada exceptions defined within the program being debugged. 36376With a regular expression @var{regexp}, only those exceptions whose 36377names match @var{regexp} are listed. 36378 36379@subsubheading @value{GDBN} Command 36380 36381The corresponding @value{GDBN} command is @samp{info exceptions}. 36382 36383@subsubheading Result 36384 36385The result is a table of Ada exceptions. The following columns are 36386defined for each exception: 36387 36388@table @samp 36389@item name 36390The name of the exception. 36391 36392@item address 36393The address of the exception. 36394 36395@end table 36396 36397@subsubheading Example 36398 36399@smallexample 36400-info-ada-exceptions aint 36401^done,ada-exceptions=@{nr_rows="2",nr_cols="2", 36402hdr=[@{width="1",alignment="-1",col_name="name",colhdr="Name"@}, 36403@{width="1",alignment="-1",col_name="address",colhdr="Address"@}], 36404body=[@{name="constraint_error",address="0x0000000000613da0"@}, 36405@{name="const.aint_global_e",address="0x0000000000613b00"@}]@} 36406@end smallexample 36407 36408@subheading Catching Ada Exceptions 36409 36410The commands describing how to ask @value{GDBN} to stop when a program 36411raises an exception are described at @ref{Ada Exception GDB/MI 36412Catchpoint Commands}. 36413 36414 36415@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 36416@node GDB/MI Support Commands 36417@section @sc{gdb/mi} Support Commands 36418 36419Since new commands and features get regularly added to @sc{gdb/mi}, 36420some commands are available to help front-ends query the debugger 36421about support for these capabilities. Similarly, it is also possible 36422to query @value{GDBN} about target support of certain features. 36423 36424@subheading The @code{-info-gdb-mi-command} Command 36425@cindex @code{-info-gdb-mi-command} 36426@findex -info-gdb-mi-command 36427 36428@subsubheading Synopsis 36429 36430@smallexample 36431 -info-gdb-mi-command @var{cmd_name} 36432@end smallexample 36433 36434Query support for the @sc{gdb/mi} command named @var{cmd_name}. 36435 36436Note that the dash (@code{-}) starting all @sc{gdb/mi} commands 36437is technically not part of the command name (@pxref{GDB/MI Input 36438Syntax}), and thus should be omitted in @var{cmd_name}. However, 36439for ease of use, this command also accepts the form with the leading 36440dash. 36441 36442@subsubheading @value{GDBN} Command 36443 36444There is no corresponding @value{GDBN} command. 36445 36446@subsubheading Result 36447 36448The result is a tuple. There is currently only one field: 36449 36450@table @samp 36451@item exists 36452This field is equal to @code{"true"} if the @sc{gdb/mi} command exists, 36453@code{"false"} otherwise. 36454 36455@end table 36456 36457@subsubheading Example 36458 36459Here is an example where the @sc{gdb/mi} command does not exist: 36460 36461@smallexample 36462-info-gdb-mi-command unsupported-command 36463^done,command=@{exists="false"@} 36464@end smallexample 36465 36466@noindent 36467And here is an example where the @sc{gdb/mi} command is known 36468to the debugger: 36469 36470@smallexample 36471-info-gdb-mi-command symbol-list-lines 36472^done,command=@{exists="true"@} 36473@end smallexample 36474 36475@subheading The @code{-list-features} Command 36476@findex -list-features 36477@cindex supported @sc{gdb/mi} features, list 36478 36479Returns a list of particular features of the MI protocol that 36480this version of gdb implements. A feature can be a command, 36481or a new field in an output of some command, or even an 36482important bugfix. While a frontend can sometimes detect presence 36483of a feature at runtime, it is easier to perform detection at debugger 36484startup. 36485 36486The command returns a list of strings, with each string naming an 36487available feature. Each returned string is just a name, it does not 36488have any internal structure. The list of possible feature names 36489is given below. 36490 36491Example output: 36492 36493@smallexample 36494(gdb) -list-features 36495^done,result=["feature1","feature2"] 36496@end smallexample 36497 36498The current list of features is: 36499 36500@ftable @samp 36501@item frozen-varobjs 36502Indicates support for the @code{-var-set-frozen} command, as well 36503as possible presence of the @code{frozen} field in the output 36504of @code{-varobj-create}. 36505@item pending-breakpoints 36506Indicates support for the @option{-f} option to the @code{-break-insert} 36507command. 36508@item python 36509Indicates Python scripting support, Python-based 36510pretty-printing commands, and possible presence of the 36511@samp{display_hint} field in the output of @code{-var-list-children} 36512@item thread-info 36513Indicates support for the @code{-thread-info} command. 36514@item data-read-memory-bytes 36515Indicates support for the @code{-data-read-memory-bytes} and the 36516@code{-data-write-memory-bytes} commands. 36517@item breakpoint-notifications 36518Indicates that changes to breakpoints and breakpoints created via the 36519CLI will be announced via async records. 36520@item ada-task-info 36521Indicates support for the @code{-ada-task-info} command. 36522@item language-option 36523Indicates that all @sc{gdb/mi} commands accept the @option{--language} 36524option (@pxref{Context management}). 36525@item info-gdb-mi-command 36526Indicates support for the @code{-info-gdb-mi-command} command. 36527@item undefined-command-error-code 36528Indicates support for the "undefined-command" error code in error result 36529records, produced when trying to execute an undefined @sc{gdb/mi} command 36530(@pxref{GDB/MI Result Records}). 36531@item exec-run-start-option 36532Indicates that the @code{-exec-run} command supports the @option{--start} 36533option (@pxref{GDB/MI Program Execution}). 36534@item data-disassemble-a-option 36535Indicates that the @code{-data-disassemble} command supports the @option{-a} 36536option (@pxref{GDB/MI Data Manipulation}). 36537@end ftable 36538 36539@subheading The @code{-list-target-features} Command 36540@findex -list-target-features 36541 36542Returns a list of particular features that are supported by the 36543target. Those features affect the permitted MI commands, but 36544unlike the features reported by the @code{-list-features} command, the 36545features depend on which target GDB is using at the moment. Whenever 36546a target can change, due to commands such as @code{-target-select}, 36547@code{-target-attach} or @code{-exec-run}, the list of target features 36548may change, and the frontend should obtain it again. 36549Example output: 36550 36551@smallexample 36552(gdb) -list-target-features 36553^done,result=["async"] 36554@end smallexample 36555 36556The current list of features is: 36557 36558@table @samp 36559@item async 36560Indicates that the target is capable of asynchronous command 36561execution, which means that @value{GDBN} will accept further commands 36562while the target is running. 36563 36564@item reverse 36565Indicates that the target is capable of reverse execution. 36566@xref{Reverse Execution}, for more information. 36567 36568@end table 36569 36570@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 36571@node GDB/MI Miscellaneous Commands 36572@section Miscellaneous @sc{gdb/mi} Commands 36573 36574@c @subheading -gdb-complete 36575 36576@subheading The @code{-gdb-exit} Command 36577@findex -gdb-exit 36578 36579@subsubheading Synopsis 36580 36581@smallexample 36582 -gdb-exit 36583@end smallexample 36584 36585Exit @value{GDBN} immediately. 36586 36587@subsubheading @value{GDBN} Command 36588 36589Approximately corresponds to @samp{quit}. 36590 36591@subsubheading Example 36592 36593@smallexample 36594(gdb) 36595-gdb-exit 36596^exit 36597@end smallexample 36598 36599 36600@ignore 36601@subheading The @code{-exec-abort} Command 36602@findex -exec-abort 36603 36604@subsubheading Synopsis 36605 36606@smallexample 36607 -exec-abort 36608@end smallexample 36609 36610Kill the inferior running program. 36611 36612@subsubheading @value{GDBN} Command 36613 36614The corresponding @value{GDBN} command is @samp{kill}. 36615 36616@subsubheading Example 36617N.A. 36618@end ignore 36619 36620 36621@subheading The @code{-gdb-set} Command 36622@findex -gdb-set 36623 36624@subsubheading Synopsis 36625 36626@smallexample 36627 -gdb-set 36628@end smallexample 36629 36630Set an internal @value{GDBN} variable. 36631@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ????? 36632 36633@subsubheading @value{GDBN} Command 36634 36635The corresponding @value{GDBN} command is @samp{set}. 36636 36637@subsubheading Example 36638 36639@smallexample 36640(gdb) 36641-gdb-set $foo=3 36642^done 36643(gdb) 36644@end smallexample 36645 36646 36647@subheading The @code{-gdb-show} Command 36648@findex -gdb-show 36649 36650@subsubheading Synopsis 36651 36652@smallexample 36653 -gdb-show 36654@end smallexample 36655 36656Show the current value of a @value{GDBN} variable. 36657 36658@subsubheading @value{GDBN} Command 36659 36660The corresponding @value{GDBN} command is @samp{show}. 36661 36662@subsubheading Example 36663 36664@smallexample 36665(gdb) 36666-gdb-show annotate 36667^done,value="0" 36668(gdb) 36669@end smallexample 36670 36671@c @subheading -gdb-source 36672 36673 36674@subheading The @code{-gdb-version} Command 36675@findex -gdb-version 36676 36677@subsubheading Synopsis 36678 36679@smallexample 36680 -gdb-version 36681@end smallexample 36682 36683Show version information for @value{GDBN}. Used mostly in testing. 36684 36685@subsubheading @value{GDBN} Command 36686 36687The @value{GDBN} equivalent is @samp{show version}. @value{GDBN} by 36688default shows this information when you start an interactive session. 36689 36690@subsubheading Example 36691 36692@c This example modifies the actual output from GDB to avoid overfull 36693@c box in TeX. 36694@smallexample 36695(gdb) 36696-gdb-version 36697~GNU gdb 5.2.1 36698~Copyright 2000 Free Software Foundation, Inc. 36699~GDB is free software, covered by the GNU General Public License, and 36700~you are welcome to change it and/or distribute copies of it under 36701~ certain conditions. 36702~Type "show copying" to see the conditions. 36703~There is absolutely no warranty for GDB. Type "show warranty" for 36704~ details. 36705~This GDB was configured as 36706 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". 36707^done 36708(gdb) 36709@end smallexample 36710 36711@subheading The @code{-list-thread-groups} Command 36712@findex -list-thread-groups 36713 36714@subheading Synopsis 36715 36716@smallexample 36717-list-thread-groups [ --available ] [ --recurse 1 ] [ @var{group} ... ] 36718@end smallexample 36719 36720Lists thread groups (@pxref{Thread groups}). When a single thread 36721group is passed as the argument, lists the children of that group. 36722When several thread group are passed, lists information about those 36723thread groups. Without any parameters, lists information about all 36724top-level thread groups. 36725 36726Normally, thread groups that are being debugged are reported. 36727With the @samp{--available} option, @value{GDBN} reports thread groups 36728available on the target. 36729 36730The output of this command may have either a @samp{threads} result or 36731a @samp{groups} result. The @samp{thread} result has a list of tuples 36732as value, with each tuple describing a thread (@pxref{GDB/MI Thread 36733Information}). The @samp{groups} result has a list of tuples as value, 36734each tuple describing a thread group. If top-level groups are 36735requested (that is, no parameter is passed), or when several groups 36736are passed, the output always has a @samp{groups} result. The format 36737of the @samp{group} result is described below. 36738 36739To reduce the number of roundtrips it's possible to list thread groups 36740together with their children, by passing the @samp{--recurse} option 36741and the recursion depth. Presently, only recursion depth of 1 is 36742permitted. If this option is present, then every reported thread group 36743will also include its children, either as @samp{group} or 36744@samp{threads} field. 36745 36746In general, any combination of option and parameters is permitted, with 36747the following caveats: 36748 36749@itemize @bullet 36750@item 36751When a single thread group is passed, the output will typically 36752be the @samp{threads} result. Because threads may not contain 36753anything, the @samp{recurse} option will be ignored. 36754 36755@item 36756When the @samp{--available} option is passed, limited information may 36757be available. In particular, the list of threads of a process might 36758be inaccessible. Further, specifying specific thread groups might 36759not give any performance advantage over listing all thread groups. 36760The frontend should assume that @samp{-list-thread-groups --available} 36761is always an expensive operation and cache the results. 36762 36763@end itemize 36764 36765The @samp{groups} result is a list of tuples, where each tuple may 36766have the following fields: 36767 36768@table @code 36769@item id 36770Identifier of the thread group. This field is always present. 36771The identifier is an opaque string; frontends should not try to 36772convert it to an integer, even though it might look like one. 36773 36774@item type 36775The type of the thread group. At present, only @samp{process} is a 36776valid type. 36777 36778@item pid 36779The target-specific process identifier. This field is only present 36780for thread groups of type @samp{process} and only if the process exists. 36781 36782@item exit-code 36783The exit code of this group's last exited thread, formatted in octal. 36784This field is only present for thread groups of type @samp{process} and 36785only if the process is not running. 36786 36787@item num_children 36788The number of children this thread group has. This field may be 36789absent for an available thread group. 36790 36791@item threads 36792This field has a list of tuples as value, each tuple describing a 36793thread. It may be present if the @samp{--recurse} option is 36794specified, and it's actually possible to obtain the threads. 36795 36796@item cores 36797This field is a list of integers, each identifying a core that one 36798thread of the group is running on. This field may be absent if 36799such information is not available. 36800 36801@item executable 36802The name of the executable file that corresponds to this thread group. 36803The field is only present for thread groups of type @samp{process}, 36804and only if there is a corresponding executable file. 36805 36806@end table 36807 36808@subheading Example 36809 36810@smallexample 36811(@value{GDBP}) 36812-list-thread-groups 36813^done,groups=[@{id="17",type="process",pid="yyy",num_children="2"@}] 36814-list-thread-groups 17 36815^done,threads=[@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", 36816 frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@}, 36817@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", 36818 frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}], 36819 file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"@},state="running"@}]] 36820-list-thread-groups --available 36821^done,groups=[@{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]@}] 36822-list-thread-groups --available --recurse 1 36823 ^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], 36824 threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@}, 36825 @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},..] 36826-list-thread-groups --available --recurse 1 17 18 36827^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], 36828 threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@}, 36829 @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},...] 36830@end smallexample 36831 36832@subheading The @code{-info-os} Command 36833@findex -info-os 36834 36835@subsubheading Synopsis 36836 36837@smallexample 36838-info-os [ @var{type} ] 36839@end smallexample 36840 36841If no argument is supplied, the command returns a table of available 36842operating-system-specific information types. If one of these types is 36843supplied as an argument @var{type}, then the command returns a table 36844of data of that type. 36845 36846The types of information available depend on the target operating 36847system. 36848 36849@subsubheading @value{GDBN} Command 36850 36851The corresponding @value{GDBN} command is @samp{info os}. 36852 36853@subsubheading Example 36854 36855When run on a @sc{gnu}/Linux system, the output will look something 36856like this: 36857 36858@smallexample 36859(@value{GDBP}) 36860-info-os 36861^done,OSDataTable=@{nr_rows="10",nr_cols="3", 36862hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="Type"@}, 36863 @{width="10",alignment="-1",col_name="col1",colhdr="Description"@}, 36864 @{width="10",alignment="-1",col_name="col2",colhdr="Title"@}], 36865body=[item=@{col0="cpus",col1="Listing of all cpus/cores on the system", 36866 col2="CPUs"@}, 36867 item=@{col0="files",col1="Listing of all file descriptors", 36868 col2="File descriptors"@}, 36869 item=@{col0="modules",col1="Listing of all loaded kernel modules", 36870 col2="Kernel modules"@}, 36871 item=@{col0="msg",col1="Listing of all message queues", 36872 col2="Message queues"@}, 36873 item=@{col0="processes",col1="Listing of all processes", 36874 col2="Processes"@}, 36875 item=@{col0="procgroups",col1="Listing of all process groups", 36876 col2="Process groups"@}, 36877 item=@{col0="semaphores",col1="Listing of all semaphores", 36878 col2="Semaphores"@}, 36879 item=@{col0="shm",col1="Listing of all shared-memory regions", 36880 col2="Shared-memory regions"@}, 36881 item=@{col0="sockets",col1="Listing of all internet-domain sockets", 36882 col2="Sockets"@}, 36883 item=@{col0="threads",col1="Listing of all threads", 36884 col2="Threads"@}] 36885(@value{GDBP}) 36886-info-os processes 36887^done,OSDataTable=@{nr_rows="190",nr_cols="4", 36888hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="pid"@}, 36889 @{width="10",alignment="-1",col_name="col1",colhdr="user"@}, 36890 @{width="10",alignment="-1",col_name="col2",colhdr="command"@}, 36891 @{width="10",alignment="-1",col_name="col3",colhdr="cores"@}], 36892body=[item=@{col0="1",col1="root",col2="/sbin/init",col3="0"@}, 36893 item=@{col0="2",col1="root",col2="[kthreadd]",col3="1"@}, 36894 item=@{col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"@}, 36895 ... 36896 item=@{col0="26446",col1="stan",col2="bash",col3="0"@}, 36897 item=@{col0="28152",col1="stan",col2="bash",col3="1"@}]@} 36898(@value{GDBP}) 36899@end smallexample 36900 36901(Note that the MI output here includes a @code{"Title"} column that 36902does not appear in command-line @code{info os}; this column is useful 36903for MI clients that want to enumerate the types of data, such as in a 36904popup menu, but is needless clutter on the command line, and 36905@code{info os} omits it.) 36906 36907@subheading The @code{-add-inferior} Command 36908@findex -add-inferior 36909 36910@subheading Synopsis 36911 36912@smallexample 36913-add-inferior 36914@end smallexample 36915 36916Creates a new inferior (@pxref{Inferiors Connections and Programs}). The created 36917inferior is not associated with any executable. Such association may 36918be established with the @samp{-file-exec-and-symbols} command 36919(@pxref{GDB/MI File Commands}). The command response has a single 36920field, @samp{inferior}, whose value is the identifier of the 36921thread group corresponding to the new inferior. 36922 36923@subheading Example 36924 36925@smallexample 36926(@value{GDBP}) 36927-add-inferior 36928^done,inferior="i3" 36929@end smallexample 36930 36931@subheading The @code{-interpreter-exec} Command 36932@findex -interpreter-exec 36933 36934@subheading Synopsis 36935 36936@smallexample 36937-interpreter-exec @var{interpreter} @var{command} 36938@end smallexample 36939@anchor{-interpreter-exec} 36940 36941Execute the specified @var{command} in the given @var{interpreter}. 36942 36943@subheading @value{GDBN} Command 36944 36945The corresponding @value{GDBN} command is @samp{interpreter-exec}. 36946 36947@subheading Example 36948 36949@smallexample 36950(gdb) 36951-interpreter-exec console "break main" 36952&"During symbol reading, couldn't parse type; debugger out of date?.\n" 36953&"During symbol reading, bad structure-type format.\n" 36954~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" 36955^done 36956(gdb) 36957@end smallexample 36958 36959@subheading The @code{-inferior-tty-set} Command 36960@findex -inferior-tty-set 36961 36962@subheading Synopsis 36963 36964@smallexample 36965-inferior-tty-set /dev/pts/1 36966@end smallexample 36967 36968Set terminal for future runs of the program being debugged. 36969 36970@subheading @value{GDBN} Command 36971 36972The corresponding @value{GDBN} command is @samp{set inferior-tty} /dev/pts/1. 36973 36974@subheading Example 36975 36976@smallexample 36977(gdb) 36978-inferior-tty-set /dev/pts/1 36979^done 36980(gdb) 36981@end smallexample 36982 36983@subheading The @code{-inferior-tty-show} Command 36984@findex -inferior-tty-show 36985 36986@subheading Synopsis 36987 36988@smallexample 36989-inferior-tty-show 36990@end smallexample 36991 36992Show terminal for future runs of program being debugged. 36993 36994@subheading @value{GDBN} Command 36995 36996The corresponding @value{GDBN} command is @samp{show inferior-tty}. 36997 36998@subheading Example 36999 37000@smallexample 37001(gdb) 37002-inferior-tty-set /dev/pts/1 37003^done 37004(gdb) 37005-inferior-tty-show 37006^done,inferior_tty_terminal="/dev/pts/1" 37007(gdb) 37008@end smallexample 37009 37010@subheading The @code{-enable-timings} Command 37011@findex -enable-timings 37012 37013@subheading Synopsis 37014 37015@smallexample 37016-enable-timings [yes | no] 37017@end smallexample 37018 37019Toggle the printing of the wallclock, user and system times for an MI 37020command as a field in its output. This command is to help frontend 37021developers optimize the performance of their code. No argument is 37022equivalent to @samp{yes}. 37023 37024@subheading @value{GDBN} Command 37025 37026No equivalent. 37027 37028@subheading Example 37029 37030@smallexample 37031(gdb) 37032-enable-timings 37033^done 37034(gdb) 37035-break-insert main 37036^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 37037addr="0x080484ed",func="main",file="myprog.c", 37038fullname="/home/nickrob/myprog.c",line="73",thread-groups=["i1"], 37039times="0"@}, 37040time=@{wallclock="0.05185",user="0.00800",system="0.00000"@} 37041(gdb) 37042-enable-timings no 37043^done 37044(gdb) 37045-exec-run 37046^running 37047(gdb) 37048*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", 37049frame=@{addr="0x080484ed",func="main",args=[@{name="argc",value="1"@}, 37050@{name="argv",value="0xbfb60364"@}],file="myprog.c", 37051fullname="/home/nickrob/myprog.c",line="73",arch="i386:x86_64"@} 37052(gdb) 37053@end smallexample 37054 37055@subheading The @code{-complete} Command 37056@findex -complete 37057 37058@subheading Synopsis 37059 37060@smallexample 37061-complete @var{command} 37062@end smallexample 37063 37064Show a list of completions for partially typed CLI @var{command}. 37065 37066This command is intended for @sc{gdb/mi} frontends that cannot use two separate 37067CLI and MI channels --- for example: because of lack of PTYs like on Windows or 37068because @value{GDBN} is used remotely via a SSH connection. 37069 37070@subheading Result 37071 37072The result consists of two or three fields: 37073 37074@table @samp 37075@item completion 37076This field contains the completed @var{command}. If @var{command} 37077has no known completions, this field is omitted. 37078 37079@item matches 37080This field contains a (possibly empty) array of matches. It is always present. 37081 37082@item max_completions_reached 37083This field contains @code{1} if number of known completions is above 37084@code{max-completions} limit (@pxref{Completion}), otherwise it contains 37085@code{0}. It is always present. 37086 37087@end table 37088 37089@subheading @value{GDBN} Command 37090 37091The corresponding @value{GDBN} command is @samp{complete}. 37092 37093@subheading Example 37094 37095@smallexample 37096(gdb) 37097-complete br 37098^done,completion="break", 37099 matches=["break","break-range"], 37100 max_completions_reached="0" 37101(gdb) 37102-complete "b ma" 37103^done,completion="b ma", 37104 matches=["b madvise","b main"],max_completions_reached="0" 37105(gdb) 37106-complete "b push_b" 37107^done,completion="b push_back(", 37108 matches=[ 37109 "b A::push_back(void*)", 37110 "b std::string::push_back(char)", 37111 "b std::vector<int, std::allocator<int> >::push_back(int&&)"], 37112 max_completions_reached="0" 37113(gdb) 37114-complete "nonexist" 37115^done,matches=[],max_completions_reached="0" 37116(gdb) 37117 37118@end smallexample 37119 37120@node Annotations 37121@chapter @value{GDBN} Annotations 37122 37123This chapter describes annotations in @value{GDBN}. Annotations were 37124designed to interface @value{GDBN} to graphical user interfaces or other 37125similar programs which want to interact with @value{GDBN} at a 37126relatively high level. 37127 37128The annotation mechanism has largely been superseded by @sc{gdb/mi} 37129(@pxref{GDB/MI}). 37130 37131@ignore 37132This is Edition @value{EDITION}, @value{DATE}. 37133@end ignore 37134 37135@menu 37136* Annotations Overview:: What annotations are; the general syntax. 37137* Server Prefix:: Issuing a command without affecting user state. 37138* Prompting:: Annotations marking @value{GDBN}'s need for input. 37139* Errors:: Annotations for error messages. 37140* Invalidation:: Some annotations describe things now invalid. 37141* Annotations for Running:: 37142 Whether the program is running, how it stopped, etc. 37143* Source Annotations:: Annotations describing source code. 37144@end menu 37145 37146@node Annotations Overview 37147@section What is an Annotation? 37148@cindex annotations 37149 37150Annotations start with a newline character, two @samp{control-z} 37151characters, and the name of the annotation. If there is no additional 37152information associated with this annotation, the name of the annotation 37153is followed immediately by a newline. If there is additional 37154information, the name of the annotation is followed by a space, the 37155additional information, and a newline. The additional information 37156cannot contain newline characters. 37157 37158Any output not beginning with a newline and two @samp{control-z} 37159characters denotes literal output from @value{GDBN}. Currently there is 37160no need for @value{GDBN} to output a newline followed by two 37161@samp{control-z} characters, but if there was such a need, the 37162annotations could be extended with an @samp{escape} annotation which 37163means those three characters as output. 37164 37165The annotation @var{level}, which is specified using the 37166@option{--annotate} command line option (@pxref{Mode Options}), controls 37167how much information @value{GDBN} prints together with its prompt, 37168values of expressions, source lines, and other types of output. Level 0 37169is for no annotations, level 1 is for use when @value{GDBN} is run as a 37170subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable 37171for programs that control @value{GDBN}, and level 2 annotations have 37172been made obsolete (@pxref{Limitations, , Limitations of the Annotation 37173Interface, annotate, GDB's Obsolete Annotations}). 37174 37175@table @code 37176@kindex set annotate 37177@item set annotate @var{level} 37178The @value{GDBN} command @code{set annotate} sets the level of 37179annotations to the specified @var{level}. 37180 37181@item show annotate 37182@kindex show annotate 37183Show the current annotation level. 37184@end table 37185 37186This chapter describes level 3 annotations. 37187 37188A simple example of starting up @value{GDBN} with annotations is: 37189 37190@smallexample 37191$ @kbd{gdb --annotate=3} 37192GNU gdb 6.0 37193Copyright 2003 Free Software Foundation, Inc. 37194GDB is free software, covered by the GNU General Public License, 37195and you are welcome to change it and/or distribute copies of it 37196under certain conditions. 37197Type "show copying" to see the conditions. 37198There is absolutely no warranty for GDB. Type "show warranty" 37199for details. 37200This GDB was configured as "i386-pc-linux-gnu" 37201 37202^Z^Zpre-prompt 37203(@value{GDBP}) 37204^Z^Zprompt 37205@kbd{quit} 37206 37207^Z^Zpost-prompt 37208$ 37209@end smallexample 37210 37211Here @samp{quit} is input to @value{GDBN}; the rest is output from 37212@value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z} 37213denotes a @samp{control-z} character) are annotations; the rest is 37214output from @value{GDBN}. 37215 37216@node Server Prefix 37217@section The Server Prefix 37218@cindex server prefix 37219 37220If you prefix a command with @samp{server } then it will not affect 37221the command history, nor will it affect @value{GDBN}'s notion of which 37222command to repeat if @key{RET} is pressed on a line by itself. This 37223means that commands can be run behind a user's back by a front-end in 37224a transparent manner. 37225 37226The @code{server } prefix does not affect the recording of values into 37227the value history; to print a value without recording it into the 37228value history, use the @code{output} command instead of the 37229@code{print} command. 37230 37231Using this prefix also disables confirmation requests 37232(@pxref{confirmation requests}). 37233 37234@node Prompting 37235@section Annotation for @value{GDBN} Input 37236 37237@cindex annotations for prompts 37238When @value{GDBN} prompts for input, it annotates this fact so it is possible 37239to know when to send output, when the output from a given command is 37240over, etc. 37241 37242Different kinds of input each have a different @dfn{input type}. Each 37243input type has three annotations: a @code{pre-} annotation, which 37244denotes the beginning of any prompt which is being output, a plain 37245annotation, which denotes the end of the prompt, and then a @code{post-} 37246annotation which denotes the end of any echo which may (or may not) be 37247associated with the input. For example, the @code{prompt} input type 37248features the following annotations: 37249 37250@smallexample 37251^Z^Zpre-prompt 37252^Z^Zprompt 37253^Z^Zpost-prompt 37254@end smallexample 37255 37256The input types are 37257 37258@table @code 37259@findex pre-prompt annotation 37260@findex prompt annotation 37261@findex post-prompt annotation 37262@item prompt 37263When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt). 37264 37265@findex pre-commands annotation 37266@findex commands annotation 37267@findex post-commands annotation 37268@item commands 37269When @value{GDBN} prompts for a set of commands, like in the @code{commands} 37270command. The annotations are repeated for each command which is input. 37271 37272@findex pre-overload-choice annotation 37273@findex overload-choice annotation 37274@findex post-overload-choice annotation 37275@item overload-choice 37276When @value{GDBN} wants the user to select between various overloaded functions. 37277 37278@findex pre-query annotation 37279@findex query annotation 37280@findex post-query annotation 37281@item query 37282When @value{GDBN} wants the user to confirm a potentially dangerous operation. 37283 37284@findex pre-prompt-for-continue annotation 37285@findex prompt-for-continue annotation 37286@findex post-prompt-for-continue annotation 37287@item prompt-for-continue 37288When @value{GDBN} is asking the user to press return to continue. Note: Don't 37289expect this to work well; instead use @code{set height 0} to disable 37290prompting. This is because the counting of lines is buggy in the 37291presence of annotations. 37292@end table 37293 37294@node Errors 37295@section Errors 37296@cindex annotations for errors, warnings and interrupts 37297 37298@findex quit annotation 37299@smallexample 37300^Z^Zquit 37301@end smallexample 37302 37303This annotation occurs right before @value{GDBN} responds to an interrupt. 37304 37305@findex error annotation 37306@smallexample 37307^Z^Zerror 37308@end smallexample 37309 37310This annotation occurs right before @value{GDBN} responds to an error. 37311 37312Quit and error annotations indicate that any annotations which @value{GDBN} was 37313in the middle of may end abruptly. For example, if a 37314@code{value-history-begin} annotation is followed by a @code{error}, one 37315cannot expect to receive the matching @code{value-history-end}. One 37316cannot expect not to receive it either, however; an error annotation 37317does not necessarily mean that @value{GDBN} is immediately returning all the way 37318to the top level. 37319 37320@findex error-begin annotation 37321A quit or error annotation may be preceded by 37322 37323@smallexample 37324^Z^Zerror-begin 37325@end smallexample 37326 37327Any output between that and the quit or error annotation is the error 37328message. 37329 37330Warning messages are not yet annotated. 37331@c If we want to change that, need to fix warning(), type_error(), 37332@c range_error(), and possibly other places. 37333 37334@node Invalidation 37335@section Invalidation Notices 37336 37337@cindex annotations for invalidation messages 37338The following annotations say that certain pieces of state may have 37339changed. 37340 37341@table @code 37342@findex frames-invalid annotation 37343@item ^Z^Zframes-invalid 37344 37345The frames (for example, output from the @code{backtrace} command) may 37346have changed. 37347 37348@findex breakpoints-invalid annotation 37349@item ^Z^Zbreakpoints-invalid 37350 37351The breakpoints may have changed. For example, the user just added or 37352deleted a breakpoint. 37353@end table 37354 37355@node Annotations for Running 37356@section Running the Program 37357@cindex annotations for running programs 37358 37359@findex starting annotation 37360@findex stopping annotation 37361When the program starts executing due to a @value{GDBN} command such as 37362@code{step} or @code{continue}, 37363 37364@smallexample 37365^Z^Zstarting 37366@end smallexample 37367 37368is output. When the program stops, 37369 37370@smallexample 37371^Z^Zstopped 37372@end smallexample 37373 37374is output. Before the @code{stopped} annotation, a variety of 37375annotations describe how the program stopped. 37376 37377@table @code 37378@findex exited annotation 37379@item ^Z^Zexited @var{exit-status} 37380The program exited, and @var{exit-status} is the exit status (zero for 37381successful exit, otherwise nonzero). 37382 37383@findex signalled annotation 37384@findex signal-name annotation 37385@findex signal-name-end annotation 37386@findex signal-string annotation 37387@findex signal-string-end annotation 37388@item ^Z^Zsignalled 37389The program exited with a signal. After the @code{^Z^Zsignalled}, the 37390annotation continues: 37391 37392@smallexample 37393@var{intro-text} 37394^Z^Zsignal-name 37395@var{name} 37396^Z^Zsignal-name-end 37397@var{middle-text} 37398^Z^Zsignal-string 37399@var{string} 37400^Z^Zsignal-string-end 37401@var{end-text} 37402@end smallexample 37403 37404@noindent 37405where @var{name} is the name of the signal, such as @code{SIGILL} or 37406@code{SIGSEGV}, and @var{string} is the explanation of the signal, such 37407as @code{Illegal Instruction} or @code{Segmentation fault}. The arguments 37408@var{intro-text}, @var{middle-text}, and @var{end-text} are for the 37409user's benefit and have no particular format. 37410 37411@findex signal annotation 37412@item ^Z^Zsignal 37413The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is 37414just saying that the program received the signal, not that it was 37415terminated with it. 37416 37417@findex breakpoint annotation 37418@item ^Z^Zbreakpoint @var{number} 37419The program hit breakpoint number @var{number}. 37420 37421@findex watchpoint annotation 37422@item ^Z^Zwatchpoint @var{number} 37423The program hit watchpoint number @var{number}. 37424@end table 37425 37426@node Source Annotations 37427@section Displaying Source 37428@cindex annotations for source display 37429 37430@findex source annotation 37431The following annotation is used instead of displaying source code: 37432 37433@smallexample 37434^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr} 37435@end smallexample 37436 37437where @var{filename} is an absolute file name indicating which source 37438file, @var{line} is the line number within that file (where 1 is the 37439first line in the file), @var{character} is the character position 37440within the file (where 0 is the first character in the file) (for most 37441debug formats this will necessarily point to the beginning of a line), 37442@var{middle} is @samp{middle} if @var{addr} is in the middle of the 37443line, or @samp{beg} if @var{addr} is at the beginning of the line, and 37444@var{addr} is the address in the target program associated with the 37445source which is being displayed. The @var{addr} is in the form @samp{0x} 37446followed by one or more lowercase hex digits (note that this does not 37447depend on the language). 37448 37449@node JIT Interface 37450@chapter JIT Compilation Interface 37451@cindex just-in-time compilation 37452@cindex JIT compilation interface 37453 37454This chapter documents @value{GDBN}'s @dfn{just-in-time} (JIT) compilation 37455interface. A JIT compiler is a program or library that generates native 37456executable code at runtime and executes it, usually in order to achieve good 37457performance while maintaining platform independence. 37458 37459Programs that use JIT compilation are normally difficult to debug because 37460portions of their code are generated at runtime, instead of being loaded from 37461object files, which is where @value{GDBN} normally finds the program's symbols 37462and debug information. In order to debug programs that use JIT compilation, 37463@value{GDBN} has an interface that allows the program to register in-memory 37464symbol files with @value{GDBN} at runtime. 37465 37466If you are using @value{GDBN} to debug a program that uses this interface, then 37467it should work transparently so long as you have not stripped the binary. If 37468you are developing a JIT compiler, then the interface is documented in the rest 37469of this chapter. At this time, the only known client of this interface is the 37470LLVM JIT. 37471 37472Broadly speaking, the JIT interface mirrors the dynamic loader interface. The 37473JIT compiler communicates with @value{GDBN} by writing data into a global 37474variable and calling a function at a well-known symbol. When @value{GDBN} 37475attaches, it reads a linked list of symbol files from the global variable to 37476find existing code, and puts a breakpoint in the function so that it can find 37477out about additional code. 37478 37479@menu 37480* Declarations:: Relevant C struct declarations 37481* Registering Code:: Steps to register code 37482* Unregistering Code:: Steps to unregister code 37483* Custom Debug Info:: Emit debug information in a custom format 37484@end menu 37485 37486@node Declarations 37487@section JIT Declarations 37488 37489These are the relevant struct declarations that a C program should include to 37490implement the interface: 37491 37492@smallexample 37493typedef enum 37494@{ 37495 JIT_NOACTION = 0, 37496 JIT_REGISTER_FN, 37497 JIT_UNREGISTER_FN 37498@} jit_actions_t; 37499 37500struct jit_code_entry 37501@{ 37502 struct jit_code_entry *next_entry; 37503 struct jit_code_entry *prev_entry; 37504 const char *symfile_addr; 37505 uint64_t symfile_size; 37506@}; 37507 37508struct jit_descriptor 37509@{ 37510 uint32_t version; 37511 /* This type should be jit_actions_t, but we use uint32_t 37512 to be explicit about the bitwidth. */ 37513 uint32_t action_flag; 37514 struct jit_code_entry *relevant_entry; 37515 struct jit_code_entry *first_entry; 37516@}; 37517 37518/* GDB puts a breakpoint in this function. */ 37519void __attribute__((noinline)) __jit_debug_register_code() @{ @}; 37520 37521/* Make sure to specify the version statically, because the 37522 debugger may check the version before we can set it. */ 37523struct jit_descriptor __jit_debug_descriptor = @{ 1, 0, 0, 0 @}; 37524@end smallexample 37525 37526If the JIT is multi-threaded, then it is important that the JIT synchronize any 37527modifications to this global data properly, which can easily be done by putting 37528a global mutex around modifications to these structures. 37529 37530@node Registering Code 37531@section Registering Code 37532 37533To register code with @value{GDBN}, the JIT should follow this protocol: 37534 37535@itemize @bullet 37536@item 37537Generate an object file in memory with symbols and other desired debug 37538information. The file must include the virtual addresses of the sections. 37539 37540@item 37541Create a code entry for the file, which gives the start and size of the symbol 37542file. 37543 37544@item 37545Add it to the linked list in the JIT descriptor. 37546 37547@item 37548Point the relevant_entry field of the descriptor at the entry. 37549 37550@item 37551Set @code{action_flag} to @code{JIT_REGISTER} and call 37552@code{__jit_debug_register_code}. 37553@end itemize 37554 37555When @value{GDBN} is attached and the breakpoint fires, @value{GDBN} uses the 37556@code{relevant_entry} pointer so it doesn't have to walk the list looking for 37557new code. However, the linked list must still be maintained in order to allow 37558@value{GDBN} to attach to a running process and still find the symbol files. 37559 37560@node Unregistering Code 37561@section Unregistering Code 37562 37563If code is freed, then the JIT should use the following protocol: 37564 37565@itemize @bullet 37566@item 37567Remove the code entry corresponding to the code from the linked list. 37568 37569@item 37570Point the @code{relevant_entry} field of the descriptor at the code entry. 37571 37572@item 37573Set @code{action_flag} to @code{JIT_UNREGISTER} and call 37574@code{__jit_debug_register_code}. 37575@end itemize 37576 37577If the JIT frees or recompiles code without unregistering it, then @value{GDBN} 37578and the JIT will leak the memory used for the associated symbol files. 37579 37580@node Custom Debug Info 37581@section Custom Debug Info 37582@cindex custom JIT debug info 37583@cindex JIT debug info reader 37584 37585Generating debug information in platform-native file formats (like ELF 37586or COFF) may be an overkill for JIT compilers; especially if all the 37587debug info is used for is displaying a meaningful backtrace. The 37588issue can be resolved by having the JIT writers decide on a debug info 37589format and also provide a reader that parses the debug info generated 37590by the JIT compiler. This section gives a brief overview on writing 37591such a parser. More specific details can be found in the source file 37592@file{gdb/jit-reader.in}, which is also installed as a header at 37593@file{@var{includedir}/gdb/jit-reader.h} for easy inclusion. 37594 37595The reader is implemented as a shared object (so this functionality is 37596not available on platforms which don't allow loading shared objects at 37597runtime). Two @value{GDBN} commands, @code{jit-reader-load} and 37598@code{jit-reader-unload} are provided, to be used to load and unload 37599the readers from a preconfigured directory. Once loaded, the shared 37600object is used the parse the debug information emitted by the JIT 37601compiler. 37602 37603@menu 37604* Using JIT Debug Info Readers:: How to use supplied readers correctly 37605* Writing JIT Debug Info Readers:: Creating a debug-info reader 37606@end menu 37607 37608@node Using JIT Debug Info Readers 37609@subsection Using JIT Debug Info Readers 37610@kindex jit-reader-load 37611@kindex jit-reader-unload 37612 37613Readers can be loaded and unloaded using the @code{jit-reader-load} 37614and @code{jit-reader-unload} commands. 37615 37616@table @code 37617@item jit-reader-load @var{reader} 37618Load the JIT reader named @var{reader}, which is a shared 37619object specified as either an absolute or a relative file name. In 37620the latter case, @value{GDBN} will try to load the reader from a 37621pre-configured directory, usually @file{@var{libdir}/gdb/} on a UNIX 37622system (here @var{libdir} is the system library directory, often 37623@file{/usr/local/lib}). 37624 37625Only one reader can be active at a time; trying to load a second 37626reader when one is already loaded will result in @value{GDBN} 37627reporting an error. A new JIT reader can be loaded by first unloading 37628the current one using @code{jit-reader-unload} and then invoking 37629@code{jit-reader-load}. 37630 37631@item jit-reader-unload 37632Unload the currently loaded JIT reader. 37633 37634@end table 37635 37636@node Writing JIT Debug Info Readers 37637@subsection Writing JIT Debug Info Readers 37638@cindex writing JIT debug info readers 37639 37640As mentioned, a reader is essentially a shared object conforming to a 37641certain ABI. This ABI is described in @file{jit-reader.h}. 37642 37643@file{jit-reader.h} defines the structures, macros and functions 37644required to write a reader. It is installed (along with 37645@value{GDBN}), in @file{@var{includedir}/gdb} where @var{includedir} is 37646the system include directory. 37647 37648Readers need to be released under a GPL compatible license. A reader 37649can be declared as released under such a license by placing the macro 37650@code{GDB_DECLARE_GPL_COMPATIBLE_READER} in a source file. 37651 37652The entry point for readers is the symbol @code{gdb_init_reader}, 37653which is expected to be a function with the prototype 37654 37655@findex gdb_init_reader 37656@smallexample 37657extern struct gdb_reader_funcs *gdb_init_reader (void); 37658@end smallexample 37659 37660@cindex @code{struct gdb_reader_funcs} 37661 37662@code{struct gdb_reader_funcs} contains a set of pointers to callback 37663functions. These functions are executed to read the debug info 37664generated by the JIT compiler (@code{read}), to unwind stack frames 37665(@code{unwind}) and to create canonical frame IDs 37666(@code{get_frame_id}). It also has a callback that is called when the 37667reader is being unloaded (@code{destroy}). The struct looks like this 37668 37669@smallexample 37670struct gdb_reader_funcs 37671@{ 37672 /* Must be set to GDB_READER_INTERFACE_VERSION. */ 37673 int reader_version; 37674 37675 /* For use by the reader. */ 37676 void *priv_data; 37677 37678 gdb_read_debug_info *read; 37679 gdb_unwind_frame *unwind; 37680 gdb_get_frame_id *get_frame_id; 37681 gdb_destroy_reader *destroy; 37682@}; 37683@end smallexample 37684 37685@cindex @code{struct gdb_symbol_callbacks} 37686@cindex @code{struct gdb_unwind_callbacks} 37687 37688The callbacks are provided with another set of callbacks by 37689@value{GDBN} to do their job. For @code{read}, these callbacks are 37690passed in a @code{struct gdb_symbol_callbacks} and for @code{unwind} 37691and @code{get_frame_id}, in a @code{struct gdb_unwind_callbacks}. 37692@code{struct gdb_symbol_callbacks} has callbacks to create new object 37693files and new symbol tables inside those object files. @code{struct 37694gdb_unwind_callbacks} has callbacks to read registers off the current 37695frame and to write out the values of the registers in the previous 37696frame. Both have a callback (@code{target_read}) to read bytes off the 37697target's address space. 37698 37699@node In-Process Agent 37700@chapter In-Process Agent 37701@cindex debugging agent 37702The traditional debugging model is conceptually low-speed, but works fine, 37703because most bugs can be reproduced in debugging-mode execution. However, 37704as multi-core or many-core processors are becoming mainstream, and 37705multi-threaded programs become more and more popular, there should be more 37706and more bugs that only manifest themselves at normal-mode execution, for 37707example, thread races, because debugger's interference with the program's 37708timing may conceal the bugs. On the other hand, in some applications, 37709it is not feasible for the debugger to interrupt the program's execution 37710long enough for the developer to learn anything helpful about its behavior. 37711If the program's correctness depends on its real-time behavior, delays 37712introduced by a debugger might cause the program to fail, even when the 37713code itself is correct. It is useful to be able to observe the program's 37714behavior without interrupting it. 37715 37716Therefore, traditional debugging model is too intrusive to reproduce 37717some bugs. In order to reduce the interference with the program, we can 37718reduce the number of operations performed by debugger. The 37719@dfn{In-Process Agent}, a shared library, is running within the same 37720process with inferior, and is able to perform some debugging operations 37721itself. As a result, debugger is only involved when necessary, and 37722performance of debugging can be improved accordingly. Note that 37723interference with program can be reduced but can't be removed completely, 37724because the in-process agent will still stop or slow down the program. 37725 37726The in-process agent can interpret and execute Agent Expressions 37727(@pxref{Agent Expressions}) during performing debugging operations. The 37728agent expressions can be used for different purposes, such as collecting 37729data in tracepoints, and condition evaluation in breakpoints. 37730 37731@anchor{Control Agent} 37732You can control whether the in-process agent is used as an aid for 37733debugging with the following commands: 37734 37735@table @code 37736@kindex set agent on 37737@item set agent on 37738Causes the in-process agent to perform some operations on behalf of the 37739debugger. Just which operations requested by the user will be done 37740by the in-process agent depends on the its capabilities. For example, 37741if you request to evaluate breakpoint conditions in the in-process agent, 37742and the in-process agent has such capability as well, then breakpoint 37743conditions will be evaluated in the in-process agent. 37744 37745@kindex set agent off 37746@item set agent off 37747Disables execution of debugging operations by the in-process agent. All 37748of the operations will be performed by @value{GDBN}. 37749 37750@kindex show agent 37751@item show agent 37752Display the current setting of execution of debugging operations by 37753the in-process agent. 37754@end table 37755 37756@menu 37757* In-Process Agent Protocol:: 37758@end menu 37759 37760@node In-Process Agent Protocol 37761@section In-Process Agent Protocol 37762@cindex in-process agent protocol 37763 37764The in-process agent is able to communicate with both @value{GDBN} and 37765GDBserver (@pxref{In-Process Agent}). This section documents the protocol 37766used for communications between @value{GDBN} or GDBserver and the IPA. 37767In general, @value{GDBN} or GDBserver sends commands 37768(@pxref{IPA Protocol Commands}) and data to in-process agent, and then 37769in-process agent replies back with the return result of the command, or 37770some other information. The data sent to in-process agent is composed 37771of primitive data types, such as 4-byte or 8-byte type, and composite 37772types, which are called objects (@pxref{IPA Protocol Objects}). 37773 37774@menu 37775* IPA Protocol Objects:: 37776* IPA Protocol Commands:: 37777@end menu 37778 37779@node IPA Protocol Objects 37780@subsection IPA Protocol Objects 37781@cindex ipa protocol objects 37782 37783The commands sent to and results received from agent may contain some 37784complex data types called @dfn{objects}. 37785 37786The in-process agent is running on the same machine with @value{GDBN} 37787or GDBserver, so it doesn't have to handle as much differences between 37788two ends as remote protocol (@pxref{Remote Protocol}) tries to handle. 37789However, there are still some differences of two ends in two processes: 37790 37791@enumerate 37792@item 37793word size. On some 64-bit machines, @value{GDBN} or GDBserver can be 37794compiled as a 64-bit executable, while in-process agent is a 32-bit one. 37795@item 37796ABI. Some machines may have multiple types of ABI, @value{GDBN} or 37797GDBserver is compiled with one, and in-process agent is compiled with 37798the other one. 37799@end enumerate 37800 37801Here are the IPA Protocol Objects: 37802 37803@enumerate 37804@item 37805agent expression object. It represents an agent expression 37806(@pxref{Agent Expressions}). 37807@anchor{agent expression object} 37808@item 37809tracepoint action object. It represents a tracepoint action 37810(@pxref{Tracepoint Actions,,Tracepoint Action Lists}) to collect registers, 37811memory, static trace data and to evaluate expression. 37812@anchor{tracepoint action object} 37813@item 37814tracepoint object. It represents a tracepoint (@pxref{Tracepoints}). 37815@anchor{tracepoint object} 37816 37817@end enumerate 37818 37819The following table describes important attributes of each IPA protocol 37820object: 37821 37822@multitable @columnfractions .30 .20 .50 37823@headitem Name @tab Size @tab Description 37824@item @emph{agent expression object} @tab @tab 37825@item length @tab 4 @tab length of bytes code 37826@item byte code @tab @var{length} @tab contents of byte code 37827@item @emph{tracepoint action for collecting memory} @tab @tab 37828@item 'M' @tab 1 @tab type of tracepoint action 37829@item addr @tab 8 @tab if @var{basereg} is @samp{-1}, @var{addr} is the 37830address of the lowest byte to collect, otherwise @var{addr} is the offset 37831of @var{basereg} for memory collecting. 37832@item len @tab 8 @tab length of memory for collecting 37833@item basereg @tab 4 @tab the register number containing the starting 37834memory address for collecting. 37835@item @emph{tracepoint action for collecting registers} @tab @tab 37836@item 'R' @tab 1 @tab type of tracepoint action 37837@item @emph{tracepoint action for collecting static trace data} @tab @tab 37838@item 'L' @tab 1 @tab type of tracepoint action 37839@item @emph{tracepoint action for expression evaluation} @tab @tab 37840@item 'X' @tab 1 @tab type of tracepoint action 37841@item agent expression @tab length of @tab @ref{agent expression object} 37842@item @emph{tracepoint object} @tab @tab 37843@item number @tab 4 @tab number of tracepoint 37844@item address @tab 8 @tab address of tracepoint inserted on 37845@item type @tab 4 @tab type of tracepoint 37846@item enabled @tab 1 @tab enable or disable of tracepoint 37847@item step_count @tab 8 @tab step 37848@item pass_count @tab 8 @tab pass 37849@item numactions @tab 4 @tab number of tracepoint actions 37850@item hit count @tab 8 @tab hit count 37851@item trace frame usage @tab 8 @tab trace frame usage 37852@item compiled_cond @tab 8 @tab compiled condition 37853@item orig_size @tab 8 @tab orig size 37854@item condition @tab 4 if condition is NULL otherwise length of 37855@ref{agent expression object} 37856@tab zero if condition is NULL, otherwise is 37857@ref{agent expression object} 37858@item actions @tab variable 37859@tab numactions number of @ref{tracepoint action object} 37860@end multitable 37861 37862@node IPA Protocol Commands 37863@subsection IPA Protocol Commands 37864@cindex ipa protocol commands 37865 37866The spaces in each command are delimiters to ease reading this commands 37867specification. They don't exist in real commands. 37868 37869@table @samp 37870 37871@item FastTrace:@var{tracepoint_object} @var{gdb_jump_pad_head} 37872Installs a new fast tracepoint described by @var{tracepoint_object} 37873(@pxref{tracepoint object}). The @var{gdb_jump_pad_head}, 8-byte long, is the 37874head of @dfn{jumppad}, which is used to jump to data collection routine 37875in IPA finally. 37876 37877Replies: 37878@table @samp 37879@item OK @var{target_address} @var{gdb_jump_pad_head} @var{fjump_size} @var{fjump} 37880@var{target_address} is address of tracepoint in the inferior. 37881The @var{gdb_jump_pad_head} is updated head of jumppad. Both of 37882@var{target_address} and @var{gdb_jump_pad_head} are 8-byte long. 37883The @var{fjump} contains a sequence of instructions jump to jumppad entry. 37884The @var{fjump_size}, 4-byte long, is the size of @var{fjump}. 37885@item E @var{NN} 37886for an error 37887 37888@end table 37889 37890@item close 37891Closes the in-process agent. This command is sent when @value{GDBN} or GDBserver 37892is about to kill inferiors. 37893 37894@item qTfSTM 37895@xref{qTfSTM}. 37896@item qTsSTM 37897@xref{qTsSTM}. 37898@item qTSTMat 37899@xref{qTSTMat}. 37900@item probe_marker_at:@var{address} 37901Asks in-process agent to probe the marker at @var{address}. 37902 37903Replies: 37904@table @samp 37905@item E @var{NN} 37906for an error 37907@end table 37908@item unprobe_marker_at:@var{address} 37909Asks in-process agent to unprobe the marker at @var{address}. 37910@end table 37911 37912@node GDB Bugs 37913@chapter Reporting Bugs in @value{GDBN} 37914@cindex bugs in @value{GDBN} 37915@cindex reporting bugs in @value{GDBN} 37916 37917Your bug reports play an essential role in making @value{GDBN} reliable. 37918 37919Reporting a bug may help you by bringing a solution to your problem, or it 37920may not. But in any case the principal function of a bug report is to help 37921the entire community by making the next version of @value{GDBN} work better. Bug 37922reports are your contribution to the maintenance of @value{GDBN}. 37923 37924In order for a bug report to serve its purpose, you must include the 37925information that enables us to fix the bug. 37926 37927@menu 37928* Bug Criteria:: Have you found a bug? 37929* Bug Reporting:: How to report bugs 37930@end menu 37931 37932@node Bug Criteria 37933@section Have You Found a Bug? 37934@cindex bug criteria 37935 37936If you are not sure whether you have found a bug, here are some guidelines: 37937 37938@itemize @bullet 37939@cindex fatal signal 37940@cindex debugger crash 37941@cindex crash of debugger 37942@item 37943If the debugger gets a fatal signal, for any input whatever, that is a 37944@value{GDBN} bug. Reliable debuggers never crash. 37945 37946@cindex error on valid input 37947@item 37948If @value{GDBN} produces an error message for valid input, that is a 37949bug. (Note that if you're cross debugging, the problem may also be 37950somewhere in the connection to the target.) 37951 37952@cindex invalid input 37953@item 37954If @value{GDBN} does not produce an error message for invalid input, 37955that is a bug. However, you should note that your idea of 37956``invalid input'' might be our idea of ``an extension'' or ``support 37957for traditional practice''. 37958 37959@item 37960If you are an experienced user of debugging tools, your suggestions 37961for improvement of @value{GDBN} are welcome in any case. 37962@end itemize 37963 37964@node Bug Reporting 37965@section How to Report Bugs 37966@cindex bug reports 37967@cindex @value{GDBN} bugs, reporting 37968 37969A number of companies and individuals offer support for @sc{gnu} products. 37970If you obtained @value{GDBN} from a support organization, we recommend you 37971contact that organization first. 37972 37973You can find contact information for many support companies and 37974individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs 37975distribution. 37976@c should add a web page ref... 37977 37978@ifset BUGURL 37979@ifset BUGURL_DEFAULT 37980In any event, we also recommend that you submit bug reports for 37981@value{GDBN}. The preferred method is to submit them directly using 37982@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web 37983page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can 37984be used. 37985 37986@strong{Do not send bug reports to @samp{info-gdb}, or to 37987@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do 37988not want to receive bug reports. Those that do have arranged to receive 37989@samp{bug-gdb}. 37990 37991The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which 37992serves as a repeater. The mailing list and the newsgroup carry exactly 37993the same messages. Often people think of posting bug reports to the 37994newsgroup instead of mailing them. This appears to work, but it has one 37995problem which can be crucial: a newsgroup posting often lacks a mail 37996path back to the sender. Thus, if we need to ask for more information, 37997we may be unable to reach you. For this reason, it is better to send 37998bug reports to the mailing list. 37999@end ifset 38000@ifclear BUGURL_DEFAULT 38001In any event, we also recommend that you submit bug reports for 38002@value{GDBN} to @value{BUGURL}. 38003@end ifclear 38004@end ifset 38005 38006The fundamental principle of reporting bugs usefully is this: 38007@strong{report all the facts}. If you are not sure whether to state a 38008fact or leave it out, state it! 38009 38010Often people omit facts because they think they know what causes the 38011problem and assume that some details do not matter. Thus, you might 38012assume that the name of the variable you use in an example does not matter. 38013Well, probably it does not, but one cannot be sure. Perhaps the bug is a 38014stray memory reference which happens to fetch from the location where that 38015name is stored in memory; perhaps, if the name were different, the contents 38016of that location would fool the debugger into doing the right thing despite 38017the bug. Play it safe and give a specific, complete example. That is the 38018easiest thing for you to do, and the most helpful. 38019 38020Keep in mind that the purpose of a bug report is to enable us to fix the 38021bug. It may be that the bug has been reported previously, but neither 38022you nor we can know that unless your bug report is complete and 38023self-contained. 38024 38025Sometimes people give a few sketchy facts and ask, ``Does this ring a 38026bell?'' Those bug reports are useless, and we urge everyone to 38027@emph{refuse to respond to them} except to chide the sender to report 38028bugs properly. 38029 38030To enable us to fix the bug, you should include all these things: 38031 38032@itemize @bullet 38033@item 38034The version of @value{GDBN}. @value{GDBN} announces it if you start 38035with no arguments; you can also print it at any time using @code{show 38036version}. 38037 38038Without this, we will not know whether there is any point in looking for 38039the bug in the current version of @value{GDBN}. 38040 38041@item 38042The type of machine you are using, and the operating system name and 38043version number. 38044 38045@item 38046The details of the @value{GDBN} build-time configuration. 38047@value{GDBN} shows these details if you invoke it with the 38048@option{--configuration} command-line option, or if you type 38049@code{show configuration} at @value{GDBN}'s prompt. 38050 38051@item 38052What compiler (and its version) was used to compile @value{GDBN}---e.g.@: 38053``@value{GCC}--2.8.1''. 38054 38055@item 38056What compiler (and its version) was used to compile the program you are 38057debugging---e.g.@: ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP 38058C Compiler''. For @value{NGCC}, you can say @kbd{@value{GCC} --version} 38059to get this information; for other compilers, see the documentation for 38060those compilers. 38061 38062@item 38063The command arguments you gave the compiler to compile your example and 38064observe the bug. For example, did you use @samp{-O}? To guarantee 38065you will not omit something important, list them all. A copy of the 38066Makefile (or the output from make) is sufficient. 38067 38068If we were to try to guess the arguments, we would probably guess wrong 38069and then we might not encounter the bug. 38070 38071@item 38072A complete input script, and all necessary source files, that will 38073reproduce the bug. 38074 38075@item 38076A description of what behavior you observe that you believe is 38077incorrect. For example, ``It gets a fatal signal.'' 38078 38079Of course, if the bug is that @value{GDBN} gets a fatal signal, then we 38080will certainly notice it. But if the bug is incorrect output, we might 38081not notice unless it is glaringly wrong. You might as well not give us 38082a chance to make a mistake. 38083 38084Even if the problem you experience is a fatal signal, you should still 38085say so explicitly. Suppose something strange is going on, such as, your 38086copy of @value{GDBN} is out of synch, or you have encountered a bug in 38087the C library on your system. (This has happened!) Your copy might 38088crash and ours would not. If you told us to expect a crash, then when 38089ours fails to crash, we would know that the bug was not happening for 38090us. If you had not told us to expect a crash, then we would not be able 38091to draw any conclusion from our observations. 38092 38093@pindex script 38094@cindex recording a session script 38095To collect all this information, you can use a session recording program 38096such as @command{script}, which is available on many Unix systems. 38097Just run your @value{GDBN} session inside @command{script} and then 38098include the @file{typescript} file with your bug report. 38099 38100Another way to record a @value{GDBN} session is to run @value{GDBN} 38101inside Emacs and then save the entire buffer to a file. 38102 38103@item 38104If you wish to suggest changes to the @value{GDBN} source, send us context 38105diffs. If you even discuss something in the @value{GDBN} source, refer to 38106it by context, not by line number. 38107 38108The line numbers in our development sources will not match those in your 38109sources. Your line numbers would convey no useful information to us. 38110 38111@end itemize 38112 38113Here are some things that are not necessary: 38114 38115@itemize @bullet 38116@item 38117A description of the envelope of the bug. 38118 38119Often people who encounter a bug spend a lot of time investigating 38120which changes to the input file will make the bug go away and which 38121changes will not affect it. 38122 38123This is often time consuming and not very useful, because the way we 38124will find the bug is by running a single example under the debugger 38125with breakpoints, not by pure deduction from a series of examples. 38126We recommend that you save your time for something else. 38127 38128Of course, if you can find a simpler example to report @emph{instead} 38129of the original one, that is a convenience for us. Errors in the 38130output will be easier to spot, running under the debugger will take 38131less time, and so on. 38132 38133However, simplification is not vital; if you do not want to do this, 38134report the bug anyway and send us the entire test case you used. 38135 38136@item 38137A patch for the bug. 38138 38139A patch for the bug does help us if it is a good one. But do not omit 38140the necessary information, such as the test case, on the assumption that 38141a patch is all we need. We might see problems with your patch and decide 38142to fix the problem another way, or we might not understand it at all. 38143 38144Sometimes with a program as complicated as @value{GDBN} it is very hard to 38145construct an example that will make the program follow a certain path 38146through the code. If you do not send us the example, we will not be able 38147to construct one, so we will not be able to verify that the bug is fixed. 38148 38149And if we cannot understand what bug you are trying to fix, or why your 38150patch should be an improvement, we will not install it. A test case will 38151help us to understand. 38152 38153@item 38154A guess about what the bug is or what it depends on. 38155 38156Such guesses are usually wrong. Even we cannot guess right about such 38157things without first using the debugger to find the facts. 38158@end itemize 38159 38160@c The readline documentation is distributed with the readline code 38161@c and consists of the two following files: 38162@c rluser.texi 38163@c hsuser.texi 38164@c Use -I with makeinfo to point to the appropriate directory, 38165@c environment var TEXINPUTS with TeX. 38166@ifclear SYSTEM_READLINE 38167@include rluser.texi 38168@include hsuser.texi 38169@end ifclear 38170 38171@node In Memoriam 38172@appendix In Memoriam 38173 38174The @value{GDBN} project mourns the loss of the following long-time 38175contributors: 38176 38177@table @code 38178@item Fred Fish 38179Fred was a long-standing contributor to @value{GDBN} (1991-2006), and 38180to Free Software in general. Outside of @value{GDBN}, he was known in 38181the Amiga world for his series of Fish Disks, and the GeekGadget project. 38182 38183@item Michael Snyder 38184Michael was one of the Global Maintainers of the @value{GDBN} project, 38185with contributions recorded as early as 1996, until 2011. In addition 38186to his day to day participation, he was a large driving force behind 38187adding Reverse Debugging to @value{GDBN}. 38188@end table 38189 38190Beyond their technical contributions to the project, they were also 38191enjoyable members of the Free Software Community. We will miss them. 38192 38193@node Formatting Documentation 38194@appendix Formatting Documentation 38195 38196@cindex @value{GDBN} reference card 38197@cindex reference card 38198The @value{GDBN} 4 release includes an already-formatted reference card, ready 38199for printing with PostScript or Ghostscript, in the @file{gdb} 38200subdirectory of the main source directory@footnote{In 38201@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN} 38202release.}. If you can use PostScript or Ghostscript with your printer, 38203you can print the reference card immediately with @file{refcard.ps}. 38204 38205The release also includes the source for the reference card. You 38206can format it, using @TeX{}, by typing: 38207 38208@smallexample 38209make refcard.dvi 38210@end smallexample 38211 38212The @value{GDBN} reference card is designed to print in @dfn{landscape} 38213mode on US ``letter'' size paper; 38214that is, on a sheet 11 inches wide by 8.5 inches 38215high. You will need to specify this form of printing as an option to 38216your @sc{dvi} output program. 38217 38218@cindex documentation 38219 38220All the documentation for @value{GDBN} comes as part of the machine-readable 38221distribution. The documentation is written in Texinfo format, which is 38222a documentation system that uses a single source file to produce both 38223on-line information and a printed manual. You can use one of the Info 38224formatting commands to create the on-line version of the documentation 38225and @TeX{} (or @code{texi2roff}) to typeset the printed version. 38226 38227@value{GDBN} includes an already formatted copy of the on-line Info 38228version of this manual in the @file{gdb} subdirectory. The main Info 38229file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to 38230subordinate files matching @samp{gdb.info*} in the same directory. If 38231necessary, you can print out these files, or read them with any editor; 38232but they are easier to read using the @code{info} subsystem in @sc{gnu} 38233Emacs or the standalone @code{info} program, available as part of the 38234@sc{gnu} Texinfo distribution. 38235 38236If you want to format these Info files yourself, you need one of the 38237Info formatting programs, such as @code{texinfo-format-buffer} or 38238@code{makeinfo}. 38239 38240If you have @code{makeinfo} installed, and are in the top level 38241@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of 38242version @value{GDBVN}), you can make the Info file by typing: 38243 38244@smallexample 38245cd gdb 38246make gdb.info 38247@end smallexample 38248 38249If you want to typeset and print copies of this manual, you need @TeX{}, 38250a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the 38251Texinfo definitions file. 38252 38253@TeX{} is a typesetting program; it does not print files directly, but 38254produces output files called @sc{dvi} files. To print a typeset 38255document, you need a program to print @sc{dvi} files. If your system 38256has @TeX{} installed, chances are it has such a program. The precise 38257command to use depends on your system; @kbd{lpr -d} is common; another 38258(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may 38259require a file name without any extension or a @samp{.dvi} extension. 38260 38261@TeX{} also requires a macro definitions file called 38262@file{texinfo.tex}. This file tells @TeX{} how to typeset a document 38263written in Texinfo format. On its own, @TeX{} cannot either read or 38264typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB 38265and is located in the @file{gdb-@var{version-number}/texinfo} 38266directory. 38267 38268If you have @TeX{} and a @sc{dvi} printer program installed, you can 38269typeset and print this manual. First switch to the @file{gdb} 38270subdirectory of the main source directory (for example, to 38271@file{gdb-@value{GDBVN}/gdb}) and type: 38272 38273@smallexample 38274make gdb.dvi 38275@end smallexample 38276 38277Then give @file{gdb.dvi} to your @sc{dvi} printing program. 38278 38279@node Installing GDB 38280@appendix Installing @value{GDBN} 38281@cindex installation 38282 38283@menu 38284* Requirements:: Requirements for building @value{GDBN} 38285* Running Configure:: Invoking the @value{GDBN} @file{configure} script 38286* Separate Objdir:: Compiling @value{GDBN} in another directory 38287* Config Names:: Specifying names for hosts and targets 38288* Configure Options:: Summary of options for configure 38289* System-wide configuration:: Having a system-wide init file 38290@end menu 38291 38292@node Requirements 38293@section Requirements for Building @value{GDBN} 38294@cindex building @value{GDBN}, requirements for 38295 38296Building @value{GDBN} requires various tools and packages to be available. 38297Other packages will be used only if they are found. 38298 38299@heading Tools/Packages Necessary for Building @value{GDBN} 38300@table @asis 38301@item C@t{++}11 compiler 38302@value{GDBN} is written in C@t{++}11. It should be buildable with any 38303recent C@t{++}11 compiler, e.g.@: GCC. 38304 38305@item GNU make 38306@value{GDBN}'s build system relies on features only found in the GNU 38307make program. Other variants of @code{make} will not work. 38308 38309@item GMP (The GNU Multiple Precision Arithmetic Library) 38310@value{GDBN} now uses GMP to perform some of its arithmetics. 38311This library may be included with your operating system distribution; 38312if it is not, you can get the latest version from 38313@url{https://gmplib.org/}. If GMP is installed at an unusual path, 38314you can use the @option{--with-libgmp-prefix} option to specify 38315its location. 38316 38317@end table 38318 38319@heading Tools/Packages Optional for Building @value{GDBN} 38320@table @asis 38321@item Expat 38322@anchor{Expat} 38323@value{GDBN} can use the Expat XML parsing library. This library may be 38324included with your operating system distribution; if it is not, you 38325can get the latest version from @url{http://expat.sourceforge.net}. 38326The @file{configure} script will search for this library in several 38327standard locations; if it is installed in an unusual path, you can 38328use the @option{--with-libexpat-prefix} option to specify its location. 38329 38330Expat is used for: 38331 38332@itemize @bullet 38333@item 38334Remote protocol memory maps (@pxref{Memory Map Format}) 38335@item 38336Target descriptions (@pxref{Target Descriptions}) 38337@item 38338Remote shared library lists (@xref{Library List Format}, 38339or alternatively @pxref{Library List Format for SVR4 Targets}) 38340@item 38341MS-Windows shared libraries (@pxref{Shared Libraries}) 38342@item 38343Traceframe info (@pxref{Traceframe Info Format}) 38344@item 38345Branch trace (@pxref{Branch Trace Format}, 38346@pxref{Branch Trace Configuration Format}) 38347@end itemize 38348 38349@item Guile 38350@value{GDBN} can be scripted using GNU Guile. @xref{Guile}. By 38351default, @value{GDBN} will be compiled if the Guile libraries are 38352installed and are found by @file{configure}. You can use the 38353@code{--with-guile} option to request Guile, and pass either the Guile 38354version number or the file name of the relevant @code{pkg-config} 38355program to choose a particular version of Guile. 38356 38357@item iconv 38358@value{GDBN}'s features related to character sets (@pxref{Character 38359Sets}) require a functioning @code{iconv} implementation. If you are 38360on a GNU system, then this is provided by the GNU C Library. Some 38361other systems also provide a working @code{iconv}. 38362 38363If @value{GDBN} is using the @code{iconv} program which is installed 38364in a non-standard place, you will need to tell @value{GDBN} where to 38365find it. This is done with @option{--with-iconv-bin} which specifies 38366the directory that contains the @code{iconv} program. This program is 38367run in order to make a list of the available character sets. 38368 38369On systems without @code{iconv}, you can install GNU Libiconv. If 38370Libiconv is installed in a standard place, @value{GDBN} will 38371automatically use it if it is needed. If you have previously 38372installed Libiconv in a non-standard place, you can use the 38373@option{--with-libiconv-prefix} option to @file{configure}. 38374 38375@value{GDBN}'s top-level @file{configure} and @file{Makefile} will 38376arrange to build Libiconv if a directory named @file{libiconv} appears 38377in the top-most source directory. If Libiconv is built this way, and 38378if the operating system does not provide a suitable @code{iconv} 38379implementation, then the just-built library will automatically be used 38380by @value{GDBN}. One easy way to set this up is to download GNU 38381Libiconv, unpack it inside the top-level directory of the @value{GDBN} 38382source tree, and then rename the directory holding the Libiconv source 38383code to @samp{libiconv}. 38384 38385@item lzma 38386@value{GDBN} can support debugging sections that are compressed with 38387the LZMA library. @xref{MiniDebugInfo}. If this library is not 38388included with your operating system, you can find it in the xz package 38389at @url{http://tukaani.org/xz/}. If the LZMA library is available in 38390the usual place, then the @file{configure} script will use it 38391automatically. If it is installed in an unusual path, you can use the 38392@option{--with-lzma-prefix} option to specify its location. 38393 38394@item MPFR 38395@anchor{MPFR} 38396@value{GDBN} can use the GNU MPFR multiple-precision floating-point 38397library. This library may be included with your operating system 38398distribution; if it is not, you can get the latest version from 38399@url{http://www.mpfr.org}. The @file{configure} script will search 38400for this library in several standard locations; if it is installed 38401in an unusual path, you can use the @option{--with-libmpfr-prefix} 38402option to specify its location. 38403 38404GNU MPFR is used to emulate target floating-point arithmetic during 38405expression evaluation when the target uses different floating-point 38406formats than the host. If GNU MPFR it is not available, @value{GDBN} 38407will fall back to using host floating-point arithmetic. 38408 38409@item Python 38410@value{GDBN} can be scripted using Python language. @xref{Python}. 38411By default, @value{GDBN} will be compiled if the Python libraries are 38412installed and are found by @file{configure}. You can use the 38413@code{--with-python} option to request Python, and pass either the 38414file name of the relevant @code{python} executable, or the name of the 38415directory in which Python is installed, to choose a particular 38416installation of Python. 38417 38418@item zlib 38419@cindex compressed debug sections 38420@value{GDBN} will use the @samp{zlib} library, if available, to read 38421compressed debug sections. Some linkers, such as GNU gold, are capable 38422of producing binaries with compressed debug sections. If @value{GDBN} 38423is compiled with @samp{zlib}, it will be able to read the debug 38424information in such binaries. 38425 38426The @samp{zlib} library is likely included with your operating system 38427distribution; if it is not, you can get the latest version from 38428@url{http://zlib.net}. 38429@end table 38430 38431@node Running Configure 38432@section Invoking the @value{GDBN} @file{configure} Script 38433@cindex configuring @value{GDBN} 38434@value{GDBN} comes with a @file{configure} script that automates the process 38435of preparing @value{GDBN} for installation; you can then use @code{make} to 38436build the @code{gdb} program. 38437@iftex 38438@c irrelevant in info file; it's as current as the code it lives with. 38439@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN}, 38440look at the @file{README} file in the sources; we may have improved the 38441installation procedures since publishing this manual.} 38442@end iftex 38443 38444The @value{GDBN} distribution includes all the source code you need for 38445@value{GDBN} in a single directory, whose name is usually composed by 38446appending the version number to @samp{gdb}. 38447 38448For example, the @value{GDBN} version @value{GDBVN} distribution is in the 38449@file{gdb-@value{GDBVN}} directory. That directory contains: 38450 38451@table @code 38452@item gdb-@value{GDBVN}/configure @r{(and supporting files)} 38453script for configuring @value{GDBN} and all its supporting libraries 38454 38455@item gdb-@value{GDBVN}/gdb 38456the source specific to @value{GDBN} itself 38457 38458@item gdb-@value{GDBVN}/bfd 38459source for the Binary File Descriptor library 38460 38461@item gdb-@value{GDBVN}/include 38462@sc{gnu} include files 38463 38464@item gdb-@value{GDBVN}/libiberty 38465source for the @samp{-liberty} free software library 38466 38467@item gdb-@value{GDBVN}/opcodes 38468source for the library of opcode tables and disassemblers 38469 38470@item gdb-@value{GDBVN}/readline 38471source for the @sc{gnu} command-line interface 38472@end table 38473 38474There may be other subdirectories as well. 38475 38476The simplest way to configure and build @value{GDBN} is to run @file{configure} 38477from the @file{gdb-@var{version-number}} source directory, which in 38478this example is the @file{gdb-@value{GDBVN}} directory. 38479 38480First switch to the @file{gdb-@var{version-number}} source directory 38481if you are not already in it; then run @file{configure}. Pass the 38482identifier for the platform on which @value{GDBN} will run as an 38483argument. 38484 38485For example: 38486 38487@smallexample 38488cd gdb-@value{GDBVN} 38489./configure 38490make 38491@end smallexample 38492 38493Running @samp{configure} and then running @code{make} builds the 38494included supporting libraries, then @code{gdb} itself. The configured 38495source files, and the binaries, are left in the corresponding source 38496directories. 38497 38498@need 750 38499@file{configure} is a Bourne-shell (@code{/bin/sh}) script; if your 38500system does not recognize this automatically when you run a different 38501shell, you may need to run @code{sh} on it explicitly: 38502 38503@smallexample 38504sh configure 38505@end smallexample 38506 38507You should run the @file{configure} script from the top directory in the 38508source tree, the @file{gdb-@var{version-number}} directory. If you run 38509@file{configure} from one of the subdirectories, you will configure only 38510that subdirectory. That is usually not what you want. In particular, 38511if you run the first @file{configure} from the @file{gdb} subdirectory 38512of the @file{gdb-@var{version-number}} directory, you will omit the 38513configuration of @file{bfd}, @file{readline}, and other sibling 38514directories of the @file{gdb} subdirectory. This leads to build errors 38515about missing include files such as @file{bfd/bfd.h}. 38516 38517You can install @code{@value{GDBN}} anywhere. The best way to do this 38518is to pass the @code{--prefix} option to @code{configure}, and then 38519install it with @code{make install}. 38520 38521@node Separate Objdir 38522@section Compiling @value{GDBN} in Another Directory 38523 38524If you want to run @value{GDBN} versions for several host or target machines, 38525you need a different @code{gdb} compiled for each combination of 38526host and target. @file{configure} is designed to make this easy by 38527allowing you to generate each configuration in a separate subdirectory, 38528rather than in the source directory. If your @code{make} program 38529handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running 38530@code{make} in each of these directories builds the @code{gdb} 38531program specified there. 38532 38533To build @code{gdb} in a separate directory, run @file{configure} 38534with the @samp{--srcdir} option to specify where to find the source. 38535(You also need to specify a path to find @file{configure} 38536itself from your working directory. If the path to @file{configure} 38537would be the same as the argument to @samp{--srcdir}, you can leave out 38538the @samp{--srcdir} option; it is assumed.) 38539 38540For example, with version @value{GDBVN}, you can build @value{GDBN} in a 38541separate directory for a Sun 4 like this: 38542 38543@smallexample 38544@group 38545cd gdb-@value{GDBVN} 38546mkdir ../gdb-sun4 38547cd ../gdb-sun4 38548../gdb-@value{GDBVN}/configure 38549make 38550@end group 38551@end smallexample 38552 38553When @file{configure} builds a configuration using a remote source 38554directory, it creates a tree for the binaries with the same structure 38555(and using the same names) as the tree under the source directory. In 38556the example, you'd find the Sun 4 library @file{libiberty.a} in the 38557directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in 38558@file{gdb-sun4/gdb}. 38559 38560Make sure that your path to the @file{configure} script has just one 38561instance of @file{gdb} in it. If your path to @file{configure} looks 38562like @file{../gdb-@value{GDBVN}/gdb/configure}, you are configuring only 38563one subdirectory of @value{GDBN}, not the whole package. This leads to 38564build errors about missing include files such as @file{bfd/bfd.h}. 38565 38566One popular reason to build several @value{GDBN} configurations in separate 38567directories is to configure @value{GDBN} for cross-compiling (where 38568@value{GDBN} runs on one machine---the @dfn{host}---while debugging 38569programs that run on another machine---the @dfn{target}). 38570You specify a cross-debugging target by 38571giving the @samp{--target=@var{target}} option to @file{configure}. 38572 38573When you run @code{make} to build a program or library, you must run 38574it in a configured directory---whatever directory you were in when you 38575called @file{configure} (or one of its subdirectories). 38576 38577The @code{Makefile} that @file{configure} generates in each source 38578directory also runs recursively. If you type @code{make} in a source 38579directory such as @file{gdb-@value{GDBVN}} (or in a separate configured 38580directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you 38581will build all the required libraries, and then build GDB. 38582 38583When you have multiple hosts or targets configured in separate 38584directories, you can run @code{make} on them in parallel (for example, 38585if they are NFS-mounted on each of the hosts); they will not interfere 38586with each other. 38587 38588@node Config Names 38589@section Specifying Names for Hosts and Targets 38590 38591The specifications used for hosts and targets in the @file{configure} 38592script are based on a three-part naming scheme, but some short predefined 38593aliases are also supported. The full naming scheme encodes three pieces 38594of information in the following pattern: 38595 38596@smallexample 38597@var{architecture}-@var{vendor}-@var{os} 38598@end smallexample 38599 38600For example, you can use the alias @code{sun4} as a @var{host} argument, 38601or as the value for @var{target} in a @code{--target=@var{target}} 38602option. The equivalent full name is @samp{sparc-sun-sunos4}. 38603 38604The @file{configure} script accompanying @value{GDBN} does not provide 38605any query facility to list all supported host and target names or 38606aliases. @file{configure} calls the Bourne shell script 38607@code{config.sub} to map abbreviations to full names; you can read the 38608script, if you wish, or you can use it to test your guesses on 38609abbreviations---for example: 38610 38611@smallexample 38612% sh config.sub i386-linux 38613i386-pc-linux-gnu 38614% sh config.sub alpha-linux 38615alpha-unknown-linux-gnu 38616% sh config.sub hp9k700 38617hppa1.1-hp-hpux 38618% sh config.sub sun4 38619sparc-sun-sunos4.1.1 38620% sh config.sub sun3 38621m68k-sun-sunos4.1.1 38622% sh config.sub i986v 38623Invalid configuration `i986v': machine `i986v' not recognized 38624@end smallexample 38625 38626@noindent 38627@code{config.sub} is also distributed in the @value{GDBN} source 38628directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}). 38629 38630@node Configure Options 38631@section @file{configure} Options 38632 38633Here is a summary of the @file{configure} options and arguments that 38634are most often useful for building @value{GDBN}. @file{configure} 38635also has several other options not listed here. @inforef{Running 38636configure scripts,,autoconf.info}, for a full 38637explanation of @file{configure}. 38638 38639@smallexample 38640configure @r{[}--help@r{]} 38641 @r{[}--prefix=@var{dir}@r{]} 38642 @r{[}--exec-prefix=@var{dir}@r{]} 38643 @r{[}--srcdir=@var{dirname}@r{]} 38644 @r{[}--target=@var{target}@r{]} 38645@end smallexample 38646 38647@noindent 38648You may introduce options with a single @samp{-} rather than 38649@samp{--} if you prefer; but you may abbreviate option names if you use 38650@samp{--}. 38651 38652@table @code 38653@item --help 38654Display a quick summary of how to invoke @file{configure}. 38655 38656@item --prefix=@var{dir} 38657Configure the source to install programs and files under directory 38658@file{@var{dir}}. 38659 38660@item --exec-prefix=@var{dir} 38661Configure the source to install programs under directory 38662@file{@var{dir}}. 38663 38664@c avoid splitting the warning from the explanation: 38665@need 2000 38666@item --srcdir=@var{dirname} 38667Use this option to make configurations in directories separate from the 38668@value{GDBN} source directories. Among other things, you can use this to 38669build (or maintain) several configurations simultaneously, in separate 38670directories. @file{configure} writes configuration-specific files in 38671the current directory, but arranges for them to use the source in the 38672directory @var{dirname}. @file{configure} creates directories under 38673the working directory in parallel to the source directories below 38674@var{dirname}. 38675 38676@item --target=@var{target} 38677Configure @value{GDBN} for cross-debugging programs running on the specified 38678@var{target}. Without this option, @value{GDBN} is configured to debug 38679programs that run on the same machine (@var{host}) as @value{GDBN} itself. 38680 38681There is no convenient way to generate a list of all available 38682targets. Also see the @code{--enable-targets} option, below. 38683@end table 38684 38685There are many other options that are specific to @value{GDBN}. This 38686lists just the most common ones; there are some very specialized 38687options not described here. 38688 38689@table @code 38690@item --enable-targets=@r{[}@var{target}@r{]}@dots{} 38691@itemx --enable-targets=all 38692Configure @value{GDBN} for cross-debugging programs running on the 38693specified list of targets. The special value @samp{all} configures 38694@value{GDBN} for debugging programs running on any target it supports. 38695 38696@item --with-gdb-datadir=@var{path} 38697Set the @value{GDBN}-specific data directory. @value{GDBN} will look 38698here for certain supporting files or scripts. This defaults to the 38699@file{gdb} subdirectory of @samp{datadir} (which can be set using 38700@code{--datadir}). 38701 38702@item --with-relocated-sources=@var{dir} 38703Sets up the default source path substitution rule so that directory 38704names recorded in debug information will be automatically adjusted for 38705any directory under @var{dir}. @var{dir} should be a subdirectory of 38706@value{GDBN}'s configured prefix, the one mentioned in the 38707@code{--prefix} or @code{--exec-prefix} options to configure. This 38708option is useful if GDB is supposed to be moved to a different place 38709after it is built. 38710 38711@item --enable-64-bit-bfd 38712Enable 64-bit support in BFD on 32-bit hosts. 38713 38714@item --disable-gdbmi 38715Build @value{GDBN} without the GDB/MI machine interface 38716(@pxref{GDB/MI}). 38717 38718@item --enable-tui 38719Build @value{GDBN} with the text-mode full-screen user interface 38720(TUI). Requires a curses library (ncurses and cursesX are also 38721supported). 38722 38723@item --with-curses 38724Use the curses library instead of the termcap library, for text-mode 38725terminal operations. 38726 38727@item --with-debuginfod 38728Build @value{GDBN} with libdebuginfod, the debuginfod client library. 38729Used to automatically fetch source files and separate debug files from 38730debuginfod servers using the associated executable's build ID. Enabled 38731by default if libdebuginfod is installed and found at configure time. 38732debuginfod is packaged with elfutils, starting with version 0.178. You 38733can get the latest version from `https://sourceware.org/elfutils/'. 38734 38735@item --with-libunwind-ia64 38736Use the libunwind library for unwinding function call stack on ia64 38737target platforms. See http://www.nongnu.org/libunwind/index.html for 38738details. 38739 38740@item --with-system-readline 38741Use the readline library installed on the host, rather than the 38742library supplied as part of @value{GDBN}. Readline 7 or newer is 38743required; this is enforced by the build system. 38744 38745@item --with-system-zlib 38746Use the zlib library installed on the host, rather than the library 38747supplied as part of @value{GDBN}. 38748 38749@item --with-expat 38750Build @value{GDBN} with Expat, a library for XML parsing. (Done by 38751default if libexpat is installed and found at configure time.) This 38752library is used to read XML files supplied with @value{GDBN}. If it 38753is unavailable, some features, such as remote protocol memory maps, 38754target descriptions, and shared library lists, that are based on XML 38755files, will not be available in @value{GDBN}. If your host does not 38756have libexpat installed, you can get the latest version from 38757`http://expat.sourceforge.net'. 38758 38759@item --with-libiconv-prefix@r{[}=@var{dir}@r{]} 38760 38761Build @value{GDBN} with GNU libiconv, a character set encoding 38762conversion library. This is not done by default, as on GNU systems 38763the @code{iconv} that is built in to the C library is sufficient. If 38764your host does not have a working @code{iconv}, you can get the latest 38765version of GNU iconv from `https://www.gnu.org/software/libiconv/'. 38766 38767@value{GDBN}'s build system also supports building GNU libiconv as 38768part of the overall build. @xref{Requirements}. 38769 38770@item --with-lzma 38771Build @value{GDBN} with LZMA, a compression library. (Done by default 38772if liblzma is installed and found at configure time.) LZMA is used by 38773@value{GDBN}'s "mini debuginfo" feature, which is only useful on 38774platforms using the ELF object file format. If your host does not 38775have liblzma installed, you can get the latest version from 38776`https://tukaani.org/xz/'. 38777 38778@item --with-mpfr 38779Build @value{GDBN} with GNU MPFR, a library for multiple-precision 38780floating-point computation with correct rounding. (Done by default if 38781GNU MPFR is installed and found at configure time.) This library is 38782used to emulate target floating-point arithmetic during expression 38783evaluation when the target uses different floating-point formats than 38784the host. If GNU MPFR is not available, @value{GDBN} will fall back 38785to using host floating-point arithmetic. If your host does not have 38786GNU MPFR installed, you can get the latest version from 38787`http://www.mpfr.org'. 38788 38789@item --with-python@r{[}=@var{python}@r{]} 38790Build @value{GDBN} with Python scripting support. (Done by default if 38791libpython is present and found at configure time.) Python makes 38792@value{GDBN} scripting much more powerful than the restricted CLI 38793scripting language. If your host does not have Python installed, you 38794can find it on `http://www.python.org/download/'. The oldest version 38795of Python supported by GDB is 2.6. The optional argument @var{python} 38796is used to find the Python headers and libraries. It can be either 38797the name of a Python executable, or the name of the directory in which 38798Python is installed. 38799 38800@item --with-guile[=GUILE]' 38801Build @value{GDBN} with GNU Guile scripting support. (Done by default 38802if libguile is present and found at configure time.) If your host 38803does not have Guile installed, you can find it at 38804`https://www.gnu.org/software/guile/'. The optional argument GUILE 38805can be a version number, which will cause @code{configure} to try to 38806use that version of Guile; or the file name of a @code{pkg-config} 38807executable, which will be queried to find the information needed to 38808compile and link against Guile. 38809 38810@item --without-included-regex 38811Don't use the regex library included with @value{GDBN} (as part of the 38812libiberty library). This is the default on hosts with version 2 of 38813the GNU C library. 38814 38815@item --with-sysroot=@var{dir} 38816Use @var{dir} as the default system root directory for libraries whose 38817file names begin with @file{/lib}' or @file{/usr/lib'}. (The value of 38818@var{dir} can be modified at run time by using the @command{set 38819sysroot} command.) If @var{dir} is under the @value{GDBN} configured 38820prefix (set with @code{--prefix} or @code{--exec-prefix options}, the 38821default system root will be automatically adjusted if and when 38822@value{GDBN} is moved to a different location. 38823 38824@item --with-system-gdbinit=@var{file} 38825Configure @value{GDBN} to automatically load a system-wide init file. 38826@var{file} should be an absolute file name. If @var{file} is in a 38827directory under the configured prefix, and @value{GDBN} is moved to 38828another location after being built, the location of the system-wide 38829init file will be adjusted accordingly. 38830 38831@item --with-system-gdbinit-dir=@var{directory} 38832Configure @value{GDBN} to automatically load init files from a 38833system-wide directory. @var{directory} should be an absolute directory 38834name. If @var{directory} is in a directory under the configured 38835prefix, and @value{GDBN} is moved to another location after being 38836built, the location of the system-wide init directory will be 38837adjusted accordingly. 38838 38839@item --enable-build-warnings 38840When building the @value{GDBN} sources, ask the compiler to warn about 38841any code which looks even vaguely suspicious. It passes many 38842different warning flags, depending on the exact version of the 38843compiler you are using. 38844 38845@item --enable-werror 38846Treat compiler warnings as werrors. It adds the @code{-Werror} flag 38847to the compiler, which will fail the compilation if the compiler 38848outputs any warning messages. 38849 38850@item --enable-ubsan 38851Enable the GCC undefined behavior sanitizer. This is disabled by 38852default, but passing @code{--enable-ubsan=yes} or 38853@code{--enable-ubsan=auto} to @code{configure} will enable it. The 38854undefined behavior sanitizer checks for C@t{++} undefined behavior. 38855It has a performance cost, so if you are looking at @value{GDBN}'s 38856performance, you should disable it. The undefined behavior sanitizer 38857was first introduced in GCC 4.9. 38858@end table 38859 38860@node System-wide configuration 38861@section System-wide configuration and settings 38862@cindex system-wide init file 38863 38864@value{GDBN} can be configured to have a system-wide init file and a 38865system-wide init file directory; this file and files in that directory 38866(if they have a recognized file extension) will be read and executed at 38867startup (@pxref{Startup, , What @value{GDBN} does during startup}). 38868 38869Here are the corresponding configure options: 38870 38871@table @code 38872@item --with-system-gdbinit=@var{file} 38873Specify that the default location of the system-wide init file is 38874@var{file}. 38875@item --with-system-gdbinit-dir=@var{directory} 38876Specify that the default location of the system-wide init file directory 38877is @var{directory}. 38878@end table 38879 38880If @value{GDBN} has been configured with the option @option{--prefix=$prefix}, 38881they may be subject to relocation. Two possible cases: 38882 38883@itemize @bullet 38884@item 38885If the default location of this init file/directory contains @file{$prefix}, 38886it will be subject to relocation. Suppose that the configure options 38887are @option{--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit}; 38888if @value{GDBN} is moved from @file{$prefix} to @file{$install}, the system 38889init file is looked for as @file{$install/etc/gdbinit} instead of 38890@file{$prefix/etc/gdbinit}. 38891 38892@item 38893By contrast, if the default location does not contain the prefix, 38894it will not be relocated. E.g.@: if @value{GDBN} has been configured with 38895@option{--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit}, 38896then @value{GDBN} will always look for @file{/usr/share/gdb/gdbinit}, 38897wherever @value{GDBN} is installed. 38898@end itemize 38899 38900If the configured location of the system-wide init file (as given by the 38901@option{--with-system-gdbinit} option at configure time) is in the 38902data-directory (as specified by @option{--with-gdb-datadir} at configure 38903time) or in one of its subdirectories, then @value{GDBN} will look for the 38904system-wide init file in the directory specified by the 38905@option{--data-directory} command-line option. 38906Note that the system-wide init file is only read once, during @value{GDBN} 38907initialization. If the data-directory is changed after @value{GDBN} has 38908started with the @code{set data-directory} command, the file will not be 38909reread. 38910 38911This applies similarly to the system-wide directory specified in 38912@option{--with-system-gdbinit-dir}. 38913 38914Any supported scripting language can be used for these init files, as long 38915as the file extension matches the scripting language. To be interpreted 38916as regular @value{GDBN} commands, the files needs to have a @file{.gdb} 38917extension. 38918 38919@menu 38920* System-wide Configuration Scripts:: Installed System-wide Configuration Scripts 38921@end menu 38922 38923@node System-wide Configuration Scripts 38924@subsection Installed System-wide Configuration Scripts 38925@cindex system-wide configuration scripts 38926 38927The @file{system-gdbinit} directory, located inside the data-directory 38928(as specified by @option{--with-gdb-datadir} at configure time) contains 38929a number of scripts which can be used as system-wide init files. To 38930automatically source those scripts at startup, @value{GDBN} should be 38931configured with @option{--with-system-gdbinit}. Otherwise, any user 38932should be able to source them by hand as needed. 38933 38934The following scripts are currently available: 38935@itemize @bullet 38936 38937@item @file{elinos.py} 38938@pindex elinos.py 38939@cindex ELinOS system-wide configuration script 38940This script is useful when debugging a program on an ELinOS target. 38941It takes advantage of the environment variables defined in a standard 38942ELinOS environment in order to determine the location of the system 38943shared libraries, and then sets the @samp{solib-absolute-prefix} 38944and @samp{solib-search-path} variables appropriately. 38945 38946@item @file{wrs-linux.py} 38947@pindex wrs-linux.py 38948@cindex Wind River Linux system-wide configuration script 38949This script is useful when debugging a program on a target running 38950Wind River Linux. It expects the @env{ENV_PREFIX} to be set to 38951the host-side sysroot used by the target system. 38952 38953@end itemize 38954 38955@node Maintenance Commands 38956@appendix Maintenance Commands 38957@cindex maintenance commands 38958@cindex internal commands 38959 38960In addition to commands intended for @value{GDBN} users, @value{GDBN} 38961includes a number of commands intended for @value{GDBN} developers, 38962that are not documented elsewhere in this manual. These commands are 38963provided here for reference. (For commands that turn on debugging 38964messages, see @ref{Debugging Output}.) 38965 38966@table @code 38967@kindex maint agent 38968@kindex maint agent-eval 38969@item maint agent @r{[}-at @var{location}@r{,}@r{]} @var{expression} 38970@itemx maint agent-eval @r{[}-at @var{location}@r{,}@r{]} @var{expression} 38971Translate the given @var{expression} into remote agent bytecodes. 38972This command is useful for debugging the Agent Expression mechanism 38973(@pxref{Agent Expressions}). The @samp{agent} version produces an 38974expression useful for data collection, such as by tracepoints, while 38975@samp{maint agent-eval} produces an expression that evaluates directly 38976to a result. For instance, a collection expression for @code{globa + 38977globb} will include bytecodes to record four bytes of memory at each 38978of the addresses of @code{globa} and @code{globb}, while discarding 38979the result of the addition, while an evaluation expression will do the 38980addition and return the sum. 38981If @code{-at} is given, generate remote agent bytecode for @var{location}. 38982If not, generate remote agent bytecode for current frame PC address. 38983 38984@kindex maint agent-printf 38985@item maint agent-printf @var{format},@var{expr},... 38986Translate the given format string and list of argument expressions 38987into remote agent bytecodes and display them as a disassembled list. 38988This command is useful for debugging the agent version of dynamic 38989printf (@pxref{Dynamic Printf}). 38990 38991@kindex maint info breakpoints 38992@item @anchor{maint info breakpoints}maint info breakpoints 38993Using the same format as @samp{info breakpoints}, display both the 38994breakpoints you've set explicitly, and those @value{GDBN} is using for 38995internal purposes. Internal breakpoints are shown with negative 38996breakpoint numbers. The type column identifies what kind of breakpoint 38997is shown: 38998 38999@table @code 39000@item breakpoint 39001Normal, explicitly set breakpoint. 39002 39003@item watchpoint 39004Normal, explicitly set watchpoint. 39005 39006@item longjmp 39007Internal breakpoint, used to handle correctly stepping through 39008@code{longjmp} calls. 39009 39010@item longjmp resume 39011Internal breakpoint at the target of a @code{longjmp}. 39012 39013@item until 39014Temporary internal breakpoint used by the @value{GDBN} @code{until} command. 39015 39016@item finish 39017Temporary internal breakpoint used by the @value{GDBN} @code{finish} command. 39018 39019@item shlib events 39020Shared library events. 39021 39022@end table 39023 39024@kindex maint info btrace 39025@item maint info btrace 39026Pint information about raw branch tracing data. 39027 39028@kindex maint btrace packet-history 39029@item maint btrace packet-history 39030Print the raw branch trace packets that are used to compute the 39031execution history for the @samp{record btrace} command. Both the 39032information and the format in which it is printed depend on the btrace 39033recording format. 39034 39035@table @code 39036@item bts 39037For the BTS recording format, print a list of blocks of sequential 39038code. For each block, the following information is printed: 39039 39040@table @asis 39041@item Block number 39042Newer blocks have higher numbers. The oldest block has number zero. 39043@item Lowest @samp{PC} 39044@item Highest @samp{PC} 39045@end table 39046 39047@item pt 39048For the Intel Processor Trace recording format, print a list of 39049Intel Processor Trace packets. For each packet, the following 39050information is printed: 39051 39052@table @asis 39053@item Packet number 39054Newer packets have higher numbers. The oldest packet has number zero. 39055@item Trace offset 39056The packet's offset in the trace stream. 39057@item Packet opcode and payload 39058@end table 39059@end table 39060 39061@kindex maint btrace clear-packet-history 39062@item maint btrace clear-packet-history 39063Discards the cached packet history printed by the @samp{maint btrace 39064packet-history} command. The history will be computed again when 39065needed. 39066 39067@kindex maint btrace clear 39068@item maint btrace clear 39069Discard the branch trace data. The data will be fetched anew and the 39070branch trace will be recomputed when needed. 39071 39072This implicitly truncates the branch trace to a single branch trace 39073buffer. When updating branch trace incrementally, the branch trace 39074available to @value{GDBN} may be bigger than a single branch trace 39075buffer. 39076 39077@kindex maint set btrace pt skip-pad 39078@item maint set btrace pt skip-pad 39079@kindex maint show btrace pt skip-pad 39080@item maint show btrace pt skip-pad 39081Control whether @value{GDBN} will skip PAD packets when computing the 39082packet history. 39083 39084@kindex set displaced-stepping 39085@kindex show displaced-stepping 39086@cindex displaced stepping support 39087@cindex out-of-line single-stepping 39088@item set displaced-stepping 39089@itemx show displaced-stepping 39090Control whether or not @value{GDBN} will do @dfn{displaced stepping} 39091if the target supports it. Displaced stepping is a way to single-step 39092over breakpoints without removing them from the inferior, by executing 39093an out-of-line copy of the instruction that was originally at the 39094breakpoint location. It is also known as out-of-line single-stepping. 39095 39096@table @code 39097@item set displaced-stepping on 39098If the target architecture supports it, @value{GDBN} will use 39099displaced stepping to step over breakpoints. 39100 39101@item set displaced-stepping off 39102@value{GDBN} will not use displaced stepping to step over breakpoints, 39103even if such is supported by the target architecture. 39104 39105@cindex non-stop mode, and @samp{set displaced-stepping} 39106@item set displaced-stepping auto 39107This is the default mode. @value{GDBN} will use displaced stepping 39108only if non-stop mode is active (@pxref{Non-Stop Mode}) and the target 39109architecture supports displaced stepping. 39110@end table 39111 39112@kindex maint check-psymtabs 39113@item maint check-psymtabs 39114Check the consistency of currently expanded psymtabs versus symtabs. 39115Use this to check, for example, whether a symbol is in one but not the other. 39116 39117@kindex maint check-symtabs 39118@item maint check-symtabs 39119Check the consistency of currently expanded symtabs. 39120 39121@kindex maint expand-symtabs 39122@item maint expand-symtabs [@var{regexp}] 39123Expand symbol tables. 39124If @var{regexp} is specified, only expand symbol tables for file 39125names matching @var{regexp}. 39126 39127@kindex maint set catch-demangler-crashes 39128@kindex maint show catch-demangler-crashes 39129@cindex demangler crashes 39130@item maint set catch-demangler-crashes [on|off] 39131@itemx maint show catch-demangler-crashes 39132Control whether @value{GDBN} should attempt to catch crashes in the 39133symbol name demangler. The default is to attempt to catch crashes. 39134If enabled, the first time a crash is caught, a core file is created, 39135the offending symbol is displayed and the user is presented with the 39136option to terminate the current session. 39137 39138@kindex maint cplus first_component 39139@item maint cplus first_component @var{name} 39140Print the first C@t{++} class/namespace component of @var{name}. 39141 39142@kindex maint cplus namespace 39143@item maint cplus namespace 39144Print the list of possible C@t{++} namespaces. 39145 39146@kindex maint deprecate 39147@kindex maint undeprecate 39148@cindex deprecated commands 39149@item maint deprecate @var{command} @r{[}@var{replacement}@r{]} 39150@itemx maint undeprecate @var{command} 39151Deprecate or undeprecate the named @var{command}. Deprecated commands 39152cause @value{GDBN} to issue a warning when you use them. The optional 39153argument @var{replacement} says which newer command should be used in 39154favor of the deprecated one; if it is given, @value{GDBN} will mention 39155the replacement as part of the warning. 39156 39157@kindex maint dump-me 39158@item maint dump-me 39159@cindex @code{SIGQUIT} signal, dump core of @value{GDBN} 39160Cause a fatal signal in the debugger and force it to dump its core. 39161This is supported only on systems which support aborting a program 39162with the @code{SIGQUIT} signal. 39163 39164@kindex maint internal-error 39165@kindex maint internal-warning 39166@kindex maint demangler-warning 39167@cindex demangler crashes 39168@item maint internal-error @r{[}@var{message-text}@r{]} 39169@itemx maint internal-warning @r{[}@var{message-text}@r{]} 39170@itemx maint demangler-warning @r{[}@var{message-text}@r{]} 39171 39172Cause @value{GDBN} to call the internal function @code{internal_error}, 39173@code{internal_warning} or @code{demangler_warning} and hence behave 39174as though an internal problem has been detected. In addition to 39175reporting the internal problem, these functions give the user the 39176opportunity to either quit @value{GDBN} or (for @code{internal_error} 39177and @code{internal_warning}) create a core file of the current 39178@value{GDBN} session. 39179 39180These commands take an optional parameter @var{message-text} that is 39181used as the text of the error or warning message. 39182 39183Here's an example of using @code{internal-error}: 39184 39185@smallexample 39186(@value{GDBP}) @kbd{maint internal-error testing, 1, 2} 39187@dots{}/maint.c:121: internal-error: testing, 1, 2 39188A problem internal to GDB has been detected. Further 39189debugging may prove unreliable. 39190Quit this debugging session? (y or n) @kbd{n} 39191Create a core file? (y or n) @kbd{n} 39192(@value{GDBP}) 39193@end smallexample 39194 39195@cindex @value{GDBN} internal error 39196@cindex internal errors, control of @value{GDBN} behavior 39197@cindex demangler crashes 39198 39199@kindex maint set internal-error 39200@kindex maint show internal-error 39201@kindex maint set internal-warning 39202@kindex maint show internal-warning 39203@kindex maint set demangler-warning 39204@kindex maint show demangler-warning 39205@item maint set internal-error @var{action} [ask|yes|no] 39206@itemx maint show internal-error @var{action} 39207@itemx maint set internal-warning @var{action} [ask|yes|no] 39208@itemx maint show internal-warning @var{action} 39209@itemx maint set demangler-warning @var{action} [ask|yes|no] 39210@itemx maint show demangler-warning @var{action} 39211When @value{GDBN} reports an internal problem (error or warning) it 39212gives the user the opportunity to both quit @value{GDBN} and create a 39213core file of the current @value{GDBN} session. These commands let you 39214override the default behaviour for each particular @var{action}, 39215described in the table below. 39216 39217@table @samp 39218@item quit 39219You can specify that @value{GDBN} should always (yes) or never (no) 39220quit. The default is to ask the user what to do. 39221 39222@item corefile 39223You can specify that @value{GDBN} should always (yes) or never (no) 39224create a core file. The default is to ask the user what to do. Note 39225that there is no @code{corefile} option for @code{demangler-warning}: 39226demangler warnings always create a core file and this cannot be 39227disabled. 39228@end table 39229 39230@kindex maint packet 39231@item maint packet @var{text} 39232If @value{GDBN} is talking to an inferior via the serial protocol, 39233then this command sends the string @var{text} to the inferior, and 39234displays the response packet. @value{GDBN} supplies the initial 39235@samp{$} character, the terminating @samp{#} character, and the 39236checksum. 39237 39238@kindex maint print architecture 39239@item maint print architecture @r{[}@var{file}@r{]} 39240Print the entire architecture configuration. The optional argument 39241@var{file} names the file where the output goes. 39242 39243@kindex maint print c-tdesc 39244@item maint print c-tdesc @r{[}-single-feature@r{]} @r{[}@var{file}@r{]} 39245Print the target description (@pxref{Target Descriptions}) as 39246a C source file. By default, the target description is for the current 39247target, but if the optional argument @var{file} is provided, that file 39248is used to produce the description. The @var{file} should be an XML 39249document, of the form described in @ref{Target Description Format}. 39250The created source file is built into @value{GDBN} when @value{GDBN} is 39251built again. This command is used by developers after they add or 39252modify XML target descriptions. 39253 39254When the optional flag @samp{-single-feature} is provided then the 39255target description being processed (either the default, or from 39256@var{file}) must only contain a single feature. The source file 39257produced is different in this case. 39258 39259@kindex maint print xml-tdesc 39260@item maint print xml-tdesc @r{[}@var{file}@r{]} 39261Print the target description (@pxref{Target Descriptions}) as an XML 39262file. By default print the target description for the current target, 39263but if the optional argument @var{file} is provided, then that file is 39264read in by GDB and then used to produce the description. The 39265@var{file} should be an XML document, of the form described in 39266@ref{Target Description Format}. 39267 39268@kindex maint check xml-descriptions 39269@item maint check xml-descriptions @var{dir} 39270Check that the target descriptions dynamically created by @value{GDBN} 39271equal the descriptions created from XML files found in @var{dir}. 39272 39273@anchor{maint check libthread-db} 39274@kindex maint check libthread-db 39275@item maint check libthread-db 39276Run integrity checks on the current inferior's thread debugging 39277library. This exercises all @code{libthread_db} functionality used by 39278@value{GDBN} on GNU/Linux systems, and by extension also exercises the 39279@code{proc_service} functions provided by @value{GDBN} that 39280@code{libthread_db} uses. Note that parts of the test may be skipped 39281on some platforms when debugging core files. 39282 39283@kindex maint print core-file-backed-mappings 39284@cindex memory address space mappings 39285@item maint print core-file-backed-mappings 39286Print the file-backed mappings which were loaded from a core file note. 39287This output represents state internal to @value{GDBN} and should be 39288similar to the mappings displayed by the @code{info proc mappings} 39289command. 39290 39291@kindex maint print dummy-frames 39292@item maint print dummy-frames 39293Prints the contents of @value{GDBN}'s internal dummy-frame stack. 39294 39295@smallexample 39296(@value{GDBP}) @kbd{b add} 39297@dots{} 39298(@value{GDBP}) @kbd{print add(2,3)} 39299Breakpoint 2, add (a=2, b=3) at @dots{} 3930058 return (a + b); 39301The program being debugged stopped while in a function called from GDB. 39302@dots{} 39303(@value{GDBP}) @kbd{maint print dummy-frames} 393040xa8206d8: id=@{stack=0xbfffe734,code=0xbfffe73f,!special@}, ptid=process 9353 39305(@value{GDBP}) 39306@end smallexample 39307 39308Takes an optional file parameter. 39309 39310@kindex maint print registers 39311@kindex maint print raw-registers 39312@kindex maint print cooked-registers 39313@kindex maint print register-groups 39314@kindex maint print remote-registers 39315@item maint print registers @r{[}@var{file}@r{]} 39316@itemx maint print raw-registers @r{[}@var{file}@r{]} 39317@itemx maint print cooked-registers @r{[}@var{file}@r{]} 39318@itemx maint print register-groups @r{[}@var{file}@r{]} 39319@itemx maint print remote-registers @r{[}@var{file}@r{]} 39320Print @value{GDBN}'s internal register data structures. 39321 39322The command @code{maint print raw-registers} includes the contents of 39323the raw register cache; the command @code{maint print 39324cooked-registers} includes the (cooked) value of all registers, 39325including registers which aren't available on the target nor visible 39326to user; the command @code{maint print register-groups} includes the 39327groups that each register is a member of; and the command @code{maint 39328print remote-registers} includes the remote target's register numbers 39329and offsets in the `G' packets. 39330 39331These commands take an optional parameter, a file name to which to 39332write the information. 39333 39334@kindex maint print reggroups 39335@item maint print reggroups @r{[}@var{file}@r{]} 39336Print @value{GDBN}'s internal register group data structures. The 39337optional argument @var{file} tells to what file to write the 39338information. 39339 39340The register groups info looks like this: 39341 39342@smallexample 39343(@value{GDBP}) @kbd{maint print reggroups} 39344 Group Type 39345 general user 39346 float user 39347 all user 39348 vector user 39349 system user 39350 save internal 39351 restore internal 39352@end smallexample 39353 39354@kindex maint flush register-cache 39355@kindex flushregs 39356@cindex register cache, flushing 39357@item maint flush register-cache 39358@itemx flushregs 39359Flush the contents of the register cache and as a consequence the 39360frame cache. This command is useful when debugging issues related to 39361register fetching, or frame unwinding. The command @code{flushregs} 39362is deprecated in favor of @code{maint flush register-cache}. 39363 39364@kindex maint print objfiles 39365@cindex info for known object files 39366@item maint print objfiles @r{[}@var{regexp}@r{]} 39367Print a dump of all known object files. 39368If @var{regexp} is specified, only print object files whose names 39369match @var{regexp}. For each object file, this command prints its name, 39370address in memory, and all of its psymtabs and symtabs. 39371 39372@kindex maint print user-registers 39373@cindex user registers 39374@item maint print user-registers 39375List all currently available @dfn{user registers}. User registers 39376typically provide alternate names for actual hardware registers. They 39377include the four ``standard'' registers @code{$fp}, @code{$pc}, 39378@code{$sp}, and @code{$ps}. @xref{standard registers}. User 39379registers can be used in expressions in the same way as the canonical 39380register names, but only the latter are listed by the @code{info 39381registers} and @code{maint print registers} commands. 39382 39383@kindex maint print section-scripts 39384@cindex info for known .debug_gdb_scripts-loaded scripts 39385@item maint print section-scripts [@var{regexp}] 39386Print a dump of scripts specified in the @code{.debug_gdb_section} section. 39387If @var{regexp} is specified, only print scripts loaded by object files 39388matching @var{regexp}. 39389For each script, this command prints its name as specified in the objfile, 39390and the full path if known. 39391@xref{dotdebug_gdb_scripts section}. 39392 39393@kindex maint print statistics 39394@cindex bcache statistics 39395@item maint print statistics 39396This command prints, for each object file in the program, various data 39397about that object file followed by the byte cache (@dfn{bcache}) 39398statistics for the object file. The objfile data includes the number 39399of minimal, partial, full, and stabs symbols, the number of types 39400defined by the objfile, the number of as yet unexpanded psym tables, 39401the number of line tables and string tables, and the amount of memory 39402used by the various tables. The bcache statistics include the counts, 39403sizes, and counts of duplicates of all and unique objects, max, 39404average, and median entry size, total memory used and its overhead and 39405savings, and various measures of the hash table size and chain 39406lengths. 39407 39408@kindex maint print target-stack 39409@cindex target stack description 39410@item maint print target-stack 39411A @dfn{target} is an interface between the debugger and a particular 39412kind of file or process. Targets can be stacked in @dfn{strata}, 39413so that more than one target can potentially respond to a request. 39414In particular, memory accesses will walk down the stack of targets 39415until they find a target that is interested in handling that particular 39416address. 39417 39418This command prints a short description of each layer that was pushed on 39419the @dfn{target stack}, starting from the top layer down to the bottom one. 39420 39421@kindex maint print type 39422@cindex type chain of a data type 39423@item maint print type @var{expr} 39424Print the type chain for a type specified by @var{expr}. The argument 39425can be either a type name or a symbol. If it is a symbol, the type of 39426that symbol is described. The type chain produced by this command is 39427a recursive definition of the data type as stored in @value{GDBN}'s 39428data structures, including its flags and contained types. 39429 39430@kindex maint selftest 39431@cindex self tests 39432@item maint selftest @r{[}@var{filter}@r{]} 39433Run any self tests that were compiled in to @value{GDBN}. This will 39434print a message showing how many tests were run, and how many failed. 39435If a @var{filter} is passed, only the tests with @var{filter} in their 39436name will by ran. 39437 39438@kindex maint info selftests 39439@cindex self tests 39440@item maint info selftests 39441List the selftests compiled in to @value{GDBN}. 39442 39443@kindex maint set dwarf always-disassemble 39444@kindex maint show dwarf always-disassemble 39445@item maint set dwarf always-disassemble 39446@item maint show dwarf always-disassemble 39447Control the behavior of @code{info address} when using DWARF debugging 39448information. 39449 39450The default is @code{off}, which means that @value{GDBN} should try to 39451describe a variable's location in an easily readable format. When 39452@code{on}, @value{GDBN} will instead display the DWARF location 39453expression in an assembly-like format. Note that some locations are 39454too complex for @value{GDBN} to describe simply; in this case you will 39455always see the disassembly form. 39456 39457Here is an example of the resulting disassembly: 39458 39459@smallexample 39460(gdb) info addr argc 39461Symbol "argc" is a complex DWARF expression: 39462 1: DW_OP_fbreg 0 39463@end smallexample 39464 39465For more information on these expressions, see 39466@uref{http://www.dwarfstd.org/, the DWARF standard}. 39467 39468@kindex maint set dwarf max-cache-age 39469@kindex maint show dwarf max-cache-age 39470@item maint set dwarf max-cache-age 39471@itemx maint show dwarf max-cache-age 39472Control the DWARF compilation unit cache. 39473 39474@cindex DWARF compilation units cache 39475In object files with inter-compilation-unit references, such as those 39476produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 39477reader needs to frequently refer to previously read compilation units. 39478This setting controls how long a compilation unit will remain in the 39479cache if it is not referenced. A higher limit means that cached 39480compilation units will be stored in memory longer, and more total 39481memory will be used. Setting it to zero disables caching, which will 39482slow down @value{GDBN} startup, but reduce memory consumption. 39483 39484@kindex maint set dwarf unwinders 39485@kindex maint show dwarf unwinders 39486@item maint set dwarf unwinders 39487@itemx maint show dwarf unwinders 39488Control use of the DWARF frame unwinders. 39489 39490@cindex DWARF frame unwinders 39491Many targets that support DWARF debugging use @value{GDBN}'s DWARF 39492frame unwinders to build the backtrace. Many of these targets will 39493also have a second mechanism for building the backtrace for use in 39494cases where DWARF information is not available, this second mechanism 39495is often an analysis of a function's prologue. 39496 39497In order to extend testing coverage of the second level stack 39498unwinding mechanisms it is helpful to be able to disable the DWARF 39499stack unwinders, this can be done with this switch. 39500 39501In normal use of @value{GDBN} disabling the DWARF unwinders is not 39502advisable, there are cases that are better handled through DWARF than 39503prologue analysis, and the debug experience is likely to be better 39504with the DWARF frame unwinders enabled. 39505 39506If DWARF frame unwinders are not supported for a particular target 39507architecture, then enabling this flag does not cause them to be used. 39508 39509@kindex maint set worker-threads 39510@kindex maint show worker-threads 39511@item maint set worker-threads 39512@item maint show worker-threads 39513Control the number of worker threads that may be used by @value{GDBN}. 39514On capable hosts, @value{GDBN} may use multiple threads to speed up 39515certain CPU-intensive operations, such as demangling symbol names. 39516While the number of threads used by @value{GDBN} may vary, this 39517command can be used to set an upper bound on this number. The default 39518is @code{unlimited}, which lets @value{GDBN} choose a reasonable 39519number. Note that this only controls worker threads started by 39520@value{GDBN} itself; libraries used by @value{GDBN} may start threads 39521of their own. 39522 39523@kindex maint set profile 39524@kindex maint show profile 39525@cindex profiling GDB 39526@item maint set profile 39527@itemx maint show profile 39528Control profiling of @value{GDBN}. 39529 39530Profiling will be disabled until you use the @samp{maint set profile} 39531command to enable it. When you enable profiling, the system will begin 39532collecting timing and execution count data; when you disable profiling or 39533exit @value{GDBN}, the results will be written to a log file. Remember that 39534if you use profiling, @value{GDBN} will overwrite the profiling log file 39535(often called @file{gmon.out}). If you have a record of important profiling 39536data in a @file{gmon.out} file, be sure to move it to a safe location. 39537 39538Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be 39539compiled with the @samp{-pg} compiler option. 39540 39541@kindex maint set show-debug-regs 39542@kindex maint show show-debug-regs 39543@cindex hardware debug registers 39544@item maint set show-debug-regs 39545@itemx maint show show-debug-regs 39546Control whether to show variables that mirror the hardware debug 39547registers. Use @code{on} to enable, @code{off} to disable. If 39548enabled, the debug registers values are shown when @value{GDBN} inserts or 39549removes a hardware breakpoint or watchpoint, and when the inferior 39550triggers a hardware-assisted breakpoint or watchpoint. 39551 39552@kindex maint set show-all-tib 39553@kindex maint show show-all-tib 39554@item maint set show-all-tib 39555@itemx maint show show-all-tib 39556Control whether to show all non zero areas within a 1k block starting 39557at thread local base, when using the @samp{info w32 thread-information-block} 39558command. 39559 39560@kindex maint set target-async 39561@kindex maint show target-async 39562@item maint set target-async 39563@itemx maint show target-async 39564This controls whether @value{GDBN} targets operate in synchronous or 39565asynchronous mode (@pxref{Background Execution}). Normally the 39566default is asynchronous, if it is available; but this can be changed 39567to more easily debug problems occurring only in synchronous mode. 39568 39569@kindex maint set target-non-stop @var{mode} [on|off|auto] 39570@kindex maint show target-non-stop 39571@item maint set target-non-stop 39572@itemx maint show target-non-stop 39573 39574This controls whether @value{GDBN} targets always operate in non-stop 39575mode even if @code{set non-stop} is @code{off} (@pxref{Non-Stop 39576Mode}). The default is @code{auto}, meaning non-stop mode is enabled 39577if supported by the target. 39578 39579@table @code 39580@item maint set target-non-stop auto 39581This is the default mode. @value{GDBN} controls the target in 39582non-stop mode if the target supports it. 39583 39584@item maint set target-non-stop on 39585@value{GDBN} controls the target in non-stop mode even if the target 39586does not indicate support. 39587 39588@item maint set target-non-stop off 39589@value{GDBN} does not control the target in non-stop mode even if the 39590target supports it. 39591@end table 39592 39593@kindex maint set tui-resize-message 39594@kindex maint show tui-resize-message 39595@item maint set tui-resize-message 39596@item maint show tui-resize-message 39597Control whether @value{GDBN} displays a message each time the terminal 39598is resized when in TUI mode. The default is @code{off}, which means 39599that @value{GDBN} is silent during resizes. When @code{on}, 39600@value{GDBN} will display a message after a resize is completed; the 39601message will include a number indicating how many times the terminal 39602has been resized. This setting is intended for use by the test suite, 39603where it would otherwise be difficult to determine when a resize and 39604refresh has been completed. 39605 39606@kindex maint set per-command 39607@kindex maint show per-command 39608@item maint set per-command 39609@itemx maint show per-command 39610@cindex resources used by commands 39611 39612@value{GDBN} can display the resources used by each command. 39613This is useful in debugging performance problems. 39614 39615@table @code 39616@item maint set per-command space [on|off] 39617@itemx maint show per-command space 39618Enable or disable the printing of the memory used by GDB for each command. 39619If enabled, @value{GDBN} will display how much memory each command 39620took, following the command's own output. 39621This can also be requested by invoking @value{GDBN} with the 39622@option{--statistics} command-line switch (@pxref{Mode Options}). 39623 39624@item maint set per-command time [on|off] 39625@itemx maint show per-command time 39626Enable or disable the printing of the execution time of @value{GDBN} 39627for each command. 39628If enabled, @value{GDBN} will display how much time it 39629took to execute each command, following the command's own output. 39630Both CPU time and wallclock time are printed. 39631Printing both is useful when trying to determine whether the cost is 39632CPU or, e.g., disk/network latency. 39633Note that the CPU time printed is for @value{GDBN} only, it does not include 39634the execution time of the inferior because there's no mechanism currently 39635to compute how much time was spent by @value{GDBN} and how much time was 39636spent by the program been debugged. 39637This can also be requested by invoking @value{GDBN} with the 39638@option{--statistics} command-line switch (@pxref{Mode Options}). 39639 39640@item maint set per-command symtab [on|off] 39641@itemx maint show per-command symtab 39642Enable or disable the printing of basic symbol table statistics 39643for each command. 39644If enabled, @value{GDBN} will display the following information: 39645 39646@enumerate a 39647@item 39648number of symbol tables 39649@item 39650number of primary symbol tables 39651@item 39652number of blocks in the blockvector 39653@end enumerate 39654@end table 39655 39656@kindex maint set check-libthread-db 39657@kindex maint show check-libthread-db 39658@item maint set check-libthread-db [on|off] 39659@itemx maint show check-libthread-db 39660Control whether @value{GDBN} should run integrity checks on inferior 39661specific thread debugging libraries as they are loaded. The default 39662is not to perform such checks. If any check fails @value{GDBN} will 39663unload the library and continue searching for a suitable candidate as 39664described in @ref{set libthread-db-search-path}. For more information 39665about the tests, see @ref{maint check libthread-db}. 39666 39667@kindex maint space 39668@cindex memory used by commands 39669@item maint space @var{value} 39670An alias for @code{maint set per-command space}. 39671A non-zero value enables it, zero disables it. 39672 39673@kindex maint time 39674@cindex time of command execution 39675@item maint time @var{value} 39676An alias for @code{maint set per-command time}. 39677A non-zero value enables it, zero disables it. 39678 39679@kindex maint translate-address 39680@item maint translate-address @r{[}@var{section}@r{]} @var{addr} 39681Find the symbol stored at the location specified by the address 39682@var{addr} and an optional section name @var{section}. If found, 39683@value{GDBN} prints the name of the closest symbol and an offset from 39684the symbol's location to the specified address. This is similar to 39685the @code{info address} command (@pxref{Symbols}), except that this 39686command also allows to find symbols in other sections. 39687 39688If section was not specified, the section in which the symbol was found 39689is also printed. For dynamically linked executables, the name of 39690executable or shared library containing the symbol is printed as well. 39691 39692@kindex maint test-options 39693@item maint test-options require-delimiter 39694@itemx maint test-options unknown-is-error 39695@itemx maint test-options unknown-is-operand 39696These commands are used by the testsuite to validate the command 39697options framework. The @code{require-delimiter} variant requires a 39698double-dash delimiter to indicate end of options. The 39699@code{unknown-is-error} and @code{unknown-is-operand} do not. The 39700@code{unknown-is-error} variant throws an error on unknown option, 39701while @code{unknown-is-operand} treats unknown options as the start of 39702the command's operands. When run, the commands output the result of 39703the processed options. When completed, the commands store the 39704internal result of completion in a variable exposed by the @code{maint 39705show test-options-completion-result} command. 39706 39707@kindex maint show test-options-completion-result 39708@item maint show test-options-completion-result 39709Shows the result of completing the @code{maint test-options} 39710subcommands. This is used by the testsuite to validate completion 39711support in the command options framework. 39712 39713@kindex maint set test-settings 39714@kindex maint show test-settings 39715@item maint set test-settings @var{kind} 39716@itemx maint show test-settings @var{kind} 39717These are representative commands for each @var{kind} of setting type 39718@value{GDBN} supports. They are used by the testsuite for exercising 39719the settings infrastructure. 39720 39721@kindex maint with 39722@item maint with @var{setting} [@var{value}] [-- @var{command}] 39723Like the @code{with} command, but works with @code{maintenance set} 39724variables. This is used by the testsuite to exercise the @code{with} 39725command's infrastructure. 39726 39727@end table 39728 39729The following command is useful for non-interactive invocations of 39730@value{GDBN}, such as in the test suite. 39731 39732@table @code 39733@item set watchdog @var{nsec} 39734@kindex set watchdog 39735@cindex watchdog timer 39736@cindex timeout for commands 39737Set the maximum number of seconds @value{GDBN} will wait for the 39738target operation to finish. If this time expires, @value{GDBN} 39739reports and error and the command is aborted. 39740 39741@item show watchdog 39742Show the current setting of the target wait timeout. 39743@end table 39744 39745@node Remote Protocol 39746@appendix @value{GDBN} Remote Serial Protocol 39747 39748@menu 39749* Overview:: 39750* Packets:: 39751* Stop Reply Packets:: 39752* General Query Packets:: 39753* Architecture-Specific Protocol Details:: 39754* Tracepoint Packets:: 39755* Host I/O Packets:: 39756* Interrupts:: 39757* Notification Packets:: 39758* Remote Non-Stop:: 39759* Packet Acknowledgment:: 39760* Examples:: 39761* File-I/O Remote Protocol Extension:: 39762* Library List Format:: 39763* Library List Format for SVR4 Targets:: 39764* Memory Map Format:: 39765* Thread List Format:: 39766* Traceframe Info Format:: 39767* Branch Trace Format:: 39768* Branch Trace Configuration Format:: 39769@end menu 39770 39771@node Overview 39772@section Overview 39773 39774There may be occasions when you need to know something about the 39775protocol---for example, if there is only one serial port to your target 39776machine, you might want your program to do something special if it 39777recognizes a packet meant for @value{GDBN}. 39778 39779In the examples below, @samp{->} and @samp{<-} are used to indicate 39780transmitted and received data, respectively. 39781 39782@cindex protocol, @value{GDBN} remote serial 39783@cindex serial protocol, @value{GDBN} remote 39784@cindex remote serial protocol 39785All @value{GDBN} commands and responses (other than acknowledgments 39786and notifications, see @ref{Notification Packets}) are sent as a 39787@var{packet}. A @var{packet} is introduced with the character 39788@samp{$}, the actual @var{packet-data}, and the terminating character 39789@samp{#} followed by a two-digit @var{checksum}: 39790 39791@smallexample 39792@code{$}@var{packet-data}@code{#}@var{checksum} 39793@end smallexample 39794@noindent 39795 39796@cindex checksum, for @value{GDBN} remote 39797@noindent 39798The two-digit @var{checksum} is computed as the modulo 256 sum of all 39799characters between the leading @samp{$} and the trailing @samp{#} (an 39800eight bit unsigned checksum). 39801 39802Implementors should note that prior to @value{GDBN} 5.0 the protocol 39803specification also included an optional two-digit @var{sequence-id}: 39804 39805@smallexample 39806@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} 39807@end smallexample 39808 39809@cindex sequence-id, for @value{GDBN} remote 39810@noindent 39811That @var{sequence-id} was appended to the acknowledgment. @value{GDBN} 39812has never output @var{sequence-id}s. Stubs that handle packets added 39813since @value{GDBN} 5.0 must not accept @var{sequence-id}. 39814 39815When either the host or the target machine receives a packet, the first 39816response expected is an acknowledgment: either @samp{+} (to indicate 39817the package was received correctly) or @samp{-} (to request 39818retransmission): 39819 39820@smallexample 39821-> @code{$}@var{packet-data}@code{#}@var{checksum} 39822<- @code{+} 39823@end smallexample 39824@noindent 39825 39826The @samp{+}/@samp{-} acknowledgments can be disabled 39827once a connection is established. 39828@xref{Packet Acknowledgment}, for details. 39829 39830The host (@value{GDBN}) sends @var{command}s, and the target (the 39831debugging stub incorporated in your program) sends a @var{response}. In 39832the case of step and continue @var{command}s, the response is only sent 39833when the operation has completed, and the target has again stopped all 39834threads in all attached processes. This is the default all-stop mode 39835behavior, but the remote protocol also supports @value{GDBN}'s non-stop 39836execution mode; see @ref{Remote Non-Stop}, for details. 39837 39838@var{packet-data} consists of a sequence of characters with the 39839exception of @samp{#} and @samp{$} (see @samp{X} packet for additional 39840exceptions). 39841 39842@cindex remote protocol, field separator 39843Fields within the packet should be separated using @samp{,} @samp{;} or 39844@samp{:}. Except where otherwise noted all numbers are represented in 39845@sc{hex} with leading zeros suppressed. 39846 39847Implementors should note that prior to @value{GDBN} 5.0, the character 39848@samp{:} could not appear as the third character in a packet (as it 39849would potentially conflict with the @var{sequence-id}). 39850 39851@cindex remote protocol, binary data 39852@anchor{Binary Data} 39853Binary data in most packets is encoded either as two hexadecimal 39854digits per byte of binary data. This allowed the traditional remote 39855protocol to work over connections which were only seven-bit clean. 39856Some packets designed more recently assume an eight-bit clean 39857connection, and use a more efficient encoding to send and receive 39858binary data. 39859 39860The binary data representation uses @code{7d} (@sc{ascii} @samp{@}}) 39861as an escape character. Any escaped byte is transmitted as the escape 39862character followed by the original character XORed with @code{0x20}. 39863For example, the byte @code{0x7d} would be transmitted as the two 39864bytes @code{0x7d 0x5d}. The bytes @code{0x23} (@sc{ascii} @samp{#}), 39865@code{0x24} (@sc{ascii} @samp{$}), and @code{0x7d} (@sc{ascii} 39866@samp{@}}) must always be escaped. Responses sent by the stub 39867must also escape @code{0x2a} (@sc{ascii} @samp{*}), so that it 39868is not interpreted as the start of a run-length encoded sequence 39869(described next). 39870 39871Response @var{data} can be run-length encoded to save space. 39872Run-length encoding replaces runs of identical characters with one 39873instance of the repeated character, followed by a @samp{*} and a 39874repeat count. The repeat count is itself sent encoded, to avoid 39875binary characters in @var{data}: a value of @var{n} is sent as 39876@code{@var{n}+29}. For a repeat count greater or equal to 3, this 39877produces a printable @sc{ascii} character, e.g.@: a space (@sc{ascii} 39878code 32) for a repeat count of 3. (This is because run-length 39879encoding starts to win for counts 3 or more.) Thus, for example, 39880@samp{0* } is a run-length encoding of ``0000'': the space character 39881after @samp{*} means repeat the leading @code{0} @w{@code{32 - 29 = 398823}} more times. 39883 39884The printable characters @samp{#} and @samp{$} or with a numeric value 39885greater than 126 must not be used. Runs of six repeats (@samp{#}) or 39886seven repeats (@samp{$}) can be expanded using a repeat count of only 39887five (@samp{"}). For example, @samp{00000000} can be encoded as 39888@samp{0*"00}. 39889 39890The error response returned for some packets includes a two character 39891error number. That number is not well defined. 39892 39893@cindex empty response, for unsupported packets 39894For any @var{command} not supported by the stub, an empty response 39895(@samp{$#00}) should be returned. That way it is possible to extend the 39896protocol. A newer @value{GDBN} can tell if a packet is supported based 39897on that response. 39898 39899At a minimum, a stub is required to support the @samp{?} command to 39900tell @value{GDBN} the reason for halting, @samp{g} and @samp{G} 39901commands for register access, and the @samp{m} and @samp{M} commands 39902for memory access. Stubs that only control single-threaded targets 39903can implement run control with the @samp{c} (continue) command, and if 39904the target architecture supports hardware-assisted single-stepping, 39905the @samp{s} (step) command. Stubs that support multi-threading 39906targets should support the @samp{vCont} command. All other commands 39907are optional. 39908 39909@node Packets 39910@section Packets 39911 39912The following table provides a complete list of all currently defined 39913@var{command}s and their corresponding response @var{data}. 39914@xref{File-I/O Remote Protocol Extension}, for details about the File 39915I/O extension of the remote protocol. 39916 39917Each packet's description has a template showing the packet's overall 39918syntax, followed by an explanation of the packet's meaning. We 39919include spaces in some of the templates for clarity; these are not 39920part of the packet's syntax. No @value{GDBN} packet uses spaces to 39921separate its components. For example, a template like @samp{foo 39922@var{bar} @var{baz}} describes a packet beginning with the three ASCII 39923bytes @samp{foo}, followed by a @var{bar}, followed directly by a 39924@var{baz}. @value{GDBN} does not transmit a space character between the 39925@samp{foo} and the @var{bar}, or between the @var{bar} and the 39926@var{baz}. 39927 39928@cindex @var{thread-id}, in remote protocol 39929@anchor{thread-id syntax} 39930Several packets and replies include a @var{thread-id} field to identify 39931a thread. Normally these are positive numbers with a target-specific 39932interpretation, formatted as big-endian hex strings. A @var{thread-id} 39933can also be a literal @samp{-1} to indicate all threads, or @samp{0} to 39934pick any thread. 39935 39936In addition, the remote protocol supports a multiprocess feature in 39937which the @var{thread-id} syntax is extended to optionally include both 39938process and thread ID fields, as @samp{p@var{pid}.@var{tid}}. 39939The @var{pid} (process) and @var{tid} (thread) components each have the 39940format described above: a positive number with target-specific 39941interpretation formatted as a big-endian hex string, literal @samp{-1} 39942to indicate all processes or threads (respectively), or @samp{0} to 39943indicate an arbitrary process or thread. Specifying just a process, as 39944@samp{p@var{pid}}, is equivalent to @samp{p@var{pid}.-1}. It is an 39945error to specify all processes but a specific thread, such as 39946@samp{p-1.@var{tid}}. Note that the @samp{p} prefix is @emph{not} used 39947for those packets and replies explicitly documented to include a process 39948ID, rather than a @var{thread-id}. 39949 39950The multiprocess @var{thread-id} syntax extensions are only used if both 39951@value{GDBN} and the stub report support for the @samp{multiprocess} 39952feature using @samp{qSupported}. @xref{multiprocess extensions}, for 39953more information. 39954 39955Note that all packet forms beginning with an upper- or lower-case 39956letter, other than those described here, are reserved for future use. 39957 39958Here are the packet descriptions. 39959 39960@table @samp 39961 39962@item ! 39963@cindex @samp{!} packet 39964@anchor{extended mode} 39965Enable extended mode. In extended mode, the remote server is made 39966persistent. The @samp{R} packet is used to restart the program being 39967debugged. 39968 39969Reply: 39970@table @samp 39971@item OK 39972The remote target both supports and has enabled extended mode. 39973@end table 39974 39975@item ? 39976@cindex @samp{?} packet 39977@anchor{? packet} 39978This is sent when connection is first established to query the reason 39979the target halted. The reply is the same as for step and continue. 39980This packet has a special interpretation when the target is in 39981non-stop mode; see @ref{Remote Non-Stop}. 39982 39983Reply: 39984@xref{Stop Reply Packets}, for the reply specifications. 39985 39986@item A @var{arglen},@var{argnum},@var{arg},@dots{} 39987@cindex @samp{A} packet 39988Initialized @code{argv[]} array passed into program. @var{arglen} 39989specifies the number of bytes in the hex encoded byte stream 39990@var{arg}. See @code{gdbserver} for more details. 39991 39992Reply: 39993@table @samp 39994@item OK 39995The arguments were set. 39996@item E @var{NN} 39997An error occurred. 39998@end table 39999 40000@item b @var{baud} 40001@cindex @samp{b} packet 40002(Don't use this packet; its behavior is not well-defined.) 40003Change the serial line speed to @var{baud}. 40004 40005JTC: @emph{When does the transport layer state change? When it's 40006received, or after the ACK is transmitted. In either case, there are 40007problems if the command or the acknowledgment packet is dropped.} 40008 40009Stan: @emph{If people really wanted to add something like this, and get 40010it working for the first time, they ought to modify ser-unix.c to send 40011some kind of out-of-band message to a specially-setup stub and have the 40012switch happen "in between" packets, so that from remote protocol's point 40013of view, nothing actually happened.} 40014 40015@item B @var{addr},@var{mode} 40016@cindex @samp{B} packet 40017Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a 40018breakpoint at @var{addr}. 40019 40020Don't use this packet. Use the @samp{Z} and @samp{z} packets instead 40021(@pxref{insert breakpoint or watchpoint packet}). 40022 40023@cindex @samp{bc} packet 40024@anchor{bc} 40025@item bc 40026Backward continue. Execute the target system in reverse. No parameter. 40027@xref{Reverse Execution}, for more information. 40028 40029Reply: 40030@xref{Stop Reply Packets}, for the reply specifications. 40031 40032@cindex @samp{bs} packet 40033@anchor{bs} 40034@item bs 40035Backward single step. Execute one instruction in reverse. No parameter. 40036@xref{Reverse Execution}, for more information. 40037 40038Reply: 40039@xref{Stop Reply Packets}, for the reply specifications. 40040 40041@item c @r{[}@var{addr}@r{]} 40042@cindex @samp{c} packet 40043Continue at @var{addr}, which is the address to resume. If @var{addr} 40044is omitted, resume at current address. 40045 40046This packet is deprecated for multi-threading support. @xref{vCont 40047packet}. 40048 40049Reply: 40050@xref{Stop Reply Packets}, for the reply specifications. 40051 40052@item C @var{sig}@r{[};@var{addr}@r{]} 40053@cindex @samp{C} packet 40054Continue with signal @var{sig} (hex signal number). If 40055@samp{;@var{addr}} is omitted, resume at same address. 40056 40057This packet is deprecated for multi-threading support. @xref{vCont 40058packet}. 40059 40060Reply: 40061@xref{Stop Reply Packets}, for the reply specifications. 40062 40063@item d 40064@cindex @samp{d} packet 40065Toggle debug flag. 40066 40067Don't use this packet; instead, define a general set packet 40068(@pxref{General Query Packets}). 40069 40070@item D 40071@itemx D;@var{pid} 40072@cindex @samp{D} packet 40073The first form of the packet is used to detach @value{GDBN} from the 40074remote system. It is sent to the remote target 40075before @value{GDBN} disconnects via the @code{detach} command. 40076 40077The second form, including a process ID, is used when multiprocess 40078protocol extensions are enabled (@pxref{multiprocess extensions}), to 40079detach only a specific process. The @var{pid} is specified as a 40080big-endian hex string. 40081 40082Reply: 40083@table @samp 40084@item OK 40085for success 40086@item E @var{NN} 40087for an error 40088@end table 40089 40090@item F @var{RC},@var{EE},@var{CF};@var{XX} 40091@cindex @samp{F} packet 40092A reply from @value{GDBN} to an @samp{F} packet sent by the target. 40093This is part of the File-I/O protocol extension. @xref{File-I/O 40094Remote Protocol Extension}, for the specification. 40095 40096@item g 40097@anchor{read registers packet} 40098@cindex @samp{g} packet 40099Read general registers. 40100 40101Reply: 40102@table @samp 40103@item @var{XX@dots{}} 40104Each byte of register data is described by two hex digits. The bytes 40105with the register are transmitted in target byte order. The size of 40106each register and their position within the @samp{g} packet are 40107determined by the @value{GDBN} internal gdbarch functions 40108@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}. 40109 40110When reading registers from a trace frame (@pxref{Analyze Collected 40111Data,,Using the Collected Data}), the stub may also return a string of 40112literal @samp{x}'s in place of the register data digits, to indicate 40113that the corresponding register has not been collected, thus its value 40114is unavailable. For example, for an architecture with 4 registers of 401154 bytes each, the following reply indicates to @value{GDBN} that 40116registers 0 and 2 have not been collected, while registers 1 and 3 40117have been collected, and both have zero value: 40118 40119@smallexample 40120-> @code{g} 40121<- @code{xxxxxxxx00000000xxxxxxxx00000000} 40122@end smallexample 40123 40124@item E @var{NN} 40125for an error. 40126@end table 40127 40128@item G @var{XX@dots{}} 40129@cindex @samp{G} packet 40130Write general registers. @xref{read registers packet}, for a 40131description of the @var{XX@dots{}} data. 40132 40133Reply: 40134@table @samp 40135@item OK 40136for success 40137@item E @var{NN} 40138for an error 40139@end table 40140 40141@item H @var{op} @var{thread-id} 40142@cindex @samp{H} packet 40143Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g}, 40144@samp{G}, et.al.). Depending on the operation to be performed, @var{op} 40145should be @samp{c} for step and continue operations (note that this 40146is deprecated, supporting the @samp{vCont} command is a better 40147option), and @samp{g} for other operations. The thread designator 40148@var{thread-id} has the format and interpretation described in 40149@ref{thread-id syntax}. 40150 40151Reply: 40152@table @samp 40153@item OK 40154for success 40155@item E @var{NN} 40156for an error 40157@end table 40158 40159@c FIXME: JTC: 40160@c 'H': How restrictive (or permissive) is the thread model. If a 40161@c thread is selected and stopped, are other threads allowed 40162@c to continue to execute? As I mentioned above, I think the 40163@c semantics of each command when a thread is selected must be 40164@c described. For example: 40165@c 40166@c 'g': If the stub supports threads and a specific thread is 40167@c selected, returns the register block from that thread; 40168@c otherwise returns current registers. 40169@c 40170@c 'G' If the stub supports threads and a specific thread is 40171@c selected, sets the registers of the register block of 40172@c that thread; otherwise sets current registers. 40173 40174@item i @r{[}@var{addr}@r{[},@var{nnn}@r{]]} 40175@anchor{cycle step packet} 40176@cindex @samp{i} packet 40177Step the remote target by a single clock cycle. If @samp{,@var{nnn}} is 40178present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle 40179step starting at that address. 40180 40181@item I 40182@cindex @samp{I} packet 40183Signal, then cycle step. @xref{step with signal packet}. @xref{cycle 40184step packet}. 40185 40186@item k 40187@cindex @samp{k} packet 40188Kill request. 40189 40190The exact effect of this packet is not specified. 40191 40192For a bare-metal target, it may power cycle or reset the target 40193system. For that reason, the @samp{k} packet has no reply. 40194 40195For a single-process target, it may kill that process if possible. 40196 40197A multiple-process target may choose to kill just one process, or all 40198that are under @value{GDBN}'s control. For more precise control, use 40199the vKill packet (@pxref{vKill packet}). 40200 40201If the target system immediately closes the connection in response to 40202@samp{k}, @value{GDBN} does not consider the lack of packet 40203acknowledgment to be an error, and assumes the kill was successful. 40204 40205If connected using @kbd{target extended-remote}, and the target does 40206not close the connection in response to a kill request, @value{GDBN} 40207probes the target state as if a new connection was opened 40208(@pxref{? packet}). 40209 40210@item m @var{addr},@var{length} 40211@cindex @samp{m} packet 40212Read @var{length} addressable memory units starting at address @var{addr} 40213(@pxref{addressable memory unit}). Note that @var{addr} may not be aligned to 40214any particular boundary. 40215 40216The stub need not use any particular size or alignment when gathering 40217data from memory for the response; even if @var{addr} is word-aligned 40218and @var{length} is a multiple of the word size, the stub is free to 40219use byte accesses, or not. For this reason, this packet may not be 40220suitable for accessing memory-mapped I/O devices. 40221@cindex alignment of remote memory accesses 40222@cindex size of remote memory accesses 40223@cindex memory, alignment and size of remote accesses 40224 40225Reply: 40226@table @samp 40227@item @var{XX@dots{}} 40228Memory contents; each byte is transmitted as a two-digit hexadecimal number. 40229The reply may contain fewer addressable memory units than requested if the 40230server was able to read only part of the region of memory. 40231@item E @var{NN} 40232@var{NN} is errno 40233@end table 40234 40235@item M @var{addr},@var{length}:@var{XX@dots{}} 40236@cindex @samp{M} packet 40237Write @var{length} addressable memory units starting at address @var{addr} 40238(@pxref{addressable memory unit}). The data is given by @var{XX@dots{}}; each 40239byte is transmitted as a two-digit hexadecimal number. 40240 40241Reply: 40242@table @samp 40243@item OK 40244for success 40245@item E @var{NN} 40246for an error (this includes the case where only part of the data was 40247written). 40248@end table 40249 40250@item p @var{n} 40251@cindex @samp{p} packet 40252Read the value of register @var{n}; @var{n} is in hex. 40253@xref{read registers packet}, for a description of how the returned 40254register value is encoded. 40255 40256Reply: 40257@table @samp 40258@item @var{XX@dots{}} 40259the register's value 40260@item E @var{NN} 40261for an error 40262@item @w{} 40263Indicating an unrecognized @var{query}. 40264@end table 40265 40266@item P @var{n@dots{}}=@var{r@dots{}} 40267@anchor{write register packet} 40268@cindex @samp{P} packet 40269Write register @var{n@dots{}} with value @var{r@dots{}}. The register 40270number @var{n} is in hexadecimal, and @var{r@dots{}} contains two hex 40271digits for each byte in the register (target byte order). 40272 40273Reply: 40274@table @samp 40275@item OK 40276for success 40277@item E @var{NN} 40278for an error 40279@end table 40280 40281@item q @var{name} @var{params}@dots{} 40282@itemx Q @var{name} @var{params}@dots{} 40283@cindex @samp{q} packet 40284@cindex @samp{Q} packet 40285General query (@samp{q}) and set (@samp{Q}). These packets are 40286described fully in @ref{General Query Packets}. 40287 40288@item r 40289@cindex @samp{r} packet 40290Reset the entire system. 40291 40292Don't use this packet; use the @samp{R} packet instead. 40293 40294@item R @var{XX} 40295@cindex @samp{R} packet 40296Restart the program being debugged. The @var{XX}, while needed, is ignored. 40297This packet is only available in extended mode (@pxref{extended mode}). 40298 40299The @samp{R} packet has no reply. 40300 40301@item s @r{[}@var{addr}@r{]} 40302@cindex @samp{s} packet 40303Single step, resuming at @var{addr}. If 40304@var{addr} is omitted, resume at same address. 40305 40306This packet is deprecated for multi-threading support. @xref{vCont 40307packet}. 40308 40309Reply: 40310@xref{Stop Reply Packets}, for the reply specifications. 40311 40312@item S @var{sig}@r{[};@var{addr}@r{]} 40313@anchor{step with signal packet} 40314@cindex @samp{S} packet 40315Step with signal. This is analogous to the @samp{C} packet, but 40316requests a single-step, rather than a normal resumption of execution. 40317 40318This packet is deprecated for multi-threading support. @xref{vCont 40319packet}. 40320 40321Reply: 40322@xref{Stop Reply Packets}, for the reply specifications. 40323 40324@item t @var{addr}:@var{PP},@var{MM} 40325@cindex @samp{t} packet 40326Search backwards starting at address @var{addr} for a match with pattern 40327@var{PP} and mask @var{MM}, both of which are are 4 byte long. 40328There must be at least 3 digits in @var{addr}. 40329 40330@item T @var{thread-id} 40331@cindex @samp{T} packet 40332Find out if the thread @var{thread-id} is alive. @xref{thread-id syntax}. 40333 40334Reply: 40335@table @samp 40336@item OK 40337thread is still alive 40338@item E @var{NN} 40339thread is dead 40340@end table 40341 40342@item v 40343Packets starting with @samp{v} are identified by a multi-letter name, 40344up to the first @samp{;} or @samp{?} (or the end of the packet). 40345 40346@item vAttach;@var{pid} 40347@cindex @samp{vAttach} packet 40348Attach to a new process with the specified process ID @var{pid}. 40349The process ID is a 40350hexadecimal integer identifying the process. In all-stop mode, all 40351threads in the attached process are stopped; in non-stop mode, it may be 40352attached without being stopped if that is supported by the target. 40353 40354@c In non-stop mode, on a successful vAttach, the stub should set the 40355@c current thread to a thread of the newly-attached process. After 40356@c attaching, GDB queries for the attached process's thread ID with qC. 40357@c Also note that, from a user perspective, whether or not the 40358@c target is stopped on attach in non-stop mode depends on whether you 40359@c use the foreground or background version of the attach command, not 40360@c on what vAttach does; GDB does the right thing with respect to either 40361@c stopping or restarting threads. 40362 40363This packet is only available in extended mode (@pxref{extended mode}). 40364 40365Reply: 40366@table @samp 40367@item E @var{nn} 40368for an error 40369@item @r{Any stop packet} 40370for success in all-stop mode (@pxref{Stop Reply Packets}) 40371@item OK 40372for success in non-stop mode (@pxref{Remote Non-Stop}) 40373@end table 40374 40375@item vCont@r{[};@var{action}@r{[}:@var{thread-id}@r{]]}@dots{} 40376@cindex @samp{vCont} packet 40377@anchor{vCont packet} 40378Resume the inferior, specifying different actions for each thread. 40379 40380For each inferior thread, the leftmost action with a matching 40381@var{thread-id} is applied. Threads that don't match any action 40382remain in their current state. Thread IDs are specified using the 40383syntax described in @ref{thread-id syntax}. If multiprocess 40384extensions (@pxref{multiprocess extensions}) are supported, actions 40385can be specified to match all threads in a process by using the 40386@samp{p@var{pid}.-1} form of the @var{thread-id}. An action with no 40387@var{thread-id} matches all threads. Specifying no actions is an 40388error. 40389 40390Currently supported actions are: 40391 40392@table @samp 40393@item c 40394Continue. 40395@item C @var{sig} 40396Continue with signal @var{sig}. The signal @var{sig} should be two hex digits. 40397@item s 40398Step. 40399@item S @var{sig} 40400Step with signal @var{sig}. The signal @var{sig} should be two hex digits. 40401@item t 40402Stop. 40403@item r @var{start},@var{end} 40404Step once, and then keep stepping as long as the thread stops at 40405addresses between @var{start} (inclusive) and @var{end} (exclusive). 40406The remote stub reports a stop reply when either the thread goes out 40407of the range or is stopped due to an unrelated reason, such as hitting 40408a breakpoint. @xref{range stepping}. 40409 40410If the range is empty (@var{start} == @var{end}), then the action 40411becomes equivalent to the @samp{s} action. In other words, 40412single-step once, and report the stop (even if the stepped instruction 40413jumps to @var{start}). 40414 40415(A stop reply may be sent at any point even if the PC is still within 40416the stepping range; for example, it is valid to implement this packet 40417in a degenerate way as a single instruction step operation.) 40418 40419@end table 40420 40421The optional argument @var{addr} normally associated with the 40422@samp{c}, @samp{C}, @samp{s}, and @samp{S} packets is 40423not supported in @samp{vCont}. 40424 40425The @samp{t} action is only relevant in non-stop mode 40426(@pxref{Remote Non-Stop}) and may be ignored by the stub otherwise. 40427A stop reply should be generated for any affected thread not already stopped. 40428When a thread is stopped by means of a @samp{t} action, 40429the corresponding stop reply should indicate that the thread has stopped with 40430signal @samp{0}, regardless of whether the target uses some other signal 40431as an implementation detail. 40432 40433The server must ignore @samp{c}, @samp{C}, @samp{s}, @samp{S}, and 40434@samp{r} actions for threads that are already running. Conversely, 40435the server must ignore @samp{t} actions for threads that are already 40436stopped. 40437 40438@emph{Note:} In non-stop mode, a thread is considered running until 40439@value{GDBN} acknowledges an asynchronous stop notification for it with 40440the @samp{vStopped} packet (@pxref{Remote Non-Stop}). 40441 40442The stub must support @samp{vCont} if it reports support for 40443multiprocess extensions (@pxref{multiprocess extensions}). 40444 40445Reply: 40446@xref{Stop Reply Packets}, for the reply specifications. 40447 40448@item vCont? 40449@cindex @samp{vCont?} packet 40450Request a list of actions supported by the @samp{vCont} packet. 40451 40452Reply: 40453@table @samp 40454@item vCont@r{[};@var{action}@dots{}@r{]} 40455The @samp{vCont} packet is supported. Each @var{action} is a supported 40456command in the @samp{vCont} packet. 40457@item @w{} 40458The @samp{vCont} packet is not supported. 40459@end table 40460 40461@anchor{vCtrlC packet} 40462@item vCtrlC 40463@cindex @samp{vCtrlC} packet 40464Interrupt remote target as if a control-C was pressed on the remote 40465terminal. This is the equivalent to reacting to the @code{^C} 40466(@samp{\003}, the control-C character) character in all-stop mode 40467while the target is running, except this works in non-stop mode. 40468@xref{interrupting remote targets}, for more info on the all-stop 40469variant. 40470 40471Reply: 40472@table @samp 40473@item E @var{nn} 40474for an error 40475@item OK 40476for success 40477@end table 40478 40479@item vFile:@var{operation}:@var{parameter}@dots{} 40480@cindex @samp{vFile} packet 40481Perform a file operation on the target system. For details, 40482see @ref{Host I/O Packets}. 40483 40484@item vFlashErase:@var{addr},@var{length} 40485@cindex @samp{vFlashErase} packet 40486Direct the stub to erase @var{length} bytes of flash starting at 40487@var{addr}. The region may enclose any number of flash blocks, but 40488its start and end must fall on block boundaries, as indicated by the 40489flash block size appearing in the memory map (@pxref{Memory Map 40490Format}). @value{GDBN} groups flash memory programming operations 40491together, and sends a @samp{vFlashDone} request after each group; the 40492stub is allowed to delay erase operation until the @samp{vFlashDone} 40493packet is received. 40494 40495Reply: 40496@table @samp 40497@item OK 40498for success 40499@item E @var{NN} 40500for an error 40501@end table 40502 40503@item vFlashWrite:@var{addr}:@var{XX@dots{}} 40504@cindex @samp{vFlashWrite} packet 40505Direct the stub to write data to flash address @var{addr}. The data 40506is passed in binary form using the same encoding as for the @samp{X} 40507packet (@pxref{Binary Data}). The memory ranges specified by 40508@samp{vFlashWrite} packets preceding a @samp{vFlashDone} packet must 40509not overlap, and must appear in order of increasing addresses 40510(although @samp{vFlashErase} packets for higher addresses may already 40511have been received; the ordering is guaranteed only between 40512@samp{vFlashWrite} packets). If a packet writes to an address that was 40513neither erased by a preceding @samp{vFlashErase} packet nor by some other 40514target-specific method, the results are unpredictable. 40515 40516 40517Reply: 40518@table @samp 40519@item OK 40520for success 40521@item E.memtype 40522for vFlashWrite addressing non-flash memory 40523@item E @var{NN} 40524for an error 40525@end table 40526 40527@item vFlashDone 40528@cindex @samp{vFlashDone} packet 40529Indicate to the stub that flash programming operation is finished. 40530The stub is permitted to delay or batch the effects of a group of 40531@samp{vFlashErase} and @samp{vFlashWrite} packets until a 40532@samp{vFlashDone} packet is received. The contents of the affected 40533regions of flash memory are unpredictable until the @samp{vFlashDone} 40534request is completed. 40535 40536@item vKill;@var{pid} 40537@cindex @samp{vKill} packet 40538@anchor{vKill packet} 40539Kill the process with the specified process ID @var{pid}, which is a 40540hexadecimal integer identifying the process. This packet is used in 40541preference to @samp{k} when multiprocess protocol extensions are 40542supported; see @ref{multiprocess extensions}. 40543 40544Reply: 40545@table @samp 40546@item E @var{nn} 40547for an error 40548@item OK 40549for success 40550@end table 40551 40552@item vMustReplyEmpty 40553@cindex @samp{vMustReplyEmpty} packet 40554The correct reply to an unknown @samp{v} packet is to return the empty 40555string, however, some older versions of @command{gdbserver} would 40556incorrectly return @samp{OK} for unknown @samp{v} packets. 40557 40558The @samp{vMustReplyEmpty} is used as a feature test to check how 40559@command{gdbserver} handles unknown packets, it is important that this 40560packet be handled in the same way as other unknown @samp{v} packets. 40561If this packet is handled differently to other unknown @samp{v} 40562packets then it is possible that @value{GDBN} may run into problems in 40563other areas, specifically around use of @samp{vFile:setfs:}. 40564 40565@item vRun;@var{filename}@r{[};@var{argument}@r{]}@dots{} 40566@cindex @samp{vRun} packet 40567Run the program @var{filename}, passing it each @var{argument} on its 40568command line. The file and arguments are hex-encoded strings. If 40569@var{filename} is an empty string, the stub may use a default program 40570(e.g.@: the last program run). The program is created in the stopped 40571state. 40572 40573@c FIXME: What about non-stop mode? 40574 40575This packet is only available in extended mode (@pxref{extended mode}). 40576 40577Reply: 40578@table @samp 40579@item E @var{nn} 40580for an error 40581@item @r{Any stop packet} 40582for success (@pxref{Stop Reply Packets}) 40583@end table 40584 40585@item vStopped 40586@cindex @samp{vStopped} packet 40587@xref{Notification Packets}. 40588 40589@item X @var{addr},@var{length}:@var{XX@dots{}} 40590@anchor{X packet} 40591@cindex @samp{X} packet 40592Write data to memory, where the data is transmitted in binary. 40593Memory is specified by its address @var{addr} and number of addressable memory 40594units @var{length} (@pxref{addressable memory unit}); 40595@samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}). 40596 40597Reply: 40598@table @samp 40599@item OK 40600for success 40601@item E @var{NN} 40602for an error 40603@end table 40604 40605@item z @var{type},@var{addr},@var{kind} 40606@itemx Z @var{type},@var{addr},@var{kind} 40607@anchor{insert breakpoint or watchpoint packet} 40608@cindex @samp{z} packet 40609@cindex @samp{Z} packets 40610Insert (@samp{Z}) or remove (@samp{z}) a @var{type} breakpoint or 40611watchpoint starting at address @var{address} of kind @var{kind}. 40612 40613Each breakpoint and watchpoint packet @var{type} is documented 40614separately. 40615 40616@emph{Implementation notes: A remote target shall return an empty string 40617for an unrecognized breakpoint or watchpoint packet @var{type}. A 40618remote target shall support either both or neither of a given 40619@samp{Z@var{type}@dots{}} and @samp{z@var{type}@dots{}} packet pair. To 40620avoid potential problems with duplicate packets, the operations should 40621be implemented in an idempotent way.} 40622 40623@item z0,@var{addr},@var{kind} 40624@itemx Z0,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}@r{[};cmds:@var{persist},@var{cmd_list}@dots{}@r{]} 40625@cindex @samp{z0} packet 40626@cindex @samp{Z0} packet 40627Insert (@samp{Z0}) or remove (@samp{z0}) a software breakpoint at address 40628@var{addr} of type @var{kind}. 40629 40630A software breakpoint is implemented by replacing the instruction at 40631@var{addr} with a software breakpoint or trap instruction. The 40632@var{kind} is target-specific and typically indicates the size of the 40633breakpoint in bytes that should be inserted. E.g., the @sc{arm} and 40634@sc{mips} can insert either a 2 or 4 byte breakpoint. Some 40635architectures have additional meanings for @var{kind} 40636(@pxref{Architecture-Specific Protocol Details}); if no 40637architecture-specific value is being used, it should be @samp{0}. 40638@var{kind} is hex-encoded. @var{cond_list} is an optional list of 40639conditional expressions in bytecode form that should be evaluated on 40640the target's side. These are the conditions that should be taken into 40641consideration when deciding if the breakpoint trigger should be 40642reported back to @value{GDBN}. 40643 40644See also the @samp{swbreak} stop reason (@pxref{swbreak stop reason}) 40645for how to best report a software breakpoint event to @value{GDBN}. 40646 40647The @var{cond_list} parameter is comprised of a series of expressions, 40648concatenated without separators. Each expression has the following form: 40649 40650@table @samp 40651 40652@item X @var{len},@var{expr} 40653@var{len} is the length of the bytecode expression and @var{expr} is the 40654actual conditional expression in bytecode form. 40655 40656@end table 40657 40658The optional @var{cmd_list} parameter introduces commands that may be 40659run on the target, rather than being reported back to @value{GDBN}. 40660The parameter starts with a numeric flag @var{persist}; if the flag is 40661nonzero, then the breakpoint may remain active and the commands 40662continue to be run even when @value{GDBN} disconnects from the target. 40663Following this flag is a series of expressions concatenated with no 40664separators. Each expression has the following form: 40665 40666@table @samp 40667 40668@item X @var{len},@var{expr} 40669@var{len} is the length of the bytecode expression and @var{expr} is the 40670actual commands expression in bytecode form. 40671 40672@end table 40673 40674@emph{Implementation note: It is possible for a target to copy or move 40675code that contains software breakpoints (e.g., when implementing 40676overlays). The behavior of this packet, in the presence of such a 40677target, is not defined.} 40678 40679Reply: 40680@table @samp 40681@item OK 40682success 40683@item @w{} 40684not supported 40685@item E @var{NN} 40686for an error 40687@end table 40688 40689@item z1,@var{addr},@var{kind} 40690@itemx Z1,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}@r{[};cmds:@var{persist},@var{cmd_list}@dots{}@r{]} 40691@cindex @samp{z1} packet 40692@cindex @samp{Z1} packet 40693Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at 40694address @var{addr}. 40695 40696A hardware breakpoint is implemented using a mechanism that is not 40697dependent on being able to modify the target's memory. The 40698@var{kind}, @var{cond_list}, and @var{cmd_list} arguments have the 40699same meaning as in @samp{Z0} packets. 40700 40701@emph{Implementation note: A hardware breakpoint is not affected by code 40702movement.} 40703 40704Reply: 40705@table @samp 40706@item OK 40707success 40708@item @w{} 40709not supported 40710@item E @var{NN} 40711for an error 40712@end table 40713 40714@item z2,@var{addr},@var{kind} 40715@itemx Z2,@var{addr},@var{kind} 40716@cindex @samp{z2} packet 40717@cindex @samp{Z2} packet 40718Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint at @var{addr}. 40719The number of bytes to watch is specified by @var{kind}. 40720 40721Reply: 40722@table @samp 40723@item OK 40724success 40725@item @w{} 40726not supported 40727@item E @var{NN} 40728for an error 40729@end table 40730 40731@item z3,@var{addr},@var{kind} 40732@itemx Z3,@var{addr},@var{kind} 40733@cindex @samp{z3} packet 40734@cindex @samp{Z3} packet 40735Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint at @var{addr}. 40736The number of bytes to watch is specified by @var{kind}. 40737 40738Reply: 40739@table @samp 40740@item OK 40741success 40742@item @w{} 40743not supported 40744@item E @var{NN} 40745for an error 40746@end table 40747 40748@item z4,@var{addr},@var{kind} 40749@itemx Z4,@var{addr},@var{kind} 40750@cindex @samp{z4} packet 40751@cindex @samp{Z4} packet 40752Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint at @var{addr}. 40753The number of bytes to watch is specified by @var{kind}. 40754 40755Reply: 40756@table @samp 40757@item OK 40758success 40759@item @w{} 40760not supported 40761@item E @var{NN} 40762for an error 40763@end table 40764 40765@end table 40766 40767@node Stop Reply Packets 40768@section Stop Reply Packets 40769@cindex stop reply packets 40770 40771The @samp{C}, @samp{c}, @samp{S}, @samp{s}, @samp{vCont}, 40772@samp{vAttach}, @samp{vRun}, @samp{vStopped}, and @samp{?} packets can 40773receive any of the below as a reply. Except for @samp{?} 40774and @samp{vStopped}, that reply is only returned 40775when the target halts. In the below the exact meaning of @dfn{signal 40776number} is defined by the header @file{include/gdb/signals.h} in the 40777@value{GDBN} source code. 40778 40779In non-stop mode, the server will simply reply @samp{OK} to commands 40780such as @samp{vCont}; any stop will be the subject of a future 40781notification. @xref{Remote Non-Stop}. 40782 40783As in the description of request packets, we include spaces in the 40784reply templates for clarity; these are not part of the reply packet's 40785syntax. No @value{GDBN} stop reply packet uses spaces to separate its 40786components. 40787 40788@table @samp 40789 40790@item S @var{AA} 40791The program received signal number @var{AA} (a two-digit hexadecimal 40792number). This is equivalent to a @samp{T} response with no 40793@var{n}:@var{r} pairs. 40794 40795@item T @var{AA} @var{n1}:@var{r1};@var{n2}:@var{r2};@dots{} 40796@cindex @samp{T} packet reply 40797The program received signal number @var{AA} (a two-digit hexadecimal 40798number). This is equivalent to an @samp{S} response, except that the 40799@samp{@var{n}:@var{r}} pairs can carry values of important registers 40800and other information directly in the stop reply packet, reducing 40801round-trip latency. Single-step and breakpoint traps are reported 40802this way. Each @samp{@var{n}:@var{r}} pair is interpreted as follows: 40803 40804@itemize @bullet 40805@item 40806If @var{n} is a hexadecimal number, it is a register number, and the 40807corresponding @var{r} gives that register's value. The data @var{r} is a 40808series of bytes in target byte order, with each byte given by a 40809two-digit hex number. 40810 40811@item 40812If @var{n} is @samp{thread}, then @var{r} is the @var{thread-id} of 40813the stopped thread, as specified in @ref{thread-id syntax}. 40814 40815@item 40816If @var{n} is @samp{core}, then @var{r} is the hexadecimal number of 40817the core on which the stop event was detected. 40818 40819@item 40820If @var{n} is a recognized @dfn{stop reason}, it describes a more 40821specific event that stopped the target. The currently defined stop 40822reasons are listed below. The @var{aa} should be @samp{05}, the trap 40823signal. At most one stop reason should be present. 40824 40825@item 40826Otherwise, @value{GDBN} should ignore this @samp{@var{n}:@var{r}} pair 40827and go on to the next; this allows us to extend the protocol in the 40828future. 40829@end itemize 40830 40831The currently defined stop reasons are: 40832 40833@table @samp 40834@item watch 40835@itemx rwatch 40836@itemx awatch 40837The packet indicates a watchpoint hit, and @var{r} is the data address, in 40838hex. 40839 40840@item syscall_entry 40841@itemx syscall_return 40842The packet indicates a syscall entry or return, and @var{r} is the 40843syscall number, in hex. 40844 40845@cindex shared library events, remote reply 40846@item library 40847The packet indicates that the loaded libraries have changed. 40848@value{GDBN} should use @samp{qXfer:libraries:read} to fetch a new 40849list of loaded libraries. The @var{r} part is ignored. 40850 40851@cindex replay log events, remote reply 40852@item replaylog 40853The packet indicates that the target cannot continue replaying 40854logged execution events, because it has reached the end (or the 40855beginning when executing backward) of the log. The value of @var{r} 40856will be either @samp{begin} or @samp{end}. @xref{Reverse Execution}, 40857for more information. 40858 40859@item swbreak 40860@anchor{swbreak stop reason} 40861The packet indicates a software breakpoint instruction was executed, 40862irrespective of whether it was @value{GDBN} that planted the 40863breakpoint or the breakpoint is hardcoded in the program. The @var{r} 40864part must be left empty. 40865 40866On some architectures, such as x86, at the architecture level, when a 40867breakpoint instruction executes the program counter points at the 40868breakpoint address plus an offset. On such targets, the stub is 40869responsible for adjusting the PC to point back at the breakpoint 40870address. 40871 40872This packet should not be sent by default; older @value{GDBN} versions 40873did not support it. @value{GDBN} requests it, by supplying an 40874appropriate @samp{qSupported} feature (@pxref{qSupported}). The 40875remote stub must also supply the appropriate @samp{qSupported} feature 40876indicating support. 40877 40878This packet is required for correct non-stop mode operation. 40879 40880@item hwbreak 40881The packet indicates the target stopped for a hardware breakpoint. 40882The @var{r} part must be left empty. 40883 40884The same remarks about @samp{qSupported} and non-stop mode above 40885apply. 40886 40887@cindex fork events, remote reply 40888@item fork 40889The packet indicates that @code{fork} was called, and @var{r} 40890is the thread ID of the new child process. Refer to 40891@ref{thread-id syntax} for the format of the @var{thread-id} 40892field. This packet is only applicable to targets that support 40893fork events. 40894 40895This packet should not be sent by default; older @value{GDBN} versions 40896did not support it. @value{GDBN} requests it, by supplying an 40897appropriate @samp{qSupported} feature (@pxref{qSupported}). The 40898remote stub must also supply the appropriate @samp{qSupported} feature 40899indicating support. 40900 40901@cindex vfork events, remote reply 40902@item vfork 40903The packet indicates that @code{vfork} was called, and @var{r} 40904is the thread ID of the new child process. Refer to 40905@ref{thread-id syntax} for the format of the @var{thread-id} 40906field. This packet is only applicable to targets that support 40907vfork events. 40908 40909This packet should not be sent by default; older @value{GDBN} versions 40910did not support it. @value{GDBN} requests it, by supplying an 40911appropriate @samp{qSupported} feature (@pxref{qSupported}). The 40912remote stub must also supply the appropriate @samp{qSupported} feature 40913indicating support. 40914 40915@cindex vforkdone events, remote reply 40916@item vforkdone 40917The packet indicates that a child process created by a vfork 40918has either called @code{exec} or terminated, so that the 40919address spaces of the parent and child process are no longer 40920shared. The @var{r} part is ignored. This packet is only 40921applicable to targets that support vforkdone events. 40922 40923This packet should not be sent by default; older @value{GDBN} versions 40924did not support it. @value{GDBN} requests it, by supplying an 40925appropriate @samp{qSupported} feature (@pxref{qSupported}). The 40926remote stub must also supply the appropriate @samp{qSupported} feature 40927indicating support. 40928 40929@cindex exec events, remote reply 40930@item exec 40931The packet indicates that @code{execve} was called, and @var{r} 40932is the absolute pathname of the file that was executed, in hex. 40933This packet is only applicable to targets that support exec events. 40934 40935This packet should not be sent by default; older @value{GDBN} versions 40936did not support it. @value{GDBN} requests it, by supplying an 40937appropriate @samp{qSupported} feature (@pxref{qSupported}). The 40938remote stub must also supply the appropriate @samp{qSupported} feature 40939indicating support. 40940 40941@cindex thread create event, remote reply 40942@anchor{thread create event} 40943@item create 40944The packet indicates that the thread was just created. The new thread 40945is stopped until @value{GDBN} sets it running with a resumption packet 40946(@pxref{vCont packet}). This packet should not be sent by default; 40947@value{GDBN} requests it with the @ref{QThreadEvents} packet. See 40948also the @samp{w} (@pxref{thread exit event}) remote reply below. The 40949@var{r} part is ignored. 40950 40951@end table 40952 40953@item W @var{AA} 40954@itemx W @var{AA} ; process:@var{pid} 40955The process exited, and @var{AA} is the exit status. This is only 40956applicable to certain targets. 40957 40958The second form of the response, including the process ID of the 40959exited process, can be used only when @value{GDBN} has reported 40960support for multiprocess protocol extensions; see @ref{multiprocess 40961extensions}. Both @var{AA} and @var{pid} are formatted as big-endian 40962hex strings. 40963 40964@item X @var{AA} 40965@itemx X @var{AA} ; process:@var{pid} 40966The process terminated with signal @var{AA}. 40967 40968The second form of the response, including the process ID of the 40969terminated process, can be used only when @value{GDBN} has reported 40970support for multiprocess protocol extensions; see @ref{multiprocess 40971extensions}. Both @var{AA} and @var{pid} are formatted as big-endian 40972hex strings. 40973 40974@anchor{thread exit event} 40975@cindex thread exit event, remote reply 40976@item w @var{AA} ; @var{tid} 40977 40978The thread exited, and @var{AA} is the exit status. This response 40979should not be sent by default; @value{GDBN} requests it with the 40980@ref{QThreadEvents} packet. See also @ref{thread create event} above. 40981@var{AA} is formatted as a big-endian hex string. 40982 40983@item N 40984There are no resumed threads left in the target. In other words, even 40985though the process is alive, the last resumed thread has exited. For 40986example, say the target process has two threads: thread 1 and thread 409872. The client leaves thread 1 stopped, and resumes thread 2, which 40988subsequently exits. At this point, even though the process is still 40989alive, and thus no @samp{W} stop reply is sent, no thread is actually 40990executing either. The @samp{N} stop reply thus informs the client 40991that it can stop waiting for stop replies. This packet should not be 40992sent by default; older @value{GDBN} versions did not support it. 40993@value{GDBN} requests it, by supplying an appropriate 40994@samp{qSupported} feature (@pxref{qSupported}). The remote stub must 40995also supply the appropriate @samp{qSupported} feature indicating 40996support. 40997 40998@item O @var{XX}@dots{} 40999@samp{@var{XX}@dots{}} is hex encoding of @sc{ascii} data, to be 41000written as the program's console output. This can happen at any time 41001while the program is running and the debugger should continue to wait 41002for @samp{W}, @samp{T}, etc. This reply is not permitted in non-stop mode. 41003 41004@item F @var{call-id},@var{parameter}@dots{} 41005@var{call-id} is the identifier which says which host system call should 41006be called. This is just the name of the function. Translation into the 41007correct system call is only applicable as it's defined in @value{GDBN}. 41008@xref{File-I/O Remote Protocol Extension}, for a list of implemented 41009system calls. 41010 41011@samp{@var{parameter}@dots{}} is a list of parameters as defined for 41012this very system call. 41013 41014The target replies with this packet when it expects @value{GDBN} to 41015call a host system call on behalf of the target. @value{GDBN} replies 41016with an appropriate @samp{F} packet and keeps up waiting for the next 41017reply packet from the target. The latest @samp{C}, @samp{c}, @samp{S} 41018or @samp{s} action is expected to be continued. @xref{File-I/O Remote 41019Protocol Extension}, for more details. 41020 41021@end table 41022 41023@node General Query Packets 41024@section General Query Packets 41025@cindex remote query requests 41026 41027Packets starting with @samp{q} are @dfn{general query packets}; 41028packets starting with @samp{Q} are @dfn{general set packets}. General 41029query and set packets are a semi-unified form for retrieving and 41030sending information to and from the stub. 41031 41032The initial letter of a query or set packet is followed by a name 41033indicating what sort of thing the packet applies to. For example, 41034@value{GDBN} may use a @samp{qSymbol} packet to exchange symbol 41035definitions with the stub. These packet names follow some 41036conventions: 41037 41038@itemize @bullet 41039@item 41040The name must not contain commas, colons or semicolons. 41041@item 41042Most @value{GDBN} query and set packets have a leading upper case 41043letter. 41044@item 41045The names of custom vendor packets should use a company prefix, in 41046lower case, followed by a period. For example, packets designed at 41047the Acme Corporation might begin with @samp{qacme.foo} (for querying 41048foos) or @samp{Qacme.bar} (for setting bars). 41049@end itemize 41050 41051The name of a query or set packet should be separated from any 41052parameters by a @samp{:}; the parameters themselves should be 41053separated by @samp{,} or @samp{;}. Stubs must be careful to match the 41054full packet name, and check for a separator or the end of the packet, 41055in case two packet names share a common prefix. New packets should not begin 41056with @samp{qC}, @samp{qP}, or @samp{qL}@footnote{The @samp{qP} and @samp{qL} 41057packets predate these conventions, and have arguments without any terminator 41058for the packet name; we suspect they are in widespread use in places that 41059are difficult to upgrade. The @samp{qC} packet has no arguments, but some 41060existing stubs (e.g.@: RedBoot) are known to not check for the end of the 41061packet.}. 41062 41063Like the descriptions of the other packets, each description here 41064has a template showing the packet's overall syntax, followed by an 41065explanation of the packet's meaning. We include spaces in some of the 41066templates for clarity; these are not part of the packet's syntax. No 41067@value{GDBN} packet uses spaces to separate its components. 41068 41069Here are the currently defined query and set packets: 41070 41071@table @samp 41072 41073@item QAgent:1 41074@itemx QAgent:0 41075Turn on or off the agent as a helper to perform some debugging operations 41076delegated from @value{GDBN} (@pxref{Control Agent}). 41077 41078@item QAllow:@var{op}:@var{val}@dots{} 41079@cindex @samp{QAllow} packet 41080Specify which operations @value{GDBN} expects to request of the 41081target, as a semicolon-separated list of operation name and value 41082pairs. Possible values for @var{op} include @samp{WriteReg}, 41083@samp{WriteMem}, @samp{InsertBreak}, @samp{InsertTrace}, 41084@samp{InsertFastTrace}, and @samp{Stop}. @var{val} is either 0, 41085indicating that @value{GDBN} will not request the operation, or 1, 41086indicating that it may. (The target can then use this to set up its 41087own internals optimally, for instance if the debugger never expects to 41088insert breakpoints, it may not need to install its own trap handler.) 41089 41090@item qC 41091@cindex current thread, remote request 41092@cindex @samp{qC} packet 41093Return the current thread ID. 41094 41095Reply: 41096@table @samp 41097@item QC @var{thread-id} 41098Where @var{thread-id} is a thread ID as documented in 41099@ref{thread-id syntax}. 41100@item @r{(anything else)} 41101Any other reply implies the old thread ID. 41102@end table 41103 41104@item qCRC:@var{addr},@var{length} 41105@cindex CRC of memory block, remote request 41106@cindex @samp{qCRC} packet 41107@anchor{qCRC packet} 41108Compute the CRC checksum of a block of memory using CRC-32 defined in 41109IEEE 802.3. The CRC is computed byte at a time, taking the most 41110significant bit of each byte first. The initial pattern code 41111@code{0xffffffff} is used to ensure leading zeros affect the CRC. 41112 41113@emph{Note:} This is the same CRC used in validating separate debug 41114files (@pxref{Separate Debug Files, , Debugging Information in Separate 41115Files}). However the algorithm is slightly different. When validating 41116separate debug files, the CRC is computed taking the @emph{least} 41117significant bit of each byte first, and the final result is inverted to 41118detect trailing zeros. 41119 41120Reply: 41121@table @samp 41122@item E @var{NN} 41123An error (such as memory fault) 41124@item C @var{crc32} 41125The specified memory region's checksum is @var{crc32}. 41126@end table 41127 41128@item QDisableRandomization:@var{value} 41129@cindex disable address space randomization, remote request 41130@cindex @samp{QDisableRandomization} packet 41131Some target operating systems will randomize the virtual address space 41132of the inferior process as a security feature, but provide a feature 41133to disable such randomization, e.g.@: to allow for a more deterministic 41134debugging experience. On such systems, this packet with a @var{value} 41135of 1 directs the target to disable address space randomization for 41136processes subsequently started via @samp{vRun} packets, while a packet 41137with a @var{value} of 0 tells the target to enable address space 41138randomization. 41139 41140This packet is only available in extended mode (@pxref{extended mode}). 41141 41142Reply: 41143@table @samp 41144@item OK 41145The request succeeded. 41146 41147@item E @var{nn} 41148An error occurred. The error number @var{nn} is given as hex digits. 41149 41150@item @w{} 41151An empty reply indicates that @samp{QDisableRandomization} is not supported 41152by the stub. 41153@end table 41154 41155This packet is not probed by default; the remote stub must request it, 41156by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 41157This should only be done on targets that actually support disabling 41158address space randomization. 41159 41160@item QStartupWithShell:@var{value} 41161@cindex startup with shell, remote request 41162@cindex @samp{QStartupWithShell} packet 41163On UNIX-like targets, it is possible to start the inferior using a 41164shell program. This is the default behavior on both @value{GDBN} and 41165@command{gdbserver} (@pxref{set startup-with-shell}). This packet is 41166used to inform @command{gdbserver} whether it should start the 41167inferior using a shell or not. 41168 41169If @var{value} is @samp{0}, @command{gdbserver} will not use a shell 41170to start the inferior. If @var{value} is @samp{1}, 41171@command{gdbserver} will use a shell to start the inferior. All other 41172values are considered an error. 41173 41174This packet is only available in extended mode (@pxref{extended 41175mode}). 41176 41177Reply: 41178@table @samp 41179@item OK 41180The request succeeded. 41181 41182@item E @var{nn} 41183An error occurred. The error number @var{nn} is given as hex digits. 41184@end table 41185 41186This packet is not probed by default; the remote stub must request it, 41187by supplying an appropriate @samp{qSupported} response 41188(@pxref{qSupported}). This should only be done on targets that 41189actually support starting the inferior using a shell. 41190 41191Use of this packet is controlled by the @code{set startup-with-shell} 41192command; @pxref{set startup-with-shell}. 41193 41194@item QEnvironmentHexEncoded:@var{hex-value} 41195@anchor{QEnvironmentHexEncoded} 41196@cindex set environment variable, remote request 41197@cindex @samp{QEnvironmentHexEncoded} packet 41198On UNIX-like targets, it is possible to set environment variables that 41199will be passed to the inferior during the startup process. This 41200packet is used to inform @command{gdbserver} of an environment 41201variable that has been defined by the user on @value{GDBN} (@pxref{set 41202environment}). 41203 41204The packet is composed by @var{hex-value}, an hex encoded 41205representation of the @var{name=value} format representing an 41206environment variable. The name of the environment variable is 41207represented by @var{name}, and the value to be assigned to the 41208environment variable is represented by @var{value}. If the variable 41209has no value (i.e., the value is @code{null}), then @var{value} will 41210not be present. 41211 41212This packet is only available in extended mode (@pxref{extended 41213mode}). 41214 41215Reply: 41216@table @samp 41217@item OK 41218The request succeeded. 41219@end table 41220 41221This packet is not probed by default; the remote stub must request it, 41222by supplying an appropriate @samp{qSupported} response 41223(@pxref{qSupported}). This should only be done on targets that 41224actually support passing environment variables to the starting 41225inferior. 41226 41227This packet is related to the @code{set environment} command; 41228@pxref{set environment}. 41229 41230@item QEnvironmentUnset:@var{hex-value} 41231@anchor{QEnvironmentUnset} 41232@cindex unset environment variable, remote request 41233@cindex @samp{QEnvironmentUnset} packet 41234On UNIX-like targets, it is possible to unset environment variables 41235before starting the inferior in the remote target. This packet is 41236used to inform @command{gdbserver} of an environment variable that has 41237been unset by the user on @value{GDBN} (@pxref{unset environment}). 41238 41239The packet is composed by @var{hex-value}, an hex encoded 41240representation of the name of the environment variable to be unset. 41241 41242This packet is only available in extended mode (@pxref{extended 41243mode}). 41244 41245Reply: 41246@table @samp 41247@item OK 41248The request succeeded. 41249@end table 41250 41251This packet is not probed by default; the remote stub must request it, 41252by supplying an appropriate @samp{qSupported} response 41253(@pxref{qSupported}). This should only be done on targets that 41254actually support passing environment variables to the starting 41255inferior. 41256 41257This packet is related to the @code{unset environment} command; 41258@pxref{unset environment}. 41259 41260@item QEnvironmentReset 41261@anchor{QEnvironmentReset} 41262@cindex reset environment, remote request 41263@cindex @samp{QEnvironmentReset} packet 41264On UNIX-like targets, this packet is used to reset the state of 41265environment variables in the remote target before starting the 41266inferior. In this context, reset means unsetting all environment 41267variables that were previously set by the user (i.e., were not 41268initially present in the environment). It is sent to 41269@command{gdbserver} before the @samp{QEnvironmentHexEncoded} 41270(@pxref{QEnvironmentHexEncoded}) and the @samp{QEnvironmentUnset} 41271(@pxref{QEnvironmentUnset}) packets. 41272 41273This packet is only available in extended mode (@pxref{extended 41274mode}). 41275 41276Reply: 41277@table @samp 41278@item OK 41279The request succeeded. 41280@end table 41281 41282This packet is not probed by default; the remote stub must request it, 41283by supplying an appropriate @samp{qSupported} response 41284(@pxref{qSupported}). This should only be done on targets that 41285actually support passing environment variables to the starting 41286inferior. 41287 41288@item QSetWorkingDir:@r{[}@var{directory}@r{]} 41289@anchor{QSetWorkingDir packet} 41290@cindex set working directory, remote request 41291@cindex @samp{QSetWorkingDir} packet 41292This packet is used to inform the remote server of the intended 41293current working directory for programs that are going to be executed. 41294 41295The packet is composed by @var{directory}, an hex encoded 41296representation of the directory that the remote inferior will use as 41297its current working directory. If @var{directory} is an empty string, 41298the remote server should reset the inferior's current working 41299directory to its original, empty value. 41300 41301This packet is only available in extended mode (@pxref{extended 41302mode}). 41303 41304Reply: 41305@table @samp 41306@item OK 41307The request succeeded. 41308@end table 41309 41310@item qfThreadInfo 41311@itemx qsThreadInfo 41312@cindex list active threads, remote request 41313@cindex @samp{qfThreadInfo} packet 41314@cindex @samp{qsThreadInfo} packet 41315Obtain a list of all active thread IDs from the target (OS). Since there 41316may be too many active threads to fit into one reply packet, this query 41317works iteratively: it may require more than one query/reply sequence to 41318obtain the entire list of threads. The first query of the sequence will 41319be the @samp{qfThreadInfo} query; subsequent queries in the 41320sequence will be the @samp{qsThreadInfo} query. 41321 41322NOTE: This packet replaces the @samp{qL} query (see below). 41323 41324Reply: 41325@table @samp 41326@item m @var{thread-id} 41327A single thread ID 41328@item m @var{thread-id},@var{thread-id}@dots{} 41329a comma-separated list of thread IDs 41330@item l 41331(lower case letter @samp{L}) denotes end of list. 41332@end table 41333 41334In response to each query, the target will reply with a list of one or 41335more thread IDs, separated by commas. 41336@value{GDBN} will respond to each reply with a request for more thread 41337ids (using the @samp{qs} form of the query), until the target responds 41338with @samp{l} (lower-case ell, for @dfn{last}). 41339Refer to @ref{thread-id syntax}, for the format of the @var{thread-id} 41340fields. 41341 41342@emph{Note: @value{GDBN} will send the @code{qfThreadInfo} query during the 41343initial connection with the remote target, and the very first thread ID 41344mentioned in the reply will be stopped by @value{GDBN} in a subsequent 41345message. Therefore, the stub should ensure that the first thread ID in 41346the @code{qfThreadInfo} reply is suitable for being stopped by @value{GDBN}.} 41347 41348@item qGetTLSAddr:@var{thread-id},@var{offset},@var{lm} 41349@cindex get thread-local storage address, remote request 41350@cindex @samp{qGetTLSAddr} packet 41351Fetch the address associated with thread local storage specified 41352by @var{thread-id}, @var{offset}, and @var{lm}. 41353 41354@var{thread-id} is the thread ID associated with the 41355thread for which to fetch the TLS address. @xref{thread-id syntax}. 41356 41357@var{offset} is the (big endian, hex encoded) offset associated with the 41358thread local variable. (This offset is obtained from the debug 41359information associated with the variable.) 41360 41361@var{lm} is the (big endian, hex encoded) OS/ABI-specific encoding of the 41362load module associated with the thread local storage. For example, 41363a @sc{gnu}/Linux system will pass the link map address of the shared 41364object associated with the thread local storage under consideration. 41365Other operating environments may choose to represent the load module 41366differently, so the precise meaning of this parameter will vary. 41367 41368Reply: 41369@table @samp 41370@item @var{XX}@dots{} 41371Hex encoded (big endian) bytes representing the address of the thread 41372local storage requested. 41373 41374@item E @var{nn} 41375An error occurred. The error number @var{nn} is given as hex digits. 41376 41377@item @w{} 41378An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub. 41379@end table 41380 41381@item qGetTIBAddr:@var{thread-id} 41382@cindex get thread information block address 41383@cindex @samp{qGetTIBAddr} packet 41384Fetch address of the Windows OS specific Thread Information Block. 41385 41386@var{thread-id} is the thread ID associated with the thread. 41387 41388Reply: 41389@table @samp 41390@item @var{XX}@dots{} 41391Hex encoded (big endian) bytes representing the linear address of the 41392thread information block. 41393 41394@item E @var{nn} 41395An error occured. This means that either the thread was not found, or the 41396address could not be retrieved. 41397 41398@item @w{} 41399An empty reply indicates that @samp{qGetTIBAddr} is not supported by the stub. 41400@end table 41401 41402@item qL @var{startflag} @var{threadcount} @var{nextthread} 41403Obtain thread information from RTOS. Where: @var{startflag} (one hex 41404digit) is one to indicate the first query and zero to indicate a 41405subsequent query; @var{threadcount} (two hex digits) is the maximum 41406number of threads the response packet can contain; and @var{nextthread} 41407(eight hex digits), for subsequent queries (@var{startflag} is zero), is 41408returned in the response as @var{argthread}. 41409 41410Don't use this packet; use the @samp{qfThreadInfo} query instead (see above). 41411 41412Reply: 41413@table @samp 41414@item qM @var{count} @var{done} @var{argthread} @var{thread}@dots{} 41415Where: @var{count} (two hex digits) is the number of threads being 41416returned; @var{done} (one hex digit) is zero to indicate more threads 41417and one indicates no further threads; @var{argthreadid} (eight hex 41418digits) is @var{nextthread} from the request packet; @var{thread}@dots{} 41419is a sequence of thread IDs, @var{threadid} (eight hex 41420digits), from the target. See @code{remote.c:parse_threadlist_response()}. 41421@end table 41422 41423@item qMemTags:@var{start address},@var{length}:@var{type} 41424@anchor{qMemTags} 41425@cindex fetch memory tags 41426@cindex @samp{qMemTags} packet 41427Fetch memory tags of type @var{type} from the address range 41428@w{@r{[}@var{start address}, @var{start address} + @var{length}@r{)}}. The 41429target is responsible for calculating how many tags will be returned, as this 41430is architecture-specific. 41431 41432@var{start address} is the starting address of the memory range. 41433 41434@var{length} is the length, in bytes, of the memory range. 41435 41436@var{type} is the type of tag the request wants to fetch. The type is a signed 41437integer. 41438 41439Reply: 41440@table @samp 41441@item @var{mxx}@dots{} 41442Hex encoded sequence of uninterpreted bytes, @var{xx}@dots{}, representing the 41443tags found in the requested memory range. 41444 41445@item E @var{nn} 41446An error occured. This means that fetching of memory tags failed for some 41447reason. 41448 41449@item @w{} 41450An empty reply indicates that @samp{qMemTags} is not supported by the stub, 41451although this should not happen given @value{GDBN} will only send this packet 41452if the stub has advertised support for memory tagging via @samp{qSupported}. 41453@end table 41454 41455@item QMemTags:@var{start address},@var{length}:@var{type}:@var{tag bytes} 41456@anchor{QMemTags} 41457@cindex store memory tags 41458@cindex @samp{QMemTags} packet 41459Store memory tags of type @var{type} to the address range 41460@w{@r{[}@var{start address}, @var{start address} + @var{length}@r{)}}. The 41461target is responsible for interpreting the type, the tag bytes and modifying 41462the memory tag granules accordingly, given this is architecture-specific. 41463 41464The interpretation of how many tags (@var{nt}) should be written to how many 41465memory tag granules (@var{ng}) is also architecture-specific. The behavior is 41466implementation-specific, but the following is suggested. 41467 41468If the number of memory tags, @var{nt}, is greater than or equal to the 41469number of memory tag granules, @var{ng}, only @var{ng} tags will be 41470stored. 41471 41472If @var{nt} is less than @var{ng}, the behavior is that of a fill operation, 41473and the tag bytes will be used as a pattern that will get repeated until 41474@var{ng} tags are stored. 41475 41476@var{start address} is the starting address of the memory range. The address 41477does not have any restriction on alignment or size. 41478 41479@var{length} is the length, in bytes, of the memory range. 41480 41481@var{type} is the type of tag the request wants to fetch. The type is a signed 41482integer. 41483 41484@var{tag bytes} is a sequence of hex encoded uninterpreted bytes which will be 41485interpreted by the target. Each pair of hex digits is interpreted as a 41486single byte. 41487 41488Reply: 41489@table @samp 41490@item OK 41491The request was successful and the memory tag granules were modified 41492accordingly. 41493 41494@item E @var{nn} 41495An error occured. This means that modifying the memory tag granules failed 41496for some reason. 41497 41498@item @w{} 41499An empty reply indicates that @samp{QMemTags} is not supported by the stub, 41500although this should not happen given @value{GDBN} will only send this packet 41501if the stub has advertised support for memory tagging via @samp{qSupported}. 41502@end table 41503 41504@item qOffsets 41505@cindex section offsets, remote request 41506@cindex @samp{qOffsets} packet 41507Get section offsets that the target used when relocating the downloaded 41508image. 41509 41510Reply: 41511@table @samp 41512@item Text=@var{xxx};Data=@var{yyy}@r{[};Bss=@var{zzz}@r{]} 41513Relocate the @code{Text} section by @var{xxx} from its original address. 41514Relocate the @code{Data} section by @var{yyy} from its original address. 41515If the object file format provides segment information (e.g.@: @sc{elf} 41516@samp{PT_LOAD} program headers), @value{GDBN} will relocate entire 41517segments by the supplied offsets. 41518 41519@emph{Note: while a @code{Bss} offset may be included in the response, 41520@value{GDBN} ignores this and instead applies the @code{Data} offset 41521to the @code{Bss} section.} 41522 41523@item TextSeg=@var{xxx}@r{[};DataSeg=@var{yyy}@r{]} 41524Relocate the first segment of the object file, which conventionally 41525contains program code, to a starting address of @var{xxx}. If 41526@samp{DataSeg} is specified, relocate the second segment, which 41527conventionally contains modifiable data, to a starting address of 41528@var{yyy}. @value{GDBN} will report an error if the object file 41529does not contain segment information, or does not contain at least 41530as many segments as mentioned in the reply. Extra segments are 41531kept at fixed offsets relative to the last relocated segment. 41532@end table 41533 41534@item qP @var{mode} @var{thread-id} 41535@cindex thread information, remote request 41536@cindex @samp{qP} packet 41537Returns information on @var{thread-id}. Where: @var{mode} is a hex 41538encoded 32 bit mode; @var{thread-id} is a thread ID 41539(@pxref{thread-id syntax}). 41540 41541Don't use this packet; use the @samp{qThreadExtraInfo} query instead 41542(see below). 41543 41544Reply: see @code{remote.c:remote_unpack_thread_info_response()}. 41545 41546@item QNonStop:1 41547@itemx QNonStop:0 41548@cindex non-stop mode, remote request 41549@cindex @samp{QNonStop} packet 41550@anchor{QNonStop} 41551Enter non-stop (@samp{QNonStop:1}) or all-stop (@samp{QNonStop:0}) mode. 41552@xref{Remote Non-Stop}, for more information. 41553 41554Reply: 41555@table @samp 41556@item OK 41557The request succeeded. 41558 41559@item E @var{nn} 41560An error occurred. The error number @var{nn} is given as hex digits. 41561 41562@item @w{} 41563An empty reply indicates that @samp{QNonStop} is not supported by 41564the stub. 41565@end table 41566 41567This packet is not probed by default; the remote stub must request it, 41568by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 41569Use of this packet is controlled by the @code{set non-stop} command; 41570@pxref{Non-Stop Mode}. 41571 41572@item QCatchSyscalls:1 @r{[};@var{sysno}@r{]}@dots{} 41573@itemx QCatchSyscalls:0 41574@cindex catch syscalls from inferior, remote request 41575@cindex @samp{QCatchSyscalls} packet 41576@anchor{QCatchSyscalls} 41577Enable (@samp{QCatchSyscalls:1}) or disable (@samp{QCatchSyscalls:0}) 41578catching syscalls from the inferior process. 41579 41580For @samp{QCatchSyscalls:1}, each listed syscall @var{sysno} (encoded 41581in hex) should be reported to @value{GDBN}. If no syscall @var{sysno} 41582is listed, every system call should be reported. 41583 41584Note that if a syscall not in the list is reported, @value{GDBN} will 41585still filter the event according to its own list from all corresponding 41586@code{catch syscall} commands. However, it is more efficient to only 41587report the requested syscalls. 41588 41589Multiple @samp{QCatchSyscalls:1} packets do not combine; any earlier 41590@samp{QCatchSyscalls:1} list is completely replaced by the new list. 41591 41592If the inferior process execs, the state of @samp{QCatchSyscalls} is 41593kept for the new process too. On targets where exec may affect syscall 41594numbers, for example with exec between 32 and 64-bit processes, the 41595client should send a new packet with the new syscall list. 41596 41597Reply: 41598@table @samp 41599@item OK 41600The request succeeded. 41601 41602@item E @var{nn} 41603An error occurred. @var{nn} are hex digits. 41604 41605@item @w{} 41606An empty reply indicates that @samp{QCatchSyscalls} is not supported by 41607the stub. 41608@end table 41609 41610Use of this packet is controlled by the @code{set remote catch-syscalls} 41611command (@pxref{Remote Configuration, set remote catch-syscalls}). 41612This packet is not probed by default; the remote stub must request it, 41613by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 41614 41615@item QPassSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{} 41616@cindex pass signals to inferior, remote request 41617@cindex @samp{QPassSignals} packet 41618@anchor{QPassSignals} 41619Each listed @var{signal} should be passed directly to the inferior process. 41620Signals are numbered identically to continue packets and stop replies 41621(@pxref{Stop Reply Packets}). Each @var{signal} list item should be 41622strictly greater than the previous item. These signals do not need to stop 41623the inferior, or be reported to @value{GDBN}. All other signals should be 41624reported to @value{GDBN}. Multiple @samp{QPassSignals} packets do not 41625combine; any earlier @samp{QPassSignals} list is completely replaced by the 41626new list. This packet improves performance when using @samp{handle 41627@var{signal} nostop noprint pass}. 41628 41629Reply: 41630@table @samp 41631@item OK 41632The request succeeded. 41633 41634@item E @var{nn} 41635An error occurred. The error number @var{nn} is given as hex digits. 41636 41637@item @w{} 41638An empty reply indicates that @samp{QPassSignals} is not supported by 41639the stub. 41640@end table 41641 41642Use of this packet is controlled by the @code{set remote pass-signals} 41643command (@pxref{Remote Configuration, set remote pass-signals}). 41644This packet is not probed by default; the remote stub must request it, 41645by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 41646 41647@item QProgramSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{} 41648@cindex signals the inferior may see, remote request 41649@cindex @samp{QProgramSignals} packet 41650@anchor{QProgramSignals} 41651Each listed @var{signal} may be delivered to the inferior process. 41652Others should be silently discarded. 41653 41654In some cases, the remote stub may need to decide whether to deliver a 41655signal to the program or not without @value{GDBN} involvement. One 41656example of that is while detaching --- the program's threads may have 41657stopped for signals that haven't yet had a chance of being reported to 41658@value{GDBN}, and so the remote stub can use the signal list specified 41659by this packet to know whether to deliver or ignore those pending 41660signals. 41661 41662This does not influence whether to deliver a signal as requested by a 41663resumption packet (@pxref{vCont packet}). 41664 41665Signals are numbered identically to continue packets and stop replies 41666(@pxref{Stop Reply Packets}). Each @var{signal} list item should be 41667strictly greater than the previous item. Multiple 41668@samp{QProgramSignals} packets do not combine; any earlier 41669@samp{QProgramSignals} list is completely replaced by the new list. 41670 41671Reply: 41672@table @samp 41673@item OK 41674The request succeeded. 41675 41676@item E @var{nn} 41677An error occurred. The error number @var{nn} is given as hex digits. 41678 41679@item @w{} 41680An empty reply indicates that @samp{QProgramSignals} is not supported 41681by the stub. 41682@end table 41683 41684Use of this packet is controlled by the @code{set remote program-signals} 41685command (@pxref{Remote Configuration, set remote program-signals}). 41686This packet is not probed by default; the remote stub must request it, 41687by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 41688 41689@anchor{QThreadEvents} 41690@item QThreadEvents:1 41691@itemx QThreadEvents:0 41692@cindex thread create/exit events, remote request 41693@cindex @samp{QThreadEvents} packet 41694 41695Enable (@samp{QThreadEvents:1}) or disable (@samp{QThreadEvents:0}) 41696reporting of thread create and exit events. @xref{thread create 41697event}, for the reply specifications. For example, this is used in 41698non-stop mode when @value{GDBN} stops a set of threads and 41699synchronously waits for the their corresponding stop replies. Without 41700exit events, if one of the threads exits, @value{GDBN} would hang 41701forever not knowing that it should no longer expect a stop for that 41702same thread. @value{GDBN} does not enable this feature unless the 41703stub reports that it supports it by including @samp{QThreadEvents+} in 41704its @samp{qSupported} reply. 41705 41706Reply: 41707@table @samp 41708@item OK 41709The request succeeded. 41710 41711@item E @var{nn} 41712An error occurred. The error number @var{nn} is given as hex digits. 41713 41714@item @w{} 41715An empty reply indicates that @samp{QThreadEvents} is not supported by 41716the stub. 41717@end table 41718 41719Use of this packet is controlled by the @code{set remote thread-events} 41720command (@pxref{Remote Configuration, set remote thread-events}). 41721 41722@item qRcmd,@var{command} 41723@cindex execute remote command, remote request 41724@cindex @samp{qRcmd} packet 41725@var{command} (hex encoded) is passed to the local interpreter for 41726execution. Invalid commands should be reported using the output 41727string. Before the final result packet, the target may also respond 41728with a number of intermediate @samp{O@var{output}} console output 41729packets. @emph{Implementors should note that providing access to a 41730stubs's interpreter may have security implications}. 41731 41732Reply: 41733@table @samp 41734@item OK 41735A command response with no output. 41736@item @var{OUTPUT} 41737A command response with the hex encoded output string @var{OUTPUT}. 41738@item E @var{NN} 41739Indicate a badly formed request. 41740@item @w{} 41741An empty reply indicates that @samp{qRcmd} is not recognized. 41742@end table 41743 41744(Note that the @code{qRcmd} packet's name is separated from the 41745command by a @samp{,}, not a @samp{:}, contrary to the naming 41746conventions above. Please don't use this packet as a model for new 41747packets.) 41748 41749@item qSearch:memory:@var{address};@var{length};@var{search-pattern} 41750@cindex searching memory, in remote debugging 41751@ifnotinfo 41752@cindex @samp{qSearch:memory} packet 41753@end ifnotinfo 41754@cindex @samp{qSearch memory} packet 41755@anchor{qSearch memory} 41756Search @var{length} bytes at @var{address} for @var{search-pattern}. 41757Both @var{address} and @var{length} are encoded in hex; 41758@var{search-pattern} is a sequence of bytes, also hex encoded. 41759 41760Reply: 41761@table @samp 41762@item 0 41763The pattern was not found. 41764@item 1,address 41765The pattern was found at @var{address}. 41766@item E @var{NN} 41767A badly formed request or an error was encountered while searching memory. 41768@item @w{} 41769An empty reply indicates that @samp{qSearch:memory} is not recognized. 41770@end table 41771 41772@item QStartNoAckMode 41773@cindex @samp{QStartNoAckMode} packet 41774@anchor{QStartNoAckMode} 41775Request that the remote stub disable the normal @samp{+}/@samp{-} 41776protocol acknowledgments (@pxref{Packet Acknowledgment}). 41777 41778Reply: 41779@table @samp 41780@item OK 41781The stub has switched to no-acknowledgment mode. 41782@value{GDBN} acknowledges this response, 41783but neither the stub nor @value{GDBN} shall send or expect further 41784@samp{+}/@samp{-} acknowledgments in the current connection. 41785@item @w{} 41786An empty reply indicates that the stub does not support no-acknowledgment mode. 41787@end table 41788 41789@item qSupported @r{[}:@var{gdbfeature} @r{[};@var{gdbfeature}@r{]}@dots{} @r{]} 41790@cindex supported packets, remote query 41791@cindex features of the remote protocol 41792@cindex @samp{qSupported} packet 41793@anchor{qSupported} 41794Tell the remote stub about features supported by @value{GDBN}, and 41795query the stub for features it supports. This packet allows 41796@value{GDBN} and the remote stub to take advantage of each others' 41797features. @samp{qSupported} also consolidates multiple feature probes 41798at startup, to improve @value{GDBN} performance---a single larger 41799packet performs better than multiple smaller probe packets on 41800high-latency links. Some features may enable behavior which must not 41801be on by default, e.g.@: because it would confuse older clients or 41802stubs. Other features may describe packets which could be 41803automatically probed for, but are not. These features must be 41804reported before @value{GDBN} will use them. This ``default 41805unsupported'' behavior is not appropriate for all packets, but it 41806helps to keep the initial connection time under control with new 41807versions of @value{GDBN} which support increasing numbers of packets. 41808 41809Reply: 41810@table @samp 41811@item @var{stubfeature} @r{[};@var{stubfeature}@r{]}@dots{} 41812The stub supports or does not support each returned @var{stubfeature}, 41813depending on the form of each @var{stubfeature} (see below for the 41814possible forms). 41815@item @w{} 41816An empty reply indicates that @samp{qSupported} is not recognized, 41817or that no features needed to be reported to @value{GDBN}. 41818@end table 41819 41820The allowed forms for each feature (either a @var{gdbfeature} in the 41821@samp{qSupported} packet, or a @var{stubfeature} in the response) 41822are: 41823 41824@table @samp 41825@item @var{name}=@var{value} 41826The remote protocol feature @var{name} is supported, and associated 41827with the specified @var{value}. The format of @var{value} depends 41828on the feature, but it must not include a semicolon. 41829@item @var{name}+ 41830The remote protocol feature @var{name} is supported, and does not 41831need an associated value. 41832@item @var{name}- 41833The remote protocol feature @var{name} is not supported. 41834@item @var{name}? 41835The remote protocol feature @var{name} may be supported, and 41836@value{GDBN} should auto-detect support in some other way when it is 41837needed. This form will not be used for @var{gdbfeature} notifications, 41838but may be used for @var{stubfeature} responses. 41839@end table 41840 41841Whenever the stub receives a @samp{qSupported} request, the 41842supplied set of @value{GDBN} features should override any previous 41843request. This allows @value{GDBN} to put the stub in a known 41844state, even if the stub had previously been communicating with 41845a different version of @value{GDBN}. 41846 41847The following values of @var{gdbfeature} (for the packet sent by @value{GDBN}) 41848are defined: 41849 41850@table @samp 41851@item multiprocess 41852This feature indicates whether @value{GDBN} supports multiprocess 41853extensions to the remote protocol. @value{GDBN} does not use such 41854extensions unless the stub also reports that it supports them by 41855including @samp{multiprocess+} in its @samp{qSupported} reply. 41856@xref{multiprocess extensions}, for details. 41857 41858@item xmlRegisters 41859This feature indicates that @value{GDBN} supports the XML target 41860description. If the stub sees @samp{xmlRegisters=} with target 41861specific strings separated by a comma, it will report register 41862description. 41863 41864@item qRelocInsn 41865This feature indicates whether @value{GDBN} supports the 41866@samp{qRelocInsn} packet (@pxref{Tracepoint Packets,,Relocate 41867instruction reply packet}). 41868 41869@item swbreak 41870This feature indicates whether @value{GDBN} supports the swbreak stop 41871reason in stop replies. @xref{swbreak stop reason}, for details. 41872 41873@item hwbreak 41874This feature indicates whether @value{GDBN} supports the hwbreak stop 41875reason in stop replies. @xref{swbreak stop reason}, for details. 41876 41877@item fork-events 41878This feature indicates whether @value{GDBN} supports fork event 41879extensions to the remote protocol. @value{GDBN} does not use such 41880extensions unless the stub also reports that it supports them by 41881including @samp{fork-events+} in its @samp{qSupported} reply. 41882 41883@item vfork-events 41884This feature indicates whether @value{GDBN} supports vfork event 41885extensions to the remote protocol. @value{GDBN} does not use such 41886extensions unless the stub also reports that it supports them by 41887including @samp{vfork-events+} in its @samp{qSupported} reply. 41888 41889@item exec-events 41890This feature indicates whether @value{GDBN} supports exec event 41891extensions to the remote protocol. @value{GDBN} does not use such 41892extensions unless the stub also reports that it supports them by 41893including @samp{exec-events+} in its @samp{qSupported} reply. 41894 41895@item vContSupported 41896This feature indicates whether @value{GDBN} wants to know the 41897supported actions in the reply to @samp{vCont?} packet. 41898@end table 41899 41900Stubs should ignore any unknown values for 41901@var{gdbfeature}. Any @value{GDBN} which sends a @samp{qSupported} 41902packet supports receiving packets of unlimited length (earlier 41903versions of @value{GDBN} may reject overly long responses). Additional values 41904for @var{gdbfeature} may be defined in the future to let the stub take 41905advantage of new features in @value{GDBN}, e.g.@: incompatible 41906improvements in the remote protocol---the @samp{multiprocess} feature is 41907an example of such a feature. The stub's reply should be independent 41908of the @var{gdbfeature} entries sent by @value{GDBN}; first @value{GDBN} 41909describes all the features it supports, and then the stub replies with 41910all the features it supports. 41911 41912Similarly, @value{GDBN} will silently ignore unrecognized stub feature 41913responses, as long as each response uses one of the standard forms. 41914 41915Some features are flags. A stub which supports a flag feature 41916should respond with a @samp{+} form response. Other features 41917require values, and the stub should respond with an @samp{=} 41918form response. 41919 41920Each feature has a default value, which @value{GDBN} will use if 41921@samp{qSupported} is not available or if the feature is not mentioned 41922in the @samp{qSupported} response. The default values are fixed; a 41923stub is free to omit any feature responses that match the defaults. 41924 41925Not all features can be probed, but for those which can, the probing 41926mechanism is useful: in some cases, a stub's internal 41927architecture may not allow the protocol layer to know some information 41928about the underlying target in advance. This is especially common in 41929stubs which may be configured for multiple targets. 41930 41931These are the currently defined stub features and their properties: 41932 41933@multitable @columnfractions 0.35 0.2 0.12 0.2 41934@c NOTE: The first row should be @headitem, but we do not yet require 41935@c a new enough version of Texinfo (4.7) to use @headitem. 41936@item Feature Name 41937@tab Value Required 41938@tab Default 41939@tab Probe Allowed 41940 41941@item @samp{PacketSize} 41942@tab Yes 41943@tab @samp{-} 41944@tab No 41945 41946@item @samp{qXfer:auxv:read} 41947@tab No 41948@tab @samp{-} 41949@tab Yes 41950 41951@item @samp{qXfer:btrace:read} 41952@tab No 41953@tab @samp{-} 41954@tab Yes 41955 41956@item @samp{qXfer:btrace-conf:read} 41957@tab No 41958@tab @samp{-} 41959@tab Yes 41960 41961@item @samp{qXfer:exec-file:read} 41962@tab No 41963@tab @samp{-} 41964@tab Yes 41965 41966@item @samp{qXfer:features:read} 41967@tab No 41968@tab @samp{-} 41969@tab Yes 41970 41971@item @samp{qXfer:libraries:read} 41972@tab No 41973@tab @samp{-} 41974@tab Yes 41975 41976@item @samp{qXfer:libraries-svr4:read} 41977@tab No 41978@tab @samp{-} 41979@tab Yes 41980 41981@item @samp{augmented-libraries-svr4-read} 41982@tab No 41983@tab @samp{-} 41984@tab No 41985 41986@item @samp{qXfer:memory-map:read} 41987@tab No 41988@tab @samp{-} 41989@tab Yes 41990 41991@item @samp{qXfer:sdata:read} 41992@tab No 41993@tab @samp{-} 41994@tab Yes 41995 41996@item @samp{qXfer:siginfo:read} 41997@tab No 41998@tab @samp{-} 41999@tab Yes 42000 42001@item @samp{qXfer:siginfo:write} 42002@tab No 42003@tab @samp{-} 42004@tab Yes 42005 42006@item @samp{qXfer:threads:read} 42007@tab No 42008@tab @samp{-} 42009@tab Yes 42010 42011@item @samp{qXfer:traceframe-info:read} 42012@tab No 42013@tab @samp{-} 42014@tab Yes 42015 42016@item @samp{qXfer:uib:read} 42017@tab No 42018@tab @samp{-} 42019@tab Yes 42020 42021@item @samp{qXfer:fdpic:read} 42022@tab No 42023@tab @samp{-} 42024@tab Yes 42025 42026@item @samp{Qbtrace:off} 42027@tab Yes 42028@tab @samp{-} 42029@tab Yes 42030 42031@item @samp{Qbtrace:bts} 42032@tab Yes 42033@tab @samp{-} 42034@tab Yes 42035 42036@item @samp{Qbtrace:pt} 42037@tab Yes 42038@tab @samp{-} 42039@tab Yes 42040 42041@item @samp{Qbtrace-conf:bts:size} 42042@tab Yes 42043@tab @samp{-} 42044@tab Yes 42045 42046@item @samp{Qbtrace-conf:pt:size} 42047@tab Yes 42048@tab @samp{-} 42049@tab Yes 42050 42051@item @samp{QNonStop} 42052@tab No 42053@tab @samp{-} 42054@tab Yes 42055 42056@item @samp{QCatchSyscalls} 42057@tab No 42058@tab @samp{-} 42059@tab Yes 42060 42061@item @samp{QPassSignals} 42062@tab No 42063@tab @samp{-} 42064@tab Yes 42065 42066@item @samp{QStartNoAckMode} 42067@tab No 42068@tab @samp{-} 42069@tab Yes 42070 42071@item @samp{multiprocess} 42072@tab No 42073@tab @samp{-} 42074@tab No 42075 42076@item @samp{ConditionalBreakpoints} 42077@tab No 42078@tab @samp{-} 42079@tab No 42080 42081@item @samp{ConditionalTracepoints} 42082@tab No 42083@tab @samp{-} 42084@tab No 42085 42086@item @samp{ReverseContinue} 42087@tab No 42088@tab @samp{-} 42089@tab No 42090 42091@item @samp{ReverseStep} 42092@tab No 42093@tab @samp{-} 42094@tab No 42095 42096@item @samp{TracepointSource} 42097@tab No 42098@tab @samp{-} 42099@tab No 42100 42101@item @samp{QAgent} 42102@tab No 42103@tab @samp{-} 42104@tab No 42105 42106@item @samp{QAllow} 42107@tab No 42108@tab @samp{-} 42109@tab No 42110 42111@item @samp{QDisableRandomization} 42112@tab No 42113@tab @samp{-} 42114@tab No 42115 42116@item @samp{EnableDisableTracepoints} 42117@tab No 42118@tab @samp{-} 42119@tab No 42120 42121@item @samp{QTBuffer:size} 42122@tab No 42123@tab @samp{-} 42124@tab No 42125 42126@item @samp{tracenz} 42127@tab No 42128@tab @samp{-} 42129@tab No 42130 42131@item @samp{BreakpointCommands} 42132@tab No 42133@tab @samp{-} 42134@tab No 42135 42136@item @samp{swbreak} 42137@tab No 42138@tab @samp{-} 42139@tab No 42140 42141@item @samp{hwbreak} 42142@tab No 42143@tab @samp{-} 42144@tab No 42145 42146@item @samp{fork-events} 42147@tab No 42148@tab @samp{-} 42149@tab No 42150 42151@item @samp{vfork-events} 42152@tab No 42153@tab @samp{-} 42154@tab No 42155 42156@item @samp{exec-events} 42157@tab No 42158@tab @samp{-} 42159@tab No 42160 42161@item @samp{QThreadEvents} 42162@tab No 42163@tab @samp{-} 42164@tab No 42165 42166@item @samp{no-resumed} 42167@tab No 42168@tab @samp{-} 42169@tab No 42170 42171@item @samp{memory-tagging} 42172@tab No 42173@tab @samp{-} 42174@tab No 42175 42176@end multitable 42177 42178These are the currently defined stub features, in more detail: 42179 42180@table @samp 42181@cindex packet size, remote protocol 42182@item PacketSize=@var{bytes} 42183The remote stub can accept packets up to at least @var{bytes} in 42184length. @value{GDBN} will send packets up to this size for bulk 42185transfers, and will never send larger packets. This is a limit on the 42186data characters in the packet, including the frame and checksum. 42187There is no trailing NUL byte in a remote protocol packet; if the stub 42188stores packets in a NUL-terminated format, it should allow an extra 42189byte in its buffer for the NUL. If this stub feature is not supported, 42190@value{GDBN} guesses based on the size of the @samp{g} packet response. 42191 42192@item qXfer:auxv:read 42193The remote stub understands the @samp{qXfer:auxv:read} packet 42194(@pxref{qXfer auxiliary vector read}). 42195 42196@item qXfer:btrace:read 42197The remote stub understands the @samp{qXfer:btrace:read} 42198packet (@pxref{qXfer btrace read}). 42199 42200@item qXfer:btrace-conf:read 42201The remote stub understands the @samp{qXfer:btrace-conf:read} 42202packet (@pxref{qXfer btrace-conf read}). 42203 42204@item qXfer:exec-file:read 42205The remote stub understands the @samp{qXfer:exec-file:read} packet 42206(@pxref{qXfer executable filename read}). 42207 42208@item qXfer:features:read 42209The remote stub understands the @samp{qXfer:features:read} packet 42210(@pxref{qXfer target description read}). 42211 42212@item qXfer:libraries:read 42213The remote stub understands the @samp{qXfer:libraries:read} packet 42214(@pxref{qXfer library list read}). 42215 42216@item qXfer:libraries-svr4:read 42217The remote stub understands the @samp{qXfer:libraries-svr4:read} packet 42218(@pxref{qXfer svr4 library list read}). 42219 42220@item augmented-libraries-svr4-read 42221The remote stub understands the augmented form of the 42222@samp{qXfer:libraries-svr4:read} packet 42223(@pxref{qXfer svr4 library list read}). 42224 42225@item qXfer:memory-map:read 42226The remote stub understands the @samp{qXfer:memory-map:read} packet 42227(@pxref{qXfer memory map read}). 42228 42229@item qXfer:sdata:read 42230The remote stub understands the @samp{qXfer:sdata:read} packet 42231(@pxref{qXfer sdata read}). 42232 42233@item qXfer:siginfo:read 42234The remote stub understands the @samp{qXfer:siginfo:read} packet 42235(@pxref{qXfer siginfo read}). 42236 42237@item qXfer:siginfo:write 42238The remote stub understands the @samp{qXfer:siginfo:write} packet 42239(@pxref{qXfer siginfo write}). 42240 42241@item qXfer:threads:read 42242The remote stub understands the @samp{qXfer:threads:read} packet 42243(@pxref{qXfer threads read}). 42244 42245@item qXfer:traceframe-info:read 42246The remote stub understands the @samp{qXfer:traceframe-info:read} 42247packet (@pxref{qXfer traceframe info read}). 42248 42249@item qXfer:uib:read 42250The remote stub understands the @samp{qXfer:uib:read} 42251packet (@pxref{qXfer unwind info block}). 42252 42253@item qXfer:fdpic:read 42254The remote stub understands the @samp{qXfer:fdpic:read} 42255packet (@pxref{qXfer fdpic loadmap read}). 42256 42257@item QNonStop 42258The remote stub understands the @samp{QNonStop} packet 42259(@pxref{QNonStop}). 42260 42261@item QCatchSyscalls 42262The remote stub understands the @samp{QCatchSyscalls} packet 42263(@pxref{QCatchSyscalls}). 42264 42265@item QPassSignals 42266The remote stub understands the @samp{QPassSignals} packet 42267(@pxref{QPassSignals}). 42268 42269@item QStartNoAckMode 42270The remote stub understands the @samp{QStartNoAckMode} packet and 42271prefers to operate in no-acknowledgment mode. @xref{Packet Acknowledgment}. 42272 42273@item multiprocess 42274@anchor{multiprocess extensions} 42275@cindex multiprocess extensions, in remote protocol 42276The remote stub understands the multiprocess extensions to the remote 42277protocol syntax. The multiprocess extensions affect the syntax of 42278thread IDs in both packets and replies (@pxref{thread-id syntax}), and 42279add process IDs to the @samp{D} packet and @samp{W} and @samp{X} 42280replies. Note that reporting this feature indicates support for the 42281syntactic extensions only, not that the stub necessarily supports 42282debugging of more than one process at a time. The stub must not use 42283multiprocess extensions in packet replies unless @value{GDBN} has also 42284indicated it supports them in its @samp{qSupported} request. 42285 42286@item qXfer:osdata:read 42287The remote stub understands the @samp{qXfer:osdata:read} packet 42288((@pxref{qXfer osdata read}). 42289 42290@item ConditionalBreakpoints 42291The target accepts and implements evaluation of conditional expressions 42292defined for breakpoints. The target will only report breakpoint triggers 42293when such conditions are true (@pxref{Conditions, ,Break Conditions}). 42294 42295@item ConditionalTracepoints 42296The remote stub accepts and implements conditional expressions defined 42297for tracepoints (@pxref{Tracepoint Conditions}). 42298 42299@item ReverseContinue 42300The remote stub accepts and implements the reverse continue packet 42301(@pxref{bc}). 42302 42303@item ReverseStep 42304The remote stub accepts and implements the reverse step packet 42305(@pxref{bs}). 42306 42307@item TracepointSource 42308The remote stub understands the @samp{QTDPsrc} packet that supplies 42309the source form of tracepoint definitions. 42310 42311@item QAgent 42312The remote stub understands the @samp{QAgent} packet. 42313 42314@item QAllow 42315The remote stub understands the @samp{QAllow} packet. 42316 42317@item QDisableRandomization 42318The remote stub understands the @samp{QDisableRandomization} packet. 42319 42320@item StaticTracepoint 42321@cindex static tracepoints, in remote protocol 42322The remote stub supports static tracepoints. 42323 42324@item InstallInTrace 42325@anchor{install tracepoint in tracing} 42326The remote stub supports installing tracepoint in tracing. 42327 42328@item EnableDisableTracepoints 42329The remote stub supports the @samp{QTEnable} (@pxref{QTEnable}) and 42330@samp{QTDisable} (@pxref{QTDisable}) packets that allow tracepoints 42331to be enabled and disabled while a trace experiment is running. 42332 42333@item QTBuffer:size 42334The remote stub supports the @samp{QTBuffer:size} (@pxref{QTBuffer-size}) 42335packet that allows to change the size of the trace buffer. 42336 42337@item tracenz 42338@cindex string tracing, in remote protocol 42339The remote stub supports the @samp{tracenz} bytecode for collecting strings. 42340See @ref{Bytecode Descriptions} for details about the bytecode. 42341 42342@item BreakpointCommands 42343@cindex breakpoint commands, in remote protocol 42344The remote stub supports running a breakpoint's command list itself, 42345rather than reporting the hit to @value{GDBN}. 42346 42347@item Qbtrace:off 42348The remote stub understands the @samp{Qbtrace:off} packet. 42349 42350@item Qbtrace:bts 42351The remote stub understands the @samp{Qbtrace:bts} packet. 42352 42353@item Qbtrace:pt 42354The remote stub understands the @samp{Qbtrace:pt} packet. 42355 42356@item Qbtrace-conf:bts:size 42357The remote stub understands the @samp{Qbtrace-conf:bts:size} packet. 42358 42359@item Qbtrace-conf:pt:size 42360The remote stub understands the @samp{Qbtrace-conf:pt:size} packet. 42361 42362@item swbreak 42363The remote stub reports the @samp{swbreak} stop reason for memory 42364breakpoints. 42365 42366@item hwbreak 42367The remote stub reports the @samp{hwbreak} stop reason for hardware 42368breakpoints. 42369 42370@item fork-events 42371The remote stub reports the @samp{fork} stop reason for fork events. 42372 42373@item vfork-events 42374The remote stub reports the @samp{vfork} stop reason for vfork events 42375and vforkdone events. 42376 42377@item exec-events 42378The remote stub reports the @samp{exec} stop reason for exec events. 42379 42380@item vContSupported 42381The remote stub reports the supported actions in the reply to 42382@samp{vCont?} packet. 42383 42384@item QThreadEvents 42385The remote stub understands the @samp{QThreadEvents} packet. 42386 42387@item no-resumed 42388The remote stub reports the @samp{N} stop reply. 42389 42390 42391@item memory-tagging 42392The remote stub supports and implements the required memory tagging 42393functionality and understands the @samp{qMemTags} (@pxref{qMemTags}) and 42394@samp{QMemTags} (@pxref{QMemTags}) packets. 42395 42396For AArch64 GNU/Linux systems, this feature also requires access to the 42397@file{/proc/@var{pid}/smaps} file so memory mapping page flags can be inspected. 42398This is done via the @samp{vFile} requests. 42399 42400@end table 42401 42402@item qSymbol:: 42403@cindex symbol lookup, remote request 42404@cindex @samp{qSymbol} packet 42405Notify the target that @value{GDBN} is prepared to serve symbol lookup 42406requests. Accept requests from the target for the values of symbols. 42407 42408Reply: 42409@table @samp 42410@item OK 42411The target does not need to look up any (more) symbols. 42412@item qSymbol:@var{sym_name} 42413The target requests the value of symbol @var{sym_name} (hex encoded). 42414@value{GDBN} may provide the value by using the 42415@samp{qSymbol:@var{sym_value}:@var{sym_name}} message, described 42416below. 42417@end table 42418 42419@item qSymbol:@var{sym_value}:@var{sym_name} 42420Set the value of @var{sym_name} to @var{sym_value}. 42421 42422@var{sym_name} (hex encoded) is the name of a symbol whose value the 42423target has previously requested. 42424 42425@var{sym_value} (hex) is the value for symbol @var{sym_name}. If 42426@value{GDBN} cannot supply a value for @var{sym_name}, then this field 42427will be empty. 42428 42429Reply: 42430@table @samp 42431@item OK 42432The target does not need to look up any (more) symbols. 42433@item qSymbol:@var{sym_name} 42434The target requests the value of a new symbol @var{sym_name} (hex 42435encoded). @value{GDBN} will continue to supply the values of symbols 42436(if available), until the target ceases to request them. 42437@end table 42438 42439@item qTBuffer 42440@itemx QTBuffer 42441@itemx QTDisconnected 42442@itemx QTDP 42443@itemx QTDPsrc 42444@itemx QTDV 42445@itemx qTfP 42446@itemx qTfV 42447@itemx QTFrame 42448@itemx qTMinFTPILen 42449 42450@xref{Tracepoint Packets}. 42451 42452@item qThreadExtraInfo,@var{thread-id} 42453@cindex thread attributes info, remote request 42454@cindex @samp{qThreadExtraInfo} packet 42455Obtain from the target OS a printable string description of thread 42456attributes for the thread @var{thread-id}; see @ref{thread-id syntax}, 42457for the forms of @var{thread-id}. This 42458string may contain anything that the target OS thinks is interesting 42459for @value{GDBN} to tell the user about the thread. The string is 42460displayed in @value{GDBN}'s @code{info threads} display. Some 42461examples of possible thread extra info strings are @samp{Runnable}, or 42462@samp{Blocked on Mutex}. 42463 42464Reply: 42465@table @samp 42466@item @var{XX}@dots{} 42467Where @samp{@var{XX}@dots{}} is a hex encoding of @sc{ascii} data, 42468comprising the printable string containing the extra information about 42469the thread's attributes. 42470@end table 42471 42472(Note that the @code{qThreadExtraInfo} packet's name is separated from 42473the command by a @samp{,}, not a @samp{:}, contrary to the naming 42474conventions above. Please don't use this packet as a model for new 42475packets.) 42476 42477@item QTNotes 42478@itemx qTP 42479@itemx QTSave 42480@itemx qTsP 42481@itemx qTsV 42482@itemx QTStart 42483@itemx QTStop 42484@itemx QTEnable 42485@itemx QTDisable 42486@itemx QTinit 42487@itemx QTro 42488@itemx qTStatus 42489@itemx qTV 42490@itemx qTfSTM 42491@itemx qTsSTM 42492@itemx qTSTMat 42493@xref{Tracepoint Packets}. 42494 42495@item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length} 42496@cindex read special object, remote request 42497@cindex @samp{qXfer} packet 42498@anchor{qXfer read} 42499Read uninterpreted bytes from the target's special data area 42500identified by the keyword @var{object}. Request @var{length} bytes 42501starting at @var{offset} bytes into the data. The content and 42502encoding of @var{annex} is specific to @var{object}; it can supply 42503additional details about what data to access. 42504 42505Reply: 42506@table @samp 42507@item m @var{data} 42508Data @var{data} (@pxref{Binary Data}) has been read from the 42509target. There may be more data at a higher address (although 42510it is permitted to return @samp{m} even for the last valid 42511block of data, as long as at least one byte of data was read). 42512It is possible for @var{data} to have fewer bytes than the @var{length} in the 42513request. 42514 42515@item l @var{data} 42516Data @var{data} (@pxref{Binary Data}) has been read from the target. 42517There is no more data to be read. It is possible for @var{data} to 42518have fewer bytes than the @var{length} in the request. 42519 42520@item l 42521The @var{offset} in the request is at the end of the data. 42522There is no more data to be read. 42523 42524@item E00 42525The request was malformed, or @var{annex} was invalid. 42526 42527@item E @var{nn} 42528The offset was invalid, or there was an error encountered reading the data. 42529The @var{nn} part is a hex-encoded @code{errno} value. 42530 42531@item @w{} 42532An empty reply indicates the @var{object} string was not recognized by 42533the stub, or that the object does not support reading. 42534@end table 42535 42536Here are the specific requests of this form defined so far. All the 42537@samp{qXfer:@var{object}:read:@dots{}} requests use the same reply 42538formats, listed above. 42539 42540@table @samp 42541@item qXfer:auxv:read::@var{offset},@var{length} 42542@anchor{qXfer auxiliary vector read} 42543Access the target's @dfn{auxiliary vector}. @xref{OS Information, 42544auxiliary vector}. Note @var{annex} must be empty. 42545 42546This packet is not probed by default; the remote stub must request it, 42547by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 42548 42549@item qXfer:btrace:read:@var{annex}:@var{offset},@var{length} 42550@anchor{qXfer btrace read} 42551 42552Return a description of the current branch trace. 42553@xref{Branch Trace Format}. The annex part of the generic @samp{qXfer} 42554packet may have one of the following values: 42555 42556@table @code 42557@item all 42558Returns all available branch trace. 42559 42560@item new 42561Returns all available branch trace if the branch trace changed since 42562the last read request. 42563 42564@item delta 42565Returns the new branch trace since the last read request. Adds a new 42566block to the end of the trace that begins at zero and ends at the source 42567location of the first branch in the trace buffer. This extra block is 42568used to stitch traces together. 42569 42570If the trace buffer overflowed, returns an error indicating the overflow. 42571@end table 42572 42573This packet is not probed by default; the remote stub must request it 42574by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 42575 42576@item qXfer:btrace-conf:read::@var{offset},@var{length} 42577@anchor{qXfer btrace-conf read} 42578 42579Return a description of the current branch trace configuration. 42580@xref{Branch Trace Configuration Format}. 42581 42582This packet is not probed by default; the remote stub must request it 42583by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 42584 42585@item qXfer:exec-file:read:@var{annex}:@var{offset},@var{length} 42586@anchor{qXfer executable filename read} 42587Return the full absolute name of the file that was executed to create 42588a process running on the remote system. The annex specifies the 42589numeric process ID of the process to query, encoded as a hexadecimal 42590number. If the annex part is empty the remote stub should return the 42591filename corresponding to the currently executing process. 42592 42593This packet is not probed by default; the remote stub must request it, 42594by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 42595 42596@item qXfer:features:read:@var{annex}:@var{offset},@var{length} 42597@anchor{qXfer target description read} 42598Access the @dfn{target description}. @xref{Target Descriptions}. The 42599annex specifies which XML document to access. The main description is 42600always loaded from the @samp{target.xml} annex. 42601 42602This packet is not probed by default; the remote stub must request it, 42603by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 42604 42605@item qXfer:libraries:read:@var{annex}:@var{offset},@var{length} 42606@anchor{qXfer library list read} 42607Access the target's list of loaded libraries. @xref{Library List Format}. 42608The annex part of the generic @samp{qXfer} packet must be empty 42609(@pxref{qXfer read}). 42610 42611Targets which maintain a list of libraries in the program's memory do 42612not need to implement this packet; it is designed for platforms where 42613the operating system manages the list of loaded libraries. 42614 42615This packet is not probed by default; the remote stub must request it, 42616by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 42617 42618@item qXfer:libraries-svr4:read:@var{annex}:@var{offset},@var{length} 42619@anchor{qXfer svr4 library list read} 42620Access the target's list of loaded libraries when the target is an SVR4 42621platform. @xref{Library List Format for SVR4 Targets}. The annex part 42622of the generic @samp{qXfer} packet must be empty unless the remote 42623stub indicated it supports the augmented form of this packet 42624by supplying an appropriate @samp{qSupported} response 42625(@pxref{qXfer read}, @ref{qSupported}). 42626 42627This packet is optional for better performance on SVR4 targets. 42628@value{GDBN} uses memory read packets to read the SVR4 library list otherwise. 42629 42630This packet is not probed by default; the remote stub must request it, 42631by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 42632 42633If the remote stub indicates it supports the augmented form of this 42634packet then the annex part of the generic @samp{qXfer} packet may 42635contain a semicolon-separated list of @samp{@var{name}=@var{value}} 42636arguments. The currently supported arguments are: 42637 42638@table @code 42639@item start=@var{address} 42640A hexadecimal number specifying the address of the @samp{struct 42641link_map} to start reading the library list from. If unset or zero 42642then the first @samp{struct link_map} in the library list will be 42643chosen as the starting point. 42644 42645@item prev=@var{address} 42646A hexadecimal number specifying the address of the @samp{struct 42647link_map} immediately preceding the @samp{struct link_map} 42648specified by the @samp{start} argument. If unset or zero then 42649the remote stub will expect that no @samp{struct link_map} 42650exists prior to the starting point. 42651 42652@end table 42653 42654Arguments that are not understood by the remote stub will be silently 42655ignored. 42656 42657@item qXfer:memory-map:read::@var{offset},@var{length} 42658@anchor{qXfer memory map read} 42659Access the target's @dfn{memory-map}. @xref{Memory Map Format}. The 42660annex part of the generic @samp{qXfer} packet must be empty 42661(@pxref{qXfer read}). 42662 42663This packet is not probed by default; the remote stub must request it, 42664by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 42665 42666@item qXfer:sdata:read::@var{offset},@var{length} 42667@anchor{qXfer sdata read} 42668 42669Read contents of the extra collected static tracepoint marker 42670information. The annex part of the generic @samp{qXfer} packet must 42671be empty (@pxref{qXfer read}). @xref{Tracepoint Actions,,Tracepoint 42672Action Lists}. 42673 42674This packet is not probed by default; the remote stub must request it, 42675by supplying an appropriate @samp{qSupported} response 42676(@pxref{qSupported}). 42677 42678@item qXfer:siginfo:read::@var{offset},@var{length} 42679@anchor{qXfer siginfo read} 42680Read contents of the extra signal information on the target 42681system. The annex part of the generic @samp{qXfer} packet must be 42682empty (@pxref{qXfer read}). 42683 42684This packet is not probed by default; the remote stub must request it, 42685by supplying an appropriate @samp{qSupported} response 42686(@pxref{qSupported}). 42687 42688@item qXfer:threads:read::@var{offset},@var{length} 42689@anchor{qXfer threads read} 42690Access the list of threads on target. @xref{Thread List Format}. The 42691annex part of the generic @samp{qXfer} packet must be empty 42692(@pxref{qXfer read}). 42693 42694This packet is not probed by default; the remote stub must request it, 42695by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 42696 42697@item qXfer:traceframe-info:read::@var{offset},@var{length} 42698@anchor{qXfer traceframe info read} 42699 42700Return a description of the current traceframe's contents. 42701@xref{Traceframe Info Format}. The annex part of the generic 42702@samp{qXfer} packet must be empty (@pxref{qXfer read}). 42703 42704This packet is not probed by default; the remote stub must request it, 42705by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 42706 42707@item qXfer:uib:read:@var{pc}:@var{offset},@var{length} 42708@anchor{qXfer unwind info block} 42709 42710Return the unwind information block for @var{pc}. This packet is used 42711on OpenVMS/ia64 to ask the kernel unwind information. 42712 42713This packet is not probed by default. 42714 42715@item qXfer:fdpic:read:@var{annex}:@var{offset},@var{length} 42716@anchor{qXfer fdpic loadmap read} 42717Read contents of @code{loadmap}s on the target system. The 42718annex, either @samp{exec} or @samp{interp}, specifies which @code{loadmap}, 42719executable @code{loadmap} or interpreter @code{loadmap} to read. 42720 42721This packet is not probed by default; the remote stub must request it, 42722by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 42723 42724@item qXfer:osdata:read::@var{offset},@var{length} 42725@anchor{qXfer osdata read} 42726Access the target's @dfn{operating system information}. 42727@xref{Operating System Information}. 42728 42729@end table 42730 42731@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{} 42732@cindex write data into object, remote request 42733@anchor{qXfer write} 42734Write uninterpreted bytes into the target's special data area 42735identified by the keyword @var{object}, starting at @var{offset} bytes 42736into the data. The binary-encoded data (@pxref{Binary Data}) to be 42737written is given by @var{data}@dots{}. The content and encoding of @var{annex} 42738is specific to @var{object}; it can supply additional details about what data 42739to access. 42740 42741Reply: 42742@table @samp 42743@item @var{nn} 42744@var{nn} (hex encoded) is the number of bytes written. 42745This may be fewer bytes than supplied in the request. 42746 42747@item E00 42748The request was malformed, or @var{annex} was invalid. 42749 42750@item E @var{nn} 42751The offset was invalid, or there was an error encountered writing the data. 42752The @var{nn} part is a hex-encoded @code{errno} value. 42753 42754@item @w{} 42755An empty reply indicates the @var{object} string was not 42756recognized by the stub, or that the object does not support writing. 42757@end table 42758 42759Here are the specific requests of this form defined so far. All the 42760@samp{qXfer:@var{object}:write:@dots{}} requests use the same reply 42761formats, listed above. 42762 42763@table @samp 42764@item qXfer:siginfo:write::@var{offset}:@var{data}@dots{} 42765@anchor{qXfer siginfo write} 42766Write @var{data} to the extra signal information on the target system. 42767The annex part of the generic @samp{qXfer} packet must be 42768empty (@pxref{qXfer write}). 42769 42770This packet is not probed by default; the remote stub must request it, 42771by supplying an appropriate @samp{qSupported} response 42772(@pxref{qSupported}). 42773@end table 42774 42775@item qXfer:@var{object}:@var{operation}:@dots{} 42776Requests of this form may be added in the future. When a stub does 42777not recognize the @var{object} keyword, or its support for 42778@var{object} does not recognize the @var{operation} keyword, the stub 42779must respond with an empty packet. 42780 42781@item qAttached:@var{pid} 42782@cindex query attached, remote request 42783@cindex @samp{qAttached} packet 42784Return an indication of whether the remote server attached to an 42785existing process or created a new process. When the multiprocess 42786protocol extensions are supported (@pxref{multiprocess extensions}), 42787@var{pid} is an integer in hexadecimal format identifying the target 42788process. Otherwise, @value{GDBN} will omit the @var{pid} field and 42789the query packet will be simplified as @samp{qAttached}. 42790 42791This query is used, for example, to know whether the remote process 42792should be detached or killed when a @value{GDBN} session is ended with 42793the @code{quit} command. 42794 42795Reply: 42796@table @samp 42797@item 1 42798The remote server attached to an existing process. 42799@item 0 42800The remote server created a new process. 42801@item E @var{NN} 42802A badly formed request or an error was encountered. 42803@end table 42804 42805@item Qbtrace:bts 42806Enable branch tracing for the current thread using Branch Trace Store. 42807 42808Reply: 42809@table @samp 42810@item OK 42811Branch tracing has been enabled. 42812@item E.errtext 42813A badly formed request or an error was encountered. 42814@end table 42815 42816@item Qbtrace:pt 42817Enable branch tracing for the current thread using Intel Processor Trace. 42818 42819Reply: 42820@table @samp 42821@item OK 42822Branch tracing has been enabled. 42823@item E.errtext 42824A badly formed request or an error was encountered. 42825@end table 42826 42827@item Qbtrace:off 42828Disable branch tracing for the current thread. 42829 42830Reply: 42831@table @samp 42832@item OK 42833Branch tracing has been disabled. 42834@item E.errtext 42835A badly formed request or an error was encountered. 42836@end table 42837 42838@item Qbtrace-conf:bts:size=@var{value} 42839Set the requested ring buffer size for new threads that use the 42840btrace recording method in bts format. 42841 42842Reply: 42843@table @samp 42844@item OK 42845The ring buffer size has been set. 42846@item E.errtext 42847A badly formed request or an error was encountered. 42848@end table 42849 42850@item Qbtrace-conf:pt:size=@var{value} 42851Set the requested ring buffer size for new threads that use the 42852btrace recording method in pt format. 42853 42854Reply: 42855@table @samp 42856@item OK 42857The ring buffer size has been set. 42858@item E.errtext 42859A badly formed request or an error was encountered. 42860@end table 42861 42862@end table 42863 42864@node Architecture-Specific Protocol Details 42865@section Architecture-Specific Protocol Details 42866 42867This section describes how the remote protocol is applied to specific 42868target architectures. Also see @ref{Standard Target Features}, for 42869details of XML target descriptions for each architecture. 42870 42871@menu 42872* ARM-Specific Protocol Details:: 42873* MIPS-Specific Protocol Details:: 42874@end menu 42875 42876@node ARM-Specific Protocol Details 42877@subsection @acronym{ARM}-specific Protocol Details 42878 42879@menu 42880* ARM Breakpoint Kinds:: 42881* ARM Memory Tag Types:: 42882@end menu 42883 42884@node ARM Breakpoint Kinds 42885@subsubsection @acronym{ARM} Breakpoint Kinds 42886@cindex breakpoint kinds, @acronym{ARM} 42887 42888These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets. 42889 42890@table @r 42891 42892@item 2 4289316-bit Thumb mode breakpoint. 42894 42895@item 3 4289632-bit Thumb mode (Thumb-2) breakpoint. 42897 42898@item 4 4289932-bit @acronym{ARM} mode breakpoint. 42900 42901@end table 42902 42903@node ARM Memory Tag Types 42904@subsubsection @acronym{ARM} Memory Tag Types 42905@cindex memory tag types, @acronym{ARM} 42906 42907These memory tag types are defined for the @samp{qMemTag} and @samp{QMemTag} 42908packets. 42909 42910@table @r 42911 42912@item 0 42913MTE logical tag 42914 42915@item 1 42916MTE allocation tag 42917 42918@end table 42919 42920@node MIPS-Specific Protocol Details 42921@subsection @acronym{MIPS}-specific Protocol Details 42922 42923@menu 42924* MIPS Register packet Format:: 42925* MIPS Breakpoint Kinds:: 42926@end menu 42927 42928@node MIPS Register packet Format 42929@subsubsection @acronym{MIPS} Register Packet Format 42930@cindex register packet format, @acronym{MIPS} 42931 42932The following @code{g}/@code{G} packets have previously been defined. 42933In the below, some thirty-two bit registers are transferred as 42934sixty-four bits. Those registers should be zero/sign extended (which?) 42935to fill the space allocated. Register bytes are transferred in target 42936byte order. The two nibbles within a register byte are transferred 42937most-significant -- least-significant. 42938 42939@table @r 42940 42941@item MIPS32 42942All registers are transferred as thirty-two bit quantities in the order: 4294332 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point 42944registers; fsr; fir; fp. 42945 42946@item MIPS64 42947All registers are transferred as sixty-four bit quantities (including 42948thirty-two bit registers such as @code{sr}). The ordering is the same 42949as @code{MIPS32}. 42950 42951@end table 42952 42953@node MIPS Breakpoint Kinds 42954@subsubsection @acronym{MIPS} Breakpoint Kinds 42955@cindex breakpoint kinds, @acronym{MIPS} 42956 42957These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets. 42958 42959@table @r 42960 42961@item 2 4296216-bit @acronym{MIPS16} mode breakpoint. 42963 42964@item 3 4296516-bit @acronym{microMIPS} mode breakpoint. 42966 42967@item 4 4296832-bit standard @acronym{MIPS} mode breakpoint. 42969 42970@item 5 4297132-bit @acronym{microMIPS} mode breakpoint. 42972 42973@end table 42974 42975@node Tracepoint Packets 42976@section Tracepoint Packets 42977@cindex tracepoint packets 42978@cindex packets, tracepoint 42979 42980Here we describe the packets @value{GDBN} uses to implement 42981tracepoints (@pxref{Tracepoints}). 42982 42983@table @samp 42984 42985@item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}[:F@var{flen}][:X@var{len},@var{bytes}]@r{[}-@r{]} 42986@cindex @samp{QTDP} packet 42987Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena} 42988is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then 42989the tracepoint is disabled. The @var{step} gives the tracepoint's step 42990count, and @var{pass} gives its pass count. If an @samp{F} is present, 42991then the tracepoint is to be a fast tracepoint, and the @var{flen} is 42992the number of bytes that the target should copy elsewhere to make room 42993for the tracepoint. If an @samp{X} is present, it introduces a 42994tracepoint condition, which consists of a hexadecimal length, followed 42995by a comma and hex-encoded bytes, in a manner similar to action 42996encodings as described below. If the trailing @samp{-} is present, 42997further @samp{QTDP} packets will follow to specify this tracepoint's 42998actions. 42999 43000Replies: 43001@table @samp 43002@item OK 43003The packet was understood and carried out. 43004@item qRelocInsn 43005@xref{Tracepoint Packets,,Relocate instruction reply packet}. 43006@item @w{} 43007The packet was not recognized. 43008@end table 43009 43010@item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]} 43011Define actions to be taken when a tracepoint is hit. The @var{n} and 43012@var{addr} must be the same as in the initial @samp{QTDP} packet for 43013this tracepoint. This packet may only be sent immediately after 43014another @samp{QTDP} packet that ended with a @samp{-}. If the 43015trailing @samp{-} is present, further @samp{QTDP} packets will follow, 43016specifying more actions for this tracepoint. 43017 43018In the series of action packets for a given tracepoint, at most one 43019can have an @samp{S} before its first @var{action}. If such a packet 43020is sent, it and the following packets define ``while-stepping'' 43021actions. Any prior packets define ordinary actions --- that is, those 43022taken when the tracepoint is first hit. If no action packet has an 43023@samp{S}, then all the packets in the series specify ordinary 43024tracepoint actions. 43025 43026The @samp{@var{action}@dots{}} portion of the packet is a series of 43027actions, concatenated without separators. Each action has one of the 43028following forms: 43029 43030@table @samp 43031 43032@item R @var{mask} 43033Collect the registers whose bits are set in @var{mask}, 43034a hexadecimal number whose @var{i}'th bit is set if register number 43035@var{i} should be collected. (The least significant bit is numbered 43036zero.) Note that @var{mask} may be any number of digits long; it may 43037not fit in a 32-bit word. 43038 43039@item M @var{basereg},@var{offset},@var{len} 43040Collect @var{len} bytes of memory starting at the address in register 43041number @var{basereg}, plus @var{offset}. If @var{basereg} is 43042@samp{-1}, then the range has a fixed address: @var{offset} is the 43043address of the lowest byte to collect. The @var{basereg}, 43044@var{offset}, and @var{len} parameters are all unsigned hexadecimal 43045values (the @samp{-1} value for @var{basereg} is a special case). 43046 43047@item X @var{len},@var{expr} 43048Evaluate @var{expr}, whose length is @var{len}, and collect memory as 43049it directs. The agent expression @var{expr} is as described in 43050@ref{Agent Expressions}. Each byte of the expression is encoded as a 43051two-digit hex number in the packet; @var{len} is the number of bytes 43052in the expression (and thus one-half the number of hex digits in the 43053packet). 43054 43055@end table 43056 43057Any number of actions may be packed together in a single @samp{QTDP} 43058packet, as long as the packet does not exceed the maximum packet 43059length (400 bytes, for many stubs). There may be only one @samp{R} 43060action per tracepoint, and it must precede any @samp{M} or @samp{X} 43061actions. Any registers referred to by @samp{M} and @samp{X} actions 43062must be collected by a preceding @samp{R} action. (The 43063``while-stepping'' actions are treated as if they were attached to a 43064separate tracepoint, as far as these restrictions are concerned.) 43065 43066Replies: 43067@table @samp 43068@item OK 43069The packet was understood and carried out. 43070@item qRelocInsn 43071@xref{Tracepoint Packets,,Relocate instruction reply packet}. 43072@item @w{} 43073The packet was not recognized. 43074@end table 43075 43076@item QTDPsrc:@var{n}:@var{addr}:@var{type}:@var{start}:@var{slen}:@var{bytes} 43077@cindex @samp{QTDPsrc} packet 43078Specify a source string of tracepoint @var{n} at address @var{addr}. 43079This is useful to get accurate reproduction of the tracepoints 43080originally downloaded at the beginning of the trace run. The @var{type} 43081is the name of the tracepoint part, such as @samp{cond} for the 43082tracepoint's conditional expression (see below for a list of types), while 43083@var{bytes} is the string, encoded in hexadecimal. 43084 43085@var{start} is the offset of the @var{bytes} within the overall source 43086string, while @var{slen} is the total length of the source string. 43087This is intended for handling source strings that are longer than will 43088fit in a single packet. 43089@c Add detailed example when this info is moved into a dedicated 43090@c tracepoint descriptions section. 43091 43092The available string types are @samp{at} for the location, 43093@samp{cond} for the conditional, and @samp{cmd} for an action command. 43094@value{GDBN} sends a separate packet for each command in the action 43095list, in the same order in which the commands are stored in the list. 43096 43097The target does not need to do anything with source strings except 43098report them back as part of the replies to the @samp{qTfP}/@samp{qTsP} 43099query packets. 43100 43101Although this packet is optional, and @value{GDBN} will only send it 43102if the target replies with @samp{TracepointSource} @xref{General 43103Query Packets}, it makes both disconnected tracing and trace files 43104much easier to use. Otherwise the user must be careful that the 43105tracepoints in effect while looking at trace frames are identical to 43106the ones in effect during the trace run; even a small discrepancy 43107could cause @samp{tdump} not to work, or a particular trace frame not 43108be found. 43109 43110@item QTDV:@var{n}:@var{value}:@var{builtin}:@var{name} 43111@cindex define trace state variable, remote request 43112@cindex @samp{QTDV} packet 43113Create a new trace state variable, number @var{n}, with an initial 43114value of @var{value}, which is a 64-bit signed integer. Both @var{n} 43115and @var{value} are encoded as hexadecimal values. @value{GDBN} has 43116the option of not using this packet for initial values of zero; the 43117target should simply create the trace state variables as they are 43118mentioned in expressions. The value @var{builtin} should be 1 (one) 43119if the trace state variable is builtin and 0 (zero) if it is not builtin. 43120@value{GDBN} only sets @var{builtin} to 1 if a previous @samp{qTfV} or 43121@samp{qTsV} packet had it set. The contents of @var{name} is the 43122hex-encoded name (without the leading @samp{$}) of the trace state 43123variable. 43124 43125@item QTFrame:@var{n} 43126@cindex @samp{QTFrame} packet 43127Select the @var{n}'th tracepoint frame from the buffer, and use the 43128register and memory contents recorded there to answer subsequent 43129request packets from @value{GDBN}. 43130 43131A successful reply from the stub indicates that the stub has found the 43132requested frame. The response is a series of parts, concatenated 43133without separators, describing the frame we selected. Each part has 43134one of the following forms: 43135 43136@table @samp 43137@item F @var{f} 43138The selected frame is number @var{n} in the trace frame buffer; 43139@var{f} is a hexadecimal number. If @var{f} is @samp{-1}, then there 43140was no frame matching the criteria in the request packet. 43141 43142@item T @var{t} 43143The selected trace frame records a hit of tracepoint number @var{t}; 43144@var{t} is a hexadecimal number. 43145 43146@end table 43147 43148@item QTFrame:pc:@var{addr} 43149Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the 43150currently selected frame whose PC is @var{addr}; 43151@var{addr} is a hexadecimal number. 43152 43153@item QTFrame:tdp:@var{t} 43154Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the 43155currently selected frame that is a hit of tracepoint @var{t}; @var{t} 43156is a hexadecimal number. 43157 43158@item QTFrame:range:@var{start}:@var{end} 43159Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the 43160currently selected frame whose PC is between @var{start} (inclusive) 43161and @var{end} (inclusive); @var{start} and @var{end} are hexadecimal 43162numbers. 43163 43164@item QTFrame:outside:@var{start}:@var{end} 43165Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first 43166frame @emph{outside} the given range of addresses (exclusive). 43167 43168@item qTMinFTPILen 43169@cindex @samp{qTMinFTPILen} packet 43170This packet requests the minimum length of instruction at which a fast 43171tracepoint (@pxref{Set Tracepoints}) may be placed. For instance, on 43172the 32-bit x86 architecture, it is possible to use a 4-byte jump, but 43173it depends on the target system being able to create trampolines in 43174the first 64K of memory, which might or might not be possible for that 43175system. So the reply to this packet will be 4 if it is able to 43176arrange for that. 43177 43178Replies: 43179 43180@table @samp 43181@item 0 43182The minimum instruction length is currently unknown. 43183@item @var{length} 43184The minimum instruction length is @var{length}, where @var{length} 43185is a hexadecimal number greater or equal to 1. A reply 43186of 1 means that a fast tracepoint may be placed on any instruction 43187regardless of size. 43188@item E 43189An error has occurred. 43190@item @w{} 43191An empty reply indicates that the request is not supported by the stub. 43192@end table 43193 43194@item QTStart 43195@cindex @samp{QTStart} packet 43196Begin the tracepoint experiment. Begin collecting data from 43197tracepoint hits in the trace frame buffer. This packet supports the 43198@samp{qRelocInsn} reply (@pxref{Tracepoint Packets,,Relocate 43199instruction reply packet}). 43200 43201@item QTStop 43202@cindex @samp{QTStop} packet 43203End the tracepoint experiment. Stop collecting trace frames. 43204 43205@item QTEnable:@var{n}:@var{addr} 43206@anchor{QTEnable} 43207@cindex @samp{QTEnable} packet 43208Enable tracepoint @var{n} at address @var{addr} in a started tracepoint 43209experiment. If the tracepoint was previously disabled, then collection 43210of data from it will resume. 43211 43212@item QTDisable:@var{n}:@var{addr} 43213@anchor{QTDisable} 43214@cindex @samp{QTDisable} packet 43215Disable tracepoint @var{n} at address @var{addr} in a started tracepoint 43216experiment. No more data will be collected from the tracepoint unless 43217@samp{QTEnable:@var{n}:@var{addr}} is subsequently issued. 43218 43219@item QTinit 43220@cindex @samp{QTinit} packet 43221Clear the table of tracepoints, and empty the trace frame buffer. 43222 43223@item QTro:@var{start1},@var{end1}:@var{start2},@var{end2}:@dots{} 43224@cindex @samp{QTro} packet 43225Establish the given ranges of memory as ``transparent''. The stub 43226will answer requests for these ranges from memory's current contents, 43227if they were not collected as part of the tracepoint hit. 43228 43229@value{GDBN} uses this to mark read-only regions of memory, like those 43230containing program code. Since these areas never change, they should 43231still have the same contents they did when the tracepoint was hit, so 43232there's no reason for the stub to refuse to provide their contents. 43233 43234@item QTDisconnected:@var{value} 43235@cindex @samp{QTDisconnected} packet 43236Set the choice to what to do with the tracing run when @value{GDBN} 43237disconnects from the target. A @var{value} of 1 directs the target to 43238continue the tracing run, while 0 tells the target to stop tracing if 43239@value{GDBN} is no longer in the picture. 43240 43241@item qTStatus 43242@cindex @samp{qTStatus} packet 43243Ask the stub if there is a trace experiment running right now. 43244 43245The reply has the form: 43246 43247@table @samp 43248 43249@item T@var{running}@r{[};@var{field}@r{]}@dots{} 43250@var{running} is a single digit @code{1} if the trace is presently 43251running, or @code{0} if not. It is followed by semicolon-separated 43252optional fields that an agent may use to report additional status. 43253 43254@end table 43255 43256If the trace is not running, the agent may report any of several 43257explanations as one of the optional fields: 43258 43259@table @samp 43260 43261@item tnotrun:0 43262No trace has been run yet. 43263 43264@item tstop[:@var{text}]:0 43265The trace was stopped by a user-originated stop command. The optional 43266@var{text} field is a user-supplied string supplied as part of the 43267stop command (for instance, an explanation of why the trace was 43268stopped manually). It is hex-encoded. 43269 43270@item tfull:0 43271The trace stopped because the trace buffer filled up. 43272 43273@item tdisconnected:0 43274The trace stopped because @value{GDBN} disconnected from the target. 43275 43276@item tpasscount:@var{tpnum} 43277The trace stopped because tracepoint @var{tpnum} exceeded its pass count. 43278 43279@item terror:@var{text}:@var{tpnum} 43280The trace stopped because tracepoint @var{tpnum} had an error. The 43281string @var{text} is available to describe the nature of the error 43282(for instance, a divide by zero in the condition expression); it 43283is hex encoded. 43284 43285@item tunknown:0 43286The trace stopped for some other reason. 43287 43288@end table 43289 43290Additional optional fields supply statistical and other information. 43291Although not required, they are extremely useful for users monitoring 43292the progress of a trace run. If a trace has stopped, and these 43293numbers are reported, they must reflect the state of the just-stopped 43294trace. 43295 43296@table @samp 43297 43298@item tframes:@var{n} 43299The number of trace frames in the buffer. 43300 43301@item tcreated:@var{n} 43302The total number of trace frames created during the run. This may 43303be larger than the trace frame count, if the buffer is circular. 43304 43305@item tsize:@var{n} 43306The total size of the trace buffer, in bytes. 43307 43308@item tfree:@var{n} 43309The number of bytes still unused in the buffer. 43310 43311@item circular:@var{n} 43312The value of the circular trace buffer flag. @code{1} means that the 43313trace buffer is circular and old trace frames will be discarded if 43314necessary to make room, @code{0} means that the trace buffer is linear 43315and may fill up. 43316 43317@item disconn:@var{n} 43318The value of the disconnected tracing flag. @code{1} means that 43319tracing will continue after @value{GDBN} disconnects, @code{0} means 43320that the trace run will stop. 43321 43322@end table 43323 43324@item qTP:@var{tp}:@var{addr} 43325@cindex tracepoint status, remote request 43326@cindex @samp{qTP} packet 43327Ask the stub for the current state of tracepoint number @var{tp} at 43328address @var{addr}. 43329 43330Replies: 43331@table @samp 43332@item V@var{hits}:@var{usage} 43333The tracepoint has been hit @var{hits} times so far during the trace 43334run, and accounts for @var{usage} in the trace buffer. Note that 43335@code{while-stepping} steps are not counted as separate hits, but the 43336steps' space consumption is added into the usage number. 43337 43338@end table 43339 43340@item qTV:@var{var} 43341@cindex trace state variable value, remote request 43342@cindex @samp{qTV} packet 43343Ask the stub for the value of the trace state variable number @var{var}. 43344 43345Replies: 43346@table @samp 43347@item V@var{value} 43348The value of the variable is @var{value}. This will be the current 43349value of the variable if the user is examining a running target, or a 43350saved value if the variable was collected in the trace frame that the 43351user is looking at. Note that multiple requests may result in 43352different reply values, such as when requesting values while the 43353program is running. 43354 43355@item U 43356The value of the variable is unknown. This would occur, for example, 43357if the user is examining a trace frame in which the requested variable 43358was not collected. 43359@end table 43360 43361@item qTfP 43362@cindex @samp{qTfP} packet 43363@itemx qTsP 43364@cindex @samp{qTsP} packet 43365These packets request data about tracepoints that are being used by 43366the target. @value{GDBN} sends @code{qTfP} to get the first piece 43367of data, and multiple @code{qTsP} to get additional pieces. Replies 43368to these packets generally take the form of the @code{QTDP} packets 43369that define tracepoints. (FIXME add detailed syntax) 43370 43371@item qTfV 43372@cindex @samp{qTfV} packet 43373@itemx qTsV 43374@cindex @samp{qTsV} packet 43375These packets request data about trace state variables that are on the 43376target. @value{GDBN} sends @code{qTfV} to get the first vari of data, 43377and multiple @code{qTsV} to get additional variables. Replies to 43378these packets follow the syntax of the @code{QTDV} packets that define 43379trace state variables. 43380 43381@item qTfSTM 43382@itemx qTsSTM 43383@anchor{qTfSTM} 43384@anchor{qTsSTM} 43385@cindex @samp{qTfSTM} packet 43386@cindex @samp{qTsSTM} packet 43387These packets request data about static tracepoint markers that exist 43388in the target program. @value{GDBN} sends @code{qTfSTM} to get the 43389first piece of data, and multiple @code{qTsSTM} to get additional 43390pieces. Replies to these packets take the following form: 43391 43392Reply: 43393@table @samp 43394@item m @var{address}:@var{id}:@var{extra} 43395A single marker 43396@item m @var{address}:@var{id}:@var{extra},@var{address}:@var{id}:@var{extra}@dots{} 43397a comma-separated list of markers 43398@item l 43399(lower case letter @samp{L}) denotes end of list. 43400@item E @var{nn} 43401An error occurred. The error number @var{nn} is given as hex digits. 43402@item @w{} 43403An empty reply indicates that the request is not supported by the 43404stub. 43405@end table 43406 43407The @var{address} is encoded in hex; 43408@var{id} and @var{extra} are strings encoded in hex. 43409 43410In response to each query, the target will reply with a list of one or 43411more markers, separated by commas. @value{GDBN} will respond to each 43412reply with a request for more markers (using the @samp{qs} form of the 43413query), until the target responds with @samp{l} (lower-case ell, for 43414@dfn{last}). 43415 43416@item qTSTMat:@var{address} 43417@anchor{qTSTMat} 43418@cindex @samp{qTSTMat} packet 43419This packets requests data about static tracepoint markers in the 43420target program at @var{address}. Replies to this packet follow the 43421syntax of the @samp{qTfSTM} and @code{qTsSTM} packets that list static 43422tracepoint markers. 43423 43424@item QTSave:@var{filename} 43425@cindex @samp{QTSave} packet 43426This packet directs the target to save trace data to the file name 43427@var{filename} in the target's filesystem. The @var{filename} is encoded 43428as a hex string; the interpretation of the file name (relative vs 43429absolute, wild cards, etc) is up to the target. 43430 43431@item qTBuffer:@var{offset},@var{len} 43432@cindex @samp{qTBuffer} packet 43433Return up to @var{len} bytes of the current contents of trace buffer, 43434starting at @var{offset}. The trace buffer is treated as if it were 43435a contiguous collection of traceframes, as per the trace file format. 43436The reply consists as many hex-encoded bytes as the target can deliver 43437in a packet; it is not an error to return fewer than were asked for. 43438A reply consisting of just @code{l} indicates that no bytes are 43439available. 43440 43441@item QTBuffer:circular:@var{value} 43442This packet directs the target to use a circular trace buffer if 43443@var{value} is 1, or a linear buffer if the value is 0. 43444 43445@item QTBuffer:size:@var{size} 43446@anchor{QTBuffer-size} 43447@cindex @samp{QTBuffer size} packet 43448This packet directs the target to make the trace buffer be of size 43449@var{size} if possible. A value of @code{-1} tells the target to 43450use whatever size it prefers. 43451 43452@item QTNotes:@r{[}@var{type}:@var{text}@r{]}@r{[};@var{type}:@var{text}@r{]}@dots{} 43453@cindex @samp{QTNotes} packet 43454This packet adds optional textual notes to the trace run. Allowable 43455types include @code{user}, @code{notes}, and @code{tstop}, the 43456@var{text} fields are arbitrary strings, hex-encoded. 43457 43458@end table 43459 43460@subsection Relocate instruction reply packet 43461When installing fast tracepoints in memory, the target may need to 43462relocate the instruction currently at the tracepoint address to a 43463different address in memory. For most instructions, a simple copy is 43464enough, but, for example, call instructions that implicitly push the 43465return address on the stack, and relative branches or other 43466PC-relative instructions require offset adjustment, so that the effect 43467of executing the instruction at a different address is the same as if 43468it had executed in the original location. 43469 43470In response to several of the tracepoint packets, the target may also 43471respond with a number of intermediate @samp{qRelocInsn} request 43472packets before the final result packet, to have @value{GDBN} handle 43473this relocation operation. If a packet supports this mechanism, its 43474documentation will explicitly say so. See for example the above 43475descriptions for the @samp{QTStart} and @samp{QTDP} packets. The 43476format of the request is: 43477 43478@table @samp 43479@item qRelocInsn:@var{from};@var{to} 43480 43481This requests @value{GDBN} to copy instruction at address @var{from} 43482to address @var{to}, possibly adjusted so that executing the 43483instruction at @var{to} has the same effect as executing it at 43484@var{from}. @value{GDBN} writes the adjusted instruction to target 43485memory starting at @var{to}. 43486@end table 43487 43488Replies: 43489@table @samp 43490@item qRelocInsn:@var{adjusted_size} 43491Informs the stub the relocation is complete. The @var{adjusted_size} is 43492the length in bytes of resulting relocated instruction sequence. 43493@item E @var{NN} 43494A badly formed request was detected, or an error was encountered while 43495relocating the instruction. 43496@end table 43497 43498@node Host I/O Packets 43499@section Host I/O Packets 43500@cindex Host I/O, remote protocol 43501@cindex file transfer, remote protocol 43502 43503The @dfn{Host I/O} packets allow @value{GDBN} to perform I/O 43504operations on the far side of a remote link. For example, Host I/O is 43505used to upload and download files to a remote target with its own 43506filesystem. Host I/O uses the same constant values and data structure 43507layout as the target-initiated File-I/O protocol. However, the 43508Host I/O packets are structured differently. The target-initiated 43509protocol relies on target memory to store parameters and buffers. 43510Host I/O requests are initiated by @value{GDBN}, and the 43511target's memory is not involved. @xref{File-I/O Remote Protocol 43512Extension}, for more details on the target-initiated protocol. 43513 43514The Host I/O request packets all encode a single operation along with 43515its arguments. They have this format: 43516 43517@table @samp 43518 43519@item vFile:@var{operation}: @var{parameter}@dots{} 43520@var{operation} is the name of the particular request; the target 43521should compare the entire packet name up to the second colon when checking 43522for a supported operation. The format of @var{parameter} depends on 43523the operation. Numbers are always passed in hexadecimal. Negative 43524numbers have an explicit minus sign (i.e.@: two's complement is not 43525used). Strings (e.g.@: filenames) are encoded as a series of 43526hexadecimal bytes. The last argument to a system call may be a 43527buffer of escaped binary data (@pxref{Binary Data}). 43528 43529@end table 43530 43531The valid responses to Host I/O packets are: 43532 43533@table @samp 43534 43535@item F @var{result} [, @var{errno}] [; @var{attachment}] 43536@var{result} is the integer value returned by this operation, usually 43537non-negative for success and -1 for errors. If an error has occured, 43538@var{errno} will be included in the result specifying a 43539value defined by the File-I/O protocol (@pxref{Errno Values}). For 43540operations which return data, @var{attachment} supplies the data as a 43541binary buffer. Binary buffers in response packets are escaped in the 43542normal way (@pxref{Binary Data}). See the individual packet 43543documentation for the interpretation of @var{result} and 43544@var{attachment}. 43545 43546@item @w{} 43547An empty response indicates that this operation is not recognized. 43548 43549@end table 43550 43551These are the supported Host I/O operations: 43552 43553@table @samp 43554@item vFile:open: @var{filename}, @var{flags}, @var{mode} 43555Open a file at @var{filename} and return a file descriptor for it, or 43556return -1 if an error occurs. The @var{filename} is a string, 43557@var{flags} is an integer indicating a mask of open flags 43558(@pxref{Open Flags}), and @var{mode} is an integer indicating a mask 43559of mode bits to use if the file is created (@pxref{mode_t Values}). 43560@xref{open}, for details of the open flags and mode values. 43561 43562@item vFile:close: @var{fd} 43563Close the open file corresponding to @var{fd} and return 0, or 43564-1 if an error occurs. 43565 43566@item vFile:pread: @var{fd}, @var{count}, @var{offset} 43567Read data from the open file corresponding to @var{fd}. Up to 43568@var{count} bytes will be read from the file, starting at @var{offset} 43569relative to the start of the file. The target may read fewer bytes; 43570common reasons include packet size limits and an end-of-file 43571condition. The number of bytes read is returned. Zero should only be 43572returned for a successful read at the end of the file, or if 43573@var{count} was zero. 43574 43575The data read should be returned as a binary attachment on success. 43576If zero bytes were read, the response should include an empty binary 43577attachment (i.e.@: a trailing semicolon). The return value is the 43578number of target bytes read; the binary attachment may be longer if 43579some characters were escaped. 43580 43581@item vFile:pwrite: @var{fd}, @var{offset}, @var{data} 43582Write @var{data} (a binary buffer) to the open file corresponding 43583to @var{fd}. Start the write at @var{offset} from the start of the 43584file. Unlike many @code{write} system calls, there is no 43585separate @var{count} argument; the length of @var{data} in the 43586packet is used. @samp{vFile:pwrite} returns the number of bytes written, 43587which may be shorter than the length of @var{data}, or -1 if an 43588error occurred. 43589 43590@item vFile:fstat: @var{fd} 43591Get information about the open file corresponding to @var{fd}. 43592On success the information is returned as a binary attachment 43593and the return value is the size of this attachment in bytes. 43594If an error occurs the return value is -1. The format of the 43595returned binary attachment is as described in @ref{struct stat}. 43596 43597@item vFile:unlink: @var{filename} 43598Delete the file at @var{filename} on the target. Return 0, 43599or -1 if an error occurs. The @var{filename} is a string. 43600 43601@item vFile:readlink: @var{filename} 43602Read value of symbolic link @var{filename} on the target. Return 43603the number of bytes read, or -1 if an error occurs. 43604 43605The data read should be returned as a binary attachment on success. 43606If zero bytes were read, the response should include an empty binary 43607attachment (i.e.@: a trailing semicolon). The return value is the 43608number of target bytes read; the binary attachment may be longer if 43609some characters were escaped. 43610 43611@item vFile:setfs: @var{pid} 43612Select the filesystem on which @code{vFile} operations with 43613@var{filename} arguments will operate. This is required for 43614@value{GDBN} to be able to access files on remote targets where 43615the remote stub does not share a common filesystem with the 43616inferior(s). 43617 43618If @var{pid} is nonzero, select the filesystem as seen by process 43619@var{pid}. If @var{pid} is zero, select the filesystem as seen by 43620the remote stub. Return 0 on success, or -1 if an error occurs. 43621If @code{vFile:setfs:} indicates success, the selected filesystem 43622remains selected until the next successful @code{vFile:setfs:} 43623operation. 43624 43625@end table 43626 43627@node Interrupts 43628@section Interrupts 43629@cindex interrupts (remote protocol) 43630@anchor{interrupting remote targets} 43631 43632In all-stop mode, when a program on the remote target is running, 43633@value{GDBN} may attempt to interrupt it by sending a @samp{Ctrl-C}, 43634@code{BREAK} or a @code{BREAK} followed by @code{g}, control of which 43635is specified via @value{GDBN}'s @samp{interrupt-sequence}. 43636 43637The precise meaning of @code{BREAK} is defined by the transport 43638mechanism and may, in fact, be undefined. @value{GDBN} does not 43639currently define a @code{BREAK} mechanism for any of the network 43640interfaces except for TCP, in which case @value{GDBN} sends the 43641@code{telnet} BREAK sequence. 43642 43643@samp{Ctrl-C}, on the other hand, is defined and implemented for all 43644transport mechanisms. It is represented by sending the single byte 43645@code{0x03} without any of the usual packet overhead described in 43646the Overview section (@pxref{Overview}). When a @code{0x03} byte is 43647transmitted as part of a packet, it is considered to be packet data 43648and does @emph{not} represent an interrupt. E.g., an @samp{X} packet 43649(@pxref{X packet}), used for binary downloads, may include an unescaped 43650@code{0x03} as part of its packet. 43651 43652@code{BREAK} followed by @code{g} is also known as Magic SysRq g. 43653When Linux kernel receives this sequence from serial port, 43654it stops execution and connects to gdb. 43655 43656In non-stop mode, because packet resumptions are asynchronous 43657(@pxref{vCont packet}), @value{GDBN} is always free to send a remote 43658command to the remote stub, even when the target is running. For that 43659reason, @value{GDBN} instead sends a regular packet (@pxref{vCtrlC 43660packet}) with the usual packet framing instead of the single byte 43661@code{0x03}. 43662 43663Stubs are not required to recognize these interrupt mechanisms and the 43664precise meaning associated with receipt of the interrupt is 43665implementation defined. If the target supports debugging of multiple 43666threads and/or processes, it should attempt to interrupt all 43667currently-executing threads and processes. 43668If the stub is successful at interrupting the 43669running program, it should send one of the stop 43670reply packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result 43671of successfully stopping the program in all-stop mode, and a stop reply 43672for each stopped thread in non-stop mode. 43673Interrupts received while the 43674program is stopped are queued and the program will be interrupted when 43675it is resumed next time. 43676 43677@node Notification Packets 43678@section Notification Packets 43679@cindex notification packets 43680@cindex packets, notification 43681 43682The @value{GDBN} remote serial protocol includes @dfn{notifications}, 43683packets that require no acknowledgment. Both the GDB and the stub 43684may send notifications (although the only notifications defined at 43685present are sent by the stub). Notifications carry information 43686without incurring the round-trip latency of an acknowledgment, and so 43687are useful for low-impact communications where occasional packet loss 43688is not a problem. 43689 43690A notification packet has the form @samp{% @var{data} # 43691@var{checksum}}, where @var{data} is the content of the notification, 43692and @var{checksum} is a checksum of @var{data}, computed and formatted 43693as for ordinary @value{GDBN} packets. A notification's @var{data} 43694never contains @samp{$}, @samp{%} or @samp{#} characters. Upon 43695receiving a notification, the recipient sends no @samp{+} or @samp{-} 43696to acknowledge the notification's receipt or to report its corruption. 43697 43698Every notification's @var{data} begins with a name, which contains no 43699colon characters, followed by a colon character. 43700 43701Recipients should silently ignore corrupted notifications and 43702notifications they do not understand. Recipients should restart 43703timeout periods on receipt of a well-formed notification, whether or 43704not they understand it. 43705 43706Senders should only send the notifications described here when this 43707protocol description specifies that they are permitted. In the 43708future, we may extend the protocol to permit existing notifications in 43709new contexts; this rule helps older senders avoid confusing newer 43710recipients. 43711 43712(Older versions of @value{GDBN} ignore bytes received until they see 43713the @samp{$} byte that begins an ordinary packet, so new stubs may 43714transmit notifications without fear of confusing older clients. There 43715are no notifications defined for @value{GDBN} to send at the moment, but we 43716assume that most older stubs would ignore them, as well.) 43717 43718Each notification is comprised of three parts: 43719@table @samp 43720@item @var{name}:@var{event} 43721The notification packet is sent by the side that initiates the 43722exchange (currently, only the stub does that), with @var{event} 43723carrying the specific information about the notification, and 43724@var{name} specifying the name of the notification. 43725@item @var{ack} 43726The acknowledge sent by the other side, usually @value{GDBN}, to 43727acknowledge the exchange and request the event. 43728@end table 43729 43730The purpose of an asynchronous notification mechanism is to report to 43731@value{GDBN} that something interesting happened in the remote stub. 43732 43733The remote stub may send notification @var{name}:@var{event} 43734at any time, but @value{GDBN} acknowledges the notification when 43735appropriate. The notification event is pending before @value{GDBN} 43736acknowledges. Only one notification at a time may be pending; if 43737additional events occur before @value{GDBN} has acknowledged the 43738previous notification, they must be queued by the stub for later 43739synchronous transmission in response to @var{ack} packets from 43740@value{GDBN}. Because the notification mechanism is unreliable, 43741the stub is permitted to resend a notification if it believes 43742@value{GDBN} may not have received it. 43743 43744Specifically, notifications may appear when @value{GDBN} is not 43745otherwise reading input from the stub, or when @value{GDBN} is 43746expecting to read a normal synchronous response or a 43747@samp{+}/@samp{-} acknowledgment to a packet it has sent. 43748Notification packets are distinct from any other communication from 43749the stub so there is no ambiguity. 43750 43751After receiving a notification, @value{GDBN} shall acknowledge it by 43752sending a @var{ack} packet as a regular, synchronous request to the 43753stub. Such acknowledgment is not required to happen immediately, as 43754@value{GDBN} is permitted to send other, unrelated packets to the 43755stub first, which the stub should process normally. 43756 43757Upon receiving a @var{ack} packet, if the stub has other queued 43758events to report to @value{GDBN}, it shall respond by sending a 43759normal @var{event}. @value{GDBN} shall then send another @var{ack} 43760packet to solicit further responses; again, it is permitted to send 43761other, unrelated packets as well which the stub should process 43762normally. 43763 43764If the stub receives a @var{ack} packet and there are no additional 43765@var{event} to report, the stub shall return an @samp{OK} response. 43766At this point, @value{GDBN} has finished processing a notification 43767and the stub has completed sending any queued events. @value{GDBN} 43768won't accept any new notifications until the final @samp{OK} is 43769received . If further notification events occur, the stub shall send 43770a new notification, @value{GDBN} shall accept the notification, and 43771the process shall be repeated. 43772 43773The process of asynchronous notification can be illustrated by the 43774following example: 43775@smallexample 43776<- @code{%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;} 43777@code{...} 43778-> @code{vStopped} 43779<- @code{T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;} 43780-> @code{vStopped} 43781<- @code{T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;} 43782-> @code{vStopped} 43783<- @code{OK} 43784@end smallexample 43785 43786The following notifications are defined: 43787@multitable @columnfractions 0.12 0.12 0.38 0.38 43788 43789@item Notification 43790@tab Ack 43791@tab Event 43792@tab Description 43793 43794@item Stop 43795@tab vStopped 43796@tab @var{reply}. The @var{reply} has the form of a stop reply, as 43797described in @ref{Stop Reply Packets}. Refer to @ref{Remote Non-Stop}, 43798for information on how these notifications are acknowledged by 43799@value{GDBN}. 43800@tab Report an asynchronous stop event in non-stop mode. 43801 43802@end multitable 43803 43804@node Remote Non-Stop 43805@section Remote Protocol Support for Non-Stop Mode 43806 43807@value{GDBN}'s remote protocol supports non-stop debugging of 43808multi-threaded programs, as described in @ref{Non-Stop Mode}. If the stub 43809supports non-stop mode, it should report that to @value{GDBN} by including 43810@samp{QNonStop+} in its @samp{qSupported} response (@pxref{qSupported}). 43811 43812@value{GDBN} typically sends a @samp{QNonStop} packet only when 43813establishing a new connection with the stub. Entering non-stop mode 43814does not alter the state of any currently-running threads, but targets 43815must stop all threads in any already-attached processes when entering 43816all-stop mode. @value{GDBN} uses the @samp{?} packet as necessary to 43817probe the target state after a mode change. 43818 43819In non-stop mode, when an attached process encounters an event that 43820would otherwise be reported with a stop reply, it uses the 43821asynchronous notification mechanism (@pxref{Notification Packets}) to 43822inform @value{GDBN}. In contrast to all-stop mode, where all threads 43823in all processes are stopped when a stop reply is sent, in non-stop 43824mode only the thread reporting the stop event is stopped. That is, 43825when reporting a @samp{S} or @samp{T} response to indicate completion 43826of a step operation, hitting a breakpoint, or a fault, only the 43827affected thread is stopped; any other still-running threads continue 43828to run. When reporting a @samp{W} or @samp{X} response, all running 43829threads belonging to other attached processes continue to run. 43830 43831In non-stop mode, the target shall respond to the @samp{?} packet as 43832follows. First, any incomplete stop reply notification/@samp{vStopped} 43833sequence in progress is abandoned. The target must begin a new 43834sequence reporting stop events for all stopped threads, whether or not 43835it has previously reported those events to @value{GDBN}. The first 43836stop reply is sent as a synchronous reply to the @samp{?} packet, and 43837subsequent stop replies are sent as responses to @samp{vStopped} packets 43838using the mechanism described above. The target must not send 43839asynchronous stop reply notifications until the sequence is complete. 43840If all threads are running when the target receives the @samp{?} packet, 43841or if the target is not attached to any process, it shall respond 43842@samp{OK}. 43843 43844If the stub supports non-stop mode, it should also support the 43845@samp{swbreak} stop reason if software breakpoints are supported, and 43846the @samp{hwbreak} stop reason if hardware breakpoints are supported 43847(@pxref{swbreak stop reason}). This is because given the asynchronous 43848nature of non-stop mode, between the time a thread hits a breakpoint 43849and the time the event is finally processed by @value{GDBN}, the 43850breakpoint may have already been removed from the target. Due to 43851this, @value{GDBN} needs to be able to tell whether a trap stop was 43852caused by a delayed breakpoint event, which should be ignored, as 43853opposed to a random trap signal, which should be reported to the user. 43854Note the @samp{swbreak} feature implies that the target is responsible 43855for adjusting the PC when a software breakpoint triggers, if 43856necessary, such as on the x86 architecture. 43857 43858@node Packet Acknowledgment 43859@section Packet Acknowledgment 43860 43861@cindex acknowledgment, for @value{GDBN} remote 43862@cindex packet acknowledgment, for @value{GDBN} remote 43863By default, when either the host or the target machine receives a packet, 43864the first response expected is an acknowledgment: either @samp{+} (to indicate 43865the package was received correctly) or @samp{-} (to request retransmission). 43866This mechanism allows the @value{GDBN} remote protocol to operate over 43867unreliable transport mechanisms, such as a serial line. 43868 43869In cases where the transport mechanism is itself reliable (such as a pipe or 43870TCP connection), the @samp{+}/@samp{-} acknowledgments are redundant. 43871It may be desirable to disable them in that case to reduce communication 43872overhead, or for other reasons. This can be accomplished by means of the 43873@samp{QStartNoAckMode} packet; @pxref{QStartNoAckMode}. 43874 43875When in no-acknowledgment mode, neither the stub nor @value{GDBN} shall send or 43876expect @samp{+}/@samp{-} protocol acknowledgments. The packet 43877and response format still includes the normal checksum, as described in 43878@ref{Overview}, but the checksum may be ignored by the receiver. 43879 43880If the stub supports @samp{QStartNoAckMode} and prefers to operate in 43881no-acknowledgment mode, it should report that to @value{GDBN} 43882by including @samp{QStartNoAckMode+} in its response to @samp{qSupported}; 43883@pxref{qSupported}. 43884If @value{GDBN} also supports @samp{QStartNoAckMode} and it has not been 43885disabled via the @code{set remote noack-packet off} command 43886(@pxref{Remote Configuration}), 43887@value{GDBN} may then send a @samp{QStartNoAckMode} packet to the stub. 43888Only then may the stub actually turn off packet acknowledgments. 43889@value{GDBN} sends a final @samp{+} acknowledgment of the stub's @samp{OK} 43890response, which can be safely ignored by the stub. 43891 43892Note that @code{set remote noack-packet} command only affects negotiation 43893between @value{GDBN} and the stub when subsequent connections are made; 43894it does not affect the protocol acknowledgment state for any current 43895connection. 43896Since @samp{+}/@samp{-} acknowledgments are enabled by default when a 43897new connection is established, 43898there is also no protocol request to re-enable the acknowledgments 43899for the current connection, once disabled. 43900 43901@node Examples 43902@section Examples 43903 43904Example sequence of a target being re-started. Notice how the restart 43905does not get any direct output: 43906 43907@smallexample 43908-> @code{R00} 43909<- @code{+} 43910@emph{target restarts} 43911-> @code{?} 43912<- @code{+} 43913<- @code{T001:1234123412341234} 43914-> @code{+} 43915@end smallexample 43916 43917Example sequence of a target being stepped by a single instruction: 43918 43919@smallexample 43920-> @code{G1445@dots{}} 43921<- @code{+} 43922-> @code{s} 43923<- @code{+} 43924@emph{time passes} 43925<- @code{T001:1234123412341234} 43926-> @code{+} 43927-> @code{g} 43928<- @code{+} 43929<- @code{1455@dots{}} 43930-> @code{+} 43931@end smallexample 43932 43933@node File-I/O Remote Protocol Extension 43934@section File-I/O Remote Protocol Extension 43935@cindex File-I/O remote protocol extension 43936 43937@menu 43938* File-I/O Overview:: 43939* Protocol Basics:: 43940* The F Request Packet:: 43941* The F Reply Packet:: 43942* The Ctrl-C Message:: 43943* Console I/O:: 43944* List of Supported Calls:: 43945* Protocol-specific Representation of Datatypes:: 43946* Constants:: 43947* File-I/O Examples:: 43948@end menu 43949 43950@node File-I/O Overview 43951@subsection File-I/O Overview 43952@cindex file-i/o overview 43953 43954The @dfn{File I/O remote protocol extension} (short: File-I/O) allows the 43955target to use the host's file system and console I/O to perform various 43956system calls. System calls on the target system are translated into a 43957remote protocol packet to the host system, which then performs the needed 43958actions and returns a response packet to the target system. 43959This simulates file system operations even on targets that lack file systems. 43960 43961The protocol is defined to be independent of both the host and target systems. 43962It uses its own internal representation of datatypes and values. Both 43963@value{GDBN} and the target's @value{GDBN} stub are responsible for 43964translating the system-dependent value representations into the internal 43965protocol representations when data is transmitted. 43966 43967The communication is synchronous. A system call is possible only when 43968@value{GDBN} is waiting for a response from the @samp{C}, @samp{c}, @samp{S} 43969or @samp{s} packets. While @value{GDBN} handles the request for a system call, 43970the target is stopped to allow deterministic access to the target's 43971memory. Therefore File-I/O is not interruptible by target signals. On 43972the other hand, it is possible to interrupt File-I/O by a user interrupt 43973(@samp{Ctrl-C}) within @value{GDBN}. 43974 43975The target's request to perform a host system call does not finish 43976the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action. That means, 43977after finishing the system call, the target returns to continuing the 43978previous activity (continue, step). No additional continue or step 43979request from @value{GDBN} is required. 43980 43981@smallexample 43982(@value{GDBP}) continue 43983 <- target requests 'system call X' 43984 target is stopped, @value{GDBN} executes system call 43985 -> @value{GDBN} returns result 43986 ... target continues, @value{GDBN} returns to wait for the target 43987 <- target hits breakpoint and sends a Txx packet 43988@end smallexample 43989 43990The protocol only supports I/O on the console and to regular files on 43991the host file system. Character or block special devices, pipes, 43992named pipes, sockets or any other communication method on the host 43993system are not supported by this protocol. 43994 43995File I/O is not supported in non-stop mode. 43996 43997@node Protocol Basics 43998@subsection Protocol Basics 43999@cindex protocol basics, file-i/o 44000 44001The File-I/O protocol uses the @code{F} packet as the request as well 44002as reply packet. Since a File-I/O system call can only occur when 44003@value{GDBN} is waiting for a response from the continuing or stepping target, 44004the File-I/O request is a reply that @value{GDBN} has to expect as a result 44005of a previous @samp{C}, @samp{c}, @samp{S} or @samp{s} packet. 44006This @code{F} packet contains all information needed to allow @value{GDBN} 44007to call the appropriate host system call: 44008 44009@itemize @bullet 44010@item 44011A unique identifier for the requested system call. 44012 44013@item 44014All parameters to the system call. Pointers are given as addresses 44015in the target memory address space. Pointers to strings are given as 44016pointer/length pair. Numerical values are given as they are. 44017Numerical control flags are given in a protocol-specific representation. 44018 44019@end itemize 44020 44021At this point, @value{GDBN} has to perform the following actions. 44022 44023@itemize @bullet 44024@item 44025If the parameters include pointer values to data needed as input to a 44026system call, @value{GDBN} requests this data from the target with a 44027standard @code{m} packet request. This additional communication has to be 44028expected by the target implementation and is handled as any other @code{m} 44029packet. 44030 44031@item 44032@value{GDBN} translates all value from protocol representation to host 44033representation as needed. Datatypes are coerced into the host types. 44034 44035@item 44036@value{GDBN} calls the system call. 44037 44038@item 44039It then coerces datatypes back to protocol representation. 44040 44041@item 44042If the system call is expected to return data in buffer space specified 44043by pointer parameters to the call, the data is transmitted to the 44044target using a @code{M} or @code{X} packet. This packet has to be expected 44045by the target implementation and is handled as any other @code{M} or @code{X} 44046packet. 44047 44048@end itemize 44049 44050Eventually @value{GDBN} replies with another @code{F} packet which contains all 44051necessary information for the target to continue. This at least contains 44052 44053@itemize @bullet 44054@item 44055Return value. 44056 44057@item 44058@code{errno}, if has been changed by the system call. 44059 44060@item 44061``Ctrl-C'' flag. 44062 44063@end itemize 44064 44065After having done the needed type and value coercion, the target continues 44066the latest continue or step action. 44067 44068@node The F Request Packet 44069@subsection The @code{F} Request Packet 44070@cindex file-i/o request packet 44071@cindex @code{F} request packet 44072 44073The @code{F} request packet has the following format: 44074 44075@table @samp 44076@item F@var{call-id},@var{parameter@dots{}} 44077 44078@var{call-id} is the identifier to indicate the host system call to be called. 44079This is just the name of the function. 44080 44081@var{parameter@dots{}} are the parameters to the system call. 44082Parameters are hexadecimal integer values, either the actual values in case 44083of scalar datatypes, pointers to target buffer space in case of compound 44084datatypes and unspecified memory areas, or pointer/length pairs in case 44085of string parameters. These are appended to the @var{call-id} as a 44086comma-delimited list. All values are transmitted in ASCII 44087string representation, pointer/length pairs separated by a slash. 44088 44089@end table 44090 44091 44092 44093@node The F Reply Packet 44094@subsection The @code{F} Reply Packet 44095@cindex file-i/o reply packet 44096@cindex @code{F} reply packet 44097 44098The @code{F} reply packet has the following format: 44099 44100@table @samp 44101 44102@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call-specific attachment} 44103 44104@var{retcode} is the return code of the system call as hexadecimal value. 44105 44106@var{errno} is the @code{errno} set by the call, in protocol-specific 44107representation. 44108This parameter can be omitted if the call was successful. 44109 44110@var{Ctrl-C flag} is only sent if the user requested a break. In this 44111case, @var{errno} must be sent as well, even if the call was successful. 44112The @var{Ctrl-C flag} itself consists of the character @samp{C}: 44113 44114@smallexample 44115F0,0,C 44116@end smallexample 44117 44118@noindent 44119or, if the call was interrupted before the host call has been performed: 44120 44121@smallexample 44122F-1,4,C 44123@end smallexample 44124 44125@noindent 44126assuming 4 is the protocol-specific representation of @code{EINTR}. 44127 44128@end table 44129 44130 44131@node The Ctrl-C Message 44132@subsection The @samp{Ctrl-C} Message 44133@cindex ctrl-c message, in file-i/o protocol 44134 44135If the @samp{Ctrl-C} flag is set in the @value{GDBN} 44136reply packet (@pxref{The F Reply Packet}), 44137the target should behave as if it had 44138gotten a break message. The meaning for the target is ``system call 44139interrupted by @code{SIGINT}''. Consequentially, the target should actually stop 44140(as with a break message) and return to @value{GDBN} with a @code{T02} 44141packet. 44142 44143It's important for the target to know in which 44144state the system call was interrupted. There are two possible cases: 44145 44146@itemize @bullet 44147@item 44148The system call hasn't been performed on the host yet. 44149 44150@item 44151The system call on the host has been finished. 44152 44153@end itemize 44154 44155These two states can be distinguished by the target by the value of the 44156returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system 44157call hasn't been performed. This is equivalent to the @code{EINTR} handling 44158on POSIX systems. In any other case, the target may presume that the 44159system call has been finished --- successfully or not --- and should behave 44160as if the break message arrived right after the system call. 44161 44162@value{GDBN} must behave reliably. If the system call has not been called 44163yet, @value{GDBN} may send the @code{F} reply immediately, setting @code{EINTR} as 44164@code{errno} in the packet. If the system call on the host has been finished 44165before the user requests a break, the full action must be finished by 44166@value{GDBN}. This requires sending @code{M} or @code{X} packets as necessary. 44167The @code{F} packet may only be sent when either nothing has happened 44168or the full action has been completed. 44169 44170@node Console I/O 44171@subsection Console I/O 44172@cindex console i/o as part of file-i/o 44173 44174By default and if not explicitly closed by the target system, the file 44175descriptors 0, 1 and 2 are connected to the @value{GDBN} console. Output 44176on the @value{GDBN} console is handled as any other file output operation 44177(@code{write(1, @dots{})} or @code{write(2, @dots{})}). Console input is handled 44178by @value{GDBN} so that after the target read request from file descriptor 441790 all following typing is buffered until either one of the following 44180conditions is met: 44181 44182@itemize @bullet 44183@item 44184The user types @kbd{Ctrl-c}. The behaviour is as explained above, and the 44185@code{read} 44186system call is treated as finished. 44187 44188@item 44189The user presses @key{RET}. This is treated as end of input with a trailing 44190newline. 44191 44192@item 44193The user types @kbd{Ctrl-d}. This is treated as end of input. No trailing 44194character (neither newline nor @samp{Ctrl-D}) is appended to the input. 44195 44196@end itemize 44197 44198If the user has typed more characters than fit in the buffer given to 44199the @code{read} call, the trailing characters are buffered in @value{GDBN} until 44200either another @code{read(0, @dots{})} is requested by the target, or debugging 44201is stopped at the user's request. 44202 44203 44204@node List of Supported Calls 44205@subsection List of Supported Calls 44206@cindex list of supported file-i/o calls 44207 44208@menu 44209* open:: 44210* close:: 44211* read:: 44212* write:: 44213* lseek:: 44214* rename:: 44215* unlink:: 44216* stat/fstat:: 44217* gettimeofday:: 44218* isatty:: 44219* system:: 44220@end menu 44221 44222@node open 44223@unnumberedsubsubsec open 44224@cindex open, file-i/o system call 44225 44226@table @asis 44227@item Synopsis: 44228@smallexample 44229int open(const char *pathname, int flags); 44230int open(const char *pathname, int flags, mode_t mode); 44231@end smallexample 44232 44233@item Request: 44234@samp{Fopen,@var{pathptr}/@var{len},@var{flags},@var{mode}} 44235 44236@noindent 44237@var{flags} is the bitwise @code{OR} of the following values: 44238 44239@table @code 44240@item O_CREAT 44241If the file does not exist it will be created. The host 44242rules apply as far as file ownership and time stamps 44243are concerned. 44244 44245@item O_EXCL 44246When used with @code{O_CREAT}, if the file already exists it is 44247an error and open() fails. 44248 44249@item O_TRUNC 44250If the file already exists and the open mode allows 44251writing (@code{O_RDWR} or @code{O_WRONLY} is given) it will be 44252truncated to zero length. 44253 44254@item O_APPEND 44255The file is opened in append mode. 44256 44257@item O_RDONLY 44258The file is opened for reading only. 44259 44260@item O_WRONLY 44261The file is opened for writing only. 44262 44263@item O_RDWR 44264The file is opened for reading and writing. 44265@end table 44266 44267@noindent 44268Other bits are silently ignored. 44269 44270 44271@noindent 44272@var{mode} is the bitwise @code{OR} of the following values: 44273 44274@table @code 44275@item S_IRUSR 44276User has read permission. 44277 44278@item S_IWUSR 44279User has write permission. 44280 44281@item S_IRGRP 44282Group has read permission. 44283 44284@item S_IWGRP 44285Group has write permission. 44286 44287@item S_IROTH 44288Others have read permission. 44289 44290@item S_IWOTH 44291Others have write permission. 44292@end table 44293 44294@noindent 44295Other bits are silently ignored. 44296 44297 44298@item Return value: 44299@code{open} returns the new file descriptor or -1 if an error 44300occurred. 44301 44302@item Errors: 44303 44304@table @code 44305@item EEXIST 44306@var{pathname} already exists and @code{O_CREAT} and @code{O_EXCL} were used. 44307 44308@item EISDIR 44309@var{pathname} refers to a directory. 44310 44311@item EACCES 44312The requested access is not allowed. 44313 44314@item ENAMETOOLONG 44315@var{pathname} was too long. 44316 44317@item ENOENT 44318A directory component in @var{pathname} does not exist. 44319 44320@item ENODEV 44321@var{pathname} refers to a device, pipe, named pipe or socket. 44322 44323@item EROFS 44324@var{pathname} refers to a file on a read-only filesystem and 44325write access was requested. 44326 44327@item EFAULT 44328@var{pathname} is an invalid pointer value. 44329 44330@item ENOSPC 44331No space on device to create the file. 44332 44333@item EMFILE 44334The process already has the maximum number of files open. 44335 44336@item ENFILE 44337The limit on the total number of files open on the system 44338has been reached. 44339 44340@item EINTR 44341The call was interrupted by the user. 44342@end table 44343 44344@end table 44345 44346@node close 44347@unnumberedsubsubsec close 44348@cindex close, file-i/o system call 44349 44350@table @asis 44351@item Synopsis: 44352@smallexample 44353int close(int fd); 44354@end smallexample 44355 44356@item Request: 44357@samp{Fclose,@var{fd}} 44358 44359@item Return value: 44360@code{close} returns zero on success, or -1 if an error occurred. 44361 44362@item Errors: 44363 44364@table @code 44365@item EBADF 44366@var{fd} isn't a valid open file descriptor. 44367 44368@item EINTR 44369The call was interrupted by the user. 44370@end table 44371 44372@end table 44373 44374@node read 44375@unnumberedsubsubsec read 44376@cindex read, file-i/o system call 44377 44378@table @asis 44379@item Synopsis: 44380@smallexample 44381int read(int fd, void *buf, unsigned int count); 44382@end smallexample 44383 44384@item Request: 44385@samp{Fread,@var{fd},@var{bufptr},@var{count}} 44386 44387@item Return value: 44388On success, the number of bytes read is returned. 44389Zero indicates end of file. If count is zero, read 44390returns zero as well. On error, -1 is returned. 44391 44392@item Errors: 44393 44394@table @code 44395@item EBADF 44396@var{fd} is not a valid file descriptor or is not open for 44397reading. 44398 44399@item EFAULT 44400@var{bufptr} is an invalid pointer value. 44401 44402@item EINTR 44403The call was interrupted by the user. 44404@end table 44405 44406@end table 44407 44408@node write 44409@unnumberedsubsubsec write 44410@cindex write, file-i/o system call 44411 44412@table @asis 44413@item Synopsis: 44414@smallexample 44415int write(int fd, const void *buf, unsigned int count); 44416@end smallexample 44417 44418@item Request: 44419@samp{Fwrite,@var{fd},@var{bufptr},@var{count}} 44420 44421@item Return value: 44422On success, the number of bytes written are returned. 44423Zero indicates nothing was written. On error, -1 44424is returned. 44425 44426@item Errors: 44427 44428@table @code 44429@item EBADF 44430@var{fd} is not a valid file descriptor or is not open for 44431writing. 44432 44433@item EFAULT 44434@var{bufptr} is an invalid pointer value. 44435 44436@item EFBIG 44437An attempt was made to write a file that exceeds the 44438host-specific maximum file size allowed. 44439 44440@item ENOSPC 44441No space on device to write the data. 44442 44443@item EINTR 44444The call was interrupted by the user. 44445@end table 44446 44447@end table 44448 44449@node lseek 44450@unnumberedsubsubsec lseek 44451@cindex lseek, file-i/o system call 44452 44453@table @asis 44454@item Synopsis: 44455@smallexample 44456long lseek (int fd, long offset, int flag); 44457@end smallexample 44458 44459@item Request: 44460@samp{Flseek,@var{fd},@var{offset},@var{flag}} 44461 44462@var{flag} is one of: 44463 44464@table @code 44465@item SEEK_SET 44466The offset is set to @var{offset} bytes. 44467 44468@item SEEK_CUR 44469The offset is set to its current location plus @var{offset} 44470bytes. 44471 44472@item SEEK_END 44473The offset is set to the size of the file plus @var{offset} 44474bytes. 44475@end table 44476 44477@item Return value: 44478On success, the resulting unsigned offset in bytes from 44479the beginning of the file is returned. Otherwise, a 44480value of -1 is returned. 44481 44482@item Errors: 44483 44484@table @code 44485@item EBADF 44486@var{fd} is not a valid open file descriptor. 44487 44488@item ESPIPE 44489@var{fd} is associated with the @value{GDBN} console. 44490 44491@item EINVAL 44492@var{flag} is not a proper value. 44493 44494@item EINTR 44495The call was interrupted by the user. 44496@end table 44497 44498@end table 44499 44500@node rename 44501@unnumberedsubsubsec rename 44502@cindex rename, file-i/o system call 44503 44504@table @asis 44505@item Synopsis: 44506@smallexample 44507int rename(const char *oldpath, const char *newpath); 44508@end smallexample 44509 44510@item Request: 44511@samp{Frename,@var{oldpathptr}/@var{len},@var{newpathptr}/@var{len}} 44512 44513@item Return value: 44514On success, zero is returned. On error, -1 is returned. 44515 44516@item Errors: 44517 44518@table @code 44519@item EISDIR 44520@var{newpath} is an existing directory, but @var{oldpath} is not a 44521directory. 44522 44523@item EEXIST 44524@var{newpath} is a non-empty directory. 44525 44526@item EBUSY 44527@var{oldpath} or @var{newpath} is a directory that is in use by some 44528process. 44529 44530@item EINVAL 44531An attempt was made to make a directory a subdirectory 44532of itself. 44533 44534@item ENOTDIR 44535A component used as a directory in @var{oldpath} or new 44536path is not a directory. Or @var{oldpath} is a directory 44537and @var{newpath} exists but is not a directory. 44538 44539@item EFAULT 44540@var{oldpathptr} or @var{newpathptr} are invalid pointer values. 44541 44542@item EACCES 44543No access to the file or the path of the file. 44544 44545@item ENAMETOOLONG 44546 44547@var{oldpath} or @var{newpath} was too long. 44548 44549@item ENOENT 44550A directory component in @var{oldpath} or @var{newpath} does not exist. 44551 44552@item EROFS 44553The file is on a read-only filesystem. 44554 44555@item ENOSPC 44556The device containing the file has no room for the new 44557directory entry. 44558 44559@item EINTR 44560The call was interrupted by the user. 44561@end table 44562 44563@end table 44564 44565@node unlink 44566@unnumberedsubsubsec unlink 44567@cindex unlink, file-i/o system call 44568 44569@table @asis 44570@item Synopsis: 44571@smallexample 44572int unlink(const char *pathname); 44573@end smallexample 44574 44575@item Request: 44576@samp{Funlink,@var{pathnameptr}/@var{len}} 44577 44578@item Return value: 44579On success, zero is returned. On error, -1 is returned. 44580 44581@item Errors: 44582 44583@table @code 44584@item EACCES 44585No access to the file or the path of the file. 44586 44587@item EPERM 44588The system does not allow unlinking of directories. 44589 44590@item EBUSY 44591The file @var{pathname} cannot be unlinked because it's 44592being used by another process. 44593 44594@item EFAULT 44595@var{pathnameptr} is an invalid pointer value. 44596 44597@item ENAMETOOLONG 44598@var{pathname} was too long. 44599 44600@item ENOENT 44601A directory component in @var{pathname} does not exist. 44602 44603@item ENOTDIR 44604A component of the path is not a directory. 44605 44606@item EROFS 44607The file is on a read-only filesystem. 44608 44609@item EINTR 44610The call was interrupted by the user. 44611@end table 44612 44613@end table 44614 44615@node stat/fstat 44616@unnumberedsubsubsec stat/fstat 44617@cindex fstat, file-i/o system call 44618@cindex stat, file-i/o system call 44619 44620@table @asis 44621@item Synopsis: 44622@smallexample 44623int stat(const char *pathname, struct stat *buf); 44624int fstat(int fd, struct stat *buf); 44625@end smallexample 44626 44627@item Request: 44628@samp{Fstat,@var{pathnameptr}/@var{len},@var{bufptr}}@* 44629@samp{Ffstat,@var{fd},@var{bufptr}} 44630 44631@item Return value: 44632On success, zero is returned. On error, -1 is returned. 44633 44634@item Errors: 44635 44636@table @code 44637@item EBADF 44638@var{fd} is not a valid open file. 44639 44640@item ENOENT 44641A directory component in @var{pathname} does not exist or the 44642path is an empty string. 44643 44644@item ENOTDIR 44645A component of the path is not a directory. 44646 44647@item EFAULT 44648@var{pathnameptr} is an invalid pointer value. 44649 44650@item EACCES 44651No access to the file or the path of the file. 44652 44653@item ENAMETOOLONG 44654@var{pathname} was too long. 44655 44656@item EINTR 44657The call was interrupted by the user. 44658@end table 44659 44660@end table 44661 44662@node gettimeofday 44663@unnumberedsubsubsec gettimeofday 44664@cindex gettimeofday, file-i/o system call 44665 44666@table @asis 44667@item Synopsis: 44668@smallexample 44669int gettimeofday(struct timeval *tv, void *tz); 44670@end smallexample 44671 44672@item Request: 44673@samp{Fgettimeofday,@var{tvptr},@var{tzptr}} 44674 44675@item Return value: 44676On success, 0 is returned, -1 otherwise. 44677 44678@item Errors: 44679 44680@table @code 44681@item EINVAL 44682@var{tz} is a non-NULL pointer. 44683 44684@item EFAULT 44685@var{tvptr} and/or @var{tzptr} is an invalid pointer value. 44686@end table 44687 44688@end table 44689 44690@node isatty 44691@unnumberedsubsubsec isatty 44692@cindex isatty, file-i/o system call 44693 44694@table @asis 44695@item Synopsis: 44696@smallexample 44697int isatty(int fd); 44698@end smallexample 44699 44700@item Request: 44701@samp{Fisatty,@var{fd}} 44702 44703@item Return value: 44704Returns 1 if @var{fd} refers to the @value{GDBN} console, 0 otherwise. 44705 44706@item Errors: 44707 44708@table @code 44709@item EINTR 44710The call was interrupted by the user. 44711@end table 44712 44713@end table 44714 44715Note that the @code{isatty} call is treated as a special case: it returns 447161 to the target if the file descriptor is attached 44717to the @value{GDBN} console, 0 otherwise. Implementing through system calls 44718would require implementing @code{ioctl} and would be more complex than 44719needed. 44720 44721 44722@node system 44723@unnumberedsubsubsec system 44724@cindex system, file-i/o system call 44725 44726@table @asis 44727@item Synopsis: 44728@smallexample 44729int system(const char *command); 44730@end smallexample 44731 44732@item Request: 44733@samp{Fsystem,@var{commandptr}/@var{len}} 44734 44735@item Return value: 44736If @var{len} is zero, the return value indicates whether a shell is 44737available. A zero return value indicates a shell is not available. 44738For non-zero @var{len}, the value returned is -1 on error and the 44739return status of the command otherwise. Only the exit status of the 44740command is returned, which is extracted from the host's @code{system} 44741return value by calling @code{WEXITSTATUS(retval)}. In case 44742@file{/bin/sh} could not be executed, 127 is returned. 44743 44744@item Errors: 44745 44746@table @code 44747@item EINTR 44748The call was interrupted by the user. 44749@end table 44750 44751@end table 44752 44753@value{GDBN} takes over the full task of calling the necessary host calls 44754to perform the @code{system} call. The return value of @code{system} on 44755the host is simplified before it's returned 44756to the target. Any termination signal information from the child process 44757is discarded, and the return value consists 44758entirely of the exit status of the called command. 44759 44760Due to security concerns, the @code{system} call is by default refused 44761by @value{GDBN}. The user has to allow this call explicitly with the 44762@code{set remote system-call-allowed 1} command. 44763 44764@table @code 44765@item set remote system-call-allowed 44766@kindex set remote system-call-allowed 44767Control whether to allow the @code{system} calls in the File I/O 44768protocol for the remote target. The default is zero (disabled). 44769 44770@item show remote system-call-allowed 44771@kindex show remote system-call-allowed 44772Show whether the @code{system} calls are allowed in the File I/O 44773protocol. 44774@end table 44775 44776@node Protocol-specific Representation of Datatypes 44777@subsection Protocol-specific Representation of Datatypes 44778@cindex protocol-specific representation of datatypes, in file-i/o protocol 44779 44780@menu 44781* Integral Datatypes:: 44782* Pointer Values:: 44783* Memory Transfer:: 44784* struct stat:: 44785* struct timeval:: 44786@end menu 44787 44788@node Integral Datatypes 44789@unnumberedsubsubsec Integral Datatypes 44790@cindex integral datatypes, in file-i/o protocol 44791 44792The integral datatypes used in the system calls are @code{int}, 44793@code{unsigned int}, @code{long}, @code{unsigned long}, 44794@code{mode_t}, and @code{time_t}. 44795 44796@code{int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are 44797implemented as 32 bit values in this protocol. 44798 44799@code{long} and @code{unsigned long} are implemented as 64 bit types. 44800 44801@xref{Limits}, for corresponding MIN and MAX values (similar to those 44802in @file{limits.h}) to allow range checking on host and target. 44803 44804@code{time_t} datatypes are defined as seconds since the Epoch. 44805 44806All integral datatypes transferred as part of a memory read or write of a 44807structured datatype e.g.@: a @code{struct stat} have to be given in big endian 44808byte order. 44809 44810@node Pointer Values 44811@unnumberedsubsubsec Pointer Values 44812@cindex pointer values, in file-i/o protocol 44813 44814Pointers to target data are transmitted as they are. An exception 44815is made for pointers to buffers for which the length isn't 44816transmitted as part of the function call, namely strings. Strings 44817are transmitted as a pointer/length pair, both as hex values, e.g.@: 44818 44819@smallexample 44820@code{1aaf/12} 44821@end smallexample 44822 44823@noindent 44824which is a pointer to data of length 18 bytes at position 0x1aaf. 44825The length is defined as the full string length in bytes, including 44826the trailing null byte. For example, the string @code{"hello world"} 44827at address 0x123456 is transmitted as 44828 44829@smallexample 44830@code{123456/d} 44831@end smallexample 44832 44833@node Memory Transfer 44834@unnumberedsubsubsec Memory Transfer 44835@cindex memory transfer, in file-i/o protocol 44836 44837Structured data which is transferred using a memory read or write (for 44838example, a @code{struct stat}) is expected to be in a protocol-specific format 44839with all scalar multibyte datatypes being big endian. Translation to 44840this representation needs to be done both by the target before the @code{F} 44841packet is sent, and by @value{GDBN} before 44842it transfers memory to the target. Transferred pointers to structured 44843data should point to the already-coerced data at any time. 44844 44845 44846@node struct stat 44847@unnumberedsubsubsec struct stat 44848@cindex struct stat, in file-i/o protocol 44849 44850The buffer of type @code{struct stat} used by the target and @value{GDBN} 44851is defined as follows: 44852 44853@smallexample 44854struct stat @{ 44855 unsigned int st_dev; /* device */ 44856 unsigned int st_ino; /* inode */ 44857 mode_t st_mode; /* protection */ 44858 unsigned int st_nlink; /* number of hard links */ 44859 unsigned int st_uid; /* user ID of owner */ 44860 unsigned int st_gid; /* group ID of owner */ 44861 unsigned int st_rdev; /* device type (if inode device) */ 44862 unsigned long st_size; /* total size, in bytes */ 44863 unsigned long st_blksize; /* blocksize for filesystem I/O */ 44864 unsigned long st_blocks; /* number of blocks allocated */ 44865 time_t st_atime; /* time of last access */ 44866 time_t st_mtime; /* time of last modification */ 44867 time_t st_ctime; /* time of last change */ 44868@}; 44869@end smallexample 44870 44871The integral datatypes conform to the definitions given in the 44872appropriate section (see @ref{Integral Datatypes}, for details) so this 44873structure is of size 64 bytes. 44874 44875The values of several fields have a restricted meaning and/or 44876range of values. 44877 44878@table @code 44879 44880@item st_dev 44881A value of 0 represents a file, 1 the console. 44882 44883@item st_ino 44884No valid meaning for the target. Transmitted unchanged. 44885 44886@item st_mode 44887Valid mode bits are described in @ref{Constants}. Any other 44888bits have currently no meaning for the target. 44889 44890@item st_uid 44891@itemx st_gid 44892@itemx st_rdev 44893No valid meaning for the target. Transmitted unchanged. 44894 44895@item st_atime 44896@itemx st_mtime 44897@itemx st_ctime 44898These values have a host and file system dependent 44899accuracy. Especially on Windows hosts, the file system may not 44900support exact timing values. 44901@end table 44902 44903The target gets a @code{struct stat} of the above representation and is 44904responsible for coercing it to the target representation before 44905continuing. 44906 44907Note that due to size differences between the host, target, and protocol 44908representations of @code{struct stat} members, these members could eventually 44909get truncated on the target. 44910 44911@node struct timeval 44912@unnumberedsubsubsec struct timeval 44913@cindex struct timeval, in file-i/o protocol 44914 44915The buffer of type @code{struct timeval} used by the File-I/O protocol 44916is defined as follows: 44917 44918@smallexample 44919struct timeval @{ 44920 time_t tv_sec; /* second */ 44921 long tv_usec; /* microsecond */ 44922@}; 44923@end smallexample 44924 44925The integral datatypes conform to the definitions given in the 44926appropriate section (see @ref{Integral Datatypes}, for details) so this 44927structure is of size 8 bytes. 44928 44929@node Constants 44930@subsection Constants 44931@cindex constants, in file-i/o protocol 44932 44933The following values are used for the constants inside of the 44934protocol. @value{GDBN} and target are responsible for translating these 44935values before and after the call as needed. 44936 44937@menu 44938* Open Flags:: 44939* mode_t Values:: 44940* Errno Values:: 44941* Lseek Flags:: 44942* Limits:: 44943@end menu 44944 44945@node Open Flags 44946@unnumberedsubsubsec Open Flags 44947@cindex open flags, in file-i/o protocol 44948 44949All values are given in hexadecimal representation. 44950 44951@smallexample 44952 O_RDONLY 0x0 44953 O_WRONLY 0x1 44954 O_RDWR 0x2 44955 O_APPEND 0x8 44956 O_CREAT 0x200 44957 O_TRUNC 0x400 44958 O_EXCL 0x800 44959@end smallexample 44960 44961@node mode_t Values 44962@unnumberedsubsubsec mode_t Values 44963@cindex mode_t values, in file-i/o protocol 44964 44965All values are given in octal representation. 44966 44967@smallexample 44968 S_IFREG 0100000 44969 S_IFDIR 040000 44970 S_IRUSR 0400 44971 S_IWUSR 0200 44972 S_IXUSR 0100 44973 S_IRGRP 040 44974 S_IWGRP 020 44975 S_IXGRP 010 44976 S_IROTH 04 44977 S_IWOTH 02 44978 S_IXOTH 01 44979@end smallexample 44980 44981@node Errno Values 44982@unnumberedsubsubsec Errno Values 44983@cindex errno values, in file-i/o protocol 44984 44985All values are given in decimal representation. 44986 44987@smallexample 44988 EPERM 1 44989 ENOENT 2 44990 EINTR 4 44991 EBADF 9 44992 EACCES 13 44993 EFAULT 14 44994 EBUSY 16 44995 EEXIST 17 44996 ENODEV 19 44997 ENOTDIR 20 44998 EISDIR 21 44999 EINVAL 22 45000 ENFILE 23 45001 EMFILE 24 45002 EFBIG 27 45003 ENOSPC 28 45004 ESPIPE 29 45005 EROFS 30 45006 ENAMETOOLONG 91 45007 EUNKNOWN 9999 45008@end smallexample 45009 45010 @code{EUNKNOWN} is used as a fallback error value if a host system returns 45011 any error value not in the list of supported error numbers. 45012 45013@node Lseek Flags 45014@unnumberedsubsubsec Lseek Flags 45015@cindex lseek flags, in file-i/o protocol 45016 45017@smallexample 45018 SEEK_SET 0 45019 SEEK_CUR 1 45020 SEEK_END 2 45021@end smallexample 45022 45023@node Limits 45024@unnumberedsubsubsec Limits 45025@cindex limits, in file-i/o protocol 45026 45027All values are given in decimal representation. 45028 45029@smallexample 45030 INT_MIN -2147483648 45031 INT_MAX 2147483647 45032 UINT_MAX 4294967295 45033 LONG_MIN -9223372036854775808 45034 LONG_MAX 9223372036854775807 45035 ULONG_MAX 18446744073709551615 45036@end smallexample 45037 45038@node File-I/O Examples 45039@subsection File-I/O Examples 45040@cindex file-i/o examples 45041 45042Example sequence of a write call, file descriptor 3, buffer is at target 45043address 0x1234, 6 bytes should be written: 45044 45045@smallexample 45046<- @code{Fwrite,3,1234,6} 45047@emph{request memory read from target} 45048-> @code{m1234,6} 45049<- XXXXXX 45050@emph{return "6 bytes written"} 45051-> @code{F6} 45052@end smallexample 45053 45054Example sequence of a read call, file descriptor 3, buffer is at target 45055address 0x1234, 6 bytes should be read: 45056 45057@smallexample 45058<- @code{Fread,3,1234,6} 45059@emph{request memory write to target} 45060-> @code{X1234,6:XXXXXX} 45061@emph{return "6 bytes read"} 45062-> @code{F6} 45063@end smallexample 45064 45065Example sequence of a read call, call fails on the host due to invalid 45066file descriptor (@code{EBADF}): 45067 45068@smallexample 45069<- @code{Fread,3,1234,6} 45070-> @code{F-1,9} 45071@end smallexample 45072 45073Example sequence of a read call, user presses @kbd{Ctrl-c} before syscall on 45074host is called: 45075 45076@smallexample 45077<- @code{Fread,3,1234,6} 45078-> @code{F-1,4,C} 45079<- @code{T02} 45080@end smallexample 45081 45082Example sequence of a read call, user presses @kbd{Ctrl-c} after syscall on 45083host is called: 45084 45085@smallexample 45086<- @code{Fread,3,1234,6} 45087-> @code{X1234,6:XXXXXX} 45088<- @code{T02} 45089@end smallexample 45090 45091@node Library List Format 45092@section Library List Format 45093@cindex library list format, remote protocol 45094 45095On some platforms, a dynamic loader (e.g.@: @file{ld.so}) runs in the 45096same process as your application to manage libraries. In this case, 45097@value{GDBN} can use the loader's symbol table and normal memory 45098operations to maintain a list of shared libraries. On other 45099platforms, the operating system manages loaded libraries. 45100@value{GDBN} can not retrieve the list of currently loaded libraries 45101through memory operations, so it uses the @samp{qXfer:libraries:read} 45102packet (@pxref{qXfer library list read}) instead. The remote stub 45103queries the target's operating system and reports which libraries 45104are loaded. 45105 45106The @samp{qXfer:libraries:read} packet returns an XML document which 45107lists loaded libraries and their offsets. Each library has an 45108associated name and one or more segment or section base addresses, 45109which report where the library was loaded in memory. 45110 45111For the common case of libraries that are fully linked binaries, the 45112library should have a list of segments. If the target supports 45113dynamic linking of a relocatable object file, its library XML element 45114should instead include a list of allocated sections. The segment or 45115section bases are start addresses, not relocation offsets; they do not 45116depend on the library's link-time base addresses. 45117 45118@value{GDBN} must be linked with the Expat library to support XML 45119library lists. @xref{Expat}. 45120 45121A simple memory map, with one loaded library relocated by a single 45122offset, looks like this: 45123 45124@smallexample 45125<library-list> 45126 <library name="/lib/libc.so.6"> 45127 <segment address="0x10000000"/> 45128 </library> 45129</library-list> 45130@end smallexample 45131 45132Another simple memory map, with one loaded library with three 45133allocated sections (.text, .data, .bss), looks like this: 45134 45135@smallexample 45136<library-list> 45137 <library name="sharedlib.o"> 45138 <section address="0x10000000"/> 45139 <section address="0x20000000"/> 45140 <section address="0x30000000"/> 45141 </library> 45142</library-list> 45143@end smallexample 45144 45145The format of a library list is described by this DTD: 45146 45147@smallexample 45148<!-- library-list: Root element with versioning --> 45149<!ELEMENT library-list (library)*> 45150<!ATTLIST library-list version CDATA #FIXED "1.0"> 45151<!ELEMENT library (segment*, section*)> 45152<!ATTLIST library name CDATA #REQUIRED> 45153<!ELEMENT segment EMPTY> 45154<!ATTLIST segment address CDATA #REQUIRED> 45155<!ELEMENT section EMPTY> 45156<!ATTLIST section address CDATA #REQUIRED> 45157@end smallexample 45158 45159In addition, segments and section descriptors cannot be mixed within a 45160single library element, and you must supply at least one segment or 45161section for each library. 45162 45163@node Library List Format for SVR4 Targets 45164@section Library List Format for SVR4 Targets 45165@cindex library list format, remote protocol 45166 45167On SVR4 platforms @value{GDBN} can use the symbol table of a dynamic loader 45168(e.g.@: @file{ld.so}) and normal memory operations to maintain a list of 45169shared libraries. Still a special library list provided by this packet is 45170more efficient for the @value{GDBN} remote protocol. 45171 45172The @samp{qXfer:libraries-svr4:read} packet returns an XML document which lists 45173loaded libraries and their SVR4 linker parameters. For each library on SVR4 45174target, the following parameters are reported: 45175 45176@itemize @minus 45177@item 45178@code{name}, the absolute file name from the @code{l_name} field of 45179@code{struct link_map}. 45180@item 45181@code{lm} with address of @code{struct link_map} used for TLS 45182(Thread Local Storage) access. 45183@item 45184@code{l_addr}, the displacement as read from the field @code{l_addr} of 45185@code{struct link_map}. For prelinked libraries this is not an absolute 45186memory address. It is a displacement of absolute memory address against 45187address the file was prelinked to during the library load. 45188@item 45189@code{l_ld}, which is memory address of the @code{PT_DYNAMIC} segment 45190@end itemize 45191 45192Additionally the single @code{main-lm} attribute specifies address of 45193@code{struct link_map} used for the main executable. This parameter is used 45194for TLS access and its presence is optional. 45195 45196@value{GDBN} must be linked with the Expat library to support XML 45197SVR4 library lists. @xref{Expat}. 45198 45199A simple memory map, with two loaded libraries (which do not use prelink), 45200looks like this: 45201 45202@smallexample 45203<library-list-svr4 version="1.0" main-lm="0xe4f8f8"> 45204 <library name="/lib/ld-linux.so.2" lm="0xe4f51c" l_addr="0xe2d000" 45205 l_ld="0xe4eefc"/> 45206 <library name="/lib/libc.so.6" lm="0xe4fbe8" l_addr="0x154000" 45207 l_ld="0x152350"/> 45208</library-list-svr> 45209@end smallexample 45210 45211The format of an SVR4 library list is described by this DTD: 45212 45213@smallexample 45214<!-- library-list-svr4: Root element with versioning --> 45215<!ELEMENT library-list-svr4 (library)*> 45216<!ATTLIST library-list-svr4 version CDATA #FIXED "1.0"> 45217<!ATTLIST library-list-svr4 main-lm CDATA #IMPLIED> 45218<!ELEMENT library EMPTY> 45219<!ATTLIST library name CDATA #REQUIRED> 45220<!ATTLIST library lm CDATA #REQUIRED> 45221<!ATTLIST library l_addr CDATA #REQUIRED> 45222<!ATTLIST library l_ld CDATA #REQUIRED> 45223@end smallexample 45224 45225@node Memory Map Format 45226@section Memory Map Format 45227@cindex memory map format 45228 45229To be able to write into flash memory, @value{GDBN} needs to obtain a 45230memory map from the target. This section describes the format of the 45231memory map. 45232 45233The memory map is obtained using the @samp{qXfer:memory-map:read} 45234(@pxref{qXfer memory map read}) packet and is an XML document that 45235lists memory regions. 45236 45237@value{GDBN} must be linked with the Expat library to support XML 45238memory maps. @xref{Expat}. 45239 45240The top-level structure of the document is shown below: 45241 45242@smallexample 45243<?xml version="1.0"?> 45244<!DOCTYPE memory-map 45245 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN" 45246 "http://sourceware.org/gdb/gdb-memory-map.dtd"> 45247<memory-map> 45248 region... 45249</memory-map> 45250@end smallexample 45251 45252Each region can be either: 45253 45254@itemize 45255 45256@item 45257A region of RAM starting at @var{addr} and extending for @var{length} 45258bytes from there: 45259 45260@smallexample 45261<memory type="ram" start="@var{addr}" length="@var{length}"/> 45262@end smallexample 45263 45264 45265@item 45266A region of read-only memory: 45267 45268@smallexample 45269<memory type="rom" start="@var{addr}" length="@var{length}"/> 45270@end smallexample 45271 45272 45273@item 45274A region of flash memory, with erasure blocks @var{blocksize} 45275bytes in length: 45276 45277@smallexample 45278<memory type="flash" start="@var{addr}" length="@var{length}"> 45279 <property name="blocksize">@var{blocksize}</property> 45280</memory> 45281@end smallexample 45282 45283@end itemize 45284 45285Regions must not overlap. @value{GDBN} assumes that areas of memory not covered 45286by the memory map are RAM, and uses the ordinary @samp{M} and @samp{X} 45287packets to write to addresses in such ranges. 45288 45289The formal DTD for memory map format is given below: 45290 45291@smallexample 45292<!-- ................................................... --> 45293<!-- Memory Map XML DTD ................................ --> 45294<!-- File: memory-map.dtd .............................. --> 45295<!-- .................................... .............. --> 45296<!-- memory-map.dtd --> 45297<!-- memory-map: Root element with versioning --> 45298<!ELEMENT memory-map (memory)*> 45299<!ATTLIST memory-map version CDATA #FIXED "1.0.0"> 45300<!ELEMENT memory (property)*> 45301<!-- memory: Specifies a memory region, 45302 and its type, or device. --> 45303<!ATTLIST memory type (ram|rom|flash) #REQUIRED 45304 start CDATA #REQUIRED 45305 length CDATA #REQUIRED> 45306<!-- property: Generic attribute tag --> 45307<!ELEMENT property (#PCDATA | property)*> 45308<!ATTLIST property name (blocksize) #REQUIRED> 45309@end smallexample 45310 45311@node Thread List Format 45312@section Thread List Format 45313@cindex thread list format 45314 45315To efficiently update the list of threads and their attributes, 45316@value{GDBN} issues the @samp{qXfer:threads:read} packet 45317(@pxref{qXfer threads read}) and obtains the XML document with 45318the following structure: 45319 45320@smallexample 45321<?xml version="1.0"?> 45322<threads> 45323 <thread id="id" core="0" name="name"> 45324 ... description ... 45325 </thread> 45326</threads> 45327@end smallexample 45328 45329Each @samp{thread} element must have the @samp{id} attribute that 45330identifies the thread (@pxref{thread-id syntax}). The 45331@samp{core} attribute, if present, specifies which processor core 45332the thread was last executing on. The @samp{name} attribute, if 45333present, specifies the human-readable name of the thread. The content 45334of the of @samp{thread} element is interpreted as human-readable 45335auxiliary information. The @samp{handle} attribute, if present, 45336is a hex encoded representation of the thread handle. 45337 45338 45339@node Traceframe Info Format 45340@section Traceframe Info Format 45341@cindex traceframe info format 45342 45343To be able to know which objects in the inferior can be examined when 45344inspecting a tracepoint hit, @value{GDBN} needs to obtain the list of 45345memory ranges, registers and trace state variables that have been 45346collected in a traceframe. 45347 45348This list is obtained using the @samp{qXfer:traceframe-info:read} 45349(@pxref{qXfer traceframe info read}) packet and is an XML document. 45350 45351@value{GDBN} must be linked with the Expat library to support XML 45352traceframe info discovery. @xref{Expat}. 45353 45354The top-level structure of the document is shown below: 45355 45356@smallexample 45357<?xml version="1.0"?> 45358<!DOCTYPE traceframe-info 45359 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN" 45360 "http://sourceware.org/gdb/gdb-traceframe-info.dtd"> 45361<traceframe-info> 45362 block... 45363</traceframe-info> 45364@end smallexample 45365 45366Each traceframe block can be either: 45367 45368@itemize 45369 45370@item 45371A region of collected memory starting at @var{addr} and extending for 45372@var{length} bytes from there: 45373 45374@smallexample 45375<memory start="@var{addr}" length="@var{length}"/> 45376@end smallexample 45377 45378@item 45379A block indicating trace state variable numbered @var{number} has been 45380collected: 45381 45382@smallexample 45383<tvar id="@var{number}"/> 45384@end smallexample 45385 45386@end itemize 45387 45388The formal DTD for the traceframe info format is given below: 45389 45390@smallexample 45391<!ELEMENT traceframe-info (memory | tvar)* > 45392<!ATTLIST traceframe-info version CDATA #FIXED "1.0"> 45393 45394<!ELEMENT memory EMPTY> 45395<!ATTLIST memory start CDATA #REQUIRED 45396 length CDATA #REQUIRED> 45397<!ELEMENT tvar> 45398<!ATTLIST tvar id CDATA #REQUIRED> 45399@end smallexample 45400 45401@node Branch Trace Format 45402@section Branch Trace Format 45403@cindex branch trace format 45404 45405In order to display the branch trace of an inferior thread, 45406@value{GDBN} needs to obtain the list of branches. This list is 45407represented as list of sequential code blocks that are connected via 45408branches. The code in each block has been executed sequentially. 45409 45410This list is obtained using the @samp{qXfer:btrace:read} 45411(@pxref{qXfer btrace read}) packet and is an XML document. 45412 45413@value{GDBN} must be linked with the Expat library to support XML 45414traceframe info discovery. @xref{Expat}. 45415 45416The top-level structure of the document is shown below: 45417 45418@smallexample 45419<?xml version="1.0"?> 45420<!DOCTYPE btrace 45421 PUBLIC "+//IDN gnu.org//DTD GDB Branch Trace V1.0//EN" 45422 "http://sourceware.org/gdb/gdb-btrace.dtd"> 45423<btrace> 45424 block... 45425</btrace> 45426@end smallexample 45427 45428@itemize 45429 45430@item 45431A block of sequentially executed instructions starting at @var{begin} 45432and ending at @var{end}: 45433 45434@smallexample 45435<block begin="@var{begin}" end="@var{end}"/> 45436@end smallexample 45437 45438@end itemize 45439 45440The formal DTD for the branch trace format is given below: 45441 45442@smallexample 45443<!ELEMENT btrace (block* | pt) > 45444<!ATTLIST btrace version CDATA #FIXED "1.0"> 45445 45446<!ELEMENT block EMPTY> 45447<!ATTLIST block begin CDATA #REQUIRED 45448 end CDATA #REQUIRED> 45449 45450<!ELEMENT pt (pt-config?, raw?)> 45451 45452<!ELEMENT pt-config (cpu?)> 45453 45454<!ELEMENT cpu EMPTY> 45455<!ATTLIST cpu vendor CDATA #REQUIRED 45456 family CDATA #REQUIRED 45457 model CDATA #REQUIRED 45458 stepping CDATA #REQUIRED> 45459 45460<!ELEMENT raw (#PCDATA)> 45461@end smallexample 45462 45463@node Branch Trace Configuration Format 45464@section Branch Trace Configuration Format 45465@cindex branch trace configuration format 45466 45467For each inferior thread, @value{GDBN} can obtain the branch trace 45468configuration using the @samp{qXfer:btrace-conf:read} 45469(@pxref{qXfer btrace-conf read}) packet. 45470 45471The configuration describes the branch trace format and configuration 45472settings for that format. The following information is described: 45473 45474@table @code 45475@item bts 45476This thread uses the @dfn{Branch Trace Store} (@acronym{BTS}) format. 45477@table @code 45478@item size 45479The size of the @acronym{BTS} ring buffer in bytes. 45480@end table 45481@item pt 45482This thread uses the @dfn{Intel Processor Trace} (@acronym{Intel 45483PT}) format. 45484@table @code 45485@item size 45486The size of the @acronym{Intel PT} ring buffer in bytes. 45487@end table 45488@end table 45489 45490@value{GDBN} must be linked with the Expat library to support XML 45491branch trace configuration discovery. @xref{Expat}. 45492 45493The formal DTD for the branch trace configuration format is given below: 45494 45495@smallexample 45496<!ELEMENT btrace-conf (bts?, pt?)> 45497<!ATTLIST btrace-conf version CDATA #FIXED "1.0"> 45498 45499<!ELEMENT bts EMPTY> 45500<!ATTLIST bts size CDATA #IMPLIED> 45501 45502<!ELEMENT pt EMPTY> 45503<!ATTLIST pt size CDATA #IMPLIED> 45504@end smallexample 45505 45506@include agentexpr.texi 45507 45508@node Target Descriptions 45509@appendix Target Descriptions 45510@cindex target descriptions 45511 45512One of the challenges of using @value{GDBN} to debug embedded systems 45513is that there are so many minor variants of each processor 45514architecture in use. It is common practice for vendors to start with 45515a standard processor core --- ARM, PowerPC, or @acronym{MIPS}, for example --- 45516and then make changes to adapt it to a particular market niche. Some 45517architectures have hundreds of variants, available from dozens of 45518vendors. This leads to a number of problems: 45519 45520@itemize @bullet 45521@item 45522With so many different customized processors, it is difficult for 45523the @value{GDBN} maintainers to keep up with the changes. 45524@item 45525Since individual variants may have short lifetimes or limited 45526audiences, it may not be worthwhile to carry information about every 45527variant in the @value{GDBN} source tree. 45528@item 45529When @value{GDBN} does support the architecture of the embedded system 45530at hand, the task of finding the correct architecture name to give the 45531@command{set architecture} command can be error-prone. 45532@end itemize 45533 45534To address these problems, the @value{GDBN} remote protocol allows a 45535target system to not only identify itself to @value{GDBN}, but to 45536actually describe its own features. This lets @value{GDBN} support 45537processor variants it has never seen before --- to the extent that the 45538descriptions are accurate, and that @value{GDBN} understands them. 45539 45540@value{GDBN} must be linked with the Expat library to support XML 45541target descriptions. @xref{Expat}. 45542 45543@menu 45544* Retrieving Descriptions:: How descriptions are fetched from a target. 45545* Target Description Format:: The contents of a target description. 45546* Predefined Target Types:: Standard types available for target 45547 descriptions. 45548* Enum Target Types:: How to define enum target types. 45549* Standard Target Features:: Features @value{GDBN} knows about. 45550@end menu 45551 45552@node Retrieving Descriptions 45553@section Retrieving Descriptions 45554 45555Target descriptions can be read from the target automatically, or 45556specified by the user manually. The default behavior is to read the 45557description from the target. @value{GDBN} retrieves it via the remote 45558protocol using @samp{qXfer} requests (@pxref{General Query Packets, 45559qXfer}). The @var{annex} in the @samp{qXfer} packet will be 45560@samp{target.xml}. The contents of the @samp{target.xml} annex are an 45561XML document, of the form described in @ref{Target Description 45562Format}. 45563 45564Alternatively, you can specify a file to read for the target description. 45565If a file is set, the target will not be queried. The commands to 45566specify a file are: 45567 45568@table @code 45569@cindex set tdesc filename 45570@item set tdesc filename @var{path} 45571Read the target description from @var{path}. 45572 45573@cindex unset tdesc filename 45574@item unset tdesc filename 45575Do not read the XML target description from a file. @value{GDBN} 45576will use the description supplied by the current target. 45577 45578@cindex show tdesc filename 45579@item show tdesc filename 45580Show the filename to read for a target description, if any. 45581@end table 45582 45583 45584@node Target Description Format 45585@section Target Description Format 45586@cindex target descriptions, XML format 45587 45588A target description annex is an @uref{http://www.w3.org/XML/, XML} 45589document which complies with the Document Type Definition provided in 45590the @value{GDBN} sources in @file{gdb/features/gdb-target.dtd}. This 45591means you can use generally available tools like @command{xmllint} to 45592check that your feature descriptions are well-formed and valid. 45593However, to help people unfamiliar with XML write descriptions for 45594their targets, we also describe the grammar here. 45595 45596Target descriptions can identify the architecture of the remote target 45597and (for some architectures) provide information about custom register 45598sets. They can also identify the OS ABI of the remote target. 45599@value{GDBN} can use this information to autoconfigure for your 45600target, or to warn you if you connect to an unsupported target. 45601 45602Here is a simple target description: 45603 45604@smallexample 45605<target version="1.0"> 45606 <architecture>i386:x86-64</architecture> 45607</target> 45608@end smallexample 45609 45610@noindent 45611This minimal description only says that the target uses 45612the x86-64 architecture. 45613 45614A target description has the following overall form, with [ ] marking 45615optional elements and @dots{} marking repeatable elements. The elements 45616are explained further below. 45617 45618@smallexample 45619<?xml version="1.0"?> 45620<!DOCTYPE target SYSTEM "gdb-target.dtd"> 45621<target version="1.0"> 45622 @r{[}@var{architecture}@r{]} 45623 @r{[}@var{osabi}@r{]} 45624 @r{[}@var{compatible}@r{]} 45625 @r{[}@var{feature}@dots{}@r{]} 45626</target> 45627@end smallexample 45628 45629@noindent 45630The description is generally insensitive to whitespace and line 45631breaks, under the usual common-sense rules. The XML version 45632declaration and document type declaration can generally be omitted 45633(@value{GDBN} does not require them), but specifying them may be 45634useful for XML validation tools. The @samp{version} attribute for 45635@samp{<target>} may also be omitted, but we recommend 45636including it; if future versions of @value{GDBN} use an incompatible 45637revision of @file{gdb-target.dtd}, they will detect and report 45638the version mismatch. 45639 45640@subsection Inclusion 45641@cindex target descriptions, inclusion 45642@cindex XInclude 45643@ifnotinfo 45644@cindex <xi:include> 45645@end ifnotinfo 45646 45647It can sometimes be valuable to split a target description up into 45648several different annexes, either for organizational purposes, or to 45649share files between different possible target descriptions. You can 45650divide a description into multiple files by replacing any element of 45651the target description with an inclusion directive of the form: 45652 45653@smallexample 45654<xi:include href="@var{document}"/> 45655@end smallexample 45656 45657@noindent 45658When @value{GDBN} encounters an element of this form, it will retrieve 45659the named XML @var{document}, and replace the inclusion directive with 45660the contents of that document. If the current description was read 45661using @samp{qXfer}, then so will be the included document; 45662@var{document} will be interpreted as the name of an annex. If the 45663current description was read from a file, @value{GDBN} will look for 45664@var{document} as a file in the same directory where it found the 45665original description. 45666 45667@subsection Architecture 45668@cindex <architecture> 45669 45670An @samp{<architecture>} element has this form: 45671 45672@smallexample 45673 <architecture>@var{arch}</architecture> 45674@end smallexample 45675 45676@var{arch} is one of the architectures from the set accepted by 45677@code{set architecture} (@pxref{Targets, ,Specifying a Debugging Target}). 45678 45679@subsection OS ABI 45680@cindex @code{<osabi>} 45681 45682This optional field was introduced in @value{GDBN} version 7.0. 45683Previous versions of @value{GDBN} ignore it. 45684 45685An @samp{<osabi>} element has this form: 45686 45687@smallexample 45688 <osabi>@var{abi-name}</osabi> 45689@end smallexample 45690 45691@var{abi-name} is an OS ABI name from the same selection accepted by 45692@w{@code{set osabi}} (@pxref{ABI, ,Configuring the Current ABI}). 45693 45694@subsection Compatible Architecture 45695@cindex @code{<compatible>} 45696 45697This optional field was introduced in @value{GDBN} version 7.0. 45698Previous versions of @value{GDBN} ignore it. 45699 45700A @samp{<compatible>} element has this form: 45701 45702@smallexample 45703 <compatible>@var{arch}</compatible> 45704@end smallexample 45705 45706@var{arch} is one of the architectures from the set accepted by 45707@code{set architecture} (@pxref{Targets, ,Specifying a Debugging Target}). 45708 45709A @samp{<compatible>} element is used to specify that the target 45710is able to run binaries in some other than the main target architecture 45711given by the @samp{<architecture>} element. For example, on the 45712Cell Broadband Engine, the main architecture is @code{powerpc:common} 45713or @code{powerpc:common64}, but the system is able to run binaries 45714in the @code{spu} architecture as well. The way to describe this 45715capability with @samp{<compatible>} is as follows: 45716 45717@smallexample 45718 <architecture>powerpc:common</architecture> 45719 <compatible>spu</compatible> 45720@end smallexample 45721 45722@subsection Features 45723@cindex <feature> 45724 45725Each @samp{<feature>} describes some logical portion of the target 45726system. Features are currently used to describe available CPU 45727registers and the types of their contents. A @samp{<feature>} element 45728has this form: 45729 45730@smallexample 45731<feature name="@var{name}"> 45732 @r{[}@var{type}@dots{}@r{]} 45733 @var{reg}@dots{} 45734</feature> 45735@end smallexample 45736 45737@noindent 45738Each feature's name should be unique within the description. The name 45739of a feature does not matter unless @value{GDBN} has some special 45740knowledge of the contents of that feature; if it does, the feature 45741should have its standard name. @xref{Standard Target Features}. 45742 45743@subsection Types 45744 45745Any register's value is a collection of bits which @value{GDBN} must 45746interpret. The default interpretation is a two's complement integer, 45747but other types can be requested by name in the register description. 45748Some predefined types are provided by @value{GDBN} (@pxref{Predefined 45749Target Types}), and the description can define additional composite 45750and enum types. 45751 45752Each type element must have an @samp{id} attribute, which gives 45753a unique (within the containing @samp{<feature>}) name to the type. 45754Types must be defined before they are used. 45755 45756@cindex <vector> 45757Some targets offer vector registers, which can be treated as arrays 45758of scalar elements. These types are written as @samp{<vector>} elements, 45759specifying the array element type, @var{type}, and the number of elements, 45760@var{count}: 45761 45762@smallexample 45763<vector id="@var{id}" type="@var{type}" count="@var{count}"/> 45764@end smallexample 45765 45766@cindex <union> 45767If a register's value is usefully viewed in multiple ways, define it 45768with a union type containing the useful representations. The 45769@samp{<union>} element contains one or more @samp{<field>} elements, 45770each of which has a @var{name} and a @var{type}: 45771 45772@smallexample 45773<union id="@var{id}"> 45774 <field name="@var{name}" type="@var{type}"/> 45775 @dots{} 45776</union> 45777@end smallexample 45778 45779@cindex <struct> 45780@cindex <flags> 45781If a register's value is composed from several separate values, define 45782it with either a structure type or a flags type. 45783A flags type may only contain bitfields. 45784A structure type may either contain only bitfields or contain no bitfields. 45785If the value contains only bitfields, its total size in bytes must be 45786specified. 45787 45788Non-bitfield values have a @var{name} and @var{type}. 45789 45790@smallexample 45791<struct id="@var{id}"> 45792 <field name="@var{name}" type="@var{type}"/> 45793 @dots{} 45794</struct> 45795@end smallexample 45796 45797Both @var{name} and @var{type} values are required. 45798No implicit padding is added. 45799 45800Bitfield values have a @var{name}, @var{start}, @var{end} and @var{type}. 45801 45802@smallexample 45803<struct id="@var{id}" size="@var{size}"> 45804 <field name="@var{name}" start="@var{start}" end="@var{end}" type="@var{type}"/> 45805 @dots{} 45806</struct> 45807@end smallexample 45808 45809@smallexample 45810<flags id="@var{id}" size="@var{size}"> 45811 <field name="@var{name}" start="@var{start}" end="@var{end}" type="@var{type}"/> 45812 @dots{} 45813</flags> 45814@end smallexample 45815 45816The @var{name} value is required. 45817Bitfield values may be named with the empty string, @samp{""}, 45818in which case the field is ``filler'' and its value is not printed. 45819Not all bits need to be specified, so ``filler'' fields are optional. 45820 45821The @var{start} and @var{end} values are required, and @var{type} 45822is optional. 45823The field's @var{start} must be less than or equal to its @var{end}, 45824and zero represents the least significant bit. 45825 45826The default value of @var{type} is @code{bool} for single bit fields, 45827and an unsigned integer otherwise. 45828 45829Which to choose? Structures or flags? 45830 45831Registers defined with @samp{flags} have these advantages over 45832defining them with @samp{struct}: 45833 45834@itemize @bullet 45835@item 45836Arithmetic may be performed on them as if they were integers. 45837@item 45838They are printed in a more readable fashion. 45839@end itemize 45840 45841Registers defined with @samp{struct} have one advantage over 45842defining them with @samp{flags}: 45843 45844@itemize @bullet 45845@item 45846One can fetch individual fields like in @samp{C}. 45847 45848@smallexample 45849(gdb) print $my_struct_reg.field3 45850$1 = 42 45851@end smallexample 45852 45853@end itemize 45854 45855@subsection Registers 45856@cindex <reg> 45857 45858Each register is represented as an element with this form: 45859 45860@smallexample 45861<reg name="@var{name}" 45862 bitsize="@var{size}" 45863 @r{[}regnum="@var{num}"@r{]} 45864 @r{[}save-restore="@var{save-restore}"@r{]} 45865 @r{[}type="@var{type}"@r{]} 45866 @r{[}group="@var{group}"@r{]}/> 45867@end smallexample 45868 45869@noindent 45870The components are as follows: 45871 45872@table @var 45873 45874@item name 45875The register's name; it must be unique within the target description. 45876 45877@item bitsize 45878The register's size, in bits. 45879 45880@item regnum 45881The register's number. If omitted, a register's number is one greater 45882than that of the previous register (either in the current feature or in 45883a preceding feature); the first register in the target description 45884defaults to zero. This register number is used to read or write 45885the register; e.g.@: it is used in the remote @code{p} and @code{P} 45886packets, and registers appear in the @code{g} and @code{G} packets 45887in order of increasing register number. 45888 45889@item save-restore 45890Whether the register should be preserved across inferior function 45891calls; this must be either @code{yes} or @code{no}. The default is 45892@code{yes}, which is appropriate for most registers except for 45893some system control registers; this is not related to the target's 45894ABI. 45895 45896@item type 45897The type of the register. It may be a predefined type, a type 45898defined in the current feature, or one of the special types @code{int} 45899and @code{float}. @code{int} is an integer type of the correct size 45900for @var{bitsize}, and @code{float} is a floating point type (in the 45901architecture's normal floating point format) of the correct size for 45902@var{bitsize}. The default is @code{int}. 45903 45904@item group 45905The register group to which this register belongs. It can be one of the 45906standard register groups @code{general}, @code{float}, @code{vector} or an 45907arbitrary string. Group names should be limited to alphanumeric characters. 45908If a group name is made up of multiple words the words may be separated by 45909hyphens; e.g.@: @code{special-group} or @code{ultra-special-group}. If no 45910@var{group} is specified, @value{GDBN} will not display the register in 45911@code{info registers}. 45912 45913@end table 45914 45915@node Predefined Target Types 45916@section Predefined Target Types 45917@cindex target descriptions, predefined types 45918 45919Type definitions in the self-description can build up composite types 45920from basic building blocks, but can not define fundamental types. Instead, 45921standard identifiers are provided by @value{GDBN} for the fundamental 45922types. The currently supported types are: 45923 45924@table @code 45925 45926@item bool 45927Boolean type, occupying a single bit. 45928 45929@item int8 45930@itemx int16 45931@itemx int24 45932@itemx int32 45933@itemx int64 45934@itemx int128 45935Signed integer types holding the specified number of bits. 45936 45937@item uint8 45938@itemx uint16 45939@itemx uint24 45940@itemx uint32 45941@itemx uint64 45942@itemx uint128 45943Unsigned integer types holding the specified number of bits. 45944 45945@item code_ptr 45946@itemx data_ptr 45947Pointers to unspecified code and data. The program counter and 45948any dedicated return address register may be marked as code 45949pointers; printing a code pointer converts it into a symbolic 45950address. The stack pointer and any dedicated address registers 45951may be marked as data pointers. 45952 45953@item ieee_single 45954Single precision IEEE floating point. 45955 45956@item ieee_double 45957Double precision IEEE floating point. 45958 45959@item arm_fpa_ext 45960The 12-byte extended precision format used by ARM FPA registers. 45961 45962@item i387_ext 45963The 10-byte extended precision format used by x87 registers. 45964 45965@item i386_eflags 4596632bit @sc{eflags} register used by x86. 45967 45968@item i386_mxcsr 4596932bit @sc{mxcsr} register used by x86. 45970 45971@end table 45972 45973@node Enum Target Types 45974@section Enum Target Types 45975@cindex target descriptions, enum types 45976 45977Enum target types are useful in @samp{struct} and @samp{flags} 45978register descriptions. @xref{Target Description Format}. 45979 45980Enum types have a name, size and a list of name/value pairs. 45981 45982@smallexample 45983<enum id="@var{id}" size="@var{size}"> 45984 <evalue name="@var{name}" value="@var{value}"/> 45985 @dots{} 45986</enum> 45987@end smallexample 45988 45989Enums must be defined before they are used. 45990 45991@smallexample 45992<enum id="levels_type" size="4"> 45993 <evalue name="low" value="0"/> 45994 <evalue name="high" value="1"/> 45995</enum> 45996<flags id="flags_type" size="4"> 45997 <field name="X" start="0"/> 45998 <field name="LEVEL" start="1" end="1" type="levels_type"/> 45999</flags> 46000<reg name="flags" bitsize="32" type="flags_type"/> 46001@end smallexample 46002 46003Given that description, a value of 3 for the @samp{flags} register 46004would be printed as: 46005 46006@smallexample 46007(gdb) info register flags 46008flags 0x3 [ X LEVEL=high ] 46009@end smallexample 46010 46011@node Standard Target Features 46012@section Standard Target Features 46013@cindex target descriptions, standard features 46014 46015A target description must contain either no registers or all the 46016target's registers. If the description contains no registers, then 46017@value{GDBN} will assume a default register layout, selected based on 46018the architecture. If the description contains any registers, the 46019default layout will not be used; the standard registers must be 46020described in the target description, in such a way that @value{GDBN} 46021can recognize them. 46022 46023This is accomplished by giving specific names to feature elements 46024which contain standard registers. @value{GDBN} will look for features 46025with those names and verify that they contain the expected registers; 46026if any known feature is missing required registers, or if any required 46027feature is missing, @value{GDBN} will reject the target 46028description. You can add additional registers to any of the 46029standard features --- @value{GDBN} will display them just as if 46030they were added to an unrecognized feature. 46031 46032This section lists the known features and their expected contents. 46033Sample XML documents for these features are included in the 46034@value{GDBN} source tree, in the directory @file{gdb/features}. 46035 46036Names recognized by @value{GDBN} should include the name of the 46037company or organization which selected the name, and the overall 46038architecture to which the feature applies; so e.g.@: the feature 46039containing ARM core registers is named @samp{org.gnu.gdb.arm.core}. 46040 46041The names of registers are not case sensitive for the purpose 46042of recognizing standard features, but @value{GDBN} will only display 46043registers using the capitalization used in the description. 46044 46045@menu 46046* AArch64 Features:: 46047* ARC Features:: 46048* ARM Features:: 46049* i386 Features:: 46050* MicroBlaze Features:: 46051* MIPS Features:: 46052* M68K Features:: 46053* NDS32 Features:: 46054* Nios II Features:: 46055* OpenRISC 1000 Features:: 46056* PowerPC Features:: 46057* RISC-V Features:: 46058* RX Features:: 46059* S/390 and System z Features:: 46060* Sparc Features:: 46061* TIC6x Features:: 46062@end menu 46063 46064 46065@node AArch64 Features 46066@subsection AArch64 Features 46067@cindex target descriptions, AArch64 features 46068 46069The @samp{org.gnu.gdb.aarch64.core} feature is required for AArch64 46070targets. It should contain registers @samp{x0} through @samp{x30}, 46071@samp{sp}, @samp{pc}, and @samp{cpsr}. 46072 46073The @samp{org.gnu.gdb.aarch64.fpu} feature is optional. If present, 46074it should contain registers @samp{v0} through @samp{v31}, @samp{fpsr}, 46075and @samp{fpcr}. 46076 46077The @samp{org.gnu.gdb.aarch64.sve} feature is optional. If present, 46078it should contain registers @samp{z0} through @samp{z31}, @samp{p0} 46079through @samp{p15}, @samp{ffr} and @samp{vg}. 46080 46081The @samp{org.gnu.gdb.aarch64.pauth} feature is optional. If present, 46082it should contain registers @samp{pauth_dmask} and @samp{pauth_cmask}. 46083 46084@node ARC Features 46085@subsection ARC Features 46086@cindex target descriptions, ARC Features 46087 46088ARC processors are so configurable that even core registers and their numbers 46089are not predetermined completely. Moreover, @emph{flags} and @emph{PC} 46090registers, which are important to @value{GDBN}, are not ``core'' registers in 46091ARC. Therefore, there are two features that their presence is mandatory: 46092@samp{org.gnu.gdb.arc.core} and @samp{org.gnu.gdb.arc.aux}. 46093 46094The @samp{org.gnu.gdb.arc.core} feature is required for all targets. It must 46095contain registers: 46096 46097@itemize @minus 46098@item 46099@samp{r0} through @samp{r25} for normal register file targets. 46100@item 46101@samp{r0} through @samp{r3}, and @samp{r10} through @samp{r15} for reduced 46102register file targets. 46103@item 46104@samp{gp}, @samp{fp}, @samp{sp}, @samp{r30}@footnote{Not necessary for ARCv1.}, 46105@samp{blink}, @samp{lp_count}, @samp{pcl}. 46106@end itemize 46107 46108In case of an ARCompact target (ARCv1 ISA), the @samp{org.gnu.gdb.arc.core} 46109feature may contain registers @samp{ilink1} and @samp{ilink2}. While in case 46110of ARC EM and ARC HS targets (ARCv2 ISA), register @samp{ilink} may be present. 46111The difference between ARCv1 and ARCv2 is the naming of registers @emph{29th} 46112and @emph{30th}. They are called @samp{ilink1} and @samp{ilink2} for ARCv1 and 46113are optional. For ARCv2, they are called @samp{ilink} and @samp{r30} and only 46114@samp{ilink} is optional. The optionality of @samp{ilink*} registers is 46115because of their inaccessibility during user space debugging sessions. 46116 46117Extension core registers @samp{r32} through @samp{r59} are optional and their 46118existence depends on the configuration. When debugging GNU/Linux applications, 46119i.e.@: user space debugging, these core registers are not available. 46120 46121The @samp{org.gnu.gdb.arc.aux} feature is required for all ARC targets. Here 46122is the list of registers pertinent to this feature: 46123 46124@itemize @minus 46125@item 46126mandatory: @samp{pc} and @samp{status32}. 46127@item 46128optional: @samp{lp_start}, @samp{lp_end}, and @samp{bta}. 46129@end itemize 46130 46131@node ARM Features 46132@subsection ARM Features 46133@cindex target descriptions, ARM features 46134 46135The @samp{org.gnu.gdb.arm.core} feature is required for non-M-profile 46136ARM targets. 46137It should contain registers @samp{r0} through @samp{r13}, @samp{sp}, 46138@samp{lr}, @samp{pc}, and @samp{cpsr}. 46139 46140For M-profile targets (e.g.@: Cortex-M3), the @samp{org.gnu.gdb.arm.core} 46141feature is replaced by @samp{org.gnu.gdb.arm.m-profile}. It should contain 46142registers @samp{r0} through @samp{r13}, @samp{sp}, @samp{lr}, @samp{pc}, 46143and @samp{xpsr}. 46144 46145The @samp{org.gnu.gdb.arm.fpa} feature is optional. If present, it 46146should contain registers @samp{f0} through @samp{f7} and @samp{fps}. 46147 46148The @samp{org.gnu.gdb.xscale.iwmmxt} feature is optional. If present, 46149it should contain at least registers @samp{wR0} through @samp{wR15} and 46150@samp{wCGR0} through @samp{wCGR3}. The @samp{wCID}, @samp{wCon}, 46151@samp{wCSSF}, and @samp{wCASF} registers are optional. 46152 46153The @samp{org.gnu.gdb.arm.vfp} feature is optional. If present, it 46154should contain at least registers @samp{d0} through @samp{d15}. If 46155they are present, @samp{d16} through @samp{d31} should also be included. 46156@value{GDBN} will synthesize the single-precision registers from 46157halves of the double-precision registers. 46158 46159The @samp{org.gnu.gdb.arm.neon} feature is optional. It does not 46160need to contain registers; it instructs @value{GDBN} to display the 46161VFP double-precision registers as vectors and to synthesize the 46162quad-precision registers from pairs of double-precision registers. 46163If this feature is present, @samp{org.gnu.gdb.arm.vfp} must also 46164be present and include 32 double-precision registers. 46165 46166@node i386 Features 46167@subsection i386 Features 46168@cindex target descriptions, i386 features 46169 46170The @samp{org.gnu.gdb.i386.core} feature is required for i386/amd64 46171targets. It should describe the following registers: 46172 46173@itemize @minus 46174@item 46175@samp{eax} through @samp{edi} plus @samp{eip} for i386 46176@item 46177@samp{rax} through @samp{r15} plus @samp{rip} for amd64 46178@item 46179@samp{eflags}, @samp{cs}, @samp{ss}, @samp{ds}, @samp{es}, 46180@samp{fs}, @samp{gs} 46181@item 46182@samp{st0} through @samp{st7} 46183@item 46184@samp{fctrl}, @samp{fstat}, @samp{ftag}, @samp{fiseg}, @samp{fioff}, 46185@samp{foseg}, @samp{fooff} and @samp{fop} 46186@end itemize 46187 46188The register sets may be different, depending on the target. 46189 46190The @samp{org.gnu.gdb.i386.sse} feature is optional. It should 46191describe registers: 46192 46193@itemize @minus 46194@item 46195@samp{xmm0} through @samp{xmm7} for i386 46196@item 46197@samp{xmm0} through @samp{xmm15} for amd64 46198@item 46199@samp{mxcsr} 46200@end itemize 46201 46202The @samp{org.gnu.gdb.i386.avx} feature is optional and requires the 46203@samp{org.gnu.gdb.i386.sse} feature. It should 46204describe the upper 128 bits of @sc{ymm} registers: 46205 46206@itemize @minus 46207@item 46208@samp{ymm0h} through @samp{ymm7h} for i386 46209@item 46210@samp{ymm0h} through @samp{ymm15h} for amd64 46211@end itemize 46212 46213The @samp{org.gnu.gdb.i386.mpx} is an optional feature representing Intel 46214Memory Protection Extension (MPX). It should describe the following registers: 46215 46216@itemize @minus 46217@item 46218@samp{bnd0raw} through @samp{bnd3raw} for i386 and amd64. 46219@item 46220@samp{bndcfgu} and @samp{bndstatus} for i386 and amd64. 46221@end itemize 46222 46223The @samp{org.gnu.gdb.i386.linux} feature is optional. It should 46224describe a single register, @samp{orig_eax}. 46225 46226The @samp{org.gnu.gdb.i386.segments} feature is optional. It should 46227describe two system registers: @samp{fs_base} and @samp{gs_base}. 46228 46229The @samp{org.gnu.gdb.i386.avx512} feature is optional and requires the 46230@samp{org.gnu.gdb.i386.avx} feature. It should 46231describe additional @sc{xmm} registers: 46232 46233@itemize @minus 46234@item 46235@samp{xmm16h} through @samp{xmm31h}, only valid for amd64. 46236@end itemize 46237 46238It should describe the upper 128 bits of additional @sc{ymm} registers: 46239 46240@itemize @minus 46241@item 46242@samp{ymm16h} through @samp{ymm31h}, only valid for amd64. 46243@end itemize 46244 46245It should 46246describe the upper 256 bits of @sc{zmm} registers: 46247 46248@itemize @minus 46249@item 46250@samp{zmm0h} through @samp{zmm7h} for i386. 46251@item 46252@samp{zmm0h} through @samp{zmm15h} for amd64. 46253@end itemize 46254 46255It should 46256describe the additional @sc{zmm} registers: 46257 46258@itemize @minus 46259@item 46260@samp{zmm16h} through @samp{zmm31h}, only valid for amd64. 46261@end itemize 46262 46263The @samp{org.gnu.gdb.i386.pkeys} feature is optional. It should 46264describe a single register, @samp{pkru}. It is a 32-bit register 46265valid for i386 and amd64. 46266 46267@node MicroBlaze Features 46268@subsection MicroBlaze Features 46269@cindex target descriptions, MicroBlaze features 46270 46271The @samp{org.gnu.gdb.microblaze.core} feature is required for MicroBlaze 46272targets. It should contain registers @samp{r0} through @samp{r31}, 46273@samp{rpc}, @samp{rmsr}, @samp{rear}, @samp{resr}, @samp{rfsr}, @samp{rbtr}, 46274@samp{rpvr}, @samp{rpvr1} through @samp{rpvr11}, @samp{redr}, @samp{rpid}, 46275@samp{rzpr}, @samp{rtlbx}, @samp{rtlbsx}, @samp{rtlblo}, and @samp{rtlbhi}. 46276 46277The @samp{org.gnu.gdb.microblaze.stack-protect} feature is optional. 46278If present, it should contain registers @samp{rshr} and @samp{rslr} 46279 46280@node MIPS Features 46281@subsection @acronym{MIPS} Features 46282@cindex target descriptions, @acronym{MIPS} features 46283 46284The @samp{org.gnu.gdb.mips.cpu} feature is required for @acronym{MIPS} targets. 46285It should contain registers @samp{r0} through @samp{r31}, @samp{lo}, 46286@samp{hi}, and @samp{pc}. They may be 32-bit or 64-bit depending 46287on the target. 46288 46289The @samp{org.gnu.gdb.mips.cp0} feature is also required. It should 46290contain at least the @samp{status}, @samp{badvaddr}, and @samp{cause} 46291registers. They may be 32-bit or 64-bit depending on the target. 46292 46293The @samp{org.gnu.gdb.mips.fpu} feature is currently required, though 46294it may be optional in a future version of @value{GDBN}. It should 46295contain registers @samp{f0} through @samp{f31}, @samp{fcsr}, and 46296@samp{fir}. They may be 32-bit or 64-bit depending on the target. 46297 46298The @samp{org.gnu.gdb.mips.dsp} feature is optional. It should 46299contain registers @samp{hi1} through @samp{hi3}, @samp{lo1} through 46300@samp{lo3}, and @samp{dspctl}. The @samp{dspctl} register should 46301be 32-bit and the rest may be 32-bit or 64-bit depending on the target. 46302 46303The @samp{org.gnu.gdb.mips.linux} feature is optional. It should 46304contain a single register, @samp{restart}, which is used by the 46305Linux kernel to control restartable syscalls. 46306 46307@node M68K Features 46308@subsection M68K Features 46309@cindex target descriptions, M68K features 46310 46311@table @code 46312@item @samp{org.gnu.gdb.m68k.core} 46313@itemx @samp{org.gnu.gdb.coldfire.core} 46314@itemx @samp{org.gnu.gdb.fido.core} 46315One of those features must be always present. 46316The feature that is present determines which flavor of m68k is 46317used. The feature that is present should contain registers 46318@samp{d0} through @samp{d7}, @samp{a0} through @samp{a5}, @samp{fp}, 46319@samp{sp}, @samp{ps} and @samp{pc}. 46320 46321@item @samp{org.gnu.gdb.coldfire.fp} 46322This feature is optional. If present, it should contain registers 46323@samp{fp0} through @samp{fp7}, @samp{fpcontrol}, @samp{fpstatus} and 46324@samp{fpiaddr}. 46325 46326Note that, despite the fact that this feature's name says 46327@samp{coldfire}, it is used to describe any floating point registers. 46328The size of the registers must match the main m68k flavor; so, for 46329example, if the primary feature is reported as @samp{coldfire}, then 4633064-bit floating point registers are required. 46331@end table 46332 46333@node NDS32 Features 46334@subsection NDS32 Features 46335@cindex target descriptions, NDS32 features 46336 46337The @samp{org.gnu.gdb.nds32.core} feature is required for NDS32 46338targets. It should contain at least registers @samp{r0} through 46339@samp{r10}, @samp{r15}, @samp{fp}, @samp{gp}, @samp{lp}, @samp{sp}, 46340and @samp{pc}. 46341 46342The @samp{org.gnu.gdb.nds32.fpu} feature is optional. If present, 46343it should contain 64-bit double-precision floating-point registers 46344@samp{fd0} through @emph{fdN}, which should be @samp{fd3}, @samp{fd7}, 46345@samp{fd15}, or @samp{fd31} based on the FPU configuration implemented. 46346 46347@emph{Note:} The first sixteen 64-bit double-precision floating-point 46348registers are overlapped with the thirty-two 32-bit single-precision 46349floating-point registers. The 32-bit single-precision registers, if 46350not being listed explicitly, will be synthesized from halves of the 46351overlapping 64-bit double-precision registers. Listing 32-bit 46352single-precision registers explicitly is deprecated, and the 46353support to it could be totally removed some day. 46354 46355@node Nios II Features 46356@subsection Nios II Features 46357@cindex target descriptions, Nios II features 46358 46359The @samp{org.gnu.gdb.nios2.cpu} feature is required for Nios II 46360targets. It should contain the 32 core registers (@samp{zero}, 46361@samp{at}, @samp{r2} through @samp{r23}, @samp{et} through @samp{ra}), 46362@samp{pc}, and the 16 control registers (@samp{status} through 46363@samp{mpuacc}). 46364 46365@node OpenRISC 1000 Features 46366@subsection Openrisc 1000 Features 46367@cindex target descriptions, OpenRISC 1000 features 46368 46369The @samp{org.gnu.gdb.or1k.group0} feature is required for OpenRISC 1000 46370targets. It should contain the 32 general purpose registers (@samp{r0} 46371through @samp{r31}), @samp{ppc}, @samp{npc} and @samp{sr}. 46372 46373@node PowerPC Features 46374@subsection PowerPC Features 46375@cindex target descriptions, PowerPC features 46376 46377The @samp{org.gnu.gdb.power.core} feature is required for PowerPC 46378targets. It should contain registers @samp{r0} through @samp{r31}, 46379@samp{pc}, @samp{msr}, @samp{cr}, @samp{lr}, @samp{ctr}, and 46380@samp{xer}. They may be 32-bit or 64-bit depending on the target. 46381 46382The @samp{org.gnu.gdb.power.fpu} feature is optional. It should 46383contain registers @samp{f0} through @samp{f31} and @samp{fpscr}. 46384 46385The @samp{org.gnu.gdb.power.altivec} feature is optional. It should 46386contain registers @samp{vr0} through @samp{vr31}, @samp{vscr}, and 46387@samp{vrsave}. @value{GDBN} will define pseudo-registers @samp{v0} 46388through @samp{v31} as aliases for the corresponding @samp{vrX} 46389registers. 46390 46391The @samp{org.gnu.gdb.power.vsx} feature is optional. It should 46392contain registers @samp{vs0h} through @samp{vs31h}. @value{GDBN} will 46393combine these registers with the floating point registers (@samp{f0} 46394through @samp{f31}) and the altivec registers (@samp{vr0} through 46395@samp{vr31}) to present the 128-bit wide registers @samp{vs0} through 46396@samp{vs63}, the set of vector-scalar registers for POWER7. 46397Therefore, this feature requires both @samp{org.gnu.gdb.power.fpu} and 46398@samp{org.gnu.gdb.power.altivec}. 46399 46400The @samp{org.gnu.gdb.power.spe} feature is optional. It should 46401contain registers @samp{ev0h} through @samp{ev31h}, @samp{acc}, and 46402@samp{spefscr}. SPE targets should provide 32-bit registers in 46403@samp{org.gnu.gdb.power.core} and provide the upper halves in 46404@samp{ev0h} through @samp{ev31h}. @value{GDBN} will combine 46405these to present registers @samp{ev0} through @samp{ev31} to the 46406user. 46407 46408The @samp{org.gnu.gdb.power.ppr} feature is optional. It should 46409contain the 64-bit register @samp{ppr}. 46410 46411The @samp{org.gnu.gdb.power.dscr} feature is optional. It should 46412contain the 64-bit register @samp{dscr}. 46413 46414The @samp{org.gnu.gdb.power.tar} feature is optional. It should 46415contain the 64-bit register @samp{tar}. 46416 46417The @samp{org.gnu.gdb.power.ebb} feature is optional. It should 46418contain registers @samp{bescr}, @samp{ebbhr} and @samp{ebbrr}, all 4641964-bit wide. 46420 46421The @samp{org.gnu.gdb.power.linux.pmu} feature is optional. It should 46422contain registers @samp{mmcr0}, @samp{mmcr2}, @samp{siar}, @samp{sdar} 46423and @samp{sier}, all 64-bit wide. This is the subset of the isa 2.07 46424server PMU registers provided by @sc{gnu}/Linux. 46425 46426The @samp{org.gnu.gdb.power.htm.spr} feature is optional. It should 46427contain registers @samp{tfhar}, @samp{texasr} and @samp{tfiar}, all 4642864-bit wide. 46429 46430The @samp{org.gnu.gdb.power.htm.core} feature is optional. It should 46431contain the checkpointed general-purpose registers @samp{cr0} through 46432@samp{cr31}, as well as the checkpointed registers @samp{clr} and 46433@samp{cctr}. These registers may all be either 32-bit or 64-bit 46434depending on the target. It should also contain the checkpointed 46435registers @samp{ccr} and @samp{cxer}, which should both be 32-bit 46436wide. 46437 46438The @samp{org.gnu.gdb.power.htm.fpu} feature is optional. It should 46439contain the checkpointed 64-bit floating-point registers @samp{cf0} 46440through @samp{cf31}, as well as the checkpointed 64-bit register 46441@samp{cfpscr}. 46442 46443The @samp{org.gnu.gdb.power.htm.altivec} feature is optional. It 46444should contain the checkpointed altivec registers @samp{cvr0} through 46445@samp{cvr31}, all 128-bit wide. It should also contain the 46446checkpointed registers @samp{cvscr} and @samp{cvrsave}, both 32-bit 46447wide. 46448 46449The @samp{org.gnu.gdb.power.htm.vsx} feature is optional. It should 46450contain registers @samp{cvs0h} through @samp{cvs31h}. @value{GDBN} 46451will combine these registers with the checkpointed floating point 46452registers (@samp{cf0} through @samp{cf31}) and the checkpointed 46453altivec registers (@samp{cvr0} through @samp{cvr31}) to present the 46454128-bit wide checkpointed vector-scalar registers @samp{cvs0} through 46455@samp{cvs63}. Therefore, this feature requires both 46456@samp{org.gnu.gdb.power.htm.altivec} and 46457@samp{org.gnu.gdb.power.htm.fpu}. 46458 46459The @samp{org.gnu.gdb.power.htm.ppr} feature is optional. It should 46460contain the 64-bit checkpointed register @samp{cppr}. 46461 46462The @samp{org.gnu.gdb.power.htm.dscr} feature is optional. It should 46463contain the 64-bit checkpointed register @samp{cdscr}. 46464 46465The @samp{org.gnu.gdb.power.htm.tar} feature is optional. It should 46466contain the 64-bit checkpointed register @samp{ctar}. 46467 46468 46469@node RISC-V Features 46470@subsection RISC-V Features 46471@cindex target descriptions, RISC-V Features 46472 46473The @samp{org.gnu.gdb.riscv.cpu} feature is required for RISC-V 46474targets. It should contain the registers @samp{x0} through 46475@samp{x31}, and @samp{pc}. Either the architectural names (@samp{x0}, 46476@samp{x1}, etc) can be used, or the ABI names (@samp{zero}, @samp{ra}, 46477etc). 46478 46479The @samp{org.gnu.gdb.riscv.fpu} feature is optional. If present, it 46480should contain registers @samp{f0} through @samp{f31}, @samp{fflags}, 46481@samp{frm}, and @samp{fcsr}. As with the cpu feature, either the 46482architectural register names, or the ABI names can be used. 46483 46484The @samp{org.gnu.gdb.riscv.virtual} feature is optional. If present, 46485it should contain registers that are not backed by real registers on 46486the target, but are instead virtual, where the register value is 46487derived from other target state. In many ways these are like 46488@value{GDBN}s pseudo-registers, except implemented by the target. 46489Currently the only register expected in this set is the one byte 46490@samp{priv} register that contains the target's privilege level in the 46491least significant two bits. 46492 46493The @samp{org.gnu.gdb.riscv.csr} feature is optional. If present, it 46494should contain all of the target's standard CSRs. Standard CSRs are 46495those defined in the RISC-V specification documents. There is some 46496overlap between this feature and the fpu feature; the @samp{fflags}, 46497@samp{frm}, and @samp{fcsr} registers could be in either feature. The 46498expectation is that these registers will be in the fpu feature if the 46499target has floating point hardware, but can be moved into the csr 46500feature if the target has the floating point control registers, but no 46501other floating point hardware. 46502 46503The @samp{org.gnu.gdb.riscv.vector} feature is optional. If present, 46504it should contain registers @samp{v0} through @samp{v31}, all of which 46505must be the same size. These requirements are based on the v0.10 46506draft vector extension, as the vector extension is not yet final. In 46507the event that the register set of the vector extension changes for 46508the final specification, the requirements given here could change for 46509future releases of @value{GDBN}. 46510 46511@node RX Features 46512@subsection RX Features 46513@cindex target descriptions, RX Features 46514 46515The @samp{org.gnu.gdb.rx.core} feature is required for RX 46516targets. It should contain the registers @samp{r0} through 46517@samp{r15}, @samp{usp}, @samp{isp}, @samp{psw}, @samp{pc}, @samp{intb}, 46518@samp{bpsw}, @samp{bpc}, @samp{fintv}, @samp{fpsw}, and @samp{acc}. 46519 46520@node S/390 and System z Features 46521@subsection S/390 and System z Features 46522@cindex target descriptions, S/390 features 46523@cindex target descriptions, System z features 46524 46525The @samp{org.gnu.gdb.s390.core} feature is required for S/390 and 46526System z targets. It should contain the PSW and the 16 general 46527registers. In particular, System z targets should provide the 64-bit 46528registers @samp{pswm}, @samp{pswa}, and @samp{r0} through @samp{r15}. 46529S/390 targets should provide the 32-bit versions of these registers. 46530A System z target that runs in 31-bit addressing mode should provide 4653132-bit versions of @samp{pswm} and @samp{pswa}, as well as the general 46532register's upper halves @samp{r0h} through @samp{r15h}, and their 46533lower halves @samp{r0l} through @samp{r15l}. 46534 46535The @samp{org.gnu.gdb.s390.fpr} feature is required. It should 46536contain the 64-bit registers @samp{f0} through @samp{f15}, and 46537@samp{fpc}. 46538 46539The @samp{org.gnu.gdb.s390.acr} feature is required. It should 46540contain the 32-bit registers @samp{acr0} through @samp{acr15}. 46541 46542The @samp{org.gnu.gdb.s390.linux} feature is optional. It should 46543contain the register @samp{orig_r2}, which is 64-bit wide on System z 46544targets and 32-bit otherwise. In addition, the feature may contain 46545the @samp{last_break} register, whose width depends on the addressing 46546mode, as well as the @samp{system_call} register, which is always 4654732-bit wide. 46548 46549The @samp{org.gnu.gdb.s390.tdb} feature is optional. It should 46550contain the 64-bit registers @samp{tdb0}, @samp{tac}, @samp{tct}, 46551@samp{atia}, and @samp{tr0} through @samp{tr15}. 46552 46553The @samp{org.gnu.gdb.s390.vx} feature is optional. It should contain 4655464-bit wide registers @samp{v0l} through @samp{v15l}, which will be 46555combined by @value{GDBN} with the floating point registers @samp{f0} 46556through @samp{f15} to present the 128-bit wide vector registers 46557@samp{v0} through @samp{v15}. In addition, this feature should 46558contain the 128-bit wide vector registers @samp{v16} through 46559@samp{v31}. 46560 46561The @samp{org.gnu.gdb.s390.gs} feature is optional. It should contain 46562the 64-bit wide guarded-storage-control registers @samp{gsd}, 46563@samp{gssm}, and @samp{gsepla}. 46564 46565The @samp{org.gnu.gdb.s390.gsbc} feature is optional. It should contain 46566the 64-bit wide guarded-storage broadcast control registers 46567@samp{bc_gsd}, @samp{bc_gssm}, and @samp{bc_gsepla}. 46568 46569@node Sparc Features 46570@subsection Sparc Features 46571@cindex target descriptions, sparc32 features 46572@cindex target descriptions, sparc64 features 46573The @samp{org.gnu.gdb.sparc.cpu} feature is required for sparc32/sparc64 46574targets. It should describe the following registers: 46575 46576@itemize @minus 46577@item 46578@samp{g0} through @samp{g7} 46579@item 46580@samp{o0} through @samp{o7} 46581@item 46582@samp{l0} through @samp{l7} 46583@item 46584@samp{i0} through @samp{i7} 46585@end itemize 46586 46587They may be 32-bit or 64-bit depending on the target. 46588 46589Also the @samp{org.gnu.gdb.sparc.fpu} feature is required for sparc32/sparc64 46590targets. It should describe the following registers: 46591 46592@itemize @minus 46593@item 46594@samp{f0} through @samp{f31} 46595@item 46596@samp{f32} through @samp{f62} for sparc64 46597@end itemize 46598 46599The @samp{org.gnu.gdb.sparc.cp0} feature is required for sparc32/sparc64 46600targets. It should describe the following registers: 46601 46602@itemize @minus 46603@item 46604@samp{y}, @samp{psr}, @samp{wim}, @samp{tbr}, @samp{pc}, @samp{npc}, 46605@samp{fsr}, and @samp{csr} for sparc32 46606@item 46607@samp{pc}, @samp{npc}, @samp{state}, @samp{fsr}, @samp{fprs}, and @samp{y} 46608for sparc64 46609@end itemize 46610 46611@node TIC6x Features 46612@subsection TMS320C6x Features 46613@cindex target descriptions, TIC6x features 46614@cindex target descriptions, TMS320C6x features 46615The @samp{org.gnu.gdb.tic6x.core} feature is required for TMS320C6x 46616targets. It should contain registers @samp{A0} through @samp{A15}, 46617registers @samp{B0} through @samp{B15}, @samp{CSR} and @samp{PC}. 46618 46619The @samp{org.gnu.gdb.tic6x.gp} feature is optional. It should 46620contain registers @samp{A16} through @samp{A31} and @samp{B16} 46621through @samp{B31}. 46622 46623The @samp{org.gnu.gdb.tic6x.c6xp} feature is optional. It should 46624contain registers @samp{TSR}, @samp{ILC} and @samp{RILC}. 46625 46626@node Operating System Information 46627@appendix Operating System Information 46628@cindex operating system information 46629 46630Users of @value{GDBN} often wish to obtain information about the state of 46631the operating system running on the target---for example the list of 46632processes, or the list of open files. This section describes the 46633mechanism that makes it possible. This mechanism is similar to the 46634target features mechanism (@pxref{Target Descriptions}), but focuses 46635on a different aspect of target. 46636 46637Operating system information is retrieved from the target via the 46638remote protocol, using @samp{qXfer} requests (@pxref{qXfer osdata 46639read}). The object name in the request should be @samp{osdata}, and 46640the @var{annex} identifies the data to be fetched. 46641 46642@menu 46643* Process list:: 46644@end menu 46645 46646@node Process list 46647@appendixsection Process list 46648@cindex operating system information, process list 46649 46650When requesting the process list, the @var{annex} field in the 46651@samp{qXfer} request should be @samp{processes}. The returned data is 46652an XML document. The formal syntax of this document is defined in 46653@file{gdb/features/osdata.dtd}. 46654 46655An example document is: 46656 46657@smallexample 46658<?xml version="1.0"?> 46659<!DOCTYPE target SYSTEM "osdata.dtd"> 46660<osdata type="processes"> 46661 <item> 46662 <column name="pid">1</column> 46663 <column name="user">root</column> 46664 <column name="command">/sbin/init</column> 46665 <column name="cores">1,2,3</column> 46666 </item> 46667</osdata> 46668@end smallexample 46669 46670Each item should include a column whose name is @samp{pid}. The value 46671of that column should identify the process on the target. The 46672@samp{user} and @samp{command} columns are optional, and will be 46673displayed by @value{GDBN}. The @samp{cores} column, if present, 46674should contain a comma-separated list of cores that this process 46675is running on. Target may provide additional columns, 46676which @value{GDBN} currently ignores. 46677 46678@node Trace File Format 46679@appendix Trace File Format 46680@cindex trace file format 46681 46682The trace file comes in three parts: a header, a textual description 46683section, and a trace frame section with binary data. 46684 46685The header has the form @code{\x7fTRACE0\n}. The first byte is 46686@code{0x7f} so as to indicate that the file contains binary data, 46687while the @code{0} is a version number that may have different values 46688in the future. 46689 46690The description section consists of multiple lines of @sc{ascii} text 46691separated by newline characters (@code{0xa}). The lines may include a 46692variety of optional descriptive or context-setting information, such 46693as tracepoint definitions or register set size. @value{GDBN} will 46694ignore any line that it does not recognize. An empty line marks the end 46695of this section. 46696 46697@table @code 46698@item R @var{size} 46699Specifies the size of a register block in bytes. This is equal to the 46700size of a @code{g} packet payload in the remote protocol. @var{size} 46701is an ascii decimal number. There should be only one such line in 46702a single trace file. 46703 46704@item status @var{status} 46705Trace status. @var{status} has the same format as a @code{qTStatus} 46706remote packet reply. There should be only one such line in a single trace 46707file. 46708 46709@item tp @var{payload} 46710Tracepoint definition. The @var{payload} has the same format as 46711@code{qTfP}/@code{qTsP} remote packet reply payload. A single tracepoint 46712may take multiple lines of definition, corresponding to the multiple 46713reply packets. 46714 46715@item tsv @var{payload} 46716Trace state variable definition. The @var{payload} has the same format as 46717@code{qTfV}/@code{qTsV} remote packet reply payload. A single variable 46718may take multiple lines of definition, corresponding to the multiple 46719reply packets. 46720 46721@item tdesc @var{payload} 46722Target description in XML format. The @var{payload} is a single line of 46723the XML file. All such lines should be concatenated together to get 46724the original XML file. This file is in the same format as @code{qXfer} 46725@code{features} payload, and corresponds to the main @code{target.xml} 46726file. Includes are not allowed. 46727 46728@end table 46729 46730The trace frame section consists of a number of consecutive frames. 46731Each frame begins with a two-byte tracepoint number, followed by a 46732four-byte size giving the amount of data in the frame. The data in 46733the frame consists of a number of blocks, each introduced by a 46734character indicating its type (at least register, memory, and trace 46735state variable). The data in this section is raw binary, not a 46736hexadecimal or other encoding; its endianness matches the target's 46737endianness. 46738 46739@c FIXME bi-arch may require endianness/arch info in description section 46740 46741@table @code 46742@item R @var{bytes} 46743Register block. The number and ordering of bytes matches that of a 46744@code{g} packet in the remote protocol. Note that these are the 46745actual bytes, in target order, not a hexadecimal encoding. 46746 46747@item M @var{address} @var{length} @var{bytes}... 46748Memory block. This is a contiguous block of memory, at the 8-byte 46749address @var{address}, with a 2-byte length @var{length}, followed by 46750@var{length} bytes. 46751 46752@item V @var{number} @var{value} 46753Trace state variable block. This records the 8-byte signed value 46754@var{value} of trace state variable numbered @var{number}. 46755 46756@end table 46757 46758Future enhancements of the trace file format may include additional types 46759of blocks. 46760 46761@node Index Section Format 46762@appendix @code{.gdb_index} section format 46763@cindex .gdb_index section format 46764@cindex index section format 46765 46766This section documents the index section that is created by @code{save 46767gdb-index} (@pxref{Index Files}). The index section is 46768DWARF-specific; some knowledge of DWARF is assumed in this 46769description. 46770 46771The mapped index file format is designed to be directly 46772@code{mmap}able on any architecture. In most cases, a datum is 46773represented using a little-endian 32-bit integer value, called an 46774@code{offset_type}. Big endian machines must byte-swap the values 46775before using them. Exceptions to this rule are noted. The data is 46776laid out such that alignment is always respected. 46777 46778A mapped index consists of several areas, laid out in order. 46779 46780@enumerate 46781@item 46782The file header. This is a sequence of values, of @code{offset_type} 46783unless otherwise noted: 46784 46785@enumerate 46786@item 46787The version number, currently 8. Versions 1, 2 and 3 are obsolete. 46788Version 4 uses a different hashing function from versions 5 and 6. 46789Version 6 includes symbols for inlined functions, whereas versions 4 46790and 5 do not. Version 7 adds attributes to the CU indices in the 46791symbol table. Version 8 specifies that symbols from DWARF type units 46792(@samp{DW_TAG_type_unit}) refer to the type unit's symbol table and not the 46793compilation unit (@samp{DW_TAG_comp_unit}) using the type. 46794 46795@value{GDBN} will only read version 4, 5, or 6 indices 46796by specifying @code{set use-deprecated-index-sections on}. 46797GDB has a workaround for potentially broken version 7 indices so it is 46798currently not flagged as deprecated. 46799 46800@item 46801The offset, from the start of the file, of the CU list. 46802 46803@item 46804The offset, from the start of the file, of the types CU list. Note 46805that this area can be empty, in which case this offset will be equal 46806to the next offset. 46807 46808@item 46809The offset, from the start of the file, of the address area. 46810 46811@item 46812The offset, from the start of the file, of the symbol table. 46813 46814@item 46815The offset, from the start of the file, of the constant pool. 46816@end enumerate 46817 46818@item 46819The CU list. This is a sequence of pairs of 64-bit little-endian 46820values, sorted by the CU offset. The first element in each pair is 46821the offset of a CU in the @code{.debug_info} section. The second 46822element in each pair is the length of that CU. References to a CU 46823elsewhere in the map are done using a CU index, which is just the 468240-based index into this table. Note that if there are type CUs, then 46825conceptually CUs and type CUs form a single list for the purposes of 46826CU indices. 46827 46828@item 46829The types CU list. This is a sequence of triplets of 64-bit 46830little-endian values. In a triplet, the first value is the CU offset, 46831the second value is the type offset in the CU, and the third value is 46832the type signature. The types CU list is not sorted. 46833 46834@item 46835The address area. The address area consists of a sequence of address 46836entries. Each address entry has three elements: 46837 46838@enumerate 46839@item 46840The low address. This is a 64-bit little-endian value. 46841 46842@item 46843The high address. This is a 64-bit little-endian value. Like 46844@code{DW_AT_high_pc}, the value is one byte beyond the end. 46845 46846@item 46847The CU index. This is an @code{offset_type} value. 46848@end enumerate 46849 46850@item 46851The symbol table. This is an open-addressed hash table. The size of 46852the hash table is always a power of 2. 46853 46854Each slot in the hash table consists of a pair of @code{offset_type} 46855values. The first value is the offset of the symbol's name in the 46856constant pool. The second value is the offset of the CU vector in the 46857constant pool. 46858 46859If both values are 0, then this slot in the hash table is empty. This 46860is ok because while 0 is a valid constant pool index, it cannot be a 46861valid index for both a string and a CU vector. 46862 46863The hash value for a table entry is computed by applying an 46864iterative hash function to the symbol's name. Starting with an 46865initial value of @code{r = 0}, each (unsigned) character @samp{c} in 46866the string is incorporated into the hash using the formula depending on the 46867index version: 46868 46869@table @asis 46870@item Version 4 46871The formula is @code{r = r * 67 + c - 113}. 46872 46873@item Versions 5 to 7 46874The formula is @code{r = r * 67 + tolower (c) - 113}. 46875@end table 46876 46877The terminating @samp{\0} is not incorporated into the hash. 46878 46879The step size used in the hash table is computed via 46880@code{((hash * 17) & (size - 1)) | 1}, where @samp{hash} is the hash 46881value, and @samp{size} is the size of the hash table. The step size 46882is used to find the next candidate slot when handling a hash 46883collision. 46884 46885The names of C@t{++} symbols in the hash table are canonicalized. We 46886don't currently have a simple description of the canonicalization 46887algorithm; if you intend to create new index sections, you must read 46888the code. 46889 46890@item 46891The constant pool. This is simply a bunch of bytes. It is organized 46892so that alignment is correct: CU vectors are stored first, followed by 46893strings. 46894 46895A CU vector in the constant pool is a sequence of @code{offset_type} 46896values. The first value is the number of CU indices in the vector. 46897Each subsequent value is the index and symbol attributes of a CU in 46898the CU list. This element in the hash table is used to indicate which 46899CUs define the symbol and how the symbol is used. 46900See below for the format of each CU index+attributes entry. 46901 46902A string in the constant pool is zero-terminated. 46903@end enumerate 46904 46905Attributes were added to CU index values in @code{.gdb_index} version 7. 46906If a symbol has multiple uses within a CU then there is one 46907CU index+attributes value for each use. 46908 46909The format of each CU index+attributes entry is as follows 46910(bit 0 = LSB): 46911 46912@table @asis 46913 46914@item Bits 0-23 46915This is the index of the CU in the CU list. 46916@item Bits 24-27 46917These bits are reserved for future purposes and must be zero. 46918@item Bits 28-30 46919The kind of the symbol in the CU. 46920 46921@table @asis 46922@item 0 46923This value is reserved and should not be used. 46924By reserving zero the full @code{offset_type} value is backwards compatible 46925with previous versions of the index. 46926@item 1 46927The symbol is a type. 46928@item 2 46929The symbol is a variable or an enum value. 46930@item 3 46931The symbol is a function. 46932@item 4 46933Any other kind of symbol. 46934@item 5,6,7 46935These values are reserved. 46936@end table 46937 46938@item Bit 31 46939This bit is zero if the value is global and one if it is static. 46940 46941The determination of whether a symbol is global or static is complicated. 46942The authorative reference is the file @file{dwarf2read.c} in 46943@value{GDBN} sources. 46944 46945@end table 46946 46947This pseudo-code describes the computation of a symbol's kind and 46948global/static attributes in the index. 46949 46950@smallexample 46951is_external = get_attribute (die, DW_AT_external); 46952language = get_attribute (cu_die, DW_AT_language); 46953switch (die->tag) 46954 @{ 46955 case DW_TAG_typedef: 46956 case DW_TAG_base_type: 46957 case DW_TAG_subrange_type: 46958 kind = TYPE; 46959 is_static = 1; 46960 break; 46961 case DW_TAG_enumerator: 46962 kind = VARIABLE; 46963 is_static = language != CPLUS; 46964 break; 46965 case DW_TAG_subprogram: 46966 kind = FUNCTION; 46967 is_static = ! (is_external || language == ADA); 46968 break; 46969 case DW_TAG_constant: 46970 kind = VARIABLE; 46971 is_static = ! is_external; 46972 break; 46973 case DW_TAG_variable: 46974 kind = VARIABLE; 46975 is_static = ! is_external; 46976 break; 46977 case DW_TAG_namespace: 46978 kind = TYPE; 46979 is_static = 0; 46980 break; 46981 case DW_TAG_class_type: 46982 case DW_TAG_interface_type: 46983 case DW_TAG_structure_type: 46984 case DW_TAG_union_type: 46985 case DW_TAG_enumeration_type: 46986 kind = TYPE; 46987 is_static = language != CPLUS; 46988 break; 46989 default: 46990 assert (0); 46991 @} 46992@end smallexample 46993 46994@node Man Pages 46995@appendix Manual pages 46996@cindex Man pages 46997 46998@menu 46999* gdb man:: The GNU Debugger man page 47000* gdbserver man:: Remote Server for the GNU Debugger man page 47001* gcore man:: Generate a core file of a running program 47002* gdbinit man:: gdbinit scripts 47003* gdb-add-index man:: Add index files to speed up GDB 47004@end menu 47005 47006@node gdb man 47007@heading gdb man 47008 47009@c man title gdb The GNU Debugger 47010 47011@c man begin SYNOPSIS gdb 47012gdb [@option{-help}] [@option{-nh}] [@option{-nx}] [@option{-q}] 47013[@option{-batch}] [@option{-cd=}@var{dir}] [@option{-f}] 47014[@option{-b}@w{ }@var{bps}] 47015 [@option{-tty=}@var{dev}] [@option{-s} @var{symfile}] 47016[@option{-e}@w{ }@var{prog}] [@option{-se}@w{ }@var{prog}] 47017[@option{-c}@w{ }@var{core}] [@option{-p}@w{ }@var{procID}] 47018 [@option{-x}@w{ }@var{cmds}] [@option{-d}@w{ }@var{dir}] 47019[@var{prog}|@var{prog} @var{procID}|@var{prog} @var{core}] 47020@c man end 47021 47022@c man begin DESCRIPTION gdb 47023The purpose of a debugger such as @value{GDBN} is to allow you to see what is 47024going on ``inside'' another program while it executes -- or what another 47025program was doing at the moment it crashed. 47026 47027@value{GDBN} can do four main kinds of things (plus other things in support of 47028these) to help you catch bugs in the act: 47029 47030@itemize @bullet 47031@item 47032Start your program, specifying anything that might affect its behavior. 47033 47034@item 47035Make your program stop on specified conditions. 47036 47037@item 47038Examine what has happened, when your program has stopped. 47039 47040@item 47041Change things in your program, so you can experiment with correcting the 47042effects of one bug and go on to learn about another. 47043@end itemize 47044 47045You can use @value{GDBN} to debug programs written in C, C@t{++}, Fortran and 47046Modula-2. 47047 47048@value{GDBN} is invoked with the shell command @code{gdb}. Once started, it reads 47049commands from the terminal until you tell it to exit with the @value{GDBN} 47050command @code{quit}. You can get online help from @value{GDBN} itself 47051by using the command @code{help}. 47052 47053You can run @code{gdb} with no arguments or options; but the most 47054usual way to start @value{GDBN} is with one argument or two, specifying an 47055executable program as the argument: 47056 47057@smallexample 47058gdb program 47059@end smallexample 47060 47061You can also start with both an executable program and a core file specified: 47062 47063@smallexample 47064gdb program core 47065@end smallexample 47066 47067You can, instead, specify a process ID as a second argument or use option 47068@code{-p}, if you want to debug a running process: 47069 47070@smallexample 47071gdb program 1234 47072gdb -p 1234 47073@end smallexample 47074 47075@noindent 47076would attach @value{GDBN} to process @code{1234}. With option @option{-p} you 47077can omit the @var{program} filename. 47078 47079Here are some of the most frequently needed @value{GDBN} commands: 47080 47081@c pod2man highlights the right hand side of the @item lines. 47082@table @env 47083@item break [@var{file}:]@var{function} 47084Set a breakpoint at @var{function} (in @var{file}). 47085 47086@item run [@var{arglist}] 47087Start your program (with @var{arglist}, if specified). 47088 47089@item bt 47090Backtrace: display the program stack. 47091 47092@item print @var{expr} 47093Display the value of an expression. 47094 47095@item c 47096Continue running your program (after stopping, e.g.@: at a breakpoint). 47097 47098@item next 47099Execute next program line (after stopping); step @emph{over} any 47100function calls in the line. 47101 47102@item edit [@var{file}:]@var{function} 47103look at the program line where it is presently stopped. 47104 47105@item list [@var{file}:]@var{function} 47106type the text of the program in the vicinity of where it is presently stopped. 47107 47108@item step 47109Execute next program line (after stopping); step @emph{into} any 47110function calls in the line. 47111 47112@item help [@var{name}] 47113Show information about @value{GDBN} command @var{name}, or general information 47114about using @value{GDBN}. 47115 47116@item quit 47117Exit from @value{GDBN}. 47118@end table 47119 47120@ifset man 47121For full details on @value{GDBN}, 47122see @cite{Using GDB: A Guide to the GNU Source-Level Debugger}, 47123by Richard M. Stallman and Roland H. Pesch. The same text is available online 47124as the @code{gdb} entry in the @code{info} program. 47125@end ifset 47126@c man end 47127 47128@c man begin OPTIONS gdb 47129Any arguments other than options specify an executable 47130file and core file (or process ID); that is, the first argument 47131encountered with no 47132associated option flag is equivalent to a @option{-se} option, and the second, 47133if any, is equivalent to a @option{-c} option if it's the name of a file. 47134Many options have 47135both long and short forms; both are shown here. The long forms are also 47136recognized if you truncate them, so long as enough of the option is 47137present to be unambiguous. (If you prefer, you can flag option 47138arguments with @option{+} rather than @option{-}, though we illustrate the 47139more usual convention.) 47140 47141All the options and command line arguments you give are processed 47142in sequential order. The order makes a difference when the @option{-x} 47143option is used. 47144 47145@table @env 47146@item -help 47147@itemx -h 47148List all options, with brief explanations. 47149 47150@item -symbols=@var{file} 47151@itemx -s @var{file} 47152Read symbol table from file @var{file}. 47153 47154@item -write 47155Enable writing into executable and core files. 47156 47157@item -exec=@var{file} 47158@itemx -e @var{file} 47159Use file @var{file} as the executable file to execute when 47160appropriate, and for examining pure data in conjunction with a core 47161dump. 47162 47163@item -se=@var{file} 47164Read symbol table from file @var{file} and use it as the executable 47165file. 47166 47167@item -core=@var{file} 47168@itemx -c @var{file} 47169Use file @var{file} as a core dump to examine. 47170 47171@item -command=@var{file} 47172@itemx -x @var{file} 47173Execute @value{GDBN} commands from file @var{file}. 47174 47175@item -ex @var{command} 47176Execute given @value{GDBN} @var{command}. 47177 47178@item -directory=@var{directory} 47179@itemx -d @var{directory} 47180Add @var{directory} to the path to search for source files. 47181 47182@item -nh 47183Do not execute commands from @file{~/.config/gdb/gdbinit}, 47184@file{~/.gdbinit}, @file{~/.config/gdb/gdbearlyinit}, or 47185@file{~/.gdbearlyinit} 47186 47187@item -nx 47188@itemx -n 47189Do not execute commands from any @file{.gdbinit} or 47190@file{.gdbearlyinit} initialization files. 47191 47192@item -quiet 47193@itemx -q 47194``Quiet''. Do not print the introductory and copyright messages. These 47195messages are also suppressed in batch mode. 47196 47197@item -batch 47198Run in batch mode. Exit with status @code{0} after processing all the command 47199files specified with @option{-x} (and @file{.gdbinit}, if not inhibited). 47200Exit with nonzero status if an error occurs in executing the @value{GDBN} 47201commands in the command files. 47202 47203Batch mode may be useful for running @value{GDBN} as a filter, for example to 47204download and run a program on another computer; in order to make this 47205more useful, the message 47206 47207@smallexample 47208Program exited normally. 47209@end smallexample 47210 47211@noindent 47212(which is ordinarily issued whenever a program running under @value{GDBN} control 47213terminates) is not issued when running in batch mode. 47214 47215@item -cd=@var{directory} 47216Run @value{GDBN} using @var{directory} as its working directory, 47217instead of the current directory. 47218 47219@item -fullname 47220@itemx -f 47221Emacs sets this option when it runs @value{GDBN} as a subprocess. It tells 47222@value{GDBN} to output the full file name and line number in a standard, 47223recognizable fashion each time a stack frame is displayed (which 47224includes each time the program stops). This recognizable format looks 47225like two @samp{\032} characters, followed by the file name, line number 47226and character position separated by colons, and a newline. The 47227Emacs-to-@value{GDBN} interface program uses the two @samp{\032} 47228characters as a signal to display the source code for the frame. 47229 47230@item -b @var{bps} 47231Set the line speed (baud rate or bits per second) of any serial 47232interface used by @value{GDBN} for remote debugging. 47233 47234@item -tty=@var{device} 47235Run using @var{device} for your program's standard input and output. 47236@end table 47237@c man end 47238 47239@c man begin SEEALSO gdb 47240@ifset man 47241The full documentation for @value{GDBN} is maintained as a Texinfo manual. 47242If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo 47243documentation are properly installed at your site, the command 47244 47245@smallexample 47246info gdb 47247@end smallexample 47248 47249@noindent 47250should give you access to the complete manual. 47251 47252@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, 47253Richard M. Stallman and Roland H. Pesch, July 1991. 47254@end ifset 47255@c man end 47256 47257@node gdbserver man 47258@heading gdbserver man 47259 47260@c man title gdbserver Remote Server for the GNU Debugger 47261@format 47262@c man begin SYNOPSIS gdbserver 47263gdbserver @var{comm} @var{prog} [@var{args}@dots{}] 47264 47265gdbserver --attach @var{comm} @var{pid} 47266 47267gdbserver --multi @var{comm} 47268@c man end 47269@end format 47270 47271@c man begin DESCRIPTION gdbserver 47272@command{gdbserver} is a program that allows you to run @value{GDBN} on a different machine 47273than the one which is running the program being debugged. 47274 47275@ifclear man 47276@subheading Usage (server (target) side) 47277@end ifclear 47278@ifset man 47279Usage (server (target) side): 47280@end ifset 47281 47282First, you need to have a copy of the program you want to debug put onto 47283the target system. The program can be stripped to save space if needed, as 47284@command{gdbserver} doesn't care about symbols. All symbol handling is taken care of by 47285the @value{GDBN} running on the host system. 47286 47287To use the server, you log on to the target system, and run the @command{gdbserver} 47288program. You must tell it (a) how to communicate with @value{GDBN}, (b) the name of 47289your program, and (c) its arguments. The general syntax is: 47290 47291@smallexample 47292target> gdbserver @var{comm} @var{program} [@var{args} ...] 47293@end smallexample 47294 47295For example, using a serial port, you might say: 47296 47297@smallexample 47298@ifset man 47299@c @file would wrap it as F</dev/com1>. 47300target> gdbserver /dev/com1 emacs foo.txt 47301@end ifset 47302@ifclear man 47303target> gdbserver @file{/dev/com1} emacs foo.txt 47304@end ifclear 47305@end smallexample 47306 47307This tells @command{gdbserver} to debug emacs with an argument of foo.txt, and 47308to communicate with @value{GDBN} via @file{/dev/com1}. @command{gdbserver} now 47309waits patiently for the host @value{GDBN} to communicate with it. 47310 47311To use a TCP connection, you could say: 47312 47313@smallexample 47314target> gdbserver host:2345 emacs foo.txt 47315@end smallexample 47316 47317This says pretty much the same thing as the last example, except that we are 47318going to communicate with the @code{host} @value{GDBN} via TCP. The @code{host:2345} argument means 47319that we are expecting to see a TCP connection from @code{host} to local TCP port 473202345. (Currently, the @code{host} part is ignored.) You can choose any number you 47321want for the port number as long as it does not conflict with any existing TCP 47322ports on the target system. This same port number must be used in the host 47323@value{GDBN}s @code{target remote} command, which will be described shortly. Note that if 47324you chose a port number that conflicts with another service, @command{gdbserver} will 47325print an error message and exit. 47326 47327@command{gdbserver} can also attach to running programs. 47328This is accomplished via the @option{--attach} argument. The syntax is: 47329 47330@smallexample 47331target> gdbserver --attach @var{comm} @var{pid} 47332@end smallexample 47333 47334@var{pid} is the process ID of a currently running process. It isn't 47335necessary to point @command{gdbserver} at a binary for the running process. 47336 47337To start @code{gdbserver} without supplying an initial command to run 47338or process ID to attach, use the @option{--multi} command line option. 47339In such case you should connect using @kbd{target extended-remote} to start 47340the program you want to debug. 47341 47342@smallexample 47343target> gdbserver --multi @var{comm} 47344@end smallexample 47345 47346@ifclear man 47347@subheading Usage (host side) 47348@end ifclear 47349@ifset man 47350Usage (host side): 47351@end ifset 47352 47353You need an unstripped copy of the target program on your host system, since 47354@value{GDBN} needs to examine its symbol tables and such. Start up @value{GDBN} as you normally 47355would, with the target program as the first argument. (You may need to use the 47356@option{--baud} option if the serial line is running at anything except 9600 baud.) 47357That is @code{gdb TARGET-PROG}, or @code{gdb --baud BAUD TARGET-PROG}. After that, the only 47358new command you need to know about is @code{target remote} 47359(or @code{target extended-remote}). Its argument is either 47360a device name (usually a serial device, like @file{/dev/ttyb}), or a @code{HOST:PORT} 47361descriptor. For example: 47362 47363@smallexample 47364@ifset man 47365@c @file would wrap it as F</dev/ttyb>. 47366(gdb) target remote /dev/ttyb 47367@end ifset 47368@ifclear man 47369(gdb) target remote @file{/dev/ttyb} 47370@end ifclear 47371@end smallexample 47372 47373@noindent 47374communicates with the server via serial line @file{/dev/ttyb}, and: 47375 47376@smallexample 47377(gdb) target remote the-target:2345 47378@end smallexample 47379 47380@noindent 47381communicates via a TCP connection to port 2345 on host `the-target', where 47382you previously started up @command{gdbserver} with the same port number. Note that for 47383TCP connections, you must start up @command{gdbserver} prior to using the `target remote' 47384command, otherwise you may get an error that looks something like 47385`Connection refused'. 47386 47387@command{gdbserver} can also debug multiple inferiors at once, 47388described in 47389@ifset man 47390the @value{GDBN} manual in node @code{Inferiors Connections and Programs} 47391-- shell command @code{info -f gdb -n 'Inferiors Connections and Programs'}. 47392@end ifset 47393@ifclear man 47394@ref{Inferiors Connections and Programs}. 47395@end ifclear 47396In such case use the @code{extended-remote} @value{GDBN} command variant: 47397 47398@smallexample 47399(gdb) target extended-remote the-target:2345 47400@end smallexample 47401 47402The @command{gdbserver} option @option{--multi} may or may not be used in such 47403case. 47404@c man end 47405 47406@c man begin OPTIONS gdbserver 47407There are three different modes for invoking @command{gdbserver}: 47408 47409@itemize @bullet 47410 47411@item 47412Debug a specific program specified by its program name: 47413 47414@smallexample 47415gdbserver @var{comm} @var{prog} [@var{args}@dots{}] 47416@end smallexample 47417 47418The @var{comm} parameter specifies how should the server communicate 47419with @value{GDBN}; it is either a device name (to use a serial line), 47420a TCP port number (@code{:1234}), or @code{-} or @code{stdio} to use 47421stdin/stdout of @code{gdbserver}. Specify the name of the program to 47422debug in @var{prog}. Any remaining arguments will be passed to the 47423program verbatim. When the program exits, @value{GDBN} will close the 47424connection, and @code{gdbserver} will exit. 47425 47426@item 47427Debug a specific program by specifying the process ID of a running 47428program: 47429 47430@smallexample 47431gdbserver --attach @var{comm} @var{pid} 47432@end smallexample 47433 47434The @var{comm} parameter is as described above. Supply the process ID 47435of a running program in @var{pid}; @value{GDBN} will do everything 47436else. Like with the previous mode, when the process @var{pid} exits, 47437@value{GDBN} will close the connection, and @code{gdbserver} will exit. 47438 47439@item 47440Multi-process mode -- debug more than one program/process: 47441 47442@smallexample 47443gdbserver --multi @var{comm} 47444@end smallexample 47445 47446In this mode, @value{GDBN} can instruct @command{gdbserver} which 47447command(s) to run. Unlike the other 2 modes, @value{GDBN} will not 47448close the connection when a process being debugged exits, so you can 47449debug several processes in the same session. 47450@end itemize 47451 47452In each of the modes you may specify these options: 47453 47454@table @env 47455 47456@item --help 47457List all options, with brief explanations. 47458 47459@item --version 47460This option causes @command{gdbserver} to print its version number and exit. 47461 47462@item --attach 47463@command{gdbserver} will attach to a running program. The syntax is: 47464 47465@smallexample 47466target> gdbserver --attach @var{comm} @var{pid} 47467@end smallexample 47468 47469@var{pid} is the process ID of a currently running process. It isn't 47470necessary to point @command{gdbserver} at a binary for the running process. 47471 47472@item --multi 47473To start @code{gdbserver} without supplying an initial command to run 47474or process ID to attach, use this command line option. 47475Then you can connect using @kbd{target extended-remote} and start 47476the program you want to debug. The syntax is: 47477 47478@smallexample 47479target> gdbserver --multi @var{comm} 47480@end smallexample 47481 47482@item --debug 47483Instruct @code{gdbserver} to display extra status information about the debugging 47484process. 47485This option is intended for @code{gdbserver} development and for bug reports to 47486the developers. 47487 47488@item --remote-debug 47489Instruct @code{gdbserver} to display remote protocol debug output. 47490This option is intended for @code{gdbserver} development and for bug reports to 47491the developers. 47492 47493@item --debug-file=@var{filename} 47494Instruct @code{gdbserver} to send any debug output to the given @var{filename}. 47495This option is intended for @code{gdbserver} development and for bug reports to 47496the developers. 47497 47498@item --debug-format=option1@r{[},option2,...@r{]} 47499Instruct @code{gdbserver} to include extra information in each line 47500of debugging output. 47501@xref{Other Command-Line Arguments for gdbserver}. 47502 47503@item --wrapper 47504Specify a wrapper to launch programs 47505for debugging. The option should be followed by the name of the 47506wrapper, then any command-line arguments to pass to the wrapper, then 47507@kbd{--} indicating the end of the wrapper arguments. 47508 47509@item --once 47510By default, @command{gdbserver} keeps the listening TCP port open, so that 47511additional connections are possible. However, if you start @code{gdbserver} 47512with the @option{--once} option, it will stop listening for any further 47513connection attempts after connecting to the first @value{GDBN} session. 47514 47515@c --disable-packet is not documented for users. 47516 47517@c --disable-randomization and --no-disable-randomization are superseded by 47518@c QDisableRandomization. 47519 47520@end table 47521@c man end 47522 47523@c man begin SEEALSO gdbserver 47524@ifset man 47525The full documentation for @value{GDBN} is maintained as a Texinfo manual. 47526If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo 47527documentation are properly installed at your site, the command 47528 47529@smallexample 47530info gdb 47531@end smallexample 47532 47533should give you access to the complete manual. 47534 47535@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, 47536Richard M. Stallman and Roland H. Pesch, July 1991. 47537@end ifset 47538@c man end 47539 47540@node gcore man 47541@heading gcore 47542 47543@c man title gcore Generate a core file of a running program 47544 47545@format 47546@c man begin SYNOPSIS gcore 47547gcore [-a] [-o @var{prefix}] @var{pid1} [@var{pid2}...@var{pidN}] 47548@c man end 47549@end format 47550 47551@c man begin DESCRIPTION gcore 47552Generate core dumps of one or more running programs with process IDs 47553@var{pid1}, @var{pid2}, etc. A core file produced by @command{gcore} 47554is equivalent to one produced by the kernel when the process crashes 47555(and when @kbd{ulimit -c} was used to set up an appropriate core dump 47556limit). However, unlike after a crash, after @command{gcore} finishes 47557its job the program remains running without any change. 47558@c man end 47559 47560@c man begin OPTIONS gcore 47561@table @env 47562@item -a 47563Dump all memory mappings. The actual effect of this option depends on 47564the Operating System. On @sc{gnu}/Linux, it will disable 47565@code{use-coredump-filter} (@pxref{set use-coredump-filter}) and 47566enable @code{dump-excluded-mappings} (@pxref{set 47567dump-excluded-mappings}). 47568 47569@item -o @var{prefix} 47570The optional argument @var{prefix} specifies the prefix to be used 47571when composing the file names of the core dumps. The file name is 47572composed as @file{@var{prefix}.@var{pid}}, where @var{pid} is the 47573process ID of the running program being analyzed by @command{gcore}. 47574If not specified, @var{prefix} defaults to @var{gcore}. 47575@end table 47576@c man end 47577 47578@c man begin SEEALSO gcore 47579@ifset man 47580The full documentation for @value{GDBN} is maintained as a Texinfo manual. 47581If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo 47582documentation are properly installed at your site, the command 47583 47584@smallexample 47585info gdb 47586@end smallexample 47587 47588@noindent 47589should give you access to the complete manual. 47590 47591@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, 47592Richard M. Stallman and Roland H. Pesch, July 1991. 47593@end ifset 47594@c man end 47595 47596@node gdbinit man 47597@heading gdbinit 47598 47599@c man title gdbinit GDB initialization scripts 47600 47601@format 47602@c man begin SYNOPSIS gdbinit 47603@ifset SYSTEM_GDBINIT 47604@value{SYSTEM_GDBINIT} 47605@end ifset 47606 47607@ifset SYSTEM_GDBINIT_DIR 47608@value{SYSTEM_GDBINIT_DIR}/* 47609@end ifset 47610 47611~/.config/gdb/gdbinit 47612 47613~/.gdbinit 47614 47615./.gdbinit 47616@c man end 47617@end format 47618 47619@c man begin DESCRIPTION gdbinit 47620These files contain @value{GDBN} commands to automatically execute during 47621@value{GDBN} startup. The lines of contents are canned sequences of commands, 47622described in 47623@ifset man 47624the @value{GDBN} manual in node @code{Sequences} 47625-- shell command @code{info -f gdb -n Sequences}. 47626@end ifset 47627@ifclear man 47628@ref{Sequences}. 47629@end ifclear 47630 47631Please read more in 47632@ifset man 47633the @value{GDBN} manual in node @code{Startup} 47634-- shell command @code{info -f gdb -n Startup}. 47635@end ifset 47636@ifclear man 47637@ref{Startup}. 47638@end ifclear 47639 47640@table @env 47641@ifset SYSTEM_GDBINIT 47642@item @value{SYSTEM_GDBINIT} 47643@end ifset 47644@ifclear SYSTEM_GDBINIT 47645@item (not enabled with @code{--with-system-gdbinit} during compilation) 47646@end ifclear 47647System-wide initialization file. It is executed unless user specified 47648@value{GDBN} option @code{-nx} or @code{-n}. 47649See more in 47650@ifset man 47651the @value{GDBN} manual in node @code{System-wide configuration} 47652-- shell command @code{info -f gdb -n 'System-wide configuration'}. 47653@end ifset 47654@ifset SYSTEM_GDBINIT_DIR 47655@item @value{SYSTEM_GDBINIT_DIR} 47656@end ifset 47657@ifclear SYSTEM_GDBINIT_DIR 47658@item (not enabled with @code{--with-system-gdbinit-dir} during compilation) 47659@end ifclear 47660System-wide initialization directory. All files in this directory are 47661executed on startup unless user specified @value{GDBN} option @code{-nx} or 47662@code{-n}, as long as they have a recognized file extension. 47663See more in 47664@ifset man 47665the @value{GDBN} manual in node @code{System-wide configuration} 47666-- shell command @code{info -f gdb -n 'System-wide configuration'}. 47667@end ifset 47668@ifclear man 47669@ref{System-wide configuration}. 47670@end ifclear 47671 47672@item @file{~/.config/gdb/gdbinit} or @file{~/.gdbinit} 47673User initialization file. It is executed unless user specified 47674@value{GDBN} options @code{-nx}, @code{-n} or @code{-nh}. 47675 47676@item @file{.gdbinit} 47677Initialization file for current directory. It may need to be enabled with 47678@value{GDBN} security command @code{set auto-load local-gdbinit}. 47679See more in 47680@ifset man 47681the @value{GDBN} manual in node @code{Init File in the Current Directory} 47682-- shell command @code{info -f gdb -n 'Init File in the Current Directory'}. 47683@end ifset 47684@ifclear man 47685@ref{Init File in the Current Directory}. 47686@end ifclear 47687@end table 47688@c man end 47689 47690@c man begin SEEALSO gdbinit 47691@ifset man 47692gdb(1), @code{info -f gdb -n Startup} 47693 47694The full documentation for @value{GDBN} is maintained as a Texinfo manual. 47695If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo 47696documentation are properly installed at your site, the command 47697 47698@smallexample 47699info gdb 47700@end smallexample 47701 47702should give you access to the complete manual. 47703 47704@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, 47705Richard M. Stallman and Roland H. Pesch, July 1991. 47706@end ifset 47707@c man end 47708 47709@node gdb-add-index man 47710@heading gdb-add-index 47711@pindex gdb-add-index 47712@anchor{gdb-add-index} 47713 47714@c man title gdb-add-index Add index files to speed up GDB 47715 47716@c man begin SYNOPSIS gdb-add-index 47717gdb-add-index @var{filename} 47718@c man end 47719 47720@c man begin DESCRIPTION gdb-add-index 47721When @value{GDBN} finds a symbol file, it scans the symbols in the 47722file in order to construct an internal symbol table. This lets most 47723@value{GDBN} operations work quickly--at the cost of a delay early on. 47724For large programs, this delay can be quite lengthy, so @value{GDBN} 47725provides a way to build an index, which speeds up startup. 47726 47727To determine whether a file contains such an index, use the command 47728@kbd{readelf -S filename}: the index is stored in a section named 47729@code{.gdb_index}. The index file can only be produced on systems 47730which use ELF binaries and DWARF debug information (i.e., sections 47731named @code{.debug_*}). 47732 47733@command{gdb-add-index} uses @value{GDBN} and @command{objdump} found 47734in the @env{PATH} environment variable. If you want to use different 47735versions of these programs, you can specify them through the 47736@env{GDB} and @env{OBJDUMP} environment variables. 47737 47738See more in 47739@ifset man 47740the @value{GDBN} manual in node @code{Index Files} 47741-- shell command @kbd{info -f gdb -n "Index Files"}. 47742@end ifset 47743@ifclear man 47744@ref{Index Files}. 47745@end ifclear 47746@c man end 47747 47748@c man begin SEEALSO gdb-add-index 47749@ifset man 47750The full documentation for @value{GDBN} is maintained as a Texinfo manual. 47751If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo 47752documentation are properly installed at your site, the command 47753 47754@smallexample 47755info gdb 47756@end smallexample 47757 47758should give you access to the complete manual. 47759 47760@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, 47761Richard M. Stallman and Roland H. Pesch, July 1991. 47762@end ifset 47763@c man end 47764 47765@include gpl.texi 47766 47767@node GNU Free Documentation License 47768@appendix GNU Free Documentation License 47769@include fdl.texi 47770 47771@node Concept Index 47772@unnumbered Concept Index 47773 47774@printindex cp 47775 47776@node Command and Variable Index 47777@unnumbered Command, Variable, and Function Index 47778 47779@printindex fn 47780 47781@tex 47782% I think something like @@colophon should be in texinfo. In the 47783% meantime: 47784\long\def\colophon{\hbox to0pt{}\vfill 47785\centerline{The body of this manual is set in} 47786\centerline{\fontname\tenrm,} 47787\centerline{with headings in {\bf\fontname\tenbf}} 47788\centerline{and examples in {\tt\fontname\tentt}.} 47789\centerline{{\it\fontname\tenit\/},} 47790\centerline{{\bf\fontname\tenbf}, and} 47791\centerline{{\sl\fontname\tensl\/}} 47792\centerline{are used for emphasis.}\vfill} 47793\page\colophon 47794% Blame: doc@@cygnus.com, 1991. 47795@end tex 47796 47797@bye 47798