1\input texinfo @c -*-texinfo-*- 2@c Copyright (C) 1988--2024 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-2024 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-2024 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* Debugger Adapter Protocol:: The Debugger Adapter Protocol. 163* JIT Interface:: Using the JIT debugging interface. 164* In-Process Agent:: In-Process Agent 165 166* GDB Bugs:: Reporting bugs in @value{GDBN} 167 168@ifset SYSTEM_READLINE 169* Command Line Editing: (rluserman). Command Line Editing 170* Using History Interactively: (history). Using History Interactively 171@end ifset 172@ifclear SYSTEM_READLINE 173* Command Line Editing:: Command Line Editing 174* Using History Interactively:: Using History Interactively 175@end ifclear 176* In Memoriam:: In Memoriam 177* Formatting Documentation:: How to format and print @value{GDBN} documentation 178* Installing GDB:: Installing @value{GDBN} 179* Maintenance Commands:: Maintenance Commands 180* Remote Protocol:: GDB Remote Serial Protocol 181* Agent Expressions:: The @value{GDBN} Agent Expression Mechanism 182* Target Descriptions:: How targets can describe themselves to 183 @value{GDBN} 184* Operating System Information:: Getting additional information from 185 the operating system 186* Trace File Format:: @value{GDBN} trace file format 187* Index Section Format:: .gdb_index section format 188* Debuginfod:: Download debugging resources with @code{debuginfod} 189* Man Pages:: Manual pages 190* Copying:: GNU General Public License says 191 how you can copy and share @value{GDBN} 192* GNU Free Documentation License:: The license for this documentation 193* Concept Index:: Index of @value{GDBN} concepts 194* Command and Variable Index:: Index of @value{GDBN} commands, variables, 195 functions, and Python data types 196@end menu 197 198@end ifnottex 199 200@contents 201 202@node Summary 203@unnumbered Summary of @value{GDBN} 204 205The purpose of a debugger such as @value{GDBN} is to allow you to see what is 206going on ``inside'' another program while it executes---or what another 207program was doing at the moment it crashed. 208 209@value{GDBN} can do four main kinds of things (plus other things in support of 210these) to help you catch bugs in the act: 211 212@itemize @bullet 213@item 214Start your program, specifying anything that might affect its behavior. 215 216@item 217Make your program stop on specified conditions. 218 219@item 220Examine what has happened, when your program has stopped. 221 222@item 223Change things in your program, so you can experiment with correcting the 224effects of one bug and go on to learn about another. 225@end itemize 226 227You can use @value{GDBN} to debug programs written in C and C@t{++}. 228For more information, see @ref{Supported Languages,,Supported Languages}. 229For more information, see @ref{C,,C and C++}. 230 231Support for D is partial. For information on D, see 232@ref{D,,D}. 233 234@cindex Modula-2 235Support for Modula-2 is partial. For information on Modula-2, see 236@ref{Modula-2,,Modula-2}. 237 238Support for OpenCL C is partial. For information on OpenCL C, see 239@ref{OpenCL C,,OpenCL C}. 240 241@cindex Pascal 242Debugging Pascal programs which use sets, subranges, file variables, or 243nested functions does not currently work. @value{GDBN} does not support 244entering expressions, printing values, or similar features using Pascal 245syntax. 246 247@cindex Fortran 248@value{GDBN} can be used to debug programs written in Fortran, although 249it may be necessary to refer to some variables with a trailing 250underscore. 251 252@value{GDBN} can be used to debug programs written in Objective-C, 253using either the Apple/NeXT or the GNU Objective-C runtime. 254 255@menu 256* Free Software:: Freely redistributable software 257* Free Documentation:: Free Software Needs Free Documentation 258* Contributors:: Contributors to GDB 259@end menu 260 261@node Free Software 262@unnumberedsec Free Software 263 264@value{GDBN} is @dfn{free software}, protected by the @sc{gnu} 265General Public License 266(GPL). The GPL gives you the freedom to copy or adapt a licensed 267program---but every person getting a copy also gets with it the 268freedom to modify that copy (which means that they must get access to 269the source code), and the freedom to distribute further copies. 270Typical software companies use copyrights to limit your freedoms; the 271Free Software Foundation uses the GPL to preserve these freedoms. 272 273Fundamentally, the General Public License is a license which says that 274you have these freedoms and that you cannot take these freedoms away 275from anyone else. 276 277@node Free Documentation 278@unnumberedsec Free Software Needs Free Documentation 279 280The biggest deficiency in the free software community today is not in 281the software---it is the lack of good free documentation that we can 282include with the free software. Many of our most important 283programs do not come with free reference manuals and free introductory 284texts. Documentation is an essential part of any software package; 285when an important free software package does not come with a free 286manual and a free tutorial, that is a major gap. We have many such 287gaps today. 288 289Consider Perl, for instance. The tutorial manuals that people 290normally use are non-free. How did this come about? Because the 291authors of those manuals published them with restrictive terms---no 292copying, no modification, source files not available---which exclude 293them from the free software world. 294 295That wasn't the first time this sort of thing happened, and it was far 296from the last. Many times we have heard a GNU user eagerly describe a 297manual that he is writing, his intended contribution to the community, 298only to learn that he had ruined everything by signing a publication 299contract to make it non-free. 300 301Free documentation, like free software, is a matter of freedom, not 302price. The problem with the non-free manual is not that publishers 303charge a price for printed copies---that in itself is fine. (The Free 304Software Foundation sells printed copies of manuals, too.) The 305problem is the restrictions on the use of the manual. Free manuals 306are available in source code form, and give you permission to copy and 307modify. Non-free manuals do not allow this. 308 309The criteria of freedom for a free manual are roughly the same as for 310free software. Redistribution (including the normal kinds of 311commercial redistribution) must be permitted, so that the manual can 312accompany every copy of the program, both on-line and on paper. 313 314Permission for modification of the technical content is crucial too. 315When people modify the software, adding or changing features, if they 316are conscientious they will change the manual too---so they can 317provide accurate and clear documentation for the modified program. A 318manual that leaves you no choice but to write a new manual to document 319a changed version of the program is not really available to our 320community. 321 322Some kinds of limits on the way modification is handled are 323acceptable. For example, requirements to preserve the original 324author's copyright notice, the distribution terms, or the list of 325authors, are ok. It is also no problem to require modified versions 326to include notice that they were modified. Even entire sections that 327may not be deleted or changed are acceptable, as long as they deal 328with nontechnical topics (like this one). These kinds of restrictions 329are acceptable because they don't obstruct the community's normal use 330of the manual. 331 332However, it must be possible to modify all the @emph{technical} 333content of the manual, and then distribute the result in all the usual 334media, through all the usual channels. Otherwise, the restrictions 335obstruct the use of the manual, it is not free, and we need another 336manual to replace it. 337 338Please spread the word about this issue. Our community continues to 339lose manuals to proprietary publishing. If we spread the word that 340free software needs free reference manuals and free tutorials, perhaps 341the next person who wants to contribute by writing documentation will 342realize, before it is too late, that only free manuals contribute to 343the free software community. 344 345If you are writing documentation, please insist on publishing it under 346the GNU Free Documentation License or another free documentation 347license. Remember that this decision requires your approval---you 348don't have to let the publisher decide. Some commercial publishers 349will use a free license if you insist, but they will not propose the 350option; it is up to you to raise the issue and say firmly that this is 351what you want. If the publisher you are dealing with refuses, please 352try other publishers. If you're not sure whether a proposed license 353is free, write to @email{licensing@@gnu.org}. 354 355You can encourage commercial publishers to sell more free, copylefted 356manuals and tutorials by buying them, and particularly by buying 357copies from the publishers that paid for their writing or for major 358improvements. Meanwhile, try to avoid buying non-free documentation 359at all. Check the distribution terms of a manual before you buy it, 360and insist that whoever seeks your business must respect your freedom. 361Check the history of the book, and try to reward the publishers that 362have paid or pay the authors to work on it. 363 364The Free Software Foundation maintains a list of free documentation 365published by other publishers, at 366@url{http://www.fsf.org/doc/other-free-books.html}. 367 368@node Contributors 369@unnumberedsec Contributors to @value{GDBN} 370 371Richard Stallman was the original author of @value{GDBN}, and of many 372other @sc{gnu} programs. Many others have contributed to its 373development. This section attempts to credit major contributors. One 374of the virtues of free software is that everyone is free to contribute 375to it; with regret, we cannot actually acknowledge everyone here. The 376file @file{ChangeLog} in the @value{GDBN} distribution approximates a 377blow-by-blow account. 378 379Changes much prior to version 2.0 are lost in the mists of time. 380 381@quotation 382@emph{Plea:} Additions to this section are particularly welcome. If you 383or your friends (or enemies, to be evenhanded) have been unfairly 384omitted from this list, we would like to add your names! 385@end quotation 386 387So that they may not regard their many labors as thankless, we 388particularly thank those who shepherded @value{GDBN} through major 389releases: 390Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); 391Jim Blandy (release 4.18); 392Jason Molenda (release 4.17); 393Stan Shebs (release 4.14); 394Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9); 395Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4); 396John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); 397Jim Kingdon (releases 3.5, 3.4, and 3.3); 398and Randy Smith (releases 3.2, 3.1, and 3.0). 399 400Richard Stallman, assisted at various times by Peter TerMaat, Chris 401Hanson, and Richard Mlynarik, handled releases through 2.8. 402 403Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support 404in @value{GDBN}, with significant additional contributions from Per 405Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++} 406demangler. Early work on C@t{++} was by Peter TerMaat (who also did 407much general update work leading to release 3.0). 408 409@value{GDBN} uses the BFD subroutine library to examine multiple 410object-file formats; BFD was a joint project of David V. 411Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore. 412 413David Johnson wrote the original COFF support; Pace Willison did 414the original support for encapsulated COFF. 415 416Brent Benson of Harris Computer Systems contributed DWARF 2 support. 417 418Adam de Boor and Bradley Davis contributed the ISI Optimum V support. 419Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS 420support. 421Jean-Daniel Fekete contributed Sun 386i support. 422Chris Hanson improved the HP9000 support. 423Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support. 424David Johnson contributed Encore Umax support. 425Jyrki Kuoppala contributed Altos 3068 support. 426Jeff Law contributed HP PA and SOM support. 427Keith Packard contributed NS32K support. 428Doug Rabson contributed Acorn Risc Machine support. 429Bob Rusk contributed Harris Nighthawk CX-UX support. 430Chris Smith contributed Convex support (and Fortran debugging). 431Jonathan Stone contributed Pyramid support. 432Michael Tiemann contributed SPARC support. 433Tim Tucker contributed support for the Gould NP1 and Gould Powernode. 434Pace Willison contributed Intel 386 support. 435Jay Vosburgh contributed Symmetry support. 436Marko Mlinar contributed OpenRISC 1000 support. 437 438Andreas Schwab contributed M68K @sc{gnu}/Linux support. 439 440Rich Schaefer and Peter Schauer helped with support of SunOS shared 441libraries. 442 443Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree 444about several machine instruction sets. 445 446Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop 447remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM 448contributed remote debugging modules for the i960, VxWorks, A29K UDI, 449and RDI targets, respectively. 450 451Brian Fox is the author of the readline libraries providing 452command-line editing and command history. 453 454Andrew Beers of SUNY Buffalo wrote the language-switching code, the 455Modula-2 support, and contributed the Languages chapter of this manual. 456 457Fred Fish wrote most of the support for Unix System Vr4. 458He also enhanced the command-completion support to cover C@t{++} overloaded 459symbols. 460 461Hitachi America (now Renesas America), Ltd. sponsored the support for 462H8/300, H8/500, and Super-H processors. 463 464NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors. 465 466Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D 467processors. 468 469Toshiba sponsored the support for the TX39 Mips processor. 470 471Matsushita sponsored the support for the MN10200 and MN10300 processors. 472 473Fujitsu sponsored the support for SPARClite and FR30 processors. 474 475Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware 476watchpoints. 477 478Michael Snyder added support for tracepoints. 479 480Stu Grossman wrote gdbserver. 481 482Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made 483nearly innumerable bug fixes and cleanups throughout @value{GDBN}. 484 485The following people at the Hewlett-Packard Company contributed 486support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 487(narrow mode), HP's implementation of kernel threads, HP's aC@t{++} 488compiler, and the Text User Interface (nee Terminal User Interface): 489Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, 490Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase 491provided HP-specific information in this manual. 492 493DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project. 494Robert Hoehne made significant contributions to the DJGPP port. 495 496Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its 497development since 1991. Cygnus engineers who have worked on @value{GDBN} 498fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin 499Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim 500Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, 501Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek 502Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In 503addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, 504JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug 505Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff 506Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, 507Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin 508Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela 509Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David 510Zuhn have made contributions both large and small. 511 512Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for 513Cygnus Solutions, implemented the original @sc{gdb/mi} interface. 514 515Jim Blandy added support for preprocessor macros, while working for Red 516Hat. 517 518Andrew Cagney designed @value{GDBN}'s architecture vector. Many 519people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick 520Duffek, Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei 521Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason 522Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped 523with the migration of old architectures to this new framework. 524 525Andrew Cagney completely re-designed and re-implemented @value{GDBN}'s 526unwinder framework, this consisting of a fresh new design featuring 527frame IDs, independent frame sniffers, and the sentinel frame. Mark 528Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the 529libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and 530trad unwinders. The architecture-specific changes, each involving a 531complete rewrite of the architecture's frame code, were carried out by 532Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane 533Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel 534Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei 535Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich 536Weigand. 537 538Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from 539Tensilica, Inc.@: contributed support for Xtensa processors. Others 540who have worked on the Xtensa port of @value{GDBN} in the past include 541Steve Tjiang, John Newlin, and Scott Foehner. 542 543Michael Eager and staff of Xilinx, Inc., contributed support for the 544Xilinx MicroBlaze architecture. 545 546Initial support for the FreeBSD/mips target and native configuration 547was developed by SRI International and the University of Cambridge 548Computer Laboratory under DARPA/AFRL contract FA8750-10-C-0237 549("CTSRD"), as part of the DARPA CRASH research programme. 550 551Initial support for the FreeBSD/riscv target and native configuration 552was developed by SRI International and the University of Cambridge 553Computer Laboratory (Department of Computer Science and Technology) 554under DARPA contract HR0011-18-C-0016 ("ECATS"), as part of the DARPA 555SSITH research programme. 556 557The original port to the OpenRISC 1000 is believed to be due to 558Alessandro Forin and Per Bothner. More recent ports have been the work 559of Jeremy Bennett, Franck Jullien, Stefan Wallentowitz and 560Stafford Horne. 561 562Weimin Pan, David Faust and Jose E. Marchesi contributed support for 563the Linux kernel BPF virtual architecture. This work was sponsored by 564Oracle. 565 566@node Sample Session 567@chapter A Sample @value{GDBN} Session 568 569You can use this manual at your leisure to read all about @value{GDBN}. 570However, a handful of commands are enough to get started using the 571debugger. This chapter illustrates those commands. 572 573@iftex 574In this sample session, we emphasize user input like this: @b{input}, 575to make it easier to pick out from the surrounding output. 576@end iftex 577 578@c FIXME: this example may not be appropriate for some configs, where 579@c FIXME...primary interest is in remote use. 580 581One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro 582processor) exhibits the following bug: sometimes, when we change its 583quote strings from the default, the commands used to capture one macro 584definition within another stop working. In the following short @code{m4} 585session, we define a macro @code{foo} which expands to @code{0000}; we 586then use the @code{m4} built-in @code{defn} to define @code{bar} as the 587same thing. However, when we change the open quote string to 588@code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same 589procedure fails to define a new synonym @code{baz}: 590 591@smallexample 592$ @b{cd gnu/m4} 593$ @b{./m4} 594@b{define(foo,0000)} 595 596@b{foo} 5970000 598@b{define(bar,defn(`foo'))} 599 600@b{bar} 6010000 602@b{changequote(<QUOTE>,<UNQUOTE>)} 603 604@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))} 605@b{baz} 606@b{Ctrl-d} 607m4: End of input: 0: fatal error: EOF in string 608@end smallexample 609 610@noindent 611Let us use @value{GDBN} to try to see what is going on. 612 613@smallexample 614$ @b{@value{GDBP} m4} 615@c FIXME: this falsifies the exact text played out, to permit smallbook 616@c FIXME... format to come out better. 617@value{GDBN} is free software and you are welcome to distribute copies 618 of it under certain conditions; type "show copying" to see 619 the conditions. 620There is absolutely no warranty for @value{GDBN}; type "show warranty" 621 for details. 622 623@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc... 624(@value{GDBP}) 625@end smallexample 626 627@noindent 628@value{GDBN} reads only enough symbol data to know where to find the 629rest when needed; as a result, the first prompt comes up very quickly. 630We now tell @value{GDBN} to use a narrower display width than usual, so 631that examples fit in this manual. 632 633@smallexample 634(@value{GDBP}) @b{set width 70} 635@end smallexample 636 637@noindent 638We need to see how the @code{m4} built-in @code{changequote} works. 639Having looked at the source, we know the relevant subroutine is 640@code{m4_changequote}, so we set a breakpoint there with the @value{GDBN} 641@code{break} command. 642 643@smallexample 644(@value{GDBP}) @b{break m4_changequote} 645Breakpoint 1 at 0x62f4: file builtin.c, line 879. 646@end smallexample 647 648@noindent 649Using the @code{run} command, we start @code{m4} running under @value{GDBN} 650control; as long as control does not reach the @code{m4_changequote} 651subroutine, the program runs as usual: 652 653@smallexample 654(@value{GDBP}) @b{run} 655Starting program: /work/Editorial/gdb/gnu/m4/m4 656@b{define(foo,0000)} 657 658@b{foo} 6590000 660@end smallexample 661 662@noindent 663To trigger the breakpoint, we call @code{changequote}. @value{GDBN} 664suspends execution of @code{m4}, displaying information about the 665context where it stops. 666 667@smallexample 668@b{changequote(<QUOTE>,<UNQUOTE>)} 669 670Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) 671 at builtin.c:879 672879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) 673@end smallexample 674 675@noindent 676Now we use the command @code{n} (@code{next}) to advance execution to 677the next line of the current function. 678 679@smallexample 680(@value{GDBP}) @b{n} 681882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ 682 : nil, 683@end smallexample 684 685@noindent 686@code{set_quotes} looks like a promising subroutine. We can go into it 687by using the command @code{s} (@code{step}) instead of @code{next}. 688@code{step} goes to the next line to be executed in @emph{any} 689subroutine, so it steps into @code{set_quotes}. 690 691@smallexample 692(@value{GDBP}) @b{s} 693set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 694 at input.c:530 695530 if (lquote != def_lquote) 696@end smallexample 697 698@noindent 699The display that shows the subroutine where @code{m4} is now 700suspended (and its arguments) is called a stack frame display. It 701shows a summary of the stack. We can use the @code{backtrace} 702command (which can also be spelled @code{bt}), to see where we are 703in the stack as a whole: the @code{backtrace} command displays a 704stack frame for each active subroutine. 705 706@smallexample 707(@value{GDBP}) @b{bt} 708#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 709 at input.c:530 710#1 0x6344 in m4_changequote (argc=3, argv=0x33c70) 711 at builtin.c:882 712#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 713#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) 714 at macro.c:71 715#4 0x79dc in expand_input () at macro.c:40 716#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 717@end smallexample 718 719@noindent 720We step through a few more lines to see what happens. The first two 721times, we can use @samp{s}; the next two times we use @code{n} to avoid 722falling into the @code{xstrdup} subroutine. 723 724@smallexample 725(@value{GDBP}) @b{s} 7260x3b5c 532 if (rquote != def_rquote) 727(@value{GDBP}) @b{s} 7280x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ 729def_lquote : xstrdup(lq); 730(@value{GDBP}) @b{n} 731536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 732 : xstrdup(rq); 733(@value{GDBP}) @b{n} 734538 len_lquote = strlen(rquote); 735@end smallexample 736 737@noindent 738The last line displayed looks a little odd; we can examine the variables 739@code{lquote} and @code{rquote} to see if they are in fact the new left 740and right quotes we specified. We use the command @code{p} 741(@code{print}) to see their values. 742 743@smallexample 744(@value{GDBP}) @b{p lquote} 745$1 = 0x35d40 "<QUOTE>" 746(@value{GDBP}) @b{p rquote} 747$2 = 0x35d50 "<UNQUOTE>" 748@end smallexample 749 750@noindent 751@code{lquote} and @code{rquote} are indeed the new left and right quotes. 752To look at some context, we can display ten lines of source 753surrounding the current line with the @code{l} (@code{list}) command. 754 755@smallexample 756(@value{GDBP}) @b{l} 757533 xfree(rquote); 758534 759535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ 760 : xstrdup (lq); 761536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 762 : xstrdup (rq); 763537 764538 len_lquote = strlen(rquote); 765539 len_rquote = strlen(lquote); 766540 @} 767541 768542 void 769@end smallexample 770 771@noindent 772Let us step past the two lines that set @code{len_lquote} and 773@code{len_rquote}, and then examine the values of those variables. 774 775@smallexample 776(@value{GDBP}) @b{n} 777539 len_rquote = strlen(lquote); 778(@value{GDBP}) @b{n} 779540 @} 780(@value{GDBP}) @b{p len_lquote} 781$3 = 9 782(@value{GDBP}) @b{p len_rquote} 783$4 = 7 784@end smallexample 785 786@noindent 787That certainly looks wrong, assuming @code{len_lquote} and 788@code{len_rquote} are meant to be the lengths of @code{lquote} and 789@code{rquote} respectively. We can set them to better values using 790the @code{p} command, since it can print the value of 791any expression---and that expression can include subroutine calls and 792assignments. 793 794@smallexample 795(@value{GDBP}) @b{p len_lquote=strlen(lquote)} 796$5 = 7 797(@value{GDBP}) @b{p len_rquote=strlen(rquote)} 798$6 = 9 799@end smallexample 800 801@noindent 802Is that enough to fix the problem of using the new quotes with the 803@code{m4} built-in @code{defn}? We can allow @code{m4} to continue 804executing with the @code{c} (@code{continue}) command, and then try the 805example that caused trouble initially: 806 807@smallexample 808(@value{GDBP}) @b{c} 809Continuing. 810 811@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))} 812 813baz 8140000 815@end smallexample 816 817@noindent 818Success! The new quotes now work just as well as the default ones. The 819problem seems to have been just the two typos defining the wrong 820lengths. We allow @code{m4} exit by giving it an EOF as input: 821 822@smallexample 823@b{Ctrl-d} 824Program exited normally. 825@end smallexample 826 827@noindent 828The message @samp{Program exited normally.} is from @value{GDBN}; it 829indicates @code{m4} has finished executing. We can end our @value{GDBN} 830session with the @value{GDBN} @code{quit} command. 831 832@smallexample 833(@value{GDBP}) @b{quit} 834@end smallexample 835 836@node Invocation 837@chapter Getting In and Out of @value{GDBN} 838 839This chapter discusses how to start @value{GDBN}, and how to get out of it. 840The essentials are: 841@itemize @bullet 842@item 843type @samp{@value{GDBP}} to start @value{GDBN}. 844@item 845type @kbd{quit}, @kbd{exit} or @kbd{Ctrl-d} to exit. 846@end itemize 847 848@menu 849* Invoking GDB:: How to start @value{GDBN} 850* Quitting GDB:: How to quit @value{GDBN} 851* Shell Commands:: How to use shell commands inside @value{GDBN} 852* Logging Output:: How to log @value{GDBN}'s output to a file 853@end menu 854 855@node Invoking GDB 856@section Invoking @value{GDBN} 857 858Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started, 859@value{GDBN} reads commands from the terminal until you tell it to exit. 860 861You can also run @code{@value{GDBP}} with a variety of arguments and options, 862to specify more of your debugging environment at the outset. 863 864The command-line options described here are designed 865to cover a variety of situations; in some environments, some of these 866options may effectively be unavailable. 867 868The most usual way to start @value{GDBN} is with one argument, 869specifying an executable program: 870 871@smallexample 872@value{GDBP} @var{program} 873@end smallexample 874 875@noindent 876You can also start with both an executable program and a core file 877specified: 878 879@smallexample 880@value{GDBP} @var{program} @var{core} 881@end smallexample 882 883You can, instead, specify a process ID as a second argument or use option 884@code{-p}, if you want to debug a running process: 885 886@smallexample 887@value{GDBP} @var{program} 1234 888@value{GDBP} -p 1234 889@end smallexample 890 891@noindent 892would attach @value{GDBN} to process @code{1234}. With option @option{-p} you 893can omit the @var{program} filename. 894 895Taking advantage of the second command-line argument requires a fairly 896complete operating system; when you use @value{GDBN} as a remote 897debugger attached to a bare board, there may not be any notion of 898``process'', and there is often no way to get a core dump. @value{GDBN} 899will warn you if it is unable to attach or to read core dumps. 900 901You can optionally have @code{@value{GDBP}} pass any arguments after the 902executable file to the inferior using @code{--args}. This option stops 903option processing. 904@smallexample 905@value{GDBP} --args gcc -O2 -c foo.c 906@end smallexample 907This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set 908@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}. 909 910You can run @code{@value{GDBP}} without printing the front material, which describes 911@value{GDBN}'s non-warranty, by specifying @code{--silent} 912(or @code{-q}/@code{--quiet}): 913 914@smallexample 915@value{GDBP} --silent 916@end smallexample 917 918@noindent 919You can further control how @value{GDBN} starts up by using command-line 920options. @value{GDBN} itself can remind you of the options available. 921 922@noindent 923Type 924 925@smallexample 926@value{GDBP} -help 927@end smallexample 928 929@noindent 930to display all available options and briefly describe their use 931(@samp{@value{GDBP} -h} is a shorter equivalent). 932 933All options and command line arguments you give are processed 934in sequential order. The order makes a difference when the 935@samp{-x} option is used. 936 937 938@menu 939* File Options:: Choosing files 940* Mode Options:: Choosing modes 941* Startup:: What @value{GDBN} does during startup 942* Initialization Files:: Initialization Files 943@end menu 944 945@node File Options 946@subsection Choosing Files 947 948When @value{GDBN} starts, it reads any arguments other than options as 949specifying an executable file and core file (or process ID). This is 950the same as if the arguments were specified by the @samp{-se} and 951@samp{-c} (or @samp{-p}) options respectively. (@value{GDBN} reads the 952first argument that does not have an associated option flag as 953equivalent to the @samp{-se} option followed by that argument; and the 954second argument that does not have an associated option flag, if any, as 955equivalent to the @samp{-c}/@samp{-p} option followed by that argument.) 956If the second argument begins with a decimal digit, @value{GDBN} will 957first attempt to attach to it as a process, and if that fails, attempt 958to open it as a corefile. If you have a corefile whose name begins with 959a digit, you can prevent @value{GDBN} from treating it as a pid by 960prefixing it with @file{./}, e.g.@: @file{./12345}. 961 962If @value{GDBN} has not been configured to included core file support, 963such as for most embedded targets, then it will complain about a second 964argument and ignore it. 965 966For the @samp{-s}, @samp{-e}, and @samp{-se} options, and their long 967form equivalents, the method used to search the file system for the 968symbol and/or executable file is the same as that used by the 969@code{file} command. @xref{Files, ,file}. 970 971Many options have both long and short forms; both are shown in the 972following list. @value{GDBN} also recognizes the long forms if you truncate 973them, so long as enough of the option is present to be unambiguous. 974(If you prefer, you can flag option arguments with @samp{--} rather 975than @samp{-}, though we illustrate the more usual convention.) 976 977@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This 978@c way, both those who look for -foo and --foo in the index, will find 979@c it. 980 981@table @code 982@item -symbols @var{file} 983@itemx -s @var{file} 984@cindex @code{--symbols} 985@cindex @code{-s} 986Read symbol table from file @var{file}. 987 988@item -exec @var{file} 989@itemx -e @var{file} 990@cindex @code{--exec} 991@cindex @code{-e} 992Use file @var{file} as the executable file to execute when appropriate, 993and for examining pure data in conjunction with a core dump. 994 995@item -se @var{file} 996@cindex @code{--se} 997Read symbol table from file @var{file} and use it as the executable 998file. 999 1000@item -core @var{file} 1001@itemx -c @var{file} 1002@cindex @code{--core} 1003@cindex @code{-c} 1004Use file @var{file} as a core dump to examine. 1005 1006@item -pid @var{number} 1007@itemx -p @var{number} 1008@cindex @code{--pid} 1009@cindex @code{-p} 1010Connect to process ID @var{number}, as with the @code{attach} command. 1011 1012@item -command @var{file} 1013@itemx -x @var{file} 1014@cindex @code{--command} 1015@cindex @code{-x} 1016Execute commands from file @var{file}. The contents of this file is 1017evaluated exactly as the @code{source} command would. 1018@xref{Command Files,, Command files}. 1019 1020@item -eval-command @var{command} 1021@itemx -ex @var{command} 1022@cindex @code{--eval-command} 1023@cindex @code{-ex} 1024Execute a single @value{GDBN} command. 1025 1026This option may be used multiple times to call multiple commands. It may 1027also be interleaved with @samp{-command} as required. 1028 1029@smallexample 1030@value{GDBP} -ex 'target sim' -ex 'load' \ 1031 -x setbreakpoints -ex 'run' a.out 1032@end smallexample 1033 1034@item -init-command @var{file} 1035@itemx -ix @var{file} 1036@cindex @code{--init-command} 1037@cindex @code{-ix} 1038Execute commands from file @var{file} before loading the inferior (but 1039after loading gdbinit files). 1040@xref{Startup}. 1041 1042@item -init-eval-command @var{command} 1043@itemx -iex @var{command} 1044@cindex @code{--init-eval-command} 1045@cindex @code{-iex} 1046Execute a single @value{GDBN} command before loading the inferior (but 1047after loading gdbinit files). 1048@xref{Startup}. 1049 1050@item -early-init-command @var{file} 1051@itemx -eix @var{file} 1052@cindex @code{--early-init-command} 1053@cindex @code{-eix} 1054Execute commands from @var{file} very early in the initialization 1055process, before any output is produced. @xref{Startup}. 1056 1057@item -early-init-eval-command @var{command} 1058@itemx -eiex @var{command} 1059@cindex @code{--early-init-eval-command} 1060@cindex @code{-eiex} 1061Execute a single @value{GDBN} command very early in the initialization 1062process, before any output is produced. 1063 1064@item -directory @var{directory} 1065@itemx -d @var{directory} 1066@cindex @code{--directory} 1067@cindex @code{-d} 1068Add @var{directory} to the path to search for source and script files. 1069 1070@item -r 1071@itemx -readnow 1072@cindex @code{--readnow} 1073@cindex @code{-r} 1074Read each symbol file's entire symbol table immediately, rather than 1075the default, which is to read it incrementally as it is needed. 1076This makes startup slower, but makes future operations faster. 1077 1078@item --readnever 1079@anchor{--readnever} 1080@cindex @code{--readnever}, command-line option 1081Do not read each symbol file's symbolic debug information. This makes 1082startup faster but at the expense of not being able to perform 1083symbolic debugging. DWARF unwind information is also not read, 1084meaning backtraces may become incomplete or inaccurate. One use of 1085this is when a user simply wants to do the following sequence: attach, 1086dump core, detach. Loading the debugging information in this case is 1087an unnecessary cause of delay. 1088@end table 1089 1090@node Mode Options 1091@subsection Choosing Modes 1092 1093You can run @value{GDBN} in various alternative modes---for example, in 1094batch mode or quiet mode. 1095 1096@table @code 1097@anchor{-nx} 1098@item -nx 1099@itemx -n 1100@cindex @code{--nx} 1101@cindex @code{-n} 1102Do not execute commands found in any initialization files 1103(@pxref{Initialization Files}). 1104 1105@anchor{-nh} 1106@item -nh 1107@cindex @code{--nh} 1108Do not execute commands found in any home directory initialization 1109file (@pxref{Initialization Files,,Home directory initialization 1110file}). The system wide and current directory initialization files 1111are still loaded. 1112 1113@item -quiet 1114@itemx -silent 1115@itemx -q 1116@cindex @code{--quiet} 1117@cindex @code{--silent} 1118@cindex @code{-q} 1119``Quiet''. Do not print the introductory and copyright messages. These 1120messages are also suppressed in batch mode. 1121 1122@kindex set startup-quietly 1123@kindex show startup-quietly 1124This can also be enabled using @code{set startup-quietly on}. The 1125default is @code{off}. Use @code{show startup-quietly} to see the 1126current setting. Place @code{set startup-quietly on} into your early 1127initialization file (@pxref{Initialization Files,,Initialization 1128Files}) to have future @value{GDBN} sessions startup quietly. 1129 1130@item -batch 1131@cindex @code{--batch} 1132Run in batch mode. Exit with status @code{0} after processing all the 1133command files specified with @samp{-x} (and all commands from 1134initialization files, if not inhibited with @samp{-n}). Exit with 1135nonzero status if an error occurs in executing the @value{GDBN} commands 1136in the command files. Batch mode also disables pagination, sets unlimited 1137terminal width and height @pxref{Screen Size}, and acts as if @kbd{set confirm 1138off} were in effect (@pxref{Messages/Warnings}). 1139 1140Batch mode may be useful for running @value{GDBN} as a filter, for 1141example to download and run a program on another computer; in order to 1142make this more useful, the message 1143 1144@smallexample 1145Program exited normally. 1146@end smallexample 1147 1148@noindent 1149(which is ordinarily issued whenever a program running under 1150@value{GDBN} control terminates) is not issued when running in batch 1151mode. 1152 1153@item -batch-silent 1154@cindex @code{--batch-silent} 1155Run in batch mode exactly like @samp{-batch}, but totally silently. All 1156@value{GDBN} output to @code{stdout} is prevented (@code{stderr} is 1157unaffected). This is much quieter than @samp{-silent} and would be useless 1158for an interactive session. 1159 1160This is particularly useful when using targets that give @samp{Loading section} 1161messages, for example. 1162 1163Note that targets that give their output via @value{GDBN}, as opposed to 1164writing directly to @code{stdout}, will also be made silent. 1165 1166@item -return-child-result 1167@cindex @code{--return-child-result} 1168The return code from @value{GDBN} will be the return code from the child 1169process (the process being debugged), with the following exceptions: 1170 1171@itemize @bullet 1172@item 1173@value{GDBN} exits abnormally. E.g., due to an incorrect argument or an 1174internal error. In this case the exit code is the same as it would have been 1175without @samp{-return-child-result}. 1176@item 1177The user quits with an explicit value. E.g., @samp{quit 1}. 1178@item 1179The child process never runs, or is not allowed to terminate, in which case 1180the exit code will be -1. 1181@end itemize 1182 1183This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent}, 1184when @value{GDBN} is being used as a remote program loader or simulator 1185interface. 1186 1187@item -nowindows 1188@itemx -nw 1189@cindex @code{--nowindows} 1190@cindex @code{-nw} 1191``No windows''. If @value{GDBN} comes with a graphical user interface 1192(GUI) built in, then this option tells @value{GDBN} to only use the command-line 1193interface. If no GUI is available, this option has no effect. 1194 1195@item -windows 1196@itemx -w 1197@cindex @code{--windows} 1198@cindex @code{-w} 1199If @value{GDBN} includes a GUI, then this option requires it to be 1200used if possible. 1201 1202@item -cd @var{directory} 1203@cindex @code{--cd} 1204Run @value{GDBN} using @var{directory} as its working directory, 1205instead of the current directory. 1206 1207@item -data-directory @var{directory} 1208@itemx -D @var{directory} 1209@cindex @code{--data-directory} 1210@cindex @code{-D} 1211Run @value{GDBN} using @var{directory} as its data directory. 1212The data directory is where @value{GDBN} searches for its 1213auxiliary files. @xref{Data Files}. 1214 1215@item -fullname 1216@itemx -f 1217@cindex @code{--fullname} 1218@cindex @code{-f} 1219@sc{gnu} Emacs sets this option when it runs @value{GDBN} as a 1220subprocess. It tells @value{GDBN} to output the full file name and line 1221number in a standard, recognizable fashion each time a stack frame is 1222displayed (which includes each time your program stops). This 1223recognizable format looks like two @samp{\032} characters, followed by 1224the file name, line number and character position separated by colons, 1225and a newline. The Emacs-to-@value{GDBN} interface program uses the two 1226@samp{\032} characters as a signal to display the source code for the 1227frame. 1228 1229@item -annotate @var{level} 1230@cindex @code{--annotate} 1231This option sets the @dfn{annotation level} inside @value{GDBN}. Its 1232effect is identical to using @samp{set annotate @var{level}} 1233(@pxref{Annotations}). The annotation @var{level} controls how much 1234information @value{GDBN} prints together with its prompt, values of 1235expressions, source lines, and other types of output. Level 0 is the 1236normal, level 1 is for use when @value{GDBN} is run as a subprocess of 1237@sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs 1238that control @value{GDBN}, and level 2 has been deprecated. 1239 1240The annotation mechanism has largely been superseded by @sc{gdb/mi} 1241(@pxref{GDB/MI}). 1242 1243@item --args 1244@cindex @code{--args} 1245Change interpretation of command line so that arguments following the 1246executable file are passed as command line arguments to the inferior. 1247This option stops option processing. 1248 1249@item -baud @var{bps} 1250@itemx -b @var{bps} 1251@cindex @code{--baud} 1252@cindex @code{-b} 1253Set the line speed (baud rate or bits per second) of any serial 1254interface used by @value{GDBN} for remote debugging. 1255 1256@item -l @var{timeout} 1257@cindex @code{-l} 1258Set the timeout (in seconds) of any communication used by @value{GDBN} 1259for remote debugging. 1260 1261@item -tty @var{device} 1262@itemx -t @var{device} 1263@cindex @code{--tty} 1264@cindex @code{-t} 1265Run using @var{device} for your program's standard input and output. 1266@c FIXME: kingdon thinks there is more to -tty. Investigate. 1267 1268@c resolve the situation of these eventually 1269@item -tui 1270@cindex @code{--tui} 1271Activate the @dfn{Text User Interface} when starting. The Text User 1272Interface manages several text windows on the terminal, showing 1273source, assembly, registers and @value{GDBN} command outputs 1274(@pxref{TUI, ,@value{GDBN} Text User Interface}). Do not use this 1275option if you run @value{GDBN} from Emacs (@pxref{Emacs, , 1276Using @value{GDBN} under @sc{gnu} Emacs}). 1277 1278@item -interpreter @var{interp} 1279@cindex @code{--interpreter} 1280Use the interpreter @var{interp} for interface with the controlling 1281program or device. This option is meant to be set by programs which 1282communicate with @value{GDBN} using it as a back end. 1283@xref{Interpreters, , Command Interpreters}. 1284 1285@samp{--interpreter=mi} (or @samp{--interpreter=mi3}) causes 1286@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} version 3 (@pxref{GDB/MI, , 1287The @sc{gdb/mi} Interface}) included since @value{GDBN} version 9.1. @sc{gdb/mi} 1288version 2 (@code{mi2}), included in @value{GDBN} 6.0 and version 1 (@code{mi1}), 1289included in @value{GDBN} 5.3, are also available. Earlier @sc{gdb/mi} 1290interfaces are no longer supported. 1291 1292@item -write 1293@cindex @code{--write} 1294Open the executable and core files for both reading and writing. This 1295is equivalent to the @samp{set write on} command inside @value{GDBN} 1296(@pxref{Patching}). 1297 1298@item -statistics 1299@cindex @code{--statistics} 1300This option causes @value{GDBN} to print statistics about time and 1301memory usage after it completes each command and returns to the prompt. 1302 1303@item -version 1304@cindex @code{--version} 1305This option causes @value{GDBN} to print its version number and 1306no-warranty blurb, and exit. 1307 1308@item -configuration 1309@cindex @code{--configuration} 1310This option causes @value{GDBN} to print details about its build-time 1311configuration parameters, and then exit. These details can be 1312important when reporting @value{GDBN} bugs (@pxref{GDB Bugs}). 1313 1314@end table 1315 1316@node Startup 1317@subsection What @value{GDBN} Does During Startup 1318@cindex @value{GDBN} startup 1319 1320Here's the description of what @value{GDBN} does during session startup: 1321 1322@enumerate 1323 1324@item 1325Performs minimal setup required to initialize basic internal state. 1326 1327@item 1328@cindex early initialization file 1329Reads commands from the early initialization file (if any) in your 1330home directory. Only a restricted set of commands can be placed into 1331an early initialization file, see @ref{Initialization Files}, for 1332details. 1333 1334@item 1335Executes commands and command files specified by the @samp{-eiex} and 1336@samp{-eix} command line options in their specified order. Only a 1337restricted set of commands can be used with @samp{-eiex} and 1338@samp{eix}, see @ref{Initialization Files}, for details. 1339 1340@item 1341Sets up the command interpreter as specified by the command line 1342(@pxref{Mode Options, interpreter}). 1343 1344@item 1345@cindex init file 1346Reads the system wide initialization file and the files from the 1347system wide initialization directory, @pxref{System Wide Init Files}. 1348 1349@item 1350Reads the initialization file (if any) in your home directory and 1351executes all the commands in that file, @pxref{Home Directory Init 1352File}. 1353 1354@anchor{Option -init-eval-command} 1355@item 1356Executes commands and command files specified by the @samp{-iex} and 1357@samp{-ix} options in their specified order. Usually you should use the 1358@samp{-ex} and @samp{-x} options instead, but this way you can apply 1359settings before @value{GDBN} init files get executed and before inferior 1360gets loaded. 1361 1362@item 1363Processes command line options and operands. 1364 1365@item 1366Reads and executes the commands from the initialization file (if any) 1367in the current working directory as long as @samp{set auto-load 1368local-gdbinit} is set to @samp{on} (@pxref{Init File in the Current 1369Directory}). This is only done if the current directory is different 1370from your home directory. Thus, you can have more than one init file, 1371one generic in your home directory, and another, specific to the 1372program you are debugging, in the directory where you invoke 1373@value{GDBN}. @xref{Init File in the Current Directory during 1374Startup}. 1375 1376@item 1377If the command line specified a program to debug, or a process to 1378attach to, or a core file, @value{GDBN} loads any auto-loaded 1379scripts provided for the program or for its loaded shared libraries. 1380@xref{Auto-loading}. 1381 1382If you wish to disable the auto-loading during startup, 1383you must do something like the following: 1384 1385@smallexample 1386$ gdb -iex "set auto-load python-scripts off" myprogram 1387@end smallexample 1388 1389Option @samp{-ex} does not work because the auto-loading is then turned 1390off too late. 1391 1392@item 1393Executes commands and command files specified by the @samp{-ex} and 1394@samp{-x} options in their specified order. @xref{Command Files}, for 1395more details about @value{GDBN} command files. 1396 1397@item 1398Reads the command history recorded in the @dfn{history file}. 1399@xref{Command History}, for more details about the command history and the 1400files where @value{GDBN} records it. 1401@end enumerate 1402 1403@node Initialization Files 1404@subsection Initialization Files 1405@cindex init file name 1406 1407During startup (@pxref{Startup}) @value{GDBN} will execute commands 1408from several initialization files. These initialization files use the 1409same syntax as @dfn{command files} (@pxref{Command Files}) and are 1410processed by @value{GDBN} in the same way. 1411 1412To display the list of initialization files loaded by @value{GDBN} at 1413startup, in the order they will be loaded, you can use @kbd{gdb 1414--help}. 1415 1416@cindex early initialization 1417The @dfn{early initialization} file is loaded very early in 1418@value{GDBN}'s initialization process, before the interpreter 1419(@pxref{Interpreters}) has been initialized, and before the default 1420target (@pxref{Targets}) is initialized. Only @code{set} or 1421@code{source} commands should be placed into an early initialization 1422file, and the only @code{set} commands that can be used are those that 1423control how @value{GDBN} starts up. 1424 1425Commands that can be placed into an early initialization file will be 1426documented as such throughout this manual. Any command that is not 1427documented as being suitable for an early initialization file should 1428instead be placed into a general initialization file. Command files 1429passed to @code{--early-init-command} or @code{-eix} are also early 1430initialization files, with the same command restrictions. Only 1431commands that can appear in an early initialization file should be 1432passed to @code{--early-init-eval-command} or @code{-eiex}. 1433 1434@cindex general initialization 1435In contrast, the @dfn{general initialization} files are processed 1436later, after @value{GDBN} has finished its own internal initialization 1437process, any valid command can be used in these files. 1438 1439@cindex initialization file 1440Throughout the rest of this document the term @dfn{initialization 1441file} refers to one of the general initialization files, not the early 1442initialization file. Any discussion of the early initialization file 1443will specifically mention that it is the early initialization file 1444being discussed. 1445 1446As the system wide and home directory initialization files are 1447processed before most command line options, changes to settings 1448(e.g.@: @samp{set complaints}) can affect subsequent processing of 1449command line options and operands. 1450 1451The following sections describe where @value{GDBN} looks for the early 1452initialization and initialization files, and the order that the files 1453are searched for. 1454 1455@subsubsection Home directory early initialization files 1456 1457@value{GDBN} initially looks for an early initialization file in the 1458users home directory@footnote{On DOS/Windows systems, the home 1459directory is the one pointed to by the @env{HOME} environment 1460variable.}. There are a number of locations that @value{GDBN} will 1461search in the home directory, these locations are searched in order 1462and @value{GDBN} will load the first file that it finds, and 1463subsequent locations will not be checked. 1464 1465On non-macOS hosts the locations searched are: 1466@itemize 1467@item 1468The file @file{gdb/gdbearlyinit} within the directory pointed to by the 1469environment variable @env{XDG_CONFIG_HOME}, if it is defined. 1470@item 1471The file @file{.config/gdb/gdbearlyinit} within the directory pointed to 1472by the environment variable @env{HOME}, if it is defined. 1473@item 1474The file @file{.gdbearlyinit} within the directory pointed to by the 1475environment variable @env{HOME}, if it is defined. 1476@end itemize 1477 1478By contrast, on macOS hosts the locations searched are: 1479@itemize 1480@item 1481The file @file{Library/Preferences/gdb/gdbearlyinit} within the 1482directory pointed to by the environment variable @env{HOME}, if it is 1483defined. 1484@item 1485The file @file{.gdbearlyinit} within the directory pointed to by the 1486environment variable @env{HOME}, if it is defined. 1487@end itemize 1488 1489It is possible to prevent the home directory early initialization file 1490from being loaded using the @samp{-nx} or @samp{-nh} command line 1491options, @pxref{Mode Options,,Choosing Modes}. 1492 1493@anchor{System Wide Init Files} 1494@subsubsection System wide initialization files 1495 1496There are two locations that are searched for system wide 1497initialization files. Both of these locations are always checked: 1498 1499@table @code 1500 1501@item @file{system.gdbinit} 1502This is a single system-wide initialization file. Its location is 1503specified with the @code{--with-system-gdbinit} configure option 1504(@pxref{System-wide configuration}). It is loaded first when 1505@value{GDBN} starts, before command line options have been processed. 1506 1507@item @file{system.gdbinit.d} 1508This is the system-wide initialization directory. Its location is 1509specified with the @code{--with-system-gdbinit-dir} configure option 1510(@pxref{System-wide configuration}). Files in this directory are 1511loaded in alphabetical order immediately after @file{system.gdbinit} 1512(if enabled) when @value{GDBN} starts, before command line options 1513have been processed. Files need to have a recognized scripting 1514language extension (@file{.py}/@file{.scm}) or be named with a 1515@file{.gdb} extension to be interpreted as regular @value{GDBN} 1516commands. @value{GDBN} will not recurse into any subdirectories of 1517this directory. 1518 1519@end table 1520 1521It is possible to prevent the system wide initialization files from 1522being loaded using the @samp{-nx} command line option, @pxref{Mode 1523Options,,Choosing Modes}. 1524 1525@anchor{Home Directory Init File} 1526@subsubsection Home directory initialization file 1527@cindex @file{gdbinit} 1528@cindex @file{.gdbinit} 1529@cindex @file{gdb.ini} 1530 1531After loading the system wide initialization files @value{GDBN} will 1532look for an initialization file in the users home 1533directory@footnote{On DOS/Windows systems, the home directory is the 1534one pointed to by the @env{HOME} environment variable.}. There are a 1535number of locations that @value{GDBN} will search in the home 1536directory, these locations are searched in order and @value{GDBN} will 1537load the first file that it finds, and subsequent locations will not 1538be checked. 1539 1540On non-Apple hosts the locations searched are: 1541@table @file 1542@item $XDG_CONFIG_HOME/gdb/gdbinit 1543@item $HOME/.config/gdb/gdbinit 1544@item $HOME/.gdbinit 1545@end table 1546 1547While on Apple hosts the locations searched are: 1548@table @file 1549@item $HOME/Library/Preferences/gdb/gdbinit 1550@item $HOME/.gdbinit 1551@end table 1552 1553It is possible to prevent the home directory initialization file from 1554being loaded using the @samp{-nx} or @samp{-nh} command line options, 1555@pxref{Mode Options,,Choosing Modes}. 1556 1557The DJGPP port of @value{GDBN} uses the name @file{gdb.ini} instead of 1558@file{.gdbinit} or @file{gdbinit}, due to the limitations of file 1559names imposed by DOS filesystems. The Windows port of @value{GDBN} 1560uses the standard name, but if it finds a @file{gdb.ini} file in your 1561home directory, it warns you about that and suggests to rename the 1562file to the standard name. 1563 1564@anchor{Init File in the Current Directory during Startup} 1565@subsubsection Local directory initialization file 1566 1567@value{GDBN} will check the current directory for a file called 1568@file{.gdbinit}. It is loaded last, after command line options 1569other than @samp{-x} and @samp{-ex} have been processed. The command 1570line options @samp{-x} and @samp{-ex} are processed last, after 1571@file{.gdbinit} has been loaded, @pxref{File Options,,Choosing 1572Files}. 1573 1574If the file in the current directory was already loaded as the home 1575directory initialization file then it will not be loaded a second 1576time. 1577 1578It is possible to prevent the local directory initialization file from 1579being loaded using the @samp{-nx} command line option, @pxref{Mode 1580Options,,Choosing Modes}. 1581 1582@node Quitting GDB 1583@section Quitting @value{GDBN} 1584@cindex exiting @value{GDBN} 1585@cindex leaving @value{GDBN} 1586 1587@table @code 1588@kindex quit @r{[}@var{expression}@r{]} 1589@kindex exit @r{[}@var{expression}@r{]} 1590@kindex q @r{(@code{quit})} 1591@item quit @r{[}@var{expression}@r{]} 1592@itemx exit @r{[}@var{expression}@r{]} 1593@itemx q 1594To exit @value{GDBN}, use the @code{quit} command (abbreviated 1595@code{q}), the @code{exit} command, or type an end-of-file 1596character (usually @kbd{Ctrl-d}). If you do not supply @var{expression}, 1597@value{GDBN} will terminate normally; otherwise it will terminate using 1598the result of @var{expression} as the error code. 1599@end table 1600 1601@cindex interrupt 1602An interrupt (often @kbd{Ctrl-c}) does not exit from @value{GDBN}, but rather 1603terminates the action of any @value{GDBN} command that is in progress and 1604returns to @value{GDBN} command level. It is safe to type the interrupt 1605character at any time because @value{GDBN} does not allow it to take effect 1606until a time when it is safe. 1607 1608If you have been using @value{GDBN} to control an attached process or 1609device, you can release it with the @code{detach} command 1610(@pxref{Attach, ,Debugging an Already-running Process}). 1611 1612@node Shell Commands 1613@section Shell Commands 1614 1615If you need to execute occasional shell commands during your 1616debugging session, there is no need to leave or suspend @value{GDBN}; you can 1617just use the @code{shell} command. 1618 1619@table @code 1620@kindex shell 1621@kindex ! 1622@cindex shell escape 1623@item shell @var{command-string} 1624@itemx !@var{command-string} 1625Invoke a shell to execute @var{command-string}. 1626Note that no space is needed between @code{!} and @var{command-string}. 1627On GNU and Unix systems, the environment variable @env{SHELL}, if it 1628exists, determines which shell to run. Otherwise @value{GDBN} uses 1629the default shell (@file{/bin/sh} on GNU and Unix systems, 1630@file{cmd.exe} on MS-Windows, @file{COMMAND.COM} on MS-DOS, etc.). 1631@end table 1632 1633You may also invoke shell commands from expressions, using the 1634@code{$_shell} convenience function. @xref{$_shell convenience 1635function}. 1636 1637The utility @code{make} is often needed in development environments. 1638You do not have to use the @code{shell} command for this purpose in 1639@value{GDBN}: 1640 1641@table @code 1642@kindex make 1643@cindex calling make 1644@item make @var{make-args} 1645Execute the @code{make} program with the specified 1646arguments. This is equivalent to @samp{shell make @var{make-args}}. 1647@end table 1648 1649@table @code 1650@kindex pipe 1651@kindex | 1652@cindex send the output of a gdb command to a shell command 1653@anchor{pipe} 1654@item pipe [@var{command}] | @var{shell_command} 1655@itemx | [@var{command}] | @var{shell_command} 1656@itemx pipe -d @var{delim} @var{command} @var{delim} @var{shell_command} 1657@itemx | -d @var{delim} @var{command} @var{delim} @var{shell_command} 1658Executes @var{command} and sends its output to @var{shell_command}. 1659Note that no space is needed around @code{|}. 1660If no @var{command} is provided, the last command executed is repeated. 1661 1662In case the @var{command} contains a @code{|}, the option @code{-d @var{delim}} 1663can be used to specify an alternate delimiter string @var{delim} that separates 1664the @var{command} from the @var{shell_command}. 1665 1666Example: 1667@smallexample 1668@group 1669(@value{GDBP}) p var 1670$1 = @{ 1671 black = 144, 1672 red = 233, 1673 green = 377, 1674 blue = 610, 1675 white = 987 1676@} 1677@end group 1678@group 1679(@value{GDBP}) pipe p var|wc 1680 7 19 80 1681(@value{GDBP}) |p var|wc -l 16827 1683@end group 1684@group 1685(@value{GDBP}) p /x var 1686$4 = @{ 1687 black = 0x90, 1688 red = 0xe9, 1689 green = 0x179, 1690 blue = 0x262, 1691 white = 0x3db 1692@} 1693(@value{GDBP}) ||grep red 1694 red => 0xe9, 1695@end group 1696@group 1697(@value{GDBP}) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/' 1698this contains a PIPE char 1699(@value{GDBP}) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/' 1700this contains a PIPE char! 1701(@value{GDBP}) 1702@end group 1703@end smallexample 1704@end table 1705 1706The convenience variables @code{$_shell_exitcode} and @code{$_shell_exitsignal} 1707can be used to examine the exit status of the last shell command launched 1708by @code{shell}, @code{make}, @code{pipe} and @code{|}. 1709@xref{Convenience Vars,, Convenience Variables}. 1710 1711@node Logging Output 1712@section Logging Output 1713@cindex logging @value{GDBN} output 1714@cindex save @value{GDBN} output to a file 1715 1716You may want to save the output of @value{GDBN} commands to a file. 1717There are several commands to control @value{GDBN}'s logging. 1718 1719@table @code 1720@kindex set logging enabled 1721@item set logging enabled [on|off] 1722Enable or disable logging. 1723@cindex logging file name 1724@item set logging file @var{file} 1725Change the name of the current logfile. The default logfile is @file{gdb.txt}. 1726@item set logging overwrite [on|off] 1727By default, @value{GDBN} will append to the logfile. Set @code{overwrite} if 1728you want @code{set logging enabled on} to overwrite the logfile instead. 1729@item set logging redirect [on|off] 1730By default, @value{GDBN} output will go to both the terminal and the logfile. 1731Set @code{redirect} if you want output to go only to the log file. 1732@item set logging debugredirect [on|off] 1733By default, @value{GDBN} debug output will go to both the terminal and the logfile. 1734Set @code{debugredirect} if you want debug output to go only to the log file. 1735@kindex show logging 1736@item show logging 1737Show the current values of the logging settings. 1738@end table 1739 1740You can also redirect the output of a @value{GDBN} command to a 1741shell command. @xref{pipe}. 1742@node Commands 1743@chapter @value{GDBN} Commands 1744 1745You can abbreviate a @value{GDBN} command to the first few letters of the command 1746name, if that abbreviation is unambiguous; and you can repeat certain 1747@value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB} 1748key to get @value{GDBN} to fill out the rest of a word in a command (or to 1749show you the alternatives available, if there is more than one possibility). 1750 1751@menu 1752* Command Syntax:: How to give commands to @value{GDBN} 1753* Command Settings:: How to change default behavior of commands 1754* Completion:: Command completion 1755* Filename Arguments:: Filenames As Command Arguments 1756* Command Options:: Command options 1757* Help:: How to ask @value{GDBN} for help 1758@end menu 1759 1760@node Command Syntax 1761@section Command Syntax 1762 1763A @value{GDBN} command is a single line of input. There is no limit on 1764how long it can be. It starts with a command name, which is followed by 1765arguments whose meaning depends on the command name. For example, the 1766command @code{step} accepts an argument which is the number of times to 1767step, as in @samp{step 5}. You can also use the @code{step} command 1768with no arguments. Some commands do not allow any arguments. 1769 1770@cindex abbreviation 1771@value{GDBN} command names may always be truncated if that abbreviation is 1772unambiguous. Other possible command abbreviations are listed in the 1773documentation for individual commands. In some cases, even ambiguous 1774abbreviations are allowed; for example, @code{s} is specially defined as 1775equivalent to @code{step} even though there are other commands whose 1776names start with @code{s}. You can test abbreviations by using them as 1777arguments to the @code{help} command. 1778 1779@cindex repeating commands 1780@kindex RET @r{(repeat last command)} 1781A blank line as input to @value{GDBN} (typing just @key{RET}) means to 1782repeat the previous command. Certain commands (for example, @code{run}) 1783will not repeat this way; these are commands whose unintentional 1784repetition might cause trouble and which you are unlikely to want to 1785repeat. User-defined commands can disable this feature; see 1786@ref{Define, dont-repeat}. 1787 1788The @code{list} and @code{x} commands, when you repeat them with 1789@key{RET}, construct new arguments rather than repeating 1790exactly as typed. This permits easy scanning of source or memory. 1791 1792@value{GDBN} can also use @key{RET} in another way: to partition lengthy 1793output, in a way similar to the common utility @code{more} 1794(@pxref{Screen Size,,Screen Size}). Since it is easy to press one 1795@key{RET} too many in this situation, @value{GDBN} disables command 1796repetition after any command that generates this sort of display. 1797 1798@kindex # @r{(a comment)} 1799@cindex comment 1800Any text from a @kbd{#} to the end of the line is a comment; it does 1801nothing. This is useful mainly in command files (@pxref{Command 1802Files,,Command Files}). 1803 1804@cindex repeating command sequences 1805@kindex Ctrl-o @r{(operate-and-get-next)} 1806The @kbd{Ctrl-o} binding is useful for repeating a complex sequence of 1807commands. This command accepts the current line, like @key{RET}, and 1808then fetches the next line relative to the current line from the history 1809for editing. 1810 1811 1812@node Command Settings 1813@section Command Settings 1814@cindex default behavior of commands, changing 1815@cindex default settings, changing 1816 1817Many commands change their behavior according to command-specific 1818variables or settings. These settings can be changed with the 1819@code{set} subcommands. For example, the @code{print} command 1820(@pxref{Data, ,Examining Data}) prints arrays differently depending on 1821settings changeable with the commands @code{set print elements 1822NUMBER-OF-ELEMENTS} and @code{set print array-indexes}, among others. 1823 1824You can change these settings to your preference in the gdbinit files 1825loaded at @value{GDBN} startup. @xref{Startup}. 1826 1827The settings can also be changed interactively during the debugging 1828session. For example, to change the limit of array elements to print, 1829you can do the following: 1830@smallexample 1831(@value{GDBP}) set print elements 10 1832(@value{GDBP}) print some_array 1833$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@} 1834@end smallexample 1835 1836The above @code{set print elements 10} command changes the number of 1837elements to print from the default of 200 to 10. If you only intend 1838this limit of 10 to be used for printing @code{some_array}, then you 1839must restore the limit back to 200, with @code{set print elements 1840200}. 1841 1842Some commands allow overriding settings with command options. For 1843example, the @code{print} command supports a number of options that 1844allow overriding relevant global print settings as set by @code{set 1845print} subcommands. @xref{print options}. The example above could be 1846rewritten as: 1847@smallexample 1848(@value{GDBP}) print -elements 10 -- some_array 1849$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@} 1850@end smallexample 1851 1852Alternatively, you can use the @code{with} command to change a setting 1853temporarily, for the duration of a command invocation. 1854 1855@table @code 1856@kindex with command 1857@kindex w @r{(@code{with})} 1858@cindex settings 1859@cindex temporarily change settings 1860@item with @var{setting} [@var{value}] [-- @var{command}] 1861@itemx w @var{setting} [@var{value}] [-- @var{command}] 1862Temporarily set @var{setting} to @var{value} for the duration of 1863@var{command}. 1864 1865@var{setting} is any setting you can change with the @code{set} 1866subcommands. @var{value} is the value to assign to @code{setting} 1867while running @code{command}. 1868 1869If no @var{command} is provided, the last command executed is 1870repeated. 1871 1872If a @var{command} is provided, it must be preceded by a double dash 1873(@code{--}) separator. This is required because some settings accept 1874free-form arguments, such as expressions or filenames. 1875 1876For example, the command 1877@smallexample 1878(@value{GDBP}) with print array on -- print some_array 1879@end smallexample 1880@noindent 1881is equivalent to the following 3 commands: 1882@smallexample 1883(@value{GDBP}) set print array on 1884(@value{GDBP}) print some_array 1885(@value{GDBP}) set print array off 1886@end smallexample 1887 1888The @code{with} command is particularly useful when you want to 1889override a setting while running user-defined commands, or commands 1890defined in Python or Guile. @xref{Extending GDB,, Extending GDB}. 1891 1892@smallexample 1893(@value{GDBP}) with print pretty on -- my_complex_command 1894@end smallexample 1895 1896To change several settings for the same command, you can nest 1897@code{with} commands. For example, @code{with language ada -- with 1898print elements 10} temporarily changes the language to Ada and sets a 1899limit of 10 elements to print for arrays and strings. 1900 1901@end table 1902 1903@node Completion 1904@section Command Completion 1905 1906@cindex completion 1907@cindex word completion 1908@value{GDBN} can fill in the rest of a word in a command for you, if there is 1909only one possibility; it can also show you what the valid possibilities 1910are for the next word in a command, at any time. This works for @value{GDBN} 1911commands, @value{GDBN} subcommands, command options, and the names of symbols 1912in your program. 1913 1914Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest 1915of a word. If there is only one possibility, @value{GDBN} fills in the 1916word, and waits for you to finish the command (or press @key{RET} to 1917enter it). For example, if you type 1918 1919@c FIXME "@key" does not distinguish its argument sufficiently to permit 1920@c complete accuracy in these examples; space introduced for clarity. 1921@c If texinfo enhancements make it unnecessary, it would be nice to 1922@c replace " @key" by "@key" in the following... 1923@smallexample 1924(@value{GDBP}) info bre@key{TAB} 1925@end smallexample 1926 1927@noindent 1928@value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is 1929the only @code{info} subcommand beginning with @samp{bre}: 1930 1931@smallexample 1932(@value{GDBP}) info breakpoints 1933@end smallexample 1934 1935@noindent 1936You can either press @key{RET} at this point, to run the @code{info 1937breakpoints} command, or backspace and enter something else, if 1938@samp{breakpoints} does not look like the command you expected. (If you 1939were sure you wanted @code{info breakpoints} in the first place, you 1940might as well just type @key{RET} immediately after @samp{info bre}, 1941to exploit command abbreviations rather than command completion). 1942 1943If there is more than one possibility for the next word when you press 1944@key{TAB}, @value{GDBN} sounds a bell. You can either supply more 1945characters and try again, or just press @key{TAB} a second time; 1946@value{GDBN} displays all the possible completions for that word. For 1947example, you might want to set a breakpoint on a subroutine whose name 1948begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN} 1949just sounds the bell. Typing @key{TAB} again displays all the 1950function names in your program that begin with those characters, for 1951example: 1952 1953@smallexample 1954(@value{GDBP}) b make_@key{TAB} 1955@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see: 1956make_a_section_from_file make_environ 1957make_abs_section make_function_type 1958make_blockvector make_pointer_type 1959make_cleanup make_reference_type 1960make_command make_symbol_completion_list 1961(@value{GDBP}) b make_ 1962@end smallexample 1963 1964@noindent 1965After displaying the available possibilities, @value{GDBN} copies your 1966partial input (@samp{b make_} in the example) so you can finish the 1967command. 1968 1969If the command you are trying to complete expects either a keyword or a 1970number to follow, then @samp{NUMBER} will be shown among the available 1971completions, for example: 1972 1973@smallexample 1974(@value{GDBP}) print -elements @key{TAB}@key{TAB} 1975NUMBER unlimited 1976(@value{GDBP}) print -elements@tie{} 1977@end smallexample 1978 1979@noindent 1980Here, the option expects a number (e.g., @code{100}), not literal 1981@code{NUMBER}. Such metasyntactical arguments are always presented in 1982uppercase. 1983 1984If you just want to see the list of alternatives in the first place, you 1985can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?} 1986means @kbd{@key{META} ?}. You can type this either by holding down a 1987key designated as the @key{META} shift on your keyboard (if there is 1988one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}. 1989 1990If the number of possible completions is large, @value{GDBN} will 1991print as much of the list as it has collected, as well as a message 1992indicating that the list may be truncated. 1993 1994@smallexample 1995(@value{GDBP}) b m@key{TAB}@key{TAB} 1996main 1997<... the rest of the possible completions ...> 1998*** List may be truncated, max-completions reached. *** 1999(@value{GDBP}) b m 2000@end smallexample 2001 2002@noindent 2003This behavior can be controlled with the following commands: 2004 2005@table @code 2006@kindex set max-completions 2007@item set max-completions @var{limit} 2008@itemx set max-completions unlimited 2009Set the maximum number of completion candidates. @value{GDBN} will 2010stop looking for more completions once it collects this many candidates. 2011This is useful when completing on things like function names as collecting 2012all the possible candidates can be time consuming. 2013The default value is 200. A value of zero disables tab-completion. 2014Note that setting either no limit or a very large limit can make 2015completion slow. 2016@kindex show max-completions 2017@item show max-completions 2018Show the maximum number of candidates that @value{GDBN} will collect and show 2019during completion. 2020@end table 2021 2022@cindex quotes in commands 2023@cindex completion of quoted strings 2024Sometimes the string you need, while logically a ``word'', may contain 2025parentheses or other characters that @value{GDBN} normally excludes from 2026its notion of a word. To permit word completion to work in this 2027situation, you may enclose words in @code{'} (single quote marks) in 2028@value{GDBN} commands. 2029 2030A likely situation where you might need this is in typing an 2031expression that involves a C@t{++} symbol name with template 2032parameters. This is because when completing expressions, GDB treats 2033the @samp{<} character as word delimiter, assuming that it's the 2034less-than comparison operator (@pxref{C Operators, , C and C@t{++} 2035Operators}). 2036 2037For example, when you want to call a C@t{++} template function 2038interactively using the @code{print} or @code{call} commands, you may 2039need to distinguish whether you mean the version of @code{name} that 2040was specialized for @code{int}, @code{name<int>()}, or the version 2041that was specialized for @code{float}, @code{name<float>()}. To use 2042the word-completion facilities in this situation, type a single quote 2043@code{'} at the beginning of the function name. This alerts 2044@value{GDBN} that it may need to consider more information than usual 2045when you press @key{TAB} or @kbd{M-?} to request word completion: 2046 2047@smallexample 2048(@value{GDBP}) p 'func<@kbd{M-?} 2049func<int>() func<float>() 2050(@value{GDBP}) p 'func< 2051@end smallexample 2052 2053When setting breakpoints however (@pxref{Location Specifications}), you don't 2054usually need to type a quote before the function name, because 2055@value{GDBN} understands that you want to set a breakpoint on a 2056function: 2057 2058@smallexample 2059(@value{GDBP}) b func<@kbd{M-?} 2060func<int>() func<float>() 2061(@value{GDBP}) b func< 2062@end smallexample 2063 2064This is true even in the case of typing the name of C@t{++} overloaded 2065functions (multiple definitions of the same function, distinguished by 2066argument type). For example, when you want to set a breakpoint you 2067don't need to distinguish whether you mean the version of @code{name} 2068that takes an @code{int} parameter, @code{name(int)}, or the version 2069that takes a @code{float} parameter, @code{name(float)}. 2070 2071@smallexample 2072(@value{GDBP}) b bubble(@kbd{M-?} 2073bubble(int) bubble(double) 2074(@value{GDBP}) b bubble(dou@kbd{M-?} 2075bubble(double) 2076@end smallexample 2077 2078See @ref{quoting names} for a description of other scenarios that 2079require quoting. 2080 2081For more information about overloaded functions, see @ref{C Plus Plus 2082Expressions, ,C@t{++} Expressions}. You can use the command @code{set 2083overload-resolution off} to disable overload resolution; 2084see @ref{Debugging C Plus Plus, ,@value{GDBN} Features for C@t{++}}. 2085 2086@cindex completion of structure field names 2087@cindex structure field name completion 2088@cindex completion of union field names 2089@cindex union field name completion 2090When completing in an expression which looks up a field in a 2091structure, @value{GDBN} also tries@footnote{The completer can be 2092confused by certain kinds of invalid expressions. Also, it only 2093examines the static type of the expression, not the dynamic type.} to 2094limit completions to the field names available in the type of the 2095left-hand-side: 2096 2097@smallexample 2098(@value{GDBP}) p gdb_stdout.@kbd{M-?} 2099magic to_fputs to_rewind 2100to_data to_isatty to_write 2101to_delete to_put to_write_async_safe 2102to_flush to_read 2103@end smallexample 2104 2105@noindent 2106This is because the @code{gdb_stdout} is a variable of the type 2107@code{struct ui_file} that is defined in @value{GDBN} sources as 2108follows: 2109 2110@smallexample 2111struct ui_file 2112@{ 2113 int *magic; 2114 ui_file_flush_ftype *to_flush; 2115 ui_file_write_ftype *to_write; 2116 ui_file_write_async_safe_ftype *to_write_async_safe; 2117 ui_file_fputs_ftype *to_fputs; 2118 ui_file_read_ftype *to_read; 2119 ui_file_delete_ftype *to_delete; 2120 ui_file_isatty_ftype *to_isatty; 2121 ui_file_rewind_ftype *to_rewind; 2122 ui_file_put_ftype *to_put; 2123 void *to_data; 2124@} 2125@end smallexample 2126 2127@node Filename Arguments 2128@section Filenames As Command Arguments 2129@cindex file names, quoting and escaping 2130 2131When passing filenames (or directory names) as arguments to a command, 2132if the filename argument does not include any whitespace, double 2133quotes, or single quotes, then for all commands the filename can be 2134written as a simple string, for example: 2135 2136@smallexample 2137(@value{GDBP}) file /path/to/some/file 2138@end smallexample 2139 2140If the filename does include whitespace, double quotes, or single 2141quotes, then @value{GDBN} has two approaches for how these filenames 2142should be formatted; which format to use depends on which command is 2143being used. 2144 2145Most @value{GDBN} commands don't require, or support, quoting and 2146escaping. These commands treat any text after the command name, that 2147is not a command option (@pxref{Command Options}), as the filename, 2148even if the filename contains whitespace or quote characters. In the 2149following example the user is adding @w{@file{/path/that contains/two 2150spaces/}} to the auto-load safe-path (@pxref{add-auto-load-safe-path}): 2151 2152@smallexample 2153(@value{GDBP}) add-auto-load-safe-path /path/that contains/two spaces/ 2154@end smallexample 2155 2156A small number of commands require that filenames containing 2157whitespace or quote characters are either quoted, or have the special 2158characters escaped with a backslash. Commands that support this style 2159are marked as such in the manual, any command not marked as accepting 2160quoting and escaping of its filename argument, does not accept this 2161filename argument style. 2162 2163For example, to load the file @w{@file{/path/with spaces/to/a file}} 2164with the @code{file} command (@pxref{Files, ,Commands to Specify 2165Files}), you can escape the whitespace characters with a backslash: 2166 2167@smallexample 2168(@value{GDBP}) file /path/with\ spaces/to/a\ file 2169@end smallexample 2170 2171Alternatively the entire filename can be wrapped in either single or 2172double quotes, in which case no backlsashes are needed, for example: 2173 2174@smallexample 2175(@value{GDBP}) symbol-file "/path/with spaces/to/a file" 2176(@value{GDBP}) exec-file '/path/with spaces/to/a file' 2177@end smallexample 2178 2179It is possible to include a quote character within a quoted filename 2180by escaping it with a backslash, for example, within a filename 2181surrounded by double quotes, a double quote character should be 2182escaped with a backslash, but a single quote character should not be 2183escaped. Within a single quoted string a single quote character needs 2184to be escaped, but a double quote character does not. 2185 2186A literal backslash character can also be included by escaping it with 2187a backslash. 2188 2189@node Command Options 2190@section Command options 2191 2192@cindex command options 2193Some commands accept options starting with a leading dash. For 2194example, @code{print -pretty}. Similarly to command names, you can 2195abbreviate a @value{GDBN} option to the first few letters of the 2196option name, if that abbreviation is unambiguous, and you can also use 2197the @key{TAB} key to get @value{GDBN} to fill out the rest of a word 2198in an option (or to show you the alternatives available, if there is 2199more than one possibility). 2200 2201@cindex command options, raw input 2202Some commands take raw input as argument. For example, the print 2203command processes arbitrary expressions in any of the languages 2204supported by @value{GDBN}. With such commands, because raw input may 2205start with a leading dash that would be confused with an option or any 2206of its abbreviations, e.g.@: @code{print -p} (short for @code{print 2207-pretty} or printing negative @code{p}?), if you specify any command 2208option, then you must use a double-dash (@code{--}) delimiter to 2209indicate the end of options. 2210 2211@cindex command options, boolean 2212 2213Some options are described as accepting an argument which can be 2214either @code{on} or @code{off}. These are known as @dfn{boolean 2215options}. Similarly to boolean settings commands---@code{on} and 2216@code{off} are the typical values, but any of @code{1}, @code{yes} and 2217@code{enable} can also be used as ``true'' value, and any of @code{0}, 2218@code{no} and @code{disable} can also be used as ``false'' value. You 2219can also omit a ``true'' value, as it is implied by default. 2220 2221For example, these are equivalent: 2222 2223@smallexample 2224(@value{GDBP}) print -object on -pretty off -element unlimited -- *myptr 2225(@value{GDBP}) p -o -p 0 -e u -- *myptr 2226@end smallexample 2227 2228You can discover the set of options some command accepts by completing 2229on @code{-} after the command name. For example: 2230 2231@smallexample 2232(@value{GDBP}) print -@key{TAB}@key{TAB} 2233-address -max-depth -object -static-members 2234-array -memory-tag-violations -pretty -symbol 2235-array-indexes -nibbles -raw-values -union 2236-elements -null-stop -repeats -vtbl 2237@end smallexample 2238 2239Completion will in some cases guide you with a suggestion of what kind 2240of argument an option expects. For example: 2241 2242@smallexample 2243(@value{GDBP}) print -elements @key{TAB}@key{TAB} 2244NUMBER unlimited 2245@end smallexample 2246 2247@noindent 2248Here, the option expects a number (e.g., @code{100}), not literal 2249@code{NUMBER}. Such metasyntactical arguments are always presented in 2250uppercase. 2251 2252(For more on using the @code{print} command, see @ref{Data, ,Examining 2253Data}.) 2254 2255@node Help 2256@section Getting Help 2257@cindex online documentation 2258@kindex help 2259 2260You can always ask @value{GDBN} itself for information on its commands, 2261using the command @code{help}. 2262 2263@table @code 2264@kindex h @r{(@code{help})} 2265@item help 2266@itemx h 2267You can use @code{help} (abbreviated @code{h}) with no arguments to 2268display a short list of named classes of commands: 2269 2270@smallexample 2271(@value{GDBP}) help 2272List of classes of commands: 2273 2274aliases -- User-defined aliases of other commands 2275breakpoints -- Making program stop at certain points 2276data -- Examining data 2277files -- Specifying and examining files 2278internals -- Maintenance commands 2279obscure -- Obscure features 2280running -- Running the program 2281stack -- Examining the stack 2282status -- Status inquiries 2283support -- Support facilities 2284tracepoints -- Tracing of program execution without 2285 stopping the program 2286user-defined -- User-defined commands 2287 2288Type "help" followed by a class name for a list of 2289commands in that class. 2290Type "help" followed by command name for full 2291documentation. 2292Command name abbreviations are allowed if unambiguous. 2293(@value{GDBP}) 2294@end smallexample 2295@c the above line break eliminates huge line overfull... 2296 2297@item help @var{class} 2298Using one of the general help classes as an argument, you can get a 2299list of the individual commands in that class. If a command has 2300aliases, the aliases are given after the command name, separated by 2301commas. If an alias has default arguments, the full definition of 2302the alias is given after the first line. 2303For example, here is the help display for the class @code{status}: 2304 2305@smallexample 2306(@value{GDBP}) help status 2307Status inquiries. 2308 2309List of commands: 2310 2311@c Line break in "show" line falsifies real output, but needed 2312@c to fit in smallbook page size. 2313info, inf, i -- Generic command for showing things 2314 about the program being debugged 2315info address, iamain -- Describe where symbol SYM is stored. 2316 alias iamain = info address main 2317info all-registers -- List of all registers and their contents, 2318 for selected stack frame. 2319... 2320show, info set -- Generic command for showing things 2321 about the debugger 2322 2323Type "help" followed by command name for full 2324documentation. 2325Command name abbreviations are allowed if unambiguous. 2326(@value{GDBP}) 2327@end smallexample 2328 2329@item help @var{command} 2330With a command name as @code{help} argument, @value{GDBN} displays a 2331short paragraph on how to use that command. If that command has 2332one or more aliases, @value{GDBN} will display a first line with 2333the command name and all its aliases separated by commas. 2334This first line will be followed by the full definition of all aliases 2335having default arguments. 2336When asking the help for an alias, the documentation for the aliased 2337command is shown. 2338 2339A user-defined alias can optionally be documented using the 2340@code{document} command (@pxref{Define, document}). @value{GDBN} then 2341considers this alias as different from the aliased command: this alias 2342is not listed in the aliased command help output, and asking help for 2343this alias will show the documentation provided for the alias instead of 2344the documentation of the aliased command. 2345 2346@kindex apropos 2347@item apropos [-v] @var{regexp} 2348The @code{apropos} command searches through all of the @value{GDBN} 2349commands and aliases, and their documentation, for the regular expression specified in 2350@var{args}. It prints out all matches found. The optional flag @samp{-v}, 2351which stands for @samp{verbose}, indicates to output the full documentation 2352of the matching commands and highlight the parts of the documentation 2353matching @var{regexp}. For example: 2354 2355@smallexample 2356apropos alias 2357@end smallexample 2358 2359@noindent 2360results in: 2361 2362@smallexample 2363@group 2364alias -- Define a new command that is an alias of an existing command 2365aliases -- User-defined aliases of other commands 2366@end group 2367@end smallexample 2368 2369@noindent 2370while 2371 2372@smallexample 2373apropos -v cut.*thread apply 2374@end smallexample 2375 2376@noindent 2377results in the below output, where @samp{cut for 'thread apply} 2378is highlighted if styling is enabled. 2379 2380@smallexample 2381@group 2382taas -- Apply a command to all threads (ignoring errors 2383and empty output). 2384Usage: taas COMMAND 2385shortcut for 'thread apply all -s COMMAND' 2386 2387tfaas -- Apply a command to all frames of all threads 2388(ignoring errors and empty output). 2389Usage: tfaas COMMAND 2390shortcut for 'thread apply all -s frame apply all -s COMMAND' 2391@end group 2392@end smallexample 2393 2394@kindex complete 2395@item complete @var{args} 2396The @code{complete @var{args}} command lists all the possible completions 2397for the beginning of a command. Use @var{args} to specify the beginning of the 2398command you want completed. For example: 2399 2400@smallexample 2401complete i 2402@end smallexample 2403 2404@noindent results in: 2405 2406@smallexample 2407@group 2408if 2409ignore 2410info 2411inspect 2412@end group 2413@end smallexample 2414 2415@noindent This is intended for use by @sc{gnu} Emacs. 2416@end table 2417 2418In addition to @code{help}, you can use the @value{GDBN} commands @code{info} 2419and @code{show} to inquire about the state of your program, or the state 2420of @value{GDBN} itself. Each command supports many topics of inquiry; this 2421manual introduces each of them in the appropriate context. The listings 2422under @code{info} and under @code{show} in the Command, Variable, and 2423Function Index point to all the sub-commands. @xref{Command and Variable 2424Index}. 2425 2426@c @group 2427@table @code 2428@kindex info 2429@kindex i @r{(@code{info})} 2430@item info 2431This command (abbreviated @code{i}) is for describing the state of your 2432program. For example, you can show the arguments passed to a function 2433with @code{info args}, list the registers currently in use with @code{info 2434registers}, or list the breakpoints you have set with @code{info breakpoints}. 2435You can get a complete list of the @code{info} sub-commands with 2436@w{@code{help info}}. 2437 2438@kindex set 2439@item set 2440You can assign the result of an expression to an environment variable with 2441@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with 2442@code{set prompt $}. 2443 2444@kindex show 2445@item show 2446In contrast to @code{info}, @code{show} is for describing the state of 2447@value{GDBN} itself. 2448You can change most of the things you can @code{show}, by using the 2449related command @code{set}; for example, you can control what number 2450system is used for displays with @code{set radix}, or simply inquire 2451which is currently in use with @code{show radix}. 2452 2453@kindex info set 2454To display all the settable parameters and their current 2455values, you can use @code{show} with no arguments; you may also use 2456@code{info set}. Both commands produce the same display. 2457@c FIXME: "info set" violates the rule that "info" is for state of 2458@c FIXME...program. Ck w/ GNU: "info set" to be called something else, 2459@c FIXME...or change desc of rule---eg "state of prog and debugging session"? 2460@end table 2461@c @end group 2462 2463Here are several miscellaneous @code{show} subcommands, all of which are 2464exceptional in lacking corresponding @code{set} commands: 2465 2466@table @code 2467@kindex show version 2468@cindex @value{GDBN} version number 2469@item show version 2470Show what version of @value{GDBN} is running. You should include this 2471information in @value{GDBN} bug-reports. If multiple versions of 2472@value{GDBN} are in use at your site, you may need to determine which 2473version of @value{GDBN} you are running; as @value{GDBN} evolves, new 2474commands are introduced, and old ones may wither away. Also, many 2475system vendors ship variant versions of @value{GDBN}, and there are 2476variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well. 2477The version number is the same as the one announced when you start 2478@value{GDBN}. 2479 2480@kindex show copying 2481@kindex info copying 2482@cindex display @value{GDBN} copyright 2483@item show copying 2484@itemx info copying 2485Display information about permission for copying @value{GDBN}. 2486 2487@kindex show warranty 2488@kindex info warranty 2489@item show warranty 2490@itemx info warranty 2491Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty, 2492if your version of @value{GDBN} comes with one. 2493 2494@kindex show configuration 2495@item show configuration 2496Display detailed information about the way @value{GDBN} was configured 2497when it was built. This displays the optional arguments passed to the 2498@file{configure} script and also configuration parameters detected 2499automatically by @command{configure}. When reporting a @value{GDBN} 2500bug (@pxref{GDB Bugs}), it is important to include this information in 2501your report. 2502 2503@end table 2504 2505@node Running 2506@chapter Running Programs Under @value{GDBN} 2507 2508When you run a program under @value{GDBN}, you must first generate 2509debugging information when you compile it. 2510 2511You may start @value{GDBN} with its arguments, if any, in an environment 2512of your choice. If you are doing native debugging, you may redirect 2513your program's input and output, debug an already running process, or 2514kill a child process. 2515 2516@menu 2517* Compilation:: Compiling for debugging 2518* Starting:: Starting your program 2519* Arguments:: Your program's arguments 2520* Environment:: Your program's environment 2521 2522* Working Directory:: Your program's working directory 2523* Input/Output:: Your program's input and output 2524* Attach:: Debugging an already-running process 2525* Kill Process:: Killing the child process 2526* Inferiors Connections and Programs:: Debugging multiple inferiors 2527 connections and programs 2528* Threads:: Debugging programs with multiple threads 2529* Forks:: Debugging forks 2530* Checkpoint/Restart:: Setting a @emph{bookmark} to return to later 2531@end menu 2532 2533@node Compilation 2534@section Compiling for Debugging 2535 2536In order to debug a program effectively, you need to generate 2537debugging information when you compile it. This debugging information 2538is stored in the object file; it describes the data type of each 2539variable or function and the correspondence between source line numbers 2540and addresses in the executable code. 2541 2542To request debugging information, specify the @samp{-g} option when you run 2543the compiler. 2544 2545Programs that are to be shipped to your customers are compiled with 2546optimizations, using the @samp{-O} compiler option. However, some 2547compilers are unable to handle the @samp{-g} and @samp{-O} options 2548together. Using those compilers, you cannot generate optimized 2549executables containing debugging information. 2550 2551@value{NGCC}, the @sc{gnu} C/C@t{++} compiler, supports @samp{-g} with or 2552without @samp{-O}, making it possible to debug optimized code. We 2553recommend that you @emph{always} use @samp{-g} whenever you compile a 2554program. You may think your program is correct, but there is no sense 2555in pushing your luck. For more information, see @ref{Optimized Code}. 2556 2557Older versions of the @sc{gnu} C compiler permitted a variant option 2558@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this 2559format; if your @sc{gnu} C compiler has this option, do not use it. 2560 2561@value{GDBN} knows about preprocessor macros and can show you their 2562expansion (@pxref{Macros}). Most compilers do not include information 2563about preprocessor macros in the debugging information if you specify 2564the @option{-g} flag alone. Version 3.1 and later of @value{NGCC}, 2565the @sc{gnu} C compiler, provides macro information if you are using 2566the DWARF debugging format, and specify the option @option{-g3}. 2567 2568@xref{Debugging Options,,Options for Debugging Your Program or GCC, 2569gcc, Using the @sc{gnu} Compiler Collection (GCC)}, for more 2570information on @value{NGCC} options affecting debug information. 2571 2572You will have the best debugging experience if you use the latest 2573version of the DWARF debugging format that your compiler supports. 2574DWARF is currently the most expressive and best supported debugging 2575format in @value{GDBN}. 2576 2577@need 2000 2578@node Starting 2579@section Starting your Program 2580@cindex starting 2581@cindex running 2582 2583@table @code 2584@kindex run 2585@kindex r @r{(@code{run})} 2586@item run 2587@itemx r 2588Use the @code{run} command to start your program under @value{GDBN}. 2589You must first specify the program name with an argument to 2590@value{GDBN} (@pxref{Invocation, ,Getting In and Out of 2591@value{GDBN}}), or by using the @code{file} or @code{exec-file} 2592command (@pxref{Files, ,Commands to Specify Files}). 2593 2594@end table 2595 2596If you are running your program in an execution environment that 2597supports processes, @code{run} creates an inferior process and makes 2598that process run your program. In some environments without processes, 2599@code{run} jumps to the start of your program. Other targets, 2600like @samp{remote}, are always running. If you get an error 2601message like this one: 2602 2603@smallexample 2604The "remote" target does not support "run". 2605Try "help target" or "continue". 2606@end smallexample 2607 2608@noindent 2609then use @code{continue} to run your program. You may need @code{load} 2610first (@pxref{load}). 2611 2612The execution of a program is affected by certain information it 2613receives from its superior. @value{GDBN} provides ways to specify this 2614information, which you must do @emph{before} starting your program. (You 2615can change it after starting your program, but such changes only affect 2616your program the next time you start it.) This information may be 2617divided into four categories: 2618 2619@table @asis 2620@item The @emph{arguments.} 2621Specify the arguments to give your program as the arguments of the 2622@code{run} command. If a shell is available on your target, the shell 2623is used to pass the arguments, so that you may use normal conventions 2624(such as wildcard expansion or variable substitution) in describing 2625the arguments. 2626In Unix systems, you can control which shell is used with the 2627@env{SHELL} environment variable. If you do not define @env{SHELL}, 2628@value{GDBN} uses the default shell (@file{/bin/sh}). You can disable 2629use of any shell with the @code{set startup-with-shell} command (see 2630below for details). 2631 2632@item The @emph{environment.} 2633Your program normally inherits its environment from @value{GDBN}, but you can 2634use the @value{GDBN} commands @code{set environment} and @code{unset 2635environment} to change parts of the environment that affect 2636your program. @xref{Environment, ,Your Program's Environment}. 2637 2638@item The @emph{working directory.} 2639You can set your program's working directory with the command 2640@kbd{set cwd}. If you do not set any working directory with this 2641command, your program will inherit @value{GDBN}'s working directory if 2642native debugging, or the remote server's working directory if remote 2643debugging. @xref{Working Directory, ,Your Program's Working 2644Directory}. 2645 2646@item The @emph{standard input and output.} 2647Your program normally uses the same device for standard input and 2648standard output as @value{GDBN} is using. You can redirect input and output 2649in the @code{run} command line, or you can use the @code{tty} command to 2650set a different device for your program. 2651@xref{Input/Output, ,Your Program's Input and Output}. 2652 2653@cindex pipes 2654@emph{Warning:} While input and output redirection work, you cannot use 2655pipes to pass the output of the program you are debugging to another 2656program; if you attempt this, @value{GDBN} is likely to wind up debugging the 2657wrong program. 2658@end table 2659 2660When you issue the @code{run} command, your program begins to execute 2661immediately. @xref{Stopping, ,Stopping and Continuing}, for discussion 2662of how to arrange for your program to stop. Once your program has 2663stopped, you may call functions in your program, using the @code{print} 2664or @code{call} commands. @xref{Data, ,Examining Data}. 2665 2666If the modification time of your symbol file has changed since the last 2667time @value{GDBN} read its symbols, @value{GDBN} discards its symbol 2668table, and reads it again. When it does this, @value{GDBN} tries to retain 2669your current breakpoints. 2670 2671@table @code 2672@kindex start 2673@item start 2674@cindex run to main procedure 2675The name of the main procedure can vary from language to language. 2676With C or C@t{++}, the main procedure name is always @code{main}, but 2677other languages such as Ada do not require a specific name for their 2678main procedure. The debugger provides a convenient way to start the 2679execution of the program and to stop at the beginning of the main 2680procedure, depending on the language used. 2681 2682The @samp{start} command does the equivalent of setting a temporary 2683breakpoint at the beginning of the main procedure and then invoking 2684the @samp{run} command. 2685 2686@cindex elaboration phase 2687Some programs contain an @dfn{elaboration} phase where some startup code is 2688executed before the main procedure is called. This depends on the 2689languages used to write your program. In C@t{++}, for instance, 2690constructors for static and global objects are executed before 2691@code{main} is called. It is therefore possible that the debugger stops 2692before reaching the main procedure. However, the temporary breakpoint 2693will remain to halt execution. 2694 2695Specify the arguments to give to your program as arguments to the 2696@samp{start} command. These arguments will be given verbatim to the 2697underlying @samp{run} command. Note that the same arguments will be 2698reused if no argument is provided during subsequent calls to 2699@samp{start} or @samp{run}. 2700 2701It is sometimes necessary to debug the program during elaboration. In 2702these cases, using the @code{start} command would stop the execution 2703of your program too late, as the program would have already completed 2704the elaboration phase. Under these circumstances, either insert 2705breakpoints in your elaboration code before running your program or 2706use the @code{starti} command. 2707 2708@kindex starti 2709@item starti 2710@cindex run to first instruction 2711The @samp{starti} command does the equivalent of setting a temporary 2712breakpoint at the first instruction of a program's execution and then 2713invoking the @samp{run} command. For programs containing an 2714elaboration phase, the @code{starti} command will stop execution at 2715the start of the elaboration phase. 2716 2717@anchor{set exec-wrapper} 2718@kindex set exec-wrapper 2719@item set exec-wrapper @var{wrapper} 2720@itemx show exec-wrapper 2721@itemx unset exec-wrapper 2722When @samp{exec-wrapper} is set, the specified wrapper is used to 2723launch programs for debugging. @value{GDBN} starts your program 2724with a shell command of the form @kbd{exec @var{wrapper} 2725@var{program}}. Quoting is added to @var{program} and its 2726arguments, but not to @var{wrapper}, so you should add quotes if 2727appropriate for your shell. The wrapper runs until it executes 2728your program, and then @value{GDBN} takes control. 2729 2730You can use any program that eventually calls @code{execve} with 2731its arguments as a wrapper. Several standard Unix utilities do 2732this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending 2733with @code{exec "$@@"} will also work. 2734 2735For example, you can use @code{env} to pass an environment variable to 2736the debugged program, without setting the variable in your shell's 2737environment: 2738 2739@smallexample 2740(@value{GDBP}) set exec-wrapper env 'LD_PRELOAD=libtest.so' 2741(@value{GDBP}) run 2742@end smallexample 2743 2744This command is available when debugging locally on most targets, excluding 2745@sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino. 2746 2747@kindex set startup-with-shell 2748@anchor{set startup-with-shell} 2749@item set startup-with-shell 2750@itemx set startup-with-shell on 2751@itemx set startup-with-shell off 2752@itemx show startup-with-shell 2753On Unix systems, by default, if a shell is available on your target, 2754@value{GDBN}) uses it to start your program. Arguments of the 2755@code{run} command are passed to the shell, which does variable 2756substitution, expands wildcard characters and performs redirection of 2757I/O. In some circumstances, it may be useful to disable such use of a 2758shell, for example, when debugging the shell itself or diagnosing 2759startup failures such as: 2760 2761@smallexample 2762(@value{GDBP}) run 2763Starting program: ./a.out 2764During startup program terminated with signal SIGSEGV, Segmentation fault. 2765@end smallexample 2766 2767@noindent 2768which indicates the shell or the wrapper specified with 2769@samp{exec-wrapper} crashed, not your program. Most often, this is 2770caused by something odd in your shell's non-interactive mode 2771initialization file---such as @file{.cshrc} for C-shell, 2772$@file{.zshenv} for the Z shell, or the file specified in the 2773@env{BASH_ENV} environment variable for BASH. 2774 2775@anchor{set auto-connect-native-target} 2776@kindex set auto-connect-native-target 2777@item set auto-connect-native-target 2778@itemx set auto-connect-native-target on 2779@itemx set auto-connect-native-target off 2780@itemx show auto-connect-native-target 2781 2782By default, if the current inferior is not connected to any target yet 2783(e.g., with @code{target remote}), the @code{run} command starts your 2784program as a native process under @value{GDBN}, on your local machine. 2785If you're sure you don't want to debug programs on your local machine, 2786you can tell @value{GDBN} to not connect to the native target 2787automatically with the @code{set auto-connect-native-target off} 2788command. 2789 2790If @code{on}, which is the default, and if the current inferior is not 2791connected to a target already, the @code{run} command automatically 2792connects to the native target, if one is available. 2793 2794If @code{off}, and if the current inferior is not connected to a 2795target already, the @code{run} command fails with an error: 2796 2797@smallexample 2798(@value{GDBP}) run 2799Don't know how to run. Try "help target". 2800@end smallexample 2801 2802If the current inferior is already connected to a target, @value{GDBN} 2803always uses it with the @code{run} command. 2804 2805In any case, you can explicitly connect to the native target with the 2806@code{target native} command. For example, 2807 2808@smallexample 2809(@value{GDBP}) set auto-connect-native-target off 2810(@value{GDBP}) run 2811Don't know how to run. Try "help target". 2812(@value{GDBP}) target native 2813(@value{GDBP}) run 2814Starting program: ./a.out 2815[Inferior 1 (process 10421) exited normally] 2816@end smallexample 2817 2818In case you connected explicitly to the @code{native} target, 2819@value{GDBN} remains connected even if all inferiors exit, ready for 2820the next @code{run} command. Use the @code{disconnect} command to 2821disconnect. 2822 2823Examples of other commands that likewise respect the 2824@code{auto-connect-native-target} setting: @code{attach}, @code{info 2825proc}, @code{info os}. 2826 2827@kindex set disable-randomization 2828@item set disable-randomization 2829@itemx set disable-randomization on 2830This option (enabled by default in @value{GDBN}) will turn off the native 2831randomization of the virtual address space of the started program. This option 2832is useful for multiple debugging sessions to make the execution better 2833reproducible and memory addresses reusable across debugging sessions. 2834 2835This feature is implemented only on certain targets, including @sc{gnu}/Linux. 2836On @sc{gnu}/Linux you can get the same behavior using 2837 2838@smallexample 2839(@value{GDBP}) set exec-wrapper setarch `uname -m` -R 2840@end smallexample 2841 2842@item set disable-randomization off 2843Leave the behavior of the started executable unchanged. Some bugs rear their 2844ugly heads only when the program is loaded at certain addresses. If your bug 2845disappears when you run the program under @value{GDBN}, that might be because 2846@value{GDBN} by default disables the address randomization on platforms, such 2847as @sc{gnu}/Linux, which do that for stand-alone programs. Use @kbd{set 2848disable-randomization off} to try to reproduce such elusive bugs. 2849 2850On targets where it is available, virtual address space randomization 2851protects the programs against certain kinds of security attacks. In these 2852cases the attacker needs to know the exact location of a concrete executable 2853code. Randomizing its location makes it impossible to inject jumps misusing 2854a code at its expected addresses. 2855 2856Prelinking shared libraries provides a startup performance advantage but it 2857makes addresses in these libraries predictable for privileged processes by 2858having just unprivileged access at the target system. Reading the shared 2859library binary gives enough information for assembling the malicious code 2860misusing it. Still even a prelinked shared library can get loaded at a new 2861random address just requiring the regular relocation process during the 2862startup. Shared libraries not already prelinked are always loaded at 2863a randomly chosen address. 2864 2865Position independent executables (PIE) contain position independent code 2866similar to the shared libraries and therefore such executables get loaded at 2867a randomly chosen address upon startup. PIE executables always load even 2868already prelinked shared libraries at a random address. You can build such 2869executable using @command{gcc -fPIE -pie}. 2870 2871Heap (malloc storage), stack and custom mmap areas are always placed randomly 2872(as long as the randomization is enabled). 2873 2874@item show disable-randomization 2875Show the current setting of the explicit disable of the native randomization of 2876the virtual address space of the started program. 2877 2878@end table 2879 2880@node Arguments 2881@section Your Program's Arguments 2882 2883@cindex arguments (to your program) 2884The arguments to your program can be specified by the arguments of the 2885@code{run} command. 2886They are passed to a shell, which expands wildcard characters and 2887performs redirection of I/O, and thence to your program. Your 2888@env{SHELL} environment variable (if it exists) specifies what shell 2889@value{GDBN} uses. If you do not define @env{SHELL}, @value{GDBN} uses 2890the default shell (@file{/bin/sh} on Unix). 2891 2892On non-Unix systems, the program is usually invoked directly by 2893@value{GDBN}, which emulates I/O redirection via the appropriate system 2894calls, and the wildcard characters are expanded by the startup code of 2895the program, not by the shell. 2896 2897@code{run} with no arguments uses the same arguments used by the previous 2898@code{run}, or those set by the @code{set args} command. 2899 2900@table @code 2901@kindex set args 2902@item set args 2903Specify the arguments to be used the next time your program is run. If 2904@code{set args} has no arguments, @code{run} executes your program 2905with no arguments. Once you have run your program with arguments, 2906using @code{set args} before the next @code{run} is the only way to run 2907it again without arguments. 2908 2909@kindex show args 2910@item show args 2911Show the arguments to give your program when it is started. 2912@end table 2913 2914@node Environment 2915@section Your Program's Environment 2916 2917@cindex environment (of your program) 2918The @dfn{environment} consists of a set of environment variables and 2919their values. Environment variables conventionally record such things as 2920your user name, your home directory, your terminal type, and your search 2921path for programs to run. Usually you set up environment variables with 2922the shell and they are inherited by all the other programs you run. When 2923debugging, it can be useful to try running your program with a modified 2924environment without having to start @value{GDBN} over again. 2925 2926@table @code 2927@kindex path 2928@item path @var{directory} 2929Add @var{directory} to the front of the @env{PATH} environment variable 2930(the search path for executables) that will be passed to your program. 2931The value of @env{PATH} used by @value{GDBN} does not change. 2932You may specify several directory names, separated by whitespace or by a 2933system-dependent separator character (@samp{:} on Unix, @samp{;} on 2934MS-DOS and MS-Windows). If @var{directory} is already in the path, it 2935is moved to the front, so it is searched sooner. 2936 2937You can use the string @samp{$cwd} to refer to whatever is the current 2938working directory at the time @value{GDBN} searches the path. If you 2939use @samp{.} instead, it refers to the directory where you executed the 2940@code{path} command. @value{GDBN} replaces @samp{.} in the 2941@var{directory} argument (with the current path) before adding 2942@var{directory} to the search path. 2943@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to 2944@c document that, since repeating it would be a no-op. 2945 2946@kindex show paths 2947@item show paths 2948Display the list of search paths for executables (the @env{PATH} 2949environment variable). 2950 2951@kindex show environment 2952@item show environment @r{[}@var{varname}@r{]} 2953Print the value of environment variable @var{varname} to be given to 2954your program when it starts. If you do not supply @var{varname}, 2955print the names and values of all environment variables to be given to 2956your program. You can abbreviate @code{environment} as @code{env}. 2957 2958@kindex set environment 2959@anchor{set environment} 2960@item set environment @var{varname} @r{[}=@var{value}@r{]} 2961Set environment variable @var{varname} to @var{value}. The value 2962changes for your program (and the shell @value{GDBN} uses to launch 2963it), not for @value{GDBN} itself. The @var{value} may be any string; the 2964values of environment variables are just strings, and any 2965interpretation is supplied by your program itself. The @var{value} 2966parameter is optional; if it is eliminated, the variable is set to a 2967null value. 2968@c "any string" here does not include leading, trailing 2969@c blanks. Gnu asks: does anyone care? 2970 2971For example, this command: 2972 2973@smallexample 2974set env USER = foo 2975@end smallexample 2976 2977@noindent 2978tells the debugged program, when subsequently run, that its user is named 2979@samp{foo}. (The spaces around @samp{=} are used for clarity here; they 2980are not actually required.) 2981 2982Note that on Unix systems, @value{GDBN} runs your program via a shell, 2983which also inherits the environment set with @code{set environment}. 2984If necessary, you can avoid that by using the @samp{env} program as a 2985wrapper instead of using @code{set environment}. @xref{set 2986exec-wrapper}, for an example doing just that. 2987 2988Environment variables that are set by the user are also transmitted to 2989@command{gdbserver} to be used when starting the remote inferior. 2990@pxref{QEnvironmentHexEncoded}. 2991 2992@kindex unset environment 2993@anchor{unset environment} 2994@item unset environment @var{varname} 2995Remove variable @var{varname} from the environment to be passed to your 2996program. This is different from @samp{set env @var{varname} =}; 2997@code{unset environment} removes the variable from the environment, 2998rather than assigning it an empty value. 2999 3000Environment variables that are unset by the user are also unset on 3001@command{gdbserver} when starting the remote inferior. 3002@pxref{QEnvironmentUnset}. 3003@end table 3004 3005@emph{Warning:} On Unix systems, @value{GDBN} runs your program using 3006the shell indicated by your @env{SHELL} environment variable if it 3007exists (or @code{/bin/sh} if not). If your @env{SHELL} variable 3008names a shell that runs an initialization file when started 3009non-interactively---such as @file{.cshrc} for C-shell, $@file{.zshenv} 3010for the Z shell, or the file specified in the @env{BASH_ENV} 3011environment variable for BASH---any variables you set in that file 3012affect your program. You may wish to move setting of environment 3013variables to files that are only run when you sign on, such as 3014@file{.login} or @file{.profile}. 3015 3016@node Working Directory 3017@section Your Program's Working Directory 3018 3019@cindex working directory (of your program) 3020Each time you start your program with @code{run}, the inferior will be 3021initialized with the current working directory specified by the 3022@kbd{set cwd} command. If no directory has been specified by this 3023command, then the inferior will inherit @value{GDBN}'s current working 3024directory as its working directory if native debugging, or it will 3025inherit the remote server's current working directory if remote 3026debugging. 3027 3028@table @code 3029@kindex set cwd 3030@cindex change inferior's working directory 3031@anchor{set cwd command} 3032@item set cwd @r{[}@var{directory}@r{]} 3033Set the inferior's working directory to @var{directory}, which will be 3034@code{glob}-expanded in order to resolve tildes (@file{~}). If no 3035argument has been specified, the command clears the setting and resets 3036it to an empty state. This setting has no effect on @value{GDBN}'s 3037working directory, and it only takes effect the next time you start 3038the inferior. The @file{~} in @var{directory} is a short for the 3039@dfn{home directory}, usually pointed to by the @env{HOME} environment 3040variable. On MS-Windows, if @env{HOME} is not defined, @value{GDBN} 3041uses the concatenation of @env{HOMEDRIVE} and @env{HOMEPATH} as 3042fallback. 3043 3044You can also change @value{GDBN}'s current working directory by using 3045the @code{cd} command. 3046@xref{cd command}. 3047 3048@kindex show cwd 3049@cindex show inferior's working directory 3050@item show cwd 3051Show the inferior's working directory. If no directory has been 3052specified by @kbd{set cwd}, then the default inferior's working 3053directory is the same as @value{GDBN}'s working directory. 3054 3055@kindex cd 3056@cindex change @value{GDBN}'s working directory 3057@anchor{cd command} 3058@item cd @r{[}@var{directory}@r{]} 3059Set the @value{GDBN} working directory to @var{directory}. If not 3060given, @var{directory} uses @file{'~'}. 3061 3062The @value{GDBN} working directory serves as a default for the 3063commands that specify files for @value{GDBN} to operate on. 3064@xref{Files, ,Commands to Specify Files}. 3065@xref{set cwd command}. 3066 3067@kindex pwd 3068@item pwd 3069Print the @value{GDBN} working directory. 3070@end table 3071 3072It is generally impossible to find the current working directory of 3073the process being debugged (since a program can change its directory 3074during its run). If you work on a system where @value{GDBN} supports 3075the @code{info proc} command (@pxref{Process Information}), you can 3076use the @code{info proc} command to find out the 3077current working directory of the debuggee. 3078 3079@node Input/Output 3080@section Your Program's Input and Output 3081 3082@cindex redirection 3083@cindex i/o 3084@cindex terminal 3085By default, the program you run under @value{GDBN} does input and output to 3086the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal 3087to its own terminal modes to interact with you, but it records the terminal 3088modes your program was using and switches back to them when you continue 3089running your program. 3090 3091@table @code 3092@kindex info terminal 3093@item info terminal 3094Displays information recorded by @value{GDBN} about the terminal modes your 3095program is using. 3096@end table 3097 3098You can redirect your program's input and/or output using shell 3099redirection with the @code{run} command. For example, 3100 3101@smallexample 3102run > outfile 3103@end smallexample 3104 3105@noindent 3106starts your program, diverting its output to the file @file{outfile}. 3107 3108@kindex tty 3109@cindex controlling terminal 3110Another way to specify where your program should do input and output is 3111with the @code{tty} command. This command accepts a file name as 3112argument, and causes this file to be the default for future @code{run} 3113commands. It also resets the controlling terminal for the child 3114process, for future @code{run} commands. For example, 3115 3116@smallexample 3117tty /dev/ttyb 3118@end smallexample 3119 3120@noindent 3121directs that processes started with subsequent @code{run} commands 3122default to do input and output on the terminal @file{/dev/ttyb} and have 3123that as their controlling terminal. 3124 3125An explicit redirection in @code{run} overrides the @code{tty} command's 3126effect on the input/output device, but not its effect on the controlling 3127terminal. 3128 3129When you use the @code{tty} command or redirect input in the @code{run} 3130command, only the input @emph{for your program} is affected. The input 3131for @value{GDBN} still comes from your terminal. @code{tty} is an alias 3132for @code{set inferior-tty}. 3133 3134@cindex inferior tty 3135@cindex set inferior controlling terminal 3136You can use the @code{show inferior-tty} command to tell @value{GDBN} to 3137display the name of the terminal that will be used for future runs of your 3138program. 3139 3140@table @code 3141@item set inferior-tty [ @var{tty} ] 3142@kindex set inferior-tty 3143Set the tty for the program being debugged to @var{tty}. Omitting @var{tty} 3144restores the default behavior, which is to use the same terminal as 3145@value{GDBN}. 3146 3147@item show inferior-tty 3148@kindex show inferior-tty 3149Show the current tty for the program being debugged. 3150@end table 3151 3152@node Attach 3153@section Debugging an Already-running Process 3154@kindex attach 3155@cindex attach 3156 3157@table @code 3158@item attach @var{process-id} 3159This command attaches to a running process---one that was started 3160outside @value{GDBN}. (@code{info files} shows your active 3161targets.) The command takes as argument a process ID. The usual way to 3162find out the @var{process-id} of a Unix process is with the @code{ps} utility, 3163or with the @samp{jobs -l} shell command. 3164 3165@code{attach} does not repeat if you press @key{RET} a second time after 3166executing the command. 3167@end table 3168 3169To use @code{attach}, your program must be running in an environment 3170which supports processes; for example, @code{attach} does not work for 3171programs on bare-board targets that lack an operating system. You must 3172also have permission to send the process a signal. 3173 3174When you use @code{attach}, the debugger finds the program running in 3175the process first by looking in the current working directory, then (if 3176the program is not found) by using the source file search path 3177(@pxref{Source Path, ,Specifying Source Directories}). You can also use 3178the @code{file} command to load the program. @xref{Files, ,Commands to 3179Specify Files}. 3180 3181@anchor{set exec-file-mismatch} 3182If the debugger can determine that the executable file running in the 3183process it is attaching to does not match the current exec-file loaded 3184by @value{GDBN}, the option @code{exec-file-mismatch} specifies how to 3185handle the mismatch. @value{GDBN} tries to compare the files by 3186comparing their build IDs (@pxref{build ID}), if available. 3187 3188@table @code 3189@kindex exec-file-mismatch 3190@cindex set exec-file-mismatch 3191@item set exec-file-mismatch @samp{ask|warn|off} 3192 3193Whether to detect mismatch between the current executable file loaded 3194by @value{GDBN} and the executable file used to start the process. If 3195@samp{ask}, the default, display a warning and ask the user whether to 3196load the process executable file; if @samp{warn}, just display a 3197warning; if @samp{off}, don't attempt to detect a mismatch. 3198If the user confirms loading the process executable file, then its symbols 3199will be loaded as well. 3200 3201@cindex show exec-file-mismatch 3202@item show exec-file-mismatch 3203Show the current value of @code{exec-file-mismatch}. 3204 3205@end table 3206 3207The first thing @value{GDBN} does after arranging to debug the specified 3208process is to stop it. You can examine and modify an attached process 3209with all the @value{GDBN} commands that are ordinarily available when 3210you start processes with @code{run}. You can insert breakpoints; you 3211can step and continue; you can modify storage. If you would rather the 3212process continue running, you may use the @code{continue} command after 3213attaching @value{GDBN} to the process. 3214 3215@table @code 3216@kindex detach 3217@item detach 3218When you have finished debugging the attached process, you can use the 3219@code{detach} command to release it from @value{GDBN} control. Detaching 3220the process continues its execution. After the @code{detach} command, 3221that process and @value{GDBN} become completely independent once more, and you 3222are ready to @code{attach} another process or start one with @code{run}. 3223@code{detach} does not repeat if you press @key{RET} again after 3224executing the command. 3225@end table 3226 3227If you exit @value{GDBN} while you have an attached process, you detach 3228that process. If you use the @code{run} command, you kill that process. 3229By default, @value{GDBN} asks for confirmation if you try to do either of these 3230things; you can control whether or not you need to confirm by using the 3231@code{set confirm} command (@pxref{Messages/Warnings, ,Optional Warnings and 3232Messages}). 3233 3234@node Kill Process 3235@section Killing the Child Process 3236 3237@table @code 3238@kindex kill 3239@item kill 3240Kill the child process in which your program is running under @value{GDBN}. 3241@end table 3242 3243This command is useful if you wish to debug a core dump instead of a 3244running process. @value{GDBN} ignores any core dump file while your program 3245is running. 3246 3247On some operating systems, a program cannot be executed outside @value{GDBN} 3248while you have breakpoints set on it inside @value{GDBN}. You can use the 3249@code{kill} command in this situation to permit running your program 3250outside the debugger. 3251 3252The @code{kill} command is also useful if you wish to recompile and 3253relink your program, since on many systems it is impossible to modify an 3254executable file while it is running in a process. In this case, when you 3255next type @code{run}, @value{GDBN} notices that the file has changed, and 3256reads the symbol table again (while trying to preserve your current 3257breakpoint settings). 3258 3259@node Inferiors Connections and Programs 3260@section Debugging Multiple Inferiors Connections and Programs 3261 3262@value{GDBN} lets you run and debug multiple programs in a single 3263session. In addition, @value{GDBN} on some systems may let you run 3264several programs simultaneously (otherwise you have to exit from one 3265before starting another). On some systems @value{GDBN} may even let 3266you debug several programs simultaneously on different remote systems. 3267In the most general case, you can have multiple threads of execution 3268in each of multiple processes, launched from multiple executables, 3269running on different machines. 3270 3271@cindex inferior 3272@value{GDBN} represents the state of each program execution with an 3273object called an @dfn{inferior}. An inferior typically corresponds to 3274a process, but is more general and applies also to targets that do not 3275have processes. Inferiors may be created before a process runs, and 3276may be retained after a process exits. Inferiors have unique 3277identifiers that are different from process ids. Usually each 3278inferior will also have its own distinct address space, although some 3279embedded targets may have several inferiors running in different parts 3280of a single address space. Each inferior may in turn have multiple 3281threads running in it. 3282 3283@cindex ID list 3284The commands @code{info inferiors} and @code{info connections}, which will be 3285introduced below, accept a space-separated @dfn{ID list} as their argument 3286specifying one or more elements on which to operate. A list element can be 3287either a single non-negative number, like @samp{5}, or an ascending range of 3288such numbers, like @samp{5-7}. A list can consist of any combination of such 3289elements, even duplicates or overlapping ranges are valid. E.g.@: 3290@samp{1 4-6 5 4-4} or @samp{1 2 4-7}. 3291 3292To find out what inferiors exist at any moment, use @w{@code{info 3293inferiors}}: 3294 3295@table @code 3296@kindex info inferiors [ @var{id}@dots{} ] 3297@item info inferiors 3298Print a list of all inferiors currently being managed by @value{GDBN}. 3299By default all inferiors are printed, but the ID list @var{id}@dots{} can be 3300used to limit the display to just the requested inferiors. 3301 3302@value{GDBN} displays for each inferior (in this order): 3303 3304@enumerate 3305@item 3306the inferior number assigned by @value{GDBN} 3307 3308@item 3309the target system's inferior identifier 3310 3311@item 3312the target connection the inferior is bound to, including the unique 3313connection number assigned by @value{GDBN}, and the protocol used by 3314the connection. 3315 3316@item 3317the name of the executable the inferior is running. 3318 3319@end enumerate 3320 3321@noindent 3322An asterisk @samp{*} preceding the @value{GDBN} inferior number 3323indicates the current inferior. 3324 3325For example, 3326@end table 3327@c end table here to get a little more width for example 3328 3329@smallexample 3330(@value{GDBP}) info inferiors 3331 Num Description Connection Executable 3332* 1 process 3401 1 (native) goodbye 3333 2 process 2307 2 (extended-remote host:10000) hello 3334@end smallexample 3335 3336To get information about the current inferior, use @code{inferior}: 3337 3338@table @code 3339@kindex inferior 3340@item inferior 3341Shows information about the current inferior. 3342 3343For example, 3344@end table 3345@c end table here to get a little more width for example 3346 3347@smallexample 3348(@value{GDBP}) inferior 3349[Current inferior is 1 [process 3401] (helloworld)] 3350@end smallexample 3351 3352To find out what open target connections exist at any moment, use 3353@w{@code{info connections}}: 3354 3355@table @code 3356@kindex info connections [ @var{id}@dots{} ] 3357@item info connections 3358Print a list of all open target connections currently being managed by 3359@value{GDBN}. By default all connections are printed, but the ID list 3360@var{id}@dots{} can be used to limit the display to just the requested 3361connections. 3362 3363@value{GDBN} displays for each connection (in this order): 3364 3365@enumerate 3366@item 3367the connection number assigned by @value{GDBN}. 3368 3369@item 3370the protocol used by the connection. 3371 3372@item 3373a textual description of the protocol used by the connection. 3374 3375@end enumerate 3376 3377@noindent 3378An asterisk @samp{*} preceding the connection number indicates the 3379connection of the current inferior. 3380 3381For example, 3382@end table 3383@c end table here to get a little more width for example 3384 3385@smallexample 3386(@value{GDBP}) info connections 3387 Num What Description 3388* 1 extended-remote host:10000 Extended remote serial target in gdb-specific protocol 3389 2 native Native process 3390 3 core Local core dump file 3391@end smallexample 3392 3393To switch focus between inferiors, use the @code{inferior} command: 3394 3395@table @code 3396@kindex inferior @var{infno} 3397@item inferior @var{infno} 3398Make inferior number @var{infno} the current inferior. The argument 3399@var{infno} is the inferior number assigned by @value{GDBN}, as shown 3400in the first field of the @samp{info inferiors} display. 3401@end table 3402 3403@vindex $_inferior@r{, convenience variable} 3404The debugger convenience variable @samp{$_inferior} contains the 3405number of the current inferior. You may find this useful in writing 3406breakpoint conditional expressions, command scripts, and so forth. 3407@xref{Convenience Vars,, Convenience Variables}, for general 3408information on convenience variables. 3409 3410You can get multiple executables into a debugging session via the 3411@code{add-inferior} and @w{@code{clone-inferior}} commands. On some 3412systems @value{GDBN} can add inferiors to the debug session 3413automatically by following calls to @code{fork} and @code{exec}. To 3414remove inferiors from the debugging session use the 3415@w{@code{remove-inferiors}} command. 3416 3417@table @code 3418@anchor{add_inferior_cli} 3419@kindex add-inferior 3420@item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ] [-no-connection ] 3421Adds @var{n} inferiors to be run using @var{executable} as the 3422executable; @var{n} defaults to 1. If no executable is specified, 3423the inferiors begins empty, with no program. You can still assign or 3424change the program assigned to the inferior at any time by using the 3425@code{file} command with the executable name as its argument. 3426 3427By default, the new inferior begins connected to the same target 3428connection as the current inferior. For example, if the current 3429inferior was connected to @code{gdbserver} with @code{target remote}, 3430then the new inferior will be connected to the same @code{gdbserver} 3431instance. The @samp{-no-connection} option starts the new inferior 3432with no connection yet. You can then for example use the @code{target 3433remote} command to connect to some other @code{gdbserver} instance, 3434use @code{run} to spawn a local program, etc. 3435 3436@kindex clone-inferior 3437@item clone-inferior [ -copies @var{n} ] [ @var{infno} ] 3438Adds @var{n} inferiors ready to execute the same program as inferior 3439@var{infno}; @var{n} defaults to 1, and @var{infno} defaults to the 3440number of the current inferior. This command copies the values of the 3441@var{args}, @w{@var{inferior-tty}} and @var{cwd} properties from the 3442current inferior to the new one. It also propagates changes the user 3443made to environment variables using the @w{@code{set environment}} and 3444@w{@code{unset environment}} commands. This is a convenient command 3445when you want to run another instance of the inferior you are debugging. 3446 3447@smallexample 3448(@value{GDBP}) info inferiors 3449 Num Description Connection Executable 3450* 1 process 29964 1 (native) helloworld 3451(@value{GDBP}) clone-inferior 3452Added inferior 2. 34531 inferiors added. 3454(@value{GDBP}) info inferiors 3455 Num Description Connection Executable 3456* 1 process 29964 1 (native) helloworld 3457 2 <null> 1 (native) helloworld 3458@end smallexample 3459 3460You can now simply switch focus to inferior 2 and run it. 3461 3462@anchor{remove_inferiors_cli} 3463@kindex remove-inferiors 3464@item remove-inferiors @var{infno}@dots{} 3465Removes the inferior or inferiors @var{infno}@dots{}. It is not 3466possible to remove an inferior that is running with this command. For 3467those, use the @code{kill} or @code{detach} command first. 3468 3469@end table 3470 3471To quit debugging one of the running inferiors that is not the current 3472inferior, you can either detach from it by using the @w{@code{detach 3473inferior}} command (allowing it to run independently), or kill it 3474using the @w{@code{kill inferiors}} command: 3475 3476@table @code 3477@kindex detach inferiors @var{infno}@dots{} 3478@item detach inferior @var{infno}@dots{} 3479Detach from the inferior or inferiors identified by @value{GDBN} 3480inferior number(s) @var{infno}@dots{}. Note that the inferior's entry 3481still stays on the list of inferiors shown by @code{info inferiors}, 3482but its Description will show @samp{<null>}. 3483 3484@kindex kill inferiors @var{infno}@dots{} 3485@item kill inferiors @var{infno}@dots{} 3486Kill the inferior or inferiors identified by @value{GDBN} inferior 3487number(s) @var{infno}@dots{}. Note that the inferior's entry still 3488stays on the list of inferiors shown by @code{info inferiors}, but its 3489Description will show @samp{<null>}. 3490@end table 3491 3492After the successful completion of a command such as @code{detach}, 3493@code{detach inferiors}, @code{kill} or @code{kill inferiors}, or after 3494a normal process exit, the inferior is still valid and listed with 3495@code{info inferiors}, ready to be restarted. 3496 3497 3498To be notified when inferiors are started or exit under @value{GDBN}'s 3499control use @w{@code{set print inferior-events}}: 3500 3501@table @code 3502@kindex set print inferior-events 3503@cindex print messages on inferior start and exit 3504@item set print inferior-events 3505@itemx set print inferior-events on 3506@itemx set print inferior-events off 3507The @code{set print inferior-events} command allows you to enable or 3508disable printing of messages when @value{GDBN} notices that new 3509inferiors have started or that inferiors have exited or have been 3510detached. By default, these messages will be printed. 3511 3512@kindex show print inferior-events 3513@item show print inferior-events 3514Show whether messages will be printed when @value{GDBN} detects that 3515inferiors have started, exited or have been detached. 3516@end table 3517 3518Many commands will work the same with multiple programs as with a 3519single program: e.g., @code{print myglobal} will simply display the 3520value of @code{myglobal} in the current inferior. 3521 3522 3523Occasionally, when debugging @value{GDBN} itself, it may be useful to 3524get more info about the relationship of inferiors, programs, address 3525spaces in a debug session. You can do that with the @w{@code{maint 3526info program-spaces}} command. 3527 3528@table @code 3529@kindex maint info program-spaces 3530@item maint info program-spaces 3531Print a list of all program spaces currently being managed by 3532@value{GDBN}. 3533 3534@value{GDBN} displays for each program space (in this order): 3535 3536@enumerate 3537@item 3538the program space number assigned by @value{GDBN} 3539 3540@item 3541the name of the executable loaded into the program space, with e.g., 3542the @code{file} command. 3543 3544@item 3545the name of the core file loaded into the program space, with e.g., 3546the @code{core-file} command. 3547 3548@end enumerate 3549 3550@noindent 3551An asterisk @samp{*} preceding the @value{GDBN} program space number 3552indicates the current program space. 3553 3554In addition, below each program space line, @value{GDBN} prints extra 3555information that isn't suitable to display in tabular form. For 3556example, the list of inferiors bound to the program space. 3557 3558@smallexample 3559(@value{GDBP}) maint info program-spaces 3560 Id Executable Core File 3561* 1 hello 3562 2 goodbye 3563 Bound inferiors: ID 1 (process 21561) 3564@end smallexample 3565 3566Here we can see that no inferior is running the program @code{hello}, 3567while @code{process 21561} is running the program @code{goodbye}. On 3568some targets, it is possible that multiple inferiors are bound to the 3569same program space. The most common example is that of debugging both 3570the parent and child processes of a @code{vfork} call. For example, 3571 3572@smallexample 3573(@value{GDBP}) maint info program-spaces 3574 Id Executable Core File 3575* 1 vfork-test 3576 Bound inferiors: ID 2 (process 18050), ID 1 (process 18045) 3577@end smallexample 3578 3579Here, both inferior 2 and inferior 1 are running in the same program 3580space as a result of inferior 1 having executed a @code{vfork} call. 3581@end table 3582 3583@menu 3584* Inferior-Specific Breakpoints:: Controlling breakpoints 3585@end menu 3586 3587@node Inferior-Specific Breakpoints 3588@subsection Inferior-Specific Breakpoints 3589 3590When debugging multiple inferiors, you can choose whether to set 3591breakpoints for all inferiors, or for a particular inferior. 3592 3593@table @code 3594@cindex breakpoints and inferiors 3595@cindex inferior-specific breakpoints 3596@kindex break @dots{} inferior @var{inferior-id} 3597@item break @var{locspec} inferior @var{inferior-id} 3598@itemx break @var{locspec} inferior @var{inferior-id} if @dots{} 3599@var{locspec} specifies a code location or locations in your program. 3600@xref{Location Specifications}, for details. 3601 3602Use the qualifier @samp{inferior @var{inferior-id}} with a breakpoint 3603command to specify that you only want @value{GDBN} to stop when a 3604particular inferior reaches this breakpoint. The @var{inferior-id} 3605specifier is one of the inferior identifiers assigned by @value{GDBN}, 3606shown in the first column of the @samp{info inferiors} output. 3607 3608If you do not specify @samp{inferior @var{inferior-id}} when you set a 3609breakpoint, the breakpoint applies to @emph{all} inferiors of your 3610program. 3611 3612You can use the @code{inferior} qualifier on conditional breakpoints as 3613well; in this case, place @samp{inferior @var{inferior-id}} before or 3614after the breakpoint condition, like this: 3615 3616@smallexample 3617(@value{GDBP}) break frik.c:13 inferior 2 if bartab > lim 3618@end smallexample 3619@end table 3620 3621Inferior-specific breakpoints are automatically deleted when the 3622corresponding inferior is removed from @value{GDBN}. For example: 3623 3624@smallexample 3625(@value{GDBP}) remove-inferiors 2 3626Inferior-specific breakpoint 3 deleted - inferior 2 has been removed. 3627@end smallexample 3628 3629A breakpoint can't be both inferior-specific and thread-specific 3630(@pxref{Thread-Specific Breakpoints}), or task-specific (@pxref{Ada 3631Tasks}); using more than one of the @code{inferior}, @code{thread}, or 3632@code{task} keywords when creating a breakpoint will give an error. 3633 3634@node Threads 3635@section Debugging Programs with Multiple Threads 3636 3637@cindex threads of execution 3638@cindex multiple threads 3639@cindex switching threads 3640In some operating systems, such as GNU/Linux and Solaris, a single program 3641may have more than one @dfn{thread} of execution. The precise semantics 3642of threads differ from one operating system to another, but in general 3643the threads of a single program are akin to multiple processes---except 3644that they share one address space (that is, they can all examine and 3645modify the same variables). On the other hand, each thread has its own 3646registers and execution stack, and perhaps private memory. 3647 3648@value{GDBN} provides these facilities for debugging multi-thread 3649programs: 3650 3651@itemize @bullet 3652@item automatic notification of new threads 3653@item @samp{thread @var{thread-id}}, a command to switch among threads 3654@item @samp{info threads}, a command to inquire about existing threads 3655@item @samp{thread apply [@var{thread-id-list} | all] @var{args}}, 3656a command to apply a command to a list of threads 3657@item thread-specific breakpoints 3658@item @samp{set print thread-events}, which controls printing of 3659messages on thread start and exit. 3660@item @samp{set libthread-db-search-path @var{path}}, which lets 3661the user specify which @code{libthread_db} to use if the default choice 3662isn't compatible with the program. 3663@end itemize 3664 3665@cindex focus of debugging 3666@cindex current thread 3667The @value{GDBN} thread debugging facility allows you to observe all 3668threads while your program runs---but whenever @value{GDBN} takes 3669control, one thread in particular is always the focus of debugging. 3670This thread is called the @dfn{current thread}. Debugging commands show 3671program information from the perspective of the current thread. 3672 3673@cindex @code{New} @var{systag} message 3674@cindex thread identifier (system) 3675@c FIXME-implementors!! It would be more helpful if the [New...] message 3676@c included GDB's numeric thread handle, so you could just go to that 3677@c thread without first checking `info threads'. 3678Whenever @value{GDBN} detects a new thread in your program, it displays 3679the target system's identification for the thread with a message in the 3680form @samp{[New @var{systag}]}, where @var{systag} is a thread identifier 3681whose form varies depending on the particular system. For example, on 3682@sc{gnu}/Linux, you might see 3683 3684@smallexample 3685[New Thread 0x41e02940 (LWP 25582)] 3686@end smallexample 3687 3688@noindent 3689when @value{GDBN} notices a new thread. In contrast, on other systems, 3690the @var{systag} is simply something like @samp{process 368}, with no 3691further qualifier. 3692 3693@c FIXME!! (1) Does the [New...] message appear even for the very first 3694@c thread of a program, or does it only appear for the 3695@c second---i.e.@: when it becomes obvious we have a multithread 3696@c program? 3697@c (2) *Is* there necessarily a first thread always? Or do some 3698@c multithread systems permit starting a program with multiple 3699@c threads ab initio? 3700 3701@anchor{thread numbers} 3702@cindex thread number, per inferior 3703@cindex thread identifier (GDB) 3704For debugging purposes, @value{GDBN} associates its own thread number 3705---always a single integer---with each thread of an inferior. This 3706number is unique between all threads of an inferior, but not unique 3707between threads of different inferiors. 3708 3709@cindex qualified thread ID 3710You can refer to a given thread in an inferior using the qualified 3711@var{inferior-num}.@var{thread-num} syntax, also known as 3712@dfn{qualified thread ID}, with @var{inferior-num} being the inferior 3713number and @var{thread-num} being the thread number of the given 3714inferior. For example, thread @code{2.3} refers to thread number 3 of 3715inferior 2. If you omit @var{inferior-num} (e.g., @code{thread 3}), 3716then @value{GDBN} infers you're referring to a thread of the current 3717inferior. 3718 3719Until you create a second inferior, @value{GDBN} does not show the 3720@var{inferior-num} part of thread IDs, even though you can always use 3721the full @var{inferior-num}.@var{thread-num} form to refer to threads 3722of inferior 1, the initial inferior. 3723 3724@anchor{thread ID lists} 3725@cindex thread ID lists 3726Some commands accept a space-separated @dfn{thread ID list} as 3727argument. A list element can be: 3728 3729@enumerate 3730@item 3731A thread ID as shown in the first field of the @samp{info threads} 3732display, with or without an inferior qualifier. E.g., @samp{2.1} or 3733@samp{1}. 3734 3735@item 3736A range of thread numbers, again with or without an inferior 3737qualifier, as in @var{inf}.@var{thr1}-@var{thr2} or 3738@var{thr1}-@var{thr2}. E.g., @samp{1.2-4} or @samp{2-4}. 3739 3740@item 3741All threads of an inferior, specified with a star wildcard, with or 3742without an inferior qualifier, as in @var{inf}.@code{*} (e.g., 3743@samp{1.*}) or @code{*}. The former refers to all threads of the 3744given inferior, and the latter form without an inferior qualifier 3745refers to all threads of the current inferior. 3746 3747@end enumerate 3748 3749For example, if the current inferior is 1, and inferior 7 has one 3750thread with ID 7.1, the thread list @samp{1 2-3 4.5 6.7-9 7.*} 3751includes threads 1 to 3 of inferior 1, thread 5 of inferior 4, threads 37527 to 9 of inferior 6 and all threads of inferior 7. That is, in 3753expanded qualified form, the same as @samp{1.1 1.2 1.3 4.5 6.7 6.8 6.9 37547.1}. 3755 3756 3757@anchor{global thread numbers} 3758@cindex global thread number 3759@cindex global thread identifier (GDB) 3760In addition to a @emph{per-inferior} number, each thread is also 3761assigned a unique @emph{global} number, also known as @dfn{global 3762thread ID}, a single integer. Unlike the thread number component of 3763the thread ID, no two threads have the same global ID, even when 3764you're debugging multiple inferiors. 3765 3766From @value{GDBN}'s perspective, a process always has at least one 3767thread. In other words, @value{GDBN} assigns a thread number to the 3768program's ``main thread'' even if the program is not multi-threaded. 3769 3770@vindex $_thread@r{, convenience variable} 3771@vindex $_gthread@r{, convenience variable} 3772@vindex $_inferior_thread_count@r{, convenience variable} 3773The debugger convenience variables @samp{$_thread} and 3774@samp{$_gthread} contain, respectively, the per-inferior thread number 3775and the global thread number of the current thread. You may find this 3776useful in writing breakpoint conditional expressions, command scripts, 3777and so forth. The convenience variable @samp{$_inferior_thread_count} 3778contains the number of live threads in the current inferior. 3779@xref{Convenience Vars,, Convenience Variables}, for general 3780information on convenience variables. 3781 3782When running in non-stop mode (@pxref{Non-Stop Mode}), where new 3783threads can be created, and existing threads exit, at any time, 3784@samp{$_inferior_thread_count} could return a different value each 3785time it is evaluated. 3786 3787If @value{GDBN} detects the program is multi-threaded, it augments the 3788usual message about stopping at a breakpoint with the ID and name of 3789the thread that hit the breakpoint. 3790 3791@smallexample 3792Thread 2 "client" hit Breakpoint 1, send_message () at client.c:68 3793@end smallexample 3794 3795Likewise when the program receives a signal: 3796 3797@smallexample 3798Thread 1 "main" received signal SIGINT, Interrupt. 3799@end smallexample 3800 3801@table @code 3802@anchor{info_threads} 3803@kindex info threads 3804@item info threads @r{[}-gid@r{]} @r{[}@var{thread-id-list}@r{]} 3805 3806Display information about one or more threads. With no arguments 3807displays information about all threads. You can specify the list of 3808threads that you want to display using the thread ID list syntax 3809(@pxref{thread ID lists}). 3810 3811@value{GDBN} displays for each thread (in this order): 3812 3813@enumerate 3814@item 3815the per-inferior thread number assigned by @value{GDBN} 3816 3817@item 3818the global thread number assigned by @value{GDBN}, if the @samp{-gid} 3819option was specified 3820 3821@item 3822the target system's thread identifier (@var{systag}) 3823 3824@item 3825the thread's name, if one is known. A thread can either be named by 3826the user (see @code{thread name}, below), or, in some cases, by the 3827program itself. 3828 3829@item 3830the current stack frame summary for that thread 3831@end enumerate 3832 3833@noindent 3834An asterisk @samp{*} to the left of the @value{GDBN} thread number 3835indicates the current thread. 3836 3837For example, 3838@end table 3839@c end table here to get a little more width for example 3840 3841@smallexample 3842(@value{GDBP}) info threads 3843 Id Target Id Frame 3844* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) 3845 2 process 35 thread 23 0x34e5 in sigpause () 3846 3 process 35 thread 27 0x34e5 in sigpause () 3847 at threadtest.c:68 3848@end smallexample 3849 3850If you're debugging multiple inferiors, @value{GDBN} displays thread 3851IDs using the qualified @var{inferior-num}.@var{thread-num} format. 3852Otherwise, only @var{thread-num} is shown. 3853 3854If you specify the @samp{-gid} option, @value{GDBN} displays a column 3855indicating each thread's global thread ID: 3856 3857@smallexample 3858(@value{GDBP}) info threads 3859 Id GId Target Id Frame 3860 1.1 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) 3861 1.2 3 process 35 thread 23 0x34e5 in sigpause () 3862 1.3 4 process 35 thread 27 0x34e5 in sigpause () 3863* 2.1 2 process 65 thread 1 main (argc=1, argv=0x7ffffff8) 3864@end smallexample 3865 3866On Solaris, you can display more information about user threads with a 3867Solaris-specific command: 3868 3869@table @code 3870@item maint info sol-threads 3871@kindex maint info sol-threads 3872@cindex thread info (Solaris) 3873Display info on Solaris user threads. 3874@end table 3875 3876@table @code 3877@kindex thread @var{thread-id} 3878@item thread @var{thread-id} 3879Make thread ID @var{thread-id} the current thread. The command 3880argument @var{thread-id} is the @value{GDBN} thread ID, as shown in 3881the first field of the @samp{info threads} display, with or without an 3882inferior qualifier (e.g., @samp{2.1} or @samp{1}). 3883 3884@value{GDBN} responds by displaying the system identifier of the 3885thread you selected, and its current stack frame summary: 3886 3887@smallexample 3888(@value{GDBP}) thread 2 3889[Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))] 3890#0 some_function (ignore=0x0) at example.c:8 38918 printf ("hello\n"); 3892@end smallexample 3893 3894@noindent 3895As with the @samp{[New @dots{}]} message, the form of the text after 3896@samp{Switching to} depends on your system's conventions for identifying 3897threads. 3898 3899@anchor{thread apply all} 3900@kindex thread apply 3901@cindex apply command to several threads 3902@item thread apply [@var{thread-id-list} | all [-ascending]] [@var{flag}]@dots{} @var{command} 3903The @code{thread apply} command allows you to apply the named 3904@var{command} to one or more threads. Specify the threads that you 3905want affected using the thread ID list syntax (@pxref{thread ID 3906lists}), or specify @code{all} to apply to all threads. To apply a 3907command to all threads in descending order, type @kbd{thread apply all 3908@var{command}}. To apply a command to all threads in ascending order, 3909type @kbd{thread apply all -ascending @var{command}}. 3910 3911The @var{flag} arguments control what output to produce and how to handle 3912errors raised when applying @var{command} to a thread. @var{flag} 3913must start with a @code{-} directly followed by one letter in 3914@code{qcs}. If several flags are provided, they must be given 3915individually, such as @code{-c -q}. 3916 3917By default, @value{GDBN} displays some thread information before the 3918output produced by @var{command}, and an error raised during the 3919execution of a @var{command} will abort @code{thread apply}. The 3920following flags can be used to fine-tune this behavior: 3921 3922@table @code 3923@item -c 3924The flag @code{-c}, which stands for @samp{continue}, causes any 3925errors in @var{command} to be displayed, and the execution of 3926@code{thread apply} then continues. 3927@item -s 3928The flag @code{-s}, which stands for @samp{silent}, causes any errors 3929or empty output produced by a @var{command} to be silently ignored. 3930That is, the execution continues, but the thread information and errors 3931are not printed. 3932@item -q 3933The flag @code{-q} (@samp{quiet}) disables printing the thread 3934information. 3935@end table 3936 3937Flags @code{-c} and @code{-s} cannot be used together. 3938 3939@kindex taas 3940@cindex apply command to all threads (ignoring errors and empty output) 3941@item taas [@var{option}]@dots{} @var{command} 3942Shortcut for @code{thread apply all -s [@var{option}]@dots{} @var{command}}. 3943Applies @var{command} on all threads, ignoring errors and empty output. 3944 3945The @code{taas} command accepts the same options as the @code{thread 3946apply all} command. @xref{thread apply all}. 3947 3948@kindex tfaas 3949@cindex apply a command to all frames of all threads (ignoring errors and empty output) 3950@item tfaas [@var{option}]@dots{} @var{command} 3951Shortcut for @code{thread apply all -s -- frame apply all -s [@var{option}]@dots{} @var{command}}. 3952Applies @var{command} on all frames of all threads, ignoring errors 3953and empty output. Note that the flag @code{-s} is specified twice: 3954The first @code{-s} ensures that @code{thread apply} only shows the thread 3955information of the threads for which @code{frame apply} produces 3956some output. The second @code{-s} is needed to ensure that @code{frame 3957apply} shows the frame information of a frame only if the 3958@var{command} successfully produced some output. 3959 3960It can for example be used to print a local variable or a function 3961argument without knowing the thread or frame where this variable or argument 3962is, using: 3963@smallexample 3964(@value{GDBP}) tfaas p some_local_var_i_do_not_remember_where_it_is 3965@end smallexample 3966 3967The @code{tfaas} command accepts the same options as the @code{frame 3968apply} command. @xref{Frame Apply,,frame apply}. 3969 3970@kindex thread name 3971@cindex name a thread 3972@item thread name [@var{name}] 3973This command assigns a name to the current thread. If no argument is 3974given, any existing user-specified name is removed. The thread name 3975appears in the @samp{info threads} display. 3976 3977On some systems, such as @sc{gnu}/Linux, @value{GDBN} is able to 3978determine the name of the thread as given by the OS. On these 3979systems, a name specified with @samp{thread name} will override the 3980system-give name, and removing the user-specified name will cause 3981@value{GDBN} to once again display the system-specified name. 3982 3983@kindex thread find 3984@cindex search for a thread 3985@item thread find [@var{regexp}] 3986Search for and display thread ids whose name or @var{systag} 3987matches the supplied regular expression. 3988 3989As well as being the complement to the @samp{thread name} command, 3990this command also allows you to identify a thread by its target 3991@var{systag}. For instance, on @sc{gnu}/Linux, the target @var{systag} 3992is the LWP id. 3993 3994@smallexample 3995(@value{GDBP}) thread find 26688 3996Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)' 3997(@value{GDBP}) info thread 4 3998 Id Target Id Frame 3999 4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select () 4000@end smallexample 4001 4002@kindex set print thread-events 4003@cindex print messages on thread start and exit 4004@item set print thread-events 4005@itemx set print thread-events on 4006@itemx set print thread-events off 4007The @code{set print thread-events} command allows you to enable or 4008disable printing of messages when @value{GDBN} notices that new threads have 4009started or that threads have exited. By default, these messages will 4010be printed if detection of these events is supported by the target. 4011Note that these messages cannot be disabled on all targets. 4012 4013@kindex show print thread-events 4014@item show print thread-events 4015Show whether messages will be printed when @value{GDBN} detects that threads 4016have started and exited. 4017@end table 4018 4019@xref{Thread Stops,,Stopping and Starting Multi-thread Programs}, for 4020more information about how @value{GDBN} behaves when you stop and start 4021programs with multiple threads. 4022 4023@xref{Set Watchpoints,,Setting Watchpoints}, for information about 4024watchpoints in programs with multiple threads. 4025 4026@anchor{set libthread-db-search-path} 4027@table @code 4028@kindex set libthread-db-search-path 4029@cindex search path for @code{libthread_db} 4030@item set libthread-db-search-path @r{[}@var{path}@r{]} 4031If this variable is set, @var{path} is a colon-separated list of 4032directories @value{GDBN} will use to search for @code{libthread_db}. 4033If you omit @var{path}, @samp{libthread-db-search-path} will be reset to 4034its default value (@code{$sdir:$pdir} on @sc{gnu}/Linux and Solaris systems). 4035Internally, the default value comes from the @code{LIBTHREAD_DB_SEARCH_PATH} 4036macro. 4037 4038On @sc{gnu}/Linux and Solaris systems, @value{GDBN} uses a ``helper'' 4039@code{libthread_db} library to obtain information about threads in the 4040inferior process. @value{GDBN} will use @samp{libthread-db-search-path} 4041to find @code{libthread_db}. @value{GDBN} also consults first if inferior 4042specific thread debugging library loading is enabled 4043by @samp{set auto-load libthread-db} (@pxref{libthread_db.so.1 file}). 4044 4045A special entry @samp{$sdir} for @samp{libthread-db-search-path} 4046refers to the default system directories that are 4047normally searched for loading shared libraries. The @samp{$sdir} entry 4048is the only kind not needing to be enabled by @samp{set auto-load libthread-db} 4049(@pxref{libthread_db.so.1 file}). 4050 4051A special entry @samp{$pdir} for @samp{libthread-db-search-path} 4052refers to the directory from which @code{libpthread} 4053was loaded in the inferior process. 4054 4055For any @code{libthread_db} library @value{GDBN} finds in above directories, 4056@value{GDBN} attempts to initialize it with the current inferior process. 4057If this initialization fails (which could happen because of a version 4058mismatch between @code{libthread_db} and @code{libpthread}), @value{GDBN} 4059will unload @code{libthread_db}, and continue with the next directory. 4060If none of @code{libthread_db} libraries initialize successfully, 4061@value{GDBN} will issue a warning and thread debugging will be disabled. 4062 4063Setting @code{libthread-db-search-path} is currently implemented 4064only on some platforms. 4065 4066@kindex show libthread-db-search-path 4067@item show libthread-db-search-path 4068Display current libthread_db search path. 4069 4070@kindex set debug libthread-db 4071@kindex show debug libthread-db 4072@cindex debugging @code{libthread_db} 4073@item set debug libthread-db 4074@itemx show debug libthread-db 4075Turns on or off display of @code{libthread_db}-related events. 4076Use @code{1} to enable, @code{0} to disable. 4077 4078@kindex set debug threads 4079@kindex show debug threads 4080@cindex debugging @code{threads} 4081@item set debug threads @r{[}on@r{|}off@r{]} 4082@itemx show debug threads 4083When @samp{on} @value{GDBN} will print additional messages when 4084threads are created and deleted. 4085@end table 4086 4087@node Forks 4088@section Debugging Forks 4089 4090@cindex fork, debugging programs which call 4091@cindex multiple processes 4092@cindex processes, multiple 4093On most systems, @value{GDBN} has no special support for debugging 4094programs which create additional processes using the @code{fork} 4095function. When a program forks, @value{GDBN} will continue to debug the 4096parent process and the child process will run unimpeded. If you have 4097set a breakpoint in any code which the child then executes, the child 4098will get a @code{SIGTRAP} signal which (unless it catches the signal) 4099will cause it to terminate. 4100 4101However, if you want to debug the child process there is a workaround 4102which isn't too painful. Put a call to @code{sleep} in the code which 4103the child process executes after the fork. It may be useful to sleep 4104only if a certain environment variable is set, or a certain file exists, 4105so that the delay need not occur when you don't want to run @value{GDBN} 4106on the child. While the child is sleeping, use the @code{ps} program to 4107get its process ID. Then tell @value{GDBN} (a new invocation of 4108@value{GDBN} if you are also debugging the parent process) to attach to 4109the child process (@pxref{Attach}). From that point on you can debug 4110the child process just like any other process which you attached to. 4111 4112On some systems, @value{GDBN} provides support for debugging programs 4113that create additional processes using the @code{fork} or @code{vfork} 4114functions. On @sc{gnu}/Linux platforms, this feature is supported 4115with kernel version 2.5.46 and later. 4116 4117The fork debugging commands are supported in native mode and when 4118connected to @code{gdbserver} in either @code{target remote} mode or 4119@code{target extended-remote} mode. 4120 4121By default, when a program forks, @value{GDBN} will continue to debug 4122the parent process and the child process will run unimpeded. 4123 4124If you want to follow the child process instead of the parent process, 4125use the command @w{@code{set follow-fork-mode}}. 4126 4127@table @code 4128@kindex set follow-fork-mode 4129@item set follow-fork-mode @var{mode} 4130Set the debugger response to a program call of @code{fork} or 4131@code{vfork}. A call to @code{fork} or @code{vfork} creates a new 4132process. The @var{mode} argument can be: 4133 4134@table @code 4135@item parent 4136The original process is debugged after a fork. The child process runs 4137unimpeded. This is the default. 4138 4139@item child 4140The new process is debugged after a fork. The parent process runs 4141unimpeded. 4142 4143@end table 4144 4145@kindex show follow-fork-mode 4146@item show follow-fork-mode 4147Display the current debugger response to a @code{fork} or @code{vfork} call. 4148@end table 4149 4150@cindex debugging multiple processes 4151On Linux, if you want to debug both the parent and child processes, use the 4152command @w{@code{set detach-on-fork}}. 4153 4154@table @code 4155@kindex set detach-on-fork 4156@item set detach-on-fork @var{mode} 4157Tells gdb whether to detach one of the processes after a fork, or 4158retain debugger control over them both. 4159 4160@table @code 4161@item on 4162The child process (or parent process, depending on the value of 4163@code{follow-fork-mode}) will be detached and allowed to run 4164independently. This is the default. 4165 4166@item off 4167Both processes will be held under the control of @value{GDBN}. 4168One process (child or parent, depending on the value of 4169@code{follow-fork-mode}) is debugged as usual, while the other 4170is held suspended. 4171 4172@end table 4173 4174@kindex show detach-on-fork 4175@item show detach-on-fork 4176Show whether detach-on-fork mode is on/off. 4177@end table 4178 4179If you choose to set @samp{detach-on-fork} mode off, then @value{GDBN} 4180will retain control of all forked processes (including nested forks). 4181You can list the forked processes under the control of @value{GDBN} by 4182using the @w{@code{info inferiors}} command, and switch from one fork 4183to another by using the @code{inferior} command (@pxref{Inferiors Connections and 4184Programs, ,Debugging Multiple Inferiors Connections and Programs}). 4185 4186To quit debugging one of the forked processes, you can either detach 4187from it by using the @w{@code{detach inferiors}} command (allowing it 4188to run independently), or kill it using the @w{@code{kill inferiors}} 4189command. @xref{Inferiors Connections and Programs, ,Debugging 4190Multiple Inferiors Connections and Programs}. 4191 4192If you ask to debug a child process and a @code{vfork} is followed by an 4193@code{exec}, @value{GDBN} executes the new target up to the first 4194breakpoint in the new target. If you have a breakpoint set on 4195@code{main} in your original program, the breakpoint will also be set on 4196the child process's @code{main}. 4197 4198On some systems, when a child process is spawned by @code{vfork}, you 4199cannot debug the child or parent until an @code{exec} call completes. 4200 4201If you issue a @code{run} command to @value{GDBN} after an @code{exec} 4202call executes, the new target restarts. To restart the parent 4203process, use the @code{file} command with the parent executable name 4204as its argument. By default, after an @code{exec} call executes, 4205@value{GDBN} discards the symbols of the previous executable image. 4206You can change this behaviour with the @w{@code{set follow-exec-mode}} 4207command. 4208 4209@table @code 4210@kindex set follow-exec-mode 4211@item set follow-exec-mode @var{mode} 4212 4213Set debugger response to a program call of @code{exec}. An 4214@code{exec} call replaces the program image of a process. 4215 4216@code{follow-exec-mode} can be: 4217 4218@table @code 4219@item new 4220@value{GDBN} creates a new inferior and rebinds the process to this 4221new inferior. The program the process was running before the 4222@code{exec} call can be restarted afterwards by restarting the 4223original inferior. 4224 4225For example: 4226 4227@smallexample 4228(@value{GDBP}) info inferiors 4229(@value{GDBP}) info inferior 4230 Id Description Executable 4231* 1 <null> prog1 4232(@value{GDBP}) run 4233process 12020 is executing new program: prog2 4234Program exited normally. 4235(@value{GDBP}) info inferiors 4236 Id Description Executable 4237 1 <null> prog1 4238* 2 <null> prog2 4239@end smallexample 4240 4241@item same 4242@value{GDBN} keeps the process bound to the same inferior. The new 4243executable image replaces the previous executable loaded in the 4244inferior. Restarting the inferior after the @code{exec} call, with 4245e.g., the @code{run} command, restarts the executable the process was 4246running after the @code{exec} call. This is the default mode. 4247 4248For example: 4249 4250@smallexample 4251(@value{GDBP}) info inferiors 4252 Id Description Executable 4253* 1 <null> prog1 4254(@value{GDBP}) run 4255process 12020 is executing new program: prog2 4256Program exited normally. 4257(@value{GDBP}) info inferiors 4258 Id Description Executable 4259* 1 <null> prog2 4260@end smallexample 4261 4262@end table 4263@end table 4264 4265@code{follow-exec-mode} is supported in native mode and 4266@code{target extended-remote} mode. 4267 4268You can use the @code{catch} command to make @value{GDBN} stop whenever 4269a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set 4270Catchpoints, ,Setting Catchpoints}. 4271 4272@node Checkpoint/Restart 4273@section Setting a @emph{Bookmark} to Return to Later 4274 4275@cindex checkpoint 4276@cindex restart 4277@cindex bookmark 4278@cindex snapshot of a process 4279@cindex rewind program state 4280 4281On certain operating systems@footnote{Currently, only 4282@sc{gnu}/Linux.}, @value{GDBN} is able to save a @dfn{snapshot} of a 4283program's state, called a @dfn{checkpoint}, and come back to it 4284later. 4285 4286Returning to a checkpoint effectively undoes everything that has 4287happened in the program since the @code{checkpoint} was saved. This 4288includes changes in memory, registers, and even (within some limits) 4289system state. Effectively, it is like going back in time to the 4290moment when the checkpoint was saved. 4291 4292Thus, if you're stepping thru a program and you think you're 4293getting close to the point where things go wrong, you can save 4294a checkpoint. Then, if you accidentally go too far and miss 4295the critical statement, instead of having to restart your program 4296from the beginning, you can just go back to the checkpoint and 4297start again from there. 4298 4299This can be especially useful if it takes a lot of time or 4300steps to reach the point where you think the bug occurs. 4301 4302To use the @code{checkpoint}/@code{restart} method of debugging: 4303 4304@table @code 4305@kindex checkpoint 4306@item checkpoint 4307Save a snapshot of the debugged program's current execution state. 4308The @code{checkpoint} command takes no arguments, but each checkpoint 4309is assigned a small integer id, similar to a breakpoint id. 4310 4311@kindex info checkpoints 4312@item info checkpoints 4313List the checkpoints that have been saved in the current debugging 4314session. For each checkpoint, the following information will be 4315listed: 4316 4317@table @code 4318@item Checkpoint ID 4319@item Process ID 4320@item Code Address 4321@item Source line, or label 4322@end table 4323 4324@kindex restart @var{checkpoint-id} 4325@item restart @var{checkpoint-id} 4326Restore the program state that was saved as checkpoint number 4327@var{checkpoint-id}. All program variables, registers, stack frames 4328etc.@: will be returned to the values that they had when the checkpoint 4329was saved. In essence, gdb will ``wind back the clock'' to the point 4330in time when the checkpoint was saved. 4331 4332Note that breakpoints, @value{GDBN} variables, command history etc. 4333are not affected by restoring a checkpoint. In general, a checkpoint 4334only restores things that reside in the program being debugged, not in 4335the debugger. 4336 4337@kindex delete checkpoint @var{checkpoint-id} 4338@item delete checkpoint @var{checkpoint-id} 4339Delete the previously-saved checkpoint identified by @var{checkpoint-id}. 4340 4341@end table 4342 4343Returning to a previously saved checkpoint will restore the user state 4344of the program being debugged, plus a significant subset of the system 4345(OS) state, including file pointers. It won't ``un-write'' data from 4346a file, but it will rewind the file pointer to the previous location, 4347so that the previously written data can be overwritten. For files 4348opened in read mode, the pointer will also be restored so that the 4349previously read data can be read again. 4350 4351Of course, characters that have been sent to a printer (or other 4352external device) cannot be ``snatched back'', and characters received 4353from eg.@: a serial device can be removed from internal program buffers, 4354but they cannot be ``pushed back'' into the serial pipeline, ready to 4355be received again. Similarly, the actual contents of files that have 4356been changed cannot be restored (at this time). 4357 4358However, within those constraints, you actually can ``rewind'' your 4359program to a previously saved point in time, and begin debugging it 4360again --- and you can change the course of events so as to debug a 4361different execution path this time. 4362 4363@cindex checkpoints and process id 4364Finally, there is one bit of internal program state that will be 4365different when you return to a checkpoint --- the program's process 4366id. Each checkpoint will have a unique process id (or @var{pid}), 4367and each will be different from the program's original @var{pid}. 4368If your program has saved a local copy of its process id, this could 4369potentially pose a problem. 4370 4371@subsection A Non-obvious Benefit of Using Checkpoints 4372 4373On some systems such as @sc{gnu}/Linux, address space randomization 4374is performed on new processes for security reasons. This makes it 4375difficult or impossible to set a breakpoint, or watchpoint, on an 4376absolute address if you have to restart the program, since the 4377absolute location of a symbol will change from one execution to the 4378next. 4379 4380A checkpoint, however, is an @emph{identical} copy of a process. 4381Therefore if you create a checkpoint at (eg.@:) the start of main, 4382and simply return to that checkpoint instead of restarting the 4383process, you can avoid the effects of address randomization and 4384your symbols will all stay in the same place. 4385 4386@node Stopping 4387@chapter Stopping and Continuing 4388 4389The principal purposes of using a debugger are so that you can stop your 4390program before it terminates; or so that, if your program runs into 4391trouble, you can investigate and find out why. 4392 4393Inside @value{GDBN}, your program may stop for any of several reasons, 4394such as a signal, a breakpoint, or reaching a new line after a 4395@value{GDBN} command such as @code{step}. You may then examine and 4396change variables, set new breakpoints or remove old ones, and then 4397continue execution. Usually, the messages shown by @value{GDBN} provide 4398ample explanation of the status of your program---but you can also 4399explicitly request this information at any time. 4400 4401@table @code 4402@kindex info program 4403@item info program 4404Display information about the status of your program: whether it is 4405running or not, what process it is, and why it stopped. 4406@end table 4407 4408@menu 4409* Breakpoints:: Breakpoints, watchpoints, tracepoints, 4410 and catchpoints 4411* Continuing and Stepping:: Resuming execution 4412* Skipping Over Functions and Files:: 4413 Skipping over functions and files 4414* Signals:: Signals 4415* Thread Stops:: Stopping and starting multi-thread programs 4416@end menu 4417 4418@node Breakpoints 4419@section Breakpoints, Watchpoints, and Catchpoints 4420 4421@cindex breakpoints 4422A @dfn{breakpoint} makes your program stop whenever a certain point in 4423the program is reached. For each breakpoint, you can add conditions to 4424control in finer detail whether your program stops. You can set 4425breakpoints with the @code{break} command and its variants (@pxref{Set 4426Breaks, ,Setting Breakpoints}), to specify the place where your program 4427should stop by line number, function name or exact address in the 4428program. 4429 4430On some systems, you can set breakpoints in shared libraries before 4431the executable is run. 4432 4433@cindex watchpoints 4434@cindex data breakpoints 4435@cindex memory tracing 4436@cindex breakpoint on memory address 4437@cindex breakpoint on variable modification 4438A @dfn{watchpoint} is a special breakpoint that stops your program 4439when the value of an expression changes. The expression may be a value 4440of a variable, or it could involve values of one or more variables 4441combined by operators, such as @samp{a + b}. This is sometimes called 4442@dfn{data breakpoints}. You must use a different command to set 4443watchpoints (@pxref{Set Watchpoints, ,Setting Watchpoints}), but aside 4444from that, you can manage a watchpoint like any other breakpoint: you 4445enable, disable, and delete both breakpoints and watchpoints using the 4446same commands. 4447 4448You can arrange to have values from your program displayed automatically 4449whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,, 4450Automatic Display}. 4451 4452@cindex catchpoints 4453@cindex breakpoint on events 4454A @dfn{catchpoint} is another special breakpoint that stops your program 4455when a certain kind of event occurs, such as the throwing of a C@t{++} 4456exception or the loading of a library. As with watchpoints, you use a 4457different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting 4458Catchpoints}), but aside from that, you can manage a catchpoint like any 4459other breakpoint. (To stop when your program receives a signal, use the 4460@code{handle} command; see @ref{Signals, ,Signals}.) 4461 4462@cindex breakpoint numbers 4463@cindex numbers for breakpoints 4464@value{GDBN} assigns a number to each breakpoint, watchpoint, or 4465catchpoint when you create it; these numbers are successive integers 4466starting with one. In many of the commands for controlling various 4467features of breakpoints you use the breakpoint number to say which 4468breakpoint you want to change. Each breakpoint may be @dfn{enabled} or 4469@dfn{disabled}; if disabled, it has no effect on your program until you 4470enable it again. 4471 4472@cindex breakpoint ranges 4473@cindex breakpoint lists 4474@cindex ranges of breakpoints 4475@cindex lists of breakpoints 4476Some @value{GDBN} commands accept a space-separated list of breakpoints 4477on which to operate. A list element can be either a single breakpoint number, 4478like @samp{5}, or a range of such numbers, like @samp{5-7}. 4479When a breakpoint list is given to a command, all breakpoints in that list 4480are operated on. 4481 4482@menu 4483* Set Breaks:: Setting breakpoints 4484* Set Watchpoints:: Setting watchpoints 4485* Set Catchpoints:: Setting catchpoints 4486* Delete Breaks:: Deleting breakpoints 4487* Disabling:: Disabling breakpoints 4488* Conditions:: Break conditions 4489* Break Commands:: Breakpoint command lists 4490* Dynamic Printf:: Dynamic printf 4491* Save Breakpoints:: How to save breakpoints in a file 4492* Static Probe Points:: Listing static probe points 4493* Error in Breakpoints:: ``Cannot insert breakpoints'' 4494* Breakpoint-related Warnings:: ``Breakpoint address adjusted...'' 4495@end menu 4496 4497@node Set Breaks 4498@subsection Setting Breakpoints 4499 4500@c FIXME LMB what does GDB do if no code on line of breakpt? 4501@c consider in particular declaration with/without initialization. 4502@c 4503@c FIXME 2 is there stuff on this already? break at fun start, already init? 4504 4505@kindex break 4506@kindex b @r{(@code{break})} 4507@vindex $bpnum@r{, convenience variable} 4508@cindex latest breakpoint 4509Breakpoints are set with the @code{break} command (abbreviated 4510@code{b}). The debugger convenience variable @samp{$bpnum} records the 4511number of the breakpoint you've set most recently: 4512@smallexample 4513(gdb) b main 4514Breakpoint 1 at 0x11c6: file zeoes.c, line 24. 4515(gdb) p $bpnum 4516$1 = 1 4517@end smallexample 4518 4519A breakpoint may be mapped to multiple code locations for example with 4520inlined functions, Ada generics, C@t{++} templates or overloaded function names. 4521@value{GDBN} then indicates the number of code locations in the breakpoint 4522command output: 4523@smallexample 4524(gdb) b some_func 4525Breakpoint 2 at 0x1179: some_func. (3 locations) 4526(gdb) p $bpnum 4527$2 = 2 4528(gdb) 4529@end smallexample 4530 4531@vindex $_hit_bpnum@r{, convenience variable} 4532@vindex $_hit_locno@r{, convenience variable} 4533When your program stops on a breakpoint, the convenience variables 4534@samp{$_hit_bpnum} and @samp{$_hit_locno} are respectively set to the number of 4535the encountered breakpoint and the number of the breakpoint's code location: 4536@smallexample 4537Thread 1 "zeoes" hit Breakpoint 2.1, some_func () at zeoes.c:8 45388 printf("some func\n"); 4539(gdb) p $_hit_bpnum 4540$5 = 2 4541(gdb) p $_hit_locno 4542$6 = 1 4543(gdb) 4544@end smallexample 4545 4546Note that @samp{$_hit_bpnum} and @samp{$bpnum} are not equivalent: 4547@samp{$_hit_bpnum} is set to the breakpoint number @b{last hit}, while 4548@samp{$bpnum} is set to the breakpoint number @b{last set}. 4549 4550 4551If the encountered breakpoint has only one code location, @samp{$_hit_locno} 4552is set to 1: 4553@smallexample 4554Breakpoint 1, main (argc=1, argv=0x7fffffffe018) at zeoes.c:24 455524 if (argc > 1) 4556(gdb) p $_hit_bpnum 4557$3 = 1 4558(gdb) p $_hit_locno 4559$4 = 1 4560(gdb) 4561@end smallexample 4562 4563The @samp{$_hit_bpnum} and @samp{$_hit_locno} variables can typically be used 4564in a breakpoint command list. 4565(@pxref{Break Commands, ,Breakpoint Command Lists}). For example, as 4566part of the breakpoint command list, you can disable completely the 4567encountered breakpoint using @kbd{disable $_hit_bpnum} or disable the 4568specific encountered breakpoint location using 4569@kbd{disable $_hit_bpnum.$_hit_locno}. 4570If a breakpoint has only one location, @samp{$_hit_locno} is set to 1 4571and the commands @kbd{disable $_hit_bpnum} and 4572@kbd{disable $_hit_bpnum.$_hit_locno} both disable the breakpoint. 4573 4574You can also define aliases to easily disable the last hit location or 4575last hit breakpoint: 4576@smallexample 4577(gdb) alias lld = disable $_hit_bpnum.$_hit_locno 4578(gdb) alias lbd = disable $_hit_bpnum 4579@end smallexample 4580 4581@table @code 4582@item break @var{locspec} 4583Set a breakpoint at all the code locations in your program that result 4584from resolving the given @var{locspec}. @var{locspec} can specify a 4585function name, a line number, an address of an instruction, and more. 4586@xref{Location Specifications}, for the various forms of 4587@var{locspec}. The breakpoint will stop your program just before it 4588executes the instruction at the address of any of the breakpoint's 4589code locations. 4590 4591When using source languages that permit overloading of symbols, such 4592as C@t{++}, a function name may refer to more than one symbol, and 4593thus more than one place to break. @xref{Ambiguous 4594Expressions,,Ambiguous Expressions}, for a discussion of that 4595situation. 4596 4597It is also possible to insert a breakpoint that will stop the program 4598only if a specific thread (@pxref{Thread-Specific Breakpoints}), 4599specific inferior (@pxref{Inferior-Specific Breakpoints}), or a 4600specific task (@pxref{Ada Tasks}) hits that breakpoint. 4601 4602@item break 4603When called without any arguments, @code{break} sets a breakpoint at 4604the next instruction to be executed in the selected stack frame 4605(@pxref{Stack, ,Examining the Stack}). In any selected frame but the 4606innermost, this makes your program stop as soon as control 4607returns to that frame. This is similar to the effect of a 4608@code{finish} command in the frame inside the selected frame---except 4609that @code{finish} does not leave an active breakpoint. If you use 4610@code{break} without an argument in the innermost frame, @value{GDBN} stops 4611the next time it reaches the current location; this may be useful 4612inside loops. 4613 4614@value{GDBN} normally ignores breakpoints when it resumes execution, until at 4615least one instruction has been executed. If it did not do this, you 4616would be unable to proceed past a breakpoint without first disabling the 4617breakpoint. This rule applies whether or not the breakpoint already 4618existed when your program stopped. 4619 4620@item break @dots{} if @var{cond} 4621Set a breakpoint with condition @var{cond}; evaluate the expression 4622@var{cond} each time the breakpoint is reached, and stop only if the 4623value is nonzero---that is, if @var{cond} evaluates as true. 4624@samp{@dots{}} stands for one of the possible arguments described 4625above (or no argument) specifying where to break. @xref{Conditions, 4626,Break Conditions}, for more information on breakpoint conditions. 4627 4628The breakpoint may be mapped to multiple locations. If the breakpoint 4629condition @var{cond} is invalid at some but not all of the locations, 4630the locations for which the condition is invalid are disabled. For 4631example, @value{GDBN} reports below that two of the three locations 4632are disabled. 4633 4634@smallexample 4635(@value{GDBP}) break func if a == 10 4636warning: failed to validate condition at location 0x11ce, disabling: 4637 No symbol "a" in current context. 4638warning: failed to validate condition at location 0x11b6, disabling: 4639 No symbol "a" in current context. 4640Breakpoint 1 at 0x11b6: func. (3 locations) 4641@end smallexample 4642 4643Locations that are disabled because of the condition are denoted by an 4644uppercase @code{N} in the output of the @code{info breakpoints} 4645command: 4646 4647@smallexample 4648(@value{GDBP}) info breakpoints 4649Num Type Disp Enb Address What 46501 breakpoint keep y <MULTIPLE> 4651 stop only if a == 10 46521.1 N* 0x00000000000011b6 in ... 46531.2 y 0x00000000000011c2 in ... 46541.3 N* 0x00000000000011ce in ... 4655(*): Breakpoint condition is invalid at this location. 4656@end smallexample 4657 4658If the breakpoint condition @var{cond} is invalid in the context of 4659@emph{all} the locations of the breakpoint, @value{GDBN} refuses to 4660define the breakpoint. For example, if variable @code{foo} is an 4661undefined variable: 4662 4663@smallexample 4664(@value{GDBP}) break func if foo 4665No symbol "foo" in current context. 4666@end smallexample 4667 4668@item break @dots{} -force-condition if @var{cond} 4669There may be cases where the condition @var{cond} is invalid at all 4670the current locations, but the user knows that it will be valid at a 4671future location; for example, because of a library load. In such 4672cases, by using the @code{-force-condition} keyword before @samp{if}, 4673@value{GDBN} can be forced to define the breakpoint with the given 4674condition expression instead of refusing it. 4675 4676@smallexample 4677(@value{GDBP}) break func -force-condition if foo 4678warning: failed to validate condition at location 1, disabling: 4679 No symbol "foo" in current context. 4680warning: failed to validate condition at location 2, disabling: 4681 No symbol "foo" in current context. 4682warning: failed to validate condition at location 3, disabling: 4683 No symbol "foo" in current context. 4684Breakpoint 1 at 0x1158: test.c:18. (3 locations) 4685@end smallexample 4686 4687This causes all the present locations where the breakpoint would 4688otherwise be inserted, to be disabled, as seen in the example above. 4689However, if there exist locations at which the condition is valid, the 4690@code{-force-condition} keyword has no effect. 4691 4692@kindex tbreak 4693@item tbreak @var{args} 4694Set a breakpoint enabled only for one stop. The @var{args} are the 4695same as for the @code{break} command, and the breakpoint is set in the same 4696way, but the breakpoint is automatically deleted after the first time your 4697program stops there. @xref{Disabling, ,Disabling Breakpoints}. 4698 4699@kindex hbreak 4700@cindex hardware breakpoints 4701@item hbreak @var{args} 4702Set a hardware-assisted breakpoint. The @var{args} are the same as for the 4703@code{break} command and the breakpoint is set in the same way, but the 4704breakpoint requires hardware support and some target hardware may not 4705have this support. The main purpose of this is EPROM/ROM code 4706debugging, so you can set a breakpoint at an instruction without 4707changing the instruction. This can be used with the new trap-generation 4708provided by SPARClite DSU and most x86-based targets. These targets 4709will generate traps when a program accesses some data or instruction 4710address that is assigned to the debug registers. However the hardware 4711breakpoint registers can take a limited number of breakpoints. For 4712example, on the DSU, only two data breakpoints can be set at a time, and 4713@value{GDBN} will reject this command if more than two are used. Delete 4714or disable unused hardware breakpoints before setting new ones 4715(@pxref{Disabling, ,Disabling Breakpoints}). 4716@xref{Conditions, ,Break Conditions}. 4717For remote targets, you can restrict the number of hardware 4718breakpoints @value{GDBN} will use, see @ref{set remote 4719hardware-breakpoint-limit}. 4720 4721@kindex thbreak 4722@item thbreak @var{args} 4723Set a hardware-assisted breakpoint enabled only for one stop. The @var{args} 4724are the same as for the @code{hbreak} command and the breakpoint is set in 4725the same way. However, like the @code{tbreak} command, 4726the breakpoint is automatically deleted after the 4727first time your program stops there. Also, like the @code{hbreak} 4728command, the breakpoint requires hardware support and some target hardware 4729may not have this support. @xref{Disabling, ,Disabling Breakpoints}. 4730See also @ref{Conditions, ,Break Conditions}. 4731 4732@kindex rbreak 4733@cindex regular expression 4734@cindex breakpoints at functions matching a regexp 4735@cindex set breakpoints in many functions 4736@item rbreak @var{regex} 4737Set breakpoints on all functions matching the regular expression 4738@var{regex}. This command sets an unconditional breakpoint on all 4739matches, printing a list of all breakpoints it set. Once these 4740breakpoints are set, they are treated just like the breakpoints set with 4741the @code{break} command. You can delete them, disable them, or make 4742them conditional the same way as any other breakpoint. 4743 4744In programs using different languages, @value{GDBN} chooses the syntax 4745to print the list of all breakpoints it sets according to the 4746@samp{set language} value: using @samp{set language auto} 4747(see @ref{Automatically, ,Set Language Automatically}) means to use the 4748language of the breakpoint's function, other values mean to use 4749the manually specified language (see @ref{Manually, ,Set Language Manually}). 4750 4751The syntax of the regular expression is the standard one used with tools 4752like @file{grep}. Note that this is different from the syntax used by 4753shells, so for instance @code{foo*} matches all functions that include 4754an @code{fo} followed by zero or more @code{o}s. There is an implicit 4755@code{.*} leading and trailing the regular expression you supply, so to 4756match only functions that begin with @code{foo}, use @code{^foo}. 4757 4758@cindex non-member C@t{++} functions, set breakpoint in 4759When debugging C@t{++} programs, @code{rbreak} is useful for setting 4760breakpoints on overloaded functions that are not members of any special 4761classes. 4762 4763@cindex set breakpoints on all functions 4764The @code{rbreak} command can be used to set breakpoints in 4765@strong{all} the functions in a program, like this: 4766 4767@smallexample 4768(@value{GDBP}) rbreak . 4769@end smallexample 4770 4771@item rbreak @var{file}:@var{regex} 4772If @code{rbreak} is called with a filename qualification, it limits 4773the search for functions matching the given regular expression to the 4774specified @var{file}. This can be used, for example, to set breakpoints on 4775every function in a given file: 4776 4777@smallexample 4778(@value{GDBP}) rbreak file.c:. 4779@end smallexample 4780 4781The colon separating the filename qualifier from the regex may 4782optionally be surrounded by spaces. 4783 4784@kindex info breakpoints 4785@cindex @code{$_} and @code{info breakpoints} 4786@item info breakpoints @r{[}@var{list}@dots{}@r{]} 4787@itemx info break @r{[}@var{list}@dots{}@r{]} 4788Print a table of all breakpoints, watchpoints, tracepoints, and catchpoints set 4789and not deleted. Optional argument @var{n} means print information only about 4790the specified breakpoint(s) (or watchpoint(s) or tracepoint(s) or catchpoint(s)). 4791For each breakpoint, following columns are printed: 4792 4793@table @emph 4794@item Breakpoint Numbers 4795@item Type 4796Breakpoint, watchpoint, tracepoint, or catchpoint. 4797@item Disposition 4798Whether the breakpoint is marked to be disabled or deleted when hit. 4799@item Enabled or Disabled 4800Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints 4801that are not enabled. 4802@item Address 4803Where the breakpoint is in your program, as a memory address. For a 4804pending breakpoint whose address is not yet known, this field will 4805contain @samp{<PENDING>}. Such breakpoint won't fire until a shared 4806library that has the symbol or line referred by breakpoint is loaded. 4807See below for details. A breakpoint with several locations will 4808have @samp{<MULTIPLE>} in this field---see below for details. 4809@item What 4810Where the breakpoint is in the source for your program, as a file and 4811line number. For a pending breakpoint, the original string passed to 4812the breakpoint command will be listed as it cannot be resolved until 4813the appropriate shared library is loaded in the future. 4814@end table 4815 4816@noindent 4817If a breakpoint is conditional, there are two evaluation modes: ``host'' and 4818``target''. If mode is ``host'', breakpoint condition evaluation is done by 4819@value{GDBN} on the host's side. If it is ``target'', then the condition 4820is evaluated by the target. The @code{info break} command shows 4821the condition on the line following the affected breakpoint, together with 4822its condition evaluation mode in between parentheses. 4823 4824Breakpoint commands, if any, are listed after that. A pending breakpoint is 4825allowed to have a condition specified for it. The condition is not parsed for 4826validity until a shared library is loaded that allows the pending 4827breakpoint to resolve to a valid location. 4828 4829@noindent 4830@code{info break} with a breakpoint 4831number @var{n} as argument lists only that breakpoint. The 4832convenience variable @code{$_} and the default examining-address for 4833the @code{x} command are set to the address of the last breakpoint 4834listed (@pxref{Memory, ,Examining Memory}). 4835 4836@noindent 4837@code{info break} displays a count of the number of times the breakpoint 4838has been hit. This is especially useful in conjunction with the 4839@code{ignore} command. You can ignore a large number of breakpoint 4840hits, look at the breakpoint info to see how many times the breakpoint 4841was hit, and then run again, ignoring one less than that number. This 4842will get you quickly to the last hit of that breakpoint. 4843 4844@noindent 4845For a breakpoints with an enable count (xref) greater than 1, 4846@code{info break} also displays that count. 4847 4848@end table 4849 4850@value{GDBN} allows you to set any number of breakpoints at the same place in 4851your program. There is nothing silly or meaningless about this. When 4852the breakpoints are conditional, this is even useful 4853(@pxref{Conditions, ,Break Conditions}). 4854 4855@cindex multiple locations, breakpoints 4856@cindex breakpoints, multiple locations 4857It is possible that a single logical breakpoint is set at several code 4858locations in your program. @xref{Location Specifications}, for 4859examples. 4860 4861A breakpoint with multiple code locations is displayed in the 4862breakpoint table using several rows---one header row, followed by one 4863row for each code location. The header row has @samp{<MULTIPLE>} in 4864the address column. Each code location row contains the actual 4865address, source file, source line and function of its code location. 4866The number column for a code location is of the form 4867@var{breakpoint-number}.@var{location-number}. 4868 4869For example: 4870 4871@smallexample 4872Num Type Disp Enb Address What 48731 breakpoint keep y <MULTIPLE> 4874 stop only if i==1 4875 breakpoint already hit 1 time 48761.1 y 0x080486a2 in void foo<int>() at t.cc:8 48771.2 y 0x080486ca in void foo<double>() at t.cc:8 4878@end smallexample 4879 4880You cannot delete the individual locations from a breakpoint. However, 4881each location can be individually enabled or disabled by passing 4882@var{breakpoint-number}.@var{location-number} as argument to the 4883@code{enable} and @code{disable} commands. It's also possible to 4884@code{enable} and @code{disable} a range of @var{location-number} 4885locations using a @var{breakpoint-number} and two @var{location-number}s, 4886in increasing order, separated by a hyphen, like 4887@kbd{@var{breakpoint-number}.@var{location-number1}-@var{location-number2}}, 4888in which case @value{GDBN} acts on all the locations in the range (inclusive). 4889Disabling or enabling the parent breakpoint (@pxref{Disabling}) affects 4890all of the locations that belong to that breakpoint. 4891 4892Locations that are enabled while their parent breakpoint is disabled 4893won't trigger a break, and are denoted by @code{y-} in the @code{Enb} 4894column. For example: 4895 4896@smallexample 4897(@value{GDBP}) info breakpoints 4898Num Type Disp Enb Address What 48991 breakpoint keep n <MULTIPLE> 49001.1 y- 0x00000000000011b6 in ... 49011.2 y- 0x00000000000011c2 in ... 49021.3 n 0x00000000000011ce in ... 4903@end smallexample 4904 4905@cindex pending breakpoints 4906It's quite common to have a breakpoint inside a shared library. 4907Shared libraries can be loaded and unloaded explicitly, 4908and possibly repeatedly, as the program is executed. To support 4909this use case, @value{GDBN} updates breakpoint locations whenever 4910any shared library is loaded or unloaded. Typically, you would 4911set a breakpoint in a shared library at the beginning of your 4912debugging session, when the library is not loaded, and when the 4913symbols from the library are not available. When you try to set 4914breakpoint, @value{GDBN} will ask you if you want to set 4915a so called @dfn{pending breakpoint}---breakpoint whose address 4916is not yet resolved. 4917 4918After the program is run, whenever a new shared library is loaded, 4919@value{GDBN} reevaluates all the breakpoints. When a newly loaded 4920shared library contains the symbol or line referred to by some 4921pending breakpoint, that breakpoint is resolved and becomes an 4922ordinary breakpoint. When a library is unloaded, all breakpoints 4923that refer to its symbols or source lines become pending again. 4924 4925This logic works for breakpoints with multiple locations, too. For 4926example, if you have a breakpoint in a C@t{++} template function, and 4927a newly loaded shared library has an instantiation of that template, 4928a new location is added to the list of locations for the breakpoint. 4929 4930Except for having unresolved address, pending breakpoints do not 4931differ from regular breakpoints. You can set conditions or commands, 4932enable and disable them and perform other breakpoint operations. 4933 4934@value{GDBN} provides some additional commands for controlling what 4935happens when the @samp{break} command cannot resolve the location spec 4936to any code location in your program (@pxref{Location 4937Specifications}): 4938 4939@kindex set breakpoint pending 4940@kindex show breakpoint pending 4941@table @code 4942@item set breakpoint pending auto 4943This is the default behavior. When @value{GDBN} cannot resolve the 4944location spec, it queries you whether a pending breakpoint should be 4945created. 4946 4947@item set breakpoint pending on 4948This indicates that when @value{GDBN} cannot resolve the location 4949spec, it should create a pending breakpoint without confirmation. 4950 4951@item set breakpoint pending off 4952This indicates that pending breakpoints are not to be created. If 4953@value{GDBN} cannot resolve the location spec, it aborts the 4954breakpoint creation with an error. This setting does not affect any 4955pending breakpoints previously created. 4956 4957@item show breakpoint pending 4958Show the current behavior setting for creating pending breakpoints. 4959@end table 4960 4961The settings above only affect the @code{break} command and its 4962variants. Once a breakpoint is set, it will be automatically updated 4963as shared libraries are loaded and unloaded. 4964 4965@cindex automatic hardware breakpoints 4966For some targets, @value{GDBN} can automatically decide if hardware or 4967software breakpoints should be used, depending on whether the 4968breakpoint address is read-only or read-write. This applies to 4969breakpoints set with the @code{break} command as well as to internal 4970breakpoints set by commands like @code{next} and @code{finish}. For 4971breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware 4972breakpoints. 4973 4974You can control this automatic behaviour with the following commands: 4975 4976@kindex set breakpoint auto-hw 4977@kindex show breakpoint auto-hw 4978@table @code 4979@item set breakpoint auto-hw on 4980This is the default behavior. When @value{GDBN} sets a breakpoint, it 4981will try to use the target memory map to decide if software or hardware 4982breakpoint must be used. 4983 4984@item set breakpoint auto-hw off 4985This indicates @value{GDBN} should not automatically select breakpoint 4986type. If the target provides a memory map, @value{GDBN} will warn when 4987trying to set software breakpoint at a read-only address. 4988@end table 4989 4990@value{GDBN} normally implements breakpoints by replacing the program code 4991at the breakpoint address with a special instruction, which, when 4992executed, given control to the debugger. By default, the program 4993code is so modified only when the program is resumed. As soon as 4994the program stops, @value{GDBN} restores the original instructions. This 4995behaviour guards against leaving breakpoints inserted in the 4996target should gdb abrubptly disconnect. However, with slow remote 4997targets, inserting and removing breakpoint can reduce the performance. 4998This behavior can be controlled with the following commands:: 4999 5000@kindex set breakpoint always-inserted 5001@kindex show breakpoint always-inserted 5002@table @code 5003@item set breakpoint always-inserted off 5004All breakpoints, including newly added by the user, are inserted in 5005the target only when the target is resumed. All breakpoints are 5006removed from the target when it stops. This is the default mode. 5007 5008@item set breakpoint always-inserted on 5009Causes all breakpoints to be inserted in the target at all times. If 5010the user adds a new breakpoint, or changes an existing breakpoint, the 5011breakpoints in the target are updated immediately. A breakpoint is 5012removed from the target only when breakpoint itself is deleted. 5013@end table 5014 5015@value{GDBN} handles conditional breakpoints by evaluating these conditions 5016when a breakpoint breaks. If the condition is true, then the process being 5017debugged stops, otherwise the process is resumed. 5018 5019If the target supports evaluating conditions on its end, @value{GDBN} may 5020download the breakpoint, together with its conditions, to it. 5021 5022This feature can be controlled via the following commands: 5023 5024@kindex set breakpoint condition-evaluation 5025@kindex show breakpoint condition-evaluation 5026@table @code 5027@item set breakpoint condition-evaluation host 5028This option commands @value{GDBN} to evaluate the breakpoint 5029conditions on the host's side. Unconditional breakpoints are sent to 5030the target which in turn receives the triggers and reports them back to GDB 5031for condition evaluation. This is the standard evaluation mode. 5032 5033@item set breakpoint condition-evaluation target 5034This option commands @value{GDBN} to download breakpoint conditions 5035to the target at the moment of their insertion. The target 5036is responsible for evaluating the conditional expression and reporting 5037breakpoint stop events back to @value{GDBN} whenever the condition 5038is true. Due to limitations of target-side evaluation, some conditions 5039cannot be evaluated there, e.g., conditions that depend on local data 5040that is only known to the host. Examples include 5041conditional expressions involving convenience variables, complex types 5042that cannot be handled by the agent expression parser and expressions 5043that are too long to be sent over to the target, specially when the 5044target is a remote system. In these cases, the conditions will be 5045evaluated by @value{GDBN}. 5046 5047@item set breakpoint condition-evaluation auto 5048This is the default mode. If the target supports evaluating breakpoint 5049conditions on its end, @value{GDBN} will download breakpoint conditions to 5050the target (limitations mentioned previously apply). If the target does 5051not support breakpoint condition evaluation, then @value{GDBN} will fallback 5052to evaluating all these conditions on the host's side. 5053@end table 5054 5055 5056@cindex negative breakpoint numbers 5057@cindex internal @value{GDBN} breakpoints 5058@value{GDBN} itself sometimes sets breakpoints in your program for 5059special purposes, such as proper handling of @code{longjmp} (in C 5060programs). These internal breakpoints are assigned negative numbers, 5061starting with @code{-1}; @samp{info breakpoints} does not display them. 5062You can see these breakpoints with the @value{GDBN} maintenance command 5063@samp{maint info breakpoints} (@pxref{maint info breakpoints}). 5064 5065 5066@node Set Watchpoints 5067@subsection Setting Watchpoints 5068 5069@cindex setting watchpoints 5070You can use a watchpoint to stop execution whenever the value of an 5071expression changes, without having to predict a particular place where 5072this may happen. (This is sometimes called a @dfn{data breakpoint}.) 5073The expression may be as simple as the value of a single variable, or 5074as complex as many variables combined by operators. Examples include: 5075 5076@itemize @bullet 5077@item 5078A reference to the value of a single variable. 5079 5080@item 5081An address cast to an appropriate data type. For example, 5082@samp{*(int *)0x12345678} will watch a 4-byte region at the specified 5083address (assuming an @code{int} occupies 4 bytes). 5084 5085@item 5086An arbitrarily complex expression, such as @samp{a*b + c/d}. The 5087expression can use any operators valid in the program's native 5088language (@pxref{Languages}). 5089@end itemize 5090 5091You can set a watchpoint on an expression even if the expression can 5092not be evaluated yet. For instance, you can set a watchpoint on 5093@samp{*global_ptr} before @samp{global_ptr} is initialized. 5094@value{GDBN} will stop when your program sets @samp{global_ptr} and 5095the expression produces a valid value. If the expression becomes 5096valid in some other way than changing a variable (e.g.@: if the memory 5097pointed to by @samp{*global_ptr} becomes readable as the result of a 5098@code{malloc} call), @value{GDBN} may not stop until the next time 5099the expression changes. 5100 5101@cindex software watchpoints 5102@cindex hardware watchpoints 5103Depending on your system, watchpoints may be implemented in software or 5104hardware. @value{GDBN} does software watchpointing by single-stepping your 5105program and testing the variable's value each time, which is hundreds of 5106times slower than normal execution. (But this may still be worth it, to 5107catch errors where you have no clue what part of your program is the 5108culprit.) 5109 5110On some systems, such as most PowerPC or x86-based targets, 5111@value{GDBN} includes support for hardware watchpoints, which do not 5112slow down the running of your program. 5113 5114@table @code 5115@kindex watch 5116@item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]} @r{[}task @var{task-id}@r{]} 5117Set a watchpoint for an expression. @value{GDBN} will break when the 5118expression @var{expr} is written into by the program and its value 5119changes. The simplest (and the most popular) use of this command is 5120to watch the value of a single variable: 5121 5122@smallexample 5123(@value{GDBP}) watch foo 5124@end smallexample 5125 5126If the command includes a @code{@r{[}thread @var{thread-id}@r{]}} 5127argument, @value{GDBN} breaks only when the thread identified by 5128@var{thread-id} changes the value of @var{expr}. If any other threads 5129change the value of @var{expr}, @value{GDBN} will not break. Note 5130that watchpoints restricted to a single thread in this way only work 5131with Hardware Watchpoints. 5132 5133Similarly, if the @code{task} argument is given, then the watchpoint 5134will be specific to the indicated Ada task (@pxref{Ada Tasks}). 5135 5136Ordinarily a watchpoint respects the scope of variables in @var{expr} 5137(see below). The @code{-location} argument tells @value{GDBN} to 5138instead watch the memory referred to by @var{expr}. In this case, 5139@value{GDBN} will evaluate @var{expr}, take the address of the result, 5140and watch the memory at that address. The type of the result is used 5141to determine the size of the watched memory. If the expression's 5142result does not have an address, then @value{GDBN} will print an 5143error. 5144 5145The @code{@r{[}mask @var{maskvalue}@r{]}} argument allows creation 5146of masked watchpoints, if the current architecture supports this 5147feature (e.g., PowerPC Embedded architecture, see @ref{PowerPC 5148Embedded}.) A @dfn{masked watchpoint} specifies a mask in addition 5149to an address to watch. The mask specifies that some bits of an address 5150(the bits which are reset in the mask) should be ignored when matching 5151the address accessed by the inferior against the watchpoint address. 5152Thus, a masked watchpoint watches many addresses simultaneously---those 5153addresses whose unmasked bits are identical to the unmasked bits in the 5154watchpoint address. The @code{mask} argument implies @code{-location}. 5155Examples: 5156 5157@smallexample 5158(@value{GDBP}) watch foo mask 0xffff00ff 5159(@value{GDBP}) watch *0xdeadbeef mask 0xffffff00 5160@end smallexample 5161 5162@kindex rwatch 5163@item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]} 5164Set a watchpoint that will break when the value of @var{expr} is read 5165by the program. 5166 5167@kindex awatch 5168@item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]} 5169Set a watchpoint that will break when @var{expr} is either read from 5170or written into by the program. 5171 5172@kindex info watchpoints @r{[}@var{list}@dots{}@r{]} 5173@item info watchpoints @r{[}@var{list}@dots{}@r{]} 5174This command prints a list of watchpoints, using the same format as 5175@code{info break} (@pxref{Set Breaks}). 5176@end table 5177 5178If you watch for a change in a numerically entered address you need to 5179dereference it, as the address itself is just a constant number which will 5180never change. @value{GDBN} refuses to create a watchpoint that watches 5181a never-changing value: 5182 5183@smallexample 5184(@value{GDBP}) watch 0x600850 5185Cannot watch constant value 0x600850. 5186(@value{GDBP}) watch *(int *) 0x600850 5187Watchpoint 1: *(int *) 6293584 5188@end smallexample 5189 5190@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware 5191watchpoints execute very quickly, and the debugger reports a change in 5192value at the exact instruction where the change occurs. If @value{GDBN} 5193cannot set a hardware watchpoint, it sets a software watchpoint, which 5194executes more slowly and reports the change in value at the next 5195@emph{statement}, not the instruction, after the change occurs. 5196 5197@cindex use only software watchpoints 5198You can force @value{GDBN} to use only software watchpoints with the 5199@kbd{set can-use-hw-watchpoints 0} command. With this variable set to 5200zero, @value{GDBN} will never try to use hardware watchpoints, even if 5201the underlying system supports them. (Note that hardware-assisted 5202watchpoints that were set @emph{before} setting 5203@code{can-use-hw-watchpoints} to zero will still use the hardware 5204mechanism of watching expression values.) 5205 5206@table @code 5207@item set can-use-hw-watchpoints 5208@kindex set can-use-hw-watchpoints 5209Set whether or not to use hardware watchpoints. 5210 5211@item show can-use-hw-watchpoints 5212@kindex show can-use-hw-watchpoints 5213Show the current mode of using hardware watchpoints. 5214@end table 5215 5216For remote targets, you can restrict the number of hardware 5217watchpoints @value{GDBN} will use, see @ref{set remote 5218hardware-breakpoint-limit}. 5219 5220When you issue the @code{watch} command, @value{GDBN} reports 5221 5222@smallexample 5223Hardware watchpoint @var{num}: @var{expr} 5224@end smallexample 5225 5226@noindent 5227if it was able to set a hardware watchpoint. 5228 5229Currently, the @code{awatch} and @code{rwatch} commands can only set 5230hardware watchpoints, because accesses to data that don't change the 5231value of the watched expression cannot be detected without examining 5232every instruction as it is being executed, and @value{GDBN} does not do 5233that currently. If @value{GDBN} finds that it is unable to set a 5234hardware breakpoint with the @code{awatch} or @code{rwatch} command, it 5235will print a message like this: 5236 5237@smallexample 5238Expression cannot be implemented with read/access watchpoint. 5239@end smallexample 5240 5241Sometimes, @value{GDBN} cannot set a hardware watchpoint because the 5242data type of the watched expression is wider than what a hardware 5243watchpoint on the target machine can handle. For example, some systems 5244can only watch regions that are up to 4 bytes wide; on such systems you 5245cannot set hardware watchpoints for an expression that yields a 5246double-precision floating-point number (which is typically 8 bytes 5247wide). As a work-around, it might be possible to break the large region 5248into a series of smaller ones and watch them with separate watchpoints. 5249 5250If you set too many hardware watchpoints, @value{GDBN} might be unable 5251to insert all of them when you resume the execution of your program. 5252Since the precise number of active watchpoints is unknown until such 5253time as the program is about to be resumed, @value{GDBN} might not be 5254able to warn you about this when you set the watchpoints, and the 5255warning will be printed only when the program is resumed: 5256 5257@smallexample 5258Hardware watchpoint @var{num}: Could not insert watchpoint 5259@end smallexample 5260 5261@noindent 5262If this happens, delete or disable some of the watchpoints. 5263 5264Watching complex expressions that reference many variables can also 5265exhaust the resources available for hardware-assisted watchpoints. 5266That's because @value{GDBN} needs to watch every variable in the 5267expression with separately allocated resources. 5268 5269If you call a function interactively using @code{print} or @code{call}, 5270any watchpoints you have set will be inactive until @value{GDBN} reaches another 5271kind of breakpoint or the call completes. 5272 5273@value{GDBN} automatically deletes watchpoints that watch local 5274(automatic) variables, or expressions that involve such variables, when 5275they go out of scope, that is, when the execution leaves the block in 5276which these variables were defined. In particular, when the program 5277being debugged terminates, @emph{all} local variables go out of scope, 5278and so only watchpoints that watch global variables remain set. If you 5279rerun the program, you will need to set all such watchpoints again. One 5280way of doing that would be to set a code breakpoint at the entry to the 5281@code{main} function and when it breaks, set all the watchpoints. 5282 5283@cindex watchpoints and threads 5284@cindex threads and watchpoints 5285In multi-threaded programs, watchpoints will detect changes to the 5286watched expression from every thread. 5287 5288@quotation 5289@emph{Warning:} In multi-threaded programs, software watchpoints 5290have only limited usefulness. If @value{GDBN} creates a software 5291watchpoint, it can only watch the value of an expression @emph{in a 5292single thread}. If you are confident that the expression can only 5293change due to the current thread's activity (and if you are also 5294confident that no other thread can become current), then you can use 5295software watchpoints as usual. However, @value{GDBN} may not notice 5296when a non-current thread's activity changes the expression. (Hardware 5297watchpoints, in contrast, watch an expression in all threads.) 5298@end quotation 5299 5300@xref{set remote hardware-watchpoint-limit}. 5301 5302@node Set Catchpoints 5303@subsection Setting Catchpoints 5304@cindex catchpoints, setting 5305@cindex exception handlers 5306@cindex event handling 5307 5308You can use @dfn{catchpoints} to cause the debugger to stop for certain 5309kinds of program events, such as C@t{++} exceptions or the loading of a 5310shared library. Use the @code{catch} command to set a catchpoint. 5311 5312@table @code 5313@kindex catch 5314@item catch @var{event} 5315Stop when @var{event} occurs. The @var{event} can be any of the following: 5316 5317@table @code 5318@item throw @r{[}@var{regexp}@r{]} 5319@itemx rethrow @r{[}@var{regexp}@r{]} 5320@itemx catch @r{[}@var{regexp}@r{]} 5321@kindex catch throw 5322@kindex catch rethrow 5323@kindex catch catch 5324@cindex stop on C@t{++} exceptions 5325The throwing, re-throwing, or catching of a C@t{++} exception. 5326 5327If @var{regexp} is given, then only exceptions whose type matches the 5328regular expression will be caught. 5329 5330@vindex $_exception@r{, convenience variable} 5331The convenience variable @code{$_exception} is available at an 5332exception-related catchpoint, on some systems. This holds the 5333exception being thrown. 5334 5335There are currently some limitations to C@t{++} exception handling in 5336@value{GDBN}: 5337 5338@itemize @bullet 5339@item 5340The support for these commands is system-dependent. Currently, only 5341systems using the @samp{gnu-v3} C@t{++} ABI (@pxref{ABI}) are 5342supported. 5343 5344@item 5345The regular expression feature and the @code{$_exception} convenience 5346variable rely on the presence of some SDT probes in @code{libstdc++}. 5347If these probes are not present, then these features cannot be used. 5348These probes were first available in the GCC 4.8 release, but whether 5349or not they are available in your GCC also depends on how it was 5350built. 5351 5352@item 5353The @code{$_exception} convenience variable is only valid at the 5354instruction at which an exception-related catchpoint is set. 5355 5356@item 5357When an exception-related catchpoint is hit, @value{GDBN} stops at a 5358location in the system library which implements runtime exception 5359support for C@t{++}, usually @code{libstdc++}. You can use @code{up} 5360(@pxref{Selection}) to get to your code. 5361 5362@item 5363If you call a function interactively, @value{GDBN} normally returns 5364control to you when the function has finished executing. If the call 5365raises an exception, however, the call may bypass the mechanism that 5366returns control to you and cause your program either to abort or to 5367simply continue running until it hits a breakpoint, catches a signal 5368that @value{GDBN} is listening for, or exits. This is the case even if 5369you set a catchpoint for the exception; catchpoints on exceptions are 5370disabled within interactive calls. @xref{Calling}, for information on 5371controlling this with @code{set unwind-on-terminating-exception}. 5372 5373@item 5374You cannot raise an exception interactively. 5375 5376@item 5377You cannot install an exception handler interactively. 5378@end itemize 5379 5380@item exception @r{[}@var{name}@r{]} 5381@kindex catch exception 5382@cindex Ada exception catching 5383@cindex catch Ada exceptions 5384An Ada exception being raised. If an exception name is specified 5385at the end of the command (eg @code{catch exception Program_Error}), 5386the debugger will stop only when this specific exception is raised. 5387Otherwise, the debugger stops execution when any Ada exception is raised. 5388 5389When inserting an exception catchpoint on a user-defined exception whose 5390name is identical to one of the exceptions defined by the language, the 5391fully qualified name must be used as the exception name. Otherwise, 5392@value{GDBN} will assume that it should stop on the pre-defined exception 5393rather than the user-defined one. For instance, assuming an exception 5394called @code{Constraint_Error} is defined in package @code{Pck}, then 5395the command to use to catch such exceptions is @kbd{catch exception 5396Pck.Constraint_Error}. 5397 5398@vindex $_ada_exception@r{, convenience variable} 5399The convenience variable @code{$_ada_exception} holds the address of 5400the exception being thrown. This can be useful when setting a 5401condition for such a catchpoint. 5402 5403@item exception unhandled 5404@kindex catch exception unhandled 5405An exception that was raised but is not handled by the program. The 5406convenience variable @code{$_ada_exception} is set as for @code{catch 5407exception}. 5408 5409@item handlers @r{[}@var{name}@r{]} 5410@kindex catch handlers 5411@cindex Ada exception handlers catching 5412@cindex catch Ada exceptions when handled 5413An Ada exception being handled. If an exception name is 5414specified at the end of the command 5415 (eg @kbd{catch handlers Program_Error}), the debugger will stop 5416only when this specific exception is handled. 5417Otherwise, the debugger stops execution when any Ada exception is handled. 5418 5419When inserting a handlers catchpoint on a user-defined 5420exception whose name is identical to one of the exceptions 5421defined by the language, the fully qualified name must be used 5422as the exception name. Otherwise, @value{GDBN} will assume that it 5423should stop on the pre-defined exception rather than the 5424user-defined one. For instance, assuming an exception called 5425 @code{Constraint_Error} is defined in package @code{Pck}, then the 5426command to use to catch such exceptions handling is 5427@kbd{catch handlers Pck.Constraint_Error}. 5428 5429The convenience variable @code{$_ada_exception} is set as for 5430@code{catch exception}. 5431 5432@item assert 5433@kindex catch assert 5434A failed Ada assertion. Note that the convenience variable 5435@code{$_ada_exception} is @emph{not} set by this catchpoint. 5436 5437@item exec 5438@kindex catch exec 5439@cindex break on fork/exec 5440A call to @code{exec}. 5441 5442@anchor{catch syscall} 5443@item syscall 5444@itemx syscall @r{[}@var{name} @r{|} @var{number} @r{|} @r{group:}@var{groupname} @r{|} @r{g:}@var{groupname}@r{]} @dots{} 5445@kindex catch syscall 5446@cindex break on a system call. 5447A call to or return from a system call, a.k.a.@: @dfn{syscall}. A 5448syscall is a mechanism for application programs to request a service 5449from the operating system (OS) or one of the OS system services. 5450@value{GDBN} can catch some or all of the syscalls issued by the 5451debuggee, and show the related information for each syscall. If no 5452argument is specified, calls to and returns from all system calls 5453will be caught. 5454 5455@var{name} can be any system call name that is valid for the 5456underlying OS. Just what syscalls are valid depends on the OS. On 5457GNU and Unix systems, you can find the full list of valid syscall 5458names on @file{/usr/include/asm/unistd.h}. 5459 5460@c For MS-Windows, the syscall names and the corresponding numbers 5461@c can be found, e.g., on this URL: 5462@c http://www.metasploit.com/users/opcode/syscalls.html 5463@c but we don't support Windows syscalls yet. 5464 5465Normally, @value{GDBN} knows in advance which syscalls are valid for 5466each OS, so you can use the @value{GDBN} command-line completion 5467facilities (@pxref{Completion,, command completion}) to list the 5468available choices. 5469 5470You may also specify the system call numerically. A syscall's 5471number is the value passed to the OS's syscall dispatcher to 5472identify the requested service. When you specify the syscall by its 5473name, @value{GDBN} uses its database of syscalls to convert the name 5474into the corresponding numeric code, but using the number directly 5475may be useful if @value{GDBN}'s database does not have the complete 5476list of syscalls on your system (e.g., because @value{GDBN} lags 5477behind the OS upgrades). 5478 5479You may specify a group of related syscalls to be caught at once using 5480the @code{group:} syntax (@code{g:} is a shorter equivalent). For 5481instance, on some platforms @value{GDBN} allows you to catch all 5482network related syscalls, by passing the argument @code{group:network} 5483to @code{catch syscall}. Note that not all syscall groups are 5484available in every system. You can use the command completion 5485facilities (@pxref{Completion,, command completion}) to list the 5486syscall groups available on your environment. 5487 5488The example below illustrates how this command works if you don't provide 5489arguments to it: 5490 5491@smallexample 5492(@value{GDBP}) catch syscall 5493Catchpoint 1 (syscall) 5494(@value{GDBP}) r 5495Starting program: /tmp/catch-syscall 5496 5497Catchpoint 1 (call to syscall 'close'), \ 5498 0xffffe424 in __kernel_vsyscall () 5499(@value{GDBP}) c 5500Continuing. 5501 5502Catchpoint 1 (returned from syscall 'close'), \ 5503 0xffffe424 in __kernel_vsyscall () 5504(@value{GDBP}) 5505@end smallexample 5506 5507Here is an example of catching a system call by name: 5508 5509@smallexample 5510(@value{GDBP}) catch syscall chroot 5511Catchpoint 1 (syscall 'chroot' [61]) 5512(@value{GDBP}) r 5513Starting program: /tmp/catch-syscall 5514 5515Catchpoint 1 (call to syscall 'chroot'), \ 5516 0xffffe424 in __kernel_vsyscall () 5517(@value{GDBP}) c 5518Continuing. 5519 5520Catchpoint 1 (returned from syscall 'chroot'), \ 5521 0xffffe424 in __kernel_vsyscall () 5522(@value{GDBP}) 5523@end smallexample 5524 5525An example of specifying a system call numerically. In the case 5526below, the syscall number has a corresponding entry in the XML 5527file, so @value{GDBN} finds its name and prints it: 5528 5529@smallexample 5530(@value{GDBP}) catch syscall 252 5531Catchpoint 1 (syscall(s) 'exit_group') 5532(@value{GDBP}) r 5533Starting program: /tmp/catch-syscall 5534 5535Catchpoint 1 (call to syscall 'exit_group'), \ 5536 0xffffe424 in __kernel_vsyscall () 5537(@value{GDBP}) c 5538Continuing. 5539 5540Program exited normally. 5541(@value{GDBP}) 5542@end smallexample 5543 5544Here is an example of catching a syscall group: 5545 5546@smallexample 5547(@value{GDBP}) catch syscall group:process 5548Catchpoint 1 (syscalls 'exit' [1] 'fork' [2] 'waitpid' [7] 5549'execve' [11] 'wait4' [114] 'clone' [120] 'vfork' [190] 5550'exit_group' [252] 'waitid' [284] 'unshare' [310]) 5551(@value{GDBP}) r 5552Starting program: /tmp/catch-syscall 5553 5554Catchpoint 1 (call to syscall fork), 0x00007ffff7df4e27 in open64 () 5555 from /lib64/ld-linux-x86-64.so.2 5556 5557(@value{GDBP}) c 5558Continuing. 5559@end smallexample 5560 5561However, there can be situations when there is no corresponding name 5562in XML file for that syscall number. In this case, @value{GDBN} prints 5563a warning message saying that it was not able to find the syscall name, 5564but the catchpoint will be set anyway. See the example below: 5565 5566@smallexample 5567(@value{GDBP}) catch syscall 764 5568warning: The number '764' does not represent a known syscall. 5569Catchpoint 2 (syscall 764) 5570(@value{GDBP}) 5571@end smallexample 5572 5573If you configure @value{GDBN} using the @samp{--without-expat} option, 5574it will not be able to display syscall names. Also, if your 5575architecture does not have an XML file describing its system calls, 5576you will not be able to see the syscall names. It is important to 5577notice that these two features are used for accessing the syscall 5578name database. In either case, you will see a warning like this: 5579 5580@smallexample 5581(@value{GDBP}) catch syscall 5582warning: Could not open "syscalls/i386-linux.xml" 5583warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'. 5584GDB will not be able to display syscall names. 5585Catchpoint 1 (syscall) 5586(@value{GDBP}) 5587@end smallexample 5588 5589Of course, the file name will change depending on your architecture and system. 5590 5591Still using the example above, you can also try to catch a syscall by its 5592number. In this case, you would see something like: 5593 5594@smallexample 5595(@value{GDBP}) catch syscall 252 5596Catchpoint 1 (syscall(s) 252) 5597@end smallexample 5598 5599Again, in this case @value{GDBN} would not be able to display syscall's names. 5600 5601@item fork 5602@kindex catch fork 5603A call to @code{fork}. 5604 5605@item vfork 5606@kindex catch vfork 5607A call to @code{vfork}. 5608 5609@item load @r{[}@var{regexp}@r{]} 5610@itemx unload @r{[}@var{regexp}@r{]} 5611@kindex catch load 5612@kindex catch unload 5613The loading or unloading of a shared library. If @var{regexp} is 5614given, then the catchpoint will stop only if the regular expression 5615matches one of the affected libraries. 5616 5617@item signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]} 5618@kindex catch signal 5619The delivery of a signal. 5620 5621With no arguments, this catchpoint will catch any signal that is not 5622used internally by @value{GDBN}, specifically, all signals except 5623@samp{SIGTRAP} and @samp{SIGINT}. 5624 5625With the argument @samp{all}, all signals, including those used by 5626@value{GDBN}, will be caught. This argument cannot be used with other 5627signal names. 5628 5629Otherwise, the arguments are a list of signal names as given to 5630@code{handle} (@pxref{Signals}). Only signals specified in this list 5631will be caught. 5632 5633One reason that @code{catch signal} can be more useful than 5634@code{handle} is that you can attach commands and conditions to the 5635catchpoint. 5636 5637When a signal is caught by a catchpoint, the signal's @code{stop} and 5638@code{print} settings, as specified by @code{handle}, are ignored. 5639However, whether the signal is still delivered to the inferior depends 5640on the @code{pass} setting; this can be changed in the catchpoint's 5641commands. 5642 5643@end table 5644 5645@item tcatch @var{event} 5646@kindex tcatch 5647Set a catchpoint that is enabled only for one stop. The catchpoint is 5648automatically deleted after the first time the event is caught. 5649 5650@end table 5651 5652Use the @code{info break} command to list the current catchpoints. 5653 5654 5655@node Delete Breaks 5656@subsection Deleting Breakpoints 5657 5658@cindex clearing breakpoints, watchpoints, catchpoints 5659@cindex deleting breakpoints, watchpoints, catchpoints 5660It is often necessary to eliminate a breakpoint, watchpoint, or 5661catchpoint once it has done its job and you no longer want your program 5662to stop there. This is called @dfn{deleting} the breakpoint. A 5663breakpoint that has been deleted no longer exists; it is forgotten. 5664 5665With the @code{clear} command you can delete breakpoints according to 5666where they are in your program. With the @code{delete} command you can 5667delete individual breakpoints, watchpoints, or catchpoints by specifying 5668their breakpoint numbers. 5669 5670It is not necessary to delete a breakpoint to proceed past it. @value{GDBN} 5671automatically ignores breakpoints on the first instruction to be executed 5672when you continue execution without changing the execution address. 5673 5674@table @code 5675@kindex clear 5676@item clear 5677Delete any breakpoints at the next instruction to be executed in the 5678selected stack frame (@pxref{Selection, ,Selecting a Frame}). When 5679the innermost frame is selected, this is a good way to delete a 5680breakpoint where your program just stopped. 5681 5682@item clear @var{locspec} 5683Delete any breakpoint with a code location that corresponds to 5684@var{locspec}. @xref{Location Specifications}, for the various forms 5685of @var{locspec}. Which code locations correspond to @var{locspec} 5686depends on the form used in the location specification @var{locspec}: 5687 5688@table @code 5689@item @var{linenum} 5690@itemx @var{filename}:@var{linenum} 5691@itemx -line @var{linenum} 5692@itemx -source @var{filename} -line @var{linenum} 5693If @var{locspec} specifies a line number, with or without a file name, 5694the command deletes any breakpoint with a code location that is at or 5695within the specified line @var{linenum} in files that match the 5696specified @var{filename}. If @var{filename} is omitted, it defaults 5697to the current source file. 5698 5699@item *@var{address} 5700If @var{locspec} specifies an address, the command deletes any 5701breakpoint with a code location that is at the given @var{address}. 5702 5703@item @var{function} 5704@itemx -function @var{function} 5705If @var{locspec} specifies a function, the command deletes any 5706breakpoint with a code location that is at the entry to any function 5707whose name matches @var{function}. 5708@end table 5709 5710Ambiguity in names of files and functions can be resolved as described 5711in @ref{Location Specifications}. 5712 5713@cindex delete breakpoints 5714@kindex delete 5715@kindex d @r{(@code{delete})} 5716@item delete @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]} 5717Delete the breakpoints, watchpoints, tracepoints, or catchpoints of the 5718breakpoint list specified as argument. If no argument is specified, delete 5719all breakpoints, watchpoints, tracepoints, and catchpoints (@value{GDBN} asks 5720confirmation, unless you have @code{set confirm off}). You can abbreviate this 5721command as @code{d}. 5722@end table 5723 5724@node Disabling 5725@subsection Disabling Breakpoints 5726 5727@cindex enable/disable a breakpoint 5728Rather than deleting a breakpoint, watchpoint, or catchpoint, you might 5729prefer to @dfn{disable} it. This makes the breakpoint inoperative as if 5730it had been deleted, but remembers the information on the breakpoint so 5731that you can @dfn{enable} it again later. 5732 5733You disable and enable breakpoints, watchpoints, tracepoints, and catchpoints 5734with the @code{enable} and @code{disable} commands, optionally specifying 5735one or more breakpoint numbers as arguments. Use @code{info break} to print 5736a list of all breakpoints, watchpoints, tracepoints, and catchpoints if you 5737do not know which numbers to use. 5738 5739Disabling and enabling a breakpoint that has multiple locations 5740affects all of its locations. 5741 5742A breakpoint, watchpoint, or catchpoint can have any of several 5743different states of enablement: 5744 5745@itemize @bullet 5746@item 5747Enabled. The breakpoint stops your program. A breakpoint set 5748with the @code{break} command starts out in this state. 5749@item 5750Disabled. The breakpoint has no effect on your program. 5751@item 5752Enabled once. The breakpoint stops your program, but then becomes 5753disabled. 5754@item 5755Enabled for a count. The breakpoint stops your program for the next 5756N times, then becomes disabled. 5757@item 5758Enabled for deletion. The breakpoint stops your program, but 5759immediately after it does so it is deleted permanently. A breakpoint 5760set with the @code{tbreak} command starts out in this state. 5761@end itemize 5762 5763You can use the following commands to enable or disable breakpoints, 5764watchpoints, tracepoints, and catchpoints: 5765 5766@table @code 5767@kindex disable 5768@kindex dis @r{(@code{disable})} 5769@item disable @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]} 5770Disable the specified breakpoints---or all breakpoints, if none are 5771listed. A disabled breakpoint has no effect but is not forgotten. All 5772options such as ignore-counts, conditions and commands are remembered in 5773case the breakpoint is enabled again later. You may abbreviate 5774@code{disable} as @code{dis}. 5775 5776@kindex enable 5777@item enable @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]} 5778Enable the specified breakpoints (or all defined breakpoints). They 5779become effective once again in stopping your program. 5780 5781@item enable @r{[}breakpoints@r{]} once @var{list}@dots{} 5782Enable the specified breakpoints temporarily. @value{GDBN} disables any 5783of these breakpoints immediately after stopping your program. 5784 5785@item enable @r{[}breakpoints@r{]} count @var{count} @var{list}@dots{} 5786Enable the specified breakpoints temporarily. @value{GDBN} records 5787@var{count} with each of the specified breakpoints, and decrements a 5788breakpoint's count when it is hit. When any count reaches 0, 5789@value{GDBN} disables that breakpoint. If a breakpoint has an ignore 5790count (@pxref{Conditions, ,Break Conditions}), that will be 5791decremented to 0 before @var{count} is affected. 5792 5793@item enable @r{[}breakpoints@r{]} delete @var{list}@dots{} 5794Enable the specified breakpoints to work once, then die. @value{GDBN} 5795deletes any of these breakpoints as soon as your program stops there. 5796Breakpoints set by the @code{tbreak} command start out in this state. 5797@end table 5798 5799@c FIXME: I think the following ``Except for [...] @code{tbreak}'' is 5800@c confusing: tbreak is also initially enabled. 5801Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks, 5802,Setting Breakpoints}), breakpoints that you set are initially enabled; 5803subsequently, they become disabled or enabled only when you use one of 5804the commands above. (The command @code{until} can set and delete a 5805breakpoint of its own, but it does not change the state of your other 5806breakpoints; see @ref{Continuing and Stepping, ,Continuing and 5807Stepping}.) 5808 5809@node Conditions 5810@subsection Break Conditions 5811@cindex conditional breakpoints 5812@cindex breakpoint conditions 5813 5814@c FIXME what is scope of break condition expr? Context where wanted? 5815@c in particular for a watchpoint? 5816The simplest sort of breakpoint breaks every time your program reaches a 5817specified place. You can also specify a @dfn{condition} for a 5818breakpoint. A condition is just a Boolean expression in your 5819programming language (@pxref{Expressions, ,Expressions}). A breakpoint with 5820a condition evaluates the expression each time your program reaches it, 5821and your program stops only if the condition is @emph{true}. 5822 5823This is the converse of using assertions for program validation; in that 5824situation, you want to stop when the assertion is violated---that is, 5825when the condition is false. In C, if you want to test an assertion expressed 5826by the condition @var{assert}, you should set the condition 5827@samp{! @var{assert}} on the appropriate breakpoint. 5828 5829Conditions are also accepted for watchpoints; you may not need them, 5830since a watchpoint is inspecting the value of an expression anyhow---but 5831it might be simpler, say, to just set a watchpoint on a variable name, 5832and specify a condition that tests whether the new value is an interesting 5833one. 5834 5835Break conditions can have side effects, and may even call functions in 5836your program. This can be useful, for example, to activate functions 5837that log program progress, or to use your own print functions to 5838format special data structures. The effects are completely predictable 5839unless there is another enabled breakpoint at the same address. (In 5840that case, @value{GDBN} might see the other breakpoint first and stop your 5841program without checking the condition of this one.) Note that 5842breakpoint commands are usually more convenient and flexible than break 5843conditions for the 5844purpose of performing side effects when a breakpoint is reached 5845(@pxref{Break Commands, ,Breakpoint Command Lists}). 5846 5847Breakpoint conditions can also be evaluated on the target's side if 5848the target supports it. Instead of evaluating the conditions locally, 5849@value{GDBN} encodes the expression into an agent expression 5850(@pxref{Agent Expressions}) suitable for execution on the target, 5851independently of @value{GDBN}. Global variables become raw memory 5852locations, locals become stack accesses, and so forth. 5853 5854In this case, @value{GDBN} will only be notified of a breakpoint trigger 5855when its condition evaluates to true. This mechanism may provide faster 5856response times depending on the performance characteristics of the target 5857since it does not need to keep @value{GDBN} informed about 5858every breakpoint trigger, even those with false conditions. 5859 5860Break conditions can be specified when a breakpoint is set, by using 5861@samp{if} in the arguments to the @code{break} command. @xref{Set 5862Breaks, ,Setting Breakpoints}. They can also be changed at any time 5863with the @code{condition} command. 5864 5865You can also use the @code{if} keyword with the @code{watch} command. 5866The @code{catch} command does not recognize the @code{if} keyword; 5867@code{condition} is the only way to impose a further condition on a 5868catchpoint. 5869 5870@table @code 5871@kindex condition 5872@item condition @var{bnum} @var{expression} 5873Specify @var{expression} as the break condition for breakpoint, 5874watchpoint, or catchpoint number @var{bnum}. After you set a condition, 5875breakpoint @var{bnum} stops your program only if the value of 5876@var{expression} is true (nonzero, in C). When you use 5877@code{condition}, @value{GDBN} checks @var{expression} immediately for 5878syntactic correctness, and to determine whether symbols in it have 5879referents in the context of your breakpoint. If @var{expression} uses 5880symbols not referenced in the context of the breakpoint, @value{GDBN} 5881prints an error message: 5882 5883@smallexample 5884No symbol "foo" in current context. 5885@end smallexample 5886 5887@noindent 5888@value{GDBN} does 5889not actually evaluate @var{expression} at the time the @code{condition} 5890command (or a command that sets a breakpoint with a condition, like 5891@code{break if @dots{}}) is given, however. @xref{Expressions, ,Expressions}. 5892 5893@item condition -force @var{bnum} @var{expression} 5894When the @code{-force} flag is used, define the condition even if 5895@var{expression} is invalid at all the current locations of breakpoint 5896@var{bnum}. This is similar to the @code{-force-condition} option 5897of the @code{break} command. 5898 5899@item condition @var{bnum} 5900Remove the condition from breakpoint number @var{bnum}. It becomes 5901an ordinary unconditional breakpoint. 5902@end table 5903 5904@cindex ignore count (of breakpoint) 5905A special case of a breakpoint condition is to stop only when the 5906breakpoint has been reached a certain number of times. This is so 5907useful that there is a special way to do it, using the @dfn{ignore 5908count} of the breakpoint. Every breakpoint has an ignore count, which 5909is an integer. Most of the time, the ignore count is zero, and 5910therefore has no effect. But if your program reaches a breakpoint whose 5911ignore count is positive, then instead of stopping, it just decrements 5912the ignore count by one and continues. As a result, if the ignore count 5913value is @var{n}, the breakpoint does not stop the next @var{n} times 5914your program reaches it. 5915 5916@table @code 5917@kindex ignore 5918@item ignore @var{bnum} @var{count} 5919Set the ignore count of breakpoint number @var{bnum} to @var{count}. 5920The next @var{count} times the breakpoint is reached, your program's 5921execution does not stop; other than to decrement the ignore count, @value{GDBN} 5922takes no action. 5923 5924To make the breakpoint stop the next time it is reached, specify 5925a count of zero. 5926 5927When you use @code{continue} to resume execution of your program from a 5928breakpoint, you can specify an ignore count directly as an argument to 5929@code{continue}, rather than using @code{ignore}. @xref{Continuing and 5930Stepping,,Continuing and Stepping}. 5931 5932If a breakpoint has a positive ignore count and a condition, the 5933condition is not checked. Once the ignore count reaches zero, 5934@value{GDBN} resumes checking the condition. 5935 5936You could achieve the effect of the ignore count with a condition such 5937as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that 5938is decremented each time. @xref{Convenience Vars, ,Convenience 5939Variables}. 5940@end table 5941 5942Ignore counts apply to breakpoints, watchpoints, tracepoints, and catchpoints. 5943 5944 5945@node Break Commands 5946@subsection Breakpoint Command Lists 5947 5948@cindex breakpoint commands 5949You can give any breakpoint (or watchpoint or catchpoint) a series of 5950commands to execute when your program stops due to that breakpoint. For 5951example, you might want to print the values of certain expressions, or 5952enable other breakpoints. 5953 5954@table @code 5955@kindex commands 5956@kindex end@r{ (breakpoint commands)} 5957@item commands @r{[}@var{list}@dots{}@r{]} 5958@itemx @dots{} @var{command-list} @dots{} 5959@itemx end 5960Specify a list of commands for the given breakpoints. The commands 5961themselves appear on the following lines. Type a line containing just 5962@code{end} to terminate the commands. 5963 5964To remove all commands from a breakpoint, type @code{commands} and 5965follow it immediately with @code{end}; that is, give no commands. 5966 5967With no argument, @code{commands} refers to the last breakpoint, 5968watchpoint, or catchpoint set (not to the breakpoint most recently 5969encountered). If the most recent breakpoints were set with a single 5970command, then the @code{commands} will apply to all the breakpoints 5971set by that command. This applies to breakpoints set by 5972@code{rbreak}, and also applies when a single @code{break} command 5973creates multiple breakpoints (@pxref{Ambiguous Expressions,,Ambiguous 5974Expressions}). 5975@end table 5976 5977Pressing @key{RET} as a means of repeating the last @value{GDBN} command is 5978disabled within a @var{command-list}. 5979 5980Inside a command list, you can use the command 5981@kbd{disable $_hit_bpnum} to disable the encountered breakpoint. 5982 5983If your breakpoint has several code locations, the command 5984@kbd{disable $_hit_bpnum.$_hit_locno} will disable the specific breakpoint 5985code location encountered. If the breakpoint has only one location, 5986this command will disable the encountered breakpoint. 5987 5988You can use breakpoint commands to start your program up again. Simply 5989use the @code{continue} command, or @code{step}, or any other command 5990that resumes execution. 5991 5992Any other commands in the command list, after a command that resumes 5993execution, are ignored. This is because any time you resume execution 5994(even with a simple @code{next} or @code{step}), you may encounter 5995another breakpoint---which could have its own command list, leading to 5996ambiguities about which list to execute. 5997 5998@kindex silent 5999If the first command you specify in a command list is @code{silent}, the 6000usual message about stopping at a breakpoint is not printed. This may 6001be desirable for breakpoints that are to print a specific message and 6002then continue. If none of the remaining commands print anything, you 6003see no sign that the breakpoint was reached. @code{silent} is 6004meaningful only at the beginning of a breakpoint command list. 6005 6006The commands @code{echo}, @code{output}, and @code{printf} allow you to 6007print precisely controlled output, and are often useful in silent 6008breakpoints. @xref{Output, ,Commands for Controlled Output}. 6009 6010For example, here is how you could use breakpoint commands to print the 6011value of @code{x} at entry to @code{foo} whenever @code{x} is positive. 6012 6013@smallexample 6014break foo if x>0 6015commands 6016silent 6017printf "x is %d\n",x 6018cont 6019end 6020@end smallexample 6021 6022One application for breakpoint commands is to compensate for one bug so 6023you can test for another. Put a breakpoint just after the erroneous line 6024of code, give it a condition to detect the case in which something 6025erroneous has been done, and give it commands to assign correct values 6026to any variables that need them. End with the @code{continue} command 6027so that your program does not stop, and start with the @code{silent} 6028command so that no output is produced. Here is an example: 6029 6030@smallexample 6031break 403 6032commands 6033silent 6034set x = y + 4 6035cont 6036end 6037@end smallexample 6038 6039@node Dynamic Printf 6040@subsection Dynamic Printf 6041 6042@cindex dynamic printf 6043@cindex dprintf 6044The dynamic printf command @code{dprintf} combines a breakpoint with 6045formatted printing of your program's data to give you the effect of 6046inserting @code{printf} calls into your program on-the-fly, without 6047having to recompile it. 6048 6049In its most basic form, the output goes to the GDB console. However, 6050you can set the variable @code{dprintf-style} for alternate handling. 6051For instance, you can ask to format the output by calling your 6052program's @code{printf} function. This has the advantage that the 6053characters go to the program's output device, so they can recorded in 6054redirects to files and so forth. 6055 6056If you are doing remote debugging with a stub or agent, you can also 6057ask to have the printf handled by the remote agent. In addition to 6058ensuring that the output goes to the remote program's device along 6059with any other output the program might produce, you can also ask that 6060the dprintf remain active even after disconnecting from the remote 6061target. Using the stub/agent is also more efficient, as it can do 6062everything without needing to communicate with @value{GDBN}. 6063 6064@table @code 6065@kindex dprintf 6066@item dprintf @var{locspec},@var{template},@var{expression}[,@var{expression}@dots{}] 6067Whenever execution reaches a code location that results from resolving 6068@var{locspec}, print the values of one or more @var{expressions} under 6069the control of the string @var{template}. To print several values, 6070separate them with commas. 6071 6072@item set dprintf-style @var{style} 6073Set the dprintf output to be handled in one of several different 6074styles enumerated below. A change of style affects all existing 6075dynamic printfs immediately. (If you need individual control over the 6076print commands, simply define normal breakpoints with 6077explicitly-supplied command lists.) 6078 6079@table @code 6080@item gdb 6081@kindex dprintf-style gdb 6082Handle the output using the @value{GDBN} @code{printf} command. When 6083using this style, it is possible to use the @samp{%V} format specifier 6084(@pxref{%V Format Specifier}). 6085 6086@item call 6087@kindex dprintf-style call 6088Handle the output by calling a function in your program (normally 6089@code{printf}). When using this style the supported format specifiers 6090depend entirely on the function being called. 6091 6092Most of @value{GDBN}'s format specifiers align with those supported by 6093the @code{printf} function, however, @value{GDBN}'s @samp{%V} format 6094specifier extension is not supported by @code{printf}. When using 6095@samp{call} style dprintf, care should be taken to ensure that only 6096format specifiers supported by the output function are used, otherwise 6097the results will be undefined. 6098 6099@item agent 6100@kindex dprintf-style agent 6101Have the remote debugging agent (such as @code{gdbserver}) handle the 6102output itself. This style is only available for agents that support 6103running commands on the target. This style does not support the 6104@samp{%V} format specifier. 6105@end table 6106 6107@item set dprintf-function @var{function} 6108Set the function to call if the dprintf style is @code{call}. By 6109default its value is @code{printf}. You may set it to any expression 6110that @value{GDBN} can evaluate to a function, as per the @code{call} 6111command. 6112 6113@item set dprintf-channel @var{channel} 6114Set a ``channel'' for dprintf. If set to a non-empty value, 6115@value{GDBN} will evaluate it as an expression and pass the result as 6116a first argument to the @code{dprintf-function}, in the manner of 6117@code{fprintf} and similar functions. Otherwise, the dprintf format 6118string will be the first argument, in the manner of @code{printf}. 6119 6120As an example, if you wanted @code{dprintf} output to go to a logfile 6121that is a standard I/O stream assigned to the variable @code{mylog}, 6122you could do the following: 6123 6124@example 6125(@value{GDBP}) set dprintf-style call 6126(@value{GDBP}) set dprintf-function fprintf 6127(@value{GDBP}) set dprintf-channel mylog 6128(@value{GDBP}) dprintf 25,"at line 25, glob=%d\n",glob 6129Dprintf 1 at 0x123456: file main.c, line 25. 6130(@value{GDBP}) info break 61311 dprintf keep y 0x00123456 in main at main.c:25 6132 call (void) fprintf (mylog,"at line 25, glob=%d\n",glob) 6133 continue 6134(@value{GDBP}) 6135@end example 6136 6137Note that the @code{info break} displays the dynamic printf commands 6138as normal breakpoint commands; you can thus easily see the effect of 6139the variable settings. 6140 6141@item set disconnected-dprintf on 6142@itemx set disconnected-dprintf off 6143@kindex set disconnected-dprintf 6144Choose whether @code{dprintf} commands should continue to run if 6145@value{GDBN} has disconnected from the target. This only applies 6146if the @code{dprintf-style} is @code{agent}. 6147 6148@item show disconnected-dprintf off 6149@kindex show disconnected-dprintf 6150Show the current choice for disconnected @code{dprintf}. 6151 6152@end table 6153 6154@value{GDBN} does not check the validity of function and channel, 6155relying on you to supply values that are meaningful for the contexts 6156in which they are being used. For instance, the function and channel 6157may be the values of local variables, but if that is the case, then 6158all enabled dynamic prints must be at locations within the scope of 6159those locals. If evaluation fails, @value{GDBN} will report an error. 6160 6161@node Save Breakpoints 6162@subsection How to save breakpoints to a file 6163 6164To save breakpoint definitions to a file use the @w{@code{save 6165breakpoints}} command. 6166 6167@table @code 6168@kindex save breakpoints 6169@cindex save breakpoints to a file for future sessions 6170@item save breakpoints [@var{filename}] 6171This command saves all current breakpoint definitions together with 6172their commands and ignore counts, into a file @file{@var{filename}} 6173suitable for use in a later debugging session. This includes all 6174types of breakpoints (breakpoints, watchpoints, catchpoints, 6175tracepoints). To read the saved breakpoint definitions, use the 6176@code{source} command (@pxref{Command Files}). Note that watchpoints 6177with expressions involving local variables may fail to be recreated 6178because it may not be possible to access the context where the 6179watchpoint is valid anymore. Because the saved breakpoint definitions 6180are simply a sequence of @value{GDBN} commands that recreate the 6181breakpoints, you can edit the file in your favorite editing program, 6182and remove the breakpoint definitions you're not interested in, or 6183that can no longer be recreated. 6184@end table 6185 6186@node Static Probe Points 6187@subsection Static Probe Points 6188 6189@cindex static probe point, SystemTap 6190@cindex static probe point, DTrace 6191@value{GDBN} supports @dfn{SDT} probes in the code. @acronym{SDT} stands 6192for Statically Defined Tracing, and the probes are designed to have a tiny 6193runtime code and data footprint, and no dynamic relocations. 6194 6195Currently, the following types of probes are supported on 6196ELF-compatible systems: 6197 6198@itemize @bullet 6199 6200@item @code{SystemTap} (@uref{http://sourceware.org/systemtap/}) 6201@acronym{SDT} probes@footnote{See 6202@uref{http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps} 6203for more information on how to add @code{SystemTap} @acronym{SDT} 6204probes in your applications.}. @code{SystemTap} probes are usable 6205from assembly, C and C@t{++} languages@footnote{See 6206@uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation} 6207for a good reference on how the @acronym{SDT} probes are implemented.}. 6208 6209@item @code{DTrace} (@uref{http://oss.oracle.com/projects/DTrace}) 6210@acronym{USDT} probes. @code{DTrace} probes are usable from C and 6211C@t{++} languages. 6212@end itemize 6213 6214@cindex semaphores on static probe points 6215Some @code{SystemTap} probes have an associated semaphore variable; 6216for instance, this happens automatically if you defined your probe 6217using a DTrace-style @file{.d} file. If your probe has a semaphore, 6218@value{GDBN} will automatically enable it when you specify a 6219breakpoint using the @samp{-probe-stap} notation. But, if you put a 6220breakpoint at a probe's location by some other method (e.g., 6221@code{break file:line}), then @value{GDBN} will not automatically set 6222the semaphore. @code{DTrace} probes do not support semaphores. 6223 6224You can examine the available static static probes using @code{info 6225probes}, with optional arguments: 6226 6227@table @code 6228@kindex info probes 6229@item info probes @r{[}@var{type}@r{]} @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]} 6230If given, @var{type} is either @code{stap} for listing 6231@code{SystemTap} probes or @code{dtrace} for listing @code{DTrace} 6232probes. If omitted all probes are listed regardless of their types. 6233 6234If given, @var{provider} is a regular expression used to match against provider 6235names when selecting which probes to list. If omitted, probes by all 6236probes from all providers are listed. 6237 6238If given, @var{name} is a regular expression to match against probe names 6239when selecting which probes to list. If omitted, probe names are not 6240considered when deciding whether to display them. 6241 6242If given, @var{objfile} is a regular expression used to select which 6243object files (executable or shared libraries) to examine. If not 6244given, all object files are considered. 6245 6246@item info probes all 6247List the available static probes, from all types. 6248@end table 6249 6250@cindex enabling and disabling probes 6251Some probe points can be enabled and/or disabled. The effect of 6252enabling or disabling a probe depends on the type of probe being 6253handled. Some @code{DTrace} probes can be enabled or 6254disabled, but @code{SystemTap} probes cannot be disabled. 6255 6256You can enable (or disable) one or more probes using the following 6257commands, with optional arguments: 6258 6259@anchor{enable probes} 6260@table @code 6261@kindex enable probes 6262@item enable probes @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]} 6263If given, @var{provider} is a regular expression used to match against 6264provider names when selecting which probes to enable. If omitted, 6265all probes from all providers are enabled. 6266 6267If given, @var{name} is a regular expression to match against probe 6268names when selecting which probes to enable. If omitted, probe names 6269are not considered when deciding whether to enable them. 6270 6271If given, @var{objfile} is a regular expression used to select which 6272object files (executable or shared libraries) to examine. If not 6273given, all object files are considered. 6274 6275@kindex disable probes 6276@item disable probes @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]} 6277See the @code{enable probes} command above for a description of the 6278optional arguments accepted by this command. 6279@end table 6280 6281@vindex $_probe_arg@r{, convenience variable} 6282A probe may specify up to twelve arguments. These are available at the 6283point at which the probe is defined---that is, when the current PC is 6284at the probe's location. The arguments are available using the 6285convenience variables (@pxref{Convenience Vars}) 6286@code{$_probe_arg0}@dots{}@code{$_probe_arg11}. In @code{SystemTap} 6287probes each probe argument is an integer of the appropriate size; 6288types are not preserved. In @code{DTrace} probes types are preserved 6289provided that they are recognized as such by @value{GDBN}; otherwise 6290the value of the probe argument will be a long integer. The 6291convenience variable @code{$_probe_argc} holds the number of arguments 6292at the current probe point. 6293 6294These variables are always available, but attempts to access them at 6295any location other than a probe point will cause @value{GDBN} to give 6296an error message. 6297 6298 6299@c @ifclear BARETARGET 6300@node Error in Breakpoints 6301@subsection ``Cannot insert breakpoints'' 6302 6303If you request too many active hardware-assisted breakpoints and 6304watchpoints, you will see this error message: 6305 6306@c FIXME: the precise wording of this message may change; the relevant 6307@c source change is not committed yet (Sep 3, 1999). 6308@smallexample 6309Stopped; cannot insert breakpoints. 6310You may have requested too many hardware breakpoints and watchpoints. 6311@end smallexample 6312 6313@noindent 6314This message is printed when you attempt to resume the program, since 6315only then @value{GDBN} knows exactly how many hardware breakpoints and 6316watchpoints it needs to insert. 6317 6318When this message is printed, you need to disable or remove some of the 6319hardware-assisted breakpoints and watchpoints, and then continue. 6320 6321@node Breakpoint-related Warnings 6322@subsection ``Breakpoint address adjusted...'' 6323@cindex breakpoint address adjusted 6324 6325Some processor architectures place constraints on the addresses at 6326which breakpoints may be placed. For architectures thus constrained, 6327@value{GDBN} will attempt to adjust the breakpoint's address to comply 6328with the constraints dictated by the architecture. 6329 6330One example of such an architecture is the Fujitsu FR-V. The FR-V is 6331a VLIW architecture in which a number of RISC-like instructions may be 6332bundled together for parallel execution. The FR-V architecture 6333constrains the location of a breakpoint instruction within such a 6334bundle to the instruction with the lowest address. @value{GDBN} 6335honors this constraint by adjusting a breakpoint's address to the 6336first in the bundle. 6337 6338It is not uncommon for optimized code to have bundles which contain 6339instructions from different source statements, thus it may happen that 6340a breakpoint's address will be adjusted from one source statement to 6341another. Since this adjustment may significantly alter @value{GDBN}'s 6342breakpoint related behavior from what the user expects, a warning is 6343printed when the breakpoint is first set and also when the breakpoint 6344is hit. 6345 6346A warning like the one below is printed when setting a breakpoint 6347that's been subject to address adjustment: 6348 6349@smallexample 6350warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. 6351@end smallexample 6352 6353Such warnings are printed both for user settable and @value{GDBN}'s 6354internal breakpoints. If you see one of these warnings, you should 6355verify that a breakpoint set at the adjusted address will have the 6356desired affect. If not, the breakpoint in question may be removed and 6357other breakpoints may be set which will have the desired behavior. 6358E.g., it may be sufficient to place the breakpoint at a later 6359instruction. A conditional breakpoint may also be useful in some 6360cases to prevent the breakpoint from triggering too often. 6361 6362@value{GDBN} will also issue a warning when stopping at one of these 6363adjusted breakpoints: 6364 6365@smallexample 6366warning: Breakpoint 1 address previously adjusted from 0x00010414 6367to 0x00010410. 6368@end smallexample 6369 6370When this warning is encountered, it may be too late to take remedial 6371action except in cases where the breakpoint is hit earlier or more 6372frequently than expected. 6373 6374@node Continuing and Stepping 6375@section Continuing and Stepping 6376 6377@cindex stepping 6378@cindex continuing 6379@cindex resuming execution 6380@dfn{Continuing} means resuming program execution until your program 6381completes normally. In contrast, @dfn{stepping} means executing just 6382one more ``step'' of your program, where ``step'' may mean either one 6383line of source code, or one machine instruction (depending on what 6384particular command you use). Either when continuing or when stepping, 6385your program may stop even sooner, due to a breakpoint or a signal. (If 6386it stops due to a signal, you may want to use @code{handle}, or use 6387@samp{signal 0} to resume execution (@pxref{Signals, ,Signals}), 6388or you may step into the signal's handler (@pxref{stepping and signal 6389handlers}).) 6390 6391@table @code 6392@kindex continue 6393@kindex c @r{(@code{continue})} 6394@kindex fg @r{(resume foreground execution)} 6395@item continue @r{[}@var{ignore-count}@r{]} 6396@itemx c @r{[}@var{ignore-count}@r{]} 6397@itemx fg @r{[}@var{ignore-count}@r{]} 6398Resume program execution, at the address where your program last stopped; 6399any breakpoints set at that address are bypassed. The optional argument 6400@var{ignore-count} allows you to specify a further number of times to 6401ignore a breakpoint at this location; its effect is like that of 6402@code{ignore} (@pxref{Conditions, ,Break Conditions}). 6403 6404The argument @var{ignore-count} is meaningful only when your program 6405stopped due to a breakpoint. At other times, the argument to 6406@code{continue} is ignored. 6407 6408The synonyms @code{c} and @code{fg} (for @dfn{foreground}, as the 6409debugged program is deemed to be the foreground program) are provided 6410purely for convenience, and have exactly the same behavior as 6411@code{continue}. 6412@end table 6413 6414To resume execution at a different place, you can use @code{return} 6415(@pxref{Returning, ,Returning from a Function}) to go back to the 6416calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a 6417Different Address}) to go to an arbitrary location in your program. 6418 6419A typical technique for using stepping is to set a breakpoint 6420(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Catchpoints}) at the 6421beginning of the function or the section of your program where a problem 6422is believed to lie, run your program until it stops at that breakpoint, 6423and then step through the suspect area, examining the variables that are 6424interesting, until you see the problem happen. 6425 6426@table @code 6427@kindex step 6428@kindex s @r{(@code{step})} 6429@item step 6430Continue running your program until control reaches a different source 6431line, then stop it and return control to @value{GDBN}. This command is 6432abbreviated @code{s}. 6433 6434@quotation 6435@c "without debugging information" is imprecise; actually "without line 6436@c numbers in the debugging information". (gcc -g1 has debugging info but 6437@c not line numbers). But it seems complex to try to make that 6438@c distinction here. 6439@emph{Warning:} If you use the @code{step} command while control is 6440within a function that was compiled without debugging information, 6441execution proceeds until control reaches a function that does have 6442debugging information. Likewise, it will not step into a function which 6443is compiled without debugging information. To step through functions 6444without debugging information, use the @code{stepi} command, described 6445below. 6446@end quotation 6447 6448The @code{step} command only stops at the first instruction of a source 6449line. This prevents the multiple stops that could otherwise occur in 6450@code{switch} statements, @code{for} loops, etc. @code{step} continues 6451to stop if a function that has debugging information is called within 6452the line. In other words, @code{step} @emph{steps inside} any functions 6453called within the line. 6454 6455Also, the @code{step} command only enters a function if there is line 6456number information for the function. Otherwise it acts like the 6457@code{next} command. This avoids problems when using @code{cc -gl} 6458on @acronym{MIPS} machines. Previously, @code{step} entered subroutines if there 6459was any debugging information about the routine. 6460 6461@item step @var{count} 6462Continue running as in @code{step}, but do so @var{count} times. If a 6463breakpoint is reached, or a signal not related to stepping occurs before 6464@var{count} steps, stepping stops right away. 6465 6466@kindex next 6467@kindex n @r{(@code{next})} 6468@item next @r{[}@var{count}@r{]} 6469Continue to the next source line in the current (innermost) stack frame. 6470This is similar to @code{step}, but function calls that appear within 6471the line of code are executed without stopping. Execution stops when 6472control reaches a different line of code at the original stack level 6473that was executing when you gave the @code{next} command. This command 6474is abbreviated @code{n}. 6475 6476An argument @var{count} is a repeat count, as for @code{step}. 6477 6478 6479@c FIX ME!! Do we delete this, or is there a way it fits in with 6480@c the following paragraph? --- Vctoria 6481@c 6482@c @code{next} within a function that lacks debugging information acts like 6483@c @code{step}, but any function calls appearing within the code of the 6484@c function are executed without stopping. 6485 6486The @code{next} command only stops at the first instruction of a 6487source line. This prevents multiple stops that could otherwise occur in 6488@code{switch} statements, @code{for} loops, etc. 6489 6490@kindex set step-mode 6491@item set step-mode 6492@cindex functions without line info, and stepping 6493@cindex stepping into functions with no line info 6494@itemx set step-mode on 6495The @code{set step-mode on} command causes the @code{step} command to 6496stop at the first instruction of a function which contains no debug line 6497information rather than stepping over it. 6498 6499This is useful in cases where you may be interested in inspecting the 6500machine instructions of a function which has no symbolic info and do not 6501want @value{GDBN} to automatically skip over this function. 6502 6503@item set step-mode off 6504Causes the @code{step} command to step over any functions which contains no 6505debug information. This is the default. 6506 6507@item show step-mode 6508Show whether @value{GDBN} will stop in or step over functions without 6509source line debug information. 6510 6511@kindex finish 6512@kindex fin @r{(@code{finish})} 6513@item finish 6514Continue running until just after function in the selected stack frame 6515returns. Print the returned value (if any). This command can be 6516abbreviated as @code{fin}. 6517 6518Contrast this with the @code{return} command (@pxref{Returning, 6519,Returning from a Function}). 6520 6521@kindex set print finish 6522@kindex show print finish 6523@item set print finish @r{[}on|off@r{]} 6524@itemx show print finish 6525By default the @code{finish} command will show the value that is 6526returned by the function. This can be disabled using @code{set print 6527finish off}. When disabled, the value is still entered into the value 6528history (@pxref{Value History}), but not displayed. 6529 6530@kindex until 6531@kindex u @r{(@code{until})} 6532@cindex run until specified location 6533@item until 6534@itemx u 6535Continue running until a source line past the current line, in the 6536current stack frame, is reached. This command is used to avoid single 6537stepping through a loop more than once. It is like the @code{next} 6538command, except that when @code{until} encounters a jump, it 6539automatically continues execution until the program counter is greater 6540than the address of the jump. 6541 6542This means that when you reach the end of a loop after single stepping 6543though it, @code{until} makes your program continue execution until it 6544exits the loop. In contrast, a @code{next} command at the end of a loop 6545simply steps back to the beginning of the loop, which forces you to step 6546through the next iteration. 6547 6548@code{until} always stops your program if it attempts to exit the current 6549stack frame. 6550 6551@code{until} may produce somewhat counterintuitive results if the order 6552of machine code does not match the order of the source lines. For 6553example, in the following excerpt from a debugging session, the @code{f} 6554(@code{frame}) command shows that execution is stopped at line 6555@code{206}; yet when we use @code{until}, we get to line @code{195}: 6556 6557@smallexample 6558(@value{GDBP}) f 6559#0 main (argc=4, argv=0xf7fffae8) at m4.c:206 6560206 expand_input(); 6561(@value{GDBP}) until 6562195 for ( ; argc > 0; NEXTARG) @{ 6563@end smallexample 6564 6565This happened because, for execution efficiency, the compiler had 6566generated code for the loop closure test at the end, rather than the 6567start, of the loop---even though the test in a C @code{for}-loop is 6568written before the body of the loop. The @code{until} command appeared 6569to step back to the beginning of the loop when it advanced to this 6570expression; however, it has not really gone to an earlier 6571statement---not in terms of the actual machine code. 6572 6573@code{until} with no argument works by means of single 6574instruction stepping, and hence is slower than @code{until} with an 6575argument. 6576 6577@item until @var{locspec} 6578@itemx u @var{locspec} 6579Continue running your program until either it reaches a code location 6580that results from resolving @var{locspec}, or the current stack frame 6581returns. @var{locspec} is any of the forms described in @ref{Location 6582Specifications}. 6583This form of the command uses temporary breakpoints, and 6584hence is quicker than @code{until} without an argument. The specified 6585location is actually reached only if it is in the current frame. This 6586implies that @code{until} can be used to skip over recursive function 6587invocations. For instance in the code below, if the current location is 6588line @code{96}, issuing @code{until 99} will execute the program up to 6589line @code{99} in the same invocation of factorial, i.e., after the inner 6590invocations have returned. 6591 6592@smallexample 659394 int factorial (int value) 659495 @{ 659596 if (value > 1) @{ 659697 value *= factorial (value - 1); 659798 @} 659899 return (value); 6599100 @} 6600@end smallexample 6601 6602 6603@kindex advance @var{locspec} 6604@item advance @var{locspec} 6605Continue running your program until either it reaches a code location 6606that results from resolving @var{locspec}, or the current stack frame 6607returns. @var{locspec} is any of the forms described in @ref{Location 6608Specifications}. This command is similar to @code{until}, but 6609@code{advance} will not skip over recursive function calls, and the 6610target code location doesn't have to be in the same frame as the 6611current one. 6612 6613 6614@kindex stepi 6615@kindex si @r{(@code{stepi})} 6616@item stepi 6617@itemx stepi @var{arg} 6618@itemx si 6619Execute one machine instruction, then stop and return to the debugger. 6620 6621It is often useful to do @samp{display/i $pc} when stepping by machine 6622instructions. This makes @value{GDBN} automatically display the next 6623instruction to be executed, each time your program stops. @xref{Auto 6624Display,, Automatic Display}. 6625 6626An argument is a repeat count, as in @code{step}. 6627 6628@need 750 6629@kindex nexti 6630@kindex ni @r{(@code{nexti})} 6631@item nexti 6632@itemx nexti @var{arg} 6633@itemx ni 6634Execute one machine instruction, but if it is a function call, 6635proceed until the function returns. 6636 6637An argument is a repeat count, as in @code{next}. 6638 6639@end table 6640 6641@anchor{range stepping} 6642@cindex range stepping 6643@cindex target-assisted range stepping 6644By default, and if available, @value{GDBN} makes use of 6645target-assisted @dfn{range stepping}. In other words, whenever you 6646use a stepping command (e.g., @code{step}, @code{next}), @value{GDBN} 6647tells the target to step the corresponding range of instruction 6648addresses instead of issuing multiple single-steps. This speeds up 6649line stepping, particularly for remote targets. Ideally, there should 6650be no reason you would want to turn range stepping off. However, it's 6651possible that a bug in the debug info, a bug in the remote stub (for 6652remote targets), or even a bug in @value{GDBN} could make line 6653stepping behave incorrectly when target-assisted range stepping is 6654enabled. You can use the following command to turn off range stepping 6655if necessary: 6656 6657@table @code 6658@kindex set range-stepping 6659@kindex show range-stepping 6660@item set range-stepping 6661@itemx show range-stepping 6662Control whether range stepping is enabled. 6663 6664If @code{on}, and the target supports it, @value{GDBN} tells the 6665target to step a range of addresses itself, instead of issuing 6666multiple single-steps. If @code{off}, @value{GDBN} always issues 6667single-steps, even if range stepping is supported by the target. The 6668default is @code{on}. 6669 6670@end table 6671 6672@node Skipping Over Functions and Files 6673@section Skipping Over Functions and Files 6674@cindex skipping over functions and files 6675 6676The program you are debugging may contain some functions which are 6677uninteresting to debug. The @code{skip} command lets you tell @value{GDBN} to 6678skip a function, all functions in a file or a particular function in 6679a particular file when stepping. 6680 6681For example, consider the following C function: 6682 6683@smallexample 6684101 int func() 6685102 @{ 6686103 foo(boring()); 6687104 bar(boring()); 6688105 @} 6689@end smallexample 6690 6691@noindent 6692Suppose you wish to step into the functions @code{foo} and @code{bar}, but you 6693are not interested in stepping through @code{boring}. If you run @code{step} 6694at line 103, you'll enter @code{boring()}, but if you run @code{next}, you'll 6695step over both @code{foo} and @code{boring}! 6696 6697One solution is to @code{step} into @code{boring} and use the @code{finish} 6698command to immediately exit it. But this can become tedious if @code{boring} 6699is called from many places. 6700 6701A more flexible solution is to execute @kbd{skip boring}. This instructs 6702@value{GDBN} never to step into @code{boring}. Now when you execute 6703@code{step} at line 103, you'll step over @code{boring} and directly into 6704@code{foo}. 6705 6706Functions may be skipped by providing either a function name, linespec 6707(@pxref{Location Specifications}), regular expression that matches the function's 6708name, file name or a @code{glob}-style pattern that matches the file name. 6709 6710On Posix systems the form of the regular expression is 6711``Extended Regular Expressions''. See for example @samp{man 7 regex} 6712on @sc{gnu}/Linux systems. On non-Posix systems the form of the regular 6713expression is whatever is provided by the @code{regcomp} function of 6714the underlying system. 6715See for example @samp{man 7 glob} on @sc{gnu}/Linux systems for a 6716description of @code{glob}-style patterns. 6717 6718@table @code 6719@kindex skip 6720@item skip @r{[}@var{options}@r{]} 6721The basic form of the @code{skip} command takes zero or more options 6722that specify what to skip. 6723The @var{options} argument is any useful combination of the following: 6724 6725@table @code 6726@item -file @var{file} 6727@itemx -fi @var{file} 6728Functions in @var{file} will be skipped over when stepping. 6729 6730@item -gfile @var{file-glob-pattern} 6731@itemx -gfi @var{file-glob-pattern} 6732@cindex skipping over files via glob-style patterns 6733Functions in files matching @var{file-glob-pattern} will be skipped 6734over when stepping. 6735 6736@smallexample 6737(@value{GDBP}) skip -gfi utils/*.c 6738@end smallexample 6739 6740@item -function @var{linespec} 6741@itemx -fu @var{linespec} 6742Functions named by @var{linespec} or the function containing the line 6743named by @var{linespec} will be skipped over when stepping. 6744@xref{Location Specifications}. 6745 6746@item -rfunction @var{regexp} 6747@itemx -rfu @var{regexp} 6748@cindex skipping over functions via regular expressions 6749Functions whose name matches @var{regexp} will be skipped over when stepping. 6750 6751This form is useful for complex function names. 6752For example, there is generally no need to step into C@t{++} @code{std::string} 6753constructors or destructors. Plus with C@t{++} templates it can be hard to 6754write out the full name of the function, and often it doesn't matter what 6755the template arguments are. Specifying the function to be skipped as a 6756regular expression makes this easier. 6757 6758@smallexample 6759(@value{GDBP}) skip -rfu ^std::(allocator|basic_string)<.*>::~?\1 *\( 6760@end smallexample 6761 6762If you want to skip every templated C@t{++} constructor and destructor 6763in the @code{std} namespace you can do: 6764 6765@smallexample 6766(@value{GDBP}) skip -rfu ^std::([a-zA-z0-9_]+)<.*>::~?\1 *\( 6767@end smallexample 6768@end table 6769 6770If no options are specified, the function you're currently debugging 6771will be skipped. 6772 6773@kindex skip function 6774@item skip function @r{[}@var{linespec}@r{]} 6775After running this command, the function named by @var{linespec} or the 6776function containing the line named by @var{linespec} will be skipped over when 6777stepping. @xref{Location Specifications}. 6778 6779If you do not specify @var{linespec}, the function you're currently debugging 6780will be skipped. 6781 6782(If you have a function called @code{file} that you want to skip, use 6783@kbd{skip function file}.) 6784 6785@kindex skip file 6786@item skip file @r{[}@var{filename}@r{]} 6787After running this command, any function whose source lives in @var{filename} 6788will be skipped over when stepping. 6789 6790@smallexample 6791(@value{GDBP}) skip file boring.c 6792File boring.c will be skipped when stepping. 6793@end smallexample 6794 6795If you do not specify @var{filename}, functions whose source lives in the file 6796you're currently debugging will be skipped. 6797@end table 6798 6799Skips can be listed, deleted, disabled, and enabled, much like breakpoints. 6800These are the commands for managing your list of skips: 6801 6802@table @code 6803@kindex info skip 6804@item info skip @r{[}@var{range}@r{]} 6805Print details about the specified skip(s). If @var{range} is not specified, 6806print a table with details about all functions and files marked for skipping. 6807@code{info skip} prints the following information about each skip: 6808 6809@table @emph 6810@item Identifier 6811A number identifying this skip. 6812@item Enabled or Disabled 6813Enabled skips are marked with @samp{y}. 6814Disabled skips are marked with @samp{n}. 6815@item Glob 6816If the file name is a @samp{glob} pattern this is @samp{y}. 6817Otherwise it is @samp{n}. 6818@item File 6819The name or @samp{glob} pattern of the file to be skipped. 6820If no file is specified this is @samp{<none>}. 6821@item RE 6822If the function name is a @samp{regular expression} this is @samp{y}. 6823Otherwise it is @samp{n}. 6824@item Function 6825The name or regular expression of the function to skip. 6826If no function is specified this is @samp{<none>}. 6827@end table 6828 6829@kindex skip delete 6830@item skip delete @r{[}@var{range}@r{]} 6831Delete the specified skip(s). If @var{range} is not specified, delete all 6832skips. 6833 6834@kindex skip enable 6835@item skip enable @r{[}@var{range}@r{]} 6836Enable the specified skip(s). If @var{range} is not specified, enable all 6837skips. 6838 6839@kindex skip disable 6840@item skip disable @r{[}@var{range}@r{]} 6841Disable the specified skip(s). If @var{range} is not specified, disable all 6842skips. 6843 6844@kindex set debug skip 6845@item set debug skip @r{[}on|off@r{]} 6846Set whether to print the debug output about skipping files and functions. 6847 6848@kindex show debug skip 6849@item show debug skip 6850Show whether the debug output about skipping files and functions is printed. 6851 6852@end table 6853 6854@node Signals 6855@section Signals 6856@cindex signals 6857 6858A signal is an asynchronous event that can happen in a program. The 6859operating system defines the possible kinds of signals, and gives each 6860kind a name and a number. For example, in Unix @code{SIGINT} is the 6861signal a program gets when you type an interrupt character (often @kbd{Ctrl-c}); 6862@code{SIGSEGV} is the signal a program gets from referencing a place in 6863memory far away from all the areas in use; @code{SIGALRM} occurs when 6864the alarm clock timer goes off (which happens only if your program has 6865requested an alarm). 6866 6867@cindex fatal signals 6868Some signals, including @code{SIGALRM}, are a normal part of the 6869functioning of your program. Others, such as @code{SIGSEGV}, indicate 6870errors; these signals are @dfn{fatal} (they kill your program immediately) if the 6871program has not specified in advance some other way to handle the signal. 6872@code{SIGINT} does not indicate an error in your program, but it is normally 6873fatal so it can carry out the purpose of the interrupt: to kill the program. 6874 6875@value{GDBN} has the ability to detect any occurrence of a signal in your 6876program. You can tell @value{GDBN} in advance what to do for each kind of 6877signal. 6878 6879@cindex handling signals 6880Normally, @value{GDBN} is set up to let the non-erroneous signals like 6881@code{SIGALRM} be silently passed to your program 6882(so as not to interfere with their role in the program's functioning) 6883but to stop your program immediately whenever an error signal happens. 6884You can change these settings with the @code{handle} command. 6885 6886@table @code 6887@kindex info signals 6888@kindex info handle 6889@item info signals 6890@itemx info handle 6891Print a table of all the kinds of signals and how @value{GDBN} has been told to 6892handle each one. You can use this to see the signal numbers of all 6893the defined types of signals. 6894 6895@item info signals @var{sig} 6896Similar, but print information only about the specified signal number. 6897 6898@code{info handle} is an alias for @code{info signals}. 6899 6900@item catch signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]} 6901Set a catchpoint for the indicated signals. @xref{Set Catchpoints}, 6902for details about this command. 6903 6904@kindex handle 6905@item handle @var{signal} @r{[} @var{signal} @dots{} @r{]} @r{[}@var{keywords}@dots{}@r{]} 6906Change the way @value{GDBN} handles each @var{signal}. Each 6907@var{signal} can be the number of a signal or its name (with or 6908without the @samp{SIG} at the beginning); a list of signal numbers of 6909the form @samp{@var{low}-@var{high}}; or the word @samp{all}, meaning 6910all the known signals, except @code{SIGINT} and @code{SIGTRAP}, which 6911are used by @value{GDBN}. Optional argument @var{keywords}, described 6912below, say what changes to make to all of the specified signals. 6913@end table 6914 6915@c @group 6916The keywords allowed by the @code{handle} command can be abbreviated. 6917Their full names are: 6918 6919@table @code 6920@item nostop 6921@value{GDBN} should not stop your program when this signal happens. It may 6922still print a message telling you that the signal has come in. 6923 6924@item stop 6925@value{GDBN} should stop your program when this signal happens. This implies 6926the @code{print} keyword as well. 6927 6928@item print 6929@value{GDBN} should print a message when this signal happens. 6930 6931@item noprint 6932@value{GDBN} should not mention the occurrence of the signal at all. This 6933implies the @code{nostop} keyword as well. 6934 6935@item pass 6936@itemx noignore 6937@value{GDBN} should allow your program to see this signal; your program 6938can handle the signal, or else it may terminate if the signal is fatal 6939and not handled. @code{pass} and @code{noignore} are synonyms. 6940 6941@item nopass 6942@itemx ignore 6943@value{GDBN} should not allow your program to see this signal. 6944@code{nopass} and @code{ignore} are synonyms. 6945@end table 6946@c @end group 6947 6948When a signal stops your program, the signal is not visible to the 6949program until you 6950continue. Your program sees the signal then, if @code{pass} is in 6951effect for the signal in question @emph{at that time}. In other words, 6952after @value{GDBN} reports a signal, you can use the @code{handle} 6953command with @code{pass} or @code{nopass} to control whether your 6954program sees that signal when you continue. 6955 6956The default is set to @code{nostop}, @code{noprint}, @code{pass} for 6957non-erroneous signals such as @code{SIGALRM}, @code{SIGWINCH} and 6958@code{SIGCHLD}, and to @code{stop}, @code{print}, @code{pass} for the 6959erroneous signals. 6960 6961You can also use the @code{signal} command to prevent your program from 6962seeing a signal, or cause it to see a signal it normally would not see, 6963or to give it any signal at any time. For example, if your program stopped 6964due to some sort of memory reference error, you might store correct 6965values into the erroneous variables and continue, hoping to see more 6966execution; but your program would probably terminate immediately as 6967a result of the fatal signal once it saw the signal. To prevent this, 6968you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your 6969Program a Signal}. 6970 6971@cindex stepping and signal handlers 6972@anchor{stepping and signal handlers} 6973 6974@value{GDBN} optimizes for stepping the mainline code. If a signal 6975that has @code{handle nostop} and @code{handle pass} set arrives while 6976a stepping command (e.g., @code{stepi}, @code{step}, @code{next}) is 6977in progress, @value{GDBN} lets the signal handler run and then resumes 6978stepping the mainline code once the signal handler returns. In other 6979words, @value{GDBN} steps over the signal handler. This prevents 6980signals that you've specified as not interesting (with @code{handle 6981nostop}) from changing the focus of debugging unexpectedly. Note that 6982the signal handler itself may still hit a breakpoint, stop for another 6983signal that has @code{handle stop} in effect, or for any other event 6984that normally results in stopping the stepping command sooner. Also 6985note that @value{GDBN} still informs you that the program received a 6986signal if @code{handle print} is set. 6987 6988@anchor{stepping into signal handlers} 6989 6990If you set @code{handle pass} for a signal, and your program sets up a 6991handler for it, then issuing a stepping command, such as @code{step} 6992or @code{stepi}, when your program is stopped due to the signal will 6993step @emph{into} the signal handler (if the target supports that). 6994 6995Likewise, if you use the @code{queue-signal} command to queue a signal 6996to be delivered to the current thread when execution of the thread 6997resumes (@pxref{Signaling, ,Giving your Program a Signal}), then a 6998stepping command will step into the signal handler. 6999 7000Here's an example, using @code{stepi} to step to the first instruction 7001of @code{SIGUSR1}'s handler: 7002 7003@smallexample 7004(@value{GDBP}) handle SIGUSR1 7005Signal Stop Print Pass to program Description 7006SIGUSR1 Yes Yes Yes User defined signal 1 7007(@value{GDBP}) c 7008Continuing. 7009 7010Program received signal SIGUSR1, User defined signal 1. 7011main () sigusr1.c:28 701228 p = 0; 7013(@value{GDBP}) si 7014sigusr1_handler () at sigusr1.c:9 70159 @{ 7016@end smallexample 7017 7018The same, but using @code{queue-signal} instead of waiting for the 7019program to receive the signal first: 7020 7021@smallexample 7022(@value{GDBP}) n 702328 p = 0; 7024(@value{GDBP}) queue-signal SIGUSR1 7025(@value{GDBP}) si 7026sigusr1_handler () at sigusr1.c:9 70279 @{ 7028(@value{GDBP}) 7029@end smallexample 7030 7031@cindex extra signal information 7032@anchor{extra signal information} 7033 7034On some targets, @value{GDBN} can inspect extra signal information 7035associated with the intercepted signal, before it is actually 7036delivered to the program being debugged. This information is exported 7037by the convenience variable @code{$_siginfo}, and consists of data 7038that is passed by the kernel to the signal handler at the time of the 7039receipt of a signal. The data type of the information itself is 7040target dependent. You can see the data type using the @code{ptype 7041$_siginfo} command. On Unix systems, it typically corresponds to the 7042standard @code{siginfo_t} type, as defined in the @file{signal.h} 7043system header. 7044 7045Here's an example, on a @sc{gnu}/Linux system, printing the stray 7046referenced address that raised a segmentation fault. 7047 7048@smallexample 7049@group 7050(@value{GDBP}) continue 7051Program received signal SIGSEGV, Segmentation fault. 70520x0000000000400766 in main () 705369 *(int *)p = 0; 7054(@value{GDBP}) ptype $_siginfo 7055type = struct @{ 7056 int si_signo; 7057 int si_errno; 7058 int si_code; 7059 union @{ 7060 int _pad[28]; 7061 struct @{...@} _kill; 7062 struct @{...@} _timer; 7063 struct @{...@} _rt; 7064 struct @{...@} _sigchld; 7065 struct @{...@} _sigfault; 7066 struct @{...@} _sigpoll; 7067 @} _sifields; 7068@} 7069(@value{GDBP}) ptype $_siginfo._sifields._sigfault 7070type = struct @{ 7071 void *si_addr; 7072@} 7073(@value{GDBP}) p $_siginfo._sifields._sigfault.si_addr 7074$1 = (void *) 0x7ffff7ff7000 7075@end group 7076@end smallexample 7077 7078Depending on target support, @code{$_siginfo} may also be writable. 7079 7080@cindex Intel MPX boundary violations 7081@cindex boundary violations, Intel MPX 7082On some targets, a @code{SIGSEGV} can be caused by a boundary 7083violation, i.e., accessing an address outside of the allowed range. 7084In those cases @value{GDBN} may displays additional information, 7085depending on how @value{GDBN} has been told to handle the signal. 7086With @code{handle stop SIGSEGV}, @value{GDBN} displays the violation 7087kind: "Upper" or "Lower", the memory address accessed and the 7088bounds, while with @code{handle nostop SIGSEGV} no additional 7089information is displayed. 7090 7091The usual output of a segfault is: 7092@smallexample 7093Program received signal SIGSEGV, Segmentation fault 70940x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68 709568 value = *(p + len); 7096@end smallexample 7097 7098While a bound violation is presented as: 7099@smallexample 7100Program received signal SIGSEGV, Segmentation fault 7101Upper bound violation while accessing address 0x7fffffffc3b3 7102Bounds: [lower = 0x7fffffffc390, upper = 0x7fffffffc3a3] 71030x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68 710468 value = *(p + len); 7105@end smallexample 7106 7107@node Thread Stops 7108@section Stopping and Starting Multi-thread Programs 7109 7110@cindex stopped threads 7111@cindex threads, stopped 7112 7113@cindex continuing threads 7114@cindex threads, continuing 7115 7116@value{GDBN} supports debugging programs with multiple threads 7117(@pxref{Threads,, Debugging Programs with Multiple Threads}). There 7118are two modes of controlling execution of your program within the 7119debugger. In the default mode, referred to as @dfn{all-stop mode}, 7120when any thread in your program stops (for example, at a breakpoint 7121or while being stepped), all other threads in the program are also stopped by 7122@value{GDBN}. On some targets, @value{GDBN} also supports 7123@dfn{non-stop mode}, in which other threads can continue to run freely while 7124you examine the stopped thread in the debugger. 7125 7126@menu 7127* All-Stop Mode:: All threads stop when GDB takes control 7128* Non-Stop Mode:: Other threads continue to execute 7129* Background Execution:: Running your program asynchronously 7130* Thread-Specific Breakpoints:: Controlling breakpoints 7131* Interrupted System Calls:: GDB may interfere with system calls 7132* Observer Mode:: GDB does not alter program behavior 7133@end menu 7134 7135@node All-Stop Mode 7136@subsection All-Stop Mode 7137 7138@cindex all-stop mode 7139 7140In all-stop mode, whenever your program stops under @value{GDBN} for any reason, 7141@emph{all} threads of execution stop, not just the current thread. This 7142allows you to examine the overall state of the program, including 7143switching between threads, without worrying that things may change 7144underfoot. 7145 7146Conversely, whenever you restart the program, @emph{all} threads start 7147executing. @emph{This is true even when single-stepping} with commands 7148like @code{step} or @code{next}. 7149 7150In particular, @value{GDBN} cannot single-step all threads in lockstep. 7151Since thread scheduling is up to your debugging target's operating 7152system (not controlled by @value{GDBN}), other threads may 7153execute more than one statement while the current thread completes a 7154single step. Moreover, in general other threads stop in the middle of a 7155statement, rather than at a clean statement boundary, when the program 7156stops. 7157 7158You might even find your program stopped in another thread after 7159continuing or even single-stepping. This happens whenever some other 7160thread runs into a breakpoint, a signal, or an exception before the 7161first thread completes whatever you requested. 7162 7163@cindex automatic thread selection 7164@cindex switching threads automatically 7165@cindex threads, automatic switching 7166Whenever @value{GDBN} stops your program, due to a breakpoint or a 7167signal, it automatically selects the thread where that breakpoint or 7168signal happened. @value{GDBN} alerts you to the context switch with a 7169message such as @samp{[Switching to Thread @var{n}]} to identify the 7170thread. 7171 7172@anchor{set scheduler-locking} 7173 7174On some OSes, you can modify @value{GDBN}'s default behavior by 7175locking the OS scheduler to allow only a single thread to run. 7176 7177@table @code 7178@item set scheduler-locking @var{mode} 7179@cindex scheduler-locking 7180@cindex scheduler locking mode 7181@cindex lock scheduler 7182Set the scheduler locking mode. It applies to normal execution, 7183record mode, and replay mode. @var{mode} can be one of 7184the following: 7185 7186@table @code 7187@item off 7188There is no locking and any thread may run at any time. 7189 7190@item on 7191Only the current thread may run when the inferior is resumed. New 7192threads created by the resumed thread are held stopped at their entry 7193point, before they execute any instruction. 7194 7195@item step 7196Behaves like @code{on} when stepping, and @code{off} otherwise. 7197Threads other than the current never get a chance to run when you 7198step, and they are completely free to run when you use commands like 7199@samp{continue}, @samp{until}, or @samp{finish}. 7200 7201This mode optimizes for single-stepping; it prevents other threads 7202from preempting the current thread while you are stepping, so that the 7203focus of debugging does not change unexpectedly. However, unless 7204another thread hits a breakpoint during its timeslice, @value{GDBN} 7205does not change the current thread away from the thread that you are 7206debugging. 7207 7208@item replay 7209Behaves like @code{on} in replay mode, and @code{off} in either record 7210mode or during normal execution. This is the default mode. 7211@end table 7212 7213@item show scheduler-locking 7214Display the current scheduler locking mode. 7215@end table 7216 7217@cindex resume threads of multiple processes simultaneously 7218By default, when you issue one of the execution commands such as 7219@code{continue}, @code{next} or @code{step}, @value{GDBN} allows only 7220threads of the current inferior to run. For example, if @value{GDBN} 7221is attached to two inferiors, each with two threads, the 7222@code{continue} command resumes only the two threads of the current 7223inferior. This is useful, for example, when you debug a program that 7224forks and you want to hold the parent stopped (so that, for instance, 7225it doesn't run to exit), while you debug the child. In other 7226situations, you may not be interested in inspecting the current state 7227of any of the processes @value{GDBN} is attached to, and you may want 7228to resume them all until some breakpoint is hit. In the latter case, 7229you can instruct @value{GDBN} to allow all threads of all the 7230inferiors to run with the @w{@code{set schedule-multiple}} command. 7231 7232@table @code 7233@kindex set schedule-multiple 7234@item set schedule-multiple 7235Set the mode for allowing threads of multiple processes to be resumed 7236when an execution command is issued. When @code{on}, all threads of 7237all processes are allowed to run. When @code{off}, only the threads 7238of the current process are resumed. The default is @code{off}. The 7239@code{scheduler-locking} mode takes precedence when set to @code{on}, 7240or while you are stepping and set to @code{step}. 7241 7242@item show schedule-multiple 7243Display the current mode for resuming the execution of threads of 7244multiple processes. 7245@end table 7246 7247@node Non-Stop Mode 7248@subsection Non-Stop Mode 7249 7250@cindex non-stop mode 7251 7252@c This section is really only a place-holder, and needs to be expanded 7253@c with more details. 7254 7255For some multi-threaded targets, @value{GDBN} supports an optional 7256mode of operation in which you can examine stopped program threads in 7257the debugger while other threads continue to execute freely. This 7258minimizes intrusion when debugging live systems, such as programs 7259where some threads have real-time constraints or must continue to 7260respond to external events. This is referred to as @dfn{non-stop} mode. 7261 7262In non-stop mode, when a thread stops to report a debugging event, 7263@emph{only} that thread is stopped; @value{GDBN} does not stop other 7264threads as well, in contrast to the all-stop mode behavior. Additionally, 7265execution commands such as @code{continue} and @code{step} apply by default 7266only to the current thread in non-stop mode, rather than all threads as 7267in all-stop mode. This allows you to control threads explicitly in 7268ways that are not possible in all-stop mode --- for example, stepping 7269one thread while allowing others to run freely, stepping 7270one thread while holding all others stopped, or stepping several threads 7271independently and simultaneously. 7272 7273To enter non-stop mode, use this sequence of commands before you run 7274or attach to your program: 7275 7276@smallexample 7277# If using the CLI, pagination breaks non-stop. 7278set pagination off 7279 7280# Finally, turn it on! 7281set non-stop on 7282@end smallexample 7283 7284You can use these commands to manipulate the non-stop mode setting: 7285 7286@table @code 7287@kindex set non-stop 7288@item set non-stop on 7289Enable selection of non-stop mode. 7290@item set non-stop off 7291Disable selection of non-stop mode. 7292@kindex show non-stop 7293@item show non-stop 7294Show the current non-stop enablement setting. 7295@end table 7296 7297Note these commands only reflect whether non-stop mode is enabled, 7298not whether the currently-executing program is being run in non-stop mode. 7299In particular, the @code{set non-stop} preference is only consulted when 7300@value{GDBN} starts or connects to the target program, and it is generally 7301not possible to switch modes once debugging has started. Furthermore, 7302since not all targets support non-stop mode, even when you have enabled 7303non-stop mode, @value{GDBN} may still fall back to all-stop operation by 7304default. 7305 7306In non-stop mode, all execution commands apply only to the current thread 7307by default. That is, @code{continue} only continues one thread. 7308To continue all threads, issue @code{continue -a} or @code{c -a}. 7309 7310You can use @value{GDBN}'s background execution commands 7311(@pxref{Background Execution}) to run some threads in the background 7312while you continue to examine or step others from @value{GDBN}. 7313The MI execution commands (@pxref{GDB/MI Program Execution}) are 7314always executed asynchronously in non-stop mode. 7315 7316Suspending execution is done with the @code{interrupt} command when 7317running in the background, or @kbd{Ctrl-c} during foreground execution. 7318In all-stop mode, this stops the whole process; 7319but in non-stop mode the interrupt applies only to the current thread. 7320To stop the whole program, use @code{interrupt -a}. 7321 7322Other execution commands do not currently support the @code{-a} option. 7323 7324In non-stop mode, when a thread stops, @value{GDBN} doesn't automatically make 7325that thread current, as it does in all-stop mode. This is because the 7326thread stop notifications are asynchronous with respect to @value{GDBN}'s 7327command interpreter, and it would be confusing if @value{GDBN} unexpectedly 7328changed to a different thread just as you entered a command to operate on the 7329previously current thread. 7330 7331@node Background Execution 7332@subsection Background Execution 7333 7334@cindex foreground execution 7335@cindex background execution 7336@cindex asynchronous execution 7337@cindex execution, foreground, background and asynchronous 7338 7339@value{GDBN}'s execution commands have two variants: the normal 7340foreground (synchronous) behavior, and a background 7341(asynchronous) behavior. In foreground execution, @value{GDBN} waits for 7342the program to report that some thread has stopped before prompting for 7343another command. In background execution, @value{GDBN} immediately gives 7344a command prompt so that you can issue other commands while your program runs. 7345 7346If the target doesn't support async mode, @value{GDBN} issues an error 7347message if you attempt to use the background execution commands. 7348 7349@cindex @code{&}, background execution of commands 7350To specify background execution, add a @code{&} to the command. For example, 7351the background form of the @code{continue} command is @code{continue&}, or 7352just @code{c&}. The execution commands that accept background execution 7353are: 7354 7355@table @code 7356@kindex run& 7357@item run 7358@xref{Starting, , Starting your Program}. 7359 7360@item attach 7361@kindex attach& 7362@xref{Attach, , Debugging an Already-running Process}. 7363 7364@item step 7365@kindex step& 7366@xref{Continuing and Stepping, step}. 7367 7368@item stepi 7369@kindex stepi& 7370@xref{Continuing and Stepping, stepi}. 7371 7372@item next 7373@kindex next& 7374@xref{Continuing and Stepping, next}. 7375 7376@item nexti 7377@kindex nexti& 7378@xref{Continuing and Stepping, nexti}. 7379 7380@item continue 7381@kindex continue& 7382@xref{Continuing and Stepping, continue}. 7383 7384@item finish 7385@kindex finish& 7386@xref{Continuing and Stepping, finish}. 7387 7388@item until 7389@kindex until& 7390@xref{Continuing and Stepping, until}. 7391 7392@end table 7393 7394Background execution is especially useful in conjunction with non-stop 7395mode for debugging programs with multiple threads; see @ref{Non-Stop Mode}. 7396However, you can also use these commands in the normal all-stop mode with 7397the restriction that you cannot issue another execution command until the 7398previous one finishes. Examples of commands that are valid in all-stop 7399mode while the program is running include @code{help} and @code{info break}. 7400 7401You can interrupt your program while it is running in the background by 7402using the @code{interrupt} command. 7403 7404@table @code 7405@kindex interrupt 7406@item interrupt 7407@itemx interrupt -a 7408 7409Suspend execution of the running program. In all-stop mode, 7410@code{interrupt} stops the whole process, but in non-stop mode, it stops 7411only the current thread. To stop the whole program in non-stop mode, 7412use @code{interrupt -a}. 7413@end table 7414 7415@node Thread-Specific Breakpoints 7416@subsection Thread-Specific Breakpoints 7417 7418When your program has multiple threads (@pxref{Threads,, Debugging 7419Programs with Multiple Threads}), you can choose whether to set 7420breakpoints on all threads, or on a particular thread. 7421 7422@table @code 7423@cindex breakpoints and threads 7424@cindex thread breakpoints 7425@kindex break @dots{} thread @var{thread-id} 7426@item break @var{locspec} thread @var{thread-id} 7427@itemx break @var{locspec} thread @var{thread-id} if @dots{} 7428@var{locspec} specifies a code location or locations in your program. 7429@xref{Location Specifications}, for details. 7430 7431Use the qualifier @samp{thread @var{thread-id}} with a breakpoint command 7432to specify that you only want @value{GDBN} to stop the program when a 7433particular thread reaches this breakpoint. The @var{thread-id} specifier 7434is one of the thread identifiers assigned by @value{GDBN}, shown 7435in the first column of the @samp{info threads} display. 7436 7437If you do not specify @samp{thread @var{thread-id}} when you set a 7438breakpoint, the breakpoint applies to @emph{all} threads of your 7439program. 7440 7441You can use the @code{thread} qualifier on conditional breakpoints as 7442well; in this case, place @samp{thread @var{thread-id}} before or 7443after the breakpoint condition, like this: 7444 7445@smallexample 7446(@value{GDBP}) break frik.c:13 thread 28 if bartab > lim 7447@end smallexample 7448 7449@end table 7450 7451Thread-specific breakpoints are automatically deleted when 7452@value{GDBN} detects the corresponding thread is no longer in the 7453thread list. For example: 7454 7455@smallexample 7456(@value{GDBP}) c 7457Thread-specific breakpoint 3 deleted - thread 28 no longer in the thread list. 7458@end smallexample 7459 7460There are several ways for a thread to disappear, such as a regular 7461thread exit, but also when you detach from the process with the 7462@code{detach} command (@pxref{Attach, ,Debugging an Already-running 7463Process}), or if @value{GDBN} loses the remote connection 7464(@pxref{Remote Debugging}), etc. Note that with some targets, 7465@value{GDBN} is only able to detect a thread has exited when the user 7466explicitly asks for the thread list with the @code{info threads} 7467command. 7468 7469A breakpoint can't be both thread-specific and inferior-specific 7470(@pxref{Inferior-Specific Breakpoints}), or task-specific (@pxref{Ada 7471Tasks}); using more than one of the @code{thread}, @code{inferior}, or 7472@code{task} keywords when creating a breakpoint will give an error. 7473 7474@node Interrupted System Calls 7475@subsection Interrupted System Calls 7476 7477@cindex thread breakpoints and system calls 7478@cindex system calls and thread breakpoints 7479@cindex premature return from system calls 7480There is an unfortunate side effect when using @value{GDBN} to debug 7481multi-threaded programs. If one thread stops for a 7482breakpoint, or for some other reason, and another thread is blocked in a 7483system call, then the system call may return prematurely. This is a 7484consequence of the interaction between multiple threads and the signals 7485that @value{GDBN} uses to implement breakpoints and other events that 7486stop execution. 7487 7488To handle this problem, your program should check the return value of 7489each system call and react appropriately. This is good programming 7490style anyways. 7491 7492For example, do not write code like this: 7493 7494@smallexample 7495 sleep (10); 7496@end smallexample 7497 7498The call to @code{sleep} will return early if a different thread stops 7499at a breakpoint or for some other reason. 7500 7501Instead, write this: 7502 7503@smallexample 7504 int unslept = 10; 7505 while (unslept > 0) 7506 unslept = sleep (unslept); 7507@end smallexample 7508 7509A system call is allowed to return early, so the system is still 7510conforming to its specification. But @value{GDBN} does cause your 7511multi-threaded program to behave differently than it would without 7512@value{GDBN}. 7513 7514Also, @value{GDBN} uses internal breakpoints in the thread library to 7515monitor certain events such as thread creation and thread destruction. 7516When such an event happens, a system call in another thread may return 7517prematurely, even though your program does not appear to stop. 7518 7519@node Observer Mode 7520@subsection Observer Mode 7521 7522If you want to build on non-stop mode and observe program behavior 7523without any chance of disruption by @value{GDBN}, you can set 7524variables to disable all of the debugger's attempts to modify state, 7525whether by writing memory, inserting breakpoints, etc. These operate 7526at a low level, intercepting operations from all commands. 7527 7528When all of these are set to @code{off}, then @value{GDBN} is said to 7529be @dfn{observer mode}. As a convenience, the variable 7530@code{observer} can be set to disable these, plus enable non-stop 7531mode. 7532 7533Note that @value{GDBN} will not prevent you from making nonsensical 7534combinations of these settings. For instance, if you have enabled 7535@code{may-insert-breakpoints} but disabled @code{may-write-memory}, 7536then breakpoints that work by writing trap instructions into the code 7537stream will still not be able to be placed. 7538 7539@table @code 7540 7541@kindex observer 7542@item set observer on 7543@itemx set observer off 7544When set to @code{on}, this disables all the permission variables 7545below (except for @code{insert-fast-tracepoints}), plus enables 7546non-stop debugging. Setting this to @code{off} switches back to 7547normal debugging, though remaining in non-stop mode. 7548 7549@item show observer 7550Show whether observer mode is on or off. 7551 7552@kindex may-write-registers 7553@item set may-write-registers on 7554@itemx set may-write-registers off 7555This controls whether @value{GDBN} will attempt to alter the values of 7556registers, such as with assignment expressions in @code{print}, or the 7557@code{jump} command. It defaults to @code{on}. 7558 7559@item show may-write-registers 7560Show the current permission to write registers. 7561 7562@kindex may-write-memory 7563@item set may-write-memory on 7564@itemx set may-write-memory off 7565This controls whether @value{GDBN} will attempt to alter the contents 7566of memory, such as with assignment expressions in @code{print}. It 7567defaults to @code{on}. 7568 7569@item show may-write-memory 7570Show the current permission to write memory. 7571 7572@kindex may-insert-breakpoints 7573@item set may-insert-breakpoints on 7574@itemx set may-insert-breakpoints off 7575This controls whether @value{GDBN} will attempt to insert breakpoints. 7576This affects all breakpoints, including internal breakpoints defined 7577by @value{GDBN}. It defaults to @code{on}. 7578 7579@item show may-insert-breakpoints 7580Show the current permission to insert breakpoints. 7581 7582@kindex may-insert-tracepoints 7583@item set may-insert-tracepoints on 7584@itemx set may-insert-tracepoints off 7585This controls whether @value{GDBN} will attempt to insert (regular) 7586tracepoints at the beginning of a tracing experiment. It affects only 7587non-fast tracepoints, fast tracepoints being under the control of 7588@code{may-insert-fast-tracepoints}. It defaults to @code{on}. 7589 7590@item show may-insert-tracepoints 7591Show the current permission to insert tracepoints. 7592 7593@kindex may-insert-fast-tracepoints 7594@item set may-insert-fast-tracepoints on 7595@itemx set may-insert-fast-tracepoints off 7596This controls whether @value{GDBN} will attempt to insert fast 7597tracepoints at the beginning of a tracing experiment. It affects only 7598fast tracepoints, regular (non-fast) tracepoints being under the 7599control of @code{may-insert-tracepoints}. It defaults to @code{on}. 7600 7601@item show may-insert-fast-tracepoints 7602Show the current permission to insert fast tracepoints. 7603 7604@kindex may-interrupt 7605@item set may-interrupt on 7606@itemx set may-interrupt off 7607This controls whether @value{GDBN} will attempt to interrupt or stop 7608program execution. When this variable is @code{off}, the 7609@code{interrupt} command will have no effect, nor will 7610@kbd{Ctrl-c}. It defaults to @code{on}. 7611 7612@item show may-interrupt 7613Show the current permission to interrupt or stop the program. 7614 7615@end table 7616 7617@node Reverse Execution 7618@chapter Running programs backward 7619@cindex reverse execution 7620@cindex running programs backward 7621 7622When you are debugging a program, it is not unusual to realize that 7623you have gone too far, and some event of interest has already happened. 7624If the target environment supports it, @value{GDBN} can allow you to 7625``rewind'' the program by running it backward. 7626 7627A target environment that supports reverse execution should be able 7628to ``undo'' the changes in machine state that have taken place as the 7629program was executing normally. Variables, registers etc.@: should 7630revert to their previous values. Obviously this requires a great 7631deal of sophistication on the part of the target environment; not 7632all target environments can support reverse execution. 7633 7634When a program is executed in reverse, the instructions that 7635have most recently been executed are ``un-executed'', in reverse 7636order. The program counter runs backward, following the previous 7637thread of execution in reverse. As each instruction is ``un-executed'', 7638the values of memory and/or registers that were changed by that 7639instruction are reverted to their previous states. After executing 7640a piece of source code in reverse, all side effects of that code 7641should be ``undone'', and all variables should be returned to their 7642prior values@footnote{ 7643Note that some side effects are easier to undo than others. For instance, 7644memory and registers are relatively easy, but device I/O is hard. Some 7645targets may be able undo things like device I/O, and some may not. 7646 7647The contract between @value{GDBN} and the reverse executing target 7648requires only that the target do something reasonable when 7649@value{GDBN} tells it to execute backwards, and then report the 7650results back to @value{GDBN}. Whatever the target reports back to 7651@value{GDBN}, @value{GDBN} will report back to the user. @value{GDBN} 7652assumes that the memory and registers that the target reports are in a 7653consistent state, but @value{GDBN} accepts whatever it is given. 7654}. 7655 7656On some platforms, @value{GDBN} has built-in support for reverse 7657execution, activated with the @code{record} or @code{record btrace} 7658commands. @xref{Process Record and Replay}. Some remote targets, 7659typically full system emulators, support reverse execution directly 7660without requiring any special command. 7661 7662If you are debugging in a target environment that supports 7663reverse execution, @value{GDBN} provides the following commands. 7664 7665@table @code 7666@kindex reverse-continue 7667@kindex rc @r{(@code{reverse-continue})} 7668@item reverse-continue @r{[}@var{ignore-count}@r{]} 7669@itemx rc @r{[}@var{ignore-count}@r{]} 7670Beginning at the point where your program last stopped, start executing 7671in reverse. Reverse execution will stop for breakpoints and synchronous 7672exceptions (signals), just like normal execution. Behavior of 7673asynchronous signals depends on the target environment. 7674 7675@kindex reverse-step 7676@kindex rs @r{(@code{step})} 7677@item reverse-step @r{[}@var{count}@r{]} 7678Run the program backward until control reaches the start of a 7679different source line; then stop it, and return control to @value{GDBN}. 7680 7681Like the @code{step} command, @code{reverse-step} will only stop 7682at the beginning of a source line. It ``un-executes'' the previously 7683executed source line. If the previous source line included calls to 7684debuggable functions, @code{reverse-step} will step (backward) into 7685the called function, stopping at the beginning of the @emph{last} 7686statement in the called function (typically a return statement). 7687 7688Also, as with the @code{step} command, if non-debuggable functions are 7689called, @code{reverse-step} will run thru them backward without stopping. 7690 7691@kindex reverse-stepi 7692@kindex rsi @r{(@code{reverse-stepi})} 7693@item reverse-stepi @r{[}@var{count}@r{]} 7694Reverse-execute one machine instruction. Note that the instruction 7695to be reverse-executed is @emph{not} the one pointed to by the program 7696counter, but the instruction executed prior to that one. For instance, 7697if the last instruction was a jump, @code{reverse-stepi} will take you 7698back from the destination of the jump to the jump instruction itself. 7699 7700@kindex reverse-next 7701@kindex rn @r{(@code{reverse-next})} 7702@item reverse-next @r{[}@var{count}@r{]} 7703Run backward to the beginning of the previous line executed in 7704the current (innermost) stack frame. If the line contains function 7705calls, they will be ``un-executed'' without stopping. Starting from 7706the first line of a function, @code{reverse-next} will take you back 7707to the caller of that function, @emph{before} the function was called, 7708just as the normal @code{next} command would take you from the last 7709line of a function back to its return to its caller 7710@footnote{Unless the code is too heavily optimized.}. 7711 7712@kindex reverse-nexti 7713@kindex rni @r{(@code{reverse-nexti})} 7714@item reverse-nexti @r{[}@var{count}@r{]} 7715Like @code{nexti}, @code{reverse-nexti} executes a single instruction 7716in reverse, except that called functions are ``un-executed'' atomically. 7717That is, if the previously executed instruction was a return from 7718another function, @code{reverse-nexti} will continue to execute 7719in reverse until the call to that function (from the current stack 7720frame) is reached. 7721 7722@kindex reverse-finish 7723@item reverse-finish 7724Just as the @code{finish} command takes you to the point where the 7725current function returns, @code{reverse-finish} takes you to the point 7726where it was called. Instead of ending up at the end of the current 7727function invocation, you end up at the beginning. 7728 7729@kindex set exec-direction 7730@item set exec-direction 7731Set the direction of target execution. 7732@item set exec-direction reverse 7733@cindex execute forward or backward in time 7734@value{GDBN} will perform all execution commands in reverse, until the 7735exec-direction mode is changed to ``forward''. Affected commands include 7736@code{step, stepi, next, nexti, continue, and finish}. The @code{return} 7737command cannot be used in reverse mode. 7738@item set exec-direction forward 7739@value{GDBN} will perform all execution commands in the normal fashion. 7740This is the default. 7741@end table 7742 7743 7744@node Process Record and Replay 7745@chapter Recording Inferior's Execution and Replaying It 7746@cindex process record and replay 7747@cindex recording inferior's execution and replaying it 7748 7749On some platforms, @value{GDBN} provides a special @dfn{process record 7750and replay} target that can record a log of the process execution, and 7751replay it later with both forward and reverse execution commands. 7752 7753@cindex replay mode 7754When this target is in use, if the execution log includes the record 7755for the next instruction, @value{GDBN} will debug in @dfn{replay 7756mode}. In the replay mode, the inferior does not really execute code 7757instructions. Instead, all the events that normally happen during 7758code execution are taken from the execution log. While code is not 7759really executed in replay mode, the values of registers (including the 7760program counter register) and the memory of the inferior are still 7761changed as they normally would. Their contents are taken from the 7762execution log. 7763 7764@cindex record mode 7765If the record for the next instruction is not in the execution log, 7766@value{GDBN} will debug in @dfn{record mode}. In this mode, the 7767inferior executes normally, and @value{GDBN} records the execution log 7768for future replay. 7769 7770The process record and replay target supports reverse execution 7771(@pxref{Reverse Execution}), even if the platform on which the 7772inferior runs does not. However, the reverse execution is limited in 7773this case by the range of the instructions recorded in the execution 7774log. In other words, reverse execution on platforms that don't 7775support it directly can only be done in the replay mode. 7776 7777When debugging in the reverse direction, @value{GDBN} will work in 7778replay mode as long as the execution log includes the record for the 7779previous instruction; otherwise, it will work in record mode, if the 7780platform supports reverse execution, or stop if not. 7781 7782Currently, process record and replay is supported on ARM, Aarch64, 7783Moxie, PowerPC, PowerPC64, S/390, and x86 (i386/amd64) running 7784GNU/Linux. Process record and replay can be used both when native 7785debugging, and when remote debugging via @code{gdbserver}. 7786 7787For architecture environments that support process record and replay, 7788@value{GDBN} provides the following commands: 7789 7790@table @code 7791@kindex target record 7792@kindex target record-full 7793@kindex target record-btrace 7794@kindex record 7795@kindex record full 7796@kindex record btrace 7797@kindex record btrace bts 7798@kindex record btrace pt 7799@kindex record bts 7800@kindex record pt 7801@kindex rec 7802@kindex rec full 7803@kindex rec btrace 7804@kindex rec btrace bts 7805@kindex rec btrace pt 7806@kindex rec bts 7807@kindex rec pt 7808@item record @var{method} 7809This command starts the process record and replay target. The 7810recording method can be specified as parameter. Without a parameter 7811the command uses the @code{full} recording method. The following 7812recording methods are available: 7813 7814@table @code 7815@item full 7816Full record/replay recording using @value{GDBN}'s software record and 7817replay implementation. This method allows replaying and reverse 7818execution. 7819 7820@item btrace @var{format} 7821Hardware-supported instruction recording, supported on Intel 7822processors. This method does not record data. Further, the data is 7823collected in a ring buffer so old data will be overwritten when the 7824buffer is full. It allows limited reverse execution. Variables and 7825registers are not available during reverse execution. In remote 7826debugging, recording continues on disconnect. Recorded data can be 7827inspected after reconnecting. The recording may be stopped using 7828@code{record stop}. 7829 7830The recording format can be specified as parameter. Without a parameter 7831the command chooses the recording format. The following recording 7832formats are available: 7833 7834@table @code 7835@item bts 7836@cindex branch trace store 7837Use the @dfn{Branch Trace Store} (@acronym{BTS}) recording format. In 7838this format, the processor stores a from/to record for each executed 7839branch in the btrace ring buffer. 7840 7841@item pt 7842@cindex Intel Processor Trace 7843Use the @dfn{Intel Processor Trace} recording format. In this 7844format, the processor stores the execution trace in a compressed form 7845that is afterwards decoded by @value{GDBN}. 7846 7847The trace can be recorded with very low overhead. The compressed 7848trace format also allows small trace buffers to already contain a big 7849number of instructions compared to @acronym{BTS}. 7850 7851Decoding the recorded execution trace, on the other hand, is more 7852expensive than decoding @acronym{BTS} trace. This is mostly due to the 7853increased number of instructions to process. You should increase the 7854buffer-size with care. 7855@end table 7856 7857Not all recording formats may be available on all processors. 7858@end table 7859 7860The process record and replay target can only debug a process that is 7861already running. Therefore, you need first to start the process with 7862the @kbd{run} or @kbd{start} commands, and then start the recording 7863with the @kbd{record @var{method}} command. 7864 7865@cindex displaced stepping, and process record and replay 7866Displaced stepping (@pxref{Maintenance Commands,, displaced stepping}) 7867will be automatically disabled when process record and replay target 7868is started. That's because the process record and replay target 7869doesn't support displaced stepping. 7870 7871@cindex non-stop mode, and process record and replay 7872@cindex asynchronous execution, and process record and replay 7873If the inferior is in the non-stop mode (@pxref{Non-Stop Mode}) or in 7874the asynchronous execution mode (@pxref{Background Execution}), not 7875all recording methods are available. The @code{full} recording method 7876does not support these two modes. 7877 7878@kindex record stop 7879@kindex rec s 7880@item record stop 7881Stop the process record and replay target. When process record and 7882replay target stops, the entire execution log will be deleted and the 7883inferior will either be terminated, or will remain in its final state. 7884 7885When you stop the process record and replay target in record mode (at 7886the end of the execution log), the inferior will be stopped at the 7887next instruction that would have been recorded. In other words, if 7888you record for a while and then stop recording, the inferior process 7889will be left in the same state as if the recording never happened. 7890 7891On the other hand, if the process record and replay target is stopped 7892while in replay mode (that is, not at the end of the execution log, 7893but at some earlier point), the inferior process will become ``live'' 7894at that earlier state, and it will then be possible to continue the 7895usual ``live'' debugging of the process from that state. 7896 7897When the inferior process exits, or @value{GDBN} detaches from it, 7898process record and replay target will automatically stop itself. 7899 7900@kindex record goto 7901@item record goto 7902Go to a specific location in the execution log. There are several 7903ways to specify the location to go to: 7904 7905@table @code 7906@item record goto begin 7907@itemx record goto start 7908Go to the beginning of the execution log. 7909 7910@item record goto end 7911Go to the end of the execution log. 7912 7913@item record goto @var{n} 7914Go to instruction number @var{n} in the execution log. 7915@end table 7916 7917@kindex record save 7918@item record save @var{filename} 7919Save the execution log to a file @file{@var{filename}}. 7920Default filename is @file{gdb_record.@var{process_id}}, where 7921@var{process_id} is the process ID of the inferior. 7922 7923This command may not be available for all recording methods. 7924 7925@kindex record restore 7926@item record restore @var{filename} 7927Restore the execution log from a file @file{@var{filename}}. 7928File must have been created with @code{record save}. 7929 7930@kindex set record full 7931@item set record full insn-number-max @var{limit} 7932@itemx set record full insn-number-max unlimited 7933Set the limit of instructions to be recorded for the @code{full} 7934recording method. Default value is 200000. 7935 7936If @var{limit} is a positive number, then @value{GDBN} will start 7937deleting instructions from the log once the number of the record 7938instructions becomes greater than @var{limit}. For every new recorded 7939instruction, @value{GDBN} will delete the earliest recorded 7940instruction to keep the number of recorded instructions at the limit. 7941(Since deleting recorded instructions loses information, @value{GDBN} 7942lets you control what happens when the limit is reached, by means of 7943the @code{stop-at-limit} option, described below.) 7944 7945If @var{limit} is @code{unlimited} or zero, @value{GDBN} will never 7946delete recorded instructions from the execution log. The number of 7947recorded instructions is limited only by the available memory. 7948 7949@kindex show record full 7950@item show record full insn-number-max 7951Show the limit of instructions to be recorded with the @code{full} 7952recording method. 7953 7954@item set record full stop-at-limit 7955Control the behavior of the @code{full} recording method when the 7956number of recorded instructions reaches the limit. If ON (the 7957default), @value{GDBN} will stop when the limit is reached for the 7958first time and ask you whether you want to stop the inferior or 7959continue running it and recording the execution log. If you decide 7960to continue recording, each new recorded instruction will cause the 7961oldest one to be deleted. 7962 7963If this option is OFF, @value{GDBN} will automatically delete the 7964oldest record to make room for each new one, without asking. 7965 7966@item show record full stop-at-limit 7967Show the current setting of @code{stop-at-limit}. 7968 7969@item set record full memory-query 7970Control the behavior when @value{GDBN} is unable to record memory 7971changes caused by an instruction for the @code{full} recording method. 7972If ON, @value{GDBN} will query whether to stop the inferior in that 7973case. 7974 7975If this option is OFF (the default), @value{GDBN} will automatically 7976ignore the effect of such instructions on memory. Later, when 7977@value{GDBN} replays this execution log, it will mark the log of this 7978instruction as not accessible, and it will not affect the replay 7979results. 7980 7981@item show record full memory-query 7982Show the current setting of @code{memory-query}. 7983 7984@kindex set record btrace 7985The @code{btrace} record target does not trace data. As a 7986convenience, when replaying, @value{GDBN} reads read-only memory off 7987the live program directly, assuming that the addresses of the 7988read-only areas don't change. This for example makes it possible to 7989disassemble code while replaying, but not to print variables. 7990In some cases, being able to inspect variables might be useful. 7991You can use the following command for that: 7992 7993@item set record btrace replay-memory-access 7994Control the behavior of the @code{btrace} recording method when 7995accessing memory during replay. If @code{read-only} (the default), 7996@value{GDBN} will only allow accesses to read-only memory. 7997If @code{read-write}, @value{GDBN} will allow accesses to read-only 7998and to read-write memory. Beware that the accessed memory corresponds 7999to the live target and not necessarily to the current replay 8000position. 8001 8002@item set record btrace cpu @var{identifier} 8003Set the processor to be used for enabling workarounds for processor 8004errata when decoding the trace. 8005 8006Processor errata are defects in processor operation, caused by its 8007design or manufacture. They can cause a trace not to match the 8008specification. This, in turn, may cause trace decode to fail. 8009@value{GDBN} can detect erroneous trace packets and correct them, thus 8010avoiding the decoding failures. These corrections are known as 8011@dfn{errata workarounds}, and are enabled based on the processor on 8012which the trace was recorded. 8013 8014By default, @value{GDBN} attempts to detect the processor 8015automatically, and apply the necessary workarounds for it. However, 8016you may need to specify the processor if @value{GDBN} does not yet 8017support it. This command allows you to do that, and also allows to 8018disable the workarounds. 8019 8020The argument @var{identifier} identifies the @sc{cpu} and is of the 8021form: @code{@var{vendor}:@var{processor identifier}}. In addition, 8022there are two special identifiers, @code{none} and @code{auto} 8023(default). 8024 8025The following vendor identifiers and corresponding processor 8026identifiers are currently supported: 8027 8028@multitable @columnfractions .1 .9 8029 8030@item @code{intel} 8031@tab @var{family}/@var{model}[/@var{stepping}] 8032 8033@end multitable 8034 8035On GNU/Linux systems, the processor @var{family}, @var{model}, and 8036@var{stepping} can be obtained from @code{/proc/cpuinfo}. 8037 8038If @var{identifier} is @code{auto}, enable errata workarounds for the 8039processor on which the trace was recorded. If @var{identifier} is 8040@code{none}, errata workarounds are disabled. 8041 8042For example, when using an old @value{GDBN} on a new system, decode 8043may fail because @value{GDBN} does not support the new processor. It 8044often suffices to specify an older processor that @value{GDBN} 8045supports. 8046 8047@smallexample 8048(@value{GDBP}) info record 8049Active record target: record-btrace 8050Recording format: Intel Processor Trace. 8051Buffer size: 16kB. 8052Failed to configure the Intel Processor Trace decoder: unknown cpu. 8053(@value{GDBP}) set record btrace cpu intel:6/158 8054(@value{GDBP}) info record 8055Active record target: record-btrace 8056Recording format: Intel Processor Trace. 8057Buffer size: 16kB. 8058Recorded 84872 instructions in 3189 functions (0 gaps) for thread 1 (...). 8059@end smallexample 8060 8061@kindex show record btrace 8062@item show record btrace replay-memory-access 8063Show the current setting of @code{replay-memory-access}. 8064 8065@item show record btrace cpu 8066Show the processor to be used for enabling trace decode errata 8067workarounds. 8068 8069@kindex set record btrace bts 8070@item set record btrace bts buffer-size @var{size} 8071@itemx set record btrace bts buffer-size unlimited 8072Set the requested ring buffer size for branch tracing in @acronym{BTS} 8073format. Default is 64KB. 8074 8075If @var{size} is a positive number, then @value{GDBN} will try to 8076allocate a buffer of at least @var{size} bytes for each new thread 8077that uses the btrace recording method and the @acronym{BTS} format. 8078The actually obtained buffer size may differ from the requested 8079@var{size}. Use the @code{info record} command to see the actual 8080buffer size for each thread that uses the btrace recording method and 8081the @acronym{BTS} format. 8082 8083If @var{limit} is @code{unlimited} or zero, @value{GDBN} will try to 8084allocate a buffer of 4MB. 8085 8086Bigger buffers mean longer traces. On the other hand, @value{GDBN} will 8087also need longer to process the branch trace data before it can be used. 8088 8089@item show record btrace bts buffer-size @var{size} 8090Show the current setting of the requested ring buffer size for branch 8091tracing in @acronym{BTS} format. 8092 8093@kindex set record btrace pt 8094@item set record btrace pt buffer-size @var{size} 8095@itemx set record btrace pt buffer-size unlimited 8096Set the requested ring buffer size for branch tracing in Intel 8097Processor Trace format. Default is 16KB. 8098 8099If @var{size} is a positive number, then @value{GDBN} will try to 8100allocate a buffer of at least @var{size} bytes for each new thread 8101that uses the btrace recording method and the Intel Processor Trace 8102format. The actually obtained buffer size may differ from the 8103requested @var{size}. Use the @code{info record} command to see the 8104actual buffer size for each thread. 8105 8106If @var{limit} is @code{unlimited} or zero, @value{GDBN} will try to 8107allocate a buffer of 4MB. 8108 8109Bigger buffers mean longer traces. On the other hand, @value{GDBN} will 8110also need longer to process the branch trace data before it can be used. 8111 8112@item show record btrace pt buffer-size @var{size} 8113Show the current setting of the requested ring buffer size for branch 8114tracing in Intel Processor Trace format. 8115 8116@kindex info record 8117@item info record 8118Show various statistics about the recording depending on the recording 8119method: 8120 8121@table @code 8122@item full 8123For the @code{full} recording method, it shows the state of process 8124record and its in-memory execution log buffer, including: 8125 8126@itemize @bullet 8127@item 8128Whether in record mode or replay mode. 8129@item 8130Lowest recorded instruction number (counting from when the current execution log started recording instructions). 8131@item 8132Highest recorded instruction number. 8133@item 8134Current instruction about to be replayed (if in replay mode). 8135@item 8136Number of instructions contained in the execution log. 8137@item 8138Maximum number of instructions that may be contained in the execution log. 8139@end itemize 8140 8141@item btrace 8142For the @code{btrace} recording method, it shows: 8143 8144@itemize @bullet 8145@item 8146Recording format. 8147@item 8148Number of instructions that have been recorded. 8149@item 8150Number of blocks of sequential control-flow formed by the recorded 8151instructions. 8152@item 8153Whether in record mode or replay mode. 8154@end itemize 8155 8156For the @code{bts} recording format, it also shows: 8157@itemize @bullet 8158@item 8159Size of the perf ring buffer. 8160@end itemize 8161 8162For the @code{pt} recording format, it also shows: 8163@itemize @bullet 8164@item 8165Size of the perf ring buffer. 8166@end itemize 8167@end table 8168 8169@kindex record delete 8170@kindex rec del 8171@item record delete 8172When record target runs in replay mode (``in the past''), delete the 8173subsequent execution log and begin to record a new execution log starting 8174from the current address. This means you will abandon the previously 8175recorded ``future'' and begin recording a new ``future''. 8176 8177@kindex record instruction-history 8178@kindex rec instruction-history 8179@item record instruction-history 8180Disassembles instructions from the recorded execution log. By 8181default, ten instructions are disassembled. This can be changed using 8182the @code{set record instruction-history-size} command. Instructions 8183are printed in execution order. 8184 8185It can also print mixed source+disassembly if you specify the the 8186@code{/m} or @code{/s} modifier, and print the raw instructions in hex 8187as well as in symbolic form by specifying the @code{/r} or @code{/b} 8188modifier. The behaviour of the @code{/m}, @code{/s}, @code{/r}, and 8189@code{/b} modifiers are the same as for the @kbd{disassemble} command 8190(@pxref{disassemble,,@kbd{disassemble}}). 8191 8192The current position marker is printed for the instruction at the 8193current program counter value. This instruction can appear multiple 8194times in the trace and the current position marker will be printed 8195every time. To omit the current position marker, specify the 8196@code{/p} modifier. 8197 8198To better align the printed instructions when the trace contains 8199instructions from more than one function, the function name may be 8200omitted by specifying the @code{/f} modifier. 8201 8202Speculatively executed instructions are prefixed with @samp{?}. This 8203feature is not available for all recording formats. 8204 8205There are several ways to specify what part of the execution log to 8206disassemble: 8207 8208@table @code 8209@item record instruction-history @var{insn} 8210Disassembles ten instructions starting from instruction number 8211@var{insn}. 8212 8213@item record instruction-history @var{insn}, +/-@var{n} 8214Disassembles @var{n} instructions around instruction number 8215@var{insn}. If @var{n} is preceded with @code{+}, disassembles 8216@var{n} instructions after instruction number @var{insn}. If 8217@var{n} is preceded with @code{-}, disassembles @var{n} 8218instructions before instruction number @var{insn}. 8219 8220@item record instruction-history 8221Disassembles ten more instructions after the last disassembly. 8222 8223@item record instruction-history - 8224Disassembles ten more instructions before the last disassembly. 8225 8226@item record instruction-history @var{begin}, @var{end} 8227Disassembles instructions beginning with instruction number 8228@var{begin} until instruction number @var{end}. The instruction 8229number @var{end} is included. 8230@end table 8231 8232This command may not be available for all recording methods. 8233 8234@kindex set record 8235@item set record instruction-history-size @var{size} 8236@itemx set record instruction-history-size unlimited 8237Define how many instructions to disassemble in the @code{record 8238instruction-history} command. The default value is 10. 8239A @var{size} of @code{unlimited} means unlimited instructions. 8240 8241@kindex show record 8242@item show record instruction-history-size 8243Show how many instructions to disassemble in the @code{record 8244instruction-history} command. 8245 8246@kindex record function-call-history 8247@kindex rec function-call-history 8248@item record function-call-history 8249Prints the execution history at function granularity. For each sequence 8250of instructions that belong to the same function, it prints the name of 8251that function, the source lines for this instruction sequence (if the 8252@code{/l} modifier is specified), and the instructions numbers that form 8253the sequence (if the @code{/i} modifier is specified). The function names 8254are indented to reflect the call stack depth if the @code{/c} modifier is 8255specified. The @code{/l}, @code{/i}, and @code{/c} modifiers can be given 8256together. 8257 8258@smallexample 8259(@value{GDBP}) @b{list 1, 10} 82601 void foo (void) 82612 @{ 82623 @} 82634 82645 void bar (void) 82656 @{ 82667 ... 82678 foo (); 82689 ... 826910 @} 8270(@value{GDBP}) @b{record function-call-history /ilc} 82711 bar inst 1,4 at foo.c:6,8 82722 foo inst 5,10 at foo.c:2,3 82733 bar inst 11,13 at foo.c:9,10 8274@end smallexample 8275 8276By default, ten functions are printed. This can be changed using the 8277@code{set record function-call-history-size} command. Functions are 8278printed in execution order. There are several ways to specify what 8279to print: 8280 8281@table @code 8282@item record function-call-history @var{func} 8283Prints ten functions starting from function number @var{func}. 8284 8285@item record function-call-history @var{func}, +/-@var{n} 8286Prints @var{n} functions around function number @var{func}. If 8287@var{n} is preceded with @code{+}, prints @var{n} functions after 8288function number @var{func}. If @var{n} is preceded with @code{-}, 8289prints @var{n} functions before function number @var{func}. 8290 8291@item record function-call-history 8292Prints ten more functions after the last ten-function print. 8293 8294@item record function-call-history - 8295Prints ten more functions before the last ten-function print. 8296 8297@item record function-call-history @var{begin}, @var{end} 8298Prints functions beginning with function number @var{begin} until 8299function number @var{end}. The function number @var{end} is included. 8300@end table 8301 8302This command may not be available for all recording methods. 8303 8304@item set record function-call-history-size @var{size} 8305@itemx set record function-call-history-size unlimited 8306Define how many functions to print in the 8307@code{record function-call-history} command. The default value is 10. 8308A size of @code{unlimited} means unlimited functions. 8309 8310@item show record function-call-history-size 8311Show how many functions to print in the 8312@code{record function-call-history} command. 8313@end table 8314 8315 8316@node Stack 8317@chapter Examining the Stack 8318 8319When your program has stopped, the first thing you need to know is where it 8320stopped and how it got there. 8321 8322@cindex call stack 8323Each time your program performs a function call, information about the call 8324is generated. 8325That information includes the location of the call in your program, 8326the arguments of the call, 8327and the local variables of the function being called. 8328The information is saved in a block of data called a @dfn{stack frame}. 8329The stack frames are allocated in a region of memory called the @dfn{call 8330stack}. 8331 8332When your program stops, the @value{GDBN} commands for examining the 8333stack allow you to see all of this information. 8334 8335@cindex selected frame 8336One of the stack frames is @dfn{selected} by @value{GDBN} and many 8337@value{GDBN} commands refer implicitly to the selected frame. In 8338particular, whenever you ask @value{GDBN} for the value of a variable in 8339your program, the value is found in the selected frame. There are 8340special @value{GDBN} commands to select whichever frame you are 8341interested in. @xref{Selection, ,Selecting a Frame}. 8342 8343When your program stops, @value{GDBN} automatically selects the 8344currently executing frame and describes it briefly, similar to the 8345@code{frame} command (@pxref{Frame Info, ,Information about a Frame}). 8346 8347@menu 8348* Frames:: Stack frames 8349* Backtrace:: Backtraces 8350* Selection:: Selecting a frame 8351* Frame Info:: Information on a frame 8352* Frame Apply:: Applying a command to several frames 8353* Frame Filter Management:: Managing frame filters 8354 8355@end menu 8356 8357@node Frames 8358@section Stack Frames 8359 8360@cindex frame, definition 8361@cindex stack frame 8362The call stack is divided up into contiguous pieces called @dfn{stack 8363frames}, or @dfn{frames} for short; each frame is the data associated 8364with one call to one function. The frame contains the arguments given 8365to the function, the function's local variables, and the address at 8366which the function is executing. 8367 8368@cindex initial frame 8369@cindex outermost frame 8370@cindex innermost frame 8371When your program is started, the stack has only one frame, that of the 8372function @code{main}. This is called the @dfn{initial} frame or the 8373@dfn{outermost} frame. Each time a function is called, a new frame is 8374made. Each time a function returns, the frame for that function invocation 8375is eliminated. If a function is recursive, there can be many frames for 8376the same function. The frame for the function in which execution is 8377actually occurring is called the @dfn{innermost} frame. This is the most 8378recently created of all the stack frames that still exist. 8379 8380@cindex frame pointer 8381Inside your program, stack frames are identified by their addresses. A 8382stack frame consists of many bytes, each of which has its own address; each 8383kind of computer has a convention for choosing one byte whose 8384address serves as the address of the frame. Usually this address is kept 8385in a register called the @dfn{frame pointer register} 8386(@pxref{Registers, $fp}) while execution is going on in that frame. 8387 8388@cindex frame level 8389@cindex frame number 8390@value{GDBN} labels each existing stack frame with a @dfn{level}, a 8391number that is zero for the innermost frame, one for the frame that 8392called it, and so on upward. These level numbers give you a way of 8393designating stack frames in @value{GDBN} commands. The terms 8394@dfn{frame number} and @dfn{frame level} can be used interchangeably to 8395describe this number. 8396 8397@c The -fomit-frame-pointer below perennially causes hbox overflow 8398@c underflow problems. 8399@cindex frameless execution 8400Some compilers provide a way to compile functions so that they operate 8401without stack frames. (For example, the @value{NGCC} option 8402@smallexample 8403@samp{-fomit-frame-pointer} 8404@end smallexample 8405generates functions without a frame.) 8406This is occasionally done with heavily used library functions to save 8407the frame setup time. @value{GDBN} has limited facilities for dealing 8408with these function invocations. If the innermost function invocation 8409has no stack frame, @value{GDBN} nevertheless regards it as though 8410it had a separate frame, which is numbered zero as usual, allowing 8411correct tracing of the function call chain. However, @value{GDBN} has 8412no provision for frameless functions elsewhere in the stack. 8413 8414@node Backtrace 8415@section Backtraces 8416 8417@cindex traceback 8418@cindex call stack traces 8419A backtrace is a summary of how your program got where it is. It shows one 8420line per frame, for many frames, starting with the currently executing 8421frame (frame zero), followed by its caller (frame one), and on up the 8422stack. 8423 8424@anchor{backtrace-command} 8425@kindex backtrace 8426@kindex bt @r{(@code{backtrace})} 8427To print a backtrace of the entire stack, use the @code{backtrace} 8428command, or its alias @code{bt}. This command will print one line per 8429frame for frames in the stack. By default, all stack frames are 8430printed. You can stop the backtrace at any time by typing the system 8431interrupt character, normally @kbd{Ctrl-c}. 8432 8433@table @code 8434@item backtrace [@var{option}]@dots{} [@var{qualifier}]@dots{} [@var{count}] 8435@itemx bt [@var{option}]@dots{} [@var{qualifier}]@dots{} [@var{count}] 8436Print the backtrace of the entire stack. 8437 8438The optional @var{count} can be one of the following: 8439 8440@table @code 8441@item @var{n} 8442@itemx @var{n} 8443Print only the innermost @var{n} frames, where @var{n} is a positive 8444number. 8445 8446@item -@var{n} 8447@itemx -@var{n} 8448Print only the outermost @var{n} frames, where @var{n} is a positive 8449number. 8450@end table 8451 8452Options: 8453 8454@table @code 8455@item -full 8456Print the values of the local variables also. This can be combined 8457with the optional @var{count} to limit the number of frames shown. 8458 8459@item -no-filters 8460Do not run Python frame filters on this backtrace. @xref{Frame 8461Filter API}, for more information. Additionally use @ref{disable 8462frame-filter all} to turn off all frame filters. This is only 8463relevant when @value{GDBN} has been configured with @code{Python} 8464support. 8465 8466@item -hide 8467A Python frame filter might decide to ``elide'' some frames. Normally 8468such elided frames are still printed, but they are indented relative 8469to the filtered frames that cause them to be elided. The @code{-hide} 8470option causes elided frames to not be printed at all. 8471@end table 8472 8473The @code{backtrace} command also supports a number of options that 8474allow overriding relevant global print settings as set by @code{set 8475backtrace} and @code{set print} subcommands: 8476 8477@table @code 8478@item -past-main [@code{on}|@code{off}] 8479Set whether backtraces should continue past @code{main}. Related setting: 8480@ref{set backtrace past-main}. 8481 8482@item -past-entry [@code{on}|@code{off}] 8483Set whether backtraces should continue past the entry point of a program. 8484Related setting: @ref{set backtrace past-entry}. 8485 8486@item -entry-values @code{no}|@code{only}|@code{preferred}|@code{if-needed}|@code{both}|@code{compact}|@code{default} 8487Set printing of function arguments at function entry. 8488Related setting: @ref{set print entry-values}. 8489 8490@item -frame-arguments @code{all}|@code{scalars}|@code{none} 8491Set printing of non-scalar frame arguments. 8492Related setting: @ref{set print frame-arguments}. 8493 8494@item -raw-frame-arguments [@code{on}|@code{off}] 8495Set whether to print frame arguments in raw form. 8496Related setting: @ref{set print raw-frame-arguments}. 8497 8498@item -frame-info @code{auto}|@code{source-line}|@code{location}|@code{source-and-location}|@code{location-and-address}|@code{short-location} 8499Set printing of frame information. 8500Related setting: @ref{set print frame-info}. 8501@end table 8502 8503The optional @var{qualifier} is maintained for backward compatibility. 8504It can be one of the following: 8505 8506@table @code 8507@item full 8508Equivalent to the @code{-full} option. 8509 8510@item no-filters 8511Equivalent to the @code{-no-filters} option. 8512 8513@item hide 8514Equivalent to the @code{-hide} option. 8515@end table 8516 8517@end table 8518 8519@kindex where 8520@kindex info stack 8521The names @code{where} and @code{info stack} (abbreviated @code{info s}) 8522are additional aliases for @code{backtrace}. 8523 8524@cindex multiple threads, backtrace 8525In a multi-threaded program, @value{GDBN} by default shows the 8526backtrace only for the current thread. To display the backtrace for 8527several or all of the threads, use the command @code{thread apply} 8528(@pxref{Threads, thread apply}). For example, if you type @kbd{thread 8529apply all backtrace}, @value{GDBN} will display the backtrace for all 8530the threads; this is handy when you debug a core dump of a 8531multi-threaded program. 8532 8533Each line in the backtrace shows the frame number and the function name. 8534The program counter value is also shown---unless you use @code{set 8535print address off}. The backtrace also shows the source file name and 8536line number, as well as the arguments to the function. The program 8537counter value is omitted if it is at the beginning of the code for that 8538line number. 8539 8540Here is an example of a backtrace. It was made with the command 8541@samp{bt 3}, so it shows the innermost three frames. 8542 8543@smallexample 8544@group 8545#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) 8546 at builtin.c:993 8547#1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242 8548#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) 8549 at macro.c:71 8550(More stack frames follow...) 8551@end group 8552@end smallexample 8553 8554@noindent 8555The display for frame zero does not begin with a program counter 8556value, indicating that your program has stopped at the beginning of the 8557code for line @code{993} of @code{builtin.c}. 8558 8559@noindent 8560The value of parameter @code{data} in frame 1 has been replaced by 8561@code{@dots{}}. By default, @value{GDBN} prints the value of a parameter 8562only if it is a scalar (integer, pointer, enumeration, etc). See command 8563@kbd{set print frame-arguments} in @ref{Print Settings} for more details 8564on how to configure the way function parameter values are printed. 8565The command @kbd{set print frame-info} (@pxref{Print Settings}) controls 8566what frame information is printed. 8567 8568@cindex optimized out, in backtrace 8569@cindex function call arguments, optimized out 8570If your program was compiled with optimizations, some compilers will 8571optimize away arguments passed to functions if those arguments are 8572never used after the call. Such optimizations generate code that 8573passes arguments through registers, but doesn't store those arguments 8574in the stack frame. @value{GDBN} has no way of displaying such 8575arguments in stack frames other than the innermost one. Here's what 8576such a backtrace might look like: 8577 8578@smallexample 8579@group 8580#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) 8581 at builtin.c:993 8582#1 0x6e38 in expand_macro (sym=<optimized out>) at macro.c:242 8583#2 0x6840 in expand_token (obs=0x0, t=<optimized out>, td=0xf7fffb08) 8584 at macro.c:71 8585(More stack frames follow...) 8586@end group 8587@end smallexample 8588 8589@noindent 8590The values of arguments that were not saved in their stack frames are 8591shown as @samp{<optimized out>}. 8592 8593If you need to display the values of such optimized-out arguments, 8594either deduce that from other variables whose values depend on the one 8595you are interested in, or recompile without optimizations. 8596 8597@cindex backtrace beyond @code{main} function 8598@cindex program entry point 8599@cindex startup code, and backtrace 8600Most programs have a standard user entry point---a place where system 8601libraries and startup code transition into user code. For C this is 8602@code{main}@footnote{ 8603Note that embedded programs (the so-called ``free-standing'' 8604environment) are not required to have a @code{main} function as the 8605entry point. They could even have multiple entry points.}. 8606When @value{GDBN} finds the entry function in a backtrace 8607it will terminate the backtrace, to avoid tracing into highly 8608system-specific (and generally uninteresting) code. 8609 8610If you need to examine the startup code, or limit the number of levels 8611in a backtrace, you can change this behavior: 8612 8613@table @code 8614@item set backtrace past-main 8615@itemx set backtrace past-main on 8616@anchor{set backtrace past-main} 8617@kindex set backtrace 8618Backtraces will continue past the user entry point. 8619 8620@item set backtrace past-main off 8621Backtraces will stop when they encounter the user entry point. This is the 8622default. 8623 8624@item show backtrace past-main 8625@kindex show backtrace 8626Display the current user entry point backtrace policy. 8627 8628@item set backtrace past-entry 8629@itemx set backtrace past-entry on 8630@anchor{set backtrace past-entry} 8631Backtraces will continue past the internal entry point of an application. 8632This entry point is encoded by the linker when the application is built, 8633and is likely before the user entry point @code{main} (or equivalent) is called. 8634 8635@item set backtrace past-entry off 8636Backtraces will stop when they encounter the internal entry point of an 8637application. This is the default. 8638 8639@item show backtrace past-entry 8640Display the current internal entry point backtrace policy. 8641 8642@item set backtrace limit @var{n} 8643@itemx set backtrace limit 0 8644@itemx set backtrace limit unlimited 8645@anchor{set backtrace limit} 8646@cindex backtrace limit 8647Limit the backtrace to @var{n} levels. A value of @code{unlimited} 8648or zero means unlimited levels. 8649 8650@item show backtrace limit 8651Display the current limit on backtrace levels. 8652@end table 8653 8654You can control how file names are displayed. 8655 8656@table @code 8657@item set filename-display 8658@itemx set filename-display relative 8659@cindex filename-display 8660Display file names relative to the compilation directory. This is the default. 8661 8662@item set filename-display basename 8663Display only basename of a filename. 8664 8665@item set filename-display absolute 8666Display an absolute filename. 8667 8668@item show filename-display 8669Show the current way to display filenames. 8670@end table 8671 8672@node Selection 8673@section Selecting a Frame 8674 8675Most commands for examining the stack and other data in your program work on 8676whichever stack frame is selected at the moment. Here are the commands for 8677selecting a stack frame; all of them finish by printing a brief description 8678of the stack frame just selected. 8679 8680@table @code 8681@kindex frame@r{, selecting} 8682@kindex f @r{(@code{frame})} 8683@item frame @r{[} @var{frame-selection-spec} @r{]} 8684@item f @r{[} @var{frame-selection-spec} @r{]} 8685The @command{frame} command allows different stack frames to be 8686selected. The @var{frame-selection-spec} can be any of the following: 8687 8688@table @code 8689@kindex frame level 8690@item @var{num} 8691@item level @var{num} 8692Select frame level @var{num}. Recall that frame zero is the innermost 8693(currently executing) frame, frame one is the frame that called the 8694innermost one, and so on. The highest level frame is usually the one 8695for @code{main}. 8696 8697As this is the most common method of navigating the frame stack, the 8698string @command{level} can be omitted. For example, the following two 8699commands are equivalent: 8700 8701@smallexample 8702(@value{GDBP}) frame 3 8703(@value{GDBP}) frame level 3 8704@end smallexample 8705 8706@kindex frame address 8707@item address @var{stack-address} 8708Select the frame with stack address @var{stack-address}. The 8709@var{stack-address} for a frame can be seen in the output of 8710@command{info frame}, for example: 8711 8712@smallexample 8713(@value{GDBP}) info frame 8714Stack level 1, frame at 0x7fffffffda30: 8715 rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5 8716 tail call frame, caller of frame at 0x7fffffffda30 8717 source language c++. 8718 Arglist at unknown address. 8719 Locals at unknown address, Previous frame's sp is 0x7fffffffda30 8720@end smallexample 8721 8722The @var{stack-address} for this frame is @code{0x7fffffffda30} as 8723indicated by the line: 8724 8725@smallexample 8726Stack level 1, frame at 0x7fffffffda30: 8727@end smallexample 8728 8729@kindex frame function 8730@item function @var{function-name} 8731Select the stack frame for function @var{function-name}. If there are 8732multiple stack frames for function @var{function-name} then the inner 8733most stack frame is selected. 8734 8735@kindex frame view 8736@item view @var{stack-address} @r{[} @var{pc-addr} @r{]} 8737View a frame that is not part of @value{GDBN}'s backtrace. The frame 8738viewed has stack address @var{stack-addr}, and optionally, a program 8739counter address of @var{pc-addr}. 8740 8741This is useful mainly if the chaining of stack frames has been 8742damaged by a bug, making it impossible for @value{GDBN} to assign 8743numbers properly to all frames. In addition, this can be useful 8744when your program has multiple stacks and switches between them. 8745 8746When viewing a frame outside the current backtrace using 8747@command{frame view} then you can always return to the original 8748stack using one of the previous stack frame selection instructions, 8749for example @command{frame level 0}. 8750 8751@end table 8752 8753@kindex up 8754@item up @var{n} 8755Move @var{n} frames up the stack; @var{n} defaults to 1. For positive 8756numbers @var{n}, this advances toward the outermost frame, to higher 8757frame numbers, to frames that have existed longer. 8758 8759@kindex down 8760@kindex do @r{(@code{down})} 8761@item down @var{n} 8762Move @var{n} frames down the stack; @var{n} defaults to 1. For 8763positive numbers @var{n}, this advances toward the innermost frame, to 8764lower frame numbers, to frames that were created more recently. 8765You may abbreviate @code{down} as @code{do}. 8766@end table 8767 8768All of these commands end by printing two lines of output describing the 8769frame. The first line shows the frame number, the function name, the 8770arguments, and the source file and line number of execution in that 8771frame. The second line shows the text of that source line. 8772 8773@need 1000 8774For example: 8775 8776@smallexample 8777@group 8778(@value{GDBP}) up 8779#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) 8780 at env.c:10 878110 read_input_file (argv[i]); 8782@end group 8783@end smallexample 8784 8785After such a printout, the @code{list} command with no arguments 8786prints ten lines centered on the point of execution in the frame. 8787You can also edit the program at the point of execution with your favorite 8788editing program by typing @code{edit}. 8789@xref{List, ,Printing Source Lines}, 8790for details. 8791 8792@table @code 8793@kindex select-frame 8794@item select-frame @r{[} @var{frame-selection-spec} @r{]} 8795The @code{select-frame} command is a variant of @code{frame} that does 8796not display the new frame after selecting it. This command is 8797intended primarily for use in @value{GDBN} command scripts, where the 8798output might be unnecessary and distracting. The 8799@var{frame-selection-spec} is as for the @command{frame} command 8800described in @ref{Selection, ,Selecting a Frame}. 8801 8802@kindex down-silently 8803@kindex up-silently 8804@item up-silently @var{n} 8805@itemx down-silently @var{n} 8806These two commands are variants of @code{up} and @code{down}, 8807respectively; they differ in that they do their work silently, without 8808causing display of the new frame. They are intended primarily for use 8809in @value{GDBN} command scripts, where the output might be unnecessary and 8810distracting. 8811@end table 8812 8813@node Frame Info 8814@section Information About a Frame 8815 8816There are several other commands to print information about the selected 8817stack frame. 8818 8819@table @code 8820@item frame 8821@itemx f 8822When used without any argument, this command does not change which 8823frame is selected, but prints a brief description of the currently 8824selected stack frame. It can be abbreviated @code{f}. With an 8825argument, this command is used to select a stack frame. 8826@xref{Selection, ,Selecting a Frame}. 8827 8828@kindex info frame 8829@kindex info f @r{(@code{info frame})} 8830@item info frame 8831@itemx info f 8832This command prints a verbose description of the selected stack frame, 8833including: 8834 8835@itemize @bullet 8836@item 8837the address of the frame 8838@item 8839the address of the next frame down (called by this frame) 8840@item 8841the address of the next frame up (caller of this frame) 8842@item 8843the language in which the source code corresponding to this frame is written 8844@item 8845the address of the frame's arguments 8846@item 8847the address of the frame's local variables 8848@item 8849the program counter saved in it (the address of execution in the caller frame) 8850@item 8851which registers were saved in the frame 8852@end itemize 8853 8854@noindent The verbose description is useful when 8855something has gone wrong that has made the stack format fail to fit 8856the usual conventions. 8857 8858@item info frame @r{[} @var{frame-selection-spec} @r{]} 8859@itemx info f @r{[} @var{frame-selection-spec} @r{]} 8860Print a verbose description of the frame selected by 8861@var{frame-selection-spec}. The @var{frame-selection-spec} is the 8862same as for the @command{frame} command (@pxref{Selection, ,Selecting 8863a Frame}). The selected frame remains unchanged by this command. 8864 8865@kindex info args 8866@item info args [-q] 8867Print the arguments of the selected frame, each on a separate line. 8868 8869The optional flag @samp{-q}, which stands for @samp{quiet}, disables 8870printing header information and messages explaining why no argument 8871have been printed. 8872 8873@item info args [-q] [-t @var{type_regexp}] [@var{regexp}] 8874Like @kbd{info args}, but only print the arguments selected 8875with the provided regexp(s). 8876 8877If @var{regexp} is provided, print only the arguments whose names 8878match the regular expression @var{regexp}. 8879 8880If @var{type_regexp} is provided, print only the arguments whose 8881types, as printed by the @code{whatis} command, match 8882the regular expression @var{type_regexp}. 8883If @var{type_regexp} contains space(s), it should be enclosed in 8884quote characters. If needed, use backslash to escape the meaning 8885of special characters or quotes. 8886 8887If both @var{regexp} and @var{type_regexp} are provided, an argument 8888is printed only if its name matches @var{regexp} and its type matches 8889@var{type_regexp}. 8890 8891@item info locals [-q] 8892@kindex info locals 8893Print the local variables of the selected frame, each on a separate 8894line. These are all variables (declared either static or automatic) 8895accessible at the point of execution of the selected frame. 8896 8897The optional flag @samp{-q}, which stands for @samp{quiet}, disables 8898printing header information and messages explaining why no local variables 8899have been printed. 8900 8901@item info locals [-q] [-t @var{type_regexp}] [@var{regexp}] 8902Like @kbd{info locals}, but only print the local variables selected 8903with the provided regexp(s). 8904 8905If @var{regexp} is provided, print only the local variables whose names 8906match the regular expression @var{regexp}. 8907 8908If @var{type_regexp} is provided, print only the local variables whose 8909types, as printed by the @code{whatis} command, match 8910the regular expression @var{type_regexp}. 8911If @var{type_regexp} contains space(s), it should be enclosed in 8912quote characters. If needed, use backslash to escape the meaning 8913of special characters or quotes. 8914 8915If both @var{regexp} and @var{type_regexp} are provided, a local variable 8916is printed only if its name matches @var{regexp} and its type matches 8917@var{type_regexp}. 8918 8919The command @kbd{info locals -q -t @var{type_regexp}} can usefully be 8920combined with the commands @kbd{frame apply} and @kbd{thread apply}. 8921For example, your program might use Resource Acquisition Is 8922Initialization types (RAII) such as @code{lock_something_t}: each 8923local variable of type @code{lock_something_t} automatically places a 8924lock that is destroyed when the variable goes out of scope. You can 8925then list all acquired locks in your program by doing 8926@smallexample 8927thread apply all -s frame apply all -s info locals -q -t lock_something_t 8928@end smallexample 8929@noindent 8930or the equivalent shorter form 8931@smallexample 8932tfaas i lo -q -t lock_something_t 8933@end smallexample 8934 8935@end table 8936 8937@node Frame Apply 8938@section Applying a Command to Several Frames. 8939@kindex frame apply 8940@cindex apply command to several frames 8941@table @code 8942@item frame apply [all | @var{count} | @var{-count} | level @var{level}@dots{}] [@var{option}]@dots{} @var{command} 8943The @code{frame apply} command allows you to apply the named 8944@var{command} to one or more frames. 8945 8946@table @code 8947@item @code{all} 8948Specify @code{all} to apply @var{command} to all frames. 8949 8950@item @var{count} 8951Use @var{count} to apply @var{command} to the innermost @var{count} 8952frames, where @var{count} is a positive number. 8953 8954@item @var{-count} 8955Use @var{-count} to apply @var{command} to the outermost @var{count} 8956frames, where @var{count} is a positive number. 8957 8958@item @code{level} 8959Use @code{level} to apply @var{command} to the set of frames identified 8960by the @var{level} list. @var{level} is a frame level or a range of frame 8961levels as @var{level1}-@var{level2}. The frame level is the number shown 8962in the first field of the @samp{backtrace} command output. 8963E.g., @samp{2-4 6-8 3} indicates to apply @var{command} for the frames 8964at levels 2, 3, 4, 6, 7, 8, and then again on frame at level 3. 8965 8966@end table 8967 8968Note that the frames on which @code{frame apply} applies a command are 8969also influenced by the @code{set backtrace} settings such as @code{set 8970backtrace past-main} and @code{set backtrace limit N}. 8971@xref{Backtrace,,Backtraces}. 8972 8973The @code{frame apply} command also supports a number of options that 8974allow overriding relevant @code{set backtrace} settings: 8975 8976@table @code 8977@item -past-main [@code{on}|@code{off}] 8978Whether backtraces should continue past @code{main}. 8979Related setting: @ref{set backtrace past-main}. 8980 8981@item -past-entry [@code{on}|@code{off}] 8982Whether backtraces should continue past the entry point of a program. 8983Related setting: @ref{set backtrace past-entry}. 8984@end table 8985 8986By default, @value{GDBN} displays some frame information before the 8987output produced by @var{command}, and an error raised during the 8988execution of a @var{command} will abort @code{frame apply}. The 8989following options can be used to fine-tune these behaviors: 8990 8991@table @code 8992@item -c 8993The flag @code{-c}, which stands for @samp{continue}, causes any 8994errors in @var{command} to be displayed, and the execution of 8995@code{frame apply} then continues. 8996@item -s 8997The flag @code{-s}, which stands for @samp{silent}, causes any errors 8998or empty output produced by a @var{command} to be silently ignored. 8999That is, the execution continues, but the frame information and errors 9000are not printed. 9001@item -q 9002The flag @code{-q} (@samp{quiet}) disables printing the frame 9003information. 9004@end table 9005 9006The following example shows how the flags @code{-c} and @code{-s} are 9007working when applying the command @code{p j} to all frames, where 9008variable @code{j} can only be successfully printed in the outermost 9009@code{#1 main} frame. 9010 9011@smallexample 9012@group 9013(@value{GDBP}) frame apply all p j 9014#0 some_function (i=5) at fun.c:4 9015No symbol "j" in current context. 9016(@value{GDBP}) frame apply all -c p j 9017#0 some_function (i=5) at fun.c:4 9018No symbol "j" in current context. 9019#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11 9020$1 = 5 9021(@value{GDBP}) frame apply all -s p j 9022#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11 9023$2 = 5 9024(@value{GDBP}) 9025@end group 9026@end smallexample 9027 9028By default, @samp{frame apply}, prints the frame location 9029information before the command output: 9030 9031@smallexample 9032@group 9033(@value{GDBP}) frame apply all p $sp 9034#0 some_function (i=5) at fun.c:4 9035$4 = (void *) 0xffffd1e0 9036#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11 9037$5 = (void *) 0xffffd1f0 9038(@value{GDBP}) 9039@end group 9040@end smallexample 9041 9042If the flag @code{-q} is given, no frame information is printed: 9043@smallexample 9044@group 9045(@value{GDBP}) frame apply all -q p $sp 9046$12 = (void *) 0xffffd1e0 9047$13 = (void *) 0xffffd1f0 9048(@value{GDBP}) 9049@end group 9050@end smallexample 9051 9052@end table 9053 9054@table @code 9055 9056@kindex faas 9057@cindex apply a command to all frames (ignoring errors and empty output) 9058@item faas @var{command} 9059Shortcut for @code{frame apply all -s @var{command}}. 9060Applies @var{command} on all frames, ignoring errors and empty output. 9061 9062It can for example be used to print a local variable or a function 9063argument without knowing the frame where this variable or argument 9064is, using: 9065@smallexample 9066(@value{GDBP}) faas p some_local_var_i_do_not_remember_where_it_is 9067@end smallexample 9068 9069The @code{faas} command accepts the same options as the @code{frame 9070apply} command. @xref{Frame Apply,,frame apply}. 9071 9072Note that the command @code{tfaas @var{command}} applies @var{command} 9073on all frames of all threads. See @xref{Threads,,Threads}. 9074@end table 9075 9076 9077@node Frame Filter Management 9078@section Management of Frame Filters. 9079@cindex managing frame filters 9080 9081Frame filters are Python based utilities to manage and decorate the 9082output of frames. @xref{Frame Filter API}, for further information. 9083 9084Managing frame filters is performed by several commands available 9085within @value{GDBN}, detailed here. 9086 9087@table @code 9088@kindex info frame-filter 9089@item info frame-filter 9090Print a list of installed frame filters from all dictionaries, showing 9091their name, priority and enabled status. 9092 9093@kindex disable frame-filter 9094@anchor{disable frame-filter all} 9095@item disable frame-filter @var{filter-dictionary} @var{filter-name} 9096Disable a frame filter in the dictionary matching 9097@var{filter-dictionary} and @var{filter-name}. The 9098@var{filter-dictionary} may be @code{all}, @code{global}, 9099@code{progspace}, or the name of the object file where the frame filter 9100dictionary resides. When @code{all} is specified, all frame filters 9101across all dictionaries are disabled. The @var{filter-name} is the name 9102of the frame filter and is used when @code{all} is not the option for 9103@var{filter-dictionary}. A disabled frame-filter is not deleted, it 9104may be enabled again later. 9105 9106@kindex enable frame-filter 9107@item enable frame-filter @var{filter-dictionary} @var{filter-name} 9108Enable a frame filter in the dictionary matching 9109@var{filter-dictionary} and @var{filter-name}. The 9110@var{filter-dictionary} may be @code{all}, @code{global}, 9111@code{progspace} or the name of the object file where the frame filter 9112dictionary resides. When @code{all} is specified, all frame filters across 9113all dictionaries are enabled. The @var{filter-name} is the name of the frame 9114filter and is used when @code{all} is not the option for 9115@var{filter-dictionary}. 9116 9117Example: 9118 9119@smallexample 9120(@value{GDBP}) info frame-filter 9121 9122global frame-filters: 9123 Priority Enabled Name 9124 1000 No PrimaryFunctionFilter 9125 100 Yes Reverse 9126 9127progspace /build/test frame-filters: 9128 Priority Enabled Name 9129 100 Yes ProgspaceFilter 9130 9131objfile /build/test frame-filters: 9132 Priority Enabled Name 9133 999 Yes BuildProgramFilter 9134 9135(@value{GDBP}) disable frame-filter /build/test BuildProgramFilter 9136(@value{GDBP}) info frame-filter 9137 9138global frame-filters: 9139 Priority Enabled Name 9140 1000 No PrimaryFunctionFilter 9141 100 Yes Reverse 9142 9143progspace /build/test frame-filters: 9144 Priority Enabled Name 9145 100 Yes ProgspaceFilter 9146 9147objfile /build/test frame-filters: 9148 Priority Enabled Name 9149 999 No BuildProgramFilter 9150 9151(@value{GDBP}) enable frame-filter global PrimaryFunctionFilter 9152(@value{GDBP}) info frame-filter 9153 9154global frame-filters: 9155 Priority Enabled Name 9156 1000 Yes PrimaryFunctionFilter 9157 100 Yes Reverse 9158 9159progspace /build/test frame-filters: 9160 Priority Enabled Name 9161 100 Yes ProgspaceFilter 9162 9163objfile /build/test frame-filters: 9164 Priority Enabled Name 9165 999 No BuildProgramFilter 9166@end smallexample 9167 9168@kindex set frame-filter priority 9169@item set frame-filter priority @var{filter-dictionary} @var{filter-name} @var{priority} 9170Set the @var{priority} of a frame filter in the dictionary matching 9171@var{filter-dictionary}, and the frame filter name matching 9172@var{filter-name}. The @var{filter-dictionary} may be @code{global}, 9173@code{progspace} or the name of the object file where the frame filter 9174dictionary resides. The @var{priority} is an integer. 9175 9176@kindex show frame-filter priority 9177@item show frame-filter priority @var{filter-dictionary} @var{filter-name} 9178Show the @var{priority} of a frame filter in the dictionary matching 9179@var{filter-dictionary}, and the frame filter name matching 9180@var{filter-name}. The @var{filter-dictionary} may be @code{global}, 9181@code{progspace} or the name of the object file where the frame filter 9182dictionary resides. 9183 9184Example: 9185 9186@smallexample 9187(@value{GDBP}) info frame-filter 9188 9189global frame-filters: 9190 Priority Enabled Name 9191 1000 Yes PrimaryFunctionFilter 9192 100 Yes Reverse 9193 9194progspace /build/test frame-filters: 9195 Priority Enabled Name 9196 100 Yes ProgspaceFilter 9197 9198objfile /build/test frame-filters: 9199 Priority Enabled Name 9200 999 No BuildProgramFilter 9201 9202(@value{GDBP}) set frame-filter priority global Reverse 50 9203(@value{GDBP}) info frame-filter 9204 9205global frame-filters: 9206 Priority Enabled Name 9207 1000 Yes PrimaryFunctionFilter 9208 50 Yes Reverse 9209 9210progspace /build/test frame-filters: 9211 Priority Enabled Name 9212 100 Yes ProgspaceFilter 9213 9214objfile /build/test frame-filters: 9215 Priority Enabled Name 9216 999 No BuildProgramFilter 9217@end smallexample 9218@end table 9219 9220@node Source 9221@chapter Examining Source Files 9222 9223@value{GDBN} can print parts of your program's source, since the debugging 9224information recorded in the program tells @value{GDBN} what source files were 9225used to build it. When your program stops, @value{GDBN} spontaneously prints 9226the line where it stopped. Likewise, when you select a stack frame 9227(@pxref{Selection, ,Selecting a Frame}), @value{GDBN} prints the line where 9228execution in that frame has stopped. You can print other portions of 9229source files by explicit command. 9230 9231If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may 9232prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using 9233@value{GDBN} under @sc{gnu} Emacs}. 9234 9235@menu 9236* List:: Printing source lines 9237* Location Specifications:: How to specify code locations 9238* Edit:: Editing source files 9239* Search:: Searching source files 9240* Source Path:: Specifying source directories 9241* Machine Code:: Source and machine code 9242* Disable Reading Source:: Disable Reading Source Code 9243@end menu 9244 9245@node List 9246@section Printing Source Lines 9247 9248@kindex list 9249@kindex l @r{(@code{list})} 9250To print lines from a source file, use the @code{list} command 9251(abbreviated @code{l}). By default, ten lines are printed. 9252There are several ways to specify what part of the file you want to 9253print; see @ref{Location Specifications}, for the full list. 9254 9255Here are the forms of the @code{list} command most commonly used: 9256 9257@table @code 9258@item list @var{linenum} 9259Print lines centered around line number @var{linenum} in the 9260current source file. 9261 9262@item list @var{function} 9263Print lines centered around the beginning of function 9264@var{function}. 9265 9266@item list 9267Print more lines. If the last lines printed were printed with a 9268@code{list} command, this prints lines following the last lines 9269printed; however, if the last line printed was a solitary line printed 9270as part of displaying a stack frame (@pxref{Stack, ,Examining the 9271Stack}), this prints lines centered around that line. If no 9272@code{list} command has been used and no solitary line was printed, 9273it prints the lines around the function @code{main}. 9274 9275@item list + 9276Same as using with no arguments. 9277 9278@item list - 9279Print lines just before the lines last printed. 9280 9281@item list . 9282Print the lines surrounding the point of execution within the 9283currently selected frame. If the inferior is not running, print lines 9284around the start of the main function instead. 9285@end table 9286 9287@cindex @code{list}, how many lines to display 9288By default, @value{GDBN} prints ten source lines with any of these forms of 9289the @code{list} command. You can change this using @code{set listsize}: 9290 9291@table @code 9292@kindex set listsize 9293@item set listsize @var{count} 9294@itemx set listsize unlimited 9295Make the @code{list} command display @var{count} source lines (unless 9296the @code{list} argument explicitly specifies some other number). 9297Setting @var{count} to @code{unlimited} or 0 means there's no limit. 9298 9299@kindex show listsize 9300@item show listsize 9301Display the number of lines that @code{list} prints. 9302@end table 9303 9304Repeating a @code{list} command with @key{RET} discards the argument, 9305so it is equivalent to typing just @code{list}. This is more useful 9306than listing the same lines again. An exception is made for an 9307argument of @samp{-}; that argument is preserved in repetition so that 9308each repetition moves up in the source file. 9309 9310In general, the @code{list} command expects you to supply zero, one or 9311two location specs. These location specs are interpreted to resolve 9312to source code lines; there are several ways of writing them 9313(@pxref{Location Specifications}), but the effect is always to resolve 9314to some source lines to display. 9315 9316Here is a complete description of the possible arguments for @code{list}: 9317 9318@table @code 9319@item list @var{locspec} 9320Print lines centered around the line or lines of all the code 9321locations that result from resolving @var{locspec}. 9322 9323@item list @var{first},@var{last} 9324Print lines from @var{first} to @var{last}. Both arguments are 9325location specs. When a @code{list} command has two location specs, 9326and the source file of the second location spec is omitted, this 9327refers to the same source file as the first location spec. If either 9328@var{first} or @var{last} resolve to more than one source line in the 9329program, then the list command shows the list of resolved source 9330lines and does not proceed with the source code listing. 9331 9332@item list ,@var{last} 9333Print lines ending with @var{last}. 9334 9335Likewise, if @var{last} resolves to more than one source line in the 9336program, then the list command prints the list of resolved source 9337lines and does not proceed with the source code listing. 9338 9339@item list @var{first}, 9340Print lines starting with @var{first}. 9341 9342@item list + 9343Print lines just after the lines last printed. 9344 9345@item list - 9346Print lines just before the lines last printed. 9347 9348@item list 9349As described in the preceding table. 9350@end table 9351 9352@node Location Specifications 9353@section Location Specifications 9354@cindex specifying location 9355@cindex locspec 9356@cindex source location 9357@cindex code location 9358 9359@cindex location spec 9360Several @value{GDBN} commands accept arguments that specify a location 9361or locations of your program's code. Many times locations are 9362specified using a source line number, but they can also be specified 9363by a function name, an address, a label, etc. The different 9364forms of specifying a location that @value{GDBN} recognizes are 9365collectively known as forms of @dfn{location specification}, or 9366@dfn{location spec}. This section documents the forms of specifying 9367locations that @value{GDBN} recognizes. 9368 9369@cindex location resolution 9370@cindex resolution of location spec 9371When you specify a location, @value{GDBN} needs to find the place in 9372your program, known as @dfn{code location}, that corresponds to the 9373given location spec. We call this process of finding actual code 9374locations corresponding to a location spec @dfn{location resolution}. 9375 9376A concrete code location in your program is uniquely identifiable by a 9377set of several attributes: its source line number, the name of its 9378source file, the fully-qualified and prototyped function in which it 9379is defined, and an instruction address. Because each inferior has its 9380own address space, the inferior number is also a necessary part of 9381these attributes. 9382 9383By contrast, location specs you type will many times omit some of 9384these attributes. For example, it is customary to specify just the 9385source line number to mean a line in the current source file, or 9386specify just the basename of the file, omitting its directories. In 9387other words, a location spec is usually incomplete, a kind of 9388blueprint, and @value{GDBN} needs to complete the missing attributes 9389by using the implied defaults, and by considering the source code and 9390the debug information available to it. This is what location 9391resolution is about. 9392 9393The resolution of an incomplete location spec can produce more than a 9394single code location, if the spec doesn't allow distinguishing between 9395them. Here are some examples of situations that result in a location 9396spec matching multiple code locations in your program: 9397 9398@itemize @bullet 9399@item 9400The location spec specifies a function name, and there are several 9401functions in the program which have that name. (To distinguish 9402between them, you can specify a fully-qualified and prototyped 9403function name, such as @code{A::func(int)} instead of just 9404@code{func}.) 9405 9406@item 9407The location spec specifies a source file name, and there are several 9408source files in the program that share the same name, for example 9409several files with the same basename in different subdirectories. (To 9410distinguish between them, specify enough leading directories with the 9411file name.) 9412 9413@item 9414For a C@t{++} constructor, the @value{NGCC} compiler generates several 9415instances of the function body, used in different cases, but their 9416source-level names are identical. 9417 9418@item 9419For a C@t{++} template function, a given line in the function can 9420correspond to any number of instantiations. 9421 9422@item 9423For an inlined function, a given source line can correspond to several 9424actual code locations with that function's inlined code. 9425@end itemize 9426 9427Resolution of a location spec can also fail to produce a complete code 9428location, or even fail to produce any code location. Here are some 9429examples of such situations: 9430 9431@itemize @bullet 9432@item 9433Some parts of the program lack detailed enough debug info, so the 9434resolved code location lacks some attributes, like source file name 9435and line number, leaving just the instruction address and perhaps also 9436a function name. Such an incomplete code location is only usable in 9437contexts that work with addresses and/or function names. Some 9438commands can only work with complete code locations. 9439 9440@item 9441The location spec specifies a function name, and there are no 9442functions in the program by that name, or they only exist in a 9443yet-unloaded shared library. 9444 9445@item 9446The location spec specifies a source file name, and there are no 9447source files in the program by that name, or they only exist in a 9448yet-unloaded shared library. 9449 9450@item 9451The location spec specifies both a source file name and a source line 9452number, and even though there are source files in the program that 9453match the file name, none of those files has the specified line 9454number. 9455@end itemize 9456 9457Locations may be specified using three different formats: linespec 9458locations, explicit locations, or address locations. The following 9459subsections describe these formats. 9460 9461@menu 9462* Linespec Locations:: Linespec locations 9463* Explicit Locations:: Explicit locations 9464* Address Locations:: Address locations 9465@end menu 9466 9467@node Linespec Locations 9468@subsection Linespec Locations 9469@cindex linespec locations 9470 9471A @dfn{linespec} is a colon-separated list of source location parameters such 9472as file name, function name, etc. Here are all the different ways of 9473specifying a linespec: 9474 9475@table @code 9476@item @var{linenum} 9477Specifies the line number @var{linenum} of the current source file. 9478 9479@item -@var{offset} 9480@itemx +@var{offset} 9481Specifies the line @var{offset} lines before or after the @dfn{current 9482line}. For the @code{list} command, the current line is the last one 9483printed; for the breakpoint commands, this is the line at which 9484execution stopped in the currently selected @dfn{stack frame} 9485(@pxref{Frames, ,Frames}, for a description of stack frames.) When 9486used as the second of the two linespecs in a @code{list} command, 9487this specifies the line @var{offset} lines up or down from the first 9488linespec. 9489 9490@item @var{filename}:@var{linenum} 9491Specifies the line @var{linenum} in the source file @var{filename}. 9492If @var{filename} is a relative file name, then it will match any 9493source file name with the same trailing components. For example, if 9494@var{filename} is @samp{gcc/expr.c}, then it will match source file 9495name of @file{/build/trunk/gcc/expr.c}, but not 9496@file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}. 9497 9498@item @var{function} 9499Specifies the line that begins the body of the function @var{function}. 9500For example, in C, this is the line with the open brace. 9501 9502By default, in C@t{++} and Ada, @var{function} is interpreted as 9503specifying all functions named @var{function} in all scopes. For 9504C@t{++}, this means in all namespaces and classes. For Ada, this 9505means in all packages. 9506 9507For example, assuming a program with C@t{++} symbols named 9508@code{A::B::func} and @code{B::func}, both commands @w{@kbd{break 9509func}} and @w{@kbd{break B::func}} set a breakpoint on both symbols. 9510 9511Commands that accept a linespec let you override this with the 9512@code{-qualified} option. For example, @w{@kbd{break -qualified 9513func}} sets a breakpoint on a free-function named @code{func} ignoring 9514any C@t{++} class methods and namespace functions called @code{func}. 9515 9516@xref{Explicit Locations}. 9517 9518@item @var{function}:@var{label} 9519Specifies the line where @var{label} appears in @var{function}. 9520 9521@item @var{filename}:@var{function} 9522Specifies the line that begins the body of the function @var{function} 9523in the file @var{filename}. You only need the file name with a 9524function name to avoid ambiguity when there are identically named 9525functions in different source files. 9526 9527@item @var{label} 9528Specifies the line at which the label named @var{label} appears 9529in the function corresponding to the currently selected stack frame. 9530If there is no current selected stack frame (for instance, if the inferior 9531is not running), then @value{GDBN} will not search for a label. 9532 9533@cindex breakpoint at static probe point 9534@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name} 9535The @sc{gnu}/Linux tool @code{SystemTap} provides a way for 9536applications to embed static probes. @xref{Static Probe Points}, for more 9537information on finding and using static probes. This form of linespec 9538specifies the location of such a static probe. 9539 9540If @var{objfile} is given, only probes coming from that shared library 9541or executable matching @var{objfile} as a regular expression are considered. 9542If @var{provider} is given, then only probes from that provider are considered. 9543If several probes match the spec, @value{GDBN} will insert a breakpoint at 9544each one of those probes. 9545@end table 9546 9547@node Explicit Locations 9548@subsection Explicit Locations 9549@cindex explicit locations 9550 9551@dfn{Explicit locations} allow the user to directly specify the source 9552location's parameters using option-value pairs. 9553 9554Explicit locations are useful when several functions, labels, or 9555file names have the same name (base name for files) in the program's 9556sources. In these cases, explicit locations point to the source 9557line you meant more accurately and unambiguously. Also, using 9558explicit locations might be faster in large programs. 9559 9560For example, the linespec @samp{foo:bar} may refer to a function @code{bar} 9561defined in the file named @file{foo} or the label @code{bar} in a function 9562named @code{foo}. @value{GDBN} must search either the file system or 9563the symbol table to know. 9564 9565The list of valid explicit location options is summarized in the 9566following table: 9567 9568@table @code 9569@item -source @var{filename} 9570The value specifies the source file name. To differentiate between 9571files with the same base name, prepend as many directories as is necessary 9572to uniquely identify the desired file, e.g., @file{foo/bar/baz.c}. Otherwise 9573@value{GDBN} will use the first file it finds with the given base 9574name. This option requires the use of either @code{-function} or @code{-line}. 9575 9576@item -function @var{function} 9577The value specifies the name of a function. Operations 9578on function locations unmodified by other options (such as @code{-label} 9579or @code{-line}) refer to the line that begins the body of the function. 9580In C, for example, this is the line with the open brace. 9581 9582By default, in C@t{++} and Ada, @var{function} is interpreted as 9583specifying all functions named @var{function} in all scopes. For 9584C@t{++}, this means in all namespaces and classes. For Ada, this 9585means in all packages. 9586 9587For example, assuming a program with C@t{++} symbols named 9588@code{A::B::func} and @code{B::func}, both commands @w{@kbd{break 9589-function func}} and @w{@kbd{break -function B::func}} set a 9590breakpoint on both symbols. 9591 9592You can use the @kbd{-qualified} flag to override this (see below). 9593 9594@item -qualified 9595 9596This flag makes @value{GDBN} interpret a function name specified with 9597@kbd{-function} as a complete fully-qualified name. 9598 9599For example, assuming a C@t{++} program with symbols named 9600@code{A::B::func} and @code{B::func}, the @w{@kbd{break -qualified 9601-function B::func}} command sets a breakpoint on @code{B::func}, only. 9602 9603(Note: the @kbd{-qualified} option can precede a linespec as well 9604(@pxref{Linespec Locations}), so the particular example above could be 9605simplified as @w{@kbd{break -qualified B::func}}.) 9606 9607@item -label @var{label} 9608The value specifies the name of a label. When the function 9609name is not specified, the label is searched in the function of the currently 9610selected stack frame. 9611 9612@item -line @var{number} 9613The value specifies a line offset for the location. The offset may either 9614be absolute (@code{-line 3}) or relative (@code{-line +3}), depending on 9615the command. When specified without any other options, the line offset is 9616relative to the current line. 9617@end table 9618 9619Explicit location options may be abbreviated by omitting any non-unique 9620trailing characters from the option name, e.g., @w{@kbd{break -s main.c -li 3}}. 9621 9622@node Address Locations 9623@subsection Address Locations 9624@cindex address locations 9625 9626@dfn{Address locations} indicate a specific program address. They have 9627the generalized form *@var{address}. 9628 9629For line-oriented commands, such as @code{list} and @code{edit}, this 9630specifies a source line that contains @var{address}. For @code{break} and 9631other breakpoint-oriented commands, this can be used to set breakpoints in 9632parts of your program which do not have debugging information or 9633source files. 9634 9635Here @var{address} may be any expression valid in the current working 9636language (@pxref{Languages, working language}) that specifies a code 9637address. In addition, as a convenience, @value{GDBN} extends the 9638semantics of expressions used in locations to cover several situations 9639that frequently occur during debugging. Here are the various forms 9640of @var{address}: 9641 9642@table @code 9643@item @var{expression} 9644Any expression valid in the current working language. 9645 9646@item @var{funcaddr} 9647An address of a function or procedure derived from its name. In C, 9648C@t{++}, Objective-C, Fortran, minimal, and assembly, this is 9649simply the function's name @var{function} (and actually a special case 9650of a valid expression). In Pascal and Modula-2, this is 9651@code{&@var{function}}. In Ada, this is @code{@var{function}'Address} 9652(although the Pascal form also works). 9653 9654This form specifies the address of the function's first instruction, 9655before the stack frame and arguments have been set up. 9656 9657@item '@var{filename}':@var{funcaddr} 9658Like @var{funcaddr} above, but also specifies the name of the source 9659file explicitly. This is useful if the name of the function does not 9660specify the function unambiguously, e.g., if there are several 9661functions with identical names in different source files. 9662@end table 9663 9664@node Edit 9665@section Editing Source Files 9666@cindex editing source files 9667 9668@kindex edit 9669@kindex e @r{(@code{edit})} 9670To edit the lines in a source file, use the @code{edit} command. 9671The editing program of your choice 9672is invoked with the current line set to 9673the active line in the program. 9674Alternatively, there are several ways to specify what part of the file you 9675want to print if you want to see other parts of the program: 9676 9677@table @code 9678@item edit @var{locspec} 9679Edit the source file of the code location that results from resolving 9680@code{locspec}. Editing starts at the source file and source line 9681@code{locspec} resolves to. 9682@xref{Location Specifications}, for all the possible forms of the 9683@var{locspec} argument. 9684 9685If @code{locspec} resolves to more than one source line in your 9686program, then the command prints the list of resolved source lines and 9687does not proceed with the editing. 9688 9689Here are the forms of the @code{edit} command most commonly used: 9690 9691@table @code 9692@item edit @var{number} 9693Edit the current source file with @var{number} as the active line number. 9694 9695@item edit @var{function} 9696Edit the file containing @var{function} at the beginning of its definition. 9697@end table 9698 9699@end table 9700 9701@subsection Choosing your Editor 9702You can customize @value{GDBN} to use any editor you want 9703@footnote{ 9704The only restriction is that your editor (say @code{ex}), recognizes the 9705following command-line syntax: 9706@smallexample 9707ex +@var{number} file 9708@end smallexample 9709The optional numeric value +@var{number} specifies the number of the line in 9710the file where to start editing.}. 9711By default, it is @file{@value{EDITOR}}, but you can change this 9712by setting the environment variable @env{EDITOR} before using 9713@value{GDBN}. For example, to configure @value{GDBN} to use the 9714@code{vi} editor, you could use these commands with the @code{sh} shell: 9715@smallexample 9716EDITOR=/usr/bin/vi 9717export EDITOR 9718gdb @dots{} 9719@end smallexample 9720or in the @code{csh} shell, 9721@smallexample 9722setenv EDITOR /usr/bin/vi 9723gdb @dots{} 9724@end smallexample 9725 9726@node Search 9727@section Searching Source Files 9728@cindex searching source files 9729 9730There are two commands for searching through the current source file for a 9731regular expression. 9732 9733@table @code 9734@kindex search 9735@kindex forward-search 9736@kindex fo @r{(@code{forward-search})} 9737@item forward-search @var{regexp} 9738@itemx search @var{regexp} 9739The command @samp{forward-search @var{regexp}} checks each line, 9740starting with the one following the last line listed, for a match for 9741@var{regexp}. It lists the line that is found. You can use the 9742synonym @samp{search @var{regexp}} or abbreviate the command name as 9743@code{fo}. 9744 9745@kindex reverse-search 9746@item reverse-search @var{regexp} 9747The command @samp{reverse-search @var{regexp}} checks each line, starting 9748with the one before the last line listed and going backward, for a match 9749for @var{regexp}. It lists the line that is found. You can abbreviate 9750this command as @code{rev}. 9751@end table 9752 9753@node Source Path 9754@section Specifying Source Directories 9755 9756@cindex source path 9757@cindex directories for source files 9758Executable programs sometimes do not record the directories of the source 9759files from which they were compiled, just the names. Even when they do, 9760the directories could be moved between the compilation and your debugging 9761session. @value{GDBN} has a list of directories to search for source files; 9762this is called the @dfn{source path}. Each time @value{GDBN} wants a source file, 9763it tries all the directories in the list, in the order they are present 9764in the list, until it finds a file with the desired name. 9765 9766For example, suppose an executable references the file 9767@file{/usr/src/foo-1.0/lib/foo.c}, does not record a compilation 9768directory, and the @dfn{source path} is @file{/mnt/cross}. 9769@value{GDBN} would look for the source file in the following 9770locations: 9771 9772@enumerate 9773 9774@item @file{/usr/src/foo-1.0/lib/foo.c} 9775@item @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} 9776@item @file{/mnt/cross/foo.c} 9777 9778@end enumerate 9779 9780If the source file is not present at any of the above locations then 9781an error is printed. @value{GDBN} does not look up the parts of the 9782source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}. 9783Likewise, the subdirectories of the source path are not searched: if 9784the source path is @file{/mnt/cross}, and the binary refers to 9785@file{foo.c}, @value{GDBN} would not find it under 9786@file{/mnt/cross/usr/src/foo-1.0/lib}. 9787 9788Plain file names, relative file names with leading directories, file 9789names containing dots, etc.@: are all treated as described above, 9790except that non-absolute file names are not looked up literally. If 9791the @dfn{source path} is @file{/mnt/cross}, the source file is 9792recorded as @file{../lib/foo.c}, and no compilation directory is 9793recorded, then @value{GDBN} will search in the following locations: 9794 9795@enumerate 9796 9797@item @file{/mnt/cross/../lib/foo.c} 9798@item @file{/mnt/cross/foo.c} 9799 9800@end enumerate 9801 9802@kindex cdir 9803@kindex cwd 9804@vindex $cdir@r{, convenience variable} 9805@vindex $cwd@r{, convenience variable} 9806@cindex compilation directory 9807@cindex current directory 9808@cindex working directory 9809@cindex directory, current 9810@cindex directory, compilation 9811The @dfn{source path} will always include two special entries 9812@samp{$cdir} and @samp{$cwd}, these refer to the compilation directory 9813(if one is recorded) and the current working directory respectively. 9814 9815@samp{$cdir} causes @value{GDBN} to search within the compilation 9816directory, if one is recorded in the debug information. If no 9817compilation directory is recorded in the debug information then 9818@samp{$cdir} is ignored. 9819 9820@samp{$cwd} is not the same as @samp{.}---the former tracks the 9821current working directory as it changes during your @value{GDBN} 9822session, while the latter is immediately expanded to the current 9823directory at the time you add an entry to the source path. 9824 9825If a compilation directory is recorded in the debug information, and 9826@value{GDBN} has not found the source file after the first search 9827using @dfn{source path}, then @value{GDBN} will combine the 9828compilation directory and the filename, and then search for the source 9829file again using the @dfn{source path}. 9830 9831For example, if the executable records the source file as 9832@file{/usr/src/foo-1.0/lib/foo.c}, the compilation directory is 9833recorded as @file{/project/build}, and the @dfn{source path} is 9834@file{/mnt/cross:$cdir:$cwd} while the current working directory of 9835the @value{GDBN} session is @file{/home/user}, then @value{GDBN} will 9836search for the source file in the following locations: 9837 9838@enumerate 9839 9840@item @file{/usr/src/foo-1.0/lib/foo.c} 9841@item @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} 9842@item @file{/project/build/usr/src/foo-1.0/lib/foo.c} 9843@item @file{/home/user/usr/src/foo-1.0/lib/foo.c} 9844@item @file{/mnt/cross/project/build/usr/src/foo-1.0/lib/foo.c} 9845@item @file{/project/build/project/build/usr/src/foo-1.0/lib/foo.c} 9846@item @file{/home/user/project/build/usr/src/foo-1.0/lib/foo.c} 9847@item @file{/mnt/cross/foo.c} 9848@item @file{/project/build/foo.c} 9849@item @file{/home/user/foo.c} 9850 9851@end enumerate 9852 9853If the file name in the previous example had been recorded in the 9854executable as a relative path rather than an absolute path, then the 9855first look up would not have occurred, but all of the remaining steps 9856would be similar. 9857 9858When searching for source files on MS-DOS and MS-Windows, where 9859absolute paths start with a drive letter (e.g.@: 9860@file{C:/project/foo.c}), @value{GDBN} will remove the drive letter 9861from the file name before appending it to a search directory from 9862@dfn{source path}; for instance if the executable references the 9863source file @file{C:/project/foo.c} and @dfn{source path} is set to 9864@file{D:/mnt/cross}, then @value{GDBN} will search in the following 9865locations for the source file: 9866 9867@enumerate 9868 9869@item @file{C:/project/foo.c} 9870@item @file{D:/mnt/cross/project/foo.c} 9871@item @file{D:/mnt/cross/foo.c} 9872 9873@end enumerate 9874 9875Note that the executable search path is @emph{not} used to locate the 9876source files. 9877 9878Whenever you reset or rearrange the source path, @value{GDBN} clears out 9879any information it has cached about where source files are found and where 9880each line is in the file. 9881 9882@kindex directory 9883@kindex dir 9884When you start @value{GDBN}, its source path includes only @samp{$cdir} 9885and @samp{$cwd}, in that order. 9886To add other directories, use the @code{directory} command. 9887 9888The search path is used to find both program source files and @value{GDBN} 9889script files (read using the @samp{-command} option and @samp{source} command). 9890 9891In addition to the source path, @value{GDBN} provides a set of commands 9892that manage a list of source path substitution rules. A @dfn{substitution 9893rule} specifies how to rewrite source directories stored in the program's 9894debug information in case the sources were moved to a different 9895directory between compilation and debugging. A rule is made of 9896two strings, the first specifying what needs to be rewritten in 9897the path, and the second specifying how it should be rewritten. 9898In @ref{set substitute-path}, we name these two parts @var{from} and 9899@var{to} respectively. @value{GDBN} does a simple string replacement 9900of @var{from} with @var{to} at the start of the directory part of the 9901source file name, and uses that result instead of the original file 9902name to look up the sources. 9903 9904Using the previous example, suppose the @file{foo-1.0} tree has been 9905moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell 9906@value{GDBN} to replace @file{/usr/src} in all source path names with 9907@file{/mnt/cross}. The first lookup will then be 9908@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location 9909of @file{/usr/src/foo-1.0/lib/foo.c}. To define a source path 9910substitution rule, use the @code{set substitute-path} command 9911(@pxref{set substitute-path}). 9912 9913To avoid unexpected substitution results, a rule is applied only if the 9914@var{from} part of the directory name ends at a directory separator. 9915For instance, a rule substituting @file{/usr/source} into 9916@file{/mnt/cross} will be applied to @file{/usr/source/foo-1.0} but 9917not to @file{/usr/sourceware/foo-2.0}. And because the substitution 9918is applied only at the beginning of the directory name, this rule will 9919not be applied to @file{/root/usr/source/baz.c} either. 9920 9921In many cases, you can achieve the same result using the @code{directory} 9922command. However, @code{set substitute-path} can be more efficient in 9923the case where the sources are organized in a complex tree with multiple 9924subdirectories. With the @code{directory} command, you need to add each 9925subdirectory of your project. If you moved the entire tree while 9926preserving its internal organization, then @code{set substitute-path} 9927allows you to direct the debugger to all the sources with one single 9928command. 9929 9930@code{set substitute-path} is also more than just a shortcut command. 9931The source path is only used if the file at the original location no 9932longer exists. On the other hand, @code{set substitute-path} modifies 9933the debugger behavior to look at the rewritten location instead. So, if 9934for any reason a source file that is not relevant to your executable is 9935located at the original location, a substitution rule is the only 9936method available to point @value{GDBN} at the new location. 9937 9938@cindex @samp{--with-relocated-sources} 9939@cindex default source path substitution 9940You can configure a default source path substitution rule by 9941configuring @value{GDBN} with the 9942@samp{--with-relocated-sources=@var{dir}} option. The @var{dir} 9943should be the name of a directory under @value{GDBN}'s configured 9944prefix (set with @samp{--prefix} or @samp{--exec-prefix}), and 9945directory names in debug information under @var{dir} will be adjusted 9946automatically if the installed @value{GDBN} is moved to a new 9947location. This is useful if @value{GDBN}, libraries or executables 9948with debug information and corresponding source code are being moved 9949together. 9950 9951@table @code 9952@item directory @var{dirname} @dots{} 9953@item dir @var{dirname} @dots{} 9954Add directory @var{dirname} to the front of the source path. Several 9955directory names may be given to this command, separated by @samp{:} 9956(@samp{;} on MS-DOS and MS-Windows, where @samp{:} usually appears as 9957part of absolute file names) or 9958whitespace. You may specify a directory that is already in the source 9959path; this moves it forward, so @value{GDBN} searches it sooner. 9960 9961The special strings @samp{$cdir} (to refer to the compilation 9962directory, if one is recorded), and @samp{$cwd} (to refer to the 9963current working directory) can also be included in the list of 9964directories @var{dirname}. Though these will already be in the source 9965path they will be moved forward in the list so @value{GDBN} searches 9966them sooner. 9967 9968@item directory 9969Reset the source path to its default value (@samp{$cdir:$cwd} on Unix systems). This requires confirmation. 9970 9971@c RET-repeat for @code{directory} is explicitly disabled, but since 9972@c repeating it would be a no-op we do not say that. (thanks to RMS) 9973 9974@item set directories @var{path-list} 9975@kindex set directories 9976Set the source path to @var{path-list}. 9977@samp{$cdir:$cwd} are added if missing. 9978 9979@item show directories 9980@kindex show directories 9981Print the source path: show which directories it contains. 9982 9983@anchor{set substitute-path} 9984@item set substitute-path @var{from} @var{to} 9985@kindex set substitute-path 9986Define a source path substitution rule, and add it at the end of the 9987current list of existing substitution rules. If a rule with the same 9988@var{from} was already defined, then the old rule is also deleted. 9989 9990For example, if the file @file{/foo/bar/baz.c} was moved to 9991@file{/mnt/cross/baz.c}, then the command 9992 9993@smallexample 9994(@value{GDBP}) set substitute-path /foo/bar /mnt/cross 9995@end smallexample 9996 9997@noindent 9998will tell @value{GDBN} to replace @samp{/foo/bar} with 9999@samp{/mnt/cross}, which will allow @value{GDBN} to find the file 10000@file{baz.c} even though it was moved. 10001 10002In the case when more than one substitution rule have been defined, 10003the rules are evaluated one by one in the order where they have been 10004defined. The first one matching, if any, is selected to perform 10005the substitution. 10006 10007For instance, if we had entered the following commands: 10008 10009@smallexample 10010(@value{GDBP}) set substitute-path /usr/src/include /mnt/include 10011(@value{GDBP}) set substitute-path /usr/src /mnt/src 10012@end smallexample 10013 10014@noindent 10015@value{GDBN} would then rewrite @file{/usr/src/include/defs.h} into 10016@file{/mnt/include/defs.h} by using the first rule. However, it would 10017use the second rule to rewrite @file{/usr/src/lib/foo.c} into 10018@file{/mnt/src/lib/foo.c}. 10019 10020 10021@item unset substitute-path [path] 10022@kindex unset substitute-path 10023If a path is specified, search the current list of substitution rules 10024for a rule that would rewrite that path. Delete that rule if found. 10025A warning is emitted by the debugger if no rule could be found. 10026 10027If no path is specified, then all substitution rules are deleted. 10028 10029@item show substitute-path [path] 10030@kindex show substitute-path 10031If a path is specified, then print the source path substitution rule 10032which would rewrite that path, if any. 10033 10034If no path is specified, then print all existing source path substitution 10035rules. 10036 10037@end table 10038 10039If your source path is cluttered with directories that are no longer of 10040interest, @value{GDBN} may sometimes cause confusion by finding the wrong 10041versions of source. You can correct the situation as follows: 10042 10043@enumerate 10044@item 10045Use @code{directory} with no argument to reset the source path to its default value. 10046 10047@item 10048Use @code{directory} with suitable arguments to reinstall the 10049directories you want in the source path. You can add all the 10050directories in one command. 10051@end enumerate 10052 10053@node Machine Code 10054@section Source and Machine Code 10055@cindex source line and its code address 10056 10057You can use the command @code{info line} to map source lines to program 10058addresses (and vice versa), and the command @code{disassemble} to display 10059a range of addresses as machine instructions. You can use the command 10060@code{set disassemble-next-line} to set whether to disassemble next 10061source line when execution stops. When run under @sc{gnu} Emacs 10062mode, the @code{info line} command causes the arrow to point to the 10063line specified. Also, @code{info line} prints addresses in symbolic form as 10064well as hex. 10065 10066@table @code 10067@kindex info line 10068@item info line 10069@itemx info line @var{locspec} 10070Print the starting and ending addresses of the compiled code for the 10071source lines of the code locations that result from resolving 10072@var{locspec}. @xref{Location Specifications}, for the various forms 10073of @var{locspec}. 10074With no @var{locspec}, information about the current source line is 10075printed. 10076@end table 10077 10078For example, we can use @code{info line} to discover the location of 10079the object code for the first line of function 10080@code{m4_changequote}: 10081 10082@smallexample 10083(@value{GDBP}) info line m4_changequote 10084Line 895 of "builtin.c" starts at pc 0x634c <m4_changequote> and \ 10085 ends at 0x6350 <m4_changequote+4>. 10086@end smallexample 10087 10088@noindent 10089@cindex code address and its source line 10090We can also inquire, using @code{*@var{addr}} as the form for 10091@var{locspec}, what source line covers a particular address 10092@var{addr}: 10093@smallexample 10094(@value{GDBP}) info line *0x63ff 10095Line 926 of "builtin.c" starts at pc 0x63e4 <m4_changequote+152> and \ 10096 ends at 0x6404 <m4_changequote+184>. 10097@end smallexample 10098 10099@cindex @code{$_} and @code{info line} 10100@cindex @code{x} command, default address 10101@kindex x@r{(examine), and} info line 10102After @code{info line}, the default address for the @code{x} command 10103is changed to the starting address of the line, so that @samp{x/i} is 10104sufficient to begin examining the machine code (@pxref{Memory, 10105,Examining Memory}). Also, this address is saved as the value of the 10106convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience 10107Variables}). 10108 10109@cindex info line, repeated calls 10110After @code{info line}, using @code{info line} again without 10111specifying a location will display information about the next source 10112line. 10113 10114@anchor{disassemble} 10115@table @code 10116@kindex disassemble 10117@cindex assembly instructions 10118@cindex instructions, assembly 10119@cindex machine instructions 10120@cindex listing machine instructions 10121@item disassemble 10122@itemx disassemble /m 10123@itemx disassemble /s 10124@itemx disassemble /r 10125@itemx disassemble /b 10126This specialized command dumps a range of memory as machine 10127instructions. It can also print mixed source+disassembly by specifying 10128the @code{/m} or @code{/s} modifier and print the raw instructions in 10129hex as well as in symbolic form by specifying the @code{/r} or @code{/b} 10130modifier. 10131 10132Only one of @code{/m} and @code{/s} can be used, attempting to use 10133both flag will give an error. 10134 10135Only one of @code{/r} and @code{/b} can be used, attempting to use 10136both flag will give an error. 10137 10138The default memory range is the function surrounding the program 10139counter of the selected frame. A single argument to this command is a 10140program counter value; @value{GDBN} dumps the function surrounding 10141this value. When two arguments are given, they should be separated by 10142a comma, possibly surrounded by whitespace. The arguments specify a 10143range of addresses to dump, in one of two forms: 10144 10145@table @code 10146@item @var{start},@var{end} 10147the addresses from @var{start} (inclusive) to @var{end} (exclusive) 10148@item @var{start},+@var{length} 10149the addresses from @var{start} (inclusive) to 10150@code{@var{start}+@var{length}} (exclusive). 10151@end table 10152 10153@noindent 10154When 2 arguments are specified, the name of the function is also 10155printed (since there could be several functions in the given range). 10156 10157The argument(s) can be any expression yielding a numeric value, such as 10158@samp{0x32c4}, @samp{&main+10} or @samp{$pc - 8}. 10159 10160If the range of memory being disassembled contains current program counter, 10161the instruction at that location is shown with a @code{=>} marker. 10162@end table 10163 10164The following example shows the disassembly of a range of addresses of 10165HP PA-RISC 2.0 code: 10166 10167@smallexample 10168(@value{GDBP}) disas 0x32c4, 0x32e4 10169Dump of assembler code from 0x32c4 to 0x32e4: 10170 0x32c4 <main+204>: addil 0,dp 10171 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 10172 0x32cc <main+212>: ldil 0x3000,r31 10173 0x32d0 <main+216>: ble 0x3f8(sr4,r31) 10174 0x32d4 <main+220>: ldo 0(r31),rp 10175 0x32d8 <main+224>: addil -0x800,dp 10176 0x32dc <main+228>: ldo 0x588(r1),r26 10177 0x32e0 <main+232>: ldil 0x3000,r31 10178End of assembler dump. 10179@end smallexample 10180 10181The following two examples are for RISC-V, and demonstrates the 10182difference between the @code{/r} and @code{/b} modifiers. First with 10183@code{/b}, the bytes of the instruction are printed, in hex, in memory 10184order: 10185 10186@smallexample 10187(@value{GDBP}) disassemble /b 0x00010150,0x0001015c 10188Dump of assembler code from 0x10150 to 0x1015c: 10189 0x00010150 <call_me+4>: 22 dc sw s0,56(sp) 10190 0x00010152 <call_me+6>: 80 00 addi s0,sp,64 10191 0x00010154 <call_me+8>: 23 26 a4 fe sw a0,-20(s0) 10192 0x00010158 <call_me+12>: 23 24 b4 fe sw a1,-24(s0) 10193End of assembler dump. 10194@end smallexample 10195 10196In contrast, with @code{/r} the bytes of the instruction are displayed 10197in the instruction order, for RISC-V this means that the bytes have been 10198swapped to little-endian order: 10199 10200@smallexample 10201(@value{GDBP}) disassemble /r 0x00010150,0x0001015c 10202Dump of assembler code from 0x10150 to 0x1015c: 10203 0x00010150 <call_me+4>: dc22 sw s0,56(sp) 10204 0x00010152 <call_me+6>: 0080 addi s0,sp,64 10205 0x00010154 <call_me+8>: fea42623 sw a0,-20(s0) 10206 0x00010158 <call_me+12>: feb42423 sw a1,-24(s0) 10207End of assembler dump. 10208@end smallexample 10209 10210Here is an example showing mixed source+assembly for Intel x86 10211with @code{/m} or @code{/s}, when the program is stopped just after 10212function prologue in a non-optimized function with no inline code. 10213 10214@smallexample 10215(@value{GDBP}) disas /m main 10216Dump of assembler code for function main: 102175 @{ 10218 0x08048330 <+0>: push %ebp 10219 0x08048331 <+1>: mov %esp,%ebp 10220 0x08048333 <+3>: sub $0x8,%esp 10221 0x08048336 <+6>: and $0xfffffff0,%esp 10222 0x08048339 <+9>: sub $0x10,%esp 10223 102246 printf ("Hello.\n"); 10225=> 0x0804833c <+12>: movl $0x8048440,(%esp) 10226 0x08048343 <+19>: call 0x8048284 <puts@@plt> 10227 102287 return 0; 102298 @} 10230 0x08048348 <+24>: mov $0x0,%eax 10231 0x0804834d <+29>: leave 10232 0x0804834e <+30>: ret 10233 10234End of assembler dump. 10235@end smallexample 10236 10237The @code{/m} option is deprecated as its output is not useful when 10238there is either inlined code or re-ordered code. 10239The @code{/s} option is the preferred choice. 10240Here is an example for AMD x86-64 showing the difference between 10241@code{/m} output and @code{/s} output. 10242This example has one inline function defined in a header file, 10243and the code is compiled with @samp{-O2} optimization. 10244Note how the @code{/m} output is missing the disassembly of 10245several instructions that are present in the @code{/s} output. 10246 10247@file{foo.h}: 10248 10249@smallexample 10250int 10251foo (int a) 10252@{ 10253 if (a < 0) 10254 return a * 2; 10255 if (a == 0) 10256 return 1; 10257 return a + 10; 10258@} 10259@end smallexample 10260 10261@file{foo.c}: 10262 10263@smallexample 10264#include "foo.h" 10265volatile int x, y; 10266int 10267main () 10268@{ 10269 x = foo (y); 10270 return 0; 10271@} 10272@end smallexample 10273 10274@smallexample 10275(@value{GDBP}) disas /m main 10276Dump of assembler code for function main: 102775 @{ 10278 102796 x = foo (y); 10280 0x0000000000400400 <+0>: mov 0x200c2e(%rip),%eax # 0x601034 <y> 10281 0x0000000000400417 <+23>: mov %eax,0x200c13(%rip) # 0x601030 <x> 10282 102837 return 0; 102848 @} 10285 0x000000000040041d <+29>: xor %eax,%eax 10286 0x000000000040041f <+31>: retq 10287 0x0000000000400420 <+32>: add %eax,%eax 10288 0x0000000000400422 <+34>: jmp 0x400417 <main+23> 10289 10290End of assembler dump. 10291(@value{GDBP}) disas /s main 10292Dump of assembler code for function main: 10293foo.c: 102945 @{ 102956 x = foo (y); 10296 0x0000000000400400 <+0>: mov 0x200c2e(%rip),%eax # 0x601034 <y> 10297 10298foo.h: 102994 if (a < 0) 10300 0x0000000000400406 <+6>: test %eax,%eax 10301 0x0000000000400408 <+8>: js 0x400420 <main+32> 10302 103036 if (a == 0) 103047 return 1; 103058 return a + 10; 10306 0x000000000040040a <+10>: lea 0xa(%rax),%edx 10307 0x000000000040040d <+13>: test %eax,%eax 10308 0x000000000040040f <+15>: mov $0x1,%eax 10309 0x0000000000400414 <+20>: cmovne %edx,%eax 10310 10311foo.c: 103126 x = foo (y); 10313 0x0000000000400417 <+23>: mov %eax,0x200c13(%rip) # 0x601030 <x> 10314 103157 return 0; 103168 @} 10317 0x000000000040041d <+29>: xor %eax,%eax 10318 0x000000000040041f <+31>: retq 10319 10320foo.h: 103215 return a * 2; 10322 0x0000000000400420 <+32>: add %eax,%eax 10323 0x0000000000400422 <+34>: jmp 0x400417 <main+23> 10324End of assembler dump. 10325@end smallexample 10326 10327Here is another example showing raw instructions in hex for AMD x86-64, 10328 10329@smallexample 10330(@value{GDBP}) disas /r 0x400281,+10 10331Dump of assembler code from 0x400281 to 0x40028b: 10332 0x0000000000400281: 38 36 cmp %dh,(%rsi) 10333 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax 10334 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx) 10335 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al 10336End of assembler dump. 10337@end smallexample 10338 10339Note that the @samp{disassemble} command's address arguments are 10340specified using expressions in your programming language 10341(@pxref{Expressions, ,Expressions}), not location specs 10342(@pxref{Location Specifications}). So, for example, if you want to 10343disassemble function @code{bar} in file @file{foo.c}, you must type 10344@samp{disassemble 'foo.c'::bar} and not @samp{disassemble foo.c:bar}. 10345 10346Some architectures have more than one commonly-used set of instruction 10347mnemonics or other syntax. 10348 10349For programs that were dynamically linked and use shared libraries, 10350instructions that call functions or branch to locations in the shared 10351libraries might show a seemingly bogus location---it's actually a 10352location of the relocation table. On some architectures, @value{GDBN} 10353might be able to resolve these to actual function names. 10354 10355@table @code 10356@kindex set disassembler-options 10357@cindex disassembler options 10358@item set disassembler-options @var{option1}[,@var{option2}@dots{}] 10359This command controls the passing of target specific information to 10360the disassembler. For a list of valid options, please refer to the 10361@code{-M}/@code{--disassembler-options} section of the @samp{objdump} 10362manual and/or the output of @kbd{objdump --help} 10363(@pxref{objdump,,objdump,binutils,The GNU Binary Utilities}). 10364The default value is the empty string. 10365 10366If it is necessary to specify more than one disassembler option, then 10367multiple options can be placed together into a comma separated list. 10368Currently this command is only supported on targets ARC, ARM, MIPS, 10369PowerPC and S/390. 10370 10371@kindex show disassembler-options 10372@item show disassembler-options 10373Show the current setting of the disassembler options. 10374@end table 10375 10376@table @code 10377@kindex set disassembly-flavor 10378@cindex Intel disassembly flavor 10379@cindex AT&T disassembly flavor 10380@item set disassembly-flavor @var{instruction-set} 10381Select the instruction set to use when disassembling the 10382program via the @code{disassemble} or @code{x/i} commands. 10383 10384Currently this command is only defined for the Intel x86 family. You 10385can set @var{instruction-set} to either @code{intel} or @code{att}. 10386The default is @code{att}, the AT&T flavor used by default by Unix 10387assemblers for x86-based targets. 10388 10389@kindex show disassembly-flavor 10390@item show disassembly-flavor 10391Show the current setting of the disassembly flavor. 10392@end table 10393 10394@table @code 10395@kindex set disassemble-next-line 10396@kindex show disassemble-next-line 10397@item set disassemble-next-line 10398@itemx show disassemble-next-line 10399Control whether or not @value{GDBN} will disassemble the next source 10400line or instruction when execution stops. If ON, @value{GDBN} will 10401display disassembly of the next source line when execution of the 10402program being debugged stops. This is @emph{in addition} to 10403displaying the source line itself, which @value{GDBN} always does if 10404possible. If the next source line cannot be displayed for some reason 10405(e.g., if @value{GDBN} cannot find the source file, or there's no line 10406info in the debug info), @value{GDBN} will display disassembly of the 10407next @emph{instruction} instead of showing the next source line. If 10408AUTO, @value{GDBN} will display disassembly of next instruction only 10409if the source line cannot be displayed. This setting causes 10410@value{GDBN} to display some feedback when you step through a function 10411with no line info or whose source file is unavailable. The default is 10412OFF, which means never display the disassembly of the next line or 10413instruction. 10414@end table 10415 10416@node Disable Reading Source 10417@section Disable Reading Source Code 10418@cindex source code, disable access 10419 10420In some cases it can be desirable to prevent @value{GDBN} from 10421accessing source code files. One case where this might be desirable 10422is if the source code files are located over a slow network 10423connection. 10424 10425The following command can be used to control whether @value{GDBN} 10426should access source code files or not: 10427 10428@table @code 10429@kindex set source open 10430@kindex show source open 10431@item set source open @r{[}on@r{|}off@r{]} 10432@itemx show source open 10433When this option is @code{on}, which is the default, @value{GDBN} will 10434access source code files when needed, for example to print source 10435lines when @value{GDBN} stops, or in response to the @code{list} 10436command. 10437 10438When this option is @code{off}, @value{GDBN} will not access source 10439code files. 10440@end table 10441 10442@node Data 10443@chapter Examining Data 10444 10445@cindex printing data 10446@cindex examining data 10447@kindex print 10448@kindex inspect 10449The usual way to examine data in your program is with the @code{print} 10450command (abbreviated @code{p}), or its synonym @code{inspect}. It 10451evaluates and prints the value of an expression of the language your 10452program is written in (@pxref{Languages, ,Using @value{GDBN} with 10453Different Languages}). It may also print the expression using a 10454Python-based pretty-printer (@pxref{Pretty Printing}). 10455 10456@table @code 10457@item print [[@var{options}] --] @var{expr} 10458@itemx print [[@var{options}] --] /@var{f} @var{expr} 10459@var{expr} is an expression (in the source language). By default the 10460value of @var{expr} is printed in a format appropriate to its data type; 10461you can choose a different format by specifying @samp{/@var{f}}, where 10462@var{f} is a letter specifying the format; see @ref{Output Formats,,Output 10463Formats}. 10464 10465@anchor{print options} 10466The @code{print} command supports a number of options that allow 10467overriding relevant global print settings as set by @code{set print} 10468subcommands: 10469 10470@table @code 10471@item -address [@code{on}|@code{off}] 10472Set printing of addresses. 10473Related setting: @ref{set print address}. 10474 10475@item -array [@code{on}|@code{off}] 10476Pretty formatting of arrays. 10477Related setting: @ref{set print array}. 10478 10479@item -array-indexes [@code{on}|@code{off}] 10480Set printing of array indexes. 10481Related setting: @ref{set print array-indexes}. 10482 10483@item -characters @var{number-of-characters}|@code{elements}|@code{unlimited} 10484Set limit on string characters to print. The value @code{elements} 10485causes the limit on array elements to print to be used. The value 10486@code{unlimited} causes there to be no limit. Related setting: 10487@ref{set print characters}. 10488 10489@item -elements @var{number-of-elements}|@code{unlimited} 10490Set limit on array elements and optionally string characters to print. 10491See @ref{set print characters}, and the @code{-characters} option above 10492for when this option applies to strings. The value @code{unlimited} 10493causes there to be no limit. @xref{set print elements}, for a related 10494CLI command. 10495 10496@item -max-depth @var{depth}|@code{unlimited} 10497Set the threshold after which nested structures are replaced with 10498ellipsis. Related setting: @ref{set print max-depth}. 10499 10500@item -nibbles [@code{on}|@code{off}] 10501Set whether to print binary values in groups of four bits, known 10502as ``nibbles''. @xref{set print nibbles}. 10503 10504@item -memory-tag-violations [@code{on}|@code{off}] 10505Set printing of additional information about memory tag violations. 10506@xref{set print memory-tag-violations}. 10507 10508@item -null-stop [@code{on}|@code{off}] 10509Set printing of char arrays to stop at first null char. Related 10510setting: @ref{set print null-stop}. 10511 10512@item -object [@code{on}|@code{off}] 10513Set printing C@t{++} virtual function tables. Related setting: 10514@ref{set print object}. 10515 10516@item -pretty [@code{on}|@code{off}] 10517Set pretty formatting of structures. Related setting: @ref{set print 10518pretty}. 10519 10520@item -raw-values [@code{on}|@code{off}] 10521Set whether to print values in raw form, bypassing any 10522pretty-printers for that value. Related setting: @ref{set print 10523raw-values}. 10524 10525@item -repeats @var{number-of-repeats}|@code{unlimited} 10526Set threshold for repeated print elements. @code{unlimited} causes 10527all elements to be individually printed. Related setting: @ref{set 10528print repeats}. 10529 10530@item -static-members [@code{on}|@code{off}] 10531Set printing C@t{++} static members. Related setting: @ref{set print 10532static-members}. 10533 10534@item -symbol [@code{on}|@code{off}] 10535Set printing of symbol names when printing pointers. Related setting: 10536@ref{set print symbol}. 10537 10538@item -union [@code{on}|@code{off}] 10539Set printing of unions interior to structures. Related setting: 10540@ref{set print union}. 10541 10542@item -vtbl [@code{on}|@code{off}] 10543Set printing of C++ virtual function tables. Related setting: 10544@ref{set print vtbl}. 10545@end table 10546 10547Because the @code{print} command accepts arbitrary expressions which 10548may look like options (including abbreviations), if you specify any 10549command option, then you must use a double dash (@code{--}) to mark 10550the end of option processing. 10551 10552For example, this prints the value of the @code{-p} expression: 10553 10554@smallexample 10555(@value{GDBP}) print -p 10556@end smallexample 10557 10558While this repeats the last value in the value history (see below) 10559with the @code{-pretty} option in effect: 10560 10561@smallexample 10562(@value{GDBP}) print -p -- 10563@end smallexample 10564 10565Here is an example including both on option and an expression: 10566 10567@smallexample 10568@group 10569(@value{GDBP}) print -pretty -- *myptr 10570$1 = @{ 10571 next = 0x0, 10572 flags = @{ 10573 sweet = 1, 10574 sour = 1 10575 @}, 10576 meat = 0x54 "Pork" 10577@} 10578@end group 10579@end smallexample 10580 10581@item print [@var{options}] 10582@itemx print [@var{options}] /@var{f} 10583@cindex reprint the last value 10584If you omit @var{expr}, @value{GDBN} displays the last value again (from the 10585@dfn{value history}; @pxref{Value History, ,Value History}). This allows you to 10586conveniently inspect the same value in an alternative format. 10587@end table 10588 10589If the architecture supports memory tagging, the @code{print} command will 10590display pointer/memory tag mismatches if what is being printed is a pointer 10591or reference type. @xref{Memory Tagging}. 10592 10593A more low-level way of examining data is with the @code{x} command. 10594It examines data in memory at a specified address and prints it in a 10595specified format. @xref{Memory, ,Examining Memory}. 10596 10597If you are interested in information about types, or about how the 10598fields of a struct or a class are declared, use the @code{ptype @var{expr}} 10599command rather than @code{print}. @xref{Symbols, ,Examining the Symbol 10600Table}. 10601 10602@cindex exploring hierarchical data structures 10603@kindex explore 10604Another way of examining values of expressions and type information is 10605through the Python extension command @code{explore} (available only if 10606the @value{GDBN} build is configured with @code{--with-python}). It 10607offers an interactive way to start at the highest level (or, the most 10608abstract level) of the data type of an expression (or, the data type 10609itself) and explore all the way down to leaf scalar values/fields 10610embedded in the higher level data types. 10611 10612@table @code 10613@item explore @var{arg} 10614@var{arg} is either an expression (in the source language), or a type 10615visible in the current context of the program being debugged. 10616@end table 10617 10618The working of the @code{explore} command can be illustrated with an 10619example. If a data type @code{struct ComplexStruct} is defined in your 10620C program as 10621 10622@smallexample 10623struct SimpleStruct 10624@{ 10625 int i; 10626 double d; 10627@}; 10628 10629struct ComplexStruct 10630@{ 10631 struct SimpleStruct *ss_p; 10632 int arr[10]; 10633@}; 10634@end smallexample 10635 10636@noindent 10637followed by variable declarations as 10638 10639@smallexample 10640struct SimpleStruct ss = @{ 10, 1.11 @}; 10641struct ComplexStruct cs = @{ &ss, @{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 @} @}; 10642@end smallexample 10643 10644@noindent 10645then, the value of the variable @code{cs} can be explored using the 10646@code{explore} command as follows. 10647 10648@smallexample 10649(@value{GDBP}) explore cs 10650The value of `cs' is a struct/class of type `struct ComplexStruct' with 10651the following fields: 10652 10653 ss_p = <Enter 0 to explore this field of type `struct SimpleStruct *'> 10654 arr = <Enter 1 to explore this field of type `int [10]'> 10655 10656Enter the field number of choice: 10657@end smallexample 10658 10659@noindent 10660Since the fields of @code{cs} are not scalar values, you are being 10661prompted to chose the field you want to explore. Let's say you choose 10662the field @code{ss_p} by entering @code{0}. Then, since this field is a 10663pointer, you will be asked if it is pointing to a single value. From 10664the declaration of @code{cs} above, it is indeed pointing to a single 10665value, hence you enter @code{y}. If you enter @code{n}, then you will 10666be asked if it were pointing to an array of values, in which case this 10667field will be explored as if it were an array. 10668 10669@smallexample 10670`cs.ss_p' is a pointer to a value of type `struct SimpleStruct' 10671Continue exploring it as a pointer to a single value [y/n]: y 10672The value of `*(cs.ss_p)' is a struct/class of type `struct 10673SimpleStruct' with the following fields: 10674 10675 i = 10 .. (Value of type `int') 10676 d = 1.1100000000000001 .. (Value of type `double') 10677 10678Press enter to return to parent value: 10679@end smallexample 10680 10681@noindent 10682If the field @code{arr} of @code{cs} was chosen for exploration by 10683entering @code{1} earlier, then since it is as array, you will be 10684prompted to enter the index of the element in the array that you want 10685to explore. 10686 10687@smallexample 10688`cs.arr' is an array of `int'. 10689Enter the index of the element you want to explore in `cs.arr': 5 10690 10691`(cs.arr)[5]' is a scalar value of type `int'. 10692 10693(cs.arr)[5] = 4 10694 10695Press enter to return to parent value: 10696@end smallexample 10697 10698In general, at any stage of exploration, you can go deeper towards the 10699leaf values by responding to the prompts appropriately, or hit the 10700return key to return to the enclosing data structure (the @i{higher} 10701level data structure). 10702 10703Similar to exploring values, you can use the @code{explore} command to 10704explore types. Instead of specifying a value (which is typically a 10705variable name or an expression valid in the current context of the 10706program being debugged), you specify a type name. If you consider the 10707same example as above, your can explore the type 10708@code{struct ComplexStruct} by passing the argument 10709@code{struct ComplexStruct} to the @code{explore} command. 10710 10711@smallexample 10712(@value{GDBP}) explore struct ComplexStruct 10713@end smallexample 10714 10715@noindent 10716By responding to the prompts appropriately in the subsequent interactive 10717session, you can explore the type @code{struct ComplexStruct} in a 10718manner similar to how the value @code{cs} was explored in the above 10719example. 10720 10721The @code{explore} command also has two sub-commands, 10722@code{explore value} and @code{explore type}. The former sub-command is 10723a way to explicitly specify that value exploration of the argument is 10724being invoked, while the latter is a way to explicitly specify that type 10725exploration of the argument is being invoked. 10726 10727@table @code 10728@item explore value @var{expr} 10729@cindex explore value 10730This sub-command of @code{explore} explores the value of the 10731expression @var{expr} (if @var{expr} is an expression valid in the 10732current context of the program being debugged). The behavior of this 10733command is identical to that of the behavior of the @code{explore} 10734command being passed the argument @var{expr}. 10735 10736@item explore type @var{arg} 10737@cindex explore type 10738This sub-command of @code{explore} explores the type of @var{arg} (if 10739@var{arg} is a type visible in the current context of program being 10740debugged), or the type of the value/expression @var{arg} (if @var{arg} 10741is an expression valid in the current context of the program being 10742debugged). If @var{arg} is a type, then the behavior of this command is 10743identical to that of the @code{explore} command being passed the 10744argument @var{arg}. If @var{arg} is an expression, then the behavior of 10745this command will be identical to that of the @code{explore} command 10746being passed the type of @var{arg} as the argument. 10747@end table 10748 10749@menu 10750* Expressions:: Expressions 10751* Ambiguous Expressions:: Ambiguous Expressions 10752* Variables:: Program variables 10753* Arrays:: Artificial arrays 10754* Output Formats:: Output formats 10755* Memory:: Examining memory 10756* Memory Tagging:: Memory Tagging 10757* Auto Display:: Automatic display 10758* Print Settings:: Print settings 10759* Pretty Printing:: Python pretty printing 10760* Value History:: Value history 10761* Convenience Vars:: Convenience variables 10762* Convenience Funs:: Convenience functions 10763* Registers:: Registers 10764* Floating Point Hardware:: Floating point hardware 10765* Vector Unit:: Vector Unit 10766* OS Information:: Auxiliary data provided by operating system 10767* Memory Region Attributes:: Memory region attributes 10768* Dump/Restore Files:: Copy between memory and a file 10769* Core File Generation:: Cause a program dump its core 10770* Character Sets:: Debugging programs that use a different 10771 character set than GDB does 10772* Caching Target Data:: Data caching for targets 10773* Searching Memory:: Searching memory for a sequence of bytes 10774* Value Sizes:: Managing memory allocated for values 10775@end menu 10776 10777@node Expressions 10778@section Expressions 10779 10780@cindex expressions 10781@code{print} and many other @value{GDBN} commands accept an expression and 10782compute its value. Any kind of constant, variable or operator defined 10783by the programming language you are using is valid in an expression in 10784@value{GDBN}. This includes conditional expressions, function calls, 10785casts, and string constants. It also includes preprocessor macros, if 10786you compiled your program to include this information; see 10787@ref{Compilation}. 10788 10789@cindex arrays in expressions 10790@value{GDBN} supports array constants in expressions input by 10791the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example, 10792you can use the command @code{print @{1, 2, 3@}} to create an array 10793of three integers. If you pass an array to a function or assign it 10794to a program variable, @value{GDBN} copies the array to memory that 10795is @code{malloc}ed in the target program. 10796 10797Because C is so widespread, most of the expressions shown in examples in 10798this manual are in C. @xref{Languages, , Using @value{GDBN} with Different 10799Languages}, for information on how to use expressions in other 10800languages. 10801 10802In this section, we discuss operators that you can use in @value{GDBN} 10803expressions regardless of your programming language. 10804 10805@cindex casts, in expressions 10806Casts are supported in all languages, not just in C, because it is so 10807useful to cast a number into a pointer in order to examine a structure 10808at that address in memory. 10809@c FIXME: casts supported---Mod2 true? 10810 10811@value{GDBN} supports these operators, in addition to those common 10812to programming languages: 10813 10814@table @code 10815@item @@ 10816@samp{@@} is a binary operator for treating parts of memory as arrays. 10817@xref{Arrays, ,Artificial Arrays}, for more information. 10818 10819@item :: 10820@samp{::} allows you to specify a variable in terms of the file or 10821function where it is defined. @xref{Variables, ,Program Variables}. 10822 10823@cindex @{@var{type}@} 10824@cindex type casting memory 10825@cindex memory, viewing as typed object 10826@cindex casts, to view memory 10827@item @{@var{type}@} @var{addr} 10828Refers to an object of type @var{type} stored at address @var{addr} in 10829memory. The address @var{addr} may be any expression whose value is 10830an integer or pointer (but parentheses are required around binary 10831operators, just as in a cast). This construct is allowed regardless 10832of what kind of data is normally supposed to reside at @var{addr}. 10833@end table 10834 10835@node Ambiguous Expressions 10836@section Ambiguous Expressions 10837@cindex ambiguous expressions 10838 10839Expressions can sometimes contain some ambiguous elements. For instance, 10840some programming languages (notably Ada, C@t{++} and Objective-C) permit 10841a single function name to be defined several times, for application in 10842different contexts. This is called @dfn{overloading}. Another example 10843involving Ada is generics. A @dfn{generic package} is similar to C@t{++} 10844templates and is typically instantiated several times, resulting in 10845the same function name being defined in different contexts. 10846 10847In some cases and depending on the language, it is possible to adjust 10848the expression to remove the ambiguity. For instance in C@t{++}, you 10849can specify the signature of the function you want to break on, as in 10850@kbd{break @var{function}(@var{types})}. In Ada, using the fully 10851qualified name of your function often makes the expression unambiguous 10852as well. 10853 10854When an ambiguity that needs to be resolved is detected, the debugger 10855has the capability to display a menu of numbered choices for each 10856possibility, and then waits for the selection with the prompt @samp{>}. 10857The first option is always @samp{[0] cancel}, and typing @kbd{0 @key{RET}} 10858aborts the current command. If the command in which the expression was 10859used allows more than one choice to be selected, the next option in the 10860menu is @samp{[1] all}, and typing @kbd{1 @key{RET}} selects all possible 10861choices. 10862 10863For example, the following session excerpt shows an attempt to set a 10864breakpoint at the overloaded symbol @code{String::after}. 10865We choose three particular definitions of that function name: 10866 10867@c FIXME! This is likely to change to show arg type lists, at least 10868@smallexample 10869@group 10870(@value{GDBP}) b String::after 10871[0] cancel 10872[1] all 10873[2] file:String.cc; line number:867 10874[3] file:String.cc; line number:860 10875[4] file:String.cc; line number:875 10876[5] file:String.cc; line number:853 10877[6] file:String.cc; line number:846 10878[7] file:String.cc; line number:735 10879> 2 4 6 10880Breakpoint 1 at 0xb26c: file String.cc, line 867. 10881Breakpoint 2 at 0xb344: file String.cc, line 875. 10882Breakpoint 3 at 0xafcc: file String.cc, line 846. 10883Multiple breakpoints were set. 10884Use the "delete" command to delete unwanted 10885 breakpoints. 10886(@value{GDBP}) 10887@end group 10888@end smallexample 10889 10890@table @code 10891@kindex set multiple-symbols 10892@item set multiple-symbols @var{mode} 10893@cindex multiple-symbols menu 10894 10895This option allows you to adjust the debugger behavior when an expression 10896is ambiguous. 10897 10898By default, @var{mode} is set to @code{all}. If the command with which 10899the expression is used allows more than one choice, then @value{GDBN} 10900automatically selects all possible choices. For instance, inserting 10901a breakpoint on a function using an ambiguous name results in a breakpoint 10902inserted on each possible match. However, if a unique choice must be made, 10903then @value{GDBN} uses the menu to help you disambiguate the expression. 10904For instance, printing the address of an overloaded function will result 10905in the use of the menu. 10906 10907When @var{mode} is set to @code{ask}, the debugger always uses the menu 10908when an ambiguity is detected. 10909 10910Finally, when @var{mode} is set to @code{cancel}, the debugger reports 10911an error due to the ambiguity and the command is aborted. 10912 10913@kindex show multiple-symbols 10914@item show multiple-symbols 10915Show the current value of the @code{multiple-symbols} setting. 10916@end table 10917 10918@node Variables 10919@section Program Variables 10920 10921The most common kind of expression to use is the name of a variable 10922in your program. 10923 10924Variables in expressions are understood in the selected stack frame 10925(@pxref{Selection, ,Selecting a Frame}); they must be either: 10926 10927@itemize @bullet 10928@item 10929global (or file-static) 10930@end itemize 10931 10932@noindent or 10933 10934@itemize @bullet 10935@item 10936visible according to the scope rules of the 10937programming language from the point of execution in that frame 10938@end itemize 10939 10940@noindent This means that in the function 10941 10942@smallexample 10943foo (a) 10944 int a; 10945@{ 10946 bar (a); 10947 @{ 10948 int b = test (); 10949 bar (b); 10950 @} 10951@} 10952@end smallexample 10953 10954@noindent 10955you can examine and use the variable @code{a} whenever your program is 10956executing within the function @code{foo}, but you can only use or 10957examine the variable @code{b} while your program is executing inside 10958the block where @code{b} is declared. 10959 10960@cindex variable name conflict 10961There is an exception: you can refer to a variable or function whose 10962scope is a single source file even if the current execution point is not 10963in this file. But it is possible to have more than one such variable or 10964function with the same name (in different source files). If that 10965happens, referring to that name has unpredictable effects. If you wish, 10966you can specify a static variable in a particular function or file by 10967using the colon-colon (@code{::}) notation: 10968 10969@cindex colon-colon, context for variables/functions 10970@ifnotinfo 10971@c info cannot cope with a :: index entry, but why deprive hard copy readers? 10972@cindex @code{::}, context for variables/functions 10973@end ifnotinfo 10974@smallexample 10975@var{file}::@var{variable} 10976@var{function}::@var{variable} 10977@end smallexample 10978 10979@noindent 10980Here @var{file} or @var{function} is the name of the context for the 10981static @var{variable}. In the case of file names, you can use quotes to 10982make sure @value{GDBN} parses the file name as a single word---for example, 10983to print a global value of @code{x} defined in @file{f2.c}: 10984 10985@smallexample 10986(@value{GDBP}) p 'f2.c'::x 10987@end smallexample 10988 10989The @code{::} notation is normally used for referring to 10990static variables, since you typically disambiguate uses of local variables 10991in functions by selecting the appropriate frame and using the 10992simple name of the variable. However, you may also use this notation 10993to refer to local variables in frames enclosing the selected frame: 10994 10995@smallexample 10996void 10997foo (int a) 10998@{ 10999 if (a < 10) 11000 bar (a); 11001 else 11002 process (a); /* Stop here */ 11003@} 11004 11005int 11006bar (int a) 11007@{ 11008 foo (a + 5); 11009@} 11010@end smallexample 11011 11012@noindent 11013For example, if there is a breakpoint at the commented line, 11014here is what you might see 11015when the program stops after executing the call @code{bar(0)}: 11016 11017@smallexample 11018(@value{GDBP}) p a 11019$1 = 10 11020(@value{GDBP}) p bar::a 11021$2 = 5 11022(@value{GDBP}) up 2 11023#2 0x080483d0 in foo (a=5) at foobar.c:12 11024(@value{GDBP}) p a 11025$3 = 5 11026(@value{GDBP}) p bar::a 11027$4 = 0 11028@end smallexample 11029 11030@cindex C@t{++} scope resolution 11031These uses of @samp{::} are very rarely in conflict with the very 11032similar use of the same notation in C@t{++}. When they are in 11033conflict, the C@t{++} meaning takes precedence; however, this can be 11034overridden by quoting the file or function name with single quotes. 11035 11036For example, suppose the program is stopped in a method of a class 11037that has a field named @code{includefile}, and there is also an 11038include file named @file{includefile} that defines a variable, 11039@code{some_global}. 11040 11041@smallexample 11042(@value{GDBP}) p includefile 11043$1 = 23 11044(@value{GDBP}) p includefile::some_global 11045A syntax error in expression, near `'. 11046(@value{GDBP}) p 'includefile'::some_global 11047$2 = 27 11048@end smallexample 11049 11050@cindex wrong values 11051@cindex variable values, wrong 11052@cindex function entry/exit, wrong values of variables 11053@cindex optimized code, wrong values of variables 11054@quotation 11055@emph{Warning:} Occasionally, a local variable may appear to have the 11056wrong value at certain points in a function---just after entry to a new 11057scope, and just before exit. 11058@end quotation 11059You may see this problem when you are stepping by machine instructions. 11060This is because, on most machines, it takes more than one instruction to 11061set up a stack frame (including local variable definitions); if you are 11062stepping by machine instructions, variables may appear to have the wrong 11063values until the stack frame is completely built. On exit, it usually 11064also takes more than one machine instruction to destroy a stack frame; 11065after you begin stepping through that group of instructions, local 11066variable definitions may be gone. 11067 11068This may also happen when the compiler does significant optimizations. 11069To be sure of always seeing accurate values, turn off all optimization 11070when compiling. 11071 11072@cindex ``No symbol "foo" in current context'' 11073Another possible effect of compiler optimizations is to optimize 11074unused variables out of existence, or assign variables to registers (as 11075opposed to memory addresses). Depending on the support for such cases 11076offered by the debug info format used by the compiler, @value{GDBN} 11077might not be able to display values for such local variables. If that 11078happens, @value{GDBN} will print a message like this: 11079 11080@smallexample 11081No symbol "foo" in current context. 11082@end smallexample 11083 11084To solve such problems, either recompile without optimizations, or use a 11085different debug info format, if the compiler supports several such 11086formats. @xref{Compilation}, for more information on choosing compiler 11087options. @xref{C, ,C and C@t{++}}, for more information about debug 11088info formats that are best suited to C@t{++} programs. 11089 11090If you ask to print an object whose contents are unknown to 11091@value{GDBN}, e.g., because its data type is not completely specified 11092by the debug information, @value{GDBN} will say @samp{<incomplete 11093type>}. @xref{Symbols, incomplete type}, for more about this. 11094 11095@cindex no debug info variables 11096If you try to examine or use the value of a (global) variable for 11097which @value{GDBN} has no type information, e.g., because the program 11098includes no debug information, @value{GDBN} displays an error message. 11099@xref{Symbols, unknown type}, for more about unknown types. If you 11100cast the variable to its declared type, @value{GDBN} gets the 11101variable's value using the cast-to type as the variable's type. For 11102example, in a C program: 11103 11104@smallexample 11105 (@value{GDBP}) p var 11106 'var' has unknown type; cast it to its declared type 11107 (@value{GDBP}) p (float) var 11108 $1 = 3.14 11109@end smallexample 11110 11111If you append @kbd{@@entry} string to a function parameter name you get its 11112value at the time the function got called. If the value is not available an 11113error message is printed. Entry values are available only with some compilers. 11114Entry values are normally also printed at the function parameter list according 11115to @ref{set print entry-values}. 11116 11117@smallexample 11118Breakpoint 1, d (i=30) at gdb.base/entry-value.c:29 1111929 i++; 11120(@value{GDBP}) next 1112130 e (i); 11122(@value{GDBP}) print i 11123$1 = 31 11124(@value{GDBP}) print i@@entry 11125$2 = 30 11126@end smallexample 11127 11128Strings are identified as arrays of @code{char} values without specified 11129signedness. Arrays of either @code{signed char} or @code{unsigned char} get 11130printed as arrays of 1 byte sized integers. @code{-fsigned-char} or 11131@code{-funsigned-char} @value{NGCC} options have no effect as @value{GDBN} 11132defines literal string type @code{"char"} as @code{char} without a sign. 11133For program code 11134 11135@smallexample 11136char var0[] = "A"; 11137signed char var1[] = "A"; 11138@end smallexample 11139 11140You get during debugging 11141@smallexample 11142(@value{GDBP}) print var0 11143$1 = "A" 11144(@value{GDBP}) print var1 11145$2 = @{65 'A', 0 '\0'@} 11146@end smallexample 11147 11148@node Arrays 11149@section Artificial Arrays 11150 11151@cindex artificial array 11152@cindex arrays 11153@kindex @@@r{, referencing memory as an array} 11154It is often useful to print out several successive objects of the 11155same type in memory; a section of an array, or an array of 11156dynamically determined size for which only a pointer exists in the 11157program. 11158 11159You can do this by referring to a contiguous span of memory as an 11160@dfn{artificial array}, using the binary operator @samp{@@}. The left 11161operand of @samp{@@} should be the first element of the desired array 11162and be an individual object. The right operand should be the desired length 11163of the array. The result is an array value whose elements are all of 11164the type of the left argument. The first element is actually the left 11165argument; the second element comes from bytes of memory immediately 11166following those that hold the first element, and so on. Here is an 11167example. If a program says 11168 11169@smallexample 11170int *array = (int *) malloc (len * sizeof (int)); 11171@end smallexample 11172 11173@noindent 11174you can print the contents of @code{array} with 11175 11176@smallexample 11177p *array@@len 11178@end smallexample 11179 11180The left operand of @samp{@@} must reside in memory. Array values made 11181with @samp{@@} in this way behave just like other arrays in terms of 11182subscripting, and are coerced to pointers when used in expressions. 11183Artificial arrays most often appear in expressions via the value history 11184(@pxref{Value History, ,Value History}), after printing one out. 11185 11186Another way to create an artificial array is to use a cast. 11187This re-interprets a value as if it were an array. 11188The value need not be in memory: 11189@smallexample 11190(@value{GDBP}) p/x (short[2])0x12345678 11191$1 = @{0x1234, 0x5678@} 11192@end smallexample 11193 11194As a convenience, if you leave the array length out (as in 11195@samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill 11196the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}: 11197@smallexample 11198(@value{GDBP}) p/x (short[])0x12345678 11199$2 = @{0x1234, 0x5678@} 11200@end smallexample 11201 11202Sometimes the artificial array mechanism is not quite enough; in 11203moderately complex data structures, the elements of interest may not 11204actually be adjacent---for example, if you are interested in the values 11205of pointers in an array. One useful work-around in this situation is 11206to use a convenience variable (@pxref{Convenience Vars, ,Convenience 11207Variables}) as a counter in an expression that prints the first 11208interesting value, and then repeat that expression via @key{RET}. For 11209instance, suppose you have an array @code{dtab} of pointers to 11210structures, and you are interested in the values of a field @code{fv} 11211in each structure. Here is an example of what you might type: 11212 11213@smallexample 11214set $i = 0 11215p dtab[$i++]->fv 11216@key{RET} 11217@key{RET} 11218@dots{} 11219@end smallexample 11220 11221@node Output Formats 11222@section Output Formats 11223 11224@cindex formatted output 11225@cindex output formats 11226By default, @value{GDBN} prints a value according to its data type. Sometimes 11227this is not what you want. For example, you might want to print a number 11228in hex, or a pointer in decimal. Or you might want to view data in memory 11229at a certain address as a character string or as an instruction. To do 11230these things, specify an @dfn{output format} when you print a value. 11231 11232The simplest use of output formats is to say how to print a value 11233already computed. This is done by starting the arguments of the 11234@code{print} command with a slash and a format letter. The format 11235letters supported are: 11236 11237@table @code 11238@item x 11239Print the binary representation of the value in hexadecimal. 11240 11241@item d 11242Print the binary representation of the value in decimal. 11243 11244@item u 11245Print the binary representation of the value as an decimal, as if it 11246were unsigned. 11247 11248@item o 11249Print the binary representation of the value in octal. 11250 11251@item t 11252Print the binary representation of the value in binary. The letter 11253@samp{t} stands for ``two''. @footnote{@samp{b} cannot be used 11254because these format letters are also used with the @code{x} command, 11255where @samp{b} stands for ``byte''; see @ref{Memory,,Examining 11256Memory}.} 11257 11258@item a 11259@cindex unknown address, locating 11260@cindex locate address 11261Print as an address, both absolute in hexadecimal and as an offset from 11262the nearest preceding symbol. You can use this format used to discover 11263where (in what function) an unknown address is located: 11264 11265@smallexample 11266(@value{GDBP}) p/a 0x54320 11267$3 = 0x54320 <_initialize_vx+396> 11268@end smallexample 11269 11270@noindent 11271The command @code{info symbol 0x54320} yields similar results. 11272@xref{Symbols, info symbol}. 11273 11274@item c 11275Cast the value to an integer (unlike other formats, this does not just 11276reinterpret the underlying bits) and print it as a character constant. 11277This prints both the numerical value and its character representation. 11278The character representation is replaced with the octal escape 11279@samp{\nnn} for characters outside the 7-bit @sc{ascii} range. 11280 11281Without this format, @value{GDBN} displays @code{char}, 11282@w{@code{unsigned char}}, and @w{@code{signed char}} data as character 11283constants. Single-byte members of vectors are displayed as integer 11284data. 11285 11286@item f 11287Regard the bits of the value as a floating point number and print 11288using typical floating point syntax. 11289 11290@item s 11291@cindex printing strings 11292@cindex printing byte arrays 11293Regard as a string, if possible. With this format, pointers to single-byte 11294data are displayed as null-terminated strings and arrays of single-byte data 11295are displayed as fixed-length strings. Other values are displayed in their 11296natural types. 11297 11298Without this format, @value{GDBN} displays pointers to and arrays of 11299@code{char}, @w{@code{unsigned char}}, and @w{@code{signed char}} as 11300strings. Single-byte members of a vector are displayed as an integer 11301array. 11302 11303@item z 11304Like @samp{x} formatting, the value is treated as an integer and 11305printed as hexadecimal, but leading zeros are printed to pad the value 11306to the size of the integer type. 11307 11308@item r 11309@cindex raw printing 11310Print using the @samp{raw} formatting. By default, @value{GDBN} will 11311use a Python-based pretty-printer, if one is available (@pxref{Pretty 11312Printing}). This typically results in a higher-level display of the 11313value's contents. The @samp{r} format bypasses any Python 11314pretty-printer which might exist. 11315@end table 11316 11317For example, to print the program counter in hex (@pxref{Registers}), type 11318 11319@smallexample 11320p/x $pc 11321@end smallexample 11322 11323@noindent 11324Note that no space is required before the slash; this is because command 11325names in @value{GDBN} cannot contain a slash. 11326 11327To reprint the last value in the value history with a different format, 11328you can use the @code{print} command with just a format and no 11329expression. For example, @samp{p/x} reprints the last value in hex. 11330 11331@node Memory 11332@section Examining Memory 11333 11334You can use the command @code{x} (for ``examine'') to examine memory in 11335any of several formats, independently of your program's data types. 11336 11337@cindex examining memory 11338@table @code 11339@kindex x @r{(examine memory)} 11340@item x/@var{nfu} @var{addr} 11341@itemx x @var{addr} 11342@itemx x 11343Use the @code{x} command to examine memory. 11344@end table 11345 11346@var{n}, @var{f}, and @var{u} are all optional parameters that specify how 11347much memory to display and how to format it; @var{addr} is an 11348expression giving the address where you want to start displaying memory. 11349If you use defaults for @var{nfu}, you need not type the slash @samp{/}. 11350Several commands set convenient defaults for @var{addr}. 11351 11352@table @r 11353@item @var{n}, the repeat count 11354The repeat count is a decimal integer; the default is 1. It specifies 11355how much memory (counting by units @var{u}) to display. If a negative 11356number is specified, memory is examined backward from @var{addr}. 11357@c This really is **decimal**; unaffected by 'set radix' as of GDB 11358@c 4.1.2. 11359 11360@item @var{f}, the display format 11361The display format is one of the formats used by @code{print} 11362(@samp{x}, @samp{d}, @samp{u}, @samp{o}, @samp{t}, @samp{a}, @samp{c}, 11363@samp{f}, @samp{s}), @samp{i} (for machine instructions) and 11364@samp{m} (for displaying memory tags). 11365The default is @samp{x} (hexadecimal) initially. The default changes 11366each time you use either @code{x} or @code{print}. 11367 11368@item @var{u}, the unit size 11369The unit size is any of 11370 11371@table @code 11372@item b 11373Bytes. 11374@item h 11375Halfwords (two bytes). 11376@item w 11377Words (four bytes). This is the initial default. 11378@item g 11379Giant words (eight bytes). 11380@end table 11381 11382Each time you specify a unit size with @code{x}, that size becomes the 11383default unit the next time you use @code{x}. For the @samp{i} format, 11384the unit size is ignored and is normally not written. For the @samp{s} format, 11385the unit size defaults to @samp{b}, unless it is explicitly given. 11386Use @kbd{x /hs} to display 16-bit char strings and @kbd{x /ws} to display 1138732-bit strings. The next use of @kbd{x /s} will again display 8-bit strings. 11388Note that the results depend on the programming language of the 11389current compilation unit. If the language is C, the @samp{s} 11390modifier will use the UTF-16 encoding while @samp{w} will use 11391UTF-32. The encoding is set by the programming language and cannot 11392be altered. 11393 11394@item @var{addr}, starting display address 11395@var{addr} is the address where you want @value{GDBN} to begin displaying 11396memory. The expression need not have a pointer value (though it may); 11397it is always interpreted as an integer address of a byte of memory. 11398@xref{Expressions, ,Expressions}, for more information on expressions. The default for 11399@var{addr} is usually just after the last address examined---but several 11400other commands also set the default address: @code{info breakpoints} (to 11401the address of the last breakpoint listed), @code{info line} (to the 11402starting address of a line), and @code{print} (if you use it to display 11403a value from memory). 11404@end table 11405 11406For example, @samp{x/3uh 0x54320} is a request to display three halfwords 11407(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}), 11408starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four 11409words (@samp{w}) of memory above the stack pointer (here, @samp{$sp}; 11410@pxref{Registers, ,Registers}) in hexadecimal (@samp{x}). 11411 11412You can also specify a negative repeat count to examine memory backward 11413from the given address. For example, @samp{x/-3uh 0x54320} prints three 11414halfwords (@code{h}) at @code{0x5431a}, @code{0x5431c}, and @code{0x5431e}. 11415 11416Since the letters indicating unit sizes are all distinct from the 11417letters specifying output formats, you do not have to remember whether 11418unit size or format comes first; either order works. The output 11419specifications @samp{4xw} and @samp{4wx} mean exactly the same thing. 11420(However, the count @var{n} must come first; @samp{wx4} does not work.) 11421 11422Even though the unit size @var{u} is ignored for the formats @samp{s} 11423and @samp{i}, you might still want to use a count @var{n}; for example, 11424@samp{3i} specifies that you want to see three machine instructions, 11425including any operands. For convenience, especially when used with 11426the @code{display} command, the @samp{i} format also prints branch delay 11427slot instructions, if any, beyond the count specified, which immediately 11428follow the last instruction that is within the count. The command 11429@code{disassemble} gives an alternative way of inspecting machine 11430instructions; see @ref{Machine Code,,Source and Machine Code}. 11431 11432If a negative repeat count is specified for the formats @samp{s} or @samp{i}, 11433the command displays null-terminated strings or instructions before the given 11434address as many as the absolute value of the given number. For the @samp{i} 11435format, we use line number information in the debug info to accurately locate 11436instruction boundaries while disassembling backward. If line info is not 11437available, the command stops examining memory with an error message. 11438 11439All the defaults for the arguments to @code{x} are designed to make it 11440easy to continue scanning memory with minimal specifications each time 11441you use @code{x}. For example, after you have inspected three machine 11442instructions with @samp{x/3i @var{addr}}, you can inspect the next seven 11443with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command, 11444the repeat count @var{n} is used again; the other arguments default as 11445for successive uses of @code{x}. 11446 11447When examining machine instructions, the instruction at current program 11448counter is shown with a @code{=>} marker. For example: 11449 11450@smallexample 11451(@value{GDBP}) x/5i $pc-6 11452 0x804837f <main+11>: mov %esp,%ebp 11453 0x8048381 <main+13>: push %ecx 11454 0x8048382 <main+14>: sub $0x4,%esp 11455=> 0x8048385 <main+17>: movl $0x8048460,(%esp) 11456 0x804838c <main+24>: call 0x80482d4 <puts@@plt> 11457@end smallexample 11458 11459If the architecture supports memory tagging, the tags can be displayed by 11460using @samp{m}. @xref{Memory Tagging}. 11461 11462The information will be displayed once per granule size 11463(the amount of bytes a particular memory tag covers). For example, AArch64 11464has a granule size of 16 bytes, so it will display a tag every 16 bytes. 11465 11466Due to the way @value{GDBN} prints information with the @code{x} command (not 11467aligned to a particular boundary), the tag information will refer to the 11468initial address displayed on a particular line. If a memory tag boundary 11469is crossed in the middle of a line displayed by the @code{x} command, it 11470will be displayed on the next line. 11471 11472The @samp{m} format doesn't affect any other specified formats that were 11473passed to the @code{x} command. 11474 11475@cindex @code{$_}, @code{$__}, and value history 11476The addresses and contents printed by the @code{x} command are not saved 11477in the value history because there is often too much of them and they 11478would get in the way. Instead, @value{GDBN} makes these values available for 11479subsequent use in expressions as values of the convenience variables 11480@code{$_} and @code{$__}. After an @code{x} command, the last address 11481examined is available for use in expressions in the convenience variable 11482@code{$_}. The contents of that address, as examined, are available in 11483the convenience variable @code{$__}. 11484 11485If the @code{x} command has a repeat count, the address and contents saved 11486are from the last memory unit printed; this is not the same as the last 11487address printed if several units were printed on the last line of output. 11488 11489@anchor{addressable memory unit} 11490@cindex addressable memory unit 11491Most targets have an addressable memory unit size of 8 bits. This means 11492that to each memory address are associated 8 bits of data. Some 11493targets, however, have other addressable memory unit sizes. 11494Within @value{GDBN} and this document, the term 11495@dfn{addressable memory unit} (or @dfn{memory unit} for short) is used 11496when explicitly referring to a chunk of data of that size. The word 11497@dfn{byte} is used to refer to a chunk of data of 8 bits, regardless of 11498the addressable memory unit size of the target. For most systems, 11499addressable memory unit is a synonym of byte. 11500 11501@cindex remote memory comparison 11502@cindex target memory comparison 11503@cindex verify remote memory image 11504@cindex verify target memory image 11505When you are debugging a program running on a remote target machine 11506(@pxref{Remote Debugging}), you may wish to verify the program's image 11507in the remote machine's memory against the executable file you 11508downloaded to the target. Or, on any target, you may want to check 11509whether the program has corrupted its own read-only sections. The 11510@code{compare-sections} command is provided for such situations. 11511 11512@table @code 11513@kindex compare-sections 11514@item compare-sections @r{[}@var{section-name}@r{|}@code{-r}@r{]} 11515Compare the data of a loadable section @var{section-name} in the 11516executable file of the program being debugged with the same section in 11517the target machine's memory, and report any mismatches. With no 11518arguments, compares all loadable sections. With an argument of 11519@code{-r}, compares all loadable read-only sections. 11520 11521Note: for remote targets, this command can be accelerated if the 11522target supports computing the CRC checksum of a block of memory 11523(@pxref{qCRC packet}). 11524@end table 11525 11526@node Memory Tagging 11527@section Memory Tagging 11528 11529Memory tagging is a memory protection technology that uses a pair of tags to 11530validate memory accesses through pointers. The tags are integer values 11531usually comprised of a few bits, depending on the architecture. 11532 11533There are two types of tags that are used in this setup: logical and 11534allocation. A logical tag is stored in the pointers themselves, usually at the 11535higher bits of the pointers. An allocation tag is the tag associated 11536with particular ranges of memory in the physical address space, against which 11537the logical tags from pointers are compared. 11538 11539The pointer tag (logical tag) must match the memory tag (allocation tag) 11540for the memory access to be valid. If the logical tag does not match the 11541allocation tag, that will raise a memory violation. 11542 11543Allocation tags cover multiple contiguous bytes of physical memory. This 11544range of bytes is called a memory tag granule and is architecture-specific. 11545For example, AArch64 has a tag granule of 16 bytes, meaning each allocation 11546tag spans 16 bytes of memory. 11547 11548If the underlying architecture supports memory tagging, like AArch64 MTE 11549or SPARC ADI do, @value{GDBN} can make use of it to validate pointers 11550against memory allocation tags. 11551 11552The @code{print} (@pxref{Data}) and @code{x} (@pxref{Memory}) commands will 11553display tag information when appropriate, and a command prefix of 11554@code{memory-tag} gives access to the various memory tagging commands. 11555 11556The @code{memory-tag} commands are the following: 11557 11558@table @code 11559@kindex memory-tag print-logical-tag 11560@item memory-tag print-logical-tag @var{pointer_expression} 11561Print the logical tag stored in @var{pointer_expression}. 11562@kindex memory-tag with-logical-tag 11563@item memory-tag with-logical-tag @var{pointer_expression} @var{tag_bytes} 11564Print the pointer given by @var{pointer_expression}, augmented with a logical 11565tag of @var{tag_bytes}. 11566@kindex memory-tag print-allocation-tag 11567@item memory-tag print-allocation-tag @var{address_expression} 11568Print the allocation tag associated with the memory address given by 11569@var{address_expression}. 11570@kindex memory-tag setatag 11571@item memory-tag setatag @var{starting_address} @var{length} @var{tag_bytes} 11572Set the allocation tag(s) for memory range @r{[}@var{starting_address}, 11573@var{starting_address} + @var{length}@r{)} to @var{tag_bytes}. 11574@kindex memory-tag check 11575@item memory-tag check @var{pointer_expression} 11576Check if the logical tag in the pointer given by @var{pointer_expression} 11577matches the allocation tag for the memory referenced by the pointer. 11578 11579This essentially emulates the hardware validation that is done when tagged 11580memory is accessed through a pointer, but does not cause a memory fault as 11581it would during hardware validation. 11582 11583It can be used to inspect potential memory tagging violations in the running 11584process, before any faults get triggered. 11585@end table 11586 11587@node Auto Display 11588@section Automatic Display 11589@cindex automatic display 11590@cindex display of expressions 11591 11592If you find that you want to print the value of an expression frequently 11593(to see how it changes), you might want to add it to the @dfn{automatic 11594display list} so that @value{GDBN} prints its value each time your program stops. 11595Each expression added to the list is given a number to identify it; 11596to remove an expression from the list, you specify that number. 11597The automatic display looks like this: 11598 11599@smallexample 116002: foo = 38 116013: bar[5] = (struct hack *) 0x3804 11602@end smallexample 11603 11604@noindent 11605This display shows item numbers, expressions and their current values. As with 11606displays you request manually using @code{x} or @code{print}, you can 11607specify the output format you prefer; in fact, @code{display} decides 11608whether to use @code{print} or @code{x} depending your format 11609specification---it uses @code{x} if you specify either the @samp{i} 11610or @samp{s} format, or a unit size; otherwise it uses @code{print}. 11611 11612@table @code 11613@kindex display 11614@item display @var{expr} 11615Add the expression @var{expr} to the list of expressions to display 11616each time your program stops. @xref{Expressions, ,Expressions}. 11617 11618@code{display} does not repeat if you press @key{RET} again after using it. 11619 11620@item display/@var{fmt} @var{expr} 11621For @var{fmt} specifying only a display format and not a size or 11622count, add the expression @var{expr} to the auto-display list but 11623arrange to display it each time in the specified format @var{fmt}. 11624@xref{Output Formats,,Output Formats}. 11625 11626@item display/@var{fmt} @var{addr} 11627For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a 11628number of units, add the expression @var{addr} as a memory address to 11629be examined each time your program stops. Examining means in effect 11630doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining Memory}. 11631@end table 11632 11633For example, @samp{display/i $pc} can be helpful, to see the machine 11634instruction about to be executed each time execution stops (@samp{$pc} 11635is a common name for the program counter; @pxref{Registers, ,Registers}). 11636 11637@table @code 11638@kindex delete display 11639@kindex undisplay 11640@item undisplay @var{dnums}@dots{} 11641@itemx delete display @var{dnums}@dots{} 11642Remove items from the list of expressions to display. Specify the 11643numbers of the displays that you want affected with the command 11644argument @var{dnums}. It can be a single display number, one of the 11645numbers shown in the first field of the @samp{info display} display; 11646or it could be a range of display numbers, as in @code{2-4}. 11647 11648@code{undisplay} does not repeat if you press @key{RET} after using it. 11649(Otherwise you would just get the error @samp{No display number @dots{}}.) 11650 11651@kindex disable display 11652@item disable display @var{dnums}@dots{} 11653Disable the display of item numbers @var{dnums}. A disabled display 11654item is not printed automatically, but is not forgotten. It may be 11655enabled again later. Specify the numbers of the displays that you 11656want affected with the command argument @var{dnums}. It can be a 11657single display number, one of the numbers shown in the first field of 11658the @samp{info display} display; or it could be a range of display 11659numbers, as in @code{2-4}. 11660 11661@kindex enable display 11662@item enable display @var{dnums}@dots{} 11663Enable display of item numbers @var{dnums}. It becomes effective once 11664again in auto display of its expression, until you specify otherwise. 11665Specify the numbers of the displays that you want affected with the 11666command argument @var{dnums}. It can be a single display number, one 11667of the numbers shown in the first field of the @samp{info display} 11668display; or it could be a range of display numbers, as in @code{2-4}. 11669 11670@item display 11671Display the current values of the expressions on the list, just as is 11672done when your program stops. 11673 11674@kindex info display 11675@item info display 11676Print the list of expressions previously set up to display 11677automatically, each one with its item number, but without showing the 11678values. This includes disabled expressions, which are marked as such. 11679It also includes expressions which would not be displayed right now 11680because they refer to automatic variables not currently available. 11681@end table 11682 11683@cindex display disabled out of scope 11684If a display expression refers to local variables, then it does not make 11685sense outside the lexical context for which it was set up. Such an 11686expression is disabled when execution enters a context where one of its 11687variables is not defined. For example, if you give the command 11688@code{display last_char} while inside a function with an argument 11689@code{last_char}, @value{GDBN} displays this argument while your program 11690continues to stop inside that function. When it stops elsewhere---where 11691there is no variable @code{last_char}---the display is disabled 11692automatically. The next time your program stops where @code{last_char} 11693is meaningful, you can enable the display expression once again. 11694 11695@node Print Settings 11696@section Print Settings 11697 11698@cindex format options 11699@cindex print settings 11700@value{GDBN} provides the following ways to control how arrays, structures, 11701and symbols are printed. 11702 11703@noindent 11704These settings are useful for debugging programs in any language: 11705 11706@table @code 11707@kindex set print 11708@anchor{set print address} 11709@item set print address 11710@itemx set print address on 11711@cindex print/don't print memory addresses 11712@value{GDBN} prints memory addresses showing the location of stack 11713traces, structure values, pointer values, breakpoints, and so forth, 11714even when it also displays the contents of those addresses. The default 11715is @code{on}. For example, this is what a stack frame display looks like with 11716@code{set print address on}: 11717 11718@smallexample 11719@group 11720(@value{GDBP}) f 11721#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") 11722 at input.c:530 11723530 if (lquote != def_lquote) 11724@end group 11725@end smallexample 11726 11727@item set print address off 11728Do not print addresses when displaying their contents. For example, 11729this is the same stack frame displayed with @code{set print address off}: 11730 11731@smallexample 11732@group 11733(@value{GDBP}) set print addr off 11734(@value{GDBP}) f 11735#0 set_quotes (lq="<<", rq=">>") at input.c:530 11736530 if (lquote != def_lquote) 11737@end group 11738@end smallexample 11739 11740You can use @samp{set print address off} to eliminate all machine 11741dependent displays from the @value{GDBN} interface. For example, with 11742@code{print address off}, you should get the same text for backtraces on 11743all machines---whether or not they involve pointer arguments. 11744 11745@kindex show print 11746@item show print address 11747Show whether or not addresses are to be printed. 11748@end table 11749 11750When @value{GDBN} prints a symbolic address, it normally prints the 11751closest earlier symbol plus an offset. If that symbol does not uniquely 11752identify the address (for example, it is a name whose scope is a single 11753source file), you may need to clarify. One way to do this is with 11754@code{info line}, for example @samp{info line *0x4537}. Alternately, 11755you can set @value{GDBN} to print the source file and line number when 11756it prints a symbolic address: 11757 11758@table @code 11759@item set print symbol-filename on 11760@cindex source file and line of a symbol 11761@cindex symbol, source file and line 11762Tell @value{GDBN} to print the source file name and line number of a 11763symbol in the symbolic form of an address. 11764 11765@item set print symbol-filename off 11766Do not print source file name and line number of a symbol. This is the 11767default. 11768 11769@item show print symbol-filename 11770Show whether or not @value{GDBN} will print the source file name and 11771line number of a symbol in the symbolic form of an address. 11772@end table 11773 11774Another situation where it is helpful to show symbol filenames and line 11775numbers is when disassembling code; @value{GDBN} shows you the line 11776number and source file that corresponds to each instruction. 11777 11778Also, you may wish to see the symbolic form only if the address being 11779printed is reasonably close to the closest earlier symbol: 11780 11781@table @code 11782@item set print max-symbolic-offset @var{max-offset} 11783@itemx set print max-symbolic-offset unlimited 11784@cindex maximum value for offset of closest symbol 11785Tell @value{GDBN} to only display the symbolic form of an address if the 11786offset between the closest earlier symbol and the address is less than 11787@var{max-offset}. The default is @code{unlimited}, which tells @value{GDBN} 11788to always print the symbolic form of an address if any symbol precedes 11789it. Zero is equivalent to @code{unlimited}. 11790 11791@item show print max-symbolic-offset 11792Ask how large the maximum offset is that @value{GDBN} prints in a 11793symbolic address. 11794@end table 11795 11796@cindex wild pointer, interpreting 11797@cindex pointer, finding referent 11798If you have a pointer and you are not sure where it points, try 11799@samp{set print symbol-filename on}. Then you can determine the name 11800and source file location of the variable where it points, using 11801@samp{p/a @var{pointer}}. This interprets the address in symbolic form. 11802For example, here @value{GDBN} shows that a variable @code{ptt} points 11803at another variable @code{t}, defined in @file{hi2.c}: 11804 11805@smallexample 11806(@value{GDBP}) set print symbol-filename on 11807(@value{GDBP}) p/a ptt 11808$4 = 0xe008 <t in hi2.c> 11809@end smallexample 11810 11811@quotation 11812@emph{Warning:} For pointers that point to a local variable, @samp{p/a} 11813does not show the symbol name and filename of the referent, even with 11814the appropriate @code{set print} options turned on. 11815@end quotation 11816 11817You can also enable @samp{/a}-like formatting all the time using 11818@samp{set print symbol on}: 11819 11820@anchor{set print symbol} 11821@table @code 11822@item set print symbol on 11823Tell @value{GDBN} to print the symbol corresponding to an address, if 11824one exists. 11825 11826@item set print symbol off 11827Tell @value{GDBN} not to print the symbol corresponding to an 11828address. In this mode, @value{GDBN} will still print the symbol 11829corresponding to pointers to functions. This is the default. 11830 11831@item show print symbol 11832Show whether @value{GDBN} will display the symbol corresponding to an 11833address. 11834@end table 11835 11836Other settings control how different kinds of objects are printed: 11837 11838@table @code 11839@anchor{set print array} 11840@item set print array 11841@itemx set print array on 11842@cindex pretty print arrays 11843Pretty print arrays. This format is more convenient to read, 11844but uses more space. The default is off. 11845 11846@item set print array off 11847Return to compressed format for arrays. 11848 11849@item show print array 11850Show whether compressed or pretty format is selected for displaying 11851arrays. 11852 11853@cindex print array indexes 11854@anchor{set print array-indexes} 11855@item set print array-indexes 11856@itemx set print array-indexes on 11857Print the index of each element when displaying arrays. May be more 11858convenient to locate a given element in the array or quickly find the 11859index of a given element in that printed array. The default is off. 11860 11861@item set print array-indexes off 11862Stop printing element indexes when displaying arrays. 11863 11864@item show print array-indexes 11865Show whether the index of each element is printed when displaying 11866arrays. 11867 11868@anchor{set print nibbles} 11869@item set print nibbles 11870@itemx set print nibbles on 11871@cindex print binary values in groups of four bits 11872Print binary values in groups of four bits, known as @dfn{nibbles}, 11873when using the print command of @value{GDBN} with the option @samp{/t}. 11874For example, this is what it looks like with @code{set print nibbles on}: 11875 11876@smallexample 11877@group 11878(@value{GDBP}) print val_flags 11879$1 = 1230 11880(@value{GDBP}) print/t val_flags 11881$2 = 0100 1100 1110 11882@end group 11883@end smallexample 11884 11885@item set print nibbles off 11886Don't printing binary values in groups. This is the default. 11887 11888@item show print nibbles 11889Show whether to print binary values in groups of four bits. 11890 11891@anchor{set print characters} 11892@item set print characters @var{number-of-characters} 11893@itemx set print characters elements 11894@itemx set print characters unlimited 11895@cindex number of string characters to print 11896@cindex limit on number of printed string characters 11897Set a limit on how many characters of a string @value{GDBN} will print. 11898If @value{GDBN} is printing a large string, it stops printing after it 11899has printed the number of characters set by the @code{set print 11900characters} command. This equally applies to multi-byte and wide 11901character strings, that is for strings whose character type is 11902@code{wchar_t}, @code{char16_t}, or @code{char32_t} it is the number of 11903actual characters rather than underlying bytes the encoding uses that 11904this setting controls. 11905Setting @var{number-of-characters} to @code{elements} means that the 11906limit on the number of characters to print follows one for array 11907elements; see @ref{set print elements}. 11908Setting @var{number-of-characters} to @code{unlimited} means that the 11909number of characters to print is unlimited. 11910When @value{GDBN} starts, this limit is set to @code{elements}. 11911 11912@item show print characters 11913Display the number of characters of a large string that @value{GDBN} 11914will print. 11915 11916@anchor{set print elements} 11917@item set print elements @var{number-of-elements} 11918@itemx set print elements unlimited 11919@cindex number of array elements to print 11920@cindex limit on number of printed array elements 11921Set a limit on how many elements of an array @value{GDBN} will print. 11922If @value{GDBN} is printing a large array, it stops printing after it has 11923printed the number of elements set by the @code{set print elements} command. 11924By default this limit also applies to the display of strings; see 11925@ref{set print characters}. 11926When @value{GDBN} starts, this limit is set to 200. 11927Setting @var{number-of-elements} to @code{unlimited} or zero means 11928that the number of elements to print is unlimited. 11929 11930When printing very large arrays, whose size is greater than 11931@code{max-value-size} (@pxref{set max-value-size,,max-value-size}), 11932if the @code{print elements} is set such that the size of the elements 11933being printed is less than or equal to @code{max-value-size}, then 11934@value{GDBN} will print the array (up to the @code{print elements} limit), 11935and only @code{max-value-size} worth of data will be added into the value 11936history (@pxref{Value History, ,Value History}). 11937 11938@item show print elements 11939Display the number of elements of a large array that @value{GDBN} will print. 11940 11941@anchor{set print frame-arguments} 11942@item set print frame-arguments @var{value} 11943@kindex set print frame-arguments 11944@cindex printing frame argument values 11945@cindex print all frame argument values 11946@cindex print frame argument values for scalars only 11947@cindex do not print frame arguments 11948This command allows to control how the values of arguments are printed 11949when the debugger prints a frame (@pxref{Frames}). The possible 11950values are: 11951 11952@table @code 11953@item all 11954The values of all arguments are printed. 11955 11956@item scalars 11957Print the value of an argument only if it is a scalar. The value of more 11958complex arguments such as arrays, structures, unions, etc, is replaced 11959by @code{@dots{}}. This is the default. Here is an example where 11960only scalar arguments are shown: 11961 11962@smallexample 11963#1 0x08048361 in call_me (i=3, s=@dots{}, ss=0xbf8d508c, u=@dots{}, e=green) 11964 at frame-args.c:23 11965@end smallexample 11966 11967@item none 11968None of the argument values are printed. Instead, the value of each argument 11969is replaced by @code{@dots{}}. In this case, the example above now becomes: 11970 11971@smallexample 11972#1 0x08048361 in call_me (i=@dots{}, s=@dots{}, ss=@dots{}, u=@dots{}, e=@dots{}) 11973 at frame-args.c:23 11974@end smallexample 11975 11976@item presence 11977Only the presence of arguments is indicated by @code{@dots{}}. 11978The @code{@dots{}} are not printed for function without any arguments. 11979None of the argument names and values are printed. 11980In this case, the example above now becomes: 11981 11982@smallexample 11983#1 0x08048361 in call_me (@dots{}) at frame-args.c:23 11984@end smallexample 11985 11986@end table 11987 11988By default, only scalar arguments are printed. This command can be used 11989to configure the debugger to print the value of all arguments, regardless 11990of their type. However, it is often advantageous to not print the value 11991of more complex parameters. For instance, it reduces the amount of 11992information printed in each frame, making the backtrace more readable. 11993Also, it improves performance when displaying Ada frames, because 11994the computation of large arguments can sometimes be CPU-intensive, 11995especially in large applications. Setting @code{print frame-arguments} 11996to @code{scalars} (the default), @code{none} or @code{presence} avoids 11997this computation, thus speeding up the display of each Ada frame. 11998 11999@item show print frame-arguments 12000Show how the value of arguments should be displayed when printing a frame. 12001 12002@anchor{set print raw-frame-arguments} 12003@item set print raw-frame-arguments on 12004Print frame arguments in raw, non pretty-printed, form. 12005 12006@item set print raw-frame-arguments off 12007Print frame arguments in pretty-printed form, if there is a pretty-printer 12008for the value (@pxref{Pretty Printing}), 12009otherwise print the value in raw form. 12010This is the default. 12011 12012@item show print raw-frame-arguments 12013Show whether to print frame arguments in raw form. 12014 12015@anchor{set print entry-values} 12016@item set print entry-values @var{value} 12017@kindex set print entry-values 12018Set printing of frame argument values at function entry. In some cases 12019@value{GDBN} can determine the value of function argument which was passed by 12020the function caller, even if the value was modified inside the called function 12021and therefore is different. With optimized code, the current value could be 12022unavailable, but the entry value may still be known. 12023 12024The default value is @code{default} (see below for its description). Older 12025@value{GDBN} behaved as with the setting @code{no}. Compilers not supporting 12026this feature will behave in the @code{default} setting the same way as with the 12027@code{no} setting. 12028 12029This functionality is currently supported only by DWARF 2 debugging format and 12030the compiler has to produce @samp{DW_TAG_call_site} tags. With 12031@value{NGCC}, you need to specify @option{-O -g} during compilation, to get 12032this information. 12033 12034The @var{value} parameter can be one of the following: 12035 12036@table @code 12037@item no 12038Print only actual parameter values, never print values from function entry 12039point. 12040@smallexample 12041#0 equal (val=5) 12042#0 different (val=6) 12043#0 lost (val=<optimized out>) 12044#0 born (val=10) 12045#0 invalid (val=<optimized out>) 12046@end smallexample 12047 12048@item only 12049Print only parameter values from function entry point. The actual parameter 12050values are never printed. 12051@smallexample 12052#0 equal (val@@entry=5) 12053#0 different (val@@entry=5) 12054#0 lost (val@@entry=5) 12055#0 born (val@@entry=<optimized out>) 12056#0 invalid (val@@entry=<optimized out>) 12057@end smallexample 12058 12059@item preferred 12060Print only parameter values from function entry point. If value from function 12061entry point is not known while the actual value is known, print the actual 12062value for such parameter. 12063@smallexample 12064#0 equal (val@@entry=5) 12065#0 different (val@@entry=5) 12066#0 lost (val@@entry=5) 12067#0 born (val=10) 12068#0 invalid (val@@entry=<optimized out>) 12069@end smallexample 12070 12071@item if-needed 12072Print actual parameter values. If actual parameter value is not known while 12073value from function entry point is known, print the entry point value for such 12074parameter. 12075@smallexample 12076#0 equal (val=5) 12077#0 different (val=6) 12078#0 lost (val@@entry=5) 12079#0 born (val=10) 12080#0 invalid (val=<optimized out>) 12081@end smallexample 12082 12083@item both 12084Always print both the actual parameter value and its value from function entry 12085point, even if values of one or both are not available due to compiler 12086optimizations. 12087@smallexample 12088#0 equal (val=5, val@@entry=5) 12089#0 different (val=6, val@@entry=5) 12090#0 lost (val=<optimized out>, val@@entry=5) 12091#0 born (val=10, val@@entry=<optimized out>) 12092#0 invalid (val=<optimized out>, val@@entry=<optimized out>) 12093@end smallexample 12094 12095@item compact 12096Print the actual parameter value if it is known and also its value from 12097function entry point if it is known. If neither is known, print for the actual 12098value @code{<optimized out>}. If not in MI mode (@pxref{GDB/MI}) and if both 12099values are known and identical, print the shortened 12100@code{param=param@@entry=VALUE} notation. 12101@smallexample 12102#0 equal (val=val@@entry=5) 12103#0 different (val=6, val@@entry=5) 12104#0 lost (val@@entry=5) 12105#0 born (val=10) 12106#0 invalid (val=<optimized out>) 12107@end smallexample 12108 12109@item default 12110Always print the actual parameter value. Print also its value from function 12111entry point, but only if it is known. If not in MI mode (@pxref{GDB/MI}) and 12112if both values are known and identical, print the shortened 12113@code{param=param@@entry=VALUE} notation. 12114@smallexample 12115#0 equal (val=val@@entry=5) 12116#0 different (val=6, val@@entry=5) 12117#0 lost (val=<optimized out>, val@@entry=5) 12118#0 born (val=10) 12119#0 invalid (val=<optimized out>) 12120@end smallexample 12121@end table 12122 12123For analysis messages on possible failures of frame argument values at function 12124entry resolution see @ref{set debug entry-values}. 12125 12126@item show print entry-values 12127Show the method being used for printing of frame argument values at function 12128entry. 12129 12130@anchor{set print frame-info} 12131@item set print frame-info @var{value} 12132@kindex set print frame-info 12133@cindex printing frame information 12134@cindex frame information, printing 12135This command allows to control the information printed when 12136the debugger prints a frame. See @ref{Frames}, @ref{Backtrace}, 12137for a general explanation about frames and frame information. 12138Note that some other settings (such as @code{set print frame-arguments} 12139and @code{set print address}) are also influencing if and how some frame 12140information is displayed. In particular, the frame program counter is never 12141printed if @code{set print address} is off. 12142 12143The possible values for @code{set print frame-info} are: 12144@table @code 12145@item short-location 12146Print the frame level, the program counter (if not at the 12147beginning of the location source line), the function, the function 12148arguments. 12149@item location 12150Same as @code{short-location} but also print the source file and source line 12151number. 12152@item location-and-address 12153Same as @code{location} but print the program counter even if located at the 12154beginning of the location source line. 12155@item source-line 12156Print the program counter (if not at the beginning of the location 12157source line), the line number and the source line. 12158@item source-and-location 12159Print what @code{location} and @code{source-line} are printing. 12160@item auto 12161The information printed for a frame is decided automatically 12162by the @value{GDBN} command that prints a frame. 12163For example, @code{frame} prints the information printed by 12164@code{source-and-location} while @code{stepi} will switch between 12165@code{source-line} and @code{source-and-location} depending on the program 12166counter. 12167The default value is @code{auto}. 12168@end table 12169 12170@anchor{set print repeats} 12171@item set print repeats @var{number-of-repeats} 12172@itemx set print repeats unlimited 12173@cindex repeated array elements 12174Set the threshold for suppressing display of repeated array 12175elements. When the number of consecutive identical elements of an 12176array exceeds the threshold, @value{GDBN} prints the string 12177@code{"<repeats @var{n} times>"}, where @var{n} is the number of 12178identical repetitions, instead of displaying the identical elements 12179themselves. Setting the threshold to @code{unlimited} or zero will 12180cause all elements to be individually printed. The default threshold 12181is 10. 12182 12183@item show print repeats 12184Display the current threshold for printing repeated identical 12185elements. 12186 12187@anchor{set print max-depth} 12188@item set print max-depth @var{depth} 12189@item set print max-depth unlimited 12190@cindex printing nested structures 12191Set the threshold after which nested structures are replaced with 12192ellipsis, this can make visualising deeply nested structures easier. 12193 12194For example, given this C code 12195 12196@smallexample 12197typedef struct s1 @{ int a; @} s1; 12198typedef struct s2 @{ s1 b; @} s2; 12199typedef struct s3 @{ s2 c; @} s3; 12200typedef struct s4 @{ s3 d; @} s4; 12201 12202s4 var = @{ @{ @{ @{ 3 @} @} @} @}; 12203@end smallexample 12204 12205The following table shows how different values of @var{depth} will 12206effect how @code{var} is printed by @value{GDBN}: 12207 12208@multitable @columnfractions .3 .7 12209@headitem @var{depth} setting @tab Result of @samp{p var} 12210@item unlimited 12211@tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}} 12212@item @code{0} 12213@tab @code{$1 = @{...@}} 12214@item @code{1} 12215@tab @code{$1 = @{d = @{...@}@}} 12216@item @code{2} 12217@tab @code{$1 = @{d = @{c = @{...@}@}@}} 12218@item @code{3} 12219@tab @code{$1 = @{d = @{c = @{b = @{...@}@}@}@}} 12220@item @code{4} 12221@tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}} 12222@end multitable 12223 12224To see the contents of structures that have been hidden the user can 12225either increase the print max-depth, or they can print the elements of 12226the structure that are visible, for example 12227 12228@smallexample 12229(@value{GDBP}) set print max-depth 2 12230(@value{GDBP}) p var 12231$1 = @{d = @{c = @{...@}@}@} 12232(@value{GDBP}) p var.d 12233$2 = @{c = @{b = @{...@}@}@} 12234(@value{GDBP}) p var.d.c 12235$3 = @{b = @{a = 3@}@} 12236@end smallexample 12237 12238The pattern used to replace nested structures varies based on 12239language, for most languages @code{@{...@}} is used, but Fortran uses 12240@code{(...)}. 12241 12242@item show print max-depth 12243Display the current threshold after which nested structures are 12244replaces with ellipsis. 12245 12246@anchor{set print memory-tag-violations} 12247@cindex printing memory tag violation information 12248@item set print memory-tag-violations 12249@itemx set print memory-tag-violations on 12250Cause @value{GDBN} to display additional information about memory tag violations 12251when printing pointers and addresses. 12252 12253@item set print memory-tag-violations off 12254Stop printing memory tag violation information. 12255 12256@item show print memory-tag-violations 12257Show whether memory tag violation information is displayed when printing 12258pointers and addresses. 12259 12260@anchor{set print null-stop} 12261@item set print null-stop 12262@cindex @sc{null} elements in arrays 12263Cause @value{GDBN} to stop printing the characters of an array when the first 12264@sc{null} is encountered. This is useful when large arrays actually 12265contain only short strings. 12266The default is off. 12267 12268@item show print null-stop 12269Show whether @value{GDBN} stops printing an array on the first 12270@sc{null} character. 12271 12272@anchor{set print pretty} 12273@item set print pretty on 12274@cindex print structures in indented form 12275@cindex indentation in structure display 12276Cause @value{GDBN} to print structures in an indented format with one member 12277per line, like this: 12278 12279@smallexample 12280@group 12281$1 = @{ 12282 next = 0x0, 12283 flags = @{ 12284 sweet = 1, 12285 sour = 1 12286 @}, 12287 meat = 0x54 "Pork" 12288@} 12289@end group 12290@end smallexample 12291 12292@item set print pretty off 12293Cause @value{GDBN} to print structures in a compact format, like this: 12294 12295@smallexample 12296@group 12297$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \ 12298meat = 0x54 "Pork"@} 12299@end group 12300@end smallexample 12301 12302@noindent 12303This is the default format. 12304 12305@item show print pretty 12306Show which format @value{GDBN} is using to print structures. 12307 12308@anchor{set print raw-values} 12309@item set print raw-values on 12310Print values in raw form, without applying the pretty 12311printers for the value. 12312 12313@item set print raw-values off 12314Print values in pretty-printed form, if there is a pretty-printer 12315for the value (@pxref{Pretty Printing}), 12316otherwise print the value in raw form. 12317 12318The default setting is ``off''. 12319 12320@item show print raw-values 12321Show whether to print values in raw form. 12322 12323@item set print sevenbit-strings on 12324@cindex eight-bit characters in strings 12325@cindex octal escapes in strings 12326Print using only seven-bit characters; if this option is set, 12327@value{GDBN} displays any eight-bit characters (in strings or 12328character values) using the notation @code{\}@var{nnn}. This setting is 12329best if you are working in English (@sc{ascii}) and you use the 12330high-order bit of characters as a marker or ``meta'' bit. 12331 12332@item set print sevenbit-strings off 12333Print full eight-bit characters. This allows the use of more 12334international character sets, and is the default. 12335 12336@item show print sevenbit-strings 12337Show whether or not @value{GDBN} is printing only seven-bit characters. 12338 12339@anchor{set print union} 12340@item set print union on 12341@cindex unions in structures, printing 12342Tell @value{GDBN} to print unions which are contained in structures 12343and other unions. This is the default setting. 12344 12345@item set print union off 12346Tell @value{GDBN} not to print unions which are contained in 12347structures and other unions. @value{GDBN} will print @code{"@{...@}"} 12348instead. 12349 12350@item show print union 12351Ask @value{GDBN} whether or not it will print unions which are contained in 12352structures and other unions. 12353 12354For example, given the declarations 12355 12356@smallexample 12357typedef enum @{Tree, Bug@} Species; 12358typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms; 12359typedef enum @{Caterpillar, Cocoon, Butterfly@} 12360 Bug_forms; 12361 12362struct thing @{ 12363 Species it; 12364 union @{ 12365 Tree_forms tree; 12366 Bug_forms bug; 12367 @} form; 12368@}; 12369 12370struct thing foo = @{Tree, @{Acorn@}@}; 12371@end smallexample 12372 12373@noindent 12374with @code{set print union on} in effect @samp{p foo} would print 12375 12376@smallexample 12377$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@} 12378@end smallexample 12379 12380@noindent 12381and with @code{set print union off} in effect it would print 12382 12383@smallexample 12384$1 = @{it = Tree, form = @{...@}@} 12385@end smallexample 12386 12387@noindent 12388@code{set print union} affects programs written in C-like languages 12389and in Pascal. 12390@end table 12391 12392@need 1000 12393@noindent 12394These settings are of interest when debugging C@t{++} programs: 12395 12396@table @code 12397@cindex demangling C@t{++} names 12398@item set print demangle 12399@itemx set print demangle on 12400Print C@t{++} names in their source form rather than in the encoded 12401(``mangled'') form passed to the assembler and linker for type-safe 12402linkage. The default is on. 12403 12404@item show print demangle 12405Show whether C@t{++} names are printed in mangled or demangled form. 12406 12407@item set print asm-demangle 12408@itemx set print asm-demangle on 12409Print C@t{++} names in their source form rather than their mangled form, even 12410in assembler code printouts such as instruction disassemblies. 12411The default is off. 12412 12413@item show print asm-demangle 12414Show whether C@t{++} names in assembly listings are printed in mangled 12415or demangled form. 12416 12417@cindex C@t{++} symbol decoding style 12418@cindex symbol decoding style, C@t{++} 12419@kindex set demangle-style 12420@item set demangle-style @var{style} 12421Choose among several encoding schemes used by different compilers to represent 12422C@t{++} names. If you omit @var{style}, you will see a list of possible 12423formats. The default value is @var{auto}, which lets @value{GDBN} choose a 12424decoding style by inspecting your program. 12425 12426@item show demangle-style 12427Display the encoding style currently in use for decoding C@t{++} symbols. 12428 12429@anchor{set print object} 12430@item set print object 12431@itemx set print object on 12432@cindex derived type of an object, printing 12433@cindex display derived types 12434When displaying a pointer to an object, identify the @emph{actual} 12435(derived) type of the object rather than the @emph{declared} type, using 12436the virtual function table. Note that the virtual function table is 12437required---this feature can only work for objects that have run-time 12438type identification; a single virtual method in the object's declared 12439type is sufficient. Note that this setting is also taken into account when 12440working with variable objects via MI (@pxref{GDB/MI}). 12441 12442@item set print object off 12443Display only the declared type of objects, without reference to the 12444virtual function table. This is the default setting. 12445 12446@item show print object 12447Show whether actual, or declared, object types are displayed. 12448 12449@anchor{set print static-members} 12450@item set print static-members 12451@itemx set print static-members on 12452@cindex static members of C@t{++} objects 12453Print static members when displaying a C@t{++} object. The default is on. 12454 12455@item set print static-members off 12456Do not print static members when displaying a C@t{++} object. 12457 12458@item show print static-members 12459Show whether C@t{++} static members are printed or not. 12460 12461@item set print pascal_static-members 12462@itemx set print pascal_static-members on 12463@cindex static members of Pascal objects 12464@cindex Pascal objects, static members display 12465Print static members when displaying a Pascal object. The default is on. 12466 12467@item set print pascal_static-members off 12468Do not print static members when displaying a Pascal object. 12469 12470@item show print pascal_static-members 12471Show whether Pascal static members are printed or not. 12472 12473@c These don't work with HP ANSI C++ yet. 12474@anchor{set print vtbl} 12475@item set print vtbl 12476@itemx set print vtbl on 12477@cindex pretty print C@t{++} virtual function tables 12478@cindex virtual functions (C@t{++}) display 12479@cindex VTBL display 12480Pretty print C@t{++} virtual function tables. The default is off. 12481(The @code{vtbl} commands do not work on programs compiled with the HP 12482ANSI C@t{++} compiler (@code{aCC}).) 12483 12484@item set print vtbl off 12485Do not pretty print C@t{++} virtual function tables. 12486 12487@item show print vtbl 12488Show whether C@t{++} virtual function tables are pretty printed, or not. 12489@end table 12490 12491@node Pretty Printing 12492@section Pretty Printing 12493 12494@value{GDBN} provides a mechanism to allow pretty-printing of values using 12495Python code. It greatly simplifies the display of complex objects. This 12496mechanism works for both MI and the CLI. 12497 12498@menu 12499* Pretty-Printer Introduction:: Introduction to pretty-printers 12500* Pretty-Printer Example:: An example pretty-printer 12501* Pretty-Printer Commands:: Pretty-printer commands 12502@end menu 12503 12504@node Pretty-Printer Introduction 12505@subsection Pretty-Printer Introduction 12506 12507When @value{GDBN} prints a value, it first sees if there is a pretty-printer 12508registered for the value. If there is then @value{GDBN} invokes the 12509pretty-printer to print the value. Otherwise the value is printed normally. 12510 12511Pretty-printers are normally named. This makes them easy to manage. 12512The @samp{info pretty-printer} command will list all the installed 12513pretty-printers with their names. 12514If a pretty-printer can handle multiple data types, then its 12515@dfn{subprinters} are the printers for the individual data types. 12516Each such subprinter has its own name. 12517The format of the name is @var{printer-name};@var{subprinter-name}. 12518 12519Pretty-printers are installed by @dfn{registering} them with @value{GDBN}. 12520Typically they are automatically loaded and registered when the corresponding 12521debug information is loaded, thus making them available without having to 12522do anything special. 12523 12524There are three places where a pretty-printer can be registered. 12525 12526@itemize @bullet 12527@item 12528Pretty-printers registered globally are available when debugging 12529all inferiors. 12530 12531@item 12532Pretty-printers registered with a program space are available only 12533when debugging that program. 12534@xref{Progspaces In Python}, for more details on program spaces in Python. 12535 12536@item 12537Pretty-printers registered with an objfile are loaded and unloaded 12538with the corresponding objfile (e.g., shared library). 12539@xref{Objfiles In Python}, for more details on objfiles in Python. 12540@end itemize 12541 12542@xref{Selecting Pretty-Printers}, for further information on how 12543pretty-printers are selected, 12544 12545@xref{Writing a Pretty-Printer}, for implementing pretty printers 12546for new types. 12547 12548@node Pretty-Printer Example 12549@subsection Pretty-Printer Example 12550 12551Here is how a C@t{++} @code{std::string} looks without a pretty-printer: 12552 12553@smallexample 12554(@value{GDBP}) print s 12555$1 = @{ 12556 static npos = 4294967295, 12557 _M_dataplus = @{ 12558 <std::allocator<char>> = @{ 12559 <__gnu_cxx::new_allocator<char>> = @{ 12560 <No data fields>@}, <No data fields> 12561 @}, 12562 members of std::basic_string<char, std::char_traits<char>, 12563 std::allocator<char> >::_Alloc_hider: 12564 _M_p = 0x804a014 "abcd" 12565 @} 12566@} 12567@end smallexample 12568 12569With a pretty-printer for @code{std::string} only the contents are printed: 12570 12571@smallexample 12572(@value{GDBP}) print s 12573$2 = "abcd" 12574@end smallexample 12575 12576@node Pretty-Printer Commands 12577@subsection Pretty-Printer Commands 12578@cindex pretty-printer commands 12579 12580@table @code 12581@kindex info pretty-printer 12582@item info pretty-printer [@var{object-regexp} [@var{name-regexp}]] 12583Print the list of installed pretty-printers. 12584This includes disabled pretty-printers, which are marked as such. 12585 12586@var{object-regexp} is a regular expression matching the objects 12587whose pretty-printers to list. 12588Objects can be @code{global}, the program space's file 12589(@pxref{Progspaces In Python}), 12590and the object files within that program space (@pxref{Objfiles In Python}). 12591@xref{Selecting Pretty-Printers}, for details on how @value{GDBN} 12592looks up a printer from these three objects. 12593 12594@var{name-regexp} is a regular expression matching the name of the printers 12595to list. 12596 12597@kindex disable pretty-printer 12598@item disable pretty-printer [@var{object-regexp} [@var{name-regexp}]] 12599Disable pretty-printers matching @var{object-regexp} and @var{name-regexp}. 12600A disabled pretty-printer is not forgotten, it may be enabled again later. 12601 12602@kindex enable pretty-printer 12603@item enable pretty-printer [@var{object-regexp} [@var{name-regexp}]] 12604Enable pretty-printers matching @var{object-regexp} and @var{name-regexp}. 12605@end table 12606 12607Example: 12608 12609Suppose we have three pretty-printers installed: one from library1.so 12610named @code{foo} that prints objects of type @code{foo}, and 12611another from library2.so named @code{bar} that prints two types of objects, 12612@code{bar1} and @code{bar2}. 12613 12614@smallexample 12615@group 12616(@value{GDBP}) info pretty-printer 12617library1.so: 12618 foo 12619library2.so: 12620 bar 12621 bar1 12622 bar2 12623@end group 12624@group 12625(@value{GDBP}) info pretty-printer library2 12626library2.so: 12627 bar 12628 bar1 12629 bar2 12630@end group 12631@group 12632(@value{GDBP}) disable pretty-printer library1 126331 printer disabled 126342 of 3 printers enabled 12635(@value{GDBP}) info pretty-printer 12636library1.so: 12637 foo [disabled] 12638library2.so: 12639 bar 12640 bar1 12641 bar2 12642@end group 12643@group 12644(@value{GDBP}) disable pretty-printer library2 bar;bar1 126451 printer disabled 126461 of 3 printers enabled 12647(@value{GDBP}) info pretty-printer library2 12648library2.so: 12649 bar 12650 bar1 [disabled] 12651 bar2 12652@end group 12653@group 12654(@value{GDBP}) disable pretty-printer library2 bar 126551 printer disabled 126560 of 3 printers enabled 12657(@value{GDBP}) info pretty-printer 12658library1.so: 12659 foo [disabled] 12660library2.so: 12661 bar [disabled] 12662 bar1 [disabled] 12663 bar2 12664@end group 12665@end smallexample 12666 12667Note that for @code{bar} the entire printer can be disabled, 12668as can each individual subprinter. 12669 12670Printing values and frame arguments is done by default using 12671the enabled pretty printers. 12672 12673The print option @code{-raw-values} and @value{GDBN} setting 12674@code{set print raw-values} (@pxref{set print raw-values}) can be 12675used to print values without applying the enabled pretty printers. 12676 12677Similarly, the backtrace option @code{-raw-frame-arguments} and 12678@value{GDBN} setting @code{set print raw-frame-arguments} 12679(@pxref{set print raw-frame-arguments}) can be used to ignore the 12680enabled pretty printers when printing frame argument values. 12681 12682@node Value History 12683@section Value History 12684 12685@cindex value history 12686@cindex history of values printed by @value{GDBN} 12687Values printed by the @code{print} command are saved in the @value{GDBN} 12688@dfn{value history}. This allows you to refer to them in other expressions. 12689Values are kept until the symbol table is re-read or discarded 12690(for example with the @code{file} or @code{symbol-file} commands). 12691When the symbol table changes, the value history is discarded, 12692since the values may contain pointers back to the types defined in the 12693symbol table. 12694 12695@cindex @code{$} 12696@cindex @code{$$} 12697@cindex history number 12698The values printed are given @dfn{history numbers} by which you can 12699refer to them. These are successive integers starting with one. 12700@code{print} shows you the history number assigned to a value by 12701printing @samp{$@var{num} = } before the value; here @var{num} is the 12702history number. 12703 12704To refer to any previous value, use @samp{$} followed by the value's 12705history number. The way @code{print} labels its output is designed to 12706remind you of this. Just @code{$} refers to the most recent value in 12707the history, and @code{$$} refers to the value before that. 12708@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2} 12709is the value just prior to @code{$$}, @code{$$1} is equivalent to 12710@code{$$}, and @code{$$0} is equivalent to @code{$}. 12711 12712For example, suppose you have just printed a pointer to a structure and 12713want to see the contents of the structure. It suffices to type 12714 12715@smallexample 12716p *$ 12717@end smallexample 12718 12719If you have a chain of structures where the component @code{next} points 12720to the next one, you can print the contents of the next one with this: 12721 12722@smallexample 12723p *$.next 12724@end smallexample 12725 12726@noindent 12727You can print successive links in the chain by repeating this 12728command---which you can do by just typing @key{RET}. 12729 12730Note that the history records values, not expressions. If the value of 12731@code{x} is 4 and you type these commands: 12732 12733@smallexample 12734print x 12735set x=5 12736@end smallexample 12737 12738@noindent 12739then the value recorded in the value history by the @code{print} command 12740remains 4 even though the value of @code{x} has changed. 12741 12742@table @code 12743@kindex show values 12744@item show values 12745Print the last ten values in the value history, with their item numbers. 12746This is like @samp{p@ $$9} repeated ten times, except that @code{show 12747values} does not change the history. 12748 12749@item show values @var{n} 12750Print ten history values centered on history item number @var{n}. 12751 12752@item show values + 12753Print ten history values just after the values last printed. If no more 12754values are available, @code{show values +} produces no display. 12755@end table 12756 12757Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the 12758same effect as @samp{show values +}. 12759 12760@node Convenience Vars 12761@section Convenience Variables 12762 12763@cindex convenience variables 12764@cindex user-defined variables 12765@value{GDBN} provides @dfn{convenience variables} that you can use within 12766@value{GDBN} to hold on to a value and refer to it later. These variables 12767exist entirely within @value{GDBN}; they are not part of your program, and 12768setting a convenience variable has no direct effect on further execution 12769of your program. That is why you can use them freely. 12770 12771Convenience variables are prefixed with @samp{$}. Any name preceded by 12772@samp{$} can be used for a convenience variable, unless it is one of 12773the predefined machine-specific register names (@pxref{Registers, ,Registers}). 12774(Value history references, in contrast, are @emph{numbers} preceded 12775by @samp{$}. @xref{Value History, ,Value History}.) 12776 12777You can save a value in a convenience variable with an assignment 12778expression, just as you would set a variable in your program. 12779For example: 12780 12781@smallexample 12782set $foo = *object_ptr 12783@end smallexample 12784 12785@noindent 12786would save in @code{$foo} the value contained in the object pointed to by 12787@code{object_ptr}. 12788 12789Using a convenience variable for the first time creates it, but its 12790value is @code{void} until you assign a new value. You can alter the 12791value with another assignment at any time. 12792 12793Convenience variables have no fixed types. You can assign a convenience 12794variable any type of value, including structures and arrays, even if 12795that variable already has a value of a different type. The convenience 12796variable, when used as an expression, has the type of its current value. 12797 12798@table @code 12799@kindex show convenience 12800@cindex show all user variables and functions 12801@item show convenience 12802Print a list of convenience variables used so far, and their values, 12803as well as a list of the convenience functions. 12804Abbreviated @code{show conv}. 12805 12806@kindex init-if-undefined 12807@cindex convenience variables, initializing 12808@item init-if-undefined $@var{variable} = @var{expression} 12809Set a convenience variable if it has not already been set. This is useful 12810for user-defined commands that keep some state. It is similar, in concept, 12811to using local static variables with initializers in C (except that 12812convenience variables are global). It can also be used to allow users to 12813override default values used in a command script. 12814 12815If the variable is already defined then the expression is not evaluated so 12816any side-effects do not occur. 12817@end table 12818 12819One of the ways to use a convenience variable is as a counter to be 12820incremented or a pointer to be advanced. For example, to print 12821a field from successive elements of an array of structures: 12822 12823@smallexample 12824set $i = 0 12825print bar[$i++]->contents 12826@end smallexample 12827 12828@noindent 12829Repeat that command by typing @key{RET}. 12830 12831Some convenience variables are created automatically by @value{GDBN} and given 12832values likely to be useful. 12833 12834@table @code 12835@vindex $_@r{, convenience variable} 12836@item $_ 12837The variable @code{$_} is automatically set by the @code{x} command to 12838the last address examined (@pxref{Memory, ,Examining Memory}). Other 12839commands which provide a default address for @code{x} to examine also 12840set @code{$_} to that address; these commands include @code{info line} 12841and @code{info breakpoint}. The type of @code{$_} is @code{void *} 12842except when set by the @code{x} command, in which case it is a pointer 12843to the type of @code{$__}. 12844 12845@vindex $__@r{, convenience variable} 12846@item $__ 12847The variable @code{$__} is automatically set by the @code{x} command 12848to the value found in the last address examined. Its type is chosen 12849to match the format in which the data was printed. 12850 12851@item $_exitcode 12852@vindex $_exitcode@r{, convenience variable} 12853When the program being debugged terminates normally, @value{GDBN} 12854automatically sets this variable to the exit code of the program, and 12855resets @code{$_exitsignal} to @code{void}. 12856 12857@item $_exitsignal 12858@vindex $_exitsignal@r{, convenience variable} 12859When the program being debugged dies due to an uncaught signal, 12860@value{GDBN} automatically sets this variable to that signal's number, 12861and resets @code{$_exitcode} to @code{void}. 12862 12863To distinguish between whether the program being debugged has exited 12864(i.e., @code{$_exitcode} is not @code{void}) or signalled (i.e., 12865@code{$_exitsignal} is not @code{void}), the convenience function 12866@code{$_isvoid} can be used (@pxref{Convenience Funs,, Convenience 12867Functions}). For example, considering the following source code: 12868 12869@smallexample 12870#include <signal.h> 12871 12872int 12873main (int argc, char *argv[]) 12874@{ 12875 raise (SIGALRM); 12876 return 0; 12877@} 12878@end smallexample 12879 12880A valid way of telling whether the program being debugged has exited 12881or signalled would be: 12882 12883@smallexample 12884(@value{GDBP}) define has_exited_or_signalled 12885Type commands for definition of ``has_exited_or_signalled''. 12886End with a line saying just ``end''. 12887>if $_isvoid ($_exitsignal) 12888 >echo The program has exited\n 12889 >else 12890 >echo The program has signalled\n 12891 >end 12892>end 12893(@value{GDBP}) run 12894Starting program: 12895 12896Program terminated with signal SIGALRM, Alarm clock. 12897The program no longer exists. 12898(@value{GDBP}) has_exited_or_signalled 12899The program has signalled 12900@end smallexample 12901 12902As can be seen, @value{GDBN} correctly informs that the program being 12903debugged has signalled, since it calls @code{raise} and raises a 12904@code{SIGALRM} signal. If the program being debugged had not called 12905@code{raise}, then @value{GDBN} would report a normal exit: 12906 12907@smallexample 12908(@value{GDBP}) has_exited_or_signalled 12909The program has exited 12910@end smallexample 12911 12912@item $_exception 12913The variable @code{$_exception} is set to the exception object being 12914thrown at an exception-related catchpoint. @xref{Set Catchpoints}. 12915 12916@item $_ada_exception 12917The variable @code{$_ada_exception} is set to the address of the 12918exception being caught or thrown at an Ada exception-related 12919catchpoint. @xref{Set Catchpoints}. 12920 12921@item $_probe_argc 12922@itemx $_probe_arg0@dots{}$_probe_arg11 12923Arguments to a static probe. @xref{Static Probe Points}. 12924 12925@item $_sdata 12926@vindex $_sdata@r{, inspect, convenience variable} 12927The variable @code{$_sdata} contains extra collected static tracepoint 12928data. @xref{Tracepoint Actions,,Tracepoint Action Lists}. Note that 12929@code{$_sdata} could be empty, if not inspecting a trace buffer, or 12930if extra static tracepoint data has not been collected. 12931 12932@item $_siginfo 12933@vindex $_siginfo@r{, convenience variable} 12934The variable @code{$_siginfo} contains extra signal information 12935(@pxref{extra signal information}). Note that @code{$_siginfo} 12936could be empty, if the application has not yet received any signals. 12937For example, it will be empty before you execute the @code{run} command. 12938 12939@item $_tlb 12940@vindex $_tlb@r{, convenience variable} 12941The variable @code{$_tlb} is automatically set when debugging 12942applications running on MS-Windows in native mode or connected to 12943gdbserver that supports the @code{qGetTIBAddr} request. 12944@xref{General Query Packets}. 12945This variable contains the address of the thread information block. 12946 12947@item $_inferior 12948The number of the current inferior. @xref{Inferiors Connections and 12949Programs, ,Debugging Multiple Inferiors Connections and Programs}. 12950 12951@item $_thread 12952The thread number of the current thread. @xref{thread numbers}. 12953 12954@item $_gthread 12955The global number of the current thread. @xref{global thread numbers}. 12956 12957@item $_inferior_thread_count 12958The number of live threads in the current inferior. @xref{Threads}. 12959 12960@item $_gdb_major 12961@itemx $_gdb_minor 12962@vindex $_gdb_major@r{, convenience variable} 12963@vindex $_gdb_minor@r{, convenience variable} 12964The major and minor version numbers of the running @value{GDBN}. 12965Development snapshots and pretest versions have their minor version 12966incremented by one; thus, @value{GDBN} pretest 9.11.90 will produce 12967the value 12 for @code{$_gdb_minor}. These variables allow you to 12968write scripts that work with different versions of @value{GDBN} 12969without errors caused by features unavailable in some of those 12970versions. 12971 12972@item $_shell_exitcode 12973@itemx $_shell_exitsignal 12974@vindex $_shell_exitcode@r{, convenience variable} 12975@vindex $_shell_exitsignal@r{, convenience variable} 12976@cindex shell command, exit code 12977@cindex shell command, exit signal 12978@cindex exit status of shell commands 12979@value{GDBN} commands such as @code{shell} and @code{|} are launching 12980shell commands. When a launched command terminates, @value{GDBN} 12981automatically maintains the variables @code{$_shell_exitcode} 12982and @code{$_shell_exitsignal} according to the exit status of the last 12983launched command. These variables are set and used similarly to 12984the variables @code{$_exitcode} and @code{$_exitsignal}. 12985 12986@end table 12987 12988@node Convenience Funs 12989@section Convenience Functions 12990 12991@cindex convenience functions 12992@value{GDBN} also supplies some @dfn{convenience functions}. These 12993have a syntax similar to convenience variables. A convenience 12994function can be used in an expression just like an ordinary function; 12995however, a convenience function is implemented internally to 12996@value{GDBN}. 12997 12998These functions do not require @value{GDBN} to be configured with 12999@code{Python} support, which means that they are always available. 13000 13001@table @code 13002 13003@findex $_isvoid@r{, convenience function} 13004@item $_isvoid (@var{expr}) 13005Return one if the expression @var{expr} is @code{void}. Otherwise it 13006returns zero. 13007 13008A @code{void} expression is an expression where the type of the result 13009is @code{void}. For example, you can examine a convenience variable 13010(see @ref{Convenience Vars,, Convenience Variables}) to check whether 13011it is @code{void}: 13012 13013@smallexample 13014(@value{GDBP}) print $_exitcode 13015$1 = void 13016(@value{GDBP}) print $_isvoid ($_exitcode) 13017$2 = 1 13018(@value{GDBP}) run 13019Starting program: ./a.out 13020[Inferior 1 (process 29572) exited normally] 13021(@value{GDBP}) print $_exitcode 13022$3 = 0 13023(@value{GDBP}) print $_isvoid ($_exitcode) 13024$4 = 0 13025@end smallexample 13026 13027In the example above, we used @code{$_isvoid} to check whether 13028@code{$_exitcode} is @code{void} before and after the execution of the 13029program being debugged. Before the execution there is no exit code to 13030be examined, therefore @code{$_exitcode} is @code{void}. After the 13031execution the program being debugged returned zero, therefore 13032@code{$_exitcode} is zero, which means that it is not @code{void} 13033anymore. 13034 13035The @code{void} expression can also be a call of a function from the 13036program being debugged. For example, given the following function: 13037 13038@smallexample 13039void 13040foo (void) 13041@{ 13042@} 13043@end smallexample 13044 13045The result of calling it inside @value{GDBN} is @code{void}: 13046 13047@smallexample 13048(@value{GDBP}) print foo () 13049$1 = void 13050(@value{GDBP}) print $_isvoid (foo ()) 13051$2 = 1 13052(@value{GDBP}) set $v = foo () 13053(@value{GDBP}) print $v 13054$3 = void 13055(@value{GDBP}) print $_isvoid ($v) 13056$4 = 1 13057@end smallexample 13058 13059@findex $_gdb_setting_str@r{, convenience function} 13060@item $_gdb_setting_str (@var{setting}) 13061Return the value of the @value{GDBN} @var{setting} as a string. 13062@var{setting} is any setting that can be used in a @code{set} or 13063@code{show} command (@pxref{Controlling GDB}). 13064 13065@smallexample 13066(@value{GDBP}) show print frame-arguments 13067Printing of non-scalar frame arguments is "scalars". 13068(@value{GDBP}) p $_gdb_setting_str("print frame-arguments") 13069$1 = "scalars" 13070(@value{GDBP}) p $_gdb_setting_str("height") 13071$2 = "30" 13072(@value{GDBP}) 13073@end smallexample 13074 13075@findex $_gdb_setting@r{, convenience function} 13076@item $_gdb_setting (@var{setting}) 13077Return the value of the @value{GDBN} @var{setting}. 13078The type of the returned value depends on the setting. 13079 13080The value type for boolean and auto boolean settings is @code{int}. 13081The boolean values @code{off} and @code{on} are converted to 13082the integer values @code{0} and @code{1}. The value @code{auto} is 13083converted to the value @code{-1}. 13084 13085The value type for integer settings is either @code{unsigned int} 13086or @code{int}, depending on the setting. 13087 13088Some integer settings accept an @code{unlimited} value. 13089Depending on the setting, the @code{set} command also accepts 13090the value @code{0} or the value @code{@minus{}1} as a synonym for 13091@code{unlimited}. 13092For example, @code{set height unlimited} is equivalent to 13093@code{set height 0}. 13094 13095Some other settings that accept the @code{unlimited} value 13096use the value @code{0} to literally mean zero. 13097For example, @code{set history size 0} indicates to not 13098record any @value{GDBN} commands in the command history. 13099For such settings, @code{@minus{}1} is the synonym 13100for @code{unlimited}. 13101 13102See the documentation of the corresponding @code{set} command for 13103the numerical value equivalent to @code{unlimited}. 13104 13105The @code{$_gdb_setting} function converts the unlimited value 13106to a @code{0} or a @code{@minus{}1} value according to what the 13107@code{set} command uses. 13108 13109@smallexample 13110@group 13111(@value{GDBP}) p $_gdb_setting_str("height") 13112$1 = "30" 13113(@value{GDBP}) p $_gdb_setting("height") 13114$2 = 30 13115(@value{GDBP}) set height unlimited 13116(@value{GDBP}) p $_gdb_setting_str("height") 13117$3 = "unlimited" 13118(@value{GDBP}) p $_gdb_setting("height") 13119$4 = 0 13120@end group 13121@group 13122(@value{GDBP}) p $_gdb_setting_str("history size") 13123$5 = "unlimited" 13124(@value{GDBP}) p $_gdb_setting("history size") 13125$6 = -1 13126(@value{GDBP}) p $_gdb_setting_str("disassemble-next-line") 13127$7 = "auto" 13128(@value{GDBP}) p $_gdb_setting("disassemble-next-line") 13129$8 = -1 13130(@value{GDBP}) 13131@end group 13132@end smallexample 13133 13134Other setting types (enum, filename, optional filename, string, string noescape) 13135are returned as string values. 13136 13137 13138@findex $_gdb_maint_setting_str@r{, convenience function} 13139@item $_gdb_maint_setting_str (@var{setting}) 13140Like the @code{$_gdb_setting_str} function, but works with 13141@code{maintenance set} variables. 13142 13143@findex $_gdb_maint_setting@r{, convenience function} 13144@item $_gdb_maint_setting (@var{setting}) 13145Like the @code{$_gdb_setting} function, but works with 13146@code{maintenance set} variables. 13147 13148@anchor{$_shell convenience function} 13149@findex $_shell@r{, convenience function} 13150@item $_shell (@var{command-string}) 13151 13152Invoke a shell to execute @var{command-string}. @var{command-string} 13153must be a string. The shell runs on the host machine, the machine 13154@value{GDBN} is running on. Returns the command's exit status. On 13155Unix systems, a command which exits with a zero exit status has 13156succeeded, and non-zero exit status indicates failure. When a command 13157terminates on a fatal signal whose number is @var{N}, @value{GDBN} 13158uses the value 128+@var{N} as the exit status, as is standard in Unix 13159shells. Note that @var{N} is a host signal number, not a target 13160signal number. If you're native debugging, they will be the same, but 13161if cross debugging, the host vs target signal numbers may be 13162completely unrelated. Please consult your host operating system's 13163documentation for the mapping between host signal numbers and signal 13164names. The shell to run is determined in the same way as for the 13165@code{shell} command. @xref{Shell Commands, ,Shell Commands}. 13166 13167@smallexample 13168(@value{GDBP}) print $_shell("true") 13169$1 = 0 13170(@value{GDBP}) print $_shell("false") 13171$2 = 1 13172(@value{GDBP}) p $_shell("echo hello") 13173hello 13174$3 = 0 13175(@value{GDBP}) p $_shell("foobar") 13176bash: line 1: foobar: command not found 13177$4 = 127 13178@end smallexample 13179 13180This may also be useful in breakpoint conditions. For example: 13181 13182@smallexample 13183(@value{GDBP}) break function if $_shell("some command") == 0 13184@end smallexample 13185 13186In this scenario, you'll want to make sure that the shell command you 13187run in the breakpoint condition takes the least amount of time 13188possible. For example, avoid running a command that may block 13189indefinitely, or that sleeps for a while before exiting. Prefer a 13190command or script which analyzes some state and exits immediately. 13191This is important because the debugged program stops for the 13192breakpoint every time, and then @value{GDBN} evaluates the breakpoint 13193condition. If the condition is false, the program is re-resumed 13194transparently, without informing you of the stop. A quick shell 13195command thus avoids significantly slowing down the debugged program 13196unnecessarily. 13197 13198Note: unlike the @code{shell} command, the @code{$_shell} convenience 13199function does not affect the @code{$_shell_exitcode} and 13200@code{$_shell_exitsignal} convenience variables. 13201 13202@end table 13203 13204The following functions require @value{GDBN} to be configured with 13205@code{Python} support. 13206 13207@table @code 13208 13209@findex $_memeq@r{, convenience function} 13210@item $_memeq(@var{buf1}, @var{buf2}, @var{length}) 13211Returns one if the @var{length} bytes at the addresses given by 13212@var{buf1} and @var{buf2} are equal. 13213Otherwise it returns zero. 13214 13215@findex $_regex@r{, convenience function} 13216@item $_regex(@var{str}, @var{regex}) 13217Returns one if the string @var{str} matches the regular expression 13218@var{regex}. Otherwise it returns zero. 13219The syntax of the regular expression is that specified by @code{Python}'s 13220regular expression support. 13221 13222@findex $_streq@r{, convenience function} 13223@item $_streq(@var{str1}, @var{str2}) 13224Returns one if the strings @var{str1} and @var{str2} are equal. 13225Otherwise it returns zero. 13226 13227@findex $_strlen@r{, convenience function} 13228@item $_strlen(@var{str}) 13229Returns the length of string @var{str}. 13230 13231@findex $_caller_is@r{, convenience function} 13232@item $_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]}) 13233Returns one if the calling function's name is equal to @var{name}. 13234Otherwise it returns zero. 13235 13236If the optional argument @var{number_of_frames} is provided, 13237it is the number of frames up in the stack to look. 13238The default is 1. 13239 13240Example: 13241 13242@smallexample 13243(@value{GDBP}) backtrace 13244#0 bottom_func () 13245 at testsuite/gdb.python/py-caller-is.c:21 13246#1 0x00000000004005a0 in middle_func () 13247 at testsuite/gdb.python/py-caller-is.c:27 13248#2 0x00000000004005ab in top_func () 13249 at testsuite/gdb.python/py-caller-is.c:33 13250#3 0x00000000004005b6 in main () 13251 at testsuite/gdb.python/py-caller-is.c:39 13252(@value{GDBP}) print $_caller_is ("middle_func") 13253$1 = 1 13254(@value{GDBP}) print $_caller_is ("top_func", 2) 13255$1 = 1 13256@end smallexample 13257 13258@findex $_caller_matches@r{, convenience function} 13259@item $_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]}) 13260Returns one if the calling function's name matches the regular expression 13261@var{regexp}. Otherwise it returns zero. 13262 13263If the optional argument @var{number_of_frames} is provided, 13264it is the number of frames up in the stack to look. 13265The default is 1. 13266 13267@findex $_any_caller_is@r{, convenience function} 13268@item $_any_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]}) 13269Returns one if any calling function's name is equal to @var{name}. 13270Otherwise it returns zero. 13271 13272If the optional argument @var{number_of_frames} is provided, 13273it is the number of frames up in the stack to look. 13274The default is 1. 13275 13276This function differs from @code{$_caller_is} in that this function 13277checks all stack frames from the immediate caller to the frame specified 13278by @var{number_of_frames}, whereas @code{$_caller_is} only checks the 13279frame specified by @var{number_of_frames}. 13280 13281@findex $_any_caller_matches@r{, convenience function} 13282@item $_any_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]}) 13283Returns one if any calling function's name matches the regular expression 13284@var{regexp}. Otherwise it returns zero. 13285 13286If the optional argument @var{number_of_frames} is provided, 13287it is the number of frames up in the stack to look. 13288The default is 1. 13289 13290This function differs from @code{$_caller_matches} in that this function 13291checks all stack frames from the immediate caller to the frame specified 13292by @var{number_of_frames}, whereas @code{$_caller_matches} only checks the 13293frame specified by @var{number_of_frames}. 13294 13295@findex $_as_string@r{, convenience function} 13296@item $_as_string(@var{value}) 13297This convenience function is considered deprecated, and could be 13298removed from future versions of @value{GDBN}. Use the @samp{%V} format 13299specifier instead (@pxref{%V Format Specifier}). 13300 13301Return the string representation of @var{value}. 13302 13303This function is useful to obtain the textual label (enumerator) of an 13304enumeration value. For example, assuming the variable @var{node} is of 13305an enumerated type: 13306 13307@smallexample 13308(@value{GDBP}) printf "Visiting node of type %s\n", $_as_string(node) 13309Visiting node of type NODE_INTEGER 13310@end smallexample 13311 13312@findex $_cimag@r{, convenience function} 13313@findex $_creal@r{, convenience function} 13314@item $_cimag(@var{value}) 13315@itemx $_creal(@var{value}) 13316Return the imaginary (@code{$_cimag}) or real (@code{$_creal}) part of 13317the complex number @var{value}. 13318 13319The type of the imaginary or real part depends on the type of the 13320complex number, e.g., using @code{$_cimag} on a @code{float complex} 13321will return an imaginary part of type @code{float}. 13322 13323@end table 13324 13325@value{GDBN} provides the ability to list and get help on 13326convenience functions. 13327 13328@table @code 13329@item help function 13330@kindex help function 13331@cindex show all convenience functions 13332Print a list of all convenience functions. 13333@end table 13334 13335@node Registers 13336@section Registers 13337 13338@cindex registers 13339You can refer to machine register contents, in expressions, as variables 13340with names starting with @samp{$}. The names of registers are different 13341for each machine; use @code{info registers} to see the names used on 13342your machine. 13343 13344@table @code 13345@kindex info registers 13346@item info registers 13347Print the names and values of all registers except floating-point 13348and vector registers (in the selected stack frame). 13349 13350@kindex info all-registers 13351@cindex floating point registers 13352@item info all-registers 13353Print the names and values of all registers, including floating-point 13354and vector registers (in the selected stack frame). 13355 13356@anchor{info_registers_reggroup} 13357@item info registers @var{reggroup} @dots{} 13358Print the name and value of the registers in each of the specified 13359@var{reggroup}s. The @var{reggroup} can be any of those returned by 13360@code{maint print reggroups} (@pxref{Maintenance Commands}). 13361 13362@item info registers @var{regname} @dots{} 13363Print the @dfn{relativized} value of each specified register @var{regname}. 13364As discussed in detail below, register values are normally relative to 13365the selected stack frame. The @var{regname} may be any register name valid on 13366the machine you are using, with or without the initial @samp{$}. 13367@end table 13368 13369@anchor{standard registers} 13370@cindex stack pointer register 13371@cindex program counter register 13372@cindex process status register 13373@cindex frame pointer register 13374@cindex standard registers 13375@value{GDBN} has four ``standard'' register names that are available (in 13376expressions) on most machines---whenever they do not conflict with an 13377architecture's canonical mnemonics for registers. The register names 13378@code{$pc} and @code{$sp} are used for the program counter register and 13379the stack pointer. @code{$fp} is used for a register that contains a 13380pointer to the current stack frame, and @code{$ps} is used for a 13381register that contains the processor status. For example, 13382you could print the program counter in hex with 13383 13384@smallexample 13385p/x $pc 13386@end smallexample 13387 13388@noindent 13389or print the instruction to be executed next with 13390 13391@smallexample 13392x/i $pc 13393@end smallexample 13394 13395@noindent 13396or add four to the stack pointer@footnote{This is a way of removing 13397one word from the stack, on machines where stacks grow downward in 13398memory (most machines, nowadays). This assumes that the innermost 13399stack frame is selected; setting @code{$sp} is not allowed when other 13400stack frames are selected. To pop entire frames off the stack, 13401regardless of machine architecture, use @code{return}; 13402see @ref{Returning, ,Returning from a Function}.} with 13403 13404@smallexample 13405set $sp += 4 13406@end smallexample 13407 13408Whenever possible, these four standard register names are available on 13409your machine even though the machine has different canonical mnemonics, 13410so long as there is no conflict. The @code{info registers} command 13411shows the canonical names. For example, on the SPARC, @code{info 13412registers} displays the processor status register as @code{$psr} but you 13413can also refer to it as @code{$ps}; and on x86-based machines @code{$ps} 13414is an alias for the @sc{eflags} register. 13415 13416@value{GDBN} always considers the contents of an ordinary register as an 13417integer when the register is examined in this way. Some machines have 13418special registers which can hold nothing but floating point; these 13419registers are considered to have floating point values. There is no way 13420to refer to the contents of an ordinary register as floating point value 13421(although you can @emph{print} it as a floating point value with 13422@samp{print/f $@var{regname}}). 13423 13424Some registers have distinct ``raw'' and ``virtual'' data formats. This 13425means that the data format in which the register contents are saved by 13426the operating system is not the same one that your program normally 13427sees. For example, the registers of the 68881 floating point 13428coprocessor are always saved in ``extended'' (raw) format, but all C 13429programs expect to work with ``double'' (virtual) format. In such 13430cases, @value{GDBN} normally works with the virtual format only (the format 13431that makes sense for your program), but the @code{info registers} command 13432prints the data in both formats. 13433 13434@cindex SSE registers (x86) 13435@cindex MMX registers (x86) 13436Some machines have special registers whose contents can be interpreted 13437in several different ways. For example, modern x86-based machines 13438have SSE and MMX registers that can hold several values packed 13439together in several different formats. @value{GDBN} refers to such 13440registers in @code{struct} notation: 13441 13442@smallexample 13443(@value{GDBP}) print $xmm1 13444$1 = @{ 13445 v4_float = @{0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044@}, 13446 v2_double = @{9.92129282474342e-303, 2.7585945287983262e-313@}, 13447 v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000", 13448 v8_int16 = @{0, 0, 14072, 315, 11, 0, 13, 0@}, 13449 v4_int32 = @{0, 20657912, 11, 13@}, 13450 v2_int64 = @{88725056443645952, 55834574859@}, 13451 uint128 = 0x0000000d0000000b013b36f800000000 13452@} 13453@end smallexample 13454 13455@noindent 13456To set values of such registers, you need to tell @value{GDBN} which 13457view of the register you wish to change, as if you were assigning 13458value to a @code{struct} member: 13459 13460@smallexample 13461 (@value{GDBP}) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF 13462@end smallexample 13463 13464Normally, register values are relative to the selected stack frame 13465(@pxref{Selection, ,Selecting a Frame}). This means that you get the 13466value that the register would contain if all stack frames farther in 13467were exited and their saved registers restored. In order to see the 13468true contents of hardware registers, you must select the innermost 13469frame (with @samp{frame 0}). 13470 13471@cindex caller-saved registers 13472@cindex call-clobbered registers 13473@cindex volatile registers 13474@cindex <not saved> values 13475Usually ABIs reserve some registers as not needed to be saved by the 13476callee (a.k.a.: ``caller-saved'', ``call-clobbered'' or ``volatile'' 13477registers). It may therefore not be possible for @value{GDBN} to know 13478the value a register had before the call (in other words, in the outer 13479frame), if the register value has since been changed by the callee. 13480@value{GDBN} tries to deduce where the inner frame saved 13481(``callee-saved'') registers, from the debug info, unwind info, or the 13482machine code generated by your compiler. If some register is not 13483saved, and @value{GDBN} knows the register is ``caller-saved'' (via 13484its own knowledge of the ABI, or because the debug/unwind info 13485explicitly says the register's value is undefined), @value{GDBN} 13486displays @w{@samp{<not saved>}} as the register's value. With targets 13487that @value{GDBN} has no knowledge of the register saving convention, 13488if a register was not saved by the callee, then its value and location 13489in the outer frame are assumed to be the same of the inner frame. 13490This is usually harmless, because if the register is call-clobbered, 13491the caller either does not care what is in the register after the 13492call, or has code to restore the value that it does care about. Note, 13493however, that if you change such a register in the outer frame, you 13494may also be affecting the inner frame. Also, the more ``outer'' the 13495frame is you're looking at, the more likely a call-clobbered 13496register's value is to be wrong, in the sense that it doesn't actually 13497represent the value the register had just before the call. 13498 13499@node Floating Point Hardware 13500@section Floating Point Hardware 13501@cindex floating point 13502 13503Depending on the configuration, @value{GDBN} may be able to give 13504you more information about the status of the floating point hardware. 13505 13506@table @code 13507@kindex info float 13508@item info float 13509Display hardware-dependent information about the floating 13510point unit. The exact contents and layout vary depending on the 13511floating point chip. Currently, @samp{info float} is supported on 13512the ARM and x86 machines. 13513@end table 13514 13515@node Vector Unit 13516@section Vector Unit 13517@cindex vector unit 13518 13519Depending on the configuration, @value{GDBN} may be able to give you 13520more information about the status of the vector unit. 13521 13522@table @code 13523@kindex info vector 13524@item info vector 13525Display information about the vector unit. The exact contents and 13526layout vary depending on the hardware. 13527@end table 13528 13529@node OS Information 13530@section Operating System Auxiliary Information 13531@cindex OS information 13532 13533@value{GDBN} provides interfaces to useful OS facilities that can help 13534you debug your program. 13535 13536@cindex auxiliary vector 13537@cindex vector, auxiliary 13538Some operating systems supply an @dfn{auxiliary vector} to programs at 13539startup. This is akin to the arguments and environment that you 13540specify for a program, but contains a system-dependent variety of 13541binary values that tell system libraries important details about the 13542hardware, operating system, and process. Each value's purpose is 13543identified by an integer tag; the meanings are well-known but system-specific. 13544Depending on the configuration and operating system facilities, 13545@value{GDBN} may be able to show you this information. For remote 13546targets, this functionality may further depend on the remote stub's 13547support of the @samp{qXfer:auxv:read} packet, see 13548@ref{qXfer auxiliary vector read}. 13549 13550@table @code 13551@kindex info auxv 13552@item info auxv 13553Display the auxiliary vector of the inferior, which can be either a 13554live process or a core dump file. @value{GDBN} prints each tag value 13555numerically, and also shows names and text descriptions for recognized 13556tags. Some values in the vector are numbers, some bit masks, and some 13557pointers to strings or other data. @value{GDBN} displays each value in the 13558most appropriate form for a recognized tag, and in hexadecimal for 13559an unrecognized tag. 13560@end table 13561 13562On some targets, @value{GDBN} can access operating system-specific 13563information and show it to you. The types of information available 13564will differ depending on the type of operating system running on the 13565target. The mechanism used to fetch the data is described in 13566@ref{Operating System Information}. For remote targets, this 13567functionality depends on the remote stub's support of the 13568@samp{qXfer:osdata:read} packet, see @ref{qXfer osdata read}. 13569 13570@table @code 13571@kindex info os 13572@item info os @var{infotype} 13573 13574Display OS information of the requested type. 13575 13576On @sc{gnu}/Linux, the following values of @var{infotype} are valid: 13577 13578@anchor{linux info os infotypes} 13579@table @code 13580@kindex info os cpus 13581@item cpus 13582Display the list of all CPUs/cores. For each CPU/core, @value{GDBN} prints 13583the available fields from /proc/cpuinfo. For each supported architecture 13584different fields are available. Two common entries are processor which gives 13585CPU number and bogomips; a system constant that is calculated during 13586kernel initialization. 13587 13588@kindex info os files 13589@item files 13590Display the list of open file descriptors on the target. For each 13591file descriptor, @value{GDBN} prints the identifier of the process 13592owning the descriptor, the command of the owning process, the value 13593of the descriptor, and the target of the descriptor. 13594 13595@kindex info os modules 13596@item modules 13597Display the list of all loaded kernel modules on the target. For each 13598module, @value{GDBN} prints the module name, the size of the module in 13599bytes, the number of times the module is used, the dependencies of the 13600module, the status of the module, and the address of the loaded module 13601in memory. 13602 13603@kindex info os msg 13604@item msg 13605Display the list of all System V message queues on the target. For each 13606message queue, @value{GDBN} prints the message queue key, the message 13607queue identifier, the access permissions, the current number of bytes 13608on the queue, the current number of messages on the queue, the processes 13609that last sent and received a message on the queue, the user and group 13610of the owner and creator of the message queue, the times at which a 13611message was last sent and received on the queue, and the time at which 13612the message queue was last changed. 13613 13614@kindex info os processes 13615@item processes 13616Display the list of processes on the target. For each process, 13617@value{GDBN} prints the process identifier, the name of the user, the 13618command corresponding to the process, and the list of processor cores 13619that the process is currently running on. (To understand what these 13620properties mean, for this and the following info types, please consult 13621the general @sc{gnu}/Linux documentation.) 13622 13623@kindex info os procgroups 13624@item procgroups 13625Display the list of process groups on the target. For each process, 13626@value{GDBN} prints the identifier of the process group that it belongs 13627to, the command corresponding to the process group leader, the process 13628identifier, and the command line of the process. The list is sorted 13629first by the process group identifier, then by the process identifier, 13630so that processes belonging to the same process group are grouped together 13631and the process group leader is listed first. 13632 13633@kindex info os semaphores 13634@item semaphores 13635Display the list of all System V semaphore sets on the target. For each 13636semaphore set, @value{GDBN} prints the semaphore set key, the semaphore 13637set identifier, the access permissions, the number of semaphores in the 13638set, the user and group of the owner and creator of the semaphore set, 13639and the times at which the semaphore set was operated upon and changed. 13640 13641@kindex info os shm 13642@item shm 13643Display the list of all System V shared-memory regions on the target. 13644For each shared-memory region, @value{GDBN} prints the region key, 13645the shared-memory identifier, the access permissions, the size of the 13646region, the process that created the region, the process that last 13647attached to or detached from the region, the current number of live 13648attaches to the region, and the times at which the region was last 13649attached to, detach from, and changed. 13650 13651@kindex info os sockets 13652@item sockets 13653Display the list of Internet-domain sockets on the target. For each 13654socket, @value{GDBN} prints the address and port of the local and 13655remote endpoints, the current state of the connection, the creator of 13656the socket, the IP address family of the socket, and the type of the 13657connection. 13658 13659@kindex info os threads 13660@item threads 13661Display the list of threads running on the target. For each thread, 13662@value{GDBN} prints the identifier of the process that the thread 13663belongs to, the command of the process, the thread identifier, and the 13664processor core that it is currently running on. The main thread of a 13665process is not listed. 13666@end table 13667 13668@item info os 13669If @var{infotype} is omitted, then list the possible values for 13670@var{infotype} and the kind of OS information available for each 13671@var{infotype}. If the target does not return a list of possible 13672types, this command will report an error. 13673@end table 13674 13675@node Memory Region Attributes 13676@section Memory Region Attributes 13677@cindex memory region attributes 13678 13679@dfn{Memory region attributes} allow you to describe special handling 13680required by regions of your target's memory. @value{GDBN} uses 13681attributes to determine whether to allow certain types of memory 13682accesses; whether to use specific width accesses; and whether to cache 13683target memory. By default the description of memory regions is 13684fetched from the target (if the current target supports this), but the 13685user can override the fetched regions. 13686 13687Defined memory regions can be individually enabled and disabled. When a 13688memory region is disabled, @value{GDBN} uses the default attributes when 13689accessing memory in that region. Similarly, if no memory regions have 13690been defined, @value{GDBN} uses the default attributes when accessing 13691all memory. 13692 13693When a memory region is defined, it is given a number to identify it; 13694to enable, disable, or remove a memory region, you specify that number. 13695 13696@table @code 13697@kindex mem 13698@item mem @var{lower} @var{upper} @var{attributes}@dots{} 13699Define a memory region bounded by @var{lower} and @var{upper} with 13700attributes @var{attributes}@dots{}, and add it to the list of regions 13701monitored by @value{GDBN}. Note that @var{upper} == 0 is a special 13702case: it is treated as the target's maximum memory address. 13703(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.) 13704 13705@item mem auto 13706Discard any user changes to the memory regions and use target-supplied 13707regions, if available, or no regions if the target does not support. 13708 13709@kindex delete mem 13710@item delete mem @var{nums}@dots{} 13711Remove memory regions @var{nums}@dots{} from the list of regions 13712monitored by @value{GDBN}. 13713 13714@kindex disable mem 13715@item disable mem @var{nums}@dots{} 13716Disable monitoring of memory regions @var{nums}@dots{}. 13717A disabled memory region is not forgotten. 13718It may be enabled again later. 13719 13720@kindex enable mem 13721@item enable mem @var{nums}@dots{} 13722Enable monitoring of memory regions @var{nums}@dots{}. 13723 13724@kindex info mem 13725@item info mem 13726Print a table of all defined memory regions, with the following columns 13727for each region: 13728 13729@table @emph 13730@item Memory Region Number 13731@item Enabled or Disabled. 13732Enabled memory regions are marked with @samp{y}. 13733Disabled memory regions are marked with @samp{n}. 13734 13735@item Lo Address 13736The address defining the inclusive lower bound of the memory region. 13737 13738@item Hi Address 13739The address defining the exclusive upper bound of the memory region. 13740 13741@item Attributes 13742The list of attributes set for this memory region. 13743@end table 13744@end table 13745 13746 13747@subsection Attributes 13748 13749@subsubsection Memory Access Mode 13750The access mode attributes set whether @value{GDBN} may make read or 13751write accesses to a memory region. 13752 13753While these attributes prevent @value{GDBN} from performing invalid 13754memory accesses, they do nothing to prevent the target system, I/O DMA, 13755etc.@: from accessing memory. 13756 13757@table @code 13758@item ro 13759Memory is read only. 13760@item wo 13761Memory is write only. 13762@item rw 13763Memory is read/write. This is the default. 13764@end table 13765 13766@subsubsection Memory Access Size 13767The access size attribute tells @value{GDBN} to use specific sized 13768accesses in the memory region. Often memory mapped device registers 13769require specific sized accesses. If no access size attribute is 13770specified, @value{GDBN} may use accesses of any size. 13771 13772@table @code 13773@item 8 13774Use 8 bit memory accesses. 13775@item 16 13776Use 16 bit memory accesses. 13777@item 32 13778Use 32 bit memory accesses. 13779@item 64 13780Use 64 bit memory accesses. 13781@end table 13782 13783@c @subsubsection Hardware/Software Breakpoints 13784@c The hardware/software breakpoint attributes set whether @value{GDBN} 13785@c will use hardware or software breakpoints for the internal breakpoints 13786@c used by the step, next, finish, until, etc. commands. 13787@c 13788@c @table @code 13789@c @item hwbreak 13790@c Always use hardware breakpoints 13791@c @item swbreak (default) 13792@c @end table 13793 13794@subsubsection Data Cache 13795The data cache attributes set whether @value{GDBN} will cache target 13796memory. While this generally improves performance by reducing debug 13797protocol overhead, it can lead to incorrect results because @value{GDBN} 13798does not know about volatile variables or memory mapped device 13799registers. 13800 13801@table @code 13802@item cache 13803Enable @value{GDBN} to cache target memory. 13804@item nocache 13805Disable @value{GDBN} from caching target memory. This is the default. 13806@end table 13807 13808@subsection Memory Access Checking 13809@value{GDBN} can be instructed to refuse accesses to memory that is 13810not explicitly described. This can be useful if accessing such 13811regions has undesired effects for a specific target, or to provide 13812better error checking. The following commands control this behaviour. 13813 13814@table @code 13815@kindex set mem inaccessible-by-default 13816@item set mem inaccessible-by-default [on|off] 13817If @code{on} is specified, make @value{GDBN} treat memory not 13818explicitly described by the memory ranges as non-existent and refuse accesses 13819to such memory. The checks are only performed if there's at least one 13820memory range defined. If @code{off} is specified, make @value{GDBN} 13821treat the memory not explicitly described by the memory ranges as RAM. 13822The default value is @code{on}. 13823@kindex show mem inaccessible-by-default 13824@item show mem inaccessible-by-default 13825Show the current handling of accesses to unknown memory. 13826@end table 13827 13828 13829@c @subsubsection Memory Write Verification 13830@c The memory write verification attributes set whether @value{GDBN} 13831@c will re-reads data after each write to verify the write was successful. 13832@c 13833@c @table @code 13834@c @item verify 13835@c @item noverify (default) 13836@c @end table 13837 13838@node Dump/Restore Files 13839@section Copy Between Memory and a File 13840@cindex dump/restore files 13841@cindex append data to a file 13842@cindex dump data to a file 13843@cindex restore data from a file 13844 13845You can use the commands @code{dump}, @code{append}, and 13846@code{restore} to copy data between target memory and a file. The 13847@code{dump} and @code{append} commands write data to a file, and the 13848@code{restore} command reads data from a file back into the inferior's 13849memory. Files may be in binary, Motorola S-record, Intel hex, 13850Tektronix Hex, or Verilog Hex format; however, @value{GDBN} can only 13851append to binary files, and cannot read from Verilog Hex files. 13852 13853@table @code 13854 13855@kindex dump 13856@item dump @r{[}@var{format}@r{]} memory @var{filename} @var{start_addr} @var{end_addr} 13857@itemx dump @r{[}@var{format}@r{]} value @var{filename} @var{expr} 13858Dump the contents of memory from @var{start_addr} to @var{end_addr}, 13859or the value of @var{expr}, to @var{filename} in the given format. 13860 13861The @var{format} parameter may be any one of: 13862@table @code 13863@item binary 13864Raw binary form. 13865@item ihex 13866Intel hex format. 13867@item srec 13868Motorola S-record format. 13869@item tekhex 13870Tektronix Hex format. 13871@item verilog 13872Verilog Hex format. 13873@end table 13874 13875@value{GDBN} uses the same definitions of these formats as the 13876@sc{gnu} binary utilities, like @samp{objdump} and @samp{objcopy}. If 13877@var{format} is omitted, @value{GDBN} dumps the data in raw binary 13878form. 13879 13880@kindex append 13881@item append @r{[}binary@r{]} memory @var{filename} @var{start_addr} @var{end_addr} 13882@itemx append @r{[}binary@r{]} value @var{filename} @var{expr} 13883Append the contents of memory from @var{start_addr} to @var{end_addr}, 13884or the value of @var{expr}, to the file @var{filename}, in raw binary form. 13885(@value{GDBN} can only append data to files in raw binary form.) 13886 13887@kindex restore 13888@item restore @var{filename} @r{[}binary@r{]} @var{bias} @var{start} @var{end} 13889Restore the contents of file @var{filename} into memory. The 13890@code{restore} command can automatically recognize any known @sc{bfd} 13891file format, except for raw binary. To restore a raw binary file you 13892must specify the optional keyword @code{binary} after the filename. 13893 13894If @var{bias} is non-zero, its value will be added to the addresses 13895contained in the file. Binary files always start at address zero, so 13896they will be restored at address @var{bias}. Other bfd files have 13897a built-in location; they will be restored at offset @var{bias} 13898from that location. 13899 13900If @var{start} and/or @var{end} are non-zero, then only data between 13901file offset @var{start} and file offset @var{end} will be restored. 13902These offsets are relative to the addresses in the file, before 13903the @var{bias} argument is applied. 13904 13905@end table 13906 13907@node Core File Generation 13908@section How to Produce a Core File from Your Program 13909@cindex dump core from inferior 13910 13911A @dfn{core file} or @dfn{core dump} is a file that records the memory 13912image of a running process and its process status (register values 13913etc.). Its primary use is post-mortem debugging of a program that 13914crashed while it ran outside a debugger. A program that crashes 13915automatically produces a core file, unless this feature is disabled by 13916the user. @xref{Files}, for information on invoking @value{GDBN} in 13917the post-mortem debugging mode. 13918 13919Occasionally, you may wish to produce a core file of the program you 13920are debugging in order to preserve a snapshot of its state. 13921@value{GDBN} has a special command for that. 13922 13923@table @code 13924@kindex gcore 13925@kindex generate-core-file 13926@item generate-core-file [@var{file}] 13927@itemx gcore [@var{file}] 13928Produce a core dump of the inferior process. The optional argument 13929@var{file} specifies the file name where to put the core dump. If not 13930specified, the file name defaults to @file{core.@var{pid}}, where 13931@var{pid} is the inferior process ID. 13932 13933If supported by the filesystem where the core is written to, 13934@value{GDBN} generates a sparse core dump file. 13935 13936Note that this command is implemented only for some systems (as of 13937this writing, @sc{gnu}/Linux, FreeBSD, Solaris, and S390). 13938 13939On @sc{gnu}/Linux, this command can take into account the value of the 13940file @file{/proc/@var{pid}/coredump_filter} when generating the core 13941dump (@pxref{set use-coredump-filter}), and by default honors the 13942@code{VM_DONTDUMP} flag for mappings where it is present in the file 13943@file{/proc/@var{pid}/smaps} (@pxref{set dump-excluded-mappings}). 13944 13945@kindex set use-coredump-filter 13946@anchor{set use-coredump-filter} 13947@item set use-coredump-filter on 13948@itemx set use-coredump-filter off 13949Enable or disable the use of the file 13950@file{/proc/@var{pid}/coredump_filter} when generating core dump 13951files. This file is used by the Linux kernel to decide what types of 13952memory mappings will be dumped or ignored when generating a core dump 13953file. @var{pid} is the process ID of a currently running process. 13954 13955To make use of this feature, you have to write in the 13956@file{/proc/@var{pid}/coredump_filter} file a value, in hexadecimal, 13957which is a bit mask representing the memory mapping types. If a bit 13958is set in the bit mask, then the memory mappings of the corresponding 13959types will be dumped; otherwise, they will be ignored. This 13960configuration is inherited by child processes. For more information 13961about the bits that can be set in the 13962@file{/proc/@var{pid}/coredump_filter} file, please refer to the 13963manpage of @code{core(5)}. 13964 13965By default, this option is @code{on}. If this option is turned 13966@code{off}, @value{GDBN} does not read the @file{coredump_filter} file 13967and instead uses the same default value as the Linux kernel in order 13968to decide which pages will be dumped in the core dump file. This 13969value is currently @code{0x33}, which means that bits @code{0} 13970(anonymous private mappings), @code{1} (anonymous shared mappings), 13971@code{4} (ELF headers) and @code{5} (private huge pages) are active. 13972This will cause these memory mappings to be dumped automatically. 13973 13974@kindex set dump-excluded-mappings 13975@anchor{set dump-excluded-mappings} 13976@item set dump-excluded-mappings on 13977@itemx set dump-excluded-mappings off 13978If @code{on} is specified, @value{GDBN} will dump memory mappings 13979marked with the @code{VM_DONTDUMP} flag. This flag is represented in 13980the file @file{/proc/@var{pid}/smaps} with the acronym @code{dd}. 13981 13982The default value is @code{off}. 13983@end table 13984 13985@node Character Sets 13986@section Character Sets 13987@cindex character sets 13988@cindex charset 13989@cindex translating between character sets 13990@cindex host character set 13991@cindex target character set 13992 13993If the program you are debugging uses a different character set to 13994represent characters and strings than the one @value{GDBN} uses itself, 13995@value{GDBN} can automatically translate between the character sets for 13996you. The character set @value{GDBN} uses we call the @dfn{host 13997character set}; the one the inferior program uses we call the 13998@dfn{target character set}. 13999 14000For example, if you are running @value{GDBN} on a @sc{gnu}/Linux system, which 14001uses the ISO Latin 1 character set, but you are using @value{GDBN}'s 14002remote protocol (@pxref{Remote Debugging}) to debug a program 14003running on an IBM mainframe, which uses the @sc{ebcdic} character set, 14004then the host character set is Latin-1, and the target character set is 14005@sc{ebcdic}. If you give @value{GDBN} the command @code{set 14006target-charset EBCDIC-US}, then @value{GDBN} translates between 14007@sc{ebcdic} and Latin 1 as you print character or string values, or use 14008character and string literals in expressions. 14009 14010@value{GDBN} has no way to automatically recognize which character set 14011the inferior program uses; you must tell it, using the @code{set 14012target-charset} command, described below. 14013 14014Here are the commands for controlling @value{GDBN}'s character set 14015support: 14016 14017@table @code 14018@item set target-charset @var{charset} 14019@kindex set target-charset 14020Set the current target character set to @var{charset}. To display the 14021list of supported target character sets, type 14022@kbd{@w{set target-charset @key{TAB}@key{TAB}}}. 14023 14024@item set host-charset @var{charset} 14025@kindex set host-charset 14026Set the current host character set to @var{charset}. 14027 14028By default, @value{GDBN} uses a host character set appropriate to the 14029system it is running on; you can override that default using the 14030@code{set host-charset} command. On some systems, @value{GDBN} cannot 14031automatically determine the appropriate host character set. In this 14032case, @value{GDBN} uses @samp{UTF-8}. 14033 14034@value{GDBN} can only use certain character sets as its host character 14035set. If you type @kbd{@w{set host-charset @key{TAB}@key{TAB}}}, 14036@value{GDBN} will list the host character sets it supports. 14037 14038@item set charset @var{charset} 14039@kindex set charset 14040Set the current host and target character sets to @var{charset}. As 14041above, if you type @kbd{@w{set charset @key{TAB}@key{TAB}}}, 14042@value{GDBN} will list the names of the character sets that can be used 14043for both host and target. 14044 14045@item show charset 14046@kindex show charset 14047Show the names of the current host and target character sets. 14048 14049@item show host-charset 14050@kindex show host-charset 14051Show the name of the current host character set. 14052 14053@item show target-charset 14054@kindex show target-charset 14055Show the name of the current target character set. 14056 14057@item set target-wide-charset @var{charset} 14058@kindex set target-wide-charset 14059Set the current target's wide character set to @var{charset}. This is 14060the character set used by the target's @code{wchar_t} type. To 14061display the list of supported wide character sets, type 14062@kbd{@w{set target-wide-charset @key{TAB}@key{TAB}}}. 14063 14064@item show target-wide-charset 14065@kindex show target-wide-charset 14066Show the name of the current target's wide character set. 14067@end table 14068 14069Here is an example of @value{GDBN}'s character set support in action. 14070Assume that the following source code has been placed in the file 14071@file{charset-test.c}: 14072 14073@smallexample 14074#include <stdio.h> 14075 14076char ascii_hello[] 14077 = @{72, 101, 108, 108, 111, 44, 32, 119, 14078 111, 114, 108, 100, 33, 10, 0@}; 14079char ibm1047_hello[] 14080 = @{200, 133, 147, 147, 150, 107, 64, 166, 14081 150, 153, 147, 132, 90, 37, 0@}; 14082 14083main () 14084@{ 14085 printf ("Hello, world!\n"); 14086@} 14087@end smallexample 14088 14089In this program, @code{ascii_hello} and @code{ibm1047_hello} are arrays 14090containing the string @samp{Hello, world!} followed by a newline, 14091encoded in the @sc{ascii} and @sc{ibm1047} character sets. 14092 14093We compile the program, and invoke the debugger on it: 14094 14095@smallexample 14096$ gcc -g charset-test.c -o charset-test 14097$ gdb -nw charset-test 14098GNU gdb 2001-12-19-cvs 14099Copyright 2001 Free Software Foundation, Inc. 14100@dots{} 14101(@value{GDBP}) 14102@end smallexample 14103 14104We can use the @code{show charset} command to see what character sets 14105@value{GDBN} is currently using to interpret and display characters and 14106strings: 14107 14108@smallexample 14109(@value{GDBP}) show charset 14110The current host and target character set is `ISO-8859-1'. 14111(@value{GDBP}) 14112@end smallexample 14113 14114For the sake of printing this manual, let's use @sc{ascii} as our 14115initial character set: 14116@smallexample 14117(@value{GDBP}) set charset ASCII 14118(@value{GDBP}) show charset 14119The current host and target character set is `ASCII'. 14120(@value{GDBP}) 14121@end smallexample 14122 14123Let's assume that @sc{ascii} is indeed the correct character set for our 14124host system --- in other words, let's assume that if @value{GDBN} prints 14125characters using the @sc{ascii} character set, our terminal will display 14126them properly. Since our current target character set is also 14127@sc{ascii}, the contents of @code{ascii_hello} print legibly: 14128 14129@smallexample 14130(@value{GDBP}) print ascii_hello 14131$1 = 0x401698 "Hello, world!\n" 14132(@value{GDBP}) print ascii_hello[0] 14133$2 = 72 'H' 14134(@value{GDBP}) 14135@end smallexample 14136 14137@value{GDBN} uses the target character set for character and string 14138literals you use in expressions: 14139 14140@smallexample 14141(@value{GDBP}) print '+' 14142$3 = 43 '+' 14143(@value{GDBP}) 14144@end smallexample 14145 14146The @sc{ascii} character set uses the number 43 to encode the @samp{+} 14147character. 14148 14149@value{GDBN} relies on the user to tell it which character set the 14150target program uses. If we print @code{ibm1047_hello} while our target 14151character set is still @sc{ascii}, we get jibberish: 14152 14153@smallexample 14154(@value{GDBP}) print ibm1047_hello 14155$4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%" 14156(@value{GDBP}) print ibm1047_hello[0] 14157$5 = 200 '\310' 14158(@value{GDBP}) 14159@end smallexample 14160 14161If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB}, 14162@value{GDBN} tells us the character sets it supports: 14163 14164@smallexample 14165(@value{GDBP}) set target-charset 14166ASCII EBCDIC-US IBM1047 ISO-8859-1 14167(@value{GDBP}) set target-charset 14168@end smallexample 14169 14170We can select @sc{ibm1047} as our target character set, and examine the 14171program's strings again. Now the @sc{ascii} string is wrong, but 14172@value{GDBN} translates the contents of @code{ibm1047_hello} from the 14173target character set, @sc{ibm1047}, to the host character set, 14174@sc{ascii}, and they display correctly: 14175 14176@smallexample 14177(@value{GDBP}) set target-charset IBM1047 14178(@value{GDBP}) show charset 14179The current host character set is `ASCII'. 14180The current target character set is `IBM1047'. 14181(@value{GDBP}) print ascii_hello 14182$6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" 14183(@value{GDBP}) print ascii_hello[0] 14184$7 = 72 '\110' 14185(@value{GDBP}) print ibm1047_hello 14186$8 = 0x4016a8 "Hello, world!\n" 14187(@value{GDBP}) print ibm1047_hello[0] 14188$9 = 200 'H' 14189(@value{GDBP}) 14190@end smallexample 14191 14192As above, @value{GDBN} uses the target character set for character and 14193string literals you use in expressions: 14194 14195@smallexample 14196(@value{GDBP}) print '+' 14197$10 = 78 '+' 14198(@value{GDBP}) 14199@end smallexample 14200 14201The @sc{ibm1047} character set uses the number 78 to encode the @samp{+} 14202character. 14203 14204@node Caching Target Data 14205@section Caching Data of Targets 14206@cindex caching data of targets 14207 14208@value{GDBN} caches data exchanged between the debugger and a target. 14209Each cache is associated with the address space of the inferior. 14210@xref{Inferiors Connections and Programs}, about inferior and address space. 14211Such caching generally improves performance in remote debugging 14212(@pxref{Remote Debugging}), because it reduces the overhead of the 14213remote protocol by bundling memory reads and writes into large chunks. 14214Unfortunately, simply caching everything would lead to incorrect results, 14215since @value{GDBN} does not necessarily know anything about volatile 14216values, memory-mapped I/O addresses, etc. Furthermore, in non-stop mode 14217(@pxref{Non-Stop Mode}) memory can be changed @emph{while} a gdb command 14218is executing. 14219Therefore, by default, @value{GDBN} only caches data 14220known to be on the stack@footnote{In non-stop mode, it is moderately 14221rare for a running thread to modify the stack of a stopped thread 14222in a way that would interfere with a backtrace, and caching of 14223stack reads provides a significant speed up of remote backtraces.} or 14224in the code segment. 14225Other regions of memory can be explicitly marked as 14226cacheable; @pxref{Memory Region Attributes}. 14227 14228@table @code 14229@kindex set remotecache 14230@item set remotecache on 14231@itemx set remotecache off 14232This option no longer does anything; it exists for compatibility 14233with old scripts. 14234 14235@kindex show remotecache 14236@item show remotecache 14237Show the current state of the obsolete remotecache flag. 14238 14239@kindex set stack-cache 14240@item set stack-cache on 14241@itemx set stack-cache off 14242Enable or disable caching of stack accesses. When @code{on}, use 14243caching. By default, this option is @code{on}. 14244 14245@kindex show stack-cache 14246@item show stack-cache 14247Show the current state of data caching for memory accesses. 14248 14249@kindex set code-cache 14250@item set code-cache on 14251@itemx set code-cache off 14252Enable or disable caching of code segment accesses. When @code{on}, 14253use caching. By default, this option is @code{on}. This improves 14254performance of disassembly in remote debugging. 14255 14256@kindex show code-cache 14257@item show code-cache 14258Show the current state of target memory cache for code segment 14259accesses. 14260 14261@kindex info dcache 14262@item info dcache @r{[}line@r{]} 14263Print the information about the performance of data cache of the 14264current inferior's address space. The information displayed 14265includes the dcache width and depth, and for each cache line, its 14266number, address, and how many times it was referenced. This 14267command is useful for debugging the data cache operation. 14268 14269If a line number is specified, the contents of that line will be 14270printed in hex. 14271 14272@item set dcache size @var{size} 14273@cindex dcache size 14274@kindex set dcache size 14275Set maximum number of entries in dcache (dcache depth above). 14276 14277@item set dcache line-size @var{line-size} 14278@cindex dcache line-size 14279@kindex set dcache line-size 14280Set number of bytes each dcache entry caches (dcache width above). 14281Must be a power of 2. 14282 14283@item show dcache size 14284@kindex show dcache size 14285Show maximum number of dcache entries. @xref{Caching Target Data, info dcache}. 14286 14287@item show dcache line-size 14288@kindex show dcache line-size 14289Show default size of dcache lines. 14290 14291@item maint flush dcache 14292@cindex dcache, flushing 14293@kindex maint flush dcache 14294Flush the contents (if any) of the dcache. This maintainer command is 14295useful when debugging the dcache implementation. 14296 14297@end table 14298 14299@node Searching Memory 14300@section Search Memory 14301@cindex searching memory 14302 14303Memory can be searched for a particular sequence of bytes with the 14304@code{find} command. 14305 14306@table @code 14307@kindex find 14308@item find @r{[}/@var{sn}@r{]} @var{start_addr}, +@var{len}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]} 14309@itemx find @r{[}/@var{sn}@r{]} @var{start_addr}, @var{end_addr}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]} 14310Search memory for the sequence of bytes specified by @var{val1}, @var{val2}, 14311etc. The search begins at address @var{start_addr} and continues for either 14312@var{len} bytes or through to @var{end_addr} inclusive. 14313@end table 14314 14315@var{s} and @var{n} are optional parameters. 14316They may be specified in either order, apart or together. 14317 14318@table @r 14319@item @var{s}, search query size 14320The size of each search query value. 14321 14322@table @code 14323@item b 14324bytes 14325@item h 14326halfwords (two bytes) 14327@item w 14328words (four bytes) 14329@item g 14330giant words (eight bytes) 14331@end table 14332 14333All values are interpreted in the current language. 14334This means, for example, that if the current source language is C/C@t{++} 14335then searching for the string ``hello'' includes the trailing '\0'. 14336The null terminator can be removed from searching by using casts, 14337e.g.: @samp{@{char[5]@}"hello"}. 14338 14339If the value size is not specified, it is taken from the 14340value's type in the current language. 14341This is useful when one wants to specify the search 14342pattern as a mixture of types. 14343Note that this means, for example, that in the case of C-like languages 14344a search for an untyped 0x42 will search for @samp{(int) 0x42} 14345which is typically four bytes. 14346 14347@item @var{n}, maximum number of finds 14348The maximum number of matches to print. The default is to print all finds. 14349@end table 14350 14351You can use strings as search values. Quote them with double-quotes 14352 (@code{"}). 14353The string value is copied into the search pattern byte by byte, 14354regardless of the endianness of the target and the size specification. 14355 14356The address of each match found is printed as well as a count of the 14357number of matches found. 14358 14359The address of the last value found is stored in convenience variable 14360@samp{$_}. 14361A count of the number of matches is stored in @samp{$numfound}. 14362 14363For example, if stopped at the @code{printf} in this function: 14364 14365@smallexample 14366void 14367hello () 14368@{ 14369 static char hello[] = "hello-hello"; 14370 static struct @{ char c; short s; int i; @} 14371 __attribute__ ((packed)) mixed 14372 = @{ 'c', 0x1234, 0x87654321 @}; 14373 printf ("%s\n", hello); 14374@} 14375@end smallexample 14376 14377@noindent 14378you get during debugging: 14379 14380@smallexample 14381(@value{GDBP}) find &hello[0], +sizeof(hello), "hello" 143820x804956d <hello.1620+6> 143831 pattern found 14384(@value{GDBP}) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o' 143850x8049567 <hello.1620> 143860x804956d <hello.1620+6> 143872 patterns found. 14388(@value{GDBP}) find &hello[0], +sizeof(hello), @{char[5]@}"hello" 143890x8049567 <hello.1620> 143900x804956d <hello.1620+6> 143912 patterns found. 14392(@value{GDBP}) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l' 143930x8049567 <hello.1620> 143941 pattern found 14395(@value{GDBP}) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321 143960x8049560 <mixed.1625> 143971 pattern found 14398(@value{GDBP}) print $numfound 14399$1 = 1 14400(@value{GDBP}) print $_ 14401$2 = (void *) 0x8049560 14402@end smallexample 14403 14404@node Value Sizes 14405@section Value Sizes 14406 14407Whenever @value{GDBN} prints a value memory will be allocated within 14408@value{GDBN} to hold the contents of the value. It is possible in 14409some languages with dynamic typing systems, that an invalid program 14410may indicate a value that is incorrectly large, this in turn may cause 14411@value{GDBN} to try and allocate an overly large amount of memory. 14412 14413@table @code 14414@anchor{set max-value-size} 14415@kindex set max-value-size 14416@item set max-value-size @var{bytes} 14417@itemx set max-value-size unlimited 14418Set the maximum size of memory that @value{GDBN} will allocate for the 14419contents of a value to @var{bytes}, trying to display a value that 14420requires more memory than that will result in an error. 14421 14422Setting this variable does not effect values that have already been 14423allocated within @value{GDBN}, only future allocations. 14424 14425There's a minimum size that @code{max-value-size} can be set to in 14426order that @value{GDBN} can still operate correctly, this minimum is 14427currently 16 bytes. 14428 14429The limit applies to the results of some subexpressions as well as to 14430complete expressions. For example, an expression denoting a simple 14431integer component, such as @code{x.y.z}, may fail if the size of 14432@var{x.y} is dynamic and exceeds @var{bytes}. On the other hand, 14433@value{GDBN} is sometimes clever; the expression @code{A[i]}, where 14434@var{A} is an array variable with non-constant size, will generally 14435succeed regardless of the bounds on @var{A}, as long as the component 14436size is less than @var{bytes}. 14437 14438The default value of @code{max-value-size} is currently 64k. 14439 14440@kindex show max-value-size 14441@item show max-value-size 14442Show the maximum size of memory, in bytes, that @value{GDBN} will 14443allocate for the contents of a value. 14444@end table 14445 14446@node Optimized Code 14447@chapter Debugging Optimized Code 14448@cindex optimized code, debugging 14449@cindex debugging optimized code 14450 14451Almost all compilers support optimization. With optimization 14452disabled, the compiler generates assembly code that corresponds 14453directly to your source code, in a simplistic way. As the compiler 14454applies more powerful optimizations, the generated assembly code 14455diverges from your original source code. With help from debugging 14456information generated by the compiler, @value{GDBN} can map from 14457the running program back to constructs from your original source. 14458 14459@value{GDBN} is more accurate with optimization disabled. If you 14460can recompile without optimization, it is easier to follow the 14461progress of your program during debugging. But, there are many cases 14462where you may need to debug an optimized version. 14463 14464When you debug a program compiled with @samp{-g -O}, remember that the 14465optimizer has rearranged your code; the debugger shows you what is 14466really there. Do not be too surprised when the execution path does not 14467exactly match your source file! An extreme example: if you define a 14468variable, but never use it, @value{GDBN} never sees that 14469variable---because the compiler optimizes it out of existence. 14470 14471Some things do not work as well with @samp{-g -O} as with just 14472@samp{-g}, particularly on machines with instruction scheduling. If in 14473doubt, recompile with @samp{-g} alone, and if this fixes the problem, 14474please report it to us as a bug (including a test case!). 14475@xref{Variables}, for more information about debugging optimized code. 14476 14477@menu 14478* Inline Functions:: How @value{GDBN} presents inlining 14479* Tail Call Frames:: @value{GDBN} analysis of jumps to functions 14480@end menu 14481 14482@node Inline Functions 14483@section Inline Functions 14484@cindex inline functions, debugging 14485 14486@dfn{Inlining} is an optimization that inserts a copy of the function 14487body directly at each call site, instead of jumping to a shared 14488routine. @value{GDBN} displays inlined functions just like 14489non-inlined functions. They appear in backtraces. You can view their 14490arguments and local variables, step into them with @code{step}, skip 14491them with @code{next}, and escape from them with @code{finish}. 14492You can check whether a function was inlined by using the 14493@code{info frame} command. 14494 14495For @value{GDBN} to support inlined functions, the compiler must 14496record information about inlining in the debug information --- 14497@value{NGCC} using the @sc{dwarf 2} format does this, and several 14498other compilers do also. @value{GDBN} only supports inlined functions 14499when using @sc{dwarf 2}. Versions of @value{NGCC} before 4.1 14500do not emit two required attributes (@samp{DW_AT_call_file} and 14501@samp{DW_AT_call_line}); @value{GDBN} does not display inlined 14502function calls with earlier versions of @value{NGCC}. It instead 14503displays the arguments and local variables of inlined functions as 14504local variables in the caller. 14505 14506The body of an inlined function is directly included at its call site; 14507unlike a non-inlined function, there are no instructions devoted to 14508the call. @value{GDBN} still pretends that the call site and the 14509start of the inlined function are different instructions. Stepping to 14510the call site shows the call site, and then stepping again shows 14511the first line of the inlined function, even though no additional 14512instructions are executed. 14513 14514This makes source-level debugging much clearer; you can see both the 14515context of the call and then the effect of the call. Only stepping by 14516a single instruction using @code{stepi} or @code{nexti} does not do 14517this; single instruction steps always show the inlined body. 14518 14519There are some ways that @value{GDBN} does not pretend that inlined 14520function calls are the same as normal calls: 14521 14522@itemize @bullet 14523@item 14524Setting breakpoints at the call site of an inlined function may not 14525work, because the call site does not contain any code. @value{GDBN} 14526may incorrectly move the breakpoint to the next line of the enclosing 14527function, after the call. This limitation will be removed in a future 14528version of @value{GDBN}; until then, set a breakpoint on an earlier line 14529or inside the inlined function instead. 14530 14531@item 14532@value{GDBN} cannot locate the return value of inlined calls after 14533using the @code{finish} command. This is a limitation of compiler-generated 14534debugging information; after @code{finish}, you can step to the next line 14535and print a variable where your program stored the return value. 14536 14537@end itemize 14538 14539@node Tail Call Frames 14540@section Tail Call Frames 14541@cindex tail call frames, debugging 14542 14543Function @code{B} can call function @code{C} in its very last statement. In 14544unoptimized compilation the call of @code{C} is immediately followed by return 14545instruction at the end of @code{B} code. Optimizing compiler may replace the 14546call and return in function @code{B} into one jump to function @code{C} 14547instead. Such use of a jump instruction is called @dfn{tail call}. 14548 14549During execution of function @code{C}, there will be no indication in the 14550function call stack frames that it was tail-called from @code{B}. If function 14551@code{A} regularly calls function @code{B} which tail-calls function @code{C}, 14552then @value{GDBN} will see @code{A} as the caller of @code{C}. However, in 14553some cases @value{GDBN} can determine that @code{C} was tail-called from 14554@code{B}, and it will then create fictitious call frame for that, with the 14555return address set up as if @code{B} called @code{C} normally. 14556 14557This functionality is currently supported only by DWARF 2 debugging format and 14558the compiler has to produce @samp{DW_TAG_call_site} tags. With 14559@value{NGCC}, you need to specify @option{-O -g} during compilation, to get 14560this information. 14561 14562@kbd{info frame} command (@pxref{Frame Info}) will indicate the tail call frame 14563kind by text @code{tail call frame} such as in this sample @value{GDBN} output: 14564 14565@smallexample 14566(@value{GDBP}) x/i $pc - 2 14567 0x40066b <b(int, double)+11>: jmp 0x400640 <c(int, double)> 14568(@value{GDBP}) info frame 14569Stack level 1, frame at 0x7fffffffda30: 14570 rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5 14571 tail call frame, caller of frame at 0x7fffffffda30 14572 source language c++. 14573 Arglist at unknown address. 14574 Locals at unknown address, Previous frame's sp is 0x7fffffffda30 14575@end smallexample 14576 14577The detection of all the possible code path executions can find them ambiguous. 14578There is no execution history stored (possible @ref{Reverse Execution} is never 14579used for this purpose) and the last known caller could have reached the known 14580callee by multiple different jump sequences. In such case @value{GDBN} still 14581tries to show at least all the unambiguous top tail callers and all the 14582unambiguous bottom tail callees, if any. 14583 14584@table @code 14585@anchor{set debug entry-values} 14586@item set debug entry-values 14587@kindex set debug entry-values 14588When set to on, enables printing of analysis messages for both frame argument 14589values at function entry and tail calls. It will show all the possible valid 14590tail calls code paths it has considered. It will also print the intersection 14591of them with the final unambiguous (possibly partial or even empty) code path 14592result. 14593 14594@item show debug entry-values 14595@kindex show debug entry-values 14596Show the current state of analysis messages printing for both frame argument 14597values at function entry and tail calls. 14598@end table 14599 14600The analysis messages for tail calls can for example show why the virtual tail 14601call frame for function @code{c} has not been recognized (due to the indirect 14602reference by variable @code{x}): 14603 14604@smallexample 14605static void __attribute__((noinline, noclone)) c (void); 14606void (*x) (void) = c; 14607static void __attribute__((noinline, noclone)) a (void) @{ x++; @} 14608static void __attribute__((noinline, noclone)) c (void) @{ a (); @} 14609int main (void) @{ x (); return 0; @} 14610 14611Breakpoint 1, DW_OP_entry_value resolving cannot find 14612DW_TAG_call_site 0x40039a in main 14613a () at t.c:3 146143 static void __attribute__((noinline, noclone)) a (void) @{ x++; @} 14615(@value{GDBP}) bt 14616#0 a () at t.c:3 14617#1 0x000000000040039a in main () at t.c:5 14618@end smallexample 14619 14620Another possibility is an ambiguous virtual tail call frames resolution: 14621 14622@smallexample 14623int i; 14624static void __attribute__((noinline, noclone)) f (void) @{ i++; @} 14625static void __attribute__((noinline, noclone)) e (void) @{ f (); @} 14626static void __attribute__((noinline, noclone)) d (void) @{ f (); @} 14627static void __attribute__((noinline, noclone)) c (void) @{ d (); @} 14628static void __attribute__((noinline, noclone)) b (void) 14629@{ if (i) c (); else e (); @} 14630static void __attribute__((noinline, noclone)) a (void) @{ b (); @} 14631int main (void) @{ a (); return 0; @} 14632 14633tailcall: initial: 0x4004d2(a) 0x4004ce(b) 0x4004b2(c) 0x4004a2(d) 14634tailcall: compare: 0x4004d2(a) 0x4004cc(b) 0x400492(e) 14635tailcall: reduced: 0x4004d2(a) | 14636(@value{GDBP}) bt 14637#0 f () at t.c:2 14638#1 0x00000000004004d2 in a () at t.c:8 14639#2 0x0000000000400395 in main () at t.c:9 14640@end smallexample 14641 14642@set CALLSEQ1A @code{main@value{ARROW}a@value{ARROW}b@value{ARROW}c@value{ARROW}d@value{ARROW}f} 14643@set CALLSEQ2A @code{main@value{ARROW}a@value{ARROW}b@value{ARROW}e@value{ARROW}f} 14644 14645@c Convert CALLSEQ#A to CALLSEQ#B depending on HAVE_MAKEINFO_CLICK. 14646@ifset HAVE_MAKEINFO_CLICK 14647@set ARROW @click{} 14648@set CALLSEQ1B @clicksequence{@value{CALLSEQ1A}} 14649@set CALLSEQ2B @clicksequence{@value{CALLSEQ2A}} 14650@end ifset 14651@ifclear HAVE_MAKEINFO_CLICK 14652@set ARROW -> 14653@set CALLSEQ1B @value{CALLSEQ1A} 14654@set CALLSEQ2B @value{CALLSEQ2A} 14655@end ifclear 14656 14657Frames #0 and #2 are real, #1 is a virtual tail call frame. 14658The code can have possible execution paths @value{CALLSEQ1B} or 14659@value{CALLSEQ2B}, @value{GDBN} cannot find which one from the inferior state. 14660 14661@code{initial:} state shows some random possible calling sequence @value{GDBN} 14662has found. It then finds another possible calling sequence - that one is 14663prefixed by @code{compare:}. The non-ambiguous intersection of these two is 14664printed as the @code{reduced:} calling sequence. That one could have many 14665further @code{compare:} and @code{reduced:} statements as long as there remain 14666any non-ambiguous sequence entries. 14667 14668For the frame of function @code{b} in both cases there are different possible 14669@code{$pc} values (@code{0x4004cc} or @code{0x4004ce}), therefore this frame is 14670also ambiguous. The only non-ambiguous frame is the one for function @code{a}, 14671therefore this one is displayed to the user while the ambiguous frames are 14672omitted. 14673 14674There can be also reasons why printing of frame argument values at function 14675entry may fail: 14676 14677@smallexample 14678int v; 14679static void __attribute__((noinline, noclone)) c (int i) @{ v++; @} 14680static void __attribute__((noinline, noclone)) a (int i); 14681static void __attribute__((noinline, noclone)) b (int i) @{ a (i); @} 14682static void __attribute__((noinline, noclone)) a (int i) 14683@{ if (i) b (i - 1); else c (0); @} 14684int main (void) @{ a (5); return 0; @} 14685 14686(@value{GDBP}) bt 14687#0 c (i=i@@entry=0) at t.c:2 14688#1 0x0000000000400428 in a (DW_OP_entry_value resolving has found 14689function "a" at 0x400420 can call itself via tail calls 14690i=<optimized out>) at t.c:6 14691#2 0x000000000040036e in main () at t.c:7 14692@end smallexample 14693 14694@value{GDBN} cannot find out from the inferior state if and how many times did 14695function @code{a} call itself (via function @code{b}) as these calls would be 14696tail calls. Such tail calls would modify the @code{i} variable, therefore 14697@value{GDBN} cannot be sure the value it knows would be right - @value{GDBN} 14698prints @code{<optimized out>} instead. 14699 14700@node Macros 14701@chapter C Preprocessor Macros 14702 14703Some languages, such as C and C@t{++}, provide a way to define and invoke 14704``preprocessor macros'' which expand into strings of tokens. 14705@value{GDBN} can evaluate expressions containing macro invocations, show 14706the result of macro expansion, and show a macro's definition, including 14707where it was defined. 14708 14709You may need to compile your program specially to provide @value{GDBN} 14710with information about preprocessor macros. Most compilers do not 14711include macros in their debugging information, even when you compile 14712with the @option{-g} flag. @xref{Compilation}. 14713 14714A program may define a macro at one point, remove that definition later, 14715and then provide a different definition after that. Thus, at different 14716points in the program, a macro may have different definitions, or have 14717no definition at all. If there is a current stack frame, @value{GDBN} 14718uses the macros in scope at that frame's source code line. Otherwise, 14719@value{GDBN} uses the macros in scope at the current listing location; 14720see @ref{List}. 14721 14722Whenever @value{GDBN} evaluates an expression, it always expands any 14723macro invocations present in the expression. @value{GDBN} also provides 14724the following commands for working with macros explicitly. 14725 14726@table @code 14727 14728@kindex macro expand 14729@cindex macro expansion, showing the results of preprocessor 14730@cindex preprocessor macro expansion, showing the results of 14731@cindex expanding preprocessor macros 14732@item macro expand @var{expression} 14733@itemx macro exp @var{expression} 14734Show the results of expanding all preprocessor macro invocations in 14735@var{expression}. Since @value{GDBN} simply expands macros, but does 14736not parse the result, @var{expression} need not be a valid expression; 14737it can be any string of tokens. 14738 14739@kindex macro exp1 14740@item macro expand-once @var{expression} 14741@itemx macro exp1 @var{expression} 14742@cindex expand macro once 14743@i{(This command is not yet implemented.)} Show the results of 14744expanding those preprocessor macro invocations that appear explicitly in 14745@var{expression}. Macro invocations appearing in that expansion are 14746left unchanged. This command allows you to see the effect of a 14747particular macro more clearly, without being confused by further 14748expansions. Since @value{GDBN} simply expands macros, but does not 14749parse the result, @var{expression} need not be a valid expression; it 14750can be any string of tokens. 14751 14752@kindex info macro 14753@cindex macro definition, showing 14754@cindex definition of a macro, showing 14755@cindex macros, from debug info 14756@item info macro [-a|-all] [--] @var{macro} 14757Show the current definition or all definitions of the named @var{macro}, 14758and describe the source location or compiler command-line where that 14759definition was established. The optional double dash is to signify the end of 14760argument processing and the beginning of @var{macro} for non C-like macros where 14761the macro may begin with a hyphen. 14762 14763@kindex info macros 14764@item info macros @var{locspec} 14765Show all macro definitions that are in effect at the source line of 14766the code location that results from resolving @var{locspec}, and 14767describe the source location or compiler command-line where those 14768definitions were established. 14769 14770@kindex macro define 14771@cindex user-defined macros 14772@cindex defining macros interactively 14773@cindex macros, user-defined 14774@item macro define @var{macro} @var{replacement-list} 14775@itemx macro define @var{macro}(@var{arglist}) @var{replacement-list} 14776Introduce a definition for a preprocessor macro named @var{macro}, 14777invocations of which are replaced by the tokens given in 14778@var{replacement-list}. The first form of this command defines an 14779``object-like'' macro, which takes no arguments; the second form 14780defines a ``function-like'' macro, which takes the arguments given in 14781@var{arglist}. 14782 14783A definition introduced by this command is in scope in every 14784expression evaluated in @value{GDBN}, until it is removed with the 14785@code{macro undef} command, described below. The definition overrides 14786all definitions for @var{macro} present in the program being debugged, 14787as well as any previous user-supplied definition. 14788 14789@kindex macro undef 14790@item macro undef @var{macro} 14791Remove any user-supplied definition for the macro named @var{macro}. 14792This command only affects definitions provided with the @code{macro 14793define} command, described above; it cannot remove definitions present 14794in the program being debugged. 14795 14796@kindex macro list 14797@item macro list 14798List all the macros defined using the @code{macro define} command. 14799@end table 14800 14801@cindex macros, example of debugging with 14802Here is a transcript showing the above commands in action. First, we 14803show our source files: 14804 14805@smallexample 14806$ cat sample.c 14807#include <stdio.h> 14808#include "sample.h" 14809 14810#define M 42 14811#define ADD(x) (M + x) 14812 14813main () 14814@{ 14815#define N 28 14816 printf ("Hello, world!\n"); 14817#undef N 14818 printf ("We're so creative.\n"); 14819#define N 1729 14820 printf ("Goodbye, world!\n"); 14821@} 14822$ cat sample.h 14823#define Q < 14824$ 14825@end smallexample 14826 14827Now, we compile the program using the @sc{gnu} C compiler, 14828@value{NGCC}. We pass the @option{-gdwarf-2}@footnote{This is the 14829minimum. Recent versions of @value{NGCC} support @option{-gdwarf-3} 14830and @option{-gdwarf-4}; we recommend always choosing the most recent 14831version of DWARF.} @emph{and} @option{-g3} flags to ensure the compiler 14832includes information about preprocessor macros in the debugging 14833information. 14834 14835@smallexample 14836$ gcc -gdwarf-2 -g3 sample.c -o sample 14837$ 14838@end smallexample 14839 14840Now, we start @value{GDBN} on our sample program: 14841 14842@smallexample 14843$ gdb -nw sample 14844GNU gdb 2002-05-06-cvs 14845Copyright 2002 Free Software Foundation, Inc. 14846GDB is free software, @dots{} 14847(@value{GDBP}) 14848@end smallexample 14849 14850We can expand macros and examine their definitions, even when the 14851program is not running. @value{GDBN} uses the current listing position 14852to decide which macro definitions are in scope: 14853 14854@smallexample 14855(@value{GDBP}) list main 148563 148574 #define M 42 148585 #define ADD(x) (M + x) 148596 148607 main () 148618 @{ 148629 #define N 28 1486310 printf ("Hello, world!\n"); 1486411 #undef N 1486512 printf ("We're so creative.\n"); 14866(@value{GDBP}) info macro ADD 14867Defined at /home/jimb/gdb/macros/play/sample.c:5 14868#define ADD(x) (M + x) 14869(@value{GDBP}) info macro Q 14870Defined at /home/jimb/gdb/macros/play/sample.h:1 14871 included at /home/jimb/gdb/macros/play/sample.c:2 14872#define Q < 14873(@value{GDBP}) macro expand ADD(1) 14874expands to: (42 + 1) 14875(@value{GDBP}) macro expand-once ADD(1) 14876expands to: once (M + 1) 14877(@value{GDBP}) 14878@end smallexample 14879 14880In the example above, note that @code{macro expand-once} expands only 14881the macro invocation explicit in the original text --- the invocation of 14882@code{ADD} --- but does not expand the invocation of the macro @code{M}, 14883which was introduced by @code{ADD}. 14884 14885Once the program is running, @value{GDBN} uses the macro definitions in 14886force at the source line of the current stack frame: 14887 14888@smallexample 14889(@value{GDBP}) break main 14890Breakpoint 1 at 0x8048370: file sample.c, line 10. 14891(@value{GDBP}) run 14892Starting program: /home/jimb/gdb/macros/play/sample 14893 14894Breakpoint 1, main () at sample.c:10 1489510 printf ("Hello, world!\n"); 14896(@value{GDBP}) 14897@end smallexample 14898 14899At line 10, the definition of the macro @code{N} at line 9 is in force: 14900 14901@smallexample 14902(@value{GDBP}) info macro N 14903Defined at /home/jimb/gdb/macros/play/sample.c:9 14904#define N 28 14905(@value{GDBP}) macro expand N Q M 14906expands to: 28 < 42 14907(@value{GDBP}) print N Q M 14908$1 = 1 14909(@value{GDBP}) 14910@end smallexample 14911 14912As we step over directives that remove @code{N}'s definition, and then 14913give it a new definition, @value{GDBN} finds the definition (or lack 14914thereof) in force at each point: 14915 14916@smallexample 14917(@value{GDBP}) next 14918Hello, world! 1491912 printf ("We're so creative.\n"); 14920(@value{GDBP}) info macro N 14921The symbol `N' has no definition as a C/C++ preprocessor macro 14922at /home/jimb/gdb/macros/play/sample.c:12 14923(@value{GDBP}) next 14924We're so creative. 1492514 printf ("Goodbye, world!\n"); 14926(@value{GDBP}) info macro N 14927Defined at /home/jimb/gdb/macros/play/sample.c:13 14928#define N 1729 14929(@value{GDBP}) macro expand N Q M 14930expands to: 1729 < 42 14931(@value{GDBP}) print N Q M 14932$2 = 0 14933(@value{GDBP}) 14934@end smallexample 14935 14936In addition to source files, macros can be defined on the compilation command 14937line using the @option{-D@var{name}=@var{value}} syntax. For macros defined in 14938such a way, @value{GDBN} displays the location of their definition as line zero 14939of the source file submitted to the compiler. 14940 14941@smallexample 14942(@value{GDBP}) info macro __STDC__ 14943Defined at /home/jimb/gdb/macros/play/sample.c:0 14944-D__STDC__=1 14945(@value{GDBP}) 14946@end smallexample 14947 14948 14949@node Tracepoints 14950@chapter Tracepoints 14951@c This chapter is based on the documentation written by Michael 14952@c Snyder, David Taylor, Jim Blandy, and Elena Zannoni. 14953 14954@cindex tracepoints 14955In some applications, it is not feasible for the debugger to interrupt 14956the program's execution long enough for the developer to learn 14957anything helpful about its behavior. If the program's correctness 14958depends on its real-time behavior, delays introduced by a debugger 14959might cause the program to change its behavior drastically, or perhaps 14960fail, even when the code itself is correct. It is useful to be able 14961to observe the program's behavior without interrupting it. 14962 14963Using @value{GDBN}'s @code{trace} and @code{collect} commands, you can 14964specify locations in the program, called @dfn{tracepoints}, and 14965arbitrary expressions to evaluate when those tracepoints are reached. 14966Later, using the @code{tfind} command, you can examine the values 14967those expressions had when the program hit the tracepoints. The 14968expressions may also denote objects in memory---structures or arrays, 14969for example---whose values @value{GDBN} should record; while visiting 14970a particular tracepoint, you may inspect those objects as if they were 14971in memory at that moment. However, because @value{GDBN} records these 14972values without interacting with you, it can do so quickly and 14973unobtrusively, hopefully not disturbing the program's behavior. 14974 14975The tracepoint facility is currently available only for remote 14976targets. @xref{Targets}. In addition, your remote target must know 14977how to collect trace data. This functionality is implemented in the 14978remote stub; however, none of the stubs distributed with @value{GDBN} 14979support tracepoints as of this writing. The format of the remote 14980packets used to implement tracepoints are described in @ref{Tracepoint 14981Packets}. 14982 14983It is also possible to get trace data from a file, in a manner reminiscent 14984of corefiles; you specify the filename, and use @code{tfind} to search 14985through the file. @xref{Trace Files}, for more details. 14986 14987This chapter describes the tracepoint commands and features. 14988 14989@menu 14990* Set Tracepoints:: 14991* Analyze Collected Data:: 14992* Tracepoint Variables:: 14993* Trace Files:: 14994@end menu 14995 14996@node Set Tracepoints 14997@section Commands to Set Tracepoints 14998 14999Before running such a @dfn{trace experiment}, an arbitrary number of 15000tracepoints can be set. A tracepoint is actually a special type of 15001breakpoint (@pxref{Set Breaks}), so you can manipulate it using 15002standard breakpoint commands. For instance, as with breakpoints, 15003tracepoint numbers are successive integers starting from one, and many 15004of the commands associated with tracepoints take the tracepoint number 15005as their argument, to identify which tracepoint to work on. 15006 15007For each tracepoint, you can specify, in advance, some arbitrary set 15008of data that you want the target to collect in the trace buffer when 15009it hits that tracepoint. The collected data can include registers, 15010local variables, or global data. Later, you can use @value{GDBN} 15011commands to examine the values these data had at the time the 15012tracepoint was hit. 15013 15014Tracepoints do not support every breakpoint feature. Ignore counts on 15015tracepoints have no effect, and tracepoints cannot run @value{GDBN} 15016commands when they are hit. Tracepoints may not be thread-specific 15017either. 15018 15019@cindex fast tracepoints 15020Some targets may support @dfn{fast tracepoints}, which are inserted in 15021a different way (such as with a jump instead of a trap), that is 15022faster but possibly restricted in where they may be installed. 15023 15024@cindex static tracepoints 15025@cindex markers, static tracepoints 15026@cindex probing markers, static tracepoints 15027Regular and fast tracepoints are dynamic tracing facilities, meaning 15028that they can be used to insert tracepoints at (almost) any location 15029in the target. Some targets may also support controlling @dfn{static 15030tracepoints} from @value{GDBN}. With static tracing, a set of 15031instrumentation points, also known as @dfn{markers}, are embedded in 15032the target program, and can be activated or deactivated by name or 15033address. These are usually placed at locations which facilitate 15034investigating what the target is actually doing. @value{GDBN}'s 15035support for static tracing includes being able to list instrumentation 15036points, and attach them with @value{GDBN} defined high level 15037tracepoints that expose the whole range of convenience of 15038@value{GDBN}'s tracepoints support. Namely, support for collecting 15039registers values and values of global or local (to the instrumentation 15040point) variables; tracepoint conditions and trace state variables. 15041The act of installing a @value{GDBN} static tracepoint on an 15042instrumentation point, or marker, is referred to as @dfn{probing} a 15043static tracepoint marker. 15044 15045@code{gdbserver} supports tracepoints on some target systems. 15046@xref{Server,,Tracepoints support in @code{gdbserver}}. 15047 15048This section describes commands to set tracepoints and associated 15049conditions and actions. 15050 15051@menu 15052* Create and Delete Tracepoints:: 15053* Enable and Disable Tracepoints:: 15054* Tracepoint Passcounts:: 15055* Tracepoint Conditions:: 15056* Trace State Variables:: 15057* Tracepoint Actions:: 15058* Listing Tracepoints:: 15059* Listing Static Tracepoint Markers:: 15060* Starting and Stopping Trace Experiments:: 15061* Tracepoint Restrictions:: 15062@end menu 15063 15064@node Create and Delete Tracepoints 15065@subsection Create and Delete Tracepoints 15066 15067@table @code 15068@cindex set tracepoint 15069@kindex trace 15070@item trace @var{locspec} 15071The @code{trace} command is very similar to the @code{break} command. 15072Its argument @var{locspec} can be any valid location specification. 15073@xref{Location Specifications}. The @code{trace} command defines a tracepoint, 15074which is a point in the target program where the debugger will briefly stop, 15075collect some data, and then allow the program to continue. Setting a tracepoint 15076or changing its actions takes effect immediately if the remote stub 15077supports the @samp{InstallInTrace} feature (@pxref{install tracepoint 15078in tracing}). 15079If remote stub doesn't support the @samp{InstallInTrace} feature, all 15080these changes don't take effect until the next @code{tstart} 15081command, and once a trace experiment is running, further changes will 15082not have any effect until the next trace experiment starts. In addition, 15083@value{GDBN} supports @dfn{pending tracepoints}---tracepoints whose 15084address is not yet resolved. (This is similar to pending breakpoints.) 15085Pending tracepoints are not downloaded to the target and not installed 15086until they are resolved. The resolution of pending tracepoints requires 15087@value{GDBN} support---when debugging with the remote target, and 15088@value{GDBN} disconnects from the remote stub (@pxref{disconnected 15089tracing}), pending tracepoints can not be resolved (and downloaded to 15090the remote stub) while @value{GDBN} is disconnected. 15091 15092Here are some examples of using the @code{trace} command: 15093 15094@smallexample 15095(@value{GDBP}) @b{trace foo.c:121} // a source file and line number 15096 15097(@value{GDBP}) @b{trace +2} // 2 lines forward 15098 15099(@value{GDBP}) @b{trace my_function} // first source line of function 15100 15101(@value{GDBP}) @b{trace *my_function} // EXACT start address of function 15102 15103(@value{GDBP}) @b{trace *0x2117c4} // an address 15104@end smallexample 15105 15106@noindent 15107You can abbreviate @code{trace} as @code{tr}. 15108 15109@item trace @var{locspec} if @var{cond} 15110Set a tracepoint with condition @var{cond}; evaluate the expression 15111@var{cond} each time the tracepoint is reached, and collect data only 15112if the value is nonzero---that is, if @var{cond} evaluates as true. 15113@xref{Tracepoint Conditions, ,Tracepoint Conditions}, for more 15114information on tracepoint conditions. 15115 15116@item ftrace @var{locspec} [ if @var{cond} ] 15117@cindex set fast tracepoint 15118@cindex fast tracepoints, setting 15119@kindex ftrace 15120The @code{ftrace} command sets a fast tracepoint. For targets that 15121support them, fast tracepoints will use a more efficient but possibly 15122less general technique to trigger data collection, such as a jump 15123instruction instead of a trap, or some sort of hardware support. It 15124may not be possible to create a fast tracepoint at the desired 15125location, in which case the command will exit with an explanatory 15126message. 15127 15128@value{GDBN} handles arguments to @code{ftrace} exactly as for 15129@code{trace}. 15130 15131On 32-bit x86-architecture systems, fast tracepoints normally need to 15132be placed at an instruction that is 5 bytes or longer, but can be 15133placed at 4-byte instructions if the low 64K of memory of the target 15134program is available to install trampolines. Some Unix-type systems, 15135such as @sc{gnu}/Linux, exclude low addresses from the program's 15136address space; but for instance with the Linux kernel it is possible 15137to let @value{GDBN} use this area by doing a @command{sysctl} command 15138to set the @code{mmap_min_addr} kernel parameter, as in 15139 15140@example 15141sudo sysctl -w vm.mmap_min_addr=32768 15142@end example 15143 15144@noindent 15145which sets the low address to 32K, which leaves plenty of room for 15146trampolines. The minimum address should be set to a page boundary. 15147 15148@item strace [@var{locspec} | -m @var{marker}] [ if @var{cond} ] 15149@cindex set static tracepoint 15150@cindex static tracepoints, setting 15151@cindex probe static tracepoint marker 15152@kindex strace 15153The @code{strace} command sets a static tracepoint. For targets that 15154support it, setting a static tracepoint probes a static 15155instrumentation point, or marker, found at the code locations that 15156result from resolving @var{locspec}. It may not be possible to set a 15157static tracepoint at the desired code location, in which case the 15158command will exit with an explanatory message. 15159 15160@value{GDBN} handles arguments to @code{strace} exactly as for 15161@code{trace}, with the addition that the user can also specify 15162@code{-m @var{marker}} instead of a location spec. This probes the marker 15163identified by the @var{marker} string identifier. This identifier 15164depends on the static tracepoint backend library your program is 15165using. You can find all the marker identifiers in the @samp{ID} field 15166of the @code{info static-tracepoint-markers} command output. 15167@xref{Listing Static Tracepoint Markers,,Listing Static Tracepoint 15168Markers}. For example, in the following small program using the UST 15169tracing engine: 15170 15171@smallexample 15172main () 15173@{ 15174 trace_mark(ust, bar33, "str %s", "FOOBAZ"); 15175@} 15176@end smallexample 15177 15178@noindent 15179the marker id is composed of joining the first two arguments to the 15180@code{trace_mark} call with a slash, which translates to: 15181 15182@smallexample 15183(@value{GDBP}) info static-tracepoint-markers 15184Cnt Enb ID Address What 151851 n ust/bar33 0x0000000000400ddc in main at stexample.c:22 15186 Data: "str %s" 15187[etc...] 15188@end smallexample 15189 15190@noindent 15191so you may probe the marker above with: 15192 15193@smallexample 15194(@value{GDBP}) strace -m ust/bar33 15195@end smallexample 15196 15197Static tracepoints accept an extra collect action --- @code{collect 15198$_sdata}. This collects arbitrary user data passed in the probe point 15199call to the tracing library. In the UST example above, you'll see 15200that the third argument to @code{trace_mark} is a printf-like format 15201string. The user data is then the result of running that formatting 15202string against the following arguments. Note that @code{info 15203static-tracepoint-markers} command output lists that format string in 15204the @samp{Data:} field. 15205 15206You can inspect this data when analyzing the trace buffer, by printing 15207the $_sdata variable like any other variable available to 15208@value{GDBN}. @xref{Tracepoint Actions,,Tracepoint Action Lists}. 15209 15210@vindex $tpnum 15211@cindex last tracepoint number 15212@cindex recent tracepoint number 15213@cindex tracepoint number 15214The convenience variable @code{$tpnum} records the tracepoint number 15215of the most recently set tracepoint. 15216 15217@kindex delete tracepoint 15218@cindex tracepoint deletion 15219@item delete tracepoint @r{[}@var{num}@r{]} 15220Permanently delete one or more tracepoints. With no argument, the 15221default is to delete all tracepoints. Note that the regular 15222@code{delete} command can remove tracepoints also. 15223 15224Examples: 15225 15226@smallexample 15227(@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints 15228 15229(@value{GDBP}) @b{delete trace} // remove all tracepoints 15230@end smallexample 15231 15232@noindent 15233You can abbreviate this command as @code{del tr}. 15234@end table 15235 15236@node Enable and Disable Tracepoints 15237@subsection Enable and Disable Tracepoints 15238 15239These commands are deprecated; they are equivalent to plain @code{disable} and @code{enable}. 15240 15241@table @code 15242@kindex disable tracepoint 15243@item disable tracepoint @r{[}@var{num}@r{]} 15244Disable tracepoint @var{num}, or all tracepoints if no argument 15245@var{num} is given. A disabled tracepoint will have no effect during 15246a trace experiment, but it is not forgotten. You can re-enable 15247a disabled tracepoint using the @code{enable tracepoint} command. 15248If the command is issued during a trace experiment and the debug target 15249has support for disabling tracepoints during a trace experiment, then the 15250change will be effective immediately. Otherwise, it will be applied to the 15251next trace experiment. 15252 15253@kindex enable tracepoint 15254@item enable tracepoint @r{[}@var{num}@r{]} 15255Enable tracepoint @var{num}, or all tracepoints. If this command is 15256issued during a trace experiment and the debug target supports enabling 15257tracepoints during a trace experiment, then the enabled tracepoints will 15258become effective immediately. Otherwise, they will become effective the 15259next time a trace experiment is run. 15260@end table 15261 15262@node Tracepoint Passcounts 15263@subsection Tracepoint Passcounts 15264 15265@table @code 15266@kindex passcount 15267@cindex tracepoint pass count 15268@item passcount @r{[}@var{n} @r{[}@var{num}@r{]]} 15269Set the @dfn{passcount} of a tracepoint. The passcount is a way to 15270automatically stop a trace experiment. If a tracepoint's passcount is 15271@var{n}, then the trace experiment will be automatically stopped on 15272the @var{n}'th time that tracepoint is hit. If the tracepoint number 15273@var{num} is not specified, the @code{passcount} command sets the 15274passcount of the most recently defined tracepoint. If no passcount is 15275given, the trace experiment will run until stopped explicitly by the 15276user. 15277 15278Examples: 15279 15280@smallexample 15281(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of 15282@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2} 15283 15284(@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the 15285@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// most recently defined tracepoint.} 15286(@value{GDBP}) @b{trace foo} 15287(@value{GDBP}) @b{pass 3} 15288(@value{GDBP}) @b{trace bar} 15289(@value{GDBP}) @b{pass 2} 15290(@value{GDBP}) @b{trace baz} 15291(@value{GDBP}) @b{pass 1} // Stop tracing when foo has been 15292@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// executed 3 times OR when bar has} 15293@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// been executed 2 times} 15294@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// OR when baz has been executed 1 time.} 15295@end smallexample 15296@end table 15297 15298@node Tracepoint Conditions 15299@subsection Tracepoint Conditions 15300@cindex conditional tracepoints 15301@cindex tracepoint conditions 15302 15303The simplest sort of tracepoint collects data every time your program 15304reaches a specified place. You can also specify a @dfn{condition} for 15305a tracepoint. A condition is just a Boolean expression in your 15306programming language (@pxref{Expressions, ,Expressions}). A 15307tracepoint with a condition evaluates the expression each time your 15308program reaches it, and data collection happens only if the condition 15309is true. 15310 15311Tracepoint conditions can be specified when a tracepoint is set, by 15312using @samp{if} in the arguments to the @code{trace} command. 15313@xref{Create and Delete Tracepoints, ,Setting Tracepoints}. They can 15314also be set or changed at any time with the @code{condition} command, 15315just as with breakpoints. 15316 15317Unlike breakpoint conditions, @value{GDBN} does not actually evaluate 15318the conditional expression itself. Instead, @value{GDBN} encodes the 15319expression into an agent expression (@pxref{Agent Expressions}) 15320suitable for execution on the target, independently of @value{GDBN}. 15321Global variables become raw memory locations, locals become stack 15322accesses, and so forth. 15323 15324For instance, suppose you have a function that is usually called 15325frequently, but should not be called after an error has occurred. You 15326could use the following tracepoint command to collect data about calls 15327of that function that happen while the error code is propagating 15328through the program; an unconditional tracepoint could end up 15329collecting thousands of useless trace frames that you would have to 15330search through. 15331 15332@smallexample 15333(@value{GDBP}) @kbd{trace normal_operation if errcode > 0} 15334@end smallexample 15335 15336@node Trace State Variables 15337@subsection Trace State Variables 15338@cindex trace state variables 15339 15340A @dfn{trace state variable} is a special type of variable that is 15341created and managed by target-side code. The syntax is the same as 15342that for GDB's convenience variables (a string prefixed with ``$''), 15343but they are stored on the target. They must be created explicitly, 15344using a @code{tvariable} command. They are always 64-bit signed 15345integers. 15346 15347Trace state variables are remembered by @value{GDBN}, and downloaded 15348to the target along with tracepoint information when the trace 15349experiment starts. There are no intrinsic limits on the number of 15350trace state variables, beyond memory limitations of the target. 15351 15352@cindex convenience variables, and trace state variables 15353Although trace state variables are managed by the target, you can use 15354them in print commands and expressions as if they were convenience 15355variables; @value{GDBN} will get the current value from the target 15356while the trace experiment is running. Trace state variables share 15357the same namespace as other ``$'' variables, which means that you 15358cannot have trace state variables with names like @code{$23} or 15359@code{$pc}, nor can you have a trace state variable and a convenience 15360variable with the same name. 15361 15362@table @code 15363 15364@item tvariable $@var{name} [ = @var{expression} ] 15365@kindex tvariable 15366The @code{tvariable} command creates a new trace state variable named 15367@code{$@var{name}}, and optionally gives it an initial value of 15368@var{expression}. The @var{expression} is evaluated when this command is 15369entered; the result will be converted to an integer if possible, 15370otherwise @value{GDBN} will report an error. A subsequent 15371@code{tvariable} command specifying the same name does not create a 15372variable, but instead assigns the supplied initial value to the 15373existing variable of that name, overwriting any previous initial 15374value. The default initial value is 0. 15375 15376@item info tvariables 15377@kindex info tvariables 15378List all the trace state variables along with their initial values. 15379Their current values may also be displayed, if the trace experiment is 15380currently running. 15381 15382@item delete tvariable @r{[} $@var{name} @dots{} @r{]} 15383@kindex delete tvariable 15384Delete the given trace state variables, or all of them if no arguments 15385are specified. 15386 15387@end table 15388 15389@node Tracepoint Actions 15390@subsection Tracepoint Action Lists 15391 15392@table @code 15393@kindex actions 15394@cindex tracepoint actions 15395@item actions @r{[}@var{num}@r{]} 15396This command will prompt for a list of actions to be taken when the 15397tracepoint is hit. If the tracepoint number @var{num} is not 15398specified, this command sets the actions for the one that was most 15399recently defined (so that you can define a tracepoint and then say 15400@code{actions} without bothering about its number). You specify the 15401actions themselves on the following lines, one action at a time, and 15402terminate the actions list with a line containing just @code{end}. So 15403far, the only defined actions are @code{collect}, @code{teval}, and 15404@code{while-stepping}. 15405 15406@code{actions} is actually equivalent to @code{commands} (@pxref{Break 15407Commands, ,Breakpoint Command Lists}), except that only the defined 15408actions are allowed; any other @value{GDBN} command is rejected. 15409 15410@cindex remove actions from a tracepoint 15411To remove all actions from a tracepoint, type @samp{actions @var{num}} 15412and follow it immediately with @samp{end}. 15413 15414@smallexample 15415(@value{GDBP}) @b{collect @var{data}} // collect some data 15416 15417(@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data 15418 15419(@value{GDBP}) @b{end} // signals the end of actions. 15420@end smallexample 15421 15422In the following example, the action list begins with @code{collect} 15423commands indicating the things to be collected when the tracepoint is 15424hit. Then, in order to single-step and collect additional data 15425following the tracepoint, a @code{while-stepping} command is used, 15426followed by the list of things to be collected after each step in a 15427sequence of single steps. The @code{while-stepping} command is 15428terminated by its own separate @code{end} command. Lastly, the action 15429list is terminated by an @code{end} command. 15430 15431@smallexample 15432(@value{GDBP}) @b{trace foo} 15433(@value{GDBP}) @b{actions} 15434Enter actions for tracepoint 1, one per line: 15435> collect bar,baz 15436> collect $regs 15437> while-stepping 12 15438 > collect $pc, arr[i] 15439 > end 15440end 15441@end smallexample 15442 15443@kindex collect @r{(tracepoints)} 15444@item collect@r{[}/@var{mods}@r{]} @var{expr1}, @var{expr2}, @dots{} 15445Collect values of the given expressions when the tracepoint is hit. 15446This command accepts a comma-separated list of any valid expressions. 15447In addition to global, static, or local variables, the following 15448special arguments are supported: 15449 15450@table @code 15451@item $regs 15452Collect all registers. 15453 15454@item $args 15455Collect all function arguments. 15456 15457@item $locals 15458Collect all local variables. 15459 15460@item $_ret 15461Collect the return address. This is helpful if you want to see more 15462of a backtrace. 15463 15464@emph{Note:} The return address location can not always be reliably 15465determined up front, and the wrong address / registers may end up 15466collected instead. On some architectures the reliability is higher 15467for tracepoints at function entry, while on others it's the opposite. 15468When this happens, backtracing will stop because the return address is 15469found unavailable (unless another collect rule happened to match it). 15470 15471@item $_probe_argc 15472Collects the number of arguments from the static probe at which the 15473tracepoint is located. 15474@xref{Static Probe Points}. 15475 15476@item $_probe_arg@var{n} 15477@var{n} is an integer between 0 and 11. Collects the @var{n}th argument 15478from the static probe at which the tracepoint is located. 15479@xref{Static Probe Points}. 15480 15481@item $_sdata 15482@vindex $_sdata@r{, collect} 15483Collect static tracepoint marker specific data. Only available for 15484static tracepoints. @xref{Tracepoint Actions,,Tracepoint Action 15485Lists}. On the UST static tracepoints library backend, an 15486instrumentation point resembles a @code{printf} function call. The 15487tracing library is able to collect user specified data formatted to a 15488character string using the format provided by the programmer that 15489instrumented the program. Other backends have similar mechanisms. 15490Here's an example of a UST marker call: 15491 15492@smallexample 15493 const char master_name[] = "$your_name"; 15494 trace_mark(channel1, marker1, "hello %s", master_name) 15495@end smallexample 15496 15497In this case, collecting @code{$_sdata} collects the string 15498@samp{hello $yourname}. When analyzing the trace buffer, you can 15499inspect @samp{$_sdata} like any other variable available to 15500@value{GDBN}. 15501@end table 15502 15503You can give several consecutive @code{collect} commands, each one 15504with a single argument, or one @code{collect} command with several 15505arguments separated by commas; the effect is the same. 15506 15507The optional @var{mods} changes the usual handling of the arguments. 15508@code{s} requests that pointers to chars be handled as strings, in 15509particular collecting the contents of the memory being pointed at, up 15510to the first zero. The upper bound is by default the value of the 15511@code{print characters} variable; if @code{s} is followed by a decimal 15512number, that is the upper bound instead. So for instance 15513@samp{collect/s25 mystr} collects as many as 25 characters at 15514@samp{mystr}. 15515 15516The command @code{info scope} (@pxref{Symbols, info scope}) is 15517particularly useful for figuring out what data to collect. 15518 15519@kindex teval @r{(tracepoints)} 15520@item teval @var{expr1}, @var{expr2}, @dots{} 15521Evaluate the given expressions when the tracepoint is hit. This 15522command accepts a comma-separated list of expressions. The results 15523are discarded, so this is mainly useful for assigning values to trace 15524state variables (@pxref{Trace State Variables}) without adding those 15525values to the trace buffer, as would be the case if the @code{collect} 15526action were used. 15527 15528@kindex while-stepping @r{(tracepoints)} 15529@item while-stepping @var{n} 15530Perform @var{n} single-step instruction traces after the tracepoint, 15531collecting new data after each step. The @code{while-stepping} 15532command is followed by the list of what to collect while stepping 15533(followed by its own @code{end} command): 15534 15535@smallexample 15536> while-stepping 12 15537 > collect $regs, myglobal 15538 > end 15539> 15540@end smallexample 15541 15542@noindent 15543Note that @code{$pc} is not automatically collected by 15544@code{while-stepping}; you need to explicitly collect that register if 15545you need it. You may abbreviate @code{while-stepping} as @code{ws} or 15546@code{stepping}. 15547 15548@item set default-collect @var{expr1}, @var{expr2}, @dots{} 15549@kindex set default-collect 15550@cindex default collection action 15551This variable is a list of expressions to collect at each tracepoint 15552hit. It is effectively an additional @code{collect} action prepended 15553to every tracepoint action list. The expressions are parsed 15554individually for each tracepoint, so for instance a variable named 15555@code{xyz} may be interpreted as a global for one tracepoint, and a 15556local for another, as appropriate to the tracepoint's location. 15557 15558@item show default-collect 15559@kindex show default-collect 15560Show the list of expressions that are collected by default at each 15561tracepoint hit. 15562 15563@end table 15564 15565@node Listing Tracepoints 15566@subsection Listing Tracepoints 15567 15568@table @code 15569@kindex info tracepoints @r{[}@var{n}@dots{}@r{]} 15570@kindex info tp @r{[}@var{n}@dots{}@r{]} 15571@cindex information about tracepoints 15572@item info tracepoints @r{[}@var{num}@dots{}@r{]} 15573Display information about the tracepoint @var{num}. If you don't 15574specify a tracepoint number, displays information about all the 15575tracepoints defined so far. The format is similar to that used for 15576@code{info breakpoints}; in fact, @code{info tracepoints} is the same 15577command, simply restricting itself to tracepoints. 15578 15579A tracepoint's listing may include additional information specific to 15580tracing: 15581 15582@itemize @bullet 15583@item 15584its passcount as given by the @code{passcount @var{n}} command 15585 15586@item 15587the state about installed on target of each location 15588@end itemize 15589 15590@smallexample 15591(@value{GDBP}) @b{info trace} 15592Num Type Disp Enb Address What 155931 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7 15594 while-stepping 20 15595 collect globfoo, $regs 15596 end 15597 collect globfoo2 15598 end 15599 pass count 1200 156002 tracepoint keep y <MULTIPLE> 15601 collect $eip 156022.1 y 0x0804859c in func4 at change-loc.h:35 15603 installed on target 156042.2 y 0xb7ffc480 in func4 at change-loc.h:35 15605 installed on target 156062.3 y <PENDING> set_tracepoint 156073 tracepoint keep y 0x080485b1 in foo at change-loc.c:29 15608 not installed on target 15609(@value{GDBP}) 15610@end smallexample 15611 15612@noindent 15613This command can be abbreviated @code{info tp}. 15614@end table 15615 15616@node Listing Static Tracepoint Markers 15617@subsection Listing Static Tracepoint Markers 15618 15619@table @code 15620@kindex info static-tracepoint-markers 15621@cindex information about static tracepoint markers 15622@item info static-tracepoint-markers 15623Display information about all static tracepoint markers defined in the 15624program. 15625 15626For each marker, the following columns are printed: 15627 15628@table @emph 15629@item Count 15630An incrementing counter, output to help readability. This is not a 15631stable identifier. 15632@item ID 15633The marker ID, as reported by the target. 15634@item Enabled or Disabled 15635Probed markers are tagged with @samp{y}. @samp{n} identifies marks 15636that are not enabled. 15637@item Address 15638Where the marker is in your program, as a memory address. 15639@item What 15640Where the marker is in the source for your program, as a file and line 15641number. If the debug information included in the program does not 15642allow @value{GDBN} to locate the source of the marker, this column 15643will be left blank. 15644@end table 15645 15646@noindent 15647In addition, the following information may be printed for each marker: 15648 15649@table @emph 15650@item Data 15651User data passed to the tracing library by the marker call. In the 15652UST backend, this is the format string passed as argument to the 15653marker call. 15654@item Static tracepoints probing the marker 15655The list of static tracepoints attached to the marker. 15656@end table 15657 15658@smallexample 15659(@value{GDBP}) info static-tracepoint-markers 15660Cnt ID Enb Address What 156611 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25 15662 Data: number1 %d number2 %d 15663 Probed by static tracepoints: #2 156642 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24 15665 Data: str %s 15666(@value{GDBP}) 15667@end smallexample 15668@end table 15669 15670@node Starting and Stopping Trace Experiments 15671@subsection Starting and Stopping Trace Experiments 15672 15673@table @code 15674@kindex tstart [ @var{notes} ] 15675@cindex start a new trace experiment 15676@cindex collected data discarded 15677@item tstart 15678This command starts the trace experiment, and begins collecting data. 15679It has the side effect of discarding all the data collected in the 15680trace buffer during the previous trace experiment. If any arguments 15681are supplied, they are taken as a note and stored with the trace 15682experiment's state. The notes may be arbitrary text, and are 15683especially useful with disconnected tracing in a multi-user context; 15684the notes can explain what the trace is doing, supply user contact 15685information, and so forth. 15686 15687@kindex tstop [ @var{notes} ] 15688@cindex stop a running trace experiment 15689@item tstop 15690This command stops the trace experiment. If any arguments are 15691supplied, they are recorded with the experiment as a note. This is 15692useful if you are stopping a trace started by someone else, for 15693instance if the trace is interfering with the system's behavior and 15694needs to be stopped quickly. 15695 15696@strong{Note}: a trace experiment and data collection may stop 15697automatically if any tracepoint's passcount is reached 15698(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full. 15699 15700@kindex tstatus 15701@cindex status of trace data collection 15702@cindex trace experiment, status of 15703@item tstatus 15704This command displays the status of the current trace data 15705collection. 15706@end table 15707 15708Here is an example of the commands we described so far: 15709 15710@smallexample 15711(@value{GDBP}) @b{trace gdb_c_test} 15712(@value{GDBP}) @b{actions} 15713Enter actions for tracepoint #1, one per line. 15714> collect $regs,$locals,$args 15715> while-stepping 11 15716 > collect $regs 15717 > end 15718> end 15719(@value{GDBP}) @b{tstart} 15720 [time passes @dots{}] 15721(@value{GDBP}) @b{tstop} 15722@end smallexample 15723 15724@anchor{disconnected tracing} 15725@cindex disconnected tracing 15726You can choose to continue running the trace experiment even if 15727@value{GDBN} disconnects from the target, voluntarily or 15728involuntarily. For commands such as @code{detach}, the debugger will 15729ask what you want to do with the trace. But for unexpected 15730terminations (@value{GDBN} crash, network outage), it would be 15731unfortunate to lose hard-won trace data, so the variable 15732@code{disconnected-tracing} lets you decide whether the trace should 15733continue running without @value{GDBN}. 15734 15735@table @code 15736@item set disconnected-tracing on 15737@itemx set disconnected-tracing off 15738@kindex set disconnected-tracing 15739Choose whether a tracing run should continue to run if @value{GDBN} 15740has disconnected from the target. Note that @code{detach} or 15741@code{quit} will ask you directly what to do about a running trace no 15742matter what this variable's setting, so the variable is mainly useful 15743for handling unexpected situations, such as loss of the network. 15744 15745@item show disconnected-tracing 15746@kindex show disconnected-tracing 15747Show the current choice for disconnected tracing. 15748 15749@end table 15750 15751When you reconnect to the target, the trace experiment may or may not 15752still be running; it might have filled the trace buffer in the 15753meantime, or stopped for one of the other reasons. If it is running, 15754it will continue after reconnection. 15755 15756Upon reconnection, the target will upload information about the 15757tracepoints in effect. @value{GDBN} will then compare that 15758information to the set of tracepoints currently defined, and attempt 15759to match them up, allowing for the possibility that the numbers may 15760have changed due to creation and deletion in the meantime. If one of 15761the target's tracepoints does not match any in @value{GDBN}, the 15762debugger will create a new tracepoint, so that you have a number with 15763which to specify that tracepoint. This matching-up process is 15764necessarily heuristic, and it may result in useless tracepoints being 15765created; you may simply delete them if they are of no use. 15766 15767@cindex circular trace buffer 15768If your target agent supports a @dfn{circular trace buffer}, then you 15769can run a trace experiment indefinitely without filling the trace 15770buffer; when space runs out, the agent deletes already-collected trace 15771frames, oldest first, until there is enough room to continue 15772collecting. This is especially useful if your tracepoints are being 15773hit too often, and your trace gets terminated prematurely because the 15774buffer is full. To ask for a circular trace buffer, simply set 15775@samp{circular-trace-buffer} to on. You can set this at any time, 15776including during tracing; if the agent can do it, it will change 15777buffer handling on the fly, otherwise it will not take effect until 15778the next run. 15779 15780@table @code 15781@item set circular-trace-buffer on 15782@itemx set circular-trace-buffer off 15783@kindex set circular-trace-buffer 15784Choose whether a tracing run should use a linear or circular buffer 15785for trace data. A linear buffer will not lose any trace data, but may 15786fill up prematurely, while a circular buffer will discard old trace 15787data, but it will have always room for the latest tracepoint hits. 15788 15789@item show circular-trace-buffer 15790@kindex show circular-trace-buffer 15791Show the current choice for the trace buffer. Note that this may not 15792match the agent's current buffer handling, nor is it guaranteed to 15793match the setting that might have been in effect during a past run, 15794for instance if you are looking at frames from a trace file. 15795 15796@end table 15797 15798@table @code 15799@item set trace-buffer-size @var{n} 15800@itemx set trace-buffer-size unlimited 15801@kindex set trace-buffer-size 15802Request that the target use a trace buffer of @var{n} bytes. Not all 15803targets will honor the request; they may have a compiled-in size for 15804the trace buffer, or some other limitation. Set to a value of 15805@code{unlimited} or @code{-1} to let the target use whatever size it 15806likes. This is also the default. 15807 15808@item show trace-buffer-size 15809@kindex show trace-buffer-size 15810Show the current requested size for the trace buffer. Note that this 15811will only match the actual size if the target supports size-setting, 15812and was able to handle the requested size. For instance, if the 15813target can only change buffer size between runs, this variable will 15814not reflect the change until the next run starts. Use @code{tstatus} 15815to get a report of the actual buffer size. 15816@end table 15817 15818@table @code 15819@item set trace-user @var{text} 15820@kindex set trace-user 15821 15822@item show trace-user 15823@kindex show trace-user 15824 15825@item set trace-notes @var{text} 15826@kindex set trace-notes 15827Set the trace run's notes. 15828 15829@item show trace-notes 15830@kindex show trace-notes 15831Show the trace run's notes. 15832 15833@item set trace-stop-notes @var{text} 15834@kindex set trace-stop-notes 15835Set the trace run's stop notes. The handling of the note is as for 15836@code{tstop} arguments; the set command is convenient way to fix a 15837stop note that is mistaken or incomplete. 15838 15839@item show trace-stop-notes 15840@kindex show trace-stop-notes 15841Show the trace run's stop notes. 15842 15843@end table 15844 15845@node Tracepoint Restrictions 15846@subsection Tracepoint Restrictions 15847 15848@cindex tracepoint restrictions 15849There are a number of restrictions on the use of tracepoints. As 15850described above, tracepoint data gathering occurs on the target 15851without interaction from @value{GDBN}. Thus the full capabilities of 15852the debugger are not available during data gathering, and then at data 15853examination time, you will be limited by only having what was 15854collected. The following items describe some common problems, but it 15855is not exhaustive, and you may run into additional difficulties not 15856mentioned here. 15857 15858@itemize @bullet 15859 15860@item 15861Tracepoint expressions are intended to gather objects (lvalues). Thus 15862the full flexibility of GDB's expression evaluator is not available. 15863You cannot call functions, cast objects to aggregate types, access 15864convenience variables or modify values (except by assignment to trace 15865state variables). Some language features may implicitly call 15866functions (for instance Objective-C fields with accessors), and therefore 15867cannot be collected either. 15868 15869@item 15870Collection of local variables, either individually or in bulk with 15871@code{$locals} or @code{$args}, during @code{while-stepping} may 15872behave erratically. The stepping action may enter a new scope (for 15873instance by stepping into a function), or the location of the variable 15874may change (for instance it is loaded into a register). The 15875tracepoint data recorded uses the location information for the 15876variables that is correct for the tracepoint location. When the 15877tracepoint is created, it is not possible, in general, to determine 15878where the steps of a @code{while-stepping} sequence will advance the 15879program---particularly if a conditional branch is stepped. 15880 15881@item 15882Collection of an incompletely-initialized or partially-destroyed object 15883may result in something that @value{GDBN} cannot display, or displays 15884in a misleading way. 15885 15886@item 15887When @value{GDBN} displays a pointer to character it automatically 15888dereferences the pointer to also display characters of the string 15889being pointed to. However, collecting the pointer during tracing does 15890not automatically collect the string. You need to explicitly 15891dereference the pointer and provide size information if you want to 15892collect not only the pointer, but the memory pointed to. For example, 15893@code{*ptr@@50} can be used to collect the 50 element array pointed to 15894by @code{ptr}. 15895 15896@item 15897It is not possible to collect a complete stack backtrace at a 15898tracepoint. Instead, you may collect the registers and a few hundred 15899bytes from the stack pointer with something like @code{*(unsigned char *)$esp@@300} 15900(adjust to use the name of the actual stack pointer register on your 15901target architecture, and the amount of stack you wish to capture). 15902Then the @code{backtrace} command will show a partial backtrace when 15903using a trace frame. The number of stack frames that can be examined 15904depends on the sizes of the frames in the collected stack. Note that 15905if you ask for a block so large that it goes past the bottom of the 15906stack, the target agent may report an error trying to read from an 15907invalid address. 15908 15909@item 15910If you do not collect registers at a tracepoint, @value{GDBN} can 15911infer that the value of @code{$pc} must be the same as the address of 15912the tracepoint and use that when you are looking at a trace frame 15913for that tracepoint. However, this cannot work if the tracepoint has 15914multiple locations (for instance if it was set in a function that was 15915inlined), or if it has a @code{while-stepping} loop. In those cases 15916@value{GDBN} will warn you that it can't infer @code{$pc}, and default 15917it to zero. 15918 15919@end itemize 15920 15921@node Analyze Collected Data 15922@section Using the Collected Data 15923 15924After the tracepoint experiment ends, you use @value{GDBN} commands 15925for examining the trace data. The basic idea is that each tracepoint 15926collects a trace @dfn{snapshot} every time it is hit and another 15927snapshot every time it single-steps. All these snapshots are 15928consecutively numbered from zero and go into a buffer, and you can 15929examine them later. The way you examine them is to @dfn{focus} on a 15930specific trace snapshot. When the remote stub is focused on a trace 15931snapshot, it will respond to all @value{GDBN} requests for memory and 15932registers by reading from the buffer which belongs to that snapshot, 15933rather than from @emph{real} memory or registers of the program being 15934debugged. This means that @strong{all} @value{GDBN} commands 15935(@code{print}, @code{info registers}, @code{backtrace}, etc.) will 15936behave as if we were currently debugging the program state as it was 15937when the tracepoint occurred. Any requests for data that are not in 15938the buffer will fail. 15939 15940@menu 15941* tfind:: How to select a trace snapshot 15942* tdump:: How to display all data for a snapshot 15943* save tracepoints:: How to save tracepoints for a future run 15944@end menu 15945 15946@node tfind 15947@subsection @code{tfind @var{n}} 15948 15949@kindex tfind 15950@cindex select trace snapshot 15951@cindex find trace snapshot 15952The basic command for selecting a trace snapshot from the buffer is 15953@code{tfind @var{n}}, which finds trace snapshot number @var{n}, 15954counting from zero. If no argument @var{n} is given, the next 15955snapshot is selected. 15956 15957Here are the various forms of using the @code{tfind} command. 15958 15959@table @code 15960@item tfind start 15961Find the first snapshot in the buffer. This is a synonym for 15962@code{tfind 0} (since 0 is the number of the first snapshot). 15963 15964@item tfind none 15965Stop debugging trace snapshots, resume @emph{live} debugging. 15966 15967@item tfind end 15968Same as @samp{tfind none}. 15969 15970@item tfind 15971No argument means find the next trace snapshot or find the first 15972one if no trace snapshot is selected. 15973 15974@item tfind - 15975Find the previous trace snapshot before the current one. This permits 15976retracing earlier steps. 15977 15978@item tfind tracepoint @var{num} 15979Find the next snapshot associated with tracepoint @var{num}. Search 15980proceeds forward from the last examined trace snapshot. If no 15981argument @var{num} is given, it means find the next snapshot collected 15982for the same tracepoint as the current snapshot. 15983 15984@item tfind pc @var{addr} 15985Find the next snapshot associated with the value @var{addr} of the 15986program counter. Search proceeds forward from the last examined trace 15987snapshot. If no argument @var{addr} is given, it means find the next 15988snapshot with the same value of PC as the current snapshot. 15989 15990@item tfind outside @var{addr1}, @var{addr2} 15991Find the next snapshot whose PC is outside the given range of 15992addresses (exclusive). 15993 15994@item tfind range @var{addr1}, @var{addr2} 15995Find the next snapshot whose PC is between @var{addr1} and 15996@var{addr2} (inclusive). 15997 15998@item tfind line @r{[}@var{file}:@r{]}@var{n} 15999Find the next snapshot associated with the source line @var{n}. If 16000the optional argument @var{file} is given, refer to line @var{n} in 16001that source file. Search proceeds forward from the last examined 16002trace snapshot. If no argument @var{n} is given, it means find the 16003next line other than the one currently being examined; thus saying 16004@code{tfind line} repeatedly can appear to have the same effect as 16005stepping from line to line in a @emph{live} debugging session. 16006@end table 16007 16008The default arguments for the @code{tfind} commands are specifically 16009designed to make it easy to scan through the trace buffer. For 16010instance, @code{tfind} with no argument selects the next trace 16011snapshot, and @code{tfind -} with no argument selects the previous 16012trace snapshot. So, by giving one @code{tfind} command, and then 16013simply hitting @key{RET} repeatedly you can examine all the trace 16014snapshots in order. Or, by saying @code{tfind -} and then hitting 16015@key{RET} repeatedly you can examine the snapshots in reverse order. 16016The @code{tfind line} command with no argument selects the snapshot 16017for the next source line executed. The @code{tfind pc} command with 16018no argument selects the next snapshot with the same program counter 16019(PC) as the current frame. The @code{tfind tracepoint} command with 16020no argument selects the next trace snapshot collected by the same 16021tracepoint as the current one. 16022 16023In addition to letting you scan through the trace buffer manually, 16024these commands make it easy to construct @value{GDBN} scripts that 16025scan through the trace buffer and print out whatever collected data 16026you are interested in. Thus, if we want to examine the PC, FP, and SP 16027registers from each trace frame in the buffer, we can say this: 16028 16029@smallexample 16030(@value{GDBP}) @b{tfind start} 16031(@value{GDBP}) @b{while ($trace_frame != -1)} 16032> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ 16033 $trace_frame, $pc, $sp, $fp 16034> tfind 16035> end 16036 16037Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 16038Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 16039Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 16040Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 16041Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 16042Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 16043Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 16044Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 16045Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 16046Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 16047Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 16048@end smallexample 16049 16050Or, if we want to examine the variable @code{X} at each source line in 16051the buffer: 16052 16053@smallexample 16054(@value{GDBP}) @b{tfind start} 16055(@value{GDBP}) @b{while ($trace_frame != -1)} 16056> printf "Frame %d, X == %d\n", $trace_frame, X 16057> tfind line 16058> end 16059 16060Frame 0, X = 1 16061Frame 7, X = 2 16062Frame 13, X = 255 16063@end smallexample 16064 16065@node tdump 16066@subsection @code{tdump} 16067@kindex tdump 16068@cindex dump all data collected at tracepoint 16069@cindex tracepoint data, display 16070 16071This command takes no arguments. It prints all the data collected at 16072the current trace snapshot. 16073 16074@smallexample 16075(@value{GDBP}) @b{trace 444} 16076(@value{GDBP}) @b{actions} 16077Enter actions for tracepoint #2, one per line: 16078> collect $regs, $locals, $args, gdb_long_test 16079> end 16080 16081(@value{GDBP}) @b{tstart} 16082 16083(@value{GDBP}) @b{tfind line 444} 16084#0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) 16085at gdb_test.c:444 16086444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) 16087 16088(@value{GDBP}) @b{tdump} 16089Data collected at tracepoint 2, trace frame 1: 16090d0 0xc4aa0085 -995491707 16091d1 0x18 24 16092d2 0x80 128 16093d3 0x33 51 16094d4 0x71aea3d 119204413 16095d5 0x22 34 16096d6 0xe0 224 16097d7 0x380035 3670069 16098a0 0x19e24a 1696330 16099a1 0x3000668 50333288 16100a2 0x100 256 16101a3 0x322000 3284992 16102a4 0x3000698 50333336 16103a5 0x1ad3cc 1758156 16104fp 0x30bf3c 0x30bf3c 16105sp 0x30bf34 0x30bf34 16106ps 0x0 0 16107pc 0x20b2c8 0x20b2c8 16108fpcontrol 0x0 0 16109fpstatus 0x0 0 16110fpiaddr 0x0 0 16111p = 0x20e5b4 "gdb-test" 16112p1 = (void *) 0x11 16113p2 = (void *) 0x22 16114p3 = (void *) 0x33 16115p4 = (void *) 0x44 16116p5 = (void *) 0x55 16117p6 = (void *) 0x66 16118gdb_long_test = 17 '\021' 16119 16120(@value{GDBP}) 16121@end smallexample 16122 16123@code{tdump} works by scanning the tracepoint's current collection 16124actions and printing the value of each expression listed. So 16125@code{tdump} can fail, if after a run, you change the tracepoint's 16126actions to mention variables that were not collected during the run. 16127 16128Also, for tracepoints with @code{while-stepping} loops, @code{tdump} 16129uses the collected value of @code{$pc} to distinguish between trace 16130frames that were collected at the tracepoint hit, and frames that were 16131collected while stepping. This allows it to correctly choose whether 16132to display the basic list of collections, or the collections from the 16133body of the while-stepping loop. However, if @code{$pc} was not collected, 16134then @code{tdump} will always attempt to dump using the basic collection 16135list, and may fail if a while-stepping frame does not include all the 16136same data that is collected at the tracepoint hit. 16137@c This is getting pretty arcane, example would be good. 16138 16139@node save tracepoints 16140@subsection @code{save tracepoints @var{filename}} 16141@kindex save tracepoints 16142@kindex save-tracepoints 16143@cindex save tracepoints for future sessions 16144 16145This command saves all current tracepoint definitions together with 16146their actions and passcounts, into a file @file{@var{filename}} 16147suitable for use in a later debugging session. To read the saved 16148tracepoint definitions, use the @code{source} command (@pxref{Command 16149Files}). The @w{@code{save-tracepoints}} command is a deprecated 16150alias for @w{@code{save tracepoints}} 16151 16152@node Tracepoint Variables 16153@section Convenience Variables for Tracepoints 16154@cindex tracepoint variables 16155@cindex convenience variables for tracepoints 16156 16157@table @code 16158@vindex $trace_frame 16159@item (int) $trace_frame 16160The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no 16161snapshot is selected. 16162 16163@vindex $tracepoint 16164@item (int) $tracepoint 16165The tracepoint for the current trace snapshot. 16166 16167@vindex $trace_line 16168@item (int) $trace_line 16169The line number for the current trace snapshot. 16170 16171@vindex $trace_file 16172@item (char []) $trace_file 16173The source file for the current trace snapshot. 16174 16175@vindex $trace_func 16176@item (char []) $trace_func 16177The name of the function containing @code{$tracepoint}. 16178@end table 16179 16180Note: @code{$trace_file} is not suitable for use in @code{printf}, 16181use @code{output} instead. 16182 16183Here's a simple example of using these convenience variables for 16184stepping through all the trace snapshots and printing some of their 16185data. Note that these are not the same as trace state variables, 16186which are managed by the target. 16187 16188@smallexample 16189(@value{GDBP}) @b{tfind start} 16190 16191(@value{GDBP}) @b{while $trace_frame != -1} 16192> output $trace_file 16193> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint 16194> tfind 16195> end 16196@end smallexample 16197 16198@node Trace Files 16199@section Using Trace Files 16200@cindex trace files 16201 16202In some situations, the target running a trace experiment may no 16203longer be available; perhaps it crashed, or the hardware was needed 16204for a different activity. To handle these cases, you can arrange to 16205dump the trace data into a file, and later use that file as a source 16206of trace data, via the @code{target tfile} command. 16207 16208@table @code 16209 16210@kindex tsave 16211@item tsave [ -r ] @var{filename} 16212@itemx tsave [-ctf] @var{dirname} 16213Save the trace data to @var{filename}. By default, this command 16214assumes that @var{filename} refers to the host filesystem, so if 16215necessary @value{GDBN} will copy raw trace data up from the target and 16216then save it. If the target supports it, you can also supply the 16217optional argument @code{-r} (``remote'') to direct the target to save 16218the data directly into @var{filename} in its own filesystem, which may be 16219more efficient if the trace buffer is very large. (Note, however, that 16220@code{target tfile} can only read from files accessible to the host.) 16221By default, this command will save trace frame in tfile format. 16222You can supply the optional argument @code{-ctf} to save data in CTF 16223format. The @dfn{Common Trace Format} (CTF) is proposed as a trace format 16224that can be shared by multiple debugging and tracing tools. Please go to 16225@indicateurl{http://www.efficios.com/ctf} to get more information. 16226 16227@kindex target tfile 16228@kindex tfile 16229@kindex target ctf 16230@kindex ctf 16231@item target tfile @var{filename} 16232@itemx target ctf @var{dirname} 16233Use the file named @var{filename} or directory named @var{dirname} as 16234a source of trace data. Commands that examine data work as they do with 16235a live target, but it is not possible to run any new trace experiments. 16236@code{tstatus} will report the state of the trace run at the moment 16237the data was saved, as well as the current trace frame you are examining. 16238Both @var{filename} and @var{dirname} must be on a filesystem accessible to 16239the host. 16240 16241@smallexample 16242(@value{GDBP}) target ctf ctf.ctf 16243(@value{GDBP}) tfind 16244Found trace frame 0, tracepoint 2 1624539 ++a; /* set tracepoint 1 here */ 16246(@value{GDBP}) tdump 16247Data collected at tracepoint 2, trace frame 0: 16248i = 0 16249a = 0 16250b = 1 '\001' 16251c = @{"123", "456", "789", "123", "456", "789"@} 16252d = @{@{@{a = 1, b = 2@}, @{a = 3, b = 4@}@}, @{@{a = 5, b = 6@}, @{a = 7, b = 8@}@}@} 16253(@value{GDBP}) p b 16254$1 = 1 16255@end smallexample 16256 16257@end table 16258 16259@node Overlays 16260@chapter Debugging Programs That Use Overlays 16261@cindex overlays 16262 16263If your program is too large to fit completely in your target system's 16264memory, you can sometimes use @dfn{overlays} to work around this 16265problem. @value{GDBN} provides some support for debugging programs that 16266use overlays. 16267 16268@menu 16269* How Overlays Work:: A general explanation of overlays. 16270* Overlay Commands:: Managing overlays in @value{GDBN}. 16271* Automatic Overlay Debugging:: @value{GDBN} can find out which overlays are 16272 mapped by asking the inferior. 16273* Overlay Sample Program:: A sample program using overlays. 16274@end menu 16275 16276@node How Overlays Work 16277@section How Overlays Work 16278@cindex mapped overlays 16279@cindex unmapped overlays 16280@cindex load address, overlay's 16281@cindex mapped address 16282@cindex overlay area 16283 16284Suppose you have a computer whose instruction address space is only 64 16285kilobytes long, but which has much more memory which can be accessed by 16286other means: special instructions, segment registers, or memory 16287management hardware, for example. Suppose further that you want to 16288adapt a program which is larger than 64 kilobytes to run on this system. 16289 16290One solution is to identify modules of your program which are relatively 16291independent, and need not call each other directly; call these modules 16292@dfn{overlays}. Separate the overlays from the main program, and place 16293their machine code in the larger memory. Place your main program in 16294instruction memory, but leave at least enough space there to hold the 16295largest overlay as well. 16296 16297Now, to call a function located in an overlay, you must first copy that 16298overlay's machine code from the large memory into the space set aside 16299for it in the instruction memory, and then jump to its entry point 16300there. 16301 16302@c NB: In the below the mapped area's size is greater or equal to the 16303@c size of all overlays. This is intentional to remind the developer 16304@c that overlays don't necessarily need to be the same size. 16305 16306@smallexample 16307@group 16308 Data Instruction Larger 16309Address Space Address Space Address Space 16310+-----------+ +-----------+ +-----------+ 16311| | | | | | 16312+-----------+ +-----------+ +-----------+<-- overlay 1 16313| program | | main | .----| overlay 1 | load address 16314| variables | | program | | +-----------+ 16315| and heap | | | | | | 16316+-----------+ | | | +-----------+<-- overlay 2 16317| | +-----------+ | | | load address 16318+-----------+ | | | .-| overlay 2 | 16319 | | | | | | 16320 mapped --->+-----------+ | | +-----------+ 16321 address | | | | | | 16322 | overlay | <-' | | | 16323 | area | <---' +-----------+<-- overlay 3 16324 | | <---. | | load address 16325 +-----------+ `--| overlay 3 | 16326 | | | | 16327 +-----------+ | | 16328 +-----------+ 16329 | | 16330 +-----------+ 16331 16332 @anchor{A code overlay}A code overlay 16333@end group 16334@end smallexample 16335 16336The diagram (@pxref{A code overlay}) shows a system with separate data 16337and instruction address spaces. To map an overlay, the program copies 16338its code from the larger address space to the instruction address space. 16339Since the overlays shown here all use the same mapped address, only one 16340may be mapped at a time. For a system with a single address space for 16341data and instructions, the diagram would be similar, except that the 16342program variables and heap would share an address space with the main 16343program and the overlay area. 16344 16345An overlay loaded into instruction memory and ready for use is called a 16346@dfn{mapped} overlay; its @dfn{mapped address} is its address in the 16347instruction memory. An overlay not present (or only partially present) 16348in instruction memory is called @dfn{unmapped}; its @dfn{load address} 16349is its address in the larger memory. The mapped address is also called 16350the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also 16351called the @dfn{load memory address}, or @dfn{LMA}. 16352 16353Unfortunately, overlays are not a completely transparent way to adapt a 16354program to limited instruction memory. They introduce a new set of 16355global constraints you must keep in mind as you design your program: 16356 16357@itemize @bullet 16358 16359@item 16360Before calling or returning to a function in an overlay, your program 16361must make sure that overlay is actually mapped. Otherwise, the call or 16362return will transfer control to the right address, but in the wrong 16363overlay, and your program will probably crash. 16364 16365@item 16366If the process of mapping an overlay is expensive on your system, you 16367will need to choose your overlays carefully to minimize their effect on 16368your program's performance. 16369 16370@item 16371The executable file you load onto your system must contain each 16372overlay's instructions, appearing at the overlay's load address, not its 16373mapped address. However, each overlay's instructions must be relocated 16374and its symbols defined as if the overlay were at its mapped address. 16375You can use GNU linker scripts to specify different load and relocation 16376addresses for pieces of your program; see @ref{Overlay Description,,, 16377ld.info, Using ld: the GNU linker}. 16378 16379@item 16380The procedure for loading executable files onto your system must be able 16381to load their contents into the larger address space as well as the 16382instruction and data spaces. 16383 16384@end itemize 16385 16386The overlay system described above is rather simple, and could be 16387improved in many ways: 16388 16389@itemize @bullet 16390 16391@item 16392If your system has suitable bank switch registers or memory management 16393hardware, you could use those facilities to make an overlay's load area 16394contents simply appear at their mapped address in instruction space. 16395This would probably be faster than copying the overlay to its mapped 16396area in the usual way. 16397 16398@item 16399If your overlays are small enough, you could set aside more than one 16400overlay area, and have more than one overlay mapped at a time. 16401 16402@item 16403You can use overlays to manage data, as well as instructions. In 16404general, data overlays are even less transparent to your design than 16405code overlays: whereas code overlays only require care when you call or 16406return to functions, data overlays require care every time you access 16407the data. Also, if you change the contents of a data overlay, you 16408must copy its contents back out to its load address before you can copy a 16409different data overlay into the same mapped area. 16410 16411@end itemize 16412 16413 16414@node Overlay Commands 16415@section Overlay Commands 16416 16417To use @value{GDBN}'s overlay support, each overlay in your program must 16418correspond to a separate section of the executable file. The section's 16419virtual memory address and load memory address must be the overlay's 16420mapped and load addresses. Identifying overlays with sections allows 16421@value{GDBN} to determine the appropriate address of a function or 16422variable, depending on whether the overlay is mapped or not. 16423 16424@value{GDBN}'s overlay commands all start with the word @code{overlay}; 16425you can abbreviate this as @code{ov} or @code{ovly}. The commands are: 16426 16427@table @code 16428@item overlay off 16429@kindex overlay 16430Disable @value{GDBN}'s overlay support. When overlay support is 16431disabled, @value{GDBN} assumes that all functions and variables are 16432always present at their mapped addresses. By default, @value{GDBN}'s 16433overlay support is disabled. 16434 16435@item overlay manual 16436@cindex manual overlay debugging 16437Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN} 16438relies on you to tell it which overlays are mapped, and which are not, 16439using the @code{overlay map-overlay} and @code{overlay unmap-overlay} 16440commands described below. 16441 16442@item overlay map-overlay @var{overlay} 16443@itemx overlay map @var{overlay} 16444@cindex map an overlay 16445Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must 16446be the name of the object file section containing the overlay. When an 16447overlay is mapped, @value{GDBN} assumes it can find the overlay's 16448functions and variables at their mapped addresses. @value{GDBN} assumes 16449that any other overlays whose mapped ranges overlap that of 16450@var{overlay} are now unmapped. 16451 16452@item overlay unmap-overlay @var{overlay} 16453@itemx overlay unmap @var{overlay} 16454@cindex unmap an overlay 16455Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay} 16456must be the name of the object file section containing the overlay. 16457When an overlay is unmapped, @value{GDBN} assumes it can find the 16458overlay's functions and variables at their load addresses. 16459 16460@item overlay auto 16461Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN} 16462consults a data structure the overlay manager maintains in the inferior 16463to see which overlays are mapped. For details, see @ref{Automatic 16464Overlay Debugging}. 16465 16466@item overlay load-target 16467@itemx overlay load 16468@cindex reloading the overlay table 16469Re-read the overlay table from the inferior. Normally, @value{GDBN} 16470re-reads the table @value{GDBN} automatically each time the inferior 16471stops, so this command should only be necessary if you have changed the 16472overlay mapping yourself using @value{GDBN}. This command is only 16473useful when using automatic overlay debugging. 16474 16475@item overlay list-overlays 16476@itemx overlay list 16477@cindex listing mapped overlays 16478Display a list of the overlays currently mapped, along with their mapped 16479addresses, load addresses, and sizes. 16480 16481@end table 16482 16483Normally, when @value{GDBN} prints a code address, it includes the name 16484of the function the address falls in: 16485 16486@smallexample 16487(@value{GDBP}) print main 16488$3 = @{int ()@} 0x11a0 <main> 16489@end smallexample 16490@noindent 16491When overlay debugging is enabled, @value{GDBN} recognizes code in 16492unmapped overlays, and prints the names of unmapped functions with 16493asterisks around them. For example, if @code{foo} is a function in an 16494unmapped overlay, @value{GDBN} prints it this way: 16495 16496@smallexample 16497(@value{GDBP}) overlay list 16498No sections are mapped. 16499(@value{GDBP}) print foo 16500$5 = @{int (int)@} 0x100000 <*foo*> 16501@end smallexample 16502@noindent 16503When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's 16504name normally: 16505 16506@smallexample 16507(@value{GDBP}) overlay list 16508Section .ov.foo.text, loaded at 0x100000 - 0x100034, 16509 mapped at 0x1016 - 0x104a 16510(@value{GDBP}) print foo 16511$6 = @{int (int)@} 0x1016 <foo> 16512@end smallexample 16513 16514When overlay debugging is enabled, @value{GDBN} can find the correct 16515address for functions and variables in an overlay, whether or not the 16516overlay is mapped. This allows most @value{GDBN} commands, like 16517@code{break} and @code{disassemble}, to work normally, even on unmapped 16518code. However, @value{GDBN}'s breakpoint support has some limitations: 16519 16520@itemize @bullet 16521@item 16522@cindex breakpoints in overlays 16523@cindex overlays, setting breakpoints in 16524You can set breakpoints in functions in unmapped overlays, as long as 16525@value{GDBN} can write to the overlay at its load address. 16526@item 16527@value{GDBN} can not set hardware or simulator-based breakpoints in 16528unmapped overlays. However, if you set a breakpoint at the end of your 16529overlay manager (and tell @value{GDBN} which overlays are now mapped, if 16530you are using manual overlay management), @value{GDBN} will re-set its 16531breakpoints properly. 16532@end itemize 16533 16534 16535@node Automatic Overlay Debugging 16536@section Automatic Overlay Debugging 16537@cindex automatic overlay debugging 16538 16539@value{GDBN} can automatically track which overlays are mapped and which 16540are not, given some simple co-operation from the overlay manager in the 16541inferior. If you enable automatic overlay debugging with the 16542@code{overlay auto} command (@pxref{Overlay Commands}), @value{GDBN} 16543looks in the inferior's memory for certain variables describing the 16544current state of the overlays. 16545 16546Here are the variables your overlay manager must define to support 16547@value{GDBN}'s automatic overlay debugging: 16548 16549@table @asis 16550 16551@item @code{_ovly_table}: 16552This variable must be an array of the following structures: 16553 16554@smallexample 16555struct 16556@{ 16557 /* The overlay's mapped address. */ 16558 unsigned long vma; 16559 16560 /* The size of the overlay, in bytes. */ 16561 unsigned long size; 16562 16563 /* The overlay's load address. */ 16564 unsigned long lma; 16565 16566 /* Non-zero if the overlay is currently mapped; 16567 zero otherwise. */ 16568 unsigned long mapped; 16569@} 16570@end smallexample 16571 16572@item @code{_novlys}: 16573This variable must be a four-byte signed integer, holding the total 16574number of elements in @code{_ovly_table}. 16575 16576@end table 16577 16578To decide whether a particular overlay is mapped or not, @value{GDBN} 16579looks for an entry in @w{@code{_ovly_table}} whose @code{vma} and 16580@code{lma} members equal the VMA and LMA of the overlay's section in the 16581executable file. When @value{GDBN} finds a matching entry, it consults 16582the entry's @code{mapped} member to determine whether the overlay is 16583currently mapped. 16584 16585In addition, your overlay manager may define a function called 16586@code{_ovly_debug_event}. If this function is defined, @value{GDBN} 16587will silently set a breakpoint there. If the overlay manager then 16588calls this function whenever it has changed the overlay table, this 16589will enable @value{GDBN} to accurately keep track of which overlays 16590are in program memory, and update any breakpoints that may be set 16591in overlays. This will allow breakpoints to work even if the 16592overlays are kept in ROM or other non-writable memory while they 16593are not being executed. 16594 16595@node Overlay Sample Program 16596@section Overlay Sample Program 16597@cindex overlay example program 16598 16599When linking a program which uses overlays, you must place the overlays 16600at their load addresses, while relocating them to run at their mapped 16601addresses. To do this, you must write a linker script (@pxref{Overlay 16602Description,,, ld.info, Using ld: the GNU linker}). Unfortunately, 16603since linker scripts are specific to a particular host system, target 16604architecture, and target memory layout, this manual cannot provide 16605portable sample code demonstrating @value{GDBN}'s overlay support. 16606 16607However, the @value{GDBN} source distribution does contain an overlaid 16608program, with linker scripts for a few systems, as part of its test 16609suite. The program consists of the following files from 16610@file{gdb/testsuite/gdb.base}: 16611 16612@table @file 16613@item overlays.c 16614The main program file. 16615@item ovlymgr.c 16616A simple overlay manager, used by @file{overlays.c}. 16617@item foo.c 16618@itemx bar.c 16619@itemx baz.c 16620@itemx grbx.c 16621Overlay modules, loaded and used by @file{overlays.c}. 16622@item d10v.ld 16623@itemx m32r.ld 16624Linker scripts for linking the test program on the @code{d10v-elf} 16625and @code{m32r-elf} targets. 16626@end table 16627 16628You can build the test program using the @code{d10v-elf} GCC 16629cross-compiler like this: 16630 16631@smallexample 16632$ d10v-elf-gcc -g -c overlays.c 16633$ d10v-elf-gcc -g -c ovlymgr.c 16634$ d10v-elf-gcc -g -c foo.c 16635$ d10v-elf-gcc -g -c bar.c 16636$ d10v-elf-gcc -g -c baz.c 16637$ d10v-elf-gcc -g -c grbx.c 16638$ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ 16639 baz.o grbx.o -Wl,-Td10v.ld -o overlays 16640@end smallexample 16641 16642The build process is identical for any other architecture, except that 16643you must substitute the appropriate compiler and linker script for the 16644target system for @code{d10v-elf-gcc} and @code{d10v.ld}. 16645 16646 16647@node Languages 16648@chapter Using @value{GDBN} with Different Languages 16649@cindex languages 16650 16651Although programming languages generally have common aspects, they are 16652rarely expressed in the same manner. For instance, in ANSI C, 16653dereferencing a pointer @code{p} is accomplished by @code{*p}, but in 16654Modula-2, it is accomplished by @code{p^}. Values can also be 16655represented (and displayed) differently. Hex numbers in C appear as 16656@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}. 16657 16658@cindex working language 16659Language-specific information is built into @value{GDBN} for some languages, 16660allowing you to express operations like the above in your program's 16661native language, and allowing @value{GDBN} to output values in a manner 16662consistent with the syntax of your program's native language. The 16663language you use to build expressions is called the @dfn{working 16664language}. 16665 16666@menu 16667* Setting:: Switching between source languages 16668* Show:: Displaying the language 16669* Checks:: Type and range checks 16670* Supported Languages:: Supported languages 16671* Unsupported Languages:: Unsupported languages 16672@end menu 16673 16674@node Setting 16675@section Switching Between Source Languages 16676 16677There are two ways to control the working language---either have @value{GDBN} 16678set it automatically, or select it manually yourself. You can use the 16679@code{set language} command for either purpose. On startup, @value{GDBN} 16680defaults to setting the language automatically. The working language is 16681used to determine how expressions you type are interpreted, how values 16682are printed, etc. 16683 16684In addition to the working language, every source file that 16685@value{GDBN} knows about has its own working language. For some object 16686file formats, the compiler might indicate which language a particular 16687source file is in. However, most of the time @value{GDBN} infers the 16688language from the name of the file. The language of a source file 16689controls whether C@t{++} names are demangled---this way @code{backtrace} can 16690show each frame appropriately for its own language. There is no way to 16691set the language of a source file from within @value{GDBN}, but you can 16692set the language associated with a filename extension. @xref{Show, , 16693Displaying the Language}. 16694 16695This is most commonly a problem when you use a program, such 16696as @code{cfront} or @code{f2c}, that generates C but is written in 16697another language. In that case, make the 16698program use @code{#line} directives in its C output; that way 16699@value{GDBN} will know the correct language of the source code of the original 16700program, and will display that source code, not the generated C code. 16701 16702@menu 16703* Filenames:: Filename extensions and languages. 16704* Manually:: Setting the working language manually 16705* Automatically:: Having @value{GDBN} infer the source language 16706@end menu 16707 16708@node Filenames 16709@subsection List of Filename Extensions and Languages 16710 16711If a source file name ends in one of the following extensions, then 16712@value{GDBN} infers that its language is the one indicated. 16713 16714@table @file 16715@item .ada 16716@itemx .ads 16717@itemx .adb 16718@itemx .a 16719Ada source file. 16720 16721@item .c 16722C source file 16723 16724@item .C 16725@itemx .cc 16726@itemx .cp 16727@itemx .cpp 16728@itemx .cxx 16729@itemx .c++ 16730C@t{++} source file 16731 16732@item .d 16733D source file 16734 16735@item .m 16736Objective-C source file 16737 16738@item .f 16739@itemx .F 16740Fortran source file 16741 16742@item .mod 16743Modula-2 source file 16744 16745@item .s 16746@itemx .S 16747Assembler source file. This actually behaves almost like C, but 16748@value{GDBN} does not skip over function prologues when stepping. 16749@end table 16750 16751In addition, you may set the language associated with a filename 16752extension. @xref{Show, , Displaying the Language}. 16753 16754@node Manually 16755@subsection Setting the Working Language 16756 16757If you allow @value{GDBN} to set the language automatically, 16758expressions are interpreted the same way in your debugging session and 16759your program. 16760 16761@kindex set language 16762If you wish, you may set the language manually. To do this, issue the 16763command @samp{set language @var{lang}}, where @var{lang} is the name of 16764a language, such as 16765@code{c} or @code{modula-2}. 16766For a list of the supported languages, type @samp{set language}. 16767 16768Setting the language manually prevents @value{GDBN} from updating the working 16769language automatically. This can lead to confusion if you try 16770to debug a program when the working language is not the same as the 16771source language, when an expression is acceptable to both 16772languages---but means different things. For instance, if the current 16773source file were written in C, and @value{GDBN} was parsing Modula-2, a 16774command such as: 16775 16776@smallexample 16777print a = b + c 16778@end smallexample 16779 16780@noindent 16781might not have the effect you intended. In C, this means to add 16782@code{b} and @code{c} and place the result in @code{a}. The result 16783printed would be the value of @code{a}. In Modula-2, this means to compare 16784@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value. 16785 16786@node Automatically 16787@subsection Having @value{GDBN} Infer the Source Language 16788 16789To have @value{GDBN} set the working language automatically, use 16790@samp{set language local} or @samp{set language auto}. @value{GDBN} 16791then infers the working language. That is, when your program stops in a 16792frame (usually by encountering a breakpoint), @value{GDBN} sets the 16793working language to the language recorded for the function in that 16794frame. If the language for a frame is unknown (that is, if the function 16795or block corresponding to the frame was defined in a source file that 16796does not have a recognized extension), the current working language is 16797not changed, and @value{GDBN} issues a warning. 16798 16799This may not seem necessary for most programs, which are written 16800entirely in one source language. However, program modules and libraries 16801written in one source language can be used by a main program written in 16802a different source language. Using @samp{set language auto} in this 16803case frees you from having to set the working language manually. 16804 16805@node Show 16806@section Displaying the Language 16807 16808The following commands help you find out which language is the 16809working language, and also what language source files were written in. 16810 16811@table @code 16812@item show language 16813@anchor{show language} 16814@kindex show language 16815Display the current working language. This is the 16816language you can use with commands such as @code{print} to 16817build and compute expressions that may involve variables in your program. 16818 16819@item info frame 16820@kindex info frame@r{, show the source language} 16821Display the source language for this frame. This language becomes the 16822working language if you use an identifier from this frame. 16823@xref{Frame Info, ,Information about a Frame}, to identify the other 16824information listed here. 16825 16826@item info source 16827@kindex info source@r{, show the source language} 16828Display the source language of this source file. 16829@xref{Symbols, ,Examining the Symbol Table}, to identify the other 16830information listed here. 16831@end table 16832 16833In unusual circumstances, you may have source files with extensions 16834not in the standard list. You can then set the extension associated 16835with a language explicitly: 16836 16837@table @code 16838@item set extension-language @var{ext} @var{language} 16839@kindex set extension-language 16840Tell @value{GDBN} that source files with extension @var{ext} are to be 16841assumed as written in the source language @var{language}. 16842 16843@item info extensions 16844@kindex info extensions 16845List all the filename extensions and the associated languages. 16846@end table 16847 16848@node Checks 16849@section Type and Range Checking 16850 16851Some languages are designed to guard you against making seemingly common 16852errors through a series of compile- and run-time checks. These include 16853checking the type of arguments to functions and operators and making 16854sure mathematical overflows are caught at run time. Checks such as 16855these help to ensure a program's correctness once it has been compiled 16856by eliminating type mismatches and providing active checks for range 16857errors when your program is running. 16858 16859By default @value{GDBN} checks for these errors according to the 16860rules of the current source language. Although @value{GDBN} does not check 16861the statements in your program, it can check expressions entered directly 16862into @value{GDBN} for evaluation via the @code{print} command, for example. 16863 16864@menu 16865* Type Checking:: An overview of type checking 16866* Range Checking:: An overview of range checking 16867@end menu 16868 16869@cindex type checking 16870@cindex checks, type 16871@node Type Checking 16872@subsection An Overview of Type Checking 16873 16874Some languages, such as C and C@t{++}, are strongly typed, meaning that the 16875arguments to operators and functions have to be of the correct type, 16876otherwise an error occurs. These checks prevent type mismatch 16877errors from ever causing any run-time problems. For example, 16878 16879@smallexample 16880int klass::my_method(char *b) @{ return b ? 1 : 2; @} 16881 16882(@value{GDBP}) print obj.my_method (0) 16883$1 = 2 16884@exdent but 16885(@value{GDBP}) print obj.my_method (0x1234) 16886Cannot resolve method klass::my_method to any overloaded instance 16887@end smallexample 16888 16889The second example fails because in C@t{++} the integer constant 16890@samp{0x1234} is not type-compatible with the pointer parameter type. 16891 16892For the expressions you use in @value{GDBN} commands, you can tell 16893@value{GDBN} to not enforce strict type checking or 16894to treat any mismatches as errors and abandon the expression; 16895When type checking is disabled, @value{GDBN} successfully evaluates 16896expressions like the second example above. 16897 16898Even if type checking is off, there may be other reasons 16899related to type that prevent @value{GDBN} from evaluating an expression. 16900For instance, @value{GDBN} does not know how to add an @code{int} and 16901a @code{struct foo}. These particular type errors have nothing to do 16902with the language in use and usually arise from expressions which make 16903little sense to evaluate anyway. 16904 16905@value{GDBN} provides some additional commands for controlling type checking: 16906 16907@kindex set check type 16908@kindex show check type 16909@table @code 16910@item set check type on 16911@itemx set check type off 16912Set strict type checking on or off. If any type mismatches occur in 16913evaluating an expression while type checking is on, @value{GDBN} prints a 16914message and aborts evaluation of the expression. 16915 16916@item show check type 16917Show the current setting of type checking and whether @value{GDBN} 16918is enforcing strict type checking rules. 16919@end table 16920 16921@cindex range checking 16922@cindex checks, range 16923@node Range Checking 16924@subsection An Overview of Range Checking 16925 16926In some languages (such as Modula-2), it is an error to exceed the 16927bounds of a type; this is enforced with run-time checks. Such range 16928checking is meant to ensure program correctness by making sure 16929computations do not overflow, or indices on an array element access do 16930not exceed the bounds of the array. 16931 16932For expressions you use in @value{GDBN} commands, you can tell 16933@value{GDBN} to treat range errors in one of three ways: ignore them, 16934always treat them as errors and abandon the expression, or issue 16935warnings but evaluate the expression anyway. 16936 16937A range error can result from numerical overflow, from exceeding an 16938array index bound, or when you type a constant that is not a member 16939of any type. Some languages, however, do not treat overflows as an 16940error. In many implementations of C, mathematical overflow causes the 16941result to ``wrap around'' to lower values---for example, if @var{m} is 16942the largest integer value, and @var{s} is the smallest, then 16943 16944@smallexample 16945@var{m} + 1 @result{} @var{s} 16946@end smallexample 16947 16948This, too, is specific to individual languages, and in some cases 16949specific to individual compilers or machines. @xref{Supported Languages, , 16950Supported Languages}, for further details on specific languages. 16951 16952@value{GDBN} provides some additional commands for controlling the range checker: 16953 16954@kindex set check range 16955@kindex show check range 16956@table @code 16957@item set check range auto 16958Set range checking on or off based on the current working language. 16959@xref{Supported Languages, ,Supported Languages}, for the default settings for 16960each language. 16961 16962@item set check range on 16963@itemx set check range off 16964Set range checking on or off, overriding the default setting for the 16965current working language. A warning is issued if the setting does not 16966match the language default. If a range error occurs and range checking is on, 16967then a message is printed and evaluation of the expression is aborted. 16968 16969@item set check range warn 16970Output messages when the @value{GDBN} range checker detects a range error, 16971but attempt to evaluate the expression anyway. Evaluating the 16972expression may still be impossible for other reasons, such as accessing 16973memory that the process does not own (a typical example from many Unix 16974systems). 16975 16976@item show check range 16977Show the current setting of the range checker, and whether or not it is 16978being set automatically by @value{GDBN}. 16979@end table 16980 16981@node Supported Languages 16982@section Supported Languages 16983 16984@value{GDBN} supports C, C@t{++}, D, Go, Objective-C, Fortran, 16985OpenCL C, Pascal, Rust, assembly, Modula-2, and Ada. 16986@c This is false ... 16987Some @value{GDBN} features may be used in expressions regardless of the 16988language you use: the @value{GDBN} @code{@@} and @code{::} operators, 16989and the @samp{@{type@}addr} construct (@pxref{Expressions, 16990,Expressions}) can be used with the constructs of any supported 16991language. 16992 16993The following sections detail to what degree each source language is 16994supported by @value{GDBN}. These sections are not meant to be language 16995tutorials or references, but serve only as a reference guide to what the 16996@value{GDBN} expression parser accepts, and what input and output 16997formats should look like for different languages. There are many good 16998books written on each of these languages; please look to these for a 16999language reference or tutorial. 17000 17001@menu 17002* C:: C and C@t{++} 17003* D:: D 17004* Go:: Go 17005* Objective-C:: Objective-C 17006* OpenCL C:: OpenCL C 17007* Fortran:: Fortran 17008* Pascal:: Pascal 17009* Rust:: Rust 17010* Modula-2:: Modula-2 17011* Ada:: Ada 17012@end menu 17013 17014@node C 17015@subsection C and C@t{++} 17016 17017@cindex C and C@t{++} 17018@cindex expressions in C or C@t{++} 17019 17020Since C and C@t{++} are so closely related, many features of @value{GDBN} apply 17021to both languages. Whenever this is the case, we discuss those languages 17022together. 17023 17024@cindex C@t{++} 17025@cindex @code{g++}, @sc{gnu} C@t{++} compiler 17026@cindex @sc{gnu} C@t{++} 17027The C@t{++} debugging facilities are jointly implemented by the C@t{++} 17028compiler and @value{GDBN}. Therefore, to debug your C@t{++} code 17029effectively, you must compile your C@t{++} programs with a supported 17030C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++} 17031compiler (@code{aCC}). 17032 17033@menu 17034* C Operators:: C and C@t{++} operators 17035* C Constants:: C and C@t{++} constants 17036* C Plus Plus Expressions:: C@t{++} expressions 17037* C Defaults:: Default settings for C and C@t{++} 17038* C Checks:: C and C@t{++} type and range checks 17039* Debugging C:: @value{GDBN} and C 17040* Debugging C Plus Plus:: @value{GDBN} features for C@t{++} 17041* Decimal Floating Point:: Numbers in Decimal Floating Point format 17042@end menu 17043 17044@node C Operators 17045@subsubsection C and C@t{++} Operators 17046 17047@cindex C and C@t{++} operators 17048 17049Operators must be defined on values of specific types. For instance, 17050@code{+} is defined on numbers, but not on structures. Operators are 17051often defined on groups of types. 17052 17053For the purposes of C and C@t{++}, the following definitions hold: 17054 17055@itemize @bullet 17056 17057@item 17058@emph{Integral types} include @code{int} with any of its storage-class 17059specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}. 17060 17061@item 17062@emph{Floating-point types} include @code{float}, @code{double}, and 17063@code{long double} (if supported by the target platform). 17064 17065@item 17066@emph{Pointer types} include all types defined as @code{(@var{type} *)}. 17067 17068@item 17069@emph{Scalar types} include all of the above. 17070 17071@end itemize 17072 17073@noindent 17074The following operators are supported. They are listed here 17075in order of increasing precedence: 17076 17077@table @code 17078@item , 17079The comma or sequencing operator. Expressions in a comma-separated list 17080are evaluated from left to right, with the result of the entire 17081expression being the last expression evaluated. 17082 17083@item = 17084Assignment. The value of an assignment expression is the value 17085assigned. Defined on scalar types. 17086 17087@item @var{op}= 17088Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}}, 17089and translated to @w{@code{@var{a} = @var{a op b}}}. 17090@w{@code{@var{op}=}} and @code{=} have the same precedence. The operator 17091@var{op} is any one of the operators @code{|}, @code{^}, @code{&}, 17092@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}. 17093 17094@item ?: 17095The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought 17096of as: if @var{a} then @var{b} else @var{c}. The argument @var{a} 17097should be of an integral type. 17098 17099@item || 17100Logical @sc{or}. Defined on integral types. 17101 17102@item && 17103Logical @sc{and}. Defined on integral types. 17104 17105@item | 17106Bitwise @sc{or}. Defined on integral types. 17107 17108@item ^ 17109Bitwise exclusive-@sc{or}. Defined on integral types. 17110 17111@item & 17112Bitwise @sc{and}. Defined on integral types. 17113 17114@item ==@r{, }!= 17115Equality and inequality. Defined on scalar types. The value of these 17116expressions is 0 for false and non-zero for true. 17117 17118@item <@r{, }>@r{, }<=@r{, }>= 17119Less than, greater than, less than or equal, greater than or equal. 17120Defined on scalar types. The value of these expressions is 0 for false 17121and non-zero for true. 17122 17123@item <<@r{, }>> 17124left shift, and right shift. Defined on integral types. 17125 17126@item @@ 17127The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}). 17128 17129@item +@r{, }- 17130Addition and subtraction. Defined on integral types, floating-point types and 17131pointer types. 17132 17133@item *@r{, }/@r{, }% 17134Multiplication, division, and modulus. Multiplication and division are 17135defined on integral and floating-point types. Modulus is defined on 17136integral types. 17137 17138@item ++@r{, }-- 17139Increment and decrement. When appearing before a variable, the 17140operation is performed before the variable is used in an expression; 17141when appearing after it, the variable's value is used before the 17142operation takes place. 17143 17144@item * 17145Pointer dereferencing. Defined on pointer types. Same precedence as 17146@code{++}. 17147 17148@item & 17149Address operator. Defined on variables. Same precedence as @code{++}. 17150 17151For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is 17152allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})} 17153to examine the address 17154where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is 17155stored. 17156 17157@item - 17158Negative. Defined on integral and floating-point types. Same 17159precedence as @code{++}. 17160 17161@item ! 17162Logical negation. Defined on integral types. Same precedence as 17163@code{++}. 17164 17165@item ~ 17166Bitwise complement operator. Defined on integral types. Same precedence as 17167@code{++}. 17168 17169 17170@item .@r{, }-> 17171Structure member, and pointer-to-structure member. For convenience, 17172@value{GDBN} regards the two as equivalent, choosing whether to dereference a 17173pointer based on the stored type information. 17174Defined on @code{struct} and @code{union} data. 17175 17176@item .*@r{, }->* 17177Dereferences of pointers to members. 17178 17179@item [] 17180Array indexing. @code{@var{a}[@var{i}]} is defined as 17181@code{*(@var{a}+@var{i})}. Same precedence as @code{->}. 17182 17183@item () 17184Function parameter list. Same precedence as @code{->}. 17185 17186@item :: 17187C@t{++} scope resolution operator. Defined on @code{struct}, @code{union}, 17188and @code{class} types. 17189 17190@item :: 17191Doubled colons also represent the @value{GDBN} scope operator 17192(@pxref{Expressions, ,Expressions}). Same precedence as @code{::}, 17193above. 17194@end table 17195 17196If an operator is redefined in the user code, @value{GDBN} usually 17197attempts to invoke the redefined version instead of using the operator's 17198predefined meaning. 17199 17200@node C Constants 17201@subsubsection C and C@t{++} Constants 17202 17203@cindex C and C@t{++} constants 17204 17205@value{GDBN} allows you to express the constants of C and C@t{++} in the 17206following ways: 17207 17208@itemize @bullet 17209@item 17210Integer constants are a sequence of digits. Octal constants are 17211specified by a leading @samp{0} (i.e.@: zero), and hexadecimal constants 17212by a leading @samp{0x} or @samp{0X}. Constants may also end with a letter 17213@samp{l}, specifying that the constant should be treated as a 17214@code{long} value. 17215 17216@item 17217Floating point constants are a sequence of digits, followed by a decimal 17218point, followed by a sequence of digits, and optionally followed by an 17219exponent. An exponent is of the form: 17220@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another 17221sequence of digits. The @samp{+} is optional for positive exponents. 17222A floating-point constant may also end with a letter @samp{f} or 17223@samp{F}, specifying that the constant should be treated as being of 17224the @code{float} (as opposed to the default @code{double}) type; or with 17225a letter @samp{l} or @samp{L}, which specifies a @code{long double} 17226constant. 17227 17228@item 17229Enumerated constants consist of enumerated identifiers, or their 17230integral equivalents. 17231 17232@item 17233Character constants are a single character surrounded by single quotes 17234(@code{'}), or a number---the ordinal value of the corresponding character 17235(usually its @sc{ascii} value). Within quotes, the single character may 17236be represented by a letter or by @dfn{escape sequences}, which are of 17237the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation 17238of the character's ordinal value; or of the form @samp{\@var{x}}, where 17239@samp{@var{x}} is a predefined special character---for example, 17240@samp{\n} for newline. 17241 17242Wide character constants can be written by prefixing a character 17243constant with @samp{L}, as in C. For example, @samp{L'x'} is the wide 17244form of @samp{x}. The target wide character set is used when 17245computing the value of this constant (@pxref{Character Sets}). 17246 17247@item 17248String constants are a sequence of character constants surrounded by 17249double quotes (@code{"}). Any valid character constant (as described 17250above) may appear. Double quotes within the string must be preceded by 17251a backslash, so for instance @samp{"a\"b'c"} is a string of five 17252characters. 17253 17254Wide string constants can be written by prefixing a string constant 17255with @samp{L}, as in C. The target wide character set is used when 17256computing the value of this constant (@pxref{Character Sets}). 17257 17258@item 17259Pointer constants are an integral value. You can also write pointers 17260to constants using the C operator @samp{&}. 17261 17262@item 17263Array constants are comma-separated lists surrounded by braces @samp{@{} 17264and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of 17265integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array, 17266and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers. 17267@end itemize 17268 17269@node C Plus Plus Expressions 17270@subsubsection C@t{++} Expressions 17271 17272@cindex expressions in C@t{++} 17273@value{GDBN} expression handling can interpret most C@t{++} expressions. 17274 17275@cindex debugging C@t{++} programs 17276@cindex C@t{++} compilers 17277@cindex debug formats and C@t{++} 17278@cindex @value{NGCC} and C@t{++} 17279@quotation 17280@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use 17281the proper compiler and the proper debug format. Currently, 17282@value{GDBN} works best when debugging C@t{++} code that is compiled 17283with the most recent version of @value{NGCC} possible. The DWARF 17284debugging format is preferred; @value{NGCC} defaults to this on most 17285popular platforms. Other compilers and/or debug formats are likely to 17286work badly or not at all when using @value{GDBN} to debug C@t{++} 17287code. @xref{Compilation}. 17288@end quotation 17289 17290@enumerate 17291 17292@cindex member functions 17293@item 17294Member function calls are allowed; you can use expressions like 17295 17296@smallexample 17297count = aml->GetOriginal(x, y) 17298@end smallexample 17299 17300@vindex this@r{, inside C@t{++} member functions} 17301@cindex namespace in C@t{++} 17302@item 17303While a member function is active (in the selected stack frame), your 17304expressions have the same namespace available as the member function; 17305that is, @value{GDBN} allows implicit references to the class instance 17306pointer @code{this} following the same rules as C@t{++}. @code{using} 17307declarations in the current scope are also respected by @value{GDBN}. 17308 17309@cindex call overloaded functions 17310@cindex overloaded functions, calling 17311@cindex type conversions in C@t{++} 17312@item 17313You can call overloaded functions; @value{GDBN} resolves the function 17314call to the right definition, with some restrictions. @value{GDBN} does not 17315perform overload resolution involving user-defined type conversions, 17316calls to constructors, or instantiations of templates that do not exist 17317in the program. It also cannot handle ellipsis argument lists or 17318default arguments. 17319 17320It does perform integral conversions and promotions, floating-point 17321promotions, arithmetic conversions, pointer conversions, conversions of 17322class objects to base classes, and standard conversions such as those of 17323functions or arrays to pointers; it requires an exact match on the 17324number of function arguments. 17325 17326Overload resolution is always performed, unless you have specified 17327@code{set overload-resolution off}. @xref{Debugging C Plus Plus, 17328,@value{GDBN} Features for C@t{++}}. 17329 17330You must specify @code{set overload-resolution off} in order to use an 17331explicit function signature to call an overloaded function, as in 17332@smallexample 17333p 'foo(char,int)'('x', 13) 17334@end smallexample 17335 17336The @value{GDBN} command-completion facility can simplify this; 17337see @ref{Completion, ,Command Completion}. 17338 17339@cindex reference declarations 17340@item 17341@value{GDBN} understands variables declared as C@t{++} lvalue or rvalue 17342references; you can use them in expressions just as you do in C@t{++} 17343source---they are automatically dereferenced. 17344 17345In the parameter list shown when @value{GDBN} displays a frame, the values of 17346reference variables are not displayed (unlike other variables); this 17347avoids clutter, since references are often used for large structures. 17348The @emph{address} of a reference variable is always shown, unless 17349you have specified @samp{set print address off}. 17350 17351@item 17352@value{GDBN} supports the C@t{++} name resolution operator @code{::}---your 17353expressions can use it just as expressions in your program do. Since 17354one scope may be defined in another, you can use @code{::} repeatedly if 17355necessary, for example in an expression like 17356@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows 17357resolving name scope by reference to source files, in both C and C@t{++} 17358debugging (@pxref{Variables, ,Program Variables}). 17359 17360@item 17361@value{GDBN} performs argument-dependent lookup, following the C@t{++} 17362specification. 17363@end enumerate 17364 17365@node C Defaults 17366@subsubsection C and C@t{++} Defaults 17367 17368@cindex C and C@t{++} defaults 17369 17370If you allow @value{GDBN} to set range checking automatically, it 17371defaults to @code{off} whenever the working language changes to 17372C or C@t{++}. This happens regardless of whether you or @value{GDBN} 17373selects the working language. 17374 17375If you allow @value{GDBN} to set the language automatically, it 17376recognizes source files whose names end with @file{.c}, @file{.C}, or 17377@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of 17378these files, it sets the working language to C or C@t{++}. 17379@xref{Automatically, ,Having @value{GDBN} Infer the Source Language}, 17380for further details. 17381 17382@node C Checks 17383@subsubsection C and C@t{++} Type and Range Checks 17384 17385@cindex C and C@t{++} checks 17386 17387By default, when @value{GDBN} parses C or C@t{++} expressions, strict type 17388checking is used. However, if you turn type checking off, @value{GDBN} 17389will allow certain non-standard conversions, such as promoting integer 17390constants to pointers. 17391 17392Range checking, if turned on, is done on mathematical operations. Array 17393indices are not checked, since they are often used to index a pointer 17394that is not itself an array. 17395 17396@node Debugging C 17397@subsubsection @value{GDBN} and C 17398 17399The @code{set print union} and @code{show print union} commands apply to 17400the @code{union} type. When set to @samp{on}, any @code{union} that is 17401inside a @code{struct} or @code{class} is also printed. Otherwise, it 17402appears as @samp{@{...@}}. 17403 17404The @code{@@} operator aids in the debugging of dynamic arrays, formed 17405with pointers and a memory allocation function. @xref{Expressions, 17406,Expressions}. 17407 17408@node Debugging C Plus Plus 17409@subsubsection @value{GDBN} Features for C@t{++} 17410 17411@cindex commands for C@t{++} 17412 17413Some @value{GDBN} commands are particularly useful with C@t{++}, and some are 17414designed specifically for use with C@t{++}. Here is a summary: 17415 17416@table @code 17417@cindex break in overloaded functions 17418@item @r{breakpoint menus} 17419When you want a breakpoint in a function whose name is overloaded, 17420@value{GDBN} has the capability to display a menu of possible breakpoint 17421locations to help you specify which function definition you want. 17422@xref{Ambiguous Expressions,,Ambiguous Expressions}. 17423 17424@cindex overloading in C@t{++} 17425@item rbreak @var{regex} 17426Setting breakpoints using regular expressions is helpful for setting 17427breakpoints on overloaded functions that are not members of any special 17428classes. 17429@xref{Set Breaks, ,Setting Breakpoints}. 17430 17431@cindex C@t{++} exception handling 17432@item catch throw 17433@itemx catch rethrow 17434@itemx catch catch 17435Debug C@t{++} exception handling using these commands. @xref{Set 17436Catchpoints, , Setting Catchpoints}. 17437 17438@cindex inheritance 17439@item ptype @var{typename} 17440Print inheritance relationships as well as other information for type 17441@var{typename}. 17442@xref{Symbols, ,Examining the Symbol Table}. 17443 17444@item info vtbl @var{expression}. 17445The @code{info vtbl} command can be used to display the virtual 17446method tables of the object computed by @var{expression}. This shows 17447one entry per virtual table; there may be multiple virtual tables when 17448multiple inheritance is in use. 17449 17450@cindex C@t{++} demangling 17451@item demangle @var{name} 17452Demangle @var{name}. 17453@xref{Symbols}, for a more complete description of the @code{demangle} command. 17454 17455@cindex C@t{++} symbol display 17456@item set print demangle 17457@itemx show print demangle 17458@itemx set print asm-demangle 17459@itemx show print asm-demangle 17460Control whether C@t{++} symbols display in their source form, both when 17461displaying code as C@t{++} source and when displaying disassemblies. 17462@xref{Print Settings, ,Print Settings}. 17463 17464@item set print object 17465@itemx show print object 17466Choose whether to print derived (actual) or declared types of objects. 17467@xref{Print Settings, ,Print Settings}. 17468 17469@item set print vtbl 17470@itemx show print vtbl 17471Control the format for printing virtual function tables. 17472@xref{Print Settings, ,Print Settings}. 17473(The @code{vtbl} commands do not work on programs compiled with the HP 17474ANSI C@t{++} compiler (@code{aCC}).) 17475 17476@kindex set overload-resolution 17477@cindex overloaded functions, overload resolution 17478@item set overload-resolution on 17479Enable overload resolution for C@t{++} expression evaluation. The default 17480is on. For overloaded functions, @value{GDBN} evaluates the arguments 17481and searches for a function whose signature matches the argument types, 17482using the standard C@t{++} conversion rules (see @ref{C Plus Plus 17483Expressions, ,C@t{++} Expressions}, for details). 17484If it cannot find a match, it emits a message. 17485 17486@item set overload-resolution off 17487Disable overload resolution for C@t{++} expression evaluation. For 17488overloaded functions that are not class member functions, @value{GDBN} 17489chooses the first function of the specified name that it finds in the 17490symbol table, whether or not its arguments are of the correct type. For 17491overloaded functions that are class member functions, @value{GDBN} 17492searches for a function whose signature @emph{exactly} matches the 17493argument types. 17494 17495@kindex show overload-resolution 17496@item show overload-resolution 17497Show the current setting of overload resolution. 17498 17499@item @r{Overloaded symbol names} 17500You can specify a particular definition of an overloaded symbol, using 17501the same notation that is used to declare such symbols in C@t{++}: type 17502@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can 17503also use the @value{GDBN} command-line word completion facilities to list the 17504available choices, or to finish the type list for you. 17505@xref{Completion,, Command Completion}, for details on how to do this. 17506 17507@item @r{Breakpoints in template functions} 17508 17509Similar to how overloaded symbols are handled, @value{GDBN} will ignore 17510template parameter lists when it encounters a symbol which includes a 17511C@t{++} template. This permits setting breakpoints on families of template functions 17512or functions whose parameters include template types. 17513 17514The @kbd{-qualified} flag may be used to override this behavior, causing 17515@value{GDBN} to search for a specific function or type. 17516 17517The @value{GDBN} command-line word completion facility also understands 17518template parameters and may be used to list available choices or finish 17519template parameter lists for you. @xref{Completion,, Command Completion}, for 17520details on how to do this. 17521 17522@item @r{Breakpoints in functions with ABI tags} 17523 17524The GNU C@t{++} compiler introduced the notion of ABI ``tags'', which 17525correspond to changes in the ABI of a type, function, or variable that 17526would not otherwise be reflected in a mangled name. See 17527@url{https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/} 17528for more detail. 17529 17530The ABI tags are visible in C@t{++} demangled names. For example, a 17531function that returns a std::string: 17532 17533@smallexample 17534std::string function(int); 17535@end smallexample 17536 17537@noindent 17538when compiled for the C++11 ABI is marked with the @code{cxx11} ABI 17539tag, and @value{GDBN} displays the symbol like this: 17540 17541@smallexample 17542function[abi:cxx11](int) 17543@end smallexample 17544 17545You can set a breakpoint on such functions simply as if they had no 17546tag. For example: 17547 17548@smallexample 17549(@value{GDBP}) b function(int) 17550Breakpoint 2 at 0x40060d: file main.cc, line 10. 17551(@value{GDBP}) info breakpoints 17552Num Type Disp Enb Address What 175531 breakpoint keep y 0x0040060d in function[abi:cxx11](int) 17554 at main.cc:10 17555@end smallexample 17556 17557On the rare occasion you need to disambiguate between different ABI 17558tags, you can do so by simply including the ABI tag in the function 17559name, like: 17560 17561@smallexample 17562(@value{GDBP}) b ambiguous[abi:other_tag](int) 17563@end smallexample 17564@end table 17565 17566@node Decimal Floating Point 17567@subsubsection Decimal Floating Point format 17568@cindex decimal floating point format 17569 17570@value{GDBN} can examine, set and perform computations with numbers in 17571decimal floating point format, which in the C language correspond to the 17572@code{_Decimal32}, @code{_Decimal64} and @code{_Decimal128} types as 17573specified by the extension to support decimal floating-point arithmetic. 17574 17575There are two encodings in use, depending on the architecture: BID (Binary 17576Integer Decimal) for x86 and x86-64, and DPD (Densely Packed Decimal) for 17577PowerPC and S/390. @value{GDBN} will use the appropriate encoding for the 17578configured target. 17579 17580Because of a limitation in @file{libdecnumber}, the library used by @value{GDBN} 17581to manipulate decimal floating point numbers, it is not possible to convert 17582(using a cast, for example) integers wider than 32-bit to decimal float. 17583 17584In addition, in order to imitate @value{GDBN}'s behaviour with binary floating 17585point computations, error checking in decimal float operations ignores 17586underflow, overflow and divide by zero exceptions. 17587 17588In the PowerPC architecture, @value{GDBN} provides a set of pseudo-registers 17589to inspect @code{_Decimal128} values stored in floating point registers. 17590See @ref{PowerPC,,PowerPC} for more details. 17591 17592@node D 17593@subsection D 17594 17595@cindex D 17596@value{GDBN} can be used to debug programs written in D and compiled with 17597GDC, LDC or DMD compilers. Currently @value{GDBN} supports only one D 17598specific feature --- dynamic arrays. 17599 17600@node Go 17601@subsection Go 17602 17603@cindex Go (programming language) 17604@value{GDBN} can be used to debug programs written in Go and compiled with 17605@file{gccgo} or @file{6g} compilers. 17606 17607Here is a summary of the Go-specific features and restrictions: 17608 17609@table @code 17610@cindex current Go package 17611@item The current Go package 17612The name of the current package does not need to be specified when 17613specifying global variables and functions. 17614 17615For example, given the program: 17616 17617@example 17618package main 17619var myglob = "Shall we?" 17620func main () @{ 17621 // ... 17622@} 17623@end example 17624 17625When stopped inside @code{main} either of these work: 17626 17627@example 17628(@value{GDBP}) p myglob 17629(@value{GDBP}) p main.myglob 17630@end example 17631 17632@cindex builtin Go types 17633@item Builtin Go types 17634The @code{string} type is recognized by @value{GDBN} and is printed 17635as a string. 17636 17637@cindex builtin Go functions 17638@item Builtin Go functions 17639The @value{GDBN} expression parser recognizes the @code{unsafe.Sizeof} 17640function and handles it internally. 17641 17642@cindex restrictions on Go expressions 17643@item Restrictions on Go expressions 17644All Go operators are supported except @code{&^}. 17645The Go @code{_} ``blank identifier'' is not supported. 17646Automatic dereferencing of pointers is not supported. 17647@end table 17648 17649@node Objective-C 17650@subsection Objective-C 17651 17652@cindex Objective-C 17653This section provides information about some commands and command 17654options that are useful for debugging Objective-C code. See also 17655@ref{Symbols, info classes}, and @ref{Symbols, info selectors}, for a 17656few more commands specific to Objective-C support. 17657 17658@menu 17659* Method Names in Commands:: 17660* The Print Command with Objective-C:: 17661@end menu 17662 17663@node Method Names in Commands 17664@subsubsection Method Names in Commands 17665 17666The following commands have been extended to accept Objective-C method 17667names as line specifications: 17668 17669@kindex clear@r{, and Objective-C} 17670@kindex break@r{, and Objective-C} 17671@kindex info line@r{, and Objective-C} 17672@kindex jump@r{, and Objective-C} 17673@kindex list@r{, and Objective-C} 17674@itemize 17675@item @code{clear} 17676@item @code{break} 17677@item @code{info line} 17678@item @code{jump} 17679@item @code{list} 17680@end itemize 17681 17682A fully qualified Objective-C method name is specified as 17683 17684@smallexample 17685-[@var{Class} @var{methodName}] 17686@end smallexample 17687 17688where the minus sign is used to indicate an instance method and a 17689plus sign (not shown) is used to indicate a class method. The class 17690name @var{Class} and method name @var{methodName} are enclosed in 17691brackets, similar to the way messages are specified in Objective-C 17692source code. For example, to set a breakpoint at the @code{create} 17693instance method of class @code{Fruit} in the program currently being 17694debugged, enter: 17695 17696@smallexample 17697break -[Fruit create] 17698@end smallexample 17699 17700To list ten program lines around the @code{initialize} class method, 17701enter: 17702 17703@smallexample 17704list +[NSText initialize] 17705@end smallexample 17706 17707In the current version of @value{GDBN}, the plus or minus sign is 17708required. In future versions of @value{GDBN}, the plus or minus 17709sign will be optional, but you can use it to narrow the search. It 17710is also possible to specify just a method name: 17711 17712@smallexample 17713break create 17714@end smallexample 17715 17716You must specify the complete method name, including any colons. If 17717your program's source files contain more than one @code{create} method, 17718you'll be presented with a numbered list of classes that implement that 17719method. Indicate your choice by number, or type @samp{0} to exit if 17720none apply. 17721 17722As another example, to clear a breakpoint established at the 17723@code{makeKeyAndOrderFront:} method of the @code{NSWindow} class, enter: 17724 17725@smallexample 17726clear -[NSWindow makeKeyAndOrderFront:] 17727@end smallexample 17728 17729@node The Print Command with Objective-C 17730@subsubsection The Print Command With Objective-C 17731@cindex Objective-C, print objects 17732@kindex print-object 17733@kindex po @r{(@code{print-object})} 17734 17735The print command has also been extended to accept methods. For example: 17736 17737@smallexample 17738print -[@var{object} hash] 17739@end smallexample 17740 17741@cindex print an Objective-C object description 17742@cindex @code{_NSPrintForDebugger}, and printing Objective-C objects 17743@noindent 17744will tell @value{GDBN} to send the @code{hash} message to @var{object} 17745and print the result. Also, an additional command has been added, 17746@code{print-object} or @code{po} for short, which is meant to print 17747the description of an object. However, this command may only work 17748with certain Objective-C libraries that have a particular hook 17749function, @code{_NSPrintForDebugger}, defined. 17750 17751@node OpenCL C 17752@subsection OpenCL C 17753 17754@cindex OpenCL C 17755This section provides information about @value{GDBN}s OpenCL C support. 17756 17757@menu 17758* OpenCL C Datatypes:: 17759* OpenCL C Expressions:: 17760* OpenCL C Operators:: 17761@end menu 17762 17763@node OpenCL C Datatypes 17764@subsubsection OpenCL C Datatypes 17765 17766@cindex OpenCL C Datatypes 17767@value{GDBN} supports the builtin scalar and vector datatypes specified 17768by OpenCL 1.1. In addition the half- and double-precision floating point 17769data types of the @code{cl_khr_fp16} and @code{cl_khr_fp64} OpenCL 17770extensions are also known to @value{GDBN}. 17771 17772@node OpenCL C Expressions 17773@subsubsection OpenCL C Expressions 17774 17775@cindex OpenCL C Expressions 17776@value{GDBN} supports accesses to vector components including the access as 17777lvalue where possible. Since OpenCL C is based on C99 most C expressions 17778supported by @value{GDBN} can be used as well. 17779 17780@node OpenCL C Operators 17781@subsubsection OpenCL C Operators 17782 17783@cindex OpenCL C Operators 17784@value{GDBN} supports the operators specified by OpenCL 1.1 for scalar and 17785vector data types. 17786 17787@node Fortran 17788@subsection Fortran 17789@cindex Fortran-specific support in @value{GDBN} 17790 17791@value{GDBN} can be used to debug programs written in Fortran. Note, that not 17792all Fortran language features are available yet. 17793 17794@cindex trailing underscore, in Fortran symbols 17795Some Fortran compilers (@sc{gnu} Fortran 77 and Fortran 95 compilers 17796among them) append an underscore to the names of variables and 17797functions. When you debug programs compiled by those compilers, you 17798will need to refer to variables and functions with a trailing 17799underscore. 17800 17801@cindex Fortran Defaults 17802Fortran symbols are usually case-insensitive, so @value{GDBN} by 17803default uses case-insensitive matching for Fortran symbols. You can 17804change that with the @samp{set case-insensitive} command, see 17805@ref{Symbols}, for the details. 17806 17807@menu 17808* Fortran Types:: Fortran builtin types 17809* Fortran Operators:: Fortran operators and expressions 17810* Fortran Intrinsics:: Fortran intrinsic functions 17811* Special Fortran Commands:: Special @value{GDBN} commands for Fortran 17812@end menu 17813 17814@node Fortran Types 17815@subsubsection Fortran Types 17816 17817@cindex Fortran Types 17818 17819In Fortran the primitive data-types have an associated @code{KIND} type 17820parameter, written as @samp{@var{type}*@var{kindparam}}, 17821@samp{@var{type}*@var{kindparam}}, or in the @value{GDBN}-only dialect 17822@samp{@var{type}_@var{kindparam}}. A concrete example would be 17823@samp{@code{Real*4}}, @samp{@code{Real(kind=4)}}, and @samp{@code{Real_4}}. 17824The kind of a type can be retrieved by using the intrinsic function 17825@code{KIND}, see @ref{Fortran Intrinsics}. 17826 17827Generally, the actual implementation of the @code{KIND} type parameter is 17828compiler specific. In @value{GDBN} the kind parameter is implemented in 17829accordance with its use in the @sc{gnu} @command{gfortran} compiler. Here, the 17830kind parameter for a given @var{type} specifies its size in memory --- a 17831Fortran @code{Integer*4} or @code{Integer(kind=4)} would be an integer type 17832occupying 4 bytes of memory. An exception to this rule is the @code{Complex} 17833type for which the kind of the type does not specify its entire size, but 17834the size of each of the two @code{Real}'s it is composed of. A 17835@code{Complex*4} would thus consist of two @code{Real*4}s and occupy 8 bytes 17836of memory. 17837 17838For every type there is also a default kind associated with it, e.g.@ 17839@code{Integer} in @value{GDBN} will internally be an @code{Integer*4} (see the 17840table below for default types). The default types are the same as in @sc{gnu} 17841compilers but note, that the @sc{gnu} default types can actually be changed by 17842compiler flags such as @option{-fdefault-integer-8} and 17843@option{-fdefault-real-8}. 17844 17845Not every kind parameter is valid for every type and in @value{GDBN} the 17846following type kinds are available. 17847 17848@table @code 17849@item Integer 17850@code{Integer*1}, @code{Integer*2}, @code{Integer*4}, @code{Integer*8}, and 17851@code{Integer} = @code{Integer*4}. 17852 17853@item Logical 17854@code{Logical*1}, @code{Logical*2}, @code{Logical*4}, @code{Logical*8}, and 17855@code{Logical} = @code{Logical*4}. 17856 17857@item Real 17858@code{Real*4}, @code{Real*8}, @code{Real*16}, and @code{Real} = @code{Real*4}. 17859 17860@item Complex 17861@code{Complex*4}, @code{Complex*8}, @code{Complex*16}, and @code{Complex} = 17862@code{Complex*4}. 17863 17864@end table 17865 17866@node Fortran Operators 17867@subsubsection Fortran Operators and Expressions 17868 17869@cindex Fortran operators and expressions 17870 17871Operators must be defined on values of specific types. For instance, 17872@code{+} is defined on numbers, but not on characters or other non- 17873arithmetic types. Operators are often defined on groups of types. 17874 17875@table @code 17876@item ** 17877The exponentiation operator. It raises the first operand to the power 17878of the second one. 17879 17880@item : 17881The range operator. Normally used in the form of array(low:high) to 17882represent a section of array. 17883 17884@item % 17885The access component operator. Normally used to access elements in derived 17886types. Also suitable for unions. As unions aren't part of regular Fortran, 17887this can only happen when accessing a register that uses a gdbarch-defined 17888union type. 17889@item :: 17890The scope operator. Normally used to access variables in modules or 17891to set breakpoints on subroutines nested in modules or in other 17892subroutines (internal subroutines). 17893@end table 17894 17895@node Fortran Intrinsics 17896@subsubsection Fortran Intrinsics 17897 17898@cindex Fortran Intrinsics 17899 17900Fortran provides a large set of intrinsic procedures. @value{GDBN} implements 17901an incomplete subset of those procedures and their overloads. Some of these 17902procedures take an optional @code{KIND} parameter, see @ref{Fortran Types}. 17903 17904@table @code 17905@item ABS(@var{a}) 17906Computes the absolute value of its argument @var{a}. Currently not supported 17907for @code{Complex} arguments. 17908 17909@item ALLOCATE(@var{array}) 17910Returns whether @var{array} is allocated or not. 17911 17912@item ASSOCIATED(@var{pointer} [, @var{target}]) 17913Returns the association status of the pointer @var{pointer} or, if @var{target} 17914is present, whether @var{pointer} is associated with the target @var{target}. 17915 17916@item CEILING(@var{a} [, @var{kind}]) 17917Computes the least integer greater than or equal to @var{a}. The optional 17918parameter @var{kind} specifies the kind of the return type 17919@code{Integer(@var{kind})}. 17920 17921@item CMPLX(@var{x} [, @var{y} [, @var{kind}]]) 17922Returns a complex number where @var{x} is converted to the real component. If 17923@var{y} is present it is converted to the imaginary component. If @var{y} is 17924not present then the imaginary component is set to @code{0.0} except if @var{x} 17925itself is of @code{Complex} type. The optional parameter @var{kind} specifies 17926the kind of the return type @code{Complex(@var{kind})}. 17927 17928@item FLOOR(@var{a} [, @var{kind}]) 17929Computes the greatest integer less than or equal to @var{a}. The optional 17930parameter @var{kind} specifies the kind of the return type 17931@code{Integer(@var{kind})}. 17932 17933@item KIND(@var{a}) 17934Returns the kind value of the argument @var{a}, see @ref{Fortran Types}. 17935 17936@item LBOUND(@var{array} [, @var{dim} [, @var{kind}]]) 17937Returns the lower bounds of an @var{array}, or a single lower bound along the 17938@var{dim} dimension if present. The optional parameter @var{kind} specifies 17939the kind of the return type @code{Integer(@var{kind})}. 17940 17941@item LOC(@var{x}) 17942Returns the address of @var{x} as an @code{Integer}. 17943 17944@item MOD(@var{a}, @var{p}) 17945Computes the remainder of the division of @var{a} by @var{p}. 17946 17947@item MODULO(@var{a}, @var{p}) 17948Computes the @var{a} modulo @var{p}. 17949 17950@item RANK(@var{a}) 17951Returns the rank of a scalar or array (scalars have rank @code{0}). 17952 17953@item SHAPE(@var{a}) 17954Returns the shape of a scalar or array (scalars have shape @samp{()}). 17955 17956@item SIZE(@var{array}[, @var{dim} [, @var{kind}]]) 17957Returns the extent of @var{array} along a specified dimension @var{dim}, or the 17958total number of elements in @var{array} if @var{dim} is absent. The optional 17959parameter @var{kind} specifies the kind of the return type 17960@code{Integer(@var{kind})}. 17961 17962@item UBOUND(@var{array} [, @var{dim} [, @var{kind}]]) 17963Returns the upper bounds of an @var{array}, or a single upper bound along the 17964@var{dim} dimension if present. The optional parameter @var{kind} specifies 17965the kind of the return type @code{Integer(@var{kind})}. 17966 17967@end table 17968 17969@node Special Fortran Commands 17970@subsubsection Special Fortran Commands 17971 17972@cindex Special Fortran commands 17973 17974@value{GDBN} has some commands to support Fortran-specific features, 17975such as displaying common blocks. 17976 17977@table @code 17978@cindex @code{COMMON} blocks, Fortran 17979@kindex info common 17980@item info common @r{[}@var{common-name}@r{]} 17981This command prints the values contained in the Fortran @code{COMMON} 17982block whose name is @var{common-name}. With no argument, the names of 17983all @code{COMMON} blocks visible at the current program location are 17984printed. 17985@cindex arrays slices (Fortran) 17986@kindex set fortran repack-array-slices 17987@kindex show fortran repack-array-slices 17988@item set fortran repack-array-slices [on|off] 17989@item show fortran repack-array-slices 17990When taking a slice from an array, a Fortran compiler can choose to 17991either produce an array descriptor that describes the slice in place, 17992or it may repack the slice, copying the elements of the slice into a 17993new region of memory. 17994 17995When this setting is on, then @value{GDBN} will also repack array 17996slices in some situations. When this setting is off, then 17997@value{GDBN} will create array descriptors for slices that reference 17998the original data in place. 17999 18000@value{GDBN} will never repack an array slice if the data for the 18001slice is contiguous within the original array. 18002 18003@value{GDBN} will always repack string slices if the data for the 18004slice is non-contiguous within the original string as @value{GDBN} 18005does not support printing non-contiguous strings. 18006 18007The default for this setting is @code{off}. 18008@end table 18009 18010@node Pascal 18011@subsection Pascal 18012 18013@cindex Pascal support in @value{GDBN}, limitations 18014Debugging Pascal programs which use sets, subranges, file variables, or 18015nested functions does not currently work. @value{GDBN} does not support 18016entering expressions, printing values, or similar features using Pascal 18017syntax. 18018 18019The Pascal-specific command @code{set print pascal_static-members} 18020controls whether static members of Pascal objects are displayed. 18021@xref{Print Settings, pascal_static-members}. 18022 18023@node Rust 18024@subsection Rust 18025 18026@value{GDBN} supports the @url{https://www.rust-lang.org/, Rust 18027Programming Language}. Type- and value-printing, and expression 18028parsing, are reasonably complete. However, there are a few 18029peculiarities and holes to be aware of. 18030 18031@itemize @bullet 18032@item 18033Linespecs (@pxref{Location Specifications}) are never relative to the 18034current crate. Instead, they act as if there were a global namespace 18035of crates, somewhat similar to the way @code{extern crate} behaves. 18036 18037That is, if @value{GDBN} is stopped at a breakpoint in a function in 18038crate @samp{A}, module @samp{B}, then @code{break B::f} will attempt 18039to set a breakpoint in a function named @samp{f} in a crate named 18040@samp{B}. 18041 18042As a consequence of this approach, linespecs also cannot refer to 18043items using @samp{self::} or @samp{super::}. 18044 18045@item 18046Because @value{GDBN} implements Rust name-lookup semantics in 18047expressions, it will sometimes prepend the current crate to a name. 18048For example, if @value{GDBN} is stopped at a breakpoint in the crate 18049@samp{K}, then @code{print ::x::y} will try to find the symbol 18050@samp{K::x::y}. 18051 18052However, since it is useful to be able to refer to other crates when 18053debugging, @value{GDBN} provides the @code{extern} extension to 18054circumvent this. To use the extension, just put @code{extern} before 18055a path expression to refer to the otherwise unavailable ``global'' 18056scope. 18057 18058In the above example, if you wanted to refer to the symbol @samp{y} in 18059the crate @samp{x}, you would use @code{print extern x::y}. 18060 18061@item 18062The Rust expression evaluator does not support ``statement-like'' 18063expressions such as @code{if} or @code{match}, or lambda expressions. 18064 18065@item 18066Tuple expressions are not implemented. 18067 18068@item 18069The Rust expression evaluator does not currently implement the 18070@code{Drop} trait. Objects that may be created by the evaluator will 18071never be destroyed. 18072 18073@item 18074@value{GDBN} does not implement type inference for generics. In order 18075to call generic functions or otherwise refer to generic items, you 18076will have to specify the type parameters manually. 18077 18078@item 18079@value{GDBN} currently uses the C@t{++} demangler for Rust. In most 18080cases this does not cause any problems. However, in an expression 18081context, completing a generic function name will give syntactically 18082invalid results. This happens because Rust requires the @samp{::} 18083operator between the function name and its generic arguments. For 18084example, @value{GDBN} might provide a completion like 18085@code{crate::f<u32>}, where the parser would require 18086@code{crate::f::<u32>}. 18087 18088@item 18089As of this writing, the Rust compiler (version 1.8) has a few holes in 18090the debugging information it generates. These holes prevent certain 18091features from being implemented by @value{GDBN}: 18092@itemize @bullet 18093 18094@item 18095Method calls cannot be made via traits. 18096 18097@item 18098Operator overloading is not implemented. 18099 18100@item 18101When debugging in a monomorphized function, you cannot use the generic 18102type names. 18103 18104@item 18105The type @code{Self} is not available. 18106 18107@item 18108@code{use} statements are not available, so some names may not be 18109available in the crate. 18110@end itemize 18111@end itemize 18112 18113@node Modula-2 18114@subsection Modula-2 18115 18116@cindex Modula-2, @value{GDBN} support 18117 18118The extensions made to @value{GDBN} to support Modula-2 only support 18119output from the @sc{gnu} Modula-2 compiler (which is currently being 18120developed). Other Modula-2 compilers are not currently supported, and 18121attempting to debug executables produced by them is most likely 18122to give an error as @value{GDBN} reads in the executable's symbol 18123table. 18124 18125@cindex expressions in Modula-2 18126@menu 18127* M2 Operators:: Built-in operators 18128* Built-In Func/Proc:: Built-in functions and procedures 18129* M2 Constants:: Modula-2 constants 18130* M2 Types:: Modula-2 types 18131* M2 Defaults:: Default settings for Modula-2 18132* Deviations:: Deviations from standard Modula-2 18133* M2 Checks:: Modula-2 type and range checks 18134* M2 Scope:: The scope operators @code{::} and @code{.} 18135* GDB/M2:: @value{GDBN} and Modula-2 18136@end menu 18137 18138@node M2 Operators 18139@subsubsection Operators 18140@cindex Modula-2 operators 18141 18142Operators must be defined on values of specific types. For instance, 18143@code{+} is defined on numbers, but not on structures. Operators are 18144often defined on groups of types. For the purposes of Modula-2, the 18145following definitions hold: 18146 18147@itemize @bullet 18148 18149@item 18150@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and 18151their subranges. 18152 18153@item 18154@emph{Character types} consist of @code{CHAR} and its subranges. 18155 18156@item 18157@emph{Floating-point types} consist of @code{REAL}. 18158 18159@item 18160@emph{Pointer types} consist of anything declared as @code{POINTER TO 18161@var{type}}. 18162 18163@item 18164@emph{Scalar types} consist of all of the above. 18165 18166@item 18167@emph{Set types} consist of @code{SET} and @code{BITSET} types. 18168 18169@item 18170@emph{Boolean types} consist of @code{BOOLEAN}. 18171@end itemize 18172 18173@noindent 18174The following operators are supported, and appear in order of 18175increasing precedence: 18176 18177@table @code 18178@item , 18179Function argument or array index separator. 18180 18181@item := 18182Assignment. The value of @var{var} @code{:=} @var{value} is 18183@var{value}. 18184 18185@item <@r{, }> 18186Less than, greater than on integral, floating-point, or enumerated 18187types. 18188 18189@item <=@r{, }>= 18190Less than or equal to, greater than or equal to 18191on integral, floating-point and enumerated types, or set inclusion on 18192set types. Same precedence as @code{<}. 18193 18194@item =@r{, }<>@r{, }# 18195Equality and two ways of expressing inequality, valid on scalar types. 18196Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is 18197available for inequality, since @code{#} conflicts with the script 18198comment character. 18199 18200@item IN 18201Set membership. Defined on set types and the types of their members. 18202Same precedence as @code{<}. 18203 18204@item OR 18205Boolean disjunction. Defined on boolean types. 18206 18207@item AND@r{, }& 18208Boolean conjunction. Defined on boolean types. 18209 18210@item @@ 18211The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}). 18212 18213@item +@r{, }- 18214Addition and subtraction on integral and floating-point types, or union 18215and difference on set types. 18216 18217@item * 18218Multiplication on integral and floating-point types, or set intersection 18219on set types. 18220 18221@item / 18222Division on floating-point types, or symmetric set difference on set 18223types. Same precedence as @code{*}. 18224 18225@item DIV@r{, }MOD 18226Integer division and remainder. Defined on integral types. Same 18227precedence as @code{*}. 18228 18229@item - 18230Negative. Defined on @code{INTEGER} and @code{REAL} data. 18231 18232@item ^ 18233Pointer dereferencing. Defined on pointer types. 18234 18235@item NOT 18236Boolean negation. Defined on boolean types. Same precedence as 18237@code{^}. 18238 18239@item . 18240@code{RECORD} field selector. Defined on @code{RECORD} data. Same 18241precedence as @code{^}. 18242 18243@item [] 18244Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}. 18245 18246@item () 18247Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence 18248as @code{^}. 18249 18250@item ::@r{, }. 18251@value{GDBN} and Modula-2 scope operators. 18252@end table 18253 18254@quotation 18255@emph{Warning:} Set expressions and their operations are not yet supported, so @value{GDBN} 18256treats the use of the operator @code{IN}, or the use of operators 18257@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#}, 18258@code{<=}, and @code{>=} on sets as an error. 18259@end quotation 18260 18261 18262@node Built-In Func/Proc 18263@subsubsection Built-in Functions and Procedures 18264@cindex Modula-2 built-ins 18265 18266Modula-2 also makes available several built-in procedures and functions. 18267In describing these, the following metavariables are used: 18268 18269@table @var 18270 18271@item a 18272represents an @code{ARRAY} variable. 18273 18274@item c 18275represents a @code{CHAR} constant or variable. 18276 18277@item i 18278represents a variable or constant of integral type. 18279 18280@item m 18281represents an identifier that belongs to a set. Generally used in the 18282same function with the metavariable @var{s}. The type of @var{s} should 18283be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}). 18284 18285@item n 18286represents a variable or constant of integral or floating-point type. 18287 18288@item r 18289represents a variable or constant of floating-point type. 18290 18291@item t 18292represents a type. 18293 18294@item v 18295represents a variable. 18296 18297@item x 18298represents a variable or constant of one of many types. See the 18299explanation of the function for details. 18300@end table 18301 18302All Modula-2 built-in procedures also return a result, described below. 18303 18304@table @code 18305@item ABS(@var{n}) 18306Returns the absolute value of @var{n}. 18307 18308@item CAP(@var{c}) 18309If @var{c} is a lower case letter, it returns its upper case 18310equivalent, otherwise it returns its argument. 18311 18312@item CHR(@var{i}) 18313Returns the character whose ordinal value is @var{i}. 18314 18315@item DEC(@var{v}) 18316Decrements the value in the variable @var{v} by one. Returns the new value. 18317 18318@item DEC(@var{v},@var{i}) 18319Decrements the value in the variable @var{v} by @var{i}. Returns the 18320new value. 18321 18322@item EXCL(@var{m},@var{s}) 18323Removes the element @var{m} from the set @var{s}. Returns the new 18324set. 18325 18326@item FLOAT(@var{i}) 18327Returns the floating point equivalent of the integer @var{i}. 18328 18329@item HIGH(@var{a}) 18330Returns the index of the last member of @var{a}. 18331 18332@item INC(@var{v}) 18333Increments the value in the variable @var{v} by one. Returns the new value. 18334 18335@item INC(@var{v},@var{i}) 18336Increments the value in the variable @var{v} by @var{i}. Returns the 18337new value. 18338 18339@item INCL(@var{m},@var{s}) 18340Adds the element @var{m} to the set @var{s} if it is not already 18341there. Returns the new set. 18342 18343@item MAX(@var{t}) 18344Returns the maximum value of the type @var{t}. 18345 18346@item MIN(@var{t}) 18347Returns the minimum value of the type @var{t}. 18348 18349@item ODD(@var{i}) 18350Returns boolean TRUE if @var{i} is an odd number. 18351 18352@item ORD(@var{x}) 18353Returns the ordinal value of its argument. For example, the ordinal 18354value of a character is its @sc{ascii} value (on machines supporting 18355the @sc{ascii} character set). The argument @var{x} must be of an 18356ordered type, which include integral, character and enumerated types. 18357 18358@item SIZE(@var{x}) 18359Returns the size of its argument. The argument @var{x} can be a 18360variable or a type. 18361 18362@item TRUNC(@var{r}) 18363Returns the integral part of @var{r}. 18364 18365@item TSIZE(@var{x}) 18366Returns the size of its argument. The argument @var{x} can be a 18367variable or a type. 18368 18369@item VAL(@var{t},@var{i}) 18370Returns the member of the type @var{t} whose ordinal value is @var{i}. 18371@end table 18372 18373@quotation 18374@emph{Warning:} Sets and their operations are not yet supported, so 18375@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as 18376an error. 18377@end quotation 18378 18379@cindex Modula-2 constants 18380@node M2 Constants 18381@subsubsection Constants 18382 18383@value{GDBN} allows you to express the constants of Modula-2 in the following 18384ways: 18385 18386@itemize @bullet 18387 18388@item 18389Integer constants are simply a sequence of digits. When used in an 18390expression, a constant is interpreted to be type-compatible with the 18391rest of the expression. Hexadecimal integers are specified by a 18392trailing @samp{H}, and octal integers by a trailing @samp{B}. 18393 18394@item 18395Floating point constants appear as a sequence of digits, followed by a 18396decimal point and another sequence of digits. An optional exponent can 18397then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where 18398@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the 18399digits of the floating point constant must be valid decimal (base 10) 18400digits. 18401 18402@item 18403Character constants consist of a single character enclosed by a pair of 18404like quotes, either single (@code{'}) or double (@code{"}). They may 18405also be expressed by their ordinal value (their @sc{ascii} value, usually) 18406followed by a @samp{C}. 18407 18408@item 18409String constants consist of a sequence of characters enclosed by a 18410pair of like quotes, either single (@code{'}) or double (@code{"}). 18411Escape sequences in the style of C are also allowed. @xref{C 18412Constants, ,C and C@t{++} Constants}, for a brief explanation of escape 18413sequences. 18414 18415@item 18416Enumerated constants consist of an enumerated identifier. 18417 18418@item 18419Boolean constants consist of the identifiers @code{TRUE} and 18420@code{FALSE}. 18421 18422@item 18423Pointer constants consist of integral values only. 18424 18425@item 18426Set constants are not yet supported. 18427@end itemize 18428 18429@node M2 Types 18430@subsubsection Modula-2 Types 18431@cindex Modula-2 types 18432 18433Currently @value{GDBN} can print the following data types in Modula-2 18434syntax: array types, record types, set types, pointer types, procedure 18435types, enumerated types, subrange types and base types. You can also 18436print the contents of variables declared using these type. 18437This section gives a number of simple source code examples together with 18438sample @value{GDBN} sessions. 18439 18440The first example contains the following section of code: 18441 18442@smallexample 18443VAR 18444 s: SET OF CHAR ; 18445 r: [20..40] ; 18446@end smallexample 18447 18448@noindent 18449and you can request @value{GDBN} to interrogate the type and value of 18450@code{r} and @code{s}. 18451 18452@smallexample 18453(@value{GDBP}) print s 18454@{'A'..'C', 'Z'@} 18455(@value{GDBP}) ptype s 18456SET OF CHAR 18457(@value{GDBP}) print r 1845821 18459(@value{GDBP}) ptype r 18460[20..40] 18461@end smallexample 18462 18463@noindent 18464Likewise if your source code declares @code{s} as: 18465 18466@smallexample 18467VAR 18468 s: SET ['A'..'Z'] ; 18469@end smallexample 18470 18471@noindent 18472then you may query the type of @code{s} by: 18473 18474@smallexample 18475(@value{GDBP}) ptype s 18476type = SET ['A'..'Z'] 18477@end smallexample 18478 18479@noindent 18480Note that at present you cannot interactively manipulate set 18481expressions using the debugger. 18482 18483The following example shows how you might declare an array in Modula-2 18484and how you can interact with @value{GDBN} to print its type and contents: 18485 18486@smallexample 18487VAR 18488 s: ARRAY [-10..10] OF CHAR ; 18489@end smallexample 18490 18491@smallexample 18492(@value{GDBP}) ptype s 18493ARRAY [-10..10] OF CHAR 18494@end smallexample 18495 18496Note that the array handling is not yet complete and although the type 18497is printed correctly, expression handling still assumes that all 18498arrays have a lower bound of zero and not @code{-10} as in the example 18499above. 18500 18501Here are some more type related Modula-2 examples: 18502 18503@smallexample 18504TYPE 18505 colour = (blue, red, yellow, green) ; 18506 t = [blue..yellow] ; 18507VAR 18508 s: t ; 18509BEGIN 18510 s := blue ; 18511@end smallexample 18512 18513@noindent 18514The @value{GDBN} interaction shows how you can query the data type 18515and value of a variable. 18516 18517@smallexample 18518(@value{GDBP}) print s 18519$1 = blue 18520(@value{GDBP}) ptype t 18521type = [blue..yellow] 18522@end smallexample 18523 18524@noindent 18525In this example a Modula-2 array is declared and its contents 18526displayed. Observe that the contents are written in the same way as 18527their @code{C} counterparts. 18528 18529@smallexample 18530VAR 18531 s: ARRAY [1..5] OF CARDINAL ; 18532BEGIN 18533 s[1] := 1 ; 18534@end smallexample 18535 18536@smallexample 18537(@value{GDBP}) print s 18538$1 = @{1, 0, 0, 0, 0@} 18539(@value{GDBP}) ptype s 18540type = ARRAY [1..5] OF CARDINAL 18541@end smallexample 18542 18543The Modula-2 language interface to @value{GDBN} also understands 18544pointer types as shown in this example: 18545 18546@smallexample 18547VAR 18548 s: POINTER TO ARRAY [1..5] OF CARDINAL ; 18549BEGIN 18550 NEW(s) ; 18551 s^[1] := 1 ; 18552@end smallexample 18553 18554@noindent 18555and you can request that @value{GDBN} describes the type of @code{s}. 18556 18557@smallexample 18558(@value{GDBP}) ptype s 18559type = POINTER TO ARRAY [1..5] OF CARDINAL 18560@end smallexample 18561 18562@value{GDBN} handles compound types as we can see in this example. 18563Here we combine array types, record types, pointer types and subrange 18564types: 18565 18566@smallexample 18567TYPE 18568 foo = RECORD 18569 f1: CARDINAL ; 18570 f2: CHAR ; 18571 f3: myarray ; 18572 END ; 18573 18574 myarray = ARRAY myrange OF CARDINAL ; 18575 myrange = [-2..2] ; 18576VAR 18577 s: POINTER TO ARRAY myrange OF foo ; 18578@end smallexample 18579 18580@noindent 18581and you can ask @value{GDBN} to describe the type of @code{s} as shown 18582below. 18583 18584@smallexample 18585(@value{GDBP}) ptype s 18586type = POINTER TO ARRAY [-2..2] OF foo = RECORD 18587 f1 : CARDINAL; 18588 f2 : CHAR; 18589 f3 : ARRAY [-2..2] OF CARDINAL; 18590END 18591@end smallexample 18592 18593@node M2 Defaults 18594@subsubsection Modula-2 Defaults 18595@cindex Modula-2 defaults 18596 18597If type and range checking are set automatically by @value{GDBN}, they 18598both default to @code{on} whenever the working language changes to 18599Modula-2. This happens regardless of whether you or @value{GDBN} 18600selected the working language. 18601 18602If you allow @value{GDBN} to set the language automatically, then entering 18603code compiled from a file whose name ends with @file{.mod} sets the 18604working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} 18605Infer the Source Language}, for further details. 18606 18607@node Deviations 18608@subsubsection Deviations from Standard Modula-2 18609@cindex Modula-2, deviations from 18610 18611A few changes have been made to make Modula-2 programs easier to debug. 18612This is done primarily via loosening its type strictness: 18613 18614@itemize @bullet 18615@item 18616Unlike in standard Modula-2, pointer constants can be formed by 18617integers. This allows you to modify pointer variables during 18618debugging. (In standard Modula-2, the actual address contained in a 18619pointer variable is hidden from you; it can only be modified 18620through direct assignment to another pointer variable or expression that 18621returned a pointer.) 18622 18623@item 18624C escape sequences can be used in strings and characters to represent 18625non-printable characters. @value{GDBN} prints out strings with these 18626escape sequences embedded. Single non-printable characters are 18627printed using the @samp{CHR(@var{nnn})} format. 18628 18629@item 18630The assignment operator (@code{:=}) returns the value of its right-hand 18631argument. 18632 18633@item 18634All built-in procedures both modify @emph{and} return their argument. 18635@end itemize 18636 18637@node M2 Checks 18638@subsubsection Modula-2 Type and Range Checks 18639@cindex Modula-2 checks 18640 18641@quotation 18642@emph{Warning:} in this release, @value{GDBN} does not yet perform type or 18643range checking. 18644@end quotation 18645@c FIXME remove warning when type/range checks added 18646 18647@value{GDBN} considers two Modula-2 variables type equivalent if: 18648 18649@itemize @bullet 18650@item 18651They are of types that have been declared equivalent via a @code{TYPE 18652@var{t1} = @var{t2}} statement 18653 18654@item 18655They have been declared on the same line. (Note: This is true of the 18656@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.) 18657@end itemize 18658 18659As long as type checking is enabled, any attempt to combine variables 18660whose types are not equivalent is an error. 18661 18662Range checking is done on all mathematical operations, assignment, array 18663index bounds, and all built-in functions and procedures. 18664 18665@node M2 Scope 18666@subsubsection The Scope Operators @code{::} and @code{.} 18667@cindex scope 18668@cindex @code{.}, Modula-2 scope operator 18669@cindex colon, doubled as scope operator 18670@ifinfo 18671@vindex colon-colon@r{, in Modula-2} 18672@c Info cannot handle :: but TeX can. 18673@end ifinfo 18674@ifnotinfo 18675@vindex ::@r{, in Modula-2} 18676@end ifnotinfo 18677 18678There are a few subtle differences between the Modula-2 scope operator 18679(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have 18680similar syntax: 18681 18682@smallexample 18683 18684@var{module} . @var{id} 18685@var{scope} :: @var{id} 18686@end smallexample 18687 18688@noindent 18689where @var{scope} is the name of a module or a procedure, 18690@var{module} the name of a module, and @var{id} is any declared 18691identifier within your program, except another module. 18692 18693Using the @code{::} operator makes @value{GDBN} search the scope 18694specified by @var{scope} for the identifier @var{id}. If it is not 18695found in the specified scope, then @value{GDBN} searches all scopes 18696enclosing the one specified by @var{scope}. 18697 18698Using the @code{.} operator makes @value{GDBN} search the current scope for 18699the identifier specified by @var{id} that was imported from the 18700definition module specified by @var{module}. With this operator, it is 18701an error if the identifier @var{id} was not imported from definition 18702module @var{module}, or if @var{id} is not an identifier in 18703@var{module}. 18704 18705@node GDB/M2 18706@subsubsection @value{GDBN} and Modula-2 18707 18708Some @value{GDBN} commands have little use when debugging Modula-2 programs. 18709Five subcommands of @code{set print} and @code{show print} apply 18710specifically to C and C@t{++}: @samp{vtbl}, @samp{demangle}, 18711@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four 18712apply to C@t{++}, and the last to the C @code{union} type, which has no direct 18713analogue in Modula-2. 18714 18715The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available 18716with any language, is not useful with Modula-2. Its 18717intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be 18718created in Modula-2 as they can in C or C@t{++}. However, because an 18719address can be specified by an integral constant, the construct 18720@samp{@{@var{type}@}@var{adrexp}} is still useful. 18721 18722@cindex @code{#} in Modula-2 18723In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is 18724interpreted as the beginning of a comment. Use @code{<>} instead. 18725 18726@node Ada 18727@subsection Ada 18728@cindex Ada 18729 18730The extensions made to @value{GDBN} for Ada only support 18731output from the @sc{gnu} Ada (GNAT) compiler. 18732Other Ada compilers are not currently supported, and 18733attempting to debug executables produced by them is most likely 18734to be difficult. 18735 18736 18737@cindex expressions in Ada 18738@menu 18739* Ada Mode Intro:: General remarks on the Ada syntax 18740 and semantics supported by Ada mode 18741 in @value{GDBN}. 18742* Omissions from Ada:: Restrictions on the Ada expression syntax. 18743* Additions to Ada:: Extensions of the Ada expression syntax. 18744* Overloading support for Ada:: Support for expressions involving overloaded 18745 subprograms. 18746* Stopping Before Main Program:: Debugging the program during elaboration. 18747* Ada Exceptions:: Ada Exceptions 18748* Ada Tasks:: Listing and setting breakpoints in tasks. 18749* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files 18750* Ravenscar Profile:: Tasking Support when using the Ravenscar 18751 Profile 18752* Ada Source Character Set:: Character set of Ada source files. 18753* Ada Glitches:: Known peculiarities of Ada mode. 18754@end menu 18755 18756@node Ada Mode Intro 18757@subsubsection Introduction 18758@cindex Ada mode, general 18759 18760The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression 18761syntax, with some extensions. 18762The philosophy behind the design of this subset is 18763 18764@itemize @bullet 18765@item 18766That @value{GDBN} should provide basic literals and access to operations for 18767arithmetic, dereferencing, field selection, indexing, and subprogram calls, 18768leaving more sophisticated computations to subprograms written into the 18769program (which therefore may be called from @value{GDBN}). 18770 18771@item 18772That type safety and strict adherence to Ada language restrictions 18773are not particularly important to the @value{GDBN} user. 18774 18775@item 18776That brevity is important to the @value{GDBN} user. 18777@end itemize 18778 18779Thus, for brevity, the debugger acts as if all names declared in 18780user-written packages are directly visible, even if they are not visible 18781according to Ada rules, thus making it unnecessary to fully qualify most 18782names with their packages, regardless of context. Where this causes 18783ambiguity, @value{GDBN} asks the user's intent. 18784 18785The debugger will start in Ada mode if it detects an Ada main program. 18786As for other languages, it will enter Ada mode when stopped in a program that 18787was translated from an Ada source file. 18788 18789While in Ada mode, you may use `@t{--}' for comments. This is useful 18790mostly for documenting command files. The standard @value{GDBN} comment 18791(@samp{#}) still works at the beginning of a line in Ada mode, but not in the 18792middle (to allow based literals). 18793 18794@node Omissions from Ada 18795@subsubsection Omissions from Ada 18796@cindex Ada, omissions from 18797 18798Here are the notable omissions from the subset: 18799 18800@itemize @bullet 18801@item 18802Only a subset of the attributes are supported: 18803 18804@itemize @minus 18805@item 18806@t{'First}, @t{'Last}, and @t{'Length} 18807 on array objects (not on types and subtypes). 18808 18809@item 18810@t{'Min} and @t{'Max}. 18811 18812@item 18813@t{'Pos} and @t{'Val}. 18814 18815@item 18816@t{'Tag}. 18817 18818@item 18819@t{'Range} on array objects (not subtypes), but only as the right 18820operand of the membership (@code{in}) operator. 18821 18822@item 18823@t{'Access}, @t{'Unchecked_Access}, and 18824@t{'Unrestricted_Access} (a GNAT extension). 18825 18826@item 18827@t{'Address}. 18828@end itemize 18829 18830@item 18831The names in @code{Characters.Latin_1} are not available. 18832 18833@item 18834Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise 18835equality of representations. They will generally work correctly 18836for strings and arrays whose elements have integer or enumeration types. 18837They may not work correctly for arrays whose element 18838types have user-defined equality, for arrays of real values 18839(in particular, IEEE-conformant floating point, because of negative 18840zeroes and NaNs), and for arrays whose elements contain unused bits with 18841indeterminate values. 18842 18843@item 18844The other component-by-component array operations (@code{and}, @code{or}, 18845@code{xor}, @code{not}, and relational tests other than equality) 18846are not implemented. 18847 18848@item 18849@cindex array aggregates (Ada) 18850@cindex record aggregates (Ada) 18851@cindex aggregates (Ada) 18852There is limited support for array and record aggregates. They are 18853permitted only on the right sides of assignments, as in these examples: 18854 18855@smallexample 18856(@value{GDBP}) set An_Array := (1, 2, 3, 4, 5, 6) 18857(@value{GDBP}) set An_Array := (1, others => 0) 18858(@value{GDBP}) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) 18859(@value{GDBP}) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) 18860(@value{GDBP}) set A_Record := (1, "Peter", True); 18861(@value{GDBP}) set A_Record := (Name => "Peter", Id => 1, Alive => True) 18862@end smallexample 18863 18864Changing a 18865discriminant's value by assigning an aggregate has an 18866undefined effect if that discriminant is used within the record. 18867However, you can first modify discriminants by directly assigning to 18868them (which normally would not be allowed in Ada), and then performing an 18869aggregate assignment. For example, given a variable @code{A_Rec} 18870declared to have a type such as: 18871 18872@smallexample 18873type Rec (Len : Small_Integer := 0) is record 18874 Id : Integer; 18875 Vals : IntArray (1 .. Len); 18876end record; 18877@end smallexample 18878 18879you can assign a value with a different size of @code{Vals} with two 18880assignments: 18881 18882@smallexample 18883(@value{GDBP}) set A_Rec.Len := 4 18884(@value{GDBP}) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) 18885@end smallexample 18886 18887As this example also illustrates, @value{GDBN} is very loose about the usual 18888rules concerning aggregates. You may leave out some of the 18889components of an array or record aggregate (such as the @code{Len} 18890component in the assignment to @code{A_Rec} above); they will retain their 18891original values upon assignment. You may freely use dynamic values as 18892indices in component associations. You may even use overlapping or 18893redundant component associations, although which component values are 18894assigned in such cases is not defined. 18895 18896@item 18897Calls to dispatching subprograms are not implemented. 18898 18899@item 18900The overloading algorithm is much more limited (i.e., less selective) 18901than that of real Ada. It makes only limited use of the context in 18902which a subexpression appears to resolve its meaning, and it is much 18903looser in its rules for allowing type matches. As a result, some 18904function calls will be ambiguous, and the user will be asked to choose 18905the proper resolution. 18906 18907@item 18908The @code{new} operator is not implemented. 18909 18910@item 18911Entry calls are not implemented. 18912 18913@item 18914Aside from printing, arithmetic operations on the native VAX floating-point 18915formats are not supported. 18916 18917@item 18918It is not possible to slice a packed array. 18919 18920@item 18921The names @code{True} and @code{False}, when not part of a qualified name, 18922are interpreted as if implicitly prefixed by @code{Standard}, regardless of 18923context. 18924Should your program 18925redefine these names in a package or procedure (at best a dubious practice), 18926you will have to use fully qualified names to access their new definitions. 18927 18928@item 18929Based real literals are not implemented. 18930@end itemize 18931 18932@node Additions to Ada 18933@subsubsection Additions to Ada 18934@cindex Ada, deviations from 18935 18936As it does for other languages, @value{GDBN} makes certain generic 18937extensions to Ada (@pxref{Expressions}): 18938 18939@itemize @bullet 18940@item 18941If the expression @var{E} is a variable residing in memory (typically 18942a local variable or array element) and @var{N} is a positive integer, 18943then @code{@var{E}@@@var{N}} displays the values of @var{E} and the 18944@var{N}-1 adjacent variables following it in memory as an array. In 18945Ada, this operator is generally not necessary, since its prime use is 18946in displaying parts of an array, and slicing will usually do this in 18947Ada. However, there are occasional uses when debugging programs in 18948which certain debugging information has been optimized away. 18949 18950@item 18951@code{@var{B}::@var{var}} means ``the variable named @var{var} that 18952appears in function or file @var{B}.'' When @var{B} is a file name, 18953you must typically surround it in single quotes. 18954 18955@item 18956The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type 18957@var{type} that appears at address @var{addr}.'' 18958 18959@item 18960A name starting with @samp{$} is a convenience variable 18961(@pxref{Convenience Vars}) or a machine register (@pxref{Registers}). 18962@end itemize 18963 18964In addition, @value{GDBN} provides a few other shortcuts and outright 18965additions specific to Ada: 18966 18967@itemize @bullet 18968@item 18969The assignment statement is allowed as an expression, returning 18970its right-hand operand as its value. Thus, you may enter 18971 18972@smallexample 18973(@value{GDBP}) set x := y + 3 18974(@value{GDBP}) print A(tmp := y + 1) 18975@end smallexample 18976 18977@item 18978The semicolon is allowed as an ``operator,'' returning as its value 18979the value of its right-hand operand. 18980This allows, for example, 18981complex conditional breaks: 18982 18983@smallexample 18984(@value{GDBP}) break f 18985(@value{GDBP}) condition 1 (report(i); k += 1; A(k) > 100) 18986@end smallexample 18987 18988@item 18989An extension to based literals can be used to specify the exact byte 18990contents of a floating-point literal. After the base, you can use 18991from zero to two @samp{l} characters, followed by an @samp{f}. The 18992number of @samp{l} characters controls the width of the resulting real 18993constant: zero means @code{Float} is used, one means 18994@code{Long_Float}, and two means @code{Long_Long_Float}. 18995 18996@smallexample 18997(@value{GDBP}) print 16f#41b80000# 18998$1 = 23.0 18999@end smallexample 19000 19001@item 19002Rather than use catenation and symbolic character names to introduce special 19003characters into strings, one may instead use a special bracket notation, 19004which is also used to print strings. A sequence of characters of the form 19005@samp{["@var{XX}"]} within a string or character literal denotes the 19006(single) character whose numeric encoding is @var{XX} in hexadecimal. The 19007sequence of characters @samp{["""]} also denotes a single quotation mark 19008in strings. For example, 19009@smallexample 19010 "One line.["0a"]Next line.["0a"]" 19011@end smallexample 19012@noindent 19013contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF}) 19014after each period. 19015 19016@item 19017The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and 19018@t{'Max} is optional (and is ignored in any case). For example, it is valid 19019to write 19020 19021@smallexample 19022(@value{GDBP}) print 'max(x, y) 19023@end smallexample 19024 19025@item 19026When printing arrays, @value{GDBN} uses positional notation when the 19027array has a lower bound of 1, and uses a modified named notation otherwise. 19028For example, a one-dimensional array of three integers with a lower bound 19029of 3 might print as 19030 19031@smallexample 19032(3 => 10, 17, 1) 19033@end smallexample 19034 19035@noindent 19036That is, in contrast to valid Ada, only the first component has a @code{=>} 19037clause. 19038 19039@item 19040You may abbreviate attributes in expressions with any unique, 19041multi-character subsequence of 19042their names (an exact match gets preference). 19043For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh} 19044in place of @t{a'length}. 19045 19046@item 19047@cindex quoting Ada internal identifiers 19048Since Ada is case-insensitive, the debugger normally maps identifiers you type 19049to lower case. The GNAT compiler uses upper-case characters for 19050some of its internal identifiers, which are normally of no interest to users. 19051For the rare occasions when you actually have to look at them, 19052enclose them in angle brackets to avoid the lower-case mapping. 19053For example, 19054@smallexample 19055(@value{GDBP}) print <JMPBUF_SAVE>[0] 19056@end smallexample 19057 19058@item 19059Printing an object of class-wide type or dereferencing an 19060access-to-class-wide value will display all the components of the object's 19061specific type (as indicated by its run-time tag). Likewise, component 19062selection on such a value will operate on the specific type of the 19063object. 19064 19065@end itemize 19066 19067@node Overloading support for Ada 19068@subsubsection Overloading support for Ada 19069@cindex overloading, Ada 19070 19071The debugger supports limited overloading. Given a subprogram call in which 19072the function symbol has multiple definitions, it will use the number of 19073actual parameters and some information about their types to attempt to narrow 19074the set of definitions. It also makes very limited use of context, preferring 19075procedures to functions in the context of the @code{call} command, and 19076functions to procedures elsewhere. 19077 19078If, after narrowing, the set of matching definitions still contains more than 19079one definition, @value{GDBN} will display a menu to query which one it should 19080use, for instance: 19081 19082@smallexample 19083(@value{GDBP}) print f(1) 19084Multiple matches for f 19085[0] cancel 19086[1] foo.f (integer) return boolean at foo.adb:23 19087[2] foo.f (foo.new_integer) return boolean at foo.adb:28 19088> 19089@end smallexample 19090 19091In this case, just select one menu entry either to cancel expression evaluation 19092(type @kbd{0} and press @key{RET}) or to continue evaluation with a specific 19093instance (type the corresponding number and press @key{RET}). 19094 19095Here are a couple of commands to customize @value{GDBN}'s behavior in this 19096case: 19097 19098@table @code 19099 19100@kindex set ada print-signatures 19101@item set ada print-signatures 19102Control whether parameter types and return types are displayed in overloads 19103selection menus. It is @code{on} by default. 19104@xref{Overloading support for Ada}. 19105 19106@kindex show ada print-signatures 19107@item show ada print-signatures 19108Show the current setting for displaying parameter types and return types in 19109overloads selection menu. 19110@xref{Overloading support for Ada}. 19111 19112@end table 19113 19114@node Stopping Before Main Program 19115@subsubsection Stopping at the Very Beginning 19116 19117@cindex breakpointing Ada elaboration code 19118It is sometimes necessary to debug the program during elaboration, and 19119before reaching the main procedure. 19120As defined in the Ada Reference 19121Manual, the elaboration code is invoked from a procedure called 19122@code{adainit}. To run your program up to the beginning of 19123elaboration, simply use the following two commands: 19124@code{tbreak adainit} and @code{run}. 19125 19126@node Ada Exceptions 19127@subsubsection Ada Exceptions 19128 19129A command is provided to list all Ada exceptions: 19130 19131@table @code 19132@kindex info exceptions 19133@item info exceptions 19134@itemx info exceptions @var{regexp} 19135The @code{info exceptions} command allows you to list all Ada exceptions 19136defined within the program being debugged, as well as their addresses. 19137With a regular expression, @var{regexp}, as argument, only those exceptions 19138whose names match @var{regexp} are listed. 19139@end table 19140 19141Below is a small example, showing how the command can be used, first 19142without argument, and next with a regular expression passed as an 19143argument. 19144 19145@smallexample 19146(@value{GDBP}) info exceptions 19147All defined Ada exceptions: 19148constraint_error: 0x613da0 19149program_error: 0x613d20 19150storage_error: 0x613ce0 19151tasking_error: 0x613ca0 19152const.aint_global_e: 0x613b00 19153(@value{GDBP}) info exceptions const.aint 19154All Ada exceptions matching regular expression "const.aint": 19155constraint_error: 0x613da0 19156const.aint_global_e: 0x613b00 19157@end smallexample 19158 19159It is also possible to ask @value{GDBN} to stop your program's execution 19160when an exception is raised. For more details, see @ref{Set Catchpoints}. 19161 19162@node Ada Tasks 19163@subsubsection Extensions for Ada Tasks 19164@cindex Ada, tasking 19165 19166Support for Ada tasks is analogous to that for threads (@pxref{Threads}). 19167@value{GDBN} provides the following task-related commands: 19168 19169@table @code 19170@kindex info tasks 19171@item info tasks 19172This command shows a list of current Ada tasks, as in the following example: 19173 19174 19175@smallexample 19176@iftex 19177@leftskip=0.5cm 19178@end iftex 19179(@value{GDBP}) info tasks 19180 ID TID P-ID Pri State Name 19181 1 8088000 0 15 Child Activation Wait main_task 19182 2 80a4000 1 15 Accept Statement b 19183 3 809a800 1 15 Child Activation Wait a 19184* 4 80ae800 3 15 Runnable c 19185 19186@end smallexample 19187 19188@noindent 19189In this listing, the asterisk before the last task indicates it to be the 19190task currently being inspected. 19191 19192@table @asis 19193@item ID 19194Represents @value{GDBN}'s internal task number. 19195 19196@item TID 19197The Ada task ID. 19198 19199@item P-ID 19200The parent's task ID (@value{GDBN}'s internal task number). 19201 19202@item Pri 19203The base priority of the task. 19204 19205@item State 19206Current state of the task. 19207 19208@table @code 19209@item Unactivated 19210The task has been created but has not been activated. It cannot be 19211executing. 19212 19213@item Runnable 19214The task is not blocked for any reason known to Ada. (It may be waiting 19215for a mutex, though.) It is conceptually "executing" in normal mode. 19216 19217@item Terminated 19218The task is terminated, in the sense of ARM 9.3 (5). Any dependents 19219that were waiting on terminate alternatives have been awakened and have 19220terminated themselves. 19221 19222@item Child Activation Wait 19223The task is waiting for created tasks to complete activation. 19224 19225@item Accept or Select Term 19226The task is waiting on an accept or selective wait statement. 19227 19228@item Waiting on entry call 19229The task is waiting on an entry call. 19230 19231@item Async Select Wait 19232The task is waiting to start the abortable part of an asynchronous 19233select statement. 19234 19235@item Delay Sleep 19236The task is waiting on a select statement with only a delay 19237alternative open. 19238 19239@item Child Termination Wait 19240The task is sleeping having completed a master within itself, and is 19241waiting for the tasks dependent on that master to become terminated or 19242waiting on a terminate Phase. 19243 19244@item Wait Child in Term Alt 19245The task is sleeping waiting for tasks on terminate alternatives to 19246finish terminating. 19247 19248@item Asynchronous Hold 19249The task has been held by @code{Ada.Asynchronous_Task_Control.Hold_Task}. 19250 19251@item Activating 19252The task has been created and is being made runnable. 19253 19254@item Selective Wait 19255The task is waiting in a selective wait statement. 19256 19257@item Accepting RV with @var{taskno} 19258The task is accepting a rendez-vous with the task @var{taskno}. 19259 19260@item Waiting on RV with @var{taskno} 19261The task is waiting for a rendez-vous with the task @var{taskno}. 19262@end table 19263 19264@item Name 19265Name of the task in the program. 19266 19267@end table 19268 19269@kindex info task @var{taskno} 19270@item info task @var{taskno} 19271This command shows detailed information on the specified task, as in 19272the following example: 19273@smallexample 19274@iftex 19275@leftskip=0.5cm 19276@end iftex 19277(@value{GDBP}) info tasks 19278 ID TID P-ID Pri State Name 19279 1 8077880 0 15 Child Activation Wait main_task 19280* 2 807c468 1 15 Runnable task_1 19281(@value{GDBP}) info task 2 19282Ada Task: 0x807c468 19283Name: "task_1" 19284Thread: 0 19285LWP: 0x1fac 19286Parent: 1 ("main_task") 19287Base Priority: 15 19288State: Runnable 19289@end smallexample 19290 19291@item task 19292@kindex task@r{ (Ada)} 19293@cindex current Ada task ID 19294This command prints the ID and name of the current task. 19295 19296@smallexample 19297@iftex 19298@leftskip=0.5cm 19299@end iftex 19300(@value{GDBP}) info tasks 19301 ID TID P-ID Pri State Name 19302 1 8077870 0 15 Child Activation Wait main_task 19303* 2 807c458 1 15 Runnable some_task 19304(@value{GDBP}) task 19305[Current task is 2 "some_task"] 19306@end smallexample 19307 19308@item task @var{taskno} 19309@cindex Ada task switching 19310This command is like the @code{thread @var{thread-id}} 19311command (@pxref{Threads}). It switches the context of debugging 19312from the current task to the given task. 19313 19314@smallexample 19315@iftex 19316@leftskip=0.5cm 19317@end iftex 19318(@value{GDBP}) info tasks 19319 ID TID P-ID Pri State Name 19320 1 8077870 0 15 Child Activation Wait main_task 19321* 2 807c458 1 15 Runnable some_task 19322(@value{GDBP}) task 1 19323[Switching to task 1 "main_task"] 19324#0 0x8067726 in pthread_cond_wait () 19325(@value{GDBP}) bt 19326#0 0x8067726 in pthread_cond_wait () 19327#1 0x8056714 in system.os_interface.pthread_cond_wait () 19328#2 0x805cb63 in system.task_primitives.operations.sleep () 19329#3 0x806153e in system.tasking.stages.activate_tasks () 19330#4 0x804aacc in un () at un.adb:5 19331@end smallexample 19332 19333@item task apply [@var{task-id-list} | all] [@var{flag}]@dots{} @var{command} 19334The @code{task apply} command is the Ada tasking analogue of 19335@code{thread apply} (@pxref{Threads}). It allows you to apply the 19336named @var{command} to one or more tasks. Specify the tasks that you 19337want affected using a list of task IDs, or specify @code{all} to apply 19338to all tasks. 19339 19340The @var{flag} arguments control what output to produce and how to 19341handle errors raised when applying @var{command} to a task. 19342@var{flag} must start with a @code{-} directly followed by one letter 19343in @code{qcs}. If several flags are provided, they must be given 19344individually, such as @code{-c -q}. 19345 19346By default, @value{GDBN} displays some task information before the 19347output produced by @var{command}, and an error raised during the 19348execution of a @var{command} will abort @code{task apply}. The 19349following flags can be used to fine-tune this behavior: 19350 19351@table @code 19352@item -c 19353The flag @code{-c}, which stands for @samp{continue}, causes any 19354errors in @var{command} to be displayed, and the execution of 19355@code{task apply} then continues. 19356@item -s 19357The flag @code{-s}, which stands for @samp{silent}, causes any errors 19358or empty output produced by a @var{command} to be silently ignored. 19359That is, the execution continues, but the task information and errors 19360are not printed. 19361@item -q 19362The flag @code{-q} (@samp{quiet}) disables printing the task 19363information. 19364@end table 19365 19366Flags @code{-c} and @code{-s} cannot be used together. 19367 19368@item break @var{locspec} task @var{taskno} 19369@itemx break @var{locspec} task @var{taskno} if @dots{} 19370@cindex breakpoints and tasks, in Ada 19371@cindex task breakpoints, in Ada 19372@kindex break @dots{} task @var{taskno}@r{ (Ada)} 19373These commands are like the @code{break @dots{} thread @dots{}} 19374command (@pxref{Thread Stops}). @xref{Location Specifications}, for 19375the various forms of @var{locspec}. 19376 19377Use the qualifier @samp{task @var{taskno}} with a breakpoint command 19378to specify that you only want @value{GDBN} to stop the program when a 19379particular Ada task reaches this breakpoint. The @var{taskno} is one of the 19380numeric task identifiers assigned by @value{GDBN}, shown in the first 19381column of the @samp{info tasks} display. 19382 19383If you do not specify @samp{task @var{taskno}} when you set a 19384breakpoint, the breakpoint applies to @emph{all} tasks of your 19385program. 19386 19387You can use the @code{task} qualifier on conditional breakpoints as 19388well; in this case, place @samp{task @var{taskno}} before the 19389breakpoint condition (before the @code{if}). 19390 19391For example, 19392 19393@smallexample 19394@iftex 19395@leftskip=0.5cm 19396@end iftex 19397(@value{GDBP}) info tasks 19398 ID TID P-ID Pri State Name 19399 1 140022020 0 15 Child Activation Wait main_task 19400 2 140045060 1 15 Accept/Select Wait t2 19401 3 140044840 1 15 Runnable t1 19402* 4 140056040 1 15 Runnable t3 19403(@value{GDBP}) b 15 task 2 19404Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15. 19405(@value{GDBP}) cont 19406Continuing. 19407task # 1 running 19408task # 2 running 19409 19410Breakpoint 5, test_task_debug () at test_task_debug.adb:15 1941115 flush; 19412(@value{GDBP}) info tasks 19413 ID TID P-ID Pri State Name 19414 1 140022020 0 15 Child Activation Wait main_task 19415* 2 140045060 1 15 Runnable t2 19416 3 140044840 1 15 Runnable t1 19417 4 140056040 1 15 Delay Sleep t3 19418@end smallexample 19419@end table 19420 19421@node Ada Tasks and Core Files 19422@subsubsection Tasking Support when Debugging Core Files 19423@cindex Ada tasking and core file debugging 19424 19425When inspecting a core file, as opposed to debugging a live program, 19426tasking support may be limited or even unavailable, depending on 19427the platform being used. 19428For instance, on x86-linux, the list of tasks is available, but task 19429switching is not supported. 19430 19431On certain platforms, the debugger needs to perform some 19432memory writes in order to provide Ada tasking support. When inspecting 19433a core file, this means that the core file must be opened with read-write 19434privileges, using the command @samp{"set write on"} (@pxref{Patching}). 19435Under these circumstances, you should make a backup copy of the core 19436file before inspecting it with @value{GDBN}. 19437 19438@node Ravenscar Profile 19439@subsubsection Tasking Support when using the Ravenscar Profile 19440@cindex Ravenscar Profile 19441 19442The @dfn{Ravenscar Profile} is a subset of the Ada tasking features, 19443specifically designed for systems with safety-critical real-time 19444requirements. 19445 19446@table @code 19447@kindex set ravenscar task-switching on 19448@cindex task switching with program using Ravenscar Profile 19449@item set ravenscar task-switching on 19450Allows task switching when debugging a program that uses the Ravenscar 19451Profile. This is the default. 19452 19453@kindex set ravenscar task-switching off 19454@item set ravenscar task-switching off 19455Turn off task switching when debugging a program that uses the Ravenscar 19456Profile. This is mostly intended to disable the code that adds support 19457for the Ravenscar Profile, in case a bug in either @value{GDBN} or in 19458the Ravenscar runtime is preventing @value{GDBN} from working properly. 19459To be effective, this command should be run before the program is started. 19460 19461@kindex show ravenscar task-switching 19462@item show ravenscar task-switching 19463Show whether it is possible to switch from task to task in a program 19464using the Ravenscar Profile. 19465 19466@end table 19467 19468@cindex Ravenscar thread 19469When Ravenscar task-switching is enabled, Ravenscar tasks are 19470announced by @value{GDBN} as if they were threads: 19471 19472@smallexample 19473(gdb) continue 19474[New Ravenscar Thread 0x2b8f0] 19475@end smallexample 19476 19477Both Ravenscar tasks and the underlying CPU threads will show up in 19478the output of @code{info threads}: 19479 19480@smallexample 19481(gdb) info threads 19482 Id Target Id Frame 19483 1 Thread 1 (CPU#0 [running]) simple () at simple.adb:10 19484 2 Thread 2 (CPU#1 [running]) 0x0000000000003d34 in __gnat_initialize_cpu_devices () 19485 3 Thread 3 (CPU#2 [running]) 0x0000000000003d28 in __gnat_initialize_cpu_devices () 19486 4 Thread 4 (CPU#3 [halted ]) 0x000000000000c6ec in system.task_primitives.operations.idle () 19487* 5 Ravenscar Thread 0x2b8f0 simple () at simple.adb:10 19488 6 Ravenscar Thread 0x2f150 0x000000000000c6ec in system.task_primitives.operations.idle () 19489@end smallexample 19490 19491One known limitation of the Ravenscar support in @value{GDBN} is that 19492it isn't currently possible to single-step through the runtime 19493initialization sequence. If you need to debug this code, you should 19494use @code{set ravenscar task-switching off}. 19495 19496@node Ada Source Character Set 19497@subsubsection Ada Source Character Set 19498@cindex Ada, source character set 19499 19500The GNAT compiler supports a number of character sets for source 19501files. @xref{Character Set Control, , Character Set Control, 19502gnat_ugn}. @value{GDBN} includes support for this as well. 19503 19504@table @code 19505@item set ada source-charset @var{charset} 19506@kindex set ada source-charset 19507Set the source character set for Ada. The character set must be 19508supported by GNAT. Because this setting affects the decoding of 19509symbols coming from the debug information in your program, the setting 19510should be set as early as possible. The default is @code{ISO-8859-1}, 19511because that is also GNAT's default. 19512 19513@item show ada source-charset 19514@kindex show ada source-charset 19515Show the current source character set for Ada. 19516@end table 19517 19518@node Ada Glitches 19519@subsubsection Known Peculiarities of Ada Mode 19520@cindex Ada, problems 19521 19522Besides the omissions listed previously (@pxref{Omissions from Ada}), 19523we know of several problems with and limitations of Ada mode in 19524@value{GDBN}, 19525some of which will be fixed with planned future releases of the debugger 19526and the GNU Ada compiler. 19527 19528@itemize @bullet 19529@item 19530Static constants that the compiler chooses not to materialize as objects in 19531storage are invisible to the debugger. 19532 19533@item 19534Named parameter associations in function argument lists are ignored (the 19535argument lists are treated as positional). 19536 19537@item 19538Many useful library packages are currently invisible to the debugger. 19539 19540@item 19541Fixed-point arithmetic, conversions, input, and output is carried out using 19542floating-point arithmetic, and may give results that only approximate those on 19543the host machine. 19544 19545@item 19546The GNAT compiler never generates the prefix @code{Standard} for any of 19547the standard symbols defined by the Ada language. @value{GDBN} knows about 19548this: it will strip the prefix from names when you use it, and will never 19549look for a name you have so qualified among local symbols, nor match against 19550symbols in other packages or subprograms. If you have 19551defined entities anywhere in your program other than parameters and 19552local variables whose simple names match names in @code{Standard}, 19553GNAT's lack of qualification here can cause confusion. When this happens, 19554you can usually resolve the confusion 19555by qualifying the problematic names with package 19556@code{Standard} explicitly. 19557@end itemize 19558 19559Older versions of the compiler sometimes generate erroneous debugging 19560information, resulting in the debugger incorrectly printing the value 19561of affected entities. In some cases, the debugger is able to work 19562around an issue automatically. In other cases, the debugger is able 19563to work around the issue, but the work-around has to be specifically 19564enabled. 19565 19566@kindex set ada trust-PAD-over-XVS 19567@kindex show ada trust-PAD-over-XVS 19568@table @code 19569 19570@item set ada trust-PAD-over-XVS on 19571Configure GDB to strictly follow the GNAT encoding when computing the 19572value of Ada entities, particularly when @code{PAD} and @code{PAD___XVS} 19573types are involved (see @code{ada/exp_dbug.ads} in the GCC sources for 19574a complete description of the encoding used by the GNAT compiler). 19575This is the default. 19576 19577@item set ada trust-PAD-over-XVS off 19578This is related to the encoding using by the GNAT compiler. If @value{GDBN} 19579sometimes prints the wrong value for certain entities, changing @code{ada 19580trust-PAD-over-XVS} to @code{off} activates a work-around which may fix 19581the issue. It is always safe to set @code{ada trust-PAD-over-XVS} to 19582@code{off}, but this incurs a slight performance penalty, so it is 19583recommended to leave this setting to @code{on} unless necessary. 19584 19585@end table 19586 19587@cindex GNAT descriptive types 19588@cindex GNAT encoding 19589Internally, the debugger also relies on the compiler following a number 19590of conventions known as the @samp{GNAT Encoding}, all documented in 19591@file{gcc/ada/exp_dbug.ads} in the GCC sources. This encoding describes 19592how the debugging information should be generated for certain types. 19593In particular, this convention makes use of @dfn{descriptive types}, 19594which are artificial types generated purely to help the debugger. 19595 19596These encodings were defined at a time when the debugging information 19597format used was not powerful enough to describe some of the more complex 19598types available in Ada. Since DWARF allows us to express nearly all 19599Ada features, the long-term goal is to slowly replace these descriptive 19600types by their pure DWARF equivalent. To facilitate that transition, 19601a new maintenance option is available to force the debugger to ignore 19602those descriptive types. It allows the user to quickly evaluate how 19603well @value{GDBN} works without them. 19604 19605@table @code 19606 19607@kindex maint ada set ignore-descriptive-types 19608@item maintenance ada set ignore-descriptive-types [on|off] 19609Control whether the debugger should ignore descriptive types. 19610The default is not to ignore descriptives types (@code{off}). 19611 19612@kindex maint ada show ignore-descriptive-types 19613@item maintenance ada show ignore-descriptive-types 19614Show if descriptive types are ignored by @value{GDBN}. 19615 19616@end table 19617 19618@node Unsupported Languages 19619@section Unsupported Languages 19620 19621@cindex unsupported languages 19622@cindex minimal language 19623In addition to the other fully-supported programming languages, 19624@value{GDBN} also provides a pseudo-language, called @code{minimal}. 19625It does not represent a real programming language, but provides a set 19626of capabilities close to what the C or assembly languages provide. 19627This should allow most simple operations to be performed while debugging 19628an application that uses a language currently not supported by @value{GDBN}. 19629 19630If the language is set to @code{auto}, @value{GDBN} will automatically 19631select this language if the current frame corresponds to an unsupported 19632language. 19633 19634@node Symbols 19635@chapter Examining the Symbol Table 19636 19637The commands described in this chapter allow you to inquire about the 19638symbols (names of variables, functions and types) defined in your 19639program. This information is inherent in the text of your program and 19640does not change as your program executes. @value{GDBN} finds it in your 19641program's symbol table, in the file indicated when you started @value{GDBN} 19642(@pxref{File Options, ,Choosing Files}), or by one of the 19643file-management commands (@pxref{Files, ,Commands to Specify Files}). 19644 19645@cindex symbol names 19646@cindex names of symbols 19647@cindex quoting names 19648@anchor{quoting names} 19649Occasionally, you may need to refer to symbols that contain unusual 19650characters, which @value{GDBN} ordinarily treats as word delimiters. The 19651most frequent case is in referring to static variables in other 19652source files (@pxref{Variables,,Program Variables}). File names 19653are recorded in object files as debugging symbols, but @value{GDBN} would 19654ordinarily parse a typical file name, like @file{foo.c}, as the three words 19655@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize 19656@samp{foo.c} as a single symbol, enclose it in single quotes; for example, 19657 19658@smallexample 19659p 'foo.c'::x 19660@end smallexample 19661 19662@noindent 19663looks up the value of @code{x} in the scope of the file @file{foo.c}. 19664 19665@table @code 19666@cindex case-insensitive symbol names 19667@cindex case sensitivity in symbol names 19668@kindex set case-sensitive 19669@item set case-sensitive on 19670@itemx set case-sensitive off 19671@itemx set case-sensitive auto 19672Normally, when @value{GDBN} looks up symbols, it matches their names 19673with case sensitivity determined by the current source language. 19674Occasionally, you may wish to control that. The command @code{set 19675case-sensitive} lets you do that by specifying @code{on} for 19676case-sensitive matches or @code{off} for case-insensitive ones. If 19677you specify @code{auto}, case sensitivity is reset to the default 19678suitable for the source language. The default is case-sensitive 19679matches for all languages except for Fortran, for which the default is 19680case-insensitive matches. 19681 19682@kindex show case-sensitive 19683@item show case-sensitive 19684This command shows the current setting of case sensitivity for symbols 19685lookups. 19686 19687@kindex set print type methods 19688@item set print type methods 19689@itemx set print type methods on 19690@itemx set print type methods off 19691Normally, when @value{GDBN} prints a class, it displays any methods 19692declared in that class. You can control this behavior either by 19693passing the appropriate flag to @code{ptype}, or using @command{set 19694print type methods}. Specifying @code{on} will cause @value{GDBN} to 19695display the methods; this is the default. Specifying @code{off} will 19696cause @value{GDBN} to omit the methods. 19697 19698@kindex show print type methods 19699@item show print type methods 19700This command shows the current setting of method display when printing 19701classes. 19702 19703@kindex set print type nested-type-limit 19704@item set print type nested-type-limit @var{limit} 19705@itemx set print type nested-type-limit unlimited 19706Set the limit of displayed nested types that the type printer will 19707show. A @var{limit} of @code{unlimited} or @code{-1} will show all 19708nested definitions. By default, the type printer will not show any nested 19709types defined in classes. 19710 19711@kindex show print type nested-type-limit 19712@item show print type nested-type-limit 19713This command shows the current display limit of nested types when 19714printing classes. 19715 19716@kindex set print type typedefs 19717@item set print type typedefs 19718@itemx set print type typedefs on 19719@itemx set print type typedefs off 19720 19721Normally, when @value{GDBN} prints a class, it displays any typedefs 19722defined in that class. You can control this behavior either by 19723passing the appropriate flag to @code{ptype}, or using @command{set 19724print type typedefs}. Specifying @code{on} will cause @value{GDBN} to 19725display the typedef definitions; this is the default. Specifying 19726@code{off} will cause @value{GDBN} to omit the typedef definitions. 19727Note that this controls whether the typedef definition itself is 19728printed, not whether typedef names are substituted when printing other 19729types. 19730 19731@kindex show print type typedefs 19732@item show print type typedefs 19733This command shows the current setting of typedef display when 19734printing classes. 19735 19736@kindex set print type hex 19737@item set print type hex 19738@itemx set print type hex on 19739@itemx set print type hex off 19740 19741When @value{GDBN} prints sizes and offsets of struct members, it can use 19742either the decimal or hexadecimal notation. You can select one or the 19743other either by passing the appropriate flag to @code{ptype}, or by using 19744the @command{set print type hex} command. 19745 19746@kindex show print type hex 19747@item show print type hex 19748This command shows whether the sizes and offsets of struct members are 19749printed in decimal or hexadecimal notation. 19750 19751@kindex info address 19752@cindex address of a symbol 19753@item info address @var{symbol} 19754Describe where the data for @var{symbol} is stored. For a register 19755variable, this says which register it is kept in. For a non-register 19756local variable, this prints the stack-frame offset at which the variable 19757is always stored. 19758 19759Note the contrast with @samp{print &@var{symbol}}, which does not work 19760at all for a register variable, and for a stack local variable prints 19761the exact address of the current instantiation of the variable. 19762 19763@kindex info symbol 19764@cindex symbol from address 19765@cindex closest symbol and offset for an address 19766@item info symbol @var{addr} 19767Print the name of a symbol which is stored at the address @var{addr}. 19768If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the 19769nearest symbol and an offset from it: 19770 19771@smallexample 19772(@value{GDBP}) info symbol 0x54320 19773_initialize_vx + 396 in section .text 19774@end smallexample 19775 19776@noindent 19777This is the opposite of the @code{info address} command. You can use 19778it to find out the name of a variable or a function given its address. 19779 19780For dynamically linked executables, the name of executable or shared 19781library containing the symbol is also printed: 19782 19783@smallexample 19784(@value{GDBP}) info symbol 0x400225 19785_start + 5 in section .text of /tmp/a.out 19786(@value{GDBP}) info symbol 0x2aaaac2811cf 19787__read_nocancel + 6 in section .text of /usr/lib64/libc.so.6 19788@end smallexample 19789 19790@kindex demangle 19791@cindex demangle 19792@item demangle @r{[}-l @var{language}@r{]} @r{[}@var{--}@r{]} @var{name} 19793Demangle @var{name}. 19794If @var{language} is provided it is the name of the language to demangle 19795@var{name} in. Otherwise @var{name} is demangled in the current language. 19796 19797The @samp{--} option specifies the end of options, 19798and is useful when @var{name} begins with a dash. 19799 19800The parameter @code{demangle-style} specifies how to interpret the kind 19801of mangling used. @xref{Print Settings}. 19802 19803@kindex whatis 19804@item whatis[/@var{flags}] [@var{arg}] 19805Print the data type of @var{arg}, which can be either an expression 19806or a name of a data type. With no argument, print the data type of 19807@code{$}, the last value in the value history. 19808 19809If @var{arg} is an expression (@pxref{Expressions, ,Expressions}), it 19810is not actually evaluated, and any side-effecting operations (such as 19811assignments or function calls) inside it do not take place. 19812 19813If @var{arg} is a variable or an expression, @code{whatis} prints its 19814literal type as it is used in the source code. If the type was 19815defined using a @code{typedef}, @code{whatis} will @emph{not} print 19816the data type underlying the @code{typedef}. If the type of the 19817variable or the expression is a compound data type, such as 19818@code{struct} or @code{class}, @code{whatis} never prints their 19819fields or methods. It just prints the @code{struct}/@code{class} 19820name (a.k.a.@: its @dfn{tag}). If you want to see the members of 19821such a compound data type, use @code{ptype}. 19822 19823If @var{arg} is a type name that was defined using @code{typedef}, 19824@code{whatis} @dfn{unrolls} only one level of that @code{typedef}. 19825Unrolling means that @code{whatis} will show the underlying type used 19826in the @code{typedef} declaration of @var{arg}. However, if that 19827underlying type is also a @code{typedef}, @code{whatis} will not 19828unroll it. 19829 19830For C code, the type names may also have the form @samp{class 19831@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union 19832@var{union-tag}} or @samp{enum @var{enum-tag}}. 19833 19834@var{flags} can be used to modify how the type is displayed. 19835Available flags are: 19836 19837@table @code 19838@item r 19839Display in ``raw'' form. Normally, @value{GDBN} substitutes template 19840parameters and typedefs defined in a class when printing the class' 19841members. The @code{/r} flag disables this. 19842 19843@item m 19844Do not print methods defined in the class. 19845 19846@item M 19847Print methods defined in the class. This is the default, but the flag 19848exists in case you change the default with @command{set print type methods}. 19849 19850@item t 19851Do not print typedefs defined in the class. Note that this controls 19852whether the typedef definition itself is printed, not whether typedef 19853names are substituted when printing other types. 19854 19855@item T 19856Print typedefs defined in the class. This is the default, but the flag 19857exists in case you change the default with @command{set print type typedefs}. 19858 19859@item o 19860Print the offsets and sizes of fields in a struct, similar to what the 19861@command{pahole} tool does. This option implies the @code{/tm} flags. 19862 19863@item x 19864Use hexadecimal notation when printing offsets and sizes of fields in a 19865struct. 19866 19867@item d 19868Use decimal notation when printing offsets and sizes of fields in a 19869struct. 19870 19871For example, given the following declarations: 19872 19873@smallexample 19874struct tuv 19875@{ 19876 int a1; 19877 char *a2; 19878 int a3; 19879@}; 19880 19881struct xyz 19882@{ 19883 int f1; 19884 char f2; 19885 void *f3; 19886 struct tuv f4; 19887@}; 19888 19889union qwe 19890@{ 19891 struct tuv fff1; 19892 struct xyz fff2; 19893@}; 19894 19895struct tyu 19896@{ 19897 int a1 : 1; 19898 int a2 : 3; 19899 int a3 : 23; 19900 char a4 : 2; 19901 int64_t a5; 19902 int a6 : 5; 19903 int64_t a7 : 3; 19904@}; 19905@end smallexample 19906 19907Issuing a @kbd{ptype /o struct tuv} command would print: 19908 19909@smallexample 19910(@value{GDBP}) ptype /o struct tuv 19911/* offset | size */ type = struct tuv @{ 19912/* 0 | 4 */ int a1; 19913/* XXX 4-byte hole */ 19914/* 8 | 8 */ char *a2; 19915/* 16 | 4 */ int a3; 19916 19917 /* total size (bytes): 24 */ 19918 @} 19919@end smallexample 19920 19921Notice the format of the first column of comments. There, you can 19922find two parts separated by the @samp{|} character: the @emph{offset}, 19923which indicates where the field is located inside the struct, in 19924bytes, and the @emph{size} of the field. Another interesting line is 19925the marker of a @emph{hole} in the struct, indicating that it may be 19926possible to pack the struct and make it use less space by reorganizing 19927its fields. 19928 19929It is also possible to print offsets inside an union: 19930 19931@smallexample 19932(@value{GDBP}) ptype /o union qwe 19933/* offset | size */ type = union qwe @{ 19934/* 24 */ struct tuv @{ 19935/* 0 | 4 */ int a1; 19936/* XXX 4-byte hole */ 19937/* 8 | 8 */ char *a2; 19938/* 16 | 4 */ int a3; 19939 19940 /* total size (bytes): 24 */ 19941 @} fff1; 19942/* 40 */ struct xyz @{ 19943/* 0 | 4 */ int f1; 19944/* 4 | 1 */ char f2; 19945/* XXX 3-byte hole */ 19946/* 8 | 8 */ void *f3; 19947/* 16 | 24 */ struct tuv @{ 19948/* 16 | 4 */ int a1; 19949/* XXX 4-byte hole */ 19950/* 24 | 8 */ char *a2; 19951/* 32 | 4 */ int a3; 19952 19953 /* total size (bytes): 24 */ 19954 @} f4; 19955 19956 /* total size (bytes): 40 */ 19957 @} fff2; 19958 19959 /* total size (bytes): 40 */ 19960 @} 19961@end smallexample 19962 19963In this case, since @code{struct tuv} and @code{struct xyz} occupy the 19964same space (because we are dealing with an union), the offset is not 19965printed for them. However, you can still examine the offset of each 19966of these structures' fields. 19967 19968Another useful scenario is printing the offsets of a struct containing 19969bitfields: 19970 19971@smallexample 19972(@value{GDBP}) ptype /o struct tyu 19973/* offset | size */ type = struct tyu @{ 19974/* 0:31 | 4 */ int a1 : 1; 19975/* 0:28 | 4 */ int a2 : 3; 19976/* 0: 5 | 4 */ int a3 : 23; 19977/* 3: 3 | 1 */ signed char a4 : 2; 19978/* XXX 3-bit hole */ 19979/* XXX 4-byte hole */ 19980/* 8 | 8 */ int64_t a5; 19981/* 16: 0 | 4 */ int a6 : 5; 19982/* 16: 5 | 8 */ int64_t a7 : 3; 19983/* XXX 7-byte padding */ 19984 19985 /* total size (bytes): 24 */ 19986 @} 19987@end smallexample 19988 19989Note how the offset information is now extended to also include the 19990first bit of the bitfield. 19991@end table 19992 19993@kindex ptype 19994@item ptype[/@var{flags}] [@var{arg}] 19995@code{ptype} accepts the same arguments as @code{whatis}, but prints a 19996detailed description of the type, instead of just the name of the type. 19997@xref{Expressions, ,Expressions}. 19998 19999Contrary to @code{whatis}, @code{ptype} always unrolls any 20000@code{typedef}s in its argument declaration, whether the argument is 20001a variable, expression, or a data type. This means that @code{ptype} 20002of a variable or an expression will not print literally its type as 20003present in the source code---use @code{whatis} for that. @code{typedef}s at 20004the pointer or reference targets are also unrolled. Only @code{typedef}s of 20005fields, methods and inner @code{class typedef}s of @code{struct}s, 20006@code{class}es and @code{union}s are not unrolled even with @code{ptype}. 20007 20008For example, for this variable declaration: 20009 20010@smallexample 20011typedef double real_t; 20012struct complex @{ real_t real; double imag; @}; 20013typedef struct complex complex_t; 20014complex_t var; 20015real_t *real_pointer_var; 20016@end smallexample 20017 20018@noindent 20019the two commands give this output: 20020 20021@smallexample 20022@group 20023(@value{GDBP}) whatis var 20024type = complex_t 20025(@value{GDBP}) ptype var 20026type = struct complex @{ 20027 real_t real; 20028 double imag; 20029@} 20030(@value{GDBP}) whatis complex_t 20031type = struct complex 20032(@value{GDBP}) whatis struct complex 20033type = struct complex 20034(@value{GDBP}) ptype struct complex 20035type = struct complex @{ 20036 real_t real; 20037 double imag; 20038@} 20039(@value{GDBP}) whatis real_pointer_var 20040type = real_t * 20041(@value{GDBP}) ptype real_pointer_var 20042type = double * 20043@end group 20044@end smallexample 20045 20046@noindent 20047As with @code{whatis}, using @code{ptype} without an argument refers to 20048the type of @code{$}, the last value in the value history. 20049 20050@cindex incomplete type 20051Sometimes, programs use opaque data types or incomplete specifications 20052of complex data structure. If the debug information included in the 20053program does not allow @value{GDBN} to display a full declaration of 20054the data type, it will say @samp{<incomplete type>}. For example, 20055given these declarations: 20056 20057@smallexample 20058 struct foo; 20059 struct foo *fooptr; 20060@end smallexample 20061 20062@noindent 20063but no definition for @code{struct foo} itself, @value{GDBN} will say: 20064 20065@smallexample 20066 (@value{GDBP}) ptype foo 20067 $1 = <incomplete type> 20068@end smallexample 20069 20070@noindent 20071``Incomplete type'' is C terminology for data types that are not 20072completely specified. 20073 20074@cindex unknown type 20075Othertimes, information about a variable's type is completely absent 20076from the debug information included in the program. This most often 20077happens when the program or library where the variable is defined 20078includes no debug information at all. @value{GDBN} knows the variable 20079exists from inspecting the linker/loader symbol table (e.g., the ELF 20080dynamic symbol table), but such symbols do not contain type 20081information. Inspecting the type of a (global) variable for which 20082@value{GDBN} has no type information shows: 20083 20084@smallexample 20085 (@value{GDBP}) ptype var 20086 type = <data variable, no debug info> 20087@end smallexample 20088 20089@xref{Variables, no debug info variables}, for how to print the values 20090of such variables. 20091 20092@kindex info types 20093@item info types [-q] [@var{regexp}] 20094Print a brief description of all types whose names match the regular 20095expression @var{regexp} (or all types in your program, if you supply 20096no argument). Each complete typename is matched as though it were a 20097complete line; thus, @samp{i type value} gives information on all 20098types in your program whose names include the string @code{value}, but 20099@samp{i type ^value$} gives information only on types whose complete 20100name is @code{value}. 20101 20102In programs using different languages, @value{GDBN} chooses the syntax 20103to print the type description according to the 20104@samp{set language} value: using @samp{set language auto} 20105(see @ref{Automatically, ,Set Language Automatically}) means to use the 20106language of the type, other values mean to use 20107the manually specified language (see @ref{Manually, ,Set Language Manually}). 20108 20109This command differs from @code{ptype} in two ways: first, like 20110@code{whatis}, it does not print a detailed description; second, it 20111lists all source files and line numbers where a type is defined. 20112 20113The output from @samp{into types} is proceeded with a header line 20114describing what types are being listed. The optional flag @samp{-q}, 20115which stands for @samp{quiet}, disables printing this header 20116information. 20117 20118@kindex info type-printers 20119@item info type-printers 20120Versions of @value{GDBN} that ship with Python scripting enabled may 20121have ``type printers'' available. When using @command{ptype} or 20122@command{whatis}, these printers are consulted when the name of a type 20123is needed. @xref{Type Printing API}, for more information on writing 20124type printers. 20125 20126@code{info type-printers} displays all the available type printers. 20127 20128@kindex enable type-printer 20129@kindex disable type-printer 20130@item enable type-printer @var{name}@dots{} 20131@item disable type-printer @var{name}@dots{} 20132These commands can be used to enable or disable type printers. 20133 20134@kindex info scope 20135@cindex local variables 20136@item info scope @var{locspec} 20137List all the variables local to the lexical scope of the code location 20138that results from resolving @var{locspec}. @xref{Location 20139Specifications}, for details about supported forms of @var{locspec}. 20140For example: 20141 20142@smallexample 20143(@value{GDBP}) @b{info scope command_line_handler} 20144Scope for command_line_handler: 20145Symbol rl is an argument at stack/frame offset 8, length 4. 20146Symbol linebuffer is in static storage at address 0x150a18, length 4. 20147Symbol linelength is in static storage at address 0x150a1c, length 4. 20148Symbol p is a local variable in register $esi, length 4. 20149Symbol p1 is a local variable in register $ebx, length 4. 20150Symbol nline is a local variable in register $edx, length 4. 20151Symbol repeat is a local variable at frame offset -8, length 4. 20152@end smallexample 20153 20154@noindent 20155This command is especially useful for determining what data to collect 20156during a @dfn{trace experiment}, see @ref{Tracepoint Actions, 20157collect}. 20158 20159@kindex info source 20160@item info source 20161Show information about the current source file---that is, the source file for 20162the function containing the current point of execution: 20163@itemize @bullet 20164@item 20165the name of the source file, and the directory containing it, 20166@item 20167the directory it was compiled in, 20168@item 20169its length, in lines, 20170@item 20171which programming language it is written in, 20172@item 20173if the debug information provides it, the program that compiled the file 20174(which may include, e.g., the compiler version and command line arguments), 20175@item 20176whether the executable includes debugging information for that file, and 20177if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and 20178@item 20179whether the debugging information includes information about 20180preprocessor macros. 20181@end itemize 20182 20183 20184@kindex info sources 20185@item info sources @r{[}-dirname | -basename@r{]} @r{[}--@r{]} @r{[}@var{regexp}@r{]} 20186 20187 20188With no options @samp{info sources} prints the names of all source 20189files in your program for which there is debugging information. The 20190source files are presented based on a list of object files 20191(executables and libraries) currently loaded into @value{GDBN}. For 20192each object file all of the associated source files are listed. 20193 20194Each source file will only be printed once for each object file, but a 20195single source file can be repeated in the output if it is part of 20196multiple object files. 20197 20198If the optional @var{regexp} is provided, then only source files that 20199match the regular expression will be printed. The matching is 20200case-sensitive, except on operating systems that have case-insensitive 20201filesystem (e.g., MS-Windows). @samp{--} can be used before 20202@var{regexp} to prevent @value{GDBN} interpreting @var{regexp} as a 20203command option (e.g. if @var{regexp} starts with @samp{-}). 20204 20205By default, the @var{regexp} is used to match anywhere in the 20206filename. If @code{-dirname}, only files having a dirname matching 20207@var{regexp} are shown. If @code{-basename}, only files having a 20208basename matching @var{regexp} are shown. 20209 20210It is possible that an object file may be printed in the list with no 20211associated source files. This can happen when either no source files 20212match @var{regexp}, or, the object file was compiled without debug 20213information and so @value{GDBN} is unable to find any source file 20214names. 20215 20216@kindex info functions 20217@item info functions [-q] [-n] 20218Print the names and data types of all defined functions. 20219Similarly to @samp{info types}, this command groups its output by source 20220files and annotates each function definition with its source line 20221number. 20222 20223In programs using different languages, @value{GDBN} chooses the syntax 20224to print the function name and type according to the 20225@samp{set language} value: using @samp{set language auto} 20226(see @ref{Automatically, ,Set Language Automatically}) means to use the 20227language of the function, other values mean to use 20228the manually specified language (see @ref{Manually, ,Set Language Manually}). 20229 20230The @samp{-n} flag excludes @dfn{non-debugging symbols} from the 20231results. A non-debugging symbol is a symbol that comes from the 20232executable's symbol table, not from the debug information (for 20233example, DWARF) associated with the executable. 20234 20235The optional flag @samp{-q}, which stands for @samp{quiet}, disables 20236printing header information and messages explaining why no functions 20237have been printed. 20238 20239@item info functions [-q] [-n] [-t @var{type_regexp}] [@var{regexp}] 20240Like @samp{info functions}, but only print the names and data types 20241of the functions selected with the provided regexp(s). 20242 20243If @var{regexp} is provided, print only the functions whose names 20244match the regular expression @var{regexp}. 20245Thus, @samp{info fun step} finds all functions whose 20246names include @code{step}; @samp{info fun ^step} finds those whose names 20247start with @code{step}. If a function name contains characters that 20248conflict with the regular expression language (e.g.@: 20249@samp{operator*()}), they may be quoted with a backslash. 20250 20251If @var{type_regexp} is provided, print only the functions whose 20252types, as printed by the @code{whatis} command, match 20253the regular expression @var{type_regexp}. 20254If @var{type_regexp} contains space(s), it should be enclosed in 20255quote characters. If needed, use backslash to escape the meaning 20256of special characters or quotes. 20257Thus, @samp{info fun -t '^int ('} finds the functions that return 20258an integer; @samp{info fun -t '(.*int.*'} finds the functions that 20259have an argument type containing int; @samp{info fun -t '^int (' ^step} 20260finds the functions whose names start with @code{step} and that return 20261int. 20262 20263If both @var{regexp} and @var{type_regexp} are provided, a function 20264is printed only if its name matches @var{regexp} and its type matches 20265@var{type_regexp}. 20266 20267 20268@kindex info variables 20269@item info variables [-q] [-n] 20270Print the names and data types of all variables that are defined 20271outside of functions (i.e.@: excluding local variables). 20272The printed variables are grouped by source files and annotated with 20273their respective source line numbers. 20274 20275In programs using different languages, @value{GDBN} chooses the syntax 20276to print the variable name and type according to the 20277@samp{set language} value: using @samp{set language auto} 20278(see @ref{Automatically, ,Set Language Automatically}) means to use the 20279language of the variable, other values mean to use 20280the manually specified language (see @ref{Manually, ,Set Language Manually}). 20281 20282The @samp{-n} flag excludes non-debugging symbols from the results. 20283 20284The optional flag @samp{-q}, which stands for @samp{quiet}, disables 20285printing header information and messages explaining why no variables 20286have been printed. 20287 20288@item info variables [-q] [-n] [-t @var{type_regexp}] [@var{regexp}] 20289Like @kbd{info variables}, but only print the variables selected 20290with the provided regexp(s). 20291 20292If @var{regexp} is provided, print only the variables whose names 20293match the regular expression @var{regexp}. 20294 20295If @var{type_regexp} is provided, print only the variables whose 20296types, as printed by the @code{whatis} command, match 20297the regular expression @var{type_regexp}. 20298If @var{type_regexp} contains space(s), it should be enclosed in 20299quote characters. If needed, use backslash to escape the meaning 20300of special characters or quotes. 20301 20302If both @var{regexp} and @var{type_regexp} are provided, an argument 20303is printed only if its name matches @var{regexp} and its type matches 20304@var{type_regexp}. 20305 20306@kindex info modules 20307@cindex modules 20308@item info modules @r{[}-q@r{]} @r{[}@var{regexp}@r{]} 20309List all Fortran modules in the program, or all modules matching the 20310optional regular expression @var{regexp}. 20311 20312The optional flag @samp{-q}, which stands for @samp{quiet}, disables 20313printing header information and messages explaining why no modules 20314have been printed. 20315 20316@kindex info module 20317@cindex Fortran modules, information about 20318@cindex functions and variables by Fortran module 20319@cindex module functions and variables 20320@item info module functions @r{[}-q@r{]} @r{[}-m @var{module-regexp}@r{]} @r{[}-t @var{type-regexp}@r{]} @r{[}@var{regexp}@r{]} 20321@itemx info module variables @r{[}-q@r{]} @r{[}-m @var{module-regexp}@r{]} @r{[}-t @var{type-regexp}@r{]} @r{[}@var{regexp}@r{]} 20322List all functions or variables within all Fortran modules. The set 20323of functions or variables listed can be limited by providing some or 20324all of the optional regular expressions. If @var{module-regexp} is 20325provided, then only Fortran modules matching @var{module-regexp} will 20326be searched. Only functions or variables whose type matches the 20327optional regular expression @var{type-regexp} will be listed. And 20328only functions or variables whose name matches the optional regular 20329expression @var{regexp} will be listed. 20330 20331The optional flag @samp{-q}, which stands for @samp{quiet}, disables 20332printing header information and messages explaining why no functions 20333or variables have been printed. 20334 20335@kindex info main 20336@item info main 20337Print the name of the starting function of the program. This serves 20338primarily Fortran programs, which have a user-supplied name for the 20339main subroutine. 20340 20341@kindex info classes 20342@cindex Objective-C, classes and selectors 20343@item info classes 20344@itemx info classes @var{regexp} 20345Display all Objective-C classes in your program, or 20346(with the @var{regexp} argument) all those matching a particular regular 20347expression. 20348 20349@kindex info selectors 20350@item info selectors 20351@itemx info selectors @var{regexp} 20352Display all Objective-C selectors in your program, or 20353(with the @var{regexp} argument) all those matching a particular regular 20354expression. 20355 20356@ignore 20357This was never implemented. 20358@kindex info methods 20359@item info methods 20360@itemx info methods @var{regexp} 20361The @code{info methods} command permits the user to examine all defined 20362methods within C@t{++} program, or (with the @var{regexp} argument) a 20363specific set of methods found in the various C@t{++} classes. Many 20364C@t{++} classes provide a large number of methods. Thus, the output 20365from the @code{ptype} command can be overwhelming and hard to use. The 20366@code{info-methods} command filters the methods, printing only those 20367which match the regular-expression @var{regexp}. 20368@end ignore 20369 20370@cindex opaque data types 20371@kindex set opaque-type-resolution 20372@item set opaque-type-resolution on 20373Tell @value{GDBN} to resolve opaque types. An opaque type is a type 20374declared as a pointer to a @code{struct}, @code{class}, or 20375@code{union}---for example, @code{struct MyType *}---that is used in one 20376source file although the full declaration of @code{struct MyType} is in 20377another source file. The default is on. 20378 20379A change in the setting of this subcommand will not take effect until 20380the next time symbols for a file are loaded. 20381 20382@item set opaque-type-resolution off 20383Tell @value{GDBN} not to resolve opaque types. In this case, the type 20384is printed as follows: 20385@smallexample 20386@{<no data fields>@} 20387@end smallexample 20388 20389@kindex show opaque-type-resolution 20390@item show opaque-type-resolution 20391Show whether opaque types are resolved or not. 20392 20393@kindex set print symbol-loading 20394@cindex print messages when symbols are loaded 20395@item set print symbol-loading 20396@itemx set print symbol-loading full 20397@itemx set print symbol-loading brief 20398@itemx set print symbol-loading off 20399The @code{set print symbol-loading} command allows you to control the 20400printing of messages when @value{GDBN} loads symbol information. 20401By default a message is printed for the executable and one for each 20402shared library, and normally this is what you want. However, when 20403debugging apps with large numbers of shared libraries these messages 20404can be annoying. 20405When set to @code{brief} a message is printed for each executable, 20406and when @value{GDBN} loads a collection of shared libraries at once 20407it will only print one message regardless of the number of shared 20408libraries. When set to @code{off} no messages are printed. 20409 20410@kindex show print symbol-loading 20411@item show print symbol-loading 20412Show whether messages will be printed when a @value{GDBN} command 20413entered from the keyboard causes symbol information to be loaded. 20414 20415@kindex maint print symbols 20416@cindex symbol dump 20417@kindex maint print psymbols 20418@cindex partial symbol dump 20419@kindex maint print msymbols 20420@cindex minimal symbol dump 20421@item maint print symbols @r{[}-pc @var{address}@r{]} @r{[}@var{filename}@r{]} 20422@itemx maint print symbols @r{[}-objfile @var{objfile}@r{]} @r{[}-source @var{source}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]} 20423@itemx maint print psymbols @r{[}-objfile @var{objfile}@r{]} @r{[}-pc @var{address}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]} 20424@itemx maint print psymbols @r{[}-objfile @var{objfile}@r{]} @r{[}-source @var{source}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]} 20425@itemx maint print msymbols @r{[}-objfile @var{objfile}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]} 20426Write a dump of debugging symbol data into the file @var{filename} or 20427the terminal if @var{filename} is unspecified. 20428If @code{-objfile @var{objfile}} is specified, only dump symbols for 20429that objfile. 20430If @code{-pc @var{address}} is specified, only dump symbols for the file 20431with code at that address. Note that @var{address} may be a symbol like 20432@code{main}. 20433If @code{-source @var{source}} is specified, only dump symbols for that 20434source file. 20435 20436These commands are used to debug the @value{GDBN} symbol-reading code. 20437These commands do not modify internal @value{GDBN} state, therefore 20438@samp{maint print symbols} will only print symbols for already expanded symbol 20439tables. 20440You can use the command @code{info sources} to find out which files these are. 20441If you use @samp{maint print psymbols} instead, the dump shows information 20442about symbols that @value{GDBN} only knows partially---that is, symbols 20443defined in files that @value{GDBN} has skimmed, but not yet read completely. 20444Finally, @samp{maint print msymbols} just dumps ``minimal symbols'', e.g., 20445``ELF symbols''. 20446 20447@xref{Files, ,Commands to Specify Files}, for a discussion of how 20448@value{GDBN} reads symbols (in the description of @code{symbol-file}). 20449 20450@kindex maint info symtabs 20451@kindex maint info psymtabs 20452@cindex listing @value{GDBN}'s internal symbol tables 20453@cindex symbol tables, listing @value{GDBN}'s internal 20454@cindex full symbol tables, listing @value{GDBN}'s internal 20455@cindex partial symbol tables, listing @value{GDBN}'s internal 20456@item maint info symtabs @r{[} @var{regexp} @r{]} 20457@itemx maint info psymtabs @r{[} @var{regexp} @r{]} 20458 20459List the @code{struct symtab} or @code{struct partial_symtab} 20460structures whose names match @var{regexp}. If @var{regexp} is not 20461given, list them all. The output includes expressions which you can 20462copy into a @value{GDBN} debugging this one to examine a particular 20463structure in more detail. For example: 20464 20465@smallexample 20466(@value{GDBP}) maint info psymtabs dwarf2read 20467@{ objfile /home/gnu/build/gdb/gdb 20468 ((struct objfile *) 0x82e69d0) 20469 @{ psymtab /home/gnu/src/gdb/dwarf2read.c 20470 ((struct partial_symtab *) 0x8474b10) 20471 readin no 20472 fullname (null) 20473 text addresses 0x814d3c8 -- 0x8158074 20474 globals (* (struct partial_symbol **) 0x8507a08 @@ 9) 20475 statics (* (struct partial_symbol **) 0x40e95b78 @@ 2882) 20476 dependencies (none) 20477 @} 20478@} 20479(@value{GDBP}) maint info symtabs 20480(@value{GDBP}) 20481@end smallexample 20482@noindent 20483We see that there is one partial symbol table whose filename contains 20484the string @samp{dwarf2read}, belonging to the @samp{gdb} executable; 20485and we see that @value{GDBN} has not read in any symtabs yet at all. 20486If we set a breakpoint on a function, that will cause @value{GDBN} to 20487read the symtab for the compilation unit containing that function: 20488 20489@smallexample 20490(@value{GDBP}) break dwarf2_psymtab_to_symtab 20491Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, 20492line 1574. 20493(@value{GDBP}) maint info symtabs 20494@{ objfile /home/gnu/build/gdb/gdb 20495 ((struct objfile *) 0x82e69d0) 20496 @{ symtab /home/gnu/src/gdb/dwarf2read.c 20497 ((struct symtab *) 0x86c1f38) 20498 dirname (null) 20499 fullname (null) 20500 blockvector ((struct blockvector *) 0x86c1bd0) (primary) 20501 linetable ((struct linetable *) 0x8370fa0) 20502 debugformat DWARF 2 20503 @} 20504@} 20505(@value{GDBP}) 20506@end smallexample 20507 20508@kindex maint info line-table 20509@cindex listing @value{GDBN}'s internal line tables 20510@cindex line tables, listing @value{GDBN}'s internal 20511@item maint info line-table @r{[} @var{regexp} @r{]} 20512 20513List the @code{struct linetable} from all @code{struct symtab} 20514instances whose name matches @var{regexp}. If @var{regexp} is not 20515given, list the @code{struct linetable} from all @code{struct symtab}. 20516For example: 20517 20518@smallexample 20519(@value{GDBP}) maint info line-table 20520objfile: /home/gnu/build/a.out ((struct objfile *) 0x6120000e0d40) 20521compunit_symtab: simple.cpp ((struct compunit_symtab *) 0x6210000ff450) 20522symtab: /home/gnu/src/simple.cpp ((struct symtab *) 0x6210000ff4d0) 20523linetable: ((struct linetable *) 0x62100012b760): 20524INDEX LINE ADDRESS IS-STMT PROLOGUE-END EPILOGUE-BEGIN 205250 3 0x0000000000401110 Y 205261 4 0x0000000000401114 Y Y Y 205272 9 0x0000000000401120 Y 205283 10 0x0000000000401124 Y Y 205294 10 0x0000000000401129 Y Y 205305 15 0x0000000000401130 Y 205316 16 0x0000000000401134 Y Y 205327 16 0x0000000000401139 205338 21 0x0000000000401140 Y Y 205349 22 0x000000000040114f Y Y 2053510 22 0x0000000000401154 Y 2053611 END 0x000000000040115a Y 20537@end smallexample 20538@noindent 20539The @samp{IS-STMT} column indicates if the address is a recommended breakpoint 20540location to represent a line or a statement. The @samp{PROLOGUE-END} column 20541indicates that a given address is an adequate place to set a breakpoint at the 20542first instruction following a function prologue. The @samp{EPILOGUE-BEGIN} 20543column indicates that a given address marks the point where a block's frame is 20544destroyed, making local variables hard or impossible to find. 20545 20546@kindex set always-read-ctf [on|off] 20547@kindex show always-read-ctf 20548@cindex always-read-ctf 20549@cindex CTF info, when to read 20550@item set always-read-ctf [on|off] 20551@itemx show always-read-ctf 20552 20553When off, CTF debug info is only read if DWARF debug info is not 20554present. When on, CTF debug info is read regardless of whether DWARF 20555debug info is present. The default value is off. 20556 20557@kindex maint set symbol-cache-size 20558@cindex symbol cache size 20559@item maint set symbol-cache-size @var{size} 20560Set the size of the symbol cache to @var{size}. 20561The default size is intended to be good enough for debugging 20562most applications. This option exists to allow for experimenting 20563with different sizes. 20564 20565@kindex maint show symbol-cache-size 20566@item maint show symbol-cache-size 20567Show the size of the symbol cache. 20568 20569@kindex maint print symbol-cache 20570@cindex symbol cache, printing its contents 20571@item maint print symbol-cache 20572Print the contents of the symbol cache. 20573This is useful when debugging symbol cache issues. 20574 20575@kindex maint print symbol-cache-statistics 20576@cindex symbol cache, printing usage statistics 20577@item maint print symbol-cache-statistics 20578Print symbol cache usage statistics. 20579This helps determine how well the cache is being utilized. 20580 20581@kindex maint flush symbol-cache 20582@kindex maint flush-symbol-cache 20583@cindex symbol cache, flushing 20584@item maint flush symbol-cache 20585@itemx maint flush-symbol-cache 20586Flush the contents of the symbol cache, all entries are removed. This 20587command is useful when debugging the symbol cache. It is also useful 20588when collecting performance data. The command @code{maint 20589flush-symbol-cache} is deprecated in favor of @code{maint flush 20590symbol-cache}.. 20591 20592@kindex maint set ignore-prologue-end-flag 20593@cindex prologue-end 20594@item maint set ignore-prologue-end-flag [on|off] 20595Enable or disable the use of the @samp{PROLOGUE-END} flag from the line-table. 20596When @samp{off} (the default), @value{GDBN} uses the @samp{PROLOGUE-END} flag 20597to place breakpoints past the end of a function prologue. When @samp{on}, 20598@value{GDBN} ignores the flag and relies on prologue analyzers to skip function 20599prologues. 20600 20601@kindex maint show ignore-prologue-end-flag 20602@item maint show ignore-prologue-end-flag 20603Show whether @value{GDBN} will ignore the @samp{PROLOGUE-END} flag. 20604 20605@end table 20606 20607@node Altering 20608@chapter Altering Execution 20609 20610Once you think you have found an error in your program, you might want to 20611find out for certain whether correcting the apparent error would lead to 20612correct results in the rest of the run. You can find the answer by 20613experiment, using the @value{GDBN} features for altering execution of the 20614program. 20615 20616For example, you can store new values into variables or memory 20617locations, give your program a signal, restart it at a different 20618address, or even return prematurely from a function. 20619 20620@menu 20621* Assignment:: Assignment to variables 20622* Jumping:: Continuing at a different address 20623* Signaling:: Giving your program a signal 20624* Returning:: Returning from a function 20625* Calling:: Calling your program's functions 20626* Patching:: Patching your program 20627* Compiling and Injecting Code:: Compiling and injecting code in @value{GDBN} 20628@end menu 20629 20630@node Assignment 20631@section Assignment to Variables 20632 20633@cindex assignment 20634@cindex setting variables 20635To alter the value of a variable, evaluate an assignment expression. 20636@xref{Expressions, ,Expressions}. For example, 20637 20638@smallexample 20639print x=4 20640@end smallexample 20641 20642@noindent 20643stores the value 4 into the variable @code{x}, and then prints the 20644value of the assignment expression (which is 4). 20645@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more 20646information on operators in supported languages. 20647 20648@kindex set variable 20649@cindex variables, setting 20650If you are not interested in seeing the value of the assignment, use the 20651@code{set} command instead of the @code{print} command. @code{set} is 20652really the same as @code{print} except that the expression's value is 20653not printed and is not put in the value history (@pxref{Value History, 20654,Value History}). The expression is evaluated only for its effects. 20655 20656If the beginning of the argument string of the @code{set} command 20657appears identical to a @code{set} subcommand, use the @code{set 20658variable} command instead of just @code{set}. This command is identical 20659to @code{set} except for its lack of subcommands. For example, if your 20660program has a variable @code{width}, you get an error if you try to set 20661a new value with just @samp{set width=13}, because @value{GDBN} has the 20662command @code{set width}: 20663 20664@smallexample 20665(@value{GDBP}) whatis width 20666type = double 20667(@value{GDBP}) p width 20668$4 = 13 20669(@value{GDBP}) set width=47 20670Invalid syntax in expression. 20671@end smallexample 20672 20673@noindent 20674The invalid expression, of course, is @samp{=47}. In 20675order to actually set the program's variable @code{width}, use 20676 20677@smallexample 20678(@value{GDBP}) set var width=47 20679@end smallexample 20680 20681Because the @code{set} command has many subcommands that can conflict 20682with the names of program variables, it is a good idea to use the 20683@code{set variable} command instead of just @code{set}. For example, if 20684your program has a variable @code{g}, you run into problems if you try 20685to set a new value with just @samp{set g=4}, because @value{GDBN} has 20686the command @code{set gnutarget}, abbreviated @code{set g}: 20687 20688@smallexample 20689@group 20690(@value{GDBP}) whatis g 20691type = double 20692(@value{GDBP}) p g 20693$1 = 1 20694(@value{GDBP}) set g=4 20695(@value{GDBP}) p g 20696$2 = 1 20697(@value{GDBP}) r 20698The program being debugged has been started already. 20699Start it from the beginning? (y or n) y 20700Starting program: /home/smith/cc_progs/a.out 20701"/home/smith/cc_progs/a.out": can't open to read symbols: 20702 Invalid bfd target. 20703(@value{GDBP}) show g 20704The current BFD target is "=4". 20705@end group 20706@end smallexample 20707 20708@noindent 20709The program variable @code{g} did not change, and you silently set the 20710@code{gnutarget} to an invalid value. In order to set the variable 20711@code{g}, use 20712 20713@smallexample 20714(@value{GDBP}) set var g=4 20715@end smallexample 20716 20717@value{GDBN} allows more implicit conversions in assignments than C; you can 20718freely store an integer value into a pointer variable or vice versa, 20719and you can convert any structure to any other structure that is the 20720same length or shorter. 20721@comment FIXME: how do structs align/pad in these conversions? 20722@comment /doc@cygnus.com 18dec1990 20723 20724To store values into arbitrary places in memory, use the @samp{@{@dots{}@}} 20725construct to generate a value of specified type at a specified address 20726(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers 20727to memory location @code{0x83040} as an integer (which implies a certain size 20728and representation in memory), and 20729 20730@smallexample 20731set @{int@}0x83040 = 4 20732@end smallexample 20733 20734@noindent 20735stores the value 4 into that memory location. 20736 20737@node Jumping 20738@section Continuing at a Different Address 20739 20740Ordinarily, when you continue your program, you do so at the place where 20741it stopped, with the @code{continue} command. You can instead continue at 20742an address of your own choosing, with the following commands: 20743 20744@table @code 20745@kindex jump 20746@kindex j @r{(@code{jump})} 20747@item jump @var{locspec} 20748@itemx j @var{locspec} 20749Resume execution at the address of the code location that results from 20750resolving @var{locspec}. 20751@xref{Location Specifications}, for a description of the different 20752forms of @var{locspec}. If @var{locspec} resolves to more than one address, 20753those outside the current compilation unit are ignored. If considering just 20754the addresses in the current compilation unit still doesn't yield a unique 20755address, the command aborts before jumping. 20756Execution stops again immediately if there is a breakpoint there. It 20757is common practice to use the @code{tbreak} command in conjunction 20758with @code{jump}. @xref{Set Breaks, ,Setting Breakpoints}. 20759 20760The @code{jump} command does not change the current stack frame, or 20761the stack pointer, or the contents of any memory location or any 20762register other than the program counter. If @var{locspec} resolves to 20763an address in a different function from the one currently executing, the 20764results may be bizarre if the two functions expect different patterns 20765of arguments or of local variables. For this reason, the @code{jump} 20766command requests confirmation if the jump address is not in the 20767function currently executing. However, even bizarre results are 20768predictable if you are well acquainted with the machine-language code 20769of your program. 20770@end table 20771 20772On many systems, you can get much the same effect as the @code{jump} 20773command by storing a new value into the register @code{$pc}. The 20774difference is that this does not start your program running; it only 20775changes the address of where it @emph{will} run when you continue. For 20776example, 20777 20778@smallexample 20779set $pc = 0x485 20780@end smallexample 20781 20782@noindent 20783makes the next @code{continue} command or stepping command execute at 20784address @code{0x485}, rather than at the address where your program stopped. 20785@xref{Continuing and Stepping, ,Continuing and Stepping}. 20786 20787However, writing directly to @code{$pc} will only change the value of 20788the program-counter register, while using @code{jump} will ensure that 20789any additional auxiliary state is also updated. For example, on 20790SPARC, @code{jump} will update both @code{$pc} and @code{$npc} 20791registers prior to resuming execution. When using the approach of 20792writing directly to @code{$pc} it is your job to also update the 20793@code{$npc} register. 20794 20795The most common occasion to use the @code{jump} command is to back 20796up---perhaps with more breakpoints set---over a portion of a program 20797that has already executed, in order to examine its execution in more 20798detail. 20799 20800@c @group 20801@node Signaling 20802@section Giving your Program a Signal 20803@cindex deliver a signal to a program 20804 20805@table @code 20806@kindex signal 20807@item signal @var{signal} 20808Resume execution where your program is stopped, but immediately give it the 20809signal @var{signal}. The @var{signal} can be the name or the number of a 20810signal. For example, on many systems @code{signal 2} and @code{signal 20811SIGINT} are both ways of sending an interrupt signal. 20812 20813Alternatively, if @var{signal} is zero, continue execution without 20814giving a signal. This is useful when your program stopped on account of 20815a signal and would ordinarily see the signal when resumed with the 20816@code{continue} command; @samp{signal 0} causes it to resume without a 20817signal. 20818 20819@emph{Note:} When resuming a multi-threaded program, @var{signal} is 20820delivered to the currently selected thread, not the thread that last 20821reported a stop. This includes the situation where a thread was 20822stopped due to a signal. So if you want to continue execution 20823suppressing the signal that stopped a thread, you should select that 20824same thread before issuing the @samp{signal 0} command. If you issue 20825the @samp{signal 0} command with another thread as the selected one, 20826@value{GDBN} detects that and asks for confirmation. 20827 20828Invoking the @code{signal} command is not the same as invoking the 20829@code{kill} utility from the shell. Sending a signal with @code{kill} 20830causes @value{GDBN} to decide what to do with the signal depending on 20831the signal handling tables (@pxref{Signals}). The @code{signal} command 20832passes the signal directly to your program. 20833 20834@code{signal} does not repeat when you press @key{RET} a second time 20835after executing the command. 20836 20837@kindex queue-signal 20838@item queue-signal @var{signal} 20839Queue @var{signal} to be delivered immediately to the current thread 20840when execution of the thread resumes. The @var{signal} can be the name or 20841the number of a signal. For example, on many systems @code{signal 2} and 20842@code{signal SIGINT} are both ways of sending an interrupt signal. 20843The handling of the signal must be set to pass the signal to the program, 20844otherwise @value{GDBN} will report an error. 20845You can control the handling of signals from @value{GDBN} with the 20846@code{handle} command (@pxref{Signals}). 20847 20848Alternatively, if @var{signal} is zero, any currently queued signal 20849for the current thread is discarded and when execution resumes no signal 20850will be delivered. This is useful when your program stopped on account 20851of a signal and would ordinarily see the signal when resumed with the 20852@code{continue} command. 20853 20854This command differs from the @code{signal} command in that the signal 20855is just queued, execution is not resumed. And @code{queue-signal} cannot 20856be used to pass a signal whose handling state has been set to @code{nopass} 20857(@pxref{Signals}). 20858@end table 20859@c @end group 20860 20861@xref{stepping into signal handlers}, for information on how stepping 20862commands behave when the thread has a signal queued. 20863 20864@node Returning 20865@section Returning from a Function 20866 20867@table @code 20868@cindex returning from a function 20869@kindex return 20870@item return 20871@itemx return @var{expression} 20872You can cancel execution of a function call with the @code{return} 20873command. If you give an 20874@var{expression} argument, its value is used as the function's return 20875value. 20876@end table 20877 20878When you use @code{return}, @value{GDBN} discards the selected stack frame 20879(and all frames within it). You can think of this as making the 20880discarded frame return prematurely. If you wish to specify a value to 20881be returned, give that value as the argument to @code{return}. 20882 20883This pops the selected stack frame (@pxref{Selection, ,Selecting a 20884Frame}), and any other frames inside of it, leaving its caller as the 20885innermost remaining frame. That frame becomes selected. The 20886specified value is stored in the registers used for returning values 20887of functions. 20888 20889The @code{return} command does not resume execution; it leaves the 20890program stopped in the state that would exist if the function had just 20891returned. In contrast, the @code{finish} command (@pxref{Continuing 20892and Stepping, ,Continuing and Stepping}) resumes execution until the 20893selected stack frame returns naturally. 20894 20895@value{GDBN} needs to know how the @var{expression} argument should be set for 20896the inferior. The concrete registers assignment depends on the OS ABI and the 20897type being returned by the selected stack frame. For example it is common for 20898OS ABI to return floating point values in FPU registers while integer values in 20899CPU registers. Still some ABIs return even floating point values in CPU 20900registers. Larger integer widths (such as @code{long long int}) also have 20901specific placement rules. @value{GDBN} already knows the OS ABI from its 20902current target so it needs to find out also the type being returned to make the 20903assignment into the right register(s). 20904 20905Normally, the selected stack frame has debug info. @value{GDBN} will always 20906use the debug info instead of the implicit type of @var{expression} when the 20907debug info is available. For example, if you type @kbd{return -1}, and the 20908function in the current stack frame is declared to return a @code{long long 20909int}, @value{GDBN} transparently converts the implicit @code{int} value of -1 20910into a @code{long long int}: 20911 20912@smallexample 20913Breakpoint 1, func () at gdb.base/return-nodebug.c:29 2091429 return 31; 20915(@value{GDBP}) return -1 20916Make func return now? (y or n) y 20917#0 0x004004f6 in main () at gdb.base/return-nodebug.c:43 2091843 printf ("result=%lld\n", func ()); 20919(@value{GDBP}) 20920@end smallexample 20921 20922However, if the selected stack frame does not have a debug info, e.g., if the 20923function was compiled without debug info, @value{GDBN} has to find out the type 20924to return from user. Specifying a different type by mistake may set the value 20925in different inferior registers than the caller code expects. For example, 20926typing @kbd{return -1} with its implicit type @code{int} would set only a part 20927of a @code{long long int} result for a debug info less function (on 32-bit 20928architectures). Therefore the user is required to specify the return type by 20929an appropriate cast explicitly: 20930 20931@smallexample 20932Breakpoint 2, 0x0040050b in func () 20933(@value{GDBP}) return -1 20934Return value type not available for selected stack frame. 20935Please use an explicit cast of the value to return. 20936(@value{GDBP}) return (long long int) -1 20937Make selected stack frame return now? (y or n) y 20938#0 0x00400526 in main () 20939(@value{GDBP}) 20940@end smallexample 20941 20942@node Calling 20943@section Calling Program Functions 20944 20945@table @code 20946@cindex calling functions 20947@cindex inferior functions, calling 20948@item print @var{expr} 20949Evaluate the expression @var{expr} and display the resulting value. 20950The expression may include calls to functions in the program being 20951debugged. 20952 20953@kindex call 20954@item call @var{expr} 20955Evaluate the expression @var{expr} without displaying @code{void} 20956returned values. 20957 20958You can use this variant of the @code{print} command if you want to 20959execute a function from your program that does not return anything 20960(a.k.a.@: @dfn{a void function}), but without cluttering the output 20961with @code{void} returned values that @value{GDBN} will otherwise 20962print. If the result is not void, it is printed and saved in the 20963value history. 20964@end table 20965 20966It is possible for the function you call via the @code{print} or 20967@code{call} command to generate a signal (e.g., if there's a bug in 20968the function, or if you passed it incorrect arguments). What happens 20969in that case is controlled by the @code{set unwind-on-signal} command. 20970 20971Similarly, with a C@t{++} program it is possible for the function you 20972call via the @code{print} or @code{call} command to generate an 20973exception that is not handled due to the constraints of the dummy 20974frame. In this case, any exception that is raised in the frame, but has 20975an out-of-frame exception handler will not be found. GDB builds a 20976dummy-frame for the inferior function call, and the unwinder cannot 20977seek for exception handlers outside of this dummy-frame. What happens 20978in that case is controlled by the 20979@code{set unwind-on-terminating-exception} command. 20980 20981@anchor{stack unwind settings} 20982@table @code 20983@item set unwind-on-signal 20984@kindex set unwind-on-signal 20985@kindex set unwindonsignal 20986@cindex unwind stack in called functions 20987@cindex call dummy stack unwinding 20988Set unwinding of the stack if a signal is received while in a function 20989that @value{GDBN} called in the program being debugged. If set to on, 20990@value{GDBN} unwinds the stack it created for the call and restores 20991the context to what it was before the call. If set to off (the 20992default), @value{GDBN} stops in the frame where the signal was 20993received. 20994 20995The command @code{set unwindonsignal} is an alias for this command, 20996and is maintained for backward compatibility. 20997 20998@item show unwind-on-signal 20999@kindex show unwind-on-signal 21000@kindex show unwindonsignal 21001Show the current setting of stack unwinding in the functions called by 21002@value{GDBN}. 21003 21004The command @code{show unwindonsignal} is an alias for this command, 21005and is maintained for backward compatibility. 21006 21007@item set unwind-on-terminating-exception 21008@kindex set unwind-on-terminating-exception 21009@cindex unwind stack in called functions with unhandled exceptions 21010@cindex call dummy stack unwinding on unhandled exception. 21011Set unwinding of the stack if a C@t{++} exception is raised, but left 21012unhandled while in a function that @value{GDBN} called in the program being 21013debugged. If set to on (the default), @value{GDBN} unwinds the stack 21014it created for the call and restores the context to what it was before 21015the call. If set to off, @value{GDBN} the exception is delivered to 21016the default C@t{++} exception handler and the inferior terminated. 21017 21018@item show unwind-on-terminating-exception 21019@kindex show unwind-on-terminating-exception 21020Show the current setting of stack unwinding in the functions called by 21021@value{GDBN}. 21022 21023@anchor{set unwind-on-timeout} 21024@item set unwind-on-timeout 21025@kindex set unwind-on-timeout 21026@cindex unwind stack in called functions when timing out 21027@cindex call dummy stack unwinding on timeout. 21028Set unwinding of the stack if a function called from @value{GDBN} 21029times out. If set to @code{off} (the default), @value{GDBN} stops in 21030the frame where the timeout occurred. If set to @code{on}, 21031@value{GDBN} unwinds the stack it created for the call and restores 21032the context to what it was before the call. 21033 21034@item show unwind-on-timeout 21035@kindex show unwind-on-timeout 21036Show whether @value{GDBN} will unwind the stack if a function called 21037from @value{GDBN} times out. 21038 21039@item set may-call-functions 21040@kindex set may-call-functions 21041@cindex disabling calling functions in the program 21042@cindex calling functions in the program, disabling 21043Set permission to call functions in the program. 21044This controls whether @value{GDBN} will attempt to call functions in 21045the program, such as with expressions in the @code{print} command. It 21046defaults to @code{on}. 21047 21048To call a function in the program, @value{GDBN} has to temporarily 21049modify the state of the inferior. This has potentially undesired side 21050effects. Also, having @value{GDBN} call nested functions is likely to 21051be erroneous and may even crash the program being debugged. You can 21052avoid such hazards by forbidding @value{GDBN} from calling functions 21053in the program being debugged. If calling functions in the program 21054is forbidden, GDB will throw an error when a command (such as printing 21055an expression) starts a function call in the program. 21056 21057@item show may-call-functions 21058@kindex show may-call-functions 21059Show permission to call functions in the program. 21060 21061@end table 21062 21063When calling a function within a program, it is possible that the 21064program could enter a state from which the called function may never 21065return. If this happens then it is possible to interrupt the function 21066call by typing the interrupt character (often @kbd{Ctrl-c}). 21067 21068If a called function is interrupted for any reason, including hitting 21069a breakpoint, or triggering a watchpoint, and the stack is not unwound 21070due to @code{set unwind-on-terminating-exception on}, @code{set 21071unwind-on-timeout on}, or @code{set unwind-on-signal on} (@pxref{stack 21072unwind settings}), then the dummy-frame, created by @value{GDBN} to 21073facilitate the call to the program function, will be visible in the 21074backtrace, for example frame @code{#3} in the following backtrace: 21075 21076@smallexample 21077(@value{GDBP}) backtrace 21078#0 0x00007ffff7b3d1e7 in nanosleep () from /lib64/libc.so.6 21079#1 0x00007ffff7b3d11e in sleep () from /lib64/libc.so.6 21080#2 0x000000000040113f in deadlock () at test.cc:13 21081#3 <function called from gdb> 21082#4 breakpt () at test.cc:20 21083#5 0x0000000000401151 in main () at test.cc:25 21084@end smallexample 21085 21086At this point it is possible to examine the state of the inferior just 21087like any other stop. 21088 21089Depending on why the function was interrupted then it may be possible 21090to resume the inferior (using commands like @code{continue}, 21091@code{step}, etc). In this case, when the inferior finally returns to 21092the dummy-frame, @value{GDBN} will once again halt the inferior. 21093 21094On targets that support asynchronous execution (@pxref{Background 21095Execution}) @value{GDBN} can place a timeout on any functions called 21096from @value{GDBN}. If the timeout expires and the function call is 21097still ongoing, then @value{GDBN} will interrupt the program. 21098 21099If a function called from @value{GDBN} is interrupted by a timeout, 21100then by default the inferior is left in the frame where the timeout 21101occurred, this behaviour can be adjusted with @samp{set 21102unwind-on-timeout} (@pxref{set unwind-on-timeout}). 21103 21104For targets that don't support asynchronous execution 21105(@pxref{Background Execution}) then timeouts for functions called from 21106@value{GDBN} are not supported, the timeout settings described below 21107will be treated as @code{unlimited}, meaning @value{GDBN} will wait 21108indefinitely for function call to complete, unless interrupted by the 21109user using @kbd{Ctrl-C}. 21110 21111@table @code 21112@item set direct-call-timeout @var{seconds} 21113@kindex set direct-call-timeout 21114@cindex timeout for called functions 21115Set the timeout used when calling functions in the program to 21116@var{seconds}, which should be an integer greater than zero, or the 21117special value @code{unlimited}, which indicates no timeout should be 21118used. The default for this setting is @code{unlimited}. 21119 21120This setting is used when the user calls a function directly from the 21121command prompt, for example with a @code{call} or @code{print} 21122command. 21123 21124This setting only works for targets that support asynchronous 21125execution (@pxref{Background Execution}), for any other target the 21126setting is treated as @code{unlimited}. 21127 21128@item show direct-call-timeout 21129@kindex show direct-call-timeout 21130@cindex timeout for called functions 21131Show the timeout used when calling functions in the program with a 21132@code{call} or @code{print} command. 21133@end table 21134 21135It is also possible to call functions within the program from the 21136condition of a conditional breakpoint (@pxref{Conditions, ,Break 21137Conditions}). A different setting controls the timeout used for 21138function calls made from a breakpoint condition. 21139 21140@table @code 21141@item set indirect-call-timeout @var{seconds} 21142@kindex set indirect-call-timeout 21143@cindex timeout for called functions 21144Set the timeout used when calling functions in the program from a 21145breakpoint or watchpoint condition to @var{seconds}, which should be 21146an integer greater than zero, or the special value @code{unlimited}, 21147which indicates no timeout should be used. The default for this 21148setting is @code{30} seconds. 21149 21150This setting only works for targets that support asynchronous 21151execution (@pxref{Background Execution}), for any other target the 21152setting is treated as @code{unlimited}. 21153 21154If a function called from a breakpoint or watchpoint condition times 21155out, then @value{GDBN} will stop at the point where the timeout 21156occurred. The breakpoint condition evaluation will be abandoned. 21157 21158@item show indirect-call-timeout 21159@kindex show indirect-call-timeout 21160@cindex timeout for called functions 21161Show the timeout used when calling functions in the program from a 21162breakpoint or watchpoint condition. 21163@end table 21164 21165@subsection Calling functions with no debug info 21166 21167@cindex no debug info functions 21168Sometimes, a function you wish to call is missing debug information. 21169In such case, @value{GDBN} does not know the type of the function, 21170including the types of the function's parameters. To avoid calling 21171the inferior function incorrectly, which could result in the called 21172function functioning erroneously and even crash, @value{GDBN} refuses 21173to call the function unless you tell it the type of the function. 21174 21175For prototyped (i.e.@: ANSI/ISO style) functions, there are two ways 21176to do that. The simplest is to cast the call to the function's 21177declared return type. For example: 21178 21179@smallexample 21180(@value{GDBP}) p getenv ("PATH") 21181'getenv' has unknown return type; cast the call to its declared return type 21182(@value{GDBP}) p (char *) getenv ("PATH") 21183$1 = 0x7fffffffe7ba "/usr/local/bin:/"... 21184@end smallexample 21185 21186Casting the return type of a no-debug function is equivalent to 21187casting the function to a pointer to a prototyped function that has a 21188prototype that matches the types of the passed-in arguments, and 21189calling that. I.e., the call above is equivalent to: 21190 21191@smallexample 21192(@value{GDBP}) p ((char * (*) (const char *)) getenv) ("PATH") 21193@end smallexample 21194 21195@noindent 21196and given this prototyped C or C++ function with float parameters: 21197 21198@smallexample 21199float multiply (float v1, float v2) @{ return v1 * v2; @} 21200@end smallexample 21201 21202@noindent 21203these calls are equivalent: 21204 21205@smallexample 21206(@value{GDBP}) p (float) multiply (2.0f, 3.0f) 21207(@value{GDBP}) p ((float (*) (float, float)) multiply) (2.0f, 3.0f) 21208@end smallexample 21209 21210If the function you wish to call is declared as unprototyped (i.e.@: 21211old K&R style), you must use the cast-to-function-pointer syntax, so 21212that @value{GDBN} knows that it needs to apply default argument 21213promotions (promote float arguments to double). @xref{ABI, float 21214promotion}. For example, given this unprototyped C function with 21215float parameters, and no debug info: 21216 21217@smallexample 21218float 21219multiply_noproto (v1, v2) 21220 float v1, v2; 21221@{ 21222 return v1 * v2; 21223@} 21224@end smallexample 21225 21226@noindent 21227you call it like this: 21228 21229@smallexample 21230 (@value{GDBP}) p ((float (*) ()) multiply_noproto) (2.0f, 3.0f) 21231@end smallexample 21232 21233@node Patching 21234@section Patching Programs 21235 21236@cindex patching binaries 21237@cindex writing into executables 21238@cindex writing into corefiles 21239 21240By default, @value{GDBN} opens the file containing your program's 21241executable code (or the corefile) read-only. This prevents accidental 21242alterations to machine code; but it also prevents you from intentionally 21243patching your program's binary. 21244 21245If you'd like to be able to patch the binary, you can specify that 21246explicitly with the @code{set write} command. For example, you might 21247want to turn on internal debugging flags, or even to make emergency 21248repairs. 21249 21250@table @code 21251@kindex set write 21252@item set write on 21253@itemx set write off 21254If you specify @samp{set write on}, @value{GDBN} opens executable and 21255core files for both reading and writing; if you specify @kbd{set write 21256off} (the default), @value{GDBN} opens them read-only. 21257 21258If you have already loaded a file, you must load it again (using the 21259@code{exec-file} or @code{core-file} command) after changing @code{set 21260write}, for your new setting to take effect. 21261 21262@item show write 21263@kindex show write 21264Display whether executable files and core files are opened for writing 21265as well as reading. 21266@end table 21267 21268@node Compiling and Injecting Code 21269@section Compiling and injecting code in @value{GDBN} 21270@cindex injecting code 21271@cindex writing into executables 21272@cindex compiling code 21273 21274@value{GDBN} supports on-demand compilation and code injection into 21275programs running under @value{GDBN}. GCC 5.0 or higher built with 21276@file{libcc1.so} must be installed for this functionality to be enabled. 21277This functionality is implemented with the following commands. 21278 21279@table @code 21280@kindex compile code 21281@item compile code @var{source-code} 21282@itemx compile code -raw @var{--} @var{source-code} 21283Compile @var{source-code} with the compiler language found as the current 21284language in @value{GDBN} (@pxref{Languages}). If compilation and 21285injection is not supported with the current language specified in 21286@value{GDBN}, or the compiler does not support this feature, an error 21287message will be printed. If @var{source-code} compiles and links 21288successfully, @value{GDBN} will load the object-code emitted, 21289and execute it within the context of the currently selected inferior. 21290It is important to note that the compiled code is executed immediately. 21291After execution, the compiled code is removed from @value{GDBN} and any 21292new types or variables you have defined will be deleted. 21293 21294The command allows you to specify @var{source-code} in two ways. 21295The simplest method is to provide a single line of code to the command. 21296E.g.: 21297 21298@smallexample 21299compile code printf ("hello world\n"); 21300@end smallexample 21301 21302If you specify options on the command line as well as source code, they 21303may conflict. The @samp{--} delimiter can be used to separate options 21304from actual source code. E.g.: 21305 21306@smallexample 21307compile code -r -- printf ("hello world\n"); 21308@end smallexample 21309 21310Alternatively you can enter source code as multiple lines of text. To 21311enter this mode, invoke the @samp{compile code} command without any text 21312following the command. This will start the multiple-line editor and 21313allow you to type as many lines of source code as required. When you 21314have completed typing, enter @samp{end} on its own line to exit the 21315editor. 21316 21317@smallexample 21318compile code 21319>printf ("hello\n"); 21320>printf ("world\n"); 21321>end 21322@end smallexample 21323 21324Specifying @samp{-raw}, prohibits @value{GDBN} from wrapping the 21325provided @var{source-code} in a callable scope. In this case, you must 21326specify the entry point of the code by defining a function named 21327@code{_gdb_expr_}. The @samp{-raw} code cannot access variables of the 21328inferior. Using @samp{-raw} option may be needed for example when 21329@var{source-code} requires @samp{#include} lines which may conflict with 21330inferior symbols otherwise. 21331 21332@kindex compile file 21333@item compile file @var{filename} 21334@itemx compile file -raw @var{filename} 21335Like @code{compile code}, but take the source code from @var{filename}. 21336 21337@smallexample 21338compile file /home/user/example.c 21339@end smallexample 21340@end table 21341 21342@table @code 21343@item compile print [[@var{options}] --] @var{expr} 21344@itemx compile print [[@var{options}] --] /@var{f} @var{expr} 21345Compile and execute @var{expr} with the compiler language found as the 21346current language in @value{GDBN} (@pxref{Languages}). By default the 21347value of @var{expr} is printed in a format appropriate to its data type; 21348you can choose a different format by specifying @samp{/@var{f}}, where 21349@var{f} is a letter specifying the format; see @ref{Output Formats,,Output 21350Formats}. The @code{compile print} command accepts the same options 21351as the @code{print} command; see @ref{print options}. 21352 21353@item compile print [[@var{options}] --] 21354@itemx compile print [[@var{options}] --] /@var{f} 21355@cindex reprint the last value 21356Alternatively you can enter the expression (source code producing it) as 21357multiple lines of text. To enter this mode, invoke the @samp{compile print} 21358command without any text following the command. This will start the 21359multiple-line editor. 21360@end table 21361 21362@noindent 21363The process of compiling and injecting the code can be inspected using: 21364 21365@table @code 21366@anchor{set debug compile} 21367@item set debug compile 21368@cindex compile command debugging info 21369Turns on or off display of @value{GDBN} process of compiling and 21370injecting the code. The default is off. 21371 21372@item show debug compile 21373Displays the current state of displaying @value{GDBN} process of 21374compiling and injecting the code. 21375 21376@anchor{set debug compile-cplus-types} 21377@item set debug compile-cplus-types 21378@cindex compile C@t{++} type conversion 21379Turns on or off the display of C@t{++} type conversion debugging information. 21380The default is off. 21381 21382@item show debug compile-cplus-types 21383Displays the current state of displaying debugging information for 21384C@t{++} type conversion. 21385@end table 21386 21387@subsection Compilation options for the @code{compile} command 21388 21389@value{GDBN} needs to specify the right compilation options for the code 21390to be injected, in part to make its ABI compatible with the inferior 21391and in part to make the injected code compatible with @value{GDBN}'s 21392injecting process. 21393 21394@noindent 21395The options used, in increasing precedence: 21396 21397@table @asis 21398@item target architecture and OS options (@code{gdbarch}) 21399These options depend on target processor type and target operating 21400system, usually they specify at least 32-bit (@code{-m32}) or 64-bit 21401(@code{-m64}) compilation option. 21402 21403@item compilation options recorded in the target 21404@value{NGCC} (since version 4.7) stores the options used for compilation 21405into @code{DW_AT_producer} part of DWARF debugging information according 21406to the @value{NGCC} option @code{-grecord-gcc-switches}. One has to 21407explicitly specify @code{-g} during inferior compilation otherwise 21408@value{NGCC} produces no DWARF. This feature is only relevant for 21409platforms where @code{-g} produces DWARF by default, otherwise one may 21410try to enforce DWARF by using @code{-gdwarf-4}. 21411 21412@item compilation options set by @code{set compile-args} 21413@end table 21414 21415@noindent 21416You can override compilation options using the following command: 21417 21418@table @code 21419@item set compile-args 21420@cindex compile command options override 21421Set compilation options used for compiling and injecting code with the 21422@code{compile} commands. These options override any conflicting ones 21423from the target architecture and/or options stored during inferior 21424compilation. 21425 21426@item show compile-args 21427Displays the current state of compilation options override. 21428This does not show all the options actually used during compilation, 21429use @ref{set debug compile} for that. 21430@end table 21431 21432@subsection Caveats when using the @code{compile} command 21433 21434There are a few caveats to keep in mind when using the @code{compile} 21435command. As the caveats are different per language, the table below 21436highlights specific issues on a per language basis. 21437 21438@table @asis 21439@item C code examples and caveats 21440When the language in @value{GDBN} is set to @samp{C}, the compiler will 21441attempt to compile the source code with a @samp{C} compiler. The source 21442code provided to the @code{compile} command will have much the same 21443access to variables and types as it normally would if it were part of 21444the program currently being debugged in @value{GDBN}. 21445 21446Below is a sample program that forms the basis of the examples that 21447follow. This program has been compiled and loaded into @value{GDBN}, 21448much like any other normal debugging session. 21449 21450@smallexample 21451void function1 (void) 21452@{ 21453 int i = 42; 21454 printf ("function 1\n"); 21455@} 21456 21457void function2 (void) 21458@{ 21459 int j = 12; 21460 function1 (); 21461@} 21462 21463int main(void) 21464@{ 21465 int k = 6; 21466 int *p; 21467 function2 (); 21468 return 0; 21469@} 21470@end smallexample 21471 21472For the purposes of the examples in this section, the program above has 21473been compiled, loaded into @value{GDBN}, stopped at the function 21474@code{main}, and @value{GDBN} is awaiting input from the user. 21475 21476To access variables and types for any program in @value{GDBN}, the 21477program must be compiled and packaged with debug information. The 21478@code{compile} command is not an exception to this rule. Without debug 21479information, you can still use the @code{compile} command, but you will 21480be very limited in what variables and types you can access. 21481 21482So with that in mind, the example above has been compiled with debug 21483information enabled. The @code{compile} command will have access to 21484all variables and types (except those that may have been optimized 21485out). Currently, as @value{GDBN} has stopped the program in the 21486@code{main} function, the @code{compile} command would have access to 21487the variable @code{k}. You could invoke the @code{compile} command 21488and type some source code to set the value of @code{k}. You can also 21489read it, or do anything with that variable you would normally do in 21490@code{C}. Be aware that changes to inferior variables in the 21491@code{compile} command are persistent. In the following example: 21492 21493@smallexample 21494compile code k = 3; 21495@end smallexample 21496 21497@noindent 21498the variable @code{k} is now 3. It will retain that value until 21499something else in the example program changes it, or another 21500@code{compile} command changes it. 21501 21502Normal scope and access rules apply to source code compiled and 21503injected by the @code{compile} command. In the example, the variables 21504@code{j} and @code{k} are not accessible yet, because the program is 21505currently stopped in the @code{main} function, where these variables 21506are not in scope. Therefore, the following command 21507 21508@smallexample 21509compile code j = 3; 21510@end smallexample 21511 21512@noindent 21513will result in a compilation error message. 21514 21515Once the program is continued, execution will bring these variables in 21516scope, and they will become accessible; then the code you specify via 21517the @code{compile} command will be able to access them. 21518 21519You can create variables and types with the @code{compile} command as 21520part of your source code. Variables and types that are created as part 21521of the @code{compile} command are not visible to the rest of the program for 21522the duration of its run. This example is valid: 21523 21524@smallexample 21525compile code int ff = 5; printf ("ff is %d\n", ff); 21526@end smallexample 21527 21528However, if you were to type the following into @value{GDBN} after that 21529command has completed: 21530 21531@smallexample 21532compile code printf ("ff is %d\n'', ff); 21533@end smallexample 21534 21535@noindent 21536a compiler error would be raised as the variable @code{ff} no longer 21537exists. Object code generated and injected by the @code{compile} 21538command is removed when its execution ends. Caution is advised 21539when assigning to program variables values of variables created by the 21540code submitted to the @code{compile} command. This example is valid: 21541 21542@smallexample 21543compile code int ff = 5; k = ff; 21544@end smallexample 21545 21546The value of the variable @code{ff} is assigned to @code{k}. The variable 21547@code{k} does not require the existence of @code{ff} to maintain the value 21548it has been assigned. However, pointers require particular care in 21549assignment. If the source code compiled with the @code{compile} command 21550changed the address of a pointer in the example program, perhaps to a 21551variable created in the @code{compile} command, that pointer would point 21552to an invalid location when the command exits. The following example 21553would likely cause issues with your debugged program: 21554 21555@smallexample 21556compile code int ff = 5; p = &ff; 21557@end smallexample 21558 21559In this example, @code{p} would point to @code{ff} when the 21560@code{compile} command is executing the source code provided to it. 21561However, as variables in the (example) program persist with their 21562assigned values, the variable @code{p} would point to an invalid 21563location when the command exists. A general rule should be followed 21564in that you should either assign @code{NULL} to any assigned pointers, 21565or restore a valid location to the pointer before the command exits. 21566 21567Similar caution must be exercised with any structs, unions, and typedefs 21568defined in @code{compile} command. Types defined in the @code{compile} 21569command will no longer be available in the next @code{compile} command. 21570Therefore, if you cast a variable to a type defined in the 21571@code{compile} command, care must be taken to ensure that any future 21572need to resolve the type can be achieved. 21573 21574@smallexample 21575(@value{GDBP}) compile code static struct a @{ int a; @} v = @{ 42 @}; argv = &v; 21576(@value{GDBP}) compile code printf ("%d\n", ((struct a *) argv)->a); 21577gdb command line:1:36: error: dereferencing pointer to incomplete type ‘struct a’ 21578Compilation failed. 21579(@value{GDBP}) compile code struct a @{ int a; @}; printf ("%d\n", ((struct a *) argv)->a); 2158042 21581@end smallexample 21582 21583Variables that have been optimized away by the compiler are not 21584accessible to the code submitted to the @code{compile} command. 21585Access to those variables will generate a compiler error which @value{GDBN} 21586will print to the console. 21587@end table 21588 21589@subsection Compiler search for the @code{compile} command 21590 21591@value{GDBN} needs to find @value{NGCC} for the inferior being debugged 21592which may not be obvious for remote targets of different architecture 21593than where @value{GDBN} is running. Environment variable @env{PATH} on 21594@value{GDBN} host is searched for @value{NGCC} binary matching the 21595target architecture and operating system. This search can be overridden 21596by @code{set compile-gcc} @value{GDBN} command below. @env{PATH} is 21597taken from shell that executed @value{GDBN}, it is not the value set by 21598@value{GDBN} command @code{set environment}). @xref{Environment}. 21599 21600 21601Specifically @env{PATH} is searched for binaries matching regular expression 21602@code{@var{arch}(-[^-]*)?-@var{os}-gcc} according to the inferior target being 21603debugged. @var{arch} is processor name --- multiarch is supported, so for 21604example both @code{i386} and @code{x86_64} targets look for pattern 21605@code{(x86_64|i.86)} and both @code{s390} and @code{s390x} targets look 21606for pattern @code{s390x?}. @var{os} is currently supported only for 21607pattern @code{linux(-gnu)?}. 21608 21609On Posix hosts the compiler driver @value{GDBN} needs to find also 21610shared library @file{libcc1.so} from the compiler. It is searched in 21611default shared library search path (overridable with usual environment 21612variable @env{LD_LIBRARY_PATH}), unrelated to @env{PATH} or @code{set 21613compile-gcc} settings. Contrary to it @file{libcc1plugin.so} is found 21614according to the installation of the found compiler --- as possibly 21615specified by the @code{set compile-gcc} command. 21616 21617@table @code 21618@item set compile-gcc 21619@cindex compile command driver filename override 21620Set compilation command used for compiling and injecting code with the 21621@code{compile} commands. If this option is not set (it is set to 21622an empty string), the search described above will occur --- that is the 21623default. 21624 21625@item show compile-gcc 21626Displays the current compile command @value{NGCC} driver filename. 21627If set, it is the main command @command{gcc}, found usually for example 21628under name @file{x86_64-linux-gnu-gcc}. 21629@end table 21630 21631@node GDB Files 21632@chapter @value{GDBN} Files 21633 21634@value{GDBN} needs to know the file name of the program to be debugged, 21635both in order to read its symbol table and in order to start your 21636program. To debug a core dump of a previous run, you must also tell 21637@value{GDBN} the name of the core dump file. 21638 21639@menu 21640* Files:: Commands to specify files 21641* File Caching:: Information about @value{GDBN}'s file caching 21642* Separate Debug Files:: Debugging information in separate files 21643* MiniDebugInfo:: Debugging information in a special section 21644* Index Files:: Index files speed up GDB 21645* Debug Names:: Extensions to .debug_names 21646* Symbol Errors:: Errors reading symbol files 21647* Data Files:: GDB data files 21648@end menu 21649 21650@node Files 21651@section Commands to Specify Files 21652 21653@cindex symbol table 21654@cindex core dump file 21655 21656You may want to specify executable and core dump file names. The usual 21657way to do this is at start-up time, using the arguments to 21658@value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and 21659Out of @value{GDBN}}). 21660 21661Occasionally it is necessary to change to a different file during a 21662@value{GDBN} session. Or you may run @value{GDBN} and forget to 21663specify a file you want to use. Or you are debugging a remote target 21664via @code{gdbserver} (@pxref{Server, file, Using the @code{gdbserver} 21665Program}). In these situations the @value{GDBN} commands to specify 21666new files are useful. 21667 21668@table @code 21669@cindex executable file 21670@kindex file 21671@item file @var{filename} 21672Use @var{filename} as the program to be debugged. It is read for its 21673symbols and for the contents of pure memory. It is also the program 21674executed when you use the @code{run} command. If you do not specify a 21675directory and the file is not found in the @value{GDBN} working directory, 21676@value{GDBN} uses the environment variable @env{PATH} as a list of 21677directories to search, just as the shell does when looking for a program 21678to run. You can change the value of this variable, for both @value{GDBN} 21679and your program, using the @code{path} command. 21680 21681The @var{filename} argument supports escaping and quoting, see 21682@ref{Filename Arguments,,Filenames As Command Arguments}. 21683 21684@cindex unlinked object files 21685@cindex patching object files 21686You can load unlinked object @file{.o} files into @value{GDBN} using 21687the @code{file} command. You will not be able to ``run'' an object 21688file, but you can disassemble functions and inspect variables. Also, 21689if the underlying BFD functionality supports it, you could use 21690@kbd{gdb -write} to patch object files using this technique. Note 21691that @value{GDBN} can neither interpret nor modify relocations in this 21692case, so branches and some initialized variables will appear to go to 21693the wrong place. But this feature is still handy from time to time. 21694 21695@item file 21696@code{file} with no argument makes @value{GDBN} discard any information it 21697has on both executable file and the symbol table. 21698 21699@kindex exec-file 21700@item exec-file @r{[} @var{filename} @r{]} 21701Specify that the program to be run (but not the symbol table) is found 21702in @var{filename}. @value{GDBN} searches the environment variable @env{PATH} 21703if necessary to locate your program. Omitting @var{filename} means to 21704discard information on the executable file. 21705 21706The @var{filename} argument supports escaping and quoting, see 21707@ref{Filename Arguments,,Filenames As Command Arguments}. 21708 21709@kindex symbol-file 21710@item symbol-file @r{[} @var{filename} @r{[} -o @var{offset} @r{]]} 21711Read symbol table information from file @var{filename}. @env{PATH} is 21712searched when necessary. Use the @code{file} command to get both symbol 21713table and program to run from the same file. 21714 21715If an optional @var{offset} is specified, it is added to the start 21716address of each section in the symbol file. This is useful if the 21717program is relocated at runtime, such as the Linux kernel with kASLR 21718enabled. 21719 21720@code{symbol-file} with no argument clears out @value{GDBN} information on your 21721program's symbol table. 21722 21723The @code{symbol-file} command causes @value{GDBN} to forget the contents of 21724some breakpoints and auto-display expressions. This is because they may 21725contain pointers to the internal data recording symbols and data types, 21726which are part of the old symbol table data being discarded inside 21727@value{GDBN}. 21728 21729@code{symbol-file} does not repeat if you press @key{RET} again after 21730executing it once. 21731 21732The @var{filename} argument supports escaping and quoting, see 21733@ref{Filename Arguments,,Filenames As Command Arguments}. 21734 21735When @value{GDBN} is configured for a particular environment, it 21736understands debugging information in whatever format is the standard 21737generated for that environment; you may use either a @sc{gnu} compiler, or 21738other compilers that adhere to the local conventions. 21739Best results are usually obtained from @sc{gnu} compilers; for example, 21740using @code{@value{NGCC}} you can generate debugging information for 21741optimized code. 21742 21743For most kinds of object files, with the exception of old SVR3 systems 21744using COFF, the @code{symbol-file} command does not normally read the 21745symbol table in full right away. Instead, it scans the symbol table 21746quickly to find which source files and which symbols are present. The 21747details are read later, one source file at a time, as they are needed. 21748 21749The purpose of this two-stage reading strategy is to make @value{GDBN} 21750start up faster. For the most part, it is invisible except for 21751occasional pauses while the symbol table details for a particular source 21752file are being read. (The @code{set verbose} command can turn these 21753pauses into messages if desired. @xref{Messages/Warnings, ,Optional 21754Warnings and Messages}.) 21755 21756We have not implemented the two-stage strategy for COFF yet. When the 21757symbol table is stored in COFF format, @code{symbol-file} reads the 21758symbol table data in full right away. Note that ``stabs-in-COFF'' 21759still does the two-stage strategy, since the debug info is actually 21760in stabs format. 21761 21762@kindex readnow 21763@cindex reading symbols immediately 21764@cindex symbols, reading immediately 21765@item symbol-file @r{[} -readnow @r{]} @var{filename} 21766@itemx file @r{[} -readnow @r{]} @var{filename} 21767You can override the @value{GDBN} two-stage strategy for reading symbol 21768tables by using the @samp{-readnow} option with any of the commands that 21769load symbol table information, if you want to be sure @value{GDBN} has the 21770entire symbol table available. 21771 21772@cindex @code{-readnever}, option for symbol-file command 21773@cindex never read symbols 21774@cindex symbols, never read 21775@item symbol-file @r{[} -readnever @r{]} @var{filename} 21776@itemx file @r{[} -readnever @r{]} @var{filename} 21777You can instruct @value{GDBN} to never read the symbolic information 21778contained in @var{filename} by using the @samp{-readnever} option. 21779@xref{--readnever}. 21780 21781@c FIXME: for now no mention of directories, since this seems to be in 21782@c flux. 13mar1992 status is that in theory GDB would look either in 21783@c current dir or in same dir as myprog; but issues like competing 21784@c GDB's, or clutter in system dirs, mean that in practice right now 21785@c only current dir is used. FFish says maybe a special GDB hierarchy 21786@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol 21787@c files. 21788 21789@kindex core-file 21790@item core-file @r{[}@var{filename}@r{]} 21791@itemx core 21792Specify the whereabouts of a core dump file to be used as the ``contents 21793of memory''. Traditionally, core files contain only some parts of the 21794address space of the process that generated them; @value{GDBN} can access the 21795executable file itself for other parts. 21796 21797@code{core-file} with no argument specifies that no core file is 21798to be used. 21799 21800Note that the core file is ignored when your program is actually running 21801under @value{GDBN}. So, if you have been running your program and you 21802wish to debug a core file instead, you must kill the subprocess in which 21803the program is running. To do this, use the @code{kill} command 21804(@pxref{Kill Process, ,Killing the Child Process}). 21805 21806@kindex add-symbol-file 21807@cindex dynamic linking 21808@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{]} 21809The @code{add-symbol-file} command reads additional symbol table 21810information from the file @var{filename}. You would use this command 21811when @var{filename} has been dynamically loaded (by some other means) 21812into the program that is running. The @var{textaddress} parameter gives 21813the memory address at which the file's text section has been loaded. 21814You can additionally specify the base address of other sections using 21815an arbitrary number of @samp{-s @var{section} @var{address}} pairs. 21816If a section is omitted, @value{GDBN} will use its default addresses 21817as found in @var{filename}. Any @var{address} or @var{textaddress} 21818can be given as an expression. 21819 21820If an optional @var{offset} is specified, it is added to the start 21821address of each section, except those for which the address was 21822specified explicitly. 21823 21824The symbol table of the file @var{filename} is added to the symbol table 21825originally read with the @code{symbol-file} command. You can use the 21826@code{add-symbol-file} command any number of times; the new symbol data 21827thus read is kept in addition to the old. 21828 21829The @var{filename} argument supports escaping and quoting, see 21830@ref{Filename Arguments,,Filenames As Command Arguments}. 21831 21832Changes can be reverted using the command @code{remove-symbol-file}. 21833 21834@cindex relocatable object files, reading symbols from 21835@cindex object files, relocatable, reading symbols from 21836@cindex reading symbols from relocatable object files 21837@cindex symbols, reading from relocatable object files 21838@cindex @file{.o} files, reading symbols from 21839Although @var{filename} is typically a shared library file, an 21840executable file, or some other object file which has been fully 21841relocated for loading into a process, you can also load symbolic 21842information from relocatable @file{.o} files, as long as: 21843 21844@itemize @bullet 21845@item 21846the file's symbolic information refers only to linker symbols defined in 21847that file, not to symbols defined by other object files, 21848@item 21849every section the file's symbolic information refers to has actually 21850been loaded into the inferior, as it appears in the file, and 21851@item 21852you can determine the address at which every section was loaded, and 21853provide these to the @code{add-symbol-file} command. 21854@end itemize 21855 21856@noindent 21857Some embedded operating systems, like Sun Chorus and VxWorks, can load 21858relocatable files into an already running program; such systems 21859typically make the requirements above easy to meet. However, it's 21860important to recognize that many native systems use complex link 21861procedures (@code{.linkonce} section factoring and C@t{++} constructor table 21862assembly, for example) that make the requirements difficult to meet. In 21863general, one cannot assume that using @code{add-symbol-file} to read a 21864relocatable object file's symbolic information will have the same effect 21865as linking the relocatable object file into the program in the normal 21866way. 21867 21868@code{add-symbol-file} does not repeat if you press @key{RET} after using it. 21869 21870@kindex remove-symbol-file 21871@item remove-symbol-file @var{filename} 21872@item remove-symbol-file -a @var{address} 21873Remove a symbol file added via the @code{add-symbol-file} command. The 21874file to remove can be identified by its @var{filename} or by an @var{address} 21875that lies within the boundaries of this symbol file in memory. Example: 21876 21877@smallexample 21878(@value{GDBP}) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480 21879add symbol table from file "/home/user/gdb/mylib.so" at 21880 .text_addr = 0x7ffff7ff9480 21881(y or n) y 21882Reading symbols from /home/user/gdb/mylib.so... 21883(@value{GDBP}) remove-symbol-file -a 0x7ffff7ff9480 21884Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y 21885(@value{GDBP}) 21886@end smallexample 21887 21888 21889@code{remove-symbol-file} does not repeat if you press @key{RET} after using it. 21890 21891The @var{filename} argument supports escaping and quoting, see 21892@ref{Filename Arguments,,Filenames As Command Arguments}. 21893 21894@kindex add-symbol-file-from-memory 21895@cindex @code{syscall DSO} 21896@cindex load symbols from memory 21897@item add-symbol-file-from-memory @var{address} 21898Load symbols from the given @var{address} in a dynamically loaded 21899object file whose image is mapped directly into the inferior's memory. 21900For example, the Linux kernel maps a @code{syscall DSO} into each 21901process's address space; this DSO provides kernel-specific code for 21902some system calls. The argument can be any expression whose 21903evaluation yields the address of the file's shared object file header. 21904For this command to work, you must have used @code{symbol-file} or 21905@code{exec-file} commands in advance. 21906 21907@kindex section 21908@item section @var{section} @var{addr} 21909The @code{section} command changes the base address of the named 21910@var{section} of the exec file to @var{addr}. This can be used if the 21911exec file does not contain section addresses, (such as in the 21912@code{a.out} format), or when the addresses specified in the file 21913itself are wrong. Each section must be changed separately. The 21914@code{info files} command, described below, lists all the sections and 21915their addresses. 21916 21917@kindex info files 21918@kindex info target 21919@item info files 21920@itemx info target 21921@code{info files} and @code{info target} are synonymous; both print the 21922current target (@pxref{Targets, ,Specifying a Debugging Target}), 21923including the names of the executable and core dump files currently in 21924use by @value{GDBN}, and the files from which symbols were loaded. The 21925command @code{help target} lists all possible targets rather than 21926current ones. 21927 21928@kindex maint info sections 21929@item maint info sections @r{[}-all-objects@r{]} @r{[}@var{filter-list}@r{]} 21930Another command that can give you extra information about program sections 21931is @code{maint info sections}. In addition to the section information 21932displayed by @code{info files}, this command displays the flags and file 21933offset of each section in the executable and core dump files. 21934 21935When @samp{-all-objects} is passed then sections from all loaded object 21936files, including shared libraries, are printed. 21937 21938The optional @var{filter-list} is a space separated list of filter 21939keywords. Sections that match any one of the filter criteria will be 21940printed. There are two types of filter: 21941 21942@table @code 21943@item @var{section-name} 21944Display information about any section named @var{section-name}. 21945@item @var{section-flag} 21946Display information for any section with @var{section-flag}. The 21947section flags that @value{GDBN} currently knows about are: 21948@table @code 21949@item ALLOC 21950Section will have space allocated in the process when loaded. 21951Set for all sections except those containing debug information. 21952@item LOAD 21953Section will be loaded from the file into the child process memory. 21954Set for pre-initialized code and data, clear for @code{.bss} sections. 21955@item RELOC 21956Section needs to be relocated before loading. 21957@item READONLY 21958Section cannot be modified by the child process. 21959@item CODE 21960Section contains executable code only. 21961@item DATA 21962Section contains data only (no executable code). 21963@item ROM 21964Section will reside in ROM. 21965@item CONSTRUCTOR 21966Section contains data for constructor/destructor lists. 21967@item HAS_CONTENTS 21968Section is not empty. 21969@item NEVER_LOAD 21970An instruction to the linker to not output the section. 21971@item COFF_SHARED_LIBRARY 21972A notification to the linker that the section contains 21973COFF shared library information. 21974@item IS_COMMON 21975Section contains common symbols. 21976@end table 21977@end table 21978 21979@kindex maint info target-sections 21980@item maint info target-sections 21981This command prints @value{GDBN}'s internal section table. For each 21982target @value{GDBN} maintains a table containing the allocatable 21983sections from all currently mapped objects, along with information 21984about where the section is mapped. 21985 21986@kindex set trust-readonly-sections 21987@cindex read-only sections 21988@item set trust-readonly-sections on 21989Tell @value{GDBN} that readonly sections in your object file 21990really are read-only (i.e.@: that their contents will not change). 21991In that case, @value{GDBN} can fetch values from these sections 21992out of the object file, rather than from the target program. 21993For some targets (notably embedded ones), this can be a significant 21994enhancement to debugging performance. 21995 21996The default is off. 21997 21998@item set trust-readonly-sections off 21999Tell @value{GDBN} not to trust readonly sections. This means that 22000the contents of the section might change while the program is running, 22001and must therefore be fetched from the target when needed. 22002 22003@item show trust-readonly-sections 22004Show the current setting of trusting readonly sections. 22005@end table 22006 22007All file-specifying commands allow both absolute and relative file names 22008as arguments. @value{GDBN} always converts the file name to an absolute file 22009name and remembers it that way. 22010 22011@cindex shared libraries 22012@anchor{Shared Libraries} 22013@value{GDBN} supports @sc{gnu}/Linux, MS-Windows, SunOS, 22014Darwin/Mach-O, SVr4, IBM RS/6000 AIX, QNX Neutrino, FDPIC (FR-V), and 22015DSBT (TIC6X) shared libraries. 22016 22017On MS-Windows @value{GDBN} must be linked with the Expat library to support 22018shared libraries. @xref{Expat}. 22019 22020@value{GDBN} automatically loads symbol definitions from shared libraries 22021when you use the @code{run} command, or when you examine a core file. 22022(Before you issue the @code{run} command, @value{GDBN} does not understand 22023references to a function in a shared library, however---unless you are 22024debugging a core file). 22025 22026@c FIXME: some @value{GDBN} release may permit some refs to undef 22027@c FIXME...symbols---eg in a break cmd---assuming they are from a shared 22028@c FIXME...lib; check this from time to time when updating manual 22029 22030There are times, however, when you may wish to not automatically load 22031symbol definitions from shared libraries, such as when they are 22032particularly large or there are many of them. 22033 22034To control the automatic loading of shared library symbols, use the 22035commands: 22036 22037@table @code 22038@kindex set auto-solib-add 22039@item set auto-solib-add @var{mode} 22040If @var{mode} is @code{on}, symbols from all shared object libraries 22041will be loaded automatically when the inferior begins execution, you 22042attach to an independently started inferior, or when the dynamic linker 22043informs @value{GDBN} that a new library has been loaded. If @var{mode} 22044is @code{off}, symbols must be loaded manually, using the 22045@code{sharedlibrary} command. The default value is @code{on}. 22046 22047@cindex memory used for symbol tables 22048If your program uses lots of shared libraries with debug info that 22049takes large amounts of memory, you can decrease the @value{GDBN} 22050memory footprint by preventing it from automatically loading the 22051symbols from shared libraries. To that end, type @kbd{set 22052auto-solib-add off} before running the inferior, then load each 22053library whose debug symbols you do need with @kbd{sharedlibrary 22054@var{regexp}}, where @var{regexp} is a regular expression that matches 22055the libraries whose symbols you want to be loaded. 22056 22057@kindex show auto-solib-add 22058@item show auto-solib-add 22059Display the current autoloading mode. 22060@end table 22061 22062@cindex load shared library 22063To explicitly load shared library symbols, use the @code{sharedlibrary} 22064command: 22065 22066@table @code 22067@kindex info sharedlibrary 22068@kindex info share 22069@item info share @var{regex} 22070@itemx info sharedlibrary @var{regex} 22071Print the names of the shared libraries which are currently loaded 22072that match @var{regex}. If @var{regex} is omitted then print 22073all shared libraries that are loaded. 22074 22075@kindex info dll 22076@item info dll @var{regex} 22077This is an alias of @code{info sharedlibrary}. 22078 22079@kindex sharedlibrary 22080@kindex share 22081@item sharedlibrary @var{regex} 22082@itemx share @var{regex} 22083Load shared object library symbols for files matching a 22084Unix regular expression. 22085As with files loaded automatically, it only loads shared libraries 22086required by your program for a core file or after typing @code{run}. If 22087@var{regex} is omitted all shared libraries required by your program are 22088loaded. 22089 22090@item nosharedlibrary 22091@kindex nosharedlibrary 22092@cindex unload symbols from shared libraries 22093Unload all shared object library symbols. This discards all symbols 22094that have been loaded from all shared libraries. Symbols from shared 22095libraries that were loaded by explicit user requests are not 22096discarded. 22097@end table 22098 22099Sometimes you may wish that @value{GDBN} stops and gives you control 22100when any of shared library events happen. The best way to do this is 22101to use @code{catch load} and @code{catch unload} (@pxref{Set 22102Catchpoints}). 22103 22104@value{GDBN} also supports the @code{set stop-on-solib-events} 22105command for this. This command exists for historical reasons. It is 22106less useful than setting a catchpoint, because it does not allow for 22107conditions or commands as a catchpoint does. 22108 22109@table @code 22110@item set stop-on-solib-events 22111@kindex set stop-on-solib-events 22112This command controls whether @value{GDBN} should give you control 22113when the dynamic linker notifies it about some shared library event. 22114The most common event of interest is loading or unloading of a new 22115shared library. 22116 22117@item show stop-on-solib-events 22118@kindex show stop-on-solib-events 22119Show whether @value{GDBN} stops and gives you control when shared 22120library events happen. 22121@end table 22122 22123Shared libraries are also supported in many cross or remote debugging 22124configurations. @value{GDBN} needs to have access to the target's libraries; 22125this can be accomplished either by providing copies of the libraries 22126on the host system, or by asking @value{GDBN} to automatically retrieve the 22127libraries from the target. If copies of the target libraries are 22128provided, they need to be the same as the target libraries, although the 22129copies on the target can be stripped as long as the copies on the host are 22130not. 22131 22132@cindex where to look for shared libraries 22133For remote debugging, you need to tell @value{GDBN} where the target 22134libraries are, so that it can load the correct copies---otherwise, it 22135may try to load the host's libraries. @value{GDBN} has two variables 22136to specify the search directories for target libraries. 22137 22138@table @code 22139@cindex prefix for executable and shared library file names 22140@cindex system root, alternate 22141@kindex set solib-absolute-prefix 22142@kindex set sysroot 22143@item set sysroot @var{path} 22144Use @var{path} as the system root for the program being debugged. Any 22145absolute shared library paths will be prefixed with @var{path}; many 22146runtime loaders store the absolute paths to the shared library in the 22147target program's memory. When starting processes remotely, and when 22148attaching to already-running processes (local or remote), their 22149executable filenames will be prefixed with @var{path} if reported to 22150@value{GDBN} as absolute by the operating system. If you use 22151@code{set sysroot} to find executables and shared libraries, they need 22152to be laid out in the same way that they are on the target, with 22153e.g.@: a @file{/bin}, @file{/lib} and @file{/usr/lib} hierarchy under 22154@var{path}. 22155 22156If @var{path} starts with the sequence @file{target:} and the target 22157system is remote then @value{GDBN} will retrieve the target binaries 22158from the remote system. This is only supported when using a remote 22159target that supports the @code{remote get} command (@pxref{File 22160Transfer,,Sending files to a remote system}). The part of @var{path} 22161following the initial @file{target:} (if present) is used as system 22162root prefix on the remote file system. If @var{path} starts with the 22163sequence @file{remote:} this is converted to the sequence 22164@file{target:} by @code{set sysroot}@footnote{Historically the 22165functionality to retrieve binaries from the remote system was 22166provided by prefixing @var{path} with @file{remote:}}. If you want 22167to specify a local system root using a directory that happens to be 22168named @file{target:} or @file{remote:}, you need to use some 22169equivalent variant of the name like @file{./target:}. 22170 22171For targets with an MS-DOS based filesystem, such as MS-Windows, 22172@value{GDBN} tries prefixing a few variants of the target 22173absolute file name with @var{path}. But first, on Unix hosts, 22174@value{GDBN} converts all backslash directory separators into forward 22175slashes, because the backslash is not a directory separator on Unix: 22176 22177@smallexample 22178 c:\foo\bar.dll @result{} c:/foo/bar.dll 22179@end smallexample 22180 22181Then, @value{GDBN} attempts prefixing the target file name with 22182@var{path}, and looks for the resulting file name in the host file 22183system: 22184 22185@smallexample 22186 c:/foo/bar.dll @result{} /path/to/sysroot/c:/foo/bar.dll 22187@end smallexample 22188 22189If that does not find the binary, @value{GDBN} tries removing 22190the @samp{:} character from the drive spec, both for convenience, and, 22191for the case of the host file system not supporting file names with 22192colons: 22193 22194@smallexample 22195 c:/foo/bar.dll @result{} /path/to/sysroot/c/foo/bar.dll 22196@end smallexample 22197 22198This makes it possible to have a system root that mirrors a target 22199with more than one drive. E.g., you may want to setup your local 22200copies of the target system shared libraries like so (note @samp{c} vs 22201@samp{z}): 22202 22203@smallexample 22204 @file{/path/to/sysroot/c/sys/bin/foo.dll} 22205 @file{/path/to/sysroot/c/sys/bin/bar.dll} 22206 @file{/path/to/sysroot/z/sys/bin/bar.dll} 22207@end smallexample 22208 22209@noindent 22210and point the system root at @file{/path/to/sysroot}, so that 22211@value{GDBN} can find the correct copies of both 22212@file{c:\sys\bin\foo.dll}, and @file{z:\sys\bin\bar.dll}. 22213 22214If that still does not find the binary, @value{GDBN} tries 22215removing the whole drive spec from the target file name: 22216 22217@smallexample 22218 c:/foo/bar.dll @result{} /path/to/sysroot/foo/bar.dll 22219@end smallexample 22220 22221This last lookup makes it possible to not care about the drive name, 22222if you don't want or need to. 22223 22224The @code{set solib-absolute-prefix} command is an alias for @code{set 22225sysroot}. 22226 22227@cindex default system root 22228@cindex @samp{--with-sysroot} 22229You can set the default system root by using the configure-time 22230@samp{--with-sysroot} option. If the system root is inside 22231@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or 22232@samp{--exec-prefix}), then the default system root will be updated 22233automatically if the installed @value{GDBN} is moved to a new 22234location. 22235 22236@kindex show sysroot 22237@item show sysroot 22238Display the current executable and shared library prefix. 22239 22240@kindex set solib-search-path 22241@item set solib-search-path @var{path} 22242If this variable is set, @var{path} is a colon-separated list of 22243directories to search for shared libraries. @samp{solib-search-path} 22244is used after @samp{sysroot} fails to locate the library, or if the 22245path to the library is relative instead of absolute. If you want to 22246use @samp{solib-search-path} instead of @samp{sysroot}, be sure to set 22247@samp{sysroot} to a nonexistent directory to prevent @value{GDBN} from 22248finding your host's libraries. @samp{sysroot} is preferred; setting 22249it to a nonexistent directory may interfere with automatic loading 22250of shared library symbols. 22251 22252@kindex show solib-search-path 22253@item show solib-search-path 22254Display the current shared library search path. 22255 22256@cindex DOS file-name semantics of file names. 22257@kindex set target-file-system-kind (unix|dos-based|auto) 22258@kindex show target-file-system-kind 22259@item set target-file-system-kind @var{kind} 22260Set assumed file system kind for target reported file names. 22261 22262Shared library file names as reported by the target system may not 22263make sense as is on the system @value{GDBN} is running on. For 22264example, when remote debugging a target that has MS-DOS based file 22265system semantics, from a Unix host, the target may be reporting to 22266@value{GDBN} a list of loaded shared libraries with file names such as 22267@file{c:\Windows\kernel32.dll}. On Unix hosts, there's no concept of 22268drive letters, so the @samp{c:\} prefix is not normally understood as 22269indicating an absolute file name, and neither is the backslash 22270normally considered a directory separator character. In that case, 22271the native file system would interpret this whole absolute file name 22272as a relative file name with no directory components. This would make 22273it impossible to point @value{GDBN} at a copy of the remote target's 22274shared libraries on the host using @code{set sysroot}, and impractical 22275with @code{set solib-search-path}. Setting 22276@code{target-file-system-kind} to @code{dos-based} tells @value{GDBN} 22277to interpret such file names similarly to how the target would, and to 22278map them to file names valid on @value{GDBN}'s native file system 22279semantics. The value of @var{kind} can be @code{"auto"}, in addition 22280to one of the supported file system kinds. In that case, @value{GDBN} 22281tries to determine the appropriate file system variant based on the 22282current target's operating system (@pxref{ABI, ,Configuring the 22283Current ABI}). The supported file system settings are: 22284 22285@table @code 22286@item unix 22287Instruct @value{GDBN} to assume the target file system is of Unix 22288kind. Only file names starting the forward slash (@samp{/}) character 22289are considered absolute, and the directory separator character is also 22290the forward slash. 22291 22292@item dos-based 22293Instruct @value{GDBN} to assume the target file system is DOS based. 22294File names starting with either a forward slash, or a drive letter 22295followed by a colon (e.g., @samp{c:}), are considered absolute, and 22296both the slash (@samp{/}) and the backslash (@samp{\\}) characters are 22297considered directory separators. 22298 22299@item auto 22300Instruct @value{GDBN} to use the file system kind associated with the 22301target operating system (@pxref{ABI, ,Configuring the Current ABI}). 22302This is the default. 22303@end table 22304@end table 22305 22306@cindex file name canonicalization 22307@cindex base name differences 22308When processing file names provided by the user, @value{GDBN} 22309frequently needs to compare them to the file names recorded in the 22310program's debug info. Normally, @value{GDBN} compares just the 22311@dfn{base names} of the files as strings, which is reasonably fast 22312even for very large programs. (The base name of a file is the last 22313portion of its name, after stripping all the leading directories.) 22314This shortcut in comparison is based upon the assumption that files 22315cannot have more than one base name. This is usually true, but 22316references to files that use symlinks or similar filesystem 22317facilities violate that assumption. If your program records files 22318using such facilities, or if you provide file names to @value{GDBN} 22319using symlinks etc., you can set @code{basenames-may-differ} to 22320@code{true} to instruct @value{GDBN} to completely canonicalize each 22321pair of file names it needs to compare. This will make file-name 22322comparisons accurate, but at a price of a significant slowdown. 22323 22324@table @code 22325@item set basenames-may-differ 22326@kindex set basenames-may-differ 22327Set whether a source file may have multiple base names. 22328 22329@item show basenames-may-differ 22330@kindex show basenames-may-differ 22331Show whether a source file may have multiple base names. 22332@end table 22333 22334@node File Caching 22335@section File Caching 22336@cindex caching of opened files 22337@cindex caching of bfd objects 22338 22339To speed up file loading, and reduce memory usage, @value{GDBN} will 22340reuse the @code{bfd} objects used to track open files. @xref{Top, , 22341BFD, bfd, The Binary File Descriptor Library}. The following commands 22342allow visibility and control of the caching behavior. 22343 22344@table @code 22345@kindex maint info bfds 22346@item maint info bfds 22347This prints information about each @code{bfd} object that is known to 22348@value{GDBN}. 22349 22350@kindex maint set bfd-sharing 22351@kindex maint show bfd-sharing 22352@kindex bfd caching 22353@item maint set bfd-sharing 22354@item maint show bfd-sharing 22355Control whether @code{bfd} objects can be shared. When sharing is 22356enabled @value{GDBN} reuses already open @code{bfd} objects rather 22357than reopening the same file. Turning sharing off does not cause 22358already shared @code{bfd} objects to be unshared, but all future files 22359that are opened will create a new @code{bfd} object. Similarly, 22360re-enabling sharing does not cause multiple existing @code{bfd} 22361objects to be collapsed into a single shared @code{bfd} object. 22362 22363@kindex set debug bfd-cache @var{level} 22364@kindex bfd caching 22365@item set debug bfd-cache @var{level} 22366Turns on debugging of the bfd cache, setting the level to @var{level}. 22367 22368@kindex show debug bfd-cache 22369@kindex bfd caching 22370@item show debug bfd-cache 22371Show the current debugging level of the bfd cache. 22372@end table 22373 22374@node Separate Debug Files 22375@section Debugging Information in Separate Files 22376@cindex separate debugging information files 22377@cindex debugging information in separate files 22378@cindex @file{.debug} subdirectories 22379@cindex debugging information directory, global 22380@cindex global debugging information directories 22381@cindex build ID, and separate debugging files 22382@cindex @file{.build-id} directory 22383 22384@value{GDBN} allows you to put a program's debugging information in a 22385file separate from the executable itself, in a way that allows 22386@value{GDBN} to find and load the debugging information automatically. 22387Since debugging information can be very large---sometimes larger 22388than the executable code itself---some systems distribute debugging 22389information for their executables in separate files, which users can 22390install only when they need to debug a problem. 22391 22392@value{GDBN} supports two ways of specifying the separate debug info 22393file: 22394 22395@itemize @bullet 22396@item 22397The executable contains a @dfn{debug link} that specifies the name of 22398the separate debug info file. The separate debug file's name is 22399usually @file{@var{executable}.debug}, where @var{executable} is the 22400name of the corresponding executable file without leading directories 22401(e.g., @file{ls.debug} for @file{/usr/bin/ls}). In addition, the 22402debug link specifies a 32-bit @dfn{Cyclic Redundancy Check} (CRC) 22403checksum for the debug file, which @value{GDBN} uses to validate that 22404the executable and the debug file came from the same build. 22405 22406@item 22407@anchor{build ID} 22408The executable contains a @dfn{build ID}, a unique bit string that is 22409also present in the corresponding debug info file. (This is supported 22410only on some operating systems, when using the ELF or PE file formats 22411for binary files and the @sc{gnu} Binutils.) For more details about 22412this feature, see the description of the @option{--build-id} 22413command-line option in @ref{Options, , Command Line Options, ld, 22414The GNU Linker}. The debug info file's name is not specified 22415explicitly by the build ID, but can be computed from the build ID, see 22416below. 22417@end itemize 22418 22419Depending on the way the debug info file is specified, @value{GDBN} 22420uses two different methods of looking for the debug file: 22421 22422@itemize @bullet 22423@item 22424For the ``debug link'' method, @value{GDBN} looks up the named file in 22425the directory of the executable file, then in a subdirectory of that 22426directory named @file{.debug}, and finally under each one of the 22427global debug directories, in a subdirectory whose name is identical to 22428the leading directories of the executable's absolute file name. (On 22429MS-Windows/MS-DOS, the drive letter of the executable's leading 22430directories is converted to a one-letter subdirectory, i.e.@: 22431@file{d:/usr/bin/} is converted to @file{/d/usr/bin/}, because Windows 22432filesystems disallow colons in file names.) 22433 22434@item 22435For the ``build ID'' method, @value{GDBN} looks in the 22436@file{.build-id} subdirectory of each one of the global debug directories for 22437a file named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the 22438first 2 hex characters of the build ID bit string, and @var{nnnnnnnn} 22439are the rest of the bit string. (Real build ID strings are 32 or more 22440hex characters, not 10.) @value{GDBN} can automatically query 22441@code{debuginfod} servers using build IDs in order to download separate debug 22442files that cannot be found locally. For more information see @ref{Debuginfod}. 22443@end itemize 22444 22445So, for example, suppose you ask @value{GDBN} to debug 22446@file{/usr/bin/ls}, which has a debug link that specifies the 22447file @file{ls.debug}, and a build ID whose value in hex is 22448@code{abcdef1234}. If the list of the global debug directories includes 22449@file{/usr/lib/debug}, then @value{GDBN} will look for the following 22450debug information files, in the indicated order: 22451 22452@itemize @minus 22453@item 22454@file{/usr/lib/debug/.build-id/ab/cdef1234.debug} 22455@item 22456@file{/usr/bin/ls.debug} 22457@item 22458@file{/usr/bin/.debug/ls.debug} 22459@item 22460@file{/usr/lib/debug/usr/bin/ls.debug}. 22461@end itemize 22462 22463If the debug file still has not been found and @code{debuginfod} 22464(@pxref{Debuginfod}) is enabled, @value{GDBN} will attempt to download the 22465file from @code{debuginfod} servers. 22466 22467@anchor{debug-file-directory} 22468Global debugging info directories default to what is set by @value{GDBN} 22469configure option @option{--with-separate-debug-dir} and augmented by the 22470colon-separated list of directories provided via @value{GDBN} configure 22471option @option{--additional-debug-dirs}. During @value{GDBN} run you can 22472also set the global debugging info directories, and view the list 22473@value{GDBN} is currently using. 22474 22475@table @code 22476 22477@kindex set debug-file-directory 22478@item set debug-file-directory @var{directories} 22479Set the directories which @value{GDBN} searches for separate debugging 22480information files to @var{directory}. Multiple path components can be set 22481concatenating them by a path separator. 22482 22483@kindex show debug-file-directory 22484@item show debug-file-directory 22485Show the directories @value{GDBN} searches for separate debugging 22486information files. 22487 22488@end table 22489 22490@cindex @code{.gnu_debuglink} sections 22491@cindex debug link sections 22492A debug link is a special section of the executable file named 22493@code{.gnu_debuglink}. The section must contain: 22494 22495@itemize 22496@item 22497A filename, with any leading directory components removed, followed by 22498a zero byte, 22499@item 22500zero to three bytes of padding, as needed to reach the next four-byte 22501boundary within the section, and 22502@item 22503a four-byte CRC checksum, stored in the same endianness used for the 22504executable file itself. The checksum is computed on the debugging 22505information file's full contents by the function given below, passing 22506zero as the @var{crc} argument. 22507@end itemize 22508 22509Any executable file format can carry a debug link, as long as it can 22510contain a section named @code{.gnu_debuglink} with the contents 22511described above. 22512 22513@cindex @code{.note.gnu.build-id} sections 22514@cindex build ID sections 22515The build ID is a special section in the executable file (and in other 22516ELF binary files that @value{GDBN} may consider). This section is 22517often named @code{.note.gnu.build-id}, but that name is not mandatory. 22518It contains unique identification for the built files---the ID remains 22519the same across multiple builds of the same build tree. The default 22520algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the 22521content for the build ID string. The same section with an identical 22522value is present in the original built binary with symbols, in its 22523stripped variant, and in the separate debugging information file. 22524 22525The debugging information file itself should be an ordinary 22526executable, containing a full set of linker symbols, sections, and 22527debugging information. The sections of the debugging information file 22528should have the same names, addresses, and sizes as the original file, 22529but they need not contain any data---much like a @code{.bss} section 22530in an ordinary executable. 22531 22532The @sc{gnu} binary utilities (Binutils) package includes the 22533@samp{objcopy} utility that can produce 22534the separated executable / debugging information file pairs using the 22535following commands: 22536 22537@smallexample 22538@kbd{objcopy --only-keep-debug foo foo.debug} 22539@kbd{strip -g foo} 22540@end smallexample 22541 22542@noindent 22543These commands remove the debugging 22544information from the executable file @file{foo} and place it in the file 22545@file{foo.debug}. You can use the first, second or both methods to link the 22546two files: 22547 22548@itemize @bullet 22549@item 22550The debug link method needs the following additional command to also leave 22551behind a debug link in @file{foo}: 22552 22553@smallexample 22554@kbd{objcopy --add-gnu-debuglink=foo.debug foo} 22555@end smallexample 22556 22557Ulrich Drepper's @file{elfutils} package, starting with version 0.53, contains 22558a version of the @code{strip} command such that the command @kbd{strip foo -f 22559foo.debug} has the same functionality as the two @code{objcopy} commands and 22560the @code{ln -s} command above, together. 22561 22562@item 22563Build ID gets embedded into the main executable using @code{ld --build-id} or 22564the @value{NGCC} counterpart @code{gcc -Wl,--build-id}. Build ID support plus 22565compatibility fixes for debug files separation are present in @sc{gnu} binary 22566utilities (Binutils) package since version 2.18. 22567@end itemize 22568 22569@noindent 22570 22571@cindex CRC algorithm definition 22572The CRC used in @code{.gnu_debuglink} is the CRC-32 defined in 22573IEEE 802.3 using the polynomial: 22574 22575@c TexInfo requires naked braces for multi-digit exponents for Tex 22576@c output, but this causes HTML output to barf. HTML has to be set using 22577@c raw commands. So we end up having to specify this equation in 2 22578@c different ways! 22579@ifhtml 22580@display 22581@html 22582 <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> 22583 + <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 22584@end html 22585@end display 22586@end ifhtml 22587@ifnothtml 22588@display 22589 @math{x^{32} + x^{26} + x^{23} + x^{22} + x^{16} + x^{12} + x^{11}} 22590 @math{+ x^{10} + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1} 22591@end display 22592@end ifnothtml 22593 22594The function is computed byte at a time, taking the least 22595significant bit of each byte first. The initial pattern 22596@code{0xffffffff} is used, to ensure leading zeros affect the CRC and 22597the final result is inverted to ensure trailing zeros also affect the 22598CRC. 22599 22600@emph{Note:} This is the same CRC polynomial as used in handling the 22601@dfn{Remote Serial Protocol} @code{qCRC} packet (@pxref{qCRC packet}). 22602However in the case of the Remote Serial Protocol, the CRC is computed 22603@emph{most} significant bit first, and the result is not inverted, so 22604trailing zeros have no effect on the CRC value. 22605 22606To complete the description, we show below the code of the function 22607which produces the CRC used in @code{.gnu_debuglink}. Inverting the 22608initially supplied @code{crc} argument means that an initial call to 22609this function passing in zero will start computing the CRC using 22610@code{0xffffffff}. 22611 22612@kindex gnu_debuglink_crc32 22613@smallexample 22614unsigned long 22615gnu_debuglink_crc32 (unsigned long crc, 22616 unsigned char *buf, size_t len) 22617@{ 22618 static const unsigned long crc32_table[256] = 22619 @{ 22620 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, 22621 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, 22622 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, 22623 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, 22624 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, 22625 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, 22626 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, 22627 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, 22628 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, 22629 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, 22630 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, 22631 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, 22632 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, 22633 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, 22634 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, 22635 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, 22636 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, 22637 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, 22638 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, 22639 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, 22640 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, 22641 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, 22642 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, 22643 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, 22644 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, 22645 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, 22646 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, 22647 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, 22648 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, 22649 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, 22650 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, 22651 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, 22652 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, 22653 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, 22654 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, 22655 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, 22656 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, 22657 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, 22658 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, 22659 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, 22660 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, 22661 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, 22662 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, 22663 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, 22664 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, 22665 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, 22666 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, 22667 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, 22668 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, 22669 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, 22670 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, 22671 0x2d02ef8d 22672 @}; 22673 unsigned char *end; 22674 22675 crc = ~crc & 0xffffffff; 22676 for (end = buf + len; buf < end; ++buf) 22677 crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); 22678 return ~crc & 0xffffffff; 22679@} 22680@end smallexample 22681 22682@noindent 22683This computation does not apply to the ``build ID'' method. 22684 22685@node MiniDebugInfo 22686@section Debugging information in a special section 22687@cindex separate debug sections 22688@cindex @samp{.gnu_debugdata} section 22689 22690Some systems ship pre-built executables and libraries that have a 22691special @samp{.gnu_debugdata} section. This feature is called 22692@dfn{MiniDebugInfo}. This section holds an LZMA-compressed object and 22693is used to supply extra symbols for backtraces. 22694 22695The intent of this section is to provide extra minimal debugging 22696information for use in simple backtraces. It is not intended to be a 22697replacement for full separate debugging information (@pxref{Separate 22698Debug Files}). The example below shows the intended use; however, 22699@value{GDBN} does not currently put restrictions on what sort of 22700debugging information might be included in the section. 22701 22702@value{GDBN} has support for this extension. If the section exists, 22703then it is used provided that no other source of debugging information 22704can be found, and that @value{GDBN} was configured with LZMA support. 22705 22706This section can be easily created using @command{objcopy} and other 22707standard utilities: 22708 22709@smallexample 22710# Extract the dynamic symbols from the main binary, there is no need 22711# to also have these in the normal symbol table. 22712nm -D @var{binary} --format=posix --defined-only \ 22713 | awk '@{ print $1 @}' | sort > dynsyms 22714 22715# Extract all the text (i.e. function) symbols from the debuginfo. 22716# (Note that we actually also accept "D" symbols, for the benefit 22717# of platforms like PowerPC64 that use function descriptors.) 22718nm @var{binary} --format=posix --defined-only \ 22719 | awk '@{ if ($2 == "T" || $2 == "t" || $2 == "D") print $1 @}' \ 22720 | sort > funcsyms 22721 22722# Keep all the function symbols not already in the dynamic symbol 22723# table. 22724comm -13 dynsyms funcsyms > keep_symbols 22725 22726# Separate full debug info into debug binary. 22727objcopy --only-keep-debug @var{binary} debug 22728 22729# Copy the full debuginfo, keeping only a minimal set of symbols and 22730# removing some unnecessary sections. 22731objcopy -S --remove-section .gdb_index --remove-section .comment \ 22732 --keep-symbols=keep_symbols debug mini_debuginfo 22733 22734# Drop the full debug info from the original binary. 22735strip --strip-all -R .comment @var{binary} 22736 22737# Inject the compressed data into the .gnu_debugdata section of the 22738# original binary. 22739xz mini_debuginfo 22740objcopy --add-section .gnu_debugdata=mini_debuginfo.xz @var{binary} 22741@end smallexample 22742 22743@node Index Files 22744@section Index Files Speed Up @value{GDBN} 22745@cindex index files 22746@cindex @samp{.gdb_index} section 22747 22748When @value{GDBN} finds a symbol file, it scans the symbols in the 22749file in order to construct an internal symbol table. This lets most 22750@value{GDBN} operations work quickly---at the cost of a delay early 22751on. For large programs, this delay can be quite lengthy, so 22752@value{GDBN} provides a way to build an index, which speeds up 22753startup. 22754 22755For convenience, @value{GDBN} comes with a program, 22756@command{gdb-add-index}, which can be used to add the index to a 22757symbol file. It takes the symbol file as its only argument: 22758 22759@smallexample 22760$ gdb-add-index symfile 22761@end smallexample 22762 22763@xref{gdb-add-index}. 22764 22765It is also possible to do the work manually. Here is what 22766@command{gdb-add-index} does behind the curtains. 22767 22768The index is stored as a section in the symbol file. @value{GDBN} can 22769write the index to a file, then you can put it into the symbol file 22770using @command{objcopy}. 22771 22772To create an index file, use the @code{save gdb-index} command: 22773 22774@table @code 22775@item save gdb-index [-dwarf-5] @var{directory} 22776@kindex save gdb-index 22777Create index files for all symbol files currently known by 22778@value{GDBN}. For each known @var{symbol-file}, this command by 22779default creates it produces a single file 22780@file{@var{symbol-file}.gdb-index}. If you invoke this command with 22781the @option{-dwarf-5} option, it produces 2 files: 22782@file{@var{symbol-file}.debug_names} and 22783@file{@var{symbol-file}.debug_str}. The files are created in the 22784given @var{directory}. 22785@end table 22786 22787Once you have created an index file you can merge it into your symbol 22788file, here named @file{symfile}, using @command{objcopy}: 22789 22790@smallexample 22791$ objcopy --add-section .gdb_index=symfile.gdb-index \ 22792 --set-section-flags .gdb_index=readonly symfile symfile 22793@end smallexample 22794 22795Or for @code{-dwarf-5}: 22796 22797@smallexample 22798$ objcopy --dump-section .debug_str=symfile.debug_str.new symfile 22799$ cat symfile.debug_str >>symfile.debug_str.new 22800$ objcopy --add-section .debug_names=symfile.gdb-index \ 22801 --set-section-flags .debug_names=readonly \ 22802 --update-section .debug_str=symfile.debug_str.new symfile symfile 22803@end smallexample 22804 22805@value{GDBN} will normally ignore older versions of @file{.gdb_index} 22806sections that have been deprecated. Usually they are deprecated because 22807they are missing a new feature or have performance issues. 22808To tell @value{GDBN} to use a deprecated index section anyway 22809specify @code{set use-deprecated-index-sections on}. 22810The default is @code{off}. 22811This can speed up startup, but may result in some functionality being lost. 22812@xref{Index Section Format}. 22813 22814@emph{Warning:} Setting @code{use-deprecated-index-sections} to @code{on} 22815must be done before gdb reads the file. The following will not work: 22816 22817@smallexample 22818$ gdb -ex "set use-deprecated-index-sections on" <program> 22819@end smallexample 22820 22821Instead you must do, for example, 22822 22823@smallexample 22824$ gdb -iex "set use-deprecated-index-sections on" <program> 22825@end smallexample 22826 22827Indices only work when using DWARF debugging information, not stabs. 22828 22829@subsection Automatic symbol index cache 22830 22831@cindex automatic symbol index cache 22832It is possible for @value{GDBN} to automatically save a copy of this index in a 22833cache on disk and retrieve it from there when loading the same binary in the 22834future. This feature can be turned on with @kbd{set index-cache enabled on}. 22835The following commands can be used to tweak the behavior of the index cache. 22836 22837@table @code 22838 22839@kindex set index-cache 22840@item set index-cache enabled on 22841@itemx set index-cache enabled off 22842Enable or disable the use of the symbol index cache. 22843 22844@item set index-cache directory @var{directory} 22845@kindex show index-cache 22846@itemx show index-cache directory 22847Set/show the directory where index files will be saved. 22848 22849The default value for this directory depends on the host platform. On 22850most systems, the index is cached in the @file{gdb} subdirectory of 22851the directory pointed to by the @env{XDG_CACHE_HOME} environment 22852variable, if it is defined, else in the @file{.cache/gdb} subdirectory 22853of your home directory. However, on some systems, the default may 22854differ according to local convention. 22855 22856There is no limit on the disk space used by index cache. It is perfectly safe 22857to delete the content of that directory to free up disk space. 22858 22859@item show index-cache stats 22860Print the number of cache hits and misses since the launch of @value{GDBN}. 22861 22862@end table 22863 22864@node Debug Names 22865@section Extensions to @samp{.debug_names} 22866@cindex index files 22867@cindex @samp{.debug_names} section 22868 22869The DWARF specification documents an optional index section called 22870@samp{.debug_names}. @value{GDBN} can both read and create this 22871section. However, in order to work with @value{GDBN}, some extensions 22872were necessary. 22873 22874@value{GDBN} uses the augmentation string @samp{GDB2}. Earlier 22875versions used the string @samp{GDB}, but these versions of the index 22876are no longer supported. 22877 22878@value{GDBN} does not use the specified hash table. Therefore, 22879because this hash table is optional, @value{GDBN} also does not write 22880it. 22881 22882@value{GDBN} also generates and uses some extra index attributes: 22883@table @code 22884@item DW_IDX_GNU_internal 22885This has the value @samp{0x2000}. It is a flag that, when set, 22886indicates that the associated entry has @code{static} linkage. 22887 22888@item DW_IDX_GNU_main 22889This has the value @samp{0x2002}. It is a flag that, when set, 22890indicates that the associated entry is the program's @code{main}. 22891 22892@item DW_IDX_GNU_language 22893This has the value @samp{0x2003}. It is @samp{DW_LANG_} constant, 22894indicating the language of the associated entry. 22895 22896@item DW_IDX_GNU_linkage_name 22897This has the value @samp{0x2004}. It is a flag that, when set, 22898indicates that the associated entry is a linkage name, and not a 22899source name. 22900@end table 22901 22902@node Symbol Errors 22903@section Errors Reading Symbol Files 22904 22905While reading a symbol file, @value{GDBN} occasionally encounters problems, 22906such as symbol types it does not recognize, or known bugs in compiler 22907output. By default, @value{GDBN} does not notify you of such problems, since 22908they are relatively common and primarily of interest to people 22909debugging compilers. If you are interested in seeing information 22910about ill-constructed symbol tables, you can either ask @value{GDBN} to print 22911only one message about each such type of problem, no matter how many 22912times the problem occurs; or you can ask @value{GDBN} to print more messages, 22913to see how many times the problems occur, with the @code{set 22914complaints} command (@pxref{Messages/Warnings, ,Optional Warnings and 22915Messages}). 22916 22917The messages currently printed, and their meanings, include: 22918 22919@table @code 22920@item inner block not inside outer block in @var{symbol} 22921 22922The symbol information shows where symbol scopes begin and end 22923(such as at the start of a function or a block of statements). This 22924error indicates that an inner scope block is not fully contained 22925in its outer scope blocks. 22926 22927@value{GDBN} circumvents the problem by treating the inner block as if it had 22928the same scope as the outer block. In the error message, @var{symbol} 22929may be shown as ``@code{(don't know)}'' if the outer block is not a 22930function. 22931 22932@item block at @var{address} out of order 22933 22934The symbol information for symbol scope blocks should occur in 22935order of increasing addresses. This error indicates that it does not 22936do so. 22937 22938@value{GDBN} does not circumvent this problem, and has trouble 22939locating symbols in the source file whose symbols it is reading. (You 22940can often determine what source file is affected by specifying 22941@code{set verbose on}. @xref{Messages/Warnings, ,Optional Warnings and 22942Messages}.) 22943 22944@item bad block start address patched 22945 22946The symbol information for a symbol scope block has a start address 22947smaller than the address of the preceding source line. This is known 22948to occur in the SunOS 4.1.1 (and earlier) C compiler. 22949 22950@value{GDBN} circumvents the problem by treating the symbol scope block as 22951starting on the previous source line. 22952 22953@item bad string table offset in symbol @var{n} 22954 22955@cindex foo 22956Symbol number @var{n} contains a pointer into the string table which is 22957larger than the size of the string table. 22958 22959@value{GDBN} circumvents the problem by considering the symbol to have the 22960name @code{foo}, which may cause other problems if many symbols end up 22961with this name. 22962 22963@item unknown symbol type @code{0x@var{nn}} 22964 22965The symbol information contains new data types that @value{GDBN} does 22966not yet know how to read. @code{0x@var{nn}} is the symbol type of the 22967uncomprehended information, in hexadecimal. 22968 22969@value{GDBN} circumvents the error by ignoring this symbol information. 22970This usually allows you to debug your program, though certain symbols 22971are not accessible. If you encounter such a problem and feel like 22972debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint 22973on @code{complain}, then go up to the function @code{read_dbx_symtab} 22974and examine @code{*bufp} to see the symbol. 22975 22976@item stub type has NULL name 22977 22978@value{GDBN} could not find the full definition for a struct or class. 22979 22980@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{} 22981The symbol information for a C@t{++} member function is missing some 22982information that recent versions of the compiler should have output for 22983it. 22984 22985@item info mismatch between compiler and debugger 22986 22987@value{GDBN} could not parse a type specification output by the compiler. 22988 22989@end table 22990 22991@node Data Files 22992@section GDB Data Files 22993 22994@cindex prefix for data files 22995@value{GDBN} will sometimes read an auxiliary data file. These files 22996are kept in a directory known as the @dfn{data directory}. 22997 22998You can set the data directory's name, and view the name @value{GDBN} 22999is currently using. 23000 23001@table @code 23002@kindex set data-directory 23003@item set data-directory @var{directory} 23004Set the directory which @value{GDBN} searches for auxiliary data files 23005to @var{directory}. 23006 23007@kindex show data-directory 23008@item show data-directory 23009Show the directory @value{GDBN} searches for auxiliary data files. 23010@end table 23011 23012@cindex default data directory 23013@cindex @samp{--with-gdb-datadir} 23014You can set the default data directory by using the configure-time 23015@samp{--with-gdb-datadir} option. If the data directory is inside 23016@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or 23017@samp{--exec-prefix}), then the default data directory will be updated 23018automatically if the installed @value{GDBN} is moved to a new 23019location. 23020 23021The data directory may also be specified with the 23022@code{--data-directory} command line option. 23023@xref{Mode Options}. 23024 23025@node Targets 23026@chapter Specifying a Debugging Target 23027 23028@cindex debugging target 23029A @dfn{target} is the execution environment occupied by your program. 23030 23031Often, @value{GDBN} runs in the same host environment as your program; 23032in that case, the debugging target is specified as a side effect when 23033you use the @code{file} or @code{core} commands. When you need more 23034flexibility---for example, running @value{GDBN} on a physically separate 23035host, or controlling a standalone system over a serial port or a 23036realtime system over a TCP/IP connection---you can use the @code{target} 23037command to specify one of the target types configured for @value{GDBN} 23038(@pxref{Target Commands, ,Commands for Managing Targets}). 23039 23040@cindex target architecture 23041It is possible to build @value{GDBN} for several different @dfn{target 23042architectures}. When @value{GDBN} is built like that, you can choose 23043one of the available architectures with the @kbd{set architecture} 23044command. 23045 23046@table @code 23047@kindex set architecture 23048@kindex show architecture 23049@item set architecture @var{arch} 23050This command sets the current target architecture to @var{arch}. The 23051value of @var{arch} can be @code{"auto"}, in addition to one of the 23052supported architectures. 23053 23054@item show architecture 23055Show the current target architecture. 23056 23057@item set processor 23058@itemx processor 23059@kindex set processor 23060@kindex show processor 23061These are alias commands for, respectively, @code{set architecture} 23062and @code{show architecture}. 23063@end table 23064 23065@menu 23066* Active Targets:: Active targets 23067* Target Commands:: Commands for managing targets 23068* Byte Order:: Choosing target byte order 23069@end menu 23070 23071@node Active Targets 23072@section Active Targets 23073 23074@cindex stacking targets 23075@cindex active targets 23076@cindex multiple targets 23077 23078There are multiple classes of targets such as: processes, executable files or 23079recording sessions. Core files belong to the process class, making core file 23080and process mutually exclusive. Otherwise, @value{GDBN} can work concurrently 23081on multiple active targets, one in each class. This allows you to (for 23082example) start a process and inspect its activity, while still having access to 23083the executable file after the process finishes. Or if you start process 23084recording (@pxref{Reverse Execution}) and @code{reverse-step} there, you are 23085presented a virtual layer of the recording target, while the process target 23086remains stopped at the chronologically last point of the process execution. 23087 23088Use the @code{core-file} and @code{exec-file} commands to select a new core 23089file or executable target (@pxref{Files, ,Commands to Specify Files}). To 23090specify as a target a process that is already running, use the @code{attach} 23091command (@pxref{Attach, ,Debugging an Already-running Process}). 23092 23093@node Target Commands 23094@section Commands for Managing Targets 23095 23096@table @code 23097@item target @var{type} @var{parameters} 23098Connects the @value{GDBN} host environment to a target machine or 23099process. A target is typically a protocol for talking to debugging 23100facilities. You use the argument @var{type} to specify the type or 23101protocol of the target machine. 23102 23103Further @var{parameters} are interpreted by the target protocol, but 23104typically include things like device names or host names to connect 23105with, process numbers, and baud rates. 23106 23107The @code{target} command does not repeat if you press @key{RET} again 23108after executing the command. 23109 23110@kindex help target 23111@item help target 23112Displays the names of all targets available. To display targets 23113currently selected, use either @code{info target} or @code{info files} 23114(@pxref{Files, ,Commands to Specify Files}). 23115 23116@item help target @var{name} 23117Describe a particular target, including any parameters necessary to 23118select it. 23119 23120@kindex set gnutarget 23121@item set gnutarget @var{args} 23122@value{GDBN} uses its own library BFD to read your files. @value{GDBN} 23123knows whether it is reading an @dfn{executable}, 23124a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format 23125with the @code{set gnutarget} command. Unlike most @code{target} commands, 23126with @code{gnutarget} the @code{target} refers to a program, not a machine. 23127 23128@quotation 23129@emph{Warning:} To specify a file format with @code{set gnutarget}, 23130you must know the actual BFD name. 23131@end quotation 23132 23133@noindent 23134@xref{Files, , Commands to Specify Files}. 23135 23136@kindex show gnutarget 23137@item show gnutarget 23138Use the @code{show gnutarget} command to display what file format 23139@code{gnutarget} is set to read. If you have not set @code{gnutarget}, 23140@value{GDBN} will determine the file format for each file automatically, 23141and @code{show gnutarget} displays @samp{The current BFD target is "auto"}. 23142@end table 23143 23144@cindex common targets 23145Here are some common targets (available, or not, depending on the GDB 23146configuration): 23147 23148@table @code 23149@kindex target 23150@item target exec @var{program} 23151@cindex executable file target 23152An executable file. @samp{target exec @var{program}} is the same as 23153@samp{exec-file @var{program}}. 23154 23155@item target core @var{filename} 23156@cindex core dump file target 23157A core dump file. @samp{target core @var{filename}} is the same as 23158@samp{core-file @var{filename}}. 23159 23160@item target remote @var{medium} 23161@cindex remote target 23162A remote system connected to @value{GDBN} via a serial line or network 23163connection. This command tells @value{GDBN} to use its own remote 23164protocol over @var{medium} for debugging. @xref{Remote Debugging}. 23165 23166For example, if you have a board connected to @file{/dev/ttya} on the 23167machine running @value{GDBN}, you could say: 23168 23169@smallexample 23170target remote /dev/ttya 23171@end smallexample 23172 23173@code{target remote} supports the @code{load} command. This is only 23174useful if you have some other way of getting the stub to the target 23175system, and you can put it somewhere in memory where it won't get 23176clobbered by the download. 23177 23178@item target sim @r{[}@var{simargs}@r{]} @dots{} 23179@cindex built-in simulator target 23180Builtin CPU simulator. @value{GDBN} includes simulators for most architectures. 23181In general, 23182@smallexample 23183 target sim 23184 load 23185 run 23186@end smallexample 23187@noindent 23188works; however, you cannot assume that a specific memory map, device 23189drivers, or even basic I/O is available, although some simulators do 23190provide these. For info about any processor-specific simulator details, 23191see the appropriate section in @ref{Embedded Processors, ,Embedded 23192Processors}. 23193 23194@item target native 23195@cindex native target 23196Setup for local/native process debugging. Useful to make the 23197@code{run} command spawn native processes (likewise @code{attach}, 23198etc.@:) even when @code{set auto-connect-native-target} is @code{off} 23199(@pxref{set auto-connect-native-target}). 23200 23201@end table 23202 23203Different targets are available on different configurations of @value{GDBN}; 23204your configuration may have more or fewer targets. 23205 23206Many remote targets require you to download the executable's code once 23207you've successfully established a connection. You may wish to control 23208various aspects of this process. 23209 23210@table @code 23211 23212@item set hash 23213@kindex set hash@r{, for remote monitors} 23214@cindex hash mark while downloading 23215This command controls whether a hash mark @samp{#} is displayed while 23216downloading a file to the remote monitor. If on, a hash mark is 23217displayed after each S-record is successfully downloaded to the 23218monitor. 23219 23220@item show hash 23221@kindex show hash@r{, for remote monitors} 23222Show the current status of displaying the hash mark. 23223 23224@item set debug monitor 23225@kindex set debug monitor 23226@cindex display remote monitor communications 23227Enable or disable display of communications messages between 23228@value{GDBN} and the remote monitor. 23229 23230@item show debug monitor 23231@kindex show debug monitor 23232Show the current status of displaying communications between 23233@value{GDBN} and the remote monitor. 23234@end table 23235 23236@table @code 23237 23238@kindex load @var{filename} @var{offset} 23239@item load @var{filename} @var{offset} 23240@anchor{load} 23241Depending on what remote debugging facilities are configured into 23242@value{GDBN}, the @code{load} command may be available. Where it exists, it 23243is meant to make @var{filename} (an executable) available for debugging 23244on the remote system---by downloading, or dynamic linking, for example. 23245@code{load} also records the @var{filename} symbol table in @value{GDBN}, like 23246the @code{add-symbol-file} command. 23247 23248If your @value{GDBN} does not have a @code{load} command, attempting to 23249execute it gets the error message ``@code{You can't do that when your 23250target is @dots{}}'' 23251 23252The file is loaded at whatever address is specified in the executable. 23253For some object file formats, you can specify the load address when you 23254link the program; for other formats, like a.out, the object file format 23255specifies a fixed address. 23256@c FIXME! This would be a good place for an xref to the GNU linker doc. 23257 23258It is also possible to tell @value{GDBN} to load the executable file at a 23259specific offset described by the optional argument @var{offset}. When 23260@var{offset} is provided, @var{filename} must also be provided. 23261 23262Depending on the remote side capabilities, @value{GDBN} may be able to 23263load programs into flash memory. 23264 23265@code{load} does not repeat if you press @key{RET} again after using it. 23266@end table 23267 23268@table @code 23269 23270@kindex flash-erase 23271@item flash-erase 23272@anchor{flash-erase} 23273 23274Erases all known flash memory regions on the target. 23275 23276@end table 23277 23278@node Byte Order 23279@section Choosing Target Byte Order 23280 23281@cindex choosing target byte order 23282@cindex target byte order 23283 23284Some types of processors, such as the @acronym{MIPS}, PowerPC, and Renesas SH, 23285offer the ability to run either big-endian or little-endian byte 23286orders. Usually the executable or symbol will include a bit to 23287designate the endian-ness, and you will not need to worry about 23288which to use. However, you may still find it useful to adjust 23289@value{GDBN}'s idea of processor endian-ness manually. 23290 23291@table @code 23292@kindex set endian 23293@item set endian big 23294Instruct @value{GDBN} to assume the target is big-endian. 23295 23296@item set endian little 23297Instruct @value{GDBN} to assume the target is little-endian. 23298 23299@item set endian auto 23300Instruct @value{GDBN} to use the byte order associated with the 23301executable. 23302 23303@item show endian 23304Display @value{GDBN}'s current idea of the target byte order. 23305 23306@end table 23307 23308If the @code{set endian auto} mode is in effect and no executable has 23309been selected, then the endianness used is the last one chosen either 23310by one of the @code{set endian big} and @code{set endian little} 23311commands or by inferring from the last executable used. If no 23312endianness has been previously chosen, then the default for this mode 23313is inferred from the target @value{GDBN} has been built for, and is 23314@code{little} if the name of the target CPU has an @code{el} suffix 23315and @code{big} otherwise. 23316 23317Note that these commands merely adjust interpretation of symbolic 23318data on the host, and that they have absolutely no effect on the 23319target system. 23320 23321 23322@node Remote Debugging 23323@chapter Debugging Remote Programs 23324@cindex remote debugging 23325 23326If you are trying to debug a program running on a machine that cannot run 23327@value{GDBN} in the usual way, it is often useful to use remote debugging. 23328For example, you might use remote debugging on an operating system kernel, 23329or on a small system which does not have a general purpose operating system 23330powerful enough to run a full-featured debugger. 23331 23332Some configurations of @value{GDBN} have special serial or TCP/IP interfaces 23333to make this work with particular debugging targets. In addition, 23334@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN}, 23335but not specific to any particular target system) which you can use if you 23336write the remote stubs---the code that runs on the remote system to 23337communicate with @value{GDBN}. 23338 23339Other remote targets may be available in your 23340configuration of @value{GDBN}; use @code{help target} to list them. 23341 23342@menu 23343* Connecting:: Connecting to a remote target 23344* File Transfer:: Sending files to a remote system 23345* Server:: Using the gdbserver program 23346* Remote Configuration:: Remote configuration 23347* Remote Stub:: Implementing a remote stub 23348@end menu 23349 23350@node Connecting 23351@section Connecting to a Remote Target 23352@cindex remote debugging, connecting 23353@cindex @code{gdbserver}, connecting 23354@cindex remote debugging, types of connections 23355@cindex @code{gdbserver}, types of connections 23356@cindex @code{gdbserver}, @code{target remote} mode 23357@cindex @code{gdbserver}, @code{target extended-remote} mode 23358 23359This section describes how to connect to a remote target, including the 23360types of connections and their differences, how to set up executable and 23361symbol files on the host and target, and the commands used for 23362connecting to and disconnecting from the remote target. 23363 23364@subsection Types of Remote Connections 23365 23366@value{GDBN} supports two types of remote connections, @code{target remote} 23367mode and @code{target extended-remote} mode. Note that many remote targets 23368support only @code{target remote} mode. There are several major 23369differences between the two types of connections, enumerated here: 23370 23371@table @asis 23372 23373@cindex remote debugging, detach and program exit 23374@item Result of detach or program exit 23375@strong{With target remote mode:} When the debugged program exits or you 23376detach from it, @value{GDBN} disconnects from the target. When using 23377@code{gdbserver}, @code{gdbserver} will exit. 23378 23379@strong{With target extended-remote mode:} When the debugged program exits or 23380you detach from it, @value{GDBN} remains connected to the target, even 23381though no program is running. You can rerun the program, attach to a 23382running program, or use @code{monitor} commands specific to the target. 23383 23384When using @code{gdbserver} in this case, it does not exit unless it was 23385invoked using the @option{--once} option. If the @option{--once} option 23386was not used, you can ask @code{gdbserver} to exit using the 23387@code{monitor exit} command (@pxref{Monitor Commands for gdbserver}). 23388 23389@item Specifying the program to debug 23390For both connection types you use the @code{file} command to specify the 23391program on the host system. If you are using @code{gdbserver} there are 23392some differences in how to specify the location of the program on the 23393target. 23394 23395@strong{With target remote mode:} You must either specify the program to debug 23396on the @code{gdbserver} command line or use the @option{--attach} option 23397(@pxref{Attaching to a program,,Attaching to a Running Program}). 23398 23399@cindex @option{--multi}, @code{gdbserver} option 23400@strong{With target extended-remote mode:} You may specify the program to debug 23401on the @code{gdbserver} command line, or you can load the program or attach 23402to it using @value{GDBN} commands after connecting to @code{gdbserver}. 23403 23404@anchor{--multi Option in Types of Remote Connnections} 23405You can start @code{gdbserver} without supplying an initial command to run 23406or process ID to attach. To do this, use the @option{--multi} command line 23407option. Then you can connect using @code{target extended-remote} and start 23408the program you want to debug (see below for details on using the 23409@code{run} command in this scenario). Note that the conditions under which 23410@code{gdbserver} terminates depend on how @value{GDBN} connects to it 23411(@code{target remote} or @code{target extended-remote}). The 23412@option{--multi} option to @code{gdbserver} has no influence on that. 23413 23414@item The @code{run} command 23415@strong{With target remote mode:} The @code{run} command is not 23416supported. Once a connection has been established, you can use all 23417the usual @value{GDBN} commands to examine and change data. The 23418remote program is already running, so you can use commands like 23419@kbd{step} and @kbd{continue}. 23420 23421@strong{With target extended-remote mode:} The @code{run} command is 23422supported. The @code{run} command uses the value set by 23423@code{set remote exec-file} (@pxref{set remote exec-file}) to select 23424the program to run. Command line arguments are supported, except for 23425wildcard expansion and I/O redirection (@pxref{Arguments}). 23426 23427If you specify the program to debug on the command line, then the 23428@code{run} command is not required to start execution, and you can 23429resume using commands like @kbd{step} and @kbd{continue} as with 23430@code{target remote} mode. 23431 23432@anchor{Attaching in Types of Remote Connections} 23433@item Attaching 23434@strong{With target remote mode:} The @value{GDBN} command @code{attach} is 23435not supported. To attach to a running program using @code{gdbserver}, you 23436must use the @option{--attach} option (@pxref{Running gdbserver}). 23437 23438@strong{With target extended-remote mode:} To attach to a running program, 23439you may use the @code{attach} command after the connection has been 23440established. If you are using @code{gdbserver}, you may also invoke 23441@code{gdbserver} using the @option{--attach} option 23442(@pxref{Running gdbserver}). 23443 23444Some remote targets allow @value{GDBN} to determine the executable file running 23445in the process the debugger is attaching to. In such a case, @value{GDBN} 23446uses the value of @code{exec-file-mismatch} to handle a possible mismatch 23447between the executable file name running in the process and the name of the 23448current exec-file loaded by @value{GDBN} (@pxref{set exec-file-mismatch}). 23449 23450@end table 23451 23452@anchor{Host and target files} 23453@subsection Host and Target Files 23454@cindex remote debugging, symbol files 23455@cindex symbol files, remote debugging 23456 23457@value{GDBN}, running on the host, needs access to symbol and debugging 23458information for your program running on the target. This requires 23459access to an unstripped copy of your program, and possibly any associated 23460symbol files. Note that this section applies equally to both @code{target 23461remote} mode and @code{target extended-remote} mode. 23462 23463Some remote targets (@pxref{qXfer executable filename read}, and 23464@pxref{Host I/O Packets}) allow @value{GDBN} to access program files over 23465the same connection used to communicate with @value{GDBN}. With such a 23466target, if the remote program is unstripped, the only command you need is 23467@code{target remote} (or @code{target extended-remote}). 23468 23469If the remote program is stripped, or the target does not support remote 23470program file access, start up @value{GDBN} using the name of the local 23471unstripped copy of your program as the first argument, or use the 23472@code{file} command. Use @code{set sysroot} to specify the location (on 23473the host) of target libraries (unless your @value{GDBN} was compiled with 23474the correct sysroot using @code{--with-sysroot}). Alternatively, you 23475may use @code{set solib-search-path} to specify how @value{GDBN} locates 23476target libraries. 23477 23478The symbol file and target libraries must exactly match the executable 23479and libraries on the target, with one exception: the files on the host 23480system should not be stripped, even if the files on the target system 23481are. Mismatched or missing files will lead to confusing results 23482during debugging. On @sc{gnu}/Linux targets, mismatched or missing 23483files may also prevent @code{gdbserver} from debugging multi-threaded 23484programs. 23485 23486@subsection Remote Connection Commands 23487@cindex remote connection commands 23488@value{GDBN} can communicate with the target over a serial line, a 23489local Unix domain socket, or 23490over an @acronym{IP} network using @acronym{TCP} or @acronym{UDP}. In 23491each case, @value{GDBN} uses the same protocol for debugging your 23492program; only the medium carrying the debugging packets varies. The 23493@code{target remote} and @code{target extended-remote} commands 23494establish a connection to the target. Both commands accept the same 23495arguments, which indicate the medium to use: 23496 23497@table @code 23498 23499@item target remote @var{serial-device} 23500@itemx target extended-remote @var{serial-device} 23501@cindex serial line, @code{target remote} 23502Use @var{serial-device} to communicate with the target. For example, 23503to use a serial line connected to the device named @file{/dev/ttyb}: 23504 23505@smallexample 23506target remote /dev/ttyb 23507@end smallexample 23508 23509If you're using a serial line, you may want to give @value{GDBN} the 23510@samp{--baud} option, or use the @code{set serial baud} command 23511(@pxref{Remote Configuration, set serial baud}) before the 23512@code{target} command. 23513 23514@item target remote @var{local-socket} 23515@itemx target extended-remote @var{local-socket} 23516@cindex local socket, @code{target remote} 23517@cindex Unix domain socket 23518Use @var{local-socket} to communicate with the target. For example, 23519to use a local Unix domain socket bound to the file system entry @file{/tmp/gdb-socket0}: 23520 23521@smallexample 23522target remote /tmp/gdb-socket0 23523@end smallexample 23524 23525Note that this command has the same form as the command to connect 23526to a serial line. @value{GDBN} will automatically determine which 23527kind of file you have specified and will make the appropriate kind 23528of connection. 23529This feature is not available if the host system does not support 23530Unix domain sockets. 23531 23532@item target remote @code{@var{host}:@var{port}} 23533@itemx target remote @code{[@var{host}]:@var{port}} 23534@itemx target remote @code{tcp:@var{host}:@var{port}} 23535@itemx target remote @code{tcp:[@var{host}]:@var{port}} 23536@itemx target remote @code{tcp4:@var{host}:@var{port}} 23537@itemx target remote @code{tcp6:@var{host}:@var{port}} 23538@itemx target remote @code{tcp6:[@var{host}]:@var{port}} 23539@itemx target extended-remote @code{@var{host}:@var{port}} 23540@itemx target extended-remote @code{[@var{host}]:@var{port}} 23541@itemx target extended-remote @code{tcp:@var{host}:@var{port}} 23542@itemx target extended-remote @code{tcp:[@var{host}]:@var{port}} 23543@itemx target extended-remote @code{tcp4:@var{host}:@var{port}} 23544@itemx target extended-remote @code{tcp6:@var{host}:@var{port}} 23545@itemx target extended-remote @code{tcp6:[@var{host}]:@var{port}} 23546@cindex @acronym{TCP} port, @code{target remote} 23547Debug using a @acronym{TCP} connection to @var{port} on @var{host}. 23548The @var{host} may be either a host name, a numeric @acronym{IPv4} 23549address, or a numeric @acronym{IPv6} address (with or without the 23550square brackets to separate the address from the port); @var{port} 23551must be a decimal number. The @var{host} could be the target machine 23552itself, if it is directly connected to the net, or it might be a 23553terminal server which in turn has a serial line to the target. 23554 23555For example, to connect to port 2828 on a terminal server named 23556@code{manyfarms}: 23557 23558@smallexample 23559target remote manyfarms:2828 23560@end smallexample 23561 23562To connect to port 2828 on a terminal server whose address is 23563@code{2001:0db8:85a3:0000:0000:8a2e:0370:7334}, you can either use the 23564square bracket syntax: 23565 23566@smallexample 23567target remote [2001:0db8:85a3:0000:0000:8a2e:0370:7334]:2828 23568@end smallexample 23569 23570@noindent 23571or explicitly specify the @acronym{IPv6} protocol: 23572 23573@smallexample 23574target remote tcp6:2001:0db8:85a3:0000:0000:8a2e:0370:7334:2828 23575@end smallexample 23576 23577This last example may be confusing to the reader, because there is no 23578visible separation between the hostname and the port number. 23579Therefore, we recommend the user to provide @acronym{IPv6} addresses 23580using square brackets for clarity. However, it is important to 23581mention that for @value{GDBN} there is no ambiguity: the number after 23582the last colon is considered to be the port number. 23583 23584If your remote target is actually running on the same machine as your 23585debugger session (e.g.@: a simulator for your target running on the 23586same host), you can omit the hostname. For example, to connect to 23587port 1234 on your local machine: 23588 23589@smallexample 23590target remote :1234 23591@end smallexample 23592@noindent 23593 23594Note that the colon is still required here. 23595 23596@item target remote @code{udp:@var{host}:@var{port}} 23597@itemx target remote @code{udp:[@var{host}]:@var{port}} 23598@itemx target remote @code{udp4:@var{host}:@var{port}} 23599@itemx target remote @code{udp6:[@var{host}]:@var{port}} 23600@itemx target extended-remote @code{udp:@var{host}:@var{port}} 23601@itemx target extended-remote @code{udp:@var{host}:@var{port}} 23602@itemx target extended-remote @code{udp:[@var{host}]:@var{port}} 23603@itemx target extended-remote @code{udp4:@var{host}:@var{port}} 23604@itemx target extended-remote @code{udp6:@var{host}:@var{port}} 23605@itemx target extended-remote @code{udp6:[@var{host}]:@var{port}} 23606@cindex @acronym{UDP} port, @code{target remote} 23607Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to 23608connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}: 23609 23610@smallexample 23611target remote udp:manyfarms:2828 23612@end smallexample 23613 23614When using a @acronym{UDP} connection for remote debugging, you should 23615keep in mind that the `U' stands for ``Unreliable''. @acronym{UDP} 23616can silently drop packets on busy or unreliable networks, which will 23617cause havoc with your debugging session. 23618 23619@item target remote | @var{command} 23620@itemx target extended-remote | @var{command} 23621@cindex pipe, @code{target remote} to 23622Run @var{command} in the background and communicate with it using a 23623pipe. The @var{command} is a shell command, to be parsed and expanded 23624by the system's command shell, @code{/bin/sh}; it should expect remote 23625protocol packets on its standard input, and send replies on its 23626standard output. You could use this to run a stand-alone simulator 23627that speaks the remote debugging protocol, to make net connections 23628using programs like @code{ssh}, or for other similar tricks. 23629 23630If @var{command} closes its standard output (perhaps by exiting), 23631@value{GDBN} will try to send it a @code{SIGTERM} signal. (If the 23632program has already exited, this will have no effect.) 23633 23634@end table 23635 23636@cindex interrupting remote programs 23637@cindex remote programs, interrupting 23638Whenever @value{GDBN} is waiting for the remote program, if you type the 23639interrupt character (often @kbd{Ctrl-c}), @value{GDBN} attempts to stop the 23640program. This may or may not succeed, depending in part on the hardware 23641and the serial drivers the remote system uses. If you type the 23642interrupt character once again, @value{GDBN} displays this prompt: 23643 23644@smallexample 23645Interrupted while waiting for the program. 23646Give up (and stop debugging it)? (y or n) 23647@end smallexample 23648 23649In @code{target remote} mode, if you type @kbd{y}, @value{GDBN} abandons 23650the remote debugging session. (If you decide you want to try again later, 23651you can use @kbd{target remote} again to connect once more.) If you type 23652@kbd{n}, @value{GDBN} goes back to waiting. 23653 23654In @code{target extended-remote} mode, typing @kbd{n} will leave 23655@value{GDBN} connected to the target. 23656 23657@table @code 23658@kindex detach (remote) 23659@item detach 23660When you have finished debugging the remote program, you can use the 23661@code{detach} command to release it from @value{GDBN} control. 23662Detaching from the target normally resumes its execution, but the results 23663will depend on your particular remote stub. After the @code{detach} 23664command in @code{target remote} mode, @value{GDBN} is free to connect to 23665another target. In @code{target extended-remote} mode, @value{GDBN} is 23666still connected to the target. 23667 23668@kindex disconnect 23669@item disconnect 23670The @code{disconnect} command closes the connection to the target, and 23671the target is generally not resumed. It will wait for @value{GDBN} 23672(this instance or another one) to connect and continue debugging. After 23673the @code{disconnect} command, @value{GDBN} is again free to connect to 23674another target. 23675 23676@cindex send command to remote monitor 23677@cindex extend @value{GDBN} for remote targets 23678@cindex add new commands for external monitor 23679@kindex monitor 23680@item monitor @var{cmd} 23681This command allows you to send arbitrary commands directly to the 23682remote monitor. Since @value{GDBN} doesn't care about the commands it 23683sends like this, this command is the way to extend @value{GDBN}---you 23684can add new commands that only the external monitor will understand 23685and implement. 23686@end table 23687 23688@node File Transfer 23689@section Sending files to a remote system 23690@cindex remote target, file transfer 23691@cindex file transfer 23692@cindex sending files to remote systems 23693 23694Some remote targets offer the ability to transfer files over the same 23695connection used to communicate with @value{GDBN}. This is convenient 23696for targets accessible through other means, e.g.@: @sc{gnu}/Linux systems 23697running @code{gdbserver} over a network interface. For other targets, 23698e.g.@: embedded devices with only a single serial port, this may be 23699the only way to upload or download files. 23700 23701Not all remote targets support these commands. 23702 23703@table @code 23704@kindex remote put 23705@item remote put @var{hostfile} @var{targetfile} 23706Copy file @var{hostfile} from the host system (the machine running 23707@value{GDBN}) to @var{targetfile} on the target system. 23708 23709@kindex remote get 23710@item remote get @var{targetfile} @var{hostfile} 23711Copy file @var{targetfile} from the target system to @var{hostfile} 23712on the host system. 23713 23714@kindex remote delete 23715@item remote delete @var{targetfile} 23716Delete @var{targetfile} from the target system. 23717 23718@end table 23719 23720@node Server 23721@section Using the @code{gdbserver} Program 23722 23723@kindex gdbserver 23724@cindex remote connection without stubs 23725@code{gdbserver} is a control program for Unix-like systems, which 23726allows you to connect your program with a remote @value{GDBN} via 23727@code{target remote} or @code{target extended-remote}---but without 23728linking in the usual debugging stub. 23729 23730@code{gdbserver} is not a complete replacement for the debugging stubs, 23731because it requires essentially the same operating-system facilities 23732that @value{GDBN} itself does. In fact, a system that can run 23733@code{gdbserver} to connect to a remote @value{GDBN} could also run 23734@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless, 23735because it is a much smaller program than @value{GDBN} itself. It is 23736also easier to port than all of @value{GDBN}, so you may be able to get 23737started more quickly on a new system by using @code{gdbserver}. 23738Finally, if you develop code for real-time systems, you may find that 23739the tradeoffs involved in real-time operation make it more convenient to 23740do as much development work as possible on another system, for example 23741by cross-compiling. You can use @code{gdbserver} to make a similar 23742choice for debugging. 23743 23744@value{GDBN} and @code{gdbserver} communicate via either a serial line 23745or a TCP connection, using the standard @value{GDBN} remote serial 23746protocol. 23747 23748@quotation 23749@emph{Warning:} @code{gdbserver} does not have any built-in security. 23750Do not run @code{gdbserver} connected to any public network; a 23751@value{GDBN} connection to @code{gdbserver} provides access to the 23752target system with the same privileges as the user running 23753@code{gdbserver}. 23754@end quotation 23755 23756@anchor{Running gdbserver} 23757@subsection Running @code{gdbserver} 23758@cindex arguments, to @code{gdbserver} 23759@cindex @code{gdbserver}, command-line arguments 23760 23761Run @code{gdbserver} on the target system. You need a copy of the 23762program you want to debug, including any libraries it requires. 23763@code{gdbserver} does not need your program's symbol table, so you can 23764strip the program if necessary to save space. @value{GDBN} on the host 23765system does all the symbol handling. 23766 23767To use the server, you must tell it how to communicate with @value{GDBN}; 23768the name of your program; and the arguments for your program. The usual 23769syntax is: 23770 23771@smallexample 23772target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ] 23773@end smallexample 23774 23775@var{comm} is either a device name (to use a serial line), or a TCP 23776hostname and portnumber, or @code{-} or @code{stdio} to use 23777stdin/stdout of @code{gdbserver}. 23778For example, to debug Emacs with the argument 23779@samp{foo.txt} and communicate with @value{GDBN} over the serial port 23780@file{/dev/com1}: 23781 23782@smallexample 23783target> gdbserver /dev/com1 emacs foo.txt 23784@end smallexample 23785 23786@code{gdbserver} waits passively for the host @value{GDBN} to communicate 23787with it. 23788 23789To use a TCP connection instead of a serial line: 23790 23791@smallexample 23792target> gdbserver host:2345 emacs foo.txt 23793@end smallexample 23794 23795The only difference from the previous example is the first argument, 23796specifying that you are communicating with the host @value{GDBN} via 23797TCP. The @samp{host:2345} argument means that @code{gdbserver} is to 23798expect a TCP connection from machine @samp{host} to local TCP port 2345. 23799(Currently, the @samp{host} part is ignored.) You can choose any number 23800you want for the port number as long as it does not conflict with any 23801TCP ports already in use on the target system (for example, @code{23} is 23802reserved for @code{telnet}).@footnote{If you choose a port number that 23803conflicts with another service, @code{gdbserver} prints an error message 23804and exits.} You must use the same port number with the host @value{GDBN} 23805@code{target remote} command. 23806 23807The @code{stdio} connection is useful when starting @code{gdbserver} 23808with ssh: 23809 23810@smallexample 23811(@value{GDBP}) target remote | ssh -T hostname gdbserver - hello 23812@end smallexample 23813 23814The @samp{-T} option to ssh is provided because we don't need a remote pty, 23815and we don't want escape-character handling. Ssh does this by default when 23816a command is provided, the flag is provided to make it explicit. 23817You could elide it if you want to. 23818 23819Programs started with stdio-connected gdbserver have @file{/dev/null} for 23820@code{stdin}, and @code{stdout},@code{stderr} are sent back to gdb for 23821display through a pipe connected to gdbserver. 23822Both @code{stdout} and @code{stderr} use the same pipe. 23823 23824@anchor{Attaching to a program} 23825@subsubsection Attaching to a Running Program 23826@cindex attach to a program, @code{gdbserver} 23827@cindex @option{--attach}, @code{gdbserver} option 23828 23829On some targets, @code{gdbserver} can also attach to running programs. 23830This is accomplished via the @code{--attach} argument. The syntax is: 23831 23832@smallexample 23833target> gdbserver --attach @var{comm} @var{pid} 23834@end smallexample 23835 23836@var{pid} is the process ID of a currently running process. It isn't 23837necessary to point @code{gdbserver} at a binary for the running process. 23838 23839In @code{target extended-remote} mode, you can also attach using the 23840@value{GDBN} attach command 23841(@pxref{Attaching in Types of Remote Connections}). 23842 23843@pindex pidof 23844You can debug processes by name instead of process ID if your target has the 23845@code{pidof} utility: 23846 23847@smallexample 23848target> gdbserver --attach @var{comm} `pidof @var{program}` 23849@end smallexample 23850 23851In case more than one copy of @var{program} is running, or @var{program} 23852has multiple threads, most versions of @code{pidof} support the 23853@code{-s} option to only return the first process ID. 23854 23855@subsubsection TCP port allocation lifecycle of @code{gdbserver} 23856 23857This section applies only when @code{gdbserver} is run to listen on a TCP 23858port. 23859 23860@code{gdbserver} normally terminates after all of its debugged processes have 23861terminated in @kbd{target remote} mode. On the other hand, for @kbd{target 23862extended-remote}, @code{gdbserver} stays running even with no processes left. 23863@value{GDBN} normally terminates the spawned debugged process on its exit, 23864which normally also terminates @code{gdbserver} in the @kbd{target remote} 23865mode. Therefore, when the connection drops unexpectedly, and @value{GDBN} 23866cannot ask @code{gdbserver} to kill its debugged processes, @code{gdbserver} 23867stays running even in the @kbd{target remote} mode. 23868 23869When @code{gdbserver} stays running, @value{GDBN} can connect to it again later. 23870Such reconnecting is useful for features like @ref{disconnected tracing}. For 23871completeness, at most one @value{GDBN} can be connected at a time. 23872 23873@cindex @option{--once}, @code{gdbserver} option 23874By default, @code{gdbserver} keeps the listening TCP port open, so that 23875subsequent connections are possible. However, if you start @code{gdbserver} 23876with the @option{--once} option, it will stop listening for any further 23877connection attempts after connecting to the first @value{GDBN} session. This 23878means no further connections to @code{gdbserver} will be possible after the 23879first one. It also means @code{gdbserver} will terminate after the first 23880connection with remote @value{GDBN} has closed, even for unexpectedly closed 23881connections and even in the @kbd{target extended-remote} mode. The 23882@option{--once} option allows reusing the same port number for connecting to 23883multiple instances of @code{gdbserver} running on the same host, since each 23884instance closes its port after the first connection. 23885 23886@anchor{Other Command-Line Arguments for gdbserver} 23887@subsubsection Other Command-Line Arguments for @code{gdbserver} 23888 23889You can use the @option{--multi} option to start @code{gdbserver} without 23890specifying a program to debug or a process to attach to. Then you can 23891attach in @code{target extended-remote} mode and run or attach to a 23892program. For more information, 23893@pxref{--multi Option in Types of Remote Connnections}. 23894 23895@cindex @option{--debug}, @code{gdbserver} option 23896The @option{--debug[=option1,option2,@dots{}]} option tells 23897@code{gdbserver} to display extra diagnostic information about the 23898debugging process. The options (@var{option1}, @var{option2}, etc) 23899control for which areas of @code{gdbserver} additional information 23900will be displayed, possible values are: 23901 23902@table @code 23903@item all 23904This enables all available diagnostic output. 23905@item threads 23906This enables diagnostic output related to threading. Currently other 23907general diagnostic output is included in this category, but this could 23908change in future releases of @code{gdbserver}. 23909@item event-loop 23910This enables event-loop specific diagnostic output. 23911@item remote 23912This enables diagnostic output related to the transfer of remote 23913protocol packets too and from the debugger. 23914@end table 23915 23916@noindent 23917If no options are passed to @option{--debug} then this is treated as 23918equivalent to @option{--debug=threads}. This could change in future 23919releases of @code{gdbserver}. The options passed to @option{--debug} 23920are processed left to right, and individual options can be prefixed 23921with the @kbd{-} (minus) character to disable diagnostic output from 23922this area, so it is possible to use: 23923 23924@smallexample 23925 target> gdbserver --debug=all,-event-loop 23926@end smallexample 23927 23928@noindent 23929In order to enable all diagnostic output except that for the 23930event-loop. 23931 23932@cindex @option{--debug-file}, @code{gdbserver} option 23933@cindex @code{gdbserver}, send all debug output to a single file 23934The @option{--debug-file=@var{filename}} option tells @code{gdbserver} to 23935write any debug output to the given @var{filename}. These options are intended 23936for @code{gdbserver} development and for bug reports to the developers. 23937 23938@cindex @option{--debug-format}, @code{gdbserver} option 23939The @option{--debug-format=option1[,option2,...]} option tells 23940@code{gdbserver} to include additional information in each output. 23941Possible options are: 23942 23943@table @code 23944@item none 23945Turn off all extra information in debugging output. 23946@item all 23947Turn on all extra information in debugging output. 23948@item timestamps 23949Include a timestamp in each line of debugging output. 23950@end table 23951 23952Options are processed in order. Thus, for example, if @option{none} 23953appears last then no additional information is added to debugging output. 23954 23955@cindex @option{--wrapper}, @code{gdbserver} option 23956The @option{--wrapper} option specifies a wrapper to launch programs 23957for debugging. The option should be followed by the name of the 23958wrapper, then any command-line arguments to pass to the wrapper, then 23959@kbd{--} indicating the end of the wrapper arguments. 23960 23961@code{gdbserver} runs the specified wrapper program with a combined 23962command line including the wrapper arguments, then the name of the 23963program to debug, then any arguments to the program. The wrapper 23964runs until it executes your program, and then @value{GDBN} gains control. 23965 23966You can use any program that eventually calls @code{execve} with 23967its arguments as a wrapper. Several standard Unix utilities do 23968this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending 23969with @code{exec "$@@"} will also work. 23970 23971For example, you can use @code{env} to pass an environment variable to 23972the debugged program, without setting the variable in @code{gdbserver}'s 23973environment: 23974 23975@smallexample 23976$ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog 23977@end smallexample 23978 23979@cindex @option{--selftest} 23980The @option{--selftest} option runs the self tests in @code{gdbserver}: 23981 23982@smallexample 23983$ gdbserver --selftest 23984Ran 2 unit tests, 0 failed 23985@end smallexample 23986 23987These tests are disabled in release. 23988@subsection Connecting to @code{gdbserver} 23989 23990The basic procedure for connecting to the remote target is: 23991@itemize 23992 23993@item 23994Run @value{GDBN} on the host system. 23995 23996@item 23997Make sure you have the necessary symbol files 23998(@pxref{Host and target files}). 23999Load symbols for your application using the @code{file} command before you 24000connect. Use @code{set sysroot} to locate target libraries (unless your 24001@value{GDBN} was compiled with the correct sysroot using 24002@code{--with-sysroot}). 24003 24004@item 24005Connect to your target (@pxref{Connecting,,Connecting to a Remote Target}). 24006For TCP connections, you must start up @code{gdbserver} prior to using 24007the @code{target} command. Otherwise you may get an error whose 24008text depends on the host system, but which usually looks something like 24009@samp{Connection refused}. Don't use the @code{load} 24010command in @value{GDBN} when using @code{target remote} mode, since the 24011program is already on the target. 24012 24013@end itemize 24014 24015@anchor{Monitor Commands for gdbserver} 24016@subsection Monitor Commands for @code{gdbserver} 24017@cindex monitor commands, for @code{gdbserver} 24018 24019During a @value{GDBN} session using @code{gdbserver}, you can use the 24020@code{monitor} command to send special requests to @code{gdbserver}. 24021Here are the available commands. 24022 24023@table @code 24024@item monitor help 24025List the available monitor commands. 24026 24027@item monitor set debug off 24028Disable all internal logging from gdbserver. 24029 24030@item monitor set debug on 24031Enable some general logging from within gdbserver. Currently this is 24032equivalent to @kbd{monitor set debug threads on}, but this might 24033change in future releases of gdbserver. 24034 24035@item monitor set debug threads off 24036@itemx monitor set debug threads on 24037Disable or enable specific logging messages associated with thread 24038handling in gdbserver. Currently this category also includes 24039additional output not specifically related to thread handling, this 24040could change in future releases of gdbserver. 24041 24042@item monitor set debug remote off 24043@itemx monitor set debug remote on 24044Disable or enable specific logging messages associated with the remote 24045protocol (@pxref{Remote Protocol}). 24046 24047@item monitor set debug event-loop off 24048@itemx monitor set debug event-loop on 24049Disable or enable specific logging messages associated with 24050gdbserver's event-loop. 24051 24052@item monitor set debug-file filename 24053@itemx monitor set debug-file 24054Send any debug output to the given file, or to stderr. 24055 24056@item monitor set debug-format option1@r{[},option2,...@r{]} 24057Specify additional text to add to debugging messages. 24058Possible options are: 24059 24060@table @code 24061@item none 24062Turn off all extra information in debugging output. 24063@item all 24064Turn on all extra information in debugging output. 24065@item timestamps 24066Include a timestamp in each line of debugging output. 24067@end table 24068 24069Options are processed in order. Thus, for example, if @option{none} 24070appears last then no additional information is added to debugging output. 24071 24072@item monitor set libthread-db-search-path [PATH] 24073@cindex gdbserver, search path for @code{libthread_db} 24074When this command is issued, @var{path} is a colon-separated list of 24075directories to search for @code{libthread_db} (@pxref{Threads,,set 24076libthread-db-search-path}). If you omit @var{path}, 24077@samp{libthread-db-search-path} will be reset to its default value. 24078 24079The special entry @samp{$pdir} for @samp{libthread-db-search-path} is 24080not supported in @code{gdbserver}. 24081 24082@item monitor exit 24083Tell gdbserver to exit immediately. This command should be followed by 24084@code{disconnect} to close the debugging session. @code{gdbserver} will 24085detach from any attached processes and kill any processes it created. 24086Use @code{monitor exit} to terminate @code{gdbserver} at the end 24087of a multi-process mode debug session. 24088 24089@end table 24090 24091@subsection Tracepoints support in @code{gdbserver} 24092@cindex tracepoints support in @code{gdbserver} 24093 24094On some targets, @code{gdbserver} supports tracepoints, fast 24095tracepoints and static tracepoints. 24096 24097For fast or static tracepoints to work, a special library called the 24098@dfn{in-process agent} (IPA), must be loaded in the inferior process. 24099This library is built and distributed as an integral part of 24100@code{gdbserver}. In addition, support for static tracepoints 24101requires building the in-process agent library with static tracepoints 24102support. At present, the UST (LTTng Userspace Tracer, 24103@url{http://lttng.org/ust}) tracing engine is supported. This support 24104is automatically available if UST development headers are found in the 24105standard include path when @code{gdbserver} is built, or if 24106@code{gdbserver} was explicitly configured using @option{--with-ust} 24107to point at such headers. You can explicitly disable the support 24108using @option{--with-ust=no}. 24109 24110There are several ways to load the in-process agent in your program: 24111 24112@table @code 24113@item Specifying it as dependency at link time 24114 24115You can link your program dynamically with the in-process agent 24116library. On most systems, this is accomplished by adding 24117@code{-linproctrace} to the link command. 24118 24119@item Using the system's preloading mechanisms 24120 24121You can force loading the in-process agent at startup time by using 24122your system's support for preloading shared libraries. Many Unixes 24123support the concept of preloading user defined libraries. In most 24124cases, you do that by specifying @code{LD_PRELOAD=libinproctrace.so} 24125in the environment. See also the description of @code{gdbserver}'s 24126@option{--wrapper} command line option. 24127 24128@item Using @value{GDBN} to force loading the agent at run time 24129 24130On some systems, you can force the inferior to load a shared library, 24131by calling a dynamic loader function in the inferior that takes care 24132of dynamically looking up and loading a shared library. On most Unix 24133systems, the function is @code{dlopen}. You'll use the @code{call} 24134command for that. For example: 24135 24136@smallexample 24137(@value{GDBP}) call dlopen ("libinproctrace.so", ...) 24138@end smallexample 24139 24140Note that on most Unix systems, for the @code{dlopen} function to be 24141available, the program needs to be linked with @code{-ldl}. 24142@end table 24143 24144On systems that have a userspace dynamic loader, like most Unix 24145systems, when you connect to @code{gdbserver} using @code{target 24146remote}, you'll find that the program is stopped at the dynamic 24147loader's entry point, and no shared library has been loaded in the 24148program's address space yet, including the in-process agent. In that 24149case, before being able to use any of the fast or static tracepoints 24150features, you need to let the loader run and load the shared 24151libraries. The simplest way to do that is to run the program to the 24152main procedure. E.g., if debugging a C or C@t{++} program, start 24153@code{gdbserver} like so: 24154 24155@smallexample 24156$ gdbserver :9999 myprogram 24157@end smallexample 24158 24159Start GDB and connect to @code{gdbserver} like so, and run to main: 24160 24161@smallexample 24162$ gdb myprogram 24163(@value{GDBP}) target remote myhost:9999 241640x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2 24165(@value{GDBP}) b main 24166(@value{GDBP}) continue 24167@end smallexample 24168 24169The in-process tracing agent library should now be loaded into the 24170process; you can confirm it with the @code{info sharedlibrary} 24171command, which will list @file{libinproctrace.so} as loaded in the 24172process. You are now ready to install fast tracepoints, list static 24173tracepoint markers, probe static tracepoints markers, and start 24174tracing. 24175 24176@node Remote Configuration 24177@section Remote Configuration 24178 24179@kindex set remote 24180@kindex show remote 24181This section documents the configuration options available when 24182debugging remote programs. For the options related to the File I/O 24183extensions of the remote protocol, see @ref{system, 24184system-call-allowed}. 24185 24186@table @code 24187@item set remoteaddresssize @var{bits} 24188@cindex address size for remote targets 24189@cindex bits in remote address 24190Set the maximum size of address in a memory packet to the specified 24191number of bits. @value{GDBN} will mask off the address bits above 24192that number, when it passes addresses to the remote target. The 24193default value is the number of bits in the target's address. 24194 24195@item show remoteaddresssize 24196Show the current value of remote address size in bits. 24197 24198@item set serial baud @var{n} 24199@cindex baud rate for remote targets 24200Set the baud rate for the remote serial I/O to @var{n} baud. The 24201value is used to set the speed of the serial port used for debugging 24202remote targets. 24203 24204@item show serial baud 24205Show the current speed of the remote connection. 24206 24207@item set serial parity @var{parity} 24208Set the parity for the remote serial I/O. Supported values of @var{parity} are: 24209@code{even}, @code{none}, and @code{odd}. The default is @code{none}. 24210 24211@item show serial parity 24212Show the current parity of the serial port. 24213 24214@item set remotebreak 24215@cindex interrupt remote programs 24216@cindex BREAK signal instead of Ctrl-C 24217@anchor{set remotebreak} 24218If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote 24219when you type @kbd{Ctrl-c} to interrupt the program running 24220on the remote. If set to off, @value{GDBN} sends the @samp{Ctrl-C} 24221character instead. The default is off, since most remote systems 24222expect to see @samp{Ctrl-C} as the interrupt signal. 24223 24224@item show remotebreak 24225Show whether @value{GDBN} sends @code{BREAK} or @samp{Ctrl-C} to 24226interrupt the remote program. 24227 24228@item set remoteflow on 24229@itemx set remoteflow off 24230@kindex set remoteflow 24231Enable or disable hardware flow control (@code{RTS}/@code{CTS}) 24232on the serial port used to communicate to the remote target. 24233 24234@item show remoteflow 24235@kindex show remoteflow 24236Show the current setting of hardware flow control. 24237 24238@item set remotelogbase @var{base} 24239Set the base (a.k.a.@: radix) of logging serial protocol 24240communications to @var{base}. Supported values of @var{base} are: 24241@code{ascii}, @code{octal}, and @code{hex}. The default is 24242@code{ascii}. 24243 24244@item show remotelogbase 24245Show the current setting of the radix for logging remote serial 24246protocol. 24247 24248@item set remotelogfile @var{file} 24249@cindex record serial communications on file 24250Record remote serial communications on the named @var{file}. The 24251default is not to record at all. 24252 24253@item show remotelogfile 24254Show the current setting of the file name on which to record the 24255serial communications. 24256 24257@item set remotetimeout @var{num} 24258@cindex timeout for serial communications 24259@cindex remote timeout 24260Set the timeout limit to wait for the remote target to respond to 24261@var{num} seconds. The default is 2 seconds. 24262 24263@item show remotetimeout 24264Show the current number of seconds to wait for the remote target 24265responses. 24266 24267@cindex limit hardware breakpoints and watchpoints 24268@cindex remote target, limit break- and watchpoints 24269@anchor{set remote hardware-watchpoint-limit} 24270@anchor{set remote hardware-breakpoint-limit} 24271@item set remote hardware-watchpoint-limit @var{limit} 24272@itemx set remote hardware-breakpoint-limit @var{limit} 24273Restrict @value{GDBN} to using @var{limit} remote hardware watchpoints 24274or breakpoints. The @var{limit} can be set to 0 to disable hardware 24275watchpoints or breakpoints, and @code{unlimited} for unlimited 24276watchpoints or breakpoints. 24277 24278@item show remote hardware-watchpoint-limit 24279@itemx show remote hardware-breakpoint-limit 24280Show the current limit for the number of hardware watchpoints or 24281breakpoints that @value{GDBN} can use. 24282 24283@cindex limit hardware watchpoints length 24284@cindex remote target, limit watchpoints length 24285@anchor{set remote hardware-watchpoint-length-limit} 24286@item set remote hardware-watchpoint-length-limit @var{limit} 24287Restrict @value{GDBN} to using @var{limit} bytes for the maximum 24288length of a remote hardware watchpoint. A @var{limit} of 0 disables 24289hardware watchpoints and @code{unlimited} allows watchpoints of any 24290length. 24291 24292@item show remote hardware-watchpoint-length-limit 24293Show the current limit (in bytes) of the maximum length of 24294a remote hardware watchpoint. 24295 24296@item set remote exec-file @var{filename} 24297@itemx show remote exec-file 24298@anchor{set remote exec-file} 24299@cindex executable file, for remote target 24300Select the file used for @code{run} with @code{target 24301extended-remote}. This should be set to a filename valid on the 24302target system. If it is not set, the target will use a default 24303filename (e.g.@: the last program run). 24304 24305@item set remote interrupt-sequence 24306@cindex interrupt remote programs 24307@cindex select Ctrl-C, BREAK or BREAK-g 24308Allow the user to select one of @samp{Ctrl-C}, a @code{BREAK} or 24309@samp{BREAK-g} as the 24310sequence to the remote target in order to interrupt the execution. 24311@samp{Ctrl-C} is a default. Some system prefers @code{BREAK} which 24312is high level of serial line for some certain time. 24313Linux kernel prefers @samp{BREAK-g}, a.k.a Magic SysRq g. 24314It is @code{BREAK} signal followed by character @code{g}. 24315 24316@item show remote interrupt-sequence 24317Show which of @samp{Ctrl-C}, @code{BREAK} or @code{BREAK-g} 24318is sent by @value{GDBN} to interrupt the remote program. 24319@code{BREAK-g} is BREAK signal followed by @code{g} and 24320also known as Magic SysRq g. 24321 24322@item set remote interrupt-on-connect 24323@cindex send interrupt-sequence on start 24324Specify whether interrupt-sequence is sent to remote target when 24325@value{GDBN} connects to it. This is mostly needed when you debug 24326Linux kernel. Linux kernel expects @code{BREAK} followed by @code{g} 24327which is known as Magic SysRq g in order to connect @value{GDBN}. 24328 24329@item show remote interrupt-on-connect 24330Show whether interrupt-sequence is sent 24331to remote target when @value{GDBN} connects to it. 24332 24333@kindex set tcp 24334@kindex show tcp 24335@item set tcp auto-retry on 24336@cindex auto-retry, for remote TCP target 24337Enable auto-retry for remote TCP connections. This is useful if the remote 24338debugging agent is launched in parallel with @value{GDBN}; there is a race 24339condition because the agent may not become ready to accept the connection 24340before @value{GDBN} attempts to connect. When auto-retry is 24341enabled, if the initial attempt to connect fails, @value{GDBN} reattempts 24342to establish the connection using the timeout specified by 24343@code{set tcp connect-timeout}. 24344 24345@item set tcp auto-retry off 24346Do not auto-retry failed TCP connections. 24347 24348@item show tcp auto-retry 24349Show the current auto-retry setting. 24350 24351@item set tcp connect-timeout @var{seconds} 24352@itemx set tcp connect-timeout unlimited 24353@cindex connection timeout, for remote TCP target 24354@cindex timeout, for remote target connection 24355Set the timeout for establishing a TCP connection to the remote target to 24356@var{seconds}. The timeout affects both polling to retry failed connections 24357(enabled by @code{set tcp auto-retry on}) and waiting for connections 24358that are merely slow to complete, and represents an approximate cumulative 24359value. If @var{seconds} is @code{unlimited}, there is no timeout and 24360@value{GDBN} will keep attempting to establish a connection forever, 24361unless interrupted with @kbd{Ctrl-c}. The default is 15 seconds. 24362 24363@item show tcp connect-timeout 24364Show the current connection timeout setting. 24365@end table 24366 24367@cindex remote packets, enabling and disabling 24368The @value{GDBN} remote protocol autodetects the packets supported by 24369your debugging stub. If you need to override the autodetection, you 24370can use these commands to enable or disable individual packets. Each 24371packet can be set to @samp{on} (the remote target supports this 24372packet), @samp{off} (the remote target does not support this packet), 24373or @samp{auto} (detect remote target support for this packet). They 24374all default to @samp{auto}. For more information about each packet, 24375see @ref{Remote Protocol}. 24376 24377During normal use, you should not have to use any of these commands. 24378If you do, that may be a bug in your remote debugging stub, or a bug 24379in @value{GDBN}. You may want to report the problem to the 24380@value{GDBN} developers. 24381 24382For each packet @var{name}, the command to enable or disable the 24383packet is @code{set remote @var{name}-packet}. If you configure a packet, the 24384configuration will apply for all future remote targets if no target is selected. 24385In case there is a target selected, only the configuration of the current target 24386is changed. All other existing remote targets' features are not affected. 24387The command to print the current configuration of a packet is 24388@code{show remote @var{name}-packet}. It displays the current remote target's 24389configuration. If no remote target is selected, the default configuration for 24390future connections is shown. The available settings are: 24391 24392@multitable @columnfractions 0.28 0.32 0.25 24393@item Command Name 24394@tab Remote Packet 24395@tab Related Features 24396 24397@item @code{fetch-register} 24398@tab @code{p} 24399@tab @code{info registers} 24400 24401@item @code{set-register} 24402@tab @code{P} 24403@tab @code{set} 24404 24405@item @code{binary-download} 24406@tab @code{X} 24407@tab @code{load}, @code{set} 24408 24409@item @code{read-aux-vector} 24410@tab @code{qXfer:auxv:read} 24411@tab @code{info auxv} 24412 24413@item @code{symbol-lookup} 24414@tab @code{qSymbol} 24415@tab Detecting multiple threads 24416 24417@item @code{attach} 24418@tab @code{vAttach} 24419@tab @code{attach} 24420 24421@item @code{verbose-resume} 24422@tab @code{vCont} 24423@tab Stepping or resuming multiple threads 24424 24425@item @code{run} 24426@tab @code{vRun} 24427@tab @code{run} 24428 24429@item @code{software-breakpoint} 24430@tab @code{Z0} 24431@tab @code{break} 24432 24433@item @code{hardware-breakpoint} 24434@tab @code{Z1} 24435@tab @code{hbreak} 24436 24437@item @code{write-watchpoint} 24438@tab @code{Z2} 24439@tab @code{watch} 24440 24441@item @code{read-watchpoint} 24442@tab @code{Z3} 24443@tab @code{rwatch} 24444 24445@item @code{access-watchpoint} 24446@tab @code{Z4} 24447@tab @code{awatch} 24448 24449@item @code{pid-to-exec-file} 24450@tab @code{qXfer:exec-file:read} 24451@tab @code{attach}, @code{run} 24452 24453@item @code{target-features} 24454@tab @code{qXfer:features:read} 24455@tab @code{set architecture} 24456 24457@item @code{library-info} 24458@tab @code{qXfer:libraries:read} 24459@tab @code{info sharedlibrary} 24460 24461@item @code{memory-map} 24462@tab @code{qXfer:memory-map:read} 24463@tab @code{info mem} 24464 24465@item @code{read-sdata-object} 24466@tab @code{qXfer:sdata:read} 24467@tab @code{print $_sdata} 24468 24469@item @code{read-siginfo-object} 24470@tab @code{qXfer:siginfo:read} 24471@tab @code{print $_siginfo} 24472 24473@item @code{write-siginfo-object} 24474@tab @code{qXfer:siginfo:write} 24475@tab @code{set $_siginfo} 24476 24477@item @code{threads} 24478@tab @code{qXfer:threads:read} 24479@tab @code{info threads} 24480 24481@item @code{get-thread-local-@*storage-address} 24482@tab @code{qGetTLSAddr} 24483@tab Displaying @code{__thread} variables 24484 24485@item @code{get-thread-information-block-address} 24486@tab @code{qGetTIBAddr} 24487@tab Display MS-Windows Thread Information Block. 24488 24489@item @code{search-memory} 24490@tab @code{qSearch:memory} 24491@tab @code{find} 24492 24493@item @code{supported-packets} 24494@tab @code{qSupported} 24495@tab Remote communications parameters 24496 24497@item @code{catch-syscalls} 24498@tab @code{QCatchSyscalls} 24499@tab @code{catch syscall} 24500 24501@item @code{pass-signals} 24502@tab @code{QPassSignals} 24503@tab @code{handle @var{signal}} 24504 24505@item @code{program-signals} 24506@tab @code{QProgramSignals} 24507@tab @code{handle @var{signal}} 24508 24509@item @code{hostio-close-packet} 24510@tab @code{vFile:close} 24511@tab @code{remote get}, @code{remote put} 24512 24513@item @code{hostio-open-packet} 24514@tab @code{vFile:open} 24515@tab @code{remote get}, @code{remote put} 24516 24517@item @code{hostio-pread-packet} 24518@tab @code{vFile:pread} 24519@tab @code{remote get}, @code{remote put} 24520 24521@item @code{hostio-pwrite-packet} 24522@tab @code{vFile:pwrite} 24523@tab @code{remote get}, @code{remote put} 24524 24525@item @code{hostio-unlink-packet} 24526@tab @code{vFile:unlink} 24527@tab @code{remote delete} 24528 24529@item @code{hostio-readlink-packet} 24530@tab @code{vFile:readlink} 24531@tab Host I/O 24532 24533@item @code{hostio-fstat-packet} 24534@tab @code{vFile:fstat} 24535@tab Host I/O 24536 24537@item @code{hostio-setfs-packet} 24538@tab @code{vFile:setfs} 24539@tab Host I/O 24540 24541@item @code{noack-packet} 24542@tab @code{QStartNoAckMode} 24543@tab Packet acknowledgment 24544 24545@item @code{osdata} 24546@tab @code{qXfer:osdata:read} 24547@tab @code{info os} 24548 24549@item @code{query-attached} 24550@tab @code{qAttached} 24551@tab Querying remote process attach state. 24552 24553@item @code{trace-buffer-size} 24554@tab @code{QTBuffer:size} 24555@tab @code{set trace-buffer-size} 24556 24557@item @code{trace-status} 24558@tab @code{qTStatus} 24559@tab @code{tstatus} 24560 24561@item @code{traceframe-info} 24562@tab @code{qXfer:traceframe-info:read} 24563@tab Traceframe info 24564 24565@item @code{install-in-trace} 24566@tab @code{InstallInTrace} 24567@tab Install tracepoint in tracing 24568 24569@item @code{disable-randomization} 24570@tab @code{QDisableRandomization} 24571@tab @code{set disable-randomization} 24572 24573@item @code{startup-with-shell} 24574@tab @code{QStartupWithShell} 24575@tab @code{set startup-with-shell} 24576 24577@item @code{environment-hex-encoded} 24578@tab @code{QEnvironmentHexEncoded} 24579@tab @code{set environment} 24580 24581@item @code{environment-unset} 24582@tab @code{QEnvironmentUnset} 24583@tab @code{unset environment} 24584 24585@item @code{environment-reset} 24586@tab @code{QEnvironmentReset} 24587@tab @code{Reset the inferior environment (i.e., unset user-set variables)} 24588 24589@item @code{set-working-dir} 24590@tab @code{QSetWorkingDir} 24591@tab @code{set cwd} 24592 24593@item @code{conditional-breakpoints-packet} 24594@tab @code{Z0 and Z1} 24595@tab @code{Support for target-side breakpoint condition evaluation} 24596 24597@item @code{multiprocess-extensions} 24598@tab @code{multiprocess extensions} 24599@tab Debug multiple processes and remote process PID awareness 24600 24601@item @code{swbreak-feature} 24602@tab @code{swbreak stop reason} 24603@tab @code{break} 24604 24605@item @code{hwbreak-feature} 24606@tab @code{hwbreak stop reason} 24607@tab @code{hbreak} 24608 24609@item @code{fork-event-feature} 24610@tab @code{fork stop reason} 24611@tab @code{fork} 24612 24613@item @code{vfork-event-feature} 24614@tab @code{vfork stop reason} 24615@tab @code{vfork} 24616 24617@item @code{exec-event-feature} 24618@tab @code{exec stop reason} 24619@tab @code{exec} 24620 24621@item @code{thread-events} 24622@tab @code{QThreadEvents} 24623@tab Tracking thread lifetime. 24624 24625@item @code{thread-options} 24626@tab @code{QThreadOptions} 24627@tab Set thread event reporting options. 24628 24629@item @code{no-resumed-stop-reply} 24630@tab @code{no resumed thread left stop reply} 24631@tab Tracking thread lifetime. 24632 24633@end multitable 24634 24635@cindex packet size, remote, configuring 24636The number of bytes per memory-read or memory-write packet for a remote target 24637can be configured using the commands 24638@w{@code{set remote memory-read-packet-size}} and 24639@w{@code{set remote memory-write-packet-size}}. If set to @samp{0} (zero) the 24640default packet size will be used. The actual limit is further reduced depending 24641on the target. Specify @samp{fixed} to disable the target-dependent restriction 24642and @samp{limit} to enable it. Similar to the enabling and disabling of remote 24643packets, the command applies to the currently selected target (if available). 24644If no remote target is selected, it applies to all future remote connections. 24645The configuration of the selected target can be displayed using the commands 24646@w{@code{show remote memory-read-packet-size}} and 24647@w{@code{show remote memory-write-packet-size}}. If no remote target is 24648selected, the default configuration for future connections is shown. 24649 24650@node Remote Stub 24651@section Implementing a Remote Stub 24652 24653@cindex debugging stub, example 24654@cindex remote stub, example 24655@cindex stub example, remote debugging 24656The stub files provided with @value{GDBN} implement the target side of the 24657communication protocol, and the @value{GDBN} side is implemented in the 24658@value{GDBN} source file @file{remote.c}. Normally, you can simply allow 24659these subroutines to communicate, and ignore the details. (If you're 24660implementing your own stub file, you can still ignore the details: start 24661with one of the existing stub files. @file{sparc-stub.c} is the best 24662organized, and therefore the easiest to read.) 24663 24664@cindex remote serial debugging, overview 24665To debug a program running on another machine (the debugging 24666@dfn{target} machine), you must first arrange for all the usual 24667prerequisites for the program to run by itself. For example, for a C 24668program, you need: 24669 24670@enumerate 24671@item 24672A startup routine to set up the C runtime environment; these usually 24673have a name like @file{crt0}. The startup routine may be supplied by 24674your hardware supplier, or you may have to write your own. 24675 24676@item 24677A C subroutine library to support your program's 24678subroutine calls, notably managing input and output. 24679 24680@item 24681A way of getting your program to the other machine---for example, a 24682download program. These are often supplied by the hardware 24683manufacturer, but you may have to write your own from hardware 24684documentation. 24685@end enumerate 24686 24687The next step is to arrange for your program to use a serial port to 24688communicate with the machine where @value{GDBN} is running (the @dfn{host} 24689machine). In general terms, the scheme looks like this: 24690 24691@table @emph 24692@item On the host, 24693@value{GDBN} already understands how to use this protocol; when everything 24694else is set up, you can simply use the @samp{target remote} command 24695(@pxref{Targets,,Specifying a Debugging Target}). 24696 24697@item On the target, 24698you must link with your program a few special-purpose subroutines that 24699implement the @value{GDBN} remote serial protocol. The file containing these 24700subroutines is called a @dfn{debugging stub}. 24701 24702On certain remote targets, you can use an auxiliary program 24703@code{gdbserver} instead of linking a stub into your program. 24704@xref{Server,,Using the @code{gdbserver} Program}, for details. 24705@end table 24706 24707The debugging stub is specific to the architecture of the remote 24708machine; for example, use @file{sparc-stub.c} to debug programs on 24709@sc{sparc} boards. 24710 24711@cindex remote serial stub list 24712These working remote stubs are distributed with @value{GDBN}: 24713 24714@table @code 24715 24716@item i386-stub.c 24717@cindex @file{i386-stub.c} 24718@cindex Intel 24719@cindex i386 24720For Intel 386 and compatible architectures. 24721 24722@item m68k-stub.c 24723@cindex @file{m68k-stub.c} 24724@cindex Motorola 680x0 24725@cindex m680x0 24726For Motorola 680x0 architectures. 24727 24728@item sh-stub.c 24729@cindex @file{sh-stub.c} 24730@cindex Renesas 24731@cindex SH 24732For Renesas SH architectures. 24733 24734@item sparc-stub.c 24735@cindex @file{sparc-stub.c} 24736@cindex Sparc 24737For @sc{sparc} architectures. 24738 24739@item sparcl-stub.c 24740@cindex @file{sparcl-stub.c} 24741@cindex Fujitsu 24742@cindex SparcLite 24743For Fujitsu @sc{sparclite} architectures. 24744 24745@end table 24746 24747The @file{README} file in the @value{GDBN} distribution may list other 24748recently added stubs. 24749 24750@menu 24751* Stub Contents:: What the stub can do for you 24752* Bootstrapping:: What you must do for the stub 24753* Debug Session:: Putting it all together 24754@end menu 24755 24756@node Stub Contents 24757@subsection What the Stub Can Do for You 24758 24759@cindex remote serial stub 24760The debugging stub for your architecture supplies these three 24761subroutines: 24762 24763@table @code 24764@findex set_debug_traps 24765@item set_debug_traps 24766@cindex remote serial stub, initialization 24767This routine arranges for @code{handle_exception} to run when your 24768program stops. You must call this subroutine explicitly in your 24769program's startup code. 24770 24771@findex handle_exception 24772@item handle_exception 24773@cindex remote serial stub, main routine 24774This is the central workhorse, but your program never calls it 24775explicitly---the setup code arranges for @code{handle_exception} to 24776run when a trap is triggered. 24777 24778@code{handle_exception} takes control when your program stops during 24779execution (for example, on a breakpoint), and mediates communications 24780with @value{GDBN} on the host machine. This is where the communications 24781protocol is implemented; @code{handle_exception} acts as the @value{GDBN} 24782representative on the target machine. It begins by sending summary 24783information on the state of your program, then continues to execute, 24784retrieving and transmitting any information @value{GDBN} needs, until you 24785execute a @value{GDBN} command that makes your program resume; at that point, 24786@code{handle_exception} returns control to your own code on the target 24787machine. 24788 24789@item breakpoint 24790@cindex @code{breakpoint} subroutine, remote 24791Use this auxiliary subroutine to make your program contain a 24792breakpoint. Depending on the particular situation, this may be the only 24793way for @value{GDBN} to get control. For instance, if your target 24794machine has some sort of interrupt button, you won't need to call this; 24795pressing the interrupt button transfers control to 24796@code{handle_exception}---in effect, to @value{GDBN}. On some machines, 24797simply receiving characters on the serial port may also trigger a trap; 24798again, in that situation, you don't need to call @code{breakpoint} from 24799your own program---simply running @samp{target remote} from the host 24800@value{GDBN} session gets control. 24801 24802Call @code{breakpoint} if none of these is true, or if you simply want 24803to make certain your program stops at a predetermined point for the 24804start of your debugging session. 24805@end table 24806 24807@node Bootstrapping 24808@subsection What You Must Do for the Stub 24809 24810@cindex remote stub, support routines 24811The debugging stubs that come with @value{GDBN} are set up for a particular 24812chip architecture, but they have no information about the rest of your 24813debugging target machine. 24814 24815First of all you need to tell the stub how to communicate with the 24816serial port. 24817 24818@table @code 24819@findex getDebugChar 24820@item int getDebugChar() 24821Write this subroutine to read a single character from the serial port. 24822It may be identical to @code{getchar} for your target system; a 24823different name is used to allow you to distinguish the two if you wish. 24824 24825@findex putDebugChar 24826@item void putDebugChar(int) 24827Write this subroutine to write a single character to the serial port. 24828It may be identical to @code{putchar} for your target system; a 24829different name is used to allow you to distinguish the two if you wish. 24830@end table 24831 24832@cindex control C, and remote debugging 24833@cindex interrupting remote targets 24834If you want @value{GDBN} to be able to stop your program while it is 24835running, you need to use an interrupt-driven serial driver, and arrange 24836for it to stop when it receives a @code{^C} (@samp{\003}, the control-C 24837character). That is the character which @value{GDBN} uses to tell the 24838remote system to stop. 24839 24840Getting the debugging target to return the proper status to @value{GDBN} 24841probably requires changes to the standard stub; one quick and dirty way 24842is to just execute a breakpoint instruction (the ``dirty'' part is that 24843@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}). 24844 24845Other routines you need to supply are: 24846 24847@table @code 24848@findex exceptionHandler 24849@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address}) 24850Write this function to install @var{exception_address} in the exception 24851handling tables. You need to do this because the stub does not have any 24852way of knowing what the exception handling tables on your target system 24853are like (for example, the processor's table might be in @sc{rom}, 24854containing entries which point to a table in @sc{ram}). 24855The @var{exception_number} specifies the exception which should be changed; 24856its meaning is architecture-dependent (for example, different numbers 24857might represent divide by zero, misaligned access, etc). When this 24858exception occurs, control should be transferred directly to 24859@var{exception_address}, and the processor state (stack, registers, 24860and so on) should be just as it is when a processor exception occurs. So if 24861you want to use a jump instruction to reach @var{exception_address}, it 24862should be a simple jump, not a jump to subroutine. 24863 24864For the 386, @var{exception_address} should be installed as an interrupt 24865gate so that interrupts are masked while the handler runs. The gate 24866should be at privilege level 0 (the most privileged level). The 24867@sc{sparc} and 68k stubs are able to mask interrupts themselves without 24868help from @code{exceptionHandler}. 24869 24870@findex flush_i_cache 24871@item void flush_i_cache() 24872On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the 24873instruction cache, if any, on your target machine. If there is no 24874instruction cache, this subroutine may be a no-op. 24875 24876On target machines that have instruction caches, @value{GDBN} requires this 24877function to make certain that the state of your program is stable. 24878@end table 24879 24880@noindent 24881You must also make sure this library routine is available: 24882 24883@table @code 24884@findex memset 24885@item void *memset(void *, int, int) 24886This is the standard library function @code{memset} that sets an area of 24887memory to a known value. If you have one of the free versions of 24888@code{libc.a}, @code{memset} can be found there; otherwise, you must 24889either obtain it from your hardware manufacturer, or write your own. 24890@end table 24891 24892If you do not use the GNU C compiler, you may need other standard 24893library subroutines as well; this varies from one stub to another, 24894but in general the stubs are likely to use any of the common library 24895subroutines which @code{@value{NGCC}} generates as inline code. 24896 24897 24898@node Debug Session 24899@subsection Putting it All Together 24900 24901@cindex remote serial debugging summary 24902In summary, when your program is ready to debug, you must follow these 24903steps. 24904 24905@enumerate 24906@item 24907Make sure you have defined the supporting low-level routines 24908(@pxref{Bootstrapping,,What You Must Do for the Stub}): 24909@display 24910@code{getDebugChar}, @code{putDebugChar}, 24911@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}. 24912@end display 24913 24914@item 24915Insert these lines in your program's startup code, before the main 24916procedure is called: 24917 24918@smallexample 24919set_debug_traps(); 24920breakpoint(); 24921@end smallexample 24922 24923On some machines, when a breakpoint trap is raised, the hardware 24924automatically makes the PC point to the instruction after the 24925breakpoint. If your machine doesn't do that, you may need to adjust 24926@code{handle_exception} to arrange for it to return to the instruction 24927after the breakpoint on this first invocation, so that your program 24928doesn't keep hitting the initial breakpoint instead of making 24929progress. 24930 24931@item 24932For the 680x0 stub only, you need to provide a variable called 24933@code{exceptionHook}. Normally you just use: 24934 24935@smallexample 24936void (*exceptionHook)() = 0; 24937@end smallexample 24938 24939@noindent 24940but if before calling @code{set_debug_traps}, you set it to point to a 24941function in your program, that function is called when 24942@code{@value{GDBN}} continues after stopping on a trap (for example, bus 24943error). The function indicated by @code{exceptionHook} is called with 24944one parameter: an @code{int} which is the exception number. 24945 24946@item 24947Compile and link together: your program, the @value{GDBN} debugging stub for 24948your target architecture, and the supporting subroutines. 24949 24950@item 24951Make sure you have a serial connection between your target machine and 24952the @value{GDBN} host, and identify the serial port on the host. 24953 24954@item 24955@c The "remote" target now provides a `load' command, so we should 24956@c document that. FIXME. 24957Download your program to your target machine (or get it there by 24958whatever means the manufacturer provides), and start it. 24959 24960@item 24961Start @value{GDBN} on the host, and connect to the target 24962(@pxref{Connecting,,Connecting to a Remote Target}). 24963 24964@end enumerate 24965 24966@node Configurations 24967@chapter Configuration-Specific Information 24968 24969While nearly all @value{GDBN} commands are available for all native and 24970cross versions of the debugger, there are some exceptions. This chapter 24971describes things that are only available in certain configurations. 24972 24973There are three major categories of configurations: native 24974configurations, where the host and target are the same, embedded 24975operating system configurations, which are usually the same for several 24976different processor architectures, and bare embedded processors, which 24977are quite different from each other. 24978 24979@menu 24980* Native:: 24981* Embedded OS:: 24982* Embedded Processors:: 24983* Architectures:: 24984@end menu 24985 24986@node Native 24987@section Native 24988 24989This section describes details specific to particular native 24990configurations. 24991 24992@menu 24993* BSD libkvm Interface:: Debugging BSD kernel memory images 24994* Process Information:: Process information 24995* DJGPP Native:: Features specific to the DJGPP port 24996* Cygwin Native:: Features specific to the Cygwin port 24997* Hurd Native:: Features specific to @sc{gnu} Hurd 24998* Darwin:: Features specific to Darwin 24999* FreeBSD:: Features specific to FreeBSD 25000@end menu 25001 25002@node BSD libkvm Interface 25003@subsection BSD libkvm Interface 25004 25005@cindex libkvm 25006@cindex kernel memory image 25007@cindex kernel crash dump 25008 25009BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory 25010interface that provides a uniform interface for accessing kernel virtual 25011memory images, including live systems and crash dumps. @value{GDBN} 25012uses this interface to allow you to debug live kernels and kernel crash 25013dumps on many native BSD configurations. This is implemented as a 25014special @code{kvm} debugging target. For debugging a live system, load 25015the currently running kernel into @value{GDBN} and connect to the 25016@code{kvm} target: 25017 25018@smallexample 25019(@value{GDBP}) @b{target kvm} 25020@end smallexample 25021 25022For debugging crash dumps, provide the file name of the crash dump as an 25023argument: 25024 25025@smallexample 25026(@value{GDBP}) @b{target kvm /var/crash/bsd.0} 25027@end smallexample 25028 25029Once connected to the @code{kvm} target, the following commands are 25030available: 25031 25032@table @code 25033@kindex kvm 25034@item kvm pcb 25035Set current context from the @dfn{Process Control Block} (PCB) address. 25036 25037@item kvm proc 25038Set current context from proc address. This command isn't available on 25039modern FreeBSD systems. 25040@end table 25041 25042@node Process Information 25043@subsection Process Information 25044@cindex /proc 25045@cindex examine process image 25046@cindex process info via @file{/proc} 25047 25048Some operating systems provide interfaces to fetch additional 25049information about running processes beyond memory and per-thread 25050register state. If @value{GDBN} is configured for an operating system 25051with a supported interface, the command @code{info proc} is available 25052to report information about the process running your program, or about 25053any process running on your system. 25054 25055One supported interface is a facility called @samp{/proc} that can be 25056used to examine the image of a running process using file-system 25057subroutines. This facility is supported on @sc{gnu}/Linux and Solaris 25058systems. 25059 25060On FreeBSD and NetBSD systems, system control nodes are used to query 25061process information. 25062 25063In addition, some systems may provide additional process information 25064in core files. Note that a core file may include a subset of the 25065information available from a live process. Process information is 25066currently available from cores created on @sc{gnu}/Linux and FreeBSD 25067systems. 25068 25069@table @code 25070@kindex info proc 25071@cindex process ID 25072@item info proc 25073@itemx info proc @var{process-id} 25074Summarize available information about a process. If a 25075process ID is specified by @var{process-id}, display information about 25076that process; otherwise display information about the program being 25077debugged. The summary includes the debugged process ID, the command 25078line used to invoke it, its current working directory, and its 25079executable file's absolute file name. 25080 25081On some systems, @var{process-id} can be of the form 25082@samp{[@var{pid}]/@var{tid}} which specifies a certain thread ID 25083within a process. If the optional @var{pid} part is missing, it means 25084a thread from the process being debugged (the leading @samp{/} still 25085needs to be present, or else @value{GDBN} will interpret the number as 25086a process ID rather than a thread ID). 25087 25088@item info proc cmdline 25089@cindex info proc cmdline 25090Show the original command line of the process. This command is 25091supported on @sc{gnu}/Linux, FreeBSD and NetBSD. 25092 25093@item info proc cwd 25094@cindex info proc cwd 25095Show the current working directory of the process. This command is 25096supported on @sc{gnu}/Linux, FreeBSD and NetBSD. 25097 25098@item info proc exe 25099@cindex info proc exe 25100Show the name of executable of the process. This command is supported 25101on @sc{gnu}/Linux, FreeBSD and NetBSD. 25102 25103@item info proc files 25104@cindex info proc files 25105Show the file descriptors open by the process. For each open file 25106descriptor, @value{GDBN} shows its number, type (file, directory, 25107character device, socket), file pointer offset, and the name of the 25108resource open on the descriptor. The resource name can be a file name 25109(for files, directories, and devices) or a protocol followed by socket 25110address (for network connections). This command is supported on 25111FreeBSD. 25112 25113This example shows the open file descriptors for a process using a 25114tty for standard input and output as well as two network sockets: 25115 25116@smallexample 25117(@value{GDBP}) info proc files 22136 25118process 22136 25119Open files: 25120 25121 FD Type Offset Flags Name 25122 text file - r-------- /usr/bin/ssh 25123 ctty chr - rw------- /dev/pts/20 25124 cwd dir - r-------- /usr/home/john 25125 root dir - r-------- / 25126 0 chr 0x32933a4 rw------- /dev/pts/20 25127 1 chr 0x32933a4 rw------- /dev/pts/20 25128 2 chr 0x32933a4 rw------- /dev/pts/20 25129 3 socket 0x0 rw----n-- tcp4 10.0.1.2:53014 -> 10.0.1.10:22 25130 4 socket 0x0 rw------- unix stream:/tmp/ssh-FIt89oAzOn5f/agent.2456 25131@end smallexample 25132 25133@item info proc mappings 25134@cindex memory address space mappings 25135Report the memory address space ranges accessible in a process. On 25136Solaris, FreeBSD and NetBSD systems, each memory range includes information 25137on whether the process has read, write, or execute access rights to each 25138range. On @sc{gnu}/Linux, FreeBSD and NetBSD systems, each memory range 25139includes the object file which is mapped to that range. 25140 25141@item info proc stat 25142@itemx info proc status 25143@cindex process detailed status information 25144Show additional process-related information, including the user ID and 25145group ID; virtual memory usage; the signals that are pending, blocked, 25146and ignored; its TTY; its consumption of system and user time; its 25147stack size; its @samp{nice} value; etc. These commands are supported 25148on @sc{gnu}/Linux, FreeBSD and NetBSD. 25149 25150For @sc{gnu}/Linux systems, see the @samp{proc} man page for more 25151information (type @kbd{man 5 proc} from your shell prompt). 25152 25153For FreeBSD and NetBSD systems, @code{info proc stat} is an alias for 25154@code{info proc status}. 25155 25156@item info proc all 25157Show all the information about the process described under all of the 25158above @code{info proc} subcommands. 25159 25160@ignore 25161@comment These sub-options of 'info proc' were not included when 25162@comment procfs.c was re-written. Keep their descriptions around 25163@comment against the day when someone finds the time to put them back in. 25164@kindex info proc times 25165@item info proc times 25166Starting time, user CPU time, and system CPU time for your program and 25167its children. 25168 25169@kindex info proc id 25170@item info proc id 25171Report on the process IDs related to your program: its own process ID, 25172the ID of its parent, the process group ID, and the session ID. 25173@end ignore 25174 25175@item set procfs-trace 25176@kindex set procfs-trace 25177@cindex @code{procfs} API calls 25178This command enables and disables tracing of @code{procfs} API calls. 25179 25180@item show procfs-trace 25181@kindex show procfs-trace 25182Show the current state of @code{procfs} API call tracing. 25183 25184@item set procfs-file @var{file} 25185@kindex set procfs-file 25186Tell @value{GDBN} to write @code{procfs} API trace to the named 25187@var{file}. @value{GDBN} appends the trace info to the previous 25188contents of the file. The default is to display the trace on the 25189standard output. 25190 25191@item show procfs-file 25192@kindex show procfs-file 25193Show the file to which @code{procfs} API trace is written. 25194 25195@item proc-trace-entry 25196@itemx proc-trace-exit 25197@itemx proc-untrace-entry 25198@itemx proc-untrace-exit 25199@kindex proc-trace-entry 25200@kindex proc-trace-exit 25201@kindex proc-untrace-entry 25202@kindex proc-untrace-exit 25203These commands enable and disable tracing of entries into and exits 25204from the @code{syscall} interface. 25205 25206@item info pidlist 25207@kindex info pidlist 25208@cindex process list, QNX Neutrino 25209For QNX Neutrino only, this command displays the list of all the 25210processes and all the threads within each process. 25211 25212@item info meminfo 25213@kindex info meminfo 25214@cindex mapinfo list, QNX Neutrino 25215For QNX Neutrino only, this command displays the list of all mapinfos. 25216@end table 25217 25218@node DJGPP Native 25219@subsection Features for Debugging @sc{djgpp} Programs 25220@cindex @sc{djgpp} debugging 25221@cindex native @sc{djgpp} debugging 25222@cindex MS-DOS-specific commands 25223 25224@cindex DPMI 25225@sc{djgpp} is a port of the @sc{gnu} development tools to MS-DOS and 25226MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs 25227that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on 25228top of real-mode DOS systems and their emulations. 25229 25230@value{GDBN} supports native debugging of @sc{djgpp} programs, and 25231defines a few commands specific to the @sc{djgpp} port. This 25232subsection describes those commands. 25233 25234@table @code 25235@kindex info dos 25236@item info dos 25237This is a prefix of @sc{djgpp}-specific commands which print 25238information about the target system and important OS structures. 25239 25240@kindex sysinfo 25241@cindex MS-DOS system info 25242@cindex free memory information (MS-DOS) 25243@item info dos sysinfo 25244This command displays assorted information about the underlying 25245platform: the CPU type and features, the OS version and flavor, the 25246DPMI version, and the available conventional and DPMI memory. 25247 25248@cindex GDT 25249@cindex LDT 25250@cindex IDT 25251@cindex segment descriptor tables 25252@cindex descriptor tables display 25253@item info dos gdt 25254@itemx info dos ldt 25255@itemx info dos idt 25256These 3 commands display entries from, respectively, Global, Local, 25257and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor 25258tables are data structures which store a descriptor for each segment 25259that is currently in use. The segment's selector is an index into a 25260descriptor table; the table entry for that index holds the 25261descriptor's base address and limit, and its attributes and access 25262rights. 25263 25264A typical @sc{djgpp} program uses 3 segments: a code segment, a data 25265segment (used for both data and the stack), and a DOS segment (which 25266allows access to DOS/BIOS data structures and absolute addresses in 25267conventional memory). However, the DPMI host will usually define 25268additional segments in order to support the DPMI environment. 25269 25270@cindex garbled pointers 25271These commands allow to display entries from the descriptor tables. 25272Without an argument, all entries from the specified table are 25273displayed. An argument, which should be an integer expression, means 25274display a single entry whose index is given by the argument. For 25275example, here's a convenient way to display information about the 25276debugged program's data segment: 25277 25278@smallexample 25279@exdent @code{(@value{GDBP}) info dos ldt $ds} 25280@exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)} 25281@end smallexample 25282 25283@noindent 25284This comes in handy when you want to see whether a pointer is outside 25285the data segment's limit (i.e.@: @dfn{garbled}). 25286 25287@cindex page tables display (MS-DOS) 25288@item info dos pde 25289@itemx info dos pte 25290These two commands display entries from, respectively, the Page 25291Directory and the Page Tables. Page Directories and Page Tables are 25292data structures which control how virtual memory addresses are mapped 25293into physical addresses. A Page Table includes an entry for every 25294page of memory that is mapped into the program's address space; there 25295may be several Page Tables, each one holding up to 4096 entries. A 25296Page Directory has up to 4096 entries, one each for every Page Table 25297that is currently in use. 25298 25299Without an argument, @kbd{info dos pde} displays the entire Page 25300Directory, and @kbd{info dos pte} displays all the entries in all of 25301the Page Tables. An argument, an integer expression, given to the 25302@kbd{info dos pde} command means display only that entry from the Page 25303Directory table. An argument given to the @kbd{info dos pte} command 25304means display entries from a single Page Table, the one pointed to by 25305the specified entry in the Page Directory. 25306 25307@cindex direct memory access (DMA) on MS-DOS 25308These commands are useful when your program uses @dfn{DMA} (Direct 25309Memory Access), which needs physical addresses to program the DMA 25310controller. 25311 25312These commands are supported only with some DPMI servers. 25313 25314@cindex physical address from linear address 25315@item info dos address-pte @var{addr} 25316This command displays the Page Table entry for a specified linear 25317address. The argument @var{addr} is a linear address which should 25318already have the appropriate segment's base address added to it, 25319because this command accepts addresses which may belong to @emph{any} 25320segment. For example, here's how to display the Page Table entry for 25321the page where a variable @code{i} is stored: 25322 25323@smallexample 25324@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i} 25325@exdent @code{Page Table entry for address 0x11a00d30:} 25326@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30} 25327@end smallexample 25328 25329@noindent 25330This says that @code{i} is stored at offset @code{0xd30} from the page 25331whose physical base address is @code{0x02698000}, and shows all the 25332attributes of that page. 25333 25334Note that you must cast the addresses of variables to a @code{char *}, 25335since otherwise the value of @code{__djgpp_base_address}, the base 25336address of all variables and functions in a @sc{djgpp} program, will 25337be added using the rules of C pointer arithmetic: if @code{i} is 25338declared an @code{int}, @value{GDBN} will add 4 times the value of 25339@code{__djgpp_base_address} to the address of @code{i}. 25340 25341Here's another example, it displays the Page Table entry for the 25342transfer buffer: 25343 25344@smallexample 25345@exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)} 25346@exdent @code{Page Table entry for address 0x29110:} 25347@exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110} 25348@end smallexample 25349 25350@noindent 25351(The @code{+ 3} offset is because the transfer buffer's address is the 253523rd member of the @code{_go32_info_block} structure.) The output 25353clearly shows that this DPMI server maps the addresses in conventional 25354memory 1:1, i.e.@: the physical (@code{0x00029000} + @code{0x110}) and 25355linear (@code{0x29110}) addresses are identical. 25356 25357This command is supported only with some DPMI servers. 25358@end table 25359 25360@cindex DOS serial data link, remote debugging 25361In addition to native debugging, the DJGPP port supports remote 25362debugging via a serial data link. The following commands are specific 25363to remote serial debugging in the DJGPP port of @value{GDBN}. 25364 25365@table @code 25366@kindex set com1base 25367@kindex set com1irq 25368@kindex set com2base 25369@kindex set com2irq 25370@kindex set com3base 25371@kindex set com3irq 25372@kindex set com4base 25373@kindex set com4irq 25374@item set com1base @var{addr} 25375This command sets the base I/O port address of the @file{COM1} serial 25376port. 25377 25378@item set com1irq @var{irq} 25379This command sets the @dfn{Interrupt Request} (@code{IRQ}) line to use 25380for the @file{COM1} serial port. 25381 25382There are similar commands @samp{set com2base}, @samp{set com3irq}, 25383etc.@: for setting the port address and the @code{IRQ} lines for the 25384other 3 COM ports. 25385 25386@kindex show com1base 25387@kindex show com1irq 25388@kindex show com2base 25389@kindex show com2irq 25390@kindex show com3base 25391@kindex show com3irq 25392@kindex show com4base 25393@kindex show com4irq 25394The related commands @samp{show com1base}, @samp{show com1irq} etc.@: 25395display the current settings of the base address and the @code{IRQ} 25396lines used by the COM ports. 25397 25398@item info serial 25399@kindex info serial 25400@cindex DOS serial port status 25401This command prints the status of the 4 DOS serial ports. For each 25402port, it prints whether it's active or not, its I/O base address and 25403IRQ number, whether it uses a 16550-style FIFO, its baudrate, and the 25404counts of various errors encountered so far. 25405@end table 25406 25407 25408@node Cygwin Native 25409@subsection Features for Debugging MS Windows PE Executables 25410@cindex MS Windows debugging 25411@cindex native Cygwin debugging 25412@cindex Cygwin-specific commands 25413 25414@value{GDBN} supports native debugging of MS Windows programs, including 25415DLLs with and without symbolic debugging information. 25416 25417@cindex Ctrl-BREAK, MS-Windows 25418@cindex interrupt debuggee on MS-Windows 25419MS-Windows programs that call @code{SetConsoleMode} to switch off the 25420special meaning of the @samp{Ctrl-C} keystroke cannot be interrupted 25421by typing @kbd{C-c}. For this reason, @value{GDBN} on MS-Windows 25422supports @kbd{C-@key{BREAK}} as an alternative interrupt key 25423sequence, which can be used to interrupt the debuggee even if it 25424ignores @kbd{C-c}. 25425 25426There are various additional Cygwin-specific commands, described in 25427this section. Working with DLLs that have no debugging symbols is 25428described in @ref{Non-debug DLL Symbols}. 25429 25430@table @code 25431@kindex info w32 25432@item info w32 25433This is a prefix of MS Windows-specific commands which print 25434information about the target system and important OS structures. 25435 25436@item info w32 selector 25437This command displays information returned by 25438the Win32 API @code{GetThreadSelectorEntry} function. 25439It takes an optional argument that is evaluated to 25440a long value to give the information about this given selector. 25441Without argument, this command displays information 25442about the six segment registers. 25443 25444@item info w32 thread-information-block 25445This command displays thread specific information stored in the 25446Thread Information Block (readable on the X86 CPU family using @code{$fs} 25447selector for 32-bit programs and @code{$gs} for 64-bit programs). 25448 25449@kindex signal-event 25450@item signal-event @var{id} 25451This command signals an event with user-provided @var{id}. Used to resume 25452crashing process when attached to it using MS-Windows JIT debugging (AeDebug). 25453 25454To use it, create or edit the following keys in 25455@code{HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug} and/or 25456@code{HKLM\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\AeDebug} 25457(for x86_64 versions): 25458 25459@itemize @minus 25460@item 25461@code{Debugger} (REG_SZ) --- a command to launch the debugger. 25462Suggested command is: @code{@var{fully-qualified-path-to-gdb.exe} -ex 25463"attach %ld" -ex "signal-event %ld" -ex "continue"}. 25464 25465The first @code{%ld} will be replaced by the process ID of the 25466crashing process, the second @code{%ld} will be replaced by the ID of 25467the event that blocks the crashing process, waiting for @value{GDBN} 25468to attach. 25469 25470@item 25471@code{Auto} (REG_SZ) --- either @code{1} or @code{0}. @code{1} will 25472make the system run debugger specified by the Debugger key 25473automatically, @code{0} will cause a dialog box with ``OK'' and 25474``Cancel'' buttons to appear, which allows the user to either 25475terminate the crashing process (OK) or debug it (Cancel). 25476@end itemize 25477 25478@kindex set cygwin-exceptions 25479@cindex debugging the Cygwin DLL 25480@cindex Cygwin DLL, debugging 25481@item set cygwin-exceptions @var{mode} 25482If @var{mode} is @code{on}, @value{GDBN} will break on exceptions that 25483happen inside the Cygwin DLL. If @var{mode} is @code{off}, 25484@value{GDBN} will delay recognition of exceptions, and may ignore some 25485exceptions which seem to be caused by internal Cygwin DLL 25486``bookkeeping''. This option is meant primarily for debugging the 25487Cygwin DLL itself; the default value is @code{off} to avoid annoying 25488@value{GDBN} users with false @code{SIGSEGV} signals. 25489 25490@kindex show cygwin-exceptions 25491@item show cygwin-exceptions 25492Displays whether @value{GDBN} will break on exceptions that happen 25493inside the Cygwin DLL itself. 25494 25495@kindex set new-console 25496@item set new-console @var{mode} 25497If @var{mode} is @code{on} the debuggee will 25498be started in a new console on next start. 25499If @var{mode} is @code{off}, the debuggee will 25500be started in the same console as the debugger. 25501 25502@kindex show new-console 25503@item show new-console 25504Displays whether a new console is used 25505when the debuggee is started. 25506 25507@kindex set new-group 25508@item set new-group @var{mode} 25509This boolean value controls whether the debuggee should 25510start a new group or stay in the same group as the debugger. 25511This affects the way the Windows OS handles 25512@samp{Ctrl-C}. 25513 25514@kindex show new-group 25515@item show new-group 25516Displays current value of new-group boolean. 25517 25518@kindex set debugevents 25519@item set debugevents 25520This boolean value adds debug output concerning kernel events related 25521to the debuggee seen by the debugger. This includes events that 25522signal thread and process creation and exit, DLL loading and 25523unloading, console interrupts, and debugging messages produced by the 25524Windows @code{OutputDebugString} API call. 25525 25526@kindex set debugexec 25527@item set debugexec 25528This boolean value adds debug output concerning execute events 25529(such as resume thread) seen by the debugger. 25530 25531@kindex set debugexceptions 25532@item set debugexceptions 25533This boolean value adds debug output concerning exceptions in the 25534debuggee seen by the debugger. 25535 25536@kindex set debugmemory 25537@item set debugmemory 25538This boolean value adds debug output concerning debuggee memory reads 25539and writes by the debugger. 25540 25541@kindex set shell 25542@item set shell 25543This boolean values specifies whether the debuggee is called 25544via a shell or directly (default value is on). 25545 25546@kindex show shell 25547@item show shell 25548Displays if the debuggee will be started with a shell. 25549 25550@end table 25551 25552@menu 25553* Non-debug DLL Symbols:: Support for DLLs without debugging symbols 25554@end menu 25555 25556@node Non-debug DLL Symbols 25557@subsubsection Support for DLLs without Debugging Symbols 25558@cindex DLLs with no debugging symbols 25559@cindex Minimal symbols and DLLs 25560 25561Very often on windows, some of the DLLs that your program relies on do 25562not include symbolic debugging information (for example, 25563@file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging 25564symbols in a DLL, it relies on the minimal amount of symbolic 25565information contained in the DLL's export table. This section 25566describes working with such symbols, known internally to @value{GDBN} as 25567``minimal symbols''. 25568 25569Note that before the debugged program has started execution, no DLLs 25570will have been loaded. The easiest way around this problem is simply to 25571start the program --- either by setting a breakpoint or letting the 25572program run once to completion. 25573 25574@subsubsection DLL Name Prefixes 25575 25576In keeping with the naming conventions used by the Microsoft debugging 25577tools, DLL export symbols are made available with a prefix based on the 25578DLL name, for instance @code{KERNEL32!CreateFileA}. The plain name is 25579also entered into the symbol table, so @code{CreateFileA} is often 25580sufficient. In some cases there will be name clashes within a program 25581(particularly if the executable itself includes full debugging symbols) 25582necessitating the use of the fully qualified name when referring to the 25583contents of the DLL. Use single-quotes around the name to avoid the 25584exclamation mark (``!'') being interpreted as a language operator. 25585 25586Note that the internal name of the DLL may be all upper-case, even 25587though the file name of the DLL is lower-case, or vice-versa. Since 25588symbols within @value{GDBN} are @emph{case-sensitive} this may cause 25589some confusion. If in doubt, try the @code{info functions} and 25590@code{info variables} commands or even @code{maint print msymbols} 25591(@pxref{Symbols}). Here's an example: 25592 25593@smallexample 25594(@value{GDBP}) info function CreateFileA 25595All functions matching regular expression "CreateFileA": 25596 25597Non-debugging symbols: 255980x77e885f4 CreateFileA 255990x77e885f4 KERNEL32!CreateFileA 25600@end smallexample 25601 25602@smallexample 25603(@value{GDBP}) info function ! 25604All functions matching regular expression "!": 25605 25606Non-debugging symbols: 256070x6100114c cygwin1!__assert 256080x61004034 cygwin1!_dll_crt0@@0 256090x61004240 cygwin1!dll_crt0(per_process *) 25610[etc...] 25611@end smallexample 25612 25613@subsubsection Working with Minimal Symbols 25614 25615Symbols extracted from a DLL's export table do not contain very much 25616type information. All that @value{GDBN} can do is guess whether a symbol 25617refers to a function or variable depending on the linker section that 25618contains the symbol. Also note that the actual contents of the memory 25619contained in a DLL are not available unless the program is running. This 25620means that you cannot examine the contents of a variable or disassemble 25621a function within a DLL without a running program. 25622 25623Variables are generally treated as pointers and dereferenced 25624automatically. For this reason, it is often necessary to prefix a 25625variable name with the address-of operator (``&'') and provide explicit 25626type information in the command. Here's an example of the type of 25627problem: 25628 25629@smallexample 25630(@value{GDBP}) print 'cygwin1!__argv' 25631'cygwin1!__argv' has unknown type; cast it to its declared type 25632@end smallexample 25633 25634@smallexample 25635(@value{GDBP}) x 'cygwin1!__argv' 25636'cygwin1!__argv' has unknown type; cast it to its declared type 25637@end smallexample 25638 25639And two possible solutions: 25640 25641@smallexample 25642(@value{GDBP}) print ((char **)'cygwin1!__argv')[0] 25643$2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" 25644@end smallexample 25645 25646@smallexample 25647(@value{GDBP}) x/2x &'cygwin1!__argv' 256480x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000 25649(@value{GDBP}) x/x 0x10021608 256500x10021608: 0x0022fd98 25651(@value{GDBP}) x/s 0x0022fd98 256520x22fd98: "/cygdrive/c/mydirectory/myprogram" 25653@end smallexample 25654 25655Setting a break point within a DLL is possible even before the program 25656starts execution. However, under these circumstances, @value{GDBN} can't 25657examine the initial instructions of the function in order to skip the 25658function's frame set-up code. You can work around this by using ``*&'' 25659to set the breakpoint at a raw memory address: 25660 25661@smallexample 25662(@value{GDBP}) break *&'python22!PyOS_Readline' 25663Breakpoint 1 at 0x1e04eff0 25664@end smallexample 25665 25666The author of these extensions is not entirely convinced that setting a 25667break point within a shared DLL like @file{kernel32.dll} is completely 25668safe. 25669 25670@node Hurd Native 25671@subsection Commands Specific to @sc{gnu} Hurd Systems 25672@cindex @sc{gnu} Hurd debugging 25673 25674This subsection describes @value{GDBN} commands specific to the 25675@sc{gnu} Hurd native debugging. 25676 25677@table @code 25678@item set signals 25679@itemx set sigs 25680@kindex set signals@r{, Hurd command} 25681@kindex set sigs@r{, Hurd command} 25682This command toggles the state of inferior signal interception by 25683@value{GDBN}. Mach exceptions, such as breakpoint traps, are not 25684affected by this command. @code{sigs} is a shorthand alias for 25685@code{signals}. 25686 25687@item show signals 25688@itemx show sigs 25689@kindex show signals@r{, Hurd command} 25690@kindex show sigs@r{, Hurd command} 25691Show the current state of intercepting inferior's signals. 25692 25693@item set signal-thread 25694@itemx set sigthread 25695@kindex set signal-thread 25696@kindex set sigthread 25697This command tells @value{GDBN} which thread is the @code{libc} signal 25698thread. That thread is run when a signal is delivered to a running 25699process. @code{set sigthread} is the shorthand alias of @code{set 25700signal-thread}. 25701 25702@item show signal-thread 25703@itemx show sigthread 25704@kindex show signal-thread 25705@kindex show sigthread 25706These two commands show which thread will run when the inferior is 25707delivered a signal. 25708 25709@item set stopped 25710@kindex set stopped@r{, Hurd command} 25711This commands tells @value{GDBN} that the inferior process is stopped, 25712as with the @code{SIGSTOP} signal. The stopped process can be 25713continued by delivering a signal to it. 25714 25715@item show stopped 25716@kindex show stopped@r{, Hurd command} 25717This command shows whether @value{GDBN} thinks the debuggee is 25718stopped. 25719 25720@item set exceptions 25721@kindex set exceptions@r{, Hurd command} 25722Use this command to turn off trapping of exceptions in the inferior. 25723When exception trapping is off, neither breakpoints nor 25724single-stepping will work. To restore the default, set exception 25725trapping on. 25726 25727@item show exceptions 25728@kindex show exceptions@r{, Hurd command} 25729Show the current state of trapping exceptions in the inferior. 25730 25731@item set task pause 25732@kindex set task@r{, Hurd commands} 25733@cindex task attributes (@sc{gnu} Hurd) 25734@cindex pause current task (@sc{gnu} Hurd) 25735This command toggles task suspension when @value{GDBN} has control. 25736Setting it to on takes effect immediately, and the task is suspended 25737whenever @value{GDBN} gets control. Setting it to off will take 25738effect the next time the inferior is continued. If this option is set 25739to off, you can use @code{set thread default pause on} or @code{set 25740thread pause on} (see below) to pause individual threads. 25741 25742@item show task pause 25743@kindex show task@r{, Hurd commands} 25744Show the current state of task suspension. 25745 25746@item set task detach-suspend-count 25747@cindex task suspend count 25748@cindex detach from task, @sc{gnu} Hurd 25749This command sets the suspend count the task will be left with when 25750@value{GDBN} detaches from it. 25751 25752@item show task detach-suspend-count 25753Show the suspend count the task will be left with when detaching. 25754 25755@item set task exception-port 25756@itemx set task excp 25757@cindex task exception port, @sc{gnu} Hurd 25758This command sets the task exception port to which @value{GDBN} will 25759forward exceptions. The argument should be the value of the @dfn{send 25760rights} of the task. @code{set task excp} is a shorthand alias. 25761 25762@item set noninvasive 25763@cindex noninvasive task options 25764This command switches @value{GDBN} to a mode that is the least 25765invasive as far as interfering with the inferior is concerned. This 25766is the same as using @code{set task pause}, @code{set exceptions}, and 25767@code{set signals} to values opposite to the defaults. 25768 25769@item info send-rights 25770@itemx info receive-rights 25771@itemx info port-rights 25772@itemx info port-sets 25773@itemx info dead-names 25774@itemx info ports 25775@itemx info psets 25776@cindex send rights, @sc{gnu} Hurd 25777@cindex receive rights, @sc{gnu} Hurd 25778@cindex port rights, @sc{gnu} Hurd 25779@cindex port sets, @sc{gnu} Hurd 25780@cindex dead names, @sc{gnu} Hurd 25781These commands display information about, respectively, send rights, 25782receive rights, port rights, port sets, and dead names of a task. 25783There are also shorthand aliases: @code{info ports} for @code{info 25784port-rights} and @code{info psets} for @code{info port-sets}. 25785 25786@item set thread pause 25787@kindex set thread@r{, Hurd command} 25788@cindex thread properties, @sc{gnu} Hurd 25789@cindex pause current thread (@sc{gnu} Hurd) 25790This command toggles current thread suspension when @value{GDBN} has 25791control. Setting it to on takes effect immediately, and the current 25792thread is suspended whenever @value{GDBN} gets control. Setting it to 25793off will take effect the next time the inferior is continued. 25794Normally, this command has no effect, since when @value{GDBN} has 25795control, the whole task is suspended. However, if you used @code{set 25796task pause off} (see above), this command comes in handy to suspend 25797only the current thread. 25798 25799@item show thread pause 25800@kindex show thread@r{, Hurd command} 25801This command shows the state of current thread suspension. 25802 25803@item set thread run 25804This command sets whether the current thread is allowed to run. 25805 25806@item show thread run 25807Show whether the current thread is allowed to run. 25808 25809@item set thread detach-suspend-count 25810@cindex thread suspend count, @sc{gnu} Hurd 25811@cindex detach from thread, @sc{gnu} Hurd 25812This command sets the suspend count @value{GDBN} will leave on a 25813thread when detaching. This number is relative to the suspend count 25814found by @value{GDBN} when it notices the thread; use @code{set thread 25815takeover-suspend-count} to force it to an absolute value. 25816 25817@item show thread detach-suspend-count 25818Show the suspend count @value{GDBN} will leave on the thread when 25819detaching. 25820 25821@item set thread exception-port 25822@itemx set thread excp 25823Set the thread exception port to which to forward exceptions. This 25824overrides the port set by @code{set task exception-port} (see above). 25825@code{set thread excp} is the shorthand alias. 25826 25827@item set thread takeover-suspend-count 25828Normally, @value{GDBN}'s thread suspend counts are relative to the 25829value @value{GDBN} finds when it notices each thread. This command 25830changes the suspend counts to be absolute instead. 25831 25832@item set thread default 25833@itemx show thread default 25834@cindex thread default settings, @sc{gnu} Hurd 25835Each of the above @code{set thread} commands has a @code{set thread 25836default} counterpart (e.g., @code{set thread default pause}, @code{set 25837thread default exception-port}, etc.). The @code{thread default} 25838variety of commands sets the default thread properties for all 25839threads; you can then change the properties of individual threads with 25840the non-default commands. 25841@end table 25842 25843@node Darwin 25844@subsection Darwin 25845@cindex Darwin 25846 25847@value{GDBN} provides the following commands specific to the Darwin target: 25848 25849@table @code 25850@item set debug darwin @var{num} 25851@kindex set debug darwin 25852When set to a non zero value, enables debugging messages specific to 25853the Darwin support. Higher values produce more verbose output. 25854 25855@item show debug darwin 25856@kindex show debug darwin 25857Show the current state of Darwin messages. 25858 25859@item set debug mach-o @var{num} 25860@kindex set debug mach-o 25861When set to a non zero value, enables debugging messages while 25862@value{GDBN} is reading Darwin object files. (@dfn{Mach-O} is the 25863file format used on Darwin for object and executable files.) Higher 25864values produce more verbose output. This is a command to diagnose 25865problems internal to @value{GDBN} and should not be needed in normal 25866usage. 25867 25868@item show debug mach-o 25869@kindex show debug mach-o 25870Show the current state of Mach-O file messages. 25871 25872@item set mach-exceptions on 25873@itemx set mach-exceptions off 25874@kindex set mach-exceptions 25875On Darwin, faults are first reported as a Mach exception and are then 25876mapped to a Posix signal. Use this command to turn on trapping of 25877Mach exceptions in the inferior. This might be sometimes useful to 25878better understand the cause of a fault. The default is off. 25879 25880@item show mach-exceptions 25881@kindex show mach-exceptions 25882Show the current state of exceptions trapping. 25883@end table 25884 25885@node FreeBSD 25886@subsection FreeBSD 25887@cindex FreeBSD 25888 25889When the ABI of a system call is changed in the FreeBSD kernel, this 25890is implemented by leaving a compatibility system call using the old 25891ABI at the existing number and allocating a new system call number for 25892the version using the new ABI. As a convenience, when a system call 25893is caught by name (@pxref{catch syscall}), compatibility system calls 25894are also caught. 25895 25896For example, FreeBSD 12 introduced a new variant of the @code{kevent} 25897system call and catching the @code{kevent} system call by name catches 25898both variants: 25899 25900@smallexample 25901(@value{GDBP}) catch syscall kevent 25902Catchpoint 1 (syscalls 'freebsd11_kevent' [363] 'kevent' [560]) 25903(@value{GDBP}) 25904@end smallexample 25905 25906 25907@node Embedded OS 25908@section Embedded Operating Systems 25909 25910This section describes configurations involving the debugging of 25911embedded operating systems that are available for several different 25912architectures. 25913 25914@value{GDBN} includes the ability to debug programs running on 25915various real-time operating systems. 25916 25917@node Embedded Processors 25918@section Embedded Processors 25919 25920This section goes into details specific to particular embedded 25921configurations. 25922 25923@cindex send command to simulator 25924Whenever a specific embedded processor has a simulator, @value{GDBN} 25925allows to send an arbitrary command to the simulator. 25926 25927@table @code 25928@item sim @var{command} 25929@kindex sim@r{, a command} 25930Send an arbitrary @var{command} string to the simulator. Consult the 25931documentation for the specific simulator in use for information about 25932acceptable commands. 25933@end table 25934 25935 25936@menu 25937* ARC:: Synopsys ARC 25938* ARM:: ARM 25939* BPF:: eBPF 25940* M68K:: Motorola M68K 25941* MicroBlaze:: Xilinx MicroBlaze 25942* MIPS Embedded:: MIPS Embedded 25943* OpenRISC 1000:: OpenRISC 1000 (or1k) 25944* PowerPC Embedded:: PowerPC Embedded 25945* AVR:: Atmel AVR 25946* CRIS:: CRIS 25947* Super-H:: Renesas Super-H 25948@end menu 25949 25950@node ARC 25951@subsection Synopsys ARC 25952@cindex Synopsys ARC 25953@cindex ARC specific commands 25954@cindex ARC600 25955@cindex ARC700 25956@cindex ARC EM 25957@cindex ARC HS 25958 25959@value{GDBN} provides the following ARC-specific commands: 25960 25961@table @code 25962@item set debug arc 25963@kindex set debug arc 25964Control the level of ARC specific debug messages. Use 0 for no messages (the 25965default), 1 for debug messages, and 2 for even more debug messages. 25966 25967@item show debug arc 25968@kindex show debug arc 25969Show the level of ARC specific debugging in operation. 25970 25971@item maint print arc arc-instruction @var{address} 25972@kindex maint print arc arc-instruction 25973Print internal disassembler information about instruction at a given address. 25974 25975@end table 25976 25977@node ARM 25978@subsection ARM 25979 25980@value{GDBN} provides the following ARM-specific commands: 25981 25982@table @code 25983@item set arm disassembler 25984@kindex set arm 25985This commands selects from a list of disassembly styles. The 25986@code{"std"} style is the standard style. 25987 25988@item show arm disassembler 25989@kindex show arm 25990Show the current disassembly style. 25991 25992@item set arm apcs32 25993@cindex ARM 32-bit mode 25994This command toggles ARM operation mode between 32-bit and 26-bit. 25995 25996@item show arm apcs32 25997Display the current usage of the ARM 32-bit mode. 25998 25999@item set arm fpu @var{fputype} 26000This command sets the ARM floating-point unit (FPU) type. The 26001argument @var{fputype} can be one of these: 26002 26003@table @code 26004@item auto 26005Determine the FPU type by querying the OS ABI. 26006@item softfpa 26007Software FPU, with mixed-endian doubles on little-endian ARM 26008processors. 26009@item fpa 26010GCC-compiled FPA co-processor. 26011@item softvfp 26012Software FPU with pure-endian doubles. 26013@item vfp 26014VFP co-processor. 26015@end table 26016 26017@item show arm fpu 26018Show the current type of the FPU. 26019 26020@item set arm abi 26021This command forces @value{GDBN} to use the specified ABI. 26022 26023@item show arm abi 26024Show the currently used ABI. 26025 26026@item set arm fallback-mode (arm|thumb|auto) 26027@value{GDBN} uses the symbol table, when available, to determine 26028whether instructions are ARM or Thumb. This command controls 26029@value{GDBN}'s default behavior when the symbol table is not 26030available. The default is @samp{auto}, which causes @value{GDBN} to 26031use the current execution mode (from the @code{T} bit in the @code{CPSR} 26032register). 26033 26034@item show arm fallback-mode 26035Show the current fallback instruction mode. 26036 26037@item set arm force-mode (arm|thumb|auto) 26038This command overrides use of the symbol table to determine whether 26039instructions are ARM or Thumb. The default is @samp{auto}, which 26040causes @value{GDBN} to use the symbol table and then the setting 26041of @samp{set arm fallback-mode}. 26042 26043@item show arm force-mode 26044Show the current forced instruction mode. 26045 26046@item set arm unwind-secure-frames 26047This command enables unwinding from Non-secure to Secure mode on 26048Cortex-M with Security extension. 26049This can trigger security exceptions when unwinding the exception 26050stack. 26051It is enabled by default. 26052 26053@item show arm unwind-secure-frames 26054Show whether unwinding from Non-secure to Secure mode is enabled. 26055 26056@item set debug arm 26057Toggle whether to display ARM-specific debugging messages from the ARM 26058target support subsystem. 26059 26060@item show debug arm 26061Show whether ARM-specific debugging messages are enabled. 26062@end table 26063 26064@table @code 26065@item target sim @r{[}@var{simargs}@r{]} @dots{} 26066The @value{GDBN} ARM simulator accepts the following optional arguments. 26067 26068@table @code 26069@item --swi-support=@var{type} 26070Tell the simulator which SWI interfaces to support. The argument 26071@var{type} may be a comma separated list of the following values. 26072The default value is @code{all}. 26073 26074@table @code 26075@item none 26076@item demon 26077@item angel 26078@item redboot 26079@item all 26080@end table 26081@end table 26082@end table 26083 26084@node BPF 26085@subsection BPF 26086 26087@table @code 26088@item target sim @r{[}@var{simargs}@r{]} @dots{} 26089The @value{GDBN} BPF simulator accepts the following optional arguments. 26090 26091@table @code 26092@item --skb-data-offset=@var{offset} 26093Tell the simulator the offset, measured in bytes, of the 26094@code{skb_data} field in the kernel @code{struct sk_buff} structure. 26095This offset is used by some BPF specific-purpose load/store 26096instructions. Defaults to 0. 26097@end table 26098@end table 26099 26100@node M68K 26101@subsection M68k 26102 26103The Motorola m68k configuration includes ColdFire support. 26104 26105@node MicroBlaze 26106@subsection MicroBlaze 26107@cindex Xilinx MicroBlaze 26108@cindex XMD, Xilinx Microprocessor Debugger 26109 26110The MicroBlaze is a soft-core processor supported on various Xilinx 26111FPGAs, such as Spartan or Virtex series. Boards with these processors 26112usually have JTAG ports which connect to a host system running the Xilinx 26113Embedded Development Kit (EDK) or Software Development Kit (SDK). 26114This host system is used to download the configuration bitstream to 26115the target FPGA. The Xilinx Microprocessor Debugger (XMD) program 26116communicates with the target board using the JTAG interface and 26117presents a @code{gdbserver} interface to the board. By default 26118@code{xmd} uses port @code{1234}. (While it is possible to change 26119this default port, it requires the use of undocumented @code{xmd} 26120commands. Contact Xilinx support if you need to do this.) 26121 26122Use these GDB commands to connect to the MicroBlaze target processor. 26123 26124@table @code 26125@item target remote :1234 26126Use this command to connect to the target if you are running @value{GDBN} 26127on the same system as @code{xmd}. 26128 26129@item target remote @var{xmd-host}:1234 26130Use this command to connect to the target if it is connected to @code{xmd} 26131running on a different system named @var{xmd-host}. 26132 26133@item load 26134Use this command to download a program to the MicroBlaze target. 26135 26136@item set debug microblaze @var{n} 26137Enable MicroBlaze-specific debugging messages if non-zero. 26138 26139@item show debug microblaze @var{n} 26140Show MicroBlaze-specific debugging level. 26141@end table 26142 26143@node MIPS Embedded 26144@subsection @acronym{MIPS} Embedded 26145 26146@noindent 26147@value{GDBN} supports these special commands for @acronym{MIPS} targets: 26148 26149@table @code 26150@item set mipsfpu double 26151@itemx set mipsfpu single 26152@itemx set mipsfpu none 26153@itemx set mipsfpu auto 26154@itemx show mipsfpu 26155@kindex set mipsfpu 26156@kindex show mipsfpu 26157@cindex @acronym{MIPS} remote floating point 26158@cindex floating point, @acronym{MIPS} remote 26159If your target board does not support the @acronym{MIPS} floating point 26160coprocessor, you should use the command @samp{set mipsfpu none} (if you 26161need this, you may wish to put the command in your @value{GDBN} init 26162file). This tells @value{GDBN} how to find the return value of 26163functions which return floating point values. It also allows 26164@value{GDBN} to avoid saving the floating point registers when calling 26165functions on the board. If you are using a floating point coprocessor 26166with only single precision floating point support, as on the @sc{r4650} 26167processor, use the command @samp{set mipsfpu single}. The default 26168double precision floating point coprocessor may be selected using 26169@samp{set mipsfpu double}. 26170 26171In previous versions the only choices were double precision or no 26172floating point, so @samp{set mipsfpu on} will select double precision 26173and @samp{set mipsfpu off} will select no floating point. 26174 26175As usual, you can inquire about the @code{mipsfpu} variable with 26176@samp{show mipsfpu}. 26177@end table 26178 26179@node OpenRISC 1000 26180@subsection OpenRISC 1000 26181@cindex OpenRISC 1000 26182 26183@noindent 26184The OpenRISC 1000 provides a free RISC instruction set architecture. It is 26185mainly provided as a soft-core which can run on Xilinx, Altera and other 26186FPGA's. 26187 26188@value{GDBN} for OpenRISC supports the below commands when connecting to 26189a target: 26190 26191@table @code 26192 26193@kindex target sim 26194@item target sim 26195 26196Runs the builtin CPU simulator which can run very basic 26197programs but does not support most hardware functions like MMU. 26198For more complex use cases the user is advised to run an external 26199target, and connect using @samp{target remote}. 26200 26201Example: @code{target sim} 26202 26203@item set debug or1k 26204Toggle whether to display OpenRISC-specific debugging messages from the 26205OpenRISC target support subsystem. 26206 26207@item show debug or1k 26208Show whether OpenRISC-specific debugging messages are enabled. 26209@end table 26210 26211@node PowerPC Embedded 26212@subsection PowerPC Embedded 26213 26214@cindex DVC register 26215@value{GDBN} supports using the DVC (Data Value Compare) register to 26216implement in hardware simple hardware watchpoint conditions of the form: 26217 26218@smallexample 26219(@value{GDBP}) watch @var{address|variable} \ 26220 if @var{address|variable} == @var{constant expression} 26221@end smallexample 26222 26223The DVC register will be automatically used when @value{GDBN} detects 26224such pattern in a condition expression, and the created watchpoint uses one 26225debug register (either the @code{exact-watchpoints} option is on and the 26226variable is scalar, or the variable has a length of one byte). This feature 26227is available in native @value{GDBN} running on a Linux kernel version 2.6.34 26228or newer. 26229 26230When running on PowerPC embedded processors, @value{GDBN} automatically uses 26231ranged hardware watchpoints, unless the @code{exact-watchpoints} option is on, 26232in which case watchpoints using only one debug register are created when 26233watching variables of scalar types. 26234 26235You can create an artificial array to watch an arbitrary memory 26236region using one of the following commands (@pxref{Expressions}): 26237 26238@smallexample 26239(@value{GDBP}) watch *((char *) @var{address})@@@var{length} 26240(@value{GDBP}) watch @{char[@var{length}]@} @var{address} 26241@end smallexample 26242 26243PowerPC embedded processors support masked watchpoints. See the discussion 26244about the @code{mask} argument in @ref{Set Watchpoints}. 26245 26246@cindex ranged breakpoint 26247PowerPC embedded processors support hardware accelerated 26248@dfn{ranged breakpoints}. A ranged breakpoint stops execution of 26249the inferior whenever it executes an instruction at any address within 26250the range it was set at. To set a ranged breakpoint in @value{GDBN}, 26251use the @code{break-range} command. 26252 26253@value{GDBN} provides the following PowerPC-specific commands: 26254 26255@table @code 26256@kindex break-range 26257@item break-range @var{start-locspec}, @var{end-locspec} 26258Set a breakpoint for an address range given by @var{start-locspec} and 26259@var{end-locspec}, which are location specs. @xref{Location 26260Specifications}, for a list of all the possible forms of location 26261specs. @value{GDBN} resolves both @var{start-locspec} and 26262@var{end-locspec}, and uses the addresses of the resolved code 26263locations as start and end addresses of the range to break at. The 26264breakpoint will stop execution of the inferior whenever it executes an 26265instruction at any address between the start and end addresses, 26266inclusive. If either @var{start-locspec} or @var{end-locspec} resolve 26267to multiple code locations in the program, then the command aborts 26268with an error without creating a breakpoint. 26269 26270@kindex set powerpc 26271@item set powerpc soft-float 26272@itemx show powerpc soft-float 26273Force @value{GDBN} to use (or not use) a software floating point calling 26274convention. By default, @value{GDBN} selects the calling convention based 26275on the selected architecture and the provided executable file. 26276 26277@item set powerpc vector-abi 26278@itemx show powerpc vector-abi 26279Force @value{GDBN} to use the specified calling convention for vector 26280arguments and return values. The valid options are @samp{auto}; 26281@samp{generic}, to avoid vector registers even if they are present; 26282@samp{altivec}, to use AltiVec registers; and @samp{spe} to use SPE 26283registers. By default, @value{GDBN} selects the calling convention 26284based on the selected architecture and the provided executable file. 26285 26286@item set powerpc exact-watchpoints 26287@itemx show powerpc exact-watchpoints 26288Allow @value{GDBN} to use only one debug register when watching a variable 26289of scalar type, thus assuming that the variable is accessed through the 26290address of its first byte. 26291 26292@end table 26293 26294@node AVR 26295@subsection Atmel AVR 26296@cindex AVR 26297 26298When configured for debugging the Atmel AVR, @value{GDBN} supports the 26299following AVR-specific commands: 26300 26301@table @code 26302@item info io_registers 26303@kindex info io_registers@r{, AVR} 26304@cindex I/O registers (Atmel AVR) 26305This command displays information about the AVR I/O registers. For 26306each register, @value{GDBN} prints its number and value. 26307@end table 26308 26309@node CRIS 26310@subsection CRIS 26311@cindex CRIS 26312 26313When configured for debugging CRIS, @value{GDBN} provides the 26314following CRIS-specific commands: 26315 26316@table @code 26317@item set cris-version @var{ver} 26318@cindex CRIS version 26319Set the current CRIS version to @var{ver}, either @samp{10} or @samp{32}. 26320The CRIS version affects register names and sizes. This command is useful in 26321case autodetection of the CRIS version fails. 26322 26323@item show cris-version 26324Show the current CRIS version. 26325 26326@item set cris-dwarf2-cfi 26327@cindex DWARF-2 CFI and CRIS 26328Set the usage of DWARF-2 CFI for CRIS debugging. The default is @samp{on}. 26329Change to @samp{off} when using @code{gcc-cris} whose version is below 26330@code{R59}. 26331 26332@item show cris-dwarf2-cfi 26333Show the current state of using DWARF-2 CFI. 26334 26335@item set cris-mode @var{mode} 26336@cindex CRIS mode 26337Set the current CRIS mode to @var{mode}. It should only be changed when 26338debugging in guru mode, in which case it should be set to 26339@samp{guru} (the default is @samp{normal}). 26340 26341@item show cris-mode 26342Show the current CRIS mode. 26343@end table 26344 26345@node Super-H 26346@subsection Renesas Super-H 26347@cindex Super-H 26348 26349For the Renesas Super-H processor, @value{GDBN} provides these 26350commands: 26351 26352@table @code 26353@item set sh calling-convention @var{convention} 26354@kindex set sh calling-convention 26355Set the calling-convention used when calling functions from @value{GDBN}. 26356Allowed values are @samp{gcc}, which is the default setting, and @samp{renesas}. 26357With the @samp{gcc} setting, functions are called using the @value{NGCC} calling 26358convention. If the DWARF-2 information of the called function specifies 26359that the function follows the Renesas calling convention, the function 26360is called using the Renesas calling convention. If the calling convention 26361is set to @samp{renesas}, the Renesas calling convention is always used, 26362regardless of the DWARF-2 information. This can be used to override the 26363default of @samp{gcc} if debug information is missing, or the compiler 26364does not emit the DWARF-2 calling convention entry for a function. 26365 26366@item show sh calling-convention 26367@kindex show sh calling-convention 26368Show the current calling convention setting. 26369 26370@end table 26371 26372 26373@node Architectures 26374@section Architectures 26375 26376This section describes characteristics of architectures that affect 26377all uses of @value{GDBN} with the architecture, both native and cross. 26378 26379@menu 26380* AArch64:: 26381* x86:: 26382* Alpha:: 26383* MIPS:: 26384* HPPA:: HP PA architecture 26385* PowerPC:: 26386* Nios II:: 26387* Sparc64:: 26388* S12Z:: 26389* AMD GPU:: @acronym{AMD GPU} architectures 26390@end menu 26391 26392@node AArch64 26393@subsection AArch64 26394@cindex AArch64 support 26395 26396When @value{GDBN} is debugging the AArch64 architecture, it provides the 26397following special commands: 26398 26399@table @code 26400@item set debug aarch64 26401@kindex set debug aarch64 26402This command determines whether AArch64 architecture-specific debugging 26403messages are to be displayed. 26404 26405@item show debug aarch64 26406Show whether AArch64 debugging messages are displayed. 26407 26408@end table 26409 26410@subsubsection AArch64 SVE. 26411@cindex AArch64 SVE. 26412 26413When @value{GDBN} is debugging the AArch64 architecture, if the Scalable Vector 26414Extension (SVE) is present, then @value{GDBN} will provide the vector registers 26415@code{$z0} through @code{$z31}, vector predicate registers @code{$p0} through 26416@code{$p15}, and the @code{$ffr} register. In addition, the pseudo register 26417@code{$vg} will be provided. This is the vector granule for the current thread 26418and represents the number of 64-bit chunks in an SVE @code{z} register. 26419 26420If the vector length changes, then the @code{$vg} register will be updated, 26421but the lengths of the @code{z} and @code{p} registers will not change. This 26422is a known limitation of @value{GDBN} and does not affect the execution of the 26423target process. 26424 26425For SVE, the following definitions are used throughout @value{GDBN}'s source 26426code and in this document: 26427 26428@itemize 26429 26430@item 26431@var{vl}: The vector length, in bytes. It defines the size of each @code{Z} 26432register. 26433@anchor{vl} 26434@cindex vl 26435 26436@item 26437@var{vq}: The number of 128 bit units in @var{vl}. This is mostly used 26438internally by @value{GDBN} and the Linux Kernel. 26439@anchor{vq} 26440@cindex vq 26441 26442@item 26443@var{vg}: The number of 64 bit units in @var{vl}. This is mostly used 26444internally by @value{GDBN} and the Linux Kernel. 26445@anchor{vg} 26446@cindex vg 26447 26448@end itemize 26449 26450@subsubsection AArch64 SME. 26451@anchor{AArch64 SME} 26452@cindex SME 26453@cindex AArch64 SME 26454@cindex Scalable Matrix Extension 26455 26456The Scalable Matrix Extension (@url{https://community.arm.com/arm-community-blogs/b/architectures-and-processors-blog/posts/scalable-matrix-extension-armv9-a-architecture, @acronym{SME}}) 26457is an AArch64 architecture extension that expands on the concept of the 26458Scalable Vector Extension (@url{https://developer.arm.com/documentation/101726/4-0/Learn-about-the-Scalable-Vector-Extension--SVE-/What-is-the-Scalable-Vector-Extension-, @acronym{SVE}}) 26459by providing a 2-dimensional register @code{ZA}, which is a square 26460matrix of variable size, just like SVE provides a group of vector registers of 26461variable size. 26462 26463Similarly to SVE, where the size of each @code{Z} register is directly related 26464to the vector length (@var{vl} for short), the @acronym{SME} @code{ZA} matrix 26465register's size is directly related to the streaming vector length 26466(@var{svl} for short). @xref{vl}. @xref{svl}. 26467 26468The @code{ZA} register state can be either active or inactive, if it is not in 26469use. 26470 26471@acronym{SME} also introduces a new execution mode called streaming 26472@acronym{SVE} mode (streaming mode for short). When streaming mode is 26473enabled, the program supports execution of @acronym{SVE2} instructions and the 26474@acronym{SVE} registers will have vector length @var{svl}. When streaming 26475mode is disabled, the SVE registers have vector length @var{vl}. 26476 26477For more information about @acronym{SME} and @acronym{SVE}, please refer to 26478official @url{https://developer.arm.com/documentation/ddi0487/latest, 26479architecture documentation}. 26480 26481The following definitions are used throughout @value{GDBN}'s source code and 26482in this document: 26483 26484@itemize 26485 26486@item 26487@var{svl}: The streaming vector length, in bytes. It defines the size of each 26488dimension of the 2-dimensional square @code{ZA} matrix. The total size of 26489@code{ZA} is therefore @var{svl} by @var{svl}. 26490 26491When streaming mode is enabled, it defines the size of the @acronym{SVE} 26492registers as well. 26493@anchor{svl} 26494@cindex svl 26495 26496@item 26497@var{svq}: The number of 128 bit units in @var{svl}, also known as streaming 26498vector granule. This is mostly used internally by @value{GDBN} and the Linux 26499Kernel. 26500@anchor{svq} 26501@cindex svq 26502 26503@item 26504@var{svg}: The number of 64 bit units in @var{svl}. This is mostly used 26505internally by @value{GDBN} and the Linux Kernel. 26506@anchor{svg} 26507@cindex svg 26508 26509@end itemize 26510 26511When @value{GDBN} is debugging the AArch64 architecture, if the Scalable Matrix 26512Extension (@acronym{SME}) is present, then @value{GDBN} will make the @code{ZA} 26513register available. @value{GDBN} will also make the @code{SVG} register and 26514@code{SVCR} pseudo-register available. 26515 26516The @code{ZA} register is a 2-dimensional square @var{svl} by @var{svl} 26517matrix of bytes. To simplify the representation and access to the @code{ZA} 26518register in @value{GDBN}, it is defined as a vector of 26519@var{svl}x@var{svl} bytes. 26520 26521If the user wants to index the @code{ZA} register as a matrix, it is possible 26522to reference @code{ZA} as @code{ZA[@var{i}][@var{j}]}, where @var{i} is the 26523row number and @var{j} is the column number. 26524 26525The @code{SVG} register always contains the streaming vector granule 26526(@var{svg}) for the current thread. From the value of register @code{SVG} we 26527can easily derive the @var{svl} value. 26528 26529@anchor{aarch64 sme svcr} 26530The @code{SVCR} pseudo-register (streaming vector control register) is a status 26531register that holds two state bits: @sc{sm} in bit 0 and @sc{za} in bit 1. 26532 26533If the @sc{sm} bit is 1, it means the current thread is in streaming 26534mode, and the @acronym{SVE} registers will use @var{svl} for their sizes. If 26535the @sc{sm} bit is 0, the current thread is not in streaming mode, and the 26536@acronym{SVE} registers will use @var{vl} for their sizes. @xref{vl}. 26537 26538If the @sc{za} bit is 1, it means the @code{ZA} register is being used and 26539has meaningful contents. If the @sc{za} bit is 0, the @code{ZA} register is 26540unavailable and its contents are undefined. 26541 26542For convenience and simplicity, if the @sc{za} bit is 0, the @code{ZA} 26543register and all of its pseudo-registers will read as zero. 26544 26545If @var{svl} changes during the execution of a program, then the @code{ZA} 26546register size and the bits in the @code{SVCR} pseudo-register will be updated 26547to reflect it. 26548 26549It is possible for users to change @var{svl} during the execution of a 26550program by modifying the @code{SVG} register value. 26551 26552Whenever the @code{SVG} register is modified with a new value, the 26553following will be observed: 26554 26555@itemize 26556 26557@item The @sc{za} and @sc{sm} bits will be cleared in the @code{SVCR} 26558pseudo-register. 26559 26560@item The @code{ZA} register will have a new size and its state will be 26561cleared, forcing its contents and the contents of all of its pseudo-registers 26562back to zero. 26563 26564@item If the @sc{sm} bit was 1, the @acronym{SVE} registers will be reset to 26565having their sizes based on @var{vl} as opposed to @var{svl}. If the 26566@sc{sm} bit was 0 prior to modifying the @code{SVG} register, there will be no 26567observable effect on the @acronym{SVE} registers. 26568 26569@end itemize 26570 26571The possible values for the @code{SVG} register are 2, 4, 8, 16, 32. These 26572numbers correspond to streaming vector length (@var{svl}) values of 16 26573bytes, 32 bytes, 64 bytes, 128 bytes and 256 bytes respectively. 26574 26575The minimum size of the @code{ZA} register is 16 x 16 (256) bytes, and the 26576maximum size is 256 x 256 (65536) bytes. In streaming mode, with bit @sc{sm} 26577set, the size of the @code{ZA} register is the size of all the SVE @code{Z} 26578registers combined. 26579 26580The @code{ZA} register can also be accessed using tiles and tile slices. 26581 26582Tile pseudo-registers are square, 2-dimensional sub-arrays of elements within 26583the @code{ZA} register. 26584 26585The tile pseudo-registers have the following naming pattern: 26586@code{ZA<@var{tile number}><@var{qualifier}>}. 26587 26588There is a total of 31 @code{ZA} tile pseudo-registers. They are 26589@code{ZA0B}, @code{ZA0H} through @code{ZA1H}, @code{ZA0S} through @code{ZA3S}, 26590@code{ZA0D} through @code{ZA7D} and @code{ZA0Q} through @code{ZA15Q}. 26591 26592Tile slice pseudo-registers are vectors of horizontally or vertically 26593contiguous elements within the @code{ZA} register. 26594 26595The tile slice pseudo-registers have the following naming pattern: 26596@code{ZA<@var{tile number}><@var{direction}><@var{qualifier}> 26597<@var{slice number}>}. 26598 26599There are up to 16 tiles (0 ~ 15), the direction can be either @code{v} 26600(vertical) or @code{h} (horizontal), the qualifiers can be @code{b} (byte), 26601@code{h} (halfword), @code{s} (word), @code{d} (doubleword) and @code{q} 26602(quadword) and there are up to 256 slices (0 ~ 255) depending on the value 26603of @var{svl}. The number of slices is the same as the value of @var{svl}. 26604 26605The number of available tile slice pseudo-registers can be large. For a 26606minimum @var{svl} of 16 bytes, there are 5 (number of qualifiers) x 266072 (number of directions) x 16 (@var{svl}) pseudo-registers. For the 26608maximum @var{svl} of 256 bytes, there are 5 x 2 x 256 pseudo-registers. 26609 26610When listing all the available registers, users will see the 26611currently-available @code{ZA} pseudo-registers. Pseudo-registers that don't 26612exist for a given @var{svl} value will not be displayed. 26613 26614For more information on @acronym{SME} and its terminology, please refer to the 26615@url{https://developer.arm.com/documentation/ddi0616/aa/, 26616Arm Architecture Reference Manual Supplement}, The Scalable Matrix Extension 26617(@acronym{SME}), for Armv9-A. 26618 26619Some features are still under development and rely on 26620@url{https://github.com/ARM-software/acle/releases/latest, ACLE} and 26621@url{https://github.com/ARM-software/abi-aa/blob/main/aapcs64/aapcs64.rst, ABI} 26622definitions, so there are known limitations to the current @acronym{SME} 26623support in @value{GDBN}. 26624 26625One such example is calling functions in the program being debugged by 26626@value{GDBN}. Such calls are not @acronym{SME}-aware and thus don't take into 26627account the @code{SVCR} pseudo-register bits nor the @code{ZA} register 26628contents. @xref{Calling}. 26629 26630The @url{https://github.com/ARM-software/abi-aa/blob/main/aapcs64/aapcs64.rst#the-za-lazy-saving-scheme, 26631lazy saving scheme} involving the @code{TPIDR2} register is not yet supported 26632by @value{GDBN}, though the @code{TPIDR2} register is known and supported 26633by @value{GDBN}. 26634 26635Lastly, an important limitation for @command{gdbserver} is its inability to 26636communicate @var{svl} changes to @value{GDBN}. This means @command{gdbserver}, 26637even though it is capable of adjusting its internal caches to reflect a change 26638in the value of @var{svl} mid-execution, will operate with a potentially 26639different @var{svl} value compared to @value{GDBN}. This can lead to 26640@value{GDBN} showing incorrect values for the @code{ZA} register and 26641incorrect values for SVE registers (when in streaming mode). 26642 26643This is the same limitation we have for the @acronym{SVE} registers, and there 26644are plans to address this limitation going forward. 26645 26646@subsubsection AArch64 SME2. 26647@anchor{AArch64 SME2} 26648@cindex SME2 26649@cindex AArch64 SME2 26650@cindex Scalable Matrix Extension 2 26651 26652The Scalable Matrix Extension 2 is an AArch64 architecture extension that 26653further expands the @acronym{SME} extension with the following: 26654 26655@itemize 26656 26657@item The ability to address the @code{ZA} array through groups of 26658one-dimensional @code{ZA} array vectors, as opposed to @code{ZA} tiles 26659with 2 dimensions. 26660 26661@item Instructions to operate on groups of @acronym{SVE} @code{Z} registers and 26662@code{ZA} array vectors. 26663 26664@item A new 512 bit @code{ZT0} lookup table register, for data decompression. 26665 26666@end itemize 26667 26668When @value{GDBN} is debugging the AArch64 architecture, if the Scalable Matrix 26669Extension 2 (@acronym{SME2}) is present, then @value{GDBN} will make the 26670@code{ZT0} register available. 26671 26672The @code{ZT0} register is only considered active when the @code{ZA} register 26673state is active, therefore when the @sc{za} bit of the @code{SVCR} is 1. 26674 26675When the @sc{za} bit of @code{SVCR} is 0, that means the @code{ZA} register 26676state is not active, which means the @code{ZT0} register state is also not 26677active. 26678 26679When @code{ZT0} is not active, it is comprised of zeroes, just like @code{ZA}. 26680 26681Similarly to the @code{ZA} register, if the @code{ZT0} state is not active and 26682the user attempts to modify its value such that any of its bytes is non-zero, 26683then @value{GDBN} will initialize the @code{ZA} register state as well, which 26684means the @code{SVCR} @sc{za} bit gets set to 1. 26685 26686For more information about @acronym{SME2}, please refer to the 26687official @url{https://developer.arm.com/documentation/ddi0487/latest, 26688architecture documentation}. 26689 26690@subsubsection AArch64 Pointer Authentication. 26691@cindex AArch64 Pointer Authentication. 26692@anchor{AArch64 PAC} 26693 26694When @value{GDBN} is debugging the AArch64 architecture, and the program is 26695using the v8.3-A feature Pointer Authentication (PAC), then whenever the link 26696register @code{$lr} is pointing to an PAC function its value will be masked. 26697When GDB prints a backtrace, any addresses that required unmasking will be 26698postfixed with the marker [PAC]. When using the MI, this is printed as part 26699of the @code{addr_flags} field. 26700 26701@subsubsection AArch64 Memory Tagging Extension. 26702@cindex AArch64 Memory Tagging Extension. 26703 26704When @value{GDBN} is debugging the AArch64 architecture, the program is 26705using the v8.5-A feature Memory Tagging Extension (MTE) and there is support 26706in the kernel for MTE, @value{GDBN} will make memory tagging functionality 26707available for inspection and editing of logical and allocation tags. 26708@xref{Memory Tagging}. 26709 26710To aid debugging, @value{GDBN} will output additional information when SIGSEGV 26711signals are generated as a result of memory tag failures. 26712 26713If the tag violation is synchronous, the following will be shown: 26714 26715@smallexample 26716Program received signal SIGSEGV, Segmentation fault 26717Memory tag violation while accessing address 0x0500fffff7ff8000 26718Allocation tag 0x1 26719Logical tag 0x5. 26720@end smallexample 26721 26722If the tag violation is asynchronous, the fault address is not available. 26723In this case @value{GDBN} will show the following: 26724 26725@smallexample 26726Program received signal SIGSEGV, Segmentation fault 26727Memory tag violation 26728Fault address unavailable. 26729@end smallexample 26730 26731A special register, @code{tag_ctl}, is made available through the 26732@code{org.gnu.gdb.aarch64.mte} feature. This register exposes some 26733options that can be controlled at runtime and emulates the @code{prctl} 26734option @code{PR_SET_TAGGED_ADDR_CTRL}. For further information, see the 26735documentation in the Linux kernel. 26736 26737@value{GDBN} supports dumping memory tag data to core files through the 26738@command{gcore} command and reading memory tag data from core files generated 26739by the @command{gcore} command or the Linux kernel. 26740 26741When a process uses memory-mapped pages protected by memory tags (for 26742example, AArch64 MTE), this additional information will be recorded in 26743the core file in the event of a crash or if @value{GDBN} generates a core file 26744from the current process state. 26745 26746The memory tag data will be used so developers can display the memory 26747tags from a particular memory region (using the @samp{m} modifier to the 26748@command{x} command, using the @command{print} command or using the various 26749@command{memory-tag} subcommands. 26750 26751In the case of a crash, @value{GDBN} will attempt to retrieve the memory tag 26752information automatically from the core file, and will show one of the above 26753messages depending on whether the synchronous or asynchronous mode is selected. 26754@xref{Memory Tagging}. @xref{Memory}. 26755 26756@node x86 26757@subsection x86 26758 26759@table @code 26760@item set struct-convention @var{mode} 26761@kindex set struct-convention 26762@cindex struct return convention 26763@cindex struct/union returned in registers 26764Set the convention used by the inferior to return @code{struct}s and 26765@code{union}s from functions to @var{mode}. Possible values of 26766@var{mode} are @code{"pcc"}, @code{"reg"}, and @code{"default"} (the 26767default). @code{"default"} or @code{"pcc"} means that @code{struct}s 26768are returned on the stack, while @code{"reg"} means that a 26769@code{struct} or a @code{union} whose size is 1, 2, 4, or 8 bytes will 26770be returned in a register. 26771 26772@item show struct-convention 26773@kindex show struct-convention 26774Show the current setting of the convention to return @code{struct}s 26775from functions. 26776@end table 26777 26778 26779@subsubsection Intel @dfn{Memory Protection Extensions} (MPX). 26780@cindex Intel Memory Protection Extensions (MPX). 26781 26782Memory Protection Extension (MPX) adds the bound registers @samp{BND0} 26783@footnote{The register named with capital letters represent the architecture 26784registers.} through @samp{BND3}. Bound registers store a pair of 64-bit values 26785which are the lower bound and upper bound. Bounds are effective addresses or 26786memory locations. The upper bounds are architecturally represented in 1's 26787complement form. A bound having lower bound = 0, and upper bound = 0 26788(1's complement of all bits set) will allow access to the entire address space. 26789 26790@samp{BND0} through @samp{BND3} are represented in @value{GDBN} as @samp{bnd0raw} 26791through @samp{bnd3raw}. Pseudo registers @samp{bnd0} through @samp{bnd3} 26792display the upper bound performing the complement of one operation on the 26793upper bound value, i.e.@ when upper bound in @samp{bnd0raw} is 0 in the 26794@value{GDBN} @samp{bnd0} it will be @code{0xfff@dots{}}. In this sense it 26795can also be noted that the upper bounds are inclusive. 26796 26797As an example, assume that the register BND0 holds bounds for a pointer having 26798access allowed for the range between 0x32 and 0x71. The values present on 26799bnd0raw and bnd registers are presented as follows: 26800 26801@smallexample 26802 bnd0raw = @{0x32, 0xffffffff8e@} 26803 bnd0 = @{lbound = 0x32, ubound = 0x71@} : size 64 26804@end smallexample 26805 26806This way the raw value can be accessed via bnd0raw@dots{}bnd3raw. Any 26807change on bnd0@dots{}bnd3 or bnd0raw@dots{}bnd3raw is reflect on its 26808counterpart. When the bnd0@dots{}bnd3 registers are displayed via 26809Python, the display includes the memory size, in bits, accessible to 26810the pointer. 26811 26812Bounds can also be stored in bounds tables, which are stored in 26813application memory. These tables store bounds for pointers by specifying 26814the bounds pointer's value along with its bounds. Evaluating and changing 26815bounds located in bound tables is therefore interesting while investigating 26816bugs on MPX context. @value{GDBN} provides commands for this purpose: 26817 26818@table @code 26819@item show mpx bound @var{pointer} 26820@kindex show mpx bound 26821Display bounds of the given @var{pointer}. 26822 26823@item set mpx bound @var{pointer}, @var{lbound}, @var{ubound} 26824@kindex set mpx bound 26825Set the bounds of a pointer in the bound table. 26826This command takes three parameters: @var{pointer} is the pointers 26827whose bounds are to be changed, @var{lbound} and @var{ubound} are new values 26828for lower and upper bounds respectively. 26829@end table 26830 26831Both commands are deprecated and will be removed in future versions of 26832@value{GDBN}. MPX itself was listed as removed by Intel in 2019. 26833 26834When you call an inferior function on an Intel MPX enabled program, 26835GDB sets the inferior's bound registers to the init (disabled) state 26836before calling the function. As a consequence, bounds checks for the 26837pointer arguments passed to the function will always pass. 26838 26839This is necessary because when you call an inferior function, the 26840program is usually in the middle of the execution of other function. 26841Since at that point bound registers are in an arbitrary state, not 26842clearing them would lead to random bound violations in the called 26843function. 26844 26845You can still examine the influence of the bound registers on the 26846execution of the called function by stopping the execution of the 26847called function at its prologue, setting bound registers, and 26848continuing the execution. For example: 26849 26850@smallexample 26851 $ break *upper 26852 Breakpoint 2 at 0x4009de: file i386-mpx-call.c, line 47. 26853 $ print upper (a, b, c, d, 1) 26854 Breakpoint 2, upper (a=0x0, b=0x6e0000005b, c=0x0, d=0x0, len=48).... 26855 $ print $bnd0 26856 @{lbound = 0x0, ubound = ffffffff@} : size -1 26857@end smallexample 26858 26859At this last step the value of bnd0 can be changed for investigation of bound 26860violations caused along the execution of the call. In order to know how to 26861set the bound registers or bound table for the call consult the ABI. 26862 26863@subsubsection x87 registers 26864 26865@value{GDBN} provides access to the x87 state through the following registers: 26866 26867@itemize 26868 26869@item @code{$st0} to @code{st7}: @code{ST(0)} to @code{ST(7)} floating-point 26870registers 26871@item @code{$fctrl}: control word register (@code{FCW}) 26872@item @code{$fstat}: status word register (@code{FSW}) 26873@item @code{$ftag}: tag word (@code{FTW}) 26874@item @code{$fiseg}: last instruction pointer segment 26875@item @code{$fioff}: last instruction pointer 26876@item @code{$foseg}: last data pointer segment 26877@item @code{$fooff}: last data pointer 26878@item @code{$fop}: last opcode 26879 26880@end itemize 26881 26882@node Alpha 26883@subsection Alpha 26884 26885See the following section. 26886 26887@node MIPS 26888@subsection @acronym{MIPS} 26889 26890@cindex stack on Alpha 26891@cindex stack on @acronym{MIPS} 26892@cindex Alpha stack 26893@cindex @acronym{MIPS} stack 26894Alpha- and @acronym{MIPS}-based computers use an unusual stack frame, which 26895sometimes requires @value{GDBN} to search backward in the object code to 26896find the beginning of a function. 26897 26898@cindex response time, @acronym{MIPS} debugging 26899To improve response time (especially for embedded applications, where 26900@value{GDBN} may be restricted to a slow serial line for this search) 26901you may want to limit the size of this search, using one of these 26902commands: 26903 26904@table @code 26905@cindex @code{heuristic-fence-post} (Alpha, @acronym{MIPS}) 26906@item set heuristic-fence-post @var{limit} 26907Restrict @value{GDBN} to examining at most @var{limit} bytes in its 26908search for the beginning of a function. A value of @var{0} (the 26909default) means there is no limit. However, except for @var{0}, the 26910larger the limit the more bytes @code{heuristic-fence-post} must search 26911and therefore the longer it takes to run. You should only need to use 26912this command when debugging a stripped executable. 26913 26914@item show heuristic-fence-post 26915Display the current limit. 26916@end table 26917 26918@noindent 26919These commands are available @emph{only} when @value{GDBN} is configured 26920for debugging programs on Alpha or @acronym{MIPS} processors. 26921 26922Several @acronym{MIPS}-specific commands are available when debugging @acronym{MIPS} 26923programs: 26924 26925@table @code 26926@item set mips abi @var{arg} 26927@kindex set mips abi 26928@cindex set ABI for @acronym{MIPS} 26929Tell @value{GDBN} which @acronym{MIPS} ABI is used by the inferior. Possible 26930values of @var{arg} are: 26931 26932@table @samp 26933@item auto 26934The default ABI associated with the current binary (this is the 26935default). 26936@item o32 26937@item o64 26938@item n32 26939@item n64 26940@item eabi32 26941@item eabi64 26942@end table 26943 26944@item show mips abi 26945@kindex show mips abi 26946Show the @acronym{MIPS} ABI used by @value{GDBN} to debug the inferior. 26947 26948@item set mips compression @var{arg} 26949@kindex set mips compression 26950@cindex code compression, @acronym{MIPS} 26951Tell @value{GDBN} which @acronym{MIPS} compressed 26952@acronym{ISA, Instruction Set Architecture} encoding is used by the 26953inferior. @value{GDBN} uses this for code disassembly and other 26954internal interpretation purposes. This setting is only referred to 26955when no executable has been associated with the debugging session or 26956the executable does not provide information about the encoding it uses. 26957Otherwise this setting is automatically updated from information 26958provided by the executable. 26959 26960Possible values of @var{arg} are @samp{mips16} and @samp{micromips}. 26961The default compressed @acronym{ISA} encoding is @samp{mips16}, as 26962executables containing @acronym{MIPS16} code frequently are not 26963identified as such. 26964 26965This setting is ``sticky''; that is, it retains its value across 26966debugging sessions until reset either explicitly with this command or 26967implicitly from an executable. 26968 26969The compiler and/or assembler typically add symbol table annotations to 26970identify functions compiled for the @acronym{MIPS16} or 26971@acronym{microMIPS} @acronym{ISA}s. If these function-scope annotations 26972are present, @value{GDBN} uses them in preference to the global 26973compressed @acronym{ISA} encoding setting. 26974 26975@item show mips compression 26976@kindex show mips compression 26977Show the @acronym{MIPS} compressed @acronym{ISA} encoding used by 26978@value{GDBN} to debug the inferior. 26979 26980@item set mipsfpu 26981@itemx show mipsfpu 26982@xref{MIPS Embedded, set mipsfpu}. 26983 26984@item set mips mask-address @var{arg} 26985@kindex set mips mask-address 26986@cindex @acronym{MIPS} addresses, masking 26987This command determines whether the most-significant 32 bits of 64-bit 26988@acronym{MIPS} addresses are masked off. The argument @var{arg} can be 26989@samp{on}, @samp{off}, or @samp{auto}. The latter is the default 26990setting, which lets @value{GDBN} determine the correct value. 26991 26992@item show mips mask-address 26993@kindex show mips mask-address 26994Show whether the upper 32 bits of @acronym{MIPS} addresses are masked off or 26995not. 26996 26997@item set remote-mips64-transfers-32bit-regs 26998@kindex set remote-mips64-transfers-32bit-regs 26999This command controls compatibility with 64-bit @acronym{MIPS} targets that 27000transfer data in 32-bit quantities. If you have an old @acronym{MIPS} 64 target 27001that transfers 32 bits for some registers, like @sc{sr} and @sc{fsr}, 27002and 64 bits for other registers, set this option to @samp{on}. 27003 27004@item show remote-mips64-transfers-32bit-regs 27005@kindex show remote-mips64-transfers-32bit-regs 27006Show the current setting of compatibility with older @acronym{MIPS} 64 targets. 27007 27008@item set debug mips 27009@kindex set debug mips 27010This command turns on and off debugging messages for the @acronym{MIPS}-specific 27011target code in @value{GDBN}. 27012 27013@item show debug mips 27014@kindex show debug mips 27015Show the current setting of @acronym{MIPS} debugging messages. 27016@end table 27017 27018 27019@node HPPA 27020@subsection HPPA 27021@cindex HPPA support 27022 27023When @value{GDBN} is debugging the HP PA architecture, it provides the 27024following special commands: 27025 27026@table @code 27027@item set debug hppa 27028@kindex set debug hppa 27029This command determines whether HPPA architecture-specific debugging 27030messages are to be displayed. 27031 27032@item show debug hppa 27033Show whether HPPA debugging messages are displayed. 27034 27035@item maint print unwind @var{address} 27036@kindex maint print unwind@r{, HPPA} 27037This command displays the contents of the unwind table entry at the 27038given @var{address}. 27039 27040@end table 27041 27042 27043@node PowerPC 27044@subsection PowerPC 27045@cindex PowerPC architecture 27046 27047When @value{GDBN} is debugging the PowerPC architecture, it provides a set of 27048pseudo-registers to enable inspection of 128-bit wide Decimal Floating Point 27049numbers stored in the floating point registers. These values must be stored 27050in two consecutive registers, always starting at an even register like 27051@code{f0} or @code{f2}. 27052 27053The pseudo-registers go from @code{$dl0} through @code{$dl15}, and are formed 27054by joining the even/odd register pairs @code{f0} and @code{f1} for @code{$dl0}, 27055@code{f2} and @code{f3} for @code{$dl1} and so on. 27056 27057For POWER7 processors, @value{GDBN} provides a set of pseudo-registers, the 64-bit 27058wide Extended Floating Point Registers (@samp{f32} through @samp{f63}). 27059 27060@node Nios II 27061@subsection Nios II 27062@cindex Nios II architecture 27063 27064When @value{GDBN} is debugging the Nios II architecture, 27065it provides the following special commands: 27066 27067@table @code 27068 27069@item set debug nios2 27070@kindex set debug nios2 27071This command turns on and off debugging messages for the Nios II 27072target code in @value{GDBN}. 27073 27074@item show debug nios2 27075@kindex show debug nios2 27076Show the current setting of Nios II debugging messages. 27077@end table 27078 27079@node Sparc64 27080@subsection Sparc64 27081@cindex Sparc64 support 27082@cindex Application Data Integrity 27083@subsubsection ADI Support 27084 27085The M7 processor supports an Application Data Integrity (ADI) feature that 27086detects invalid data accesses. When software allocates memory and enables 27087ADI on the allocated memory, it chooses a 4-bit version number, sets the 27088version in the upper 4 bits of the 64-bit pointer to that data, and stores 27089the 4-bit version in every cacheline of that data. Hardware saves the latter 27090in spare bits in the cache and memory hierarchy. On each load and store, 27091the processor compares the upper 4 VA (virtual address) bits to the 27092cacheline's version. If there is a mismatch, the processor generates a 27093version mismatch trap which can be either precise or disrupting. The trap 27094is an error condition which the kernel delivers to the process as a SIGSEGV 27095signal. 27096 27097Note that only 64-bit applications can use ADI and need to be built with 27098ADI-enabled. 27099 27100Values of the ADI version tags, which are in granularity of a 27101cacheline (64 bytes), can be viewed or modified. 27102 27103 27104@table @code 27105@kindex adi examine 27106@item adi (examine | x) [ / @var{n} ] @var{addr} 27107 27108The @code{adi examine} command displays the value of one ADI version tag per 27109cacheline. 27110 27111@var{n} is a decimal integer specifying the number in bytes; the default 27112is 1. It specifies how much ADI version information, at the ratio of 1:ADI 27113block size, to display. 27114 27115@var{addr} is the address in user address space where you want @value{GDBN} 27116to begin displaying the ADI version tags. 27117 27118Below is an example of displaying ADI versions of variable "shmaddr". 27119 27120@smallexample 27121(@value{GDBP}) adi x/100 shmaddr 27122 0xfff800010002c000: 0 0 27123@end smallexample 27124 27125@kindex adi assign 27126@item adi (assign | a) [ / @var{n} ] @var{addr} = @var{tag} 27127 27128The @code{adi assign} command is used to assign new ADI version tag 27129to an address. 27130 27131@var{n} is a decimal integer specifying the number in bytes; 27132the default is 1. It specifies how much ADI version information, at the 27133ratio of 1:ADI block size, to modify. 27134 27135@var{addr} is the address in user address space where you want @value{GDBN} 27136to begin modifying the ADI version tags. 27137 27138@var{tag} is the new ADI version tag. 27139 27140For example, do the following to modify then verify ADI versions of 27141variable "shmaddr": 27142 27143@smallexample 27144(@value{GDBP}) adi a/100 shmaddr = 7 27145(@value{GDBP}) adi x/100 shmaddr 27146 0xfff800010002c000: 7 7 27147@end smallexample 27148 27149@end table 27150 27151@node S12Z 27152@subsection S12Z 27153@cindex S12Z support 27154 27155When @value{GDBN} is debugging the S12Z architecture, 27156it provides the following special command: 27157 27158@table @code 27159@item maint info bdccsr 27160@kindex maint info bdccsr@r{, S12Z} 27161This command displays the current value of the microprocessor's 27162BDCCSR register. 27163@end table 27164 27165@node AMD GPU 27166@subsection @acronym{AMD GPU} 27167@cindex @acronym{AMD GPU} support 27168 27169@value{GDBN} supports debugging programs offloaded to @acronym{AMD GPU} devices 27170using the @url{https://docs.amd.com/, @acronym{AMD ROCm}} platform. 27171@value{GDBN} presents host threads alongside GPU wavefronts, allowing debugging 27172both the host and device parts of the program simultaneously. 27173 27174@subsubsection @acronym{AMD GPU} Architectures 27175 27176The list of @acronym{AMD GPU} architectures supported by @value{GDBN} depends 27177on the version of the AMD Debugger API library used. See its 27178@uref{https://docs.amd.com/bundle/ROCDebugger_User_and_API, documentation} for 27179more details. 27180 27181@subsubsection @acronym{AMD GPU} Device Driver and @acronym{AMD ROCm} Runtime 27182 27183@value{GDBN} requires a compatible @acronym{AMD GPU} device driver to 27184be installed. A warning message is displayed if either the device 27185driver version or the version of the debug support it implements is 27186unsupported. @value{GDBN} will continue to function except no 27187@acronym{AMD GPU} debugging will be possible. 27188 27189@value{GDBN} requires each agent to have compatible firmware installed 27190by the device driver. A warning message is displayed if unsupported 27191firmware is detected. @value{GDBN} will continue to function except 27192no @acronym{AMD GPU} debugging will be possible on the agent. 27193 27194@value{GDBN} requires a compatible @acronym{AMD ROCm} runtime to be 27195loaded in order to detect @acronym{AMD GPU} code objects and 27196wavefronts. A warning message is displayed if an unsupported 27197@acronym{AMD ROCm} runtime is detected, or there is an error or 27198restriction that prevents debugging. @value{GDBN} will continue to 27199function except no @acronym{AMD GPU} debugging will be possible. 27200 27201@subsubsection @acronym{AMD GPU} Wavefronts 27202@cindex wavefronts 27203 27204An @acronym{AMD GPU} wavefront is represented in @value{GDBN} as a 27205thread. 27206 27207Note that some @acronym{AMD GPU} architectures may have restrictions 27208on providing information about @acronym{AMD GPU} wavefronts created 27209when @value{GDBN} is not attached (@pxref{AMD GPU Attaching 27210Restrictions, , @acronym{AMD GPU} Attaching Restrictions}). 27211 27212When scheduler-locking is in effect (@pxref{set scheduler-locking}), 27213new wavefronts created by the resumed thread (either CPU thread or GPU 27214wavefront) are held in the halt state. 27215 27216@subsubsection @acronym{AMD GPU} Code Objects 27217 27218The @samp{info sharedlibrary} command will show the @acronym{AMD GPU} 27219code objects as file or memory URIs, together with the host's shared 27220libraries. For example: 27221 27222@smallexample 27223(@value{GDBP}) info sharedlibrary 27224From To Syms Read Shared Object Library 272250x1111 0x2222 Yes (*) /lib64/ld-linux-x86-64.so.2 27226... 272270x3333 0x4444 Yes (*) /opt/rocm-4.5.0/.../libamd_comgr.so 272280x5555 0x6666 Yes (*) /lib/x86_64-linux-gnu/libtinfo.so.5 272290x7777 0x8888 Yes file:///tmp/a.out#offset=6477&size=10832 272300x9999 0xaaaa Yes (*) memory://95557/mem#offset=0x1234&size=100 27231(*): Shared library is missing debugging information. 27232(@value{GDBP}) 27233@end smallexample 27234 27235For a @samp{file} URI, the path portion is the file on disk containing 27236the code object. The @var{offset} parameter is a 0-based offset in 27237this file, to the start of the code object. If omitted, it defaults to 272380. The @var{size} parameter is the size of the code object in bytes. 27239If omitted, it defaults to the size of the file. 27240 27241For a @samp{memory} URI, the path portion is the process id of the 27242process owning the memory containing the code object. The @var{offset} 27243parameter is the memory address where the code object is found, and 27244the @var{size} parameter is its size in bytes. 27245 27246@acronym{AMD GPU} code objects are loaded into each @acronym{AMD GPU} 27247device separately. The @samp{info sharedlibrary} command may 27248therefore show the same code object loaded multiple times. As a 27249consequence, setting a breakpoint in @acronym{AMD GPU} code will 27250result in multiple breakpoint locations if there are multiple 27251@acronym{AMD GPU} devices. 27252 27253@subsubsection @acronym{AMD GPU} Entity Target Identifiers and Convenience Variables 27254 27255The @acronym{AMD GPU} entities have the following target identifier formats: 27256 27257@table @asis 27258 27259@item Thread Target ID 27260The @acronym{AMD GPU} thread target identifier (@var{systag}) string has the 27261following format: 27262 27263@smallexample 27264AMDGPU Wave @var{agent-id}:@var{queue-id}:@var{dispatch-id}:@var{wave-id} (@var{work-group-x},@var{work-group-y},@var{work-group-z})/@var{work-group-thread-index} 27265@end smallexample 27266 27267@end table 27268 27269@anchor{AMD GPU Signals} 27270@subsubsection @acronym{AMD GPU} Signals 27271 27272For @acronym{AMD GPU} wavefronts, @value{GDBN} maps target conditions to stop 27273signals in the following way: 27274 27275@table @code 27276 27277@item SIGILL 27278Execution of an illegal instruction. 27279 27280@item SIGTRAP 27281Execution of a @code{S_TRAP} instruction other than: 27282 27283@itemize @bullet{} 27284 27285@item 27286@code{S_TRAP 1} which is used by @value{GDBN} to insert breakpoints. 27287 27288@item 27289@code{S_TRAP 2} which raises @code{SIGABRT}. 27290 27291@end itemize 27292 27293@item SIGABRT 27294Execution of a @code{S_TRAP 2} instruction. 27295 27296@item SIGFPE 27297Execution of a floating point or integer instruction detects a 27298condition that is enabled to raise a signal. The conditions include: 27299 27300@itemize @bullet{} 27301 27302@item 27303Floating point operation is invalid. 27304 27305@item 27306Floating point operation had subnormal input that was rounded to zero. 27307 27308@item 27309Floating point operation performed a division by zero. 27310 27311@item 27312Floating point operation produced an overflow result. The result was 27313rounded to infinity. 27314 27315@item 27316Floating point operation produced an underflow result. A subnormal 27317result was rounded to zero. 27318 27319@item 27320Floating point operation produced an inexact result. 27321 27322@item 27323Integer operation performed a division by zero. 27324 27325@end itemize 27326 27327By default, these conditions are not enabled to raise signals. The 27328@samp{set $mode} command can be used to change the @acronym{AMD GPU} 27329wavefront's register that has bits controlling which conditions are 27330enabled to raise signals. The @samp{print $trapsts} command can be 27331used to inspect which conditions have been detected even if they are 27332not enabled to raise a signal. 27333 27334@item SIGBUS 27335Execution of an instruction that accessed global memory using an 27336address that is outside the virtual address range. 27337 27338@item SIGSEGV 27339Execution of an instruction that accessed a global memory page that is 27340either not mapped or accessed with incompatible permissions. 27341 27342@end table 27343 27344If a single instruction raises more than one signal, they will be 27345reported one at a time each time the wavefront is continued. 27346 27347@subsubsection @acronym{AMD GPU} Memory Violation Reporting 27348 27349A wavefront can report memory violation events. However, the program 27350location at which they are reported may be after the machine instruction 27351that caused them. This can result in the reported source statement 27352being incorrect. The following commands can be used to control this 27353behavior: 27354 27355@table @code 27356 27357@kindex set amdgpu precise-memory 27358@cindex AMD GPU precise memory event reporting 27359@item set amdgpu precise-memory @var{mode} 27360Controls how @acronym{AMD GPU} devices detect memory violations, where 27361@var{mode} can be: 27362 27363@table @code 27364 27365@item off 27366The program location may not be immediately after the instruction that 27367caused the memory violation. This is the default. 27368 27369@item on 27370Requests that the program location will be immediately after the 27371instruction that caused a memory violation. Enabling this mode may make 27372the @acronym{AMD GPU} device execution significantly slower as it has to 27373wait for each memory operation to complete before executing the next 27374instruction. 27375 27376@end table 27377 27378The @code{amdgpu precise-memory} parameter is per-inferior. When an 27379inferior forks or execs, or the user uses the @code{clone-inferior} command, 27380and an inferior is created as a result, the newly created inferior inherits 27381the parameter value of the original inferior. 27382 27383@kindex show amdgpu precise-memory 27384@cindex AMD GPU precise memory event reporting 27385@item show amdgpu precise-memory 27386Displays the currently requested AMD GPU precise memory setting. 27387 27388@end table 27389 27390@subsubsection @acronym{AMD GPU} Logging 27391 27392The @samp{set debug amd-dbgapi} command can be used 27393to enable diagnostic messages in the @samp{amd-dbgapi} target. The 27394@samp{show debug amd-dbgapi} command displays the current setting. 27395@xref{set debug amd-dbgapi}. 27396 27397The @samp{set debug amd-dbgapi-lib log-level @var{level}} command can be used 27398to enable diagnostic messages from the @samp{amd-dbgapi} library (which 27399@value{GDBN} uses under the hood). The @samp{show debug amd-dbgapi-lib 27400log-level} command displays the current @samp{amd-dbgapi} library log level. 27401@xref{set debug amd-dbgapi-lib}. 27402 27403@subsubsection @acronym{AMD GPU} Restrictions 27404 27405@enumerate 27406 27407@item 27408When in non-stop mode, wavefronts may not hit breakpoints inserted 27409while not stopped, nor see memory updates made while not stopped, 27410until the wavefront is next stopped. Memory updated by non-stopped 27411wavefronts may not be visible until the wavefront is next stopped. 27412 27413@item The HIP runtime performs deferred code object loading by default. 27414@acronym{AMD GPU} code objects are not loaded until the first kernel is 27415launched. Before then, all breakpoints have to be set as pending breakpoints. 27416 27417If source line positions are used that only correspond to source lines in 27418unloaded code objects, then @value{GDBN} may not set pending breakpoints, and 27419instead set breakpoints on the next following source line that maps to host 27420code. This can result in unexpected breakpoint hits being reported. When the 27421code object containing the source lines is loaded, the incorrect breakpoints 27422will be removed and replaced by the correct ones. This problem can be avoided 27423by only setting breakpoints in unloaded code objects using symbol or function 27424names. 27425 27426Setting the @code{HIP_ENABLE_DEFERRED_LOADING} environment variable to @code{0} 27427can be used to disable deferred code object loading by the HIP runtime. This 27428ensures all code objects will be loaded when the inferior reaches the beginning 27429of the @code{main} function. 27430 27431@item 27432If no CPU thread is running, then @samp{Ctrl-C} is not able to stop 27433@acronym{AMD GPU} threads. This can happen for example if you enable 27434@code{scheduler-locking} after the whole program stopped, and then resume an 27435@acronym{AMD GPU} thread. The only way to unblock the situation is to kill the 27436@value{GDBN} process. 27437 27438@anchor{AMD GPU Attaching Restrictions} 27439@item 27440 27441By default, for some architectures, the @acronym{AMD GPU} device driver causes 27442all @acronym{AMD GPU} wavefronts created when @value{GDBN} is not attached to 27443be unable to report the dispatch associated with the wavefront, or the 27444wavefront's work-group position. The @samp{info threads} command will display 27445this missing information with a @samp{?}. 27446 27447This does not affect wavefronts created while @value{GDBN} is attached which 27448are always capable of reporting this information. 27449 27450If the @env{HSA_ENABLE_DEBUG} environment variable is set to @samp{1} when the 27451@acronym{AMD ROCm} runtime is initialized, then this information will be 27452available for all architectures even for wavefronts created when @value{GDBN} 27453was not attached. 27454 27455@end enumerate 27456 27457@node Controlling GDB 27458@chapter Controlling @value{GDBN} 27459 27460You can alter the way @value{GDBN} interacts with you by using the 27461@code{set} command. For commands controlling how @value{GDBN} displays 27462data, see @ref{Print Settings, ,Print Settings}. Other settings are 27463described here. 27464 27465@menu 27466* Prompt:: Prompt 27467* Editing:: Command editing 27468* Command History:: Command history 27469* Screen Size:: Screen size 27470* Output Styling:: Output styling 27471* Numbers:: Numbers 27472* ABI:: Configuring the current ABI 27473* Auto-loading:: Automatically loading associated files 27474* Messages/Warnings:: Optional warnings and messages 27475* Debugging Output:: Optional messages about internal happenings 27476* Other Misc Settings:: Other Miscellaneous Settings 27477@end menu 27478 27479@node Prompt 27480@section Prompt 27481 27482@cindex prompt 27483 27484@value{GDBN} indicates its readiness to read a command by printing a string 27485called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You 27486can change the prompt string with the @code{set prompt} command. For 27487instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change 27488the prompt in one of the @value{GDBN} sessions so that you can always tell 27489which one you are talking to. 27490 27491@emph{Note:} @code{set prompt} does not add a space for you after the 27492prompt you set. This allows you to set a prompt which ends in a space 27493or a prompt that does not. 27494 27495@table @code 27496@kindex set prompt 27497@item set prompt @var{newprompt} 27498Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth. 27499 27500@kindex show prompt 27501@item show prompt 27502Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}} 27503@end table 27504 27505Versions of @value{GDBN} that ship with Python scripting enabled have 27506prompt extensions. The commands for interacting with these extensions 27507are: 27508 27509@table @code 27510@kindex set extended-prompt 27511@item set extended-prompt @var{prompt} 27512Set an extended prompt that allows for substitutions. 27513@xref{gdb.prompt}, for a list of escape sequences that can be used for 27514substitution. Any escape sequences specified as part of the prompt 27515string are replaced with the corresponding strings each time the prompt 27516is displayed. 27517 27518For example: 27519 27520@smallexample 27521set extended-prompt Current working directory: \w (@value{GDBP}) 27522@end smallexample 27523 27524Note that when an extended-prompt is set, it takes control of the 27525@var{prompt_hook} hook. @xref{prompt_hook}, for further information. 27526 27527@kindex show extended-prompt 27528@item show extended-prompt 27529Prints the extended prompt. Any escape sequences specified as part of 27530the prompt string with @code{set extended-prompt}, are replaced with the 27531corresponding strings each time the prompt is displayed. 27532@end table 27533 27534@node Editing 27535@section Command Editing 27536@cindex readline 27537@cindex command line editing 27538 27539@value{GDBN} reads its input commands via the @dfn{Readline} interface. This 27540@sc{gnu} library provides consistent behavior for programs which provide a 27541command line interface to the user. Advantages are @sc{gnu} Emacs-style 27542or @dfn{vi}-style inline editing of commands, @code{csh}-like history 27543substitution, and a storage and recall of command history across 27544debugging sessions. 27545 27546You may control the behavior of command line editing in @value{GDBN} with the 27547command @code{set}. 27548 27549@table @code 27550@kindex set editing 27551@cindex editing 27552@item set editing 27553@itemx set editing on 27554Enable command line editing (enabled by default). 27555 27556@item set editing off 27557Disable command line editing. 27558 27559@kindex show editing 27560@item show editing 27561Show whether command line editing is enabled. 27562@end table 27563 27564@ifset SYSTEM_READLINE 27565@xref{Command Line Editing, , , rluserman, GNU Readline Library}, 27566@end ifset 27567@ifclear SYSTEM_READLINE 27568@xref{Command Line Editing}, 27569@end ifclear 27570for more details about the Readline 27571interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are 27572encouraged to read that chapter. 27573 27574@cindex Readline application name 27575@value{GDBN} sets the Readline application name to @samp{gdb}. This 27576is useful for conditions in @file{.inputrc}. 27577 27578@cindex operate-and-get-next 27579@value{GDBN} defines a bindable Readline command, 27580@code{operate-and-get-next}. This is bound to @kbd{C-o} by default. 27581This command accepts the current line for execution and fetches the 27582next line relative to the current line from the history for editing. 27583Any argument is ignored. 27584 27585@node Command History 27586@section Command History 27587@cindex command history 27588 27589@value{GDBN} can keep track of the commands you type during your 27590debugging sessions, so that you can be certain of precisely what 27591happened. Use these commands to manage the @value{GDBN} command 27592history facility. 27593 27594@value{GDBN} uses the @sc{gnu} History library, a part of the Readline 27595package, to provide the history facility. 27596@ifset SYSTEM_READLINE 27597@xref{Using History Interactively, , , history, GNU History Library}, 27598@end ifset 27599@ifclear SYSTEM_READLINE 27600@xref{Using History Interactively}, 27601@end ifclear 27602for the detailed description of the History library. 27603 27604To issue a command to @value{GDBN} without affecting certain aspects of 27605the state which is seen by users, prefix it with @samp{server } 27606(@pxref{Server Prefix}). This 27607means that this command will not affect the command history, nor will it 27608affect @value{GDBN}'s notion of which command to repeat if @key{RET} is 27609pressed on a line by itself. 27610 27611@cindex @code{server}, command prefix 27612The server prefix does not affect the recording of values into the value 27613history; to print a value without recording it into the value history, 27614use the @code{output} command instead of the @code{print} command. 27615 27616Here is the description of @value{GDBN} commands related to command 27617history. 27618 27619@table @code 27620@cindex history substitution 27621@cindex history file 27622@kindex set history filename 27623@cindex @env{GDBHISTFILE}, environment variable 27624@item set history filename @r{[}@var{fname}@r{]} 27625Set the name of the @value{GDBN} command history file to @var{fname}. 27626This is the file where @value{GDBN} reads an initial command history 27627list, and where it writes the command history from this session when it 27628exits. You can access this list through history expansion or through 27629the history command editing characters listed below. This file defaults 27630to the value of the environment variable @env{GDBHISTFILE}, or to 27631@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable 27632is not set. 27633 27634The @env{GDBHISTFILE} environment variable is read after processing 27635any @value{GDBN} initialization files (@pxref{Startup}) and after 27636processing any commands passed using command line options (for 27637example, @code{-ex}). 27638 27639If the @var{fname} argument is not given, or if the @env{GDBHISTFILE} 27640is the empty string then @value{GDBN} will neither try to load an 27641existing history file, nor will it try to save the history on exit. 27642 27643@cindex save command history 27644@kindex set history save 27645@item set history save 27646@itemx set history save on 27647Record command history in a file, whose name may be specified with the 27648@code{set history filename} command. By default, this option is 27649disabled. The command history will be recorded when @value{GDBN} 27650exits. If @code{set history filename} is set to the empty string then 27651history saving is disabled, even when @code{set history save} is 27652@code{on}. 27653 27654@item set history save off 27655Don't record the command history into the file specified by @code{set 27656history filename} when @value{GDBN} exits. 27657 27658@cindex history size 27659@kindex set history size 27660@cindex @env{GDBHISTSIZE}, environment variable 27661@item set history size @var{size} 27662@itemx set history size unlimited 27663Set the number of commands which @value{GDBN} keeps in its history list. 27664This defaults to the value of the environment variable @env{GDBHISTSIZE}, or 27665to 256 if this variable is not set. Non-numeric values of @env{GDBHISTSIZE} 27666are ignored. If @var{size} is @code{unlimited} or if @env{GDBHISTSIZE} is 27667either a negative number or the empty string, then the number of commands 27668@value{GDBN} keeps in the history list is unlimited. 27669 27670The @env{GDBHISTSIZE} environment variable is read after processing 27671any @value{GDBN} initialization files (@pxref{Startup}) and after 27672processing any commands passed using command line options (for 27673example, @code{-ex}). 27674 27675@cindex remove duplicate history 27676@kindex set history remove-duplicates 27677@item set history remove-duplicates @var{count} 27678@itemx set history remove-duplicates unlimited 27679Control the removal of duplicate history entries in the command history list. 27680If @var{count} is non-zero, @value{GDBN} will look back at the last @var{count} 27681history entries and remove the first entry that is a duplicate of the current 27682entry being added to the command history list. If @var{count} is 27683@code{unlimited} then this lookbehind is unbounded. If @var{count} is 0, then 27684removal of duplicate history entries is disabled. 27685 27686Only history entries added during the current session are considered for 27687removal. This option is set to 0 by default. 27688 27689@end table 27690 27691History expansion assigns special meaning to the character @kbd{!}. 27692@ifset SYSTEM_READLINE 27693@xref{Event Designators, , , history, GNU History Library}, 27694@end ifset 27695@ifclear SYSTEM_READLINE 27696@xref{Event Designators}, 27697@end ifclear 27698for more details. 27699 27700@cindex history expansion, turn on/off 27701Since @kbd{!} is also the logical not operator in C, history expansion 27702is off by default. If you decide to enable history expansion with the 27703@code{set history expansion on} command, you may sometimes need to 27704follow @kbd{!} (when it is used as logical not, in an expression) with 27705a space or a tab to prevent it from being expanded. The readline 27706history facilities do not attempt substitution on the strings 27707@kbd{!=} and @kbd{!(}, even when history expansion is enabled. 27708 27709The commands to control history expansion are: 27710 27711@table @code 27712@item set history expansion on 27713@itemx set history expansion 27714@kindex set history expansion 27715Enable history expansion. History expansion is off by default. 27716 27717@item set history expansion off 27718Disable history expansion. 27719 27720@c @group 27721@kindex show history 27722@item show history 27723@itemx show history filename 27724@itemx show history save 27725@itemx show history size 27726@itemx show history expansion 27727These commands display the state of the @value{GDBN} history parameters. 27728@code{show history} by itself displays all four states. 27729@c @end group 27730@end table 27731 27732@table @code 27733@kindex show commands 27734@cindex show last commands 27735@cindex display command history 27736@item show commands 27737Display the last ten commands in the command history. 27738 27739@item show commands @var{n} 27740Print ten commands centered on command number @var{n}. 27741 27742@item show commands + 27743Print ten commands just after the commands last printed. 27744@end table 27745 27746@node Screen Size 27747@section Screen Size 27748@cindex size of screen 27749@cindex screen size 27750@cindex pagination 27751@cindex page size 27752@cindex pauses in output 27753 27754Certain commands to @value{GDBN} may produce large amounts of 27755information output to the screen. To help you read all of it, 27756@value{GDBN} pauses and asks you for input at the end of each page of 27757output. Type @key{RET} when you want to see one more page of output, 27758@kbd{q} to discard the remaining output, or @kbd{c} to continue 27759without paging for the rest of the current command. Also, the screen 27760width setting determines when to wrap lines of output. Depending on 27761what is being printed, @value{GDBN} tries to break the line at a 27762readable place, rather than simply letting it overflow onto the 27763following line. 27764 27765Normally @value{GDBN} knows the size of the screen from the terminal 27766driver software. For example, on Unix @value{GDBN} uses the termcap data base 27767together with the value of the @env{TERM} environment variable and the 27768@code{stty rows} and @code{stty cols} settings. If this is not correct, 27769you can override it with the @code{set height} and @code{set 27770width} commands: 27771 27772@table @code 27773@kindex set height 27774@kindex set width 27775@kindex show width 27776@kindex show height 27777@item set height @var{lpp} 27778@itemx set height unlimited 27779@itemx show height 27780@itemx set width @var{cpl} 27781@itemx set width unlimited 27782@itemx show width 27783These @code{set} commands specify a screen height of @var{lpp} lines and 27784a screen width of @var{cpl} characters. The associated @code{show} 27785commands display the current settings. 27786 27787If you specify a height of either @code{unlimited} or zero lines, 27788@value{GDBN} does not pause during output no matter how long the 27789output is. This is useful if output is to a file or to an editor 27790buffer. 27791 27792Likewise, you can specify @samp{set width unlimited} or @samp{set 27793width 0} to prevent @value{GDBN} from wrapping its output. 27794 27795@item set pagination on 27796@itemx set pagination off 27797@kindex set pagination 27798Turn the output pagination on or off; the default is on. Turning 27799pagination off is the alternative to @code{set height unlimited}. Note that 27800running @value{GDBN} with the @option{--batch} option (@pxref{Mode 27801Options, -batch}) also automatically disables pagination. 27802 27803@item show pagination 27804@kindex show pagination 27805Show the current pagination mode. 27806@end table 27807 27808@node Output Styling 27809@section Output Styling 27810@cindex styling 27811@cindex colors 27812 27813@kindex set style 27814@kindex show style 27815@value{GDBN} can style its output on a capable terminal. This is 27816enabled by default on most systems, but disabled by default when in 27817batch mode (@pxref{Mode Options}). Various style settings are available; 27818and styles can also be disabled entirely. 27819 27820@table @code 27821@item set style enabled @samp{on|off} 27822Enable or disable all styling. The default is host-dependent, with 27823most hosts defaulting to @samp{on}. 27824 27825If the @env{NO_COLOR} environment variable is set to a non-empty 27826value, then @value{GDBN} will change this to @samp{off} at startup. 27827 27828@item show style enabled 27829Show the current state of styling. 27830 27831@item set style sources @samp{on|off} 27832Enable or disable source code styling. This affects whether source 27833code, such as the output of the @code{list} command, is styled. The 27834default is @samp{on}. Note that source styling only works if styling 27835in general is enabled, and if a source highlighting library is 27836available to @value{GDBN}. 27837 27838There are two ways that highlighting can be done. First, if 27839@value{GDBN} was linked with the GNU Source Highlight library, then it 27840is used. Otherwise, if @value{GDBN} was configured with Python 27841scripting support, and if the Python Pygments package is available, 27842then it will be used. 27843 27844@item show style sources 27845Show the current state of source code styling. 27846 27847@item set style tui-current-position @samp{on|off} 27848Enable or disable styling of the source and assembly code highlighted 27849by the TUI's current position indicator. The default is @samp{off}. 27850@xref{TUI, ,@value{GDBN} Text User Interface}. 27851 27852@item show style tui-current-position 27853Show whether the source and assembly code highlighted by the TUI's 27854current position indicator is styled. 27855 27856@anchor{style_disassembler_enabled} 27857@item set style disassembler enabled @samp{on|off} 27858Enable or disable disassembler styling. This affects whether 27859disassembler output, such as the output of the @code{disassemble} 27860command, is styled. Disassembler styling only works if styling in 27861general is enabled (with @code{set style enabled on}), and if a source 27862highlighting library is available to @value{GDBN}. 27863 27864The two source highlighting libraries that @value{GDBN} could use to 27865style disassembler output are; @value{GDBN}'s builtin disassembler, or 27866the Python Pygments package. 27867 27868@value{GDBN}'s first choice will be to use the builtin disassembler 27869for styling, this usually provides better results, being able to style 27870different types of instruction operands differently. However, the 27871builtin disassembler is not able to style all architectures. 27872 27873For architectures that the builtin disassembler is unable to style, 27874@value{GDBN} will fall back to use the Python Pygments package where 27875possible. In order to use the Python Pygments package, @value{GDBN} 27876must be built with Python support, and the Pygments package must be 27877installed. 27878 27879If neither of these options are available then @value{GDBN} will 27880produce unstyled disassembler output, even when this setting is 27881@samp{on}. 27882 27883To discover if the current architecture supports styling using the 27884builtin disassembler library see @ref{maint_libopcodes_styling,,@kbd{maint 27885show libopcodes-styling enabled}}. 27886 27887@item show style disassembler enabled 27888Show the current state of disassembler styling. 27889 27890@end table 27891 27892Subcommands of @code{set style} control specific forms of styling. 27893These subcommands all follow the same pattern: each style-able object 27894can be styled with a foreground color, a background color, and an 27895intensity. 27896 27897For example, the style of file names can be controlled using the 27898@code{set style filename} group of commands: 27899 27900@table @code 27901@item set style filename background @var{color} 27902Set the background to @var{color}. Valid colors are @samp{none} 27903(meaning the terminal's default color), @samp{black}, @samp{red}, 27904@samp{green}, @samp{yellow}, @samp{blue}, @samp{magenta}, @samp{cyan}, 27905and@samp{white}. 27906 27907@item set style filename foreground @var{color} 27908Set the foreground to @var{color}. Valid colors are @samp{none} 27909(meaning the terminal's default color), @samp{black}, @samp{red}, 27910@samp{green}, @samp{yellow}, @samp{blue}, @samp{magenta}, @samp{cyan}, 27911and@samp{white}. 27912 27913@item set style filename intensity @var{value} 27914Set the intensity to @var{value}. Valid intensities are @samp{normal} 27915(the default), @samp{bold}, and @samp{dim}. 27916@end table 27917 27918The @code{show style} command and its subcommands are styling 27919a style name in their output using its own style. 27920So, use @command{show style} to see the complete list of styles, 27921their characteristics and the visual aspect of each style. 27922 27923The style-able objects are: 27924@table @code 27925@item filename 27926Control the styling of file names and URLs. By default, this style's 27927foreground color is green. 27928 27929@item function 27930Control the styling of function names. These are managed with the 27931@code{set style function} family of commands. By default, this 27932style's foreground color is yellow. 27933 27934This style is also used for symbol names in styled disassembler output 27935if @value{GDBN} is using its builtin disassembler library for styling 27936(@pxref{style_disassembler_enabled,,@kbd{set style disassembler 27937enabled}}). 27938 27939@item variable 27940Control the styling of variable names. These are managed with the 27941@code{set style variable} family of commands. By default, this style's 27942foreground color is cyan. 27943 27944@item address 27945Control the styling of addresses. These are managed with the 27946@code{set style address} family of commands. By default, this style's 27947foreground color is blue. 27948 27949This style is also used for addresses in styled disassembler output 27950if @value{GDBN} is using its builtin disassembler library for styling 27951(@pxref{style_disassembler_enabled,,@kbd{set style disassembler 27952enabled}}). 27953 27954@item version 27955Control the styling of @value{GDBN}'s version number text. By 27956default, this style's foreground color is magenta and it has bold 27957intensity. The version number is displayed in two places, the output 27958of @command{show version}, and when @value{GDBN} starts up. 27959 27960In order to control how @value{GDBN} styles the version number at 27961startup, add the @code{set style version} family of commands to the 27962early initialization command file (@pxref{Initialization 27963Files}). 27964 27965@item title 27966Control the styling of titles. These are managed with the 27967@code{set style title} family of commands. By default, this style's 27968intensity is bold. Commands are using the title style to improve 27969the readability of large output. For example, the commands 27970@command{apropos} and @command{help} are using the title style 27971for the command names. 27972 27973@item highlight 27974Control the styling of highlightings. These are managed with the 27975@code{set style highlight} family of commands. By default, this style's 27976foreground color is red. Commands are using the highlight style to draw 27977the user attention to some specific parts of their output. For example, 27978the command @command{apropos -v REGEXP} uses the highlight style to 27979mark the documentation parts matching @var{regexp}. 27980 27981@item metadata 27982Control the styling of data annotations added by @value{GDBN} to data 27983it displays. By default, this style's intensity is dim. Metadata 27984annotations include the @samp{repeats @var{n} times} annotation for 27985suppressed display of repeated array elements (@pxref{Print Settings}), 27986@samp{<unavailable>} and @w{@samp{<error @var{descr}>}} annotations 27987for errors and @samp{<optimized-out>} annotations for optimized-out 27988values in displaying stack frame information in backtraces 27989(@pxref{Backtrace}), etc. 27990 27991@item tui-border 27992Control the styling of the TUI border. Note that, unlike other 27993styling options, only the color of the border can be controlled via 27994@code{set style}. This was done for compatibility reasons, as TUI 27995controls to set the border's intensity predated the addition of 27996general styling to @value{GDBN}. @xref{TUI Configuration}. 27997 27998@item tui-active-border 27999Control the styling of the active TUI border; that is, the TUI window 28000that has the focus. 28001 28002@item disassembler comment 28003Control the styling of comments in the disassembler output. These are 28004managed with the @code{set style disassembler comment} family of 28005commands. This style is only used when @value{GDBN} is styling using 28006its builtin disassembler library 28007(@pxref{style_disassembler_enabled,,@kbd{set style disassembler 28008enabled}}). By default, this style's intensity is dim, and its 28009foreground color is white. 28010 28011@item disassembler immediate 28012Control the styling of numeric operands in the disassembler output. 28013These are managed with the @code{set style disassembler immediate} 28014family of commands. This style is not used for instruction operands 28015that represent addresses, in that case the @samp{disassembler address} 28016style is used. This style is only used when @value{GDBN} is styling 28017using its builtin disassembler library. By default, this style's 28018foreground color is blue. 28019 28020@item disassembler address 28021Control the styling of address operands in the disassembler output. 28022This is an alias for the @samp{address} style. 28023 28024@item disassembler symbol 28025Control the styling of symbol names in the disassembler output. This 28026is an alias for the @samp{function} style. 28027 28028@item disassembler mnemonic 28029Control the styling of instruction mnemonics in the disassembler 28030output. These are managed with the @code{set style disassembler 28031mnemonic} family of commands. This style is also used for assembler 28032directives, e.g.@: @code{.byte}, @code{.word}, etc. This style is 28033only used when @value{GDBN} is styling using its builtin disassembler 28034library. By default, this style's foreground color is green. 28035 28036@item disassembler register 28037Control the styling of register operands in the disassembler output. 28038These are managed with the @code{set style disassembler register} 28039family of commands. This style is only used when @value{GDBN} is 28040styling using its builtin disassembler library. By default, this style's 28041foreground color is red. 28042 28043@end table 28044 28045@node Numbers 28046@section Numbers 28047@cindex number representation 28048@cindex entering numbers 28049 28050You can always enter numbers in octal, decimal, or hexadecimal in 28051@value{GDBN} by the usual conventions: octal numbers begin with 28052@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers 28053begin with @samp{0x}. Numbers that neither begin with @samp{0} or 28054@samp{0x}, nor end with a @samp{.} are, by default, entered in base 2805510; likewise, the default display for numbers---when no particular 28056format is specified---is base 10. You can change the default base for 28057both input and output with the commands described below. 28058 28059@table @code 28060@kindex set input-radix 28061@item set input-radix @var{base} 28062Set the default base for numeric input. Supported choices 28063for @var{base} are decimal 8, 10, or 16. The base must itself be 28064specified either unambiguously or using the current input radix; for 28065example, any of 28066 28067@smallexample 28068set input-radix 012 28069set input-radix 10. 28070set input-radix 0xa 28071@end smallexample 28072 28073@noindent 28074sets the input base to decimal. On the other hand, @samp{set input-radix 10} 28075leaves the input radix unchanged, no matter what it was, since 28076@samp{10}, being without any leading or trailing signs of its base, is 28077interpreted in the current radix. Thus, if the current radix is 16, 28078@samp{10} is interpreted in hex, i.e.@: as 16 decimal, which doesn't 28079change the radix. 28080 28081@kindex set output-radix 28082@item set output-radix @var{base} 28083Set the default base for numeric display. Supported choices 28084for @var{base} are decimal 8, 10, or 16. The base must itself be 28085specified either unambiguously or using the current input radix. 28086 28087@kindex show input-radix 28088@item show input-radix 28089Display the current default base for numeric input. 28090 28091@kindex show output-radix 28092@item show output-radix 28093Display the current default base for numeric display. 28094 28095@item set radix @r{[}@var{base}@r{]} 28096@itemx show radix 28097@kindex set radix 28098@kindex show radix 28099These commands set and show the default base for both input and output 28100of numbers. @code{set radix} sets the radix of input and output to 28101the same base; without an argument, it resets the radix back to its 28102default value of 10. 28103 28104@end table 28105 28106@node ABI 28107@section Configuring the Current ABI 28108 28109@value{GDBN} can determine the @dfn{ABI} (Application Binary Interface) of your 28110application automatically. However, sometimes you need to override its 28111conclusions. Use these commands to manage @value{GDBN}'s view of the 28112current ABI. 28113 28114@cindex OS ABI 28115@kindex set osabi 28116@kindex show osabi 28117@cindex Newlib OS ABI and its influence on the longjmp handling 28118 28119One @value{GDBN} configuration can debug binaries for multiple operating 28120system targets, either via remote debugging or native emulation. 28121@value{GDBN} will autodetect the @dfn{OS ABI} (Operating System ABI) in use, 28122but you can override its conclusion using the @code{set osabi} command. 28123One example where this is useful is in debugging of binaries which use 28124an alternate C library (e.g.@: @sc{uClibc} for @sc{gnu}/Linux) which does 28125not have the same identifying marks that the standard C library for your 28126platform provides. 28127 28128When @value{GDBN} is debugging the AArch64 architecture, it provides a 28129``Newlib'' OS ABI. This is useful for handling @code{setjmp} and 28130@code{longjmp} when debugging binaries that use the @sc{newlib} C library. 28131The ``Newlib'' OS ABI can be selected by @code{set osabi Newlib}. 28132 28133@table @code 28134@item show osabi 28135Show the OS ABI currently in use. 28136 28137@item set osabi 28138With no argument, show the list of registered available OS ABI's. 28139 28140@item set osabi @var{abi} 28141Set the current OS ABI to @var{abi}. 28142@end table 28143 28144@cindex float promotion 28145 28146Generally, the way that an argument of type @code{float} is passed to a 28147function depends on whether the function is prototyped. For a prototyped 28148(i.e.@: ANSI/ISO style) function, @code{float} arguments are passed unchanged, 28149according to the architecture's convention for @code{float}. For unprototyped 28150(i.e.@: K&R style) functions, @code{float} arguments are first promoted to type 28151@code{double} and then passed. 28152 28153Unfortunately, some forms of debug information do not reliably indicate whether 28154a function is prototyped. If @value{GDBN} calls a function that is not marked 28155as prototyped, it consults @kbd{set coerce-float-to-double}. 28156 28157@table @code 28158@kindex set coerce-float-to-double 28159@item set coerce-float-to-double 28160@itemx set coerce-float-to-double on 28161Arguments of type @code{float} will be promoted to @code{double} when passed 28162to an unprototyped function. This is the default setting. 28163 28164@item set coerce-float-to-double off 28165Arguments of type @code{float} will be passed directly to unprototyped 28166functions. 28167 28168@kindex show coerce-float-to-double 28169@item show coerce-float-to-double 28170Show the current setting of promoting @code{float} to @code{double}. 28171@end table 28172 28173@kindex set cp-abi 28174@kindex show cp-abi 28175@value{GDBN} needs to know the ABI used for your program's C@t{++} 28176objects. The correct C@t{++} ABI depends on which C@t{++} compiler was 28177used to build your application. @value{GDBN} only fully supports 28178programs with a single C@t{++} ABI; if your program contains code using 28179multiple C@t{++} ABI's or if @value{GDBN} can not identify your 28180program's ABI correctly, you can tell @value{GDBN} which ABI to use. 28181Currently supported ABI's include ``gnu-v2'', for @code{g++} versions 28182before 3.0, ``gnu-v3'', for @code{g++} versions 3.0 and later, and 28183``hpaCC'' for the HP ANSI C@t{++} compiler. Other C@t{++} compilers may 28184use the ``gnu-v2'' or ``gnu-v3'' ABI's as well. The default setting is 28185``auto''. 28186 28187@table @code 28188@item show cp-abi 28189Show the C@t{++} ABI currently in use. 28190 28191@item set cp-abi 28192With no argument, show the list of supported C@t{++} ABI's. 28193 28194@item set cp-abi @var{abi} 28195@itemx set cp-abi auto 28196Set the current C@t{++} ABI to @var{abi}, or return to automatic detection. 28197@end table 28198 28199@node Auto-loading 28200@section Automatically loading associated files 28201@cindex auto-loading 28202 28203@value{GDBN} sometimes reads files with commands and settings automatically, 28204without being explicitly told so by the user. We call this feature 28205@dfn{auto-loading}. While auto-loading is useful for automatically adapting 28206@value{GDBN} to the needs of your project, it can sometimes produce unexpected 28207results or introduce security risks (e.g., if the file comes from untrusted 28208sources). 28209 28210There are various kinds of files @value{GDBN} can automatically load. 28211In addition to these files, @value{GDBN} supports auto-loading code written 28212in various extension languages. @xref{Auto-loading extensions}. 28213 28214Note that loading of these associated files (including the local @file{.gdbinit} 28215file) requires accordingly configured @code{auto-load safe-path} 28216(@pxref{Auto-loading safe path}). 28217 28218For these reasons, @value{GDBN} includes commands and options to let you 28219control when to auto-load files and which files should be auto-loaded. 28220 28221@table @code 28222@anchor{set auto-load off} 28223@kindex set auto-load off 28224@item set auto-load off 28225Globally disable loading of all auto-loaded files. 28226You may want to use this command with the @samp{-iex} option 28227(@pxref{Option -init-eval-command}) such as: 28228@smallexample 28229$ @kbd{gdb -iex "set auto-load off" untrusted-executable corefile} 28230@end smallexample 28231 28232Be aware that system init file (@pxref{System-wide configuration}) 28233and init files from your home directory (@pxref{Home Directory Init File}) 28234still get read (as they come from generally trusted directories). 28235To prevent @value{GDBN} from auto-loading even those init files, use the 28236@option{-nx} option (@pxref{Mode Options}), in addition to 28237@code{set auto-load no}. 28238 28239@anchor{show auto-load} 28240@kindex show auto-load 28241@item show auto-load 28242Show whether auto-loading of each specific @samp{auto-load} file(s) is enabled 28243or disabled. 28244 28245@smallexample 28246(@value{GDBP}) show auto-load 28247gdb-scripts: Auto-loading of canned sequences of commands scripts is on. 28248libthread-db: Auto-loading of inferior specific libthread_db is on. 28249local-gdbinit: Auto-loading of .gdbinit script from current directory 28250 is on. 28251python-scripts: Auto-loading of Python scripts is on. 28252safe-path: List of directories from which it is safe to auto-load files 28253 is $debugdir:$datadir/auto-load. 28254scripts-directory: List of directories from which to load auto-loaded scripts 28255 is $debugdir:$datadir/auto-load. 28256@end smallexample 28257 28258@anchor{info auto-load} 28259@kindex info auto-load 28260@item info auto-load 28261Print whether each specific @samp{auto-load} file(s) have been auto-loaded or 28262not. 28263 28264@smallexample 28265(@value{GDBP}) info auto-load 28266gdb-scripts: 28267Loaded Script 28268Yes /home/user/gdb/gdb-gdb.gdb 28269libthread-db: No auto-loaded libthread-db. 28270local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been 28271 loaded. 28272python-scripts: 28273Loaded Script 28274Yes /home/user/gdb/gdb-gdb.py 28275@end smallexample 28276@end table 28277 28278These are @value{GDBN} control commands for the auto-loading: 28279 28280@multitable @columnfractions .5 .5 28281@item @xref{set auto-load off}. 28282@tab Disable auto-loading globally. 28283@item @xref{show auto-load}. 28284@tab Show setting of all kinds of files. 28285@item @xref{info auto-load}. 28286@tab Show state of all kinds of files. 28287@item @xref{set auto-load gdb-scripts}. 28288@tab Control for @value{GDBN} command scripts. 28289@item @xref{show auto-load gdb-scripts}. 28290@tab Show setting of @value{GDBN} command scripts. 28291@item @xref{info auto-load gdb-scripts}. 28292@tab Show state of @value{GDBN} command scripts. 28293@item @xref{set auto-load python-scripts}. 28294@tab Control for @value{GDBN} Python scripts. 28295@item @xref{show auto-load python-scripts}. 28296@tab Show setting of @value{GDBN} Python scripts. 28297@item @xref{info auto-load python-scripts}. 28298@tab Show state of @value{GDBN} Python scripts. 28299@item @xref{set auto-load guile-scripts}. 28300@tab Control for @value{GDBN} Guile scripts. 28301@item @xref{show auto-load guile-scripts}. 28302@tab Show setting of @value{GDBN} Guile scripts. 28303@item @xref{info auto-load guile-scripts}. 28304@tab Show state of @value{GDBN} Guile scripts. 28305@item @xref{set auto-load scripts-directory}. 28306@tab Control for @value{GDBN} auto-loaded scripts location. 28307@item @xref{show auto-load scripts-directory}. 28308@tab Show @value{GDBN} auto-loaded scripts location. 28309@item @xref{add-auto-load-scripts-directory}. 28310@tab Add directory for auto-loaded scripts location list. 28311@item @xref{set auto-load local-gdbinit}. 28312@tab Control for init file in the current directory. 28313@item @xref{show auto-load local-gdbinit}. 28314@tab Show setting of init file in the current directory. 28315@item @xref{info auto-load local-gdbinit}. 28316@tab Show state of init file in the current directory. 28317@item @xref{set auto-load libthread-db}. 28318@tab Control for thread debugging library. 28319@item @xref{show auto-load libthread-db}. 28320@tab Show setting of thread debugging library. 28321@item @xref{info auto-load libthread-db}. 28322@tab Show state of thread debugging library. 28323@item @xref{set auto-load safe-path}. 28324@tab Control directories trusted for automatic loading. 28325@item @xref{show auto-load safe-path}. 28326@tab Show directories trusted for automatic loading. 28327@item @xref{add-auto-load-safe-path}. 28328@tab Add directory trusted for automatic loading. 28329@end multitable 28330 28331@menu 28332* Init File in the Current Directory:: @samp{set/show/info auto-load local-gdbinit} 28333* libthread_db.so.1 file:: @samp{set/show/info auto-load libthread-db} 28334 28335* Auto-loading safe path:: @samp{set/show/info auto-load safe-path} 28336* Auto-loading verbose mode:: @samp{set/show debug auto-load} 28337@end menu 28338 28339@node Init File in the Current Directory 28340@subsection Automatically loading init file in the current directory 28341@cindex auto-loading init file in the current directory 28342 28343By default, @value{GDBN} reads and executes the canned sequences of commands 28344from init file (if any) in the current working directory, 28345see @ref{Init File in the Current Directory during Startup}. 28346 28347Note that loading of this local @file{.gdbinit} file also requires accordingly 28348configured @code{auto-load safe-path} (@pxref{Auto-loading safe path}). 28349 28350@table @code 28351@anchor{set auto-load local-gdbinit} 28352@kindex set auto-load local-gdbinit 28353@item set auto-load local-gdbinit [on|off] 28354Enable or disable the auto-loading of canned sequences of commands 28355(@pxref{Sequences}) found in init file in the current directory. 28356 28357@anchor{show auto-load local-gdbinit} 28358@kindex show auto-load local-gdbinit 28359@item show auto-load local-gdbinit 28360Show whether auto-loading of canned sequences of commands from init file in the 28361current directory is enabled or disabled. 28362 28363@anchor{info auto-load local-gdbinit} 28364@kindex info auto-load local-gdbinit 28365@item info auto-load local-gdbinit 28366Print whether canned sequences of commands from init file in the 28367current directory have been auto-loaded. 28368@end table 28369 28370@node libthread_db.so.1 file 28371@subsection Automatically loading thread debugging library 28372@cindex auto-loading libthread_db.so.1 28373 28374This feature is currently present only on @sc{gnu}/Linux native hosts. 28375 28376@value{GDBN} reads in some cases thread debugging library from places specific 28377to the inferior (@pxref{set libthread-db-search-path}). 28378 28379The special @samp{libthread-db-search-path} entry @samp{$sdir} is processed 28380without checking this @samp{set auto-load libthread-db} switch as system 28381libraries have to be trusted in general. In all other cases of 28382@samp{libthread-db-search-path} entries @value{GDBN} checks first if @samp{set 28383auto-load libthread-db} is enabled before trying to open such thread debugging 28384library. 28385 28386Note that loading of this debugging library also requires accordingly configured 28387@code{auto-load safe-path} (@pxref{Auto-loading safe path}). 28388 28389@table @code 28390@anchor{set auto-load libthread-db} 28391@kindex set auto-load libthread-db 28392@item set auto-load libthread-db [on|off] 28393Enable or disable the auto-loading of inferior specific thread debugging library. 28394 28395@anchor{show auto-load libthread-db} 28396@kindex show auto-load libthread-db 28397@item show auto-load libthread-db 28398Show whether auto-loading of inferior specific thread debugging library is 28399enabled or disabled. 28400 28401@anchor{info auto-load libthread-db} 28402@kindex info auto-load libthread-db 28403@item info auto-load libthread-db 28404Print the list of all loaded inferior specific thread debugging libraries and 28405for each such library print list of inferior @var{pid}s using it. 28406@end table 28407 28408@node Auto-loading safe path 28409@subsection Security restriction for auto-loading 28410@cindex auto-loading safe-path 28411 28412As the files of inferior can come from untrusted source (such as submitted by 28413an application user) @value{GDBN} does not always load any files automatically. 28414@value{GDBN} provides the @samp{set auto-load safe-path} setting to list 28415directories trusted for loading files not explicitly requested by user. 28416Each directory can also be a shell wildcard pattern. 28417 28418If the path is not set properly you will see a warning and the file will not 28419get loaded: 28420 28421@smallexample 28422$ ./gdb -q ./gdb 28423Reading symbols from /home/user/gdb/gdb... 28424warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been 28425 declined by your `auto-load safe-path' set 28426 to "$debugdir:$datadir/auto-load". 28427warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been 28428 declined by your `auto-load safe-path' set 28429 to "$debugdir:$datadir/auto-load". 28430@end smallexample 28431 28432@noindent 28433To instruct @value{GDBN} to go ahead and use the init files anyway, 28434invoke @value{GDBN} like this: 28435 28436@smallexample 28437$ gdb -q -iex "set auto-load safe-path /home/user/gdb" ./gdb 28438@end smallexample 28439 28440The list of trusted directories is controlled by the following commands: 28441 28442@table @code 28443@anchor{set auto-load safe-path} 28444@kindex set auto-load safe-path 28445@item set auto-load safe-path @r{[}@var{directories}@r{]} 28446Set the list of directories (and their subdirectories) trusted for automatic 28447loading and execution of scripts. You can also enter a specific trusted file. 28448Each directory can also be a shell wildcard pattern; wildcards do not match 28449directory separator - see @code{FNM_PATHNAME} for system function @code{fnmatch} 28450(@pxref{Wildcard Matching, fnmatch, , libc, GNU C Library Reference Manual}). 28451If you omit @var{directories}, @samp{auto-load safe-path} will be reset to 28452its default value as specified during @value{GDBN} compilation. 28453 28454The list of directories uses path separator (@samp{:} on GNU and Unix 28455systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly 28456to the @env{PATH} environment variable. 28457 28458@anchor{show auto-load safe-path} 28459@kindex show auto-load safe-path 28460@item show auto-load safe-path 28461Show the list of directories trusted for automatic loading and execution of 28462scripts. 28463 28464@anchor{add-auto-load-safe-path} 28465@kindex add-auto-load-safe-path 28466@item add-auto-load-safe-path 28467Add an entry (or list of entries) to the list of directories trusted for 28468automatic loading and execution of scripts. Multiple entries may be delimited 28469by the host platform path separator in use. 28470@end table 28471 28472This variable defaults to what @code{--with-auto-load-dir} has been configured 28473to (@pxref{with-auto-load-dir}). @file{$debugdir} and @file{$datadir} 28474substitution applies the same as for @ref{set auto-load scripts-directory}. 28475The default @code{set auto-load safe-path} value can be also overridden by 28476@value{GDBN} configuration option @option{--with-auto-load-safe-path}. 28477 28478Setting this variable to @file{/} disables this security protection, 28479corresponding @value{GDBN} configuration option is 28480@option{--without-auto-load-safe-path}. 28481This variable is supposed to be set to the system directories writable by the 28482system superuser only. Users can add their source directories in init files in 28483their home directories (@pxref{Home Directory Init File}). See also deprecated 28484init file in the current directory 28485(@pxref{Init File in the Current Directory during Startup}). 28486 28487To force @value{GDBN} to load the files it declined to load in the previous 28488example, you could use one of the following ways: 28489 28490@table @asis 28491@item @file{~/.gdbinit}: @samp{add-auto-load-safe-path ~/src/gdb} 28492Specify this trusted directory (or a file) as additional component of the list. 28493You have to specify also any existing directories displayed by 28494by @samp{show auto-load safe-path} (such as @samp{/usr:/bin} in this example). 28495 28496@item @kbd{gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" @dots{}} 28497Specify this directory as in the previous case but just for a single 28498@value{GDBN} session. 28499 28500@item @kbd{gdb -iex "set auto-load safe-path /" @dots{}} 28501Disable auto-loading safety for a single @value{GDBN} session. 28502This assumes all the files you debug during this @value{GDBN} session will come 28503from trusted sources. 28504 28505@item @kbd{./configure --without-auto-load-safe-path} 28506During compilation of @value{GDBN} you may disable any auto-loading safety. 28507This assumes all the files you will ever debug with this @value{GDBN} come from 28508trusted sources. 28509@end table 28510 28511On the other hand you can also explicitly forbid automatic files loading which 28512also suppresses any such warning messages: 28513 28514@table @asis 28515@item @kbd{gdb -iex "set auto-load no" @dots{}} 28516You can use @value{GDBN} command-line option for a single @value{GDBN} session. 28517 28518@item @file{~/.gdbinit}: @samp{set auto-load no} 28519Disable auto-loading globally for the user 28520(@pxref{Home Directory Init File}). While it is improbable, you could also 28521use system init file instead (@pxref{System-wide configuration}). 28522@end table 28523 28524This setting applies to the file names as entered by user. If no entry matches 28525@value{GDBN} tries as a last resort to also resolve all the file names into 28526their canonical form (typically resolving symbolic links) and compare the 28527entries again. @value{GDBN} already canonicalizes most of the filenames on its 28528own before starting the comparison so a canonical form of directories is 28529recommended to be entered. 28530 28531@node Auto-loading verbose mode 28532@subsection Displaying files tried for auto-load 28533@cindex auto-loading verbose mode 28534 28535For better visibility of all the file locations where you can place scripts to 28536be auto-loaded with inferior --- or to protect yourself against accidental 28537execution of untrusted scripts --- @value{GDBN} provides a feature for printing 28538all the files attempted to be loaded. Both existing and non-existing files may 28539be printed. 28540 28541For example the list of directories from which it is safe to auto-load files 28542(@pxref{Auto-loading safe path}) applies also to canonicalized filenames which 28543may not be too obvious while setting it up. 28544 28545@smallexample 28546(@value{GDBP}) set debug auto-load on 28547(@value{GDBP}) file ~/src/t/true 28548auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb" 28549 for objfile "/tmp/true". 28550auto-load: Updating directories of "/usr:/opt". 28551auto-load: Using directory "/usr". 28552auto-load: Using directory "/opt". 28553warning: File "/tmp/true-gdb.gdb" auto-loading has been declined 28554 by your `auto-load safe-path' set to "/usr:/opt". 28555@end smallexample 28556 28557@table @code 28558@anchor{set debug auto-load} 28559@kindex set debug auto-load 28560@item set debug auto-load [on|off] 28561Set whether to print the filenames attempted to be auto-loaded. 28562 28563@anchor{show debug auto-load} 28564@kindex show debug auto-load 28565@item show debug auto-load 28566Show whether printing of the filenames attempted to be auto-loaded is turned 28567on or off. 28568@end table 28569 28570@node Messages/Warnings 28571@section Optional Warnings and Messages 28572 28573@cindex verbose operation 28574@cindex optional warnings 28575By default, @value{GDBN} is silent about its inner workings. If you are 28576running on a slow machine, you may want to use the @code{set verbose} 28577command. This makes @value{GDBN} tell you when it does a lengthy 28578internal operation, so you will not think it has crashed. 28579 28580Currently, the messages controlled by @code{set verbose} are those 28581which announce that the symbol table for a source file is being read; 28582see @code{symbol-file} in @ref{Files, ,Commands to Specify Files}. 28583 28584@table @code 28585@kindex set verbose 28586@item set verbose on 28587Enables @value{GDBN} output of certain informational messages. 28588 28589@item set verbose off 28590Disables @value{GDBN} output of certain informational messages. 28591 28592@kindex show verbose 28593@item show verbose 28594Displays whether @code{set verbose} is on or off. 28595@end table 28596 28597By default, if @value{GDBN} encounters bugs in the symbol table of an 28598object file, it is silent; but if you are debugging a compiler, you may 28599find this information useful (@pxref{Symbol Errors, ,Errors Reading 28600Symbol Files}). 28601 28602@table @code 28603 28604@kindex set complaints 28605@item set complaints @var{limit} 28606Permits @value{GDBN} to output @var{limit} complaints about each type of 28607unusual symbols before becoming silent about the problem. Set 28608@var{limit} to zero to suppress all complaints; set it to a large number 28609to prevent complaints from being suppressed. 28610 28611@kindex show complaints 28612@item show complaints 28613Displays how many symbol complaints @value{GDBN} is permitted to produce. 28614 28615@end table 28616 28617@anchor{confirmation requests} 28618By default, @value{GDBN} is cautious, and asks what sometimes seems to be a 28619lot of stupid questions to confirm certain commands. For example, if 28620you try to run a program which is already running: 28621 28622@smallexample 28623(@value{GDBP}) run 28624The program being debugged has been started already. 28625Start it from the beginning? (y or n) 28626@end smallexample 28627 28628If you are willing to unflinchingly face the consequences of your own 28629commands, you can disable this ``feature'': 28630 28631@table @code 28632 28633@kindex set confirm 28634@cindex flinching 28635@cindex confirmation 28636@cindex stupid questions 28637@item set confirm off 28638Disables confirmation requests. Note that running @value{GDBN} with 28639the @option{--batch} option (@pxref{Mode Options, -batch}) also 28640automatically disables confirmation requests. 28641 28642@item set confirm on 28643Enables confirmation requests (the default). 28644 28645@kindex show confirm 28646@item show confirm 28647Displays state of confirmation requests. 28648 28649@end table 28650 28651@cindex command tracing 28652If you need to debug user-defined commands or sourced files you may find it 28653useful to enable @dfn{command tracing}. In this mode each command will be 28654printed as it is executed, prefixed with one or more @samp{+} symbols, the 28655quantity denoting the call depth of each command. 28656 28657@table @code 28658@kindex set trace-commands 28659@cindex command scripts, debugging 28660@item set trace-commands on 28661Enable command tracing. 28662@item set trace-commands off 28663Disable command tracing. 28664@item show trace-commands 28665Display the current state of command tracing. 28666@end table 28667 28668@node Debugging Output 28669@section Optional Messages about Internal Happenings 28670@cindex optional debugging messages 28671 28672@value{GDBN} has commands that enable optional debugging messages from 28673various @value{GDBN} subsystems; normally these commands are of 28674interest to @value{GDBN} maintainers, or when reporting a bug. This 28675section documents those commands. 28676 28677@table @code 28678@kindex set exec-done-display 28679@item set exec-done-display 28680Turns on or off the notification of asynchronous commands' 28681completion. When on, @value{GDBN} will print a message when an 28682asynchronous command finishes its execution. The default is off. 28683@kindex show exec-done-display 28684@item show exec-done-display 28685Displays the current setting of asynchronous command completion 28686notification. 28687 28688@kindex set debug 28689@cindex ARM AArch64 28690@item set debug aarch64 28691Turns on or off display of debugging messages related to ARM AArch64. 28692The default is off. 28693@kindex show debug 28694@item show debug aarch64 28695Displays the current state of displaying debugging messages related to 28696ARM AArch64. 28697 28698@cindex gdbarch debugging info 28699@cindex architecture debugging info 28700@item set debug arch 28701Turns on or off display of gdbarch debugging info. The default is off 28702@item show debug arch 28703Displays the current state of displaying gdbarch debugging info. 28704 28705@item set debug aix-thread 28706@cindex AIX threads 28707Display debugging messages about inner workings of the AIX thread 28708module. 28709@item show debug aix-thread 28710Show the current state of AIX thread debugging info display. 28711 28712@cindex AMD GPU debugging info 28713@anchor{set debug amd-dbgapi-lib} 28714@item set debug amd-dbgapi-lib 28715@itemx show debug amd-dbgapi-lib 28716 28717The @code{set debug amd-dbgapi-lib log-level @var{level}} command can be used 28718to enable diagnostic messages from the @samp{amd-dbgapi} library, where 28719@var{level} can be: 28720 28721@table @code 28722 28723@item off 28724no logging is enabled 28725 28726@item error 28727fatal errors are reported 28728 28729@item warning 28730fatal errors and warnings are reported 28731 28732@item info 28733fatal errors, warnings, and info messages are reported 28734 28735@item verbose 28736all messages are reported 28737 28738@end table 28739 28740The @code{show debug amd-dbgapi-lib log-level} command displays the current 28741@acronym{amd-dbgapi} library log level. 28742 28743@anchor{set debug amd-dbgapi} 28744@item set debug amd-dbgapi 28745@itemx show debug amd-dbgapi 28746 28747The @samp{set debug amd-dbgapi} command can be used 28748to enable diagnostic messages in the @samp{amd-dbgapi} target. The 28749@samp{show debug amd-dbgapi} command displays the current setting. 28750@xref{set debug amd-dbgapi}. 28751 28752@item set debug check-physname 28753@cindex physname 28754Check the results of the ``physname'' computation. When reading DWARF 28755debugging information for C@t{++}, @value{GDBN} attempts to compute 28756each entity's name. @value{GDBN} can do this computation in two 28757different ways, depending on exactly what information is present. 28758When enabled, this setting causes @value{GDBN} to compute the names 28759both ways and display any discrepancies. 28760@item show debug check-physname 28761Show the current state of ``physname'' checking. 28762 28763@item set debug coff-pe-read 28764@cindex COFF/PE exported symbols 28765Control display of debugging messages related to reading of COFF/PE 28766exported symbols. The default is off. 28767@item show debug coff-pe-read 28768Displays the current state of displaying debugging messages related to 28769reading of COFF/PE exported symbols. 28770 28771@item set debug dwarf-die 28772@cindex DWARF DIEs 28773Dump DWARF DIEs after they are read in. 28774The value is the number of nesting levels to print. 28775A value of zero turns off the display. 28776@item show debug dwarf-die 28777Show the current state of DWARF DIE debugging. 28778 28779@item set debug dwarf-line 28780@cindex DWARF Line Tables 28781Turns on or off display of debugging messages related to reading 28782DWARF line tables. The default is 0 (off). 28783A value of 1 provides basic information. 28784A value greater than 1 provides more verbose information. 28785@item show debug dwarf-line 28786Show the current state of DWARF line table debugging. 28787 28788@item set debug dwarf-read 28789@cindex DWARF Reading 28790Turns on or off display of debugging messages related to reading 28791DWARF debug info. The default is 0 (off). 28792A value of 1 provides basic information. 28793A value greater than 1 provides more verbose information. 28794@item show debug dwarf-read 28795Show the current state of DWARF reader debugging. 28796 28797@item set debug displaced 28798@cindex displaced stepping debugging info 28799Turns on or off display of @value{GDBN} debugging info for the 28800displaced stepping support. The default is off. 28801@item show debug displaced 28802Displays the current state of displaying @value{GDBN} debugging info 28803related to displaced stepping. 28804 28805@item set debug event 28806@cindex event debugging info 28807Turns on or off display of @value{GDBN} event debugging info. The 28808default is off. 28809@item show debug event 28810Displays the current state of displaying @value{GDBN} event debugging 28811info. 28812 28813@item set debug event-loop 28814@cindex event-loop debugging 28815Controls output of debugging info about the event loop. The possible 28816values are @samp{off}, @samp{all} (shows all debugging info) and 28817@samp{all-except-ui} (shows all debugging info except those about 28818UI-related events). 28819@item show debug event-loop 28820Shows the current state of displaying debugging info about the event 28821loop. 28822 28823@item set debug expression 28824@cindex expression debugging info 28825Turns on or off display of debugging info about @value{GDBN} 28826expression parsing. The default is off. 28827@item show debug expression 28828Displays the current state of displaying debugging info about 28829@value{GDBN} expression parsing. 28830 28831@item set debug fbsd-lwp 28832@cindex FreeBSD LWP debug messages 28833Turns on or off debugging messages from the FreeBSD LWP debug support. 28834@item show debug fbsd-lwp 28835Show the current state of FreeBSD LWP debugging messages. 28836 28837@item set debug fbsd-nat 28838@cindex FreeBSD native target debug messages 28839Turns on or off debugging messages from the FreeBSD native target. 28840@item show debug fbsd-nat 28841Show the current state of FreeBSD native target debugging messages. 28842 28843@item set debug fortran-array-slicing 28844@cindex fortran array slicing debugging info 28845Turns on or off display of @value{GDBN} Fortran array slicing 28846debugging info. The default is off. 28847 28848@item show debug fortran-array-slicing 28849Displays the current state of displaying @value{GDBN} Fortran array 28850slicing debugging info. 28851 28852@item set debug frame 28853@cindex frame debugging info 28854Turns on or off display of @value{GDBN} frame debugging info. The 28855default is off. 28856@item show debug frame 28857Displays the current state of displaying @value{GDBN} frame debugging 28858info. 28859 28860@item set debug gnu-nat 28861@cindex @sc{gnu}/Hurd debug messages 28862Turn on or off debugging messages from the @sc{gnu}/Hurd debug support. 28863@item show debug gnu-nat 28864Show the current state of @sc{gnu}/Hurd debugging messages. 28865 28866@item set debug infrun 28867@cindex inferior debugging info 28868Turns on or off display of @value{GDBN} debugging info for running the inferior. 28869The default is off. @file{infrun.c} contains GDB's runtime state machine used 28870for implementing operations such as single-stepping the inferior. 28871@item show debug infrun 28872Displays the current state of @value{GDBN} inferior debugging. 28873 28874@item set debug infcall 28875@cindex inferior function call debugging info 28876Turns on or off display of debugging info related to inferior function 28877calls made by @value{GDBN}. 28878@item show debug infcall 28879Displays the current state of @value{GDBN} inferior function call debugging. 28880 28881@item set debug jit 28882@cindex just-in-time compilation, debugging messages 28883Turn on or off debugging messages from JIT debug support. 28884@item show debug jit 28885Displays the current state of @value{GDBN} JIT debugging. 28886 28887@item set debug linux-nat @r{[}on@r{|}off@r{]} 28888@cindex @sc{gnu}/Linux native target debug messages 28889@cindex Linux native targets 28890Turn on or off debugging messages from the Linux native target debug support. 28891@item show debug linux-nat 28892Show the current state of Linux native target debugging messages. 28893 28894@item set debug linux-namespaces 28895@cindex @sc{gnu}/Linux namespaces debug messages 28896Turn on or off debugging messages from the Linux namespaces debug support. 28897@item show debug linux-namespaces 28898Show the current state of Linux namespaces debugging messages. 28899 28900@item set debug mach-o 28901@cindex Mach-O symbols processing 28902Control display of debugging messages related to Mach-O symbols 28903processing. The default is off. 28904@item show debug mach-o 28905Displays the current state of displaying debugging messages related to 28906reading of COFF/PE exported symbols. 28907 28908@item set debug notification 28909@cindex remote async notification debugging info 28910Turn on or off debugging messages about remote async notification. 28911The default is off. 28912@item show debug notification 28913Displays the current state of remote async notification debugging messages. 28914 28915@item set debug observer 28916@cindex observer debugging info 28917Turns on or off display of @value{GDBN} observer debugging. This 28918includes info such as the notification of observable events. 28919@item show debug observer 28920Displays the current state of observer debugging. 28921 28922@item set debug overload 28923@cindex C@t{++} overload debugging info 28924Turns on or off display of @value{GDBN} C@t{++} overload debugging 28925info. This includes info such as ranking of functions, etc. The default 28926is off. 28927@item show debug overload 28928Displays the current state of displaying @value{GDBN} C@t{++} overload 28929debugging info. 28930 28931@cindex expression parser, debugging info 28932@cindex debug expression parser 28933@item set debug parser 28934Turns on or off the display of expression parser debugging output. 28935Internally, this sets the @code{yydebug} variable in the expression 28936parser. @xref{Tracing, , Tracing Your Parser, bison, Bison}, for 28937details. The default is off. 28938@item show debug parser 28939Show the current state of expression parser debugging. 28940 28941@cindex packets, reporting on stdout 28942@cindex serial connections, debugging 28943@cindex debug remote protocol 28944@cindex remote protocol debugging 28945@cindex display remote packets 28946@item set debug remote 28947Turns on or off display of reports on all packets sent back and forth across 28948the serial line to the remote machine. The info is printed on the 28949@value{GDBN} standard output stream. The default is off. 28950@item show debug remote 28951Displays the state of display of remote packets. 28952 28953@item set debug remote-packet-max-chars 28954Sets the maximum number of characters to display for each remote packet when 28955@code{set debug remote} is on. This is useful to prevent @value{GDBN} from 28956displaying lengthy remote packets and polluting the console. 28957 28958The default value is @code{512}, which means @value{GDBN} will truncate each 28959remote packet after 512 bytes. 28960 28961Setting this option to @code{unlimited} will disable truncation and will output 28962the full length of the remote packets. 28963@item show debug remote-packet-max-chars 28964Displays the number of bytes to output for remote packet debugging. 28965 28966@item set debug separate-debug-file 28967Turns on or off display of debug output about separate debug file search. 28968@item show debug separate-debug-file 28969Displays the state of separate debug file search debug output. 28970 28971@item set debug serial 28972Turns on or off display of @value{GDBN} serial debugging info. The 28973default is off. 28974@item show debug serial 28975Displays the current state of displaying @value{GDBN} serial debugging 28976info. 28977 28978@item set debug solib 28979Turns on or off display of debugging messages related to shared libraries. 28980The default is off. 28981@item show debug solib 28982Show the current state of solib debugging messages. 28983 28984@item set debug symbol-lookup 28985@cindex symbol lookup 28986Turns on or off display of debugging messages related to symbol lookup. 28987The default is 0 (off). 28988A value of 1 provides basic information. 28989A value greater than 1 provides more verbose information. 28990@item show debug symbol-lookup 28991Show the current state of symbol lookup debugging messages. 28992 28993@item set debug symfile 28994@cindex symbol file functions 28995Turns on or off display of debugging messages related to symbol file functions. 28996The default is off. @xref{Files}. 28997@item show debug symfile 28998Show the current state of symbol file debugging messages. 28999 29000@item set debug symtab-create 29001@cindex symbol table creation 29002Turns on or off display of debugging messages related to symbol table creation. 29003The default is 0 (off). 29004A value of 1 provides basic information. 29005A value greater than 1 provides more verbose information. 29006@item show debug symtab-create 29007Show the current state of symbol table creation debugging. 29008 29009@item set debug target 29010@cindex target debugging info 29011Turns on or off display of @value{GDBN} target debugging info. This info 29012includes what is going on at the target level of GDB, as it happens. The 29013default is 0. Set it to 1 to track events, and to 2 to also track the 29014value of large memory transfers. 29015@item show debug target 29016Displays the current state of displaying @value{GDBN} target debugging 29017info. 29018 29019@item set debug timestamp 29020@cindex timestamping debugging info 29021Turns on or off display of timestamps with @value{GDBN} debugging info. 29022When enabled, seconds and microseconds are displayed before each debugging 29023message. 29024@item show debug timestamp 29025Displays the current state of displaying timestamps with @value{GDBN} 29026debugging info. 29027 29028@item set debug varobj 29029@cindex variable object debugging info 29030Turns on or off display of @value{GDBN} variable object debugging 29031info. The default is off. 29032@item show debug varobj 29033Displays the current state of displaying @value{GDBN} variable object 29034debugging info. 29035 29036@item set debug xml 29037@cindex XML parser debugging 29038Turn on or off debugging messages for built-in XML parsers. 29039@item show debug xml 29040Displays the current state of XML debugging messages. 29041 29042@item set debug breakpoints 29043@cindex breakpoint debugging info 29044Turns on or off display of @value{GDBN} debugging info for breakpoint insertion 29045and removal. The default is off. 29046@item show debug breakpoints 29047Displays the current state of displaying @value{GDBN} debugging info for 29048breakpoint insertion and removal. 29049@end table 29050 29051@node Other Misc Settings 29052@section Other Miscellaneous Settings 29053@cindex miscellaneous settings 29054 29055@table @code 29056@kindex set interactive-mode 29057@item set interactive-mode 29058If @code{on}, forces @value{GDBN} to assume that GDB was started 29059in a terminal. In practice, this means that @value{GDBN} should wait 29060for the user to answer queries generated by commands entered at 29061the command prompt. If @code{off}, forces @value{GDBN} to operate 29062in the opposite mode, and it uses the default answers to all queries. 29063If @code{auto} (the default), @value{GDBN} tries to determine whether 29064its standard input is a terminal, and works in interactive-mode if it 29065is, non-interactively otherwise. 29066 29067In the vast majority of cases, the debugger should be able to guess 29068correctly which mode should be used. But this setting can be useful 29069in certain specific cases, such as running a MinGW @value{GDBN} 29070inside a cygwin window. 29071 29072@kindex show interactive-mode 29073@item show interactive-mode 29074Displays whether the debugger is operating in interactive mode or not. 29075@end table 29076 29077@table @code 29078@kindex set suppress-cli-notifications 29079@item set suppress-cli-notifications 29080If @code{on}, command-line-interface (CLI) notifications that are 29081printed by @value{GDBN} are suppressed. If @code{off}, the 29082notifications are printed as usual. The default value is @code{off}. 29083CLI notifications occur when you change the selected context or when 29084the program being debugged stops, as detailed below. 29085 29086@table @emph 29087@item User-selected context changes: 29088When you change the selected context (i.e.@: the current inferior, 29089thread and/or the frame), @value{GDBN} prints information about the 29090new context. For example, the default behavior is below: 29091 29092@smallexample 29093(gdb) inferior 1 29094[Switching to inferior 1 [process 634] (/tmp/test)] 29095[Switching to thread 1 (process 634)] 29096#0 main () at test.c:3 290973 return 0; 29098(gdb) 29099@end smallexample 29100 29101When the notifications are suppressed, the new context is not printed: 29102 29103@smallexample 29104(gdb) set suppress-cli-notifications on 29105(gdb) inferior 1 29106(gdb) 29107@end smallexample 29108 29109@item The program being debugged stops: 29110When the program you are debugging stops (e.g.@: because of hitting a 29111breakpoint, completing source-stepping, an interrupt, etc.), 29112@value{GDBN} prints information about the stop event. For example, 29113below is a breakpoint hit: 29114 29115@smallexample 29116(gdb) break test.c:3 29117Breakpoint 2 at 0x555555555155: file test.c, line 3. 29118(gdb) continue 29119Continuing. 29120 29121Breakpoint 2, main () at test.c:3 291223 return 0; 29123(gdb) 29124@end smallexample 29125 29126When the notifications are suppressed, the output becomes: 29127 29128@smallexample 29129(gdb) break test.c:3 29130Breakpoint 2 at 0x555555555155: file test.c, line 3. 29131(gdb) set suppress-cli-notifications on 29132(gdb) continue 29133Continuing. 29134(gdb) 29135@end smallexample 29136 29137Suppressing CLI notifications may be useful in scripts to obtain a 29138reduced output from a list of commands. 29139@end table 29140 29141@kindex show suppress-cli-notifications 29142@item show suppress-cli-notifications 29143Displays whether printing CLI notifications is suppressed or not. 29144@end table 29145 29146@node Extending GDB 29147@chapter Extending @value{GDBN} 29148@cindex extending GDB 29149 29150@value{GDBN} provides several mechanisms for extension. 29151@value{GDBN} also provides the ability to automatically load 29152extensions when it reads a file for debugging. This allows the 29153user to automatically customize @value{GDBN} for the program 29154being debugged. 29155 29156To facilitate the use of extension languages, @value{GDBN} is capable 29157of evaluating the contents of a file. When doing so, @value{GDBN} 29158can recognize which extension language is being used by looking at 29159the filename extension. Files with an unrecognized filename extension 29160are always treated as a @value{GDBN} Command Files. 29161@xref{Command Files,, Command files}. 29162 29163You can control how @value{GDBN} evaluates these files with the following 29164setting: 29165 29166@table @code 29167@kindex set script-extension 29168@kindex show script-extension 29169@item set script-extension off 29170All scripts are always evaluated as @value{GDBN} Command Files. 29171 29172@item set script-extension soft 29173The debugger determines the scripting language based on filename 29174extension. If this scripting language is supported, @value{GDBN} 29175evaluates the script using that language. Otherwise, it evaluates 29176the file as a @value{GDBN} Command File. 29177 29178@item set script-extension strict 29179The debugger determines the scripting language based on filename 29180extension, and evaluates the script using that language. If the 29181language is not supported, then the evaluation fails. 29182 29183@item show script-extension 29184Display the current value of the @code{script-extension} option. 29185 29186@end table 29187 29188@ifset SYSTEM_GDBINIT_DIR 29189This setting is not used for files in the system-wide gdbinit directory. 29190Files in that directory must have an extension matching their language, 29191or have a @file{.gdb} extension to be interpreted as regular @value{GDBN} 29192commands. @xref{Startup}. 29193@end ifset 29194 29195@menu 29196* Sequences:: Canned Sequences of @value{GDBN} Commands 29197* Aliases:: Command Aliases 29198* Python:: Extending @value{GDBN} using Python 29199* Guile:: Extending @value{GDBN} using Guile 29200* Auto-loading extensions:: Automatically loading extensions 29201* Multiple Extension Languages:: Working with multiple extension languages 29202@end menu 29203 29204@node Sequences 29205@section Canned Sequences of Commands 29206 29207Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint 29208Command Lists}), @value{GDBN} provides two ways to store sequences of 29209commands for execution as a unit: user-defined commands and command 29210files. 29211 29212@menu 29213* Define:: How to define your own commands 29214* Hooks:: Hooks for user-defined commands 29215* Command Files:: How to write scripts of commands to be stored in a file 29216* Output:: Commands for controlled output 29217* Auto-loading sequences:: Controlling auto-loaded command files 29218@end menu 29219 29220@node Define 29221@subsection User-defined Commands 29222 29223@cindex user-defined command 29224@cindex arguments, to user-defined commands 29225A @dfn{user-defined command} is a sequence of @value{GDBN} commands to 29226which you assign a new name as a command. This is done with the 29227@code{define} command. User commands may accept an unlimited number of arguments 29228separated by whitespace. Arguments are accessed within the user command 29229via @code{$arg0@dots{}$argN}. A trivial example: 29230 29231@smallexample 29232define adder 29233 print $arg0 + $arg1 + $arg2 29234end 29235@end smallexample 29236 29237@noindent 29238To execute the command use: 29239 29240@smallexample 29241adder 1 2 3 29242@end smallexample 29243 29244@noindent 29245This defines the command @code{adder}, which prints the sum of 29246its three arguments. Note the arguments are text substitutions, so they may 29247reference variables, use complex expressions, or even perform inferior 29248functions calls. 29249 29250@cindex argument count in user-defined commands 29251@cindex how many arguments (user-defined commands) 29252In addition, @code{$argc} may be used to find out how many arguments have 29253been passed. 29254 29255@smallexample 29256define adder 29257 if $argc == 2 29258 print $arg0 + $arg1 29259 end 29260 if $argc == 3 29261 print $arg0 + $arg1 + $arg2 29262 end 29263end 29264@end smallexample 29265 29266Combining with the @code{eval} command (@pxref{eval}) makes it easier 29267to process a variable number of arguments: 29268 29269@smallexample 29270define adder 29271 set $i = 0 29272 set $sum = 0 29273 while $i < $argc 29274 eval "set $sum = $sum + $arg%d", $i 29275 set $i = $i + 1 29276 end 29277 print $sum 29278end 29279@end smallexample 29280 29281@table @code 29282 29283@kindex define 29284@item define @var{commandname} 29285Define a command named @var{commandname}. If there is already a command 29286by that name, you are asked to confirm that you want to redefine it. 29287The argument @var{commandname} may be a bare command name consisting of letters, 29288numbers, dashes, dots, and underscores. It may also start with any 29289predefined or user-defined prefix command. 29290For example, @samp{define target my-target} creates 29291a user-defined @samp{target my-target} command. 29292 29293The definition of the command is made up of other @value{GDBN} command lines, 29294which are given following the @code{define} command. The end of these 29295commands is marked by a line containing @code{end}. 29296 29297@kindex document 29298@kindex end@r{ (user-defined commands)} 29299@item document @var{commandname} 29300Document the user-defined command @var{commandname}, so that it can be 29301accessed by @code{help}. The command @var{commandname} must already be 29302defined. This command reads lines of documentation just as @code{define} 29303reads the lines of the command definition, ending with @code{end}. 29304After the @code{document} command is finished, @code{help} on command 29305@var{commandname} displays the documentation you have written. 29306 29307You may use the @code{document} command again to change the 29308documentation of a command. Redefining the command with @code{define} 29309does not change the documentation. 29310 29311It is also possible to document user-defined aliases. The alias documentation 29312will then be used by the @code{help} and @code{apropos} commands 29313instead of the documentation of the aliased command. 29314Documenting a user-defined alias is particularly useful when defining 29315an alias as a set of nested @code{with} commands 29316(@pxref{Command aliases default args}). 29317 29318@kindex define-prefix 29319@item define-prefix @var{commandname} 29320Define or mark the command @var{commandname} as a user-defined prefix 29321command. Once marked, @var{commandname} can be used as prefix command 29322by the @code{define} command. 29323Note that @code{define-prefix} can be used with a not yet defined 29324@var{commandname}. In such a case, @var{commandname} is defined as 29325an empty user-defined command. 29326In case you redefine a command that was marked as a user-defined 29327prefix command, the subcommands of the redefined command are kept 29328(and @value{GDBN} indicates so to the user). 29329 29330Example: 29331@example 29332(@value{GDBP}) define-prefix abc 29333(@value{GDBP}) define-prefix abc def 29334(@value{GDBP}) define abc def 29335Type commands for definition of "abc def". 29336End with a line saying just "end". 29337>echo command initial def\n 29338>end 29339(@value{GDBP}) define abc def ghi 29340Type commands for definition of "abc def ghi". 29341End with a line saying just "end". 29342>echo command ghi\n 29343>end 29344(@value{GDBP}) define abc def 29345Keeping subcommands of prefix command "def". 29346Redefine command "def"? (y or n) y 29347Type commands for definition of "abc def". 29348End with a line saying just "end". 29349>echo command def\n 29350>end 29351(@value{GDBP}) abc def ghi 29352command ghi 29353(@value{GDBP}) abc def 29354command def 29355(@value{GDBP}) 29356@end example 29357 29358@kindex dont-repeat 29359@cindex don't repeat command 29360@item dont-repeat 29361Used inside a user-defined command, this tells @value{GDBN} that this 29362command should not be repeated when the user hits @key{RET} 29363(@pxref{Command Syntax, repeat last command}). 29364 29365@kindex help user-defined 29366@item help user-defined 29367List all user-defined commands and all python commands defined in class 29368COMMAND_USER. The first line of the documentation or docstring is 29369included (if any). 29370 29371@kindex show user 29372@item show user 29373@itemx show user @var{commandname} 29374Display the @value{GDBN} commands used to define @var{commandname} (but 29375not its documentation). If no @var{commandname} is given, display the 29376definitions for all user-defined commands. 29377This does not work for user-defined python commands. 29378 29379@cindex infinite recursion in user-defined commands 29380@kindex show max-user-call-depth 29381@kindex set max-user-call-depth 29382@item show max-user-call-depth 29383@itemx set max-user-call-depth 29384The value of @code{max-user-call-depth} controls how many recursion 29385levels are allowed in user-defined commands before @value{GDBN} suspects an 29386infinite recursion and aborts the command. 29387This does not apply to user-defined python commands. 29388@end table 29389 29390In addition to the above commands, user-defined commands frequently 29391use control flow commands, described in @ref{Command Files}. 29392 29393When user-defined commands are executed, the 29394commands of the definition are not printed. An error in any command 29395stops execution of the user-defined command. 29396 29397If used interactively, commands that would ask for confirmation proceed 29398without asking when used inside a user-defined command. Many @value{GDBN} 29399commands that normally print messages to say what they are doing omit the 29400messages when used in a user-defined command. 29401 29402@node Hooks 29403@subsection User-defined Command Hooks 29404@cindex command hooks 29405@cindex hooks, for commands 29406@cindex hooks, pre-command 29407 29408@kindex hook 29409You may define @dfn{hooks}, which are a special kind of user-defined 29410command. Whenever you run the command @samp{foo}, if the user-defined 29411command @samp{hook-foo} exists, it is executed (with no arguments) 29412before that command. 29413 29414@cindex hooks, post-command 29415@kindex hookpost 29416A hook may also be defined which is run after the command you executed. 29417Whenever you run the command @samp{foo}, if the user-defined command 29418@samp{hookpost-foo} exists, it is executed (with no arguments) after 29419that command. Post-execution hooks may exist simultaneously with 29420pre-execution hooks, for the same command. 29421 29422It is valid for a hook to call the command which it hooks. If this 29423occurs, the hook is not re-executed, thereby avoiding infinite recursion. 29424 29425@c It would be nice if hookpost could be passed a parameter indicating 29426@c if the command it hooks executed properly or not. FIXME! 29427 29428@kindex stop@r{, a pseudo-command} 29429In addition, a pseudo-command, @samp{stop} exists. Defining 29430(@samp{hook-stop}) makes the associated commands execute every time 29431execution stops in your program: before breakpoint commands are run, 29432displays are printed, or the stack frame is printed. 29433 29434For example, to ignore @code{SIGALRM} signals while 29435single-stepping, but treat them normally during normal execution, 29436you could define: 29437 29438@smallexample 29439define hook-stop 29440handle SIGALRM nopass 29441end 29442 29443define hook-run 29444handle SIGALRM pass 29445end 29446 29447define hook-continue 29448handle SIGALRM pass 29449end 29450@end smallexample 29451 29452As a further example, to hook at the beginning and end of the @code{echo} 29453command, and to add extra text to the beginning and end of the message, 29454you could define: 29455 29456@smallexample 29457define hook-echo 29458echo <<<--- 29459end 29460 29461define hookpost-echo 29462echo --->>>\n 29463end 29464 29465(@value{GDBP}) echo Hello World 29466<<<---Hello World--->>> 29467(@value{GDBP}) 29468 29469@end smallexample 29470 29471You can define a hook for any single-word command in @value{GDBN}, but 29472not for command aliases; you should define a hook for the basic command 29473name, e.g.@: @code{backtrace} rather than @code{bt}. 29474@c FIXME! So how does Joe User discover whether a command is an alias 29475@c or not? 29476You can hook a multi-word command by adding @code{hook-} or 29477@code{hookpost-} to the last word of the command, e.g.@: 29478@samp{define target hook-remote} to add a hook to @samp{target remote}. 29479 29480If an error occurs during the execution of your hook, execution of 29481@value{GDBN} commands stops and @value{GDBN} issues a prompt 29482(before the command that you actually typed had a chance to run). 29483 29484If you try to define a hook which does not match any known command, you 29485get a warning from the @code{define} command. 29486 29487@node Command Files 29488@subsection Command Files 29489 29490@cindex command files 29491@cindex scripting commands 29492A command file for @value{GDBN} is a text file made of lines that are 29493@value{GDBN} commands. Comments (lines starting with @kbd{#}) may 29494also be included. An empty line in a command file does nothing; it 29495does not mean to repeat the last command, as it would from the 29496terminal. 29497 29498You can request the execution of a command file with the @code{source} 29499command. Note that the @code{source} command is also used to evaluate 29500scripts that are not Command Files. The exact behavior can be configured 29501using the @code{script-extension} setting. 29502@xref{Extending GDB,, Extending GDB}. 29503 29504@table @code 29505@kindex source 29506@cindex execute commands from a file 29507@item source [-s] [-v] @var{filename} 29508Execute the command file @var{filename}. 29509@end table 29510 29511The lines in a command file are generally executed sequentially, 29512unless the order of execution is changed by one of the 29513@emph{flow-control commands} described below. The commands are not 29514printed as they are executed. An error in any command terminates 29515execution of the command file and control is returned to the console. 29516 29517@value{GDBN} first searches for @var{filename} in the current directory. 29518If the file is not found there, and @var{filename} does not specify a 29519directory, then @value{GDBN} also looks for the file on the source search path 29520(specified with the @samp{directory} command); 29521except that @file{$cdir} is not searched because the compilation directory 29522is not relevant to scripts. 29523 29524If @code{-s} is specified, then @value{GDBN} searches for @var{filename} 29525on the search path even if @var{filename} specifies a directory. 29526The search is done by appending @var{filename} to each element of the 29527search path. So, for example, if @var{filename} is @file{mylib/myscript} 29528and the search path contains @file{/home/user} then @value{GDBN} will 29529look for the script @file{/home/user/mylib/myscript}. 29530The search is also done if @var{filename} is an absolute path. 29531For example, if @var{filename} is @file{/tmp/myscript} and 29532the search path contains @file{/home/user} then @value{GDBN} will 29533look for the script @file{/home/user/tmp/myscript}. 29534For DOS-like systems, if @var{filename} contains a drive specification, 29535it is stripped before concatenation. For example, if @var{filename} is 29536@file{d:myscript} and the search path contains @file{c:/tmp} then @value{GDBN} 29537will look for the script @file{c:/tmp/myscript}. 29538 29539If @code{-v}, for verbose mode, is given then @value{GDBN} displays 29540each command as it is executed. The option must be given before 29541@var{filename}, and is interpreted as part of the filename anywhere else. 29542 29543Commands that would ask for confirmation if used interactively proceed 29544without asking when used in a command file. Many @value{GDBN} commands that 29545normally print messages to say what they are doing omit the messages 29546when called from command files. 29547 29548@value{GDBN} also accepts command input from standard input. In this 29549mode, normal output goes to standard output and error output goes to 29550standard error. Errors in a command file supplied on standard input do 29551not terminate execution of the command file---execution continues with 29552the next command. 29553 29554@smallexample 29555gdb < cmds > log 2>&1 29556@end smallexample 29557 29558(The syntax above will vary depending on the shell used.) This example 29559will execute commands from the file @file{cmds}. All output and errors 29560would be directed to @file{log}. 29561 29562Since commands stored on command files tend to be more general than 29563commands typed interactively, they frequently need to deal with 29564complicated situations, such as different or unexpected values of 29565variables and symbols, changes in how the program being debugged is 29566built, etc. @value{GDBN} provides a set of flow-control commands to 29567deal with these complexities. Using these commands, you can write 29568complex scripts that loop over data structures, execute commands 29569conditionally, etc. 29570 29571@table @code 29572@kindex if 29573@kindex else 29574@item if 29575@itemx else 29576This command allows to include in your script conditionally executed 29577commands. The @code{if} command takes a single argument, which is an 29578expression to evaluate. It is followed by a series of commands that 29579are executed only if the expression is true (its value is nonzero). 29580There can then optionally be an @code{else} line, followed by a series 29581of commands that are only executed if the expression was false. The 29582end of the list is marked by a line containing @code{end}. 29583 29584@kindex while 29585@item while 29586This command allows to write loops. Its syntax is similar to 29587@code{if}: the command takes a single argument, which is an expression 29588to evaluate, and must be followed by the commands to execute, one per 29589line, terminated by an @code{end}. These commands are called the 29590@dfn{body} of the loop. The commands in the body of @code{while} are 29591executed repeatedly as long as the expression evaluates to true. 29592 29593@kindex loop_break 29594@item loop_break 29595This command exits the @code{while} loop in whose body it is included. 29596Execution of the script continues after that @code{while}s @code{end} 29597line. 29598 29599@kindex loop_continue 29600@item loop_continue 29601This command skips the execution of the rest of the body of commands 29602in the @code{while} loop in whose body it is included. Execution 29603branches to the beginning of the @code{while} loop, where it evaluates 29604the controlling expression. 29605 29606@kindex end@r{ (if/else/while commands)} 29607@item end 29608Terminate the block of commands that are the body of @code{if}, 29609@code{else}, or @code{while} flow-control commands. 29610@end table 29611 29612 29613@node Output 29614@subsection Commands for Controlled Output 29615 29616During the execution of a command file or a user-defined command, normal 29617@value{GDBN} output is suppressed; the only output that appears is what is 29618explicitly printed by the commands in the definition. This section 29619describes three commands useful for generating exactly the output you 29620want. 29621 29622@table @code 29623@kindex echo 29624@item echo @var{text} 29625@c I do not consider backslash-space a standard C escape sequence 29626@c because it is not in ANSI. 29627Print @var{text}. Nonprinting characters can be included in 29628@var{text} using C escape sequences, such as @samp{\n} to print a 29629newline. @strong{No newline is printed unless you specify one.} 29630In addition to the standard C escape sequences, a backslash followed 29631by a space stands for a space. This is useful for displaying a 29632string with spaces at the beginning or the end, since leading and 29633trailing spaces are otherwise trimmed from all arguments. 29634To print @samp{@w{ }and foo =@w{ }}, use the command 29635@samp{echo \@w{ }and foo = \@w{ }}. 29636 29637A backslash at the end of @var{text} can be used, as in C, to continue 29638the command onto subsequent lines. For example, 29639 29640@smallexample 29641echo This is some text\n\ 29642which is continued\n\ 29643onto several lines.\n 29644@end smallexample 29645 29646produces the same output as 29647 29648@smallexample 29649echo This is some text\n 29650echo which is continued\n 29651echo onto several lines.\n 29652@end smallexample 29653 29654@kindex output 29655@item output @var{expression} 29656Print the value of @var{expression} and nothing but that value: no 29657newlines, no @samp{$@var{nn} = }. The value is not entered in the 29658value history either. @xref{Expressions, ,Expressions}, for more information 29659on expressions. 29660 29661@item output/@var{fmt} @var{expression} 29662Print the value of @var{expression} in format @var{fmt}. You can use 29663the same formats as for @code{print}. @xref{Output Formats,,Output 29664Formats}, for more information. 29665 29666@kindex printf 29667@item printf @var{template}, @var{expressions}@dots{} 29668Print the values of one or more @var{expressions} under the control of 29669the string @var{template}. To print several values, make 29670@var{expressions} be a comma-separated list of individual expressions, 29671which may be either numbers or pointers. Their values are printed as 29672specified by @var{template}, exactly as a C program would do by 29673executing the code below: 29674 29675@smallexample 29676printf (@var{template}, @var{expressions}@dots{}); 29677@end smallexample 29678 29679As in @code{C} @code{printf}, ordinary characters in @var{template} 29680are printed verbatim, while @dfn{conversion specification} introduced 29681by the @samp{%} character cause subsequent @var{expressions} to be 29682evaluated, their values converted and formatted according to type and 29683style information encoded in the conversion specifications, and then 29684printed. 29685 29686For example, you can print two values in hex like this: 29687 29688@smallexample 29689printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo 29690@end smallexample 29691 29692@code{printf} supports all the standard @code{C} conversion 29693specifications, including the flags and modifiers between the @samp{%} 29694character and the conversion letter, with the following exceptions: 29695 29696@itemize @bullet 29697@item 29698The argument-ordering modifiers, such as @samp{2$}, are not supported. 29699 29700@item 29701The modifier @samp{*} is not supported for specifying precision or 29702width. 29703 29704@item 29705The @samp{'} flag (for separation of digits into groups according to 29706@code{LC_NUMERIC'}) is not supported. 29707 29708@item 29709The type modifiers @samp{hh}, @samp{j}, @samp{t}, and @samp{z} are not 29710supported. 29711 29712@item 29713The conversion letter @samp{n} (as in @samp{%n}) is not supported. 29714 29715@item 29716The conversion letters @samp{a} and @samp{A} are not supported. 29717@end itemize 29718 29719@noindent 29720Note that the @samp{ll} type modifier is supported only if the 29721underlying @code{C} implementation used to build @value{GDBN} supports 29722the @code{long long int} type, and the @samp{L} type modifier is 29723supported only if @code{long double} type is available. 29724 29725As in @code{C}, @code{printf} supports simple backslash-escape 29726sequences, such as @code{\n}, @samp{\t}, @samp{\\}, @samp{\"}, 29727@samp{\a}, and @samp{\f}, that consist of backslash followed by a 29728single character. Octal and hexadecimal escape sequences are not 29729supported. 29730 29731Additionally, @code{printf} supports conversion specifications for DFP 29732(@dfn{Decimal Floating Point}) types using the following length modifiers 29733together with a floating point specifier. 29734letters: 29735 29736@itemize @bullet 29737@item 29738@samp{H} for printing @code{Decimal32} types. 29739 29740@item 29741@samp{D} for printing @code{Decimal64} types. 29742 29743@item 29744@samp{DD} for printing @code{Decimal128} types. 29745@end itemize 29746 29747If the underlying @code{C} implementation used to build @value{GDBN} has 29748support for the three length modifiers for DFP types, other modifiers 29749such as width and precision will also be available for @value{GDBN} to use. 29750 29751In case there is no such @code{C} support, no additional modifiers will be 29752available and the value will be printed in the standard way. 29753 29754Here's an example of printing DFP types using the above conversion letters: 29755@smallexample 29756printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl 29757@end smallexample 29758 29759@anchor{%V Format Specifier} 29760Additionally, @code{printf} supports a special @samp{%V} output format. 29761This format prints the string representation of an expression just as 29762@value{GDBN} would produce with the standard @kbd{print} command 29763(@pxref{Data, ,Examining Data}): 29764 29765@smallexample 29766(@value{GDBP}) print array 29767$1 = @{0, 1, 2, 3, 4, 5@} 29768(@value{GDBP}) printf "Array is: %V\n", array 29769Array is: @{0, 1, 2, 3, 4, 5@} 29770@end smallexample 29771 29772It is possible to include print options with the @samp{%V} format by 29773placing them in @samp{[...]} immediately after the @samp{%V}, like 29774this: 29775 29776@smallexample 29777(@value{GDBP}) printf "Array is: %V[-array-indexes on]\n", array 29778Array is: @{[0] = 0, [1] = 1, [2] = 2, [3] = 3, [4] = 4, [5] = 5@} 29779@end smallexample 29780 29781If you need to print a literal @samp{[} directly after a @samp{%V}, then 29782just include an empty print options list: 29783 29784@smallexample 29785(@value{GDBP}) printf "Array is: %V[][Hello]\n", array 29786Array is: @{0, 1, 2, 3, 4, 5@}[Hello] 29787@end smallexample 29788 29789@anchor{eval} 29790@kindex eval 29791@item eval @var{template}, @var{expressions}@dots{} 29792Convert the values of one or more @var{expressions} under the control of 29793the string @var{template} to a command line, and call it. 29794 29795@end table 29796 29797@node Auto-loading sequences 29798@subsection Controlling auto-loading native @value{GDBN} scripts 29799@cindex native script auto-loading 29800 29801When a new object file is read (for example, due to the @code{file} 29802command, or because the inferior has loaded a shared library), 29803@value{GDBN} will look for the command file @file{@var{objfile}-gdb.gdb}. 29804@xref{Auto-loading extensions}. 29805 29806Auto-loading can be enabled or disabled, 29807and the list of auto-loaded scripts can be printed. 29808 29809@table @code 29810@anchor{set auto-load gdb-scripts} 29811@kindex set auto-load gdb-scripts 29812@item set auto-load gdb-scripts [on|off] 29813Enable or disable the auto-loading of canned sequences of commands scripts. 29814 29815@anchor{show auto-load gdb-scripts} 29816@kindex show auto-load gdb-scripts 29817@item show auto-load gdb-scripts 29818Show whether auto-loading of canned sequences of commands scripts is enabled or 29819disabled. 29820 29821@anchor{info auto-load gdb-scripts} 29822@kindex info auto-load gdb-scripts 29823@cindex print list of auto-loaded canned sequences of commands scripts 29824@item info auto-load gdb-scripts [@var{regexp}] 29825Print the list of all canned sequences of commands scripts that @value{GDBN} 29826auto-loaded. 29827@end table 29828 29829If @var{regexp} is supplied only canned sequences of commands scripts with 29830matching names are printed. 29831 29832@node Aliases 29833@section Command Aliases 29834@cindex aliases for commands 29835 29836Aliases allow you to define alternate spellings for existing commands. 29837For example, if a new @value{GDBN} command defined in Python 29838(@pxref{Python}) has a long name, it is handy to have an abbreviated 29839version of it that involves less typing. 29840 29841@value{GDBN} itself uses aliases. For example @samp{s} is an alias 29842of the @samp{step} command even though it is otherwise an ambiguous 29843abbreviation of other commands like @samp{set} and @samp{show}. 29844 29845Aliases are also used to provide shortened or more common versions 29846of multi-word commands. For example, @value{GDBN} provides the 29847@samp{tty} alias of the @samp{set inferior-tty} command. 29848 29849You can define a new alias with the @samp{alias} command. 29850 29851@table @code 29852 29853@kindex alias 29854@item alias [-a] [--] @var{alias} = @var{command} [@var{default-args}] 29855 29856@end table 29857 29858@var{alias} specifies the name of the new alias. Each word of 29859@var{alias} must consist of letters, numbers, dashes and underscores. 29860 29861@var{command} specifies the name of an existing command 29862that is being aliased. 29863 29864@var{command} can also be the name of an existing alias. In this 29865case, @var{command} cannot be an alias that has default arguments. 29866 29867The @samp{-a} option specifies that the new alias is an abbreviation 29868of the command. Abbreviations are not used in command completion. 29869 29870The @samp{--} option specifies the end of options, 29871and is useful when @var{alias} begins with a dash. 29872 29873You can specify @var{default-args} for your alias. These 29874@var{default-args} will be automatically added before the alias 29875arguments typed explicitly on the command line. 29876 29877For example, the below defines an alias @code{btfullall} that shows all local 29878variables and all frame arguments: 29879@smallexample 29880(@value{GDBP}) alias btfullall = backtrace -full -frame-arguments all 29881@end smallexample 29882 29883For more information about @var{default-args}, see @ref{Command 29884aliases default args, ,Default Arguments}. 29885 29886Here is a simple example showing how to make an abbreviation of a 29887command so that there is less to type. Suppose you were tired of 29888typing @samp{disas}, the current shortest unambiguous abbreviation of 29889the @samp{disassemble} command and you wanted an even shorter version 29890named @samp{di}. The following will accomplish this. 29891 29892@smallexample 29893(@value{GDBP}) alias -a di = disas 29894@end smallexample 29895 29896Note that aliases are different from user-defined commands. With a 29897user-defined command, you also need to write documentation for it with 29898the @samp{document} command. An alias automatically picks up the 29899documentation of the existing command. 29900 29901Here is an example where we make @samp{elms} an abbreviation of 29902@samp{elements} in the @samp{set print elements} command. 29903This is to show that you can make an abbreviation of any part 29904of a command. 29905 29906@smallexample 29907(@value{GDBP}) alias -a set print elms = set print elements 29908(@value{GDBP}) alias -a show print elms = show print elements 29909(@value{GDBP}) set p elms 200 29910(@value{GDBP}) show p elms 29911Limit on string chars or array elements to print is 200. 29912@end smallexample 29913 29914Note that if you are defining an alias of a @samp{set} command, 29915and you want to have an alias for the corresponding @samp{show} 29916command, then you need to define the latter separately. 29917 29918Unambiguously abbreviated commands are allowed in @var{command} and 29919@var{alias}, just as they are normally. 29920 29921@smallexample 29922(@value{GDBP}) alias -a set pr elms = set p ele 29923@end smallexample 29924 29925Finally, here is an example showing the creation of a one word 29926alias for a more complex command. 29927This creates alias @samp{spe} of the command @samp{set print elements}. 29928 29929@smallexample 29930(@value{GDBP}) alias spe = set print elements 29931(@value{GDBP}) spe 20 29932@end smallexample 29933 29934@menu 29935* Command aliases default args:: Default arguments for aliases 29936@end menu 29937 29938@node Command aliases default args 29939@subsection Default Arguments 29940@cindex aliases for commands, default arguments 29941 29942You can tell @value{GDBN} to always prepend some default arguments to 29943the list of arguments provided explicitly by the user when using a 29944user-defined alias. 29945 29946If you repeatedly use the same arguments or options for a command, you 29947can define an alias for this command and tell @value{GDBN} to 29948automatically prepend these arguments or options to the list of 29949arguments you type explicitly when using the alias@footnote{@value{GDBN} 29950could easily accept default arguments for pre-defined commands and aliases, 29951but it was deemed this would be confusing, and so is not allowed.}. 29952 29953For example, if you often use the command @code{thread apply all} 29954specifying to work on the threads in ascending order and to continue in case it 29955encounters an error, you can tell @value{GDBN} to automatically preprend 29956the @code{-ascending} and @code{-c} options by using: 29957 29958@smallexample 29959(@value{GDBP}) alias thread apply asc-all = thread apply all -ascending -c 29960@end smallexample 29961 29962Once you have defined this alias with its default args, any time you type 29963the @code{thread apply asc-all} followed by @code{some arguments}, 29964@value{GDBN} will execute @code{thread apply all -ascending -c some arguments}. 29965 29966To have even less to type, you can also define a one word alias: 29967@smallexample 29968(@value{GDBP}) alias t_a_c = thread apply all -ascending -c 29969@end smallexample 29970 29971As usual, unambiguous abbreviations can be used for @var{alias} 29972and @var{default-args}. 29973 29974The different aliases of a command do not share their default args. 29975For example, you define a new alias @code{bt_ALL} showing all possible 29976information and another alias @code{bt_SMALL} showing very limited information 29977using: 29978@smallexample 29979(@value{GDBP}) alias bt_ALL = backtrace -entry-values both -frame-arg all \ 29980 -past-main -past-entry -full 29981(@value{GDBP}) alias bt_SMALL = backtrace -entry-values no -frame-arg none \ 29982 -past-main off -past-entry off 29983@end smallexample 29984 29985(For more on using the @code{alias} command, see @ref{Aliases}.) 29986 29987Default args are not limited to the arguments and options of @var{command}, 29988but can specify nested commands if @var{command} accepts such a nested command 29989as argument. 29990For example, the below defines @code{faalocalsoftype} that lists the 29991frames having locals of a certain type, together with the matching 29992local vars: 29993@smallexample 29994(@value{GDBP}) alias faalocalsoftype = frame apply all info locals -q -t 29995(@value{GDBP}) faalocalsoftype int 29996#1 0x55554f5e in sleeper_or_burner (v=0xdf50) at sleepers.c:86 29997i = 0 29998ret = 21845 29999@end smallexample 30000 30001This is also very useful to define an alias for a set of nested @code{with} 30002commands to have a particular combination of temporary settings. For example, 30003the below defines the alias @code{pp10} that pretty prints an expression 30004argument, with a maximum of 10 elements if the expression is a string or 30005an array: 30006@smallexample 30007(@value{GDBP}) alias pp10 = with print pretty -- with print elements 10 -- print 30008@end smallexample 30009This defines the alias @code{pp10} as being a sequence of 3 commands. 30010The first part @code{with print pretty --} temporarily activates the setting 30011@code{set print pretty}, then launches the command that follows the separator 30012@code{--}. 30013The command following the first part is also a @code{with} command that 30014temporarily changes the setting @code{set print elements} to 10, then 30015launches the command that follows the second separator @code{--}. 30016The third part @code{print} is the command the @code{pp10} alias will launch, 30017using the temporary values of the settings and the arguments explicitly given 30018by the user. 30019For more information about the @code{with} command usage, 30020see @ref{Command Settings}. 30021 30022By default, asking the help for an alias shows the documentation of 30023the aliased command. When the alias is a set of nested commands, @code{help} 30024of an alias shows the documentation of the first command. This help 30025is not particularly useful for an alias such as @code{pp10}. 30026For such an alias, it is useful to give a specific documentation 30027using the @code{document} command (@pxref{Define, document}). 30028 30029 30030@c Python docs live in a separate file. 30031@include python.texi 30032 30033@c Guile docs live in a separate file. 30034@include guile.texi 30035 30036@node Auto-loading extensions 30037@section Auto-loading extensions 30038@cindex auto-loading extensions 30039 30040@value{GDBN} provides two mechanisms for automatically loading 30041extensions when a new object file is read (for example, due to the 30042@code{file} command, or because the inferior has loaded a shared 30043library): @file{@var{objfile}-gdb.@var{ext}} (@pxref{objfile-gdbdotext 30044file,,The @file{@var{objfile}-gdb.@var{ext}} file}) and the 30045@code{.debug_gdb_scripts} section of modern file formats like ELF 30046(@pxref{dotdebug_gdb_scripts section,,The @code{.debug_gdb_scripts} 30047section}). For a discussion of the differences between these two 30048approaches see @ref{Which flavor to choose?}. 30049 30050The auto-loading feature is useful for supplying application-specific 30051debugging commands and features. 30052 30053Auto-loading can be enabled or disabled, 30054and the list of auto-loaded scripts can be printed. 30055See the @samp{auto-loading} section of each extension language 30056for more information. 30057For @value{GDBN} command files see @ref{Auto-loading sequences}. 30058For Python files see @ref{Python Auto-loading}. 30059 30060Note that loading of this script file also requires accordingly configured 30061@code{auto-load safe-path} (@pxref{Auto-loading safe path}). 30062 30063@menu 30064* objfile-gdbdotext file:: The @file{@var{objfile}-gdb.@var{ext}} file 30065* dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section 30066* Which flavor to choose?:: Choosing between these approaches 30067@end menu 30068 30069@node objfile-gdbdotext file 30070@subsection The @file{@var{objfile}-gdb.@var{ext}} file 30071@cindex @file{@var{objfile}-gdb.gdb} 30072@cindex @file{@var{objfile}-gdb.py} 30073@cindex @file{@var{objfile}-gdb.scm} 30074 30075When a new object file is read, @value{GDBN} looks for a file named 30076@file{@var{objfile}-gdb.@var{ext}} (we call it @var{script-name} below), 30077where @var{objfile} is the object file's name and 30078where @var{ext} is the file extension for the extension language: 30079 30080@table @code 30081@item @file{@var{objfile}-gdb.gdb} 30082GDB's own command language 30083@item @file{@var{objfile}-gdb.py} 30084Python 30085@item @file{@var{objfile}-gdb.scm} 30086Guile 30087@end table 30088 30089@var{script-name} is formed by ensuring that the file name of @var{objfile} 30090is absolute, following all symlinks, and resolving @code{.} and @code{..} 30091components, and appending the @file{-gdb.@var{ext}} suffix. 30092If this file exists and is readable, @value{GDBN} will evaluate it as a 30093script in the specified extension language. 30094 30095If this file does not exist, then @value{GDBN} will look for 30096@var{script-name} file in all of the directories as specified below. 30097(On MS-Windows/MS-DOS, the drive letter of the executable's leading 30098directories is converted to a one-letter subdirectory, i.e.@: 30099@file{d:/usr/bin/} is converted to @file{/d/usr/bin/}, because Windows 30100filesystems disallow colons in file names.) 30101 30102Note that loading of these files requires an accordingly configured 30103@code{auto-load safe-path} (@pxref{Auto-loading safe path}). 30104 30105For object files using @file{.exe} suffix @value{GDBN} tries to load first the 30106scripts normally according to its @file{.exe} filename. But if no scripts are 30107found @value{GDBN} also tries script filenames matching the object file without 30108its @file{.exe} suffix. This @file{.exe} stripping is case insensitive and it 30109is attempted on any platform. This makes the script filenames compatible 30110between Unix and MS-Windows hosts. 30111 30112@table @code 30113@anchor{set auto-load scripts-directory} 30114@kindex set auto-load scripts-directory 30115@item set auto-load scripts-directory @r{[}@var{directories}@r{]} 30116Control @value{GDBN} auto-loaded scripts location. Multiple directory entries 30117may be delimited by the host platform path separator in use 30118(@samp{:} on Unix, @samp{;} on MS-Windows and MS-DOS). 30119 30120Each entry here needs to be covered also by the security setting 30121@code{set auto-load safe-path} (@pxref{set auto-load safe-path}). 30122 30123@anchor{with-auto-load-dir} 30124This variable defaults to @file{$debugdir:$datadir/auto-load}. The default 30125@code{set auto-load safe-path} value can be also overridden by @value{GDBN} 30126configuration option @option{--with-auto-load-dir}. 30127 30128Any reference to @file{$debugdir} will get replaced by 30129@var{debug-file-directory} value (@pxref{Separate Debug Files}) and any 30130reference to @file{$datadir} will get replaced by @var{data-directory} which is 30131determined at @value{GDBN} startup (@pxref{Data Files}). @file{$debugdir} and 30132@file{$datadir} must be placed as a directory component --- either alone or 30133delimited by @file{/} or @file{\} directory separators, depending on the host 30134platform. 30135 30136The list of directories uses path separator (@samp{:} on GNU and Unix 30137systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly 30138to the @env{PATH} environment variable. 30139 30140@anchor{show auto-load scripts-directory} 30141@kindex show auto-load scripts-directory 30142@item show auto-load scripts-directory 30143Show @value{GDBN} auto-loaded scripts location. 30144 30145@anchor{add-auto-load-scripts-directory} 30146@kindex add-auto-load-scripts-directory 30147@item add-auto-load-scripts-directory @r{[}@var{directories}@dots{}@r{]} 30148Add an entry (or list of entries) to the list of auto-loaded scripts locations. 30149Multiple entries may be delimited by the host platform path separator in use. 30150@end table 30151 30152@value{GDBN} does not track which files it has already auto-loaded this way. 30153@value{GDBN} will load the associated script every time the corresponding 30154@var{objfile} is opened. 30155So your @file{-gdb.@var{ext}} file should be careful to avoid errors if it 30156is evaluated more than once. 30157 30158@node dotdebug_gdb_scripts section 30159@subsection The @code{.debug_gdb_scripts} section 30160@cindex @code{.debug_gdb_scripts} section 30161 30162For systems using file formats like ELF and COFF, 30163when @value{GDBN} loads a new object file 30164it will look for a special section named @code{.debug_gdb_scripts}. 30165If this section exists, its contents is a list of null-terminated entries 30166specifying scripts to load. Each entry begins with a non-null prefix byte that 30167specifies the kind of entry, typically the extension language and whether the 30168script is in a file or inlined in @code{.debug_gdb_scripts}. 30169 30170The following entries are supported: 30171 30172@table @code 30173@item SECTION_SCRIPT_ID_PYTHON_FILE = 1 30174@item SECTION_SCRIPT_ID_SCHEME_FILE = 3 30175@item SECTION_SCRIPT_ID_PYTHON_TEXT = 4 30176@item SECTION_SCRIPT_ID_SCHEME_TEXT = 6 30177@end table 30178 30179@subsubsection Script File Entries 30180 30181If the entry specifies a file, @value{GDBN} will look for the file first 30182in the current directory and then along the source search path 30183(@pxref{Source Path, ,Specifying Source Directories}), 30184except that @file{$cdir} is not searched, since the compilation 30185directory is not relevant to scripts. 30186 30187File entries can be placed in section @code{.debug_gdb_scripts} with, 30188for example, this GCC macro for Python scripts. 30189 30190@example 30191/* Note: The "MS" section flags are to remove duplicates. */ 30192#define DEFINE_GDB_PY_SCRIPT(script_name) \ 30193 asm("\ 30194.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\ 30195.byte 1 /* Python */\n\ 30196.asciz \"" script_name "\"\n\ 30197.popsection \n\ 30198"); 30199@end example 30200 30201@noindent 30202For Guile scripts, replace @code{.byte 1} with @code{.byte 3}. 30203Then one can reference the macro in a header or source file like this: 30204 30205@example 30206DEFINE_GDB_PY_SCRIPT ("my-app-scripts.py") 30207@end example 30208 30209The script name may include directories if desired. 30210 30211Note that loading of this script file also requires accordingly configured 30212@code{auto-load safe-path} (@pxref{Auto-loading safe path}). 30213 30214If the macro invocation is put in a header, any application or library 30215using this header will get a reference to the specified script, 30216and with the use of @code{"MS"} attributes on the section, the linker 30217will remove duplicates. 30218 30219@subsubsection Script Text Entries 30220 30221Script text entries allow to put the executable script in the entry 30222itself instead of loading it from a file. 30223The first line of the entry, everything after the prefix byte and up to 30224the first newline (@code{0xa}) character, is the script name, and must not 30225contain any kind of space character, e.g., spaces or tabs. 30226The rest of the entry, up to the trailing null byte, is the script to 30227execute in the specified language. The name needs to be unique among 30228all script names, as @value{GDBN} executes each script only once based 30229on its name. 30230 30231Here is an example from file @file{py-section-script.c} in the @value{GDBN} 30232testsuite. 30233 30234@example 30235#include "symcat.h" 30236#include "gdb/section-scripts.h" 30237asm( 30238".pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n" 30239".byte " XSTRING (SECTION_SCRIPT_ID_PYTHON_TEXT) "\n" 30240".ascii \"gdb.inlined-script\\n\"\n" 30241".ascii \"class test_cmd (gdb.Command):\\n\"\n" 30242".ascii \" def __init__ (self):\\n\"\n" 30243".ascii \" super (test_cmd, self).__init__ (" 30244 "\\\"test-cmd\\\", gdb.COMMAND_OBSCURE)\\n\"\n" 30245".ascii \" def invoke (self, arg, from_tty):\\n\"\n" 30246".ascii \" print (\\\"test-cmd output, arg = %s\\\" % arg)\\n\"\n" 30247".ascii \"test_cmd ()\\n\"\n" 30248".byte 0\n" 30249".popsection\n" 30250); 30251@end example 30252 30253Loading of inlined scripts requires a properly configured 30254@code{auto-load safe-path} (@pxref{Auto-loading safe path}). 30255The path to specify in @code{auto-load safe-path} is the path of the file 30256containing the @code{.debug_gdb_scripts} section. 30257 30258@node Which flavor to choose? 30259@subsection Which flavor to choose? 30260 30261Given the multiple ways of auto-loading extensions, it might not always 30262be clear which one to choose. This section provides some guidance. 30263 30264@noindent 30265Benefits of the @file{-gdb.@var{ext}} way: 30266 30267@itemize @bullet 30268@item 30269Can be used with file formats that don't support multiple sections. 30270 30271@item 30272Ease of finding scripts for public libraries. 30273 30274Scripts specified in the @code{.debug_gdb_scripts} section are searched for 30275in the source search path. 30276For publicly installed libraries, e.g., @file{libstdc++}, there typically 30277isn't a source directory in which to find the script. 30278 30279@item 30280Doesn't require source code additions. 30281@end itemize 30282 30283@noindent 30284Benefits of the @code{.debug_gdb_scripts} way: 30285 30286@itemize @bullet 30287@item 30288Works with static linking. 30289 30290Scripts for libraries done the @file{-gdb.@var{ext}} way require an objfile to 30291trigger their loading. When an application is statically linked the only 30292objfile available is the executable, and it is cumbersome to attach all the 30293scripts from all the input libraries to the executable's 30294@file{-gdb.@var{ext}} script. 30295 30296@item 30297Works with classes that are entirely inlined. 30298 30299Some classes can be entirely inlined, and thus there may not be an associated 30300shared library to attach a @file{-gdb.@var{ext}} script to. 30301 30302@item 30303Scripts needn't be copied out of the source tree. 30304 30305In some circumstances, apps can be built out of large collections of internal 30306libraries, and the build infrastructure necessary to install the 30307@file{-gdb.@var{ext}} scripts in a place where @value{GDBN} can find them is 30308cumbersome. It may be easier to specify the scripts in the 30309@code{.debug_gdb_scripts} section as relative paths, and add a path to the 30310top of the source tree to the source search path. 30311@end itemize 30312 30313@node Multiple Extension Languages 30314@section Multiple Extension Languages 30315 30316The Guile and Python extension languages do not share any state, 30317and generally do not interfere with each other. 30318There are some things to be aware of, however. 30319 30320@subsection Python comes first 30321 30322Python was @value{GDBN}'s first extension language, and to avoid breaking 30323existing behaviour Python comes first. This is generally solved by the 30324``first one wins'' principle. @value{GDBN} maintains a list of enabled 30325extension languages, and when it makes a call to an extension language, 30326(say to pretty-print a value), it tries each in turn until an extension 30327language indicates it has performed the request (e.g., has returned the 30328pretty-printed form of a value). 30329This extends to errors while performing such requests: If an error happens 30330while, for example, trying to pretty-print an object then the error is 30331reported and any following extension languages are not tried. 30332 30333@node Interpreters 30334@chapter Command Interpreters 30335@cindex command interpreters 30336 30337@value{GDBN} supports multiple command interpreters, and some command 30338infrastructure to allow users or user interface writers to switch 30339between interpreters or run commands in other interpreters. 30340 30341@value{GDBN} currently supports two command interpreters, the console 30342interpreter (sometimes called the command-line interpreter or @sc{cli}) 30343and the machine interface interpreter (or @sc{gdb/mi}). This manual 30344describes both of these interfaces in great detail. 30345 30346By default, @value{GDBN} will start with the console interpreter. 30347However, the user may choose to start @value{GDBN} with another 30348interpreter by specifying the @option{-i} or @option{--interpreter} 30349startup options. Defined interpreters include: 30350 30351@table @code 30352@item console 30353@cindex console interpreter 30354The traditional console or command-line interpreter. This is the most often 30355used interpreter with @value{GDBN}. With no interpreter specified at runtime, 30356@value{GDBN} will use this interpreter. 30357 30358@item dap 30359@cindex DAP 30360@cindex Debugger Adapter Protocol 30361When @value{GDBN} has been built with Python support, it also supports 30362the Debugger Adapter Protocol. This protocol can be used by a 30363debugger GUI or an IDE to communicate with @value{GDBN}. This 30364protocol is documented at 30365@url{https://microsoft.github.io/debug-adapter-protocol/}. 30366@xref{Debugger Adapter Protocol}, for information about @value{GDBN} 30367extensions to the protocol. 30368 30369@item mi 30370@cindex mi interpreter 30371The newest @sc{gdb/mi} interface (currently @code{mi3}). Used primarily 30372by programs wishing to use @value{GDBN} as a backend for a debugger GUI 30373or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi} 30374Interface}. 30375 30376@item mi3 30377@cindex mi3 interpreter 30378The @sc{gdb/mi} interface introduced in @value{GDBN} 9.1. 30379 30380@item mi2 30381@cindex mi2 interpreter 30382The @sc{gdb/mi} interface introduced in @value{GDBN} 6.0. 30383 30384@end table 30385 30386@cindex invoke another interpreter 30387 30388@kindex interpreter-exec 30389You may execute commands in any interpreter from the current 30390interpreter using the appropriate command. If you are running the 30391console interpreter, simply use the @code{interpreter-exec} command: 30392 30393@smallexample 30394interpreter-exec mi "-data-list-register-names" 30395@end smallexample 30396 30397@sc{gdb/mi} has a similar command, although it is only available in versions of 30398@value{GDBN} which support @sc{gdb/mi} version 2 (or greater). 30399 30400Note that @code{interpreter-exec} only changes the interpreter for the 30401duration of the specified command. It does not change the interpreter 30402permanently. 30403 30404@cindex start a new independent interpreter 30405 30406Although you may only choose a single interpreter at startup, it is 30407possible to run an independent interpreter on a specified input/output 30408device (usually a tty). 30409 30410For example, consider a debugger GUI or IDE that wants to provide a 30411@value{GDBN} console view. It may do so by embedding a terminal 30412emulator widget in its GUI, starting @value{GDBN} in the traditional 30413command-line mode with stdin/stdout/stderr redirected to that 30414terminal, and then creating an MI interpreter running on a specified 30415input/output device. The console interpreter created by @value{GDBN} 30416at startup handles commands the user types in the terminal widget, 30417while the GUI controls and synchronizes state with @value{GDBN} using 30418the separate MI interpreter. 30419 30420To start a new secondary @dfn{user interface} running MI, use the 30421@code{new-ui} command: 30422 30423@kindex new-ui 30424@cindex new user interface 30425@smallexample 30426new-ui @var{interpreter} @var{tty} 30427@end smallexample 30428 30429The @var{interpreter} parameter specifies the interpreter to run. 30430This accepts the same values as the @code{interpreter-exec} command. 30431For example, @samp{console}, @samp{mi}, @samp{mi2}, etc. The 30432@var{tty} parameter specifies the name of the bidirectional file the 30433interpreter uses for input/output, usually the name of a 30434pseudoterminal slave on Unix systems. For example: 30435 30436@smallexample 30437(@value{GDBP}) new-ui mi /dev/pts/9 30438@end smallexample 30439 30440@noindent 30441runs an MI interpreter on @file{/dev/pts/9}. 30442 30443@node TUI 30444@chapter @value{GDBN} Text User Interface 30445@cindex TUI 30446@cindex Text User Interface 30447 30448The @value{GDBN} Text User Interface (TUI) is a terminal 30449interface which uses the @code{curses} library to show the source 30450file, the assembly output, the program registers and @value{GDBN} 30451commands in separate text windows. The TUI mode is supported only 30452on platforms where a suitable version of the @code{curses} library 30453is available. 30454 30455The TUI mode is enabled by default when you invoke @value{GDBN} as 30456@samp{@value{GDBP} -tui}. 30457You can also switch in and out of TUI mode while @value{GDBN} runs by 30458using various TUI commands and key bindings, such as @command{tui 30459enable} or @kbd{C-x C-a}. @xref{TUI Commands, ,TUI Commands}, and 30460@ref{TUI Keys, ,TUI Key Bindings}. 30461 30462@menu 30463* TUI Overview:: TUI overview 30464* TUI Keys:: TUI key bindings 30465* TUI Single Key Mode:: TUI single key mode 30466* TUI Mouse Support:: TUI mouse support 30467* TUI Commands:: TUI-specific commands 30468* TUI Configuration:: TUI configuration variables 30469@end menu 30470 30471@node TUI Overview 30472@section TUI Overview 30473 30474In TUI mode, @value{GDBN} can display several text windows: 30475 30476@table @emph 30477@item command 30478This window is the @value{GDBN} command window with the @value{GDBN} 30479prompt and the @value{GDBN} output. The @value{GDBN} input is still 30480managed using readline. 30481 30482@item source 30483The source window shows the source file of the program. The current 30484line and active breakpoints are displayed in this window. 30485 30486@item assembly 30487The assembly window shows the disassembly output of the program. 30488 30489@item register 30490This window shows the processor registers. Registers are highlighted 30491when their values change. 30492@end table 30493 30494The source and assembly windows show the current program position by 30495highlighting the current line and marking it with a @samp{>} marker. 30496By default, source and assembly code styling is disabled for the 30497highlighted text, but you can enable it with the @code{set style 30498tui-current-position on} command. @xref{Output Styling}. 30499 30500Breakpoints are indicated with two markers. The first marker 30501indicates the breakpoint type: 30502 30503@table @code 30504@item B 30505Breakpoint which was hit at least once. 30506 30507@item b 30508Breakpoint which was never hit. 30509 30510@item H 30511Hardware breakpoint which was hit at least once. 30512 30513@item h 30514Hardware breakpoint which was never hit. 30515@end table 30516 30517The second marker indicates whether the breakpoint is enabled or not: 30518 30519@table @code 30520@item + 30521Breakpoint is enabled. 30522 30523@item - 30524Breakpoint is disabled. 30525@end table 30526 30527The source, assembly and register windows are updated when the current 30528thread changes, when the frame changes, or when the program counter 30529changes. 30530 30531These windows are not all visible at the same time. The command 30532window is always visible. The others can be arranged in several 30533layouts: 30534 30535@itemize @bullet 30536@item 30537source only, 30538 30539@item 30540assembly only, 30541 30542@item 30543source and assembly, 30544 30545@item 30546source and registers, or 30547 30548@item 30549assembly and registers. 30550@end itemize 30551 30552These are the standard layouts, but other layouts can be defined. 30553 30554A status line above the command window shows the following information: 30555 30556@table @emph 30557@item target 30558Indicates the current @value{GDBN} target. 30559(@pxref{Targets, ,Specifying a Debugging Target}). 30560 30561@item process 30562Gives the current process or thread number. 30563When no process is being debugged, this field is set to @code{No process}. 30564 30565@item focus 30566Shows the name of the TUI window that has the focus. 30567 30568@item function 30569Gives the current function name for the selected frame. 30570The name is demangled if demangling is turned on (@pxref{Print Settings}). 30571When there is no symbol corresponding to the current program counter, 30572the string @code{??} is displayed. 30573 30574@item line 30575Indicates the current line number for the selected frame. 30576When the current line number is not known, the string @code{??} is displayed. 30577 30578@item pc 30579Indicates the current program counter address. 30580@end table 30581 30582@node TUI Keys 30583@section TUI Key Bindings 30584@cindex TUI key bindings 30585 30586The TUI installs several key bindings in the readline keymaps 30587@ifset SYSTEM_READLINE 30588(@pxref{Command Line Editing, , , rluserman, GNU Readline Library}). 30589@end ifset 30590@ifclear SYSTEM_READLINE 30591(@pxref{Command Line Editing}). 30592@end ifclear 30593The following key bindings are installed for both TUI mode and the 30594@value{GDBN} standard mode. 30595 30596@table @kbd 30597@kindex C-x C-a 30598@item C-x C-a 30599@kindex C-x a 30600@itemx C-x a 30601@kindex C-x A 30602@itemx C-x A 30603Enter or leave the TUI mode. When leaving the TUI mode, 30604the curses window management stops and @value{GDBN} operates using 30605its standard mode, writing on the terminal directly. When reentering 30606the TUI mode, control is given back to the curses windows. 30607The screen is then refreshed. 30608 30609This key binding uses the bindable Readline function 30610@code{tui-switch-mode}. 30611 30612@kindex C-x 1 30613@item C-x 1 30614Use a TUI layout with only one window. The layout will 30615either be @samp{source} or @samp{assembly}. When the TUI mode 30616is not active, it will switch to the TUI mode. 30617 30618Think of this key binding as the Emacs @kbd{C-x 1} binding. 30619 30620This key binding uses the bindable Readline function 30621@code{tui-delete-other-windows}. 30622 30623@kindex C-x 2 30624@item C-x 2 30625Use a TUI layout with at least two windows. When the current 30626layout already has two windows, the next layout with two windows is used. 30627When a new layout is chosen, one window will always be common to the 30628previous layout and the new one. 30629 30630Think of it as the Emacs @kbd{C-x 2} binding. 30631 30632This key binding uses the bindable Readline function 30633@code{tui-change-windows}. 30634 30635@kindex C-x o 30636@item C-x o 30637Change the active window. The TUI associates several key bindings 30638(like scrolling and arrow keys) with the active window. This command 30639gives the focus to the next TUI window. 30640 30641Think of it as the Emacs @kbd{C-x o} binding. 30642 30643This key binding uses the bindable Readline function 30644@code{tui-other-window}. 30645 30646@kindex C-x s 30647@item C-x s 30648Switch in and out of the TUI SingleKey mode that binds single 30649keys to @value{GDBN} commands (@pxref{TUI Single Key Mode}). 30650 30651This key binding uses the bindable Readline function 30652@code{next-keymap}. 30653@end table 30654 30655The following key bindings only work in the TUI mode: 30656 30657@table @asis 30658@kindex PgUp 30659@item @key{PgUp} 30660Scroll the active window one page up. 30661 30662@kindex PgDn 30663@item @key{PgDn} 30664Scroll the active window one page down. 30665 30666@kindex Up 30667@item @key{Up} 30668Scroll the active window one line up. 30669 30670@kindex Down 30671@item @key{Down} 30672Scroll the active window one line down. 30673 30674@kindex Left 30675@item @key{Left} 30676Scroll the active window one column left. 30677 30678@kindex Right 30679@item @key{Right} 30680Scroll the active window one column right. 30681 30682@kindex C-L 30683@item @kbd{C-L} 30684Refresh the screen. 30685@end table 30686 30687Because the arrow keys scroll the active window in the TUI mode, they 30688are not available for their normal use by readline unless the command 30689window has the focus. When another window is active, you must use 30690other readline key bindings such as @kbd{C-p}, @kbd{C-n}, @kbd{C-b} 30691and @kbd{C-f} to control the command window. 30692 30693@node TUI Single Key Mode 30694@section TUI Single Key Mode 30695@cindex TUI single key mode 30696 30697The TUI also provides a @dfn{SingleKey} mode, which binds several 30698frequently used @value{GDBN} commands to single keys. Type @kbd{C-x s} to 30699switch into this mode, where the following key bindings are used: 30700 30701@table @kbd 30702@kindex c @r{(SingleKey TUI key)} 30703@item c 30704continue 30705 30706@kindex C @r{(SingleKey TUI key)} 30707@item C 30708reverse-continue 30709 30710@kindex d @r{(SingleKey TUI key)} 30711@item d 30712down 30713 30714@kindex f @r{(SingleKey TUI key)} 30715@item f 30716finish 30717 30718@kindex F @r{(SingleKey TUI key)} 30719@item F 30720reverse-finish 30721 30722@kindex n @r{(SingleKey TUI key)} 30723@item n 30724next 30725 30726@kindex N @r{(SingleKey TUI key)} 30727@item N 30728reverse-next 30729 30730@kindex o @r{(SingleKey TUI key)} 30731@item o 30732nexti. The shortcut letter @samp{o} stands for ``step Over''. 30733 30734@kindex O @r{(SingleKey TUI key)} 30735@item O 30736reverse-nexti 30737 30738@kindex q @r{(SingleKey TUI key)} 30739@item q 30740exit the SingleKey mode. 30741 30742@kindex r @r{(SingleKey TUI key)} 30743@item r 30744run 30745 30746@kindex s @r{(SingleKey TUI key)} 30747@item s 30748step 30749 30750@kindex S @r{(SingleKey TUI key)} 30751@item S 30752reverse-step 30753 30754@kindex i @r{(SingleKey TUI key)} 30755@item i 30756stepi. The shortcut letter @samp{i} stands for ``step Into''. 30757 30758@kindex I @r{(SingleKey TUI key)} 30759@item I 30760reverse-stepi 30761 30762@kindex u @r{(SingleKey TUI key)} 30763@item u 30764up 30765 30766@kindex v @r{(SingleKey TUI key)} 30767@item v 30768info locals 30769 30770@kindex w @r{(SingleKey TUI key)} 30771@item w 30772where 30773@end table 30774 30775Other keys temporarily switch to the @value{GDBN} command prompt. 30776The key that was pressed is inserted in the editing buffer so that 30777it is possible to type most @value{GDBN} commands without interaction 30778with the TUI SingleKey mode. Once the command is entered the TUI 30779SingleKey mode is restored. The only way to permanently leave 30780this mode is by typing @kbd{q} or @kbd{C-x s}. 30781 30782@cindex SingleKey keymap name 30783If @value{GDBN} was built with Readline 8.0 or later, the TUI 30784SingleKey keymap will be named @samp{SingleKey}. This can be used in 30785@file{.inputrc} to add additional bindings to this keymap. 30786 30787@node TUI Mouse Support 30788@section TUI Mouse Support 30789@cindex TUI mouse support 30790 30791If the curses library supports the mouse, the TUI supports mouse 30792actions. 30793 30794The mouse wheel scrolls the appropriate window under the mouse cursor. 30795 30796The TUI itself does not directly support copying/pasting with the 30797mouse. However, on Unix terminals, you can typically press and hold 30798the @key{SHIFT} key on your keyboard to temporarily bypass 30799@value{GDBN}'s TUI and access the terminal's native mouse copy/paste 30800functionality (commonly, click-drag-release or double-click to select 30801text, middle-click to paste). This copy/paste works with the 30802terminal's selection buffer, as opposed to the TUI's buffer. Alternatively, to 30803disable mouse support in the TUI entirely and give the terminal control over 30804mouse clicks, turn off the @code{tui mouse-events} setting 30805(@pxref{tui-mouse-events,,set tui mouse-events}). 30806 30807Python extensions can react to mouse clicks 30808(@pxref{python-window-click,,Window.click}). 30809 30810@node TUI Commands 30811@section TUI-specific Commands 30812@cindex TUI commands 30813 30814The TUI has specific commands to control the text windows. 30815These commands are always available, even when @value{GDBN} is not in 30816the TUI mode. When @value{GDBN} is in the standard mode, most 30817of these commands will automatically switch to the TUI mode. 30818 30819Note that if @value{GDBN}'s @code{stdout} is not connected to a 30820terminal, or @value{GDBN} has been started with the machine interface 30821interpreter (@pxref{GDB/MI, ,The @sc{gdb/mi} Interface}), most of 30822these commands will fail with an error, because it would not be 30823possible or desirable to enable curses window management. 30824 30825@table @code 30826@item tui enable 30827@kindex tui enable 30828Activate TUI mode. The last active TUI window layout will be used if 30829TUI mode has previously been used in the current debugging session, 30830otherwise a default layout is used. 30831 30832@item tui disable 30833@kindex tui disable 30834Disable TUI mode, returning to the console interpreter. 30835 30836@anchor{info_win_command} 30837@item info win 30838@kindex info win 30839List the names and sizes of all currently displayed windows. 30840 30841@item tui new-layout @var{name} @var{window} @var{weight} @r{[}@var{window} @var{weight}@dots{}@r{]} 30842@kindex tui new-layout 30843Create a new TUI layout. The new layout will be named @var{name}, and 30844can be accessed using the @code{layout} command (see below). 30845 30846Each @var{window} parameter is either the name of a window to display, 30847or a window description. The windows will be displayed from top to 30848bottom in the order listed. 30849 30850The names of the windows are the same as the ones given to the 30851@code{focus} command (see below); additionally, the @code{status} 30852window can be specified. Note that, because it is of fixed height, 30853the weight assigned to the status window is of no importance. It is 30854conventional to use @samp{0} here. 30855 30856A window description looks a bit like an invocation of @code{tui 30857new-layout}, and is of the form 30858@{@r{[}@code{-horizontal}@r{]}@var{window} @var{weight} @r{[}@var{window} @var{weight}@dots{}@r{]}@}. 30859 30860This specifies a sub-layout. If @code{-horizontal} is given, the 30861windows in this description will be arranged side-by-side, rather than 30862top-to-bottom. 30863 30864Each @var{weight} is an integer. It is the weight of this window 30865relative to all the other windows in the layout. These numbers are 30866used to calculate how much of the screen is given to each window. 30867 30868For example: 30869 30870@example 30871(gdb) tui new-layout example src 1 regs 1 status 0 cmd 1 30872@end example 30873 30874Here, the new layout is called @samp{example}. It shows the source 30875and register windows, followed by the status window, and then finally 30876the command window. The non-status windows all have the same weight, 30877so the terminal will be split into three roughly equal sections. 30878 30879Here is a more complex example, showing a horizontal layout: 30880 30881@example 30882(gdb) tui new-layout example @{-horizontal src 1 asm 1@} 2 status 0 cmd 1 30883@end example 30884 30885This will result in side-by-side source and assembly windows; with the 30886status and command window being beneath these, filling the entire 30887width of the terminal. Because they have weight 2, the source and 30888assembly windows will be twice the height of the command window. 30889 30890@kindex tui layout 30891@kindex layout 30892@item tui layout @var{name} 30893@itemx layout @var{name} 30894Changes which TUI windows are displayed. The @var{name} parameter 30895controls which layout is shown. It can be either one of the built-in 30896layout names, or the name of a layout defined by the user using 30897@code{tui new-layout}. 30898 30899The built-in layouts are as follows: 30900 30901@table @code 30902@item next 30903Display the next layout. 30904 30905@item prev 30906Display the previous layout. 30907 30908@item src 30909Display the source and command windows. 30910 30911@item asm 30912Display the assembly and command windows. 30913 30914@item split 30915Display the source, assembly, and command windows. 30916 30917@item regs 30918When in @code{src} layout display the register, source, and command 30919windows. When in @code{asm} or @code{split} layout display the 30920register, assembler, and command windows. 30921@end table 30922 30923@kindex focus 30924@item tui focus @var{name} 30925@itemx focus @var{name} 30926Changes which TUI window is currently active for scrolling. The 30927@var{name} parameter can be any of the following: 30928 30929@table @code 30930@item next 30931Make the next window active for scrolling. 30932 30933@item prev 30934Make the previous window active for scrolling. 30935 30936@item src 30937Make the source window active for scrolling. 30938 30939@item asm 30940Make the assembly window active for scrolling. 30941 30942@item regs 30943Make the register window active for scrolling. 30944 30945@item cmd 30946Make the command window active for scrolling. 30947@end table 30948 30949@kindex tui refresh 30950@kindex refresh 30951@item tui refresh 30952@itemx refresh 30953Refresh the screen. This is similar to typing @kbd{C-L}. 30954 30955@item tui reg @var{group} 30956@kindex tui reg 30957Changes the register group displayed in the tui register window to 30958@var{group}. If the register window is not currently displayed this 30959command will cause the register window to be displayed. The list of 30960register groups, as well as their order is target specific. The 30961following groups are available on most targets: 30962@table @code 30963@item next 30964Repeatedly selecting this group will cause the display to cycle 30965through all of the available register groups. 30966 30967@item prev 30968Repeatedly selecting this group will cause the display to cycle 30969through all of the available register groups in the reverse order to 30970@var{next}. 30971 30972@item general 30973Display the general registers. 30974@item float 30975Display the floating point registers. 30976@item system 30977Display the system registers. 30978@item vector 30979Display the vector registers. 30980@item all 30981Display all registers. 30982@end table 30983 30984@item update 30985@kindex update 30986Update the source window and the current execution point. 30987 30988@kindex tui window height 30989@kindex winheight 30990@item tui window height @var{name} +@var{count} 30991@itemx tui window height @var{name} -@var{count} 30992@itemx winheight @var{name} +@var{count} 30993@itemx winheight @var{name} -@var{count} 30994Change the height of the window @var{name} by @var{count} lines. 30995Positive counts increase the height, while negative counts decrease 30996it. The @var{name} parameter can be the name of any currently visible 30997window. The names of the currently visible windows can be discovered 30998using @kbd{info win} (@pxref{info_win_command,,info win}). 30999 31000The set of currently visible windows must always fill the terminal, 31001and so, it is only possible to resize on window if there are other 31002visible windows that can either give or receive the extra terminal 31003space. 31004 31005@kindex tui window width 31006@kindex winwidth 31007@item tui window width @var{name} +@var{count} 31008@itemx tui window width @var{name} -@var{count} 31009@itemx winwidth @var{name} +@var{count} 31010@itemx winwidth @var{name} -@var{count} 31011Change the width of the window @var{name} by @var{count} columns. 31012Positive counts increase the width, while negative counts decrease it. 31013The @var{name} parameter can be the name of any currently visible 31014window. The names of the currently visible windows can be discovered 31015using @code{info win} (@pxref{info_win_command,,info win}). 31016 31017The set of currently visible windows must always fill the terminal, 31018and so, it is only possible to resize on window if there are other 31019visible windows that can either give or receive the extra terminal 31020space. 31021@end table 31022 31023@node TUI Configuration 31024@section TUI Configuration Variables 31025@cindex TUI configuration variables 31026 31027Several configuration variables control the appearance of TUI windows. 31028 31029@table @code 31030@item set tui border-kind @var{kind} 31031@kindex set tui border-kind 31032Select the border appearance for the source, assembly and register windows. 31033The possible values are the following: 31034@table @code 31035@item space 31036Use a space character to draw the border. 31037 31038@item ascii 31039Use @sc{ascii} characters @samp{+}, @samp{-} and @samp{|} to draw the border. 31040 31041@item acs 31042Use the Alternate Character Set to draw the border. The border is 31043drawn using character line graphics if the terminal supports them. 31044@end table 31045 31046@item set tui border-mode @var{mode} 31047@kindex set tui border-mode 31048@itemx set tui active-border-mode @var{mode} 31049@kindex set tui active-border-mode 31050Select the display attributes for the borders of the inactive windows 31051or the active window. The @var{mode} can be one of the following: 31052@table @code 31053@item normal 31054Use normal attributes to display the border. 31055 31056@item standout 31057Use standout mode. 31058 31059@item reverse 31060Use reverse video mode. 31061 31062@item half 31063Use half bright mode. 31064 31065@item half-standout 31066Use half bright and standout mode. 31067 31068@item bold 31069Use extra bright or bold mode. 31070 31071@item bold-standout 31072Use extra bright or bold and standout mode. 31073@end table 31074 31075@item set tui tab-width @var{nchars} 31076@kindex set tui tab-width 31077@kindex tabset 31078Set the width of tab stops to be @var{nchars} characters. This 31079setting affects the display of TAB characters in the source and 31080assembly windows. 31081 31082@item set tui compact-source @r{[}on@r{|}off@r{]} 31083@kindex set tui compact-source 31084Set whether the TUI source window is displayed in ``compact'' form. 31085The default display uses more space for line numbers; the compact 31086display uses only as much space as is needed for the line numbers in 31087the current file. 31088 31089@anchor{tui-mouse-events} 31090@item set tui mouse-events @r{[}on@r{|}off@r{]} 31091@kindex set tui mouse-events 31092When on (default), mouse clicks control the TUI (@pxref{TUI Mouse Support}). 31093When off, mouse clicks are handled by the terminal, enabling terminal-native 31094text selection. 31095 31096@kindex set debug tui 31097@item set debug tui @r{[}on|off@r{]} 31098Turn on or off display of @value{GDBN} internal debug messages relating 31099to the TUI. 31100 31101@kindex show debug tui 31102@item show debug tui 31103Show the current status of displaying @value{GDBN} internal debug 31104messages relating to the TUI. 31105 31106@end table 31107 31108Note that the colors of the TUI borders can be controlled using the 31109appropriate @code{set style} commands. @xref{Output Styling}. 31110 31111@node Emacs 31112@chapter Using @value{GDBN} under @sc{gnu} Emacs 31113 31114@cindex Emacs 31115@cindex @sc{gnu} Emacs 31116A special interface allows you to use @sc{gnu} Emacs to view (and 31117edit) the source files for the program you are debugging with 31118@value{GDBN}. 31119 31120To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the 31121executable file you want to debug as an argument. This command starts 31122@value{GDBN} as a subprocess of Emacs, with input and output through a newly 31123created Emacs buffer. 31124@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.) 31125 31126Running @value{GDBN} under Emacs can be just like running @value{GDBN} normally except for two 31127things: 31128 31129@itemize @bullet 31130@item 31131All ``terminal'' input and output goes through an Emacs buffer, called 31132the GUD buffer. 31133 31134This applies both to @value{GDBN} commands and their output, and to the input 31135and output done by the program you are debugging. 31136 31137This is useful because it means that you can copy the text of previous 31138commands and input them again; you can even use parts of the output 31139in this way. 31140 31141All the facilities of Emacs' Shell mode are available for interacting 31142with your program. In particular, you can send signals the usual 31143way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a 31144stop. 31145 31146@item 31147@value{GDBN} displays source code through Emacs. 31148 31149Each time @value{GDBN} displays a stack frame, Emacs automatically finds the 31150source file for that frame and puts an arrow (@samp{=>}) at the 31151left margin of the current line. Emacs uses a separate buffer for 31152source display, and splits the screen to show both your @value{GDBN} session 31153and the source. 31154 31155Explicit @value{GDBN} @code{list} or search commands still produce output as 31156usual, but you probably have no reason to use them from Emacs. 31157@end itemize 31158 31159We call this @dfn{text command mode}. Emacs 22.1, and later, also uses 31160a graphical mode, enabled by default, which provides further buffers 31161that can control the execution and describe the state of your program. 31162@xref{GDB Graphical Interface,,, Emacs, The @sc{gnu} Emacs Manual}. 31163 31164If you specify an absolute file name when prompted for the @kbd{M-x 31165gdb} argument, then Emacs sets your current working directory to where 31166your program resides. If you only specify the file name, then Emacs 31167sets your current working directory to the directory associated 31168with the previous buffer. In this case, @value{GDBN} may find your 31169program by searching your environment's @env{PATH} variable, but on 31170some operating systems it might not find the source. So, although the 31171@value{GDBN} input and output session proceeds normally, the auxiliary 31172buffer does not display the current source and line of execution. 31173 31174The initial working directory of @value{GDBN} is printed on the top 31175line of the GUD buffer and this serves as a default for the commands 31176that specify files for @value{GDBN} to operate on. @xref{Files, 31177,Commands to Specify Files}. 31178 31179By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you 31180need to call @value{GDBN} by a different name (for example, if you 31181keep several configurations around, with different names) you can 31182customize the Emacs variable @code{gud-gdb-command-name} to run the 31183one you want. 31184 31185In the GUD buffer, you can use these special Emacs commands in 31186addition to the standard Shell mode commands: 31187 31188@table @kbd 31189@item C-h m 31190Describe the features of Emacs' GUD Mode. 31191 31192@item C-c C-s 31193Execute to another source line, like the @value{GDBN} @code{step} command; also 31194update the display window to show the current file and location. 31195 31196@item C-c C-n 31197Execute to next source line in this function, skipping all function 31198calls, like the @value{GDBN} @code{next} command. Then update the display window 31199to show the current file and location. 31200 31201@item C-c C-i 31202Execute one instruction, like the @value{GDBN} @code{stepi} command; update 31203display window accordingly. 31204 31205@item C-c C-f 31206Execute until exit from the selected stack frame, like the @value{GDBN} 31207@code{finish} command. 31208 31209@item C-c C-r 31210Continue execution of your program, like the @value{GDBN} @code{continue} 31211command. 31212 31213@item C-c < 31214Go up the number of frames indicated by the numeric argument 31215(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}), 31216like the @value{GDBN} @code{up} command. 31217 31218@item C-c > 31219Go down the number of frames indicated by the numeric argument, like the 31220@value{GDBN} @code{down} command. 31221@end table 31222 31223In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break}) 31224tells @value{GDBN} to set a breakpoint on the source line point is on. 31225 31226In text command mode, if you type @kbd{M-x speedbar}, Emacs displays a 31227separate frame which shows a backtrace when the GUD buffer is current. 31228Move point to any frame in the stack and type @key{RET} to make it 31229become the current frame and display the associated source in the 31230source buffer. Alternatively, click @kbd{Mouse-2} to make the 31231selected frame become the current one. In graphical mode, the 31232speedbar displays watch expressions. 31233 31234If you accidentally delete the source-display buffer, an easy way to get 31235it back is to type the command @code{f} in the @value{GDBN} buffer, to 31236request a frame display; when you run under Emacs, this recreates 31237the source buffer if necessary to show you the context of the current 31238frame. 31239 31240The source files displayed in Emacs are in ordinary Emacs buffers 31241which are visiting the source files in the usual way. You can edit 31242the files with these buffers if you wish; but keep in mind that @value{GDBN} 31243communicates with Emacs in terms of line numbers. If you add or 31244delete lines from the text, the line numbers that @value{GDBN} knows cease 31245to correspond properly with the code. 31246 31247A more detailed description of Emacs' interaction with @value{GDBN} is 31248given in the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} 31249Emacs Manual}). 31250 31251@node GDB/MI 31252@chapter The @sc{gdb/mi} Interface 31253 31254@unnumberedsec Function and Purpose 31255 31256@cindex @sc{gdb/mi}, its purpose 31257@sc{gdb/mi} is a line based machine oriented text interface to 31258@value{GDBN} and is activated by specifying using the 31259@option{--interpreter} command line option (@pxref{Mode Options}). It 31260is specifically intended to support the development of systems which 31261use the debugger as just one small component of a larger system. 31262 31263This chapter is a specification of the @sc{gdb/mi} interface. It is written 31264in the form of a reference manual. 31265 31266Note that @sc{gdb/mi} is still under construction, so some of the 31267features described below are incomplete and subject to change 31268(@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}). 31269 31270@unnumberedsec Notation and Terminology 31271 31272@cindex notational conventions, for @sc{gdb/mi} 31273This chapter uses the following notation: 31274 31275@itemize @bullet 31276@item 31277@code{|} separates two alternatives. 31278 31279@item 31280@code{[ @var{something} ]} indicates that @var{something} is optional: 31281it may or may not be given. 31282 31283@item 31284@code{( @var{group} )*} means that @var{group} inside the parentheses 31285may repeat zero or more times. 31286 31287@item 31288@code{( @var{group} )+} means that @var{group} inside the parentheses 31289may repeat one or more times. 31290 31291@item 31292@code{( @var{group} )} means that @var{group} inside the parentheses 31293occurs exactly once. 31294 31295@item 31296@code{"@var{string}"} means a literal @var{string}. 31297@end itemize 31298 31299@ignore 31300@heading Dependencies 31301@end ignore 31302 31303@menu 31304* GDB/MI General Design:: 31305* GDB/MI Command Syntax:: 31306* GDB/MI Compatibility with CLI:: 31307* GDB/MI Development and Front Ends:: 31308* GDB/MI Output Records:: 31309* GDB/MI Simple Examples:: 31310* GDB/MI Command Description Format:: 31311* GDB/MI Breakpoint Commands:: 31312* GDB/MI Catchpoint Commands:: 31313* GDB/MI Program Context:: 31314* GDB/MI Thread Commands:: 31315* GDB/MI Ada Tasking Commands:: 31316* GDB/MI Program Execution:: 31317* GDB/MI Stack Manipulation:: 31318* GDB/MI Variable Objects:: 31319* GDB/MI Data Manipulation:: 31320* GDB/MI Tracepoint Commands:: 31321* GDB/MI Symbol Query:: 31322* GDB/MI File Commands:: 31323@ignore 31324* GDB/MI Kod Commands:: 31325* GDB/MI Memory Overlay Commands:: 31326* GDB/MI Signal Handling Commands:: 31327@end ignore 31328* GDB/MI Target Manipulation:: 31329* GDB/MI File Transfer Commands:: 31330* GDB/MI Ada Exceptions Commands:: 31331* GDB/MI Support Commands:: 31332* GDB/MI Miscellaneous Commands:: 31333@end menu 31334 31335@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 31336@node GDB/MI General Design 31337@section @sc{gdb/mi} General Design 31338@cindex GDB/MI General Design 31339 31340Interaction of a @sc{gdb/mi} frontend with @value{GDBN} involves three 31341parts---commands sent to @value{GDBN}, responses to those commands 31342and notifications. Each command results in exactly one response, 31343indicating either successful completion of the command, or an error. 31344For the commands that do not resume the target, the response contains the 31345requested information. For the commands that resume the target, the 31346response only indicates whether the target was successfully resumed. 31347Notifications is the mechanism for reporting changes in the state of the 31348target, or in @value{GDBN} state, that cannot conveniently be associated with 31349a command and reported as part of that command response. 31350 31351The important examples of notifications are: 31352@itemize @bullet 31353 31354@item 31355Exec notifications. These are used to report changes in 31356target state---when a target is resumed, or stopped. It would not 31357be feasible to include this information in response of resuming 31358commands, because one resume commands can result in multiple events in 31359different threads. Also, quite some time may pass before any event 31360happens in the target, while a frontend needs to know whether the resuming 31361command itself was successfully executed. 31362 31363@item 31364Console output, and status notifications. Console output 31365notifications are used to report output of CLI commands, as well as 31366diagnostics for other commands. Status notifications are used to 31367report the progress of a long-running operation. Naturally, including 31368this information in command response would mean no output is produced 31369until the command is finished, which is undesirable. 31370 31371@item 31372General notifications. Commands may have various side effects on 31373the @value{GDBN} or target state beyond their official purpose. For example, 31374a command may change the selected thread. Although such changes can 31375be included in command response, using notification allows for more 31376orthogonal frontend design. 31377 31378@end itemize 31379 31380There's no guarantee that whenever an MI command reports an error, 31381@value{GDBN} or the target are in any specific state, and especially, 31382the state is not reverted to the state before the MI command was 31383processed. Therefore, whenever an MI command results in an error, 31384we recommend that the frontend refreshes all the information shown in 31385the user interface. 31386 31387 31388@menu 31389* Context management:: 31390* Asynchronous and non-stop modes:: 31391* Thread groups:: 31392@end menu 31393 31394@node Context management 31395@subsection Context management 31396 31397@subsubsection Threads and Frames 31398 31399In most cases when @value{GDBN} accesses the target, this access is 31400done in context of a specific thread and frame (@pxref{Frames}). 31401Often, even when accessing global data, the target requires that a thread 31402be specified. The CLI interface maintains the selected thread and frame, 31403and supplies them to target on each command. This is convenient, 31404because a command line user would not want to specify that information 31405explicitly on each command, and because user interacts with 31406@value{GDBN} via a single terminal, so no confusion is possible as 31407to what thread and frame are the current ones. 31408 31409In the case of MI, the concept of selected thread and frame is less 31410useful. First, a frontend can easily remember this information 31411itself. Second, a graphical frontend can have more than one window, 31412each one used for debugging a different thread, and the frontend might 31413want to access additional threads for internal purposes. This 31414increases the risk that by relying on implicitly selected thread, the 31415frontend may be operating on a wrong one. Therefore, each MI command 31416should explicitly specify which thread and frame to operate on. To 31417make it possible, each MI command accepts the @samp{--thread} and 31418@samp{--frame} options, the value to each is @value{GDBN} global 31419identifier for thread and frame to operate on. 31420 31421Usually, each top-level window in a frontend allows the user to select 31422a thread and a frame, and remembers the user selection for further 31423operations. However, in some cases @value{GDBN} may suggest that the 31424current thread or frame be changed. For example, when stopping on a 31425breakpoint it is reasonable to switch to the thread where breakpoint is 31426hit. For another example, if the user issues the CLI @samp{thread} or 31427@samp{frame} commands via the frontend, it is desirable to change the 31428frontend's selection to the one specified by user. @value{GDBN} 31429communicates the suggestion to change current thread and frame using the 31430@samp{=thread-selected} notification. 31431 31432Note that historically, MI shares the selected thread with CLI, so 31433frontends used the @code{-thread-select} to execute commands in the 31434right context. However, getting this to work right is cumbersome. The 31435simplest way is for frontend to emit @code{-thread-select} command 31436before every command. This doubles the number of commands that need 31437to be sent. The alternative approach is to suppress @code{-thread-select} 31438if the selected thread in @value{GDBN} is supposed to be identical to the 31439thread the frontend wants to operate on. However, getting this 31440optimization right can be tricky. In particular, if the frontend 31441sends several commands to @value{GDBN}, and one of the commands changes the 31442selected thread, then the behaviour of subsequent commands will 31443change. So, a frontend should either wait for response from such 31444problematic commands, or explicitly add @code{-thread-select} for 31445all subsequent commands. No frontend is known to do this exactly 31446right, so it is suggested to just always pass the @samp{--thread} and 31447@samp{--frame} options. 31448 31449@subsubsection Language 31450 31451The execution of several commands depends on which language is selected. 31452By default, the current language (@pxref{show language}) is used. 31453But for commands known to be language-sensitive, it is recommended 31454to use the @samp{--language} option. This option takes one argument, 31455which is the name of the language to use while executing the command. 31456For instance: 31457 31458@smallexample 31459-data-evaluate-expression --language c "sizeof (void*)" 31460^done,value="4" 31461(gdb) 31462@end smallexample 31463 31464The valid language names are the same names accepted by the 31465@samp{set language} command (@pxref{Manually}), excluding @samp{auto}, 31466@samp{local} or @samp{unknown}. 31467 31468@node Asynchronous and non-stop modes 31469@subsection Asynchronous command execution and non-stop mode 31470 31471On some targets, @value{GDBN} is capable of processing MI commands 31472even while the target is running. This is called @dfn{asynchronous 31473command execution} (@pxref{Background Execution}). The frontend may 31474specify a preference for asynchronous execution using the 31475@code{-gdb-set mi-async 1} command, which should be emitted before 31476either running the executable or attaching to the target. After the 31477frontend has started the executable or attached to the target, it can 31478find if asynchronous execution is enabled using the 31479@code{-list-target-features} command. 31480 31481@table @code 31482@cindex foreground execution 31483@cindex background execution 31484@cindex asynchronous execution 31485@cindex execution, foreground, background and asynchronous 31486@kindex set mi-async 31487@item -gdb-set mi-async @r{[}on@r{|}off@r{]} 31488Set whether MI is in asynchronous mode. 31489 31490When @code{off}, which is the default, MI execution commands (e.g., 31491@code{-exec-continue}) are foreground commands, and @value{GDBN} waits 31492for the program to stop before processing further commands. 31493 31494When @code{on}, MI execution commands are background execution 31495commands (e.g., @code{-exec-continue} becomes the equivalent of the 31496@code{c&} CLI command), and so @value{GDBN} is capable of processing 31497MI commands even while the target is running. 31498 31499@kindex show mi-async 31500@item -gdb-show mi-async 31501Show whether MI asynchronous mode is enabled. 31502@end table 31503 31504Note: In @value{GDBN} version 7.7 and earlier, this option was called 31505@code{target-async} instead of @code{mi-async}, and it had the effect 31506of both putting MI in asynchronous mode and making CLI background 31507commands possible. CLI background commands are now always possible 31508``out of the box'' if the target supports them. The old spelling is 31509kept as a deprecated alias for backwards compatibility. 31510 31511Even if @value{GDBN} can accept a command while target is running, 31512many commands that access the target do not work when the target is 31513running. Therefore, asynchronous command execution is most useful 31514when combined with non-stop mode (@pxref{Non-Stop Mode}). Then, 31515it is possible to examine the state of one thread, while other threads 31516are running. 31517 31518When a given thread is running, MI commands that try to access the 31519target in the context of that thread may not work, or may work only on 31520some targets. In particular, commands that try to operate on thread's 31521stack will not work, on any target. Commands that read memory, or 31522modify breakpoints, may work or not work, depending on the target. Note 31523that even commands that operate on global state, such as @code{print}, 31524@code{set}, and breakpoint commands, still access the target in the 31525context of a specific thread, so frontend should try to find a 31526stopped thread and perform the operation on that thread (using the 31527@samp{--thread} option). 31528 31529Which commands will work in the context of a running thread is 31530highly target dependent. However, the two commands 31531@code{-exec-interrupt}, to stop a thread, and @code{-thread-info}, 31532to find the state of a thread, will always work. 31533 31534@node Thread groups 31535@subsection Thread groups 31536@value{GDBN} may be used to debug several processes at the same time. 31537On some platforms, @value{GDBN} may support debugging of several 31538hardware systems, each one having several cores with several different 31539processes running on each core. This section describes the MI 31540mechanism to support such debugging scenarios. 31541 31542The key observation is that regardless of the structure of the 31543target, MI can have a global list of threads, because most commands that 31544accept the @samp{--thread} option do not need to know what process that 31545thread belongs to. Therefore, it is not necessary to introduce 31546neither additional @samp{--process} option, nor an notion of the 31547current process in the MI interface. The only strictly new feature 31548that is required is the ability to find how the threads are grouped 31549into processes. 31550 31551To allow the user to discover such grouping, and to support arbitrary 31552hierarchy of machines/cores/processes, MI introduces the concept of a 31553@dfn{thread group}. Thread group is a collection of threads and other 31554thread groups. A thread group always has a string identifier, a type, 31555and may have additional attributes specific to the type. A new 31556command, @code{-list-thread-groups}, returns the list of top-level 31557thread groups, which correspond to processes that @value{GDBN} is 31558debugging at the moment. By passing an identifier of a thread group 31559to the @code{-list-thread-groups} command, it is possible to obtain 31560the members of specific thread group. 31561 31562To allow the user to easily discover processes, and other objects, he 31563wishes to debug, a concept of @dfn{available thread group} is 31564introduced. Available thread group is an thread group that 31565@value{GDBN} is not debugging, but that can be attached to, using the 31566@code{-target-attach} command. The list of available top-level thread 31567groups can be obtained using @samp{-list-thread-groups --available}. 31568In general, the content of a thread group may be only retrieved only 31569after attaching to that thread group. 31570 31571Thread groups are related to inferiors (@pxref{Inferiors Connections and 31572Programs}). Each inferior corresponds to a thread group of a special 31573type @samp{process}, and some additional operations are permitted on 31574such thread groups. 31575 31576@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 31577@node GDB/MI Command Syntax 31578@section @sc{gdb/mi} Command Syntax 31579 31580@menu 31581* GDB/MI Input Syntax:: 31582* GDB/MI Output Syntax:: 31583@end menu 31584 31585@node GDB/MI Input Syntax 31586@subsection @sc{gdb/mi} Input Syntax 31587 31588@cindex input syntax for @sc{gdb/mi} 31589@cindex @sc{gdb/mi}, input syntax 31590@table @code 31591@item @var{command} @expansion{} 31592@code{@var{cli-command} | @var{mi-command}} 31593 31594@item @var{cli-command} @expansion{} 31595@code{[ @var{token} ] @var{cli-command} @var{nl}}, where 31596@var{cli-command} is any existing @value{GDBN} CLI command. 31597 31598@item @var{mi-command} @expansion{} 31599@code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )* 31600@code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}} 31601 31602@item @var{token} @expansion{} 31603"any sequence of digits" 31604 31605@item @var{option} @expansion{} 31606@code{"-" @var{parameter} [ " " @var{parameter} ]} 31607 31608@item @var{parameter} @expansion{} 31609@code{@var{non-blank-sequence} | @var{c-string}} 31610 31611@item @var{operation} @expansion{} 31612@emph{any of the operations described in this chapter} 31613 31614@item @var{non-blank-sequence} @expansion{} 31615@emph{anything, provided it doesn't contain special characters such as 31616"-", @var{nl}, """ and of course " "} 31617 31618@item @var{c-string} @expansion{} 31619@code{""" @var{seven-bit-iso-c-string-content} """} 31620 31621@item @var{nl} @expansion{} 31622@code{CR | CR-LF} 31623@end table 31624 31625@noindent 31626Notes: 31627 31628@itemize @bullet 31629@item 31630The CLI commands are still handled by the @sc{mi} interpreter; their 31631output is described below. 31632 31633@item 31634The @code{@var{token}}, when present, is passed back when the command 31635finishes. 31636 31637@item 31638Some @sc{mi} commands accept optional arguments as part of the parameter 31639list. Each option is identified by a leading @samp{-} (dash) and may be 31640followed by an optional argument parameter. Options occur first in the 31641parameter list and can be delimited from normal parameters using 31642@samp{--} (this is useful when some parameters begin with a dash). 31643@end itemize 31644 31645Pragmatics: 31646 31647@itemize @bullet 31648@item 31649We want easy access to the existing CLI syntax (for debugging). 31650 31651@item 31652We want it to be easy to spot a @sc{mi} operation. 31653@end itemize 31654 31655@node GDB/MI Output Syntax 31656@subsection @sc{gdb/mi} Output Syntax 31657 31658@cindex output syntax of @sc{gdb/mi} 31659@cindex @sc{gdb/mi}, output syntax 31660The output from @sc{gdb/mi} consists of zero or more out-of-band records 31661followed, optionally, by a single result record. This result record 31662is for the most recent command. The sequence of output records is 31663terminated by @samp{(gdb)}. 31664 31665If an input command was prefixed with a @code{@var{token}} then the 31666corresponding output for that command will also be prefixed by that same 31667@var{token}. 31668 31669@table @code 31670@item @var{output} @expansion{} 31671@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}} 31672 31673@item @var{result-record} @expansion{} 31674@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}} 31675 31676@item @var{out-of-band-record} @expansion{} 31677@code{@var{async-record} | @var{stream-record}} 31678 31679@item @var{async-record} @expansion{} 31680@code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}} 31681 31682@item @var{exec-async-output} @expansion{} 31683@code{[ @var{token} ] "*" @var{async-output nl}} 31684 31685@item @var{status-async-output} @expansion{} 31686@code{[ @var{token} ] "+" @var{async-output nl}} 31687 31688@item @var{notify-async-output} @expansion{} 31689@code{[ @var{token} ] "=" @var{async-output nl}} 31690 31691@item @var{async-output} @expansion{} 31692@code{@var{async-class} ( "," @var{result} )*} 31693 31694@item @var{result-class} @expansion{} 31695@code{"done" | "running" | "connected" | "error" | "exit"} 31696 31697@item @var{async-class} @expansion{} 31698@code{"stopped" | @var{others}} (where @var{others} will be added 31699depending on the needs---this is still in development). 31700 31701@item @var{result} @expansion{} 31702@code{ @var{variable} "=" @var{value}} 31703 31704@item @var{variable} @expansion{} 31705@code{ @var{string} } 31706 31707@item @var{value} @expansion{} 31708@code{ @var{const} | @var{tuple} | @var{list} } 31709 31710@item @var{const} @expansion{} 31711@code{@var{c-string}} 31712 31713@item @var{tuple} @expansion{} 31714@code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" } 31715 31716@item @var{list} @expansion{} 31717@code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "[" 31718@var{result} ( "," @var{result} )* "]" } 31719 31720@item @var{stream-record} @expansion{} 31721@code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}} 31722 31723@item @var{console-stream-output} @expansion{} 31724@code{"~" @var{c-string nl}} 31725 31726@item @var{target-stream-output} @expansion{} 31727@code{"@@" @var{c-string nl}} 31728 31729@item @var{log-stream-output} @expansion{} 31730@code{"&" @var{c-string nl}} 31731 31732@item @var{nl} @expansion{} 31733@code{CR | CR-LF} 31734 31735@item @var{token} @expansion{} 31736@emph{any sequence of digits}. 31737@end table 31738 31739@noindent 31740Notes: 31741 31742@itemize @bullet 31743@item 31744All output sequences end in a single line containing a period. 31745 31746@item 31747The @code{@var{token}} is from the corresponding request. Note that 31748for all async output, while the token is allowed by the grammar and 31749may be output by future versions of @value{GDBN} for select async 31750output messages, it is generally omitted. Frontends should treat 31751all async output as reporting general changes in the state of the 31752target and there should be no need to associate async output to any 31753prior command. 31754 31755@item 31756@cindex status output in @sc{gdb/mi} 31757@var{status-async-output} contains on-going status information about the 31758progress of a slow operation. It can be discarded. All status output is 31759prefixed by @samp{+}. 31760 31761@item 31762@cindex async output in @sc{gdb/mi} 31763@var{exec-async-output} contains asynchronous state change on the target 31764(stopped, started, disappeared). All async output is prefixed by 31765@samp{*}. 31766 31767@item 31768@cindex notify output in @sc{gdb/mi} 31769@var{notify-async-output} contains supplementary information that the 31770client should handle (e.g., a new breakpoint information). All notify 31771output is prefixed by @samp{=}. 31772 31773@item 31774@cindex console output in @sc{gdb/mi} 31775@var{console-stream-output} is output that should be displayed as is in the 31776console. It is the textual response to a CLI command. All the console 31777output is prefixed by @samp{~}. 31778 31779@item 31780@cindex target output in @sc{gdb/mi} 31781@var{target-stream-output} is the output produced by the target program. 31782All the target output is prefixed by @samp{@@}. 31783 31784@item 31785@cindex log output in @sc{gdb/mi} 31786@var{log-stream-output} is output text coming from @value{GDBN}'s internals, for 31787instance messages that should be displayed as part of an error log. All 31788the log output is prefixed by @samp{&}. 31789 31790@item 31791@cindex list output in @sc{gdb/mi} 31792New @sc{gdb/mi} commands should only output @var{lists} containing 31793@var{values}. 31794 31795 31796@end itemize 31797 31798@xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more 31799details about the various output records. 31800 31801@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 31802@node GDB/MI Compatibility with CLI 31803@section @sc{gdb/mi} Compatibility with CLI 31804 31805@cindex compatibility, @sc{gdb/mi} and CLI 31806@cindex @sc{gdb/mi}, compatibility with CLI 31807 31808For the developers convenience CLI commands can be entered directly, 31809but there may be some unexpected behaviour. For example, commands 31810that query the user will behave as if the user replied yes, breakpoint 31811command lists are not executed and some CLI commands, such as 31812@code{if}, @code{when} and @code{define}, prompt for further input with 31813@samp{>}, which is not valid MI output. 31814 31815This feature may be removed at some stage in the future and it is 31816recommended that front ends use the @code{-interpreter-exec} command 31817(@pxref{-interpreter-exec}). 31818 31819@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 31820@node GDB/MI Development and Front Ends 31821@section @sc{gdb/mi} Development and Front Ends 31822@cindex @sc{gdb/mi} development 31823 31824The application which takes the MI output and presents the state of the 31825program being debugged to the user is called a @dfn{front end}. 31826 31827Since @sc{gdb/mi} is used by a variety of front ends to @value{GDBN}, changes 31828to the MI interface may break existing usage. This section describes how the 31829protocol changes and how to request previous version of the protocol when it 31830does. 31831 31832Some changes in MI need not break a carefully designed front end, and 31833for these the MI version will remain unchanged. The following is a 31834list of changes that may occur within one level, so front ends should 31835parse MI output in a way that can handle them: 31836 31837@itemize @bullet 31838@item 31839New MI commands may be added. 31840 31841@item 31842New fields may be added to the output of any MI command. 31843 31844@item 31845The range of values for fields with specified values, e.g., 31846@code{in_scope} (@pxref{-var-update}) may be extended. 31847 31848@c The format of field's content e.g type prefix, may change so parse it 31849@c at your own risk. Yes, in general? 31850 31851@c The order of fields may change? Shouldn't really matter but it might 31852@c resolve inconsistencies. 31853@end itemize 31854 31855If the changes are likely to break front ends, the MI version level 31856will be increased by one. The new versions of the MI protocol are not compatible 31857with the old versions. Old versions of MI remain available, allowing front ends 31858to keep using them until they are modified to use the latest MI version. 31859 31860Since @code{--interpreter=mi} always points to the latest MI version, it is 31861recommended that front ends request a specific version of MI when launching 31862@value{GDBN} (e.g.@: @code{--interpreter=mi2}) to make sure they get an 31863interpreter with the MI version they expect. 31864 31865The following table gives a summary of the released versions of the MI 31866interface: the version number, the version of GDB in which it first appeared 31867and the breaking changes compared to the previous version. 31868 31869@multitable @columnfractions .1 .1 .8 31870@headitem MI version @tab GDB version @tab Breaking changes 31871 31872@item 31873@center 1 31874@tab 31875@center 5.1 31876@tab 31877None 31878 31879@item 31880@center 2 31881@tab 31882@center 6.0 31883@tab 31884 31885@itemize 31886@item 31887The @code{-environment-pwd}, @code{-environment-directory} and 31888@code{-environment-path} commands now returns values using the MI output 31889syntax, rather than CLI output syntax. 31890 31891@item 31892@code{-var-list-children}'s @code{children} result field is now a list, rather 31893than a tuple. 31894 31895@item 31896@code{-var-update}'s @code{changelist} result field is now a list, rather than 31897a tuple. 31898@end itemize 31899 31900@item 31901@center 3 31902@tab 31903@center 9.1 31904@tab 31905 31906@itemize 31907@item 31908The output of information about multi-location breakpoints has changed in the 31909responses to the @code{-break-insert} and @code{-break-info} commands, as well 31910as in the @code{=breakpoint-created} and @code{=breakpoint-modified} events. 31911The multiple locations are now placed in a @code{locations} field, whose value 31912is a list. 31913@end itemize 31914 31915@item 31916@center 4 31917@tab 31918@center 13.1 31919@tab 31920 31921@itemize 31922@item 31923The syntax of the "script" field in breakpoint output has changed in the 31924responses to the @code{-break-insert} and @code{-break-info} commands, as 31925well as the @code{=breakpoint-created} and @code{=breakpoint-modified} 31926events. The previous output was syntactically invalid. The new output is 31927a list. 31928@end itemize 31929 31930@end multitable 31931 31932If your front end cannot yet migrate to a more recent version of the 31933MI protocol, you can nevertheless selectively enable specific features 31934available in those recent MI versions, using the following commands: 31935 31936@table @code 31937 31938@item -fix-multi-location-breakpoint-output 31939Use the output for multi-location breakpoints which was introduced by 31940MI 3, even when using MI versions below 3. This command has no 31941effect when using MI version 3 or later. 31942 31943@item -fix-breakpoint-script-output 31944Use the output for the breakpoint "script" field which was introduced by 31945MI 4, even when using MI versions below 4. This command has no effect when 31946using MI version 4 or later. 31947 31948@end table 31949 31950The best way to avoid unexpected changes in MI that might break your front 31951end is to make your project known to @value{GDBN} developers and 31952follow development on @email{gdb@@sourceware.org} and 31953@email{gdb-patches@@sourceware.org}. 31954@cindex mailing lists 31955 31956@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 31957@node GDB/MI Output Records 31958@section @sc{gdb/mi} Output Records 31959 31960@menu 31961* GDB/MI Result Records:: 31962* GDB/MI Stream Records:: 31963* GDB/MI Async Records:: 31964* GDB/MI Breakpoint Information:: 31965* GDB/MI Frame Information:: 31966* GDB/MI Thread Information:: 31967* GDB/MI Ada Exception Information:: 31968@end menu 31969 31970@node GDB/MI Result Records 31971@subsection @sc{gdb/mi} Result Records 31972 31973@cindex result records in @sc{gdb/mi} 31974@cindex @sc{gdb/mi}, result records 31975In addition to a number of out-of-band notifications, the response to a 31976@sc{gdb/mi} command includes one of the following result indications: 31977 31978@table @code 31979@findex ^done 31980@item "^done" [ "," @var{results} ] 31981The synchronous operation was successful, @code{@var{results}} are the return 31982values. 31983 31984@findex ^running 31985@item "^running" 31986This result record is equivalent to @samp{^done}. Historically, it 31987was output instead of @samp{^done} if the command has resumed the 31988target. This behaviour is maintained for backward compatibility, but 31989all frontends should treat @samp{^done} and @samp{^running} 31990identically and rely on the @samp{*running} output record to determine 31991which threads are resumed. 31992 31993@findex ^connected 31994@item "^connected" 31995@value{GDBN} has connected to a remote target. 31996 31997@findex ^error 31998@item "^error" "," "msg=" @var{c-string} [ "," "code=" @var{c-string} ] 31999The operation failed. The @code{msg=@var{c-string}} variable contains 32000the corresponding error message. 32001 32002If present, the @code{code=@var{c-string}} variable provides an error 32003code on which consumers can rely on to detect the corresponding 32004error condition. At present, only one error code is defined: 32005 32006@table @samp 32007@item "undefined-command" 32008Indicates that the command causing the error does not exist. 32009@end table 32010 32011@findex ^exit 32012@item "^exit" 32013@value{GDBN} has terminated. 32014 32015@end table 32016 32017@node GDB/MI Stream Records 32018@subsection @sc{gdb/mi} Stream Records 32019 32020@cindex @sc{gdb/mi}, stream records 32021@cindex stream records in @sc{gdb/mi} 32022@value{GDBN} internally maintains a number of output streams: the console, the 32023target, and the log. The output intended for each of these streams is 32024funneled through the @sc{gdb/mi} interface using @dfn{stream records}. 32025 32026Each stream record begins with a unique @dfn{prefix character} which 32027identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output 32028Syntax}). In addition to the prefix, each stream record contains a 32029@code{@var{string-output}}. This is either raw text (with an implicit new 32030line) or a quoted C string (which does not contain an implicit newline). 32031 32032@table @code 32033@item "~" @var{string-output} 32034The console output stream contains text that should be displayed in the 32035CLI console window. It contains the textual responses to CLI commands. 32036 32037@item "@@" @var{string-output} 32038The target output stream contains any textual output from the running 32039target. This is only present when GDB's event loop is truly 32040asynchronous, which is currently only the case for remote targets. 32041 32042@item "&" @var{string-output} 32043The log stream contains debugging messages being produced by @value{GDBN}'s 32044internals. 32045@end table 32046 32047@node GDB/MI Async Records 32048@subsection @sc{gdb/mi} Async Records 32049 32050@cindex async records in @sc{gdb/mi} 32051@cindex @sc{gdb/mi}, async records 32052@dfn{Async} records are used to notify the @sc{gdb/mi} client of 32053additional changes that have occurred. Those changes can either be a 32054consequence of @sc{gdb/mi} commands (e.g., a breakpoint modified) or a result of 32055target activity (e.g., target stopped). 32056 32057The following is the list of possible async records: 32058 32059@table @code 32060 32061@item *running,thread-id="@var{thread}" 32062The target is now running. The @var{thread} field can be the global 32063thread ID of the thread that is now running, and it can be 32064@samp{all} if all threads are running. The frontend should assume 32065that no interaction with a running thread is possible after this 32066notification is produced. The frontend should not assume that this 32067notification is output only once for any command. @value{GDBN} may 32068emit this notification several times, either for different threads, 32069because it cannot resume all threads together, or even for a single 32070thread, if the thread must be stepped though some code before letting 32071it run freely. 32072 32073@item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}",core="@var{core}" 32074The target has stopped. The @var{reason} field can have one of the 32075following values: 32076 32077@table @code 32078@item breakpoint-hit 32079A breakpoint was reached. 32080@item watchpoint-trigger 32081A watchpoint was triggered. 32082@item read-watchpoint-trigger 32083A read watchpoint was triggered. 32084@item access-watchpoint-trigger 32085An access watchpoint was triggered. 32086@item function-finished 32087An -exec-finish or similar CLI command was accomplished. 32088@item location-reached 32089An -exec-until or similar CLI command was accomplished. 32090@item watchpoint-scope 32091A watchpoint has gone out of scope. 32092@item end-stepping-range 32093An -exec-next, -exec-next-instruction, -exec-step, -exec-step-instruction or 32094similar CLI command was accomplished. 32095@item exited-signalled 32096The inferior exited because of a signal. 32097@item exited 32098The inferior exited. 32099@item exited-normally 32100The inferior exited normally. 32101@item signal-received 32102A signal was received by the inferior. 32103@item solib-event 32104The inferior has stopped due to a library being loaded or unloaded. 32105This can happen when @code{stop-on-solib-events} (@pxref{Files}) is 32106set or when a @code{catch load} or @code{catch unload} catchpoint is 32107in use (@pxref{Set Catchpoints}). 32108@item fork 32109The inferior has forked. This is reported when @code{catch fork} 32110(@pxref{Set Catchpoints}) has been used. 32111@item vfork 32112The inferior has vforked. This is reported in when @code{catch vfork} 32113(@pxref{Set Catchpoints}) has been used. 32114@item syscall-entry 32115The inferior entered a system call. This is reported when @code{catch 32116syscall} (@pxref{Set Catchpoints}) has been used. 32117@item syscall-return 32118The inferior returned from a system call. This is reported when 32119@code{catch syscall} (@pxref{Set Catchpoints}) has been used. 32120@item exec 32121The inferior called @code{exec}. This is reported when @code{catch exec} 32122(@pxref{Set Catchpoints}) has been used. 32123@item no-history 32124There isn't enough history recorded to continue reverse execution. 32125@end table 32126 32127The @var{id} field identifies the global thread ID of the thread 32128that directly caused the stop -- for example by hitting a breakpoint. 32129Depending on whether all-stop 32130mode is in effect (@pxref{All-Stop Mode}), @value{GDBN} may either 32131stop all threads, or only the thread that directly triggered the stop. 32132If all threads are stopped, the @var{stopped} field will have the 32133value of @code{"all"}. Otherwise, the value of the @var{stopped} 32134field will be a list of thread identifiers. Presently, this list will 32135always include a single thread, but frontend should be prepared to see 32136several threads in the list. The @var{core} field reports the 32137processor core on which the stop event has happened. This field may be absent 32138if such information is not available. 32139 32140@item =thread-group-added,id="@var{id}" 32141@itemx =thread-group-removed,id="@var{id}" 32142A thread group was either added or removed. The @var{id} field 32143contains the @value{GDBN} identifier of the thread group. When a thread 32144group is added, it generally might not be associated with a running 32145process. When a thread group is removed, its id becomes invalid and 32146cannot be used in any way. 32147 32148@item =thread-group-started,id="@var{id}",pid="@var{pid}" 32149A thread group became associated with a running program, 32150either because the program was just started or the thread group 32151was attached to a program. The @var{id} field contains the 32152@value{GDBN} identifier of the thread group. The @var{pid} field 32153contains process identifier, specific to the operating system. 32154 32155@item =thread-group-exited,id="@var{id}"[,exit-code="@var{code}"] 32156A thread group is no longer associated with a running program, 32157either because the program has exited, or because it was detached 32158from. The @var{id} field contains the @value{GDBN} identifier of the 32159thread group. The @var{code} field is the exit code of the inferior; it exists 32160only when the inferior exited with some code. 32161 32162@item =thread-created,id="@var{id}",group-id="@var{gid}" 32163@itemx =thread-exited,id="@var{id}",group-id="@var{gid}" 32164A thread either was created, or has exited. The @var{id} field 32165contains the global @value{GDBN} identifier of the thread. The @var{gid} 32166field identifies the thread group this thread belongs to. 32167 32168@item =thread-selected,id="@var{id}"[,frame="@var{frame}"] 32169Informs that the selected thread or frame were changed. This notification 32170is not emitted as result of the @code{-thread-select} or 32171@code{-stack-select-frame} commands, but is emitted whenever an MI command 32172that is not documented to change the selected thread and frame actually 32173changes them. In particular, invoking, directly or indirectly 32174(via user-defined command), the CLI @code{thread} or @code{frame} commands, 32175will generate this notification. Changing the thread or frame from another 32176user interface (see @ref{Interpreters}) will also generate this notification. 32177 32178The @var{frame} field is only present if the newly selected thread is 32179stopped. See @ref{GDB/MI Frame Information} for the format of its value. 32180 32181We suggest that in response to this notification, front ends 32182highlight the selected thread and cause subsequent commands to apply to 32183that thread. 32184 32185@item =library-loaded,... 32186Reports that a new library file was loaded by the program. This 32187notification has 5 fields---@var{id}, @var{target-name}, 32188@var{host-name}, @var{symbols-loaded} and @var{ranges}. The @var{id} field is an 32189opaque identifier of the library. For remote debugging case, 32190@var{target-name} and @var{host-name} fields give the name of the 32191library file on the target, and on the host respectively. For native 32192debugging, both those fields have the same value. The 32193@var{symbols-loaded} field is emitted only for backward compatibility 32194and should not be relied on to convey any useful information. The 32195@var{thread-group} field, if present, specifies the id of the thread 32196group in whose context the library was loaded. If the field is 32197absent, it means the library was loaded in the context of all present 32198thread groups. The @var{ranges} field specifies the ranges of addresses belonging 32199to this library. 32200 32201@item =library-unloaded,... 32202Reports that a library was unloaded by the program. This notification 32203has 3 fields---@var{id}, @var{target-name} and @var{host-name} with 32204the same meaning as for the @code{=library-loaded} notification. 32205The @var{thread-group} field, if present, specifies the id of the 32206thread group in whose context the library was unloaded. If the field is 32207absent, it means the library was unloaded in the context of all present 32208thread groups. 32209 32210@item =traceframe-changed,num=@var{tfnum},tracepoint=@var{tpnum} 32211@itemx =traceframe-changed,end 32212Reports that the trace frame was changed and its new number is 32213@var{tfnum}. The number of the tracepoint associated with this trace 32214frame is @var{tpnum}. 32215 32216@item =tsv-created,name=@var{name},initial=@var{initial} 32217Reports that the new trace state variable @var{name} is created with 32218initial value @var{initial}. 32219 32220@item =tsv-deleted,name=@var{name} 32221@itemx =tsv-deleted 32222Reports that the trace state variable @var{name} is deleted or all 32223trace state variables are deleted. 32224 32225@item =tsv-modified,name=@var{name},initial=@var{initial}[,current=@var{current}] 32226Reports that the trace state variable @var{name} is modified with 32227the initial value @var{initial}. The current value @var{current} of 32228trace state variable is optional and is reported if the current 32229value of trace state variable is known. 32230 32231@item =breakpoint-created,bkpt=@{...@} 32232@itemx =breakpoint-modified,bkpt=@{...@} 32233@itemx =breakpoint-deleted,id=@var{number} 32234Reports that a breakpoint was created, modified, or deleted, 32235respectively. Only user-visible breakpoints are reported to the MI 32236user. 32237 32238The @var{bkpt} argument is of the same form as returned by the various 32239breakpoint commands; @xref{GDB/MI Breakpoint Commands}. The 32240@var{number} is the ordinal number of the breakpoint. 32241 32242Note that if a breakpoint is emitted in the result record of a 32243command, then it will not also be emitted in an async record. 32244 32245@item =record-started,thread-group="@var{id}",method="@var{method}"[,format="@var{format}"] 32246@itemx =record-stopped,thread-group="@var{id}" 32247Execution log recording was either started or stopped on an 32248inferior. The @var{id} is the @value{GDBN} identifier of the thread 32249group corresponding to the affected inferior. 32250 32251The @var{method} field indicates the method used to record execution. If the 32252method in use supports multiple recording formats, @var{format} will be present 32253and contain the currently used format. @xref{Process Record and Replay}, 32254for existing method and format values. 32255 32256@item =cmd-param-changed,param=@var{param},value=@var{value} 32257Reports that a parameter of the command @code{set @var{param}} is 32258changed to @var{value}. In the multi-word @code{set} command, 32259the @var{param} is the whole parameter list to @code{set} command. 32260For example, In command @code{set check type on}, @var{param} 32261is @code{check type} and @var{value} is @code{on}. 32262 32263@item =memory-changed,thread-group=@var{id},addr=@var{addr},len=@var{len}[,type="code"] 32264Reports that bytes from @var{addr} to @var{data} + @var{len} were 32265written in an inferior. The @var{id} is the identifier of the 32266thread group corresponding to the affected inferior. The optional 32267@code{type="code"} part is reported if the memory written to holds 32268executable code. 32269@end table 32270 32271@node GDB/MI Breakpoint Information 32272@subsection @sc{gdb/mi} Breakpoint Information 32273 32274When @value{GDBN} reports information about a breakpoint, a 32275tracepoint, a watchpoint, or a catchpoint, it uses a tuple with the 32276following fields: 32277 32278@table @code 32279@item number 32280The breakpoint number. 32281 32282@item type 32283The type of the breakpoint. For ordinary breakpoints this will be 32284@samp{breakpoint}, but many values are possible. 32285 32286@item catch-type 32287If the type of the breakpoint is @samp{catchpoint}, then this 32288indicates the exact type of catchpoint. 32289 32290@item disp 32291This is the breakpoint disposition---either @samp{del}, meaning that 32292the breakpoint will be deleted at the next stop, or @samp{keep}, 32293meaning that the breakpoint will not be deleted. 32294 32295@item enabled 32296This indicates whether the breakpoint is enabled, in which case the 32297value is @samp{y}, or disabled, in which case the value is @samp{n}. 32298Note that this is not the same as the field @code{enable}. 32299 32300@item addr 32301The address of the breakpoint. This may be a hexadecimal number, 32302giving the address; or the string @samp{<PENDING>}, for a pending 32303breakpoint; or the string @samp{<MULTIPLE>}, for a breakpoint with 32304multiple locations. This field will not be present if no address can 32305be determined. For example, a watchpoint does not have an address. 32306 32307@item addr_flags 32308Optional field containing any flags related to the address. These flags are 32309architecture-dependent; see @ref{Architectures} for their meaning for a 32310particular CPU. 32311 32312@item func 32313If known, the function in which the breakpoint appears. 32314If not known, this field is not present. 32315 32316@item filename 32317The name of the source file which contains this function, if known. 32318If not known, this field is not present. 32319 32320@item fullname 32321The full file name of the source file which contains this function, if 32322known. If not known, this field is not present. 32323 32324@item line 32325The line number at which this breakpoint appears, if known. 32326If not known, this field is not present. 32327 32328@item at 32329If the source file is not known, this field may be provided. If 32330provided, this holds the address of the breakpoint, possibly followed 32331by a symbol name. 32332 32333@item pending 32334If this breakpoint is pending, this field is present and holds the 32335text used to set the breakpoint, as entered by the user. 32336 32337@item evaluated-by 32338Where this breakpoint's condition is evaluated, either @samp{host} or 32339@samp{target}. 32340 32341@item thread 32342If this is a thread-specific breakpoint, then this identifies the 32343thread in which the breakpoint can trigger. 32344 32345@item inferior 32346If this is an inferior-specific breakpoint, this this identifies the 32347inferior in which the breakpoint can trigger. 32348 32349@item task 32350If this breakpoint is restricted to a particular Ada task, then this 32351field will hold the task identifier. 32352 32353@item cond 32354If the breakpoint is conditional, this is the condition expression. 32355 32356@item ignore 32357The ignore count of the breakpoint. 32358 32359@item enable 32360The enable count of the breakpoint. 32361 32362@item traceframe-usage 32363FIXME. 32364 32365@item static-tracepoint-marker-string-id 32366For a static tracepoint, the name of the static tracepoint marker. 32367 32368@item mask 32369For a masked watchpoint, this is the mask. 32370 32371@item pass 32372A tracepoint's pass count. 32373 32374@item original-location 32375The location of the breakpoint as originally specified by the user. 32376This field is optional. 32377 32378@item times 32379The number of times the breakpoint has been hit. 32380 32381@item installed 32382This field is only given for tracepoints. This is either @samp{y}, 32383meaning that the tracepoint is installed, or @samp{n}, meaning that it 32384is not. 32385 32386@item what 32387Some extra data, the exact contents of which are type-dependent. 32388 32389@item locations 32390This field is present if the breakpoint has multiple locations. It is also 32391exceptionally present if the breakpoint is enabled and has a single, disabled 32392location. 32393 32394The value is a list of locations. The format of a location is described below. 32395 32396@end table 32397 32398A location in a multi-location breakpoint is represented as a tuple with the 32399following fields: 32400 32401@table @code 32402 32403@item number 32404The location number as a dotted pair, like @samp{1.2}. The first digit is the 32405number of the parent breakpoint. The second digit is the number of the 32406location within that breakpoint. 32407 32408@item enabled 32409There are three possible values, with the following meanings: 32410@table @code 32411@item y 32412The location is enabled. 32413@item n 32414The location is disabled by the user. 32415@item N 32416The location is disabled because the breakpoint condition is invalid 32417at this location. 32418@end table 32419 32420@item addr 32421The address of this location as an hexadecimal number. 32422 32423@item addr_flags 32424Optional field containing any flags related to the address. These flags are 32425architecture-dependent; see @ref{Architectures} for their meaning for a 32426particular CPU. 32427 32428@item func 32429If known, the function in which the location appears. 32430If not known, this field is not present. 32431 32432@item file 32433The name of the source file which contains this location, if known. 32434If not known, this field is not present. 32435 32436@item fullname 32437The full file name of the source file which contains this location, if 32438known. If not known, this field is not present. 32439 32440@item line 32441The line number at which this location appears, if known. 32442If not known, this field is not present. 32443 32444@item thread-groups 32445The thread groups this location is in. 32446 32447@end table 32448 32449For example, here is what the output of @code{-break-insert} 32450(@pxref{GDB/MI Breakpoint Commands}) might be: 32451 32452@smallexample 32453-> -break-insert main 32454<- ^done,bkpt=@{number="1",type="breakpoint",disp="keep", 32455 enabled="y",addr="0x08048564",func="main",file="myprog.c", 32456 fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"], 32457 times="0"@} 32458<- (gdb) 32459@end smallexample 32460 32461@node GDB/MI Frame Information 32462@subsection @sc{gdb/mi} Frame Information 32463 32464Response from many MI commands includes an information about stack 32465frame. This information is a tuple that may have the following 32466fields: 32467 32468@table @code 32469@item level 32470The level of the stack frame. The innermost frame has the level of 32471zero. This field is always present. 32472 32473@item func 32474The name of the function corresponding to the frame. This field may 32475be absent if @value{GDBN} is unable to determine the function name. 32476 32477@item addr 32478The code address for the frame. This field is always present. 32479 32480@item addr_flags 32481Optional field containing any flags related to the address. These flags are 32482architecture-dependent; see @ref{Architectures} for their meaning for a 32483particular CPU. 32484 32485@item file 32486The name of the source files that correspond to the frame's code 32487address. This field may be absent. 32488 32489@item line 32490The source line corresponding to the frames' code address. This field 32491may be absent. 32492 32493@item from 32494The name of the binary file (either executable or shared library) the 32495corresponds to the frame's code address. This field may be absent. 32496 32497@end table 32498 32499@node GDB/MI Thread Information 32500@subsection @sc{gdb/mi} Thread Information 32501 32502Whenever @value{GDBN} has to report an information about a thread, it 32503uses a tuple with the following fields. The fields are always present unless 32504stated otherwise. 32505 32506@table @code 32507@item id 32508The global numeric id assigned to the thread by @value{GDBN}. 32509 32510@item target-id 32511The target-specific string identifying the thread. 32512 32513@item details 32514Additional information about the thread provided by the target. 32515It is supposed to be human-readable and not interpreted by the 32516frontend. This field is optional. 32517 32518@item name 32519The name of the thread. If the user specified a name using the 32520@code{thread name} command, then this name is given. Otherwise, if 32521@value{GDBN} can extract the thread name from the target, then that 32522name is given. If @value{GDBN} cannot find the thread name, then this 32523field is omitted. 32524 32525@item state 32526The execution state of the thread, either @samp{stopped} or @samp{running}, 32527depending on whether the thread is presently running. 32528 32529@item frame 32530The stack frame currently executing in the thread. This field is only present 32531if the thread is stopped. Its format is documented in 32532@ref{GDB/MI Frame Information}. 32533 32534@item core 32535The value of this field is an integer number of the processor core the 32536thread was last seen on. This field is optional. 32537@end table 32538 32539@node GDB/MI Ada Exception Information 32540@subsection @sc{gdb/mi} Ada Exception Information 32541 32542Whenever a @code{*stopped} record is emitted because the program 32543stopped after hitting an exception catchpoint (@pxref{Set Catchpoints}), 32544@value{GDBN} provides the name of the exception that was raised via 32545the @code{exception-name} field. Also, for exceptions that were raised 32546with an exception message, @value{GDBN} provides that message via 32547the @code{exception-message} field. 32548 32549@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 32550@node GDB/MI Simple Examples 32551@section Simple Examples of @sc{gdb/mi} Interaction 32552@cindex @sc{gdb/mi}, simple examples 32553 32554This subsection presents several simple examples of interaction using 32555the @sc{gdb/mi} interface. In these examples, @samp{->} means that the 32556following line is passed to @sc{gdb/mi} as input, while @samp{<-} means 32557the output received from @sc{gdb/mi}. 32558 32559Note the line breaks shown in the examples are here only for 32560readability, they don't appear in the real output. 32561 32562@subheading Setting a Breakpoint 32563 32564Setting a breakpoint generates synchronous output which contains detailed 32565information of the breakpoint. 32566 32567@smallexample 32568-> -break-insert main 32569<- ^done,bkpt=@{number="1",type="breakpoint",disp="keep", 32570 enabled="y",addr="0x08048564",func="main",file="myprog.c", 32571 fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"], 32572 times="0"@} 32573<- (gdb) 32574@end smallexample 32575 32576@subheading Program Execution 32577 32578Program execution generates asynchronous records and MI gives the 32579reason that execution stopped. 32580 32581@smallexample 32582-> -exec-run 32583<- ^running 32584<- (gdb) 32585<- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", 32586 frame=@{addr="0x08048564",func="main", 32587 args=[@{name="argc",value="1"@},@{name="argv",value="0xbfc4d4d4"@}], 32588 file="myprog.c",fullname="/home/nickrob/myprog.c",line="68", 32589 arch="i386:x86_64"@} 32590<- (gdb) 32591-> -exec-continue 32592<- ^running 32593<- (gdb) 32594<- *stopped,reason="exited-normally" 32595<- (gdb) 32596@end smallexample 32597 32598@subheading Quitting @value{GDBN} 32599 32600Quitting @value{GDBN} just prints the result class @samp{^exit}. 32601 32602@smallexample 32603-> (gdb) 32604<- -gdb-exit 32605<- ^exit 32606@end smallexample 32607 32608Please note that @samp{^exit} is printed immediately, but it might 32609take some time for @value{GDBN} to actually exit. During that time, @value{GDBN} 32610performs necessary cleanups, including killing programs being debugged 32611or disconnecting from debug hardware, so the frontend should wait till 32612@value{GDBN} exits and should only forcibly kill @value{GDBN} if it 32613fails to exit in reasonable time. 32614 32615@subheading A Bad Command 32616 32617Here's what happens if you pass a non-existent command: 32618 32619@smallexample 32620-> -rubbish 32621<- ^error,msg="Undefined MI command: rubbish" 32622<- (gdb) 32623@end smallexample 32624 32625 32626@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 32627@node GDB/MI Command Description Format 32628@section @sc{gdb/mi} Command Description Format 32629 32630The remaining sections describe blocks of commands. Each block of 32631commands is laid out in a fashion similar to this section. 32632 32633@subheading Motivation 32634 32635The motivation for this collection of commands. 32636 32637@subheading Introduction 32638 32639A brief introduction to this collection of commands as a whole. 32640 32641@subheading Commands 32642 32643For each command in the block, the following is described: 32644 32645@subsubheading Synopsis 32646 32647@smallexample 32648 -command @var{args}@dots{} 32649@end smallexample 32650 32651@subsubheading Result 32652 32653@subsubheading @value{GDBN} Command 32654 32655The corresponding @value{GDBN} CLI command(s), if any. 32656 32657@subsubheading Example 32658 32659Example(s) formatted for readability. Some of the described commands have 32660not been implemented yet and these are labeled N.A.@: (not available). 32661 32662 32663@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 32664@node GDB/MI Breakpoint Commands 32665@section @sc{gdb/mi} Breakpoint Commands 32666 32667@cindex breakpoint commands for @sc{gdb/mi} 32668@cindex @sc{gdb/mi}, breakpoint commands 32669This section documents @sc{gdb/mi} commands for manipulating 32670breakpoints. 32671 32672@findex -break-after 32673@subheading The @code{-break-after} Command 32674 32675@subsubheading Synopsis 32676 32677@smallexample 32678 -break-after @var{number} @var{count} 32679@end smallexample 32680 32681The breakpoint number @var{number} is not in effect until it has been 32682hit @var{count} times. To see how this is reflected in the output of 32683the @samp{-break-list} command, see the description of the 32684@samp{-break-list} command below. 32685 32686@subsubheading @value{GDBN} Command 32687 32688The corresponding @value{GDBN} command is @samp{ignore}. 32689 32690@subsubheading Example 32691 32692@smallexample 32693(gdb) 32694-break-insert main 32695^done,bkpt=@{number="1",type="breakpoint",disp="keep", 32696enabled="y",addr="0x000100d0",func="main",file="hello.c", 32697fullname="/home/foo/hello.c",line="5",thread-groups=["i1"], 32698times="0"@} 32699(gdb) 32700-break-after 1 3 32701~ 32702^done 32703(gdb) 32704-break-list 32705^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 32706hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 32707@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 32708@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 32709@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 32710@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 32711@{width="40",alignment="2",col_name="what",colhdr="What"@}], 32712body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 32713addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 32714line="5",thread-groups=["i1"],times="0",ignore="3"@}]@} 32715(gdb) 32716@end smallexample 32717 32718@ignore 32719@findex -break-catch 32720@subheading The @code{-break-catch} Command 32721@end ignore 32722 32723@findex -break-commands 32724@subheading The @code{-break-commands} Command 32725 32726@subsubheading Synopsis 32727 32728@smallexample 32729 -break-commands @var{number} [ @var{command1} ... @var{commandN} ] 32730@end smallexample 32731 32732Specifies the CLI commands that should be executed when breakpoint 32733@var{number} is hit. The parameters @var{command1} to @var{commandN} 32734are the commands. If no command is specified, any previously-set 32735commands are cleared. @xref{Break Commands}. Typical use of this 32736functionality is tracing a program, that is, printing of values of 32737some variables whenever breakpoint is hit and then continuing. 32738 32739@subsubheading @value{GDBN} Command 32740 32741The corresponding @value{GDBN} command is @samp{commands}. 32742 32743@subsubheading Example 32744 32745@smallexample 32746(gdb) 32747-break-insert main 32748^done,bkpt=@{number="1",type="breakpoint",disp="keep", 32749enabled="y",addr="0x000100d0",func="main",file="hello.c", 32750fullname="/home/foo/hello.c",line="5",thread-groups=["i1"], 32751times="0"@} 32752(gdb) 32753-break-commands 1 "print v" "continue" 32754^done 32755(gdb) 32756@end smallexample 32757 32758@findex -break-condition 32759@subheading The @code{-break-condition} Command 32760 32761@subsubheading Synopsis 32762 32763@smallexample 32764 -break-condition [ --force ] @var{number} [ @var{expr} ] 32765@end smallexample 32766 32767Breakpoint @var{number} will stop the program only if the condition in 32768@var{expr} is true. The condition becomes part of the 32769@samp{-break-list} output (see the description of the @samp{-break-list} 32770command below). If the @samp{--force} flag is passed, the condition 32771is forcibly defined even when it is invalid for all locations of 32772breakpoint @var{number}. If the @var{expr} argument is omitted, 32773breakpoint @var{number} becomes unconditional. 32774 32775@subsubheading @value{GDBN} Command 32776 32777The corresponding @value{GDBN} command is @samp{condition}. 32778 32779@subsubheading Example 32780 32781@smallexample 32782(gdb) 32783-break-condition 1 1 32784^done 32785(gdb) 32786-break-list 32787^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 32788hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 32789@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 32790@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 32791@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 32792@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 32793@{width="40",alignment="2",col_name="what",colhdr="What"@}], 32794body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 32795addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 32796line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"@}]@} 32797(gdb) 32798@end smallexample 32799 32800@findex -break-delete 32801@subheading The @code{-break-delete} Command 32802 32803@subsubheading Synopsis 32804 32805@smallexample 32806 -break-delete ( @var{breakpoint} )+ 32807@end smallexample 32808 32809Delete the breakpoint(s) whose number(s) are specified in the argument 32810list. This is obviously reflected in the breakpoint list. 32811 32812@subsubheading @value{GDBN} Command 32813 32814The corresponding @value{GDBN} command is @samp{delete}. 32815 32816@subsubheading Example 32817 32818@smallexample 32819(gdb) 32820-break-delete 1 32821^done 32822(gdb) 32823-break-list 32824^done,BreakpointTable=@{nr_rows="0",nr_cols="6", 32825hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 32826@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 32827@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 32828@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 32829@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 32830@{width="40",alignment="2",col_name="what",colhdr="What"@}], 32831body=[]@} 32832(gdb) 32833@end smallexample 32834 32835@findex -break-disable 32836@subheading The @code{-break-disable} Command 32837 32838@subsubheading Synopsis 32839 32840@smallexample 32841 -break-disable ( @var{breakpoint} )+ 32842@end smallexample 32843 32844Disable the named @var{breakpoint}(s). The field @samp{enabled} in the 32845break list is now set to @samp{n} for the named @var{breakpoint}(s). 32846 32847@subsubheading @value{GDBN} Command 32848 32849The corresponding @value{GDBN} command is @samp{disable}. 32850 32851@subsubheading Example 32852 32853@smallexample 32854(gdb) 32855-break-disable 2 32856^done 32857(gdb) 32858-break-list 32859^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 32860hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 32861@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 32862@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 32863@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 32864@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 32865@{width="40",alignment="2",col_name="what",colhdr="What"@}], 32866body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n", 32867addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 32868line="5",thread-groups=["i1"],times="0"@}]@} 32869(gdb) 32870@end smallexample 32871 32872@findex -break-enable 32873@subheading The @code{-break-enable} Command 32874 32875@subsubheading Synopsis 32876 32877@smallexample 32878 -break-enable ( @var{breakpoint} )+ 32879@end smallexample 32880 32881Enable (previously disabled) @var{breakpoint}(s). 32882 32883@subsubheading @value{GDBN} Command 32884 32885The corresponding @value{GDBN} command is @samp{enable}. 32886 32887@subsubheading Example 32888 32889@smallexample 32890(gdb) 32891-break-enable 2 32892^done 32893(gdb) 32894-break-list 32895^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 32896hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 32897@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 32898@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 32899@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 32900@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 32901@{width="40",alignment="2",col_name="what",colhdr="What"@}], 32902body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", 32903addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 32904line="5",thread-groups=["i1"],times="0"@}]@} 32905(gdb) 32906@end smallexample 32907 32908@findex -break-info 32909@subheading The @code{-break-info} Command 32910 32911@subsubheading Synopsis 32912 32913@smallexample 32914 -break-info @var{breakpoint} 32915@end smallexample 32916 32917@c REDUNDANT??? 32918Get information about a single breakpoint. 32919 32920The result is a table of breakpoints. @xref{GDB/MI Breakpoint 32921Information}, for details on the format of each breakpoint in the 32922table. 32923 32924@subsubheading @value{GDBN} Command 32925 32926The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}. 32927 32928@subsubheading Example 32929N.A. 32930 32931@findex -break-insert 32932@anchor{-break-insert} 32933@subheading The @code{-break-insert} Command 32934 32935@subsubheading Synopsis 32936 32937@smallexample 32938 -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] [ --qualified ] 32939 [ -c @var{condition} ] [ --force-condition ] [ -i @var{ignore-count} ] 32940 [ -p @var{thread-id} ] [ -g @var{thread-group-id} ] [ @var{locspec} ] 32941@end smallexample 32942 32943@noindent 32944If specified, @var{locspec}, can be one of: 32945 32946@table @var 32947@item linespec location 32948A linespec location. @xref{Linespec Locations}. 32949 32950@item explicit location 32951An explicit location. @sc{gdb/mi} explicit locations are 32952analogous to the CLI's explicit locations using the option names 32953listed below. @xref{Explicit Locations}. 32954 32955@table @samp 32956@item --source @var{filename} 32957The source file name of the location. This option requires the use 32958of either @samp{--function} or @samp{--line}. 32959 32960@item --function @var{function} 32961The name of a function or method. 32962 32963@item --label @var{label} 32964The name of a label. 32965 32966@item --line @var{lineoffset} 32967An absolute or relative line offset from the start of the location. 32968@end table 32969 32970@item address location 32971An address location, *@var{address}. @xref{Address Locations}. 32972@end table 32973 32974@noindent 32975The possible optional parameters of this command are: 32976 32977@table @samp 32978@item -t 32979Insert a temporary breakpoint. 32980@item -h 32981Insert a hardware breakpoint. 32982@item -f 32983If @var{locspec} cannot be resolved (for example if it 32984refers to unknown files or functions), create a pending 32985breakpoint. Without this flag, @value{GDBN} will report 32986an error, and won't create a breakpoint, if @var{locspec} 32987cannot be parsed. 32988@item -d 32989Create a disabled breakpoint. 32990@item -a 32991Create a tracepoint. @xref{Tracepoints}. When this parameter 32992is used together with @samp{-h}, a fast tracepoint is created. 32993@item -c @var{condition} 32994Make the breakpoint conditional on @var{condition}. 32995@item --force-condition 32996Forcibly define the breakpoint even if the condition is invalid at 32997all of the breakpoint locations. 32998@item -i @var{ignore-count} 32999Initialize the @var{ignore-count}. 33000@item -p @var{thread-id} 33001Restrict the breakpoint to the thread with the specified global 33002@var{thread-id}. @var{thread-id} must be a valid thread-id at the 33003time the breakpoint is requested. Breakpoints created with a 33004@var{thread-id} will automatically be deleted when the corresponding 33005thread exits. 33006@item -g @var{thread-group-id} 33007Restrict the breakpoint to the thread group with the specified 33008@var{thread-group-id}. 33009@item --qualified 33010This option makes @value{GDBN} interpret a function name specified as 33011a complete fully-qualified name. 33012@end table 33013 33014@subsubheading Result 33015 33016@xref{GDB/MI Breakpoint Information}, for details on the format of the 33017resulting breakpoint. 33018 33019Note: this format is open to change. 33020@c An out-of-band breakpoint instead of part of the result? 33021 33022@subsubheading @value{GDBN} Command 33023 33024The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak}, 33025@samp{hbreak}, and @samp{thbreak}. @c and @samp{rbreak}. 33026 33027@subsubheading Example 33028 33029@smallexample 33030(gdb) 33031-break-insert main 33032^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c", 33033fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"], 33034times="0"@} 33035(gdb) 33036-break-insert -t foo 33037^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c", 33038fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"], 33039times="0"@} 33040(gdb) 33041-break-list 33042^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 33043hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 33044@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 33045@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 33046@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 33047@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 33048@{width="40",alignment="2",col_name="what",colhdr="What"@}], 33049body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 33050addr="0x0001072c", func="main",file="recursive2.c", 33051fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"], 33052times="0"@}, 33053bkpt=@{number="2",type="breakpoint",disp="del",enabled="y", 33054addr="0x00010774",func="foo",file="recursive2.c", 33055fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"], 33056times="0"@}]@} 33057(gdb) 33058@end smallexample 33059 33060@findex -dprintf-insert 33061@subheading The @code{-dprintf-insert} Command 33062 33063@subsubheading Synopsis 33064 33065@smallexample 33066 -dprintf-insert [ -t ] [ -f ] [ -d ] [ --qualified ] 33067 [ -c @var{condition} ] [--force-condition] [ -i @var{ignore-count} ] 33068 [ -p @var{thread-id} ] [ @var{locspec} ] @var{format} 33069 [ @var{argument}@dots{} ] 33070@end smallexample 33071 33072@noindent 33073Insert a new dynamic print breakpoint at the given location. 33074@xref{Dynamic Printf}. @var{format} is the format to use, and any 33075remaining arguments are passed as expressions to substitute. 33076 33077@noindent 33078If supplied, @var{locspec} and @code{--qualified} may be specified 33079the same way as for the @code{-break-insert} command. 33080@xref{-break-insert}. 33081 33082The possible optional parameters of this command are: 33083 33084@table @samp 33085@item -t 33086Insert a temporary breakpoint. 33087@item -f 33088If @var{locspec} cannot be parsed (for example, if it 33089refers to unknown files or functions), create a pending 33090breakpoint. Without this flag, @value{GDBN} will report 33091an error, and won't create a breakpoint, if @var{locspec} 33092cannot be parsed. 33093@item -d 33094Create a disabled breakpoint. 33095@item -c @var{condition} 33096Make the breakpoint conditional on @var{condition}. 33097@item --force-condition 33098Forcibly define the breakpoint even if the condition is invalid at 33099all of the breakpoint locations. 33100@item -i @var{ignore-count} 33101Set the ignore count of the breakpoint (@pxref{Conditions, ignore count}) 33102to @var{ignore-count}. 33103@item -p @var{thread-id} 33104Restrict the breakpoint to the thread with the specified global 33105@var{thread-id}. 33106@end table 33107 33108@subsubheading Result 33109 33110@xref{GDB/MI Breakpoint Information}, for details on the format of the 33111resulting breakpoint. 33112 33113@c An out-of-band breakpoint instead of part of the result? 33114 33115@subsubheading @value{GDBN} Command 33116 33117The corresponding @value{GDBN} command is @samp{dprintf}. 33118 33119@subsubheading Example 33120 33121@smallexample 33122(gdb) 331234-dprintf-insert foo "At foo entry\n" 331244^done,bkpt=@{number="1",type="dprintf",disp="keep",enabled="y", 33125addr="0x000000000040061b",func="foo",file="mi-dprintf.c", 33126fullname="mi-dprintf.c",line="25",thread-groups=["i1"], 33127times="0",script=["printf \"At foo entry\\n\"","continue"], 33128original-location="foo"@} 33129(gdb) 331305-dprintf-insert 26 "arg=%d, g=%d\n" arg g 331315^done,bkpt=@{number="2",type="dprintf",disp="keep",enabled="y", 33132addr="0x000000000040062a",func="foo",file="mi-dprintf.c", 33133fullname="mi-dprintf.c",line="26",thread-groups=["i1"], 33134times="0",script=["printf \"arg=%d, g=%d\\n\", arg, g","continue"], 33135original-location="mi-dprintf.c:26"@} 33136(gdb) 33137@end smallexample 33138 33139@findex -break-list 33140@subheading The @code{-break-list} Command 33141 33142@subsubheading Synopsis 33143 33144@smallexample 33145 -break-list 33146@end smallexample 33147 33148Displays the list of inserted breakpoints, showing the following fields: 33149 33150@table @samp 33151@item Number 33152number of the breakpoint 33153@item Type 33154type of the breakpoint: @samp{breakpoint} or @samp{watchpoint} 33155@item Disposition 33156should the breakpoint be deleted or disabled when it is hit: @samp{keep} 33157or @samp{nokeep} 33158@item Enabled 33159is the breakpoint enabled or no: @samp{y} or @samp{n} 33160@item Address 33161memory location at which the breakpoint is set 33162@item What 33163logical location of the breakpoint, expressed by function name, file 33164name, line number 33165@item Thread-groups 33166list of thread groups to which this breakpoint applies 33167@item Times 33168number of times the breakpoint has been hit 33169@end table 33170 33171If there are no breakpoints, watchpoints, tracepoints, or catchpoints, 33172the @code{BreakpointTable} @code{body} field is an empty list. 33173 33174@subsubheading @value{GDBN} Command 33175 33176The corresponding @value{GDBN} command is @samp{info break}. 33177 33178@subsubheading Example 33179 33180@smallexample 33181(gdb) 33182-break-list 33183^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 33184hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 33185@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 33186@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 33187@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 33188@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 33189@{width="40",alignment="2",col_name="what",colhdr="What"@}], 33190body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 33191addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"], 33192times="0"@}, 33193bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", 33194addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c", 33195line="13",thread-groups=["i1"],times="0"@}]@} 33196(gdb) 33197@end smallexample 33198 33199Here's an example of the result when there are no breakpoints: 33200 33201@smallexample 33202(gdb) 33203-break-list 33204^done,BreakpointTable=@{nr_rows="0",nr_cols="6", 33205hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 33206@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 33207@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 33208@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 33209@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 33210@{width="40",alignment="2",col_name="what",colhdr="What"@}], 33211body=[]@} 33212(gdb) 33213@end smallexample 33214 33215@findex -break-passcount 33216@subheading The @code{-break-passcount} Command 33217 33218@subsubheading Synopsis 33219 33220@smallexample 33221 -break-passcount @var{tracepoint-number} @var{passcount} 33222@end smallexample 33223 33224Set the passcount for tracepoint @var{tracepoint-number} to 33225@var{passcount}. If the breakpoint referred to by @var{tracepoint-number} 33226is not a tracepoint, error is emitted. This corresponds to CLI 33227command @samp{passcount}. 33228 33229@findex -break-watch 33230@subheading The @code{-break-watch} Command 33231 33232@subsubheading Synopsis 33233 33234@smallexample 33235 -break-watch [ -a | -r ] 33236@end smallexample 33237 33238Create a watchpoint. With the @samp{-a} option it will create an 33239@dfn{access} watchpoint, i.e., a watchpoint that triggers either on a 33240read from or on a write to the memory location. With the @samp{-r} 33241option, the watchpoint created is a @dfn{read} watchpoint, i.e., it will 33242trigger only when the memory location is accessed for reading. Without 33243either of the options, the watchpoint created is a regular watchpoint, 33244i.e., it will trigger when the memory location is accessed for writing. 33245@xref{Set Watchpoints, , Setting Watchpoints}. 33246 33247Note that @samp{-break-list} will report a single list of watchpoints and 33248breakpoints inserted. 33249 33250@subsubheading @value{GDBN} Command 33251 33252The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and 33253@samp{rwatch}. 33254 33255@subsubheading Example 33256 33257Setting a watchpoint on a variable in the @code{main} function: 33258 33259@smallexample 33260(gdb) 33261-break-watch x 33262^done,wpt=@{number="2",exp="x"@} 33263(gdb) 33264-exec-continue 33265^running 33266(gdb) 33267*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@}, 33268value=@{old="-268439212",new="55"@}, 33269frame=@{func="main",args=[],file="recursive2.c", 33270fullname="/home/foo/bar/recursive2.c",line="5",arch="i386:x86_64"@} 33271(gdb) 33272@end smallexample 33273 33274Setting a watchpoint on a variable local to a function. @value{GDBN} will stop 33275the program execution twice: first for the variable changing value, then 33276for the watchpoint going out of scope. 33277 33278@smallexample 33279(gdb) 33280-break-watch C 33281^done,wpt=@{number="5",exp="C"@} 33282(gdb) 33283-exec-continue 33284^running 33285(gdb) 33286*stopped,reason="watchpoint-trigger", 33287wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@}, 33288frame=@{func="callee4",args=[], 33289file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 33290fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13", 33291arch="i386:x86_64"@} 33292(gdb) 33293-exec-continue 33294^running 33295(gdb) 33296*stopped,reason="watchpoint-scope",wpnum="5", 33297frame=@{func="callee3",args=[@{name="strarg", 33298value="0x11940 \"A string argument.\""@}], 33299file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 33300fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18", 33301arch="i386:x86_64"@} 33302(gdb) 33303@end smallexample 33304 33305Listing breakpoints and watchpoints, at different points in the program 33306execution. Note that once the watchpoint goes out of scope, it is 33307deleted. 33308 33309@smallexample 33310(gdb) 33311-break-watch C 33312^done,wpt=@{number="2",exp="C"@} 33313(gdb) 33314-break-list 33315^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 33316hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 33317@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 33318@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 33319@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 33320@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 33321@{width="40",alignment="2",col_name="what",colhdr="What"@}], 33322body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 33323addr="0x00010734",func="callee4", 33324file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 33325fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"], 33326times="1"@}, 33327bkpt=@{number="2",type="watchpoint",disp="keep", 33328enabled="y",addr="",what="C",thread-groups=["i1"],times="0"@}]@} 33329(gdb) 33330-exec-continue 33331^running 33332(gdb) 33333*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@}, 33334value=@{old="-276895068",new="3"@}, 33335frame=@{func="callee4",args=[], 33336file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 33337fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13", 33338arch="i386:x86_64"@} 33339(gdb) 33340-break-list 33341^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 33342hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 33343@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 33344@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 33345@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 33346@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 33347@{width="40",alignment="2",col_name="what",colhdr="What"@}], 33348body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 33349addr="0x00010734",func="callee4", 33350file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 33351fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"], 33352times="1"@}, 33353bkpt=@{number="2",type="watchpoint",disp="keep", 33354enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"@}]@} 33355(gdb) 33356-exec-continue 33357^running 33358^done,reason="watchpoint-scope",wpnum="2", 33359frame=@{func="callee3",args=[@{name="strarg", 33360value="0x11940 \"A string argument.\""@}], 33361file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 33362fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18", 33363arch="i386:x86_64"@} 33364(gdb) 33365-break-list 33366^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 33367hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 33368@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 33369@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 33370@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 33371@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 33372@{width="40",alignment="2",col_name="what",colhdr="What"@}], 33373body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 33374addr="0x00010734",func="callee4", 33375file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 33376fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8", 33377thread-groups=["i1"],times="1"@}]@} 33378(gdb) 33379@end smallexample 33380 33381 33382@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 33383@node GDB/MI Catchpoint Commands 33384@section @sc{gdb/mi} Catchpoint Commands 33385 33386This section documents @sc{gdb/mi} commands for manipulating 33387catchpoints. 33388 33389@menu 33390* Shared Library GDB/MI Catchpoint Commands:: 33391* Ada Exception GDB/MI Catchpoint Commands:: 33392* C++ Exception GDB/MI Catchpoint Commands:: 33393@end menu 33394 33395@node Shared Library GDB/MI Catchpoint Commands 33396@subsection Shared Library @sc{gdb/mi} Catchpoints 33397 33398@findex -catch-load 33399@subheading The @code{-catch-load} Command 33400 33401@subsubheading Synopsis 33402 33403@smallexample 33404 -catch-load [ -t ] [ -d ] @var{regexp} 33405@end smallexample 33406 33407Add a catchpoint for library load events. If the @samp{-t} option is used, 33408the catchpoint is a temporary one (@pxref{Set Breaks, ,Setting 33409Breakpoints}). If the @samp{-d} option is used, the catchpoint is created 33410in a disabled state. The @samp{regexp} argument is a regular 33411expression used to match the name of the loaded library. 33412 33413 33414@subsubheading @value{GDBN} Command 33415 33416The corresponding @value{GDBN} command is @samp{catch load}. 33417 33418@subsubheading Example 33419 33420@smallexample 33421-catch-load -t foo.so 33422^done,bkpt=@{number="1",type="catchpoint",disp="del",enabled="y", 33423what="load of library matching foo.so",catch-type="load",times="0"@} 33424(gdb) 33425@end smallexample 33426 33427 33428@findex -catch-unload 33429@subheading The @code{-catch-unload} Command 33430 33431@subsubheading Synopsis 33432 33433@smallexample 33434 -catch-unload [ -t ] [ -d ] @var{regexp} 33435@end smallexample 33436 33437Add a catchpoint for library unload events. If the @samp{-t} option is 33438used, the catchpoint is a temporary one (@pxref{Set Breaks, ,Setting 33439Breakpoints}). If the @samp{-d} option is used, the catchpoint is 33440created in a disabled state. The @samp{regexp} argument is a regular 33441expression used to match the name of the unloaded library. 33442 33443@subsubheading @value{GDBN} Command 33444 33445The corresponding @value{GDBN} command is @samp{catch unload}. 33446 33447@subsubheading Example 33448 33449@smallexample 33450-catch-unload -d bar.so 33451^done,bkpt=@{number="2",type="catchpoint",disp="keep",enabled="n", 33452what="load of library matching bar.so",catch-type="unload",times="0"@} 33453(gdb) 33454@end smallexample 33455 33456@node Ada Exception GDB/MI Catchpoint Commands 33457@subsection Ada Exception @sc{gdb/mi} Catchpoints 33458 33459The following @sc{gdb/mi} commands can be used to create catchpoints 33460that stop the execution when Ada exceptions are being raised. 33461 33462@findex -catch-assert 33463@subheading The @code{-catch-assert} Command 33464 33465@subsubheading Synopsis 33466 33467@smallexample 33468 -catch-assert [ -c @var{condition}] [ -d ] [ -t ] 33469@end smallexample 33470 33471Add a catchpoint for failed Ada assertions. 33472 33473The possible optional parameters for this command are: 33474 33475@table @samp 33476@item -c @var{condition} 33477Make the catchpoint conditional on @var{condition}. 33478@item -d 33479Create a disabled catchpoint. 33480@item -t 33481Create a temporary catchpoint. 33482@end table 33483 33484@subsubheading @value{GDBN} Command 33485 33486The corresponding @value{GDBN} command is @samp{catch assert}. 33487 33488@subsubheading Example 33489 33490@smallexample 33491-catch-assert 33492^done,bkptno="5",bkpt=@{number="5",type="breakpoint",disp="keep", 33493enabled="y",addr="0x0000000000404888",what="failed Ada assertions", 33494thread-groups=["i1"],times="0", 33495original-location="__gnat_debug_raise_assert_failure"@} 33496(gdb) 33497@end smallexample 33498 33499@findex -catch-exception 33500@subheading The @code{-catch-exception} Command 33501 33502@subsubheading Synopsis 33503 33504@smallexample 33505 -catch-exception [ -c @var{condition}] [ -d ] [ -e @var{exception-name} ] 33506 [ -t ] [ -u ] 33507@end smallexample 33508 33509Add a catchpoint stopping when Ada exceptions are raised. 33510By default, the command stops the program when any Ada exception 33511gets raised. But it is also possible, by using some of the 33512optional parameters described below, to create more selective 33513catchpoints. 33514 33515The possible optional parameters for this command are: 33516 33517@table @samp 33518@item -c @var{condition} 33519Make the catchpoint conditional on @var{condition}. 33520@item -d 33521Create a disabled catchpoint. 33522@item -e @var{exception-name} 33523Only stop when @var{exception-name} is raised. This option cannot 33524be used combined with @samp{-u}. 33525@item -t 33526Create a temporary catchpoint. 33527@item -u 33528Stop only when an unhandled exception gets raised. This option 33529cannot be used combined with @samp{-e}. 33530@end table 33531 33532@subsubheading @value{GDBN} Command 33533 33534The corresponding @value{GDBN} commands are @samp{catch exception} 33535and @samp{catch exception unhandled}. 33536 33537@subsubheading Example 33538 33539@smallexample 33540-catch-exception -e Program_Error 33541^done,bkptno="4",bkpt=@{number="4",type="breakpoint",disp="keep", 33542enabled="y",addr="0x0000000000404874", 33543what="`Program_Error' Ada exception", thread-groups=["i1"], 33544times="0",original-location="__gnat_debug_raise_exception"@} 33545(gdb) 33546@end smallexample 33547 33548@findex -catch-handlers 33549@subheading The @code{-catch-handlers} Command 33550 33551@subsubheading Synopsis 33552 33553@smallexample 33554 -catch-handlers [ -c @var{condition}] [ -d ] [ -e @var{exception-name} ] 33555 [ -t ] 33556@end smallexample 33557 33558Add a catchpoint stopping when Ada exceptions are handled. 33559By default, the command stops the program when any Ada exception 33560gets handled. But it is also possible, by using some of the 33561optional parameters described below, to create more selective 33562catchpoints. 33563 33564The possible optional parameters for this command are: 33565 33566@table @samp 33567@item -c @var{condition} 33568Make the catchpoint conditional on @var{condition}. 33569@item -d 33570Create a disabled catchpoint. 33571@item -e @var{exception-name} 33572Only stop when @var{exception-name} is handled. 33573@item -t 33574Create a temporary catchpoint. 33575@end table 33576 33577@subsubheading @value{GDBN} Command 33578 33579The corresponding @value{GDBN} command is @samp{catch handlers}. 33580 33581@subsubheading Example 33582 33583@smallexample 33584-catch-handlers -e Constraint_Error 33585^done,bkptno="4",bkpt=@{number="4",type="breakpoint",disp="keep", 33586enabled="y",addr="0x0000000000402f68", 33587what="`Constraint_Error' Ada exception handlers",thread-groups=["i1"], 33588times="0",original-location="__gnat_begin_handler"@} 33589(gdb) 33590@end smallexample 33591 33592@node C++ Exception GDB/MI Catchpoint Commands 33593@subsection C@t{++} Exception @sc{gdb/mi} Catchpoints 33594 33595The following @sc{gdb/mi} commands can be used to create catchpoints 33596that stop the execution when C@t{++} exceptions are being throw, rethrown, 33597or caught. 33598 33599@findex -catch-throw 33600@subheading The @code{-catch-throw} Command 33601 33602@subsubheading Synopsis 33603 33604@smallexample 33605 -catch-throw [ -t ] [ -r @var{regexp}] 33606@end smallexample 33607 33608Stop when the debuggee throws a C@t{++} exception. If @var{regexp} is 33609given, then only exceptions whose type matches the regular expression 33610will be caught. 33611 33612If @samp{-t} is given, then the catchpoint is enabled only for one 33613stop, the catchpoint is automatically deleted after stopping once for 33614the event. 33615 33616@subsubheading @value{GDBN} Command 33617 33618The corresponding @value{GDBN} commands are @samp{catch throw} 33619and @samp{tcatch throw} (@pxref{Set Catchpoints}). 33620 33621@subsubheading Example 33622 33623@smallexample 33624-catch-throw -r exception_type 33625^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y", 33626 what="exception throw",catch-type="throw", 33627 thread-groups=["i1"], 33628 regexp="exception_type",times="0"@} 33629(gdb) 33630-exec-run 33631^running 33632(gdb) 33633~"\n" 33634~"Catchpoint 1 (exception thrown), 0x00007ffff7ae00ed 33635 in __cxa_throw () from /lib64/libstdc++.so.6\n" 33636*stopped,bkptno="1",reason="breakpoint-hit",disp="keep", 33637 frame=@{addr="0x00007ffff7ae00ed",func="__cxa_throw", 33638 args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@}, 33639 thread-id="1",stopped-threads="all",core="6" 33640(gdb) 33641@end smallexample 33642 33643@findex -catch-rethrow 33644@subheading The @code{-catch-rethrow} Command 33645 33646@subsubheading Synopsis 33647 33648@smallexample 33649 -catch-rethrow [ -t ] [ -r @var{regexp}] 33650@end smallexample 33651 33652Stop when a C@t{++} exception is re-thrown. If @var{regexp} is given, 33653then only exceptions whose type matches the regular expression will be 33654caught. 33655 33656If @samp{-t} is given, then the catchpoint is enabled only for one 33657stop, the catchpoint is automatically deleted after the first event is 33658caught. 33659 33660@subsubheading @value{GDBN} Command 33661 33662The corresponding @value{GDBN} commands are @samp{catch rethrow} 33663and @samp{tcatch rethrow} (@pxref{Set Catchpoints}). 33664 33665@subsubheading Example 33666 33667@smallexample 33668-catch-rethrow -r exception_type 33669^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y", 33670 what="exception rethrow",catch-type="rethrow", 33671 thread-groups=["i1"], 33672 regexp="exception_type",times="0"@} 33673(gdb) 33674-exec-run 33675^running 33676(gdb) 33677~"\n" 33678~"Catchpoint 1 (exception rethrown), 0x00007ffff7ae00ed 33679 in __cxa_rethrow () from /lib64/libstdc++.so.6\n" 33680*stopped,bkptno="1",reason="breakpoint-hit",disp="keep", 33681 frame=@{addr="0x00007ffff7ae00ed",func="__cxa_rethrow", 33682 args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@}, 33683 thread-id="1",stopped-threads="all",core="6" 33684(gdb) 33685@end smallexample 33686 33687@findex -catch-catch 33688@subheading The @code{-catch-catch} Command 33689 33690@subsubheading Synopsis 33691 33692@smallexample 33693 -catch-catch [ -t ] [ -r @var{regexp}] 33694@end smallexample 33695 33696Stop when the debuggee catches a C@t{++} exception. If @var{regexp} 33697is given, then only exceptions whose type matches the regular 33698expression will be caught. 33699 33700If @samp{-t} is given, then the catchpoint is enabled only for one 33701stop, the catchpoint is automatically deleted after the first event is 33702caught. 33703 33704@subsubheading @value{GDBN} Command 33705 33706The corresponding @value{GDBN} commands are @samp{catch catch} 33707and @samp{tcatch catch} (@pxref{Set Catchpoints}). 33708 33709@subsubheading Example 33710 33711@smallexample 33712-catch-catch -r exception_type 33713^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y", 33714 what="exception catch",catch-type="catch", 33715 thread-groups=["i1"], 33716 regexp="exception_type",times="0"@} 33717(gdb) 33718-exec-run 33719^running 33720(gdb) 33721~"\n" 33722~"Catchpoint 1 (exception caught), 0x00007ffff7ae00ed 33723 in __cxa_begin_catch () from /lib64/libstdc++.so.6\n" 33724*stopped,bkptno="1",reason="breakpoint-hit",disp="keep", 33725 frame=@{addr="0x00007ffff7ae00ed",func="__cxa_begin_catch", 33726 args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@}, 33727 thread-id="1",stopped-threads="all",core="6" 33728(gdb) 33729@end smallexample 33730 33731@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 33732@node GDB/MI Program Context 33733@section @sc{gdb/mi} Program Context 33734 33735@findex -exec-arguments 33736@subheading The @code{-exec-arguments} Command 33737 33738 33739@subsubheading Synopsis 33740 33741@smallexample 33742 -exec-arguments @var{args} 33743@end smallexample 33744 33745Set the inferior program arguments, to be used in the next 33746@samp{-exec-run}. 33747 33748@subsubheading @value{GDBN} Command 33749 33750The corresponding @value{GDBN} command is @samp{set args}. 33751 33752@subsubheading Example 33753 33754@smallexample 33755(gdb) 33756-exec-arguments -v word 33757^done 33758(gdb) 33759@end smallexample 33760 33761 33762@ignore 33763@findex -exec-show-arguments 33764@subheading The @code{-exec-show-arguments} Command 33765 33766@subsubheading Synopsis 33767 33768@smallexample 33769 -exec-show-arguments 33770@end smallexample 33771 33772Print the arguments of the program. 33773 33774@subsubheading @value{GDBN} Command 33775 33776The corresponding @value{GDBN} command is @samp{show args}. 33777 33778@subsubheading Example 33779N.A. 33780@end ignore 33781 33782 33783@findex -environment-cd 33784@subheading The @code{-environment-cd} Command 33785 33786@subsubheading Synopsis 33787 33788@smallexample 33789 -environment-cd @var{pathdir} 33790@end smallexample 33791 33792Set @value{GDBN}'s working directory. 33793 33794@subsubheading @value{GDBN} Command 33795 33796The corresponding @value{GDBN} command is @samp{cd}. 33797 33798@subsubheading Example 33799 33800@smallexample 33801(gdb) 33802-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb 33803^done 33804(gdb) 33805@end smallexample 33806 33807 33808@findex -environment-directory 33809@subheading The @code{-environment-directory} Command 33810 33811@subsubheading Synopsis 33812 33813@smallexample 33814 -environment-directory [ -r ] [ @var{pathdir} ]+ 33815@end smallexample 33816 33817Add directories @var{pathdir} to beginning of search path for source files. 33818If the @samp{-r} option is used, the search path is reset to the default 33819search path. If directories @var{pathdir} are supplied in addition to the 33820@samp{-r} option, the search path is first reset and then addition 33821occurs as normal. 33822Multiple directories may be specified, separated by blanks. Specifying 33823multiple directories in a single command 33824results in the directories added to the beginning of the 33825search path in the same order they were presented in the command. 33826If blanks are needed as 33827part of a directory name, double-quotes should be used around 33828the name. In the command output, the path will show up separated 33829by the system directory-separator character. The directory-separator 33830character must not be used 33831in any directory name. 33832If no directories are specified, the current search path is displayed. 33833 33834@subsubheading @value{GDBN} Command 33835 33836The corresponding @value{GDBN} command is @samp{dir}. 33837 33838@subsubheading Example 33839 33840@smallexample 33841(gdb) 33842-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb 33843^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" 33844(gdb) 33845-environment-directory "" 33846^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" 33847(gdb) 33848-environment-directory -r /home/jjohnstn/src/gdb /usr/src 33849^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" 33850(gdb) 33851-environment-directory -r 33852^done,source-path="$cdir:$cwd" 33853(gdb) 33854@end smallexample 33855 33856 33857@findex -environment-path 33858@subheading The @code{-environment-path} Command 33859 33860@subsubheading Synopsis 33861 33862@smallexample 33863 -environment-path [ -r ] [ @var{pathdir} ]+ 33864@end smallexample 33865 33866Add directories @var{pathdir} to beginning of search path for object files. 33867If the @samp{-r} option is used, the search path is reset to the original 33868search path that existed at gdb start-up. If directories @var{pathdir} are 33869supplied in addition to the 33870@samp{-r} option, the search path is first reset and then addition 33871occurs as normal. 33872Multiple directories may be specified, separated by blanks. Specifying 33873multiple directories in a single command 33874results in the directories added to the beginning of the 33875search path in the same order they were presented in the command. 33876If blanks are needed as 33877part of a directory name, double-quotes should be used around 33878the name. In the command output, the path will show up separated 33879by the system directory-separator character. The directory-separator 33880character must not be used 33881in any directory name. 33882If no directories are specified, the current path is displayed. 33883 33884 33885@subsubheading @value{GDBN} Command 33886 33887The corresponding @value{GDBN} command is @samp{path}. 33888 33889@subsubheading Example 33890 33891@smallexample 33892(gdb) 33893-environment-path 33894^done,path="/usr/bin" 33895(gdb) 33896-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin 33897^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" 33898(gdb) 33899-environment-path -r /usr/local/bin 33900^done,path="/usr/local/bin:/usr/bin" 33901(gdb) 33902@end smallexample 33903 33904 33905@findex -environment-pwd 33906@subheading The @code{-environment-pwd} Command 33907 33908@subsubheading Synopsis 33909 33910@smallexample 33911 -environment-pwd 33912@end smallexample 33913 33914Show the current working directory. 33915 33916@subsubheading @value{GDBN} Command 33917 33918The corresponding @value{GDBN} command is @samp{pwd}. 33919 33920@subsubheading Example 33921 33922@smallexample 33923(gdb) 33924-environment-pwd 33925^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" 33926(gdb) 33927@end smallexample 33928 33929@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 33930@node GDB/MI Thread Commands 33931@section @sc{gdb/mi} Thread Commands 33932 33933 33934@findex -thread-info 33935@subheading The @code{-thread-info} Command 33936 33937@subsubheading Synopsis 33938 33939@smallexample 33940 -thread-info [ @var{thread-id} ] 33941@end smallexample 33942 33943Reports information about either a specific thread, if the 33944@var{thread-id} parameter is present, or about all threads. 33945@var{thread-id} is the thread's global thread ID. When printing 33946information about all threads, also reports the global ID of the 33947current thread. 33948 33949@subsubheading @value{GDBN} Command 33950 33951The @samp{info thread} command prints the same information 33952about all threads. 33953 33954@subsubheading Result 33955 33956The result contains the following attributes: 33957 33958@table @samp 33959@item threads 33960A list of threads. The format of the elements of the list is described in 33961@ref{GDB/MI Thread Information}. 33962 33963@item current-thread-id 33964The global id of the currently selected thread. This field is omitted if there 33965is no selected thread (for example, when the selected inferior is not running, 33966and therefore has no threads) or if a @var{thread-id} argument was passed to 33967the command. 33968 33969@end table 33970 33971@subsubheading Example 33972 33973@smallexample 33974-thread-info 33975^done,threads=[ 33976@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", 33977 frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall", 33978 args=[]@},state="running"@}, 33979@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", 33980 frame=@{level="0",addr="0x0804891f",func="foo", 33981 args=[@{name="i",value="10"@}], 33982 file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"@}, 33983 state="running"@}], 33984current-thread-id="1" 33985(gdb) 33986@end smallexample 33987 33988@findex -thread-list-ids 33989@subheading The @code{-thread-list-ids} Command 33990 33991@subsubheading Synopsis 33992 33993@smallexample 33994 -thread-list-ids 33995@end smallexample 33996 33997Produces a list of the currently known global @value{GDBN} thread ids. 33998At the end of the list it also prints the total number of such 33999threads. 34000 34001This command is retained for historical reasons, the 34002@code{-thread-info} command should be used instead. 34003 34004@subsubheading @value{GDBN} Command 34005 34006Part of @samp{info threads} supplies the same information. 34007 34008@subsubheading Example 34009 34010@smallexample 34011(gdb) 34012-thread-list-ids 34013^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, 34014current-thread-id="1",number-of-threads="3" 34015(gdb) 34016@end smallexample 34017 34018 34019@findex -thread-select 34020@subheading The @code{-thread-select} Command 34021 34022@subsubheading Synopsis 34023 34024@smallexample 34025 -thread-select @var{thread-id} 34026@end smallexample 34027 34028Make thread with global thread number @var{thread-id} the current 34029thread. It prints the number of the new current thread, and the 34030topmost frame for that thread. 34031 34032This command is deprecated in favor of explicitly using the 34033@samp{--thread} option to each command. 34034 34035@subsubheading @value{GDBN} Command 34036 34037The corresponding @value{GDBN} command is @samp{thread}. 34038 34039@subsubheading Example 34040 34041@smallexample 34042(gdb) 34043-exec-next 34044^running 34045(gdb) 34046*stopped,reason="end-stepping-range",thread-id="2",line="187", 34047file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" 34048(gdb) 34049-thread-list-ids 34050^done, 34051thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, 34052number-of-threads="3" 34053(gdb) 34054-thread-select 3 34055^done,new-thread-id="3", 34056frame=@{level="0",func="vprintf", 34057args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@}, 34058@{name="arg",value="0x2"@}],file="vprintf.c",line="31",arch="i386:x86_64"@} 34059(gdb) 34060@end smallexample 34061 34062@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 34063@node GDB/MI Ada Tasking Commands 34064@section @sc{gdb/mi} Ada Tasking Commands 34065 34066@findex -ada-task-info 34067@subheading The @code{-ada-task-info} Command 34068 34069@subsubheading Synopsis 34070 34071@smallexample 34072 -ada-task-info [ @var{task-id} ] 34073@end smallexample 34074 34075Reports information about either a specific Ada task, if the 34076@var{task-id} parameter is present, or about all Ada tasks. 34077 34078@subsubheading @value{GDBN} Command 34079 34080The @samp{info tasks} command prints the same information 34081about all Ada tasks (@pxref{Ada Tasks}). 34082 34083@subsubheading Result 34084 34085The result is a table of Ada tasks. The following columns are 34086defined for each Ada task: 34087 34088@table @samp 34089@item current 34090This field exists only for the current thread. It has the value @samp{*}. 34091 34092@item id 34093The identifier that @value{GDBN} uses to refer to the Ada task. 34094 34095@item task-id 34096The identifier that the target uses to refer to the Ada task. 34097 34098@item thread-id 34099The global thread identifier of the thread corresponding to the Ada 34100task. 34101 34102This field should always exist, as Ada tasks are always implemented 34103on top of a thread. But if @value{GDBN} cannot find this corresponding 34104thread for any reason, the field is omitted. 34105 34106@item parent-id 34107This field exists only when the task was created by another task. 34108In this case, it provides the ID of the parent task. 34109 34110@item priority 34111The base priority of the task. 34112 34113@item state 34114The current state of the task. For a detailed description of the 34115possible states, see @ref{Ada Tasks}. 34116 34117@item name 34118The name of the task. 34119 34120@end table 34121 34122@subsubheading Example 34123 34124@smallexample 34125-ada-task-info 34126^done,tasks=@{nr_rows="3",nr_cols="8", 34127hdr=[@{width="1",alignment="-1",col_name="current",colhdr=""@}, 34128@{width="3",alignment="1",col_name="id",colhdr="ID"@}, 34129@{width="9",alignment="1",col_name="task-id",colhdr="TID"@}, 34130@{width="4",alignment="1",col_name="thread-id",colhdr=""@}, 34131@{width="4",alignment="1",col_name="parent-id",colhdr="P-ID"@}, 34132@{width="3",alignment="1",col_name="priority",colhdr="Pri"@}, 34133@{width="22",alignment="-1",col_name="state",colhdr="State"@}, 34134@{width="1",alignment="2",col_name="name",colhdr="Name"@}], 34135body=[@{current="*",id="1",task-id=" 644010",thread-id="1",priority="48", 34136state="Child Termination Wait",name="main_task"@}]@} 34137(gdb) 34138@end smallexample 34139 34140@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 34141@node GDB/MI Program Execution 34142@section @sc{gdb/mi} Program Execution 34143 34144These are the asynchronous commands which generate the out-of-band 34145record @samp{*stopped}. Currently @value{GDBN} only really executes 34146asynchronously with remote targets and this interaction is mimicked in 34147other cases. 34148 34149@findex -exec-continue 34150@subheading The @code{-exec-continue} Command 34151 34152@subsubheading Synopsis 34153 34154@smallexample 34155 -exec-continue [--reverse] [--all|--thread-group N] 34156@end smallexample 34157 34158Resumes the execution of the inferior program, which will continue 34159to execute until it reaches a debugger stop event. If the 34160@samp{--reverse} option is specified, execution resumes in reverse until 34161it reaches a stop event. Stop events may include 34162@itemize @bullet 34163@item 34164breakpoints, watchpoints, tracepoints, or catchpoints 34165@item 34166signals or exceptions 34167@item 34168the end of the process (or its beginning under @samp{--reverse}) 34169@item 34170the end or beginning of a replay log if one is being used. 34171@end itemize 34172In all-stop mode (@pxref{All-Stop 34173Mode}), may resume only one thread, or all threads, depending on the 34174value of the @samp{scheduler-locking} variable. If @samp{--all} is 34175specified, all threads (in all inferiors) will be resumed. The @samp{--all} option is 34176ignored in all-stop mode. If the @samp{--thread-group} options is 34177specified, then all threads in that thread group are resumed. 34178 34179@subsubheading @value{GDBN} Command 34180 34181The corresponding @value{GDBN} corresponding is @samp{continue}. 34182 34183@subsubheading Example 34184 34185@smallexample 34186-exec-continue 34187^running 34188(gdb) 34189@@Hello world 34190*stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame=@{ 34191func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", 34192line="13",arch="i386:x86_64"@} 34193(gdb) 34194@end smallexample 34195 34196For a @samp{breakpoint-hit} stopped reason, when the breakpoint 34197encountered has multiple locations, the field @samp{bkptno} is 34198followed by the field @samp{locno}. 34199 34200@smallexample 34201-exec-continue 34202^running 34203(gdb) 34204@@Hello world 34205*stopped,reason="breakpoint-hit",disp="keep",bkptno="2",locno="3",frame=@{ 34206func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", 34207line="13",arch="i386:x86_64"@} 34208(gdb) 34209@end smallexample 34210 34211@findex -exec-finish 34212@subheading The @code{-exec-finish} Command 34213 34214@subsubheading Synopsis 34215 34216@smallexample 34217 -exec-finish [--reverse] 34218@end smallexample 34219 34220Resumes the execution of the inferior program until the current 34221function is exited. Displays the results returned by the function. 34222If the @samp{--reverse} option is specified, resumes the reverse 34223execution of the inferior program until the point where current 34224function was called. 34225 34226@subsubheading @value{GDBN} Command 34227 34228The corresponding @value{GDBN} command is @samp{finish}. 34229 34230@subsubheading Example 34231 34232Function returning @code{void}. 34233 34234@smallexample 34235-exec-finish 34236^running 34237(gdb) 34238@@hello from foo 34239*stopped,reason="function-finished",frame=@{func="main",args=[], 34240file="hello.c",fullname="/home/foo/bar/hello.c",line="7",arch="i386:x86_64"@} 34241(gdb) 34242@end smallexample 34243 34244Function returning other than @code{void}. The name of the internal 34245@value{GDBN} variable storing the result is printed, together with the 34246value itself. 34247 34248@smallexample 34249-exec-finish 34250^running 34251(gdb) 34252*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo", 34253args=[@{name="a",value="1"],@{name="b",value="9"@}@}, 34254file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 34255arch="i386:x86_64"@}, 34256gdb-result-var="$1",return-value="0" 34257(gdb) 34258@end smallexample 34259 34260 34261@findex -exec-interrupt 34262@subheading The @code{-exec-interrupt} Command 34263 34264@subsubheading Synopsis 34265 34266@smallexample 34267 -exec-interrupt [--all|--thread-group N] 34268@end smallexample 34269 34270Interrupts the background execution of the target. Note how the token 34271associated with the stop message is the one for the execution command 34272that has been interrupted. The token for the interrupt itself only 34273appears in the @samp{^done} output. If the user is trying to 34274interrupt a non-running program, an error message will be printed. 34275 34276Note that when asynchronous execution is enabled, this command is 34277asynchronous just like other execution commands. That is, first the 34278@samp{^done} response will be printed, and the target stop will be 34279reported after that using the @samp{*stopped} notification. 34280 34281In non-stop mode, only the context thread is interrupted by default. 34282All threads (in all inferiors) will be interrupted if the 34283@samp{--all} option is specified. If the @samp{--thread-group} 34284option is specified, all threads in that group will be interrupted. 34285 34286@subsubheading @value{GDBN} Command 34287 34288The corresponding @value{GDBN} command is @samp{interrupt}. 34289 34290@subsubheading Example 34291 34292@smallexample 34293(gdb) 34294111-exec-continue 34295111^running 34296 34297(gdb) 34298222-exec-interrupt 34299222^done 34300(gdb) 34301111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", 34302frame=@{addr="0x00010140",func="foo",args=[],file="try.c", 34303fullname="/home/foo/bar/try.c",line="13",arch="i386:x86_64"@} 34304(gdb) 34305 34306(gdb) 34307-exec-interrupt 34308^error,msg="mi_cmd_exec_interrupt: Inferior not executing." 34309(gdb) 34310@end smallexample 34311 34312@findex -exec-jump 34313@subheading The @code{-exec-jump} Command 34314 34315@subsubheading Synopsis 34316 34317@smallexample 34318 -exec-jump @var{locspec} 34319@end smallexample 34320 34321Resumes execution of the inferior program at the address to 34322which @var{locspec} resolves. @xref{Location Specifications}, 34323for a description of the different forms of @var{locspec}. 34324 34325@subsubheading @value{GDBN} Command 34326 34327The corresponding @value{GDBN} command is @samp{jump}. 34328 34329@subsubheading Example 34330 34331@smallexample 34332-exec-jump foo.c:10 34333*running,thread-id="all" 34334^running 34335@end smallexample 34336 34337 34338@findex -exec-next 34339@subheading The @code{-exec-next} Command 34340 34341@subsubheading Synopsis 34342 34343@smallexample 34344 -exec-next [--reverse] 34345@end smallexample 34346 34347Resumes execution of the inferior program, stopping when the beginning 34348of the next source line is reached. 34349 34350If the @samp{--reverse} option is specified, resumes reverse execution 34351of the inferior program, stopping at the beginning of the previous 34352source line. If you issue this command on the first line of a 34353function, it will take you back to the caller of that function, to the 34354source line where the function was called. 34355 34356 34357@subsubheading @value{GDBN} Command 34358 34359The corresponding @value{GDBN} command is @samp{next}. 34360 34361@subsubheading Example 34362 34363@smallexample 34364-exec-next 34365^running 34366(gdb) 34367*stopped,reason="end-stepping-range",line="8",file="hello.c" 34368(gdb) 34369@end smallexample 34370 34371 34372@findex -exec-next-instruction 34373@subheading The @code{-exec-next-instruction} Command 34374 34375@subsubheading Synopsis 34376 34377@smallexample 34378 -exec-next-instruction [--reverse] 34379@end smallexample 34380 34381Executes one machine instruction. If the instruction is a function 34382call, continues until the function returns. If the program stops at an 34383instruction in the middle of a source line, the address will be 34384printed as well. 34385 34386If the @samp{--reverse} option is specified, resumes reverse execution 34387of the inferior program, stopping at the previous instruction. If the 34388previously executed instruction was a return from another function, 34389it will continue to execute in reverse until the call to that function 34390(from the current stack frame) is reached. 34391 34392@subsubheading @value{GDBN} Command 34393 34394The corresponding @value{GDBN} command is @samp{nexti}. 34395 34396@subsubheading Example 34397 34398@smallexample 34399(gdb) 34400-exec-next-instruction 34401^running 34402 34403(gdb) 34404*stopped,reason="end-stepping-range", 34405addr="0x000100d4",line="5",file="hello.c" 34406(gdb) 34407@end smallexample 34408 34409 34410@findex -exec-return 34411@subheading The @code{-exec-return} Command 34412 34413@subsubheading Synopsis 34414 34415@smallexample 34416 -exec-return 34417@end smallexample 34418 34419Makes current function return immediately. Doesn't execute the inferior. 34420Displays the new current frame. 34421 34422@subsubheading @value{GDBN} Command 34423 34424The corresponding @value{GDBN} command is @samp{return}. 34425 34426@subsubheading Example 34427 34428@smallexample 34429(gdb) 34430200-break-insert callee4 34431200^done,bkpt=@{number="1",addr="0x00010734", 34432file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} 34433(gdb) 34434000-exec-run 34435000^running 34436(gdb) 34437000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", 34438frame=@{func="callee4",args=[], 34439file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 34440fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8", 34441arch="i386:x86_64"@} 34442(gdb) 34443205-break-delete 34444205^done 34445(gdb) 34446111-exec-return 34447111^done,frame=@{level="0",func="callee3", 34448args=[@{name="strarg", 34449value="0x11940 \"A string argument.\""@}], 34450file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 34451fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18", 34452arch="i386:x86_64"@} 34453(gdb) 34454@end smallexample 34455 34456 34457@findex -exec-run 34458@subheading The @code{-exec-run} Command 34459 34460@subsubheading Synopsis 34461 34462@smallexample 34463 -exec-run [ --all | --thread-group N ] [ --start ] 34464@end smallexample 34465 34466Starts execution of the inferior from the beginning. The inferior 34467executes until either a breakpoint is encountered or the program 34468exits. In the latter case the output will include an exit code, if 34469the program has exited exceptionally. 34470 34471When neither the @samp{--all} nor the @samp{--thread-group} option 34472is specified, the current inferior is started. If the 34473@samp{--thread-group} option is specified, it should refer to a thread 34474group of type @samp{process}, and that thread group will be started. 34475If the @samp{--all} option is specified, then all inferiors will be started. 34476 34477Using the @samp{--start} option instructs the debugger to stop 34478the execution at the start of the inferior's main subprogram, 34479following the same behavior as the @code{start} command 34480(@pxref{Starting}). 34481 34482@subsubheading @value{GDBN} Command 34483 34484The corresponding @value{GDBN} command is @samp{run}. 34485 34486@subsubheading Examples 34487 34488@smallexample 34489(gdb) 34490-break-insert main 34491^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} 34492(gdb) 34493-exec-run 34494^running 34495(gdb) 34496*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", 34497frame=@{func="main",args=[],file="recursive2.c", 34498fullname="/home/foo/bar/recursive2.c",line="4",arch="i386:x86_64"@} 34499(gdb) 34500@end smallexample 34501 34502@noindent 34503Program exited normally: 34504 34505@smallexample 34506(gdb) 34507-exec-run 34508^running 34509(gdb) 34510x = 55 34511*stopped,reason="exited-normally" 34512(gdb) 34513@end smallexample 34514 34515@noindent 34516Program exited exceptionally: 34517 34518@smallexample 34519(gdb) 34520-exec-run 34521^running 34522(gdb) 34523x = 55 34524*stopped,reason="exited",exit-code="01" 34525(gdb) 34526@end smallexample 34527 34528Another way the program can terminate is if it receives a signal such as 34529@code{SIGINT}. In this case, @sc{gdb/mi} displays this: 34530 34531@smallexample 34532(gdb) 34533*stopped,reason="exited-signalled",signal-name="SIGINT", 34534signal-meaning="Interrupt" 34535@end smallexample 34536 34537 34538@c @subheading -exec-signal 34539 34540 34541@findex -exec-step 34542@subheading The @code{-exec-step} Command 34543 34544@subsubheading Synopsis 34545 34546@smallexample 34547 -exec-step [--reverse] 34548@end smallexample 34549 34550Resumes execution of the inferior program, stopping when the beginning 34551of the next source line is reached, if the next source line is not a 34552function call. If it is, stop at the first instruction of the called 34553function. If the @samp{--reverse} option is specified, resumes reverse 34554execution of the inferior program, stopping at the beginning of the 34555previously executed source line. 34556 34557@subsubheading @value{GDBN} Command 34558 34559The corresponding @value{GDBN} command is @samp{step}. 34560 34561@subsubheading Example 34562 34563Stepping into a function: 34564 34565@smallexample 34566-exec-step 34567^running 34568(gdb) 34569*stopped,reason="end-stepping-range", 34570frame=@{func="foo",args=[@{name="a",value="10"@}, 34571@{name="b",value="0"@}],file="recursive2.c", 34572fullname="/home/foo/bar/recursive2.c",line="11",arch="i386:x86_64"@} 34573(gdb) 34574@end smallexample 34575 34576Regular stepping: 34577 34578@smallexample 34579-exec-step 34580^running 34581(gdb) 34582*stopped,reason="end-stepping-range",line="14",file="recursive2.c" 34583(gdb) 34584@end smallexample 34585 34586 34587@findex -exec-step-instruction 34588@subheading The @code{-exec-step-instruction} Command 34589 34590@subsubheading Synopsis 34591 34592@smallexample 34593 -exec-step-instruction [--reverse] 34594@end smallexample 34595 34596Resumes the inferior which executes one machine instruction. If the 34597@samp{--reverse} option is specified, resumes reverse execution of the 34598inferior program, stopping at the previously executed instruction. 34599The output, once @value{GDBN} has stopped, will vary depending on 34600whether we have stopped in the middle of a source line or not. In the 34601former case, the address at which the program stopped will be printed 34602as well. 34603 34604@subsubheading @value{GDBN} Command 34605 34606The corresponding @value{GDBN} command is @samp{stepi}. 34607 34608@subsubheading Example 34609 34610@smallexample 34611(gdb) 34612-exec-step-instruction 34613^running 34614 34615(gdb) 34616*stopped,reason="end-stepping-range", 34617frame=@{func="foo",args=[],file="try.c", 34618fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"@} 34619(gdb) 34620-exec-step-instruction 34621^running 34622 34623(gdb) 34624*stopped,reason="end-stepping-range", 34625frame=@{addr="0x000100f4",func="foo",args=[],file="try.c", 34626fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"@} 34627(gdb) 34628@end smallexample 34629 34630 34631@findex -exec-until 34632@subheading The @code{-exec-until} Command 34633 34634@subsubheading Synopsis 34635 34636@smallexample 34637 -exec-until [ @var{locspec} ] 34638@end smallexample 34639 34640Executes the inferior until it reaches the address to which 34641@var{locspec} resolves. If there is no argument, the inferior 34642executes until it reaches a source line greater than the current one. 34643The reason for stopping in this case will be @samp{location-reached}. 34644 34645@subsubheading @value{GDBN} Command 34646 34647The corresponding @value{GDBN} command is @samp{until}. 34648 34649@subsubheading Example 34650 34651@smallexample 34652(gdb) 34653-exec-until recursive2.c:6 34654^running 34655(gdb) 34656x = 55 34657*stopped,reason="location-reached",frame=@{func="main",args=[], 34658file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6", 34659arch="i386:x86_64"@} 34660(gdb) 34661@end smallexample 34662 34663@ignore 34664@subheading -file-clear 34665Is this going away???? 34666@end ignore 34667 34668@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 34669@node GDB/MI Stack Manipulation 34670@section @sc{gdb/mi} Stack Manipulation Commands 34671 34672@findex -enable-frame-filters 34673@subheading The @code{-enable-frame-filters} Command 34674 34675@smallexample 34676-enable-frame-filters 34677@end smallexample 34678 34679@value{GDBN} allows Python-based frame filters to affect the output of 34680the MI commands relating to stack traces. As there is no way to 34681implement this in a fully backward-compatible way, a front end must 34682request that this functionality be enabled. 34683 34684Once enabled, this feature cannot be disabled. 34685 34686Note that if Python support has not been compiled into @value{GDBN}, 34687this command will still succeed (and do nothing). 34688 34689@findex -stack-info-frame 34690@subheading The @code{-stack-info-frame} Command 34691 34692@subsubheading Synopsis 34693 34694@smallexample 34695 -stack-info-frame 34696@end smallexample 34697 34698Get info on the selected frame. 34699 34700@subsubheading @value{GDBN} Command 34701 34702The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame} 34703(without arguments). 34704 34705@subsubheading Example 34706 34707@smallexample 34708(gdb) 34709-stack-info-frame 34710^done,frame=@{level="1",addr="0x0001076c",func="callee3", 34711file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 34712fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17", 34713arch="i386:x86_64"@} 34714(gdb) 34715@end smallexample 34716 34717@findex -stack-info-depth 34718@subheading The @code{-stack-info-depth} Command 34719 34720@subsubheading Synopsis 34721 34722@smallexample 34723 -stack-info-depth [ @var{max-depth} ] 34724@end smallexample 34725 34726Return the depth of the stack. If the integer argument @var{max-depth} 34727is specified, do not count beyond @var{max-depth} frames. 34728 34729@subsubheading @value{GDBN} Command 34730 34731There's no equivalent @value{GDBN} command. 34732 34733@subsubheading Example 34734 34735For a stack with frame levels 0 through 11: 34736 34737@smallexample 34738(gdb) 34739-stack-info-depth 34740^done,depth="12" 34741(gdb) 34742-stack-info-depth 4 34743^done,depth="4" 34744(gdb) 34745-stack-info-depth 12 34746^done,depth="12" 34747(gdb) 34748-stack-info-depth 11 34749^done,depth="11" 34750(gdb) 34751-stack-info-depth 13 34752^done,depth="12" 34753(gdb) 34754@end smallexample 34755 34756@anchor{-stack-list-arguments} 34757@findex -stack-list-arguments 34758@subheading The @code{-stack-list-arguments} Command 34759 34760@subsubheading Synopsis 34761 34762@smallexample 34763 -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values} 34764 [ @var{low-frame} @var{high-frame} ] 34765@end smallexample 34766 34767Display a list of the arguments for the frames between @var{low-frame} 34768and @var{high-frame} (inclusive). If @var{low-frame} and 34769@var{high-frame} are not provided, list the arguments for the whole 34770call stack. If the two arguments are equal, show the single frame 34771at the corresponding level. It is an error if @var{low-frame} is 34772larger than the actual number of frames. On the other hand, 34773@var{high-frame} may be larger than the actual number of frames, in 34774which case only existing frames will be returned. 34775 34776If @var{print-values} is 0 or @code{--no-values}, print only the names of 34777the variables; if it is 1 or @code{--all-values}, print also their 34778values; and if it is 2 or @code{--simple-values}, print the name, 34779type and value for simple data types, and the name and type for arrays, 34780structures and unions. If the option @code{--no-frame-filters} is 34781supplied, then Python frame filters will not be executed. 34782 34783If the @code{--skip-unavailable} option is specified, arguments that 34784are not available are not listed. Partially available arguments 34785are still displayed, however. 34786 34787Use of this command to obtain arguments in a single frame is 34788deprecated in favor of the @samp{-stack-list-variables} command. 34789 34790@subsubheading @value{GDBN} Command 34791 34792@value{GDBN} does not have an equivalent command. @code{gdbtk} has a 34793@samp{gdb_get_args} command which partially overlaps with the 34794functionality of @samp{-stack-list-arguments}. 34795 34796@subsubheading Example 34797 34798@smallexample 34799(gdb) 34800-stack-list-frames 34801^done, 34802stack=[ 34803frame=@{level="0",addr="0x00010734",func="callee4", 34804file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 34805fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8", 34806arch="i386:x86_64"@}, 34807frame=@{level="1",addr="0x0001076c",func="callee3", 34808file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 34809fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17", 34810arch="i386:x86_64"@}, 34811frame=@{level="2",addr="0x0001078c",func="callee2", 34812file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 34813fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22", 34814arch="i386:x86_64"@}, 34815frame=@{level="3",addr="0x000107b4",func="callee1", 34816file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 34817fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27", 34818arch="i386:x86_64"@}, 34819frame=@{level="4",addr="0x000107e0",func="main", 34820file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 34821fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32", 34822arch="i386:x86_64"@}] 34823(gdb) 34824-stack-list-arguments 0 34825^done, 34826stack-args=[ 34827frame=@{level="0",args=[]@}, 34828frame=@{level="1",args=[name="strarg"]@}, 34829frame=@{level="2",args=[name="intarg",name="strarg"]@}, 34830frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@}, 34831frame=@{level="4",args=[]@}] 34832(gdb) 34833-stack-list-arguments 1 34834^done, 34835stack-args=[ 34836frame=@{level="0",args=[]@}, 34837frame=@{level="1", 34838 args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, 34839frame=@{level="2",args=[ 34840@{name="intarg",value="2"@}, 34841@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, 34842@{frame=@{level="3",args=[ 34843@{name="intarg",value="2"@}, 34844@{name="strarg",value="0x11940 \"A string argument.\""@}, 34845@{name="fltarg",value="3.5"@}]@}, 34846frame=@{level="4",args=[]@}] 34847(gdb) 34848-stack-list-arguments 0 2 2 34849^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}] 34850(gdb) 34851-stack-list-arguments 1 2 2 34852^done,stack-args=[frame=@{level="2", 34853args=[@{name="intarg",value="2"@}, 34854@{name="strarg",value="0x11940 \"A string argument.\""@}]@}] 34855(gdb) 34856@end smallexample 34857 34858@c @subheading -stack-list-exception-handlers 34859 34860 34861@anchor{-stack-list-frames} 34862@findex -stack-list-frames 34863@subheading The @code{-stack-list-frames} Command 34864 34865@subsubheading Synopsis 34866 34867@smallexample 34868 -stack-list-frames [ --no-frame-filters @var{low-frame} @var{high-frame} ] 34869@end smallexample 34870 34871List the frames currently on the stack. For each frame it displays the 34872following info: 34873 34874@table @samp 34875@item @var{level} 34876The frame number, 0 being the topmost frame, i.e., the innermost function. 34877@item @var{addr} 34878The @code{$pc} value for that frame. 34879@item @var{func} 34880Function name. 34881@item @var{file} 34882File name of the source file where the function lives. 34883@item @var{fullname} 34884The full file name of the source file where the function lives. 34885@item @var{line} 34886Line number corresponding to the @code{$pc}. 34887@item @var{from} 34888The shared library where this function is defined. This is only given 34889if the frame's function is not known. 34890@item @var{arch} 34891Frame's architecture. 34892@end table 34893 34894If invoked without arguments, this command prints a backtrace for the 34895whole stack. If given two integer arguments, it shows the frames whose 34896levels are between the two arguments (inclusive). If the two arguments 34897are equal, it shows the single frame at the corresponding level. It is 34898an error if @var{low-frame} is larger than the actual number of 34899frames. On the other hand, @var{high-frame} may be larger than the 34900actual number of frames, in which case only existing frames will be 34901returned. If the option @code{--no-frame-filters} is supplied, then 34902Python frame filters will not be executed. 34903 34904@subsubheading @value{GDBN} Command 34905 34906The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}. 34907 34908@subsubheading Example 34909 34910Full stack backtrace: 34911 34912@smallexample 34913(gdb) 34914-stack-list-frames 34915^done,stack= 34916[frame=@{level="0",addr="0x0001076c",func="foo", 34917 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11", 34918 arch="i386:x86_64"@}, 34919frame=@{level="1",addr="0x000107a4",func="foo", 34920 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 34921 arch="i386:x86_64"@}, 34922frame=@{level="2",addr="0x000107a4",func="foo", 34923 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 34924 arch="i386:x86_64"@}, 34925frame=@{level="3",addr="0x000107a4",func="foo", 34926 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 34927 arch="i386:x86_64"@}, 34928frame=@{level="4",addr="0x000107a4",func="foo", 34929 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 34930 arch="i386:x86_64"@}, 34931frame=@{level="5",addr="0x000107a4",func="foo", 34932 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 34933 arch="i386:x86_64"@}, 34934frame=@{level="6",addr="0x000107a4",func="foo", 34935 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 34936 arch="i386:x86_64"@}, 34937frame=@{level="7",addr="0x000107a4",func="foo", 34938 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 34939 arch="i386:x86_64"@}, 34940frame=@{level="8",addr="0x000107a4",func="foo", 34941 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 34942 arch="i386:x86_64"@}, 34943frame=@{level="9",addr="0x000107a4",func="foo", 34944 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 34945 arch="i386:x86_64"@}, 34946frame=@{level="10",addr="0x000107a4",func="foo", 34947 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 34948 arch="i386:x86_64"@}, 34949frame=@{level="11",addr="0x00010738",func="main", 34950 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4", 34951 arch="i386:x86_64"@}] 34952(gdb) 34953@end smallexample 34954 34955Show frames between @var{low_frame} and @var{high_frame}: 34956 34957@smallexample 34958(gdb) 34959-stack-list-frames 3 5 34960^done,stack= 34961[frame=@{level="3",addr="0x000107a4",func="foo", 34962 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 34963 arch="i386:x86_64"@}, 34964frame=@{level="4",addr="0x000107a4",func="foo", 34965 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 34966 arch="i386:x86_64"@}, 34967frame=@{level="5",addr="0x000107a4",func="foo", 34968 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 34969 arch="i386:x86_64"@}] 34970(gdb) 34971@end smallexample 34972 34973Show a single frame: 34974 34975@smallexample 34976(gdb) 34977-stack-list-frames 3 3 34978^done,stack= 34979[frame=@{level="3",addr="0x000107a4",func="foo", 34980 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", 34981 arch="i386:x86_64"@}] 34982(gdb) 34983@end smallexample 34984 34985 34986@findex -stack-list-locals 34987@anchor{-stack-list-locals} 34988@subheading The @code{-stack-list-locals} Command 34989 34990@subsubheading Synopsis 34991 34992@smallexample 34993 -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values} 34994@end smallexample 34995 34996Display the local variable names for the selected frame. If 34997@var{print-values} is 0 or @code{--no-values}, print only the names of 34998the variables; if it is 1 or @code{--all-values}, print also their 34999values; and if it is 2 or @code{--simple-values}, print the name, 35000type and value for simple data types, and the name and type for arrays, 35001structures and unions. In this last case, a frontend can immediately 35002display the value of simple data types and create variable objects for 35003other data types when the user wishes to explore their values in 35004more detail. If the option @code{--no-frame-filters} is supplied, then 35005Python frame filters will not be executed. 35006 35007If the @code{--skip-unavailable} option is specified, local variables 35008that are not available are not listed. Partially available local 35009variables are still displayed, however. 35010 35011This command is deprecated in favor of the 35012@samp{-stack-list-variables} command. 35013 35014@subsubheading @value{GDBN} Command 35015 35016@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}. 35017 35018@subsubheading Example 35019 35020@smallexample 35021(gdb) 35022-stack-list-locals 0 35023^done,locals=[name="A",name="B",name="C"] 35024(gdb) 35025-stack-list-locals --all-values 35026^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@}, 35027 @{name="C",value="@{1, 2, 3@}"@}] 35028-stack-list-locals --simple-values 35029^done,locals=[@{name="A",type="int",value="1"@}, 35030 @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}] 35031(gdb) 35032@end smallexample 35033 35034@anchor{-stack-list-variables} 35035@findex -stack-list-variables 35036@subheading The @code{-stack-list-variables} Command 35037 35038@subsubheading Synopsis 35039 35040@smallexample 35041 -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values} 35042@end smallexample 35043 35044Display the names of local variables and function arguments for the selected frame. If 35045@var{print-values} is 0 or @code{--no-values}, print only the names of 35046the variables; if it is 1 or @code{--all-values}, print also their 35047values; and if it is 2 or @code{--simple-values}, print the name, 35048type and value for simple data types, and the name and type for arrays, 35049structures and unions. If the option @code{--no-frame-filters} is 35050supplied, then Python frame filters will not be executed. 35051 35052If the @code{--skip-unavailable} option is specified, local variables 35053and arguments that are not available are not listed. Partially 35054available arguments and local variables are still displayed, however. 35055 35056@subsubheading Example 35057 35058@smallexample 35059(gdb) 35060-stack-list-variables --thread 1 --frame 0 --all-values 35061^done,variables=[@{name="x",value="11"@},@{name="s",value="@{a = 1, b = 2@}"@}] 35062(gdb) 35063@end smallexample 35064 35065 35066@findex -stack-select-frame 35067@subheading The @code{-stack-select-frame} Command 35068 35069@subsubheading Synopsis 35070 35071@smallexample 35072 -stack-select-frame @var{framenum} 35073@end smallexample 35074 35075Change the selected frame. Select a different frame @var{framenum} on 35076the stack. 35077 35078This command in deprecated in favor of passing the @samp{--frame} 35079option to every command. 35080 35081@subsubheading @value{GDBN} Command 35082 35083The corresponding @value{GDBN} commands are @samp{frame}, @samp{up}, 35084@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}. 35085 35086@subsubheading Example 35087 35088@smallexample 35089(gdb) 35090-stack-select-frame 2 35091^done 35092(gdb) 35093@end smallexample 35094 35095@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 35096@node GDB/MI Variable Objects 35097@section @sc{gdb/mi} Variable Objects 35098 35099@ignore 35100 35101@subheading Motivation for Variable Objects in @sc{gdb/mi} 35102 35103For the implementation of a variable debugger window (locals, watched 35104expressions, etc.), we are proposing the adaptation of the existing code 35105used by @code{Insight}. 35106 35107The two main reasons for that are: 35108 35109@enumerate 1 35110@item 35111It has been proven in practice (it is already on its second generation). 35112 35113@item 35114It will shorten development time (needless to say how important it is 35115now). 35116@end enumerate 35117 35118The original interface was designed to be used by Tcl code, so it was 35119slightly changed so it could be used through @sc{gdb/mi}. This section 35120describes the @sc{gdb/mi} operations that will be available and gives some 35121hints about their use. 35122 35123@emph{Note}: In addition to the set of operations described here, we 35124expect the @sc{gui} implementation of a variable window to require, at 35125least, the following operations: 35126 35127@itemize @bullet 35128@item @code{-gdb-show} @code{output-radix} 35129@item @code{-stack-list-arguments} 35130@item @code{-stack-list-locals} 35131@item @code{-stack-select-frame} 35132@end itemize 35133 35134@end ignore 35135 35136@subheading Introduction to Variable Objects 35137 35138@cindex variable objects in @sc{gdb/mi} 35139 35140Variable objects are "object-oriented" MI interface for examining and 35141changing values of expressions. Unlike some other MI interfaces that 35142work with expressions, variable objects are specifically designed for 35143simple and efficient presentation in the frontend. A variable object 35144is identified by string name. When a variable object is created, the 35145frontend specifies the expression for that variable object. The 35146expression can be a simple variable, or it can be an arbitrary complex 35147expression, and can even involve CPU registers. After creating a 35148variable object, the frontend can invoke other variable object 35149operations---for example to obtain or change the value of a variable 35150object, or to change display format. 35151 35152Variable objects have hierarchical tree structure. Any variable object 35153that corresponds to a composite type, such as structure in C, has 35154a number of child variable objects, for example corresponding to each 35155element of a structure. A child variable object can itself have 35156children, recursively. Recursion ends when we reach 35157leaf variable objects, which always have built-in types. Child variable 35158objects are created only by explicit request, so if a frontend 35159is not interested in the children of a particular variable object, no 35160child will be created. 35161 35162For a leaf variable object it is possible to obtain its value as a 35163string, or set the value from a string. String value can be also 35164obtained for a non-leaf variable object, but it's generally a string 35165that only indicates the type of the object, and does not list its 35166contents. Assignment to a non-leaf variable object is not allowed. 35167 35168A frontend does not need to read the values of all variable objects each time 35169the program stops. Instead, MI provides an update command that lists all 35170variable objects whose values has changed since the last update 35171operation. This considerably reduces the amount of data that must 35172be transferred to the frontend. As noted above, children variable 35173objects are created on demand, and only leaf variable objects have a 35174real value. As result, gdb will read target memory only for leaf 35175variables that frontend has created. 35176 35177The automatic update is not always desirable. For example, a frontend 35178might want to keep a value of some expression for future reference, 35179and never update it. For another example, fetching memory is 35180relatively slow for embedded targets, so a frontend might want 35181to disable automatic update for the variables that are either not 35182visible on the screen, or ``closed''. This is possible using so 35183called ``frozen variable objects''. Such variable objects are never 35184implicitly updated. 35185 35186Variable objects can be either @dfn{fixed} or @dfn{floating}. For the 35187fixed variable object, the expression is parsed when the variable 35188object is created, including associating identifiers to specific 35189variables. The meaning of expression never changes. For a floating 35190variable object the values of variables whose names appear in the 35191expressions are re-evaluated every time in the context of the current 35192frame. Consider this example: 35193 35194@smallexample 35195void do_work(...) 35196@{ 35197 struct work_state state; 35198 35199 if (...) 35200 do_work(...); 35201@} 35202@end smallexample 35203 35204If a fixed variable object for the @code{state} variable is created in 35205this function, and we enter the recursive call, the variable 35206object will report the value of @code{state} in the top-level 35207@code{do_work} invocation. On the other hand, a floating variable 35208object will report the value of @code{state} in the current frame. 35209 35210If an expression specified when creating a fixed variable object 35211refers to a local variable, the variable object becomes bound to the 35212thread and frame in which the variable object is created. When such 35213variable object is updated, @value{GDBN} makes sure that the 35214thread/frame combination the variable object is bound to still exists, 35215and re-evaluates the variable object in context of that thread/frame. 35216 35217The following is the complete set of @sc{gdb/mi} operations defined to 35218access this functionality: 35219 35220@multitable @columnfractions .4 .6 35221@item @strong{Operation} 35222@tab @strong{Description} 35223 35224@item @code{-enable-pretty-printing} 35225@tab enable Python-based pretty-printing 35226@item @code{-var-create} 35227@tab create a variable object 35228@item @code{-var-delete} 35229@tab delete the variable object and/or its children 35230@item @code{-var-set-format} 35231@tab set the display format of this variable 35232@item @code{-var-show-format} 35233@tab show the display format of this variable 35234@item @code{-var-info-num-children} 35235@tab tells how many children this object has 35236@item @code{-var-list-children} 35237@tab return a list of the object's children 35238@item @code{-var-info-type} 35239@tab show the type of this variable object 35240@item @code{-var-info-expression} 35241@tab print parent-relative expression that this variable object represents 35242@item @code{-var-info-path-expression} 35243@tab print full expression that this variable object represents 35244@item @code{-var-show-attributes} 35245@tab is this variable editable? does it exist here? 35246@item @code{-var-evaluate-expression} 35247@tab get the value of this variable 35248@item @code{-var-assign} 35249@tab set the value of this variable 35250@item @code{-var-update} 35251@tab update the variable and its children 35252@item @code{-var-set-frozen} 35253@tab set frozenness attribute 35254@item @code{-var-set-update-range} 35255@tab set range of children to display on update 35256@end multitable 35257 35258In the next subsection we describe each operation in detail and suggest 35259how it can be used. 35260 35261@subheading Description And Use of Operations on Variable Objects 35262 35263@findex -enable-pretty-printing 35264@subheading The @code{-enable-pretty-printing} Command 35265 35266@smallexample 35267-enable-pretty-printing 35268@end smallexample 35269 35270@value{GDBN} allows Python-based visualizers to affect the output of the 35271MI variable object commands. However, because there was no way to 35272implement this in a fully backward-compatible way, a front end must 35273request that this functionality be enabled. 35274 35275Once enabled, this feature cannot be disabled. 35276 35277Note that if Python support has not been compiled into @value{GDBN}, 35278this command will still succeed (and do nothing). 35279 35280@findex -var-create 35281@subheading The @code{-var-create} Command 35282 35283@subsubheading Synopsis 35284 35285@smallexample 35286 -var-create @{@var{name} | "-"@} 35287 @{@var{frame-addr} | "*" | "@@"@} @var{expression} 35288@end smallexample 35289 35290This operation creates a variable object, which allows the monitoring of 35291a variable, the result of an expression, a memory cell or a CPU 35292register. 35293 35294The @var{name} parameter is the string by which the object can be 35295referenced. It must be unique. If @samp{-} is specified, the varobj 35296system will generate a string ``varNNNNNN'' automatically. It will be 35297unique provided that one does not specify @var{name} of that format. 35298The command fails if a duplicate name is found. 35299 35300The frame under which the expression should be evaluated can be 35301specified by @var{frame-addr}. A @samp{*} indicates that the current 35302frame should be used. A @samp{@@} indicates that a floating variable 35303object must be created. 35304 35305@var{expression} is any expression valid on the current language set (must not 35306begin with a @samp{*}), or one of the following: 35307 35308@itemize @bullet 35309@item 35310@samp{*@var{addr}}, where @var{addr} is the address of a memory cell 35311 35312@item 35313@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD) 35314 35315@item 35316@samp{$@var{regname}} --- a CPU register name 35317@end itemize 35318 35319@cindex dynamic varobj 35320A varobj's contents may be provided by a Python-based pretty-printer. In this 35321case the varobj is known as a @dfn{dynamic varobj}. Dynamic varobjs 35322have slightly different semantics in some cases. If the 35323@code{-enable-pretty-printing} command is not sent, then @value{GDBN} 35324will never create a dynamic varobj. This ensures backward 35325compatibility for existing clients. 35326 35327@subsubheading Result 35328 35329This operation returns attributes of the newly-created varobj. These 35330are: 35331 35332@table @samp 35333@item name 35334The name of the varobj. 35335 35336@item numchild 35337The number of children of the varobj. This number is not necessarily 35338reliable for a dynamic varobj. Instead, you must examine the 35339@samp{has_more} attribute. 35340 35341@item value 35342The varobj's scalar value. For a varobj whose type is some sort of 35343aggregate (e.g., a @code{struct}), this value will not be interesting. 35344For a dynamic varobj, this value comes directly from the Python 35345pretty-printer object's @code{to_string} method. 35346 35347@item type 35348The varobj's type. This is a string representation of the type, as 35349would be printed by the @value{GDBN} CLI. If @samp{print object} 35350(@pxref{Print Settings, set print object}) is set to @code{on}, the 35351@emph{actual} (derived) type of the object is shown rather than the 35352@emph{declared} one. 35353 35354@item thread-id 35355If a variable object is bound to a specific thread, then this is the 35356thread's global identifier. 35357 35358@item has_more 35359For a dynamic varobj, this indicates whether there appear to be any 35360children available. For a non-dynamic varobj, this will be 0. 35361 35362@item dynamic 35363This attribute will be present and have the value @samp{1} if the 35364varobj is a dynamic varobj. If the varobj is not a dynamic varobj, 35365then this attribute will not be present. 35366 35367@item displayhint 35368A dynamic varobj can supply a display hint to the front end. The 35369value comes directly from the Python pretty-printer object's 35370@code{display_hint} method. @xref{Pretty Printing API}. 35371@end table 35372 35373Typical output will look like this: 35374 35375@smallexample 35376 name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}", 35377 has_more="@var{has_more}" 35378@end smallexample 35379 35380 35381@findex -var-delete 35382@subheading The @code{-var-delete} Command 35383 35384@subsubheading Synopsis 35385 35386@smallexample 35387 -var-delete [ -c ] @var{name} 35388@end smallexample 35389 35390Deletes a previously created variable object and all of its children. 35391With the @samp{-c} option, just deletes the children. 35392 35393Returns an error if the object @var{name} is not found. 35394 35395 35396@findex -var-set-format 35397@subheading The @code{-var-set-format} Command 35398 35399@subsubheading Synopsis 35400 35401@smallexample 35402 -var-set-format @var{name} @var{format-spec} 35403@end smallexample 35404 35405Sets the output format for the value of the object @var{name} to be 35406@var{format-spec}. 35407 35408@anchor{-var-set-format} 35409The syntax for the @var{format-spec} is as follows: 35410 35411@smallexample 35412 @var{format-spec} @expansion{} 35413 @{binary | decimal | hexadecimal | octal | natural | zero-hexadecimal@} 35414@end smallexample 35415 35416The natural format is the default format chosen automatically 35417based on the variable type (like decimal for an @code{int}, hex 35418for pointers, etc.). 35419 35420The zero-hexadecimal format has a representation similar to hexadecimal 35421but with padding zeroes to the left of the value. For example, a 32-bit 35422hexadecimal value of 0x1234 would be represented as 0x00001234 in the 35423zero-hexadecimal format. 35424 35425For a variable with children, the format is set only on the 35426variable itself, and the children are not affected. 35427 35428@findex -var-show-format 35429@subheading The @code{-var-show-format} Command 35430 35431@subsubheading Synopsis 35432 35433@smallexample 35434 -var-show-format @var{name} 35435@end smallexample 35436 35437Returns the format used to display the value of the object @var{name}. 35438 35439@smallexample 35440 @var{format} @expansion{} 35441 @var{format-spec} 35442@end smallexample 35443 35444 35445@findex -var-info-num-children 35446@subheading The @code{-var-info-num-children} Command 35447 35448@subsubheading Synopsis 35449 35450@smallexample 35451 -var-info-num-children @var{name} 35452@end smallexample 35453 35454Returns the number of children of a variable object @var{name}: 35455 35456@smallexample 35457 numchild=@var{n} 35458@end smallexample 35459 35460Note that this number is not completely reliable for a dynamic varobj. 35461It will return the current number of children, but more children may 35462be available. 35463 35464 35465@findex -var-list-children 35466@subheading The @code{-var-list-children} Command 35467 35468@subsubheading Synopsis 35469 35470@smallexample 35471 -var-list-children [@var{print-values}] @var{name} [@var{from} @var{to}] 35472@end smallexample 35473@anchor{-var-list-children} 35474 35475Return a list of the children of the specified variable object and 35476create variable objects for them, if they do not already exist. With 35477a single argument or if @var{print-values} has a value of 0 or 35478@code{--no-values}, print only the names of the variables; if 35479@var{print-values} is 1 or @code{--all-values}, also print their 35480values; and if it is 2 or @code{--simple-values} print the name and 35481value for simple data types and just the name for arrays, structures 35482and unions. 35483 35484@var{from} and @var{to}, if specified, indicate the range of children 35485to report. If @var{from} or @var{to} is less than zero, the range is 35486reset and all children will be reported. Otherwise, children starting 35487at @var{from} (zero-based) and up to and excluding @var{to} will be 35488reported. 35489 35490If a child range is requested, it will only affect the current call to 35491@code{-var-list-children}, but not future calls to @code{-var-update}. 35492For this, you must instead use @code{-var-set-update-range}. The 35493intent of this approach is to enable a front end to implement any 35494update approach it likes; for example, scrolling a view may cause the 35495front end to request more children with @code{-var-list-children}, and 35496then the front end could call @code{-var-set-update-range} with a 35497different range to ensure that future updates are restricted to just 35498the visible items. 35499 35500For each child the following results are returned: 35501 35502@table @var 35503 35504@item name 35505Name of the variable object created for this child. 35506 35507@item exp 35508The expression to be shown to the user by the front end to designate this child. 35509For example this may be the name of a structure member. 35510 35511For a dynamic varobj, this value cannot be used to form an 35512expression. There is no way to do this at all with a dynamic varobj. 35513 35514For C/C@t{++} structures there are several pseudo children returned to 35515designate access qualifiers. For these pseudo children @var{exp} is 35516@samp{public}, @samp{private}, or @samp{protected}. In this case the 35517type and value are not present. 35518 35519A dynamic varobj will not report the access qualifying 35520pseudo-children, regardless of the language. This information is not 35521available at all with a dynamic varobj. 35522 35523@item numchild 35524Number of children this child has. For a dynamic varobj, this will be 355250. 35526 35527@item type 35528The type of the child. If @samp{print object} 35529(@pxref{Print Settings, set print object}) is set to @code{on}, the 35530@emph{actual} (derived) type of the object is shown rather than the 35531@emph{declared} one. 35532 35533@item value 35534If values were requested, this is the value. 35535 35536@item thread-id 35537If this variable object is associated with a thread, this is the 35538thread's global thread id. Otherwise this result is not present. 35539 35540@item frozen 35541If the variable object is frozen, this variable will be present with a value of 1. 35542 35543@item displayhint 35544A dynamic varobj can supply a display hint to the front end. The 35545value comes directly from the Python pretty-printer object's 35546@code{display_hint} method. @xref{Pretty Printing API}. 35547 35548@item dynamic 35549This attribute will be present and have the value @samp{1} if the 35550varobj is a dynamic varobj. If the varobj is not a dynamic varobj, 35551then this attribute will not be present. 35552 35553@end table 35554 35555The result may have its own attributes: 35556 35557@table @samp 35558@item displayhint 35559A dynamic varobj can supply a display hint to the front end. The 35560value comes directly from the Python pretty-printer object's 35561@code{display_hint} method. @xref{Pretty Printing API}. 35562 35563@item has_more 35564This is an integer attribute which is nonzero if there are children 35565remaining after the end of the selected range. 35566@end table 35567 35568@subsubheading Example 35569 35570@smallexample 35571(gdb) 35572 -var-list-children n 35573 ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp}, 35574 numchild=@var{n},type=@var{type}@},@r{(repeats N times)}] 35575(gdb) 35576 -var-list-children --all-values n 35577 ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp}, 35578 numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}] 35579@end smallexample 35580 35581 35582@findex -var-info-type 35583@subheading The @code{-var-info-type} Command 35584 35585@subsubheading Synopsis 35586 35587@smallexample 35588 -var-info-type @var{name} 35589@end smallexample 35590 35591Returns the type of the specified variable @var{name}. The type is 35592returned as a string in the same format as it is output by the 35593@value{GDBN} CLI: 35594 35595@smallexample 35596 type=@var{typename} 35597@end smallexample 35598 35599 35600@findex -var-info-expression 35601@subheading The @code{-var-info-expression} Command 35602 35603@subsubheading Synopsis 35604 35605@smallexample 35606 -var-info-expression @var{name} 35607@end smallexample 35608 35609Returns a string that is suitable for presenting this 35610variable object in user interface. The string is generally 35611not valid expression in the current language, and cannot be evaluated. 35612 35613For example, if @code{a} is an array, and variable object 35614@code{A} was created for @code{a}, then we'll get this output: 35615 35616@smallexample 35617(gdb) -var-info-expression A.1 35618^done,lang="C",exp="1" 35619@end smallexample 35620 35621@noindent 35622Here, the value of @code{lang} is the language name, which can be 35623found in @ref{Supported Languages}. 35624 35625Note that the output of the @code{-var-list-children} command also 35626includes those expressions, so the @code{-var-info-expression} command 35627is of limited use. 35628 35629@findex -var-info-path-expression 35630@subheading The @code{-var-info-path-expression} Command 35631 35632@subsubheading Synopsis 35633 35634@smallexample 35635 -var-info-path-expression @var{name} 35636@end smallexample 35637 35638Returns an expression that can be evaluated in the current 35639context and will yield the same value that a variable object has. 35640Compare this with the @code{-var-info-expression} command, which 35641result can be used only for UI presentation. Typical use of 35642the @code{-var-info-path-expression} command is creating a 35643watchpoint from a variable object. 35644 35645This command is currently not valid for children of a dynamic varobj, 35646and will give an error when invoked on one. 35647 35648For example, suppose @code{C} is a C@t{++} class, derived from class 35649@code{Base}, and that the @code{Base} class has a member called 35650@code{m_size}. Assume a variable @code{c} is has the type of 35651@code{C} and a variable object @code{C} was created for variable 35652@code{c}. Then, we'll get this output: 35653@smallexample 35654(gdb) -var-info-path-expression C.Base.public.m_size 35655^done,path_expr=((Base)c).m_size) 35656@end smallexample 35657 35658@findex -var-show-attributes 35659@subheading The @code{-var-show-attributes} Command 35660 35661@subsubheading Synopsis 35662 35663@smallexample 35664 -var-show-attributes @var{name} 35665@end smallexample 35666 35667List attributes of the specified variable object @var{name}: 35668 35669@smallexample 35670 status=@var{attr} [ ( ,@var{attr} )* ] 35671@end smallexample 35672 35673@noindent 35674where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}. 35675 35676@findex -var-evaluate-expression 35677@subheading The @code{-var-evaluate-expression} Command 35678 35679@subsubheading Synopsis 35680 35681@smallexample 35682 -var-evaluate-expression [-f @var{format-spec}] @var{name} 35683@end smallexample 35684 35685Evaluates the expression that is represented by the specified variable 35686object and returns its value as a string. The format of the string 35687can be specified with the @samp{-f} option. The possible values of 35688this option are the same as for @code{-var-set-format} 35689(@pxref{-var-set-format}). If the @samp{-f} option is not specified, 35690the current display format will be used. The current display format 35691can be changed using the @code{-var-set-format} command. 35692 35693@smallexample 35694 value=@var{value} 35695@end smallexample 35696 35697Note that one must invoke @code{-var-list-children} for a variable 35698before the value of a child variable can be evaluated. 35699 35700@findex -var-assign 35701@subheading The @code{-var-assign} Command 35702 35703@subsubheading Synopsis 35704 35705@smallexample 35706 -var-assign @var{name} @var{expression} 35707@end smallexample 35708 35709Assigns the value of @var{expression} to the variable object specified 35710by @var{name}. The object must be @samp{editable}. If the variable's 35711value is altered by the assign, the variable will show up in any 35712subsequent @code{-var-update} list. 35713 35714@subsubheading Example 35715 35716@smallexample 35717(gdb) 35718-var-assign var1 3 35719^done,value="3" 35720(gdb) 35721-var-update * 35722^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}] 35723(gdb) 35724@end smallexample 35725 35726@findex -var-update 35727@subheading The @code{-var-update} Command 35728 35729@subsubheading Synopsis 35730 35731@smallexample 35732 -var-update [@var{print-values}] @{@var{name} | "*"@} 35733@end smallexample 35734 35735Reevaluate the expressions corresponding to the variable object 35736@var{name} and all its direct and indirect children, and return the 35737list of variable objects whose values have changed; @var{name} must 35738be a root variable object. Here, ``changed'' means that the result of 35739@code{-var-evaluate-expression} before and after the 35740@code{-var-update} is different. If @samp{*} is used as the variable 35741object names, all existing variable objects are updated, except 35742for frozen ones (@pxref{-var-set-frozen}). The option 35743@var{print-values} determines whether both names and values, or just 35744names are printed. The possible values of this option are the same 35745as for @code{-var-list-children} (@pxref{-var-list-children}). It is 35746recommended to use the @samp{--all-values} option, to reduce the 35747number of MI commands needed on each program stop. 35748 35749With the @samp{*} parameter, if a variable object is bound to a 35750currently running thread, it will not be updated, without any 35751diagnostic. 35752 35753If @code{-var-set-update-range} was previously used on a varobj, then 35754only the selected range of children will be reported. 35755 35756@code{-var-update} reports all the changed varobjs in a tuple named 35757@samp{changelist}. 35758 35759Each item in the change list is itself a tuple holding: 35760 35761@table @samp 35762@item name 35763The name of the varobj. 35764 35765@item value 35766If values were requested for this update, then this field will be 35767present and will hold the value of the varobj. 35768 35769@item in_scope 35770@anchor{-var-update} 35771This field is a string which may take one of three values: 35772 35773@table @code 35774@item "true" 35775The variable object's current value is valid. 35776 35777@item "false" 35778The variable object does not currently hold a valid value but it may 35779hold one in the future if its associated expression comes back into 35780scope. 35781 35782@item "invalid" 35783The variable object no longer holds a valid value. 35784This can occur when the executable file being debugged has changed, 35785either through recompilation or by using the @value{GDBN} @code{file} 35786command. The front end should normally choose to delete these variable 35787objects. 35788@end table 35789 35790In the future new values may be added to this list so the front should 35791be prepared for this possibility. @xref{GDB/MI Development and Front Ends, ,@sc{gdb/mi} Development and Front Ends}. 35792 35793@item type_changed 35794This is only present if the varobj is still valid. If the type 35795changed, then this will be the string @samp{true}; otherwise it will 35796be @samp{false}. 35797 35798When a varobj's type changes, its children are also likely to have 35799become incorrect. Therefore, the varobj's children are automatically 35800deleted when this attribute is @samp{true}. Also, the varobj's update 35801range, when set using the @code{-var-set-update-range} command, is 35802unset. 35803 35804@item new_type 35805If the varobj's type changed, then this field will be present and will 35806hold the new type. 35807 35808@item new_num_children 35809For a dynamic varobj, if the number of children changed, or if the 35810type changed, this will be the new number of children. 35811 35812The @samp{numchild} field in other varobj responses is generally not 35813valid for a dynamic varobj -- it will show the number of children that 35814@value{GDBN} knows about, but because dynamic varobjs lazily 35815instantiate their children, this will not reflect the number of 35816children which may be available. 35817 35818The @samp{new_num_children} attribute only reports changes to the 35819number of children known by @value{GDBN}. This is the only way to 35820detect whether an update has removed children (which necessarily can 35821only happen at the end of the update range). 35822 35823@item displayhint 35824The display hint, if any. 35825 35826@item has_more 35827This is an integer value, which will be 1 if there are more children 35828available outside the varobj's update range. 35829 35830@item dynamic 35831This attribute will be present and have the value @samp{1} if the 35832varobj is a dynamic varobj. If the varobj is not a dynamic varobj, 35833then this attribute will not be present. 35834 35835@item new_children 35836If new children were added to a dynamic varobj within the selected 35837update range (as set by @code{-var-set-update-range}), then they will 35838be listed in this attribute. 35839@end table 35840 35841@subsubheading Example 35842 35843@smallexample 35844(gdb) 35845-var-assign var1 3 35846^done,value="3" 35847(gdb) 35848-var-update --all-values var1 35849^done,changelist=[@{name="var1",value="3",in_scope="true", 35850type_changed="false"@}] 35851(gdb) 35852@end smallexample 35853 35854@findex -var-set-frozen 35855@anchor{-var-set-frozen} 35856@subheading The @code{-var-set-frozen} Command 35857 35858@subsubheading Synopsis 35859 35860@smallexample 35861 -var-set-frozen @var{name} @var{flag} 35862@end smallexample 35863 35864Set the frozenness flag on the variable object @var{name}. The 35865@var{flag} parameter should be either @samp{1} to make the variable 35866frozen or @samp{0} to make it unfrozen. If a variable object is 35867frozen, then neither itself, nor any of its children, are 35868implicitly updated by @code{-var-update} of 35869a parent variable or by @code{-var-update *}. Only 35870@code{-var-update} of the variable itself will update its value and 35871values of its children. After a variable object is unfrozen, it is 35872implicitly updated by all subsequent @code{-var-update} operations. 35873Unfreezing a variable does not update it, only subsequent 35874@code{-var-update} does. 35875 35876@subsubheading Example 35877 35878@smallexample 35879(gdb) 35880-var-set-frozen V 1 35881^done 35882(gdb) 35883@end smallexample 35884 35885@findex -var-set-update-range 35886@anchor{-var-set-update-range} 35887@subheading The @code{-var-set-update-range} command 35888 35889@subsubheading Synopsis 35890 35891@smallexample 35892 -var-set-update-range @var{name} @var{from} @var{to} 35893@end smallexample 35894 35895Set the range of children to be returned by future invocations of 35896@code{-var-update}. 35897 35898@var{from} and @var{to} indicate the range of children to report. If 35899@var{from} or @var{to} is less than zero, the range is reset and all 35900children will be reported. Otherwise, children starting at @var{from} 35901(zero-based) and up to and excluding @var{to} will be reported. 35902 35903@subsubheading Example 35904 35905@smallexample 35906(gdb) 35907-var-set-update-range V 1 2 35908^done 35909@end smallexample 35910 35911@findex -var-set-visualizer 35912@anchor{-var-set-visualizer} 35913@subheading The @code{-var-set-visualizer} command 35914 35915@subsubheading Synopsis 35916 35917@smallexample 35918 -var-set-visualizer @var{name} @var{visualizer} 35919@end smallexample 35920 35921Set a visualizer for the variable object @var{name}. 35922 35923@var{visualizer} is the visualizer to use. The special value 35924@samp{None} means to disable any visualizer in use. 35925 35926If not @samp{None}, @var{visualizer} must be a Python expression. 35927This expression must evaluate to a callable object which accepts a 35928single argument. @value{GDBN} will call this object with the value of 35929the varobj @var{name} as an argument (this is done so that the same 35930Python pretty-printing code can be used for both the CLI and MI). 35931When called, this object must return an object which conforms to the 35932pretty-printing interface (@pxref{Pretty Printing API}). 35933 35934The pre-defined function @code{gdb.default_visualizer} may be used to 35935select a visualizer by following the built-in process 35936(@pxref{Selecting Pretty-Printers}). This is done automatically when 35937a varobj is created, and so ordinarily is not needed. 35938 35939This feature is only available if Python support is enabled. The MI 35940command @code{-list-features} (@pxref{GDB/MI Support Commands}) 35941can be used to check this. 35942 35943@subsubheading Example 35944 35945Resetting the visualizer: 35946 35947@smallexample 35948(gdb) 35949-var-set-visualizer V None 35950^done 35951@end smallexample 35952 35953Reselecting the default (type-based) visualizer: 35954 35955@smallexample 35956(gdb) 35957-var-set-visualizer V gdb.default_visualizer 35958^done 35959@end smallexample 35960 35961Suppose @code{SomeClass} is a visualizer class. A lambda expression 35962can be used to instantiate this class for a varobj: 35963 35964@smallexample 35965(gdb) 35966-var-set-visualizer V "lambda val: SomeClass()" 35967^done 35968@end smallexample 35969 35970@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 35971@node GDB/MI Data Manipulation 35972@section @sc{gdb/mi} Data Manipulation 35973 35974@cindex data manipulation, in @sc{gdb/mi} 35975@cindex @sc{gdb/mi}, data manipulation 35976This section describes the @sc{gdb/mi} commands that manipulate data: 35977examine memory and registers, evaluate expressions, etc. 35978 35979For details about what an addressable memory unit is, 35980@pxref{addressable memory unit}. 35981 35982@c REMOVED FROM THE INTERFACE. 35983@c @subheading -data-assign 35984@c Change the value of a program variable. Plenty of side effects. 35985@c @subsubheading GDB Command 35986@c set variable 35987@c @subsubheading Example 35988@c N.A. 35989 35990@findex -data-disassemble 35991@subheading The @code{-data-disassemble} Command 35992 35993@subsubheading Synopsis 35994 35995@smallexample 35996 -data-disassemble 35997 ( -s @var{start-addr} -e @var{end-addr} 35998 | -a @var{addr} 35999 | -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ) 36000 [ --opcodes @var{opcodes-mode} ] 36001 [ --source ] 36002 [ -- @var{mode} ] 36003@end smallexample 36004 36005@noindent 36006Where: 36007 36008@table @samp 36009@item @var{start-addr} 36010is the beginning address (or @code{$pc}) 36011@item @var{end-addr} 36012is the end address 36013@item @var{addr} 36014is an address anywhere within (or the name of) the function to 36015disassemble. If an address is specified, the whole function 36016surrounding that address will be disassembled. If a name is 36017specified, the whole function with that name will be disassembled. 36018@item @var{filename} 36019is the name of the file to disassemble 36020@item @var{linenum} 36021is the line number to disassemble around 36022@item @var{lines} 36023is the number of disassembly lines to be produced. If it is -1, 36024the whole function will be disassembled, in case no @var{end-addr} is 36025specified. If @var{end-addr} is specified as a non-zero value, and 36026@var{lines} is lower than the number of disassembly lines between 36027@var{start-addr} and @var{end-addr}, only @var{lines} lines are 36028displayed; if @var{lines} is higher than the number of lines between 36029@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr} 36030are displayed. 36031@item @var{opcodes-mode} 36032can only be used with @var{mode} 0, and should be one of the following: 36033@table @samp 36034@item none 36035no opcode information will be included in the result. 36036 36037@item bytes 36038opcodes will be included in the result, the opcodes will be formatted 36039as for @kbd{disassemble /b}. 36040 36041@item display 36042opcodes will be included in the result, the opcodes will be formatted 36043as for @kbd{disassemble /r}. 36044@end table 36045@item @var{mode} 36046the use of @var{mode} is deprecated in favour of using the 36047@code{--opcodes} and @code{--source} options. When no @var{mode} is 36048given, @var{mode} 0 will be assumed. However, the @var{mode} is still 36049available for backward compatibility. The @var{mode} should be one of: 36050@table @samp 36051@item 0 36052@emph{disassembly only}, this is the default mode if no mode is 36053specified. 36054 36055@item 1 36056@emph{mixed source and disassembly (deprecated)}, it is not possible 36057to recreate this mode using @code{--opcodes} and @code{--source} 36058options. 36059 36060@item 2 36061@emph{disassembly with raw opcodes}, this mode is equivalent to using 36062@var{mode} 0 and passing @code{--opcodes bytes} to the command. 36063 36064@item 3 36065@emph{mixed source and disassembly with raw opcodes (deprecated)}, it 36066is not possible to recreate this mode using @code{--opcodes} and 36067@code{--source} options. 36068 36069@item 4 36070@emph{mixed source and disassembly}, this mode is equivalent to using 36071@var{mode} 0 and passing @code{--source} to the command. 36072 36073@item 5 36074@emph{mixed source and disassembly with raw opcodes}, this mode is 36075equivalent to using @var{mode} 0 and passing @code{--opcodes bytes} 36076and @code{--source} to the command. 36077@end table 36078Modes 1 and 3 are deprecated. The output is ``source centric'' 36079which hasn't proved useful in practice. 36080@xref{Machine Code}, for a discussion of the difference between 36081@code{/m} and @code{/s} output of the @code{disassemble} command. 36082@end table 36083 36084The @code{--source} can only be used with @var{mode} 0. Passing this 36085option will include the source code in the disassembly result as if 36086@var{mode} 4 or 5 had been used. 36087 36088@subsubheading Result 36089 36090The result of the @code{-data-disassemble} command will be a list named 36091@samp{asm_insns}, the contents of this list depend on the options used 36092with the @code{-data-disassemble} command. 36093 36094For modes 0 and 2, and when the @code{--source} option is not used, the 36095@samp{asm_insns} list contains tuples with the following fields: 36096 36097@table @code 36098@item address 36099The address at which this instruction was disassembled. 36100 36101@item func-name 36102The name of the function this instruction is within. 36103 36104@item offset 36105The decimal offset in bytes from the start of @samp{func-name}. 36106 36107@item inst 36108The text disassembly for this @samp{address}. 36109 36110@item opcodes 36111This field is only present for modes 2, 3 and 5, or when the 36112@code{--opcodes} option @samp{bytes} or @samp{display} is used. This 36113contains the raw opcode bytes for the @samp{inst} field. 36114 36115When the @samp{--opcodes} option is not passed to 36116@code{-data-disassemble}, or the @samp{bytes} value is passed to 36117@samp{--opcodes}, then the bytes are formatted as a series of single 36118bytes, in hex, in ascending address order, with a single space between 36119each byte. This format is equivalent to the @samp{/b} option being 36120used with the @kbd{disassemble} command 36121(@pxref{disassemble,,@kbd{disassemble}}). 36122 36123When @samp{--opcodes} is passed the value @samp{display} then the bytes 36124are formatted in the natural instruction display order. This means 36125multiple bytes can be grouped together, and the bytes might be 36126byte-swapped. This format is equivalent to the @samp{/r} option being 36127used with the @kbd{disassemble} command. 36128@end table 36129 36130For modes 1, 3, 4 and 5, or when the @code{--source} option is used, the 36131@samp{asm_insns} list contains tuples named @samp{src_and_asm_line}, 36132each of which has the following fields: 36133 36134@table @code 36135@item line 36136The line number within @samp{file}. 36137 36138@item file 36139The file name from the compilation unit. This might be an absolute 36140file name or a relative file name depending on the compile command 36141used. 36142 36143@item fullname 36144Absolute file name of @samp{file}. It is converted to a canonical form 36145using the source file search path 36146(@pxref{Source Path, ,Specifying Source Directories}) 36147and after resolving all the symbolic links. 36148 36149If the source file is not found this field will contain the path as 36150present in the debug information. 36151 36152@item line_asm_insn 36153This is a list of tuples containing the disassembly for @samp{line} in 36154@samp{file}. The fields of each tuple are the same as for 36155@code{-data-disassemble} in @var{mode} 0 and 2, so @samp{address}, 36156@samp{func-name}, @samp{offset}, @samp{inst}, and optionally 36157@samp{opcodes}. 36158 36159@end table 36160 36161Note that whatever included in the @samp{inst} field, is not 36162manipulated directly by @sc{gdb/mi}, i.e., it is not possible to 36163adjust its format. 36164 36165@subsubheading @value{GDBN} Command 36166 36167The corresponding @value{GDBN} command is @samp{disassemble}. 36168 36169@subsubheading Example 36170 36171Disassemble from the current value of @code{$pc} to @code{$pc + 20}: 36172 36173@smallexample 36174(gdb) 36175-data-disassemble -s $pc -e "$pc + 20" -- 0 36176^done, 36177asm_insns=[ 36178@{address="0x000107c0",func-name="main",offset="4", 36179inst="mov 2, %o0"@}, 36180@{address="0x000107c4",func-name="main",offset="8", 36181inst="sethi %hi(0x11800), %o2"@}, 36182@{address="0x000107c8",func-name="main",offset="12", 36183inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@}, 36184@{address="0x000107cc",func-name="main",offset="16", 36185inst="sethi %hi(0x11800), %o2"@}, 36186@{address="0x000107d0",func-name="main",offset="20", 36187inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}] 36188(gdb) 36189@end smallexample 36190 36191Disassemble the whole @code{main} function. Line 32 is part of 36192@code{main}. 36193 36194@smallexample 36195-data-disassemble -f basics.c -l 32 -- 0 36196^done,asm_insns=[ 36197@{address="0x000107bc",func-name="main",offset="0", 36198inst="save %sp, -112, %sp"@}, 36199@{address="0x000107c0",func-name="main",offset="4", 36200inst="mov 2, %o0"@}, 36201@{address="0x000107c4",func-name="main",offset="8", 36202inst="sethi %hi(0x11800), %o2"@}, 36203[@dots{}] 36204@{address="0x0001081c",func-name="main",offset="96",inst="ret "@}, 36205@{address="0x00010820",func-name="main",offset="100",inst="restore "@}] 36206(gdb) 36207@end smallexample 36208 36209Disassemble 3 instructions from the start of @code{main}: 36210 36211@smallexample 36212(gdb) 36213-data-disassemble -f basics.c -l 32 -n 3 -- 0 36214^done,asm_insns=[ 36215@{address="0x000107bc",func-name="main",offset="0", 36216inst="save %sp, -112, %sp"@}, 36217@{address="0x000107c0",func-name="main",offset="4", 36218inst="mov 2, %o0"@}, 36219@{address="0x000107c4",func-name="main",offset="8", 36220inst="sethi %hi(0x11800), %o2"@}] 36221(gdb) 36222@end smallexample 36223 36224Disassemble 3 instructions from the start of @code{main} in mixed mode: 36225 36226@smallexample 36227(gdb) 36228-data-disassemble -f basics.c -l 32 -n 3 -- 1 36229^done,asm_insns=[ 36230src_and_asm_line=@{line="31", 36231file="../../../src/gdb/testsuite/gdb.mi/basics.c", 36232fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c", 36233line_asm_insn=[@{address="0x000107bc", 36234func-name="main",offset="0",inst="save %sp, -112, %sp"@}]@}, 36235src_and_asm_line=@{line="32", 36236file="../../../src/gdb/testsuite/gdb.mi/basics.c", 36237fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c", 36238line_asm_insn=[@{address="0x000107c0", 36239func-name="main",offset="4",inst="mov 2, %o0"@}, 36240@{address="0x000107c4",func-name="main",offset="8", 36241inst="sethi %hi(0x11800), %o2"@}]@}] 36242(gdb) 36243@end smallexample 36244 36245 36246@findex -data-evaluate-expression 36247@subheading The @code{-data-evaluate-expression} Command 36248 36249@subsubheading Synopsis 36250 36251@smallexample 36252 -data-evaluate-expression @var{expr} 36253@end smallexample 36254 36255Evaluate @var{expr} as an expression. The expression could contain an 36256inferior function call. The function call will execute synchronously. 36257If the expression contains spaces, it must be enclosed in double quotes. 36258 36259@subsubheading @value{GDBN} Command 36260 36261The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and 36262@samp{call}. In @code{gdbtk} only, there's a corresponding 36263@samp{gdb_eval} command. 36264 36265@subsubheading Example 36266 36267In the following example, the numbers that precede the commands are the 36268@dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi} 36269Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its 36270output. 36271 36272@smallexample 36273211-data-evaluate-expression A 36274211^done,value="1" 36275(gdb) 36276311-data-evaluate-expression &A 36277311^done,value="0xefffeb7c" 36278(gdb) 36279411-data-evaluate-expression A+3 36280411^done,value="4" 36281(gdb) 36282511-data-evaluate-expression "A + 3" 36283511^done,value="4" 36284(gdb) 36285@end smallexample 36286 36287 36288@findex -data-list-changed-registers 36289@subheading The @code{-data-list-changed-registers} Command 36290 36291@subsubheading Synopsis 36292 36293@smallexample 36294 -data-list-changed-registers 36295@end smallexample 36296 36297Display a list of the registers that have changed. 36298 36299@subsubheading @value{GDBN} Command 36300 36301@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk} 36302has the corresponding command @samp{gdb_changed_register_list}. 36303 36304@subsubheading Example 36305 36306On a PPC MBX board: 36307 36308@smallexample 36309(gdb) 36310-exec-continue 36311^running 36312 36313(gdb) 36314*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame=@{ 36315func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c", 36316line="5",arch="powerpc"@} 36317(gdb) 36318-data-list-changed-registers 36319^done,changed-registers=["0","1","2","4","5","6","7","8","9", 36320"10","11","13","14","15","16","17","18","19","20","21","22","23", 36321"24","25","26","27","28","30","31","64","65","66","67","69"] 36322(gdb) 36323@end smallexample 36324 36325 36326@findex -data-list-register-names 36327@subheading The @code{-data-list-register-names} Command 36328 36329@subsubheading Synopsis 36330 36331@smallexample 36332 -data-list-register-names [ ( @var{regno} )+ ] 36333@end smallexample 36334 36335Show a list of register names for the current target. If no arguments 36336are given, it shows a list of the names of all the registers. If 36337integer numbers are given as arguments, it will print a list of the 36338names of the registers corresponding to the arguments. To ensure 36339consistency between a register name and its number, the output list may 36340include empty register names. 36341 36342@subsubheading @value{GDBN} Command 36343 36344@value{GDBN} does not have a command which corresponds to 36345@samp{-data-list-register-names}. In @code{gdbtk} there is a 36346corresponding command @samp{gdb_regnames}. 36347 36348@subsubheading Example 36349 36350For the PPC MBX board: 36351@smallexample 36352(gdb) 36353-data-list-register-names 36354^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", 36355"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", 36356"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", 36357"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", 36358"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", 36359"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", 36360"", "pc","ps","cr","lr","ctr","xer"] 36361(gdb) 36362-data-list-register-names 1 2 3 36363^done,register-names=["r1","r2","r3"] 36364(gdb) 36365@end smallexample 36366 36367@findex -data-list-register-values 36368@subheading The @code{-data-list-register-values} Command 36369 36370@subsubheading Synopsis 36371 36372@smallexample 36373 -data-list-register-values 36374 [ @code{--skip-unavailable} ] @var{fmt} [ ( @var{regno} )*] 36375@end smallexample 36376 36377Display the registers' contents. The format according to which the 36378registers' contents are to be returned is given by @var{fmt}, followed 36379by an optional list of numbers specifying the registers to display. A 36380missing list of numbers indicates that the contents of all the 36381registers must be returned. The @code{--skip-unavailable} option 36382indicates that only the available registers are to be returned. 36383 36384Allowed formats for @var{fmt} are: 36385 36386@table @code 36387@item x 36388Hexadecimal 36389@item o 36390Octal 36391@item t 36392Binary 36393@item d 36394Decimal 36395@item r 36396Raw 36397@item N 36398Natural 36399@end table 36400 36401@subsubheading @value{GDBN} Command 36402 36403The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info 36404all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}. 36405 36406@subsubheading Example 36407 36408For a PPC MBX board (note: line breaks are for readability only, they 36409don't appear in the actual output): 36410 36411@smallexample 36412(gdb) 36413-data-list-register-values r 64 65 36414^done,register-values=[@{number="64",value="0xfe00a300"@}, 36415@{number="65",value="0x00029002"@}] 36416(gdb) 36417-data-list-register-values x 36418^done,register-values=[@{number="0",value="0xfe0043c8"@}, 36419@{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@}, 36420@{number="3",value="0x0"@},@{number="4",value="0xa"@}, 36421@{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@}, 36422@{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@}, 36423@{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@}, 36424@{number="11",value="0x1"@},@{number="12",value="0x0"@}, 36425@{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@}, 36426@{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@}, 36427@{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@}, 36428@{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@}, 36429@{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@}, 36430@{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@}, 36431@{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@}, 36432@{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@}, 36433@{number="29",value="0x0"@},@{number="30",value="0xfe010000"@}, 36434@{number="31",value="0x0"@},@{number="32",value="0x0"@}, 36435@{number="33",value="0x0"@},@{number="34",value="0x0"@}, 36436@{number="35",value="0x0"@},@{number="36",value="0x0"@}, 36437@{number="37",value="0x0"@},@{number="38",value="0x0"@}, 36438@{number="39",value="0x0"@},@{number="40",value="0x0"@}, 36439@{number="41",value="0x0"@},@{number="42",value="0x0"@}, 36440@{number="43",value="0x0"@},@{number="44",value="0x0"@}, 36441@{number="45",value="0x0"@},@{number="46",value="0x0"@}, 36442@{number="47",value="0x0"@},@{number="48",value="0x0"@}, 36443@{number="49",value="0x0"@},@{number="50",value="0x0"@}, 36444@{number="51",value="0x0"@},@{number="52",value="0x0"@}, 36445@{number="53",value="0x0"@},@{number="54",value="0x0"@}, 36446@{number="55",value="0x0"@},@{number="56",value="0x0"@}, 36447@{number="57",value="0x0"@},@{number="58",value="0x0"@}, 36448@{number="59",value="0x0"@},@{number="60",value="0x0"@}, 36449@{number="61",value="0x0"@},@{number="62",value="0x0"@}, 36450@{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@}, 36451@{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@}, 36452@{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@}, 36453@{number="69",value="0x20002b03"@}] 36454(gdb) 36455@end smallexample 36456 36457 36458@findex -data-read-memory 36459@subheading The @code{-data-read-memory} Command 36460 36461This command is deprecated, use @code{-data-read-memory-bytes} instead. 36462 36463@subsubheading Synopsis 36464 36465@smallexample 36466 -data-read-memory [ -o @var{byte-offset} ] 36467 @var{address} @var{word-format} @var{word-size} 36468 @var{nr-rows} @var{nr-cols} [ @var{aschar} ] 36469@end smallexample 36470 36471@noindent 36472where: 36473 36474@table @samp 36475@item @var{address} 36476An expression specifying the address of the first memory word to be 36477read. Complex expressions containing embedded white space should be 36478quoted using the C convention. 36479 36480@item @var{word-format} 36481The format to be used to print the memory words. The notation is the 36482same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats, 36483,Output Formats}). 36484 36485@item @var{word-size} 36486The size of each memory word in bytes. 36487 36488@item @var{nr-rows} 36489The number of rows in the output table. 36490 36491@item @var{nr-cols} 36492The number of columns in the output table. 36493 36494@item @var{aschar} 36495If present, indicates that each row should include an @sc{ascii} dump. The 36496value of @var{aschar} is used as a padding character when a byte is not a 36497member of the printable @sc{ascii} character set (printable @sc{ascii} 36498characters are those whose code is between 32 and 126, inclusively). 36499 36500@item @var{byte-offset} 36501An offset to add to the @var{address} before fetching memory. 36502@end table 36503 36504This command displays memory contents as a table of @var{nr-rows} by 36505@var{nr-cols} words, each word being @var{word-size} bytes. In total, 36506@code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read 36507(returned as @samp{total-bytes}). Should less than the requested number 36508of bytes be returned by the target, the missing words are identified 36509using @samp{N/A}. The number of bytes read from the target is returned 36510in @samp{nr-bytes} and the starting address used to read memory in 36511@samp{addr}. 36512 36513The address of the next/previous row or page is available in 36514@samp{next-row} and @samp{prev-row}, @samp{next-page} and 36515@samp{prev-page}. 36516 36517@subsubheading @value{GDBN} Command 36518 36519The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has 36520@samp{gdb_get_mem} memory read command. 36521 36522@subsubheading Example 36523 36524Read six bytes of memory starting at @code{bytes+6} but then offset by 36525@code{-6} bytes. Format as three rows of two columns. One byte per 36526word. Display each word in hex. 36527 36528@smallexample 36529(gdb) 365309-data-read-memory -o -6 -- bytes+6 x 1 3 2 365319^done,addr="0x00001390",nr-bytes="6",total-bytes="6", 36532next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", 36533prev-page="0x0000138a",memory=[ 36534@{addr="0x00001390",data=["0x00","0x01"]@}, 36535@{addr="0x00001392",data=["0x02","0x03"]@}, 36536@{addr="0x00001394",data=["0x04","0x05"]@}] 36537(gdb) 36538@end smallexample 36539 36540Read two bytes of memory starting at address @code{shorts + 64} and 36541display as a single word formatted in decimal. 36542 36543@smallexample 36544(gdb) 365455-data-read-memory shorts+64 d 2 1 1 365465^done,addr="0x00001510",nr-bytes="2",total-bytes="2", 36547next-row="0x00001512",prev-row="0x0000150e", 36548next-page="0x00001512",prev-page="0x0000150e",memory=[ 36549@{addr="0x00001510",data=["128"]@}] 36550(gdb) 36551@end smallexample 36552 36553Read thirty two bytes of memory starting at @code{bytes+16} and format 36554as eight rows of four columns. Include a string encoding with @samp{x} 36555used as the non-printable character. 36556 36557@smallexample 36558(gdb) 365594-data-read-memory bytes+16 x 1 8 4 x 365604^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", 36561next-row="0x000013c0",prev-row="0x0000139c", 36562next-page="0x000013c0",prev-page="0x00001380",memory=[ 36563@{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@}, 36564@{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@}, 36565@{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@}, 36566@{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@}, 36567@{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@}, 36568@{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@}, 36569@{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@}, 36570@{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}] 36571(gdb) 36572@end smallexample 36573 36574@findex -data-read-memory-bytes 36575@subheading The @code{-data-read-memory-bytes} Command 36576 36577@subsubheading Synopsis 36578 36579@smallexample 36580 -data-read-memory-bytes [ -o @var{offset} ] 36581 @var{address} @var{count} 36582@end smallexample 36583 36584@noindent 36585where: 36586 36587@table @samp 36588@item @var{address} 36589An expression specifying the address of the first addressable memory unit 36590to be read. Complex expressions containing embedded white space should be 36591quoted using the C convention. 36592 36593@item @var{count} 36594The number of addressable memory units to read. This should be an integer 36595literal. 36596 36597@item @var{offset} 36598The offset relative to @var{address} at which to start reading. This 36599should be an integer literal. This option is provided so that a frontend 36600is not required to first evaluate address and then perform address 36601arithmetic itself. 36602 36603@end table 36604 36605This command attempts to read all accessible memory regions in the 36606specified range. First, all regions marked as unreadable in the memory 36607map (if one is defined) will be skipped. @xref{Memory Region 36608Attributes}. Second, @value{GDBN} will attempt to read the remaining 36609regions. For each one, if reading full region results in an errors, 36610@value{GDBN} will try to read a subset of the region. 36611 36612In general, every single memory unit in the region may be readable or not, 36613and the only way to read every readable unit is to try a read at 36614every address, which is not practical. Therefore, @value{GDBN} will 36615attempt to read all accessible memory units at either beginning or the end 36616of the region, using a binary division scheme. This heuristic works 36617well for reading across a memory map boundary. Note that if a region 36618has a readable range that is neither at the beginning or the end, 36619@value{GDBN} will not read it. 36620 36621The result record (@pxref{GDB/MI Result Records}) that is output of 36622the command includes a field named @samp{memory} whose content is a 36623list of tuples. Each tuple represent a successfully read memory block 36624and has the following fields: 36625 36626@table @code 36627@item begin 36628The start address of the memory block, as hexadecimal literal. 36629 36630@item end 36631The end address of the memory block, as hexadecimal literal. 36632 36633@item offset 36634The offset of the memory block, as hexadecimal literal, relative to 36635the start address passed to @code{-data-read-memory-bytes}. 36636 36637@item contents 36638The contents of the memory block, in hex. 36639 36640@end table 36641 36642 36643 36644@subsubheading @value{GDBN} Command 36645 36646The corresponding @value{GDBN} command is @samp{x}. 36647 36648@subsubheading Example 36649 36650@smallexample 36651(gdb) 36652-data-read-memory-bytes &a 10 36653^done,memory=[@{begin="0xbffff154",offset="0x00000000", 36654 end="0xbffff15e", 36655 contents="01000000020000000300"@}] 36656(gdb) 36657@end smallexample 36658 36659 36660@findex -data-write-memory-bytes 36661@subheading The @code{-data-write-memory-bytes} Command 36662 36663@subsubheading Synopsis 36664 36665@smallexample 36666 -data-write-memory-bytes @var{address} @var{contents} 36667 -data-write-memory-bytes @var{address} @var{contents} @r{[}@var{count}@r{]} 36668@end smallexample 36669 36670@noindent 36671where: 36672 36673@table @samp 36674@item @var{address} 36675An expression specifying the address of the first addressable memory unit 36676to be written. Complex expressions containing embedded white space should 36677be quoted using the C convention. 36678 36679@item @var{contents} 36680The hex-encoded data to write. It is an error if @var{contents} does 36681not represent an integral number of addressable memory units. 36682 36683@item @var{count} 36684Optional argument indicating the number of addressable memory units to be 36685written. If @var{count} is greater than @var{contents}' length, 36686@value{GDBN} will repeatedly write @var{contents} until it fills 36687@var{count} memory units. 36688 36689@end table 36690 36691@subsubheading @value{GDBN} Command 36692 36693There's no corresponding @value{GDBN} command. 36694 36695@subsubheading Example 36696 36697@smallexample 36698(gdb) 36699-data-write-memory-bytes &a "aabbccdd" 36700^done 36701(gdb) 36702@end smallexample 36703 36704@smallexample 36705(gdb) 36706-data-write-memory-bytes &a "aabbccdd" 16e 36707^done 36708(gdb) 36709@end smallexample 36710 36711@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 36712@node GDB/MI Tracepoint Commands 36713@section @sc{gdb/mi} Tracepoint Commands 36714 36715The commands defined in this section implement MI support for 36716tracepoints. For detailed introduction, see @ref{Tracepoints}. 36717 36718@findex -trace-find 36719@subheading The @code{-trace-find} Command 36720 36721@subsubheading Synopsis 36722 36723@smallexample 36724 -trace-find @var{mode} [@var{parameters}@dots{}] 36725@end smallexample 36726 36727Find a trace frame using criteria defined by @var{mode} and 36728@var{parameters}. The following table lists permissible 36729modes and their parameters. For details of operation, see @ref{tfind}. 36730 36731@table @samp 36732 36733@item none 36734No parameters are required. Stops examining trace frames. 36735 36736@item frame-number 36737An integer is required as parameter. Selects tracepoint frame with 36738that index. 36739 36740@item tracepoint-number 36741An integer is required as parameter. Finds next 36742trace frame that corresponds to tracepoint with the specified number. 36743 36744@item pc 36745An address is required as parameter. Finds 36746next trace frame that corresponds to any tracepoint at the specified 36747address. 36748 36749@item pc-inside-range 36750Two addresses are required as parameters. Finds next trace 36751frame that corresponds to a tracepoint at an address inside the 36752specified range. Both bounds are considered to be inside the range. 36753 36754@item pc-outside-range 36755Two addresses are required as parameters. Finds 36756next trace frame that corresponds to a tracepoint at an address outside 36757the specified range. Both bounds are considered to be inside the range. 36758 36759@item line 36760Location specification is required as parameter. @xref{Location Specifications}. 36761Finds next trace frame that corresponds to a tracepoint at 36762the specified location. 36763 36764@end table 36765 36766If @samp{none} was passed as @var{mode}, the response does not 36767have fields. Otherwise, the response may have the following fields: 36768 36769@table @samp 36770@item found 36771This field has either @samp{0} or @samp{1} as the value, depending 36772on whether a matching tracepoint was found. 36773 36774@item traceframe 36775The index of the found traceframe. This field is present iff 36776the @samp{found} field has value of @samp{1}. 36777 36778@item tracepoint 36779The index of the found tracepoint. This field is present iff 36780the @samp{found} field has value of @samp{1}. 36781 36782@item frame 36783The information about the frame corresponding to the found trace 36784frame. This field is present only if a trace frame was found. 36785@xref{GDB/MI Frame Information}, for description of this field. 36786 36787@end table 36788 36789@subsubheading @value{GDBN} Command 36790 36791The corresponding @value{GDBN} command is @samp{tfind}. 36792 36793@findex -trace-define-variable 36794@subheading The @code{-trace-define-variable} Command 36795 36796@subsubheading Synopsis 36797 36798@smallexample 36799 -trace-define-variable @var{name} [ @var{value} ] 36800@end smallexample 36801 36802Create trace variable @var{name} if it does not exist. If 36803@var{value} is specified, sets the initial value of the specified 36804trace variable to that value. Note that the @var{name} should start 36805with the @samp{$} character. 36806 36807@subsubheading @value{GDBN} Command 36808 36809The corresponding @value{GDBN} command is @samp{tvariable}. 36810 36811@findex -trace-frame-collected 36812@subheading The @code{-trace-frame-collected} Command 36813 36814@subsubheading Synopsis 36815 36816@smallexample 36817 -trace-frame-collected 36818 [--var-print-values @var{var_pval}] 36819 [--comp-print-values @var{comp_pval}] 36820 [--registers-format @var{regformat}] 36821 [--memory-contents] 36822@end smallexample 36823 36824This command returns the set of collected objects, register names, 36825trace state variable names, memory ranges and computed expressions 36826that have been collected at a particular trace frame. The optional 36827parameters to the command affect the output format in different ways. 36828See the output description table below for more details. 36829 36830The reported names can be used in the normal manner to create 36831varobjs and inspect the objects themselves. The items returned by 36832this command are categorized so that it is clear which is a variable, 36833which is a register, which is a trace state variable, which is a 36834memory range and which is a computed expression. 36835 36836For instance, if the actions were 36837@smallexample 36838collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2 36839collect *(int*)0xaf02bef0@@40 36840@end smallexample 36841 36842@noindent 36843the object collected in its entirety would be @code{myVar}. The 36844object @code{myArray} would be partially collected, because only the 36845element at index @code{myIndex} would be collected. The remaining 36846objects would be computed expressions. 36847 36848An example output would be: 36849 36850@smallexample 36851(gdb) 36852-trace-frame-collected 36853^done, 36854 explicit-variables=[@{name="myVar",value="1"@}], 36855 computed-expressions=[@{name="myArray[myIndex]",value="0"@}, 36856 @{name="myObj.field",value="0"@}, 36857 @{name="myPtr->field",value="1"@}, 36858 @{name="myCount + 2",value="3"@}, 36859 @{name="$tvar1 + 1",value="43970027"@}], 36860 registers=[@{number="0",value="0x7fe2c6e79ec8"@}, 36861 @{number="1",value="0x0"@}, 36862 @{number="2",value="0x4"@}, 36863 ... 36864 @{number="125",value="0x0"@}], 36865 tvars=[@{name="$tvar1",current="43970026"@}], 36866 memory=[@{address="0x0000000000602264",length="4"@}, 36867 @{address="0x0000000000615bc0",length="4"@}] 36868(gdb) 36869@end smallexample 36870 36871Where: 36872 36873@table @code 36874@item explicit-variables 36875The set of objects that have been collected in their entirety (as 36876opposed to collecting just a few elements of an array or a few struct 36877members). For each object, its name and value are printed. 36878The @code{--var-print-values} option affects how or whether the value 36879field is output. If @var{var_pval} is 0, then print only the names; 36880if it is 1, print also their values; and if it is 2, print the name, 36881type and value for simple data types, and the name and type for 36882arrays, structures and unions. 36883 36884@item computed-expressions 36885The set of computed expressions that have been collected at the 36886current trace frame. The @code{--comp-print-values} option affects 36887this set like the @code{--var-print-values} option affects the 36888@code{explicit-variables} set. See above. 36889 36890@item registers 36891The registers that have been collected at the current trace frame. 36892For each register collected, the name and current value are returned. 36893The value is formatted according to the @code{--registers-format} 36894option. See the @command{-data-list-register-values} command for a 36895list of the allowed formats. The default is @samp{x}. 36896 36897@item tvars 36898The trace state variables that have been collected at the current 36899trace frame. For each trace state variable collected, the name and 36900current value are returned. 36901 36902@item memory 36903The set of memory ranges that have been collected at the current trace 36904frame. Its content is a list of tuples. Each tuple represents a 36905collected memory range and has the following fields: 36906 36907@table @code 36908@item address 36909The start address of the memory range, as hexadecimal literal. 36910 36911@item length 36912The length of the memory range, as decimal literal. 36913 36914@item contents 36915The contents of the memory block, in hex. This field is only present 36916if the @code{--memory-contents} option is specified. 36917 36918@end table 36919 36920@end table 36921 36922@subsubheading @value{GDBN} Command 36923 36924There is no corresponding @value{GDBN} command. 36925 36926@subsubheading Example 36927 36928@findex -trace-list-variables 36929@subheading The @code{-trace-list-variables} Command 36930 36931@subsubheading Synopsis 36932 36933@smallexample 36934 -trace-list-variables 36935@end smallexample 36936 36937Return a table of all defined trace variables. Each element of the 36938table has the following fields: 36939 36940@table @samp 36941@item name 36942The name of the trace variable. This field is always present. 36943 36944@item initial 36945The initial value. This is a 64-bit signed integer. This 36946field is always present. 36947 36948@item current 36949The value the trace variable has at the moment. This is a 64-bit 36950signed integer. This field is absent iff current value is 36951not defined, for example if the trace was never run, or is 36952presently running. 36953 36954@end table 36955 36956@subsubheading @value{GDBN} Command 36957 36958The corresponding @value{GDBN} command is @samp{tvariables}. 36959 36960@subsubheading Example 36961 36962@smallexample 36963(gdb) 36964-trace-list-variables 36965^done,trace-variables=@{nr_rows="1",nr_cols="3", 36966hdr=[@{width="15",alignment="-1",col_name="name",colhdr="Name"@}, 36967 @{width="11",alignment="-1",col_name="initial",colhdr="Initial"@}, 36968 @{width="11",alignment="-1",col_name="current",colhdr="Current"@}], 36969body=[variable=@{name="$trace_timestamp",initial="0"@} 36970 variable=@{name="$foo",initial="10",current="15"@}]@} 36971(gdb) 36972@end smallexample 36973 36974@findex -trace-save 36975@subheading The @code{-trace-save} Command 36976 36977@subsubheading Synopsis 36978 36979@smallexample 36980 -trace-save [ -r ] [ -ctf ] @var{filename} 36981@end smallexample 36982 36983Saves the collected trace data to @var{filename}. Without the 36984@samp{-r} option, the data is downloaded from the target and saved 36985in a local file. With the @samp{-r} option the target is asked 36986to perform the save. 36987 36988By default, this command will save the trace in the tfile format. You can 36989supply the optional @samp{-ctf} argument to save it the CTF format. See 36990@ref{Trace Files} for more information about CTF. 36991 36992@subsubheading @value{GDBN} Command 36993 36994The corresponding @value{GDBN} command is @samp{tsave}. 36995 36996 36997@findex -trace-start 36998@subheading The @code{-trace-start} Command 36999 37000@subsubheading Synopsis 37001 37002@smallexample 37003 -trace-start 37004@end smallexample 37005 37006Starts a tracing experiment. The result of this command does not 37007have any fields. 37008 37009@subsubheading @value{GDBN} Command 37010 37011The corresponding @value{GDBN} command is @samp{tstart}. 37012 37013@findex -trace-status 37014@subheading The @code{-trace-status} Command 37015 37016@subsubheading Synopsis 37017 37018@smallexample 37019 -trace-status 37020@end smallexample 37021 37022Obtains the status of a tracing experiment. The result may include 37023the following fields: 37024 37025@table @samp 37026 37027@item supported 37028May have a value of either @samp{0}, when no tracing operations are 37029supported, @samp{1}, when all tracing operations are supported, or 37030@samp{file} when examining trace file. In the latter case, examining 37031of trace frame is possible but new tracing experiment cannot be 37032started. This field is always present. 37033 37034@item running 37035May have a value of either @samp{0} or @samp{1} depending on whether 37036tracing experiment is in progress on target. This field is present 37037if @samp{supported} field is not @samp{0}. 37038 37039@item stop-reason 37040Report the reason why the tracing was stopped last time. This field 37041may be absent iff tracing was never stopped on target yet. The 37042value of @samp{request} means the tracing was stopped as result of 37043the @code{-trace-stop} command. The value of @samp{overflow} means 37044the tracing buffer is full. The value of @samp{disconnection} means 37045tracing was automatically stopped when @value{GDBN} has disconnected. 37046The value of @samp{passcount} means tracing was stopped when a 37047tracepoint was passed a maximal number of times for that tracepoint. 37048This field is present if @samp{supported} field is not @samp{0}. 37049 37050@item stopping-tracepoint 37051The number of tracepoint whose passcount as exceeded. This field is 37052present iff the @samp{stop-reason} field has the value of 37053@samp{passcount}. 37054 37055@item frames 37056@itemx frames-created 37057The @samp{frames} field is a count of the total number of trace frames 37058in the trace buffer, while @samp{frames-created} is the total created 37059during the run, including ones that were discarded, such as when a 37060circular trace buffer filled up. Both fields are optional. 37061 37062@item buffer-size 37063@itemx buffer-free 37064These fields tell the current size of the tracing buffer and the 37065remaining space. These fields are optional. 37066 37067@item circular 37068The value of the circular trace buffer flag. @code{1} means that the 37069trace buffer is circular and old trace frames will be discarded if 37070necessary to make room, @code{0} means that the trace buffer is linear 37071and may fill up. 37072 37073@item disconnected 37074The value of the disconnected tracing flag. @code{1} means that 37075tracing will continue after @value{GDBN} disconnects, @code{0} means 37076that the trace run will stop. 37077 37078@item trace-file 37079The filename of the trace file being examined. This field is 37080optional, and only present when examining a trace file. 37081 37082@end table 37083 37084@subsubheading @value{GDBN} Command 37085 37086The corresponding @value{GDBN} command is @samp{tstatus}. 37087 37088@findex -trace-stop 37089@subheading The @code{-trace-stop} Command 37090 37091@subsubheading Synopsis 37092 37093@smallexample 37094 -trace-stop 37095@end smallexample 37096 37097Stops a tracing experiment. The result of this command has the same 37098fields as @code{-trace-status}, except that the @samp{supported} and 37099@samp{running} fields are not output. 37100 37101@subsubheading @value{GDBN} Command 37102 37103The corresponding @value{GDBN} command is @samp{tstop}. 37104 37105 37106@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 37107@node GDB/MI Symbol Query 37108@section @sc{gdb/mi} Symbol Query Commands 37109 37110 37111@ignore 37112@findex -symbol-info-address 37113@subheading The @code{-symbol-info-address} Command 37114 37115@subsubheading Synopsis 37116 37117@smallexample 37118 -symbol-info-address @var{symbol} 37119@end smallexample 37120 37121Describe where @var{symbol} is stored. 37122 37123@subsubheading @value{GDBN} Command 37124 37125The corresponding @value{GDBN} command is @samp{info address}. 37126 37127@subsubheading Example 37128N.A. 37129 37130 37131@findex -symbol-info-file 37132@subheading The @code{-symbol-info-file} Command 37133 37134@subsubheading Synopsis 37135 37136@smallexample 37137 -symbol-info-file 37138@end smallexample 37139 37140Show the file for the symbol. 37141 37142@subsubheading @value{GDBN} Command 37143 37144There's no equivalent @value{GDBN} command. @code{gdbtk} has 37145@samp{gdb_find_file}. 37146 37147@subsubheading Example 37148N.A. 37149@end ignore 37150 37151@findex -symbol-info-functions 37152@anchor{-symbol-info-functions} 37153@subheading The @code{-symbol-info-functions} Command 37154 37155@subsubheading Synopsis 37156 37157@smallexample 37158 -symbol-info-functions [--include-nondebug] 37159 [--type @var{type_regexp}] 37160 [--name @var{name_regexp}] 37161 [--max-results @var{limit}] 37162@end smallexample 37163 37164@noindent 37165Return a list containing the names and types for all global functions 37166taken from the debug information. The functions are grouped by source 37167file, and shown with the line number on which each function is 37168defined. 37169 37170The @code{--include-nondebug} option causes the output to include 37171code symbols from the symbol table. 37172 37173The options @code{--type} and @code{--name} allow the symbols returned 37174to be filtered based on either the name of the function, or the type 37175signature of the function. 37176 37177The option @code{--max-results} restricts the command to return no 37178more than @var{limit} results. If exactly @var{limit} results are 37179returned then there might be additional results available if a higher 37180limit is used. 37181 37182@subsubheading @value{GDBN} Command 37183 37184The corresponding @value{GDBN} command is @samp{info functions}. 37185 37186@subsubheading Example 37187@smallexample 37188@group 37189(gdb) 37190-symbol-info-functions 37191^done,symbols= 37192 @{debug= 37193 [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37194 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37195 symbols=[@{line="36", name="f4", type="void (int *)", 37196 description="void f4(int *);"@}, 37197 @{line="42", name="main", type="int ()", 37198 description="int main();"@}, 37199 @{line="30", name="f1", type="my_int_t (int, int)", 37200 description="static my_int_t f1(int, int);"@}]@}, 37201 @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 37202 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 37203 symbols=[@{line="33", name="f2", type="float (another_float_t)", 37204 description="float f2(another_float_t);"@}, 37205 @{line="39", name="f3", type="int (another_int_t)", 37206 description="int f3(another_int_t);"@}, 37207 @{line="27", name="f1", type="another_float_t (int)", 37208 description="static another_float_t f1(int);"@}]@}]@} 37209@end group 37210@group 37211(gdb) 37212-symbol-info-functions --name f1 37213^done,symbols= 37214 @{debug= 37215 [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37216 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37217 symbols=[@{line="30", name="f1", type="my_int_t (int, int)", 37218 description="static my_int_t f1(int, int);"@}]@}, 37219 @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 37220 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 37221 symbols=[@{line="27", name="f1", type="another_float_t (int)", 37222 description="static another_float_t f1(int);"@}]@}]@} 37223@end group 37224@group 37225(gdb) 37226-symbol-info-functions --type void 37227^done,symbols= 37228 @{debug= 37229 [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37230 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37231 symbols=[@{line="36", name="f4", type="void (int *)", 37232 description="void f4(int *);"@}]@}]@} 37233@end group 37234@group 37235(gdb) 37236-symbol-info-functions --include-nondebug 37237^done,symbols= 37238 @{debug= 37239 [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37240 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37241 symbols=[@{line="36", name="f4", type="void (int *)", 37242 description="void f4(int *);"@}, 37243 @{line="42", name="main", type="int ()", 37244 description="int main();"@}, 37245 @{line="30", name="f1", type="my_int_t (int, int)", 37246 description="static my_int_t f1(int, int);"@}]@}, 37247 @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 37248 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 37249 symbols=[@{line="33", name="f2", type="float (another_float_t)", 37250 description="float f2(another_float_t);"@}, 37251 @{line="39", name="f3", type="int (another_int_t)", 37252 description="int f3(another_int_t);"@}, 37253 @{line="27", name="f1", type="another_float_t (int)", 37254 description="static another_float_t f1(int);"@}]@}], 37255 nondebug= 37256 [@{address="0x0000000000400398",name="_init"@}, 37257 @{address="0x00000000004003b0",name="_start"@}, 37258 ... 37259 ]@} 37260@end group 37261@end smallexample 37262 37263@findex -symbol-info-module-functions 37264@anchor{-symbol-info-module-functions} 37265@subheading The @code{-symbol-info-module-functions} Command 37266 37267@subsubheading Synopsis 37268 37269@smallexample 37270 -symbol-info-module-functions [--module @var{module_regexp}] 37271 [--name @var{name_regexp}] 37272 [--type @var{type_regexp}] 37273@end smallexample 37274 37275@noindent 37276Return a list containing the names of all known functions within all 37277know Fortran modules. The functions are grouped by source file and 37278containing module, and shown with the line number on which each 37279function is defined. 37280 37281The option @code{--module} only returns results for modules matching 37282@var{module_regexp}. The option @code{--name} only returns functions 37283whose name matches @var{name_regexp}, and @code{--type} only returns 37284functions whose type matches @var{type_regexp}. 37285 37286@subsubheading @value{GDBN} Command 37287 37288The corresponding @value{GDBN} command is @samp{info module functions}. 37289 37290@subsubheading Example 37291 37292@smallexample 37293@group 37294(gdb) 37295-symbol-info-module-functions 37296^done,symbols= 37297 [@{module="mod1", 37298 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 37299 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 37300 symbols=[@{line="21",name="mod1::check_all",type="void (void)", 37301 description="void mod1::check_all(void);"@}]@}]@}, 37302 @{module="mod2", 37303 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 37304 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 37305 symbols=[@{line="30",name="mod2::check_var_i",type="void (void)", 37306 description="void mod2::check_var_i(void);"@}]@}]@}, 37307 @{module="mod3", 37308 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 37309 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 37310 symbols=[@{line="21",name="mod3::check_all",type="void (void)", 37311 description="void mod3::check_all(void);"@}, 37312 @{line="27",name="mod3::check_mod2",type="void (void)", 37313 description="void mod3::check_mod2(void);"@}]@}]@}, 37314 @{module="modmany", 37315 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 37316 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 37317 symbols=[@{line="35",name="modmany::check_some",type="void (void)", 37318 description="void modmany::check_some(void);"@}]@}]@}, 37319 @{module="moduse", 37320 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 37321 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 37322 symbols=[@{line="44",name="moduse::check_all",type="void (void)", 37323 description="void moduse::check_all(void);"@}, 37324 @{line="49",name="moduse::check_var_x",type="void (void)", 37325 description="void moduse::check_var_x(void);"@}]@}]@}] 37326@end group 37327@end smallexample 37328 37329@findex -symbol-info-module-variables 37330@anchor{-symbol-info-module-variables} 37331@subheading The @code{-symbol-info-module-variables} Command 37332 37333@subsubheading Synopsis 37334 37335@smallexample 37336 -symbol-info-module-variables [--module @var{module_regexp}] 37337 [--name @var{name_regexp}] 37338 [--type @var{type_regexp}] 37339@end smallexample 37340 37341@noindent 37342Return a list containing the names of all known variables within all 37343know Fortran modules. The variables are grouped by source file and 37344containing module, and shown with the line number on which each 37345variable is defined. 37346 37347The option @code{--module} only returns results for modules matching 37348@var{module_regexp}. The option @code{--name} only returns variables 37349whose name matches @var{name_regexp}, and @code{--type} only returns 37350variables whose type matches @var{type_regexp}. 37351 37352@subsubheading @value{GDBN} Command 37353 37354The corresponding @value{GDBN} command is @samp{info module variables}. 37355 37356@subsubheading Example 37357 37358@smallexample 37359@group 37360(gdb) 37361-symbol-info-module-variables 37362^done,symbols= 37363 [@{module="mod1", 37364 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 37365 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 37366 symbols=[@{line="18",name="mod1::var_const",type="integer(kind=4)", 37367 description="integer(kind=4) mod1::var_const;"@}, 37368 @{line="17",name="mod1::var_i",type="integer(kind=4)", 37369 description="integer(kind=4) mod1::var_i;"@}]@}]@}, 37370 @{module="mod2", 37371 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 37372 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 37373 symbols=[@{line="28",name="mod2::var_i",type="integer(kind=4)", 37374 description="integer(kind=4) mod2::var_i;"@}]@}]@}, 37375 @{module="mod3", 37376 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 37377 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 37378 symbols=[@{line="18",name="mod3::mod1",type="integer(kind=4)", 37379 description="integer(kind=4) mod3::mod1;"@}, 37380 @{line="17",name="mod3::mod2",type="integer(kind=4)", 37381 description="integer(kind=4) mod3::mod2;"@}, 37382 @{line="19",name="mod3::var_i",type="integer(kind=4)", 37383 description="integer(kind=4) mod3::var_i;"@}]@}]@}, 37384 @{module="modmany", 37385 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 37386 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 37387 symbols=[@{line="33",name="modmany::var_a",type="integer(kind=4)", 37388 description="integer(kind=4) modmany::var_a;"@}, 37389 @{line="33",name="modmany::var_b",type="integer(kind=4)", 37390 description="integer(kind=4) modmany::var_b;"@}, 37391 @{line="33",name="modmany::var_c",type="integer(kind=4)", 37392 description="integer(kind=4) modmany::var_c;"@}, 37393 @{line="33",name="modmany::var_i",type="integer(kind=4)", 37394 description="integer(kind=4) modmany::var_i;"@}]@}]@}, 37395 @{module="moduse", 37396 files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 37397 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 37398 symbols=[@{line="42",name="moduse::var_x",type="integer(kind=4)", 37399 description="integer(kind=4) moduse::var_x;"@}, 37400 @{line="42",name="moduse::var_y",type="integer(kind=4)", 37401 description="integer(kind=4) moduse::var_y;"@}]@}]@}] 37402@end group 37403@end smallexample 37404 37405@findex -symbol-info-modules 37406@anchor{-symbol-info-modules} 37407@subheading The @code{-symbol-info-modules} Command 37408 37409@subsubheading Synopsis 37410 37411@smallexample 37412 -symbol-info-modules [--name @var{name_regexp}] 37413 [--max-results @var{limit}] 37414 37415@end smallexample 37416 37417@noindent 37418Return a list containing the names of all known Fortran modules. The 37419modules are grouped by source file, and shown with the line number on 37420which each modules is defined. 37421 37422The option @code{--name} allows the modules returned to be filtered 37423based the name of the module. 37424 37425The option @code{--max-results} restricts the command to return no 37426more than @var{limit} results. If exactly @var{limit} results are 37427returned then there might be additional results available if a higher 37428limit is used. 37429 37430@subsubheading @value{GDBN} Command 37431 37432The corresponding @value{GDBN} command is @samp{info modules}. 37433 37434@subsubheading Example 37435@smallexample 37436@group 37437(gdb) 37438-symbol-info-modules 37439^done,symbols= 37440 @{debug= 37441 [@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 37442 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 37443 symbols=[@{line="16",name="mod1"@}, 37444 @{line="22",name="mod2"@}]@}, 37445 @{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 37446 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 37447 symbols=[@{line="16",name="mod3"@}, 37448 @{line="22",name="modmany"@}, 37449 @{line="26",name="moduse"@}]@}]@} 37450@end group 37451@group 37452(gdb) 37453-symbol-info-modules --name mod[123] 37454^done,symbols= 37455 @{debug= 37456 [@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 37457 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", 37458 symbols=[@{line="16",name="mod1"@}, 37459 @{line="22",name="mod2"@}]@}, 37460 @{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 37461 fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", 37462 symbols=[@{line="16",name="mod3"@}]@}]@} 37463@end group 37464@end smallexample 37465 37466@findex -symbol-info-types 37467@anchor{-symbol-info-types} 37468@subheading The @code{-symbol-info-types} Command 37469 37470@subsubheading Synopsis 37471 37472@smallexample 37473 -symbol-info-types [--name @var{name_regexp}] 37474 [--max-results @var{limit}] 37475 37476@end smallexample 37477 37478@noindent 37479Return a list of all defined types. The types are grouped by source 37480file, and shown with the line number on which each user defined type 37481is defined. Some base types are not defined in the source code but 37482are added to the debug information by the compiler, for example 37483@code{int}, @code{float}, etc.; these types do not have an associated 37484line number. 37485 37486The option @code{--name} allows the list of types returned to be 37487filtered by name. 37488 37489The option @code{--max-results} restricts the command to return no 37490more than @var{limit} results. If exactly @var{limit} results are 37491returned then there might be additional results available if a higher 37492limit is used. 37493 37494@subsubheading @value{GDBN} Command 37495 37496The corresponding @value{GDBN} command is @samp{info types}. 37497 37498@subsubheading Example 37499@smallexample 37500@group 37501(gdb) 37502-symbol-info-types 37503^done,symbols= 37504 @{debug= 37505 [@{filename="gdb.mi/mi-sym-info-1.c", 37506 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37507 symbols=[@{name="float"@}, 37508 @{name="int"@}, 37509 @{line="27",name="typedef int my_int_t;"@}]@}, 37510 @{filename="gdb.mi/mi-sym-info-2.c", 37511 fullname="/project/gdb.mi/mi-sym-info-2.c", 37512 symbols=[@{line="24",name="typedef float another_float_t;"@}, 37513 @{line="23",name="typedef int another_int_t;"@}, 37514 @{name="float"@}, 37515 @{name="int"@}]@}]@} 37516@end group 37517@group 37518(gdb) 37519-symbol-info-types --name _int_ 37520^done,symbols= 37521 @{debug= 37522 [@{filename="gdb.mi/mi-sym-info-1.c", 37523 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37524 symbols=[@{line="27",name="typedef int my_int_t;"@}]@}, 37525 @{filename="gdb.mi/mi-sym-info-2.c", 37526 fullname="/project/gdb.mi/mi-sym-info-2.c", 37527 symbols=[@{line="23",name="typedef int another_int_t;"@}]@}]@} 37528@end group 37529@end smallexample 37530 37531@findex -symbol-info-variables 37532@anchor{-symbol-info-variables} 37533@subheading The @code{-symbol-info-variables} Command 37534 37535@subsubheading Synopsis 37536 37537@smallexample 37538 -symbol-info-variables [--include-nondebug] 37539 [--type @var{type_regexp}] 37540 [--name @var{name_regexp}] 37541 [--max-results @var{limit}] 37542 37543@end smallexample 37544 37545@noindent 37546Return a list containing the names and types for all global variables 37547taken from the debug information. The variables are grouped by source 37548file, and shown with the line number on which each variable is 37549defined. 37550 37551The @code{--include-nondebug} option causes the output to include 37552data symbols from the symbol table. 37553 37554The options @code{--type} and @code{--name} allow the symbols returned 37555to be filtered based on either the name of the variable, or the type 37556of the variable. 37557 37558The option @code{--max-results} restricts the command to return no 37559more than @var{limit} results. If exactly @var{limit} results are 37560returned then there might be additional results available if a higher 37561limit is used. 37562 37563@subsubheading @value{GDBN} Command 37564 37565The corresponding @value{GDBN} command is @samp{info variables}. 37566 37567@subsubheading Example 37568@smallexample 37569@group 37570(gdb) 37571-symbol-info-variables 37572^done,symbols= 37573 @{debug= 37574 [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37575 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37576 symbols=[@{line="25",name="global_f1",type="float", 37577 description="static float global_f1;"@}, 37578 @{line="24",name="global_i1",type="int", 37579 description="static int global_i1;"@}]@}, 37580 @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 37581 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 37582 symbols=[@{line="21",name="global_f2",type="int", 37583 description="int global_f2;"@}, 37584 @{line="20",name="global_i2",type="int", 37585 description="int global_i2;"@}, 37586 @{line="19",name="global_f1",type="float", 37587 description="static float global_f1;"@}, 37588 @{line="18",name="global_i1",type="int", 37589 description="static int global_i1;"@}]@}]@} 37590@end group 37591@group 37592(gdb) 37593-symbol-info-variables --name f1 37594^done,symbols= 37595 @{debug= 37596 [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37597 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37598 symbols=[@{line="25",name="global_f1",type="float", 37599 description="static float global_f1;"@}]@}, 37600 @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 37601 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 37602 symbols=[@{line="19",name="global_f1",type="float", 37603 description="static float global_f1;"@}]@}]@} 37604@end group 37605@group 37606(gdb) 37607-symbol-info-variables --type float 37608^done,symbols= 37609 @{debug= 37610 [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37611 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37612 symbols=[@{line="25",name="global_f1",type="float", 37613 description="static float global_f1;"@}]@}, 37614 @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 37615 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 37616 symbols=[@{line="19",name="global_f1",type="float", 37617 description="static float global_f1;"@}]@}]@} 37618@end group 37619@group 37620(gdb) 37621-symbol-info-variables --include-nondebug 37622^done,symbols= 37623 @{debug= 37624 [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37625 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", 37626 symbols=[@{line="25",name="global_f1",type="float", 37627 description="static float global_f1;"@}, 37628 @{line="24",name="global_i1",type="int", 37629 description="static int global_i1;"@}]@}, 37630 @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 37631 fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", 37632 symbols=[@{line="21",name="global_f2",type="int", 37633 description="int global_f2;"@}, 37634 @{line="20",name="global_i2",type="int", 37635 description="int global_i2;"@}, 37636 @{line="19",name="global_f1",type="float", 37637 description="static float global_f1;"@}, 37638 @{line="18",name="global_i1",type="int", 37639 description="static int global_i1;"@}]@}], 37640 nondebug= 37641 [@{address="0x00000000004005d0",name="_IO_stdin_used"@}, 37642 @{address="0x00000000004005d8",name="__dso_handle"@} 37643 ... 37644 ]@} 37645@end group 37646@end smallexample 37647 37648@ignore 37649@findex -symbol-info-line 37650@subheading The @code{-symbol-info-line} Command 37651 37652@subsubheading Synopsis 37653 37654@smallexample 37655 -symbol-info-line 37656@end smallexample 37657 37658Show the core addresses of the code for a source line. 37659 37660@subsubheading @value{GDBN} Command 37661 37662The corresponding @value{GDBN} command is @samp{info line}. 37663@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands. 37664 37665@subsubheading Example 37666N.A. 37667 37668 37669@findex -symbol-info-symbol 37670@subheading The @code{-symbol-info-symbol} Command 37671 37672@subsubheading Synopsis 37673 37674@smallexample 37675 -symbol-info-symbol @var{addr} 37676@end smallexample 37677 37678Describe what symbol is at location @var{addr}. 37679 37680@subsubheading @value{GDBN} Command 37681 37682The corresponding @value{GDBN} command is @samp{info symbol}. 37683 37684@subsubheading Example 37685N.A. 37686 37687 37688@findex -symbol-list-functions 37689@subheading The @code{-symbol-list-functions} Command 37690 37691@subsubheading Synopsis 37692 37693@smallexample 37694 -symbol-list-functions 37695@end smallexample 37696 37697List the functions in the executable. 37698 37699@subsubheading @value{GDBN} Command 37700 37701@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and 37702@samp{gdb_search} in @code{gdbtk}. 37703 37704@subsubheading Example 37705N.A. 37706@end ignore 37707 37708 37709@findex -symbol-list-lines 37710@subheading The @code{-symbol-list-lines} Command 37711 37712@subsubheading Synopsis 37713 37714@smallexample 37715 -symbol-list-lines @var{filename} 37716@end smallexample 37717 37718Print the list of lines that contain code and their associated program 37719addresses for the given source filename. The entries are sorted in 37720ascending PC order. 37721 37722@subsubheading @value{GDBN} Command 37723 37724There is no corresponding @value{GDBN} command. 37725 37726@subsubheading Example 37727@smallexample 37728(gdb) 37729-symbol-list-lines basics.c 37730^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}] 37731(gdb) 37732@end smallexample 37733 37734 37735@ignore 37736@findex -symbol-list-types 37737@subheading The @code{-symbol-list-types} Command 37738 37739@subsubheading Synopsis 37740 37741@smallexample 37742 -symbol-list-types 37743@end smallexample 37744 37745List all the type names. 37746 37747@subsubheading @value{GDBN} Command 37748 37749The corresponding commands are @samp{info types} in @value{GDBN}, 37750@samp{gdb_search} in @code{gdbtk}. 37751 37752@subsubheading Example 37753N.A. 37754 37755 37756@findex -symbol-list-variables 37757@subheading The @code{-symbol-list-variables} Command 37758 37759@subsubheading Synopsis 37760 37761@smallexample 37762 -symbol-list-variables 37763@end smallexample 37764 37765List all the global and static variable names. 37766 37767@subsubheading @value{GDBN} Command 37768 37769@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}. 37770 37771@subsubheading Example 37772N.A. 37773 37774 37775@findex -symbol-locate 37776@subheading The @code{-symbol-locate} Command 37777 37778@subsubheading Synopsis 37779 37780@smallexample 37781 -symbol-locate 37782@end smallexample 37783 37784@subsubheading @value{GDBN} Command 37785 37786@samp{gdb_loc} in @code{gdbtk}. 37787 37788@subsubheading Example 37789N.A. 37790 37791 37792@findex -symbol-type 37793@subheading The @code{-symbol-type} Command 37794 37795@subsubheading Synopsis 37796 37797@smallexample 37798 -symbol-type @var{variable} 37799@end smallexample 37800 37801Show type of @var{variable}. 37802 37803@subsubheading @value{GDBN} Command 37804 37805The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has 37806@samp{gdb_obj_variable}. 37807 37808@subsubheading Example 37809N.A. 37810@end ignore 37811 37812 37813@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 37814@node GDB/MI File Commands 37815@section @sc{gdb/mi} File Commands 37816 37817This section describes the GDB/MI commands to specify executable file names 37818and to read in and obtain symbol table information. 37819 37820@findex -file-exec-and-symbols 37821@subheading The @code{-file-exec-and-symbols} Command 37822 37823@subsubheading Synopsis 37824 37825@smallexample 37826 -file-exec-and-symbols @var{file} 37827@end smallexample 37828 37829Specify the executable file to be debugged. This file is the one from 37830which the symbol table is also read. If no file is specified, the 37831command clears the executable and symbol information. If breakpoints 37832are set when using this command with no arguments, @value{GDBN} will produce 37833error messages. Otherwise, no output is produced, except a completion 37834notification. 37835 37836@subsubheading @value{GDBN} Command 37837 37838The corresponding @value{GDBN} command is @samp{file}. 37839 37840@subsubheading Example 37841 37842@smallexample 37843(gdb) 37844-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 37845^done 37846(gdb) 37847@end smallexample 37848 37849 37850@findex -file-exec-file 37851@subheading The @code{-file-exec-file} Command 37852 37853@subsubheading Synopsis 37854 37855@smallexample 37856 -file-exec-file @var{file} 37857@end smallexample 37858 37859Specify the executable file to be debugged. Unlike 37860@samp{-file-exec-and-symbols}, the symbol table is @emph{not} read 37861from this file. If used without argument, @value{GDBN} clears the information 37862about the executable file. No output is produced, except a completion 37863notification. 37864 37865@subsubheading @value{GDBN} Command 37866 37867The corresponding @value{GDBN} command is @samp{exec-file}. 37868 37869@subsubheading Example 37870 37871@smallexample 37872(gdb) 37873-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 37874^done 37875(gdb) 37876@end smallexample 37877 37878 37879@ignore 37880@findex -file-list-exec-sections 37881@subheading The @code{-file-list-exec-sections} Command 37882 37883@subsubheading Synopsis 37884 37885@smallexample 37886 -file-list-exec-sections 37887@end smallexample 37888 37889List the sections of the current executable file. 37890 37891@subsubheading @value{GDBN} Command 37892 37893The @value{GDBN} command @samp{info file} shows, among the rest, the same 37894information as this command. @code{gdbtk} has a corresponding command 37895@samp{gdb_load_info}. 37896 37897@subsubheading Example 37898N.A. 37899@end ignore 37900 37901 37902@findex -file-list-exec-source-file 37903@subheading The @code{-file-list-exec-source-file} Command 37904 37905@subsubheading Synopsis 37906 37907@smallexample 37908 -file-list-exec-source-file 37909@end smallexample 37910 37911List the line number, the current source file, and the absolute path 37912to the current source file for the current executable. The macro 37913information field has a value of @samp{1} or @samp{0} depending on 37914whether or not the file includes preprocessor macro information. 37915 37916@subsubheading @value{GDBN} Command 37917 37918The @value{GDBN} equivalent is @samp{info source} 37919 37920@subsubheading Example 37921 37922@smallexample 37923(gdb) 37924123-file-list-exec-source-file 37925123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1" 37926(gdb) 37927@end smallexample 37928 37929 37930@findex -file-list-exec-source-files 37931@subheading The @code{-file-list-exec-source-files} Command 37932@kindex info sources 37933 37934@subsubheading Synopsis 37935 37936@smallexample 37937 -file-list-exec-source-files @r{[} @var{--group-by-objfile} @r{]} 37938 @r{[} @var{--dirname} @r{|} @var{--basename} @r{]} 37939 @r{[} -- @r{]} 37940 @r{[} @var{regexp} @r{]} 37941@end smallexample 37942 37943This command returns information about the source files @value{GDBN} 37944knows about, it will output both the filename and fullname (absolute 37945file name) of a source file, though the fullname can be elided if this 37946information is not known to @value{GDBN}. 37947 37948With no arguments this command returns a list of source files. Each 37949source file is represented by a tuple with the fields; @var{file}, 37950@var{fullname}, and @var{debug-fully-read}. The @var{file} is the 37951display name for the file, while @var{fullname} is the absolute name 37952of the file. The @var{fullname} field can be elided if the absolute 37953name of the source file can't be computed. The field 37954@var{debug-fully-read} will be a string, either @code{true} or 37955@code{false}. When @code{true}, this indicates the full debug 37956information for the compilation unit describing this file has been 37957read in. When @code{false}, the full debug information has not yet 37958been read in. While reading in the full debug information it is 37959possible that @value{GDBN} could become aware of additional source 37960files. 37961 37962The optional @var{regexp} can be used to filter the list of source 37963files returned. The @var{regexp} will be matched against the full 37964source file name. The matching is case-sensitive, except on operating 37965systems that have case-insensitive filesystem (e.g., 37966MS-Windows). @samp{--} can be used before @var{regexp} to prevent 37967@value{GDBN} interpreting @var{regexp} as a command option (e.g.@: if 37968@var{regexp} starts with @samp{-}). 37969 37970If @code{--dirname} is provided, then @var{regexp} is matched only 37971against the directory name of each source file. If @code{--basename} 37972is provided, then @var{regexp} is matched against the basename of each 37973source file. Only one of @code{--dirname} or @code{--basename} may be 37974given, and if either is given then @var{regexp} is required. 37975 37976If @code{--group-by-objfile} is used then the format of the results is 37977changed. The results will now be a list of tuples, with each tuple 37978representing an object file (executable or shared library) loaded into 37979@value{GDBN}. The fields of these tuples are; @var{filename}, 37980@var{debug-info}, and @var{sources}. The @var{filename} is the 37981absolute name of the object file, @var{debug-info} is a string with 37982one of the following values: 37983 37984@table @code 37985@item none 37986This object file has no debug information. 37987@item partially-read 37988This object file has debug information, but it is not fully read in 37989yet. When it is read in later, GDB might become aware of additional 37990source files. 37991@item fully-read 37992This object file has debug information, and this information is fully 37993read into GDB. The list of source files is complete. 37994@end table 37995 37996The @var{sources} is a list or tuples, with each tuple describing a 37997single source file with the same fields as described previously. The 37998@var{sources} list can be empty for object files that have no debug 37999information. 38000 38001@subsubheading @value{GDBN} Command 38002 38003The @value{GDBN} equivalent is @samp{info sources}. 38004@code{gdbtk} has an analogous command @samp{gdb_listfiles}. 38005 38006@subsubheading Example 38007@smallexample 38008(@value{GDBP}) 38009-file-list-exec-source-files 38010^done,files=[@{file="foo.c",fullname="/home/foo.c",debug-fully-read="true"@}, 38011 @{file="/home/bar.c",fullname="/home/bar.c",debug-fully-read="true"@}, 38012 @{file="gdb_could_not_find_fullpath.c",debug-fully-read="true"@}] 38013(@value{GDBP}) 38014-file-list-exec-source-files 38015^done,files=[@{file="test.c", 38016 fullname="/tmp/info-sources/test.c", 38017 debug-fully-read="true"@}, 38018 @{file="/usr/include/stdc-predef.h", 38019 fullname="/usr/include/stdc-predef.h", 38020 debug-fully-read="true"@}, 38021 @{file="header.h", 38022 fullname="/tmp/info-sources/header.h", 38023 debug-fully-read="true"@}, 38024 @{file="helper.c", 38025 fullname="/tmp/info-sources/helper.c", 38026 debug-fully-read="true"@}] 38027(@value{GDBP}) 38028-file-list-exec-source-files -- \\.c 38029^done,files=[@{file="test.c", 38030 fullname="/tmp/info-sources/test.c", 38031 debug-fully-read="true"@}, 38032 @{file="helper.c", 38033 fullname="/tmp/info-sources/helper.c", 38034 debug-fully-read="true"@}] 38035(@value{GDBP}) 38036-file-list-exec-source-files --group-by-objfile 38037^done,files=[@{filename="/tmp/info-sources/test.x", 38038 debug-info="fully-read", 38039 sources=[@{file="test.c", 38040 fullname="/tmp/info-sources/test.c", 38041 debug-fully-read="true"@}, 38042 @{file="/usr/include/stdc-predef.h", 38043 fullname="/usr/include/stdc-predef.h", 38044 debug-fully-read="true"@}, 38045 @{file="header.h", 38046 fullname="/tmp/info-sources/header.h", 38047 debug-fully-read="true"@}]@}, 38048 @{filename="/lib64/ld-linux-x86-64.so.2", 38049 debug-info="none", 38050 sources=[]@}, 38051 @{filename="system-supplied DSO at 0x7ffff7fcf000", 38052 debug-info="none", 38053 sources=[]@}, 38054 @{filename="/tmp/info-sources/libhelper.so", 38055 debug-info="fully-read", 38056 sources=[@{file="helper.c", 38057 fullname="/tmp/info-sources/helper.c", 38058 debug-fully-read="true"@}, 38059 @{file="/usr/include/stdc-predef.h", 38060 fullname="/usr/include/stdc-predef.h", 38061 debug-fully-read="true"@}, 38062 @{file="header.h", 38063 fullname="/tmp/info-sources/header.h", 38064 debug-fully-read="true"@}]@}, 38065 @{filename="/lib64/libc.so.6", 38066 debug-info="none", 38067 sources=[]@}] 38068@end smallexample 38069 38070@findex -file-list-shared-libraries 38071@subheading The @code{-file-list-shared-libraries} Command 38072 38073@subsubheading Synopsis 38074 38075@smallexample 38076 -file-list-shared-libraries [ @var{regexp} ] 38077@end smallexample 38078 38079List the shared libraries in the program. 38080With a regular expression @var{regexp}, only those libraries whose 38081names match @var{regexp} are listed. 38082 38083@subsubheading @value{GDBN} Command 38084 38085The corresponding @value{GDBN} command is @samp{info shared}. The fields 38086have a similar meaning to the @code{=library-loaded} notification. 38087The @code{ranges} field specifies the multiple segments belonging to this 38088library. Each range has the following fields: 38089 38090@table @samp 38091@item from 38092The address defining the inclusive lower bound of the segment. 38093@item to 38094The address defining the exclusive upper bound of the segment. 38095@end table 38096 38097@subsubheading Example 38098@smallexample 38099(gdb) 38100-file-list-exec-source-files 38101^done,shared-libraries=[ 38102@{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"@}]@}, 38103@{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"@}]@}] 38104(gdb) 38105@end smallexample 38106 38107 38108@ignore 38109@findex -file-list-symbol-files 38110@subheading The @code{-file-list-symbol-files} Command 38111 38112@subsubheading Synopsis 38113 38114@smallexample 38115 -file-list-symbol-files 38116@end smallexample 38117 38118List symbol files. 38119 38120@subsubheading @value{GDBN} Command 38121 38122The corresponding @value{GDBN} command is @samp{info file} (part of it). 38123 38124@subsubheading Example 38125N.A. 38126@end ignore 38127 38128 38129@findex -file-symbol-file 38130@subheading The @code{-file-symbol-file} Command 38131 38132@subsubheading Synopsis 38133 38134@smallexample 38135 -file-symbol-file @var{file} 38136@end smallexample 38137 38138Read symbol table info from the specified @var{file} argument. When 38139used without arguments, clears @value{GDBN}'s symbol table info. No output is 38140produced, except for a completion notification. 38141 38142@subsubheading @value{GDBN} Command 38143 38144The corresponding @value{GDBN} command is @samp{symbol-file}. 38145 38146@subsubheading Example 38147 38148@smallexample 38149(gdb) 38150-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 38151^done 38152(gdb) 38153@end smallexample 38154 38155@ignore 38156@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 38157@node GDB/MI Memory Overlay Commands 38158@section @sc{gdb/mi} Memory Overlay Commands 38159 38160The memory overlay commands are not implemented. 38161 38162@c @subheading -overlay-auto 38163 38164@c @subheading -overlay-list-mapping-state 38165 38166@c @subheading -overlay-list-overlays 38167 38168@c @subheading -overlay-map 38169 38170@c @subheading -overlay-off 38171 38172@c @subheading -overlay-on 38173 38174@c @subheading -overlay-unmap 38175 38176@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 38177@node GDB/MI Signal Handling Commands 38178@section @sc{gdb/mi} Signal Handling Commands 38179 38180Signal handling commands are not implemented. 38181 38182@c @subheading -signal-handle 38183 38184@c @subheading -signal-list-handle-actions 38185 38186@c @subheading -signal-list-signal-types 38187@end ignore 38188 38189 38190@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 38191@node GDB/MI Target Manipulation 38192@section @sc{gdb/mi} Target Manipulation Commands 38193 38194 38195@findex -target-attach 38196@subheading The @code{-target-attach} Command 38197 38198@subsubheading Synopsis 38199 38200@smallexample 38201 -target-attach @var{pid} | @var{gid} | @var{file} 38202@end smallexample 38203 38204Attach to a process @var{pid} or a file @var{file} outside of 38205@value{GDBN}, or a thread group @var{gid}. If attaching to a thread 38206group, the id previously returned by 38207@samp{-list-thread-groups --available} must be used. 38208 38209@subsubheading @value{GDBN} Command 38210 38211The corresponding @value{GDBN} command is @samp{attach}. 38212 38213@subsubheading Example 38214@smallexample 38215(gdb) 38216-target-attach 34 38217=thread-created,id="1" 38218*stopped,thread-id="1",frame=@{addr="0xb7f7e410",func="bar",args=[]@} 38219^done 38220(gdb) 38221@end smallexample 38222 38223@ignore 38224@findex -target-compare-sections 38225@subheading The @code{-target-compare-sections} Command 38226 38227@subsubheading Synopsis 38228 38229@smallexample 38230 -target-compare-sections [ @var{section} ] 38231@end smallexample 38232 38233Compare data of section @var{section} on target to the exec file. 38234Without the argument, all sections are compared. 38235 38236@subsubheading @value{GDBN} Command 38237 38238The @value{GDBN} equivalent is @samp{compare-sections}. 38239 38240@subsubheading Example 38241N.A. 38242@end ignore 38243 38244 38245@findex -target-detach 38246@subheading The @code{-target-detach} Command 38247 38248@subsubheading Synopsis 38249 38250@smallexample 38251 -target-detach [ @var{pid} | @var{gid} ] 38252@end smallexample 38253 38254Detach from the remote target which normally resumes its execution. 38255If either @var{pid} or @var{gid} is specified, detaches from either 38256the specified process, or specified thread group. There's no output. 38257 38258@subsubheading @value{GDBN} Command 38259 38260The corresponding @value{GDBN} command is @samp{detach}. 38261 38262@subsubheading Example 38263 38264@smallexample 38265(gdb) 38266-target-detach 38267^done 38268(gdb) 38269@end smallexample 38270 38271 38272@findex -target-disconnect 38273@subheading The @code{-target-disconnect} Command 38274 38275@subsubheading Synopsis 38276 38277@smallexample 38278 -target-disconnect 38279@end smallexample 38280 38281Disconnect from the remote target. There's no output and the target is 38282generally not resumed. 38283 38284@subsubheading @value{GDBN} Command 38285 38286The corresponding @value{GDBN} command is @samp{disconnect}. 38287 38288@subsubheading Example 38289 38290@smallexample 38291(gdb) 38292-target-disconnect 38293^done 38294(gdb) 38295@end smallexample 38296 38297 38298@findex -target-download 38299@subheading The @code{-target-download} Command 38300 38301@subsubheading Synopsis 38302 38303@smallexample 38304 -target-download 38305@end smallexample 38306 38307Loads the executable onto the remote target. 38308It prints out an update message every half second, which includes the fields: 38309 38310@table @samp 38311@item section 38312The name of the section. 38313@item section-sent 38314The size of what has been sent so far for that section. 38315@item section-size 38316The size of the section. 38317@item total-sent 38318The total size of what was sent so far (the current and the previous sections). 38319@item total-size 38320The size of the overall executable to download. 38321@end table 38322 38323@noindent 38324Each message is sent as status record (@pxref{GDB/MI Output Syntax, , 38325@sc{gdb/mi} Output Syntax}). 38326 38327In addition, it prints the name and size of the sections, as they are 38328downloaded. These messages include the following fields: 38329 38330@table @samp 38331@item section 38332The name of the section. 38333@item section-size 38334The size of the section. 38335@item total-size 38336The size of the overall executable to download. 38337@end table 38338 38339@noindent 38340At the end, a summary is printed. 38341 38342@subsubheading @value{GDBN} Command 38343 38344The corresponding @value{GDBN} command is @samp{load}. 38345 38346@subsubheading Example 38347 38348Note: each status message appears on a single line. Here the messages 38349have been broken down so that they can fit onto a page. 38350 38351@smallexample 38352(gdb) 38353-target-download 38354+download,@{section=".text",section-size="6668",total-size="9880"@} 38355+download,@{section=".text",section-sent="512",section-size="6668", 38356total-sent="512",total-size="9880"@} 38357+download,@{section=".text",section-sent="1024",section-size="6668", 38358total-sent="1024",total-size="9880"@} 38359+download,@{section=".text",section-sent="1536",section-size="6668", 38360total-sent="1536",total-size="9880"@} 38361+download,@{section=".text",section-sent="2048",section-size="6668", 38362total-sent="2048",total-size="9880"@} 38363+download,@{section=".text",section-sent="2560",section-size="6668", 38364total-sent="2560",total-size="9880"@} 38365+download,@{section=".text",section-sent="3072",section-size="6668", 38366total-sent="3072",total-size="9880"@} 38367+download,@{section=".text",section-sent="3584",section-size="6668", 38368total-sent="3584",total-size="9880"@} 38369+download,@{section=".text",section-sent="4096",section-size="6668", 38370total-sent="4096",total-size="9880"@} 38371+download,@{section=".text",section-sent="4608",section-size="6668", 38372total-sent="4608",total-size="9880"@} 38373+download,@{section=".text",section-sent="5120",section-size="6668", 38374total-sent="5120",total-size="9880"@} 38375+download,@{section=".text",section-sent="5632",section-size="6668", 38376total-sent="5632",total-size="9880"@} 38377+download,@{section=".text",section-sent="6144",section-size="6668", 38378total-sent="6144",total-size="9880"@} 38379+download,@{section=".text",section-sent="6656",section-size="6668", 38380total-sent="6656",total-size="9880"@} 38381+download,@{section=".init",section-size="28",total-size="9880"@} 38382+download,@{section=".fini",section-size="28",total-size="9880"@} 38383+download,@{section=".data",section-size="3156",total-size="9880"@} 38384+download,@{section=".data",section-sent="512",section-size="3156", 38385total-sent="7236",total-size="9880"@} 38386+download,@{section=".data",section-sent="1024",section-size="3156", 38387total-sent="7748",total-size="9880"@} 38388+download,@{section=".data",section-sent="1536",section-size="3156", 38389total-sent="8260",total-size="9880"@} 38390+download,@{section=".data",section-sent="2048",section-size="3156", 38391total-sent="8772",total-size="9880"@} 38392+download,@{section=".data",section-sent="2560",section-size="3156", 38393total-sent="9284",total-size="9880"@} 38394+download,@{section=".data",section-sent="3072",section-size="3156", 38395total-sent="9796",total-size="9880"@} 38396^done,address="0x10004",load-size="9880",transfer-rate="6586", 38397write-rate="429" 38398(gdb) 38399@end smallexample 38400 38401 38402@ignore 38403@findex -target-exec-status 38404@subheading The @code{-target-exec-status} Command 38405 38406@subsubheading Synopsis 38407 38408@smallexample 38409 -target-exec-status 38410@end smallexample 38411 38412Provide information on the state of the target (whether it is running or 38413not, for instance). 38414 38415@subsubheading @value{GDBN} Command 38416 38417There's no equivalent @value{GDBN} command. 38418 38419@subsubheading Example 38420N.A. 38421 38422 38423@findex -target-list-available-targets 38424@subheading The @code{-target-list-available-targets} Command 38425 38426@subsubheading Synopsis 38427 38428@smallexample 38429 -target-list-available-targets 38430@end smallexample 38431 38432List the possible targets to connect to. 38433 38434@subsubheading @value{GDBN} Command 38435 38436The corresponding @value{GDBN} command is @samp{help target}. 38437 38438@subsubheading Example 38439N.A. 38440 38441 38442@findex -target-list-current-targets 38443@subheading The @code{-target-list-current-targets} Command 38444 38445@subsubheading Synopsis 38446 38447@smallexample 38448 -target-list-current-targets 38449@end smallexample 38450 38451Describe the current target. 38452 38453@subsubheading @value{GDBN} Command 38454 38455The corresponding information is printed by @samp{info file} (among 38456other things). 38457 38458@subsubheading Example 38459N.A. 38460 38461 38462@findex -target-list-parameters 38463@subheading The @code{-target-list-parameters} Command 38464 38465@subsubheading Synopsis 38466 38467@smallexample 38468 -target-list-parameters 38469@end smallexample 38470 38471@c ???? 38472@end ignore 38473 38474@subsubheading @value{GDBN} Command 38475 38476No equivalent. 38477 38478@subsubheading Example 38479N.A. 38480 38481@findex -target-flash-erase 38482@subheading The @code{-target-flash-erase} Command 38483 38484@subsubheading Synopsis 38485 38486@smallexample 38487 -target-flash-erase 38488@end smallexample 38489 38490Erases all known flash memory regions on the target. 38491 38492The corresponding @value{GDBN} command is @samp{flash-erase}. 38493 38494The output is a list of flash regions that have been erased, with starting 38495addresses and memory region sizes. 38496 38497@smallexample 38498(gdb) 38499-target-flash-erase 38500^done,erased-regions=@{address="0x0",size="0x40000"@} 38501(gdb) 38502@end smallexample 38503 38504@findex -target-select 38505@subheading The @code{-target-select} Command 38506 38507@subsubheading Synopsis 38508 38509@smallexample 38510 -target-select @var{type} @var{parameters @dots{}} 38511@end smallexample 38512 38513Connect @value{GDBN} to the remote target. This command takes two args: 38514 38515@table @samp 38516@item @var{type} 38517The type of target, for instance @samp{remote}, etc. 38518@item @var{parameters} 38519Device names, host names and the like. @xref{Target Commands, , 38520Commands for Managing Targets}, for more details. 38521@end table 38522 38523The output is a connection notification, followed by the address at 38524which the target program is, in the following form: 38525 38526@smallexample 38527^connected,addr="@var{address}",func="@var{function name}", 38528 args=[@var{arg list}] 38529@end smallexample 38530 38531@subsubheading @value{GDBN} Command 38532 38533The corresponding @value{GDBN} command is @samp{target}. 38534 38535@subsubheading Example 38536 38537@smallexample 38538(gdb) 38539-target-select remote /dev/ttya 38540^connected,addr="0xfe00a300",func="??",args=[] 38541(gdb) 38542@end smallexample 38543 38544@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 38545@node GDB/MI File Transfer Commands 38546@section @sc{gdb/mi} File Transfer Commands 38547 38548 38549@findex -target-file-put 38550@subheading The @code{-target-file-put} Command 38551 38552@subsubheading Synopsis 38553 38554@smallexample 38555 -target-file-put @var{hostfile} @var{targetfile} 38556@end smallexample 38557 38558Copy file @var{hostfile} from the host system (the machine running 38559@value{GDBN}) to @var{targetfile} on the target system. 38560 38561@subsubheading @value{GDBN} Command 38562 38563The corresponding @value{GDBN} command is @samp{remote put}. 38564 38565@subsubheading Example 38566 38567@smallexample 38568(gdb) 38569-target-file-put localfile remotefile 38570^done 38571(gdb) 38572@end smallexample 38573 38574 38575@findex -target-file-get 38576@subheading The @code{-target-file-get} Command 38577 38578@subsubheading Synopsis 38579 38580@smallexample 38581 -target-file-get @var{targetfile} @var{hostfile} 38582@end smallexample 38583 38584Copy file @var{targetfile} from the target system to @var{hostfile} 38585on the host system. 38586 38587@subsubheading @value{GDBN} Command 38588 38589The corresponding @value{GDBN} command is @samp{remote get}. 38590 38591@subsubheading Example 38592 38593@smallexample 38594(gdb) 38595-target-file-get remotefile localfile 38596^done 38597(gdb) 38598@end smallexample 38599 38600 38601@findex -target-file-delete 38602@subheading The @code{-target-file-delete} Command 38603 38604@subsubheading Synopsis 38605 38606@smallexample 38607 -target-file-delete @var{targetfile} 38608@end smallexample 38609 38610Delete @var{targetfile} from the target system. 38611 38612@subsubheading @value{GDBN} Command 38613 38614The corresponding @value{GDBN} command is @samp{remote delete}. 38615 38616@subsubheading Example 38617 38618@smallexample 38619(gdb) 38620-target-file-delete remotefile 38621^done 38622(gdb) 38623@end smallexample 38624 38625 38626@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 38627@node GDB/MI Ada Exceptions Commands 38628@section Ada Exceptions @sc{gdb/mi} Commands 38629 38630@findex -info-ada-exceptions 38631@subheading The @code{-info-ada-exceptions} Command 38632 38633@subsubheading Synopsis 38634 38635@smallexample 38636 -info-ada-exceptions [ @var{regexp}] 38637@end smallexample 38638 38639List all Ada exceptions defined within the program being debugged. 38640With a regular expression @var{regexp}, only those exceptions whose 38641names match @var{regexp} are listed. 38642 38643@subsubheading @value{GDBN} Command 38644 38645The corresponding @value{GDBN} command is @samp{info exceptions}. 38646 38647@subsubheading Result 38648 38649The result is a table of Ada exceptions. The following columns are 38650defined for each exception: 38651 38652@table @samp 38653@item name 38654The name of the exception. 38655 38656@item address 38657The address of the exception. 38658 38659@end table 38660 38661@subsubheading Example 38662 38663@smallexample 38664-info-ada-exceptions aint 38665^done,ada-exceptions=@{nr_rows="2",nr_cols="2", 38666hdr=[@{width="1",alignment="-1",col_name="name",colhdr="Name"@}, 38667@{width="1",alignment="-1",col_name="address",colhdr="Address"@}], 38668body=[@{name="constraint_error",address="0x0000000000613da0"@}, 38669@{name="const.aint_global_e",address="0x0000000000613b00"@}]@} 38670@end smallexample 38671 38672@subheading Catching Ada Exceptions 38673 38674The commands describing how to ask @value{GDBN} to stop when a program 38675raises an exception are described at @ref{Ada Exception GDB/MI 38676Catchpoint Commands}. 38677 38678 38679@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 38680@node GDB/MI Support Commands 38681@section @sc{gdb/mi} Support Commands 38682 38683Since new commands and features get regularly added to @sc{gdb/mi}, 38684some commands are available to help front-ends query the debugger 38685about support for these capabilities. Similarly, it is also possible 38686to query @value{GDBN} about target support of certain features. 38687 38688@cindex @code{-info-gdb-mi-command} 38689@findex -info-gdb-mi-command 38690@subheading The @code{-info-gdb-mi-command} Command 38691 38692@subsubheading Synopsis 38693 38694@smallexample 38695 -info-gdb-mi-command @var{cmd_name} 38696@end smallexample 38697 38698Query support for the @sc{gdb/mi} command named @var{cmd_name}. 38699 38700Note that the dash (@code{-}) starting all @sc{gdb/mi} commands 38701is technically not part of the command name (@pxref{GDB/MI Input 38702Syntax}), and thus should be omitted in @var{cmd_name}. However, 38703for ease of use, this command also accepts the form with the leading 38704dash. 38705 38706@subsubheading @value{GDBN} Command 38707 38708There is no corresponding @value{GDBN} command. 38709 38710@subsubheading Result 38711 38712The result is a tuple. There is currently only one field: 38713 38714@table @samp 38715@item exists 38716This field is equal to @code{"true"} if the @sc{gdb/mi} command exists, 38717@code{"false"} otherwise. 38718 38719@end table 38720 38721@subsubheading Example 38722 38723Here is an example where the @sc{gdb/mi} command does not exist: 38724 38725@smallexample 38726-info-gdb-mi-command unsupported-command 38727^done,command=@{exists="false"@} 38728@end smallexample 38729 38730@noindent 38731And here is an example where the @sc{gdb/mi} command is known 38732to the debugger: 38733 38734@smallexample 38735-info-gdb-mi-command symbol-list-lines 38736^done,command=@{exists="true"@} 38737@end smallexample 38738 38739@findex -list-features 38740@cindex supported @sc{gdb/mi} features, list 38741@subheading The @code{-list-features} Command 38742 38743Returns a list of particular features of the MI protocol that 38744this version of gdb implements. A feature can be a command, 38745or a new field in an output of some command, or even an 38746important bugfix. While a frontend can sometimes detect presence 38747of a feature at runtime, it is easier to perform detection at debugger 38748startup. 38749 38750The command returns a list of strings, with each string naming an 38751available feature. Each returned string is just a name, it does not 38752have any internal structure. The list of possible feature names 38753is given below. 38754 38755Example output: 38756 38757@smallexample 38758(gdb) -list-features 38759^done,result=["feature1","feature2"] 38760@end smallexample 38761 38762The current list of features is: 38763 38764@ftable @samp 38765@item frozen-varobjs 38766Indicates support for the @code{-var-set-frozen} command, as well 38767as possible presence of the @code{frozen} field in the output 38768of @code{-varobj-create}. 38769@item pending-breakpoints 38770Indicates support for the @option{-f} option to the @code{-break-insert} 38771command. 38772@item python 38773Indicates Python scripting support, Python-based 38774pretty-printing commands, and possible presence of the 38775@samp{display_hint} field in the output of @code{-var-list-children} 38776@item thread-info 38777Indicates support for the @code{-thread-info} command. 38778@item data-read-memory-bytes 38779Indicates support for the @code{-data-read-memory-bytes} and the 38780@code{-data-write-memory-bytes} commands. 38781@item breakpoint-notifications 38782Indicates that changes to breakpoints and breakpoints created via the 38783CLI will be announced via async records. 38784@item ada-task-info 38785Indicates support for the @code{-ada-task-info} command. 38786@item language-option 38787Indicates that all @sc{gdb/mi} commands accept the @option{--language} 38788option (@pxref{Context management}). 38789@item info-gdb-mi-command 38790Indicates support for the @code{-info-gdb-mi-command} command. 38791@item undefined-command-error-code 38792Indicates support for the "undefined-command" error code in error result 38793records, produced when trying to execute an undefined @sc{gdb/mi} command 38794(@pxref{GDB/MI Result Records}). 38795@item exec-run-start-option 38796Indicates that the @code{-exec-run} command supports the @option{--start} 38797option (@pxref{GDB/MI Program Execution}). 38798@item data-disassemble-a-option 38799Indicates that the @code{-data-disassemble} command supports the @option{-a} 38800option (@pxref{GDB/MI Data Manipulation}). 38801@item simple-values-ref-types 38802Indicates that the @code{--simple-values} argument to the 38803@code{-stack-list-arguments}, @code{-stack-list-locals}, 38804@code{-stack-list-variables}, and @code{-var-list-children} commands 38805takes reference types into account: that is, a value is considered 38806simple if it is neither an array, structure, or union, nor a reference 38807to an array, structure, or union. 38808@end ftable 38809 38810@findex -list-target-features 38811@subheading The @code{-list-target-features} Command 38812 38813Returns a list of particular features that are supported by the 38814target. Those features affect the permitted MI commands, but 38815unlike the features reported by the @code{-list-features} command, the 38816features depend on which target GDB is using at the moment. Whenever 38817a target can change, due to commands such as @code{-target-select}, 38818@code{-target-attach} or @code{-exec-run}, the list of target features 38819may change, and the frontend should obtain it again. 38820Example output: 38821 38822@smallexample 38823(gdb) -list-target-features 38824^done,result=["async"] 38825@end smallexample 38826 38827The current list of features is: 38828 38829@table @samp 38830@item async 38831Indicates that the target is capable of asynchronous command 38832execution, which means that @value{GDBN} will accept further commands 38833while the target is running. 38834 38835@item reverse 38836Indicates that the target is capable of reverse execution. 38837@xref{Reverse Execution}, for more information. 38838 38839@end table 38840 38841@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 38842@node GDB/MI Miscellaneous Commands 38843@section Miscellaneous @sc{gdb/mi} Commands 38844 38845@c @subheading -gdb-complete 38846 38847@findex -gdb-exit 38848@subheading The @code{-gdb-exit} Command 38849 38850@subsubheading Synopsis 38851 38852@smallexample 38853 -gdb-exit 38854@end smallexample 38855 38856Exit @value{GDBN} immediately. 38857 38858@subsubheading @value{GDBN} Command 38859 38860Approximately corresponds to @samp{quit}. 38861 38862@subsubheading Example 38863 38864@smallexample 38865(gdb) 38866-gdb-exit 38867^exit 38868@end smallexample 38869 38870 38871@ignore 38872@findex -exec-abort 38873@subheading The @code{-exec-abort} Command 38874 38875@subsubheading Synopsis 38876 38877@smallexample 38878 -exec-abort 38879@end smallexample 38880 38881Kill the inferior running program. 38882 38883@subsubheading @value{GDBN} Command 38884 38885The corresponding @value{GDBN} command is @samp{kill}. 38886 38887@subsubheading Example 38888N.A. 38889@end ignore 38890 38891 38892@findex -gdb-set 38893@subheading The @code{-gdb-set} Command 38894 38895@subsubheading Synopsis 38896 38897@smallexample 38898 -gdb-set 38899@end smallexample 38900 38901Set an internal @value{GDBN} variable. 38902@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ????? 38903 38904@subsubheading @value{GDBN} Command 38905 38906The corresponding @value{GDBN} command is @samp{set}. 38907 38908@subsubheading Example 38909 38910@smallexample 38911(gdb) 38912-gdb-set $foo=3 38913^done 38914(gdb) 38915@end smallexample 38916 38917 38918@findex -gdb-show 38919@subheading The @code{-gdb-show} Command 38920 38921@subsubheading Synopsis 38922 38923@smallexample 38924 -gdb-show 38925@end smallexample 38926 38927Show the current value of a @value{GDBN} variable. 38928 38929@subsubheading @value{GDBN} Command 38930 38931The corresponding @value{GDBN} command is @samp{show}. 38932 38933@subsubheading Example 38934 38935@smallexample 38936(gdb) 38937-gdb-show annotate 38938^done,value="0" 38939(gdb) 38940@end smallexample 38941 38942@c @subheading -gdb-source 38943 38944 38945@findex -gdb-version 38946@subheading The @code{-gdb-version} Command 38947 38948@subsubheading Synopsis 38949 38950@smallexample 38951 -gdb-version 38952@end smallexample 38953 38954Show version information for @value{GDBN}. Used mostly in testing. 38955 38956@subsubheading @value{GDBN} Command 38957 38958The @value{GDBN} equivalent is @samp{show version}. @value{GDBN} by 38959default shows this information when you start an interactive session. 38960 38961@subsubheading Example 38962 38963@c This example modifies the actual output from GDB to avoid overfull 38964@c box in TeX. 38965@smallexample 38966(gdb) 38967-gdb-version 38968~GNU gdb 5.2.1 38969~Copyright 2000 Free Software Foundation, Inc. 38970~GDB is free software, covered by the GNU General Public License, and 38971~you are welcome to change it and/or distribute copies of it under 38972~ certain conditions. 38973~Type "show copying" to see the conditions. 38974~There is absolutely no warranty for GDB. Type "show warranty" for 38975~ details. 38976~This GDB was configured as 38977 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". 38978^done 38979(gdb) 38980@end smallexample 38981 38982@findex -list-thread-groups 38983@subheading The @code{-list-thread-groups} Command 38984 38985@subsubheading Synopsis 38986 38987@smallexample 38988-list-thread-groups [ --available ] [ --recurse 1 ] [ @var{group} ... ] 38989@end smallexample 38990 38991Lists thread groups (@pxref{Thread groups}). When a single thread 38992group is passed as the argument, lists the children of that group. 38993When several thread group are passed, lists information about those 38994thread groups. Without any parameters, lists information about all 38995top-level thread groups. 38996 38997Normally, thread groups that are being debugged are reported. 38998With the @samp{--available} option, @value{GDBN} reports thread groups 38999available on the target. 39000 39001The output of this command may have either a @samp{threads} result or 39002a @samp{groups} result. The @samp{thread} result has a list of tuples 39003as value, with each tuple describing a thread (@pxref{GDB/MI Thread 39004Information}). The @samp{groups} result has a list of tuples as value, 39005each tuple describing a thread group. If top-level groups are 39006requested (that is, no parameter is passed), or when several groups 39007are passed, the output always has a @samp{groups} result. The format 39008of the @samp{group} result is described below. 39009 39010To reduce the number of roundtrips it's possible to list thread groups 39011together with their children, by passing the @samp{--recurse} option 39012and the recursion depth. Presently, only recursion depth of 1 is 39013permitted. If this option is present, then every reported thread group 39014will also include its children, either as @samp{group} or 39015@samp{threads} field. 39016 39017In general, any combination of option and parameters is permitted, with 39018the following caveats: 39019 39020@itemize @bullet 39021@item 39022When a single thread group is passed, the output will typically 39023be the @samp{threads} result. Because threads may not contain 39024anything, the @samp{recurse} option will be ignored. 39025 39026@item 39027When the @samp{--available} option is passed, limited information may 39028be available. In particular, the list of threads of a process might 39029be inaccessible. Further, specifying specific thread groups might 39030not give any performance advantage over listing all thread groups. 39031The frontend should assume that @samp{-list-thread-groups --available} 39032is always an expensive operation and cache the results. 39033 39034@end itemize 39035 39036The @samp{groups} result is a list of tuples, where each tuple may 39037have the following fields: 39038 39039@table @code 39040@item id 39041Identifier of the thread group. This field is always present. 39042The identifier is an opaque string; frontends should not try to 39043convert it to an integer, even though it might look like one. 39044 39045@item type 39046The type of the thread group. At present, only @samp{process} is a 39047valid type. 39048 39049@item pid 39050The target-specific process identifier. This field is only present 39051for thread groups of type @samp{process} and only if the process exists. 39052 39053@item exit-code 39054The exit code of this group's last exited thread, formatted in octal. 39055This field is only present for thread groups of type @samp{process} and 39056only if the process is not running. 39057 39058@item num_children 39059The number of children this thread group has. This field may be 39060absent for an available thread group. 39061 39062@item threads 39063This field has a list of tuples as value, each tuple describing a 39064thread. It may be present if the @samp{--recurse} option is 39065specified, and it's actually possible to obtain the threads. 39066 39067@item cores 39068This field is a list of integers, each identifying a core that one 39069thread of the group is running on. This field may be absent if 39070such information is not available. 39071 39072@item executable 39073The name of the executable file that corresponds to this thread group. 39074The field is only present for thread groups of type @samp{process}, 39075and only if there is a corresponding executable file. 39076 39077@end table 39078 39079@subsubheading Example 39080 39081@smallexample 39082(@value{GDBP}) 39083-list-thread-groups 39084^done,groups=[@{id="17",type="process",pid="yyy",num_children="2"@}] 39085-list-thread-groups 17 39086^done,threads=[@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", 39087 frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@}, 39088@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", 39089 frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}], 39090 file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"@},state="running"@}]] 39091-list-thread-groups --available 39092^done,groups=[@{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]@}] 39093-list-thread-groups --available --recurse 1 39094 ^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], 39095 threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@}, 39096 @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},..] 39097-list-thread-groups --available --recurse 1 17 18 39098^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], 39099 threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@}, 39100 @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},...] 39101@end smallexample 39102 39103@findex -info-os 39104@subheading The @code{-info-os} Command 39105 39106@subsubheading Synopsis 39107 39108@smallexample 39109-info-os [ @var{type} ] 39110@end smallexample 39111 39112If no argument is supplied, the command returns a table of available 39113operating-system-specific information types. If one of these types is 39114supplied as an argument @var{type}, then the command returns a table 39115of data of that type. 39116 39117The types of information available depend on the target operating 39118system. 39119 39120@subsubheading @value{GDBN} Command 39121 39122The corresponding @value{GDBN} command is @samp{info os}. 39123 39124@subsubheading Example 39125 39126When run on a @sc{gnu}/Linux system, the output will look something 39127like this: 39128 39129@smallexample 39130(@value{GDBP}) 39131-info-os 39132^done,OSDataTable=@{nr_rows="10",nr_cols="3", 39133hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="Type"@}, 39134 @{width="10",alignment="-1",col_name="col1",colhdr="Description"@}, 39135 @{width="10",alignment="-1",col_name="col2",colhdr="Title"@}], 39136body=[item=@{col0="cpus",col1="Listing of all cpus/cores on the system", 39137 col2="CPUs"@}, 39138 item=@{col0="files",col1="Listing of all file descriptors", 39139 col2="File descriptors"@}, 39140 item=@{col0="modules",col1="Listing of all loaded kernel modules", 39141 col2="Kernel modules"@}, 39142 item=@{col0="msg",col1="Listing of all message queues", 39143 col2="Message queues"@}, 39144 item=@{col0="processes",col1="Listing of all processes", 39145 col2="Processes"@}, 39146 item=@{col0="procgroups",col1="Listing of all process groups", 39147 col2="Process groups"@}, 39148 item=@{col0="semaphores",col1="Listing of all semaphores", 39149 col2="Semaphores"@}, 39150 item=@{col0="shm",col1="Listing of all shared-memory regions", 39151 col2="Shared-memory regions"@}, 39152 item=@{col0="sockets",col1="Listing of all internet-domain sockets", 39153 col2="Sockets"@}, 39154 item=@{col0="threads",col1="Listing of all threads", 39155 col2="Threads"@}] 39156(@value{GDBP}) 39157-info-os processes 39158^done,OSDataTable=@{nr_rows="190",nr_cols="4", 39159hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="pid"@}, 39160 @{width="10",alignment="-1",col_name="col1",colhdr="user"@}, 39161 @{width="10",alignment="-1",col_name="col2",colhdr="command"@}, 39162 @{width="10",alignment="-1",col_name="col3",colhdr="cores"@}], 39163body=[item=@{col0="1",col1="root",col2="/sbin/init",col3="0"@}, 39164 item=@{col0="2",col1="root",col2="[kthreadd]",col3="1"@}, 39165 item=@{col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"@}, 39166 ... 39167 item=@{col0="26446",col1="stan",col2="bash",col3="0"@}, 39168 item=@{col0="28152",col1="stan",col2="bash",col3="1"@}]@} 39169(@value{GDBP}) 39170@end smallexample 39171 39172(Note that the MI output here includes a @code{"Title"} column that 39173does not appear in command-line @code{info os}; this column is useful 39174for MI clients that want to enumerate the types of data, such as in a 39175popup menu, but is needless clutter on the command line, and 39176@code{info os} omits it.) 39177 39178@findex -add-inferior 39179@subheading The @code{-add-inferior} Command 39180 39181@subsubheading Synopsis 39182 39183@smallexample 39184-add-inferior [ --no-connection ] 39185@end smallexample 39186 39187Creates a new inferior (@pxref{Inferiors Connections and Programs}). The created 39188inferior is not associated with any executable. Such association may 39189be established with the @samp{-file-exec-and-symbols} command 39190(@pxref{GDB/MI File Commands}). 39191 39192By default, the new inferior begins connected to the same target 39193connection as the current inferior. For example, if the current 39194inferior was connected to @code{gdbserver} with @code{target remote}, 39195then the new inferior will be connected to the same @code{gdbserver} 39196instance. The @samp{--no-connection} option starts the new inferior 39197with no connection yet. You can then for example use the 39198@code{-target-select remote} command to connect to some other 39199@code{gdbserver} instance, use @code{-exec-run} to spawn a local 39200program, etc. 39201 39202The command response always has a field, @var{inferior}, whose value 39203is the identifier of the thread group corresponding to the new 39204inferior. 39205 39206An additional section field, @var{connection}, is optional. This 39207field will only exist if the new inferior has a target connection. If 39208this field exists, then its value will be a tuple containing the 39209following fields: 39210 39211@table @samp 39212@item number 39213The number of the connection used for the new inferior. 39214 39215@item name 39216The name of the connection type used for the new inferior. 39217@end table 39218 39219@subsubheading @value{GDBN} Command 39220 39221The corresponding @value{GDBN} command is @samp{add-inferior} 39222(@pxref{add_inferior_cli,,@samp{add-inferior}}). 39223 39224@subsubheading Example 39225 39226@smallexample 39227(@value{GDBP}) 39228-add-inferior 39229^done,inferior="i3" 39230@end smallexample 39231 39232@findex -remove-inferior 39233@subheading The @code{-remove-inferior} Command 39234 39235@subsubheading Synopsis 39236 39237@smallexample 39238-remove-inferior @var{inferior-id} 39239@end smallexample 39240 39241Removes an inferior (@pxref{Inferiors Connections and Programs}). 39242Only inferiors that have exited can be removed. The @var{inferior-id} 39243is the inferior to be removed, and should be the same id string as 39244returned by the @samp{-add-inferior} command. 39245 39246When an inferior is successfully removed a 39247@code{=thread-group-removed} notification (@pxref{GDB/MI Async 39248Records}) is emitted, the @var{id} field of which contains the 39249@var{inferior-id} for the removed inferior. 39250 39251@subsubheading @value{GDBN} Command 39252 39253The corresponding @value{GDBN} command is @samp{remove-inferiors} 39254(@pxref{remove_inferiors_cli,,@samp{remove-inferiors}}). 39255 39256@subsubheading Example 39257 39258@smallexample 39259(@value{GDBP}) 39260-remove-inferior i3 39261=thread-group-removed,id="i3" 39262^done 39263@end smallexample 39264 39265@findex -interpreter-exec 39266@subheading The @code{-interpreter-exec} Command 39267 39268@subsubheading Synopsis 39269 39270@smallexample 39271-interpreter-exec @var{interpreter} @var{command} 39272@end smallexample 39273@anchor{-interpreter-exec} 39274 39275Execute the specified @var{command} in the given @var{interpreter}. 39276 39277@subsubheading @value{GDBN} Command 39278 39279The corresponding @value{GDBN} command is @samp{interpreter-exec}. 39280 39281@subsubheading Example 39282 39283@smallexample 39284(gdb) 39285-interpreter-exec console "break main" 39286&"During symbol reading, couldn't parse type; debugger out of date?.\n" 39287&"During symbol reading, bad structure-type format.\n" 39288~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" 39289^done 39290(gdb) 39291@end smallexample 39292 39293@findex -inferior-tty-set 39294@subheading The @code{-inferior-tty-set} Command 39295 39296@subsubheading Synopsis 39297 39298@smallexample 39299-inferior-tty-set /dev/pts/1 39300@end smallexample 39301 39302Set terminal for future runs of the program being debugged. 39303 39304@subsubheading @value{GDBN} Command 39305 39306The corresponding @value{GDBN} command is @samp{set inferior-tty} /dev/pts/1. 39307 39308@subsubheading Example 39309 39310@smallexample 39311(gdb) 39312-inferior-tty-set /dev/pts/1 39313^done 39314(gdb) 39315@end smallexample 39316 39317@findex -inferior-tty-show 39318@subheading The @code{-inferior-tty-show} Command 39319 39320@subsubheading Synopsis 39321 39322@smallexample 39323-inferior-tty-show 39324@end smallexample 39325 39326Show terminal for future runs of program being debugged. 39327 39328@subsubheading @value{GDBN} Command 39329 39330The corresponding @value{GDBN} command is @samp{show inferior-tty}. 39331 39332@subsubheading Example 39333 39334@smallexample 39335(gdb) 39336-inferior-tty-set /dev/pts/1 39337^done 39338(gdb) 39339-inferior-tty-show 39340^done,inferior_tty_terminal="/dev/pts/1" 39341(gdb) 39342@end smallexample 39343 39344@findex -enable-timings 39345@subheading The @code{-enable-timings} Command 39346 39347@subsubheading Synopsis 39348 39349@smallexample 39350-enable-timings [yes | no] 39351@end smallexample 39352 39353Toggle the printing of the wallclock, user and system times for an MI 39354command as a field in its output. This command is to help frontend 39355developers optimize the performance of their code. No argument is 39356equivalent to @samp{yes}. 39357 39358@subsubheading @value{GDBN} Command 39359 39360No equivalent. 39361 39362@subsubheading Example 39363 39364@smallexample 39365(gdb) 39366-enable-timings 39367^done 39368(gdb) 39369-break-insert main 39370^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 39371addr="0x080484ed",func="main",file="myprog.c", 39372fullname="/home/nickrob/myprog.c",line="73",thread-groups=["i1"], 39373times="0"@}, 39374time=@{wallclock="0.05185",user="0.00800",system="0.00000"@} 39375(gdb) 39376-enable-timings no 39377^done 39378(gdb) 39379-exec-run 39380^running 39381(gdb) 39382*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", 39383frame=@{addr="0x080484ed",func="main",args=[@{name="argc",value="1"@}, 39384@{name="argv",value="0xbfb60364"@}],file="myprog.c", 39385fullname="/home/nickrob/myprog.c",line="73",arch="i386:x86_64"@} 39386(gdb) 39387@end smallexample 39388 39389@findex -complete 39390@subheading The @code{-complete} Command 39391 39392@subsubheading Synopsis 39393 39394@smallexample 39395-complete @var{command} 39396@end smallexample 39397 39398Show a list of completions for partially typed CLI @var{command}. 39399 39400This command is intended for @sc{gdb/mi} frontends that cannot use two separate 39401CLI and MI channels --- for example: because of lack of PTYs like on Windows or 39402because @value{GDBN} is used remotely via a SSH connection. 39403 39404@subsubheading Result 39405 39406The result consists of two or three fields: 39407 39408@table @samp 39409@item completion 39410This field contains the completed @var{command}. If @var{command} 39411has no known completions, this field is omitted. 39412 39413@item matches 39414This field contains a (possibly empty) array of matches. It is always present. 39415 39416@item max_completions_reached 39417This field contains @code{1} if number of known completions is above 39418@code{max-completions} limit (@pxref{Completion}), otherwise it contains 39419@code{0}. It is always present. 39420 39421@end table 39422 39423@subsubheading @value{GDBN} Command 39424 39425The corresponding @value{GDBN} command is @samp{complete}. 39426 39427@subsubheading Example 39428 39429@smallexample 39430(gdb) 39431-complete br 39432^done,completion="break", 39433 matches=["break","break-range"], 39434 max_completions_reached="0" 39435(gdb) 39436-complete "b ma" 39437^done,completion="b ma", 39438 matches=["b madvise","b main"],max_completions_reached="0" 39439(gdb) 39440-complete "b push_b" 39441^done,completion="b push_back(", 39442 matches=[ 39443 "b A::push_back(void*)", 39444 "b std::string::push_back(char)", 39445 "b std::vector<int, std::allocator<int> >::push_back(int&&)"], 39446 max_completions_reached="0" 39447(gdb) 39448-complete "nonexist" 39449^done,matches=[],max_completions_reached="0" 39450(gdb) 39451 39452@end smallexample 39453 39454@node Annotations 39455@chapter @value{GDBN} Annotations 39456 39457This chapter describes annotations in @value{GDBN}. Annotations were 39458designed to interface @value{GDBN} to graphical user interfaces or other 39459similar programs which want to interact with @value{GDBN} at a 39460relatively high level. 39461 39462The annotation mechanism has largely been superseded by @sc{gdb/mi} 39463(@pxref{GDB/MI}). 39464 39465@ignore 39466This is Edition @value{EDITION}, @value{DATE}. 39467@end ignore 39468 39469@menu 39470* Annotations Overview:: What annotations are; the general syntax. 39471* Server Prefix:: Issuing a command without affecting user state. 39472* Prompting:: Annotations marking @value{GDBN}'s need for input. 39473* Errors:: Annotations for error messages. 39474* Invalidation:: Some annotations describe things now invalid. 39475* Annotations for Running:: 39476 Whether the program is running, how it stopped, etc. 39477* Source Annotations:: Annotations describing source code. 39478@end menu 39479 39480@node Annotations Overview 39481@section What is an Annotation? 39482@cindex annotations 39483 39484Annotations start with a newline character, two @samp{control-z} 39485characters, and the name of the annotation. If there is no additional 39486information associated with this annotation, the name of the annotation 39487is followed immediately by a newline. If there is additional 39488information, the name of the annotation is followed by a space, the 39489additional information, and a newline. The additional information 39490cannot contain newline characters. 39491 39492Any output not beginning with a newline and two @samp{control-z} 39493characters denotes literal output from @value{GDBN}. Currently there is 39494no need for @value{GDBN} to output a newline followed by two 39495@samp{control-z} characters, but if there was such a need, the 39496annotations could be extended with an @samp{escape} annotation which 39497means those three characters as output. 39498 39499The annotation @var{level}, which is specified using the 39500@option{--annotate} command line option (@pxref{Mode Options}), controls 39501how much information @value{GDBN} prints together with its prompt, 39502values of expressions, source lines, and other types of output. Level 0 39503is for no annotations, level 1 is for use when @value{GDBN} is run as a 39504subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable 39505for programs that control @value{GDBN}, and level 2 annotations have 39506been made obsolete (@pxref{Limitations, , Limitations of the Annotation 39507Interface, annotate, GDB's Obsolete Annotations}). 39508 39509@table @code 39510@kindex set annotate 39511@item set annotate @var{level} 39512The @value{GDBN} command @code{set annotate} sets the level of 39513annotations to the specified @var{level}. 39514 39515@item show annotate 39516@kindex show annotate 39517Show the current annotation level. 39518@end table 39519 39520This chapter describes level 3 annotations. 39521 39522A simple example of starting up @value{GDBN} with annotations is: 39523 39524@smallexample 39525$ @kbd{gdb --annotate=3} 39526GNU gdb 6.0 39527Copyright 2003 Free Software Foundation, Inc. 39528GDB is free software, covered by the GNU General Public License, 39529and you are welcome to change it and/or distribute copies of it 39530under certain conditions. 39531Type "show copying" to see the conditions. 39532There is absolutely no warranty for GDB. Type "show warranty" 39533for details. 39534This GDB was configured as "i386-pc-linux-gnu" 39535 39536^Z^Zpre-prompt 39537(@value{GDBP}) 39538^Z^Zprompt 39539@kbd{quit} 39540 39541^Z^Zpost-prompt 39542$ 39543@end smallexample 39544 39545Here @samp{quit} is input to @value{GDBN}; the rest is output from 39546@value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z} 39547denotes a @samp{control-z} character) are annotations; the rest is 39548output from @value{GDBN}. 39549 39550@node Server Prefix 39551@section The Server Prefix 39552@cindex server prefix 39553 39554If you prefix a command with @samp{server } then it will not affect 39555the command history, nor will it affect @value{GDBN}'s notion of which 39556command to repeat if @key{RET} is pressed on a line by itself. This 39557means that commands can be run behind a user's back by a front-end in 39558a transparent manner. 39559 39560The @code{server } prefix does not affect the recording of values into 39561the value history; to print a value without recording it into the 39562value history, use the @code{output} command instead of the 39563@code{print} command. 39564 39565Using this prefix also disables confirmation requests 39566(@pxref{confirmation requests}). 39567 39568@node Prompting 39569@section Annotation for @value{GDBN} Input 39570 39571@cindex annotations for prompts 39572When @value{GDBN} prompts for input, it annotates this fact so it is possible 39573to know when to send output, when the output from a given command is 39574over, etc. 39575 39576Different kinds of input each have a different @dfn{input type}. Each 39577input type has three annotations: a @code{pre-} annotation, which 39578denotes the beginning of any prompt which is being output, a plain 39579annotation, which denotes the end of the prompt, and then a @code{post-} 39580annotation which denotes the end of any echo which may (or may not) be 39581associated with the input. For example, the @code{prompt} input type 39582features the following annotations: 39583 39584@smallexample 39585^Z^Zpre-prompt 39586^Z^Zprompt 39587^Z^Zpost-prompt 39588@end smallexample 39589 39590The input types are 39591 39592@table @code 39593@findex pre-prompt annotation 39594@findex prompt annotation 39595@findex post-prompt annotation 39596@item prompt 39597When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt). 39598 39599@findex pre-commands annotation 39600@findex commands annotation 39601@findex post-commands annotation 39602@item commands 39603When @value{GDBN} prompts for a set of commands, like in the @code{commands} 39604command. The annotations are repeated for each command which is input. 39605 39606@findex pre-overload-choice annotation 39607@findex overload-choice annotation 39608@findex post-overload-choice annotation 39609@item overload-choice 39610When @value{GDBN} wants the user to select between various overloaded functions. 39611 39612@findex pre-query annotation 39613@findex query annotation 39614@findex post-query annotation 39615@item query 39616When @value{GDBN} wants the user to confirm a potentially dangerous operation. 39617 39618@findex pre-prompt-for-continue annotation 39619@findex prompt-for-continue annotation 39620@findex post-prompt-for-continue annotation 39621@item prompt-for-continue 39622When @value{GDBN} is asking the user to press return to continue. Note: Don't 39623expect this to work well; instead use @code{set height 0} to disable 39624prompting. This is because the counting of lines is buggy in the 39625presence of annotations. 39626@end table 39627 39628@node Errors 39629@section Errors 39630@cindex annotations for errors, warnings and interrupts 39631 39632@findex quit annotation 39633@smallexample 39634^Z^Zquit 39635@end smallexample 39636 39637This annotation occurs right before @value{GDBN} responds to an interrupt. 39638 39639@findex error annotation 39640@smallexample 39641^Z^Zerror 39642@end smallexample 39643 39644This annotation occurs right before @value{GDBN} responds to an error. 39645 39646Quit and error annotations indicate that any annotations which @value{GDBN} was 39647in the middle of may end abruptly. For example, if a 39648@code{value-history-begin} annotation is followed by a @code{error}, one 39649cannot expect to receive the matching @code{value-history-end}. One 39650cannot expect not to receive it either, however; an error annotation 39651does not necessarily mean that @value{GDBN} is immediately returning all the way 39652to the top level. 39653 39654@findex error-begin annotation 39655A quit or error annotation may be preceded by 39656 39657@smallexample 39658^Z^Zerror-begin 39659@end smallexample 39660 39661Any output between that and the quit or error annotation is the error 39662message. 39663 39664Warning messages are not yet annotated. 39665@c If we want to change that, need to fix warning(), type_error(), 39666@c range_error(), and possibly other places. 39667 39668@node Invalidation 39669@section Invalidation Notices 39670 39671@cindex annotations for invalidation messages 39672The following annotations say that certain pieces of state may have 39673changed. 39674 39675@table @code 39676@findex frames-invalid annotation 39677@item ^Z^Zframes-invalid 39678 39679The frames (for example, output from the @code{backtrace} command) may 39680have changed. 39681 39682@findex breakpoints-invalid annotation 39683@item ^Z^Zbreakpoints-invalid 39684 39685The breakpoints may have changed. For example, the user just added or 39686deleted a breakpoint. 39687@end table 39688 39689@node Annotations for Running 39690@section Running the Program 39691@cindex annotations for running programs 39692 39693@findex starting annotation 39694@findex stopping annotation 39695When the program starts executing due to a @value{GDBN} command such as 39696@code{step} or @code{continue}, 39697 39698@smallexample 39699^Z^Zstarting 39700@end smallexample 39701 39702is output. When the program stops, 39703 39704@smallexample 39705^Z^Zstopped 39706@end smallexample 39707 39708is output. Before the @code{stopped} annotation, a variety of 39709annotations describe how the program stopped. 39710 39711@table @code 39712@findex exited annotation 39713@item ^Z^Zexited @var{exit-status} 39714The program exited, and @var{exit-status} is the exit status (zero for 39715successful exit, otherwise nonzero). 39716 39717@findex signalled annotation 39718@findex signal-name annotation 39719@findex signal-name-end annotation 39720@findex signal-string annotation 39721@findex signal-string-end annotation 39722@item ^Z^Zsignalled 39723The program exited with a signal. After the @code{^Z^Zsignalled}, the 39724annotation continues: 39725 39726@smallexample 39727@var{intro-text} 39728^Z^Zsignal-name 39729@var{name} 39730^Z^Zsignal-name-end 39731@var{middle-text} 39732^Z^Zsignal-string 39733@var{string} 39734^Z^Zsignal-string-end 39735@var{end-text} 39736@end smallexample 39737 39738@noindent 39739where @var{name} is the name of the signal, such as @code{SIGILL} or 39740@code{SIGSEGV}, and @var{string} is the explanation of the signal, such 39741as @code{Illegal Instruction} or @code{Segmentation fault}. The arguments 39742@var{intro-text}, @var{middle-text}, and @var{end-text} are for the 39743user's benefit and have no particular format. 39744 39745@findex signal annotation 39746@item ^Z^Zsignal 39747The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is 39748just saying that the program received the signal, not that it was 39749terminated with it. 39750 39751@findex breakpoint annotation 39752@item ^Z^Zbreakpoint @var{number} 39753The program hit breakpoint number @var{number}. 39754 39755@findex watchpoint annotation 39756@item ^Z^Zwatchpoint @var{number} 39757The program hit watchpoint number @var{number}. 39758@end table 39759 39760@node Source Annotations 39761@section Displaying Source 39762@cindex annotations for source display 39763 39764@findex source annotation 39765The following annotation is used instead of displaying source code: 39766 39767@smallexample 39768^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr} 39769@end smallexample 39770 39771where @var{filename} is an absolute file name indicating which source 39772file, @var{line} is the line number within that file (where 1 is the 39773first line in the file), @var{character} is the character position 39774within the file (where 0 is the first character in the file) (for most 39775debug formats this will necessarily point to the beginning of a line), 39776@var{middle} is @samp{middle} if @var{addr} is in the middle of the 39777line, or @samp{beg} if @var{addr} is at the beginning of the line, and 39778@var{addr} is the address in the target program associated with the 39779source which is being displayed. The @var{addr} is in the form @samp{0x} 39780followed by one or more lowercase hex digits (note that this does not 39781depend on the language). 39782 39783@node Debugger Adapter Protocol 39784@chapter Debugger Adapter Protocol 39785 39786The Debugger Adapter Protocol is a generic API that is used by some 39787IDEs to communicate with debuggers. It is documented at 39788@url{https://microsoft.github.io/debug-adapter-protocol/}. 39789 39790Generally, @value{GDBN} implements the Debugger Adapter Protocol as 39791written. However, in some cases, extensions are either needed or even 39792expected. 39793 39794@value{GDBN} defines some parameters that can be passed to the 39795@code{launch} request: 39796 39797@table @code 39798@item args 39799If provided, this should be an array of strings. These strings are 39800provided as command-line arguments to the inferior, as if by 39801@code{set args}. @xref{Arguments}. 39802 39803@item cwd 39804If provided, this should be a string. @value{GDBN} will change its 39805working directory to this directory, as if by the @code{cd} command 39806(@pxref{Working Directory}). The launched program will inherit this 39807as its working directory. Note that change of directory happens 39808before the @code{program} parameter is processed. This will affect 39809the result if @code{program} is a relative filename. 39810 39811@item env 39812If provided, this should be an object. Each key of the object will be 39813used as the name of an environment variable; each value must be a 39814string and will be the value of that variable. The environment of the 39815inferior will be set to exactly as passed in. @xref{Environment}. 39816 39817@item program 39818If provided, this is a string that specifies the program to use. This 39819corresponds to the @code{file} command. @xref{Files}. 39820 39821@item stopAtBeginningOfMainSubprogram 39822If provided, this must be a boolean. When @samp{True}, @value{GDBN} 39823will set a temporary breakpoint at the program's main procedure, using 39824the same approach as the @code{start} command. @xref{Starting}. 39825@end table 39826 39827@value{GDBN} defines some parameters that can be passed to the 39828@code{attach} request. Either @code{pid} or @code{target} must be 39829specified, but if both are specified then @code{target} will be 39830ignored. 39831 39832@table @code 39833@item pid 39834The process ID to which @value{GDBN} should attach. @xref{Attach}. 39835 39836@item program 39837If provided, this is a string that specifies the program to use. This 39838corresponds to the @code{file} command. @xref{Files}. In some cases, 39839@value{GDBN} can automatically determine which program is running. 39840However, for many remote targets, this is not the case, and so this 39841should be supplied. 39842 39843@item target 39844The target to which @value{GDBN} should connect. This is a string and 39845is passed to the @code{target remote} command. @xref{Connecting}. 39846@end table 39847 39848In response to the @code{disassemble} request, DAP allows the client 39849to return the bytes of each instruction in an implementation-defined 39850format. @value{GDBN} implements this by sending a string with the 39851bytes encoded in hex, like @code{"55a2b900"}. 39852 39853When the @code{repl} context is used for the @code{evaluate} request, 39854@value{GDBN} evaluates the provided expression as a CLI command. 39855 39856Evaluation in general can cause the inferior to continue execution. 39857For example, evaluating the @code{continue} command could do this, as 39858could evaluating an expression that involves an inferior function 39859call. 39860 39861@code{repl} evaluation can also cause @value{GDBN} to appear to stop 39862responding to requests, for example if a CLI script does a lengthy 39863computation. 39864 39865Evaluations like this can be interrupted using the DAP @code{cancel} 39866request. (In fact, @code{cancel} should work for any request, but it 39867is unlikely to be useful for most of them.) 39868 39869@value{GDBN} provides a couple of logging settings that can be used in 39870DAP mode. These can be set on the command line using the @code{-iex} 39871option (@pxref{File Options}). 39872 39873@table @code 39874@item set debug dap-log-file @r{[}@var{filename}@r{]} 39875Enable DAP logging. Logs are written to @var{filename}. If no 39876@var{filename} is given, logging is stopped. 39877 39878@item set debug dap-log-level @var{level} 39879Set the DAP logging level. The default is @samp{1}, which logs the 39880DAP protocol, whatever debug messages the developers thought were 39881useful, and unexpected exceptions. Level @samp{2} can be used to log 39882all exceptions, including ones that are considered to be expected. 39883For example, a failure to parse an expression would be considered a 39884normal exception and not normally be logged. 39885@end table 39886 39887@node JIT Interface 39888@chapter JIT Compilation Interface 39889@cindex just-in-time compilation 39890@cindex JIT compilation interface 39891 39892This chapter documents @value{GDBN}'s @dfn{just-in-time} (JIT) compilation 39893interface. A JIT compiler is a program or library that generates native 39894executable code at runtime and executes it, usually in order to achieve good 39895performance while maintaining platform independence. 39896 39897Programs that use JIT compilation are normally difficult to debug because 39898portions of their code are generated at runtime, instead of being loaded from 39899object files, which is where @value{GDBN} normally finds the program's symbols 39900and debug information. In order to debug programs that use JIT compilation, 39901@value{GDBN} has an interface that allows the program to register in-memory 39902symbol files with @value{GDBN} at runtime. 39903 39904If you are using @value{GDBN} to debug a program that uses this interface, then 39905it should work transparently so long as you have not stripped the binary. If 39906you are developing a JIT compiler, then the interface is documented in the rest 39907of this chapter. At this time, the only known client of this interface is the 39908LLVM JIT. 39909 39910Broadly speaking, the JIT interface mirrors the dynamic loader interface. The 39911JIT compiler communicates with @value{GDBN} by writing data into a global 39912variable and calling a function at a well-known symbol. When @value{GDBN} 39913attaches, it reads a linked list of symbol files from the global variable to 39914find existing code, and puts a breakpoint in the function so that it can find 39915out about additional code. 39916 39917@menu 39918* Declarations:: Relevant C struct declarations 39919* Registering Code:: Steps to register code 39920* Unregistering Code:: Steps to unregister code 39921* Custom Debug Info:: Emit debug information in a custom format 39922@end menu 39923 39924@node Declarations 39925@section JIT Declarations 39926 39927These are the relevant struct declarations that a C program should include to 39928implement the interface: 39929 39930@smallexample 39931typedef enum 39932@{ 39933 JIT_NOACTION = 0, 39934 JIT_REGISTER_FN, 39935 JIT_UNREGISTER_FN 39936@} jit_actions_t; 39937 39938struct jit_code_entry 39939@{ 39940 struct jit_code_entry *next_entry; 39941 struct jit_code_entry *prev_entry; 39942 const char *symfile_addr; 39943 uint64_t symfile_size; 39944@}; 39945 39946struct jit_descriptor 39947@{ 39948 uint32_t version; 39949 /* This type should be jit_actions_t, but we use uint32_t 39950 to be explicit about the bitwidth. */ 39951 uint32_t action_flag; 39952 struct jit_code_entry *relevant_entry; 39953 struct jit_code_entry *first_entry; 39954@}; 39955 39956/* GDB puts a breakpoint in this function. */ 39957void __attribute__((noinline)) __jit_debug_register_code() @{ @}; 39958 39959/* Make sure to specify the version statically, because the 39960 debugger may check the version before we can set it. */ 39961struct jit_descriptor __jit_debug_descriptor = @{ 1, 0, 0, 0 @}; 39962@end smallexample 39963 39964If the JIT is multi-threaded, then it is important that the JIT synchronize any 39965modifications to this global data properly, which can easily be done by putting 39966a global mutex around modifications to these structures. 39967 39968@node Registering Code 39969@section Registering Code 39970 39971To register code with @value{GDBN}, the JIT should follow this protocol: 39972 39973@itemize @bullet 39974@item 39975Generate an object file in memory with symbols and other desired debug 39976information. The file must include the virtual addresses of the sections. 39977 39978@item 39979Create a code entry for the file, which gives the start and size of the symbol 39980file. 39981 39982@item 39983Add it to the linked list in the JIT descriptor. 39984 39985@item 39986Point the relevant_entry field of the descriptor at the entry. 39987 39988@item 39989Set @code{action_flag} to @code{JIT_REGISTER} and call 39990@code{__jit_debug_register_code}. 39991@end itemize 39992 39993When @value{GDBN} is attached and the breakpoint fires, @value{GDBN} uses the 39994@code{relevant_entry} pointer so it doesn't have to walk the list looking for 39995new code. However, the linked list must still be maintained in order to allow 39996@value{GDBN} to attach to a running process and still find the symbol files. 39997 39998@node Unregistering Code 39999@section Unregistering Code 40000 40001If code is freed, then the JIT should use the following protocol: 40002 40003@itemize @bullet 40004@item 40005Remove the code entry corresponding to the code from the linked list. 40006 40007@item 40008Point the @code{relevant_entry} field of the descriptor at the code entry. 40009 40010@item 40011Set @code{action_flag} to @code{JIT_UNREGISTER} and call 40012@code{__jit_debug_register_code}. 40013@end itemize 40014 40015If the JIT frees or recompiles code without unregistering it, then @value{GDBN} 40016and the JIT will leak the memory used for the associated symbol files. 40017 40018@node Custom Debug Info 40019@section Custom Debug Info 40020@cindex custom JIT debug info 40021@cindex JIT debug info reader 40022 40023Generating debug information in platform-native file formats (like ELF 40024or COFF) may be an overkill for JIT compilers; especially if all the 40025debug info is used for is displaying a meaningful backtrace. The 40026issue can be resolved by having the JIT writers decide on a debug info 40027format and also provide a reader that parses the debug info generated 40028by the JIT compiler. This section gives a brief overview on writing 40029such a parser. More specific details can be found in the source file 40030@file{gdb/jit-reader.in}, which is also installed as a header at 40031@file{@var{includedir}/gdb/jit-reader.h} for easy inclusion. 40032 40033The reader is implemented as a shared object (so this functionality is 40034not available on platforms which don't allow loading shared objects at 40035runtime). Two @value{GDBN} commands, @code{jit-reader-load} and 40036@code{jit-reader-unload} are provided, to be used to load and unload 40037the readers from a preconfigured directory. Once loaded, the shared 40038object is used the parse the debug information emitted by the JIT 40039compiler. 40040 40041@menu 40042* Using JIT Debug Info Readers:: How to use supplied readers correctly 40043* Writing JIT Debug Info Readers:: Creating a debug-info reader 40044@end menu 40045 40046@node Using JIT Debug Info Readers 40047@subsection Using JIT Debug Info Readers 40048@kindex jit-reader-load 40049@kindex jit-reader-unload 40050 40051Readers can be loaded and unloaded using the @code{jit-reader-load} 40052and @code{jit-reader-unload} commands. 40053 40054@table @code 40055@item jit-reader-load @var{reader} 40056Load the JIT reader named @var{reader}, which is a shared 40057object specified as either an absolute or a relative file name. In 40058the latter case, @value{GDBN} will try to load the reader from a 40059pre-configured directory, usually @file{@var{libdir}/gdb/} on a UNIX 40060system (here @var{libdir} is the system library directory, often 40061@file{/usr/local/lib}). 40062 40063Only one reader can be active at a time; trying to load a second 40064reader when one is already loaded will result in @value{GDBN} 40065reporting an error. A new JIT reader can be loaded by first unloading 40066the current one using @code{jit-reader-unload} and then invoking 40067@code{jit-reader-load}. 40068 40069@item jit-reader-unload 40070Unload the currently loaded JIT reader. 40071 40072@end table 40073 40074@node Writing JIT Debug Info Readers 40075@subsection Writing JIT Debug Info Readers 40076@cindex writing JIT debug info readers 40077 40078As mentioned, a reader is essentially a shared object conforming to a 40079certain ABI. This ABI is described in @file{jit-reader.h}. 40080 40081@file{jit-reader.h} defines the structures, macros and functions 40082required to write a reader. It is installed (along with 40083@value{GDBN}), in @file{@var{includedir}/gdb} where @var{includedir} is 40084the system include directory. 40085 40086Readers need to be released under a GPL compatible license. A reader 40087can be declared as released under such a license by placing the macro 40088@code{GDB_DECLARE_GPL_COMPATIBLE_READER} in a source file. 40089 40090The entry point for readers is the symbol @code{gdb_init_reader}, 40091which is expected to be a function with the prototype 40092 40093@findex gdb_init_reader 40094@smallexample 40095extern struct gdb_reader_funcs *gdb_init_reader (void); 40096@end smallexample 40097 40098@cindex @code{struct gdb_reader_funcs} 40099 40100@code{struct gdb_reader_funcs} contains a set of pointers to callback 40101functions. These functions are executed to read the debug info 40102generated by the JIT compiler (@code{read}), to unwind stack frames 40103(@code{unwind}) and to create canonical frame IDs 40104(@code{get_frame_id}). It also has a callback that is called when the 40105reader is being unloaded (@code{destroy}). The struct looks like this 40106 40107@smallexample 40108struct gdb_reader_funcs 40109@{ 40110 /* Must be set to GDB_READER_INTERFACE_VERSION. */ 40111 int reader_version; 40112 40113 /* For use by the reader. */ 40114 void *priv_data; 40115 40116 gdb_read_debug_info *read; 40117 gdb_unwind_frame *unwind; 40118 gdb_get_frame_id *get_frame_id; 40119 gdb_destroy_reader *destroy; 40120@}; 40121@end smallexample 40122 40123@cindex @code{struct gdb_symbol_callbacks} 40124@cindex @code{struct gdb_unwind_callbacks} 40125 40126The callbacks are provided with another set of callbacks by 40127@value{GDBN} to do their job. For @code{read}, these callbacks are 40128passed in a @code{struct gdb_symbol_callbacks} and for @code{unwind} 40129and @code{get_frame_id}, in a @code{struct gdb_unwind_callbacks}. 40130@code{struct gdb_symbol_callbacks} has callbacks to create new object 40131files and new symbol tables inside those object files. @code{struct 40132gdb_unwind_callbacks} has callbacks to read registers off the current 40133frame and to write out the values of the registers in the previous 40134frame. Both have a callback (@code{target_read}) to read bytes off the 40135target's address space. 40136 40137@node In-Process Agent 40138@chapter In-Process Agent 40139@cindex debugging agent 40140The traditional debugging model is conceptually low-speed, but works fine, 40141because most bugs can be reproduced in debugging-mode execution. However, 40142as multi-core or many-core processors are becoming mainstream, and 40143multi-threaded programs become more and more popular, there should be more 40144and more bugs that only manifest themselves at normal-mode execution, for 40145example, thread races, because debugger's interference with the program's 40146timing may conceal the bugs. On the other hand, in some applications, 40147it is not feasible for the debugger to interrupt the program's execution 40148long enough for the developer to learn anything helpful about its behavior. 40149If the program's correctness depends on its real-time behavior, delays 40150introduced by a debugger might cause the program to fail, even when the 40151code itself is correct. It is useful to be able to observe the program's 40152behavior without interrupting it. 40153 40154Therefore, traditional debugging model is too intrusive to reproduce 40155some bugs. In order to reduce the interference with the program, we can 40156reduce the number of operations performed by debugger. The 40157@dfn{In-Process Agent}, a shared library, is running within the same 40158process with inferior, and is able to perform some debugging operations 40159itself. As a result, debugger is only involved when necessary, and 40160performance of debugging can be improved accordingly. Note that 40161interference with program can be reduced but can't be removed completely, 40162because the in-process agent will still stop or slow down the program. 40163 40164The in-process agent can interpret and execute Agent Expressions 40165(@pxref{Agent Expressions}) during performing debugging operations. The 40166agent expressions can be used for different purposes, such as collecting 40167data in tracepoints, and condition evaluation in breakpoints. 40168 40169@anchor{Control Agent} 40170You can control whether the in-process agent is used as an aid for 40171debugging with the following commands: 40172 40173@table @code 40174@kindex set agent on 40175@item set agent on 40176Causes the in-process agent to perform some operations on behalf of the 40177debugger. Just which operations requested by the user will be done 40178by the in-process agent depends on the its capabilities. For example, 40179if you request to evaluate breakpoint conditions in the in-process agent, 40180and the in-process agent has such capability as well, then breakpoint 40181conditions will be evaluated in the in-process agent. 40182 40183@kindex set agent off 40184@item set agent off 40185Disables execution of debugging operations by the in-process agent. All 40186of the operations will be performed by @value{GDBN}. 40187 40188@kindex show agent 40189@item show agent 40190Display the current setting of execution of debugging operations by 40191the in-process agent. 40192@end table 40193 40194@menu 40195* In-Process Agent Protocol:: 40196@end menu 40197 40198@node In-Process Agent Protocol 40199@section In-Process Agent Protocol 40200@cindex in-process agent protocol 40201 40202The in-process agent is able to communicate with both @value{GDBN} and 40203GDBserver (@pxref{In-Process Agent}). This section documents the protocol 40204used for communications between @value{GDBN} or GDBserver and the IPA. 40205In general, @value{GDBN} or GDBserver sends commands 40206(@pxref{IPA Protocol Commands}) and data to in-process agent, and then 40207in-process agent replies back with the return result of the command, or 40208some other information. The data sent to in-process agent is composed 40209of primitive data types, such as 4-byte or 8-byte type, and composite 40210types, which are called objects (@pxref{IPA Protocol Objects}). 40211 40212@menu 40213* IPA Protocol Objects:: 40214* IPA Protocol Commands:: 40215@end menu 40216 40217@node IPA Protocol Objects 40218@subsection IPA Protocol Objects 40219@cindex ipa protocol objects 40220 40221The commands sent to and results received from agent may contain some 40222complex data types called @dfn{objects}. 40223 40224The in-process agent is running on the same machine with @value{GDBN} 40225or GDBserver, so it doesn't have to handle as much differences between 40226two ends as remote protocol (@pxref{Remote Protocol}) tries to handle. 40227However, there are still some differences of two ends in two processes: 40228 40229@enumerate 40230@item 40231word size. On some 64-bit machines, @value{GDBN} or GDBserver can be 40232compiled as a 64-bit executable, while in-process agent is a 32-bit one. 40233@item 40234ABI. Some machines may have multiple types of ABI, @value{GDBN} or 40235GDBserver is compiled with one, and in-process agent is compiled with 40236the other one. 40237@end enumerate 40238 40239Here are the IPA Protocol Objects: 40240 40241@enumerate 40242@item 40243agent expression object. It represents an agent expression 40244(@pxref{Agent Expressions}). 40245@anchor{agent expression object} 40246@item 40247tracepoint action object. It represents a tracepoint action 40248(@pxref{Tracepoint Actions,,Tracepoint Action Lists}) to collect registers, 40249memory, static trace data and to evaluate expression. 40250@anchor{tracepoint action object} 40251@item 40252tracepoint object. It represents a tracepoint (@pxref{Tracepoints}). 40253@anchor{tracepoint object} 40254 40255@end enumerate 40256 40257The following table describes important attributes of each IPA protocol 40258object: 40259 40260@multitable @columnfractions .30 .20 .50 40261@headitem Name @tab Size @tab Description 40262@item @emph{agent expression object} @tab @tab 40263@item length @tab 4 @tab length of bytes code 40264@item byte code @tab @var{length} @tab contents of byte code 40265@item @emph{tracepoint action for collecting memory} @tab @tab 40266@item 'M' @tab 1 @tab type of tracepoint action 40267@item addr @tab 8 @tab if @var{basereg} is @samp{-1}, @var{addr} is the 40268address of the lowest byte to collect, otherwise @var{addr} is the offset 40269of @var{basereg} for memory collecting. 40270@item len @tab 8 @tab length of memory for collecting 40271@item basereg @tab 4 @tab the register number containing the starting 40272memory address for collecting. 40273@item @emph{tracepoint action for collecting registers} @tab @tab 40274@item 'R' @tab 1 @tab type of tracepoint action 40275@item @emph{tracepoint action for collecting static trace data} @tab @tab 40276@item 'L' @tab 1 @tab type of tracepoint action 40277@item @emph{tracepoint action for expression evaluation} @tab @tab 40278@item 'X' @tab 1 @tab type of tracepoint action 40279@item agent expression @tab length of @tab @ref{agent expression object} 40280@item @emph{tracepoint object} @tab @tab 40281@item number @tab 4 @tab number of tracepoint 40282@item address @tab 8 @tab address of tracepoint inserted on 40283@item type @tab 4 @tab type of tracepoint 40284@item enabled @tab 1 @tab enable or disable of tracepoint 40285@item step_count @tab 8 @tab step 40286@item pass_count @tab 8 @tab pass 40287@item numactions @tab 4 @tab number of tracepoint actions 40288@item hit count @tab 8 @tab hit count 40289@item trace frame usage @tab 8 @tab trace frame usage 40290@item compiled_cond @tab 8 @tab compiled condition 40291@item orig_size @tab 8 @tab orig size 40292@item condition @tab 4 if condition is NULL otherwise length of 40293@ref{agent expression object} 40294@tab zero if condition is NULL, otherwise is 40295@ref{agent expression object} 40296@item actions @tab variable 40297@tab numactions number of @ref{tracepoint action object} 40298@end multitable 40299 40300@node IPA Protocol Commands 40301@subsection IPA Protocol Commands 40302@cindex ipa protocol commands 40303 40304The spaces in each command are delimiters to ease reading this commands 40305specification. They don't exist in real commands. 40306 40307@table @samp 40308 40309@item FastTrace:@var{tracepoint_object} @var{gdb_jump_pad_head} 40310Installs a new fast tracepoint described by @var{tracepoint_object} 40311(@pxref{tracepoint object}). The @var{gdb_jump_pad_head}, 8-byte long, is the 40312head of @dfn{jumppad}, which is used to jump to data collection routine 40313in IPA finally. 40314 40315Replies: 40316@table @samp 40317@item OK @var{target_address} @var{gdb_jump_pad_head} @var{fjump_size} @var{fjump} 40318@var{target_address} is address of tracepoint in the inferior. 40319The @var{gdb_jump_pad_head} is updated head of jumppad. Both of 40320@var{target_address} and @var{gdb_jump_pad_head} are 8-byte long. 40321The @var{fjump} contains a sequence of instructions jump to jumppad entry. 40322The @var{fjump_size}, 4-byte long, is the size of @var{fjump}. 40323 40324@end table 40325 40326@item close 40327Closes the in-process agent. This command is sent when @value{GDBN} or GDBserver 40328is about to kill inferiors. 40329 40330@item qTfSTM 40331@xref{qTfSTM}. 40332@item qTsSTM 40333@xref{qTsSTM}. 40334@item qTSTMat 40335@xref{qTSTMat}. 40336@item probe_marker_at:@var{address} 40337Asks in-process agent to probe the marker at @var{address}. 40338 40339Replies: 40340@table @samp 40341@end table 40342@item unprobe_marker_at:@var{address} 40343Asks in-process agent to unprobe the marker at @var{address}. 40344@end table 40345 40346@node GDB Bugs 40347@chapter Reporting Bugs in @value{GDBN} 40348@cindex bugs in @value{GDBN} 40349@cindex reporting bugs in @value{GDBN} 40350 40351Your bug reports play an essential role in making @value{GDBN} reliable. 40352 40353Reporting a bug may help you by bringing a solution to your problem, or it 40354may not. But in any case the principal function of a bug report is to help 40355the entire community by making the next version of @value{GDBN} work better. Bug 40356reports are your contribution to the maintenance of @value{GDBN}. 40357 40358In order for a bug report to serve its purpose, you must include the 40359information that enables us to fix the bug. 40360 40361@menu 40362* Bug Criteria:: Have you found a bug? 40363* Bug Reporting:: How to report bugs 40364@end menu 40365 40366@node Bug Criteria 40367@section Have You Found a Bug? 40368@cindex bug criteria 40369 40370If you are not sure whether you have found a bug, here are some guidelines: 40371 40372@itemize @bullet 40373@cindex fatal signal 40374@cindex debugger crash 40375@cindex crash of debugger 40376@item 40377If the debugger gets a fatal signal, for any input whatever, that is a 40378@value{GDBN} bug. Reliable debuggers never crash. 40379 40380@cindex error on valid input 40381@item 40382If @value{GDBN} produces an error message for valid input, that is a 40383bug. (Note that if you're cross debugging, the problem may also be 40384somewhere in the connection to the target.) 40385 40386@cindex invalid input 40387@item 40388If @value{GDBN} does not produce an error message for invalid input, 40389that is a bug. However, you should note that your idea of 40390``invalid input'' might be our idea of ``an extension'' or ``support 40391for traditional practice''. 40392 40393@item 40394If you are an experienced user of debugging tools, your suggestions 40395for improvement of @value{GDBN} are welcome in any case. 40396@end itemize 40397 40398@node Bug Reporting 40399@section How to Report Bugs 40400@cindex bug reports 40401@cindex @value{GDBN} bugs, reporting 40402 40403A number of companies and individuals offer support for @sc{gnu} products. 40404If you obtained @value{GDBN} from a support organization, we recommend you 40405contact that organization first. 40406 40407You can find contact information for many support companies and 40408individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs 40409distribution. 40410@c should add a web page ref... 40411 40412@ifset BUGURL 40413@ifset BUGURL_DEFAULT 40414In any event, we also recommend that you submit bug reports for 40415@value{GDBN}. The preferred method is to submit them directly using 40416@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web 40417page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can 40418be used. 40419 40420@strong{Do not send bug reports to @samp{info-gdb}, or to 40421@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do 40422not want to receive bug reports. Those that do have arranged to receive 40423@samp{bug-gdb}. 40424 40425The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which 40426serves as a repeater. The mailing list and the newsgroup carry exactly 40427the same messages. Often people think of posting bug reports to the 40428newsgroup instead of mailing them. This appears to work, but it has one 40429problem which can be crucial: a newsgroup posting often lacks a mail 40430path back to the sender. Thus, if we need to ask for more information, 40431we may be unable to reach you. For this reason, it is better to send 40432bug reports to the mailing list. 40433@end ifset 40434@ifclear BUGURL_DEFAULT 40435In any event, we also recommend that you submit bug reports for 40436@value{GDBN} to @value{BUGURL}. 40437@end ifclear 40438@end ifset 40439 40440The fundamental principle of reporting bugs usefully is this: 40441@strong{report all the facts}. If you are not sure whether to state a 40442fact or leave it out, state it! 40443 40444Often people omit facts because they think they know what causes the 40445problem and assume that some details do not matter. Thus, you might 40446assume that the name of the variable you use in an example does not matter. 40447Well, probably it does not, but one cannot be sure. Perhaps the bug is a 40448stray memory reference which happens to fetch from the location where that 40449name is stored in memory; perhaps, if the name were different, the contents 40450of that location would fool the debugger into doing the right thing despite 40451the bug. Play it safe and give a specific, complete example. That is the 40452easiest thing for you to do, and the most helpful. 40453 40454Keep in mind that the purpose of a bug report is to enable us to fix the 40455bug. It may be that the bug has been reported previously, but neither 40456you nor we can know that unless your bug report is complete and 40457self-contained. 40458 40459Sometimes people give a few sketchy facts and ask, ``Does this ring a 40460bell?'' Those bug reports are useless, and we urge everyone to 40461@emph{refuse to respond to them} except to chide the sender to report 40462bugs properly. 40463 40464To enable us to fix the bug, you should include all these things: 40465 40466@itemize @bullet 40467@item 40468The version of @value{GDBN}. @value{GDBN} announces it if you start 40469with no arguments; you can also print it at any time using @code{show 40470version}. 40471 40472Without this, we will not know whether there is any point in looking for 40473the bug in the current version of @value{GDBN}. 40474 40475@item 40476The type of machine you are using, and the operating system name and 40477version number. 40478 40479@item 40480The details of the @value{GDBN} build-time configuration. 40481@value{GDBN} shows these details if you invoke it with the 40482@option{--configuration} command-line option, or if you type 40483@code{show configuration} at @value{GDBN}'s prompt. 40484 40485@item 40486What compiler (and its version) was used to compile @value{GDBN}---e.g.@: 40487``@value{GCC}--2.8.1''. 40488 40489@item 40490What compiler (and its version) was used to compile the program you are 40491debugging---e.g.@: ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP 40492C Compiler''. For @value{NGCC}, you can say @kbd{@value{GCC} --version} 40493to get this information; for other compilers, see the documentation for 40494those compilers. 40495 40496@item 40497The command arguments you gave the compiler to compile your example and 40498observe the bug. For example, did you use @samp{-O}? To guarantee 40499you will not omit something important, list them all. A copy of the 40500Makefile (or the output from make) is sufficient. 40501 40502If we were to try to guess the arguments, we would probably guess wrong 40503and then we might not encounter the bug. 40504 40505@item 40506A complete input script, and all necessary source files, that will 40507reproduce the bug. 40508 40509@item 40510A description of what behavior you observe that you believe is 40511incorrect. For example, ``It gets a fatal signal.'' 40512 40513Of course, if the bug is that @value{GDBN} gets a fatal signal, then we 40514will certainly notice it. But if the bug is incorrect output, we might 40515not notice unless it is glaringly wrong. You might as well not give us 40516a chance to make a mistake. 40517 40518Even if the problem you experience is a fatal signal, you should still 40519say so explicitly. Suppose something strange is going on, such as, your 40520copy of @value{GDBN} is out of synch, or you have encountered a bug in 40521the C library on your system. (This has happened!) Your copy might 40522crash and ours would not. If you told us to expect a crash, then when 40523ours fails to crash, we would know that the bug was not happening for 40524us. If you had not told us to expect a crash, then we would not be able 40525to draw any conclusion from our observations. 40526 40527@pindex script 40528@cindex recording a session script 40529To collect all this information, you can use a session recording program 40530such as @command{script}, which is available on many Unix systems. 40531Just run your @value{GDBN} session inside @command{script} and then 40532include the @file{typescript} file with your bug report. 40533 40534Another way to record a @value{GDBN} session is to run @value{GDBN} 40535inside Emacs and then save the entire buffer to a file. 40536 40537@item 40538If you wish to suggest changes to the @value{GDBN} source, send us context 40539diffs. If you even discuss something in the @value{GDBN} source, refer to 40540it by context, not by line number. 40541 40542The line numbers in our development sources will not match those in your 40543sources. Your line numbers would convey no useful information to us. 40544 40545@end itemize 40546 40547Here are some things that are not necessary: 40548 40549@itemize @bullet 40550@item 40551A description of the envelope of the bug. 40552 40553Often people who encounter a bug spend a lot of time investigating 40554which changes to the input file will make the bug go away and which 40555changes will not affect it. 40556 40557This is often time consuming and not very useful, because the way we 40558will find the bug is by running a single example under the debugger 40559with breakpoints, not by pure deduction from a series of examples. 40560We recommend that you save your time for something else. 40561 40562Of course, if you can find a simpler example to report @emph{instead} 40563of the original one, that is a convenience for us. Errors in the 40564output will be easier to spot, running under the debugger will take 40565less time, and so on. 40566 40567However, simplification is not vital; if you do not want to do this, 40568report the bug anyway and send us the entire test case you used. 40569 40570@item 40571A patch for the bug. 40572 40573A patch for the bug does help us if it is a good one. But do not omit 40574the necessary information, such as the test case, on the assumption that 40575a patch is all we need. We might see problems with your patch and decide 40576to fix the problem another way, or we might not understand it at all. 40577 40578Sometimes with a program as complicated as @value{GDBN} it is very hard to 40579construct an example that will make the program follow a certain path 40580through the code. If you do not send us the example, we will not be able 40581to construct one, so we will not be able to verify that the bug is fixed. 40582 40583And if we cannot understand what bug you are trying to fix, or why your 40584patch should be an improvement, we will not install it. A test case will 40585help us to understand. 40586 40587@item 40588A guess about what the bug is or what it depends on. 40589 40590Such guesses are usually wrong. Even we cannot guess right about such 40591things without first using the debugger to find the facts. 40592@end itemize 40593 40594@c The readline documentation is distributed with the readline code 40595@c and consists of the two following files: 40596@c rluser.texi 40597@c hsuser.texi 40598@c Use -I with makeinfo to point to the appropriate directory, 40599@c environment var TEXINPUTS with TeX. 40600@ifclear SYSTEM_READLINE 40601@include rluser.texi 40602@include hsuser.texi 40603@end ifclear 40604 40605@node In Memoriam 40606@appendix In Memoriam 40607 40608The @value{GDBN} project mourns the loss of the following long-time 40609contributors: 40610 40611@table @code 40612@item Fred Fish 40613Fred was a long-standing contributor to @value{GDBN} (1991-2006), and 40614to Free Software in general. Outside of @value{GDBN}, he was known in 40615the Amiga world for his series of Fish Disks, and the GeekGadget project. 40616 40617@item Michael Snyder 40618Michael was one of the Global Maintainers of the @value{GDBN} project, 40619with contributions recorded as early as 1996, until 2011. In addition 40620to his day to day participation, he was a large driving force behind 40621adding Reverse Debugging to @value{GDBN}. 40622@end table 40623 40624Beyond their technical contributions to the project, they were also 40625enjoyable members of the Free Software Community. We will miss them. 40626 40627@node Formatting Documentation 40628@appendix Formatting Documentation 40629 40630@cindex @value{GDBN} reference card 40631@cindex reference card 40632The @value{GDBN} 4 release includes an already-formatted reference card, ready 40633for printing with PostScript or Ghostscript, in the @file{gdb} 40634subdirectory of the main source directory@footnote{In 40635@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN} 40636release.}. If you can use PostScript or Ghostscript with your printer, 40637you can print the reference card immediately with @file{refcard.ps}. 40638 40639The release also includes the source for the reference card. You 40640can format it, using @TeX{}, by typing: 40641 40642@smallexample 40643make refcard.dvi 40644@end smallexample 40645 40646The @value{GDBN} reference card is designed to print in @dfn{landscape} 40647mode on US ``letter'' size paper; 40648that is, on a sheet 11 inches wide by 8.5 inches 40649high. You will need to specify this form of printing as an option to 40650your @sc{dvi} output program. 40651 40652@cindex documentation 40653 40654All the documentation for @value{GDBN} comes as part of the machine-readable 40655distribution. The documentation is written in Texinfo format, which is 40656a documentation system that uses a single source file to produce both 40657on-line information and a printed manual. You can use one of the Info 40658formatting commands to create the on-line version of the documentation 40659and @TeX{} (or @code{texi2roff}) to typeset the printed version. 40660 40661@value{GDBN} includes an already formatted copy of the on-line Info 40662version of this manual in the @file{gdb} subdirectory. The main Info 40663file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to 40664subordinate files matching @samp{gdb.info*} in the same directory. If 40665necessary, you can print out these files, or read them with any editor; 40666but they are easier to read using the @code{info} subsystem in @sc{gnu} 40667Emacs or the standalone @code{info} program, available as part of the 40668@sc{gnu} Texinfo distribution. 40669 40670If you want to format these Info files yourself, you need one of the 40671Info formatting programs, such as @code{texinfo-format-buffer} or 40672@code{makeinfo}. 40673 40674If you have @code{makeinfo} installed, and are in the top level 40675@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of 40676version @value{GDBVN}), you can make the Info file by typing: 40677 40678@smallexample 40679cd gdb 40680make gdb.info 40681@end smallexample 40682 40683If you want to typeset and print copies of this manual, you need @TeX{}, 40684a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the 40685Texinfo definitions file. 40686 40687@TeX{} is a typesetting program; it does not print files directly, but 40688produces output files called @sc{dvi} files. To print a typeset 40689document, you need a program to print @sc{dvi} files. If your system 40690has @TeX{} installed, chances are it has such a program. The precise 40691command to use depends on your system; @kbd{lpr -d} is common; another 40692(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may 40693require a file name without any extension or a @samp{.dvi} extension. 40694 40695@TeX{} also requires a macro definitions file called 40696@file{texinfo.tex}. This file tells @TeX{} how to typeset a document 40697written in Texinfo format. On its own, @TeX{} cannot either read or 40698typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB 40699and is located in the @file{gdb-@var{version-number}/texinfo} 40700directory. 40701 40702If you have @TeX{} and a @sc{dvi} printer program installed, you can 40703typeset and print this manual. First switch to the @file{gdb} 40704subdirectory of the main source directory (for example, to 40705@file{gdb-@value{GDBVN}/gdb}) and type: 40706 40707@smallexample 40708make gdb.dvi 40709@end smallexample 40710 40711Then give @file{gdb.dvi} to your @sc{dvi} printing program. 40712 40713@node Installing GDB 40714@appendix Installing @value{GDBN} 40715@cindex installation 40716 40717@menu 40718* Requirements:: Requirements for building @value{GDBN} 40719* Running Configure:: Invoking the @value{GDBN} @file{configure} script 40720* Separate Objdir:: Compiling @value{GDBN} in another directory 40721* Config Names:: Specifying names for hosts and targets 40722* Configure Options:: Summary of options for configure 40723* System-wide configuration:: Having a system-wide init file 40724@end menu 40725 40726@node Requirements 40727@section Requirements for Building @value{GDBN} 40728@cindex building @value{GDBN}, requirements for 40729 40730Building @value{GDBN} requires various tools and packages to be available. 40731Other packages will be used only if they are found. 40732 40733@heading Tools/Packages Necessary for Building @value{GDBN} 40734@table @asis 40735@item C@t{++}17 compiler 40736@value{GDBN} is written in C@t{++}17. It should be buildable with any 40737recent C@t{++}17 compiler, e.g.@: GCC. 40738 40739@item GNU make 40740@value{GDBN}'s build system relies on features only found in the GNU 40741make program. Other variants of @code{make} will not work. 40742 40743@item Libraries 40744The following libraries are mandatory for building @value{GDBN}. The 40745@file{configure} script searches for each of these libraries in 40746several standard locations; if some library is installed in an unusual 40747place, you can use either the @option{--with-@var{lib}} 40748@file{configure} option to specify its installation directory, or 40749the two separate options @option{---with-@var{library}-include} (to 40750specify the location of its header files) and 40751@option{--with-@var{library}-lib} (to specify the location of its 40752libraries). For example, for the GMP library, the 3 options are 40753@option{--with-gmp}, @option{--with-gmp-include}, and 40754@option{--with-gmp-lib}. @xref{Configure Options}. We mention below 40755the home site of each library, so that you could download and install 40756them if your system doesn't already include them. 40757 40758@table @asis 40759@item GMP (The GNU Multiple Precision arithmetic library) 40760@value{GDBN} uses GMP to perform some of its extended-precision 40761arithmetic. The latest version of GMP is available from 40762@url{https://gmplib.org/}. 40763 40764@anchor{MPFR} 40765@item MPFR (The GNU Multiple-precision floating-point library) 40766@value{GDBN} uses MPFR to emulate the target floating-point 40767arithmetic during expression evaluation, if the target uses different 40768floating-point formats than the host. The latest version of MPFR is 40769available from @url{http://www.mpfr.org}. 40770@end table 40771 40772@end table 40773 40774@heading Tools/Packages Optional for Building @value{GDBN} 40775The tools/packages and libraries listed below are optional; 40776@value{GDBN} can be build without them, at the expense of some run-time 40777functionality that will be missing. As above, we list the home sites 40778for each package/library, and the command-line options supported by 40779the @file{configure} script to specify their installation directories 40780if they are non-standard. In addition, for each package you can use 40781the option @option{--with-@var{package}} to force @value{GDBN} to be 40782compiled with the named @var{package}, and 40783@option{--without-@var{package}} to disable building with it even if 40784it is available. @xref{Configure Options}, for detailed description 40785of the options to @file{configure}. 40786 40787@table @asis 40788@item Python 40789@value{GDBN} can be scripted using Python language. @xref{Python}. 40790The latest version is available from 40791@url{https://www.python.org/downloads/}. Use the 40792@option{--with-python=@var{dir}} to specify the non-standard directory 40793where Python is installed. 40794 40795@item Guile 40796@value{GDBN} can also be scripted using GNU Guile. @xref{Guile}. The 40797latest version can be found on 40798@url{https://www.gnu.org/software/guile/download/}. If you have more 40799than one version of Guile installed, use the 40800@option{--with-guile=@var{guile-version}} to specify the Guile version 40801to include in the build. 40802 40803@anchor{Expat} 40804@item Expat 40805If available, @value{GDBN} uses the Expat library for parsing XML 40806files. @value{GDBN} uses XML files for the following functionalities: 40807 40808@itemize @bullet 40809@item 40810Remote protocol memory maps (@pxref{Memory Map Format}) 40811@item 40812Target descriptions (@pxref{Target Descriptions}) 40813@item 40814Remote shared library lists (@xref{Library List Format}, 40815or alternatively @pxref{Library List Format for SVR4 Targets}) 40816@item 40817MS-Windows shared libraries (@pxref{Shared Libraries}) 40818@item 40819Traceframe info (@pxref{Traceframe Info Format}) 40820@item 40821Branch trace (@pxref{Branch Trace Format}, 40822@pxref{Branch Trace Configuration Format}) 40823@end itemize 40824 40825The latest version of Expat is available from 40826@url{http://expat.sourceforge.net}. Use the 40827@option{--with-libexpat-prefix} to specify non-standard installation 40828places for Expat. 40829 40830@item iconv 40831@value{GDBN}'s features related to character sets (@pxref{Character 40832Sets}) require a functioning @code{iconv} implementation. If you are 40833on a GNU system, then this is provided by the GNU C Library. Some 40834other systems also provide a working @code{iconv}. Use the option 40835@option{--with-iconv-bin} to specify where to find the @command{iconv} 40836program. 40837 40838On systems without @code{iconv}, you can install the GNU Libiconv 40839library; its latest version can be found on 40840@url{https://ftp.gnu.org/pub/gnu/libiconv/} if your system doesn't 40841provide it. Use the @option{--with-libiconv-prefix} option to 40842@file{configure} to specify non-standard installation place for it. 40843 40844Alternatively, @value{GDBN}'s top-level @file{configure} and 40845@file{Makefile} will arrange to build Libiconv if a directory named 40846@file{libiconv} appears in the top-most source directory. If Libiconv 40847is built this way, and if the operating system does not provide a 40848suitable @code{iconv} implementation, then the just-built library will 40849automatically be used by @value{GDBN}. One easy way to set this up is 40850to download GNU Libiconv, unpack it inside the top-level directory of 40851the @value{GDBN} source tree, and then rename the directory holding 40852the Libiconv source code to @samp{libiconv}. 40853 40854@cindex compressed debug sections 40855@item lzma 40856@value{GDBN} can support debugging sections that are compressed with 40857the LZMA library. @xref{MiniDebugInfo}. If this library is not 40858included with your operating system, you can find it in the xz package 40859at @url{http://tukaani.org/xz/}. Use the 40860@option{--with-liblzma-prefix} option to specify its non-standard 40861location. 40862 40863@item zlib 40864@value{GDBN} will use the @samp{zlib} library, if available, to read 40865compressed debug sections. Some linkers, such as GNU @command{gold}, 40866are capable of producing binaries with compressed debug sections. If 40867@value{GDBN} is compiled with @samp{zlib}, it will be able to read the 40868debug information in such binaries. 40869 40870The @samp{zlib} library is likely included with your operating system 40871distribution; if it is not, you can get the latest version from 40872@url{http://zlib.net}. 40873 40874@c FIXME: what about other optional libraries: debuginfod, zstd, 40875@c libipt, babeltrace, xxhash, source-highlight? 40876@end table 40877 40878@node Running Configure 40879@section Invoking the @value{GDBN} @file{configure} Script 40880@cindex configuring @value{GDBN} 40881@value{GDBN} comes with a @file{configure} script that automates the process 40882of preparing @value{GDBN} for installation; you can then use @code{make} to 40883build the @code{gdb} program. 40884@iftex 40885@c irrelevant in info file; it's as current as the code it lives with. 40886@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN}, 40887look at the @file{README} file in the sources; we may have improved the 40888installation procedures since publishing this manual.} 40889@end iftex 40890 40891The @value{GDBN} distribution includes all the source code you need for 40892@value{GDBN} in a single directory, whose name is usually composed by 40893appending the version number to @samp{gdb}. 40894 40895For example, the @value{GDBN} version @value{GDBVN} distribution is in the 40896@file{gdb-@value{GDBVN}} directory. That directory contains: 40897 40898@table @code 40899@item gdb-@value{GDBVN}/configure @r{(and supporting files)} 40900script for configuring @value{GDBN} and all its supporting libraries 40901 40902@item gdb-@value{GDBVN}/gdb 40903the source specific to @value{GDBN} itself 40904 40905@item gdb-@value{GDBVN}/bfd 40906source for the Binary File Descriptor library 40907 40908@item gdb-@value{GDBVN}/include 40909@sc{gnu} include files 40910 40911@item gdb-@value{GDBVN}/libiberty 40912source for the @samp{-liberty} free software library 40913 40914@item gdb-@value{GDBVN}/opcodes 40915source for the library of opcode tables and disassemblers 40916 40917@item gdb-@value{GDBVN}/readline 40918source for the @sc{gnu} command-line interface 40919@end table 40920 40921There may be other subdirectories as well. 40922 40923The simplest way to configure and build @value{GDBN} is to run @file{configure} 40924from the @file{gdb-@var{version-number}} source directory, which in 40925this example is the @file{gdb-@value{GDBVN}} directory. 40926 40927First switch to the @file{gdb-@var{version-number}} source directory 40928if you are not already in it; then run @file{configure}. Pass the 40929identifier for the platform on which @value{GDBN} will run as an 40930argument. 40931 40932For example: 40933 40934@smallexample 40935cd gdb-@value{GDBVN} 40936./configure 40937make 40938@end smallexample 40939 40940Running @samp{configure} and then running @code{make} builds the 40941included supporting libraries, then @code{gdb} itself. The configured 40942source files, and the binaries, are left in the corresponding source 40943directories. 40944 40945@need 750 40946@file{configure} is a Bourne-shell (@code{/bin/sh}) script; if your 40947system does not recognize this automatically when you run a different 40948shell, you may need to run @code{sh} on it explicitly: 40949 40950@smallexample 40951sh configure 40952@end smallexample 40953 40954You should run the @file{configure} script from the top directory in the 40955source tree, the @file{gdb-@var{version-number}} directory. If you run 40956@file{configure} from one of the subdirectories, you will configure only 40957that subdirectory. That is usually not what you want. In particular, 40958if you run the first @file{configure} from the @file{gdb} subdirectory 40959of the @file{gdb-@var{version-number}} directory, you will omit the 40960configuration of @file{bfd}, @file{readline}, and other sibling 40961directories of the @file{gdb} subdirectory. This leads to build errors 40962about missing include files such as @file{bfd/bfd.h}. 40963 40964You can install @code{@value{GDBN}} anywhere. The best way to do this 40965is to pass the @code{--prefix} option to @code{configure}, and then 40966install it with @code{make install}. 40967 40968@node Separate Objdir 40969@section Compiling @value{GDBN} in Another Directory 40970 40971If you want to run @value{GDBN} versions for several host or target machines, 40972you need a different @code{gdb} compiled for each combination of 40973host and target. @file{configure} is designed to make this easy by 40974allowing you to generate each configuration in a separate subdirectory, 40975rather than in the source directory. If your @code{make} program 40976handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running 40977@code{make} in each of these directories builds the @code{gdb} 40978program specified there. 40979 40980To build @code{gdb} in a separate directory, run @file{configure} 40981with the @samp{--srcdir} option to specify where to find the source. 40982(You also need to specify a path to find @file{configure} 40983itself from your working directory. If the path to @file{configure} 40984would be the same as the argument to @samp{--srcdir}, you can leave out 40985the @samp{--srcdir} option; it is assumed.) 40986 40987For example, with version @value{GDBVN}, you can build @value{GDBN} in a 40988separate directory for a Sun 4 like this: 40989 40990@smallexample 40991@group 40992cd gdb-@value{GDBVN} 40993mkdir ../gdb-sun4 40994cd ../gdb-sun4 40995../gdb-@value{GDBVN}/configure 40996make 40997@end group 40998@end smallexample 40999 41000When @file{configure} builds a configuration using a remote source 41001directory, it creates a tree for the binaries with the same structure 41002(and using the same names) as the tree under the source directory. In 41003the example, you'd find the Sun 4 library @file{libiberty.a} in the 41004directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in 41005@file{gdb-sun4/gdb}. 41006 41007Make sure that your path to the @file{configure} script has just one 41008instance of @file{gdb} in it. If your path to @file{configure} looks 41009like @file{../gdb-@value{GDBVN}/gdb/configure}, you are configuring only 41010one subdirectory of @value{GDBN}, not the whole package. This leads to 41011build errors about missing include files such as @file{bfd/bfd.h}. 41012 41013One popular reason to build several @value{GDBN} configurations in separate 41014directories is to configure @value{GDBN} for cross-compiling (where 41015@value{GDBN} runs on one machine---the @dfn{host}---while debugging 41016programs that run on another machine---the @dfn{target}). 41017You specify a cross-debugging target by 41018giving the @samp{--target=@var{target}} option to @file{configure}. 41019 41020When you run @code{make} to build a program or library, you must run 41021it in a configured directory---whatever directory you were in when you 41022called @file{configure} (or one of its subdirectories). 41023 41024The @code{Makefile} that @file{configure} generates in each source 41025directory also runs recursively. If you type @code{make} in a source 41026directory such as @file{gdb-@value{GDBVN}} (or in a separate configured 41027directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you 41028will build all the required libraries, and then build GDB. 41029 41030When you have multiple hosts or targets configured in separate 41031directories, you can run @code{make} on them in parallel (for example, 41032if they are NFS-mounted on each of the hosts); they will not interfere 41033with each other. 41034 41035@node Config Names 41036@section Specifying Names for Hosts and Targets 41037 41038The specifications used for hosts and targets in the @file{configure} 41039script are based on a three-part naming scheme, but some short predefined 41040aliases are also supported. The full naming scheme encodes three pieces 41041of information in the following pattern: 41042 41043@smallexample 41044@var{architecture}-@var{vendor}-@var{os} 41045@end smallexample 41046 41047For example, you can use the alias @code{sun4} as a @var{host} argument, 41048or as the value for @var{target} in a @code{--target=@var{target}} 41049option. The equivalent full name is @samp{sparc-sun-sunos4}. 41050 41051The @file{configure} script accompanying @value{GDBN} does not provide 41052any query facility to list all supported host and target names or 41053aliases. @file{configure} calls the Bourne shell script 41054@code{config.sub} to map abbreviations to full names; you can read the 41055script, if you wish, or you can use it to test your guesses on 41056abbreviations---for example: 41057 41058@smallexample 41059% sh config.sub i386-linux 41060i386-pc-linux-gnu 41061% sh config.sub alpha-linux 41062alpha-unknown-linux-gnu 41063% sh config.sub hp9k700 41064hppa1.1-hp-hpux 41065% sh config.sub sun4 41066sparc-sun-sunos4.1.1 41067% sh config.sub sun3 41068m68k-sun-sunos4.1.1 41069% sh config.sub i986v 41070Invalid configuration `i986v': machine `i986v' not recognized 41071@end smallexample 41072 41073@noindent 41074@code{config.sub} is also distributed in the @value{GDBN} source 41075directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}). 41076 41077@node Configure Options 41078@section @file{configure} Options 41079 41080@c FIXME: This largely repeats what was already described in 41081@c ``Requirements'', and OTOH doesn't describe the more fgine-granular 41082@c options like --with-libexpat-prefix and --with-python-libdir. 41083@c Should it? 41084Here is a summary of the @file{configure} options and arguments that 41085are most often useful for building @value{GDBN}. @file{configure} 41086also has several other options not listed here. @xref{Running 41087configure Scripts,,,autoconf}, for a full 41088explanation of @file{configure}. 41089 41090@smallexample 41091configure @r{[}--help@r{]} 41092 @r{[}--prefix=@var{dir}@r{]} 41093 @r{[}--exec-prefix=@var{dir}@r{]} 41094 @r{[}--srcdir=@var{dirname}@r{]} 41095 @r{[}--target=@var{target}@r{]} 41096@end smallexample 41097 41098@noindent 41099You may introduce options with a single @samp{-} rather than 41100@samp{--} if you prefer; but you may abbreviate option names if you use 41101@samp{--}. 41102 41103@table @code 41104@item --help 41105Display a quick summary of how to invoke @file{configure}. 41106 41107@item --prefix=@var{dir} 41108Configure the source to install programs and files under directory 41109@file{@var{dir}}. 41110 41111@item --exec-prefix=@var{dir} 41112Configure the source to install programs under directory 41113@file{@var{dir}}. 41114 41115@c avoid splitting the warning from the explanation: 41116@need 2000 41117@item --srcdir=@var{dirname} 41118Use this option to make configurations in directories separate from the 41119@value{GDBN} source directories. Among other things, you can use this to 41120build (or maintain) several configurations simultaneously, in separate 41121directories. @file{configure} writes configuration-specific files in 41122the current directory, but arranges for them to use the source in the 41123directory @var{dirname}. @file{configure} creates directories under 41124the working directory in parallel to the source directories below 41125@var{dirname}. 41126 41127@item --target=@var{target} 41128Configure @value{GDBN} for cross-debugging programs running on the specified 41129@var{target}. Without this option, @value{GDBN} is configured to debug 41130programs that run on the same machine (@var{host}) as @value{GDBN} itself. 41131 41132There is no convenient way to generate a list of all available 41133targets. Also see the @code{--enable-targets} option, below. 41134@end table 41135 41136There are many other options that are specific to @value{GDBN}. This 41137lists just the most common ones; there are some very specialized 41138options not described here. 41139 41140@table @code 41141@item --enable-targets=@r{[}@var{target}@r{]}@dots{} 41142@itemx --enable-targets=all 41143Configure @value{GDBN} for cross-debugging programs running on the 41144specified list of targets. The special value @samp{all} configures 41145@value{GDBN} for debugging programs running on any target it supports. 41146 41147@item --with-gdb-datadir=@var{path} 41148Set the @value{GDBN}-specific data directory. @value{GDBN} will look 41149here for certain supporting files or scripts. This defaults to the 41150@file{gdb} subdirectory of @samp{datadir} (which can be set using 41151@code{--datadir}). 41152 41153@item --with-relocated-sources=@var{dir} 41154Sets up the default source path substitution rule so that directory 41155names recorded in debug information will be automatically adjusted for 41156any directory under @var{dir}. @var{dir} should be a subdirectory of 41157@value{GDBN}'s configured prefix, the one mentioned in the 41158@code{--prefix} or @code{--exec-prefix} options to configure. This 41159option is useful if GDB is supposed to be moved to a different place 41160after it is built. 41161 41162@item --enable-64-bit-bfd 41163Enable 64-bit support in BFD on 32-bit hosts. 41164 41165@item --disable-gdbmi 41166Build @value{GDBN} without the GDB/MI machine interface 41167(@pxref{GDB/MI}). 41168 41169@item --enable-tui 41170Build @value{GDBN} with the text-mode full-screen user interface 41171(TUI). Requires a curses library (ncurses and cursesX are also 41172supported). 41173 41174@item --with-curses 41175Use the curses library instead of the termcap library, for text-mode 41176terminal operations. 41177 41178@item --with-debuginfod 41179Build @value{GDBN} with @file{libdebuginfod}, the @code{debuginfod} client 41180library. Used to automatically fetch ELF, DWARF and source files from 41181@code{debuginfod} servers using build IDs associated with any missing 41182files. Enabled by default if @file{libdebuginfod} is installed and found 41183at configure time. For more information regarding @code{debuginfod} see 41184@ref{Debuginfod}. 41185 41186@item --with-libunwind-ia64 41187Use the libunwind library for unwinding function call stack on ia64 41188target platforms. See @url{http://www.nongnu.org/libunwind/index.html} for 41189details. 41190 41191@item --with-system-readline 41192Use the readline library installed on the host, rather than the 41193library supplied as part of @value{GDBN}. Readline 7 or newer is 41194required; this is enforced by the build system. 41195 41196@item --with-system-zlib 41197Use the zlib library installed on the host, rather than the library 41198supplied as part of @value{GDBN}. 41199 41200@item --with-expat 41201Build @value{GDBN} with Expat, a library for XML parsing. (Done by 41202default if libexpat is installed and found at configure time.) This 41203library is used to read XML files supplied with @value{GDBN}. If it 41204is unavailable, some features, such as remote protocol memory maps, 41205target descriptions, and shared library lists, that are based on XML 41206files, will not be available in @value{GDBN}. If your host does not 41207have libexpat installed, you can get the latest version from 41208@url{http://expat.sourceforge.net}. 41209 41210@item --with-libiconv-prefix@r{[}=@var{dir}@r{]} 41211Build @value{GDBN} with GNU libiconv, a character set encoding 41212conversion library. This is not done by default, as on GNU systems 41213the @code{iconv} that is built in to the C library is sufficient. If 41214your host does not have a working @code{iconv}, you can get the latest 41215version of GNU iconv from @url{https://www.gnu.org/software/libiconv/}. 41216 41217@value{GDBN}'s build system also supports building GNU libiconv as 41218part of the overall build. @xref{Requirements}. 41219 41220@item --with-lzma 41221Build @value{GDBN} with LZMA, a compression library. (Done by default 41222if liblzma is installed and found at configure time.) LZMA is used by 41223@value{GDBN}'s "mini debuginfo" feature, which is only useful on 41224platforms using the ELF object file format. If your host does not 41225have liblzma installed, you can get the latest version from 41226@url{https://tukaani.org/xz/}. 41227 41228@item --with-python@r{[}=@var{python}@r{]} 41229Build @value{GDBN} with Python scripting support. (Done by default if 41230libpython is present and found at configure time.) Python makes 41231@value{GDBN} scripting much more powerful than the restricted CLI 41232scripting language. If your host does not have Python installed, you 41233can find it on @url{http://www.python.org/download/}. The oldest version 41234of Python supported by GDB is 3.0.1. The optional argument @var{python} 41235is used to find the Python headers and libraries. It can be either 41236the name of a Python executable, or the name of the directory in which 41237Python is installed. 41238 41239@item --with-guile[=@var{guile}] 41240Build @value{GDBN} with GNU Guile scripting support. (Done by default 41241if libguile is present and found at configure time.) If your host 41242does not have Guile installed, you can find it at 41243@url{https://www.gnu.org/software/guile/}. The optional argument @var{guile} 41244can be a version number, which will cause @code{configure} to try to 41245use that version of Guile; or the file name of a @code{pkg-config} 41246executable, which will be queried to find the information needed to 41247compile and link against Guile. 41248 41249@item --without-included-regex 41250Don't use the regex library included with @value{GDBN} (as part of the 41251libiberty library). This is the default on hosts with version 2 of 41252the GNU C library. 41253 41254@item --with-sysroot=@var{dir} 41255Use @var{dir} as the default system root directory for libraries whose 41256file names begin with @file{/lib}' or @file{/usr/lib'}. (The value of 41257@var{dir} can be modified at run time by using the @command{set 41258sysroot} command.) If @var{dir} is under the @value{GDBN} configured 41259prefix (set with @code{--prefix} or @code{--exec-prefix options}, the 41260default system root will be automatically adjusted if and when 41261@value{GDBN} is moved to a different location. 41262 41263@item --with-system-gdbinit=@var{file} 41264Configure @value{GDBN} to automatically load a system-wide init file. 41265@var{file} should be an absolute file name. If @var{file} is in a 41266directory under the configured prefix, and @value{GDBN} is moved to 41267another location after being built, the location of the system-wide 41268init file will be adjusted accordingly. 41269 41270@item --with-system-gdbinit-dir=@var{directory} 41271Configure @value{GDBN} to automatically load init files from a 41272system-wide directory. @var{directory} should be an absolute directory 41273name. If @var{directory} is in a directory under the configured 41274prefix, and @value{GDBN} is moved to another location after being 41275built, the location of the system-wide init directory will be 41276adjusted accordingly. 41277 41278@item --enable-build-warnings 41279When building the @value{GDBN} sources, ask the compiler to warn about 41280any code which looks even vaguely suspicious. It passes many 41281different warning flags, depending on the exact version of the 41282compiler you are using. 41283 41284@item --enable-werror 41285Treat compiler warnings as errors. It adds the @code{-Werror} flag 41286to the compiler, which will fail the compilation if the compiler 41287outputs any warning messages. 41288 41289@item --enable-ubsan 41290Enable the GCC undefined behavior sanitizer. This is disabled by 41291default, but passing @code{--enable-ubsan=yes} or 41292@code{--enable-ubsan=auto} to @code{configure} will enable it. The 41293undefined behavior sanitizer checks for C@t{++} undefined behavior. 41294It has a performance cost, so if you are looking at @value{GDBN}'s 41295performance, you should disable it. The undefined behavior sanitizer 41296was first introduced in GCC 4.9. 41297@end table 41298 41299@node System-wide configuration 41300@section System-wide configuration and settings 41301@cindex system-wide init file 41302 41303@value{GDBN} can be configured to have a system-wide init file and a 41304system-wide init file directory; this file and files in that directory 41305(if they have a recognized file extension) will be read and executed at 41306startup (@pxref{Startup, , What @value{GDBN} does during startup}). 41307 41308Here are the corresponding configure options: 41309 41310@table @code 41311@item --with-system-gdbinit=@var{file} 41312Specify that the default location of the system-wide init file is 41313@var{file}. 41314@item --with-system-gdbinit-dir=@var{directory} 41315Specify that the default location of the system-wide init file directory 41316is @var{directory}. 41317@end table 41318 41319If @value{GDBN} has been configured with the option @option{--prefix=$prefix}, 41320they may be subject to relocation. Two possible cases: 41321 41322@itemize @bullet 41323@item 41324If the default location of this init file/directory contains @file{$prefix}, 41325it will be subject to relocation. Suppose that the configure options 41326are @option{--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit}; 41327if @value{GDBN} is moved from @file{$prefix} to @file{$install}, the system 41328init file is looked for as @file{$install/etc/gdbinit} instead of 41329@file{$prefix/etc/gdbinit}. 41330 41331@item 41332By contrast, if the default location does not contain the prefix, 41333it will not be relocated. E.g.@: if @value{GDBN} has been configured with 41334@option{--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit}, 41335then @value{GDBN} will always look for @file{/usr/share/gdb/gdbinit}, 41336wherever @value{GDBN} is installed. 41337@end itemize 41338 41339If the configured location of the system-wide init file (as given by the 41340@option{--with-system-gdbinit} option at configure time) is in the 41341data-directory (as specified by @option{--with-gdb-datadir} at configure 41342time) or in one of its subdirectories, then @value{GDBN} will look for the 41343system-wide init file in the directory specified by the 41344@option{--data-directory} command-line option. 41345Note that the system-wide init file is only read once, during @value{GDBN} 41346initialization. If the data-directory is changed after @value{GDBN} has 41347started with the @code{set data-directory} command, the file will not be 41348reread. 41349 41350This applies similarly to the system-wide directory specified in 41351@option{--with-system-gdbinit-dir}. 41352 41353Any supported scripting language can be used for these init files, as long 41354as the file extension matches the scripting language. To be interpreted 41355as regular @value{GDBN} commands, the files needs to have a @file{.gdb} 41356extension. 41357 41358@menu 41359* System-wide Configuration Scripts:: Installed System-wide Configuration Scripts 41360@end menu 41361 41362@node System-wide Configuration Scripts 41363@subsection Installed System-wide Configuration Scripts 41364@cindex system-wide configuration scripts 41365 41366The @file{system-gdbinit} directory, located inside the data-directory 41367(as specified by @option{--with-gdb-datadir} at configure time) contains 41368a number of scripts which can be used as system-wide init files. To 41369automatically source those scripts at startup, @value{GDBN} should be 41370configured with @option{--with-system-gdbinit}. Otherwise, any user 41371should be able to source them by hand as needed. 41372 41373The following scripts are currently available: 41374@itemize @bullet 41375 41376@item @file{elinos.py} 41377@pindex elinos.py 41378@cindex ELinOS system-wide configuration script 41379This script is useful when debugging a program on an ELinOS target. 41380It takes advantage of the environment variables defined in a standard 41381ELinOS environment in order to determine the location of the system 41382shared libraries, and then sets the @samp{solib-absolute-prefix} 41383and @samp{solib-search-path} variables appropriately. 41384 41385@item @file{wrs-linux.py} 41386@pindex wrs-linux.py 41387@cindex Wind River Linux system-wide configuration script 41388This script is useful when debugging a program on a target running 41389Wind River Linux. It expects the @env{ENV_PREFIX} to be set to 41390the host-side sysroot used by the target system. 41391 41392@end itemize 41393 41394@node Maintenance Commands 41395@appendix Maintenance Commands 41396@cindex maintenance commands 41397@cindex internal commands 41398 41399In addition to commands intended for @value{GDBN} users, @value{GDBN} 41400includes a number of commands intended for @value{GDBN} developers, 41401that are not documented elsewhere in this manual. These commands are 41402provided here for reference. (For commands that turn on debugging 41403messages, see @ref{Debugging Output}.) 41404 41405@table @code 41406@kindex maint agent 41407@kindex maint agent-eval 41408@item maint agent @r{[}-at @var{linespec}@r{,}@r{]} @var{expression} 41409@itemx maint agent-eval @r{[}-at @var{linespec}@r{,}@r{]} @var{expression} 41410Translate the given @var{expression} into remote agent bytecodes. 41411This command is useful for debugging the Agent Expression mechanism 41412(@pxref{Agent Expressions}). The @samp{agent} version produces an 41413expression useful for data collection, such as by tracepoints, while 41414@samp{maint agent-eval} produces an expression that evaluates directly 41415to a result. For instance, a collection expression for @code{globa + 41416globb} will include bytecodes to record four bytes of memory at each 41417of the addresses of @code{globa} and @code{globb}, while discarding 41418the result of the addition, while an evaluation expression will do the 41419addition and return the sum. 41420If @code{-at} is given, generate remote agent bytecode for all the 41421addresses to which @var{linespec} resolves (@pxref{Linespec 41422Locations}). 41423If not, generate remote agent bytecode for current frame PC address. 41424 41425@kindex maint agent-printf 41426@item maint agent-printf @var{format},@var{expr},... 41427Translate the given format string and list of argument expressions 41428into remote agent bytecodes and display them as a disassembled list. 41429This command is useful for debugging the agent version of dynamic 41430printf (@pxref{Dynamic Printf}). 41431 41432@kindex maint info breakpoints 41433@item @anchor{maint info breakpoints}maint info breakpoints 41434Using the same format as @samp{info breakpoints}, display both the 41435breakpoints you've set explicitly, and those @value{GDBN} is using for 41436internal purposes. Internal breakpoints are shown with negative 41437breakpoint numbers. The type column identifies what kind of breakpoint 41438is shown: 41439 41440@table @code 41441@item breakpoint 41442Normal, explicitly set breakpoint. 41443 41444@item watchpoint 41445Normal, explicitly set watchpoint. 41446 41447@item longjmp 41448Internal breakpoint, used to handle correctly stepping through 41449@code{longjmp} calls. 41450 41451@item longjmp resume 41452Internal breakpoint at the target of a @code{longjmp}. 41453 41454@item until 41455Temporary internal breakpoint used by the @value{GDBN} @code{until} command. 41456 41457@item finish 41458Temporary internal breakpoint used by the @value{GDBN} @code{finish} command. 41459 41460@item shlib events 41461Shared library events. 41462 41463@end table 41464 41465@kindex maint info btrace 41466@item maint info btrace 41467Pint information about raw branch tracing data. 41468 41469@kindex maint btrace packet-history 41470@item maint btrace packet-history 41471Print the raw branch trace packets that are used to compute the 41472execution history for the @samp{record btrace} command. Both the 41473information and the format in which it is printed depend on the btrace 41474recording format. 41475 41476@table @code 41477@item bts 41478For the BTS recording format, print a list of blocks of sequential 41479code. For each block, the following information is printed: 41480 41481@table @asis 41482@item Block number 41483Newer blocks have higher numbers. The oldest block has number zero. 41484@item Lowest @samp{PC} 41485@item Highest @samp{PC} 41486@end table 41487 41488@item pt 41489For the Intel Processor Trace recording format, print a list of 41490Intel Processor Trace packets. For each packet, the following 41491information is printed: 41492 41493@table @asis 41494@item Packet number 41495Newer packets have higher numbers. The oldest packet has number zero. 41496@item Trace offset 41497The packet's offset in the trace stream. 41498@item Packet opcode and payload 41499@end table 41500@end table 41501 41502@kindex maint btrace clear-packet-history 41503@item maint btrace clear-packet-history 41504Discards the cached packet history printed by the @samp{maint btrace 41505packet-history} command. The history will be computed again when 41506needed. 41507 41508@kindex maint btrace clear 41509@item maint btrace clear 41510Discard the branch trace data. The data will be fetched anew and the 41511branch trace will be recomputed when needed. 41512 41513This implicitly truncates the branch trace to a single branch trace 41514buffer. When updating branch trace incrementally, the branch trace 41515available to @value{GDBN} may be bigger than a single branch trace 41516buffer. 41517 41518@kindex maint set btrace pt skip-pad 41519@item maint set btrace pt skip-pad 41520@kindex maint show btrace pt skip-pad 41521@item maint show btrace pt skip-pad 41522Control whether @value{GDBN} will skip PAD packets when computing the 41523packet history. 41524 41525@kindex maint info jit 41526@item maint info jit 41527Print information about JIT code objects loaded in the current inferior. 41528 41529@anchor{maint info python-disassemblers} 41530@kindex maint info python-disassemblers 41531@item maint info python-disassemblers 41532This command is defined within the @code{gdb.disassembler} Python 41533module (@pxref{Disassembly In Python}), and will only be present after 41534that module has been imported. To force the module to be imported do 41535the following: 41536 41537@kindex maint info linux-lwps 41538@item maint info linux-lwps 41539Print information about LWPs under control of the Linux native target. 41540 41541@smallexample 41542(@value{GDBP}) python import gdb.disassembler 41543@end smallexample 41544 41545This command lists all the architectures for which a disassembler is 41546currently registered, and the name of the disassembler. If a 41547disassembler is registered for all architectures, then this is listed 41548last against the @samp{GLOBAL} architecture. 41549 41550If one of the disassemblers would be selected for the architecture of 41551the current inferior, then this disassembler will be marked. 41552 41553The following example shows a situation in which two disassemblers are 41554registered, initially the @samp{i386} disassembler matches the current 41555architecture, then the architecture is changed, now the @samp{GLOBAL} 41556disassembler matches. 41557 41558@smallexample 41559@group 41560(@value{GDBP}) show architecture 41561The target architecture is set to "auto" (currently "i386"). 41562(@value{GDBP}) maint info python-disassemblers 41563Architecture Disassember Name 41564i386 Disassembler_1 (Matches current architecture) 41565GLOBAL Disassembler_2 41566@end group 41567@group 41568(@value{GDBP}) set architecture arm 41569The target architecture is set to "arm". 41570(@value{GDBP}) maint info python-disassemblers 41571quit 41572Architecture Disassember Name 41573i386 Disassembler_1 41574GLOBAL Disassembler_2 (Matches current architecture) 41575@end group 41576@end smallexample 41577 41578@kindex set displaced-stepping 41579@kindex show displaced-stepping 41580@cindex displaced stepping support 41581@cindex out-of-line single-stepping 41582@item set displaced-stepping 41583@itemx show displaced-stepping 41584Control whether or not @value{GDBN} will do @dfn{displaced stepping} 41585if the target supports it. Displaced stepping is a way to single-step 41586over breakpoints without removing them from the inferior, by executing 41587an out-of-line copy of the instruction that was originally at the 41588breakpoint location. It is also known as out-of-line single-stepping. 41589 41590@table @code 41591@item set displaced-stepping on 41592If the target architecture supports it, @value{GDBN} will use 41593displaced stepping to step over breakpoints. 41594 41595@item set displaced-stepping off 41596@value{GDBN} will not use displaced stepping to step over breakpoints, 41597even if such is supported by the target architecture. 41598 41599@cindex non-stop mode, and @samp{set displaced-stepping} 41600@item set displaced-stepping auto 41601This is the default mode. @value{GDBN} will use displaced stepping 41602only if non-stop mode is active (@pxref{Non-Stop Mode}) and the target 41603architecture supports displaced stepping. 41604@end table 41605 41606@kindex maint check-psymtabs 41607@item maint check-psymtabs 41608Check the consistency of currently expanded psymtabs versus symtabs. 41609Use this to check, for example, whether a symbol is in one but not the other. 41610 41611@kindex maint check-symtabs 41612@item maint check-symtabs 41613Check the consistency of currently expanded symtabs. 41614 41615@kindex maint expand-symtabs 41616@item maint expand-symtabs [@var{regexp}] 41617Expand symbol tables. 41618If @var{regexp} is specified, only expand symbol tables for file 41619names matching @var{regexp}. 41620 41621@kindex maint set catch-demangler-crashes 41622@kindex maint show catch-demangler-crashes 41623@cindex demangler crashes 41624@item maint set catch-demangler-crashes [on|off] 41625@itemx maint show catch-demangler-crashes 41626Control whether @value{GDBN} should attempt to catch crashes in the 41627symbol name demangler. The default is to attempt to catch crashes. 41628If enabled, the first time a crash is caught, a core file is created, 41629the offending symbol is displayed and the user is presented with the 41630option to terminate the current session. 41631 41632@kindex maint cplus first_component 41633@item maint cplus first_component @var{name} 41634Print the first C@t{++} class/namespace component of @var{name}. 41635 41636@kindex maint cplus namespace 41637@item maint cplus namespace 41638Print the list of possible C@t{++} namespaces. 41639 41640@kindex maint deprecate 41641@kindex maint undeprecate 41642@cindex deprecated commands 41643@item maint deprecate @var{command} @r{[}@var{replacement}@r{]} 41644@itemx maint undeprecate @var{command} 41645Deprecate or undeprecate the named @var{command}. Deprecated commands 41646cause @value{GDBN} to issue a warning when you use them. The optional 41647argument @var{replacement} says which newer command should be used in 41648favor of the deprecated one; if it is given, @value{GDBN} will mention 41649the replacement as part of the warning. 41650 41651@kindex maint dump-me 41652@item maint dump-me 41653@cindex @code{SIGQUIT} signal, dump core of @value{GDBN} 41654Cause a fatal signal in the debugger and force it to dump its core. 41655This is supported only on systems which support aborting a program 41656with the @code{SIGQUIT} signal. 41657 41658@kindex maint internal-error 41659@kindex maint internal-warning 41660@kindex maint demangler-warning 41661@cindex demangler crashes 41662@item maint internal-error @r{[}@var{message-text}@r{]} 41663@itemx maint internal-warning @r{[}@var{message-text}@r{]} 41664@itemx maint demangler-warning @r{[}@var{message-text}@r{]} 41665 41666Cause @value{GDBN} to call the internal function @code{internal_error}, 41667@code{internal_warning} or @code{demangler_warning} and hence behave 41668as though an internal problem has been detected. In addition to 41669reporting the internal problem, these functions give the user the 41670opportunity to either quit @value{GDBN} or (for @code{internal_error} 41671and @code{internal_warning}) create a core file of the current 41672@value{GDBN} session. 41673 41674These commands take an optional parameter @var{message-text} that is 41675used as the text of the error or warning message. 41676 41677Here's an example of using @code{internal-error}: 41678 41679@smallexample 41680(@value{GDBP}) @kbd{maint internal-error testing, 1, 2} 41681@dots{}/maint.c:121: internal-error: testing, 1, 2 41682A problem internal to GDB has been detected. Further 41683debugging may prove unreliable. 41684Quit this debugging session? (y or n) @kbd{n} 41685Create a core file? (y or n) @kbd{n} 41686(@value{GDBP}) 41687@end smallexample 41688 41689@kindex maint set debuginfod download-sections 41690@kindex maint show debuginfod download-sections 41691@cindex debuginfod, maintenance commands 41692@item maint set debuginfod download-sections 41693@itemx maint set debuginfod download-sections @r{[}on|off@r{]} 41694@itemx maint show debuginfod download-sections 41695Controls whether @value{GDBN} will attempt to download individual 41696ELF/DWARF sections from @code{debuginfod}. If disabled, only 41697whole debug info files will be downloaded; this could result 41698in @value{GDBN} downloading larger amounts of data. 41699 41700@cindex @value{GDBN} internal error 41701@cindex internal errors, control of @value{GDBN} behavior 41702@cindex demangler crashes 41703 41704@kindex maint set internal-error 41705@kindex maint show internal-error 41706@kindex maint set internal-warning 41707@kindex maint show internal-warning 41708@kindex maint set demangler-warning 41709@kindex maint show demangler-warning 41710@item maint set internal-error @var{action} [ask|yes|no] 41711@itemx maint show internal-error @var{action} 41712@itemx maint set internal-warning @var{action} [ask|yes|no] 41713@itemx maint show internal-warning @var{action} 41714@itemx maint set demangler-warning @var{action} [ask|yes|no] 41715@itemx maint show demangler-warning @var{action} 41716When @value{GDBN} reports an internal problem (error or warning) it 41717gives the user the opportunity to both quit @value{GDBN} and create a 41718core file of the current @value{GDBN} session. These commands let you 41719override the default behaviour for each particular @var{action}, 41720described in the table below. 41721 41722@table @samp 41723@item quit 41724You can specify that @value{GDBN} should always (yes) or never (no) 41725quit. The default is to ask the user what to do. 41726 41727@item corefile 41728You can specify that @value{GDBN} should always (yes) or never (no) 41729create a core file. The default is to ask the user what to do. Note 41730that there is no @code{corefile} option for @code{demangler-warning}: 41731demangler warnings always create a core file and this cannot be 41732disabled. 41733@end table 41734 41735@kindex maint set internal-error 41736@kindex maint show internal-error 41737@kindex maint set internal-warning 41738@kindex maint show internal-warning 41739@item maint set internal-error backtrace @r{[}on|off@r{]} 41740@itemx maint show internal-error backtrace 41741@itemx maint set internal-warning backtrace @r{[}on|off@r{]} 41742@itemx maint show internal-warning backtrace 41743When @value{GDBN} reports an internal problem (error or warning) it is 41744possible to have a backtrace of @value{GDBN} printed to the standard 41745error stream. This is @samp{on} by default for @code{internal-error} 41746and @samp{off} by default for @code{internal-warning}. 41747 41748@anchor{maint packet} 41749@kindex maint packet 41750@item maint packet @var{text} 41751If @value{GDBN} is talking to an inferior via the serial protocol, 41752then this command sends the string @var{text} to the inferior, and 41753displays the response packet. @value{GDBN} supplies the initial 41754@samp{$} character, the terminating @samp{#} character, and the 41755checksum. 41756 41757Any non-printable characters in the reply are printed as escaped hex, 41758e.g. @samp{\x00}, @samp{\x01}, etc. 41759 41760@kindex maint print architecture 41761@item maint print architecture @r{[}@var{file}@r{]} 41762Print the entire architecture configuration. The optional argument 41763@var{file} names the file where the output goes. 41764 41765@kindex maint print c-tdesc 41766@item maint print c-tdesc @r{[}-single-feature@r{]} @r{[}@var{file}@r{]} 41767Print the target description (@pxref{Target Descriptions}) as 41768a C source file. By default, the target description is for the current 41769target, but if the optional argument @var{file} is provided, that file 41770is used to produce the description. The @var{file} should be an XML 41771document, of the form described in @ref{Target Description Format}. 41772The created source file is built into @value{GDBN} when @value{GDBN} is 41773built again. This command is used by developers after they add or 41774modify XML target descriptions. 41775 41776When the optional flag @samp{-single-feature} is provided then the 41777target description being processed (either the default, or from 41778@var{file}) must only contain a single feature. The source file 41779produced is different in this case. 41780 41781@kindex maint print xml-tdesc 41782@item maint print xml-tdesc @r{[}@var{file}@r{]} 41783Print the target description (@pxref{Target Descriptions}) as an XML 41784file. By default print the target description for the current target, 41785but if the optional argument @var{file} is provided, then that file is 41786read in by GDB and then used to produce the description. The 41787@var{file} should be an XML document, of the form described in 41788@ref{Target Description Format}. 41789 41790@kindex maint check xml-descriptions 41791@item maint check xml-descriptions @var{dir} 41792Check that the target descriptions dynamically created by @value{GDBN} 41793equal the descriptions created from XML files found in @var{dir}. 41794 41795@anchor{maint check libthread-db} 41796@kindex maint check libthread-db 41797@item maint check libthread-db 41798Run integrity checks on the current inferior's thread debugging 41799library. This exercises all @code{libthread_db} functionality used by 41800@value{GDBN} on GNU/Linux systems, and by extension also exercises the 41801@code{proc_service} functions provided by @value{GDBN} that 41802@code{libthread_db} uses. Note that parts of the test may be skipped 41803on some platforms when debugging core files. 41804 41805@kindex maint print core-file-backed-mappings 41806@cindex memory address space mappings 41807@item maint print core-file-backed-mappings 41808Print the file-backed mappings which were loaded from a core file note. 41809This output represents state internal to @value{GDBN} and should be 41810similar to the mappings displayed by the @code{info proc mappings} 41811command. 41812 41813@kindex maint print dummy-frames 41814@item maint print dummy-frames 41815Prints the contents of @value{GDBN}'s internal dummy-frame stack. 41816 41817@smallexample 41818(@value{GDBP}) @kbd{b add} 41819@dots{} 41820(@value{GDBP}) @kbd{print add(2,3)} 41821Breakpoint 2, add (a=2, b=3) at @dots{} 4182258 return (a + b); 41823The program being debugged stopped while in a function called from GDB. 41824@dots{} 41825(@value{GDBP}) @kbd{maint print dummy-frames} 418260xa8206d8: id=@{stack=0xbfffe734,code=0xbfffe73f,!special@}, ptid=process 9353 41827(@value{GDBP}) 41828@end smallexample 41829 41830Takes an optional file parameter. 41831 41832@kindex maint print frame-id 41833@item maint print frame-id 41834@itemx maint print frame-id @var{level} 41835Print @value{GDBN}'s internal frame-id for the frame at relative 41836@var{level}, or for the currently selected frame when @var{level} is 41837not given. 41838 41839If used, @var{level} should be an integer, as displayed in the 41840@command{backtrace} output. 41841 41842@smallexample 41843(@value{GDBP}) maint print frame-id 41844frame-id for frame #0: @{stack=0x7fffffffac70,code=0x0000000000401106,!special@} 41845(@value{GDBP}) maint print frame-id 2 41846frame-id for frame #2: @{stack=0x7fffffffac90,code=0x000000000040111c,!special@} 41847@end smallexample 41848 41849@kindex maint print registers 41850@kindex maint print raw-registers 41851@kindex maint print cooked-registers 41852@kindex maint print register-groups 41853@kindex maint print remote-registers 41854@item maint print registers @r{[}@var{file}@r{]} 41855@itemx maint print raw-registers @r{[}@var{file}@r{]} 41856@itemx maint print cooked-registers @r{[}@var{file}@r{]} 41857@itemx maint print register-groups @r{[}@var{file}@r{]} 41858@itemx maint print remote-registers @r{[}@var{file}@r{]} 41859Print @value{GDBN}'s internal register data structures. 41860 41861The command @code{maint print raw-registers} includes the contents of 41862the raw register cache; the command @code{maint print 41863cooked-registers} includes the (cooked) value of all registers, 41864including registers which aren't available on the target nor visible 41865to user; the command @code{maint print register-groups} includes the 41866groups that each register is a member of; and the command @code{maint 41867print remote-registers} includes the remote target's register numbers 41868and offsets in the `G' packets. 41869 41870These commands take an optional parameter, a file name to which to 41871write the information. 41872 41873@kindex maint print reggroups 41874@item maint print reggroups @r{[}@var{file}@r{]} 41875Print @value{GDBN}'s internal register group data structures. The 41876optional argument @var{file} tells to what file to write the 41877information. 41878 41879The register groups info looks like this: 41880 41881@smallexample 41882(@value{GDBP}) @kbd{maint print reggroups} 41883 Group Type 41884 general user 41885 float user 41886 all user 41887 vector user 41888 system user 41889 save internal 41890 restore internal 41891@end smallexample 41892 41893@kindex maint flush register-cache 41894@kindex flushregs 41895@cindex register cache, flushing 41896@item maint flush register-cache 41897@itemx flushregs 41898Flush the contents of the register cache and as a consequence the 41899frame cache. This command is useful when debugging issues related to 41900register fetching, or frame unwinding. The command @code{flushregs} 41901is deprecated in favor of @code{maint flush register-cache}. 41902 41903@kindex maint flush source-cache 41904@cindex source code, caching 41905@item maint flush source-cache 41906Flush @value{GDBN}'s cache of source code file contents. After 41907@value{GDBN} reads a source file, and optionally applies styling 41908(@pxref{Output Styling}), the file contents are cached. This command 41909clears that cache. The next time @value{GDBN} wants to show lines 41910from a source file, the content will be re-read. 41911 41912This command is useful when debugging issues related to source code 41913styling. After flushing the cache any source code displayed by 41914@value{GDBN} will be re-read and re-styled. 41915 41916@kindex maint print objfiles 41917@cindex info for known object files 41918@item maint print objfiles @r{[}@var{regexp}@r{]} 41919Print a dump of all known object files. 41920If @var{regexp} is specified, only print object files whose names 41921match @var{regexp}. For each object file, this command prints its name, 41922address in memory, and all of its psymtabs and symtabs. 41923 41924@kindex maint print user-registers 41925@cindex user registers 41926@item maint print user-registers 41927List all currently available @dfn{user registers}. User registers 41928typically provide alternate names for actual hardware registers. They 41929include the four ``standard'' registers @code{$fp}, @code{$pc}, 41930@code{$sp}, and @code{$ps}. @xref{standard registers}. User 41931registers can be used in expressions in the same way as the canonical 41932register names, but only the latter are listed by the @code{info 41933registers} and @code{maint print registers} commands. 41934 41935@kindex maint print section-scripts 41936@cindex info for known .debug_gdb_scripts-loaded scripts 41937@item maint print section-scripts [@var{regexp}] 41938Print a dump of scripts specified in the @code{.debug_gdb_section} section. 41939If @var{regexp} is specified, only print scripts loaded by object files 41940matching @var{regexp}. 41941For each script, this command prints its name as specified in the objfile, 41942and the full path if known. 41943@xref{dotdebug_gdb_scripts section}. 41944 41945@kindex maint print statistics 41946@cindex bcache statistics 41947@item maint print statistics 41948This command prints, for each object file in the program, various data 41949about that object file followed by the byte cache (@dfn{bcache}) 41950statistics for the object file. The objfile data includes the number 41951of minimal, partial, full, and stabs symbols, the number of types 41952defined by the objfile, the number of as yet unexpanded psym tables, 41953the number of line tables and string tables, and the amount of memory 41954used by the various tables. The bcache statistics include the counts, 41955sizes, and counts of duplicates of all and unique objects, max, 41956average, and median entry size, total memory used and its overhead and 41957savings, and various measures of the hash table size and chain 41958lengths. 41959 41960@kindex maint print target-stack 41961@cindex target stack description 41962@item maint print target-stack 41963A @dfn{target} is an interface between the debugger and a particular 41964kind of file or process. Targets can be stacked in @dfn{strata}, 41965so that more than one target can potentially respond to a request. 41966In particular, memory accesses will walk down the stack of targets 41967until they find a target that is interested in handling that particular 41968address. 41969 41970This command prints a short description of each layer that was pushed on 41971the @dfn{target stack}, starting from the top layer down to the bottom one. 41972 41973@kindex maint print type 41974@cindex type chain of a data type 41975@item maint print type @var{expr} 41976Print the type chain for a type specified by @var{expr}. The argument 41977can be either a type name or a symbol. If it is a symbol, the type of 41978that symbol is described. The type chain produced by this command is 41979a recursive definition of the data type as stored in @value{GDBN}'s 41980data structures, including its flags and contained types. 41981 41982@kindex maint print record-instruction 41983@item maint print record-instruction 41984@itemx maint print record-instruction @var{N} 41985print how GDB recorded a given instruction. If @var{n} is not positive 41986number, it prints the values stored by the inferior before the @var{n}-th previous 41987instruction was executed. If @var{n} is positive, print the values after the @var{n}-th 41988following instruction is executed. If @var{n} is not given, 0 is assumed. 41989 41990@kindex maint selftest 41991@cindex self tests 41992@item maint selftest @r{[}-verbose@r{]} @r{[}@var{filter}@r{]} 41993Run any self tests that were compiled in to @value{GDBN}. This will 41994print a message showing how many tests were run, and how many failed. 41995If a @var{filter} is passed, only the tests with @var{filter} in their 41996name will be ran. If @code{-verbose} is passed, the self tests can be 41997more verbose. 41998 41999@kindex maint set selftest verbose 42000@kindex maint show selftest verbose 42001@cindex self tests 42002@item maint set selftest verbose 42003@item maint show selftest verbose 42004Control whether self tests are run verbosely or not. 42005 42006@kindex maint info selftests 42007@cindex self tests 42008@item maint info selftests 42009List the selftests compiled in to @value{GDBN}. 42010 42011@kindex maint set dwarf always-disassemble 42012@kindex maint show dwarf always-disassemble 42013@item maint set dwarf always-disassemble 42014@item maint show dwarf always-disassemble 42015Control the behavior of @code{info address} when using DWARF debugging 42016information. 42017 42018The default is @code{off}, which means that @value{GDBN} should try to 42019describe a variable's location in an easily readable format. When 42020@code{on}, @value{GDBN} will instead display the DWARF location 42021expression in an assembly-like format. Note that some locations are 42022too complex for @value{GDBN} to describe simply; in this case you will 42023always see the disassembly form. 42024 42025Here is an example of the resulting disassembly: 42026 42027@smallexample 42028(@value{GDBP}) info addr argc 42029Symbol "argc" is a complex DWARF expression: 42030 1: DW_OP_fbreg 0 42031@end smallexample 42032 42033For more information on these expressions, see 42034@uref{http://www.dwarfstd.org/, the DWARF standard}. 42035 42036@kindex maint set dwarf max-cache-age 42037@kindex maint show dwarf max-cache-age 42038@item maint set dwarf max-cache-age 42039@itemx maint show dwarf max-cache-age 42040Control the DWARF compilation unit cache. 42041 42042@cindex DWARF compilation units cache 42043In object files with inter-compilation-unit references, such as those 42044produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 42045reader needs to frequently refer to previously read compilation units. 42046This setting controls how long a compilation unit will remain in the 42047cache if it is not referenced. A higher limit means that cached 42048compilation units will be stored in memory longer, and more total 42049memory will be used. Setting it to zero disables caching, which will 42050slow down @value{GDBN} startup, but reduce memory consumption. 42051 42052@kindex maint set dwarf synchronous 42053@kindex maint show dwarf synchronous 42054@item maint set dwarf synchronous 42055@itemx maint show dwarf synchronous 42056Control whether DWARF is read asynchronously. 42057 42058On hosts where threading is available, the DWARF reader is mostly 42059asynchronous with respect to the rest of @value{GDBN}. That is, the 42060bulk of the reading is done in the background, and @value{GDBN} will 42061only pause for completion of this task when absolutely necessary. 42062 42063When this setting is enabled, @value{GDBN} will instead wait for DWARF 42064processing to complete before continuing. 42065 42066On hosts without threading, or where worker threads have been disabled 42067at runtime, this setting has no effect, as DWARF reading is always 42068done on the main thread, and is therefore always synchronous. 42069 42070@kindex maint set dwarf unwinders 42071@kindex maint show dwarf unwinders 42072@item maint set dwarf unwinders 42073@itemx maint show dwarf unwinders 42074Control use of the DWARF frame unwinders. 42075 42076@cindex DWARF frame unwinders 42077Many targets that support DWARF debugging use @value{GDBN}'s DWARF 42078frame unwinders to build the backtrace. Many of these targets will 42079also have a second mechanism for building the backtrace for use in 42080cases where DWARF information is not available, this second mechanism 42081is often an analysis of a function's prologue. 42082 42083In order to extend testing coverage of the second level stack 42084unwinding mechanisms it is helpful to be able to disable the DWARF 42085stack unwinders, this can be done with this switch. 42086 42087In normal use of @value{GDBN} disabling the DWARF unwinders is not 42088advisable, there are cases that are better handled through DWARF than 42089prologue analysis, and the debug experience is likely to be better 42090with the DWARF frame unwinders enabled. 42091 42092If DWARF frame unwinders are not supported for a particular target 42093architecture, then enabling this flag does not cause them to be used. 42094 42095@kindex maint info frame-unwinders 42096@item maint info frame-unwinders 42097List the frame unwinders currently in effect, starting with the highest priority. 42098 42099@kindex maint set worker-threads 42100@kindex maint show worker-threads 42101@item maint set worker-threads 42102@item maint show worker-threads 42103Control the number of worker threads that may be used by @value{GDBN}. 42104On capable hosts, @value{GDBN} may use multiple threads to speed up 42105certain CPU-intensive operations, such as demangling symbol names. 42106While the number of threads used by @value{GDBN} may vary, this 42107command can be used to set an upper bound on this number. The default 42108is @code{unlimited}, which lets @value{GDBN} choose a reasonable 42109number. Note that this only controls worker threads started by 42110@value{GDBN} itself; libraries used by @value{GDBN} may start threads 42111of their own. 42112 42113@kindex maint set profile 42114@kindex maint show profile 42115@cindex profiling GDB 42116@item maint set profile 42117@itemx maint show profile 42118Control profiling of @value{GDBN}. 42119 42120Profiling will be disabled until you use the @samp{maint set profile} 42121command to enable it. When you enable profiling, the system will begin 42122collecting timing and execution count data; when you disable profiling or 42123exit @value{GDBN}, the results will be written to a log file. Remember that 42124if you use profiling, @value{GDBN} will overwrite the profiling log file 42125(often called @file{gmon.out}). If you have a record of important profiling 42126data in a @file{gmon.out} file, be sure to move it to a safe location. 42127 42128Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be 42129compiled with the @samp{-pg} compiler option. 42130 42131@kindex maint set show-debug-regs 42132@kindex maint show show-debug-regs 42133@cindex hardware debug registers 42134@item maint set show-debug-regs 42135@itemx maint show show-debug-regs 42136Control whether to show variables that mirror the hardware debug 42137registers. Use @code{on} to enable, @code{off} to disable. If 42138enabled, the debug registers values are shown when @value{GDBN} inserts or 42139removes a hardware breakpoint or watchpoint, and when the inferior 42140triggers a hardware-assisted breakpoint or watchpoint. 42141 42142@kindex maint set show-all-tib 42143@kindex maint show show-all-tib 42144@item maint set show-all-tib 42145@itemx maint show show-all-tib 42146Control whether to show all non zero areas within a 1k block starting 42147at thread local base, when using the @samp{info w32 thread-information-block} 42148command. 42149 42150@kindex maint set target-async 42151@kindex maint show target-async 42152@item maint set target-async 42153@itemx maint show target-async 42154This controls whether @value{GDBN} targets operate in synchronous or 42155asynchronous mode (@pxref{Background Execution}). Normally the 42156default is asynchronous, if it is available; but this can be changed 42157to more easily debug problems occurring only in synchronous mode. 42158 42159@kindex maint set target-non-stop @var{mode} [on|off|auto] 42160@kindex maint show target-non-stop 42161@item maint set target-non-stop 42162@itemx maint show target-non-stop 42163 42164This controls whether @value{GDBN} targets always operate in non-stop 42165mode even if @code{set non-stop} is @code{off} (@pxref{Non-Stop 42166Mode}). The default is @code{auto}, meaning non-stop mode is enabled 42167if supported by the target. 42168 42169@table @code 42170@item maint set target-non-stop auto 42171This is the default mode. @value{GDBN} controls the target in 42172non-stop mode if the target supports it. 42173 42174@item maint set target-non-stop on 42175@value{GDBN} controls the target in non-stop mode even if the target 42176does not indicate support. 42177 42178@item maint set target-non-stop off 42179@value{GDBN} does not control the target in non-stop mode even if the 42180target supports it. 42181@end table 42182 42183@kindex maint set tui-resize-message 42184@kindex maint show tui-resize-message 42185@item maint set tui-resize-message 42186@item maint show tui-resize-message 42187Control whether @value{GDBN} displays a message each time the terminal 42188is resized when in TUI mode. The default is @code{off}, which means 42189that @value{GDBN} is silent during resizes. When @code{on}, 42190@value{GDBN} will display a message after a resize is completed; the 42191message will include a number indicating how many times the terminal 42192has been resized. This setting is intended for use by the test suite, 42193where it would otherwise be difficult to determine when a resize and 42194refresh has been completed. 42195 42196@kindex maint set tui-left-margin-verbose 42197@kindex maint show tui-left-margin-verbose 42198@item maint set tui-left-margin-verbose 42199@item maint show tui-left-margin-verbose 42200Control whether the left margin of the TUI source and disassembly windows 42201uses @samp{_} and @samp{0} at locations where otherwise there would be a 42202space. The default is @code{off}, which means spaces are used. The 42203setting is intended to make it clear where the left margin begins and 42204ends, to avoid incorrectly interpreting a space as being part of the 42205the left margin. 42206 42207@kindex maint set per-command 42208@kindex maint show per-command 42209@item maint set per-command 42210@itemx maint show per-command 42211@cindex resources used by commands 42212 42213@value{GDBN} can display the resources used by each command. 42214This is useful in debugging performance problems. 42215 42216@table @code 42217@item maint set per-command space [on|off] 42218@itemx maint show per-command space 42219Enable or disable the printing of the memory used by GDB for each command. 42220If enabled, @value{GDBN} will display how much memory each command 42221took, following the command's own output. 42222This can also be requested by invoking @value{GDBN} with the 42223@option{--statistics} command-line switch (@pxref{Mode Options}). 42224 42225@item maint set per-command time [on|off] 42226@itemx maint show per-command time 42227Enable or disable the printing of the execution time of @value{GDBN} 42228for each command. 42229If enabled, @value{GDBN} will display how much time it 42230took to execute each command, following the command's own output. 42231Both CPU time and wallclock time are printed. 42232Printing both is useful when trying to determine whether the cost is 42233CPU or, e.g., disk/network latency. 42234Note that the CPU time printed is for @value{GDBN} only, it does not include 42235the execution time of the inferior because there's no mechanism currently 42236to compute how much time was spent by @value{GDBN} and how much time was 42237spent by the program been debugged. 42238This can also be requested by invoking @value{GDBN} with the 42239@option{--statistics} command-line switch (@pxref{Mode Options}). 42240 42241@item maint set per-command symtab [on|off] 42242@itemx maint show per-command symtab 42243Enable or disable the printing of basic symbol table statistics 42244for each command. 42245If enabled, @value{GDBN} will display the following information: 42246 42247@enumerate a 42248@item 42249number of symbol tables 42250@item 42251number of primary symbol tables 42252@item 42253number of blocks in the blockvector 42254@end enumerate 42255@end table 42256 42257@kindex maint set check-libthread-db 42258@kindex maint show check-libthread-db 42259@item maint set check-libthread-db [on|off] 42260@itemx maint show check-libthread-db 42261Control whether @value{GDBN} should run integrity checks on inferior 42262specific thread debugging libraries as they are loaded. The default 42263is not to perform such checks. If any check fails @value{GDBN} will 42264unload the library and continue searching for a suitable candidate as 42265described in @ref{set libthread-db-search-path}. For more information 42266about the tests, see @ref{maint check libthread-db}. 42267 42268@kindex maint set gnu-source-highlight enabled 42269@kindex maint show gnu-source-highlight enabled 42270@item maint set gnu-source-highlight enabled @r{[}on|off@r{]} 42271@itemx maint show gnu-source-highlight enabled 42272Control whether @value{GDBN} should use the GNU Source Highlight 42273library for applying styling to source code (@pxref{Output Styling}). 42274This will be @samp{on} by default if the GNU Source Highlight library 42275is available. If the GNU Source Highlight library is not available, 42276then this will be @samp{off} by default, and attempting to change this 42277value to @samp{on} will give an error. 42278 42279If the GNU Source Highlight library is not being used, then 42280@value{GDBN} will use the Python Pygments package for source code 42281styling, if it is available. 42282 42283This option is useful for debugging @value{GDBN}'s use of the Pygments 42284library when @value{GDBN} is linked against the GNU Source Highlight 42285library. 42286 42287@anchor{maint_libopcodes_styling} 42288@kindex maint set libopcodes-styling enabled 42289@kindex maint show libopcodes-styling enabled 42290@item maint set libopcodes-styling enabled @r{[}on|off@r{]} 42291@itemx maint show libopcodes-styling enabled 42292Control whether @value{GDBN} should use its builtin disassembler 42293(@file{libopcodes}) to style disassembler output (@pxref{Output 42294Styling}). The builtin disassembler does not support styling for all 42295architectures. 42296 42297When this option is @samp{off} the builtin disassembler will not be 42298used for styling, @value{GDBN} will fall back to using the Python 42299Pygments package if possible. 42300 42301Trying to set this option @samp{on} for an architecture that the 42302builtin disassembler is unable to style will give an error, otherwise, 42303the builtin disassembler will be used to style disassembler output. 42304 42305This option is @samp{on} by default for supported architectures. 42306 42307This option is useful for debugging @value{GDBN}'s use of the Pygments 42308library when @value{GDBN} is built for an architecture that supports 42309styling with the builtin disassembler 42310 42311@kindex maint info screen 42312@cindex show screen characteristics 42313@item maint info screen 42314Print various characteristics of the screen, such as various notions 42315of width and height. 42316 42317@kindex maint space 42318@cindex memory used by commands 42319@item maint space @var{value} 42320An alias for @code{maint set per-command space}. 42321A non-zero value enables it, zero disables it. 42322 42323@kindex maint time 42324@cindex time of command execution 42325@item maint time @var{value} 42326An alias for @code{maint set per-command time}. 42327A non-zero value enables it, zero disables it. 42328 42329@kindex maint translate-address 42330@item maint translate-address @r{[}@var{section}@r{]} @var{addr} 42331Find the symbol stored at the location specified by the address 42332@var{addr} and an optional section name @var{section}. If found, 42333@value{GDBN} prints the name of the closest symbol and an offset from 42334the symbol's location to the specified address. This is similar to 42335the @code{info address} command (@pxref{Symbols}), except that this 42336command also allows to find symbols in other sections. 42337 42338If section was not specified, the section in which the symbol was found 42339is also printed. For dynamically linked executables, the name of 42340executable or shared library containing the symbol is printed as well. 42341 42342@kindex maint test-options 42343@item maint test-options require-delimiter 42344@itemx maint test-options unknown-is-error 42345@itemx maint test-options unknown-is-operand 42346These commands are used by the testsuite to validate the command 42347options framework. The @code{require-delimiter} variant requires a 42348double-dash delimiter to indicate end of options. The 42349@code{unknown-is-error} and @code{unknown-is-operand} do not. The 42350@code{unknown-is-error} variant throws an error on unknown option, 42351while @code{unknown-is-operand} treats unknown options as the start of 42352the command's operands. When run, the commands output the result of 42353the processed options. When completed, the commands store the 42354internal result of completion in a variable exposed by the @code{maint 42355show test-options-completion-result} command. 42356 42357@kindex maint show test-options-completion-result 42358@item maint show test-options-completion-result 42359Shows the result of completing the @code{maint test-options} 42360subcommands. This is used by the testsuite to validate completion 42361support in the command options framework. 42362 42363@kindex maint set test-settings 42364@kindex maint show test-settings 42365@item maint set test-settings @var{kind} 42366@itemx maint show test-settings @var{kind} 42367These are representative commands for each @var{kind} of setting type 42368@value{GDBN} supports. They are used by the testsuite for exercising 42369the settings infrastructure. 42370 42371@kindex maint set backtrace-on-fatal-signal 42372@kindex maint show backtrace-on-fatal-signal 42373@item maint set backtrace-on-fatal-signal [on|off] 42374@itemx maint show backtrace-on-fatal-signal 42375When this setting is @code{on}, if @value{GDBN} itself terminates with 42376a fatal signal (e.g.@: SIGSEGV), then a limited backtrace will be 42377printed to the standard error stream. This backtrace can be used to 42378help diagnose crashes within @value{GDBN} in situations where a user 42379is unable to share a corefile with the @value{GDBN} developers. 42380 42381If the functionality to provide this backtrace is not available for 42382the platform on which GDB is running then this feature will be 42383@code{off} by default, and attempting to turn this feature on will 42384give an error. 42385 42386For platforms that do support creating the backtrace this feature is 42387@code{on} by default. 42388 42389@kindex maint wait-for-index-cache 42390@item maint wait-for-index-cache 42391Wait until all pending writes to the index cache have completed. This 42392is used by the test suite to avoid races when the index cache is being 42393updated by a worker thread. 42394 42395@kindex maint with 42396@item maint with @var{setting} [@var{value}] [-- @var{command}] 42397Like the @code{with} command, but works with @code{maintenance set} 42398variables. This is used by the testsuite to exercise the @code{with} 42399command's infrastructure. 42400 42401@kindex maint ignore-probes 42402@item maint ignore-probes [@var{-v}|@var{-verbose}] [@var{provider} [@var{name} [@var{objfile}]]] 42403@itemx maint ignore-probes @var{-reset} 42404Set or reset the ignore-probes filter. The @var{provider}, @var{name} 42405and @var{objfile} arguments are as in @code{enable probes} and 42406@code{disable probes} (@pxref{enable probes}). Only supported for 42407SystemTap probes. 42408 42409Here's an example of using @code{maint ignore-probes}: 42410@smallexample 42411(gdb) maint ignore-probes -verbose libc ^longjmp$ 42412ignore-probes filter has been set to: 42413PROVIDER: 'libc' 42414PROBE_NAME: '^longjmp$' 42415OBJNAME: '' 42416(gdb) start 42417<... more output ...> 42418Ignoring SystemTap probe libc longjmp in /lib64/libc.so.6.^M 42419Ignoring SystemTap probe libc longjmp in /lib64/libc.so.6.^M 42420Ignoring SystemTap probe libc longjmp in /lib64/libc.so.6.^M 42421@end smallexample 42422@end table 42423 42424The following command is useful for non-interactive invocations of 42425@value{GDBN}, such as in the test suite. 42426 42427@table @code 42428@item set watchdog @var{nsec} 42429@kindex set watchdog 42430@cindex watchdog timer 42431@cindex timeout for commands 42432Set the maximum number of seconds @value{GDBN} will wait for the 42433target operation to finish. If this time expires, @value{GDBN} 42434reports and error and the command is aborted. 42435 42436@item show watchdog 42437Show the current setting of the target wait timeout. 42438@end table 42439 42440@node Remote Protocol 42441@appendix @value{GDBN} Remote Serial Protocol 42442 42443@menu 42444* Overview:: 42445* Standard Replies:: 42446* Packets:: 42447* Stop Reply Packets:: 42448* General Query Packets:: 42449* Architecture-Specific Protocol Details:: 42450* Tracepoint Packets:: 42451* Host I/O Packets:: 42452* Interrupts:: 42453* Notification Packets:: 42454* Remote Non-Stop:: 42455* Packet Acknowledgment:: 42456* Examples:: 42457* File-I/O Remote Protocol Extension:: 42458* Library List Format:: 42459* Library List Format for SVR4 Targets:: 42460* Memory Map Format:: 42461* Thread List Format:: 42462* Traceframe Info Format:: 42463* Branch Trace Format:: 42464* Branch Trace Configuration Format:: 42465@end menu 42466 42467@node Overview 42468@section Overview 42469 42470There may be occasions when you need to know something about the 42471protocol---for example, if there is only one serial port to your target 42472machine, you might want your program to do something special if it 42473recognizes a packet meant for @value{GDBN}. 42474 42475In the examples below, @samp{->} and @samp{<-} are used to indicate 42476transmitted and received data, respectively. 42477 42478@cindex protocol, @value{GDBN} remote serial 42479@cindex serial protocol, @value{GDBN} remote 42480@cindex remote serial protocol 42481All @value{GDBN} commands and responses (other than acknowledgments 42482and notifications, see @ref{Notification Packets}) are sent as a 42483@var{packet}. A @var{packet} is introduced with the character 42484@samp{$}, the actual @var{packet-data}, and the terminating character 42485@samp{#} followed by a two-digit @var{checksum}: 42486 42487@smallexample 42488@code{$}@var{packet-data}@code{#}@var{checksum} 42489@end smallexample 42490@noindent 42491 42492@cindex checksum, for @value{GDBN} remote 42493@noindent 42494The two-digit @var{checksum} is computed as the modulo 256 sum of all 42495characters between the leading @samp{$} and the trailing @samp{#} (an 42496eight bit unsigned checksum). 42497 42498Implementors should note that prior to @value{GDBN} 5.0 the protocol 42499specification also included an optional two-digit @var{sequence-id}: 42500 42501@smallexample 42502@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} 42503@end smallexample 42504 42505@cindex sequence-id, for @value{GDBN} remote 42506@noindent 42507That @var{sequence-id} was appended to the acknowledgment. @value{GDBN} 42508has never output @var{sequence-id}s. Stubs that handle packets added 42509since @value{GDBN} 5.0 must not accept @var{sequence-id}. 42510 42511When either the host or the target machine receives a packet, the first 42512response expected is an acknowledgment: either @samp{+} (to indicate 42513the package was received correctly) or @samp{-} (to request 42514retransmission): 42515 42516@smallexample 42517-> @code{$}@var{packet-data}@code{#}@var{checksum} 42518<- @code{+} 42519@end smallexample 42520@noindent 42521 42522The @samp{+}/@samp{-} acknowledgments can be disabled 42523once a connection is established. 42524@xref{Packet Acknowledgment}, for details. 42525 42526The host (@value{GDBN}) sends @var{command}s, and the target (the 42527debugging stub incorporated in your program) sends a @var{response}. In 42528the case of step and continue @var{command}s, the response is only sent 42529when the operation has completed, and the target has again stopped all 42530threads in all attached processes. This is the default all-stop mode 42531behavior, but the remote protocol also supports @value{GDBN}'s non-stop 42532execution mode; see @ref{Remote Non-Stop}, for details. 42533 42534@var{packet-data} consists of a sequence of characters with the 42535exception of @samp{#} and @samp{$} (see @samp{X} packet for additional 42536exceptions). 42537 42538@cindex remote protocol, field separator 42539Fields within the packet should be separated using @samp{,} @samp{;} or 42540@samp{:}. Except where otherwise noted all numbers are represented in 42541@sc{hex} with leading zeros suppressed. 42542 42543Implementors should note that prior to @value{GDBN} 5.0, the character 42544@samp{:} could not appear as the third character in a packet (as it 42545would potentially conflict with the @var{sequence-id}). 42546 42547@cindex remote protocol, binary data 42548@anchor{Binary Data} 42549Binary data in most packets is encoded as two hexadecimal 42550digits per byte of binary data. This allowed the traditional remote 42551protocol to work over connections which were only seven-bit clean. 42552Some packets designed more recently assume an eight-bit clean 42553connection, and use a more efficient encoding to send and receive 42554binary data. 42555 42556The binary data representation uses @code{7d} (@sc{ascii} @samp{@}}) 42557as an escape character. Any escaped byte is transmitted as the escape 42558character followed by the original character XORed with @code{0x20}. 42559For example, the byte @code{0x7d} would be transmitted as the two 42560bytes @code{0x7d 0x5d}. The bytes @code{0x23} (@sc{ascii} @samp{#}), 42561@code{0x24} (@sc{ascii} @samp{$}), and @code{0x7d} (@sc{ascii} 42562@samp{@}}) must always be escaped. Responses sent by the stub 42563must also escape @code{0x2a} (@sc{ascii} @samp{*}), so that it 42564is not interpreted as the start of a run-length encoded sequence 42565(described next). 42566 42567Response @var{data} can be run-length encoded to save space. 42568Run-length encoding replaces runs of identical characters with one 42569instance of the repeated character, followed by a @samp{*} and a 42570repeat count. The repeat count is itself sent encoded, to avoid 42571binary characters in @var{data}: a value of @var{n} is sent as 42572@code{@var{n}+29}. For a repeat count greater or equal to 3, this 42573produces a printable @sc{ascii} character, e.g.@: a space (@sc{ascii} 42574code 32) for a repeat count of 3. (This is because run-length 42575encoding starts to win for counts 3 or more.) Thus, for example, 42576@samp{0* } is a run-length encoding of ``0000'': the space character 42577after @samp{*} means repeat the leading @code{0} @w{@code{32 - 29 = 425783}} more times. 42579 42580The printable characters @samp{#} and @samp{$} or with a numeric value 42581greater than 126 must not be used. Runs of six repeats (@samp{#}) or 42582seven repeats (@samp{$}) can be expanded using a repeat count of only 42583five (@samp{"}). For example, @samp{00000000} can be encoded as 42584@samp{0*"00}. 42585 42586@xref{Standard Replies} for standard error responses, and how to 42587respond indicating a command is not supported. 42588 42589In describing packets (commands and responses), each description has a 42590template showing the overall syntax, followed by an explanation of the 42591packet's meaning. We include spaces in some of the templates for 42592clarity; these are not part of the packet's syntax. No @value{GDBN} 42593packet uses spaces to separate its components. For example, a 42594template like @samp{foo @var{bar} @var{baz}} describes a packet 42595beginning with the three ASCII bytes @samp{foo}, followed by a 42596@var{bar}, followed directly by a @var{baz}. @value{GDBN} does not 42597transmit a space character between the @samp{foo} and the @var{bar}, 42598or between the @var{bar} and the @var{baz}. 42599 42600We place optional portions of a packet in [square brackets]; 42601for example, a template like @samp{c @r{[}@var{addr}@r{]}} describes a 42602packet beginning with the single ASCII character @samp{c}, possibly 42603followed by an @var{addr}. 42604 42605At a minimum, a stub is required to support the @samp{?} command to 42606tell @value{GDBN} the reason for halting, @samp{g} and @samp{G} 42607commands for register access, and the @samp{m} and @samp{M} commands 42608for memory access. Stubs that only control single-threaded targets 42609can implement run control with the @samp{c} (continue) command, and if 42610the target architecture supports hardware-assisted single-stepping, 42611the @samp{s} (step) command. Stubs that support multi-threading 42612targets should support the @samp{vCont} command. All other commands 42613are optional. 42614 42615@node Standard Replies 42616@section Standard Replies 42617@cindex standard responses for remote packets 42618@cindex remote packets, standard replies 42619 42620The remote protocol specifies a few standard replies. All commands 42621support these, except as noted in the individual command descriptions. 42622 42623@table @asis 42624 42625@item empty response 42626 42627@cindex empty response, for unsupported packets 42628@cindex unsupported packets, empty response for 42629An empty response (raw character sequence @samp{$#00}) means the 42630@var{command} is not supported by the stub. This way it is possible 42631to extend the protocol. A newer @value{GDBN} can tell if a command is 42632supported based on that response (but see also @ref{qSupported}). 42633 42634@item @samp{E @var{xx}} 42635An error has occurred; @var{xx} is a two-digit hexadecimal error 42636number. In almost all cases, the protocol does not specify the 42637meaning of the error numbers; @value{GDBN} usually ignores the 42638numbers, or displays them to the user without further interpretation. 42639 42640@anchor{textual error reply} 42641@item @samp{E.@var{errtext}} 42642An error has occurred; @var{errtext} is the textual error message, 42643encoded in @sc{ascii}. 42644 42645@end table 42646 42647@node Packets 42648@section Packets 42649 42650The following table provides a complete list of all currently defined 42651@var{command}s and their corresponding response @var{data}. 42652@xref{File-I/O Remote Protocol Extension}, for details about the File 42653I/O extension of the remote protocol. 42654 42655Each packet's description has a template showing the packet's overall 42656syntax, followed by an explanation of the packet's meaning. We 42657include spaces in some of the templates for clarity; these are not 42658part of the packet's syntax. No @value{GDBN} packet uses spaces to 42659separate its components. For example, a template like @samp{foo 42660@var{bar} @var{baz}} describes a packet beginning with the three ASCII 42661bytes @samp{foo}, followed by a @var{bar}, followed directly by a 42662@var{baz}. @value{GDBN} does not transmit a space character between the 42663@samp{foo} and the @var{bar}, or between the @var{bar} and the 42664@var{baz}. 42665 42666@cindex @var{thread-id}, in remote protocol 42667@anchor{thread-id syntax} 42668Several packets and replies include a @var{thread-id} field to identify 42669a thread. Normally these are positive numbers with a target-specific 42670interpretation, formatted as big-endian hex strings. A @var{thread-id} 42671can also be a literal @samp{-1} to indicate all threads, or @samp{0} to 42672pick any thread. 42673 42674In addition, the remote protocol supports a multiprocess feature in 42675which the @var{thread-id} syntax is extended to optionally include both 42676process and thread ID fields, as @samp{p@var{pid}.@var{tid}}. 42677The @var{pid} (process) and @var{tid} (thread) components each have the 42678format described above: a positive number with target-specific 42679interpretation formatted as a big-endian hex string, literal @samp{-1} 42680to indicate all processes or threads (respectively), or @samp{0} to 42681indicate an arbitrary process or thread. Specifying just a process, as 42682@samp{p@var{pid}}, is equivalent to @samp{p@var{pid}.-1}. It is an 42683error to specify all processes but a specific thread, such as 42684@samp{p-1.@var{tid}}. Note that the @samp{p} prefix is @emph{not} used 42685for those packets and replies explicitly documented to include a process 42686ID, rather than a @var{thread-id}. 42687 42688The multiprocess @var{thread-id} syntax extensions are only used if both 42689@value{GDBN} and the stub report support for the @samp{multiprocess} 42690feature using @samp{qSupported}. @xref{multiprocess extensions}, for 42691more information. 42692 42693Note that all packet forms beginning with an upper- or lower-case 42694letter, other than those described here, are reserved for future use. 42695 42696Here are the packet descriptions. 42697 42698@table @samp 42699 42700@item ! 42701@cindex @samp{!} packet 42702@anchor{extended mode} 42703Enable extended mode. In extended mode, the remote server is made 42704persistent. The @samp{R} packet is used to restart the program being 42705debugged. 42706 42707Reply: 42708@table @samp 42709@item OK 42710The remote target both supports and has enabled extended mode. 42711@end table 42712 42713@item ? 42714@cindex @samp{?} packet 42715@anchor{? packet} 42716This is sent when connection is first established to query the reason 42717the target halted. The reply is the same as for step and continue. 42718This packet has a special interpretation when the target is in 42719non-stop mode; see @ref{Remote Non-Stop}. 42720 42721Reply: 42722@xref{Stop Reply Packets}, for the reply specifications. 42723 42724@item A @var{arglen},@var{argnum},@var{arg},@dots{} 42725@cindex @samp{A} packet 42726Initialized @code{argv[]} array passed into program. @var{arglen} 42727specifies the number of bytes in the hex encoded byte stream 42728@var{arg}. See @code{gdbserver} for more details. 42729 42730Reply: 42731@table @samp 42732@item OK 42733The arguments were set. 42734@end table 42735 42736@item b @var{baud} 42737@cindex @samp{b} packet 42738(Don't use this packet; its behavior is not well-defined.) 42739Change the serial line speed to @var{baud}. 42740 42741JTC: @emph{When does the transport layer state change? When it's 42742received, or after the ACK is transmitted. In either case, there are 42743problems if the command or the acknowledgment packet is dropped.} 42744 42745Stan: @emph{If people really wanted to add something like this, and get 42746it working for the first time, they ought to modify ser-unix.c to send 42747some kind of out-of-band message to a specially-setup stub and have the 42748switch happen "in between" packets, so that from remote protocol's point 42749of view, nothing actually happened.} 42750 42751@item B @var{addr},@var{mode} 42752@cindex @samp{B} packet 42753Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a 42754breakpoint at @var{addr}. 42755 42756Don't use this packet. Use the @samp{Z} and @samp{z} packets instead 42757(@pxref{insert breakpoint or watchpoint packet}). 42758 42759@cindex @samp{bc} packet 42760@anchor{bc} 42761@item bc 42762Backward continue. Execute the target system in reverse. No parameter. 42763@xref{Reverse Execution}, for more information. 42764 42765Reply: 42766@xref{Stop Reply Packets}, for the reply specifications. 42767 42768@cindex @samp{bs} packet 42769@anchor{bs} 42770@item bs 42771Backward single step. Execute one instruction in reverse. No parameter. 42772@xref{Reverse Execution}, for more information. 42773 42774Reply: 42775@xref{Stop Reply Packets}, for the reply specifications. 42776 42777@item c @r{[}@var{addr}@r{]} 42778@cindex @samp{c} packet 42779Continue at @var{addr}, which is the address to resume. If @var{addr} 42780is omitted, resume at current address. 42781 42782This packet is deprecated for multi-threading support. @xref{vCont 42783packet}. 42784 42785Reply: 42786@xref{Stop Reply Packets}, for the reply specifications. 42787 42788@item C @var{sig}@r{[};@var{addr}@r{]} 42789@cindex @samp{C} packet 42790Continue with signal @var{sig} (hex signal number). If 42791@samp{;@var{addr}} is omitted, resume at same address. 42792 42793This packet is deprecated for multi-threading support. @xref{vCont 42794packet}. 42795 42796Reply: 42797@xref{Stop Reply Packets}, for the reply specifications. 42798 42799@item d 42800@cindex @samp{d} packet 42801Toggle debug flag. 42802 42803Don't use this packet; instead, define a general set packet 42804(@pxref{General Query Packets}). 42805 42806@item D 42807@itemx D;@var{pid} 42808@cindex @samp{D} packet 42809The first form of the packet is used to detach @value{GDBN} from the 42810remote system. It is sent to the remote target 42811before @value{GDBN} disconnects via the @code{detach} command. 42812 42813The second form, including a process ID, is used when multiprocess 42814protocol extensions are enabled (@pxref{multiprocess extensions}), to 42815detach only a specific process. The @var{pid} is specified as a 42816big-endian hex string. 42817 42818Reply: 42819@table @samp 42820@item OK 42821for success 42822@end table 42823 42824@item F @var{RC},@var{EE},@var{CF};@var{XX} 42825@cindex @samp{F} packet 42826A reply from @value{GDBN} to an @samp{F} packet sent by the target. 42827This is part of the File-I/O protocol extension. @xref{File-I/O 42828Remote Protocol Extension}, for the specification. 42829 42830@item g 42831@anchor{read registers packet} 42832@cindex @samp{g} packet 42833Read general registers. 42834 42835Reply: 42836@table @samp 42837@item @var{XX@dots{}} 42838Each byte of register data is described by two hex digits. The bytes 42839with the register are transmitted in target byte order. The size of 42840each register and their position within the @samp{g} packet are 42841determined by the target description (@pxref{Target Descriptions}); in 42842the absence of a target description, this is done using code internal 42843to @value{GDBN}; typically this is some customary register layout for 42844the architecture in question. 42845 42846When reading registers, the stub may also return a string of literal 42847@samp{x}'s in place of the register data digits, to indicate that the 42848corresponding register's value is unavailable. For example, when 42849reading registers from a trace frame (@pxref{Analyze Collected 42850Data,,Using the Collected Data}), this means that the register has not 42851been collected in the trace frame. When reading registers from a live 42852program, this indicates that the stub has no means to access the 42853register contents, even though the corresponding register is known to 42854exist. Note that if a register truly does not exist on the target, 42855then it is better to not include it in the target description in the 42856first place. 42857 42858For example, for an architecture with 4 registers of 428594 bytes each, the following reply indicates to @value{GDBN} that 42860registers 0 and 2 are unavailable, while registers 1 and 3 42861are available, and both have zero value: 42862 42863@smallexample 42864-> @code{g} 42865<- @code{xxxxxxxx00000000xxxxxxxx00000000} 42866@end smallexample 42867 42868@end table 42869 42870@item G @var{XX@dots{}} 42871@cindex @samp{G} packet 42872Write general registers. @xref{read registers packet}, for a 42873description of the @var{XX@dots{}} data. 42874 42875Reply: 42876@table @samp 42877@item OK 42878for success 42879@end table 42880 42881@item H @var{op} @var{thread-id} 42882@cindex @samp{H} packet 42883Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g}, 42884@samp{G}, et.al.). Depending on the operation to be performed, @var{op} 42885should be @samp{c} for step and continue operations (note that this 42886is deprecated, supporting the @samp{vCont} command is a better 42887option), and @samp{g} for other operations. The thread designator 42888@var{thread-id} has the format and interpretation described in 42889@ref{thread-id syntax}. 42890 42891Reply: 42892@table @samp 42893@item OK 42894for success 42895@end table 42896 42897@c FIXME: JTC: 42898@c 'H': How restrictive (or permissive) is the thread model. If a 42899@c thread is selected and stopped, are other threads allowed 42900@c to continue to execute? As I mentioned above, I think the 42901@c semantics of each command when a thread is selected must be 42902@c described. For example: 42903@c 42904@c 'g': If the stub supports threads and a specific thread is 42905@c selected, returns the register block from that thread; 42906@c otherwise returns current registers. 42907@c 42908@c 'G' If the stub supports threads and a specific thread is 42909@c selected, sets the registers of the register block of 42910@c that thread; otherwise sets current registers. 42911 42912@item i @r{[}@var{addr}@r{[},@var{nnn}@r{]]} 42913@anchor{cycle step packet} 42914@cindex @samp{i} packet 42915Step the remote target by a single clock cycle. If @samp{,@var{nnn}} is 42916present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle 42917step starting at that address. 42918 42919@item I 42920@cindex @samp{I} packet 42921Signal, then cycle step. @xref{step with signal packet}. @xref{cycle 42922step packet}. 42923 42924@item k 42925@cindex @samp{k} packet 42926Kill request. 42927 42928The exact effect of this packet is not specified. 42929 42930For a bare-metal target, it may power cycle or reset the target 42931system. For that reason, the @samp{k} packet has no reply. 42932 42933For a single-process target, it may kill that process if possible. 42934 42935A multiple-process target may choose to kill just one process, or all 42936that are under @value{GDBN}'s control. For more precise control, use 42937the vKill packet (@pxref{vKill packet}). 42938 42939If the target system immediately closes the connection in response to 42940@samp{k}, @value{GDBN} does not consider the lack of packet 42941acknowledgment to be an error, and assumes the kill was successful. 42942 42943If connected using @kbd{target extended-remote}, and the target does 42944not close the connection in response to a kill request, @value{GDBN} 42945probes the target state as if a new connection was opened 42946(@pxref{? packet}). 42947 42948@item m @var{addr},@var{length} 42949@cindex @samp{m} packet 42950Read @var{length} addressable memory units starting at address @var{addr} 42951(@pxref{addressable memory unit}). Note that @var{addr} may not be aligned to 42952any particular boundary. 42953 42954The stub need not use any particular size or alignment when gathering 42955data from memory for the response; even if @var{addr} is word-aligned 42956and @var{length} is a multiple of the word size, the stub is free to 42957use byte accesses, or not. For this reason, this packet may not be 42958suitable for accessing memory-mapped I/O devices. 42959@cindex alignment of remote memory accesses 42960@cindex size of remote memory accesses 42961@cindex memory, alignment and size of remote accesses 42962 42963Reply: 42964@table @samp 42965@item @var{XX@dots{}} 42966Memory contents; each byte is transmitted as a two-digit hexadecimal number. 42967The reply may contain fewer addressable memory units than requested if the 42968server was able to read only part of the region of memory. 42969@end table 42970 42971Unlike most packets, this packet does not support 42972@samp{E.@var{errtext}}-style textual error replies (@pxref{textual 42973error reply}). 42974 42975@item M @var{addr},@var{length}:@var{XX@dots{}} 42976@cindex @samp{M} packet 42977Write @var{length} addressable memory units starting at address @var{addr} 42978(@pxref{addressable memory unit}). The data is given by @var{XX@dots{}}; each 42979byte is transmitted as a two-digit hexadecimal number. 42980 42981Reply: 42982@table @samp 42983@item OK 42984All the data was written successfully. (If only part of the data was 42985written, this command returns an error.) 42986@end table 42987 42988@item p @var{n} 42989@cindex @samp{p} packet 42990Read the value of register @var{n}; @var{n} is in hex. 42991@xref{read registers packet}, for a description of how the returned 42992register value is encoded. 42993 42994Reply: 42995@table @samp 42996@item @var{XX@dots{}} 42997the register's value 42998@end table 42999 43000@item P @var{n@dots{}}=@var{r@dots{}} 43001@anchor{write register packet} 43002@cindex @samp{P} packet 43003Write register @var{n@dots{}} with value @var{r@dots{}}. The register 43004number @var{n} is in hexadecimal, and @var{r@dots{}} contains two hex 43005digits for each byte in the register (target byte order). 43006 43007Reply: 43008@table @samp 43009@item OK 43010for success 43011@end table 43012 43013@item q @var{name} @var{params}@dots{} 43014@itemx Q @var{name} @var{params}@dots{} 43015@cindex @samp{q} packet 43016@cindex @samp{Q} packet 43017General query (@samp{q}) and set (@samp{Q}). These packets are 43018described fully in @ref{General Query Packets}. 43019 43020@item r 43021@cindex @samp{r} packet 43022Reset the entire system. 43023 43024Don't use this packet; use the @samp{R} packet instead. 43025 43026@item R @var{XX} 43027@cindex @samp{R} packet 43028Restart the program being debugged. The @var{XX}, while needed, is ignored. 43029This packet is only available in extended mode (@pxref{extended mode}). 43030 43031The @samp{R} packet has no reply. 43032 43033@item s @r{[}@var{addr}@r{]} 43034@cindex @samp{s} packet 43035Single step, resuming at @var{addr}. If 43036@var{addr} is omitted, resume at same address. 43037 43038This packet is deprecated for multi-threading support. @xref{vCont 43039packet}. 43040 43041Reply: 43042@xref{Stop Reply Packets}, for the reply specifications. 43043 43044@item S @var{sig}@r{[};@var{addr}@r{]} 43045@anchor{step with signal packet} 43046@cindex @samp{S} packet 43047Step with signal. This is analogous to the @samp{C} packet, but 43048requests a single-step, rather than a normal resumption of execution. 43049 43050This packet is deprecated for multi-threading support. @xref{vCont 43051packet}. 43052 43053Reply: 43054@xref{Stop Reply Packets}, for the reply specifications. 43055 43056@item t @var{addr}:@var{PP},@var{MM} 43057@cindex @samp{t} packet 43058Search backwards starting at address @var{addr} for a match with pattern 43059@var{PP} and mask @var{MM}, both of which are are 4 byte long. 43060There must be at least 3 digits in @var{addr}. 43061 43062@item T @var{thread-id} 43063@cindex @samp{T} packet 43064Find out if the thread @var{thread-id} is alive. @xref{thread-id syntax}. 43065 43066Reply: 43067@table @samp 43068@item OK 43069thread is still alive 43070@end table 43071 43072@item v 43073Packets starting with @samp{v} are identified by a multi-letter name, 43074up to the first @samp{;} or @samp{?} (or the end of the packet). 43075 43076@item vAttach;@var{pid} 43077@cindex @samp{vAttach} packet 43078Attach to a new process with the specified process ID @var{pid}. 43079The process ID is a 43080hexadecimal integer identifying the process. In all-stop mode, all 43081threads in the attached process are stopped; in non-stop mode, it may be 43082attached without being stopped if that is supported by the target. 43083 43084@c In non-stop mode, on a successful vAttach, the stub should set the 43085@c current thread to a thread of the newly-attached process. After 43086@c attaching, GDB queries for the attached process's thread ID with qC. 43087@c Also note that, from a user perspective, whether or not the 43088@c target is stopped on attach in non-stop mode depends on whether you 43089@c use the foreground or background version of the attach command, not 43090@c on what vAttach does; GDB does the right thing with respect to either 43091@c stopping or restarting threads. 43092 43093This packet is only available in extended mode (@pxref{extended mode}). 43094 43095Reply: 43096@table @samp 43097@item @r{Any stop packet} 43098for success in all-stop mode (@pxref{Stop Reply Packets}) 43099@item OK 43100for success in non-stop mode (@pxref{Remote Non-Stop}) 43101@end table 43102 43103@item vCont@r{[};@var{action}@r{[}:@var{thread-id}@r{]]}@dots{} 43104@cindex @samp{vCont} packet 43105@anchor{vCont packet} 43106Resume the inferior, specifying different actions for each thread. 43107 43108For each inferior thread, the leftmost action with a matching 43109@var{thread-id} is applied. Threads that don't match any action 43110remain in their current state. Thread IDs are specified using the 43111syntax described in @ref{thread-id syntax}. If multiprocess 43112extensions (@pxref{multiprocess extensions}) are supported, actions 43113can be specified to match all threads in a process by using the 43114@samp{p@var{pid}.-1} form of the @var{thread-id}. An action with no 43115@var{thread-id} matches all threads. Specifying no actions is an 43116error. 43117 43118Currently supported actions are: 43119 43120@table @samp 43121@item c 43122Continue. 43123@item C @var{sig} 43124Continue with signal @var{sig}. The signal @var{sig} should be two hex digits. 43125@item s 43126Step. 43127@item S @var{sig} 43128Step with signal @var{sig}. The signal @var{sig} should be two hex digits. 43129@item t 43130Stop. 43131@item r @var{start},@var{end} 43132Step once, and then keep stepping as long as the thread stops at 43133addresses between @var{start} (inclusive) and @var{end} (exclusive). 43134The remote stub reports a stop reply when either the thread goes out 43135of the range or is stopped due to an unrelated reason, such as hitting 43136a breakpoint. @xref{range stepping}. 43137 43138If the range is empty (@var{start} == @var{end}), then the action 43139becomes equivalent to the @samp{s} action. In other words, 43140single-step once, and report the stop (even if the stepped instruction 43141jumps to @var{start}). 43142 43143(A stop reply may be sent at any point even if the PC is still within 43144the stepping range; for example, it is valid to implement this packet 43145in a degenerate way as a single instruction step operation.) 43146 43147@end table 43148 43149The optional argument @var{addr} normally associated with the 43150@samp{c}, @samp{C}, @samp{s}, and @samp{S} packets is 43151not supported in @samp{vCont}. 43152 43153The @samp{t} action is only relevant in non-stop mode 43154(@pxref{Remote Non-Stop}) and may be ignored by the stub otherwise. 43155A stop reply should be generated for any affected thread not already stopped. 43156When a thread is stopped by means of a @samp{t} action, 43157the corresponding stop reply should indicate that the thread has stopped with 43158signal @samp{0}, regardless of whether the target uses some other signal 43159as an implementation detail. 43160 43161The server must ignore @samp{c}, @samp{C}, @samp{s}, @samp{S}, and 43162@samp{r} actions for threads that are already running. Conversely, 43163the server must ignore @samp{t} actions for threads that are already 43164stopped. 43165 43166@emph{Note:} In non-stop mode, a thread is considered running until 43167@value{GDBN} acknowledges an asynchronous stop notification for it with 43168the @samp{vStopped} packet (@pxref{Remote Non-Stop}). 43169 43170The stub must support @samp{vCont} if it reports support for 43171multiprocess extensions (@pxref{multiprocess extensions}). 43172 43173Reply: 43174@xref{Stop Reply Packets}, for the reply specifications. 43175 43176@item vCont? 43177@cindex @samp{vCont?} packet 43178Request a list of actions supported by the @samp{vCont} packet. 43179 43180Reply: 43181@table @samp 43182@item vCont@r{[};@var{action}@dots{}@r{]} 43183The @samp{vCont} packet is supported. Each @var{action} is a supported 43184command in the @samp{vCont} packet. 43185@end table 43186 43187@anchor{vCtrlC packet} 43188@item vCtrlC 43189@cindex @samp{vCtrlC} packet 43190Interrupt remote target as if a control-C was pressed on the remote 43191terminal. This is the equivalent to reacting to the @code{^C} 43192(@samp{\003}, the control-C character) character in all-stop mode 43193while the target is running, except this works in non-stop mode. 43194@xref{interrupting remote targets}, for more info on the all-stop 43195variant. 43196 43197Reply: 43198@table @samp 43199@item OK 43200for success 43201@end table 43202 43203@item vFile:@var{operation}:@var{parameter}@dots{} 43204@cindex @samp{vFile} packet 43205Perform a file operation on the target system. For details, 43206see @ref{Host I/O Packets}. 43207 43208@item vFlashErase:@var{addr},@var{length} 43209@cindex @samp{vFlashErase} packet 43210Direct the stub to erase @var{length} bytes of flash starting at 43211@var{addr}. The region may enclose any number of flash blocks, but 43212its start and end must fall on block boundaries, as indicated by the 43213flash block size appearing in the memory map (@pxref{Memory Map 43214Format}). @value{GDBN} groups flash memory programming operations 43215together, and sends a @samp{vFlashDone} request after each group; the 43216stub is allowed to delay erase operation until the @samp{vFlashDone} 43217packet is received. 43218 43219Reply: 43220@table @samp 43221@item OK 43222for success 43223@end table 43224 43225@item vFlashWrite:@var{addr}:@var{XX@dots{}} 43226@cindex @samp{vFlashWrite} packet 43227Direct the stub to write data to flash address @var{addr}. The data 43228is passed in binary form using the same encoding as for the @samp{X} 43229packet (@pxref{Binary Data}). The memory ranges specified by 43230@samp{vFlashWrite} packets preceding a @samp{vFlashDone} packet must 43231not overlap, and must appear in order of increasing addresses 43232(although @samp{vFlashErase} packets for higher addresses may already 43233have been received; the ordering is guaranteed only between 43234@samp{vFlashWrite} packets). If a packet writes to an address that was 43235neither erased by a preceding @samp{vFlashErase} packet nor by some other 43236target-specific method, the results are unpredictable. 43237 43238 43239Reply: 43240@table @samp 43241@item OK 43242for success 43243@item E.memtype 43244for vFlashWrite addressing non-flash memory 43245@end table 43246 43247@item vFlashDone 43248@cindex @samp{vFlashDone} packet 43249Indicate to the stub that flash programming operation is finished. 43250The stub is permitted to delay or batch the effects of a group of 43251@samp{vFlashErase} and @samp{vFlashWrite} packets until a 43252@samp{vFlashDone} packet is received. The contents of the affected 43253regions of flash memory are unpredictable until the @samp{vFlashDone} 43254request is completed. 43255 43256@item vKill;@var{pid} 43257@cindex @samp{vKill} packet 43258@anchor{vKill packet} 43259Kill the process with the specified process ID @var{pid}, which is a 43260hexadecimal integer identifying the process. This packet is used in 43261preference to @samp{k} when multiprocess protocol extensions are 43262supported; see @ref{multiprocess extensions}. 43263 43264Reply: 43265@table @samp 43266@item OK 43267for success 43268@end table 43269 43270@item vMustReplyEmpty 43271@cindex @samp{vMustReplyEmpty} packet 43272The correct reply to an unknown @samp{v} packet is to return the empty 43273string, however, some older versions of @command{gdbserver} would 43274incorrectly return @samp{OK} for unknown @samp{v} packets. 43275 43276The @samp{vMustReplyEmpty} is used as a feature test to check how 43277@command{gdbserver} handles unknown packets, it is important that this 43278packet be handled in the same way as other unknown @samp{v} packets. 43279If this packet is handled differently to other unknown @samp{v} 43280packets then it is possible that @value{GDBN} may run into problems in 43281other areas, specifically around use of @samp{vFile:setfs:}. 43282 43283@item vRun;@var{filename}@r{[};@var{argument}@r{]}@dots{} 43284@cindex @samp{vRun} packet 43285Run the program @var{filename}, passing it each @var{argument} on its 43286command line. The file and arguments are hex-encoded strings. If 43287@var{filename} is an empty string, the stub may use a default program 43288(e.g.@: the last program run). The program is created in the stopped 43289state. 43290 43291@c FIXME: What about non-stop mode? 43292 43293This packet is only available in extended mode (@pxref{extended mode}). 43294 43295Reply: 43296@table @samp 43297@item @r{Any stop packet} 43298for success (@pxref{Stop Reply Packets}) 43299@end table 43300 43301@item vStopped 43302@cindex @samp{vStopped} packet 43303@xref{Notification Packets}. 43304 43305@item X @var{addr},@var{length}:@var{XX@dots{}} 43306@anchor{X packet} 43307@cindex @samp{X} packet 43308Write data to memory, where the data is transmitted in binary. 43309Memory is specified by its address @var{addr} and number of addressable memory 43310units @var{length} (@pxref{addressable memory unit}); 43311@samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}). 43312 43313Reply: 43314@table @samp 43315@item OK 43316for success 43317@end table 43318 43319@item z @var{type},@var{addr},@var{kind} 43320@itemx Z @var{type},@var{addr},@var{kind} 43321@anchor{insert breakpoint or watchpoint packet} 43322@cindex @samp{z} packet 43323@cindex @samp{Z} packets 43324Insert (@samp{Z}) or remove (@samp{z}) a @var{type} breakpoint or 43325watchpoint starting at address @var{address} of kind @var{kind}. 43326 43327Each breakpoint and watchpoint packet @var{type} is documented 43328separately. 43329 43330@emph{Implementation notes: A remote target shall return an empty string 43331for an unrecognized breakpoint or watchpoint packet @var{type}. A 43332remote target shall support either both or neither of a given 43333@samp{Z@var{type}@dots{}} and @samp{z@var{type}@dots{}} packet pair. To 43334avoid potential problems with duplicate packets, the operations should 43335be implemented in an idempotent way.} 43336 43337@item z0,@var{addr},@var{kind} 43338@itemx Z0,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}@r{[};cmds:@var{persist},@var{cmd_list}@dots{}@r{]} 43339@cindex @samp{z0} packet 43340@cindex @samp{Z0} packet 43341Insert (@samp{Z0}) or remove (@samp{z0}) a software breakpoint at address 43342@var{addr} of type @var{kind}. 43343 43344A software breakpoint is implemented by replacing the instruction at 43345@var{addr} with a software breakpoint or trap instruction. The 43346@var{kind} is target-specific and typically indicates the size of the 43347breakpoint in bytes that should be inserted. E.g., the @sc{arm} and 43348@sc{mips} can insert either a 2 or 4 byte breakpoint. Some 43349architectures have additional meanings for @var{kind} 43350(@pxref{Architecture-Specific Protocol Details}); if no 43351architecture-specific value is being used, it should be @samp{0}. 43352@var{kind} is hex-encoded. @var{cond_list} is an optional list of 43353conditional expressions in bytecode form that should be evaluated on 43354the target's side. These are the conditions that should be taken into 43355consideration when deciding if the breakpoint trigger should be 43356reported back to @value{GDBN}. 43357 43358See also the @samp{swbreak} stop reason (@pxref{swbreak stop reason}) 43359for how to best report a software breakpoint event to @value{GDBN}. 43360 43361The @var{cond_list} parameter is comprised of a series of expressions, 43362concatenated without separators. Each expression has the following form: 43363 43364@table @samp 43365 43366@item X @var{len},@var{expr} 43367@var{len} is the length of the bytecode expression and @var{expr} is the 43368actual conditional expression in bytecode form. 43369 43370@end table 43371 43372The optional @var{cmd_list} parameter introduces commands that may be 43373run on the target, rather than being reported back to @value{GDBN}. 43374The parameter starts with a numeric flag @var{persist}; if the flag is 43375nonzero, then the breakpoint may remain active and the commands 43376continue to be run even when @value{GDBN} disconnects from the target. 43377Following this flag is a series of expressions concatenated with no 43378separators. Each expression has the following form: 43379 43380@table @samp 43381 43382@item X @var{len},@var{expr} 43383@var{len} is the length of the bytecode expression and @var{expr} is the 43384actual commands expression in bytecode form. 43385 43386@end table 43387 43388@emph{Implementation note: It is possible for a target to copy or move 43389code that contains software breakpoints (e.g., when implementing 43390overlays). The behavior of this packet, in the presence of such a 43391target, is not defined.} 43392 43393Reply: 43394@table @samp 43395@item OK 43396success 43397@end table 43398 43399@item z1,@var{addr},@var{kind} 43400@itemx Z1,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}@r{[};cmds:@var{persist},@var{cmd_list}@dots{}@r{]} 43401@cindex @samp{z1} packet 43402@cindex @samp{Z1} packet 43403Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at 43404address @var{addr}. 43405 43406A hardware breakpoint is implemented using a mechanism that is not 43407dependent on being able to modify the target's memory. The 43408@var{kind}, @var{cond_list}, and @var{cmd_list} arguments have the 43409same meaning as in @samp{Z0} packets. 43410 43411@emph{Implementation note: A hardware breakpoint is not affected by code 43412movement.} 43413 43414Reply: 43415@table @samp 43416@item OK 43417success 43418@end table 43419 43420@item z2,@var{addr},@var{kind} 43421@itemx Z2,@var{addr},@var{kind} 43422@cindex @samp{z2} packet 43423@cindex @samp{Z2} packet 43424Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint at @var{addr}. 43425The number of bytes to watch is specified by @var{kind}. 43426 43427Reply: 43428@table @samp 43429@item OK 43430success 43431@end table 43432 43433@item z3,@var{addr},@var{kind} 43434@itemx Z3,@var{addr},@var{kind} 43435@cindex @samp{z3} packet 43436@cindex @samp{Z3} packet 43437Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint at @var{addr}. 43438The number of bytes to watch is specified by @var{kind}. 43439 43440Reply: 43441@table @samp 43442@item OK 43443success 43444@end table 43445 43446@item z4,@var{addr},@var{kind} 43447@itemx Z4,@var{addr},@var{kind} 43448@cindex @samp{z4} packet 43449@cindex @samp{Z4} packet 43450Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint at @var{addr}. 43451The number of bytes to watch is specified by @var{kind}. 43452 43453Reply: 43454@table @samp 43455@item OK 43456success 43457@end table 43458 43459@end table 43460 43461@node Stop Reply Packets 43462@section Stop Reply Packets 43463@cindex stop reply packets 43464 43465The @samp{C}, @samp{c}, @samp{S}, @samp{s}, @samp{vCont}, 43466@samp{vAttach}, @samp{vRun}, @samp{vStopped}, and @samp{?} packets can 43467receive any of the below as a reply. Except for @samp{?} 43468and @samp{vStopped}, that reply is only returned 43469when the target halts. In the below the exact meaning of @dfn{signal 43470number} is defined by the header @file{include/gdb/signals.h} in the 43471@value{GDBN} source code. 43472 43473In non-stop mode, the server will simply reply @samp{OK} to commands 43474such as @samp{vCont}; any stop will be the subject of a future 43475notification. @xref{Remote Non-Stop}. 43476 43477As in the description of request packets, we include spaces in the 43478reply templates for clarity; these are not part of the reply packet's 43479syntax. No @value{GDBN} stop reply packet uses spaces to separate its 43480components. 43481 43482@table @samp 43483 43484@item S @var{AA} 43485The program received signal number @var{AA} (a two-digit hexadecimal 43486number). This is equivalent to a @samp{T} response with no 43487@var{n}:@var{r} pairs. 43488 43489@item T @var{AA} @var{n1}:@var{r1};@var{n2}:@var{r2};@dots{} 43490@cindex @samp{T} packet reply 43491The program received signal number @var{AA} (a two-digit hexadecimal 43492number). This is equivalent to an @samp{S} response, except that the 43493@samp{@var{n}:@var{r}} pairs can carry values of important registers 43494and other information directly in the stop reply packet, reducing 43495round-trip latency. Single-step and breakpoint traps are reported 43496this way. Each @samp{@var{n}:@var{r}} pair is interpreted as follows: 43497 43498@itemize @bullet 43499@item 43500If @var{n} is a hexadecimal number, it is a register number, and the 43501corresponding @var{r} gives that register's value. The data @var{r} is a 43502series of bytes in target byte order, with each byte given by a 43503two-digit hex number. 43504 43505@item 43506If @var{n} is @samp{thread}, then @var{r} is the thread ID of 43507the stopped thread, as specified in @ref{thread-id syntax}. 43508 43509@item 43510If @var{n} is @samp{core}, then @var{r} is the hexadecimal number of 43511the core on which the stop event was detected. 43512 43513@item 43514If @var{n} is a recognized @dfn{stop reason}, it describes a more 43515specific event that stopped the target. The currently defined stop 43516reasons are listed below. The @var{aa} should be @samp{05}, the trap 43517signal. At most one stop reason should be present. 43518 43519@item 43520Otherwise, @value{GDBN} should ignore this @samp{@var{n}:@var{r}} pair 43521and go on to the next; this allows us to extend the protocol in the 43522future. 43523@end itemize 43524 43525The currently defined stop reasons are: 43526 43527@table @samp 43528@item watch 43529@itemx rwatch 43530@itemx awatch 43531The packet indicates a watchpoint hit, and @var{r} is the data address, in 43532hex. 43533 43534@item syscall_entry 43535@itemx syscall_return 43536The packet indicates a syscall entry or return, and @var{r} is the 43537syscall number, in hex. 43538 43539@cindex shared library events, remote reply 43540@item library 43541The packet indicates that the loaded libraries have changed. 43542@value{GDBN} should use @samp{qXfer:libraries:read} to fetch a new 43543list of loaded libraries. The @var{r} part is ignored. 43544 43545@cindex replay log events, remote reply 43546@item replaylog 43547The packet indicates that the target cannot continue replaying 43548logged execution events, because it has reached the end (or the 43549beginning when executing backward) of the log. The value of @var{r} 43550will be either @samp{begin} or @samp{end}. @xref{Reverse Execution}, 43551for more information. 43552 43553@item swbreak 43554@anchor{swbreak stop reason} 43555The packet indicates a software breakpoint instruction was executed, 43556irrespective of whether it was @value{GDBN} that planted the 43557breakpoint or the breakpoint is hardcoded in the program. The @var{r} 43558part must be left empty. 43559 43560On some architectures, such as x86, at the architecture level, when a 43561breakpoint instruction executes the program counter points at the 43562breakpoint address plus an offset. On such targets, the stub is 43563responsible for adjusting the PC to point back at the breakpoint 43564address. 43565 43566This packet should not be sent by default; older @value{GDBN} versions 43567did not support it. @value{GDBN} requests it, by supplying an 43568appropriate @samp{qSupported} feature (@pxref{qSupported}). The 43569remote stub must also supply the appropriate @samp{qSupported} feature 43570indicating support. 43571 43572This packet is required for correct non-stop mode operation. 43573 43574@item hwbreak 43575The packet indicates the target stopped for a hardware breakpoint. 43576The @var{r} part must be left empty. 43577 43578The same remarks about @samp{qSupported} and non-stop mode above 43579apply. 43580 43581@cindex fork events, remote reply 43582@item fork 43583The packet indicates that @code{fork} was called, and @var{r} is the 43584thread ID of the new child process, as specified in @ref{thread-id 43585syntax}. This packet is only applicable to targets that support fork 43586events. 43587 43588This packet should not be sent by default; older @value{GDBN} versions 43589did not support it. @value{GDBN} requests it, by supplying an 43590appropriate @samp{qSupported} feature (@pxref{qSupported}). The 43591remote stub must also supply the appropriate @samp{qSupported} feature 43592indicating support. 43593 43594@cindex vfork events, remote reply 43595@item vfork 43596The packet indicates that @code{vfork} was called, and @var{r} is the 43597thread ID of the new child process, as specified in @ref{thread-id 43598syntax}. This packet is only applicable to targets that support vfork 43599events. 43600 43601This packet should not be sent by default; older @value{GDBN} versions 43602did not support it. @value{GDBN} requests it, by supplying an 43603appropriate @samp{qSupported} feature (@pxref{qSupported}). The 43604remote stub must also supply the appropriate @samp{qSupported} feature 43605indicating support. 43606 43607@cindex vforkdone events, remote reply 43608@item vforkdone 43609The packet indicates that a child process created by a vfork 43610has either called @code{exec} or terminated, so that the 43611address spaces of the parent and child process are no longer 43612shared. The @var{r} part is ignored. This packet is only 43613applicable to targets that support vforkdone events. 43614 43615This packet should not be sent by default; older @value{GDBN} versions 43616did not support it. @value{GDBN} requests it, by supplying an 43617appropriate @samp{qSupported} feature (@pxref{qSupported}). The 43618remote stub must also supply the appropriate @samp{qSupported} feature 43619indicating support. 43620 43621@cindex exec events, remote reply 43622@item exec 43623The packet indicates that @code{execve} was called, and @var{r} 43624is the absolute pathname of the file that was executed, in hex. 43625This packet is only applicable to targets that support exec events. 43626 43627This packet should not be sent by default; older @value{GDBN} versions 43628did not support it. @value{GDBN} requests it, by supplying an 43629appropriate @samp{qSupported} feature (@pxref{qSupported}). The 43630remote stub must also supply the appropriate @samp{qSupported} feature 43631indicating support. 43632 43633@cindex thread clone events, remote reply 43634@anchor{thread clone event} 43635@item clone 43636The packet indicates that @code{clone} was called, and @var{r} is the 43637thread ID of the new child thread, as specified in @ref{thread-id 43638syntax}. This packet is only applicable to targets that support clone 43639events. 43640 43641This packet should not be sent by default; @value{GDBN} requests it 43642with the @ref{QThreadOptions} packet. 43643 43644@cindex thread create event, remote reply 43645@anchor{thread create event} 43646@item create 43647The packet indicates that the thread was just created. The new thread 43648is stopped until @value{GDBN} sets it running with a resumption packet 43649(@pxref{vCont packet}). This packet should not be sent by default; 43650@value{GDBN} requests it with the @ref{QThreadEvents} packet. See 43651also the @samp{w} (@pxref{thread exit event}) remote reply below. The 43652@var{r} part is ignored. 43653 43654@end table 43655 43656@item W @var{AA} 43657@itemx W @var{AA} ; process:@var{pid} 43658The process exited, and @var{AA} is the exit status. This is only 43659applicable to certain targets. 43660 43661The second form of the response, including the process ID of the 43662exited process, can be used only when @value{GDBN} has reported 43663support for multiprocess protocol extensions; see @ref{multiprocess 43664extensions}. Both @var{AA} and @var{pid} are formatted as big-endian 43665hex strings. 43666 43667@item X @var{AA} 43668@itemx X @var{AA} ; process:@var{pid} 43669The process terminated with signal @var{AA}. 43670 43671The second form of the response, including the process ID of the 43672terminated process, can be used only when @value{GDBN} has reported 43673support for multiprocess protocol extensions; see @ref{multiprocess 43674extensions}. Both @var{AA} and @var{pid} are formatted as big-endian 43675hex strings. 43676 43677@anchor{thread exit event} 43678@cindex thread exit event, remote reply 43679@item w @var{AA} ; @var{tid} 43680 43681The thread exited, and @var{AA} is the exit status. This response 43682should not be sent by default; @value{GDBN} requests it with either 43683the @ref{QThreadEvents} or @ref{QThreadOptions} packets. See also 43684@ref{thread create event} above. @var{AA} is formatted as a 43685big-endian hex string. 43686 43687@item N 43688There are no resumed threads left in the target. In other words, even 43689though the process is alive, the last resumed thread has exited. For 43690example, say the target process has two threads: thread 1 and thread 436912. The client leaves thread 1 stopped, and resumes thread 2, which 43692subsequently exits. At this point, even though the process is still 43693alive, and thus no @samp{W} stop reply is sent, no thread is actually 43694executing either. The @samp{N} stop reply thus informs the client 43695that it can stop waiting for stop replies. This packet should not be 43696sent by default; older @value{GDBN} versions did not support it. 43697@value{GDBN} requests it, by supplying an appropriate 43698@samp{qSupported} feature (@pxref{qSupported}). The remote stub must 43699also supply the appropriate @samp{qSupported} feature indicating 43700support. 43701 43702@item O @var{XX}@dots{} 43703@samp{@var{XX}@dots{}} is hex encoding of @sc{ascii} data, to be 43704written as the program's console output. This can happen at any time 43705while the program is running and the debugger should continue to wait 43706for @samp{W}, @samp{T}, etc. This reply is not permitted in non-stop mode. 43707 43708@item F @var{call-id},@var{parameter}@dots{} 43709@var{call-id} is the identifier which says which host system call should 43710be called. This is just the name of the function. Translation into the 43711correct system call is only applicable as it's defined in @value{GDBN}. 43712@xref{File-I/O Remote Protocol Extension}, for a list of implemented 43713system calls. 43714 43715@samp{@var{parameter}@dots{}} is a list of parameters as defined for 43716this very system call. 43717 43718The target replies with this packet when it expects @value{GDBN} to 43719call a host system call on behalf of the target. @value{GDBN} replies 43720with an appropriate @samp{F} packet and keeps up waiting for the next 43721reply packet from the target. The latest @samp{C}, @samp{c}, @samp{S} 43722or @samp{s} action is expected to be continued. @xref{File-I/O Remote 43723Protocol Extension}, for more details. 43724 43725@end table 43726 43727@node General Query Packets 43728@section General Query Packets 43729@cindex remote query requests 43730 43731Packets starting with @samp{q} are @dfn{general query packets}; 43732packets starting with @samp{Q} are @dfn{general set packets}. General 43733query and set packets are a semi-unified form for retrieving and 43734sending information to and from the stub. 43735 43736The initial letter of a query or set packet is followed by a name 43737indicating what sort of thing the packet applies to. For example, 43738@value{GDBN} may use a @samp{qSymbol} packet to exchange symbol 43739definitions with the stub. These packet names follow some 43740conventions: 43741 43742@itemize @bullet 43743@item 43744The name must not contain commas, colons or semicolons. 43745@item 43746Most @value{GDBN} query and set packets have a leading upper case 43747letter. 43748@item 43749The names of custom vendor packets should use a company prefix, in 43750lower case, followed by a period. For example, packets designed at 43751the Acme Corporation might begin with @samp{qacme.foo} (for querying 43752foos) or @samp{Qacme.bar} (for setting bars). 43753@end itemize 43754 43755The name of a query or set packet should be separated from any 43756parameters by a @samp{:}; the parameters themselves should be 43757separated by @samp{,} or @samp{;}. Stubs must be careful to match the 43758full packet name, and check for a separator or the end of the packet, 43759in case two packet names share a common prefix. New packets should not begin 43760with @samp{qC}, @samp{qP}, or @samp{qL}@footnote{The @samp{qP} and @samp{qL} 43761packets predate these conventions, and have arguments without any terminator 43762for the packet name; we suspect they are in widespread use in places that 43763are difficult to upgrade. The @samp{qC} packet has no arguments, but some 43764existing stubs (e.g.@: RedBoot) are known to not check for the end of the 43765packet.}. 43766 43767Like the descriptions of the other packets, each description here 43768has a template showing the packet's overall syntax, followed by an 43769explanation of the packet's meaning. We include spaces in some of the 43770templates for clarity; these are not part of the packet's syntax. No 43771@value{GDBN} packet uses spaces to separate its components. 43772 43773Here are the currently defined query and set packets: 43774 43775@table @samp 43776 43777@item QAgent:1 43778@itemx QAgent:0 43779Turn on or off the agent as a helper to perform some debugging operations 43780delegated from @value{GDBN} (@pxref{Control Agent}). 43781 43782@item QAllow:@var{op}:@var{val}@dots{} 43783@cindex @samp{QAllow} packet 43784Specify which operations @value{GDBN} expects to request of the 43785target, as a semicolon-separated list of operation name and value 43786pairs. Possible values for @var{op} include @samp{WriteReg}, 43787@samp{WriteMem}, @samp{InsertBreak}, @samp{InsertTrace}, 43788@samp{InsertFastTrace}, and @samp{Stop}. @var{val} is either 0, 43789indicating that @value{GDBN} will not request the operation, or 1, 43790indicating that it may. (The target can then use this to set up its 43791own internals optimally, for instance if the debugger never expects to 43792insert breakpoints, it may not need to install its own trap handler.) 43793 43794@item qC 43795@cindex current thread, remote request 43796@cindex @samp{qC} packet 43797Return the current thread ID. 43798 43799Reply: 43800@table @samp 43801@item QC @var{thread-id} 43802Where @var{thread-id} is a thread ID as documented in 43803@ref{thread-id syntax}. 43804@item @r{(anything else)} 43805Any other reply implies the old thread ID. 43806@end table 43807 43808@item qCRC:@var{addr},@var{length} 43809@cindex CRC of memory block, remote request 43810@cindex @samp{qCRC} packet 43811@anchor{qCRC packet} 43812Compute the CRC checksum of a block of memory using CRC-32 defined in 43813IEEE 802.3. The CRC is computed byte at a time, taking the most 43814significant bit of each byte first. The initial pattern code 43815@code{0xffffffff} is used to ensure leading zeros affect the CRC. 43816 43817@emph{Note:} This is the same CRC used in validating separate debug 43818files (@pxref{Separate Debug Files, , Debugging Information in Separate 43819Files}). However the algorithm is slightly different. When validating 43820separate debug files, the CRC is computed taking the @emph{least} 43821significant bit of each byte first, and the final result is inverted to 43822detect trailing zeros. 43823 43824Reply: 43825@table @samp 43826@item C @var{crc32} 43827The specified memory region's checksum is @var{crc32}. 43828@end table 43829 43830@item QDisableRandomization:@var{value} 43831@cindex disable address space randomization, remote request 43832@cindex @samp{QDisableRandomization} packet 43833Some target operating systems will randomize the virtual address space 43834of the inferior process as a security feature, but provide a feature 43835to disable such randomization, e.g.@: to allow for a more deterministic 43836debugging experience. On such systems, this packet with a @var{value} 43837of 1 directs the target to disable address space randomization for 43838processes subsequently started via @samp{vRun} packets, while a packet 43839with a @var{value} of 0 tells the target to enable address space 43840randomization. 43841 43842This packet is only available in extended mode (@pxref{extended mode}). 43843 43844Reply: 43845@table @samp 43846@item OK 43847The request succeeded. 43848@end table 43849 43850This packet is not probed by default; the remote stub must request it, 43851by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 43852This should only be done on targets that actually support disabling 43853address space randomization. 43854 43855@item QStartupWithShell:@var{value} 43856@cindex startup with shell, remote request 43857@cindex @samp{QStartupWithShell} packet 43858On UNIX-like targets, it is possible to start the inferior using a 43859shell program. This is the default behavior on both @value{GDBN} and 43860@command{gdbserver} (@pxref{set startup-with-shell}). This packet is 43861used to inform @command{gdbserver} whether it should start the 43862inferior using a shell or not. 43863 43864If @var{value} is @samp{0}, @command{gdbserver} will not use a shell 43865to start the inferior. If @var{value} is @samp{1}, 43866@command{gdbserver} will use a shell to start the inferior. All other 43867values are considered an error. 43868 43869This packet is only available in extended mode (@pxref{extended 43870mode}). 43871 43872Reply: 43873@table @samp 43874@item OK 43875The request succeeded. 43876@end table 43877 43878This packet is not probed by default; the remote stub must request it, 43879by supplying an appropriate @samp{qSupported} response 43880(@pxref{qSupported}). This should only be done on targets that 43881actually support starting the inferior using a shell. 43882 43883Use of this packet is controlled by the @code{set startup-with-shell} 43884command; @pxref{set startup-with-shell}. 43885 43886@item QEnvironmentHexEncoded:@var{hex-value} 43887@anchor{QEnvironmentHexEncoded} 43888@cindex set environment variable, remote request 43889@cindex @samp{QEnvironmentHexEncoded} packet 43890On UNIX-like targets, it is possible to set environment variables that 43891will be passed to the inferior during the startup process. This 43892packet is used to inform @command{gdbserver} of an environment 43893variable that has been defined by the user on @value{GDBN} (@pxref{set 43894environment}). 43895 43896The packet is composed by @var{hex-value}, an hex encoded 43897representation of the @var{name=value} format representing an 43898environment variable. The name of the environment variable is 43899represented by @var{name}, and the value to be assigned to the 43900environment variable is represented by @var{value}. If the variable 43901has no value (i.e., the value is @code{null}), then @var{value} will 43902not be present. 43903 43904This packet is only available in extended mode (@pxref{extended 43905mode}). 43906 43907Reply: 43908@table @samp 43909@item OK 43910The request succeeded. 43911@end table 43912 43913This packet is not probed by default; the remote stub must request it, 43914by supplying an appropriate @samp{qSupported} response 43915(@pxref{qSupported}). This should only be done on targets that 43916actually support passing environment variables to the starting 43917inferior. 43918 43919This packet is related to the @code{set environment} command; 43920@pxref{set environment}. 43921 43922@item QEnvironmentUnset:@var{hex-value} 43923@anchor{QEnvironmentUnset} 43924@cindex unset environment variable, remote request 43925@cindex @samp{QEnvironmentUnset} packet 43926On UNIX-like targets, it is possible to unset environment variables 43927before starting the inferior in the remote target. This packet is 43928used to inform @command{gdbserver} of an environment variable that has 43929been unset by the user on @value{GDBN} (@pxref{unset environment}). 43930 43931The packet is composed by @var{hex-value}, an hex encoded 43932representation of the name of the environment variable to be unset. 43933 43934This packet is only available in extended mode (@pxref{extended 43935mode}). 43936 43937Reply: 43938@table @samp 43939@item OK 43940The request succeeded. 43941@end table 43942 43943This packet is not probed by default; the remote stub must request it, 43944by supplying an appropriate @samp{qSupported} response 43945(@pxref{qSupported}). This should only be done on targets that 43946actually support passing environment variables to the starting 43947inferior. 43948 43949This packet is related to the @code{unset environment} command; 43950@pxref{unset environment}. 43951 43952@item QEnvironmentReset 43953@anchor{QEnvironmentReset} 43954@cindex reset environment, remote request 43955@cindex @samp{QEnvironmentReset} packet 43956On UNIX-like targets, this packet is used to reset the state of 43957environment variables in the remote target before starting the 43958inferior. In this context, reset means unsetting all environment 43959variables that were previously set by the user (i.e., were not 43960initially present in the environment). It is sent to 43961@command{gdbserver} before the @samp{QEnvironmentHexEncoded} 43962(@pxref{QEnvironmentHexEncoded}) and the @samp{QEnvironmentUnset} 43963(@pxref{QEnvironmentUnset}) packets. 43964 43965This packet is only available in extended mode (@pxref{extended 43966mode}). 43967 43968Reply: 43969@table @samp 43970@item OK 43971The request succeeded. 43972@end table 43973 43974This packet is not probed by default; the remote stub must request it, 43975by supplying an appropriate @samp{qSupported} response 43976(@pxref{qSupported}). This should only be done on targets that 43977actually support passing environment variables to the starting 43978inferior. 43979 43980@item QSetWorkingDir:@r{[}@var{directory}@r{]} 43981@anchor{QSetWorkingDir packet} 43982@cindex set working directory, remote request 43983@cindex @samp{QSetWorkingDir} packet 43984This packet is used to inform the remote server of the intended 43985current working directory for programs that are going to be executed. 43986 43987The packet is composed by @var{directory}, an hex encoded 43988representation of the directory that the remote inferior will use as 43989its current working directory. If @var{directory} is an empty string, 43990the remote server should reset the inferior's current working 43991directory to its original, empty value. 43992 43993This packet is only available in extended mode (@pxref{extended 43994mode}). 43995 43996Reply: 43997@table @samp 43998@item OK 43999The request succeeded. 44000@end table 44001 44002@item qfThreadInfo 44003@itemx qsThreadInfo 44004@cindex list active threads, remote request 44005@cindex @samp{qfThreadInfo} packet 44006@cindex @samp{qsThreadInfo} packet 44007Obtain a list of all active thread IDs from the target (OS). Since there 44008may be too many active threads to fit into one reply packet, this query 44009works iteratively: it may require more than one query/reply sequence to 44010obtain the entire list of threads. The first query of the sequence will 44011be the @samp{qfThreadInfo} query; subsequent queries in the 44012sequence will be the @samp{qsThreadInfo} query. 44013 44014NOTE: This packet replaces the @samp{qL} query (see below). 44015 44016Reply: 44017@table @samp 44018@item m @var{thread-id} 44019A single thread ID 44020@item m @var{thread-id},@var{thread-id}@dots{} 44021a comma-separated list of thread IDs 44022@item l 44023(lower case letter @samp{L}) denotes end of list. 44024@end table 44025 44026In response to each query, the target will reply with a list of one or 44027more thread IDs, separated by commas. 44028@value{GDBN} will respond to each reply with a request for more thread 44029ids (using the @samp{qs} form of the query), until the target responds 44030with @samp{l} (lower-case ell, for @dfn{last}). 44031Refer to @ref{thread-id syntax}, for the format of the @var{thread-id} 44032fields. 44033 44034@emph{Note: @value{GDBN} will send the @code{qfThreadInfo} query during the 44035initial connection with the remote target, and the very first thread ID 44036mentioned in the reply will be stopped by @value{GDBN} in a subsequent 44037message. Therefore, the stub should ensure that the first thread ID in 44038the @code{qfThreadInfo} reply is suitable for being stopped by @value{GDBN}.} 44039 44040@item qGetTLSAddr:@var{thread-id},@var{offset},@var{lm} 44041@cindex get thread-local storage address, remote request 44042@cindex @samp{qGetTLSAddr} packet 44043Fetch the address associated with thread local storage specified 44044by @var{thread-id}, @var{offset}, and @var{lm}. 44045 44046@var{thread-id} is the thread ID associated with the 44047thread for which to fetch the TLS address. @xref{thread-id syntax}. 44048 44049@var{offset} is the (big endian, hex encoded) offset associated with the 44050thread local variable. (This offset is obtained from the debug 44051information associated with the variable.) 44052 44053@var{lm} is the (big endian, hex encoded) OS/ABI-specific encoding of the 44054load module associated with the thread local storage. For example, 44055a @sc{gnu}/Linux system will pass the link map address of the shared 44056object associated with the thread local storage under consideration. 44057Other operating environments may choose to represent the load module 44058differently, so the precise meaning of this parameter will vary. 44059 44060Reply: 44061@table @samp 44062@item @var{XX}@dots{} 44063Hex encoded (big endian) bytes representing the address of the thread 44064local storage requested. 44065@end table 44066 44067@item qGetTIBAddr:@var{thread-id} 44068@cindex get thread information block address 44069@cindex @samp{qGetTIBAddr} packet 44070Fetch address of the Windows OS specific Thread Information Block. 44071 44072@var{thread-id} is the thread ID associated with the thread. 44073 44074Reply: 44075@table @samp 44076@item @var{XX}@dots{} 44077Hex encoded (big endian) bytes representing the linear address of the 44078thread information block. 44079@end table 44080 44081@item qL @var{startflag} @var{threadcount} @var{nextthread} 44082Obtain thread information from RTOS. Where: @var{startflag} (one hex 44083digit) is one to indicate the first query and zero to indicate a 44084subsequent query; @var{threadcount} (two hex digits) is the maximum 44085number of threads the response packet can contain; and @var{nextthread} 44086(eight hex digits), for subsequent queries (@var{startflag} is zero), is 44087returned in the response as @var{argthread}. 44088 44089Don't use this packet; use the @samp{qfThreadInfo} query instead (see above). 44090 44091Reply: 44092@table @samp 44093@item qM @var{count} @var{done} @var{argthread} @var{thread}@dots{} 44094Where: @var{count} (two hex digits) is the number of threads being 44095returned; @var{done} (one hex digit) is zero to indicate more threads 44096and one indicates no further threads; @var{argthreadid} (eight hex 44097digits) is @var{nextthread} from the request packet; @var{thread}@dots{} 44098is a sequence of thread IDs, @var{threadid} (eight hex 44099digits), from the target. See @code{remote.c:parse_threadlist_response()}. 44100@end table 44101 44102@item qMemTags:@var{start address},@var{length}:@var{type} 44103@anchor{qMemTags} 44104@cindex fetch memory tags 44105@cindex @samp{qMemTags} packet 44106Fetch memory tags of type @var{type} from the address range 44107@w{@r{[}@var{start address}, @var{start address} + @var{length}@r{)}}. The 44108target is responsible for calculating how many tags will be returned, as this 44109is architecture-specific. 44110 44111@var{start address} is the starting address of the memory range. 44112 44113@var{length} is the length, in bytes, of the memory range. 44114 44115@var{type} is the type of tag the request wants to fetch. The type is a signed 44116integer. 44117 44118@value{GDBN} will only send this packet if the stub has advertised 44119support for memory tagging via @samp{qSupported}. 44120 44121Reply: 44122@table @samp 44123@item @var{mxx}@dots{} 44124Hex encoded sequence of uninterpreted bytes, @var{xx}@dots{}, representing the 44125tags found in the requested memory range. 44126 44127@end table 44128 44129@cindex check if a given address is in a memory tagged region 44130@cindex @samp{qIsAddressTagged} packet 44131@item qIsAddressTagged:@var{address} 44132@anchor {qIsAddressTagged} 44133Check if address @var{address} is in a memory tagged region; if it is, it's 44134said to be @dfn{tagged}. The target is responsible for checking it, as this 44135is architecture-specific. 44136 44137@var{address} is the address to be checked. 44138 44139Reply: 44140@table @samp 44141Replies to this packet should all be in two hex digit format, as follows: 44142 44143@item @samp{01} 44144Address @var{address} is tagged. 44145 44146@item @samp{00} 44147Address @var{address} is not tagged. 44148@end table 44149 44150@item QMemTags:@var{start address},@var{length}:@var{type}:@var{tag bytes} 44151@anchor{QMemTags} 44152@cindex store memory tags 44153@cindex @samp{QMemTags} packet 44154Store memory tags of type @var{type} to the address range 44155@w{@r{[}@var{start address}, @var{start address} + @var{length}@r{)}}. The 44156target is responsible for interpreting the type, the tag bytes and modifying 44157the memory tag granules accordingly, given this is architecture-specific. 44158 44159The interpretation of how many tags (@var{nt}) should be written to how many 44160memory tag granules (@var{ng}) is also architecture-specific. The behavior is 44161implementation-specific, but the following is suggested. 44162 44163If the number of memory tags, @var{nt}, is greater than or equal to the 44164number of memory tag granules, @var{ng}, only @var{ng} tags will be 44165stored. 44166 44167If @var{nt} is less than @var{ng}, the behavior is that of a fill operation, 44168and the tag bytes will be used as a pattern that will get repeated until 44169@var{ng} tags are stored. 44170 44171@var{start address} is the starting address of the memory range. The address 44172does not have any restriction on alignment or size. 44173 44174@var{length} is the length, in bytes, of the memory range. 44175 44176@var{type} is the type of tag the request wants to fetch. The type is a signed 44177integer. 44178 44179@var{tag bytes} is a sequence of hex encoded uninterpreted bytes which will be 44180interpreted by the target. Each pair of hex digits is interpreted as a 44181single byte. 44182 44183@value{GDBN} will only send this packet if the stub has advertised 44184support for memory tagging via @samp{qSupported}. 44185 44186Reply: 44187@table @samp 44188@item OK 44189The request was successful and the memory tag granules were modified 44190accordingly. 44191@end table 44192 44193@item qOffsets 44194@cindex section offsets, remote request 44195@cindex @samp{qOffsets} packet 44196Get section offsets that the target used when relocating the downloaded 44197image. 44198 44199Reply: 44200@table @samp 44201@item Text=@var{xxx};Data=@var{yyy}@r{[};Bss=@var{zzz}@r{]} 44202Relocate the @code{Text} section by @var{xxx} from its original address. 44203Relocate the @code{Data} section by @var{yyy} from its original address. 44204If the object file format provides segment information (e.g.@: @sc{elf} 44205@samp{PT_LOAD} program headers), @value{GDBN} will relocate entire 44206segments by the supplied offsets. 44207 44208@emph{Note: while a @code{Bss} offset may be included in the response, 44209@value{GDBN} ignores this and instead applies the @code{Data} offset 44210to the @code{Bss} section.} 44211 44212@item TextSeg=@var{xxx}@r{[};DataSeg=@var{yyy}@r{]} 44213Relocate the first segment of the object file, which conventionally 44214contains program code, to a starting address of @var{xxx}. If 44215@samp{DataSeg} is specified, relocate the second segment, which 44216conventionally contains modifiable data, to a starting address of 44217@var{yyy}. @value{GDBN} will report an error if the object file 44218does not contain segment information, or does not contain at least 44219as many segments as mentioned in the reply. Extra segments are 44220kept at fixed offsets relative to the last relocated segment. 44221@end table 44222 44223@item qP @var{mode} @var{thread-id} 44224@cindex thread information, remote request 44225@cindex @samp{qP} packet 44226Returns information on @var{thread-id}. Where: @var{mode} is a hex 44227encoded 32 bit mode; @var{thread-id} is a thread ID 44228(@pxref{thread-id syntax}). 44229 44230Don't use this packet; use the @samp{qThreadExtraInfo} query instead 44231(see below). 44232 44233Reply: see @code{remote.c:remote_unpack_thread_info_response()}. 44234 44235@item QNonStop:1 44236@itemx QNonStop:0 44237@cindex non-stop mode, remote request 44238@cindex @samp{QNonStop} packet 44239@anchor{QNonStop} 44240Enter non-stop (@samp{QNonStop:1}) or all-stop (@samp{QNonStop:0}) mode. 44241@xref{Remote Non-Stop}, for more information. 44242 44243Reply: 44244@table @samp 44245@item OK 44246The request succeeded. 44247@end table 44248 44249This packet is not probed by default; the remote stub must request it, 44250by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 44251Use of this packet is controlled by the @code{set non-stop} command; 44252@pxref{Non-Stop Mode}. 44253 44254@item QCatchSyscalls:1 @r{[};@var{sysno}@r{]}@dots{} 44255@itemx QCatchSyscalls:0 44256@cindex catch syscalls from inferior, remote request 44257@cindex @samp{QCatchSyscalls} packet 44258@anchor{QCatchSyscalls} 44259Enable (@samp{QCatchSyscalls:1}) or disable (@samp{QCatchSyscalls:0}) 44260catching syscalls from the inferior process. 44261 44262For @samp{QCatchSyscalls:1}, each listed syscall @var{sysno} (encoded 44263in hex) should be reported to @value{GDBN}. If no syscall @var{sysno} 44264is listed, every system call should be reported. 44265 44266Note that if a syscall not in the list is reported, @value{GDBN} will 44267still filter the event according to its own list from all corresponding 44268@code{catch syscall} commands. However, it is more efficient to only 44269report the requested syscalls. 44270 44271Multiple @samp{QCatchSyscalls:1} packets do not combine; any earlier 44272@samp{QCatchSyscalls:1} list is completely replaced by the new list. 44273 44274If the inferior process execs, the state of @samp{QCatchSyscalls} is 44275kept for the new process too. On targets where exec may affect syscall 44276numbers, for example with exec between 32 and 64-bit processes, the 44277client should send a new packet with the new syscall list. 44278 44279Reply: 44280@table @samp 44281@item OK 44282The request succeeded. 44283@end table 44284 44285Use of this packet is controlled by the @code{set remote catch-syscalls} 44286command (@pxref{Remote Configuration, set remote catch-syscalls}). 44287This packet is not probed by default; the remote stub must request it, 44288by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 44289 44290@item QPassSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{} 44291@cindex pass signals to inferior, remote request 44292@cindex @samp{QPassSignals} packet 44293@anchor{QPassSignals} 44294Each listed @var{signal} should be passed directly to the inferior process. 44295Signals are numbered identically to continue packets and stop replies 44296(@pxref{Stop Reply Packets}). Each @var{signal} list item should be 44297strictly greater than the previous item. These signals do not need to stop 44298the inferior, or be reported to @value{GDBN}. All other signals should be 44299reported to @value{GDBN}. Multiple @samp{QPassSignals} packets do not 44300combine; any earlier @samp{QPassSignals} list is completely replaced by the 44301new list. This packet improves performance when using @samp{handle 44302@var{signal} nostop noprint pass}. 44303 44304Reply: 44305@table @samp 44306@item OK 44307The request succeeded. 44308@end table 44309 44310Use of this packet is controlled by the @code{set remote pass-signals} 44311command (@pxref{Remote Configuration, set remote pass-signals}). 44312This packet is not probed by default; the remote stub must request it, 44313by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 44314 44315@item QProgramSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{} 44316@cindex signals the inferior may see, remote request 44317@cindex @samp{QProgramSignals} packet 44318@anchor{QProgramSignals} 44319Each listed @var{signal} may be delivered to the inferior process. 44320Others should be silently discarded. 44321 44322In some cases, the remote stub may need to decide whether to deliver a 44323signal to the program or not without @value{GDBN} involvement. One 44324example of that is while detaching --- the program's threads may have 44325stopped for signals that haven't yet had a chance of being reported to 44326@value{GDBN}, and so the remote stub can use the signal list specified 44327by this packet to know whether to deliver or ignore those pending 44328signals. 44329 44330This does not influence whether to deliver a signal as requested by a 44331resumption packet (@pxref{vCont packet}). 44332 44333Signals are numbered identically to continue packets and stop replies 44334(@pxref{Stop Reply Packets}). Each @var{signal} list item should be 44335strictly greater than the previous item. Multiple 44336@samp{QProgramSignals} packets do not combine; any earlier 44337@samp{QProgramSignals} list is completely replaced by the new list. 44338 44339Reply: 44340@table @samp 44341@item OK 44342The request succeeded. 44343@end table 44344 44345Use of this packet is controlled by the @code{set remote program-signals} 44346command (@pxref{Remote Configuration, set remote program-signals}). 44347This packet is not probed by default; the remote stub must request it, 44348by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 44349 44350@anchor{QThreadEvents} 44351@item QThreadEvents:1 44352@itemx QThreadEvents:0 44353@cindex thread create/exit events, remote request 44354@cindex @samp{QThreadEvents} packet 44355 44356Enable (@samp{QThreadEvents:1}) or disable (@samp{QThreadEvents:0}) 44357reporting of thread create and exit events. @xref{thread create 44358event}, for the reply specifications. For example, this is used in 44359non-stop mode when @value{GDBN} stops a set of threads and 44360synchronously waits for the their corresponding stop replies. Without 44361exit events, if one of the threads exits, @value{GDBN} would hang 44362forever not knowing that it should no longer expect a stop for that 44363same thread. @value{GDBN} does not enable this feature unless the 44364stub reports that it supports it by including @samp{QThreadEvents+} in 44365its @samp{qSupported} reply. 44366 44367This packet always enables/disables event reporting for all threads of 44368all processes under control of the remote stub. For per-thread 44369control of optional event reporting, see the @ref{QThreadOptions} 44370packet. 44371 44372Reply: 44373@table @samp 44374@item OK 44375The request succeeded. 44376@end table 44377 44378Use of this packet is controlled by the @code{set remote thread-events} 44379command (@pxref{Remote Configuration, set remote thread-events}). 44380 44381@anchor{QThreadOptions} 44382@item QThreadOptions@r{[};@var{options}@r{[}:@var{thread-id}@r{]]}@dots{} 44383@cindex thread options, remote request 44384@cindex @samp{QThreadOptions} packet 44385 44386For each inferior thread, the last @var{options} in the list with a 44387matching @var{thread-id} are applied. Any options previously set on a 44388thread are discarded and replaced by the new options specified. 44389Threads that do not match any @var{thread-id} retain their 44390previously-set options. Thread IDs are specified using the syntax 44391described in @ref{thread-id syntax}. If multiprocess extensions 44392(@pxref{multiprocess extensions}) are supported, options can be 44393specified to apply to all threads of a process by using the 44394@samp{p@var{pid}.-1} form of @var{thread-id}. Options with no 44395@var{thread-id} apply to all threads. Specifying no options value is 44396an error. Zero is a valid value. 44397 44398@var{options} is an hexadecimal integer specifying the enabled thread 44399options, and is the bitwise @code{OR} of the following values. All 44400values are given in hexadecimal representation. 44401 44402@table @code 44403@item GDB_THREAD_OPTION_CLONE (0x1) 44404Report thread clone events (@pxref{thread clone event}). This is only 44405meaningful for targets that support clone events (e.g., GNU/Linux 44406systems). 44407 44408@item GDB_THREAD_OPTION_EXIT (0x2) 44409Report thread exit events (@pxref{thread exit event}). 44410@end table 44411 44412@noindent 44413 44414For example, @value{GDBN} enables the @code{GDB_THREAD_OPTION_EXIT} 44415and @code{GDB_THREAD_OPTION_CLONE} options when single-stepping a 44416thread past a breakpoint, for the following reasons: 44417 44418@itemize @bullet 44419@item 44420If the single-stepped thread exits (e.g., it executes a thread exit 44421system call), enabling @code{GDB_THREAD_OPTION_EXIT} prevents 44422@value{GDBN} from waiting forever, not knowing that it should no 44423longer expect a stop for that same thread, and blocking other threads 44424from progressing. 44425 44426@item 44427If the single-stepped thread spawns a new clone child (i.e., it 44428executes a clone system call), enabling @code{GDB_THREAD_OPTION_CLONE} 44429halts the cloned thread before it executes any instructions, and thus 44430prevents the following problematic situations: 44431 44432@itemize @minus 44433@item 44434If the breakpoint is stepped-over in-line, the spawned thread would 44435incorrectly run free while the breakpoint being stepped over is not 44436inserted, and thus the cloned thread may potentially run past the 44437breakpoint without stopping for it; 44438 44439@item 44440If displaced (out-of-line) stepping is used, the cloned thread starts 44441running at the out-of-line PC, leading to undefined behavior, usually 44442crashing or corrupting data. 44443@end itemize 44444 44445@end itemize 44446 44447New threads start with thread options cleared. 44448 44449@value{GDBN} does not enable this feature unless the stub reports that 44450it supports it by including 44451@samp{QThreadOptions=@var{supported_options}} in its @samp{qSupported} 44452reply. 44453 44454Reply: 44455@table @samp 44456@item OK 44457The request succeeded. 44458@end table 44459 44460Use of this packet is controlled by the @code{set remote thread-options} 44461command (@pxref{Remote Configuration, set remote thread-options}). 44462 44463@item qRcmd,@var{command} 44464@cindex execute remote command, remote request 44465@cindex @samp{qRcmd} packet 44466@var{command} (hex encoded) is passed to the local interpreter for 44467execution. Invalid commands should be reported using the output 44468string. Before the final result packet, the target may also respond 44469with a number of intermediate @samp{O@var{output}} console output 44470packets. @emph{Implementors should note that providing access to a 44471stubs's interpreter may have security implications}. 44472 44473Reply: 44474@table @samp 44475@item OK 44476A command response with no output. 44477@item @var{OUTPUT} 44478A command response with the hex encoded output string @var{OUTPUT}. 44479@end table 44480 44481Unlike most packets, this packet does not support 44482@samp{E.@var{errtext}}-style textual error replies (@pxref{textual 44483error reply}). 44484 44485(Note that the @code{qRcmd} packet's name is separated from the 44486command by a @samp{,}, not a @samp{:}, contrary to the naming 44487conventions above. Please don't use this packet as a model for new 44488packets.) 44489 44490@item qSearch:memory:@var{address};@var{length};@var{search-pattern} 44491@cindex searching memory, in remote debugging 44492@ifnotinfo 44493@cindex @samp{qSearch:memory} packet 44494@end ifnotinfo 44495@cindex @samp{qSearch memory} packet 44496@anchor{qSearch memory} 44497Search @var{length} bytes at @var{address} for @var{search-pattern}. 44498Both @var{address} and @var{length} are encoded in hex; 44499@var{search-pattern} is a sequence of bytes, also hex encoded. 44500 44501Reply: 44502@table @samp 44503@item 0 44504The pattern was not found. 44505@item 1,address 44506The pattern was found at @var{address}. 44507@end table 44508 44509@item QStartNoAckMode 44510@cindex @samp{QStartNoAckMode} packet 44511@anchor{QStartNoAckMode} 44512Request that the remote stub disable the normal @samp{+}/@samp{-} 44513protocol acknowledgments (@pxref{Packet Acknowledgment}). 44514 44515Reply: 44516@table @samp 44517@item OK 44518The stub has switched to no-acknowledgment mode. 44519@value{GDBN} acknowledges this response, 44520but neither the stub nor @value{GDBN} shall send or expect further 44521@samp{+}/@samp{-} acknowledgments in the current connection. 44522@end table 44523 44524@item qSupported @r{[}:@var{gdbfeature} @r{[};@var{gdbfeature}@r{]}@dots{} @r{]} 44525@cindex supported packets, remote query 44526@cindex features of the remote protocol 44527@cindex @samp{qSupported} packet 44528@anchor{qSupported} 44529Tell the remote stub about features supported by @value{GDBN}, and 44530query the stub for features it supports. This packet allows 44531@value{GDBN} and the remote stub to take advantage of each others' 44532features. @samp{qSupported} also consolidates multiple feature probes 44533at startup, to improve @value{GDBN} performance---a single larger 44534packet performs better than multiple smaller probe packets on 44535high-latency links. Some features may enable behavior which must not 44536be on by default, e.g.@: because it would confuse older clients or 44537stubs. Other features may describe packets which could be 44538automatically probed for, but are not. These features must be 44539reported before @value{GDBN} will use them. This ``default 44540unsupported'' behavior is not appropriate for all packets, but it 44541helps to keep the initial connection time under control with new 44542versions of @value{GDBN} which support increasing numbers of packets. 44543 44544Reply: 44545@table @samp 44546@item @var{stubfeature} @r{[};@var{stubfeature}@r{]}@dots{} 44547The stub supports or does not support each returned @var{stubfeature}, 44548depending on the form of each @var{stubfeature} (see below for the 44549possible forms). 44550@end table 44551 44552The allowed forms for each feature (either a @var{gdbfeature} in the 44553@samp{qSupported} packet, or a @var{stubfeature} in the response) 44554are: 44555 44556@table @samp 44557@item @var{name}=@var{value} 44558The remote protocol feature @var{name} is supported, and associated 44559with the specified @var{value}. The format of @var{value} depends 44560on the feature, but it must not include a semicolon. 44561@item @var{name}+ 44562The remote protocol feature @var{name} is supported, and does not 44563need an associated value. 44564@item @var{name}- 44565The remote protocol feature @var{name} is not supported. 44566@item @var{name}? 44567The remote protocol feature @var{name} may be supported, and 44568@value{GDBN} should auto-detect support in some other way when it is 44569needed. This form will not be used for @var{gdbfeature} notifications, 44570but may be used for @var{stubfeature} responses. 44571@end table 44572 44573Whenever the stub receives a @samp{qSupported} request, the 44574supplied set of @value{GDBN} features should override any previous 44575request. This allows @value{GDBN} to put the stub in a known 44576state, even if the stub had previously been communicating with 44577a different version of @value{GDBN}. 44578 44579The following values of @var{gdbfeature} (for the packet sent by @value{GDBN}) 44580are defined: 44581 44582@table @samp 44583@item multiprocess 44584This feature indicates whether @value{GDBN} supports multiprocess 44585extensions to the remote protocol. @value{GDBN} does not use such 44586extensions unless the stub also reports that it supports them by 44587including @samp{multiprocess+} in its @samp{qSupported} reply. 44588@xref{multiprocess extensions}, for details. 44589 44590@item xmlRegisters 44591This feature indicates that @value{GDBN} supports the XML target 44592description. If the stub sees @samp{xmlRegisters=} with target 44593specific strings separated by a comma, it will report register 44594description. 44595 44596@item qRelocInsn 44597This feature indicates whether @value{GDBN} supports the 44598@samp{qRelocInsn} packet (@pxref{Tracepoint Packets,,Relocate 44599instruction reply packet}). 44600 44601@item swbreak 44602This feature indicates whether @value{GDBN} supports the swbreak stop 44603reason in stop replies. @xref{swbreak stop reason}, for details. 44604 44605@item hwbreak 44606This feature indicates whether @value{GDBN} supports the hwbreak stop 44607reason in stop replies. @xref{swbreak stop reason}, for details. 44608 44609@item fork-events 44610This feature indicates whether @value{GDBN} supports fork event 44611extensions to the remote protocol. @value{GDBN} does not use such 44612extensions unless the stub also reports that it supports them by 44613including @samp{fork-events+} in its @samp{qSupported} reply. 44614 44615@item vfork-events 44616This feature indicates whether @value{GDBN} supports vfork event 44617extensions to the remote protocol. @value{GDBN} does not use such 44618extensions unless the stub also reports that it supports them by 44619including @samp{vfork-events+} in its @samp{qSupported} reply. 44620 44621@item exec-events 44622This feature indicates whether @value{GDBN} supports exec event 44623extensions to the remote protocol. @value{GDBN} does not use such 44624extensions unless the stub also reports that it supports them by 44625including @samp{exec-events+} in its @samp{qSupported} reply. 44626 44627@item vContSupported 44628This feature indicates whether @value{GDBN} wants to know the 44629supported actions in the reply to @samp{vCont?} packet. 44630@end table 44631 44632Stubs should ignore any unknown values for 44633@var{gdbfeature}. Any @value{GDBN} which sends a @samp{qSupported} 44634packet supports receiving packets of unlimited length (earlier 44635versions of @value{GDBN} may reject overly long responses). Additional values 44636for @var{gdbfeature} may be defined in the future to let the stub take 44637advantage of new features in @value{GDBN}, e.g.@: incompatible 44638improvements in the remote protocol---the @samp{multiprocess} feature is 44639an example of such a feature. The stub's reply should be independent 44640of the @var{gdbfeature} entries sent by @value{GDBN}; first @value{GDBN} 44641describes all the features it supports, and then the stub replies with 44642all the features it supports. 44643 44644Similarly, @value{GDBN} will silently ignore unrecognized stub feature 44645responses, as long as each response uses one of the standard forms. 44646 44647Some features are flags. A stub which supports a flag feature 44648should respond with a @samp{+} form response. Other features 44649require values, and the stub should respond with an @samp{=} 44650form response. 44651 44652Each feature has a default value, which @value{GDBN} will use if 44653@samp{qSupported} is not available or if the feature is not mentioned 44654in the @samp{qSupported} response. The default values are fixed; a 44655stub is free to omit any feature responses that match the defaults. 44656 44657Not all features can be probed, but for those which can, the probing 44658mechanism is useful: in some cases, a stub's internal 44659architecture may not allow the protocol layer to know some information 44660about the underlying target in advance. This is especially common in 44661stubs which may be configured for multiple targets. 44662 44663These are the currently defined stub features and their properties: 44664 44665@multitable @columnfractions 0.35 0.2 0.12 0.2 44666@c NOTE: The first row should be @headitem, but we do not yet require 44667@c a new enough version of Texinfo (4.7) to use @headitem. 44668@item Feature Name 44669@tab Value Required 44670@tab Default 44671@tab Probe Allowed 44672 44673@item @samp{PacketSize} 44674@tab Yes 44675@tab @samp{-} 44676@tab No 44677 44678@item @samp{qXfer:auxv:read} 44679@tab No 44680@tab @samp{-} 44681@tab Yes 44682 44683@item @samp{qXfer:btrace:read} 44684@tab No 44685@tab @samp{-} 44686@tab Yes 44687 44688@item @samp{qXfer:btrace-conf:read} 44689@tab No 44690@tab @samp{-} 44691@tab Yes 44692 44693@item @samp{qXfer:exec-file:read} 44694@tab No 44695@tab @samp{-} 44696@tab Yes 44697 44698@item @samp{qXfer:features:read} 44699@tab No 44700@tab @samp{-} 44701@tab Yes 44702 44703@item @samp{qXfer:libraries:read} 44704@tab No 44705@tab @samp{-} 44706@tab Yes 44707 44708@item @samp{qXfer:libraries-svr4:read} 44709@tab No 44710@tab @samp{-} 44711@tab Yes 44712 44713@item @samp{augmented-libraries-svr4-read} 44714@tab No 44715@tab @samp{-} 44716@tab No 44717 44718@item @samp{qXfer:memory-map:read} 44719@tab No 44720@tab @samp{-} 44721@tab Yes 44722 44723@item @samp{qXfer:sdata:read} 44724@tab No 44725@tab @samp{-} 44726@tab Yes 44727 44728@item @samp{qXfer:siginfo:read} 44729@tab No 44730@tab @samp{-} 44731@tab Yes 44732 44733@item @samp{qXfer:siginfo:write} 44734@tab No 44735@tab @samp{-} 44736@tab Yes 44737 44738@item @samp{qXfer:threads:read} 44739@tab No 44740@tab @samp{-} 44741@tab Yes 44742 44743@item @samp{qXfer:traceframe-info:read} 44744@tab No 44745@tab @samp{-} 44746@tab Yes 44747 44748@item @samp{qXfer:uib:read} 44749@tab No 44750@tab @samp{-} 44751@tab Yes 44752 44753@item @samp{qXfer:fdpic:read} 44754@tab No 44755@tab @samp{-} 44756@tab Yes 44757 44758@item @samp{Qbtrace:off} 44759@tab Yes 44760@tab @samp{-} 44761@tab Yes 44762 44763@item @samp{Qbtrace:bts} 44764@tab Yes 44765@tab @samp{-} 44766@tab Yes 44767 44768@item @samp{Qbtrace:pt} 44769@tab Yes 44770@tab @samp{-} 44771@tab Yes 44772 44773@item @samp{Qbtrace-conf:bts:size} 44774@tab Yes 44775@tab @samp{-} 44776@tab Yes 44777 44778@item @samp{Qbtrace-conf:pt:size} 44779@tab Yes 44780@tab @samp{-} 44781@tab Yes 44782 44783@item @samp{QNonStop} 44784@tab No 44785@tab @samp{-} 44786@tab Yes 44787 44788@item @samp{QCatchSyscalls} 44789@tab No 44790@tab @samp{-} 44791@tab Yes 44792 44793@item @samp{QPassSignals} 44794@tab No 44795@tab @samp{-} 44796@tab Yes 44797 44798@item @samp{QStartNoAckMode} 44799@tab No 44800@tab @samp{-} 44801@tab Yes 44802 44803@item @samp{multiprocess} 44804@tab No 44805@tab @samp{-} 44806@tab No 44807 44808@item @samp{ConditionalBreakpoints} 44809@tab No 44810@tab @samp{-} 44811@tab No 44812 44813@item @samp{ConditionalTracepoints} 44814@tab No 44815@tab @samp{-} 44816@tab No 44817 44818@item @samp{ReverseContinue} 44819@tab No 44820@tab @samp{-} 44821@tab No 44822 44823@item @samp{ReverseStep} 44824@tab No 44825@tab @samp{-} 44826@tab No 44827 44828@item @samp{TracepointSource} 44829@tab No 44830@tab @samp{-} 44831@tab No 44832 44833@item @samp{QAgent} 44834@tab No 44835@tab @samp{-} 44836@tab No 44837 44838@item @samp{QAllow} 44839@tab No 44840@tab @samp{-} 44841@tab No 44842 44843@item @samp{QDisableRandomization} 44844@tab No 44845@tab @samp{-} 44846@tab No 44847 44848@item @samp{EnableDisableTracepoints} 44849@tab No 44850@tab @samp{-} 44851@tab No 44852 44853@item @samp{QTBuffer:size} 44854@tab No 44855@tab @samp{-} 44856@tab No 44857 44858@item @samp{tracenz} 44859@tab No 44860@tab @samp{-} 44861@tab No 44862 44863@item @samp{BreakpointCommands} 44864@tab No 44865@tab @samp{-} 44866@tab No 44867 44868@item @samp{swbreak} 44869@tab No 44870@tab @samp{-} 44871@tab No 44872 44873@item @samp{hwbreak} 44874@tab No 44875@tab @samp{-} 44876@tab No 44877 44878@item @samp{fork-events} 44879@tab No 44880@tab @samp{-} 44881@tab No 44882 44883@item @samp{vfork-events} 44884@tab No 44885@tab @samp{-} 44886@tab No 44887 44888@item @samp{exec-events} 44889@tab No 44890@tab @samp{-} 44891@tab No 44892 44893@item @samp{QThreadEvents} 44894@tab No 44895@tab @samp{-} 44896@tab No 44897 44898@item @samp{QThreadOptions} 44899@tab Yes 44900@tab @samp{-} 44901@tab No 44902 44903@item @samp{no-resumed} 44904@tab No 44905@tab @samp{-} 44906@tab No 44907 44908@item @samp{memory-tagging} 44909@tab No 44910@tab @samp{-} 44911@tab No 44912 44913@end multitable 44914 44915These are the currently defined stub features, in more detail: 44916 44917@table @samp 44918@cindex packet size, remote protocol 44919@item PacketSize=@var{bytes} 44920The remote stub can accept packets up to at least @var{bytes} in 44921length. @value{GDBN} will send packets up to this size for bulk 44922transfers, and will never send larger packets. This is a limit on the 44923data characters in the packet, not including the frame and checksum. 44924There is no trailing NUL byte in a remote protocol packet; if the stub 44925stores packets in a NUL-terminated format, it should allow an extra 44926byte in its buffer for the NUL. If this stub feature is not supported, 44927@value{GDBN} guesses based on the size of the @samp{g} packet response. 44928 44929@item qXfer:auxv:read 44930The remote stub understands the @samp{qXfer:auxv:read} packet 44931(@pxref{qXfer auxiliary vector read}). 44932 44933@item qXfer:btrace:read 44934The remote stub understands the @samp{qXfer:btrace:read} 44935packet (@pxref{qXfer btrace read}). 44936 44937@item qXfer:btrace-conf:read 44938The remote stub understands the @samp{qXfer:btrace-conf:read} 44939packet (@pxref{qXfer btrace-conf read}). 44940 44941@item qXfer:exec-file:read 44942The remote stub understands the @samp{qXfer:exec-file:read} packet 44943(@pxref{qXfer executable filename read}). 44944 44945@item qXfer:features:read 44946The remote stub understands the @samp{qXfer:features:read} packet 44947(@pxref{qXfer target description read}). 44948 44949@item qXfer:libraries:read 44950The remote stub understands the @samp{qXfer:libraries:read} packet 44951(@pxref{qXfer library list read}). 44952 44953@item qXfer:libraries-svr4:read 44954The remote stub understands the @samp{qXfer:libraries-svr4:read} packet 44955(@pxref{qXfer svr4 library list read}). 44956 44957@item augmented-libraries-svr4-read 44958The remote stub understands the augmented form of the 44959@samp{qXfer:libraries-svr4:read} packet 44960(@pxref{qXfer svr4 library list read}). 44961 44962@item qXfer:memory-map:read 44963The remote stub understands the @samp{qXfer:memory-map:read} packet 44964(@pxref{qXfer memory map read}). 44965 44966@item qXfer:sdata:read 44967The remote stub understands the @samp{qXfer:sdata:read} packet 44968(@pxref{qXfer sdata read}). 44969 44970@item qXfer:siginfo:read 44971The remote stub understands the @samp{qXfer:siginfo:read} packet 44972(@pxref{qXfer siginfo read}). 44973 44974@item qXfer:siginfo:write 44975The remote stub understands the @samp{qXfer:siginfo:write} packet 44976(@pxref{qXfer siginfo write}). 44977 44978@item qXfer:threads:read 44979The remote stub understands the @samp{qXfer:threads:read} packet 44980(@pxref{qXfer threads read}). 44981 44982@item qXfer:traceframe-info:read 44983The remote stub understands the @samp{qXfer:traceframe-info:read} 44984packet (@pxref{qXfer traceframe info read}). 44985 44986@item qXfer:uib:read 44987The remote stub understands the @samp{qXfer:uib:read} 44988packet (@pxref{qXfer unwind info block}). 44989 44990@item qXfer:fdpic:read 44991The remote stub understands the @samp{qXfer:fdpic:read} 44992packet (@pxref{qXfer fdpic loadmap read}). 44993 44994@item QNonStop 44995The remote stub understands the @samp{QNonStop} packet 44996(@pxref{QNonStop}). 44997 44998@item QCatchSyscalls 44999The remote stub understands the @samp{QCatchSyscalls} packet 45000(@pxref{QCatchSyscalls}). 45001 45002@item QPassSignals 45003The remote stub understands the @samp{QPassSignals} packet 45004(@pxref{QPassSignals}). 45005 45006@item QStartNoAckMode 45007The remote stub understands the @samp{QStartNoAckMode} packet and 45008prefers to operate in no-acknowledgment mode. @xref{Packet Acknowledgment}. 45009 45010@item multiprocess 45011@anchor{multiprocess extensions} 45012@cindex multiprocess extensions, in remote protocol 45013The remote stub understands the multiprocess extensions to the remote 45014protocol syntax. The multiprocess extensions affect the syntax of 45015thread IDs in both packets and replies (@pxref{thread-id syntax}), and 45016add process IDs to the @samp{D} packet and @samp{W} and @samp{X} 45017replies. Note that reporting this feature indicates support for the 45018syntactic extensions only, not that the stub necessarily supports 45019debugging of more than one process at a time. The stub must not use 45020multiprocess extensions in packet replies unless @value{GDBN} has also 45021indicated it supports them in its @samp{qSupported} request. 45022 45023@item qXfer:osdata:read 45024The remote stub understands the @samp{qXfer:osdata:read} packet 45025((@pxref{qXfer osdata read}). 45026 45027@item ConditionalBreakpoints 45028The target accepts and implements evaluation of conditional expressions 45029defined for breakpoints. The target will only report breakpoint triggers 45030when such conditions are true (@pxref{Conditions, ,Break Conditions}). 45031 45032@item ConditionalTracepoints 45033The remote stub accepts and implements conditional expressions defined 45034for tracepoints (@pxref{Tracepoint Conditions}). 45035 45036@item ReverseContinue 45037The remote stub accepts and implements the reverse continue packet 45038(@pxref{bc}). 45039 45040@item ReverseStep 45041The remote stub accepts and implements the reverse step packet 45042(@pxref{bs}). 45043 45044@item TracepointSource 45045The remote stub understands the @samp{QTDPsrc} packet that supplies 45046the source form of tracepoint definitions. 45047 45048@item QAgent 45049The remote stub understands the @samp{QAgent} packet. 45050 45051@item QAllow 45052The remote stub understands the @samp{QAllow} packet. 45053 45054@item QDisableRandomization 45055The remote stub understands the @samp{QDisableRandomization} packet. 45056 45057@item StaticTracepoint 45058@cindex static tracepoints, in remote protocol 45059The remote stub supports static tracepoints. 45060 45061@item InstallInTrace 45062@anchor{install tracepoint in tracing} 45063The remote stub supports installing tracepoint in tracing. 45064 45065@item EnableDisableTracepoints 45066The remote stub supports the @samp{QTEnable} (@pxref{QTEnable}) and 45067@samp{QTDisable} (@pxref{QTDisable}) packets that allow tracepoints 45068to be enabled and disabled while a trace experiment is running. 45069 45070@item QTBuffer:size 45071The remote stub supports the @samp{QTBuffer:size} (@pxref{QTBuffer-size}) 45072packet that allows to change the size of the trace buffer. 45073 45074@item tracenz 45075@cindex string tracing, in remote protocol 45076The remote stub supports the @samp{tracenz} bytecode for collecting strings. 45077See @ref{Bytecode Descriptions} for details about the bytecode. 45078 45079@item BreakpointCommands 45080@cindex breakpoint commands, in remote protocol 45081The remote stub supports running a breakpoint's command list itself, 45082rather than reporting the hit to @value{GDBN}. 45083 45084@item Qbtrace:off 45085The remote stub understands the @samp{Qbtrace:off} packet. 45086 45087@item Qbtrace:bts 45088The remote stub understands the @samp{Qbtrace:bts} packet. 45089 45090@item Qbtrace:pt 45091The remote stub understands the @samp{Qbtrace:pt} packet. 45092 45093@item Qbtrace-conf:bts:size 45094The remote stub understands the @samp{Qbtrace-conf:bts:size} packet. 45095 45096@item Qbtrace-conf:pt:size 45097The remote stub understands the @samp{Qbtrace-conf:pt:size} packet. 45098 45099@item swbreak 45100The remote stub reports the @samp{swbreak} stop reason for memory 45101breakpoints. 45102 45103@item hwbreak 45104The remote stub reports the @samp{hwbreak} stop reason for hardware 45105breakpoints. 45106 45107@item fork-events 45108The remote stub reports the @samp{fork} stop reason for fork events. 45109 45110@item vfork-events 45111The remote stub reports the @samp{vfork} stop reason for vfork events 45112and vforkdone events. 45113 45114@item exec-events 45115The remote stub reports the @samp{exec} stop reason for exec events. 45116 45117@item vContSupported 45118The remote stub reports the supported actions in the reply to 45119@samp{vCont?} packet. 45120 45121@item QThreadEvents 45122The remote stub understands the @samp{QThreadEvents} packet. 45123 45124@item QThreadOptions=@var{supported_options} 45125The remote stub understands the @samp{QThreadOptions} packet. 45126@var{supported_options} indicates the set of thread options the remote 45127stub supports. @var{supported_options} has the same format as the 45128@var{options} parameter of the @code{QThreadOptions} packet, described 45129at @ref{QThreadOptions}. 45130 45131@item no-resumed 45132The remote stub reports the @samp{N} stop reply. 45133 45134 45135@item memory-tagging 45136The remote stub supports and implements the required memory tagging 45137functionality and understands the @samp{qMemTags} (@pxref{qMemTags}) and 45138@samp{QMemTags} (@pxref{QMemTags}) packets. 45139 45140For AArch64 GNU/Linux systems, this feature can require access to the 45141@file{/proc/@var{pid}/smaps} file so memory mapping page flags can be 45142inspected, if @samp{qIsAddressTagged} (@pxref{qIsAddressTagged}) packet 45143is not supported by the stub. Access to the @file{/proc/@var{pid}/smaps} 45144file is done via @samp{vFile} requests. 45145 45146@end table 45147 45148@item qSymbol:: 45149@cindex symbol lookup, remote request 45150@cindex @samp{qSymbol} packet 45151Notify the target that @value{GDBN} is prepared to serve symbol lookup 45152requests. Accept requests from the target for the values of symbols. 45153 45154Reply: 45155@table @samp 45156@item OK 45157The target does not need to look up any (more) symbols. 45158@item qSymbol:@var{sym_name} 45159The target requests the value of symbol @var{sym_name} (hex encoded). 45160@value{GDBN} may provide the value by using the 45161@samp{qSymbol:@var{sym_value}:@var{sym_name}} message, described 45162below. 45163@end table 45164 45165@item qSymbol:@var{sym_value}:@var{sym_name} 45166Set the value of @var{sym_name} to @var{sym_value}. 45167 45168@var{sym_name} (hex encoded) is the name of a symbol whose value the 45169target has previously requested. 45170 45171@var{sym_value} (hex) is the value for symbol @var{sym_name}. If 45172@value{GDBN} cannot supply a value for @var{sym_name}, then this field 45173will be empty. 45174 45175Reply: 45176@table @samp 45177@item OK 45178The target does not need to look up any (more) symbols. 45179@item qSymbol:@var{sym_name} 45180The target requests the value of a new symbol @var{sym_name} (hex 45181encoded). @value{GDBN} will continue to supply the values of symbols 45182(if available), until the target ceases to request them. 45183@end table 45184 45185@item qTBuffer 45186@itemx QTBuffer 45187@itemx QTDisconnected 45188@itemx QTDP 45189@itemx QTDPsrc 45190@itemx QTDV 45191@itemx qTfP 45192@itemx qTfV 45193@itemx QTFrame 45194@itemx qTMinFTPILen 45195 45196@xref{Tracepoint Packets}. 45197 45198@anchor{qThreadExtraInfo} 45199@item qThreadExtraInfo,@var{thread-id} 45200@cindex thread attributes info, remote request 45201@cindex @samp{qThreadExtraInfo} packet 45202Obtain from the target OS a printable string description of thread 45203attributes for the thread @var{thread-id}; see @ref{thread-id syntax}, 45204for the forms of @var{thread-id}. This 45205string may contain anything that the target OS thinks is interesting 45206for @value{GDBN} to tell the user about the thread. The string is 45207displayed in @value{GDBN}'s @code{info threads} display. Some 45208examples of possible thread extra info strings are @samp{Runnable}, or 45209@samp{Blocked on Mutex}. 45210 45211Reply: 45212@table @samp 45213@item @var{XX}@dots{} 45214Where @samp{@var{XX}@dots{}} is a hex encoding of @sc{ascii} data, 45215comprising the printable string containing the extra information about 45216the thread's attributes. 45217@end table 45218 45219(Note that the @code{qThreadExtraInfo} packet's name is separated from 45220the command by a @samp{,}, not a @samp{:}, contrary to the naming 45221conventions above. Please don't use this packet as a model for new 45222packets.) 45223 45224@item QTNotes 45225@itemx qTP 45226@itemx QTSave 45227@itemx qTsP 45228@itemx qTsV 45229@itemx QTStart 45230@itemx QTStop 45231@itemx QTEnable 45232@itemx QTDisable 45233@itemx QTinit 45234@itemx QTro 45235@itemx qTStatus 45236@itemx qTV 45237@itemx qTfSTM 45238@itemx qTsSTM 45239@itemx qTSTMat 45240@xref{Tracepoint Packets}. 45241 45242@item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length} 45243@cindex read special object, remote request 45244@cindex @samp{qXfer} packet 45245@anchor{qXfer read} 45246Read uninterpreted bytes from the target's special data area 45247identified by the keyword @var{object}. Request @var{length} bytes 45248starting at @var{offset} bytes into the data. The content and 45249encoding of @var{annex} is specific to @var{object}; it can supply 45250additional details about what data to access. 45251 45252Reply: 45253@table @samp 45254@item m @var{data} 45255Data @var{data} (@pxref{Binary Data}) has been read from the 45256target. There may be more data at a higher address (although 45257it is permitted to return @samp{m} even for the last valid 45258block of data, as long as at least one byte of data was read). 45259It is possible for @var{data} to have fewer bytes than the @var{length} in the 45260request. 45261 45262@item l @var{data} 45263Data @var{data} (@pxref{Binary Data}) has been read from the target. 45264There is no more data to be read. It is possible for @var{data} to 45265have fewer bytes than the @var{length} in the request. 45266 45267@item l 45268The @var{offset} in the request is at the end of the data. 45269There is no more data to be read. 45270@end table 45271 45272Here are the specific requests of this form defined so far. All the 45273@samp{qXfer:@var{object}:read:@dots{}} requests use the same reply 45274formats, listed above. 45275 45276@table @samp 45277@item qXfer:auxv:read::@var{offset},@var{length} 45278@anchor{qXfer auxiliary vector read} 45279Access the target's @dfn{auxiliary vector}. @xref{OS Information, 45280auxiliary vector}. Note @var{annex} must be empty. 45281 45282This packet is not probed by default; the remote stub must request it, 45283by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 45284 45285@item qXfer:btrace:read:@var{annex}:@var{offset},@var{length} 45286@anchor{qXfer btrace read} 45287 45288Return a description of the current branch trace. 45289@xref{Branch Trace Format}. The annex part of the generic @samp{qXfer} 45290packet may have one of the following values: 45291 45292@table @code 45293@item all 45294Returns all available branch trace. 45295 45296@item new 45297Returns all available branch trace if the branch trace changed since 45298the last read request. 45299 45300@item delta 45301Returns the new branch trace since the last read request. Adds a new 45302block to the end of the trace that begins at zero and ends at the source 45303location of the first branch in the trace buffer. This extra block is 45304used to stitch traces together. 45305 45306If the trace buffer overflowed, returns an error indicating the overflow. 45307@end table 45308 45309This packet is not probed by default; the remote stub must request it 45310by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 45311 45312@item qXfer:btrace-conf:read::@var{offset},@var{length} 45313@anchor{qXfer btrace-conf read} 45314 45315Return a description of the current branch trace configuration. 45316@xref{Branch Trace Configuration Format}. 45317 45318This packet is not probed by default; the remote stub must request it 45319by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 45320 45321@item qXfer:exec-file:read:@var{annex}:@var{offset},@var{length} 45322@anchor{qXfer executable filename read} 45323Return the full absolute name of the file that was executed to create 45324a process running on the remote system. The annex specifies the 45325numeric process ID of the process to query, encoded as a hexadecimal 45326number. If the annex part is empty the remote stub should return the 45327filename corresponding to the currently executing process. 45328 45329This packet is not probed by default; the remote stub must request it, 45330by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 45331 45332@item qXfer:features:read:@var{annex}:@var{offset},@var{length} 45333@anchor{qXfer target description read} 45334Access the @dfn{target description}. @xref{Target Descriptions}. The 45335annex specifies which XML document to access. The main description is 45336always loaded from the @samp{target.xml} annex. 45337 45338This packet is not probed by default; the remote stub must request it, 45339by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 45340 45341@item qXfer:libraries:read:@var{annex}:@var{offset},@var{length} 45342@anchor{qXfer library list read} 45343Access the target's list of loaded libraries. @xref{Library List Format}. 45344The annex part of the generic @samp{qXfer} packet must be empty 45345(@pxref{qXfer read}). 45346 45347Targets which maintain a list of libraries in the program's memory do 45348not need to implement this packet; it is designed for platforms where 45349the operating system manages the list of loaded libraries. 45350 45351This packet is not probed by default; the remote stub must request it, 45352by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 45353 45354@item qXfer:libraries-svr4:read:@var{annex}:@var{offset},@var{length} 45355@anchor{qXfer svr4 library list read} 45356Access the target's list of loaded libraries when the target is an SVR4 45357platform. @xref{Library List Format for SVR4 Targets}. The annex part 45358of the generic @samp{qXfer} packet must be empty unless the remote 45359stub indicated it supports the augmented form of this packet 45360by supplying an appropriate @samp{qSupported} response 45361(@pxref{qXfer read}, @ref{qSupported}). 45362 45363This packet is optional for better performance on SVR4 targets. 45364@value{GDBN} uses memory read packets to read the SVR4 library list otherwise. 45365 45366This packet is not probed by default; the remote stub must request it, 45367by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 45368 45369If the remote stub indicates it supports the augmented form of this 45370packet then the annex part of the generic @samp{qXfer} packet may 45371contain a semicolon-separated list of @samp{@var{name}=@var{value}} 45372arguments. The currently supported arguments are: 45373 45374@table @code 45375@item start=@var{address} 45376A hexadecimal number specifying the address of the @samp{struct 45377link_map} to start reading the library list from. If unset or zero 45378then the first @samp{struct link_map} in the library list will be 45379chosen as the starting point. 45380 45381@item prev=@var{address} 45382A hexadecimal number specifying the address of the @samp{struct 45383link_map} immediately preceding the @samp{struct link_map} 45384specified by the @samp{start} argument. If unset or zero then 45385the remote stub will expect that no @samp{struct link_map} 45386exists prior to the starting point. 45387 45388@item lmid=@var{lmid} 45389A hexadecimal number specifying a namespace identifier. This is 45390currently only used together with @samp{start} to provide the 45391namespace identifier back to @value{GDBN} in the response. 45392@value{GDBN} will only provide values that were previously reported to 45393it. If unset, the response will include @samp{lmid="0x0"}. 45394@end table 45395 45396Arguments that are not understood by the remote stub will be silently 45397ignored. 45398 45399@item qXfer:memory-map:read::@var{offset},@var{length} 45400@anchor{qXfer memory map read} 45401Access the target's @dfn{memory-map}. @xref{Memory Map Format}. The 45402annex part of the generic @samp{qXfer} packet must be empty 45403(@pxref{qXfer read}). 45404 45405This packet is not probed by default; the remote stub must request it, 45406by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 45407 45408@item qXfer:sdata:read::@var{offset},@var{length} 45409@anchor{qXfer sdata read} 45410 45411Read contents of the extra collected static tracepoint marker 45412information. The annex part of the generic @samp{qXfer} packet must 45413be empty (@pxref{qXfer read}). @xref{Tracepoint Actions,,Tracepoint 45414Action Lists}. 45415 45416This packet is not probed by default; the remote stub must request it, 45417by supplying an appropriate @samp{qSupported} response 45418(@pxref{qSupported}). 45419 45420@item qXfer:siginfo:read::@var{offset},@var{length} 45421@anchor{qXfer siginfo read} 45422Read contents of the extra signal information on the target 45423system. The annex part of the generic @samp{qXfer} packet must be 45424empty (@pxref{qXfer read}). 45425 45426This packet is not probed by default; the remote stub must request it, 45427by supplying an appropriate @samp{qSupported} response 45428(@pxref{qSupported}). 45429 45430@item qXfer:threads:read::@var{offset},@var{length} 45431@anchor{qXfer threads read} 45432Access the list of threads on target. @xref{Thread List Format}. The 45433annex part of the generic @samp{qXfer} packet must be empty 45434(@pxref{qXfer read}). 45435 45436This packet is not probed by default; the remote stub must request it, 45437by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 45438 45439@item qXfer:traceframe-info:read::@var{offset},@var{length} 45440@anchor{qXfer traceframe info read} 45441 45442Return a description of the current traceframe's contents. 45443@xref{Traceframe Info Format}. The annex part of the generic 45444@samp{qXfer} packet must be empty (@pxref{qXfer read}). 45445 45446This packet is not probed by default; the remote stub must request it, 45447by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 45448 45449@item qXfer:uib:read:@var{pc}:@var{offset},@var{length} 45450@anchor{qXfer unwind info block} 45451 45452Return the unwind information block for @var{pc}. This packet is used 45453on OpenVMS/ia64 to ask the kernel unwind information. 45454 45455This packet is not probed by default. 45456 45457@item qXfer:fdpic:read:@var{annex}:@var{offset},@var{length} 45458@anchor{qXfer fdpic loadmap read} 45459Read contents of @code{loadmap}s on the target system. The 45460annex, either @samp{exec} or @samp{interp}, specifies which @code{loadmap}, 45461executable @code{loadmap} or interpreter @code{loadmap} to read. 45462 45463This packet is not probed by default; the remote stub must request it, 45464by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 45465 45466@item qXfer:osdata:read::@var{offset},@var{length} 45467@anchor{qXfer osdata read} 45468Access the target's @dfn{operating system information}. 45469@xref{Operating System Information}. 45470 45471@end table 45472 45473@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{} 45474@cindex write data into object, remote request 45475@anchor{qXfer write} 45476Write uninterpreted bytes into the target's special data area 45477identified by the keyword @var{object}, starting at @var{offset} bytes 45478into the data. The binary-encoded data (@pxref{Binary Data}) to be 45479written is given by @var{data}@dots{}. The content and encoding of @var{annex} 45480is specific to @var{object}; it can supply additional details about what data 45481to access. 45482 45483Reply: 45484@table @samp 45485@item @var{nn} 45486@var{nn} (hex encoded) is the number of bytes written. 45487This may be fewer bytes than supplied in the request. 45488@end table 45489 45490Here are the specific requests of this form defined so far. All the 45491@samp{qXfer:@var{object}:write:@dots{}} requests use the same reply 45492formats, listed above. 45493 45494@table @samp 45495@item qXfer:siginfo:write::@var{offset}:@var{data}@dots{} 45496@anchor{qXfer siginfo write} 45497Write @var{data} to the extra signal information on the target system. 45498The annex part of the generic @samp{qXfer} packet must be 45499empty (@pxref{qXfer write}). 45500 45501This packet is not probed by default; the remote stub must request it, 45502by supplying an appropriate @samp{qSupported} response 45503(@pxref{qSupported}). 45504@end table 45505 45506@item qXfer:@var{object}:@var{operation}:@dots{} 45507Requests of this form may be added in the future. When a stub does 45508not recognize the @var{object} keyword, or its support for 45509@var{object} does not recognize the @var{operation} keyword, the stub 45510must respond with an empty packet. 45511 45512@item qAttached:@var{pid} 45513@cindex query attached, remote request 45514@cindex @samp{qAttached} packet 45515Return an indication of whether the remote server attached to an 45516existing process or created a new process. When the multiprocess 45517protocol extensions are supported (@pxref{multiprocess extensions}), 45518@var{pid} is an integer in hexadecimal format identifying the target 45519process. Otherwise, @value{GDBN} will omit the @var{pid} field and 45520the query packet will be simplified as @samp{qAttached}. 45521 45522This query is used, for example, to know whether the remote process 45523should be detached or killed when a @value{GDBN} session is ended with 45524the @code{quit} command. 45525 45526Reply: 45527@table @samp 45528@item 1 45529The remote server attached to an existing process. 45530@item 0 45531The remote server created a new process. 45532@end table 45533 45534@item Qbtrace:bts 45535Enable branch tracing for the current thread using Branch Trace Store. 45536 45537Reply: 45538@table @samp 45539@item OK 45540Branch tracing has been enabled. 45541@end table 45542 45543@item Qbtrace:pt 45544Enable branch tracing for the current thread using Intel Processor Trace. 45545 45546Reply: 45547@table @samp 45548@item OK 45549Branch tracing has been enabled. 45550@end table 45551 45552@item Qbtrace:off 45553Disable branch tracing for the current thread. 45554 45555Reply: 45556@table @samp 45557@item OK 45558Branch tracing has been disabled. 45559@end table 45560 45561@item Qbtrace-conf:bts:size=@var{value} 45562Set the requested ring buffer size for new threads that use the 45563btrace recording method in bts format. 45564 45565Reply: 45566@table @samp 45567@item OK 45568The ring buffer size has been set. 45569@end table 45570 45571@item Qbtrace-conf:pt:size=@var{value} 45572Set the requested ring buffer size for new threads that use the 45573btrace recording method in pt format. 45574 45575Reply: 45576@table @samp 45577@item OK 45578The ring buffer size has been set. 45579@end table 45580 45581@end table 45582 45583@node Architecture-Specific Protocol Details 45584@section Architecture-Specific Protocol Details 45585 45586This section describes how the remote protocol is applied to specific 45587target architectures. Also see @ref{Standard Target Features}, for 45588details of XML target descriptions for each architecture. 45589 45590@menu 45591* ARM-Specific Protocol Details:: 45592* MIPS-Specific Protocol Details:: 45593@end menu 45594 45595@node ARM-Specific Protocol Details 45596@subsection @acronym{ARM}-specific Protocol Details 45597 45598@menu 45599* ARM Breakpoint Kinds:: 45600* ARM Memory Tag Types:: 45601@end menu 45602 45603@node ARM Breakpoint Kinds 45604@subsubsection @acronym{ARM} Breakpoint Kinds 45605@cindex breakpoint kinds, @acronym{ARM} 45606 45607These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets. 45608 45609@table @r 45610 45611@item 2 4561216-bit Thumb mode breakpoint. 45613 45614@item 3 4561532-bit Thumb mode (Thumb-2) breakpoint. 45616 45617@item 4 4561832-bit @acronym{ARM} mode breakpoint. 45619 45620@end table 45621 45622@node ARM Memory Tag Types 45623@subsubsection @acronym{ARM} Memory Tag Types 45624@cindex memory tag types, @acronym{ARM} 45625 45626These memory tag types are defined for the @samp{qMemTag} and @samp{QMemTag} 45627packets. 45628 45629@table @r 45630 45631@item 0 45632MTE logical tag 45633 45634@item 1 45635MTE allocation tag 45636 45637@end table 45638 45639@node MIPS-Specific Protocol Details 45640@subsection @acronym{MIPS}-specific Protocol Details 45641 45642@menu 45643* MIPS Register packet Format:: 45644* MIPS Breakpoint Kinds:: 45645@end menu 45646 45647@node MIPS Register packet Format 45648@subsubsection @acronym{MIPS} Register Packet Format 45649@cindex register packet format, @acronym{MIPS} 45650 45651The following @code{g}/@code{G} packets have previously been defined. 45652In the below, some thirty-two bit registers are transferred as 45653sixty-four bits. Those registers should be zero/sign extended (which?) 45654to fill the space allocated. Register bytes are transferred in target 45655byte order. The two nibbles within a register byte are transferred 45656most-significant -- least-significant. 45657 45658@table @r 45659 45660@item MIPS32 45661All registers are transferred as thirty-two bit quantities in the order: 4566232 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point 45663registers; fsr; fir; fp. 45664 45665@item MIPS64 45666All registers are transferred as sixty-four bit quantities (including 45667thirty-two bit registers such as @code{sr}). The ordering is the same 45668as @code{MIPS32}. 45669 45670@end table 45671 45672@node MIPS Breakpoint Kinds 45673@subsubsection @acronym{MIPS} Breakpoint Kinds 45674@cindex breakpoint kinds, @acronym{MIPS} 45675 45676These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets. 45677 45678@table @r 45679 45680@item 2 4568116-bit @acronym{MIPS16} mode breakpoint. 45682 45683@item 3 4568416-bit @acronym{microMIPS} mode breakpoint. 45685 45686@item 4 4568732-bit standard @acronym{MIPS} mode breakpoint. 45688 45689@item 5 4569032-bit @acronym{microMIPS} mode breakpoint. 45691 45692@end table 45693 45694@node Tracepoint Packets 45695@section Tracepoint Packets 45696@cindex tracepoint packets 45697@cindex packets, tracepoint 45698 45699Here we describe the packets @value{GDBN} uses to implement 45700tracepoints (@pxref{Tracepoints}). 45701 45702@table @samp 45703 45704@item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}[:F@var{flen}][:X@var{len},@var{bytes}]@r{[}-@r{]} 45705@cindex @samp{QTDP} packet 45706Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena} 45707is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then 45708the tracepoint is disabled. The @var{step} gives the tracepoint's step 45709count, and @var{pass} gives its pass count. If an @samp{F} is present, 45710then the tracepoint is to be a fast tracepoint, and the @var{flen} is 45711the number of bytes that the target should copy elsewhere to make room 45712for the tracepoint. If an @samp{X} is present, it introduces a 45713tracepoint condition, which consists of a hexadecimal length, followed 45714by a comma and hex-encoded bytes, in a manner similar to action 45715encodings as described below. If the trailing @samp{-} is present, 45716further @samp{QTDP} packets will follow to specify this tracepoint's 45717actions. 45718 45719Replies: 45720@table @samp 45721@item OK 45722The packet was understood and carried out. 45723@item qRelocInsn 45724@xref{Tracepoint Packets,,Relocate instruction reply packet}. 45725@end table 45726 45727@item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]} 45728Define actions to be taken when a tracepoint is hit. The @var{n} and 45729@var{addr} must be the same as in the initial @samp{QTDP} packet for 45730this tracepoint. This packet may only be sent immediately after 45731another @samp{QTDP} packet that ended with a @samp{-}. If the 45732trailing @samp{-} is present, further @samp{QTDP} packets will follow, 45733specifying more actions for this tracepoint. 45734 45735In the series of action packets for a given tracepoint, at most one 45736can have an @samp{S} before its first @var{action}. If such a packet 45737is sent, it and the following packets define ``while-stepping'' 45738actions. Any prior packets define ordinary actions --- that is, those 45739taken when the tracepoint is first hit. If no action packet has an 45740@samp{S}, then all the packets in the series specify ordinary 45741tracepoint actions. 45742 45743The @samp{@var{action}@dots{}} portion of the packet is a series of 45744actions, concatenated without separators. Each action has one of the 45745following forms: 45746 45747@table @samp 45748 45749@item R @var{mask} 45750Collect the registers whose bits are set in @var{mask}, 45751a hexadecimal number whose @var{i}'th bit is set if register number 45752@var{i} should be collected. (The least significant bit is numbered 45753zero.) Note that @var{mask} may be any number of digits long; it may 45754not fit in a 32-bit word. 45755 45756@item M @var{basereg},@var{offset},@var{len} 45757Collect @var{len} bytes of memory starting at the address in register 45758number @var{basereg}, plus @var{offset}. If @var{basereg} is 45759@samp{-1}, then the range has a fixed address: @var{offset} is the 45760address of the lowest byte to collect. The @var{basereg}, 45761@var{offset}, and @var{len} parameters are all unsigned hexadecimal 45762values (the @samp{-1} value for @var{basereg} is a special case). 45763 45764@item X @var{len},@var{expr} 45765Evaluate @var{expr}, whose length is @var{len}, and collect memory as 45766it directs. The agent expression @var{expr} is as described in 45767@ref{Agent Expressions}. Each byte of the expression is encoded as a 45768two-digit hex number in the packet; @var{len} is the number of bytes 45769in the expression (and thus one-half the number of hex digits in the 45770packet). 45771 45772@end table 45773 45774Any number of actions may be packed together in a single @samp{QTDP} 45775packet, as long as the packet does not exceed the maximum packet 45776length (400 bytes, for many stubs). There may be only one @samp{R} 45777action per tracepoint, and it must precede any @samp{M} or @samp{X} 45778actions. Any registers referred to by @samp{M} and @samp{X} actions 45779must be collected by a preceding @samp{R} action. (The 45780``while-stepping'' actions are treated as if they were attached to a 45781separate tracepoint, as far as these restrictions are concerned.) 45782 45783Replies: 45784@table @samp 45785@item OK 45786The packet was understood and carried out. 45787@item qRelocInsn 45788@xref{Tracepoint Packets,,Relocate instruction reply packet}. 45789@end table 45790 45791@item QTDPsrc:@var{n}:@var{addr}:@var{type}:@var{start}:@var{slen}:@var{bytes} 45792@cindex @samp{QTDPsrc} packet 45793Specify a source string of tracepoint @var{n} at address @var{addr}. 45794This is useful to get accurate reproduction of the tracepoints 45795originally downloaded at the beginning of the trace run. The @var{type} 45796is the name of the tracepoint part, such as @samp{cond} for the 45797tracepoint's conditional expression (see below for a list of types), while 45798@var{bytes} is the string, encoded in hexadecimal. 45799 45800@var{start} is the offset of the @var{bytes} within the overall source 45801string, while @var{slen} is the total length of the source string. 45802This is intended for handling source strings that are longer than will 45803fit in a single packet. 45804@c Add detailed example when this info is moved into a dedicated 45805@c tracepoint descriptions section. 45806 45807The available string types are @samp{at} for the location, 45808@samp{cond} for the conditional, and @samp{cmd} for an action command. 45809@value{GDBN} sends a separate packet for each command in the action 45810list, in the same order in which the commands are stored in the list. 45811 45812The target does not need to do anything with source strings except 45813report them back as part of the replies to the @samp{qTfP}/@samp{qTsP} 45814query packets. 45815 45816Although this packet is optional, and @value{GDBN} will only send it 45817if the target replies with @samp{TracepointSource} @xref{General 45818Query Packets}, it makes both disconnected tracing and trace files 45819much easier to use. Otherwise the user must be careful that the 45820tracepoints in effect while looking at trace frames are identical to 45821the ones in effect during the trace run; even a small discrepancy 45822could cause @samp{tdump} not to work, or a particular trace frame not 45823be found. 45824 45825@item QTDV:@var{n}:@var{value}:@var{builtin}:@var{name} 45826@cindex define trace state variable, remote request 45827@cindex @samp{QTDV} packet 45828Create a new trace state variable, number @var{n}, with an initial 45829value of @var{value}, which is a 64-bit signed integer. Both @var{n} 45830and @var{value} are encoded as hexadecimal values. @value{GDBN} has 45831the option of not using this packet for initial values of zero; the 45832target should simply create the trace state variables as they are 45833mentioned in expressions. The value @var{builtin} should be 1 (one) 45834if the trace state variable is builtin and 0 (zero) if it is not builtin. 45835@value{GDBN} only sets @var{builtin} to 1 if a previous @samp{qTfV} or 45836@samp{qTsV} packet had it set. The contents of @var{name} is the 45837hex-encoded name (without the leading @samp{$}) of the trace state 45838variable. 45839 45840@item QTFrame:@var{n} 45841@cindex @samp{QTFrame} packet 45842Select the @var{n}'th tracepoint frame from the buffer, and use the 45843register and memory contents recorded there to answer subsequent 45844request packets from @value{GDBN}. 45845 45846A successful reply from the stub indicates that the stub has found the 45847requested frame. The response is a series of parts, concatenated 45848without separators, describing the frame we selected. Each part has 45849one of the following forms: 45850 45851@table @samp 45852@item F @var{f} 45853The selected frame is number @var{n} in the trace frame buffer; 45854@var{f} is a hexadecimal number. If @var{f} is @samp{-1}, then there 45855was no frame matching the criteria in the request packet. 45856 45857@item T @var{t} 45858The selected trace frame records a hit of tracepoint number @var{t}; 45859@var{t} is a hexadecimal number. 45860 45861@end table 45862 45863@item QTFrame:pc:@var{addr} 45864Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the 45865currently selected frame whose PC is @var{addr}; 45866@var{addr} is a hexadecimal number. 45867 45868@item QTFrame:tdp:@var{t} 45869Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the 45870currently selected frame that is a hit of tracepoint @var{t}; @var{t} 45871is a hexadecimal number. 45872 45873@item QTFrame:range:@var{start}:@var{end} 45874Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the 45875currently selected frame whose PC is between @var{start} (inclusive) 45876and @var{end} (inclusive); @var{start} and @var{end} are hexadecimal 45877numbers. 45878 45879@item QTFrame:outside:@var{start}:@var{end} 45880Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first 45881frame @emph{outside} the given range of addresses (exclusive). 45882 45883@item qTMinFTPILen 45884@cindex @samp{qTMinFTPILen} packet 45885This packet requests the minimum length of instruction at which a fast 45886tracepoint (@pxref{Set Tracepoints}) may be placed. For instance, on 45887the 32-bit x86 architecture, it is possible to use a 4-byte jump, but 45888it depends on the target system being able to create trampolines in 45889the first 64K of memory, which might or might not be possible for that 45890system. So the reply to this packet will be 4 if it is able to 45891arrange for that. 45892 45893Replies: 45894 45895@table @samp 45896@item 0 45897The minimum instruction length is currently unknown. 45898@item @var{length} 45899The minimum instruction length is @var{length}, where @var{length} 45900is a hexadecimal number greater or equal to 1. A reply 45901of 1 means that a fast tracepoint may be placed on any instruction 45902regardless of size. 45903@item E 45904An error has occurred. 45905@end table 45906 45907@item QTStart 45908@cindex @samp{QTStart} packet 45909Begin the tracepoint experiment. Begin collecting data from 45910tracepoint hits in the trace frame buffer. This packet supports the 45911@samp{qRelocInsn} reply (@pxref{Tracepoint Packets,,Relocate 45912instruction reply packet}). 45913 45914@item QTStop 45915@cindex @samp{QTStop} packet 45916End the tracepoint experiment. Stop collecting trace frames. 45917 45918@item QTEnable:@var{n}:@var{addr} 45919@anchor{QTEnable} 45920@cindex @samp{QTEnable} packet 45921Enable tracepoint @var{n} at address @var{addr} in a started tracepoint 45922experiment. If the tracepoint was previously disabled, then collection 45923of data from it will resume. 45924 45925@item QTDisable:@var{n}:@var{addr} 45926@anchor{QTDisable} 45927@cindex @samp{QTDisable} packet 45928Disable tracepoint @var{n} at address @var{addr} in a started tracepoint 45929experiment. No more data will be collected from the tracepoint unless 45930@samp{QTEnable:@var{n}:@var{addr}} is subsequently issued. 45931 45932@item QTinit 45933@cindex @samp{QTinit} packet 45934Clear the table of tracepoints, and empty the trace frame buffer. 45935 45936@item QTro:@var{start1},@var{end1}:@var{start2},@var{end2}:@dots{} 45937@cindex @samp{QTro} packet 45938Establish the given ranges of memory as ``transparent''. The stub 45939will answer requests for these ranges from memory's current contents, 45940if they were not collected as part of the tracepoint hit. 45941 45942@value{GDBN} uses this to mark read-only regions of memory, like those 45943containing program code. Since these areas never change, they should 45944still have the same contents they did when the tracepoint was hit, so 45945there's no reason for the stub to refuse to provide their contents. 45946 45947@item QTDisconnected:@var{value} 45948@cindex @samp{QTDisconnected} packet 45949Set the choice to what to do with the tracing run when @value{GDBN} 45950disconnects from the target. A @var{value} of 1 directs the target to 45951continue the tracing run, while 0 tells the target to stop tracing if 45952@value{GDBN} is no longer in the picture. 45953 45954@item qTStatus 45955@cindex @samp{qTStatus} packet 45956Ask the stub if there is a trace experiment running right now. 45957 45958The reply has the form: 45959 45960@table @samp 45961 45962@item T@var{running}@r{[};@var{field}@r{]}@dots{} 45963@var{running} is a single digit @code{1} if the trace is presently 45964running, or @code{0} if not. It is followed by semicolon-separated 45965optional fields that an agent may use to report additional status. 45966 45967@end table 45968 45969If the trace is not running, the agent may report any of several 45970explanations as one of the optional fields: 45971 45972@table @samp 45973 45974@item tnotrun:0 45975No trace has been run yet. 45976 45977@item tstop[:@var{text}]:0 45978The trace was stopped by a user-originated stop command. The optional 45979@var{text} field is a user-supplied string supplied as part of the 45980stop command (for instance, an explanation of why the trace was 45981stopped manually). It is hex-encoded. 45982 45983@item tfull:0 45984The trace stopped because the trace buffer filled up. 45985 45986@item tdisconnected:0 45987The trace stopped because @value{GDBN} disconnected from the target. 45988 45989@item tpasscount:@var{tpnum} 45990The trace stopped because tracepoint @var{tpnum} exceeded its pass count. 45991 45992@item terror:@var{text}:@var{tpnum} 45993The trace stopped because tracepoint @var{tpnum} had an error. The 45994string @var{text} is available to describe the nature of the error 45995(for instance, a divide by zero in the condition expression); it 45996is hex encoded. 45997 45998@item tunknown:0 45999The trace stopped for some other reason. 46000 46001@end table 46002 46003Additional optional fields supply statistical and other information. 46004Although not required, they are extremely useful for users monitoring 46005the progress of a trace run. If a trace has stopped, and these 46006numbers are reported, they must reflect the state of the just-stopped 46007trace. 46008 46009@table @samp 46010 46011@item tframes:@var{n} 46012The number of trace frames in the buffer. 46013 46014@item tcreated:@var{n} 46015The total number of trace frames created during the run. This may 46016be larger than the trace frame count, if the buffer is circular. 46017 46018@item tsize:@var{n} 46019The total size of the trace buffer, in bytes. 46020 46021@item tfree:@var{n} 46022The number of bytes still unused in the buffer. 46023 46024@item circular:@var{n} 46025The value of the circular trace buffer flag. @code{1} means that the 46026trace buffer is circular and old trace frames will be discarded if 46027necessary to make room, @code{0} means that the trace buffer is linear 46028and may fill up. 46029 46030@item disconn:@var{n} 46031The value of the disconnected tracing flag. @code{1} means that 46032tracing will continue after @value{GDBN} disconnects, @code{0} means 46033that the trace run will stop. 46034 46035@end table 46036 46037@item qTP:@var{tp}:@var{addr} 46038@cindex tracepoint status, remote request 46039@cindex @samp{qTP} packet 46040Ask the stub for the current state of tracepoint number @var{tp} at 46041address @var{addr}. 46042 46043Replies: 46044@table @samp 46045@item V@var{hits}:@var{usage} 46046The tracepoint has been hit @var{hits} times so far during the trace 46047run, and accounts for @var{usage} in the trace buffer. Note that 46048@code{while-stepping} steps are not counted as separate hits, but the 46049steps' space consumption is added into the usage number. 46050 46051@end table 46052 46053@item qTV:@var{var} 46054@cindex trace state variable value, remote request 46055@cindex @samp{qTV} packet 46056Ask the stub for the value of the trace state variable number @var{var}. 46057 46058Replies: 46059@table @samp 46060@item V@var{value} 46061The value of the variable is @var{value}. This will be the current 46062value of the variable if the user is examining a running target, or a 46063saved value if the variable was collected in the trace frame that the 46064user is looking at. Note that multiple requests may result in 46065different reply values, such as when requesting values while the 46066program is running. 46067 46068@item U 46069The value of the variable is unknown. This would occur, for example, 46070if the user is examining a trace frame in which the requested variable 46071was not collected. 46072@end table 46073 46074@item qTfP 46075@cindex @samp{qTfP} packet 46076@itemx qTsP 46077@cindex @samp{qTsP} packet 46078These packets request data about tracepoints that are being used by 46079the target. @value{GDBN} sends @code{qTfP} to get the first piece 46080of data, and multiple @code{qTsP} to get additional pieces. Replies 46081to these packets generally take the form of the @code{QTDP} packets 46082that define tracepoints. (FIXME add detailed syntax) 46083 46084@item qTfV 46085@cindex @samp{qTfV} packet 46086@itemx qTsV 46087@cindex @samp{qTsV} packet 46088These packets request data about trace state variables that are on the 46089target. @value{GDBN} sends @code{qTfV} to get the first vari of data, 46090and multiple @code{qTsV} to get additional variables. Replies to 46091these packets follow the syntax of the @code{QTDV} packets that define 46092trace state variables. 46093 46094@item qTfSTM 46095@itemx qTsSTM 46096@anchor{qTfSTM} 46097@anchor{qTsSTM} 46098@cindex @samp{qTfSTM} packet 46099@cindex @samp{qTsSTM} packet 46100These packets request data about static tracepoint markers that exist 46101in the target program. @value{GDBN} sends @code{qTfSTM} to get the 46102first piece of data, and multiple @code{qTsSTM} to get additional 46103pieces. Replies to these packets take the following form: 46104 46105Reply: 46106@table @samp 46107@item m @var{address}:@var{id}:@var{extra} 46108A single marker 46109@item m @var{address}:@var{id}:@var{extra},@var{address}:@var{id}:@var{extra}@dots{} 46110a comma-separated list of markers 46111@item l 46112(lower case letter @samp{L}) denotes end of list. 46113@end table 46114 46115The @var{address} is encoded in hex; 46116@var{id} and @var{extra} are strings encoded in hex. 46117 46118In response to each query, the target will reply with a list of one or 46119more markers, separated by commas. @value{GDBN} will respond to each 46120reply with a request for more markers (using the @samp{qs} form of the 46121query), until the target responds with @samp{l} (lower-case ell, for 46122@dfn{last}). 46123 46124@item qTSTMat:@var{address} 46125@anchor{qTSTMat} 46126@cindex @samp{qTSTMat} packet 46127This packets requests data about static tracepoint markers in the 46128target program at @var{address}. Replies to this packet follow the 46129syntax of the @samp{qTfSTM} and @code{qTsSTM} packets that list static 46130tracepoint markers. 46131 46132@item QTSave:@var{filename} 46133@cindex @samp{QTSave} packet 46134This packet directs the target to save trace data to the file name 46135@var{filename} in the target's filesystem. The @var{filename} is encoded 46136as a hex string; the interpretation of the file name (relative vs 46137absolute, wild cards, etc) is up to the target. 46138 46139@item qTBuffer:@var{offset},@var{len} 46140@cindex @samp{qTBuffer} packet 46141Return up to @var{len} bytes of the current contents of trace buffer, 46142starting at @var{offset}. The trace buffer is treated as if it were 46143a contiguous collection of traceframes, as per the trace file format. 46144The reply consists as many hex-encoded bytes as the target can deliver 46145in a packet; it is not an error to return fewer than were asked for. 46146A reply consisting of just @code{l} indicates that no bytes are 46147available. 46148 46149@item QTBuffer:circular:@var{value} 46150This packet directs the target to use a circular trace buffer if 46151@var{value} is 1, or a linear buffer if the value is 0. 46152 46153@item QTBuffer:size:@var{size} 46154@anchor{QTBuffer-size} 46155@cindex @samp{QTBuffer size} packet 46156This packet directs the target to make the trace buffer be of size 46157@var{size} if possible. A value of @code{-1} tells the target to 46158use whatever size it prefers. 46159 46160@item QTNotes:@r{[}@var{type}:@var{text}@r{]}@r{[};@var{type}:@var{text}@r{]}@dots{} 46161@cindex @samp{QTNotes} packet 46162This packet adds optional textual notes to the trace run. Allowable 46163types include @code{user}, @code{notes}, and @code{tstop}, the 46164@var{text} fields are arbitrary strings, hex-encoded. 46165 46166@end table 46167 46168@subsection Relocate instruction reply packet 46169When installing fast tracepoints in memory, the target may need to 46170relocate the instruction currently at the tracepoint address to a 46171different address in memory. For most instructions, a simple copy is 46172enough, but, for example, call instructions that implicitly push the 46173return address on the stack, and relative branches or other 46174PC-relative instructions require offset adjustment, so that the effect 46175of executing the instruction at a different address is the same as if 46176it had executed in the original location. 46177 46178In response to several of the tracepoint packets, the target may also 46179respond with a number of intermediate @samp{qRelocInsn} request 46180packets before the final result packet, to have @value{GDBN} handle 46181this relocation operation. If a packet supports this mechanism, its 46182documentation will explicitly say so. See for example the above 46183descriptions for the @samp{QTStart} and @samp{QTDP} packets. The 46184format of the request is: 46185 46186@table @samp 46187@item qRelocInsn:@var{from};@var{to} 46188 46189This requests @value{GDBN} to copy instruction at address @var{from} 46190to address @var{to}, possibly adjusted so that executing the 46191instruction at @var{to} has the same effect as executing it at 46192@var{from}. @value{GDBN} writes the adjusted instruction to target 46193memory starting at @var{to}. 46194@end table 46195 46196Replies: 46197@table @samp 46198@item qRelocInsn:@var{adjusted_size} 46199Informs the stub the relocation is complete. The @var{adjusted_size} is 46200the length in bytes of resulting relocated instruction sequence. 46201@end table 46202 46203@node Host I/O Packets 46204@section Host I/O Packets 46205@cindex Host I/O, remote protocol 46206@cindex file transfer, remote protocol 46207 46208The @dfn{Host I/O} packets allow @value{GDBN} to perform I/O 46209operations on the far side of a remote link. For example, Host I/O is 46210used to upload and download files to a remote target with its own 46211filesystem. Host I/O uses the same constant values and data structure 46212layout as the target-initiated File-I/O protocol. However, the 46213Host I/O packets are structured differently. The target-initiated 46214protocol relies on target memory to store parameters and buffers. 46215Host I/O requests are initiated by @value{GDBN}, and the 46216target's memory is not involved. @xref{File-I/O Remote Protocol 46217Extension}, for more details on the target-initiated protocol. 46218 46219The Host I/O request packets all encode a single operation along with 46220its arguments. They have this format: 46221 46222@table @samp 46223 46224@item vFile:@var{operation}: @var{parameter}@dots{} 46225@var{operation} is the name of the particular request; the target 46226should compare the entire packet name up to the second colon when checking 46227for a supported operation. The format of @var{parameter} depends on 46228the operation. Numbers are always passed in hexadecimal. Negative 46229numbers have an explicit minus sign (i.e.@: two's complement is not 46230used). Strings (e.g.@: filenames) are encoded as a series of 46231hexadecimal bytes. The last argument to a system call may be a 46232buffer of escaped binary data (@pxref{Binary Data}). 46233 46234@end table 46235 46236The valid responses to Host I/O packets are: 46237 46238@table @samp 46239 46240@item F @var{result} [, @var{errno}] [; @var{attachment}] 46241@var{result} is the integer value returned by this operation, usually 46242non-negative for success and -1 for errors. If an error has occurred, 46243@var{errno} will be included in the result specifying a 46244value defined by the File-I/O protocol (@pxref{Errno Values}). For 46245operations which return data, @var{attachment} supplies the data as a 46246binary buffer. Binary buffers in response packets are escaped in the 46247normal way (@pxref{Binary Data}). See the individual packet 46248documentation for the interpretation of @var{result} and 46249@var{attachment}. 46250 46251@item @w{} 46252An empty response indicates that this operation is not recognized. 46253 46254@end table 46255 46256These are the supported Host I/O operations: 46257 46258@table @samp 46259@item vFile:open: @var{filename}, @var{flags}, @var{mode} 46260Open a file at @var{filename} and return a file descriptor for it, or 46261return -1 if an error occurs. The @var{filename} is a string, 46262@var{flags} is an integer indicating a mask of open flags 46263(@pxref{Open Flags}), and @var{mode} is an integer indicating a mask 46264of mode bits to use if the file is created (@pxref{mode_t Values}). 46265@xref{open}, for details of the open flags and mode values. 46266 46267@item vFile:close: @var{fd} 46268Close the open file corresponding to @var{fd} and return 0, or 46269-1 if an error occurs. 46270 46271@item vFile:pread: @var{fd}, @var{count}, @var{offset} 46272Read data from the open file corresponding to @var{fd}. Up to 46273@var{count} bytes will be read from the file, starting at @var{offset} 46274relative to the start of the file. The target may read fewer bytes; 46275common reasons include packet size limits and an end-of-file 46276condition. The number of bytes read is returned. Zero should only be 46277returned for a successful read at the end of the file, or if 46278@var{count} was zero. 46279 46280The data read should be returned as a binary attachment on success. 46281If zero bytes were read, the response should include an empty binary 46282attachment (i.e.@: a trailing semicolon). The return value is the 46283number of target bytes read; the binary attachment may be longer if 46284some characters were escaped. 46285 46286@item vFile:pwrite: @var{fd}, @var{offset}, @var{data} 46287Write @var{data} (a binary buffer) to the open file corresponding 46288to @var{fd}. Start the write at @var{offset} from the start of the 46289file. Unlike many @code{write} system calls, there is no 46290separate @var{count} argument; the length of @var{data} in the 46291packet is used. @samp{vFile:pwrite} returns the number of bytes written, 46292which may be shorter than the length of @var{data}, or -1 if an 46293error occurred. 46294 46295@item vFile:fstat: @var{fd} 46296Get information about the open file corresponding to @var{fd}. 46297On success the information is returned as a binary attachment 46298and the return value is the size of this attachment in bytes. 46299If an error occurs the return value is -1. The format of the 46300returned binary attachment is as described in @ref{struct stat}. 46301 46302@item vFile:unlink: @var{filename} 46303Delete the file at @var{filename} on the target. Return 0, 46304or -1 if an error occurs. The @var{filename} is a string. 46305 46306@item vFile:readlink: @var{filename} 46307Read value of symbolic link @var{filename} on the target. Return 46308the number of bytes read, or -1 if an error occurs. 46309 46310The data read should be returned as a binary attachment on success. 46311If zero bytes were read, the response should include an empty binary 46312attachment (i.e.@: a trailing semicolon). The return value is the 46313number of target bytes read; the binary attachment may be longer if 46314some characters were escaped. 46315 46316@item vFile:setfs: @var{pid} 46317Select the filesystem on which @code{vFile} operations with 46318@var{filename} arguments will operate. This is required for 46319@value{GDBN} to be able to access files on remote targets where 46320the remote stub does not share a common filesystem with the 46321inferior(s). 46322 46323If @var{pid} is nonzero, select the filesystem as seen by process 46324@var{pid}. If @var{pid} is zero, select the filesystem as seen by 46325the remote stub. Return 0 on success, or -1 if an error occurs. 46326If @code{vFile:setfs:} indicates success, the selected filesystem 46327remains selected until the next successful @code{vFile:setfs:} 46328operation. 46329 46330@end table 46331 46332@node Interrupts 46333@section Interrupts 46334@cindex interrupts (remote protocol) 46335@anchor{interrupting remote targets} 46336 46337In all-stop mode, when a program on the remote target is running, 46338@value{GDBN} may attempt to interrupt it by sending a @samp{Ctrl-C}, 46339@code{BREAK} or a @code{BREAK} followed by @code{g}, control of which 46340is specified via @value{GDBN}'s @samp{interrupt-sequence}. 46341 46342The precise meaning of @code{BREAK} is defined by the transport 46343mechanism and may, in fact, be undefined. @value{GDBN} does not 46344currently define a @code{BREAK} mechanism for any of the network 46345interfaces except for TCP, in which case @value{GDBN} sends the 46346@code{telnet} BREAK sequence. 46347 46348@samp{Ctrl-C}, on the other hand, is defined and implemented for all 46349transport mechanisms. It is represented by sending the single byte 46350@code{0x03} without any of the usual packet overhead described in 46351the Overview section (@pxref{Overview}). When a @code{0x03} byte is 46352transmitted as part of a packet, it is considered to be packet data 46353and does @emph{not} represent an interrupt. E.g., an @samp{X} packet 46354(@pxref{X packet}), used for binary downloads, may include an unescaped 46355@code{0x03} as part of its packet. 46356 46357@code{BREAK} followed by @code{g} is also known as Magic SysRq g. 46358When Linux kernel receives this sequence from serial port, 46359it stops execution and connects to gdb. 46360 46361In non-stop mode, because packet resumptions are asynchronous 46362(@pxref{vCont packet}), @value{GDBN} is always free to send a remote 46363command to the remote stub, even when the target is running. For that 46364reason, @value{GDBN} instead sends a regular packet (@pxref{vCtrlC 46365packet}) with the usual packet framing instead of the single byte 46366@code{0x03}. 46367 46368Stubs are not required to recognize these interrupt mechanisms and the 46369precise meaning associated with receipt of the interrupt is 46370implementation defined. If the target supports debugging of multiple 46371threads and/or processes, it should attempt to interrupt all 46372currently-executing threads and processes. 46373If the stub is successful at interrupting the 46374running program, it should send one of the stop 46375reply packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result 46376of successfully stopping the program in all-stop mode, and a stop reply 46377for each stopped thread in non-stop mode. 46378Interrupts received while the 46379program is stopped are queued and the program will be interrupted when 46380it is resumed next time. 46381 46382@node Notification Packets 46383@section Notification Packets 46384@cindex notification packets 46385@cindex packets, notification 46386 46387The @value{GDBN} remote serial protocol includes @dfn{notifications}, 46388packets that require no acknowledgment. Both the GDB and the stub 46389may send notifications (although the only notifications defined at 46390present are sent by the stub). Notifications carry information 46391without incurring the round-trip latency of an acknowledgment, and so 46392are useful for low-impact communications where occasional packet loss 46393is not a problem. 46394 46395A notification packet has the form @samp{% @var{data} # 46396@var{checksum}}, where @var{data} is the content of the notification, 46397and @var{checksum} is a checksum of @var{data}, computed and formatted 46398as for ordinary @value{GDBN} packets. A notification's @var{data} 46399never contains @samp{$}, @samp{%} or @samp{#} characters. Upon 46400receiving a notification, the recipient sends no @samp{+} or @samp{-} 46401to acknowledge the notification's receipt or to report its corruption. 46402 46403Every notification's @var{data} begins with a name, which contains no 46404colon characters, followed by a colon character. 46405 46406Recipients should silently ignore corrupted notifications and 46407notifications they do not understand. Recipients should restart 46408timeout periods on receipt of a well-formed notification, whether or 46409not they understand it. 46410 46411Senders should only send the notifications described here when this 46412protocol description specifies that they are permitted. In the 46413future, we may extend the protocol to permit existing notifications in 46414new contexts; this rule helps older senders avoid confusing newer 46415recipients. 46416 46417(Older versions of @value{GDBN} ignore bytes received until they see 46418the @samp{$} byte that begins an ordinary packet, so new stubs may 46419transmit notifications without fear of confusing older clients. There 46420are no notifications defined for @value{GDBN} to send at the moment, but we 46421assume that most older stubs would ignore them, as well.) 46422 46423Each notification is comprised of three parts: 46424@table @samp 46425@item @var{name}:@var{event} 46426The notification packet is sent by the side that initiates the 46427exchange (currently, only the stub does that), with @var{event} 46428carrying the specific information about the notification, and 46429@var{name} specifying the name of the notification. 46430@item @var{ack} 46431The acknowledge sent by the other side, usually @value{GDBN}, to 46432acknowledge the exchange and request the event. 46433@end table 46434 46435The purpose of an asynchronous notification mechanism is to report to 46436@value{GDBN} that something interesting happened in the remote stub. 46437 46438The remote stub may send notification @var{name}:@var{event} 46439at any time, but @value{GDBN} acknowledges the notification when 46440appropriate. The notification event is pending before @value{GDBN} 46441acknowledges. Only one notification at a time may be pending; if 46442additional events occur before @value{GDBN} has acknowledged the 46443previous notification, they must be queued by the stub for later 46444synchronous transmission in response to @var{ack} packets from 46445@value{GDBN}. Because the notification mechanism is unreliable, 46446the stub is permitted to resend a notification if it believes 46447@value{GDBN} may not have received it. 46448 46449Specifically, notifications may appear when @value{GDBN} is not 46450otherwise reading input from the stub, or when @value{GDBN} is 46451expecting to read a normal synchronous response or a 46452@samp{+}/@samp{-} acknowledgment to a packet it has sent. 46453Notification packets are distinct from any other communication from 46454the stub so there is no ambiguity. 46455 46456After receiving a notification, @value{GDBN} shall acknowledge it by 46457sending a @var{ack} packet as a regular, synchronous request to the 46458stub. Such acknowledgment is not required to happen immediately, as 46459@value{GDBN} is permitted to send other, unrelated packets to the 46460stub first, which the stub should process normally. 46461 46462Upon receiving a @var{ack} packet, if the stub has other queued 46463events to report to @value{GDBN}, it shall respond by sending a 46464normal @var{event}. @value{GDBN} shall then send another @var{ack} 46465packet to solicit further responses; again, it is permitted to send 46466other, unrelated packets as well which the stub should process 46467normally. 46468 46469If the stub receives a @var{ack} packet and there are no additional 46470@var{event} to report, the stub shall return an @samp{OK} response. 46471At this point, @value{GDBN} has finished processing a notification 46472and the stub has completed sending any queued events. @value{GDBN} 46473won't accept any new notifications until the final @samp{OK} is 46474received . If further notification events occur, the stub shall send 46475a new notification, @value{GDBN} shall accept the notification, and 46476the process shall be repeated. 46477 46478The process of asynchronous notification can be illustrated by the 46479following example: 46480@smallexample 46481<- @code{%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;} 46482@code{...} 46483-> @code{vStopped} 46484<- @code{T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;} 46485-> @code{vStopped} 46486<- @code{T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;} 46487-> @code{vStopped} 46488<- @code{OK} 46489@end smallexample 46490 46491The following notifications are defined: 46492@multitable @columnfractions 0.12 0.12 0.38 0.38 46493 46494@item Notification 46495@tab Ack 46496@tab Event 46497@tab Description 46498 46499@item Stop 46500@tab vStopped 46501@tab @var{reply}. The @var{reply} has the form of a stop reply, as 46502described in @ref{Stop Reply Packets}. Refer to @ref{Remote Non-Stop}, 46503for information on how these notifications are acknowledged by 46504@value{GDBN}. 46505@tab Report an asynchronous stop event in non-stop mode. 46506 46507@end multitable 46508 46509@node Remote Non-Stop 46510@section Remote Protocol Support for Non-Stop Mode 46511 46512@value{GDBN}'s remote protocol supports non-stop debugging of 46513multi-threaded programs, as described in @ref{Non-Stop Mode}. If the stub 46514supports non-stop mode, it should report that to @value{GDBN} by including 46515@samp{QNonStop+} in its @samp{qSupported} response (@pxref{qSupported}). 46516 46517@value{GDBN} typically sends a @samp{QNonStop} packet only when 46518establishing a new connection with the stub. Entering non-stop mode 46519does not alter the state of any currently-running threads, but targets 46520must stop all threads in any already-attached processes when entering 46521all-stop mode. @value{GDBN} uses the @samp{?} packet as necessary to 46522probe the target state after a mode change. 46523 46524In non-stop mode, when an attached process encounters an event that 46525would otherwise be reported with a stop reply, it uses the 46526asynchronous notification mechanism (@pxref{Notification Packets}) to 46527inform @value{GDBN}. In contrast to all-stop mode, where all threads 46528in all processes are stopped when a stop reply is sent, in non-stop 46529mode only the thread reporting the stop event is stopped. That is, 46530when reporting a @samp{S} or @samp{T} response to indicate completion 46531of a step operation, hitting a breakpoint, or a fault, only the 46532affected thread is stopped; any other still-running threads continue 46533to run. When reporting a @samp{W} or @samp{X} response, all running 46534threads belonging to other attached processes continue to run. 46535 46536In non-stop mode, the target shall respond to the @samp{?} packet as 46537follows. First, any incomplete stop reply notification/@samp{vStopped} 46538sequence in progress is abandoned. The target must begin a new 46539sequence reporting stop events for all stopped threads, whether or not 46540it has previously reported those events to @value{GDBN}. The first 46541stop reply is sent as a synchronous reply to the @samp{?} packet, and 46542subsequent stop replies are sent as responses to @samp{vStopped} packets 46543using the mechanism described above. The target must not send 46544asynchronous stop reply notifications until the sequence is complete. 46545If all threads are running when the target receives the @samp{?} packet, 46546or if the target is not attached to any process, it shall respond 46547@samp{OK}. 46548 46549If the stub supports non-stop mode, it should also support the 46550@samp{swbreak} stop reason if software breakpoints are supported, and 46551the @samp{hwbreak} stop reason if hardware breakpoints are supported 46552(@pxref{swbreak stop reason}). This is because given the asynchronous 46553nature of non-stop mode, between the time a thread hits a breakpoint 46554and the time the event is finally processed by @value{GDBN}, the 46555breakpoint may have already been removed from the target. Due to 46556this, @value{GDBN} needs to be able to tell whether a trap stop was 46557caused by a delayed breakpoint event, which should be ignored, as 46558opposed to a random trap signal, which should be reported to the user. 46559Note the @samp{swbreak} feature implies that the target is responsible 46560for adjusting the PC when a software breakpoint triggers, if 46561necessary, such as on the x86 architecture. 46562 46563@node Packet Acknowledgment 46564@section Packet Acknowledgment 46565 46566@cindex acknowledgment, for @value{GDBN} remote 46567@cindex packet acknowledgment, for @value{GDBN} remote 46568By default, when either the host or the target machine receives a packet, 46569the first response expected is an acknowledgment: either @samp{+} (to indicate 46570the package was received correctly) or @samp{-} (to request retransmission). 46571This mechanism allows the @value{GDBN} remote protocol to operate over 46572unreliable transport mechanisms, such as a serial line. 46573 46574In cases where the transport mechanism is itself reliable (such as a pipe or 46575TCP connection), the @samp{+}/@samp{-} acknowledgments are redundant. 46576It may be desirable to disable them in that case to reduce communication 46577overhead, or for other reasons. This can be accomplished by means of the 46578@samp{QStartNoAckMode} packet; @pxref{QStartNoAckMode}. 46579 46580When in no-acknowledgment mode, neither the stub nor @value{GDBN} shall send or 46581expect @samp{+}/@samp{-} protocol acknowledgments. The packet 46582and response format still includes the normal checksum, as described in 46583@ref{Overview}, but the checksum may be ignored by the receiver. 46584 46585If the stub supports @samp{QStartNoAckMode} and prefers to operate in 46586no-acknowledgment mode, it should report that to @value{GDBN} 46587by including @samp{QStartNoAckMode+} in its response to @samp{qSupported}; 46588@pxref{qSupported}. 46589If @value{GDBN} also supports @samp{QStartNoAckMode} and it has not been 46590disabled via the @code{set remote noack-packet off} command 46591(@pxref{Remote Configuration}), 46592@value{GDBN} may then send a @samp{QStartNoAckMode} packet to the stub. 46593Only then may the stub actually turn off packet acknowledgments. 46594@value{GDBN} sends a final @samp{+} acknowledgment of the stub's @samp{OK} 46595response, which can be safely ignored by the stub. 46596 46597Note that @code{set remote noack-packet} command only affects negotiation 46598between @value{GDBN} and the stub when subsequent connections are made; 46599it does not affect the protocol acknowledgment state for any current 46600connection. 46601Since @samp{+}/@samp{-} acknowledgments are enabled by default when a 46602new connection is established, 46603there is also no protocol request to re-enable the acknowledgments 46604for the current connection, once disabled. 46605 46606@node Examples 46607@section Examples 46608 46609Example sequence of a target being re-started. Notice how the restart 46610does not get any direct output: 46611 46612@smallexample 46613-> @code{R00} 46614<- @code{+} 46615@emph{target restarts} 46616-> @code{?} 46617<- @code{+} 46618<- @code{T001:1234123412341234} 46619-> @code{+} 46620@end smallexample 46621 46622Example sequence of a target being stepped by a single instruction: 46623 46624@smallexample 46625-> @code{G1445@dots{}} 46626<- @code{+} 46627-> @code{s} 46628<- @code{+} 46629@emph{time passes} 46630<- @code{T001:1234123412341234} 46631-> @code{+} 46632-> @code{g} 46633<- @code{+} 46634<- @code{1455@dots{}} 46635-> @code{+} 46636@end smallexample 46637 46638@node File-I/O Remote Protocol Extension 46639@section File-I/O Remote Protocol Extension 46640@cindex File-I/O remote protocol extension 46641 46642@menu 46643* File-I/O Overview:: 46644* Protocol Basics:: 46645* The F Request Packet:: 46646* The F Reply Packet:: 46647* The Ctrl-C Message:: 46648* Console I/O:: 46649* List of Supported Calls:: 46650* Protocol-specific Representation of Datatypes:: 46651* Constants:: 46652* File-I/O Examples:: 46653@end menu 46654 46655@node File-I/O Overview 46656@subsection File-I/O Overview 46657@cindex file-i/o overview 46658 46659The @dfn{File I/O remote protocol extension} (short: File-I/O) allows the 46660target to use the host's file system and console I/O to perform various 46661system calls. System calls on the target system are translated into a 46662remote protocol packet to the host system, which then performs the needed 46663actions and returns a response packet to the target system. 46664This simulates file system operations even on targets that lack file systems. 46665 46666The protocol is defined to be independent of both the host and target systems. 46667It uses its own internal representation of datatypes and values. Both 46668@value{GDBN} and the target's @value{GDBN} stub are responsible for 46669translating the system-dependent value representations into the internal 46670protocol representations when data is transmitted. 46671 46672The communication is synchronous. A system call is possible only when 46673@value{GDBN} is waiting for a response from the @samp{C}, @samp{c}, @samp{S} 46674or @samp{s} packets. While @value{GDBN} handles the request for a system call, 46675the target is stopped to allow deterministic access to the target's 46676memory. Therefore File-I/O is not interruptible by target signals. On 46677the other hand, it is possible to interrupt File-I/O by a user interrupt 46678(@samp{Ctrl-C}) within @value{GDBN}. 46679 46680The target's request to perform a host system call does not finish 46681the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action. That means, 46682after finishing the system call, the target returns to continuing the 46683previous activity (continue, step). No additional continue or step 46684request from @value{GDBN} is required. 46685 46686@smallexample 46687(@value{GDBP}) continue 46688 <- target requests 'system call X' 46689 target is stopped, @value{GDBN} executes system call 46690 -> @value{GDBN} returns result 46691 ... target continues, @value{GDBN} returns to wait for the target 46692 <- target hits breakpoint and sends a Txx packet 46693@end smallexample 46694 46695The protocol only supports I/O on the console and to regular files on 46696the host file system. Character or block special devices, pipes, 46697named pipes, sockets or any other communication method on the host 46698system are not supported by this protocol. 46699 46700File I/O is not supported in non-stop mode. 46701 46702@node Protocol Basics 46703@subsection Protocol Basics 46704@cindex protocol basics, file-i/o 46705 46706The File-I/O protocol uses the @code{F} packet as the request as well 46707as reply packet. Since a File-I/O system call can only occur when 46708@value{GDBN} is waiting for a response from the continuing or stepping target, 46709the File-I/O request is a reply that @value{GDBN} has to expect as a result 46710of a previous @samp{C}, @samp{c}, @samp{S} or @samp{s} packet. 46711This @code{F} packet contains all information needed to allow @value{GDBN} 46712to call the appropriate host system call: 46713 46714@itemize @bullet 46715@item 46716A unique identifier for the requested system call. 46717 46718@item 46719All parameters to the system call. Pointers are given as addresses 46720in the target memory address space. Pointers to strings are given as 46721pointer/length pair. Numerical values are given as they are. 46722Numerical control flags are given in a protocol-specific representation. 46723 46724@end itemize 46725 46726At this point, @value{GDBN} has to perform the following actions. 46727 46728@itemize @bullet 46729@item 46730If the parameters include pointer values to data needed as input to a 46731system call, @value{GDBN} requests this data from the target with a 46732standard @code{m} packet request. This additional communication has to be 46733expected by the target implementation and is handled as any other @code{m} 46734packet. 46735 46736@item 46737@value{GDBN} translates all value from protocol representation to host 46738representation as needed. Datatypes are coerced into the host types. 46739 46740@item 46741@value{GDBN} calls the system call. 46742 46743@item 46744It then coerces datatypes back to protocol representation. 46745 46746@item 46747If the system call is expected to return data in buffer space specified 46748by pointer parameters to the call, the data is transmitted to the 46749target using a @code{M} or @code{X} packet. This packet has to be expected 46750by the target implementation and is handled as any other @code{M} or @code{X} 46751packet. 46752 46753@end itemize 46754 46755Eventually @value{GDBN} replies with another @code{F} packet which contains all 46756necessary information for the target to continue. This at least contains 46757 46758@itemize @bullet 46759@item 46760Return value. 46761 46762@item 46763@code{errno}, if has been changed by the system call. 46764 46765@item 46766``Ctrl-C'' flag. 46767 46768@end itemize 46769 46770After having done the needed type and value coercion, the target continues 46771the latest continue or step action. 46772 46773@node The F Request Packet 46774@subsection The @code{F} Request Packet 46775@cindex file-i/o request packet 46776@cindex @code{F} request packet 46777 46778The @code{F} request packet has the following format: 46779 46780@table @samp 46781@item F@var{call-id},@var{parameter@dots{}} 46782 46783@var{call-id} is the identifier to indicate the host system call to be called. 46784This is just the name of the function. 46785 46786@var{parameter@dots{}} are the parameters to the system call. 46787Parameters are hexadecimal integer values, either the actual values in case 46788of scalar datatypes, pointers to target buffer space in case of compound 46789datatypes and unspecified memory areas, or pointer/length pairs in case 46790of string parameters. These are appended to the @var{call-id} as a 46791comma-delimited list. All values are transmitted in ASCII 46792string representation, pointer/length pairs separated by a slash. 46793 46794@end table 46795 46796 46797 46798@node The F Reply Packet 46799@subsection The @code{F} Reply Packet 46800@cindex file-i/o reply packet 46801@cindex @code{F} reply packet 46802 46803The @code{F} reply packet has the following format: 46804 46805@table @samp 46806 46807@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call-specific attachment} 46808 46809@var{retcode} is the return code of the system call as hexadecimal value. 46810 46811@var{errno} is the @code{errno} set by the call, in protocol-specific 46812representation. 46813This parameter can be omitted if the call was successful. 46814 46815@var{Ctrl-C flag} is only sent if the user requested a break. In this 46816case, @var{errno} must be sent as well, even if the call was successful. 46817The @var{Ctrl-C flag} itself consists of the character @samp{C}: 46818 46819@smallexample 46820F0,0,C 46821@end smallexample 46822 46823@noindent 46824or, if the call was interrupted before the host call has been performed: 46825 46826@smallexample 46827F-1,4,C 46828@end smallexample 46829 46830@noindent 46831assuming 4 is the protocol-specific representation of @code{EINTR}. 46832 46833@end table 46834 46835 46836@node The Ctrl-C Message 46837@subsection The @samp{Ctrl-C} Message 46838@cindex ctrl-c message, in file-i/o protocol 46839 46840If the @samp{Ctrl-C} flag is set in the @value{GDBN} 46841reply packet (@pxref{The F Reply Packet}), 46842the target should behave as if it had 46843gotten a break message. The meaning for the target is ``system call 46844interrupted by @code{SIGINT}''. Consequently, the target should actually stop 46845(as with a break message) and return to @value{GDBN} with a @code{T02} 46846packet. 46847 46848It's important for the target to know in which 46849state the system call was interrupted. There are two possible cases: 46850 46851@itemize @bullet 46852@item 46853The system call hasn't been performed on the host yet. 46854 46855@item 46856The system call on the host has been finished. 46857 46858@end itemize 46859 46860These two states can be distinguished by the target by the value of the 46861returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system 46862call hasn't been performed. This is equivalent to the @code{EINTR} handling 46863on POSIX systems. In any other case, the target may presume that the 46864system call has been finished --- successfully or not --- and should behave 46865as if the break message arrived right after the system call. 46866 46867@value{GDBN} must behave reliably. If the system call has not been called 46868yet, @value{GDBN} may send the @code{F} reply immediately, setting @code{EINTR} as 46869@code{errno} in the packet. If the system call on the host has been finished 46870before the user requests a break, the full action must be finished by 46871@value{GDBN}. This requires sending @code{M} or @code{X} packets as necessary. 46872The @code{F} packet may only be sent when either nothing has happened 46873or the full action has been completed. 46874 46875@node Console I/O 46876@subsection Console I/O 46877@cindex console i/o as part of file-i/o 46878 46879By default and if not explicitly closed by the target system, the file 46880descriptors 0, 1 and 2 are connected to the @value{GDBN} console. Output 46881on the @value{GDBN} console is handled as any other file output operation 46882(@code{write(1, @dots{})} or @code{write(2, @dots{})}). Console input is handled 46883by @value{GDBN} so that after the target read request from file descriptor 468840 all following typing is buffered until either one of the following 46885conditions is met: 46886 46887@itemize @bullet 46888@item 46889The user types @kbd{Ctrl-c}. The behaviour is as explained above, and the 46890@code{read} 46891system call is treated as finished. 46892 46893@item 46894The user presses @key{RET}. This is treated as end of input with a trailing 46895newline. 46896 46897@item 46898The user types @kbd{Ctrl-d}. This is treated as end of input. No trailing 46899character (neither newline nor @samp{Ctrl-D}) is appended to the input. 46900 46901@end itemize 46902 46903If the user has typed more characters than fit in the buffer given to 46904the @code{read} call, the trailing characters are buffered in @value{GDBN} until 46905either another @code{read(0, @dots{})} is requested by the target, or debugging 46906is stopped at the user's request. 46907 46908 46909@node List of Supported Calls 46910@subsection List of Supported Calls 46911@cindex list of supported file-i/o calls 46912 46913@menu 46914* open:: 46915* close:: 46916* read:: 46917* write:: 46918* lseek:: 46919* rename:: 46920* unlink:: 46921* stat/fstat:: 46922* gettimeofday:: 46923* isatty:: 46924* system:: 46925@end menu 46926 46927@node open 46928@unnumberedsubsubsec open 46929@cindex open, file-i/o system call 46930 46931@table @asis 46932@item Synopsis: 46933@smallexample 46934int open(const char *pathname, int flags); 46935int open(const char *pathname, int flags, mode_t mode); 46936@end smallexample 46937 46938@item Request: 46939@samp{Fopen,@var{pathptr}/@var{len},@var{flags},@var{mode}} 46940 46941@noindent 46942@var{flags} is the bitwise @code{OR} of the following values: 46943 46944@table @code 46945@item O_CREAT 46946If the file does not exist it will be created. The host 46947rules apply as far as file ownership and time stamps 46948are concerned. 46949 46950@item O_EXCL 46951When used with @code{O_CREAT}, if the file already exists it is 46952an error and open() fails. 46953 46954@item O_TRUNC 46955If the file already exists and the open mode allows 46956writing (@code{O_RDWR} or @code{O_WRONLY} is given) it will be 46957truncated to zero length. 46958 46959@item O_APPEND 46960The file is opened in append mode. 46961 46962@item O_RDONLY 46963The file is opened for reading only. 46964 46965@item O_WRONLY 46966The file is opened for writing only. 46967 46968@item O_RDWR 46969The file is opened for reading and writing. 46970@end table 46971 46972@noindent 46973Other bits are silently ignored. 46974 46975 46976@noindent 46977@var{mode} is the bitwise @code{OR} of the following values: 46978 46979@table @code 46980@item S_IRUSR 46981User has read permission. 46982 46983@item S_IWUSR 46984User has write permission. 46985 46986@item S_IRGRP 46987Group has read permission. 46988 46989@item S_IWGRP 46990Group has write permission. 46991 46992@item S_IROTH 46993Others have read permission. 46994 46995@item S_IWOTH 46996Others have write permission. 46997@end table 46998 46999@noindent 47000Other bits are silently ignored. 47001 47002 47003@item Return value: 47004@code{open} returns the new file descriptor or -1 if an error 47005occurred. 47006 47007@item Errors: 47008 47009@table @code 47010@item EEXIST 47011@var{pathname} already exists and @code{O_CREAT} and @code{O_EXCL} were used. 47012 47013@item EISDIR 47014@var{pathname} refers to a directory. 47015 47016@item EACCES 47017The requested access is not allowed. 47018 47019@item ENAMETOOLONG 47020@var{pathname} was too long. 47021 47022@item ENOENT 47023A directory component in @var{pathname} does not exist. 47024 47025@item ENODEV 47026@var{pathname} refers to a device, pipe, named pipe or socket. 47027 47028@item EROFS 47029@var{pathname} refers to a file on a read-only filesystem and 47030write access was requested. 47031 47032@item EFAULT 47033@var{pathname} is an invalid pointer value. 47034 47035@item ENOSPC 47036No space on device to create the file. 47037 47038@item EMFILE 47039The process already has the maximum number of files open. 47040 47041@item ENFILE 47042The limit on the total number of files open on the system 47043has been reached. 47044 47045@item EINTR 47046The call was interrupted by the user. 47047@end table 47048 47049@end table 47050 47051@node close 47052@unnumberedsubsubsec close 47053@cindex close, file-i/o system call 47054 47055@table @asis 47056@item Synopsis: 47057@smallexample 47058int close(int fd); 47059@end smallexample 47060 47061@item Request: 47062@samp{Fclose,@var{fd}} 47063 47064@item Return value: 47065@code{close} returns zero on success, or -1 if an error occurred. 47066 47067@item Errors: 47068 47069@table @code 47070@item EBADF 47071@var{fd} isn't a valid open file descriptor. 47072 47073@item EINTR 47074The call was interrupted by the user. 47075@end table 47076 47077@end table 47078 47079@node read 47080@unnumberedsubsubsec read 47081@cindex read, file-i/o system call 47082 47083@table @asis 47084@item Synopsis: 47085@smallexample 47086int read(int fd, void *buf, unsigned int count); 47087@end smallexample 47088 47089@item Request: 47090@samp{Fread,@var{fd},@var{bufptr},@var{count}} 47091 47092@item Return value: 47093On success, the number of bytes read is returned. 47094Zero indicates end of file. If count is zero, read 47095returns zero as well. On error, -1 is returned. 47096 47097@item Errors: 47098 47099@table @code 47100@item EBADF 47101@var{fd} is not a valid file descriptor or is not open for 47102reading. 47103 47104@item EFAULT 47105@var{bufptr} is an invalid pointer value. 47106 47107@item EINTR 47108The call was interrupted by the user. 47109@end table 47110 47111@end table 47112 47113@node write 47114@unnumberedsubsubsec write 47115@cindex write, file-i/o system call 47116 47117@table @asis 47118@item Synopsis: 47119@smallexample 47120int write(int fd, const void *buf, unsigned int count); 47121@end smallexample 47122 47123@item Request: 47124@samp{Fwrite,@var{fd},@var{bufptr},@var{count}} 47125 47126@item Return value: 47127On success, the number of bytes written are returned. 47128Zero indicates nothing was written. On error, -1 47129is returned. 47130 47131@item Errors: 47132 47133@table @code 47134@item EBADF 47135@var{fd} is not a valid file descriptor or is not open for 47136writing. 47137 47138@item EFAULT 47139@var{bufptr} is an invalid pointer value. 47140 47141@item EFBIG 47142An attempt was made to write a file that exceeds the 47143host-specific maximum file size allowed. 47144 47145@item ENOSPC 47146No space on device to write the data. 47147 47148@item EINTR 47149The call was interrupted by the user. 47150@end table 47151 47152@end table 47153 47154@node lseek 47155@unnumberedsubsubsec lseek 47156@cindex lseek, file-i/o system call 47157 47158@table @asis 47159@item Synopsis: 47160@smallexample 47161long lseek (int fd, long offset, int flag); 47162@end smallexample 47163 47164@item Request: 47165@samp{Flseek,@var{fd},@var{offset},@var{flag}} 47166 47167@var{flag} is one of: 47168 47169@table @code 47170@item SEEK_SET 47171The offset is set to @var{offset} bytes. 47172 47173@item SEEK_CUR 47174The offset is set to its current location plus @var{offset} 47175bytes. 47176 47177@item SEEK_END 47178The offset is set to the size of the file plus @var{offset} 47179bytes. 47180@end table 47181 47182@item Return value: 47183On success, the resulting unsigned offset in bytes from 47184the beginning of the file is returned. Otherwise, a 47185value of -1 is returned. 47186 47187@item Errors: 47188 47189@table @code 47190@item EBADF 47191@var{fd} is not a valid open file descriptor. 47192 47193@item ESPIPE 47194@var{fd} is associated with the @value{GDBN} console. 47195 47196@item EINVAL 47197@var{flag} is not a proper value. 47198 47199@item EINTR 47200The call was interrupted by the user. 47201@end table 47202 47203@end table 47204 47205@node rename 47206@unnumberedsubsubsec rename 47207@cindex rename, file-i/o system call 47208 47209@table @asis 47210@item Synopsis: 47211@smallexample 47212int rename(const char *oldpath, const char *newpath); 47213@end smallexample 47214 47215@item Request: 47216@samp{Frename,@var{oldpathptr}/@var{len},@var{newpathptr}/@var{len}} 47217 47218@item Return value: 47219On success, zero is returned. On error, -1 is returned. 47220 47221@item Errors: 47222 47223@table @code 47224@item EISDIR 47225@var{newpath} is an existing directory, but @var{oldpath} is not a 47226directory. 47227 47228@item EEXIST 47229@var{newpath} is a non-empty directory. 47230 47231@item EBUSY 47232@var{oldpath} or @var{newpath} is a directory that is in use by some 47233process. 47234 47235@item EINVAL 47236An attempt was made to make a directory a subdirectory 47237of itself. 47238 47239@item ENOTDIR 47240A component used as a directory in @var{oldpath} or new 47241path is not a directory. Or @var{oldpath} is a directory 47242and @var{newpath} exists but is not a directory. 47243 47244@item EFAULT 47245@var{oldpathptr} or @var{newpathptr} are invalid pointer values. 47246 47247@item EACCES 47248No access to the file or the path of the file. 47249 47250@item ENAMETOOLONG 47251 47252@var{oldpath} or @var{newpath} was too long. 47253 47254@item ENOENT 47255A directory component in @var{oldpath} or @var{newpath} does not exist. 47256 47257@item EROFS 47258The file is on a read-only filesystem. 47259 47260@item ENOSPC 47261The device containing the file has no room for the new 47262directory entry. 47263 47264@item EINTR 47265The call was interrupted by the user. 47266@end table 47267 47268@end table 47269 47270@node unlink 47271@unnumberedsubsubsec unlink 47272@cindex unlink, file-i/o system call 47273 47274@table @asis 47275@item Synopsis: 47276@smallexample 47277int unlink(const char *pathname); 47278@end smallexample 47279 47280@item Request: 47281@samp{Funlink,@var{pathnameptr}/@var{len}} 47282 47283@item Return value: 47284On success, zero is returned. On error, -1 is returned. 47285 47286@item Errors: 47287 47288@table @code 47289@item EACCES 47290No access to the file or the path of the file. 47291 47292@item EPERM 47293The system does not allow unlinking of directories. 47294 47295@item EBUSY 47296The file @var{pathname} cannot be unlinked because it's 47297being used by another process. 47298 47299@item EFAULT 47300@var{pathnameptr} is an invalid pointer value. 47301 47302@item ENAMETOOLONG 47303@var{pathname} was too long. 47304 47305@item ENOENT 47306A directory component in @var{pathname} does not exist. 47307 47308@item ENOTDIR 47309A component of the path is not a directory. 47310 47311@item EROFS 47312The file is on a read-only filesystem. 47313 47314@item EINTR 47315The call was interrupted by the user. 47316@end table 47317 47318@end table 47319 47320@node stat/fstat 47321@unnumberedsubsubsec stat/fstat 47322@cindex fstat, file-i/o system call 47323@cindex stat, file-i/o system call 47324 47325@table @asis 47326@item Synopsis: 47327@smallexample 47328int stat(const char *pathname, struct stat *buf); 47329int fstat(int fd, struct stat *buf); 47330@end smallexample 47331 47332@item Request: 47333@samp{Fstat,@var{pathnameptr}/@var{len},@var{bufptr}}@* 47334@samp{Ffstat,@var{fd},@var{bufptr}} 47335 47336@item Return value: 47337On success, zero is returned. On error, -1 is returned. 47338 47339@item Errors: 47340 47341@table @code 47342@item EBADF 47343@var{fd} is not a valid open file. 47344 47345@item ENOENT 47346A directory component in @var{pathname} does not exist or the 47347path is an empty string. 47348 47349@item ENOTDIR 47350A component of the path is not a directory. 47351 47352@item EFAULT 47353@var{pathnameptr} is an invalid pointer value. 47354 47355@item EACCES 47356No access to the file or the path of the file. 47357 47358@item ENAMETOOLONG 47359@var{pathname} was too long. 47360 47361@item EINTR 47362The call was interrupted by the user. 47363@end table 47364 47365@end table 47366 47367@node gettimeofday 47368@unnumberedsubsubsec gettimeofday 47369@cindex gettimeofday, file-i/o system call 47370 47371@table @asis 47372@item Synopsis: 47373@smallexample 47374int gettimeofday(struct timeval *tv, void *tz); 47375@end smallexample 47376 47377@item Request: 47378@samp{Fgettimeofday,@var{tvptr},@var{tzptr}} 47379 47380@item Return value: 47381On success, 0 is returned, -1 otherwise. 47382 47383@item Errors: 47384 47385@table @code 47386@item EINVAL 47387@var{tz} is a non-NULL pointer. 47388 47389@item EFAULT 47390@var{tvptr} and/or @var{tzptr} is an invalid pointer value. 47391@end table 47392 47393@end table 47394 47395@node isatty 47396@unnumberedsubsubsec isatty 47397@cindex isatty, file-i/o system call 47398 47399@table @asis 47400@item Synopsis: 47401@smallexample 47402int isatty(int fd); 47403@end smallexample 47404 47405@item Request: 47406@samp{Fisatty,@var{fd}} 47407 47408@item Return value: 47409Returns 1 if @var{fd} refers to the @value{GDBN} console, 0 otherwise. 47410 47411@item Errors: 47412 47413@table @code 47414@item EINTR 47415The call was interrupted by the user. 47416@end table 47417 47418@end table 47419 47420Note that the @code{isatty} call is treated as a special case: it returns 474211 to the target if the file descriptor is attached 47422to the @value{GDBN} console, 0 otherwise. Implementing through system calls 47423would require implementing @code{ioctl} and would be more complex than 47424needed. 47425 47426 47427@node system 47428@unnumberedsubsubsec system 47429@cindex system, file-i/o system call 47430 47431@table @asis 47432@item Synopsis: 47433@smallexample 47434int system(const char *command); 47435@end smallexample 47436 47437@item Request: 47438@samp{Fsystem,@var{commandptr}/@var{len}} 47439 47440@item Return value: 47441If @var{len} is zero, the return value indicates whether a shell is 47442available. A zero return value indicates a shell is not available. 47443For non-zero @var{len}, the value returned is -1 on error and the 47444return status of the command otherwise. Only the exit status of the 47445command is returned, which is extracted from the host's @code{system} 47446return value by calling @code{WEXITSTATUS(retval)}. In case 47447@file{/bin/sh} could not be executed, 127 is returned. 47448 47449@item Errors: 47450 47451@table @code 47452@item EINTR 47453The call was interrupted by the user. 47454@end table 47455 47456@end table 47457 47458@value{GDBN} takes over the full task of calling the necessary host calls 47459to perform the @code{system} call. The return value of @code{system} on 47460the host is simplified before it's returned 47461to the target. Any termination signal information from the child process 47462is discarded, and the return value consists 47463entirely of the exit status of the called command. 47464 47465Due to security concerns, the @code{system} call is by default refused 47466by @value{GDBN}. The user has to allow this call explicitly with the 47467@code{set remote system-call-allowed 1} command. 47468 47469@table @code 47470@item set remote system-call-allowed 47471@kindex set remote system-call-allowed 47472Control whether to allow the @code{system} calls in the File I/O 47473protocol for the remote target. The default is zero (disabled). 47474 47475@item show remote system-call-allowed 47476@kindex show remote system-call-allowed 47477Show whether the @code{system} calls are allowed in the File I/O 47478protocol. 47479@end table 47480 47481@node Protocol-specific Representation of Datatypes 47482@subsection Protocol-specific Representation of Datatypes 47483@cindex protocol-specific representation of datatypes, in file-i/o protocol 47484 47485@menu 47486* Integral Datatypes:: 47487* Pointer Values:: 47488* Memory Transfer:: 47489* struct stat:: 47490* struct timeval:: 47491@end menu 47492 47493@node Integral Datatypes 47494@unnumberedsubsubsec Integral Datatypes 47495@cindex integral datatypes, in file-i/o protocol 47496 47497The integral datatypes used in the system calls are @code{int}, 47498@code{unsigned int}, @code{long}, @code{unsigned long}, 47499@code{mode_t}, and @code{time_t}. 47500 47501@code{int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are 47502implemented as 32 bit values in this protocol. 47503 47504@code{long} and @code{unsigned long} are implemented as 64 bit types. 47505 47506@xref{Limits}, for corresponding MIN and MAX values (similar to those 47507in @file{limits.h}) to allow range checking on host and target. 47508 47509@code{time_t} datatypes are defined as seconds since the Epoch. 47510 47511All integral datatypes transferred as part of a memory read or write of a 47512structured datatype e.g.@: a @code{struct stat} have to be given in big endian 47513byte order. 47514 47515@node Pointer Values 47516@unnumberedsubsubsec Pointer Values 47517@cindex pointer values, in file-i/o protocol 47518 47519Pointers to target data are transmitted as they are. An exception 47520is made for pointers to buffers for which the length isn't 47521transmitted as part of the function call, namely strings. Strings 47522are transmitted as a pointer/length pair, both as hex values, e.g.@: 47523 47524@smallexample 47525@code{1aaf/12} 47526@end smallexample 47527 47528@noindent 47529which is a pointer to data of length 18 bytes at position 0x1aaf. 47530The length is defined as the full string length in bytes, including 47531the trailing null byte. For example, the string @code{"hello world"} 47532at address 0x123456 is transmitted as 47533 47534@smallexample 47535@code{123456/d} 47536@end smallexample 47537 47538@node Memory Transfer 47539@unnumberedsubsubsec Memory Transfer 47540@cindex memory transfer, in file-i/o protocol 47541 47542Structured data which is transferred using a memory read or write (for 47543example, a @code{struct stat}) is expected to be in a protocol-specific format 47544with all scalar multibyte datatypes being big endian. Translation to 47545this representation needs to be done both by the target before the @code{F} 47546packet is sent, and by @value{GDBN} before 47547it transfers memory to the target. Transferred pointers to structured 47548data should point to the already-coerced data at any time. 47549 47550 47551@node struct stat 47552@unnumberedsubsubsec struct stat 47553@cindex struct stat, in file-i/o protocol 47554 47555The buffer of type @code{struct stat} used by the target and @value{GDBN} 47556is defined as follows: 47557 47558@smallexample 47559struct stat @{ 47560 unsigned int st_dev; /* device */ 47561 unsigned int st_ino; /* inode */ 47562 mode_t st_mode; /* protection */ 47563 unsigned int st_nlink; /* number of hard links */ 47564 unsigned int st_uid; /* user ID of owner */ 47565 unsigned int st_gid; /* group ID of owner */ 47566 unsigned int st_rdev; /* device type (if inode device) */ 47567 unsigned long st_size; /* total size, in bytes */ 47568 unsigned long st_blksize; /* blocksize for filesystem I/O */ 47569 unsigned long st_blocks; /* number of blocks allocated */ 47570 time_t st_atime; /* time of last access */ 47571 time_t st_mtime; /* time of last modification */ 47572 time_t st_ctime; /* time of last change */ 47573@}; 47574@end smallexample 47575 47576The integral datatypes conform to the definitions given in the 47577appropriate section (see @ref{Integral Datatypes}, for details) so this 47578structure is of size 64 bytes. 47579 47580The values of several fields have a restricted meaning and/or 47581range of values. 47582 47583@table @code 47584 47585@item st_dev 47586A value of 0 represents a file, 1 the console. 47587 47588@item st_ino 47589No valid meaning for the target. Transmitted unchanged. 47590 47591@item st_mode 47592Valid mode bits are described in @ref{Constants}. Any other 47593bits have currently no meaning for the target. 47594 47595@item st_uid 47596@itemx st_gid 47597@itemx st_rdev 47598No valid meaning for the target. Transmitted unchanged. 47599 47600@item st_atime 47601@itemx st_mtime 47602@itemx st_ctime 47603These values have a host and file system dependent 47604accuracy. Especially on Windows hosts, the file system may not 47605support exact timing values. 47606@end table 47607 47608The target gets a @code{struct stat} of the above representation and is 47609responsible for coercing it to the target representation before 47610continuing. 47611 47612Note that due to size differences between the host, target, and protocol 47613representations of @code{struct stat} members, these members could eventually 47614get truncated on the target. 47615 47616@node struct timeval 47617@unnumberedsubsubsec struct timeval 47618@cindex struct timeval, in file-i/o protocol 47619 47620The buffer of type @code{struct timeval} used by the File-I/O protocol 47621is defined as follows: 47622 47623@smallexample 47624struct timeval @{ 47625 time_t tv_sec; /* second */ 47626 long tv_usec; /* microsecond */ 47627@}; 47628@end smallexample 47629 47630The integral datatypes conform to the definitions given in the 47631appropriate section (see @ref{Integral Datatypes}, for details) so this 47632structure is of size 8 bytes. 47633 47634@node Constants 47635@subsection Constants 47636@cindex constants, in file-i/o protocol 47637 47638The following values are used for the constants inside of the 47639protocol. @value{GDBN} and target are responsible for translating these 47640values before and after the call as needed. 47641 47642@menu 47643* Open Flags:: 47644* mode_t Values:: 47645* Errno Values:: 47646* Lseek Flags:: 47647* Limits:: 47648@end menu 47649 47650@node Open Flags 47651@unnumberedsubsubsec Open Flags 47652@cindex open flags, in file-i/o protocol 47653 47654All values are given in hexadecimal representation. 47655 47656@smallexample 47657 O_RDONLY 0x0 47658 O_WRONLY 0x1 47659 O_RDWR 0x2 47660 O_APPEND 0x8 47661 O_CREAT 0x200 47662 O_TRUNC 0x400 47663 O_EXCL 0x800 47664@end smallexample 47665 47666@node mode_t Values 47667@unnumberedsubsubsec mode_t Values 47668@cindex mode_t values, in file-i/o protocol 47669 47670All values are given in octal representation. 47671 47672@smallexample 47673 S_IFREG 0100000 47674 S_IFDIR 040000 47675 S_IRUSR 0400 47676 S_IWUSR 0200 47677 S_IXUSR 0100 47678 S_IRGRP 040 47679 S_IWGRP 020 47680 S_IXGRP 010 47681 S_IROTH 04 47682 S_IWOTH 02 47683 S_IXOTH 01 47684@end smallexample 47685 47686@node Errno Values 47687@unnumberedsubsubsec Errno Values 47688@cindex errno values, in file-i/o protocol 47689 47690All values are given in decimal representation. 47691 47692@smallexample 47693 EPERM 1 47694 ENOENT 2 47695 EINTR 4 47696 EBADF 9 47697 EACCES 13 47698 EFAULT 14 47699 EBUSY 16 47700 EEXIST 17 47701 ENODEV 19 47702 ENOTDIR 20 47703 EISDIR 21 47704 EINVAL 22 47705 ENFILE 23 47706 EMFILE 24 47707 EFBIG 27 47708 ENOSPC 28 47709 ESPIPE 29 47710 EROFS 30 47711 ENAMETOOLONG 91 47712 EUNKNOWN 9999 47713@end smallexample 47714 47715 @code{EUNKNOWN} is used as a fallback error value if a host system returns 47716 any error value not in the list of supported error numbers. 47717 47718@node Lseek Flags 47719@unnumberedsubsubsec Lseek Flags 47720@cindex lseek flags, in file-i/o protocol 47721 47722@smallexample 47723 SEEK_SET 0 47724 SEEK_CUR 1 47725 SEEK_END 2 47726@end smallexample 47727 47728@node Limits 47729@unnumberedsubsubsec Limits 47730@cindex limits, in file-i/o protocol 47731 47732All values are given in decimal representation. 47733 47734@smallexample 47735 INT_MIN -2147483648 47736 INT_MAX 2147483647 47737 UINT_MAX 4294967295 47738 LONG_MIN -9223372036854775808 47739 LONG_MAX 9223372036854775807 47740 ULONG_MAX 18446744073709551615 47741@end smallexample 47742 47743@node File-I/O Examples 47744@subsection File-I/O Examples 47745@cindex file-i/o examples 47746 47747Example sequence of a write call, file descriptor 3, buffer is at target 47748address 0x1234, 6 bytes should be written: 47749 47750@smallexample 47751<- @code{Fwrite,3,1234,6} 47752@emph{request memory read from target} 47753-> @code{m1234,6} 47754<- XXXXXX 47755@emph{return "6 bytes written"} 47756-> @code{F6} 47757@end smallexample 47758 47759Example sequence of a read call, file descriptor 3, buffer is at target 47760address 0x1234, 6 bytes should be read: 47761 47762@smallexample 47763<- @code{Fread,3,1234,6} 47764@emph{request memory write to target} 47765-> @code{X1234,6:XXXXXX} 47766@emph{return "6 bytes read"} 47767-> @code{F6} 47768@end smallexample 47769 47770Example sequence of a read call, call fails on the host due to invalid 47771file descriptor (@code{EBADF}): 47772 47773@smallexample 47774<- @code{Fread,3,1234,6} 47775-> @code{F-1,9} 47776@end smallexample 47777 47778Example sequence of a read call, user presses @kbd{Ctrl-c} before syscall on 47779host is called: 47780 47781@smallexample 47782<- @code{Fread,3,1234,6} 47783-> @code{F-1,4,C} 47784<- @code{T02} 47785@end smallexample 47786 47787Example sequence of a read call, user presses @kbd{Ctrl-c} after syscall on 47788host is called: 47789 47790@smallexample 47791<- @code{Fread,3,1234,6} 47792-> @code{X1234,6:XXXXXX} 47793<- @code{T02} 47794@end smallexample 47795 47796@node Library List Format 47797@section Library List Format 47798@cindex library list format, remote protocol 47799 47800On some platforms, a dynamic loader (e.g.@: @file{ld.so}) runs in the 47801same process as your application to manage libraries. In this case, 47802@value{GDBN} can use the loader's symbol table and normal memory 47803operations to maintain a list of shared libraries. On other 47804platforms, the operating system manages loaded libraries. 47805@value{GDBN} can not retrieve the list of currently loaded libraries 47806through memory operations, so it uses the @samp{qXfer:libraries:read} 47807packet (@pxref{qXfer library list read}) instead. The remote stub 47808queries the target's operating system and reports which libraries 47809are loaded. 47810 47811The @samp{qXfer:libraries:read} packet returns an XML document which 47812lists loaded libraries and their offsets. Each library has an 47813associated name and one or more segment or section base addresses, 47814which report where the library was loaded in memory. 47815 47816For the common case of libraries that are fully linked binaries, the 47817library should have a list of segments. If the target supports 47818dynamic linking of a relocatable object file, its library XML element 47819should instead include a list of allocated sections. The segment or 47820section bases are start addresses, not relocation offsets; they do not 47821depend on the library's link-time base addresses. 47822 47823@value{GDBN} must be linked with the Expat library to support XML 47824library lists. @xref{Expat}. 47825 47826A simple memory map, with one loaded library relocated by a single 47827offset, looks like this: 47828 47829@smallexample 47830<library-list> 47831 <library name="/lib/libc.so.6"> 47832 <segment address="0x10000000"/> 47833 </library> 47834</library-list> 47835@end smallexample 47836 47837Another simple memory map, with one loaded library with three 47838allocated sections (.text, .data, .bss), looks like this: 47839 47840@smallexample 47841<library-list> 47842 <library name="sharedlib.o"> 47843 <section address="0x10000000"/> 47844 <section address="0x20000000"/> 47845 <section address="0x30000000"/> 47846 </library> 47847</library-list> 47848@end smallexample 47849 47850The format of a library list is described by this DTD: 47851 47852@smallexample 47853<!-- library-list: Root element with versioning --> 47854<!ELEMENT library-list (library)*> 47855<!ATTLIST library-list version CDATA #FIXED "1.0"> 47856<!ELEMENT library (segment*, section*)> 47857<!ATTLIST library name CDATA #REQUIRED> 47858<!ELEMENT segment EMPTY> 47859<!ATTLIST segment address CDATA #REQUIRED> 47860<!ELEMENT section EMPTY> 47861<!ATTLIST section address CDATA #REQUIRED> 47862@end smallexample 47863 47864In addition, segments and section descriptors cannot be mixed within a 47865single library element, and you must supply at least one segment or 47866section for each library. 47867 47868@node Library List Format for SVR4 Targets 47869@section Library List Format for SVR4 Targets 47870@cindex library list format, remote protocol 47871 47872On SVR4 platforms @value{GDBN} can use the symbol table of a dynamic loader 47873(e.g.@: @file{ld.so}) and normal memory operations to maintain a list of 47874shared libraries. Still a special library list provided by this packet is 47875more efficient for the @value{GDBN} remote protocol. 47876 47877The @samp{qXfer:libraries-svr4:read} packet returns an XML document which lists 47878loaded libraries and their SVR4 linker parameters. For each library on SVR4 47879target, the following parameters are reported: 47880 47881@itemize @minus 47882@item 47883@code{name}, the absolute file name from the @code{l_name} field of 47884@code{struct link_map}. 47885@item 47886@code{lm} with address of @code{struct link_map} used for TLS 47887(Thread Local Storage) access. 47888@item 47889@code{l_addr}, the displacement as read from the field @code{l_addr} of 47890@code{struct link_map}. For prelinked libraries this is not an absolute 47891memory address. It is a displacement of absolute memory address against 47892address the file was prelinked to during the library load. 47893@item 47894@code{l_ld}, which is memory address of the @code{PT_DYNAMIC} segment 47895@item 47896@code{lmid}, which is an identifier for a linker namespace, such as 47897the memory address of the @code{r_debug} object that contains this 47898namespace's load map or the namespace identifier returned by 47899@code{dlinfo (3)}. 47900@end itemize 47901 47902Additionally the single @code{main-lm} attribute specifies address of 47903@code{struct link_map} used for the main executable. This parameter is used 47904for TLS access and its presence is optional. 47905 47906@value{GDBN} must be linked with the Expat library to support XML 47907SVR4 library lists. @xref{Expat}. 47908 47909A simple memory map, with two loaded libraries (which do not use prelink), 47910looks like this: 47911 47912@smallexample 47913<library-list-svr4 version="1.0" main-lm="0xe4f8f8"> 47914 <library name="/lib/ld-linux.so.2" lm="0xe4f51c" l_addr="0xe2d000" 47915 l_ld="0xe4eefc" lmid="0xfffe0"/> 47916 <library name="/lib/libc.so.6" lm="0xe4fbe8" l_addr="0x154000" 47917 l_ld="0x152350" lmid="0xfffe0"/> 47918</library-list-svr> 47919@end smallexample 47920 47921The format of an SVR4 library list is described by this DTD: 47922 47923@smallexample 47924<!-- library-list-svr4: Root element with versioning --> 47925<!ELEMENT library-list-svr4 (library)*> 47926<!ATTLIST library-list-svr4 version CDATA #FIXED "1.0"> 47927<!ATTLIST library-list-svr4 main-lm CDATA #IMPLIED> 47928<!ELEMENT library EMPTY> 47929<!ATTLIST library name CDATA #REQUIRED> 47930<!ATTLIST library lm CDATA #REQUIRED> 47931<!ATTLIST library l_addr CDATA #REQUIRED> 47932<!ATTLIST library l_ld CDATA #REQUIRED> 47933<!ATTLIST library lmid CDATA #IMPLIED> 47934@end smallexample 47935 47936@node Memory Map Format 47937@section Memory Map Format 47938@cindex memory map format 47939 47940To be able to write into flash memory, @value{GDBN} needs to obtain a 47941memory map from the target. This section describes the format of the 47942memory map. 47943 47944The memory map is obtained using the @samp{qXfer:memory-map:read} 47945(@pxref{qXfer memory map read}) packet and is an XML document that 47946lists memory regions. 47947 47948@value{GDBN} must be linked with the Expat library to support XML 47949memory maps. @xref{Expat}. 47950 47951The top-level structure of the document is shown below: 47952 47953@smallexample 47954<?xml version="1.0"?> 47955<!DOCTYPE memory-map 47956 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN" 47957 "http://sourceware.org/gdb/gdb-memory-map.dtd"> 47958<memory-map> 47959 region... 47960</memory-map> 47961@end smallexample 47962 47963Each region can be either: 47964 47965@itemize 47966 47967@item 47968A region of RAM starting at @var{addr} and extending for @var{length} 47969bytes from there: 47970 47971@smallexample 47972<memory type="ram" start="@var{addr}" length="@var{length}"/> 47973@end smallexample 47974 47975 47976@item 47977A region of read-only memory: 47978 47979@smallexample 47980<memory type="rom" start="@var{addr}" length="@var{length}"/> 47981@end smallexample 47982 47983 47984@item 47985A region of flash memory, with erasure blocks @var{blocksize} 47986bytes in length: 47987 47988@smallexample 47989<memory type="flash" start="@var{addr}" length="@var{length}"> 47990 <property name="blocksize">@var{blocksize}</property> 47991</memory> 47992@end smallexample 47993 47994@end itemize 47995 47996Regions must not overlap. @value{GDBN} assumes that areas of memory not covered 47997by the memory map are RAM, and uses the ordinary @samp{M} and @samp{X} 47998packets to write to addresses in such ranges. 47999 48000The formal DTD for memory map format is given below: 48001 48002@smallexample 48003<!-- ................................................... --> 48004<!-- Memory Map XML DTD ................................ --> 48005<!-- File: memory-map.dtd .............................. --> 48006<!-- .................................... .............. --> 48007<!-- memory-map.dtd --> 48008<!-- memory-map: Root element with versioning --> 48009<!ELEMENT memory-map (memory)*> 48010<!ATTLIST memory-map version CDATA #FIXED "1.0.0"> 48011<!ELEMENT memory (property)*> 48012<!-- memory: Specifies a memory region, 48013 and its type, or device. --> 48014<!ATTLIST memory type (ram|rom|flash) #REQUIRED 48015 start CDATA #REQUIRED 48016 length CDATA #REQUIRED> 48017<!-- property: Generic attribute tag --> 48018<!ELEMENT property (#PCDATA | property)*> 48019<!ATTLIST property name (blocksize) #REQUIRED> 48020@end smallexample 48021 48022@node Thread List Format 48023@section Thread List Format 48024@cindex thread list format 48025 48026To efficiently update the list of threads and their attributes, 48027@value{GDBN} issues the @samp{qXfer:threads:read} packet 48028(@pxref{qXfer threads read}) and obtains the XML document with 48029the following structure: 48030 48031@smallexample 48032<?xml version="1.0"?> 48033<threads> 48034 <thread id="id" core="0" name="name" handle="1a2b3c"> 48035 ... description ... 48036 </thread> 48037</threads> 48038@end smallexample 48039 48040Each @samp{thread} element must have the @samp{id} attribute that 48041identifies the thread (@pxref{thread-id syntax}). The 48042@samp{core} attribute, if present, specifies which processor core 48043the thread was last executing on. The @samp{name} attribute, if 48044present, specifies the human-readable name of the thread. The content 48045of the of @samp{thread} element is interpreted as human-readable 48046auxiliary information. The @samp{handle} attribute, if present, 48047is a hex encoded representation of the thread handle. 48048 48049 48050@node Traceframe Info Format 48051@section Traceframe Info Format 48052@cindex traceframe info format 48053 48054To be able to know which objects in the inferior can be examined when 48055inspecting a tracepoint hit, @value{GDBN} needs to obtain the list of 48056memory ranges, registers and trace state variables that have been 48057collected in a traceframe. 48058 48059This list is obtained using the @samp{qXfer:traceframe-info:read} 48060(@pxref{qXfer traceframe info read}) packet and is an XML document. 48061 48062@value{GDBN} must be linked with the Expat library to support XML 48063traceframe info discovery. @xref{Expat}. 48064 48065The top-level structure of the document is shown below: 48066 48067@smallexample 48068<?xml version="1.0"?> 48069<!DOCTYPE traceframe-info 48070 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN" 48071 "http://sourceware.org/gdb/gdb-traceframe-info.dtd"> 48072<traceframe-info> 48073 block... 48074</traceframe-info> 48075@end smallexample 48076 48077Each traceframe block can be either: 48078 48079@itemize 48080 48081@item 48082A region of collected memory starting at @var{addr} and extending for 48083@var{length} bytes from there: 48084 48085@smallexample 48086<memory start="@var{addr}" length="@var{length}"/> 48087@end smallexample 48088 48089@item 48090A block indicating trace state variable numbered @var{number} has been 48091collected: 48092 48093@smallexample 48094<tvar id="@var{number}"/> 48095@end smallexample 48096 48097@end itemize 48098 48099The formal DTD for the traceframe info format is given below: 48100 48101@smallexample 48102<!ELEMENT traceframe-info (memory | tvar)* > 48103<!ATTLIST traceframe-info version CDATA #FIXED "1.0"> 48104 48105<!ELEMENT memory EMPTY> 48106<!ATTLIST memory start CDATA #REQUIRED 48107 length CDATA #REQUIRED> 48108<!ELEMENT tvar> 48109<!ATTLIST tvar id CDATA #REQUIRED> 48110@end smallexample 48111 48112@node Branch Trace Format 48113@section Branch Trace Format 48114@cindex branch trace format 48115 48116In order to display the branch trace of an inferior thread, 48117@value{GDBN} needs to obtain the list of branches. This list is 48118represented as list of sequential code blocks that are connected via 48119branches. The code in each block has been executed sequentially. 48120 48121This list is obtained using the @samp{qXfer:btrace:read} 48122(@pxref{qXfer btrace read}) packet and is an XML document. 48123 48124@value{GDBN} must be linked with the Expat library to support XML 48125traceframe info discovery. @xref{Expat}. 48126 48127The top-level structure of the document is shown below: 48128 48129@smallexample 48130<?xml version="1.0"?> 48131<!DOCTYPE btrace 48132 PUBLIC "+//IDN gnu.org//DTD GDB Branch Trace V1.0//EN" 48133 "http://sourceware.org/gdb/gdb-btrace.dtd"> 48134<btrace> 48135 block... 48136</btrace> 48137@end smallexample 48138 48139@itemize 48140 48141@item 48142A block of sequentially executed instructions starting at @var{begin} 48143and ending at @var{end}: 48144 48145@smallexample 48146<block begin="@var{begin}" end="@var{end}"/> 48147@end smallexample 48148 48149@end itemize 48150 48151The formal DTD for the branch trace format is given below: 48152 48153@smallexample 48154<!ELEMENT btrace (block* | pt) > 48155<!ATTLIST btrace version CDATA #FIXED "1.0"> 48156 48157<!ELEMENT block EMPTY> 48158<!ATTLIST block begin CDATA #REQUIRED 48159 end CDATA #REQUIRED> 48160 48161<!ELEMENT pt (pt-config?, raw?)> 48162 48163<!ELEMENT pt-config (cpu?)> 48164 48165<!ELEMENT cpu EMPTY> 48166<!ATTLIST cpu vendor CDATA #REQUIRED 48167 family CDATA #REQUIRED 48168 model CDATA #REQUIRED 48169 stepping CDATA #REQUIRED> 48170 48171<!ELEMENT raw (#PCDATA)> 48172@end smallexample 48173 48174@node Branch Trace Configuration Format 48175@section Branch Trace Configuration Format 48176@cindex branch trace configuration format 48177 48178For each inferior thread, @value{GDBN} can obtain the branch trace 48179configuration using the @samp{qXfer:btrace-conf:read} 48180(@pxref{qXfer btrace-conf read}) packet. 48181 48182The configuration describes the branch trace format and configuration 48183settings for that format. The following information is described: 48184 48185@table @code 48186@item bts 48187This thread uses the @dfn{Branch Trace Store} (@acronym{BTS}) format. 48188@table @code 48189@item size 48190The size of the @acronym{BTS} ring buffer in bytes. 48191@end table 48192@item pt 48193This thread uses the @dfn{Intel Processor Trace} (@acronym{Intel 48194PT}) format. 48195@table @code 48196@item size 48197The size of the @acronym{Intel PT} ring buffer in bytes. 48198@end table 48199@end table 48200 48201@value{GDBN} must be linked with the Expat library to support XML 48202branch trace configuration discovery. @xref{Expat}. 48203 48204The formal DTD for the branch trace configuration format is given below: 48205 48206@smallexample 48207<!ELEMENT btrace-conf (bts?, pt?)> 48208<!ATTLIST btrace-conf version CDATA #FIXED "1.0"> 48209 48210<!ELEMENT bts EMPTY> 48211<!ATTLIST bts size CDATA #IMPLIED> 48212 48213<!ELEMENT pt EMPTY> 48214<!ATTLIST pt size CDATA #IMPLIED> 48215@end smallexample 48216 48217@include agentexpr.texi 48218 48219@node Target Descriptions 48220@appendix Target Descriptions 48221@cindex target descriptions 48222 48223One of the challenges of using @value{GDBN} to debug embedded systems 48224is that there are so many minor variants of each processor 48225architecture in use. It is common practice for vendors to start with 48226a standard processor core --- ARM, PowerPC, or @acronym{MIPS}, for example --- 48227and then make changes to adapt it to a particular market niche. Some 48228architectures have hundreds of variants, available from dozens of 48229vendors. This leads to a number of problems: 48230 48231@itemize @bullet 48232@item 48233With so many different customized processors, it is difficult for 48234the @value{GDBN} maintainers to keep up with the changes. 48235@item 48236Since individual variants may have short lifetimes or limited 48237audiences, it may not be worthwhile to carry information about every 48238variant in the @value{GDBN} source tree. 48239@item 48240When @value{GDBN} does support the architecture of the embedded system 48241at hand, the task of finding the correct architecture name to give the 48242@command{set architecture} command can be error-prone. 48243@end itemize 48244 48245To address these problems, the @value{GDBN} remote protocol allows a 48246target system to not only identify itself to @value{GDBN}, but to 48247actually describe its own features. This lets @value{GDBN} support 48248processor variants it has never seen before --- to the extent that the 48249descriptions are accurate, and that @value{GDBN} understands them. 48250 48251@value{GDBN} must be linked with the Expat library to support XML 48252target descriptions. @xref{Expat}. 48253 48254@menu 48255* Retrieving Descriptions:: How descriptions are fetched from a target. 48256* Target Description Format:: The contents of a target description. 48257* Predefined Target Types:: Standard types available for target 48258 descriptions. 48259* Enum Target Types:: How to define enum target types. 48260* Standard Target Features:: Features @value{GDBN} knows about. 48261@end menu 48262 48263@node Retrieving Descriptions 48264@section Retrieving Descriptions 48265 48266Target descriptions can be read from the target automatically, or 48267specified by the user manually. The default behavior is to read the 48268description from the target. @value{GDBN} retrieves it via the remote 48269protocol using @samp{qXfer} requests (@pxref{General Query Packets, 48270qXfer}). The @var{annex} in the @samp{qXfer} packet will be 48271@samp{target.xml}. The contents of the @samp{target.xml} annex are an 48272XML document, of the form described in @ref{Target Description 48273Format}. 48274 48275Alternatively, you can specify a file to read for the target description. 48276If a file is set, the target will not be queried. The commands to 48277specify a file are: 48278 48279@table @code 48280@cindex set tdesc filename 48281@item set tdesc filename @var{path} 48282Read the target description from @var{path}. 48283 48284@cindex unset tdesc filename 48285@item unset tdesc filename 48286Do not read the XML target description from a file. @value{GDBN} 48287will use the description supplied by the current target. 48288 48289@cindex show tdesc filename 48290@item show tdesc filename 48291Show the filename to read for a target description, if any. 48292@end table 48293 48294 48295@node Target Description Format 48296@section Target Description Format 48297@cindex target descriptions, XML format 48298 48299A target description annex is an @uref{http://www.w3.org/XML/, XML} 48300document which complies with the Document Type Definition provided in 48301the @value{GDBN} sources in @file{gdb/features/gdb-target.dtd}. This 48302means you can use generally available tools like @command{xmllint} to 48303check that your feature descriptions are well-formed and valid. 48304However, to help people unfamiliar with XML write descriptions for 48305their targets, we also describe the grammar here. 48306 48307Target descriptions can identify the architecture of the remote target 48308and (for some architectures) provide information about custom register 48309sets. They can also identify the OS ABI of the remote target. 48310@value{GDBN} can use this information to autoconfigure for your 48311target, or to warn you if you connect to an unsupported target. 48312 48313Here is a simple target description: 48314 48315@smallexample 48316<target version="1.0"> 48317 <architecture>i386:x86-64</architecture> 48318</target> 48319@end smallexample 48320 48321@noindent 48322This minimal description only says that the target uses 48323the x86-64 architecture. 48324 48325A target description has the following overall form, with [ ] marking 48326optional elements and @dots{} marking repeatable elements. The elements 48327are explained further below. 48328 48329@smallexample 48330<?xml version="1.0"?> 48331<!DOCTYPE target SYSTEM "gdb-target.dtd"> 48332<target version="1.0"> 48333 @r{[}@var{architecture}@r{]} 48334 @r{[}@var{osabi}@r{]} 48335 @r{[}@var{compatible}@r{]} 48336 @r{[}@var{feature}@dots{}@r{]} 48337</target> 48338@end smallexample 48339 48340@noindent 48341The description is generally insensitive to whitespace and line 48342breaks, under the usual common-sense rules. The XML version 48343declaration and document type declaration can generally be omitted 48344(@value{GDBN} does not require them), but specifying them may be 48345useful for XML validation tools. The @samp{version} attribute for 48346@samp{<target>} may also be omitted, but we recommend 48347including it; if future versions of @value{GDBN} use an incompatible 48348revision of @file{gdb-target.dtd}, they will detect and report 48349the version mismatch. 48350 48351@subsection Inclusion 48352@cindex target descriptions, inclusion 48353@cindex XInclude 48354@ifnotinfo 48355@cindex <xi:include> 48356@end ifnotinfo 48357 48358It can sometimes be valuable to split a target description up into 48359several different annexes, either for organizational purposes, or to 48360share files between different possible target descriptions. You can 48361divide a description into multiple files by replacing any element of 48362the target description with an inclusion directive of the form: 48363 48364@smallexample 48365<xi:include href="@var{document}"/> 48366@end smallexample 48367 48368@noindent 48369When @value{GDBN} encounters an element of this form, it will retrieve 48370the named XML @var{document}, and replace the inclusion directive with 48371the contents of that document. If the current description was read 48372using @samp{qXfer}, then so will be the included document; 48373@var{document} will be interpreted as the name of an annex. If the 48374current description was read from a file, @value{GDBN} will look for 48375@var{document} as a file in the same directory where it found the 48376original description. 48377 48378@subsection Architecture 48379@cindex <architecture> 48380 48381An @samp{<architecture>} element has this form: 48382 48383@smallexample 48384 <architecture>@var{arch}</architecture> 48385@end smallexample 48386 48387@var{arch} is one of the architectures from the set accepted by 48388@code{set architecture} (@pxref{Targets, ,Specifying a Debugging Target}). 48389 48390@subsection OS ABI 48391@cindex @code{<osabi>} 48392 48393This optional field was introduced in @value{GDBN} version 7.0. 48394Previous versions of @value{GDBN} ignore it. 48395 48396An @samp{<osabi>} element has this form: 48397 48398@smallexample 48399 <osabi>@var{abi-name}</osabi> 48400@end smallexample 48401 48402@var{abi-name} is an OS ABI name from the same selection accepted by 48403@w{@code{set osabi}} (@pxref{ABI, ,Configuring the Current ABI}). 48404 48405@subsection Compatible Architecture 48406@cindex @code{<compatible>} 48407 48408This optional field was introduced in @value{GDBN} version 7.0. 48409Previous versions of @value{GDBN} ignore it. 48410 48411A @samp{<compatible>} element has this form: 48412 48413@smallexample 48414 <compatible>@var{arch}</compatible> 48415@end smallexample 48416 48417@var{arch} is one of the architectures from the set accepted by 48418@code{set architecture} (@pxref{Targets, ,Specifying a Debugging Target}). 48419 48420A @samp{<compatible>} element is used to specify that the target 48421is able to run binaries in some other than the main target architecture 48422given by the @samp{<architecture>} element. For example, on the 48423Cell Broadband Engine, the main architecture is @code{powerpc:common} 48424or @code{powerpc:common64}, but the system is able to run binaries 48425in the @code{spu} architecture as well. The way to describe this 48426capability with @samp{<compatible>} is as follows: 48427 48428@smallexample 48429 <architecture>powerpc:common</architecture> 48430 <compatible>spu</compatible> 48431@end smallexample 48432 48433@subsection Features 48434@cindex <feature> 48435 48436Each @samp{<feature>} describes some logical portion of the target 48437system. Features are currently used to describe available CPU 48438registers and the types of their contents. A @samp{<feature>} element 48439has this form: 48440 48441@smallexample 48442<feature name="@var{name}"> 48443 @r{[}@var{type}@dots{}@r{]} 48444 @var{reg}@dots{} 48445</feature> 48446@end smallexample 48447 48448@noindent 48449Each feature's name should be unique within the description. The name 48450of a feature does not matter unless @value{GDBN} has some special 48451knowledge of the contents of that feature; if it does, the feature 48452should have its standard name. @xref{Standard Target Features}. 48453 48454@subsection Types 48455 48456Any register's value is a collection of bits which @value{GDBN} must 48457interpret. The default interpretation is a two's complement integer, 48458but other types can be requested by name in the register description. 48459Some predefined types are provided by @value{GDBN} (@pxref{Predefined 48460Target Types}), and the description can define additional composite 48461and enum types. 48462 48463Each type element must have an @samp{id} attribute, which gives 48464a unique (within the containing @samp{<feature>}) name to the type. 48465Types must be defined before they are used. 48466 48467@cindex <vector> 48468Some targets offer vector registers, which can be treated as arrays 48469of scalar elements. These types are written as @samp{<vector>} elements, 48470specifying the array element type, @var{type}, and the number of elements, 48471@var{count}: 48472 48473@smallexample 48474<vector id="@var{id}" type="@var{type}" count="@var{count}"/> 48475@end smallexample 48476 48477@cindex <union> 48478If a register's value is usefully viewed in multiple ways, define it 48479with a union type containing the useful representations. The 48480@samp{<union>} element contains one or more @samp{<field>} elements, 48481each of which has a @var{name} and a @var{type}: 48482 48483@smallexample 48484<union id="@var{id}"> 48485 <field name="@var{name}" type="@var{type}"/> 48486 @dots{} 48487</union> 48488@end smallexample 48489 48490@cindex <struct> 48491@cindex <flags> 48492If a register's value is composed from several separate values, define 48493it with either a structure type or a flags type. 48494A flags type may only contain bitfields. 48495A structure type may either contain only bitfields or contain no bitfields. 48496If the value contains only bitfields, its total size in bytes must be 48497specified. 48498 48499Non-bitfield values have a @var{name} and @var{type}. 48500 48501@smallexample 48502<struct id="@var{id}"> 48503 <field name="@var{name}" type="@var{type}"/> 48504 @dots{} 48505</struct> 48506@end smallexample 48507 48508Both @var{name} and @var{type} values are required. 48509No implicit padding is added. 48510 48511Bitfield values have a @var{name}, @var{start}, @var{end} and @var{type}. 48512 48513@smallexample 48514<struct id="@var{id}" size="@var{size}"> 48515 <field name="@var{name}" start="@var{start}" end="@var{end}" type="@var{type}"/> 48516 @dots{} 48517</struct> 48518@end smallexample 48519 48520@smallexample 48521<flags id="@var{id}" size="@var{size}"> 48522 <field name="@var{name}" start="@var{start}" end="@var{end}" type="@var{type}"/> 48523 @dots{} 48524</flags> 48525@end smallexample 48526 48527The @var{name} value is required. 48528Bitfield values may be named with the empty string, @samp{""}, 48529in which case the field is ``filler'' and its value is not printed. 48530Not all bits need to be specified, so ``filler'' fields are optional. 48531 48532The @var{start} and @var{end} values are required, and @var{type} 48533is optional. 48534The field's @var{start} must be less than or equal to its @var{end}, 48535and zero represents the least significant bit. 48536 48537The default value of @var{type} is @code{bool} for single bit fields, 48538and an unsigned integer otherwise. 48539 48540Which to choose? Structures or flags? 48541 48542Registers defined with @samp{flags} have these advantages over 48543defining them with @samp{struct}: 48544 48545@itemize @bullet 48546@item 48547Arithmetic may be performed on them as if they were integers. 48548@item 48549They are printed in a more readable fashion. 48550@end itemize 48551 48552Registers defined with @samp{struct} have one advantage over 48553defining them with @samp{flags}: 48554 48555@itemize @bullet 48556@item 48557One can fetch individual fields like in @samp{C}. 48558 48559@smallexample 48560(@value{GDBP}) print $my_struct_reg.field3 48561$1 = 42 48562@end smallexample 48563 48564@end itemize 48565 48566@subsection Registers 48567@cindex <reg> 48568 48569Each register is represented as an element with this form: 48570 48571@smallexample 48572<reg name="@var{name}" 48573 bitsize="@var{size}" 48574 @r{[}regnum="@var{num}"@r{]} 48575 @r{[}save-restore="@var{save-restore}"@r{]} 48576 @r{[}type="@var{type}"@r{]} 48577 @r{[}group="@var{group}"@r{]}/> 48578@end smallexample 48579 48580@noindent 48581The components are as follows: 48582 48583@table @var 48584 48585@item name 48586The register's name; it must be unique within the target description. 48587 48588@item bitsize 48589The register's size, in bits. 48590 48591@item regnum 48592The register's number. If omitted, a register's number is one greater 48593than that of the previous register (either in the current feature or in 48594a preceding feature); the first register in the target description 48595defaults to zero. This register number is used to read or write 48596the register; e.g.@: it is used in the remote @code{p} and @code{P} 48597packets, and registers appear in the @code{g} and @code{G} packets 48598in order of increasing register number. 48599 48600@item save-restore 48601Whether the register should be preserved across inferior function 48602calls; this must be either @code{yes} or @code{no}. The default is 48603@code{yes}, which is appropriate for most registers except for 48604some system control registers; this is not related to the target's 48605ABI. 48606 48607@item type 48608The type of the register. It may be a predefined type, a type 48609defined in the current feature, or one of the special types @code{int} 48610and @code{float}. @code{int} is an integer type of the correct size 48611for @var{bitsize}, and @code{float} is a floating point type (in the 48612architecture's normal floating point format) of the correct size for 48613@var{bitsize}. The default is @code{int}. 48614 48615@item group 48616The register group to which this register belongs. It can be one of the 48617standard register groups @code{general}, @code{float}, @code{vector} or an 48618arbitrary string. Group names should be limited to alphanumeric characters. 48619If a group name is made up of multiple words the words may be separated by 48620hyphens; e.g.@: @code{special-group} or @code{ultra-special-group}. If no 48621@var{group} is specified, @value{GDBN} will not display the register in 48622@code{info registers}. 48623 48624@end table 48625 48626@node Predefined Target Types 48627@section Predefined Target Types 48628@cindex target descriptions, predefined types 48629 48630Type definitions in the self-description can build up composite types 48631from basic building blocks, but can not define fundamental types. Instead, 48632standard identifiers are provided by @value{GDBN} for the fundamental 48633types. The currently supported types are: 48634 48635@table @code 48636 48637@item bool 48638Boolean type, occupying a single bit. 48639 48640@item int8 48641@itemx int16 48642@itemx int24 48643@itemx int32 48644@itemx int64 48645@itemx int128 48646Signed integer types holding the specified number of bits. 48647 48648@item uint8 48649@itemx uint16 48650@itemx uint24 48651@itemx uint32 48652@itemx uint64 48653@itemx uint128 48654Unsigned integer types holding the specified number of bits. 48655 48656@item code_ptr 48657@itemx data_ptr 48658Pointers to unspecified code and data. The program counter and 48659any dedicated return address register may be marked as code 48660pointers; printing a code pointer converts it into a symbolic 48661address. The stack pointer and any dedicated address registers 48662may be marked as data pointers. 48663 48664@item ieee_half 48665Half precision IEEE floating point. 48666 48667@item ieee_single 48668Single precision IEEE floating point. 48669 48670@item ieee_double 48671Double precision IEEE floating point. 48672 48673@item bfloat16 48674The 16-bit @dfn{brain floating point} format used e.g.@: by x86 and ARM. 48675 48676@item arm_fpa_ext 48677The 12-byte extended precision format used by ARM FPA registers. 48678 48679@item i387_ext 48680The 10-byte extended precision format used by x87 registers. 48681 48682@item i386_eflags 4868332bit @sc{eflags} register used by x86. 48684 48685@item i386_mxcsr 4868632bit @sc{mxcsr} register used by x86. 48687 48688@end table 48689 48690@node Enum Target Types 48691@section Enum Target Types 48692@cindex target descriptions, enum types 48693 48694Enum target types are useful in @samp{struct} and @samp{flags} 48695register descriptions. @xref{Target Description Format}. 48696 48697Enum types have a name, size and a list of name/value pairs. 48698 48699@smallexample 48700<enum id="@var{id}" size="@var{size}"> 48701 <evalue name="@var{name}" value="@var{value}"/> 48702 @dots{} 48703</enum> 48704@end smallexample 48705 48706Enums must be defined before they are used. 48707 48708@smallexample 48709<enum id="levels_type" size="4"> 48710 <evalue name="low" value="0"/> 48711 <evalue name="high" value="1"/> 48712</enum> 48713<flags id="flags_type" size="4"> 48714 <field name="X" start="0"/> 48715 <field name="LEVEL" start="1" end="1" type="levels_type"/> 48716</flags> 48717<reg name="flags" bitsize="32" type="flags_type"/> 48718@end smallexample 48719 48720Given that description, a value of 3 for the @samp{flags} register 48721would be printed as: 48722 48723@smallexample 48724(@value{GDBP}) info register flags 48725flags 0x3 [ X LEVEL=high ] 48726@end smallexample 48727 48728@node Standard Target Features 48729@section Standard Target Features 48730@cindex target descriptions, standard features 48731 48732A target description must contain either no registers or all the 48733target's registers. If the description contains no registers, then 48734@value{GDBN} will assume a default register layout, selected based on 48735the architecture. If the description contains any registers, the 48736default layout will not be used; the standard registers must be 48737described in the target description, in such a way that @value{GDBN} 48738can recognize them. 48739 48740This is accomplished by giving specific names to feature elements 48741which contain standard registers. @value{GDBN} will look for features 48742with those names and verify that they contain the expected registers; 48743if any known feature is missing required registers, or if any required 48744feature is missing, @value{GDBN} will reject the target 48745description. You can add additional registers to any of the 48746standard features --- @value{GDBN} will display them just as if 48747they were added to an unrecognized feature. 48748 48749This section lists the known features and their expected contents. 48750Sample XML documents for these features are included in the 48751@value{GDBN} source tree, in the directory @file{gdb/features}. 48752 48753Names recognized by @value{GDBN} should include the name of the 48754company or organization which selected the name, and the overall 48755architecture to which the feature applies; so e.g.@: the feature 48756containing ARM core registers is named @samp{org.gnu.gdb.arm.core}. 48757 48758The names of registers are not case sensitive for the purpose 48759of recognizing standard features, but @value{GDBN} will only display 48760registers using the capitalization used in the description. 48761 48762@menu 48763* AArch64 Features:: 48764* ARC Features:: 48765* ARM Features:: 48766* i386 Features:: 48767* LoongArch Features:: 48768* MicroBlaze Features:: 48769* MIPS Features:: 48770* M68K Features:: 48771* NDS32 Features:: 48772* Nios II Features:: 48773* OpenRISC 1000 Features:: 48774* PowerPC Features:: 48775* RISC-V Features:: 48776* RX Features:: 48777* S/390 and System z Features:: 48778* Sparc Features:: 48779* TIC6x Features:: 48780@end menu 48781 48782 48783@node AArch64 Features 48784@subsection AArch64 Features 48785@cindex target descriptions, AArch64 features 48786 48787@subsubsection AArch64 core registers feature 48788 48789The @samp{org.gnu.gdb.aarch64.core} feature is required for AArch64 48790targets. It must contain the following: 48791 48792@itemize @minus 48793@item 48794@samp{x0} through @samp{x30}, the general purpose registers, with size of 4879564 bits. Register @samp{x30} is also known as the @dfn{link register}, 48796or @samp{lr}. 48797@item 48798@samp{sp}, the stack pointer register or @samp{x31}. It is 64 bits in size and 48799has a type of @samp{data_ptr}. 48800@item 48801@samp{pc}, the program counter register. It is 64 bits in size and has a type 48802of @samp{code_ptr}. 48803@item 48804@samp{cpsr}, the current program status register. It is 32 bits in size 48805and has a custom flags type. 48806@end itemize 48807 48808The semantics of the individual flags and fields in @samp{cpsr} can change as 48809new architectural features are added. The current layout can be found in the 48810aarch64-core.xml file. 48811 48812Extra registers are allowed in this feature, but they will not affect 48813@value{GDBN}. 48814 48815@subsubsection AArch64 floating-point registers feature 48816 48817The @samp{org.gnu.gdb.aarch64.fpu} feature is optional. If present, 48818it must contain the following registers: 48819 48820@itemize @minus 48821@item 48822@samp{v0} through @samp{v31}, the vector registers with size of 128 bits. The 48823type is a custom vector type. 48824@item 48825@samp{fpsr}, the floating-point status register. It is 32 bits in size and has 48826a custom flags type. 48827@item 48828@samp{fpcr}, the floating-point control register. It is 32 bits in size and has 48829a custom flags type. 48830@end itemize 48831 48832The semantics of the individual flags and fields in @samp{fpsr} and @samp{fpcr} 48833can change as new architectural features are added. 48834 48835The types for the vector registers, @samp{fpsr} and @samp{fpcr} registers can 48836be found in the aarch64-fpu.xml file. 48837 48838Extra registers are allowed in this feature, but they will not affect 48839@value{GDBN}. 48840 48841@subsubsection AArch64 SVE registers feature 48842 48843The @samp{org.gnu.gdb.aarch64.sve} feature is optional. If present, 48844it means the target supports the Scalable Vector Extension and must contain 48845the following registers: 48846 48847@itemize @minus 48848@item 48849@samp{z0} through @samp{z31}, the scalable vector registers. Their sizes are 48850variable and a multiple of 128 bits up to a maximum of 2048 bit. Their type is 48851a custom union type that helps visualize different sizes of sub-vectors. 48852@item 48853@samp{fpsr}, the floating-point status register. It is 32 bits in size and has 48854a custom flags type. 48855@item 48856@samp{fpcr}, the floating-point control register. It is 32 bits in size and has 48857a custom flags type. 48858@item 48859@samp{p0} through @samp{p15}, the predicate registers. Their sizes are 48860variable, based on the current vector length, and a multiple of 4886116 bits. Their types are a custom union to help visualize sub-elements. 48862@item 48863@samp{ffr}, the First Fault register. It has a variable size based on the 48864current vector length and is a multiple of 16 bits. The type is the same as 48865the predicate registers. 48866@item 48867@samp{vg}, the vector granule. It represents the number of 64 bits chunks in 48868a @samp{z} register. It is closely associated with the current vector 48869length. It has a type of @samp{int}. 48870@end itemize 48871 48872When @value{GDBN} sees the SVE feature, it will assume the Scalable Vector 48873Extension is supported, and will adjust the sizes of the @samp{z}, @samp{p} 48874and @samp{ffr} registers accordingly, based on the value of @samp{vg}. 48875 48876@value{GDBN} will also create pseudo-registers equivalent to the @samp{v} 48877vector registers from the @samp{org.gnu.gdb.aarch64.fpu} feature. 48878 48879The first 128 bits of the @samp{z} registers overlap the 128 bits of the 48880@samp{v} registers, so changing one will trigger a change to the other. 48881 48882For the types of the @samp{z}, @samp{p} and @samp{ffr} registers, please 48883check the aarch64-sve.c file. No XML file is available for this feature 48884because it is dynamically generated based on the current vector length. 48885 48886The semantics of the individual flags and fields in @samp{fpsr} and @samp{fpcr} 48887can change as new architectural features are added. 48888 48889The types for the @samp{fpsr} and @samp{fpcr} registers can be found in the 48890aarch64-sve.c file, and should match what is described in aarch64-fpu.xml. 48891 48892Extra registers are allowed in this feature, but they will not affect 48893@value{GDBN}. 48894 48895@subsubsection AArch64 Pointer Authentication registers feature 48896 48897The @samp{org.gnu.gdb.aarch64.pauth} optional feature was introduced so 48898@value{GDBN} could detect support for the Pointer Authentication 48899extension. If present, it must contain one of two possible register sets. 48900 48901Pointer Authentication masks for user-mode: 48902 48903@itemize @minus 48904@item 48905@samp{pauth_dmask}, the user-mode pointer authentication mask for data 48906pointers. It is 64 bits in size. 48907@item 48908@samp{pauth_cmask}, the user-mode pointer authentication mask for code 48909pointers. It is 64 bits in size. 48910@end itemize 48911 48912Pointer Authentication masks for user-mode and kernel-mode: 48913 48914@itemize @minus 48915@item 48916@samp{pauth_dmask}, the user-mode pointer authentication mask for data 48917pointers. It is 64 bits in size. 48918@item 48919@samp{pauth_cmask}, the user-mode pointer authentication mask for code 48920pointers. It is 64 bits in size. 48921@item 48922@samp{pauth_dmask_high}, the kernel-mode pointer authentication mask for 48923data pointers. It is 64 bits in size. 48924@item 48925@samp{pauth_cmask_high}, the kernel-mode pointer authentication mask for 48926code pointers. It is 64 bits in size. 48927@end itemize 48928 48929If @value{GDBN} sees any of the two sets of registers in this feature, it will 48930assume the target is capable of signing pointers. If so, @value{GDBN} will 48931decorate backtraces with a @samp{[PAC]} marker alongside a function that 48932has a signed link register value that needs to be unmasked/decoded. 48933 48934@value{GDBN} will also use the masks to remove non-address bits from pointers. 48935 48936Extra registers are allowed in this feature, but they will not affect 48937@value{GDBN}. 48938 48939Please note the @samp{org.gnu.gdb.aarch64.pauth} feature string is deprecated 48940and must only be used for backwards compatibility with older releases of 48941@value{GDBN} and @command{gdbserver}. Targets that support Pointer 48942Authentication must advertise such capability by using the 48943@samp{org.gnu.gdb.aarch64.pauth_v2} feature string instead. 48944 48945The @samp{org.gnu.gdb.aarch64.pauth_v2} feature has the exact same contents 48946as feature @samp{org.gnu.gdb.aarch64.pauth}. 48947 48948The reason for having feature @samp{org.gnu.gdb.aarch64.pauth_v2} is a bug in 48949previous versions of @value{GDBN} (versions 9, 10, 11 and 12). This bug 48950caused @value{GDBN} to crash whenever the target reported support for Pointer 48951Authentication (using feature string @samp{org.gnu.gdb.aarch64.pauth}) and also 48952reported additional system registers that were not accounted for by 48953@value{GDBN}. This is more common when using emulators and on bare-metal 48954debugging scenarios. 48955 48956It can also happen if a newer gdbserver is used with an old @value{GDBN} that 48957has the bug. In such a case, the newer gdbserver might report Pointer 48958Authentication support via the @samp{org.gnu.gdb.aarch64.pauth} feature string 48959and also report additional registers the older @value{GDBN} does not know 48960about, potentially leading to a crash. 48961 48962@subsubsection AArch64 TLS registers feature 48963 48964The @samp{org.gnu.gdb.aarch64.tls} optional feature was introduced to expose 48965the TLS registers to @value{GDBN}. If present, it must contain either one 48966of the following register sets. 48967 48968Only @samp{tpidr}: 48969 48970@itemize @minus 48971@item 48972@samp{tpidr}, the software thread id register. It is 64 bits in size and has a 48973type of @samp{data_ptr}. 48974@end itemize 48975 48976Both @samp{tpidr} and @samp{tpidr2}. 48977 48978@itemize @minus 48979@item 48980@samp{tpidr}, the software thread id register. It is 64 bits in size and has a 48981type of @samp{data_ptr}. 48982@item 48983@samp{tpidr2}, the second software thread id register. It is 64 bits in size 48984and has a type of @samp{data_ptr}. It may be used in the future alongside 48985the Scalable Matrix Extension for a lazy restore scheme. 48986@end itemize 48987 48988If @value{GDBN} sees this feature, it will attempt to find one of the 48989variations of the register set. If @samp{tpidr2} is available, 48990@value{GDBN} may act on it to display additional data in the future. 48991 48992There is no XML for this feature as the presence of @samp{tpidr2} is 48993determined dynamically at runtime. 48994 48995Extra registers are allowed in this feature, but they will not affect 48996@value{GDBN}. 48997 48998@subsubsection AArch64 MTE registers feature 48999 49000The @samp{org.gnu.gdb.aarch64.mte} optional feature was introduced so 49001@value{GDBN} could detect support for the Memory Tagging Extension and 49002control memory tagging settings. If present, this feature must have the 49003following register: 49004 49005@itemize @minus 49006@item 49007@samp{tag_ctl}, the tag control register. It is 64 bits in size and has a type 49008of @samp{uint64}. 49009@end itemize 49010 49011Memory Tagging detection is done via a runtime check though, so the presence 49012of this feature and register is not enough to enable memory tagging support. 49013 49014This restriction may be lifted in the future. 49015 49016Extra registers are allowed in this feature, but they will not affect 49017@value{GDBN}. 49018 49019@subsubsection AArch64 SME registers feature 49020 49021The @samp{org.gnu.gdb.aarch64.sme} feature is optional. If present, 49022it should contain registers @code{ZA}, @code{SVG} and @code{SVCR}. 49023@xref{AArch64 SME}. 49024 49025@itemize @minus 49026 49027@item 49028@code{ZA} is a register represented by a vector of @var{svl}x@var{svl} 49029bytes. @xref{svl}. 49030 49031@item 49032@code{SVG} is a 64-bit register containing the value of @var{svg}. @xref{svg}. 49033 49034@item 49035@code{SVCR} is a 64-bit status pseudo-register with two valid bits. Bit 0 49036(@sc{sm}) shows whether the streaming @acronym{SVE} mode is enabled or disabled. 49037Bit 1 (@sc{ZA}) shows whether the @code{ZA} register state is active (in use) or 49038not. 49039@xref{aarch64 sme svcr}. 49040 49041The rest of the unused bits of the @code{SVCR} pseudo-register is undefined 49042and reserved. Such bits should not be used and may be defined by future 49043extensions of the architecture. 49044 49045@end itemize 49046 49047Extra registers are allowed in this feature, but they will not affect 49048@value{GDBN}. 49049 49050The @samp{org.gnu.gdb.aarch64.sme} feature is required when the target also 49051reports support for the @samp{org.gnu.gdb.aarch64.sme2} feature. 49052 49053@subsubsection AArch64 SME2 registers feature 49054 49055The @samp{org.gnu.gdb.aarch64.sme2} feature is optional. If present, 49056then the @samp{org.gnu.gdb.aarch64.sme} feature must also be present. The 49057@samp{org.gnu.gdb.aarch64.sme2} feature should contain the following: 49058@xref{AArch64 SME2}. 49059 49060@itemize @minus 49061 49062@item 49063@code{ZT0} is a register of 512 bits (64 bytes). It is defined as a vector 49064of bytes. 49065 49066@end itemize 49067 49068Extra registers are allowed in this feature, but they will not affect 49069@value{GDBN}. 49070 49071@node ARC Features 49072@subsection ARC Features 49073@cindex target descriptions, ARC Features 49074 49075ARC processors are so configurable that even core registers and their numbers 49076are not predetermined completely. Moreover, @emph{flags} and @emph{PC} 49077registers, which are important to @value{GDBN}, are not ``core'' registers in 49078ARC. Therefore, there are two features that their presence is mandatory: 49079@samp{org.gnu.gdb.arc.core} and @samp{org.gnu.gdb.arc.aux}. 49080 49081The @samp{org.gnu.gdb.arc.core} feature is required for all targets. It must 49082contain registers: 49083 49084@itemize @minus 49085@item 49086@samp{r0} through @samp{r25} for normal register file targets. 49087@item 49088@samp{r0} through @samp{r3}, and @samp{r10} through @samp{r15} for reduced 49089register file targets. 49090@item 49091@samp{gp}, @samp{fp}, @samp{sp}, @samp{r30}@footnote{Not necessary for ARCv1.}, 49092@samp{blink}, @samp{lp_count}, @samp{pcl}. 49093@end itemize 49094 49095In case of an ARCompact target (ARCv1 ISA), the @samp{org.gnu.gdb.arc.core} 49096feature may contain registers @samp{ilink1} and @samp{ilink2}. While in case 49097of ARC EM and ARC HS targets (ARCv2 ISA), register @samp{ilink} may be present. 49098The difference between ARCv1 and ARCv2 is the naming of registers @emph{29th} 49099and @emph{30th}. They are called @samp{ilink1} and @samp{ilink2} for ARCv1 and 49100are optional. For ARCv2, they are called @samp{ilink} and @samp{r30} and only 49101@samp{ilink} is optional. The optionality of @samp{ilink*} registers is 49102because of their inaccessibility during user space debugging sessions. 49103 49104Extension core registers @samp{r32} through @samp{r59} are optional and their 49105existence depends on the configuration. When debugging GNU/Linux applications, 49106i.e.@: user space debugging, these core registers are not available. 49107 49108The @samp{org.gnu.gdb.arc.aux} feature is required for all ARC targets. Here 49109is the list of registers pertinent to this feature: 49110 49111@itemize @minus 49112@item 49113mandatory: @samp{pc} and @samp{status32}. 49114@item 49115optional: @samp{lp_start}, @samp{lp_end}, and @samp{bta}. 49116@end itemize 49117 49118@node ARM Features 49119@subsection ARM Features 49120@cindex target descriptions, ARM features 49121 49122@subsubsection Core register set for non-M-profile 49123 49124The @samp{org.gnu.gdb.arm.core} feature is required for non-M-profile 49125ARM targets. It must contain the following registers: 49126 49127@itemize @minus 49128@item 49129@samp{r0} through @samp{r12}. The general purpose registers. They are 32 bits 49130in size and have a type of @samp{uint32}. 49131@item 49132@samp{sp}, the stack pointer register, also known as @samp{r13}. It is 32 bits 49133in size and has a type of @samp{data_ptr}. 49134@item 49135@samp{lr}, the link register. It is 32 bits in size. 49136@item 49137@samp{pc}, the program counter register. It is 32 bit in size and of type 49138@samp{code_ptr}. 49139@item 49140@samp{cpsr}, the current program status register containing all the status 49141bits. It is 32 bits in size. Historically this register was hardwired to 49142number 25, but debugging stubs that report XML do not need to use this number 49143anymore. 49144@end itemize 49145 49146Extra registers are allowed in this feature, but they will not affect 49147@value{GDBN}. 49148 49149@subsubsection Core register set for M-profile 49150 49151For M-profile targets (e.g.@: Cortex-M3), the @samp{org.gnu.gdb.arm.core} 49152feature is replaced by @samp{org.gnu.gdb.arm.m-profile}, and it is a required 49153feature. It must contain the following registers: 49154 49155@itemize @minus 49156@item 49157@samp{r0} through @samp{r12}, the general purpose registers. They have a size 49158of 32 bits and a type of @samp{uint32}. 49159@item 49160@samp{sp}, the stack pointer register, also known as @samp{r13}. It has a size 49161of 32 bits and a type of @samp{data_ptr}. 49162@item 49163@samp{lr}, the link register. It has a size of 32 bits. 49164@item 49165@samp{pc}, the program counter register. It has a size of 32 bits and a type 49166of @samp{code_ptr}. 49167@item 49168@samp{xpsr}, the program status register containing all the status 49169bits. It has a size of 32 bits. Historically this register was hardwired to 49170number 25, but debugging stubs that report XML do not need to use this number 49171anymore. 49172@end itemize 49173 49174Upon seeing this feature, @value{GDBN} will acknowledge that it is dealing 49175with an M-profile target. This means @value{GDBN} will use hooks and 49176configurations that are meaningful to M-profiles. 49177 49178Extra registers are allowed in this feature, but they will not affect 49179@value{GDBN}. 49180 49181@subsubsection FPA registers feature (obsolete) 49182 49183The @samp{org.gnu.gdb.arm.fpa} feature is obsolete and should not be 49184advertised by debugging stubs anymore. It used to advertise registers for 49185the old FPA architecture that has long been discontinued in toolchains. 49186 49187It is kept in @value{GDBN} for backward compatibility purposes so older 49188debugging stubs that don't support XML target descriptions still work 49189correctly. One such example is the KGDB debugging stub from 49190Linux or BSD kernels. 49191 49192The description below is for historical purposes only. This feature 49193used to contain the following registers: 49194 49195@itemize @minus 49196@item 49197@samp{f0} through @samp{f8}. The floating point registers. They are 96 bits 49198in size and of type @samp{arm_fpa_ext}. @samp{f0} is pinned to register 49199number 16. 49200@item 49201@samp{fps}, the status register. It has a size of 32 bits. 49202@end itemize 49203 49204@subsubsection M-profile Vector Extension (MVE) 49205 49206Also known as Helium, the M-profile Vector Extension is advertised via the 49207optional @samp{org.gnu.gdb.arm.m-profile-mve} feature. 49208 49209It must contain the following: 49210 49211@itemize @minus 49212@item 49213@samp{vpr}, the vector predication status and control register. It is 32 bits 49214in size and has a custom flags type. The flags type is laid out in a way that 49215exposes the @samp{P0} field from bits 0 to 15, the @samp{MASK01} field from 49216bits 16 to 19 and the @samp{MASK23} field from bits 20 to 23. 49217 49218Bits 24 through 31 are reserved. 49219@end itemize 49220 49221When this feature is available, @value{GDBN} will synthesize the @samp{p0} 49222pseudo-register from @samp{vpr} contents. 49223 49224This feature must only be advertised if the target is M-profile. Advertising 49225this feature for targets that are not M-profile may cause @value{GDBN} to 49226assume the target is M-profile when it isn't. 49227 49228If the @samp{org.gnu.gdb.arm.vfp} feature is available alongside the 49229@samp{org.gnu.gdb.arm.m-profile-mve} feature, @value{GDBN} will 49230synthesize the @samp{q} pseudo-registers from @samp{d} register 49231contents. 49232 49233Extra registers are allowed in this feature, but they will not affect 49234@value{GDBN}. 49235 49236@subsubsection XScale iwMMXt feature 49237 49238The XScale @samp{org.gnu.gdb.xscale.iwmmxt} feature is optional. If present, 49239it must contain the following: 49240 49241@itemize @minus 49242@item 49243@samp{wR0} through @samp{wR15}, registers with size 64 bits and a custom type 49244@samp{iwmmxt_vec64i}. @samp{iwmmxt_vec64i} is a union of four other 49245types: @samp{uint64}, a 2-element vector of @samp{uint32}, a 4-element 49246vector of @samp{uint16} and a 8-element vector of @samp{uint8}. 49247@item 49248@samp{wCGR0} through @samp{wCGR3}, registers with size 32 bits and 49249type @samp{int}. 49250@end itemize 49251 49252The following registers are optional: 49253 49254@itemize @minus 49255@item 49256@samp{wCID}, register with size of 32 bits and type @samp{int}. 49257@item 49258@samp{wCon}, register with size 32 bits and type @samp{int}. 49259@item 49260@samp{wCSSF}, register with size 32 bits and type @samp{int}. 49261@item 49262@samp{wCASF}, register with size 32 bit and type @samp{int}. 49263@end itemize 49264 49265This feature should only be reported if the target is XScale. 49266 49267Extra registers are allowed in this feature, but they will not affect 49268@value{GDBN}. 49269 49270@subsubsection Vector Floating-Point (VFP) feature 49271 49272The @samp{org.gnu.gdb.arm.vfp} feature is optional. If present, it 49273should contain one of two possible sets of values depending on whether 49274VFP version 2 or VFP version 3 is in use. 49275 49276For VFP v2: 49277 49278@itemize @minus 49279@item 49280@samp{d0} through @samp{d15}. The double-precision registers. They are 4928164 bits in size and have type @samp{ieee_double}. 49282@item 49283@samp{fpscr}, the floating-point status and control register. It has a size 49284of 32 bits and a type of @samp{int}. 49285@end itemize 49286 49287For VFP v3: 49288 49289@itemize @minus 49290@item 49291@samp{d0} through @samp{d31}. The double-precision registers. They are 4929264 bits in size and have type @samp{ieee_double}. 49293@item 49294@samp{fpscr}, the floating-point status and control register. It has a size 49295of 32 bits and a type of @samp{int}. 49296@end itemize 49297 49298If this feature is available, @value{GDBN} will synthesize the 49299single-precision floating-point registers from halves of the double-precision 49300registers as pseudo-registers. 49301 49302Extra registers are allowed in this feature, but they will not affect 49303@value{GDBN}. 49304 49305@subsubsection NEON architecture feature 49306 49307The @samp{org.gnu.gdb.arm.neon} feature is optional. It does not 49308need to contain registers; it instructs @value{GDBN} to display the 49309VFP double-precision registers as vectors and to synthesize the 49310quad-precision registers from pairs of double-precision registers. 49311If this feature is present, @samp{org.gnu.gdb.arm.vfp} must also 49312be present and include 32 double-precision registers. 49313 49314Extra registers are allowed in this feature, but they will not affect 49315@value{GDBN}. 49316 49317@subsubsection M-profile Pointer Authentication and Branch Target Identification feature 49318 49319The @samp{org.gnu.gdb.arm.m-profile-pacbti} feature is optional, and 49320acknowledges support for the ARMv8.1-m PACBTI extensions. 49321 49322This feature doesn't contain any required registers, and it only serves as a 49323hint to @value{GDBN} that the debugging stub supports the ARMv8.1-m PACBTI 49324extensions. 49325 49326When @value{GDBN} sees this feature, it will track return address signing 49327states and will decorate backtraces using the [PAC] marker, similar to 49328AArch64's PAC extension. 49329@xref{AArch64 PAC}. 49330 49331Extra registers are allowed in this feature, but they will not affect 49332@value{GDBN}. 49333 49334@subsubsection M-profile system registers feature 49335 49336The @samp{org.gnu.gdb.arm.m-system} optional feature was introduced as a way to 49337inform @value{GDBN} about additional system registers. 49338 49339At the moment this feature must contain the following: 49340 49341@itemize @minus 49342@item 49343@samp{msp}, the main stack pointer register. It is 32 bits in size with 49344type @samp{data_ptr}. 49345@item 49346@samp{psp}, the process stack pointer register. It is 32 bits in size with 49347type @samp{data_ptr}. 49348@end itemize 49349 49350This feature must only be advertised for M-profile targets. When @value{GDBN} 49351sees this feature, it will attempt to track the values of @samp{msp} and 49352@samp{psp} across frames. 49353 49354Extra registers are allowed in this feature, but they will not affect 49355@value{GDBN}. 49356 49357@subsubsection M-profile Security Extensions feature 49358 49359The @samp{org.gnu.gdb.arm.secext} optional feature was introduced so 49360@value{GDBN} could better support the switching of stack pointers and 49361secure states in the Security Extensions. 49362 49363At the moment this feature must contain the following: 49364 49365@itemize @minus 49366@item 49367@samp{msp_ns}, the main stack pointer register (non-secure state). It is 4936832 bits in size with type @samp{data_ptr}. 49369@item 49370@samp{psp_ns}, the process stack pointer register (non-secure state). It is 4937132 bits in size with type @samp{data_ptr}. 49372@item 49373@samp{msp_s}, the main stack pointer register (secure state). It is 32 bits 49374in size with type @samp{data_ptr}. 49375@item 49376@samp{psp_s}, the process stack pointer register (secure state). It is 32 bits 49377in size with type @samp{data_ptr}. 49378@end itemize 49379 49380When @value{GDBN} sees this feature, it will attempt to track the values of 49381all 4 stack pointers across secure state transitions, potentially improving 49382unwinding when applications switch between security states. 49383 49384Extra registers are allowed in this feature, but they will not affect 49385@value{GDBN}. 49386 49387@subsubsection TLS registers feature 49388 49389The optional @samp{org.gnu.gdb.arm.tls} feature contains TLS registers. 49390 49391Currently it contains the following: 49392 49393@itemize @minus 49394@item 49395@samp{tpidruro}, the user read-only thread id register. It is 32 bits in size 49396and has type @samp{data_ptr}. 49397@end itemize 49398 49399At the moment @value{GDBN} looks for this feature, but doesn't do anything 49400with it other than displaying it. 49401 49402Extra registers are allowed in this feature, but they will not affect 49403@value{GDBN}. 49404 49405@node i386 Features 49406@subsection i386 Features 49407@cindex target descriptions, i386 features 49408 49409The @samp{org.gnu.gdb.i386.core} feature is required for i386/amd64 49410targets. It should describe the following registers: 49411 49412@itemize @minus 49413@item 49414@samp{eax} through @samp{edi} plus @samp{eip} for i386 49415@item 49416@samp{rax} through @samp{r15} plus @samp{rip} for amd64 49417@item 49418@samp{eflags}, @samp{cs}, @samp{ss}, @samp{ds}, @samp{es}, 49419@samp{fs}, @samp{gs} 49420@item 49421@samp{st0} through @samp{st7} 49422@item 49423@samp{fctrl}, @samp{fstat}, @samp{ftag}, @samp{fiseg}, @samp{fioff}, 49424@samp{foseg}, @samp{fooff} and @samp{fop} 49425@end itemize 49426 49427The register sets may be different, depending on the target. 49428 49429The @samp{org.gnu.gdb.i386.sse} feature is optional. It should 49430describe registers: 49431 49432@itemize @minus 49433@item 49434@samp{xmm0} through @samp{xmm7} for i386 49435@item 49436@samp{xmm0} through @samp{xmm15} for amd64 49437@item 49438@samp{mxcsr} 49439@end itemize 49440 49441The @samp{org.gnu.gdb.i386.avx} feature is optional and requires the 49442@samp{org.gnu.gdb.i386.sse} feature. It should 49443describe the upper 128 bits of @sc{ymm} registers: 49444 49445@itemize @minus 49446@item 49447@samp{ymm0h} through @samp{ymm7h} for i386 49448@item 49449@samp{ymm0h} through @samp{ymm15h} for amd64 49450@end itemize 49451 49452The @samp{org.gnu.gdb.i386.mpx} is an optional feature representing Intel 49453Memory Protection Extension (MPX). It should describe the following registers: 49454 49455@itemize @minus 49456@item 49457@samp{bnd0raw} through @samp{bnd3raw} for i386 and amd64. 49458@item 49459@samp{bndcfgu} and @samp{bndstatus} for i386 and amd64. 49460@end itemize 49461 49462The @samp{org.gnu.gdb.i386.linux} feature is optional. It should 49463describe a single register, @samp{orig_eax}. 49464 49465The @samp{org.gnu.gdb.i386.segments} feature is optional. It should 49466describe two system registers: @samp{fs_base} and @samp{gs_base}. 49467 49468The @samp{org.gnu.gdb.i386.avx512} feature is optional and requires the 49469@samp{org.gnu.gdb.i386.avx} feature. It should 49470describe additional @sc{xmm} registers: 49471 49472@itemize @minus 49473@item 49474@samp{xmm16h} through @samp{xmm31h}, only valid for amd64. 49475@end itemize 49476 49477It should describe the upper 128 bits of additional @sc{ymm} registers: 49478 49479@itemize @minus 49480@item 49481@samp{ymm16h} through @samp{ymm31h}, only valid for amd64. 49482@end itemize 49483 49484It should 49485describe the upper 256 bits of @sc{zmm} registers: 49486 49487@itemize @minus 49488@item 49489@samp{zmm0h} through @samp{zmm7h} for i386. 49490@item 49491@samp{zmm0h} through @samp{zmm15h} for amd64. 49492@end itemize 49493 49494It should 49495describe the additional @sc{zmm} registers: 49496 49497@itemize @minus 49498@item 49499@samp{zmm16h} through @samp{zmm31h}, only valid for amd64. 49500@end itemize 49501 49502The @samp{org.gnu.gdb.i386.pkeys} feature is optional. It should 49503describe a single register, @samp{pkru}. It is a 32-bit register 49504valid for i386 and amd64. 49505 49506@node LoongArch Features 49507@subsection LoongArch Features 49508@cindex target descriptions, LoongArch Features 49509 49510The @samp{org.gnu.gdb.loongarch.base} feature is required for LoongArch 49511targets. It should contain the registers @samp{r0} through @samp{r31}, 49512@samp{pc}, and @samp{badv}. Either the architectural names (@samp{r0}, 49513@samp{r1}, etc) can be used, or the ABI names (@samp{zero}, @samp{ra}, etc). 49514 49515The @samp{org.gnu.gdb.loongarch.fpu} feature is optional. If present, 49516it should contain registers @samp{f0} through @samp{f31}, @samp{fcc}, 49517and @samp{fcsr}. 49518 49519@node MicroBlaze Features 49520@subsection MicroBlaze Features 49521@cindex target descriptions, MicroBlaze features 49522 49523The @samp{org.gnu.gdb.microblaze.core} feature is required for MicroBlaze 49524targets. It should contain registers @samp{r0} through @samp{r31}, 49525@samp{rpc}, @samp{rmsr}, @samp{rear}, @samp{resr}, @samp{rfsr}, @samp{rbtr}, 49526@samp{rpvr}, @samp{rpvr1} through @samp{rpvr11}, @samp{redr}, @samp{rpid}, 49527@samp{rzpr}, @samp{rtlbx}, @samp{rtlbsx}, @samp{rtlblo}, and @samp{rtlbhi}. 49528 49529The @samp{org.gnu.gdb.microblaze.stack-protect} feature is optional. 49530If present, it should contain registers @samp{rshr} and @samp{rslr} 49531 49532@node MIPS Features 49533@subsection @acronym{MIPS} Features 49534@cindex target descriptions, @acronym{MIPS} features 49535 49536The @samp{org.gnu.gdb.mips.cpu} feature is required for @acronym{MIPS} targets. 49537It should contain registers @samp{r0} through @samp{r31}, @samp{lo}, 49538@samp{hi}, and @samp{pc}. They may be 32-bit or 64-bit depending 49539on the target. 49540 49541The @samp{org.gnu.gdb.mips.cp0} feature is also required. It should 49542contain at least the @samp{status}, @samp{badvaddr}, and @samp{cause} 49543registers. They may be 32-bit or 64-bit depending on the target. 49544 49545The @samp{org.gnu.gdb.mips.fpu} feature is currently required, though 49546it may be optional in a future version of @value{GDBN}. It should 49547contain registers @samp{f0} through @samp{f31}, @samp{fcsr}, and 49548@samp{fir}. They may be 32-bit or 64-bit depending on the target. 49549 49550The @samp{org.gnu.gdb.mips.dsp} feature is optional. It should 49551contain registers @samp{hi1} through @samp{hi3}, @samp{lo1} through 49552@samp{lo3}, and @samp{dspctl}. The @samp{dspctl} register should 49553be 32-bit and the rest may be 32-bit or 64-bit depending on the target. 49554 49555The @samp{org.gnu.gdb.mips.linux} feature is optional. It should 49556contain a single register, @samp{restart}, which is used by the 49557Linux kernel to control restartable syscalls. 49558 49559@node M68K Features 49560@subsection M68K Features 49561@cindex target descriptions, M68K features 49562 49563@table @code 49564@item @samp{org.gnu.gdb.m68k.core} 49565@itemx @samp{org.gnu.gdb.coldfire.core} 49566@itemx @samp{org.gnu.gdb.fido.core} 49567One of those features must be always present. 49568The feature that is present determines which flavor of m68k is 49569used. The feature that is present should contain registers 49570@samp{d0} through @samp{d7}, @samp{a0} through @samp{a5}, @samp{fp}, 49571@samp{sp}, @samp{ps} and @samp{pc}. 49572 49573@item @samp{org.gnu.gdb.coldfire.fp} 49574This feature is optional. If present, it should contain registers 49575@samp{fp0} through @samp{fp7}, @samp{fpcontrol}, @samp{fpstatus} and 49576@samp{fpiaddr}. 49577 49578Note that, despite the fact that this feature's name says 49579@samp{coldfire}, it is used to describe any floating point registers. 49580The size of the registers must match the main m68k flavor; so, for 49581example, if the primary feature is reported as @samp{coldfire}, then 4958264-bit floating point registers are required. 49583@end table 49584 49585@node NDS32 Features 49586@subsection NDS32 Features 49587@cindex target descriptions, NDS32 features 49588 49589The @samp{org.gnu.gdb.nds32.core} feature is required for NDS32 49590targets. It should contain at least registers @samp{r0} through 49591@samp{r10}, @samp{r15}, @samp{fp}, @samp{gp}, @samp{lp}, @samp{sp}, 49592and @samp{pc}. 49593 49594The @samp{org.gnu.gdb.nds32.fpu} feature is optional. If present, 49595it should contain 64-bit double-precision floating-point registers 49596@samp{fd0} through @emph{fdN}, which should be @samp{fd3}, @samp{fd7}, 49597@samp{fd15}, or @samp{fd31} based on the FPU configuration implemented. 49598 49599@emph{Note:} The first sixteen 64-bit double-precision floating-point 49600registers are overlapped with the thirty-two 32-bit single-precision 49601floating-point registers. The 32-bit single-precision registers, if 49602not being listed explicitly, will be synthesized from halves of the 49603overlapping 64-bit double-precision registers. Listing 32-bit 49604single-precision registers explicitly is deprecated, and the 49605support to it could be totally removed some day. 49606 49607@node Nios II Features 49608@subsection Nios II Features 49609@cindex target descriptions, Nios II features 49610 49611The @samp{org.gnu.gdb.nios2.cpu} feature is required for Nios II 49612targets. It should contain the 32 core registers (@samp{zero}, 49613@samp{at}, @samp{r2} through @samp{r23}, @samp{et} through @samp{ra}), 49614@samp{pc}, and the 16 control registers (@samp{status} through 49615@samp{mpuacc}). 49616 49617@node OpenRISC 1000 Features 49618@subsection Openrisc 1000 Features 49619@cindex target descriptions, OpenRISC 1000 features 49620 49621The @samp{org.gnu.gdb.or1k.group0} feature is required for OpenRISC 1000 49622targets. It should contain the 32 general purpose registers (@samp{r0} 49623through @samp{r31}), @samp{ppc}, @samp{npc} and @samp{sr}. 49624 49625@node PowerPC Features 49626@subsection PowerPC Features 49627@cindex target descriptions, PowerPC features 49628 49629The @samp{org.gnu.gdb.power.core} feature is required for PowerPC 49630targets. It should contain registers @samp{r0} through @samp{r31}, 49631@samp{pc}, @samp{msr}, @samp{cr}, @samp{lr}, @samp{ctr}, and 49632@samp{xer}. They may be 32-bit or 64-bit depending on the target. 49633 49634The @samp{org.gnu.gdb.power.fpu} feature is optional. It should 49635contain registers @samp{f0} through @samp{f31} and @samp{fpscr}. 49636 49637The @samp{org.gnu.gdb.power.altivec} feature is optional. It should 49638contain registers @samp{vr0} through @samp{vr31}, @samp{vscr}, and 49639@samp{vrsave}. @value{GDBN} will define pseudo-registers @samp{v0} 49640through @samp{v31} as aliases for the corresponding @samp{vrX} 49641registers. 49642 49643The @samp{org.gnu.gdb.power.vsx} feature is optional. It should 49644contain registers @samp{vs0h} through @samp{vs31h}. @value{GDBN} will 49645combine these registers with the floating point registers (@samp{f0} 49646through @samp{f31}) and the altivec registers (@samp{vr0} through 49647@samp{vr31}) to present the 128-bit wide registers @samp{vs0} through 49648@samp{vs63}, the set of vector-scalar registers for POWER7. 49649Therefore, this feature requires both @samp{org.gnu.gdb.power.fpu} and 49650@samp{org.gnu.gdb.power.altivec}. 49651 49652The @samp{org.gnu.gdb.power.spe} feature is optional. It should 49653contain registers @samp{ev0h} through @samp{ev31h}, @samp{acc}, and 49654@samp{spefscr}. SPE targets should provide 32-bit registers in 49655@samp{org.gnu.gdb.power.core} and provide the upper halves in 49656@samp{ev0h} through @samp{ev31h}. @value{GDBN} will combine 49657these to present registers @samp{ev0} through @samp{ev31} to the 49658user. 49659 49660The @samp{org.gnu.gdb.power.ppr} feature is optional. It should 49661contain the 64-bit register @samp{ppr}. 49662 49663The @samp{org.gnu.gdb.power.dscr} feature is optional. It should 49664contain the 64-bit register @samp{dscr}. 49665 49666The @samp{org.gnu.gdb.power.tar} feature is optional. It should 49667contain the 64-bit register @samp{tar}. 49668 49669The @samp{org.gnu.gdb.power.ebb} feature is optional. It should 49670contain registers @samp{bescr}, @samp{ebbhr} and @samp{ebbrr}, all 4967164-bit wide. 49672 49673The @samp{org.gnu.gdb.power.linux.pmu} feature is optional. It should 49674contain registers @samp{mmcr0}, @samp{mmcr2}, @samp{siar}, @samp{sdar} 49675and @samp{sier}, all 64-bit wide. This is the subset of the isa 2.07 49676server PMU registers provided by @sc{gnu}/Linux. 49677 49678The @samp{org.gnu.gdb.power.htm.spr} feature is optional. It should 49679contain registers @samp{tfhar}, @samp{texasr} and @samp{tfiar}, all 4968064-bit wide. 49681 49682The @samp{org.gnu.gdb.power.htm.core} feature is optional. It should 49683contain the checkpointed general-purpose registers @samp{cr0} through 49684@samp{cr31}, as well as the checkpointed registers @samp{clr} and 49685@samp{cctr}. These registers may all be either 32-bit or 64-bit 49686depending on the target. It should also contain the checkpointed 49687registers @samp{ccr} and @samp{cxer}, which should both be 32-bit 49688wide. 49689 49690The @samp{org.gnu.gdb.power.htm.fpu} feature is optional. It should 49691contain the checkpointed 64-bit floating-point registers @samp{cf0} 49692through @samp{cf31}, as well as the checkpointed 64-bit register 49693@samp{cfpscr}. 49694 49695The @samp{org.gnu.gdb.power.htm.altivec} feature is optional. It 49696should contain the checkpointed altivec registers @samp{cvr0} through 49697@samp{cvr31}, all 128-bit wide. It should also contain the 49698checkpointed registers @samp{cvscr} and @samp{cvrsave}, both 32-bit 49699wide. 49700 49701The @samp{org.gnu.gdb.power.htm.vsx} feature is optional. It should 49702contain registers @samp{cvs0h} through @samp{cvs31h}. @value{GDBN} 49703will combine these registers with the checkpointed floating point 49704registers (@samp{cf0} through @samp{cf31}) and the checkpointed 49705altivec registers (@samp{cvr0} through @samp{cvr31}) to present the 49706128-bit wide checkpointed vector-scalar registers @samp{cvs0} through 49707@samp{cvs63}. Therefore, this feature requires both 49708@samp{org.gnu.gdb.power.htm.altivec} and 49709@samp{org.gnu.gdb.power.htm.fpu}. 49710 49711The @samp{org.gnu.gdb.power.htm.ppr} feature is optional. It should 49712contain the 64-bit checkpointed register @samp{cppr}. 49713 49714The @samp{org.gnu.gdb.power.htm.dscr} feature is optional. It should 49715contain the 64-bit checkpointed register @samp{cdscr}. 49716 49717The @samp{org.gnu.gdb.power.htm.tar} feature is optional. It should 49718contain the 64-bit checkpointed register @samp{ctar}. 49719 49720 49721@node RISC-V Features 49722@subsection RISC-V Features 49723@cindex target descriptions, RISC-V Features 49724 49725The @samp{org.gnu.gdb.riscv.cpu} feature is required for RISC-V 49726targets. It should contain the registers @samp{x0} through 49727@samp{x31}, and @samp{pc}. Either the architectural names (@samp{x0}, 49728@samp{x1}, etc) can be used, or the ABI names (@samp{zero}, @samp{ra}, 49729etc). 49730 49731The @samp{org.gnu.gdb.riscv.fpu} feature is optional. If present, it 49732should contain registers @samp{f0} through @samp{f31}, @samp{fflags}, 49733@samp{frm}, and @samp{fcsr}. As with the cpu feature, either the 49734architectural register names, or the ABI names can be used. 49735 49736The @samp{org.gnu.gdb.riscv.virtual} feature is optional. If present, 49737it should contain registers that are not backed by real registers on 49738the target, but are instead virtual, where the register value is 49739derived from other target state. In many ways these are like 49740@value{GDBN}s pseudo-registers, except implemented by the target. 49741Currently the only register expected in this set is the one byte 49742@samp{priv} register that contains the target's privilege level in the 49743least significant two bits. 49744 49745The @samp{org.gnu.gdb.riscv.csr} feature is optional. If present, it 49746should contain all of the target's standard CSRs. Standard CSRs are 49747those defined in the RISC-V specification documents. There is some 49748overlap between this feature and the fpu feature; the @samp{fflags}, 49749@samp{frm}, and @samp{fcsr} registers could be in either feature. The 49750expectation is that these registers will be in the fpu feature if the 49751target has floating point hardware, but can be moved into the csr 49752feature if the target has the floating point control registers, but no 49753other floating point hardware. 49754 49755The @samp{org.gnu.gdb.riscv.vector} feature is optional. If present, 49756it should contain registers @samp{v0} through @samp{v31}, all of which 49757must be the same size. 49758 49759@node RX Features 49760@subsection RX Features 49761@cindex target descriptions, RX Features 49762 49763The @samp{org.gnu.gdb.rx.core} feature is required for RX 49764targets. It should contain the registers @samp{r0} through 49765@samp{r15}, @samp{usp}, @samp{isp}, @samp{psw}, @samp{pc}, @samp{intb}, 49766@samp{bpsw}, @samp{bpc}, @samp{fintv}, @samp{fpsw}, and @samp{acc}. 49767 49768@node S/390 and System z Features 49769@subsection S/390 and System z Features 49770@cindex target descriptions, S/390 features 49771@cindex target descriptions, System z features 49772 49773The @samp{org.gnu.gdb.s390.core} feature is required for S/390 and 49774System z targets. It should contain the PSW and the 16 general 49775registers. In particular, System z targets should provide the 64-bit 49776registers @samp{pswm}, @samp{pswa}, and @samp{r0} through @samp{r15}. 49777S/390 targets should provide the 32-bit versions of these registers. 49778A System z target that runs in 31-bit addressing mode should provide 4977932-bit versions of @samp{pswm} and @samp{pswa}, as well as the general 49780register's upper halves @samp{r0h} through @samp{r15h}, and their 49781lower halves @samp{r0l} through @samp{r15l}. 49782 49783The @samp{org.gnu.gdb.s390.fpr} feature is required. It should 49784contain the 64-bit registers @samp{f0} through @samp{f15}, and 49785@samp{fpc}. 49786 49787The @samp{org.gnu.gdb.s390.acr} feature is required. It should 49788contain the 32-bit registers @samp{acr0} through @samp{acr15}. 49789 49790The @samp{org.gnu.gdb.s390.linux} feature is optional. It should 49791contain the register @samp{orig_r2}, which is 64-bit wide on System z 49792targets and 32-bit otherwise. In addition, the feature may contain 49793the @samp{last_break} register, whose width depends on the addressing 49794mode, as well as the @samp{system_call} register, which is always 4979532-bit wide. 49796 49797The @samp{org.gnu.gdb.s390.tdb} feature is optional. It should 49798contain the 64-bit registers @samp{tdb0}, @samp{tac}, @samp{tct}, 49799@samp{atia}, and @samp{tr0} through @samp{tr15}. 49800 49801The @samp{org.gnu.gdb.s390.vx} feature is optional. It should contain 4980264-bit wide registers @samp{v0l} through @samp{v15l}, which will be 49803combined by @value{GDBN} with the floating point registers @samp{f0} 49804through @samp{f15} to present the 128-bit wide vector registers 49805@samp{v0} through @samp{v15}. In addition, this feature should 49806contain the 128-bit wide vector registers @samp{v16} through 49807@samp{v31}. 49808 49809The @samp{org.gnu.gdb.s390.gs} feature is optional. It should contain 49810the 64-bit wide guarded-storage-control registers @samp{gsd}, 49811@samp{gssm}, and @samp{gsepla}. 49812 49813The @samp{org.gnu.gdb.s390.gsbc} feature is optional. It should contain 49814the 64-bit wide guarded-storage broadcast control registers 49815@samp{bc_gsd}, @samp{bc_gssm}, and @samp{bc_gsepla}. 49816 49817@node Sparc Features 49818@subsection Sparc Features 49819@cindex target descriptions, sparc32 features 49820@cindex target descriptions, sparc64 features 49821The @samp{org.gnu.gdb.sparc.cpu} feature is required for sparc32/sparc64 49822targets. It should describe the following registers: 49823 49824@itemize @minus 49825@item 49826@samp{g0} through @samp{g7} 49827@item 49828@samp{o0} through @samp{o7} 49829@item 49830@samp{l0} through @samp{l7} 49831@item 49832@samp{i0} through @samp{i7} 49833@end itemize 49834 49835They may be 32-bit or 64-bit depending on the target. 49836 49837Also the @samp{org.gnu.gdb.sparc.fpu} feature is required for sparc32/sparc64 49838targets. It should describe the following registers: 49839 49840@itemize @minus 49841@item 49842@samp{f0} through @samp{f31} 49843@item 49844@samp{f32} through @samp{f62} for sparc64 49845@end itemize 49846 49847The @samp{org.gnu.gdb.sparc.cp0} feature is required for sparc32/sparc64 49848targets. It should describe the following registers: 49849 49850@itemize @minus 49851@item 49852@samp{y}, @samp{psr}, @samp{wim}, @samp{tbr}, @samp{pc}, @samp{npc}, 49853@samp{fsr}, and @samp{csr} for sparc32 49854@item 49855@samp{pc}, @samp{npc}, @samp{state}, @samp{fsr}, @samp{fprs}, and @samp{y} 49856for sparc64 49857@end itemize 49858 49859@node TIC6x Features 49860@subsection TMS320C6x Features 49861@cindex target descriptions, TIC6x features 49862@cindex target descriptions, TMS320C6x features 49863The @samp{org.gnu.gdb.tic6x.core} feature is required for TMS320C6x 49864targets. It should contain registers @samp{A0} through @samp{A15}, 49865registers @samp{B0} through @samp{B15}, @samp{CSR} and @samp{PC}. 49866 49867The @samp{org.gnu.gdb.tic6x.gp} feature is optional. It should 49868contain registers @samp{A16} through @samp{A31} and @samp{B16} 49869through @samp{B31}. 49870 49871The @samp{org.gnu.gdb.tic6x.c6xp} feature is optional. It should 49872contain registers @samp{TSR}, @samp{ILC} and @samp{RILC}. 49873 49874@node Operating System Information 49875@appendix Operating System Information 49876@cindex operating system information 49877 49878Users of @value{GDBN} often wish to obtain information about the state of 49879the operating system running on the target---for example the list of 49880processes, or the list of open files. This section describes the 49881mechanism that makes it possible. This mechanism is similar to the 49882target features mechanism (@pxref{Target Descriptions}), but focuses 49883on a different aspect of target. 49884 49885Operating system information is retrieved from the target via the 49886remote protocol, using @samp{qXfer} requests (@pxref{qXfer osdata 49887read}). The object name in the request should be @samp{osdata}, and 49888the @var{annex} identifies the data to be fetched. 49889 49890@menu 49891* Process list:: 49892@end menu 49893 49894@node Process list 49895@appendixsection Process list 49896@cindex operating system information, process list 49897 49898When requesting the process list, the @var{annex} field in the 49899@samp{qXfer} request should be @samp{processes}. The returned data is 49900an XML document. The formal syntax of this document is defined in 49901@file{gdb/features/osdata.dtd}. 49902 49903An example document is: 49904 49905@smallexample 49906<?xml version="1.0"?> 49907<!DOCTYPE target SYSTEM "osdata.dtd"> 49908<osdata type="processes"> 49909 <item> 49910 <column name="pid">1</column> 49911 <column name="user">root</column> 49912 <column name="command">/sbin/init</column> 49913 <column name="cores">1,2,3</column> 49914 </item> 49915</osdata> 49916@end smallexample 49917 49918Each item should include a column whose name is @samp{pid}. The value 49919of that column should identify the process on the target. The 49920@samp{user} and @samp{command} columns are optional, and will be 49921displayed by @value{GDBN}. The @samp{cores} column, if present, 49922should contain a comma-separated list of cores that this process 49923is running on. Target may provide additional columns, 49924which @value{GDBN} currently ignores. 49925 49926@node Trace File Format 49927@appendix Trace File Format 49928@cindex trace file format 49929 49930The trace file comes in three parts: a header, a textual description 49931section, and a trace frame section with binary data. 49932 49933The header has the form @code{\x7fTRACE0\n}. The first byte is 49934@code{0x7f} so as to indicate that the file contains binary data, 49935while the @code{0} is a version number that may have different values 49936in the future. 49937 49938The description section consists of multiple lines of @sc{ascii} text 49939separated by newline characters (@code{0xa}). The lines may include a 49940variety of optional descriptive or context-setting information, such 49941as tracepoint definitions or register set size. @value{GDBN} will 49942ignore any line that it does not recognize. An empty line marks the end 49943of this section. 49944 49945@table @code 49946@item R @var{size} 49947Specifies the size of a register block in bytes. This is equal to the 49948size of a @code{g} packet payload in the remote protocol. @var{size} 49949is an ascii decimal number. There should be only one such line in 49950a single trace file. 49951 49952@item status @var{status} 49953Trace status. @var{status} has the same format as a @code{qTStatus} 49954remote packet reply. There should be only one such line in a single trace 49955file. 49956 49957@item tp @var{payload} 49958Tracepoint definition. The @var{payload} has the same format as 49959@code{qTfP}/@code{qTsP} remote packet reply payload. A single tracepoint 49960may take multiple lines of definition, corresponding to the multiple 49961reply packets. 49962 49963@item tsv @var{payload} 49964Trace state variable definition. The @var{payload} has the same format as 49965@code{qTfV}/@code{qTsV} remote packet reply payload. A single variable 49966may take multiple lines of definition, corresponding to the multiple 49967reply packets. 49968 49969@item tdesc @var{payload} 49970Target description in XML format. The @var{payload} is a single line of 49971the XML file. All such lines should be concatenated together to get 49972the original XML file. This file is in the same format as @code{qXfer} 49973@code{features} payload, and corresponds to the main @code{target.xml} 49974file. Includes are not allowed. 49975 49976@end table 49977 49978The trace frame section consists of a number of consecutive frames. 49979Each frame begins with a two-byte tracepoint number, followed by a 49980four-byte size giving the amount of data in the frame. The data in 49981the frame consists of a number of blocks, each introduced by a 49982character indicating its type (at least register, memory, and trace 49983state variable). The data in this section is raw binary, not a 49984hexadecimal or other encoding; its endianness matches the target's 49985endianness. 49986 49987@c FIXME bi-arch may require endianness/arch info in description section 49988 49989@table @code 49990@item R @var{bytes} 49991Register block. The number and ordering of bytes matches that of a 49992@code{g} packet in the remote protocol. Note that these are the 49993actual bytes, in target order, not a hexadecimal encoding. 49994 49995@item M @var{address} @var{length} @var{bytes}... 49996Memory block. This is a contiguous block of memory, at the 8-byte 49997address @var{address}, with a 2-byte length @var{length}, followed by 49998@var{length} bytes. 49999 50000@item V @var{number} @var{value} 50001Trace state variable block. This records the 8-byte signed value 50002@var{value} of trace state variable numbered @var{number}. 50003 50004@end table 50005 50006Future enhancements of the trace file format may include additional types 50007of blocks. 50008 50009@node Index Section Format 50010@appendix @code{.gdb_index} section format 50011@cindex .gdb_index section format 50012@cindex index section format 50013 50014This section documents the index section that is created by @code{save 50015gdb-index} (@pxref{Index Files}). The index section is 50016DWARF-specific; some knowledge of DWARF is assumed in this 50017description. 50018 50019The mapped index file format is designed to be directly 50020@code{mmap}able on any architecture. In most cases, a datum is 50021represented using a little-endian 32-bit integer value, called an 50022@code{offset_type}. Big endian machines must byte-swap the values 50023before using them. Exceptions to this rule are noted. The data is 50024laid out such that alignment is always respected. 50025 50026A mapped index consists of several areas, laid out in order. 50027 50028@enumerate 50029@item 50030The file header. This is a sequence of values, of @code{offset_type} 50031unless otherwise noted: 50032 50033@enumerate 50034@item 50035The version number, currently 9. Versions 1, 2 and 3 are obsolete. 50036Version 4 uses a different hashing function from versions 5 and 6. 50037Version 6 includes symbols for inlined functions, whereas versions 4 50038and 5 do not. Version 7 adds attributes to the CU indices in the 50039symbol table. Version 8 specifies that symbols from DWARF type units 50040(@samp{DW_TAG_type_unit}) refer to the type unit's symbol table and not the 50041compilation unit (@samp{DW_TAG_comp_unit}) using the type. Version 9 adds 50042the name and the language of the main function to the index. 50043 50044@value{GDBN} will only read version 4, 5, or 6 indices 50045by specifying @code{set use-deprecated-index-sections on}. 50046GDB has a workaround for potentially broken version 7 indices so it is 50047currently not flagged as deprecated. 50048 50049@item 50050The offset, from the start of the file, of the CU list. 50051 50052@item 50053The offset, from the start of the file, of the types CU list. Note 50054that this area can be empty, in which case this offset will be equal 50055to the next offset. 50056 50057@item 50058The offset, from the start of the file, of the address area. 50059 50060@item 50061The offset, from the start of the file, of the symbol table. 50062 50063@item 50064The offset, from the start of the file, of the shortcut table. 50065 50066@item 50067The offset, from the start of the file, of the constant pool. 50068@end enumerate 50069 50070@item 50071The CU list. This is a sequence of pairs of 64-bit little-endian 50072values, sorted by the CU offset. The first element in each pair is 50073the offset of a CU in the @code{.debug_info} section. The second 50074element in each pair is the length of that CU. References to a CU 50075elsewhere in the map are done using a CU index, which is just the 500760-based index into this table. Note that if there are type CUs, then 50077conceptually CUs and type CUs form a single list for the purposes of 50078CU indices. 50079 50080@item 50081The types CU list. This is a sequence of triplets of 64-bit 50082little-endian values. In a triplet, the first value is the CU offset, 50083the second value is the type offset in the CU, and the third value is 50084the type signature. The types CU list is not sorted. 50085 50086@item 50087The address area. The address area consists of a sequence of address 50088entries. Each address entry has three elements: 50089 50090@enumerate 50091@item 50092The low address. This is a 64-bit little-endian value. 50093 50094@item 50095The high address. This is a 64-bit little-endian value. Like 50096@code{DW_AT_high_pc}, the value is one byte beyond the end. 50097 50098@item 50099The CU index. This is an @code{offset_type} value. 50100@end enumerate 50101 50102@item 50103The symbol table. This is an open-addressed hash table. The size of 50104the hash table is always a power of 2. 50105 50106Each slot in the hash table consists of a pair of @code{offset_type} 50107values. The first value is the offset of the symbol's name in the 50108constant pool. The second value is the offset of the CU vector in the 50109constant pool. 50110 50111If both values are 0, then this slot in the hash table is empty. This 50112is ok because while 0 is a valid constant pool index, it cannot be a 50113valid index for both a string and a CU vector. 50114 50115The hash value for a table entry is computed by applying an 50116iterative hash function to the symbol's name. Starting with an 50117initial value of @code{r = 0}, each (unsigned) character @samp{c} in 50118the string is incorporated into the hash using the formula depending on the 50119index version: 50120 50121@table @asis 50122@item Version 4 50123The formula is @code{r = r * 67 + c - 113}. 50124 50125@item Versions 5 to 7 50126The formula is @code{r = r * 67 + tolower (c) - 113}. 50127@end table 50128 50129The terminating @samp{\0} is not incorporated into the hash. 50130 50131The step size used in the hash table is computed via 50132@code{((hash * 17) & (size - 1)) | 1}, where @samp{hash} is the hash 50133value, and @samp{size} is the size of the hash table. The step size 50134is used to find the next candidate slot when handling a hash 50135collision. 50136 50137The names of C@t{++} symbols in the hash table are canonicalized. We 50138don't currently have a simple description of the canonicalization 50139algorithm; if you intend to create new index sections, you must read 50140the code. 50141 50142@item The shortcut table 50143This is a data structure with the following fields: 50144 50145@table @asis 50146@item Language of main 50147An @code{offset_type} value indicating the language of the main function as a 50148@code{DW_LANG_} constant. This value will be zero if main function information 50149is not present. 50150 50151@item Name of main 50152An @code{offset_type} value indicating the offset of the main function's name 50153in the constant pool. This value must be ignored if the value for the language 50154of main is zero. 50155@end table 50156 50157@item 50158The constant pool. This is simply a bunch of bytes. It is organized 50159so that alignment is correct: CU vectors are stored first, followed by 50160strings. 50161 50162A CU vector in the constant pool is a sequence of @code{offset_type} 50163values. The first value is the number of CU indices in the vector. 50164Each subsequent value is the index and symbol attributes of a CU in 50165the CU list. This element in the hash table is used to indicate which 50166CUs define the symbol and how the symbol is used. 50167See below for the format of each CU index+attributes entry. 50168 50169A string in the constant pool is zero-terminated. 50170@end enumerate 50171 50172Attributes were added to CU index values in @code{.gdb_index} version 7. 50173If a symbol has multiple uses within a CU then there is one 50174CU index+attributes value for each use. 50175 50176The format of each CU index+attributes entry is as follows 50177(bit 0 = LSB): 50178 50179@table @asis 50180 50181@item Bits 0-23 50182This is the index of the CU in the CU list. 50183@item Bits 24-27 50184These bits are reserved for future purposes and must be zero. 50185@item Bits 28-30 50186The kind of the symbol in the CU. 50187 50188@table @asis 50189@item 0 50190This value is reserved and should not be used. 50191By reserving zero the full @code{offset_type} value is backwards compatible 50192with previous versions of the index. 50193@item 1 50194The symbol is a type. 50195@item 2 50196The symbol is a variable or an enum value. 50197@item 3 50198The symbol is a function. 50199@item 4 50200Any other kind of symbol. 50201@item 5,6,7 50202These values are reserved. 50203@end table 50204 50205@item Bit 31 50206This bit is zero if the value is global and one if it is static. 50207 50208The determination of whether a symbol is global or static is complicated. 50209The authoritative reference is the file @file{dwarf2read.c} in 50210@value{GDBN} sources. 50211 50212@end table 50213 50214This pseudo-code describes the computation of a symbol's kind and 50215global/static attributes in the index. 50216 50217@smallexample 50218is_external = get_attribute (die, DW_AT_external); 50219language = get_attribute (cu_die, DW_AT_language); 50220switch (die->tag) 50221 @{ 50222 case DW_TAG_typedef: 50223 case DW_TAG_base_type: 50224 case DW_TAG_subrange_type: 50225 kind = TYPE; 50226 is_static = 1; 50227 break; 50228 case DW_TAG_enumerator: 50229 kind = VARIABLE; 50230 is_static = language != CPLUS; 50231 break; 50232 case DW_TAG_subprogram: 50233 kind = FUNCTION; 50234 is_static = ! (is_external || language == ADA); 50235 break; 50236 case DW_TAG_constant: 50237 kind = VARIABLE; 50238 is_static = ! is_external; 50239 break; 50240 case DW_TAG_variable: 50241 kind = VARIABLE; 50242 is_static = ! is_external; 50243 break; 50244 case DW_TAG_namespace: 50245 kind = TYPE; 50246 is_static = 0; 50247 break; 50248 case DW_TAG_class_type: 50249 case DW_TAG_interface_type: 50250 case DW_TAG_structure_type: 50251 case DW_TAG_union_type: 50252 case DW_TAG_enumeration_type: 50253 kind = TYPE; 50254 is_static = language != CPLUS; 50255 break; 50256 default: 50257 assert (0); 50258 @} 50259@end smallexample 50260 50261@node Debuginfod 50262@appendix Download debugging resources with Debuginfod 50263@cindex debuginfod 50264 50265@code{debuginfod} is an HTTP server for distributing ELF, DWARF and source 50266files. 50267 50268With the @code{debuginfod} client library, @file{libdebuginfod}, @value{GDBN} 50269can query servers using the build IDs associated with missing debug info, 50270executables and source files in order to download them on demand. 50271 50272For instructions on building @value{GDBN} with @file{libdebuginfod}, 50273@pxref{Configure Options,,--with-debuginfod}. @code{debuginfod} is packaged 50274with @code{elfutils}, starting with version 0.178. See 50275@uref{https://sourceware.org/elfutils/Debuginfod.html} for more information 50276regarding @code{debuginfod}. 50277 50278@menu 50279* Debuginfod Settings:: Configuring debuginfod with @value{GDBN} 50280@end menu 50281 50282@node Debuginfod Settings 50283@section Debuginfod Settings 50284 50285@value{GDBN} provides the following commands for configuring @code{debuginfod}. 50286 50287@table @code 50288@kindex set debuginfod enabled 50289@anchor{set debuginfod enabled} 50290@item set debuginfod enabled 50291@itemx set debuginfod enabled on 50292@cindex enable debuginfod 50293@value{GDBN} may query @code{debuginfod} servers for missing debug info and 50294source files. @value{GDBN} may also download individual ELF/DWARF sections 50295such as @code{.gdb_index} to help reduce the total amount of data downloaded 50296from @code{debuginfod} servers; this can be controlled by @w{@code{maint 50297set debuginfod download-sections}} (@pxref{Maintenance Commands, maint set 50298debuginfod download-sections}). 50299 50300@item set debuginfod enabled off 50301@value{GDBN} will not attempt to query @code{debuginfod} servers when missing 50302debug info or source files. By default, @code{debuginfod enabled} is set to 50303@code{off} for non-interactive sessions. 50304 50305@item set debuginfod enabled ask 50306@value{GDBN} will prompt the user to enable or disable @code{debuginfod} before 50307attempting to perform the next query. By default, @code{debuginfod enabled} 50308is set to @code{ask} for interactive sessions. 50309 50310@kindex show debuginfod enabled 50311@item show debuginfod enabled 50312Display whether @code{debuginfod enabled} is set to @code{on}, @code{off} or 50313@code{ask}. 50314 50315@kindex set debuginfod urls 50316@cindex configure debuginfod URLs 50317@item set debuginfod urls 50318@itemx set debuginfod urls @var{urls} 50319Set the space-separated list of URLs that @code{debuginfod} will attempt to 50320query. Only @code{http://}, @code{https://} and @code{file://} protocols 50321should be used. The default value of @code{debuginfod urls} is copied from 50322the @var{DEBUGINFOD_URLS} environment variable. 50323 50324@kindex show debuginfod urls 50325@item show debuginfod urls 50326Display the list of URLs that @code{debuginfod} will attempt to query. 50327 50328@kindex set debuginfod verbose 50329@cindex debuginfod verbosity 50330@item set debuginfod verbose 50331@itemx set debuginfod verbose @var{n} 50332Enable or disable @code{debuginfod}-related output. Use a non-zero value 50333to enable and @code{0} to disable. @code{debuginfod} output is shown by 50334default. 50335 50336@kindex show debuginfod verbose 50337@item show debuginfod verbose 50338Show the current verbosity setting. 50339 50340@end table 50341 50342@node Man Pages 50343@appendix Manual pages 50344@cindex Man pages 50345 50346@menu 50347* gdb man:: The GNU Debugger man page 50348* gdbserver man:: Remote Server for the GNU Debugger man page 50349* gcore man:: Generate a core file of a running program 50350* gdbinit man:: gdbinit scripts 50351* gdb-add-index man:: Add index files to speed up GDB 50352@end menu 50353 50354@node gdb man 50355@heading gdb man 50356 50357@c man title gdb The GNU Debugger 50358 50359@c man begin SYNOPSIS gdb 50360gdb [OPTIONS] [@var{prog}|@var{prog} @var{procID}|@var{prog} @var{core}] 50361@c man end 50362 50363@c man begin DESCRIPTION gdb 50364The purpose of a debugger such as @value{GDBN} is to allow you to see what is 50365going on ``inside'' another program while it executes -- or what another 50366program was doing at the moment it crashed. 50367 50368@value{GDBN} can do four main kinds of things (plus other things in support of 50369these) to help you catch bugs in the act: 50370 50371@itemize @bullet 50372@item 50373Start your program, specifying anything that might affect its behavior. 50374 50375@item 50376Make your program stop on specified conditions. 50377 50378@item 50379Examine what has happened, when your program has stopped. 50380 50381@item 50382Change things in your program, so you can experiment with correcting the 50383effects of one bug and go on to learn about another. 50384@end itemize 50385 50386You can use @value{GDBN} to debug programs written in C, C@t{++}, Fortran and 50387Modula-2. 50388 50389@value{GDBN} is invoked with the shell command @code{gdb}. Once started, it reads 50390commands from the terminal until you tell it to exit with the @value{GDBN} 50391command @code{quit} or @code{exit}. You can get online help from @value{GDBN} itself 50392by using the command @code{help}. 50393 50394You can run @code{gdb} with no arguments or options; but the most 50395usual way to start @value{GDBN} is with one argument or two, specifying an 50396executable program as the argument: 50397 50398@smallexample 50399gdb program 50400@end smallexample 50401 50402You can also start with both an executable program and a core file specified: 50403 50404@smallexample 50405gdb program core 50406@end smallexample 50407 50408You can, instead, specify a process ID as a second argument or use option 50409@code{-p}, if you want to debug a running process: 50410 50411@smallexample 50412gdb program 1234 50413gdb -p 1234 50414@end smallexample 50415 50416@noindent 50417would attach @value{GDBN} to process @code{1234}. With option @option{-p} you 50418can omit the @var{program} filename. 50419 50420Here are some of the most frequently needed @value{GDBN} commands: 50421 50422@c pod2man highlights the right hand side of the @item lines. 50423@table @env 50424@item break [@var{file}:][@var{function}|@var{line}] 50425Set a breakpoint at @var{function} or @var{line} (in @var{file}). 50426 50427@item run [@var{arglist}] 50428Start your program (with @var{arglist}, if specified). 50429 50430@item bt 50431Backtrace: display the program stack. 50432 50433@item print @var{expr} 50434Display the value of an expression. 50435 50436@item c 50437Continue running your program (after stopping, e.g.@: at a breakpoint). 50438 50439@item next 50440Execute next program line (after stopping); step @emph{over} any 50441function calls in the line. 50442 50443@item edit [@var{file}:]@var{function} 50444look at the program line where it is presently stopped. 50445 50446@item list [@var{file}:]@var{function} 50447type the text of the program in the vicinity of where it is presently stopped. 50448 50449@item step 50450Execute next program line (after stopping); step @emph{into} any 50451function calls in the line. 50452 50453@item help [@var{name}] 50454Show information about @value{GDBN} command @var{name}, or general information 50455about using @value{GDBN}. 50456 50457@item quit 50458@itemx exit 50459Exit from @value{GDBN}. 50460@end table 50461 50462@ifset man 50463For full details on @value{GDBN}, 50464see @cite{Using GDB: A Guide to the GNU Source-Level Debugger}, 50465by Richard M. Stallman and Roland H. Pesch. The same text is available online 50466as the @code{gdb} entry in the @code{info} program. 50467@end ifset 50468@c man end 50469 50470@c man begin OPTIONS gdb 50471Any arguments other than options specify an executable 50472file and core file (or process ID); that is, the first argument 50473encountered with no 50474associated option flag is equivalent to a @option{--se} option, and the second, 50475if any, is equivalent to a @option{-c} option if it's the name of a file. 50476Many options have 50477both long and abbreviated forms; both are shown here. The long forms are also 50478recognized if you truncate them, so long as enough of the option is 50479present to be unambiguous. 50480 50481The abbreviated forms are shown here with @samp{-} and long forms are shown 50482with @samp{--} to reflect how they are shown in @option{--help}. However, 50483@value{GDBN} recognizes all of the following conventions for most options: 50484 50485@table @code 50486@item --option=@var{value} 50487@item --option @var{value} 50488@item -option=@var{value} 50489@item -option @var{value} 50490@item --o=@var{value} 50491@item --o @var{value} 50492@item -o=@var{value} 50493@item -o @var{value} 50494@end table 50495 50496All the options and command line arguments you give are processed 50497in sequential order. The order makes a difference when the @option{-x} 50498option is used. 50499 50500@table @env 50501@item --help 50502@itemx -h 50503List all options, with brief explanations. 50504 50505@item --symbols=@var{file} 50506@itemx -s @var{file} 50507Read symbol table from @var{file}. 50508 50509@item --write 50510Enable writing into executable and core files. 50511 50512@item --exec=@var{file} 50513@itemx -e @var{file} 50514Use @var{file} as the executable file to execute when 50515appropriate, and for examining pure data in conjunction with a core 50516dump. 50517 50518@item --se=@var{file} 50519Read symbol table from @var{file} and use it as the executable 50520file. 50521 50522@item --core=@var{file} 50523@itemx -c @var{file} 50524Use @var{file} as a core dump to examine. 50525 50526@item --command=@var{file} 50527@itemx -x @var{file} 50528Execute @value{GDBN} commands from @var{file}. 50529 50530@item --eval-command=@var{command} 50531@item -ex @var{command} 50532Execute given @value{GDBN} @var{command}. 50533 50534@item --init-eval-command=@var{command} 50535@item -iex 50536Execute @value{GDBN} @var{command} before loading the inferior. 50537 50538@item --directory=@var{directory} 50539@itemx -d @var{directory} 50540Add @var{directory} to the path to search for source files. 50541 50542@item --nh 50543Do not execute commands from @file{~/.config/gdb/gdbinit}, 50544@file{~/.gdbinit}, @file{~/.config/gdb/gdbearlyinit}, or 50545@file{~/.gdbearlyinit} 50546 50547@item --nx 50548@itemx -n 50549Do not execute commands from any @file{.gdbinit} or 50550@file{.gdbearlyinit} initialization files. 50551 50552@item --quiet 50553@item --silent 50554@itemx -q 50555``Quiet''. Do not print the introductory and copyright messages. These 50556messages are also suppressed in batch mode. 50557 50558@item --batch 50559Run in batch mode. Exit with status @code{0} after processing all the command 50560files specified with @option{-x} (and @file{.gdbinit}, if not inhibited). 50561Exit with nonzero status if an error occurs in executing the @value{GDBN} 50562commands in the command files. 50563 50564Batch mode may be useful for running @value{GDBN} as a filter, for example to 50565download and run a program on another computer; in order to make this 50566more useful, the message 50567 50568@smallexample 50569Program exited normally. 50570@end smallexample 50571 50572@noindent 50573(which is ordinarily issued whenever a program running under @value{GDBN} control 50574terminates) is not issued when running in batch mode. 50575 50576@item --batch-silent 50577Run in batch mode, just like @option{--batch}, but totally silent. All @value{GDBN} 50578output is suppressed (stderr is unaffected). This is much quieter than 50579@option{--silent} and would be useless for an interactive session. 50580 50581This is particularly useful when using targets that give @samp{Loading section} 50582messages, for example. 50583 50584Note that targets that give their output via @value{GDBN}, as opposed to writing 50585directly to @code{stdout}, will also be made silent. 50586 50587@item --args @var{prog} [@var{arglist}] 50588Change interpretation of command line so that arguments following this 50589option are passed as arguments to the inferior. As an example, take 50590the following command: 50591 50592@smallexample 50593gdb ./a.out -q 50594@end smallexample 50595 50596@noindent 50597It would start @value{GDBN} with @option{-q}, not printing the introductory message. On 50598the other hand, using: 50599 50600@smallexample 50601gdb --args ./a.out -q 50602@end smallexample 50603 50604@noindent 50605starts @value{GDBN} with the introductory message, and passes the option to the inferior. 50606 50607@item --pid=@var{pid} 50608Attach @value{GDBN} to an already running program, with the PID @var{pid}. 50609 50610@item --tui 50611Open the terminal user interface. 50612 50613@item --readnow 50614Read all symbols from the given symfile on the first access. 50615 50616@item --readnever 50617Do not read symbol files. 50618 50619@item --return-child-result 50620@value{GDBN}'s exit code will be the same as the child's exit code. 50621 50622@item --configuration 50623Print details about GDB configuration and then exit. 50624 50625@item --version 50626Print version information and then exit. 50627 50628@item --cd=@var{directory} 50629Run @value{GDBN} using @var{directory} as its working directory, 50630instead of the current directory. 50631 50632@item --data-directory=@var{directory} 50633@item -D 50634Run @value{GDBN} using @var{directory} as its data directory. The data 50635directory is where @value{GDBN} searches for its auxiliary files. 50636 50637@item --fullname 50638@itemx -f 50639Emacs sets this option when it runs @value{GDBN} as a subprocess. It tells 50640@value{GDBN} to output the full file name and line number in a standard, 50641recognizable fashion each time a stack frame is displayed (which 50642includes each time the program stops). This recognizable format looks 50643like two @samp{\032} characters, followed by the file name, line number 50644and character position separated by colons, and a newline. The 50645Emacs-to-@value{GDBN} interface program uses the two @samp{\032} 50646characters as a signal to display the source code for the frame. 50647 50648@item -b @var{baudrate} 50649Set the line speed (baud rate or bits per second) of any serial 50650interface used by @value{GDBN} for remote debugging. 50651 50652@item -l @var{timeout} 50653Set timeout, in seconds, for remote debugging. 50654 50655@item --tty=@var{device} 50656Run using @var{device} for your program's standard input and output. 50657@end table 50658@c man end 50659 50660@c man begin SEEALSO gdb 50661@ifset man 50662The full documentation for @value{GDBN} is maintained as a Texinfo manual. 50663If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo 50664documentation are properly installed at your site, the command 50665 50666@smallexample 50667info gdb 50668@end smallexample 50669 50670@noindent 50671should give you access to the complete manual. 50672 50673@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, 50674Richard M. Stallman and Roland H. Pesch, July 1991. 50675@end ifset 50676@c man end 50677 50678@node gdbserver man 50679@heading gdbserver man 50680 50681@c man title gdbserver Remote Server for the GNU Debugger 50682@format 50683@c man begin SYNOPSIS gdbserver 50684gdbserver @var{comm} @var{prog} [@var{args}@dots{}] 50685 50686gdbserver --attach @var{comm} @var{pid} 50687 50688gdbserver --multi @var{comm} 50689@c man end 50690@end format 50691 50692@c man begin DESCRIPTION gdbserver 50693@command{gdbserver} is a program that allows you to run @value{GDBN} on a different machine 50694than the one which is running the program being debugged. 50695 50696@ifclear man 50697@subheading Usage (server (target) side) 50698@end ifclear 50699@ifset man 50700Usage (server (target) side): 50701@end ifset 50702 50703First, you need to have a copy of the program you want to debug put onto 50704the target system. The program can be stripped to save space if needed, as 50705@command{gdbserver} doesn't care about symbols. All symbol handling is taken care of by 50706the @value{GDBN} running on the host system. 50707 50708To use the server, you log on to the target system, and run the @command{gdbserver} 50709program. You must tell it (a) how to communicate with @value{GDBN}, (b) the name of 50710your program, and (c) its arguments. The general syntax is: 50711 50712@smallexample 50713target> gdbserver @var{comm} @var{program} [@var{args} ...] 50714@end smallexample 50715 50716For example, using a serial port, you might say: 50717 50718@smallexample 50719@ifset man 50720@c @file would wrap it as F</dev/com1>. 50721target> gdbserver /dev/com1 emacs foo.txt 50722@end ifset 50723@ifclear man 50724target> gdbserver @file{/dev/com1} emacs foo.txt 50725@end ifclear 50726@end smallexample 50727 50728This tells @command{gdbserver} to debug emacs with an argument of foo.txt, and 50729to communicate with @value{GDBN} via @file{/dev/com1}. @command{gdbserver} now 50730waits patiently for the host @value{GDBN} to communicate with it. 50731 50732To use a TCP connection, you could say: 50733 50734@smallexample 50735target> gdbserver host:2345 emacs foo.txt 50736@end smallexample 50737 50738This says pretty much the same thing as the last example, except that we are 50739going to communicate with the @code{host} @value{GDBN} via TCP. The @code{host:2345} argument means 50740that we are expecting to see a TCP connection from @code{host} to local TCP port 507412345. (Currently, the @code{host} part is ignored.) You can choose any number you 50742want for the port number as long as it does not conflict with any existing TCP 50743ports on the target system. This same port number must be used in the host 50744@value{GDBN}s @code{target remote} command, which will be described shortly. Note that if 50745you chose a port number that conflicts with another service, @command{gdbserver} will 50746print an error message and exit. 50747 50748@command{gdbserver} can also attach to running programs. 50749This is accomplished via the @option{--attach} argument. The syntax is: 50750 50751@smallexample 50752target> gdbserver --attach @var{comm} @var{pid} 50753@end smallexample 50754 50755@var{pid} is the process ID of a currently running process. It isn't 50756necessary to point @command{gdbserver} at a binary for the running process. 50757 50758To start @code{gdbserver} without supplying an initial command to run 50759or process ID to attach, use the @option{--multi} command line option. 50760In such case you should connect using @kbd{target extended-remote} to start 50761the program you want to debug. 50762 50763@smallexample 50764target> gdbserver --multi @var{comm} 50765@end smallexample 50766 50767@ifclear man 50768@subheading Usage (host side) 50769@end ifclear 50770@ifset man 50771Usage (host side): 50772@end ifset 50773 50774You need an unstripped copy of the target program on your host system, since 50775@value{GDBN} needs to examine its symbol tables and such. Start up @value{GDBN} as you normally 50776would, with the target program as the first argument. (You may need to use the 50777@option{--baud} option if the serial line is running at anything except 9600 baud.) 50778That is @code{gdb TARGET-PROG}, or @code{gdb --baud BAUD TARGET-PROG}. After that, the only 50779new command you need to know about is @code{target remote} 50780(or @code{target extended-remote}). Its argument is either 50781a device name (usually a serial device, like @file{/dev/ttyb}), or a @code{HOST:PORT} 50782descriptor. For example: 50783 50784@smallexample 50785@ifset man 50786@c @file would wrap it as F</dev/ttyb>. 50787(@value{GDBP}) target remote /dev/ttyb 50788@end ifset 50789@ifclear man 50790(@value{GDBP}) target remote @file{/dev/ttyb} 50791@end ifclear 50792@end smallexample 50793 50794@noindent 50795communicates with the server via serial line @file{/dev/ttyb}, and: 50796 50797@smallexample 50798(@value{GDBP}) target remote the-target:2345 50799@end smallexample 50800 50801@noindent 50802communicates via a TCP connection to port 2345 on host `the-target', where 50803you previously started up @command{gdbserver} with the same port number. Note that for 50804TCP connections, you must start up @command{gdbserver} prior to using the `target remote' 50805command, otherwise you may get an error that looks something like 50806`Connection refused'. 50807 50808@command{gdbserver} can also debug multiple inferiors at once, 50809described in 50810@ifset man 50811the @value{GDBN} manual in node @code{Inferiors Connections and Programs} 50812-- shell command @code{info -f gdb -n 'Inferiors Connections and Programs'}. 50813@end ifset 50814@ifclear man 50815@ref{Inferiors Connections and Programs}. 50816@end ifclear 50817In such case use the @code{extended-remote} @value{GDBN} command variant: 50818 50819@smallexample 50820(@value{GDBP}) target extended-remote the-target:2345 50821@end smallexample 50822 50823The @command{gdbserver} option @option{--multi} may or may not be used in such 50824case. 50825@c man end 50826 50827@c man begin OPTIONS gdbserver 50828There are three different modes for invoking @command{gdbserver}: 50829 50830@itemize @bullet 50831 50832@item 50833Debug a specific program specified by its program name: 50834 50835@smallexample 50836gdbserver @var{comm} @var{prog} [@var{args}@dots{}] 50837@end smallexample 50838 50839The @var{comm} parameter specifies how should the server communicate 50840with @value{GDBN}; it is either a device name (to use a serial line), 50841a TCP port number (@code{:1234}), or @code{-} or @code{stdio} to use 50842stdin/stdout of @code{gdbserver}. Specify the name of the program to 50843debug in @var{prog}. Any remaining arguments will be passed to the 50844program verbatim. When the program exits, @value{GDBN} will close the 50845connection, and @code{gdbserver} will exit. 50846 50847@item 50848Debug a specific program by specifying the process ID of a running 50849program: 50850 50851@smallexample 50852gdbserver --attach @var{comm} @var{pid} 50853@end smallexample 50854 50855The @var{comm} parameter is as described above. Supply the process ID 50856of a running program in @var{pid}; @value{GDBN} will do everything 50857else. Like with the previous mode, when the process @var{pid} exits, 50858@value{GDBN} will close the connection, and @code{gdbserver} will exit. 50859 50860@item 50861Multi-process mode -- debug more than one program/process: 50862 50863@smallexample 50864gdbserver --multi @var{comm} 50865@end smallexample 50866 50867In this mode, @value{GDBN} can instruct @command{gdbserver} which 50868command(s) to run. Unlike the other 2 modes, @value{GDBN} will not 50869close the connection when a process being debugged exits, so you can 50870debug several processes in the same session. 50871@end itemize 50872 50873In each of the modes you may specify these options: 50874 50875@table @env 50876 50877@item --help 50878List all options, with brief explanations. 50879 50880@item --version 50881This option causes @command{gdbserver} to print its version number and exit. 50882 50883@item --attach 50884@command{gdbserver} will attach to a running program. The syntax is: 50885 50886@smallexample 50887target> gdbserver --attach @var{comm} @var{pid} 50888@end smallexample 50889 50890@var{pid} is the process ID of a currently running process. It isn't 50891necessary to point @command{gdbserver} at a binary for the running process. 50892 50893@item --multi 50894To start @code{gdbserver} without supplying an initial command to run 50895or process ID to attach, use this command line option. 50896Then you can connect using @kbd{target extended-remote} and start 50897the program you want to debug. The syntax is: 50898 50899@smallexample 50900target> gdbserver --multi @var{comm} 50901@end smallexample 50902 50903@item --debug@r{[}=option1,option2,@dots{}@r{]} 50904Instruct @code{gdbserver} to display extra status information about 50905the debugging process. This option is intended for @code{gdbserver} 50906development and for bug reports to the developers. 50907 50908Each @var{option} is the name of a component for which debugging 50909should be enabled. The list of possible options is @option{all}, 50910@option{threads}, @option{event-loop}, @option{remote}. The special 50911option @option{all} enables all components. The option list is 50912processed left to right, and an option can be prefixed with the 50913@kbd{-} character to disable output for that component, so you could write: 50914 50915@smallexample 50916target> gdbserver --debug=all,-event-loop 50917@end smallexample 50918 50919@noindent 50920to turn on debug output for all components except @option{event-loop}. 50921If no options are passed to @option{--debug} then this is treated as 50922equivalent to @option{--debug=threads}. This could change in future 50923releases of @code{gdbserver}. 50924 50925@item --debug-file=@var{filename} 50926Instruct @code{gdbserver} to send any debug output to the given @var{filename}. 50927This option is intended for @code{gdbserver} development and for bug reports to 50928the developers. 50929 50930@item --debug-format=option1@r{[},option2,...@r{]} 50931Instruct @code{gdbserver} to include extra information in each line 50932of debugging output. 50933@xref{Other Command-Line Arguments for gdbserver}. 50934 50935@item --wrapper 50936Specify a wrapper to launch programs 50937for debugging. The option should be followed by the name of the 50938wrapper, then any command-line arguments to pass to the wrapper, then 50939@kbd{--} indicating the end of the wrapper arguments. 50940 50941@item --once 50942By default, @command{gdbserver} keeps the listening TCP port open, so that 50943additional connections are possible. However, if you start @code{gdbserver} 50944with the @option{--once} option, it will stop listening for any further 50945connection attempts after connecting to the first @value{GDBN} session. 50946 50947@c --disable-packet is not documented for users. 50948 50949@c --disable-randomization and --no-disable-randomization are superseded by 50950@c QDisableRandomization. 50951 50952@end table 50953@c man end 50954 50955@c man begin SEEALSO gdbserver 50956@ifset man 50957The full documentation for @value{GDBN} is maintained as a Texinfo manual. 50958If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo 50959documentation are properly installed at your site, the command 50960 50961@smallexample 50962info gdb 50963@end smallexample 50964 50965should give you access to the complete manual. 50966 50967@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, 50968Richard M. Stallman and Roland H. Pesch, July 1991. 50969@end ifset 50970@c man end 50971 50972@node gcore man 50973@heading gcore 50974 50975@c man title gcore Generate a core file of a running program 50976 50977@format 50978@c man begin SYNOPSIS gcore 50979gcore [-a] [-o @var{prefix}] @var{pid1} [@var{pid2}...@var{pidN}] 50980@c man end 50981@end format 50982 50983@c man begin DESCRIPTION gcore 50984Generate core dumps of one or more running programs with process IDs 50985@var{pid1}, @var{pid2}, etc. A core file produced by @command{gcore} 50986is equivalent to one produced by the kernel when the process crashes 50987(and when @kbd{ulimit -c} was used to set up an appropriate core dump 50988limit). However, unlike after a crash, after @command{gcore} finishes 50989its job the program remains running without any change. 50990@c man end 50991 50992@c man begin OPTIONS gcore 50993@table @env 50994@item -a 50995Dump all memory mappings. The actual effect of this option depends on 50996the Operating System. On @sc{gnu}/Linux, it will disable 50997@code{use-coredump-filter} (@pxref{set use-coredump-filter}) and 50998enable @code{dump-excluded-mappings} (@pxref{set 50999dump-excluded-mappings}). 51000 51001@item -o @var{prefix} 51002The optional argument @var{prefix} specifies the prefix to be used 51003when composing the file names of the core dumps. The file name is 51004composed as @file{@var{prefix}.@var{pid}}, where @var{pid} is the 51005process ID of the running program being analyzed by @command{gcore}. 51006If not specified, @var{prefix} defaults to @var{gcore}. 51007@end table 51008@c man end 51009 51010@c man begin SEEALSO gcore 51011@ifset man 51012The full documentation for @value{GDBN} is maintained as a Texinfo manual. 51013If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo 51014documentation are properly installed at your site, the command 51015 51016@smallexample 51017info gdb 51018@end smallexample 51019 51020@noindent 51021should give you access to the complete manual. 51022 51023@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, 51024Richard M. Stallman and Roland H. Pesch, July 1991. 51025@end ifset 51026@c man end 51027 51028@node gdbinit man 51029@heading gdbinit 51030 51031@c man title gdbinit GDB initialization scripts 51032 51033@format 51034@c man begin SYNOPSIS gdbinit 51035@ifset SYSTEM_GDBINIT 51036@value{SYSTEM_GDBINIT} 51037@end ifset 51038 51039@ifset SYSTEM_GDBINIT_DIR 51040@value{SYSTEM_GDBINIT_DIR}/* 51041@end ifset 51042 51043~/.config/gdb/gdbinit 51044 51045~/.gdbinit 51046 51047./.gdbinit 51048@c man end 51049@end format 51050 51051@c man begin DESCRIPTION gdbinit 51052These files contain @value{GDBN} commands to automatically execute during 51053@value{GDBN} startup. The lines of contents are canned sequences of commands, 51054described in 51055@ifset man 51056the @value{GDBN} manual in node @code{Sequences} 51057-- shell command @code{info -f gdb -n Sequences}. 51058@end ifset 51059@ifclear man 51060@ref{Sequences}. 51061@end ifclear 51062 51063Please read more in 51064@ifset man 51065the @value{GDBN} manual in node @code{Startup} 51066-- shell command @code{info -f gdb -n Startup}. 51067@end ifset 51068@ifclear man 51069@ref{Startup}. 51070@end ifclear 51071 51072@table @env 51073@ifset SYSTEM_GDBINIT 51074@item @value{SYSTEM_GDBINIT} 51075@end ifset 51076@ifclear SYSTEM_GDBINIT 51077@item (not enabled with @code{--with-system-gdbinit} during compilation) 51078@end ifclear 51079System-wide initialization file. It is executed unless user specified 51080@value{GDBN} option @code{-nx} or @code{-n}. 51081See more in 51082@ifset man 51083the @value{GDBN} manual in node @code{System-wide configuration} 51084-- shell command @code{info -f gdb -n 'System-wide configuration'}. 51085@end ifset 51086@ifset SYSTEM_GDBINIT_DIR 51087@item @value{SYSTEM_GDBINIT_DIR} 51088@end ifset 51089@ifclear SYSTEM_GDBINIT_DIR 51090@item (not enabled with @code{--with-system-gdbinit-dir} during compilation) 51091@end ifclear 51092System-wide initialization directory. All files in this directory are 51093executed on startup unless user specified @value{GDBN} option @code{-nx} or 51094@code{-n}, as long as they have a recognized file extension. 51095See more in 51096@ifset man 51097the @value{GDBN} manual in node @code{System-wide configuration} 51098-- shell command @code{info -f gdb -n 'System-wide configuration'}. 51099@end ifset 51100@ifclear man 51101@ref{System-wide configuration}. 51102@end ifclear 51103 51104@item @file{~/.config/gdb/gdbinit} or @file{~/.gdbinit} 51105User initialization file. It is executed unless user specified 51106@value{GDBN} options @code{-nx}, @code{-n} or @code{-nh}. 51107 51108@item @file{.gdbinit} 51109Initialization file for current directory. It may need to be enabled with 51110@value{GDBN} security command @code{set auto-load local-gdbinit}. 51111See more in 51112@ifset man 51113the @value{GDBN} manual in node @code{Init File in the Current Directory} 51114-- shell command @code{info -f gdb -n 'Init File in the Current Directory'}. 51115@end ifset 51116@ifclear man 51117@ref{Init File in the Current Directory}. 51118@end ifclear 51119@end table 51120@c man end 51121 51122@c man begin SEEALSO gdbinit 51123@ifset man 51124gdb(1), @code{info -f gdb -n Startup} 51125 51126The full documentation for @value{GDBN} is maintained as a Texinfo manual. 51127If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo 51128documentation are properly installed at your site, the command 51129 51130@smallexample 51131info gdb 51132@end smallexample 51133 51134should give you access to the complete manual. 51135 51136@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, 51137Richard M. Stallman and Roland H. Pesch, July 1991. 51138@end ifset 51139@c man end 51140 51141@node gdb-add-index man 51142@heading gdb-add-index 51143@pindex gdb-add-index 51144@anchor{gdb-add-index} 51145 51146@c man title gdb-add-index Add index files to speed up GDB 51147 51148@c man begin SYNOPSIS gdb-add-index 51149gdb-add-index @var{filename} 51150@c man end 51151 51152@c man begin DESCRIPTION gdb-add-index 51153When @value{GDBN} finds a symbol file, it scans the symbols in the 51154file in order to construct an internal symbol table. This lets most 51155@value{GDBN} operations work quickly--at the cost of a delay early on. 51156For large programs, this delay can be quite lengthy, so @value{GDBN} 51157provides a way to build an index, which speeds up startup. 51158 51159To determine whether a file contains such an index, use the command 51160@kbd{readelf -S filename}: the index is stored in a section named 51161@code{.gdb_index}. The index file can only be produced on systems 51162which use ELF binaries and DWARF debug information (i.e., sections 51163named @code{.debug_*}). 51164 51165@command{gdb-add-index} uses @value{GDBN} and @command{objdump} found 51166in the @env{PATH} environment variable. If you want to use different 51167versions of these programs, you can specify them through the 51168@env{GDB} and @env{OBJDUMP} environment variables. 51169 51170See more in 51171@ifset man 51172the @value{GDBN} manual in node @code{Index Files} 51173-- shell command @kbd{info -f gdb -n "Index Files"}. 51174@end ifset 51175@ifclear man 51176@ref{Index Files}. 51177@end ifclear 51178@c man end 51179 51180@c man begin SEEALSO gdb-add-index 51181@ifset man 51182The full documentation for @value{GDBN} is maintained as a Texinfo manual. 51183If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo 51184documentation are properly installed at your site, the command 51185 51186@smallexample 51187info gdb 51188@end smallexample 51189 51190should give you access to the complete manual. 51191 51192@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, 51193Richard M. Stallman and Roland H. Pesch, July 1991. 51194@end ifset 51195@c man end 51196 51197@include gpl.texi 51198 51199@node GNU Free Documentation License 51200@appendix GNU Free Documentation License 51201@include fdl.texi 51202 51203@node Concept Index 51204@unnumbered Concept Index 51205 51206@printindex cp 51207 51208@node Command and Variable Index 51209@unnumbered Command, Variable, and Function Index 51210 51211@printindex fn 51212 51213@tex 51214% I think something like @@colophon should be in texinfo. In the 51215% meantime: 51216\long\def\colophon{\hbox to0pt{}\vfill 51217\centerline{The body of this manual is set in} 51218\centerline{\fontname\tenrm,} 51219\centerline{with headings in {\bf\fontname\tenbf}} 51220\centerline{and examples in {\tt\fontname\tentt}.} 51221\centerline{{\it\fontname\tenit\/},} 51222\centerline{{\bf\fontname\tenbf}, and} 51223\centerline{{\sl\fontname\tensl\/}} 51224\centerline{are used for emphasis.}\vfill} 51225\page\colophon 51226% Blame: doc@@cygnus.com, 1991. 51227@end tex 51228 51229@bye 51230