1\input texinfo @c -*-texinfo-*- 2@c Copyright (C) 1988-2013 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@include gdb-cfg.texi 10@c 11@settitle Debugging with @value{GDBN} 12@setchapternewpage odd 13@c %**end of header 14 15@iftex 16@c @smallbook 17@c @cropmarks 18@end iftex 19 20@finalout 21@c To avoid file-name clashes between index.html and Index.html, when 22@c the manual is produced on a Posix host and then moved to a 23@c case-insensitive filesystem (e.g., MS-Windows), we separate the 24@c indices into two: Concept Index and all the rest. 25@syncodeindex ky fn 26@syncodeindex tp fn 27 28@c readline appendices use @vindex, @findex and @ftable, 29@c annotate.texi and gdbmi use @findex. 30@syncodeindex vr fn 31 32@c !!set GDB manual's edition---not the same as GDB version! 33@c This is updated by GNU Press. 34@set EDITION Tenth 35 36@c !!set GDB edit command default editor 37@set EDITOR /bin/ex 38 39@c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER. 40 41@c This is a dir.info fragment to support semi-automated addition of 42@c manuals to an info tree. 43@dircategory Software development 44@direntry 45* Gdb: (gdb). The GNU debugger. 46@end direntry 47 48@copying 49Copyright @copyright{} 1988-2013 Free Software Foundation, Inc. 50 51Permission is granted to copy, distribute and/or modify this document 52under the terms of the GNU Free Documentation License, Version 1.3 or 53any later version published by the Free Software Foundation; with the 54Invariant Sections being ``Free Software'' and ``Free Software Needs 55Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 56and with the Back-Cover Texts as in (a) below. 57 58(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 59this GNU Manual. Buying copies from GNU Press supports the FSF in 60developing GNU and promoting software freedom.'' 61@end copying 62 63@ifnottex 64This file documents the @sc{gnu} debugger @value{GDBN}. 65 66This is the @value{EDITION} Edition, of @cite{Debugging with 67@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN} 68@ifset VERSION_PACKAGE 69@value{VERSION_PACKAGE} 70@end ifset 71Version @value{GDBVN}. 72 73@insertcopying 74@end ifnottex 75 76@titlepage 77@title Debugging with @value{GDBN} 78@subtitle The @sc{gnu} Source-Level Debugger 79@sp 1 80@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN} 81@ifset VERSION_PACKAGE 82@sp 1 83@subtitle @value{VERSION_PACKAGE} 84@end ifset 85@author Richard Stallman, Roland Pesch, Stan Shebs, et al. 86@page 87@tex 88{\parskip=0pt 89\hfill (Send bugs and comments on @value{GDBN} to @value{BUGURL}.)\par 90\hfill {\it Debugging with @value{GDBN}}\par 91\hfill \TeX{}info \texinfoversion\par 92} 93@end tex 94 95@vskip 0pt plus 1filll 96Published by the Free Software Foundation @* 9751 Franklin Street, Fifth Floor, 98Boston, MA 02110-1301, USA@* 99ISBN 978-0-9831592-3-0 @* 100 101@insertcopying 102@end titlepage 103@page 104 105@ifnottex 106@node Top, Summary, (dir), (dir) 107 108@top Debugging with @value{GDBN} 109 110This file describes @value{GDBN}, the @sc{gnu} symbolic debugger. 111 112This is the @value{EDITION} Edition, for @value{GDBN} 113@ifset VERSION_PACKAGE 114@value{VERSION_PACKAGE} 115@end ifset 116Version @value{GDBVN}. 117 118Copyright (C) 1988-2013 Free Software Foundation, Inc. 119 120This edition of the GDB manual is dedicated to the memory of Fred 121Fish. Fred was a long-standing contributor to GDB and to Free 122software in general. We will miss him. 123 124@menu 125* Summary:: Summary of @value{GDBN} 126* Sample Session:: A sample @value{GDBN} session 127 128* Invocation:: Getting in and out of @value{GDBN} 129* Commands:: @value{GDBN} commands 130* Running:: Running programs under @value{GDBN} 131* Stopping:: Stopping and continuing 132* Reverse Execution:: Running programs backward 133* Process Record and Replay:: Recording inferior's execution and replaying it 134* Stack:: Examining the stack 135* Source:: Examining source files 136* Data:: Examining data 137* Optimized Code:: Debugging optimized code 138* Macros:: Preprocessor Macros 139* Tracepoints:: Debugging remote targets non-intrusively 140* Overlays:: Debugging programs that use overlays 141 142* Languages:: Using @value{GDBN} with different languages 143 144* Symbols:: Examining the symbol table 145* Altering:: Altering execution 146* GDB Files:: @value{GDBN} files 147* Targets:: Specifying a debugging target 148* Remote Debugging:: Debugging remote programs 149* Configurations:: Configuration-specific information 150* Controlling GDB:: Controlling @value{GDBN} 151* Extending GDB:: Extending @value{GDBN} 152* Interpreters:: Command Interpreters 153* TUI:: @value{GDBN} Text User Interface 154* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs 155* GDB/MI:: @value{GDBN}'s Machine Interface. 156* Annotations:: @value{GDBN}'s annotation interface. 157* JIT Interface:: Using the JIT debugging interface. 158* In-Process Agent:: In-Process Agent 159 160* GDB Bugs:: Reporting bugs in @value{GDBN} 161 162@ifset SYSTEM_READLINE 163* Command Line Editing: (rluserman). Command Line Editing 164* Using History Interactively: (history). Using History Interactively 165@end ifset 166@ifclear SYSTEM_READLINE 167* Command Line Editing:: Command Line Editing 168* Using History Interactively:: Using History Interactively 169@end ifclear 170* In Memoriam:: In Memoriam 171* Formatting Documentation:: How to format and print @value{GDBN} documentation 172* Installing GDB:: Installing GDB 173* Maintenance Commands:: Maintenance Commands 174* Remote Protocol:: GDB Remote Serial Protocol 175* Agent Expressions:: The GDB Agent Expression Mechanism 176* Target Descriptions:: How targets can describe themselves to 177 @value{GDBN} 178* Operating System Information:: Getting additional information from 179 the operating system 180* Trace File Format:: GDB trace file format 181* Index Section Format:: .gdb_index section format 182* Copying:: GNU General Public License says 183 how you can copy and share GDB 184* GNU Free Documentation License:: The license for this documentation 185* Concept Index:: Index of @value{GDBN} concepts 186* Command and Variable Index:: Index of @value{GDBN} commands, variables, 187 functions, and Python data types 188@end menu 189 190@end ifnottex 191 192@contents 193 194@node Summary 195@unnumbered Summary of @value{GDBN} 196 197The purpose of a debugger such as @value{GDBN} is to allow you to see what is 198going on ``inside'' another program while it executes---or what another 199program was doing at the moment it crashed. 200 201@value{GDBN} can do four main kinds of things (plus other things in support of 202these) to help you catch bugs in the act: 203 204@itemize @bullet 205@item 206Start your program, specifying anything that might affect its behavior. 207 208@item 209Make your program stop on specified conditions. 210 211@item 212Examine what has happened, when your program has stopped. 213 214@item 215Change things in your program, so you can experiment with correcting the 216effects of one bug and go on to learn about another. 217@end itemize 218 219You can use @value{GDBN} to debug programs written in C and C@t{++}. 220For more information, see @ref{Supported Languages,,Supported Languages}. 221For more information, see @ref{C,,C and C++}. 222 223Support for D is partial. For information on D, see 224@ref{D,,D}. 225 226@cindex Modula-2 227Support for Modula-2 is partial. For information on Modula-2, see 228@ref{Modula-2,,Modula-2}. 229 230Support for OpenCL C is partial. For information on OpenCL C, see 231@ref{OpenCL C,,OpenCL C}. 232 233@cindex Pascal 234Debugging Pascal programs which use sets, subranges, file variables, or 235nested functions does not currently work. @value{GDBN} does not support 236entering expressions, printing values, or similar features using Pascal 237syntax. 238 239@cindex Fortran 240@value{GDBN} can be used to debug programs written in Fortran, although 241it may be necessary to refer to some variables with a trailing 242underscore. 243 244@value{GDBN} can be used to debug programs written in Objective-C, 245using either the Apple/NeXT or the GNU Objective-C runtime. 246 247@menu 248* Free Software:: Freely redistributable software 249* Free Documentation:: Free Software Needs Free Documentation 250* Contributors:: Contributors to GDB 251@end menu 252 253@node Free Software 254@unnumberedsec Free Software 255 256@value{GDBN} is @dfn{free software}, protected by the @sc{gnu} 257General Public License 258(GPL). The GPL gives you the freedom to copy or adapt a licensed 259program---but every person getting a copy also gets with it the 260freedom to modify that copy (which means that they must get access to 261the source code), and the freedom to distribute further copies. 262Typical software companies use copyrights to limit your freedoms; the 263Free Software Foundation uses the GPL to preserve these freedoms. 264 265Fundamentally, the General Public License is a license which says that 266you have these freedoms and that you cannot take these freedoms away 267from anyone else. 268 269@node Free Documentation 270@unnumberedsec Free Software Needs Free Documentation 271 272The biggest deficiency in the free software community today is not in 273the software---it is the lack of good free documentation that we can 274include with the free software. Many of our most important 275programs do not come with free reference manuals and free introductory 276texts. Documentation is an essential part of any software package; 277when an important free software package does not come with a free 278manual and a free tutorial, that is a major gap. We have many such 279gaps today. 280 281Consider Perl, for instance. The tutorial manuals that people 282normally use are non-free. How did this come about? Because the 283authors of those manuals published them with restrictive terms---no 284copying, no modification, source files not available---which exclude 285them from the free software world. 286 287That wasn't the first time this sort of thing happened, and it was far 288from the last. Many times we have heard a GNU user eagerly describe a 289manual that he is writing, his intended contribution to the community, 290only to learn that he had ruined everything by signing a publication 291contract to make it non-free. 292 293Free documentation, like free software, is a matter of freedom, not 294price. The problem with the non-free manual is not that publishers 295charge a price for printed copies---that in itself is fine. (The Free 296Software Foundation sells printed copies of manuals, too.) The 297problem is the restrictions on the use of the manual. Free manuals 298are available in source code form, and give you permission to copy and 299modify. Non-free manuals do not allow this. 300 301The criteria of freedom for a free manual are roughly the same as for 302free software. Redistribution (including the normal kinds of 303commercial redistribution) must be permitted, so that the manual can 304accompany every copy of the program, both on-line and on paper. 305 306Permission for modification of the technical content is crucial too. 307When people modify the software, adding or changing features, if they 308are conscientious they will change the manual too---so they can 309provide accurate and clear documentation for the modified program. A 310manual that leaves you no choice but to write a new manual to document 311a changed version of the program is not really available to our 312community. 313 314Some kinds of limits on the way modification is handled are 315acceptable. For example, requirements to preserve the original 316author's copyright notice, the distribution terms, or the list of 317authors, are ok. It is also no problem to require modified versions 318to include notice that they were modified. Even entire sections that 319may not be deleted or changed are acceptable, as long as they deal 320with nontechnical topics (like this one). These kinds of restrictions 321are acceptable because they don't obstruct the community's normal use 322of the manual. 323 324However, it must be possible to modify all the @emph{technical} 325content of the manual, and then distribute the result in all the usual 326media, through all the usual channels. Otherwise, the restrictions 327obstruct the use of the manual, it is not free, and we need another 328manual to replace it. 329 330Please spread the word about this issue. Our community continues to 331lose manuals to proprietary publishing. If we spread the word that 332free software needs free reference manuals and free tutorials, perhaps 333the next person who wants to contribute by writing documentation will 334realize, before it is too late, that only free manuals contribute to 335the free software community. 336 337If you are writing documentation, please insist on publishing it under 338the GNU Free Documentation License or another free documentation 339license. Remember that this decision requires your approval---you 340don't have to let the publisher decide. Some commercial publishers 341will use a free license if you insist, but they will not propose the 342option; it is up to you to raise the issue and say firmly that this is 343what you want. If the publisher you are dealing with refuses, please 344try other publishers. If you're not sure whether a proposed license 345is free, write to @email{licensing@@gnu.org}. 346 347You can encourage commercial publishers to sell more free, copylefted 348manuals and tutorials by buying them, and particularly by buying 349copies from the publishers that paid for their writing or for major 350improvements. Meanwhile, try to avoid buying non-free documentation 351at all. Check the distribution terms of a manual before you buy it, 352and insist that whoever seeks your business must respect your freedom. 353Check the history of the book, and try to reward the publishers that 354have paid or pay the authors to work on it. 355 356The Free Software Foundation maintains a list of free documentation 357published by other publishers, at 358@url{http://www.fsf.org/doc/other-free-books.html}. 359 360@node Contributors 361@unnumberedsec Contributors to @value{GDBN} 362 363Richard Stallman was the original author of @value{GDBN}, and of many 364other @sc{gnu} programs. Many others have contributed to its 365development. This section attempts to credit major contributors. One 366of the virtues of free software is that everyone is free to contribute 367to it; with regret, we cannot actually acknowledge everyone here. The 368file @file{ChangeLog} in the @value{GDBN} distribution approximates a 369blow-by-blow account. 370 371Changes much prior to version 2.0 are lost in the mists of time. 372 373@quotation 374@emph{Plea:} Additions to this section are particularly welcome. If you 375or your friends (or enemies, to be evenhanded) have been unfairly 376omitted from this list, we would like to add your names! 377@end quotation 378 379So that they may not regard their many labors as thankless, we 380particularly thank those who shepherded @value{GDBN} through major 381releases: 382Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); 383Jim Blandy (release 4.18); 384Jason Molenda (release 4.17); 385Stan Shebs (release 4.14); 386Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9); 387Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4); 388John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); 389Jim Kingdon (releases 3.5, 3.4, and 3.3); 390and Randy Smith (releases 3.2, 3.1, and 3.0). 391 392Richard Stallman, assisted at various times by Peter TerMaat, Chris 393Hanson, and Richard Mlynarik, handled releases through 2.8. 394 395Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support 396in @value{GDBN}, with significant additional contributions from Per 397Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++} 398demangler. Early work on C@t{++} was by Peter TerMaat (who also did 399much general update work leading to release 3.0). 400 401@value{GDBN} uses the BFD subroutine library to examine multiple 402object-file formats; BFD was a joint project of David V. 403Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore. 404 405David Johnson wrote the original COFF support; Pace Willison did 406the original support for encapsulated COFF. 407 408Brent Benson of Harris Computer Systems contributed DWARF 2 support. 409 410Adam de Boor and Bradley Davis contributed the ISI Optimum V support. 411Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS 412support. 413Jean-Daniel Fekete contributed Sun 386i support. 414Chris Hanson improved the HP9000 support. 415Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support. 416David Johnson contributed Encore Umax support. 417Jyrki Kuoppala contributed Altos 3068 support. 418Jeff Law contributed HP PA and SOM support. 419Keith Packard contributed NS32K support. 420Doug Rabson contributed Acorn Risc Machine support. 421Bob Rusk contributed Harris Nighthawk CX-UX support. 422Chris Smith contributed Convex support (and Fortran debugging). 423Jonathan Stone contributed Pyramid support. 424Michael Tiemann contributed SPARC support. 425Tim Tucker contributed support for the Gould NP1 and Gould Powernode. 426Pace Willison contributed Intel 386 support. 427Jay Vosburgh contributed Symmetry support. 428Marko Mlinar contributed OpenRISC 1000 support. 429 430Andreas Schwab contributed M68K @sc{gnu}/Linux support. 431 432Rich Schaefer and Peter Schauer helped with support of SunOS shared 433libraries. 434 435Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree 436about several machine instruction sets. 437 438Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop 439remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM 440contributed remote debugging modules for the i960, VxWorks, A29K UDI, 441and RDI targets, respectively. 442 443Brian Fox is the author of the readline libraries providing 444command-line editing and command history. 445 446Andrew Beers of SUNY Buffalo wrote the language-switching code, the 447Modula-2 support, and contributed the Languages chapter of this manual. 448 449Fred Fish wrote most of the support for Unix System Vr4. 450He also enhanced the command-completion support to cover C@t{++} overloaded 451symbols. 452 453Hitachi America (now Renesas America), Ltd. sponsored the support for 454H8/300, H8/500, and Super-H processors. 455 456NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors. 457 458Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D 459processors. 460 461Toshiba sponsored the support for the TX39 Mips processor. 462 463Matsushita sponsored the support for the MN10200 and MN10300 processors. 464 465Fujitsu sponsored the support for SPARClite and FR30 processors. 466 467Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware 468watchpoints. 469 470Michael Snyder added support for tracepoints. 471 472Stu Grossman wrote gdbserver. 473 474Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made 475nearly innumerable bug fixes and cleanups throughout @value{GDBN}. 476 477The following people at the Hewlett-Packard Company contributed 478support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 479(narrow mode), HP's implementation of kernel threads, HP's aC@t{++} 480compiler, and the Text User Interface (nee Terminal User Interface): 481Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, 482Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase 483provided HP-specific information in this manual. 484 485DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project. 486Robert Hoehne made significant contributions to the DJGPP port. 487 488Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its 489development since 1991. Cygnus engineers who have worked on @value{GDBN} 490fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin 491Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim 492Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, 493Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek 494Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In 495addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, 496JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug 497Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff 498Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, 499Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin 500Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela 501Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David 502Zuhn have made contributions both large and small. 503 504Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for 505Cygnus Solutions, implemented the original @sc{gdb/mi} interface. 506 507Jim Blandy added support for preprocessor macros, while working for Red 508Hat. 509 510Andrew Cagney designed @value{GDBN}'s architecture vector. Many 511people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick 512Duffek, Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei 513Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason 514Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped 515with the migration of old architectures to this new framework. 516 517Andrew Cagney completely re-designed and re-implemented @value{GDBN}'s 518unwinder framework, this consisting of a fresh new design featuring 519frame IDs, independent frame sniffers, and the sentinel frame. Mark 520Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the 521libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and 522trad unwinders. The architecture-specific changes, each involving a 523complete rewrite of the architecture's frame code, were carried out by 524Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane 525Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel 526Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei 527Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich 528Weigand. 529 530Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from 531Tensilica, Inc.@: contributed support for Xtensa processors. Others 532who have worked on the Xtensa port of @value{GDBN} in the past include 533Steve Tjiang, John Newlin, and Scott Foehner. 534 535Michael Eager and staff of Xilinx, Inc., contributed support for the 536Xilinx MicroBlaze architecture. 537 538@node Sample Session 539@chapter A Sample @value{GDBN} Session 540 541You can use this manual at your leisure to read all about @value{GDBN}. 542However, a handful of commands are enough to get started using the 543debugger. This chapter illustrates those commands. 544 545@iftex 546In this sample session, we emphasize user input like this: @b{input}, 547to make it easier to pick out from the surrounding output. 548@end iftex 549 550@c FIXME: this example may not be appropriate for some configs, where 551@c FIXME...primary interest is in remote use. 552 553One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro 554processor) exhibits the following bug: sometimes, when we change its 555quote strings from the default, the commands used to capture one macro 556definition within another stop working. In the following short @code{m4} 557session, we define a macro @code{foo} which expands to @code{0000}; we 558then use the @code{m4} built-in @code{defn} to define @code{bar} as the 559same thing. However, when we change the open quote string to 560@code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same 561procedure fails to define a new synonym @code{baz}: 562 563@smallexample 564$ @b{cd gnu/m4} 565$ @b{./m4} 566@b{define(foo,0000)} 567 568@b{foo} 5690000 570@b{define(bar,defn(`foo'))} 571 572@b{bar} 5730000 574@b{changequote(<QUOTE>,<UNQUOTE>)} 575 576@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))} 577@b{baz} 578@b{Ctrl-d} 579m4: End of input: 0: fatal error: EOF in string 580@end smallexample 581 582@noindent 583Let us use @value{GDBN} to try to see what is going on. 584 585@smallexample 586$ @b{@value{GDBP} m4} 587@c FIXME: this falsifies the exact text played out, to permit smallbook 588@c FIXME... format to come out better. 589@value{GDBN} is free software and you are welcome to distribute copies 590 of it under certain conditions; type "show copying" to see 591 the conditions. 592There is absolutely no warranty for @value{GDBN}; type "show warranty" 593 for details. 594 595@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc... 596(@value{GDBP}) 597@end smallexample 598 599@noindent 600@value{GDBN} reads only enough symbol data to know where to find the 601rest when needed; as a result, the first prompt comes up very quickly. 602We now tell @value{GDBN} to use a narrower display width than usual, so 603that examples fit in this manual. 604 605@smallexample 606(@value{GDBP}) @b{set width 70} 607@end smallexample 608 609@noindent 610We need to see how the @code{m4} built-in @code{changequote} works. 611Having looked at the source, we know the relevant subroutine is 612@code{m4_changequote}, so we set a breakpoint there with the @value{GDBN} 613@code{break} command. 614 615@smallexample 616(@value{GDBP}) @b{break m4_changequote} 617Breakpoint 1 at 0x62f4: file builtin.c, line 879. 618@end smallexample 619 620@noindent 621Using the @code{run} command, we start @code{m4} running under @value{GDBN} 622control; as long as control does not reach the @code{m4_changequote} 623subroutine, the program runs as usual: 624 625@smallexample 626(@value{GDBP}) @b{run} 627Starting program: /work/Editorial/gdb/gnu/m4/m4 628@b{define(foo,0000)} 629 630@b{foo} 6310000 632@end smallexample 633 634@noindent 635To trigger the breakpoint, we call @code{changequote}. @value{GDBN} 636suspends execution of @code{m4}, displaying information about the 637context where it stops. 638 639@smallexample 640@b{changequote(<QUOTE>,<UNQUOTE>)} 641 642Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) 643 at builtin.c:879 644879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) 645@end smallexample 646 647@noindent 648Now we use the command @code{n} (@code{next}) to advance execution to 649the next line of the current function. 650 651@smallexample 652(@value{GDBP}) @b{n} 653882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ 654 : nil, 655@end smallexample 656 657@noindent 658@code{set_quotes} looks like a promising subroutine. We can go into it 659by using the command @code{s} (@code{step}) instead of @code{next}. 660@code{step} goes to the next line to be executed in @emph{any} 661subroutine, so it steps into @code{set_quotes}. 662 663@smallexample 664(@value{GDBP}) @b{s} 665set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 666 at input.c:530 667530 if (lquote != def_lquote) 668@end smallexample 669 670@noindent 671The display that shows the subroutine where @code{m4} is now 672suspended (and its arguments) is called a stack frame display. It 673shows a summary of the stack. We can use the @code{backtrace} 674command (which can also be spelled @code{bt}), to see where we are 675in the stack as a whole: the @code{backtrace} command displays a 676stack frame for each active subroutine. 677 678@smallexample 679(@value{GDBP}) @b{bt} 680#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 681 at input.c:530 682#1 0x6344 in m4_changequote (argc=3, argv=0x33c70) 683 at builtin.c:882 684#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 685#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) 686 at macro.c:71 687#4 0x79dc in expand_input () at macro.c:40 688#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 689@end smallexample 690 691@noindent 692We step through a few more lines to see what happens. The first two 693times, we can use @samp{s}; the next two times we use @code{n} to avoid 694falling into the @code{xstrdup} subroutine. 695 696@smallexample 697(@value{GDBP}) @b{s} 6980x3b5c 532 if (rquote != def_rquote) 699(@value{GDBP}) @b{s} 7000x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ 701def_lquote : xstrdup(lq); 702(@value{GDBP}) @b{n} 703536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 704 : xstrdup(rq); 705(@value{GDBP}) @b{n} 706538 len_lquote = strlen(rquote); 707@end smallexample 708 709@noindent 710The last line displayed looks a little odd; we can examine the variables 711@code{lquote} and @code{rquote} to see if they are in fact the new left 712and right quotes we specified. We use the command @code{p} 713(@code{print}) to see their values. 714 715@smallexample 716(@value{GDBP}) @b{p lquote} 717$1 = 0x35d40 "<QUOTE>" 718(@value{GDBP}) @b{p rquote} 719$2 = 0x35d50 "<UNQUOTE>" 720@end smallexample 721 722@noindent 723@code{lquote} and @code{rquote} are indeed the new left and right quotes. 724To look at some context, we can display ten lines of source 725surrounding the current line with the @code{l} (@code{list}) command. 726 727@smallexample 728(@value{GDBP}) @b{l} 729533 xfree(rquote); 730534 731535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ 732 : xstrdup (lq); 733536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 734 : xstrdup (rq); 735537 736538 len_lquote = strlen(rquote); 737539 len_rquote = strlen(lquote); 738540 @} 739541 740542 void 741@end smallexample 742 743@noindent 744Let us step past the two lines that set @code{len_lquote} and 745@code{len_rquote}, and then examine the values of those variables. 746 747@smallexample 748(@value{GDBP}) @b{n} 749539 len_rquote = strlen(lquote); 750(@value{GDBP}) @b{n} 751540 @} 752(@value{GDBP}) @b{p len_lquote} 753$3 = 9 754(@value{GDBP}) @b{p len_rquote} 755$4 = 7 756@end smallexample 757 758@noindent 759That certainly looks wrong, assuming @code{len_lquote} and 760@code{len_rquote} are meant to be the lengths of @code{lquote} and 761@code{rquote} respectively. We can set them to better values using 762the @code{p} command, since it can print the value of 763any expression---and that expression can include subroutine calls and 764assignments. 765 766@smallexample 767(@value{GDBP}) @b{p len_lquote=strlen(lquote)} 768$5 = 7 769(@value{GDBP}) @b{p len_rquote=strlen(rquote)} 770$6 = 9 771@end smallexample 772 773@noindent 774Is that enough to fix the problem of using the new quotes with the 775@code{m4} built-in @code{defn}? We can allow @code{m4} to continue 776executing with the @code{c} (@code{continue}) command, and then try the 777example that caused trouble initially: 778 779@smallexample 780(@value{GDBP}) @b{c} 781Continuing. 782 783@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))} 784 785baz 7860000 787@end smallexample 788 789@noindent 790Success! The new quotes now work just as well as the default ones. The 791problem seems to have been just the two typos defining the wrong 792lengths. We allow @code{m4} exit by giving it an EOF as input: 793 794@smallexample 795@b{Ctrl-d} 796Program exited normally. 797@end smallexample 798 799@noindent 800The message @samp{Program exited normally.} is from @value{GDBN}; it 801indicates @code{m4} has finished executing. We can end our @value{GDBN} 802session with the @value{GDBN} @code{quit} command. 803 804@smallexample 805(@value{GDBP}) @b{quit} 806@end smallexample 807 808@node Invocation 809@chapter Getting In and Out of @value{GDBN} 810 811This chapter discusses how to start @value{GDBN}, and how to get out of it. 812The essentials are: 813@itemize @bullet 814@item 815type @samp{@value{GDBP}} to start @value{GDBN}. 816@item 817type @kbd{quit} or @kbd{Ctrl-d} to exit. 818@end itemize 819 820@menu 821* Invoking GDB:: How to start @value{GDBN} 822* Quitting GDB:: How to quit @value{GDBN} 823* Shell Commands:: How to use shell commands inside @value{GDBN} 824* Logging Output:: How to log @value{GDBN}'s output to a file 825@end menu 826 827@node Invoking GDB 828@section Invoking @value{GDBN} 829 830Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started, 831@value{GDBN} reads commands from the terminal until you tell it to exit. 832 833You can also run @code{@value{GDBP}} with a variety of arguments and options, 834to specify more of your debugging environment at the outset. 835 836The command-line options described here are designed 837to cover a variety of situations; in some environments, some of these 838options may effectively be unavailable. 839 840The most usual way to start @value{GDBN} is with one argument, 841specifying an executable program: 842 843@smallexample 844@value{GDBP} @var{program} 845@end smallexample 846 847@noindent 848You can also start with both an executable program and a core file 849specified: 850 851@smallexample 852@value{GDBP} @var{program} @var{core} 853@end smallexample 854 855You can, instead, specify a process ID as a second argument, if you want 856to debug a running process: 857 858@smallexample 859@value{GDBP} @var{program} 1234 860@end smallexample 861 862@noindent 863would attach @value{GDBN} to process @code{1234} (unless you also have a file 864named @file{1234}; @value{GDBN} does check for a core file first). 865 866Taking advantage of the second command-line argument requires a fairly 867complete operating system; when you use @value{GDBN} as a remote 868debugger attached to a bare board, there may not be any notion of 869``process'', and there is often no way to get a core dump. @value{GDBN} 870will warn you if it is unable to attach or to read core dumps. 871 872You can optionally have @code{@value{GDBP}} pass any arguments after the 873executable file to the inferior using @code{--args}. This option stops 874option processing. 875@smallexample 876@value{GDBP} --args gcc -O2 -c foo.c 877@end smallexample 878This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set 879@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}. 880 881You can run @code{@value{GDBP}} without printing the front material, which describes 882@value{GDBN}'s non-warranty, by specifying @code{-silent}: 883 884@smallexample 885@value{GDBP} -silent 886@end smallexample 887 888@noindent 889You can further control how @value{GDBN} starts up by using command-line 890options. @value{GDBN} itself can remind you of the options available. 891 892@noindent 893Type 894 895@smallexample 896@value{GDBP} -help 897@end smallexample 898 899@noindent 900to display all available options and briefly describe their use 901(@samp{@value{GDBP} -h} is a shorter equivalent). 902 903All options and command line arguments you give are processed 904in sequential order. The order makes a difference when the 905@samp{-x} option is used. 906 907 908@menu 909* File Options:: Choosing files 910* Mode Options:: Choosing modes 911* Startup:: What @value{GDBN} does during startup 912@end menu 913 914@node File Options 915@subsection Choosing Files 916 917When @value{GDBN} starts, it reads any arguments other than options as 918specifying an executable file and core file (or process ID). This is 919the same as if the arguments were specified by the @samp{-se} and 920@samp{-c} (or @samp{-p}) options respectively. (@value{GDBN} reads the 921first argument that does not have an associated option flag as 922equivalent to the @samp{-se} option followed by that argument; and the 923second argument that does not have an associated option flag, if any, as 924equivalent to the @samp{-c}/@samp{-p} option followed by that argument.) 925If the second argument begins with a decimal digit, @value{GDBN} will 926first attempt to attach to it as a process, and if that fails, attempt 927to open it as a corefile. If you have a corefile whose name begins with 928a digit, you can prevent @value{GDBN} from treating it as a pid by 929prefixing it with @file{./}, e.g.@: @file{./12345}. 930 931If @value{GDBN} has not been configured to included core file support, 932such as for most embedded targets, then it will complain about a second 933argument and ignore it. 934 935Many options have both long and short forms; both are shown in the 936following list. @value{GDBN} also recognizes the long forms if you truncate 937them, so long as enough of the option is present to be unambiguous. 938(If you prefer, you can flag option arguments with @samp{--} rather 939than @samp{-}, though we illustrate the more usual convention.) 940 941@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This 942@c way, both those who look for -foo and --foo in the index, will find 943@c it. 944 945@table @code 946@item -symbols @var{file} 947@itemx -s @var{file} 948@cindex @code{--symbols} 949@cindex @code{-s} 950Read symbol table from file @var{file}. 951 952@item -exec @var{file} 953@itemx -e @var{file} 954@cindex @code{--exec} 955@cindex @code{-e} 956Use file @var{file} as the executable file to execute when appropriate, 957and for examining pure data in conjunction with a core dump. 958 959@item -se @var{file} 960@cindex @code{--se} 961Read symbol table from file @var{file} and use it as the executable 962file. 963 964@item -core @var{file} 965@itemx -c @var{file} 966@cindex @code{--core} 967@cindex @code{-c} 968Use file @var{file} as a core dump to examine. 969 970@item -pid @var{number} 971@itemx -p @var{number} 972@cindex @code{--pid} 973@cindex @code{-p} 974Connect to process ID @var{number}, as with the @code{attach} command. 975 976@item -command @var{file} 977@itemx -x @var{file} 978@cindex @code{--command} 979@cindex @code{-x} 980Execute commands from file @var{file}. The contents of this file is 981evaluated exactly as the @code{source} command would. 982@xref{Command Files,, Command files}. 983 984@item -eval-command @var{command} 985@itemx -ex @var{command} 986@cindex @code{--eval-command} 987@cindex @code{-ex} 988Execute a single @value{GDBN} command. 989 990This option may be used multiple times to call multiple commands. It may 991also be interleaved with @samp{-command} as required. 992 993@smallexample 994@value{GDBP} -ex 'target sim' -ex 'load' \ 995 -x setbreakpoints -ex 'run' a.out 996@end smallexample 997 998@item -init-command @var{file} 999@itemx -ix @var{file} 1000@cindex @code{--init-command} 1001@cindex @code{-ix} 1002Execute commands from file @var{file} before loading the inferior (but 1003after loading gdbinit files). 1004@xref{Startup}. 1005 1006@item -init-eval-command @var{command} 1007@itemx -iex @var{command} 1008@cindex @code{--init-eval-command} 1009@cindex @code{-iex} 1010Execute a single @value{GDBN} command before loading the inferior (but 1011after loading gdbinit files). 1012@xref{Startup}. 1013 1014@item -directory @var{directory} 1015@itemx -d @var{directory} 1016@cindex @code{--directory} 1017@cindex @code{-d} 1018Add @var{directory} to the path to search for source and script files. 1019 1020@item -r 1021@itemx -readnow 1022@cindex @code{--readnow} 1023@cindex @code{-r} 1024Read each symbol file's entire symbol table immediately, rather than 1025the default, which is to read it incrementally as it is needed. 1026This makes startup slower, but makes future operations faster. 1027 1028@end table 1029 1030@node Mode Options 1031@subsection Choosing Modes 1032 1033You can run @value{GDBN} in various alternative modes---for example, in 1034batch mode or quiet mode. 1035 1036@table @code 1037@anchor{-nx} 1038@item -nx 1039@itemx -n 1040@cindex @code{--nx} 1041@cindex @code{-n} 1042Do not execute commands found in any initialization file. 1043There are three init files, loaded in the following order: 1044 1045@table @code 1046@item @file{system.gdbinit} 1047This is the system-wide init file. 1048Its location is specified with the @code{--with-system-gdbinit} 1049configure option (@pxref{System-wide configuration}). 1050It is loaded first when @value{GDBN} starts, before command line options 1051have been processed. 1052@item @file{~/.gdbinit} 1053This is the init file in your home directory. 1054It is loaded next, after @file{system.gdbinit}, and before 1055command options have been processed. 1056@item @file{./.gdbinit} 1057This is the init file in the current directory. 1058It is loaded last, after command line options other than @code{-x} and 1059@code{-ex} have been processed. Command line options @code{-x} and 1060@code{-ex} are processed last, after @file{./.gdbinit} has been loaded. 1061@end table 1062 1063For further documentation on startup processing, @xref{Startup}. 1064For documentation on how to write command files, 1065@xref{Command Files,,Command Files}. 1066 1067@anchor{-nh} 1068@item -nh 1069@cindex @code{--nh} 1070Do not execute commands found in @file{~/.gdbinit}, the init file 1071in your home directory. 1072@xref{Startup}. 1073 1074@item -quiet 1075@itemx -silent 1076@itemx -q 1077@cindex @code{--quiet} 1078@cindex @code{--silent} 1079@cindex @code{-q} 1080``Quiet''. Do not print the introductory and copyright messages. These 1081messages are also suppressed in batch mode. 1082 1083@item -batch 1084@cindex @code{--batch} 1085Run in batch mode. Exit with status @code{0} after processing all the 1086command files specified with @samp{-x} (and all commands from 1087initialization files, if not inhibited with @samp{-n}). Exit with 1088nonzero status if an error occurs in executing the @value{GDBN} commands 1089in the command files. Batch mode also disables pagination, sets unlimited 1090terminal width and height @pxref{Screen Size}, and acts as if @kbd{set confirm 1091off} were in effect (@pxref{Messages/Warnings}). 1092 1093Batch mode may be useful for running @value{GDBN} as a filter, for 1094example to download and run a program on another computer; in order to 1095make this more useful, the message 1096 1097@smallexample 1098Program exited normally. 1099@end smallexample 1100 1101@noindent 1102(which is ordinarily issued whenever a program running under 1103@value{GDBN} control terminates) is not issued when running in batch 1104mode. 1105 1106@item -batch-silent 1107@cindex @code{--batch-silent} 1108Run in batch mode exactly like @samp{-batch}, but totally silently. All 1109@value{GDBN} output to @code{stdout} is prevented (@code{stderr} is 1110unaffected). This is much quieter than @samp{-silent} and would be useless 1111for an interactive session. 1112 1113This is particularly useful when using targets that give @samp{Loading section} 1114messages, for example. 1115 1116Note that targets that give their output via @value{GDBN}, as opposed to 1117writing directly to @code{stdout}, will also be made silent. 1118 1119@item -return-child-result 1120@cindex @code{--return-child-result} 1121The return code from @value{GDBN} will be the return code from the child 1122process (the process being debugged), with the following exceptions: 1123 1124@itemize @bullet 1125@item 1126@value{GDBN} exits abnormally. E.g., due to an incorrect argument or an 1127internal error. In this case the exit code is the same as it would have been 1128without @samp{-return-child-result}. 1129@item 1130The user quits with an explicit value. E.g., @samp{quit 1}. 1131@item 1132The child process never runs, or is not allowed to terminate, in which case 1133the exit code will be -1. 1134@end itemize 1135 1136This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent}, 1137when @value{GDBN} is being used as a remote program loader or simulator 1138interface. 1139 1140@item -nowindows 1141@itemx -nw 1142@cindex @code{--nowindows} 1143@cindex @code{-nw} 1144``No windows''. If @value{GDBN} comes with a graphical user interface 1145(GUI) built in, then this option tells @value{GDBN} to only use the command-line 1146interface. If no GUI is available, this option has no effect. 1147 1148@item -windows 1149@itemx -w 1150@cindex @code{--windows} 1151@cindex @code{-w} 1152If @value{GDBN} includes a GUI, then this option requires it to be 1153used if possible. 1154 1155@item -cd @var{directory} 1156@cindex @code{--cd} 1157Run @value{GDBN} using @var{directory} as its working directory, 1158instead of the current directory. 1159 1160@item -data-directory @var{directory} 1161@cindex @code{--data-directory} 1162Run @value{GDBN} using @var{directory} as its data directory. 1163The data directory is where @value{GDBN} searches for its 1164auxiliary files. @xref{Data Files}. 1165 1166@item -fullname 1167@itemx -f 1168@cindex @code{--fullname} 1169@cindex @code{-f} 1170@sc{gnu} Emacs sets this option when it runs @value{GDBN} as a 1171subprocess. It tells @value{GDBN} to output the full file name and line 1172number in a standard, recognizable fashion each time a stack frame is 1173displayed (which includes each time your program stops). This 1174recognizable format looks like two @samp{\032} characters, followed by 1175the file name, line number and character position separated by colons, 1176and a newline. The Emacs-to-@value{GDBN} interface program uses the two 1177@samp{\032} characters as a signal to display the source code for the 1178frame. 1179 1180@item -annotate @var{level} 1181@cindex @code{--annotate} 1182This option sets the @dfn{annotation level} inside @value{GDBN}. Its 1183effect is identical to using @samp{set annotate @var{level}} 1184(@pxref{Annotations}). The annotation @var{level} controls how much 1185information @value{GDBN} prints together with its prompt, values of 1186expressions, source lines, and other types of output. Level 0 is the 1187normal, level 1 is for use when @value{GDBN} is run as a subprocess of 1188@sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs 1189that control @value{GDBN}, and level 2 has been deprecated. 1190 1191The annotation mechanism has largely been superseded by @sc{gdb/mi} 1192(@pxref{GDB/MI}). 1193 1194@item --args 1195@cindex @code{--args} 1196Change interpretation of command line so that arguments following the 1197executable file are passed as command line arguments to the inferior. 1198This option stops option processing. 1199 1200@item -baud @var{bps} 1201@itemx -b @var{bps} 1202@cindex @code{--baud} 1203@cindex @code{-b} 1204Set the line speed (baud rate or bits per second) of any serial 1205interface used by @value{GDBN} for remote debugging. 1206 1207@item -l @var{timeout} 1208@cindex @code{-l} 1209Set the timeout (in seconds) of any communication used by @value{GDBN} 1210for remote debugging. 1211 1212@item -tty @var{device} 1213@itemx -t @var{device} 1214@cindex @code{--tty} 1215@cindex @code{-t} 1216Run using @var{device} for your program's standard input and output. 1217@c FIXME: kingdon thinks there is more to -tty. Investigate. 1218 1219@c resolve the situation of these eventually 1220@item -tui 1221@cindex @code{--tui} 1222Activate the @dfn{Text User Interface} when starting. The Text User 1223Interface manages several text windows on the terminal, showing 1224source, assembly, registers and @value{GDBN} command outputs 1225(@pxref{TUI, ,@value{GDBN} Text User Interface}). Do not use this 1226option if you run @value{GDBN} from Emacs (@pxref{Emacs, , 1227Using @value{GDBN} under @sc{gnu} Emacs}). 1228 1229@c @item -xdb 1230@c @cindex @code{--xdb} 1231@c Run in XDB compatibility mode, allowing the use of certain XDB commands. 1232@c For information, see the file @file{xdb_trans.html}, which is usually 1233@c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX 1234@c systems. 1235 1236@item -interpreter @var{interp} 1237@cindex @code{--interpreter} 1238Use the interpreter @var{interp} for interface with the controlling 1239program or device. This option is meant to be set by programs which 1240communicate with @value{GDBN} using it as a back end. 1241@xref{Interpreters, , Command Interpreters}. 1242 1243@samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes 1244@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} (@pxref{GDB/MI, , 1245The @sc{gdb/mi} Interface}) included since @value{GDBN} version 6.0. The 1246previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and 1247selected with @samp{--interpreter=mi1}, is deprecated. Earlier 1248@sc{gdb/mi} interfaces are no longer supported. 1249 1250@item -write 1251@cindex @code{--write} 1252Open the executable and core files for both reading and writing. This 1253is equivalent to the @samp{set write on} command inside @value{GDBN} 1254(@pxref{Patching}). 1255 1256@item -statistics 1257@cindex @code{--statistics} 1258This option causes @value{GDBN} to print statistics about time and 1259memory usage after it completes each command and returns to the prompt. 1260 1261@item -version 1262@cindex @code{--version} 1263This option causes @value{GDBN} to print its version number and 1264no-warranty blurb, and exit. 1265 1266@end table 1267 1268@node Startup 1269@subsection What @value{GDBN} Does During Startup 1270@cindex @value{GDBN} startup 1271 1272Here's the description of what @value{GDBN} does during session startup: 1273 1274@enumerate 1275@item 1276Sets up the command interpreter as specified by the command line 1277(@pxref{Mode Options, interpreter}). 1278 1279@item 1280@cindex init file 1281Reads the system-wide @dfn{init file} (if @option{--with-system-gdbinit} was 1282used when building @value{GDBN}; @pxref{System-wide configuration, 1283 ,System-wide configuration and settings}) and executes all the commands in 1284that file. 1285 1286@anchor{Home Directory Init File} 1287@item 1288Reads the init file (if any) in your home directory@footnote{On 1289DOS/Windows systems, the home directory is the one pointed to by the 1290@code{HOME} environment variable.} and executes all the commands in 1291that file. 1292 1293@anchor{Option -init-eval-command} 1294@item 1295Executes commands and command files specified by the @samp{-iex} and 1296@samp{-ix} options in their specified order. Usually you should use the 1297@samp{-ex} and @samp{-x} options instead, but this way you can apply 1298settings before @value{GDBN} init files get executed and before inferior 1299gets loaded. 1300 1301@item 1302Processes command line options and operands. 1303 1304@anchor{Init File in the Current Directory during Startup} 1305@item 1306Reads and executes the commands from init file (if any) in the current 1307working directory as long as @samp{set auto-load local-gdbinit} is set to 1308@samp{on} (@pxref{Init File in the Current Directory}). 1309This is only done if the current directory is 1310different from your home directory. Thus, you can have more than one 1311init file, one generic in your home directory, and another, specific 1312to the program you are debugging, in the directory where you invoke 1313@value{GDBN}. 1314 1315@item 1316If the command line specified a program to debug, or a process to 1317attach to, or a core file, @value{GDBN} loads any auto-loaded 1318scripts provided for the program or for its loaded shared libraries. 1319@xref{Auto-loading}. 1320 1321If you wish to disable the auto-loading during startup, 1322you must do something like the following: 1323 1324@smallexample 1325$ gdb -iex "set auto-load python-scripts off" myprogram 1326@end smallexample 1327 1328Option @samp{-ex} does not work because the auto-loading is then turned 1329off too late. 1330 1331@item 1332Executes commands and command files specified by the @samp{-ex} and 1333@samp{-x} options in their specified order. @xref{Command Files}, for 1334more details about @value{GDBN} command files. 1335 1336@item 1337Reads the command history recorded in the @dfn{history file}. 1338@xref{Command History}, for more details about the command history and the 1339files where @value{GDBN} records it. 1340@end enumerate 1341 1342Init files use the same syntax as @dfn{command files} (@pxref{Command 1343Files}) and are processed by @value{GDBN} in the same way. The init 1344file in your home directory can set options (such as @samp{set 1345complaints}) that affect subsequent processing of command line options 1346and operands. Init files are not executed if you use the @samp{-nx} 1347option (@pxref{Mode Options, ,Choosing Modes}). 1348 1349To display the list of init files loaded by gdb at startup, you 1350can use @kbd{gdb --help}. 1351 1352@cindex init file name 1353@cindex @file{.gdbinit} 1354@cindex @file{gdb.ini} 1355The @value{GDBN} init files are normally called @file{.gdbinit}. 1356The DJGPP port of @value{GDBN} uses the name @file{gdb.ini}, due to 1357the limitations of file names imposed by DOS filesystems. The Windows 1358port of @value{GDBN} uses the standard name, but if it finds a 1359@file{gdb.ini} file in your home directory, it warns you about that 1360and suggests to rename the file to the standard name. 1361 1362 1363@node Quitting GDB 1364@section Quitting @value{GDBN} 1365@cindex exiting @value{GDBN} 1366@cindex leaving @value{GDBN} 1367 1368@table @code 1369@kindex quit @r{[}@var{expression}@r{]} 1370@kindex q @r{(@code{quit})} 1371@item quit @r{[}@var{expression}@r{]} 1372@itemx q 1373To exit @value{GDBN}, use the @code{quit} command (abbreviated 1374@code{q}), or type an end-of-file character (usually @kbd{Ctrl-d}). If you 1375do not supply @var{expression}, @value{GDBN} will terminate normally; 1376otherwise it will terminate using the result of @var{expression} as the 1377error code. 1378@end table 1379 1380@cindex interrupt 1381An interrupt (often @kbd{Ctrl-c}) does not exit from @value{GDBN}, but rather 1382terminates the action of any @value{GDBN} command that is in progress and 1383returns to @value{GDBN} command level. It is safe to type the interrupt 1384character at any time because @value{GDBN} does not allow it to take effect 1385until a time when it is safe. 1386 1387If you have been using @value{GDBN} to control an attached process or 1388device, you can release it with the @code{detach} command 1389(@pxref{Attach, ,Debugging an Already-running Process}). 1390 1391@node Shell Commands 1392@section Shell Commands 1393 1394If you need to execute occasional shell commands during your 1395debugging session, there is no need to leave or suspend @value{GDBN}; you can 1396just use the @code{shell} command. 1397 1398@table @code 1399@kindex shell 1400@kindex ! 1401@cindex shell escape 1402@item shell @var{command-string} 1403@itemx !@var{command-string} 1404Invoke a standard shell to execute @var{command-string}. 1405Note that no space is needed between @code{!} and @var{command-string}. 1406If it exists, the environment variable @code{SHELL} determines which 1407shell to run. Otherwise @value{GDBN} uses the default shell 1408(@file{/bin/sh} on Unix systems, @file{COMMAND.COM} on MS-DOS, etc.). 1409@end table 1410 1411The utility @code{make} is often needed in development environments. 1412You do not have to use the @code{shell} command for this purpose in 1413@value{GDBN}: 1414 1415@table @code 1416@kindex make 1417@cindex calling make 1418@item make @var{make-args} 1419Execute the @code{make} program with the specified 1420arguments. This is equivalent to @samp{shell make @var{make-args}}. 1421@end table 1422 1423@node Logging Output 1424@section Logging Output 1425@cindex logging @value{GDBN} output 1426@cindex save @value{GDBN} output to a file 1427 1428You may want to save the output of @value{GDBN} commands to a file. 1429There are several commands to control @value{GDBN}'s logging. 1430 1431@table @code 1432@kindex set logging 1433@item set logging on 1434Enable logging. 1435@item set logging off 1436Disable logging. 1437@cindex logging file name 1438@item set logging file @var{file} 1439Change the name of the current logfile. The default logfile is @file{gdb.txt}. 1440@item set logging overwrite [on|off] 1441By default, @value{GDBN} will append to the logfile. Set @code{overwrite} if 1442you want @code{set logging on} to overwrite the logfile instead. 1443@item set logging redirect [on|off] 1444By default, @value{GDBN} output will go to both the terminal and the logfile. 1445Set @code{redirect} if you want output to go only to the log file. 1446@kindex show logging 1447@item show logging 1448Show the current values of the logging settings. 1449@end table 1450 1451@node Commands 1452@chapter @value{GDBN} Commands 1453 1454You can abbreviate a @value{GDBN} command to the first few letters of the command 1455name, if that abbreviation is unambiguous; and you can repeat certain 1456@value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB} 1457key to get @value{GDBN} to fill out the rest of a word in a command (or to 1458show you the alternatives available, if there is more than one possibility). 1459 1460@menu 1461* Command Syntax:: How to give commands to @value{GDBN} 1462* Completion:: Command completion 1463* Help:: How to ask @value{GDBN} for help 1464@end menu 1465 1466@node Command Syntax 1467@section Command Syntax 1468 1469A @value{GDBN} command is a single line of input. There is no limit on 1470how long it can be. It starts with a command name, which is followed by 1471arguments whose meaning depends on the command name. For example, the 1472command @code{step} accepts an argument which is the number of times to 1473step, as in @samp{step 5}. You can also use the @code{step} command 1474with no arguments. Some commands do not allow any arguments. 1475 1476@cindex abbreviation 1477@value{GDBN} command names may always be truncated if that abbreviation is 1478unambiguous. Other possible command abbreviations are listed in the 1479documentation for individual commands. In some cases, even ambiguous 1480abbreviations are allowed; for example, @code{s} is specially defined as 1481equivalent to @code{step} even though there are other commands whose 1482names start with @code{s}. You can test abbreviations by using them as 1483arguments to the @code{help} command. 1484 1485@cindex repeating commands 1486@kindex RET @r{(repeat last command)} 1487A blank line as input to @value{GDBN} (typing just @key{RET}) means to 1488repeat the previous command. Certain commands (for example, @code{run}) 1489will not repeat this way; these are commands whose unintentional 1490repetition might cause trouble and which you are unlikely to want to 1491repeat. User-defined commands can disable this feature; see 1492@ref{Define, dont-repeat}. 1493 1494The @code{list} and @code{x} commands, when you repeat them with 1495@key{RET}, construct new arguments rather than repeating 1496exactly as typed. This permits easy scanning of source or memory. 1497 1498@value{GDBN} can also use @key{RET} in another way: to partition lengthy 1499output, in a way similar to the common utility @code{more} 1500(@pxref{Screen Size,,Screen Size}). Since it is easy to press one 1501@key{RET} too many in this situation, @value{GDBN} disables command 1502repetition after any command that generates this sort of display. 1503 1504@kindex # @r{(a comment)} 1505@cindex comment 1506Any text from a @kbd{#} to the end of the line is a comment; it does 1507nothing. This is useful mainly in command files (@pxref{Command 1508Files,,Command Files}). 1509 1510@cindex repeating command sequences 1511@kindex Ctrl-o @r{(operate-and-get-next)} 1512The @kbd{Ctrl-o} binding is useful for repeating a complex sequence of 1513commands. This command accepts the current line, like @key{RET}, and 1514then fetches the next line relative to the current line from the history 1515for editing. 1516 1517@node Completion 1518@section Command Completion 1519 1520@cindex completion 1521@cindex word completion 1522@value{GDBN} can fill in the rest of a word in a command for you, if there is 1523only one possibility; it can also show you what the valid possibilities 1524are for the next word in a command, at any time. This works for @value{GDBN} 1525commands, @value{GDBN} subcommands, and the names of symbols in your program. 1526 1527Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest 1528of a word. If there is only one possibility, @value{GDBN} fills in the 1529word, and waits for you to finish the command (or press @key{RET} to 1530enter it). For example, if you type 1531 1532@c FIXME "@key" does not distinguish its argument sufficiently to permit 1533@c complete accuracy in these examples; space introduced for clarity. 1534@c If texinfo enhancements make it unnecessary, it would be nice to 1535@c replace " @key" by "@key" in the following... 1536@smallexample 1537(@value{GDBP}) info bre @key{TAB} 1538@end smallexample 1539 1540@noindent 1541@value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is 1542the only @code{info} subcommand beginning with @samp{bre}: 1543 1544@smallexample 1545(@value{GDBP}) info breakpoints 1546@end smallexample 1547 1548@noindent 1549You can either press @key{RET} at this point, to run the @code{info 1550breakpoints} command, or backspace and enter something else, if 1551@samp{breakpoints} does not look like the command you expected. (If you 1552were sure you wanted @code{info breakpoints} in the first place, you 1553might as well just type @key{RET} immediately after @samp{info bre}, 1554to exploit command abbreviations rather than command completion). 1555 1556If there is more than one possibility for the next word when you press 1557@key{TAB}, @value{GDBN} sounds a bell. You can either supply more 1558characters and try again, or just press @key{TAB} a second time; 1559@value{GDBN} displays all the possible completions for that word. For 1560example, you might want to set a breakpoint on a subroutine whose name 1561begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN} 1562just sounds the bell. Typing @key{TAB} again displays all the 1563function names in your program that begin with those characters, for 1564example: 1565 1566@smallexample 1567(@value{GDBP}) b make_ @key{TAB} 1568@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see: 1569make_a_section_from_file make_environ 1570make_abs_section make_function_type 1571make_blockvector make_pointer_type 1572make_cleanup make_reference_type 1573make_command make_symbol_completion_list 1574(@value{GDBP}) b make_ 1575@end smallexample 1576 1577@noindent 1578After displaying the available possibilities, @value{GDBN} copies your 1579partial input (@samp{b make_} in the example) so you can finish the 1580command. 1581 1582If you just want to see the list of alternatives in the first place, you 1583can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?} 1584means @kbd{@key{META} ?}. You can type this either by holding down a 1585key designated as the @key{META} shift on your keyboard (if there is 1586one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}. 1587 1588@cindex quotes in commands 1589@cindex completion of quoted strings 1590Sometimes the string you need, while logically a ``word'', may contain 1591parentheses or other characters that @value{GDBN} normally excludes from 1592its notion of a word. To permit word completion to work in this 1593situation, you may enclose words in @code{'} (single quote marks) in 1594@value{GDBN} commands. 1595 1596The most likely situation where you might need this is in typing the 1597name of a C@t{++} function. This is because C@t{++} allows function 1598overloading (multiple definitions of the same function, distinguished 1599by argument type). For example, when you want to set a breakpoint you 1600may need to distinguish whether you mean the version of @code{name} 1601that takes an @code{int} parameter, @code{name(int)}, or the version 1602that takes a @code{float} parameter, @code{name(float)}. To use the 1603word-completion facilities in this situation, type a single quote 1604@code{'} at the beginning of the function name. This alerts 1605@value{GDBN} that it may need to consider more information than usual 1606when you press @key{TAB} or @kbd{M-?} to request word completion: 1607 1608@smallexample 1609(@value{GDBP}) b 'bubble( @kbd{M-?} 1610bubble(double,double) bubble(int,int) 1611(@value{GDBP}) b 'bubble( 1612@end smallexample 1613 1614In some cases, @value{GDBN} can tell that completing a name requires using 1615quotes. When this happens, @value{GDBN} inserts the quote for you (while 1616completing as much as it can) if you do not type the quote in the first 1617place: 1618 1619@smallexample 1620(@value{GDBP}) b bub @key{TAB} 1621@exdent @value{GDBN} alters your input line to the following, and rings a bell: 1622(@value{GDBP}) b 'bubble( 1623@end smallexample 1624 1625@noindent 1626In general, @value{GDBN} can tell that a quote is needed (and inserts it) if 1627you have not yet started typing the argument list when you ask for 1628completion on an overloaded symbol. 1629 1630For more information about overloaded functions, see @ref{C Plus Plus 1631Expressions, ,C@t{++} Expressions}. You can use the command @code{set 1632overload-resolution off} to disable overload resolution; 1633see @ref{Debugging C Plus Plus, ,@value{GDBN} Features for C@t{++}}. 1634 1635@cindex completion of structure field names 1636@cindex structure field name completion 1637@cindex completion of union field names 1638@cindex union field name completion 1639When completing in an expression which looks up a field in a 1640structure, @value{GDBN} also tries@footnote{The completer can be 1641confused by certain kinds of invalid expressions. Also, it only 1642examines the static type of the expression, not the dynamic type.} to 1643limit completions to the field names available in the type of the 1644left-hand-side: 1645 1646@smallexample 1647(@value{GDBP}) p gdb_stdout.@kbd{M-?} 1648magic to_fputs to_rewind 1649to_data to_isatty to_write 1650to_delete to_put to_write_async_safe 1651to_flush to_read 1652@end smallexample 1653 1654@noindent 1655This is because the @code{gdb_stdout} is a variable of the type 1656@code{struct ui_file} that is defined in @value{GDBN} sources as 1657follows: 1658 1659@smallexample 1660struct ui_file 1661@{ 1662 int *magic; 1663 ui_file_flush_ftype *to_flush; 1664 ui_file_write_ftype *to_write; 1665 ui_file_write_async_safe_ftype *to_write_async_safe; 1666 ui_file_fputs_ftype *to_fputs; 1667 ui_file_read_ftype *to_read; 1668 ui_file_delete_ftype *to_delete; 1669 ui_file_isatty_ftype *to_isatty; 1670 ui_file_rewind_ftype *to_rewind; 1671 ui_file_put_ftype *to_put; 1672 void *to_data; 1673@} 1674@end smallexample 1675 1676 1677@node Help 1678@section Getting Help 1679@cindex online documentation 1680@kindex help 1681 1682You can always ask @value{GDBN} itself for information on its commands, 1683using the command @code{help}. 1684 1685@table @code 1686@kindex h @r{(@code{help})} 1687@item help 1688@itemx h 1689You can use @code{help} (abbreviated @code{h}) with no arguments to 1690display a short list of named classes of commands: 1691 1692@smallexample 1693(@value{GDBP}) help 1694List of classes of commands: 1695 1696aliases -- Aliases of other commands 1697breakpoints -- Making program stop at certain points 1698data -- Examining data 1699files -- Specifying and examining files 1700internals -- Maintenance commands 1701obscure -- Obscure features 1702running -- Running the program 1703stack -- Examining the stack 1704status -- Status inquiries 1705support -- Support facilities 1706tracepoints -- Tracing of program execution without 1707 stopping the program 1708user-defined -- User-defined commands 1709 1710Type "help" followed by a class name for a list of 1711commands in that class. 1712Type "help" followed by command name for full 1713documentation. 1714Command name abbreviations are allowed if unambiguous. 1715(@value{GDBP}) 1716@end smallexample 1717@c the above line break eliminates huge line overfull... 1718 1719@item help @var{class} 1720Using one of the general help classes as an argument, you can get a 1721list of the individual commands in that class. For example, here is the 1722help display for the class @code{status}: 1723 1724@smallexample 1725(@value{GDBP}) help status 1726Status inquiries. 1727 1728List of commands: 1729 1730@c Line break in "show" line falsifies real output, but needed 1731@c to fit in smallbook page size. 1732info -- Generic command for showing things 1733 about the program being debugged 1734show -- Generic command for showing things 1735 about the debugger 1736 1737Type "help" followed by command name for full 1738documentation. 1739Command name abbreviations are allowed if unambiguous. 1740(@value{GDBP}) 1741@end smallexample 1742 1743@item help @var{command} 1744With a command name as @code{help} argument, @value{GDBN} displays a 1745short paragraph on how to use that command. 1746 1747@kindex apropos 1748@item apropos @var{args} 1749The @code{apropos} command searches through all of the @value{GDBN} 1750commands, and their documentation, for the regular expression specified in 1751@var{args}. It prints out all matches found. For example: 1752 1753@smallexample 1754apropos alias 1755@end smallexample 1756 1757@noindent 1758results in: 1759 1760@smallexample 1761@c @group 1762alias -- Define a new command that is an alias of an existing command 1763aliases -- Aliases of other commands 1764d -- Delete some breakpoints or auto-display expressions 1765del -- Delete some breakpoints or auto-display expressions 1766delete -- Delete some breakpoints or auto-display expressions 1767@c @end group 1768@end smallexample 1769 1770@kindex complete 1771@item complete @var{args} 1772The @code{complete @var{args}} command lists all the possible completions 1773for the beginning of a command. Use @var{args} to specify the beginning of the 1774command you want completed. For example: 1775 1776@smallexample 1777complete i 1778@end smallexample 1779 1780@noindent results in: 1781 1782@smallexample 1783@group 1784if 1785ignore 1786info 1787inspect 1788@end group 1789@end smallexample 1790 1791@noindent This is intended for use by @sc{gnu} Emacs. 1792@end table 1793 1794In addition to @code{help}, you can use the @value{GDBN} commands @code{info} 1795and @code{show} to inquire about the state of your program, or the state 1796of @value{GDBN} itself. Each command supports many topics of inquiry; this 1797manual introduces each of them in the appropriate context. The listings 1798under @code{info} and under @code{show} in the Command, Variable, and 1799Function Index point to all the sub-commands. @xref{Command and Variable 1800Index}. 1801 1802@c @group 1803@table @code 1804@kindex info 1805@kindex i @r{(@code{info})} 1806@item info 1807This command (abbreviated @code{i}) is for describing the state of your 1808program. For example, you can show the arguments passed to a function 1809with @code{info args}, list the registers currently in use with @code{info 1810registers}, or list the breakpoints you have set with @code{info breakpoints}. 1811You can get a complete list of the @code{info} sub-commands with 1812@w{@code{help info}}. 1813 1814@kindex set 1815@item set 1816You can assign the result of an expression to an environment variable with 1817@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with 1818@code{set prompt $}. 1819 1820@kindex show 1821@item show 1822In contrast to @code{info}, @code{show} is for describing the state of 1823@value{GDBN} itself. 1824You can change most of the things you can @code{show}, by using the 1825related command @code{set}; for example, you can control what number 1826system is used for displays with @code{set radix}, or simply inquire 1827which is currently in use with @code{show radix}. 1828 1829@kindex info set 1830To display all the settable parameters and their current 1831values, you can use @code{show} with no arguments; you may also use 1832@code{info set}. Both commands produce the same display. 1833@c FIXME: "info set" violates the rule that "info" is for state of 1834@c FIXME...program. Ck w/ GNU: "info set" to be called something else, 1835@c FIXME...or change desc of rule---eg "state of prog and debugging session"? 1836@end table 1837@c @end group 1838 1839Here are three miscellaneous @code{show} subcommands, all of which are 1840exceptional in lacking corresponding @code{set} commands: 1841 1842@table @code 1843@kindex show version 1844@cindex @value{GDBN} version number 1845@item show version 1846Show what version of @value{GDBN} is running. You should include this 1847information in @value{GDBN} bug-reports. If multiple versions of 1848@value{GDBN} are in use at your site, you may need to determine which 1849version of @value{GDBN} you are running; as @value{GDBN} evolves, new 1850commands are introduced, and old ones may wither away. Also, many 1851system vendors ship variant versions of @value{GDBN}, and there are 1852variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well. 1853The version number is the same as the one announced when you start 1854@value{GDBN}. 1855 1856@kindex show copying 1857@kindex info copying 1858@cindex display @value{GDBN} copyright 1859@item show copying 1860@itemx info copying 1861Display information about permission for copying @value{GDBN}. 1862 1863@kindex show warranty 1864@kindex info warranty 1865@item show warranty 1866@itemx info warranty 1867Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty, 1868if your version of @value{GDBN} comes with one. 1869 1870@end table 1871 1872@node Running 1873@chapter Running Programs Under @value{GDBN} 1874 1875When you run a program under @value{GDBN}, you must first generate 1876debugging information when you compile it. 1877 1878You may start @value{GDBN} with its arguments, if any, in an environment 1879of your choice. If you are doing native debugging, you may redirect 1880your program's input and output, debug an already running process, or 1881kill a child process. 1882 1883@menu 1884* Compilation:: Compiling for debugging 1885* Starting:: Starting your program 1886* Arguments:: Your program's arguments 1887* Environment:: Your program's environment 1888 1889* Working Directory:: Your program's working directory 1890* Input/Output:: Your program's input and output 1891* Attach:: Debugging an already-running process 1892* Kill Process:: Killing the child process 1893 1894* Inferiors and Programs:: Debugging multiple inferiors and programs 1895* Threads:: Debugging programs with multiple threads 1896* Forks:: Debugging forks 1897* Checkpoint/Restart:: Setting a @emph{bookmark} to return to later 1898@end menu 1899 1900@node Compilation 1901@section Compiling for Debugging 1902 1903In order to debug a program effectively, you need to generate 1904debugging information when you compile it. This debugging information 1905is stored in the object file; it describes the data type of each 1906variable or function and the correspondence between source line numbers 1907and addresses in the executable code. 1908 1909To request debugging information, specify the @samp{-g} option when you run 1910the compiler. 1911 1912Programs that are to be shipped to your customers are compiled with 1913optimizations, using the @samp{-O} compiler option. However, some 1914compilers are unable to handle the @samp{-g} and @samp{-O} options 1915together. Using those compilers, you cannot generate optimized 1916executables containing debugging information. 1917 1918@value{NGCC}, the @sc{gnu} C/C@t{++} compiler, supports @samp{-g} with or 1919without @samp{-O}, making it possible to debug optimized code. We 1920recommend that you @emph{always} use @samp{-g} whenever you compile a 1921program. You may think your program is correct, but there is no sense 1922in pushing your luck. For more information, see @ref{Optimized Code}. 1923 1924Older versions of the @sc{gnu} C compiler permitted a variant option 1925@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this 1926format; if your @sc{gnu} C compiler has this option, do not use it. 1927 1928@value{GDBN} knows about preprocessor macros and can show you their 1929expansion (@pxref{Macros}). Most compilers do not include information 1930about preprocessor macros in the debugging information if you specify 1931the @option{-g} flag alone. Version 3.1 and later of @value{NGCC}, 1932the @sc{gnu} C compiler, provides macro information if you are using 1933the DWARF debugging format, and specify the option @option{-g3}. 1934 1935@xref{Debugging Options,,Options for Debugging Your Program or GCC, 1936gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}, for more 1937information on @value{NGCC} options affecting debug information. 1938 1939You will have the best debugging experience if you use the latest 1940version of the DWARF debugging format that your compiler supports. 1941DWARF is currently the most expressive and best supported debugging 1942format in @value{GDBN}. 1943 1944@need 2000 1945@node Starting 1946@section Starting your Program 1947@cindex starting 1948@cindex running 1949 1950@table @code 1951@kindex run 1952@kindex r @r{(@code{run})} 1953@item run 1954@itemx r 1955Use the @code{run} command to start your program under @value{GDBN}. 1956You must first specify the program name (except on VxWorks) with an 1957argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of 1958@value{GDBN}}), or by using the @code{file} or @code{exec-file} command 1959(@pxref{Files, ,Commands to Specify Files}). 1960 1961@end table 1962 1963If you are running your program in an execution environment that 1964supports processes, @code{run} creates an inferior process and makes 1965that process run your program. In some environments without processes, 1966@code{run} jumps to the start of your program. Other targets, 1967like @samp{remote}, are always running. If you get an error 1968message like this one: 1969 1970@smallexample 1971The "remote" target does not support "run". 1972Try "help target" or "continue". 1973@end smallexample 1974 1975@noindent 1976then use @code{continue} to run your program. You may need @code{load} 1977first (@pxref{load}). 1978 1979The execution of a program is affected by certain information it 1980receives from its superior. @value{GDBN} provides ways to specify this 1981information, which you must do @emph{before} starting your program. (You 1982can change it after starting your program, but such changes only affect 1983your program the next time you start it.) This information may be 1984divided into four categories: 1985 1986@table @asis 1987@item The @emph{arguments.} 1988Specify the arguments to give your program as the arguments of the 1989@code{run} command. If a shell is available on your target, the shell 1990is used to pass the arguments, so that you may use normal conventions 1991(such as wildcard expansion or variable substitution) in describing 1992the arguments. 1993In Unix systems, you can control which shell is used with the 1994@code{SHELL} environment variable. 1995@xref{Arguments, ,Your Program's Arguments}. 1996 1997@item The @emph{environment.} 1998Your program normally inherits its environment from @value{GDBN}, but you can 1999use the @value{GDBN} commands @code{set environment} and @code{unset 2000environment} to change parts of the environment that affect 2001your program. @xref{Environment, ,Your Program's Environment}. 2002 2003@item The @emph{working directory.} 2004Your program inherits its working directory from @value{GDBN}. You can set 2005the @value{GDBN} working directory with the @code{cd} command in @value{GDBN}. 2006@xref{Working Directory, ,Your Program's Working Directory}. 2007 2008@item The @emph{standard input and output.} 2009Your program normally uses the same device for standard input and 2010standard output as @value{GDBN} is using. You can redirect input and output 2011in the @code{run} command line, or you can use the @code{tty} command to 2012set a different device for your program. 2013@xref{Input/Output, ,Your Program's Input and Output}. 2014 2015@cindex pipes 2016@emph{Warning:} While input and output redirection work, you cannot use 2017pipes to pass the output of the program you are debugging to another 2018program; if you attempt this, @value{GDBN} is likely to wind up debugging the 2019wrong program. 2020@end table 2021 2022When you issue the @code{run} command, your program begins to execute 2023immediately. @xref{Stopping, ,Stopping and Continuing}, for discussion 2024of how to arrange for your program to stop. Once your program has 2025stopped, you may call functions in your program, using the @code{print} 2026or @code{call} commands. @xref{Data, ,Examining Data}. 2027 2028If the modification time of your symbol file has changed since the last 2029time @value{GDBN} read its symbols, @value{GDBN} discards its symbol 2030table, and reads it again. When it does this, @value{GDBN} tries to retain 2031your current breakpoints. 2032 2033@table @code 2034@kindex start 2035@item start 2036@cindex run to main procedure 2037The name of the main procedure can vary from language to language. 2038With C or C@t{++}, the main procedure name is always @code{main}, but 2039other languages such as Ada do not require a specific name for their 2040main procedure. The debugger provides a convenient way to start the 2041execution of the program and to stop at the beginning of the main 2042procedure, depending on the language used. 2043 2044The @samp{start} command does the equivalent of setting a temporary 2045breakpoint at the beginning of the main procedure and then invoking 2046the @samp{run} command. 2047 2048@cindex elaboration phase 2049Some programs contain an @dfn{elaboration} phase where some startup code is 2050executed before the main procedure is called. This depends on the 2051languages used to write your program. In C@t{++}, for instance, 2052constructors for static and global objects are executed before 2053@code{main} is called. It is therefore possible that the debugger stops 2054before reaching the main procedure. However, the temporary breakpoint 2055will remain to halt execution. 2056 2057Specify the arguments to give to your program as arguments to the 2058@samp{start} command. These arguments will be given verbatim to the 2059underlying @samp{run} command. Note that the same arguments will be 2060reused if no argument is provided during subsequent calls to 2061@samp{start} or @samp{run}. 2062 2063It is sometimes necessary to debug the program during elaboration. In 2064these cases, using the @code{start} command would stop the execution of 2065your program too late, as the program would have already completed the 2066elaboration phase. Under these circumstances, insert breakpoints in your 2067elaboration code before running your program. 2068 2069@kindex set exec-wrapper 2070@item set exec-wrapper @var{wrapper} 2071@itemx show exec-wrapper 2072@itemx unset exec-wrapper 2073When @samp{exec-wrapper} is set, the specified wrapper is used to 2074launch programs for debugging. @value{GDBN} starts your program 2075with a shell command of the form @kbd{exec @var{wrapper} 2076@var{program}}. Quoting is added to @var{program} and its 2077arguments, but not to @var{wrapper}, so you should add quotes if 2078appropriate for your shell. The wrapper runs until it executes 2079your program, and then @value{GDBN} takes control. 2080 2081You can use any program that eventually calls @code{execve} with 2082its arguments as a wrapper. Several standard Unix utilities do 2083this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending 2084with @code{exec "$@@"} will also work. 2085 2086For example, you can use @code{env} to pass an environment variable to 2087the debugged program, without setting the variable in your shell's 2088environment: 2089 2090@smallexample 2091(@value{GDBP}) set exec-wrapper env 'LD_PRELOAD=libtest.so' 2092(@value{GDBP}) run 2093@end smallexample 2094 2095This command is available when debugging locally on most targets, excluding 2096@sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino. 2097 2098@kindex set disable-randomization 2099@item set disable-randomization 2100@itemx set disable-randomization on 2101This option (enabled by default in @value{GDBN}) will turn off the native 2102randomization of the virtual address space of the started program. This option 2103is useful for multiple debugging sessions to make the execution better 2104reproducible and memory addresses reusable across debugging sessions. 2105 2106This feature is implemented only on certain targets, including @sc{gnu}/Linux. 2107On @sc{gnu}/Linux you can get the same behavior using 2108 2109@smallexample 2110(@value{GDBP}) set exec-wrapper setarch `uname -m` -R 2111@end smallexample 2112 2113@item set disable-randomization off 2114Leave the behavior of the started executable unchanged. Some bugs rear their 2115ugly heads only when the program is loaded at certain addresses. If your bug 2116disappears when you run the program under @value{GDBN}, that might be because 2117@value{GDBN} by default disables the address randomization on platforms, such 2118as @sc{gnu}/Linux, which do that for stand-alone programs. Use @kbd{set 2119disable-randomization off} to try to reproduce such elusive bugs. 2120 2121On targets where it is available, virtual address space randomization 2122protects the programs against certain kinds of security attacks. In these 2123cases the attacker needs to know the exact location of a concrete executable 2124code. Randomizing its location makes it impossible to inject jumps misusing 2125a code at its expected addresses. 2126 2127Prelinking shared libraries provides a startup performance advantage but it 2128makes addresses in these libraries predictable for privileged processes by 2129having just unprivileged access at the target system. Reading the shared 2130library binary gives enough information for assembling the malicious code 2131misusing it. Still even a prelinked shared library can get loaded at a new 2132random address just requiring the regular relocation process during the 2133startup. Shared libraries not already prelinked are always loaded at 2134a randomly chosen address. 2135 2136Position independent executables (PIE) contain position independent code 2137similar to the shared libraries and therefore such executables get loaded at 2138a randomly chosen address upon startup. PIE executables always load even 2139already prelinked shared libraries at a random address. You can build such 2140executable using @command{gcc -fPIE -pie}. 2141 2142Heap (malloc storage), stack and custom mmap areas are always placed randomly 2143(as long as the randomization is enabled). 2144 2145@item show disable-randomization 2146Show the current setting of the explicit disable of the native randomization of 2147the virtual address space of the started program. 2148 2149@end table 2150 2151@node Arguments 2152@section Your Program's Arguments 2153 2154@cindex arguments (to your program) 2155The arguments to your program can be specified by the arguments of the 2156@code{run} command. 2157They are passed to a shell, which expands wildcard characters and 2158performs redirection of I/O, and thence to your program. Your 2159@code{SHELL} environment variable (if it exists) specifies what shell 2160@value{GDBN} uses. If you do not define @code{SHELL}, @value{GDBN} uses 2161the default shell (@file{/bin/sh} on Unix). 2162 2163On non-Unix systems, the program is usually invoked directly by 2164@value{GDBN}, which emulates I/O redirection via the appropriate system 2165calls, and the wildcard characters are expanded by the startup code of 2166the program, not by the shell. 2167 2168@code{run} with no arguments uses the same arguments used by the previous 2169@code{run}, or those set by the @code{set args} command. 2170 2171@table @code 2172@kindex set args 2173@item set args 2174Specify the arguments to be used the next time your program is run. If 2175@code{set args} has no arguments, @code{run} executes your program 2176with no arguments. Once you have run your program with arguments, 2177using @code{set args} before the next @code{run} is the only way to run 2178it again without arguments. 2179 2180@kindex show args 2181@item show args 2182Show the arguments to give your program when it is started. 2183@end table 2184 2185@node Environment 2186@section Your Program's Environment 2187 2188@cindex environment (of your program) 2189The @dfn{environment} consists of a set of environment variables and 2190their values. Environment variables conventionally record such things as 2191your user name, your home directory, your terminal type, and your search 2192path for programs to run. Usually you set up environment variables with 2193the shell and they are inherited by all the other programs you run. When 2194debugging, it can be useful to try running your program with a modified 2195environment without having to start @value{GDBN} over again. 2196 2197@table @code 2198@kindex path 2199@item path @var{directory} 2200Add @var{directory} to the front of the @code{PATH} environment variable 2201(the search path for executables) that will be passed to your program. 2202The value of @code{PATH} used by @value{GDBN} does not change. 2203You may specify several directory names, separated by whitespace or by a 2204system-dependent separator character (@samp{:} on Unix, @samp{;} on 2205MS-DOS and MS-Windows). If @var{directory} is already in the path, it 2206is moved to the front, so it is searched sooner. 2207 2208You can use the string @samp{$cwd} to refer to whatever is the current 2209working directory at the time @value{GDBN} searches the path. If you 2210use @samp{.} instead, it refers to the directory where you executed the 2211@code{path} command. @value{GDBN} replaces @samp{.} in the 2212@var{directory} argument (with the current path) before adding 2213@var{directory} to the search path. 2214@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to 2215@c document that, since repeating it would be a no-op. 2216 2217@kindex show paths 2218@item show paths 2219Display the list of search paths for executables (the @code{PATH} 2220environment variable). 2221 2222@kindex show environment 2223@item show environment @r{[}@var{varname}@r{]} 2224Print the value of environment variable @var{varname} to be given to 2225your program when it starts. If you do not supply @var{varname}, 2226print the names and values of all environment variables to be given to 2227your program. You can abbreviate @code{environment} as @code{env}. 2228 2229@kindex set environment 2230@item set environment @var{varname} @r{[}=@var{value}@r{]} 2231Set environment variable @var{varname} to @var{value}. The value 2232changes for your program only, not for @value{GDBN} itself. @var{value} may 2233be any string; the values of environment variables are just strings, and 2234any interpretation is supplied by your program itself. The @var{value} 2235parameter is optional; if it is eliminated, the variable is set to a 2236null value. 2237@c "any string" here does not include leading, trailing 2238@c blanks. Gnu asks: does anyone care? 2239 2240For example, this command: 2241 2242@smallexample 2243set env USER = foo 2244@end smallexample 2245 2246@noindent 2247tells the debugged program, when subsequently run, that its user is named 2248@samp{foo}. (The spaces around @samp{=} are used for clarity here; they 2249are not actually required.) 2250 2251@kindex unset environment 2252@item unset environment @var{varname} 2253Remove variable @var{varname} from the environment to be passed to your 2254program. This is different from @samp{set env @var{varname} =}; 2255@code{unset environment} removes the variable from the environment, 2256rather than assigning it an empty value. 2257@end table 2258 2259@emph{Warning:} On Unix systems, @value{GDBN} runs your program using 2260the shell indicated 2261by your @code{SHELL} environment variable if it exists (or 2262@code{/bin/sh} if not). If your @code{SHELL} variable names a shell 2263that runs an initialization file---such as @file{.cshrc} for C-shell, or 2264@file{.bashrc} for BASH---any variables you set in that file affect 2265your program. You may wish to move setting of environment variables to 2266files that are only run when you sign on, such as @file{.login} or 2267@file{.profile}. 2268 2269@node Working Directory 2270@section Your Program's Working Directory 2271 2272@cindex working directory (of your program) 2273Each time you start your program with @code{run}, it inherits its 2274working directory from the current working directory of @value{GDBN}. 2275The @value{GDBN} working directory is initially whatever it inherited 2276from its parent process (typically the shell), but you can specify a new 2277working directory in @value{GDBN} with the @code{cd} command. 2278 2279The @value{GDBN} working directory also serves as a default for the commands 2280that specify files for @value{GDBN} to operate on. @xref{Files, ,Commands to 2281Specify Files}. 2282 2283@table @code 2284@kindex cd 2285@cindex change working directory 2286@item cd @r{[}@var{directory}@r{]} 2287Set the @value{GDBN} working directory to @var{directory}. If not 2288given, @var{directory} uses @file{'~'}. 2289 2290@kindex pwd 2291@item pwd 2292Print the @value{GDBN} working directory. 2293@end table 2294 2295It is generally impossible to find the current working directory of 2296the process being debugged (since a program can change its directory 2297during its run). If you work on a system where @value{GDBN} is 2298configured with the @file{/proc} support, you can use the @code{info 2299proc} command (@pxref{SVR4 Process Information}) to find out the 2300current working directory of the debuggee. 2301 2302@node Input/Output 2303@section Your Program's Input and Output 2304 2305@cindex redirection 2306@cindex i/o 2307@cindex terminal 2308By default, the program you run under @value{GDBN} does input and output to 2309the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal 2310to its own terminal modes to interact with you, but it records the terminal 2311modes your program was using and switches back to them when you continue 2312running your program. 2313 2314@table @code 2315@kindex info terminal 2316@item info terminal 2317Displays information recorded by @value{GDBN} about the terminal modes your 2318program is using. 2319@end table 2320 2321You can redirect your program's input and/or output using shell 2322redirection with the @code{run} command. For example, 2323 2324@smallexample 2325run > outfile 2326@end smallexample 2327 2328@noindent 2329starts your program, diverting its output to the file @file{outfile}. 2330 2331@kindex tty 2332@cindex controlling terminal 2333Another way to specify where your program should do input and output is 2334with the @code{tty} command. This command accepts a file name as 2335argument, and causes this file to be the default for future @code{run} 2336commands. It also resets the controlling terminal for the child 2337process, for future @code{run} commands. For example, 2338 2339@smallexample 2340tty /dev/ttyb 2341@end smallexample 2342 2343@noindent 2344directs that processes started with subsequent @code{run} commands 2345default to do input and output on the terminal @file{/dev/ttyb} and have 2346that as their controlling terminal. 2347 2348An explicit redirection in @code{run} overrides the @code{tty} command's 2349effect on the input/output device, but not its effect on the controlling 2350terminal. 2351 2352When you use the @code{tty} command or redirect input in the @code{run} 2353command, only the input @emph{for your program} is affected. The input 2354for @value{GDBN} still comes from your terminal. @code{tty} is an alias 2355for @code{set inferior-tty}. 2356 2357@cindex inferior tty 2358@cindex set inferior controlling terminal 2359You can use the @code{show inferior-tty} command to tell @value{GDBN} to 2360display the name of the terminal that will be used for future runs of your 2361program. 2362 2363@table @code 2364@item set inferior-tty /dev/ttyb 2365@kindex set inferior-tty 2366Set the tty for the program being debugged to /dev/ttyb. 2367 2368@item show inferior-tty 2369@kindex show inferior-tty 2370Show the current tty for the program being debugged. 2371@end table 2372 2373@node Attach 2374@section Debugging an Already-running Process 2375@kindex attach 2376@cindex attach 2377 2378@table @code 2379@item attach @var{process-id} 2380This command attaches to a running process---one that was started 2381outside @value{GDBN}. (@code{info files} shows your active 2382targets.) The command takes as argument a process ID. The usual way to 2383find out the @var{process-id} of a Unix process is with the @code{ps} utility, 2384or with the @samp{jobs -l} shell command. 2385 2386@code{attach} does not repeat if you press @key{RET} a second time after 2387executing the command. 2388@end table 2389 2390To use @code{attach}, your program must be running in an environment 2391which supports processes; for example, @code{attach} does not work for 2392programs on bare-board targets that lack an operating system. You must 2393also have permission to send the process a signal. 2394 2395When you use @code{attach}, the debugger finds the program running in 2396the process first by looking in the current working directory, then (if 2397the program is not found) by using the source file search path 2398(@pxref{Source Path, ,Specifying Source Directories}). You can also use 2399the @code{file} command to load the program. @xref{Files, ,Commands to 2400Specify Files}. 2401 2402The first thing @value{GDBN} does after arranging to debug the specified 2403process is to stop it. You can examine and modify an attached process 2404with all the @value{GDBN} commands that are ordinarily available when 2405you start processes with @code{run}. You can insert breakpoints; you 2406can step and continue; you can modify storage. If you would rather the 2407process continue running, you may use the @code{continue} command after 2408attaching @value{GDBN} to the process. 2409 2410@table @code 2411@kindex detach 2412@item detach 2413When you have finished debugging the attached process, you can use the 2414@code{detach} command to release it from @value{GDBN} control. Detaching 2415the process continues its execution. After the @code{detach} command, 2416that process and @value{GDBN} become completely independent once more, and you 2417are ready to @code{attach} another process or start one with @code{run}. 2418@code{detach} does not repeat if you press @key{RET} again after 2419executing the command. 2420@end table 2421 2422If you exit @value{GDBN} while you have an attached process, you detach 2423that process. If you use the @code{run} command, you kill that process. 2424By default, @value{GDBN} asks for confirmation if you try to do either of these 2425things; you can control whether or not you need to confirm by using the 2426@code{set confirm} command (@pxref{Messages/Warnings, ,Optional Warnings and 2427Messages}). 2428 2429@node Kill Process 2430@section Killing the Child Process 2431 2432@table @code 2433@kindex kill 2434@item kill 2435Kill the child process in which your program is running under @value{GDBN}. 2436@end table 2437 2438This command is useful if you wish to debug a core dump instead of a 2439running process. @value{GDBN} ignores any core dump file while your program 2440is running. 2441 2442On some operating systems, a program cannot be executed outside @value{GDBN} 2443while you have breakpoints set on it inside @value{GDBN}. You can use the 2444@code{kill} command in this situation to permit running your program 2445outside the debugger. 2446 2447The @code{kill} command is also useful if you wish to recompile and 2448relink your program, since on many systems it is impossible to modify an 2449executable file while it is running in a process. In this case, when you 2450next type @code{run}, @value{GDBN} notices that the file has changed, and 2451reads the symbol table again (while trying to preserve your current 2452breakpoint settings). 2453 2454@node Inferiors and Programs 2455@section Debugging Multiple Inferiors and Programs 2456 2457@value{GDBN} lets you run and debug multiple programs in a single 2458session. In addition, @value{GDBN} on some systems may let you run 2459several programs simultaneously (otherwise you have to exit from one 2460before starting another). In the most general case, you can have 2461multiple threads of execution in each of multiple processes, launched 2462from multiple executables. 2463 2464@cindex inferior 2465@value{GDBN} represents the state of each program execution with an 2466object called an @dfn{inferior}. An inferior typically corresponds to 2467a process, but is more general and applies also to targets that do not 2468have processes. Inferiors may be created before a process runs, and 2469may be retained after a process exits. Inferiors have unique 2470identifiers that are different from process ids. Usually each 2471inferior will also have its own distinct address space, although some 2472embedded targets may have several inferiors running in different parts 2473of a single address space. Each inferior may in turn have multiple 2474threads running in it. 2475 2476To find out what inferiors exist at any moment, use @w{@code{info 2477inferiors}}: 2478 2479@table @code 2480@kindex info inferiors 2481@item info inferiors 2482Print a list of all inferiors currently being managed by @value{GDBN}. 2483 2484@value{GDBN} displays for each inferior (in this order): 2485 2486@enumerate 2487@item 2488the inferior number assigned by @value{GDBN} 2489 2490@item 2491the target system's inferior identifier 2492 2493@item 2494the name of the executable the inferior is running. 2495 2496@end enumerate 2497 2498@noindent 2499An asterisk @samp{*} preceding the @value{GDBN} inferior number 2500indicates the current inferior. 2501 2502For example, 2503@end table 2504@c end table here to get a little more width for example 2505 2506@smallexample 2507(@value{GDBP}) info inferiors 2508 Num Description Executable 2509 2 process 2307 hello 2510* 1 process 3401 goodbye 2511@end smallexample 2512 2513To switch focus between inferiors, use the @code{inferior} command: 2514 2515@table @code 2516@kindex inferior @var{infno} 2517@item inferior @var{infno} 2518Make inferior number @var{infno} the current inferior. The argument 2519@var{infno} is the inferior number assigned by @value{GDBN}, as shown 2520in the first field of the @samp{info inferiors} display. 2521@end table 2522 2523 2524You can get multiple executables into a debugging session via the 2525@code{add-inferior} and @w{@code{clone-inferior}} commands. On some 2526systems @value{GDBN} can add inferiors to the debug session 2527automatically by following calls to @code{fork} and @code{exec}. To 2528remove inferiors from the debugging session use the 2529@w{@code{remove-inferiors}} command. 2530 2531@table @code 2532@kindex add-inferior 2533@item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ] 2534Adds @var{n} inferiors to be run using @var{executable} as the 2535executable. @var{n} defaults to 1. If no executable is specified, 2536the inferiors begins empty, with no program. You can still assign or 2537change the program assigned to the inferior at any time by using the 2538@code{file} command with the executable name as its argument. 2539 2540@kindex clone-inferior 2541@item clone-inferior [ -copies @var{n} ] [ @var{infno} ] 2542Adds @var{n} inferiors ready to execute the same program as inferior 2543@var{infno}. @var{n} defaults to 1. @var{infno} defaults to the 2544number of the current inferior. This is a convenient command when you 2545want to run another instance of the inferior you are debugging. 2546 2547@smallexample 2548(@value{GDBP}) info inferiors 2549 Num Description Executable 2550* 1 process 29964 helloworld 2551(@value{GDBP}) clone-inferior 2552Added inferior 2. 25531 inferiors added. 2554(@value{GDBP}) info inferiors 2555 Num Description Executable 2556 2 <null> helloworld 2557* 1 process 29964 helloworld 2558@end smallexample 2559 2560You can now simply switch focus to inferior 2 and run it. 2561 2562@kindex remove-inferiors 2563@item remove-inferiors @var{infno}@dots{} 2564Removes the inferior or inferiors @var{infno}@dots{}. It is not 2565possible to remove an inferior that is running with this command. For 2566those, use the @code{kill} or @code{detach} command first. 2567 2568@end table 2569 2570To quit debugging one of the running inferiors that is not the current 2571inferior, you can either detach from it by using the @w{@code{detach 2572inferior}} command (allowing it to run independently), or kill it 2573using the @w{@code{kill inferiors}} command: 2574 2575@table @code 2576@kindex detach inferiors @var{infno}@dots{} 2577@item detach inferior @var{infno}@dots{} 2578Detach from the inferior or inferiors identified by @value{GDBN} 2579inferior number(s) @var{infno}@dots{}. Note that the inferior's entry 2580still stays on the list of inferiors shown by @code{info inferiors}, 2581but its Description will show @samp{<null>}. 2582 2583@kindex kill inferiors @var{infno}@dots{} 2584@item kill inferiors @var{infno}@dots{} 2585Kill the inferior or inferiors identified by @value{GDBN} inferior 2586number(s) @var{infno}@dots{}. Note that the inferior's entry still 2587stays on the list of inferiors shown by @code{info inferiors}, but its 2588Description will show @samp{<null>}. 2589@end table 2590 2591After the successful completion of a command such as @code{detach}, 2592@code{detach inferiors}, @code{kill} or @code{kill inferiors}, or after 2593a normal process exit, the inferior is still valid and listed with 2594@code{info inferiors}, ready to be restarted. 2595 2596 2597To be notified when inferiors are started or exit under @value{GDBN}'s 2598control use @w{@code{set print inferior-events}}: 2599 2600@table @code 2601@kindex set print inferior-events 2602@cindex print messages on inferior start and exit 2603@item set print inferior-events 2604@itemx set print inferior-events on 2605@itemx set print inferior-events off 2606The @code{set print inferior-events} command allows you to enable or 2607disable printing of messages when @value{GDBN} notices that new 2608inferiors have started or that inferiors have exited or have been 2609detached. By default, these messages will not be printed. 2610 2611@kindex show print inferior-events 2612@item show print inferior-events 2613Show whether messages will be printed when @value{GDBN} detects that 2614inferiors have started, exited or have been detached. 2615@end table 2616 2617Many commands will work the same with multiple programs as with a 2618single program: e.g., @code{print myglobal} will simply display the 2619value of @code{myglobal} in the current inferior. 2620 2621 2622Occasionaly, when debugging @value{GDBN} itself, it may be useful to 2623get more info about the relationship of inferiors, programs, address 2624spaces in a debug session. You can do that with the @w{@code{maint 2625info program-spaces}} command. 2626 2627@table @code 2628@kindex maint info program-spaces 2629@item maint info program-spaces 2630Print a list of all program spaces currently being managed by 2631@value{GDBN}. 2632 2633@value{GDBN} displays for each program space (in this order): 2634 2635@enumerate 2636@item 2637the program space number assigned by @value{GDBN} 2638 2639@item 2640the name of the executable loaded into the program space, with e.g., 2641the @code{file} command. 2642 2643@end enumerate 2644 2645@noindent 2646An asterisk @samp{*} preceding the @value{GDBN} program space number 2647indicates the current program space. 2648 2649In addition, below each program space line, @value{GDBN} prints extra 2650information that isn't suitable to display in tabular form. For 2651example, the list of inferiors bound to the program space. 2652 2653@smallexample 2654(@value{GDBP}) maint info program-spaces 2655 Id Executable 2656 2 goodbye 2657 Bound inferiors: ID 1 (process 21561) 2658* 1 hello 2659@end smallexample 2660 2661Here we can see that no inferior is running the program @code{hello}, 2662while @code{process 21561} is running the program @code{goodbye}. On 2663some targets, it is possible that multiple inferiors are bound to the 2664same program space. The most common example is that of debugging both 2665the parent and child processes of a @code{vfork} call. For example, 2666 2667@smallexample 2668(@value{GDBP}) maint info program-spaces 2669 Id Executable 2670* 1 vfork-test 2671 Bound inferiors: ID 2 (process 18050), ID 1 (process 18045) 2672@end smallexample 2673 2674Here, both inferior 2 and inferior 1 are running in the same program 2675space as a result of inferior 1 having executed a @code{vfork} call. 2676@end table 2677 2678@node Threads 2679@section Debugging Programs with Multiple Threads 2680 2681@cindex threads of execution 2682@cindex multiple threads 2683@cindex switching threads 2684In some operating systems, such as HP-UX and Solaris, a single program 2685may have more than one @dfn{thread} of execution. The precise semantics 2686of threads differ from one operating system to another, but in general 2687the threads of a single program are akin to multiple processes---except 2688that they share one address space (that is, they can all examine and 2689modify the same variables). On the other hand, each thread has its own 2690registers and execution stack, and perhaps private memory. 2691 2692@value{GDBN} provides these facilities for debugging multi-thread 2693programs: 2694 2695@itemize @bullet 2696@item automatic notification of new threads 2697@item @samp{thread @var{threadno}}, a command to switch among threads 2698@item @samp{info threads}, a command to inquire about existing threads 2699@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}}, 2700a command to apply a command to a list of threads 2701@item thread-specific breakpoints 2702@item @samp{set print thread-events}, which controls printing of 2703messages on thread start and exit. 2704@item @samp{set libthread-db-search-path @var{path}}, which lets 2705the user specify which @code{libthread_db} to use if the default choice 2706isn't compatible with the program. 2707@end itemize 2708 2709@quotation 2710@emph{Warning:} These facilities are not yet available on every 2711@value{GDBN} configuration where the operating system supports threads. 2712If your @value{GDBN} does not support threads, these commands have no 2713effect. For example, a system without thread support shows no output 2714from @samp{info threads}, and always rejects the @code{thread} command, 2715like this: 2716 2717@smallexample 2718(@value{GDBP}) info threads 2719(@value{GDBP}) thread 1 2720Thread ID 1 not known. Use the "info threads" command to 2721see the IDs of currently known threads. 2722@end smallexample 2723@c FIXME to implementors: how hard would it be to say "sorry, this GDB 2724@c doesn't support threads"? 2725@end quotation 2726 2727@cindex focus of debugging 2728@cindex current thread 2729The @value{GDBN} thread debugging facility allows you to observe all 2730threads while your program runs---but whenever @value{GDBN} takes 2731control, one thread in particular is always the focus of debugging. 2732This thread is called the @dfn{current thread}. Debugging commands show 2733program information from the perspective of the current thread. 2734 2735@cindex @code{New} @var{systag} message 2736@cindex thread identifier (system) 2737@c FIXME-implementors!! It would be more helpful if the [New...] message 2738@c included GDB's numeric thread handle, so you could just go to that 2739@c thread without first checking `info threads'. 2740Whenever @value{GDBN} detects a new thread in your program, it displays 2741the target system's identification for the thread with a message in the 2742form @samp{[New @var{systag}]}. @var{systag} is a thread identifier 2743whose form varies depending on the particular system. For example, on 2744@sc{gnu}/Linux, you might see 2745 2746@smallexample 2747[New Thread 0x41e02940 (LWP 25582)] 2748@end smallexample 2749 2750@noindent 2751when @value{GDBN} notices a new thread. In contrast, on an SGI system, 2752the @var{systag} is simply something like @samp{process 368}, with no 2753further qualifier. 2754 2755@c FIXME!! (1) Does the [New...] message appear even for the very first 2756@c thread of a program, or does it only appear for the 2757@c second---i.e.@: when it becomes obvious we have a multithread 2758@c program? 2759@c (2) *Is* there necessarily a first thread always? Or do some 2760@c multithread systems permit starting a program with multiple 2761@c threads ab initio? 2762 2763@cindex thread number 2764@cindex thread identifier (GDB) 2765For debugging purposes, @value{GDBN} associates its own thread 2766number---always a single integer---with each thread in your program. 2767 2768@table @code 2769@kindex info threads 2770@item info threads @r{[}@var{id}@dots{}@r{]} 2771Display a summary of all threads currently in your program. Optional 2772argument @var{id}@dots{} is one or more thread ids separated by spaces, and 2773means to print information only about the specified thread or threads. 2774@value{GDBN} displays for each thread (in this order): 2775 2776@enumerate 2777@item 2778the thread number assigned by @value{GDBN} 2779 2780@item 2781the target system's thread identifier (@var{systag}) 2782 2783@item 2784the thread's name, if one is known. A thread can either be named by 2785the user (see @code{thread name}, below), or, in some cases, by the 2786program itself. 2787 2788@item 2789the current stack frame summary for that thread 2790@end enumerate 2791 2792@noindent 2793An asterisk @samp{*} to the left of the @value{GDBN} thread number 2794indicates the current thread. 2795 2796For example, 2797@end table 2798@c end table here to get a little more width for example 2799 2800@smallexample 2801(@value{GDBP}) info threads 2802 Id Target Id Frame 2803 3 process 35 thread 27 0x34e5 in sigpause () 2804 2 process 35 thread 23 0x34e5 in sigpause () 2805* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) 2806 at threadtest.c:68 2807@end smallexample 2808 2809On Solaris, you can display more information about user threads with a 2810Solaris-specific command: 2811 2812@table @code 2813@item maint info sol-threads 2814@kindex maint info sol-threads 2815@cindex thread info (Solaris) 2816Display info on Solaris user threads. 2817@end table 2818 2819@table @code 2820@kindex thread @var{threadno} 2821@item thread @var{threadno} 2822Make thread number @var{threadno} the current thread. The command 2823argument @var{threadno} is the internal @value{GDBN} thread number, as 2824shown in the first field of the @samp{info threads} display. 2825@value{GDBN} responds by displaying the system identifier of the thread 2826you selected, and its current stack frame summary: 2827 2828@smallexample 2829(@value{GDBP}) thread 2 2830[Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))] 2831#0 some_function (ignore=0x0) at example.c:8 28328 printf ("hello\n"); 2833@end smallexample 2834 2835@noindent 2836As with the @samp{[New @dots{}]} message, the form of the text after 2837@samp{Switching to} depends on your system's conventions for identifying 2838threads. 2839 2840@vindex $_thread@r{, convenience variable} 2841The debugger convenience variable @samp{$_thread} contains the number 2842of the current thread. You may find this useful in writing breakpoint 2843conditional expressions, command scripts, and so forth. See 2844@xref{Convenience Vars,, Convenience Variables}, for general 2845information on convenience variables. 2846 2847@kindex thread apply 2848@cindex apply command to several threads 2849@item thread apply [@var{threadno} | all] @var{command} 2850The @code{thread apply} command allows you to apply the named 2851@var{command} to one or more threads. Specify the numbers of the 2852threads that you want affected with the command argument 2853@var{threadno}. It can be a single thread number, one of the numbers 2854shown in the first field of the @samp{info threads} display; or it 2855could be a range of thread numbers, as in @code{2-4}. To apply a 2856command to all threads, type @kbd{thread apply all @var{command}}. 2857 2858@kindex thread name 2859@cindex name a thread 2860@item thread name [@var{name}] 2861This command assigns a name to the current thread. If no argument is 2862given, any existing user-specified name is removed. The thread name 2863appears in the @samp{info threads} display. 2864 2865On some systems, such as @sc{gnu}/Linux, @value{GDBN} is able to 2866determine the name of the thread as given by the OS. On these 2867systems, a name specified with @samp{thread name} will override the 2868system-give name, and removing the user-specified name will cause 2869@value{GDBN} to once again display the system-specified name. 2870 2871@kindex thread find 2872@cindex search for a thread 2873@item thread find [@var{regexp}] 2874Search for and display thread ids whose name or @var{systag} 2875matches the supplied regular expression. 2876 2877As well as being the complement to the @samp{thread name} command, 2878this command also allows you to identify a thread by its target 2879@var{systag}. For instance, on @sc{gnu}/Linux, the target @var{systag} 2880is the LWP id. 2881 2882@smallexample 2883(@value{GDBN}) thread find 26688 2884Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)' 2885(@value{GDBN}) info thread 4 2886 Id Target Id Frame 2887 4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select () 2888@end smallexample 2889 2890@kindex set print thread-events 2891@cindex print messages on thread start and exit 2892@item set print thread-events 2893@itemx set print thread-events on 2894@itemx set print thread-events off 2895The @code{set print thread-events} command allows you to enable or 2896disable printing of messages when @value{GDBN} notices that new threads have 2897started or that threads have exited. By default, these messages will 2898be printed if detection of these events is supported by the target. 2899Note that these messages cannot be disabled on all targets. 2900 2901@kindex show print thread-events 2902@item show print thread-events 2903Show whether messages will be printed when @value{GDBN} detects that threads 2904have started and exited. 2905@end table 2906 2907@xref{Thread Stops,,Stopping and Starting Multi-thread Programs}, for 2908more information about how @value{GDBN} behaves when you stop and start 2909programs with multiple threads. 2910 2911@xref{Set Watchpoints,,Setting Watchpoints}, for information about 2912watchpoints in programs with multiple threads. 2913 2914@anchor{set libthread-db-search-path} 2915@table @code 2916@kindex set libthread-db-search-path 2917@cindex search path for @code{libthread_db} 2918@item set libthread-db-search-path @r{[}@var{path}@r{]} 2919If this variable is set, @var{path} is a colon-separated list of 2920directories @value{GDBN} will use to search for @code{libthread_db}. 2921If you omit @var{path}, @samp{libthread-db-search-path} will be reset to 2922its default value (@code{$sdir:$pdir} on @sc{gnu}/Linux and Solaris systems). 2923Internally, the default value comes from the @code{LIBTHREAD_DB_SEARCH_PATH} 2924macro. 2925 2926On @sc{gnu}/Linux and Solaris systems, @value{GDBN} uses a ``helper'' 2927@code{libthread_db} library to obtain information about threads in the 2928inferior process. @value{GDBN} will use @samp{libthread-db-search-path} 2929to find @code{libthread_db}. @value{GDBN} also consults first if inferior 2930specific thread debugging library loading is enabled 2931by @samp{set auto-load libthread-db} (@pxref{libthread_db.so.1 file}). 2932 2933A special entry @samp{$sdir} for @samp{libthread-db-search-path} 2934refers to the default system directories that are 2935normally searched for loading shared libraries. The @samp{$sdir} entry 2936is the only kind not needing to be enabled by @samp{set auto-load libthread-db} 2937(@pxref{libthread_db.so.1 file}). 2938 2939A special entry @samp{$pdir} for @samp{libthread-db-search-path} 2940refers to the directory from which @code{libpthread} 2941was loaded in the inferior process. 2942 2943For any @code{libthread_db} library @value{GDBN} finds in above directories, 2944@value{GDBN} attempts to initialize it with the current inferior process. 2945If this initialization fails (which could happen because of a version 2946mismatch between @code{libthread_db} and @code{libpthread}), @value{GDBN} 2947will unload @code{libthread_db}, and continue with the next directory. 2948If none of @code{libthread_db} libraries initialize successfully, 2949@value{GDBN} will issue a warning and thread debugging will be disabled. 2950 2951Setting @code{libthread-db-search-path} is currently implemented 2952only on some platforms. 2953 2954@kindex show libthread-db-search-path 2955@item show libthread-db-search-path 2956Display current libthread_db search path. 2957 2958@kindex set debug libthread-db 2959@kindex show debug libthread-db 2960@cindex debugging @code{libthread_db} 2961@item set debug libthread-db 2962@itemx show debug libthread-db 2963Turns on or off display of @code{libthread_db}-related events. 2964Use @code{1} to enable, @code{0} to disable. 2965@end table 2966 2967@node Forks 2968@section Debugging Forks 2969 2970@cindex fork, debugging programs which call 2971@cindex multiple processes 2972@cindex processes, multiple 2973On most systems, @value{GDBN} has no special support for debugging 2974programs which create additional processes using the @code{fork} 2975function. When a program forks, @value{GDBN} will continue to debug the 2976parent process and the child process will run unimpeded. If you have 2977set a breakpoint in any code which the child then executes, the child 2978will get a @code{SIGTRAP} signal which (unless it catches the signal) 2979will cause it to terminate. 2980 2981However, if you want to debug the child process there is a workaround 2982which isn't too painful. Put a call to @code{sleep} in the code which 2983the child process executes after the fork. It may be useful to sleep 2984only if a certain environment variable is set, or a certain file exists, 2985so that the delay need not occur when you don't want to run @value{GDBN} 2986on the child. While the child is sleeping, use the @code{ps} program to 2987get its process ID. Then tell @value{GDBN} (a new invocation of 2988@value{GDBN} if you are also debugging the parent process) to attach to 2989the child process (@pxref{Attach}). From that point on you can debug 2990the child process just like any other process which you attached to. 2991 2992On some systems, @value{GDBN} provides support for debugging programs that 2993create additional processes using the @code{fork} or @code{vfork} functions. 2994Currently, the only platforms with this feature are HP-UX (11.x and later 2995only?) and @sc{gnu}/Linux (kernel version 2.5.60 and later). 2996 2997By default, when a program forks, @value{GDBN} will continue to debug 2998the parent process and the child process will run unimpeded. 2999 3000If you want to follow the child process instead of the parent process, 3001use the command @w{@code{set follow-fork-mode}}. 3002 3003@table @code 3004@kindex set follow-fork-mode 3005@item set follow-fork-mode @var{mode} 3006Set the debugger response to a program call of @code{fork} or 3007@code{vfork}. A call to @code{fork} or @code{vfork} creates a new 3008process. The @var{mode} argument can be: 3009 3010@table @code 3011@item parent 3012The original process is debugged after a fork. The child process runs 3013unimpeded. This is the default. 3014 3015@item child 3016The new process is debugged after a fork. The parent process runs 3017unimpeded. 3018 3019@end table 3020 3021@kindex show follow-fork-mode 3022@item show follow-fork-mode 3023Display the current debugger response to a @code{fork} or @code{vfork} call. 3024@end table 3025 3026@cindex debugging multiple processes 3027On Linux, if you want to debug both the parent and child processes, use the 3028command @w{@code{set detach-on-fork}}. 3029 3030@table @code 3031@kindex set detach-on-fork 3032@item set detach-on-fork @var{mode} 3033Tells gdb whether to detach one of the processes after a fork, or 3034retain debugger control over them both. 3035 3036@table @code 3037@item on 3038The child process (or parent process, depending on the value of 3039@code{follow-fork-mode}) will be detached and allowed to run 3040independently. This is the default. 3041 3042@item off 3043Both processes will be held under the control of @value{GDBN}. 3044One process (child or parent, depending on the value of 3045@code{follow-fork-mode}) is debugged as usual, while the other 3046is held suspended. 3047 3048@end table 3049 3050@kindex show detach-on-fork 3051@item show detach-on-fork 3052Show whether detach-on-fork mode is on/off. 3053@end table 3054 3055If you choose to set @samp{detach-on-fork} mode off, then @value{GDBN} 3056will retain control of all forked processes (including nested forks). 3057You can list the forked processes under the control of @value{GDBN} by 3058using the @w{@code{info inferiors}} command, and switch from one fork 3059to another by using the @code{inferior} command (@pxref{Inferiors and 3060Programs, ,Debugging Multiple Inferiors and Programs}). 3061 3062To quit debugging one of the forked processes, you can either detach 3063from it by using the @w{@code{detach inferiors}} command (allowing it 3064to run independently), or kill it using the @w{@code{kill inferiors}} 3065command. @xref{Inferiors and Programs, ,Debugging Multiple Inferiors 3066and Programs}. 3067 3068If you ask to debug a child process and a @code{vfork} is followed by an 3069@code{exec}, @value{GDBN} executes the new target up to the first 3070breakpoint in the new target. If you have a breakpoint set on 3071@code{main} in your original program, the breakpoint will also be set on 3072the child process's @code{main}. 3073 3074On some systems, when a child process is spawned by @code{vfork}, you 3075cannot debug the child or parent until an @code{exec} call completes. 3076 3077If you issue a @code{run} command to @value{GDBN} after an @code{exec} 3078call executes, the new target restarts. To restart the parent 3079process, use the @code{file} command with the parent executable name 3080as its argument. By default, after an @code{exec} call executes, 3081@value{GDBN} discards the symbols of the previous executable image. 3082You can change this behaviour with the @w{@code{set follow-exec-mode}} 3083command. 3084 3085@table @code 3086@kindex set follow-exec-mode 3087@item set follow-exec-mode @var{mode} 3088 3089Set debugger response to a program call of @code{exec}. An 3090@code{exec} call replaces the program image of a process. 3091 3092@code{follow-exec-mode} can be: 3093 3094@table @code 3095@item new 3096@value{GDBN} creates a new inferior and rebinds the process to this 3097new inferior. The program the process was running before the 3098@code{exec} call can be restarted afterwards by restarting the 3099original inferior. 3100 3101For example: 3102 3103@smallexample 3104(@value{GDBP}) info inferiors 3105(gdb) info inferior 3106 Id Description Executable 3107* 1 <null> prog1 3108(@value{GDBP}) run 3109process 12020 is executing new program: prog2 3110Program exited normally. 3111(@value{GDBP}) info inferiors 3112 Id Description Executable 3113* 2 <null> prog2 3114 1 <null> prog1 3115@end smallexample 3116 3117@item same 3118@value{GDBN} keeps the process bound to the same inferior. The new 3119executable image replaces the previous executable loaded in the 3120inferior. Restarting the inferior after the @code{exec} call, with 3121e.g., the @code{run} command, restarts the executable the process was 3122running after the @code{exec} call. This is the default mode. 3123 3124For example: 3125 3126@smallexample 3127(@value{GDBP}) info inferiors 3128 Id Description Executable 3129* 1 <null> prog1 3130(@value{GDBP}) run 3131process 12020 is executing new program: prog2 3132Program exited normally. 3133(@value{GDBP}) info inferiors 3134 Id Description Executable 3135* 1 <null> prog2 3136@end smallexample 3137 3138@end table 3139@end table 3140 3141You can use the @code{catch} command to make @value{GDBN} stop whenever 3142a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set 3143Catchpoints, ,Setting Catchpoints}. 3144 3145@node Checkpoint/Restart 3146@section Setting a @emph{Bookmark} to Return to Later 3147 3148@cindex checkpoint 3149@cindex restart 3150@cindex bookmark 3151@cindex snapshot of a process 3152@cindex rewind program state 3153 3154On certain operating systems@footnote{Currently, only 3155@sc{gnu}/Linux.}, @value{GDBN} is able to save a @dfn{snapshot} of a 3156program's state, called a @dfn{checkpoint}, and come back to it 3157later. 3158 3159Returning to a checkpoint effectively undoes everything that has 3160happened in the program since the @code{checkpoint} was saved. This 3161includes changes in memory, registers, and even (within some limits) 3162system state. Effectively, it is like going back in time to the 3163moment when the checkpoint was saved. 3164 3165Thus, if you're stepping thru a program and you think you're 3166getting close to the point where things go wrong, you can save 3167a checkpoint. Then, if you accidentally go too far and miss 3168the critical statement, instead of having to restart your program 3169from the beginning, you can just go back to the checkpoint and 3170start again from there. 3171 3172This can be especially useful if it takes a lot of time or 3173steps to reach the point where you think the bug occurs. 3174 3175To use the @code{checkpoint}/@code{restart} method of debugging: 3176 3177@table @code 3178@kindex checkpoint 3179@item checkpoint 3180Save a snapshot of the debugged program's current execution state. 3181The @code{checkpoint} command takes no arguments, but each checkpoint 3182is assigned a small integer id, similar to a breakpoint id. 3183 3184@kindex info checkpoints 3185@item info checkpoints 3186List the checkpoints that have been saved in the current debugging 3187session. For each checkpoint, the following information will be 3188listed: 3189 3190@table @code 3191@item Checkpoint ID 3192@item Process ID 3193@item Code Address 3194@item Source line, or label 3195@end table 3196 3197@kindex restart @var{checkpoint-id} 3198@item restart @var{checkpoint-id} 3199Restore the program state that was saved as checkpoint number 3200@var{checkpoint-id}. All program variables, registers, stack frames 3201etc.@: will be returned to the values that they had when the checkpoint 3202was saved. In essence, gdb will ``wind back the clock'' to the point 3203in time when the checkpoint was saved. 3204 3205Note that breakpoints, @value{GDBN} variables, command history etc. 3206are not affected by restoring a checkpoint. In general, a checkpoint 3207only restores things that reside in the program being debugged, not in 3208the debugger. 3209 3210@kindex delete checkpoint @var{checkpoint-id} 3211@item delete checkpoint @var{checkpoint-id} 3212Delete the previously-saved checkpoint identified by @var{checkpoint-id}. 3213 3214@end table 3215 3216Returning to a previously saved checkpoint will restore the user state 3217of the program being debugged, plus a significant subset of the system 3218(OS) state, including file pointers. It won't ``un-write'' data from 3219a file, but it will rewind the file pointer to the previous location, 3220so that the previously written data can be overwritten. For files 3221opened in read mode, the pointer will also be restored so that the 3222previously read data can be read again. 3223 3224Of course, characters that have been sent to a printer (or other 3225external device) cannot be ``snatched back'', and characters received 3226from eg.@: a serial device can be removed from internal program buffers, 3227but they cannot be ``pushed back'' into the serial pipeline, ready to 3228be received again. Similarly, the actual contents of files that have 3229been changed cannot be restored (at this time). 3230 3231However, within those constraints, you actually can ``rewind'' your 3232program to a previously saved point in time, and begin debugging it 3233again --- and you can change the course of events so as to debug a 3234different execution path this time. 3235 3236@cindex checkpoints and process id 3237Finally, there is one bit of internal program state that will be 3238different when you return to a checkpoint --- the program's process 3239id. Each checkpoint will have a unique process id (or @var{pid}), 3240and each will be different from the program's original @var{pid}. 3241If your program has saved a local copy of its process id, this could 3242potentially pose a problem. 3243 3244@subsection A Non-obvious Benefit of Using Checkpoints 3245 3246On some systems such as @sc{gnu}/Linux, address space randomization 3247is performed on new processes for security reasons. This makes it 3248difficult or impossible to set a breakpoint, or watchpoint, on an 3249absolute address if you have to restart the program, since the 3250absolute location of a symbol will change from one execution to the 3251next. 3252 3253A checkpoint, however, is an @emph{identical} copy of a process. 3254Therefore if you create a checkpoint at (eg.@:) the start of main, 3255and simply return to that checkpoint instead of restarting the 3256process, you can avoid the effects of address randomization and 3257your symbols will all stay in the same place. 3258 3259@node Stopping 3260@chapter Stopping and Continuing 3261 3262The principal purposes of using a debugger are so that you can stop your 3263program before it terminates; or so that, if your program runs into 3264trouble, you can investigate and find out why. 3265 3266Inside @value{GDBN}, your program may stop for any of several reasons, 3267such as a signal, a breakpoint, or reaching a new line after a 3268@value{GDBN} command such as @code{step}. You may then examine and 3269change variables, set new breakpoints or remove old ones, and then 3270continue execution. Usually, the messages shown by @value{GDBN} provide 3271ample explanation of the status of your program---but you can also 3272explicitly request this information at any time. 3273 3274@table @code 3275@kindex info program 3276@item info program 3277Display information about the status of your program: whether it is 3278running or not, what process it is, and why it stopped. 3279@end table 3280 3281@menu 3282* Breakpoints:: Breakpoints, watchpoints, and catchpoints 3283* Continuing and Stepping:: Resuming execution 3284* Skipping Over Functions and Files:: 3285 Skipping over functions and files 3286* Signals:: Signals 3287* Thread Stops:: Stopping and starting multi-thread programs 3288@end menu 3289 3290@node Breakpoints 3291@section Breakpoints, Watchpoints, and Catchpoints 3292 3293@cindex breakpoints 3294A @dfn{breakpoint} makes your program stop whenever a certain point in 3295the program is reached. For each breakpoint, you can add conditions to 3296control in finer detail whether your program stops. You can set 3297breakpoints with the @code{break} command and its variants (@pxref{Set 3298Breaks, ,Setting Breakpoints}), to specify the place where your program 3299should stop by line number, function name or exact address in the 3300program. 3301 3302On some systems, you can set breakpoints in shared libraries before 3303the executable is run. There is a minor limitation on HP-UX systems: 3304you must wait until the executable is run in order to set breakpoints 3305in shared library routines that are not called directly by the program 3306(for example, routines that are arguments in a @code{pthread_create} 3307call). 3308 3309@cindex watchpoints 3310@cindex data breakpoints 3311@cindex memory tracing 3312@cindex breakpoint on memory address 3313@cindex breakpoint on variable modification 3314A @dfn{watchpoint} is a special breakpoint that stops your program 3315when the value of an expression changes. The expression may be a value 3316of a variable, or it could involve values of one or more variables 3317combined by operators, such as @samp{a + b}. This is sometimes called 3318@dfn{data breakpoints}. You must use a different command to set 3319watchpoints (@pxref{Set Watchpoints, ,Setting Watchpoints}), but aside 3320from that, you can manage a watchpoint like any other breakpoint: you 3321enable, disable, and delete both breakpoints and watchpoints using the 3322same commands. 3323 3324You can arrange to have values from your program displayed automatically 3325whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,, 3326Automatic Display}. 3327 3328@cindex catchpoints 3329@cindex breakpoint on events 3330A @dfn{catchpoint} is another special breakpoint that stops your program 3331when a certain kind of event occurs, such as the throwing of a C@t{++} 3332exception or the loading of a library. As with watchpoints, you use a 3333different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting 3334Catchpoints}), but aside from that, you can manage a catchpoint like any 3335other breakpoint. (To stop when your program receives a signal, use the 3336@code{handle} command; see @ref{Signals, ,Signals}.) 3337 3338@cindex breakpoint numbers 3339@cindex numbers for breakpoints 3340@value{GDBN} assigns a number to each breakpoint, watchpoint, or 3341catchpoint when you create it; these numbers are successive integers 3342starting with one. In many of the commands for controlling various 3343features of breakpoints you use the breakpoint number to say which 3344breakpoint you want to change. Each breakpoint may be @dfn{enabled} or 3345@dfn{disabled}; if disabled, it has no effect on your program until you 3346enable it again. 3347 3348@cindex breakpoint ranges 3349@cindex ranges of breakpoints 3350Some @value{GDBN} commands accept a range of breakpoints on which to 3351operate. A breakpoint range is either a single breakpoint number, like 3352@samp{5}, or two such numbers, in increasing order, separated by a 3353hyphen, like @samp{5-7}. When a breakpoint range is given to a command, 3354all breakpoints in that range are operated on. 3355 3356@menu 3357* Set Breaks:: Setting breakpoints 3358* Set Watchpoints:: Setting watchpoints 3359* Set Catchpoints:: Setting catchpoints 3360* Delete Breaks:: Deleting breakpoints 3361* Disabling:: Disabling breakpoints 3362* Conditions:: Break conditions 3363* Break Commands:: Breakpoint command lists 3364* Dynamic Printf:: Dynamic printf 3365* Save Breakpoints:: How to save breakpoints in a file 3366* Static Probe Points:: Listing static probe points 3367* Error in Breakpoints:: ``Cannot insert breakpoints'' 3368* Breakpoint-related Warnings:: ``Breakpoint address adjusted...'' 3369@end menu 3370 3371@node Set Breaks 3372@subsection Setting Breakpoints 3373 3374@c FIXME LMB what does GDB do if no code on line of breakpt? 3375@c consider in particular declaration with/without initialization. 3376@c 3377@c FIXME 2 is there stuff on this already? break at fun start, already init? 3378 3379@kindex break 3380@kindex b @r{(@code{break})} 3381@vindex $bpnum@r{, convenience variable} 3382@cindex latest breakpoint 3383Breakpoints are set with the @code{break} command (abbreviated 3384@code{b}). The debugger convenience variable @samp{$bpnum} records the 3385number of the breakpoint you've set most recently; see @ref{Convenience 3386Vars,, Convenience Variables}, for a discussion of what you can do with 3387convenience variables. 3388 3389@table @code 3390@item break @var{location} 3391Set a breakpoint at the given @var{location}, which can specify a 3392function name, a line number, or an address of an instruction. 3393(@xref{Specify Location}, for a list of all the possible ways to 3394specify a @var{location}.) The breakpoint will stop your program just 3395before it executes any of the code in the specified @var{location}. 3396 3397When using source languages that permit overloading of symbols, such as 3398C@t{++}, a function name may refer to more than one possible place to break. 3399@xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of 3400that situation. 3401 3402It is also possible to insert a breakpoint that will stop the program 3403only if a specific thread (@pxref{Thread-Specific Breakpoints}) 3404or a specific task (@pxref{Ada Tasks}) hits that breakpoint. 3405 3406@item break 3407When called without any arguments, @code{break} sets a breakpoint at 3408the next instruction to be executed in the selected stack frame 3409(@pxref{Stack, ,Examining the Stack}). In any selected frame but the 3410innermost, this makes your program stop as soon as control 3411returns to that frame. This is similar to the effect of a 3412@code{finish} command in the frame inside the selected frame---except 3413that @code{finish} does not leave an active breakpoint. If you use 3414@code{break} without an argument in the innermost frame, @value{GDBN} stops 3415the next time it reaches the current location; this may be useful 3416inside loops. 3417 3418@value{GDBN} normally ignores breakpoints when it resumes execution, until at 3419least one instruction has been executed. If it did not do this, you 3420would be unable to proceed past a breakpoint without first disabling the 3421breakpoint. This rule applies whether or not the breakpoint already 3422existed when your program stopped. 3423 3424@item break @dots{} if @var{cond} 3425Set a breakpoint with condition @var{cond}; evaluate the expression 3426@var{cond} each time the breakpoint is reached, and stop only if the 3427value is nonzero---that is, if @var{cond} evaluates as true. 3428@samp{@dots{}} stands for one of the possible arguments described 3429above (or no argument) specifying where to break. @xref{Conditions, 3430,Break Conditions}, for more information on breakpoint conditions. 3431 3432@kindex tbreak 3433@item tbreak @var{args} 3434Set a breakpoint enabled only for one stop. @var{args} are the 3435same as for the @code{break} command, and the breakpoint is set in the same 3436way, but the breakpoint is automatically deleted after the first time your 3437program stops there. @xref{Disabling, ,Disabling Breakpoints}. 3438 3439@kindex hbreak 3440@cindex hardware breakpoints 3441@item hbreak @var{args} 3442Set a hardware-assisted breakpoint. @var{args} are the same as for the 3443@code{break} command and the breakpoint is set in the same way, but the 3444breakpoint requires hardware support and some target hardware may not 3445have this support. The main purpose of this is EPROM/ROM code 3446debugging, so you can set a breakpoint at an instruction without 3447changing the instruction. This can be used with the new trap-generation 3448provided by SPARClite DSU and most x86-based targets. These targets 3449will generate traps when a program accesses some data or instruction 3450address that is assigned to the debug registers. However the hardware 3451breakpoint registers can take a limited number of breakpoints. For 3452example, on the DSU, only two data breakpoints can be set at a time, and 3453@value{GDBN} will reject this command if more than two are used. Delete 3454or disable unused hardware breakpoints before setting new ones 3455(@pxref{Disabling, ,Disabling Breakpoints}). 3456@xref{Conditions, ,Break Conditions}. 3457For remote targets, you can restrict the number of hardware 3458breakpoints @value{GDBN} will use, see @ref{set remote 3459hardware-breakpoint-limit}. 3460 3461@kindex thbreak 3462@item thbreak @var{args} 3463Set a hardware-assisted breakpoint enabled only for one stop. @var{args} 3464are the same as for the @code{hbreak} command and the breakpoint is set in 3465the same way. However, like the @code{tbreak} command, 3466the breakpoint is automatically deleted after the 3467first time your program stops there. Also, like the @code{hbreak} 3468command, the breakpoint requires hardware support and some target hardware 3469may not have this support. @xref{Disabling, ,Disabling Breakpoints}. 3470See also @ref{Conditions, ,Break Conditions}. 3471 3472@kindex rbreak 3473@cindex regular expression 3474@cindex breakpoints at functions matching a regexp 3475@cindex set breakpoints in many functions 3476@item rbreak @var{regex} 3477Set breakpoints on all functions matching the regular expression 3478@var{regex}. This command sets an unconditional breakpoint on all 3479matches, printing a list of all breakpoints it set. Once these 3480breakpoints are set, they are treated just like the breakpoints set with 3481the @code{break} command. You can delete them, disable them, or make 3482them conditional the same way as any other breakpoint. 3483 3484The syntax of the regular expression is the standard one used with tools 3485like @file{grep}. Note that this is different from the syntax used by 3486shells, so for instance @code{foo*} matches all functions that include 3487an @code{fo} followed by zero or more @code{o}s. There is an implicit 3488@code{.*} leading and trailing the regular expression you supply, so to 3489match only functions that begin with @code{foo}, use @code{^foo}. 3490 3491@cindex non-member C@t{++} functions, set breakpoint in 3492When debugging C@t{++} programs, @code{rbreak} is useful for setting 3493breakpoints on overloaded functions that are not members of any special 3494classes. 3495 3496@cindex set breakpoints on all functions 3497The @code{rbreak} command can be used to set breakpoints in 3498@strong{all} the functions in a program, like this: 3499 3500@smallexample 3501(@value{GDBP}) rbreak . 3502@end smallexample 3503 3504@item rbreak @var{file}:@var{regex} 3505If @code{rbreak} is called with a filename qualification, it limits 3506the search for functions matching the given regular expression to the 3507specified @var{file}. This can be used, for example, to set breakpoints on 3508every function in a given file: 3509 3510@smallexample 3511(@value{GDBP}) rbreak file.c:. 3512@end smallexample 3513 3514The colon separating the filename qualifier from the regex may 3515optionally be surrounded by spaces. 3516 3517@kindex info breakpoints 3518@cindex @code{$_} and @code{info breakpoints} 3519@item info breakpoints @r{[}@var{n}@dots{}@r{]} 3520@itemx info break @r{[}@var{n}@dots{}@r{]} 3521Print a table of all breakpoints, watchpoints, and catchpoints set and 3522not deleted. Optional argument @var{n} means print information only 3523about the specified breakpoint(s) (or watchpoint(s) or catchpoint(s)). 3524For each breakpoint, following columns are printed: 3525 3526@table @emph 3527@item Breakpoint Numbers 3528@item Type 3529Breakpoint, watchpoint, or catchpoint. 3530@item Disposition 3531Whether the breakpoint is marked to be disabled or deleted when hit. 3532@item Enabled or Disabled 3533Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints 3534that are not enabled. 3535@item Address 3536Where the breakpoint is in your program, as a memory address. For a 3537pending breakpoint whose address is not yet known, this field will 3538contain @samp{<PENDING>}. Such breakpoint won't fire until a shared 3539library that has the symbol or line referred by breakpoint is loaded. 3540See below for details. A breakpoint with several locations will 3541have @samp{<MULTIPLE>} in this field---see below for details. 3542@item What 3543Where the breakpoint is in the source for your program, as a file and 3544line number. For a pending breakpoint, the original string passed to 3545the breakpoint command will be listed as it cannot be resolved until 3546the appropriate shared library is loaded in the future. 3547@end table 3548 3549@noindent 3550If a breakpoint is conditional, there are two evaluation modes: ``host'' and 3551``target''. If mode is ``host'', breakpoint condition evaluation is done by 3552@value{GDBN} on the host's side. If it is ``target'', then the condition 3553is evaluated by the target. The @code{info break} command shows 3554the condition on the line following the affected breakpoint, together with 3555its condition evaluation mode in between parentheses. 3556 3557Breakpoint commands, if any, are listed after that. A pending breakpoint is 3558allowed to have a condition specified for it. The condition is not parsed for 3559validity until a shared library is loaded that allows the pending 3560breakpoint to resolve to a valid location. 3561 3562@noindent 3563@code{info break} with a breakpoint 3564number @var{n} as argument lists only that breakpoint. The 3565convenience variable @code{$_} and the default examining-address for 3566the @code{x} command are set to the address of the last breakpoint 3567listed (@pxref{Memory, ,Examining Memory}). 3568 3569@noindent 3570@code{info break} displays a count of the number of times the breakpoint 3571has been hit. This is especially useful in conjunction with the 3572@code{ignore} command. You can ignore a large number of breakpoint 3573hits, look at the breakpoint info to see how many times the breakpoint 3574was hit, and then run again, ignoring one less than that number. This 3575will get you quickly to the last hit of that breakpoint. 3576 3577@noindent 3578For a breakpoints with an enable count (xref) greater than 1, 3579@code{info break} also displays that count. 3580 3581@end table 3582 3583@value{GDBN} allows you to set any number of breakpoints at the same place in 3584your program. There is nothing silly or meaningless about this. When 3585the breakpoints are conditional, this is even useful 3586(@pxref{Conditions, ,Break Conditions}). 3587 3588@cindex multiple locations, breakpoints 3589@cindex breakpoints, multiple locations 3590It is possible that a breakpoint corresponds to several locations 3591in your program. Examples of this situation are: 3592 3593@itemize @bullet 3594@item 3595Multiple functions in the program may have the same name. 3596 3597@item 3598For a C@t{++} constructor, the @value{NGCC} compiler generates several 3599instances of the function body, used in different cases. 3600 3601@item 3602For a C@t{++} template function, a given line in the function can 3603correspond to any number of instantiations. 3604 3605@item 3606For an inlined function, a given source line can correspond to 3607several places where that function is inlined. 3608@end itemize 3609 3610In all those cases, @value{GDBN} will insert a breakpoint at all 3611the relevant locations. 3612 3613A breakpoint with multiple locations is displayed in the breakpoint 3614table using several rows---one header row, followed by one row for 3615each breakpoint location. The header row has @samp{<MULTIPLE>} in the 3616address column. The rows for individual locations contain the actual 3617addresses for locations, and show the functions to which those 3618locations belong. The number column for a location is of the form 3619@var{breakpoint-number}.@var{location-number}. 3620 3621For example: 3622 3623@smallexample 3624Num Type Disp Enb Address What 36251 breakpoint keep y <MULTIPLE> 3626 stop only if i==1 3627 breakpoint already hit 1 time 36281.1 y 0x080486a2 in void foo<int>() at t.cc:8 36291.2 y 0x080486ca in void foo<double>() at t.cc:8 3630@end smallexample 3631 3632Each location can be individually enabled or disabled by passing 3633@var{breakpoint-number}.@var{location-number} as argument to the 3634@code{enable} and @code{disable} commands. Note that you cannot 3635delete the individual locations from the list, you can only delete the 3636entire list of locations that belong to their parent breakpoint (with 3637the @kbd{delete @var{num}} command, where @var{num} is the number of 3638the parent breakpoint, 1 in the above example). Disabling or enabling 3639the parent breakpoint (@pxref{Disabling}) affects all of the locations 3640that belong to that breakpoint. 3641 3642@cindex pending breakpoints 3643It's quite common to have a breakpoint inside a shared library. 3644Shared libraries can be loaded and unloaded explicitly, 3645and possibly repeatedly, as the program is executed. To support 3646this use case, @value{GDBN} updates breakpoint locations whenever 3647any shared library is loaded or unloaded. Typically, you would 3648set a breakpoint in a shared library at the beginning of your 3649debugging session, when the library is not loaded, and when the 3650symbols from the library are not available. When you try to set 3651breakpoint, @value{GDBN} will ask you if you want to set 3652a so called @dfn{pending breakpoint}---breakpoint whose address 3653is not yet resolved. 3654 3655After the program is run, whenever a new shared library is loaded, 3656@value{GDBN} reevaluates all the breakpoints. When a newly loaded 3657shared library contains the symbol or line referred to by some 3658pending breakpoint, that breakpoint is resolved and becomes an 3659ordinary breakpoint. When a library is unloaded, all breakpoints 3660that refer to its symbols or source lines become pending again. 3661 3662This logic works for breakpoints with multiple locations, too. For 3663example, if you have a breakpoint in a C@t{++} template function, and 3664a newly loaded shared library has an instantiation of that template, 3665a new location is added to the list of locations for the breakpoint. 3666 3667Except for having unresolved address, pending breakpoints do not 3668differ from regular breakpoints. You can set conditions or commands, 3669enable and disable them and perform other breakpoint operations. 3670 3671@value{GDBN} provides some additional commands for controlling what 3672happens when the @samp{break} command cannot resolve breakpoint 3673address specification to an address: 3674 3675@kindex set breakpoint pending 3676@kindex show breakpoint pending 3677@table @code 3678@item set breakpoint pending auto 3679This is the default behavior. When @value{GDBN} cannot find the breakpoint 3680location, it queries you whether a pending breakpoint should be created. 3681 3682@item set breakpoint pending on 3683This indicates that an unrecognized breakpoint location should automatically 3684result in a pending breakpoint being created. 3685 3686@item set breakpoint pending off 3687This indicates that pending breakpoints are not to be created. Any 3688unrecognized breakpoint location results in an error. This setting does 3689not affect any pending breakpoints previously created. 3690 3691@item show breakpoint pending 3692Show the current behavior setting for creating pending breakpoints. 3693@end table 3694 3695The settings above only affect the @code{break} command and its 3696variants. Once breakpoint is set, it will be automatically updated 3697as shared libraries are loaded and unloaded. 3698 3699@cindex automatic hardware breakpoints 3700For some targets, @value{GDBN} can automatically decide if hardware or 3701software breakpoints should be used, depending on whether the 3702breakpoint address is read-only or read-write. This applies to 3703breakpoints set with the @code{break} command as well as to internal 3704breakpoints set by commands like @code{next} and @code{finish}. For 3705breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware 3706breakpoints. 3707 3708You can control this automatic behaviour with the following commands:: 3709 3710@kindex set breakpoint auto-hw 3711@kindex show breakpoint auto-hw 3712@table @code 3713@item set breakpoint auto-hw on 3714This is the default behavior. When @value{GDBN} sets a breakpoint, it 3715will try to use the target memory map to decide if software or hardware 3716breakpoint must be used. 3717 3718@item set breakpoint auto-hw off 3719This indicates @value{GDBN} should not automatically select breakpoint 3720type. If the target provides a memory map, @value{GDBN} will warn when 3721trying to set software breakpoint at a read-only address. 3722@end table 3723 3724@value{GDBN} normally implements breakpoints by replacing the program code 3725at the breakpoint address with a special instruction, which, when 3726executed, given control to the debugger. By default, the program 3727code is so modified only when the program is resumed. As soon as 3728the program stops, @value{GDBN} restores the original instructions. This 3729behaviour guards against leaving breakpoints inserted in the 3730target should gdb abrubptly disconnect. However, with slow remote 3731targets, inserting and removing breakpoint can reduce the performance. 3732This behavior can be controlled with the following commands:: 3733 3734@kindex set breakpoint always-inserted 3735@kindex show breakpoint always-inserted 3736@table @code 3737@item set breakpoint always-inserted off 3738All breakpoints, including newly added by the user, are inserted in 3739the target only when the target is resumed. All breakpoints are 3740removed from the target when it stops. 3741 3742@item set breakpoint always-inserted on 3743Causes all breakpoints to be inserted in the target at all times. If 3744the user adds a new breakpoint, or changes an existing breakpoint, the 3745breakpoints in the target are updated immediately. A breakpoint is 3746removed from the target only when breakpoint itself is removed. 3747 3748@cindex non-stop mode, and @code{breakpoint always-inserted} 3749@item set breakpoint always-inserted auto 3750This is the default mode. If @value{GDBN} is controlling the inferior 3751in non-stop mode (@pxref{Non-Stop Mode}), gdb behaves as if 3752@code{breakpoint always-inserted} mode is on. If @value{GDBN} is 3753controlling the inferior in all-stop mode, @value{GDBN} behaves as if 3754@code{breakpoint always-inserted} mode is off. 3755@end table 3756 3757@value{GDBN} handles conditional breakpoints by evaluating these conditions 3758when a breakpoint breaks. If the condition is true, then the process being 3759debugged stops, otherwise the process is resumed. 3760 3761If the target supports evaluating conditions on its end, @value{GDBN} may 3762download the breakpoint, together with its conditions, to it. 3763 3764This feature can be controlled via the following commands: 3765 3766@kindex set breakpoint condition-evaluation 3767@kindex show breakpoint condition-evaluation 3768@table @code 3769@item set breakpoint condition-evaluation host 3770This option commands @value{GDBN} to evaluate the breakpoint 3771conditions on the host's side. Unconditional breakpoints are sent to 3772the target which in turn receives the triggers and reports them back to GDB 3773for condition evaluation. This is the standard evaluation mode. 3774 3775@item set breakpoint condition-evaluation target 3776This option commands @value{GDBN} to download breakpoint conditions 3777to the target at the moment of their insertion. The target 3778is responsible for evaluating the conditional expression and reporting 3779breakpoint stop events back to @value{GDBN} whenever the condition 3780is true. Due to limitations of target-side evaluation, some conditions 3781cannot be evaluated there, e.g., conditions that depend on local data 3782that is only known to the host. Examples include 3783conditional expressions involving convenience variables, complex types 3784that cannot be handled by the agent expression parser and expressions 3785that are too long to be sent over to the target, specially when the 3786target is a remote system. In these cases, the conditions will be 3787evaluated by @value{GDBN}. 3788 3789@item set breakpoint condition-evaluation auto 3790This is the default mode. If the target supports evaluating breakpoint 3791conditions on its end, @value{GDBN} will download breakpoint conditions to 3792the target (limitations mentioned previously apply). If the target does 3793not support breakpoint condition evaluation, then @value{GDBN} will fallback 3794to evaluating all these conditions on the host's side. 3795@end table 3796 3797 3798@cindex negative breakpoint numbers 3799@cindex internal @value{GDBN} breakpoints 3800@value{GDBN} itself sometimes sets breakpoints in your program for 3801special purposes, such as proper handling of @code{longjmp} (in C 3802programs). These internal breakpoints are assigned negative numbers, 3803starting with @code{-1}; @samp{info breakpoints} does not display them. 3804You can see these breakpoints with the @value{GDBN} maintenance command 3805@samp{maint info breakpoints} (@pxref{maint info breakpoints}). 3806 3807 3808@node Set Watchpoints 3809@subsection Setting Watchpoints 3810 3811@cindex setting watchpoints 3812You can use a watchpoint to stop execution whenever the value of an 3813expression changes, without having to predict a particular place where 3814this may happen. (This is sometimes called a @dfn{data breakpoint}.) 3815The expression may be as simple as the value of a single variable, or 3816as complex as many variables combined by operators. Examples include: 3817 3818@itemize @bullet 3819@item 3820A reference to the value of a single variable. 3821 3822@item 3823An address cast to an appropriate data type. For example, 3824@samp{*(int *)0x12345678} will watch a 4-byte region at the specified 3825address (assuming an @code{int} occupies 4 bytes). 3826 3827@item 3828An arbitrarily complex expression, such as @samp{a*b + c/d}. The 3829expression can use any operators valid in the program's native 3830language (@pxref{Languages}). 3831@end itemize 3832 3833You can set a watchpoint on an expression even if the expression can 3834not be evaluated yet. For instance, you can set a watchpoint on 3835@samp{*global_ptr} before @samp{global_ptr} is initialized. 3836@value{GDBN} will stop when your program sets @samp{global_ptr} and 3837the expression produces a valid value. If the expression becomes 3838valid in some other way than changing a variable (e.g.@: if the memory 3839pointed to by @samp{*global_ptr} becomes readable as the result of a 3840@code{malloc} call), @value{GDBN} may not stop until the next time 3841the expression changes. 3842 3843@cindex software watchpoints 3844@cindex hardware watchpoints 3845Depending on your system, watchpoints may be implemented in software or 3846hardware. @value{GDBN} does software watchpointing by single-stepping your 3847program and testing the variable's value each time, which is hundreds of 3848times slower than normal execution. (But this may still be worth it, to 3849catch errors where you have no clue what part of your program is the 3850culprit.) 3851 3852On some systems, such as HP-UX, PowerPC, @sc{gnu}/Linux and most other 3853x86-based targets, @value{GDBN} includes support for hardware 3854watchpoints, which do not slow down the running of your program. 3855 3856@table @code 3857@kindex watch 3858@item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]} 3859Set a watchpoint for an expression. @value{GDBN} will break when the 3860expression @var{expr} is written into by the program and its value 3861changes. The simplest (and the most popular) use of this command is 3862to watch the value of a single variable: 3863 3864@smallexample 3865(@value{GDBP}) watch foo 3866@end smallexample 3867 3868If the command includes a @code{@r{[}thread @var{threadnum}@r{]}} 3869argument, @value{GDBN} breaks only when the thread identified by 3870@var{threadnum} changes the value of @var{expr}. If any other threads 3871change the value of @var{expr}, @value{GDBN} will not break. Note 3872that watchpoints restricted to a single thread in this way only work 3873with Hardware Watchpoints. 3874 3875Ordinarily a watchpoint respects the scope of variables in @var{expr} 3876(see below). The @code{-location} argument tells @value{GDBN} to 3877instead watch the memory referred to by @var{expr}. In this case, 3878@value{GDBN} will evaluate @var{expr}, take the address of the result, 3879and watch the memory at that address. The type of the result is used 3880to determine the size of the watched memory. If the expression's 3881result does not have an address, then @value{GDBN} will print an 3882error. 3883 3884The @code{@r{[}mask @var{maskvalue}@r{]}} argument allows creation 3885of masked watchpoints, if the current architecture supports this 3886feature (e.g., PowerPC Embedded architecture, see @ref{PowerPC 3887Embedded}.) A @dfn{masked watchpoint} specifies a mask in addition 3888to an address to watch. The mask specifies that some bits of an address 3889(the bits which are reset in the mask) should be ignored when matching 3890the address accessed by the inferior against the watchpoint address. 3891Thus, a masked watchpoint watches many addresses simultaneously---those 3892addresses whose unmasked bits are identical to the unmasked bits in the 3893watchpoint address. The @code{mask} argument implies @code{-location}. 3894Examples: 3895 3896@smallexample 3897(@value{GDBP}) watch foo mask 0xffff00ff 3898(@value{GDBP}) watch *0xdeadbeef mask 0xffffff00 3899@end smallexample 3900 3901@kindex rwatch 3902@item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]} 3903Set a watchpoint that will break when the value of @var{expr} is read 3904by the program. 3905 3906@kindex awatch 3907@item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]} 3908Set a watchpoint that will break when @var{expr} is either read from 3909or written into by the program. 3910 3911@kindex info watchpoints @r{[}@var{n}@dots{}@r{]} 3912@item info watchpoints @r{[}@var{n}@dots{}@r{]} 3913This command prints a list of watchpoints, using the same format as 3914@code{info break} (@pxref{Set Breaks}). 3915@end table 3916 3917If you watch for a change in a numerically entered address you need to 3918dereference it, as the address itself is just a constant number which will 3919never change. @value{GDBN} refuses to create a watchpoint that watches 3920a never-changing value: 3921 3922@smallexample 3923(@value{GDBP}) watch 0x600850 3924Cannot watch constant value 0x600850. 3925(@value{GDBP}) watch *(int *) 0x600850 3926Watchpoint 1: *(int *) 6293584 3927@end smallexample 3928 3929@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware 3930watchpoints execute very quickly, and the debugger reports a change in 3931value at the exact instruction where the change occurs. If @value{GDBN} 3932cannot set a hardware watchpoint, it sets a software watchpoint, which 3933executes more slowly and reports the change in value at the next 3934@emph{statement}, not the instruction, after the change occurs. 3935 3936@cindex use only software watchpoints 3937You can force @value{GDBN} to use only software watchpoints with the 3938@kbd{set can-use-hw-watchpoints 0} command. With this variable set to 3939zero, @value{GDBN} will never try to use hardware watchpoints, even if 3940the underlying system supports them. (Note that hardware-assisted 3941watchpoints that were set @emph{before} setting 3942@code{can-use-hw-watchpoints} to zero will still use the hardware 3943mechanism of watching expression values.) 3944 3945@table @code 3946@item set can-use-hw-watchpoints 3947@kindex set can-use-hw-watchpoints 3948Set whether or not to use hardware watchpoints. 3949 3950@item show can-use-hw-watchpoints 3951@kindex show can-use-hw-watchpoints 3952Show the current mode of using hardware watchpoints. 3953@end table 3954 3955For remote targets, you can restrict the number of hardware 3956watchpoints @value{GDBN} will use, see @ref{set remote 3957hardware-breakpoint-limit}. 3958 3959When you issue the @code{watch} command, @value{GDBN} reports 3960 3961@smallexample 3962Hardware watchpoint @var{num}: @var{expr} 3963@end smallexample 3964 3965@noindent 3966if it was able to set a hardware watchpoint. 3967 3968Currently, the @code{awatch} and @code{rwatch} commands can only set 3969hardware watchpoints, because accesses to data that don't change the 3970value of the watched expression cannot be detected without examining 3971every instruction as it is being executed, and @value{GDBN} does not do 3972that currently. If @value{GDBN} finds that it is unable to set a 3973hardware breakpoint with the @code{awatch} or @code{rwatch} command, it 3974will print a message like this: 3975 3976@smallexample 3977Expression cannot be implemented with read/access watchpoint. 3978@end smallexample 3979 3980Sometimes, @value{GDBN} cannot set a hardware watchpoint because the 3981data type of the watched expression is wider than what a hardware 3982watchpoint on the target machine can handle. For example, some systems 3983can only watch regions that are up to 4 bytes wide; on such systems you 3984cannot set hardware watchpoints for an expression that yields a 3985double-precision floating-point number (which is typically 8 bytes 3986wide). As a work-around, it might be possible to break the large region 3987into a series of smaller ones and watch them with separate watchpoints. 3988 3989If you set too many hardware watchpoints, @value{GDBN} might be unable 3990to insert all of them when you resume the execution of your program. 3991Since the precise number of active watchpoints is unknown until such 3992time as the program is about to be resumed, @value{GDBN} might not be 3993able to warn you about this when you set the watchpoints, and the 3994warning will be printed only when the program is resumed: 3995 3996@smallexample 3997Hardware watchpoint @var{num}: Could not insert watchpoint 3998@end smallexample 3999 4000@noindent 4001If this happens, delete or disable some of the watchpoints. 4002 4003Watching complex expressions that reference many variables can also 4004exhaust the resources available for hardware-assisted watchpoints. 4005That's because @value{GDBN} needs to watch every variable in the 4006expression with separately allocated resources. 4007 4008If you call a function interactively using @code{print} or @code{call}, 4009any watchpoints you have set will be inactive until @value{GDBN} reaches another 4010kind of breakpoint or the call completes. 4011 4012@value{GDBN} automatically deletes watchpoints that watch local 4013(automatic) variables, or expressions that involve such variables, when 4014they go out of scope, that is, when the execution leaves the block in 4015which these variables were defined. In particular, when the program 4016being debugged terminates, @emph{all} local variables go out of scope, 4017and so only watchpoints that watch global variables remain set. If you 4018rerun the program, you will need to set all such watchpoints again. One 4019way of doing that would be to set a code breakpoint at the entry to the 4020@code{main} function and when it breaks, set all the watchpoints. 4021 4022@cindex watchpoints and threads 4023@cindex threads and watchpoints 4024In multi-threaded programs, watchpoints will detect changes to the 4025watched expression from every thread. 4026 4027@quotation 4028@emph{Warning:} In multi-threaded programs, software watchpoints 4029have only limited usefulness. If @value{GDBN} creates a software 4030watchpoint, it can only watch the value of an expression @emph{in a 4031single thread}. If you are confident that the expression can only 4032change due to the current thread's activity (and if you are also 4033confident that no other thread can become current), then you can use 4034software watchpoints as usual. However, @value{GDBN} may not notice 4035when a non-current thread's activity changes the expression. (Hardware 4036watchpoints, in contrast, watch an expression in all threads.) 4037@end quotation 4038 4039@xref{set remote hardware-watchpoint-limit}. 4040 4041@node Set Catchpoints 4042@subsection Setting Catchpoints 4043@cindex catchpoints, setting 4044@cindex exception handlers 4045@cindex event handling 4046 4047You can use @dfn{catchpoints} to cause the debugger to stop for certain 4048kinds of program events, such as C@t{++} exceptions or the loading of a 4049shared library. Use the @code{catch} command to set a catchpoint. 4050 4051@table @code 4052@kindex catch 4053@item catch @var{event} 4054Stop when @var{event} occurs. @var{event} can be any of the following: 4055@table @code 4056@item throw 4057@cindex stop on C@t{++} exceptions 4058The throwing of a C@t{++} exception. 4059 4060@item catch 4061The catching of a C@t{++} exception. 4062 4063@item exception 4064@cindex Ada exception catching 4065@cindex catch Ada exceptions 4066An Ada exception being raised. If an exception name is specified 4067at the end of the command (eg @code{catch exception Program_Error}), 4068the debugger will stop only when this specific exception is raised. 4069Otherwise, the debugger stops execution when any Ada exception is raised. 4070 4071When inserting an exception catchpoint on a user-defined exception whose 4072name is identical to one of the exceptions defined by the language, the 4073fully qualified name must be used as the exception name. Otherwise, 4074@value{GDBN} will assume that it should stop on the pre-defined exception 4075rather than the user-defined one. For instance, assuming an exception 4076called @code{Constraint_Error} is defined in package @code{Pck}, then 4077the command to use to catch such exceptions is @kbd{catch exception 4078Pck.Constraint_Error}. 4079 4080@item exception unhandled 4081An exception that was raised but is not handled by the program. 4082 4083@item assert 4084A failed Ada assertion. 4085 4086@item exec 4087@cindex break on fork/exec 4088A call to @code{exec}. This is currently only available for HP-UX 4089and @sc{gnu}/Linux. 4090 4091@item syscall 4092@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{} 4093@cindex break on a system call. 4094A call to or return from a system call, a.k.a.@: @dfn{syscall}. A 4095syscall is a mechanism for application programs to request a service 4096from the operating system (OS) or one of the OS system services. 4097@value{GDBN} can catch some or all of the syscalls issued by the 4098debuggee, and show the related information for each syscall. If no 4099argument is specified, calls to and returns from all system calls 4100will be caught. 4101 4102@var{name} can be any system call name that is valid for the 4103underlying OS. Just what syscalls are valid depends on the OS. On 4104GNU and Unix systems, you can find the full list of valid syscall 4105names on @file{/usr/include/asm/unistd.h}. 4106 4107@c For MS-Windows, the syscall names and the corresponding numbers 4108@c can be found, e.g., on this URL: 4109@c http://www.metasploit.com/users/opcode/syscalls.html 4110@c but we don't support Windows syscalls yet. 4111 4112Normally, @value{GDBN} knows in advance which syscalls are valid for 4113each OS, so you can use the @value{GDBN} command-line completion 4114facilities (@pxref{Completion,, command completion}) to list the 4115available choices. 4116 4117You may also specify the system call numerically. A syscall's 4118number is the value passed to the OS's syscall dispatcher to 4119identify the requested service. When you specify the syscall by its 4120name, @value{GDBN} uses its database of syscalls to convert the name 4121into the corresponding numeric code, but using the number directly 4122may be useful if @value{GDBN}'s database does not have the complete 4123list of syscalls on your system (e.g., because @value{GDBN} lags 4124behind the OS upgrades). 4125 4126The example below illustrates how this command works if you don't provide 4127arguments to it: 4128 4129@smallexample 4130(@value{GDBP}) catch syscall 4131Catchpoint 1 (syscall) 4132(@value{GDBP}) r 4133Starting program: /tmp/catch-syscall 4134 4135Catchpoint 1 (call to syscall 'close'), \ 4136 0xffffe424 in __kernel_vsyscall () 4137(@value{GDBP}) c 4138Continuing. 4139 4140Catchpoint 1 (returned from syscall 'close'), \ 4141 0xffffe424 in __kernel_vsyscall () 4142(@value{GDBP}) 4143@end smallexample 4144 4145Here is an example of catching a system call by name: 4146 4147@smallexample 4148(@value{GDBP}) catch syscall chroot 4149Catchpoint 1 (syscall 'chroot' [61]) 4150(@value{GDBP}) r 4151Starting program: /tmp/catch-syscall 4152 4153Catchpoint 1 (call to syscall 'chroot'), \ 4154 0xffffe424 in __kernel_vsyscall () 4155(@value{GDBP}) c 4156Continuing. 4157 4158Catchpoint 1 (returned from syscall 'chroot'), \ 4159 0xffffe424 in __kernel_vsyscall () 4160(@value{GDBP}) 4161@end smallexample 4162 4163An example of specifying a system call numerically. In the case 4164below, the syscall number has a corresponding entry in the XML 4165file, so @value{GDBN} finds its name and prints it: 4166 4167@smallexample 4168(@value{GDBP}) catch syscall 252 4169Catchpoint 1 (syscall(s) 'exit_group') 4170(@value{GDBP}) r 4171Starting program: /tmp/catch-syscall 4172 4173Catchpoint 1 (call to syscall 'exit_group'), \ 4174 0xffffe424 in __kernel_vsyscall () 4175(@value{GDBP}) c 4176Continuing. 4177 4178Program exited normally. 4179(@value{GDBP}) 4180@end smallexample 4181 4182However, there can be situations when there is no corresponding name 4183in XML file for that syscall number. In this case, @value{GDBN} prints 4184a warning message saying that it was not able to find the syscall name, 4185but the catchpoint will be set anyway. See the example below: 4186 4187@smallexample 4188(@value{GDBP}) catch syscall 764 4189warning: The number '764' does not represent a known syscall. 4190Catchpoint 2 (syscall 764) 4191(@value{GDBP}) 4192@end smallexample 4193 4194If you configure @value{GDBN} using the @samp{--without-expat} option, 4195it will not be able to display syscall names. Also, if your 4196architecture does not have an XML file describing its system calls, 4197you will not be able to see the syscall names. It is important to 4198notice that these two features are used for accessing the syscall 4199name database. In either case, you will see a warning like this: 4200 4201@smallexample 4202(@value{GDBP}) catch syscall 4203warning: Could not open "syscalls/i386-linux.xml" 4204warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'. 4205GDB will not be able to display syscall names. 4206Catchpoint 1 (syscall) 4207(@value{GDBP}) 4208@end smallexample 4209 4210Of course, the file name will change depending on your architecture and system. 4211 4212Still using the example above, you can also try to catch a syscall by its 4213number. In this case, you would see something like: 4214 4215@smallexample 4216(@value{GDBP}) catch syscall 252 4217Catchpoint 1 (syscall(s) 252) 4218@end smallexample 4219 4220Again, in this case @value{GDBN} would not be able to display syscall's names. 4221 4222@item fork 4223A call to @code{fork}. This is currently only available for HP-UX 4224and @sc{gnu}/Linux. 4225 4226@item vfork 4227A call to @code{vfork}. This is currently only available for HP-UX 4228and @sc{gnu}/Linux. 4229 4230@item load @r{[}regexp@r{]} 4231@itemx unload @r{[}regexp@r{]} 4232The loading or unloading of a shared library. If @var{regexp} is 4233given, then the catchpoint will stop only if the regular expression 4234matches one of the affected libraries. 4235 4236@item signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]} 4237The delivery of a signal. 4238 4239With no arguments, this catchpoint will catch any signal that is not 4240used internally by @value{GDBN}, specifically, all signals except 4241@samp{SIGTRAP} and @samp{SIGINT}. 4242 4243With the argument @samp{all}, all signals, including those used by 4244@value{GDBN}, will be caught. This argument cannot be used with other 4245signal names. 4246 4247Otherwise, the arguments are a list of signal names as given to 4248@code{handle} (@pxref{Signals}). Only signals specified in this list 4249will be caught. 4250 4251One reason that @code{catch signal} can be more useful than 4252@code{handle} is that you can attach commands and conditions to the 4253catchpoint. 4254 4255When a signal is caught by a catchpoint, the signal's @code{stop} and 4256@code{print} settings, as specified by @code{handle}, are ignored. 4257However, whether the signal is still delivered to the inferior depends 4258on the @code{pass} setting; this can be changed in the catchpoint's 4259commands. 4260 4261@end table 4262 4263@item tcatch @var{event} 4264Set a catchpoint that is enabled only for one stop. The catchpoint is 4265automatically deleted after the first time the event is caught. 4266 4267@end table 4268 4269Use the @code{info break} command to list the current catchpoints. 4270 4271There are currently some limitations to C@t{++} exception handling 4272(@code{catch throw} and @code{catch catch}) in @value{GDBN}: 4273 4274@itemize @bullet 4275@item 4276If you call a function interactively, @value{GDBN} normally returns 4277control to you when the function has finished executing. If the call 4278raises an exception, however, the call may bypass the mechanism that 4279returns control to you and cause your program either to abort or to 4280simply continue running until it hits a breakpoint, catches a signal 4281that @value{GDBN} is listening for, or exits. This is the case even if 4282you set a catchpoint for the exception; catchpoints on exceptions are 4283disabled within interactive calls. 4284 4285@item 4286You cannot raise an exception interactively. 4287 4288@item 4289You cannot install an exception handler interactively. 4290@end itemize 4291 4292@cindex raise exceptions 4293Sometimes @code{catch} is not the best way to debug exception handling: 4294if you need to know exactly where an exception is raised, it is better to 4295stop @emph{before} the exception handler is called, since that way you 4296can see the stack before any unwinding takes place. If you set a 4297breakpoint in an exception handler instead, it may not be easy to find 4298out where the exception was raised. 4299 4300To stop just before an exception handler is called, you need some 4301knowledge of the implementation. In the case of @sc{gnu} C@t{++}, exceptions are 4302raised by calling a library function named @code{__raise_exception} 4303which has the following ANSI C interface: 4304 4305@smallexample 4306 /* @var{addr} is where the exception identifier is stored. 4307 @var{id} is the exception identifier. */ 4308 void __raise_exception (void **addr, void *id); 4309@end smallexample 4310 4311@noindent 4312To make the debugger catch all exceptions before any stack 4313unwinding takes place, set a breakpoint on @code{__raise_exception} 4314(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Exceptions}). 4315 4316With a conditional breakpoint (@pxref{Conditions, ,Break Conditions}) 4317that depends on the value of @var{id}, you can stop your program when 4318a specific exception is raised. You can use multiple conditional 4319breakpoints to stop your program when any of a number of exceptions are 4320raised. 4321 4322 4323@node Delete Breaks 4324@subsection Deleting Breakpoints 4325 4326@cindex clearing breakpoints, watchpoints, catchpoints 4327@cindex deleting breakpoints, watchpoints, catchpoints 4328It is often necessary to eliminate a breakpoint, watchpoint, or 4329catchpoint once it has done its job and you no longer want your program 4330to stop there. This is called @dfn{deleting} the breakpoint. A 4331breakpoint that has been deleted no longer exists; it is forgotten. 4332 4333With the @code{clear} command you can delete breakpoints according to 4334where they are in your program. With the @code{delete} command you can 4335delete individual breakpoints, watchpoints, or catchpoints by specifying 4336their breakpoint numbers. 4337 4338It is not necessary to delete a breakpoint to proceed past it. @value{GDBN} 4339automatically ignores breakpoints on the first instruction to be executed 4340when you continue execution without changing the execution address. 4341 4342@table @code 4343@kindex clear 4344@item clear 4345Delete any breakpoints at the next instruction to be executed in the 4346selected stack frame (@pxref{Selection, ,Selecting a Frame}). When 4347the innermost frame is selected, this is a good way to delete a 4348breakpoint where your program just stopped. 4349 4350@item clear @var{location} 4351Delete any breakpoints set at the specified @var{location}. 4352@xref{Specify Location}, for the various forms of @var{location}; the 4353most useful ones are listed below: 4354 4355@table @code 4356@item clear @var{function} 4357@itemx clear @var{filename}:@var{function} 4358Delete any breakpoints set at entry to the named @var{function}. 4359 4360@item clear @var{linenum} 4361@itemx clear @var{filename}:@var{linenum} 4362Delete any breakpoints set at or within the code of the specified 4363@var{linenum} of the specified @var{filename}. 4364@end table 4365 4366@cindex delete breakpoints 4367@kindex delete 4368@kindex d @r{(@code{delete})} 4369@item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} 4370Delete the breakpoints, watchpoints, or catchpoints of the breakpoint 4371ranges specified as arguments. If no argument is specified, delete all 4372breakpoints (@value{GDBN} asks confirmation, unless you have @code{set 4373confirm off}). You can abbreviate this command as @code{d}. 4374@end table 4375 4376@node Disabling 4377@subsection Disabling Breakpoints 4378 4379@cindex enable/disable a breakpoint 4380Rather than deleting a breakpoint, watchpoint, or catchpoint, you might 4381prefer to @dfn{disable} it. This makes the breakpoint inoperative as if 4382it had been deleted, but remembers the information on the breakpoint so 4383that you can @dfn{enable} it again later. 4384 4385You disable and enable breakpoints, watchpoints, and catchpoints with 4386the @code{enable} and @code{disable} commands, optionally specifying 4387one or more breakpoint numbers as arguments. Use @code{info break} to 4388print a list of all breakpoints, watchpoints, and catchpoints if you 4389do not know which numbers to use. 4390 4391Disabling and enabling a breakpoint that has multiple locations 4392affects all of its locations. 4393 4394A breakpoint, watchpoint, or catchpoint can have any of several 4395different states of enablement: 4396 4397@itemize @bullet 4398@item 4399Enabled. The breakpoint stops your program. A breakpoint set 4400with the @code{break} command starts out in this state. 4401@item 4402Disabled. The breakpoint has no effect on your program. 4403@item 4404Enabled once. The breakpoint stops your program, but then becomes 4405disabled. 4406@item 4407Enabled for a count. The breakpoint stops your program for the next 4408N times, then becomes disabled. 4409@item 4410Enabled for deletion. The breakpoint stops your program, but 4411immediately after it does so it is deleted permanently. A breakpoint 4412set with the @code{tbreak} command starts out in this state. 4413@end itemize 4414 4415You can use the following commands to enable or disable breakpoints, 4416watchpoints, and catchpoints: 4417 4418@table @code 4419@kindex disable 4420@kindex dis @r{(@code{disable})} 4421@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} 4422Disable the specified breakpoints---or all breakpoints, if none are 4423listed. A disabled breakpoint has no effect but is not forgotten. All 4424options such as ignore-counts, conditions and commands are remembered in 4425case the breakpoint is enabled again later. You may abbreviate 4426@code{disable} as @code{dis}. 4427 4428@kindex enable 4429@item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} 4430Enable the specified breakpoints (or all defined breakpoints). They 4431become effective once again in stopping your program. 4432 4433@item enable @r{[}breakpoints@r{]} once @var{range}@dots{} 4434Enable the specified breakpoints temporarily. @value{GDBN} disables any 4435of these breakpoints immediately after stopping your program. 4436 4437@item enable @r{[}breakpoints@r{]} count @var{count} @var{range}@dots{} 4438Enable the specified breakpoints temporarily. @value{GDBN} records 4439@var{count} with each of the specified breakpoints, and decrements a 4440breakpoint's count when it is hit. When any count reaches 0, 4441@value{GDBN} disables that breakpoint. If a breakpoint has an ignore 4442count (@pxref{Conditions, ,Break Conditions}), that will be 4443decremented to 0 before @var{count} is affected. 4444 4445@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{} 4446Enable the specified breakpoints to work once, then die. @value{GDBN} 4447deletes any of these breakpoints as soon as your program stops there. 4448Breakpoints set by the @code{tbreak} command start out in this state. 4449@end table 4450 4451@c FIXME: I think the following ``Except for [...] @code{tbreak}'' is 4452@c confusing: tbreak is also initially enabled. 4453Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks, 4454,Setting Breakpoints}), breakpoints that you set are initially enabled; 4455subsequently, they become disabled or enabled only when you use one of 4456the commands above. (The command @code{until} can set and delete a 4457breakpoint of its own, but it does not change the state of your other 4458breakpoints; see @ref{Continuing and Stepping, ,Continuing and 4459Stepping}.) 4460 4461@node Conditions 4462@subsection Break Conditions 4463@cindex conditional breakpoints 4464@cindex breakpoint conditions 4465 4466@c FIXME what is scope of break condition expr? Context where wanted? 4467@c in particular for a watchpoint? 4468The simplest sort of breakpoint breaks every time your program reaches a 4469specified place. You can also specify a @dfn{condition} for a 4470breakpoint. A condition is just a Boolean expression in your 4471programming language (@pxref{Expressions, ,Expressions}). A breakpoint with 4472a condition evaluates the expression each time your program reaches it, 4473and your program stops only if the condition is @emph{true}. 4474 4475This is the converse of using assertions for program validation; in that 4476situation, you want to stop when the assertion is violated---that is, 4477when the condition is false. In C, if you want to test an assertion expressed 4478by the condition @var{assert}, you should set the condition 4479@samp{! @var{assert}} on the appropriate breakpoint. 4480 4481Conditions are also accepted for watchpoints; you may not need them, 4482since a watchpoint is inspecting the value of an expression anyhow---but 4483it might be simpler, say, to just set a watchpoint on a variable name, 4484and specify a condition that tests whether the new value is an interesting 4485one. 4486 4487Break conditions can have side effects, and may even call functions in 4488your program. This can be useful, for example, to activate functions 4489that log program progress, or to use your own print functions to 4490format special data structures. The effects are completely predictable 4491unless there is another enabled breakpoint at the same address. (In 4492that case, @value{GDBN} might see the other breakpoint first and stop your 4493program without checking the condition of this one.) Note that 4494breakpoint commands are usually more convenient and flexible than break 4495conditions for the 4496purpose of performing side effects when a breakpoint is reached 4497(@pxref{Break Commands, ,Breakpoint Command Lists}). 4498 4499Breakpoint conditions can also be evaluated on the target's side if 4500the target supports it. Instead of evaluating the conditions locally, 4501@value{GDBN} encodes the expression into an agent expression 4502(@pxref{Agent Expressions}) suitable for execution on the target, 4503independently of @value{GDBN}. Global variables become raw memory 4504locations, locals become stack accesses, and so forth. 4505 4506In this case, @value{GDBN} will only be notified of a breakpoint trigger 4507when its condition evaluates to true. This mechanism may provide faster 4508response times depending on the performance characteristics of the target 4509since it does not need to keep @value{GDBN} informed about 4510every breakpoint trigger, even those with false conditions. 4511 4512Break conditions can be specified when a breakpoint is set, by using 4513@samp{if} in the arguments to the @code{break} command. @xref{Set 4514Breaks, ,Setting Breakpoints}. They can also be changed at any time 4515with the @code{condition} command. 4516 4517You can also use the @code{if} keyword with the @code{watch} command. 4518The @code{catch} command does not recognize the @code{if} keyword; 4519@code{condition} is the only way to impose a further condition on a 4520catchpoint. 4521 4522@table @code 4523@kindex condition 4524@item condition @var{bnum} @var{expression} 4525Specify @var{expression} as the break condition for breakpoint, 4526watchpoint, or catchpoint number @var{bnum}. After you set a condition, 4527breakpoint @var{bnum} stops your program only if the value of 4528@var{expression} is true (nonzero, in C). When you use 4529@code{condition}, @value{GDBN} checks @var{expression} immediately for 4530syntactic correctness, and to determine whether symbols in it have 4531referents in the context of your breakpoint. If @var{expression} uses 4532symbols not referenced in the context of the breakpoint, @value{GDBN} 4533prints an error message: 4534 4535@smallexample 4536No symbol "foo" in current context. 4537@end smallexample 4538 4539@noindent 4540@value{GDBN} does 4541not actually evaluate @var{expression} at the time the @code{condition} 4542command (or a command that sets a breakpoint with a condition, like 4543@code{break if @dots{}}) is given, however. @xref{Expressions, ,Expressions}. 4544 4545@item condition @var{bnum} 4546Remove the condition from breakpoint number @var{bnum}. It becomes 4547an ordinary unconditional breakpoint. 4548@end table 4549 4550@cindex ignore count (of breakpoint) 4551A special case of a breakpoint condition is to stop only when the 4552breakpoint has been reached a certain number of times. This is so 4553useful that there is a special way to do it, using the @dfn{ignore 4554count} of the breakpoint. Every breakpoint has an ignore count, which 4555is an integer. Most of the time, the ignore count is zero, and 4556therefore has no effect. But if your program reaches a breakpoint whose 4557ignore count is positive, then instead of stopping, it just decrements 4558the ignore count by one and continues. As a result, if the ignore count 4559value is @var{n}, the breakpoint does not stop the next @var{n} times 4560your program reaches it. 4561 4562@table @code 4563@kindex ignore 4564@item ignore @var{bnum} @var{count} 4565Set the ignore count of breakpoint number @var{bnum} to @var{count}. 4566The next @var{count} times the breakpoint is reached, your program's 4567execution does not stop; other than to decrement the ignore count, @value{GDBN} 4568takes no action. 4569 4570To make the breakpoint stop the next time it is reached, specify 4571a count of zero. 4572 4573When you use @code{continue} to resume execution of your program from a 4574breakpoint, you can specify an ignore count directly as an argument to 4575@code{continue}, rather than using @code{ignore}. @xref{Continuing and 4576Stepping,,Continuing and Stepping}. 4577 4578If a breakpoint has a positive ignore count and a condition, the 4579condition is not checked. Once the ignore count reaches zero, 4580@value{GDBN} resumes checking the condition. 4581 4582You could achieve the effect of the ignore count with a condition such 4583as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that 4584is decremented each time. @xref{Convenience Vars, ,Convenience 4585Variables}. 4586@end table 4587 4588Ignore counts apply to breakpoints, watchpoints, and catchpoints. 4589 4590 4591@node Break Commands 4592@subsection Breakpoint Command Lists 4593 4594@cindex breakpoint commands 4595You can give any breakpoint (or watchpoint or catchpoint) a series of 4596commands to execute when your program stops due to that breakpoint. For 4597example, you might want to print the values of certain expressions, or 4598enable other breakpoints. 4599 4600@table @code 4601@kindex commands 4602@kindex end@r{ (breakpoint commands)} 4603@item commands @r{[}@var{range}@dots{}@r{]} 4604@itemx @dots{} @var{command-list} @dots{} 4605@itemx end 4606Specify a list of commands for the given breakpoints. The commands 4607themselves appear on the following lines. Type a line containing just 4608@code{end} to terminate the commands. 4609 4610To remove all commands from a breakpoint, type @code{commands} and 4611follow it immediately with @code{end}; that is, give no commands. 4612 4613With no argument, @code{commands} refers to the last breakpoint, 4614watchpoint, or catchpoint set (not to the breakpoint most recently 4615encountered). If the most recent breakpoints were set with a single 4616command, then the @code{commands} will apply to all the breakpoints 4617set by that command. This applies to breakpoints set by 4618@code{rbreak}, and also applies when a single @code{break} command 4619creates multiple breakpoints (@pxref{Ambiguous Expressions,,Ambiguous 4620Expressions}). 4621@end table 4622 4623Pressing @key{RET} as a means of repeating the last @value{GDBN} command is 4624disabled within a @var{command-list}. 4625 4626You can use breakpoint commands to start your program up again. Simply 4627use the @code{continue} command, or @code{step}, or any other command 4628that resumes execution. 4629 4630Any other commands in the command list, after a command that resumes 4631execution, are ignored. This is because any time you resume execution 4632(even with a simple @code{next} or @code{step}), you may encounter 4633another breakpoint---which could have its own command list, leading to 4634ambiguities about which list to execute. 4635 4636@kindex silent 4637If the first command you specify in a command list is @code{silent}, the 4638usual message about stopping at a breakpoint is not printed. This may 4639be desirable for breakpoints that are to print a specific message and 4640then continue. If none of the remaining commands print anything, you 4641see no sign that the breakpoint was reached. @code{silent} is 4642meaningful only at the beginning of a breakpoint command list. 4643 4644The commands @code{echo}, @code{output}, and @code{printf} allow you to 4645print precisely controlled output, and are often useful in silent 4646breakpoints. @xref{Output, ,Commands for Controlled Output}. 4647 4648For example, here is how you could use breakpoint commands to print the 4649value of @code{x} at entry to @code{foo} whenever @code{x} is positive. 4650 4651@smallexample 4652break foo if x>0 4653commands 4654silent 4655printf "x is %d\n",x 4656cont 4657end 4658@end smallexample 4659 4660One application for breakpoint commands is to compensate for one bug so 4661you can test for another. Put a breakpoint just after the erroneous line 4662of code, give it a condition to detect the case in which something 4663erroneous has been done, and give it commands to assign correct values 4664to any variables that need them. End with the @code{continue} command 4665so that your program does not stop, and start with the @code{silent} 4666command so that no output is produced. Here is an example: 4667 4668@smallexample 4669break 403 4670commands 4671silent 4672set x = y + 4 4673cont 4674end 4675@end smallexample 4676 4677@node Dynamic Printf 4678@subsection Dynamic Printf 4679 4680@cindex dynamic printf 4681@cindex dprintf 4682The dynamic printf command @code{dprintf} combines a breakpoint with 4683formatted printing of your program's data to give you the effect of 4684inserting @code{printf} calls into your program on-the-fly, without 4685having to recompile it. 4686 4687In its most basic form, the output goes to the GDB console. However, 4688you can set the variable @code{dprintf-style} for alternate handling. 4689For instance, you can ask to format the output by calling your 4690program's @code{printf} function. This has the advantage that the 4691characters go to the program's output device, so they can recorded in 4692redirects to files and so forth. 4693 4694If you are doing remote debugging with a stub or agent, you can also 4695ask to have the printf handled by the remote agent. In addition to 4696ensuring that the output goes to the remote program's device along 4697with any other output the program might produce, you can also ask that 4698the dprintf remain active even after disconnecting from the remote 4699target. Using the stub/agent is also more efficient, as it can do 4700everything without needing to communicate with @value{GDBN}. 4701 4702@table @code 4703@kindex dprintf 4704@item dprintf @var{location},@var{template},@var{expression}[,@var{expression}@dots{}] 4705Whenever execution reaches @var{location}, print the values of one or 4706more @var{expressions} under the control of the string @var{template}. 4707To print several values, separate them with commas. 4708 4709@item set dprintf-style @var{style} 4710Set the dprintf output to be handled in one of several different 4711styles enumerated below. A change of style affects all existing 4712dynamic printfs immediately. (If you need individual control over the 4713print commands, simply define normal breakpoints with 4714explicitly-supplied command lists.) 4715 4716@item gdb 4717@kindex dprintf-style gdb 4718Handle the output using the @value{GDBN} @code{printf} command. 4719 4720@item call 4721@kindex dprintf-style call 4722Handle the output by calling a function in your program (normally 4723@code{printf}). 4724 4725@item agent 4726@kindex dprintf-style agent 4727Have the remote debugging agent (such as @code{gdbserver}) handle 4728the output itself. This style is only available for agents that 4729support running commands on the target. 4730 4731@item set dprintf-function @var{function} 4732Set the function to call if the dprintf style is @code{call}. By 4733default its value is @code{printf}. You may set it to any expression. 4734that @value{GDBN} can evaluate to a function, as per the @code{call} 4735command. 4736 4737@item set dprintf-channel @var{channel} 4738Set a ``channel'' for dprintf. If set to a non-empty value, 4739@value{GDBN} will evaluate it as an expression and pass the result as 4740a first argument to the @code{dprintf-function}, in the manner of 4741@code{fprintf} and similar functions. Otherwise, the dprintf format 4742string will be the first argument, in the manner of @code{printf}. 4743 4744As an example, if you wanted @code{dprintf} output to go to a logfile 4745that is a standard I/O stream assigned to the variable @code{mylog}, 4746you could do the following: 4747 4748@example 4749(gdb) set dprintf-style call 4750(gdb) set dprintf-function fprintf 4751(gdb) set dprintf-channel mylog 4752(gdb) dprintf 25,"at line 25, glob=%d\n",glob 4753Dprintf 1 at 0x123456: file main.c, line 25. 4754(gdb) info break 47551 dprintf keep y 0x00123456 in main at main.c:25 4756 call (void) fprintf (mylog,"at line 25, glob=%d\n",glob) 4757 continue 4758(gdb) 4759@end example 4760 4761Note that the @code{info break} displays the dynamic printf commands 4762as normal breakpoint commands; you can thus easily see the effect of 4763the variable settings. 4764 4765@item set disconnected-dprintf on 4766@itemx set disconnected-dprintf off 4767@kindex set disconnected-dprintf 4768Choose whether @code{dprintf} commands should continue to run if 4769@value{GDBN} has disconnected from the target. This only applies 4770if the @code{dprintf-style} is @code{agent}. 4771 4772@item show disconnected-dprintf off 4773@kindex show disconnected-dprintf 4774Show the current choice for disconnected @code{dprintf}. 4775 4776@end table 4777 4778@value{GDBN} does not check the validity of function and channel, 4779relying on you to supply values that are meaningful for the contexts 4780in which they are being used. For instance, the function and channel 4781may be the values of local variables, but if that is the case, then 4782all enabled dynamic prints must be at locations within the scope of 4783those locals. If evaluation fails, @value{GDBN} will report an error. 4784 4785@node Save Breakpoints 4786@subsection How to save breakpoints to a file 4787 4788To save breakpoint definitions to a file use the @w{@code{save 4789breakpoints}} command. 4790 4791@table @code 4792@kindex save breakpoints 4793@cindex save breakpoints to a file for future sessions 4794@item save breakpoints [@var{filename}] 4795This command saves all current breakpoint definitions together with 4796their commands and ignore counts, into a file @file{@var{filename}} 4797suitable for use in a later debugging session. This includes all 4798types of breakpoints (breakpoints, watchpoints, catchpoints, 4799tracepoints). To read the saved breakpoint definitions, use the 4800@code{source} command (@pxref{Command Files}). Note that watchpoints 4801with expressions involving local variables may fail to be recreated 4802because it may not be possible to access the context where the 4803watchpoint is valid anymore. Because the saved breakpoint definitions 4804are simply a sequence of @value{GDBN} commands that recreate the 4805breakpoints, you can edit the file in your favorite editing program, 4806and remove the breakpoint definitions you're not interested in, or 4807that can no longer be recreated. 4808@end table 4809 4810@node Static Probe Points 4811@subsection Static Probe Points 4812 4813@cindex static probe point, SystemTap 4814@value{GDBN} supports @dfn{SDT} probes in the code. @acronym{SDT} stands 4815for Statically Defined Tracing, and the probes are designed to have a tiny 4816runtime code and data footprint, and no dynamic relocations. They are 4817usable from assembly, C and C@t{++} languages. See 4818@uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation} 4819for a good reference on how the @acronym{SDT} probes are implemented. 4820 4821Currently, @code{SystemTap} (@uref{http://sourceware.org/systemtap/}) 4822@acronym{SDT} probes are supported on ELF-compatible systems. See 4823@uref{http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps} 4824for more information on how to add @code{SystemTap} @acronym{SDT} probes 4825in your applications. 4826 4827@cindex semaphores on static probe points 4828Some probes have an associated semaphore variable; for instance, this 4829happens automatically if you defined your probe using a DTrace-style 4830@file{.d} file. If your probe has a semaphore, @value{GDBN} will 4831automatically enable it when you specify a breakpoint using the 4832@samp{-probe-stap} notation. But, if you put a breakpoint at a probe's 4833location by some other method (e.g., @code{break file:line}), then 4834@value{GDBN} will not automatically set the semaphore. 4835 4836You can examine the available static static probes using @code{info 4837probes}, with optional arguments: 4838 4839@table @code 4840@kindex info probes 4841@item info probes stap @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]} 4842If given, @var{provider} is a regular expression used to match against provider 4843names when selecting which probes to list. If omitted, probes by all 4844probes from all providers are listed. 4845 4846If given, @var{name} is a regular expression to match against probe names 4847when selecting which probes to list. If omitted, probe names are not 4848considered when deciding whether to display them. 4849 4850If given, @var{objfile} is a regular expression used to select which 4851object files (executable or shared libraries) to examine. If not 4852given, all object files are considered. 4853 4854@item info probes all 4855List the available static probes, from all types. 4856@end table 4857 4858@vindex $_probe_arg@r{, convenience variable} 4859A probe may specify up to twelve arguments. These are available at the 4860point at which the probe is defined---that is, when the current PC is 4861at the probe's location. The arguments are available using the 4862convenience variables (@pxref{Convenience Vars}) 4863@code{$_probe_arg0}@dots{}@code{$_probe_arg11}. Each probe argument is 4864an integer of the appropriate size; types are not preserved. The 4865convenience variable @code{$_probe_argc} holds the number of arguments 4866at the current probe point. 4867 4868These variables are always available, but attempts to access them at 4869any location other than a probe point will cause @value{GDBN} to give 4870an error message. 4871 4872 4873@c @ifclear BARETARGET 4874@node Error in Breakpoints 4875@subsection ``Cannot insert breakpoints'' 4876 4877If you request too many active hardware-assisted breakpoints and 4878watchpoints, you will see this error message: 4879 4880@c FIXME: the precise wording of this message may change; the relevant 4881@c source change is not committed yet (Sep 3, 1999). 4882@smallexample 4883Stopped; cannot insert breakpoints. 4884You may have requested too many hardware breakpoints and watchpoints. 4885@end smallexample 4886 4887@noindent 4888This message is printed when you attempt to resume the program, since 4889only then @value{GDBN} knows exactly how many hardware breakpoints and 4890watchpoints it needs to insert. 4891 4892When this message is printed, you need to disable or remove some of the 4893hardware-assisted breakpoints and watchpoints, and then continue. 4894 4895@node Breakpoint-related Warnings 4896@subsection ``Breakpoint address adjusted...'' 4897@cindex breakpoint address adjusted 4898 4899Some processor architectures place constraints on the addresses at 4900which breakpoints may be placed. For architectures thus constrained, 4901@value{GDBN} will attempt to adjust the breakpoint's address to comply 4902with the constraints dictated by the architecture. 4903 4904One example of such an architecture is the Fujitsu FR-V. The FR-V is 4905a VLIW architecture in which a number of RISC-like instructions may be 4906bundled together for parallel execution. The FR-V architecture 4907constrains the location of a breakpoint instruction within such a 4908bundle to the instruction with the lowest address. @value{GDBN} 4909honors this constraint by adjusting a breakpoint's address to the 4910first in the bundle. 4911 4912It is not uncommon for optimized code to have bundles which contain 4913instructions from different source statements, thus it may happen that 4914a breakpoint's address will be adjusted from one source statement to 4915another. Since this adjustment may significantly alter @value{GDBN}'s 4916breakpoint related behavior from what the user expects, a warning is 4917printed when the breakpoint is first set and also when the breakpoint 4918is hit. 4919 4920A warning like the one below is printed when setting a breakpoint 4921that's been subject to address adjustment: 4922 4923@smallexample 4924warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. 4925@end smallexample 4926 4927Such warnings are printed both for user settable and @value{GDBN}'s 4928internal breakpoints. If you see one of these warnings, you should 4929verify that a breakpoint set at the adjusted address will have the 4930desired affect. If not, the breakpoint in question may be removed and 4931other breakpoints may be set which will have the desired behavior. 4932E.g., it may be sufficient to place the breakpoint at a later 4933instruction. A conditional breakpoint may also be useful in some 4934cases to prevent the breakpoint from triggering too often. 4935 4936@value{GDBN} will also issue a warning when stopping at one of these 4937adjusted breakpoints: 4938 4939@smallexample 4940warning: Breakpoint 1 address previously adjusted from 0x00010414 4941to 0x00010410. 4942@end smallexample 4943 4944When this warning is encountered, it may be too late to take remedial 4945action except in cases where the breakpoint is hit earlier or more 4946frequently than expected. 4947 4948@node Continuing and Stepping 4949@section Continuing and Stepping 4950 4951@cindex stepping 4952@cindex continuing 4953@cindex resuming execution 4954@dfn{Continuing} means resuming program execution until your program 4955completes normally. In contrast, @dfn{stepping} means executing just 4956one more ``step'' of your program, where ``step'' may mean either one 4957line of source code, or one machine instruction (depending on what 4958particular command you use). Either when continuing or when stepping, 4959your program may stop even sooner, due to a breakpoint or a signal. (If 4960it stops due to a signal, you may want to use @code{handle}, or use 4961@samp{signal 0} to resume execution. @xref{Signals, ,Signals}.) 4962 4963@table @code 4964@kindex continue 4965@kindex c @r{(@code{continue})} 4966@kindex fg @r{(resume foreground execution)} 4967@item continue @r{[}@var{ignore-count}@r{]} 4968@itemx c @r{[}@var{ignore-count}@r{]} 4969@itemx fg @r{[}@var{ignore-count}@r{]} 4970Resume program execution, at the address where your program last stopped; 4971any breakpoints set at that address are bypassed. The optional argument 4972@var{ignore-count} allows you to specify a further number of times to 4973ignore a breakpoint at this location; its effect is like that of 4974@code{ignore} (@pxref{Conditions, ,Break Conditions}). 4975 4976The argument @var{ignore-count} is meaningful only when your program 4977stopped due to a breakpoint. At other times, the argument to 4978@code{continue} is ignored. 4979 4980The synonyms @code{c} and @code{fg} (for @dfn{foreground}, as the 4981debugged program is deemed to be the foreground program) are provided 4982purely for convenience, and have exactly the same behavior as 4983@code{continue}. 4984@end table 4985 4986To resume execution at a different place, you can use @code{return} 4987(@pxref{Returning, ,Returning from a Function}) to go back to the 4988calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a 4989Different Address}) to go to an arbitrary location in your program. 4990 4991A typical technique for using stepping is to set a breakpoint 4992(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Catchpoints}) at the 4993beginning of the function or the section of your program where a problem 4994is believed to lie, run your program until it stops at that breakpoint, 4995and then step through the suspect area, examining the variables that are 4996interesting, until you see the problem happen. 4997 4998@table @code 4999@kindex step 5000@kindex s @r{(@code{step})} 5001@item step 5002Continue running your program until control reaches a different source 5003line, then stop it and return control to @value{GDBN}. This command is 5004abbreviated @code{s}. 5005 5006@quotation 5007@c "without debugging information" is imprecise; actually "without line 5008@c numbers in the debugging information". (gcc -g1 has debugging info but 5009@c not line numbers). But it seems complex to try to make that 5010@c distinction here. 5011@emph{Warning:} If you use the @code{step} command while control is 5012within a function that was compiled without debugging information, 5013execution proceeds until control reaches a function that does have 5014debugging information. Likewise, it will not step into a function which 5015is compiled without debugging information. To step through functions 5016without debugging information, use the @code{stepi} command, described 5017below. 5018@end quotation 5019 5020The @code{step} command only stops at the first instruction of a source 5021line. This prevents the multiple stops that could otherwise occur in 5022@code{switch} statements, @code{for} loops, etc. @code{step} continues 5023to stop if a function that has debugging information is called within 5024the line. In other words, @code{step} @emph{steps inside} any functions 5025called within the line. 5026 5027Also, the @code{step} command only enters a function if there is line 5028number information for the function. Otherwise it acts like the 5029@code{next} command. This avoids problems when using @code{cc -gl} 5030on @acronym{MIPS} machines. Previously, @code{step} entered subroutines if there 5031was any debugging information about the routine. 5032 5033@item step @var{count} 5034Continue running as in @code{step}, but do so @var{count} times. If a 5035breakpoint is reached, or a signal not related to stepping occurs before 5036@var{count} steps, stepping stops right away. 5037 5038@kindex next 5039@kindex n @r{(@code{next})} 5040@item next @r{[}@var{count}@r{]} 5041Continue to the next source line in the current (innermost) stack frame. 5042This is similar to @code{step}, but function calls that appear within 5043the line of code are executed without stopping. Execution stops when 5044control reaches a different line of code at the original stack level 5045that was executing when you gave the @code{next} command. This command 5046is abbreviated @code{n}. 5047 5048An argument @var{count} is a repeat count, as for @code{step}. 5049 5050 5051@c FIX ME!! Do we delete this, or is there a way it fits in with 5052@c the following paragraph? --- Vctoria 5053@c 5054@c @code{next} within a function that lacks debugging information acts like 5055@c @code{step}, but any function calls appearing within the code of the 5056@c function are executed without stopping. 5057 5058The @code{next} command only stops at the first instruction of a 5059source line. This prevents multiple stops that could otherwise occur in 5060@code{switch} statements, @code{for} loops, etc. 5061 5062@kindex set step-mode 5063@item set step-mode 5064@cindex functions without line info, and stepping 5065@cindex stepping into functions with no line info 5066@itemx set step-mode on 5067The @code{set step-mode on} command causes the @code{step} command to 5068stop at the first instruction of a function which contains no debug line 5069information rather than stepping over it. 5070 5071This is useful in cases where you may be interested in inspecting the 5072machine instructions of a function which has no symbolic info and do not 5073want @value{GDBN} to automatically skip over this function. 5074 5075@item set step-mode off 5076Causes the @code{step} command to step over any functions which contains no 5077debug information. This is the default. 5078 5079@item show step-mode 5080Show whether @value{GDBN} will stop in or step over functions without 5081source line debug information. 5082 5083@kindex finish 5084@kindex fin @r{(@code{finish})} 5085@item finish 5086Continue running until just after function in the selected stack frame 5087returns. Print the returned value (if any). This command can be 5088abbreviated as @code{fin}. 5089 5090Contrast this with the @code{return} command (@pxref{Returning, 5091,Returning from a Function}). 5092 5093@kindex until 5094@kindex u @r{(@code{until})} 5095@cindex run until specified location 5096@item until 5097@itemx u 5098Continue running until a source line past the current line, in the 5099current stack frame, is reached. This command is used to avoid single 5100stepping through a loop more than once. It is like the @code{next} 5101command, except that when @code{until} encounters a jump, it 5102automatically continues execution until the program counter is greater 5103than the address of the jump. 5104 5105This means that when you reach the end of a loop after single stepping 5106though it, @code{until} makes your program continue execution until it 5107exits the loop. In contrast, a @code{next} command at the end of a loop 5108simply steps back to the beginning of the loop, which forces you to step 5109through the next iteration. 5110 5111@code{until} always stops your program if it attempts to exit the current 5112stack frame. 5113 5114@code{until} may produce somewhat counterintuitive results if the order 5115of machine code does not match the order of the source lines. For 5116example, in the following excerpt from a debugging session, the @code{f} 5117(@code{frame}) command shows that execution is stopped at line 5118@code{206}; yet when we use @code{until}, we get to line @code{195}: 5119 5120@smallexample 5121(@value{GDBP}) f 5122#0 main (argc=4, argv=0xf7fffae8) at m4.c:206 5123206 expand_input(); 5124(@value{GDBP}) until 5125195 for ( ; argc > 0; NEXTARG) @{ 5126@end smallexample 5127 5128This happened because, for execution efficiency, the compiler had 5129generated code for the loop closure test at the end, rather than the 5130start, of the loop---even though the test in a C @code{for}-loop is 5131written before the body of the loop. The @code{until} command appeared 5132to step back to the beginning of the loop when it advanced to this 5133expression; however, it has not really gone to an earlier 5134statement---not in terms of the actual machine code. 5135 5136@code{until} with no argument works by means of single 5137instruction stepping, and hence is slower than @code{until} with an 5138argument. 5139 5140@item until @var{location} 5141@itemx u @var{location} 5142Continue running your program until either the specified location is 5143reached, or the current stack frame returns. @var{location} is any of 5144the forms described in @ref{Specify Location}. 5145This form of the command uses temporary breakpoints, and 5146hence is quicker than @code{until} without an argument. The specified 5147location is actually reached only if it is in the current frame. This 5148implies that @code{until} can be used to skip over recursive function 5149invocations. For instance in the code below, if the current location is 5150line @code{96}, issuing @code{until 99} will execute the program up to 5151line @code{99} in the same invocation of factorial, i.e., after the inner 5152invocations have returned. 5153 5154@smallexample 515594 int factorial (int value) 515695 @{ 515796 if (value > 1) @{ 515897 value *= factorial (value - 1); 515998 @} 516099 return (value); 5161100 @} 5162@end smallexample 5163 5164 5165@kindex advance @var{location} 5166@item advance @var{location} 5167Continue running the program up to the given @var{location}. An argument is 5168required, which should be of one of the forms described in 5169@ref{Specify Location}. 5170Execution will also stop upon exit from the current stack 5171frame. This command is similar to @code{until}, but @code{advance} will 5172not skip over recursive function calls, and the target location doesn't 5173have to be in the same frame as the current one. 5174 5175 5176@kindex stepi 5177@kindex si @r{(@code{stepi})} 5178@item stepi 5179@itemx stepi @var{arg} 5180@itemx si 5181Execute one machine instruction, then stop and return to the debugger. 5182 5183It is often useful to do @samp{display/i $pc} when stepping by machine 5184instructions. This makes @value{GDBN} automatically display the next 5185instruction to be executed, each time your program stops. @xref{Auto 5186Display,, Automatic Display}. 5187 5188An argument is a repeat count, as in @code{step}. 5189 5190@need 750 5191@kindex nexti 5192@kindex ni @r{(@code{nexti})} 5193@item nexti 5194@itemx nexti @var{arg} 5195@itemx ni 5196Execute one machine instruction, but if it is a function call, 5197proceed until the function returns. 5198 5199An argument is a repeat count, as in @code{next}. 5200@end table 5201 5202@node Skipping Over Functions and Files 5203@section Skipping Over Functions and Files 5204@cindex skipping over functions and files 5205 5206The program you are debugging may contain some functions which are 5207uninteresting to debug. The @code{skip} comand lets you tell @value{GDBN} to 5208skip a function or all functions in a file when stepping. 5209 5210For example, consider the following C function: 5211 5212@smallexample 5213101 int func() 5214102 @{ 5215103 foo(boring()); 5216104 bar(boring()); 5217105 @} 5218@end smallexample 5219 5220@noindent 5221Suppose you wish to step into the functions @code{foo} and @code{bar}, but you 5222are not interested in stepping through @code{boring}. If you run @code{step} 5223at line 103, you'll enter @code{boring()}, but if you run @code{next}, you'll 5224step over both @code{foo} and @code{boring}! 5225 5226One solution is to @code{step} into @code{boring} and use the @code{finish} 5227command to immediately exit it. But this can become tedious if @code{boring} 5228is called from many places. 5229 5230A more flexible solution is to execute @kbd{skip boring}. This instructs 5231@value{GDBN} never to step into @code{boring}. Now when you execute 5232@code{step} at line 103, you'll step over @code{boring} and directly into 5233@code{foo}. 5234 5235You can also instruct @value{GDBN} to skip all functions in a file, with, for 5236example, @code{skip file boring.c}. 5237 5238@table @code 5239@kindex skip function 5240@item skip @r{[}@var{linespec}@r{]} 5241@itemx skip function @r{[}@var{linespec}@r{]} 5242After running this command, the function named by @var{linespec} or the 5243function containing the line named by @var{linespec} will be skipped over when 5244stepping. @xref{Specify Location}. 5245 5246If you do not specify @var{linespec}, the function you're currently debugging 5247will be skipped. 5248 5249(If you have a function called @code{file} that you want to skip, use 5250@kbd{skip function file}.) 5251 5252@kindex skip file 5253@item skip file @r{[}@var{filename}@r{]} 5254After running this command, any function whose source lives in @var{filename} 5255will be skipped over when stepping. 5256 5257If you do not specify @var{filename}, functions whose source lives in the file 5258you're currently debugging will be skipped. 5259@end table 5260 5261Skips can be listed, deleted, disabled, and enabled, much like breakpoints. 5262These are the commands for managing your list of skips: 5263 5264@table @code 5265@kindex info skip 5266@item info skip @r{[}@var{range}@r{]} 5267Print details about the specified skip(s). If @var{range} is not specified, 5268print a table with details about all functions and files marked for skipping. 5269@code{info skip} prints the following information about each skip: 5270 5271@table @emph 5272@item Identifier 5273A number identifying this skip. 5274@item Type 5275The type of this skip, either @samp{function} or @samp{file}. 5276@item Enabled or Disabled 5277Enabled skips are marked with @samp{y}. Disabled skips are marked with @samp{n}. 5278@item Address 5279For function skips, this column indicates the address in memory of the function 5280being skipped. If you've set a function skip on a function which has not yet 5281been loaded, this field will contain @samp{<PENDING>}. Once a shared library 5282which has the function is loaded, @code{info skip} will show the function's 5283address here. 5284@item What 5285For file skips, this field contains the filename being skipped. For functions 5286skips, this field contains the function name and its line number in the file 5287where it is defined. 5288@end table 5289 5290@kindex skip delete 5291@item skip delete @r{[}@var{range}@r{]} 5292Delete the specified skip(s). If @var{range} is not specified, delete all 5293skips. 5294 5295@kindex skip enable 5296@item skip enable @r{[}@var{range}@r{]} 5297Enable the specified skip(s). If @var{range} is not specified, enable all 5298skips. 5299 5300@kindex skip disable 5301@item skip disable @r{[}@var{range}@r{]} 5302Disable the specified skip(s). If @var{range} is not specified, disable all 5303skips. 5304 5305@end table 5306 5307@node Signals 5308@section Signals 5309@cindex signals 5310 5311A signal is an asynchronous event that can happen in a program. The 5312operating system defines the possible kinds of signals, and gives each 5313kind a name and a number. For example, in Unix @code{SIGINT} is the 5314signal a program gets when you type an interrupt character (often @kbd{Ctrl-c}); 5315@code{SIGSEGV} is the signal a program gets from referencing a place in 5316memory far away from all the areas in use; @code{SIGALRM} occurs when 5317the alarm clock timer goes off (which happens only if your program has 5318requested an alarm). 5319 5320@cindex fatal signals 5321Some signals, including @code{SIGALRM}, are a normal part of the 5322functioning of your program. Others, such as @code{SIGSEGV}, indicate 5323errors; these signals are @dfn{fatal} (they kill your program immediately) if the 5324program has not specified in advance some other way to handle the signal. 5325@code{SIGINT} does not indicate an error in your program, but it is normally 5326fatal so it can carry out the purpose of the interrupt: to kill the program. 5327 5328@value{GDBN} has the ability to detect any occurrence of a signal in your 5329program. You can tell @value{GDBN} in advance what to do for each kind of 5330signal. 5331 5332@cindex handling signals 5333Normally, @value{GDBN} is set up to let the non-erroneous signals like 5334@code{SIGALRM} be silently passed to your program 5335(so as not to interfere with their role in the program's functioning) 5336but to stop your program immediately whenever an error signal happens. 5337You can change these settings with the @code{handle} command. 5338 5339@table @code 5340@kindex info signals 5341@kindex info handle 5342@item info signals 5343@itemx info handle 5344Print a table of all the kinds of signals and how @value{GDBN} has been told to 5345handle each one. You can use this to see the signal numbers of all 5346the defined types of signals. 5347 5348@item info signals @var{sig} 5349Similar, but print information only about the specified signal number. 5350 5351@code{info handle} is an alias for @code{info signals}. 5352 5353@item catch signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]} 5354Set a catchpoint for the indicated signals. @xref{Set Catchpoints}, 5355for details about this command. 5356 5357@kindex handle 5358@item handle @var{signal} @r{[}@var{keywords}@dots{}@r{]} 5359Change the way @value{GDBN} handles signal @var{signal}. @var{signal} 5360can be the number of a signal or its name (with or without the 5361@samp{SIG} at the beginning); a list of signal numbers of the form 5362@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the 5363known signals. Optional arguments @var{keywords}, described below, 5364say what change to make. 5365@end table 5366 5367@c @group 5368The keywords allowed by the @code{handle} command can be abbreviated. 5369Their full names are: 5370 5371@table @code 5372@item nostop 5373@value{GDBN} should not stop your program when this signal happens. It may 5374still print a message telling you that the signal has come in. 5375 5376@item stop 5377@value{GDBN} should stop your program when this signal happens. This implies 5378the @code{print} keyword as well. 5379 5380@item print 5381@value{GDBN} should print a message when this signal happens. 5382 5383@item noprint 5384@value{GDBN} should not mention the occurrence of the signal at all. This 5385implies the @code{nostop} keyword as well. 5386 5387@item pass 5388@itemx noignore 5389@value{GDBN} should allow your program to see this signal; your program 5390can handle the signal, or else it may terminate if the signal is fatal 5391and not handled. @code{pass} and @code{noignore} are synonyms. 5392 5393@item nopass 5394@itemx ignore 5395@value{GDBN} should not allow your program to see this signal. 5396@code{nopass} and @code{ignore} are synonyms. 5397@end table 5398@c @end group 5399 5400When a signal stops your program, the signal is not visible to the 5401program until you 5402continue. Your program sees the signal then, if @code{pass} is in 5403effect for the signal in question @emph{at that time}. In other words, 5404after @value{GDBN} reports a signal, you can use the @code{handle} 5405command with @code{pass} or @code{nopass} to control whether your 5406program sees that signal when you continue. 5407 5408The default is set to @code{nostop}, @code{noprint}, @code{pass} for 5409non-erroneous signals such as @code{SIGALRM}, @code{SIGWINCH} and 5410@code{SIGCHLD}, and to @code{stop}, @code{print}, @code{pass} for the 5411erroneous signals. 5412 5413You can also use the @code{signal} command to prevent your program from 5414seeing a signal, or cause it to see a signal it normally would not see, 5415or to give it any signal at any time. For example, if your program stopped 5416due to some sort of memory reference error, you might store correct 5417values into the erroneous variables and continue, hoping to see more 5418execution; but your program would probably terminate immediately as 5419a result of the fatal signal once it saw the signal. To prevent this, 5420you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your 5421Program a Signal}. 5422 5423@cindex extra signal information 5424@anchor{extra signal information} 5425 5426On some targets, @value{GDBN} can inspect extra signal information 5427associated with the intercepted signal, before it is actually 5428delivered to the program being debugged. This information is exported 5429by the convenience variable @code{$_siginfo}, and consists of data 5430that is passed by the kernel to the signal handler at the time of the 5431receipt of a signal. The data type of the information itself is 5432target dependent. You can see the data type using the @code{ptype 5433$_siginfo} command. On Unix systems, it typically corresponds to the 5434standard @code{siginfo_t} type, as defined in the @file{signal.h} 5435system header. 5436 5437Here's an example, on a @sc{gnu}/Linux system, printing the stray 5438referenced address that raised a segmentation fault. 5439 5440@smallexample 5441@group 5442(@value{GDBP}) continue 5443Program received signal SIGSEGV, Segmentation fault. 54440x0000000000400766 in main () 544569 *(int *)p = 0; 5446(@value{GDBP}) ptype $_siginfo 5447type = struct @{ 5448 int si_signo; 5449 int si_errno; 5450 int si_code; 5451 union @{ 5452 int _pad[28]; 5453 struct @{...@} _kill; 5454 struct @{...@} _timer; 5455 struct @{...@} _rt; 5456 struct @{...@} _sigchld; 5457 struct @{...@} _sigfault; 5458 struct @{...@} _sigpoll; 5459 @} _sifields; 5460@} 5461(@value{GDBP}) ptype $_siginfo._sifields._sigfault 5462type = struct @{ 5463 void *si_addr; 5464@} 5465(@value{GDBP}) p $_siginfo._sifields._sigfault.si_addr 5466$1 = (void *) 0x7ffff7ff7000 5467@end group 5468@end smallexample 5469 5470Depending on target support, @code{$_siginfo} may also be writable. 5471 5472@node Thread Stops 5473@section Stopping and Starting Multi-thread Programs 5474 5475@cindex stopped threads 5476@cindex threads, stopped 5477 5478@cindex continuing threads 5479@cindex threads, continuing 5480 5481@value{GDBN} supports debugging programs with multiple threads 5482(@pxref{Threads,, Debugging Programs with Multiple Threads}). There 5483are two modes of controlling execution of your program within the 5484debugger. In the default mode, referred to as @dfn{all-stop mode}, 5485when any thread in your program stops (for example, at a breakpoint 5486or while being stepped), all other threads in the program are also stopped by 5487@value{GDBN}. On some targets, @value{GDBN} also supports 5488@dfn{non-stop mode}, in which other threads can continue to run freely while 5489you examine the stopped thread in the debugger. 5490 5491@menu 5492* All-Stop Mode:: All threads stop when GDB takes control 5493* Non-Stop Mode:: Other threads continue to execute 5494* Background Execution:: Running your program asynchronously 5495* Thread-Specific Breakpoints:: Controlling breakpoints 5496* Interrupted System Calls:: GDB may interfere with system calls 5497* Observer Mode:: GDB does not alter program behavior 5498@end menu 5499 5500@node All-Stop Mode 5501@subsection All-Stop Mode 5502 5503@cindex all-stop mode 5504 5505In all-stop mode, whenever your program stops under @value{GDBN} for any reason, 5506@emph{all} threads of execution stop, not just the current thread. This 5507allows you to examine the overall state of the program, including 5508switching between threads, without worrying that things may change 5509underfoot. 5510 5511Conversely, whenever you restart the program, @emph{all} threads start 5512executing. @emph{This is true even when single-stepping} with commands 5513like @code{step} or @code{next}. 5514 5515In particular, @value{GDBN} cannot single-step all threads in lockstep. 5516Since thread scheduling is up to your debugging target's operating 5517system (not controlled by @value{GDBN}), other threads may 5518execute more than one statement while the current thread completes a 5519single step. Moreover, in general other threads stop in the middle of a 5520statement, rather than at a clean statement boundary, when the program 5521stops. 5522 5523You might even find your program stopped in another thread after 5524continuing or even single-stepping. This happens whenever some other 5525thread runs into a breakpoint, a signal, or an exception before the 5526first thread completes whatever you requested. 5527 5528@cindex automatic thread selection 5529@cindex switching threads automatically 5530@cindex threads, automatic switching 5531Whenever @value{GDBN} stops your program, due to a breakpoint or a 5532signal, it automatically selects the thread where that breakpoint or 5533signal happened. @value{GDBN} alerts you to the context switch with a 5534message such as @samp{[Switching to Thread @var{n}]} to identify the 5535thread. 5536 5537On some OSes, you can modify @value{GDBN}'s default behavior by 5538locking the OS scheduler to allow only a single thread to run. 5539 5540@table @code 5541@item set scheduler-locking @var{mode} 5542@cindex scheduler locking mode 5543@cindex lock scheduler 5544Set the scheduler locking mode. If it is @code{off}, then there is no 5545locking and any thread may run at any time. If @code{on}, then only the 5546current thread may run when the inferior is resumed. The @code{step} 5547mode optimizes for single-stepping; it prevents other threads 5548from preempting the current thread while you are stepping, so that 5549the focus of debugging does not change unexpectedly. 5550Other threads only rarely (or never) get a chance to run 5551when you step. They are more likely to run when you @samp{next} over a 5552function call, and they are completely free to run when you use commands 5553like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another 5554thread hits a breakpoint during its timeslice, @value{GDBN} does not change 5555the current thread away from the thread that you are debugging. 5556 5557@item show scheduler-locking 5558Display the current scheduler locking mode. 5559@end table 5560 5561@cindex resume threads of multiple processes simultaneously 5562By default, when you issue one of the execution commands such as 5563@code{continue}, @code{next} or @code{step}, @value{GDBN} allows only 5564threads of the current inferior to run. For example, if @value{GDBN} 5565is attached to two inferiors, each with two threads, the 5566@code{continue} command resumes only the two threads of the current 5567inferior. This is useful, for example, when you debug a program that 5568forks and you want to hold the parent stopped (so that, for instance, 5569it doesn't run to exit), while you debug the child. In other 5570situations, you may not be interested in inspecting the current state 5571of any of the processes @value{GDBN} is attached to, and you may want 5572to resume them all until some breakpoint is hit. In the latter case, 5573you can instruct @value{GDBN} to allow all threads of all the 5574inferiors to run with the @w{@code{set schedule-multiple}} command. 5575 5576@table @code 5577@kindex set schedule-multiple 5578@item set schedule-multiple 5579Set the mode for allowing threads of multiple processes to be resumed 5580when an execution command is issued. When @code{on}, all threads of 5581all processes are allowed to run. When @code{off}, only the threads 5582of the current process are resumed. The default is @code{off}. The 5583@code{scheduler-locking} mode takes precedence when set to @code{on}, 5584or while you are stepping and set to @code{step}. 5585 5586@item show schedule-multiple 5587Display the current mode for resuming the execution of threads of 5588multiple processes. 5589@end table 5590 5591@node Non-Stop Mode 5592@subsection Non-Stop Mode 5593 5594@cindex non-stop mode 5595 5596@c This section is really only a place-holder, and needs to be expanded 5597@c with more details. 5598 5599For some multi-threaded targets, @value{GDBN} supports an optional 5600mode of operation in which you can examine stopped program threads in 5601the debugger while other threads continue to execute freely. This 5602minimizes intrusion when debugging live systems, such as programs 5603where some threads have real-time constraints or must continue to 5604respond to external events. This is referred to as @dfn{non-stop} mode. 5605 5606In non-stop mode, when a thread stops to report a debugging event, 5607@emph{only} that thread is stopped; @value{GDBN} does not stop other 5608threads as well, in contrast to the all-stop mode behavior. Additionally, 5609execution commands such as @code{continue} and @code{step} apply by default 5610only to the current thread in non-stop mode, rather than all threads as 5611in all-stop mode. This allows you to control threads explicitly in 5612ways that are not possible in all-stop mode --- for example, stepping 5613one thread while allowing others to run freely, stepping 5614one thread while holding all others stopped, or stepping several threads 5615independently and simultaneously. 5616 5617To enter non-stop mode, use this sequence of commands before you run 5618or attach to your program: 5619 5620@smallexample 5621# Enable the async interface. 5622set target-async 1 5623 5624# If using the CLI, pagination breaks non-stop. 5625set pagination off 5626 5627# Finally, turn it on! 5628set non-stop on 5629@end smallexample 5630 5631You can use these commands to manipulate the non-stop mode setting: 5632 5633@table @code 5634@kindex set non-stop 5635@item set non-stop on 5636Enable selection of non-stop mode. 5637@item set non-stop off 5638Disable selection of non-stop mode. 5639@kindex show non-stop 5640@item show non-stop 5641Show the current non-stop enablement setting. 5642@end table 5643 5644Note these commands only reflect whether non-stop mode is enabled, 5645not whether the currently-executing program is being run in non-stop mode. 5646In particular, the @code{set non-stop} preference is only consulted when 5647@value{GDBN} starts or connects to the target program, and it is generally 5648not possible to switch modes once debugging has started. Furthermore, 5649since not all targets support non-stop mode, even when you have enabled 5650non-stop mode, @value{GDBN} may still fall back to all-stop operation by 5651default. 5652 5653In non-stop mode, all execution commands apply only to the current thread 5654by default. That is, @code{continue} only continues one thread. 5655To continue all threads, issue @code{continue -a} or @code{c -a}. 5656 5657You can use @value{GDBN}'s background execution commands 5658(@pxref{Background Execution}) to run some threads in the background 5659while you continue to examine or step others from @value{GDBN}. 5660The MI execution commands (@pxref{GDB/MI Program Execution}) are 5661always executed asynchronously in non-stop mode. 5662 5663Suspending execution is done with the @code{interrupt} command when 5664running in the background, or @kbd{Ctrl-c} during foreground execution. 5665In all-stop mode, this stops the whole process; 5666but in non-stop mode the interrupt applies only to the current thread. 5667To stop the whole program, use @code{interrupt -a}. 5668 5669Other execution commands do not currently support the @code{-a} option. 5670 5671In non-stop mode, when a thread stops, @value{GDBN} doesn't automatically make 5672that thread current, as it does in all-stop mode. This is because the 5673thread stop notifications are asynchronous with respect to @value{GDBN}'s 5674command interpreter, and it would be confusing if @value{GDBN} unexpectedly 5675changed to a different thread just as you entered a command to operate on the 5676previously current thread. 5677 5678@node Background Execution 5679@subsection Background Execution 5680 5681@cindex foreground execution 5682@cindex background execution 5683@cindex asynchronous execution 5684@cindex execution, foreground, background and asynchronous 5685 5686@value{GDBN}'s execution commands have two variants: the normal 5687foreground (synchronous) behavior, and a background 5688(asynchronous) behavior. In foreground execution, @value{GDBN} waits for 5689the program to report that some thread has stopped before prompting for 5690another command. In background execution, @value{GDBN} immediately gives 5691a command prompt so that you can issue other commands while your program runs. 5692 5693You need to explicitly enable asynchronous mode before you can use 5694background execution commands. You can use these commands to 5695manipulate the asynchronous mode setting: 5696 5697@table @code 5698@kindex set target-async 5699@item set target-async on 5700Enable asynchronous mode. 5701@item set target-async off 5702Disable asynchronous mode. 5703@kindex show target-async 5704@item show target-async 5705Show the current target-async setting. 5706@end table 5707 5708If the target doesn't support async mode, @value{GDBN} issues an error 5709message if you attempt to use the background execution commands. 5710 5711To specify background execution, add a @code{&} to the command. For example, 5712the background form of the @code{continue} command is @code{continue&}, or 5713just @code{c&}. The execution commands that accept background execution 5714are: 5715 5716@table @code 5717@kindex run& 5718@item run 5719@xref{Starting, , Starting your Program}. 5720 5721@item attach 5722@kindex attach& 5723@xref{Attach, , Debugging an Already-running Process}. 5724 5725@item step 5726@kindex step& 5727@xref{Continuing and Stepping, step}. 5728 5729@item stepi 5730@kindex stepi& 5731@xref{Continuing and Stepping, stepi}. 5732 5733@item next 5734@kindex next& 5735@xref{Continuing and Stepping, next}. 5736 5737@item nexti 5738@kindex nexti& 5739@xref{Continuing and Stepping, nexti}. 5740 5741@item continue 5742@kindex continue& 5743@xref{Continuing and Stepping, continue}. 5744 5745@item finish 5746@kindex finish& 5747@xref{Continuing and Stepping, finish}. 5748 5749@item until 5750@kindex until& 5751@xref{Continuing and Stepping, until}. 5752 5753@end table 5754 5755Background execution is especially useful in conjunction with non-stop 5756mode for debugging programs with multiple threads; see @ref{Non-Stop Mode}. 5757However, you can also use these commands in the normal all-stop mode with 5758the restriction that you cannot issue another execution command until the 5759previous one finishes. Examples of commands that are valid in all-stop 5760mode while the program is running include @code{help} and @code{info break}. 5761 5762You can interrupt your program while it is running in the background by 5763using the @code{interrupt} command. 5764 5765@table @code 5766@kindex interrupt 5767@item interrupt 5768@itemx interrupt -a 5769 5770Suspend execution of the running program. In all-stop mode, 5771@code{interrupt} stops the whole process, but in non-stop mode, it stops 5772only the current thread. To stop the whole program in non-stop mode, 5773use @code{interrupt -a}. 5774@end table 5775 5776@node Thread-Specific Breakpoints 5777@subsection Thread-Specific Breakpoints 5778 5779When your program has multiple threads (@pxref{Threads,, Debugging 5780Programs with Multiple Threads}), you can choose whether to set 5781breakpoints on all threads, or on a particular thread. 5782 5783@table @code 5784@cindex breakpoints and threads 5785@cindex thread breakpoints 5786@kindex break @dots{} thread @var{threadno} 5787@item break @var{linespec} thread @var{threadno} 5788@itemx break @var{linespec} thread @var{threadno} if @dots{} 5789@var{linespec} specifies source lines; there are several ways of 5790writing them (@pxref{Specify Location}), but the effect is always to 5791specify some source line. 5792 5793Use the qualifier @samp{thread @var{threadno}} with a breakpoint command 5794to specify that you only want @value{GDBN} to stop the program when a 5795particular thread reaches this breakpoint. @var{threadno} is one of the 5796numeric thread identifiers assigned by @value{GDBN}, shown in the first 5797column of the @samp{info threads} display. 5798 5799If you do not specify @samp{thread @var{threadno}} when you set a 5800breakpoint, the breakpoint applies to @emph{all} threads of your 5801program. 5802 5803You can use the @code{thread} qualifier on conditional breakpoints as 5804well; in this case, place @samp{thread @var{threadno}} before or 5805after the breakpoint condition, like this: 5806 5807@smallexample 5808(@value{GDBP}) break frik.c:13 thread 28 if bartab > lim 5809@end smallexample 5810 5811@end table 5812 5813@node Interrupted System Calls 5814@subsection Interrupted System Calls 5815 5816@cindex thread breakpoints and system calls 5817@cindex system calls and thread breakpoints 5818@cindex premature return from system calls 5819There is an unfortunate side effect when using @value{GDBN} to debug 5820multi-threaded programs. If one thread stops for a 5821breakpoint, or for some other reason, and another thread is blocked in a 5822system call, then the system call may return prematurely. This is a 5823consequence of the interaction between multiple threads and the signals 5824that @value{GDBN} uses to implement breakpoints and other events that 5825stop execution. 5826 5827To handle this problem, your program should check the return value of 5828each system call and react appropriately. This is good programming 5829style anyways. 5830 5831For example, do not write code like this: 5832 5833@smallexample 5834 sleep (10); 5835@end smallexample 5836 5837The call to @code{sleep} will return early if a different thread stops 5838at a breakpoint or for some other reason. 5839 5840Instead, write this: 5841 5842@smallexample 5843 int unslept = 10; 5844 while (unslept > 0) 5845 unslept = sleep (unslept); 5846@end smallexample 5847 5848A system call is allowed to return early, so the system is still 5849conforming to its specification. But @value{GDBN} does cause your 5850multi-threaded program to behave differently than it would without 5851@value{GDBN}. 5852 5853Also, @value{GDBN} uses internal breakpoints in the thread library to 5854monitor certain events such as thread creation and thread destruction. 5855When such an event happens, a system call in another thread may return 5856prematurely, even though your program does not appear to stop. 5857 5858@node Observer Mode 5859@subsection Observer Mode 5860 5861If you want to build on non-stop mode and observe program behavior 5862without any chance of disruption by @value{GDBN}, you can set 5863variables to disable all of the debugger's attempts to modify state, 5864whether by writing memory, inserting breakpoints, etc. These operate 5865at a low level, intercepting operations from all commands. 5866 5867When all of these are set to @code{off}, then @value{GDBN} is said to 5868be @dfn{observer mode}. As a convenience, the variable 5869@code{observer} can be set to disable these, plus enable non-stop 5870mode. 5871 5872Note that @value{GDBN} will not prevent you from making nonsensical 5873combinations of these settings. For instance, if you have enabled 5874@code{may-insert-breakpoints} but disabled @code{may-write-memory}, 5875then breakpoints that work by writing trap instructions into the code 5876stream will still not be able to be placed. 5877 5878@table @code 5879 5880@kindex observer 5881@item set observer on 5882@itemx set observer off 5883When set to @code{on}, this disables all the permission variables 5884below (except for @code{insert-fast-tracepoints}), plus enables 5885non-stop debugging. Setting this to @code{off} switches back to 5886normal debugging, though remaining in non-stop mode. 5887 5888@item show observer 5889Show whether observer mode is on or off. 5890 5891@kindex may-write-registers 5892@item set may-write-registers on 5893@itemx set may-write-registers off 5894This controls whether @value{GDBN} will attempt to alter the values of 5895registers, such as with assignment expressions in @code{print}, or the 5896@code{jump} command. It defaults to @code{on}. 5897 5898@item show may-write-registers 5899Show the current permission to write registers. 5900 5901@kindex may-write-memory 5902@item set may-write-memory on 5903@itemx set may-write-memory off 5904This controls whether @value{GDBN} will attempt to alter the contents 5905of memory, such as with assignment expressions in @code{print}. It 5906defaults to @code{on}. 5907 5908@item show may-write-memory 5909Show the current permission to write memory. 5910 5911@kindex may-insert-breakpoints 5912@item set may-insert-breakpoints on 5913@itemx set may-insert-breakpoints off 5914This controls whether @value{GDBN} will attempt to insert breakpoints. 5915This affects all breakpoints, including internal breakpoints defined 5916by @value{GDBN}. It defaults to @code{on}. 5917 5918@item show may-insert-breakpoints 5919Show the current permission to insert breakpoints. 5920 5921@kindex may-insert-tracepoints 5922@item set may-insert-tracepoints on 5923@itemx set may-insert-tracepoints off 5924This controls whether @value{GDBN} will attempt to insert (regular) 5925tracepoints at the beginning of a tracing experiment. It affects only 5926non-fast tracepoints, fast tracepoints being under the control of 5927@code{may-insert-fast-tracepoints}. It defaults to @code{on}. 5928 5929@item show may-insert-tracepoints 5930Show the current permission to insert tracepoints. 5931 5932@kindex may-insert-fast-tracepoints 5933@item set may-insert-fast-tracepoints on 5934@itemx set may-insert-fast-tracepoints off 5935This controls whether @value{GDBN} will attempt to insert fast 5936tracepoints at the beginning of a tracing experiment. It affects only 5937fast tracepoints, regular (non-fast) tracepoints being under the 5938control of @code{may-insert-tracepoints}. It defaults to @code{on}. 5939 5940@item show may-insert-fast-tracepoints 5941Show the current permission to insert fast tracepoints. 5942 5943@kindex may-interrupt 5944@item set may-interrupt on 5945@itemx set may-interrupt off 5946This controls whether @value{GDBN} will attempt to interrupt or stop 5947program execution. When this variable is @code{off}, the 5948@code{interrupt} command will have no effect, nor will 5949@kbd{Ctrl-c}. It defaults to @code{on}. 5950 5951@item show may-interrupt 5952Show the current permission to interrupt or stop the program. 5953 5954@end table 5955 5956@node Reverse Execution 5957@chapter Running programs backward 5958@cindex reverse execution 5959@cindex running programs backward 5960 5961When you are debugging a program, it is not unusual to realize that 5962you have gone too far, and some event of interest has already happened. 5963If the target environment supports it, @value{GDBN} can allow you to 5964``rewind'' the program by running it backward. 5965 5966A target environment that supports reverse execution should be able 5967to ``undo'' the changes in machine state that have taken place as the 5968program was executing normally. Variables, registers etc.@: should 5969revert to their previous values. Obviously this requires a great 5970deal of sophistication on the part of the target environment; not 5971all target environments can support reverse execution. 5972 5973When a program is executed in reverse, the instructions that 5974have most recently been executed are ``un-executed'', in reverse 5975order. The program counter runs backward, following the previous 5976thread of execution in reverse. As each instruction is ``un-executed'', 5977the values of memory and/or registers that were changed by that 5978instruction are reverted to their previous states. After executing 5979a piece of source code in reverse, all side effects of that code 5980should be ``undone'', and all variables should be returned to their 5981prior values@footnote{ 5982Note that some side effects are easier to undo than others. For instance, 5983memory and registers are relatively easy, but device I/O is hard. Some 5984targets may be able undo things like device I/O, and some may not. 5985 5986The contract between @value{GDBN} and the reverse executing target 5987requires only that the target do something reasonable when 5988@value{GDBN} tells it to execute backwards, and then report the 5989results back to @value{GDBN}. Whatever the target reports back to 5990@value{GDBN}, @value{GDBN} will report back to the user. @value{GDBN} 5991assumes that the memory and registers that the target reports are in a 5992consistant state, but @value{GDBN} accepts whatever it is given. 5993}. 5994 5995If you are debugging in a target environment that supports 5996reverse execution, @value{GDBN} provides the following commands. 5997 5998@table @code 5999@kindex reverse-continue 6000@kindex rc @r{(@code{reverse-continue})} 6001@item reverse-continue @r{[}@var{ignore-count}@r{]} 6002@itemx rc @r{[}@var{ignore-count}@r{]} 6003Beginning at the point where your program last stopped, start executing 6004in reverse. Reverse execution will stop for breakpoints and synchronous 6005exceptions (signals), just like normal execution. Behavior of 6006asynchronous signals depends on the target environment. 6007 6008@kindex reverse-step 6009@kindex rs @r{(@code{step})} 6010@item reverse-step @r{[}@var{count}@r{]} 6011Run the program backward until control reaches the start of a 6012different source line; then stop it, and return control to @value{GDBN}. 6013 6014Like the @code{step} command, @code{reverse-step} will only stop 6015at the beginning of a source line. It ``un-executes'' the previously 6016executed source line. If the previous source line included calls to 6017debuggable functions, @code{reverse-step} will step (backward) into 6018the called function, stopping at the beginning of the @emph{last} 6019statement in the called function (typically a return statement). 6020 6021Also, as with the @code{step} command, if non-debuggable functions are 6022called, @code{reverse-step} will run thru them backward without stopping. 6023 6024@kindex reverse-stepi 6025@kindex rsi @r{(@code{reverse-stepi})} 6026@item reverse-stepi @r{[}@var{count}@r{]} 6027Reverse-execute one machine instruction. Note that the instruction 6028to be reverse-executed is @emph{not} the one pointed to by the program 6029counter, but the instruction executed prior to that one. For instance, 6030if the last instruction was a jump, @code{reverse-stepi} will take you 6031back from the destination of the jump to the jump instruction itself. 6032 6033@kindex reverse-next 6034@kindex rn @r{(@code{reverse-next})} 6035@item reverse-next @r{[}@var{count}@r{]} 6036Run backward to the beginning of the previous line executed in 6037the current (innermost) stack frame. If the line contains function 6038calls, they will be ``un-executed'' without stopping. Starting from 6039the first line of a function, @code{reverse-next} will take you back 6040to the caller of that function, @emph{before} the function was called, 6041just as the normal @code{next} command would take you from the last 6042line of a function back to its return to its caller 6043@footnote{Unless the code is too heavily optimized.}. 6044 6045@kindex reverse-nexti 6046@kindex rni @r{(@code{reverse-nexti})} 6047@item reverse-nexti @r{[}@var{count}@r{]} 6048Like @code{nexti}, @code{reverse-nexti} executes a single instruction 6049in reverse, except that called functions are ``un-executed'' atomically. 6050That is, if the previously executed instruction was a return from 6051another function, @code{reverse-nexti} will continue to execute 6052in reverse until the call to that function (from the current stack 6053frame) is reached. 6054 6055@kindex reverse-finish 6056@item reverse-finish 6057Just as the @code{finish} command takes you to the point where the 6058current function returns, @code{reverse-finish} takes you to the point 6059where it was called. Instead of ending up at the end of the current 6060function invocation, you end up at the beginning. 6061 6062@kindex set exec-direction 6063@item set exec-direction 6064Set the direction of target execution. 6065@item set exec-direction reverse 6066@cindex execute forward or backward in time 6067@value{GDBN} will perform all execution commands in reverse, until the 6068exec-direction mode is changed to ``forward''. Affected commands include 6069@code{step, stepi, next, nexti, continue, and finish}. The @code{return} 6070command cannot be used in reverse mode. 6071@item set exec-direction forward 6072@value{GDBN} will perform all execution commands in the normal fashion. 6073This is the default. 6074@end table 6075 6076 6077@node Process Record and Replay 6078@chapter Recording Inferior's Execution and Replaying It 6079@cindex process record and replay 6080@cindex recording inferior's execution and replaying it 6081 6082On some platforms, @value{GDBN} provides a special @dfn{process record 6083and replay} target that can record a log of the process execution, and 6084replay it later with both forward and reverse execution commands. 6085 6086@cindex replay mode 6087When this target is in use, if the execution log includes the record 6088for the next instruction, @value{GDBN} will debug in @dfn{replay 6089mode}. In the replay mode, the inferior does not really execute code 6090instructions. Instead, all the events that normally happen during 6091code execution are taken from the execution log. While code is not 6092really executed in replay mode, the values of registers (including the 6093program counter register) and the memory of the inferior are still 6094changed as they normally would. Their contents are taken from the 6095execution log. 6096 6097@cindex record mode 6098If the record for the next instruction is not in the execution log, 6099@value{GDBN} will debug in @dfn{record mode}. In this mode, the 6100inferior executes normally, and @value{GDBN} records the execution log 6101for future replay. 6102 6103The process record and replay target supports reverse execution 6104(@pxref{Reverse Execution}), even if the platform on which the 6105inferior runs does not. However, the reverse execution is limited in 6106this case by the range of the instructions recorded in the execution 6107log. In other words, reverse execution on platforms that don't 6108support it directly can only be done in the replay mode. 6109 6110When debugging in the reverse direction, @value{GDBN} will work in 6111replay mode as long as the execution log includes the record for the 6112previous instruction; otherwise, it will work in record mode, if the 6113platform supports reverse execution, or stop if not. 6114 6115For architecture environments that support process record and replay, 6116@value{GDBN} provides the following commands: 6117 6118@table @code 6119@kindex target record 6120@kindex target record-full 6121@kindex target record-btrace 6122@kindex record 6123@kindex record full 6124@kindex record btrace 6125@kindex rec 6126@kindex rec full 6127@kindex rec btrace 6128@item record @var{method} 6129This command starts the process record and replay target. The 6130recording method can be specified as parameter. Without a parameter 6131the command uses the @code{full} recording method. The following 6132recording methods are available: 6133 6134@table @code 6135@item full 6136Full record/replay recording using @value{GDBN}'s software record and 6137replay implementation. This method allows replaying and reverse 6138execution. 6139 6140@item btrace 6141Hardware-supported instruction recording. This method does not allow 6142replaying and reverse execution. 6143 6144This recording method may not be available on all processors. 6145@end table 6146 6147The process record and replay target can only debug a process that is 6148already running. Therefore, you need first to start the process with 6149the @kbd{run} or @kbd{start} commands, and then start the recording 6150with the @kbd{record @var{method}} command. 6151 6152Both @code{record @var{method}} and @code{rec @var{method}} are 6153aliases of @code{target record-@var{method}}. 6154 6155@cindex displaced stepping, and process record and replay 6156Displaced stepping (@pxref{Maintenance Commands,, displaced stepping}) 6157will be automatically disabled when process record and replay target 6158is started. That's because the process record and replay target 6159doesn't support displaced stepping. 6160 6161@cindex non-stop mode, and process record and replay 6162@cindex asynchronous execution, and process record and replay 6163If the inferior is in the non-stop mode (@pxref{Non-Stop Mode}) or in 6164the asynchronous execution mode (@pxref{Background Execution}), not 6165all recording methods are available. The @code{full} recording method 6166does not support these two modes. 6167 6168@kindex record stop 6169@kindex rec s 6170@item record stop 6171Stop the process record and replay target. When process record and 6172replay target stops, the entire execution log will be deleted and the 6173inferior will either be terminated, or will remain in its final state. 6174 6175When you stop the process record and replay target in record mode (at 6176the end of the execution log), the inferior will be stopped at the 6177next instruction that would have been recorded. In other words, if 6178you record for a while and then stop recording, the inferior process 6179will be left in the same state as if the recording never happened. 6180 6181On the other hand, if the process record and replay target is stopped 6182while in replay mode (that is, not at the end of the execution log, 6183but at some earlier point), the inferior process will become ``live'' 6184at that earlier state, and it will then be possible to continue the 6185usual ``live'' debugging of the process from that state. 6186 6187When the inferior process exits, or @value{GDBN} detaches from it, 6188process record and replay target will automatically stop itself. 6189 6190@kindex record save 6191@item record save @var{filename} 6192Save the execution log to a file @file{@var{filename}}. 6193Default filename is @file{gdb_record.@var{process_id}}, where 6194@var{process_id} is the process ID of the inferior. 6195 6196This command may not be available for all recording methods. 6197 6198@kindex record restore 6199@item record restore @var{filename} 6200Restore the execution log from a file @file{@var{filename}}. 6201File must have been created with @code{record save}. 6202 6203@kindex set record full 6204@item set record full insn-number-max @var{limit} 6205Set the limit of instructions to be recorded for the @code{full} 6206recording method. Default value is 200000. 6207 6208If @var{limit} is a positive number, then @value{GDBN} will start 6209deleting instructions from the log once the number of the record 6210instructions becomes greater than @var{limit}. For every new recorded 6211instruction, @value{GDBN} will delete the earliest recorded 6212instruction to keep the number of recorded instructions at the limit. 6213(Since deleting recorded instructions loses information, @value{GDBN} 6214lets you control what happens when the limit is reached, by means of 6215the @code{stop-at-limit} option, described below.) 6216 6217If @var{limit} is zero, @value{GDBN} will never delete recorded 6218instructions from the execution log. The number of recorded 6219instructions is unlimited in this case. 6220 6221@kindex show record full 6222@item show record full insn-number-max 6223Show the limit of instructions to be recorded with the @code{full} 6224recording method. 6225 6226@item set record full stop-at-limit 6227Control the behavior of the @code{full} recording method when the 6228number of recorded instructions reaches the limit. If ON (the 6229default), @value{GDBN} will stop when the limit is reached for the 6230first time and ask you whether you want to stop the inferior or 6231continue running it and recording the execution log. If you decide 6232to continue recording, each new recorded instruction will cause the 6233oldest one to be deleted. 6234 6235If this option is OFF, @value{GDBN} will automatically delete the 6236oldest record to make room for each new one, without asking. 6237 6238@item show record full stop-at-limit 6239Show the current setting of @code{stop-at-limit}. 6240 6241@item set record full memory-query 6242Control the behavior when @value{GDBN} is unable to record memory 6243changes caused by an instruction for the @code{full} recording method. 6244If ON, @value{GDBN} will query whether to stop the inferior in that 6245case. 6246 6247If this option is OFF (the default), @value{GDBN} will automatically 6248ignore the effect of such instructions on memory. Later, when 6249@value{GDBN} replays this execution log, it will mark the log of this 6250instruction as not accessible, and it will not affect the replay 6251results. 6252 6253@item show record full memory-query 6254Show the current setting of @code{memory-query}. 6255 6256@kindex info record 6257@item info record 6258Show various statistics about the recording depending on the recording 6259method: 6260 6261@table @code 6262@item full 6263For the @code{full} recording method, it shows the state of process 6264record and its in-memory execution log buffer, including: 6265 6266@itemize @bullet 6267@item 6268Whether in record mode or replay mode. 6269@item 6270Lowest recorded instruction number (counting from when the current execution log started recording instructions). 6271@item 6272Highest recorded instruction number. 6273@item 6274Current instruction about to be replayed (if in replay mode). 6275@item 6276Number of instructions contained in the execution log. 6277@item 6278Maximum number of instructions that may be contained in the execution log. 6279@end itemize 6280 6281@item btrace 6282For the @code{btrace} recording method, it shows the number of 6283instructions that have been recorded and the number of blocks of 6284sequential control-flow that is formed by the recorded instructions. 6285@end table 6286 6287@kindex record delete 6288@kindex rec del 6289@item record delete 6290When record target runs in replay mode (``in the past''), delete the 6291subsequent execution log and begin to record a new execution log starting 6292from the current address. This means you will abandon the previously 6293recorded ``future'' and begin recording a new ``future''. 6294 6295@kindex record instruction-history 6296@kindex rec instruction-history 6297@item record instruction-history 6298Disassembles instructions from the recorded execution log. By 6299default, ten instructions are disassembled. This can be changed using 6300the @code{set record instruction-history-size} command. Instructions 6301are printed in execution order. There are several ways to specify 6302what part of the execution log to disassemble: 6303 6304@table @code 6305@item record instruction-history @var{insn} 6306Disassembles ten instructions starting from instruction number 6307@var{insn}. 6308 6309@item record instruction-history @var{insn}, +/-@var{n} 6310Disassembles @var{n} instructions around instruction number 6311@var{insn}. If @var{n} is preceded with @code{+}, disassembles 6312@var{n} instructions after instruction number @var{insn}. If 6313@var{n} is preceded with @code{-}, disassembles @var{n} 6314instructions before instruction number @var{insn}. 6315 6316@item record instruction-history 6317Disassembles ten more instructions after the last disassembly. 6318 6319@item record instruction-history - 6320Disassembles ten more instructions before the last disassembly. 6321 6322@item record instruction-history @var{begin} @var{end} 6323Disassembles instructions beginning with instruction number 6324@var{begin} until instruction number @var{end}. The instruction 6325number @var{end} is not included. 6326@end table 6327 6328This command may not be available for all recording methods. 6329 6330@kindex set record 6331@item set record instruction-history-size 6332Define how many instructions to disassemble in the @code{record 6333instruction-history} command. The default value is 10. 6334 6335@kindex show record 6336@item show record instruction-history-size 6337Show how many instructions to disassemble in the @code{record 6338instruction-history} command. 6339 6340@kindex record function-call-history 6341@kindex rec function-call-history 6342@item record function-call-history 6343Prints the execution history at function granularity. It prints one 6344line for each sequence of instructions that belong to the same 6345function giving the name of that function, the source lines 6346for this instruction sequence (if the @code{/l} modifier is 6347specified), and the instructions numbers that form the sequence (if 6348the @code{/i} modifier is specified). 6349 6350@smallexample 6351(@value{GDBP}) @b{list 1, 10} 63521 void foo (void) 63532 @{ 63543 @} 63554 63565 void bar (void) 63576 @{ 63587 ... 63598 foo (); 63609 ... 636110 @} 6362(@value{GDBP}) @b{record function-call-history /l} 63631 foo.c:6-8 bar 63642 foo.c:2-3 foo 63653 foo.c:9-10 bar 6366@end smallexample 6367 6368By default, ten lines are printed. This can be changed using the 6369@code{set record function-call-history-size} command. Functions are 6370printed in execution order. There are several ways to specify what 6371to print: 6372 6373@table @code 6374@item record function-call-history @var{func} 6375Prints ten functions starting from function number @var{func}. 6376 6377@item record function-call-history @var{func}, +/-@var{n} 6378Prints @var{n} functions around function number @var{func}. If 6379@var{n} is preceded with @code{+}, prints @var{n} functions after 6380function number @var{func}. If @var{n} is preceded with @code{-}, 6381prints @var{n} functions before function number @var{func}. 6382 6383@item record function-call-history 6384Prints ten more functions after the last ten-line print. 6385 6386@item record function-call-history - 6387Prints ten more functions before the last ten-line print. 6388 6389@item record function-call-history @var{begin} @var{end} 6390Prints functions beginning with function number @var{begin} until 6391function number @var{end}. The function number @var{end} is not 6392included. 6393@end table 6394 6395This command may not be available for all recording methods. 6396 6397@item set record function-call-history-size 6398Define how many lines to print in the 6399@code{record function-call-history} command. The default value is 10. 6400 6401@item show record function-call-history-size 6402Show how many lines to print in the 6403@code{record function-call-history} command. 6404@end table 6405 6406 6407@node Stack 6408@chapter Examining the Stack 6409 6410When your program has stopped, the first thing you need to know is where it 6411stopped and how it got there. 6412 6413@cindex call stack 6414Each time your program performs a function call, information about the call 6415is generated. 6416That information includes the location of the call in your program, 6417the arguments of the call, 6418and the local variables of the function being called. 6419The information is saved in a block of data called a @dfn{stack frame}. 6420The stack frames are allocated in a region of memory called the @dfn{call 6421stack}. 6422 6423When your program stops, the @value{GDBN} commands for examining the 6424stack allow you to see all of this information. 6425 6426@cindex selected frame 6427One of the stack frames is @dfn{selected} by @value{GDBN} and many 6428@value{GDBN} commands refer implicitly to the selected frame. In 6429particular, whenever you ask @value{GDBN} for the value of a variable in 6430your program, the value is found in the selected frame. There are 6431special @value{GDBN} commands to select whichever frame you are 6432interested in. @xref{Selection, ,Selecting a Frame}. 6433 6434When your program stops, @value{GDBN} automatically selects the 6435currently executing frame and describes it briefly, similar to the 6436@code{frame} command (@pxref{Frame Info, ,Information about a Frame}). 6437 6438@menu 6439* Frames:: Stack frames 6440* Backtrace:: Backtraces 6441* Selection:: Selecting a frame 6442* Frame Info:: Information on a frame 6443 6444@end menu 6445 6446@node Frames 6447@section Stack Frames 6448 6449@cindex frame, definition 6450@cindex stack frame 6451The call stack is divided up into contiguous pieces called @dfn{stack 6452frames}, or @dfn{frames} for short; each frame is the data associated 6453with one call to one function. The frame contains the arguments given 6454to the function, the function's local variables, and the address at 6455which the function is executing. 6456 6457@cindex initial frame 6458@cindex outermost frame 6459@cindex innermost frame 6460When your program is started, the stack has only one frame, that of the 6461function @code{main}. This is called the @dfn{initial} frame or the 6462@dfn{outermost} frame. Each time a function is called, a new frame is 6463made. Each time a function returns, the frame for that function invocation 6464is eliminated. If a function is recursive, there can be many frames for 6465the same function. The frame for the function in which execution is 6466actually occurring is called the @dfn{innermost} frame. This is the most 6467recently created of all the stack frames that still exist. 6468 6469@cindex frame pointer 6470Inside your program, stack frames are identified by their addresses. A 6471stack frame consists of many bytes, each of which has its own address; each 6472kind of computer has a convention for choosing one byte whose 6473address serves as the address of the frame. Usually this address is kept 6474in a register called the @dfn{frame pointer register} 6475(@pxref{Registers, $fp}) while execution is going on in that frame. 6476 6477@cindex frame number 6478@value{GDBN} assigns numbers to all existing stack frames, starting with 6479zero for the innermost frame, one for the frame that called it, 6480and so on upward. These numbers do not really exist in your program; 6481they are assigned by @value{GDBN} to give you a way of designating stack 6482frames in @value{GDBN} commands. 6483 6484@c The -fomit-frame-pointer below perennially causes hbox overflow 6485@c underflow problems. 6486@cindex frameless execution 6487Some compilers provide a way to compile functions so that they operate 6488without stack frames. (For example, the @value{NGCC} option 6489@smallexample 6490@samp{-fomit-frame-pointer} 6491@end smallexample 6492generates functions without a frame.) 6493This is occasionally done with heavily used library functions to save 6494the frame setup time. @value{GDBN} has limited facilities for dealing 6495with these function invocations. If the innermost function invocation 6496has no stack frame, @value{GDBN} nevertheless regards it as though 6497it had a separate frame, which is numbered zero as usual, allowing 6498correct tracing of the function call chain. However, @value{GDBN} has 6499no provision for frameless functions elsewhere in the stack. 6500 6501@table @code 6502@kindex frame@r{, command} 6503@cindex current stack frame 6504@item frame @var{args} 6505The @code{frame} command allows you to move from one stack frame to another, 6506and to print the stack frame you select. @var{args} may be either the 6507address of the frame or the stack frame number. Without an argument, 6508@code{frame} prints the current stack frame. 6509 6510@kindex select-frame 6511@cindex selecting frame silently 6512@item select-frame 6513The @code{select-frame} command allows you to move from one stack frame 6514to another without printing the frame. This is the silent version of 6515@code{frame}. 6516@end table 6517 6518@node Backtrace 6519@section Backtraces 6520 6521@cindex traceback 6522@cindex call stack traces 6523A backtrace is a summary of how your program got where it is. It shows one 6524line per frame, for many frames, starting with the currently executing 6525frame (frame zero), followed by its caller (frame one), and on up the 6526stack. 6527 6528@table @code 6529@kindex backtrace 6530@kindex bt @r{(@code{backtrace})} 6531@item backtrace 6532@itemx bt 6533Print a backtrace of the entire stack: one line per frame for all 6534frames in the stack. 6535 6536You can stop the backtrace at any time by typing the system interrupt 6537character, normally @kbd{Ctrl-c}. 6538 6539@item backtrace @var{n} 6540@itemx bt @var{n} 6541Similar, but print only the innermost @var{n} frames. 6542 6543@item backtrace -@var{n} 6544@itemx bt -@var{n} 6545Similar, but print only the outermost @var{n} frames. 6546 6547@item backtrace full 6548@itemx bt full 6549@itemx bt full @var{n} 6550@itemx bt full -@var{n} 6551Print the values of the local variables also. @var{n} specifies the 6552number of frames to print, as described above. 6553@end table 6554 6555@kindex where 6556@kindex info stack 6557The names @code{where} and @code{info stack} (abbreviated @code{info s}) 6558are additional aliases for @code{backtrace}. 6559 6560@cindex multiple threads, backtrace 6561In a multi-threaded program, @value{GDBN} by default shows the 6562backtrace only for the current thread. To display the backtrace for 6563several or all of the threads, use the command @code{thread apply} 6564(@pxref{Threads, thread apply}). For example, if you type @kbd{thread 6565apply all backtrace}, @value{GDBN} will display the backtrace for all 6566the threads; this is handy when you debug a core dump of a 6567multi-threaded program. 6568 6569Each line in the backtrace shows the frame number and the function name. 6570The program counter value is also shown---unless you use @code{set 6571print address off}. The backtrace also shows the source file name and 6572line number, as well as the arguments to the function. The program 6573counter value is omitted if it is at the beginning of the code for that 6574line number. 6575 6576Here is an example of a backtrace. It was made with the command 6577@samp{bt 3}, so it shows the innermost three frames. 6578 6579@smallexample 6580@group 6581#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) 6582 at builtin.c:993 6583#1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242 6584#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) 6585 at macro.c:71 6586(More stack frames follow...) 6587@end group 6588@end smallexample 6589 6590@noindent 6591The display for frame zero does not begin with a program counter 6592value, indicating that your program has stopped at the beginning of the 6593code for line @code{993} of @code{builtin.c}. 6594 6595@noindent 6596The value of parameter @code{data} in frame 1 has been replaced by 6597@code{@dots{}}. By default, @value{GDBN} prints the value of a parameter 6598only if it is a scalar (integer, pointer, enumeration, etc). See command 6599@kbd{set print frame-arguments} in @ref{Print Settings} for more details 6600on how to configure the way function parameter values are printed. 6601 6602@cindex optimized out, in backtrace 6603@cindex function call arguments, optimized out 6604If your program was compiled with optimizations, some compilers will 6605optimize away arguments passed to functions if those arguments are 6606never used after the call. Such optimizations generate code that 6607passes arguments through registers, but doesn't store those arguments 6608in the stack frame. @value{GDBN} has no way of displaying such 6609arguments in stack frames other than the innermost one. Here's what 6610such a backtrace might look like: 6611 6612@smallexample 6613@group 6614#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) 6615 at builtin.c:993 6616#1 0x6e38 in expand_macro (sym=<optimized out>) at macro.c:242 6617#2 0x6840 in expand_token (obs=0x0, t=<optimized out>, td=0xf7fffb08) 6618 at macro.c:71 6619(More stack frames follow...) 6620@end group 6621@end smallexample 6622 6623@noindent 6624The values of arguments that were not saved in their stack frames are 6625shown as @samp{<optimized out>}. 6626 6627If you need to display the values of such optimized-out arguments, 6628either deduce that from other variables whose values depend on the one 6629you are interested in, or recompile without optimizations. 6630 6631@cindex backtrace beyond @code{main} function 6632@cindex program entry point 6633@cindex startup code, and backtrace 6634Most programs have a standard user entry point---a place where system 6635libraries and startup code transition into user code. For C this is 6636@code{main}@footnote{ 6637Note that embedded programs (the so-called ``free-standing'' 6638environment) are not required to have a @code{main} function as the 6639entry point. They could even have multiple entry points.}. 6640When @value{GDBN} finds the entry function in a backtrace 6641it will terminate the backtrace, to avoid tracing into highly 6642system-specific (and generally uninteresting) code. 6643 6644If you need to examine the startup code, or limit the number of levels 6645in a backtrace, you can change this behavior: 6646 6647@table @code 6648@item set backtrace past-main 6649@itemx set backtrace past-main on 6650@kindex set backtrace 6651Backtraces will continue past the user entry point. 6652 6653@item set backtrace past-main off 6654Backtraces will stop when they encounter the user entry point. This is the 6655default. 6656 6657@item show backtrace past-main 6658@kindex show backtrace 6659Display the current user entry point backtrace policy. 6660 6661@item set backtrace past-entry 6662@itemx set backtrace past-entry on 6663Backtraces will continue past the internal entry point of an application. 6664This entry point is encoded by the linker when the application is built, 6665and is likely before the user entry point @code{main} (or equivalent) is called. 6666 6667@item set backtrace past-entry off 6668Backtraces will stop when they encounter the internal entry point of an 6669application. This is the default. 6670 6671@item show backtrace past-entry 6672Display the current internal entry point backtrace policy. 6673 6674@item set backtrace limit @var{n} 6675@itemx set backtrace limit 0 6676@cindex backtrace limit 6677Limit the backtrace to @var{n} levels. A value of zero means 6678unlimited. 6679 6680@item show backtrace limit 6681Display the current limit on backtrace levels. 6682@end table 6683 6684You can control how file names are displayed. 6685 6686@table @code 6687@item set filename-display 6688@itemx set filename-display relative 6689@cindex filename-display 6690Display file names relative to the compilation directory. This is the default. 6691 6692@item set filename-display basename 6693Display only basename of a filename. 6694 6695@item set filename-display absolute 6696Display an absolute filename. 6697 6698@item show filename-display 6699Show the current way to display filenames. 6700@end table 6701 6702@node Selection 6703@section Selecting a Frame 6704 6705Most commands for examining the stack and other data in your program work on 6706whichever stack frame is selected at the moment. Here are the commands for 6707selecting a stack frame; all of them finish by printing a brief description 6708of the stack frame just selected. 6709 6710@table @code 6711@kindex frame@r{, selecting} 6712@kindex f @r{(@code{frame})} 6713@item frame @var{n} 6714@itemx f @var{n} 6715Select frame number @var{n}. Recall that frame zero is the innermost 6716(currently executing) frame, frame one is the frame that called the 6717innermost one, and so on. The highest-numbered frame is the one for 6718@code{main}. 6719 6720@item frame @var{addr} 6721@itemx f @var{addr} 6722Select the frame at address @var{addr}. This is useful mainly if the 6723chaining of stack frames has been damaged by a bug, making it 6724impossible for @value{GDBN} to assign numbers properly to all frames. In 6725addition, this can be useful when your program has multiple stacks and 6726switches between them. 6727 6728On the SPARC architecture, @code{frame} needs two addresses to 6729select an arbitrary frame: a frame pointer and a stack pointer. 6730 6731On the @acronym{MIPS} and Alpha architecture, it needs two addresses: a stack 6732pointer and a program counter. 6733 6734On the 29k architecture, it needs three addresses: a register stack 6735pointer, a program counter, and a memory stack pointer. 6736 6737@kindex up 6738@item up @var{n} 6739Move @var{n} frames up the stack. For positive numbers @var{n}, this 6740advances toward the outermost frame, to higher frame numbers, to frames 6741that have existed longer. @var{n} defaults to one. 6742 6743@kindex down 6744@kindex do @r{(@code{down})} 6745@item down @var{n} 6746Move @var{n} frames down the stack. For positive numbers @var{n}, this 6747advances toward the innermost frame, to lower frame numbers, to frames 6748that were created more recently. @var{n} defaults to one. You may 6749abbreviate @code{down} as @code{do}. 6750@end table 6751 6752All of these commands end by printing two lines of output describing the 6753frame. The first line shows the frame number, the function name, the 6754arguments, and the source file and line number of execution in that 6755frame. The second line shows the text of that source line. 6756 6757@need 1000 6758For example: 6759 6760@smallexample 6761@group 6762(@value{GDBP}) up 6763#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) 6764 at env.c:10 676510 read_input_file (argv[i]); 6766@end group 6767@end smallexample 6768 6769After such a printout, the @code{list} command with no arguments 6770prints ten lines centered on the point of execution in the frame. 6771You can also edit the program at the point of execution with your favorite 6772editing program by typing @code{edit}. 6773@xref{List, ,Printing Source Lines}, 6774for details. 6775 6776@table @code 6777@kindex down-silently 6778@kindex up-silently 6779@item up-silently @var{n} 6780@itemx down-silently @var{n} 6781These two commands are variants of @code{up} and @code{down}, 6782respectively; they differ in that they do their work silently, without 6783causing display of the new frame. They are intended primarily for use 6784in @value{GDBN} command scripts, where the output might be unnecessary and 6785distracting. 6786@end table 6787 6788@node Frame Info 6789@section Information About a Frame 6790 6791There are several other commands to print information about the selected 6792stack frame. 6793 6794@table @code 6795@item frame 6796@itemx f 6797When used without any argument, this command does not change which 6798frame is selected, but prints a brief description of the currently 6799selected stack frame. It can be abbreviated @code{f}. With an 6800argument, this command is used to select a stack frame. 6801@xref{Selection, ,Selecting a Frame}. 6802 6803@kindex info frame 6804@kindex info f @r{(@code{info frame})} 6805@item info frame 6806@itemx info f 6807This command prints a verbose description of the selected stack frame, 6808including: 6809 6810@itemize @bullet 6811@item 6812the address of the frame 6813@item 6814the address of the next frame down (called by this frame) 6815@item 6816the address of the next frame up (caller of this frame) 6817@item 6818the language in which the source code corresponding to this frame is written 6819@item 6820the address of the frame's arguments 6821@item 6822the address of the frame's local variables 6823@item 6824the program counter saved in it (the address of execution in the caller frame) 6825@item 6826which registers were saved in the frame 6827@end itemize 6828 6829@noindent The verbose description is useful when 6830something has gone wrong that has made the stack format fail to fit 6831the usual conventions. 6832 6833@item info frame @var{addr} 6834@itemx info f @var{addr} 6835Print a verbose description of the frame at address @var{addr}, without 6836selecting that frame. The selected frame remains unchanged by this 6837command. This requires the same kind of address (more than one for some 6838architectures) that you specify in the @code{frame} command. 6839@xref{Selection, ,Selecting a Frame}. 6840 6841@kindex info args 6842@item info args 6843Print the arguments of the selected frame, each on a separate line. 6844 6845@item info locals 6846@kindex info locals 6847Print the local variables of the selected frame, each on a separate 6848line. These are all variables (declared either static or automatic) 6849accessible at the point of execution of the selected frame. 6850 6851@end table 6852 6853 6854@node Source 6855@chapter Examining Source Files 6856 6857@value{GDBN} can print parts of your program's source, since the debugging 6858information recorded in the program tells @value{GDBN} what source files were 6859used to build it. When your program stops, @value{GDBN} spontaneously prints 6860the line where it stopped. Likewise, when you select a stack frame 6861(@pxref{Selection, ,Selecting a Frame}), @value{GDBN} prints the line where 6862execution in that frame has stopped. You can print other portions of 6863source files by explicit command. 6864 6865If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may 6866prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using 6867@value{GDBN} under @sc{gnu} Emacs}. 6868 6869@menu 6870* List:: Printing source lines 6871* Specify Location:: How to specify code locations 6872* Edit:: Editing source files 6873* Search:: Searching source files 6874* Source Path:: Specifying source directories 6875* Machine Code:: Source and machine code 6876@end menu 6877 6878@node List 6879@section Printing Source Lines 6880 6881@kindex list 6882@kindex l @r{(@code{list})} 6883To print lines from a source file, use the @code{list} command 6884(abbreviated @code{l}). By default, ten lines are printed. 6885There are several ways to specify what part of the file you want to 6886print; see @ref{Specify Location}, for the full list. 6887 6888Here are the forms of the @code{list} command most commonly used: 6889 6890@table @code 6891@item list @var{linenum} 6892Print lines centered around line number @var{linenum} in the 6893current source file. 6894 6895@item list @var{function} 6896Print lines centered around the beginning of function 6897@var{function}. 6898 6899@item list 6900Print more lines. If the last lines printed were printed with a 6901@code{list} command, this prints lines following the last lines 6902printed; however, if the last line printed was a solitary line printed 6903as part of displaying a stack frame (@pxref{Stack, ,Examining the 6904Stack}), this prints lines centered around that line. 6905 6906@item list - 6907Print lines just before the lines last printed. 6908@end table 6909 6910@cindex @code{list}, how many lines to display 6911By default, @value{GDBN} prints ten source lines with any of these forms of 6912the @code{list} command. You can change this using @code{set listsize}: 6913 6914@table @code 6915@kindex set listsize 6916@item set listsize @var{count} 6917Make the @code{list} command display @var{count} source lines (unless 6918the @code{list} argument explicitly specifies some other number). 6919Setting @var{count} to 0 means there's no limit. 6920 6921@kindex show listsize 6922@item show listsize 6923Display the number of lines that @code{list} prints. 6924@end table 6925 6926Repeating a @code{list} command with @key{RET} discards the argument, 6927so it is equivalent to typing just @code{list}. This is more useful 6928than listing the same lines again. An exception is made for an 6929argument of @samp{-}; that argument is preserved in repetition so that 6930each repetition moves up in the source file. 6931 6932In general, the @code{list} command expects you to supply zero, one or two 6933@dfn{linespecs}. Linespecs specify source lines; there are several ways 6934of writing them (@pxref{Specify Location}), but the effect is always 6935to specify some source line. 6936 6937Here is a complete description of the possible arguments for @code{list}: 6938 6939@table @code 6940@item list @var{linespec} 6941Print lines centered around the line specified by @var{linespec}. 6942 6943@item list @var{first},@var{last} 6944Print lines from @var{first} to @var{last}. Both arguments are 6945linespecs. When a @code{list} command has two linespecs, and the 6946source file of the second linespec is omitted, this refers to 6947the same source file as the first linespec. 6948 6949@item list ,@var{last} 6950Print lines ending with @var{last}. 6951 6952@item list @var{first}, 6953Print lines starting with @var{first}. 6954 6955@item list + 6956Print lines just after the lines last printed. 6957 6958@item list - 6959Print lines just before the lines last printed. 6960 6961@item list 6962As described in the preceding table. 6963@end table 6964 6965@node Specify Location 6966@section Specifying a Location 6967@cindex specifying location 6968@cindex linespec 6969 6970Several @value{GDBN} commands accept arguments that specify a location 6971of your program's code. Since @value{GDBN} is a source-level 6972debugger, a location usually specifies some line in the source code; 6973for that reason, locations are also known as @dfn{linespecs}. 6974 6975Here are all the different ways of specifying a code location that 6976@value{GDBN} understands: 6977 6978@table @code 6979@item @var{linenum} 6980Specifies the line number @var{linenum} of the current source file. 6981 6982@item -@var{offset} 6983@itemx +@var{offset} 6984Specifies the line @var{offset} lines before or after the @dfn{current 6985line}. For the @code{list} command, the current line is the last one 6986printed; for the breakpoint commands, this is the line at which 6987execution stopped in the currently selected @dfn{stack frame} 6988(@pxref{Frames, ,Frames}, for a description of stack frames.) When 6989used as the second of the two linespecs in a @code{list} command, 6990this specifies the line @var{offset} lines up or down from the first 6991linespec. 6992 6993@item @var{filename}:@var{linenum} 6994Specifies the line @var{linenum} in the source file @var{filename}. 6995If @var{filename} is a relative file name, then it will match any 6996source file name with the same trailing components. For example, if 6997@var{filename} is @samp{gcc/expr.c}, then it will match source file 6998name of @file{/build/trunk/gcc/expr.c}, but not 6999@file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}. 7000 7001@item @var{function} 7002Specifies the line that begins the body of the function @var{function}. 7003For example, in C, this is the line with the open brace. 7004 7005@item @var{function}:@var{label} 7006Specifies the line where @var{label} appears in @var{function}. 7007 7008@item @var{filename}:@var{function} 7009Specifies the line that begins the body of the function @var{function} 7010in the file @var{filename}. You only need the file name with a 7011function name to avoid ambiguity when there are identically named 7012functions in different source files. 7013 7014@item @var{label} 7015Specifies the line at which the label named @var{label} appears. 7016@value{GDBN} searches for the label in the function corresponding to 7017the currently selected stack frame. If there is no current selected 7018stack frame (for instance, if the inferior is not running), then 7019@value{GDBN} will not search for a label. 7020 7021@item *@var{address} 7022Specifies the program address @var{address}. For line-oriented 7023commands, such as @code{list} and @code{edit}, this specifies a source 7024line that contains @var{address}. For @code{break} and other 7025breakpoint oriented commands, this can be used to set breakpoints in 7026parts of your program which do not have debugging information or 7027source files. 7028 7029Here @var{address} may be any expression valid in the current working 7030language (@pxref{Languages, working language}) that specifies a code 7031address. In addition, as a convenience, @value{GDBN} extends the 7032semantics of expressions used in locations to cover the situations 7033that frequently happen during debugging. Here are the various forms 7034of @var{address}: 7035 7036@table @code 7037@item @var{expression} 7038Any expression valid in the current working language. 7039 7040@item @var{funcaddr} 7041An address of a function or procedure derived from its name. In C, 7042C@t{++}, Java, Objective-C, Fortran, minimal, and assembly, this is 7043simply the function's name @var{function} (and actually a special case 7044of a valid expression). In Pascal and Modula-2, this is 7045@code{&@var{function}}. In Ada, this is @code{@var{function}'Address} 7046(although the Pascal form also works). 7047 7048This form specifies the address of the function's first instruction, 7049before the stack frame and arguments have been set up. 7050 7051@item '@var{filename}'::@var{funcaddr} 7052Like @var{funcaddr} above, but also specifies the name of the source 7053file explicitly. This is useful if the name of the function does not 7054specify the function unambiguously, e.g., if there are several 7055functions with identical names in different source files. 7056@end table 7057 7058@cindex breakpoint at static probe point 7059@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name} 7060The @sc{gnu}/Linux tool @code{SystemTap} provides a way for 7061applications to embed static probes. @xref{Static Probe Points}, for more 7062information on finding and using static probes. This form of linespec 7063specifies the location of such a static probe. 7064 7065If @var{objfile} is given, only probes coming from that shared library 7066or executable matching @var{objfile} as a regular expression are considered. 7067If @var{provider} is given, then only probes from that provider are considered. 7068If several probes match the spec, @value{GDBN} will insert a breakpoint at 7069each one of those probes. 7070 7071@end table 7072 7073 7074@node Edit 7075@section Editing Source Files 7076@cindex editing source files 7077 7078@kindex edit 7079@kindex e @r{(@code{edit})} 7080To edit the lines in a source file, use the @code{edit} command. 7081The editing program of your choice 7082is invoked with the current line set to 7083the active line in the program. 7084Alternatively, there are several ways to specify what part of the file you 7085want to print if you want to see other parts of the program: 7086 7087@table @code 7088@item edit @var{location} 7089Edit the source file specified by @code{location}. Editing starts at 7090that @var{location}, e.g., at the specified source line of the 7091specified file. @xref{Specify Location}, for all the possible forms 7092of the @var{location} argument; here are the forms of the @code{edit} 7093command most commonly used: 7094 7095@table @code 7096@item edit @var{number} 7097Edit the current source file with @var{number} as the active line number. 7098 7099@item edit @var{function} 7100Edit the file containing @var{function} at the beginning of its definition. 7101@end table 7102 7103@end table 7104 7105@subsection Choosing your Editor 7106You can customize @value{GDBN} to use any editor you want 7107@footnote{ 7108The only restriction is that your editor (say @code{ex}), recognizes the 7109following command-line syntax: 7110@smallexample 7111ex +@var{number} file 7112@end smallexample 7113The optional numeric value +@var{number} specifies the number of the line in 7114the file where to start editing.}. 7115By default, it is @file{@value{EDITOR}}, but you can change this 7116by setting the environment variable @code{EDITOR} before using 7117@value{GDBN}. For example, to configure @value{GDBN} to use the 7118@code{vi} editor, you could use these commands with the @code{sh} shell: 7119@smallexample 7120EDITOR=/usr/bin/vi 7121export EDITOR 7122gdb @dots{} 7123@end smallexample 7124or in the @code{csh} shell, 7125@smallexample 7126setenv EDITOR /usr/bin/vi 7127gdb @dots{} 7128@end smallexample 7129 7130@node Search 7131@section Searching Source Files 7132@cindex searching source files 7133 7134There are two commands for searching through the current source file for a 7135regular expression. 7136 7137@table @code 7138@kindex search 7139@kindex forward-search 7140@kindex fo @r{(@code{forward-search})} 7141@item forward-search @var{regexp} 7142@itemx search @var{regexp} 7143The command @samp{forward-search @var{regexp}} checks each line, 7144starting with the one following the last line listed, for a match for 7145@var{regexp}. It lists the line that is found. You can use the 7146synonym @samp{search @var{regexp}} or abbreviate the command name as 7147@code{fo}. 7148 7149@kindex reverse-search 7150@item reverse-search @var{regexp} 7151The command @samp{reverse-search @var{regexp}} checks each line, starting 7152with the one before the last line listed and going backward, for a match 7153for @var{regexp}. It lists the line that is found. You can abbreviate 7154this command as @code{rev}. 7155@end table 7156 7157@node Source Path 7158@section Specifying Source Directories 7159 7160@cindex source path 7161@cindex directories for source files 7162Executable programs sometimes do not record the directories of the source 7163files from which they were compiled, just the names. Even when they do, 7164the directories could be moved between the compilation and your debugging 7165session. @value{GDBN} has a list of directories to search for source files; 7166this is called the @dfn{source path}. Each time @value{GDBN} wants a source file, 7167it tries all the directories in the list, in the order they are present 7168in the list, until it finds a file with the desired name. 7169 7170For example, suppose an executable references the file 7171@file{/usr/src/foo-1.0/lib/foo.c}, and our source path is 7172@file{/mnt/cross}. The file is first looked up literally; if this 7173fails, @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} is tried; if this 7174fails, @file{/mnt/cross/foo.c} is opened; if this fails, an error 7175message is printed. @value{GDBN} does not look up the parts of the 7176source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}. 7177Likewise, the subdirectories of the source path are not searched: if 7178the source path is @file{/mnt/cross}, and the binary refers to 7179@file{foo.c}, @value{GDBN} would not find it under 7180@file{/mnt/cross/usr/src/foo-1.0/lib}. 7181 7182Plain file names, relative file names with leading directories, file 7183names containing dots, etc.@: are all treated as described above; for 7184instance, if the source path is @file{/mnt/cross}, and the source file 7185is recorded as @file{../lib/foo.c}, @value{GDBN} would first try 7186@file{../lib/foo.c}, then @file{/mnt/cross/../lib/foo.c}, and after 7187that---@file{/mnt/cross/foo.c}. 7188 7189Note that the executable search path is @emph{not} used to locate the 7190source files. 7191 7192Whenever you reset or rearrange the source path, @value{GDBN} clears out 7193any information it has cached about where source files are found and where 7194each line is in the file. 7195 7196@kindex directory 7197@kindex dir 7198When you start @value{GDBN}, its source path includes only @samp{cdir} 7199and @samp{cwd}, in that order. 7200To add other directories, use the @code{directory} command. 7201 7202The search path is used to find both program source files and @value{GDBN} 7203script files (read using the @samp{-command} option and @samp{source} command). 7204 7205In addition to the source path, @value{GDBN} provides a set of commands 7206that manage a list of source path substitution rules. A @dfn{substitution 7207rule} specifies how to rewrite source directories stored in the program's 7208debug information in case the sources were moved to a different 7209directory between compilation and debugging. A rule is made of 7210two strings, the first specifying what needs to be rewritten in 7211the path, and the second specifying how it should be rewritten. 7212In @ref{set substitute-path}, we name these two parts @var{from} and 7213@var{to} respectively. @value{GDBN} does a simple string replacement 7214of @var{from} with @var{to} at the start of the directory part of the 7215source file name, and uses that result instead of the original file 7216name to look up the sources. 7217 7218Using the previous example, suppose the @file{foo-1.0} tree has been 7219moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell 7220@value{GDBN} to replace @file{/usr/src} in all source path names with 7221@file{/mnt/cross}. The first lookup will then be 7222@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location 7223of @file{/usr/src/foo-1.0/lib/foo.c}. To define a source path 7224substitution rule, use the @code{set substitute-path} command 7225(@pxref{set substitute-path}). 7226 7227To avoid unexpected substitution results, a rule is applied only if the 7228@var{from} part of the directory name ends at a directory separator. 7229For instance, a rule substituting @file{/usr/source} into 7230@file{/mnt/cross} will be applied to @file{/usr/source/foo-1.0} but 7231not to @file{/usr/sourceware/foo-2.0}. And because the substitution 7232is applied only at the beginning of the directory name, this rule will 7233not be applied to @file{/root/usr/source/baz.c} either. 7234 7235In many cases, you can achieve the same result using the @code{directory} 7236command. However, @code{set substitute-path} can be more efficient in 7237the case where the sources are organized in a complex tree with multiple 7238subdirectories. With the @code{directory} command, you need to add each 7239subdirectory of your project. If you moved the entire tree while 7240preserving its internal organization, then @code{set substitute-path} 7241allows you to direct the debugger to all the sources with one single 7242command. 7243 7244@code{set substitute-path} is also more than just a shortcut command. 7245The source path is only used if the file at the original location no 7246longer exists. On the other hand, @code{set substitute-path} modifies 7247the debugger behavior to look at the rewritten location instead. So, if 7248for any reason a source file that is not relevant to your executable is 7249located at the original location, a substitution rule is the only 7250method available to point @value{GDBN} at the new location. 7251 7252@cindex @samp{--with-relocated-sources} 7253@cindex default source path substitution 7254You can configure a default source path substitution rule by 7255configuring @value{GDBN} with the 7256@samp{--with-relocated-sources=@var{dir}} option. The @var{dir} 7257should be the name of a directory under @value{GDBN}'s configured 7258prefix (set with @samp{--prefix} or @samp{--exec-prefix}), and 7259directory names in debug information under @var{dir} will be adjusted 7260automatically if the installed @value{GDBN} is moved to a new 7261location. This is useful if @value{GDBN}, libraries or executables 7262with debug information and corresponding source code are being moved 7263together. 7264 7265@table @code 7266@item directory @var{dirname} @dots{} 7267@item dir @var{dirname} @dots{} 7268Add directory @var{dirname} to the front of the source path. Several 7269directory names may be given to this command, separated by @samp{:} 7270(@samp{;} on MS-DOS and MS-Windows, where @samp{:} usually appears as 7271part of absolute file names) or 7272whitespace. You may specify a directory that is already in the source 7273path; this moves it forward, so @value{GDBN} searches it sooner. 7274 7275@kindex cdir 7276@kindex cwd 7277@vindex $cdir@r{, convenience variable} 7278@vindex $cwd@r{, convenience variable} 7279@cindex compilation directory 7280@cindex current directory 7281@cindex working directory 7282@cindex directory, current 7283@cindex directory, compilation 7284You can use the string @samp{$cdir} to refer to the compilation 7285directory (if one is recorded), and @samp{$cwd} to refer to the current 7286working directory. @samp{$cwd} is not the same as @samp{.}---the former 7287tracks the current working directory as it changes during your @value{GDBN} 7288session, while the latter is immediately expanded to the current 7289directory at the time you add an entry to the source path. 7290 7291@item directory 7292Reset the source path to its default value (@samp{$cdir:$cwd} on Unix systems). This requires confirmation. 7293 7294@c RET-repeat for @code{directory} is explicitly disabled, but since 7295@c repeating it would be a no-op we do not say that. (thanks to RMS) 7296 7297@item set directories @var{path-list} 7298@kindex set directories 7299Set the source path to @var{path-list}. 7300@samp{$cdir:$cwd} are added if missing. 7301 7302@item show directories 7303@kindex show directories 7304Print the source path: show which directories it contains. 7305 7306@anchor{set substitute-path} 7307@item set substitute-path @var{from} @var{to} 7308@kindex set substitute-path 7309Define a source path substitution rule, and add it at the end of the 7310current list of existing substitution rules. If a rule with the same 7311@var{from} was already defined, then the old rule is also deleted. 7312 7313For example, if the file @file{/foo/bar/baz.c} was moved to 7314@file{/mnt/cross/baz.c}, then the command 7315 7316@smallexample 7317(@value{GDBP}) set substitute-path /usr/src /mnt/cross 7318@end smallexample 7319 7320@noindent 7321will tell @value{GDBN} to replace @samp{/usr/src} with 7322@samp{/mnt/cross}, which will allow @value{GDBN} to find the file 7323@file{baz.c} even though it was moved. 7324 7325In the case when more than one substitution rule have been defined, 7326the rules are evaluated one by one in the order where they have been 7327defined. The first one matching, if any, is selected to perform 7328the substitution. 7329 7330For instance, if we had entered the following commands: 7331 7332@smallexample 7333(@value{GDBP}) set substitute-path /usr/src/include /mnt/include 7334(@value{GDBP}) set substitute-path /usr/src /mnt/src 7335@end smallexample 7336 7337@noindent 7338@value{GDBN} would then rewrite @file{/usr/src/include/defs.h} into 7339@file{/mnt/include/defs.h} by using the first rule. However, it would 7340use the second rule to rewrite @file{/usr/src/lib/foo.c} into 7341@file{/mnt/src/lib/foo.c}. 7342 7343 7344@item unset substitute-path [path] 7345@kindex unset substitute-path 7346If a path is specified, search the current list of substitution rules 7347for a rule that would rewrite that path. Delete that rule if found. 7348A warning is emitted by the debugger if no rule could be found. 7349 7350If no path is specified, then all substitution rules are deleted. 7351 7352@item show substitute-path [path] 7353@kindex show substitute-path 7354If a path is specified, then print the source path substitution rule 7355which would rewrite that path, if any. 7356 7357If no path is specified, then print all existing source path substitution 7358rules. 7359 7360@end table 7361 7362If your source path is cluttered with directories that are no longer of 7363interest, @value{GDBN} may sometimes cause confusion by finding the wrong 7364versions of source. You can correct the situation as follows: 7365 7366@enumerate 7367@item 7368Use @code{directory} with no argument to reset the source path to its default value. 7369 7370@item 7371Use @code{directory} with suitable arguments to reinstall the 7372directories you want in the source path. You can add all the 7373directories in one command. 7374@end enumerate 7375 7376@node Machine Code 7377@section Source and Machine Code 7378@cindex source line and its code address 7379 7380You can use the command @code{info line} to map source lines to program 7381addresses (and vice versa), and the command @code{disassemble} to display 7382a range of addresses as machine instructions. You can use the command 7383@code{set disassemble-next-line} to set whether to disassemble next 7384source line when execution stops. When run under @sc{gnu} Emacs 7385mode, the @code{info line} command causes the arrow to point to the 7386line specified. Also, @code{info line} prints addresses in symbolic form as 7387well as hex. 7388 7389@table @code 7390@kindex info line 7391@item info line @var{linespec} 7392Print the starting and ending addresses of the compiled code for 7393source line @var{linespec}. You can specify source lines in any of 7394the ways documented in @ref{Specify Location}. 7395@end table 7396 7397For example, we can use @code{info line} to discover the location of 7398the object code for the first line of function 7399@code{m4_changequote}: 7400 7401@c FIXME: I think this example should also show the addresses in 7402@c symbolic form, as they usually would be displayed. 7403@smallexample 7404(@value{GDBP}) info line m4_changequote 7405Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. 7406@end smallexample 7407 7408@noindent 7409@cindex code address and its source line 7410We can also inquire (using @code{*@var{addr}} as the form for 7411@var{linespec}) what source line covers a particular address: 7412@smallexample 7413(@value{GDBP}) info line *0x63ff 7414Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. 7415@end smallexample 7416 7417@cindex @code{$_} and @code{info line} 7418@cindex @code{x} command, default address 7419@kindex x@r{(examine), and} info line 7420After @code{info line}, the default address for the @code{x} command 7421is changed to the starting address of the line, so that @samp{x/i} is 7422sufficient to begin examining the machine code (@pxref{Memory, 7423,Examining Memory}). Also, this address is saved as the value of the 7424convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience 7425Variables}). 7426 7427@table @code 7428@kindex disassemble 7429@cindex assembly instructions 7430@cindex instructions, assembly 7431@cindex machine instructions 7432@cindex listing machine instructions 7433@item disassemble 7434@itemx disassemble /m 7435@itemx disassemble /r 7436This specialized command dumps a range of memory as machine 7437instructions. It can also print mixed source+disassembly by specifying 7438the @code{/m} modifier and print the raw instructions in hex as well as 7439in symbolic form by specifying the @code{/r}. 7440The default memory range is the function surrounding the 7441program counter of the selected frame. A single argument to this 7442command is a program counter value; @value{GDBN} dumps the function 7443surrounding this value. When two arguments are given, they should 7444be separated by a comma, possibly surrounded by whitespace. The 7445arguments specify a range of addresses to dump, in one of two forms: 7446 7447@table @code 7448@item @var{start},@var{end} 7449the addresses from @var{start} (inclusive) to @var{end} (exclusive) 7450@item @var{start},+@var{length} 7451the addresses from @var{start} (inclusive) to 7452@code{@var{start}+@var{length}} (exclusive). 7453@end table 7454 7455@noindent 7456When 2 arguments are specified, the name of the function is also 7457printed (since there could be several functions in the given range). 7458 7459The argument(s) can be any expression yielding a numeric value, such as 7460@samp{0x32c4}, @samp{&main+10} or @samp{$pc - 8}. 7461 7462If the range of memory being disassembled contains current program counter, 7463the instruction at that location is shown with a @code{=>} marker. 7464@end table 7465 7466The following example shows the disassembly of a range of addresses of 7467HP PA-RISC 2.0 code: 7468 7469@smallexample 7470(@value{GDBP}) disas 0x32c4, 0x32e4 7471Dump of assembler code from 0x32c4 to 0x32e4: 7472 0x32c4 <main+204>: addil 0,dp 7473 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 7474 0x32cc <main+212>: ldil 0x3000,r31 7475 0x32d0 <main+216>: ble 0x3f8(sr4,r31) 7476 0x32d4 <main+220>: ldo 0(r31),rp 7477 0x32d8 <main+224>: addil -0x800,dp 7478 0x32dc <main+228>: ldo 0x588(r1),r26 7479 0x32e0 <main+232>: ldil 0x3000,r31 7480End of assembler dump. 7481@end smallexample 7482 7483Here is an example showing mixed source+assembly for Intel x86, when the 7484program is stopped just after function prologue: 7485 7486@smallexample 7487(@value{GDBP}) disas /m main 7488Dump of assembler code for function main: 74895 @{ 7490 0x08048330 <+0>: push %ebp 7491 0x08048331 <+1>: mov %esp,%ebp 7492 0x08048333 <+3>: sub $0x8,%esp 7493 0x08048336 <+6>: and $0xfffffff0,%esp 7494 0x08048339 <+9>: sub $0x10,%esp 7495 74966 printf ("Hello.\n"); 7497=> 0x0804833c <+12>: movl $0x8048440,(%esp) 7498 0x08048343 <+19>: call 0x8048284 <puts@@plt> 7499 75007 return 0; 75018 @} 7502 0x08048348 <+24>: mov $0x0,%eax 7503 0x0804834d <+29>: leave 7504 0x0804834e <+30>: ret 7505 7506End of assembler dump. 7507@end smallexample 7508 7509Here is another example showing raw instructions in hex for AMD x86-64, 7510 7511@smallexample 7512(gdb) disas /r 0x400281,+10 7513Dump of assembler code from 0x400281 to 0x40028b: 7514 0x0000000000400281: 38 36 cmp %dh,(%rsi) 7515 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax 7516 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx) 7517 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al 7518End of assembler dump. 7519@end smallexample 7520 7521Addresses cannot be specified as a linespec (@pxref{Specify Location}). 7522So, for example, if you want to disassemble function @code{bar} 7523in file @file{foo.c}, you must type @samp{disassemble 'foo.c'::bar} 7524and not @samp{disassemble foo.c:bar}. 7525 7526Some architectures have more than one commonly-used set of instruction 7527mnemonics or other syntax. 7528 7529For programs that were dynamically linked and use shared libraries, 7530instructions that call functions or branch to locations in the shared 7531libraries might show a seemingly bogus location---it's actually a 7532location of the relocation table. On some architectures, @value{GDBN} 7533might be able to resolve these to actual function names. 7534 7535@table @code 7536@kindex set disassembly-flavor 7537@cindex Intel disassembly flavor 7538@cindex AT&T disassembly flavor 7539@item set disassembly-flavor @var{instruction-set} 7540Select the instruction set to use when disassembling the 7541program via the @code{disassemble} or @code{x/i} commands. 7542 7543Currently this command is only defined for the Intel x86 family. You 7544can set @var{instruction-set} to either @code{intel} or @code{att}. 7545The default is @code{att}, the AT&T flavor used by default by Unix 7546assemblers for x86-based targets. 7547 7548@kindex show disassembly-flavor 7549@item show disassembly-flavor 7550Show the current setting of the disassembly flavor. 7551@end table 7552 7553@table @code 7554@kindex set disassemble-next-line 7555@kindex show disassemble-next-line 7556@item set disassemble-next-line 7557@itemx show disassemble-next-line 7558Control whether or not @value{GDBN} will disassemble the next source 7559line or instruction when execution stops. If ON, @value{GDBN} will 7560display disassembly of the next source line when execution of the 7561program being debugged stops. This is @emph{in addition} to 7562displaying the source line itself, which @value{GDBN} always does if 7563possible. If the next source line cannot be displayed for some reason 7564(e.g., if @value{GDBN} cannot find the source file, or there's no line 7565info in the debug info), @value{GDBN} will display disassembly of the 7566next @emph{instruction} instead of showing the next source line. If 7567AUTO, @value{GDBN} will display disassembly of next instruction only 7568if the source line cannot be displayed. This setting causes 7569@value{GDBN} to display some feedback when you step through a function 7570with no line info or whose source file is unavailable. The default is 7571OFF, which means never display the disassembly of the next line or 7572instruction. 7573@end table 7574 7575 7576@node Data 7577@chapter Examining Data 7578 7579@cindex printing data 7580@cindex examining data 7581@kindex print 7582@kindex inspect 7583The usual way to examine data in your program is with the @code{print} 7584command (abbreviated @code{p}), or its synonym @code{inspect}. It 7585evaluates and prints the value of an expression of the language your 7586program is written in (@pxref{Languages, ,Using @value{GDBN} with 7587Different Languages}). It may also print the expression using a 7588Python-based pretty-printer (@pxref{Pretty Printing}). 7589 7590@table @code 7591@item print @var{expr} 7592@itemx print /@var{f} @var{expr} 7593@var{expr} is an expression (in the source language). By default the 7594value of @var{expr} is printed in a format appropriate to its data type; 7595you can choose a different format by specifying @samp{/@var{f}}, where 7596@var{f} is a letter specifying the format; see @ref{Output Formats,,Output 7597Formats}. 7598 7599@item print 7600@itemx print /@var{f} 7601@cindex reprint the last value 7602If you omit @var{expr}, @value{GDBN} displays the last value again (from the 7603@dfn{value history}; @pxref{Value History, ,Value History}). This allows you to 7604conveniently inspect the same value in an alternative format. 7605@end table 7606 7607A more low-level way of examining data is with the @code{x} command. 7608It examines data in memory at a specified address and prints it in a 7609specified format. @xref{Memory, ,Examining Memory}. 7610 7611If you are interested in information about types, or about how the 7612fields of a struct or a class are declared, use the @code{ptype @var{exp}} 7613command rather than @code{print}. @xref{Symbols, ,Examining the Symbol 7614Table}. 7615 7616@cindex exploring hierarchical data structures 7617@kindex explore 7618Another way of examining values of expressions and type information is 7619through the Python extension command @code{explore} (available only if 7620the @value{GDBN} build is configured with @code{--with-python}). It 7621offers an interactive way to start at the highest level (or, the most 7622abstract level) of the data type of an expression (or, the data type 7623itself) and explore all the way down to leaf scalar values/fields 7624embedded in the higher level data types. 7625 7626@table @code 7627@item explore @var{arg} 7628@var{arg} is either an expression (in the source language), or a type 7629visible in the current context of the program being debugged. 7630@end table 7631 7632The working of the @code{explore} command can be illustrated with an 7633example. If a data type @code{struct ComplexStruct} is defined in your 7634C program as 7635 7636@smallexample 7637struct SimpleStruct 7638@{ 7639 int i; 7640 double d; 7641@}; 7642 7643struct ComplexStruct 7644@{ 7645 struct SimpleStruct *ss_p; 7646 int arr[10]; 7647@}; 7648@end smallexample 7649 7650@noindent 7651followed by variable declarations as 7652 7653@smallexample 7654struct SimpleStruct ss = @{ 10, 1.11 @}; 7655struct ComplexStruct cs = @{ &ss, @{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 @} @}; 7656@end smallexample 7657 7658@noindent 7659then, the value of the variable @code{cs} can be explored using the 7660@code{explore} command as follows. 7661 7662@smallexample 7663(gdb) explore cs 7664The value of `cs' is a struct/class of type `struct ComplexStruct' with 7665the following fields: 7666 7667 ss_p = <Enter 0 to explore this field of type `struct SimpleStruct *'> 7668 arr = <Enter 1 to explore this field of type `int [10]'> 7669 7670Enter the field number of choice: 7671@end smallexample 7672 7673@noindent 7674Since the fields of @code{cs} are not scalar values, you are being 7675prompted to chose the field you want to explore. Let's say you choose 7676the field @code{ss_p} by entering @code{0}. Then, since this field is a 7677pointer, you will be asked if it is pointing to a single value. From 7678the declaration of @code{cs} above, it is indeed pointing to a single 7679value, hence you enter @code{y}. If you enter @code{n}, then you will 7680be asked if it were pointing to an array of values, in which case this 7681field will be explored as if it were an array. 7682 7683@smallexample 7684`cs.ss_p' is a pointer to a value of type `struct SimpleStruct' 7685Continue exploring it as a pointer to a single value [y/n]: y 7686The value of `*(cs.ss_p)' is a struct/class of type `struct 7687SimpleStruct' with the following fields: 7688 7689 i = 10 .. (Value of type `int') 7690 d = 1.1100000000000001 .. (Value of type `double') 7691 7692Press enter to return to parent value: 7693@end smallexample 7694 7695@noindent 7696If the field @code{arr} of @code{cs} was chosen for exploration by 7697entering @code{1} earlier, then since it is as array, you will be 7698prompted to enter the index of the element in the array that you want 7699to explore. 7700 7701@smallexample 7702`cs.arr' is an array of `int'. 7703Enter the index of the element you want to explore in `cs.arr': 5 7704 7705`(cs.arr)[5]' is a scalar value of type `int'. 7706 7707(cs.arr)[5] = 4 7708 7709Press enter to return to parent value: 7710@end smallexample 7711 7712In general, at any stage of exploration, you can go deeper towards the 7713leaf values by responding to the prompts appropriately, or hit the 7714return key to return to the enclosing data structure (the @i{higher} 7715level data structure). 7716 7717Similar to exploring values, you can use the @code{explore} command to 7718explore types. Instead of specifying a value (which is typically a 7719variable name or an expression valid in the current context of the 7720program being debugged), you specify a type name. If you consider the 7721same example as above, your can explore the type 7722@code{struct ComplexStruct} by passing the argument 7723@code{struct ComplexStruct} to the @code{explore} command. 7724 7725@smallexample 7726(gdb) explore struct ComplexStruct 7727@end smallexample 7728 7729@noindent 7730By responding to the prompts appropriately in the subsequent interactive 7731session, you can explore the type @code{struct ComplexStruct} in a 7732manner similar to how the value @code{cs} was explored in the above 7733example. 7734 7735The @code{explore} command also has two sub-commands, 7736@code{explore value} and @code{explore type}. The former sub-command is 7737a way to explicitly specify that value exploration of the argument is 7738being invoked, while the latter is a way to explicitly specify that type 7739exploration of the argument is being invoked. 7740 7741@table @code 7742@item explore value @var{expr} 7743@cindex explore value 7744This sub-command of @code{explore} explores the value of the 7745expression @var{expr} (if @var{expr} is an expression valid in the 7746current context of the program being debugged). The behavior of this 7747command is identical to that of the behavior of the @code{explore} 7748command being passed the argument @var{expr}. 7749 7750@item explore type @var{arg} 7751@cindex explore type 7752This sub-command of @code{explore} explores the type of @var{arg} (if 7753@var{arg} is a type visible in the current context of program being 7754debugged), or the type of the value/expression @var{arg} (if @var{arg} 7755is an expression valid in the current context of the program being 7756debugged). If @var{arg} is a type, then the behavior of this command is 7757identical to that of the @code{explore} command being passed the 7758argument @var{arg}. If @var{arg} is an expression, then the behavior of 7759this command will be identical to that of the @code{explore} command 7760being passed the type of @var{arg} as the argument. 7761@end table 7762 7763@menu 7764* Expressions:: Expressions 7765* Ambiguous Expressions:: Ambiguous Expressions 7766* Variables:: Program variables 7767* Arrays:: Artificial arrays 7768* Output Formats:: Output formats 7769* Memory:: Examining memory 7770* Auto Display:: Automatic display 7771* Print Settings:: Print settings 7772* Pretty Printing:: Python pretty printing 7773* Value History:: Value history 7774* Convenience Vars:: Convenience variables 7775* Convenience Funs:: Convenience functions 7776* Registers:: Registers 7777* Floating Point Hardware:: Floating point hardware 7778* Vector Unit:: Vector Unit 7779* OS Information:: Auxiliary data provided by operating system 7780* Memory Region Attributes:: Memory region attributes 7781* Dump/Restore Files:: Copy between memory and a file 7782* Core File Generation:: Cause a program dump its core 7783* Character Sets:: Debugging programs that use a different 7784 character set than GDB does 7785* Caching Remote Data:: Data caching for remote targets 7786* Searching Memory:: Searching memory for a sequence of bytes 7787@end menu 7788 7789@node Expressions 7790@section Expressions 7791 7792@cindex expressions 7793@code{print} and many other @value{GDBN} commands accept an expression and 7794compute its value. Any kind of constant, variable or operator defined 7795by the programming language you are using is valid in an expression in 7796@value{GDBN}. This includes conditional expressions, function calls, 7797casts, and string constants. It also includes preprocessor macros, if 7798you compiled your program to include this information; see 7799@ref{Compilation}. 7800 7801@cindex arrays in expressions 7802@value{GDBN} supports array constants in expressions input by 7803the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example, 7804you can use the command @code{print @{1, 2, 3@}} to create an array 7805of three integers. If you pass an array to a function or assign it 7806to a program variable, @value{GDBN} copies the array to memory that 7807is @code{malloc}ed in the target program. 7808 7809Because C is so widespread, most of the expressions shown in examples in 7810this manual are in C. @xref{Languages, , Using @value{GDBN} with Different 7811Languages}, for information on how to use expressions in other 7812languages. 7813 7814In this section, we discuss operators that you can use in @value{GDBN} 7815expressions regardless of your programming language. 7816 7817@cindex casts, in expressions 7818Casts are supported in all languages, not just in C, because it is so 7819useful to cast a number into a pointer in order to examine a structure 7820at that address in memory. 7821@c FIXME: casts supported---Mod2 true? 7822 7823@value{GDBN} supports these operators, in addition to those common 7824to programming languages: 7825 7826@table @code 7827@item @@ 7828@samp{@@} is a binary operator for treating parts of memory as arrays. 7829@xref{Arrays, ,Artificial Arrays}, for more information. 7830 7831@item :: 7832@samp{::} allows you to specify a variable in terms of the file or 7833function where it is defined. @xref{Variables, ,Program Variables}. 7834 7835@cindex @{@var{type}@} 7836@cindex type casting memory 7837@cindex memory, viewing as typed object 7838@cindex casts, to view memory 7839@item @{@var{type}@} @var{addr} 7840Refers to an object of type @var{type} stored at address @var{addr} in 7841memory. @var{addr} may be any expression whose value is an integer or 7842pointer (but parentheses are required around binary operators, just as in 7843a cast). This construct is allowed regardless of what kind of data is 7844normally supposed to reside at @var{addr}. 7845@end table 7846 7847@node Ambiguous Expressions 7848@section Ambiguous Expressions 7849@cindex ambiguous expressions 7850 7851Expressions can sometimes contain some ambiguous elements. For instance, 7852some programming languages (notably Ada, C@t{++} and Objective-C) permit 7853a single function name to be defined several times, for application in 7854different contexts. This is called @dfn{overloading}. Another example 7855involving Ada is generics. A @dfn{generic package} is similar to C@t{++} 7856templates and is typically instantiated several times, resulting in 7857the same function name being defined in different contexts. 7858 7859In some cases and depending on the language, it is possible to adjust 7860the expression to remove the ambiguity. For instance in C@t{++}, you 7861can specify the signature of the function you want to break on, as in 7862@kbd{break @var{function}(@var{types})}. In Ada, using the fully 7863qualified name of your function often makes the expression unambiguous 7864as well. 7865 7866When an ambiguity that needs to be resolved is detected, the debugger 7867has the capability to display a menu of numbered choices for each 7868possibility, and then waits for the selection with the prompt @samp{>}. 7869The first option is always @samp{[0] cancel}, and typing @kbd{0 @key{RET}} 7870aborts the current command. If the command in which the expression was 7871used allows more than one choice to be selected, the next option in the 7872menu is @samp{[1] all}, and typing @kbd{1 @key{RET}} selects all possible 7873choices. 7874 7875For example, the following session excerpt shows an attempt to set a 7876breakpoint at the overloaded symbol @code{String::after}. 7877We choose three particular definitions of that function name: 7878 7879@c FIXME! This is likely to change to show arg type lists, at least 7880@smallexample 7881@group 7882(@value{GDBP}) b String::after 7883[0] cancel 7884[1] all 7885[2] file:String.cc; line number:867 7886[3] file:String.cc; line number:860 7887[4] file:String.cc; line number:875 7888[5] file:String.cc; line number:853 7889[6] file:String.cc; line number:846 7890[7] file:String.cc; line number:735 7891> 2 4 6 7892Breakpoint 1 at 0xb26c: file String.cc, line 867. 7893Breakpoint 2 at 0xb344: file String.cc, line 875. 7894Breakpoint 3 at 0xafcc: file String.cc, line 846. 7895Multiple breakpoints were set. 7896Use the "delete" command to delete unwanted 7897 breakpoints. 7898(@value{GDBP}) 7899@end group 7900@end smallexample 7901 7902@table @code 7903@kindex set multiple-symbols 7904@item set multiple-symbols @var{mode} 7905@cindex multiple-symbols menu 7906 7907This option allows you to adjust the debugger behavior when an expression 7908is ambiguous. 7909 7910By default, @var{mode} is set to @code{all}. If the command with which 7911the expression is used allows more than one choice, then @value{GDBN} 7912automatically selects all possible choices. For instance, inserting 7913a breakpoint on a function using an ambiguous name results in a breakpoint 7914inserted on each possible match. However, if a unique choice must be made, 7915then @value{GDBN} uses the menu to help you disambiguate the expression. 7916For instance, printing the address of an overloaded function will result 7917in the use of the menu. 7918 7919When @var{mode} is set to @code{ask}, the debugger always uses the menu 7920when an ambiguity is detected. 7921 7922Finally, when @var{mode} is set to @code{cancel}, the debugger reports 7923an error due to the ambiguity and the command is aborted. 7924 7925@kindex show multiple-symbols 7926@item show multiple-symbols 7927Show the current value of the @code{multiple-symbols} setting. 7928@end table 7929 7930@node Variables 7931@section Program Variables 7932 7933The most common kind of expression to use is the name of a variable 7934in your program. 7935 7936Variables in expressions are understood in the selected stack frame 7937(@pxref{Selection, ,Selecting a Frame}); they must be either: 7938 7939@itemize @bullet 7940@item 7941global (or file-static) 7942@end itemize 7943 7944@noindent or 7945 7946@itemize @bullet 7947@item 7948visible according to the scope rules of the 7949programming language from the point of execution in that frame 7950@end itemize 7951 7952@noindent This means that in the function 7953 7954@smallexample 7955foo (a) 7956 int a; 7957@{ 7958 bar (a); 7959 @{ 7960 int b = test (); 7961 bar (b); 7962 @} 7963@} 7964@end smallexample 7965 7966@noindent 7967you can examine and use the variable @code{a} whenever your program is 7968executing within the function @code{foo}, but you can only use or 7969examine the variable @code{b} while your program is executing inside 7970the block where @code{b} is declared. 7971 7972@cindex variable name conflict 7973There is an exception: you can refer to a variable or function whose 7974scope is a single source file even if the current execution point is not 7975in this file. But it is possible to have more than one such variable or 7976function with the same name (in different source files). If that 7977happens, referring to that name has unpredictable effects. If you wish, 7978you can specify a static variable in a particular function or file by 7979using the colon-colon (@code{::}) notation: 7980 7981@cindex colon-colon, context for variables/functions 7982@ifnotinfo 7983@c info cannot cope with a :: index entry, but why deprive hard copy readers? 7984@cindex @code{::}, context for variables/functions 7985@end ifnotinfo 7986@smallexample 7987@var{file}::@var{variable} 7988@var{function}::@var{variable} 7989@end smallexample 7990 7991@noindent 7992Here @var{file} or @var{function} is the name of the context for the 7993static @var{variable}. In the case of file names, you can use quotes to 7994make sure @value{GDBN} parses the file name as a single word---for example, 7995to print a global value of @code{x} defined in @file{f2.c}: 7996 7997@smallexample 7998(@value{GDBP}) p 'f2.c'::x 7999@end smallexample 8000 8001The @code{::} notation is normally used for referring to 8002static variables, since you typically disambiguate uses of local variables 8003in functions by selecting the appropriate frame and using the 8004simple name of the variable. However, you may also use this notation 8005to refer to local variables in frames enclosing the selected frame: 8006 8007@smallexample 8008void 8009foo (int a) 8010@{ 8011 if (a < 10) 8012 bar (a); 8013 else 8014 process (a); /* Stop here */ 8015@} 8016 8017int 8018bar (int a) 8019@{ 8020 foo (a + 5); 8021@} 8022@end smallexample 8023 8024@noindent 8025For example, if there is a breakpoint at the commented line, 8026here is what you might see 8027when the program stops after executing the call @code{bar(0)}: 8028 8029@smallexample 8030(@value{GDBP}) p a 8031$1 = 10 8032(@value{GDBP}) p bar::a 8033$2 = 5 8034(@value{GDBP}) up 2 8035#2 0x080483d0 in foo (a=5) at foobar.c:12 8036(@value{GDBP}) p a 8037$3 = 5 8038(@value{GDBP}) p bar::a 8039$4 = 0 8040@end smallexample 8041 8042@cindex C@t{++} scope resolution 8043These uses of @samp{::} are very rarely in conflict with the very similar 8044use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++} 8045scope resolution operator in @value{GDBN} expressions. 8046@c FIXME: Um, so what happens in one of those rare cases where it's in 8047@c conflict?? --mew 8048 8049@cindex wrong values 8050@cindex variable values, wrong 8051@cindex function entry/exit, wrong values of variables 8052@cindex optimized code, wrong values of variables 8053@quotation 8054@emph{Warning:} Occasionally, a local variable may appear to have the 8055wrong value at certain points in a function---just after entry to a new 8056scope, and just before exit. 8057@end quotation 8058You may see this problem when you are stepping by machine instructions. 8059This is because, on most machines, it takes more than one instruction to 8060set up a stack frame (including local variable definitions); if you are 8061stepping by machine instructions, variables may appear to have the wrong 8062values until the stack frame is completely built. On exit, it usually 8063also takes more than one machine instruction to destroy a stack frame; 8064after you begin stepping through that group of instructions, local 8065variable definitions may be gone. 8066 8067This may also happen when the compiler does significant optimizations. 8068To be sure of always seeing accurate values, turn off all optimization 8069when compiling. 8070 8071@cindex ``No symbol "foo" in current context'' 8072Another possible effect of compiler optimizations is to optimize 8073unused variables out of existence, or assign variables to registers (as 8074opposed to memory addresses). Depending on the support for such cases 8075offered by the debug info format used by the compiler, @value{GDBN} 8076might not be able to display values for such local variables. If that 8077happens, @value{GDBN} will print a message like this: 8078 8079@smallexample 8080No symbol "foo" in current context. 8081@end smallexample 8082 8083To solve such problems, either recompile without optimizations, or use a 8084different debug info format, if the compiler supports several such 8085formats. @xref{Compilation}, for more information on choosing compiler 8086options. @xref{C, ,C and C@t{++}}, for more information about debug 8087info formats that are best suited to C@t{++} programs. 8088 8089If you ask to print an object whose contents are unknown to 8090@value{GDBN}, e.g., because its data type is not completely specified 8091by the debug information, @value{GDBN} will say @samp{<incomplete 8092type>}. @xref{Symbols, incomplete type}, for more about this. 8093 8094If you append @kbd{@@entry} string to a function parameter name you get its 8095value at the time the function got called. If the value is not available an 8096error message is printed. Entry values are available only with some compilers. 8097Entry values are normally also printed at the function parameter list according 8098to @ref{set print entry-values}. 8099 8100@smallexample 8101Breakpoint 1, d (i=30) at gdb.base/entry-value.c:29 810229 i++; 8103(gdb) next 810430 e (i); 8105(gdb) print i 8106$1 = 31 8107(gdb) print i@@entry 8108$2 = 30 8109@end smallexample 8110 8111Strings are identified as arrays of @code{char} values without specified 8112signedness. Arrays of either @code{signed char} or @code{unsigned char} get 8113printed as arrays of 1 byte sized integers. @code{-fsigned-char} or 8114@code{-funsigned-char} @value{NGCC} options have no effect as @value{GDBN} 8115defines literal string type @code{"char"} as @code{char} without a sign. 8116For program code 8117 8118@smallexample 8119char var0[] = "A"; 8120signed char var1[] = "A"; 8121@end smallexample 8122 8123You get during debugging 8124@smallexample 8125(gdb) print var0 8126$1 = "A" 8127(gdb) print var1 8128$2 = @{65 'A', 0 '\0'@} 8129@end smallexample 8130 8131@node Arrays 8132@section Artificial Arrays 8133 8134@cindex artificial array 8135@cindex arrays 8136@kindex @@@r{, referencing memory as an array} 8137It is often useful to print out several successive objects of the 8138same type in memory; a section of an array, or an array of 8139dynamically determined size for which only a pointer exists in the 8140program. 8141 8142You can do this by referring to a contiguous span of memory as an 8143@dfn{artificial array}, using the binary operator @samp{@@}. The left 8144operand of @samp{@@} should be the first element of the desired array 8145and be an individual object. The right operand should be the desired length 8146of the array. The result is an array value whose elements are all of 8147the type of the left argument. The first element is actually the left 8148argument; the second element comes from bytes of memory immediately 8149following those that hold the first element, and so on. Here is an 8150example. If a program says 8151 8152@smallexample 8153int *array = (int *) malloc (len * sizeof (int)); 8154@end smallexample 8155 8156@noindent 8157you can print the contents of @code{array} with 8158 8159@smallexample 8160p *array@@len 8161@end smallexample 8162 8163The left operand of @samp{@@} must reside in memory. Array values made 8164with @samp{@@} in this way behave just like other arrays in terms of 8165subscripting, and are coerced to pointers when used in expressions. 8166Artificial arrays most often appear in expressions via the value history 8167(@pxref{Value History, ,Value History}), after printing one out. 8168 8169Another way to create an artificial array is to use a cast. 8170This re-interprets a value as if it were an array. 8171The value need not be in memory: 8172@smallexample 8173(@value{GDBP}) p/x (short[2])0x12345678 8174$1 = @{0x1234, 0x5678@} 8175@end smallexample 8176 8177As a convenience, if you leave the array length out (as in 8178@samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill 8179the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}: 8180@smallexample 8181(@value{GDBP}) p/x (short[])0x12345678 8182$2 = @{0x1234, 0x5678@} 8183@end smallexample 8184 8185Sometimes the artificial array mechanism is not quite enough; in 8186moderately complex data structures, the elements of interest may not 8187actually be adjacent---for example, if you are interested in the values 8188of pointers in an array. One useful work-around in this situation is 8189to use a convenience variable (@pxref{Convenience Vars, ,Convenience 8190Variables}) as a counter in an expression that prints the first 8191interesting value, and then repeat that expression via @key{RET}. For 8192instance, suppose you have an array @code{dtab} of pointers to 8193structures, and you are interested in the values of a field @code{fv} 8194in each structure. Here is an example of what you might type: 8195 8196@smallexample 8197set $i = 0 8198p dtab[$i++]->fv 8199@key{RET} 8200@key{RET} 8201@dots{} 8202@end smallexample 8203 8204@node Output Formats 8205@section Output Formats 8206 8207@cindex formatted output 8208@cindex output formats 8209By default, @value{GDBN} prints a value according to its data type. Sometimes 8210this is not what you want. For example, you might want to print a number 8211in hex, or a pointer in decimal. Or you might want to view data in memory 8212at a certain address as a character string or as an instruction. To do 8213these things, specify an @dfn{output format} when you print a value. 8214 8215The simplest use of output formats is to say how to print a value 8216already computed. This is done by starting the arguments of the 8217@code{print} command with a slash and a format letter. The format 8218letters supported are: 8219 8220@table @code 8221@item x 8222Regard the bits of the value as an integer, and print the integer in 8223hexadecimal. 8224 8225@item d 8226Print as integer in signed decimal. 8227 8228@item u 8229Print as integer in unsigned decimal. 8230 8231@item o 8232Print as integer in octal. 8233 8234@item t 8235Print as integer in binary. The letter @samp{t} stands for ``two''. 8236@footnote{@samp{b} cannot be used because these format letters are also 8237used with the @code{x} command, where @samp{b} stands for ``byte''; 8238see @ref{Memory,,Examining Memory}.} 8239 8240@item a 8241@cindex unknown address, locating 8242@cindex locate address 8243Print as an address, both absolute in hexadecimal and as an offset from 8244the nearest preceding symbol. You can use this format used to discover 8245where (in what function) an unknown address is located: 8246 8247@smallexample 8248(@value{GDBP}) p/a 0x54320 8249$3 = 0x54320 <_initialize_vx+396> 8250@end smallexample 8251 8252@noindent 8253The command @code{info symbol 0x54320} yields similar results. 8254@xref{Symbols, info symbol}. 8255 8256@item c 8257Regard as an integer and print it as a character constant. This 8258prints both the numerical value and its character representation. The 8259character representation is replaced with the octal escape @samp{\nnn} 8260for characters outside the 7-bit @sc{ascii} range. 8261 8262Without this format, @value{GDBN} displays @code{char}, 8263@w{@code{unsigned char}}, and @w{@code{signed char}} data as character 8264constants. Single-byte members of vectors are displayed as integer 8265data. 8266 8267@item f 8268Regard the bits of the value as a floating point number and print 8269using typical floating point syntax. 8270 8271@item s 8272@cindex printing strings 8273@cindex printing byte arrays 8274Regard as a string, if possible. With this format, pointers to single-byte 8275data are displayed as null-terminated strings and arrays of single-byte data 8276are displayed as fixed-length strings. Other values are displayed in their 8277natural types. 8278 8279Without this format, @value{GDBN} displays pointers to and arrays of 8280@code{char}, @w{@code{unsigned char}}, and @w{@code{signed char}} as 8281strings. Single-byte members of a vector are displayed as an integer 8282array. 8283 8284@item r 8285@cindex raw printing 8286Print using the @samp{raw} formatting. By default, @value{GDBN} will 8287use a Python-based pretty-printer, if one is available (@pxref{Pretty 8288Printing}). This typically results in a higher-level display of the 8289value's contents. The @samp{r} format bypasses any Python 8290pretty-printer which might exist. 8291@end table 8292 8293For example, to print the program counter in hex (@pxref{Registers}), type 8294 8295@smallexample 8296p/x $pc 8297@end smallexample 8298 8299@noindent 8300Note that no space is required before the slash; this is because command 8301names in @value{GDBN} cannot contain a slash. 8302 8303To reprint the last value in the value history with a different format, 8304you can use the @code{print} command with just a format and no 8305expression. For example, @samp{p/x} reprints the last value in hex. 8306 8307@node Memory 8308@section Examining Memory 8309 8310You can use the command @code{x} (for ``examine'') to examine memory in 8311any of several formats, independently of your program's data types. 8312 8313@cindex examining memory 8314@table @code 8315@kindex x @r{(examine memory)} 8316@item x/@var{nfu} @var{addr} 8317@itemx x @var{addr} 8318@itemx x 8319Use the @code{x} command to examine memory. 8320@end table 8321 8322@var{n}, @var{f}, and @var{u} are all optional parameters that specify how 8323much memory to display and how to format it; @var{addr} is an 8324expression giving the address where you want to start displaying memory. 8325If you use defaults for @var{nfu}, you need not type the slash @samp{/}. 8326Several commands set convenient defaults for @var{addr}. 8327 8328@table @r 8329@item @var{n}, the repeat count 8330The repeat count is a decimal integer; the default is 1. It specifies 8331how much memory (counting by units @var{u}) to display. 8332@c This really is **decimal**; unaffected by 'set radix' as of GDB 8333@c 4.1.2. 8334 8335@item @var{f}, the display format 8336The display format is one of the formats used by @code{print} 8337(@samp{x}, @samp{d}, @samp{u}, @samp{o}, @samp{t}, @samp{a}, @samp{c}, 8338@samp{f}, @samp{s}), and in addition @samp{i} (for machine instructions). 8339The default is @samp{x} (hexadecimal) initially. The default changes 8340each time you use either @code{x} or @code{print}. 8341 8342@item @var{u}, the unit size 8343The unit size is any of 8344 8345@table @code 8346@item b 8347Bytes. 8348@item h 8349Halfwords (two bytes). 8350@item w 8351Words (four bytes). This is the initial default. 8352@item g 8353Giant words (eight bytes). 8354@end table 8355 8356Each time you specify a unit size with @code{x}, that size becomes the 8357default unit the next time you use @code{x}. For the @samp{i} format, 8358the unit size is ignored and is normally not written. For the @samp{s} format, 8359the unit size defaults to @samp{b}, unless it is explicitly given. 8360Use @kbd{x /hs} to display 16-bit char strings and @kbd{x /ws} to display 836132-bit strings. The next use of @kbd{x /s} will again display 8-bit strings. 8362Note that the results depend on the programming language of the 8363current compilation unit. If the language is C, the @samp{s} 8364modifier will use the UTF-16 encoding while @samp{w} will use 8365UTF-32. The encoding is set by the programming language and cannot 8366be altered. 8367 8368@item @var{addr}, starting display address 8369@var{addr} is the address where you want @value{GDBN} to begin displaying 8370memory. The expression need not have a pointer value (though it may); 8371it is always interpreted as an integer address of a byte of memory. 8372@xref{Expressions, ,Expressions}, for more information on expressions. The default for 8373@var{addr} is usually just after the last address examined---but several 8374other commands also set the default address: @code{info breakpoints} (to 8375the address of the last breakpoint listed), @code{info line} (to the 8376starting address of a line), and @code{print} (if you use it to display 8377a value from memory). 8378@end table 8379 8380For example, @samp{x/3uh 0x54320} is a request to display three halfwords 8381(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}), 8382starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four 8383words (@samp{w}) of memory above the stack pointer (here, @samp{$sp}; 8384@pxref{Registers, ,Registers}) in hexadecimal (@samp{x}). 8385 8386Since the letters indicating unit sizes are all distinct from the 8387letters specifying output formats, you do not have to remember whether 8388unit size or format comes first; either order works. The output 8389specifications @samp{4xw} and @samp{4wx} mean exactly the same thing. 8390(However, the count @var{n} must come first; @samp{wx4} does not work.) 8391 8392Even though the unit size @var{u} is ignored for the formats @samp{s} 8393and @samp{i}, you might still want to use a count @var{n}; for example, 8394@samp{3i} specifies that you want to see three machine instructions, 8395including any operands. For convenience, especially when used with 8396the @code{display} command, the @samp{i} format also prints branch delay 8397slot instructions, if any, beyond the count specified, which immediately 8398follow the last instruction that is within the count. The command 8399@code{disassemble} gives an alternative way of inspecting machine 8400instructions; see @ref{Machine Code,,Source and Machine Code}. 8401 8402All the defaults for the arguments to @code{x} are designed to make it 8403easy to continue scanning memory with minimal specifications each time 8404you use @code{x}. For example, after you have inspected three machine 8405instructions with @samp{x/3i @var{addr}}, you can inspect the next seven 8406with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command, 8407the repeat count @var{n} is used again; the other arguments default as 8408for successive uses of @code{x}. 8409 8410When examining machine instructions, the instruction at current program 8411counter is shown with a @code{=>} marker. For example: 8412 8413@smallexample 8414(@value{GDBP}) x/5i $pc-6 8415 0x804837f <main+11>: mov %esp,%ebp 8416 0x8048381 <main+13>: push %ecx 8417 0x8048382 <main+14>: sub $0x4,%esp 8418=> 0x8048385 <main+17>: movl $0x8048460,(%esp) 8419 0x804838c <main+24>: call 0x80482d4 <puts@@plt> 8420@end smallexample 8421 8422@cindex @code{$_}, @code{$__}, and value history 8423The addresses and contents printed by the @code{x} command are not saved 8424in the value history because there is often too much of them and they 8425would get in the way. Instead, @value{GDBN} makes these values available for 8426subsequent use in expressions as values of the convenience variables 8427@code{$_} and @code{$__}. After an @code{x} command, the last address 8428examined is available for use in expressions in the convenience variable 8429@code{$_}. The contents of that address, as examined, are available in 8430the convenience variable @code{$__}. 8431 8432If the @code{x} command has a repeat count, the address and contents saved 8433are from the last memory unit printed; this is not the same as the last 8434address printed if several units were printed on the last line of output. 8435 8436@cindex remote memory comparison 8437@cindex verify remote memory image 8438When you are debugging a program running on a remote target machine 8439(@pxref{Remote Debugging}), you may wish to verify the program's image in the 8440remote machine's memory against the executable file you downloaded to 8441the target. The @code{compare-sections} command is provided for such 8442situations. 8443 8444@table @code 8445@kindex compare-sections 8446@item compare-sections @r{[}@var{section-name}@r{]} 8447Compare the data of a loadable section @var{section-name} in the 8448executable file of the program being debugged with the same section in 8449the remote machine's memory, and report any mismatches. With no 8450arguments, compares all loadable sections. This command's 8451availability depends on the target's support for the @code{"qCRC"} 8452remote request. 8453@end table 8454 8455@node Auto Display 8456@section Automatic Display 8457@cindex automatic display 8458@cindex display of expressions 8459 8460If you find that you want to print the value of an expression frequently 8461(to see how it changes), you might want to add it to the @dfn{automatic 8462display list} so that @value{GDBN} prints its value each time your program stops. 8463Each expression added to the list is given a number to identify it; 8464to remove an expression from the list, you specify that number. 8465The automatic display looks like this: 8466 8467@smallexample 84682: foo = 38 84693: bar[5] = (struct hack *) 0x3804 8470@end smallexample 8471 8472@noindent 8473This display shows item numbers, expressions and their current values. As with 8474displays you request manually using @code{x} or @code{print}, you can 8475specify the output format you prefer; in fact, @code{display} decides 8476whether to use @code{print} or @code{x} depending your format 8477specification---it uses @code{x} if you specify either the @samp{i} 8478or @samp{s} format, or a unit size; otherwise it uses @code{print}. 8479 8480@table @code 8481@kindex display 8482@item display @var{expr} 8483Add the expression @var{expr} to the list of expressions to display 8484each time your program stops. @xref{Expressions, ,Expressions}. 8485 8486@code{display} does not repeat if you press @key{RET} again after using it. 8487 8488@item display/@var{fmt} @var{expr} 8489For @var{fmt} specifying only a display format and not a size or 8490count, add the expression @var{expr} to the auto-display list but 8491arrange to display it each time in the specified format @var{fmt}. 8492@xref{Output Formats,,Output Formats}. 8493 8494@item display/@var{fmt} @var{addr} 8495For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a 8496number of units, add the expression @var{addr} as a memory address to 8497be examined each time your program stops. Examining means in effect 8498doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining Memory}. 8499@end table 8500 8501For example, @samp{display/i $pc} can be helpful, to see the machine 8502instruction about to be executed each time execution stops (@samp{$pc} 8503is a common name for the program counter; @pxref{Registers, ,Registers}). 8504 8505@table @code 8506@kindex delete display 8507@kindex undisplay 8508@item undisplay @var{dnums}@dots{} 8509@itemx delete display @var{dnums}@dots{} 8510Remove items from the list of expressions to display. Specify the 8511numbers of the displays that you want affected with the command 8512argument @var{dnums}. It can be a single display number, one of the 8513numbers shown in the first field of the @samp{info display} display; 8514or it could be a range of display numbers, as in @code{2-4}. 8515 8516@code{undisplay} does not repeat if you press @key{RET} after using it. 8517(Otherwise you would just get the error @samp{No display number @dots{}}.) 8518 8519@kindex disable display 8520@item disable display @var{dnums}@dots{} 8521Disable the display of item numbers @var{dnums}. A disabled display 8522item is not printed automatically, but is not forgotten. It may be 8523enabled again later. Specify the numbers of the displays that you 8524want affected with the command argument @var{dnums}. It can be a 8525single display number, one of the numbers shown in the first field of 8526the @samp{info display} display; or it could be a range of display 8527numbers, as in @code{2-4}. 8528 8529@kindex enable display 8530@item enable display @var{dnums}@dots{} 8531Enable display of item numbers @var{dnums}. It becomes effective once 8532again in auto display of its expression, until you specify otherwise. 8533Specify the numbers of the displays that you want affected with the 8534command argument @var{dnums}. It can be a single display number, one 8535of the numbers shown in the first field of the @samp{info display} 8536display; or it could be a range of display numbers, as in @code{2-4}. 8537 8538@item display 8539Display the current values of the expressions on the list, just as is 8540done when your program stops. 8541 8542@kindex info display 8543@item info display 8544Print the list of expressions previously set up to display 8545automatically, each one with its item number, but without showing the 8546values. This includes disabled expressions, which are marked as such. 8547It also includes expressions which would not be displayed right now 8548because they refer to automatic variables not currently available. 8549@end table 8550 8551@cindex display disabled out of scope 8552If a display expression refers to local variables, then it does not make 8553sense outside the lexical context for which it was set up. Such an 8554expression is disabled when execution enters a context where one of its 8555variables is not defined. For example, if you give the command 8556@code{display last_char} while inside a function with an argument 8557@code{last_char}, @value{GDBN} displays this argument while your program 8558continues to stop inside that function. When it stops elsewhere---where 8559there is no variable @code{last_char}---the display is disabled 8560automatically. The next time your program stops where @code{last_char} 8561is meaningful, you can enable the display expression once again. 8562 8563@node Print Settings 8564@section Print Settings 8565 8566@cindex format options 8567@cindex print settings 8568@value{GDBN} provides the following ways to control how arrays, structures, 8569and symbols are printed. 8570 8571@noindent 8572These settings are useful for debugging programs in any language: 8573 8574@table @code 8575@kindex set print 8576@item set print address 8577@itemx set print address on 8578@cindex print/don't print memory addresses 8579@value{GDBN} prints memory addresses showing the location of stack 8580traces, structure values, pointer values, breakpoints, and so forth, 8581even when it also displays the contents of those addresses. The default 8582is @code{on}. For example, this is what a stack frame display looks like with 8583@code{set print address on}: 8584 8585@smallexample 8586@group 8587(@value{GDBP}) f 8588#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") 8589 at input.c:530 8590530 if (lquote != def_lquote) 8591@end group 8592@end smallexample 8593 8594@item set print address off 8595Do not print addresses when displaying their contents. For example, 8596this is the same stack frame displayed with @code{set print address off}: 8597 8598@smallexample 8599@group 8600(@value{GDBP}) set print addr off 8601(@value{GDBP}) f 8602#0 set_quotes (lq="<<", rq=">>") at input.c:530 8603530 if (lquote != def_lquote) 8604@end group 8605@end smallexample 8606 8607You can use @samp{set print address off} to eliminate all machine 8608dependent displays from the @value{GDBN} interface. For example, with 8609@code{print address off}, you should get the same text for backtraces on 8610all machines---whether or not they involve pointer arguments. 8611 8612@kindex show print 8613@item show print address 8614Show whether or not addresses are to be printed. 8615@end table 8616 8617When @value{GDBN} prints a symbolic address, it normally prints the 8618closest earlier symbol plus an offset. If that symbol does not uniquely 8619identify the address (for example, it is a name whose scope is a single 8620source file), you may need to clarify. One way to do this is with 8621@code{info line}, for example @samp{info line *0x4537}. Alternately, 8622you can set @value{GDBN} to print the source file and line number when 8623it prints a symbolic address: 8624 8625@table @code 8626@item set print symbol-filename on 8627@cindex source file and line of a symbol 8628@cindex symbol, source file and line 8629Tell @value{GDBN} to print the source file name and line number of a 8630symbol in the symbolic form of an address. 8631 8632@item set print symbol-filename off 8633Do not print source file name and line number of a symbol. This is the 8634default. 8635 8636@item show print symbol-filename 8637Show whether or not @value{GDBN} will print the source file name and 8638line number of a symbol in the symbolic form of an address. 8639@end table 8640 8641Another situation where it is helpful to show symbol filenames and line 8642numbers is when disassembling code; @value{GDBN} shows you the line 8643number and source file that corresponds to each instruction. 8644 8645Also, you may wish to see the symbolic form only if the address being 8646printed is reasonably close to the closest earlier symbol: 8647 8648@table @code 8649@item set print max-symbolic-offset @var{max-offset} 8650@cindex maximum value for offset of closest symbol 8651Tell @value{GDBN} to only display the symbolic form of an address if the 8652offset between the closest earlier symbol and the address is less than 8653@var{max-offset}. The default is 0, which tells @value{GDBN} 8654to always print the symbolic form of an address if any symbol precedes it. 8655 8656@item show print max-symbolic-offset 8657Ask how large the maximum offset is that @value{GDBN} prints in a 8658symbolic address. 8659@end table 8660 8661@cindex wild pointer, interpreting 8662@cindex pointer, finding referent 8663If you have a pointer and you are not sure where it points, try 8664@samp{set print symbol-filename on}. Then you can determine the name 8665and source file location of the variable where it points, using 8666@samp{p/a @var{pointer}}. This interprets the address in symbolic form. 8667For example, here @value{GDBN} shows that a variable @code{ptt} points 8668at another variable @code{t}, defined in @file{hi2.c}: 8669 8670@smallexample 8671(@value{GDBP}) set print symbol-filename on 8672(@value{GDBP}) p/a ptt 8673$4 = 0xe008 <t in hi2.c> 8674@end smallexample 8675 8676@quotation 8677@emph{Warning:} For pointers that point to a local variable, @samp{p/a} 8678does not show the symbol name and filename of the referent, even with 8679the appropriate @code{set print} options turned on. 8680@end quotation 8681 8682You can also enable @samp{/a}-like formatting all the time using 8683@samp{set print symbol on}: 8684 8685@table @code 8686@item set print symbol on 8687Tell @value{GDBN} to print the symbol corresponding to an address, if 8688one exists. 8689 8690@item set print symbol off 8691Tell @value{GDBN} not to print the symbol corresponding to an 8692address. In this mode, @value{GDBN} will still print the symbol 8693corresponding to pointers to functions. This is the default. 8694 8695@item show print symbol 8696Show whether @value{GDBN} will display the symbol corresponding to an 8697address. 8698@end table 8699 8700Other settings control how different kinds of objects are printed: 8701 8702@table @code 8703@item set print array 8704@itemx set print array on 8705@cindex pretty print arrays 8706Pretty print arrays. This format is more convenient to read, 8707but uses more space. The default is off. 8708 8709@item set print array off 8710Return to compressed format for arrays. 8711 8712@item show print array 8713Show whether compressed or pretty format is selected for displaying 8714arrays. 8715 8716@cindex print array indexes 8717@item set print array-indexes 8718@itemx set print array-indexes on 8719Print the index of each element when displaying arrays. May be more 8720convenient to locate a given element in the array or quickly find the 8721index of a given element in that printed array. The default is off. 8722 8723@item set print array-indexes off 8724Stop printing element indexes when displaying arrays. 8725 8726@item show print array-indexes 8727Show whether the index of each element is printed when displaying 8728arrays. 8729 8730@item set print elements @var{number-of-elements} 8731@cindex number of array elements to print 8732@cindex limit on number of printed array elements 8733Set a limit on how many elements of an array @value{GDBN} will print. 8734If @value{GDBN} is printing a large array, it stops printing after it has 8735printed the number of elements set by the @code{set print elements} command. 8736This limit also applies to the display of strings. 8737When @value{GDBN} starts, this limit is set to 200. 8738Setting @var{number-of-elements} to zero means that the printing is unlimited. 8739 8740@item show print elements 8741Display the number of elements of a large array that @value{GDBN} will print. 8742If the number is 0, then the printing is unlimited. 8743 8744@item set print frame-arguments @var{value} 8745@kindex set print frame-arguments 8746@cindex printing frame argument values 8747@cindex print all frame argument values 8748@cindex print frame argument values for scalars only 8749@cindex do not print frame argument values 8750This command allows to control how the values of arguments are printed 8751when the debugger prints a frame (@pxref{Frames}). The possible 8752values are: 8753 8754@table @code 8755@item all 8756The values of all arguments are printed. 8757 8758@item scalars 8759Print the value of an argument only if it is a scalar. The value of more 8760complex arguments such as arrays, structures, unions, etc, is replaced 8761by @code{@dots{}}. This is the default. Here is an example where 8762only scalar arguments are shown: 8763 8764@smallexample 8765#1 0x08048361 in call_me (i=3, s=@dots{}, ss=0xbf8d508c, u=@dots{}, e=green) 8766 at frame-args.c:23 8767@end smallexample 8768 8769@item none 8770None of the argument values are printed. Instead, the value of each argument 8771is replaced by @code{@dots{}}. In this case, the example above now becomes: 8772 8773@smallexample 8774#1 0x08048361 in call_me (i=@dots{}, s=@dots{}, ss=@dots{}, u=@dots{}, e=@dots{}) 8775 at frame-args.c:23 8776@end smallexample 8777@end table 8778 8779By default, only scalar arguments are printed. This command can be used 8780to configure the debugger to print the value of all arguments, regardless 8781of their type. However, it is often advantageous to not print the value 8782of more complex parameters. For instance, it reduces the amount of 8783information printed in each frame, making the backtrace more readable. 8784Also, it improves performance when displaying Ada frames, because 8785the computation of large arguments can sometimes be CPU-intensive, 8786especially in large applications. Setting @code{print frame-arguments} 8787to @code{scalars} (the default) or @code{none} avoids this computation, 8788thus speeding up the display of each Ada frame. 8789 8790@item show print frame-arguments 8791Show how the value of arguments should be displayed when printing a frame. 8792 8793@anchor{set print entry-values} 8794@item set print entry-values @var{value} 8795@kindex set print entry-values 8796Set printing of frame argument values at function entry. In some cases 8797@value{GDBN} can determine the value of function argument which was passed by 8798the function caller, even if the value was modified inside the called function 8799and therefore is different. With optimized code, the current value could be 8800unavailable, but the entry value may still be known. 8801 8802The default value is @code{default} (see below for its description). Older 8803@value{GDBN} behaved as with the setting @code{no}. Compilers not supporting 8804this feature will behave in the @code{default} setting the same way as with the 8805@code{no} setting. 8806 8807This functionality is currently supported only by DWARF 2 debugging format and 8808the compiler has to produce @samp{DW_TAG_GNU_call_site} tags. With 8809@value{NGCC}, you need to specify @option{-O -g} during compilation, to get 8810this information. 8811 8812The @var{value} parameter can be one of the following: 8813 8814@table @code 8815@item no 8816Print only actual parameter values, never print values from function entry 8817point. 8818@smallexample 8819#0 equal (val=5) 8820#0 different (val=6) 8821#0 lost (val=<optimized out>) 8822#0 born (val=10) 8823#0 invalid (val=<optimized out>) 8824@end smallexample 8825 8826@item only 8827Print only parameter values from function entry point. The actual parameter 8828values are never printed. 8829@smallexample 8830#0 equal (val@@entry=5) 8831#0 different (val@@entry=5) 8832#0 lost (val@@entry=5) 8833#0 born (val@@entry=<optimized out>) 8834#0 invalid (val@@entry=<optimized out>) 8835@end smallexample 8836 8837@item preferred 8838Print only parameter values from function entry point. If value from function 8839entry point is not known while the actual value is known, print the actual 8840value for such parameter. 8841@smallexample 8842#0 equal (val@@entry=5) 8843#0 different (val@@entry=5) 8844#0 lost (val@@entry=5) 8845#0 born (val=10) 8846#0 invalid (val@@entry=<optimized out>) 8847@end smallexample 8848 8849@item if-needed 8850Print actual parameter values. If actual parameter value is not known while 8851value from function entry point is known, print the entry point value for such 8852parameter. 8853@smallexample 8854#0 equal (val=5) 8855#0 different (val=6) 8856#0 lost (val@@entry=5) 8857#0 born (val=10) 8858#0 invalid (val=<optimized out>) 8859@end smallexample 8860 8861@item both 8862Always print both the actual parameter value and its value from function entry 8863point, even if values of one or both are not available due to compiler 8864optimizations. 8865@smallexample 8866#0 equal (val=5, val@@entry=5) 8867#0 different (val=6, val@@entry=5) 8868#0 lost (val=<optimized out>, val@@entry=5) 8869#0 born (val=10, val@@entry=<optimized out>) 8870#0 invalid (val=<optimized out>, val@@entry=<optimized out>) 8871@end smallexample 8872 8873@item compact 8874Print the actual parameter value if it is known and also its value from 8875function entry point if it is known. If neither is known, print for the actual 8876value @code{<optimized out>}. If not in MI mode (@pxref{GDB/MI}) and if both 8877values are known and identical, print the shortened 8878@code{param=param@@entry=VALUE} notation. 8879@smallexample 8880#0 equal (val=val@@entry=5) 8881#0 different (val=6, val@@entry=5) 8882#0 lost (val@@entry=5) 8883#0 born (val=10) 8884#0 invalid (val=<optimized out>) 8885@end smallexample 8886 8887@item default 8888Always print the actual parameter value. Print also its value from function 8889entry point, but only if it is known. If not in MI mode (@pxref{GDB/MI}) and 8890if both values are known and identical, print the shortened 8891@code{param=param@@entry=VALUE} notation. 8892@smallexample 8893#0 equal (val=val@@entry=5) 8894#0 different (val=6, val@@entry=5) 8895#0 lost (val=<optimized out>, val@@entry=5) 8896#0 born (val=10) 8897#0 invalid (val=<optimized out>) 8898@end smallexample 8899@end table 8900 8901For analysis messages on possible failures of frame argument values at function 8902entry resolution see @ref{set debug entry-values}. 8903 8904@item show print entry-values 8905Show the method being used for printing of frame argument values at function 8906entry. 8907 8908@item set print repeats 8909@cindex repeated array elements 8910Set the threshold for suppressing display of repeated array 8911elements. When the number of consecutive identical elements of an 8912array exceeds the threshold, @value{GDBN} prints the string 8913@code{"<repeats @var{n} times>"}, where @var{n} is the number of 8914identical repetitions, instead of displaying the identical elements 8915themselves. Setting the threshold to zero will cause all elements to 8916be individually printed. The default threshold is 10. 8917 8918@item show print repeats 8919Display the current threshold for printing repeated identical 8920elements. 8921 8922@item set print null-stop 8923@cindex @sc{null} elements in arrays 8924Cause @value{GDBN} to stop printing the characters of an array when the first 8925@sc{null} is encountered. This is useful when large arrays actually 8926contain only short strings. 8927The default is off. 8928 8929@item show print null-stop 8930Show whether @value{GDBN} stops printing an array on the first 8931@sc{null} character. 8932 8933@item set print pretty on 8934@cindex print structures in indented form 8935@cindex indentation in structure display 8936Cause @value{GDBN} to print structures in an indented format with one member 8937per line, like this: 8938 8939@smallexample 8940@group 8941$1 = @{ 8942 next = 0x0, 8943 flags = @{ 8944 sweet = 1, 8945 sour = 1 8946 @}, 8947 meat = 0x54 "Pork" 8948@} 8949@end group 8950@end smallexample 8951 8952@item set print pretty off 8953Cause @value{GDBN} to print structures in a compact format, like this: 8954 8955@smallexample 8956@group 8957$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \ 8958meat = 0x54 "Pork"@} 8959@end group 8960@end smallexample 8961 8962@noindent 8963This is the default format. 8964 8965@item show print pretty 8966Show which format @value{GDBN} is using to print structures. 8967 8968@item set print sevenbit-strings on 8969@cindex eight-bit characters in strings 8970@cindex octal escapes in strings 8971Print using only seven-bit characters; if this option is set, 8972@value{GDBN} displays any eight-bit characters (in strings or 8973character values) using the notation @code{\}@var{nnn}. This setting is 8974best if you are working in English (@sc{ascii}) and you use the 8975high-order bit of characters as a marker or ``meta'' bit. 8976 8977@item set print sevenbit-strings off 8978Print full eight-bit characters. This allows the use of more 8979international character sets, and is the default. 8980 8981@item show print sevenbit-strings 8982Show whether or not @value{GDBN} is printing only seven-bit characters. 8983 8984@item set print union on 8985@cindex unions in structures, printing 8986Tell @value{GDBN} to print unions which are contained in structures 8987and other unions. This is the default setting. 8988 8989@item set print union off 8990Tell @value{GDBN} not to print unions which are contained in 8991structures and other unions. @value{GDBN} will print @code{"@{...@}"} 8992instead. 8993 8994@item show print union 8995Ask @value{GDBN} whether or not it will print unions which are contained in 8996structures and other unions. 8997 8998For example, given the declarations 8999 9000@smallexample 9001typedef enum @{Tree, Bug@} Species; 9002typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms; 9003typedef enum @{Caterpillar, Cocoon, Butterfly@} 9004 Bug_forms; 9005 9006struct thing @{ 9007 Species it; 9008 union @{ 9009 Tree_forms tree; 9010 Bug_forms bug; 9011 @} form; 9012@}; 9013 9014struct thing foo = @{Tree, @{Acorn@}@}; 9015@end smallexample 9016 9017@noindent 9018with @code{set print union on} in effect @samp{p foo} would print 9019 9020@smallexample 9021$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@} 9022@end smallexample 9023 9024@noindent 9025and with @code{set print union off} in effect it would print 9026 9027@smallexample 9028$1 = @{it = Tree, form = @{...@}@} 9029@end smallexample 9030 9031@noindent 9032@code{set print union} affects programs written in C-like languages 9033and in Pascal. 9034@end table 9035 9036@need 1000 9037@noindent 9038These settings are of interest when debugging C@t{++} programs: 9039 9040@table @code 9041@cindex demangling C@t{++} names 9042@item set print demangle 9043@itemx set print demangle on 9044Print C@t{++} names in their source form rather than in the encoded 9045(``mangled'') form passed to the assembler and linker for type-safe 9046linkage. The default is on. 9047 9048@item show print demangle 9049Show whether C@t{++} names are printed in mangled or demangled form. 9050 9051@item set print asm-demangle 9052@itemx set print asm-demangle on 9053Print C@t{++} names in their source form rather than their mangled form, even 9054in assembler code printouts such as instruction disassemblies. 9055The default is off. 9056 9057@item show print asm-demangle 9058Show whether C@t{++} names in assembly listings are printed in mangled 9059or demangled form. 9060 9061@cindex C@t{++} symbol decoding style 9062@cindex symbol decoding style, C@t{++} 9063@kindex set demangle-style 9064@item set demangle-style @var{style} 9065Choose among several encoding schemes used by different compilers to 9066represent C@t{++} names. The choices for @var{style} are currently: 9067 9068@table @code 9069@item auto 9070Allow @value{GDBN} to choose a decoding style by inspecting your program. 9071This is the default. 9072 9073@item gnu 9074Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm. 9075 9076@item hp 9077Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm. 9078 9079@item lucid 9080Decode based on the Lucid C@t{++} compiler (@code{lcc}) encoding algorithm. 9081 9082@item arm 9083Decode using the algorithm in the @cite{C@t{++} Annotated Reference Manual}. 9084@strong{Warning:} this setting alone is not sufficient to allow 9085debugging @code{cfront}-generated executables. @value{GDBN} would 9086require further enhancement to permit that. 9087 9088@end table 9089If you omit @var{style}, you will see a list of possible formats. 9090 9091@item show demangle-style 9092Display the encoding style currently in use for decoding C@t{++} symbols. 9093 9094@item set print object 9095@itemx set print object on 9096@cindex derived type of an object, printing 9097@cindex display derived types 9098When displaying a pointer to an object, identify the @emph{actual} 9099(derived) type of the object rather than the @emph{declared} type, using 9100the virtual function table. Note that the virtual function table is 9101required---this feature can only work for objects that have run-time 9102type identification; a single virtual method in the object's declared 9103type is sufficient. Note that this setting is also taken into account when 9104working with variable objects via MI (@pxref{GDB/MI}). 9105 9106@item set print object off 9107Display only the declared type of objects, without reference to the 9108virtual function table. This is the default setting. 9109 9110@item show print object 9111Show whether actual, or declared, object types are displayed. 9112 9113@item set print static-members 9114@itemx set print static-members on 9115@cindex static members of C@t{++} objects 9116Print static members when displaying a C@t{++} object. The default is on. 9117 9118@item set print static-members off 9119Do not print static members when displaying a C@t{++} object. 9120 9121@item show print static-members 9122Show whether C@t{++} static members are printed or not. 9123 9124@item set print pascal_static-members 9125@itemx set print pascal_static-members on 9126@cindex static members of Pascal objects 9127@cindex Pascal objects, static members display 9128Print static members when displaying a Pascal object. The default is on. 9129 9130@item set print pascal_static-members off 9131Do not print static members when displaying a Pascal object. 9132 9133@item show print pascal_static-members 9134Show whether Pascal static members are printed or not. 9135 9136@c These don't work with HP ANSI C++ yet. 9137@item set print vtbl 9138@itemx set print vtbl on 9139@cindex pretty print C@t{++} virtual function tables 9140@cindex virtual functions (C@t{++}) display 9141@cindex VTBL display 9142Pretty print C@t{++} virtual function tables. The default is off. 9143(The @code{vtbl} commands do not work on programs compiled with the HP 9144ANSI C@t{++} compiler (@code{aCC}).) 9145 9146@item set print vtbl off 9147Do not pretty print C@t{++} virtual function tables. 9148 9149@item show print vtbl 9150Show whether C@t{++} virtual function tables are pretty printed, or not. 9151@end table 9152 9153@node Pretty Printing 9154@section Pretty Printing 9155 9156@value{GDBN} provides a mechanism to allow pretty-printing of values using 9157Python code. It greatly simplifies the display of complex objects. This 9158mechanism works for both MI and the CLI. 9159 9160@menu 9161* Pretty-Printer Introduction:: Introduction to pretty-printers 9162* Pretty-Printer Example:: An example pretty-printer 9163* Pretty-Printer Commands:: Pretty-printer commands 9164@end menu 9165 9166@node Pretty-Printer Introduction 9167@subsection Pretty-Printer Introduction 9168 9169When @value{GDBN} prints a value, it first sees if there is a pretty-printer 9170registered for the value. If there is then @value{GDBN} invokes the 9171pretty-printer to print the value. Otherwise the value is printed normally. 9172 9173Pretty-printers are normally named. This makes them easy to manage. 9174The @samp{info pretty-printer} command will list all the installed 9175pretty-printers with their names. 9176If a pretty-printer can handle multiple data types, then its 9177@dfn{subprinters} are the printers for the individual data types. 9178Each such subprinter has its own name. 9179The format of the name is @var{printer-name};@var{subprinter-name}. 9180 9181Pretty-printers are installed by @dfn{registering} them with @value{GDBN}. 9182Typically they are automatically loaded and registered when the corresponding 9183debug information is loaded, thus making them available without having to 9184do anything special. 9185 9186There are three places where a pretty-printer can be registered. 9187 9188@itemize @bullet 9189@item 9190Pretty-printers registered globally are available when debugging 9191all inferiors. 9192 9193@item 9194Pretty-printers registered with a program space are available only 9195when debugging that program. 9196@xref{Progspaces In Python}, for more details on program spaces in Python. 9197 9198@item 9199Pretty-printers registered with an objfile are loaded and unloaded 9200with the corresponding objfile (e.g., shared library). 9201@xref{Objfiles In Python}, for more details on objfiles in Python. 9202@end itemize 9203 9204@xref{Selecting Pretty-Printers}, for further information on how 9205pretty-printers are selected, 9206 9207@xref{Writing a Pretty-Printer}, for implementing pretty printers 9208for new types. 9209 9210@node Pretty-Printer Example 9211@subsection Pretty-Printer Example 9212 9213Here is how a C@t{++} @code{std::string} looks without a pretty-printer: 9214 9215@smallexample 9216(@value{GDBP}) print s 9217$1 = @{ 9218 static npos = 4294967295, 9219 _M_dataplus = @{ 9220 <std::allocator<char>> = @{ 9221 <__gnu_cxx::new_allocator<char>> = @{ 9222 <No data fields>@}, <No data fields> 9223 @}, 9224 members of std::basic_string<char, std::char_traits<char>, 9225 std::allocator<char> >::_Alloc_hider: 9226 _M_p = 0x804a014 "abcd" 9227 @} 9228@} 9229@end smallexample 9230 9231With a pretty-printer for @code{std::string} only the contents are printed: 9232 9233@smallexample 9234(@value{GDBP}) print s 9235$2 = "abcd" 9236@end smallexample 9237 9238@node Pretty-Printer Commands 9239@subsection Pretty-Printer Commands 9240@cindex pretty-printer commands 9241 9242@table @code 9243@kindex info pretty-printer 9244@item info pretty-printer [@var{object-regexp} [@var{name-regexp}]] 9245Print the list of installed pretty-printers. 9246This includes disabled pretty-printers, which are marked as such. 9247 9248@var{object-regexp} is a regular expression matching the objects 9249whose pretty-printers to list. 9250Objects can be @code{global}, the program space's file 9251(@pxref{Progspaces In Python}), 9252and the object files within that program space (@pxref{Objfiles In Python}). 9253@xref{Selecting Pretty-Printers}, for details on how @value{GDBN} 9254looks up a printer from these three objects. 9255 9256@var{name-regexp} is a regular expression matching the name of the printers 9257to list. 9258 9259@kindex disable pretty-printer 9260@item disable pretty-printer [@var{object-regexp} [@var{name-regexp}]] 9261Disable pretty-printers matching @var{object-regexp} and @var{name-regexp}. 9262A disabled pretty-printer is not forgotten, it may be enabled again later. 9263 9264@kindex enable pretty-printer 9265@item enable pretty-printer [@var{object-regexp} [@var{name-regexp}]] 9266Enable pretty-printers matching @var{object-regexp} and @var{name-regexp}. 9267@end table 9268 9269Example: 9270 9271Suppose we have three pretty-printers installed: one from library1.so 9272named @code{foo} that prints objects of type @code{foo}, and 9273another from library2.so named @code{bar} that prints two types of objects, 9274@code{bar1} and @code{bar2}. 9275 9276@smallexample 9277(gdb) info pretty-printer 9278library1.so: 9279 foo 9280library2.so: 9281 bar 9282 bar1 9283 bar2 9284(gdb) info pretty-printer library2 9285library2.so: 9286 bar 9287 bar1 9288 bar2 9289(gdb) disable pretty-printer library1 92901 printer disabled 92912 of 3 printers enabled 9292(gdb) info pretty-printer 9293library1.so: 9294 foo [disabled] 9295library2.so: 9296 bar 9297 bar1 9298 bar2 9299(gdb) disable pretty-printer library2 bar:bar1 93001 printer disabled 93011 of 3 printers enabled 9302(gdb) info pretty-printer library2 9303library1.so: 9304 foo [disabled] 9305library2.so: 9306 bar 9307 bar1 [disabled] 9308 bar2 9309(gdb) disable pretty-printer library2 bar 93101 printer disabled 93110 of 3 printers enabled 9312(gdb) info pretty-printer library2 9313library1.so: 9314 foo [disabled] 9315library2.so: 9316 bar [disabled] 9317 bar1 [disabled] 9318 bar2 9319@end smallexample 9320 9321Note that for @code{bar} the entire printer can be disabled, 9322as can each individual subprinter. 9323 9324@node Value History 9325@section Value History 9326 9327@cindex value history 9328@cindex history of values printed by @value{GDBN} 9329Values printed by the @code{print} command are saved in the @value{GDBN} 9330@dfn{value history}. This allows you to refer to them in other expressions. 9331Values are kept until the symbol table is re-read or discarded 9332(for example with the @code{file} or @code{symbol-file} commands). 9333When the symbol table changes, the value history is discarded, 9334since the values may contain pointers back to the types defined in the 9335symbol table. 9336 9337@cindex @code{$} 9338@cindex @code{$$} 9339@cindex history number 9340The values printed are given @dfn{history numbers} by which you can 9341refer to them. These are successive integers starting with one. 9342@code{print} shows you the history number assigned to a value by 9343printing @samp{$@var{num} = } before the value; here @var{num} is the 9344history number. 9345 9346To refer to any previous value, use @samp{$} followed by the value's 9347history number. The way @code{print} labels its output is designed to 9348remind you of this. Just @code{$} refers to the most recent value in 9349the history, and @code{$$} refers to the value before that. 9350@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2} 9351is the value just prior to @code{$$}, @code{$$1} is equivalent to 9352@code{$$}, and @code{$$0} is equivalent to @code{$}. 9353 9354For example, suppose you have just printed a pointer to a structure and 9355want to see the contents of the structure. It suffices to type 9356 9357@smallexample 9358p *$ 9359@end smallexample 9360 9361If you have a chain of structures where the component @code{next} points 9362to the next one, you can print the contents of the next one with this: 9363 9364@smallexample 9365p *$.next 9366@end smallexample 9367 9368@noindent 9369You can print successive links in the chain by repeating this 9370command---which you can do by just typing @key{RET}. 9371 9372Note that the history records values, not expressions. If the value of 9373@code{x} is 4 and you type these commands: 9374 9375@smallexample 9376print x 9377set x=5 9378@end smallexample 9379 9380@noindent 9381then the value recorded in the value history by the @code{print} command 9382remains 4 even though the value of @code{x} has changed. 9383 9384@table @code 9385@kindex show values 9386@item show values 9387Print the last ten values in the value history, with their item numbers. 9388This is like @samp{p@ $$9} repeated ten times, except that @code{show 9389values} does not change the history. 9390 9391@item show values @var{n} 9392Print ten history values centered on history item number @var{n}. 9393 9394@item show values + 9395Print ten history values just after the values last printed. If no more 9396values are available, @code{show values +} produces no display. 9397@end table 9398 9399Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the 9400same effect as @samp{show values +}. 9401 9402@node Convenience Vars 9403@section Convenience Variables 9404 9405@cindex convenience variables 9406@cindex user-defined variables 9407@value{GDBN} provides @dfn{convenience variables} that you can use within 9408@value{GDBN} to hold on to a value and refer to it later. These variables 9409exist entirely within @value{GDBN}; they are not part of your program, and 9410setting a convenience variable has no direct effect on further execution 9411of your program. That is why you can use them freely. 9412 9413Convenience variables are prefixed with @samp{$}. Any name preceded by 9414@samp{$} can be used for a convenience variable, unless it is one of 9415the predefined machine-specific register names (@pxref{Registers, ,Registers}). 9416(Value history references, in contrast, are @emph{numbers} preceded 9417by @samp{$}. @xref{Value History, ,Value History}.) 9418 9419You can save a value in a convenience variable with an assignment 9420expression, just as you would set a variable in your program. 9421For example: 9422 9423@smallexample 9424set $foo = *object_ptr 9425@end smallexample 9426 9427@noindent 9428would save in @code{$foo} the value contained in the object pointed to by 9429@code{object_ptr}. 9430 9431Using a convenience variable for the first time creates it, but its 9432value is @code{void} until you assign a new value. You can alter the 9433value with another assignment at any time. 9434 9435Convenience variables have no fixed types. You can assign a convenience 9436variable any type of value, including structures and arrays, even if 9437that variable already has a value of a different type. The convenience 9438variable, when used as an expression, has the type of its current value. 9439 9440@table @code 9441@kindex show convenience 9442@cindex show all user variables and functions 9443@item show convenience 9444Print a list of convenience variables used so far, and their values, 9445as well as a list of the convenience functions. 9446Abbreviated @code{show conv}. 9447 9448@kindex init-if-undefined 9449@cindex convenience variables, initializing 9450@item init-if-undefined $@var{variable} = @var{expression} 9451Set a convenience variable if it has not already been set. This is useful 9452for user-defined commands that keep some state. It is similar, in concept, 9453to using local static variables with initializers in C (except that 9454convenience variables are global). It can also be used to allow users to 9455override default values used in a command script. 9456 9457If the variable is already defined then the expression is not evaluated so 9458any side-effects do not occur. 9459@end table 9460 9461One of the ways to use a convenience variable is as a counter to be 9462incremented or a pointer to be advanced. For example, to print 9463a field from successive elements of an array of structures: 9464 9465@smallexample 9466set $i = 0 9467print bar[$i++]->contents 9468@end smallexample 9469 9470@noindent 9471Repeat that command by typing @key{RET}. 9472 9473Some convenience variables are created automatically by @value{GDBN} and given 9474values likely to be useful. 9475 9476@table @code 9477@vindex $_@r{, convenience variable} 9478@item $_ 9479The variable @code{$_} is automatically set by the @code{x} command to 9480the last address examined (@pxref{Memory, ,Examining Memory}). Other 9481commands which provide a default address for @code{x} to examine also 9482set @code{$_} to that address; these commands include @code{info line} 9483and @code{info breakpoint}. The type of @code{$_} is @code{void *} 9484except when set by the @code{x} command, in which case it is a pointer 9485to the type of @code{$__}. 9486 9487@vindex $__@r{, convenience variable} 9488@item $__ 9489The variable @code{$__} is automatically set by the @code{x} command 9490to the value found in the last address examined. Its type is chosen 9491to match the format in which the data was printed. 9492 9493@item $_exitcode 9494@vindex $_exitcode@r{, convenience variable} 9495The variable @code{$_exitcode} is automatically set to the exit code when 9496the program being debugged terminates. 9497 9498@item $_probe_argc 9499@itemx $_probe_arg0@dots{}$_probe_arg11 9500Arguments to a static probe. @xref{Static Probe Points}. 9501 9502@item $_sdata 9503@vindex $_sdata@r{, inspect, convenience variable} 9504The variable @code{$_sdata} contains extra collected static tracepoint 9505data. @xref{Tracepoint Actions,,Tracepoint Action Lists}. Note that 9506@code{$_sdata} could be empty, if not inspecting a trace buffer, or 9507if extra static tracepoint data has not been collected. 9508 9509@item $_siginfo 9510@vindex $_siginfo@r{, convenience variable} 9511The variable @code{$_siginfo} contains extra signal information 9512(@pxref{extra signal information}). Note that @code{$_siginfo} 9513could be empty, if the application has not yet received any signals. 9514For example, it will be empty before you execute the @code{run} command. 9515 9516@item $_tlb 9517@vindex $_tlb@r{, convenience variable} 9518The variable @code{$_tlb} is automatically set when debugging 9519applications running on MS-Windows in native mode or connected to 9520gdbserver that supports the @code{qGetTIBAddr} request. 9521@xref{General Query Packets}. 9522This variable contains the address of the thread information block. 9523 9524@end table 9525 9526On HP-UX systems, if you refer to a function or variable name that 9527begins with a dollar sign, @value{GDBN} searches for a user or system 9528name first, before it searches for a convenience variable. 9529 9530@node Convenience Funs 9531@section Convenience Functions 9532 9533@cindex convenience functions 9534@value{GDBN} also supplies some @dfn{convenience functions}. These 9535have a syntax similar to convenience variables. A convenience 9536function can be used in an expression just like an ordinary function; 9537however, a convenience function is implemented internally to 9538@value{GDBN}. 9539 9540These functions require @value{GDBN} to be configured with 9541@code{Python} support. 9542 9543@table @code 9544 9545@item $_memeq(@var{buf1}, @var{buf2}, @var{length}) 9546@findex $_memeq@r{, convenience function} 9547Returns one if the @var{length} bytes at the addresses given by 9548@var{buf1} and @var{buf2} are equal. 9549Otherwise it returns zero. 9550 9551@item $_regex(@var{str}, @var{regex}) 9552@findex $_regex@r{, convenience function} 9553Returns one if the string @var{str} matches the regular expression 9554@var{regex}. Otherwise it returns zero. 9555The syntax of the regular expression is that specified by @code{Python}'s 9556regular expression support. 9557 9558@item $_streq(@var{str1}, @var{str2}) 9559@findex $_streq@r{, convenience function} 9560Returns one if the strings @var{str1} and @var{str2} are equal. 9561Otherwise it returns zero. 9562 9563@item $_strlen(@var{str}) 9564@findex $_strlen@r{, convenience function} 9565Returns the length of string @var{str}. 9566 9567@end table 9568 9569@value{GDBN} provides the ability to list and get help on 9570convenience functions. 9571 9572@table @code 9573@item help function 9574@kindex help function 9575@cindex show all convenience functions 9576Print a list of all convenience functions. 9577@end table 9578 9579@node Registers 9580@section Registers 9581 9582@cindex registers 9583You can refer to machine register contents, in expressions, as variables 9584with names starting with @samp{$}. The names of registers are different 9585for each machine; use @code{info registers} to see the names used on 9586your machine. 9587 9588@table @code 9589@kindex info registers 9590@item info registers 9591Print the names and values of all registers except floating-point 9592and vector registers (in the selected stack frame). 9593 9594@kindex info all-registers 9595@cindex floating point registers 9596@item info all-registers 9597Print the names and values of all registers, including floating-point 9598and vector registers (in the selected stack frame). 9599 9600@item info registers @var{regname} @dots{} 9601Print the @dfn{relativized} value of each specified register @var{regname}. 9602As discussed in detail below, register values are normally relative to 9603the selected stack frame. @var{regname} may be any register name valid on 9604the machine you are using, with or without the initial @samp{$}. 9605@end table 9606 9607@cindex stack pointer register 9608@cindex program counter register 9609@cindex process status register 9610@cindex frame pointer register 9611@cindex standard registers 9612@value{GDBN} has four ``standard'' register names that are available (in 9613expressions) on most machines---whenever they do not conflict with an 9614architecture's canonical mnemonics for registers. The register names 9615@code{$pc} and @code{$sp} are used for the program counter register and 9616the stack pointer. @code{$fp} is used for a register that contains a 9617pointer to the current stack frame, and @code{$ps} is used for a 9618register that contains the processor status. For example, 9619you could print the program counter in hex with 9620 9621@smallexample 9622p/x $pc 9623@end smallexample 9624 9625@noindent 9626or print the instruction to be executed next with 9627 9628@smallexample 9629x/i $pc 9630@end smallexample 9631 9632@noindent 9633or add four to the stack pointer@footnote{This is a way of removing 9634one word from the stack, on machines where stacks grow downward in 9635memory (most machines, nowadays). This assumes that the innermost 9636stack frame is selected; setting @code{$sp} is not allowed when other 9637stack frames are selected. To pop entire frames off the stack, 9638regardless of machine architecture, use @code{return}; 9639see @ref{Returning, ,Returning from a Function}.} with 9640 9641@smallexample 9642set $sp += 4 9643@end smallexample 9644 9645Whenever possible, these four standard register names are available on 9646your machine even though the machine has different canonical mnemonics, 9647so long as there is no conflict. The @code{info registers} command 9648shows the canonical names. For example, on the SPARC, @code{info 9649registers} displays the processor status register as @code{$psr} but you 9650can also refer to it as @code{$ps}; and on x86-based machines @code{$ps} 9651is an alias for the @sc{eflags} register. 9652 9653@value{GDBN} always considers the contents of an ordinary register as an 9654integer when the register is examined in this way. Some machines have 9655special registers which can hold nothing but floating point; these 9656registers are considered to have floating point values. There is no way 9657to refer to the contents of an ordinary register as floating point value 9658(although you can @emph{print} it as a floating point value with 9659@samp{print/f $@var{regname}}). 9660 9661Some registers have distinct ``raw'' and ``virtual'' data formats. This 9662means that the data format in which the register contents are saved by 9663the operating system is not the same one that your program normally 9664sees. For example, the registers of the 68881 floating point 9665coprocessor are always saved in ``extended'' (raw) format, but all C 9666programs expect to work with ``double'' (virtual) format. In such 9667cases, @value{GDBN} normally works with the virtual format only (the format 9668that makes sense for your program), but the @code{info registers} command 9669prints the data in both formats. 9670 9671@cindex SSE registers (x86) 9672@cindex MMX registers (x86) 9673Some machines have special registers whose contents can be interpreted 9674in several different ways. For example, modern x86-based machines 9675have SSE and MMX registers that can hold several values packed 9676together in several different formats. @value{GDBN} refers to such 9677registers in @code{struct} notation: 9678 9679@smallexample 9680(@value{GDBP}) print $xmm1 9681$1 = @{ 9682 v4_float = @{0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044@}, 9683 v2_double = @{9.92129282474342e-303, 2.7585945287983262e-313@}, 9684 v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000", 9685 v8_int16 = @{0, 0, 14072, 315, 11, 0, 13, 0@}, 9686 v4_int32 = @{0, 20657912, 11, 13@}, 9687 v2_int64 = @{88725056443645952, 55834574859@}, 9688 uint128 = 0x0000000d0000000b013b36f800000000 9689@} 9690@end smallexample 9691 9692@noindent 9693To set values of such registers, you need to tell @value{GDBN} which 9694view of the register you wish to change, as if you were assigning 9695value to a @code{struct} member: 9696 9697@smallexample 9698 (@value{GDBP}) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF 9699@end smallexample 9700 9701Normally, register values are relative to the selected stack frame 9702(@pxref{Selection, ,Selecting a Frame}). This means that you get the 9703value that the register would contain if all stack frames farther in 9704were exited and their saved registers restored. In order to see the 9705true contents of hardware registers, you must select the innermost 9706frame (with @samp{frame 0}). 9707 9708However, @value{GDBN} must deduce where registers are saved, from the machine 9709code generated by your compiler. If some registers are not saved, or if 9710@value{GDBN} is unable to locate the saved registers, the selected stack 9711frame makes no difference. 9712 9713@node Floating Point Hardware 9714@section Floating Point Hardware 9715@cindex floating point 9716 9717Depending on the configuration, @value{GDBN} may be able to give 9718you more information about the status of the floating point hardware. 9719 9720@table @code 9721@kindex info float 9722@item info float 9723Display hardware-dependent information about the floating 9724point unit. The exact contents and layout vary depending on the 9725floating point chip. Currently, @samp{info float} is supported on 9726the ARM and x86 machines. 9727@end table 9728 9729@node Vector Unit 9730@section Vector Unit 9731@cindex vector unit 9732 9733Depending on the configuration, @value{GDBN} may be able to give you 9734more information about the status of the vector unit. 9735 9736@table @code 9737@kindex info vector 9738@item info vector 9739Display information about the vector unit. The exact contents and 9740layout vary depending on the hardware. 9741@end table 9742 9743@node OS Information 9744@section Operating System Auxiliary Information 9745@cindex OS information 9746 9747@value{GDBN} provides interfaces to useful OS facilities that can help 9748you debug your program. 9749 9750@cindex auxiliary vector 9751@cindex vector, auxiliary 9752Some operating systems supply an @dfn{auxiliary vector} to programs at 9753startup. This is akin to the arguments and environment that you 9754specify for a program, but contains a system-dependent variety of 9755binary values that tell system libraries important details about the 9756hardware, operating system, and process. Each value's purpose is 9757identified by an integer tag; the meanings are well-known but system-specific. 9758Depending on the configuration and operating system facilities, 9759@value{GDBN} may be able to show you this information. For remote 9760targets, this functionality may further depend on the remote stub's 9761support of the @samp{qXfer:auxv:read} packet, see 9762@ref{qXfer auxiliary vector read}. 9763 9764@table @code 9765@kindex info auxv 9766@item info auxv 9767Display the auxiliary vector of the inferior, which can be either a 9768live process or a core dump file. @value{GDBN} prints each tag value 9769numerically, and also shows names and text descriptions for recognized 9770tags. Some values in the vector are numbers, some bit masks, and some 9771pointers to strings or other data. @value{GDBN} displays each value in the 9772most appropriate form for a recognized tag, and in hexadecimal for 9773an unrecognized tag. 9774@end table 9775 9776On some targets, @value{GDBN} can access operating system-specific 9777information and show it to you. The types of information available 9778will differ depending on the type of operating system running on the 9779target. The mechanism used to fetch the data is described in 9780@ref{Operating System Information}. For remote targets, this 9781functionality depends on the remote stub's support of the 9782@samp{qXfer:osdata:read} packet, see @ref{qXfer osdata read}. 9783 9784@table @code 9785@kindex info os 9786@item info os @var{infotype} 9787 9788Display OS information of the requested type. 9789 9790On @sc{gnu}/Linux, the following values of @var{infotype} are valid: 9791 9792@anchor{linux info os infotypes} 9793@table @code 9794@kindex info os processes 9795@item processes 9796Display the list of processes on the target. For each process, 9797@value{GDBN} prints the process identifier, the name of the user, the 9798command corresponding to the process, and the list of processor cores 9799that the process is currently running on. (To understand what these 9800properties mean, for this and the following info types, please consult 9801the general @sc{gnu}/Linux documentation.) 9802 9803@kindex info os procgroups 9804@item procgroups 9805Display the list of process groups on the target. For each process, 9806@value{GDBN} prints the identifier of the process group that it belongs 9807to, the command corresponding to the process group leader, the process 9808identifier, and the command line of the process. The list is sorted 9809first by the process group identifier, then by the process identifier, 9810so that processes belonging to the same process group are grouped together 9811and the process group leader is listed first. 9812 9813@kindex info os threads 9814@item threads 9815Display the list of threads running on the target. For each thread, 9816@value{GDBN} prints the identifier of the process that the thread 9817belongs to, the command of the process, the thread identifier, and the 9818processor core that it is currently running on. The main thread of a 9819process is not listed. 9820 9821@kindex info os files 9822@item files 9823Display the list of open file descriptors on the target. For each 9824file descriptor, @value{GDBN} prints the identifier of the process 9825owning the descriptor, the command of the owning process, the value 9826of the descriptor, and the target of the descriptor. 9827 9828@kindex info os sockets 9829@item sockets 9830Display the list of Internet-domain sockets on the target. For each 9831socket, @value{GDBN} prints the address and port of the local and 9832remote endpoints, the current state of the connection, the creator of 9833the socket, the IP address family of the socket, and the type of the 9834connection. 9835 9836@kindex info os shm 9837@item shm 9838Display the list of all System V shared-memory regions on the target. 9839For each shared-memory region, @value{GDBN} prints the region key, 9840the shared-memory identifier, the access permissions, the size of the 9841region, the process that created the region, the process that last 9842attached to or detached from the region, the current number of live 9843attaches to the region, and the times at which the region was last 9844attached to, detach from, and changed. 9845 9846@kindex info os semaphores 9847@item semaphores 9848Display the list of all System V semaphore sets on the target. For each 9849semaphore set, @value{GDBN} prints the semaphore set key, the semaphore 9850set identifier, the access permissions, the number of semaphores in the 9851set, the user and group of the owner and creator of the semaphore set, 9852and the times at which the semaphore set was operated upon and changed. 9853 9854@kindex info os msg 9855@item msg 9856Display the list of all System V message queues on the target. For each 9857message queue, @value{GDBN} prints the message queue key, the message 9858queue identifier, the access permissions, the current number of bytes 9859on the queue, the current number of messages on the queue, the processes 9860that last sent and received a message on the queue, the user and group 9861of the owner and creator of the message queue, the times at which a 9862message was last sent and received on the queue, and the time at which 9863the message queue was last changed. 9864 9865@kindex info os modules 9866@item modules 9867Display the list of all loaded kernel modules on the target. For each 9868module, @value{GDBN} prints the module name, the size of the module in 9869bytes, the number of times the module is used, the dependencies of the 9870module, the status of the module, and the address of the loaded module 9871in memory. 9872@end table 9873 9874@item info os 9875If @var{infotype} is omitted, then list the possible values for 9876@var{infotype} and the kind of OS information available for each 9877@var{infotype}. If the target does not return a list of possible 9878types, this command will report an error. 9879@end table 9880 9881@node Memory Region Attributes 9882@section Memory Region Attributes 9883@cindex memory region attributes 9884 9885@dfn{Memory region attributes} allow you to describe special handling 9886required by regions of your target's memory. @value{GDBN} uses 9887attributes to determine whether to allow certain types of memory 9888accesses; whether to use specific width accesses; and whether to cache 9889target memory. By default the description of memory regions is 9890fetched from the target (if the current target supports this), but the 9891user can override the fetched regions. 9892 9893Defined memory regions can be individually enabled and disabled. When a 9894memory region is disabled, @value{GDBN} uses the default attributes when 9895accessing memory in that region. Similarly, if no memory regions have 9896been defined, @value{GDBN} uses the default attributes when accessing 9897all memory. 9898 9899When a memory region is defined, it is given a number to identify it; 9900to enable, disable, or remove a memory region, you specify that number. 9901 9902@table @code 9903@kindex mem 9904@item mem @var{lower} @var{upper} @var{attributes}@dots{} 9905Define a memory region bounded by @var{lower} and @var{upper} with 9906attributes @var{attributes}@dots{}, and add it to the list of regions 9907monitored by @value{GDBN}. Note that @var{upper} == 0 is a special 9908case: it is treated as the target's maximum memory address. 9909(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.) 9910 9911@item mem auto 9912Discard any user changes to the memory regions and use target-supplied 9913regions, if available, or no regions if the target does not support. 9914 9915@kindex delete mem 9916@item delete mem @var{nums}@dots{} 9917Remove memory regions @var{nums}@dots{} from the list of regions 9918monitored by @value{GDBN}. 9919 9920@kindex disable mem 9921@item disable mem @var{nums}@dots{} 9922Disable monitoring of memory regions @var{nums}@dots{}. 9923A disabled memory region is not forgotten. 9924It may be enabled again later. 9925 9926@kindex enable mem 9927@item enable mem @var{nums}@dots{} 9928Enable monitoring of memory regions @var{nums}@dots{}. 9929 9930@kindex info mem 9931@item info mem 9932Print a table of all defined memory regions, with the following columns 9933for each region: 9934 9935@table @emph 9936@item Memory Region Number 9937@item Enabled or Disabled. 9938Enabled memory regions are marked with @samp{y}. 9939Disabled memory regions are marked with @samp{n}. 9940 9941@item Lo Address 9942The address defining the inclusive lower bound of the memory region. 9943 9944@item Hi Address 9945The address defining the exclusive upper bound of the memory region. 9946 9947@item Attributes 9948The list of attributes set for this memory region. 9949@end table 9950@end table 9951 9952 9953@subsection Attributes 9954 9955@subsubsection Memory Access Mode 9956The access mode attributes set whether @value{GDBN} may make read or 9957write accesses to a memory region. 9958 9959While these attributes prevent @value{GDBN} from performing invalid 9960memory accesses, they do nothing to prevent the target system, I/O DMA, 9961etc.@: from accessing memory. 9962 9963@table @code 9964@item ro 9965Memory is read only. 9966@item wo 9967Memory is write only. 9968@item rw 9969Memory is read/write. This is the default. 9970@end table 9971 9972@subsubsection Memory Access Size 9973The access size attribute tells @value{GDBN} to use specific sized 9974accesses in the memory region. Often memory mapped device registers 9975require specific sized accesses. If no access size attribute is 9976specified, @value{GDBN} may use accesses of any size. 9977 9978@table @code 9979@item 8 9980Use 8 bit memory accesses. 9981@item 16 9982Use 16 bit memory accesses. 9983@item 32 9984Use 32 bit memory accesses. 9985@item 64 9986Use 64 bit memory accesses. 9987@end table 9988 9989@c @subsubsection Hardware/Software Breakpoints 9990@c The hardware/software breakpoint attributes set whether @value{GDBN} 9991@c will use hardware or software breakpoints for the internal breakpoints 9992@c used by the step, next, finish, until, etc. commands. 9993@c 9994@c @table @code 9995@c @item hwbreak 9996@c Always use hardware breakpoints 9997@c @item swbreak (default) 9998@c @end table 9999 10000@subsubsection Data Cache 10001The data cache attributes set whether @value{GDBN} will cache target 10002memory. While this generally improves performance by reducing debug 10003protocol overhead, it can lead to incorrect results because @value{GDBN} 10004does not know about volatile variables or memory mapped device 10005registers. 10006 10007@table @code 10008@item cache 10009Enable @value{GDBN} to cache target memory. 10010@item nocache 10011Disable @value{GDBN} from caching target memory. This is the default. 10012@end table 10013 10014@subsection Memory Access Checking 10015@value{GDBN} can be instructed to refuse accesses to memory that is 10016not explicitly described. This can be useful if accessing such 10017regions has undesired effects for a specific target, or to provide 10018better error checking. The following commands control this behaviour. 10019 10020@table @code 10021@kindex set mem inaccessible-by-default 10022@item set mem inaccessible-by-default [on|off] 10023If @code{on} is specified, make @value{GDBN} treat memory not 10024explicitly described by the memory ranges as non-existent and refuse accesses 10025to such memory. The checks are only performed if there's at least one 10026memory range defined. If @code{off} is specified, make @value{GDBN} 10027treat the memory not explicitly described by the memory ranges as RAM. 10028The default value is @code{on}. 10029@kindex show mem inaccessible-by-default 10030@item show mem inaccessible-by-default 10031Show the current handling of accesses to unknown memory. 10032@end table 10033 10034 10035@c @subsubsection Memory Write Verification 10036@c The memory write verification attributes set whether @value{GDBN} 10037@c will re-reads data after each write to verify the write was successful. 10038@c 10039@c @table @code 10040@c @item verify 10041@c @item noverify (default) 10042@c @end table 10043 10044@node Dump/Restore Files 10045@section Copy Between Memory and a File 10046@cindex dump/restore files 10047@cindex append data to a file 10048@cindex dump data to a file 10049@cindex restore data from a file 10050 10051You can use the commands @code{dump}, @code{append}, and 10052@code{restore} to copy data between target memory and a file. The 10053@code{dump} and @code{append} commands write data to a file, and the 10054@code{restore} command reads data from a file back into the inferior's 10055memory. Files may be in binary, Motorola S-record, Intel hex, or 10056Tektronix Hex format; however, @value{GDBN} can only append to binary 10057files. 10058 10059@table @code 10060 10061@kindex dump 10062@item dump @r{[}@var{format}@r{]} memory @var{filename} @var{start_addr} @var{end_addr} 10063@itemx dump @r{[}@var{format}@r{]} value @var{filename} @var{expr} 10064Dump the contents of memory from @var{start_addr} to @var{end_addr}, 10065or the value of @var{expr}, to @var{filename} in the given format. 10066 10067The @var{format} parameter may be any one of: 10068@table @code 10069@item binary 10070Raw binary form. 10071@item ihex 10072Intel hex format. 10073@item srec 10074Motorola S-record format. 10075@item tekhex 10076Tektronix Hex format. 10077@end table 10078 10079@value{GDBN} uses the same definitions of these formats as the 10080@sc{gnu} binary utilities, like @samp{objdump} and @samp{objcopy}. If 10081@var{format} is omitted, @value{GDBN} dumps the data in raw binary 10082form. 10083 10084@kindex append 10085@item append @r{[}binary@r{]} memory @var{filename} @var{start_addr} @var{end_addr} 10086@itemx append @r{[}binary@r{]} value @var{filename} @var{expr} 10087Append the contents of memory from @var{start_addr} to @var{end_addr}, 10088or the value of @var{expr}, to the file @var{filename}, in raw binary form. 10089(@value{GDBN} can only append data to files in raw binary form.) 10090 10091@kindex restore 10092@item restore @var{filename} @r{[}binary@r{]} @var{bias} @var{start} @var{end} 10093Restore the contents of file @var{filename} into memory. The 10094@code{restore} command can automatically recognize any known @sc{bfd} 10095file format, except for raw binary. To restore a raw binary file you 10096must specify the optional keyword @code{binary} after the filename. 10097 10098If @var{bias} is non-zero, its value will be added to the addresses 10099contained in the file. Binary files always start at address zero, so 10100they will be restored at address @var{bias}. Other bfd files have 10101a built-in location; they will be restored at offset @var{bias} 10102from that location. 10103 10104If @var{start} and/or @var{end} are non-zero, then only data between 10105file offset @var{start} and file offset @var{end} will be restored. 10106These offsets are relative to the addresses in the file, before 10107the @var{bias} argument is applied. 10108 10109@end table 10110 10111@node Core File Generation 10112@section How to Produce a Core File from Your Program 10113@cindex dump core from inferior 10114 10115A @dfn{core file} or @dfn{core dump} is a file that records the memory 10116image of a running process and its process status (register values 10117etc.). Its primary use is post-mortem debugging of a program that 10118crashed while it ran outside a debugger. A program that crashes 10119automatically produces a core file, unless this feature is disabled by 10120the user. @xref{Files}, for information on invoking @value{GDBN} in 10121the post-mortem debugging mode. 10122 10123Occasionally, you may wish to produce a core file of the program you 10124are debugging in order to preserve a snapshot of its state. 10125@value{GDBN} has a special command for that. 10126 10127@table @code 10128@kindex gcore 10129@kindex generate-core-file 10130@item generate-core-file [@var{file}] 10131@itemx gcore [@var{file}] 10132Produce a core dump of the inferior process. The optional argument 10133@var{file} specifies the file name where to put the core dump. If not 10134specified, the file name defaults to @file{core.@var{pid}}, where 10135@var{pid} is the inferior process ID. 10136 10137Note that this command is implemented only for some systems (as of 10138this writing, @sc{gnu}/Linux, FreeBSD, Solaris, and S390). 10139@end table 10140 10141@node Character Sets 10142@section Character Sets 10143@cindex character sets 10144@cindex charset 10145@cindex translating between character sets 10146@cindex host character set 10147@cindex target character set 10148 10149If the program you are debugging uses a different character set to 10150represent characters and strings than the one @value{GDBN} uses itself, 10151@value{GDBN} can automatically translate between the character sets for 10152you. The character set @value{GDBN} uses we call the @dfn{host 10153character set}; the one the inferior program uses we call the 10154@dfn{target character set}. 10155 10156For example, if you are running @value{GDBN} on a @sc{gnu}/Linux system, which 10157uses the ISO Latin 1 character set, but you are using @value{GDBN}'s 10158remote protocol (@pxref{Remote Debugging}) to debug a program 10159running on an IBM mainframe, which uses the @sc{ebcdic} character set, 10160then the host character set is Latin-1, and the target character set is 10161@sc{ebcdic}. If you give @value{GDBN} the command @code{set 10162target-charset EBCDIC-US}, then @value{GDBN} translates between 10163@sc{ebcdic} and Latin 1 as you print character or string values, or use 10164character and string literals in expressions. 10165 10166@value{GDBN} has no way to automatically recognize which character set 10167the inferior program uses; you must tell it, using the @code{set 10168target-charset} command, described below. 10169 10170Here are the commands for controlling @value{GDBN}'s character set 10171support: 10172 10173@table @code 10174@item set target-charset @var{charset} 10175@kindex set target-charset 10176Set the current target character set to @var{charset}. To display the 10177list of supported target character sets, type 10178@kbd{@w{set target-charset @key{TAB}@key{TAB}}}. 10179 10180@item set host-charset @var{charset} 10181@kindex set host-charset 10182Set the current host character set to @var{charset}. 10183 10184By default, @value{GDBN} uses a host character set appropriate to the 10185system it is running on; you can override that default using the 10186@code{set host-charset} command. On some systems, @value{GDBN} cannot 10187automatically determine the appropriate host character set. In this 10188case, @value{GDBN} uses @samp{UTF-8}. 10189 10190@value{GDBN} can only use certain character sets as its host character 10191set. If you type @kbd{@w{set host-charset @key{TAB}@key{TAB}}}, 10192@value{GDBN} will list the host character sets it supports. 10193 10194@item set charset @var{charset} 10195@kindex set charset 10196Set the current host and target character sets to @var{charset}. As 10197above, if you type @kbd{@w{set charset @key{TAB}@key{TAB}}}, 10198@value{GDBN} will list the names of the character sets that can be used 10199for both host and target. 10200 10201@item show charset 10202@kindex show charset 10203Show the names of the current host and target character sets. 10204 10205@item show host-charset 10206@kindex show host-charset 10207Show the name of the current host character set. 10208 10209@item show target-charset 10210@kindex show target-charset 10211Show the name of the current target character set. 10212 10213@item set target-wide-charset @var{charset} 10214@kindex set target-wide-charset 10215Set the current target's wide character set to @var{charset}. This is 10216the character set used by the target's @code{wchar_t} type. To 10217display the list of supported wide character sets, type 10218@kbd{@w{set target-wide-charset @key{TAB}@key{TAB}}}. 10219 10220@item show target-wide-charset 10221@kindex show target-wide-charset 10222Show the name of the current target's wide character set. 10223@end table 10224 10225Here is an example of @value{GDBN}'s character set support in action. 10226Assume that the following source code has been placed in the file 10227@file{charset-test.c}: 10228 10229@smallexample 10230#include <stdio.h> 10231 10232char ascii_hello[] 10233 = @{72, 101, 108, 108, 111, 44, 32, 119, 10234 111, 114, 108, 100, 33, 10, 0@}; 10235char ibm1047_hello[] 10236 = @{200, 133, 147, 147, 150, 107, 64, 166, 10237 150, 153, 147, 132, 90, 37, 0@}; 10238 10239main () 10240@{ 10241 printf ("Hello, world!\n"); 10242@} 10243@end smallexample 10244 10245In this program, @code{ascii_hello} and @code{ibm1047_hello} are arrays 10246containing the string @samp{Hello, world!} followed by a newline, 10247encoded in the @sc{ascii} and @sc{ibm1047} character sets. 10248 10249We compile the program, and invoke the debugger on it: 10250 10251@smallexample 10252$ gcc -g charset-test.c -o charset-test 10253$ gdb -nw charset-test 10254GNU gdb 2001-12-19-cvs 10255Copyright 2001 Free Software Foundation, Inc. 10256@dots{} 10257(@value{GDBP}) 10258@end smallexample 10259 10260We can use the @code{show charset} command to see what character sets 10261@value{GDBN} is currently using to interpret and display characters and 10262strings: 10263 10264@smallexample 10265(@value{GDBP}) show charset 10266The current host and target character set is `ISO-8859-1'. 10267(@value{GDBP}) 10268@end smallexample 10269 10270For the sake of printing this manual, let's use @sc{ascii} as our 10271initial character set: 10272@smallexample 10273(@value{GDBP}) set charset ASCII 10274(@value{GDBP}) show charset 10275The current host and target character set is `ASCII'. 10276(@value{GDBP}) 10277@end smallexample 10278 10279Let's assume that @sc{ascii} is indeed the correct character set for our 10280host system --- in other words, let's assume that if @value{GDBN} prints 10281characters using the @sc{ascii} character set, our terminal will display 10282them properly. Since our current target character set is also 10283@sc{ascii}, the contents of @code{ascii_hello} print legibly: 10284 10285@smallexample 10286(@value{GDBP}) print ascii_hello 10287$1 = 0x401698 "Hello, world!\n" 10288(@value{GDBP}) print ascii_hello[0] 10289$2 = 72 'H' 10290(@value{GDBP}) 10291@end smallexample 10292 10293@value{GDBN} uses the target character set for character and string 10294literals you use in expressions: 10295 10296@smallexample 10297(@value{GDBP}) print '+' 10298$3 = 43 '+' 10299(@value{GDBP}) 10300@end smallexample 10301 10302The @sc{ascii} character set uses the number 43 to encode the @samp{+} 10303character. 10304 10305@value{GDBN} relies on the user to tell it which character set the 10306target program uses. If we print @code{ibm1047_hello} while our target 10307character set is still @sc{ascii}, we get jibberish: 10308 10309@smallexample 10310(@value{GDBP}) print ibm1047_hello 10311$4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%" 10312(@value{GDBP}) print ibm1047_hello[0] 10313$5 = 200 '\310' 10314(@value{GDBP}) 10315@end smallexample 10316 10317If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB}, 10318@value{GDBN} tells us the character sets it supports: 10319 10320@smallexample 10321(@value{GDBP}) set target-charset 10322ASCII EBCDIC-US IBM1047 ISO-8859-1 10323(@value{GDBP}) set target-charset 10324@end smallexample 10325 10326We can select @sc{ibm1047} as our target character set, and examine the 10327program's strings again. Now the @sc{ascii} string is wrong, but 10328@value{GDBN} translates the contents of @code{ibm1047_hello} from the 10329target character set, @sc{ibm1047}, to the host character set, 10330@sc{ascii}, and they display correctly: 10331 10332@smallexample 10333(@value{GDBP}) set target-charset IBM1047 10334(@value{GDBP}) show charset 10335The current host character set is `ASCII'. 10336The current target character set is `IBM1047'. 10337(@value{GDBP}) print ascii_hello 10338$6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" 10339(@value{GDBP}) print ascii_hello[0] 10340$7 = 72 '\110' 10341(@value{GDBP}) print ibm1047_hello 10342$8 = 0x4016a8 "Hello, world!\n" 10343(@value{GDBP}) print ibm1047_hello[0] 10344$9 = 200 'H' 10345(@value{GDBP}) 10346@end smallexample 10347 10348As above, @value{GDBN} uses the target character set for character and 10349string literals you use in expressions: 10350 10351@smallexample 10352(@value{GDBP}) print '+' 10353$10 = 78 '+' 10354(@value{GDBP}) 10355@end smallexample 10356 10357The @sc{ibm1047} character set uses the number 78 to encode the @samp{+} 10358character. 10359 10360@node Caching Remote Data 10361@section Caching Data of Remote Targets 10362@cindex caching data of remote targets 10363 10364@value{GDBN} caches data exchanged between the debugger and a 10365remote target (@pxref{Remote Debugging}). Such caching generally improves 10366performance, because it reduces the overhead of the remote protocol by 10367bundling memory reads and writes into large chunks. Unfortunately, simply 10368caching everything would lead to incorrect results, since @value{GDBN} 10369does not necessarily know anything about volatile values, memory-mapped I/O 10370addresses, etc. Furthermore, in non-stop mode (@pxref{Non-Stop Mode}) 10371memory can be changed @emph{while} a gdb command is executing. 10372Therefore, by default, @value{GDBN} only caches data 10373known to be on the stack@footnote{In non-stop mode, it is moderately 10374rare for a running thread to modify the stack of a stopped thread 10375in a way that would interfere with a backtrace, and caching of 10376stack reads provides a significant speed up of remote backtraces.}. 10377Other regions of memory can be explicitly marked as 10378cacheable; see @pxref{Memory Region Attributes}. 10379 10380@table @code 10381@kindex set remotecache 10382@item set remotecache on 10383@itemx set remotecache off 10384This option no longer does anything; it exists for compatibility 10385with old scripts. 10386 10387@kindex show remotecache 10388@item show remotecache 10389Show the current state of the obsolete remotecache flag. 10390 10391@kindex set stack-cache 10392@item set stack-cache on 10393@itemx set stack-cache off 10394Enable or disable caching of stack accesses. When @code{ON}, use 10395caching. By default, this option is @code{ON}. 10396 10397@kindex show stack-cache 10398@item show stack-cache 10399Show the current state of data caching for memory accesses. 10400 10401@kindex info dcache 10402@item info dcache @r{[}line@r{]} 10403Print the information about the data cache performance. The 10404information displayed includes the dcache width and depth, and for 10405each cache line, its number, address, and how many times it was 10406referenced. This command is useful for debugging the data cache 10407operation. 10408 10409If a line number is specified, the contents of that line will be 10410printed in hex. 10411 10412@item set dcache size @var{size} 10413@cindex dcache size 10414@kindex set dcache size 10415Set maximum number of entries in dcache (dcache depth above). 10416 10417@item set dcache line-size @var{line-size} 10418@cindex dcache line-size 10419@kindex set dcache line-size 10420Set number of bytes each dcache entry caches (dcache width above). 10421Must be a power of 2. 10422 10423@item show dcache size 10424@kindex show dcache size 10425Show maximum number of dcache entries. See also @ref{Caching Remote Data, info dcache}. 10426 10427@item show dcache line-size 10428@kindex show dcache line-size 10429Show default size of dcache lines. See also @ref{Caching Remote Data, info dcache}. 10430 10431@end table 10432 10433@node Searching Memory 10434@section Search Memory 10435@cindex searching memory 10436 10437Memory can be searched for a particular sequence of bytes with the 10438@code{find} command. 10439 10440@table @code 10441@kindex find 10442@item find @r{[}/@var{sn}@r{]} @var{start_addr}, +@var{len}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]} 10443@itemx find @r{[}/@var{sn}@r{]} @var{start_addr}, @var{end_addr}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]} 10444Search memory for the sequence of bytes specified by @var{val1}, @var{val2}, 10445etc. The search begins at address @var{start_addr} and continues for either 10446@var{len} bytes or through to @var{end_addr} inclusive. 10447@end table 10448 10449@var{s} and @var{n} are optional parameters. 10450They may be specified in either order, apart or together. 10451 10452@table @r 10453@item @var{s}, search query size 10454The size of each search query value. 10455 10456@table @code 10457@item b 10458bytes 10459@item h 10460halfwords (two bytes) 10461@item w 10462words (four bytes) 10463@item g 10464giant words (eight bytes) 10465@end table 10466 10467All values are interpreted in the current language. 10468This means, for example, that if the current source language is C/C@t{++} 10469then searching for the string ``hello'' includes the trailing '\0'. 10470 10471If the value size is not specified, it is taken from the 10472value's type in the current language. 10473This is useful when one wants to specify the search 10474pattern as a mixture of types. 10475Note that this means, for example, that in the case of C-like languages 10476a search for an untyped 0x42 will search for @samp{(int) 0x42} 10477which is typically four bytes. 10478 10479@item @var{n}, maximum number of finds 10480The maximum number of matches to print. The default is to print all finds. 10481@end table 10482 10483You can use strings as search values. Quote them with double-quotes 10484 (@code{"}). 10485The string value is copied into the search pattern byte by byte, 10486regardless of the endianness of the target and the size specification. 10487 10488The address of each match found is printed as well as a count of the 10489number of matches found. 10490 10491The address of the last value found is stored in convenience variable 10492@samp{$_}. 10493A count of the number of matches is stored in @samp{$numfound}. 10494 10495For example, if stopped at the @code{printf} in this function: 10496 10497@smallexample 10498void 10499hello () 10500@{ 10501 static char hello[] = "hello-hello"; 10502 static struct @{ char c; short s; int i; @} 10503 __attribute__ ((packed)) mixed 10504 = @{ 'c', 0x1234, 0x87654321 @}; 10505 printf ("%s\n", hello); 10506@} 10507@end smallexample 10508 10509@noindent 10510you get during debugging: 10511 10512@smallexample 10513(gdb) find &hello[0], +sizeof(hello), "hello" 105140x804956d <hello.1620+6> 105151 pattern found 10516(gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o' 105170x8049567 <hello.1620> 105180x804956d <hello.1620+6> 105192 patterns found 10520(gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l' 105210x8049567 <hello.1620> 105221 pattern found 10523(gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321 105240x8049560 <mixed.1625> 105251 pattern found 10526(gdb) print $numfound 10527$1 = 1 10528(gdb) print $_ 10529$2 = (void *) 0x8049560 10530@end smallexample 10531 10532@node Optimized Code 10533@chapter Debugging Optimized Code 10534@cindex optimized code, debugging 10535@cindex debugging optimized code 10536 10537Almost all compilers support optimization. With optimization 10538disabled, the compiler generates assembly code that corresponds 10539directly to your source code, in a simplistic way. As the compiler 10540applies more powerful optimizations, the generated assembly code 10541diverges from your original source code. With help from debugging 10542information generated by the compiler, @value{GDBN} can map from 10543the running program back to constructs from your original source. 10544 10545@value{GDBN} is more accurate with optimization disabled. If you 10546can recompile without optimization, it is easier to follow the 10547progress of your program during debugging. But, there are many cases 10548where you may need to debug an optimized version. 10549 10550When you debug a program compiled with @samp{-g -O}, remember that the 10551optimizer has rearranged your code; the debugger shows you what is 10552really there. Do not be too surprised when the execution path does not 10553exactly match your source file! An extreme example: if you define a 10554variable, but never use it, @value{GDBN} never sees that 10555variable---because the compiler optimizes it out of existence. 10556 10557Some things do not work as well with @samp{-g -O} as with just 10558@samp{-g}, particularly on machines with instruction scheduling. If in 10559doubt, recompile with @samp{-g} alone, and if this fixes the problem, 10560please report it to us as a bug (including a test case!). 10561@xref{Variables}, for more information about debugging optimized code. 10562 10563@menu 10564* Inline Functions:: How @value{GDBN} presents inlining 10565* Tail Call Frames:: @value{GDBN} analysis of jumps to functions 10566@end menu 10567 10568@node Inline Functions 10569@section Inline Functions 10570@cindex inline functions, debugging 10571 10572@dfn{Inlining} is an optimization that inserts a copy of the function 10573body directly at each call site, instead of jumping to a shared 10574routine. @value{GDBN} displays inlined functions just like 10575non-inlined functions. They appear in backtraces. You can view their 10576arguments and local variables, step into them with @code{step}, skip 10577them with @code{next}, and escape from them with @code{finish}. 10578You can check whether a function was inlined by using the 10579@code{info frame} command. 10580 10581For @value{GDBN} to support inlined functions, the compiler must 10582record information about inlining in the debug information --- 10583@value{NGCC} using the @sc{dwarf 2} format does this, and several 10584other compilers do also. @value{GDBN} only supports inlined functions 10585when using @sc{dwarf 2}. Versions of @value{NGCC} before 4.1 10586do not emit two required attributes (@samp{DW_AT_call_file} and 10587@samp{DW_AT_call_line}); @value{GDBN} does not display inlined 10588function calls with earlier versions of @value{NGCC}. It instead 10589displays the arguments and local variables of inlined functions as 10590local variables in the caller. 10591 10592The body of an inlined function is directly included at its call site; 10593unlike a non-inlined function, there are no instructions devoted to 10594the call. @value{GDBN} still pretends that the call site and the 10595start of the inlined function are different instructions. Stepping to 10596the call site shows the call site, and then stepping again shows 10597the first line of the inlined function, even though no additional 10598instructions are executed. 10599 10600This makes source-level debugging much clearer; you can see both the 10601context of the call and then the effect of the call. Only stepping by 10602a single instruction using @code{stepi} or @code{nexti} does not do 10603this; single instruction steps always show the inlined body. 10604 10605There are some ways that @value{GDBN} does not pretend that inlined 10606function calls are the same as normal calls: 10607 10608@itemize @bullet 10609@item 10610Setting breakpoints at the call site of an inlined function may not 10611work, because the call site does not contain any code. @value{GDBN} 10612may incorrectly move the breakpoint to the next line of the enclosing 10613function, after the call. This limitation will be removed in a future 10614version of @value{GDBN}; until then, set a breakpoint on an earlier line 10615or inside the inlined function instead. 10616 10617@item 10618@value{GDBN} cannot locate the return value of inlined calls after 10619using the @code{finish} command. This is a limitation of compiler-generated 10620debugging information; after @code{finish}, you can step to the next line 10621and print a variable where your program stored the return value. 10622 10623@end itemize 10624 10625@node Tail Call Frames 10626@section Tail Call Frames 10627@cindex tail call frames, debugging 10628 10629Function @code{B} can call function @code{C} in its very last statement. In 10630unoptimized compilation the call of @code{C} is immediately followed by return 10631instruction at the end of @code{B} code. Optimizing compiler may replace the 10632call and return in function @code{B} into one jump to function @code{C} 10633instead. Such use of a jump instruction is called @dfn{tail call}. 10634 10635During execution of function @code{C}, there will be no indication in the 10636function call stack frames that it was tail-called from @code{B}. If function 10637@code{A} regularly calls function @code{B} which tail-calls function @code{C}, 10638then @value{GDBN} will see @code{A} as the caller of @code{C}. However, in 10639some cases @value{GDBN} can determine that @code{C} was tail-called from 10640@code{B}, and it will then create fictitious call frame for that, with the 10641return address set up as if @code{B} called @code{C} normally. 10642 10643This functionality is currently supported only by DWARF 2 debugging format and 10644the compiler has to produce @samp{DW_TAG_GNU_call_site} tags. With 10645@value{NGCC}, you need to specify @option{-O -g} during compilation, to get 10646this information. 10647 10648@kbd{info frame} command (@pxref{Frame Info}) will indicate the tail call frame 10649kind by text @code{tail call frame} such as in this sample @value{GDBN} output: 10650 10651@smallexample 10652(gdb) x/i $pc - 2 10653 0x40066b <b(int, double)+11>: jmp 0x400640 <c(int, double)> 10654(gdb) info frame 10655Stack level 1, frame at 0x7fffffffda30: 10656 rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5 10657 tail call frame, caller of frame at 0x7fffffffda30 10658 source language c++. 10659 Arglist at unknown address. 10660 Locals at unknown address, Previous frame's sp is 0x7fffffffda30 10661@end smallexample 10662 10663The detection of all the possible code path executions can find them ambiguous. 10664There is no execution history stored (possible @ref{Reverse Execution} is never 10665used for this purpose) and the last known caller could have reached the known 10666callee by multiple different jump sequences. In such case @value{GDBN} still 10667tries to show at least all the unambiguous top tail callers and all the 10668unambiguous bottom tail calees, if any. 10669 10670@table @code 10671@anchor{set debug entry-values} 10672@item set debug entry-values 10673@kindex set debug entry-values 10674When set to on, enables printing of analysis messages for both frame argument 10675values at function entry and tail calls. It will show all the possible valid 10676tail calls code paths it has considered. It will also print the intersection 10677of them with the final unambiguous (possibly partial or even empty) code path 10678result. 10679 10680@item show debug entry-values 10681@kindex show debug entry-values 10682Show the current state of analysis messages printing for both frame argument 10683values at function entry and tail calls. 10684@end table 10685 10686The analysis messages for tail calls can for example show why the virtual tail 10687call frame for function @code{c} has not been recognized (due to the indirect 10688reference by variable @code{x}): 10689 10690@smallexample 10691static void __attribute__((noinline, noclone)) c (void); 10692void (*x) (void) = c; 10693static void __attribute__((noinline, noclone)) a (void) @{ x++; @} 10694static void __attribute__((noinline, noclone)) c (void) @{ a (); @} 10695int main (void) @{ x (); return 0; @} 10696 10697Breakpoint 1, DW_OP_GNU_entry_value resolving cannot find 10698DW_TAG_GNU_call_site 0x40039a in main 10699a () at t.c:3 107003 static void __attribute__((noinline, noclone)) a (void) @{ x++; @} 10701(gdb) bt 10702#0 a () at t.c:3 10703#1 0x000000000040039a in main () at t.c:5 10704@end smallexample 10705 10706Another possibility is an ambiguous virtual tail call frames resolution: 10707 10708@smallexample 10709int i; 10710static void __attribute__((noinline, noclone)) f (void) @{ i++; @} 10711static void __attribute__((noinline, noclone)) e (void) @{ f (); @} 10712static void __attribute__((noinline, noclone)) d (void) @{ f (); @} 10713static void __attribute__((noinline, noclone)) c (void) @{ d (); @} 10714static void __attribute__((noinline, noclone)) b (void) 10715@{ if (i) c (); else e (); @} 10716static void __attribute__((noinline, noclone)) a (void) @{ b (); @} 10717int main (void) @{ a (); return 0; @} 10718 10719tailcall: initial: 0x4004d2(a) 0x4004ce(b) 0x4004b2(c) 0x4004a2(d) 10720tailcall: compare: 0x4004d2(a) 0x4004cc(b) 0x400492(e) 10721tailcall: reduced: 0x4004d2(a) | 10722(gdb) bt 10723#0 f () at t.c:2 10724#1 0x00000000004004d2 in a () at t.c:8 10725#2 0x0000000000400395 in main () at t.c:9 10726@end smallexample 10727 10728@set CALLSEQ1A @code{main@value{ARROW}a@value{ARROW}b@value{ARROW}c@value{ARROW}d@value{ARROW}f} 10729@set CALLSEQ2A @code{main@value{ARROW}a@value{ARROW}b@value{ARROW}e@value{ARROW}f} 10730 10731@c Convert CALLSEQ#A to CALLSEQ#B depending on HAVE_MAKEINFO_CLICK. 10732@ifset HAVE_MAKEINFO_CLICK 10733@set ARROW @click{} 10734@set CALLSEQ1B @clicksequence{@value{CALLSEQ1A}} 10735@set CALLSEQ2B @clicksequence{@value{CALLSEQ2A}} 10736@end ifset 10737@ifclear HAVE_MAKEINFO_CLICK 10738@set ARROW -> 10739@set CALLSEQ1B @value{CALLSEQ1A} 10740@set CALLSEQ2B @value{CALLSEQ2A} 10741@end ifclear 10742 10743Frames #0 and #2 are real, #1 is a virtual tail call frame. 10744The code can have possible execution paths @value{CALLSEQ1B} or 10745@value{CALLSEQ2B}, @value{GDBN} cannot find which one from the inferior state. 10746 10747@code{initial:} state shows some random possible calling sequence @value{GDBN} 10748has found. It then finds another possible calling sequcen - that one is 10749prefixed by @code{compare:}. The non-ambiguous intersection of these two is 10750printed as the @code{reduced:} calling sequence. That one could have many 10751futher @code{compare:} and @code{reduced:} statements as long as there remain 10752any non-ambiguous sequence entries. 10753 10754For the frame of function @code{b} in both cases there are different possible 10755@code{$pc} values (@code{0x4004cc} or @code{0x4004ce}), therefore this frame is 10756also ambigous. The only non-ambiguous frame is the one for function @code{a}, 10757therefore this one is displayed to the user while the ambiguous frames are 10758omitted. 10759 10760There can be also reasons why printing of frame argument values at function 10761entry may fail: 10762 10763@smallexample 10764int v; 10765static void __attribute__((noinline, noclone)) c (int i) @{ v++; @} 10766static void __attribute__((noinline, noclone)) a (int i); 10767static void __attribute__((noinline, noclone)) b (int i) @{ a (i); @} 10768static void __attribute__((noinline, noclone)) a (int i) 10769@{ if (i) b (i - 1); else c (0); @} 10770int main (void) @{ a (5); return 0; @} 10771 10772(gdb) bt 10773#0 c (i=i@@entry=0) at t.c:2 10774#1 0x0000000000400428 in a (DW_OP_GNU_entry_value resolving has found 10775function "a" at 0x400420 can call itself via tail calls 10776i=<optimized out>) at t.c:6 10777#2 0x000000000040036e in main () at t.c:7 10778@end smallexample 10779 10780@value{GDBN} cannot find out from the inferior state if and how many times did 10781function @code{a} call itself (via function @code{b}) as these calls would be 10782tail calls. Such tail calls would modify thue @code{i} variable, therefore 10783@value{GDBN} cannot be sure the value it knows would be right - @value{GDBN} 10784prints @code{<optimized out>} instead. 10785 10786@node Macros 10787@chapter C Preprocessor Macros 10788 10789Some languages, such as C and C@t{++}, provide a way to define and invoke 10790``preprocessor macros'' which expand into strings of tokens. 10791@value{GDBN} can evaluate expressions containing macro invocations, show 10792the result of macro expansion, and show a macro's definition, including 10793where it was defined. 10794 10795You may need to compile your program specially to provide @value{GDBN} 10796with information about preprocessor macros. Most compilers do not 10797include macros in their debugging information, even when you compile 10798with the @option{-g} flag. @xref{Compilation}. 10799 10800A program may define a macro at one point, remove that definition later, 10801and then provide a different definition after that. Thus, at different 10802points in the program, a macro may have different definitions, or have 10803no definition at all. If there is a current stack frame, @value{GDBN} 10804uses the macros in scope at that frame's source code line. Otherwise, 10805@value{GDBN} uses the macros in scope at the current listing location; 10806see @ref{List}. 10807 10808Whenever @value{GDBN} evaluates an expression, it always expands any 10809macro invocations present in the expression. @value{GDBN} also provides 10810the following commands for working with macros explicitly. 10811 10812@table @code 10813 10814@kindex macro expand 10815@cindex macro expansion, showing the results of preprocessor 10816@cindex preprocessor macro expansion, showing the results of 10817@cindex expanding preprocessor macros 10818@item macro expand @var{expression} 10819@itemx macro exp @var{expression} 10820Show the results of expanding all preprocessor macro invocations in 10821@var{expression}. Since @value{GDBN} simply expands macros, but does 10822not parse the result, @var{expression} need not be a valid expression; 10823it can be any string of tokens. 10824 10825@kindex macro exp1 10826@item macro expand-once @var{expression} 10827@itemx macro exp1 @var{expression} 10828@cindex expand macro once 10829@i{(This command is not yet implemented.)} Show the results of 10830expanding those preprocessor macro invocations that appear explicitly in 10831@var{expression}. Macro invocations appearing in that expansion are 10832left unchanged. This command allows you to see the effect of a 10833particular macro more clearly, without being confused by further 10834expansions. Since @value{GDBN} simply expands macros, but does not 10835parse the result, @var{expression} need not be a valid expression; it 10836can be any string of tokens. 10837 10838@kindex info macro 10839@cindex macro definition, showing 10840@cindex definition of a macro, showing 10841@cindex macros, from debug info 10842@item info macro [-a|-all] [--] @var{macro} 10843Show the current definition or all definitions of the named @var{macro}, 10844and describe the source location or compiler command-line where that 10845definition was established. The optional double dash is to signify the end of 10846argument processing and the beginning of @var{macro} for non C-like macros where 10847the macro may begin with a hyphen. 10848 10849@kindex info macros 10850@item info macros @var{linespec} 10851Show all macro definitions that are in effect at the location specified 10852by @var{linespec}, and describe the source location or compiler 10853command-line where those definitions were established. 10854 10855@kindex macro define 10856@cindex user-defined macros 10857@cindex defining macros interactively 10858@cindex macros, user-defined 10859@item macro define @var{macro} @var{replacement-list} 10860@itemx macro define @var{macro}(@var{arglist}) @var{replacement-list} 10861Introduce a definition for a preprocessor macro named @var{macro}, 10862invocations of which are replaced by the tokens given in 10863@var{replacement-list}. The first form of this command defines an 10864``object-like'' macro, which takes no arguments; the second form 10865defines a ``function-like'' macro, which takes the arguments given in 10866@var{arglist}. 10867 10868A definition introduced by this command is in scope in every 10869expression evaluated in @value{GDBN}, until it is removed with the 10870@code{macro undef} command, described below. The definition overrides 10871all definitions for @var{macro} present in the program being debugged, 10872as well as any previous user-supplied definition. 10873 10874@kindex macro undef 10875@item macro undef @var{macro} 10876Remove any user-supplied definition for the macro named @var{macro}. 10877This command only affects definitions provided with the @code{macro 10878define} command, described above; it cannot remove definitions present 10879in the program being debugged. 10880 10881@kindex macro list 10882@item macro list 10883List all the macros defined using the @code{macro define} command. 10884@end table 10885 10886@cindex macros, example of debugging with 10887Here is a transcript showing the above commands in action. First, we 10888show our source files: 10889 10890@smallexample 10891$ cat sample.c 10892#include <stdio.h> 10893#include "sample.h" 10894 10895#define M 42 10896#define ADD(x) (M + x) 10897 10898main () 10899@{ 10900#define N 28 10901 printf ("Hello, world!\n"); 10902#undef N 10903 printf ("We're so creative.\n"); 10904#define N 1729 10905 printf ("Goodbye, world!\n"); 10906@} 10907$ cat sample.h 10908#define Q < 10909$ 10910@end smallexample 10911 10912Now, we compile the program using the @sc{gnu} C compiler, 10913@value{NGCC}. We pass the @option{-gdwarf-2}@footnote{This is the 10914minimum. Recent versions of @value{NGCC} support @option{-gdwarf-3} 10915and @option{-gdwarf-4}; we recommend always choosing the most recent 10916version of DWARF.} @emph{and} @option{-g3} flags to ensure the compiler 10917includes information about preprocessor macros in the debugging 10918information. 10919 10920@smallexample 10921$ gcc -gdwarf-2 -g3 sample.c -o sample 10922$ 10923@end smallexample 10924 10925Now, we start @value{GDBN} on our sample program: 10926 10927@smallexample 10928$ gdb -nw sample 10929GNU gdb 2002-05-06-cvs 10930Copyright 2002 Free Software Foundation, Inc. 10931GDB is free software, @dots{} 10932(@value{GDBP}) 10933@end smallexample 10934 10935We can expand macros and examine their definitions, even when the 10936program is not running. @value{GDBN} uses the current listing position 10937to decide which macro definitions are in scope: 10938 10939@smallexample 10940(@value{GDBP}) list main 109413 109424 #define M 42 109435 #define ADD(x) (M + x) 109446 109457 main () 109468 @{ 109479 #define N 28 1094810 printf ("Hello, world!\n"); 1094911 #undef N 1095012 printf ("We're so creative.\n"); 10951(@value{GDBP}) info macro ADD 10952Defined at /home/jimb/gdb/macros/play/sample.c:5 10953#define ADD(x) (M + x) 10954(@value{GDBP}) info macro Q 10955Defined at /home/jimb/gdb/macros/play/sample.h:1 10956 included at /home/jimb/gdb/macros/play/sample.c:2 10957#define Q < 10958(@value{GDBP}) macro expand ADD(1) 10959expands to: (42 + 1) 10960(@value{GDBP}) macro expand-once ADD(1) 10961expands to: once (M + 1) 10962(@value{GDBP}) 10963@end smallexample 10964 10965In the example above, note that @code{macro expand-once} expands only 10966the macro invocation explicit in the original text --- the invocation of 10967@code{ADD} --- but does not expand the invocation of the macro @code{M}, 10968which was introduced by @code{ADD}. 10969 10970Once the program is running, @value{GDBN} uses the macro definitions in 10971force at the source line of the current stack frame: 10972 10973@smallexample 10974(@value{GDBP}) break main 10975Breakpoint 1 at 0x8048370: file sample.c, line 10. 10976(@value{GDBP}) run 10977Starting program: /home/jimb/gdb/macros/play/sample 10978 10979Breakpoint 1, main () at sample.c:10 1098010 printf ("Hello, world!\n"); 10981(@value{GDBP}) 10982@end smallexample 10983 10984At line 10, the definition of the macro @code{N} at line 9 is in force: 10985 10986@smallexample 10987(@value{GDBP}) info macro N 10988Defined at /home/jimb/gdb/macros/play/sample.c:9 10989#define N 28 10990(@value{GDBP}) macro expand N Q M 10991expands to: 28 < 42 10992(@value{GDBP}) print N Q M 10993$1 = 1 10994(@value{GDBP}) 10995@end smallexample 10996 10997As we step over directives that remove @code{N}'s definition, and then 10998give it a new definition, @value{GDBN} finds the definition (or lack 10999thereof) in force at each point: 11000 11001@smallexample 11002(@value{GDBP}) next 11003Hello, world! 1100412 printf ("We're so creative.\n"); 11005(@value{GDBP}) info macro N 11006The symbol `N' has no definition as a C/C++ preprocessor macro 11007at /home/jimb/gdb/macros/play/sample.c:12 11008(@value{GDBP}) next 11009We're so creative. 1101014 printf ("Goodbye, world!\n"); 11011(@value{GDBP}) info macro N 11012Defined at /home/jimb/gdb/macros/play/sample.c:13 11013#define N 1729 11014(@value{GDBP}) macro expand N Q M 11015expands to: 1729 < 42 11016(@value{GDBP}) print N Q M 11017$2 = 0 11018(@value{GDBP}) 11019@end smallexample 11020 11021In addition to source files, macros can be defined on the compilation command 11022line using the @option{-D@var{name}=@var{value}} syntax. For macros defined in 11023such a way, @value{GDBN} displays the location of their definition as line zero 11024of the source file submitted to the compiler. 11025 11026@smallexample 11027(@value{GDBP}) info macro __STDC__ 11028Defined at /home/jimb/gdb/macros/play/sample.c:0 11029-D__STDC__=1 11030(@value{GDBP}) 11031@end smallexample 11032 11033 11034@node Tracepoints 11035@chapter Tracepoints 11036@c This chapter is based on the documentation written by Michael 11037@c Snyder, David Taylor, Jim Blandy, and Elena Zannoni. 11038 11039@cindex tracepoints 11040In some applications, it is not feasible for the debugger to interrupt 11041the program's execution long enough for the developer to learn 11042anything helpful about its behavior. If the program's correctness 11043depends on its real-time behavior, delays introduced by a debugger 11044might cause the program to change its behavior drastically, or perhaps 11045fail, even when the code itself is correct. It is useful to be able 11046to observe the program's behavior without interrupting it. 11047 11048Using @value{GDBN}'s @code{trace} and @code{collect} commands, you can 11049specify locations in the program, called @dfn{tracepoints}, and 11050arbitrary expressions to evaluate when those tracepoints are reached. 11051Later, using the @code{tfind} command, you can examine the values 11052those expressions had when the program hit the tracepoints. The 11053expressions may also denote objects in memory---structures or arrays, 11054for example---whose values @value{GDBN} should record; while visiting 11055a particular tracepoint, you may inspect those objects as if they were 11056in memory at that moment. However, because @value{GDBN} records these 11057values without interacting with you, it can do so quickly and 11058unobtrusively, hopefully not disturbing the program's behavior. 11059 11060The tracepoint facility is currently available only for remote 11061targets. @xref{Targets}. In addition, your remote target must know 11062how to collect trace data. This functionality is implemented in the 11063remote stub; however, none of the stubs distributed with @value{GDBN} 11064support tracepoints as of this writing. The format of the remote 11065packets used to implement tracepoints are described in @ref{Tracepoint 11066Packets}. 11067 11068It is also possible to get trace data from a file, in a manner reminiscent 11069of corefiles; you specify the filename, and use @code{tfind} to search 11070through the file. @xref{Trace Files}, for more details. 11071 11072This chapter describes the tracepoint commands and features. 11073 11074@menu 11075* Set Tracepoints:: 11076* Analyze Collected Data:: 11077* Tracepoint Variables:: 11078* Trace Files:: 11079@end menu 11080 11081@node Set Tracepoints 11082@section Commands to Set Tracepoints 11083 11084Before running such a @dfn{trace experiment}, an arbitrary number of 11085tracepoints can be set. A tracepoint is actually a special type of 11086breakpoint (@pxref{Set Breaks}), so you can manipulate it using 11087standard breakpoint commands. For instance, as with breakpoints, 11088tracepoint numbers are successive integers starting from one, and many 11089of the commands associated with tracepoints take the tracepoint number 11090as their argument, to identify which tracepoint to work on. 11091 11092For each tracepoint, you can specify, in advance, some arbitrary set 11093of data that you want the target to collect in the trace buffer when 11094it hits that tracepoint. The collected data can include registers, 11095local variables, or global data. Later, you can use @value{GDBN} 11096commands to examine the values these data had at the time the 11097tracepoint was hit. 11098 11099Tracepoints do not support every breakpoint feature. Ignore counts on 11100tracepoints have no effect, and tracepoints cannot run @value{GDBN} 11101commands when they are hit. Tracepoints may not be thread-specific 11102either. 11103 11104@cindex fast tracepoints 11105Some targets may support @dfn{fast tracepoints}, which are inserted in 11106a different way (such as with a jump instead of a trap), that is 11107faster but possibly restricted in where they may be installed. 11108 11109@cindex static tracepoints 11110@cindex markers, static tracepoints 11111@cindex probing markers, static tracepoints 11112Regular and fast tracepoints are dynamic tracing facilities, meaning 11113that they can be used to insert tracepoints at (almost) any location 11114in the target. Some targets may also support controlling @dfn{static 11115tracepoints} from @value{GDBN}. With static tracing, a set of 11116instrumentation points, also known as @dfn{markers}, are embedded in 11117the target program, and can be activated or deactivated by name or 11118address. These are usually placed at locations which facilitate 11119investigating what the target is actually doing. @value{GDBN}'s 11120support for static tracing includes being able to list instrumentation 11121points, and attach them with @value{GDBN} defined high level 11122tracepoints that expose the whole range of convenience of 11123@value{GDBN}'s tracepoints support. Namely, support for collecting 11124registers values and values of global or local (to the instrumentation 11125point) variables; tracepoint conditions and trace state variables. 11126The act of installing a @value{GDBN} static tracepoint on an 11127instrumentation point, or marker, is referred to as @dfn{probing} a 11128static tracepoint marker. 11129 11130@code{gdbserver} supports tracepoints on some target systems. 11131@xref{Server,,Tracepoints support in @code{gdbserver}}. 11132 11133This section describes commands to set tracepoints and associated 11134conditions and actions. 11135 11136@menu 11137* Create and Delete Tracepoints:: 11138* Enable and Disable Tracepoints:: 11139* Tracepoint Passcounts:: 11140* Tracepoint Conditions:: 11141* Trace State Variables:: 11142* Tracepoint Actions:: 11143* Listing Tracepoints:: 11144* Listing Static Tracepoint Markers:: 11145* Starting and Stopping Trace Experiments:: 11146* Tracepoint Restrictions:: 11147@end menu 11148 11149@node Create and Delete Tracepoints 11150@subsection Create and Delete Tracepoints 11151 11152@table @code 11153@cindex set tracepoint 11154@kindex trace 11155@item trace @var{location} 11156The @code{trace} command is very similar to the @code{break} command. 11157Its argument @var{location} can be a source line, a function name, or 11158an address in the target program. @xref{Specify Location}. The 11159@code{trace} command defines a tracepoint, which is a point in the 11160target program where the debugger will briefly stop, collect some 11161data, and then allow the program to continue. Setting a tracepoint or 11162changing its actions takes effect immediately if the remote stub 11163supports the @samp{InstallInTrace} feature (@pxref{install tracepoint 11164in tracing}). 11165If remote stub doesn't support the @samp{InstallInTrace} feature, all 11166these changes don't take effect until the next @code{tstart} 11167command, and once a trace experiment is running, further changes will 11168not have any effect until the next trace experiment starts. In addition, 11169@value{GDBN} supports @dfn{pending tracepoints}---tracepoints whose 11170address is not yet resolved. (This is similar to pending breakpoints.) 11171Pending tracepoints are not downloaded to the target and not installed 11172until they are resolved. The resolution of pending tracepoints requires 11173@value{GDBN} support---when debugging with the remote target, and 11174@value{GDBN} disconnects from the remote stub (@pxref{disconnected 11175tracing}), pending tracepoints can not be resolved (and downloaded to 11176the remote stub) while @value{GDBN} is disconnected. 11177 11178Here are some examples of using the @code{trace} command: 11179 11180@smallexample 11181(@value{GDBP}) @b{trace foo.c:121} // a source file and line number 11182 11183(@value{GDBP}) @b{trace +2} // 2 lines forward 11184 11185(@value{GDBP}) @b{trace my_function} // first source line of function 11186 11187(@value{GDBP}) @b{trace *my_function} // EXACT start address of function 11188 11189(@value{GDBP}) @b{trace *0x2117c4} // an address 11190@end smallexample 11191 11192@noindent 11193You can abbreviate @code{trace} as @code{tr}. 11194 11195@item trace @var{location} if @var{cond} 11196Set a tracepoint with condition @var{cond}; evaluate the expression 11197@var{cond} each time the tracepoint is reached, and collect data only 11198if the value is nonzero---that is, if @var{cond} evaluates as true. 11199@xref{Tracepoint Conditions, ,Tracepoint Conditions}, for more 11200information on tracepoint conditions. 11201 11202@item ftrace @var{location} [ if @var{cond} ] 11203@cindex set fast tracepoint 11204@cindex fast tracepoints, setting 11205@kindex ftrace 11206The @code{ftrace} command sets a fast tracepoint. For targets that 11207support them, fast tracepoints will use a more efficient but possibly 11208less general technique to trigger data collection, such as a jump 11209instruction instead of a trap, or some sort of hardware support. It 11210may not be possible to create a fast tracepoint at the desired 11211location, in which case the command will exit with an explanatory 11212message. 11213 11214@value{GDBN} handles arguments to @code{ftrace} exactly as for 11215@code{trace}. 11216 11217On 32-bit x86-architecture systems, fast tracepoints normally need to 11218be placed at an instruction that is 5 bytes or longer, but can be 11219placed at 4-byte instructions if the low 64K of memory of the target 11220program is available to install trampolines. Some Unix-type systems, 11221such as @sc{gnu}/Linux, exclude low addresses from the program's 11222address space; but for instance with the Linux kernel it is possible 11223to let @value{GDBN} use this area by doing a @command{sysctl} command 11224to set the @code{mmap_min_addr} kernel parameter, as in 11225 11226@example 11227sudo sysctl -w vm.mmap_min_addr=32768 11228@end example 11229 11230@noindent 11231which sets the low address to 32K, which leaves plenty of room for 11232trampolines. The minimum address should be set to a page boundary. 11233 11234@item strace @var{location} [ if @var{cond} ] 11235@cindex set static tracepoint 11236@cindex static tracepoints, setting 11237@cindex probe static tracepoint marker 11238@kindex strace 11239The @code{strace} command sets a static tracepoint. For targets that 11240support it, setting a static tracepoint probes a static 11241instrumentation point, or marker, found at @var{location}. It may not 11242be possible to set a static tracepoint at the desired location, in 11243which case the command will exit with an explanatory message. 11244 11245@value{GDBN} handles arguments to @code{strace} exactly as for 11246@code{trace}, with the addition that the user can also specify 11247@code{-m @var{marker}} as @var{location}. This probes the marker 11248identified by the @var{marker} string identifier. This identifier 11249depends on the static tracepoint backend library your program is 11250using. You can find all the marker identifiers in the @samp{ID} field 11251of the @code{info static-tracepoint-markers} command output. 11252@xref{Listing Static Tracepoint Markers,,Listing Static Tracepoint 11253Markers}. For example, in the following small program using the UST 11254tracing engine: 11255 11256@smallexample 11257main () 11258@{ 11259 trace_mark(ust, bar33, "str %s", "FOOBAZ"); 11260@} 11261@end smallexample 11262 11263@noindent 11264the marker id is composed of joining the first two arguments to the 11265@code{trace_mark} call with a slash, which translates to: 11266 11267@smallexample 11268(@value{GDBP}) info static-tracepoint-markers 11269Cnt Enb ID Address What 112701 n ust/bar33 0x0000000000400ddc in main at stexample.c:22 11271 Data: "str %s" 11272[etc...] 11273@end smallexample 11274 11275@noindent 11276so you may probe the marker above with: 11277 11278@smallexample 11279(@value{GDBP}) strace -m ust/bar33 11280@end smallexample 11281 11282Static tracepoints accept an extra collect action --- @code{collect 11283$_sdata}. This collects arbitrary user data passed in the probe point 11284call to the tracing library. In the UST example above, you'll see 11285that the third argument to @code{trace_mark} is a printf-like format 11286string. The user data is then the result of running that formating 11287string against the following arguments. Note that @code{info 11288static-tracepoint-markers} command output lists that format string in 11289the @samp{Data:} field. 11290 11291You can inspect this data when analyzing the trace buffer, by printing 11292the $_sdata variable like any other variable available to 11293@value{GDBN}. @xref{Tracepoint Actions,,Tracepoint Action Lists}. 11294 11295@vindex $tpnum 11296@cindex last tracepoint number 11297@cindex recent tracepoint number 11298@cindex tracepoint number 11299The convenience variable @code{$tpnum} records the tracepoint number 11300of the most recently set tracepoint. 11301 11302@kindex delete tracepoint 11303@cindex tracepoint deletion 11304@item delete tracepoint @r{[}@var{num}@r{]} 11305Permanently delete one or more tracepoints. With no argument, the 11306default is to delete all tracepoints. Note that the regular 11307@code{delete} command can remove tracepoints also. 11308 11309Examples: 11310 11311@smallexample 11312(@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints 11313 11314(@value{GDBP}) @b{delete trace} // remove all tracepoints 11315@end smallexample 11316 11317@noindent 11318You can abbreviate this command as @code{del tr}. 11319@end table 11320 11321@node Enable and Disable Tracepoints 11322@subsection Enable and Disable Tracepoints 11323 11324These commands are deprecated; they are equivalent to plain @code{disable} and @code{enable}. 11325 11326@table @code 11327@kindex disable tracepoint 11328@item disable tracepoint @r{[}@var{num}@r{]} 11329Disable tracepoint @var{num}, or all tracepoints if no argument 11330@var{num} is given. A disabled tracepoint will have no effect during 11331a trace experiment, but it is not forgotten. You can re-enable 11332a disabled tracepoint using the @code{enable tracepoint} command. 11333If the command is issued during a trace experiment and the debug target 11334has support for disabling tracepoints during a trace experiment, then the 11335change will be effective immediately. Otherwise, it will be applied to the 11336next trace experiment. 11337 11338@kindex enable tracepoint 11339@item enable tracepoint @r{[}@var{num}@r{]} 11340Enable tracepoint @var{num}, or all tracepoints. If this command is 11341issued during a trace experiment and the debug target supports enabling 11342tracepoints during a trace experiment, then the enabled tracepoints will 11343become effective immediately. Otherwise, they will become effective the 11344next time a trace experiment is run. 11345@end table 11346 11347@node Tracepoint Passcounts 11348@subsection Tracepoint Passcounts 11349 11350@table @code 11351@kindex passcount 11352@cindex tracepoint pass count 11353@item passcount @r{[}@var{n} @r{[}@var{num}@r{]]} 11354Set the @dfn{passcount} of a tracepoint. The passcount is a way to 11355automatically stop a trace experiment. If a tracepoint's passcount is 11356@var{n}, then the trace experiment will be automatically stopped on 11357the @var{n}'th time that tracepoint is hit. If the tracepoint number 11358@var{num} is not specified, the @code{passcount} command sets the 11359passcount of the most recently defined tracepoint. If no passcount is 11360given, the trace experiment will run until stopped explicitly by the 11361user. 11362 11363Examples: 11364 11365@smallexample 11366(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of 11367@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2} 11368 11369(@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the 11370@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// most recently defined tracepoint.} 11371(@value{GDBP}) @b{trace foo} 11372(@value{GDBP}) @b{pass 3} 11373(@value{GDBP}) @b{trace bar} 11374(@value{GDBP}) @b{pass 2} 11375(@value{GDBP}) @b{trace baz} 11376(@value{GDBP}) @b{pass 1} // Stop tracing when foo has been 11377@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// executed 3 times OR when bar has} 11378@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// been executed 2 times} 11379@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// OR when baz has been executed 1 time.} 11380@end smallexample 11381@end table 11382 11383@node Tracepoint Conditions 11384@subsection Tracepoint Conditions 11385@cindex conditional tracepoints 11386@cindex tracepoint conditions 11387 11388The simplest sort of tracepoint collects data every time your program 11389reaches a specified place. You can also specify a @dfn{condition} for 11390a tracepoint. A condition is just a Boolean expression in your 11391programming language (@pxref{Expressions, ,Expressions}). A 11392tracepoint with a condition evaluates the expression each time your 11393program reaches it, and data collection happens only if the condition 11394is true. 11395 11396Tracepoint conditions can be specified when a tracepoint is set, by 11397using @samp{if} in the arguments to the @code{trace} command. 11398@xref{Create and Delete Tracepoints, ,Setting Tracepoints}. They can 11399also be set or changed at any time with the @code{condition} command, 11400just as with breakpoints. 11401 11402Unlike breakpoint conditions, @value{GDBN} does not actually evaluate 11403the conditional expression itself. Instead, @value{GDBN} encodes the 11404expression into an agent expression (@pxref{Agent Expressions}) 11405suitable for execution on the target, independently of @value{GDBN}. 11406Global variables become raw memory locations, locals become stack 11407accesses, and so forth. 11408 11409For instance, suppose you have a function that is usually called 11410frequently, but should not be called after an error has occurred. You 11411could use the following tracepoint command to collect data about calls 11412of that function that happen while the error code is propagating 11413through the program; an unconditional tracepoint could end up 11414collecting thousands of useless trace frames that you would have to 11415search through. 11416 11417@smallexample 11418(@value{GDBP}) @kbd{trace normal_operation if errcode > 0} 11419@end smallexample 11420 11421@node Trace State Variables 11422@subsection Trace State Variables 11423@cindex trace state variables 11424 11425A @dfn{trace state variable} is a special type of variable that is 11426created and managed by target-side code. The syntax is the same as 11427that for GDB's convenience variables (a string prefixed with ``$''), 11428but they are stored on the target. They must be created explicitly, 11429using a @code{tvariable} command. They are always 64-bit signed 11430integers. 11431 11432Trace state variables are remembered by @value{GDBN}, and downloaded 11433to the target along with tracepoint information when the trace 11434experiment starts. There are no intrinsic limits on the number of 11435trace state variables, beyond memory limitations of the target. 11436 11437@cindex convenience variables, and trace state variables 11438Although trace state variables are managed by the target, you can use 11439them in print commands and expressions as if they were convenience 11440variables; @value{GDBN} will get the current value from the target 11441while the trace experiment is running. Trace state variables share 11442the same namespace as other ``$'' variables, which means that you 11443cannot have trace state variables with names like @code{$23} or 11444@code{$pc}, nor can you have a trace state variable and a convenience 11445variable with the same name. 11446 11447@table @code 11448 11449@item tvariable $@var{name} [ = @var{expression} ] 11450@kindex tvariable 11451The @code{tvariable} command creates a new trace state variable named 11452@code{$@var{name}}, and optionally gives it an initial value of 11453@var{expression}. @var{expression} is evaluated when this command is 11454entered; the result will be converted to an integer if possible, 11455otherwise @value{GDBN} will report an error. A subsequent 11456@code{tvariable} command specifying the same name does not create a 11457variable, but instead assigns the supplied initial value to the 11458existing variable of that name, overwriting any previous initial 11459value. The default initial value is 0. 11460 11461@item info tvariables 11462@kindex info tvariables 11463List all the trace state variables along with their initial values. 11464Their current values may also be displayed, if the trace experiment is 11465currently running. 11466 11467@item delete tvariable @r{[} $@var{name} @dots{} @r{]} 11468@kindex delete tvariable 11469Delete the given trace state variables, or all of them if no arguments 11470are specified. 11471 11472@end table 11473 11474@node Tracepoint Actions 11475@subsection Tracepoint Action Lists 11476 11477@table @code 11478@kindex actions 11479@cindex tracepoint actions 11480@item actions @r{[}@var{num}@r{]} 11481This command will prompt for a list of actions to be taken when the 11482tracepoint is hit. If the tracepoint number @var{num} is not 11483specified, this command sets the actions for the one that was most 11484recently defined (so that you can define a tracepoint and then say 11485@code{actions} without bothering about its number). You specify the 11486actions themselves on the following lines, one action at a time, and 11487terminate the actions list with a line containing just @code{end}. So 11488far, the only defined actions are @code{collect}, @code{teval}, and 11489@code{while-stepping}. 11490 11491@code{actions} is actually equivalent to @code{commands} (@pxref{Break 11492Commands, ,Breakpoint Command Lists}), except that only the defined 11493actions are allowed; any other @value{GDBN} command is rejected. 11494 11495@cindex remove actions from a tracepoint 11496To remove all actions from a tracepoint, type @samp{actions @var{num}} 11497and follow it immediately with @samp{end}. 11498 11499@smallexample 11500(@value{GDBP}) @b{collect @var{data}} // collect some data 11501 11502(@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data 11503 11504(@value{GDBP}) @b{end} // signals the end of actions. 11505@end smallexample 11506 11507In the following example, the action list begins with @code{collect} 11508commands indicating the things to be collected when the tracepoint is 11509hit. Then, in order to single-step and collect additional data 11510following the tracepoint, a @code{while-stepping} command is used, 11511followed by the list of things to be collected after each step in a 11512sequence of single steps. The @code{while-stepping} command is 11513terminated by its own separate @code{end} command. Lastly, the action 11514list is terminated by an @code{end} command. 11515 11516@smallexample 11517(@value{GDBP}) @b{trace foo} 11518(@value{GDBP}) @b{actions} 11519Enter actions for tracepoint 1, one per line: 11520> collect bar,baz 11521> collect $regs 11522> while-stepping 12 11523 > collect $pc, arr[i] 11524 > end 11525end 11526@end smallexample 11527 11528@kindex collect @r{(tracepoints)} 11529@item collect@r{[}/@var{mods}@r{]} @var{expr1}, @var{expr2}, @dots{} 11530Collect values of the given expressions when the tracepoint is hit. 11531This command accepts a comma-separated list of any valid expressions. 11532In addition to global, static, or local variables, the following 11533special arguments are supported: 11534 11535@table @code 11536@item $regs 11537Collect all registers. 11538 11539@item $args 11540Collect all function arguments. 11541 11542@item $locals 11543Collect all local variables. 11544 11545@item $_ret 11546Collect the return address. This is helpful if you want to see more 11547of a backtrace. 11548 11549@item $_probe_argc 11550Collects the number of arguments from the static probe at which the 11551tracepoint is located. 11552@xref{Static Probe Points}. 11553 11554@item $_probe_arg@var{n} 11555@var{n} is an integer between 0 and 11. Collects the @var{n}th argument 11556from the static probe at which the tracepoint is located. 11557@xref{Static Probe Points}. 11558 11559@item $_sdata 11560@vindex $_sdata@r{, collect} 11561Collect static tracepoint marker specific data. Only available for 11562static tracepoints. @xref{Tracepoint Actions,,Tracepoint Action 11563Lists}. On the UST static tracepoints library backend, an 11564instrumentation point resembles a @code{printf} function call. The 11565tracing library is able to collect user specified data formatted to a 11566character string using the format provided by the programmer that 11567instrumented the program. Other backends have similar mechanisms. 11568Here's an example of a UST marker call: 11569 11570@smallexample 11571 const char master_name[] = "$your_name"; 11572 trace_mark(channel1, marker1, "hello %s", master_name) 11573@end smallexample 11574 11575In this case, collecting @code{$_sdata} collects the string 11576@samp{hello $yourname}. When analyzing the trace buffer, you can 11577inspect @samp{$_sdata} like any other variable available to 11578@value{GDBN}. 11579@end table 11580 11581You can give several consecutive @code{collect} commands, each one 11582with a single argument, or one @code{collect} command with several 11583arguments separated by commas; the effect is the same. 11584 11585The optional @var{mods} changes the usual handling of the arguments. 11586@code{s} requests that pointers to chars be handled as strings, in 11587particular collecting the contents of the memory being pointed at, up 11588to the first zero. The upper bound is by default the value of the 11589@code{print elements} variable; if @code{s} is followed by a decimal 11590number, that is the upper bound instead. So for instance 11591@samp{collect/s25 mystr} collects as many as 25 characters at 11592@samp{mystr}. 11593 11594The command @code{info scope} (@pxref{Symbols, info scope}) is 11595particularly useful for figuring out what data to collect. 11596 11597@kindex teval @r{(tracepoints)} 11598@item teval @var{expr1}, @var{expr2}, @dots{} 11599Evaluate the given expressions when the tracepoint is hit. This 11600command accepts a comma-separated list of expressions. The results 11601are discarded, so this is mainly useful for assigning values to trace 11602state variables (@pxref{Trace State Variables}) without adding those 11603values to the trace buffer, as would be the case if the @code{collect} 11604action were used. 11605 11606@kindex while-stepping @r{(tracepoints)} 11607@item while-stepping @var{n} 11608Perform @var{n} single-step instruction traces after the tracepoint, 11609collecting new data after each step. The @code{while-stepping} 11610command is followed by the list of what to collect while stepping 11611(followed by its own @code{end} command): 11612 11613@smallexample 11614> while-stepping 12 11615 > collect $regs, myglobal 11616 > end 11617> 11618@end smallexample 11619 11620@noindent 11621Note that @code{$pc} is not automatically collected by 11622@code{while-stepping}; you need to explicitly collect that register if 11623you need it. You may abbreviate @code{while-stepping} as @code{ws} or 11624@code{stepping}. 11625 11626@item set default-collect @var{expr1}, @var{expr2}, @dots{} 11627@kindex set default-collect 11628@cindex default collection action 11629This variable is a list of expressions to collect at each tracepoint 11630hit. It is effectively an additional @code{collect} action prepended 11631to every tracepoint action list. The expressions are parsed 11632individually for each tracepoint, so for instance a variable named 11633@code{xyz} may be interpreted as a global for one tracepoint, and a 11634local for another, as appropriate to the tracepoint's location. 11635 11636@item show default-collect 11637@kindex show default-collect 11638Show the list of expressions that are collected by default at each 11639tracepoint hit. 11640 11641@end table 11642 11643@node Listing Tracepoints 11644@subsection Listing Tracepoints 11645 11646@table @code 11647@kindex info tracepoints @r{[}@var{n}@dots{}@r{]} 11648@kindex info tp @r{[}@var{n}@dots{}@r{]} 11649@cindex information about tracepoints 11650@item info tracepoints @r{[}@var{num}@dots{}@r{]} 11651Display information about the tracepoint @var{num}. If you don't 11652specify a tracepoint number, displays information about all the 11653tracepoints defined so far. The format is similar to that used for 11654@code{info breakpoints}; in fact, @code{info tracepoints} is the same 11655command, simply restricting itself to tracepoints. 11656 11657A tracepoint's listing may include additional information specific to 11658tracing: 11659 11660@itemize @bullet 11661@item 11662its passcount as given by the @code{passcount @var{n}} command 11663 11664@item 11665the state about installed on target of each location 11666@end itemize 11667 11668@smallexample 11669(@value{GDBP}) @b{info trace} 11670Num Type Disp Enb Address What 116711 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7 11672 while-stepping 20 11673 collect globfoo, $regs 11674 end 11675 collect globfoo2 11676 end 11677 pass count 1200 116782 tracepoint keep y <MULTIPLE> 11679 collect $eip 116802.1 y 0x0804859c in func4 at change-loc.h:35 11681 installed on target 116822.2 y 0xb7ffc480 in func4 at change-loc.h:35 11683 installed on target 116842.3 y <PENDING> set_tracepoint 116853 tracepoint keep y 0x080485b1 in foo at change-loc.c:29 11686 not installed on target 11687(@value{GDBP}) 11688@end smallexample 11689 11690@noindent 11691This command can be abbreviated @code{info tp}. 11692@end table 11693 11694@node Listing Static Tracepoint Markers 11695@subsection Listing Static Tracepoint Markers 11696 11697@table @code 11698@kindex info static-tracepoint-markers 11699@cindex information about static tracepoint markers 11700@item info static-tracepoint-markers 11701Display information about all static tracepoint markers defined in the 11702program. 11703 11704For each marker, the following columns are printed: 11705 11706@table @emph 11707@item Count 11708An incrementing counter, output to help readability. This is not a 11709stable identifier. 11710@item ID 11711The marker ID, as reported by the target. 11712@item Enabled or Disabled 11713Probed markers are tagged with @samp{y}. @samp{n} identifies marks 11714that are not enabled. 11715@item Address 11716Where the marker is in your program, as a memory address. 11717@item What 11718Where the marker is in the source for your program, as a file and line 11719number. If the debug information included in the program does not 11720allow @value{GDBN} to locate the source of the marker, this column 11721will be left blank. 11722@end table 11723 11724@noindent 11725In addition, the following information may be printed for each marker: 11726 11727@table @emph 11728@item Data 11729User data passed to the tracing library by the marker call. In the 11730UST backend, this is the format string passed as argument to the 11731marker call. 11732@item Static tracepoints probing the marker 11733The list of static tracepoints attached to the marker. 11734@end table 11735 11736@smallexample 11737(@value{GDBP}) info static-tracepoint-markers 11738Cnt ID Enb Address What 117391 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25 11740 Data: number1 %d number2 %d 11741 Probed by static tracepoints: #2 117422 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24 11743 Data: str %s 11744(@value{GDBP}) 11745@end smallexample 11746@end table 11747 11748@node Starting and Stopping Trace Experiments 11749@subsection Starting and Stopping Trace Experiments 11750 11751@table @code 11752@kindex tstart [ @var{notes} ] 11753@cindex start a new trace experiment 11754@cindex collected data discarded 11755@item tstart 11756This command starts the trace experiment, and begins collecting data. 11757It has the side effect of discarding all the data collected in the 11758trace buffer during the previous trace experiment. If any arguments 11759are supplied, they are taken as a note and stored with the trace 11760experiment's state. The notes may be arbitrary text, and are 11761especially useful with disconnected tracing in a multi-user context; 11762the notes can explain what the trace is doing, supply user contact 11763information, and so forth. 11764 11765@kindex tstop [ @var{notes} ] 11766@cindex stop a running trace experiment 11767@item tstop 11768This command stops the trace experiment. If any arguments are 11769supplied, they are recorded with the experiment as a note. This is 11770useful if you are stopping a trace started by someone else, for 11771instance if the trace is interfering with the system's behavior and 11772needs to be stopped quickly. 11773 11774@strong{Note}: a trace experiment and data collection may stop 11775automatically if any tracepoint's passcount is reached 11776(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full. 11777 11778@kindex tstatus 11779@cindex status of trace data collection 11780@cindex trace experiment, status of 11781@item tstatus 11782This command displays the status of the current trace data 11783collection. 11784@end table 11785 11786Here is an example of the commands we described so far: 11787 11788@smallexample 11789(@value{GDBP}) @b{trace gdb_c_test} 11790(@value{GDBP}) @b{actions} 11791Enter actions for tracepoint #1, one per line. 11792> collect $regs,$locals,$args 11793> while-stepping 11 11794 > collect $regs 11795 > end 11796> end 11797(@value{GDBP}) @b{tstart} 11798 [time passes @dots{}] 11799(@value{GDBP}) @b{tstop} 11800@end smallexample 11801 11802@anchor{disconnected tracing} 11803@cindex disconnected tracing 11804You can choose to continue running the trace experiment even if 11805@value{GDBN} disconnects from the target, voluntarily or 11806involuntarily. For commands such as @code{detach}, the debugger will 11807ask what you want to do with the trace. But for unexpected 11808terminations (@value{GDBN} crash, network outage), it would be 11809unfortunate to lose hard-won trace data, so the variable 11810@code{disconnected-tracing} lets you decide whether the trace should 11811continue running without @value{GDBN}. 11812 11813@table @code 11814@item set disconnected-tracing on 11815@itemx set disconnected-tracing off 11816@kindex set disconnected-tracing 11817Choose whether a tracing run should continue to run if @value{GDBN} 11818has disconnected from the target. Note that @code{detach} or 11819@code{quit} will ask you directly what to do about a running trace no 11820matter what this variable's setting, so the variable is mainly useful 11821for handling unexpected situations, such as loss of the network. 11822 11823@item show disconnected-tracing 11824@kindex show disconnected-tracing 11825Show the current choice for disconnected tracing. 11826 11827@end table 11828 11829When you reconnect to the target, the trace experiment may or may not 11830still be running; it might have filled the trace buffer in the 11831meantime, or stopped for one of the other reasons. If it is running, 11832it will continue after reconnection. 11833 11834Upon reconnection, the target will upload information about the 11835tracepoints in effect. @value{GDBN} will then compare that 11836information to the set of tracepoints currently defined, and attempt 11837to match them up, allowing for the possibility that the numbers may 11838have changed due to creation and deletion in the meantime. If one of 11839the target's tracepoints does not match any in @value{GDBN}, the 11840debugger will create a new tracepoint, so that you have a number with 11841which to specify that tracepoint. This matching-up process is 11842necessarily heuristic, and it may result in useless tracepoints being 11843created; you may simply delete them if they are of no use. 11844 11845@cindex circular trace buffer 11846If your target agent supports a @dfn{circular trace buffer}, then you 11847can run a trace experiment indefinitely without filling the trace 11848buffer; when space runs out, the agent deletes already-collected trace 11849frames, oldest first, until there is enough room to continue 11850collecting. This is especially useful if your tracepoints are being 11851hit too often, and your trace gets terminated prematurely because the 11852buffer is full. To ask for a circular trace buffer, simply set 11853@samp{circular-trace-buffer} to on. You can set this at any time, 11854including during tracing; if the agent can do it, it will change 11855buffer handling on the fly, otherwise it will not take effect until 11856the next run. 11857 11858@table @code 11859@item set circular-trace-buffer on 11860@itemx set circular-trace-buffer off 11861@kindex set circular-trace-buffer 11862Choose whether a tracing run should use a linear or circular buffer 11863for trace data. A linear buffer will not lose any trace data, but may 11864fill up prematurely, while a circular buffer will discard old trace 11865data, but it will have always room for the latest tracepoint hits. 11866 11867@item show circular-trace-buffer 11868@kindex show circular-trace-buffer 11869Show the current choice for the trace buffer. Note that this may not 11870match the agent's current buffer handling, nor is it guaranteed to 11871match the setting that might have been in effect during a past run, 11872for instance if you are looking at frames from a trace file. 11873 11874@end table 11875 11876@table @code 11877@item set trace-buffer-size @var{n} 11878@kindex set trace-buffer-size 11879Request that the target use a trace buffer of @var{n} bytes. Not all 11880targets will honor the request; they may have a compiled-in size for 11881the trace buffer, or some other limitation. Set to a value of 11882@code{-1} to let the target use whatever size it likes. This is also 11883the default. 11884 11885@item show trace-buffer-size 11886@kindex show trace-buffer-size 11887Show the current requested size for the trace buffer. Note that this 11888will only match the actual size if the target supports size-setting, 11889and was able to handle the requested size. For instance, if the 11890target can only change buffer size between runs, this variable will 11891not reflect the change until the next run starts. Use @code{tstatus} 11892to get a report of the actual buffer size. 11893@end table 11894 11895@table @code 11896@item set trace-user @var{text} 11897@kindex set trace-user 11898 11899@item show trace-user 11900@kindex show trace-user 11901 11902@item set trace-notes @var{text} 11903@kindex set trace-notes 11904Set the trace run's notes. 11905 11906@item show trace-notes 11907@kindex show trace-notes 11908Show the trace run's notes. 11909 11910@item set trace-stop-notes @var{text} 11911@kindex set trace-stop-notes 11912Set the trace run's stop notes. The handling of the note is as for 11913@code{tstop} arguments; the set command is convenient way to fix a 11914stop note that is mistaken or incomplete. 11915 11916@item show trace-stop-notes 11917@kindex show trace-stop-notes 11918Show the trace run's stop notes. 11919 11920@end table 11921 11922@node Tracepoint Restrictions 11923@subsection Tracepoint Restrictions 11924 11925@cindex tracepoint restrictions 11926There are a number of restrictions on the use of tracepoints. As 11927described above, tracepoint data gathering occurs on the target 11928without interaction from @value{GDBN}. Thus the full capabilities of 11929the debugger are not available during data gathering, and then at data 11930examination time, you will be limited by only having what was 11931collected. The following items describe some common problems, but it 11932is not exhaustive, and you may run into additional difficulties not 11933mentioned here. 11934 11935@itemize @bullet 11936 11937@item 11938Tracepoint expressions are intended to gather objects (lvalues). Thus 11939the full flexibility of GDB's expression evaluator is not available. 11940You cannot call functions, cast objects to aggregate types, access 11941convenience variables or modify values (except by assignment to trace 11942state variables). Some language features may implicitly call 11943functions (for instance Objective-C fields with accessors), and therefore 11944cannot be collected either. 11945 11946@item 11947Collection of local variables, either individually or in bulk with 11948@code{$locals} or @code{$args}, during @code{while-stepping} may 11949behave erratically. The stepping action may enter a new scope (for 11950instance by stepping into a function), or the location of the variable 11951may change (for instance it is loaded into a register). The 11952tracepoint data recorded uses the location information for the 11953variables that is correct for the tracepoint location. When the 11954tracepoint is created, it is not possible, in general, to determine 11955where the steps of a @code{while-stepping} sequence will advance the 11956program---particularly if a conditional branch is stepped. 11957 11958@item 11959Collection of an incompletely-initialized or partially-destroyed object 11960may result in something that @value{GDBN} cannot display, or displays 11961in a misleading way. 11962 11963@item 11964When @value{GDBN} displays a pointer to character it automatically 11965dereferences the pointer to also display characters of the string 11966being pointed to. However, collecting the pointer during tracing does 11967not automatically collect the string. You need to explicitly 11968dereference the pointer and provide size information if you want to 11969collect not only the pointer, but the memory pointed to. For example, 11970@code{*ptr@@50} can be used to collect the 50 element array pointed to 11971by @code{ptr}. 11972 11973@item 11974It is not possible to collect a complete stack backtrace at a 11975tracepoint. Instead, you may collect the registers and a few hundred 11976bytes from the stack pointer with something like @code{*(unsigned char *)$esp@@300} 11977(adjust to use the name of the actual stack pointer register on your 11978target architecture, and the amount of stack you wish to capture). 11979Then the @code{backtrace} command will show a partial backtrace when 11980using a trace frame. The number of stack frames that can be examined 11981depends on the sizes of the frames in the collected stack. Note that 11982if you ask for a block so large that it goes past the bottom of the 11983stack, the target agent may report an error trying to read from an 11984invalid address. 11985 11986@item 11987If you do not collect registers at a tracepoint, @value{GDBN} can 11988infer that the value of @code{$pc} must be the same as the address of 11989the tracepoint and use that when you are looking at a trace frame 11990for that tracepoint. However, this cannot work if the tracepoint has 11991multiple locations (for instance if it was set in a function that was 11992inlined), or if it has a @code{while-stepping} loop. In those cases 11993@value{GDBN} will warn you that it can't infer @code{$pc}, and default 11994it to zero. 11995 11996@end itemize 11997 11998@node Analyze Collected Data 11999@section Using the Collected Data 12000 12001After the tracepoint experiment ends, you use @value{GDBN} commands 12002for examining the trace data. The basic idea is that each tracepoint 12003collects a trace @dfn{snapshot} every time it is hit and another 12004snapshot every time it single-steps. All these snapshots are 12005consecutively numbered from zero and go into a buffer, and you can 12006examine them later. The way you examine them is to @dfn{focus} on a 12007specific trace snapshot. When the remote stub is focused on a trace 12008snapshot, it will respond to all @value{GDBN} requests for memory and 12009registers by reading from the buffer which belongs to that snapshot, 12010rather than from @emph{real} memory or registers of the program being 12011debugged. This means that @strong{all} @value{GDBN} commands 12012(@code{print}, @code{info registers}, @code{backtrace}, etc.) will 12013behave as if we were currently debugging the program state as it was 12014when the tracepoint occurred. Any requests for data that are not in 12015the buffer will fail. 12016 12017@menu 12018* tfind:: How to select a trace snapshot 12019* tdump:: How to display all data for a snapshot 12020* save tracepoints:: How to save tracepoints for a future run 12021@end menu 12022 12023@node tfind 12024@subsection @code{tfind @var{n}} 12025 12026@kindex tfind 12027@cindex select trace snapshot 12028@cindex find trace snapshot 12029The basic command for selecting a trace snapshot from the buffer is 12030@code{tfind @var{n}}, which finds trace snapshot number @var{n}, 12031counting from zero. If no argument @var{n} is given, the next 12032snapshot is selected. 12033 12034Here are the various forms of using the @code{tfind} command. 12035 12036@table @code 12037@item tfind start 12038Find the first snapshot in the buffer. This is a synonym for 12039@code{tfind 0} (since 0 is the number of the first snapshot). 12040 12041@item tfind none 12042Stop debugging trace snapshots, resume @emph{live} debugging. 12043 12044@item tfind end 12045Same as @samp{tfind none}. 12046 12047@item tfind 12048No argument means find the next trace snapshot. 12049 12050@item tfind - 12051Find the previous trace snapshot before the current one. This permits 12052retracing earlier steps. 12053 12054@item tfind tracepoint @var{num} 12055Find the next snapshot associated with tracepoint @var{num}. Search 12056proceeds forward from the last examined trace snapshot. If no 12057argument @var{num} is given, it means find the next snapshot collected 12058for the same tracepoint as the current snapshot. 12059 12060@item tfind pc @var{addr} 12061Find the next snapshot associated with the value @var{addr} of the 12062program counter. Search proceeds forward from the last examined trace 12063snapshot. If no argument @var{addr} is given, it means find the next 12064snapshot with the same value of PC as the current snapshot. 12065 12066@item tfind outside @var{addr1}, @var{addr2} 12067Find the next snapshot whose PC is outside the given range of 12068addresses (exclusive). 12069 12070@item tfind range @var{addr1}, @var{addr2} 12071Find the next snapshot whose PC is between @var{addr1} and 12072@var{addr2} (inclusive). 12073 12074@item tfind line @r{[}@var{file}:@r{]}@var{n} 12075Find the next snapshot associated with the source line @var{n}. If 12076the optional argument @var{file} is given, refer to line @var{n} in 12077that source file. Search proceeds forward from the last examined 12078trace snapshot. If no argument @var{n} is given, it means find the 12079next line other than the one currently being examined; thus saying 12080@code{tfind line} repeatedly can appear to have the same effect as 12081stepping from line to line in a @emph{live} debugging session. 12082@end table 12083 12084The default arguments for the @code{tfind} commands are specifically 12085designed to make it easy to scan through the trace buffer. For 12086instance, @code{tfind} with no argument selects the next trace 12087snapshot, and @code{tfind -} with no argument selects the previous 12088trace snapshot. So, by giving one @code{tfind} command, and then 12089simply hitting @key{RET} repeatedly you can examine all the trace 12090snapshots in order. Or, by saying @code{tfind -} and then hitting 12091@key{RET} repeatedly you can examine the snapshots in reverse order. 12092The @code{tfind line} command with no argument selects the snapshot 12093for the next source line executed. The @code{tfind pc} command with 12094no argument selects the next snapshot with the same program counter 12095(PC) as the current frame. The @code{tfind tracepoint} command with 12096no argument selects the next trace snapshot collected by the same 12097tracepoint as the current one. 12098 12099In addition to letting you scan through the trace buffer manually, 12100these commands make it easy to construct @value{GDBN} scripts that 12101scan through the trace buffer and print out whatever collected data 12102you are interested in. Thus, if we want to examine the PC, FP, and SP 12103registers from each trace frame in the buffer, we can say this: 12104 12105@smallexample 12106(@value{GDBP}) @b{tfind start} 12107(@value{GDBP}) @b{while ($trace_frame != -1)} 12108> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ 12109 $trace_frame, $pc, $sp, $fp 12110> tfind 12111> end 12112 12113Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 12114Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 12115Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 12116Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 12117Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 12118Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 12119Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 12120Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 12121Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 12122Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 12123Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 12124@end smallexample 12125 12126Or, if we want to examine the variable @code{X} at each source line in 12127the buffer: 12128 12129@smallexample 12130(@value{GDBP}) @b{tfind start} 12131(@value{GDBP}) @b{while ($trace_frame != -1)} 12132> printf "Frame %d, X == %d\n", $trace_frame, X 12133> tfind line 12134> end 12135 12136Frame 0, X = 1 12137Frame 7, X = 2 12138Frame 13, X = 255 12139@end smallexample 12140 12141@node tdump 12142@subsection @code{tdump} 12143@kindex tdump 12144@cindex dump all data collected at tracepoint 12145@cindex tracepoint data, display 12146 12147This command takes no arguments. It prints all the data collected at 12148the current trace snapshot. 12149 12150@smallexample 12151(@value{GDBP}) @b{trace 444} 12152(@value{GDBP}) @b{actions} 12153Enter actions for tracepoint #2, one per line: 12154> collect $regs, $locals, $args, gdb_long_test 12155> end 12156 12157(@value{GDBP}) @b{tstart} 12158 12159(@value{GDBP}) @b{tfind line 444} 12160#0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) 12161at gdb_test.c:444 12162444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) 12163 12164(@value{GDBP}) @b{tdump} 12165Data collected at tracepoint 2, trace frame 1: 12166d0 0xc4aa0085 -995491707 12167d1 0x18 24 12168d2 0x80 128 12169d3 0x33 51 12170d4 0x71aea3d 119204413 12171d5 0x22 34 12172d6 0xe0 224 12173d7 0x380035 3670069 12174a0 0x19e24a 1696330 12175a1 0x3000668 50333288 12176a2 0x100 256 12177a3 0x322000 3284992 12178a4 0x3000698 50333336 12179a5 0x1ad3cc 1758156 12180fp 0x30bf3c 0x30bf3c 12181sp 0x30bf34 0x30bf34 12182ps 0x0 0 12183pc 0x20b2c8 0x20b2c8 12184fpcontrol 0x0 0 12185fpstatus 0x0 0 12186fpiaddr 0x0 0 12187p = 0x20e5b4 "gdb-test" 12188p1 = (void *) 0x11 12189p2 = (void *) 0x22 12190p3 = (void *) 0x33 12191p4 = (void *) 0x44 12192p5 = (void *) 0x55 12193p6 = (void *) 0x66 12194gdb_long_test = 17 '\021' 12195 12196(@value{GDBP}) 12197@end smallexample 12198 12199@code{tdump} works by scanning the tracepoint's current collection 12200actions and printing the value of each expression listed. So 12201@code{tdump} can fail, if after a run, you change the tracepoint's 12202actions to mention variables that were not collected during the run. 12203 12204Also, for tracepoints with @code{while-stepping} loops, @code{tdump} 12205uses the collected value of @code{$pc} to distinguish between trace 12206frames that were collected at the tracepoint hit, and frames that were 12207collected while stepping. This allows it to correctly choose whether 12208to display the basic list of collections, or the collections from the 12209body of the while-stepping loop. However, if @code{$pc} was not collected, 12210then @code{tdump} will always attempt to dump using the basic collection 12211list, and may fail if a while-stepping frame does not include all the 12212same data that is collected at the tracepoint hit. 12213@c This is getting pretty arcane, example would be good. 12214 12215@node save tracepoints 12216@subsection @code{save tracepoints @var{filename}} 12217@kindex save tracepoints 12218@kindex save-tracepoints 12219@cindex save tracepoints for future sessions 12220 12221This command saves all current tracepoint definitions together with 12222their actions and passcounts, into a file @file{@var{filename}} 12223suitable for use in a later debugging session. To read the saved 12224tracepoint definitions, use the @code{source} command (@pxref{Command 12225Files}). The @w{@code{save-tracepoints}} command is a deprecated 12226alias for @w{@code{save tracepoints}} 12227 12228@node Tracepoint Variables 12229@section Convenience Variables for Tracepoints 12230@cindex tracepoint variables 12231@cindex convenience variables for tracepoints 12232 12233@table @code 12234@vindex $trace_frame 12235@item (int) $trace_frame 12236The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no 12237snapshot is selected. 12238 12239@vindex $tracepoint 12240@item (int) $tracepoint 12241The tracepoint for the current trace snapshot. 12242 12243@vindex $trace_line 12244@item (int) $trace_line 12245The line number for the current trace snapshot. 12246 12247@vindex $trace_file 12248@item (char []) $trace_file 12249The source file for the current trace snapshot. 12250 12251@vindex $trace_func 12252@item (char []) $trace_func 12253The name of the function containing @code{$tracepoint}. 12254@end table 12255 12256Note: @code{$trace_file} is not suitable for use in @code{printf}, 12257use @code{output} instead. 12258 12259Here's a simple example of using these convenience variables for 12260stepping through all the trace snapshots and printing some of their 12261data. Note that these are not the same as trace state variables, 12262which are managed by the target. 12263 12264@smallexample 12265(@value{GDBP}) @b{tfind start} 12266 12267(@value{GDBP}) @b{while $trace_frame != -1} 12268> output $trace_file 12269> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint 12270> tfind 12271> end 12272@end smallexample 12273 12274@node Trace Files 12275@section Using Trace Files 12276@cindex trace files 12277 12278In some situations, the target running a trace experiment may no 12279longer be available; perhaps it crashed, or the hardware was needed 12280for a different activity. To handle these cases, you can arrange to 12281dump the trace data into a file, and later use that file as a source 12282of trace data, via the @code{target tfile} command. 12283 12284@table @code 12285 12286@kindex tsave 12287@item tsave [ -r ] @var{filename} 12288Save the trace data to @var{filename}. By default, this command 12289assumes that @var{filename} refers to the host filesystem, so if 12290necessary @value{GDBN} will copy raw trace data up from the target and 12291then save it. If the target supports it, you can also supply the 12292optional argument @code{-r} (``remote'') to direct the target to save 12293the data directly into @var{filename} in its own filesystem, which may be 12294more efficient if the trace buffer is very large. (Note, however, that 12295@code{target tfile} can only read from files accessible to the host.) 12296 12297@kindex target tfile 12298@kindex tfile 12299@item target tfile @var{filename} 12300Use the file named @var{filename} as a source of trace data. Commands 12301that examine data work as they do with a live target, but it is not 12302possible to run any new trace experiments. @code{tstatus} will report 12303the state of the trace run at the moment the data was saved, as well 12304as the current trace frame you are examining. @var{filename} must be 12305on a filesystem accessible to the host. 12306 12307@end table 12308 12309@node Overlays 12310@chapter Debugging Programs That Use Overlays 12311@cindex overlays 12312 12313If your program is too large to fit completely in your target system's 12314memory, you can sometimes use @dfn{overlays} to work around this 12315problem. @value{GDBN} provides some support for debugging programs that 12316use overlays. 12317 12318@menu 12319* How Overlays Work:: A general explanation of overlays. 12320* Overlay Commands:: Managing overlays in @value{GDBN}. 12321* Automatic Overlay Debugging:: @value{GDBN} can find out which overlays are 12322 mapped by asking the inferior. 12323* Overlay Sample Program:: A sample program using overlays. 12324@end menu 12325 12326@node How Overlays Work 12327@section How Overlays Work 12328@cindex mapped overlays 12329@cindex unmapped overlays 12330@cindex load address, overlay's 12331@cindex mapped address 12332@cindex overlay area 12333 12334Suppose you have a computer whose instruction address space is only 64 12335kilobytes long, but which has much more memory which can be accessed by 12336other means: special instructions, segment registers, or memory 12337management hardware, for example. Suppose further that you want to 12338adapt a program which is larger than 64 kilobytes to run on this system. 12339 12340One solution is to identify modules of your program which are relatively 12341independent, and need not call each other directly; call these modules 12342@dfn{overlays}. Separate the overlays from the main program, and place 12343their machine code in the larger memory. Place your main program in 12344instruction memory, but leave at least enough space there to hold the 12345largest overlay as well. 12346 12347Now, to call a function located in an overlay, you must first copy that 12348overlay's machine code from the large memory into the space set aside 12349for it in the instruction memory, and then jump to its entry point 12350there. 12351 12352@c NB: In the below the mapped area's size is greater or equal to the 12353@c size of all overlays. This is intentional to remind the developer 12354@c that overlays don't necessarily need to be the same size. 12355 12356@smallexample 12357@group 12358 Data Instruction Larger 12359Address Space Address Space Address Space 12360+-----------+ +-----------+ +-----------+ 12361| | | | | | 12362+-----------+ +-----------+ +-----------+<-- overlay 1 12363| program | | main | .----| overlay 1 | load address 12364| variables | | program | | +-----------+ 12365| and heap | | | | | | 12366+-----------+ | | | +-----------+<-- overlay 2 12367| | +-----------+ | | | load address 12368+-----------+ | | | .-| overlay 2 | 12369 | | | | | | 12370 mapped --->+-----------+ | | +-----------+ 12371 address | | | | | | 12372 | overlay | <-' | | | 12373 | area | <---' +-----------+<-- overlay 3 12374 | | <---. | | load address 12375 +-----------+ `--| overlay 3 | 12376 | | | | 12377 +-----------+ | | 12378 +-----------+ 12379 | | 12380 +-----------+ 12381 12382 @anchor{A code overlay}A code overlay 12383@end group 12384@end smallexample 12385 12386The diagram (@pxref{A code overlay}) shows a system with separate data 12387and instruction address spaces. To map an overlay, the program copies 12388its code from the larger address space to the instruction address space. 12389Since the overlays shown here all use the same mapped address, only one 12390may be mapped at a time. For a system with a single address space for 12391data and instructions, the diagram would be similar, except that the 12392program variables and heap would share an address space with the main 12393program and the overlay area. 12394 12395An overlay loaded into instruction memory and ready for use is called a 12396@dfn{mapped} overlay; its @dfn{mapped address} is its address in the 12397instruction memory. An overlay not present (or only partially present) 12398in instruction memory is called @dfn{unmapped}; its @dfn{load address} 12399is its address in the larger memory. The mapped address is also called 12400the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also 12401called the @dfn{load memory address}, or @dfn{LMA}. 12402 12403Unfortunately, overlays are not a completely transparent way to adapt a 12404program to limited instruction memory. They introduce a new set of 12405global constraints you must keep in mind as you design your program: 12406 12407@itemize @bullet 12408 12409@item 12410Before calling or returning to a function in an overlay, your program 12411must make sure that overlay is actually mapped. Otherwise, the call or 12412return will transfer control to the right address, but in the wrong 12413overlay, and your program will probably crash. 12414 12415@item 12416If the process of mapping an overlay is expensive on your system, you 12417will need to choose your overlays carefully to minimize their effect on 12418your program's performance. 12419 12420@item 12421The executable file you load onto your system must contain each 12422overlay's instructions, appearing at the overlay's load address, not its 12423mapped address. However, each overlay's instructions must be relocated 12424and its symbols defined as if the overlay were at its mapped address. 12425You can use GNU linker scripts to specify different load and relocation 12426addresses for pieces of your program; see @ref{Overlay Description,,, 12427ld.info, Using ld: the GNU linker}. 12428 12429@item 12430The procedure for loading executable files onto your system must be able 12431to load their contents into the larger address space as well as the 12432instruction and data spaces. 12433 12434@end itemize 12435 12436The overlay system described above is rather simple, and could be 12437improved in many ways: 12438 12439@itemize @bullet 12440 12441@item 12442If your system has suitable bank switch registers or memory management 12443hardware, you could use those facilities to make an overlay's load area 12444contents simply appear at their mapped address in instruction space. 12445This would probably be faster than copying the overlay to its mapped 12446area in the usual way. 12447 12448@item 12449If your overlays are small enough, you could set aside more than one 12450overlay area, and have more than one overlay mapped at a time. 12451 12452@item 12453You can use overlays to manage data, as well as instructions. In 12454general, data overlays are even less transparent to your design than 12455code overlays: whereas code overlays only require care when you call or 12456return to functions, data overlays require care every time you access 12457the data. Also, if you change the contents of a data overlay, you 12458must copy its contents back out to its load address before you can copy a 12459different data overlay into the same mapped area. 12460 12461@end itemize 12462 12463 12464@node Overlay Commands 12465@section Overlay Commands 12466 12467To use @value{GDBN}'s overlay support, each overlay in your program must 12468correspond to a separate section of the executable file. The section's 12469virtual memory address and load memory address must be the overlay's 12470mapped and load addresses. Identifying overlays with sections allows 12471@value{GDBN} to determine the appropriate address of a function or 12472variable, depending on whether the overlay is mapped or not. 12473 12474@value{GDBN}'s overlay commands all start with the word @code{overlay}; 12475you can abbreviate this as @code{ov} or @code{ovly}. The commands are: 12476 12477@table @code 12478@item overlay off 12479@kindex overlay 12480Disable @value{GDBN}'s overlay support. When overlay support is 12481disabled, @value{GDBN} assumes that all functions and variables are 12482always present at their mapped addresses. By default, @value{GDBN}'s 12483overlay support is disabled. 12484 12485@item overlay manual 12486@cindex manual overlay debugging 12487Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN} 12488relies on you to tell it which overlays are mapped, and which are not, 12489using the @code{overlay map-overlay} and @code{overlay unmap-overlay} 12490commands described below. 12491 12492@item overlay map-overlay @var{overlay} 12493@itemx overlay map @var{overlay} 12494@cindex map an overlay 12495Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must 12496be the name of the object file section containing the overlay. When an 12497overlay is mapped, @value{GDBN} assumes it can find the overlay's 12498functions and variables at their mapped addresses. @value{GDBN} assumes 12499that any other overlays whose mapped ranges overlap that of 12500@var{overlay} are now unmapped. 12501 12502@item overlay unmap-overlay @var{overlay} 12503@itemx overlay unmap @var{overlay} 12504@cindex unmap an overlay 12505Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay} 12506must be the name of the object file section containing the overlay. 12507When an overlay is unmapped, @value{GDBN} assumes it can find the 12508overlay's functions and variables at their load addresses. 12509 12510@item overlay auto 12511Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN} 12512consults a data structure the overlay manager maintains in the inferior 12513to see which overlays are mapped. For details, see @ref{Automatic 12514Overlay Debugging}. 12515 12516@item overlay load-target 12517@itemx overlay load 12518@cindex reloading the overlay table 12519Re-read the overlay table from the inferior. Normally, @value{GDBN} 12520re-reads the table @value{GDBN} automatically each time the inferior 12521stops, so this command should only be necessary if you have changed the 12522overlay mapping yourself using @value{GDBN}. This command is only 12523useful when using automatic overlay debugging. 12524 12525@item overlay list-overlays 12526@itemx overlay list 12527@cindex listing mapped overlays 12528Display a list of the overlays currently mapped, along with their mapped 12529addresses, load addresses, and sizes. 12530 12531@end table 12532 12533Normally, when @value{GDBN} prints a code address, it includes the name 12534of the function the address falls in: 12535 12536@smallexample 12537(@value{GDBP}) print main 12538$3 = @{int ()@} 0x11a0 <main> 12539@end smallexample 12540@noindent 12541When overlay debugging is enabled, @value{GDBN} recognizes code in 12542unmapped overlays, and prints the names of unmapped functions with 12543asterisks around them. For example, if @code{foo} is a function in an 12544unmapped overlay, @value{GDBN} prints it this way: 12545 12546@smallexample 12547(@value{GDBP}) overlay list 12548No sections are mapped. 12549(@value{GDBP}) print foo 12550$5 = @{int (int)@} 0x100000 <*foo*> 12551@end smallexample 12552@noindent 12553When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's 12554name normally: 12555 12556@smallexample 12557(@value{GDBP}) overlay list 12558Section .ov.foo.text, loaded at 0x100000 - 0x100034, 12559 mapped at 0x1016 - 0x104a 12560(@value{GDBP}) print foo 12561$6 = @{int (int)@} 0x1016 <foo> 12562@end smallexample 12563 12564When overlay debugging is enabled, @value{GDBN} can find the correct 12565address for functions and variables in an overlay, whether or not the 12566overlay is mapped. This allows most @value{GDBN} commands, like 12567@code{break} and @code{disassemble}, to work normally, even on unmapped 12568code. However, @value{GDBN}'s breakpoint support has some limitations: 12569 12570@itemize @bullet 12571@item 12572@cindex breakpoints in overlays 12573@cindex overlays, setting breakpoints in 12574You can set breakpoints in functions in unmapped overlays, as long as 12575@value{GDBN} can write to the overlay at its load address. 12576@item 12577@value{GDBN} can not set hardware or simulator-based breakpoints in 12578unmapped overlays. However, if you set a breakpoint at the end of your 12579overlay manager (and tell @value{GDBN} which overlays are now mapped, if 12580you are using manual overlay management), @value{GDBN} will re-set its 12581breakpoints properly. 12582@end itemize 12583 12584 12585@node Automatic Overlay Debugging 12586@section Automatic Overlay Debugging 12587@cindex automatic overlay debugging 12588 12589@value{GDBN} can automatically track which overlays are mapped and which 12590are not, given some simple co-operation from the overlay manager in the 12591inferior. If you enable automatic overlay debugging with the 12592@code{overlay auto} command (@pxref{Overlay Commands}), @value{GDBN} 12593looks in the inferior's memory for certain variables describing the 12594current state of the overlays. 12595 12596Here are the variables your overlay manager must define to support 12597@value{GDBN}'s automatic overlay debugging: 12598 12599@table @asis 12600 12601@item @code{_ovly_table}: 12602This variable must be an array of the following structures: 12603 12604@smallexample 12605struct 12606@{ 12607 /* The overlay's mapped address. */ 12608 unsigned long vma; 12609 12610 /* The size of the overlay, in bytes. */ 12611 unsigned long size; 12612 12613 /* The overlay's load address. */ 12614 unsigned long lma; 12615 12616 /* Non-zero if the overlay is currently mapped; 12617 zero otherwise. */ 12618 unsigned long mapped; 12619@} 12620@end smallexample 12621 12622@item @code{_novlys}: 12623This variable must be a four-byte signed integer, holding the total 12624number of elements in @code{_ovly_table}. 12625 12626@end table 12627 12628To decide whether a particular overlay is mapped or not, @value{GDBN} 12629looks for an entry in @w{@code{_ovly_table}} whose @code{vma} and 12630@code{lma} members equal the VMA and LMA of the overlay's section in the 12631executable file. When @value{GDBN} finds a matching entry, it consults 12632the entry's @code{mapped} member to determine whether the overlay is 12633currently mapped. 12634 12635In addition, your overlay manager may define a function called 12636@code{_ovly_debug_event}. If this function is defined, @value{GDBN} 12637will silently set a breakpoint there. If the overlay manager then 12638calls this function whenever it has changed the overlay table, this 12639will enable @value{GDBN} to accurately keep track of which overlays 12640are in program memory, and update any breakpoints that may be set 12641in overlays. This will allow breakpoints to work even if the 12642overlays are kept in ROM or other non-writable memory while they 12643are not being executed. 12644 12645@node Overlay Sample Program 12646@section Overlay Sample Program 12647@cindex overlay example program 12648 12649When linking a program which uses overlays, you must place the overlays 12650at their load addresses, while relocating them to run at their mapped 12651addresses. To do this, you must write a linker script (@pxref{Overlay 12652Description,,, ld.info, Using ld: the GNU linker}). Unfortunately, 12653since linker scripts are specific to a particular host system, target 12654architecture, and target memory layout, this manual cannot provide 12655portable sample code demonstrating @value{GDBN}'s overlay support. 12656 12657However, the @value{GDBN} source distribution does contain an overlaid 12658program, with linker scripts for a few systems, as part of its test 12659suite. The program consists of the following files from 12660@file{gdb/testsuite/gdb.base}: 12661 12662@table @file 12663@item overlays.c 12664The main program file. 12665@item ovlymgr.c 12666A simple overlay manager, used by @file{overlays.c}. 12667@item foo.c 12668@itemx bar.c 12669@itemx baz.c 12670@itemx grbx.c 12671Overlay modules, loaded and used by @file{overlays.c}. 12672@item d10v.ld 12673@itemx m32r.ld 12674Linker scripts for linking the test program on the @code{d10v-elf} 12675and @code{m32r-elf} targets. 12676@end table 12677 12678You can build the test program using the @code{d10v-elf} GCC 12679cross-compiler like this: 12680 12681@smallexample 12682$ d10v-elf-gcc -g -c overlays.c 12683$ d10v-elf-gcc -g -c ovlymgr.c 12684$ d10v-elf-gcc -g -c foo.c 12685$ d10v-elf-gcc -g -c bar.c 12686$ d10v-elf-gcc -g -c baz.c 12687$ d10v-elf-gcc -g -c grbx.c 12688$ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ 12689 baz.o grbx.o -Wl,-Td10v.ld -o overlays 12690@end smallexample 12691 12692The build process is identical for any other architecture, except that 12693you must substitute the appropriate compiler and linker script for the 12694target system for @code{d10v-elf-gcc} and @code{d10v.ld}. 12695 12696 12697@node Languages 12698@chapter Using @value{GDBN} with Different Languages 12699@cindex languages 12700 12701Although programming languages generally have common aspects, they are 12702rarely expressed in the same manner. For instance, in ANSI C, 12703dereferencing a pointer @code{p} is accomplished by @code{*p}, but in 12704Modula-2, it is accomplished by @code{p^}. Values can also be 12705represented (and displayed) differently. Hex numbers in C appear as 12706@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}. 12707 12708@cindex working language 12709Language-specific information is built into @value{GDBN} for some languages, 12710allowing you to express operations like the above in your program's 12711native language, and allowing @value{GDBN} to output values in a manner 12712consistent with the syntax of your program's native language. The 12713language you use to build expressions is called the @dfn{working 12714language}. 12715 12716@menu 12717* Setting:: Switching between source languages 12718* Show:: Displaying the language 12719* Checks:: Type and range checks 12720* Supported Languages:: Supported languages 12721* Unsupported Languages:: Unsupported languages 12722@end menu 12723 12724@node Setting 12725@section Switching Between Source Languages 12726 12727There are two ways to control the working language---either have @value{GDBN} 12728set it automatically, or select it manually yourself. You can use the 12729@code{set language} command for either purpose. On startup, @value{GDBN} 12730defaults to setting the language automatically. The working language is 12731used to determine how expressions you type are interpreted, how values 12732are printed, etc. 12733 12734In addition to the working language, every source file that 12735@value{GDBN} knows about has its own working language. For some object 12736file formats, the compiler might indicate which language a particular 12737source file is in. However, most of the time @value{GDBN} infers the 12738language from the name of the file. The language of a source file 12739controls whether C@t{++} names are demangled---this way @code{backtrace} can 12740show each frame appropriately for its own language. There is no way to 12741set the language of a source file from within @value{GDBN}, but you can 12742set the language associated with a filename extension. @xref{Show, , 12743Displaying the Language}. 12744 12745This is most commonly a problem when you use a program, such 12746as @code{cfront} or @code{f2c}, that generates C but is written in 12747another language. In that case, make the 12748program use @code{#line} directives in its C output; that way 12749@value{GDBN} will know the correct language of the source code of the original 12750program, and will display that source code, not the generated C code. 12751 12752@menu 12753* Filenames:: Filename extensions and languages. 12754* Manually:: Setting the working language manually 12755* Automatically:: Having @value{GDBN} infer the source language 12756@end menu 12757 12758@node Filenames 12759@subsection List of Filename Extensions and Languages 12760 12761If a source file name ends in one of the following extensions, then 12762@value{GDBN} infers that its language is the one indicated. 12763 12764@table @file 12765@item .ada 12766@itemx .ads 12767@itemx .adb 12768@itemx .a 12769Ada source file. 12770 12771@item .c 12772C source file 12773 12774@item .C 12775@itemx .cc 12776@itemx .cp 12777@itemx .cpp 12778@itemx .cxx 12779@itemx .c++ 12780C@t{++} source file 12781 12782@item .d 12783D source file 12784 12785@item .m 12786Objective-C source file 12787 12788@item .f 12789@itemx .F 12790Fortran source file 12791 12792@item .mod 12793Modula-2 source file 12794 12795@item .s 12796@itemx .S 12797Assembler source file. This actually behaves almost like C, but 12798@value{GDBN} does not skip over function prologues when stepping. 12799@end table 12800 12801In addition, you may set the language associated with a filename 12802extension. @xref{Show, , Displaying the Language}. 12803 12804@node Manually 12805@subsection Setting the Working Language 12806 12807If you allow @value{GDBN} to set the language automatically, 12808expressions are interpreted the same way in your debugging session and 12809your program. 12810 12811@kindex set language 12812If you wish, you may set the language manually. To do this, issue the 12813command @samp{set language @var{lang}}, where @var{lang} is the name of 12814a language, such as 12815@code{c} or @code{modula-2}. 12816For a list of the supported languages, type @samp{set language}. 12817 12818Setting the language manually prevents @value{GDBN} from updating the working 12819language automatically. This can lead to confusion if you try 12820to debug a program when the working language is not the same as the 12821source language, when an expression is acceptable to both 12822languages---but means different things. For instance, if the current 12823source file were written in C, and @value{GDBN} was parsing Modula-2, a 12824command such as: 12825 12826@smallexample 12827print a = b + c 12828@end smallexample 12829 12830@noindent 12831might not have the effect you intended. In C, this means to add 12832@code{b} and @code{c} and place the result in @code{a}. The result 12833printed would be the value of @code{a}. In Modula-2, this means to compare 12834@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value. 12835 12836@node Automatically 12837@subsection Having @value{GDBN} Infer the Source Language 12838 12839To have @value{GDBN} set the working language automatically, use 12840@samp{set language local} or @samp{set language auto}. @value{GDBN} 12841then infers the working language. That is, when your program stops in a 12842frame (usually by encountering a breakpoint), @value{GDBN} sets the 12843working language to the language recorded for the function in that 12844frame. If the language for a frame is unknown (that is, if the function 12845or block corresponding to the frame was defined in a source file that 12846does not have a recognized extension), the current working language is 12847not changed, and @value{GDBN} issues a warning. 12848 12849This may not seem necessary for most programs, which are written 12850entirely in one source language. However, program modules and libraries 12851written in one source language can be used by a main program written in 12852a different source language. Using @samp{set language auto} in this 12853case frees you from having to set the working language manually. 12854 12855@node Show 12856@section Displaying the Language 12857 12858The following commands help you find out which language is the 12859working language, and also what language source files were written in. 12860 12861@table @code 12862@item show language 12863@kindex show language 12864Display the current working language. This is the 12865language you can use with commands such as @code{print} to 12866build and compute expressions that may involve variables in your program. 12867 12868@item info frame 12869@kindex info frame@r{, show the source language} 12870Display the source language for this frame. This language becomes the 12871working language if you use an identifier from this frame. 12872@xref{Frame Info, ,Information about a Frame}, to identify the other 12873information listed here. 12874 12875@item info source 12876@kindex info source@r{, show the source language} 12877Display the source language of this source file. 12878@xref{Symbols, ,Examining the Symbol Table}, to identify the other 12879information listed here. 12880@end table 12881 12882In unusual circumstances, you may have source files with extensions 12883not in the standard list. You can then set the extension associated 12884with a language explicitly: 12885 12886@table @code 12887@item set extension-language @var{ext} @var{language} 12888@kindex set extension-language 12889Tell @value{GDBN} that source files with extension @var{ext} are to be 12890assumed as written in the source language @var{language}. 12891 12892@item info extensions 12893@kindex info extensions 12894List all the filename extensions and the associated languages. 12895@end table 12896 12897@node Checks 12898@section Type and Range Checking 12899 12900Some languages are designed to guard you against making seemingly common 12901errors through a series of compile- and run-time checks. These include 12902checking the type of arguments to functions and operators and making 12903sure mathematical overflows are caught at run time. Checks such as 12904these help to ensure a program's correctness once it has been compiled 12905by eliminating type mismatches and providing active checks for range 12906errors when your program is running. 12907 12908By default @value{GDBN} checks for these errors according to the 12909rules of the current source language. Although @value{GDBN} does not check 12910the statements in your program, it can check expressions entered directly 12911into @value{GDBN} for evaluation via the @code{print} command, for example. 12912 12913@menu 12914* Type Checking:: An overview of type checking 12915* Range Checking:: An overview of range checking 12916@end menu 12917 12918@cindex type checking 12919@cindex checks, type 12920@node Type Checking 12921@subsection An Overview of Type Checking 12922 12923Some languages, such as C and C@t{++}, are strongly typed, meaning that the 12924arguments to operators and functions have to be of the correct type, 12925otherwise an error occurs. These checks prevent type mismatch 12926errors from ever causing any run-time problems. For example, 12927 12928@smallexample 12929int klass::my_method(char *b) @{ return b ? 1 : 2; @} 12930 12931(@value{GDBP}) print obj.my_method (0) 12932$1 = 2 12933@exdent but 12934(@value{GDBP}) print obj.my_method (0x1234) 12935Cannot resolve method klass::my_method to any overloaded instance 12936@end smallexample 12937 12938The second example fails because in C@t{++} the integer constant 12939@samp{0x1234} is not type-compatible with the pointer parameter type. 12940 12941For the expressions you use in @value{GDBN} commands, you can tell 12942@value{GDBN} to not enforce strict type checking or 12943to treat any mismatches as errors and abandon the expression; 12944When type checking is disabled, @value{GDBN} successfully evaluates 12945expressions like the second example above. 12946 12947Even if type checking is off, there may be other reasons 12948related to type that prevent @value{GDBN} from evaluating an expression. 12949For instance, @value{GDBN} does not know how to add an @code{int} and 12950a @code{struct foo}. These particular type errors have nothing to do 12951with the language in use and usually arise from expressions which make 12952little sense to evaluate anyway. 12953 12954@value{GDBN} provides some additional commands for controlling type checking: 12955 12956@kindex set check type 12957@kindex show check type 12958@table @code 12959@item set check type on 12960@itemx set check type off 12961Set strict type checking on or off. If any type mismatches occur in 12962evaluating an expression while type checking is on, @value{GDBN} prints a 12963message and aborts evaluation of the expression. 12964 12965@item show check type 12966Show the current setting of type checking and whether @value{GDBN} 12967is enforcing strict type checking rules. 12968@end table 12969 12970@cindex range checking 12971@cindex checks, range 12972@node Range Checking 12973@subsection An Overview of Range Checking 12974 12975In some languages (such as Modula-2), it is an error to exceed the 12976bounds of a type; this is enforced with run-time checks. Such range 12977checking is meant to ensure program correctness by making sure 12978computations do not overflow, or indices on an array element access do 12979not exceed the bounds of the array. 12980 12981For expressions you use in @value{GDBN} commands, you can tell 12982@value{GDBN} to treat range errors in one of three ways: ignore them, 12983always treat them as errors and abandon the expression, or issue 12984warnings but evaluate the expression anyway. 12985 12986A range error can result from numerical overflow, from exceeding an 12987array index bound, or when you type a constant that is not a member 12988of any type. Some languages, however, do not treat overflows as an 12989error. In many implementations of C, mathematical overflow causes the 12990result to ``wrap around'' to lower values---for example, if @var{m} is 12991the largest integer value, and @var{s} is the smallest, then 12992 12993@smallexample 12994@var{m} + 1 @result{} @var{s} 12995@end smallexample 12996 12997This, too, is specific to individual languages, and in some cases 12998specific to individual compilers or machines. @xref{Supported Languages, , 12999Supported Languages}, for further details on specific languages. 13000 13001@value{GDBN} provides some additional commands for controlling the range checker: 13002 13003@kindex set check range 13004@kindex show check range 13005@table @code 13006@item set check range auto 13007Set range checking on or off based on the current working language. 13008@xref{Supported Languages, ,Supported Languages}, for the default settings for 13009each language. 13010 13011@item set check range on 13012@itemx set check range off 13013Set range checking on or off, overriding the default setting for the 13014current working language. A warning is issued if the setting does not 13015match the language default. If a range error occurs and range checking is on, 13016then a message is printed and evaluation of the expression is aborted. 13017 13018@item set check range warn 13019Output messages when the @value{GDBN} range checker detects a range error, 13020but attempt to evaluate the expression anyway. Evaluating the 13021expression may still be impossible for other reasons, such as accessing 13022memory that the process does not own (a typical example from many Unix 13023systems). 13024 13025@item show range 13026Show the current setting of the range checker, and whether or not it is 13027being set automatically by @value{GDBN}. 13028@end table 13029 13030@node Supported Languages 13031@section Supported Languages 13032 13033@value{GDBN} supports C, C@t{++}, D, Go, Objective-C, Fortran, Java, 13034OpenCL C, Pascal, assembly, Modula-2, and Ada. 13035@c This is false ... 13036Some @value{GDBN} features may be used in expressions regardless of the 13037language you use: the @value{GDBN} @code{@@} and @code{::} operators, 13038and the @samp{@{type@}addr} construct (@pxref{Expressions, 13039,Expressions}) can be used with the constructs of any supported 13040language. 13041 13042The following sections detail to what degree each source language is 13043supported by @value{GDBN}. These sections are not meant to be language 13044tutorials or references, but serve only as a reference guide to what the 13045@value{GDBN} expression parser accepts, and what input and output 13046formats should look like for different languages. There are many good 13047books written on each of these languages; please look to these for a 13048language reference or tutorial. 13049 13050@menu 13051* C:: C and C@t{++} 13052* D:: D 13053* Go:: Go 13054* Objective-C:: Objective-C 13055* OpenCL C:: OpenCL C 13056* Fortran:: Fortran 13057* Pascal:: Pascal 13058* Modula-2:: Modula-2 13059* Ada:: Ada 13060@end menu 13061 13062@node C 13063@subsection C and C@t{++} 13064 13065@cindex C and C@t{++} 13066@cindex expressions in C or C@t{++} 13067 13068Since C and C@t{++} are so closely related, many features of @value{GDBN} apply 13069to both languages. Whenever this is the case, we discuss those languages 13070together. 13071 13072@cindex C@t{++} 13073@cindex @code{g++}, @sc{gnu} C@t{++} compiler 13074@cindex @sc{gnu} C@t{++} 13075The C@t{++} debugging facilities are jointly implemented by the C@t{++} 13076compiler and @value{GDBN}. Therefore, to debug your C@t{++} code 13077effectively, you must compile your C@t{++} programs with a supported 13078C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++} 13079compiler (@code{aCC}). 13080 13081@menu 13082* C Operators:: C and C@t{++} operators 13083* C Constants:: C and C@t{++} constants 13084* C Plus Plus Expressions:: C@t{++} expressions 13085* C Defaults:: Default settings for C and C@t{++} 13086* C Checks:: C and C@t{++} type and range checks 13087* Debugging C:: @value{GDBN} and C 13088* Debugging C Plus Plus:: @value{GDBN} features for C@t{++} 13089* Decimal Floating Point:: Numbers in Decimal Floating Point format 13090@end menu 13091 13092@node C Operators 13093@subsubsection C and C@t{++} Operators 13094 13095@cindex C and C@t{++} operators 13096 13097Operators must be defined on values of specific types. For instance, 13098@code{+} is defined on numbers, but not on structures. Operators are 13099often defined on groups of types. 13100 13101For the purposes of C and C@t{++}, the following definitions hold: 13102 13103@itemize @bullet 13104 13105@item 13106@emph{Integral types} include @code{int} with any of its storage-class 13107specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}. 13108 13109@item 13110@emph{Floating-point types} include @code{float}, @code{double}, and 13111@code{long double} (if supported by the target platform). 13112 13113@item 13114@emph{Pointer types} include all types defined as @code{(@var{type} *)}. 13115 13116@item 13117@emph{Scalar types} include all of the above. 13118 13119@end itemize 13120 13121@noindent 13122The following operators are supported. They are listed here 13123in order of increasing precedence: 13124 13125@table @code 13126@item , 13127The comma or sequencing operator. Expressions in a comma-separated list 13128are evaluated from left to right, with the result of the entire 13129expression being the last expression evaluated. 13130 13131@item = 13132Assignment. The value of an assignment expression is the value 13133assigned. Defined on scalar types. 13134 13135@item @var{op}= 13136Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}}, 13137and translated to @w{@code{@var{a} = @var{a op b}}}. 13138@w{@code{@var{op}=}} and @code{=} have the same precedence. 13139@var{op} is any one of the operators @code{|}, @code{^}, @code{&}, 13140@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}. 13141 13142@item ?: 13143The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought 13144of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an 13145integral type. 13146 13147@item || 13148Logical @sc{or}. Defined on integral types. 13149 13150@item && 13151Logical @sc{and}. Defined on integral types. 13152 13153@item | 13154Bitwise @sc{or}. Defined on integral types. 13155 13156@item ^ 13157Bitwise exclusive-@sc{or}. Defined on integral types. 13158 13159@item & 13160Bitwise @sc{and}. Defined on integral types. 13161 13162@item ==@r{, }!= 13163Equality and inequality. Defined on scalar types. The value of these 13164expressions is 0 for false and non-zero for true. 13165 13166@item <@r{, }>@r{, }<=@r{, }>= 13167Less than, greater than, less than or equal, greater than or equal. 13168Defined on scalar types. The value of these expressions is 0 for false 13169and non-zero for true. 13170 13171@item <<@r{, }>> 13172left shift, and right shift. Defined on integral types. 13173 13174@item @@ 13175The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}). 13176 13177@item +@r{, }- 13178Addition and subtraction. Defined on integral types, floating-point types and 13179pointer types. 13180 13181@item *@r{, }/@r{, }% 13182Multiplication, division, and modulus. Multiplication and division are 13183defined on integral and floating-point types. Modulus is defined on 13184integral types. 13185 13186@item ++@r{, }-- 13187Increment and decrement. When appearing before a variable, the 13188operation is performed before the variable is used in an expression; 13189when appearing after it, the variable's value is used before the 13190operation takes place. 13191 13192@item * 13193Pointer dereferencing. Defined on pointer types. Same precedence as 13194@code{++}. 13195 13196@item & 13197Address operator. Defined on variables. Same precedence as @code{++}. 13198 13199For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is 13200allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})} 13201to examine the address 13202where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is 13203stored. 13204 13205@item - 13206Negative. Defined on integral and floating-point types. Same 13207precedence as @code{++}. 13208 13209@item ! 13210Logical negation. Defined on integral types. Same precedence as 13211@code{++}. 13212 13213@item ~ 13214Bitwise complement operator. Defined on integral types. Same precedence as 13215@code{++}. 13216 13217 13218@item .@r{, }-> 13219Structure member, and pointer-to-structure member. For convenience, 13220@value{GDBN} regards the two as equivalent, choosing whether to dereference a 13221pointer based on the stored type information. 13222Defined on @code{struct} and @code{union} data. 13223 13224@item .*@r{, }->* 13225Dereferences of pointers to members. 13226 13227@item [] 13228Array indexing. @code{@var{a}[@var{i}]} is defined as 13229@code{*(@var{a}+@var{i})}. Same precedence as @code{->}. 13230 13231@item () 13232Function parameter list. Same precedence as @code{->}. 13233 13234@item :: 13235C@t{++} scope resolution operator. Defined on @code{struct}, @code{union}, 13236and @code{class} types. 13237 13238@item :: 13239Doubled colons also represent the @value{GDBN} scope operator 13240(@pxref{Expressions, ,Expressions}). Same precedence as @code{::}, 13241above. 13242@end table 13243 13244If an operator is redefined in the user code, @value{GDBN} usually 13245attempts to invoke the redefined version instead of using the operator's 13246predefined meaning. 13247 13248@node C Constants 13249@subsubsection C and C@t{++} Constants 13250 13251@cindex C and C@t{++} constants 13252 13253@value{GDBN} allows you to express the constants of C and C@t{++} in the 13254following ways: 13255 13256@itemize @bullet 13257@item 13258Integer constants are a sequence of digits. Octal constants are 13259specified by a leading @samp{0} (i.e.@: zero), and hexadecimal constants 13260by a leading @samp{0x} or @samp{0X}. Constants may also end with a letter 13261@samp{l}, specifying that the constant should be treated as a 13262@code{long} value. 13263 13264@item 13265Floating point constants are a sequence of digits, followed by a decimal 13266point, followed by a sequence of digits, and optionally followed by an 13267exponent. An exponent is of the form: 13268@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another 13269sequence of digits. The @samp{+} is optional for positive exponents. 13270A floating-point constant may also end with a letter @samp{f} or 13271@samp{F}, specifying that the constant should be treated as being of 13272the @code{float} (as opposed to the default @code{double}) type; or with 13273a letter @samp{l} or @samp{L}, which specifies a @code{long double} 13274constant. 13275 13276@item 13277Enumerated constants consist of enumerated identifiers, or their 13278integral equivalents. 13279 13280@item 13281Character constants are a single character surrounded by single quotes 13282(@code{'}), or a number---the ordinal value of the corresponding character 13283(usually its @sc{ascii} value). Within quotes, the single character may 13284be represented by a letter or by @dfn{escape sequences}, which are of 13285the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation 13286of the character's ordinal value; or of the form @samp{\@var{x}}, where 13287@samp{@var{x}} is a predefined special character---for example, 13288@samp{\n} for newline. 13289 13290Wide character constants can be written by prefixing a character 13291constant with @samp{L}, as in C. For example, @samp{L'x'} is the wide 13292form of @samp{x}. The target wide character set is used when 13293computing the value of this constant (@pxref{Character Sets}). 13294 13295@item 13296String constants are a sequence of character constants surrounded by 13297double quotes (@code{"}). Any valid character constant (as described 13298above) may appear. Double quotes within the string must be preceded by 13299a backslash, so for instance @samp{"a\"b'c"} is a string of five 13300characters. 13301 13302Wide string constants can be written by prefixing a string constant 13303with @samp{L}, as in C. The target wide character set is used when 13304computing the value of this constant (@pxref{Character Sets}). 13305 13306@item 13307Pointer constants are an integral value. You can also write pointers 13308to constants using the C operator @samp{&}. 13309 13310@item 13311Array constants are comma-separated lists surrounded by braces @samp{@{} 13312and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of 13313integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array, 13314and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers. 13315@end itemize 13316 13317@node C Plus Plus Expressions 13318@subsubsection C@t{++} Expressions 13319 13320@cindex expressions in C@t{++} 13321@value{GDBN} expression handling can interpret most C@t{++} expressions. 13322 13323@cindex debugging C@t{++} programs 13324@cindex C@t{++} compilers 13325@cindex debug formats and C@t{++} 13326@cindex @value{NGCC} and C@t{++} 13327@quotation 13328@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use 13329the proper compiler and the proper debug format. Currently, 13330@value{GDBN} works best when debugging C@t{++} code that is compiled 13331with the most recent version of @value{NGCC} possible. The DWARF 13332debugging format is preferred; @value{NGCC} defaults to this on most 13333popular platforms. Other compilers and/or debug formats are likely to 13334work badly or not at all when using @value{GDBN} to debug C@t{++} 13335code. @xref{Compilation}. 13336@end quotation 13337 13338@enumerate 13339 13340@cindex member functions 13341@item 13342Member function calls are allowed; you can use expressions like 13343 13344@smallexample 13345count = aml->GetOriginal(x, y) 13346@end smallexample 13347 13348@vindex this@r{, inside C@t{++} member functions} 13349@cindex namespace in C@t{++} 13350@item 13351While a member function is active (in the selected stack frame), your 13352expressions have the same namespace available as the member function; 13353that is, @value{GDBN} allows implicit references to the class instance 13354pointer @code{this} following the same rules as C@t{++}. @code{using} 13355declarations in the current scope are also respected by @value{GDBN}. 13356 13357@cindex call overloaded functions 13358@cindex overloaded functions, calling 13359@cindex type conversions in C@t{++} 13360@item 13361You can call overloaded functions; @value{GDBN} resolves the function 13362call to the right definition, with some restrictions. @value{GDBN} does not 13363perform overload resolution involving user-defined type conversions, 13364calls to constructors, or instantiations of templates that do not exist 13365in the program. It also cannot handle ellipsis argument lists or 13366default arguments. 13367 13368It does perform integral conversions and promotions, floating-point 13369promotions, arithmetic conversions, pointer conversions, conversions of 13370class objects to base classes, and standard conversions such as those of 13371functions or arrays to pointers; it requires an exact match on the 13372number of function arguments. 13373 13374Overload resolution is always performed, unless you have specified 13375@code{set overload-resolution off}. @xref{Debugging C Plus Plus, 13376,@value{GDBN} Features for C@t{++}}. 13377 13378You must specify @code{set overload-resolution off} in order to use an 13379explicit function signature to call an overloaded function, as in 13380@smallexample 13381p 'foo(char,int)'('x', 13) 13382@end smallexample 13383 13384The @value{GDBN} command-completion facility can simplify this; 13385see @ref{Completion, ,Command Completion}. 13386 13387@cindex reference declarations 13388@item 13389@value{GDBN} understands variables declared as C@t{++} references; you can use 13390them in expressions just as you do in C@t{++} source---they are automatically 13391dereferenced. 13392 13393In the parameter list shown when @value{GDBN} displays a frame, the values of 13394reference variables are not displayed (unlike other variables); this 13395avoids clutter, since references are often used for large structures. 13396The @emph{address} of a reference variable is always shown, unless 13397you have specified @samp{set print address off}. 13398 13399@item 13400@value{GDBN} supports the C@t{++} name resolution operator @code{::}---your 13401expressions can use it just as expressions in your program do. Since 13402one scope may be defined in another, you can use @code{::} repeatedly if 13403necessary, for example in an expression like 13404@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows 13405resolving name scope by reference to source files, in both C and C@t{++} 13406debugging (@pxref{Variables, ,Program Variables}). 13407 13408@item 13409@value{GDBN} performs argument-dependent lookup, following the C@t{++} 13410specification. 13411@end enumerate 13412 13413@node C Defaults 13414@subsubsection C and C@t{++} Defaults 13415 13416@cindex C and C@t{++} defaults 13417 13418If you allow @value{GDBN} to set range checking automatically, it 13419defaults to @code{off} whenever the working language changes to 13420C or C@t{++}. This happens regardless of whether you or @value{GDBN} 13421selects the working language. 13422 13423If you allow @value{GDBN} to set the language automatically, it 13424recognizes source files whose names end with @file{.c}, @file{.C}, or 13425@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of 13426these files, it sets the working language to C or C@t{++}. 13427@xref{Automatically, ,Having @value{GDBN} Infer the Source Language}, 13428for further details. 13429 13430@node C Checks 13431@subsubsection C and C@t{++} Type and Range Checks 13432 13433@cindex C and C@t{++} checks 13434 13435By default, when @value{GDBN} parses C or C@t{++} expressions, strict type 13436checking is used. However, if you turn type checking off, @value{GDBN} 13437will allow certain non-standard conversions, such as promoting integer 13438constants to pointers. 13439 13440Range checking, if turned on, is done on mathematical operations. Array 13441indices are not checked, since they are often used to index a pointer 13442that is not itself an array. 13443 13444@node Debugging C 13445@subsubsection @value{GDBN} and C 13446 13447The @code{set print union} and @code{show print union} commands apply to 13448the @code{union} type. When set to @samp{on}, any @code{union} that is 13449inside a @code{struct} or @code{class} is also printed. Otherwise, it 13450appears as @samp{@{...@}}. 13451 13452The @code{@@} operator aids in the debugging of dynamic arrays, formed 13453with pointers and a memory allocation function. @xref{Expressions, 13454,Expressions}. 13455 13456@node Debugging C Plus Plus 13457@subsubsection @value{GDBN} Features for C@t{++} 13458 13459@cindex commands for C@t{++} 13460 13461Some @value{GDBN} commands are particularly useful with C@t{++}, and some are 13462designed specifically for use with C@t{++}. Here is a summary: 13463 13464@table @code 13465@cindex break in overloaded functions 13466@item @r{breakpoint menus} 13467When you want a breakpoint in a function whose name is overloaded, 13468@value{GDBN} has the capability to display a menu of possible breakpoint 13469locations to help you specify which function definition you want. 13470@xref{Ambiguous Expressions,,Ambiguous Expressions}. 13471 13472@cindex overloading in C@t{++} 13473@item rbreak @var{regex} 13474Setting breakpoints using regular expressions is helpful for setting 13475breakpoints on overloaded functions that are not members of any special 13476classes. 13477@xref{Set Breaks, ,Setting Breakpoints}. 13478 13479@cindex C@t{++} exception handling 13480@item catch throw 13481@itemx catch catch 13482Debug C@t{++} exception handling using these commands. @xref{Set 13483Catchpoints, , Setting Catchpoints}. 13484 13485@cindex inheritance 13486@item ptype @var{typename} 13487Print inheritance relationships as well as other information for type 13488@var{typename}. 13489@xref{Symbols, ,Examining the Symbol Table}. 13490 13491@item info vtbl @var{expression}. 13492The @code{info vtbl} command can be used to display the virtual 13493method tables of the object computed by @var{expression}. This shows 13494one entry per virtual table; there may be multiple virtual tables when 13495multiple inheritance is in use. 13496 13497@cindex C@t{++} symbol display 13498@item set print demangle 13499@itemx show print demangle 13500@itemx set print asm-demangle 13501@itemx show print asm-demangle 13502Control whether C@t{++} symbols display in their source form, both when 13503displaying code as C@t{++} source and when displaying disassemblies. 13504@xref{Print Settings, ,Print Settings}. 13505 13506@item set print object 13507@itemx show print object 13508Choose whether to print derived (actual) or declared types of objects. 13509@xref{Print Settings, ,Print Settings}. 13510 13511@item set print vtbl 13512@itemx show print vtbl 13513Control the format for printing virtual function tables. 13514@xref{Print Settings, ,Print Settings}. 13515(The @code{vtbl} commands do not work on programs compiled with the HP 13516ANSI C@t{++} compiler (@code{aCC}).) 13517 13518@kindex set overload-resolution 13519@cindex overloaded functions, overload resolution 13520@item set overload-resolution on 13521Enable overload resolution for C@t{++} expression evaluation. The default 13522is on. For overloaded functions, @value{GDBN} evaluates the arguments 13523and searches for a function whose signature matches the argument types, 13524using the standard C@t{++} conversion rules (see @ref{C Plus Plus 13525Expressions, ,C@t{++} Expressions}, for details). 13526If it cannot find a match, it emits a message. 13527 13528@item set overload-resolution off 13529Disable overload resolution for C@t{++} expression evaluation. For 13530overloaded functions that are not class member functions, @value{GDBN} 13531chooses the first function of the specified name that it finds in the 13532symbol table, whether or not its arguments are of the correct type. For 13533overloaded functions that are class member functions, @value{GDBN} 13534searches for a function whose signature @emph{exactly} matches the 13535argument types. 13536 13537@kindex show overload-resolution 13538@item show overload-resolution 13539Show the current setting of overload resolution. 13540 13541@item @r{Overloaded symbol names} 13542You can specify a particular definition of an overloaded symbol, using 13543the same notation that is used to declare such symbols in C@t{++}: type 13544@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can 13545also use the @value{GDBN} command-line word completion facilities to list the 13546available choices, or to finish the type list for you. 13547@xref{Completion,, Command Completion}, for details on how to do this. 13548@end table 13549 13550@node Decimal Floating Point 13551@subsubsection Decimal Floating Point format 13552@cindex decimal floating point format 13553 13554@value{GDBN} can examine, set and perform computations with numbers in 13555decimal floating point format, which in the C language correspond to the 13556@code{_Decimal32}, @code{_Decimal64} and @code{_Decimal128} types as 13557specified by the extension to support decimal floating-point arithmetic. 13558 13559There are two encodings in use, depending on the architecture: BID (Binary 13560Integer Decimal) for x86 and x86-64, and DPD (Densely Packed Decimal) for 13561PowerPC. @value{GDBN} will use the appropriate encoding for the configured 13562target. 13563 13564Because of a limitation in @file{libdecnumber}, the library used by @value{GDBN} 13565to manipulate decimal floating point numbers, it is not possible to convert 13566(using a cast, for example) integers wider than 32-bit to decimal float. 13567 13568In addition, in order to imitate @value{GDBN}'s behaviour with binary floating 13569point computations, error checking in decimal float operations ignores 13570underflow, overflow and divide by zero exceptions. 13571 13572In the PowerPC architecture, @value{GDBN} provides a set of pseudo-registers 13573to inspect @code{_Decimal128} values stored in floating point registers. 13574See @ref{PowerPC,,PowerPC} for more details. 13575 13576@node D 13577@subsection D 13578 13579@cindex D 13580@value{GDBN} can be used to debug programs written in D and compiled with 13581GDC, LDC or DMD compilers. Currently @value{GDBN} supports only one D 13582specific feature --- dynamic arrays. 13583 13584@node Go 13585@subsection Go 13586 13587@cindex Go (programming language) 13588@value{GDBN} can be used to debug programs written in Go and compiled with 13589@file{gccgo} or @file{6g} compilers. 13590 13591Here is a summary of the Go-specific features and restrictions: 13592 13593@table @code 13594@cindex current Go package 13595@item The current Go package 13596The name of the current package does not need to be specified when 13597specifying global variables and functions. 13598 13599For example, given the program: 13600 13601@example 13602package main 13603var myglob = "Shall we?" 13604func main () @{ 13605 // ... 13606@} 13607@end example 13608 13609When stopped inside @code{main} either of these work: 13610 13611@example 13612(gdb) p myglob 13613(gdb) p main.myglob 13614@end example 13615 13616@cindex builtin Go types 13617@item Builtin Go types 13618The @code{string} type is recognized by @value{GDBN} and is printed 13619as a string. 13620 13621@cindex builtin Go functions 13622@item Builtin Go functions 13623The @value{GDBN} expression parser recognizes the @code{unsafe.Sizeof} 13624function and handles it internally. 13625 13626@cindex restrictions on Go expressions 13627@item Restrictions on Go expressions 13628All Go operators are supported except @code{&^}. 13629The Go @code{_} ``blank identifier'' is not supported. 13630Automatic dereferencing of pointers is not supported. 13631@end table 13632 13633@node Objective-C 13634@subsection Objective-C 13635 13636@cindex Objective-C 13637This section provides information about some commands and command 13638options that are useful for debugging Objective-C code. See also 13639@ref{Symbols, info classes}, and @ref{Symbols, info selectors}, for a 13640few more commands specific to Objective-C support. 13641 13642@menu 13643* Method Names in Commands:: 13644* The Print Command with Objective-C:: 13645@end menu 13646 13647@node Method Names in Commands 13648@subsubsection Method Names in Commands 13649 13650The following commands have been extended to accept Objective-C method 13651names as line specifications: 13652 13653@kindex clear@r{, and Objective-C} 13654@kindex break@r{, and Objective-C} 13655@kindex info line@r{, and Objective-C} 13656@kindex jump@r{, and Objective-C} 13657@kindex list@r{, and Objective-C} 13658@itemize 13659@item @code{clear} 13660@item @code{break} 13661@item @code{info line} 13662@item @code{jump} 13663@item @code{list} 13664@end itemize 13665 13666A fully qualified Objective-C method name is specified as 13667 13668@smallexample 13669-[@var{Class} @var{methodName}] 13670@end smallexample 13671 13672where the minus sign is used to indicate an instance method and a 13673plus sign (not shown) is used to indicate a class method. The class 13674name @var{Class} and method name @var{methodName} are enclosed in 13675brackets, similar to the way messages are specified in Objective-C 13676source code. For example, to set a breakpoint at the @code{create} 13677instance method of class @code{Fruit} in the program currently being 13678debugged, enter: 13679 13680@smallexample 13681break -[Fruit create] 13682@end smallexample 13683 13684To list ten program lines around the @code{initialize} class method, 13685enter: 13686 13687@smallexample 13688list +[NSText initialize] 13689@end smallexample 13690 13691In the current version of @value{GDBN}, the plus or minus sign is 13692required. In future versions of @value{GDBN}, the plus or minus 13693sign will be optional, but you can use it to narrow the search. It 13694is also possible to specify just a method name: 13695 13696@smallexample 13697break create 13698@end smallexample 13699 13700You must specify the complete method name, including any colons. If 13701your program's source files contain more than one @code{create} method, 13702you'll be presented with a numbered list of classes that implement that 13703method. Indicate your choice by number, or type @samp{0} to exit if 13704none apply. 13705 13706As another example, to clear a breakpoint established at the 13707@code{makeKeyAndOrderFront:} method of the @code{NSWindow} class, enter: 13708 13709@smallexample 13710clear -[NSWindow makeKeyAndOrderFront:] 13711@end smallexample 13712 13713@node The Print Command with Objective-C 13714@subsubsection The Print Command With Objective-C 13715@cindex Objective-C, print objects 13716@kindex print-object 13717@kindex po @r{(@code{print-object})} 13718 13719The print command has also been extended to accept methods. For example: 13720 13721@smallexample 13722print -[@var{object} hash] 13723@end smallexample 13724 13725@cindex print an Objective-C object description 13726@cindex @code{_NSPrintForDebugger}, and printing Objective-C objects 13727@noindent 13728will tell @value{GDBN} to send the @code{hash} message to @var{object} 13729and print the result. Also, an additional command has been added, 13730@code{print-object} or @code{po} for short, which is meant to print 13731the description of an object. However, this command may only work 13732with certain Objective-C libraries that have a particular hook 13733function, @code{_NSPrintForDebugger}, defined. 13734 13735@node OpenCL C 13736@subsection OpenCL C 13737 13738@cindex OpenCL C 13739This section provides information about @value{GDBN}s OpenCL C support. 13740 13741@menu 13742* OpenCL C Datatypes:: 13743* OpenCL C Expressions:: 13744* OpenCL C Operators:: 13745@end menu 13746 13747@node OpenCL C Datatypes 13748@subsubsection OpenCL C Datatypes 13749 13750@cindex OpenCL C Datatypes 13751@value{GDBN} supports the builtin scalar and vector datatypes specified 13752by OpenCL 1.1. In addition the half- and double-precision floating point 13753data types of the @code{cl_khr_fp16} and @code{cl_khr_fp64} OpenCL 13754extensions are also known to @value{GDBN}. 13755 13756@node OpenCL C Expressions 13757@subsubsection OpenCL C Expressions 13758 13759@cindex OpenCL C Expressions 13760@value{GDBN} supports accesses to vector components including the access as 13761lvalue where possible. Since OpenCL C is based on C99 most C expressions 13762supported by @value{GDBN} can be used as well. 13763 13764@node OpenCL C Operators 13765@subsubsection OpenCL C Operators 13766 13767@cindex OpenCL C Operators 13768@value{GDBN} supports the operators specified by OpenCL 1.1 for scalar and 13769vector data types. 13770 13771@node Fortran 13772@subsection Fortran 13773@cindex Fortran-specific support in @value{GDBN} 13774 13775@value{GDBN} can be used to debug programs written in Fortran, but it 13776currently supports only the features of Fortran 77 language. 13777 13778@cindex trailing underscore, in Fortran symbols 13779Some Fortran compilers (@sc{gnu} Fortran 77 and Fortran 95 compilers 13780among them) append an underscore to the names of variables and 13781functions. When you debug programs compiled by those compilers, you 13782will need to refer to variables and functions with a trailing 13783underscore. 13784 13785@menu 13786* Fortran Operators:: Fortran operators and expressions 13787* Fortran Defaults:: Default settings for Fortran 13788* Special Fortran Commands:: Special @value{GDBN} commands for Fortran 13789@end menu 13790 13791@node Fortran Operators 13792@subsubsection Fortran Operators and Expressions 13793 13794@cindex Fortran operators and expressions 13795 13796Operators must be defined on values of specific types. For instance, 13797@code{+} is defined on numbers, but not on characters or other non- 13798arithmetic types. Operators are often defined on groups of types. 13799 13800@table @code 13801@item ** 13802The exponentiation operator. It raises the first operand to the power 13803of the second one. 13804 13805@item : 13806The range operator. Normally used in the form of array(low:high) to 13807represent a section of array. 13808 13809@item % 13810The access component operator. Normally used to access elements in derived 13811types. Also suitable for unions. As unions aren't part of regular Fortran, 13812this can only happen when accessing a register that uses a gdbarch-defined 13813union type. 13814@end table 13815 13816@node Fortran Defaults 13817@subsubsection Fortran Defaults 13818 13819@cindex Fortran Defaults 13820 13821Fortran symbols are usually case-insensitive, so @value{GDBN} by 13822default uses case-insensitive matches for Fortran symbols. You can 13823change that with the @samp{set case-insensitive} command, see 13824@ref{Symbols}, for the details. 13825 13826@node Special Fortran Commands 13827@subsubsection Special Fortran Commands 13828 13829@cindex Special Fortran commands 13830 13831@value{GDBN} has some commands to support Fortran-specific features, 13832such as displaying common blocks. 13833 13834@table @code 13835@cindex @code{COMMON} blocks, Fortran 13836@kindex info common 13837@item info common @r{[}@var{common-name}@r{]} 13838This command prints the values contained in the Fortran @code{COMMON} 13839block whose name is @var{common-name}. With no argument, the names of 13840all @code{COMMON} blocks visible at the current program location are 13841printed. 13842@end table 13843 13844@node Pascal 13845@subsection Pascal 13846 13847@cindex Pascal support in @value{GDBN}, limitations 13848Debugging Pascal programs which use sets, subranges, file variables, or 13849nested functions does not currently work. @value{GDBN} does not support 13850entering expressions, printing values, or similar features using Pascal 13851syntax. 13852 13853The Pascal-specific command @code{set print pascal_static-members} 13854controls whether static members of Pascal objects are displayed. 13855@xref{Print Settings, pascal_static-members}. 13856 13857@node Modula-2 13858@subsection Modula-2 13859 13860@cindex Modula-2, @value{GDBN} support 13861 13862The extensions made to @value{GDBN} to support Modula-2 only support 13863output from the @sc{gnu} Modula-2 compiler (which is currently being 13864developed). Other Modula-2 compilers are not currently supported, and 13865attempting to debug executables produced by them is most likely 13866to give an error as @value{GDBN} reads in the executable's symbol 13867table. 13868 13869@cindex expressions in Modula-2 13870@menu 13871* M2 Operators:: Built-in operators 13872* Built-In Func/Proc:: Built-in functions and procedures 13873* M2 Constants:: Modula-2 constants 13874* M2 Types:: Modula-2 types 13875* M2 Defaults:: Default settings for Modula-2 13876* Deviations:: Deviations from standard Modula-2 13877* M2 Checks:: Modula-2 type and range checks 13878* M2 Scope:: The scope operators @code{::} and @code{.} 13879* GDB/M2:: @value{GDBN} and Modula-2 13880@end menu 13881 13882@node M2 Operators 13883@subsubsection Operators 13884@cindex Modula-2 operators 13885 13886Operators must be defined on values of specific types. For instance, 13887@code{+} is defined on numbers, but not on structures. Operators are 13888often defined on groups of types. For the purposes of Modula-2, the 13889following definitions hold: 13890 13891@itemize @bullet 13892 13893@item 13894@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and 13895their subranges. 13896 13897@item 13898@emph{Character types} consist of @code{CHAR} and its subranges. 13899 13900@item 13901@emph{Floating-point types} consist of @code{REAL}. 13902 13903@item 13904@emph{Pointer types} consist of anything declared as @code{POINTER TO 13905@var{type}}. 13906 13907@item 13908@emph{Scalar types} consist of all of the above. 13909 13910@item 13911@emph{Set types} consist of @code{SET} and @code{BITSET} types. 13912 13913@item 13914@emph{Boolean types} consist of @code{BOOLEAN}. 13915@end itemize 13916 13917@noindent 13918The following operators are supported, and appear in order of 13919increasing precedence: 13920 13921@table @code 13922@item , 13923Function argument or array index separator. 13924 13925@item := 13926Assignment. The value of @var{var} @code{:=} @var{value} is 13927@var{value}. 13928 13929@item <@r{, }> 13930Less than, greater than on integral, floating-point, or enumerated 13931types. 13932 13933@item <=@r{, }>= 13934Less than or equal to, greater than or equal to 13935on integral, floating-point and enumerated types, or set inclusion on 13936set types. Same precedence as @code{<}. 13937 13938@item =@r{, }<>@r{, }# 13939Equality and two ways of expressing inequality, valid on scalar types. 13940Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is 13941available for inequality, since @code{#} conflicts with the script 13942comment character. 13943 13944@item IN 13945Set membership. Defined on set types and the types of their members. 13946Same precedence as @code{<}. 13947 13948@item OR 13949Boolean disjunction. Defined on boolean types. 13950 13951@item AND@r{, }& 13952Boolean conjunction. Defined on boolean types. 13953 13954@item @@ 13955The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}). 13956 13957@item +@r{, }- 13958Addition and subtraction on integral and floating-point types, or union 13959and difference on set types. 13960 13961@item * 13962Multiplication on integral and floating-point types, or set intersection 13963on set types. 13964 13965@item / 13966Division on floating-point types, or symmetric set difference on set 13967types. Same precedence as @code{*}. 13968 13969@item DIV@r{, }MOD 13970Integer division and remainder. Defined on integral types. Same 13971precedence as @code{*}. 13972 13973@item - 13974Negative. Defined on @code{INTEGER} and @code{REAL} data. 13975 13976@item ^ 13977Pointer dereferencing. Defined on pointer types. 13978 13979@item NOT 13980Boolean negation. Defined on boolean types. Same precedence as 13981@code{^}. 13982 13983@item . 13984@code{RECORD} field selector. Defined on @code{RECORD} data. Same 13985precedence as @code{^}. 13986 13987@item [] 13988Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}. 13989 13990@item () 13991Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence 13992as @code{^}. 13993 13994@item ::@r{, }. 13995@value{GDBN} and Modula-2 scope operators. 13996@end table 13997 13998@quotation 13999@emph{Warning:} Set expressions and their operations are not yet supported, so @value{GDBN} 14000treats the use of the operator @code{IN}, or the use of operators 14001@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#}, 14002@code{<=}, and @code{>=} on sets as an error. 14003@end quotation 14004 14005 14006@node Built-In Func/Proc 14007@subsubsection Built-in Functions and Procedures 14008@cindex Modula-2 built-ins 14009 14010Modula-2 also makes available several built-in procedures and functions. 14011In describing these, the following metavariables are used: 14012 14013@table @var 14014 14015@item a 14016represents an @code{ARRAY} variable. 14017 14018@item c 14019represents a @code{CHAR} constant or variable. 14020 14021@item i 14022represents a variable or constant of integral type. 14023 14024@item m 14025represents an identifier that belongs to a set. Generally used in the 14026same function with the metavariable @var{s}. The type of @var{s} should 14027be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}). 14028 14029@item n 14030represents a variable or constant of integral or floating-point type. 14031 14032@item r 14033represents a variable or constant of floating-point type. 14034 14035@item t 14036represents a type. 14037 14038@item v 14039represents a variable. 14040 14041@item x 14042represents a variable or constant of one of many types. See the 14043explanation of the function for details. 14044@end table 14045 14046All Modula-2 built-in procedures also return a result, described below. 14047 14048@table @code 14049@item ABS(@var{n}) 14050Returns the absolute value of @var{n}. 14051 14052@item CAP(@var{c}) 14053If @var{c} is a lower case letter, it returns its upper case 14054equivalent, otherwise it returns its argument. 14055 14056@item CHR(@var{i}) 14057Returns the character whose ordinal value is @var{i}. 14058 14059@item DEC(@var{v}) 14060Decrements the value in the variable @var{v} by one. Returns the new value. 14061 14062@item DEC(@var{v},@var{i}) 14063Decrements the value in the variable @var{v} by @var{i}. Returns the 14064new value. 14065 14066@item EXCL(@var{m},@var{s}) 14067Removes the element @var{m} from the set @var{s}. Returns the new 14068set. 14069 14070@item FLOAT(@var{i}) 14071Returns the floating point equivalent of the integer @var{i}. 14072 14073@item HIGH(@var{a}) 14074Returns the index of the last member of @var{a}. 14075 14076@item INC(@var{v}) 14077Increments the value in the variable @var{v} by one. Returns the new value. 14078 14079@item INC(@var{v},@var{i}) 14080Increments the value in the variable @var{v} by @var{i}. Returns the 14081new value. 14082 14083@item INCL(@var{m},@var{s}) 14084Adds the element @var{m} to the set @var{s} if it is not already 14085there. Returns the new set. 14086 14087@item MAX(@var{t}) 14088Returns the maximum value of the type @var{t}. 14089 14090@item MIN(@var{t}) 14091Returns the minimum value of the type @var{t}. 14092 14093@item ODD(@var{i}) 14094Returns boolean TRUE if @var{i} is an odd number. 14095 14096@item ORD(@var{x}) 14097Returns the ordinal value of its argument. For example, the ordinal 14098value of a character is its @sc{ascii} value (on machines supporting the 14099@sc{ascii} character set). @var{x} must be of an ordered type, which include 14100integral, character and enumerated types. 14101 14102@item SIZE(@var{x}) 14103Returns the size of its argument. @var{x} can be a variable or a type. 14104 14105@item TRUNC(@var{r}) 14106Returns the integral part of @var{r}. 14107 14108@item TSIZE(@var{x}) 14109Returns the size of its argument. @var{x} can be a variable or a type. 14110 14111@item VAL(@var{t},@var{i}) 14112Returns the member of the type @var{t} whose ordinal value is @var{i}. 14113@end table 14114 14115@quotation 14116@emph{Warning:} Sets and their operations are not yet supported, so 14117@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as 14118an error. 14119@end quotation 14120 14121@cindex Modula-2 constants 14122@node M2 Constants 14123@subsubsection Constants 14124 14125@value{GDBN} allows you to express the constants of Modula-2 in the following 14126ways: 14127 14128@itemize @bullet 14129 14130@item 14131Integer constants are simply a sequence of digits. When used in an 14132expression, a constant is interpreted to be type-compatible with the 14133rest of the expression. Hexadecimal integers are specified by a 14134trailing @samp{H}, and octal integers by a trailing @samp{B}. 14135 14136@item 14137Floating point constants appear as a sequence of digits, followed by a 14138decimal point and another sequence of digits. An optional exponent can 14139then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where 14140@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the 14141digits of the floating point constant must be valid decimal (base 10) 14142digits. 14143 14144@item 14145Character constants consist of a single character enclosed by a pair of 14146like quotes, either single (@code{'}) or double (@code{"}). They may 14147also be expressed by their ordinal value (their @sc{ascii} value, usually) 14148followed by a @samp{C}. 14149 14150@item 14151String constants consist of a sequence of characters enclosed by a 14152pair of like quotes, either single (@code{'}) or double (@code{"}). 14153Escape sequences in the style of C are also allowed. @xref{C 14154Constants, ,C and C@t{++} Constants}, for a brief explanation of escape 14155sequences. 14156 14157@item 14158Enumerated constants consist of an enumerated identifier. 14159 14160@item 14161Boolean constants consist of the identifiers @code{TRUE} and 14162@code{FALSE}. 14163 14164@item 14165Pointer constants consist of integral values only. 14166 14167@item 14168Set constants are not yet supported. 14169@end itemize 14170 14171@node M2 Types 14172@subsubsection Modula-2 Types 14173@cindex Modula-2 types 14174 14175Currently @value{GDBN} can print the following data types in Modula-2 14176syntax: array types, record types, set types, pointer types, procedure 14177types, enumerated types, subrange types and base types. You can also 14178print the contents of variables declared using these type. 14179This section gives a number of simple source code examples together with 14180sample @value{GDBN} sessions. 14181 14182The first example contains the following section of code: 14183 14184@smallexample 14185VAR 14186 s: SET OF CHAR ; 14187 r: [20..40] ; 14188@end smallexample 14189 14190@noindent 14191and you can request @value{GDBN} to interrogate the type and value of 14192@code{r} and @code{s}. 14193 14194@smallexample 14195(@value{GDBP}) print s 14196@{'A'..'C', 'Z'@} 14197(@value{GDBP}) ptype s 14198SET OF CHAR 14199(@value{GDBP}) print r 1420021 14201(@value{GDBP}) ptype r 14202[20..40] 14203@end smallexample 14204 14205@noindent 14206Likewise if your source code declares @code{s} as: 14207 14208@smallexample 14209VAR 14210 s: SET ['A'..'Z'] ; 14211@end smallexample 14212 14213@noindent 14214then you may query the type of @code{s} by: 14215 14216@smallexample 14217(@value{GDBP}) ptype s 14218type = SET ['A'..'Z'] 14219@end smallexample 14220 14221@noindent 14222Note that at present you cannot interactively manipulate set 14223expressions using the debugger. 14224 14225The following example shows how you might declare an array in Modula-2 14226and how you can interact with @value{GDBN} to print its type and contents: 14227 14228@smallexample 14229VAR 14230 s: ARRAY [-10..10] OF CHAR ; 14231@end smallexample 14232 14233@smallexample 14234(@value{GDBP}) ptype s 14235ARRAY [-10..10] OF CHAR 14236@end smallexample 14237 14238Note that the array handling is not yet complete and although the type 14239is printed correctly, expression handling still assumes that all 14240arrays have a lower bound of zero and not @code{-10} as in the example 14241above. 14242 14243Here are some more type related Modula-2 examples: 14244 14245@smallexample 14246TYPE 14247 colour = (blue, red, yellow, green) ; 14248 t = [blue..yellow] ; 14249VAR 14250 s: t ; 14251BEGIN 14252 s := blue ; 14253@end smallexample 14254 14255@noindent 14256The @value{GDBN} interaction shows how you can query the data type 14257and value of a variable. 14258 14259@smallexample 14260(@value{GDBP}) print s 14261$1 = blue 14262(@value{GDBP}) ptype t 14263type = [blue..yellow] 14264@end smallexample 14265 14266@noindent 14267In this example a Modula-2 array is declared and its contents 14268displayed. Observe that the contents are written in the same way as 14269their @code{C} counterparts. 14270 14271@smallexample 14272VAR 14273 s: ARRAY [1..5] OF CARDINAL ; 14274BEGIN 14275 s[1] := 1 ; 14276@end smallexample 14277 14278@smallexample 14279(@value{GDBP}) print s 14280$1 = @{1, 0, 0, 0, 0@} 14281(@value{GDBP}) ptype s 14282type = ARRAY [1..5] OF CARDINAL 14283@end smallexample 14284 14285The Modula-2 language interface to @value{GDBN} also understands 14286pointer types as shown in this example: 14287 14288@smallexample 14289VAR 14290 s: POINTER TO ARRAY [1..5] OF CARDINAL ; 14291BEGIN 14292 NEW(s) ; 14293 s^[1] := 1 ; 14294@end smallexample 14295 14296@noindent 14297and you can request that @value{GDBN} describes the type of @code{s}. 14298 14299@smallexample 14300(@value{GDBP}) ptype s 14301type = POINTER TO ARRAY [1..5] OF CARDINAL 14302@end smallexample 14303 14304@value{GDBN} handles compound types as we can see in this example. 14305Here we combine array types, record types, pointer types and subrange 14306types: 14307 14308@smallexample 14309TYPE 14310 foo = RECORD 14311 f1: CARDINAL ; 14312 f2: CHAR ; 14313 f3: myarray ; 14314 END ; 14315 14316 myarray = ARRAY myrange OF CARDINAL ; 14317 myrange = [-2..2] ; 14318VAR 14319 s: POINTER TO ARRAY myrange OF foo ; 14320@end smallexample 14321 14322@noindent 14323and you can ask @value{GDBN} to describe the type of @code{s} as shown 14324below. 14325 14326@smallexample 14327(@value{GDBP}) ptype s 14328type = POINTER TO ARRAY [-2..2] OF foo = RECORD 14329 f1 : CARDINAL; 14330 f2 : CHAR; 14331 f3 : ARRAY [-2..2] OF CARDINAL; 14332END 14333@end smallexample 14334 14335@node M2 Defaults 14336@subsubsection Modula-2 Defaults 14337@cindex Modula-2 defaults 14338 14339If type and range checking are set automatically by @value{GDBN}, they 14340both default to @code{on} whenever the working language changes to 14341Modula-2. This happens regardless of whether you or @value{GDBN} 14342selected the working language. 14343 14344If you allow @value{GDBN} to set the language automatically, then entering 14345code compiled from a file whose name ends with @file{.mod} sets the 14346working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} 14347Infer the Source Language}, for further details. 14348 14349@node Deviations 14350@subsubsection Deviations from Standard Modula-2 14351@cindex Modula-2, deviations from 14352 14353A few changes have been made to make Modula-2 programs easier to debug. 14354This is done primarily via loosening its type strictness: 14355 14356@itemize @bullet 14357@item 14358Unlike in standard Modula-2, pointer constants can be formed by 14359integers. This allows you to modify pointer variables during 14360debugging. (In standard Modula-2, the actual address contained in a 14361pointer variable is hidden from you; it can only be modified 14362through direct assignment to another pointer variable or expression that 14363returned a pointer.) 14364 14365@item 14366C escape sequences can be used in strings and characters to represent 14367non-printable characters. @value{GDBN} prints out strings with these 14368escape sequences embedded. Single non-printable characters are 14369printed using the @samp{CHR(@var{nnn})} format. 14370 14371@item 14372The assignment operator (@code{:=}) returns the value of its right-hand 14373argument. 14374 14375@item 14376All built-in procedures both modify @emph{and} return their argument. 14377@end itemize 14378 14379@node M2 Checks 14380@subsubsection Modula-2 Type and Range Checks 14381@cindex Modula-2 checks 14382 14383@quotation 14384@emph{Warning:} in this release, @value{GDBN} does not yet perform type or 14385range checking. 14386@end quotation 14387@c FIXME remove warning when type/range checks added 14388 14389@value{GDBN} considers two Modula-2 variables type equivalent if: 14390 14391@itemize @bullet 14392@item 14393They are of types that have been declared equivalent via a @code{TYPE 14394@var{t1} = @var{t2}} statement 14395 14396@item 14397They have been declared on the same line. (Note: This is true of the 14398@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.) 14399@end itemize 14400 14401As long as type checking is enabled, any attempt to combine variables 14402whose types are not equivalent is an error. 14403 14404Range checking is done on all mathematical operations, assignment, array 14405index bounds, and all built-in functions and procedures. 14406 14407@node M2 Scope 14408@subsubsection The Scope Operators @code{::} and @code{.} 14409@cindex scope 14410@cindex @code{.}, Modula-2 scope operator 14411@cindex colon, doubled as scope operator 14412@ifinfo 14413@vindex colon-colon@r{, in Modula-2} 14414@c Info cannot handle :: but TeX can. 14415@end ifinfo 14416@ifnotinfo 14417@vindex ::@r{, in Modula-2} 14418@end ifnotinfo 14419 14420There are a few subtle differences between the Modula-2 scope operator 14421(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have 14422similar syntax: 14423 14424@smallexample 14425 14426@var{module} . @var{id} 14427@var{scope} :: @var{id} 14428@end smallexample 14429 14430@noindent 14431where @var{scope} is the name of a module or a procedure, 14432@var{module} the name of a module, and @var{id} is any declared 14433identifier within your program, except another module. 14434 14435Using the @code{::} operator makes @value{GDBN} search the scope 14436specified by @var{scope} for the identifier @var{id}. If it is not 14437found in the specified scope, then @value{GDBN} searches all scopes 14438enclosing the one specified by @var{scope}. 14439 14440Using the @code{.} operator makes @value{GDBN} search the current scope for 14441the identifier specified by @var{id} that was imported from the 14442definition module specified by @var{module}. With this operator, it is 14443an error if the identifier @var{id} was not imported from definition 14444module @var{module}, or if @var{id} is not an identifier in 14445@var{module}. 14446 14447@node GDB/M2 14448@subsubsection @value{GDBN} and Modula-2 14449 14450Some @value{GDBN} commands have little use when debugging Modula-2 programs. 14451Five subcommands of @code{set print} and @code{show print} apply 14452specifically to C and C@t{++}: @samp{vtbl}, @samp{demangle}, 14453@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four 14454apply to C@t{++}, and the last to the C @code{union} type, which has no direct 14455analogue in Modula-2. 14456 14457The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available 14458with any language, is not useful with Modula-2. Its 14459intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be 14460created in Modula-2 as they can in C or C@t{++}. However, because an 14461address can be specified by an integral constant, the construct 14462@samp{@{@var{type}@}@var{adrexp}} is still useful. 14463 14464@cindex @code{#} in Modula-2 14465In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is 14466interpreted as the beginning of a comment. Use @code{<>} instead. 14467 14468@node Ada 14469@subsection Ada 14470@cindex Ada 14471 14472The extensions made to @value{GDBN} for Ada only support 14473output from the @sc{gnu} Ada (GNAT) compiler. 14474Other Ada compilers are not currently supported, and 14475attempting to debug executables produced by them is most likely 14476to be difficult. 14477 14478 14479@cindex expressions in Ada 14480@menu 14481* Ada Mode Intro:: General remarks on the Ada syntax 14482 and semantics supported by Ada mode 14483 in @value{GDBN}. 14484* Omissions from Ada:: Restrictions on the Ada expression syntax. 14485* Additions to Ada:: Extensions of the Ada expression syntax. 14486* Stopping Before Main Program:: Debugging the program during elaboration. 14487* Ada Tasks:: Listing and setting breakpoints in tasks. 14488* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files 14489* Ravenscar Profile:: Tasking Support when using the Ravenscar 14490 Profile 14491* Ada Glitches:: Known peculiarities of Ada mode. 14492@end menu 14493 14494@node Ada Mode Intro 14495@subsubsection Introduction 14496@cindex Ada mode, general 14497 14498The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression 14499syntax, with some extensions. 14500The philosophy behind the design of this subset is 14501 14502@itemize @bullet 14503@item 14504That @value{GDBN} should provide basic literals and access to operations for 14505arithmetic, dereferencing, field selection, indexing, and subprogram calls, 14506leaving more sophisticated computations to subprograms written into the 14507program (which therefore may be called from @value{GDBN}). 14508 14509@item 14510That type safety and strict adherence to Ada language restrictions 14511are not particularly important to the @value{GDBN} user. 14512 14513@item 14514That brevity is important to the @value{GDBN} user. 14515@end itemize 14516 14517Thus, for brevity, the debugger acts as if all names declared in 14518user-written packages are directly visible, even if they are not visible 14519according to Ada rules, thus making it unnecessary to fully qualify most 14520names with their packages, regardless of context. Where this causes 14521ambiguity, @value{GDBN} asks the user's intent. 14522 14523The debugger will start in Ada mode if it detects an Ada main program. 14524As for other languages, it will enter Ada mode when stopped in a program that 14525was translated from an Ada source file. 14526 14527While in Ada mode, you may use `@t{--}' for comments. This is useful 14528mostly for documenting command files. The standard @value{GDBN} comment 14529(@samp{#}) still works at the beginning of a line in Ada mode, but not in the 14530middle (to allow based literals). 14531 14532The debugger supports limited overloading. Given a subprogram call in which 14533the function symbol has multiple definitions, it will use the number of 14534actual parameters and some information about their types to attempt to narrow 14535the set of definitions. It also makes very limited use of context, preferring 14536procedures to functions in the context of the @code{call} command, and 14537functions to procedures elsewhere. 14538 14539@node Omissions from Ada 14540@subsubsection Omissions from Ada 14541@cindex Ada, omissions from 14542 14543Here are the notable omissions from the subset: 14544 14545@itemize @bullet 14546@item 14547Only a subset of the attributes are supported: 14548 14549@itemize @minus 14550@item 14551@t{'First}, @t{'Last}, and @t{'Length} 14552 on array objects (not on types and subtypes). 14553 14554@item 14555@t{'Min} and @t{'Max}. 14556 14557@item 14558@t{'Pos} and @t{'Val}. 14559 14560@item 14561@t{'Tag}. 14562 14563@item 14564@t{'Range} on array objects (not subtypes), but only as the right 14565operand of the membership (@code{in}) operator. 14566 14567@item 14568@t{'Access}, @t{'Unchecked_Access}, and 14569@t{'Unrestricted_Access} (a GNAT extension). 14570 14571@item 14572@t{'Address}. 14573@end itemize 14574 14575@item 14576The names in 14577@code{Characters.Latin_1} are not available and 14578concatenation is not implemented. Thus, escape characters in strings are 14579not currently available. 14580 14581@item 14582Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise 14583equality of representations. They will generally work correctly 14584for strings and arrays whose elements have integer or enumeration types. 14585They may not work correctly for arrays whose element 14586types have user-defined equality, for arrays of real values 14587(in particular, IEEE-conformant floating point, because of negative 14588zeroes and NaNs), and for arrays whose elements contain unused bits with 14589indeterminate values. 14590 14591@item 14592The other component-by-component array operations (@code{and}, @code{or}, 14593@code{xor}, @code{not}, and relational tests other than equality) 14594are not implemented. 14595 14596@item 14597@cindex array aggregates (Ada) 14598@cindex record aggregates (Ada) 14599@cindex aggregates (Ada) 14600There is limited support for array and record aggregates. They are 14601permitted only on the right sides of assignments, as in these examples: 14602 14603@smallexample 14604(@value{GDBP}) set An_Array := (1, 2, 3, 4, 5, 6) 14605(@value{GDBP}) set An_Array := (1, others => 0) 14606(@value{GDBP}) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) 14607(@value{GDBP}) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) 14608(@value{GDBP}) set A_Record := (1, "Peter", True); 14609(@value{GDBP}) set A_Record := (Name => "Peter", Id => 1, Alive => True) 14610@end smallexample 14611 14612Changing a 14613discriminant's value by assigning an aggregate has an 14614undefined effect if that discriminant is used within the record. 14615However, you can first modify discriminants by directly assigning to 14616them (which normally would not be allowed in Ada), and then performing an 14617aggregate assignment. For example, given a variable @code{A_Rec} 14618declared to have a type such as: 14619 14620@smallexample 14621type Rec (Len : Small_Integer := 0) is record 14622 Id : Integer; 14623 Vals : IntArray (1 .. Len); 14624end record; 14625@end smallexample 14626 14627you can assign a value with a different size of @code{Vals} with two 14628assignments: 14629 14630@smallexample 14631(@value{GDBP}) set A_Rec.Len := 4 14632(@value{GDBP}) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) 14633@end smallexample 14634 14635As this example also illustrates, @value{GDBN} is very loose about the usual 14636rules concerning aggregates. You may leave out some of the 14637components of an array or record aggregate (such as the @code{Len} 14638component in the assignment to @code{A_Rec} above); they will retain their 14639original values upon assignment. You may freely use dynamic values as 14640indices in component associations. You may even use overlapping or 14641redundant component associations, although which component values are 14642assigned in such cases is not defined. 14643 14644@item 14645Calls to dispatching subprograms are not implemented. 14646 14647@item 14648The overloading algorithm is much more limited (i.e., less selective) 14649than that of real Ada. It makes only limited use of the context in 14650which a subexpression appears to resolve its meaning, and it is much 14651looser in its rules for allowing type matches. As a result, some 14652function calls will be ambiguous, and the user will be asked to choose 14653the proper resolution. 14654 14655@item 14656The @code{new} operator is not implemented. 14657 14658@item 14659Entry calls are not implemented. 14660 14661@item 14662Aside from printing, arithmetic operations on the native VAX floating-point 14663formats are not supported. 14664 14665@item 14666It is not possible to slice a packed array. 14667 14668@item 14669The names @code{True} and @code{False}, when not part of a qualified name, 14670are interpreted as if implicitly prefixed by @code{Standard}, regardless of 14671context. 14672Should your program 14673redefine these names in a package or procedure (at best a dubious practice), 14674you will have to use fully qualified names to access their new definitions. 14675@end itemize 14676 14677@node Additions to Ada 14678@subsubsection Additions to Ada 14679@cindex Ada, deviations from 14680 14681As it does for other languages, @value{GDBN} makes certain generic 14682extensions to Ada (@pxref{Expressions}): 14683 14684@itemize @bullet 14685@item 14686If the expression @var{E} is a variable residing in memory (typically 14687a local variable or array element) and @var{N} is a positive integer, 14688then @code{@var{E}@@@var{N}} displays the values of @var{E} and the 14689@var{N}-1 adjacent variables following it in memory as an array. In 14690Ada, this operator is generally not necessary, since its prime use is 14691in displaying parts of an array, and slicing will usually do this in 14692Ada. However, there are occasional uses when debugging programs in 14693which certain debugging information has been optimized away. 14694 14695@item 14696@code{@var{B}::@var{var}} means ``the variable named @var{var} that 14697appears in function or file @var{B}.'' When @var{B} is a file name, 14698you must typically surround it in single quotes. 14699 14700@item 14701The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type 14702@var{type} that appears at address @var{addr}.'' 14703 14704@item 14705A name starting with @samp{$} is a convenience variable 14706(@pxref{Convenience Vars}) or a machine register (@pxref{Registers}). 14707@end itemize 14708 14709In addition, @value{GDBN} provides a few other shortcuts and outright 14710additions specific to Ada: 14711 14712@itemize @bullet 14713@item 14714The assignment statement is allowed as an expression, returning 14715its right-hand operand as its value. Thus, you may enter 14716 14717@smallexample 14718(@value{GDBP}) set x := y + 3 14719(@value{GDBP}) print A(tmp := y + 1) 14720@end smallexample 14721 14722@item 14723The semicolon is allowed as an ``operator,'' returning as its value 14724the value of its right-hand operand. 14725This allows, for example, 14726complex conditional breaks: 14727 14728@smallexample 14729(@value{GDBP}) break f 14730(@value{GDBP}) condition 1 (report(i); k += 1; A(k) > 100) 14731@end smallexample 14732 14733@item 14734Rather than use catenation and symbolic character names to introduce special 14735characters into strings, one may instead use a special bracket notation, 14736which is also used to print strings. A sequence of characters of the form 14737@samp{["@var{XX}"]} within a string or character literal denotes the 14738(single) character whose numeric encoding is @var{XX} in hexadecimal. The 14739sequence of characters @samp{["""]} also denotes a single quotation mark 14740in strings. For example, 14741@smallexample 14742 "One line.["0a"]Next line.["0a"]" 14743@end smallexample 14744@noindent 14745contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF}) 14746after each period. 14747 14748@item 14749The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and 14750@t{'Max} is optional (and is ignored in any case). For example, it is valid 14751to write 14752 14753@smallexample 14754(@value{GDBP}) print 'max(x, y) 14755@end smallexample 14756 14757@item 14758When printing arrays, @value{GDBN} uses positional notation when the 14759array has a lower bound of 1, and uses a modified named notation otherwise. 14760For example, a one-dimensional array of three integers with a lower bound 14761of 3 might print as 14762 14763@smallexample 14764(3 => 10, 17, 1) 14765@end smallexample 14766 14767@noindent 14768That is, in contrast to valid Ada, only the first component has a @code{=>} 14769clause. 14770 14771@item 14772You may abbreviate attributes in expressions with any unique, 14773multi-character subsequence of 14774their names (an exact match gets preference). 14775For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh} 14776in place of @t{a'length}. 14777 14778@item 14779@cindex quoting Ada internal identifiers 14780Since Ada is case-insensitive, the debugger normally maps identifiers you type 14781to lower case. The GNAT compiler uses upper-case characters for 14782some of its internal identifiers, which are normally of no interest to users. 14783For the rare occasions when you actually have to look at them, 14784enclose them in angle brackets to avoid the lower-case mapping. 14785For example, 14786@smallexample 14787(@value{GDBP}) print <JMPBUF_SAVE>[0] 14788@end smallexample 14789 14790@item 14791Printing an object of class-wide type or dereferencing an 14792access-to-class-wide value will display all the components of the object's 14793specific type (as indicated by its run-time tag). Likewise, component 14794selection on such a value will operate on the specific type of the 14795object. 14796 14797@end itemize 14798 14799@node Stopping Before Main Program 14800@subsubsection Stopping at the Very Beginning 14801 14802@cindex breakpointing Ada elaboration code 14803It is sometimes necessary to debug the program during elaboration, and 14804before reaching the main procedure. 14805As defined in the Ada Reference 14806Manual, the elaboration code is invoked from a procedure called 14807@code{adainit}. To run your program up to the beginning of 14808elaboration, simply use the following two commands: 14809@code{tbreak adainit} and @code{run}. 14810 14811@node Ada Tasks 14812@subsubsection Extensions for Ada Tasks 14813@cindex Ada, tasking 14814 14815Support for Ada tasks is analogous to that for threads (@pxref{Threads}). 14816@value{GDBN} provides the following task-related commands: 14817 14818@table @code 14819@kindex info tasks 14820@item info tasks 14821This command shows a list of current Ada tasks, as in the following example: 14822 14823 14824@smallexample 14825@iftex 14826@leftskip=0.5cm 14827@end iftex 14828(@value{GDBP}) info tasks 14829 ID TID P-ID Pri State Name 14830 1 8088000 0 15 Child Activation Wait main_task 14831 2 80a4000 1 15 Accept Statement b 14832 3 809a800 1 15 Child Activation Wait a 14833* 4 80ae800 3 15 Runnable c 14834 14835@end smallexample 14836 14837@noindent 14838In this listing, the asterisk before the last task indicates it to be the 14839task currently being inspected. 14840 14841@table @asis 14842@item ID 14843Represents @value{GDBN}'s internal task number. 14844 14845@item TID 14846The Ada task ID. 14847 14848@item P-ID 14849The parent's task ID (@value{GDBN}'s internal task number). 14850 14851@item Pri 14852The base priority of the task. 14853 14854@item State 14855Current state of the task. 14856 14857@table @code 14858@item Unactivated 14859The task has been created but has not been activated. It cannot be 14860executing. 14861 14862@item Runnable 14863The task is not blocked for any reason known to Ada. (It may be waiting 14864for a mutex, though.) It is conceptually "executing" in normal mode. 14865 14866@item Terminated 14867The task is terminated, in the sense of ARM 9.3 (5). Any dependents 14868that were waiting on terminate alternatives have been awakened and have 14869terminated themselves. 14870 14871@item Child Activation Wait 14872The task is waiting for created tasks to complete activation. 14873 14874@item Accept Statement 14875The task is waiting on an accept or selective wait statement. 14876 14877@item Waiting on entry call 14878The task is waiting on an entry call. 14879 14880@item Async Select Wait 14881The task is waiting to start the abortable part of an asynchronous 14882select statement. 14883 14884@item Delay Sleep 14885The task is waiting on a select statement with only a delay 14886alternative open. 14887 14888@item Child Termination Wait 14889The task is sleeping having completed a master within itself, and is 14890waiting for the tasks dependent on that master to become terminated or 14891waiting on a terminate Phase. 14892 14893@item Wait Child in Term Alt 14894The task is sleeping waiting for tasks on terminate alternatives to 14895finish terminating. 14896 14897@item Accepting RV with @var{taskno} 14898The task is accepting a rendez-vous with the task @var{taskno}. 14899@end table 14900 14901@item Name 14902Name of the task in the program. 14903 14904@end table 14905 14906@kindex info task @var{taskno} 14907@item info task @var{taskno} 14908This command shows detailled informations on the specified task, as in 14909the following example: 14910@smallexample 14911@iftex 14912@leftskip=0.5cm 14913@end iftex 14914(@value{GDBP}) info tasks 14915 ID TID P-ID Pri State Name 14916 1 8077880 0 15 Child Activation Wait main_task 14917* 2 807c468 1 15 Runnable task_1 14918(@value{GDBP}) info task 2 14919Ada Task: 0x807c468 14920Name: task_1 14921Thread: 0x807f378 14922Parent: 1 (main_task) 14923Base Priority: 15 14924State: Runnable 14925@end smallexample 14926 14927@item task 14928@kindex task@r{ (Ada)} 14929@cindex current Ada task ID 14930This command prints the ID of the current task. 14931 14932@smallexample 14933@iftex 14934@leftskip=0.5cm 14935@end iftex 14936(@value{GDBP}) info tasks 14937 ID TID P-ID Pri State Name 14938 1 8077870 0 15 Child Activation Wait main_task 14939* 2 807c458 1 15 Runnable t 14940(@value{GDBP}) task 14941[Current task is 2] 14942@end smallexample 14943 14944@item task @var{taskno} 14945@cindex Ada task switching 14946This command is like the @code{thread @var{threadno}} 14947command (@pxref{Threads}). It switches the context of debugging 14948from the current task to the given task. 14949 14950@smallexample 14951@iftex 14952@leftskip=0.5cm 14953@end iftex 14954(@value{GDBP}) info tasks 14955 ID TID P-ID Pri State Name 14956 1 8077870 0 15 Child Activation Wait main_task 14957* 2 807c458 1 15 Runnable t 14958(@value{GDBP}) task 1 14959[Switching to task 1] 14960#0 0x8067726 in pthread_cond_wait () 14961(@value{GDBP}) bt 14962#0 0x8067726 in pthread_cond_wait () 14963#1 0x8056714 in system.os_interface.pthread_cond_wait () 14964#2 0x805cb63 in system.task_primitives.operations.sleep () 14965#3 0x806153e in system.tasking.stages.activate_tasks () 14966#4 0x804aacc in un () at un.adb:5 14967@end smallexample 14968 14969@item break @var{linespec} task @var{taskno} 14970@itemx break @var{linespec} task @var{taskno} if @dots{} 14971@cindex breakpoints and tasks, in Ada 14972@cindex task breakpoints, in Ada 14973@kindex break @dots{} task @var{taskno}@r{ (Ada)} 14974These commands are like the @code{break @dots{} thread @dots{}} 14975command (@pxref{Thread Stops}). 14976@var{linespec} specifies source lines, as described 14977in @ref{Specify Location}. 14978 14979Use the qualifier @samp{task @var{taskno}} with a breakpoint command 14980to specify that you only want @value{GDBN} to stop the program when a 14981particular Ada task reaches this breakpoint. @var{taskno} is one of the 14982numeric task identifiers assigned by @value{GDBN}, shown in the first 14983column of the @samp{info tasks} display. 14984 14985If you do not specify @samp{task @var{taskno}} when you set a 14986breakpoint, the breakpoint applies to @emph{all} tasks of your 14987program. 14988 14989You can use the @code{task} qualifier on conditional breakpoints as 14990well; in this case, place @samp{task @var{taskno}} before the 14991breakpoint condition (before the @code{if}). 14992 14993For example, 14994 14995@smallexample 14996@iftex 14997@leftskip=0.5cm 14998@end iftex 14999(@value{GDBP}) info tasks 15000 ID TID P-ID Pri State Name 15001 1 140022020 0 15 Child Activation Wait main_task 15002 2 140045060 1 15 Accept/Select Wait t2 15003 3 140044840 1 15 Runnable t1 15004* 4 140056040 1 15 Runnable t3 15005(@value{GDBP}) b 15 task 2 15006Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15. 15007(@value{GDBP}) cont 15008Continuing. 15009task # 1 running 15010task # 2 running 15011 15012Breakpoint 5, test_task_debug () at test_task_debug.adb:15 1501315 flush; 15014(@value{GDBP}) info tasks 15015 ID TID P-ID Pri State Name 15016 1 140022020 0 15 Child Activation Wait main_task 15017* 2 140045060 1 15 Runnable t2 15018 3 140044840 1 15 Runnable t1 15019 4 140056040 1 15 Delay Sleep t3 15020@end smallexample 15021@end table 15022 15023@node Ada Tasks and Core Files 15024@subsubsection Tasking Support when Debugging Core Files 15025@cindex Ada tasking and core file debugging 15026 15027When inspecting a core file, as opposed to debugging a live program, 15028tasking support may be limited or even unavailable, depending on 15029the platform being used. 15030For instance, on x86-linux, the list of tasks is available, but task 15031switching is not supported. On Tru64, however, task switching will work 15032as usual. 15033 15034On certain platforms, including Tru64, the debugger needs to perform some 15035memory writes in order to provide Ada tasking support. When inspecting 15036a core file, this means that the core file must be opened with read-write 15037privileges, using the command @samp{"set write on"} (@pxref{Patching}). 15038Under these circumstances, you should make a backup copy of the core 15039file before inspecting it with @value{GDBN}. 15040 15041@node Ravenscar Profile 15042@subsubsection Tasking Support when using the Ravenscar Profile 15043@cindex Ravenscar Profile 15044 15045The @dfn{Ravenscar Profile} is a subset of the Ada tasking features, 15046specifically designed for systems with safety-critical real-time 15047requirements. 15048 15049@table @code 15050@kindex set ravenscar task-switching on 15051@cindex task switching with program using Ravenscar Profile 15052@item set ravenscar task-switching on 15053Allows task switching when debugging a program that uses the Ravenscar 15054Profile. This is the default. 15055 15056@kindex set ravenscar task-switching off 15057@item set ravenscar task-switching off 15058Turn off task switching when debugging a program that uses the Ravenscar 15059Profile. This is mostly intended to disable the code that adds support 15060for the Ravenscar Profile, in case a bug in either @value{GDBN} or in 15061the Ravenscar runtime is preventing @value{GDBN} from working properly. 15062To be effective, this command should be run before the program is started. 15063 15064@kindex show ravenscar task-switching 15065@item show ravenscar task-switching 15066Show whether it is possible to switch from task to task in a program 15067using the Ravenscar Profile. 15068 15069@end table 15070 15071@node Ada Glitches 15072@subsubsection Known Peculiarities of Ada Mode 15073@cindex Ada, problems 15074 15075Besides the omissions listed previously (@pxref{Omissions from Ada}), 15076we know of several problems with and limitations of Ada mode in 15077@value{GDBN}, 15078some of which will be fixed with planned future releases of the debugger 15079and the GNU Ada compiler. 15080 15081@itemize @bullet 15082@item 15083Static constants that the compiler chooses not to materialize as objects in 15084storage are invisible to the debugger. 15085 15086@item 15087Named parameter associations in function argument lists are ignored (the 15088argument lists are treated as positional). 15089 15090@item 15091Many useful library packages are currently invisible to the debugger. 15092 15093@item 15094Fixed-point arithmetic, conversions, input, and output is carried out using 15095floating-point arithmetic, and may give results that only approximate those on 15096the host machine. 15097 15098@item 15099The GNAT compiler never generates the prefix @code{Standard} for any of 15100the standard symbols defined by the Ada language. @value{GDBN} knows about 15101this: it will strip the prefix from names when you use it, and will never 15102look for a name you have so qualified among local symbols, nor match against 15103symbols in other packages or subprograms. If you have 15104defined entities anywhere in your program other than parameters and 15105local variables whose simple names match names in @code{Standard}, 15106GNAT's lack of qualification here can cause confusion. When this happens, 15107you can usually resolve the confusion 15108by qualifying the problematic names with package 15109@code{Standard} explicitly. 15110@end itemize 15111 15112Older versions of the compiler sometimes generate erroneous debugging 15113information, resulting in the debugger incorrectly printing the value 15114of affected entities. In some cases, the debugger is able to work 15115around an issue automatically. In other cases, the debugger is able 15116to work around the issue, but the work-around has to be specifically 15117enabled. 15118 15119@kindex set ada trust-PAD-over-XVS 15120@kindex show ada trust-PAD-over-XVS 15121@table @code 15122 15123@item set ada trust-PAD-over-XVS on 15124Configure GDB to strictly follow the GNAT encoding when computing the 15125value of Ada entities, particularly when @code{PAD} and @code{PAD___XVS} 15126types are involved (see @code{ada/exp_dbug.ads} in the GCC sources for 15127a complete description of the encoding used by the GNAT compiler). 15128This is the default. 15129 15130@item set ada trust-PAD-over-XVS off 15131This is related to the encoding using by the GNAT compiler. If @value{GDBN} 15132sometimes prints the wrong value for certain entities, changing @code{ada 15133trust-PAD-over-XVS} to @code{off} activates a work-around which may fix 15134the issue. It is always safe to set @code{ada trust-PAD-over-XVS} to 15135@code{off}, but this incurs a slight performance penalty, so it is 15136recommended to leave this setting to @code{on} unless necessary. 15137 15138@end table 15139 15140@node Unsupported Languages 15141@section Unsupported Languages 15142 15143@cindex unsupported languages 15144@cindex minimal language 15145In addition to the other fully-supported programming languages, 15146@value{GDBN} also provides a pseudo-language, called @code{minimal}. 15147It does not represent a real programming language, but provides a set 15148of capabilities close to what the C or assembly languages provide. 15149This should allow most simple operations to be performed while debugging 15150an application that uses a language currently not supported by @value{GDBN}. 15151 15152If the language is set to @code{auto}, @value{GDBN} will automatically 15153select this language if the current frame corresponds to an unsupported 15154language. 15155 15156@node Symbols 15157@chapter Examining the Symbol Table 15158 15159The commands described in this chapter allow you to inquire about the 15160symbols (names of variables, functions and types) defined in your 15161program. This information is inherent in the text of your program and 15162does not change as your program executes. @value{GDBN} finds it in your 15163program's symbol table, in the file indicated when you started @value{GDBN} 15164(@pxref{File Options, ,Choosing Files}), or by one of the 15165file-management commands (@pxref{Files, ,Commands to Specify Files}). 15166 15167@cindex symbol names 15168@cindex names of symbols 15169@cindex quoting names 15170Occasionally, you may need to refer to symbols that contain unusual 15171characters, which @value{GDBN} ordinarily treats as word delimiters. The 15172most frequent case is in referring to static variables in other 15173source files (@pxref{Variables,,Program Variables}). File names 15174are recorded in object files as debugging symbols, but @value{GDBN} would 15175ordinarily parse a typical file name, like @file{foo.c}, as the three words 15176@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize 15177@samp{foo.c} as a single symbol, enclose it in single quotes; for example, 15178 15179@smallexample 15180p 'foo.c'::x 15181@end smallexample 15182 15183@noindent 15184looks up the value of @code{x} in the scope of the file @file{foo.c}. 15185 15186@table @code 15187@cindex case-insensitive symbol names 15188@cindex case sensitivity in symbol names 15189@kindex set case-sensitive 15190@item set case-sensitive on 15191@itemx set case-sensitive off 15192@itemx set case-sensitive auto 15193Normally, when @value{GDBN} looks up symbols, it matches their names 15194with case sensitivity determined by the current source language. 15195Occasionally, you may wish to control that. The command @code{set 15196case-sensitive} lets you do that by specifying @code{on} for 15197case-sensitive matches or @code{off} for case-insensitive ones. If 15198you specify @code{auto}, case sensitivity is reset to the default 15199suitable for the source language. The default is case-sensitive 15200matches for all languages except for Fortran, for which the default is 15201case-insensitive matches. 15202 15203@kindex show case-sensitive 15204@item show case-sensitive 15205This command shows the current setting of case sensitivity for symbols 15206lookups. 15207 15208@kindex set print type methods 15209@item set print type methods 15210@itemx set print type methods on 15211@itemx set print type methods off 15212Normally, when @value{GDBN} prints a class, it displays any methods 15213declared in that class. You can control this behavior either by 15214passing the appropriate flag to @code{ptype}, or using @command{set 15215print type methods}. Specifying @code{on} will cause @value{GDBN} to 15216display the methods; this is the default. Specifying @code{off} will 15217cause @value{GDBN} to omit the methods. 15218 15219@kindex show print type methods 15220@item show print type methods 15221This command shows the current setting of method display when printing 15222classes. 15223 15224@kindex set print type typedefs 15225@item set print type typedefs 15226@itemx set print type typedefs on 15227@itemx set print type typedefs off 15228 15229Normally, when @value{GDBN} prints a class, it displays any typedefs 15230defined in that class. You can control this behavior either by 15231passing the appropriate flag to @code{ptype}, or using @command{set 15232print type typedefs}. Specifying @code{on} will cause @value{GDBN} to 15233display the typedef definitions; this is the default. Specifying 15234@code{off} will cause @value{GDBN} to omit the typedef definitions. 15235Note that this controls whether the typedef definition itself is 15236printed, not whether typedef names are substituted when printing other 15237types. 15238 15239@kindex show print type typedefs 15240@item show print type typedefs 15241This command shows the current setting of typedef display when 15242printing classes. 15243 15244@kindex info address 15245@cindex address of a symbol 15246@item info address @var{symbol} 15247Describe where the data for @var{symbol} is stored. For a register 15248variable, this says which register it is kept in. For a non-register 15249local variable, this prints the stack-frame offset at which the variable 15250is always stored. 15251 15252Note the contrast with @samp{print &@var{symbol}}, which does not work 15253at all for a register variable, and for a stack local variable prints 15254the exact address of the current instantiation of the variable. 15255 15256@kindex info symbol 15257@cindex symbol from address 15258@cindex closest symbol and offset for an address 15259@item info symbol @var{addr} 15260Print the name of a symbol which is stored at the address @var{addr}. 15261If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the 15262nearest symbol and an offset from it: 15263 15264@smallexample 15265(@value{GDBP}) info symbol 0x54320 15266_initialize_vx + 396 in section .text 15267@end smallexample 15268 15269@noindent 15270This is the opposite of the @code{info address} command. You can use 15271it to find out the name of a variable or a function given its address. 15272 15273For dynamically linked executables, the name of executable or shared 15274library containing the symbol is also printed: 15275 15276@smallexample 15277(@value{GDBP}) info symbol 0x400225 15278_start + 5 in section .text of /tmp/a.out 15279(@value{GDBP}) info symbol 0x2aaaac2811cf 15280__read_nocancel + 6 in section .text of /usr/lib64/libc.so.6 15281@end smallexample 15282 15283@kindex whatis 15284@item whatis[/@var{flags}] [@var{arg}] 15285Print the data type of @var{arg}, which can be either an expression 15286or a name of a data type. With no argument, print the data type of 15287@code{$}, the last value in the value history. 15288 15289If @var{arg} is an expression (@pxref{Expressions, ,Expressions}), it 15290is not actually evaluated, and any side-effecting operations (such as 15291assignments or function calls) inside it do not take place. 15292 15293If @var{arg} is a variable or an expression, @code{whatis} prints its 15294literal type as it is used in the source code. If the type was 15295defined using a @code{typedef}, @code{whatis} will @emph{not} print 15296the data type underlying the @code{typedef}. If the type of the 15297variable or the expression is a compound data type, such as 15298@code{struct} or @code{class}, @code{whatis} never prints their 15299fields or methods. It just prints the @code{struct}/@code{class} 15300name (a.k.a.@: its @dfn{tag}). If you want to see the members of 15301such a compound data type, use @code{ptype}. 15302 15303If @var{arg} is a type name that was defined using @code{typedef}, 15304@code{whatis} @dfn{unrolls} only one level of that @code{typedef}. 15305Unrolling means that @code{whatis} will show the underlying type used 15306in the @code{typedef} declaration of @var{arg}. However, if that 15307underlying type is also a @code{typedef}, @code{whatis} will not 15308unroll it. 15309 15310For C code, the type names may also have the form @samp{class 15311@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union 15312@var{union-tag}} or @samp{enum @var{enum-tag}}. 15313 15314@var{flags} can be used to modify how the type is displayed. 15315Available flags are: 15316 15317@table @code 15318@item r 15319Display in ``raw'' form. Normally, @value{GDBN} substitutes template 15320parameters and typedefs defined in a class when printing the class' 15321members. The @code{/r} flag disables this. 15322 15323@item m 15324Do not print methods defined in the class. 15325 15326@item M 15327Print methods defined in the class. This is the default, but the flag 15328exists in case you change the default with @command{set print type methods}. 15329 15330@item t 15331Do not print typedefs defined in the class. Note that this controls 15332whether the typedef definition itself is printed, not whether typedef 15333names are substituted when printing other types. 15334 15335@item T 15336Print typedefs defined in the class. This is the default, but the flag 15337exists in case you change the default with @command{set print type typedefs}. 15338@end table 15339 15340@kindex ptype 15341@item ptype[/@var{flags}] [@var{arg}] 15342@code{ptype} accepts the same arguments as @code{whatis}, but prints a 15343detailed description of the type, instead of just the name of the type. 15344@xref{Expressions, ,Expressions}. 15345 15346Contrary to @code{whatis}, @code{ptype} always unrolls any 15347@code{typedef}s in its argument declaration, whether the argument is 15348a variable, expression, or a data type. This means that @code{ptype} 15349of a variable or an expression will not print literally its type as 15350present in the source code---use @code{whatis} for that. @code{typedef}s at 15351the pointer or reference targets are also unrolled. Only @code{typedef}s of 15352fields, methods and inner @code{class typedef}s of @code{struct}s, 15353@code{class}es and @code{union}s are not unrolled even with @code{ptype}. 15354 15355For example, for this variable declaration: 15356 15357@smallexample 15358typedef double real_t; 15359struct complex @{ real_t real; double imag; @}; 15360typedef struct complex complex_t; 15361complex_t var; 15362real_t *real_pointer_var; 15363@end smallexample 15364 15365@noindent 15366the two commands give this output: 15367 15368@smallexample 15369@group 15370(@value{GDBP}) whatis var 15371type = complex_t 15372(@value{GDBP}) ptype var 15373type = struct complex @{ 15374 real_t real; 15375 double imag; 15376@} 15377(@value{GDBP}) whatis complex_t 15378type = struct complex 15379(@value{GDBP}) whatis struct complex 15380type = struct complex 15381(@value{GDBP}) ptype struct complex 15382type = struct complex @{ 15383 real_t real; 15384 double imag; 15385@} 15386(@value{GDBP}) whatis real_pointer_var 15387type = real_t * 15388(@value{GDBP}) ptype real_pointer_var 15389type = double * 15390@end group 15391@end smallexample 15392 15393@noindent 15394As with @code{whatis}, using @code{ptype} without an argument refers to 15395the type of @code{$}, the last value in the value history. 15396 15397@cindex incomplete type 15398Sometimes, programs use opaque data types or incomplete specifications 15399of complex data structure. If the debug information included in the 15400program does not allow @value{GDBN} to display a full declaration of 15401the data type, it will say @samp{<incomplete type>}. For example, 15402given these declarations: 15403 15404@smallexample 15405 struct foo; 15406 struct foo *fooptr; 15407@end smallexample 15408 15409@noindent 15410but no definition for @code{struct foo} itself, @value{GDBN} will say: 15411 15412@smallexample 15413 (@value{GDBP}) ptype foo 15414 $1 = <incomplete type> 15415@end smallexample 15416 15417@noindent 15418``Incomplete type'' is C terminology for data types that are not 15419completely specified. 15420 15421@kindex info types 15422@item info types @var{regexp} 15423@itemx info types 15424Print a brief description of all types whose names match the regular 15425expression @var{regexp} (or all types in your program, if you supply 15426no argument). Each complete typename is matched as though it were a 15427complete line; thus, @samp{i type value} gives information on all 15428types in your program whose names include the string @code{value}, but 15429@samp{i type ^value$} gives information only on types whose complete 15430name is @code{value}. 15431 15432This command differs from @code{ptype} in two ways: first, like 15433@code{whatis}, it does not print a detailed description; second, it 15434lists all source files where a type is defined. 15435 15436@kindex info type-printers 15437@item info type-printers 15438Versions of @value{GDBN} that ship with Python scripting enabled may 15439have ``type printers'' available. When using @command{ptype} or 15440@command{whatis}, these printers are consulted when the name of a type 15441is needed. @xref{Type Printing API}, for more information on writing 15442type printers. 15443 15444@code{info type-printers} displays all the available type printers. 15445 15446@kindex enable type-printer 15447@kindex disable type-printer 15448@item enable type-printer @var{name}@dots{} 15449@item disable type-printer @var{name}@dots{} 15450These commands can be used to enable or disable type printers. 15451 15452@kindex info scope 15453@cindex local variables 15454@item info scope @var{location} 15455List all the variables local to a particular scope. This command 15456accepts a @var{location} argument---a function name, a source line, or 15457an address preceded by a @samp{*}, and prints all the variables local 15458to the scope defined by that location. (@xref{Specify Location}, for 15459details about supported forms of @var{location}.) For example: 15460 15461@smallexample 15462(@value{GDBP}) @b{info scope command_line_handler} 15463Scope for command_line_handler: 15464Symbol rl is an argument at stack/frame offset 8, length 4. 15465Symbol linebuffer is in static storage at address 0x150a18, length 4. 15466Symbol linelength is in static storage at address 0x150a1c, length 4. 15467Symbol p is a local variable in register $esi, length 4. 15468Symbol p1 is a local variable in register $ebx, length 4. 15469Symbol nline is a local variable in register $edx, length 4. 15470Symbol repeat is a local variable at frame offset -8, length 4. 15471@end smallexample 15472 15473@noindent 15474This command is especially useful for determining what data to collect 15475during a @dfn{trace experiment}, see @ref{Tracepoint Actions, 15476collect}. 15477 15478@kindex info source 15479@item info source 15480Show information about the current source file---that is, the source file for 15481the function containing the current point of execution: 15482@itemize @bullet 15483@item 15484the name of the source file, and the directory containing it, 15485@item 15486the directory it was compiled in, 15487@item 15488its length, in lines, 15489@item 15490which programming language it is written in, 15491@item 15492whether the executable includes debugging information for that file, and 15493if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and 15494@item 15495whether the debugging information includes information about 15496preprocessor macros. 15497@end itemize 15498 15499 15500@kindex info sources 15501@item info sources 15502Print the names of all source files in your program for which there is 15503debugging information, organized into two lists: files whose symbols 15504have already been read, and files whose symbols will be read when needed. 15505 15506@kindex info functions 15507@item info functions 15508Print the names and data types of all defined functions. 15509 15510@item info functions @var{regexp} 15511Print the names and data types of all defined functions 15512whose names contain a match for regular expression @var{regexp}. 15513Thus, @samp{info fun step} finds all functions whose names 15514include @code{step}; @samp{info fun ^step} finds those whose names 15515start with @code{step}. If a function name contains characters 15516that conflict with the regular expression language (e.g.@: 15517@samp{operator*()}), they may be quoted with a backslash. 15518 15519@kindex info variables 15520@item info variables 15521Print the names and data types of all variables that are defined 15522outside of functions (i.e.@: excluding local variables). 15523 15524@item info variables @var{regexp} 15525Print the names and data types of all variables (except for local 15526variables) whose names contain a match for regular expression 15527@var{regexp}. 15528 15529@kindex info classes 15530@cindex Objective-C, classes and selectors 15531@item info classes 15532@itemx info classes @var{regexp} 15533Display all Objective-C classes in your program, or 15534(with the @var{regexp} argument) all those matching a particular regular 15535expression. 15536 15537@kindex info selectors 15538@item info selectors 15539@itemx info selectors @var{regexp} 15540Display all Objective-C selectors in your program, or 15541(with the @var{regexp} argument) all those matching a particular regular 15542expression. 15543 15544@ignore 15545This was never implemented. 15546@kindex info methods 15547@item info methods 15548@itemx info methods @var{regexp} 15549The @code{info methods} command permits the user to examine all defined 15550methods within C@t{++} program, or (with the @var{regexp} argument) a 15551specific set of methods found in the various C@t{++} classes. Many 15552C@t{++} classes provide a large number of methods. Thus, the output 15553from the @code{ptype} command can be overwhelming and hard to use. The 15554@code{info-methods} command filters the methods, printing only those 15555which match the regular-expression @var{regexp}. 15556@end ignore 15557 15558@cindex opaque data types 15559@kindex set opaque-type-resolution 15560@item set opaque-type-resolution on 15561Tell @value{GDBN} to resolve opaque types. An opaque type is a type 15562declared as a pointer to a @code{struct}, @code{class}, or 15563@code{union}---for example, @code{struct MyType *}---that is used in one 15564source file although the full declaration of @code{struct MyType} is in 15565another source file. The default is on. 15566 15567A change in the setting of this subcommand will not take effect until 15568the next time symbols for a file are loaded. 15569 15570@item set opaque-type-resolution off 15571Tell @value{GDBN} not to resolve opaque types. In this case, the type 15572is printed as follows: 15573@smallexample 15574@{<no data fields>@} 15575@end smallexample 15576 15577@kindex show opaque-type-resolution 15578@item show opaque-type-resolution 15579Show whether opaque types are resolved or not. 15580 15581@kindex maint print symbols 15582@cindex symbol dump 15583@kindex maint print psymbols 15584@cindex partial symbol dump 15585@item maint print symbols @var{filename} 15586@itemx maint print psymbols @var{filename} 15587@itemx maint print msymbols @var{filename} 15588Write a dump of debugging symbol data into the file @var{filename}. 15589These commands are used to debug the @value{GDBN} symbol-reading code. Only 15590symbols with debugging data are included. If you use @samp{maint print 15591symbols}, @value{GDBN} includes all the symbols for which it has already 15592collected full details: that is, @var{filename} reflects symbols for 15593only those files whose symbols @value{GDBN} has read. You can use the 15594command @code{info sources} to find out which files these are. If you 15595use @samp{maint print psymbols} instead, the dump shows information about 15596symbols that @value{GDBN} only knows partially---that is, symbols defined in 15597files that @value{GDBN} has skimmed, but not yet read completely. Finally, 15598@samp{maint print msymbols} dumps just the minimal symbol information 15599required for each object file from which @value{GDBN} has read some symbols. 15600@xref{Files, ,Commands to Specify Files}, for a discussion of how 15601@value{GDBN} reads symbols (in the description of @code{symbol-file}). 15602 15603@kindex maint info symtabs 15604@kindex maint info psymtabs 15605@cindex listing @value{GDBN}'s internal symbol tables 15606@cindex symbol tables, listing @value{GDBN}'s internal 15607@cindex full symbol tables, listing @value{GDBN}'s internal 15608@cindex partial symbol tables, listing @value{GDBN}'s internal 15609@item maint info symtabs @r{[} @var{regexp} @r{]} 15610@itemx maint info psymtabs @r{[} @var{regexp} @r{]} 15611 15612List the @code{struct symtab} or @code{struct partial_symtab} 15613structures whose names match @var{regexp}. If @var{regexp} is not 15614given, list them all. The output includes expressions which you can 15615copy into a @value{GDBN} debugging this one to examine a particular 15616structure in more detail. For example: 15617 15618@smallexample 15619(@value{GDBP}) maint info psymtabs dwarf2read 15620@{ objfile /home/gnu/build/gdb/gdb 15621 ((struct objfile *) 0x82e69d0) 15622 @{ psymtab /home/gnu/src/gdb/dwarf2read.c 15623 ((struct partial_symtab *) 0x8474b10) 15624 readin no 15625 fullname (null) 15626 text addresses 0x814d3c8 -- 0x8158074 15627 globals (* (struct partial_symbol **) 0x8507a08 @@ 9) 15628 statics (* (struct partial_symbol **) 0x40e95b78 @@ 2882) 15629 dependencies (none) 15630 @} 15631@} 15632(@value{GDBP}) maint info symtabs 15633(@value{GDBP}) 15634@end smallexample 15635@noindent 15636We see that there is one partial symbol table whose filename contains 15637the string @samp{dwarf2read}, belonging to the @samp{gdb} executable; 15638and we see that @value{GDBN} has not read in any symtabs yet at all. 15639If we set a breakpoint on a function, that will cause @value{GDBN} to 15640read the symtab for the compilation unit containing that function: 15641 15642@smallexample 15643(@value{GDBP}) break dwarf2_psymtab_to_symtab 15644Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, 15645line 1574. 15646(@value{GDBP}) maint info symtabs 15647@{ objfile /home/gnu/build/gdb/gdb 15648 ((struct objfile *) 0x82e69d0) 15649 @{ symtab /home/gnu/src/gdb/dwarf2read.c 15650 ((struct symtab *) 0x86c1f38) 15651 dirname (null) 15652 fullname (null) 15653 blockvector ((struct blockvector *) 0x86c1bd0) (primary) 15654 linetable ((struct linetable *) 0x8370fa0) 15655 debugformat DWARF 2 15656 @} 15657@} 15658(@value{GDBP}) 15659@end smallexample 15660@end table 15661 15662 15663@node Altering 15664@chapter Altering Execution 15665 15666Once you think you have found an error in your program, you might want to 15667find out for certain whether correcting the apparent error would lead to 15668correct results in the rest of the run. You can find the answer by 15669experiment, using the @value{GDBN} features for altering execution of the 15670program. 15671 15672For example, you can store new values into variables or memory 15673locations, give your program a signal, restart it at a different 15674address, or even return prematurely from a function. 15675 15676@menu 15677* Assignment:: Assignment to variables 15678* Jumping:: Continuing at a different address 15679* Signaling:: Giving your program a signal 15680* Returning:: Returning from a function 15681* Calling:: Calling your program's functions 15682* Patching:: Patching your program 15683@end menu 15684 15685@node Assignment 15686@section Assignment to Variables 15687 15688@cindex assignment 15689@cindex setting variables 15690To alter the value of a variable, evaluate an assignment expression. 15691@xref{Expressions, ,Expressions}. For example, 15692 15693@smallexample 15694print x=4 15695@end smallexample 15696 15697@noindent 15698stores the value 4 into the variable @code{x}, and then prints the 15699value of the assignment expression (which is 4). 15700@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more 15701information on operators in supported languages. 15702 15703@kindex set variable 15704@cindex variables, setting 15705If you are not interested in seeing the value of the assignment, use the 15706@code{set} command instead of the @code{print} command. @code{set} is 15707really the same as @code{print} except that the expression's value is 15708not printed and is not put in the value history (@pxref{Value History, 15709,Value History}). The expression is evaluated only for its effects. 15710 15711If the beginning of the argument string of the @code{set} command 15712appears identical to a @code{set} subcommand, use the @code{set 15713variable} command instead of just @code{set}. This command is identical 15714to @code{set} except for its lack of subcommands. For example, if your 15715program has a variable @code{width}, you get an error if you try to set 15716a new value with just @samp{set width=13}, because @value{GDBN} has the 15717command @code{set width}: 15718 15719@smallexample 15720(@value{GDBP}) whatis width 15721type = double 15722(@value{GDBP}) p width 15723$4 = 13 15724(@value{GDBP}) set width=47 15725Invalid syntax in expression. 15726@end smallexample 15727 15728@noindent 15729The invalid expression, of course, is @samp{=47}. In 15730order to actually set the program's variable @code{width}, use 15731 15732@smallexample 15733(@value{GDBP}) set var width=47 15734@end smallexample 15735 15736Because the @code{set} command has many subcommands that can conflict 15737with the names of program variables, it is a good idea to use the 15738@code{set variable} command instead of just @code{set}. For example, if 15739your program has a variable @code{g}, you run into problems if you try 15740to set a new value with just @samp{set g=4}, because @value{GDBN} has 15741the command @code{set gnutarget}, abbreviated @code{set g}: 15742 15743@smallexample 15744@group 15745(@value{GDBP}) whatis g 15746type = double 15747(@value{GDBP}) p g 15748$1 = 1 15749(@value{GDBP}) set g=4 15750(@value{GDBP}) p g 15751$2 = 1 15752(@value{GDBP}) r 15753The program being debugged has been started already. 15754Start it from the beginning? (y or n) y 15755Starting program: /home/smith/cc_progs/a.out 15756"/home/smith/cc_progs/a.out": can't open to read symbols: 15757 Invalid bfd target. 15758(@value{GDBP}) show g 15759The current BFD target is "=4". 15760@end group 15761@end smallexample 15762 15763@noindent 15764The program variable @code{g} did not change, and you silently set the 15765@code{gnutarget} to an invalid value. In order to set the variable 15766@code{g}, use 15767 15768@smallexample 15769(@value{GDBP}) set var g=4 15770@end smallexample 15771 15772@value{GDBN} allows more implicit conversions in assignments than C; you can 15773freely store an integer value into a pointer variable or vice versa, 15774and you can convert any structure to any other structure that is the 15775same length or shorter. 15776@comment FIXME: how do structs align/pad in these conversions? 15777@comment /doc@cygnus.com 18dec1990 15778 15779To store values into arbitrary places in memory, use the @samp{@{@dots{}@}} 15780construct to generate a value of specified type at a specified address 15781(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers 15782to memory location @code{0x83040} as an integer (which implies a certain size 15783and representation in memory), and 15784 15785@smallexample 15786set @{int@}0x83040 = 4 15787@end smallexample 15788 15789@noindent 15790stores the value 4 into that memory location. 15791 15792@node Jumping 15793@section Continuing at a Different Address 15794 15795Ordinarily, when you continue your program, you do so at the place where 15796it stopped, with the @code{continue} command. You can instead continue at 15797an address of your own choosing, with the following commands: 15798 15799@table @code 15800@kindex jump 15801@kindex j @r{(@code{jump})} 15802@item jump @var{linespec} 15803@itemx j @var{linespec} 15804@itemx jump @var{location} 15805@itemx j @var{location} 15806Resume execution at line @var{linespec} or at address given by 15807@var{location}. Execution stops again immediately if there is a 15808breakpoint there. @xref{Specify Location}, for a description of the 15809different forms of @var{linespec} and @var{location}. It is common 15810practice to use the @code{tbreak} command in conjunction with 15811@code{jump}. @xref{Set Breaks, ,Setting Breakpoints}. 15812 15813The @code{jump} command does not change the current stack frame, or 15814the stack pointer, or the contents of any memory location or any 15815register other than the program counter. If line @var{linespec} is in 15816a different function from the one currently executing, the results may 15817be bizarre if the two functions expect different patterns of arguments or 15818of local variables. For this reason, the @code{jump} command requests 15819confirmation if the specified line is not in the function currently 15820executing. However, even bizarre results are predictable if you are 15821well acquainted with the machine-language code of your program. 15822@end table 15823 15824@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt. 15825On many systems, you can get much the same effect as the @code{jump} 15826command by storing a new value into the register @code{$pc}. The 15827difference is that this does not start your program running; it only 15828changes the address of where it @emph{will} run when you continue. For 15829example, 15830 15831@smallexample 15832set $pc = 0x485 15833@end smallexample 15834 15835@noindent 15836makes the next @code{continue} command or stepping command execute at 15837address @code{0x485}, rather than at the address where your program stopped. 15838@xref{Continuing and Stepping, ,Continuing and Stepping}. 15839 15840The most common occasion to use the @code{jump} command is to back 15841up---perhaps with more breakpoints set---over a portion of a program 15842that has already executed, in order to examine its execution in more 15843detail. 15844 15845@c @group 15846@node Signaling 15847@section Giving your Program a Signal 15848@cindex deliver a signal to a program 15849 15850@table @code 15851@kindex signal 15852@item signal @var{signal} 15853Resume execution where your program stopped, but immediately give it the 15854signal @var{signal}. @var{signal} can be the name or the number of a 15855signal. For example, on many systems @code{signal 2} and @code{signal 15856SIGINT} are both ways of sending an interrupt signal. 15857 15858Alternatively, if @var{signal} is zero, continue execution without 15859giving a signal. This is useful when your program stopped on account of 15860a signal and would ordinarily see the signal when resumed with the 15861@code{continue} command; @samp{signal 0} causes it to resume without a 15862signal. 15863 15864@code{signal} does not repeat when you press @key{RET} a second time 15865after executing the command. 15866@end table 15867@c @end group 15868 15869Invoking the @code{signal} command is not the same as invoking the 15870@code{kill} utility from the shell. Sending a signal with @code{kill} 15871causes @value{GDBN} to decide what to do with the signal depending on 15872the signal handling tables (@pxref{Signals}). The @code{signal} command 15873passes the signal directly to your program. 15874 15875 15876@node Returning 15877@section Returning from a Function 15878 15879@table @code 15880@cindex returning from a function 15881@kindex return 15882@item return 15883@itemx return @var{expression} 15884You can cancel execution of a function call with the @code{return} 15885command. If you give an 15886@var{expression} argument, its value is used as the function's return 15887value. 15888@end table 15889 15890When you use @code{return}, @value{GDBN} discards the selected stack frame 15891(and all frames within it). You can think of this as making the 15892discarded frame return prematurely. If you wish to specify a value to 15893be returned, give that value as the argument to @code{return}. 15894 15895This pops the selected stack frame (@pxref{Selection, ,Selecting a 15896Frame}), and any other frames inside of it, leaving its caller as the 15897innermost remaining frame. That frame becomes selected. The 15898specified value is stored in the registers used for returning values 15899of functions. 15900 15901The @code{return} command does not resume execution; it leaves the 15902program stopped in the state that would exist if the function had just 15903returned. In contrast, the @code{finish} command (@pxref{Continuing 15904and Stepping, ,Continuing and Stepping}) resumes execution until the 15905selected stack frame returns naturally. 15906 15907@value{GDBN} needs to know how the @var{expression} argument should be set for 15908the inferior. The concrete registers assignment depends on the OS ABI and the 15909type being returned by the selected stack frame. For example it is common for 15910OS ABI to return floating point values in FPU registers while integer values in 15911CPU registers. Still some ABIs return even floating point values in CPU 15912registers. Larger integer widths (such as @code{long long int}) also have 15913specific placement rules. @value{GDBN} already knows the OS ABI from its 15914current target so it needs to find out also the type being returned to make the 15915assignment into the right register(s). 15916 15917Normally, the selected stack frame has debug info. @value{GDBN} will always 15918use the debug info instead of the implicit type of @var{expression} when the 15919debug info is available. For example, if you type @kbd{return -1}, and the 15920function in the current stack frame is declared to return a @code{long long 15921int}, @value{GDBN} transparently converts the implicit @code{int} value of -1 15922into a @code{long long int}: 15923 15924@smallexample 15925Breakpoint 1, func () at gdb.base/return-nodebug.c:29 1592629 return 31; 15927(@value{GDBP}) return -1 15928Make func return now? (y or n) y 15929#0 0x004004f6 in main () at gdb.base/return-nodebug.c:43 1593043 printf ("result=%lld\n", func ()); 15931(@value{GDBP}) 15932@end smallexample 15933 15934However, if the selected stack frame does not have a debug info, e.g., if the 15935function was compiled without debug info, @value{GDBN} has to find out the type 15936to return from user. Specifying a different type by mistake may set the value 15937in different inferior registers than the caller code expects. For example, 15938typing @kbd{return -1} with its implicit type @code{int} would set only a part 15939of a @code{long long int} result for a debug info less function (on 32-bit 15940architectures). Therefore the user is required to specify the return type by 15941an appropriate cast explicitly: 15942 15943@smallexample 15944Breakpoint 2, 0x0040050b in func () 15945(@value{GDBP}) return -1 15946Return value type not available for selected stack frame. 15947Please use an explicit cast of the value to return. 15948(@value{GDBP}) return (long long int) -1 15949Make selected stack frame return now? (y or n) y 15950#0 0x00400526 in main () 15951(@value{GDBP}) 15952@end smallexample 15953 15954@node Calling 15955@section Calling Program Functions 15956 15957@table @code 15958@cindex calling functions 15959@cindex inferior functions, calling 15960@item print @var{expr} 15961Evaluate the expression @var{expr} and display the resulting value. 15962@var{expr} may include calls to functions in the program being 15963debugged. 15964 15965@kindex call 15966@item call @var{expr} 15967Evaluate the expression @var{expr} without displaying @code{void} 15968returned values. 15969 15970You can use this variant of the @code{print} command if you want to 15971execute a function from your program that does not return anything 15972(a.k.a.@: @dfn{a void function}), but without cluttering the output 15973with @code{void} returned values that @value{GDBN} will otherwise 15974print. If the result is not void, it is printed and saved in the 15975value history. 15976@end table 15977 15978It is possible for the function you call via the @code{print} or 15979@code{call} command to generate a signal (e.g., if there's a bug in 15980the function, or if you passed it incorrect arguments). What happens 15981in that case is controlled by the @code{set unwindonsignal} command. 15982 15983Similarly, with a C@t{++} program it is possible for the function you 15984call via the @code{print} or @code{call} command to generate an 15985exception that is not handled due to the constraints of the dummy 15986frame. In this case, any exception that is raised in the frame, but has 15987an out-of-frame exception handler will not be found. GDB builds a 15988dummy-frame for the inferior function call, and the unwinder cannot 15989seek for exception handlers outside of this dummy-frame. What happens 15990in that case is controlled by the 15991@code{set unwind-on-terminating-exception} command. 15992 15993@table @code 15994@item set unwindonsignal 15995@kindex set unwindonsignal 15996@cindex unwind stack in called functions 15997@cindex call dummy stack unwinding 15998Set unwinding of the stack if a signal is received while in a function 15999that @value{GDBN} called in the program being debugged. If set to on, 16000@value{GDBN} unwinds the stack it created for the call and restores 16001the context to what it was before the call. If set to off (the 16002default), @value{GDBN} stops in the frame where the signal was 16003received. 16004 16005@item show unwindonsignal 16006@kindex show unwindonsignal 16007Show the current setting of stack unwinding in the functions called by 16008@value{GDBN}. 16009 16010@item set unwind-on-terminating-exception 16011@kindex set unwind-on-terminating-exception 16012@cindex unwind stack in called functions with unhandled exceptions 16013@cindex call dummy stack unwinding on unhandled exception. 16014Set unwinding of the stack if a C@t{++} exception is raised, but left 16015unhandled while in a function that @value{GDBN} called in the program being 16016debugged. If set to on (the default), @value{GDBN} unwinds the stack 16017it created for the call and restores the context to what it was before 16018the call. If set to off, @value{GDBN} the exception is delivered to 16019the default C@t{++} exception handler and the inferior terminated. 16020 16021@item show unwind-on-terminating-exception 16022@kindex show unwind-on-terminating-exception 16023Show the current setting of stack unwinding in the functions called by 16024@value{GDBN}. 16025 16026@end table 16027 16028@cindex weak alias functions 16029Sometimes, a function you wish to call is actually a @dfn{weak alias} 16030for another function. In such case, @value{GDBN} might not pick up 16031the type information, including the types of the function arguments, 16032which causes @value{GDBN} to call the inferior function incorrectly. 16033As a result, the called function will function erroneously and may 16034even crash. A solution to that is to use the name of the aliased 16035function instead. 16036 16037@node Patching 16038@section Patching Programs 16039 16040@cindex patching binaries 16041@cindex writing into executables 16042@cindex writing into corefiles 16043 16044By default, @value{GDBN} opens the file containing your program's 16045executable code (or the corefile) read-only. This prevents accidental 16046alterations to machine code; but it also prevents you from intentionally 16047patching your program's binary. 16048 16049If you'd like to be able to patch the binary, you can specify that 16050explicitly with the @code{set write} command. For example, you might 16051want to turn on internal debugging flags, or even to make emergency 16052repairs. 16053 16054@table @code 16055@kindex set write 16056@item set write on 16057@itemx set write off 16058If you specify @samp{set write on}, @value{GDBN} opens executable and 16059core files for both reading and writing; if you specify @kbd{set write 16060off} (the default), @value{GDBN} opens them read-only. 16061 16062If you have already loaded a file, you must load it again (using the 16063@code{exec-file} or @code{core-file} command) after changing @code{set 16064write}, for your new setting to take effect. 16065 16066@item show write 16067@kindex show write 16068Display whether executable files and core files are opened for writing 16069as well as reading. 16070@end table 16071 16072@node GDB Files 16073@chapter @value{GDBN} Files 16074 16075@value{GDBN} needs to know the file name of the program to be debugged, 16076both in order to read its symbol table and in order to start your 16077program. To debug a core dump of a previous run, you must also tell 16078@value{GDBN} the name of the core dump file. 16079 16080@menu 16081* Files:: Commands to specify files 16082* Separate Debug Files:: Debugging information in separate files 16083* MiniDebugInfo:: Debugging information in a special section 16084* Index Files:: Index files speed up GDB 16085* Symbol Errors:: Errors reading symbol files 16086* Data Files:: GDB data files 16087@end menu 16088 16089@node Files 16090@section Commands to Specify Files 16091 16092@cindex symbol table 16093@cindex core dump file 16094 16095You may want to specify executable and core dump file names. The usual 16096way to do this is at start-up time, using the arguments to 16097@value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and 16098Out of @value{GDBN}}). 16099 16100Occasionally it is necessary to change to a different file during a 16101@value{GDBN} session. Or you may run @value{GDBN} and forget to 16102specify a file you want to use. Or you are debugging a remote target 16103via @code{gdbserver} (@pxref{Server, file, Using the @code{gdbserver} 16104Program}). In these situations the @value{GDBN} commands to specify 16105new files are useful. 16106 16107@table @code 16108@cindex executable file 16109@kindex file 16110@item file @var{filename} 16111Use @var{filename} as the program to be debugged. It is read for its 16112symbols and for the contents of pure memory. It is also the program 16113executed when you use the @code{run} command. If you do not specify a 16114directory and the file is not found in the @value{GDBN} working directory, 16115@value{GDBN} uses the environment variable @code{PATH} as a list of 16116directories to search, just as the shell does when looking for a program 16117to run. You can change the value of this variable, for both @value{GDBN} 16118and your program, using the @code{path} command. 16119 16120@cindex unlinked object files 16121@cindex patching object files 16122You can load unlinked object @file{.o} files into @value{GDBN} using 16123the @code{file} command. You will not be able to ``run'' an object 16124file, but you can disassemble functions and inspect variables. Also, 16125if the underlying BFD functionality supports it, you could use 16126@kbd{gdb -write} to patch object files using this technique. Note 16127that @value{GDBN} can neither interpret nor modify relocations in this 16128case, so branches and some initialized variables will appear to go to 16129the wrong place. But this feature is still handy from time to time. 16130 16131@item file 16132@code{file} with no argument makes @value{GDBN} discard any information it 16133has on both executable file and the symbol table. 16134 16135@kindex exec-file 16136@item exec-file @r{[} @var{filename} @r{]} 16137Specify that the program to be run (but not the symbol table) is found 16138in @var{filename}. @value{GDBN} searches the environment variable @code{PATH} 16139if necessary to locate your program. Omitting @var{filename} means to 16140discard information on the executable file. 16141 16142@kindex symbol-file 16143@item symbol-file @r{[} @var{filename} @r{]} 16144Read symbol table information from file @var{filename}. @code{PATH} is 16145searched when necessary. Use the @code{file} command to get both symbol 16146table and program to run from the same file. 16147 16148@code{symbol-file} with no argument clears out @value{GDBN} information on your 16149program's symbol table. 16150 16151The @code{symbol-file} command causes @value{GDBN} to forget the contents of 16152some breakpoints and auto-display expressions. This is because they may 16153contain pointers to the internal data recording symbols and data types, 16154which are part of the old symbol table data being discarded inside 16155@value{GDBN}. 16156 16157@code{symbol-file} does not repeat if you press @key{RET} again after 16158executing it once. 16159 16160When @value{GDBN} is configured for a particular environment, it 16161understands debugging information in whatever format is the standard 16162generated for that environment; you may use either a @sc{gnu} compiler, or 16163other compilers that adhere to the local conventions. 16164Best results are usually obtained from @sc{gnu} compilers; for example, 16165using @code{@value{NGCC}} you can generate debugging information for 16166optimized code. 16167 16168For most kinds of object files, with the exception of old SVR3 systems 16169using COFF, the @code{symbol-file} command does not normally read the 16170symbol table in full right away. Instead, it scans the symbol table 16171quickly to find which source files and which symbols are present. The 16172details are read later, one source file at a time, as they are needed. 16173 16174The purpose of this two-stage reading strategy is to make @value{GDBN} 16175start up faster. For the most part, it is invisible except for 16176occasional pauses while the symbol table details for a particular source 16177file are being read. (The @code{set verbose} command can turn these 16178pauses into messages if desired. @xref{Messages/Warnings, ,Optional 16179Warnings and Messages}.) 16180 16181We have not implemented the two-stage strategy for COFF yet. When the 16182symbol table is stored in COFF format, @code{symbol-file} reads the 16183symbol table data in full right away. Note that ``stabs-in-COFF'' 16184still does the two-stage strategy, since the debug info is actually 16185in stabs format. 16186 16187@kindex readnow 16188@cindex reading symbols immediately 16189@cindex symbols, reading immediately 16190@item symbol-file @r{[} -readnow @r{]} @var{filename} 16191@itemx file @r{[} -readnow @r{]} @var{filename} 16192You can override the @value{GDBN} two-stage strategy for reading symbol 16193tables by using the @samp{-readnow} option with any of the commands that 16194load symbol table information, if you want to be sure @value{GDBN} has the 16195entire symbol table available. 16196 16197@c FIXME: for now no mention of directories, since this seems to be in 16198@c flux. 13mar1992 status is that in theory GDB would look either in 16199@c current dir or in same dir as myprog; but issues like competing 16200@c GDB's, or clutter in system dirs, mean that in practice right now 16201@c only current dir is used. FFish says maybe a special GDB hierarchy 16202@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol 16203@c files. 16204 16205@kindex core-file 16206@item core-file @r{[}@var{filename}@r{]} 16207@itemx core 16208Specify the whereabouts of a core dump file to be used as the ``contents 16209of memory''. Traditionally, core files contain only some parts of the 16210address space of the process that generated them; @value{GDBN} can access the 16211executable file itself for other parts. 16212 16213@code{core-file} with no argument specifies that no core file is 16214to be used. 16215 16216Note that the core file is ignored when your program is actually running 16217under @value{GDBN}. So, if you have been running your program and you 16218wish to debug a core file instead, you must kill the subprocess in which 16219the program is running. To do this, use the @code{kill} command 16220(@pxref{Kill Process, ,Killing the Child Process}). 16221 16222@kindex add-symbol-file 16223@cindex dynamic linking 16224@item add-symbol-file @var{filename} @var{address} 16225@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} 16226@itemx add-symbol-file @var{filename} @var{address} -s @var{section} @var{address} @dots{} 16227The @code{add-symbol-file} command reads additional symbol table 16228information from the file @var{filename}. You would use this command 16229when @var{filename} has been dynamically loaded (by some other means) 16230into the program that is running. @var{address} should be the memory 16231address at which the file has been loaded; @value{GDBN} cannot figure 16232this out for itself. You can additionally specify an arbitrary number 16233of @samp{-s @var{section} @var{address}} pairs, to give an explicit 16234section name and base address for that section. You can specify any 16235@var{address} as an expression. 16236 16237The symbol table of the file @var{filename} is added to the symbol table 16238originally read with the @code{symbol-file} command. You can use the 16239@code{add-symbol-file} command any number of times; the new symbol data 16240thus read keeps adding to the old. To discard all old symbol data 16241instead, use the @code{symbol-file} command without any arguments. 16242 16243@cindex relocatable object files, reading symbols from 16244@cindex object files, relocatable, reading symbols from 16245@cindex reading symbols from relocatable object files 16246@cindex symbols, reading from relocatable object files 16247@cindex @file{.o} files, reading symbols from 16248Although @var{filename} is typically a shared library file, an 16249executable file, or some other object file which has been fully 16250relocated for loading into a process, you can also load symbolic 16251information from relocatable @file{.o} files, as long as: 16252 16253@itemize @bullet 16254@item 16255the file's symbolic information refers only to linker symbols defined in 16256that file, not to symbols defined by other object files, 16257@item 16258every section the file's symbolic information refers to has actually 16259been loaded into the inferior, as it appears in the file, and 16260@item 16261you can determine the address at which every section was loaded, and 16262provide these to the @code{add-symbol-file} command. 16263@end itemize 16264 16265@noindent 16266Some embedded operating systems, like Sun Chorus and VxWorks, can load 16267relocatable files into an already running program; such systems 16268typically make the requirements above easy to meet. However, it's 16269important to recognize that many native systems use complex link 16270procedures (@code{.linkonce} section factoring and C@t{++} constructor table 16271assembly, for example) that make the requirements difficult to meet. In 16272general, one cannot assume that using @code{add-symbol-file} to read a 16273relocatable object file's symbolic information will have the same effect 16274as linking the relocatable object file into the program in the normal 16275way. 16276 16277@code{add-symbol-file} does not repeat if you press @key{RET} after using it. 16278 16279@kindex add-symbol-file-from-memory 16280@cindex @code{syscall DSO} 16281@cindex load symbols from memory 16282@item add-symbol-file-from-memory @var{address} 16283Load symbols from the given @var{address} in a dynamically loaded 16284object file whose image is mapped directly into the inferior's memory. 16285For example, the Linux kernel maps a @code{syscall DSO} into each 16286process's address space; this DSO provides kernel-specific code for 16287some system calls. The argument can be any expression whose 16288evaluation yields the address of the file's shared object file header. 16289For this command to work, you must have used @code{symbol-file} or 16290@code{exec-file} commands in advance. 16291 16292@kindex add-shared-symbol-files 16293@kindex assf 16294@item add-shared-symbol-files @var{library-file} 16295@itemx assf @var{library-file} 16296The @code{add-shared-symbol-files} command can currently be used only 16297in the Cygwin build of @value{GDBN} on MS-Windows OS, where it is an 16298alias for the @code{dll-symbols} command (@pxref{Cygwin Native}). 16299@value{GDBN} automatically looks for shared libraries, however if 16300@value{GDBN} does not find yours, you can invoke 16301@code{add-shared-symbol-files}. It takes one argument: the shared 16302library's file name. @code{assf} is a shorthand alias for 16303@code{add-shared-symbol-files}. 16304 16305@kindex section 16306@item section @var{section} @var{addr} 16307The @code{section} command changes the base address of the named 16308@var{section} of the exec file to @var{addr}. This can be used if the 16309exec file does not contain section addresses, (such as in the 16310@code{a.out} format), or when the addresses specified in the file 16311itself are wrong. Each section must be changed separately. The 16312@code{info files} command, described below, lists all the sections and 16313their addresses. 16314 16315@kindex info files 16316@kindex info target 16317@item info files 16318@itemx info target 16319@code{info files} and @code{info target} are synonymous; both print the 16320current target (@pxref{Targets, ,Specifying a Debugging Target}), 16321including the names of the executable and core dump files currently in 16322use by @value{GDBN}, and the files from which symbols were loaded. The 16323command @code{help target} lists all possible targets rather than 16324current ones. 16325 16326@kindex maint info sections 16327@item maint info sections 16328Another command that can give you extra information about program sections 16329is @code{maint info sections}. In addition to the section information 16330displayed by @code{info files}, this command displays the flags and file 16331offset of each section in the executable and core dump files. In addition, 16332@code{maint info sections} provides the following command options (which 16333may be arbitrarily combined): 16334 16335@table @code 16336@item ALLOBJ 16337Display sections for all loaded object files, including shared libraries. 16338@item @var{sections} 16339Display info only for named @var{sections}. 16340@item @var{section-flags} 16341Display info only for sections for which @var{section-flags} are true. 16342The section flags that @value{GDBN} currently knows about are: 16343@table @code 16344@item ALLOC 16345Section will have space allocated in the process when loaded. 16346Set for all sections except those containing debug information. 16347@item LOAD 16348Section will be loaded from the file into the child process memory. 16349Set for pre-initialized code and data, clear for @code{.bss} sections. 16350@item RELOC 16351Section needs to be relocated before loading. 16352@item READONLY 16353Section cannot be modified by the child process. 16354@item CODE 16355Section contains executable code only. 16356@item DATA 16357Section contains data only (no executable code). 16358@item ROM 16359Section will reside in ROM. 16360@item CONSTRUCTOR 16361Section contains data for constructor/destructor lists. 16362@item HAS_CONTENTS 16363Section is not empty. 16364@item NEVER_LOAD 16365An instruction to the linker to not output the section. 16366@item COFF_SHARED_LIBRARY 16367A notification to the linker that the section contains 16368COFF shared library information. 16369@item IS_COMMON 16370Section contains common symbols. 16371@end table 16372@end table 16373@kindex set trust-readonly-sections 16374@cindex read-only sections 16375@item set trust-readonly-sections on 16376Tell @value{GDBN} that readonly sections in your object file 16377really are read-only (i.e.@: that their contents will not change). 16378In that case, @value{GDBN} can fetch values from these sections 16379out of the object file, rather than from the target program. 16380For some targets (notably embedded ones), this can be a significant 16381enhancement to debugging performance. 16382 16383The default is off. 16384 16385@item set trust-readonly-sections off 16386Tell @value{GDBN} not to trust readonly sections. This means that 16387the contents of the section might change while the program is running, 16388and must therefore be fetched from the target when needed. 16389 16390@item show trust-readonly-sections 16391Show the current setting of trusting readonly sections. 16392@end table 16393 16394All file-specifying commands allow both absolute and relative file names 16395as arguments. @value{GDBN} always converts the file name to an absolute file 16396name and remembers it that way. 16397 16398@cindex shared libraries 16399@anchor{Shared Libraries} 16400@value{GDBN} supports @sc{gnu}/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, 16401and IBM RS/6000 AIX shared libraries. 16402 16403On MS-Windows @value{GDBN} must be linked with the Expat library to support 16404shared libraries. @xref{Expat}. 16405 16406@value{GDBN} automatically loads symbol definitions from shared libraries 16407when you use the @code{run} command, or when you examine a core file. 16408(Before you issue the @code{run} command, @value{GDBN} does not understand 16409references to a function in a shared library, however---unless you are 16410debugging a core file). 16411 16412On HP-UX, if the program loads a library explicitly, @value{GDBN} 16413automatically loads the symbols at the time of the @code{shl_load} call. 16414 16415@c FIXME: some @value{GDBN} release may permit some refs to undef 16416@c FIXME...symbols---eg in a break cmd---assuming they are from a shared 16417@c FIXME...lib; check this from time to time when updating manual 16418 16419There are times, however, when you may wish to not automatically load 16420symbol definitions from shared libraries, such as when they are 16421particularly large or there are many of them. 16422 16423To control the automatic loading of shared library symbols, use the 16424commands: 16425 16426@table @code 16427@kindex set auto-solib-add 16428@item set auto-solib-add @var{mode} 16429If @var{mode} is @code{on}, symbols from all shared object libraries 16430will be loaded automatically when the inferior begins execution, you 16431attach to an independently started inferior, or when the dynamic linker 16432informs @value{GDBN} that a new library has been loaded. If @var{mode} 16433is @code{off}, symbols must be loaded manually, using the 16434@code{sharedlibrary} command. The default value is @code{on}. 16435 16436@cindex memory used for symbol tables 16437If your program uses lots of shared libraries with debug info that 16438takes large amounts of memory, you can decrease the @value{GDBN} 16439memory footprint by preventing it from automatically loading the 16440symbols from shared libraries. To that end, type @kbd{set 16441auto-solib-add off} before running the inferior, then load each 16442library whose debug symbols you do need with @kbd{sharedlibrary 16443@var{regexp}}, where @var{regexp} is a regular expression that matches 16444the libraries whose symbols you want to be loaded. 16445 16446@kindex show auto-solib-add 16447@item show auto-solib-add 16448Display the current autoloading mode. 16449@end table 16450 16451@cindex load shared library 16452To explicitly load shared library symbols, use the @code{sharedlibrary} 16453command: 16454 16455@table @code 16456@kindex info sharedlibrary 16457@kindex info share 16458@item info share @var{regex} 16459@itemx info sharedlibrary @var{regex} 16460Print the names of the shared libraries which are currently loaded 16461that match @var{regex}. If @var{regex} is omitted then print 16462all shared libraries that are loaded. 16463 16464@kindex sharedlibrary 16465@kindex share 16466@item sharedlibrary @var{regex} 16467@itemx share @var{regex} 16468Load shared object library symbols for files matching a 16469Unix regular expression. 16470As with files loaded automatically, it only loads shared libraries 16471required by your program for a core file or after typing @code{run}. If 16472@var{regex} is omitted all shared libraries required by your program are 16473loaded. 16474 16475@item nosharedlibrary 16476@kindex nosharedlibrary 16477@cindex unload symbols from shared libraries 16478Unload all shared object library symbols. This discards all symbols 16479that have been loaded from all shared libraries. Symbols from shared 16480libraries that were loaded by explicit user requests are not 16481discarded. 16482@end table 16483 16484Sometimes you may wish that @value{GDBN} stops and gives you control 16485when any of shared library events happen. The best way to do this is 16486to use @code{catch load} and @code{catch unload} (@pxref{Set 16487Catchpoints}). 16488 16489@value{GDBN} also supports the the @code{set stop-on-solib-events} 16490command for this. This command exists for historical reasons. It is 16491less useful than setting a catchpoint, because it does not allow for 16492conditions or commands as a catchpoint does. 16493 16494@table @code 16495@item set stop-on-solib-events 16496@kindex set stop-on-solib-events 16497This command controls whether @value{GDBN} should give you control 16498when the dynamic linker notifies it about some shared library event. 16499The most common event of interest is loading or unloading of a new 16500shared library. 16501 16502@item show stop-on-solib-events 16503@kindex show stop-on-solib-events 16504Show whether @value{GDBN} stops and gives you control when shared 16505library events happen. 16506@end table 16507 16508Shared libraries are also supported in many cross or remote debugging 16509configurations. @value{GDBN} needs to have access to the target's libraries; 16510this can be accomplished either by providing copies of the libraries 16511on the host system, or by asking @value{GDBN} to automatically retrieve the 16512libraries from the target. If copies of the target libraries are 16513provided, they need to be the same as the target libraries, although the 16514copies on the target can be stripped as long as the copies on the host are 16515not. 16516 16517@cindex where to look for shared libraries 16518For remote debugging, you need to tell @value{GDBN} where the target 16519libraries are, so that it can load the correct copies---otherwise, it 16520may try to load the host's libraries. @value{GDBN} has two variables 16521to specify the search directories for target libraries. 16522 16523@table @code 16524@cindex prefix for shared library file names 16525@cindex system root, alternate 16526@kindex set solib-absolute-prefix 16527@kindex set sysroot 16528@item set sysroot @var{path} 16529Use @var{path} as the system root for the program being debugged. Any 16530absolute shared library paths will be prefixed with @var{path}; many 16531runtime loaders store the absolute paths to the shared library in the 16532target program's memory. If you use @code{set sysroot} to find shared 16533libraries, they need to be laid out in the same way that they are on 16534the target, with e.g.@: a @file{/lib} and @file{/usr/lib} hierarchy 16535under @var{path}. 16536 16537If @var{path} starts with the sequence @file{remote:}, @value{GDBN} will 16538retrieve the target libraries from the remote system. This is only 16539supported when using a remote target that supports the @code{remote get} 16540command (@pxref{File Transfer,,Sending files to a remote system}). 16541The part of @var{path} following the initial @file{remote:} 16542(if present) is used as system root prefix on the remote file system. 16543@footnote{If you want to specify a local system root using a directory 16544that happens to be named @file{remote:}, you need to use some equivalent 16545variant of the name like @file{./remote:}.} 16546 16547For targets with an MS-DOS based filesystem, such as MS-Windows and 16548SymbianOS, @value{GDBN} tries prefixing a few variants of the target 16549absolute file name with @var{path}. But first, on Unix hosts, 16550@value{GDBN} converts all backslash directory separators into forward 16551slashes, because the backslash is not a directory separator on Unix: 16552 16553@smallexample 16554 c:\foo\bar.dll @result{} c:/foo/bar.dll 16555@end smallexample 16556 16557Then, @value{GDBN} attempts prefixing the target file name with 16558@var{path}, and looks for the resulting file name in the host file 16559system: 16560 16561@smallexample 16562 c:/foo/bar.dll @result{} /path/to/sysroot/c:/foo/bar.dll 16563@end smallexample 16564 16565If that does not find the shared library, @value{GDBN} tries removing 16566the @samp{:} character from the drive spec, both for convenience, and, 16567for the case of the host file system not supporting file names with 16568colons: 16569 16570@smallexample 16571 c:/foo/bar.dll @result{} /path/to/sysroot/c/foo/bar.dll 16572@end smallexample 16573 16574This makes it possible to have a system root that mirrors a target 16575with more than one drive. E.g., you may want to setup your local 16576copies of the target system shared libraries like so (note @samp{c} vs 16577@samp{z}): 16578 16579@smallexample 16580 @file{/path/to/sysroot/c/sys/bin/foo.dll} 16581 @file{/path/to/sysroot/c/sys/bin/bar.dll} 16582 @file{/path/to/sysroot/z/sys/bin/bar.dll} 16583@end smallexample 16584 16585@noindent 16586and point the system root at @file{/path/to/sysroot}, so that 16587@value{GDBN} can find the correct copies of both 16588@file{c:\sys\bin\foo.dll}, and @file{z:\sys\bin\bar.dll}. 16589 16590If that still does not find the shared library, @value{GDBN} tries 16591removing the whole drive spec from the target file name: 16592 16593@smallexample 16594 c:/foo/bar.dll @result{} /path/to/sysroot/foo/bar.dll 16595@end smallexample 16596 16597This last lookup makes it possible to not care about the drive name, 16598if you don't want or need to. 16599 16600The @code{set solib-absolute-prefix} command is an alias for @code{set 16601sysroot}. 16602 16603@cindex default system root 16604@cindex @samp{--with-sysroot} 16605You can set the default system root by using the configure-time 16606@samp{--with-sysroot} option. If the system root is inside 16607@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or 16608@samp{--exec-prefix}), then the default system root will be updated 16609automatically if the installed @value{GDBN} is moved to a new 16610location. 16611 16612@kindex show sysroot 16613@item show sysroot 16614Display the current shared library prefix. 16615 16616@kindex set solib-search-path 16617@item set solib-search-path @var{path} 16618If this variable is set, @var{path} is a colon-separated list of 16619directories to search for shared libraries. @samp{solib-search-path} 16620is used after @samp{sysroot} fails to locate the library, or if the 16621path to the library is relative instead of absolute. If you want to 16622use @samp{solib-search-path} instead of @samp{sysroot}, be sure to set 16623@samp{sysroot} to a nonexistent directory to prevent @value{GDBN} from 16624finding your host's libraries. @samp{sysroot} is preferred; setting 16625it to a nonexistent directory may interfere with automatic loading 16626of shared library symbols. 16627 16628@kindex show solib-search-path 16629@item show solib-search-path 16630Display the current shared library search path. 16631 16632@cindex DOS file-name semantics of file names. 16633@kindex set target-file-system-kind (unix|dos-based|auto) 16634@kindex show target-file-system-kind 16635@item set target-file-system-kind @var{kind} 16636Set assumed file system kind for target reported file names. 16637 16638Shared library file names as reported by the target system may not 16639make sense as is on the system @value{GDBN} is running on. For 16640example, when remote debugging a target that has MS-DOS based file 16641system semantics, from a Unix host, the target may be reporting to 16642@value{GDBN} a list of loaded shared libraries with file names such as 16643@file{c:\Windows\kernel32.dll}. On Unix hosts, there's no concept of 16644drive letters, so the @samp{c:\} prefix is not normally understood as 16645indicating an absolute file name, and neither is the backslash 16646normally considered a directory separator character. In that case, 16647the native file system would interpret this whole absolute file name 16648as a relative file name with no directory components. This would make 16649it impossible to point @value{GDBN} at a copy of the remote target's 16650shared libraries on the host using @code{set sysroot}, and impractical 16651with @code{set solib-search-path}. Setting 16652@code{target-file-system-kind} to @code{dos-based} tells @value{GDBN} 16653to interpret such file names similarly to how the target would, and to 16654map them to file names valid on @value{GDBN}'s native file system 16655semantics. The value of @var{kind} can be @code{"auto"}, in addition 16656to one of the supported file system kinds. In that case, @value{GDBN} 16657tries to determine the appropriate file system variant based on the 16658current target's operating system (@pxref{ABI, ,Configuring the 16659Current ABI}). The supported file system settings are: 16660 16661@table @code 16662@item unix 16663Instruct @value{GDBN} to assume the target file system is of Unix 16664kind. Only file names starting the forward slash (@samp{/}) character 16665are considered absolute, and the directory separator character is also 16666the forward slash. 16667 16668@item dos-based 16669Instruct @value{GDBN} to assume the target file system is DOS based. 16670File names starting with either a forward slash, or a drive letter 16671followed by a colon (e.g., @samp{c:}), are considered absolute, and 16672both the slash (@samp{/}) and the backslash (@samp{\\}) characters are 16673considered directory separators. 16674 16675@item auto 16676Instruct @value{GDBN} to use the file system kind associated with the 16677target operating system (@pxref{ABI, ,Configuring the Current ABI}). 16678This is the default. 16679@end table 16680@end table 16681 16682@cindex file name canonicalization 16683@cindex base name differences 16684When processing file names provided by the user, @value{GDBN} 16685frequently needs to compare them to the file names recorded in the 16686program's debug info. Normally, @value{GDBN} compares just the 16687@dfn{base names} of the files as strings, which is reasonably fast 16688even for very large programs. (The base name of a file is the last 16689portion of its name, after stripping all the leading directories.) 16690This shortcut in comparison is based upon the assumption that files 16691cannot have more than one base name. This is usually true, but 16692references to files that use symlinks or similar filesystem 16693facilities violate that assumption. If your program records files 16694using such facilities, or if you provide file names to @value{GDBN} 16695using symlinks etc., you can set @code{basenames-may-differ} to 16696@code{true} to instruct @value{GDBN} to completely canonicalize each 16697pair of file names it needs to compare. This will make file-name 16698comparisons accurate, but at a price of a significant slowdown. 16699 16700@table @code 16701@item set basenames-may-differ 16702@kindex set basenames-may-differ 16703Set whether a source file may have multiple base names. 16704 16705@item show basenames-may-differ 16706@kindex show basenames-may-differ 16707Show whether a source file may have multiple base names. 16708@end table 16709 16710@node Separate Debug Files 16711@section Debugging Information in Separate Files 16712@cindex separate debugging information files 16713@cindex debugging information in separate files 16714@cindex @file{.debug} subdirectories 16715@cindex debugging information directory, global 16716@cindex global debugging information directories 16717@cindex build ID, and separate debugging files 16718@cindex @file{.build-id} directory 16719 16720@value{GDBN} allows you to put a program's debugging information in a 16721file separate from the executable itself, in a way that allows 16722@value{GDBN} to find and load the debugging information automatically. 16723Since debugging information can be very large---sometimes larger 16724than the executable code itself---some systems distribute debugging 16725information for their executables in separate files, which users can 16726install only when they need to debug a problem. 16727 16728@value{GDBN} supports two ways of specifying the separate debug info 16729file: 16730 16731@itemize @bullet 16732@item 16733The executable contains a @dfn{debug link} that specifies the name of 16734the separate debug info file. The separate debug file's name is 16735usually @file{@var{executable}.debug}, where @var{executable} is the 16736name of the corresponding executable file without leading directories 16737(e.g., @file{ls.debug} for @file{/usr/bin/ls}). In addition, the 16738debug link specifies a 32-bit @dfn{Cyclic Redundancy Check} (CRC) 16739checksum for the debug file, which @value{GDBN} uses to validate that 16740the executable and the debug file came from the same build. 16741 16742@item 16743The executable contains a @dfn{build ID}, a unique bit string that is 16744also present in the corresponding debug info file. (This is supported 16745only on some operating systems, notably those which use the ELF format 16746for binary files and the @sc{gnu} Binutils.) For more details about 16747this feature, see the description of the @option{--build-id} 16748command-line option in @ref{Options, , Command Line Options, ld.info, 16749The GNU Linker}. The debug info file's name is not specified 16750explicitly by the build ID, but can be computed from the build ID, see 16751below. 16752@end itemize 16753 16754Depending on the way the debug info file is specified, @value{GDBN} 16755uses two different methods of looking for the debug file: 16756 16757@itemize @bullet 16758@item 16759For the ``debug link'' method, @value{GDBN} looks up the named file in 16760the directory of the executable file, then in a subdirectory of that 16761directory named @file{.debug}, and finally under each one of the global debug 16762directories, in a subdirectory whose name is identical to the leading 16763directories of the executable's absolute file name. 16764 16765@item 16766For the ``build ID'' method, @value{GDBN} looks in the 16767@file{.build-id} subdirectory of each one of the global debug directories for 16768a file named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the 16769first 2 hex characters of the build ID bit string, and @var{nnnnnnnn} 16770are the rest of the bit string. (Real build ID strings are 32 or more 16771hex characters, not 10.) 16772@end itemize 16773 16774So, for example, suppose you ask @value{GDBN} to debug 16775@file{/usr/bin/ls}, which has a debug link that specifies the 16776file @file{ls.debug}, and a build ID whose value in hex is 16777@code{abcdef1234}. If the list of the global debug directories includes 16778@file{/usr/lib/debug}, then @value{GDBN} will look for the following 16779debug information files, in the indicated order: 16780 16781@itemize @minus 16782@item 16783@file{/usr/lib/debug/.build-id/ab/cdef1234.debug} 16784@item 16785@file{/usr/bin/ls.debug} 16786@item 16787@file{/usr/bin/.debug/ls.debug} 16788@item 16789@file{/usr/lib/debug/usr/bin/ls.debug}. 16790@end itemize 16791 16792@anchor{debug-file-directory} 16793Global debugging info directories default to what is set by @value{GDBN} 16794configure option @option{--with-separate-debug-dir}. During @value{GDBN} run 16795you can also set the global debugging info directories, and view the list 16796@value{GDBN} is currently using. 16797 16798@table @code 16799 16800@kindex set debug-file-directory 16801@item set debug-file-directory @var{directories} 16802Set the directories which @value{GDBN} searches for separate debugging 16803information files to @var{directory}. Multiple path components can be set 16804concatenating them by a path separator. 16805 16806@kindex show debug-file-directory 16807@item show debug-file-directory 16808Show the directories @value{GDBN} searches for separate debugging 16809information files. 16810 16811@end table 16812 16813@cindex @code{.gnu_debuglink} sections 16814@cindex debug link sections 16815A debug link is a special section of the executable file named 16816@code{.gnu_debuglink}. The section must contain: 16817 16818@itemize 16819@item 16820A filename, with any leading directory components removed, followed by 16821a zero byte, 16822@item 16823zero to three bytes of padding, as needed to reach the next four-byte 16824boundary within the section, and 16825@item 16826a four-byte CRC checksum, stored in the same endianness used for the 16827executable file itself. The checksum is computed on the debugging 16828information file's full contents by the function given below, passing 16829zero as the @var{crc} argument. 16830@end itemize 16831 16832Any executable file format can carry a debug link, as long as it can 16833contain a section named @code{.gnu_debuglink} with the contents 16834described above. 16835 16836@cindex @code{.note.gnu.build-id} sections 16837@cindex build ID sections 16838The build ID is a special section in the executable file (and in other 16839ELF binary files that @value{GDBN} may consider). This section is 16840often named @code{.note.gnu.build-id}, but that name is not mandatory. 16841It contains unique identification for the built files---the ID remains 16842the same across multiple builds of the same build tree. The default 16843algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the 16844content for the build ID string. The same section with an identical 16845value is present in the original built binary with symbols, in its 16846stripped variant, and in the separate debugging information file. 16847 16848The debugging information file itself should be an ordinary 16849executable, containing a full set of linker symbols, sections, and 16850debugging information. The sections of the debugging information file 16851should have the same names, addresses, and sizes as the original file, 16852but they need not contain any data---much like a @code{.bss} section 16853in an ordinary executable. 16854 16855The @sc{gnu} binary utilities (Binutils) package includes the 16856@samp{objcopy} utility that can produce 16857the separated executable / debugging information file pairs using the 16858following commands: 16859 16860@smallexample 16861@kbd{objcopy --only-keep-debug foo foo.debug} 16862@kbd{strip -g foo} 16863@end smallexample 16864 16865@noindent 16866These commands remove the debugging 16867information from the executable file @file{foo} and place it in the file 16868@file{foo.debug}. You can use the first, second or both methods to link the 16869two files: 16870 16871@itemize @bullet 16872@item 16873The debug link method needs the following additional command to also leave 16874behind a debug link in @file{foo}: 16875 16876@smallexample 16877@kbd{objcopy --add-gnu-debuglink=foo.debug foo} 16878@end smallexample 16879 16880Ulrich Drepper's @file{elfutils} package, starting with version 0.53, contains 16881a version of the @code{strip} command such that the command @kbd{strip foo -f 16882foo.debug} has the same functionality as the two @code{objcopy} commands and 16883the @code{ln -s} command above, together. 16884 16885@item 16886Build ID gets embedded into the main executable using @code{ld --build-id} or 16887the @value{NGCC} counterpart @code{gcc -Wl,--build-id}. Build ID support plus 16888compatibility fixes for debug files separation are present in @sc{gnu} binary 16889utilities (Binutils) package since version 2.18. 16890@end itemize 16891 16892@noindent 16893 16894@cindex CRC algorithm definition 16895The CRC used in @code{.gnu_debuglink} is the CRC-32 defined in 16896IEEE 802.3 using the polynomial: 16897 16898@c TexInfo requires naked braces for multi-digit exponents for Tex 16899@c output, but this causes HTML output to barf. HTML has to be set using 16900@c raw commands. So we end up having to specify this equation in 2 16901@c different ways! 16902@ifhtml 16903@display 16904@html 16905 <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> 16906 + <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 16907@end html 16908@end display 16909@end ifhtml 16910@ifnothtml 16911@display 16912 @math{x^{32} + x^{26} + x^{23} + x^{22} + x^{16} + x^{12} + x^{11}} 16913 @math{+ x^{10} + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1} 16914@end display 16915@end ifnothtml 16916 16917The function is computed byte at a time, taking the least 16918significant bit of each byte first. The initial pattern 16919@code{0xffffffff} is used, to ensure leading zeros affect the CRC and 16920the final result is inverted to ensure trailing zeros also affect the 16921CRC. 16922 16923@emph{Note:} This is the same CRC polynomial as used in handling the 16924@dfn{Remote Serial Protocol} @code{qCRC} packet (@pxref{Remote Protocol, 16925, @value{GDBN} Remote Serial Protocol}). However in the 16926case of the Remote Serial Protocol, the CRC is computed @emph{most} 16927significant bit first, and the result is not inverted, so trailing 16928zeros have no effect on the CRC value. 16929 16930To complete the description, we show below the code of the function 16931which produces the CRC used in @code{.gnu_debuglink}. Inverting the 16932initially supplied @code{crc} argument means that an initial call to 16933this function passing in zero will start computing the CRC using 16934@code{0xffffffff}. 16935 16936@kindex gnu_debuglink_crc32 16937@smallexample 16938unsigned long 16939gnu_debuglink_crc32 (unsigned long crc, 16940 unsigned char *buf, size_t len) 16941@{ 16942 static const unsigned long crc32_table[256] = 16943 @{ 16944 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, 16945 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, 16946 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, 16947 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, 16948 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, 16949 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, 16950 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, 16951 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, 16952 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, 16953 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, 16954 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, 16955 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, 16956 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, 16957 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, 16958 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, 16959 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, 16960 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, 16961 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, 16962 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, 16963 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, 16964 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, 16965 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, 16966 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, 16967 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, 16968 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, 16969 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, 16970 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, 16971 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, 16972 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, 16973 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, 16974 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, 16975 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, 16976 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, 16977 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, 16978 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, 16979 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, 16980 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, 16981 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, 16982 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, 16983 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, 16984 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, 16985 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, 16986 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, 16987 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, 16988 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, 16989 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, 16990 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, 16991 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, 16992 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, 16993 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, 16994 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, 16995 0x2d02ef8d 16996 @}; 16997 unsigned char *end; 16998 16999 crc = ~crc & 0xffffffff; 17000 for (end = buf + len; buf < end; ++buf) 17001 crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); 17002 return ~crc & 0xffffffff; 17003@} 17004@end smallexample 17005 17006@noindent 17007This computation does not apply to the ``build ID'' method. 17008 17009@node MiniDebugInfo 17010@section Debugging information in a special section 17011@cindex separate debug sections 17012@cindex @samp{.gnu_debugdata} section 17013 17014Some systems ship pre-built executables and libraries that have a 17015special @samp{.gnu_debugdata} section. This feature is called 17016@dfn{MiniDebugInfo}. This section holds an LZMA-compressed object and 17017is used to supply extra symbols for backtraces. 17018 17019The intent of this section is to provide extra minimal debugging 17020information for use in simple backtraces. It is not intended to be a 17021replacement for full separate debugging information (@pxref{Separate 17022Debug Files}). The example below shows the intended use; however, 17023@value{GDBN} does not currently put restrictions on what sort of 17024debugging information might be included in the section. 17025 17026@value{GDBN} has support for this extension. If the section exists, 17027then it is used provided that no other source of debugging information 17028can be found, and that @value{GDBN} was configured with LZMA support. 17029 17030This section can be easily created using @command{objcopy} and other 17031standard utilities: 17032 17033@smallexample 17034# Extract the dynamic symbols from the main binary, there is no need 17035# to also have these in the normal symbol table 17036nm -D @var{binary} --format=posix --defined-only \ 17037 | awk '@{ print $1 @}' | sort > dynsyms 17038 17039# Extract all the text (i.e. function) symbols from the debuginfo . 17040nm @var{binary} --format=posix --defined-only \ 17041 | awk '@{ if ($2 == "T" || $2 == "t") print $1 @}' \ 17042 | sort > funcsyms 17043 17044# Keep all the function symbols not already in the dynamic symbol 17045# table. 17046comm -13 dynsyms funcsyms > keep_symbols 17047 17048# Copy the full debuginfo, keeping only a minimal set of symbols and 17049# removing some unnecessary sections. 17050objcopy -S --remove-section .gdb_index --remove-section .comment \ 17051 --keep-symbols=keep_symbols @var{binary} mini_debuginfo 17052 17053# Inject the compressed data into the .gnu_debugdata section of the 17054# original binary. 17055xz mini_debuginfo 17056objcopy --add-section .gnu_debugdata=mini_debuginfo.xz @var{binary} 17057@end smallexample 17058 17059@node Index Files 17060@section Index Files Speed Up @value{GDBN} 17061@cindex index files 17062@cindex @samp{.gdb_index} section 17063 17064When @value{GDBN} finds a symbol file, it scans the symbols in the 17065file in order to construct an internal symbol table. This lets most 17066@value{GDBN} operations work quickly---at the cost of a delay early 17067on. For large programs, this delay can be quite lengthy, so 17068@value{GDBN} provides a way to build an index, which speeds up 17069startup. 17070 17071The index is stored as a section in the symbol file. @value{GDBN} can 17072write the index to a file, then you can put it into the symbol file 17073using @command{objcopy}. 17074 17075To create an index file, use the @code{save gdb-index} command: 17076 17077@table @code 17078@item save gdb-index @var{directory} 17079@kindex save gdb-index 17080Create an index file for each symbol file currently known by 17081@value{GDBN}. Each file is named after its corresponding symbol file, 17082with @samp{.gdb-index} appended, and is written into the given 17083@var{directory}. 17084@end table 17085 17086Once you have created an index file you can merge it into your symbol 17087file, here named @file{symfile}, using @command{objcopy}: 17088 17089@smallexample 17090$ objcopy --add-section .gdb_index=symfile.gdb-index \ 17091 --set-section-flags .gdb_index=readonly symfile symfile 17092@end smallexample 17093 17094@value{GDBN} will normally ignore older versions of @file{.gdb_index} 17095sections that have been deprecated. Usually they are deprecated because 17096they are missing a new feature or have performance issues. 17097To tell @value{GDBN} to use a deprecated index section anyway 17098specify @code{set use-deprecated-index-sections on}. 17099The default is @code{off}. 17100This can speed up startup, but may result in some functionality being lost. 17101@xref{Index Section Format}. 17102 17103@emph{Warning:} Setting @code{use-deprecated-index-sections} to @code{on} 17104must be done before gdb reads the file. The following will not work: 17105 17106@smallexample 17107$ gdb -ex "set use-deprecated-index-sections on" <program> 17108@end smallexample 17109 17110Instead you must do, for example, 17111 17112@smallexample 17113$ gdb -iex "set use-deprecated-index-sections on" <program> 17114@end smallexample 17115 17116There are currently some limitation on indices. They only work when 17117for DWARF debugging information, not stabs. And, they do not 17118currently work for programs using Ada. 17119 17120@node Symbol Errors 17121@section Errors Reading Symbol Files 17122 17123While reading a symbol file, @value{GDBN} occasionally encounters problems, 17124such as symbol types it does not recognize, or known bugs in compiler 17125output. By default, @value{GDBN} does not notify you of such problems, since 17126they are relatively common and primarily of interest to people 17127debugging compilers. If you are interested in seeing information 17128about ill-constructed symbol tables, you can either ask @value{GDBN} to print 17129only one message about each such type of problem, no matter how many 17130times the problem occurs; or you can ask @value{GDBN} to print more messages, 17131to see how many times the problems occur, with the @code{set 17132complaints} command (@pxref{Messages/Warnings, ,Optional Warnings and 17133Messages}). 17134 17135The messages currently printed, and their meanings, include: 17136 17137@table @code 17138@item inner block not inside outer block in @var{symbol} 17139 17140The symbol information shows where symbol scopes begin and end 17141(such as at the start of a function or a block of statements). This 17142error indicates that an inner scope block is not fully contained 17143in its outer scope blocks. 17144 17145@value{GDBN} circumvents the problem by treating the inner block as if it had 17146the same scope as the outer block. In the error message, @var{symbol} 17147may be shown as ``@code{(don't know)}'' if the outer block is not a 17148function. 17149 17150@item block at @var{address} out of order 17151 17152The symbol information for symbol scope blocks should occur in 17153order of increasing addresses. This error indicates that it does not 17154do so. 17155 17156@value{GDBN} does not circumvent this problem, and has trouble 17157locating symbols in the source file whose symbols it is reading. (You 17158can often determine what source file is affected by specifying 17159@code{set verbose on}. @xref{Messages/Warnings, ,Optional Warnings and 17160Messages}.) 17161 17162@item bad block start address patched 17163 17164The symbol information for a symbol scope block has a start address 17165smaller than the address of the preceding source line. This is known 17166to occur in the SunOS 4.1.1 (and earlier) C compiler. 17167 17168@value{GDBN} circumvents the problem by treating the symbol scope block as 17169starting on the previous source line. 17170 17171@item bad string table offset in symbol @var{n} 17172 17173@cindex foo 17174Symbol number @var{n} contains a pointer into the string table which is 17175larger than the size of the string table. 17176 17177@value{GDBN} circumvents the problem by considering the symbol to have the 17178name @code{foo}, which may cause other problems if many symbols end up 17179with this name. 17180 17181@item unknown symbol type @code{0x@var{nn}} 17182 17183The symbol information contains new data types that @value{GDBN} does 17184not yet know how to read. @code{0x@var{nn}} is the symbol type of the 17185uncomprehended information, in hexadecimal. 17186 17187@value{GDBN} circumvents the error by ignoring this symbol information. 17188This usually allows you to debug your program, though certain symbols 17189are not accessible. If you encounter such a problem and feel like 17190debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint 17191on @code{complain}, then go up to the function @code{read_dbx_symtab} 17192and examine @code{*bufp} to see the symbol. 17193 17194@item stub type has NULL name 17195 17196@value{GDBN} could not find the full definition for a struct or class. 17197 17198@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{} 17199The symbol information for a C@t{++} member function is missing some 17200information that recent versions of the compiler should have output for 17201it. 17202 17203@item info mismatch between compiler and debugger 17204 17205@value{GDBN} could not parse a type specification output by the compiler. 17206 17207@end table 17208 17209@node Data Files 17210@section GDB Data Files 17211 17212@cindex prefix for data files 17213@value{GDBN} will sometimes read an auxiliary data file. These files 17214are kept in a directory known as the @dfn{data directory}. 17215 17216You can set the data directory's name, and view the name @value{GDBN} 17217is currently using. 17218 17219@table @code 17220@kindex set data-directory 17221@item set data-directory @var{directory} 17222Set the directory which @value{GDBN} searches for auxiliary data files 17223to @var{directory}. 17224 17225@kindex show data-directory 17226@item show data-directory 17227Show the directory @value{GDBN} searches for auxiliary data files. 17228@end table 17229 17230@cindex default data directory 17231@cindex @samp{--with-gdb-datadir} 17232You can set the default data directory by using the configure-time 17233@samp{--with-gdb-datadir} option. If the data directory is inside 17234@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or 17235@samp{--exec-prefix}), then the default data directory will be updated 17236automatically if the installed @value{GDBN} is moved to a new 17237location. 17238 17239The data directory may also be specified with the 17240@code{--data-directory} command line option. 17241@xref{Mode Options}. 17242 17243@node Targets 17244@chapter Specifying a Debugging Target 17245 17246@cindex debugging target 17247A @dfn{target} is the execution environment occupied by your program. 17248 17249Often, @value{GDBN} runs in the same host environment as your program; 17250in that case, the debugging target is specified as a side effect when 17251you use the @code{file} or @code{core} commands. When you need more 17252flexibility---for example, running @value{GDBN} on a physically separate 17253host, or controlling a standalone system over a serial port or a 17254realtime system over a TCP/IP connection---you can use the @code{target} 17255command to specify one of the target types configured for @value{GDBN} 17256(@pxref{Target Commands, ,Commands for Managing Targets}). 17257 17258@cindex target architecture 17259It is possible to build @value{GDBN} for several different @dfn{target 17260architectures}. When @value{GDBN} is built like that, you can choose 17261one of the available architectures with the @kbd{set architecture} 17262command. 17263 17264@table @code 17265@kindex set architecture 17266@kindex show architecture 17267@item set architecture @var{arch} 17268This command sets the current target architecture to @var{arch}. The 17269value of @var{arch} can be @code{"auto"}, in addition to one of the 17270supported architectures. 17271 17272@item show architecture 17273Show the current target architecture. 17274 17275@item set processor 17276@itemx processor 17277@kindex set processor 17278@kindex show processor 17279These are alias commands for, respectively, @code{set architecture} 17280and @code{show architecture}. 17281@end table 17282 17283@menu 17284* Active Targets:: Active targets 17285* Target Commands:: Commands for managing targets 17286* Byte Order:: Choosing target byte order 17287@end menu 17288 17289@node Active Targets 17290@section Active Targets 17291 17292@cindex stacking targets 17293@cindex active targets 17294@cindex multiple targets 17295 17296There are multiple classes of targets such as: processes, executable files or 17297recording sessions. Core files belong to the process class, making core file 17298and process mutually exclusive. Otherwise, @value{GDBN} can work concurrently 17299on multiple active targets, one in each class. This allows you to (for 17300example) start a process and inspect its activity, while still having access to 17301the executable file after the process finishes. Or if you start process 17302recording (@pxref{Reverse Execution}) and @code{reverse-step} there, you are 17303presented a virtual layer of the recording target, while the process target 17304remains stopped at the chronologically last point of the process execution. 17305 17306Use the @code{core-file} and @code{exec-file} commands to select a new core 17307file or executable target (@pxref{Files, ,Commands to Specify Files}). To 17308specify as a target a process that is already running, use the @code{attach} 17309command (@pxref{Attach, ,Debugging an Already-running Process}). 17310 17311@node Target Commands 17312@section Commands for Managing Targets 17313 17314@table @code 17315@item target @var{type} @var{parameters} 17316Connects the @value{GDBN} host environment to a target machine or 17317process. A target is typically a protocol for talking to debugging 17318facilities. You use the argument @var{type} to specify the type or 17319protocol of the target machine. 17320 17321Further @var{parameters} are interpreted by the target protocol, but 17322typically include things like device names or host names to connect 17323with, process numbers, and baud rates. 17324 17325The @code{target} command does not repeat if you press @key{RET} again 17326after executing the command. 17327 17328@kindex help target 17329@item help target 17330Displays the names of all targets available. To display targets 17331currently selected, use either @code{info target} or @code{info files} 17332(@pxref{Files, ,Commands to Specify Files}). 17333 17334@item help target @var{name} 17335Describe a particular target, including any parameters necessary to 17336select it. 17337 17338@kindex set gnutarget 17339@item set gnutarget @var{args} 17340@value{GDBN} uses its own library BFD to read your files. @value{GDBN} 17341knows whether it is reading an @dfn{executable}, 17342a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format 17343with the @code{set gnutarget} command. Unlike most @code{target} commands, 17344with @code{gnutarget} the @code{target} refers to a program, not a machine. 17345 17346@quotation 17347@emph{Warning:} To specify a file format with @code{set gnutarget}, 17348you must know the actual BFD name. 17349@end quotation 17350 17351@noindent 17352@xref{Files, , Commands to Specify Files}. 17353 17354@kindex show gnutarget 17355@item show gnutarget 17356Use the @code{show gnutarget} command to display what file format 17357@code{gnutarget} is set to read. If you have not set @code{gnutarget}, 17358@value{GDBN} will determine the file format for each file automatically, 17359and @code{show gnutarget} displays @samp{The current BFD target is "auto"}. 17360@end table 17361 17362@cindex common targets 17363Here are some common targets (available, or not, depending on the GDB 17364configuration): 17365 17366@table @code 17367@kindex target 17368@item target exec @var{program} 17369@cindex executable file target 17370An executable file. @samp{target exec @var{program}} is the same as 17371@samp{exec-file @var{program}}. 17372 17373@item target core @var{filename} 17374@cindex core dump file target 17375A core dump file. @samp{target core @var{filename}} is the same as 17376@samp{core-file @var{filename}}. 17377 17378@item target remote @var{medium} 17379@cindex remote target 17380A remote system connected to @value{GDBN} via a serial line or network 17381connection. This command tells @value{GDBN} to use its own remote 17382protocol over @var{medium} for debugging. @xref{Remote Debugging}. 17383 17384For example, if you have a board connected to @file{/dev/ttya} on the 17385machine running @value{GDBN}, you could say: 17386 17387@smallexample 17388target remote /dev/ttya 17389@end smallexample 17390 17391@code{target remote} supports the @code{load} command. This is only 17392useful if you have some other way of getting the stub to the target 17393system, and you can put it somewhere in memory where it won't get 17394clobbered by the download. 17395 17396@item target sim @r{[}@var{simargs}@r{]} @dots{} 17397@cindex built-in simulator target 17398Builtin CPU simulator. @value{GDBN} includes simulators for most architectures. 17399In general, 17400@smallexample 17401 target sim 17402 load 17403 run 17404@end smallexample 17405@noindent 17406works; however, you cannot assume that a specific memory map, device 17407drivers, or even basic I/O is available, although some simulators do 17408provide these. For info about any processor-specific simulator details, 17409see the appropriate section in @ref{Embedded Processors, ,Embedded 17410Processors}. 17411 17412@end table 17413 17414Some configurations may include these targets as well: 17415 17416@table @code 17417 17418@item target nrom @var{dev} 17419@cindex NetROM ROM emulator target 17420NetROM ROM emulator. This target only supports downloading. 17421 17422@end table 17423 17424Different targets are available on different configurations of @value{GDBN}; 17425your configuration may have more or fewer targets. 17426 17427Many remote targets require you to download the executable's code once 17428you've successfully established a connection. You may wish to control 17429various aspects of this process. 17430 17431@table @code 17432 17433@item set hash 17434@kindex set hash@r{, for remote monitors} 17435@cindex hash mark while downloading 17436This command controls whether a hash mark @samp{#} is displayed while 17437downloading a file to the remote monitor. If on, a hash mark is 17438displayed after each S-record is successfully downloaded to the 17439monitor. 17440 17441@item show hash 17442@kindex show hash@r{, for remote monitors} 17443Show the current status of displaying the hash mark. 17444 17445@item set debug monitor 17446@kindex set debug monitor 17447@cindex display remote monitor communications 17448Enable or disable display of communications messages between 17449@value{GDBN} and the remote monitor. 17450 17451@item show debug monitor 17452@kindex show debug monitor 17453Show the current status of displaying communications between 17454@value{GDBN} and the remote monitor. 17455@end table 17456 17457@table @code 17458 17459@kindex load @var{filename} 17460@item load @var{filename} 17461@anchor{load} 17462Depending on what remote debugging facilities are configured into 17463@value{GDBN}, the @code{load} command may be available. Where it exists, it 17464is meant to make @var{filename} (an executable) available for debugging 17465on the remote system---by downloading, or dynamic linking, for example. 17466@code{load} also records the @var{filename} symbol table in @value{GDBN}, like 17467the @code{add-symbol-file} command. 17468 17469If your @value{GDBN} does not have a @code{load} command, attempting to 17470execute it gets the error message ``@code{You can't do that when your 17471target is @dots{}}'' 17472 17473The file is loaded at whatever address is specified in the executable. 17474For some object file formats, you can specify the load address when you 17475link the program; for other formats, like a.out, the object file format 17476specifies a fixed address. 17477@c FIXME! This would be a good place for an xref to the GNU linker doc. 17478 17479Depending on the remote side capabilities, @value{GDBN} may be able to 17480load programs into flash memory. 17481 17482@code{load} does not repeat if you press @key{RET} again after using it. 17483@end table 17484 17485@node Byte Order 17486@section Choosing Target Byte Order 17487 17488@cindex choosing target byte order 17489@cindex target byte order 17490 17491Some types of processors, such as the @acronym{MIPS}, PowerPC, and Renesas SH, 17492offer the ability to run either big-endian or little-endian byte 17493orders. Usually the executable or symbol will include a bit to 17494designate the endian-ness, and you will not need to worry about 17495which to use. However, you may still find it useful to adjust 17496@value{GDBN}'s idea of processor endian-ness manually. 17497 17498@table @code 17499@kindex set endian 17500@item set endian big 17501Instruct @value{GDBN} to assume the target is big-endian. 17502 17503@item set endian little 17504Instruct @value{GDBN} to assume the target is little-endian. 17505 17506@item set endian auto 17507Instruct @value{GDBN} to use the byte order associated with the 17508executable. 17509 17510@item show endian 17511Display @value{GDBN}'s current idea of the target byte order. 17512 17513@end table 17514 17515Note that these commands merely adjust interpretation of symbolic 17516data on the host, and that they have absolutely no effect on the 17517target system. 17518 17519 17520@node Remote Debugging 17521@chapter Debugging Remote Programs 17522@cindex remote debugging 17523 17524If you are trying to debug a program running on a machine that cannot run 17525@value{GDBN} in the usual way, it is often useful to use remote debugging. 17526For example, you might use remote debugging on an operating system kernel, 17527or on a small system which does not have a general purpose operating system 17528powerful enough to run a full-featured debugger. 17529 17530Some configurations of @value{GDBN} have special serial or TCP/IP interfaces 17531to make this work with particular debugging targets. In addition, 17532@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN}, 17533but not specific to any particular target system) which you can use if you 17534write the remote stubs---the code that runs on the remote system to 17535communicate with @value{GDBN}. 17536 17537Other remote targets may be available in your 17538configuration of @value{GDBN}; use @code{help target} to list them. 17539 17540@menu 17541* Connecting:: Connecting to a remote target 17542* File Transfer:: Sending files to a remote system 17543* Server:: Using the gdbserver program 17544* Remote Configuration:: Remote configuration 17545* Remote Stub:: Implementing a remote stub 17546@end menu 17547 17548@node Connecting 17549@section Connecting to a Remote Target 17550 17551On the @value{GDBN} host machine, you will need an unstripped copy of 17552your program, since @value{GDBN} needs symbol and debugging information. 17553Start up @value{GDBN} as usual, using the name of the local copy of your 17554program as the first argument. 17555 17556@cindex @code{target remote} 17557@value{GDBN} can communicate with the target over a serial line, or 17558over an @acronym{IP} network using @acronym{TCP} or @acronym{UDP}. In 17559each case, @value{GDBN} uses the same protocol for debugging your 17560program; only the medium carrying the debugging packets varies. The 17561@code{target remote} command establishes a connection to the target. 17562Its arguments indicate which medium to use: 17563 17564@table @code 17565 17566@item target remote @var{serial-device} 17567@cindex serial line, @code{target remote} 17568Use @var{serial-device} to communicate with the target. For example, 17569to use a serial line connected to the device named @file{/dev/ttyb}: 17570 17571@smallexample 17572target remote /dev/ttyb 17573@end smallexample 17574 17575If you're using a serial line, you may want to give @value{GDBN} the 17576@w{@samp{--baud}} option, or use the @code{set remotebaud} command 17577(@pxref{Remote Configuration, set remotebaud}) before the 17578@code{target} command. 17579 17580@item target remote @code{@var{host}:@var{port}} 17581@itemx target remote @code{tcp:@var{host}:@var{port}} 17582@cindex @acronym{TCP} port, @code{target remote} 17583Debug using a @acronym{TCP} connection to @var{port} on @var{host}. 17584The @var{host} may be either a host name or a numeric @acronym{IP} 17585address; @var{port} must be a decimal number. The @var{host} could be 17586the target machine itself, if it is directly connected to the net, or 17587it might be a terminal server which in turn has a serial line to the 17588target. 17589 17590For example, to connect to port 2828 on a terminal server named 17591@code{manyfarms}: 17592 17593@smallexample 17594target remote manyfarms:2828 17595@end smallexample 17596 17597If your remote target is actually running on the same machine as your 17598debugger session (e.g.@: a simulator for your target running on the 17599same host), you can omit the hostname. For example, to connect to 17600port 1234 on your local machine: 17601 17602@smallexample 17603target remote :1234 17604@end smallexample 17605@noindent 17606 17607Note that the colon is still required here. 17608 17609@item target remote @code{udp:@var{host}:@var{port}} 17610@cindex @acronym{UDP} port, @code{target remote} 17611Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to 17612connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}: 17613 17614@smallexample 17615target remote udp:manyfarms:2828 17616@end smallexample 17617 17618When using a @acronym{UDP} connection for remote debugging, you should 17619keep in mind that the `U' stands for ``Unreliable''. @acronym{UDP} 17620can silently drop packets on busy or unreliable networks, which will 17621cause havoc with your debugging session. 17622 17623@item target remote | @var{command} 17624@cindex pipe, @code{target remote} to 17625Run @var{command} in the background and communicate with it using a 17626pipe. The @var{command} is a shell command, to be parsed and expanded 17627by the system's command shell, @code{/bin/sh}; it should expect remote 17628protocol packets on its standard input, and send replies on its 17629standard output. You could use this to run a stand-alone simulator 17630that speaks the remote debugging protocol, to make net connections 17631using programs like @code{ssh}, or for other similar tricks. 17632 17633If @var{command} closes its standard output (perhaps by exiting), 17634@value{GDBN} will try to send it a @code{SIGTERM} signal. (If the 17635program has already exited, this will have no effect.) 17636 17637@end table 17638 17639Once the connection has been established, you can use all the usual 17640commands to examine and change data. The remote program is already 17641running; you can use @kbd{step} and @kbd{continue}, and you do not 17642need to use @kbd{run}. 17643 17644@cindex interrupting remote programs 17645@cindex remote programs, interrupting 17646Whenever @value{GDBN} is waiting for the remote program, if you type the 17647interrupt character (often @kbd{Ctrl-c}), @value{GDBN} attempts to stop the 17648program. This may or may not succeed, depending in part on the hardware 17649and the serial drivers the remote system uses. If you type the 17650interrupt character once again, @value{GDBN} displays this prompt: 17651 17652@smallexample 17653Interrupted while waiting for the program. 17654Give up (and stop debugging it)? (y or n) 17655@end smallexample 17656 17657If you type @kbd{y}, @value{GDBN} abandons the remote debugging session. 17658(If you decide you want to try again later, you can use @samp{target 17659remote} again to connect once more.) If you type @kbd{n}, @value{GDBN} 17660goes back to waiting. 17661 17662@table @code 17663@kindex detach (remote) 17664@item detach 17665When you have finished debugging the remote program, you can use the 17666@code{detach} command to release it from @value{GDBN} control. 17667Detaching from the target normally resumes its execution, but the results 17668will depend on your particular remote stub. After the @code{detach} 17669command, @value{GDBN} is free to connect to another target. 17670 17671@kindex disconnect 17672@item disconnect 17673The @code{disconnect} command behaves like @code{detach}, except that 17674the target is generally not resumed. It will wait for @value{GDBN} 17675(this instance or another one) to connect and continue debugging. After 17676the @code{disconnect} command, @value{GDBN} is again free to connect to 17677another target. 17678 17679@cindex send command to remote monitor 17680@cindex extend @value{GDBN} for remote targets 17681@cindex add new commands for external monitor 17682@kindex monitor 17683@item monitor @var{cmd} 17684This command allows you to send arbitrary commands directly to the 17685remote monitor. Since @value{GDBN} doesn't care about the commands it 17686sends like this, this command is the way to extend @value{GDBN}---you 17687can add new commands that only the external monitor will understand 17688and implement. 17689@end table 17690 17691@node File Transfer 17692@section Sending files to a remote system 17693@cindex remote target, file transfer 17694@cindex file transfer 17695@cindex sending files to remote systems 17696 17697Some remote targets offer the ability to transfer files over the same 17698connection used to communicate with @value{GDBN}. This is convenient 17699for targets accessible through other means, e.g.@: @sc{gnu}/Linux systems 17700running @code{gdbserver} over a network interface. For other targets, 17701e.g.@: embedded devices with only a single serial port, this may be 17702the only way to upload or download files. 17703 17704Not all remote targets support these commands. 17705 17706@table @code 17707@kindex remote put 17708@item remote put @var{hostfile} @var{targetfile} 17709Copy file @var{hostfile} from the host system (the machine running 17710@value{GDBN}) to @var{targetfile} on the target system. 17711 17712@kindex remote get 17713@item remote get @var{targetfile} @var{hostfile} 17714Copy file @var{targetfile} from the target system to @var{hostfile} 17715on the host system. 17716 17717@kindex remote delete 17718@item remote delete @var{targetfile} 17719Delete @var{targetfile} from the target system. 17720 17721@end table 17722 17723@node Server 17724@section Using the @code{gdbserver} Program 17725 17726@kindex gdbserver 17727@cindex remote connection without stubs 17728@code{gdbserver} is a control program for Unix-like systems, which 17729allows you to connect your program with a remote @value{GDBN} via 17730@code{target remote}---but without linking in the usual debugging stub. 17731 17732@code{gdbserver} is not a complete replacement for the debugging stubs, 17733because it requires essentially the same operating-system facilities 17734that @value{GDBN} itself does. In fact, a system that can run 17735@code{gdbserver} to connect to a remote @value{GDBN} could also run 17736@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless, 17737because it is a much smaller program than @value{GDBN} itself. It is 17738also easier to port than all of @value{GDBN}, so you may be able to get 17739started more quickly on a new system by using @code{gdbserver}. 17740Finally, if you develop code for real-time systems, you may find that 17741the tradeoffs involved in real-time operation make it more convenient to 17742do as much development work as possible on another system, for example 17743by cross-compiling. You can use @code{gdbserver} to make a similar 17744choice for debugging. 17745 17746@value{GDBN} and @code{gdbserver} communicate via either a serial line 17747or a TCP connection, using the standard @value{GDBN} remote serial 17748protocol. 17749 17750@quotation 17751@emph{Warning:} @code{gdbserver} does not have any built-in security. 17752Do not run @code{gdbserver} connected to any public network; a 17753@value{GDBN} connection to @code{gdbserver} provides access to the 17754target system with the same privileges as the user running 17755@code{gdbserver}. 17756@end quotation 17757 17758@subsection Running @code{gdbserver} 17759@cindex arguments, to @code{gdbserver} 17760@cindex @code{gdbserver}, command-line arguments 17761 17762Run @code{gdbserver} on the target system. You need a copy of the 17763program you want to debug, including any libraries it requires. 17764@code{gdbserver} does not need your program's symbol table, so you can 17765strip the program if necessary to save space. @value{GDBN} on the host 17766system does all the symbol handling. 17767 17768To use the server, you must tell it how to communicate with @value{GDBN}; 17769the name of your program; and the arguments for your program. The usual 17770syntax is: 17771 17772@smallexample 17773target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ] 17774@end smallexample 17775 17776@var{comm} is either a device name (to use a serial line), or a TCP 17777hostname and portnumber, or @code{-} or @code{stdio} to use 17778stdin/stdout of @code{gdbserver}. 17779For example, to debug Emacs with the argument 17780@samp{foo.txt} and communicate with @value{GDBN} over the serial port 17781@file{/dev/com1}: 17782 17783@smallexample 17784target> gdbserver /dev/com1 emacs foo.txt 17785@end smallexample 17786 17787@code{gdbserver} waits passively for the host @value{GDBN} to communicate 17788with it. 17789 17790To use a TCP connection instead of a serial line: 17791 17792@smallexample 17793target> gdbserver host:2345 emacs foo.txt 17794@end smallexample 17795 17796The only difference from the previous example is the first argument, 17797specifying that you are communicating with the host @value{GDBN} via 17798TCP. The @samp{host:2345} argument means that @code{gdbserver} is to 17799expect a TCP connection from machine @samp{host} to local TCP port 2345. 17800(Currently, the @samp{host} part is ignored.) You can choose any number 17801you want for the port number as long as it does not conflict with any 17802TCP ports already in use on the target system (for example, @code{23} is 17803reserved for @code{telnet}).@footnote{If you choose a port number that 17804conflicts with another service, @code{gdbserver} prints an error message 17805and exits.} You must use the same port number with the host @value{GDBN} 17806@code{target remote} command. 17807 17808The @code{stdio} connection is useful when starting @code{gdbserver} 17809with ssh: 17810 17811@smallexample 17812(gdb) target remote | ssh -T hostname gdbserver - hello 17813@end smallexample 17814 17815The @samp{-T} option to ssh is provided because we don't need a remote pty, 17816and we don't want escape-character handling. Ssh does this by default when 17817a command is provided, the flag is provided to make it explicit. 17818You could elide it if you want to. 17819 17820Programs started with stdio-connected gdbserver have @file{/dev/null} for 17821@code{stdin}, and @code{stdout},@code{stderr} are sent back to gdb for 17822display through a pipe connected to gdbserver. 17823Both @code{stdout} and @code{stderr} use the same pipe. 17824 17825@subsubsection Attaching to a Running Program 17826@cindex attach to a program, @code{gdbserver} 17827@cindex @option{--attach}, @code{gdbserver} option 17828 17829On some targets, @code{gdbserver} can also attach to running programs. 17830This is accomplished via the @code{--attach} argument. The syntax is: 17831 17832@smallexample 17833target> gdbserver --attach @var{comm} @var{pid} 17834@end smallexample 17835 17836@var{pid} is the process ID of a currently running process. It isn't necessary 17837to point @code{gdbserver} at a binary for the running process. 17838 17839@pindex pidof 17840You can debug processes by name instead of process ID if your target has the 17841@code{pidof} utility: 17842 17843@smallexample 17844target> gdbserver --attach @var{comm} `pidof @var{program}` 17845@end smallexample 17846 17847In case more than one copy of @var{program} is running, or @var{program} 17848has multiple threads, most versions of @code{pidof} support the 17849@code{-s} option to only return the first process ID. 17850 17851@subsubsection Multi-Process Mode for @code{gdbserver} 17852@cindex @code{gdbserver}, multiple processes 17853@cindex multiple processes with @code{gdbserver} 17854 17855When you connect to @code{gdbserver} using @code{target remote}, 17856@code{gdbserver} debugs the specified program only once. When the 17857program exits, or you detach from it, @value{GDBN} closes the connection 17858and @code{gdbserver} exits. 17859 17860If you connect using @kbd{target extended-remote}, @code{gdbserver} 17861enters multi-process mode. When the debugged program exits, or you 17862detach from it, @value{GDBN} stays connected to @code{gdbserver} even 17863though no program is running. The @code{run} and @code{attach} 17864commands instruct @code{gdbserver} to run or attach to a new program. 17865The @code{run} command uses @code{set remote exec-file} (@pxref{set 17866remote exec-file}) to select the program to run. Command line 17867arguments are supported, except for wildcard expansion and I/O 17868redirection (@pxref{Arguments}). 17869 17870@cindex @option{--multi}, @code{gdbserver} option 17871To start @code{gdbserver} without supplying an initial command to run 17872or process ID to attach, use the @option{--multi} command line option. 17873Then you can connect using @kbd{target extended-remote} and start 17874the program you want to debug. 17875 17876In multi-process mode @code{gdbserver} does not automatically exit unless you 17877use the option @option{--once}. You can terminate it by using 17878@code{monitor exit} (@pxref{Monitor Commands for gdbserver}). Note that the 17879conditions under which @code{gdbserver} terminates depend on how @value{GDBN} 17880connects to it (@kbd{target remote} or @kbd{target extended-remote}). The 17881@option{--multi} option to @code{gdbserver} has no influence on that. 17882 17883@subsubsection TCP port allocation lifecycle of @code{gdbserver} 17884 17885This section applies only when @code{gdbserver} is run to listen on a TCP port. 17886 17887@code{gdbserver} normally terminates after all of its debugged processes have 17888terminated in @kbd{target remote} mode. On the other hand, for @kbd{target 17889extended-remote}, @code{gdbserver} stays running even with no processes left. 17890@value{GDBN} normally terminates the spawned debugged process on its exit, 17891which normally also terminates @code{gdbserver} in the @kbd{target remote} 17892mode. Therefore, when the connection drops unexpectedly, and @value{GDBN} 17893cannot ask @code{gdbserver} to kill its debugged processes, @code{gdbserver} 17894stays running even in the @kbd{target remote} mode. 17895 17896When @code{gdbserver} stays running, @value{GDBN} can connect to it again later. 17897Such reconnecting is useful for features like @ref{disconnected tracing}. For 17898completeness, at most one @value{GDBN} can be connected at a time. 17899 17900@cindex @option{--once}, @code{gdbserver} option 17901By default, @code{gdbserver} keeps the listening TCP port open, so that 17902additional connections are possible. However, if you start @code{gdbserver} 17903with the @option{--once} option, it will stop listening for any further 17904connection attempts after connecting to the first @value{GDBN} session. This 17905means no further connections to @code{gdbserver} will be possible after the 17906first one. It also means @code{gdbserver} will terminate after the first 17907connection with remote @value{GDBN} has closed, even for unexpectedly closed 17908connections and even in the @kbd{target extended-remote} mode. The 17909@option{--once} option allows reusing the same port number for connecting to 17910multiple instances of @code{gdbserver} running on the same host, since each 17911instance closes its port after the first connection. 17912 17913@subsubsection Other Command-Line Arguments for @code{gdbserver} 17914 17915@cindex @option{--debug}, @code{gdbserver} option 17916The @option{--debug} option tells @code{gdbserver} to display extra 17917status information about the debugging process. 17918@cindex @option{--remote-debug}, @code{gdbserver} option 17919The @option{--remote-debug} option tells @code{gdbserver} to display 17920remote protocol debug output. These options are intended for 17921@code{gdbserver} development and for bug reports to the developers. 17922 17923@cindex @option{--wrapper}, @code{gdbserver} option 17924The @option{--wrapper} option specifies a wrapper to launch programs 17925for debugging. The option should be followed by the name of the 17926wrapper, then any command-line arguments to pass to the wrapper, then 17927@kbd{--} indicating the end of the wrapper arguments. 17928 17929@code{gdbserver} runs the specified wrapper program with a combined 17930command line including the wrapper arguments, then the name of the 17931program to debug, then any arguments to the program. The wrapper 17932runs until it executes your program, and then @value{GDBN} gains control. 17933 17934You can use any program that eventually calls @code{execve} with 17935its arguments as a wrapper. Several standard Unix utilities do 17936this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending 17937with @code{exec "$@@"} will also work. 17938 17939For example, you can use @code{env} to pass an environment variable to 17940the debugged program, without setting the variable in @code{gdbserver}'s 17941environment: 17942 17943@smallexample 17944$ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog 17945@end smallexample 17946 17947@subsection Connecting to @code{gdbserver} 17948 17949Run @value{GDBN} on the host system. 17950 17951First make sure you have the necessary symbol files. Load symbols for 17952your application using the @code{file} command before you connect. Use 17953@code{set sysroot} to locate target libraries (unless your @value{GDBN} 17954was compiled with the correct sysroot using @code{--with-sysroot}). 17955 17956The symbol file and target libraries must exactly match the executable 17957and libraries on the target, with one exception: the files on the host 17958system should not be stripped, even if the files on the target system 17959are. Mismatched or missing files will lead to confusing results 17960during debugging. On @sc{gnu}/Linux targets, mismatched or missing 17961files may also prevent @code{gdbserver} from debugging multi-threaded 17962programs. 17963 17964Connect to your target (@pxref{Connecting,,Connecting to a Remote Target}). 17965For TCP connections, you must start up @code{gdbserver} prior to using 17966the @code{target remote} command. Otherwise you may get an error whose 17967text depends on the host system, but which usually looks something like 17968@samp{Connection refused}. Don't use the @code{load} 17969command in @value{GDBN} when using @code{gdbserver}, since the program is 17970already on the target. 17971 17972@subsection Monitor Commands for @code{gdbserver} 17973@cindex monitor commands, for @code{gdbserver} 17974@anchor{Monitor Commands for gdbserver} 17975 17976During a @value{GDBN} session using @code{gdbserver}, you can use the 17977@code{monitor} command to send special requests to @code{gdbserver}. 17978Here are the available commands. 17979 17980@table @code 17981@item monitor help 17982List the available monitor commands. 17983 17984@item monitor set debug 0 17985@itemx monitor set debug 1 17986Disable or enable general debugging messages. 17987 17988@item monitor set remote-debug 0 17989@itemx monitor set remote-debug 1 17990Disable or enable specific debugging messages associated with the remote 17991protocol (@pxref{Remote Protocol}). 17992 17993@item monitor set libthread-db-search-path [PATH] 17994@cindex gdbserver, search path for @code{libthread_db} 17995When this command is issued, @var{path} is a colon-separated list of 17996directories to search for @code{libthread_db} (@pxref{Threads,,set 17997libthread-db-search-path}). If you omit @var{path}, 17998@samp{libthread-db-search-path} will be reset to its default value. 17999 18000The special entry @samp{$pdir} for @samp{libthread-db-search-path} is 18001not supported in @code{gdbserver}. 18002 18003@item monitor exit 18004Tell gdbserver to exit immediately. This command should be followed by 18005@code{disconnect} to close the debugging session. @code{gdbserver} will 18006detach from any attached processes and kill any processes it created. 18007Use @code{monitor exit} to terminate @code{gdbserver} at the end 18008of a multi-process mode debug session. 18009 18010@end table 18011 18012@subsection Tracepoints support in @code{gdbserver} 18013@cindex tracepoints support in @code{gdbserver} 18014 18015On some targets, @code{gdbserver} supports tracepoints, fast 18016tracepoints and static tracepoints. 18017 18018For fast or static tracepoints to work, a special library called the 18019@dfn{in-process agent} (IPA), must be loaded in the inferior process. 18020This library is built and distributed as an integral part of 18021@code{gdbserver}. In addition, support for static tracepoints 18022requires building the in-process agent library with static tracepoints 18023support. At present, the UST (LTTng Userspace Tracer, 18024@url{http://lttng.org/ust}) tracing engine is supported. This support 18025is automatically available if UST development headers are found in the 18026standard include path when @code{gdbserver} is built, or if 18027@code{gdbserver} was explicitly configured using @option{--with-ust} 18028to point at such headers. You can explicitly disable the support 18029using @option{--with-ust=no}. 18030 18031There are several ways to load the in-process agent in your program: 18032 18033@table @code 18034@item Specifying it as dependency at link time 18035 18036You can link your program dynamically with the in-process agent 18037library. On most systems, this is accomplished by adding 18038@code{-linproctrace} to the link command. 18039 18040@item Using the system's preloading mechanisms 18041 18042You can force loading the in-process agent at startup time by using 18043your system's support for preloading shared libraries. Many Unixes 18044support the concept of preloading user defined libraries. In most 18045cases, you do that by specifying @code{LD_PRELOAD=libinproctrace.so} 18046in the environment. See also the description of @code{gdbserver}'s 18047@option{--wrapper} command line option. 18048 18049@item Using @value{GDBN} to force loading the agent at run time 18050 18051On some systems, you can force the inferior to load a shared library, 18052by calling a dynamic loader function in the inferior that takes care 18053of dynamically looking up and loading a shared library. On most Unix 18054systems, the function is @code{dlopen}. You'll use the @code{call} 18055command for that. For example: 18056 18057@smallexample 18058(@value{GDBP}) call dlopen ("libinproctrace.so", ...) 18059@end smallexample 18060 18061Note that on most Unix systems, for the @code{dlopen} function to be 18062available, the program needs to be linked with @code{-ldl}. 18063@end table 18064 18065On systems that have a userspace dynamic loader, like most Unix 18066systems, when you connect to @code{gdbserver} using @code{target 18067remote}, you'll find that the program is stopped at the dynamic 18068loader's entry point, and no shared library has been loaded in the 18069program's address space yet, including the in-process agent. In that 18070case, before being able to use any of the fast or static tracepoints 18071features, you need to let the loader run and load the shared 18072libraries. The simplest way to do that is to run the program to the 18073main procedure. E.g., if debugging a C or C@t{++} program, start 18074@code{gdbserver} like so: 18075 18076@smallexample 18077$ gdbserver :9999 myprogram 18078@end smallexample 18079 18080Start GDB and connect to @code{gdbserver} like so, and run to main: 18081 18082@smallexample 18083$ gdb myprogram 18084(@value{GDBP}) target remote myhost:9999 180850x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2 18086(@value{GDBP}) b main 18087(@value{GDBP}) continue 18088@end smallexample 18089 18090The in-process tracing agent library should now be loaded into the 18091process; you can confirm it with the @code{info sharedlibrary} 18092command, which will list @file{libinproctrace.so} as loaded in the 18093process. You are now ready to install fast tracepoints, list static 18094tracepoint markers, probe static tracepoints markers, and start 18095tracing. 18096 18097@node Remote Configuration 18098@section Remote Configuration 18099 18100@kindex set remote 18101@kindex show remote 18102This section documents the configuration options available when 18103debugging remote programs. For the options related to the File I/O 18104extensions of the remote protocol, see @ref{system, 18105system-call-allowed}. 18106 18107@table @code 18108@item set remoteaddresssize @var{bits} 18109@cindex address size for remote targets 18110@cindex bits in remote address 18111Set the maximum size of address in a memory packet to the specified 18112number of bits. @value{GDBN} will mask off the address bits above 18113that number, when it passes addresses to the remote target. The 18114default value is the number of bits in the target's address. 18115 18116@item show remoteaddresssize 18117Show the current value of remote address size in bits. 18118 18119@item set remotebaud @var{n} 18120@cindex baud rate for remote targets 18121Set the baud rate for the remote serial I/O to @var{n} baud. The 18122value is used to set the speed of the serial port used for debugging 18123remote targets. 18124 18125@item show remotebaud 18126Show the current speed of the remote connection. 18127 18128@item set remotebreak 18129@cindex interrupt remote programs 18130@cindex BREAK signal instead of Ctrl-C 18131@anchor{set remotebreak} 18132If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote 18133when you type @kbd{Ctrl-c} to interrupt the program running 18134on the remote. If set to off, @value{GDBN} sends the @samp{Ctrl-C} 18135character instead. The default is off, since most remote systems 18136expect to see @samp{Ctrl-C} as the interrupt signal. 18137 18138@item show remotebreak 18139Show whether @value{GDBN} sends @code{BREAK} or @samp{Ctrl-C} to 18140interrupt the remote program. 18141 18142@item set remoteflow on 18143@itemx set remoteflow off 18144@kindex set remoteflow 18145Enable or disable hardware flow control (@code{RTS}/@code{CTS}) 18146on the serial port used to communicate to the remote target. 18147 18148@item show remoteflow 18149@kindex show remoteflow 18150Show the current setting of hardware flow control. 18151 18152@item set remotelogbase @var{base} 18153Set the base (a.k.a.@: radix) of logging serial protocol 18154communications to @var{base}. Supported values of @var{base} are: 18155@code{ascii}, @code{octal}, and @code{hex}. The default is 18156@code{ascii}. 18157 18158@item show remotelogbase 18159Show the current setting of the radix for logging remote serial 18160protocol. 18161 18162@item set remotelogfile @var{file} 18163@cindex record serial communications on file 18164Record remote serial communications on the named @var{file}. The 18165default is not to record at all. 18166 18167@item show remotelogfile. 18168Show the current setting of the file name on which to record the 18169serial communications. 18170 18171@item set remotetimeout @var{num} 18172@cindex timeout for serial communications 18173@cindex remote timeout 18174Set the timeout limit to wait for the remote target to respond to 18175@var{num} seconds. The default is 2 seconds. 18176 18177@item show remotetimeout 18178Show the current number of seconds to wait for the remote target 18179responses. 18180 18181@cindex limit hardware breakpoints and watchpoints 18182@cindex remote target, limit break- and watchpoints 18183@anchor{set remote hardware-watchpoint-limit} 18184@anchor{set remote hardware-breakpoint-limit} 18185@item set remote hardware-watchpoint-limit @var{limit} 18186@itemx set remote hardware-breakpoint-limit @var{limit} 18187Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or 18188watchpoints. A limit of -1, the default, is treated as unlimited. 18189 18190@cindex limit hardware watchpoints length 18191@cindex remote target, limit watchpoints length 18192@anchor{set remote hardware-watchpoint-length-limit} 18193@item set remote hardware-watchpoint-length-limit @var{limit} 18194Restrict @value{GDBN} to using @var{limit} bytes for the maximum length of 18195a remote hardware watchpoint. A limit of -1, the default, is treated 18196as unlimited. 18197 18198@item show remote hardware-watchpoint-length-limit 18199Show the current limit (in bytes) of the maximum length of 18200a remote hardware watchpoint. 18201 18202@item set remote exec-file @var{filename} 18203@itemx show remote exec-file 18204@anchor{set remote exec-file} 18205@cindex executable file, for remote target 18206Select the file used for @code{run} with @code{target 18207extended-remote}. This should be set to a filename valid on the 18208target system. If it is not set, the target will use a default 18209filename (e.g.@: the last program run). 18210 18211@item set remote interrupt-sequence 18212@cindex interrupt remote programs 18213@cindex select Ctrl-C, BREAK or BREAK-g 18214Allow the user to select one of @samp{Ctrl-C}, a @code{BREAK} or 18215@samp{BREAK-g} as the 18216sequence to the remote target in order to interrupt the execution. 18217@samp{Ctrl-C} is a default. Some system prefers @code{BREAK} which 18218is high level of serial line for some certain time. 18219Linux kernel prefers @samp{BREAK-g}, a.k.a Magic SysRq g. 18220It is @code{BREAK} signal followed by character @code{g}. 18221 18222@item show interrupt-sequence 18223Show which of @samp{Ctrl-C}, @code{BREAK} or @code{BREAK-g} 18224is sent by @value{GDBN} to interrupt the remote program. 18225@code{BREAK-g} is BREAK signal followed by @code{g} and 18226also known as Magic SysRq g. 18227 18228@item set remote interrupt-on-connect 18229@cindex send interrupt-sequence on start 18230Specify whether interrupt-sequence is sent to remote target when 18231@value{GDBN} connects to it. This is mostly needed when you debug 18232Linux kernel. Linux kernel expects @code{BREAK} followed by @code{g} 18233which is known as Magic SysRq g in order to connect @value{GDBN}. 18234 18235@item show interrupt-on-connect 18236Show whether interrupt-sequence is sent 18237to remote target when @value{GDBN} connects to it. 18238 18239@kindex set tcp 18240@kindex show tcp 18241@item set tcp auto-retry on 18242@cindex auto-retry, for remote TCP target 18243Enable auto-retry for remote TCP connections. This is useful if the remote 18244debugging agent is launched in parallel with @value{GDBN}; there is a race 18245condition because the agent may not become ready to accept the connection 18246before @value{GDBN} attempts to connect. When auto-retry is 18247enabled, if the initial attempt to connect fails, @value{GDBN} reattempts 18248to establish the connection using the timeout specified by 18249@code{set tcp connect-timeout}. 18250 18251@item set tcp auto-retry off 18252Do not auto-retry failed TCP connections. 18253 18254@item show tcp auto-retry 18255Show the current auto-retry setting. 18256 18257@item set tcp connect-timeout @var{seconds} 18258@cindex connection timeout, for remote TCP target 18259@cindex timeout, for remote target connection 18260Set the timeout for establishing a TCP connection to the remote target to 18261@var{seconds}. The timeout affects both polling to retry failed connections 18262(enabled by @code{set tcp auto-retry on}) and waiting for connections 18263that are merely slow to complete, and represents an approximate cumulative 18264value. 18265 18266@item show tcp connect-timeout 18267Show the current connection timeout setting. 18268@end table 18269 18270@cindex remote packets, enabling and disabling 18271The @value{GDBN} remote protocol autodetects the packets supported by 18272your debugging stub. If you need to override the autodetection, you 18273can use these commands to enable or disable individual packets. Each 18274packet can be set to @samp{on} (the remote target supports this 18275packet), @samp{off} (the remote target does not support this packet), 18276or @samp{auto} (detect remote target support for this packet). They 18277all default to @samp{auto}. For more information about each packet, 18278see @ref{Remote Protocol}. 18279 18280During normal use, you should not have to use any of these commands. 18281If you do, that may be a bug in your remote debugging stub, or a bug 18282in @value{GDBN}. You may want to report the problem to the 18283@value{GDBN} developers. 18284 18285For each packet @var{name}, the command to enable or disable the 18286packet is @code{set remote @var{name}-packet}. The available settings 18287are: 18288 18289@multitable @columnfractions 0.28 0.32 0.25 18290@item Command Name 18291@tab Remote Packet 18292@tab Related Features 18293 18294@item @code{fetch-register} 18295@tab @code{p} 18296@tab @code{info registers} 18297 18298@item @code{set-register} 18299@tab @code{P} 18300@tab @code{set} 18301 18302@item @code{binary-download} 18303@tab @code{X} 18304@tab @code{load}, @code{set} 18305 18306@item @code{read-aux-vector} 18307@tab @code{qXfer:auxv:read} 18308@tab @code{info auxv} 18309 18310@item @code{symbol-lookup} 18311@tab @code{qSymbol} 18312@tab Detecting multiple threads 18313 18314@item @code{attach} 18315@tab @code{vAttach} 18316@tab @code{attach} 18317 18318@item @code{verbose-resume} 18319@tab @code{vCont} 18320@tab Stepping or resuming multiple threads 18321 18322@item @code{run} 18323@tab @code{vRun} 18324@tab @code{run} 18325 18326@item @code{software-breakpoint} 18327@tab @code{Z0} 18328@tab @code{break} 18329 18330@item @code{hardware-breakpoint} 18331@tab @code{Z1} 18332@tab @code{hbreak} 18333 18334@item @code{write-watchpoint} 18335@tab @code{Z2} 18336@tab @code{watch} 18337 18338@item @code{read-watchpoint} 18339@tab @code{Z3} 18340@tab @code{rwatch} 18341 18342@item @code{access-watchpoint} 18343@tab @code{Z4} 18344@tab @code{awatch} 18345 18346@item @code{target-features} 18347@tab @code{qXfer:features:read} 18348@tab @code{set architecture} 18349 18350@item @code{library-info} 18351@tab @code{qXfer:libraries:read} 18352@tab @code{info sharedlibrary} 18353 18354@item @code{memory-map} 18355@tab @code{qXfer:memory-map:read} 18356@tab @code{info mem} 18357 18358@item @code{read-sdata-object} 18359@tab @code{qXfer:sdata:read} 18360@tab @code{print $_sdata} 18361 18362@item @code{read-spu-object} 18363@tab @code{qXfer:spu:read} 18364@tab @code{info spu} 18365 18366@item @code{write-spu-object} 18367@tab @code{qXfer:spu:write} 18368@tab @code{info spu} 18369 18370@item @code{read-siginfo-object} 18371@tab @code{qXfer:siginfo:read} 18372@tab @code{print $_siginfo} 18373 18374@item @code{write-siginfo-object} 18375@tab @code{qXfer:siginfo:write} 18376@tab @code{set $_siginfo} 18377 18378@item @code{threads} 18379@tab @code{qXfer:threads:read} 18380@tab @code{info threads} 18381 18382@item @code{get-thread-local-@*storage-address} 18383@tab @code{qGetTLSAddr} 18384@tab Displaying @code{__thread} variables 18385 18386@item @code{get-thread-information-block-address} 18387@tab @code{qGetTIBAddr} 18388@tab Display MS-Windows Thread Information Block. 18389 18390@item @code{search-memory} 18391@tab @code{qSearch:memory} 18392@tab @code{find} 18393 18394@item @code{supported-packets} 18395@tab @code{qSupported} 18396@tab Remote communications parameters 18397 18398@item @code{pass-signals} 18399@tab @code{QPassSignals} 18400@tab @code{handle @var{signal}} 18401 18402@item @code{program-signals} 18403@tab @code{QProgramSignals} 18404@tab @code{handle @var{signal}} 18405 18406@item @code{hostio-close-packet} 18407@tab @code{vFile:close} 18408@tab @code{remote get}, @code{remote put} 18409 18410@item @code{hostio-open-packet} 18411@tab @code{vFile:open} 18412@tab @code{remote get}, @code{remote put} 18413 18414@item @code{hostio-pread-packet} 18415@tab @code{vFile:pread} 18416@tab @code{remote get}, @code{remote put} 18417 18418@item @code{hostio-pwrite-packet} 18419@tab @code{vFile:pwrite} 18420@tab @code{remote get}, @code{remote put} 18421 18422@item @code{hostio-unlink-packet} 18423@tab @code{vFile:unlink} 18424@tab @code{remote delete} 18425 18426@item @code{hostio-readlink-packet} 18427@tab @code{vFile:readlink} 18428@tab Host I/O 18429 18430@item @code{noack-packet} 18431@tab @code{QStartNoAckMode} 18432@tab Packet acknowledgment 18433 18434@item @code{osdata} 18435@tab @code{qXfer:osdata:read} 18436@tab @code{info os} 18437 18438@item @code{query-attached} 18439@tab @code{qAttached} 18440@tab Querying remote process attach state. 18441 18442@item @code{trace-buffer-size} 18443@tab @code{QTBuffer:size} 18444@tab @code{set trace-buffer-size} 18445 18446@item @code{traceframe-info} 18447@tab @code{qXfer:traceframe-info:read} 18448@tab Traceframe info 18449 18450@item @code{install-in-trace} 18451@tab @code{InstallInTrace} 18452@tab Install tracepoint in tracing 18453 18454@item @code{disable-randomization} 18455@tab @code{QDisableRandomization} 18456@tab @code{set disable-randomization} 18457 18458@item @code{conditional-breakpoints-packet} 18459@tab @code{Z0 and Z1} 18460@tab @code{Support for target-side breakpoint condition evaluation} 18461@end multitable 18462 18463@node Remote Stub 18464@section Implementing a Remote Stub 18465 18466@cindex debugging stub, example 18467@cindex remote stub, example 18468@cindex stub example, remote debugging 18469The stub files provided with @value{GDBN} implement the target side of the 18470communication protocol, and the @value{GDBN} side is implemented in the 18471@value{GDBN} source file @file{remote.c}. Normally, you can simply allow 18472these subroutines to communicate, and ignore the details. (If you're 18473implementing your own stub file, you can still ignore the details: start 18474with one of the existing stub files. @file{sparc-stub.c} is the best 18475organized, and therefore the easiest to read.) 18476 18477@cindex remote serial debugging, overview 18478To debug a program running on another machine (the debugging 18479@dfn{target} machine), you must first arrange for all the usual 18480prerequisites for the program to run by itself. For example, for a C 18481program, you need: 18482 18483@enumerate 18484@item 18485A startup routine to set up the C runtime environment; these usually 18486have a name like @file{crt0}. The startup routine may be supplied by 18487your hardware supplier, or you may have to write your own. 18488 18489@item 18490A C subroutine library to support your program's 18491subroutine calls, notably managing input and output. 18492 18493@item 18494A way of getting your program to the other machine---for example, a 18495download program. These are often supplied by the hardware 18496manufacturer, but you may have to write your own from hardware 18497documentation. 18498@end enumerate 18499 18500The next step is to arrange for your program to use a serial port to 18501communicate with the machine where @value{GDBN} is running (the @dfn{host} 18502machine). In general terms, the scheme looks like this: 18503 18504@table @emph 18505@item On the host, 18506@value{GDBN} already understands how to use this protocol; when everything 18507else is set up, you can simply use the @samp{target remote} command 18508(@pxref{Targets,,Specifying a Debugging Target}). 18509 18510@item On the target, 18511you must link with your program a few special-purpose subroutines that 18512implement the @value{GDBN} remote serial protocol. The file containing these 18513subroutines is called a @dfn{debugging stub}. 18514 18515On certain remote targets, you can use an auxiliary program 18516@code{gdbserver} instead of linking a stub into your program. 18517@xref{Server,,Using the @code{gdbserver} Program}, for details. 18518@end table 18519 18520The debugging stub is specific to the architecture of the remote 18521machine; for example, use @file{sparc-stub.c} to debug programs on 18522@sc{sparc} boards. 18523 18524@cindex remote serial stub list 18525These working remote stubs are distributed with @value{GDBN}: 18526 18527@table @code 18528 18529@item i386-stub.c 18530@cindex @file{i386-stub.c} 18531@cindex Intel 18532@cindex i386 18533For Intel 386 and compatible architectures. 18534 18535@item m68k-stub.c 18536@cindex @file{m68k-stub.c} 18537@cindex Motorola 680x0 18538@cindex m680x0 18539For Motorola 680x0 architectures. 18540 18541@item sh-stub.c 18542@cindex @file{sh-stub.c} 18543@cindex Renesas 18544@cindex SH 18545For Renesas SH architectures. 18546 18547@item sparc-stub.c 18548@cindex @file{sparc-stub.c} 18549@cindex Sparc 18550For @sc{sparc} architectures. 18551 18552@item sparcl-stub.c 18553@cindex @file{sparcl-stub.c} 18554@cindex Fujitsu 18555@cindex SparcLite 18556For Fujitsu @sc{sparclite} architectures. 18557 18558@end table 18559 18560The @file{README} file in the @value{GDBN} distribution may list other 18561recently added stubs. 18562 18563@menu 18564* Stub Contents:: What the stub can do for you 18565* Bootstrapping:: What you must do for the stub 18566* Debug Session:: Putting it all together 18567@end menu 18568 18569@node Stub Contents 18570@subsection What the Stub Can Do for You 18571 18572@cindex remote serial stub 18573The debugging stub for your architecture supplies these three 18574subroutines: 18575 18576@table @code 18577@item set_debug_traps 18578@findex set_debug_traps 18579@cindex remote serial stub, initialization 18580This routine arranges for @code{handle_exception} to run when your 18581program stops. You must call this subroutine explicitly in your 18582program's startup code. 18583 18584@item handle_exception 18585@findex handle_exception 18586@cindex remote serial stub, main routine 18587This is the central workhorse, but your program never calls it 18588explicitly---the setup code arranges for @code{handle_exception} to 18589run when a trap is triggered. 18590 18591@code{handle_exception} takes control when your program stops during 18592execution (for example, on a breakpoint), and mediates communications 18593with @value{GDBN} on the host machine. This is where the communications 18594protocol is implemented; @code{handle_exception} acts as the @value{GDBN} 18595representative on the target machine. It begins by sending summary 18596information on the state of your program, then continues to execute, 18597retrieving and transmitting any information @value{GDBN} needs, until you 18598execute a @value{GDBN} command that makes your program resume; at that point, 18599@code{handle_exception} returns control to your own code on the target 18600machine. 18601 18602@item breakpoint 18603@cindex @code{breakpoint} subroutine, remote 18604Use this auxiliary subroutine to make your program contain a 18605breakpoint. Depending on the particular situation, this may be the only 18606way for @value{GDBN} to get control. For instance, if your target 18607machine has some sort of interrupt button, you won't need to call this; 18608pressing the interrupt button transfers control to 18609@code{handle_exception}---in effect, to @value{GDBN}. On some machines, 18610simply receiving characters on the serial port may also trigger a trap; 18611again, in that situation, you don't need to call @code{breakpoint} from 18612your own program---simply running @samp{target remote} from the host 18613@value{GDBN} session gets control. 18614 18615Call @code{breakpoint} if none of these is true, or if you simply want 18616to make certain your program stops at a predetermined point for the 18617start of your debugging session. 18618@end table 18619 18620@node Bootstrapping 18621@subsection What You Must Do for the Stub 18622 18623@cindex remote stub, support routines 18624The debugging stubs that come with @value{GDBN} are set up for a particular 18625chip architecture, but they have no information about the rest of your 18626debugging target machine. 18627 18628First of all you need to tell the stub how to communicate with the 18629serial port. 18630 18631@table @code 18632@item int getDebugChar() 18633@findex getDebugChar 18634Write this subroutine to read a single character from the serial port. 18635It may be identical to @code{getchar} for your target system; a 18636different name is used to allow you to distinguish the two if you wish. 18637 18638@item void putDebugChar(int) 18639@findex putDebugChar 18640Write this subroutine to write a single character to the serial port. 18641It may be identical to @code{putchar} for your target system; a 18642different name is used to allow you to distinguish the two if you wish. 18643@end table 18644 18645@cindex control C, and remote debugging 18646@cindex interrupting remote targets 18647If you want @value{GDBN} to be able to stop your program while it is 18648running, you need to use an interrupt-driven serial driver, and arrange 18649for it to stop when it receives a @code{^C} (@samp{\003}, the control-C 18650character). That is the character which @value{GDBN} uses to tell the 18651remote system to stop. 18652 18653Getting the debugging target to return the proper status to @value{GDBN} 18654probably requires changes to the standard stub; one quick and dirty way 18655is to just execute a breakpoint instruction (the ``dirty'' part is that 18656@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}). 18657 18658Other routines you need to supply are: 18659 18660@table @code 18661@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address}) 18662@findex exceptionHandler 18663Write this function to install @var{exception_address} in the exception 18664handling tables. You need to do this because the stub does not have any 18665way of knowing what the exception handling tables on your target system 18666are like (for example, the processor's table might be in @sc{rom}, 18667containing entries which point to a table in @sc{ram}). 18668@var{exception_number} is the exception number which should be changed; 18669its meaning is architecture-dependent (for example, different numbers 18670might represent divide by zero, misaligned access, etc). When this 18671exception occurs, control should be transferred directly to 18672@var{exception_address}, and the processor state (stack, registers, 18673and so on) should be just as it is when a processor exception occurs. So if 18674you want to use a jump instruction to reach @var{exception_address}, it 18675should be a simple jump, not a jump to subroutine. 18676 18677For the 386, @var{exception_address} should be installed as an interrupt 18678gate so that interrupts are masked while the handler runs. The gate 18679should be at privilege level 0 (the most privileged level). The 18680@sc{sparc} and 68k stubs are able to mask interrupts themselves without 18681help from @code{exceptionHandler}. 18682 18683@item void flush_i_cache() 18684@findex flush_i_cache 18685On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the 18686instruction cache, if any, on your target machine. If there is no 18687instruction cache, this subroutine may be a no-op. 18688 18689On target machines that have instruction caches, @value{GDBN} requires this 18690function to make certain that the state of your program is stable. 18691@end table 18692 18693@noindent 18694You must also make sure this library routine is available: 18695 18696@table @code 18697@item void *memset(void *, int, int) 18698@findex memset 18699This is the standard library function @code{memset} that sets an area of 18700memory to a known value. If you have one of the free versions of 18701@code{libc.a}, @code{memset} can be found there; otherwise, you must 18702either obtain it from your hardware manufacturer, or write your own. 18703@end table 18704 18705If you do not use the GNU C compiler, you may need other standard 18706library subroutines as well; this varies from one stub to another, 18707but in general the stubs are likely to use any of the common library 18708subroutines which @code{@value{NGCC}} generates as inline code. 18709 18710 18711@node Debug Session 18712@subsection Putting it All Together 18713 18714@cindex remote serial debugging summary 18715In summary, when your program is ready to debug, you must follow these 18716steps. 18717 18718@enumerate 18719@item 18720Make sure you have defined the supporting low-level routines 18721(@pxref{Bootstrapping,,What You Must Do for the Stub}): 18722@display 18723@code{getDebugChar}, @code{putDebugChar}, 18724@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}. 18725@end display 18726 18727@item 18728Insert these lines in your program's startup code, before the main 18729procedure is called: 18730 18731@smallexample 18732set_debug_traps(); 18733breakpoint(); 18734@end smallexample 18735 18736On some machines, when a breakpoint trap is raised, the hardware 18737automatically makes the PC point to the instruction after the 18738breakpoint. If your machine doesn't do that, you may need to adjust 18739@code{handle_exception} to arrange for it to return to the instruction 18740after the breakpoint on this first invocation, so that your program 18741doesn't keep hitting the initial breakpoint instead of making 18742progress. 18743 18744@item 18745For the 680x0 stub only, you need to provide a variable called 18746@code{exceptionHook}. Normally you just use: 18747 18748@smallexample 18749void (*exceptionHook)() = 0; 18750@end smallexample 18751 18752@noindent 18753but if before calling @code{set_debug_traps}, you set it to point to a 18754function in your program, that function is called when 18755@code{@value{GDBN}} continues after stopping on a trap (for example, bus 18756error). The function indicated by @code{exceptionHook} is called with 18757one parameter: an @code{int} which is the exception number. 18758 18759@item 18760Compile and link together: your program, the @value{GDBN} debugging stub for 18761your target architecture, and the supporting subroutines. 18762 18763@item 18764Make sure you have a serial connection between your target machine and 18765the @value{GDBN} host, and identify the serial port on the host. 18766 18767@item 18768@c The "remote" target now provides a `load' command, so we should 18769@c document that. FIXME. 18770Download your program to your target machine (or get it there by 18771whatever means the manufacturer provides), and start it. 18772 18773@item 18774Start @value{GDBN} on the host, and connect to the target 18775(@pxref{Connecting,,Connecting to a Remote Target}). 18776 18777@end enumerate 18778 18779@node Configurations 18780@chapter Configuration-Specific Information 18781 18782While nearly all @value{GDBN} commands are available for all native and 18783cross versions of the debugger, there are some exceptions. This chapter 18784describes things that are only available in certain configurations. 18785 18786There are three major categories of configurations: native 18787configurations, where the host and target are the same, embedded 18788operating system configurations, which are usually the same for several 18789different processor architectures, and bare embedded processors, which 18790are quite different from each other. 18791 18792@menu 18793* Native:: 18794* Embedded OS:: 18795* Embedded Processors:: 18796* Architectures:: 18797@end menu 18798 18799@node Native 18800@section Native 18801 18802This section describes details specific to particular native 18803configurations. 18804 18805@menu 18806* HP-UX:: HP-UX 18807* BSD libkvm Interface:: Debugging BSD kernel memory images 18808* SVR4 Process Information:: SVR4 process information 18809* DJGPP Native:: Features specific to the DJGPP port 18810* Cygwin Native:: Features specific to the Cygwin port 18811* Hurd Native:: Features specific to @sc{gnu} Hurd 18812* Darwin:: Features specific to Darwin 18813@end menu 18814 18815@node HP-UX 18816@subsection HP-UX 18817 18818On HP-UX systems, if you refer to a function or variable name that 18819begins with a dollar sign, @value{GDBN} searches for a user or system 18820name first, before it searches for a convenience variable. 18821 18822 18823@node BSD libkvm Interface 18824@subsection BSD libkvm Interface 18825 18826@cindex libkvm 18827@cindex kernel memory image 18828@cindex kernel crash dump 18829 18830BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory 18831interface that provides a uniform interface for accessing kernel virtual 18832memory images, including live systems and crash dumps. @value{GDBN} 18833uses this interface to allow you to debug live kernels and kernel crash 18834dumps on many native BSD configurations. This is implemented as a 18835special @code{kvm} debugging target. For debugging a live system, load 18836the currently running kernel into @value{GDBN} and connect to the 18837@code{kvm} target: 18838 18839@smallexample 18840(@value{GDBP}) @b{target kvm} 18841@end smallexample 18842 18843For debugging crash dumps, provide the file name of the crash dump as an 18844argument: 18845 18846@smallexample 18847(@value{GDBP}) @b{target kvm /var/crash/bsd.0} 18848@end smallexample 18849 18850Once connected to the @code{kvm} target, the following commands are 18851available: 18852 18853@table @code 18854@kindex kvm 18855@item kvm pcb 18856Set current context from the @dfn{Process Control Block} (PCB) address. 18857 18858@item kvm proc 18859Set current context from proc address. This command isn't available on 18860modern FreeBSD systems. 18861@end table 18862 18863@node SVR4 Process Information 18864@subsection SVR4 Process Information 18865@cindex /proc 18866@cindex examine process image 18867@cindex process info via @file{/proc} 18868 18869Many versions of SVR4 and compatible systems provide a facility called 18870@samp{/proc} that can be used to examine the image of a running 18871process using file-system subroutines. 18872 18873If @value{GDBN} is configured for an operating system with this 18874facility, the command @code{info proc} is available to report 18875information about the process running your program, or about any 18876process running on your system. This includes, as of this writing, 18877@sc{gnu}/Linux, OSF/1 (Digital Unix), Solaris, and Irix, but 18878not HP-UX, for example. 18879 18880This command may also work on core files that were created on a system 18881that has the @samp{/proc} facility. 18882 18883@table @code 18884@kindex info proc 18885@cindex process ID 18886@item info proc 18887@itemx info proc @var{process-id} 18888Summarize available information about any running process. If a 18889process ID is specified by @var{process-id}, display information about 18890that process; otherwise display information about the program being 18891debugged. The summary includes the debugged process ID, the command 18892line used to invoke it, its current working directory, and its 18893executable file's absolute file name. 18894 18895On some systems, @var{process-id} can be of the form 18896@samp{[@var{pid}]/@var{tid}} which specifies a certain thread ID 18897within a process. If the optional @var{pid} part is missing, it means 18898a thread from the process being debugged (the leading @samp{/} still 18899needs to be present, or else @value{GDBN} will interpret the number as 18900a process ID rather than a thread ID). 18901 18902@item info proc cmdline 18903@cindex info proc cmdline 18904Show the original command line of the process. This command is 18905specific to @sc{gnu}/Linux. 18906 18907@item info proc cwd 18908@cindex info proc cwd 18909Show the current working directory of the process. This command is 18910specific to @sc{gnu}/Linux. 18911 18912@item info proc exe 18913@cindex info proc exe 18914Show the name of executable of the process. This command is specific 18915to @sc{gnu}/Linux. 18916 18917@item info proc mappings 18918@cindex memory address space mappings 18919Report the memory address space ranges accessible in the program, with 18920information on whether the process has read, write, or execute access 18921rights to each range. On @sc{gnu}/Linux systems, each memory range 18922includes the object file which is mapped to that range, instead of the 18923memory access rights to that range. 18924 18925@item info proc stat 18926@itemx info proc status 18927@cindex process detailed status information 18928These subcommands are specific to @sc{gnu}/Linux systems. They show 18929the process-related information, including the user ID and group ID; 18930how many threads are there in the process; its virtual memory usage; 18931the signals that are pending, blocked, and ignored; its TTY; its 18932consumption of system and user time; its stack size; its @samp{nice} 18933value; etc. For more information, see the @samp{proc} man page 18934(type @kbd{man 5 proc} from your shell prompt). 18935 18936@item info proc all 18937Show all the information about the process described under all of the 18938above @code{info proc} subcommands. 18939 18940@ignore 18941@comment These sub-options of 'info proc' were not included when 18942@comment procfs.c was re-written. Keep their descriptions around 18943@comment against the day when someone finds the time to put them back in. 18944@kindex info proc times 18945@item info proc times 18946Starting time, user CPU time, and system CPU time for your program and 18947its children. 18948 18949@kindex info proc id 18950@item info proc id 18951Report on the process IDs related to your program: its own process ID, 18952the ID of its parent, the process group ID, and the session ID. 18953@end ignore 18954 18955@item set procfs-trace 18956@kindex set procfs-trace 18957@cindex @code{procfs} API calls 18958This command enables and disables tracing of @code{procfs} API calls. 18959 18960@item show procfs-trace 18961@kindex show procfs-trace 18962Show the current state of @code{procfs} API call tracing. 18963 18964@item set procfs-file @var{file} 18965@kindex set procfs-file 18966Tell @value{GDBN} to write @code{procfs} API trace to the named 18967@var{file}. @value{GDBN} appends the trace info to the previous 18968contents of the file. The default is to display the trace on the 18969standard output. 18970 18971@item show procfs-file 18972@kindex show procfs-file 18973Show the file to which @code{procfs} API trace is written. 18974 18975@item proc-trace-entry 18976@itemx proc-trace-exit 18977@itemx proc-untrace-entry 18978@itemx proc-untrace-exit 18979@kindex proc-trace-entry 18980@kindex proc-trace-exit 18981@kindex proc-untrace-entry 18982@kindex proc-untrace-exit 18983These commands enable and disable tracing of entries into and exits 18984from the @code{syscall} interface. 18985 18986@item info pidlist 18987@kindex info pidlist 18988@cindex process list, QNX Neutrino 18989For QNX Neutrino only, this command displays the list of all the 18990processes and all the threads within each process. 18991 18992@item info meminfo 18993@kindex info meminfo 18994@cindex mapinfo list, QNX Neutrino 18995For QNX Neutrino only, this command displays the list of all mapinfos. 18996@end table 18997 18998@node DJGPP Native 18999@subsection Features for Debugging @sc{djgpp} Programs 19000@cindex @sc{djgpp} debugging 19001@cindex native @sc{djgpp} debugging 19002@cindex MS-DOS-specific commands 19003 19004@cindex DPMI 19005@sc{djgpp} is a port of the @sc{gnu} development tools to MS-DOS and 19006MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs 19007that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on 19008top of real-mode DOS systems and their emulations. 19009 19010@value{GDBN} supports native debugging of @sc{djgpp} programs, and 19011defines a few commands specific to the @sc{djgpp} port. This 19012subsection describes those commands. 19013 19014@table @code 19015@kindex info dos 19016@item info dos 19017This is a prefix of @sc{djgpp}-specific commands which print 19018information about the target system and important OS structures. 19019 19020@kindex sysinfo 19021@cindex MS-DOS system info 19022@cindex free memory information (MS-DOS) 19023@item info dos sysinfo 19024This command displays assorted information about the underlying 19025platform: the CPU type and features, the OS version and flavor, the 19026DPMI version, and the available conventional and DPMI memory. 19027 19028@cindex GDT 19029@cindex LDT 19030@cindex IDT 19031@cindex segment descriptor tables 19032@cindex descriptor tables display 19033@item info dos gdt 19034@itemx info dos ldt 19035@itemx info dos idt 19036These 3 commands display entries from, respectively, Global, Local, 19037and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor 19038tables are data structures which store a descriptor for each segment 19039that is currently in use. The segment's selector is an index into a 19040descriptor table; the table entry for that index holds the 19041descriptor's base address and limit, and its attributes and access 19042rights. 19043 19044A typical @sc{djgpp} program uses 3 segments: a code segment, a data 19045segment (used for both data and the stack), and a DOS segment (which 19046allows access to DOS/BIOS data structures and absolute addresses in 19047conventional memory). However, the DPMI host will usually define 19048additional segments in order to support the DPMI environment. 19049 19050@cindex garbled pointers 19051These commands allow to display entries from the descriptor tables. 19052Without an argument, all entries from the specified table are 19053displayed. An argument, which should be an integer expression, means 19054display a single entry whose index is given by the argument. For 19055example, here's a convenient way to display information about the 19056debugged program's data segment: 19057 19058@smallexample 19059@exdent @code{(@value{GDBP}) info dos ldt $ds} 19060@exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)} 19061@end smallexample 19062 19063@noindent 19064This comes in handy when you want to see whether a pointer is outside 19065the data segment's limit (i.e.@: @dfn{garbled}). 19066 19067@cindex page tables display (MS-DOS) 19068@item info dos pde 19069@itemx info dos pte 19070These two commands display entries from, respectively, the Page 19071Directory and the Page Tables. Page Directories and Page Tables are 19072data structures which control how virtual memory addresses are mapped 19073into physical addresses. A Page Table includes an entry for every 19074page of memory that is mapped into the program's address space; there 19075may be several Page Tables, each one holding up to 4096 entries. A 19076Page Directory has up to 4096 entries, one each for every Page Table 19077that is currently in use. 19078 19079Without an argument, @kbd{info dos pde} displays the entire Page 19080Directory, and @kbd{info dos pte} displays all the entries in all of 19081the Page Tables. An argument, an integer expression, given to the 19082@kbd{info dos pde} command means display only that entry from the Page 19083Directory table. An argument given to the @kbd{info dos pte} command 19084means display entries from a single Page Table, the one pointed to by 19085the specified entry in the Page Directory. 19086 19087@cindex direct memory access (DMA) on MS-DOS 19088These commands are useful when your program uses @dfn{DMA} (Direct 19089Memory Access), which needs physical addresses to program the DMA 19090controller. 19091 19092These commands are supported only with some DPMI servers. 19093 19094@cindex physical address from linear address 19095@item info dos address-pte @var{addr} 19096This command displays the Page Table entry for a specified linear 19097address. The argument @var{addr} is a linear address which should 19098already have the appropriate segment's base address added to it, 19099because this command accepts addresses which may belong to @emph{any} 19100segment. For example, here's how to display the Page Table entry for 19101the page where a variable @code{i} is stored: 19102 19103@smallexample 19104@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i} 19105@exdent @code{Page Table entry for address 0x11a00d30:} 19106@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30} 19107@end smallexample 19108 19109@noindent 19110This says that @code{i} is stored at offset @code{0xd30} from the page 19111whose physical base address is @code{0x02698000}, and shows all the 19112attributes of that page. 19113 19114Note that you must cast the addresses of variables to a @code{char *}, 19115since otherwise the value of @code{__djgpp_base_address}, the base 19116address of all variables and functions in a @sc{djgpp} program, will 19117be added using the rules of C pointer arithmetics: if @code{i} is 19118declared an @code{int}, @value{GDBN} will add 4 times the value of 19119@code{__djgpp_base_address} to the address of @code{i}. 19120 19121Here's another example, it displays the Page Table entry for the 19122transfer buffer: 19123 19124@smallexample 19125@exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)} 19126@exdent @code{Page Table entry for address 0x29110:} 19127@exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110} 19128@end smallexample 19129 19130@noindent 19131(The @code{+ 3} offset is because the transfer buffer's address is the 191323rd member of the @code{_go32_info_block} structure.) The output 19133clearly shows that this DPMI server maps the addresses in conventional 19134memory 1:1, i.e.@: the physical (@code{0x00029000} + @code{0x110}) and 19135linear (@code{0x29110}) addresses are identical. 19136 19137This command is supported only with some DPMI servers. 19138@end table 19139 19140@cindex DOS serial data link, remote debugging 19141In addition to native debugging, the DJGPP port supports remote 19142debugging via a serial data link. The following commands are specific 19143to remote serial debugging in the DJGPP port of @value{GDBN}. 19144 19145@table @code 19146@kindex set com1base 19147@kindex set com1irq 19148@kindex set com2base 19149@kindex set com2irq 19150@kindex set com3base 19151@kindex set com3irq 19152@kindex set com4base 19153@kindex set com4irq 19154@item set com1base @var{addr} 19155This command sets the base I/O port address of the @file{COM1} serial 19156port. 19157 19158@item set com1irq @var{irq} 19159This command sets the @dfn{Interrupt Request} (@code{IRQ}) line to use 19160for the @file{COM1} serial port. 19161 19162There are similar commands @samp{set com2base}, @samp{set com3irq}, 19163etc.@: for setting the port address and the @code{IRQ} lines for the 19164other 3 COM ports. 19165 19166@kindex show com1base 19167@kindex show com1irq 19168@kindex show com2base 19169@kindex show com2irq 19170@kindex show com3base 19171@kindex show com3irq 19172@kindex show com4base 19173@kindex show com4irq 19174The related commands @samp{show com1base}, @samp{show com1irq} etc.@: 19175display the current settings of the base address and the @code{IRQ} 19176lines used by the COM ports. 19177 19178@item info serial 19179@kindex info serial 19180@cindex DOS serial port status 19181This command prints the status of the 4 DOS serial ports. For each 19182port, it prints whether it's active or not, its I/O base address and 19183IRQ number, whether it uses a 16550-style FIFO, its baudrate, and the 19184counts of various errors encountered so far. 19185@end table 19186 19187 19188@node Cygwin Native 19189@subsection Features for Debugging MS Windows PE Executables 19190@cindex MS Windows debugging 19191@cindex native Cygwin debugging 19192@cindex Cygwin-specific commands 19193 19194@value{GDBN} supports native debugging of MS Windows programs, including 19195DLLs with and without symbolic debugging information. 19196 19197@cindex Ctrl-BREAK, MS-Windows 19198@cindex interrupt debuggee on MS-Windows 19199MS-Windows programs that call @code{SetConsoleMode} to switch off the 19200special meaning of the @samp{Ctrl-C} keystroke cannot be interrupted 19201by typing @kbd{C-c}. For this reason, @value{GDBN} on MS-Windows 19202supports @kbd{C-@key{BREAK}} as an alternative interrupt key 19203sequence, which can be used to interrupt the debuggee even if it 19204ignores @kbd{C-c}. 19205 19206There are various additional Cygwin-specific commands, described in 19207this section. Working with DLLs that have no debugging symbols is 19208described in @ref{Non-debug DLL Symbols}. 19209 19210@table @code 19211@kindex info w32 19212@item info w32 19213This is a prefix of MS Windows-specific commands which print 19214information about the target system and important OS structures. 19215 19216@item info w32 selector 19217This command displays information returned by 19218the Win32 API @code{GetThreadSelectorEntry} function. 19219It takes an optional argument that is evaluated to 19220a long value to give the information about this given selector. 19221Without argument, this command displays information 19222about the six segment registers. 19223 19224@item info w32 thread-information-block 19225This command displays thread specific information stored in the 19226Thread Information Block (readable on the X86 CPU family using @code{$fs} 19227selector for 32-bit programs and @code{$gs} for 64-bit programs). 19228 19229@kindex info dll 19230@item info dll 19231This is a Cygwin-specific alias of @code{info shared}. 19232 19233@kindex dll-symbols 19234@item dll-symbols 19235This command loads symbols from a dll similarly to 19236add-sym command but without the need to specify a base address. 19237 19238@kindex set cygwin-exceptions 19239@cindex debugging the Cygwin DLL 19240@cindex Cygwin DLL, debugging 19241@item set cygwin-exceptions @var{mode} 19242If @var{mode} is @code{on}, @value{GDBN} will break on exceptions that 19243happen inside the Cygwin DLL. If @var{mode} is @code{off}, 19244@value{GDBN} will delay recognition of exceptions, and may ignore some 19245exceptions which seem to be caused by internal Cygwin DLL 19246``bookkeeping''. This option is meant primarily for debugging the 19247Cygwin DLL itself; the default value is @code{off} to avoid annoying 19248@value{GDBN} users with false @code{SIGSEGV} signals. 19249 19250@kindex show cygwin-exceptions 19251@item show cygwin-exceptions 19252Displays whether @value{GDBN} will break on exceptions that happen 19253inside the Cygwin DLL itself. 19254 19255@kindex set new-console 19256@item set new-console @var{mode} 19257If @var{mode} is @code{on} the debuggee will 19258be started in a new console on next start. 19259If @var{mode} is @code{off}, the debuggee will 19260be started in the same console as the debugger. 19261 19262@kindex show new-console 19263@item show new-console 19264Displays whether a new console is used 19265when the debuggee is started. 19266 19267@kindex set new-group 19268@item set new-group @var{mode} 19269This boolean value controls whether the debuggee should 19270start a new group or stay in the same group as the debugger. 19271This affects the way the Windows OS handles 19272@samp{Ctrl-C}. 19273 19274@kindex show new-group 19275@item show new-group 19276Displays current value of new-group boolean. 19277 19278@kindex set debugevents 19279@item set debugevents 19280This boolean value adds debug output concerning kernel events related 19281to the debuggee seen by the debugger. This includes events that 19282signal thread and process creation and exit, DLL loading and 19283unloading, console interrupts, and debugging messages produced by the 19284Windows @code{OutputDebugString} API call. 19285 19286@kindex set debugexec 19287@item set debugexec 19288This boolean value adds debug output concerning execute events 19289(such as resume thread) seen by the debugger. 19290 19291@kindex set debugexceptions 19292@item set debugexceptions 19293This boolean value adds debug output concerning exceptions in the 19294debuggee seen by the debugger. 19295 19296@kindex set debugmemory 19297@item set debugmemory 19298This boolean value adds debug output concerning debuggee memory reads 19299and writes by the debugger. 19300 19301@kindex set shell 19302@item set shell 19303This boolean values specifies whether the debuggee is called 19304via a shell or directly (default value is on). 19305 19306@kindex show shell 19307@item show shell 19308Displays if the debuggee will be started with a shell. 19309 19310@end table 19311 19312@menu 19313* Non-debug DLL Symbols:: Support for DLLs without debugging symbols 19314@end menu 19315 19316@node Non-debug DLL Symbols 19317@subsubsection Support for DLLs without Debugging Symbols 19318@cindex DLLs with no debugging symbols 19319@cindex Minimal symbols and DLLs 19320 19321Very often on windows, some of the DLLs that your program relies on do 19322not include symbolic debugging information (for example, 19323@file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging 19324symbols in a DLL, it relies on the minimal amount of symbolic 19325information contained in the DLL's export table. This section 19326describes working with such symbols, known internally to @value{GDBN} as 19327``minimal symbols''. 19328 19329Note that before the debugged program has started execution, no DLLs 19330will have been loaded. The easiest way around this problem is simply to 19331start the program --- either by setting a breakpoint or letting the 19332program run once to completion. It is also possible to force 19333@value{GDBN} to load a particular DLL before starting the executable --- 19334see the shared library information in @ref{Files}, or the 19335@code{dll-symbols} command in @ref{Cygwin Native}. Currently, 19336explicitly loading symbols from a DLL with no debugging information will 19337cause the symbol names to be duplicated in @value{GDBN}'s lookup table, 19338which may adversely affect symbol lookup performance. 19339 19340@subsubsection DLL Name Prefixes 19341 19342In keeping with the naming conventions used by the Microsoft debugging 19343tools, DLL export symbols are made available with a prefix based on the 19344DLL name, for instance @code{KERNEL32!CreateFileA}. The plain name is 19345also entered into the symbol table, so @code{CreateFileA} is often 19346sufficient. In some cases there will be name clashes within a program 19347(particularly if the executable itself includes full debugging symbols) 19348necessitating the use of the fully qualified name when referring to the 19349contents of the DLL. Use single-quotes around the name to avoid the 19350exclamation mark (``!'') being interpreted as a language operator. 19351 19352Note that the internal name of the DLL may be all upper-case, even 19353though the file name of the DLL is lower-case, or vice-versa. Since 19354symbols within @value{GDBN} are @emph{case-sensitive} this may cause 19355some confusion. If in doubt, try the @code{info functions} and 19356@code{info variables} commands or even @code{maint print msymbols} 19357(@pxref{Symbols}). Here's an example: 19358 19359@smallexample 19360(@value{GDBP}) info function CreateFileA 19361All functions matching regular expression "CreateFileA": 19362 19363Non-debugging symbols: 193640x77e885f4 CreateFileA 193650x77e885f4 KERNEL32!CreateFileA 19366@end smallexample 19367 19368@smallexample 19369(@value{GDBP}) info function ! 19370All functions matching regular expression "!": 19371 19372Non-debugging symbols: 193730x6100114c cygwin1!__assert 193740x61004034 cygwin1!_dll_crt0@@0 193750x61004240 cygwin1!dll_crt0(per_process *) 19376[etc...] 19377@end smallexample 19378 19379@subsubsection Working with Minimal Symbols 19380 19381Symbols extracted from a DLL's export table do not contain very much 19382type information. All that @value{GDBN} can do is guess whether a symbol 19383refers to a function or variable depending on the linker section that 19384contains the symbol. Also note that the actual contents of the memory 19385contained in a DLL are not available unless the program is running. This 19386means that you cannot examine the contents of a variable or disassemble 19387a function within a DLL without a running program. 19388 19389Variables are generally treated as pointers and dereferenced 19390automatically. For this reason, it is often necessary to prefix a 19391variable name with the address-of operator (``&'') and provide explicit 19392type information in the command. Here's an example of the type of 19393problem: 19394 19395@smallexample 19396(@value{GDBP}) print 'cygwin1!__argv' 19397$1 = 268572168 19398@end smallexample 19399 19400@smallexample 19401(@value{GDBP}) x 'cygwin1!__argv' 194020x10021610: "\230y\"" 19403@end smallexample 19404 19405And two possible solutions: 19406 19407@smallexample 19408(@value{GDBP}) print ((char **)'cygwin1!__argv')[0] 19409$2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" 19410@end smallexample 19411 19412@smallexample 19413(@value{GDBP}) x/2x &'cygwin1!__argv' 194140x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000 19415(@value{GDBP}) x/x 0x10021608 194160x10021608: 0x0022fd98 19417(@value{GDBP}) x/s 0x0022fd98 194180x22fd98: "/cygdrive/c/mydirectory/myprogram" 19419@end smallexample 19420 19421Setting a break point within a DLL is possible even before the program 19422starts execution. However, under these circumstances, @value{GDBN} can't 19423examine the initial instructions of the function in order to skip the 19424function's frame set-up code. You can work around this by using ``*&'' 19425to set the breakpoint at a raw memory address: 19426 19427@smallexample 19428(@value{GDBP}) break *&'python22!PyOS_Readline' 19429Breakpoint 1 at 0x1e04eff0 19430@end smallexample 19431 19432The author of these extensions is not entirely convinced that setting a 19433break point within a shared DLL like @file{kernel32.dll} is completely 19434safe. 19435 19436@node Hurd Native 19437@subsection Commands Specific to @sc{gnu} Hurd Systems 19438@cindex @sc{gnu} Hurd debugging 19439 19440This subsection describes @value{GDBN} commands specific to the 19441@sc{gnu} Hurd native debugging. 19442 19443@table @code 19444@item set signals 19445@itemx set sigs 19446@kindex set signals@r{, Hurd command} 19447@kindex set sigs@r{, Hurd command} 19448This command toggles the state of inferior signal interception by 19449@value{GDBN}. Mach exceptions, such as breakpoint traps, are not 19450affected by this command. @code{sigs} is a shorthand alias for 19451@code{signals}. 19452 19453@item show signals 19454@itemx show sigs 19455@kindex show signals@r{, Hurd command} 19456@kindex show sigs@r{, Hurd command} 19457Show the current state of intercepting inferior's signals. 19458 19459@item set signal-thread 19460@itemx set sigthread 19461@kindex set signal-thread 19462@kindex set sigthread 19463This command tells @value{GDBN} which thread is the @code{libc} signal 19464thread. That thread is run when a signal is delivered to a running 19465process. @code{set sigthread} is the shorthand alias of @code{set 19466signal-thread}. 19467 19468@item show signal-thread 19469@itemx show sigthread 19470@kindex show signal-thread 19471@kindex show sigthread 19472These two commands show which thread will run when the inferior is 19473delivered a signal. 19474 19475@item set stopped 19476@kindex set stopped@r{, Hurd command} 19477This commands tells @value{GDBN} that the inferior process is stopped, 19478as with the @code{SIGSTOP} signal. The stopped process can be 19479continued by delivering a signal to it. 19480 19481@item show stopped 19482@kindex show stopped@r{, Hurd command} 19483This command shows whether @value{GDBN} thinks the debuggee is 19484stopped. 19485 19486@item set exceptions 19487@kindex set exceptions@r{, Hurd command} 19488Use this command to turn off trapping of exceptions in the inferior. 19489When exception trapping is off, neither breakpoints nor 19490single-stepping will work. To restore the default, set exception 19491trapping on. 19492 19493@item show exceptions 19494@kindex show exceptions@r{, Hurd command} 19495Show the current state of trapping exceptions in the inferior. 19496 19497@item set task pause 19498@kindex set task@r{, Hurd commands} 19499@cindex task attributes (@sc{gnu} Hurd) 19500@cindex pause current task (@sc{gnu} Hurd) 19501This command toggles task suspension when @value{GDBN} has control. 19502Setting it to on takes effect immediately, and the task is suspended 19503whenever @value{GDBN} gets control. Setting it to off will take 19504effect the next time the inferior is continued. If this option is set 19505to off, you can use @code{set thread default pause on} or @code{set 19506thread pause on} (see below) to pause individual threads. 19507 19508@item show task pause 19509@kindex show task@r{, Hurd commands} 19510Show the current state of task suspension. 19511 19512@item set task detach-suspend-count 19513@cindex task suspend count 19514@cindex detach from task, @sc{gnu} Hurd 19515This command sets the suspend count the task will be left with when 19516@value{GDBN} detaches from it. 19517 19518@item show task detach-suspend-count 19519Show the suspend count the task will be left with when detaching. 19520 19521@item set task exception-port 19522@itemx set task excp 19523@cindex task exception port, @sc{gnu} Hurd 19524This command sets the task exception port to which @value{GDBN} will 19525forward exceptions. The argument should be the value of the @dfn{send 19526rights} of the task. @code{set task excp} is a shorthand alias. 19527 19528@item set noninvasive 19529@cindex noninvasive task options 19530This command switches @value{GDBN} to a mode that is the least 19531invasive as far as interfering with the inferior is concerned. This 19532is the same as using @code{set task pause}, @code{set exceptions}, and 19533@code{set signals} to values opposite to the defaults. 19534 19535@item info send-rights 19536@itemx info receive-rights 19537@itemx info port-rights 19538@itemx info port-sets 19539@itemx info dead-names 19540@itemx info ports 19541@itemx info psets 19542@cindex send rights, @sc{gnu} Hurd 19543@cindex receive rights, @sc{gnu} Hurd 19544@cindex port rights, @sc{gnu} Hurd 19545@cindex port sets, @sc{gnu} Hurd 19546@cindex dead names, @sc{gnu} Hurd 19547These commands display information about, respectively, send rights, 19548receive rights, port rights, port sets, and dead names of a task. 19549There are also shorthand aliases: @code{info ports} for @code{info 19550port-rights} and @code{info psets} for @code{info port-sets}. 19551 19552@item set thread pause 19553@kindex set thread@r{, Hurd command} 19554@cindex thread properties, @sc{gnu} Hurd 19555@cindex pause current thread (@sc{gnu} Hurd) 19556This command toggles current thread suspension when @value{GDBN} has 19557control. Setting it to on takes effect immediately, and the current 19558thread is suspended whenever @value{GDBN} gets control. Setting it to 19559off will take effect the next time the inferior is continued. 19560Normally, this command has no effect, since when @value{GDBN} has 19561control, the whole task is suspended. However, if you used @code{set 19562task pause off} (see above), this command comes in handy to suspend 19563only the current thread. 19564 19565@item show thread pause 19566@kindex show thread@r{, Hurd command} 19567This command shows the state of current thread suspension. 19568 19569@item set thread run 19570This command sets whether the current thread is allowed to run. 19571 19572@item show thread run 19573Show whether the current thread is allowed to run. 19574 19575@item set thread detach-suspend-count 19576@cindex thread suspend count, @sc{gnu} Hurd 19577@cindex detach from thread, @sc{gnu} Hurd 19578This command sets the suspend count @value{GDBN} will leave on a 19579thread when detaching. This number is relative to the suspend count 19580found by @value{GDBN} when it notices the thread; use @code{set thread 19581takeover-suspend-count} to force it to an absolute value. 19582 19583@item show thread detach-suspend-count 19584Show the suspend count @value{GDBN} will leave on the thread when 19585detaching. 19586 19587@item set thread exception-port 19588@itemx set thread excp 19589Set the thread exception port to which to forward exceptions. This 19590overrides the port set by @code{set task exception-port} (see above). 19591@code{set thread excp} is the shorthand alias. 19592 19593@item set thread takeover-suspend-count 19594Normally, @value{GDBN}'s thread suspend counts are relative to the 19595value @value{GDBN} finds when it notices each thread. This command 19596changes the suspend counts to be absolute instead. 19597 19598@item set thread default 19599@itemx show thread default 19600@cindex thread default settings, @sc{gnu} Hurd 19601Each of the above @code{set thread} commands has a @code{set thread 19602default} counterpart (e.g., @code{set thread default pause}, @code{set 19603thread default exception-port}, etc.). The @code{thread default} 19604variety of commands sets the default thread properties for all 19605threads; you can then change the properties of individual threads with 19606the non-default commands. 19607@end table 19608 19609@node Darwin 19610@subsection Darwin 19611@cindex Darwin 19612 19613@value{GDBN} provides the following commands specific to the Darwin target: 19614 19615@table @code 19616@item set debug darwin @var{num} 19617@kindex set debug darwin 19618When set to a non zero value, enables debugging messages specific to 19619the Darwin support. Higher values produce more verbose output. 19620 19621@item show debug darwin 19622@kindex show debug darwin 19623Show the current state of Darwin messages. 19624 19625@item set debug mach-o @var{num} 19626@kindex set debug mach-o 19627When set to a non zero value, enables debugging messages while 19628@value{GDBN} is reading Darwin object files. (@dfn{Mach-O} is the 19629file format used on Darwin for object and executable files.) Higher 19630values produce more verbose output. This is a command to diagnose 19631problems internal to @value{GDBN} and should not be needed in normal 19632usage. 19633 19634@item show debug mach-o 19635@kindex show debug mach-o 19636Show the current state of Mach-O file messages. 19637 19638@item set mach-exceptions on 19639@itemx set mach-exceptions off 19640@kindex set mach-exceptions 19641On Darwin, faults are first reported as a Mach exception and are then 19642mapped to a Posix signal. Use this command to turn on trapping of 19643Mach exceptions in the inferior. This might be sometimes useful to 19644better understand the cause of a fault. The default is off. 19645 19646@item show mach-exceptions 19647@kindex show mach-exceptions 19648Show the current state of exceptions trapping. 19649@end table 19650 19651 19652@node Embedded OS 19653@section Embedded Operating Systems 19654 19655This section describes configurations involving the debugging of 19656embedded operating systems that are available for several different 19657architectures. 19658 19659@menu 19660* VxWorks:: Using @value{GDBN} with VxWorks 19661@end menu 19662 19663@value{GDBN} includes the ability to debug programs running on 19664various real-time operating systems. 19665 19666@node VxWorks 19667@subsection Using @value{GDBN} with VxWorks 19668 19669@cindex VxWorks 19670 19671@table @code 19672 19673@kindex target vxworks 19674@item target vxworks @var{machinename} 19675A VxWorks system, attached via TCP/IP. The argument @var{machinename} 19676is the target system's machine name or IP address. 19677 19678@end table 19679 19680On VxWorks, @code{load} links @var{filename} dynamically on the 19681current target system as well as adding its symbols in @value{GDBN}. 19682 19683@value{GDBN} enables developers to spawn and debug tasks running on networked 19684VxWorks targets from a Unix host. Already-running tasks spawned from 19685the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on 19686both the Unix host and on the VxWorks target. The program 19687@code{@value{GDBP}} is installed and executed on the Unix host. (It may be 19688installed with the name @code{vxgdb}, to distinguish it from a 19689@value{GDBN} for debugging programs on the host itself.) 19690 19691@table @code 19692@item VxWorks-timeout @var{args} 19693@kindex vxworks-timeout 19694All VxWorks-based targets now support the option @code{vxworks-timeout}. 19695This option is set by the user, and @var{args} represents the number of 19696seconds @value{GDBN} waits for responses to rpc's. You might use this if 19697your VxWorks target is a slow software simulator or is on the far side 19698of a thin network line. 19699@end table 19700 19701The following information on connecting to VxWorks was current when 19702this manual was produced; newer releases of VxWorks may use revised 19703procedures. 19704 19705@findex INCLUDE_RDB 19706To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel 19707to include the remote debugging interface routines in the VxWorks 19708library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the 19709VxWorks configuration file @file{configAll.h} and rebuild your VxWorks 19710kernel. The resulting kernel contains @file{rdb.a}, and spawns the 19711source debugging task @code{tRdbTask} when VxWorks is booted. For more 19712information on configuring and remaking VxWorks, see the manufacturer's 19713manual. 19714@c VxWorks, see the @cite{VxWorks Programmer's Guide}. 19715 19716Once you have included @file{rdb.a} in your VxWorks system image and set 19717your Unix execution search path to find @value{GDBN}, you are ready to 19718run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or 19719@code{vxgdb}, depending on your installation). 19720 19721@value{GDBN} comes up showing the prompt: 19722 19723@smallexample 19724(vxgdb) 19725@end smallexample 19726 19727@menu 19728* VxWorks Connection:: Connecting to VxWorks 19729* VxWorks Download:: VxWorks download 19730* VxWorks Attach:: Running tasks 19731@end menu 19732 19733@node VxWorks Connection 19734@subsubsection Connecting to VxWorks 19735 19736The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the 19737network. To connect to a target whose host name is ``@code{tt}'', type: 19738 19739@smallexample 19740(vxgdb) target vxworks tt 19741@end smallexample 19742 19743@need 750 19744@value{GDBN} displays messages like these: 19745 19746@smallexample 19747Attaching remote machine across net... 19748Connected to tt. 19749@end smallexample 19750 19751@need 1000 19752@value{GDBN} then attempts to read the symbol tables of any object modules 19753loaded into the VxWorks target since it was last booted. @value{GDBN} locates 19754these files by searching the directories listed in the command search 19755path (@pxref{Environment, ,Your Program's Environment}); if it fails 19756to find an object file, it displays a message such as: 19757 19758@smallexample 19759prog.o: No such file or directory. 19760@end smallexample 19761 19762When this happens, add the appropriate directory to the search path with 19763the @value{GDBN} command @code{path}, and execute the @code{target} 19764command again. 19765 19766@node VxWorks Download 19767@subsubsection VxWorks Download 19768 19769@cindex download to VxWorks 19770If you have connected to the VxWorks target and you want to debug an 19771object that has not yet been loaded, you can use the @value{GDBN} 19772@code{load} command to download a file from Unix to VxWorks 19773incrementally. The object file given as an argument to the @code{load} 19774command is actually opened twice: first by the VxWorks target in order 19775to download the code, then by @value{GDBN} in order to read the symbol 19776table. This can lead to problems if the current working directories on 19777the two systems differ. If both systems have NFS mounted the same 19778filesystems, you can avoid these problems by using absolute paths. 19779Otherwise, it is simplest to set the working directory on both systems 19780to the directory in which the object file resides, and then to reference 19781the file by its name, without any path. For instance, a program 19782@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks 19783and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this 19784program, type this on VxWorks: 19785 19786@smallexample 19787-> cd "@var{vxpath}/vw/demo/rdb" 19788@end smallexample 19789 19790@noindent 19791Then, in @value{GDBN}, type: 19792 19793@smallexample 19794(vxgdb) cd @var{hostpath}/vw/demo/rdb 19795(vxgdb) load prog.o 19796@end smallexample 19797 19798@value{GDBN} displays a response similar to this: 19799 19800@smallexample 19801Reading symbol data from wherever/vw/demo/rdb/prog.o... done. 19802@end smallexample 19803 19804You can also use the @code{load} command to reload an object module 19805after editing and recompiling the corresponding source file. Note that 19806this makes @value{GDBN} delete all currently-defined breakpoints, 19807auto-displays, and convenience variables, and to clear the value 19808history. (This is necessary in order to preserve the integrity of 19809debugger's data structures that reference the target system's symbol 19810table.) 19811 19812@node VxWorks Attach 19813@subsubsection Running Tasks 19814 19815@cindex running VxWorks tasks 19816You can also attach to an existing task using the @code{attach} command as 19817follows: 19818 19819@smallexample 19820(vxgdb) attach @var{task} 19821@end smallexample 19822 19823@noindent 19824where @var{task} is the VxWorks hexadecimal task ID. The task can be running 19825or suspended when you attach to it. Running tasks are suspended at 19826the time of attachment. 19827 19828@node Embedded Processors 19829@section Embedded Processors 19830 19831This section goes into details specific to particular embedded 19832configurations. 19833 19834@cindex send command to simulator 19835Whenever a specific embedded processor has a simulator, @value{GDBN} 19836allows to send an arbitrary command to the simulator. 19837 19838@table @code 19839@item sim @var{command} 19840@kindex sim@r{, a command} 19841Send an arbitrary @var{command} string to the simulator. Consult the 19842documentation for the specific simulator in use for information about 19843acceptable commands. 19844@end table 19845 19846 19847@menu 19848* ARM:: ARM RDI 19849* M32R/D:: Renesas M32R/D 19850* M68K:: Motorola M68K 19851* MicroBlaze:: Xilinx MicroBlaze 19852* MIPS Embedded:: MIPS Embedded 19853* OpenRISC 1000:: OpenRisc 1000 19854* PowerPC Embedded:: PowerPC Embedded 19855* PA:: HP PA Embedded 19856* Sparclet:: Tsqware Sparclet 19857* Sparclite:: Fujitsu Sparclite 19858* Z8000:: Zilog Z8000 19859* AVR:: Atmel AVR 19860* CRIS:: CRIS 19861* Super-H:: Renesas Super-H 19862@end menu 19863 19864@node ARM 19865@subsection ARM 19866@cindex ARM RDI 19867 19868@table @code 19869@kindex target rdi 19870@item target rdi @var{dev} 19871ARM Angel monitor, via RDI library interface to ADP protocol. You may 19872use this target to communicate with both boards running the Angel 19873monitor, or with the EmbeddedICE JTAG debug device. 19874 19875@kindex target rdp 19876@item target rdp @var{dev} 19877ARM Demon monitor. 19878 19879@end table 19880 19881@value{GDBN} provides the following ARM-specific commands: 19882 19883@table @code 19884@item set arm disassembler 19885@kindex set arm 19886This commands selects from a list of disassembly styles. The 19887@code{"std"} style is the standard style. 19888 19889@item show arm disassembler 19890@kindex show arm 19891Show the current disassembly style. 19892 19893@item set arm apcs32 19894@cindex ARM 32-bit mode 19895This command toggles ARM operation mode between 32-bit and 26-bit. 19896 19897@item show arm apcs32 19898Display the current usage of the ARM 32-bit mode. 19899 19900@item set arm fpu @var{fputype} 19901This command sets the ARM floating-point unit (FPU) type. The 19902argument @var{fputype} can be one of these: 19903 19904@table @code 19905@item auto 19906Determine the FPU type by querying the OS ABI. 19907@item softfpa 19908Software FPU, with mixed-endian doubles on little-endian ARM 19909processors. 19910@item fpa 19911GCC-compiled FPA co-processor. 19912@item softvfp 19913Software FPU with pure-endian doubles. 19914@item vfp 19915VFP co-processor. 19916@end table 19917 19918@item show arm fpu 19919Show the current type of the FPU. 19920 19921@item set arm abi 19922This command forces @value{GDBN} to use the specified ABI. 19923 19924@item show arm abi 19925Show the currently used ABI. 19926 19927@item set arm fallback-mode (arm|thumb|auto) 19928@value{GDBN} uses the symbol table, when available, to determine 19929whether instructions are ARM or Thumb. This command controls 19930@value{GDBN}'s default behavior when the symbol table is not 19931available. The default is @samp{auto}, which causes @value{GDBN} to 19932use the current execution mode (from the @code{T} bit in the @code{CPSR} 19933register). 19934 19935@item show arm fallback-mode 19936Show the current fallback instruction mode. 19937 19938@item set arm force-mode (arm|thumb|auto) 19939This command overrides use of the symbol table to determine whether 19940instructions are ARM or Thumb. The default is @samp{auto}, which 19941causes @value{GDBN} to use the symbol table and then the setting 19942of @samp{set arm fallback-mode}. 19943 19944@item show arm force-mode 19945Show the current forced instruction mode. 19946 19947@item set debug arm 19948Toggle whether to display ARM-specific debugging messages from the ARM 19949target support subsystem. 19950 19951@item show debug arm 19952Show whether ARM-specific debugging messages are enabled. 19953@end table 19954 19955The following commands are available when an ARM target is debugged 19956using the RDI interface: 19957 19958@table @code 19959@item rdilogfile @r{[}@var{file}@r{]} 19960@kindex rdilogfile 19961@cindex ADP (Angel Debugger Protocol) logging 19962Set the filename for the ADP (Angel Debugger Protocol) packet log. 19963With an argument, sets the log file to the specified @var{file}. With 19964no argument, show the current log file name. The default log file is 19965@file{rdi.log}. 19966 19967@item rdilogenable @r{[}@var{arg}@r{]} 19968@kindex rdilogenable 19969Control logging of ADP packets. With an argument of 1 or @code{"yes"} 19970enables logging, with an argument 0 or @code{"no"} disables it. With 19971no arguments displays the current setting. When logging is enabled, 19972ADP packets exchanged between @value{GDBN} and the RDI target device 19973are logged to a file. 19974 19975@item set rdiromatzero 19976@kindex set rdiromatzero 19977@cindex ROM at zero address, RDI 19978Tell @value{GDBN} whether the target has ROM at address 0. If on, 19979vector catching is disabled, so that zero address can be used. If off 19980(the default), vector catching is enabled. For this command to take 19981effect, it needs to be invoked prior to the @code{target rdi} command. 19982 19983@item show rdiromatzero 19984@kindex show rdiromatzero 19985Show the current setting of ROM at zero address. 19986 19987@item set rdiheartbeat 19988@kindex set rdiheartbeat 19989@cindex RDI heartbeat 19990Enable or disable RDI heartbeat packets. It is not recommended to 19991turn on this option, since it confuses ARM and EPI JTAG interface, as 19992well as the Angel monitor. 19993 19994@item show rdiheartbeat 19995@kindex show rdiheartbeat 19996Show the setting of RDI heartbeat packets. 19997@end table 19998 19999@table @code 20000@item target sim @r{[}@var{simargs}@r{]} @dots{} 20001The @value{GDBN} ARM simulator accepts the following optional arguments. 20002 20003@table @code 20004@item --swi-support=@var{type} 20005Tell the simulator which SWI interfaces to support. 20006@var{type} may be a comma separated list of the following values. 20007The default value is @code{all}. 20008 20009@table @code 20010@item none 20011@item demon 20012@item angel 20013@item redboot 20014@item all 20015@end table 20016@end table 20017@end table 20018 20019@node M32R/D 20020@subsection Renesas M32R/D and M32R/SDI 20021 20022@table @code 20023@kindex target m32r 20024@item target m32r @var{dev} 20025Renesas M32R/D ROM monitor. 20026 20027@kindex target m32rsdi 20028@item target m32rsdi @var{dev} 20029Renesas M32R SDI server, connected via parallel port to the board. 20030@end table 20031 20032The following @value{GDBN} commands are specific to the M32R monitor: 20033 20034@table @code 20035@item set download-path @var{path} 20036@kindex set download-path 20037@cindex find downloadable @sc{srec} files (M32R) 20038Set the default path for finding downloadable @sc{srec} files. 20039 20040@item show download-path 20041@kindex show download-path 20042Show the default path for downloadable @sc{srec} files. 20043 20044@item set board-address @var{addr} 20045@kindex set board-address 20046@cindex M32-EVA target board address 20047Set the IP address for the M32R-EVA target board. 20048 20049@item show board-address 20050@kindex show board-address 20051Show the current IP address of the target board. 20052 20053@item set server-address @var{addr} 20054@kindex set server-address 20055@cindex download server address (M32R) 20056Set the IP address for the download server, which is the @value{GDBN}'s 20057host machine. 20058 20059@item show server-address 20060@kindex show server-address 20061Display the IP address of the download server. 20062 20063@item upload @r{[}@var{file}@r{]} 20064@kindex upload@r{, M32R} 20065Upload the specified @sc{srec} @var{file} via the monitor's Ethernet 20066upload capability. If no @var{file} argument is given, the current 20067executable file is uploaded. 20068 20069@item tload @r{[}@var{file}@r{]} 20070@kindex tload@r{, M32R} 20071Test the @code{upload} command. 20072@end table 20073 20074The following commands are available for M32R/SDI: 20075 20076@table @code 20077@item sdireset 20078@kindex sdireset 20079@cindex reset SDI connection, M32R 20080This command resets the SDI connection. 20081 20082@item sdistatus 20083@kindex sdistatus 20084This command shows the SDI connection status. 20085 20086@item debug_chaos 20087@kindex debug_chaos 20088@cindex M32R/Chaos debugging 20089Instructs the remote that M32R/Chaos debugging is to be used. 20090 20091@item use_debug_dma 20092@kindex use_debug_dma 20093Instructs the remote to use the DEBUG_DMA method of accessing memory. 20094 20095@item use_mon_code 20096@kindex use_mon_code 20097Instructs the remote to use the MON_CODE method of accessing memory. 20098 20099@item use_ib_break 20100@kindex use_ib_break 20101Instructs the remote to set breakpoints by IB break. 20102 20103@item use_dbt_break 20104@kindex use_dbt_break 20105Instructs the remote to set breakpoints by DBT. 20106@end table 20107 20108@node M68K 20109@subsection M68k 20110 20111The Motorola m68k configuration includes ColdFire support, and a 20112target command for the following ROM monitor. 20113 20114@table @code 20115 20116@kindex target dbug 20117@item target dbug @var{dev} 20118dBUG ROM monitor for Motorola ColdFire. 20119 20120@end table 20121 20122@node MicroBlaze 20123@subsection MicroBlaze 20124@cindex Xilinx MicroBlaze 20125@cindex XMD, Xilinx Microprocessor Debugger 20126 20127The MicroBlaze is a soft-core processor supported on various Xilinx 20128FPGAs, such as Spartan or Virtex series. Boards with these processors 20129usually have JTAG ports which connect to a host system running the Xilinx 20130Embedded Development Kit (EDK) or Software Development Kit (SDK). 20131This host system is used to download the configuration bitstream to 20132the target FPGA. The Xilinx Microprocessor Debugger (XMD) program 20133communicates with the target board using the JTAG interface and 20134presents a @code{gdbserver} interface to the board. By default 20135@code{xmd} uses port @code{1234}. (While it is possible to change 20136this default port, it requires the use of undocumented @code{xmd} 20137commands. Contact Xilinx support if you need to do this.) 20138 20139Use these GDB commands to connect to the MicroBlaze target processor. 20140 20141@table @code 20142@item target remote :1234 20143Use this command to connect to the target if you are running @value{GDBN} 20144on the same system as @code{xmd}. 20145 20146@item target remote @var{xmd-host}:1234 20147Use this command to connect to the target if it is connected to @code{xmd} 20148running on a different system named @var{xmd-host}. 20149 20150@item load 20151Use this command to download a program to the MicroBlaze target. 20152 20153@item set debug microblaze @var{n} 20154Enable MicroBlaze-specific debugging messages if non-zero. 20155 20156@item show debug microblaze @var{n} 20157Show MicroBlaze-specific debugging level. 20158@end table 20159 20160@node MIPS Embedded 20161@subsection @acronym{MIPS} Embedded 20162 20163@cindex @acronym{MIPS} boards 20164@value{GDBN} can use the @acronym{MIPS} remote debugging protocol to talk to a 20165@acronym{MIPS} board attached to a serial line. This is available when 20166you configure @value{GDBN} with @samp{--target=mips-elf}. 20167 20168@need 1000 20169Use these @value{GDBN} commands to specify the connection to your target board: 20170 20171@table @code 20172@item target mips @var{port} 20173@kindex target mips @var{port} 20174To run a program on the board, start up @code{@value{GDBP}} with the 20175name of your program as the argument. To connect to the board, use the 20176command @samp{target mips @var{port}}, where @var{port} is the name of 20177the serial port connected to the board. If the program has not already 20178been downloaded to the board, you may use the @code{load} command to 20179download it. You can then use all the usual @value{GDBN} commands. 20180 20181For example, this sequence connects to the target board through a serial 20182port, and loads and runs a program called @var{prog} through the 20183debugger: 20184 20185@smallexample 20186host$ @value{GDBP} @var{prog} 20187@value{GDBN} is free software and @dots{} 20188(@value{GDBP}) target mips /dev/ttyb 20189(@value{GDBP}) load @var{prog} 20190(@value{GDBP}) run 20191@end smallexample 20192 20193@item target mips @var{hostname}:@var{portnumber} 20194On some @value{GDBN} host configurations, you can specify a TCP 20195connection (for instance, to a serial line managed by a terminal 20196concentrator) instead of a serial port, using the syntax 20197@samp{@var{hostname}:@var{portnumber}}. 20198 20199@item target pmon @var{port} 20200@kindex target pmon @var{port} 20201PMON ROM monitor. 20202 20203@item target ddb @var{port} 20204@kindex target ddb @var{port} 20205NEC's DDB variant of PMON for Vr4300. 20206 20207@item target lsi @var{port} 20208@kindex target lsi @var{port} 20209LSI variant of PMON. 20210 20211@kindex target r3900 20212@item target r3900 @var{dev} 20213Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. 20214 20215@kindex target array 20216@item target array @var{dev} 20217Array Tech LSI33K RAID controller board. 20218 20219@end table 20220 20221 20222@noindent 20223@value{GDBN} also supports these special commands for @acronym{MIPS} targets: 20224 20225@table @code 20226@item set mipsfpu double 20227@itemx set mipsfpu single 20228@itemx set mipsfpu none 20229@itemx set mipsfpu auto 20230@itemx show mipsfpu 20231@kindex set mipsfpu 20232@kindex show mipsfpu 20233@cindex @acronym{MIPS} remote floating point 20234@cindex floating point, @acronym{MIPS} remote 20235If your target board does not support the @acronym{MIPS} floating point 20236coprocessor, you should use the command @samp{set mipsfpu none} (if you 20237need this, you may wish to put the command in your @value{GDBN} init 20238file). This tells @value{GDBN} how to find the return value of 20239functions which return floating point values. It also allows 20240@value{GDBN} to avoid saving the floating point registers when calling 20241functions on the board. If you are using a floating point coprocessor 20242with only single precision floating point support, as on the @sc{r4650} 20243processor, use the command @samp{set mipsfpu single}. The default 20244double precision floating point coprocessor may be selected using 20245@samp{set mipsfpu double}. 20246 20247In previous versions the only choices were double precision or no 20248floating point, so @samp{set mipsfpu on} will select double precision 20249and @samp{set mipsfpu off} will select no floating point. 20250 20251As usual, you can inquire about the @code{mipsfpu} variable with 20252@samp{show mipsfpu}. 20253 20254@item set timeout @var{seconds} 20255@itemx set retransmit-timeout @var{seconds} 20256@itemx show timeout 20257@itemx show retransmit-timeout 20258@cindex @code{timeout}, @acronym{MIPS} protocol 20259@cindex @code{retransmit-timeout}, @acronym{MIPS} protocol 20260@kindex set timeout 20261@kindex show timeout 20262@kindex set retransmit-timeout 20263@kindex show retransmit-timeout 20264You can control the timeout used while waiting for a packet, in the @acronym{MIPS} 20265remote protocol, with the @code{set timeout @var{seconds}} command. The 20266default is 5 seconds. Similarly, you can control the timeout used while 20267waiting for an acknowledgment of a packet with the @code{set 20268retransmit-timeout @var{seconds}} command. The default is 3 seconds. 20269You can inspect both values with @code{show timeout} and @code{show 20270retransmit-timeout}. (These commands are @emph{only} available when 20271@value{GDBN} is configured for @samp{--target=mips-elf}.) 20272 20273The timeout set by @code{set timeout} does not apply when @value{GDBN} 20274is waiting for your program to stop. In that case, @value{GDBN} waits 20275forever because it has no way of knowing how long the program is going 20276to run before stopping. 20277 20278@item set syn-garbage-limit @var{num} 20279@kindex set syn-garbage-limit@r{, @acronym{MIPS} remote} 20280@cindex synchronize with remote @acronym{MIPS} target 20281Limit the maximum number of characters @value{GDBN} should ignore when 20282it tries to synchronize with the remote target. The default is 10 20283characters. Setting the limit to -1 means there's no limit. 20284 20285@item show syn-garbage-limit 20286@kindex show syn-garbage-limit@r{, @acronym{MIPS} remote} 20287Show the current limit on the number of characters to ignore when 20288trying to synchronize with the remote system. 20289 20290@item set monitor-prompt @var{prompt} 20291@kindex set monitor-prompt@r{, @acronym{MIPS} remote} 20292@cindex remote monitor prompt 20293Tell @value{GDBN} to expect the specified @var{prompt} string from the 20294remote monitor. The default depends on the target: 20295@table @asis 20296@item pmon target 20297@samp{PMON} 20298@item ddb target 20299@samp{NEC010} 20300@item lsi target 20301@samp{PMON>} 20302@end table 20303 20304@item show monitor-prompt 20305@kindex show monitor-prompt@r{, @acronym{MIPS} remote} 20306Show the current strings @value{GDBN} expects as the prompt from the 20307remote monitor. 20308 20309@item set monitor-warnings 20310@kindex set monitor-warnings@r{, @acronym{MIPS} remote} 20311Enable or disable monitor warnings about hardware breakpoints. This 20312has effect only for the @code{lsi} target. When on, @value{GDBN} will 20313display warning messages whose codes are returned by the @code{lsi} 20314PMON monitor for breakpoint commands. 20315 20316@item show monitor-warnings 20317@kindex show monitor-warnings@r{, @acronym{MIPS} remote} 20318Show the current setting of printing monitor warnings. 20319 20320@item pmon @var{command} 20321@kindex pmon@r{, @acronym{MIPS} remote} 20322@cindex send PMON command 20323This command allows sending an arbitrary @var{command} string to the 20324monitor. The monitor must be in debug mode for this to work. 20325@end table 20326 20327@node OpenRISC 1000 20328@subsection OpenRISC 1000 20329@cindex OpenRISC 1000 20330 20331@cindex or1k boards 20332See OR1k Architecture document (@uref{www.opencores.org}) for more information 20333about platform and commands. 20334 20335@table @code 20336 20337@kindex target jtag 20338@item target jtag jtag://@var{host}:@var{port} 20339 20340Connects to remote JTAG server. 20341JTAG remote server can be either an or1ksim or JTAG server, 20342connected via parallel port to the board. 20343 20344Example: @code{target jtag jtag://localhost:9999} 20345 20346@kindex or1ksim 20347@item or1ksim @var{command} 20348If connected to @code{or1ksim} OpenRISC 1000 Architectural 20349Simulator, proprietary commands can be executed. 20350 20351@kindex info or1k spr 20352@item info or1k spr 20353Displays spr groups. 20354 20355@item info or1k spr @var{group} 20356@itemx info or1k spr @var{groupno} 20357Displays register names in selected group. 20358 20359@item info or1k spr @var{group} @var{register} 20360@itemx info or1k spr @var{register} 20361@itemx info or1k spr @var{groupno} @var{registerno} 20362@itemx info or1k spr @var{registerno} 20363Shows information about specified spr register. 20364 20365@kindex spr 20366@item spr @var{group} @var{register} @var{value} 20367@itemx spr @var{register @var{value}} 20368@itemx spr @var{groupno} @var{registerno @var{value}} 20369@itemx spr @var{registerno @var{value}} 20370Writes @var{value} to specified spr register. 20371@end table 20372 20373Some implementations of OpenRISC 1000 Architecture also have hardware trace. 20374It is very similar to @value{GDBN} trace, except it does not interfere with normal 20375program execution and is thus much faster. Hardware breakpoints/watchpoint 20376triggers can be set using: 20377@table @code 20378@item $LEA/$LDATA 20379Load effective address/data 20380@item $SEA/$SDATA 20381Store effective address/data 20382@item $AEA/$ADATA 20383Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA) 20384@item $FETCH 20385Fetch data 20386@end table 20387 20388When triggered, it can capture low level data, like: @code{PC}, @code{LSEA}, 20389@code{LDATA}, @code{SDATA}, @code{READSPR}, @code{WRITESPR}, @code{INSTR}. 20390 20391@code{htrace} commands: 20392@cindex OpenRISC 1000 htrace 20393@table @code 20394@kindex hwatch 20395@item hwatch @var{conditional} 20396Set hardware watchpoint on combination of Load/Store Effective Address(es) 20397or Data. For example: 20398 20399@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)} 20400 20401@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)} 20402 20403@kindex htrace 20404@item htrace info 20405Display information about current HW trace configuration. 20406 20407@item htrace trigger @var{conditional} 20408Set starting criteria for HW trace. 20409 20410@item htrace qualifier @var{conditional} 20411Set acquisition qualifier for HW trace. 20412 20413@item htrace stop @var{conditional} 20414Set HW trace stopping criteria. 20415 20416@item htrace record [@var{data}]* 20417Selects the data to be recorded, when qualifier is met and HW trace was 20418triggered. 20419 20420@item htrace enable 20421@itemx htrace disable 20422Enables/disables the HW trace. 20423 20424@item htrace rewind [@var{filename}] 20425Clears currently recorded trace data. 20426 20427If filename is specified, new trace file is made and any newly collected data 20428will be written there. 20429 20430@item htrace print [@var{start} [@var{len}]] 20431Prints trace buffer, using current record configuration. 20432 20433@item htrace mode continuous 20434Set continuous trace mode. 20435 20436@item htrace mode suspend 20437Set suspend trace mode. 20438 20439@end table 20440 20441@node PowerPC Embedded 20442@subsection PowerPC Embedded 20443 20444@cindex DVC register 20445@value{GDBN} supports using the DVC (Data Value Compare) register to 20446implement in hardware simple hardware watchpoint conditions of the form: 20447 20448@smallexample 20449(@value{GDBP}) watch @var{ADDRESS|VARIABLE} \ 20450 if @var{ADDRESS|VARIABLE} == @var{CONSTANT EXPRESSION} 20451@end smallexample 20452 20453The DVC register will be automatically used when @value{GDBN} detects 20454such pattern in a condition expression, and the created watchpoint uses one 20455debug register (either the @code{exact-watchpoints} option is on and the 20456variable is scalar, or the variable has a length of one byte). This feature 20457is available in native @value{GDBN} running on a Linux kernel version 2.6.34 20458or newer. 20459 20460When running on PowerPC embedded processors, @value{GDBN} automatically uses 20461ranged hardware watchpoints, unless the @code{exact-watchpoints} option is on, 20462in which case watchpoints using only one debug register are created when 20463watching variables of scalar types. 20464 20465You can create an artificial array to watch an arbitrary memory 20466region using one of the following commands (@pxref{Expressions}): 20467 20468@smallexample 20469(@value{GDBP}) watch *((char *) @var{address})@@@var{length} 20470(@value{GDBP}) watch @{char[@var{length}]@} @var{address} 20471@end smallexample 20472 20473PowerPC embedded processors support masked watchpoints. See the discussion 20474about the @code{mask} argument in @ref{Set Watchpoints}. 20475 20476@cindex ranged breakpoint 20477PowerPC embedded processors support hardware accelerated 20478@dfn{ranged breakpoints}. A ranged breakpoint stops execution of 20479the inferior whenever it executes an instruction at any address within 20480the range it specifies. To set a ranged breakpoint in @value{GDBN}, 20481use the @code{break-range} command. 20482 20483@value{GDBN} provides the following PowerPC-specific commands: 20484 20485@table @code 20486@kindex break-range 20487@item break-range @var{start-location}, @var{end-location} 20488Set a breakpoint for an address range. 20489@var{start-location} and @var{end-location} can specify a function name, 20490a line number, an offset of lines from the current line or from the start 20491location, or an address of an instruction (see @ref{Specify Location}, 20492for a list of all the possible ways to specify a @var{location}.) 20493The breakpoint will stop execution of the inferior whenever it 20494executes an instruction at any address within the specified range, 20495(including @var{start-location} and @var{end-location}.) 20496 20497@kindex set powerpc 20498@item set powerpc soft-float 20499@itemx show powerpc soft-float 20500Force @value{GDBN} to use (or not use) a software floating point calling 20501convention. By default, @value{GDBN} selects the calling convention based 20502on the selected architecture and the provided executable file. 20503 20504@item set powerpc vector-abi 20505@itemx show powerpc vector-abi 20506Force @value{GDBN} to use the specified calling convention for vector 20507arguments and return values. The valid options are @samp{auto}; 20508@samp{generic}, to avoid vector registers even if they are present; 20509@samp{altivec}, to use AltiVec registers; and @samp{spe} to use SPE 20510registers. By default, @value{GDBN} selects the calling convention 20511based on the selected architecture and the provided executable file. 20512 20513@item set powerpc exact-watchpoints 20514@itemx show powerpc exact-watchpoints 20515Allow @value{GDBN} to use only one debug register when watching a variable 20516of scalar type, thus assuming that the variable is accessed through the 20517address of its first byte. 20518 20519@kindex target dink32 20520@item target dink32 @var{dev} 20521DINK32 ROM monitor. 20522 20523@kindex target ppcbug 20524@item target ppcbug @var{dev} 20525@kindex target ppcbug1 20526@item target ppcbug1 @var{dev} 20527PPCBUG ROM monitor for PowerPC. 20528 20529@kindex target sds 20530@item target sds @var{dev} 20531SDS monitor, running on a PowerPC board (such as Motorola's ADS). 20532@end table 20533 20534@cindex SDS protocol 20535The following commands specific to the SDS protocol are supported 20536by @value{GDBN}: 20537 20538@table @code 20539@item set sdstimeout @var{nsec} 20540@kindex set sdstimeout 20541Set the timeout for SDS protocol reads to be @var{nsec} seconds. The 20542default is 2 seconds. 20543 20544@item show sdstimeout 20545@kindex show sdstimeout 20546Show the current value of the SDS timeout. 20547 20548@item sds @var{command} 20549@kindex sds@r{, a command} 20550Send the specified @var{command} string to the SDS monitor. 20551@end table 20552 20553 20554@node PA 20555@subsection HP PA Embedded 20556 20557@table @code 20558 20559@kindex target op50n 20560@item target op50n @var{dev} 20561OP50N monitor, running on an OKI HPPA board. 20562 20563@kindex target w89k 20564@item target w89k @var{dev} 20565W89K monitor, running on a Winbond HPPA board. 20566 20567@end table 20568 20569@node Sparclet 20570@subsection Tsqware Sparclet 20571 20572@cindex Sparclet 20573 20574@value{GDBN} enables developers to debug tasks running on 20575Sparclet targets from a Unix host. 20576@value{GDBN} uses code that runs on 20577both the Unix host and on the Sparclet target. The program 20578@code{@value{GDBP}} is installed and executed on the Unix host. 20579 20580@table @code 20581@item remotetimeout @var{args} 20582@kindex remotetimeout 20583@value{GDBN} supports the option @code{remotetimeout}. 20584This option is set by the user, and @var{args} represents the number of 20585seconds @value{GDBN} waits for responses. 20586@end table 20587 20588@cindex compiling, on Sparclet 20589When compiling for debugging, include the options @samp{-g} to get debug 20590information and @samp{-Ttext} to relocate the program to where you wish to 20591load it on the target. You may also want to add the options @samp{-n} or 20592@samp{-N} in order to reduce the size of the sections. Example: 20593 20594@smallexample 20595sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N 20596@end smallexample 20597 20598You can use @code{objdump} to verify that the addresses are what you intended: 20599 20600@smallexample 20601sparclet-aout-objdump --headers --syms prog 20602@end smallexample 20603 20604@cindex running, on Sparclet 20605Once you have set 20606your Unix execution search path to find @value{GDBN}, you are ready to 20607run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} 20608(or @code{sparclet-aout-gdb}, depending on your installation). 20609 20610@value{GDBN} comes up showing the prompt: 20611 20612@smallexample 20613(gdbslet) 20614@end smallexample 20615 20616@menu 20617* Sparclet File:: Setting the file to debug 20618* Sparclet Connection:: Connecting to Sparclet 20619* Sparclet Download:: Sparclet download 20620* Sparclet Execution:: Running and debugging 20621@end menu 20622 20623@node Sparclet File 20624@subsubsection Setting File to Debug 20625 20626The @value{GDBN} command @code{file} lets you choose with program to debug. 20627 20628@smallexample 20629(gdbslet) file prog 20630@end smallexample 20631 20632@need 1000 20633@value{GDBN} then attempts to read the symbol table of @file{prog}. 20634@value{GDBN} locates 20635the file by searching the directories listed in the command search 20636path. 20637If the file was compiled with debug information (option @samp{-g}), source 20638files will be searched as well. 20639@value{GDBN} locates 20640the source files by searching the directories listed in the directory search 20641path (@pxref{Environment, ,Your Program's Environment}). 20642If it fails 20643to find a file, it displays a message such as: 20644 20645@smallexample 20646prog: No such file or directory. 20647@end smallexample 20648 20649When this happens, add the appropriate directories to the search paths with 20650the @value{GDBN} commands @code{path} and @code{dir}, and execute the 20651@code{target} command again. 20652 20653@node Sparclet Connection 20654@subsubsection Connecting to Sparclet 20655 20656The @value{GDBN} command @code{target} lets you connect to a Sparclet target. 20657To connect to a target on serial port ``@code{ttya}'', type: 20658 20659@smallexample 20660(gdbslet) target sparclet /dev/ttya 20661Remote target sparclet connected to /dev/ttya 20662main () at ../prog.c:3 20663@end smallexample 20664 20665@need 750 20666@value{GDBN} displays messages like these: 20667 20668@smallexample 20669Connected to ttya. 20670@end smallexample 20671 20672@node Sparclet Download 20673@subsubsection Sparclet Download 20674 20675@cindex download to Sparclet 20676Once connected to the Sparclet target, 20677you can use the @value{GDBN} 20678@code{load} command to download the file from the host to the target. 20679The file name and load offset should be given as arguments to the @code{load} 20680command. 20681Since the file format is aout, the program must be loaded to the starting 20682address. You can use @code{objdump} to find out what this value is. The load 20683offset is an offset which is added to the VMA (virtual memory address) 20684of each of the file's sections. 20685For instance, if the program 20686@file{prog} was linked to text address 0x1201000, with data at 0x12010160 20687and bss at 0x12010170, in @value{GDBN}, type: 20688 20689@smallexample 20690(gdbslet) load prog 0x12010000 20691Loading section .text, size 0xdb0 vma 0x12010000 20692@end smallexample 20693 20694If the code is loaded at a different address then what the program was linked 20695to, you may need to use the @code{section} and @code{add-symbol-file} commands 20696to tell @value{GDBN} where to map the symbol table. 20697 20698@node Sparclet Execution 20699@subsubsection Running and Debugging 20700 20701@cindex running and debugging Sparclet programs 20702You can now begin debugging the task using @value{GDBN}'s execution control 20703commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN} 20704manual for the list of commands. 20705 20706@smallexample 20707(gdbslet) b main 20708Breakpoint 1 at 0x12010000: file prog.c, line 3. 20709(gdbslet) run 20710Starting program: prog 20711Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 207123 char *symarg = 0; 20713(gdbslet) step 207144 char *execarg = "hello!"; 20715(gdbslet) 20716@end smallexample 20717 20718@node Sparclite 20719@subsection Fujitsu Sparclite 20720 20721@table @code 20722 20723@kindex target sparclite 20724@item target sparclite @var{dev} 20725Fujitsu sparclite boards, used only for the purpose of loading. 20726You must use an additional command to debug the program. 20727For example: target remote @var{dev} using @value{GDBN} standard 20728remote protocol. 20729 20730@end table 20731 20732@node Z8000 20733@subsection Zilog Z8000 20734 20735@cindex Z8000 20736@cindex simulator, Z8000 20737@cindex Zilog Z8000 simulator 20738 20739When configured for debugging Zilog Z8000 targets, @value{GDBN} includes 20740a Z8000 simulator. 20741 20742For the Z8000 family, @samp{target sim} simulates either the Z8002 (the 20743unsegmented variant of the Z8000 architecture) or the Z8001 (the 20744segmented variant). The simulator recognizes which architecture is 20745appropriate by inspecting the object code. 20746 20747@table @code 20748@item target sim @var{args} 20749@kindex sim 20750@kindex target sim@r{, with Z8000} 20751Debug programs on a simulated CPU. If the simulator supports setup 20752options, specify them via @var{args}. 20753@end table 20754 20755@noindent 20756After specifying this target, you can debug programs for the simulated 20757CPU in the same style as programs for your host computer; use the 20758@code{file} command to load a new program image, the @code{run} command 20759to run your program, and so on. 20760 20761As well as making available all the usual machine registers 20762(@pxref{Registers, ,Registers}), the Z8000 simulator provides three 20763additional items of information as specially named registers: 20764 20765@table @code 20766 20767@item cycles 20768Counts clock-ticks in the simulator. 20769 20770@item insts 20771Counts instructions run in the simulator. 20772 20773@item time 20774Execution time in 60ths of a second. 20775 20776@end table 20777 20778You can refer to these values in @value{GDBN} expressions with the usual 20779conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a 20780conditional breakpoint that suspends only after at least 5000 20781simulated clock ticks. 20782 20783@node AVR 20784@subsection Atmel AVR 20785@cindex AVR 20786 20787When configured for debugging the Atmel AVR, @value{GDBN} supports the 20788following AVR-specific commands: 20789 20790@table @code 20791@item info io_registers 20792@kindex info io_registers@r{, AVR} 20793@cindex I/O registers (Atmel AVR) 20794This command displays information about the AVR I/O registers. For 20795each register, @value{GDBN} prints its number and value. 20796@end table 20797 20798@node CRIS 20799@subsection CRIS 20800@cindex CRIS 20801 20802When configured for debugging CRIS, @value{GDBN} provides the 20803following CRIS-specific commands: 20804 20805@table @code 20806@item set cris-version @var{ver} 20807@cindex CRIS version 20808Set the current CRIS version to @var{ver}, either @samp{10} or @samp{32}. 20809The CRIS version affects register names and sizes. This command is useful in 20810case autodetection of the CRIS version fails. 20811 20812@item show cris-version 20813Show the current CRIS version. 20814 20815@item set cris-dwarf2-cfi 20816@cindex DWARF-2 CFI and CRIS 20817Set the usage of DWARF-2 CFI for CRIS debugging. The default is @samp{on}. 20818Change to @samp{off} when using @code{gcc-cris} whose version is below 20819@code{R59}. 20820 20821@item show cris-dwarf2-cfi 20822Show the current state of using DWARF-2 CFI. 20823 20824@item set cris-mode @var{mode} 20825@cindex CRIS mode 20826Set the current CRIS mode to @var{mode}. It should only be changed when 20827debugging in guru mode, in which case it should be set to 20828@samp{guru} (the default is @samp{normal}). 20829 20830@item show cris-mode 20831Show the current CRIS mode. 20832@end table 20833 20834@node Super-H 20835@subsection Renesas Super-H 20836@cindex Super-H 20837 20838For the Renesas Super-H processor, @value{GDBN} provides these 20839commands: 20840 20841@table @code 20842@item set sh calling-convention @var{convention} 20843@kindex set sh calling-convention 20844Set the calling-convention used when calling functions from @value{GDBN}. 20845Allowed values are @samp{gcc}, which is the default setting, and @samp{renesas}. 20846With the @samp{gcc} setting, functions are called using the @value{NGCC} calling 20847convention. If the DWARF-2 information of the called function specifies 20848that the function follows the Renesas calling convention, the function 20849is called using the Renesas calling convention. If the calling convention 20850is set to @samp{renesas}, the Renesas calling convention is always used, 20851regardless of the DWARF-2 information. This can be used to override the 20852default of @samp{gcc} if debug information is missing, or the compiler 20853does not emit the DWARF-2 calling convention entry for a function. 20854 20855@item show sh calling-convention 20856@kindex show sh calling-convention 20857Show the current calling convention setting. 20858 20859@end table 20860 20861 20862@node Architectures 20863@section Architectures 20864 20865This section describes characteristics of architectures that affect 20866all uses of @value{GDBN} with the architecture, both native and cross. 20867 20868@menu 20869* AArch64:: 20870* i386:: 20871* Alpha:: 20872* MIPS:: 20873* HPPA:: HP PA architecture 20874* SPU:: Cell Broadband Engine SPU architecture 20875* PowerPC:: 20876@end menu 20877 20878@node AArch64 20879@subsection AArch64 20880@cindex AArch64 support 20881 20882When @value{GDBN} is debugging the AArch64 architecture, it provides the 20883following special commands: 20884 20885@table @code 20886@item set debug aarch64 20887@kindex set debug aarch64 20888This command determines whether AArch64 architecture-specific debugging 20889messages are to be displayed. 20890 20891@item show debug aarch64 20892Show whether AArch64 debugging messages are displayed. 20893 20894@end table 20895 20896@node i386 20897@subsection x86 Architecture-specific Issues 20898 20899@table @code 20900@item set struct-convention @var{mode} 20901@kindex set struct-convention 20902@cindex struct return convention 20903@cindex struct/union returned in registers 20904Set the convention used by the inferior to return @code{struct}s and 20905@code{union}s from functions to @var{mode}. Possible values of 20906@var{mode} are @code{"pcc"}, @code{"reg"}, and @code{"default"} (the 20907default). @code{"default"} or @code{"pcc"} means that @code{struct}s 20908are returned on the stack, while @code{"reg"} means that a 20909@code{struct} or a @code{union} whose size is 1, 2, 4, or 8 bytes will 20910be returned in a register. 20911 20912@item show struct-convention 20913@kindex show struct-convention 20914Show the current setting of the convention to return @code{struct}s 20915from functions. 20916@end table 20917 20918@node Alpha 20919@subsection Alpha 20920 20921See the following section. 20922 20923@node MIPS 20924@subsection @acronym{MIPS} 20925 20926@cindex stack on Alpha 20927@cindex stack on @acronym{MIPS} 20928@cindex Alpha stack 20929@cindex @acronym{MIPS} stack 20930Alpha- and @acronym{MIPS}-based computers use an unusual stack frame, which 20931sometimes requires @value{GDBN} to search backward in the object code to 20932find the beginning of a function. 20933 20934@cindex response time, @acronym{MIPS} debugging 20935To improve response time (especially for embedded applications, where 20936@value{GDBN} may be restricted to a slow serial line for this search) 20937you may want to limit the size of this search, using one of these 20938commands: 20939 20940@table @code 20941@cindex @code{heuristic-fence-post} (Alpha, @acronym{MIPS}) 20942@item set heuristic-fence-post @var{limit} 20943Restrict @value{GDBN} to examining at most @var{limit} bytes in its 20944search for the beginning of a function. A value of @var{0} (the 20945default) means there is no limit. However, except for @var{0}, the 20946larger the limit the more bytes @code{heuristic-fence-post} must search 20947and therefore the longer it takes to run. You should only need to use 20948this command when debugging a stripped executable. 20949 20950@item show heuristic-fence-post 20951Display the current limit. 20952@end table 20953 20954@noindent 20955These commands are available @emph{only} when @value{GDBN} is configured 20956for debugging programs on Alpha or @acronym{MIPS} processors. 20957 20958Several @acronym{MIPS}-specific commands are available when debugging @acronym{MIPS} 20959programs: 20960 20961@table @code 20962@item set mips abi @var{arg} 20963@kindex set mips abi 20964@cindex set ABI for @acronym{MIPS} 20965Tell @value{GDBN} which @acronym{MIPS} ABI is used by the inferior. Possible 20966values of @var{arg} are: 20967 20968@table @samp 20969@item auto 20970The default ABI associated with the current binary (this is the 20971default). 20972@item o32 20973@item o64 20974@item n32 20975@item n64 20976@item eabi32 20977@item eabi64 20978@end table 20979 20980@item show mips abi 20981@kindex show mips abi 20982Show the @acronym{MIPS} ABI used by @value{GDBN} to debug the inferior. 20983 20984@item set mips compression @var{arg} 20985@kindex set mips compression 20986@cindex code compression, @acronym{MIPS} 20987Tell @value{GDBN} which @acronym{MIPS} compressed 20988@acronym{ISA, Instruction Set Architecture} encoding is used by the 20989inferior. @value{GDBN} uses this for code disassembly and other 20990internal interpretation purposes. This setting is only referred to 20991when no executable has been associated with the debugging session or 20992the executable does not provide information about the encoding it uses. 20993Otherwise this setting is automatically updated from information 20994provided by the executable. 20995 20996Possible values of @var{arg} are @samp{mips16} and @samp{micromips}. 20997The default compressed @acronym{ISA} encoding is @samp{mips16}, as 20998executables containing @acronym{MIPS16} code frequently are not 20999identified as such. 21000 21001This setting is ``sticky''; that is, it retains its value across 21002debugging sessions until reset either explicitly with this command or 21003implicitly from an executable. 21004 21005The compiler and/or assembler typically add symbol table annotations to 21006identify functions compiled for the @acronym{MIPS16} or 21007@acronym{microMIPS} @acronym{ISA}s. If these function-scope annotations 21008are present, @value{GDBN} uses them in preference to the global 21009compressed @acronym{ISA} encoding setting. 21010 21011@item show mips compression 21012@kindex show mips compression 21013Show the @acronym{MIPS} compressed @acronym{ISA} encoding used by 21014@value{GDBN} to debug the inferior. 21015 21016@item set mipsfpu 21017@itemx show mipsfpu 21018@xref{MIPS Embedded, set mipsfpu}. 21019 21020@item set mips mask-address @var{arg} 21021@kindex set mips mask-address 21022@cindex @acronym{MIPS} addresses, masking 21023This command determines whether the most-significant 32 bits of 64-bit 21024@acronym{MIPS} addresses are masked off. The argument @var{arg} can be 21025@samp{on}, @samp{off}, or @samp{auto}. The latter is the default 21026setting, which lets @value{GDBN} determine the correct value. 21027 21028@item show mips mask-address 21029@kindex show mips mask-address 21030Show whether the upper 32 bits of @acronym{MIPS} addresses are masked off or 21031not. 21032 21033@item set remote-mips64-transfers-32bit-regs 21034@kindex set remote-mips64-transfers-32bit-regs 21035This command controls compatibility with 64-bit @acronym{MIPS} targets that 21036transfer data in 32-bit quantities. If you have an old @acronym{MIPS} 64 target 21037that transfers 32 bits for some registers, like @sc{sr} and @sc{fsr}, 21038and 64 bits for other registers, set this option to @samp{on}. 21039 21040@item show remote-mips64-transfers-32bit-regs 21041@kindex show remote-mips64-transfers-32bit-regs 21042Show the current setting of compatibility with older @acronym{MIPS} 64 targets. 21043 21044@item set debug mips 21045@kindex set debug mips 21046This command turns on and off debugging messages for the @acronym{MIPS}-specific 21047target code in @value{GDBN}. 21048 21049@item show debug mips 21050@kindex show debug mips 21051Show the current setting of @acronym{MIPS} debugging messages. 21052@end table 21053 21054 21055@node HPPA 21056@subsection HPPA 21057@cindex HPPA support 21058 21059When @value{GDBN} is debugging the HP PA architecture, it provides the 21060following special commands: 21061 21062@table @code 21063@item set debug hppa 21064@kindex set debug hppa 21065This command determines whether HPPA architecture-specific debugging 21066messages are to be displayed. 21067 21068@item show debug hppa 21069Show whether HPPA debugging messages are displayed. 21070 21071@item maint print unwind @var{address} 21072@kindex maint print unwind@r{, HPPA} 21073This command displays the contents of the unwind table entry at the 21074given @var{address}. 21075 21076@end table 21077 21078 21079@node SPU 21080@subsection Cell Broadband Engine SPU architecture 21081@cindex Cell Broadband Engine 21082@cindex SPU 21083 21084When @value{GDBN} is debugging the Cell Broadband Engine SPU architecture, 21085it provides the following special commands: 21086 21087@table @code 21088@item info spu event 21089@kindex info spu 21090Display SPU event facility status. Shows current event mask 21091and pending event status. 21092 21093@item info spu signal 21094Display SPU signal notification facility status. Shows pending 21095signal-control word and signal notification mode of both signal 21096notification channels. 21097 21098@item info spu mailbox 21099Display SPU mailbox facility status. Shows all pending entries, 21100in order of processing, in each of the SPU Write Outbound, 21101SPU Write Outbound Interrupt, and SPU Read Inbound mailboxes. 21102 21103@item info spu dma 21104Display MFC DMA status. Shows all pending commands in the MFC 21105DMA queue. For each entry, opcode, tag, class IDs, effective 21106and local store addresses and transfer size are shown. 21107 21108@item info spu proxydma 21109Display MFC Proxy-DMA status. Shows all pending commands in the MFC 21110Proxy-DMA queue. For each entry, opcode, tag, class IDs, effective 21111and local store addresses and transfer size are shown. 21112 21113@end table 21114 21115When @value{GDBN} is debugging a combined PowerPC/SPU application 21116on the Cell Broadband Engine, it provides in addition the following 21117special commands: 21118 21119@table @code 21120@item set spu stop-on-load @var{arg} 21121@kindex set spu 21122Set whether to stop for new SPE threads. When set to @code{on}, @value{GDBN} 21123will give control to the user when a new SPE thread enters its @code{main} 21124function. The default is @code{off}. 21125 21126@item show spu stop-on-load 21127@kindex show spu 21128Show whether to stop for new SPE threads. 21129 21130@item set spu auto-flush-cache @var{arg} 21131Set whether to automatically flush the software-managed cache. When set to 21132@code{on}, @value{GDBN} will automatically cause the SPE software-managed 21133cache to be flushed whenever SPE execution stops. This provides a consistent 21134view of PowerPC memory that is accessed via the cache. If an application 21135does not use the software-managed cache, this option has no effect. 21136 21137@item show spu auto-flush-cache 21138Show whether to automatically flush the software-managed cache. 21139 21140@end table 21141 21142@node PowerPC 21143@subsection PowerPC 21144@cindex PowerPC architecture 21145 21146When @value{GDBN} is debugging the PowerPC architecture, it provides a set of 21147pseudo-registers to enable inspection of 128-bit wide Decimal Floating Point 21148numbers stored in the floating point registers. These values must be stored 21149in two consecutive registers, always starting at an even register like 21150@code{f0} or @code{f2}. 21151 21152The pseudo-registers go from @code{$dl0} through @code{$dl15}, and are formed 21153by joining the even/odd register pairs @code{f0} and @code{f1} for @code{$dl0}, 21154@code{f2} and @code{f3} for @code{$dl1} and so on. 21155 21156For POWER7 processors, @value{GDBN} provides a set of pseudo-registers, the 64-bit 21157wide Extended Floating Point Registers (@samp{f32} through @samp{f63}). 21158 21159 21160@node Controlling GDB 21161@chapter Controlling @value{GDBN} 21162 21163You can alter the way @value{GDBN} interacts with you by using the 21164@code{set} command. For commands controlling how @value{GDBN} displays 21165data, see @ref{Print Settings, ,Print Settings}. Other settings are 21166described here. 21167 21168@menu 21169* Prompt:: Prompt 21170* Editing:: Command editing 21171* Command History:: Command history 21172* Screen Size:: Screen size 21173* Numbers:: Numbers 21174* ABI:: Configuring the current ABI 21175* Auto-loading:: Automatically loading associated files 21176* Messages/Warnings:: Optional warnings and messages 21177* Debugging Output:: Optional messages about internal happenings 21178* Other Misc Settings:: Other Miscellaneous Settings 21179@end menu 21180 21181@node Prompt 21182@section Prompt 21183 21184@cindex prompt 21185 21186@value{GDBN} indicates its readiness to read a command by printing a string 21187called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You 21188can change the prompt string with the @code{set prompt} command. For 21189instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change 21190the prompt in one of the @value{GDBN} sessions so that you can always tell 21191which one you are talking to. 21192 21193@emph{Note:} @code{set prompt} does not add a space for you after the 21194prompt you set. This allows you to set a prompt which ends in a space 21195or a prompt that does not. 21196 21197@table @code 21198@kindex set prompt 21199@item set prompt @var{newprompt} 21200Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth. 21201 21202@kindex show prompt 21203@item show prompt 21204Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}} 21205@end table 21206 21207Versions of @value{GDBN} that ship with Python scripting enabled have 21208prompt extensions. The commands for interacting with these extensions 21209are: 21210 21211@table @code 21212@kindex set extended-prompt 21213@item set extended-prompt @var{prompt} 21214Set an extended prompt that allows for substitutions. 21215@xref{gdb.prompt}, for a list of escape sequences that can be used for 21216substitution. Any escape sequences specified as part of the prompt 21217string are replaced with the corresponding strings each time the prompt 21218is displayed. 21219 21220For example: 21221 21222@smallexample 21223set extended-prompt Current working directory: \w (gdb) 21224@end smallexample 21225 21226Note that when an extended-prompt is set, it takes control of the 21227@var{prompt_hook} hook. @xref{prompt_hook}, for further information. 21228 21229@kindex show extended-prompt 21230@item show extended-prompt 21231Prints the extended prompt. Any escape sequences specified as part of 21232the prompt string with @code{set extended-prompt}, are replaced with the 21233corresponding strings each time the prompt is displayed. 21234@end table 21235 21236@node Editing 21237@section Command Editing 21238@cindex readline 21239@cindex command line editing 21240 21241@value{GDBN} reads its input commands via the @dfn{Readline} interface. This 21242@sc{gnu} library provides consistent behavior for programs which provide a 21243command line interface to the user. Advantages are @sc{gnu} Emacs-style 21244or @dfn{vi}-style inline editing of commands, @code{csh}-like history 21245substitution, and a storage and recall of command history across 21246debugging sessions. 21247 21248You may control the behavior of command line editing in @value{GDBN} with the 21249command @code{set}. 21250 21251@table @code 21252@kindex set editing 21253@cindex editing 21254@item set editing 21255@itemx set editing on 21256Enable command line editing (enabled by default). 21257 21258@item set editing off 21259Disable command line editing. 21260 21261@kindex show editing 21262@item show editing 21263Show whether command line editing is enabled. 21264@end table 21265 21266@ifset SYSTEM_READLINE 21267@xref{Command Line Editing, , , rluserman, GNU Readline Library}, 21268@end ifset 21269@ifclear SYSTEM_READLINE 21270@xref{Command Line Editing}, 21271@end ifclear 21272for more details about the Readline 21273interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are 21274encouraged to read that chapter. 21275 21276@node Command History 21277@section Command History 21278@cindex command history 21279 21280@value{GDBN} can keep track of the commands you type during your 21281debugging sessions, so that you can be certain of precisely what 21282happened. Use these commands to manage the @value{GDBN} command 21283history facility. 21284 21285@value{GDBN} uses the @sc{gnu} History library, a part of the Readline 21286package, to provide the history facility. 21287@ifset SYSTEM_READLINE 21288@xref{Using History Interactively, , , history, GNU History Library}, 21289@end ifset 21290@ifclear SYSTEM_READLINE 21291@xref{Using History Interactively}, 21292@end ifclear 21293for the detailed description of the History library. 21294 21295To issue a command to @value{GDBN} without affecting certain aspects of 21296the state which is seen by users, prefix it with @samp{server } 21297(@pxref{Server Prefix}). This 21298means that this command will not affect the command history, nor will it 21299affect @value{GDBN}'s notion of which command to repeat if @key{RET} is 21300pressed on a line by itself. 21301 21302@cindex @code{server}, command prefix 21303The server prefix does not affect the recording of values into the value 21304history; to print a value without recording it into the value history, 21305use the @code{output} command instead of the @code{print} command. 21306 21307Here is the description of @value{GDBN} commands related to command 21308history. 21309 21310@table @code 21311@cindex history substitution 21312@cindex history file 21313@kindex set history filename 21314@cindex @env{GDBHISTFILE}, environment variable 21315@item set history filename @var{fname} 21316Set the name of the @value{GDBN} command history file to @var{fname}. 21317This is the file where @value{GDBN} reads an initial command history 21318list, and where it writes the command history from this session when it 21319exits. You can access this list through history expansion or through 21320the history command editing characters listed below. This file defaults 21321to the value of the environment variable @code{GDBHISTFILE}, or to 21322@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable 21323is not set. 21324 21325@cindex save command history 21326@kindex set history save 21327@item set history save 21328@itemx set history save on 21329Record command history in a file, whose name may be specified with the 21330@code{set history filename} command. By default, this option is disabled. 21331 21332@item set history save off 21333Stop recording command history in a file. 21334 21335@cindex history size 21336@kindex set history size 21337@cindex @env{HISTSIZE}, environment variable 21338@item set history size @var{size} 21339Set the number of commands which @value{GDBN} keeps in its history list. 21340This defaults to the value of the environment variable 21341@code{HISTSIZE}, or to 256 if this variable is not set. 21342@end table 21343 21344History expansion assigns special meaning to the character @kbd{!}. 21345@ifset SYSTEM_READLINE 21346@xref{Event Designators, , , history, GNU History Library}, 21347@end ifset 21348@ifclear SYSTEM_READLINE 21349@xref{Event Designators}, 21350@end ifclear 21351for more details. 21352 21353@cindex history expansion, turn on/off 21354Since @kbd{!} is also the logical not operator in C, history expansion 21355is off by default. If you decide to enable history expansion with the 21356@code{set history expansion on} command, you may sometimes need to 21357follow @kbd{!} (when it is used as logical not, in an expression) with 21358a space or a tab to prevent it from being expanded. The readline 21359history facilities do not attempt substitution on the strings 21360@kbd{!=} and @kbd{!(}, even when history expansion is enabled. 21361 21362The commands to control history expansion are: 21363 21364@table @code 21365@item set history expansion on 21366@itemx set history expansion 21367@kindex set history expansion 21368Enable history expansion. History expansion is off by default. 21369 21370@item set history expansion off 21371Disable history expansion. 21372 21373@c @group 21374@kindex show history 21375@item show history 21376@itemx show history filename 21377@itemx show history save 21378@itemx show history size 21379@itemx show history expansion 21380These commands display the state of the @value{GDBN} history parameters. 21381@code{show history} by itself displays all four states. 21382@c @end group 21383@end table 21384 21385@table @code 21386@kindex show commands 21387@cindex show last commands 21388@cindex display command history 21389@item show commands 21390Display the last ten commands in the command history. 21391 21392@item show commands @var{n} 21393Print ten commands centered on command number @var{n}. 21394 21395@item show commands + 21396Print ten commands just after the commands last printed. 21397@end table 21398 21399@node Screen Size 21400@section Screen Size 21401@cindex size of screen 21402@cindex pauses in output 21403 21404Certain commands to @value{GDBN} may produce large amounts of 21405information output to the screen. To help you read all of it, 21406@value{GDBN} pauses and asks you for input at the end of each page of 21407output. Type @key{RET} when you want to continue the output, or @kbd{q} 21408to discard the remaining output. Also, the screen width setting 21409determines when to wrap lines of output. Depending on what is being 21410printed, @value{GDBN} tries to break the line at a readable place, 21411rather than simply letting it overflow onto the following line. 21412 21413Normally @value{GDBN} knows the size of the screen from the terminal 21414driver software. For example, on Unix @value{GDBN} uses the termcap data base 21415together with the value of the @code{TERM} environment variable and the 21416@code{stty rows} and @code{stty cols} settings. If this is not correct, 21417you can override it with the @code{set height} and @code{set 21418width} commands: 21419 21420@table @code 21421@kindex set height 21422@kindex set width 21423@kindex show width 21424@kindex show height 21425@item set height @var{lpp} 21426@itemx show height 21427@itemx set width @var{cpl} 21428@itemx show width 21429These @code{set} commands specify a screen height of @var{lpp} lines and 21430a screen width of @var{cpl} characters. The associated @code{show} 21431commands display the current settings. 21432 21433If you specify a height of zero lines, @value{GDBN} does not pause during 21434output no matter how long the output is. This is useful if output is to a 21435file or to an editor buffer. 21436 21437Likewise, you can specify @samp{set width 0} to prevent @value{GDBN} 21438from wrapping its output. 21439 21440@item set pagination on 21441@itemx set pagination off 21442@kindex set pagination 21443Turn the output pagination on or off; the default is on. Turning 21444pagination off is the alternative to @code{set height 0}. Note that 21445running @value{GDBN} with the @option{--batch} option (@pxref{Mode 21446Options, -batch}) also automatically disables pagination. 21447 21448@item show pagination 21449@kindex show pagination 21450Show the current pagination mode. 21451@end table 21452 21453@node Numbers 21454@section Numbers 21455@cindex number representation 21456@cindex entering numbers 21457 21458You can always enter numbers in octal, decimal, or hexadecimal in 21459@value{GDBN} by the usual conventions: octal numbers begin with 21460@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers 21461begin with @samp{0x}. Numbers that neither begin with @samp{0} or 21462@samp{0x}, nor end with a @samp{.} are, by default, entered in base 2146310; likewise, the default display for numbers---when no particular 21464format is specified---is base 10. You can change the default base for 21465both input and output with the commands described below. 21466 21467@table @code 21468@kindex set input-radix 21469@item set input-radix @var{base} 21470Set the default base for numeric input. Supported choices 21471for @var{base} are decimal 8, 10, or 16. @var{base} must itself be 21472specified either unambiguously or using the current input radix; for 21473example, any of 21474 21475@smallexample 21476set input-radix 012 21477set input-radix 10. 21478set input-radix 0xa 21479@end smallexample 21480 21481@noindent 21482sets the input base to decimal. On the other hand, @samp{set input-radix 10} 21483leaves the input radix unchanged, no matter what it was, since 21484@samp{10}, being without any leading or trailing signs of its base, is 21485interpreted in the current radix. Thus, if the current radix is 16, 21486@samp{10} is interpreted in hex, i.e.@: as 16 decimal, which doesn't 21487change the radix. 21488 21489@kindex set output-radix 21490@item set output-radix @var{base} 21491Set the default base for numeric display. Supported choices 21492for @var{base} are decimal 8, 10, or 16. @var{base} must itself be 21493specified either unambiguously or using the current input radix. 21494 21495@kindex show input-radix 21496@item show input-radix 21497Display the current default base for numeric input. 21498 21499@kindex show output-radix 21500@item show output-radix 21501Display the current default base for numeric display. 21502 21503@item set radix @r{[}@var{base}@r{]} 21504@itemx show radix 21505@kindex set radix 21506@kindex show radix 21507These commands set and show the default base for both input and output 21508of numbers. @code{set radix} sets the radix of input and output to 21509the same base; without an argument, it resets the radix back to its 21510default value of 10. 21511 21512@end table 21513 21514@node ABI 21515@section Configuring the Current ABI 21516 21517@value{GDBN} can determine the @dfn{ABI} (Application Binary Interface) of your 21518application automatically. However, sometimes you need to override its 21519conclusions. Use these commands to manage @value{GDBN}'s view of the 21520current ABI. 21521 21522@cindex OS ABI 21523@kindex set osabi 21524@kindex show osabi 21525@cindex Newlib OS ABI and its influence on the longjmp handling 21526 21527One @value{GDBN} configuration can debug binaries for multiple operating 21528system targets, either via remote debugging or native emulation. 21529@value{GDBN} will autodetect the @dfn{OS ABI} (Operating System ABI) in use, 21530but you can override its conclusion using the @code{set osabi} command. 21531One example where this is useful is in debugging of binaries which use 21532an alternate C library (e.g.@: @sc{uClibc} for @sc{gnu}/Linux) which does 21533not have the same identifying marks that the standard C library for your 21534platform provides. 21535 21536When @value{GDBN} is debugging the AArch64 architecture, it provides a 21537``Newlib'' OS ABI. This is useful for handling @code{setjmp} and 21538@code{longjmp} when debugging binaries that use the @sc{newlib} C library. 21539The ``Newlib'' OS ABI can be selected by @code{set osabi Newlib}. 21540 21541@table @code 21542@item show osabi 21543Show the OS ABI currently in use. 21544 21545@item set osabi 21546With no argument, show the list of registered available OS ABI's. 21547 21548@item set osabi @var{abi} 21549Set the current OS ABI to @var{abi}. 21550@end table 21551 21552@cindex float promotion 21553 21554Generally, the way that an argument of type @code{float} is passed to a 21555function depends on whether the function is prototyped. For a prototyped 21556(i.e.@: ANSI/ISO style) function, @code{float} arguments are passed unchanged, 21557according to the architecture's convention for @code{float}. For unprototyped 21558(i.e.@: K&R style) functions, @code{float} arguments are first promoted to type 21559@code{double} and then passed. 21560 21561Unfortunately, some forms of debug information do not reliably indicate whether 21562a function is prototyped. If @value{GDBN} calls a function that is not marked 21563as prototyped, it consults @kbd{set coerce-float-to-double}. 21564 21565@table @code 21566@kindex set coerce-float-to-double 21567@item set coerce-float-to-double 21568@itemx set coerce-float-to-double on 21569Arguments of type @code{float} will be promoted to @code{double} when passed 21570to an unprototyped function. This is the default setting. 21571 21572@item set coerce-float-to-double off 21573Arguments of type @code{float} will be passed directly to unprototyped 21574functions. 21575 21576@kindex show coerce-float-to-double 21577@item show coerce-float-to-double 21578Show the current setting of promoting @code{float} to @code{double}. 21579@end table 21580 21581@kindex set cp-abi 21582@kindex show cp-abi 21583@value{GDBN} needs to know the ABI used for your program's C@t{++} 21584objects. The correct C@t{++} ABI depends on which C@t{++} compiler was 21585used to build your application. @value{GDBN} only fully supports 21586programs with a single C@t{++} ABI; if your program contains code using 21587multiple C@t{++} ABI's or if @value{GDBN} can not identify your 21588program's ABI correctly, you can tell @value{GDBN} which ABI to use. 21589Currently supported ABI's include ``gnu-v2'', for @code{g++} versions 21590before 3.0, ``gnu-v3'', for @code{g++} versions 3.0 and later, and 21591``hpaCC'' for the HP ANSI C@t{++} compiler. Other C@t{++} compilers may 21592use the ``gnu-v2'' or ``gnu-v3'' ABI's as well. The default setting is 21593``auto''. 21594 21595@table @code 21596@item show cp-abi 21597Show the C@t{++} ABI currently in use. 21598 21599@item set cp-abi 21600With no argument, show the list of supported C@t{++} ABI's. 21601 21602@item set cp-abi @var{abi} 21603@itemx set cp-abi auto 21604Set the current C@t{++} ABI to @var{abi}, or return to automatic detection. 21605@end table 21606 21607@node Auto-loading 21608@section Automatically loading associated files 21609@cindex auto-loading 21610 21611@value{GDBN} sometimes reads files with commands and settings automatically, 21612without being explicitly told so by the user. We call this feature 21613@dfn{auto-loading}. While auto-loading is useful for automatically adapting 21614@value{GDBN} to the needs of your project, it can sometimes produce unexpected 21615results or introduce security risks (e.g., if the file comes from untrusted 21616sources). 21617 21618Note that loading of these associated files (including the local @file{.gdbinit} 21619file) requires accordingly configured @code{auto-load safe-path} 21620(@pxref{Auto-loading safe path}). 21621 21622For these reasons, @value{GDBN} includes commands and options to let you 21623control when to auto-load files and which files should be auto-loaded. 21624 21625@table @code 21626@anchor{set auto-load off} 21627@kindex set auto-load off 21628@item set auto-load off 21629Globally disable loading of all auto-loaded files. 21630You may want to use this command with the @samp{-iex} option 21631(@pxref{Option -init-eval-command}) such as: 21632@smallexample 21633$ @kbd{gdb -iex "set auto-load off" untrusted-executable corefile} 21634@end smallexample 21635 21636Be aware that system init file (@pxref{System-wide configuration}) 21637and init files from your home directory (@pxref{Home Directory Init File}) 21638still get read (as they come from generally trusted directories). 21639To prevent @value{GDBN} from auto-loading even those init files, use the 21640@option{-nx} option (@pxref{Mode Options}), in addition to 21641@code{set auto-load no}. 21642 21643@anchor{show auto-load} 21644@kindex show auto-load 21645@item show auto-load 21646Show whether auto-loading of each specific @samp{auto-load} file(s) is enabled 21647or disabled. 21648 21649@smallexample 21650(gdb) show auto-load 21651gdb-scripts: Auto-loading of canned sequences of commands scripts is on. 21652libthread-db: Auto-loading of inferior specific libthread_db is on. 21653local-gdbinit: Auto-loading of .gdbinit script from current directory 21654 is on. 21655python-scripts: Auto-loading of Python scripts is on. 21656safe-path: List of directories from which it is safe to auto-load files 21657 is $debugdir:$datadir/auto-load. 21658scripts-directory: List of directories from which to load auto-loaded scripts 21659 is $debugdir:$datadir/auto-load. 21660@end smallexample 21661 21662@anchor{info auto-load} 21663@kindex info auto-load 21664@item info auto-load 21665Print whether each specific @samp{auto-load} file(s) have been auto-loaded or 21666not. 21667 21668@smallexample 21669(gdb) info auto-load 21670gdb-scripts: 21671Loaded Script 21672Yes /home/user/gdb/gdb-gdb.gdb 21673libthread-db: No auto-loaded libthread-db. 21674local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been 21675 loaded. 21676python-scripts: 21677Loaded Script 21678Yes /home/user/gdb/gdb-gdb.py 21679@end smallexample 21680@end table 21681 21682These are various kinds of files @value{GDBN} can automatically load: 21683 21684@itemize @bullet 21685@item 21686@xref{objfile-gdb.py file}, controlled by @ref{set auto-load python-scripts}. 21687@item 21688@xref{objfile-gdb.gdb file}, controlled by @ref{set auto-load gdb-scripts}. 21689@item 21690@xref{dotdebug_gdb_scripts section}, 21691controlled by @ref{set auto-load python-scripts}. 21692@item 21693@xref{Init File in the Current Directory}, 21694controlled by @ref{set auto-load local-gdbinit}. 21695@item 21696@xref{libthread_db.so.1 file}, controlled by @ref{set auto-load libthread-db}. 21697@end itemize 21698 21699These are @value{GDBN} control commands for the auto-loading: 21700 21701@multitable @columnfractions .5 .5 21702@item @xref{set auto-load off}. 21703@tab Disable auto-loading globally. 21704@item @xref{show auto-load}. 21705@tab Show setting of all kinds of files. 21706@item @xref{info auto-load}. 21707@tab Show state of all kinds of files. 21708@item @xref{set auto-load gdb-scripts}. 21709@tab Control for @value{GDBN} command scripts. 21710@item @xref{show auto-load gdb-scripts}. 21711@tab Show setting of @value{GDBN} command scripts. 21712@item @xref{info auto-load gdb-scripts}. 21713@tab Show state of @value{GDBN} command scripts. 21714@item @xref{set auto-load python-scripts}. 21715@tab Control for @value{GDBN} Python scripts. 21716@item @xref{show auto-load python-scripts}. 21717@tab Show setting of @value{GDBN} Python scripts. 21718@item @xref{info auto-load python-scripts}. 21719@tab Show state of @value{GDBN} Python scripts. 21720@item @xref{set auto-load scripts-directory}. 21721@tab Control for @value{GDBN} auto-loaded scripts location. 21722@item @xref{show auto-load scripts-directory}. 21723@tab Show @value{GDBN} auto-loaded scripts location. 21724@item @xref{set auto-load local-gdbinit}. 21725@tab Control for init file in the current directory. 21726@item @xref{show auto-load local-gdbinit}. 21727@tab Show setting of init file in the current directory. 21728@item @xref{info auto-load local-gdbinit}. 21729@tab Show state of init file in the current directory. 21730@item @xref{set auto-load libthread-db}. 21731@tab Control for thread debugging library. 21732@item @xref{show auto-load libthread-db}. 21733@tab Show setting of thread debugging library. 21734@item @xref{info auto-load libthread-db}. 21735@tab Show state of thread debugging library. 21736@item @xref{set auto-load safe-path}. 21737@tab Control directories trusted for automatic loading. 21738@item @xref{show auto-load safe-path}. 21739@tab Show directories trusted for automatic loading. 21740@item @xref{add-auto-load-safe-path}. 21741@tab Add directory trusted for automatic loading. 21742@end multitable 21743 21744@menu 21745* Init File in the Current Directory:: @samp{set/show/info auto-load local-gdbinit} 21746* libthread_db.so.1 file:: @samp{set/show/info auto-load libthread-db} 21747* objfile-gdb.gdb file:: @samp{set/show/info auto-load gdb-script} 21748* Auto-loading safe path:: @samp{set/show/info auto-load safe-path} 21749* Auto-loading verbose mode:: @samp{set/show debug auto-load} 21750@xref{Python Auto-loading}. 21751@end menu 21752 21753@node Init File in the Current Directory 21754@subsection Automatically loading init file in the current directory 21755@cindex auto-loading init file in the current directory 21756 21757By default, @value{GDBN} reads and executes the canned sequences of commands 21758from init file (if any) in the current working directory, 21759see @ref{Init File in the Current Directory during Startup}. 21760 21761Note that loading of this local @file{.gdbinit} file also requires accordingly 21762configured @code{auto-load safe-path} (@pxref{Auto-loading safe path}). 21763 21764@table @code 21765@anchor{set auto-load local-gdbinit} 21766@kindex set auto-load local-gdbinit 21767@item set auto-load local-gdbinit [on|off] 21768Enable or disable the auto-loading of canned sequences of commands 21769(@pxref{Sequences}) found in init file in the current directory. 21770 21771@anchor{show auto-load local-gdbinit} 21772@kindex show auto-load local-gdbinit 21773@item show auto-load local-gdbinit 21774Show whether auto-loading of canned sequences of commands from init file in the 21775current directory is enabled or disabled. 21776 21777@anchor{info auto-load local-gdbinit} 21778@kindex info auto-load local-gdbinit 21779@item info auto-load local-gdbinit 21780Print whether canned sequences of commands from init file in the 21781current directory have been auto-loaded. 21782@end table 21783 21784@node libthread_db.so.1 file 21785@subsection Automatically loading thread debugging library 21786@cindex auto-loading libthread_db.so.1 21787 21788This feature is currently present only on @sc{gnu}/Linux native hosts. 21789 21790@value{GDBN} reads in some cases thread debugging library from places specific 21791to the inferior (@pxref{set libthread-db-search-path}). 21792 21793The special @samp{libthread-db-search-path} entry @samp{$sdir} is processed 21794without checking this @samp{set auto-load libthread-db} switch as system 21795libraries have to be trusted in general. In all other cases of 21796@samp{libthread-db-search-path} entries @value{GDBN} checks first if @samp{set 21797auto-load libthread-db} is enabled before trying to open such thread debugging 21798library. 21799 21800Note that loading of this debugging library also requires accordingly configured 21801@code{auto-load safe-path} (@pxref{Auto-loading safe path}). 21802 21803@table @code 21804@anchor{set auto-load libthread-db} 21805@kindex set auto-load libthread-db 21806@item set auto-load libthread-db [on|off] 21807Enable or disable the auto-loading of inferior specific thread debugging library. 21808 21809@anchor{show auto-load libthread-db} 21810@kindex show auto-load libthread-db 21811@item show auto-load libthread-db 21812Show whether auto-loading of inferior specific thread debugging library is 21813enabled or disabled. 21814 21815@anchor{info auto-load libthread-db} 21816@kindex info auto-load libthread-db 21817@item info auto-load libthread-db 21818Print the list of all loaded inferior specific thread debugging libraries and 21819for each such library print list of inferior @var{pid}s using it. 21820@end table 21821 21822@node objfile-gdb.gdb file 21823@subsection The @file{@var{objfile}-gdb.gdb} file 21824@cindex auto-loading @file{@var{objfile}-gdb.gdb} 21825 21826@value{GDBN} tries to load an @file{@var{objfile}-gdb.gdb} file containing 21827canned sequences of commands (@pxref{Sequences}), as long as @samp{set 21828auto-load gdb-scripts} is set to @samp{on}. 21829 21830Note that loading of this script file also requires accordingly configured 21831@code{auto-load safe-path} (@pxref{Auto-loading safe path}). 21832 21833For more background refer to the similar Python scripts auto-loading 21834description (@pxref{objfile-gdb.py file}). 21835 21836@table @code 21837@anchor{set auto-load gdb-scripts} 21838@kindex set auto-load gdb-scripts 21839@item set auto-load gdb-scripts [on|off] 21840Enable or disable the auto-loading of canned sequences of commands scripts. 21841 21842@anchor{show auto-load gdb-scripts} 21843@kindex show auto-load gdb-scripts 21844@item show auto-load gdb-scripts 21845Show whether auto-loading of canned sequences of commands scripts is enabled or 21846disabled. 21847 21848@anchor{info auto-load gdb-scripts} 21849@kindex info auto-load gdb-scripts 21850@cindex print list of auto-loaded canned sequences of commands scripts 21851@item info auto-load gdb-scripts [@var{regexp}] 21852Print the list of all canned sequences of commands scripts that @value{GDBN} 21853auto-loaded. 21854@end table 21855 21856If @var{regexp} is supplied only canned sequences of commands scripts with 21857matching names are printed. 21858 21859@node Auto-loading safe path 21860@subsection Security restriction for auto-loading 21861@cindex auto-loading safe-path 21862 21863As the files of inferior can come from untrusted source (such as submitted by 21864an application user) @value{GDBN} does not always load any files automatically. 21865@value{GDBN} provides the @samp{set auto-load safe-path} setting to list 21866directories trusted for loading files not explicitly requested by user. 21867Each directory can also be a shell wildcard pattern. 21868 21869If the path is not set properly you will see a warning and the file will not 21870get loaded: 21871 21872@smallexample 21873$ ./gdb -q ./gdb 21874Reading symbols from /home/user/gdb/gdb...done. 21875warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been 21876 declined by your `auto-load safe-path' set 21877 to "$debugdir:$datadir/auto-load". 21878warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been 21879 declined by your `auto-load safe-path' set 21880 to "$debugdir:$datadir/auto-load". 21881@end smallexample 21882 21883@noindent 21884To instruct @value{GDBN} to go ahead and use the init files anyway, 21885invoke @value{GDBN} like this: 21886 21887@smallexample 21888$ gdb -q -iex "set auto-load safe-path /home/user/gdb" ./gdb 21889@end smallexample 21890 21891The list of trusted directories is controlled by the following commands: 21892 21893@table @code 21894@anchor{set auto-load safe-path} 21895@kindex set auto-load safe-path 21896@item set auto-load safe-path @r{[}@var{directories}@r{]} 21897Set the list of directories (and their subdirectories) trusted for automatic 21898loading and execution of scripts. You can also enter a specific trusted file. 21899Each directory can also be a shell wildcard pattern; wildcards do not match 21900directory separator - see @code{FNM_PATHNAME} for system function @code{fnmatch} 21901(@pxref{Wildcard Matching, fnmatch, , libc, GNU C Library Reference Manual}). 21902If you omit @var{directories}, @samp{auto-load safe-path} will be reset to 21903its default value as specified during @value{GDBN} compilation. 21904 21905The list of directories uses path separator (@samp{:} on GNU and Unix 21906systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly 21907to the @env{PATH} environment variable. 21908 21909@anchor{show auto-load safe-path} 21910@kindex show auto-load safe-path 21911@item show auto-load safe-path 21912Show the list of directories trusted for automatic loading and execution of 21913scripts. 21914 21915@anchor{add-auto-load-safe-path} 21916@kindex add-auto-load-safe-path 21917@item add-auto-load-safe-path 21918Add an entry (or list of entries) the list of directories trusted for automatic 21919loading and execution of scripts. Multiple entries may be delimited by the 21920host platform path separator in use. 21921@end table 21922 21923This variable defaults to what @code{--with-auto-load-dir} has been configured 21924to (@pxref{with-auto-load-dir}). @file{$debugdir} and @file{$datadir} 21925substitution applies the same as for @ref{set auto-load scripts-directory}. 21926The default @code{set auto-load safe-path} value can be also overriden by 21927@value{GDBN} configuration option @option{--with-auto-load-safe-path}. 21928 21929Setting this variable to @file{/} disables this security protection, 21930corresponding @value{GDBN} configuration option is 21931@option{--without-auto-load-safe-path}. 21932This variable is supposed to be set to the system directories writable by the 21933system superuser only. Users can add their source directories in init files in 21934their home directories (@pxref{Home Directory Init File}). See also deprecated 21935init file in the current directory 21936(@pxref{Init File in the Current Directory during Startup}). 21937 21938To force @value{GDBN} to load the files it declined to load in the previous 21939example, you could use one of the following ways: 21940 21941@table @asis 21942@item @file{~/.gdbinit}: @samp{add-auto-load-safe-path ~/src/gdb} 21943Specify this trusted directory (or a file) as additional component of the list. 21944You have to specify also any existing directories displayed by 21945by @samp{show auto-load safe-path} (such as @samp{/usr:/bin} in this example). 21946 21947@item @kbd{gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" @dots{}} 21948Specify this directory as in the previous case but just for a single 21949@value{GDBN} session. 21950 21951@item @kbd{gdb -iex "set auto-load safe-path /" @dots{}} 21952Disable auto-loading safety for a single @value{GDBN} session. 21953This assumes all the files you debug during this @value{GDBN} session will come 21954from trusted sources. 21955 21956@item @kbd{./configure --without-auto-load-safe-path} 21957During compilation of @value{GDBN} you may disable any auto-loading safety. 21958This assumes all the files you will ever debug with this @value{GDBN} come from 21959trusted sources. 21960@end table 21961 21962On the other hand you can also explicitly forbid automatic files loading which 21963also suppresses any such warning messages: 21964 21965@table @asis 21966@item @kbd{gdb -iex "set auto-load no" @dots{}} 21967You can use @value{GDBN} command-line option for a single @value{GDBN} session. 21968 21969@item @file{~/.gdbinit}: @samp{set auto-load no} 21970Disable auto-loading globally for the user 21971(@pxref{Home Directory Init File}). While it is improbable, you could also 21972use system init file instead (@pxref{System-wide configuration}). 21973@end table 21974 21975This setting applies to the file names as entered by user. If no entry matches 21976@value{GDBN} tries as a last resort to also resolve all the file names into 21977their canonical form (typically resolving symbolic links) and compare the 21978entries again. @value{GDBN} already canonicalizes most of the filenames on its 21979own before starting the comparison so a canonical form of directories is 21980recommended to be entered. 21981 21982@node Auto-loading verbose mode 21983@subsection Displaying files tried for auto-load 21984@cindex auto-loading verbose mode 21985 21986For better visibility of all the file locations where you can place scripts to 21987be auto-loaded with inferior --- or to protect yourself against accidental 21988execution of untrusted scripts --- @value{GDBN} provides a feature for printing 21989all the files attempted to be loaded. Both existing and non-existing files may 21990be printed. 21991 21992For example the list of directories from which it is safe to auto-load files 21993(@pxref{Auto-loading safe path}) applies also to canonicalized filenames which 21994may not be too obvious while setting it up. 21995 21996@smallexample 21997(gdb) set debug auto-load on 21998(gdb) file ~/src/t/true 21999auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb" 22000 for objfile "/tmp/true". 22001auto-load: Updating directories of "/usr:/opt". 22002auto-load: Using directory "/usr". 22003auto-load: Using directory "/opt". 22004warning: File "/tmp/true-gdb.gdb" auto-loading has been declined 22005 by your `auto-load safe-path' set to "/usr:/opt". 22006@end smallexample 22007 22008@table @code 22009@anchor{set debug auto-load} 22010@kindex set debug auto-load 22011@item set debug auto-load [on|off] 22012Set whether to print the filenames attempted to be auto-loaded. 22013 22014@anchor{show debug auto-load} 22015@kindex show debug auto-load 22016@item show debug auto-load 22017Show whether printing of the filenames attempted to be auto-loaded is turned 22018on or off. 22019@end table 22020 22021@node Messages/Warnings 22022@section Optional Warnings and Messages 22023 22024@cindex verbose operation 22025@cindex optional warnings 22026By default, @value{GDBN} is silent about its inner workings. If you are 22027running on a slow machine, you may want to use the @code{set verbose} 22028command. This makes @value{GDBN} tell you when it does a lengthy 22029internal operation, so you will not think it has crashed. 22030 22031Currently, the messages controlled by @code{set verbose} are those 22032which announce that the symbol table for a source file is being read; 22033see @code{symbol-file} in @ref{Files, ,Commands to Specify Files}. 22034 22035@table @code 22036@kindex set verbose 22037@item set verbose on 22038Enables @value{GDBN} output of certain informational messages. 22039 22040@item set verbose off 22041Disables @value{GDBN} output of certain informational messages. 22042 22043@kindex show verbose 22044@item show verbose 22045Displays whether @code{set verbose} is on or off. 22046@end table 22047 22048By default, if @value{GDBN} encounters bugs in the symbol table of an 22049object file, it is silent; but if you are debugging a compiler, you may 22050find this information useful (@pxref{Symbol Errors, ,Errors Reading 22051Symbol Files}). 22052 22053@table @code 22054 22055@kindex set complaints 22056@item set complaints @var{limit} 22057Permits @value{GDBN} to output @var{limit} complaints about each type of 22058unusual symbols before becoming silent about the problem. Set 22059@var{limit} to zero to suppress all complaints; set it to a large number 22060to prevent complaints from being suppressed. 22061 22062@kindex show complaints 22063@item show complaints 22064Displays how many symbol complaints @value{GDBN} is permitted to produce. 22065 22066@end table 22067 22068@anchor{confirmation requests} 22069By default, @value{GDBN} is cautious, and asks what sometimes seems to be a 22070lot of stupid questions to confirm certain commands. For example, if 22071you try to run a program which is already running: 22072 22073@smallexample 22074(@value{GDBP}) run 22075The program being debugged has been started already. 22076Start it from the beginning? (y or n) 22077@end smallexample 22078 22079If you are willing to unflinchingly face the consequences of your own 22080commands, you can disable this ``feature'': 22081 22082@table @code 22083 22084@kindex set confirm 22085@cindex flinching 22086@cindex confirmation 22087@cindex stupid questions 22088@item set confirm off 22089Disables confirmation requests. Note that running @value{GDBN} with 22090the @option{--batch} option (@pxref{Mode Options, -batch}) also 22091automatically disables confirmation requests. 22092 22093@item set confirm on 22094Enables confirmation requests (the default). 22095 22096@kindex show confirm 22097@item show confirm 22098Displays state of confirmation requests. 22099 22100@end table 22101 22102@cindex command tracing 22103If you need to debug user-defined commands or sourced files you may find it 22104useful to enable @dfn{command tracing}. In this mode each command will be 22105printed as it is executed, prefixed with one or more @samp{+} symbols, the 22106quantity denoting the call depth of each command. 22107 22108@table @code 22109@kindex set trace-commands 22110@cindex command scripts, debugging 22111@item set trace-commands on 22112Enable command tracing. 22113@item set trace-commands off 22114Disable command tracing. 22115@item show trace-commands 22116Display the current state of command tracing. 22117@end table 22118 22119@node Debugging Output 22120@section Optional Messages about Internal Happenings 22121@cindex optional debugging messages 22122 22123@value{GDBN} has commands that enable optional debugging messages from 22124various @value{GDBN} subsystems; normally these commands are of 22125interest to @value{GDBN} maintainers, or when reporting a bug. This 22126section documents those commands. 22127 22128@table @code 22129@kindex set exec-done-display 22130@item set exec-done-display 22131Turns on or off the notification of asynchronous commands' 22132completion. When on, @value{GDBN} will print a message when an 22133asynchronous command finishes its execution. The default is off. 22134@kindex show exec-done-display 22135@item show exec-done-display 22136Displays the current setting of asynchronous command completion 22137notification. 22138@kindex set debug 22139@cindex ARM AArch64 22140@item set debug aarch64 22141Turns on or off display of debugging messages related to ARM AArch64. 22142The default is off. 22143@kindex show debug 22144@item show debug aarch64 22145Displays the current state of displaying debugging messages related to 22146ARM AArch64. 22147@cindex gdbarch debugging info 22148@cindex architecture debugging info 22149@item set debug arch 22150Turns on or off display of gdbarch debugging info. The default is off 22151@item show debug arch 22152Displays the current state of displaying gdbarch debugging info. 22153@item set debug aix-thread 22154@cindex AIX threads 22155Display debugging messages about inner workings of the AIX thread 22156module. 22157@item show debug aix-thread 22158Show the current state of AIX thread debugging info display. 22159@item set debug check-physname 22160@cindex physname 22161Check the results of the ``physname'' computation. When reading DWARF 22162debugging information for C@t{++}, @value{GDBN} attempts to compute 22163each entity's name. @value{GDBN} can do this computation in two 22164different ways, depending on exactly what information is present. 22165When enabled, this setting causes @value{GDBN} to compute the names 22166both ways and display any discrepancies. 22167@item show debug check-physname 22168Show the current state of ``physname'' checking. 22169@item set debug coff-pe-read 22170@cindex COFF/PE exported symbols 22171Control display of debugging messages related to reading of COFF/PE 22172exported symbols. The default is off. 22173@item show debug coff-pe-read 22174Displays the current state of displaying debugging messages related to 22175reading of COFF/PE exported symbols. 22176@item set debug dwarf2-die 22177@cindex DWARF2 DIEs 22178Dump DWARF2 DIEs after they are read in. 22179The value is the number of nesting levels to print. 22180A value of zero turns off the display. 22181@item show debug dwarf2-die 22182Show the current state of DWARF2 DIE debugging. 22183@item set debug dwarf2-read 22184@cindex DWARF2 Reading 22185Turns on or off display of debugging messages related to reading 22186DWARF debug info. The default is off. 22187@item show debug dwarf2-read 22188Show the current state of DWARF2 reader debugging. 22189@item set debug displaced 22190@cindex displaced stepping debugging info 22191Turns on or off display of @value{GDBN} debugging info for the 22192displaced stepping support. The default is off. 22193@item show debug displaced 22194Displays the current state of displaying @value{GDBN} debugging info 22195related to displaced stepping. 22196@item set debug event 22197@cindex event debugging info 22198Turns on or off display of @value{GDBN} event debugging info. The 22199default is off. 22200@item show debug event 22201Displays the current state of displaying @value{GDBN} event debugging 22202info. 22203@item set debug expression 22204@cindex expression debugging info 22205Turns on or off display of debugging info about @value{GDBN} 22206expression parsing. The default is off. 22207@item show debug expression 22208Displays the current state of displaying debugging info about 22209@value{GDBN} expression parsing. 22210@item set debug frame 22211@cindex frame debugging info 22212Turns on or off display of @value{GDBN} frame debugging info. The 22213default is off. 22214@item show debug frame 22215Displays the current state of displaying @value{GDBN} frame debugging 22216info. 22217@item set debug gnu-nat 22218@cindex @sc{gnu}/Hurd debug messages 22219Turns on or off debugging messages from the @sc{gnu}/Hurd debug support. 22220@item show debug gnu-nat 22221Show the current state of @sc{gnu}/Hurd debugging messages. 22222@item set debug infrun 22223@cindex inferior debugging info 22224Turns on or off display of @value{GDBN} debugging info for running the inferior. 22225The default is off. @file{infrun.c} contains GDB's runtime state machine used 22226for implementing operations such as single-stepping the inferior. 22227@item show debug infrun 22228Displays the current state of @value{GDBN} inferior debugging. 22229@item set debug jit 22230@cindex just-in-time compilation, debugging messages 22231Turns on or off debugging messages from JIT debug support. 22232@item show debug jit 22233Displays the current state of @value{GDBN} JIT debugging. 22234@item set debug lin-lwp 22235@cindex @sc{gnu}/Linux LWP debug messages 22236@cindex Linux lightweight processes 22237Turns on or off debugging messages from the Linux LWP debug support. 22238@item show debug lin-lwp 22239Show the current state of Linux LWP debugging messages. 22240@item set debug mach-o 22241@cindex Mach-O symbols processing 22242Control display of debugging messages related to Mach-O symbols 22243processing. The default is off. 22244@item show debug mach-o 22245Displays the current state of displaying debugging messages related to 22246reading of COFF/PE exported symbols. 22247@item set debug notification 22248@cindex remote async notification debugging info 22249Turns on or off debugging messages about remote async notification. 22250The default is off. 22251@item show debug notification 22252Displays the current state of remote async notification debugging messages. 22253@item set debug observer 22254@cindex observer debugging info 22255Turns on or off display of @value{GDBN} observer debugging. This 22256includes info such as the notification of observable events. 22257@item show debug observer 22258Displays the current state of observer debugging. 22259@item set debug overload 22260@cindex C@t{++} overload debugging info 22261Turns on or off display of @value{GDBN} C@t{++} overload debugging 22262info. This includes info such as ranking of functions, etc. The default 22263is off. 22264@item show debug overload 22265Displays the current state of displaying @value{GDBN} C@t{++} overload 22266debugging info. 22267@cindex expression parser, debugging info 22268@cindex debug expression parser 22269@item set debug parser 22270Turns on or off the display of expression parser debugging output. 22271Internally, this sets the @code{yydebug} variable in the expression 22272parser. @xref{Tracing, , Tracing Your Parser, bison, Bison}, for 22273details. The default is off. 22274@item show debug parser 22275Show the current state of expression parser debugging. 22276@cindex packets, reporting on stdout 22277@cindex serial connections, debugging 22278@cindex debug remote protocol 22279@cindex remote protocol debugging 22280@cindex display remote packets 22281@item set debug remote 22282Turns on or off display of reports on all packets sent back and forth across 22283the serial line to the remote machine. The info is printed on the 22284@value{GDBN} standard output stream. The default is off. 22285@item show debug remote 22286Displays the state of display of remote packets. 22287@item set debug serial 22288Turns on or off display of @value{GDBN} serial debugging info. The 22289default is off. 22290@item show debug serial 22291Displays the current state of displaying @value{GDBN} serial debugging 22292info. 22293@item set debug solib-frv 22294@cindex FR-V shared-library debugging 22295Turns on or off debugging messages for FR-V shared-library code. 22296@item show debug solib-frv 22297Display the current state of FR-V shared-library code debugging 22298messages. 22299@item set debug symtab-create 22300@cindex symbol table creation 22301Turns on or off display of debugging messages related to symbol table creation. 22302The default is off. 22303@item show debug symtab-create 22304Show the current state of symbol table creation debugging. 22305@item set debug target 22306@cindex target debugging info 22307Turns on or off display of @value{GDBN} target debugging info. This info 22308includes what is going on at the target level of GDB, as it happens. The 22309default is 0. Set it to 1 to track events, and to 2 to also track the 22310value of large memory transfers. Changes to this flag do not take effect 22311until the next time you connect to a target or use the @code{run} command. 22312@item show debug target 22313Displays the current state of displaying @value{GDBN} target debugging 22314info. 22315@item set debug timestamp 22316@cindex timestampping debugging info 22317Turns on or off display of timestamps with @value{GDBN} debugging info. 22318When enabled, seconds and microseconds are displayed before each debugging 22319message. 22320@item show debug timestamp 22321Displays the current state of displaying timestamps with @value{GDBN} 22322debugging info. 22323@item set debugvarobj 22324@cindex variable object debugging info 22325Turns on or off display of @value{GDBN} variable object debugging 22326info. The default is off. 22327@item show debugvarobj 22328Displays the current state of displaying @value{GDBN} variable object 22329debugging info. 22330@item set debug xml 22331@cindex XML parser debugging 22332Turns on or off debugging messages for built-in XML parsers. 22333@item show debug xml 22334Displays the current state of XML debugging messages. 22335@end table 22336 22337@node Other Misc Settings 22338@section Other Miscellaneous Settings 22339@cindex miscellaneous settings 22340 22341@table @code 22342@kindex set interactive-mode 22343@item set interactive-mode 22344If @code{on}, forces @value{GDBN} to assume that GDB was started 22345in a terminal. In practice, this means that @value{GDBN} should wait 22346for the user to answer queries generated by commands entered at 22347the command prompt. If @code{off}, forces @value{GDBN} to operate 22348in the opposite mode, and it uses the default answers to all queries. 22349If @code{auto} (the default), @value{GDBN} tries to determine whether 22350its standard input is a terminal, and works in interactive-mode if it 22351is, non-interactively otherwise. 22352 22353In the vast majority of cases, the debugger should be able to guess 22354correctly which mode should be used. But this setting can be useful 22355in certain specific cases, such as running a MinGW @value{GDBN} 22356inside a cygwin window. 22357 22358@kindex show interactive-mode 22359@item show interactive-mode 22360Displays whether the debugger is operating in interactive mode or not. 22361@end table 22362 22363@node Extending GDB 22364@chapter Extending @value{GDBN} 22365@cindex extending GDB 22366 22367@value{GDBN} provides three mechanisms for extension. The first is based 22368on composition of @value{GDBN} commands, the second is based on the 22369Python scripting language, and the third is for defining new aliases of 22370existing commands. 22371 22372To facilitate the use of the first two extensions, @value{GDBN} is capable 22373of evaluating the contents of a file. When doing so, @value{GDBN} 22374can recognize which scripting language is being used by looking at 22375the filename extension. Files with an unrecognized filename extension 22376are always treated as a @value{GDBN} Command Files. 22377@xref{Command Files,, Command files}. 22378 22379You can control how @value{GDBN} evaluates these files with the following 22380setting: 22381 22382@table @code 22383@kindex set script-extension 22384@kindex show script-extension 22385@item set script-extension off 22386All scripts are always evaluated as @value{GDBN} Command Files. 22387 22388@item set script-extension soft 22389The debugger determines the scripting language based on filename 22390extension. If this scripting language is supported, @value{GDBN} 22391evaluates the script using that language. Otherwise, it evaluates 22392the file as a @value{GDBN} Command File. 22393 22394@item set script-extension strict 22395The debugger determines the scripting language based on filename 22396extension, and evaluates the script using that language. If the 22397language is not supported, then the evaluation fails. 22398 22399@item show script-extension 22400Display the current value of the @code{script-extension} option. 22401 22402@end table 22403 22404@menu 22405* Sequences:: Canned Sequences of Commands 22406* Python:: Scripting @value{GDBN} using Python 22407* Aliases:: Creating new spellings of existing commands 22408@end menu 22409 22410@node Sequences 22411@section Canned Sequences of Commands 22412 22413Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint 22414Command Lists}), @value{GDBN} provides two ways to store sequences of 22415commands for execution as a unit: user-defined commands and command 22416files. 22417 22418@menu 22419* Define:: How to define your own commands 22420* Hooks:: Hooks for user-defined commands 22421* Command Files:: How to write scripts of commands to be stored in a file 22422* Output:: Commands for controlled output 22423@end menu 22424 22425@node Define 22426@subsection User-defined Commands 22427 22428@cindex user-defined command 22429@cindex arguments, to user-defined commands 22430A @dfn{user-defined command} is a sequence of @value{GDBN} commands to 22431which you assign a new name as a command. This is done with the 22432@code{define} command. User commands may accept up to 10 arguments 22433separated by whitespace. Arguments are accessed within the user command 22434via @code{$arg0@dots{}$arg9}. A trivial example: 22435 22436@smallexample 22437define adder 22438 print $arg0 + $arg1 + $arg2 22439end 22440@end smallexample 22441 22442@noindent 22443To execute the command use: 22444 22445@smallexample 22446adder 1 2 3 22447@end smallexample 22448 22449@noindent 22450This defines the command @code{adder}, which prints the sum of 22451its three arguments. Note the arguments are text substitutions, so they may 22452reference variables, use complex expressions, or even perform inferior 22453functions calls. 22454 22455@cindex argument count in user-defined commands 22456@cindex how many arguments (user-defined commands) 22457In addition, @code{$argc} may be used to find out how many arguments have 22458been passed. This expands to a number in the range 0@dots{}10. 22459 22460@smallexample 22461define adder 22462 if $argc == 2 22463 print $arg0 + $arg1 22464 end 22465 if $argc == 3 22466 print $arg0 + $arg1 + $arg2 22467 end 22468end 22469@end smallexample 22470 22471@table @code 22472 22473@kindex define 22474@item define @var{commandname} 22475Define a command named @var{commandname}. If there is already a command 22476by that name, you are asked to confirm that you want to redefine it. 22477@var{commandname} may be a bare command name consisting of letters, 22478numbers, dashes, and underscores. It may also start with any predefined 22479prefix command. For example, @samp{define target my-target} creates 22480a user-defined @samp{target my-target} command. 22481 22482The definition of the command is made up of other @value{GDBN} command lines, 22483which are given following the @code{define} command. The end of these 22484commands is marked by a line containing @code{end}. 22485 22486@kindex document 22487@kindex end@r{ (user-defined commands)} 22488@item document @var{commandname} 22489Document the user-defined command @var{commandname}, so that it can be 22490accessed by @code{help}. The command @var{commandname} must already be 22491defined. This command reads lines of documentation just as @code{define} 22492reads the lines of the command definition, ending with @code{end}. 22493After the @code{document} command is finished, @code{help} on command 22494@var{commandname} displays the documentation you have written. 22495 22496You may use the @code{document} command again to change the 22497documentation of a command. Redefining the command with @code{define} 22498does not change the documentation. 22499 22500@kindex dont-repeat 22501@cindex don't repeat command 22502@item dont-repeat 22503Used inside a user-defined command, this tells @value{GDBN} that this 22504command should not be repeated when the user hits @key{RET} 22505(@pxref{Command Syntax, repeat last command}). 22506 22507@kindex help user-defined 22508@item help user-defined 22509List all user-defined commands and all python commands defined in class 22510COMAND_USER. The first line of the documentation or docstring is 22511included (if any). 22512 22513@kindex show user 22514@item show user 22515@itemx show user @var{commandname} 22516Display the @value{GDBN} commands used to define @var{commandname} (but 22517not its documentation). If no @var{commandname} is given, display the 22518definitions for all user-defined commands. 22519This does not work for user-defined python commands. 22520 22521@cindex infinite recursion in user-defined commands 22522@kindex show max-user-call-depth 22523@kindex set max-user-call-depth 22524@item show max-user-call-depth 22525@itemx set max-user-call-depth 22526The value of @code{max-user-call-depth} controls how many recursion 22527levels are allowed in user-defined commands before @value{GDBN} suspects an 22528infinite recursion and aborts the command. 22529This does not apply to user-defined python commands. 22530@end table 22531 22532In addition to the above commands, user-defined commands frequently 22533use control flow commands, described in @ref{Command Files}. 22534 22535When user-defined commands are executed, the 22536commands of the definition are not printed. An error in any command 22537stops execution of the user-defined command. 22538 22539If used interactively, commands that would ask for confirmation proceed 22540without asking when used inside a user-defined command. Many @value{GDBN} 22541commands that normally print messages to say what they are doing omit the 22542messages when used in a user-defined command. 22543 22544@node Hooks 22545@subsection User-defined Command Hooks 22546@cindex command hooks 22547@cindex hooks, for commands 22548@cindex hooks, pre-command 22549 22550@kindex hook 22551You may define @dfn{hooks}, which are a special kind of user-defined 22552command. Whenever you run the command @samp{foo}, if the user-defined 22553command @samp{hook-foo} exists, it is executed (with no arguments) 22554before that command. 22555 22556@cindex hooks, post-command 22557@kindex hookpost 22558A hook may also be defined which is run after the command you executed. 22559Whenever you run the command @samp{foo}, if the user-defined command 22560@samp{hookpost-foo} exists, it is executed (with no arguments) after 22561that command. Post-execution hooks may exist simultaneously with 22562pre-execution hooks, for the same command. 22563 22564It is valid for a hook to call the command which it hooks. If this 22565occurs, the hook is not re-executed, thereby avoiding infinite recursion. 22566 22567@c It would be nice if hookpost could be passed a parameter indicating 22568@c if the command it hooks executed properly or not. FIXME! 22569 22570@kindex stop@r{, a pseudo-command} 22571In addition, a pseudo-command, @samp{stop} exists. Defining 22572(@samp{hook-stop}) makes the associated commands execute every time 22573execution stops in your program: before breakpoint commands are run, 22574displays are printed, or the stack frame is printed. 22575 22576For example, to ignore @code{SIGALRM} signals while 22577single-stepping, but treat them normally during normal execution, 22578you could define: 22579 22580@smallexample 22581define hook-stop 22582handle SIGALRM nopass 22583end 22584 22585define hook-run 22586handle SIGALRM pass 22587end 22588 22589define hook-continue 22590handle SIGALRM pass 22591end 22592@end smallexample 22593 22594As a further example, to hook at the beginning and end of the @code{echo} 22595command, and to add extra text to the beginning and end of the message, 22596you could define: 22597 22598@smallexample 22599define hook-echo 22600echo <<<--- 22601end 22602 22603define hookpost-echo 22604echo --->>>\n 22605end 22606 22607(@value{GDBP}) echo Hello World 22608<<<---Hello World--->>> 22609(@value{GDBP}) 22610 22611@end smallexample 22612 22613You can define a hook for any single-word command in @value{GDBN}, but 22614not for command aliases; you should define a hook for the basic command 22615name, e.g.@: @code{backtrace} rather than @code{bt}. 22616@c FIXME! So how does Joe User discover whether a command is an alias 22617@c or not? 22618You can hook a multi-word command by adding @code{hook-} or 22619@code{hookpost-} to the last word of the command, e.g.@: 22620@samp{define target hook-remote} to add a hook to @samp{target remote}. 22621 22622If an error occurs during the execution of your hook, execution of 22623@value{GDBN} commands stops and @value{GDBN} issues a prompt 22624(before the command that you actually typed had a chance to run). 22625 22626If you try to define a hook which does not match any known command, you 22627get a warning from the @code{define} command. 22628 22629@node Command Files 22630@subsection Command Files 22631 22632@cindex command files 22633@cindex scripting commands 22634A command file for @value{GDBN} is a text file made of lines that are 22635@value{GDBN} commands. Comments (lines starting with @kbd{#}) may 22636also be included. An empty line in a command file does nothing; it 22637does not mean to repeat the last command, as it would from the 22638terminal. 22639 22640You can request the execution of a command file with the @code{source} 22641command. Note that the @code{source} command is also used to evaluate 22642scripts that are not Command Files. The exact behavior can be configured 22643using the @code{script-extension} setting. 22644@xref{Extending GDB,, Extending GDB}. 22645 22646@table @code 22647@kindex source 22648@cindex execute commands from a file 22649@item source [-s] [-v] @var{filename} 22650Execute the command file @var{filename}. 22651@end table 22652 22653The lines in a command file are generally executed sequentially, 22654unless the order of execution is changed by one of the 22655@emph{flow-control commands} described below. The commands are not 22656printed as they are executed. An error in any command terminates 22657execution of the command file and control is returned to the console. 22658 22659@value{GDBN} first searches for @var{filename} in the current directory. 22660If the file is not found there, and @var{filename} does not specify a 22661directory, then @value{GDBN} also looks for the file on the source search path 22662(specified with the @samp{directory} command); 22663except that @file{$cdir} is not searched because the compilation directory 22664is not relevant to scripts. 22665 22666If @code{-s} is specified, then @value{GDBN} searches for @var{filename} 22667on the search path even if @var{filename} specifies a directory. 22668The search is done by appending @var{filename} to each element of the 22669search path. So, for example, if @var{filename} is @file{mylib/myscript} 22670and the search path contains @file{/home/user} then @value{GDBN} will 22671look for the script @file{/home/user/mylib/myscript}. 22672The search is also done if @var{filename} is an absolute path. 22673For example, if @var{filename} is @file{/tmp/myscript} and 22674the search path contains @file{/home/user} then @value{GDBN} will 22675look for the script @file{/home/user/tmp/myscript}. 22676For DOS-like systems, if @var{filename} contains a drive specification, 22677it is stripped before concatenation. For example, if @var{filename} is 22678@file{d:myscript} and the search path contains @file{c:/tmp} then @value{GDBN} 22679will look for the script @file{c:/tmp/myscript}. 22680 22681If @code{-v}, for verbose mode, is given then @value{GDBN} displays 22682each command as it is executed. The option must be given before 22683@var{filename}, and is interpreted as part of the filename anywhere else. 22684 22685Commands that would ask for confirmation if used interactively proceed 22686without asking when used in a command file. Many @value{GDBN} commands that 22687normally print messages to say what they are doing omit the messages 22688when called from command files. 22689 22690@value{GDBN} also accepts command input from standard input. In this 22691mode, normal output goes to standard output and error output goes to 22692standard error. Errors in a command file supplied on standard input do 22693not terminate execution of the command file---execution continues with 22694the next command. 22695 22696@smallexample 22697gdb < cmds > log 2>&1 22698@end smallexample 22699 22700(The syntax above will vary depending on the shell used.) This example 22701will execute commands from the file @file{cmds}. All output and errors 22702would be directed to @file{log}. 22703 22704Since commands stored on command files tend to be more general than 22705commands typed interactively, they frequently need to deal with 22706complicated situations, such as different or unexpected values of 22707variables and symbols, changes in how the program being debugged is 22708built, etc. @value{GDBN} provides a set of flow-control commands to 22709deal with these complexities. Using these commands, you can write 22710complex scripts that loop over data structures, execute commands 22711conditionally, etc. 22712 22713@table @code 22714@kindex if 22715@kindex else 22716@item if 22717@itemx else 22718This command allows to include in your script conditionally executed 22719commands. The @code{if} command takes a single argument, which is an 22720expression to evaluate. It is followed by a series of commands that 22721are executed only if the expression is true (its value is nonzero). 22722There can then optionally be an @code{else} line, followed by a series 22723of commands that are only executed if the expression was false. The 22724end of the list is marked by a line containing @code{end}. 22725 22726@kindex while 22727@item while 22728This command allows to write loops. Its syntax is similar to 22729@code{if}: the command takes a single argument, which is an expression 22730to evaluate, and must be followed by the commands to execute, one per 22731line, terminated by an @code{end}. These commands are called the 22732@dfn{body} of the loop. The commands in the body of @code{while} are 22733executed repeatedly as long as the expression evaluates to true. 22734 22735@kindex loop_break 22736@item loop_break 22737This command exits the @code{while} loop in whose body it is included. 22738Execution of the script continues after that @code{while}s @code{end} 22739line. 22740 22741@kindex loop_continue 22742@item loop_continue 22743This command skips the execution of the rest of the body of commands 22744in the @code{while} loop in whose body it is included. Execution 22745branches to the beginning of the @code{while} loop, where it evaluates 22746the controlling expression. 22747 22748@kindex end@r{ (if/else/while commands)} 22749@item end 22750Terminate the block of commands that are the body of @code{if}, 22751@code{else}, or @code{while} flow-control commands. 22752@end table 22753 22754 22755@node Output 22756@subsection Commands for Controlled Output 22757 22758During the execution of a command file or a user-defined command, normal 22759@value{GDBN} output is suppressed; the only output that appears is what is 22760explicitly printed by the commands in the definition. This section 22761describes three commands useful for generating exactly the output you 22762want. 22763 22764@table @code 22765@kindex echo 22766@item echo @var{text} 22767@c I do not consider backslash-space a standard C escape sequence 22768@c because it is not in ANSI. 22769Print @var{text}. Nonprinting characters can be included in 22770@var{text} using C escape sequences, such as @samp{\n} to print a 22771newline. @strong{No newline is printed unless you specify one.} 22772In addition to the standard C escape sequences, a backslash followed 22773by a space stands for a space. This is useful for displaying a 22774string with spaces at the beginning or the end, since leading and 22775trailing spaces are otherwise trimmed from all arguments. 22776To print @samp{@w{ }and foo =@w{ }}, use the command 22777@samp{echo \@w{ }and foo = \@w{ }}. 22778 22779A backslash at the end of @var{text} can be used, as in C, to continue 22780the command onto subsequent lines. For example, 22781 22782@smallexample 22783echo This is some text\n\ 22784which is continued\n\ 22785onto several lines.\n 22786@end smallexample 22787 22788produces the same output as 22789 22790@smallexample 22791echo This is some text\n 22792echo which is continued\n 22793echo onto several lines.\n 22794@end smallexample 22795 22796@kindex output 22797@item output @var{expression} 22798Print the value of @var{expression} and nothing but that value: no 22799newlines, no @samp{$@var{nn} = }. The value is not entered in the 22800value history either. @xref{Expressions, ,Expressions}, for more information 22801on expressions. 22802 22803@item output/@var{fmt} @var{expression} 22804Print the value of @var{expression} in format @var{fmt}. You can use 22805the same formats as for @code{print}. @xref{Output Formats,,Output 22806Formats}, for more information. 22807 22808@kindex printf 22809@item printf @var{template}, @var{expressions}@dots{} 22810Print the values of one or more @var{expressions} under the control of 22811the string @var{template}. To print several values, make 22812@var{expressions} be a comma-separated list of individual expressions, 22813which may be either numbers or pointers. Their values are printed as 22814specified by @var{template}, exactly as a C program would do by 22815executing the code below: 22816 22817@smallexample 22818printf (@var{template}, @var{expressions}@dots{}); 22819@end smallexample 22820 22821As in @code{C} @code{printf}, ordinary characters in @var{template} 22822are printed verbatim, while @dfn{conversion specification} introduced 22823by the @samp{%} character cause subsequent @var{expressions} to be 22824evaluated, their values converted and formatted according to type and 22825style information encoded in the conversion specifications, and then 22826printed. 22827 22828For example, you can print two values in hex like this: 22829 22830@smallexample 22831printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo 22832@end smallexample 22833 22834@code{printf} supports all the standard @code{C} conversion 22835specifications, including the flags and modifiers between the @samp{%} 22836character and the conversion letter, with the following exceptions: 22837 22838@itemize @bullet 22839@item 22840The argument-ordering modifiers, such as @samp{2$}, are not supported. 22841 22842@item 22843The modifier @samp{*} is not supported for specifying precision or 22844width. 22845 22846@item 22847The @samp{'} flag (for separation of digits into groups according to 22848@code{LC_NUMERIC'}) is not supported. 22849 22850@item 22851The type modifiers @samp{hh}, @samp{j}, @samp{t}, and @samp{z} are not 22852supported. 22853 22854@item 22855The conversion letter @samp{n} (as in @samp{%n}) is not supported. 22856 22857@item 22858The conversion letters @samp{a} and @samp{A} are not supported. 22859@end itemize 22860 22861@noindent 22862Note that the @samp{ll} type modifier is supported only if the 22863underlying @code{C} implementation used to build @value{GDBN} supports 22864the @code{long long int} type, and the @samp{L} type modifier is 22865supported only if @code{long double} type is available. 22866 22867As in @code{C}, @code{printf} supports simple backslash-escape 22868sequences, such as @code{\n}, @samp{\t}, @samp{\\}, @samp{\"}, 22869@samp{\a}, and @samp{\f}, that consist of backslash followed by a 22870single character. Octal and hexadecimal escape sequences are not 22871supported. 22872 22873Additionally, @code{printf} supports conversion specifications for DFP 22874(@dfn{Decimal Floating Point}) types using the following length modifiers 22875together with a floating point specifier. 22876letters: 22877 22878@itemize @bullet 22879@item 22880@samp{H} for printing @code{Decimal32} types. 22881 22882@item 22883@samp{D} for printing @code{Decimal64} types. 22884 22885@item 22886@samp{DD} for printing @code{Decimal128} types. 22887@end itemize 22888 22889If the underlying @code{C} implementation used to build @value{GDBN} has 22890support for the three length modifiers for DFP types, other modifiers 22891such as width and precision will also be available for @value{GDBN} to use. 22892 22893In case there is no such @code{C} support, no additional modifiers will be 22894available and the value will be printed in the standard way. 22895 22896Here's an example of printing DFP types using the above conversion letters: 22897@smallexample 22898printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl 22899@end smallexample 22900 22901@kindex eval 22902@item eval @var{template}, @var{expressions}@dots{} 22903Convert the values of one or more @var{expressions} under the control of 22904the string @var{template} to a command line, and call it. 22905 22906@end table 22907 22908@node Python 22909@section Scripting @value{GDBN} using Python 22910@cindex python scripting 22911@cindex scripting with python 22912 22913You can script @value{GDBN} using the @uref{http://www.python.org/, 22914Python programming language}. This feature is available only if 22915@value{GDBN} was configured using @option{--with-python}. 22916 22917@cindex python directory 22918Python scripts used by @value{GDBN} should be installed in 22919@file{@var{data-directory}/python}, where @var{data-directory} is 22920the data directory as determined at @value{GDBN} startup (@pxref{Data Files}). 22921This directory, known as the @dfn{python directory}, 22922is automatically added to the Python Search Path in order to allow 22923the Python interpreter to locate all scripts installed at this location. 22924 22925Additionally, @value{GDBN} commands and convenience functions which 22926are written in Python and are located in the 22927@file{@var{data-directory}/python/gdb/command} or 22928@file{@var{data-directory}/python/gdb/function} directories are 22929automatically imported when @value{GDBN} starts. 22930 22931@menu 22932* Python Commands:: Accessing Python from @value{GDBN}. 22933* Python API:: Accessing @value{GDBN} from Python. 22934* Python Auto-loading:: Automatically loading Python code. 22935* Python modules:: Python modules provided by @value{GDBN}. 22936@end menu 22937 22938@node Python Commands 22939@subsection Python Commands 22940@cindex python commands 22941@cindex commands to access python 22942 22943@value{GDBN} provides two commands for accessing the Python interpreter, 22944and one related setting: 22945 22946@table @code 22947@kindex python-interactive 22948@kindex pi 22949@item python-interactive @r{[}@var{command}@r{]} 22950@itemx pi @r{[}@var{command}@r{]} 22951Without an argument, the @code{python-interactive} command can be used 22952to start an interactive Python prompt. To return to @value{GDBN}, 22953type the @code{EOF} character (e.g., @kbd{Ctrl-D} on an empty prompt). 22954 22955Alternatively, a single-line Python command can be given as an 22956argument and evaluated. If the command is an expression, the result 22957will be printed; otherwise, nothing will be printed. For example: 22958 22959@smallexample 22960(@value{GDBP}) python-interactive 2 + 3 229615 22962@end smallexample 22963 22964@kindex python 22965@kindex py 22966@item python @r{[}@var{command}@r{]} 22967@itemx py @r{[}@var{command}@r{]} 22968The @code{python} command can be used to evaluate Python code. 22969 22970If given an argument, the @code{python} command will evaluate the 22971argument as a Python command. For example: 22972 22973@smallexample 22974(@value{GDBP}) python print 23 2297523 22976@end smallexample 22977 22978If you do not provide an argument to @code{python}, it will act as a 22979multi-line command, like @code{define}. In this case, the Python 22980script is made up of subsequent command lines, given after the 22981@code{python} command. This command list is terminated using a line 22982containing @code{end}. For example: 22983 22984@smallexample 22985(@value{GDBP}) python 22986Type python script 22987End with a line saying just "end". 22988>print 23 22989>end 2299023 22991@end smallexample 22992 22993@kindex set python print-stack 22994@item set python print-stack 22995By default, @value{GDBN} will print only the message component of a 22996Python exception when an error occurs in a Python script. This can be 22997controlled using @code{set python print-stack}: if @code{full}, then 22998full Python stack printing is enabled; if @code{none}, then Python stack 22999and message printing is disabled; if @code{message}, the default, only 23000the message component of the error is printed. 23001@end table 23002 23003It is also possible to execute a Python script from the @value{GDBN} 23004interpreter: 23005 23006@table @code 23007@item source @file{script-name} 23008The script name must end with @samp{.py} and @value{GDBN} must be configured 23009to recognize the script language based on filename extension using 23010the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}. 23011 23012@item python execfile ("script-name") 23013This method is based on the @code{execfile} Python built-in function, 23014and thus is always available. 23015@end table 23016 23017@node Python API 23018@subsection Python API 23019@cindex python api 23020@cindex programming in python 23021 23022@cindex python stdout 23023@cindex python pagination 23024At startup, @value{GDBN} overrides Python's @code{sys.stdout} and 23025@code{sys.stderr} to print using @value{GDBN}'s output-paging streams. 23026A Python program which outputs to one of these streams may have its 23027output interrupted by the user (@pxref{Screen Size}). In this 23028situation, a Python @code{KeyboardInterrupt} exception is thrown. 23029 23030@menu 23031* Basic Python:: Basic Python Functions. 23032* Exception Handling:: How Python exceptions are translated. 23033* Values From Inferior:: Python representation of values. 23034* Types In Python:: Python representation of types. 23035* Pretty Printing API:: Pretty-printing values. 23036* Selecting Pretty-Printers:: How GDB chooses a pretty-printer. 23037* Writing a Pretty-Printer:: Writing a Pretty-Printer. 23038* Type Printing API:: Pretty-printing types. 23039* Inferiors In Python:: Python representation of inferiors (processes) 23040* Events In Python:: Listening for events from @value{GDBN}. 23041* Threads In Python:: Accessing inferior threads from Python. 23042* Commands In Python:: Implementing new commands in Python. 23043* Parameters In Python:: Adding new @value{GDBN} parameters. 23044* Functions In Python:: Writing new convenience functions. 23045* Progspaces In Python:: Program spaces. 23046* Objfiles In Python:: Object files. 23047* Frames In Python:: Accessing inferior stack frames from Python. 23048* Blocks In Python:: Accessing frame blocks from Python. 23049* Symbols In Python:: Python representation of symbols. 23050* Symbol Tables In Python:: Python representation of symbol tables. 23051* Breakpoints In Python:: Manipulating breakpoints using Python. 23052* Finish Breakpoints in Python:: Setting Breakpoints on function return 23053 using Python. 23054* Lazy Strings In Python:: Python representation of lazy strings. 23055* Architectures In Python:: Python representation of architectures. 23056@end menu 23057 23058@node Basic Python 23059@subsubsection Basic Python 23060 23061@cindex python functions 23062@cindex python module 23063@cindex gdb module 23064@value{GDBN} introduces a new Python module, named @code{gdb}. All 23065methods and classes added by @value{GDBN} are placed in this module. 23066@value{GDBN} automatically @code{import}s the @code{gdb} module for 23067use in all scripts evaluated by the @code{python} command. 23068 23069@findex gdb.PYTHONDIR 23070@defvar gdb.PYTHONDIR 23071A string containing the python directory (@pxref{Python}). 23072@end defvar 23073 23074@findex gdb.execute 23075@defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]}) 23076Evaluate @var{command}, a string, as a @value{GDBN} CLI command. 23077If a GDB exception happens while @var{command} runs, it is 23078translated as described in @ref{Exception Handling,,Exception Handling}. 23079 23080@var{from_tty} specifies whether @value{GDBN} ought to consider this 23081command as having originated from the user invoking it interactively. 23082It must be a boolean value. If omitted, it defaults to @code{False}. 23083 23084By default, any output produced by @var{command} is sent to 23085@value{GDBN}'s standard output. If the @var{to_string} parameter is 23086@code{True}, then output will be collected by @code{gdb.execute} and 23087returned as a string. The default is @code{False}, in which case the 23088return value is @code{None}. If @var{to_string} is @code{True}, the 23089@value{GDBN} virtual terminal will be temporarily set to unlimited width 23090and height, and its pagination will be disabled; @pxref{Screen Size}. 23091@end defun 23092 23093@findex gdb.breakpoints 23094@defun gdb.breakpoints () 23095Return a sequence holding all of @value{GDBN}'s breakpoints. 23096@xref{Breakpoints In Python}, for more information. 23097@end defun 23098 23099@findex gdb.parameter 23100@defun gdb.parameter (parameter) 23101Return the value of a @value{GDBN} parameter. @var{parameter} is a 23102string naming the parameter to look up; @var{parameter} may contain 23103spaces if the parameter has a multi-part name. For example, 23104@samp{print object} is a valid parameter name. 23105 23106If the named parameter does not exist, this function throws a 23107@code{gdb.error} (@pxref{Exception Handling}). Otherwise, the 23108parameter's value is converted to a Python value of the appropriate 23109type, and returned. 23110@end defun 23111 23112@findex gdb.history 23113@defun gdb.history (number) 23114Return a value from @value{GDBN}'s value history (@pxref{Value 23115History}). @var{number} indicates which history element to return. 23116If @var{number} is negative, then @value{GDBN} will take its absolute value 23117and count backward from the last element (i.e., the most recent element) to 23118find the value to return. If @var{number} is zero, then @value{GDBN} will 23119return the most recent element. If the element specified by @var{number} 23120doesn't exist in the value history, a @code{gdb.error} exception will be 23121raised. 23122 23123If no exception is raised, the return value is always an instance of 23124@code{gdb.Value} (@pxref{Values From Inferior}). 23125@end defun 23126 23127@findex gdb.parse_and_eval 23128@defun gdb.parse_and_eval (expression) 23129Parse @var{expression} as an expression in the current language, 23130evaluate it, and return the result as a @code{gdb.Value}. 23131@var{expression} must be a string. 23132 23133This function can be useful when implementing a new command 23134(@pxref{Commands In Python}), as it provides a way to parse the 23135command's argument as an expression. It is also useful simply to 23136compute values, for example, it is the only way to get the value of a 23137convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}. 23138@end defun 23139 23140@findex gdb.find_pc_line 23141@defun gdb.find_pc_line (pc) 23142Return the @code{gdb.Symtab_and_line} object corresponding to the 23143@var{pc} value. @xref{Symbol Tables In Python}. If an invalid 23144value of @var{pc} is passed as an argument, then the @code{symtab} and 23145@code{line} attributes of the returned @code{gdb.Symtab_and_line} object 23146will be @code{None} and 0 respectively. 23147@end defun 23148 23149@findex gdb.post_event 23150@defun gdb.post_event (event) 23151Put @var{event}, a callable object taking no arguments, into 23152@value{GDBN}'s internal event queue. This callable will be invoked at 23153some later point, during @value{GDBN}'s event processing. Events 23154posted using @code{post_event} will be run in the order in which they 23155were posted; however, there is no way to know when they will be 23156processed relative to other events inside @value{GDBN}. 23157 23158@value{GDBN} is not thread-safe. If your Python program uses multiple 23159threads, you must be careful to only call @value{GDBN}-specific 23160functions in the main @value{GDBN} thread. @code{post_event} ensures 23161this. For example: 23162 23163@smallexample 23164(@value{GDBP}) python 23165>import threading 23166> 23167>class Writer(): 23168> def __init__(self, message): 23169> self.message = message; 23170> def __call__(self): 23171> gdb.write(self.message) 23172> 23173>class MyThread1 (threading.Thread): 23174> def run (self): 23175> gdb.post_event(Writer("Hello ")) 23176> 23177>class MyThread2 (threading.Thread): 23178> def run (self): 23179> gdb.post_event(Writer("World\n")) 23180> 23181>MyThread1().start() 23182>MyThread2().start() 23183>end 23184(@value{GDBP}) Hello World 23185@end smallexample 23186@end defun 23187 23188@findex gdb.write 23189@defun gdb.write (string @r{[}, stream{]}) 23190Print a string to @value{GDBN}'s paginated output stream. The 23191optional @var{stream} determines the stream to print to. The default 23192stream is @value{GDBN}'s standard output stream. Possible stream 23193values are: 23194 23195@table @code 23196@findex STDOUT 23197@findex gdb.STDOUT 23198@item gdb.STDOUT 23199@value{GDBN}'s standard output stream. 23200 23201@findex STDERR 23202@findex gdb.STDERR 23203@item gdb.STDERR 23204@value{GDBN}'s standard error stream. 23205 23206@findex STDLOG 23207@findex gdb.STDLOG 23208@item gdb.STDLOG 23209@value{GDBN}'s log stream (@pxref{Logging Output}). 23210@end table 23211 23212Writing to @code{sys.stdout} or @code{sys.stderr} will automatically 23213call this function and will automatically direct the output to the 23214relevant stream. 23215@end defun 23216 23217@findex gdb.flush 23218@defun gdb.flush () 23219Flush the buffer of a @value{GDBN} paginated stream so that the 23220contents are displayed immediately. @value{GDBN} will flush the 23221contents of a stream automatically when it encounters a newline in the 23222buffer. The optional @var{stream} determines the stream to flush. The 23223default stream is @value{GDBN}'s standard output stream. Possible 23224stream values are: 23225 23226@table @code 23227@findex STDOUT 23228@findex gdb.STDOUT 23229@item gdb.STDOUT 23230@value{GDBN}'s standard output stream. 23231 23232@findex STDERR 23233@findex gdb.STDERR 23234@item gdb.STDERR 23235@value{GDBN}'s standard error stream. 23236 23237@findex STDLOG 23238@findex gdb.STDLOG 23239@item gdb.STDLOG 23240@value{GDBN}'s log stream (@pxref{Logging Output}). 23241 23242@end table 23243 23244Flushing @code{sys.stdout} or @code{sys.stderr} will automatically 23245call this function for the relevant stream. 23246@end defun 23247 23248@findex gdb.target_charset 23249@defun gdb.target_charset () 23250Return the name of the current target character set (@pxref{Character 23251Sets}). This differs from @code{gdb.parameter('target-charset')} in 23252that @samp{auto} is never returned. 23253@end defun 23254 23255@findex gdb.target_wide_charset 23256@defun gdb.target_wide_charset () 23257Return the name of the current target wide character set 23258(@pxref{Character Sets}). This differs from 23259@code{gdb.parameter('target-wide-charset')} in that @samp{auto} is 23260never returned. 23261@end defun 23262 23263@findex gdb.solib_name 23264@defun gdb.solib_name (address) 23265Return the name of the shared library holding the given @var{address} 23266as a string, or @code{None}. 23267@end defun 23268 23269@findex gdb.decode_line 23270@defun gdb.decode_line @r{[}expression@r{]} 23271Return locations of the line specified by @var{expression}, or of the 23272current line if no argument was given. This function returns a Python 23273tuple containing two elements. The first element contains a string 23274holding any unparsed section of @var{expression} (or @code{None} if 23275the expression has been fully parsed). The second element contains 23276either @code{None} or another tuple that contains all the locations 23277that match the expression represented as @code{gdb.Symtab_and_line} 23278objects (@pxref{Symbol Tables In Python}). If @var{expression} is 23279provided, it is decoded the way that @value{GDBN}'s inbuilt 23280@code{break} or @code{edit} commands do (@pxref{Specify Location}). 23281@end defun 23282 23283@defun gdb.prompt_hook (current_prompt) 23284@anchor{prompt_hook} 23285 23286If @var{prompt_hook} is callable, @value{GDBN} will call the method 23287assigned to this operation before a prompt is displayed by 23288@value{GDBN}. 23289 23290The parameter @code{current_prompt} contains the current @value{GDBN} 23291prompt. This method must return a Python string, or @code{None}. If 23292a string is returned, the @value{GDBN} prompt will be set to that 23293string. If @code{None} is returned, @value{GDBN} will continue to use 23294the current prompt. 23295 23296Some prompts cannot be substituted in @value{GDBN}. Secondary prompts 23297such as those used by readline for command input, and annotation 23298related prompts are prohibited from being changed. 23299@end defun 23300 23301@node Exception Handling 23302@subsubsection Exception Handling 23303@cindex python exceptions 23304@cindex exceptions, python 23305 23306When executing the @code{python} command, Python exceptions 23307uncaught within the Python code are translated to calls to 23308@value{GDBN} error-reporting mechanism. If the command that called 23309@code{python} does not handle the error, @value{GDBN} will 23310terminate it and print an error message containing the Python 23311exception name, the associated value, and the Python call stack 23312backtrace at the point where the exception was raised. Example: 23313 23314@smallexample 23315(@value{GDBP}) python print foo 23316Traceback (most recent call last): 23317 File "<string>", line 1, in <module> 23318NameError: name 'foo' is not defined 23319@end smallexample 23320 23321@value{GDBN} errors that happen in @value{GDBN} commands invoked by 23322Python code are converted to Python exceptions. The type of the 23323Python exception depends on the error. 23324 23325@ftable @code 23326@item gdb.error 23327This is the base class for most exceptions generated by @value{GDBN}. 23328It is derived from @code{RuntimeError}, for compatibility with earlier 23329versions of @value{GDBN}. 23330 23331If an error occurring in @value{GDBN} does not fit into some more 23332specific category, then the generated exception will have this type. 23333 23334@item gdb.MemoryError 23335This is a subclass of @code{gdb.error} which is thrown when an 23336operation tried to access invalid memory in the inferior. 23337 23338@item KeyboardInterrupt 23339User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination 23340prompt) is translated to a Python @code{KeyboardInterrupt} exception. 23341@end ftable 23342 23343In all cases, your exception handler will see the @value{GDBN} error 23344message as its value and the Python call stack backtrace at the Python 23345statement closest to where the @value{GDBN} error occured as the 23346traceback. 23347 23348@findex gdb.GdbError 23349When implementing @value{GDBN} commands in Python via @code{gdb.Command}, 23350it is useful to be able to throw an exception that doesn't cause a 23351traceback to be printed. For example, the user may have invoked the 23352command incorrectly. Use the @code{gdb.GdbError} exception 23353to handle this case. Example: 23354 23355@smallexample 23356(gdb) python 23357>class HelloWorld (gdb.Command): 23358> """Greet the whole world.""" 23359> def __init__ (self): 23360> super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER) 23361> def invoke (self, args, from_tty): 23362> argv = gdb.string_to_argv (args) 23363> if len (argv) != 0: 23364> raise gdb.GdbError ("hello-world takes no arguments") 23365> print "Hello, World!" 23366>HelloWorld () 23367>end 23368(gdb) hello-world 42 23369hello-world takes no arguments 23370@end smallexample 23371 23372@node Values From Inferior 23373@subsubsection Values From Inferior 23374@cindex values from inferior, with Python 23375@cindex python, working with values from inferior 23376 23377@cindex @code{gdb.Value} 23378@value{GDBN} provides values it obtains from the inferior program in 23379an object of type @code{gdb.Value}. @value{GDBN} uses this object 23380for its internal bookkeeping of the inferior's values, and for 23381fetching values when necessary. 23382 23383Inferior values that are simple scalars can be used directly in 23384Python expressions that are valid for the value's data type. Here's 23385an example for an integer or floating-point value @code{some_val}: 23386 23387@smallexample 23388bar = some_val + 2 23389@end smallexample 23390 23391@noindent 23392As result of this, @code{bar} will also be a @code{gdb.Value} object 23393whose values are of the same type as those of @code{some_val}. 23394 23395Inferior values that are structures or instances of some class can 23396be accessed using the Python @dfn{dictionary syntax}. For example, if 23397@code{some_val} is a @code{gdb.Value} instance holding a structure, you 23398can access its @code{foo} element with: 23399 23400@smallexample 23401bar = some_val['foo'] 23402@end smallexample 23403 23404Again, @code{bar} will also be a @code{gdb.Value} object. 23405 23406A @code{gdb.Value} that represents a function can be executed via 23407inferior function call. Any arguments provided to the call must match 23408the function's prototype, and must be provided in the order specified 23409by that prototype. 23410 23411For example, @code{some_val} is a @code{gdb.Value} instance 23412representing a function that takes two integers as arguments. To 23413execute this function, call it like so: 23414 23415@smallexample 23416result = some_val (10,20) 23417@end smallexample 23418 23419Any values returned from a function call will be stored as a 23420@code{gdb.Value}. 23421 23422The following attributes are provided: 23423 23424@defvar Value.address 23425If this object is addressable, this read-only attribute holds a 23426@code{gdb.Value} object representing the address. Otherwise, 23427this attribute holds @code{None}. 23428@end defvar 23429 23430@cindex optimized out value in Python 23431@defvar Value.is_optimized_out 23432This read-only boolean attribute is true if the compiler optimized out 23433this value, thus it is not available for fetching from the inferior. 23434@end defvar 23435 23436@defvar Value.type 23437The type of this @code{gdb.Value}. The value of this attribute is a 23438@code{gdb.Type} object (@pxref{Types In Python}). 23439@end defvar 23440 23441@defvar Value.dynamic_type 23442The dynamic type of this @code{gdb.Value}. This uses C@t{++} run-time 23443type information (@acronym{RTTI}) to determine the dynamic type of the 23444value. If this value is of class type, it will return the class in 23445which the value is embedded, if any. If this value is of pointer or 23446reference to a class type, it will compute the dynamic type of the 23447referenced object, and return a pointer or reference to that type, 23448respectively. In all other cases, it will return the value's static 23449type. 23450 23451Note that this feature will only work when debugging a C@t{++} program 23452that includes @acronym{RTTI} for the object in question. Otherwise, 23453it will just return the static type of the value as in @kbd{ptype foo} 23454(@pxref{Symbols, ptype}). 23455@end defvar 23456 23457@defvar Value.is_lazy 23458The value of this read-only boolean attribute is @code{True} if this 23459@code{gdb.Value} has not yet been fetched from the inferior. 23460@value{GDBN} does not fetch values until necessary, for efficiency. 23461For example: 23462 23463@smallexample 23464myval = gdb.parse_and_eval ('somevar') 23465@end smallexample 23466 23467The value of @code{somevar} is not fetched at this time. It will be 23468fetched when the value is needed, or when the @code{fetch_lazy} 23469method is invoked. 23470@end defvar 23471 23472The following methods are provided: 23473 23474@defun Value.__init__ (@var{val}) 23475Many Python values can be converted directly to a @code{gdb.Value} via 23476this object initializer. Specifically: 23477 23478@table @asis 23479@item Python boolean 23480A Python boolean is converted to the boolean type from the current 23481language. 23482 23483@item Python integer 23484A Python integer is converted to the C @code{long} type for the 23485current architecture. 23486 23487@item Python long 23488A Python long is converted to the C @code{long long} type for the 23489current architecture. 23490 23491@item Python float 23492A Python float is converted to the C @code{double} type for the 23493current architecture. 23494 23495@item Python string 23496A Python string is converted to a target string, using the current 23497target encoding. 23498 23499@item @code{gdb.Value} 23500If @code{val} is a @code{gdb.Value}, then a copy of the value is made. 23501 23502@item @code{gdb.LazyString} 23503If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In 23504Python}), then the lazy string's @code{value} method is called, and 23505its result is used. 23506@end table 23507@end defun 23508 23509@defun Value.cast (type) 23510Return a new instance of @code{gdb.Value} that is the result of 23511casting this instance to the type described by @var{type}, which must 23512be a @code{gdb.Type} object. If the cast cannot be performed for some 23513reason, this method throws an exception. 23514@end defun 23515 23516@defun Value.dereference () 23517For pointer data types, this method returns a new @code{gdb.Value} object 23518whose contents is the object pointed to by the pointer. For example, if 23519@code{foo} is a C pointer to an @code{int}, declared in your C program as 23520 23521@smallexample 23522int *foo; 23523@end smallexample 23524 23525@noindent 23526then you can use the corresponding @code{gdb.Value} to access what 23527@code{foo} points to like this: 23528 23529@smallexample 23530bar = foo.dereference () 23531@end smallexample 23532 23533The result @code{bar} will be a @code{gdb.Value} object holding the 23534value pointed to by @code{foo}. 23535 23536A similar function @code{Value.referenced_value} exists which also 23537returns @code{gdb.Value} objects corresonding to the values pointed to 23538by pointer values (and additionally, values referenced by reference 23539values). However, the behavior of @code{Value.dereference} 23540differs from @code{Value.referenced_value} by the fact that the 23541behavior of @code{Value.dereference} is identical to applying the C 23542unary operator @code{*} on a given value. For example, consider a 23543reference to a pointer @code{ptrref}, declared in your C@t{++} program 23544as 23545 23546@smallexample 23547typedef int *intptr; 23548... 23549int val = 10; 23550intptr ptr = &val; 23551intptr &ptrref = ptr; 23552@end smallexample 23553 23554Though @code{ptrref} is a reference value, one can apply the method 23555@code{Value.dereference} to the @code{gdb.Value} object corresponding 23556to it and obtain a @code{gdb.Value} which is identical to that 23557corresponding to @code{val}. However, if you apply the method 23558@code{Value.referenced_value}, the result would be a @code{gdb.Value} 23559object identical to that corresponding to @code{ptr}. 23560 23561@smallexample 23562py_ptrref = gdb.parse_and_eval ("ptrref") 23563py_val = py_ptrref.dereference () 23564py_ptr = py_ptrref.referenced_value () 23565@end smallexample 23566 23567The @code{gdb.Value} object @code{py_val} is identical to that 23568corresponding to @code{val}, and @code{py_ptr} is identical to that 23569corresponding to @code{ptr}. In general, @code{Value.dereference} can 23570be applied whenever the C unary operator @code{*} can be applied 23571to the corresponding C value. For those cases where applying both 23572@code{Value.dereference} and @code{Value.referenced_value} is allowed, 23573the results obtained need not be identical (as we have seen in the above 23574example). The results are however identical when applied on 23575@code{gdb.Value} objects corresponding to pointers (@code{gdb.Value} 23576objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program. 23577@end defun 23578 23579@defun Value.referenced_value () 23580For pointer or reference data types, this method returns a new 23581@code{gdb.Value} object corresponding to the value referenced by the 23582pointer/reference value. For pointer data types, 23583@code{Value.dereference} and @code{Value.referenced_value} produce 23584identical results. The difference between these methods is that 23585@code{Value.dereference} cannot get the values referenced by reference 23586values. For example, consider a reference to an @code{int}, declared 23587in your C@t{++} program as 23588 23589@smallexample 23590int val = 10; 23591int &ref = val; 23592@end smallexample 23593 23594@noindent 23595then applying @code{Value.dereference} to the @code{gdb.Value} object 23596corresponding to @code{ref} will result in an error, while applying 23597@code{Value.referenced_value} will result in a @code{gdb.Value} object 23598identical to that corresponding to @code{val}. 23599 23600@smallexample 23601py_ref = gdb.parse_and_eval ("ref") 23602er_ref = py_ref.dereference () # Results in error 23603py_val = py_ref.referenced_value () # Returns the referenced value 23604@end smallexample 23605 23606The @code{gdb.Value} object @code{py_val} is identical to that 23607corresponding to @code{val}. 23608@end defun 23609 23610@defun Value.dynamic_cast (type) 23611Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast} 23612operator were used. Consult a C@t{++} reference for details. 23613@end defun 23614 23615@defun Value.reinterpret_cast (type) 23616Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast} 23617operator were used. Consult a C@t{++} reference for details. 23618@end defun 23619 23620@defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]}) 23621If this @code{gdb.Value} represents a string, then this method 23622converts the contents to a Python string. Otherwise, this method will 23623throw an exception. 23624 23625Strings are recognized in a language-specific way; whether a given 23626@code{gdb.Value} represents a string is determined by the current 23627language. 23628 23629For C-like languages, a value is a string if it is a pointer to or an 23630array of characters or ints. The string is assumed to be terminated 23631by a zero of the appropriate width. However if the optional length 23632argument is given, the string will be converted to that given length, 23633ignoring any embedded zeros that the string may contain. 23634 23635If the optional @var{encoding} argument is given, it must be a string 23636naming the encoding of the string in the @code{gdb.Value}, such as 23637@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts 23638the same encodings as the corresponding argument to Python's 23639@code{string.decode} method, and the Python codec machinery will be used 23640to convert the string. If @var{encoding} is not given, or if 23641@var{encoding} is the empty string, then either the @code{target-charset} 23642(@pxref{Character Sets}) will be used, or a language-specific encoding 23643will be used, if the current language is able to supply one. 23644 23645The optional @var{errors} argument is the same as the corresponding 23646argument to Python's @code{string.decode} method. 23647 23648If the optional @var{length} argument is given, the string will be 23649fetched and converted to the given length. 23650@end defun 23651 23652@defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]}) 23653If this @code{gdb.Value} represents a string, then this method 23654converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings 23655In Python}). Otherwise, this method will throw an exception. 23656 23657If the optional @var{encoding} argument is given, it must be a string 23658naming the encoding of the @code{gdb.LazyString}. Some examples are: 23659@samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the 23660@var{encoding} argument is an encoding that @value{GDBN} does 23661recognize, @value{GDBN} will raise an error. 23662 23663When a lazy string is printed, the @value{GDBN} encoding machinery is 23664used to convert the string during printing. If the optional 23665@var{encoding} argument is not provided, or is an empty string, 23666@value{GDBN} will automatically select the encoding most suitable for 23667the string type. For further information on encoding in @value{GDBN} 23668please see @ref{Character Sets}. 23669 23670If the optional @var{length} argument is given, the string will be 23671fetched and encoded to the length of characters specified. If 23672the @var{length} argument is not provided, the string will be fetched 23673and encoded until a null of appropriate width is found. 23674@end defun 23675 23676@defun Value.fetch_lazy () 23677If the @code{gdb.Value} object is currently a lazy value 23678(@code{gdb.Value.is_lazy} is @code{True}), then the value is 23679fetched from the inferior. Any errors that occur in the process 23680will produce a Python exception. 23681 23682If the @code{gdb.Value} object is not a lazy value, this method 23683has no effect. 23684 23685This method does not return a value. 23686@end defun 23687 23688 23689@node Types In Python 23690@subsubsection Types In Python 23691@cindex types in Python 23692@cindex Python, working with types 23693 23694@tindex gdb.Type 23695@value{GDBN} represents types from the inferior using the class 23696@code{gdb.Type}. 23697 23698The following type-related functions are available in the @code{gdb} 23699module: 23700 23701@findex gdb.lookup_type 23702@defun gdb.lookup_type (name @r{[}, block@r{]}) 23703This function looks up a type by name. @var{name} is the name of the 23704type to look up. It must be a string. 23705 23706If @var{block} is given, then @var{name} is looked up in that scope. 23707Otherwise, it is searched for globally. 23708 23709Ordinarily, this function will return an instance of @code{gdb.Type}. 23710If the named type cannot be found, it will throw an exception. 23711@end defun 23712 23713If the type is a structure or class type, or an enum type, the fields 23714of that type can be accessed using the Python @dfn{dictionary syntax}. 23715For example, if @code{some_type} is a @code{gdb.Type} instance holding 23716a structure type, you can access its @code{foo} field with: 23717 23718@smallexample 23719bar = some_type['foo'] 23720@end smallexample 23721 23722@code{bar} will be a @code{gdb.Field} object; see below under the 23723description of the @code{Type.fields} method for a description of the 23724@code{gdb.Field} class. 23725 23726An instance of @code{Type} has the following attributes: 23727 23728@defvar Type.code 23729The type code for this type. The type code will be one of the 23730@code{TYPE_CODE_} constants defined below. 23731@end defvar 23732 23733@defvar Type.sizeof 23734The size of this type, in target @code{char} units. Usually, a 23735target's @code{char} type will be an 8-bit byte. However, on some 23736unusual platforms, this type may have a different size. 23737@end defvar 23738 23739@defvar Type.tag 23740The tag name for this type. The tag name is the name after 23741@code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all 23742languages have this concept. If this type has no tag name, then 23743@code{None} is returned. 23744@end defvar 23745 23746The following methods are provided: 23747 23748@defun Type.fields () 23749For structure and union types, this method returns the fields. Range 23750types have two fields, the minimum and maximum values. Enum types 23751have one field per enum constant. Function and method types have one 23752field per parameter. The base types of C@t{++} classes are also 23753represented as fields. If the type has no fields, or does not fit 23754into one of these categories, an empty sequence will be returned. 23755 23756Each field is a @code{gdb.Field} object, with some pre-defined attributes: 23757@table @code 23758@item bitpos 23759This attribute is not available for @code{static} fields (as in 23760C@t{++} or Java). For non-@code{static} fields, the value is the bit 23761position of the field. For @code{enum} fields, the value is the 23762enumeration member's integer representation. 23763 23764@item name 23765The name of the field, or @code{None} for anonymous fields. 23766 23767@item artificial 23768This is @code{True} if the field is artificial, usually meaning that 23769it was provided by the compiler and not the user. This attribute is 23770always provided, and is @code{False} if the field is not artificial. 23771 23772@item is_base_class 23773This is @code{True} if the field represents a base class of a C@t{++} 23774structure. This attribute is always provided, and is @code{False} 23775if the field is not a base class of the type that is the argument of 23776@code{fields}, or if that type was not a C@t{++} class. 23777 23778@item bitsize 23779If the field is packed, or is a bitfield, then this will have a 23780non-zero value, which is the size of the field in bits. Otherwise, 23781this will be zero; in this case the field's size is given by its type. 23782 23783@item type 23784The type of the field. This is usually an instance of @code{Type}, 23785but it can be @code{None} in some situations. 23786@end table 23787@end defun 23788 23789@defun Type.array (@var{n1} @r{[}, @var{n2}@r{]}) 23790Return a new @code{gdb.Type} object which represents an array of this 23791type. If one argument is given, it is the inclusive upper bound of 23792the array; in this case the lower bound is zero. If two arguments are 23793given, the first argument is the lower bound of the array, and the 23794second argument is the upper bound of the array. An array's length 23795must not be negative, but the bounds can be. 23796@end defun 23797 23798@defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]}) 23799Return a new @code{gdb.Type} object which represents a vector of this 23800type. If one argument is given, it is the inclusive upper bound of 23801the vector; in this case the lower bound is zero. If two arguments are 23802given, the first argument is the lower bound of the vector, and the 23803second argument is the upper bound of the vector. A vector's length 23804must not be negative, but the bounds can be. 23805 23806The difference between an @code{array} and a @code{vector} is that 23807arrays behave like in C: when used in expressions they decay to a pointer 23808to the first element whereas vectors are treated as first class values. 23809@end defun 23810 23811@defun Type.const () 23812Return a new @code{gdb.Type} object which represents a 23813@code{const}-qualified variant of this type. 23814@end defun 23815 23816@defun Type.volatile () 23817Return a new @code{gdb.Type} object which represents a 23818@code{volatile}-qualified variant of this type. 23819@end defun 23820 23821@defun Type.unqualified () 23822Return a new @code{gdb.Type} object which represents an unqualified 23823variant of this type. That is, the result is neither @code{const} nor 23824@code{volatile}. 23825@end defun 23826 23827@defun Type.range () 23828Return a Python @code{Tuple} object that contains two elements: the 23829low bound of the argument type and the high bound of that type. If 23830the type does not have a range, @value{GDBN} will raise a 23831@code{gdb.error} exception (@pxref{Exception Handling}). 23832@end defun 23833 23834@defun Type.reference () 23835Return a new @code{gdb.Type} object which represents a reference to this 23836type. 23837@end defun 23838 23839@defun Type.pointer () 23840Return a new @code{gdb.Type} object which represents a pointer to this 23841type. 23842@end defun 23843 23844@defun Type.strip_typedefs () 23845Return a new @code{gdb.Type} that represents the real type, 23846after removing all layers of typedefs. 23847@end defun 23848 23849@defun Type.target () 23850Return a new @code{gdb.Type} object which represents the target type 23851of this type. 23852 23853For a pointer type, the target type is the type of the pointed-to 23854object. For an array type (meaning C-like arrays), the target type is 23855the type of the elements of the array. For a function or method type, 23856the target type is the type of the return value. For a complex type, 23857the target type is the type of the elements. For a typedef, the 23858target type is the aliased type. 23859 23860If the type does not have a target, this method will throw an 23861exception. 23862@end defun 23863 23864@defun Type.template_argument (n @r{[}, block@r{]}) 23865If this @code{gdb.Type} is an instantiation of a template, this will 23866return a new @code{gdb.Type} which represents the type of the 23867@var{n}th template argument. 23868 23869If this @code{gdb.Type} is not a template type, this will throw an 23870exception. Ordinarily, only C@t{++} code will have template types. 23871 23872If @var{block} is given, then @var{name} is looked up in that scope. 23873Otherwise, it is searched for globally. 23874@end defun 23875 23876 23877Each type has a code, which indicates what category this type falls 23878into. The available type categories are represented by constants 23879defined in the @code{gdb} module: 23880 23881@table @code 23882@findex TYPE_CODE_PTR 23883@findex gdb.TYPE_CODE_PTR 23884@item gdb.TYPE_CODE_PTR 23885The type is a pointer. 23886 23887@findex TYPE_CODE_ARRAY 23888@findex gdb.TYPE_CODE_ARRAY 23889@item gdb.TYPE_CODE_ARRAY 23890The type is an array. 23891 23892@findex TYPE_CODE_STRUCT 23893@findex gdb.TYPE_CODE_STRUCT 23894@item gdb.TYPE_CODE_STRUCT 23895The type is a structure. 23896 23897@findex TYPE_CODE_UNION 23898@findex gdb.TYPE_CODE_UNION 23899@item gdb.TYPE_CODE_UNION 23900The type is a union. 23901 23902@findex TYPE_CODE_ENUM 23903@findex gdb.TYPE_CODE_ENUM 23904@item gdb.TYPE_CODE_ENUM 23905The type is an enum. 23906 23907@findex TYPE_CODE_FLAGS 23908@findex gdb.TYPE_CODE_FLAGS 23909@item gdb.TYPE_CODE_FLAGS 23910A bit flags type, used for things such as status registers. 23911 23912@findex TYPE_CODE_FUNC 23913@findex gdb.TYPE_CODE_FUNC 23914@item gdb.TYPE_CODE_FUNC 23915The type is a function. 23916 23917@findex TYPE_CODE_INT 23918@findex gdb.TYPE_CODE_INT 23919@item gdb.TYPE_CODE_INT 23920The type is an integer type. 23921 23922@findex TYPE_CODE_FLT 23923@findex gdb.TYPE_CODE_FLT 23924@item gdb.TYPE_CODE_FLT 23925A floating point type. 23926 23927@findex TYPE_CODE_VOID 23928@findex gdb.TYPE_CODE_VOID 23929@item gdb.TYPE_CODE_VOID 23930The special type @code{void}. 23931 23932@findex TYPE_CODE_SET 23933@findex gdb.TYPE_CODE_SET 23934@item gdb.TYPE_CODE_SET 23935A Pascal set type. 23936 23937@findex TYPE_CODE_RANGE 23938@findex gdb.TYPE_CODE_RANGE 23939@item gdb.TYPE_CODE_RANGE 23940A range type, that is, an integer type with bounds. 23941 23942@findex TYPE_CODE_STRING 23943@findex gdb.TYPE_CODE_STRING 23944@item gdb.TYPE_CODE_STRING 23945A string type. Note that this is only used for certain languages with 23946language-defined string types; C strings are not represented this way. 23947 23948@findex TYPE_CODE_BITSTRING 23949@findex gdb.TYPE_CODE_BITSTRING 23950@item gdb.TYPE_CODE_BITSTRING 23951A string of bits. It is deprecated. 23952 23953@findex TYPE_CODE_ERROR 23954@findex gdb.TYPE_CODE_ERROR 23955@item gdb.TYPE_CODE_ERROR 23956An unknown or erroneous type. 23957 23958@findex TYPE_CODE_METHOD 23959@findex gdb.TYPE_CODE_METHOD 23960@item gdb.TYPE_CODE_METHOD 23961A method type, as found in C@t{++} or Java. 23962 23963@findex TYPE_CODE_METHODPTR 23964@findex gdb.TYPE_CODE_METHODPTR 23965@item gdb.TYPE_CODE_METHODPTR 23966A pointer-to-member-function. 23967 23968@findex TYPE_CODE_MEMBERPTR 23969@findex gdb.TYPE_CODE_MEMBERPTR 23970@item gdb.TYPE_CODE_MEMBERPTR 23971A pointer-to-member. 23972 23973@findex TYPE_CODE_REF 23974@findex gdb.TYPE_CODE_REF 23975@item gdb.TYPE_CODE_REF 23976A reference type. 23977 23978@findex TYPE_CODE_CHAR 23979@findex gdb.TYPE_CODE_CHAR 23980@item gdb.TYPE_CODE_CHAR 23981A character type. 23982 23983@findex TYPE_CODE_BOOL 23984@findex gdb.TYPE_CODE_BOOL 23985@item gdb.TYPE_CODE_BOOL 23986A boolean type. 23987 23988@findex TYPE_CODE_COMPLEX 23989@findex gdb.TYPE_CODE_COMPLEX 23990@item gdb.TYPE_CODE_COMPLEX 23991A complex float type. 23992 23993@findex TYPE_CODE_TYPEDEF 23994@findex gdb.TYPE_CODE_TYPEDEF 23995@item gdb.TYPE_CODE_TYPEDEF 23996A typedef to some other type. 23997 23998@findex TYPE_CODE_NAMESPACE 23999@findex gdb.TYPE_CODE_NAMESPACE 24000@item gdb.TYPE_CODE_NAMESPACE 24001A C@t{++} namespace. 24002 24003@findex TYPE_CODE_DECFLOAT 24004@findex gdb.TYPE_CODE_DECFLOAT 24005@item gdb.TYPE_CODE_DECFLOAT 24006A decimal floating point type. 24007 24008@findex TYPE_CODE_INTERNAL_FUNCTION 24009@findex gdb.TYPE_CODE_INTERNAL_FUNCTION 24010@item gdb.TYPE_CODE_INTERNAL_FUNCTION 24011A function internal to @value{GDBN}. This is the type used to represent 24012convenience functions. 24013@end table 24014 24015Further support for types is provided in the @code{gdb.types} 24016Python module (@pxref{gdb.types}). 24017 24018@node Pretty Printing API 24019@subsubsection Pretty Printing API 24020 24021An example output is provided (@pxref{Pretty Printing}). 24022 24023A pretty-printer is just an object that holds a value and implements a 24024specific interface, defined here. 24025 24026@defun pretty_printer.children (self) 24027@value{GDBN} will call this method on a pretty-printer to compute the 24028children of the pretty-printer's value. 24029 24030This method must return an object conforming to the Python iterator 24031protocol. Each item returned by the iterator must be a tuple holding 24032two elements. The first element is the ``name'' of the child; the 24033second element is the child's value. The value can be any Python 24034object which is convertible to a @value{GDBN} value. 24035 24036This method is optional. If it does not exist, @value{GDBN} will act 24037as though the value has no children. 24038@end defun 24039 24040@defun pretty_printer.display_hint (self) 24041The CLI may call this method and use its result to change the 24042formatting of a value. The result will also be supplied to an MI 24043consumer as a @samp{displayhint} attribute of the variable being 24044printed. 24045 24046This method is optional. If it does exist, this method must return a 24047string. 24048 24049Some display hints are predefined by @value{GDBN}: 24050 24051@table @samp 24052@item array 24053Indicate that the object being printed is ``array-like''. The CLI 24054uses this to respect parameters such as @code{set print elements} and 24055@code{set print array}. 24056 24057@item map 24058Indicate that the object being printed is ``map-like'', and that the 24059children of this value can be assumed to alternate between keys and 24060values. 24061 24062@item string 24063Indicate that the object being printed is ``string-like''. If the 24064printer's @code{to_string} method returns a Python string of some 24065kind, then @value{GDBN} will call its internal language-specific 24066string-printing function to format the string. For the CLI this means 24067adding quotation marks, possibly escaping some characters, respecting 24068@code{set print elements}, and the like. 24069@end table 24070@end defun 24071 24072@defun pretty_printer.to_string (self) 24073@value{GDBN} will call this method to display the string 24074representation of the value passed to the object's constructor. 24075 24076When printing from the CLI, if the @code{to_string} method exists, 24077then @value{GDBN} will prepend its result to the values returned by 24078@code{children}. Exactly how this formatting is done is dependent on 24079the display hint, and may change as more hints are added. Also, 24080depending on the print settings (@pxref{Print Settings}), the CLI may 24081print just the result of @code{to_string} in a stack trace, omitting 24082the result of @code{children}. 24083 24084If this method returns a string, it is printed verbatim. 24085 24086Otherwise, if this method returns an instance of @code{gdb.Value}, 24087then @value{GDBN} prints this value. This may result in a call to 24088another pretty-printer. 24089 24090If instead the method returns a Python value which is convertible to a 24091@code{gdb.Value}, then @value{GDBN} performs the conversion and prints 24092the resulting value. Again, this may result in a call to another 24093pretty-printer. Python scalars (integers, floats, and booleans) and 24094strings are convertible to @code{gdb.Value}; other types are not. 24095 24096Finally, if this method returns @code{None} then no further operations 24097are peformed in this method and nothing is printed. 24098 24099If the result is not one of these types, an exception is raised. 24100@end defun 24101 24102@value{GDBN} provides a function which can be used to look up the 24103default pretty-printer for a @code{gdb.Value}: 24104 24105@findex gdb.default_visualizer 24106@defun gdb.default_visualizer (value) 24107This function takes a @code{gdb.Value} object as an argument. If a 24108pretty-printer for this value exists, then it is returned. If no such 24109printer exists, then this returns @code{None}. 24110@end defun 24111 24112@node Selecting Pretty-Printers 24113@subsubsection Selecting Pretty-Printers 24114 24115The Python list @code{gdb.pretty_printers} contains an array of 24116functions or callable objects that have been registered via addition 24117as a pretty-printer. Printers in this list are called @code{global} 24118printers, they're available when debugging all inferiors. 24119Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute. 24120Each @code{gdb.Objfile} also contains a @code{pretty_printers} 24121attribute. 24122 24123Each function on these lists is passed a single @code{gdb.Value} 24124argument and should return a pretty-printer object conforming to the 24125interface definition above (@pxref{Pretty Printing API}). If a function 24126cannot create a pretty-printer for the value, it should return 24127@code{None}. 24128 24129@value{GDBN} first checks the @code{pretty_printers} attribute of each 24130@code{gdb.Objfile} in the current program space and iteratively calls 24131each enabled lookup routine in the list for that @code{gdb.Objfile} 24132until it receives a pretty-printer object. 24133If no pretty-printer is found in the objfile lists, @value{GDBN} then 24134searches the pretty-printer list of the current program space, 24135calling each enabled function until an object is returned. 24136After these lists have been exhausted, it tries the global 24137@code{gdb.pretty_printers} list, again calling each enabled function until an 24138object is returned. 24139 24140The order in which the objfiles are searched is not specified. For a 24141given list, functions are always invoked from the head of the list, 24142and iterated over sequentially until the end of the list, or a printer 24143object is returned. 24144 24145For various reasons a pretty-printer may not work. 24146For example, the underlying data structure may have changed and 24147the pretty-printer is out of date. 24148 24149The consequences of a broken pretty-printer are severe enough that 24150@value{GDBN} provides support for enabling and disabling individual 24151printers. For example, if @code{print frame-arguments} is on, 24152a backtrace can become highly illegible if any argument is printed 24153with a broken printer. 24154 24155Pretty-printers are enabled and disabled by attaching an @code{enabled} 24156attribute to the registered function or callable object. If this attribute 24157is present and its value is @code{False}, the printer is disabled, otherwise 24158the printer is enabled. 24159 24160@node Writing a Pretty-Printer 24161@subsubsection Writing a Pretty-Printer 24162@cindex writing a pretty-printer 24163 24164A pretty-printer consists of two parts: a lookup function to detect 24165if the type is supported, and the printer itself. 24166 24167Here is an example showing how a @code{std::string} printer might be 24168written. @xref{Pretty Printing API}, for details on the API this class 24169must provide. 24170 24171@smallexample 24172class StdStringPrinter(object): 24173 "Print a std::string" 24174 24175 def __init__(self, val): 24176 self.val = val 24177 24178 def to_string(self): 24179 return self.val['_M_dataplus']['_M_p'] 24180 24181 def display_hint(self): 24182 return 'string' 24183@end smallexample 24184 24185And here is an example showing how a lookup function for the printer 24186example above might be written. 24187 24188@smallexample 24189def str_lookup_function(val): 24190 lookup_tag = val.type.tag 24191 if lookup_tag == None: 24192 return None 24193 regex = re.compile("^std::basic_string<char,.*>$") 24194 if regex.match(lookup_tag): 24195 return StdStringPrinter(val) 24196 return None 24197@end smallexample 24198 24199The example lookup function extracts the value's type, and attempts to 24200match it to a type that it can pretty-print. If it is a type the 24201printer can pretty-print, it will return a printer object. If not, it 24202returns @code{None}. 24203 24204We recommend that you put your core pretty-printers into a Python 24205package. If your pretty-printers are for use with a library, we 24206further recommend embedding a version number into the package name. 24207This practice will enable @value{GDBN} to load multiple versions of 24208your pretty-printers at the same time, because they will have 24209different names. 24210 24211You should write auto-loaded code (@pxref{Python Auto-loading}) such that it 24212can be evaluated multiple times without changing its meaning. An 24213ideal auto-load file will consist solely of @code{import}s of your 24214printer modules, followed by a call to a register pretty-printers with 24215the current objfile. 24216 24217Taken as a whole, this approach will scale nicely to multiple 24218inferiors, each potentially using a different library version. 24219Embedding a version number in the Python package name will ensure that 24220@value{GDBN} is able to load both sets of printers simultaneously. 24221Then, because the search for pretty-printers is done by objfile, and 24222because your auto-loaded code took care to register your library's 24223printers with a specific objfile, @value{GDBN} will find the correct 24224printers for the specific version of the library used by each 24225inferior. 24226 24227To continue the @code{std::string} example (@pxref{Pretty Printing API}), 24228this code might appear in @code{gdb.libstdcxx.v6}: 24229 24230@smallexample 24231def register_printers(objfile): 24232 objfile.pretty_printers.append(str_lookup_function) 24233@end smallexample 24234 24235@noindent 24236And then the corresponding contents of the auto-load file would be: 24237 24238@smallexample 24239import gdb.libstdcxx.v6 24240gdb.libstdcxx.v6.register_printers(gdb.current_objfile()) 24241@end smallexample 24242 24243The previous example illustrates a basic pretty-printer. 24244There are a few things that can be improved on. 24245The printer doesn't have a name, making it hard to identify in a 24246list of installed printers. The lookup function has a name, but 24247lookup functions can have arbitrary, even identical, names. 24248 24249Second, the printer only handles one type, whereas a library typically has 24250several types. One could install a lookup function for each desired type 24251in the library, but one could also have a single lookup function recognize 24252several types. The latter is the conventional way this is handled. 24253If a pretty-printer can handle multiple data types, then its 24254@dfn{subprinters} are the printers for the individual data types. 24255 24256The @code{gdb.printing} module provides a formal way of solving these 24257problems (@pxref{gdb.printing}). 24258Here is another example that handles multiple types. 24259 24260These are the types we are going to pretty-print: 24261 24262@smallexample 24263struct foo @{ int a, b; @}; 24264struct bar @{ struct foo x, y; @}; 24265@end smallexample 24266 24267Here are the printers: 24268 24269@smallexample 24270class fooPrinter: 24271 """Print a foo object.""" 24272 24273 def __init__(self, val): 24274 self.val = val 24275 24276 def to_string(self): 24277 return ("a=<" + str(self.val["a"]) + 24278 "> b=<" + str(self.val["b"]) + ">") 24279 24280class barPrinter: 24281 """Print a bar object.""" 24282 24283 def __init__(self, val): 24284 self.val = val 24285 24286 def to_string(self): 24287 return ("x=<" + str(self.val["x"]) + 24288 "> y=<" + str(self.val["y"]) + ">") 24289@end smallexample 24290 24291This example doesn't need a lookup function, that is handled by the 24292@code{gdb.printing} module. Instead a function is provided to build up 24293the object that handles the lookup. 24294 24295@smallexample 24296import gdb.printing 24297 24298def build_pretty_printer(): 24299 pp = gdb.printing.RegexpCollectionPrettyPrinter( 24300 "my_library") 24301 pp.add_printer('foo', '^foo$', fooPrinter) 24302 pp.add_printer('bar', '^bar$', barPrinter) 24303 return pp 24304@end smallexample 24305 24306And here is the autoload support: 24307 24308@smallexample 24309import gdb.printing 24310import my_library 24311gdb.printing.register_pretty_printer( 24312 gdb.current_objfile(), 24313 my_library.build_pretty_printer()) 24314@end smallexample 24315 24316Finally, when this printer is loaded into @value{GDBN}, here is the 24317corresponding output of @samp{info pretty-printer}: 24318 24319@smallexample 24320(gdb) info pretty-printer 24321my_library.so: 24322 my_library 24323 foo 24324 bar 24325@end smallexample 24326 24327@node Type Printing API 24328@subsubsection Type Printing API 24329@cindex type printing API for Python 24330 24331@value{GDBN} provides a way for Python code to customize type display. 24332This is mainly useful for substituting canonical typedef names for 24333types. 24334 24335@cindex type printer 24336A @dfn{type printer} is just a Python object conforming to a certain 24337protocol. A simple base class implementing the protocol is provided; 24338see @ref{gdb.types}. A type printer must supply at least: 24339 24340@defivar type_printer enabled 24341A boolean which is True if the printer is enabled, and False 24342otherwise. This is manipulated by the @code{enable type-printer} 24343and @code{disable type-printer} commands. 24344@end defivar 24345 24346@defivar type_printer name 24347The name of the type printer. This must be a string. This is used by 24348the @code{enable type-printer} and @code{disable type-printer} 24349commands. 24350@end defivar 24351 24352@defmethod type_printer instantiate (self) 24353This is called by @value{GDBN} at the start of type-printing. It is 24354only called if the type printer is enabled. This method must return a 24355new object that supplies a @code{recognize} method, as described below. 24356@end defmethod 24357 24358 24359When displaying a type, say via the @code{ptype} command, @value{GDBN} 24360will compute a list of type recognizers. This is done by iterating 24361first over the per-objfile type printers (@pxref{Objfiles In Python}), 24362followed by the per-progspace type printers (@pxref{Progspaces In 24363Python}), and finally the global type printers. 24364 24365@value{GDBN} will call the @code{instantiate} method of each enabled 24366type printer. If this method returns @code{None}, then the result is 24367ignored; otherwise, it is appended to the list of recognizers. 24368 24369Then, when @value{GDBN} is going to display a type name, it iterates 24370over the list of recognizers. For each one, it calls the recognition 24371function, stopping if the function returns a non-@code{None} value. 24372The recognition function is defined as: 24373 24374@defmethod type_recognizer recognize (self, type) 24375If @var{type} is not recognized, return @code{None}. Otherwise, 24376return a string which is to be printed as the name of @var{type}. 24377@var{type} will be an instance of @code{gdb.Type} (@pxref{Types In 24378Python}). 24379@end defmethod 24380 24381@value{GDBN} uses this two-pass approach so that type printers can 24382efficiently cache information without holding on to it too long. For 24383example, it can be convenient to look up type information in a type 24384printer and hold it for a recognizer's lifetime; if a single pass were 24385done then type printers would have to make use of the event system in 24386order to avoid holding information that could become stale as the 24387inferior changed. 24388 24389@node Inferiors In Python 24390@subsubsection Inferiors In Python 24391@cindex inferiors in Python 24392 24393@findex gdb.Inferior 24394Programs which are being run under @value{GDBN} are called inferiors 24395(@pxref{Inferiors and Programs}). Python scripts can access 24396information about and manipulate inferiors controlled by @value{GDBN} 24397via objects of the @code{gdb.Inferior} class. 24398 24399The following inferior-related functions are available in the @code{gdb} 24400module: 24401 24402@defun gdb.inferiors () 24403Return a tuple containing all inferior objects. 24404@end defun 24405 24406@defun gdb.selected_inferior () 24407Return an object representing the current inferior. 24408@end defun 24409 24410A @code{gdb.Inferior} object has the following attributes: 24411 24412@defvar Inferior.num 24413ID of inferior, as assigned by GDB. 24414@end defvar 24415 24416@defvar Inferior.pid 24417Process ID of the inferior, as assigned by the underlying operating 24418system. 24419@end defvar 24420 24421@defvar Inferior.was_attached 24422Boolean signaling whether the inferior was created using `attach', or 24423started by @value{GDBN} itself. 24424@end defvar 24425 24426A @code{gdb.Inferior} object has the following methods: 24427 24428@defun Inferior.is_valid () 24429Returns @code{True} if the @code{gdb.Inferior} object is valid, 24430@code{False} if not. A @code{gdb.Inferior} object will become invalid 24431if the inferior no longer exists within @value{GDBN}. All other 24432@code{gdb.Inferior} methods will throw an exception if it is invalid 24433at the time the method is called. 24434@end defun 24435 24436@defun Inferior.threads () 24437This method returns a tuple holding all the threads which are valid 24438when it is called. If there are no valid threads, the method will 24439return an empty tuple. 24440@end defun 24441 24442@findex Inferior.read_memory 24443@defun Inferior.read_memory (address, length) 24444Read @var{length} bytes of memory from the inferior, starting at 24445@var{address}. Returns a buffer object, which behaves much like an array 24446or a string. It can be modified and given to the 24447@code{Inferior.write_memory} function. In @code{Python} 3, the return 24448value is a @code{memoryview} object. 24449@end defun 24450 24451@findex Inferior.write_memory 24452@defun Inferior.write_memory (address, buffer @r{[}, length@r{]}) 24453Write the contents of @var{buffer} to the inferior, starting at 24454@var{address}. The @var{buffer} parameter must be a Python object 24455which supports the buffer protocol, i.e., a string, an array or the 24456object returned from @code{Inferior.read_memory}. If given, @var{length} 24457determines the number of bytes from @var{buffer} to be written. 24458@end defun 24459 24460@findex gdb.search_memory 24461@defun Inferior.search_memory (address, length, pattern) 24462Search a region of the inferior memory starting at @var{address} with 24463the given @var{length} using the search pattern supplied in 24464@var{pattern}. The @var{pattern} parameter must be a Python object 24465which supports the buffer protocol, i.e., a string, an array or the 24466object returned from @code{gdb.read_memory}. Returns a Python @code{Long} 24467containing the address where the pattern was found, or @code{None} if 24468the pattern could not be found. 24469@end defun 24470 24471@node Events In Python 24472@subsubsection Events In Python 24473@cindex inferior events in Python 24474 24475@value{GDBN} provides a general event facility so that Python code can be 24476notified of various state changes, particularly changes that occur in 24477the inferior. 24478 24479An @dfn{event} is just an object that describes some state change. The 24480type of the object and its attributes will vary depending on the details 24481of the change. All the existing events are described below. 24482 24483In order to be notified of an event, you must register an event handler 24484with an @dfn{event registry}. An event registry is an object in the 24485@code{gdb.events} module which dispatches particular events. A registry 24486provides methods to register and unregister event handlers: 24487 24488@defun EventRegistry.connect (object) 24489Add the given callable @var{object} to the registry. This object will be 24490called when an event corresponding to this registry occurs. 24491@end defun 24492 24493@defun EventRegistry.disconnect (object) 24494Remove the given @var{object} from the registry. Once removed, the object 24495will no longer receive notifications of events. 24496@end defun 24497 24498Here is an example: 24499 24500@smallexample 24501def exit_handler (event): 24502 print "event type: exit" 24503 print "exit code: %d" % (event.exit_code) 24504 24505gdb.events.exited.connect (exit_handler) 24506@end smallexample 24507 24508In the above example we connect our handler @code{exit_handler} to the 24509registry @code{events.exited}. Once connected, @code{exit_handler} gets 24510called when the inferior exits. The argument @dfn{event} in this example is 24511of type @code{gdb.ExitedEvent}. As you can see in the example the 24512@code{ExitedEvent} object has an attribute which indicates the exit code of 24513the inferior. 24514 24515The following is a listing of the event registries that are available and 24516details of the events they emit: 24517 24518@table @code 24519 24520@item events.cont 24521Emits @code{gdb.ThreadEvent}. 24522 24523Some events can be thread specific when @value{GDBN} is running in non-stop 24524mode. When represented in Python, these events all extend 24525@code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead, 24526events which are emitted by this or other modules might extend this event. 24527Examples of these events are @code{gdb.BreakpointEvent} and 24528@code{gdb.ContinueEvent}. 24529 24530@defvar ThreadEvent.inferior_thread 24531In non-stop mode this attribute will be set to the specific thread which was 24532involved in the emitted event. Otherwise, it will be set to @code{None}. 24533@end defvar 24534 24535Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}. 24536 24537This event indicates that the inferior has been continued after a stop. For 24538inherited attribute refer to @code{gdb.ThreadEvent} above. 24539 24540@item events.exited 24541Emits @code{events.ExitedEvent} which indicates that the inferior has exited. 24542@code{events.ExitedEvent} has two attributes: 24543@defvar ExitedEvent.exit_code 24544An integer representing the exit code, if available, which the inferior 24545has returned. (The exit code could be unavailable if, for example, 24546@value{GDBN} detaches from the inferior.) If the exit code is unavailable, 24547the attribute does not exist. 24548@end defvar 24549@defvar ExitedEvent inferior 24550A reference to the inferior which triggered the @code{exited} event. 24551@end defvar 24552 24553@item events.stop 24554Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}. 24555 24556Indicates that the inferior has stopped. All events emitted by this registry 24557extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent} 24558will indicate the stopped thread when @value{GDBN} is running in non-stop 24559mode. Refer to @code{gdb.ThreadEvent} above for more details. 24560 24561Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}. 24562 24563This event indicates that the inferior or one of its threads has received as 24564signal. @code{gdb.SignalEvent} has the following attributes: 24565 24566@defvar SignalEvent.stop_signal 24567A string representing the signal received by the inferior. A list of possible 24568signal values can be obtained by running the command @code{info signals} in 24569the @value{GDBN} command prompt. 24570@end defvar 24571 24572Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}. 24573 24574@code{gdb.BreakpointEvent} event indicates that one or more breakpoints have 24575been hit, and has the following attributes: 24576 24577@defvar BreakpointEvent.breakpoints 24578A sequence containing references to all the breakpoints (type 24579@code{gdb.Breakpoint}) that were hit. 24580@xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object. 24581@end defvar 24582@defvar BreakpointEvent.breakpoint 24583A reference to the first breakpoint that was hit. 24584This function is maintained for backward compatibility and is now deprecated 24585in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute. 24586@end defvar 24587 24588@item events.new_objfile 24589Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has 24590been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute: 24591 24592@defvar NewObjFileEvent.new_objfile 24593A reference to the object file (@code{gdb.Objfile}) which has been loaded. 24594@xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object. 24595@end defvar 24596 24597@end table 24598 24599@node Threads In Python 24600@subsubsection Threads In Python 24601@cindex threads in python 24602 24603@findex gdb.InferiorThread 24604Python scripts can access information about, and manipulate inferior threads 24605controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class. 24606 24607The following thread-related functions are available in the @code{gdb} 24608module: 24609 24610@findex gdb.selected_thread 24611@defun gdb.selected_thread () 24612This function returns the thread object for the selected thread. If there 24613is no selected thread, this will return @code{None}. 24614@end defun 24615 24616A @code{gdb.InferiorThread} object has the following attributes: 24617 24618@defvar InferiorThread.name 24619The name of the thread. If the user specified a name using 24620@code{thread name}, then this returns that name. Otherwise, if an 24621OS-supplied name is available, then it is returned. Otherwise, this 24622returns @code{None}. 24623 24624This attribute can be assigned to. The new value must be a string 24625object, which sets the new name, or @code{None}, which removes any 24626user-specified thread name. 24627@end defvar 24628 24629@defvar InferiorThread.num 24630ID of the thread, as assigned by GDB. 24631@end defvar 24632 24633@defvar InferiorThread.ptid 24634ID of the thread, as assigned by the operating system. This attribute is a 24635tuple containing three integers. The first is the Process ID (PID); the second 24636is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID). 24637Either the LWPID or TID may be 0, which indicates that the operating system 24638does not use that identifier. 24639@end defvar 24640 24641A @code{gdb.InferiorThread} object has the following methods: 24642 24643@defun InferiorThread.is_valid () 24644Returns @code{True} if the @code{gdb.InferiorThread} object is valid, 24645@code{False} if not. A @code{gdb.InferiorThread} object will become 24646invalid if the thread exits, or the inferior that the thread belongs 24647is deleted. All other @code{gdb.InferiorThread} methods will throw an 24648exception if it is invalid at the time the method is called. 24649@end defun 24650 24651@defun InferiorThread.switch () 24652This changes @value{GDBN}'s currently selected thread to the one represented 24653by this object. 24654@end defun 24655 24656@defun InferiorThread.is_stopped () 24657Return a Boolean indicating whether the thread is stopped. 24658@end defun 24659 24660@defun InferiorThread.is_running () 24661Return a Boolean indicating whether the thread is running. 24662@end defun 24663 24664@defun InferiorThread.is_exited () 24665Return a Boolean indicating whether the thread is exited. 24666@end defun 24667 24668@node Commands In Python 24669@subsubsection Commands In Python 24670 24671@cindex commands in python 24672@cindex python commands 24673You can implement new @value{GDBN} CLI commands in Python. A CLI 24674command is implemented using an instance of the @code{gdb.Command} 24675class, most commonly using a subclass. 24676 24677@defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]}) 24678The object initializer for @code{Command} registers the new command 24679with @value{GDBN}. This initializer is normally invoked from the 24680subclass' own @code{__init__} method. 24681 24682@var{name} is the name of the command. If @var{name} consists of 24683multiple words, then the initial words are looked for as prefix 24684commands. In this case, if one of the prefix commands does not exist, 24685an exception is raised. 24686 24687There is no support for multi-line commands. 24688 24689@var{command_class} should be one of the @samp{COMMAND_} constants 24690defined below. This argument tells @value{GDBN} how to categorize the 24691new command in the help system. 24692 24693@var{completer_class} is an optional argument. If given, it should be 24694one of the @samp{COMPLETE_} constants defined below. This argument 24695tells @value{GDBN} how to perform completion for this command. If not 24696given, @value{GDBN} will attempt to complete using the object's 24697@code{complete} method (see below); if no such method is found, an 24698error will occur when completion is attempted. 24699 24700@var{prefix} is an optional argument. If @code{True}, then the new 24701command is a prefix command; sub-commands of this command may be 24702registered. 24703 24704The help text for the new command is taken from the Python 24705documentation string for the command's class, if there is one. If no 24706documentation string is provided, the default value ``This command is 24707not documented.'' is used. 24708@end defun 24709 24710@cindex don't repeat Python command 24711@defun Command.dont_repeat () 24712By default, a @value{GDBN} command is repeated when the user enters a 24713blank line at the command prompt. A command can suppress this 24714behavior by invoking the @code{dont_repeat} method. This is similar 24715to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}. 24716@end defun 24717 24718@defun Command.invoke (argument, from_tty) 24719This method is called by @value{GDBN} when this command is invoked. 24720 24721@var{argument} is a string. It is the argument to the command, after 24722leading and trailing whitespace has been stripped. 24723 24724@var{from_tty} is a boolean argument. When true, this means that the 24725command was entered by the user at the terminal; when false it means 24726that the command came from elsewhere. 24727 24728If this method throws an exception, it is turned into a @value{GDBN} 24729@code{error} call. Otherwise, the return value is ignored. 24730 24731@findex gdb.string_to_argv 24732To break @var{argument} up into an argv-like string use 24733@code{gdb.string_to_argv}. This function behaves identically to 24734@value{GDBN}'s internal argument lexer @code{buildargv}. 24735It is recommended to use this for consistency. 24736Arguments are separated by spaces and may be quoted. 24737Example: 24738 24739@smallexample 24740print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"") 24741['1', '2 "3', '4 "5', "6 '7"] 24742@end smallexample 24743 24744@end defun 24745 24746@cindex completion of Python commands 24747@defun Command.complete (text, word) 24748This method is called by @value{GDBN} when the user attempts 24749completion on this command. All forms of completion are handled by 24750this method, that is, the @key{TAB} and @key{M-?} key bindings 24751(@pxref{Completion}), and the @code{complete} command (@pxref{Help, 24752complete}). 24753 24754The arguments @var{text} and @var{word} are both strings. @var{text} 24755holds the complete command line up to the cursor's location. 24756@var{word} holds the last word of the command line; this is computed 24757using a word-breaking heuristic. 24758 24759The @code{complete} method can return several values: 24760@itemize @bullet 24761@item 24762If the return value is a sequence, the contents of the sequence are 24763used as the completions. It is up to @code{complete} to ensure that the 24764contents actually do complete the word. A zero-length sequence is 24765allowed, it means that there were no completions available. Only 24766string elements of the sequence are used; other elements in the 24767sequence are ignored. 24768 24769@item 24770If the return value is one of the @samp{COMPLETE_} constants defined 24771below, then the corresponding @value{GDBN}-internal completion 24772function is invoked, and its result is used. 24773 24774@item 24775All other results are treated as though there were no available 24776completions. 24777@end itemize 24778@end defun 24779 24780When a new command is registered, it must be declared as a member of 24781some general class of commands. This is used to classify top-level 24782commands in the on-line help system; note that prefix commands are not 24783listed under their own category but rather that of their top-level 24784command. The available classifications are represented by constants 24785defined in the @code{gdb} module: 24786 24787@table @code 24788@findex COMMAND_NONE 24789@findex gdb.COMMAND_NONE 24790@item gdb.COMMAND_NONE 24791The command does not belong to any particular class. A command in 24792this category will not be displayed in any of the help categories. 24793 24794@findex COMMAND_RUNNING 24795@findex gdb.COMMAND_RUNNING 24796@item gdb.COMMAND_RUNNING 24797The command is related to running the inferior. For example, 24798@code{start}, @code{step}, and @code{continue} are in this category. 24799Type @kbd{help running} at the @value{GDBN} prompt to see a list of 24800commands in this category. 24801 24802@findex COMMAND_DATA 24803@findex gdb.COMMAND_DATA 24804@item gdb.COMMAND_DATA 24805The command is related to data or variables. For example, 24806@code{call}, @code{find}, and @code{print} are in this category. Type 24807@kbd{help data} at the @value{GDBN} prompt to see a list of commands 24808in this category. 24809 24810@findex COMMAND_STACK 24811@findex gdb.COMMAND_STACK 24812@item gdb.COMMAND_STACK 24813The command has to do with manipulation of the stack. For example, 24814@code{backtrace}, @code{frame}, and @code{return} are in this 24815category. Type @kbd{help stack} at the @value{GDBN} prompt to see a 24816list of commands in this category. 24817 24818@findex COMMAND_FILES 24819@findex gdb.COMMAND_FILES 24820@item gdb.COMMAND_FILES 24821This class is used for file-related commands. For example, 24822@code{file}, @code{list} and @code{section} are in this category. 24823Type @kbd{help files} at the @value{GDBN} prompt to see a list of 24824commands in this category. 24825 24826@findex COMMAND_SUPPORT 24827@findex gdb.COMMAND_SUPPORT 24828@item gdb.COMMAND_SUPPORT 24829This should be used for ``support facilities'', generally meaning 24830things that are useful to the user when interacting with @value{GDBN}, 24831but not related to the state of the inferior. For example, 24832@code{help}, @code{make}, and @code{shell} are in this category. Type 24833@kbd{help support} at the @value{GDBN} prompt to see a list of 24834commands in this category. 24835 24836@findex COMMAND_STATUS 24837@findex gdb.COMMAND_STATUS 24838@item gdb.COMMAND_STATUS 24839The command is an @samp{info}-related command, that is, related to the 24840state of @value{GDBN} itself. For example, @code{info}, @code{macro}, 24841and @code{show} are in this category. Type @kbd{help status} at the 24842@value{GDBN} prompt to see a list of commands in this category. 24843 24844@findex COMMAND_BREAKPOINTS 24845@findex gdb.COMMAND_BREAKPOINTS 24846@item gdb.COMMAND_BREAKPOINTS 24847The command has to do with breakpoints. For example, @code{break}, 24848@code{clear}, and @code{delete} are in this category. Type @kbd{help 24849breakpoints} at the @value{GDBN} prompt to see a list of commands in 24850this category. 24851 24852@findex COMMAND_TRACEPOINTS 24853@findex gdb.COMMAND_TRACEPOINTS 24854@item gdb.COMMAND_TRACEPOINTS 24855The command has to do with tracepoints. For example, @code{trace}, 24856@code{actions}, and @code{tfind} are in this category. Type 24857@kbd{help tracepoints} at the @value{GDBN} prompt to see a list of 24858commands in this category. 24859 24860@findex COMMAND_USER 24861@findex gdb.COMMAND_USER 24862@item gdb.COMMAND_USER 24863The command is a general purpose command for the user, and typically 24864does not fit in one of the other categories. 24865Type @kbd{help user-defined} at the @value{GDBN} prompt to see 24866a list of commands in this category, as well as the list of gdb macros 24867(@pxref{Sequences}). 24868 24869@findex COMMAND_OBSCURE 24870@findex gdb.COMMAND_OBSCURE 24871@item gdb.COMMAND_OBSCURE 24872The command is only used in unusual circumstances, or is not of 24873general interest to users. For example, @code{checkpoint}, 24874@code{fork}, and @code{stop} are in this category. Type @kbd{help 24875obscure} at the @value{GDBN} prompt to see a list of commands in this 24876category. 24877 24878@findex COMMAND_MAINTENANCE 24879@findex gdb.COMMAND_MAINTENANCE 24880@item gdb.COMMAND_MAINTENANCE 24881The command is only useful to @value{GDBN} maintainers. The 24882@code{maintenance} and @code{flushregs} commands are in this category. 24883Type @kbd{help internals} at the @value{GDBN} prompt to see a list of 24884commands in this category. 24885@end table 24886 24887A new command can use a predefined completion function, either by 24888specifying it via an argument at initialization, or by returning it 24889from the @code{complete} method. These predefined completion 24890constants are all defined in the @code{gdb} module: 24891 24892@table @code 24893@findex COMPLETE_NONE 24894@findex gdb.COMPLETE_NONE 24895@item gdb.COMPLETE_NONE 24896This constant means that no completion should be done. 24897 24898@findex COMPLETE_FILENAME 24899@findex gdb.COMPLETE_FILENAME 24900@item gdb.COMPLETE_FILENAME 24901This constant means that filename completion should be performed. 24902 24903@findex COMPLETE_LOCATION 24904@findex gdb.COMPLETE_LOCATION 24905@item gdb.COMPLETE_LOCATION 24906This constant means that location completion should be done. 24907@xref{Specify Location}. 24908 24909@findex COMPLETE_COMMAND 24910@findex gdb.COMPLETE_COMMAND 24911@item gdb.COMPLETE_COMMAND 24912This constant means that completion should examine @value{GDBN} 24913command names. 24914 24915@findex COMPLETE_SYMBOL 24916@findex gdb.COMPLETE_SYMBOL 24917@item gdb.COMPLETE_SYMBOL 24918This constant means that completion should be done using symbol names 24919as the source. 24920@end table 24921 24922The following code snippet shows how a trivial CLI command can be 24923implemented in Python: 24924 24925@smallexample 24926class HelloWorld (gdb.Command): 24927 """Greet the whole world.""" 24928 24929 def __init__ (self): 24930 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER) 24931 24932 def invoke (self, arg, from_tty): 24933 print "Hello, World!" 24934 24935HelloWorld () 24936@end smallexample 24937 24938The last line instantiates the class, and is necessary to trigger the 24939registration of the command with @value{GDBN}. Depending on how the 24940Python code is read into @value{GDBN}, you may need to import the 24941@code{gdb} module explicitly. 24942 24943@node Parameters In Python 24944@subsubsection Parameters In Python 24945 24946@cindex parameters in python 24947@cindex python parameters 24948@tindex gdb.Parameter 24949@tindex Parameter 24950You can implement new @value{GDBN} parameters using Python. A new 24951parameter is implemented as an instance of the @code{gdb.Parameter} 24952class. 24953 24954Parameters are exposed to the user via the @code{set} and 24955@code{show} commands. @xref{Help}. 24956 24957There are many parameters that already exist and can be set in 24958@value{GDBN}. Two examples are: @code{set follow fork} and 24959@code{set charset}. Setting these parameters influences certain 24960behavior in @value{GDBN}. Similarly, you can define parameters that 24961can be used to influence behavior in custom Python scripts and commands. 24962 24963@defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]}) 24964The object initializer for @code{Parameter} registers the new 24965parameter with @value{GDBN}. This initializer is normally invoked 24966from the subclass' own @code{__init__} method. 24967 24968@var{name} is the name of the new parameter. If @var{name} consists 24969of multiple words, then the initial words are looked for as prefix 24970parameters. An example of this can be illustrated with the 24971@code{set print} set of parameters. If @var{name} is 24972@code{print foo}, then @code{print} will be searched as the prefix 24973parameter. In this case the parameter can subsequently be accessed in 24974@value{GDBN} as @code{set print foo}. 24975 24976If @var{name} consists of multiple words, and no prefix parameter group 24977can be found, an exception is raised. 24978 24979@var{command-class} should be one of the @samp{COMMAND_} constants 24980(@pxref{Commands In Python}). This argument tells @value{GDBN} how to 24981categorize the new parameter in the help system. 24982 24983@var{parameter-class} should be one of the @samp{PARAM_} constants 24984defined below. This argument tells @value{GDBN} the type of the new 24985parameter; this information is used for input validation and 24986completion. 24987 24988If @var{parameter-class} is @code{PARAM_ENUM}, then 24989@var{enum-sequence} must be a sequence of strings. These strings 24990represent the possible values for the parameter. 24991 24992If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence 24993of a fourth argument will cause an exception to be thrown. 24994 24995The help text for the new parameter is taken from the Python 24996documentation string for the parameter's class, if there is one. If 24997there is no documentation string, a default value is used. 24998@end defun 24999 25000@defvar Parameter.set_doc 25001If this attribute exists, and is a string, then its value is used as 25002the help text for this parameter's @code{set} command. The value is 25003examined when @code{Parameter.__init__} is invoked; subsequent changes 25004have no effect. 25005@end defvar 25006 25007@defvar Parameter.show_doc 25008If this attribute exists, and is a string, then its value is used as 25009the help text for this parameter's @code{show} command. The value is 25010examined when @code{Parameter.__init__} is invoked; subsequent changes 25011have no effect. 25012@end defvar 25013 25014@defvar Parameter.value 25015The @code{value} attribute holds the underlying value of the 25016parameter. It can be read and assigned to just as any other 25017attribute. @value{GDBN} does validation when assignments are made. 25018@end defvar 25019 25020There are two methods that should be implemented in any 25021@code{Parameter} class. These are: 25022 25023@defun Parameter.get_set_string (self) 25024@value{GDBN} will call this method when a @var{parameter}'s value has 25025been changed via the @code{set} API (for example, @kbd{set foo off}). 25026The @code{value} attribute has already been populated with the new 25027value and may be used in output. This method must return a string. 25028@end defun 25029 25030@defun Parameter.get_show_string (self, svalue) 25031@value{GDBN} will call this method when a @var{parameter}'s 25032@code{show} API has been invoked (for example, @kbd{show foo}). The 25033argument @code{svalue} receives the string representation of the 25034current value. This method must return a string. 25035@end defun 25036 25037When a new parameter is defined, its type must be specified. The 25038available types are represented by constants defined in the @code{gdb} 25039module: 25040 25041@table @code 25042@findex PARAM_BOOLEAN 25043@findex gdb.PARAM_BOOLEAN 25044@item gdb.PARAM_BOOLEAN 25045The value is a plain boolean. The Python boolean values, @code{True} 25046and @code{False} are the only valid values. 25047 25048@findex PARAM_AUTO_BOOLEAN 25049@findex gdb.PARAM_AUTO_BOOLEAN 25050@item gdb.PARAM_AUTO_BOOLEAN 25051The value has three possible states: true, false, and @samp{auto}. In 25052Python, true and false are represented using boolean constants, and 25053@samp{auto} is represented using @code{None}. 25054 25055@findex PARAM_UINTEGER 25056@findex gdb.PARAM_UINTEGER 25057@item gdb.PARAM_UINTEGER 25058The value is an unsigned integer. The value of 0 should be 25059interpreted to mean ``unlimited''. 25060 25061@findex PARAM_INTEGER 25062@findex gdb.PARAM_INTEGER 25063@item gdb.PARAM_INTEGER 25064The value is a signed integer. The value of 0 should be interpreted 25065to mean ``unlimited''. 25066 25067@findex PARAM_STRING 25068@findex gdb.PARAM_STRING 25069@item gdb.PARAM_STRING 25070The value is a string. When the user modifies the string, any escape 25071sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are 25072translated into corresponding characters and encoded into the current 25073host charset. 25074 25075@findex PARAM_STRING_NOESCAPE 25076@findex gdb.PARAM_STRING_NOESCAPE 25077@item gdb.PARAM_STRING_NOESCAPE 25078The value is a string. When the user modifies the string, escapes are 25079passed through untranslated. 25080 25081@findex PARAM_OPTIONAL_FILENAME 25082@findex gdb.PARAM_OPTIONAL_FILENAME 25083@item gdb.PARAM_OPTIONAL_FILENAME 25084The value is a either a filename (a string), or @code{None}. 25085 25086@findex PARAM_FILENAME 25087@findex gdb.PARAM_FILENAME 25088@item gdb.PARAM_FILENAME 25089The value is a filename. This is just like 25090@code{PARAM_STRING_NOESCAPE}, but uses file names for completion. 25091 25092@findex PARAM_ZINTEGER 25093@findex gdb.PARAM_ZINTEGER 25094@item gdb.PARAM_ZINTEGER 25095The value is an integer. This is like @code{PARAM_INTEGER}, except 0 25096is interpreted as itself. 25097 25098@findex PARAM_ENUM 25099@findex gdb.PARAM_ENUM 25100@item gdb.PARAM_ENUM 25101The value is a string, which must be one of a collection string 25102constants provided when the parameter is created. 25103@end table 25104 25105@node Functions In Python 25106@subsubsection Writing new convenience functions 25107 25108@cindex writing convenience functions 25109@cindex convenience functions in python 25110@cindex python convenience functions 25111@tindex gdb.Function 25112@tindex Function 25113You can implement new convenience functions (@pxref{Convenience Vars}) 25114in Python. A convenience function is an instance of a subclass of the 25115class @code{gdb.Function}. 25116 25117@defun Function.__init__ (name) 25118The initializer for @code{Function} registers the new function with 25119@value{GDBN}. The argument @var{name} is the name of the function, 25120a string. The function will be visible to the user as a convenience 25121variable of type @code{internal function}, whose name is the same as 25122the given @var{name}. 25123 25124The documentation for the new function is taken from the documentation 25125string for the new class. 25126@end defun 25127 25128@defun Function.invoke (@var{*args}) 25129When a convenience function is evaluated, its arguments are converted 25130to instances of @code{gdb.Value}, and then the function's 25131@code{invoke} method is called. Note that @value{GDBN} does not 25132predetermine the arity of convenience functions. Instead, all 25133available arguments are passed to @code{invoke}, following the 25134standard Python calling convention. In particular, a convenience 25135function can have default values for parameters without ill effect. 25136 25137The return value of this method is used as its value in the enclosing 25138expression. If an ordinary Python value is returned, it is converted 25139to a @code{gdb.Value} following the usual rules. 25140@end defun 25141 25142The following code snippet shows how a trivial convenience function can 25143be implemented in Python: 25144 25145@smallexample 25146class Greet (gdb.Function): 25147 """Return string to greet someone. 25148Takes a name as argument.""" 25149 25150 def __init__ (self): 25151 super (Greet, self).__init__ ("greet") 25152 25153 def invoke (self, name): 25154 return "Hello, %s!" % name.string () 25155 25156Greet () 25157@end smallexample 25158 25159The last line instantiates the class, and is necessary to trigger the 25160registration of the function with @value{GDBN}. Depending on how the 25161Python code is read into @value{GDBN}, you may need to import the 25162@code{gdb} module explicitly. 25163 25164Now you can use the function in an expression: 25165 25166@smallexample 25167(gdb) print $greet("Bob") 25168$1 = "Hello, Bob!" 25169@end smallexample 25170 25171@node Progspaces In Python 25172@subsubsection Program Spaces In Python 25173 25174@cindex progspaces in python 25175@tindex gdb.Progspace 25176@tindex Progspace 25177A program space, or @dfn{progspace}, represents a symbolic view 25178of an address space. 25179It consists of all of the objfiles of the program. 25180@xref{Objfiles In Python}. 25181@xref{Inferiors and Programs, program spaces}, for more details 25182about program spaces. 25183 25184The following progspace-related functions are available in the 25185@code{gdb} module: 25186 25187@findex gdb.current_progspace 25188@defun gdb.current_progspace () 25189This function returns the program space of the currently selected inferior. 25190@xref{Inferiors and Programs}. 25191@end defun 25192 25193@findex gdb.progspaces 25194@defun gdb.progspaces () 25195Return a sequence of all the progspaces currently known to @value{GDBN}. 25196@end defun 25197 25198Each progspace is represented by an instance of the @code{gdb.Progspace} 25199class. 25200 25201@defvar Progspace.filename 25202The file name of the progspace as a string. 25203@end defvar 25204 25205@defvar Progspace.pretty_printers 25206The @code{pretty_printers} attribute is a list of functions. It is 25207used to look up pretty-printers. A @code{Value} is passed to each 25208function in order; if the function returns @code{None}, then the 25209search continues. Otherwise, the return value should be an object 25210which is used to format the value. @xref{Pretty Printing API}, for more 25211information. 25212@end defvar 25213 25214@defvar Progspace.type_printers 25215The @code{type_printers} attribute is a list of type printer objects. 25216@xref{Type Printing API}, for more information. 25217@end defvar 25218 25219@node Objfiles In Python 25220@subsubsection Objfiles In Python 25221 25222@cindex objfiles in python 25223@tindex gdb.Objfile 25224@tindex Objfile 25225@value{GDBN} loads symbols for an inferior from various 25226symbol-containing files (@pxref{Files}). These include the primary 25227executable file, any shared libraries used by the inferior, and any 25228separate debug info files (@pxref{Separate Debug Files}). 25229@value{GDBN} calls these symbol-containing files @dfn{objfiles}. 25230 25231The following objfile-related functions are available in the 25232@code{gdb} module: 25233 25234@findex gdb.current_objfile 25235@defun gdb.current_objfile () 25236When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN} 25237sets the ``current objfile'' to the corresponding objfile. This 25238function returns the current objfile. If there is no current objfile, 25239this function returns @code{None}. 25240@end defun 25241 25242@findex gdb.objfiles 25243@defun gdb.objfiles () 25244Return a sequence of all the objfiles current known to @value{GDBN}. 25245@xref{Objfiles In Python}. 25246@end defun 25247 25248Each objfile is represented by an instance of the @code{gdb.Objfile} 25249class. 25250 25251@defvar Objfile.filename 25252The file name of the objfile as a string. 25253@end defvar 25254 25255@defvar Objfile.pretty_printers 25256The @code{pretty_printers} attribute is a list of functions. It is 25257used to look up pretty-printers. A @code{Value} is passed to each 25258function in order; if the function returns @code{None}, then the 25259search continues. Otherwise, the return value should be an object 25260which is used to format the value. @xref{Pretty Printing API}, for more 25261information. 25262@end defvar 25263 25264@defvar Objfile.type_printers 25265The @code{type_printers} attribute is a list of type printer objects. 25266@xref{Type Printing API}, for more information. 25267@end defvar 25268 25269A @code{gdb.Objfile} object has the following methods: 25270 25271@defun Objfile.is_valid () 25272Returns @code{True} if the @code{gdb.Objfile} object is valid, 25273@code{False} if not. A @code{gdb.Objfile} object can become invalid 25274if the object file it refers to is not loaded in @value{GDBN} any 25275longer. All other @code{gdb.Objfile} methods will throw an exception 25276if it is invalid at the time the method is called. 25277@end defun 25278 25279@node Frames In Python 25280@subsubsection Accessing inferior stack frames from Python. 25281 25282@cindex frames in python 25283When the debugged program stops, @value{GDBN} is able to analyze its call 25284stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class 25285represents a frame in the stack. A @code{gdb.Frame} object is only valid 25286while its corresponding frame exists in the inferior's stack. If you try 25287to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error} 25288exception (@pxref{Exception Handling}). 25289 25290Two @code{gdb.Frame} objects can be compared for equality with the @code{==} 25291operator, like: 25292 25293@smallexample 25294(@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame () 25295True 25296@end smallexample 25297 25298The following frame-related functions are available in the @code{gdb} module: 25299 25300@findex gdb.selected_frame 25301@defun gdb.selected_frame () 25302Return the selected frame object. (@pxref{Selection,,Selecting a Frame}). 25303@end defun 25304 25305@findex gdb.newest_frame 25306@defun gdb.newest_frame () 25307Return the newest frame object for the selected thread. 25308@end defun 25309 25310@defun gdb.frame_stop_reason_string (reason) 25311Return a string explaining the reason why @value{GDBN} stopped unwinding 25312frames, as expressed by the given @var{reason} code (an integer, see the 25313@code{unwind_stop_reason} method further down in this section). 25314@end defun 25315 25316A @code{gdb.Frame} object has the following methods: 25317 25318@defun Frame.is_valid () 25319Returns true if the @code{gdb.Frame} object is valid, false if not. 25320A frame object can become invalid if the frame it refers to doesn't 25321exist anymore in the inferior. All @code{gdb.Frame} methods will throw 25322an exception if it is invalid at the time the method is called. 25323@end defun 25324 25325@defun Frame.name () 25326Returns the function name of the frame, or @code{None} if it can't be 25327obtained. 25328@end defun 25329 25330@defun Frame.architecture () 25331Returns the @code{gdb.Architecture} object corresponding to the frame's 25332architecture. @xref{Architectures In Python}. 25333@end defun 25334 25335@defun Frame.type () 25336Returns the type of the frame. The value can be one of: 25337@table @code 25338@item gdb.NORMAL_FRAME 25339An ordinary stack frame. 25340 25341@item gdb.DUMMY_FRAME 25342A fake stack frame that was created by @value{GDBN} when performing an 25343inferior function call. 25344 25345@item gdb.INLINE_FRAME 25346A frame representing an inlined function. The function was inlined 25347into a @code{gdb.NORMAL_FRAME} that is older than this one. 25348 25349@item gdb.TAILCALL_FRAME 25350A frame representing a tail call. @xref{Tail Call Frames}. 25351 25352@item gdb.SIGTRAMP_FRAME 25353A signal trampoline frame. This is the frame created by the OS when 25354it calls into a signal handler. 25355 25356@item gdb.ARCH_FRAME 25357A fake stack frame representing a cross-architecture call. 25358 25359@item gdb.SENTINEL_FRAME 25360This is like @code{gdb.NORMAL_FRAME}, but it is only used for the 25361newest frame. 25362@end table 25363@end defun 25364 25365@defun Frame.unwind_stop_reason () 25366Return an integer representing the reason why it's not possible to find 25367more frames toward the outermost frame. Use 25368@code{gdb.frame_stop_reason_string} to convert the value returned by this 25369function to a string. The value can be one of: 25370 25371@table @code 25372@item gdb.FRAME_UNWIND_NO_REASON 25373No particular reason (older frames should be available). 25374 25375@item gdb.FRAME_UNWIND_NULL_ID 25376The previous frame's analyzer returns an invalid result. 25377 25378@item gdb.FRAME_UNWIND_OUTERMOST 25379This frame is the outermost. 25380 25381@item gdb.FRAME_UNWIND_UNAVAILABLE 25382Cannot unwind further, because that would require knowing the 25383values of registers or memory that have not been collected. 25384 25385@item gdb.FRAME_UNWIND_INNER_ID 25386This frame ID looks like it ought to belong to a NEXT frame, 25387but we got it for a PREV frame. Normally, this is a sign of 25388unwinder failure. It could also indicate stack corruption. 25389 25390@item gdb.FRAME_UNWIND_SAME_ID 25391This frame has the same ID as the previous one. That means 25392that unwinding further would almost certainly give us another 25393frame with exactly the same ID, so break the chain. Normally, 25394this is a sign of unwinder failure. It could also indicate 25395stack corruption. 25396 25397@item gdb.FRAME_UNWIND_NO_SAVED_PC 25398The frame unwinder did not find any saved PC, but we needed 25399one to unwind further. 25400 25401@item gdb.FRAME_UNWIND_FIRST_ERROR 25402Any stop reason greater or equal to this value indicates some kind 25403of error. This special value facilitates writing code that tests 25404for errors in unwinding in a way that will work correctly even if 25405the list of the other values is modified in future @value{GDBN} 25406versions. Using it, you could write: 25407@smallexample 25408reason = gdb.selected_frame().unwind_stop_reason () 25409reason_str = gdb.frame_stop_reason_string (reason) 25410if reason >= gdb.FRAME_UNWIND_FIRST_ERROR: 25411 print "An error occured: %s" % reason_str 25412@end smallexample 25413@end table 25414 25415@end defun 25416 25417@defun Frame.pc () 25418Returns the frame's resume address. 25419@end defun 25420 25421@defun Frame.block () 25422Return the frame's code block. @xref{Blocks In Python}. 25423@end defun 25424 25425@defun Frame.function () 25426Return the symbol for the function corresponding to this frame. 25427@xref{Symbols In Python}. 25428@end defun 25429 25430@defun Frame.older () 25431Return the frame that called this frame. 25432@end defun 25433 25434@defun Frame.newer () 25435Return the frame called by this frame. 25436@end defun 25437 25438@defun Frame.find_sal () 25439Return the frame's symtab and line object. 25440@xref{Symbol Tables In Python}. 25441@end defun 25442 25443@defun Frame.read_var (variable @r{[}, block@r{]}) 25444Return the value of @var{variable} in this frame. If the optional 25445argument @var{block} is provided, search for the variable from that 25446block; otherwise start at the frame's current block (which is 25447determined by the frame's current program counter). @var{variable} 25448must be a string or a @code{gdb.Symbol} object. @var{block} must be a 25449@code{gdb.Block} object. 25450@end defun 25451 25452@defun Frame.select () 25453Set this frame to be the selected frame. @xref{Stack, ,Examining the 25454Stack}. 25455@end defun 25456 25457@node Blocks In Python 25458@subsubsection Accessing frame blocks from Python. 25459 25460@cindex blocks in python 25461@tindex gdb.Block 25462 25463Within each frame, @value{GDBN} maintains information on each block 25464stored in that frame. These blocks are organized hierarchically, and 25465are represented individually in Python as a @code{gdb.Block}. 25466Please see @ref{Frames In Python}, for a more in-depth discussion on 25467frames. Furthermore, see @ref{Stack, ,Examining the Stack}, for more 25468detailed technical information on @value{GDBN}'s book-keeping of the 25469stack. 25470 25471A @code{gdb.Block} is iterable. The iterator returns the symbols 25472(@pxref{Symbols In Python}) local to the block. Python programs 25473should not assume that a specific block object will always contain a 25474given symbol, since changes in @value{GDBN} features and 25475infrastructure may cause symbols move across blocks in a symbol 25476table. 25477 25478The following block-related functions are available in the @code{gdb} 25479module: 25480 25481@findex gdb.block_for_pc 25482@defun gdb.block_for_pc (pc) 25483Return the @code{gdb.Block} containing the given @var{pc} value. If the 25484block cannot be found for the @var{pc} value specified, the function 25485will return @code{None}. 25486@end defun 25487 25488A @code{gdb.Block} object has the following methods: 25489 25490@defun Block.is_valid () 25491Returns @code{True} if the @code{gdb.Block} object is valid, 25492@code{False} if not. A block object can become invalid if the block it 25493refers to doesn't exist anymore in the inferior. All other 25494@code{gdb.Block} methods will throw an exception if it is invalid at 25495the time the method is called. The block's validity is also checked 25496during iteration over symbols of the block. 25497@end defun 25498 25499A @code{gdb.Block} object has the following attributes: 25500 25501@defvar Block.start 25502The start address of the block. This attribute is not writable. 25503@end defvar 25504 25505@defvar Block.end 25506The end address of the block. This attribute is not writable. 25507@end defvar 25508 25509@defvar Block.function 25510The name of the block represented as a @code{gdb.Symbol}. If the 25511block is not named, then this attribute holds @code{None}. This 25512attribute is not writable. 25513@end defvar 25514 25515@defvar Block.superblock 25516The block containing this block. If this parent block does not exist, 25517this attribute holds @code{None}. This attribute is not writable. 25518@end defvar 25519 25520@defvar Block.global_block 25521The global block associated with this block. This attribute is not 25522writable. 25523@end defvar 25524 25525@defvar Block.static_block 25526The static block associated with this block. This attribute is not 25527writable. 25528@end defvar 25529 25530@defvar Block.is_global 25531@code{True} if the @code{gdb.Block} object is a global block, 25532@code{False} if not. This attribute is not 25533writable. 25534@end defvar 25535 25536@defvar Block.is_static 25537@code{True} if the @code{gdb.Block} object is a static block, 25538@code{False} if not. This attribute is not writable. 25539@end defvar 25540 25541@node Symbols In Python 25542@subsubsection Python representation of Symbols. 25543 25544@cindex symbols in python 25545@tindex gdb.Symbol 25546 25547@value{GDBN} represents every variable, function and type as an 25548entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}. 25549Similarly, Python represents these symbols in @value{GDBN} with the 25550@code{gdb.Symbol} object. 25551 25552The following symbol-related functions are available in the @code{gdb} 25553module: 25554 25555@findex gdb.lookup_symbol 25556@defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]}) 25557This function searches for a symbol by name. The search scope can be 25558restricted to the parameters defined in the optional domain and block 25559arguments. 25560 25561@var{name} is the name of the symbol. It must be a string. The 25562optional @var{block} argument restricts the search to symbols visible 25563in that @var{block}. The @var{block} argument must be a 25564@code{gdb.Block} object. If omitted, the block for the current frame 25565is used. The optional @var{domain} argument restricts 25566the search to the domain type. The @var{domain} argument must be a 25567domain constant defined in the @code{gdb} module and described later 25568in this chapter. 25569 25570The result is a tuple of two elements. 25571The first element is a @code{gdb.Symbol} object or @code{None} if the symbol 25572is not found. 25573If the symbol is found, the second element is @code{True} if the symbol 25574is a field of a method's object (e.g., @code{this} in C@t{++}), 25575otherwise it is @code{False}. 25576If the symbol is not found, the second element is @code{False}. 25577@end defun 25578 25579@findex gdb.lookup_global_symbol 25580@defun gdb.lookup_global_symbol (name @r{[}, domain@r{]}) 25581This function searches for a global symbol by name. 25582The search scope can be restricted to by the domain argument. 25583 25584@var{name} is the name of the symbol. It must be a string. 25585The optional @var{domain} argument restricts the search to the domain type. 25586The @var{domain} argument must be a domain constant defined in the @code{gdb} 25587module and described later in this chapter. 25588 25589The result is a @code{gdb.Symbol} object or @code{None} if the symbol 25590is not found. 25591@end defun 25592 25593A @code{gdb.Symbol} object has the following attributes: 25594 25595@defvar Symbol.type 25596The type of the symbol or @code{None} if no type is recorded. 25597This attribute is represented as a @code{gdb.Type} object. 25598@xref{Types In Python}. This attribute is not writable. 25599@end defvar 25600 25601@defvar Symbol.symtab 25602The symbol table in which the symbol appears. This attribute is 25603represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In 25604Python}. This attribute is not writable. 25605@end defvar 25606 25607@defvar Symbol.line 25608The line number in the source code at which the symbol was defined. 25609This is an integer. 25610@end defvar 25611 25612@defvar Symbol.name 25613The name of the symbol as a string. This attribute is not writable. 25614@end defvar 25615 25616@defvar Symbol.linkage_name 25617The name of the symbol, as used by the linker (i.e., may be mangled). 25618This attribute is not writable. 25619@end defvar 25620 25621@defvar Symbol.print_name 25622The name of the symbol in a form suitable for output. This is either 25623@code{name} or @code{linkage_name}, depending on whether the user 25624asked @value{GDBN} to display demangled or mangled names. 25625@end defvar 25626 25627@defvar Symbol.addr_class 25628The address class of the symbol. This classifies how to find the value 25629of a symbol. Each address class is a constant defined in the 25630@code{gdb} module and described later in this chapter. 25631@end defvar 25632 25633@defvar Symbol.needs_frame 25634This is @code{True} if evaluating this symbol's value requires a frame 25635(@pxref{Frames In Python}) and @code{False} otherwise. Typically, 25636local variables will require a frame, but other symbols will not. 25637@end defvar 25638 25639@defvar Symbol.is_argument 25640@code{True} if the symbol is an argument of a function. 25641@end defvar 25642 25643@defvar Symbol.is_constant 25644@code{True} if the symbol is a constant. 25645@end defvar 25646 25647@defvar Symbol.is_function 25648@code{True} if the symbol is a function or a method. 25649@end defvar 25650 25651@defvar Symbol.is_variable 25652@code{True} if the symbol is a variable. 25653@end defvar 25654 25655A @code{gdb.Symbol} object has the following methods: 25656 25657@defun Symbol.is_valid () 25658Returns @code{True} if the @code{gdb.Symbol} object is valid, 25659@code{False} if not. A @code{gdb.Symbol} object can become invalid if 25660the symbol it refers to does not exist in @value{GDBN} any longer. 25661All other @code{gdb.Symbol} methods will throw an exception if it is 25662invalid at the time the method is called. 25663@end defun 25664 25665@defun Symbol.value (@r{[}frame@r{]}) 25666Compute the value of the symbol, as a @code{gdb.Value}. For 25667functions, this computes the address of the function, cast to the 25668appropriate type. If the symbol requires a frame in order to compute 25669its value, then @var{frame} must be given. If @var{frame} is not 25670given, or if @var{frame} is invalid, then this method will throw an 25671exception. 25672@end defun 25673 25674The available domain categories in @code{gdb.Symbol} are represented 25675as constants in the @code{gdb} module: 25676 25677@table @code 25678@findex SYMBOL_UNDEF_DOMAIN 25679@findex gdb.SYMBOL_UNDEF_DOMAIN 25680@item gdb.SYMBOL_UNDEF_DOMAIN 25681This is used when a domain has not been discovered or none of the 25682following domains apply. This usually indicates an error either 25683in the symbol information or in @value{GDBN}'s handling of symbols. 25684@findex SYMBOL_VAR_DOMAIN 25685@findex gdb.SYMBOL_VAR_DOMAIN 25686@item gdb.SYMBOL_VAR_DOMAIN 25687This domain contains variables, function names, typedef names and enum 25688type values. 25689@findex SYMBOL_STRUCT_DOMAIN 25690@findex gdb.SYMBOL_STRUCT_DOMAIN 25691@item gdb.SYMBOL_STRUCT_DOMAIN 25692This domain holds struct, union and enum type names. 25693@findex SYMBOL_LABEL_DOMAIN 25694@findex gdb.SYMBOL_LABEL_DOMAIN 25695@item gdb.SYMBOL_LABEL_DOMAIN 25696This domain contains names of labels (for gotos). 25697@findex SYMBOL_VARIABLES_DOMAIN 25698@findex gdb.SYMBOL_VARIABLES_DOMAIN 25699@item gdb.SYMBOL_VARIABLES_DOMAIN 25700This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it 25701contains everything minus functions and types. 25702@findex SYMBOL_FUNCTIONS_DOMAIN 25703@findex gdb.SYMBOL_FUNCTIONS_DOMAIN 25704@item gdb.SYMBOL_FUNCTION_DOMAIN 25705This domain contains all functions. 25706@findex SYMBOL_TYPES_DOMAIN 25707@findex gdb.SYMBOL_TYPES_DOMAIN 25708@item gdb.SYMBOL_TYPES_DOMAIN 25709This domain contains all types. 25710@end table 25711 25712The available address class categories in @code{gdb.Symbol} are represented 25713as constants in the @code{gdb} module: 25714 25715@table @code 25716@findex SYMBOL_LOC_UNDEF 25717@findex gdb.SYMBOL_LOC_UNDEF 25718@item gdb.SYMBOL_LOC_UNDEF 25719If this is returned by address class, it indicates an error either in 25720the symbol information or in @value{GDBN}'s handling of symbols. 25721@findex SYMBOL_LOC_CONST 25722@findex gdb.SYMBOL_LOC_CONST 25723@item gdb.SYMBOL_LOC_CONST 25724Value is constant int. 25725@findex SYMBOL_LOC_STATIC 25726@findex gdb.SYMBOL_LOC_STATIC 25727@item gdb.SYMBOL_LOC_STATIC 25728Value is at a fixed address. 25729@findex SYMBOL_LOC_REGISTER 25730@findex gdb.SYMBOL_LOC_REGISTER 25731@item gdb.SYMBOL_LOC_REGISTER 25732Value is in a register. 25733@findex SYMBOL_LOC_ARG 25734@findex gdb.SYMBOL_LOC_ARG 25735@item gdb.SYMBOL_LOC_ARG 25736Value is an argument. This value is at the offset stored within the 25737symbol inside the frame's argument list. 25738@findex SYMBOL_LOC_REF_ARG 25739@findex gdb.SYMBOL_LOC_REF_ARG 25740@item gdb.SYMBOL_LOC_REF_ARG 25741Value address is stored in the frame's argument list. Just like 25742@code{LOC_ARG} except that the value's address is stored at the 25743offset, not the value itself. 25744@findex SYMBOL_LOC_REGPARM_ADDR 25745@findex gdb.SYMBOL_LOC_REGPARM_ADDR 25746@item gdb.SYMBOL_LOC_REGPARM_ADDR 25747Value is a specified register. Just like @code{LOC_REGISTER} except 25748the register holds the address of the argument instead of the argument 25749itself. 25750@findex SYMBOL_LOC_LOCAL 25751@findex gdb.SYMBOL_LOC_LOCAL 25752@item gdb.SYMBOL_LOC_LOCAL 25753Value is a local variable. 25754@findex SYMBOL_LOC_TYPEDEF 25755@findex gdb.SYMBOL_LOC_TYPEDEF 25756@item gdb.SYMBOL_LOC_TYPEDEF 25757Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all 25758have this class. 25759@findex SYMBOL_LOC_BLOCK 25760@findex gdb.SYMBOL_LOC_BLOCK 25761@item gdb.SYMBOL_LOC_BLOCK 25762Value is a block. 25763@findex SYMBOL_LOC_CONST_BYTES 25764@findex gdb.SYMBOL_LOC_CONST_BYTES 25765@item gdb.SYMBOL_LOC_CONST_BYTES 25766Value is a byte-sequence. 25767@findex SYMBOL_LOC_UNRESOLVED 25768@findex gdb.SYMBOL_LOC_UNRESOLVED 25769@item gdb.SYMBOL_LOC_UNRESOLVED 25770Value is at a fixed address, but the address of the variable has to be 25771determined from the minimal symbol table whenever the variable is 25772referenced. 25773@findex SYMBOL_LOC_OPTIMIZED_OUT 25774@findex gdb.SYMBOL_LOC_OPTIMIZED_OUT 25775@item gdb.SYMBOL_LOC_OPTIMIZED_OUT 25776The value does not actually exist in the program. 25777@findex SYMBOL_LOC_COMPUTED 25778@findex gdb.SYMBOL_LOC_COMPUTED 25779@item gdb.SYMBOL_LOC_COMPUTED 25780The value's address is a computed location. 25781@end table 25782 25783@node Symbol Tables In Python 25784@subsubsection Symbol table representation in Python. 25785 25786@cindex symbol tables in python 25787@tindex gdb.Symtab 25788@tindex gdb.Symtab_and_line 25789 25790Access to symbol table data maintained by @value{GDBN} on the inferior 25791is exposed to Python via two objects: @code{gdb.Symtab_and_line} and 25792@code{gdb.Symtab}. Symbol table and line data for a frame is returned 25793from the @code{find_sal} method in @code{gdb.Frame} object. 25794@xref{Frames In Python}. 25795 25796For more information on @value{GDBN}'s symbol table management, see 25797@ref{Symbols, ,Examining the Symbol Table}, for more information. 25798 25799A @code{gdb.Symtab_and_line} object has the following attributes: 25800 25801@defvar Symtab_and_line.symtab 25802The symbol table object (@code{gdb.Symtab}) for this frame. 25803This attribute is not writable. 25804@end defvar 25805 25806@defvar Symtab_and_line.pc 25807Indicates the start of the address range occupied by code for the 25808current source line. This attribute is not writable. 25809@end defvar 25810 25811@defvar Symtab_and_line.last 25812Indicates the end of the address range occupied by code for the current 25813source line. This attribute is not writable. 25814@end defvar 25815 25816@defvar Symtab_and_line.line 25817Indicates the current line number for this object. This 25818attribute is not writable. 25819@end defvar 25820 25821A @code{gdb.Symtab_and_line} object has the following methods: 25822 25823@defun Symtab_and_line.is_valid () 25824Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid, 25825@code{False} if not. A @code{gdb.Symtab_and_line} object can become 25826invalid if the Symbol table and line object it refers to does not 25827exist in @value{GDBN} any longer. All other 25828@code{gdb.Symtab_and_line} methods will throw an exception if it is 25829invalid at the time the method is called. 25830@end defun 25831 25832A @code{gdb.Symtab} object has the following attributes: 25833 25834@defvar Symtab.filename 25835The symbol table's source filename. This attribute is not writable. 25836@end defvar 25837 25838@defvar Symtab.objfile 25839The symbol table's backing object file. @xref{Objfiles In Python}. 25840This attribute is not writable. 25841@end defvar 25842 25843A @code{gdb.Symtab} object has the following methods: 25844 25845@defun Symtab.is_valid () 25846Returns @code{True} if the @code{gdb.Symtab} object is valid, 25847@code{False} if not. A @code{gdb.Symtab} object can become invalid if 25848the symbol table it refers to does not exist in @value{GDBN} any 25849longer. All other @code{gdb.Symtab} methods will throw an exception 25850if it is invalid at the time the method is called. 25851@end defun 25852 25853@defun Symtab.fullname () 25854Return the symbol table's source absolute file name. 25855@end defun 25856 25857@defun Symtab.global_block () 25858Return the global block of the underlying symbol table. 25859@xref{Blocks In Python}. 25860@end defun 25861 25862@defun Symtab.static_block () 25863Return the static block of the underlying symbol table. 25864@xref{Blocks In Python}. 25865@end defun 25866 25867@node Breakpoints In Python 25868@subsubsection Manipulating breakpoints using Python 25869 25870@cindex breakpoints in python 25871@tindex gdb.Breakpoint 25872 25873Python code can manipulate breakpoints via the @code{gdb.Breakpoint} 25874class. 25875 25876@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal@r{]]]}) 25877Create a new breakpoint. @var{spec} is a string naming the 25878location of the breakpoint, or an expression that defines a 25879watchpoint. The contents can be any location recognized by the 25880@code{break} command, or in the case of a watchpoint, by the @code{watch} 25881command. The optional @var{type} denotes the breakpoint to create 25882from the types defined later in this chapter. This argument can be 25883either: @code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}. @var{type} 25884defaults to @code{gdb.BP_BREAKPOINT}. The optional @var{internal} argument 25885allows the breakpoint to become invisible to the user. The breakpoint 25886will neither be reported when created, nor will it be listed in the 25887output from @code{info breakpoints} (but will be listed with the 25888@code{maint info breakpoints} command). The optional @var{wp_class} 25889argument defines the class of watchpoint to create, if @var{type} is 25890@code{gdb.BP_WATCHPOINT}. If a watchpoint class is not provided, it is 25891assumed to be a @code{gdb.WP_WRITE} class. 25892@end defun 25893 25894@defun Breakpoint.stop (self) 25895The @code{gdb.Breakpoint} class can be sub-classed and, in 25896particular, you may choose to implement the @code{stop} method. 25897If this method is defined as a sub-class of @code{gdb.Breakpoint}, 25898it will be called when the inferior reaches any location of a 25899breakpoint which instantiates that sub-class. If the method returns 25900@code{True}, the inferior will be stopped at the location of the 25901breakpoint, otherwise the inferior will continue. 25902 25903If there are multiple breakpoints at the same location with a 25904@code{stop} method, each one will be called regardless of the 25905return status of the previous. This ensures that all @code{stop} 25906methods have a chance to execute at that location. In this scenario 25907if one of the methods returns @code{True} but the others return 25908@code{False}, the inferior will still be stopped. 25909 25910You should not alter the execution state of the inferior (i.e.@:, step, 25911next, etc.), alter the current frame context (i.e.@:, change the current 25912active frame), or alter, add or delete any breakpoint. As a general 25913rule, you should not alter any data within @value{GDBN} or the inferior 25914at this time. 25915 25916Example @code{stop} implementation: 25917 25918@smallexample 25919class MyBreakpoint (gdb.Breakpoint): 25920 def stop (self): 25921 inf_val = gdb.parse_and_eval("foo") 25922 if inf_val == 3: 25923 return True 25924 return False 25925@end smallexample 25926@end defun 25927 25928The available watchpoint types represented by constants are defined in the 25929@code{gdb} module: 25930 25931@table @code 25932@findex WP_READ 25933@findex gdb.WP_READ 25934@item gdb.WP_READ 25935Read only watchpoint. 25936 25937@findex WP_WRITE 25938@findex gdb.WP_WRITE 25939@item gdb.WP_WRITE 25940Write only watchpoint. 25941 25942@findex WP_ACCESS 25943@findex gdb.WP_ACCESS 25944@item gdb.WP_ACCESS 25945Read/Write watchpoint. 25946@end table 25947 25948@defun Breakpoint.is_valid () 25949Return @code{True} if this @code{Breakpoint} object is valid, 25950@code{False} otherwise. A @code{Breakpoint} object can become invalid 25951if the user deletes the breakpoint. In this case, the object still 25952exists, but the underlying breakpoint does not. In the cases of 25953watchpoint scope, the watchpoint remains valid even if execution of the 25954inferior leaves the scope of that watchpoint. 25955@end defun 25956 25957@defun Breakpoint.delete 25958Permanently deletes the @value{GDBN} breakpoint. This also 25959invalidates the Python @code{Breakpoint} object. Any further access 25960to this object's attributes or methods will raise an error. 25961@end defun 25962 25963@defvar Breakpoint.enabled 25964This attribute is @code{True} if the breakpoint is enabled, and 25965@code{False} otherwise. This attribute is writable. 25966@end defvar 25967 25968@defvar Breakpoint.silent 25969This attribute is @code{True} if the breakpoint is silent, and 25970@code{False} otherwise. This attribute is writable. 25971 25972Note that a breakpoint can also be silent if it has commands and the 25973first command is @code{silent}. This is not reported by the 25974@code{silent} attribute. 25975@end defvar 25976 25977@defvar Breakpoint.thread 25978If the breakpoint is thread-specific, this attribute holds the thread 25979id. If the breakpoint is not thread-specific, this attribute is 25980@code{None}. This attribute is writable. 25981@end defvar 25982 25983@defvar Breakpoint.task 25984If the breakpoint is Ada task-specific, this attribute holds the Ada task 25985id. If the breakpoint is not task-specific (or the underlying 25986language is not Ada), this attribute is @code{None}. This attribute 25987is writable. 25988@end defvar 25989 25990@defvar Breakpoint.ignore_count 25991This attribute holds the ignore count for the breakpoint, an integer. 25992This attribute is writable. 25993@end defvar 25994 25995@defvar Breakpoint.number 25996This attribute holds the breakpoint's number --- the identifier used by 25997the user to manipulate the breakpoint. This attribute is not writable. 25998@end defvar 25999 26000@defvar Breakpoint.type 26001This attribute holds the breakpoint's type --- the identifier used to 26002determine the actual breakpoint type or use-case. This attribute is not 26003writable. 26004@end defvar 26005 26006@defvar Breakpoint.visible 26007This attribute tells whether the breakpoint is visible to the user 26008when set, or when the @samp{info breakpoints} command is run. This 26009attribute is not writable. 26010@end defvar 26011 26012The available types are represented by constants defined in the @code{gdb} 26013module: 26014 26015@table @code 26016@findex BP_BREAKPOINT 26017@findex gdb.BP_BREAKPOINT 26018@item gdb.BP_BREAKPOINT 26019Normal code breakpoint. 26020 26021@findex BP_WATCHPOINT 26022@findex gdb.BP_WATCHPOINT 26023@item gdb.BP_WATCHPOINT 26024Watchpoint breakpoint. 26025 26026@findex BP_HARDWARE_WATCHPOINT 26027@findex gdb.BP_HARDWARE_WATCHPOINT 26028@item gdb.BP_HARDWARE_WATCHPOINT 26029Hardware assisted watchpoint. 26030 26031@findex BP_READ_WATCHPOINT 26032@findex gdb.BP_READ_WATCHPOINT 26033@item gdb.BP_READ_WATCHPOINT 26034Hardware assisted read watchpoint. 26035 26036@findex BP_ACCESS_WATCHPOINT 26037@findex gdb.BP_ACCESS_WATCHPOINT 26038@item gdb.BP_ACCESS_WATCHPOINT 26039Hardware assisted access watchpoint. 26040@end table 26041 26042@defvar Breakpoint.hit_count 26043This attribute holds the hit count for the breakpoint, an integer. 26044This attribute is writable, but currently it can only be set to zero. 26045@end defvar 26046 26047@defvar Breakpoint.location 26048This attribute holds the location of the breakpoint, as specified by 26049the user. It is a string. If the breakpoint does not have a location 26050(that is, it is a watchpoint) the attribute's value is @code{None}. This 26051attribute is not writable. 26052@end defvar 26053 26054@defvar Breakpoint.expression 26055This attribute holds a breakpoint expression, as specified by 26056the user. It is a string. If the breakpoint does not have an 26057expression (the breakpoint is not a watchpoint) the attribute's value 26058is @code{None}. This attribute is not writable. 26059@end defvar 26060 26061@defvar Breakpoint.condition 26062This attribute holds the condition of the breakpoint, as specified by 26063the user. It is a string. If there is no condition, this attribute's 26064value is @code{None}. This attribute is writable. 26065@end defvar 26066 26067@defvar Breakpoint.commands 26068This attribute holds the commands attached to the breakpoint. If 26069there are commands, this attribute's value is a string holding all the 26070commands, separated by newlines. If there are no commands, this 26071attribute is @code{None}. This attribute is not writable. 26072@end defvar 26073 26074@node Finish Breakpoints in Python 26075@subsubsection Finish Breakpoints 26076 26077@cindex python finish breakpoints 26078@tindex gdb.FinishBreakpoint 26079 26080A finish breakpoint is a temporary breakpoint set at the return address of 26081a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint} 26082extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled 26083and deleted when the execution will run out of the breakpoint scope (i.e.@: 26084@code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered). 26085Finish breakpoints are thread specific and must be create with the right 26086thread selected. 26087 26088@defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]}) 26089Create a finish breakpoint at the return address of the @code{gdb.Frame} 26090object @var{frame}. If @var{frame} is not provided, this defaults to the 26091newest frame. The optional @var{internal} argument allows the breakpoint to 26092become invisible to the user. @xref{Breakpoints In Python}, for further 26093details about this argument. 26094@end defun 26095 26096@defun FinishBreakpoint.out_of_scope (self) 26097In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN} 26098@code{return} command, @dots{}), a function may not properly terminate, and 26099thus never hit the finish breakpoint. When @value{GDBN} notices such a 26100situation, the @code{out_of_scope} callback will be triggered. 26101 26102You may want to sub-class @code{gdb.FinishBreakpoint} and override this 26103method: 26104 26105@smallexample 26106class MyFinishBreakpoint (gdb.FinishBreakpoint) 26107 def stop (self): 26108 print "normal finish" 26109 return True 26110 26111 def out_of_scope (): 26112 print "abnormal finish" 26113@end smallexample 26114@end defun 26115 26116@defvar FinishBreakpoint.return_value 26117When @value{GDBN} is stopped at a finish breakpoint and the frame 26118used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this 26119attribute will contain a @code{gdb.Value} object corresponding to the return 26120value of the function. The value will be @code{None} if the function return 26121type is @code{void} or if the return value was not computable. This attribute 26122is not writable. 26123@end defvar 26124 26125@node Lazy Strings In Python 26126@subsubsection Python representation of lazy strings. 26127 26128@cindex lazy strings in python 26129@tindex gdb.LazyString 26130 26131A @dfn{lazy string} is a string whose contents is not retrieved or 26132encoded until it is needed. 26133 26134A @code{gdb.LazyString} is represented in @value{GDBN} as an 26135@code{address} that points to a region of memory, an @code{encoding} 26136that will be used to encode that region of memory, and a @code{length} 26137to delimit the region of memory that represents the string. The 26138difference between a @code{gdb.LazyString} and a string wrapped within 26139a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated 26140differently by @value{GDBN} when printing. A @code{gdb.LazyString} is 26141retrieved and encoded during printing, while a @code{gdb.Value} 26142wrapping a string is immediately retrieved and encoded on creation. 26143 26144A @code{gdb.LazyString} object has the following functions: 26145 26146@defun LazyString.value () 26147Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value 26148will point to the string in memory, but will lose all the delayed 26149retrieval, encoding and handling that @value{GDBN} applies to a 26150@code{gdb.LazyString}. 26151@end defun 26152 26153@defvar LazyString.address 26154This attribute holds the address of the string. This attribute is not 26155writable. 26156@end defvar 26157 26158@defvar LazyString.length 26159This attribute holds the length of the string in characters. If the 26160length is -1, then the string will be fetched and encoded up to the 26161first null of appropriate width. This attribute is not writable. 26162@end defvar 26163 26164@defvar LazyString.encoding 26165This attribute holds the encoding that will be applied to the string 26166when the string is printed by @value{GDBN}. If the encoding is not 26167set, or contains an empty string, then @value{GDBN} will select the 26168most appropriate encoding when the string is printed. This attribute 26169is not writable. 26170@end defvar 26171 26172@defvar LazyString.type 26173This attribute holds the type that is represented by the lazy string's 26174type. For a lazy string this will always be a pointer type. To 26175resolve this to the lazy string's character type, use the type's 26176@code{target} method. @xref{Types In Python}. This attribute is not 26177writable. 26178@end defvar 26179 26180@node Architectures In Python 26181@subsubsection Python representation of architectures 26182@cindex Python architectures 26183 26184@value{GDBN} uses architecture specific parameters and artifacts in a 26185number of its various computations. An architecture is represented 26186by an instance of the @code{gdb.Architecture} class. 26187 26188A @code{gdb.Architecture} class has the following methods: 26189 26190@defun Architecture.name () 26191Return the name (string value) of the architecture. 26192@end defun 26193 26194@defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]}) 26195Return a list of disassembled instructions starting from the memory 26196address @var{start_pc}. The optional arguments @var{end_pc} and 26197@var{count} determine the number of instructions in the returned list. 26198If both the optional arguments @var{end_pc} and @var{count} are 26199specified, then a list of at most @var{count} disassembled instructions 26200whose start address falls in the closed memory address interval from 26201@var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not 26202specified, but @var{count} is specified, then @var{count} number of 26203instructions starting from the address @var{start_pc} are returned. If 26204@var{count} is not specified but @var{end_pc} is specified, then all 26205instructions whose start address falls in the closed memory address 26206interval from @var{start_pc} to @var{end_pc} are returned. If neither 26207@var{end_pc} nor @var{count} are specified, then a single instruction at 26208@var{start_pc} is returned. For all of these cases, each element of the 26209returned list is a Python @code{dict} with the following string keys: 26210 26211@table @code 26212 26213@item addr 26214The value corresponding to this key is a Python long integer capturing 26215the memory address of the instruction. 26216 26217@item asm 26218The value corresponding to this key is a string value which represents 26219the instruction with assembly language mnemonics. The assembly 26220language flavor used is the same as that specified by the current CLI 26221variable @code{disassembly-flavor}. @xref{Machine Code}. 26222 26223@item length 26224The value corresponding to this key is the length (integer value) of the 26225instruction in bytes. 26226 26227@end table 26228@end defun 26229 26230@node Python Auto-loading 26231@subsection Python Auto-loading 26232@cindex Python auto-loading 26233 26234When a new object file is read (for example, due to the @code{file} 26235command, or because the inferior has loaded a shared library), 26236@value{GDBN} will look for Python support scripts in several ways: 26237@file{@var{objfile}-gdb.py} (@pxref{objfile-gdb.py file}) 26238and @code{.debug_gdb_scripts} section 26239(@pxref{dotdebug_gdb_scripts section}). 26240 26241The auto-loading feature is useful for supplying application-specific 26242debugging commands and scripts. 26243 26244Auto-loading can be enabled or disabled, 26245and the list of auto-loaded scripts can be printed. 26246 26247@table @code 26248@anchor{set auto-load python-scripts} 26249@kindex set auto-load python-scripts 26250@item set auto-load python-scripts [on|off] 26251Enable or disable the auto-loading of Python scripts. 26252 26253@anchor{show auto-load python-scripts} 26254@kindex show auto-load python-scripts 26255@item show auto-load python-scripts 26256Show whether auto-loading of Python scripts is enabled or disabled. 26257 26258@anchor{info auto-load python-scripts} 26259@kindex info auto-load python-scripts 26260@cindex print list of auto-loaded Python scripts 26261@item info auto-load python-scripts [@var{regexp}] 26262Print the list of all Python scripts that @value{GDBN} auto-loaded. 26263 26264Also printed is the list of Python scripts that were mentioned in 26265the @code{.debug_gdb_scripts} section and were not found 26266(@pxref{dotdebug_gdb_scripts section}). 26267This is useful because their names are not printed when @value{GDBN} 26268tries to load them and fails. There may be many of them, and printing 26269an error message for each one is problematic. 26270 26271If @var{regexp} is supplied only Python scripts with matching names are printed. 26272 26273Example: 26274 26275@smallexample 26276(gdb) info auto-load python-scripts 26277Loaded Script 26278Yes py-section-script.py 26279 full name: /tmp/py-section-script.py 26280No my-foo-pretty-printers.py 26281@end smallexample 26282@end table 26283 26284When reading an auto-loaded file, @value{GDBN} sets the 26285@dfn{current objfile}. This is available via the @code{gdb.current_objfile} 26286function (@pxref{Objfiles In Python}). This can be useful for 26287registering objfile-specific pretty-printers. 26288 26289@menu 26290* objfile-gdb.py file:: The @file{@var{objfile}-gdb.py} file 26291* dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section 26292* Which flavor to choose?:: 26293@end menu 26294 26295@node objfile-gdb.py file 26296@subsubsection The @file{@var{objfile}-gdb.py} file 26297@cindex @file{@var{objfile}-gdb.py} 26298 26299When a new object file is read, @value{GDBN} looks for 26300a file named @file{@var{objfile}-gdb.py} (we call it @var{script-name} below), 26301where @var{objfile} is the object file's real name, formed by ensuring 26302that the file name is absolute, following all symlinks, and resolving 26303@code{.} and @code{..} components. If this file exists and is 26304readable, @value{GDBN} will evaluate it as a Python script. 26305 26306If this file does not exist, then @value{GDBN} will look for 26307@var{script-name} file in all of the directories as specified below. 26308 26309Note that loading of this script file also requires accordingly configured 26310@code{auto-load safe-path} (@pxref{Auto-loading safe path}). 26311 26312For object files using @file{.exe} suffix @value{GDBN} tries to load first the 26313scripts normally according to its @file{.exe} filename. But if no scripts are 26314found @value{GDBN} also tries script filenames matching the object file without 26315its @file{.exe} suffix. This @file{.exe} stripping is case insensitive and it 26316is attempted on any platform. This makes the script filenames compatible 26317between Unix and MS-Windows hosts. 26318 26319@table @code 26320@anchor{set auto-load scripts-directory} 26321@kindex set auto-load scripts-directory 26322@item set auto-load scripts-directory @r{[}@var{directories}@r{]} 26323Control @value{GDBN} auto-loaded scripts location. Multiple directory entries 26324may be delimited by the host platform path separator in use 26325(@samp{:} on Unix, @samp{;} on MS-Windows and MS-DOS). 26326 26327Each entry here needs to be covered also by the security setting 26328@code{set auto-load safe-path} (@pxref{set auto-load safe-path}). 26329 26330@anchor{with-auto-load-dir} 26331This variable defaults to @file{$debugdir:$datadir/auto-load}. The default 26332@code{set auto-load safe-path} value can be also overriden by @value{GDBN} 26333configuration option @option{--with-auto-load-dir}. 26334 26335Any reference to @file{$debugdir} will get replaced by 26336@var{debug-file-directory} value (@pxref{Separate Debug Files}) and any 26337reference to @file{$datadir} will get replaced by @var{data-directory} which is 26338determined at @value{GDBN} startup (@pxref{Data Files}). @file{$debugdir} and 26339@file{$datadir} must be placed as a directory component --- either alone or 26340delimited by @file{/} or @file{\} directory separators, depending on the host 26341platform. 26342 26343The list of directories uses path separator (@samp{:} on GNU and Unix 26344systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly 26345to the @env{PATH} environment variable. 26346 26347@anchor{show auto-load scripts-directory} 26348@kindex show auto-load scripts-directory 26349@item show auto-load scripts-directory 26350Show @value{GDBN} auto-loaded scripts location. 26351@end table 26352 26353@value{GDBN} does not track which files it has already auto-loaded this way. 26354@value{GDBN} will load the associated script every time the corresponding 26355@var{objfile} is opened. 26356So your @file{-gdb.py} file should be careful to avoid errors if it 26357is evaluated more than once. 26358 26359@node dotdebug_gdb_scripts section 26360@subsubsection The @code{.debug_gdb_scripts} section 26361@cindex @code{.debug_gdb_scripts} section 26362 26363For systems using file formats like ELF and COFF, 26364when @value{GDBN} loads a new object file 26365it will look for a special section named @samp{.debug_gdb_scripts}. 26366If this section exists, its contents is a list of names of scripts to load. 26367 26368@value{GDBN} will look for each specified script file first in the 26369current directory and then along the source search path 26370(@pxref{Source Path, ,Specifying Source Directories}), 26371except that @file{$cdir} is not searched, since the compilation 26372directory is not relevant to scripts. 26373 26374Entries can be placed in section @code{.debug_gdb_scripts} with, 26375for example, this GCC macro: 26376 26377@example 26378/* Note: The "MS" section flags are to remove duplicates. */ 26379#define DEFINE_GDB_SCRIPT(script_name) \ 26380 asm("\ 26381.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\ 26382.byte 1\n\ 26383.asciz \"" script_name "\"\n\ 26384.popsection \n\ 26385"); 26386@end example 26387 26388@noindent 26389Then one can reference the macro in a header or source file like this: 26390 26391@example 26392DEFINE_GDB_SCRIPT ("my-app-scripts.py") 26393@end example 26394 26395The script name may include directories if desired. 26396 26397Note that loading of this script file also requires accordingly configured 26398@code{auto-load safe-path} (@pxref{Auto-loading safe path}). 26399 26400If the macro is put in a header, any application or library 26401using this header will get a reference to the specified script. 26402 26403@node Which flavor to choose? 26404@subsubsection Which flavor to choose? 26405 26406Given the multiple ways of auto-loading Python scripts, it might not always 26407be clear which one to choose. This section provides some guidance. 26408 26409Benefits of the @file{-gdb.py} way: 26410 26411@itemize @bullet 26412@item 26413Can be used with file formats that don't support multiple sections. 26414 26415@item 26416Ease of finding scripts for public libraries. 26417 26418Scripts specified in the @code{.debug_gdb_scripts} section are searched for 26419in the source search path. 26420For publicly installed libraries, e.g., @file{libstdc++}, there typically 26421isn't a source directory in which to find the script. 26422 26423@item 26424Doesn't require source code additions. 26425@end itemize 26426 26427Benefits of the @code{.debug_gdb_scripts} way: 26428 26429@itemize @bullet 26430@item 26431Works with static linking. 26432 26433Scripts for libraries done the @file{-gdb.py} way require an objfile to 26434trigger their loading. When an application is statically linked the only 26435objfile available is the executable, and it is cumbersome to attach all the 26436scripts from all the input libraries to the executable's @file{-gdb.py} script. 26437 26438@item 26439Works with classes that are entirely inlined. 26440 26441Some classes can be entirely inlined, and thus there may not be an associated 26442shared library to attach a @file{-gdb.py} script to. 26443 26444@item 26445Scripts needn't be copied out of the source tree. 26446 26447In some circumstances, apps can be built out of large collections of internal 26448libraries, and the build infrastructure necessary to install the 26449@file{-gdb.py} scripts in a place where @value{GDBN} can find them is 26450cumbersome. It may be easier to specify the scripts in the 26451@code{.debug_gdb_scripts} section as relative paths, and add a path to the 26452top of the source tree to the source search path. 26453@end itemize 26454 26455@node Python modules 26456@subsection Python modules 26457@cindex python modules 26458 26459@value{GDBN} comes with several modules to assist writing Python code. 26460 26461@menu 26462* gdb.printing:: Building and registering pretty-printers. 26463* gdb.types:: Utilities for working with types. 26464* gdb.prompt:: Utilities for prompt value substitution. 26465@end menu 26466 26467@node gdb.printing 26468@subsubsection gdb.printing 26469@cindex gdb.printing 26470 26471This module provides a collection of utilities for working with 26472pretty-printers. 26473 26474@table @code 26475@item PrettyPrinter (@var{name}, @var{subprinters}=None) 26476This class specifies the API that makes @samp{info pretty-printer}, 26477@samp{enable pretty-printer} and @samp{disable pretty-printer} work. 26478Pretty-printers should generally inherit from this class. 26479 26480@item SubPrettyPrinter (@var{name}) 26481For printers that handle multiple types, this class specifies the 26482corresponding API for the subprinters. 26483 26484@item RegexpCollectionPrettyPrinter (@var{name}) 26485Utility class for handling multiple printers, all recognized via 26486regular expressions. 26487@xref{Writing a Pretty-Printer}, for an example. 26488 26489@item FlagEnumerationPrinter (@var{name}) 26490A pretty-printer which handles printing of @code{enum} values. Unlike 26491@value{GDBN}'s built-in @code{enum} printing, this printer attempts to 26492work properly when there is some overlap between the enumeration 26493constants. @var{name} is the name of the printer and also the name of 26494the @code{enum} type to look up. 26495 26496@item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False) 26497Register @var{printer} with the pretty-printer list of @var{obj}. 26498If @var{replace} is @code{True} then any existing copy of the printer 26499is replaced. Otherwise a @code{RuntimeError} exception is raised 26500if a printer with the same name already exists. 26501@end table 26502 26503@node gdb.types 26504@subsubsection gdb.types 26505@cindex gdb.types 26506 26507This module provides a collection of utilities for working with 26508@code{gdb.Type} objects. 26509 26510@table @code 26511@item get_basic_type (@var{type}) 26512Return @var{type} with const and volatile qualifiers stripped, 26513and with typedefs and C@t{++} references converted to the underlying type. 26514 26515C@t{++} example: 26516 26517@smallexample 26518typedef const int const_int; 26519const_int foo (3); 26520const_int& foo_ref (foo); 26521int main () @{ return 0; @} 26522@end smallexample 26523 26524Then in gdb: 26525 26526@smallexample 26527(gdb) start 26528(gdb) python import gdb.types 26529(gdb) python foo_ref = gdb.parse_and_eval("foo_ref") 26530(gdb) python print gdb.types.get_basic_type(foo_ref.type) 26531int 26532@end smallexample 26533 26534@item has_field (@var{type}, @var{field}) 26535Return @code{True} if @var{type}, assumed to be a type with fields 26536(e.g., a structure or union), has field @var{field}. 26537 26538@item make_enum_dict (@var{enum_type}) 26539Return a Python @code{dictionary} type produced from @var{enum_type}. 26540 26541@item deep_items (@var{type}) 26542Returns a Python iterator similar to the standard 26543@code{gdb.Type.iteritems} method, except that the iterator returned 26544by @code{deep_items} will recursively traverse anonymous struct or 26545union fields. For example: 26546 26547@smallexample 26548struct A 26549@{ 26550 int a; 26551 union @{ 26552 int b0; 26553 int b1; 26554 @}; 26555@}; 26556@end smallexample 26557 26558@noindent 26559Then in @value{GDBN}: 26560@smallexample 26561(@value{GDBP}) python import gdb.types 26562(@value{GDBP}) python struct_a = gdb.lookup_type("struct A") 26563(@value{GDBP}) python print struct_a.keys () 26564@{['a', '']@} 26565(@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)] 26566@{['a', 'b0', 'b1']@} 26567@end smallexample 26568 26569@item get_type_recognizers () 26570Return a list of the enabled type recognizers for the current context. 26571This is called by @value{GDBN} during the type-printing process 26572(@pxref{Type Printing API}). 26573 26574@item apply_type_recognizers (recognizers, type_obj) 26575Apply the type recognizers, @var{recognizers}, to the type object 26576@var{type_obj}. If any recognizer returns a string, return that 26577string. Otherwise, return @code{None}. This is called by 26578@value{GDBN} during the type-printing process (@pxref{Type Printing 26579API}). 26580 26581@item register_type_printer (locus, printer) 26582This is a convenience function to register a type printer. 26583@var{printer} is the type printer to register. It must implement the 26584type printer protocol. @var{locus} is either a @code{gdb.Objfile}, in 26585which case the printer is registered with that objfile; a 26586@code{gdb.Progspace}, in which case the printer is registered with 26587that progspace; or @code{None}, in which case the printer is 26588registered globally. 26589 26590@item TypePrinter 26591This is a base class that implements the type printer protocol. Type 26592printers are encouraged, but not required, to derive from this class. 26593It defines a constructor: 26594 26595@defmethod TypePrinter __init__ (self, name) 26596Initialize the type printer with the given name. The new printer 26597starts in the enabled state. 26598@end defmethod 26599 26600@end table 26601 26602@node gdb.prompt 26603@subsubsection gdb.prompt 26604@cindex gdb.prompt 26605 26606This module provides a method for prompt value-substitution. 26607 26608@table @code 26609@item substitute_prompt (@var{string}) 26610Return @var{string} with escape sequences substituted by values. Some 26611escape sequences take arguments. You can specify arguments inside 26612``@{@}'' immediately following the escape sequence. 26613 26614The escape sequences you can pass to this function are: 26615 26616@table @code 26617@item \\ 26618Substitute a backslash. 26619@item \e 26620Substitute an ESC character. 26621@item \f 26622Substitute the selected frame; an argument names a frame parameter. 26623@item \n 26624Substitute a newline. 26625@item \p 26626Substitute a parameter's value; the argument names the parameter. 26627@item \r 26628Substitute a carriage return. 26629@item \t 26630Substitute the selected thread; an argument names a thread parameter. 26631@item \v 26632Substitute the version of GDB. 26633@item \w 26634Substitute the current working directory. 26635@item \[ 26636Begin a sequence of non-printing characters. These sequences are 26637typically used with the ESC character, and are not counted in the string 26638length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a 26639blue-colored ``(gdb)'' prompt where the length is five. 26640@item \] 26641End a sequence of non-printing characters. 26642@end table 26643 26644For example: 26645 26646@smallexample 26647substitute_prompt (``frame: \f, 26648 print arguments: \p@{print frame-arguments@}'') 26649@end smallexample 26650 26651@exdent will return the string: 26652 26653@smallexample 26654"frame: main, print arguments: scalars" 26655@end smallexample 26656@end table 26657 26658@node Aliases 26659@section Creating new spellings of existing commands 26660@cindex aliases for commands 26661 26662It is often useful to define alternate spellings of existing commands. 26663For example, if a new @value{GDBN} command defined in Python has 26664a long name to type, it is handy to have an abbreviated version of it 26665that involves less typing. 26666 26667@value{GDBN} itself uses aliases. For example @samp{s} is an alias 26668of the @samp{step} command even though it is otherwise an ambiguous 26669abbreviation of other commands like @samp{set} and @samp{show}. 26670 26671Aliases are also used to provide shortened or more common versions 26672of multi-word commands. For example, @value{GDBN} provides the 26673@samp{tty} alias of the @samp{set inferior-tty} command. 26674 26675You can define a new alias with the @samp{alias} command. 26676 26677@table @code 26678 26679@kindex alias 26680@item alias [-a] [--] @var{ALIAS} = @var{COMMAND} 26681 26682@end table 26683 26684@var{ALIAS} specifies the name of the new alias. 26685Each word of @var{ALIAS} must consist of letters, numbers, dashes and 26686underscores. 26687 26688@var{COMMAND} specifies the name of an existing command 26689that is being aliased. 26690 26691The @samp{-a} option specifies that the new alias is an abbreviation 26692of the command. Abbreviations are not shown in command 26693lists displayed by the @samp{help} command. 26694 26695The @samp{--} option specifies the end of options, 26696and is useful when @var{ALIAS} begins with a dash. 26697 26698Here is a simple example showing how to make an abbreviation 26699of a command so that there is less to type. 26700Suppose you were tired of typing @samp{disas}, the current 26701shortest unambiguous abbreviation of the @samp{disassemble} command 26702and you wanted an even shorter version named @samp{di}. 26703The following will accomplish this. 26704 26705@smallexample 26706(gdb) alias -a di = disas 26707@end smallexample 26708 26709Note that aliases are different from user-defined commands. 26710With a user-defined command, you also need to write documentation 26711for it with the @samp{document} command. 26712An alias automatically picks up the documentation of the existing command. 26713 26714Here is an example where we make @samp{elms} an abbreviation of 26715@samp{elements} in the @samp{set print elements} command. 26716This is to show that you can make an abbreviation of any part 26717of a command. 26718 26719@smallexample 26720(gdb) alias -a set print elms = set print elements 26721(gdb) alias -a show print elms = show print elements 26722(gdb) set p elms 20 26723(gdb) show p elms 26724Limit on string chars or array elements to print is 200. 26725@end smallexample 26726 26727Note that if you are defining an alias of a @samp{set} command, 26728and you want to have an alias for the corresponding @samp{show} 26729command, then you need to define the latter separately. 26730 26731Unambiguously abbreviated commands are allowed in @var{COMMAND} and 26732@var{ALIAS}, just as they are normally. 26733 26734@smallexample 26735(gdb) alias -a set pr elms = set p ele 26736@end smallexample 26737 26738Finally, here is an example showing the creation of a one word 26739alias for a more complex command. 26740This creates alias @samp{spe} of the command @samp{set print elements}. 26741 26742@smallexample 26743(gdb) alias spe = set print elements 26744(gdb) spe 20 26745@end smallexample 26746 26747@node Interpreters 26748@chapter Command Interpreters 26749@cindex command interpreters 26750 26751@value{GDBN} supports multiple command interpreters, and some command 26752infrastructure to allow users or user interface writers to switch 26753between interpreters or run commands in other interpreters. 26754 26755@value{GDBN} currently supports two command interpreters, the console 26756interpreter (sometimes called the command-line interpreter or @sc{cli}) 26757and the machine interface interpreter (or @sc{gdb/mi}). This manual 26758describes both of these interfaces in great detail. 26759 26760By default, @value{GDBN} will start with the console interpreter. 26761However, the user may choose to start @value{GDBN} with another 26762interpreter by specifying the @option{-i} or @option{--interpreter} 26763startup options. Defined interpreters include: 26764 26765@table @code 26766@item console 26767@cindex console interpreter 26768The traditional console or command-line interpreter. This is the most often 26769used interpreter with @value{GDBN}. With no interpreter specified at runtime, 26770@value{GDBN} will use this interpreter. 26771 26772@item mi 26773@cindex mi interpreter 26774The newest @sc{gdb/mi} interface (currently @code{mi2}). Used primarily 26775by programs wishing to use @value{GDBN} as a backend for a debugger GUI 26776or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi} 26777Interface}. 26778 26779@item mi2 26780@cindex mi2 interpreter 26781The current @sc{gdb/mi} interface. 26782 26783@item mi1 26784@cindex mi1 interpreter 26785The @sc{gdb/mi} interface included in @value{GDBN} 5.1, 5.2, and 5.3. 26786 26787@end table 26788 26789@cindex invoke another interpreter 26790The interpreter being used by @value{GDBN} may not be dynamically 26791switched at runtime. Although possible, this could lead to a very 26792precarious situation. Consider an IDE using @sc{gdb/mi}. If a user 26793enters the command "interpreter-set console" in a console view, 26794@value{GDBN} would switch to using the console interpreter, rendering 26795the IDE inoperable! 26796 26797@kindex interpreter-exec 26798Although you may only choose a single interpreter at startup, you may execute 26799commands in any interpreter from the current interpreter using the appropriate 26800command. If you are running the console interpreter, simply use the 26801@code{interpreter-exec} command: 26802 26803@smallexample 26804interpreter-exec mi "-data-list-register-names" 26805@end smallexample 26806 26807@sc{gdb/mi} has a similar command, although it is only available in versions of 26808@value{GDBN} which support @sc{gdb/mi} version 2 (or greater). 26809 26810@node TUI 26811@chapter @value{GDBN} Text User Interface 26812@cindex TUI 26813@cindex Text User Interface 26814 26815@menu 26816* TUI Overview:: TUI overview 26817* TUI Keys:: TUI key bindings 26818* TUI Single Key Mode:: TUI single key mode 26819* TUI Commands:: TUI-specific commands 26820* TUI Configuration:: TUI configuration variables 26821@end menu 26822 26823The @value{GDBN} Text User Interface (TUI) is a terminal 26824interface which uses the @code{curses} library to show the source 26825file, the assembly output, the program registers and @value{GDBN} 26826commands in separate text windows. The TUI mode is supported only 26827on platforms where a suitable version of the @code{curses} library 26828is available. 26829 26830The TUI mode is enabled by default when you invoke @value{GDBN} as 26831@samp{@value{GDBP} -tui}. 26832You can also switch in and out of TUI mode while @value{GDBN} runs by 26833using various TUI commands and key bindings, such as @kbd{C-x C-a}. 26834@xref{TUI Keys, ,TUI Key Bindings}. 26835 26836@node TUI Overview 26837@section TUI Overview 26838 26839In TUI mode, @value{GDBN} can display several text windows: 26840 26841@table @emph 26842@item command 26843This window is the @value{GDBN} command window with the @value{GDBN} 26844prompt and the @value{GDBN} output. The @value{GDBN} input is still 26845managed using readline. 26846 26847@item source 26848The source window shows the source file of the program. The current 26849line and active breakpoints are displayed in this window. 26850 26851@item assembly 26852The assembly window shows the disassembly output of the program. 26853 26854@item register 26855This window shows the processor registers. Registers are highlighted 26856when their values change. 26857@end table 26858 26859The source and assembly windows show the current program position 26860by highlighting the current line and marking it with a @samp{>} marker. 26861Breakpoints are indicated with two markers. The first marker 26862indicates the breakpoint type: 26863 26864@table @code 26865@item B 26866Breakpoint which was hit at least once. 26867 26868@item b 26869Breakpoint which was never hit. 26870 26871@item H 26872Hardware breakpoint which was hit at least once. 26873 26874@item h 26875Hardware breakpoint which was never hit. 26876@end table 26877 26878The second marker indicates whether the breakpoint is enabled or not: 26879 26880@table @code 26881@item + 26882Breakpoint is enabled. 26883 26884@item - 26885Breakpoint is disabled. 26886@end table 26887 26888The source, assembly and register windows are updated when the current 26889thread changes, when the frame changes, or when the program counter 26890changes. 26891 26892These windows are not all visible at the same time. The command 26893window is always visible. The others can be arranged in several 26894layouts: 26895 26896@itemize @bullet 26897@item 26898source only, 26899 26900@item 26901assembly only, 26902 26903@item 26904source and assembly, 26905 26906@item 26907source and registers, or 26908 26909@item 26910assembly and registers. 26911@end itemize 26912 26913A status line above the command window shows the following information: 26914 26915@table @emph 26916@item target 26917Indicates the current @value{GDBN} target. 26918(@pxref{Targets, ,Specifying a Debugging Target}). 26919 26920@item process 26921Gives the current process or thread number. 26922When no process is being debugged, this field is set to @code{No process}. 26923 26924@item function 26925Gives the current function name for the selected frame. 26926The name is demangled if demangling is turned on (@pxref{Print Settings}). 26927When there is no symbol corresponding to the current program counter, 26928the string @code{??} is displayed. 26929 26930@item line 26931Indicates the current line number for the selected frame. 26932When the current line number is not known, the string @code{??} is displayed. 26933 26934@item pc 26935Indicates the current program counter address. 26936@end table 26937 26938@node TUI Keys 26939@section TUI Key Bindings 26940@cindex TUI key bindings 26941 26942The TUI installs several key bindings in the readline keymaps 26943@ifset SYSTEM_READLINE 26944(@pxref{Command Line Editing, , , rluserman, GNU Readline Library}). 26945@end ifset 26946@ifclear SYSTEM_READLINE 26947(@pxref{Command Line Editing}). 26948@end ifclear 26949The following key bindings are installed for both TUI mode and the 26950@value{GDBN} standard mode. 26951 26952@table @kbd 26953@kindex C-x C-a 26954@item C-x C-a 26955@kindex C-x a 26956@itemx C-x a 26957@kindex C-x A 26958@itemx C-x A 26959Enter or leave the TUI mode. When leaving the TUI mode, 26960the curses window management stops and @value{GDBN} operates using 26961its standard mode, writing on the terminal directly. When reentering 26962the TUI mode, control is given back to the curses windows. 26963The screen is then refreshed. 26964 26965@kindex C-x 1 26966@item C-x 1 26967Use a TUI layout with only one window. The layout will 26968either be @samp{source} or @samp{assembly}. When the TUI mode 26969is not active, it will switch to the TUI mode. 26970 26971Think of this key binding as the Emacs @kbd{C-x 1} binding. 26972 26973@kindex C-x 2 26974@item C-x 2 26975Use a TUI layout with at least two windows. When the current 26976layout already has two windows, the next layout with two windows is used. 26977When a new layout is chosen, one window will always be common to the 26978previous layout and the new one. 26979 26980Think of it as the Emacs @kbd{C-x 2} binding. 26981 26982@kindex C-x o 26983@item C-x o 26984Change the active window. The TUI associates several key bindings 26985(like scrolling and arrow keys) with the active window. This command 26986gives the focus to the next TUI window. 26987 26988Think of it as the Emacs @kbd{C-x o} binding. 26989 26990@kindex C-x s 26991@item C-x s 26992Switch in and out of the TUI SingleKey mode that binds single 26993keys to @value{GDBN} commands (@pxref{TUI Single Key Mode}). 26994@end table 26995 26996The following key bindings only work in the TUI mode: 26997 26998@table @asis 26999@kindex PgUp 27000@item @key{PgUp} 27001Scroll the active window one page up. 27002 27003@kindex PgDn 27004@item @key{PgDn} 27005Scroll the active window one page down. 27006 27007@kindex Up 27008@item @key{Up} 27009Scroll the active window one line up. 27010 27011@kindex Down 27012@item @key{Down} 27013Scroll the active window one line down. 27014 27015@kindex Left 27016@item @key{Left} 27017Scroll the active window one column left. 27018 27019@kindex Right 27020@item @key{Right} 27021Scroll the active window one column right. 27022 27023@kindex C-L 27024@item @kbd{C-L} 27025Refresh the screen. 27026@end table 27027 27028Because the arrow keys scroll the active window in the TUI mode, they 27029are not available for their normal use by readline unless the command 27030window has the focus. When another window is active, you must use 27031other readline key bindings such as @kbd{C-p}, @kbd{C-n}, @kbd{C-b} 27032and @kbd{C-f} to control the command window. 27033 27034@node TUI Single Key Mode 27035@section TUI Single Key Mode 27036@cindex TUI single key mode 27037 27038The TUI also provides a @dfn{SingleKey} mode, which binds several 27039frequently used @value{GDBN} commands to single keys. Type @kbd{C-x s} to 27040switch into this mode, where the following key bindings are used: 27041 27042@table @kbd 27043@kindex c @r{(SingleKey TUI key)} 27044@item c 27045continue 27046 27047@kindex d @r{(SingleKey TUI key)} 27048@item d 27049down 27050 27051@kindex f @r{(SingleKey TUI key)} 27052@item f 27053finish 27054 27055@kindex n @r{(SingleKey TUI key)} 27056@item n 27057next 27058 27059@kindex q @r{(SingleKey TUI key)} 27060@item q 27061exit the SingleKey mode. 27062 27063@kindex r @r{(SingleKey TUI key)} 27064@item r 27065run 27066 27067@kindex s @r{(SingleKey TUI key)} 27068@item s 27069step 27070 27071@kindex u @r{(SingleKey TUI key)} 27072@item u 27073up 27074 27075@kindex v @r{(SingleKey TUI key)} 27076@item v 27077info locals 27078 27079@kindex w @r{(SingleKey TUI key)} 27080@item w 27081where 27082@end table 27083 27084Other keys temporarily switch to the @value{GDBN} command prompt. 27085The key that was pressed is inserted in the editing buffer so that 27086it is possible to type most @value{GDBN} commands without interaction 27087with the TUI SingleKey mode. Once the command is entered the TUI 27088SingleKey mode is restored. The only way to permanently leave 27089this mode is by typing @kbd{q} or @kbd{C-x s}. 27090 27091 27092@node TUI Commands 27093@section TUI-specific Commands 27094@cindex TUI commands 27095 27096The TUI has specific commands to control the text windows. 27097These commands are always available, even when @value{GDBN} is not in 27098the TUI mode. When @value{GDBN} is in the standard mode, most 27099of these commands will automatically switch to the TUI mode. 27100 27101Note that if @value{GDBN}'s @code{stdout} is not connected to a 27102terminal, or @value{GDBN} has been started with the machine interface 27103interpreter (@pxref{GDB/MI, ,The @sc{gdb/mi} Interface}), most of 27104these commands will fail with an error, because it would not be 27105possible or desirable to enable curses window management. 27106 27107@table @code 27108@item info win 27109@kindex info win 27110List and give the size of all displayed windows. 27111 27112@item layout next 27113@kindex layout 27114Display the next layout. 27115 27116@item layout prev 27117Display the previous layout. 27118 27119@item layout src 27120Display the source window only. 27121 27122@item layout asm 27123Display the assembly window only. 27124 27125@item layout split 27126Display the source and assembly window. 27127 27128@item layout regs 27129Display the register window together with the source or assembly window. 27130 27131@item focus next 27132@kindex focus 27133Make the next window active for scrolling. 27134 27135@item focus prev 27136Make the previous window active for scrolling. 27137 27138@item focus src 27139Make the source window active for scrolling. 27140 27141@item focus asm 27142Make the assembly window active for scrolling. 27143 27144@item focus regs 27145Make the register window active for scrolling. 27146 27147@item focus cmd 27148Make the command window active for scrolling. 27149 27150@item refresh 27151@kindex refresh 27152Refresh the screen. This is similar to typing @kbd{C-L}. 27153 27154@item tui reg float 27155@kindex tui reg 27156Show the floating point registers in the register window. 27157 27158@item tui reg general 27159Show the general registers in the register window. 27160 27161@item tui reg next 27162Show the next register group. The list of register groups as well as 27163their order is target specific. The predefined register groups are the 27164following: @code{general}, @code{float}, @code{system}, @code{vector}, 27165@code{all}, @code{save}, @code{restore}. 27166 27167@item tui reg system 27168Show the system registers in the register window. 27169 27170@item update 27171@kindex update 27172Update the source window and the current execution point. 27173 27174@item winheight @var{name} +@var{count} 27175@itemx winheight @var{name} -@var{count} 27176@kindex winheight 27177Change the height of the window @var{name} by @var{count} 27178lines. Positive counts increase the height, while negative counts 27179decrease it. 27180 27181@item tabset @var{nchars} 27182@kindex tabset 27183Set the width of tab stops to be @var{nchars} characters. 27184@end table 27185 27186@node TUI Configuration 27187@section TUI Configuration Variables 27188@cindex TUI configuration variables 27189 27190Several configuration variables control the appearance of TUI windows. 27191 27192@table @code 27193@item set tui border-kind @var{kind} 27194@kindex set tui border-kind 27195Select the border appearance for the source, assembly and register windows. 27196The possible values are the following: 27197@table @code 27198@item space 27199Use a space character to draw the border. 27200 27201@item ascii 27202Use @sc{ascii} characters @samp{+}, @samp{-} and @samp{|} to draw the border. 27203 27204@item acs 27205Use the Alternate Character Set to draw the border. The border is 27206drawn using character line graphics if the terminal supports them. 27207@end table 27208 27209@item set tui border-mode @var{mode} 27210@kindex set tui border-mode 27211@itemx set tui active-border-mode @var{mode} 27212@kindex set tui active-border-mode 27213Select the display attributes for the borders of the inactive windows 27214or the active window. The @var{mode} can be one of the following: 27215@table @code 27216@item normal 27217Use normal attributes to display the border. 27218 27219@item standout 27220Use standout mode. 27221 27222@item reverse 27223Use reverse video mode. 27224 27225@item half 27226Use half bright mode. 27227 27228@item half-standout 27229Use half bright and standout mode. 27230 27231@item bold 27232Use extra bright or bold mode. 27233 27234@item bold-standout 27235Use extra bright or bold and standout mode. 27236@end table 27237@end table 27238 27239@node Emacs 27240@chapter Using @value{GDBN} under @sc{gnu} Emacs 27241 27242@cindex Emacs 27243@cindex @sc{gnu} Emacs 27244A special interface allows you to use @sc{gnu} Emacs to view (and 27245edit) the source files for the program you are debugging with 27246@value{GDBN}. 27247 27248To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the 27249executable file you want to debug as an argument. This command starts 27250@value{GDBN} as a subprocess of Emacs, with input and output through a newly 27251created Emacs buffer. 27252@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.) 27253 27254Running @value{GDBN} under Emacs can be just like running @value{GDBN} normally except for two 27255things: 27256 27257@itemize @bullet 27258@item 27259All ``terminal'' input and output goes through an Emacs buffer, called 27260the GUD buffer. 27261 27262This applies both to @value{GDBN} commands and their output, and to the input 27263and output done by the program you are debugging. 27264 27265This is useful because it means that you can copy the text of previous 27266commands and input them again; you can even use parts of the output 27267in this way. 27268 27269All the facilities of Emacs' Shell mode are available for interacting 27270with your program. In particular, you can send signals the usual 27271way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a 27272stop. 27273 27274@item 27275@value{GDBN} displays source code through Emacs. 27276 27277Each time @value{GDBN} displays a stack frame, Emacs automatically finds the 27278source file for that frame and puts an arrow (@samp{=>}) at the 27279left margin of the current line. Emacs uses a separate buffer for 27280source display, and splits the screen to show both your @value{GDBN} session 27281and the source. 27282 27283Explicit @value{GDBN} @code{list} or search commands still produce output as 27284usual, but you probably have no reason to use them from Emacs. 27285@end itemize 27286 27287We call this @dfn{text command mode}. Emacs 22.1, and later, also uses 27288a graphical mode, enabled by default, which provides further buffers 27289that can control the execution and describe the state of your program. 27290@xref{GDB Graphical Interface,,, Emacs, The @sc{gnu} Emacs Manual}. 27291 27292If you specify an absolute file name when prompted for the @kbd{M-x 27293gdb} argument, then Emacs sets your current working directory to where 27294your program resides. If you only specify the file name, then Emacs 27295sets your current working directory to the directory associated 27296with the previous buffer. In this case, @value{GDBN} may find your 27297program by searching your environment's @code{PATH} variable, but on 27298some operating systems it might not find the source. So, although the 27299@value{GDBN} input and output session proceeds normally, the auxiliary 27300buffer does not display the current source and line of execution. 27301 27302The initial working directory of @value{GDBN} is printed on the top 27303line of the GUD buffer and this serves as a default for the commands 27304that specify files for @value{GDBN} to operate on. @xref{Files, 27305,Commands to Specify Files}. 27306 27307By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you 27308need to call @value{GDBN} by a different name (for example, if you 27309keep several configurations around, with different names) you can 27310customize the Emacs variable @code{gud-gdb-command-name} to run the 27311one you want. 27312 27313In the GUD buffer, you can use these special Emacs commands in 27314addition to the standard Shell mode commands: 27315 27316@table @kbd 27317@item C-h m 27318Describe the features of Emacs' GUD Mode. 27319 27320@item C-c C-s 27321Execute to another source line, like the @value{GDBN} @code{step} command; also 27322update the display window to show the current file and location. 27323 27324@item C-c C-n 27325Execute to next source line in this function, skipping all function 27326calls, like the @value{GDBN} @code{next} command. Then update the display window 27327to show the current file and location. 27328 27329@item C-c C-i 27330Execute one instruction, like the @value{GDBN} @code{stepi} command; update 27331display window accordingly. 27332 27333@item C-c C-f 27334Execute until exit from the selected stack frame, like the @value{GDBN} 27335@code{finish} command. 27336 27337@item C-c C-r 27338Continue execution of your program, like the @value{GDBN} @code{continue} 27339command. 27340 27341@item C-c < 27342Go up the number of frames indicated by the numeric argument 27343(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}), 27344like the @value{GDBN} @code{up} command. 27345 27346@item C-c > 27347Go down the number of frames indicated by the numeric argument, like the 27348@value{GDBN} @code{down} command. 27349@end table 27350 27351In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break}) 27352tells @value{GDBN} to set a breakpoint on the source line point is on. 27353 27354In text command mode, if you type @kbd{M-x speedbar}, Emacs displays a 27355separate frame which shows a backtrace when the GUD buffer is current. 27356Move point to any frame in the stack and type @key{RET} to make it 27357become the current frame and display the associated source in the 27358source buffer. Alternatively, click @kbd{Mouse-2} to make the 27359selected frame become the current one. In graphical mode, the 27360speedbar displays watch expressions. 27361 27362If you accidentally delete the source-display buffer, an easy way to get 27363it back is to type the command @code{f} in the @value{GDBN} buffer, to 27364request a frame display; when you run under Emacs, this recreates 27365the source buffer if necessary to show you the context of the current 27366frame. 27367 27368The source files displayed in Emacs are in ordinary Emacs buffers 27369which are visiting the source files in the usual way. You can edit 27370the files with these buffers if you wish; but keep in mind that @value{GDBN} 27371communicates with Emacs in terms of line numbers. If you add or 27372delete lines from the text, the line numbers that @value{GDBN} knows cease 27373to correspond properly with the code. 27374 27375A more detailed description of Emacs' interaction with @value{GDBN} is 27376given in the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} 27377Emacs Manual}). 27378 27379@node GDB/MI 27380@chapter The @sc{gdb/mi} Interface 27381 27382@unnumberedsec Function and Purpose 27383 27384@cindex @sc{gdb/mi}, its purpose 27385@sc{gdb/mi} is a line based machine oriented text interface to 27386@value{GDBN} and is activated by specifying using the 27387@option{--interpreter} command line option (@pxref{Mode Options}). It 27388is specifically intended to support the development of systems which 27389use the debugger as just one small component of a larger system. 27390 27391This chapter is a specification of the @sc{gdb/mi} interface. It is written 27392in the form of a reference manual. 27393 27394Note that @sc{gdb/mi} is still under construction, so some of the 27395features described below are incomplete and subject to change 27396(@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}). 27397 27398@unnumberedsec Notation and Terminology 27399 27400@cindex notational conventions, for @sc{gdb/mi} 27401This chapter uses the following notation: 27402 27403@itemize @bullet 27404@item 27405@code{|} separates two alternatives. 27406 27407@item 27408@code{[ @var{something} ]} indicates that @var{something} is optional: 27409it may or may not be given. 27410 27411@item 27412@code{( @var{group} )*} means that @var{group} inside the parentheses 27413may repeat zero or more times. 27414 27415@item 27416@code{( @var{group} )+} means that @var{group} inside the parentheses 27417may repeat one or more times. 27418 27419@item 27420@code{"@var{string}"} means a literal @var{string}. 27421@end itemize 27422 27423@ignore 27424@heading Dependencies 27425@end ignore 27426 27427@menu 27428* GDB/MI General Design:: 27429* GDB/MI Command Syntax:: 27430* GDB/MI Compatibility with CLI:: 27431* GDB/MI Development and Front Ends:: 27432* GDB/MI Output Records:: 27433* GDB/MI Simple Examples:: 27434* GDB/MI Command Description Format:: 27435* GDB/MI Breakpoint Commands:: 27436* GDB/MI Catchpoint Commands:: 27437* GDB/MI Program Context:: 27438* GDB/MI Thread Commands:: 27439* GDB/MI Ada Tasking Commands:: 27440* GDB/MI Program Execution:: 27441* GDB/MI Stack Manipulation:: 27442* GDB/MI Variable Objects:: 27443* GDB/MI Data Manipulation:: 27444* GDB/MI Tracepoint Commands:: 27445* GDB/MI Symbol Query:: 27446* GDB/MI File Commands:: 27447@ignore 27448* GDB/MI Kod Commands:: 27449* GDB/MI Memory Overlay Commands:: 27450* GDB/MI Signal Handling Commands:: 27451@end ignore 27452* GDB/MI Target Manipulation:: 27453* GDB/MI File Transfer Commands:: 27454* GDB/MI Miscellaneous Commands:: 27455@end menu 27456 27457@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 27458@node GDB/MI General Design 27459@section @sc{gdb/mi} General Design 27460@cindex GDB/MI General Design 27461 27462Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three 27463parts---commands sent to @value{GDBN}, responses to those commands 27464and notifications. Each command results in exactly one response, 27465indicating either successful completion of the command, or an error. 27466For the commands that do not resume the target, the response contains the 27467requested information. For the commands that resume the target, the 27468response only indicates whether the target was successfully resumed. 27469Notifications is the mechanism for reporting changes in the state of the 27470target, or in @value{GDBN} state, that cannot conveniently be associated with 27471a command and reported as part of that command response. 27472 27473The important examples of notifications are: 27474@itemize @bullet 27475 27476@item 27477Exec notifications. These are used to report changes in 27478target state---when a target is resumed, or stopped. It would not 27479be feasible to include this information in response of resuming 27480commands, because one resume commands can result in multiple events in 27481different threads. Also, quite some time may pass before any event 27482happens in the target, while a frontend needs to know whether the resuming 27483command itself was successfully executed. 27484 27485@item 27486Console output, and status notifications. Console output 27487notifications are used to report output of CLI commands, as well as 27488diagnostics for other commands. Status notifications are used to 27489report the progress of a long-running operation. Naturally, including 27490this information in command response would mean no output is produced 27491until the command is finished, which is undesirable. 27492 27493@item 27494General notifications. Commands may have various side effects on 27495the @value{GDBN} or target state beyond their official purpose. For example, 27496a command may change the selected thread. Although such changes can 27497be included in command response, using notification allows for more 27498orthogonal frontend design. 27499 27500@end itemize 27501 27502There's no guarantee that whenever an MI command reports an error, 27503@value{GDBN} or the target are in any specific state, and especially, 27504the state is not reverted to the state before the MI command was 27505processed. Therefore, whenever an MI command results in an error, 27506we recommend that the frontend refreshes all the information shown in 27507the user interface. 27508 27509 27510@menu 27511* Context management:: 27512* Asynchronous and non-stop modes:: 27513* Thread groups:: 27514@end menu 27515 27516@node Context management 27517@subsection Context management 27518 27519In most cases when @value{GDBN} accesses the target, this access is 27520done in context of a specific thread and frame (@pxref{Frames}). 27521Often, even when accessing global data, the target requires that a thread 27522be specified. The CLI interface maintains the selected thread and frame, 27523and supplies them to target on each command. This is convenient, 27524because a command line user would not want to specify that information 27525explicitly on each command, and because user interacts with 27526@value{GDBN} via a single terminal, so no confusion is possible as 27527to what thread and frame are the current ones. 27528 27529In the case of MI, the concept of selected thread and frame is less 27530useful. First, a frontend can easily remember this information 27531itself. Second, a graphical frontend can have more than one window, 27532each one used for debugging a different thread, and the frontend might 27533want to access additional threads for internal purposes. This 27534increases the risk that by relying on implicitly selected thread, the 27535frontend may be operating on a wrong one. Therefore, each MI command 27536should explicitly specify which thread and frame to operate on. To 27537make it possible, each MI command accepts the @samp{--thread} and 27538@samp{--frame} options, the value to each is @value{GDBN} identifier 27539for thread and frame to operate on. 27540 27541Usually, each top-level window in a frontend allows the user to select 27542a thread and a frame, and remembers the user selection for further 27543operations. However, in some cases @value{GDBN} may suggest that the 27544current thread be changed. For example, when stopping on a breakpoint 27545it is reasonable to switch to the thread where breakpoint is hit. For 27546another example, if the user issues the CLI @samp{thread} command via 27547the frontend, it is desirable to change the frontend's selected thread to the 27548one specified by user. @value{GDBN} communicates the suggestion to 27549change current thread using the @samp{=thread-selected} notification. 27550No such notification is available for the selected frame at the moment. 27551 27552Note that historically, MI shares the selected thread with CLI, so 27553frontends used the @code{-thread-select} to execute commands in the 27554right context. However, getting this to work right is cumbersome. The 27555simplest way is for frontend to emit @code{-thread-select} command 27556before every command. This doubles the number of commands that need 27557to be sent. The alternative approach is to suppress @code{-thread-select} 27558if the selected thread in @value{GDBN} is supposed to be identical to the 27559thread the frontend wants to operate on. However, getting this 27560optimization right can be tricky. In particular, if the frontend 27561sends several commands to @value{GDBN}, and one of the commands changes the 27562selected thread, then the behaviour of subsequent commands will 27563change. So, a frontend should either wait for response from such 27564problematic commands, or explicitly add @code{-thread-select} for 27565all subsequent commands. No frontend is known to do this exactly 27566right, so it is suggested to just always pass the @samp{--thread} and 27567@samp{--frame} options. 27568 27569@node Asynchronous and non-stop modes 27570@subsection Asynchronous command execution and non-stop mode 27571 27572On some targets, @value{GDBN} is capable of processing MI commands 27573even while the target is running. This is called @dfn{asynchronous 27574command execution} (@pxref{Background Execution}). The frontend may 27575specify a preferrence for asynchronous execution using the 27576@code{-gdb-set target-async 1} command, which should be emitted before 27577either running the executable or attaching to the target. After the 27578frontend has started the executable or attached to the target, it can 27579find if asynchronous execution is enabled using the 27580@code{-list-target-features} command. 27581 27582Even if @value{GDBN} can accept a command while target is running, 27583many commands that access the target do not work when the target is 27584running. Therefore, asynchronous command execution is most useful 27585when combined with non-stop mode (@pxref{Non-Stop Mode}). Then, 27586it is possible to examine the state of one thread, while other threads 27587are running. 27588 27589When a given thread is running, MI commands that try to access the 27590target in the context of that thread may not work, or may work only on 27591some targets. In particular, commands that try to operate on thread's 27592stack will not work, on any target. Commands that read memory, or 27593modify breakpoints, may work or not work, depending on the target. Note 27594that even commands that operate on global state, such as @code{print}, 27595@code{set}, and breakpoint commands, still access the target in the 27596context of a specific thread, so frontend should try to find a 27597stopped thread and perform the operation on that thread (using the 27598@samp{--thread} option). 27599 27600Which commands will work in the context of a running thread is 27601highly target dependent. However, the two commands 27602@code{-exec-interrupt}, to stop a thread, and @code{-thread-info}, 27603to find the state of a thread, will always work. 27604 27605@node Thread groups 27606@subsection Thread groups 27607@value{GDBN} may be used to debug several processes at the same time. 27608On some platfroms, @value{GDBN} may support debugging of several 27609hardware systems, each one having several cores with several different 27610processes running on each core. This section describes the MI 27611mechanism to support such debugging scenarios. 27612 27613The key observation is that regardless of the structure of the 27614target, MI can have a global list of threads, because most commands that 27615accept the @samp{--thread} option do not need to know what process that 27616thread belongs to. Therefore, it is not necessary to introduce 27617neither additional @samp{--process} option, nor an notion of the 27618current process in the MI interface. The only strictly new feature 27619that is required is the ability to find how the threads are grouped 27620into processes. 27621 27622To allow the user to discover such grouping, and to support arbitrary 27623hierarchy of machines/cores/processes, MI introduces the concept of a 27624@dfn{thread group}. Thread group is a collection of threads and other 27625thread groups. A thread group always has a string identifier, a type, 27626and may have additional attributes specific to the type. A new 27627command, @code{-list-thread-groups}, returns the list of top-level 27628thread groups, which correspond to processes that @value{GDBN} is 27629debugging at the moment. By passing an identifier of a thread group 27630to the @code{-list-thread-groups} command, it is possible to obtain 27631the members of specific thread group. 27632 27633To allow the user to easily discover processes, and other objects, he 27634wishes to debug, a concept of @dfn{available thread group} is 27635introduced. Available thread group is an thread group that 27636@value{GDBN} is not debugging, but that can be attached to, using the 27637@code{-target-attach} command. The list of available top-level thread 27638groups can be obtained using @samp{-list-thread-groups --available}. 27639In general, the content of a thread group may be only retrieved only 27640after attaching to that thread group. 27641 27642Thread groups are related to inferiors (@pxref{Inferiors and 27643Programs}). Each inferior corresponds to a thread group of a special 27644type @samp{process}, and some additional operations are permitted on 27645such thread groups. 27646 27647@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 27648@node GDB/MI Command Syntax 27649@section @sc{gdb/mi} Command Syntax 27650 27651@menu 27652* GDB/MI Input Syntax:: 27653* GDB/MI Output Syntax:: 27654@end menu 27655 27656@node GDB/MI Input Syntax 27657@subsection @sc{gdb/mi} Input Syntax 27658 27659@cindex input syntax for @sc{gdb/mi} 27660@cindex @sc{gdb/mi}, input syntax 27661@table @code 27662@item @var{command} @expansion{} 27663@code{@var{cli-command} | @var{mi-command}} 27664 27665@item @var{cli-command} @expansion{} 27666@code{[ @var{token} ] @var{cli-command} @var{nl}}, where 27667@var{cli-command} is any existing @value{GDBN} CLI command. 27668 27669@item @var{mi-command} @expansion{} 27670@code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )* 27671@code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}} 27672 27673@item @var{token} @expansion{} 27674"any sequence of digits" 27675 27676@item @var{option} @expansion{} 27677@code{"-" @var{parameter} [ " " @var{parameter} ]} 27678 27679@item @var{parameter} @expansion{} 27680@code{@var{non-blank-sequence} | @var{c-string}} 27681 27682@item @var{operation} @expansion{} 27683@emph{any of the operations described in this chapter} 27684 27685@item @var{non-blank-sequence} @expansion{} 27686@emph{anything, provided it doesn't contain special characters such as 27687"-", @var{nl}, """ and of course " "} 27688 27689@item @var{c-string} @expansion{} 27690@code{""" @var{seven-bit-iso-c-string-content} """} 27691 27692@item @var{nl} @expansion{} 27693@code{CR | CR-LF} 27694@end table 27695 27696@noindent 27697Notes: 27698 27699@itemize @bullet 27700@item 27701The CLI commands are still handled by the @sc{mi} interpreter; their 27702output is described below. 27703 27704@item 27705The @code{@var{token}}, when present, is passed back when the command 27706finishes. 27707 27708@item 27709Some @sc{mi} commands accept optional arguments as part of the parameter 27710list. Each option is identified by a leading @samp{-} (dash) and may be 27711followed by an optional argument parameter. Options occur first in the 27712parameter list and can be delimited from normal parameters using 27713@samp{--} (this is useful when some parameters begin with a dash). 27714@end itemize 27715 27716Pragmatics: 27717 27718@itemize @bullet 27719@item 27720We want easy access to the existing CLI syntax (for debugging). 27721 27722@item 27723We want it to be easy to spot a @sc{mi} operation. 27724@end itemize 27725 27726@node GDB/MI Output Syntax 27727@subsection @sc{gdb/mi} Output Syntax 27728 27729@cindex output syntax of @sc{gdb/mi} 27730@cindex @sc{gdb/mi}, output syntax 27731The output from @sc{gdb/mi} consists of zero or more out-of-band records 27732followed, optionally, by a single result record. This result record 27733is for the most recent command. The sequence of output records is 27734terminated by @samp{(gdb)}. 27735 27736If an input command was prefixed with a @code{@var{token}} then the 27737corresponding output for that command will also be prefixed by that same 27738@var{token}. 27739 27740@table @code 27741@item @var{output} @expansion{} 27742@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}} 27743 27744@item @var{result-record} @expansion{} 27745@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}} 27746 27747@item @var{out-of-band-record} @expansion{} 27748@code{@var{async-record} | @var{stream-record}} 27749 27750@item @var{async-record} @expansion{} 27751@code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}} 27752 27753@item @var{exec-async-output} @expansion{} 27754@code{[ @var{token} ] "*" @var{async-output}} 27755 27756@item @var{status-async-output} @expansion{} 27757@code{[ @var{token} ] "+" @var{async-output}} 27758 27759@item @var{notify-async-output} @expansion{} 27760@code{[ @var{token} ] "=" @var{async-output}} 27761 27762@item @var{async-output} @expansion{} 27763@code{@var{async-class} ( "," @var{result} )* @var{nl}} 27764 27765@item @var{result-class} @expansion{} 27766@code{"done" | "running" | "connected" | "error" | "exit"} 27767 27768@item @var{async-class} @expansion{} 27769@code{"stopped" | @var{others}} (where @var{others} will be added 27770depending on the needs---this is still in development). 27771 27772@item @var{result} @expansion{} 27773@code{ @var{variable} "=" @var{value}} 27774 27775@item @var{variable} @expansion{} 27776@code{ @var{string} } 27777 27778@item @var{value} @expansion{} 27779@code{ @var{const} | @var{tuple} | @var{list} } 27780 27781@item @var{const} @expansion{} 27782@code{@var{c-string}} 27783 27784@item @var{tuple} @expansion{} 27785@code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" } 27786 27787@item @var{list} @expansion{} 27788@code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "[" 27789@var{result} ( "," @var{result} )* "]" } 27790 27791@item @var{stream-record} @expansion{} 27792@code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}} 27793 27794@item @var{console-stream-output} @expansion{} 27795@code{"~" @var{c-string}} 27796 27797@item @var{target-stream-output} @expansion{} 27798@code{"@@" @var{c-string}} 27799 27800@item @var{log-stream-output} @expansion{} 27801@code{"&" @var{c-string}} 27802 27803@item @var{nl} @expansion{} 27804@code{CR | CR-LF} 27805 27806@item @var{token} @expansion{} 27807@emph{any sequence of digits}. 27808@end table 27809 27810@noindent 27811Notes: 27812 27813@itemize @bullet 27814@item 27815All output sequences end in a single line containing a period. 27816 27817@item 27818The @code{@var{token}} is from the corresponding request. Note that 27819for all async output, while the token is allowed by the grammar and 27820may be output by future versions of @value{GDBN} for select async 27821output messages, it is generally omitted. Frontends should treat 27822all async output as reporting general changes in the state of the 27823target and there should be no need to associate async output to any 27824prior command. 27825 27826@item 27827@cindex status output in @sc{gdb/mi} 27828@var{status-async-output} contains on-going status information about the 27829progress of a slow operation. It can be discarded. All status output is 27830prefixed by @samp{+}. 27831 27832@item 27833@cindex async output in @sc{gdb/mi} 27834@var{exec-async-output} contains asynchronous state change on the target 27835(stopped, started, disappeared). All async output is prefixed by 27836@samp{*}. 27837 27838@item 27839@cindex notify output in @sc{gdb/mi} 27840@var{notify-async-output} contains supplementary information that the 27841client should handle (e.g., a new breakpoint information). All notify 27842output is prefixed by @samp{=}. 27843 27844@item 27845@cindex console output in @sc{gdb/mi} 27846@var{console-stream-output} is output that should be displayed as is in the 27847console. It is the textual response to a CLI command. All the console 27848output is prefixed by @samp{~}. 27849 27850@item 27851@cindex target output in @sc{gdb/mi} 27852@var{target-stream-output} is the output produced by the target program. 27853All the target output is prefixed by @samp{@@}. 27854 27855@item 27856@cindex log output in @sc{gdb/mi} 27857@var{log-stream-output} is output text coming from @value{GDBN}'s internals, for 27858instance messages that should be displayed as part of an error log. All 27859the log output is prefixed by @samp{&}. 27860 27861@item 27862@cindex list output in @sc{gdb/mi} 27863New @sc{gdb/mi} commands should only output @var{lists} containing 27864@var{values}. 27865 27866 27867@end itemize 27868 27869@xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more 27870details about the various output records. 27871 27872@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 27873@node GDB/MI Compatibility with CLI 27874@section @sc{gdb/mi} Compatibility with CLI 27875 27876@cindex compatibility, @sc{gdb/mi} and CLI 27877@cindex @sc{gdb/mi}, compatibility with CLI 27878 27879For the developers convenience CLI commands can be entered directly, 27880but there may be some unexpected behaviour. For example, commands 27881that query the user will behave as if the user replied yes, breakpoint 27882command lists are not executed and some CLI commands, such as 27883@code{if}, @code{when} and @code{define}, prompt for further input with 27884@samp{>}, which is not valid MI output. 27885 27886This feature may be removed at some stage in the future and it is 27887recommended that front ends use the @code{-interpreter-exec} command 27888(@pxref{-interpreter-exec}). 27889 27890@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 27891@node GDB/MI Development and Front Ends 27892@section @sc{gdb/mi} Development and Front Ends 27893@cindex @sc{gdb/mi} development 27894 27895The application which takes the MI output and presents the state of the 27896program being debugged to the user is called a @dfn{front end}. 27897 27898Although @sc{gdb/mi} is still incomplete, it is currently being used 27899by a variety of front ends to @value{GDBN}. This makes it difficult 27900to introduce new functionality without breaking existing usage. This 27901section tries to minimize the problems by describing how the protocol 27902might change. 27903 27904Some changes in MI need not break a carefully designed front end, and 27905for these the MI version will remain unchanged. The following is a 27906list of changes that may occur within one level, so front ends should 27907parse MI output in a way that can handle them: 27908 27909@itemize @bullet 27910@item 27911New MI commands may be added. 27912 27913@item 27914New fields may be added to the output of any MI command. 27915 27916@item 27917The range of values for fields with specified values, e.g., 27918@code{in_scope} (@pxref{-var-update}) may be extended. 27919 27920@c The format of field's content e.g type prefix, may change so parse it 27921@c at your own risk. Yes, in general? 27922 27923@c The order of fields may change? Shouldn't really matter but it might 27924@c resolve inconsistencies. 27925@end itemize 27926 27927If the changes are likely to break front ends, the MI version level 27928will be increased by one. This will allow the front end to parse the 27929output according to the MI version. Apart from mi0, new versions of 27930@value{GDBN} will not support old versions of MI and it will be the 27931responsibility of the front end to work with the new one. 27932 27933@c Starting with mi3, add a new command -mi-version that prints the MI 27934@c version? 27935 27936The best way to avoid unexpected changes in MI that might break your front 27937end is to make your project known to @value{GDBN} developers and 27938follow development on @email{gdb@@sourceware.org} and 27939@email{gdb-patches@@sourceware.org}. 27940@cindex mailing lists 27941 27942@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 27943@node GDB/MI Output Records 27944@section @sc{gdb/mi} Output Records 27945 27946@menu 27947* GDB/MI Result Records:: 27948* GDB/MI Stream Records:: 27949* GDB/MI Async Records:: 27950* GDB/MI Breakpoint Information:: 27951* GDB/MI Frame Information:: 27952* GDB/MI Thread Information:: 27953* GDB/MI Ada Exception Information:: 27954@end menu 27955 27956@node GDB/MI Result Records 27957@subsection @sc{gdb/mi} Result Records 27958 27959@cindex result records in @sc{gdb/mi} 27960@cindex @sc{gdb/mi}, result records 27961In addition to a number of out-of-band notifications, the response to a 27962@sc{gdb/mi} command includes one of the following result indications: 27963 27964@table @code 27965@findex ^done 27966@item "^done" [ "," @var{results} ] 27967The synchronous operation was successful, @code{@var{results}} are the return 27968values. 27969 27970@item "^running" 27971@findex ^running 27972This result record is equivalent to @samp{^done}. Historically, it 27973was output instead of @samp{^done} if the command has resumed the 27974target. This behaviour is maintained for backward compatibility, but 27975all frontends should treat @samp{^done} and @samp{^running} 27976identically and rely on the @samp{*running} output record to determine 27977which threads are resumed. 27978 27979@item "^connected" 27980@findex ^connected 27981@value{GDBN} has connected to a remote target. 27982 27983@item "^error" "," @var{c-string} 27984@findex ^error 27985The operation failed. The @code{@var{c-string}} contains the corresponding 27986error message. 27987 27988@item "^exit" 27989@findex ^exit 27990@value{GDBN} has terminated. 27991 27992@end table 27993 27994@node GDB/MI Stream Records 27995@subsection @sc{gdb/mi} Stream Records 27996 27997@cindex @sc{gdb/mi}, stream records 27998@cindex stream records in @sc{gdb/mi} 27999@value{GDBN} internally maintains a number of output streams: the console, the 28000target, and the log. The output intended for each of these streams is 28001funneled through the @sc{gdb/mi} interface using @dfn{stream records}. 28002 28003Each stream record begins with a unique @dfn{prefix character} which 28004identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output 28005Syntax}). In addition to the prefix, each stream record contains a 28006@code{@var{string-output}}. This is either raw text (with an implicit new 28007line) or a quoted C string (which does not contain an implicit newline). 28008 28009@table @code 28010@item "~" @var{string-output} 28011The console output stream contains text that should be displayed in the 28012CLI console window. It contains the textual responses to CLI commands. 28013 28014@item "@@" @var{string-output} 28015The target output stream contains any textual output from the running 28016target. This is only present when GDB's event loop is truly 28017asynchronous, which is currently only the case for remote targets. 28018 28019@item "&" @var{string-output} 28020The log stream contains debugging messages being produced by @value{GDBN}'s 28021internals. 28022@end table 28023 28024@node GDB/MI Async Records 28025@subsection @sc{gdb/mi} Async Records 28026 28027@cindex async records in @sc{gdb/mi} 28028@cindex @sc{gdb/mi}, async records 28029@dfn{Async} records are used to notify the @sc{gdb/mi} client of 28030additional changes that have occurred. Those changes can either be a 28031consequence of @sc{gdb/mi} commands (e.g., a breakpoint modified) or a result of 28032target activity (e.g., target stopped). 28033 28034The following is the list of possible async records: 28035 28036@table @code 28037 28038@item *running,thread-id="@var{thread}" 28039The target is now running. The @var{thread} field tells which 28040specific thread is now running, and can be @samp{all} if all threads 28041are running. The frontend should assume that no interaction with a 28042running thread is possible after this notification is produced. 28043The frontend should not assume that this notification is output 28044only once for any command. @value{GDBN} may emit this notification 28045several times, either for different threads, because it cannot resume 28046all threads together, or even for a single thread, if the thread must 28047be stepped though some code before letting it run freely. 28048 28049@item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}",core="@var{core}" 28050The target has stopped. The @var{reason} field can have one of the 28051following values: 28052 28053@table @code 28054@item breakpoint-hit 28055A breakpoint was reached. 28056@item watchpoint-trigger 28057A watchpoint was triggered. 28058@item read-watchpoint-trigger 28059A read watchpoint was triggered. 28060@item access-watchpoint-trigger 28061An access watchpoint was triggered. 28062@item function-finished 28063An -exec-finish or similar CLI command was accomplished. 28064@item location-reached 28065An -exec-until or similar CLI command was accomplished. 28066@item watchpoint-scope 28067A watchpoint has gone out of scope. 28068@item end-stepping-range 28069An -exec-next, -exec-next-instruction, -exec-step, -exec-step-instruction or 28070similar CLI command was accomplished. 28071@item exited-signalled 28072The inferior exited because of a signal. 28073@item exited 28074The inferior exited. 28075@item exited-normally 28076The inferior exited normally. 28077@item signal-received 28078A signal was received by the inferior. 28079@item solib-event 28080The inferior has stopped due to a library being loaded or unloaded. 28081This can happen when @code{stop-on-solib-events} (@pxref{Files}) is 28082set or when a @code{catch load} or @code{catch unload} catchpoint is 28083in use (@pxref{Set Catchpoints}). 28084@item fork 28085The inferior has forked. This is reported when @code{catch fork} 28086(@pxref{Set Catchpoints}) has been used. 28087@item vfork 28088The inferior has vforked. This is reported in when @code{catch vfork} 28089(@pxref{Set Catchpoints}) has been used. 28090@item syscall-entry 28091The inferior entered a system call. This is reported when @code{catch 28092syscall} (@pxref{Set Catchpoints}) has been used. 28093@item syscall-entry 28094The inferior returned from a system call. This is reported when 28095@code{catch syscall} (@pxref{Set Catchpoints}) has been used. 28096@item exec 28097The inferior called @code{exec}. This is reported when @code{catch exec} 28098(@pxref{Set Catchpoints}) has been used. 28099@end table 28100 28101The @var{id} field identifies the thread that directly caused the stop 28102-- for example by hitting a breakpoint. Depending on whether all-stop 28103mode is in effect (@pxref{All-Stop Mode}), @value{GDBN} may either 28104stop all threads, or only the thread that directly triggered the stop. 28105If all threads are stopped, the @var{stopped} field will have the 28106value of @code{"all"}. Otherwise, the value of the @var{stopped} 28107field will be a list of thread identifiers. Presently, this list will 28108always include a single thread, but frontend should be prepared to see 28109several threads in the list. The @var{core} field reports the 28110processor core on which the stop event has happened. This field may be absent 28111if such information is not available. 28112 28113@item =thread-group-added,id="@var{id}" 28114@itemx =thread-group-removed,id="@var{id}" 28115A thread group was either added or removed. The @var{id} field 28116contains the @value{GDBN} identifier of the thread group. When a thread 28117group is added, it generally might not be associated with a running 28118process. When a thread group is removed, its id becomes invalid and 28119cannot be used in any way. 28120 28121@item =thread-group-started,id="@var{id}",pid="@var{pid}" 28122A thread group became associated with a running program, 28123either because the program was just started or the thread group 28124was attached to a program. The @var{id} field contains the 28125@value{GDBN} identifier of the thread group. The @var{pid} field 28126contains process identifier, specific to the operating system. 28127 28128@item =thread-group-exited,id="@var{id}"[,exit-code="@var{code}"] 28129A thread group is no longer associated with a running program, 28130either because the program has exited, or because it was detached 28131from. The @var{id} field contains the @value{GDBN} identifier of the 28132thread group. @var{code} is the exit code of the inferior; it exists 28133only when the inferior exited with some code. 28134 28135@item =thread-created,id="@var{id}",group-id="@var{gid}" 28136@itemx =thread-exited,id="@var{id}",group-id="@var{gid}" 28137A thread either was created, or has exited. The @var{id} field 28138contains the @value{GDBN} identifier of the thread. The @var{gid} 28139field identifies the thread group this thread belongs to. 28140 28141@item =thread-selected,id="@var{id}" 28142Informs that the selected thread was changed as result of the last 28143command. This notification is not emitted as result of @code{-thread-select} 28144command but is emitted whenever an MI command that is not documented 28145to change the selected thread actually changes it. In particular, 28146invoking, directly or indirectly (via user-defined command), the CLI 28147@code{thread} command, will generate this notification. 28148 28149We suggest that in response to this notification, front ends 28150highlight the selected thread and cause subsequent commands to apply to 28151that thread. 28152 28153@item =library-loaded,... 28154Reports that a new library file was loaded by the program. This 28155notification has 4 fields---@var{id}, @var{target-name}, 28156@var{host-name}, and @var{symbols-loaded}. The @var{id} field is an 28157opaque identifier of the library. For remote debugging case, 28158@var{target-name} and @var{host-name} fields give the name of the 28159library file on the target, and on the host respectively. For native 28160debugging, both those fields have the same value. The 28161@var{symbols-loaded} field is emitted only for backward compatibility 28162and should not be relied on to convey any useful information. The 28163@var{thread-group} field, if present, specifies the id of the thread 28164group in whose context the library was loaded. If the field is 28165absent, it means the library was loaded in the context of all present 28166thread groups. 28167 28168@item =library-unloaded,... 28169Reports that a library was unloaded by the program. This notification 28170has 3 fields---@var{id}, @var{target-name} and @var{host-name} with 28171the same meaning as for the @code{=library-loaded} notification. 28172The @var{thread-group} field, if present, specifies the id of the 28173thread group in whose context the library was unloaded. If the field is 28174absent, it means the library was unloaded in the context of all present 28175thread groups. 28176 28177@item =traceframe-changed,num=@var{tfnum},tracepoint=@var{tpnum} 28178@itemx =traceframe-changed,end 28179Reports that the trace frame was changed and its new number is 28180@var{tfnum}. The number of the tracepoint associated with this trace 28181frame is @var{tpnum}. 28182 28183@item =tsv-created,name=@var{name},initial=@var{initial} 28184Reports that the new trace state variable @var{name} is created with 28185initial value @var{initial}. 28186 28187@item =tsv-deleted,name=@var{name} 28188@itemx =tsv-deleted 28189Reports that the trace state variable @var{name} is deleted or all 28190trace state variables are deleted. 28191 28192@item =tsv-modified,name=@var{name},initial=@var{initial}[,current=@var{current}] 28193Reports that the trace state variable @var{name} is modified with 28194the initial value @var{initial}. The current value @var{current} of 28195trace state variable is optional and is reported if the current 28196value of trace state variable is known. 28197 28198@item =breakpoint-created,bkpt=@{...@} 28199@itemx =breakpoint-modified,bkpt=@{...@} 28200@itemx =breakpoint-deleted,id=@var{number} 28201Reports that a breakpoint was created, modified, or deleted, 28202respectively. Only user-visible breakpoints are reported to the MI 28203user. 28204 28205The @var{bkpt} argument is of the same form as returned by the various 28206breakpoint commands; @xref{GDB/MI Breakpoint Commands}. The 28207@var{number} is the ordinal number of the breakpoint. 28208 28209Note that if a breakpoint is emitted in the result record of a 28210command, then it will not also be emitted in an async record. 28211 28212@item =record-started,thread-group="@var{id}" 28213@itemx =record-stopped,thread-group="@var{id}" 28214Execution log recording was either started or stopped on an 28215inferior. The @var{id} is the @value{GDBN} identifier of the thread 28216group corresponding to the affected inferior. 28217 28218@item =cmd-param-changed,param=@var{param},value=@var{value} 28219Reports that a parameter of the command @code{set @var{param}} is 28220changed to @var{value}. In the multi-word @code{set} command, 28221the @var{param} is the whole parameter list to @code{set} command. 28222For example, In command @code{set check type on}, @var{param} 28223is @code{check type} and @var{value} is @code{on}. 28224 28225@item =memory-changed,thread-group=@var{id},addr=@var{addr},len=@var{len}[,type="code"] 28226Reports that bytes from @var{addr} to @var{data} + @var{len} were 28227written in an inferior. The @var{id} is the identifier of the 28228thread group corresponding to the affected inferior. The optional 28229@code{type="code"} part is reported if the memory written to holds 28230executable code. 28231@end table 28232 28233@node GDB/MI Breakpoint Information 28234@subsection @sc{gdb/mi} Breakpoint Information 28235 28236When @value{GDBN} reports information about a breakpoint, a 28237tracepoint, a watchpoint, or a catchpoint, it uses a tuple with the 28238following fields: 28239 28240@table @code 28241@item number 28242The breakpoint number. For a breakpoint that represents one location 28243of a multi-location breakpoint, this will be a dotted pair, like 28244@samp{1.2}. 28245 28246@item type 28247The type of the breakpoint. For ordinary breakpoints this will be 28248@samp{breakpoint}, but many values are possible. 28249 28250@item catch-type 28251If the type of the breakpoint is @samp{catchpoint}, then this 28252indicates the exact type of catchpoint. 28253 28254@item disp 28255This is the breakpoint disposition---either @samp{del}, meaning that 28256the breakpoint will be deleted at the next stop, or @samp{keep}, 28257meaning that the breakpoint will not be deleted. 28258 28259@item enabled 28260This indicates whether the breakpoint is enabled, in which case the 28261value is @samp{y}, or disabled, in which case the value is @samp{n}. 28262Note that this is not the same as the field @code{enable}. 28263 28264@item addr 28265The address of the breakpoint. This may be a hexidecimal number, 28266giving the address; or the string @samp{<PENDING>}, for a pending 28267breakpoint; or the string @samp{<MULTIPLE>}, for a breakpoint with 28268multiple locations. This field will not be present if no address can 28269be determined. For example, a watchpoint does not have an address. 28270 28271@item func 28272If known, the function in which the breakpoint appears. 28273If not known, this field is not present. 28274 28275@item filename 28276The name of the source file which contains this function, if known. 28277If not known, this field is not present. 28278 28279@item fullname 28280The full file name of the source file which contains this function, if 28281known. If not known, this field is not present. 28282 28283@item line 28284The line number at which this breakpoint appears, if known. 28285If not known, this field is not present. 28286 28287@item at 28288If the source file is not known, this field may be provided. If 28289provided, this holds the address of the breakpoint, possibly followed 28290by a symbol name. 28291 28292@item pending 28293If this breakpoint is pending, this field is present and holds the 28294text used to set the breakpoint, as entered by the user. 28295 28296@item evaluated-by 28297Where this breakpoint's condition is evaluated, either @samp{host} or 28298@samp{target}. 28299 28300@item thread 28301If this is a thread-specific breakpoint, then this identifies the 28302thread in which the breakpoint can trigger. 28303 28304@item task 28305If this breakpoint is restricted to a particular Ada task, then this 28306field will hold the task identifier. 28307 28308@item cond 28309If the breakpoint is conditional, this is the condition expression. 28310 28311@item ignore 28312The ignore count of the breakpoint. 28313 28314@item enable 28315The enable count of the breakpoint. 28316 28317@item traceframe-usage 28318FIXME. 28319 28320@item static-tracepoint-marker-string-id 28321For a static tracepoint, the name of the static tracepoint marker. 28322 28323@item mask 28324For a masked watchpoint, this is the mask. 28325 28326@item pass 28327A tracepoint's pass count. 28328 28329@item original-location 28330The location of the breakpoint as originally specified by the user. 28331This field is optional. 28332 28333@item times 28334The number of times the breakpoint has been hit. 28335 28336@item installed 28337This field is only given for tracepoints. This is either @samp{y}, 28338meaning that the tracepoint is installed, or @samp{n}, meaning that it 28339is not. 28340 28341@item what 28342Some extra data, the exact contents of which are type-dependent. 28343 28344@end table 28345 28346For example, here is what the output of @code{-break-insert} 28347(@pxref{GDB/MI Breakpoint Commands}) might be: 28348 28349@smallexample 28350-> -break-insert main 28351<- ^done,bkpt=@{number="1",type="breakpoint",disp="keep", 28352 enabled="y",addr="0x08048564",func="main",file="myprog.c", 28353 fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"], 28354 times="0"@} 28355<- (gdb) 28356@end smallexample 28357 28358@node GDB/MI Frame Information 28359@subsection @sc{gdb/mi} Frame Information 28360 28361Response from many MI commands includes an information about stack 28362frame. This information is a tuple that may have the following 28363fields: 28364 28365@table @code 28366@item level 28367The level of the stack frame. The innermost frame has the level of 28368zero. This field is always present. 28369 28370@item func 28371The name of the function corresponding to the frame. This field may 28372be absent if @value{GDBN} is unable to determine the function name. 28373 28374@item addr 28375The code address for the frame. This field is always present. 28376 28377@item file 28378The name of the source files that correspond to the frame's code 28379address. This field may be absent. 28380 28381@item line 28382The source line corresponding to the frames' code address. This field 28383may be absent. 28384 28385@item from 28386The name of the binary file (either executable or shared library) the 28387corresponds to the frame's code address. This field may be absent. 28388 28389@end table 28390 28391@node GDB/MI Thread Information 28392@subsection @sc{gdb/mi} Thread Information 28393 28394Whenever @value{GDBN} has to report an information about a thread, it 28395uses a tuple with the following fields: 28396 28397@table @code 28398@item id 28399The numeric id assigned to the thread by @value{GDBN}. This field is 28400always present. 28401 28402@item target-id 28403Target-specific string identifying the thread. This field is always present. 28404 28405@item details 28406Additional information about the thread provided by the target. 28407It is supposed to be human-readable and not interpreted by the 28408frontend. This field is optional. 28409 28410@item state 28411Either @samp{stopped} or @samp{running}, depending on whether the 28412thread is presently running. This field is always present. 28413 28414@item core 28415The value of this field is an integer number of the processor core the 28416thread was last seen on. This field is optional. 28417@end table 28418 28419@node GDB/MI Ada Exception Information 28420@subsection @sc{gdb/mi} Ada Exception Information 28421 28422Whenever a @code{*stopped} record is emitted because the program 28423stopped after hitting an exception catchpoint (@pxref{Set Catchpoints}), 28424@value{GDBN} provides the name of the exception that was raised via 28425the @code{exception-name} field. 28426 28427@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 28428@node GDB/MI Simple Examples 28429@section Simple Examples of @sc{gdb/mi} Interaction 28430@cindex @sc{gdb/mi}, simple examples 28431 28432This subsection presents several simple examples of interaction using 28433the @sc{gdb/mi} interface. In these examples, @samp{->} means that the 28434following line is passed to @sc{gdb/mi} as input, while @samp{<-} means 28435the output received from @sc{gdb/mi}. 28436 28437Note the line breaks shown in the examples are here only for 28438readability, they don't appear in the real output. 28439 28440@subheading Setting a Breakpoint 28441 28442Setting a breakpoint generates synchronous output which contains detailed 28443information of the breakpoint. 28444 28445@smallexample 28446-> -break-insert main 28447<- ^done,bkpt=@{number="1",type="breakpoint",disp="keep", 28448 enabled="y",addr="0x08048564",func="main",file="myprog.c", 28449 fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"], 28450 times="0"@} 28451<- (gdb) 28452@end smallexample 28453 28454@subheading Program Execution 28455 28456Program execution generates asynchronous records and MI gives the 28457reason that execution stopped. 28458 28459@smallexample 28460-> -exec-run 28461<- ^running 28462<- (gdb) 28463<- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", 28464 frame=@{addr="0x08048564",func="main", 28465 args=[@{name="argc",value="1"@},@{name="argv",value="0xbfc4d4d4"@}], 28466 file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"@} 28467<- (gdb) 28468-> -exec-continue 28469<- ^running 28470<- (gdb) 28471<- *stopped,reason="exited-normally" 28472<- (gdb) 28473@end smallexample 28474 28475@subheading Quitting @value{GDBN} 28476 28477Quitting @value{GDBN} just prints the result class @samp{^exit}. 28478 28479@smallexample 28480-> (gdb) 28481<- -gdb-exit 28482<- ^exit 28483@end smallexample 28484 28485Please note that @samp{^exit} is printed immediately, but it might 28486take some time for @value{GDBN} to actually exit. During that time, @value{GDBN} 28487performs necessary cleanups, including killing programs being debugged 28488or disconnecting from debug hardware, so the frontend should wait till 28489@value{GDBN} exits and should only forcibly kill @value{GDBN} if it 28490fails to exit in reasonable time. 28491 28492@subheading A Bad Command 28493 28494Here's what happens if you pass a non-existent command: 28495 28496@smallexample 28497-> -rubbish 28498<- ^error,msg="Undefined MI command: rubbish" 28499<- (gdb) 28500@end smallexample 28501 28502 28503@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 28504@node GDB/MI Command Description Format 28505@section @sc{gdb/mi} Command Description Format 28506 28507The remaining sections describe blocks of commands. Each block of 28508commands is laid out in a fashion similar to this section. 28509 28510@subheading Motivation 28511 28512The motivation for this collection of commands. 28513 28514@subheading Introduction 28515 28516A brief introduction to this collection of commands as a whole. 28517 28518@subheading Commands 28519 28520For each command in the block, the following is described: 28521 28522@subsubheading Synopsis 28523 28524@smallexample 28525 -command @var{args}@dots{} 28526@end smallexample 28527 28528@subsubheading Result 28529 28530@subsubheading @value{GDBN} Command 28531 28532The corresponding @value{GDBN} CLI command(s), if any. 28533 28534@subsubheading Example 28535 28536Example(s) formatted for readability. Some of the described commands have 28537not been implemented yet and these are labeled N.A.@: (not available). 28538 28539 28540@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 28541@node GDB/MI Breakpoint Commands 28542@section @sc{gdb/mi} Breakpoint Commands 28543 28544@cindex breakpoint commands for @sc{gdb/mi} 28545@cindex @sc{gdb/mi}, breakpoint commands 28546This section documents @sc{gdb/mi} commands for manipulating 28547breakpoints. 28548 28549@subheading The @code{-break-after} Command 28550@findex -break-after 28551 28552@subsubheading Synopsis 28553 28554@smallexample 28555 -break-after @var{number} @var{count} 28556@end smallexample 28557 28558The breakpoint number @var{number} is not in effect until it has been 28559hit @var{count} times. To see how this is reflected in the output of 28560the @samp{-break-list} command, see the description of the 28561@samp{-break-list} command below. 28562 28563@subsubheading @value{GDBN} Command 28564 28565The corresponding @value{GDBN} command is @samp{ignore}. 28566 28567@subsubheading Example 28568 28569@smallexample 28570(gdb) 28571-break-insert main 28572^done,bkpt=@{number="1",type="breakpoint",disp="keep", 28573enabled="y",addr="0x000100d0",func="main",file="hello.c", 28574fullname="/home/foo/hello.c",line="5",thread-groups=["i1"], 28575times="0"@} 28576(gdb) 28577-break-after 1 3 28578~ 28579^done 28580(gdb) 28581-break-list 28582^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 28583hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 28584@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 28585@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 28586@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 28587@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 28588@{width="40",alignment="2",col_name="what",colhdr="What"@}], 28589body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 28590addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 28591line="5",thread-groups=["i1"],times="0",ignore="3"@}]@} 28592(gdb) 28593@end smallexample 28594 28595@ignore 28596@subheading The @code{-break-catch} Command 28597@findex -break-catch 28598@end ignore 28599 28600@subheading The @code{-break-commands} Command 28601@findex -break-commands 28602 28603@subsubheading Synopsis 28604 28605@smallexample 28606 -break-commands @var{number} [ @var{command1} ... @var{commandN} ] 28607@end smallexample 28608 28609Specifies the CLI commands that should be executed when breakpoint 28610@var{number} is hit. The parameters @var{command1} to @var{commandN} 28611are the commands. If no command is specified, any previously-set 28612commands are cleared. @xref{Break Commands}. Typical use of this 28613functionality is tracing a program, that is, printing of values of 28614some variables whenever breakpoint is hit and then continuing. 28615 28616@subsubheading @value{GDBN} Command 28617 28618The corresponding @value{GDBN} command is @samp{commands}. 28619 28620@subsubheading Example 28621 28622@smallexample 28623(gdb) 28624-break-insert main 28625^done,bkpt=@{number="1",type="breakpoint",disp="keep", 28626enabled="y",addr="0x000100d0",func="main",file="hello.c", 28627fullname="/home/foo/hello.c",line="5",thread-groups=["i1"], 28628times="0"@} 28629(gdb) 28630-break-commands 1 "print v" "continue" 28631^done 28632(gdb) 28633@end smallexample 28634 28635@subheading The @code{-break-condition} Command 28636@findex -break-condition 28637 28638@subsubheading Synopsis 28639 28640@smallexample 28641 -break-condition @var{number} @var{expr} 28642@end smallexample 28643 28644Breakpoint @var{number} will stop the program only if the condition in 28645@var{expr} is true. The condition becomes part of the 28646@samp{-break-list} output (see the description of the @samp{-break-list} 28647command below). 28648 28649@subsubheading @value{GDBN} Command 28650 28651The corresponding @value{GDBN} command is @samp{condition}. 28652 28653@subsubheading Example 28654 28655@smallexample 28656(gdb) 28657-break-condition 1 1 28658^done 28659(gdb) 28660-break-list 28661^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 28662hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 28663@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 28664@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 28665@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 28666@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 28667@{width="40",alignment="2",col_name="what",colhdr="What"@}], 28668body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 28669addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 28670line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"@}]@} 28671(gdb) 28672@end smallexample 28673 28674@subheading The @code{-break-delete} Command 28675@findex -break-delete 28676 28677@subsubheading Synopsis 28678 28679@smallexample 28680 -break-delete ( @var{breakpoint} )+ 28681@end smallexample 28682 28683Delete the breakpoint(s) whose number(s) are specified in the argument 28684list. This is obviously reflected in the breakpoint list. 28685 28686@subsubheading @value{GDBN} Command 28687 28688The corresponding @value{GDBN} command is @samp{delete}. 28689 28690@subsubheading Example 28691 28692@smallexample 28693(gdb) 28694-break-delete 1 28695^done 28696(gdb) 28697-break-list 28698^done,BreakpointTable=@{nr_rows="0",nr_cols="6", 28699hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 28700@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 28701@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 28702@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 28703@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 28704@{width="40",alignment="2",col_name="what",colhdr="What"@}], 28705body=[]@} 28706(gdb) 28707@end smallexample 28708 28709@subheading The @code{-break-disable} Command 28710@findex -break-disable 28711 28712@subsubheading Synopsis 28713 28714@smallexample 28715 -break-disable ( @var{breakpoint} )+ 28716@end smallexample 28717 28718Disable the named @var{breakpoint}(s). The field @samp{enabled} in the 28719break list is now set to @samp{n} for the named @var{breakpoint}(s). 28720 28721@subsubheading @value{GDBN} Command 28722 28723The corresponding @value{GDBN} command is @samp{disable}. 28724 28725@subsubheading Example 28726 28727@smallexample 28728(gdb) 28729-break-disable 2 28730^done 28731(gdb) 28732-break-list 28733^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 28734hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 28735@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 28736@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 28737@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 28738@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 28739@{width="40",alignment="2",col_name="what",colhdr="What"@}], 28740body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n", 28741addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 28742line="5",thread-groups=["i1"],times="0"@}]@} 28743(gdb) 28744@end smallexample 28745 28746@subheading The @code{-break-enable} Command 28747@findex -break-enable 28748 28749@subsubheading Synopsis 28750 28751@smallexample 28752 -break-enable ( @var{breakpoint} )+ 28753@end smallexample 28754 28755Enable (previously disabled) @var{breakpoint}(s). 28756 28757@subsubheading @value{GDBN} Command 28758 28759The corresponding @value{GDBN} command is @samp{enable}. 28760 28761@subsubheading Example 28762 28763@smallexample 28764(gdb) 28765-break-enable 2 28766^done 28767(gdb) 28768-break-list 28769^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 28770hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 28771@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 28772@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 28773@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 28774@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 28775@{width="40",alignment="2",col_name="what",colhdr="What"@}], 28776body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", 28777addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 28778line="5",thread-groups=["i1"],times="0"@}]@} 28779(gdb) 28780@end smallexample 28781 28782@subheading The @code{-break-info} Command 28783@findex -break-info 28784 28785@subsubheading Synopsis 28786 28787@smallexample 28788 -break-info @var{breakpoint} 28789@end smallexample 28790 28791@c REDUNDANT??? 28792Get information about a single breakpoint. 28793 28794The result is a table of breakpoints. @xref{GDB/MI Breakpoint 28795Information}, for details on the format of each breakpoint in the 28796table. 28797 28798@subsubheading @value{GDBN} Command 28799 28800The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}. 28801 28802@subsubheading Example 28803N.A. 28804 28805@subheading The @code{-break-insert} Command 28806@findex -break-insert 28807 28808@subsubheading Synopsis 28809 28810@smallexample 28811 -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] 28812 [ -c @var{condition} ] [ -i @var{ignore-count} ] 28813 [ -p @var{thread-id} ] [ @var{location} ] 28814@end smallexample 28815 28816@noindent 28817If specified, @var{location}, can be one of: 28818 28819@itemize @bullet 28820@item function 28821@c @item +offset 28822@c @item -offset 28823@c @item linenum 28824@item filename:linenum 28825@item filename:function 28826@item *address 28827@end itemize 28828 28829The possible optional parameters of this command are: 28830 28831@table @samp 28832@item -t 28833Insert a temporary breakpoint. 28834@item -h 28835Insert a hardware breakpoint. 28836@item -f 28837If @var{location} cannot be parsed (for example if it 28838refers to unknown files or functions), create a pending 28839breakpoint. Without this flag, @value{GDBN} will report 28840an error, and won't create a breakpoint, if @var{location} 28841cannot be parsed. 28842@item -d 28843Create a disabled breakpoint. 28844@item -a 28845Create a tracepoint. @xref{Tracepoints}. When this parameter 28846is used together with @samp{-h}, a fast tracepoint is created. 28847@item -c @var{condition} 28848Make the breakpoint conditional on @var{condition}. 28849@item -i @var{ignore-count} 28850Initialize the @var{ignore-count}. 28851@item -p @var{thread-id} 28852Restrict the breakpoint to the specified @var{thread-id}. 28853@end table 28854 28855@subsubheading Result 28856 28857@xref{GDB/MI Breakpoint Information}, for details on the format of the 28858resulting breakpoint. 28859 28860Note: this format is open to change. 28861@c An out-of-band breakpoint instead of part of the result? 28862 28863@subsubheading @value{GDBN} Command 28864 28865The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak}, 28866@samp{hbreak}, and @samp{thbreak}. @c and @samp{rbreak}. 28867 28868@subsubheading Example 28869 28870@smallexample 28871(gdb) 28872-break-insert main 28873^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c", 28874fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"], 28875times="0"@} 28876(gdb) 28877-break-insert -t foo 28878^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c", 28879fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"], 28880times="0"@} 28881(gdb) 28882-break-list 28883^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 28884hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 28885@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 28886@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 28887@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 28888@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 28889@{width="40",alignment="2",col_name="what",colhdr="What"@}], 28890body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 28891addr="0x0001072c", func="main",file="recursive2.c", 28892fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"], 28893times="0"@}, 28894bkpt=@{number="2",type="breakpoint",disp="del",enabled="y", 28895addr="0x00010774",func="foo",file="recursive2.c", 28896fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"], 28897times="0"@}]@} 28898(gdb) 28899@c -break-insert -r foo.* 28900@c ~int foo(int, int); 28901@c ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c, 28902@c "fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"], 28903@c times="0"@} 28904@c (gdb) 28905@end smallexample 28906 28907@subheading The @code{-break-list} Command 28908@findex -break-list 28909 28910@subsubheading Synopsis 28911 28912@smallexample 28913 -break-list 28914@end smallexample 28915 28916Displays the list of inserted breakpoints, showing the following fields: 28917 28918@table @samp 28919@item Number 28920number of the breakpoint 28921@item Type 28922type of the breakpoint: @samp{breakpoint} or @samp{watchpoint} 28923@item Disposition 28924should the breakpoint be deleted or disabled when it is hit: @samp{keep} 28925or @samp{nokeep} 28926@item Enabled 28927is the breakpoint enabled or no: @samp{y} or @samp{n} 28928@item Address 28929memory location at which the breakpoint is set 28930@item What 28931logical location of the breakpoint, expressed by function name, file 28932name, line number 28933@item Thread-groups 28934list of thread groups to which this breakpoint applies 28935@item Times 28936number of times the breakpoint has been hit 28937@end table 28938 28939If there are no breakpoints or watchpoints, the @code{BreakpointTable} 28940@code{body} field is an empty list. 28941 28942@subsubheading @value{GDBN} Command 28943 28944The corresponding @value{GDBN} command is @samp{info break}. 28945 28946@subsubheading Example 28947 28948@smallexample 28949(gdb) 28950-break-list 28951^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 28952hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 28953@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 28954@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 28955@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 28956@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 28957@{width="40",alignment="2",col_name="what",colhdr="What"@}], 28958body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 28959addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"], 28960times="0"@}, 28961bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", 28962addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c", 28963line="13",thread-groups=["i1"],times="0"@}]@} 28964(gdb) 28965@end smallexample 28966 28967Here's an example of the result when there are no breakpoints: 28968 28969@smallexample 28970(gdb) 28971-break-list 28972^done,BreakpointTable=@{nr_rows="0",nr_cols="6", 28973hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 28974@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 28975@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 28976@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 28977@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 28978@{width="40",alignment="2",col_name="what",colhdr="What"@}], 28979body=[]@} 28980(gdb) 28981@end smallexample 28982 28983@subheading The @code{-break-passcount} Command 28984@findex -break-passcount 28985 28986@subsubheading Synopsis 28987 28988@smallexample 28989 -break-passcount @var{tracepoint-number} @var{passcount} 28990@end smallexample 28991 28992Set the passcount for tracepoint @var{tracepoint-number} to 28993@var{passcount}. If the breakpoint referred to by @var{tracepoint-number} 28994is not a tracepoint, error is emitted. This corresponds to CLI 28995command @samp{passcount}. 28996 28997@subheading The @code{-break-watch} Command 28998@findex -break-watch 28999 29000@subsubheading Synopsis 29001 29002@smallexample 29003 -break-watch [ -a | -r ] 29004@end smallexample 29005 29006Create a watchpoint. With the @samp{-a} option it will create an 29007@dfn{access} watchpoint, i.e., a watchpoint that triggers either on a 29008read from or on a write to the memory location. With the @samp{-r} 29009option, the watchpoint created is a @dfn{read} watchpoint, i.e., it will 29010trigger only when the memory location is accessed for reading. Without 29011either of the options, the watchpoint created is a regular watchpoint, 29012i.e., it will trigger when the memory location is accessed for writing. 29013@xref{Set Watchpoints, , Setting Watchpoints}. 29014 29015Note that @samp{-break-list} will report a single list of watchpoints and 29016breakpoints inserted. 29017 29018@subsubheading @value{GDBN} Command 29019 29020The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and 29021@samp{rwatch}. 29022 29023@subsubheading Example 29024 29025Setting a watchpoint on a variable in the @code{main} function: 29026 29027@smallexample 29028(gdb) 29029-break-watch x 29030^done,wpt=@{number="2",exp="x"@} 29031(gdb) 29032-exec-continue 29033^running 29034(gdb) 29035*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@}, 29036value=@{old="-268439212",new="55"@}, 29037frame=@{func="main",args=[],file="recursive2.c", 29038fullname="/home/foo/bar/recursive2.c",line="5"@} 29039(gdb) 29040@end smallexample 29041 29042Setting a watchpoint on a variable local to a function. @value{GDBN} will stop 29043the program execution twice: first for the variable changing value, then 29044for the watchpoint going out of scope. 29045 29046@smallexample 29047(gdb) 29048-break-watch C 29049^done,wpt=@{number="5",exp="C"@} 29050(gdb) 29051-exec-continue 29052^running 29053(gdb) 29054*stopped,reason="watchpoint-trigger", 29055wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@}, 29056frame=@{func="callee4",args=[], 29057file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 29058fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@} 29059(gdb) 29060-exec-continue 29061^running 29062(gdb) 29063*stopped,reason="watchpoint-scope",wpnum="5", 29064frame=@{func="callee3",args=[@{name="strarg", 29065value="0x11940 \"A string argument.\""@}], 29066file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 29067fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} 29068(gdb) 29069@end smallexample 29070 29071Listing breakpoints and watchpoints, at different points in the program 29072execution. Note that once the watchpoint goes out of scope, it is 29073deleted. 29074 29075@smallexample 29076(gdb) 29077-break-watch C 29078^done,wpt=@{number="2",exp="C"@} 29079(gdb) 29080-break-list 29081^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 29082hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 29083@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 29084@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 29085@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 29086@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 29087@{width="40",alignment="2",col_name="what",colhdr="What"@}], 29088body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 29089addr="0x00010734",func="callee4", 29090file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 29091fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"], 29092times="1"@}, 29093bkpt=@{number="2",type="watchpoint",disp="keep", 29094enabled="y",addr="",what="C",thread-groups=["i1"],times="0"@}]@} 29095(gdb) 29096-exec-continue 29097^running 29098(gdb) 29099*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@}, 29100value=@{old="-276895068",new="3"@}, 29101frame=@{func="callee4",args=[], 29102file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 29103fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@} 29104(gdb) 29105-break-list 29106^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 29107hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 29108@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 29109@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 29110@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 29111@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 29112@{width="40",alignment="2",col_name="what",colhdr="What"@}], 29113body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 29114addr="0x00010734",func="callee4", 29115file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 29116fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"], 29117times="1"@}, 29118bkpt=@{number="2",type="watchpoint",disp="keep", 29119enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"@}]@} 29120(gdb) 29121-exec-continue 29122^running 29123^done,reason="watchpoint-scope",wpnum="2", 29124frame=@{func="callee3",args=[@{name="strarg", 29125value="0x11940 \"A string argument.\""@}], 29126file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 29127fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} 29128(gdb) 29129-break-list 29130^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 29131hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 29132@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 29133@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 29134@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 29135@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 29136@{width="40",alignment="2",col_name="what",colhdr="What"@}], 29137body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 29138addr="0x00010734",func="callee4", 29139file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 29140fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8", 29141thread-groups=["i1"],times="1"@}]@} 29142(gdb) 29143@end smallexample 29144 29145 29146@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 29147@node GDB/MI Catchpoint Commands 29148@section @sc{gdb/mi} Catchpoint Commands 29149 29150This section documents @sc{gdb/mi} commands for manipulating 29151catchpoints. 29152 29153@subheading The @code{-catch-load} Command 29154@findex -catch-load 29155 29156@subsubheading Synopsis 29157 29158@smallexample 29159 -catch-load [ -t ] [ -d ] @var{regexp} 29160@end smallexample 29161 29162Add a catchpoint for library load events. If the @samp{-t} option is used, 29163the catchpoint is a temporary one (@pxref{Set Breaks, ,Setting 29164Breakpoints}). If the @samp{-d} option is used, the catchpoint is created 29165in a disabled state. The @samp{regexp} argument is a regular 29166expression used to match the name of the loaded library. 29167 29168 29169@subsubheading @value{GDBN} Command 29170 29171The corresponding @value{GDBN} command is @samp{catch load}. 29172 29173@subsubheading Example 29174 29175@smallexample 29176-catch-load -t foo.so 29177^done,bkpt=@{number="1",type="catchpoint",disp="del",enabled="y", 29178what="load of library matching foo.so",catch-type="load",times="0"@} 29179(gdb) 29180@end smallexample 29181 29182 29183@subheading The @code{-catch-unload} Command 29184@findex -catch-unload 29185 29186@subsubheading Synopsis 29187 29188@smallexample 29189 -catch-unload [ -t ] [ -d ] @var{regexp} 29190@end smallexample 29191 29192Add a catchpoint for library unload events. If the @samp{-t} option is 29193used, the catchpoint is a temporary one (@pxref{Set Breaks, ,Setting 29194Breakpoints}). If the @samp{-d} option is used, the catchpoint is 29195created in a disabled state. The @samp{regexp} argument is a regular 29196expression used to match the name of the unloaded library. 29197 29198@subsubheading @value{GDBN} Command 29199 29200The corresponding @value{GDBN} command is @samp{catch unload}. 29201 29202@subsubheading Example 29203 29204@smallexample 29205-catch-unload -d bar.so 29206^done,bkpt=@{number="2",type="catchpoint",disp="keep",enabled="n", 29207what="load of library matching bar.so",catch-type="unload",times="0"@} 29208(gdb) 29209@end smallexample 29210 29211 29212@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 29213@node GDB/MI Program Context 29214@section @sc{gdb/mi} Program Context 29215 29216@subheading The @code{-exec-arguments} Command 29217@findex -exec-arguments 29218 29219 29220@subsubheading Synopsis 29221 29222@smallexample 29223 -exec-arguments @var{args} 29224@end smallexample 29225 29226Set the inferior program arguments, to be used in the next 29227@samp{-exec-run}. 29228 29229@subsubheading @value{GDBN} Command 29230 29231The corresponding @value{GDBN} command is @samp{set args}. 29232 29233@subsubheading Example 29234 29235@smallexample 29236(gdb) 29237-exec-arguments -v word 29238^done 29239(gdb) 29240@end smallexample 29241 29242 29243@ignore 29244@subheading The @code{-exec-show-arguments} Command 29245@findex -exec-show-arguments 29246 29247@subsubheading Synopsis 29248 29249@smallexample 29250 -exec-show-arguments 29251@end smallexample 29252 29253Print the arguments of the program. 29254 29255@subsubheading @value{GDBN} Command 29256 29257The corresponding @value{GDBN} command is @samp{show args}. 29258 29259@subsubheading Example 29260N.A. 29261@end ignore 29262 29263 29264@subheading The @code{-environment-cd} Command 29265@findex -environment-cd 29266 29267@subsubheading Synopsis 29268 29269@smallexample 29270 -environment-cd @var{pathdir} 29271@end smallexample 29272 29273Set @value{GDBN}'s working directory. 29274 29275@subsubheading @value{GDBN} Command 29276 29277The corresponding @value{GDBN} command is @samp{cd}. 29278 29279@subsubheading Example 29280 29281@smallexample 29282(gdb) 29283-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb 29284^done 29285(gdb) 29286@end smallexample 29287 29288 29289@subheading The @code{-environment-directory} Command 29290@findex -environment-directory 29291 29292@subsubheading Synopsis 29293 29294@smallexample 29295 -environment-directory [ -r ] [ @var{pathdir} ]+ 29296@end smallexample 29297 29298Add directories @var{pathdir} to beginning of search path for source files. 29299If the @samp{-r} option is used, the search path is reset to the default 29300search path. If directories @var{pathdir} are supplied in addition to the 29301@samp{-r} option, the search path is first reset and then addition 29302occurs as normal. 29303Multiple directories may be specified, separated by blanks. Specifying 29304multiple directories in a single command 29305results in the directories added to the beginning of the 29306search path in the same order they were presented in the command. 29307If blanks are needed as 29308part of a directory name, double-quotes should be used around 29309the name. In the command output, the path will show up separated 29310by the system directory-separator character. The directory-separator 29311character must not be used 29312in any directory name. 29313If no directories are specified, the current search path is displayed. 29314 29315@subsubheading @value{GDBN} Command 29316 29317The corresponding @value{GDBN} command is @samp{dir}. 29318 29319@subsubheading Example 29320 29321@smallexample 29322(gdb) 29323-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb 29324^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" 29325(gdb) 29326-environment-directory "" 29327^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" 29328(gdb) 29329-environment-directory -r /home/jjohnstn/src/gdb /usr/src 29330^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" 29331(gdb) 29332-environment-directory -r 29333^done,source-path="$cdir:$cwd" 29334(gdb) 29335@end smallexample 29336 29337 29338@subheading The @code{-environment-path} Command 29339@findex -environment-path 29340 29341@subsubheading Synopsis 29342 29343@smallexample 29344 -environment-path [ -r ] [ @var{pathdir} ]+ 29345@end smallexample 29346 29347Add directories @var{pathdir} to beginning of search path for object files. 29348If the @samp{-r} option is used, the search path is reset to the original 29349search path that existed at gdb start-up. If directories @var{pathdir} are 29350supplied in addition to the 29351@samp{-r} option, the search path is first reset and then addition 29352occurs as normal. 29353Multiple directories may be specified, separated by blanks. Specifying 29354multiple directories in a single command 29355results in the directories added to the beginning of the 29356search path in the same order they were presented in the command. 29357If blanks are needed as 29358part of a directory name, double-quotes should be used around 29359the name. In the command output, the path will show up separated 29360by the system directory-separator character. The directory-separator 29361character must not be used 29362in any directory name. 29363If no directories are specified, the current path is displayed. 29364 29365 29366@subsubheading @value{GDBN} Command 29367 29368The corresponding @value{GDBN} command is @samp{path}. 29369 29370@subsubheading Example 29371 29372@smallexample 29373(gdb) 29374-environment-path 29375^done,path="/usr/bin" 29376(gdb) 29377-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin 29378^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" 29379(gdb) 29380-environment-path -r /usr/local/bin 29381^done,path="/usr/local/bin:/usr/bin" 29382(gdb) 29383@end smallexample 29384 29385 29386@subheading The @code{-environment-pwd} Command 29387@findex -environment-pwd 29388 29389@subsubheading Synopsis 29390 29391@smallexample 29392 -environment-pwd 29393@end smallexample 29394 29395Show the current working directory. 29396 29397@subsubheading @value{GDBN} Command 29398 29399The corresponding @value{GDBN} command is @samp{pwd}. 29400 29401@subsubheading Example 29402 29403@smallexample 29404(gdb) 29405-environment-pwd 29406^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" 29407(gdb) 29408@end smallexample 29409 29410@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 29411@node GDB/MI Thread Commands 29412@section @sc{gdb/mi} Thread Commands 29413 29414 29415@subheading The @code{-thread-info} Command 29416@findex -thread-info 29417 29418@subsubheading Synopsis 29419 29420@smallexample 29421 -thread-info [ @var{thread-id} ] 29422@end smallexample 29423 29424Reports information about either a specific thread, if 29425the @var{thread-id} parameter is present, or about all 29426threads. When printing information about all threads, 29427also reports the current thread. 29428 29429@subsubheading @value{GDBN} Command 29430 29431The @samp{info thread} command prints the same information 29432about all threads. 29433 29434@subsubheading Result 29435 29436The result is a list of threads. The following attributes are 29437defined for a given thread: 29438 29439@table @samp 29440@item current 29441This field exists only for the current thread. It has the value @samp{*}. 29442 29443@item id 29444The identifier that @value{GDBN} uses to refer to the thread. 29445 29446@item target-id 29447The identifier that the target uses to refer to the thread. 29448 29449@item details 29450Extra information about the thread, in a target-specific format. This 29451field is optional. 29452 29453@item name 29454The name of the thread. If the user specified a name using the 29455@code{thread name} command, then this name is given. Otherwise, if 29456@value{GDBN} can extract the thread name from the target, then that 29457name is given. If @value{GDBN} cannot find the thread name, then this 29458field is omitted. 29459 29460@item frame 29461The stack frame currently executing in the thread. 29462 29463@item state 29464The thread's state. The @samp{state} field may have the following 29465values: 29466 29467@table @code 29468@item stopped 29469The thread is stopped. Frame information is available for stopped 29470threads. 29471 29472@item running 29473The thread is running. There's no frame information for running 29474threads. 29475 29476@end table 29477 29478@item core 29479If @value{GDBN} can find the CPU core on which this thread is running, 29480then this field is the core identifier. This field is optional. 29481 29482@end table 29483 29484@subsubheading Example 29485 29486@smallexample 29487-thread-info 29488^done,threads=[ 29489@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", 29490 frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall", 29491 args=[]@},state="running"@}, 29492@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", 29493 frame=@{level="0",addr="0x0804891f",func="foo", 29494 args=[@{name="i",value="10"@}], 29495 file="/tmp/a.c",fullname="/tmp/a.c",line="158"@}, 29496 state="running"@}], 29497current-thread-id="1" 29498(gdb) 29499@end smallexample 29500 29501@subheading The @code{-thread-list-ids} Command 29502@findex -thread-list-ids 29503 29504@subsubheading Synopsis 29505 29506@smallexample 29507 -thread-list-ids 29508@end smallexample 29509 29510Produces a list of the currently known @value{GDBN} thread ids. At the 29511end of the list it also prints the total number of such threads. 29512 29513This command is retained for historical reasons, the 29514@code{-thread-info} command should be used instead. 29515 29516@subsubheading @value{GDBN} Command 29517 29518Part of @samp{info threads} supplies the same information. 29519 29520@subsubheading Example 29521 29522@smallexample 29523(gdb) 29524-thread-list-ids 29525^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, 29526current-thread-id="1",number-of-threads="3" 29527(gdb) 29528@end smallexample 29529 29530 29531@subheading The @code{-thread-select} Command 29532@findex -thread-select 29533 29534@subsubheading Synopsis 29535 29536@smallexample 29537 -thread-select @var{threadnum} 29538@end smallexample 29539 29540Make @var{threadnum} the current thread. It prints the number of the new 29541current thread, and the topmost frame for that thread. 29542 29543This command is deprecated in favor of explicitly using the 29544@samp{--thread} option to each command. 29545 29546@subsubheading @value{GDBN} Command 29547 29548The corresponding @value{GDBN} command is @samp{thread}. 29549 29550@subsubheading Example 29551 29552@smallexample 29553(gdb) 29554-exec-next 29555^running 29556(gdb) 29557*stopped,reason="end-stepping-range",thread-id="2",line="187", 29558file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" 29559(gdb) 29560-thread-list-ids 29561^done, 29562thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, 29563number-of-threads="3" 29564(gdb) 29565-thread-select 3 29566^done,new-thread-id="3", 29567frame=@{level="0",func="vprintf", 29568args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@}, 29569@{name="arg",value="0x2"@}],file="vprintf.c",line="31"@} 29570(gdb) 29571@end smallexample 29572 29573@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 29574@node GDB/MI Ada Tasking Commands 29575@section @sc{gdb/mi} Ada Tasking Commands 29576 29577@subheading The @code{-ada-task-info} Command 29578@findex -ada-task-info 29579 29580@subsubheading Synopsis 29581 29582@smallexample 29583 -ada-task-info [ @var{task-id} ] 29584@end smallexample 29585 29586Reports information about either a specific Ada task, if the 29587@var{task-id} parameter is present, or about all Ada tasks. 29588 29589@subsubheading @value{GDBN} Command 29590 29591The @samp{info tasks} command prints the same information 29592about all Ada tasks (@pxref{Ada Tasks}). 29593 29594@subsubheading Result 29595 29596The result is a table of Ada tasks. The following columns are 29597defined for each Ada task: 29598 29599@table @samp 29600@item current 29601This field exists only for the current thread. It has the value @samp{*}. 29602 29603@item id 29604The identifier that @value{GDBN} uses to refer to the Ada task. 29605 29606@item task-id 29607The identifier that the target uses to refer to the Ada task. 29608 29609@item thread-id 29610The identifier of the thread corresponding to the Ada task. 29611 29612This field should always exist, as Ada tasks are always implemented 29613on top of a thread. But if @value{GDBN} cannot find this corresponding 29614thread for any reason, the field is omitted. 29615 29616@item parent-id 29617This field exists only when the task was created by another task. 29618In this case, it provides the ID of the parent task. 29619 29620@item priority 29621The base priority of the task. 29622 29623@item state 29624The current state of the task. For a detailed description of the 29625possible states, see @ref{Ada Tasks}. 29626 29627@item name 29628The name of the task. 29629 29630@end table 29631 29632@subsubheading Example 29633 29634@smallexample 29635-ada-task-info 29636^done,tasks=@{nr_rows="3",nr_cols="8", 29637hdr=[@{width="1",alignment="-1",col_name="current",colhdr=""@}, 29638@{width="3",alignment="1",col_name="id",colhdr="ID"@}, 29639@{width="9",alignment="1",col_name="task-id",colhdr="TID"@}, 29640@{width="4",alignment="1",col_name="thread-id",colhdr=""@}, 29641@{width="4",alignment="1",col_name="parent-id",colhdr="P-ID"@}, 29642@{width="3",alignment="1",col_name="priority",colhdr="Pri"@}, 29643@{width="22",alignment="-1",col_name="state",colhdr="State"@}, 29644@{width="1",alignment="2",col_name="name",colhdr="Name"@}], 29645body=[@{current="*",id="1",task-id=" 644010",thread-id="1",priority="48", 29646state="Child Termination Wait",name="main_task"@}]@} 29647(gdb) 29648@end smallexample 29649 29650@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 29651@node GDB/MI Program Execution 29652@section @sc{gdb/mi} Program Execution 29653 29654These are the asynchronous commands which generate the out-of-band 29655record @samp{*stopped}. Currently @value{GDBN} only really executes 29656asynchronously with remote targets and this interaction is mimicked in 29657other cases. 29658 29659@subheading The @code{-exec-continue} Command 29660@findex -exec-continue 29661 29662@subsubheading Synopsis 29663 29664@smallexample 29665 -exec-continue [--reverse] [--all|--thread-group N] 29666@end smallexample 29667 29668Resumes the execution of the inferior program, which will continue 29669to execute until it reaches a debugger stop event. If the 29670@samp{--reverse} option is specified, execution resumes in reverse until 29671it reaches a stop event. Stop events may include 29672@itemize @bullet 29673@item 29674breakpoints or watchpoints 29675@item 29676signals or exceptions 29677@item 29678the end of the process (or its beginning under @samp{--reverse}) 29679@item 29680the end or beginning of a replay log if one is being used. 29681@end itemize 29682In all-stop mode (@pxref{All-Stop 29683Mode}), may resume only one thread, or all threads, depending on the 29684value of the @samp{scheduler-locking} variable. If @samp{--all} is 29685specified, all threads (in all inferiors) will be resumed. The @samp{--all} option is 29686ignored in all-stop mode. If the @samp{--thread-group} options is 29687specified, then all threads in that thread group are resumed. 29688 29689@subsubheading @value{GDBN} Command 29690 29691The corresponding @value{GDBN} corresponding is @samp{continue}. 29692 29693@subsubheading Example 29694 29695@smallexample 29696-exec-continue 29697^running 29698(gdb) 29699@@Hello world 29700*stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame=@{ 29701func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", 29702line="13"@} 29703(gdb) 29704@end smallexample 29705 29706 29707@subheading The @code{-exec-finish} Command 29708@findex -exec-finish 29709 29710@subsubheading Synopsis 29711 29712@smallexample 29713 -exec-finish [--reverse] 29714@end smallexample 29715 29716Resumes the execution of the inferior program until the current 29717function is exited. Displays the results returned by the function. 29718If the @samp{--reverse} option is specified, resumes the reverse 29719execution of the inferior program until the point where current 29720function was called. 29721 29722@subsubheading @value{GDBN} Command 29723 29724The corresponding @value{GDBN} command is @samp{finish}. 29725 29726@subsubheading Example 29727 29728Function returning @code{void}. 29729 29730@smallexample 29731-exec-finish 29732^running 29733(gdb) 29734@@hello from foo 29735*stopped,reason="function-finished",frame=@{func="main",args=[], 29736file="hello.c",fullname="/home/foo/bar/hello.c",line="7"@} 29737(gdb) 29738@end smallexample 29739 29740Function returning other than @code{void}. The name of the internal 29741@value{GDBN} variable storing the result is printed, together with the 29742value itself. 29743 29744@smallexample 29745-exec-finish 29746^running 29747(gdb) 29748*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo", 29749args=[@{name="a",value="1"],@{name="b",value="9"@}@}, 29750file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 29751gdb-result-var="$1",return-value="0" 29752(gdb) 29753@end smallexample 29754 29755 29756@subheading The @code{-exec-interrupt} Command 29757@findex -exec-interrupt 29758 29759@subsubheading Synopsis 29760 29761@smallexample 29762 -exec-interrupt [--all|--thread-group N] 29763@end smallexample 29764 29765Interrupts the background execution of the target. Note how the token 29766associated with the stop message is the one for the execution command 29767that has been interrupted. The token for the interrupt itself only 29768appears in the @samp{^done} output. If the user is trying to 29769interrupt a non-running program, an error message will be printed. 29770 29771Note that when asynchronous execution is enabled, this command is 29772asynchronous just like other execution commands. That is, first the 29773@samp{^done} response will be printed, and the target stop will be 29774reported after that using the @samp{*stopped} notification. 29775 29776In non-stop mode, only the context thread is interrupted by default. 29777All threads (in all inferiors) will be interrupted if the 29778@samp{--all} option is specified. If the @samp{--thread-group} 29779option is specified, all threads in that group will be interrupted. 29780 29781@subsubheading @value{GDBN} Command 29782 29783The corresponding @value{GDBN} command is @samp{interrupt}. 29784 29785@subsubheading Example 29786 29787@smallexample 29788(gdb) 29789111-exec-continue 29790111^running 29791 29792(gdb) 29793222-exec-interrupt 29794222^done 29795(gdb) 29796111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", 29797frame=@{addr="0x00010140",func="foo",args=[],file="try.c", 29798fullname="/home/foo/bar/try.c",line="13"@} 29799(gdb) 29800 29801(gdb) 29802-exec-interrupt 29803^error,msg="mi_cmd_exec_interrupt: Inferior not executing." 29804(gdb) 29805@end smallexample 29806 29807@subheading The @code{-exec-jump} Command 29808@findex -exec-jump 29809 29810@subsubheading Synopsis 29811 29812@smallexample 29813 -exec-jump @var{location} 29814@end smallexample 29815 29816Resumes execution of the inferior program at the location specified by 29817parameter. @xref{Specify Location}, for a description of the 29818different forms of @var{location}. 29819 29820@subsubheading @value{GDBN} Command 29821 29822The corresponding @value{GDBN} command is @samp{jump}. 29823 29824@subsubheading Example 29825 29826@smallexample 29827-exec-jump foo.c:10 29828*running,thread-id="all" 29829^running 29830@end smallexample 29831 29832 29833@subheading The @code{-exec-next} Command 29834@findex -exec-next 29835 29836@subsubheading Synopsis 29837 29838@smallexample 29839 -exec-next [--reverse] 29840@end smallexample 29841 29842Resumes execution of the inferior program, stopping when the beginning 29843of the next source line is reached. 29844 29845If the @samp{--reverse} option is specified, resumes reverse execution 29846of the inferior program, stopping at the beginning of the previous 29847source line. If you issue this command on the first line of a 29848function, it will take you back to the caller of that function, to the 29849source line where the function was called. 29850 29851 29852@subsubheading @value{GDBN} Command 29853 29854The corresponding @value{GDBN} command is @samp{next}. 29855 29856@subsubheading Example 29857 29858@smallexample 29859-exec-next 29860^running 29861(gdb) 29862*stopped,reason="end-stepping-range",line="8",file="hello.c" 29863(gdb) 29864@end smallexample 29865 29866 29867@subheading The @code{-exec-next-instruction} Command 29868@findex -exec-next-instruction 29869 29870@subsubheading Synopsis 29871 29872@smallexample 29873 -exec-next-instruction [--reverse] 29874@end smallexample 29875 29876Executes one machine instruction. If the instruction is a function 29877call, continues until the function returns. If the program stops at an 29878instruction in the middle of a source line, the address will be 29879printed as well. 29880 29881If the @samp{--reverse} option is specified, resumes reverse execution 29882of the inferior program, stopping at the previous instruction. If the 29883previously executed instruction was a return from another function, 29884it will continue to execute in reverse until the call to that function 29885(from the current stack frame) is reached. 29886 29887@subsubheading @value{GDBN} Command 29888 29889The corresponding @value{GDBN} command is @samp{nexti}. 29890 29891@subsubheading Example 29892 29893@smallexample 29894(gdb) 29895-exec-next-instruction 29896^running 29897 29898(gdb) 29899*stopped,reason="end-stepping-range", 29900addr="0x000100d4",line="5",file="hello.c" 29901(gdb) 29902@end smallexample 29903 29904 29905@subheading The @code{-exec-return} Command 29906@findex -exec-return 29907 29908@subsubheading Synopsis 29909 29910@smallexample 29911 -exec-return 29912@end smallexample 29913 29914Makes current function return immediately. Doesn't execute the inferior. 29915Displays the new current frame. 29916 29917@subsubheading @value{GDBN} Command 29918 29919The corresponding @value{GDBN} command is @samp{return}. 29920 29921@subsubheading Example 29922 29923@smallexample 29924(gdb) 29925200-break-insert callee4 29926200^done,bkpt=@{number="1",addr="0x00010734", 29927file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} 29928(gdb) 29929000-exec-run 29930000^running 29931(gdb) 29932000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", 29933frame=@{func="callee4",args=[], 29934file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 29935fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} 29936(gdb) 29937205-break-delete 29938205^done 29939(gdb) 29940111-exec-return 29941111^done,frame=@{level="0",func="callee3", 29942args=[@{name="strarg", 29943value="0x11940 \"A string argument.\""@}], 29944file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 29945fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} 29946(gdb) 29947@end smallexample 29948 29949 29950@subheading The @code{-exec-run} Command 29951@findex -exec-run 29952 29953@subsubheading Synopsis 29954 29955@smallexample 29956 -exec-run [--all | --thread-group N] 29957@end smallexample 29958 29959Starts execution of the inferior from the beginning. The inferior 29960executes until either a breakpoint is encountered or the program 29961exits. In the latter case the output will include an exit code, if 29962the program has exited exceptionally. 29963 29964When no option is specified, the current inferior is started. If the 29965@samp{--thread-group} option is specified, it should refer to a thread 29966group of type @samp{process}, and that thread group will be started. 29967If the @samp{--all} option is specified, then all inferiors will be started. 29968 29969@subsubheading @value{GDBN} Command 29970 29971The corresponding @value{GDBN} command is @samp{run}. 29972 29973@subsubheading Examples 29974 29975@smallexample 29976(gdb) 29977-break-insert main 29978^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} 29979(gdb) 29980-exec-run 29981^running 29982(gdb) 29983*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", 29984frame=@{func="main",args=[],file="recursive2.c", 29985fullname="/home/foo/bar/recursive2.c",line="4"@} 29986(gdb) 29987@end smallexample 29988 29989@noindent 29990Program exited normally: 29991 29992@smallexample 29993(gdb) 29994-exec-run 29995^running 29996(gdb) 29997x = 55 29998*stopped,reason="exited-normally" 29999(gdb) 30000@end smallexample 30001 30002@noindent 30003Program exited exceptionally: 30004 30005@smallexample 30006(gdb) 30007-exec-run 30008^running 30009(gdb) 30010x = 55 30011*stopped,reason="exited",exit-code="01" 30012(gdb) 30013@end smallexample 30014 30015Another way the program can terminate is if it receives a signal such as 30016@code{SIGINT}. In this case, @sc{gdb/mi} displays this: 30017 30018@smallexample 30019(gdb) 30020*stopped,reason="exited-signalled",signal-name="SIGINT", 30021signal-meaning="Interrupt" 30022@end smallexample 30023 30024 30025@c @subheading -exec-signal 30026 30027 30028@subheading The @code{-exec-step} Command 30029@findex -exec-step 30030 30031@subsubheading Synopsis 30032 30033@smallexample 30034 -exec-step [--reverse] 30035@end smallexample 30036 30037Resumes execution of the inferior program, stopping when the beginning 30038of the next source line is reached, if the next source line is not a 30039function call. If it is, stop at the first instruction of the called 30040function. If the @samp{--reverse} option is specified, resumes reverse 30041execution of the inferior program, stopping at the beginning of the 30042previously executed source line. 30043 30044@subsubheading @value{GDBN} Command 30045 30046The corresponding @value{GDBN} command is @samp{step}. 30047 30048@subsubheading Example 30049 30050Stepping into a function: 30051 30052@smallexample 30053-exec-step 30054^running 30055(gdb) 30056*stopped,reason="end-stepping-range", 30057frame=@{func="foo",args=[@{name="a",value="10"@}, 30058@{name="b",value="0"@}],file="recursive2.c", 30059fullname="/home/foo/bar/recursive2.c",line="11"@} 30060(gdb) 30061@end smallexample 30062 30063Regular stepping: 30064 30065@smallexample 30066-exec-step 30067^running 30068(gdb) 30069*stopped,reason="end-stepping-range",line="14",file="recursive2.c" 30070(gdb) 30071@end smallexample 30072 30073 30074@subheading The @code{-exec-step-instruction} Command 30075@findex -exec-step-instruction 30076 30077@subsubheading Synopsis 30078 30079@smallexample 30080 -exec-step-instruction [--reverse] 30081@end smallexample 30082 30083Resumes the inferior which executes one machine instruction. If the 30084@samp{--reverse} option is specified, resumes reverse execution of the 30085inferior program, stopping at the previously executed instruction. 30086The output, once @value{GDBN} has stopped, will vary depending on 30087whether we have stopped in the middle of a source line or not. In the 30088former case, the address at which the program stopped will be printed 30089as well. 30090 30091@subsubheading @value{GDBN} Command 30092 30093The corresponding @value{GDBN} command is @samp{stepi}. 30094 30095@subsubheading Example 30096 30097@smallexample 30098(gdb) 30099-exec-step-instruction 30100^running 30101 30102(gdb) 30103*stopped,reason="end-stepping-range", 30104frame=@{func="foo",args=[],file="try.c", 30105fullname="/home/foo/bar/try.c",line="10"@} 30106(gdb) 30107-exec-step-instruction 30108^running 30109 30110(gdb) 30111*stopped,reason="end-stepping-range", 30112frame=@{addr="0x000100f4",func="foo",args=[],file="try.c", 30113fullname="/home/foo/bar/try.c",line="10"@} 30114(gdb) 30115@end smallexample 30116 30117 30118@subheading The @code{-exec-until} Command 30119@findex -exec-until 30120 30121@subsubheading Synopsis 30122 30123@smallexample 30124 -exec-until [ @var{location} ] 30125@end smallexample 30126 30127Executes the inferior until the @var{location} specified in the 30128argument is reached. If there is no argument, the inferior executes 30129until a source line greater than the current one is reached. The 30130reason for stopping in this case will be @samp{location-reached}. 30131 30132@subsubheading @value{GDBN} Command 30133 30134The corresponding @value{GDBN} command is @samp{until}. 30135 30136@subsubheading Example 30137 30138@smallexample 30139(gdb) 30140-exec-until recursive2.c:6 30141^running 30142(gdb) 30143x = 55 30144*stopped,reason="location-reached",frame=@{func="main",args=[], 30145file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"@} 30146(gdb) 30147@end smallexample 30148 30149@ignore 30150@subheading -file-clear 30151Is this going away???? 30152@end ignore 30153 30154@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 30155@node GDB/MI Stack Manipulation 30156@section @sc{gdb/mi} Stack Manipulation Commands 30157 30158 30159@subheading The @code{-stack-info-frame} Command 30160@findex -stack-info-frame 30161 30162@subsubheading Synopsis 30163 30164@smallexample 30165 -stack-info-frame 30166@end smallexample 30167 30168Get info on the selected frame. 30169 30170@subsubheading @value{GDBN} Command 30171 30172The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame} 30173(without arguments). 30174 30175@subsubheading Example 30176 30177@smallexample 30178(gdb) 30179-stack-info-frame 30180^done,frame=@{level="1",addr="0x0001076c",func="callee3", 30181file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 30182fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@} 30183(gdb) 30184@end smallexample 30185 30186@subheading The @code{-stack-info-depth} Command 30187@findex -stack-info-depth 30188 30189@subsubheading Synopsis 30190 30191@smallexample 30192 -stack-info-depth [ @var{max-depth} ] 30193@end smallexample 30194 30195Return the depth of the stack. If the integer argument @var{max-depth} 30196is specified, do not count beyond @var{max-depth} frames. 30197 30198@subsubheading @value{GDBN} Command 30199 30200There's no equivalent @value{GDBN} command. 30201 30202@subsubheading Example 30203 30204For a stack with frame levels 0 through 11: 30205 30206@smallexample 30207(gdb) 30208-stack-info-depth 30209^done,depth="12" 30210(gdb) 30211-stack-info-depth 4 30212^done,depth="4" 30213(gdb) 30214-stack-info-depth 12 30215^done,depth="12" 30216(gdb) 30217-stack-info-depth 11 30218^done,depth="11" 30219(gdb) 30220-stack-info-depth 13 30221^done,depth="12" 30222(gdb) 30223@end smallexample 30224 30225@subheading The @code{-stack-list-arguments} Command 30226@findex -stack-list-arguments 30227 30228@subsubheading Synopsis 30229 30230@smallexample 30231 -stack-list-arguments @var{print-values} 30232 [ @var{low-frame} @var{high-frame} ] 30233@end smallexample 30234 30235Display a list of the arguments for the frames between @var{low-frame} 30236and @var{high-frame} (inclusive). If @var{low-frame} and 30237@var{high-frame} are not provided, list the arguments for the whole 30238call stack. If the two arguments are equal, show the single frame 30239at the corresponding level. It is an error if @var{low-frame} is 30240larger than the actual number of frames. On the other hand, 30241@var{high-frame} may be larger than the actual number of frames, in 30242which case only existing frames will be returned. 30243 30244If @var{print-values} is 0 or @code{--no-values}, print only the names of 30245the variables; if it is 1 or @code{--all-values}, print also their 30246values; and if it is 2 or @code{--simple-values}, print the name, 30247type and value for simple data types, and the name and type for arrays, 30248structures and unions. 30249 30250Use of this command to obtain arguments in a single frame is 30251deprecated in favor of the @samp{-stack-list-variables} command. 30252 30253@subsubheading @value{GDBN} Command 30254 30255@value{GDBN} does not have an equivalent command. @code{gdbtk} has a 30256@samp{gdb_get_args} command which partially overlaps with the 30257functionality of @samp{-stack-list-arguments}. 30258 30259@subsubheading Example 30260 30261@smallexample 30262(gdb) 30263-stack-list-frames 30264^done, 30265stack=[ 30266frame=@{level="0",addr="0x00010734",func="callee4", 30267file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 30268fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}, 30269frame=@{level="1",addr="0x0001076c",func="callee3", 30270file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 30271fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}, 30272frame=@{level="2",addr="0x0001078c",func="callee2", 30273file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 30274fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"@}, 30275frame=@{level="3",addr="0x000107b4",func="callee1", 30276file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 30277fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"@}, 30278frame=@{level="4",addr="0x000107e0",func="main", 30279file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 30280fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}] 30281(gdb) 30282-stack-list-arguments 0 30283^done, 30284stack-args=[ 30285frame=@{level="0",args=[]@}, 30286frame=@{level="1",args=[name="strarg"]@}, 30287frame=@{level="2",args=[name="intarg",name="strarg"]@}, 30288frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@}, 30289frame=@{level="4",args=[]@}] 30290(gdb) 30291-stack-list-arguments 1 30292^done, 30293stack-args=[ 30294frame=@{level="0",args=[]@}, 30295frame=@{level="1", 30296 args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, 30297frame=@{level="2",args=[ 30298@{name="intarg",value="2"@}, 30299@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, 30300@{frame=@{level="3",args=[ 30301@{name="intarg",value="2"@}, 30302@{name="strarg",value="0x11940 \"A string argument.\""@}, 30303@{name="fltarg",value="3.5"@}]@}, 30304frame=@{level="4",args=[]@}] 30305(gdb) 30306-stack-list-arguments 0 2 2 30307^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}] 30308(gdb) 30309-stack-list-arguments 1 2 2 30310^done,stack-args=[frame=@{level="2", 30311args=[@{name="intarg",value="2"@}, 30312@{name="strarg",value="0x11940 \"A string argument.\""@}]@}] 30313(gdb) 30314@end smallexample 30315 30316@c @subheading -stack-list-exception-handlers 30317 30318 30319@subheading The @code{-stack-list-frames} Command 30320@findex -stack-list-frames 30321 30322@subsubheading Synopsis 30323 30324@smallexample 30325 -stack-list-frames [ @var{low-frame} @var{high-frame} ] 30326@end smallexample 30327 30328List the frames currently on the stack. For each frame it displays the 30329following info: 30330 30331@table @samp 30332@item @var{level} 30333The frame number, 0 being the topmost frame, i.e., the innermost function. 30334@item @var{addr} 30335The @code{$pc} value for that frame. 30336@item @var{func} 30337Function name. 30338@item @var{file} 30339File name of the source file where the function lives. 30340@item @var{fullname} 30341The full file name of the source file where the function lives. 30342@item @var{line} 30343Line number corresponding to the @code{$pc}. 30344@item @var{from} 30345The shared library where this function is defined. This is only given 30346if the frame's function is not known. 30347@end table 30348 30349If invoked without arguments, this command prints a backtrace for the 30350whole stack. If given two integer arguments, it shows the frames whose 30351levels are between the two arguments (inclusive). If the two arguments 30352are equal, it shows the single frame at the corresponding level. It is 30353an error if @var{low-frame} is larger than the actual number of 30354frames. On the other hand, @var{high-frame} may be larger than the 30355actual number of frames, in which case only existing frames will be returned. 30356 30357@subsubheading @value{GDBN} Command 30358 30359The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}. 30360 30361@subsubheading Example 30362 30363Full stack backtrace: 30364 30365@smallexample 30366(gdb) 30367-stack-list-frames 30368^done,stack= 30369[frame=@{level="0",addr="0x0001076c",func="foo", 30370 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"@}, 30371frame=@{level="1",addr="0x000107a4",func="foo", 30372 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 30373frame=@{level="2",addr="0x000107a4",func="foo", 30374 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 30375frame=@{level="3",addr="0x000107a4",func="foo", 30376 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 30377frame=@{level="4",addr="0x000107a4",func="foo", 30378 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 30379frame=@{level="5",addr="0x000107a4",func="foo", 30380 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 30381frame=@{level="6",addr="0x000107a4",func="foo", 30382 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 30383frame=@{level="7",addr="0x000107a4",func="foo", 30384 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 30385frame=@{level="8",addr="0x000107a4",func="foo", 30386 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 30387frame=@{level="9",addr="0x000107a4",func="foo", 30388 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 30389frame=@{level="10",addr="0x000107a4",func="foo", 30390 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 30391frame=@{level="11",addr="0x00010738",func="main", 30392 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"@}] 30393(gdb) 30394@end smallexample 30395 30396Show frames between @var{low_frame} and @var{high_frame}: 30397 30398@smallexample 30399(gdb) 30400-stack-list-frames 3 5 30401^done,stack= 30402[frame=@{level="3",addr="0x000107a4",func="foo", 30403 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 30404frame=@{level="4",addr="0x000107a4",func="foo", 30405 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 30406frame=@{level="5",addr="0x000107a4",func="foo", 30407 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}] 30408(gdb) 30409@end smallexample 30410 30411Show a single frame: 30412 30413@smallexample 30414(gdb) 30415-stack-list-frames 3 3 30416^done,stack= 30417[frame=@{level="3",addr="0x000107a4",func="foo", 30418 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}] 30419(gdb) 30420@end smallexample 30421 30422 30423@subheading The @code{-stack-list-locals} Command 30424@findex -stack-list-locals 30425 30426@subsubheading Synopsis 30427 30428@smallexample 30429 -stack-list-locals @var{print-values} 30430@end smallexample 30431 30432Display the local variable names for the selected frame. If 30433@var{print-values} is 0 or @code{--no-values}, print only the names of 30434the variables; if it is 1 or @code{--all-values}, print also their 30435values; and if it is 2 or @code{--simple-values}, print the name, 30436type and value for simple data types, and the name and type for arrays, 30437structures and unions. In this last case, a frontend can immediately 30438display the value of simple data types and create variable objects for 30439other data types when the user wishes to explore their values in 30440more detail. 30441 30442This command is deprecated in favor of the 30443@samp{-stack-list-variables} command. 30444 30445@subsubheading @value{GDBN} Command 30446 30447@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}. 30448 30449@subsubheading Example 30450 30451@smallexample 30452(gdb) 30453-stack-list-locals 0 30454^done,locals=[name="A",name="B",name="C"] 30455(gdb) 30456-stack-list-locals --all-values 30457^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@}, 30458 @{name="C",value="@{1, 2, 3@}"@}] 30459-stack-list-locals --simple-values 30460^done,locals=[@{name="A",type="int",value="1"@}, 30461 @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}] 30462(gdb) 30463@end smallexample 30464 30465@subheading The @code{-stack-list-variables} Command 30466@findex -stack-list-variables 30467 30468@subsubheading Synopsis 30469 30470@smallexample 30471 -stack-list-variables @var{print-values} 30472@end smallexample 30473 30474Display the names of local variables and function arguments for the selected frame. If 30475@var{print-values} is 0 or @code{--no-values}, print only the names of 30476the variables; if it is 1 or @code{--all-values}, print also their 30477values; and if it is 2 or @code{--simple-values}, print the name, 30478type and value for simple data types, and the name and type for arrays, 30479structures and unions. 30480 30481@subsubheading Example 30482 30483@smallexample 30484(gdb) 30485-stack-list-variables --thread 1 --frame 0 --all-values 30486^done,variables=[@{name="x",value="11"@},@{name="s",value="@{a = 1, b = 2@}"@}] 30487(gdb) 30488@end smallexample 30489 30490 30491@subheading The @code{-stack-select-frame} Command 30492@findex -stack-select-frame 30493 30494@subsubheading Synopsis 30495 30496@smallexample 30497 -stack-select-frame @var{framenum} 30498@end smallexample 30499 30500Change the selected frame. Select a different frame @var{framenum} on 30501the stack. 30502 30503This command in deprecated in favor of passing the @samp{--frame} 30504option to every command. 30505 30506@subsubheading @value{GDBN} Command 30507 30508The corresponding @value{GDBN} commands are @samp{frame}, @samp{up}, 30509@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}. 30510 30511@subsubheading Example 30512 30513@smallexample 30514(gdb) 30515-stack-select-frame 2 30516^done 30517(gdb) 30518@end smallexample 30519 30520@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 30521@node GDB/MI Variable Objects 30522@section @sc{gdb/mi} Variable Objects 30523 30524@ignore 30525 30526@subheading Motivation for Variable Objects in @sc{gdb/mi} 30527 30528For the implementation of a variable debugger window (locals, watched 30529expressions, etc.), we are proposing the adaptation of the existing code 30530used by @code{Insight}. 30531 30532The two main reasons for that are: 30533 30534@enumerate 1 30535@item 30536It has been proven in practice (it is already on its second generation). 30537 30538@item 30539It will shorten development time (needless to say how important it is 30540now). 30541@end enumerate 30542 30543The original interface was designed to be used by Tcl code, so it was 30544slightly changed so it could be used through @sc{gdb/mi}. This section 30545describes the @sc{gdb/mi} operations that will be available and gives some 30546hints about their use. 30547 30548@emph{Note}: In addition to the set of operations described here, we 30549expect the @sc{gui} implementation of a variable window to require, at 30550least, the following operations: 30551 30552@itemize @bullet 30553@item @code{-gdb-show} @code{output-radix} 30554@item @code{-stack-list-arguments} 30555@item @code{-stack-list-locals} 30556@item @code{-stack-select-frame} 30557@end itemize 30558 30559@end ignore 30560 30561@subheading Introduction to Variable Objects 30562 30563@cindex variable objects in @sc{gdb/mi} 30564 30565Variable objects are "object-oriented" MI interface for examining and 30566changing values of expressions. Unlike some other MI interfaces that 30567work with expressions, variable objects are specifically designed for 30568simple and efficient presentation in the frontend. A variable object 30569is identified by string name. When a variable object is created, the 30570frontend specifies the expression for that variable object. The 30571expression can be a simple variable, or it can be an arbitrary complex 30572expression, and can even involve CPU registers. After creating a 30573variable object, the frontend can invoke other variable object 30574operations---for example to obtain or change the value of a variable 30575object, or to change display format. 30576 30577Variable objects have hierarchical tree structure. Any variable object 30578that corresponds to a composite type, such as structure in C, has 30579a number of child variable objects, for example corresponding to each 30580element of a structure. A child variable object can itself have 30581children, recursively. Recursion ends when we reach 30582leaf variable objects, which always have built-in types. Child variable 30583objects are created only by explicit request, so if a frontend 30584is not interested in the children of a particular variable object, no 30585child will be created. 30586 30587For a leaf variable object it is possible to obtain its value as a 30588string, or set the value from a string. String value can be also 30589obtained for a non-leaf variable object, but it's generally a string 30590that only indicates the type of the object, and does not list its 30591contents. Assignment to a non-leaf variable object is not allowed. 30592 30593A frontend does not need to read the values of all variable objects each time 30594the program stops. Instead, MI provides an update command that lists all 30595variable objects whose values has changed since the last update 30596operation. This considerably reduces the amount of data that must 30597be transferred to the frontend. As noted above, children variable 30598objects are created on demand, and only leaf variable objects have a 30599real value. As result, gdb will read target memory only for leaf 30600variables that frontend has created. 30601 30602The automatic update is not always desirable. For example, a frontend 30603might want to keep a value of some expression for future reference, 30604and never update it. For another example, fetching memory is 30605relatively slow for embedded targets, so a frontend might want 30606to disable automatic update for the variables that are either not 30607visible on the screen, or ``closed''. This is possible using so 30608called ``frozen variable objects''. Such variable objects are never 30609implicitly updated. 30610 30611Variable objects can be either @dfn{fixed} or @dfn{floating}. For the 30612fixed variable object, the expression is parsed when the variable 30613object is created, including associating identifiers to specific 30614variables. The meaning of expression never changes. For a floating 30615variable object the values of variables whose names appear in the 30616expressions are re-evaluated every time in the context of the current 30617frame. Consider this example: 30618 30619@smallexample 30620void do_work(...) 30621@{ 30622 struct work_state state; 30623 30624 if (...) 30625 do_work(...); 30626@} 30627@end smallexample 30628 30629If a fixed variable object for the @code{state} variable is created in 30630this function, and we enter the recursive call, the variable 30631object will report the value of @code{state} in the top-level 30632@code{do_work} invocation. On the other hand, a floating variable 30633object will report the value of @code{state} in the current frame. 30634 30635If an expression specified when creating a fixed variable object 30636refers to a local variable, the variable object becomes bound to the 30637thread and frame in which the variable object is created. When such 30638variable object is updated, @value{GDBN} makes sure that the 30639thread/frame combination the variable object is bound to still exists, 30640and re-evaluates the variable object in context of that thread/frame. 30641 30642The following is the complete set of @sc{gdb/mi} operations defined to 30643access this functionality: 30644 30645@multitable @columnfractions .4 .6 30646@item @strong{Operation} 30647@tab @strong{Description} 30648 30649@item @code{-enable-pretty-printing} 30650@tab enable Python-based pretty-printing 30651@item @code{-var-create} 30652@tab create a variable object 30653@item @code{-var-delete} 30654@tab delete the variable object and/or its children 30655@item @code{-var-set-format} 30656@tab set the display format of this variable 30657@item @code{-var-show-format} 30658@tab show the display format of this variable 30659@item @code{-var-info-num-children} 30660@tab tells how many children this object has 30661@item @code{-var-list-children} 30662@tab return a list of the object's children 30663@item @code{-var-info-type} 30664@tab show the type of this variable object 30665@item @code{-var-info-expression} 30666@tab print parent-relative expression that this variable object represents 30667@item @code{-var-info-path-expression} 30668@tab print full expression that this variable object represents 30669@item @code{-var-show-attributes} 30670@tab is this variable editable? does it exist here? 30671@item @code{-var-evaluate-expression} 30672@tab get the value of this variable 30673@item @code{-var-assign} 30674@tab set the value of this variable 30675@item @code{-var-update} 30676@tab update the variable and its children 30677@item @code{-var-set-frozen} 30678@tab set frozeness attribute 30679@item @code{-var-set-update-range} 30680@tab set range of children to display on update 30681@end multitable 30682 30683In the next subsection we describe each operation in detail and suggest 30684how it can be used. 30685 30686@subheading Description And Use of Operations on Variable Objects 30687 30688@subheading The @code{-enable-pretty-printing} Command 30689@findex -enable-pretty-printing 30690 30691@smallexample 30692-enable-pretty-printing 30693@end smallexample 30694 30695@value{GDBN} allows Python-based visualizers to affect the output of the 30696MI variable object commands. However, because there was no way to 30697implement this in a fully backward-compatible way, a front end must 30698request that this functionality be enabled. 30699 30700Once enabled, this feature cannot be disabled. 30701 30702Note that if Python support has not been compiled into @value{GDBN}, 30703this command will still succeed (and do nothing). 30704 30705This feature is currently (as of @value{GDBN} 7.0) experimental, and 30706may work differently in future versions of @value{GDBN}. 30707 30708@subheading The @code{-var-create} Command 30709@findex -var-create 30710 30711@subsubheading Synopsis 30712 30713@smallexample 30714 -var-create @{@var{name} | "-"@} 30715 @{@var{frame-addr} | "*" | "@@"@} @var{expression} 30716@end smallexample 30717 30718This operation creates a variable object, which allows the monitoring of 30719a variable, the result of an expression, a memory cell or a CPU 30720register. 30721 30722The @var{name} parameter is the string by which the object can be 30723referenced. It must be unique. If @samp{-} is specified, the varobj 30724system will generate a string ``varNNNNNN'' automatically. It will be 30725unique provided that one does not specify @var{name} of that format. 30726The command fails if a duplicate name is found. 30727 30728The frame under which the expression should be evaluated can be 30729specified by @var{frame-addr}. A @samp{*} indicates that the current 30730frame should be used. A @samp{@@} indicates that a floating variable 30731object must be created. 30732 30733@var{expression} is any expression valid on the current language set (must not 30734begin with a @samp{*}), or one of the following: 30735 30736@itemize @bullet 30737@item 30738@samp{*@var{addr}}, where @var{addr} is the address of a memory cell 30739 30740@item 30741@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD) 30742 30743@item 30744@samp{$@var{regname}} --- a CPU register name 30745@end itemize 30746 30747@cindex dynamic varobj 30748A varobj's contents may be provided by a Python-based pretty-printer. In this 30749case the varobj is known as a @dfn{dynamic varobj}. Dynamic varobjs 30750have slightly different semantics in some cases. If the 30751@code{-enable-pretty-printing} command is not sent, then @value{GDBN} 30752will never create a dynamic varobj. This ensures backward 30753compatibility for existing clients. 30754 30755@subsubheading Result 30756 30757This operation returns attributes of the newly-created varobj. These 30758are: 30759 30760@table @samp 30761@item name 30762The name of the varobj. 30763 30764@item numchild 30765The number of children of the varobj. This number is not necessarily 30766reliable for a dynamic varobj. Instead, you must examine the 30767@samp{has_more} attribute. 30768 30769@item value 30770The varobj's scalar value. For a varobj whose type is some sort of 30771aggregate (e.g., a @code{struct}), or for a dynamic varobj, this value 30772will not be interesting. 30773 30774@item type 30775The varobj's type. This is a string representation of the type, as 30776would be printed by the @value{GDBN} CLI. If @samp{print object} 30777(@pxref{Print Settings, set print object}) is set to @code{on}, the 30778@emph{actual} (derived) type of the object is shown rather than the 30779@emph{declared} one. 30780 30781@item thread-id 30782If a variable object is bound to a specific thread, then this is the 30783thread's identifier. 30784 30785@item has_more 30786For a dynamic varobj, this indicates whether there appear to be any 30787children available. For a non-dynamic varobj, this will be 0. 30788 30789@item dynamic 30790This attribute will be present and have the value @samp{1} if the 30791varobj is a dynamic varobj. If the varobj is not a dynamic varobj, 30792then this attribute will not be present. 30793 30794@item displayhint 30795A dynamic varobj can supply a display hint to the front end. The 30796value comes directly from the Python pretty-printer object's 30797@code{display_hint} method. @xref{Pretty Printing API}. 30798@end table 30799 30800Typical output will look like this: 30801 30802@smallexample 30803 name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}", 30804 has_more="@var{has_more}" 30805@end smallexample 30806 30807 30808@subheading The @code{-var-delete} Command 30809@findex -var-delete 30810 30811@subsubheading Synopsis 30812 30813@smallexample 30814 -var-delete [ -c ] @var{name} 30815@end smallexample 30816 30817Deletes a previously created variable object and all of its children. 30818With the @samp{-c} option, just deletes the children. 30819 30820Returns an error if the object @var{name} is not found. 30821 30822 30823@subheading The @code{-var-set-format} Command 30824@findex -var-set-format 30825 30826@subsubheading Synopsis 30827 30828@smallexample 30829 -var-set-format @var{name} @var{format-spec} 30830@end smallexample 30831 30832Sets the output format for the value of the object @var{name} to be 30833@var{format-spec}. 30834 30835@anchor{-var-set-format} 30836The syntax for the @var{format-spec} is as follows: 30837 30838@smallexample 30839 @var{format-spec} @expansion{} 30840 @{binary | decimal | hexadecimal | octal | natural@} 30841@end smallexample 30842 30843The natural format is the default format choosen automatically 30844based on the variable type (like decimal for an @code{int}, hex 30845for pointers, etc.). 30846 30847For a variable with children, the format is set only on the 30848variable itself, and the children are not affected. 30849 30850@subheading The @code{-var-show-format} Command 30851@findex -var-show-format 30852 30853@subsubheading Synopsis 30854 30855@smallexample 30856 -var-show-format @var{name} 30857@end smallexample 30858 30859Returns the format used to display the value of the object @var{name}. 30860 30861@smallexample 30862 @var{format} @expansion{} 30863 @var{format-spec} 30864@end smallexample 30865 30866 30867@subheading The @code{-var-info-num-children} Command 30868@findex -var-info-num-children 30869 30870@subsubheading Synopsis 30871 30872@smallexample 30873 -var-info-num-children @var{name} 30874@end smallexample 30875 30876Returns the number of children of a variable object @var{name}: 30877 30878@smallexample 30879 numchild=@var{n} 30880@end smallexample 30881 30882Note that this number is not completely reliable for a dynamic varobj. 30883It will return the current number of children, but more children may 30884be available. 30885 30886 30887@subheading The @code{-var-list-children} Command 30888@findex -var-list-children 30889 30890@subsubheading Synopsis 30891 30892@smallexample 30893 -var-list-children [@var{print-values}] @var{name} [@var{from} @var{to}] 30894@end smallexample 30895@anchor{-var-list-children} 30896 30897Return a list of the children of the specified variable object and 30898create variable objects for them, if they do not already exist. With 30899a single argument or if @var{print-values} has a value of 0 or 30900@code{--no-values}, print only the names of the variables; if 30901@var{print-values} is 1 or @code{--all-values}, also print their 30902values; and if it is 2 or @code{--simple-values} print the name and 30903value for simple data types and just the name for arrays, structures 30904and unions. 30905 30906@var{from} and @var{to}, if specified, indicate the range of children 30907to report. If @var{from} or @var{to} is less than zero, the range is 30908reset and all children will be reported. Otherwise, children starting 30909at @var{from} (zero-based) and up to and excluding @var{to} will be 30910reported. 30911 30912If a child range is requested, it will only affect the current call to 30913@code{-var-list-children}, but not future calls to @code{-var-update}. 30914For this, you must instead use @code{-var-set-update-range}. The 30915intent of this approach is to enable a front end to implement any 30916update approach it likes; for example, scrolling a view may cause the 30917front end to request more children with @code{-var-list-children}, and 30918then the front end could call @code{-var-set-update-range} with a 30919different range to ensure that future updates are restricted to just 30920the visible items. 30921 30922For each child the following results are returned: 30923 30924@table @var 30925 30926@item name 30927Name of the variable object created for this child. 30928 30929@item exp 30930The expression to be shown to the user by the front end to designate this child. 30931For example this may be the name of a structure member. 30932 30933For a dynamic varobj, this value cannot be used to form an 30934expression. There is no way to do this at all with a dynamic varobj. 30935 30936For C/C@t{++} structures there are several pseudo children returned to 30937designate access qualifiers. For these pseudo children @var{exp} is 30938@samp{public}, @samp{private}, or @samp{protected}. In this case the 30939type and value are not present. 30940 30941A dynamic varobj will not report the access qualifying 30942pseudo-children, regardless of the language. This information is not 30943available at all with a dynamic varobj. 30944 30945@item numchild 30946Number of children this child has. For a dynamic varobj, this will be 309470. 30948 30949@item type 30950The type of the child. If @samp{print object} 30951(@pxref{Print Settings, set print object}) is set to @code{on}, the 30952@emph{actual} (derived) type of the object is shown rather than the 30953@emph{declared} one. 30954 30955@item value 30956If values were requested, this is the value. 30957 30958@item thread-id 30959If this variable object is associated with a thread, this is the thread id. 30960Otherwise this result is not present. 30961 30962@item frozen 30963If the variable object is frozen, this variable will be present with a value of 1. 30964@end table 30965 30966The result may have its own attributes: 30967 30968@table @samp 30969@item displayhint 30970A dynamic varobj can supply a display hint to the front end. The 30971value comes directly from the Python pretty-printer object's 30972@code{display_hint} method. @xref{Pretty Printing API}. 30973 30974@item has_more 30975This is an integer attribute which is nonzero if there are children 30976remaining after the end of the selected range. 30977@end table 30978 30979@subsubheading Example 30980 30981@smallexample 30982(gdb) 30983 -var-list-children n 30984 ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp}, 30985 numchild=@var{n},type=@var{type}@},@r{(repeats N times)}] 30986(gdb) 30987 -var-list-children --all-values n 30988 ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp}, 30989 numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}] 30990@end smallexample 30991 30992 30993@subheading The @code{-var-info-type} Command 30994@findex -var-info-type 30995 30996@subsubheading Synopsis 30997 30998@smallexample 30999 -var-info-type @var{name} 31000@end smallexample 31001 31002Returns the type of the specified variable @var{name}. The type is 31003returned as a string in the same format as it is output by the 31004@value{GDBN} CLI: 31005 31006@smallexample 31007 type=@var{typename} 31008@end smallexample 31009 31010 31011@subheading The @code{-var-info-expression} Command 31012@findex -var-info-expression 31013 31014@subsubheading Synopsis 31015 31016@smallexample 31017 -var-info-expression @var{name} 31018@end smallexample 31019 31020Returns a string that is suitable for presenting this 31021variable object in user interface. The string is generally 31022not valid expression in the current language, and cannot be evaluated. 31023 31024For example, if @code{a} is an array, and variable object 31025@code{A} was created for @code{a}, then we'll get this output: 31026 31027@smallexample 31028(gdb) -var-info-expression A.1 31029^done,lang="C",exp="1" 31030@end smallexample 31031 31032@noindent 31033Here, the values of @code{lang} can be @code{@{"C" | "C++" | "Java"@}}. 31034 31035Note that the output of the @code{-var-list-children} command also 31036includes those expressions, so the @code{-var-info-expression} command 31037is of limited use. 31038 31039@subheading The @code{-var-info-path-expression} Command 31040@findex -var-info-path-expression 31041 31042@subsubheading Synopsis 31043 31044@smallexample 31045 -var-info-path-expression @var{name} 31046@end smallexample 31047 31048Returns an expression that can be evaluated in the current 31049context and will yield the same value that a variable object has. 31050Compare this with the @code{-var-info-expression} command, which 31051result can be used only for UI presentation. Typical use of 31052the @code{-var-info-path-expression} command is creating a 31053watchpoint from a variable object. 31054 31055This command is currently not valid for children of a dynamic varobj, 31056and will give an error when invoked on one. 31057 31058For example, suppose @code{C} is a C@t{++} class, derived from class 31059@code{Base}, and that the @code{Base} class has a member called 31060@code{m_size}. Assume a variable @code{c} is has the type of 31061@code{C} and a variable object @code{C} was created for variable 31062@code{c}. Then, we'll get this output: 31063@smallexample 31064(gdb) -var-info-path-expression C.Base.public.m_size 31065^done,path_expr=((Base)c).m_size) 31066@end smallexample 31067 31068@subheading The @code{-var-show-attributes} Command 31069@findex -var-show-attributes 31070 31071@subsubheading Synopsis 31072 31073@smallexample 31074 -var-show-attributes @var{name} 31075@end smallexample 31076 31077List attributes of the specified variable object @var{name}: 31078 31079@smallexample 31080 status=@var{attr} [ ( ,@var{attr} )* ] 31081@end smallexample 31082 31083@noindent 31084where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}. 31085 31086@subheading The @code{-var-evaluate-expression} Command 31087@findex -var-evaluate-expression 31088 31089@subsubheading Synopsis 31090 31091@smallexample 31092 -var-evaluate-expression [-f @var{format-spec}] @var{name} 31093@end smallexample 31094 31095Evaluates the expression that is represented by the specified variable 31096object and returns its value as a string. The format of the string 31097can be specified with the @samp{-f} option. The possible values of 31098this option are the same as for @code{-var-set-format} 31099(@pxref{-var-set-format}). If the @samp{-f} option is not specified, 31100the current display format will be used. The current display format 31101can be changed using the @code{-var-set-format} command. 31102 31103@smallexample 31104 value=@var{value} 31105@end smallexample 31106 31107Note that one must invoke @code{-var-list-children} for a variable 31108before the value of a child variable can be evaluated. 31109 31110@subheading The @code{-var-assign} Command 31111@findex -var-assign 31112 31113@subsubheading Synopsis 31114 31115@smallexample 31116 -var-assign @var{name} @var{expression} 31117@end smallexample 31118 31119Assigns the value of @var{expression} to the variable object specified 31120by @var{name}. The object must be @samp{editable}. If the variable's 31121value is altered by the assign, the variable will show up in any 31122subsequent @code{-var-update} list. 31123 31124@subsubheading Example 31125 31126@smallexample 31127(gdb) 31128-var-assign var1 3 31129^done,value="3" 31130(gdb) 31131-var-update * 31132^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}] 31133(gdb) 31134@end smallexample 31135 31136@subheading The @code{-var-update} Command 31137@findex -var-update 31138 31139@subsubheading Synopsis 31140 31141@smallexample 31142 -var-update [@var{print-values}] @{@var{name} | "*"@} 31143@end smallexample 31144 31145Reevaluate the expressions corresponding to the variable object 31146@var{name} and all its direct and indirect children, and return the 31147list of variable objects whose values have changed; @var{name} must 31148be a root variable object. Here, ``changed'' means that the result of 31149@code{-var-evaluate-expression} before and after the 31150@code{-var-update} is different. If @samp{*} is used as the variable 31151object names, all existing variable objects are updated, except 31152for frozen ones (@pxref{-var-set-frozen}). The option 31153@var{print-values} determines whether both names and values, or just 31154names are printed. The possible values of this option are the same 31155as for @code{-var-list-children} (@pxref{-var-list-children}). It is 31156recommended to use the @samp{--all-values} option, to reduce the 31157number of MI commands needed on each program stop. 31158 31159With the @samp{*} parameter, if a variable object is bound to a 31160currently running thread, it will not be updated, without any 31161diagnostic. 31162 31163If @code{-var-set-update-range} was previously used on a varobj, then 31164only the selected range of children will be reported. 31165 31166@code{-var-update} reports all the changed varobjs in a tuple named 31167@samp{changelist}. 31168 31169Each item in the change list is itself a tuple holding: 31170 31171@table @samp 31172@item name 31173The name of the varobj. 31174 31175@item value 31176If values were requested for this update, then this field will be 31177present and will hold the value of the varobj. 31178 31179@item in_scope 31180@anchor{-var-update} 31181This field is a string which may take one of three values: 31182 31183@table @code 31184@item "true" 31185The variable object's current value is valid. 31186 31187@item "false" 31188The variable object does not currently hold a valid value but it may 31189hold one in the future if its associated expression comes back into 31190scope. 31191 31192@item "invalid" 31193The variable object no longer holds a valid value. 31194This can occur when the executable file being debugged has changed, 31195either through recompilation or by using the @value{GDBN} @code{file} 31196command. The front end should normally choose to delete these variable 31197objects. 31198@end table 31199 31200In the future new values may be added to this list so the front should 31201be prepared for this possibility. @xref{GDB/MI Development and Front Ends, ,@sc{GDB/MI} Development and Front Ends}. 31202 31203@item type_changed 31204This is only present if the varobj is still valid. If the type 31205changed, then this will be the string @samp{true}; otherwise it will 31206be @samp{false}. 31207 31208When a varobj's type changes, its children are also likely to have 31209become incorrect. Therefore, the varobj's children are automatically 31210deleted when this attribute is @samp{true}. Also, the varobj's update 31211range, when set using the @code{-var-set-update-range} command, is 31212unset. 31213 31214@item new_type 31215If the varobj's type changed, then this field will be present and will 31216hold the new type. 31217 31218@item new_num_children 31219For a dynamic varobj, if the number of children changed, or if the 31220type changed, this will be the new number of children. 31221 31222The @samp{numchild} field in other varobj responses is generally not 31223valid for a dynamic varobj -- it will show the number of children that 31224@value{GDBN} knows about, but because dynamic varobjs lazily 31225instantiate their children, this will not reflect the number of 31226children which may be available. 31227 31228The @samp{new_num_children} attribute only reports changes to the 31229number of children known by @value{GDBN}. This is the only way to 31230detect whether an update has removed children (which necessarily can 31231only happen at the end of the update range). 31232 31233@item displayhint 31234The display hint, if any. 31235 31236@item has_more 31237This is an integer value, which will be 1 if there are more children 31238available outside the varobj's update range. 31239 31240@item dynamic 31241This attribute will be present and have the value @samp{1} if the 31242varobj is a dynamic varobj. If the varobj is not a dynamic varobj, 31243then this attribute will not be present. 31244 31245@item new_children 31246If new children were added to a dynamic varobj within the selected 31247update range (as set by @code{-var-set-update-range}), then they will 31248be listed in this attribute. 31249@end table 31250 31251@subsubheading Example 31252 31253@smallexample 31254(gdb) 31255-var-assign var1 3 31256^done,value="3" 31257(gdb) 31258-var-update --all-values var1 31259^done,changelist=[@{name="var1",value="3",in_scope="true", 31260type_changed="false"@}] 31261(gdb) 31262@end smallexample 31263 31264@subheading The @code{-var-set-frozen} Command 31265@findex -var-set-frozen 31266@anchor{-var-set-frozen} 31267 31268@subsubheading Synopsis 31269 31270@smallexample 31271 -var-set-frozen @var{name} @var{flag} 31272@end smallexample 31273 31274Set the frozenness flag on the variable object @var{name}. The 31275@var{flag} parameter should be either @samp{1} to make the variable 31276frozen or @samp{0} to make it unfrozen. If a variable object is 31277frozen, then neither itself, nor any of its children, are 31278implicitly updated by @code{-var-update} of 31279a parent variable or by @code{-var-update *}. Only 31280@code{-var-update} of the variable itself will update its value and 31281values of its children. After a variable object is unfrozen, it is 31282implicitly updated by all subsequent @code{-var-update} operations. 31283Unfreezing a variable does not update it, only subsequent 31284@code{-var-update} does. 31285 31286@subsubheading Example 31287 31288@smallexample 31289(gdb) 31290-var-set-frozen V 1 31291^done 31292(gdb) 31293@end smallexample 31294 31295@subheading The @code{-var-set-update-range} command 31296@findex -var-set-update-range 31297@anchor{-var-set-update-range} 31298 31299@subsubheading Synopsis 31300 31301@smallexample 31302 -var-set-update-range @var{name} @var{from} @var{to} 31303@end smallexample 31304 31305Set the range of children to be returned by future invocations of 31306@code{-var-update}. 31307 31308@var{from} and @var{to} indicate the range of children to report. If 31309@var{from} or @var{to} is less than zero, the range is reset and all 31310children will be reported. Otherwise, children starting at @var{from} 31311(zero-based) and up to and excluding @var{to} will be reported. 31312 31313@subsubheading Example 31314 31315@smallexample 31316(gdb) 31317-var-set-update-range V 1 2 31318^done 31319@end smallexample 31320 31321@subheading The @code{-var-set-visualizer} command 31322@findex -var-set-visualizer 31323@anchor{-var-set-visualizer} 31324 31325@subsubheading Synopsis 31326 31327@smallexample 31328 -var-set-visualizer @var{name} @var{visualizer} 31329@end smallexample 31330 31331Set a visualizer for the variable object @var{name}. 31332 31333@var{visualizer} is the visualizer to use. The special value 31334@samp{None} means to disable any visualizer in use. 31335 31336If not @samp{None}, @var{visualizer} must be a Python expression. 31337This expression must evaluate to a callable object which accepts a 31338single argument. @value{GDBN} will call this object with the value of 31339the varobj @var{name} as an argument (this is done so that the same 31340Python pretty-printing code can be used for both the CLI and MI). 31341When called, this object must return an object which conforms to the 31342pretty-printing interface (@pxref{Pretty Printing API}). 31343 31344The pre-defined function @code{gdb.default_visualizer} may be used to 31345select a visualizer by following the built-in process 31346(@pxref{Selecting Pretty-Printers}). This is done automatically when 31347a varobj is created, and so ordinarily is not needed. 31348 31349This feature is only available if Python support is enabled. The MI 31350command @code{-list-features} (@pxref{GDB/MI Miscellaneous Commands}) 31351can be used to check this. 31352 31353@subsubheading Example 31354 31355Resetting the visualizer: 31356 31357@smallexample 31358(gdb) 31359-var-set-visualizer V None 31360^done 31361@end smallexample 31362 31363Reselecting the default (type-based) visualizer: 31364 31365@smallexample 31366(gdb) 31367-var-set-visualizer V gdb.default_visualizer 31368^done 31369@end smallexample 31370 31371Suppose @code{SomeClass} is a visualizer class. A lambda expression 31372can be used to instantiate this class for a varobj: 31373 31374@smallexample 31375(gdb) 31376-var-set-visualizer V "lambda val: SomeClass()" 31377^done 31378@end smallexample 31379 31380@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 31381@node GDB/MI Data Manipulation 31382@section @sc{gdb/mi} Data Manipulation 31383 31384@cindex data manipulation, in @sc{gdb/mi} 31385@cindex @sc{gdb/mi}, data manipulation 31386This section describes the @sc{gdb/mi} commands that manipulate data: 31387examine memory and registers, evaluate expressions, etc. 31388 31389@c REMOVED FROM THE INTERFACE. 31390@c @subheading -data-assign 31391@c Change the value of a program variable. Plenty of side effects. 31392@c @subsubheading GDB Command 31393@c set variable 31394@c @subsubheading Example 31395@c N.A. 31396 31397@subheading The @code{-data-disassemble} Command 31398@findex -data-disassemble 31399 31400@subsubheading Synopsis 31401 31402@smallexample 31403 -data-disassemble 31404 [ -s @var{start-addr} -e @var{end-addr} ] 31405 | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ] 31406 -- @var{mode} 31407@end smallexample 31408 31409@noindent 31410Where: 31411 31412@table @samp 31413@item @var{start-addr} 31414is the beginning address (or @code{$pc}) 31415@item @var{end-addr} 31416is the end address 31417@item @var{filename} 31418is the name of the file to disassemble 31419@item @var{linenum} 31420is the line number to disassemble around 31421@item @var{lines} 31422is the number of disassembly lines to be produced. If it is -1, 31423the whole function will be disassembled, in case no @var{end-addr} is 31424specified. If @var{end-addr} is specified as a non-zero value, and 31425@var{lines} is lower than the number of disassembly lines between 31426@var{start-addr} and @var{end-addr}, only @var{lines} lines are 31427displayed; if @var{lines} is higher than the number of lines between 31428@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr} 31429are displayed. 31430@item @var{mode} 31431is either 0 (meaning only disassembly), 1 (meaning mixed source and 31432disassembly), 2 (meaning disassembly with raw opcodes), or 3 (meaning 31433mixed source and disassembly with raw opcodes). 31434@end table 31435 31436@subsubheading Result 31437 31438The result of the @code{-data-disassemble} command will be a list named 31439@samp{asm_insns}, the contents of this list depend on the @var{mode} 31440used with the @code{-data-disassemble} command. 31441 31442For modes 0 and 2 the @samp{asm_insns} list contains tuples with the 31443following fields: 31444 31445@table @code 31446@item address 31447The address at which this instruction was disassembled. 31448 31449@item func-name 31450The name of the function this instruction is within. 31451 31452@item offset 31453The decimal offset in bytes from the start of @samp{func-name}. 31454 31455@item inst 31456The text disassembly for this @samp{address}. 31457 31458@item opcodes 31459This field is only present for mode 2. This contains the raw opcode 31460bytes for the @samp{inst} field. 31461 31462@end table 31463 31464For modes 1 and 3 the @samp{asm_insns} list contains tuples named 31465@samp{src_and_asm_line}, each of which has the following fields: 31466 31467@table @code 31468@item line 31469The line number within @samp{file}. 31470 31471@item file 31472The file name from the compilation unit. This might be an absolute 31473file name or a relative file name depending on the compile command 31474used. 31475 31476@item fullname 31477Absolute file name of @samp{file}. It is converted to a canonical form 31478using the source file search path 31479(@pxref{Source Path, ,Specifying Source Directories}) 31480and after resolving all the symbolic links. 31481 31482If the source file is not found this field will contain the path as 31483present in the debug information. 31484 31485@item line_asm_insn 31486This is a list of tuples containing the disassembly for @samp{line} in 31487@samp{file}. The fields of each tuple are the same as for 31488@code{-data-disassemble} in @var{mode} 0 and 2, so @samp{address}, 31489@samp{func-name}, @samp{offset}, @samp{inst}, and optionally 31490@samp{opcodes}. 31491 31492@end table 31493 31494Note that whatever included in the @samp{inst} field, is not 31495manipulated directly by @sc{gdb/mi}, i.e., it is not possible to 31496adjust its format. 31497 31498@subsubheading @value{GDBN} Command 31499 31500The corresponding @value{GDBN} command is @samp{disassemble}. 31501 31502@subsubheading Example 31503 31504Disassemble from the current value of @code{$pc} to @code{$pc + 20}: 31505 31506@smallexample 31507(gdb) 31508-data-disassemble -s $pc -e "$pc + 20" -- 0 31509^done, 31510asm_insns=[ 31511@{address="0x000107c0",func-name="main",offset="4", 31512inst="mov 2, %o0"@}, 31513@{address="0x000107c4",func-name="main",offset="8", 31514inst="sethi %hi(0x11800), %o2"@}, 31515@{address="0x000107c8",func-name="main",offset="12", 31516inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@}, 31517@{address="0x000107cc",func-name="main",offset="16", 31518inst="sethi %hi(0x11800), %o2"@}, 31519@{address="0x000107d0",func-name="main",offset="20", 31520inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}] 31521(gdb) 31522@end smallexample 31523 31524Disassemble the whole @code{main} function. Line 32 is part of 31525@code{main}. 31526 31527@smallexample 31528-data-disassemble -f basics.c -l 32 -- 0 31529^done,asm_insns=[ 31530@{address="0x000107bc",func-name="main",offset="0", 31531inst="save %sp, -112, %sp"@}, 31532@{address="0x000107c0",func-name="main",offset="4", 31533inst="mov 2, %o0"@}, 31534@{address="0x000107c4",func-name="main",offset="8", 31535inst="sethi %hi(0x11800), %o2"@}, 31536[@dots{}] 31537@{address="0x0001081c",func-name="main",offset="96",inst="ret "@}, 31538@{address="0x00010820",func-name="main",offset="100",inst="restore "@}] 31539(gdb) 31540@end smallexample 31541 31542Disassemble 3 instructions from the start of @code{main}: 31543 31544@smallexample 31545(gdb) 31546-data-disassemble -f basics.c -l 32 -n 3 -- 0 31547^done,asm_insns=[ 31548@{address="0x000107bc",func-name="main",offset="0", 31549inst="save %sp, -112, %sp"@}, 31550@{address="0x000107c0",func-name="main",offset="4", 31551inst="mov 2, %o0"@}, 31552@{address="0x000107c4",func-name="main",offset="8", 31553inst="sethi %hi(0x11800), %o2"@}] 31554(gdb) 31555@end smallexample 31556 31557Disassemble 3 instructions from the start of @code{main} in mixed mode: 31558 31559@smallexample 31560(gdb) 31561-data-disassemble -f basics.c -l 32 -n 3 -- 1 31562^done,asm_insns=[ 31563src_and_asm_line=@{line="31", 31564file="../../../src/gdb/testsuite/gdb.mi/basics.c", 31565fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c", 31566line_asm_insn=[@{address="0x000107bc", 31567func-name="main",offset="0",inst="save %sp, -112, %sp"@}]@}, 31568src_and_asm_line=@{line="32", 31569file="../../../src/gdb/testsuite/gdb.mi/basics.c", 31570fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c", 31571line_asm_insn=[@{address="0x000107c0", 31572func-name="main",offset="4",inst="mov 2, %o0"@}, 31573@{address="0x000107c4",func-name="main",offset="8", 31574inst="sethi %hi(0x11800), %o2"@}]@}] 31575(gdb) 31576@end smallexample 31577 31578 31579@subheading The @code{-data-evaluate-expression} Command 31580@findex -data-evaluate-expression 31581 31582@subsubheading Synopsis 31583 31584@smallexample 31585 -data-evaluate-expression @var{expr} 31586@end smallexample 31587 31588Evaluate @var{expr} as an expression. The expression could contain an 31589inferior function call. The function call will execute synchronously. 31590If the expression contains spaces, it must be enclosed in double quotes. 31591 31592@subsubheading @value{GDBN} Command 31593 31594The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and 31595@samp{call}. In @code{gdbtk} only, there's a corresponding 31596@samp{gdb_eval} command. 31597 31598@subsubheading Example 31599 31600In the following example, the numbers that precede the commands are the 31601@dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi} 31602Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its 31603output. 31604 31605@smallexample 31606211-data-evaluate-expression A 31607211^done,value="1" 31608(gdb) 31609311-data-evaluate-expression &A 31610311^done,value="0xefffeb7c" 31611(gdb) 31612411-data-evaluate-expression A+3 31613411^done,value="4" 31614(gdb) 31615511-data-evaluate-expression "A + 3" 31616511^done,value="4" 31617(gdb) 31618@end smallexample 31619 31620 31621@subheading The @code{-data-list-changed-registers} Command 31622@findex -data-list-changed-registers 31623 31624@subsubheading Synopsis 31625 31626@smallexample 31627 -data-list-changed-registers 31628@end smallexample 31629 31630Display a list of the registers that have changed. 31631 31632@subsubheading @value{GDBN} Command 31633 31634@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk} 31635has the corresponding command @samp{gdb_changed_register_list}. 31636 31637@subsubheading Example 31638 31639On a PPC MBX board: 31640 31641@smallexample 31642(gdb) 31643-exec-continue 31644^running 31645 31646(gdb) 31647*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame=@{ 31648func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c", 31649line="5"@} 31650(gdb) 31651-data-list-changed-registers 31652^done,changed-registers=["0","1","2","4","5","6","7","8","9", 31653"10","11","13","14","15","16","17","18","19","20","21","22","23", 31654"24","25","26","27","28","30","31","64","65","66","67","69"] 31655(gdb) 31656@end smallexample 31657 31658 31659@subheading The @code{-data-list-register-names} Command 31660@findex -data-list-register-names 31661 31662@subsubheading Synopsis 31663 31664@smallexample 31665 -data-list-register-names [ ( @var{regno} )+ ] 31666@end smallexample 31667 31668Show a list of register names for the current target. If no arguments 31669are given, it shows a list of the names of all the registers. If 31670integer numbers are given as arguments, it will print a list of the 31671names of the registers corresponding to the arguments. To ensure 31672consistency between a register name and its number, the output list may 31673include empty register names. 31674 31675@subsubheading @value{GDBN} Command 31676 31677@value{GDBN} does not have a command which corresponds to 31678@samp{-data-list-register-names}. In @code{gdbtk} there is a 31679corresponding command @samp{gdb_regnames}. 31680 31681@subsubheading Example 31682 31683For the PPC MBX board: 31684@smallexample 31685(gdb) 31686-data-list-register-names 31687^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", 31688"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", 31689"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", 31690"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", 31691"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", 31692"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", 31693"", "pc","ps","cr","lr","ctr","xer"] 31694(gdb) 31695-data-list-register-names 1 2 3 31696^done,register-names=["r1","r2","r3"] 31697(gdb) 31698@end smallexample 31699 31700@subheading The @code{-data-list-register-values} Command 31701@findex -data-list-register-values 31702 31703@subsubheading Synopsis 31704 31705@smallexample 31706 -data-list-register-values @var{fmt} [ ( @var{regno} )*] 31707@end smallexample 31708 31709Display the registers' contents. @var{fmt} is the format according to 31710which the registers' contents are to be returned, followed by an optional 31711list of numbers specifying the registers to display. A missing list of 31712numbers indicates that the contents of all the registers must be returned. 31713 31714Allowed formats for @var{fmt} are: 31715 31716@table @code 31717@item x 31718Hexadecimal 31719@item o 31720Octal 31721@item t 31722Binary 31723@item d 31724Decimal 31725@item r 31726Raw 31727@item N 31728Natural 31729@end table 31730 31731@subsubheading @value{GDBN} Command 31732 31733The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info 31734all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}. 31735 31736@subsubheading Example 31737 31738For a PPC MBX board (note: line breaks are for readability only, they 31739don't appear in the actual output): 31740 31741@smallexample 31742(gdb) 31743-data-list-register-values r 64 65 31744^done,register-values=[@{number="64",value="0xfe00a300"@}, 31745@{number="65",value="0x00029002"@}] 31746(gdb) 31747-data-list-register-values x 31748^done,register-values=[@{number="0",value="0xfe0043c8"@}, 31749@{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@}, 31750@{number="3",value="0x0"@},@{number="4",value="0xa"@}, 31751@{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@}, 31752@{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@}, 31753@{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@}, 31754@{number="11",value="0x1"@},@{number="12",value="0x0"@}, 31755@{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@}, 31756@{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@}, 31757@{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@}, 31758@{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@}, 31759@{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@}, 31760@{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@}, 31761@{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@}, 31762@{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@}, 31763@{number="29",value="0x0"@},@{number="30",value="0xfe010000"@}, 31764@{number="31",value="0x0"@},@{number="32",value="0x0"@}, 31765@{number="33",value="0x0"@},@{number="34",value="0x0"@}, 31766@{number="35",value="0x0"@},@{number="36",value="0x0"@}, 31767@{number="37",value="0x0"@},@{number="38",value="0x0"@}, 31768@{number="39",value="0x0"@},@{number="40",value="0x0"@}, 31769@{number="41",value="0x0"@},@{number="42",value="0x0"@}, 31770@{number="43",value="0x0"@},@{number="44",value="0x0"@}, 31771@{number="45",value="0x0"@},@{number="46",value="0x0"@}, 31772@{number="47",value="0x0"@},@{number="48",value="0x0"@}, 31773@{number="49",value="0x0"@},@{number="50",value="0x0"@}, 31774@{number="51",value="0x0"@},@{number="52",value="0x0"@}, 31775@{number="53",value="0x0"@},@{number="54",value="0x0"@}, 31776@{number="55",value="0x0"@},@{number="56",value="0x0"@}, 31777@{number="57",value="0x0"@},@{number="58",value="0x0"@}, 31778@{number="59",value="0x0"@},@{number="60",value="0x0"@}, 31779@{number="61",value="0x0"@},@{number="62",value="0x0"@}, 31780@{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@}, 31781@{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@}, 31782@{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@}, 31783@{number="69",value="0x20002b03"@}] 31784(gdb) 31785@end smallexample 31786 31787 31788@subheading The @code{-data-read-memory} Command 31789@findex -data-read-memory 31790 31791This command is deprecated, use @code{-data-read-memory-bytes} instead. 31792 31793@subsubheading Synopsis 31794 31795@smallexample 31796 -data-read-memory [ -o @var{byte-offset} ] 31797 @var{address} @var{word-format} @var{word-size} 31798 @var{nr-rows} @var{nr-cols} [ @var{aschar} ] 31799@end smallexample 31800 31801@noindent 31802where: 31803 31804@table @samp 31805@item @var{address} 31806An expression specifying the address of the first memory word to be 31807read. Complex expressions containing embedded white space should be 31808quoted using the C convention. 31809 31810@item @var{word-format} 31811The format to be used to print the memory words. The notation is the 31812same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats, 31813,Output Formats}). 31814 31815@item @var{word-size} 31816The size of each memory word in bytes. 31817 31818@item @var{nr-rows} 31819The number of rows in the output table. 31820 31821@item @var{nr-cols} 31822The number of columns in the output table. 31823 31824@item @var{aschar} 31825If present, indicates that each row should include an @sc{ascii} dump. The 31826value of @var{aschar} is used as a padding character when a byte is not a 31827member of the printable @sc{ascii} character set (printable @sc{ascii} 31828characters are those whose code is between 32 and 126, inclusively). 31829 31830@item @var{byte-offset} 31831An offset to add to the @var{address} before fetching memory. 31832@end table 31833 31834This command displays memory contents as a table of @var{nr-rows} by 31835@var{nr-cols} words, each word being @var{word-size} bytes. In total, 31836@code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read 31837(returned as @samp{total-bytes}). Should less than the requested number 31838of bytes be returned by the target, the missing words are identified 31839using @samp{N/A}. The number of bytes read from the target is returned 31840in @samp{nr-bytes} and the starting address used to read memory in 31841@samp{addr}. 31842 31843The address of the next/previous row or page is available in 31844@samp{next-row} and @samp{prev-row}, @samp{next-page} and 31845@samp{prev-page}. 31846 31847@subsubheading @value{GDBN} Command 31848 31849The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has 31850@samp{gdb_get_mem} memory read command. 31851 31852@subsubheading Example 31853 31854Read six bytes of memory starting at @code{bytes+6} but then offset by 31855@code{-6} bytes. Format as three rows of two columns. One byte per 31856word. Display each word in hex. 31857 31858@smallexample 31859(gdb) 318609-data-read-memory -o -6 -- bytes+6 x 1 3 2 318619^done,addr="0x00001390",nr-bytes="6",total-bytes="6", 31862next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", 31863prev-page="0x0000138a",memory=[ 31864@{addr="0x00001390",data=["0x00","0x01"]@}, 31865@{addr="0x00001392",data=["0x02","0x03"]@}, 31866@{addr="0x00001394",data=["0x04","0x05"]@}] 31867(gdb) 31868@end smallexample 31869 31870Read two bytes of memory starting at address @code{shorts + 64} and 31871display as a single word formatted in decimal. 31872 31873@smallexample 31874(gdb) 318755-data-read-memory shorts+64 d 2 1 1 318765^done,addr="0x00001510",nr-bytes="2",total-bytes="2", 31877next-row="0x00001512",prev-row="0x0000150e", 31878next-page="0x00001512",prev-page="0x0000150e",memory=[ 31879@{addr="0x00001510",data=["128"]@}] 31880(gdb) 31881@end smallexample 31882 31883Read thirty two bytes of memory starting at @code{bytes+16} and format 31884as eight rows of four columns. Include a string encoding with @samp{x} 31885used as the non-printable character. 31886 31887@smallexample 31888(gdb) 318894-data-read-memory bytes+16 x 1 8 4 x 318904^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", 31891next-row="0x000013c0",prev-row="0x0000139c", 31892next-page="0x000013c0",prev-page="0x00001380",memory=[ 31893@{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@}, 31894@{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@}, 31895@{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@}, 31896@{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@}, 31897@{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@}, 31898@{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@}, 31899@{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@}, 31900@{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}] 31901(gdb) 31902@end smallexample 31903 31904@subheading The @code{-data-read-memory-bytes} Command 31905@findex -data-read-memory-bytes 31906 31907@subsubheading Synopsis 31908 31909@smallexample 31910 -data-read-memory-bytes [ -o @var{byte-offset} ] 31911 @var{address} @var{count} 31912@end smallexample 31913 31914@noindent 31915where: 31916 31917@table @samp 31918@item @var{address} 31919An expression specifying the address of the first memory word to be 31920read. Complex expressions containing embedded white space should be 31921quoted using the C convention. 31922 31923@item @var{count} 31924The number of bytes to read. This should be an integer literal. 31925 31926@item @var{byte-offset} 31927The offsets in bytes relative to @var{address} at which to start 31928reading. This should be an integer literal. This option is provided 31929so that a frontend is not required to first evaluate address and then 31930perform address arithmetics itself. 31931 31932@end table 31933 31934This command attempts to read all accessible memory regions in the 31935specified range. First, all regions marked as unreadable in the memory 31936map (if one is defined) will be skipped. @xref{Memory Region 31937Attributes}. Second, @value{GDBN} will attempt to read the remaining 31938regions. For each one, if reading full region results in an errors, 31939@value{GDBN} will try to read a subset of the region. 31940 31941In general, every single byte in the region may be readable or not, 31942and the only way to read every readable byte is to try a read at 31943every address, which is not practical. Therefore, @value{GDBN} will 31944attempt to read all accessible bytes at either beginning or the end 31945of the region, using a binary division scheme. This heuristic works 31946well for reading accross a memory map boundary. Note that if a region 31947has a readable range that is neither at the beginning or the end, 31948@value{GDBN} will not read it. 31949 31950The result record (@pxref{GDB/MI Result Records}) that is output of 31951the command includes a field named @samp{memory} whose content is a 31952list of tuples. Each tuple represent a successfully read memory block 31953and has the following fields: 31954 31955@table @code 31956@item begin 31957The start address of the memory block, as hexadecimal literal. 31958 31959@item end 31960The end address of the memory block, as hexadecimal literal. 31961 31962@item offset 31963The offset of the memory block, as hexadecimal literal, relative to 31964the start address passed to @code{-data-read-memory-bytes}. 31965 31966@item contents 31967The contents of the memory block, in hex. 31968 31969@end table 31970 31971 31972 31973@subsubheading @value{GDBN} Command 31974 31975The corresponding @value{GDBN} command is @samp{x}. 31976 31977@subsubheading Example 31978 31979@smallexample 31980(gdb) 31981-data-read-memory-bytes &a 10 31982^done,memory=[@{begin="0xbffff154",offset="0x00000000", 31983 end="0xbffff15e", 31984 contents="01000000020000000300"@}] 31985(gdb) 31986@end smallexample 31987 31988 31989@subheading The @code{-data-write-memory-bytes} Command 31990@findex -data-write-memory-bytes 31991 31992@subsubheading Synopsis 31993 31994@smallexample 31995 -data-write-memory-bytes @var{address} @var{contents} 31996 -data-write-memory-bytes @var{address} @var{contents} @r{[}@var{count}@r{]} 31997@end smallexample 31998 31999@noindent 32000where: 32001 32002@table @samp 32003@item @var{address} 32004An expression specifying the address of the first memory word to be 32005read. Complex expressions containing embedded white space should be 32006quoted using the C convention. 32007 32008@item @var{contents} 32009The hex-encoded bytes to write. 32010 32011@item @var{count} 32012Optional argument indicating the number of bytes to be written. If @var{count} 32013is greater than @var{contents}' length, @value{GDBN} will repeatedly 32014write @var{contents} until it fills @var{count} bytes. 32015 32016@end table 32017 32018@subsubheading @value{GDBN} Command 32019 32020There's no corresponding @value{GDBN} command. 32021 32022@subsubheading Example 32023 32024@smallexample 32025(gdb) 32026-data-write-memory-bytes &a "aabbccdd" 32027^done 32028(gdb) 32029@end smallexample 32030 32031@smallexample 32032(gdb) 32033-data-write-memory-bytes &a "aabbccdd" 16e 32034^done 32035(gdb) 32036@end smallexample 32037 32038@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 32039@node GDB/MI Tracepoint Commands 32040@section @sc{gdb/mi} Tracepoint Commands 32041 32042The commands defined in this section implement MI support for 32043tracepoints. For detailed introduction, see @ref{Tracepoints}. 32044 32045@subheading The @code{-trace-find} Command 32046@findex -trace-find 32047 32048@subsubheading Synopsis 32049 32050@smallexample 32051 -trace-find @var{mode} [@var{parameters}@dots{}] 32052@end smallexample 32053 32054Find a trace frame using criteria defined by @var{mode} and 32055@var{parameters}. The following table lists permissible 32056modes and their parameters. For details of operation, see @ref{tfind}. 32057 32058@table @samp 32059 32060@item none 32061No parameters are required. Stops examining trace frames. 32062 32063@item frame-number 32064An integer is required as parameter. Selects tracepoint frame with 32065that index. 32066 32067@item tracepoint-number 32068An integer is required as parameter. Finds next 32069trace frame that corresponds to tracepoint with the specified number. 32070 32071@item pc 32072An address is required as parameter. Finds 32073next trace frame that corresponds to any tracepoint at the specified 32074address. 32075 32076@item pc-inside-range 32077Two addresses are required as parameters. Finds next trace 32078frame that corresponds to a tracepoint at an address inside the 32079specified range. Both bounds are considered to be inside the range. 32080 32081@item pc-outside-range 32082Two addresses are required as parameters. Finds 32083next trace frame that corresponds to a tracepoint at an address outside 32084the specified range. Both bounds are considered to be inside the range. 32085 32086@item line 32087Line specification is required as parameter. @xref{Specify Location}. 32088Finds next trace frame that corresponds to a tracepoint at 32089the specified location. 32090 32091@end table 32092 32093If @samp{none} was passed as @var{mode}, the response does not 32094have fields. Otherwise, the response may have the following fields: 32095 32096@table @samp 32097@item found 32098This field has either @samp{0} or @samp{1} as the value, depending 32099on whether a matching tracepoint was found. 32100 32101@item traceframe 32102The index of the found traceframe. This field is present iff 32103the @samp{found} field has value of @samp{1}. 32104 32105@item tracepoint 32106The index of the found tracepoint. This field is present iff 32107the @samp{found} field has value of @samp{1}. 32108 32109@item frame 32110The information about the frame corresponding to the found trace 32111frame. This field is present only if a trace frame was found. 32112@xref{GDB/MI Frame Information}, for description of this field. 32113 32114@end table 32115 32116@subsubheading @value{GDBN} Command 32117 32118The corresponding @value{GDBN} command is @samp{tfind}. 32119 32120@subheading -trace-define-variable 32121@findex -trace-define-variable 32122 32123@subsubheading Synopsis 32124 32125@smallexample 32126 -trace-define-variable @var{name} [ @var{value} ] 32127@end smallexample 32128 32129Create trace variable @var{name} if it does not exist. If 32130@var{value} is specified, sets the initial value of the specified 32131trace variable to that value. Note that the @var{name} should start 32132with the @samp{$} character. 32133 32134@subsubheading @value{GDBN} Command 32135 32136The corresponding @value{GDBN} command is @samp{tvariable}. 32137 32138@subheading -trace-list-variables 32139@findex -trace-list-variables 32140 32141@subsubheading Synopsis 32142 32143@smallexample 32144 -trace-list-variables 32145@end smallexample 32146 32147Return a table of all defined trace variables. Each element of the 32148table has the following fields: 32149 32150@table @samp 32151@item name 32152The name of the trace variable. This field is always present. 32153 32154@item initial 32155The initial value. This is a 64-bit signed integer. This 32156field is always present. 32157 32158@item current 32159The value the trace variable has at the moment. This is a 64-bit 32160signed integer. This field is absent iff current value is 32161not defined, for example if the trace was never run, or is 32162presently running. 32163 32164@end table 32165 32166@subsubheading @value{GDBN} Command 32167 32168The corresponding @value{GDBN} command is @samp{tvariables}. 32169 32170@subsubheading Example 32171 32172@smallexample 32173(gdb) 32174-trace-list-variables 32175^done,trace-variables=@{nr_rows="1",nr_cols="3", 32176hdr=[@{width="15",alignment="-1",col_name="name",colhdr="Name"@}, 32177 @{width="11",alignment="-1",col_name="initial",colhdr="Initial"@}, 32178 @{width="11",alignment="-1",col_name="current",colhdr="Current"@}], 32179body=[variable=@{name="$trace_timestamp",initial="0"@} 32180 variable=@{name="$foo",initial="10",current="15"@}]@} 32181(gdb) 32182@end smallexample 32183 32184@subheading -trace-save 32185@findex -trace-save 32186 32187@subsubheading Synopsis 32188 32189@smallexample 32190 -trace-save [-r ] @var{filename} 32191@end smallexample 32192 32193Saves the collected trace data to @var{filename}. Without the 32194@samp{-r} option, the data is downloaded from the target and saved 32195in a local file. With the @samp{-r} option the target is asked 32196to perform the save. 32197 32198@subsubheading @value{GDBN} Command 32199 32200The corresponding @value{GDBN} command is @samp{tsave}. 32201 32202 32203@subheading -trace-start 32204@findex -trace-start 32205 32206@subsubheading Synopsis 32207 32208@smallexample 32209 -trace-start 32210@end smallexample 32211 32212Starts a tracing experiments. The result of this command does not 32213have any fields. 32214 32215@subsubheading @value{GDBN} Command 32216 32217The corresponding @value{GDBN} command is @samp{tstart}. 32218 32219@subheading -trace-status 32220@findex -trace-status 32221 32222@subsubheading Synopsis 32223 32224@smallexample 32225 -trace-status 32226@end smallexample 32227 32228Obtains the status of a tracing experiment. The result may include 32229the following fields: 32230 32231@table @samp 32232 32233@item supported 32234May have a value of either @samp{0}, when no tracing operations are 32235supported, @samp{1}, when all tracing operations are supported, or 32236@samp{file} when examining trace file. In the latter case, examining 32237of trace frame is possible but new tracing experiement cannot be 32238started. This field is always present. 32239 32240@item running 32241May have a value of either @samp{0} or @samp{1} depending on whether 32242tracing experiement is in progress on target. This field is present 32243if @samp{supported} field is not @samp{0}. 32244 32245@item stop-reason 32246Report the reason why the tracing was stopped last time. This field 32247may be absent iff tracing was never stopped on target yet. The 32248value of @samp{request} means the tracing was stopped as result of 32249the @code{-trace-stop} command. The value of @samp{overflow} means 32250the tracing buffer is full. The value of @samp{disconnection} means 32251tracing was automatically stopped when @value{GDBN} has disconnected. 32252The value of @samp{passcount} means tracing was stopped when a 32253tracepoint was passed a maximal number of times for that tracepoint. 32254This field is present if @samp{supported} field is not @samp{0}. 32255 32256@item stopping-tracepoint 32257The number of tracepoint whose passcount as exceeded. This field is 32258present iff the @samp{stop-reason} field has the value of 32259@samp{passcount}. 32260 32261@item frames 32262@itemx frames-created 32263The @samp{frames} field is a count of the total number of trace frames 32264in the trace buffer, while @samp{frames-created} is the total created 32265during the run, including ones that were discarded, such as when a 32266circular trace buffer filled up. Both fields are optional. 32267 32268@item buffer-size 32269@itemx buffer-free 32270These fields tell the current size of the tracing buffer and the 32271remaining space. These fields are optional. 32272 32273@item circular 32274The value of the circular trace buffer flag. @code{1} means that the 32275trace buffer is circular and old trace frames will be discarded if 32276necessary to make room, @code{0} means that the trace buffer is linear 32277and may fill up. 32278 32279@item disconnected 32280The value of the disconnected tracing flag. @code{1} means that 32281tracing will continue after @value{GDBN} disconnects, @code{0} means 32282that the trace run will stop. 32283 32284@item trace-file 32285The filename of the trace file being examined. This field is 32286optional, and only present when examining a trace file. 32287 32288@end table 32289 32290@subsubheading @value{GDBN} Command 32291 32292The corresponding @value{GDBN} command is @samp{tstatus}. 32293 32294@subheading -trace-stop 32295@findex -trace-stop 32296 32297@subsubheading Synopsis 32298 32299@smallexample 32300 -trace-stop 32301@end smallexample 32302 32303Stops a tracing experiment. The result of this command has the same 32304fields as @code{-trace-status}, except that the @samp{supported} and 32305@samp{running} fields are not output. 32306 32307@subsubheading @value{GDBN} Command 32308 32309The corresponding @value{GDBN} command is @samp{tstop}. 32310 32311 32312@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 32313@node GDB/MI Symbol Query 32314@section @sc{gdb/mi} Symbol Query Commands 32315 32316 32317@ignore 32318@subheading The @code{-symbol-info-address} Command 32319@findex -symbol-info-address 32320 32321@subsubheading Synopsis 32322 32323@smallexample 32324 -symbol-info-address @var{symbol} 32325@end smallexample 32326 32327Describe where @var{symbol} is stored. 32328 32329@subsubheading @value{GDBN} Command 32330 32331The corresponding @value{GDBN} command is @samp{info address}. 32332 32333@subsubheading Example 32334N.A. 32335 32336 32337@subheading The @code{-symbol-info-file} Command 32338@findex -symbol-info-file 32339 32340@subsubheading Synopsis 32341 32342@smallexample 32343 -symbol-info-file 32344@end smallexample 32345 32346Show the file for the symbol. 32347 32348@subsubheading @value{GDBN} Command 32349 32350There's no equivalent @value{GDBN} command. @code{gdbtk} has 32351@samp{gdb_find_file}. 32352 32353@subsubheading Example 32354N.A. 32355 32356 32357@subheading The @code{-symbol-info-function} Command 32358@findex -symbol-info-function 32359 32360@subsubheading Synopsis 32361 32362@smallexample 32363 -symbol-info-function 32364@end smallexample 32365 32366Show which function the symbol lives in. 32367 32368@subsubheading @value{GDBN} Command 32369 32370@samp{gdb_get_function} in @code{gdbtk}. 32371 32372@subsubheading Example 32373N.A. 32374 32375 32376@subheading The @code{-symbol-info-line} Command 32377@findex -symbol-info-line 32378 32379@subsubheading Synopsis 32380 32381@smallexample 32382 -symbol-info-line 32383@end smallexample 32384 32385Show the core addresses of the code for a source line. 32386 32387@subsubheading @value{GDBN} Command 32388 32389The corresponding @value{GDBN} command is @samp{info line}. 32390@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands. 32391 32392@subsubheading Example 32393N.A. 32394 32395 32396@subheading The @code{-symbol-info-symbol} Command 32397@findex -symbol-info-symbol 32398 32399@subsubheading Synopsis 32400 32401@smallexample 32402 -symbol-info-symbol @var{addr} 32403@end smallexample 32404 32405Describe what symbol is at location @var{addr}. 32406 32407@subsubheading @value{GDBN} Command 32408 32409The corresponding @value{GDBN} command is @samp{info symbol}. 32410 32411@subsubheading Example 32412N.A. 32413 32414 32415@subheading The @code{-symbol-list-functions} Command 32416@findex -symbol-list-functions 32417 32418@subsubheading Synopsis 32419 32420@smallexample 32421 -symbol-list-functions 32422@end smallexample 32423 32424List the functions in the executable. 32425 32426@subsubheading @value{GDBN} Command 32427 32428@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and 32429@samp{gdb_search} in @code{gdbtk}. 32430 32431@subsubheading Example 32432N.A. 32433@end ignore 32434 32435 32436@subheading The @code{-symbol-list-lines} Command 32437@findex -symbol-list-lines 32438 32439@subsubheading Synopsis 32440 32441@smallexample 32442 -symbol-list-lines @var{filename} 32443@end smallexample 32444 32445Print the list of lines that contain code and their associated program 32446addresses for the given source filename. The entries are sorted in 32447ascending PC order. 32448 32449@subsubheading @value{GDBN} Command 32450 32451There is no corresponding @value{GDBN} command. 32452 32453@subsubheading Example 32454@smallexample 32455(gdb) 32456-symbol-list-lines basics.c 32457^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}] 32458(gdb) 32459@end smallexample 32460 32461 32462@ignore 32463@subheading The @code{-symbol-list-types} Command 32464@findex -symbol-list-types 32465 32466@subsubheading Synopsis 32467 32468@smallexample 32469 -symbol-list-types 32470@end smallexample 32471 32472List all the type names. 32473 32474@subsubheading @value{GDBN} Command 32475 32476The corresponding commands are @samp{info types} in @value{GDBN}, 32477@samp{gdb_search} in @code{gdbtk}. 32478 32479@subsubheading Example 32480N.A. 32481 32482 32483@subheading The @code{-symbol-list-variables} Command 32484@findex -symbol-list-variables 32485 32486@subsubheading Synopsis 32487 32488@smallexample 32489 -symbol-list-variables 32490@end smallexample 32491 32492List all the global and static variable names. 32493 32494@subsubheading @value{GDBN} Command 32495 32496@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}. 32497 32498@subsubheading Example 32499N.A. 32500 32501 32502@subheading The @code{-symbol-locate} Command 32503@findex -symbol-locate 32504 32505@subsubheading Synopsis 32506 32507@smallexample 32508 -symbol-locate 32509@end smallexample 32510 32511@subsubheading @value{GDBN} Command 32512 32513@samp{gdb_loc} in @code{gdbtk}. 32514 32515@subsubheading Example 32516N.A. 32517 32518 32519@subheading The @code{-symbol-type} Command 32520@findex -symbol-type 32521 32522@subsubheading Synopsis 32523 32524@smallexample 32525 -symbol-type @var{variable} 32526@end smallexample 32527 32528Show type of @var{variable}. 32529 32530@subsubheading @value{GDBN} Command 32531 32532The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has 32533@samp{gdb_obj_variable}. 32534 32535@subsubheading Example 32536N.A. 32537@end ignore 32538 32539 32540@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 32541@node GDB/MI File Commands 32542@section @sc{gdb/mi} File Commands 32543 32544This section describes the GDB/MI commands to specify executable file names 32545and to read in and obtain symbol table information. 32546 32547@subheading The @code{-file-exec-and-symbols} Command 32548@findex -file-exec-and-symbols 32549 32550@subsubheading Synopsis 32551 32552@smallexample 32553 -file-exec-and-symbols @var{file} 32554@end smallexample 32555 32556Specify the executable file to be debugged. This file is the one from 32557which the symbol table is also read. If no file is specified, the 32558command clears the executable and symbol information. If breakpoints 32559are set when using this command with no arguments, @value{GDBN} will produce 32560error messages. Otherwise, no output is produced, except a completion 32561notification. 32562 32563@subsubheading @value{GDBN} Command 32564 32565The corresponding @value{GDBN} command is @samp{file}. 32566 32567@subsubheading Example 32568 32569@smallexample 32570(gdb) 32571-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 32572^done 32573(gdb) 32574@end smallexample 32575 32576 32577@subheading The @code{-file-exec-file} Command 32578@findex -file-exec-file 32579 32580@subsubheading Synopsis 32581 32582@smallexample 32583 -file-exec-file @var{file} 32584@end smallexample 32585 32586Specify the executable file to be debugged. Unlike 32587@samp{-file-exec-and-symbols}, the symbol table is @emph{not} read 32588from this file. If used without argument, @value{GDBN} clears the information 32589about the executable file. No output is produced, except a completion 32590notification. 32591 32592@subsubheading @value{GDBN} Command 32593 32594The corresponding @value{GDBN} command is @samp{exec-file}. 32595 32596@subsubheading Example 32597 32598@smallexample 32599(gdb) 32600-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 32601^done 32602(gdb) 32603@end smallexample 32604 32605 32606@ignore 32607@subheading The @code{-file-list-exec-sections} Command 32608@findex -file-list-exec-sections 32609 32610@subsubheading Synopsis 32611 32612@smallexample 32613 -file-list-exec-sections 32614@end smallexample 32615 32616List the sections of the current executable file. 32617 32618@subsubheading @value{GDBN} Command 32619 32620The @value{GDBN} command @samp{info file} shows, among the rest, the same 32621information as this command. @code{gdbtk} has a corresponding command 32622@samp{gdb_load_info}. 32623 32624@subsubheading Example 32625N.A. 32626@end ignore 32627 32628 32629@subheading The @code{-file-list-exec-source-file} Command 32630@findex -file-list-exec-source-file 32631 32632@subsubheading Synopsis 32633 32634@smallexample 32635 -file-list-exec-source-file 32636@end smallexample 32637 32638List the line number, the current source file, and the absolute path 32639to the current source file for the current executable. The macro 32640information field has a value of @samp{1} or @samp{0} depending on 32641whether or not the file includes preprocessor macro information. 32642 32643@subsubheading @value{GDBN} Command 32644 32645The @value{GDBN} equivalent is @samp{info source} 32646 32647@subsubheading Example 32648 32649@smallexample 32650(gdb) 32651123-file-list-exec-source-file 32652123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1" 32653(gdb) 32654@end smallexample 32655 32656 32657@subheading The @code{-file-list-exec-source-files} Command 32658@findex -file-list-exec-source-files 32659 32660@subsubheading Synopsis 32661 32662@smallexample 32663 -file-list-exec-source-files 32664@end smallexample 32665 32666List the source files for the current executable. 32667 32668It will always output both the filename and fullname (absolute file 32669name) of a source file. 32670 32671@subsubheading @value{GDBN} Command 32672 32673The @value{GDBN} equivalent is @samp{info sources}. 32674@code{gdbtk} has an analogous command @samp{gdb_listfiles}. 32675 32676@subsubheading Example 32677@smallexample 32678(gdb) 32679-file-list-exec-source-files 32680^done,files=[ 32681@{file=foo.c,fullname=/home/foo.c@}, 32682@{file=/home/bar.c,fullname=/home/bar.c@}, 32683@{file=gdb_could_not_find_fullpath.c@}] 32684(gdb) 32685@end smallexample 32686 32687@ignore 32688@subheading The @code{-file-list-shared-libraries} Command 32689@findex -file-list-shared-libraries 32690 32691@subsubheading Synopsis 32692 32693@smallexample 32694 -file-list-shared-libraries 32695@end smallexample 32696 32697List the shared libraries in the program. 32698 32699@subsubheading @value{GDBN} Command 32700 32701The corresponding @value{GDBN} command is @samp{info shared}. 32702 32703@subsubheading Example 32704N.A. 32705 32706 32707@subheading The @code{-file-list-symbol-files} Command 32708@findex -file-list-symbol-files 32709 32710@subsubheading Synopsis 32711 32712@smallexample 32713 -file-list-symbol-files 32714@end smallexample 32715 32716List symbol files. 32717 32718@subsubheading @value{GDBN} Command 32719 32720The corresponding @value{GDBN} command is @samp{info file} (part of it). 32721 32722@subsubheading Example 32723N.A. 32724@end ignore 32725 32726 32727@subheading The @code{-file-symbol-file} Command 32728@findex -file-symbol-file 32729 32730@subsubheading Synopsis 32731 32732@smallexample 32733 -file-symbol-file @var{file} 32734@end smallexample 32735 32736Read symbol table info from the specified @var{file} argument. When 32737used without arguments, clears @value{GDBN}'s symbol table info. No output is 32738produced, except for a completion notification. 32739 32740@subsubheading @value{GDBN} Command 32741 32742The corresponding @value{GDBN} command is @samp{symbol-file}. 32743 32744@subsubheading Example 32745 32746@smallexample 32747(gdb) 32748-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 32749^done 32750(gdb) 32751@end smallexample 32752 32753@ignore 32754@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 32755@node GDB/MI Memory Overlay Commands 32756@section @sc{gdb/mi} Memory Overlay Commands 32757 32758The memory overlay commands are not implemented. 32759 32760@c @subheading -overlay-auto 32761 32762@c @subheading -overlay-list-mapping-state 32763 32764@c @subheading -overlay-list-overlays 32765 32766@c @subheading -overlay-map 32767 32768@c @subheading -overlay-off 32769 32770@c @subheading -overlay-on 32771 32772@c @subheading -overlay-unmap 32773 32774@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 32775@node GDB/MI Signal Handling Commands 32776@section @sc{gdb/mi} Signal Handling Commands 32777 32778Signal handling commands are not implemented. 32779 32780@c @subheading -signal-handle 32781 32782@c @subheading -signal-list-handle-actions 32783 32784@c @subheading -signal-list-signal-types 32785@end ignore 32786 32787 32788@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 32789@node GDB/MI Target Manipulation 32790@section @sc{gdb/mi} Target Manipulation Commands 32791 32792 32793@subheading The @code{-target-attach} Command 32794@findex -target-attach 32795 32796@subsubheading Synopsis 32797 32798@smallexample 32799 -target-attach @var{pid} | @var{gid} | @var{file} 32800@end smallexample 32801 32802Attach to a process @var{pid} or a file @var{file} outside of 32803@value{GDBN}, or a thread group @var{gid}. If attaching to a thread 32804group, the id previously returned by 32805@samp{-list-thread-groups --available} must be used. 32806 32807@subsubheading @value{GDBN} Command 32808 32809The corresponding @value{GDBN} command is @samp{attach}. 32810 32811@subsubheading Example 32812@smallexample 32813(gdb) 32814-target-attach 34 32815=thread-created,id="1" 32816*stopped,thread-id="1",frame=@{addr="0xb7f7e410",func="bar",args=[]@} 32817^done 32818(gdb) 32819@end smallexample 32820 32821@ignore 32822@subheading The @code{-target-compare-sections} Command 32823@findex -target-compare-sections 32824 32825@subsubheading Synopsis 32826 32827@smallexample 32828 -target-compare-sections [ @var{section} ] 32829@end smallexample 32830 32831Compare data of section @var{section} on target to the exec file. 32832Without the argument, all sections are compared. 32833 32834@subsubheading @value{GDBN} Command 32835 32836The @value{GDBN} equivalent is @samp{compare-sections}. 32837 32838@subsubheading Example 32839N.A. 32840@end ignore 32841 32842 32843@subheading The @code{-target-detach} Command 32844@findex -target-detach 32845 32846@subsubheading Synopsis 32847 32848@smallexample 32849 -target-detach [ @var{pid} | @var{gid} ] 32850@end smallexample 32851 32852Detach from the remote target which normally resumes its execution. 32853If either @var{pid} or @var{gid} is specified, detaches from either 32854the specified process, or specified thread group. There's no output. 32855 32856@subsubheading @value{GDBN} Command 32857 32858The corresponding @value{GDBN} command is @samp{detach}. 32859 32860@subsubheading Example 32861 32862@smallexample 32863(gdb) 32864-target-detach 32865^done 32866(gdb) 32867@end smallexample 32868 32869 32870@subheading The @code{-target-disconnect} Command 32871@findex -target-disconnect 32872 32873@subsubheading Synopsis 32874 32875@smallexample 32876 -target-disconnect 32877@end smallexample 32878 32879Disconnect from the remote target. There's no output and the target is 32880generally not resumed. 32881 32882@subsubheading @value{GDBN} Command 32883 32884The corresponding @value{GDBN} command is @samp{disconnect}. 32885 32886@subsubheading Example 32887 32888@smallexample 32889(gdb) 32890-target-disconnect 32891^done 32892(gdb) 32893@end smallexample 32894 32895 32896@subheading The @code{-target-download} Command 32897@findex -target-download 32898 32899@subsubheading Synopsis 32900 32901@smallexample 32902 -target-download 32903@end smallexample 32904 32905Loads the executable onto the remote target. 32906It prints out an update message every half second, which includes the fields: 32907 32908@table @samp 32909@item section 32910The name of the section. 32911@item section-sent 32912The size of what has been sent so far for that section. 32913@item section-size 32914The size of the section. 32915@item total-sent 32916The total size of what was sent so far (the current and the previous sections). 32917@item total-size 32918The size of the overall executable to download. 32919@end table 32920 32921@noindent 32922Each message is sent as status record (@pxref{GDB/MI Output Syntax, , 32923@sc{gdb/mi} Output Syntax}). 32924 32925In addition, it prints the name and size of the sections, as they are 32926downloaded. These messages include the following fields: 32927 32928@table @samp 32929@item section 32930The name of the section. 32931@item section-size 32932The size of the section. 32933@item total-size 32934The size of the overall executable to download. 32935@end table 32936 32937@noindent 32938At the end, a summary is printed. 32939 32940@subsubheading @value{GDBN} Command 32941 32942The corresponding @value{GDBN} command is @samp{load}. 32943 32944@subsubheading Example 32945 32946Note: each status message appears on a single line. Here the messages 32947have been broken down so that they can fit onto a page. 32948 32949@smallexample 32950(gdb) 32951-target-download 32952+download,@{section=".text",section-size="6668",total-size="9880"@} 32953+download,@{section=".text",section-sent="512",section-size="6668", 32954total-sent="512",total-size="9880"@} 32955+download,@{section=".text",section-sent="1024",section-size="6668", 32956total-sent="1024",total-size="9880"@} 32957+download,@{section=".text",section-sent="1536",section-size="6668", 32958total-sent="1536",total-size="9880"@} 32959+download,@{section=".text",section-sent="2048",section-size="6668", 32960total-sent="2048",total-size="9880"@} 32961+download,@{section=".text",section-sent="2560",section-size="6668", 32962total-sent="2560",total-size="9880"@} 32963+download,@{section=".text",section-sent="3072",section-size="6668", 32964total-sent="3072",total-size="9880"@} 32965+download,@{section=".text",section-sent="3584",section-size="6668", 32966total-sent="3584",total-size="9880"@} 32967+download,@{section=".text",section-sent="4096",section-size="6668", 32968total-sent="4096",total-size="9880"@} 32969+download,@{section=".text",section-sent="4608",section-size="6668", 32970total-sent="4608",total-size="9880"@} 32971+download,@{section=".text",section-sent="5120",section-size="6668", 32972total-sent="5120",total-size="9880"@} 32973+download,@{section=".text",section-sent="5632",section-size="6668", 32974total-sent="5632",total-size="9880"@} 32975+download,@{section=".text",section-sent="6144",section-size="6668", 32976total-sent="6144",total-size="9880"@} 32977+download,@{section=".text",section-sent="6656",section-size="6668", 32978total-sent="6656",total-size="9880"@} 32979+download,@{section=".init",section-size="28",total-size="9880"@} 32980+download,@{section=".fini",section-size="28",total-size="9880"@} 32981+download,@{section=".data",section-size="3156",total-size="9880"@} 32982+download,@{section=".data",section-sent="512",section-size="3156", 32983total-sent="7236",total-size="9880"@} 32984+download,@{section=".data",section-sent="1024",section-size="3156", 32985total-sent="7748",total-size="9880"@} 32986+download,@{section=".data",section-sent="1536",section-size="3156", 32987total-sent="8260",total-size="9880"@} 32988+download,@{section=".data",section-sent="2048",section-size="3156", 32989total-sent="8772",total-size="9880"@} 32990+download,@{section=".data",section-sent="2560",section-size="3156", 32991total-sent="9284",total-size="9880"@} 32992+download,@{section=".data",section-sent="3072",section-size="3156", 32993total-sent="9796",total-size="9880"@} 32994^done,address="0x10004",load-size="9880",transfer-rate="6586", 32995write-rate="429" 32996(gdb) 32997@end smallexample 32998 32999 33000@ignore 33001@subheading The @code{-target-exec-status} Command 33002@findex -target-exec-status 33003 33004@subsubheading Synopsis 33005 33006@smallexample 33007 -target-exec-status 33008@end smallexample 33009 33010Provide information on the state of the target (whether it is running or 33011not, for instance). 33012 33013@subsubheading @value{GDBN} Command 33014 33015There's no equivalent @value{GDBN} command. 33016 33017@subsubheading Example 33018N.A. 33019 33020 33021@subheading The @code{-target-list-available-targets} Command 33022@findex -target-list-available-targets 33023 33024@subsubheading Synopsis 33025 33026@smallexample 33027 -target-list-available-targets 33028@end smallexample 33029 33030List the possible targets to connect to. 33031 33032@subsubheading @value{GDBN} Command 33033 33034The corresponding @value{GDBN} command is @samp{help target}. 33035 33036@subsubheading Example 33037N.A. 33038 33039 33040@subheading The @code{-target-list-current-targets} Command 33041@findex -target-list-current-targets 33042 33043@subsubheading Synopsis 33044 33045@smallexample 33046 -target-list-current-targets 33047@end smallexample 33048 33049Describe the current target. 33050 33051@subsubheading @value{GDBN} Command 33052 33053The corresponding information is printed by @samp{info file} (among 33054other things). 33055 33056@subsubheading Example 33057N.A. 33058 33059 33060@subheading The @code{-target-list-parameters} Command 33061@findex -target-list-parameters 33062 33063@subsubheading Synopsis 33064 33065@smallexample 33066 -target-list-parameters 33067@end smallexample 33068 33069@c ???? 33070@end ignore 33071 33072@subsubheading @value{GDBN} Command 33073 33074No equivalent. 33075 33076@subsubheading Example 33077N.A. 33078 33079 33080@subheading The @code{-target-select} Command 33081@findex -target-select 33082 33083@subsubheading Synopsis 33084 33085@smallexample 33086 -target-select @var{type} @var{parameters @dots{}} 33087@end smallexample 33088 33089Connect @value{GDBN} to the remote target. This command takes two args: 33090 33091@table @samp 33092@item @var{type} 33093The type of target, for instance @samp{remote}, etc. 33094@item @var{parameters} 33095Device names, host names and the like. @xref{Target Commands, , 33096Commands for Managing Targets}, for more details. 33097@end table 33098 33099The output is a connection notification, followed by the address at 33100which the target program is, in the following form: 33101 33102@smallexample 33103^connected,addr="@var{address}",func="@var{function name}", 33104 args=[@var{arg list}] 33105@end smallexample 33106 33107@subsubheading @value{GDBN} Command 33108 33109The corresponding @value{GDBN} command is @samp{target}. 33110 33111@subsubheading Example 33112 33113@smallexample 33114(gdb) 33115-target-select remote /dev/ttya 33116^connected,addr="0xfe00a300",func="??",args=[] 33117(gdb) 33118@end smallexample 33119 33120@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 33121@node GDB/MI File Transfer Commands 33122@section @sc{gdb/mi} File Transfer Commands 33123 33124 33125@subheading The @code{-target-file-put} Command 33126@findex -target-file-put 33127 33128@subsubheading Synopsis 33129 33130@smallexample 33131 -target-file-put @var{hostfile} @var{targetfile} 33132@end smallexample 33133 33134Copy file @var{hostfile} from the host system (the machine running 33135@value{GDBN}) to @var{targetfile} on the target system. 33136 33137@subsubheading @value{GDBN} Command 33138 33139The corresponding @value{GDBN} command is @samp{remote put}. 33140 33141@subsubheading Example 33142 33143@smallexample 33144(gdb) 33145-target-file-put localfile remotefile 33146^done 33147(gdb) 33148@end smallexample 33149 33150 33151@subheading The @code{-target-file-get} Command 33152@findex -target-file-get 33153 33154@subsubheading Synopsis 33155 33156@smallexample 33157 -target-file-get @var{targetfile} @var{hostfile} 33158@end smallexample 33159 33160Copy file @var{targetfile} from the target system to @var{hostfile} 33161on the host system. 33162 33163@subsubheading @value{GDBN} Command 33164 33165The corresponding @value{GDBN} command is @samp{remote get}. 33166 33167@subsubheading Example 33168 33169@smallexample 33170(gdb) 33171-target-file-get remotefile localfile 33172^done 33173(gdb) 33174@end smallexample 33175 33176 33177@subheading The @code{-target-file-delete} Command 33178@findex -target-file-delete 33179 33180@subsubheading Synopsis 33181 33182@smallexample 33183 -target-file-delete @var{targetfile} 33184@end smallexample 33185 33186Delete @var{targetfile} from the target system. 33187 33188@subsubheading @value{GDBN} Command 33189 33190The corresponding @value{GDBN} command is @samp{remote delete}. 33191 33192@subsubheading Example 33193 33194@smallexample 33195(gdb) 33196-target-file-delete remotefile 33197^done 33198(gdb) 33199@end smallexample 33200 33201 33202@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 33203@node GDB/MI Miscellaneous Commands 33204@section Miscellaneous @sc{gdb/mi} Commands 33205 33206@c @subheading -gdb-complete 33207 33208@subheading The @code{-gdb-exit} Command 33209@findex -gdb-exit 33210 33211@subsubheading Synopsis 33212 33213@smallexample 33214 -gdb-exit 33215@end smallexample 33216 33217Exit @value{GDBN} immediately. 33218 33219@subsubheading @value{GDBN} Command 33220 33221Approximately corresponds to @samp{quit}. 33222 33223@subsubheading Example 33224 33225@smallexample 33226(gdb) 33227-gdb-exit 33228^exit 33229@end smallexample 33230 33231 33232@ignore 33233@subheading The @code{-exec-abort} Command 33234@findex -exec-abort 33235 33236@subsubheading Synopsis 33237 33238@smallexample 33239 -exec-abort 33240@end smallexample 33241 33242Kill the inferior running program. 33243 33244@subsubheading @value{GDBN} Command 33245 33246The corresponding @value{GDBN} command is @samp{kill}. 33247 33248@subsubheading Example 33249N.A. 33250@end ignore 33251 33252 33253@subheading The @code{-gdb-set} Command 33254@findex -gdb-set 33255 33256@subsubheading Synopsis 33257 33258@smallexample 33259 -gdb-set 33260@end smallexample 33261 33262Set an internal @value{GDBN} variable. 33263@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ????? 33264 33265@subsubheading @value{GDBN} Command 33266 33267The corresponding @value{GDBN} command is @samp{set}. 33268 33269@subsubheading Example 33270 33271@smallexample 33272(gdb) 33273-gdb-set $foo=3 33274^done 33275(gdb) 33276@end smallexample 33277 33278 33279@subheading The @code{-gdb-show} Command 33280@findex -gdb-show 33281 33282@subsubheading Synopsis 33283 33284@smallexample 33285 -gdb-show 33286@end smallexample 33287 33288Show the current value of a @value{GDBN} variable. 33289 33290@subsubheading @value{GDBN} Command 33291 33292The corresponding @value{GDBN} command is @samp{show}. 33293 33294@subsubheading Example 33295 33296@smallexample 33297(gdb) 33298-gdb-show annotate 33299^done,value="0" 33300(gdb) 33301@end smallexample 33302 33303@c @subheading -gdb-source 33304 33305 33306@subheading The @code{-gdb-version} Command 33307@findex -gdb-version 33308 33309@subsubheading Synopsis 33310 33311@smallexample 33312 -gdb-version 33313@end smallexample 33314 33315Show version information for @value{GDBN}. Used mostly in testing. 33316 33317@subsubheading @value{GDBN} Command 33318 33319The @value{GDBN} equivalent is @samp{show version}. @value{GDBN} by 33320default shows this information when you start an interactive session. 33321 33322@subsubheading Example 33323 33324@c This example modifies the actual output from GDB to avoid overfull 33325@c box in TeX. 33326@smallexample 33327(gdb) 33328-gdb-version 33329~GNU gdb 5.2.1 33330~Copyright 2000 Free Software Foundation, Inc. 33331~GDB is free software, covered by the GNU General Public License, and 33332~you are welcome to change it and/or distribute copies of it under 33333~ certain conditions. 33334~Type "show copying" to see the conditions. 33335~There is absolutely no warranty for GDB. Type "show warranty" for 33336~ details. 33337~This GDB was configured as 33338 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". 33339^done 33340(gdb) 33341@end smallexample 33342 33343@subheading The @code{-list-features} Command 33344@findex -list-features 33345 33346Returns a list of particular features of the MI protocol that 33347this version of gdb implements. A feature can be a command, 33348or a new field in an output of some command, or even an 33349important bugfix. While a frontend can sometimes detect presence 33350of a feature at runtime, it is easier to perform detection at debugger 33351startup. 33352 33353The command returns a list of strings, with each string naming an 33354available feature. Each returned string is just a name, it does not 33355have any internal structure. The list of possible feature names 33356is given below. 33357 33358Example output: 33359 33360@smallexample 33361(gdb) -list-features 33362^done,result=["feature1","feature2"] 33363@end smallexample 33364 33365The current list of features is: 33366 33367@table @samp 33368@item frozen-varobjs 33369Indicates support for the @code{-var-set-frozen} command, as well 33370as possible presense of the @code{frozen} field in the output 33371of @code{-varobj-create}. 33372@item pending-breakpoints 33373Indicates support for the @option{-f} option to the @code{-break-insert} 33374command. 33375@item python 33376Indicates Python scripting support, Python-based 33377pretty-printing commands, and possible presence of the 33378@samp{display_hint} field in the output of @code{-var-list-children} 33379@item thread-info 33380Indicates support for the @code{-thread-info} command. 33381@item data-read-memory-bytes 33382Indicates support for the @code{-data-read-memory-bytes} and the 33383@code{-data-write-memory-bytes} commands. 33384@item breakpoint-notifications 33385Indicates that changes to breakpoints and breakpoints created via the 33386CLI will be announced via async records. 33387@item ada-task-info 33388Indicates support for the @code{-ada-task-info} command. 33389@end table 33390 33391@subheading The @code{-list-target-features} Command 33392@findex -list-target-features 33393 33394Returns a list of particular features that are supported by the 33395target. Those features affect the permitted MI commands, but 33396unlike the features reported by the @code{-list-features} command, the 33397features depend on which target GDB is using at the moment. Whenever 33398a target can change, due to commands such as @code{-target-select}, 33399@code{-target-attach} or @code{-exec-run}, the list of target features 33400may change, and the frontend should obtain it again. 33401Example output: 33402 33403@smallexample 33404(gdb) -list-features 33405^done,result=["async"] 33406@end smallexample 33407 33408The current list of features is: 33409 33410@table @samp 33411@item async 33412Indicates that the target is capable of asynchronous command 33413execution, which means that @value{GDBN} will accept further commands 33414while the target is running. 33415 33416@item reverse 33417Indicates that the target is capable of reverse execution. 33418@xref{Reverse Execution}, for more information. 33419 33420@end table 33421 33422@subheading The @code{-list-thread-groups} Command 33423@findex -list-thread-groups 33424 33425@subheading Synopsis 33426 33427@smallexample 33428-list-thread-groups [ --available ] [ --recurse 1 ] [ @var{group} ... ] 33429@end smallexample 33430 33431Lists thread groups (@pxref{Thread groups}). When a single thread 33432group is passed as the argument, lists the children of that group. 33433When several thread group are passed, lists information about those 33434thread groups. Without any parameters, lists information about all 33435top-level thread groups. 33436 33437Normally, thread groups that are being debugged are reported. 33438With the @samp{--available} option, @value{GDBN} reports thread groups 33439available on the target. 33440 33441The output of this command may have either a @samp{threads} result or 33442a @samp{groups} result. The @samp{thread} result has a list of tuples 33443as value, with each tuple describing a thread (@pxref{GDB/MI Thread 33444Information}). The @samp{groups} result has a list of tuples as value, 33445each tuple describing a thread group. If top-level groups are 33446requested (that is, no parameter is passed), or when several groups 33447are passed, the output always has a @samp{groups} result. The format 33448of the @samp{group} result is described below. 33449 33450To reduce the number of roundtrips it's possible to list thread groups 33451together with their children, by passing the @samp{--recurse} option 33452and the recursion depth. Presently, only recursion depth of 1 is 33453permitted. If this option is present, then every reported thread group 33454will also include its children, either as @samp{group} or 33455@samp{threads} field. 33456 33457In general, any combination of option and parameters is permitted, with 33458the following caveats: 33459 33460@itemize @bullet 33461@item 33462When a single thread group is passed, the output will typically 33463be the @samp{threads} result. Because threads may not contain 33464anything, the @samp{recurse} option will be ignored. 33465 33466@item 33467When the @samp{--available} option is passed, limited information may 33468be available. In particular, the list of threads of a process might 33469be inaccessible. Further, specifying specific thread groups might 33470not give any performance advantage over listing all thread groups. 33471The frontend should assume that @samp{-list-thread-groups --available} 33472is always an expensive operation and cache the results. 33473 33474@end itemize 33475 33476The @samp{groups} result is a list of tuples, where each tuple may 33477have the following fields: 33478 33479@table @code 33480@item id 33481Identifier of the thread group. This field is always present. 33482The identifier is an opaque string; frontends should not try to 33483convert it to an integer, even though it might look like one. 33484 33485@item type 33486The type of the thread group. At present, only @samp{process} is a 33487valid type. 33488 33489@item pid 33490The target-specific process identifier. This field is only present 33491for thread groups of type @samp{process} and only if the process exists. 33492 33493@item num_children 33494The number of children this thread group has. This field may be 33495absent for an available thread group. 33496 33497@item threads 33498This field has a list of tuples as value, each tuple describing a 33499thread. It may be present if the @samp{--recurse} option is 33500specified, and it's actually possible to obtain the threads. 33501 33502@item cores 33503This field is a list of integers, each identifying a core that one 33504thread of the group is running on. This field may be absent if 33505such information is not available. 33506 33507@item executable 33508The name of the executable file that corresponds to this thread group. 33509The field is only present for thread groups of type @samp{process}, 33510and only if there is a corresponding executable file. 33511 33512@end table 33513 33514@subheading Example 33515 33516@smallexample 33517@value{GDBP} 33518-list-thread-groups 33519^done,groups=[@{id="17",type="process",pid="yyy",num_children="2"@}] 33520-list-thread-groups 17 33521^done,threads=[@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", 33522 frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@}, 33523@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", 33524 frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}], 33525 file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}]] 33526-list-thread-groups --available 33527^done,groups=[@{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]@}] 33528-list-thread-groups --available --recurse 1 33529 ^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], 33530 threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@}, 33531 @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},..] 33532-list-thread-groups --available --recurse 1 17 18 33533^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], 33534 threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@}, 33535 @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},...] 33536@end smallexample 33537 33538@subheading The @code{-info-os} Command 33539@findex -info-os 33540 33541@subsubheading Synopsis 33542 33543@smallexample 33544-info-os [ @var{type} ] 33545@end smallexample 33546 33547If no argument is supplied, the command returns a table of available 33548operating-system-specific information types. If one of these types is 33549supplied as an argument @var{type}, then the command returns a table 33550of data of that type. 33551 33552The types of information available depend on the target operating 33553system. 33554 33555@subsubheading @value{GDBN} Command 33556 33557The corresponding @value{GDBN} command is @samp{info os}. 33558 33559@subsubheading Example 33560 33561When run on a @sc{gnu}/Linux system, the output will look something 33562like this: 33563 33564@smallexample 33565@value{GDBP} 33566-info-os 33567^done,OSDataTable=@{nr_rows="9",nr_cols="3", 33568hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="Type"@}, 33569 @{width="10",alignment="-1",col_name="col1",colhdr="Description"@}, 33570 @{width="10",alignment="-1",col_name="col2",colhdr="Title"@}], 33571body=[item=@{col0="processes",col1="Listing of all processes", 33572 col2="Processes"@}, 33573 item=@{col0="procgroups",col1="Listing of all process groups", 33574 col2="Process groups"@}, 33575 item=@{col0="threads",col1="Listing of all threads", 33576 col2="Threads"@}, 33577 item=@{col0="files",col1="Listing of all file descriptors", 33578 col2="File descriptors"@}, 33579 item=@{col0="sockets",col1="Listing of all internet-domain sockets", 33580 col2="Sockets"@}, 33581 item=@{col0="shm",col1="Listing of all shared-memory regions", 33582 col2="Shared-memory regions"@}, 33583 item=@{col0="semaphores",col1="Listing of all semaphores", 33584 col2="Semaphores"@}, 33585 item=@{col0="msg",col1="Listing of all message queues", 33586 col2="Message queues"@}, 33587 item=@{col0="modules",col1="Listing of all loaded kernel modules", 33588 col2="Kernel modules"@}]@} 33589@value{GDBP} 33590-info-os processes 33591^done,OSDataTable=@{nr_rows="190",nr_cols="4", 33592hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="pid"@}, 33593 @{width="10",alignment="-1",col_name="col1",colhdr="user"@}, 33594 @{width="10",alignment="-1",col_name="col2",colhdr="command"@}, 33595 @{width="10",alignment="-1",col_name="col3",colhdr="cores"@}], 33596body=[item=@{col0="1",col1="root",col2="/sbin/init",col3="0"@}, 33597 item=@{col0="2",col1="root",col2="[kthreadd]",col3="1"@}, 33598 item=@{col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"@}, 33599 ... 33600 item=@{col0="26446",col1="stan",col2="bash",col3="0"@}, 33601 item=@{col0="28152",col1="stan",col2="bash",col3="1"@}]@} 33602(gdb) 33603@end smallexample 33604 33605(Note that the MI output here includes a @code{"Title"} column that 33606does not appear in command-line @code{info os}; this column is useful 33607for MI clients that want to enumerate the types of data, such as in a 33608popup menu, but is needless clutter on the command line, and 33609@code{info os} omits it.) 33610 33611@subheading The @code{-add-inferior} Command 33612@findex -add-inferior 33613 33614@subheading Synopsis 33615 33616@smallexample 33617-add-inferior 33618@end smallexample 33619 33620Creates a new inferior (@pxref{Inferiors and Programs}). The created 33621inferior is not associated with any executable. Such association may 33622be established with the @samp{-file-exec-and-symbols} command 33623(@pxref{GDB/MI File Commands}). The command response has a single 33624field, @samp{thread-group}, whose value is the identifier of the 33625thread group corresponding to the new inferior. 33626 33627@subheading Example 33628 33629@smallexample 33630@value{GDBP} 33631-add-inferior 33632^done,thread-group="i3" 33633@end smallexample 33634 33635@subheading The @code{-interpreter-exec} Command 33636@findex -interpreter-exec 33637 33638@subheading Synopsis 33639 33640@smallexample 33641-interpreter-exec @var{interpreter} @var{command} 33642@end smallexample 33643@anchor{-interpreter-exec} 33644 33645Execute the specified @var{command} in the given @var{interpreter}. 33646 33647@subheading @value{GDBN} Command 33648 33649The corresponding @value{GDBN} command is @samp{interpreter-exec}. 33650 33651@subheading Example 33652 33653@smallexample 33654(gdb) 33655-interpreter-exec console "break main" 33656&"During symbol reading, couldn't parse type; debugger out of date?.\n" 33657&"During symbol reading, bad structure-type format.\n" 33658~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" 33659^done 33660(gdb) 33661@end smallexample 33662 33663@subheading The @code{-inferior-tty-set} Command 33664@findex -inferior-tty-set 33665 33666@subheading Synopsis 33667 33668@smallexample 33669-inferior-tty-set /dev/pts/1 33670@end smallexample 33671 33672Set terminal for future runs of the program being debugged. 33673 33674@subheading @value{GDBN} Command 33675 33676The corresponding @value{GDBN} command is @samp{set inferior-tty} /dev/pts/1. 33677 33678@subheading Example 33679 33680@smallexample 33681(gdb) 33682-inferior-tty-set /dev/pts/1 33683^done 33684(gdb) 33685@end smallexample 33686 33687@subheading The @code{-inferior-tty-show} Command 33688@findex -inferior-tty-show 33689 33690@subheading Synopsis 33691 33692@smallexample 33693-inferior-tty-show 33694@end smallexample 33695 33696Show terminal for future runs of program being debugged. 33697 33698@subheading @value{GDBN} Command 33699 33700The corresponding @value{GDBN} command is @samp{show inferior-tty}. 33701 33702@subheading Example 33703 33704@smallexample 33705(gdb) 33706-inferior-tty-set /dev/pts/1 33707^done 33708(gdb) 33709-inferior-tty-show 33710^done,inferior_tty_terminal="/dev/pts/1" 33711(gdb) 33712@end smallexample 33713 33714@subheading The @code{-enable-timings} Command 33715@findex -enable-timings 33716 33717@subheading Synopsis 33718 33719@smallexample 33720-enable-timings [yes | no] 33721@end smallexample 33722 33723Toggle the printing of the wallclock, user and system times for an MI 33724command as a field in its output. This command is to help frontend 33725developers optimize the performance of their code. No argument is 33726equivalent to @samp{yes}. 33727 33728@subheading @value{GDBN} Command 33729 33730No equivalent. 33731 33732@subheading Example 33733 33734@smallexample 33735(gdb) 33736-enable-timings 33737^done 33738(gdb) 33739-break-insert main 33740^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 33741addr="0x080484ed",func="main",file="myprog.c", 33742fullname="/home/nickrob/myprog.c",line="73",thread-groups=["i1"], 33743times="0"@}, 33744time=@{wallclock="0.05185",user="0.00800",system="0.00000"@} 33745(gdb) 33746-enable-timings no 33747^done 33748(gdb) 33749-exec-run 33750^running 33751(gdb) 33752*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", 33753frame=@{addr="0x080484ed",func="main",args=[@{name="argc",value="1"@}, 33754@{name="argv",value="0xbfb60364"@}],file="myprog.c", 33755fullname="/home/nickrob/myprog.c",line="73"@} 33756(gdb) 33757@end smallexample 33758 33759@node Annotations 33760@chapter @value{GDBN} Annotations 33761 33762This chapter describes annotations in @value{GDBN}. Annotations were 33763designed to interface @value{GDBN} to graphical user interfaces or other 33764similar programs which want to interact with @value{GDBN} at a 33765relatively high level. 33766 33767The annotation mechanism has largely been superseded by @sc{gdb/mi} 33768(@pxref{GDB/MI}). 33769 33770@ignore 33771This is Edition @value{EDITION}, @value{DATE}. 33772@end ignore 33773 33774@menu 33775* Annotations Overview:: What annotations are; the general syntax. 33776* Server Prefix:: Issuing a command without affecting user state. 33777* Prompting:: Annotations marking @value{GDBN}'s need for input. 33778* Errors:: Annotations for error messages. 33779* Invalidation:: Some annotations describe things now invalid. 33780* Annotations for Running:: 33781 Whether the program is running, how it stopped, etc. 33782* Source Annotations:: Annotations describing source code. 33783@end menu 33784 33785@node Annotations Overview 33786@section What is an Annotation? 33787@cindex annotations 33788 33789Annotations start with a newline character, two @samp{control-z} 33790characters, and the name of the annotation. If there is no additional 33791information associated with this annotation, the name of the annotation 33792is followed immediately by a newline. If there is additional 33793information, the name of the annotation is followed by a space, the 33794additional information, and a newline. The additional information 33795cannot contain newline characters. 33796 33797Any output not beginning with a newline and two @samp{control-z} 33798characters denotes literal output from @value{GDBN}. Currently there is 33799no need for @value{GDBN} to output a newline followed by two 33800@samp{control-z} characters, but if there was such a need, the 33801annotations could be extended with an @samp{escape} annotation which 33802means those three characters as output. 33803 33804The annotation @var{level}, which is specified using the 33805@option{--annotate} command line option (@pxref{Mode Options}), controls 33806how much information @value{GDBN} prints together with its prompt, 33807values of expressions, source lines, and other types of output. Level 0 33808is for no annotations, level 1 is for use when @value{GDBN} is run as a 33809subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable 33810for programs that control @value{GDBN}, and level 2 annotations have 33811been made obsolete (@pxref{Limitations, , Limitations of the Annotation 33812Interface, annotate, GDB's Obsolete Annotations}). 33813 33814@table @code 33815@kindex set annotate 33816@item set annotate @var{level} 33817The @value{GDBN} command @code{set annotate} sets the level of 33818annotations to the specified @var{level}. 33819 33820@item show annotate 33821@kindex show annotate 33822Show the current annotation level. 33823@end table 33824 33825This chapter describes level 3 annotations. 33826 33827A simple example of starting up @value{GDBN} with annotations is: 33828 33829@smallexample 33830$ @kbd{gdb --annotate=3} 33831GNU gdb 6.0 33832Copyright 2003 Free Software Foundation, Inc. 33833GDB is free software, covered by the GNU General Public License, 33834and you are welcome to change it and/or distribute copies of it 33835under certain conditions. 33836Type "show copying" to see the conditions. 33837There is absolutely no warranty for GDB. Type "show warranty" 33838for details. 33839This GDB was configured as "i386-pc-linux-gnu" 33840 33841^Z^Zpre-prompt 33842(@value{GDBP}) 33843^Z^Zprompt 33844@kbd{quit} 33845 33846^Z^Zpost-prompt 33847$ 33848@end smallexample 33849 33850Here @samp{quit} is input to @value{GDBN}; the rest is output from 33851@value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z} 33852denotes a @samp{control-z} character) are annotations; the rest is 33853output from @value{GDBN}. 33854 33855@node Server Prefix 33856@section The Server Prefix 33857@cindex server prefix 33858 33859If you prefix a command with @samp{server } then it will not affect 33860the command history, nor will it affect @value{GDBN}'s notion of which 33861command to repeat if @key{RET} is pressed on a line by itself. This 33862means that commands can be run behind a user's back by a front-end in 33863a transparent manner. 33864 33865The @code{server } prefix does not affect the recording of values into 33866the value history; to print a value without recording it into the 33867value history, use the @code{output} command instead of the 33868@code{print} command. 33869 33870Using this prefix also disables confirmation requests 33871(@pxref{confirmation requests}). 33872 33873@node Prompting 33874@section Annotation for @value{GDBN} Input 33875 33876@cindex annotations for prompts 33877When @value{GDBN} prompts for input, it annotates this fact so it is possible 33878to know when to send output, when the output from a given command is 33879over, etc. 33880 33881Different kinds of input each have a different @dfn{input type}. Each 33882input type has three annotations: a @code{pre-} annotation, which 33883denotes the beginning of any prompt which is being output, a plain 33884annotation, which denotes the end of the prompt, and then a @code{post-} 33885annotation which denotes the end of any echo which may (or may not) be 33886associated with the input. For example, the @code{prompt} input type 33887features the following annotations: 33888 33889@smallexample 33890^Z^Zpre-prompt 33891^Z^Zprompt 33892^Z^Zpost-prompt 33893@end smallexample 33894 33895The input types are 33896 33897@table @code 33898@findex pre-prompt annotation 33899@findex prompt annotation 33900@findex post-prompt annotation 33901@item prompt 33902When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt). 33903 33904@findex pre-commands annotation 33905@findex commands annotation 33906@findex post-commands annotation 33907@item commands 33908When @value{GDBN} prompts for a set of commands, like in the @code{commands} 33909command. The annotations are repeated for each command which is input. 33910 33911@findex pre-overload-choice annotation 33912@findex overload-choice annotation 33913@findex post-overload-choice annotation 33914@item overload-choice 33915When @value{GDBN} wants the user to select between various overloaded functions. 33916 33917@findex pre-query annotation 33918@findex query annotation 33919@findex post-query annotation 33920@item query 33921When @value{GDBN} wants the user to confirm a potentially dangerous operation. 33922 33923@findex pre-prompt-for-continue annotation 33924@findex prompt-for-continue annotation 33925@findex post-prompt-for-continue annotation 33926@item prompt-for-continue 33927When @value{GDBN} is asking the user to press return to continue. Note: Don't 33928expect this to work well; instead use @code{set height 0} to disable 33929prompting. This is because the counting of lines is buggy in the 33930presence of annotations. 33931@end table 33932 33933@node Errors 33934@section Errors 33935@cindex annotations for errors, warnings and interrupts 33936 33937@findex quit annotation 33938@smallexample 33939^Z^Zquit 33940@end smallexample 33941 33942This annotation occurs right before @value{GDBN} responds to an interrupt. 33943 33944@findex error annotation 33945@smallexample 33946^Z^Zerror 33947@end smallexample 33948 33949This annotation occurs right before @value{GDBN} responds to an error. 33950 33951Quit and error annotations indicate that any annotations which @value{GDBN} was 33952in the middle of may end abruptly. For example, if a 33953@code{value-history-begin} annotation is followed by a @code{error}, one 33954cannot expect to receive the matching @code{value-history-end}. One 33955cannot expect not to receive it either, however; an error annotation 33956does not necessarily mean that @value{GDBN} is immediately returning all the way 33957to the top level. 33958 33959@findex error-begin annotation 33960A quit or error annotation may be preceded by 33961 33962@smallexample 33963^Z^Zerror-begin 33964@end smallexample 33965 33966Any output between that and the quit or error annotation is the error 33967message. 33968 33969Warning messages are not yet annotated. 33970@c If we want to change that, need to fix warning(), type_error(), 33971@c range_error(), and possibly other places. 33972 33973@node Invalidation 33974@section Invalidation Notices 33975 33976@cindex annotations for invalidation messages 33977The following annotations say that certain pieces of state may have 33978changed. 33979 33980@table @code 33981@findex frames-invalid annotation 33982@item ^Z^Zframes-invalid 33983 33984The frames (for example, output from the @code{backtrace} command) may 33985have changed. 33986 33987@findex breakpoints-invalid annotation 33988@item ^Z^Zbreakpoints-invalid 33989 33990The breakpoints may have changed. For example, the user just added or 33991deleted a breakpoint. 33992@end table 33993 33994@node Annotations for Running 33995@section Running the Program 33996@cindex annotations for running programs 33997 33998@findex starting annotation 33999@findex stopping annotation 34000When the program starts executing due to a @value{GDBN} command such as 34001@code{step} or @code{continue}, 34002 34003@smallexample 34004^Z^Zstarting 34005@end smallexample 34006 34007is output. When the program stops, 34008 34009@smallexample 34010^Z^Zstopped 34011@end smallexample 34012 34013is output. Before the @code{stopped} annotation, a variety of 34014annotations describe how the program stopped. 34015 34016@table @code 34017@findex exited annotation 34018@item ^Z^Zexited @var{exit-status} 34019The program exited, and @var{exit-status} is the exit status (zero for 34020successful exit, otherwise nonzero). 34021 34022@findex signalled annotation 34023@findex signal-name annotation 34024@findex signal-name-end annotation 34025@findex signal-string annotation 34026@findex signal-string-end annotation 34027@item ^Z^Zsignalled 34028The program exited with a signal. After the @code{^Z^Zsignalled}, the 34029annotation continues: 34030 34031@smallexample 34032@var{intro-text} 34033^Z^Zsignal-name 34034@var{name} 34035^Z^Zsignal-name-end 34036@var{middle-text} 34037^Z^Zsignal-string 34038@var{string} 34039^Z^Zsignal-string-end 34040@var{end-text} 34041@end smallexample 34042 34043@noindent 34044where @var{name} is the name of the signal, such as @code{SIGILL} or 34045@code{SIGSEGV}, and @var{string} is the explanation of the signal, such 34046as @code{Illegal Instruction} or @code{Segmentation fault}. 34047@var{intro-text}, @var{middle-text}, and @var{end-text} are for the 34048user's benefit and have no particular format. 34049 34050@findex signal annotation 34051@item ^Z^Zsignal 34052The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is 34053just saying that the program received the signal, not that it was 34054terminated with it. 34055 34056@findex breakpoint annotation 34057@item ^Z^Zbreakpoint @var{number} 34058The program hit breakpoint number @var{number}. 34059 34060@findex watchpoint annotation 34061@item ^Z^Zwatchpoint @var{number} 34062The program hit watchpoint number @var{number}. 34063@end table 34064 34065@node Source Annotations 34066@section Displaying Source 34067@cindex annotations for source display 34068 34069@findex source annotation 34070The following annotation is used instead of displaying source code: 34071 34072@smallexample 34073^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr} 34074@end smallexample 34075 34076where @var{filename} is an absolute file name indicating which source 34077file, @var{line} is the line number within that file (where 1 is the 34078first line in the file), @var{character} is the character position 34079within the file (where 0 is the first character in the file) (for most 34080debug formats this will necessarily point to the beginning of a line), 34081@var{middle} is @samp{middle} if @var{addr} is in the middle of the 34082line, or @samp{beg} if @var{addr} is at the beginning of the line, and 34083@var{addr} is the address in the target program associated with the 34084source which is being displayed. @var{addr} is in the form @samp{0x} 34085followed by one or more lowercase hex digits (note that this does not 34086depend on the language). 34087 34088@node JIT Interface 34089@chapter JIT Compilation Interface 34090@cindex just-in-time compilation 34091@cindex JIT compilation interface 34092 34093This chapter documents @value{GDBN}'s @dfn{just-in-time} (JIT) compilation 34094interface. A JIT compiler is a program or library that generates native 34095executable code at runtime and executes it, usually in order to achieve good 34096performance while maintaining platform independence. 34097 34098Programs that use JIT compilation are normally difficult to debug because 34099portions of their code are generated at runtime, instead of being loaded from 34100object files, which is where @value{GDBN} normally finds the program's symbols 34101and debug information. In order to debug programs that use JIT compilation, 34102@value{GDBN} has an interface that allows the program to register in-memory 34103symbol files with @value{GDBN} at runtime. 34104 34105If you are using @value{GDBN} to debug a program that uses this interface, then 34106it should work transparently so long as you have not stripped the binary. If 34107you are developing a JIT compiler, then the interface is documented in the rest 34108of this chapter. At this time, the only known client of this interface is the 34109LLVM JIT. 34110 34111Broadly speaking, the JIT interface mirrors the dynamic loader interface. The 34112JIT compiler communicates with @value{GDBN} by writing data into a global 34113variable and calling a fuction at a well-known symbol. When @value{GDBN} 34114attaches, it reads a linked list of symbol files from the global variable to 34115find existing code, and puts a breakpoint in the function so that it can find 34116out about additional code. 34117 34118@menu 34119* Declarations:: Relevant C struct declarations 34120* Registering Code:: Steps to register code 34121* Unregistering Code:: Steps to unregister code 34122* Custom Debug Info:: Emit debug information in a custom format 34123@end menu 34124 34125@node Declarations 34126@section JIT Declarations 34127 34128These are the relevant struct declarations that a C program should include to 34129implement the interface: 34130 34131@smallexample 34132typedef enum 34133@{ 34134 JIT_NOACTION = 0, 34135 JIT_REGISTER_FN, 34136 JIT_UNREGISTER_FN 34137@} jit_actions_t; 34138 34139struct jit_code_entry 34140@{ 34141 struct jit_code_entry *next_entry; 34142 struct jit_code_entry *prev_entry; 34143 const char *symfile_addr; 34144 uint64_t symfile_size; 34145@}; 34146 34147struct jit_descriptor 34148@{ 34149 uint32_t version; 34150 /* This type should be jit_actions_t, but we use uint32_t 34151 to be explicit about the bitwidth. */ 34152 uint32_t action_flag; 34153 struct jit_code_entry *relevant_entry; 34154 struct jit_code_entry *first_entry; 34155@}; 34156 34157/* GDB puts a breakpoint in this function. */ 34158void __attribute__((noinline)) __jit_debug_register_code() @{ @}; 34159 34160/* Make sure to specify the version statically, because the 34161 debugger may check the version before we can set it. */ 34162struct jit_descriptor __jit_debug_descriptor = @{ 1, 0, 0, 0 @}; 34163@end smallexample 34164 34165If the JIT is multi-threaded, then it is important that the JIT synchronize any 34166modifications to this global data properly, which can easily be done by putting 34167a global mutex around modifications to these structures. 34168 34169@node Registering Code 34170@section Registering Code 34171 34172To register code with @value{GDBN}, the JIT should follow this protocol: 34173 34174@itemize @bullet 34175@item 34176Generate an object file in memory with symbols and other desired debug 34177information. The file must include the virtual addresses of the sections. 34178 34179@item 34180Create a code entry for the file, which gives the start and size of the symbol 34181file. 34182 34183@item 34184Add it to the linked list in the JIT descriptor. 34185 34186@item 34187Point the relevant_entry field of the descriptor at the entry. 34188 34189@item 34190Set @code{action_flag} to @code{JIT_REGISTER} and call 34191@code{__jit_debug_register_code}. 34192@end itemize 34193 34194When @value{GDBN} is attached and the breakpoint fires, @value{GDBN} uses the 34195@code{relevant_entry} pointer so it doesn't have to walk the list looking for 34196new code. However, the linked list must still be maintained in order to allow 34197@value{GDBN} to attach to a running process and still find the symbol files. 34198 34199@node Unregistering Code 34200@section Unregistering Code 34201 34202If code is freed, then the JIT should use the following protocol: 34203 34204@itemize @bullet 34205@item 34206Remove the code entry corresponding to the code from the linked list. 34207 34208@item 34209Point the @code{relevant_entry} field of the descriptor at the code entry. 34210 34211@item 34212Set @code{action_flag} to @code{JIT_UNREGISTER} and call 34213@code{__jit_debug_register_code}. 34214@end itemize 34215 34216If the JIT frees or recompiles code without unregistering it, then @value{GDBN} 34217and the JIT will leak the memory used for the associated symbol files. 34218 34219@node Custom Debug Info 34220@section Custom Debug Info 34221@cindex custom JIT debug info 34222@cindex JIT debug info reader 34223 34224Generating debug information in platform-native file formats (like ELF 34225or COFF) may be an overkill for JIT compilers; especially if all the 34226debug info is used for is displaying a meaningful backtrace. The 34227issue can be resolved by having the JIT writers decide on a debug info 34228format and also provide a reader that parses the debug info generated 34229by the JIT compiler. This section gives a brief overview on writing 34230such a parser. More specific details can be found in the source file 34231@file{gdb/jit-reader.in}, which is also installed as a header at 34232@file{@var{includedir}/gdb/jit-reader.h} for easy inclusion. 34233 34234The reader is implemented as a shared object (so this functionality is 34235not available on platforms which don't allow loading shared objects at 34236runtime). Two @value{GDBN} commands, @code{jit-reader-load} and 34237@code{jit-reader-unload} are provided, to be used to load and unload 34238the readers from a preconfigured directory. Once loaded, the shared 34239object is used the parse the debug information emitted by the JIT 34240compiler. 34241 34242@menu 34243* Using JIT Debug Info Readers:: How to use supplied readers correctly 34244* Writing JIT Debug Info Readers:: Creating a debug-info reader 34245@end menu 34246 34247@node Using JIT Debug Info Readers 34248@subsection Using JIT Debug Info Readers 34249@kindex jit-reader-load 34250@kindex jit-reader-unload 34251 34252Readers can be loaded and unloaded using the @code{jit-reader-load} 34253and @code{jit-reader-unload} commands. 34254 34255@table @code 34256@item jit-reader-load @var{reader} 34257Load the JIT reader named @var{reader}. @var{reader} is a shared 34258object specified as either an absolute or a relative file name. In 34259the latter case, @value{GDBN} will try to load the reader from a 34260pre-configured directory, usually @file{@var{libdir}/gdb/} on a UNIX 34261system (here @var{libdir} is the system library directory, often 34262@file{/usr/local/lib}). 34263 34264Only one reader can be active at a time; trying to load a second 34265reader when one is already loaded will result in @value{GDBN} 34266reporting an error. A new JIT reader can be loaded by first unloading 34267the current one using @code{jit-reader-unload} and then invoking 34268@code{jit-reader-load}. 34269 34270@item jit-reader-unload 34271Unload the currently loaded JIT reader. 34272 34273@end table 34274 34275@node Writing JIT Debug Info Readers 34276@subsection Writing JIT Debug Info Readers 34277@cindex writing JIT debug info readers 34278 34279As mentioned, a reader is essentially a shared object conforming to a 34280certain ABI. This ABI is described in @file{jit-reader.h}. 34281 34282@file{jit-reader.h} defines the structures, macros and functions 34283required to write a reader. It is installed (along with 34284@value{GDBN}), in @file{@var{includedir}/gdb} where @var{includedir} is 34285the system include directory. 34286 34287Readers need to be released under a GPL compatible license. A reader 34288can be declared as released under such a license by placing the macro 34289@code{GDB_DECLARE_GPL_COMPATIBLE_READER} in a source file. 34290 34291The entry point for readers is the symbol @code{gdb_init_reader}, 34292which is expected to be a function with the prototype 34293 34294@findex gdb_init_reader 34295@smallexample 34296extern struct gdb_reader_funcs *gdb_init_reader (void); 34297@end smallexample 34298 34299@cindex @code{struct gdb_reader_funcs} 34300 34301@code{struct gdb_reader_funcs} contains a set of pointers to callback 34302functions. These functions are executed to read the debug info 34303generated by the JIT compiler (@code{read}), to unwind stack frames 34304(@code{unwind}) and to create canonical frame IDs 34305(@code{get_Frame_id}). It also has a callback that is called when the 34306reader is being unloaded (@code{destroy}). The struct looks like this 34307 34308@smallexample 34309struct gdb_reader_funcs 34310@{ 34311 /* Must be set to GDB_READER_INTERFACE_VERSION. */ 34312 int reader_version; 34313 34314 /* For use by the reader. */ 34315 void *priv_data; 34316 34317 gdb_read_debug_info *read; 34318 gdb_unwind_frame *unwind; 34319 gdb_get_frame_id *get_frame_id; 34320 gdb_destroy_reader *destroy; 34321@}; 34322@end smallexample 34323 34324@cindex @code{struct gdb_symbol_callbacks} 34325@cindex @code{struct gdb_unwind_callbacks} 34326 34327The callbacks are provided with another set of callbacks by 34328@value{GDBN} to do their job. For @code{read}, these callbacks are 34329passed in a @code{struct gdb_symbol_callbacks} and for @code{unwind} 34330and @code{get_frame_id}, in a @code{struct gdb_unwind_callbacks}. 34331@code{struct gdb_symbol_callbacks} has callbacks to create new object 34332files and new symbol tables inside those object files. @code{struct 34333gdb_unwind_callbacks} has callbacks to read registers off the current 34334frame and to write out the values of the registers in the previous 34335frame. Both have a callback (@code{target_read}) to read bytes off the 34336target's address space. 34337 34338@node In-Process Agent 34339@chapter In-Process Agent 34340@cindex debugging agent 34341The traditional debugging model is conceptually low-speed, but works fine, 34342because most bugs can be reproduced in debugging-mode execution. However, 34343as multi-core or many-core processors are becoming mainstream, and 34344multi-threaded programs become more and more popular, there should be more 34345and more bugs that only manifest themselves at normal-mode execution, for 34346example, thread races, because debugger's interference with the program's 34347timing may conceal the bugs. On the other hand, in some applications, 34348it is not feasible for the debugger to interrupt the program's execution 34349long enough for the developer to learn anything helpful about its behavior. 34350If the program's correctness depends on its real-time behavior, delays 34351introduced by a debugger might cause the program to fail, even when the 34352code itself is correct. It is useful to be able to observe the program's 34353behavior without interrupting it. 34354 34355Therefore, traditional debugging model is too intrusive to reproduce 34356some bugs. In order to reduce the interference with the program, we can 34357reduce the number of operations performed by debugger. The 34358@dfn{In-Process Agent}, a shared library, is running within the same 34359process with inferior, and is able to perform some debugging operations 34360itself. As a result, debugger is only involved when necessary, and 34361performance of debugging can be improved accordingly. Note that 34362interference with program can be reduced but can't be removed completely, 34363because the in-process agent will still stop or slow down the program. 34364 34365The in-process agent can interpret and execute Agent Expressions 34366(@pxref{Agent Expressions}) during performing debugging operations. The 34367agent expressions can be used for different purposes, such as collecting 34368data in tracepoints, and condition evaluation in breakpoints. 34369 34370@anchor{Control Agent} 34371You can control whether the in-process agent is used as an aid for 34372debugging with the following commands: 34373 34374@table @code 34375@kindex set agent on 34376@item set agent on 34377Causes the in-process agent to perform some operations on behalf of the 34378debugger. Just which operations requested by the user will be done 34379by the in-process agent depends on the its capabilities. For example, 34380if you request to evaluate breakpoint conditions in the in-process agent, 34381and the in-process agent has such capability as well, then breakpoint 34382conditions will be evaluated in the in-process agent. 34383 34384@kindex set agent off 34385@item set agent off 34386Disables execution of debugging operations by the in-process agent. All 34387of the operations will be performed by @value{GDBN}. 34388 34389@kindex show agent 34390@item show agent 34391Display the current setting of execution of debugging operations by 34392the in-process agent. 34393@end table 34394 34395@menu 34396* In-Process Agent Protocol:: 34397@end menu 34398 34399@node In-Process Agent Protocol 34400@section In-Process Agent Protocol 34401@cindex in-process agent protocol 34402 34403The in-process agent is able to communicate with both @value{GDBN} and 34404GDBserver (@pxref{In-Process Agent}). This section documents the protocol 34405used for communications between @value{GDBN} or GDBserver and the IPA. 34406In general, @value{GDBN} or GDBserver sends commands 34407(@pxref{IPA Protocol Commands}) and data to in-process agent, and then 34408in-process agent replies back with the return result of the command, or 34409some other information. The data sent to in-process agent is composed 34410of primitive data types, such as 4-byte or 8-byte type, and composite 34411types, which are called objects (@pxref{IPA Protocol Objects}). 34412 34413@menu 34414* IPA Protocol Objects:: 34415* IPA Protocol Commands:: 34416@end menu 34417 34418@node IPA Protocol Objects 34419@subsection IPA Protocol Objects 34420@cindex ipa protocol objects 34421 34422The commands sent to and results received from agent may contain some 34423complex data types called @dfn{objects}. 34424 34425The in-process agent is running on the same machine with @value{GDBN} 34426or GDBserver, so it doesn't have to handle as much differences between 34427two ends as remote protocol (@pxref{Remote Protocol}) tries to handle. 34428However, there are still some differences of two ends in two processes: 34429 34430@enumerate 34431@item 34432word size. On some 64-bit machines, @value{GDBN} or GDBserver can be 34433compiled as a 64-bit executable, while in-process agent is a 32-bit one. 34434@item 34435ABI. Some machines may have multiple types of ABI, @value{GDBN} or 34436GDBserver is compiled with one, and in-process agent is compiled with 34437the other one. 34438@end enumerate 34439 34440Here are the IPA Protocol Objects: 34441 34442@enumerate 34443@item 34444agent expression object. It represents an agent expression 34445(@pxref{Agent Expressions}). 34446@anchor{agent expression object} 34447@item 34448tracepoint action object. It represents a tracepoint action 34449(@pxref{Tracepoint Actions,,Tracepoint Action Lists}) to collect registers, 34450memory, static trace data and to evaluate expression. 34451@anchor{tracepoint action object} 34452@item 34453tracepoint object. It represents a tracepoint (@pxref{Tracepoints}). 34454@anchor{tracepoint object} 34455 34456@end enumerate 34457 34458The following table describes important attributes of each IPA protocol 34459object: 34460 34461@multitable @columnfractions .30 .20 .50 34462@headitem Name @tab Size @tab Description 34463@item @emph{agent expression object} @tab @tab 34464@item length @tab 4 @tab length of bytes code 34465@item byte code @tab @var{length} @tab contents of byte code 34466@item @emph{tracepoint action for collecting memory} @tab @tab 34467@item 'M' @tab 1 @tab type of tracepoint action 34468@item addr @tab 8 @tab if @var{basereg} is @samp{-1}, @var{addr} is the 34469address of the lowest byte to collect, otherwise @var{addr} is the offset 34470of @var{basereg} for memory collecting. 34471@item len @tab 8 @tab length of memory for collecting 34472@item basereg @tab 4 @tab the register number containing the starting 34473memory address for collecting. 34474@item @emph{tracepoint action for collecting registers} @tab @tab 34475@item 'R' @tab 1 @tab type of tracepoint action 34476@item @emph{tracepoint action for collecting static trace data} @tab @tab 34477@item 'L' @tab 1 @tab type of tracepoint action 34478@item @emph{tracepoint action for expression evaluation} @tab @tab 34479@item 'X' @tab 1 @tab type of tracepoint action 34480@item agent expression @tab length of @tab @ref{agent expression object} 34481@item @emph{tracepoint object} @tab @tab 34482@item number @tab 4 @tab number of tracepoint 34483@item address @tab 8 @tab address of tracepoint inserted on 34484@item type @tab 4 @tab type of tracepoint 34485@item enabled @tab 1 @tab enable or disable of tracepoint 34486@item step_count @tab 8 @tab step 34487@item pass_count @tab 8 @tab pass 34488@item numactions @tab 4 @tab number of tracepoint actions 34489@item hit count @tab 8 @tab hit count 34490@item trace frame usage @tab 8 @tab trace frame usage 34491@item compiled_cond @tab 8 @tab compiled condition 34492@item orig_size @tab 8 @tab orig size 34493@item condition @tab 4 if condition is NULL otherwise length of 34494@ref{agent expression object} 34495@tab zero if condition is NULL, otherwise is 34496@ref{agent expression object} 34497@item actions @tab variable 34498@tab numactions number of @ref{tracepoint action object} 34499@end multitable 34500 34501@node IPA Protocol Commands 34502@subsection IPA Protocol Commands 34503@cindex ipa protocol commands 34504 34505The spaces in each command are delimiters to ease reading this commands 34506specification. They don't exist in real commands. 34507 34508@table @samp 34509 34510@item FastTrace:@var{tracepoint_object} @var{gdb_jump_pad_head} 34511Installs a new fast tracepoint described by @var{tracepoint_object} 34512(@pxref{tracepoint object}). @var{gdb_jump_pad_head}, 8-byte long, is the 34513head of @dfn{jumppad}, which is used to jump to data collection routine 34514in IPA finally. 34515 34516Replies: 34517@table @samp 34518@item OK @var{target_address} @var{gdb_jump_pad_head} @var{fjump_size} @var{fjump} 34519@var{target_address} is address of tracepoint in the inferior. 34520@var{gdb_jump_pad_head} is updated head of jumppad. Both of 34521@var{target_address} and @var{gdb_jump_pad_head} are 8-byte long. 34522@var{fjump} contains a sequence of instructions jump to jumppad entry. 34523@var{fjump_size}, 4-byte long, is the size of @var{fjump}. 34524@item E @var{NN} 34525for an error 34526 34527@end table 34528 34529@item close 34530Closes the in-process agent. This command is sent when @value{GDBN} or GDBserver 34531is about to kill inferiors. 34532 34533@item qTfSTM 34534@xref{qTfSTM}. 34535@item qTsSTM 34536@xref{qTsSTM}. 34537@item qTSTMat 34538@xref{qTSTMat}. 34539@item probe_marker_at:@var{address} 34540Asks in-process agent to probe the marker at @var{address}. 34541 34542Replies: 34543@table @samp 34544@item E @var{NN} 34545for an error 34546@end table 34547@item unprobe_marker_at:@var{address} 34548Asks in-process agent to unprobe the marker at @var{address}. 34549@end table 34550 34551@node GDB Bugs 34552@chapter Reporting Bugs in @value{GDBN} 34553@cindex bugs in @value{GDBN} 34554@cindex reporting bugs in @value{GDBN} 34555 34556Your bug reports play an essential role in making @value{GDBN} reliable. 34557 34558Reporting a bug may help you by bringing a solution to your problem, or it 34559may not. But in any case the principal function of a bug report is to help 34560the entire community by making the next version of @value{GDBN} work better. Bug 34561reports are your contribution to the maintenance of @value{GDBN}. 34562 34563In order for a bug report to serve its purpose, you must include the 34564information that enables us to fix the bug. 34565 34566@menu 34567* Bug Criteria:: Have you found a bug? 34568* Bug Reporting:: How to report bugs 34569@end menu 34570 34571@node Bug Criteria 34572@section Have You Found a Bug? 34573@cindex bug criteria 34574 34575If you are not sure whether you have found a bug, here are some guidelines: 34576 34577@itemize @bullet 34578@cindex fatal signal 34579@cindex debugger crash 34580@cindex crash of debugger 34581@item 34582If the debugger gets a fatal signal, for any input whatever, that is a 34583@value{GDBN} bug. Reliable debuggers never crash. 34584 34585@cindex error on valid input 34586@item 34587If @value{GDBN} produces an error message for valid input, that is a 34588bug. (Note that if you're cross debugging, the problem may also be 34589somewhere in the connection to the target.) 34590 34591@cindex invalid input 34592@item 34593If @value{GDBN} does not produce an error message for invalid input, 34594that is a bug. However, you should note that your idea of 34595``invalid input'' might be our idea of ``an extension'' or ``support 34596for traditional practice''. 34597 34598@item 34599If you are an experienced user of debugging tools, your suggestions 34600for improvement of @value{GDBN} are welcome in any case. 34601@end itemize 34602 34603@node Bug Reporting 34604@section How to Report Bugs 34605@cindex bug reports 34606@cindex @value{GDBN} bugs, reporting 34607 34608A number of companies and individuals offer support for @sc{gnu} products. 34609If you obtained @value{GDBN} from a support organization, we recommend you 34610contact that organization first. 34611 34612You can find contact information for many support companies and 34613individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs 34614distribution. 34615@c should add a web page ref... 34616 34617@ifset BUGURL 34618@ifset BUGURL_DEFAULT 34619In any event, we also recommend that you submit bug reports for 34620@value{GDBN}. The preferred method is to submit them directly using 34621@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web 34622page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can 34623be used. 34624 34625@strong{Do not send bug reports to @samp{info-gdb}, or to 34626@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do 34627not want to receive bug reports. Those that do have arranged to receive 34628@samp{bug-gdb}. 34629 34630The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which 34631serves as a repeater. The mailing list and the newsgroup carry exactly 34632the same messages. Often people think of posting bug reports to the 34633newsgroup instead of mailing them. This appears to work, but it has one 34634problem which can be crucial: a newsgroup posting often lacks a mail 34635path back to the sender. Thus, if we need to ask for more information, 34636we may be unable to reach you. For this reason, it is better to send 34637bug reports to the mailing list. 34638@end ifset 34639@ifclear BUGURL_DEFAULT 34640In any event, we also recommend that you submit bug reports for 34641@value{GDBN} to @value{BUGURL}. 34642@end ifclear 34643@end ifset 34644 34645The fundamental principle of reporting bugs usefully is this: 34646@strong{report all the facts}. If you are not sure whether to state a 34647fact or leave it out, state it! 34648 34649Often people omit facts because they think they know what causes the 34650problem and assume that some details do not matter. Thus, you might 34651assume that the name of the variable you use in an example does not matter. 34652Well, probably it does not, but one cannot be sure. Perhaps the bug is a 34653stray memory reference which happens to fetch from the location where that 34654name is stored in memory; perhaps, if the name were different, the contents 34655of that location would fool the debugger into doing the right thing despite 34656the bug. Play it safe and give a specific, complete example. That is the 34657easiest thing for you to do, and the most helpful. 34658 34659Keep in mind that the purpose of a bug report is to enable us to fix the 34660bug. It may be that the bug has been reported previously, but neither 34661you nor we can know that unless your bug report is complete and 34662self-contained. 34663 34664Sometimes people give a few sketchy facts and ask, ``Does this ring a 34665bell?'' Those bug reports are useless, and we urge everyone to 34666@emph{refuse to respond to them} except to chide the sender to report 34667bugs properly. 34668 34669To enable us to fix the bug, you should include all these things: 34670 34671@itemize @bullet 34672@item 34673The version of @value{GDBN}. @value{GDBN} announces it if you start 34674with no arguments; you can also print it at any time using @code{show 34675version}. 34676 34677Without this, we will not know whether there is any point in looking for 34678the bug in the current version of @value{GDBN}. 34679 34680@item 34681The type of machine you are using, and the operating system name and 34682version number. 34683 34684@item 34685What compiler (and its version) was used to compile @value{GDBN}---e.g.@: 34686``@value{GCC}--2.8.1''. 34687 34688@item 34689What compiler (and its version) was used to compile the program you are 34690debugging---e.g.@: ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP 34691C Compiler''. For @value{NGCC}, you can say @kbd{@value{GCC} --version} 34692to get this information; for other compilers, see the documentation for 34693those compilers. 34694 34695@item 34696The command arguments you gave the compiler to compile your example and 34697observe the bug. For example, did you use @samp{-O}? To guarantee 34698you will not omit something important, list them all. A copy of the 34699Makefile (or the output from make) is sufficient. 34700 34701If we were to try to guess the arguments, we would probably guess wrong 34702and then we might not encounter the bug. 34703 34704@item 34705A complete input script, and all necessary source files, that will 34706reproduce the bug. 34707 34708@item 34709A description of what behavior you observe that you believe is 34710incorrect. For example, ``It gets a fatal signal.'' 34711 34712Of course, if the bug is that @value{GDBN} gets a fatal signal, then we 34713will certainly notice it. But if the bug is incorrect output, we might 34714not notice unless it is glaringly wrong. You might as well not give us 34715a chance to make a mistake. 34716 34717Even if the problem you experience is a fatal signal, you should still 34718say so explicitly. Suppose something strange is going on, such as, your 34719copy of @value{GDBN} is out of synch, or you have encountered a bug in 34720the C library on your system. (This has happened!) Your copy might 34721crash and ours would not. If you told us to expect a crash, then when 34722ours fails to crash, we would know that the bug was not happening for 34723us. If you had not told us to expect a crash, then we would not be able 34724to draw any conclusion from our observations. 34725 34726@pindex script 34727@cindex recording a session script 34728To collect all this information, you can use a session recording program 34729such as @command{script}, which is available on many Unix systems. 34730Just run your @value{GDBN} session inside @command{script} and then 34731include the @file{typescript} file with your bug report. 34732 34733Another way to record a @value{GDBN} session is to run @value{GDBN} 34734inside Emacs and then save the entire buffer to a file. 34735 34736@item 34737If you wish to suggest changes to the @value{GDBN} source, send us context 34738diffs. If you even discuss something in the @value{GDBN} source, refer to 34739it by context, not by line number. 34740 34741The line numbers in our development sources will not match those in your 34742sources. Your line numbers would convey no useful information to us. 34743 34744@end itemize 34745 34746Here are some things that are not necessary: 34747 34748@itemize @bullet 34749@item 34750A description of the envelope of the bug. 34751 34752Often people who encounter a bug spend a lot of time investigating 34753which changes to the input file will make the bug go away and which 34754changes will not affect it. 34755 34756This is often time consuming and not very useful, because the way we 34757will find the bug is by running a single example under the debugger 34758with breakpoints, not by pure deduction from a series of examples. 34759We recommend that you save your time for something else. 34760 34761Of course, if you can find a simpler example to report @emph{instead} 34762of the original one, that is a convenience for us. Errors in the 34763output will be easier to spot, running under the debugger will take 34764less time, and so on. 34765 34766However, simplification is not vital; if you do not want to do this, 34767report the bug anyway and send us the entire test case you used. 34768 34769@item 34770A patch for the bug. 34771 34772A patch for the bug does help us if it is a good one. But do not omit 34773the necessary information, such as the test case, on the assumption that 34774a patch is all we need. We might see problems with your patch and decide 34775to fix the problem another way, or we might not understand it at all. 34776 34777Sometimes with a program as complicated as @value{GDBN} it is very hard to 34778construct an example that will make the program follow a certain path 34779through the code. If you do not send us the example, we will not be able 34780to construct one, so we will not be able to verify that the bug is fixed. 34781 34782And if we cannot understand what bug you are trying to fix, or why your 34783patch should be an improvement, we will not install it. A test case will 34784help us to understand. 34785 34786@item 34787A guess about what the bug is or what it depends on. 34788 34789Such guesses are usually wrong. Even we cannot guess right about such 34790things without first using the debugger to find the facts. 34791@end itemize 34792 34793@c The readline documentation is distributed with the readline code 34794@c and consists of the two following files: 34795@c rluser.texi 34796@c hsuser.texi 34797@c Use -I with makeinfo to point to the appropriate directory, 34798@c environment var TEXINPUTS with TeX. 34799@ifclear SYSTEM_READLINE 34800@include rluser.texi 34801@include hsuser.texi 34802@end ifclear 34803 34804@node In Memoriam 34805@appendix In Memoriam 34806 34807The @value{GDBN} project mourns the loss of the following long-time 34808contributors: 34809 34810@table @code 34811@item Fred Fish 34812Fred was a long-standing contributor to @value{GDBN} (1991-2006), and 34813to Free Software in general. Outside of @value{GDBN}, he was known in 34814the Amiga world for his series of Fish Disks, and the GeekGadget project. 34815 34816@item Michael Snyder 34817Michael was one of the Global Maintainers of the @value{GDBN} project, 34818with contributions recorded as early as 1996, until 2011. In addition 34819to his day to day participation, he was a large driving force behind 34820adding Reverse Debugging to @value{GDBN}. 34821@end table 34822 34823Beyond their technical contributions to the project, they were also 34824enjoyable members of the Free Software Community. We will miss them. 34825 34826@node Formatting Documentation 34827@appendix Formatting Documentation 34828 34829@cindex @value{GDBN} reference card 34830@cindex reference card 34831The @value{GDBN} 4 release includes an already-formatted reference card, ready 34832for printing with PostScript or Ghostscript, in the @file{gdb} 34833subdirectory of the main source directory@footnote{In 34834@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN} 34835release.}. If you can use PostScript or Ghostscript with your printer, 34836you can print the reference card immediately with @file{refcard.ps}. 34837 34838The release also includes the source for the reference card. You 34839can format it, using @TeX{}, by typing: 34840 34841@smallexample 34842make refcard.dvi 34843@end smallexample 34844 34845The @value{GDBN} reference card is designed to print in @dfn{landscape} 34846mode on US ``letter'' size paper; 34847that is, on a sheet 11 inches wide by 8.5 inches 34848high. You will need to specify this form of printing as an option to 34849your @sc{dvi} output program. 34850 34851@cindex documentation 34852 34853All the documentation for @value{GDBN} comes as part of the machine-readable 34854distribution. The documentation is written in Texinfo format, which is 34855a documentation system that uses a single source file to produce both 34856on-line information and a printed manual. You can use one of the Info 34857formatting commands to create the on-line version of the documentation 34858and @TeX{} (or @code{texi2roff}) to typeset the printed version. 34859 34860@value{GDBN} includes an already formatted copy of the on-line Info 34861version of this manual in the @file{gdb} subdirectory. The main Info 34862file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to 34863subordinate files matching @samp{gdb.info*} in the same directory. If 34864necessary, you can print out these files, or read them with any editor; 34865but they are easier to read using the @code{info} subsystem in @sc{gnu} 34866Emacs or the standalone @code{info} program, available as part of the 34867@sc{gnu} Texinfo distribution. 34868 34869If you want to format these Info files yourself, you need one of the 34870Info formatting programs, such as @code{texinfo-format-buffer} or 34871@code{makeinfo}. 34872 34873If you have @code{makeinfo} installed, and are in the top level 34874@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of 34875version @value{GDBVN}), you can make the Info file by typing: 34876 34877@smallexample 34878cd gdb 34879make gdb.info 34880@end smallexample 34881 34882If you want to typeset and print copies of this manual, you need @TeX{}, 34883a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the 34884Texinfo definitions file. 34885 34886@TeX{} is a typesetting program; it does not print files directly, but 34887produces output files called @sc{dvi} files. To print a typeset 34888document, you need a program to print @sc{dvi} files. If your system 34889has @TeX{} installed, chances are it has such a program. The precise 34890command to use depends on your system; @kbd{lpr -d} is common; another 34891(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may 34892require a file name without any extension or a @samp{.dvi} extension. 34893 34894@TeX{} also requires a macro definitions file called 34895@file{texinfo.tex}. This file tells @TeX{} how to typeset a document 34896written in Texinfo format. On its own, @TeX{} cannot either read or 34897typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB 34898and is located in the @file{gdb-@var{version-number}/texinfo} 34899directory. 34900 34901If you have @TeX{} and a @sc{dvi} printer program installed, you can 34902typeset and print this manual. First switch to the @file{gdb} 34903subdirectory of the main source directory (for example, to 34904@file{gdb-@value{GDBVN}/gdb}) and type: 34905 34906@smallexample 34907make gdb.dvi 34908@end smallexample 34909 34910Then give @file{gdb.dvi} to your @sc{dvi} printing program. 34911 34912@node Installing GDB 34913@appendix Installing @value{GDBN} 34914@cindex installation 34915 34916@menu 34917* Requirements:: Requirements for building @value{GDBN} 34918* Running Configure:: Invoking the @value{GDBN} @file{configure} script 34919* Separate Objdir:: Compiling @value{GDBN} in another directory 34920* Config Names:: Specifying names for hosts and targets 34921* Configure Options:: Summary of options for configure 34922* System-wide configuration:: Having a system-wide init file 34923@end menu 34924 34925@node Requirements 34926@section Requirements for Building @value{GDBN} 34927@cindex building @value{GDBN}, requirements for 34928 34929Building @value{GDBN} requires various tools and packages to be available. 34930Other packages will be used only if they are found. 34931 34932@heading Tools/Packages Necessary for Building @value{GDBN} 34933@table @asis 34934@item ISO C90 compiler 34935@value{GDBN} is written in ISO C90. It should be buildable with any 34936working C90 compiler, e.g.@: GCC. 34937 34938@end table 34939 34940@heading Tools/Packages Optional for Building @value{GDBN} 34941@table @asis 34942@item Expat 34943@anchor{Expat} 34944@value{GDBN} can use the Expat XML parsing library. This library may be 34945included with your operating system distribution; if it is not, you 34946can get the latest version from @url{http://expat.sourceforge.net}. 34947The @file{configure} script will search for this library in several 34948standard locations; if it is installed in an unusual path, you can 34949use the @option{--with-libexpat-prefix} option to specify its location. 34950 34951Expat is used for: 34952 34953@itemize @bullet 34954@item 34955Remote protocol memory maps (@pxref{Memory Map Format}) 34956@item 34957Target descriptions (@pxref{Target Descriptions}) 34958@item 34959Remote shared library lists (@xref{Library List Format}, 34960or alternatively @pxref{Library List Format for SVR4 Targets}) 34961@item 34962MS-Windows shared libraries (@pxref{Shared Libraries}) 34963@item 34964Traceframe info (@pxref{Traceframe Info Format}) 34965@item 34966Branch trace (@pxref{Branch Trace Format}) 34967@end itemize 34968 34969@item zlib 34970@cindex compressed debug sections 34971@value{GDBN} will use the @samp{zlib} library, if available, to read 34972compressed debug sections. Some linkers, such as GNU gold, are capable 34973of producing binaries with compressed debug sections. If @value{GDBN} 34974is compiled with @samp{zlib}, it will be able to read the debug 34975information in such binaries. 34976 34977The @samp{zlib} library is likely included with your operating system 34978distribution; if it is not, you can get the latest version from 34979@url{http://zlib.net}. 34980 34981@item iconv 34982@value{GDBN}'s features related to character sets (@pxref{Character 34983Sets}) require a functioning @code{iconv} implementation. If you are 34984on a GNU system, then this is provided by the GNU C Library. Some 34985other systems also provide a working @code{iconv}. 34986 34987If @value{GDBN} is using the @code{iconv} program which is installed 34988in a non-standard place, you will need to tell @value{GDBN} where to find it. 34989This is done with @option{--with-iconv-bin} which specifies the 34990directory that contains the @code{iconv} program. 34991 34992On systems without @code{iconv}, you can install GNU Libiconv. If you 34993have previously installed Libiconv, you can use the 34994@option{--with-libiconv-prefix} option to configure. 34995 34996@value{GDBN}'s top-level @file{configure} and @file{Makefile} will 34997arrange to build Libiconv if a directory named @file{libiconv} appears 34998in the top-most source directory. If Libiconv is built this way, and 34999if the operating system does not provide a suitable @code{iconv} 35000implementation, then the just-built library will automatically be used 35001by @value{GDBN}. One easy way to set this up is to download GNU 35002Libiconv, unpack it, and then rename the directory holding the 35003Libiconv source code to @samp{libiconv}. 35004@end table 35005 35006@node Running Configure 35007@section Invoking the @value{GDBN} @file{configure} Script 35008@cindex configuring @value{GDBN} 35009@value{GDBN} comes with a @file{configure} script that automates the process 35010of preparing @value{GDBN} for installation; you can then use @code{make} to 35011build the @code{gdb} program. 35012@iftex 35013@c irrelevant in info file; it's as current as the code it lives with. 35014@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN}, 35015look at the @file{README} file in the sources; we may have improved the 35016installation procedures since publishing this manual.} 35017@end iftex 35018 35019The @value{GDBN} distribution includes all the source code you need for 35020@value{GDBN} in a single directory, whose name is usually composed by 35021appending the version number to @samp{gdb}. 35022 35023For example, the @value{GDBN} version @value{GDBVN} distribution is in the 35024@file{gdb-@value{GDBVN}} directory. That directory contains: 35025 35026@table @code 35027@item gdb-@value{GDBVN}/configure @r{(and supporting files)} 35028script for configuring @value{GDBN} and all its supporting libraries 35029 35030@item gdb-@value{GDBVN}/gdb 35031the source specific to @value{GDBN} itself 35032 35033@item gdb-@value{GDBVN}/bfd 35034source for the Binary File Descriptor library 35035 35036@item gdb-@value{GDBVN}/include 35037@sc{gnu} include files 35038 35039@item gdb-@value{GDBVN}/libiberty 35040source for the @samp{-liberty} free software library 35041 35042@item gdb-@value{GDBVN}/opcodes 35043source for the library of opcode tables and disassemblers 35044 35045@item gdb-@value{GDBVN}/readline 35046source for the @sc{gnu} command-line interface 35047 35048@item gdb-@value{GDBVN}/glob 35049source for the @sc{gnu} filename pattern-matching subroutine 35050 35051@item gdb-@value{GDBVN}/mmalloc 35052source for the @sc{gnu} memory-mapped malloc package 35053@end table 35054 35055The simplest way to configure and build @value{GDBN} is to run @file{configure} 35056from the @file{gdb-@var{version-number}} source directory, which in 35057this example is the @file{gdb-@value{GDBVN}} directory. 35058 35059First switch to the @file{gdb-@var{version-number}} source directory 35060if you are not already in it; then run @file{configure}. Pass the 35061identifier for the platform on which @value{GDBN} will run as an 35062argument. 35063 35064For example: 35065 35066@smallexample 35067cd gdb-@value{GDBVN} 35068./configure @var{host} 35069make 35070@end smallexample 35071 35072@noindent 35073where @var{host} is an identifier such as @samp{sun4} or 35074@samp{decstation}, that identifies the platform where @value{GDBN} will run. 35075(You can often leave off @var{host}; @file{configure} tries to guess the 35076correct value by examining your system.) 35077 35078Running @samp{configure @var{host}} and then running @code{make} builds the 35079@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty} 35080libraries, then @code{gdb} itself. The configured source files, and the 35081binaries, are left in the corresponding source directories. 35082 35083@need 750 35084@file{configure} is a Bourne-shell (@code{/bin/sh}) script; if your 35085system does not recognize this automatically when you run a different 35086shell, you may need to run @code{sh} on it explicitly: 35087 35088@smallexample 35089sh configure @var{host} 35090@end smallexample 35091 35092If you run @file{configure} from a directory that contains source 35093directories for multiple libraries or programs, such as the 35094@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, 35095@file{configure} 35096creates configuration files for every directory level underneath (unless 35097you tell it not to, with the @samp{--norecursion} option). 35098 35099You should run the @file{configure} script from the top directory in the 35100source tree, the @file{gdb-@var{version-number}} directory. If you run 35101@file{configure} from one of the subdirectories, you will configure only 35102that subdirectory. That is usually not what you want. In particular, 35103if you run the first @file{configure} from the @file{gdb} subdirectory 35104of the @file{gdb-@var{version-number}} directory, you will omit the 35105configuration of @file{bfd}, @file{readline}, and other sibling 35106directories of the @file{gdb} subdirectory. This leads to build errors 35107about missing include files such as @file{bfd/bfd.h}. 35108 35109You can install @code{@value{GDBP}} anywhere; it has no hardwired paths. 35110However, you should make sure that the shell on your path (named by 35111the @samp{SHELL} environment variable) is publicly readable. Remember 35112that @value{GDBN} uses the shell to start your program---some systems refuse to 35113let @value{GDBN} debug child processes whose programs are not readable. 35114 35115@node Separate Objdir 35116@section Compiling @value{GDBN} in Another Directory 35117 35118If you want to run @value{GDBN} versions for several host or target machines, 35119you need a different @code{gdb} compiled for each combination of 35120host and target. @file{configure} is designed to make this easy by 35121allowing you to generate each configuration in a separate subdirectory, 35122rather than in the source directory. If your @code{make} program 35123handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running 35124@code{make} in each of these directories builds the @code{gdb} 35125program specified there. 35126 35127To build @code{gdb} in a separate directory, run @file{configure} 35128with the @samp{--srcdir} option to specify where to find the source. 35129(You also need to specify a path to find @file{configure} 35130itself from your working directory. If the path to @file{configure} 35131would be the same as the argument to @samp{--srcdir}, you can leave out 35132the @samp{--srcdir} option; it is assumed.) 35133 35134For example, with version @value{GDBVN}, you can build @value{GDBN} in a 35135separate directory for a Sun 4 like this: 35136 35137@smallexample 35138@group 35139cd gdb-@value{GDBVN} 35140mkdir ../gdb-sun4 35141cd ../gdb-sun4 35142../gdb-@value{GDBVN}/configure sun4 35143make 35144@end group 35145@end smallexample 35146 35147When @file{configure} builds a configuration using a remote source 35148directory, it creates a tree for the binaries with the same structure 35149(and using the same names) as the tree under the source directory. In 35150the example, you'd find the Sun 4 library @file{libiberty.a} in the 35151directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in 35152@file{gdb-sun4/gdb}. 35153 35154Make sure that your path to the @file{configure} script has just one 35155instance of @file{gdb} in it. If your path to @file{configure} looks 35156like @file{../gdb-@value{GDBVN}/gdb/configure}, you are configuring only 35157one subdirectory of @value{GDBN}, not the whole package. This leads to 35158build errors about missing include files such as @file{bfd/bfd.h}. 35159 35160One popular reason to build several @value{GDBN} configurations in separate 35161directories is to configure @value{GDBN} for cross-compiling (where 35162@value{GDBN} runs on one machine---the @dfn{host}---while debugging 35163programs that run on another machine---the @dfn{target}). 35164You specify a cross-debugging target by 35165giving the @samp{--target=@var{target}} option to @file{configure}. 35166 35167When you run @code{make} to build a program or library, you must run 35168it in a configured directory---whatever directory you were in when you 35169called @file{configure} (or one of its subdirectories). 35170 35171The @code{Makefile} that @file{configure} generates in each source 35172directory also runs recursively. If you type @code{make} in a source 35173directory such as @file{gdb-@value{GDBVN}} (or in a separate configured 35174directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you 35175will build all the required libraries, and then build GDB. 35176 35177When you have multiple hosts or targets configured in separate 35178directories, you can run @code{make} on them in parallel (for example, 35179if they are NFS-mounted on each of the hosts); they will not interfere 35180with each other. 35181 35182@node Config Names 35183@section Specifying Names for Hosts and Targets 35184 35185The specifications used for hosts and targets in the @file{configure} 35186script are based on a three-part naming scheme, but some short predefined 35187aliases are also supported. The full naming scheme encodes three pieces 35188of information in the following pattern: 35189 35190@smallexample 35191@var{architecture}-@var{vendor}-@var{os} 35192@end smallexample 35193 35194For example, you can use the alias @code{sun4} as a @var{host} argument, 35195or as the value for @var{target} in a @code{--target=@var{target}} 35196option. The equivalent full name is @samp{sparc-sun-sunos4}. 35197 35198The @file{configure} script accompanying @value{GDBN} does not provide 35199any query facility to list all supported host and target names or 35200aliases. @file{configure} calls the Bourne shell script 35201@code{config.sub} to map abbreviations to full names; you can read the 35202script, if you wish, or you can use it to test your guesses on 35203abbreviations---for example: 35204 35205@smallexample 35206% sh config.sub i386-linux 35207i386-pc-linux-gnu 35208% sh config.sub alpha-linux 35209alpha-unknown-linux-gnu 35210% sh config.sub hp9k700 35211hppa1.1-hp-hpux 35212% sh config.sub sun4 35213sparc-sun-sunos4.1.1 35214% sh config.sub sun3 35215m68k-sun-sunos4.1.1 35216% sh config.sub i986v 35217Invalid configuration `i986v': machine `i986v' not recognized 35218@end smallexample 35219 35220@noindent 35221@code{config.sub} is also distributed in the @value{GDBN} source 35222directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}). 35223 35224@node Configure Options 35225@section @file{configure} Options 35226 35227Here is a summary of the @file{configure} options and arguments that 35228are most often useful for building @value{GDBN}. @file{configure} also has 35229several other options not listed here. @inforef{What Configure 35230Does,,configure.info}, for a full explanation of @file{configure}. 35231 35232@smallexample 35233configure @r{[}--help@r{]} 35234 @r{[}--prefix=@var{dir}@r{]} 35235 @r{[}--exec-prefix=@var{dir}@r{]} 35236 @r{[}--srcdir=@var{dirname}@r{]} 35237 @r{[}--norecursion@r{]} @r{[}--rm@r{]} 35238 @r{[}--target=@var{target}@r{]} 35239 @var{host} 35240@end smallexample 35241 35242@noindent 35243You may introduce options with a single @samp{-} rather than 35244@samp{--} if you prefer; but you may abbreviate option names if you use 35245@samp{--}. 35246 35247@table @code 35248@item --help 35249Display a quick summary of how to invoke @file{configure}. 35250 35251@item --prefix=@var{dir} 35252Configure the source to install programs and files under directory 35253@file{@var{dir}}. 35254 35255@item --exec-prefix=@var{dir} 35256Configure the source to install programs under directory 35257@file{@var{dir}}. 35258 35259@c avoid splitting the warning from the explanation: 35260@need 2000 35261@item --srcdir=@var{dirname} 35262@strong{Warning: using this option requires @sc{gnu} @code{make}, or another 35263@code{make} that implements the @code{VPATH} feature.}@* 35264Use this option to make configurations in directories separate from the 35265@value{GDBN} source directories. Among other things, you can use this to 35266build (or maintain) several configurations simultaneously, in separate 35267directories. @file{configure} writes configuration-specific files in 35268the current directory, but arranges for them to use the source in the 35269directory @var{dirname}. @file{configure} creates directories under 35270the working directory in parallel to the source directories below 35271@var{dirname}. 35272 35273@item --norecursion 35274Configure only the directory level where @file{configure} is executed; do not 35275propagate configuration to subdirectories. 35276 35277@item --target=@var{target} 35278Configure @value{GDBN} for cross-debugging programs running on the specified 35279@var{target}. Without this option, @value{GDBN} is configured to debug 35280programs that run on the same machine (@var{host}) as @value{GDBN} itself. 35281 35282There is no convenient way to generate a list of all available targets. 35283 35284@item @var{host} @dots{} 35285Configure @value{GDBN} to run on the specified @var{host}. 35286 35287There is no convenient way to generate a list of all available hosts. 35288@end table 35289 35290There are many other options available as well, but they are generally 35291needed for special purposes only. 35292 35293@node System-wide configuration 35294@section System-wide configuration and settings 35295@cindex system-wide init file 35296 35297@value{GDBN} can be configured to have a system-wide init file; 35298this file will be read and executed at startup (@pxref{Startup, , What 35299@value{GDBN} does during startup}). 35300 35301Here is the corresponding configure option: 35302 35303@table @code 35304@item --with-system-gdbinit=@var{file} 35305Specify that the default location of the system-wide init file is 35306@var{file}. 35307@end table 35308 35309If @value{GDBN} has been configured with the option @option{--prefix=$prefix}, 35310it may be subject to relocation. Two possible cases: 35311 35312@itemize @bullet 35313@item 35314If the default location of this init file contains @file{$prefix}, 35315it will be subject to relocation. Suppose that the configure options 35316are @option{--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit}; 35317if @value{GDBN} is moved from @file{$prefix} to @file{$install}, the system 35318init file is looked for as @file{$install/etc/gdbinit} instead of 35319@file{$prefix/etc/gdbinit}. 35320 35321@item 35322By contrast, if the default location does not contain the prefix, 35323it will not be relocated. E.g.@: if @value{GDBN} has been configured with 35324@option{--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit}, 35325then @value{GDBN} will always look for @file{/usr/share/gdb/gdbinit}, 35326wherever @value{GDBN} is installed. 35327@end itemize 35328 35329If the configured location of the system-wide init file (as given by the 35330@option{--with-system-gdbinit} option at configure time) is in the 35331data-directory (as specified by @option{--with-gdb-datadir} at configure 35332time) or in one of its subdirectories, then @value{GDBN} will look for the 35333system-wide init file in the directory specified by the 35334@option{--data-directory} command-line option. 35335Note that the system-wide init file is only read once, during @value{GDBN} 35336initialization. If the data-directory is changed after @value{GDBN} has 35337started with the @code{set data-directory} command, the file will not be 35338reread. 35339 35340@node Maintenance Commands 35341@appendix Maintenance Commands 35342@cindex maintenance commands 35343@cindex internal commands 35344 35345In addition to commands intended for @value{GDBN} users, @value{GDBN} 35346includes a number of commands intended for @value{GDBN} developers, 35347that are not documented elsewhere in this manual. These commands are 35348provided here for reference. (For commands that turn on debugging 35349messages, see @ref{Debugging Output}.) 35350 35351@table @code 35352@kindex maint agent 35353@kindex maint agent-eval 35354@item maint agent @r{[}-at @var{location}@r{,}@r{]} @var{expression} 35355@itemx maint agent-eval @r{[}-at @var{location}@r{,}@r{]} @var{expression} 35356Translate the given @var{expression} into remote agent bytecodes. 35357This command is useful for debugging the Agent Expression mechanism 35358(@pxref{Agent Expressions}). The @samp{agent} version produces an 35359expression useful for data collection, such as by tracepoints, while 35360@samp{maint agent-eval} produces an expression that evaluates directly 35361to a result. For instance, a collection expression for @code{globa + 35362globb} will include bytecodes to record four bytes of memory at each 35363of the addresses of @code{globa} and @code{globb}, while discarding 35364the result of the addition, while an evaluation expression will do the 35365addition and return the sum. 35366If @code{-at} is given, generate remote agent bytecode for @var{location}. 35367If not, generate remote agent bytecode for current frame PC address. 35368 35369@kindex maint agent-printf 35370@item maint agent-printf @var{format},@var{expr},... 35371Translate the given format string and list of argument expressions 35372into remote agent bytecodes and display them as a disassembled list. 35373This command is useful for debugging the agent version of dynamic 35374printf (@pxref{Dynamic Printf}. 35375 35376@kindex maint info breakpoints 35377@item @anchor{maint info breakpoints}maint info breakpoints 35378Using the same format as @samp{info breakpoints}, display both the 35379breakpoints you've set explicitly, and those @value{GDBN} is using for 35380internal purposes. Internal breakpoints are shown with negative 35381breakpoint numbers. The type column identifies what kind of breakpoint 35382is shown: 35383 35384@table @code 35385@item breakpoint 35386Normal, explicitly set breakpoint. 35387 35388@item watchpoint 35389Normal, explicitly set watchpoint. 35390 35391@item longjmp 35392Internal breakpoint, used to handle correctly stepping through 35393@code{longjmp} calls. 35394 35395@item longjmp resume 35396Internal breakpoint at the target of a @code{longjmp}. 35397 35398@item until 35399Temporary internal breakpoint used by the @value{GDBN} @code{until} command. 35400 35401@item finish 35402Temporary internal breakpoint used by the @value{GDBN} @code{finish} command. 35403 35404@item shlib events 35405Shared library events. 35406 35407@end table 35408 35409@kindex maint info bfds 35410@item maint info bfds 35411This prints information about each @code{bfd} object that is known to 35412@value{GDBN}. @xref{Top, , BFD, bfd, The Binary File Descriptor Library}. 35413 35414@kindex set displaced-stepping 35415@kindex show displaced-stepping 35416@cindex displaced stepping support 35417@cindex out-of-line single-stepping 35418@item set displaced-stepping 35419@itemx show displaced-stepping 35420Control whether or not @value{GDBN} will do @dfn{displaced stepping} 35421if the target supports it. Displaced stepping is a way to single-step 35422over breakpoints without removing them from the inferior, by executing 35423an out-of-line copy of the instruction that was originally at the 35424breakpoint location. It is also known as out-of-line single-stepping. 35425 35426@table @code 35427@item set displaced-stepping on 35428If the target architecture supports it, @value{GDBN} will use 35429displaced stepping to step over breakpoints. 35430 35431@item set displaced-stepping off 35432@value{GDBN} will not use displaced stepping to step over breakpoints, 35433even if such is supported by the target architecture. 35434 35435@cindex non-stop mode, and @samp{set displaced-stepping} 35436@item set displaced-stepping auto 35437This is the default mode. @value{GDBN} will use displaced stepping 35438only if non-stop mode is active (@pxref{Non-Stop Mode}) and the target 35439architecture supports displaced stepping. 35440@end table 35441 35442@kindex maint check-symtabs 35443@item maint check-symtabs 35444Check the consistency of psymtabs and symtabs. 35445 35446@kindex maint cplus first_component 35447@item maint cplus first_component @var{name} 35448Print the first C@t{++} class/namespace component of @var{name}. 35449 35450@kindex maint cplus namespace 35451@item maint cplus namespace 35452Print the list of possible C@t{++} namespaces. 35453 35454@kindex maint demangle 35455@item maint demangle @var{name} 35456Demangle a C@t{++} or Objective-C mangled @var{name}. 35457 35458@kindex maint deprecate 35459@kindex maint undeprecate 35460@cindex deprecated commands 35461@item maint deprecate @var{command} @r{[}@var{replacement}@r{]} 35462@itemx maint undeprecate @var{command} 35463Deprecate or undeprecate the named @var{command}. Deprecated commands 35464cause @value{GDBN} to issue a warning when you use them. The optional 35465argument @var{replacement} says which newer command should be used in 35466favor of the deprecated one; if it is given, @value{GDBN} will mention 35467the replacement as part of the warning. 35468 35469@kindex maint dump-me 35470@item maint dump-me 35471@cindex @code{SIGQUIT} signal, dump core of @value{GDBN} 35472Cause a fatal signal in the debugger and force it to dump its core. 35473This is supported only on systems which support aborting a program 35474with the @code{SIGQUIT} signal. 35475 35476@kindex maint internal-error 35477@kindex maint internal-warning 35478@item maint internal-error @r{[}@var{message-text}@r{]} 35479@itemx maint internal-warning @r{[}@var{message-text}@r{]} 35480Cause @value{GDBN} to call the internal function @code{internal_error} 35481or @code{internal_warning} and hence behave as though an internal error 35482or internal warning has been detected. In addition to reporting the 35483internal problem, these functions give the user the opportunity to 35484either quit @value{GDBN} or create a core file of the current 35485@value{GDBN} session. 35486 35487These commands take an optional parameter @var{message-text} that is 35488used as the text of the error or warning message. 35489 35490Here's an example of using @code{internal-error}: 35491 35492@smallexample 35493(@value{GDBP}) @kbd{maint internal-error testing, 1, 2} 35494@dots{}/maint.c:121: internal-error: testing, 1, 2 35495A problem internal to GDB has been detected. Further 35496debugging may prove unreliable. 35497Quit this debugging session? (y or n) @kbd{n} 35498Create a core file? (y or n) @kbd{n} 35499(@value{GDBP}) 35500@end smallexample 35501 35502@cindex @value{GDBN} internal error 35503@cindex internal errors, control of @value{GDBN} behavior 35504 35505@kindex maint set internal-error 35506@kindex maint show internal-error 35507@kindex maint set internal-warning 35508@kindex maint show internal-warning 35509@item maint set internal-error @var{action} [ask|yes|no] 35510@itemx maint show internal-error @var{action} 35511@itemx maint set internal-warning @var{action} [ask|yes|no] 35512@itemx maint show internal-warning @var{action} 35513When @value{GDBN} reports an internal problem (error or warning) it 35514gives the user the opportunity to both quit @value{GDBN} and create a 35515core file of the current @value{GDBN} session. These commands let you 35516override the default behaviour for each particular @var{action}, 35517described in the table below. 35518 35519@table @samp 35520@item quit 35521You can specify that @value{GDBN} should always (yes) or never (no) 35522quit. The default is to ask the user what to do. 35523 35524@item corefile 35525You can specify that @value{GDBN} should always (yes) or never (no) 35526create a core file. The default is to ask the user what to do. 35527@end table 35528 35529@kindex maint packet 35530@item maint packet @var{text} 35531If @value{GDBN} is talking to an inferior via the serial protocol, 35532then this command sends the string @var{text} to the inferior, and 35533displays the response packet. @value{GDBN} supplies the initial 35534@samp{$} character, the terminating @samp{#} character, and the 35535checksum. 35536 35537@kindex maint print architecture 35538@item maint print architecture @r{[}@var{file}@r{]} 35539Print the entire architecture configuration. The optional argument 35540@var{file} names the file where the output goes. 35541 35542@kindex maint print c-tdesc 35543@item maint print c-tdesc 35544Print the current target description (@pxref{Target Descriptions}) as 35545a C source file. The created source file can be used in @value{GDBN} 35546when an XML parser is not available to parse the description. 35547 35548@kindex maint print dummy-frames 35549@item maint print dummy-frames 35550Prints the contents of @value{GDBN}'s internal dummy-frame stack. 35551 35552@smallexample 35553(@value{GDBP}) @kbd{b add} 35554@dots{} 35555(@value{GDBP}) @kbd{print add(2,3)} 35556Breakpoint 2, add (a=2, b=3) at @dots{} 3555758 return (a + b); 35558The program being debugged stopped while in a function called from GDB. 35559@dots{} 35560(@value{GDBP}) @kbd{maint print dummy-frames} 355610x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6 35562 top=0x0200bdd4 id=@{stack=0x200bddc,code=0x101405c@} 35563 call_lo=0x01014000 call_hi=0x01014001 35564(@value{GDBP}) 35565@end smallexample 35566 35567Takes an optional file parameter. 35568 35569@kindex maint print registers 35570@kindex maint print raw-registers 35571@kindex maint print cooked-registers 35572@kindex maint print register-groups 35573@kindex maint print remote-registers 35574@item maint print registers @r{[}@var{file}@r{]} 35575@itemx maint print raw-registers @r{[}@var{file}@r{]} 35576@itemx maint print cooked-registers @r{[}@var{file}@r{]} 35577@itemx maint print register-groups @r{[}@var{file}@r{]} 35578@itemx maint print remote-registers @r{[}@var{file}@r{]} 35579Print @value{GDBN}'s internal register data structures. 35580 35581The command @code{maint print raw-registers} includes the contents of 35582the raw register cache; the command @code{maint print 35583cooked-registers} includes the (cooked) value of all registers, 35584including registers which aren't available on the target nor visible 35585to user; the command @code{maint print register-groups} includes the 35586groups that each register is a member of; and the command @code{maint 35587print remote-registers} includes the remote target's register numbers 35588and offsets in the `G' packets. @xref{Registers,, Registers, gdbint, 35589@value{GDBN} Internals}. 35590 35591These commands take an optional parameter, a file name to which to 35592write the information. 35593 35594@kindex maint print reggroups 35595@item maint print reggroups @r{[}@var{file}@r{]} 35596Print @value{GDBN}'s internal register group data structures. The 35597optional argument @var{file} tells to what file to write the 35598information. 35599 35600The register groups info looks like this: 35601 35602@smallexample 35603(@value{GDBP}) @kbd{maint print reggroups} 35604 Group Type 35605 general user 35606 float user 35607 all user 35608 vector user 35609 system user 35610 save internal 35611 restore internal 35612@end smallexample 35613 35614@kindex flushregs 35615@item flushregs 35616This command forces @value{GDBN} to flush its internal register cache. 35617 35618@kindex maint print objfiles 35619@cindex info for known object files 35620@item maint print objfiles 35621Print a dump of all known object files. For each object file, this 35622command prints its name, address in memory, and all of its psymtabs 35623and symtabs. 35624 35625@kindex maint print section-scripts 35626@cindex info for known .debug_gdb_scripts-loaded scripts 35627@item maint print section-scripts [@var{regexp}] 35628Print a dump of scripts specified in the @code{.debug_gdb_section} section. 35629If @var{regexp} is specified, only print scripts loaded by object files 35630matching @var{regexp}. 35631For each script, this command prints its name as specified in the objfile, 35632and the full path if known. 35633@xref{dotdebug_gdb_scripts section}. 35634 35635@kindex maint print statistics 35636@cindex bcache statistics 35637@item maint print statistics 35638This command prints, for each object file in the program, various data 35639about that object file followed by the byte cache (@dfn{bcache}) 35640statistics for the object file. The objfile data includes the number 35641of minimal, partial, full, and stabs symbols, the number of types 35642defined by the objfile, the number of as yet unexpanded psym tables, 35643the number of line tables and string tables, and the amount of memory 35644used by the various tables. The bcache statistics include the counts, 35645sizes, and counts of duplicates of all and unique objects, max, 35646average, and median entry size, total memory used and its overhead and 35647savings, and various measures of the hash table size and chain 35648lengths. 35649 35650@kindex maint print target-stack 35651@cindex target stack description 35652@item maint print target-stack 35653A @dfn{target} is an interface between the debugger and a particular 35654kind of file or process. Targets can be stacked in @dfn{strata}, 35655so that more than one target can potentially respond to a request. 35656In particular, memory accesses will walk down the stack of targets 35657until they find a target that is interested in handling that particular 35658address. 35659 35660This command prints a short description of each layer that was pushed on 35661the @dfn{target stack}, starting from the top layer down to the bottom one. 35662 35663@kindex maint print type 35664@cindex type chain of a data type 35665@item maint print type @var{expr} 35666Print the type chain for a type specified by @var{expr}. The argument 35667can be either a type name or a symbol. If it is a symbol, the type of 35668that symbol is described. The type chain produced by this command is 35669a recursive definition of the data type as stored in @value{GDBN}'s 35670data structures, including its flags and contained types. 35671 35672@kindex maint set dwarf2 always-disassemble 35673@kindex maint show dwarf2 always-disassemble 35674@item maint set dwarf2 always-disassemble 35675@item maint show dwarf2 always-disassemble 35676Control the behavior of @code{info address} when using DWARF debugging 35677information. 35678 35679The default is @code{off}, which means that @value{GDBN} should try to 35680describe a variable's location in an easily readable format. When 35681@code{on}, @value{GDBN} will instead display the DWARF location 35682expression in an assembly-like format. Note that some locations are 35683too complex for @value{GDBN} to describe simply; in this case you will 35684always see the disassembly form. 35685 35686Here is an example of the resulting disassembly: 35687 35688@smallexample 35689(gdb) info addr argc 35690Symbol "argc" is a complex DWARF expression: 35691 1: DW_OP_fbreg 0 35692@end smallexample 35693 35694For more information on these expressions, see 35695@uref{http://www.dwarfstd.org/, the DWARF standard}. 35696 35697@kindex maint set dwarf2 max-cache-age 35698@kindex maint show dwarf2 max-cache-age 35699@item maint set dwarf2 max-cache-age 35700@itemx maint show dwarf2 max-cache-age 35701Control the DWARF 2 compilation unit cache. 35702 35703@cindex DWARF 2 compilation units cache 35704In object files with inter-compilation-unit references, such as those 35705produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 2 35706reader needs to frequently refer to previously read compilation units. 35707This setting controls how long a compilation unit will remain in the 35708cache if it is not referenced. A higher limit means that cached 35709compilation units will be stored in memory longer, and more total 35710memory will be used. Setting it to zero disables caching, which will 35711slow down @value{GDBN} startup, but reduce memory consumption. 35712 35713@kindex maint set profile 35714@kindex maint show profile 35715@cindex profiling GDB 35716@item maint set profile 35717@itemx maint show profile 35718Control profiling of @value{GDBN}. 35719 35720Profiling will be disabled until you use the @samp{maint set profile} 35721command to enable it. When you enable profiling, the system will begin 35722collecting timing and execution count data; when you disable profiling or 35723exit @value{GDBN}, the results will be written to a log file. Remember that 35724if you use profiling, @value{GDBN} will overwrite the profiling log file 35725(often called @file{gmon.out}). If you have a record of important profiling 35726data in a @file{gmon.out} file, be sure to move it to a safe location. 35727 35728Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be 35729compiled with the @samp{-pg} compiler option. 35730 35731@kindex maint set show-debug-regs 35732@kindex maint show show-debug-regs 35733@cindex hardware debug registers 35734@item maint set show-debug-regs 35735@itemx maint show show-debug-regs 35736Control whether to show variables that mirror the hardware debug 35737registers. Use @code{ON} to enable, @code{OFF} to disable. If 35738enabled, the debug registers values are shown when @value{GDBN} inserts or 35739removes a hardware breakpoint or watchpoint, and when the inferior 35740triggers a hardware-assisted breakpoint or watchpoint. 35741 35742@kindex maint set show-all-tib 35743@kindex maint show show-all-tib 35744@item maint set show-all-tib 35745@itemx maint show show-all-tib 35746Control whether to show all non zero areas within a 1k block starting 35747at thread local base, when using the @samp{info w32 thread-information-block} 35748command. 35749 35750@kindex maint space 35751@cindex memory used by commands 35752@item maint space 35753Control whether to display memory usage for each command. If set to a 35754nonzero value, @value{GDBN} will display how much memory each command 35755took, following the command's own output. This can also be requested 35756by invoking @value{GDBN} with the @option{--statistics} command-line 35757switch (@pxref{Mode Options}). 35758 35759@kindex maint time 35760@cindex time of command execution 35761@item maint time 35762Control whether to display the execution time of @value{GDBN} for each command. 35763If set to a nonzero value, @value{GDBN} will display how much time it 35764took to execute each command, following the command's own output. 35765Both CPU time and wallclock time are printed. 35766Printing both is useful when trying to determine whether the cost is 35767CPU or, e.g., disk/network, latency. 35768Note that the CPU time printed is for @value{GDBN} only, it does not include 35769the execution time of the inferior because there's no mechanism currently 35770to compute how much time was spent by @value{GDBN} and how much time was 35771spent by the program been debugged. 35772This can also be requested by invoking @value{GDBN} with the 35773@option{--statistics} command-line switch (@pxref{Mode Options}). 35774 35775@kindex maint translate-address 35776@item maint translate-address @r{[}@var{section}@r{]} @var{addr} 35777Find the symbol stored at the location specified by the address 35778@var{addr} and an optional section name @var{section}. If found, 35779@value{GDBN} prints the name of the closest symbol and an offset from 35780the symbol's location to the specified address. This is similar to 35781the @code{info address} command (@pxref{Symbols}), except that this 35782command also allows to find symbols in other sections. 35783 35784If section was not specified, the section in which the symbol was found 35785is also printed. For dynamically linked executables, the name of 35786executable or shared library containing the symbol is printed as well. 35787 35788@end table 35789 35790The following command is useful for non-interactive invocations of 35791@value{GDBN}, such as in the test suite. 35792 35793@table @code 35794@item set watchdog @var{nsec} 35795@kindex set watchdog 35796@cindex watchdog timer 35797@cindex timeout for commands 35798Set the maximum number of seconds @value{GDBN} will wait for the 35799target operation to finish. If this time expires, @value{GDBN} 35800reports and error and the command is aborted. 35801 35802@item show watchdog 35803Show the current setting of the target wait timeout. 35804@end table 35805 35806@node Remote Protocol 35807@appendix @value{GDBN} Remote Serial Protocol 35808 35809@menu 35810* Overview:: 35811* Packets:: 35812* Stop Reply Packets:: 35813* General Query Packets:: 35814* Architecture-Specific Protocol Details:: 35815* Tracepoint Packets:: 35816* Host I/O Packets:: 35817* Interrupts:: 35818* Notification Packets:: 35819* Remote Non-Stop:: 35820* Packet Acknowledgment:: 35821* Examples:: 35822* File-I/O Remote Protocol Extension:: 35823* Library List Format:: 35824* Library List Format for SVR4 Targets:: 35825* Memory Map Format:: 35826* Thread List Format:: 35827* Traceframe Info Format:: 35828* Branch Trace Format:: 35829@end menu 35830 35831@node Overview 35832@section Overview 35833 35834There may be occasions when you need to know something about the 35835protocol---for example, if there is only one serial port to your target 35836machine, you might want your program to do something special if it 35837recognizes a packet meant for @value{GDBN}. 35838 35839In the examples below, @samp{->} and @samp{<-} are used to indicate 35840transmitted and received data, respectively. 35841 35842@cindex protocol, @value{GDBN} remote serial 35843@cindex serial protocol, @value{GDBN} remote 35844@cindex remote serial protocol 35845All @value{GDBN} commands and responses (other than acknowledgments 35846and notifications, see @ref{Notification Packets}) are sent as a 35847@var{packet}. A @var{packet} is introduced with the character 35848@samp{$}, the actual @var{packet-data}, and the terminating character 35849@samp{#} followed by a two-digit @var{checksum}: 35850 35851@smallexample 35852@code{$}@var{packet-data}@code{#}@var{checksum} 35853@end smallexample 35854@noindent 35855 35856@cindex checksum, for @value{GDBN} remote 35857@noindent 35858The two-digit @var{checksum} is computed as the modulo 256 sum of all 35859characters between the leading @samp{$} and the trailing @samp{#} (an 35860eight bit unsigned checksum). 35861 35862Implementors should note that prior to @value{GDBN} 5.0 the protocol 35863specification also included an optional two-digit @var{sequence-id}: 35864 35865@smallexample 35866@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} 35867@end smallexample 35868 35869@cindex sequence-id, for @value{GDBN} remote 35870@noindent 35871That @var{sequence-id} was appended to the acknowledgment. @value{GDBN} 35872has never output @var{sequence-id}s. Stubs that handle packets added 35873since @value{GDBN} 5.0 must not accept @var{sequence-id}. 35874 35875When either the host or the target machine receives a packet, the first 35876response expected is an acknowledgment: either @samp{+} (to indicate 35877the package was received correctly) or @samp{-} (to request 35878retransmission): 35879 35880@smallexample 35881-> @code{$}@var{packet-data}@code{#}@var{checksum} 35882<- @code{+} 35883@end smallexample 35884@noindent 35885 35886The @samp{+}/@samp{-} acknowledgments can be disabled 35887once a connection is established. 35888@xref{Packet Acknowledgment}, for details. 35889 35890The host (@value{GDBN}) sends @var{command}s, and the target (the 35891debugging stub incorporated in your program) sends a @var{response}. In 35892the case of step and continue @var{command}s, the response is only sent 35893when the operation has completed, and the target has again stopped all 35894threads in all attached processes. This is the default all-stop mode 35895behavior, but the remote protocol also supports @value{GDBN}'s non-stop 35896execution mode; see @ref{Remote Non-Stop}, for details. 35897 35898@var{packet-data} consists of a sequence of characters with the 35899exception of @samp{#} and @samp{$} (see @samp{X} packet for additional 35900exceptions). 35901 35902@cindex remote protocol, field separator 35903Fields within the packet should be separated using @samp{,} @samp{;} or 35904@samp{:}. Except where otherwise noted all numbers are represented in 35905@sc{hex} with leading zeros suppressed. 35906 35907Implementors should note that prior to @value{GDBN} 5.0, the character 35908@samp{:} could not appear as the third character in a packet (as it 35909would potentially conflict with the @var{sequence-id}). 35910 35911@cindex remote protocol, binary data 35912@anchor{Binary Data} 35913Binary data in most packets is encoded either as two hexadecimal 35914digits per byte of binary data. This allowed the traditional remote 35915protocol to work over connections which were only seven-bit clean. 35916Some packets designed more recently assume an eight-bit clean 35917connection, and use a more efficient encoding to send and receive 35918binary data. 35919 35920The binary data representation uses @code{7d} (@sc{ascii} @samp{@}}) 35921as an escape character. Any escaped byte is transmitted as the escape 35922character followed by the original character XORed with @code{0x20}. 35923For example, the byte @code{0x7d} would be transmitted as the two 35924bytes @code{0x7d 0x5d}. The bytes @code{0x23} (@sc{ascii} @samp{#}), 35925@code{0x24} (@sc{ascii} @samp{$}), and @code{0x7d} (@sc{ascii} 35926@samp{@}}) must always be escaped. Responses sent by the stub 35927must also escape @code{0x2a} (@sc{ascii} @samp{*}), so that it 35928is not interpreted as the start of a run-length encoded sequence 35929(described next). 35930 35931Response @var{data} can be run-length encoded to save space. 35932Run-length encoding replaces runs of identical characters with one 35933instance of the repeated character, followed by a @samp{*} and a 35934repeat count. The repeat count is itself sent encoded, to avoid 35935binary characters in @var{data}: a value of @var{n} is sent as 35936@code{@var{n}+29}. For a repeat count greater or equal to 3, this 35937produces a printable @sc{ascii} character, e.g.@: a space (@sc{ascii} 35938code 32) for a repeat count of 3. (This is because run-length 35939encoding starts to win for counts 3 or more.) Thus, for example, 35940@samp{0* } is a run-length encoding of ``0000'': the space character 35941after @samp{*} means repeat the leading @code{0} @w{@code{32 - 29 = 359423}} more times. 35943 35944The printable characters @samp{#} and @samp{$} or with a numeric value 35945greater than 126 must not be used. Runs of six repeats (@samp{#}) or 35946seven repeats (@samp{$}) can be expanded using a repeat count of only 35947five (@samp{"}). For example, @samp{00000000} can be encoded as 35948@samp{0*"00}. 35949 35950The error response returned for some packets includes a two character 35951error number. That number is not well defined. 35952 35953@cindex empty response, for unsupported packets 35954For any @var{command} not supported by the stub, an empty response 35955(@samp{$#00}) should be returned. That way it is possible to extend the 35956protocol. A newer @value{GDBN} can tell if a packet is supported based 35957on that response. 35958 35959At a minimum, a stub is required to support the @samp{g} and @samp{G} 35960commands for register access, and the @samp{m} and @samp{M} commands 35961for memory access. Stubs that only control single-threaded targets 35962can implement run control with the @samp{c} (continue), and @samp{s} 35963(step) commands. Stubs that support multi-threading targets should 35964support the @samp{vCont} command. All other commands are optional. 35965 35966@node Packets 35967@section Packets 35968 35969The following table provides a complete list of all currently defined 35970@var{command}s and their corresponding response @var{data}. 35971@xref{File-I/O Remote Protocol Extension}, for details about the File 35972I/O extension of the remote protocol. 35973 35974Each packet's description has a template showing the packet's overall 35975syntax, followed by an explanation of the packet's meaning. We 35976include spaces in some of the templates for clarity; these are not 35977part of the packet's syntax. No @value{GDBN} packet uses spaces to 35978separate its components. For example, a template like @samp{foo 35979@var{bar} @var{baz}} describes a packet beginning with the three ASCII 35980bytes @samp{foo}, followed by a @var{bar}, followed directly by a 35981@var{baz}. @value{GDBN} does not transmit a space character between the 35982@samp{foo} and the @var{bar}, or between the @var{bar} and the 35983@var{baz}. 35984 35985@cindex @var{thread-id}, in remote protocol 35986@anchor{thread-id syntax} 35987Several packets and replies include a @var{thread-id} field to identify 35988a thread. Normally these are positive numbers with a target-specific 35989interpretation, formatted as big-endian hex strings. A @var{thread-id} 35990can also be a literal @samp{-1} to indicate all threads, or @samp{0} to 35991pick any thread. 35992 35993In addition, the remote protocol supports a multiprocess feature in 35994which the @var{thread-id} syntax is extended to optionally include both 35995process and thread ID fields, as @samp{p@var{pid}.@var{tid}}. 35996The @var{pid} (process) and @var{tid} (thread) components each have the 35997format described above: a positive number with target-specific 35998interpretation formatted as a big-endian hex string, literal @samp{-1} 35999to indicate all processes or threads (respectively), or @samp{0} to 36000indicate an arbitrary process or thread. Specifying just a process, as 36001@samp{p@var{pid}}, is equivalent to @samp{p@var{pid}.-1}. It is an 36002error to specify all processes but a specific thread, such as 36003@samp{p-1.@var{tid}}. Note that the @samp{p} prefix is @emph{not} used 36004for those packets and replies explicitly documented to include a process 36005ID, rather than a @var{thread-id}. 36006 36007The multiprocess @var{thread-id} syntax extensions are only used if both 36008@value{GDBN} and the stub report support for the @samp{multiprocess} 36009feature using @samp{qSupported}. @xref{multiprocess extensions}, for 36010more information. 36011 36012Note that all packet forms beginning with an upper- or lower-case 36013letter, other than those described here, are reserved for future use. 36014 36015Here are the packet descriptions. 36016 36017@table @samp 36018 36019@item ! 36020@cindex @samp{!} packet 36021@anchor{extended mode} 36022Enable extended mode. In extended mode, the remote server is made 36023persistent. The @samp{R} packet is used to restart the program being 36024debugged. 36025 36026Reply: 36027@table @samp 36028@item OK 36029The remote target both supports and has enabled extended mode. 36030@end table 36031 36032@item ? 36033@cindex @samp{?} packet 36034Indicate the reason the target halted. The reply is the same as for 36035step and continue. This packet has a special interpretation when the 36036target is in non-stop mode; see @ref{Remote Non-Stop}. 36037 36038Reply: 36039@xref{Stop Reply Packets}, for the reply specifications. 36040 36041@item A @var{arglen},@var{argnum},@var{arg},@dots{} 36042@cindex @samp{A} packet 36043Initialized @code{argv[]} array passed into program. @var{arglen} 36044specifies the number of bytes in the hex encoded byte stream 36045@var{arg}. See @code{gdbserver} for more details. 36046 36047Reply: 36048@table @samp 36049@item OK 36050The arguments were set. 36051@item E @var{NN} 36052An error occurred. 36053@end table 36054 36055@item b @var{baud} 36056@cindex @samp{b} packet 36057(Don't use this packet; its behavior is not well-defined.) 36058Change the serial line speed to @var{baud}. 36059 36060JTC: @emph{When does the transport layer state change? When it's 36061received, or after the ACK is transmitted. In either case, there are 36062problems if the command or the acknowledgment packet is dropped.} 36063 36064Stan: @emph{If people really wanted to add something like this, and get 36065it working for the first time, they ought to modify ser-unix.c to send 36066some kind of out-of-band message to a specially-setup stub and have the 36067switch happen "in between" packets, so that from remote protocol's point 36068of view, nothing actually happened.} 36069 36070@item B @var{addr},@var{mode} 36071@cindex @samp{B} packet 36072Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a 36073breakpoint at @var{addr}. 36074 36075Don't use this packet. Use the @samp{Z} and @samp{z} packets instead 36076(@pxref{insert breakpoint or watchpoint packet}). 36077 36078@cindex @samp{bc} packet 36079@anchor{bc} 36080@item bc 36081Backward continue. Execute the target system in reverse. No parameter. 36082@xref{Reverse Execution}, for more information. 36083 36084Reply: 36085@xref{Stop Reply Packets}, for the reply specifications. 36086 36087@cindex @samp{bs} packet 36088@anchor{bs} 36089@item bs 36090Backward single step. Execute one instruction in reverse. No parameter. 36091@xref{Reverse Execution}, for more information. 36092 36093Reply: 36094@xref{Stop Reply Packets}, for the reply specifications. 36095 36096@item c @r{[}@var{addr}@r{]} 36097@cindex @samp{c} packet 36098Continue. @var{addr} is address to resume. If @var{addr} is omitted, 36099resume at current address. 36100 36101This packet is deprecated for multi-threading support. @xref{vCont 36102packet}. 36103 36104Reply: 36105@xref{Stop Reply Packets}, for the reply specifications. 36106 36107@item C @var{sig}@r{[};@var{addr}@r{]} 36108@cindex @samp{C} packet 36109Continue with signal @var{sig} (hex signal number). If 36110@samp{;@var{addr}} is omitted, resume at same address. 36111 36112This packet is deprecated for multi-threading support. @xref{vCont 36113packet}. 36114 36115Reply: 36116@xref{Stop Reply Packets}, for the reply specifications. 36117 36118@item d 36119@cindex @samp{d} packet 36120Toggle debug flag. 36121 36122Don't use this packet; instead, define a general set packet 36123(@pxref{General Query Packets}). 36124 36125@item D 36126@itemx D;@var{pid} 36127@cindex @samp{D} packet 36128The first form of the packet is used to detach @value{GDBN} from the 36129remote system. It is sent to the remote target 36130before @value{GDBN} disconnects via the @code{detach} command. 36131 36132The second form, including a process ID, is used when multiprocess 36133protocol extensions are enabled (@pxref{multiprocess extensions}), to 36134detach only a specific process. The @var{pid} is specified as a 36135big-endian hex string. 36136 36137Reply: 36138@table @samp 36139@item OK 36140for success 36141@item E @var{NN} 36142for an error 36143@end table 36144 36145@item F @var{RC},@var{EE},@var{CF};@var{XX} 36146@cindex @samp{F} packet 36147A reply from @value{GDBN} to an @samp{F} packet sent by the target. 36148This is part of the File-I/O protocol extension. @xref{File-I/O 36149Remote Protocol Extension}, for the specification. 36150 36151@item g 36152@anchor{read registers packet} 36153@cindex @samp{g} packet 36154Read general registers. 36155 36156Reply: 36157@table @samp 36158@item @var{XX@dots{}} 36159Each byte of register data is described by two hex digits. The bytes 36160with the register are transmitted in target byte order. The size of 36161each register and their position within the @samp{g} packet are 36162determined by the @value{GDBN} internal gdbarch functions 36163@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}. The 36164specification of several standard @samp{g} packets is specified below. 36165 36166When reading registers from a trace frame (@pxref{Analyze Collected 36167Data,,Using the Collected Data}), the stub may also return a string of 36168literal @samp{x}'s in place of the register data digits, to indicate 36169that the corresponding register has not been collected, thus its value 36170is unavailable. For example, for an architecture with 4 registers of 361714 bytes each, the following reply indicates to @value{GDBN} that 36172registers 0 and 2 have not been collected, while registers 1 and 3 36173have been collected, and both have zero value: 36174 36175@smallexample 36176-> @code{g} 36177<- @code{xxxxxxxx00000000xxxxxxxx00000000} 36178@end smallexample 36179 36180@item E @var{NN} 36181for an error. 36182@end table 36183 36184@item G @var{XX@dots{}} 36185@cindex @samp{G} packet 36186Write general registers. @xref{read registers packet}, for a 36187description of the @var{XX@dots{}} data. 36188 36189Reply: 36190@table @samp 36191@item OK 36192for success 36193@item E @var{NN} 36194for an error 36195@end table 36196 36197@item H @var{op} @var{thread-id} 36198@cindex @samp{H} packet 36199Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g}, 36200@samp{G}, et.al.). @var{op} depends on the operation to be performed: 36201it should be @samp{c} for step and continue operations (note that this 36202is deprecated, supporting the @samp{vCont} command is a better 36203option), @samp{g} for other operations. The thread designator 36204@var{thread-id} has the format and interpretation described in 36205@ref{thread-id syntax}. 36206 36207Reply: 36208@table @samp 36209@item OK 36210for success 36211@item E @var{NN} 36212for an error 36213@end table 36214 36215@c FIXME: JTC: 36216@c 'H': How restrictive (or permissive) is the thread model. If a 36217@c thread is selected and stopped, are other threads allowed 36218@c to continue to execute? As I mentioned above, I think the 36219@c semantics of each command when a thread is selected must be 36220@c described. For example: 36221@c 36222@c 'g': If the stub supports threads and a specific thread is 36223@c selected, returns the register block from that thread; 36224@c otherwise returns current registers. 36225@c 36226@c 'G' If the stub supports threads and a specific thread is 36227@c selected, sets the registers of the register block of 36228@c that thread; otherwise sets current registers. 36229 36230@item i @r{[}@var{addr}@r{[},@var{nnn}@r{]]} 36231@anchor{cycle step packet} 36232@cindex @samp{i} packet 36233Step the remote target by a single clock cycle. If @samp{,@var{nnn}} is 36234present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle 36235step starting at that address. 36236 36237@item I 36238@cindex @samp{I} packet 36239Signal, then cycle step. @xref{step with signal packet}. @xref{cycle 36240step packet}. 36241 36242@item k 36243@cindex @samp{k} packet 36244Kill request. 36245 36246FIXME: @emph{There is no description of how to operate when a specific 36247thread context has been selected (i.e.@: does 'k' kill only that 36248thread?)}. 36249 36250@item m @var{addr},@var{length} 36251@cindex @samp{m} packet 36252Read @var{length} bytes of memory starting at address @var{addr}. 36253Note that @var{addr} may not be aligned to any particular boundary. 36254 36255The stub need not use any particular size or alignment when gathering 36256data from memory for the response; even if @var{addr} is word-aligned 36257and @var{length} is a multiple of the word size, the stub is free to 36258use byte accesses, or not. For this reason, this packet may not be 36259suitable for accessing memory-mapped I/O devices. 36260@cindex alignment of remote memory accesses 36261@cindex size of remote memory accesses 36262@cindex memory, alignment and size of remote accesses 36263 36264Reply: 36265@table @samp 36266@item @var{XX@dots{}} 36267Memory contents; each byte is transmitted as a two-digit hexadecimal 36268number. The reply may contain fewer bytes than requested if the 36269server was able to read only part of the region of memory. 36270@item E @var{NN} 36271@var{NN} is errno 36272@end table 36273 36274@item M @var{addr},@var{length}:@var{XX@dots{}} 36275@cindex @samp{M} packet 36276Write @var{length} bytes of memory starting at address @var{addr}. 36277@var{XX@dots{}} is the data; each byte is transmitted as a two-digit 36278hexadecimal number. 36279 36280Reply: 36281@table @samp 36282@item OK 36283for success 36284@item E @var{NN} 36285for an error (this includes the case where only part of the data was 36286written). 36287@end table 36288 36289@item p @var{n} 36290@cindex @samp{p} packet 36291Read the value of register @var{n}; @var{n} is in hex. 36292@xref{read registers packet}, for a description of how the returned 36293register value is encoded. 36294 36295Reply: 36296@table @samp 36297@item @var{XX@dots{}} 36298the register's value 36299@item E @var{NN} 36300for an error 36301@item @w{} 36302Indicating an unrecognized @var{query}. 36303@end table 36304 36305@item P @var{n@dots{}}=@var{r@dots{}} 36306@anchor{write register packet} 36307@cindex @samp{P} packet 36308Write register @var{n@dots{}} with value @var{r@dots{}}. The register 36309number @var{n} is in hexadecimal, and @var{r@dots{}} contains two hex 36310digits for each byte in the register (target byte order). 36311 36312Reply: 36313@table @samp 36314@item OK 36315for success 36316@item E @var{NN} 36317for an error 36318@end table 36319 36320@item q @var{name} @var{params}@dots{} 36321@itemx Q @var{name} @var{params}@dots{} 36322@cindex @samp{q} packet 36323@cindex @samp{Q} packet 36324General query (@samp{q}) and set (@samp{Q}). These packets are 36325described fully in @ref{General Query Packets}. 36326 36327@item r 36328@cindex @samp{r} packet 36329Reset the entire system. 36330 36331Don't use this packet; use the @samp{R} packet instead. 36332 36333@item R @var{XX} 36334@cindex @samp{R} packet 36335Restart the program being debugged. @var{XX}, while needed, is ignored. 36336This packet is only available in extended mode (@pxref{extended mode}). 36337 36338The @samp{R} packet has no reply. 36339 36340@item s @r{[}@var{addr}@r{]} 36341@cindex @samp{s} packet 36342Single step. @var{addr} is the address at which to resume. If 36343@var{addr} is omitted, resume at same address. 36344 36345This packet is deprecated for multi-threading support. @xref{vCont 36346packet}. 36347 36348Reply: 36349@xref{Stop Reply Packets}, for the reply specifications. 36350 36351@item S @var{sig}@r{[};@var{addr}@r{]} 36352@anchor{step with signal packet} 36353@cindex @samp{S} packet 36354Step with signal. This is analogous to the @samp{C} packet, but 36355requests a single-step, rather than a normal resumption of execution. 36356 36357This packet is deprecated for multi-threading support. @xref{vCont 36358packet}. 36359 36360Reply: 36361@xref{Stop Reply Packets}, for the reply specifications. 36362 36363@item t @var{addr}:@var{PP},@var{MM} 36364@cindex @samp{t} packet 36365Search backwards starting at address @var{addr} for a match with pattern 36366@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes. 36367@var{addr} must be at least 3 digits. 36368 36369@item T @var{thread-id} 36370@cindex @samp{T} packet 36371Find out if the thread @var{thread-id} is alive. @xref{thread-id syntax}. 36372 36373Reply: 36374@table @samp 36375@item OK 36376thread is still alive 36377@item E @var{NN} 36378thread is dead 36379@end table 36380 36381@item v 36382Packets starting with @samp{v} are identified by a multi-letter name, 36383up to the first @samp{;} or @samp{?} (or the end of the packet). 36384 36385@item vAttach;@var{pid} 36386@cindex @samp{vAttach} packet 36387Attach to a new process with the specified process ID @var{pid}. 36388The process ID is a 36389hexadecimal integer identifying the process. In all-stop mode, all 36390threads in the attached process are stopped; in non-stop mode, it may be 36391attached without being stopped if that is supported by the target. 36392 36393@c In non-stop mode, on a successful vAttach, the stub should set the 36394@c current thread to a thread of the newly-attached process. After 36395@c attaching, GDB queries for the attached process's thread ID with qC. 36396@c Also note that, from a user perspective, whether or not the 36397@c target is stopped on attach in non-stop mode depends on whether you 36398@c use the foreground or background version of the attach command, not 36399@c on what vAttach does; GDB does the right thing with respect to either 36400@c stopping or restarting threads. 36401 36402This packet is only available in extended mode (@pxref{extended mode}). 36403 36404Reply: 36405@table @samp 36406@item E @var{nn} 36407for an error 36408@item @r{Any stop packet} 36409for success in all-stop mode (@pxref{Stop Reply Packets}) 36410@item OK 36411for success in non-stop mode (@pxref{Remote Non-Stop}) 36412@end table 36413 36414@item vCont@r{[};@var{action}@r{[}:@var{thread-id}@r{]]}@dots{} 36415@cindex @samp{vCont} packet 36416@anchor{vCont packet} 36417Resume the inferior, specifying different actions for each thread. 36418If an action is specified with no @var{thread-id}, then it is applied to any 36419threads that don't have a specific action specified; if no default action is 36420specified then other threads should remain stopped in all-stop mode and 36421in their current state in non-stop mode. 36422Specifying multiple 36423default actions is an error; specifying no actions is also an error. 36424Thread IDs are specified using the syntax described in @ref{thread-id syntax}. 36425 36426Currently supported actions are: 36427 36428@table @samp 36429@item c 36430Continue. 36431@item C @var{sig} 36432Continue with signal @var{sig}. The signal @var{sig} should be two hex digits. 36433@item s 36434Step. 36435@item S @var{sig} 36436Step with signal @var{sig}. The signal @var{sig} should be two hex digits. 36437@item t 36438Stop. 36439@end table 36440 36441The optional argument @var{addr} normally associated with the 36442@samp{c}, @samp{C}, @samp{s}, and @samp{S} packets is 36443not supported in @samp{vCont}. 36444 36445The @samp{t} action is only relevant in non-stop mode 36446(@pxref{Remote Non-Stop}) and may be ignored by the stub otherwise. 36447A stop reply should be generated for any affected thread not already stopped. 36448When a thread is stopped by means of a @samp{t} action, 36449the corresponding stop reply should indicate that the thread has stopped with 36450signal @samp{0}, regardless of whether the target uses some other signal 36451as an implementation detail. 36452 36453The stub must support @samp{vCont} if it reports support for 36454multiprocess extensions (@pxref{multiprocess extensions}). Note that in 36455this case @samp{vCont} actions can be specified to apply to all threads 36456in a process by using the @samp{p@var{pid}.-1} form of the 36457@var{thread-id}. 36458 36459Reply: 36460@xref{Stop Reply Packets}, for the reply specifications. 36461 36462@item vCont? 36463@cindex @samp{vCont?} packet 36464Request a list of actions supported by the @samp{vCont} packet. 36465 36466Reply: 36467@table @samp 36468@item vCont@r{[};@var{action}@dots{}@r{]} 36469The @samp{vCont} packet is supported. Each @var{action} is a supported 36470command in the @samp{vCont} packet. 36471@item @w{} 36472The @samp{vCont} packet is not supported. 36473@end table 36474 36475@item vFile:@var{operation}:@var{parameter}@dots{} 36476@cindex @samp{vFile} packet 36477Perform a file operation on the target system. For details, 36478see @ref{Host I/O Packets}. 36479 36480@item vFlashErase:@var{addr},@var{length} 36481@cindex @samp{vFlashErase} packet 36482Direct the stub to erase @var{length} bytes of flash starting at 36483@var{addr}. The region may enclose any number of flash blocks, but 36484its start and end must fall on block boundaries, as indicated by the 36485flash block size appearing in the memory map (@pxref{Memory Map 36486Format}). @value{GDBN} groups flash memory programming operations 36487together, and sends a @samp{vFlashDone} request after each group; the 36488stub is allowed to delay erase operation until the @samp{vFlashDone} 36489packet is received. 36490 36491Reply: 36492@table @samp 36493@item OK 36494for success 36495@item E @var{NN} 36496for an error 36497@end table 36498 36499@item vFlashWrite:@var{addr}:@var{XX@dots{}} 36500@cindex @samp{vFlashWrite} packet 36501Direct the stub to write data to flash address @var{addr}. The data 36502is passed in binary form using the same encoding as for the @samp{X} 36503packet (@pxref{Binary Data}). The memory ranges specified by 36504@samp{vFlashWrite} packets preceding a @samp{vFlashDone} packet must 36505not overlap, and must appear in order of increasing addresses 36506(although @samp{vFlashErase} packets for higher addresses may already 36507have been received; the ordering is guaranteed only between 36508@samp{vFlashWrite} packets). If a packet writes to an address that was 36509neither erased by a preceding @samp{vFlashErase} packet nor by some other 36510target-specific method, the results are unpredictable. 36511 36512 36513Reply: 36514@table @samp 36515@item OK 36516for success 36517@item E.memtype 36518for vFlashWrite addressing non-flash memory 36519@item E @var{NN} 36520for an error 36521@end table 36522 36523@item vFlashDone 36524@cindex @samp{vFlashDone} packet 36525Indicate to the stub that flash programming operation is finished. 36526The stub is permitted to delay or batch the effects of a group of 36527@samp{vFlashErase} and @samp{vFlashWrite} packets until a 36528@samp{vFlashDone} packet is received. The contents of the affected 36529regions of flash memory are unpredictable until the @samp{vFlashDone} 36530request is completed. 36531 36532@item vKill;@var{pid} 36533@cindex @samp{vKill} packet 36534Kill the process with the specified process ID. @var{pid} is a 36535hexadecimal integer identifying the process. This packet is used in 36536preference to @samp{k} when multiprocess protocol extensions are 36537supported; see @ref{multiprocess extensions}. 36538 36539Reply: 36540@table @samp 36541@item E @var{nn} 36542for an error 36543@item OK 36544for success 36545@end table 36546 36547@item vRun;@var{filename}@r{[};@var{argument}@r{]}@dots{} 36548@cindex @samp{vRun} packet 36549Run the program @var{filename}, passing it each @var{argument} on its 36550command line. The file and arguments are hex-encoded strings. If 36551@var{filename} is an empty string, the stub may use a default program 36552(e.g.@: the last program run). The program is created in the stopped 36553state. 36554 36555@c FIXME: What about non-stop mode? 36556 36557This packet is only available in extended mode (@pxref{extended mode}). 36558 36559Reply: 36560@table @samp 36561@item E @var{nn} 36562for an error 36563@item @r{Any stop packet} 36564for success (@pxref{Stop Reply Packets}) 36565@end table 36566 36567@item vStopped 36568@cindex @samp{vStopped} packet 36569@xref{Notification Packets}. 36570 36571@item X @var{addr},@var{length}:@var{XX@dots{}} 36572@anchor{X packet} 36573@cindex @samp{X} packet 36574Write data to memory, where the data is transmitted in binary. 36575@var{addr} is address, @var{length} is number of bytes, 36576@samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}). 36577 36578Reply: 36579@table @samp 36580@item OK 36581for success 36582@item E @var{NN} 36583for an error 36584@end table 36585 36586@item z @var{type},@var{addr},@var{kind} 36587@itemx Z @var{type},@var{addr},@var{kind} 36588@anchor{insert breakpoint or watchpoint packet} 36589@cindex @samp{z} packet 36590@cindex @samp{Z} packets 36591Insert (@samp{Z}) or remove (@samp{z}) a @var{type} breakpoint or 36592watchpoint starting at address @var{address} of kind @var{kind}. 36593 36594Each breakpoint and watchpoint packet @var{type} is documented 36595separately. 36596 36597@emph{Implementation notes: A remote target shall return an empty string 36598for an unrecognized breakpoint or watchpoint packet @var{type}. A 36599remote target shall support either both or neither of a given 36600@samp{Z@var{type}@dots{}} and @samp{z@var{type}@dots{}} packet pair. To 36601avoid potential problems with duplicate packets, the operations should 36602be implemented in an idempotent way.} 36603 36604@item z0,@var{addr},@var{kind} 36605@itemx Z0,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}@r{[};cmds:@var{persist},@var{cmd_list}@dots{}@r{]} 36606@cindex @samp{z0} packet 36607@cindex @samp{Z0} packet 36608Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address 36609@var{addr} of type @var{kind}. 36610 36611A memory breakpoint is implemented by replacing the instruction at 36612@var{addr} with a software breakpoint or trap instruction. The 36613@var{kind} is target-specific and typically indicates the size of 36614the breakpoint in bytes that should be inserted. E.g., the @sc{arm} 36615and @sc{mips} can insert either a 2 or 4 byte breakpoint. Some 36616architectures have additional meanings for @var{kind}; 36617@var{cond_list} is an optional list of conditional expressions in bytecode 36618form that should be evaluated on the target's side. These are the 36619conditions that should be taken into consideration when deciding if 36620the breakpoint trigger should be reported back to @var{GDBN}. 36621 36622The @var{cond_list} parameter is comprised of a series of expressions, 36623concatenated without separators. Each expression has the following form: 36624 36625@table @samp 36626 36627@item X @var{len},@var{expr} 36628@var{len} is the length of the bytecode expression and @var{expr} is the 36629actual conditional expression in bytecode form. 36630 36631@end table 36632 36633The optional @var{cmd_list} parameter introduces commands that may be 36634run on the target, rather than being reported back to @value{GDBN}. 36635The parameter starts with a numeric flag @var{persist}; if the flag is 36636nonzero, then the breakpoint may remain active and the commands 36637continue to be run even when @value{GDBN} disconnects from the target. 36638Following this flag is a series of expressions concatenated with no 36639separators. Each expression has the following form: 36640 36641@table @samp 36642 36643@item X @var{len},@var{expr} 36644@var{len} is the length of the bytecode expression and @var{expr} is the 36645actual conditional expression in bytecode form. 36646 36647@end table 36648 36649see @ref{Architecture-Specific Protocol Details}. 36650 36651@emph{Implementation note: It is possible for a target to copy or move 36652code that contains memory breakpoints (e.g., when implementing 36653overlays). The behavior of this packet, in the presence of such a 36654target, is not defined.} 36655 36656Reply: 36657@table @samp 36658@item OK 36659success 36660@item @w{} 36661not supported 36662@item E @var{NN} 36663for an error 36664@end table 36665 36666@item z1,@var{addr},@var{kind} 36667@itemx Z1,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]} 36668@cindex @samp{z1} packet 36669@cindex @samp{Z1} packet 36670Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at 36671address @var{addr}. 36672 36673A hardware breakpoint is implemented using a mechanism that is not 36674dependant on being able to modify the target's memory. @var{kind} 36675and @var{cond_list} have the same meaning as in @samp{Z0} packets. 36676 36677@emph{Implementation note: A hardware breakpoint is not affected by code 36678movement.} 36679 36680Reply: 36681@table @samp 36682@item OK 36683success 36684@item @w{} 36685not supported 36686@item E @var{NN} 36687for an error 36688@end table 36689 36690@item z2,@var{addr},@var{kind} 36691@itemx Z2,@var{addr},@var{kind} 36692@cindex @samp{z2} packet 36693@cindex @samp{Z2} packet 36694Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint at @var{addr}. 36695@var{kind} is interpreted as the number of bytes to watch. 36696 36697Reply: 36698@table @samp 36699@item OK 36700success 36701@item @w{} 36702not supported 36703@item E @var{NN} 36704for an error 36705@end table 36706 36707@item z3,@var{addr},@var{kind} 36708@itemx Z3,@var{addr},@var{kind} 36709@cindex @samp{z3} packet 36710@cindex @samp{Z3} packet 36711Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint at @var{addr}. 36712@var{kind} is interpreted as the number of bytes to watch. 36713 36714Reply: 36715@table @samp 36716@item OK 36717success 36718@item @w{} 36719not supported 36720@item E @var{NN} 36721for an error 36722@end table 36723 36724@item z4,@var{addr},@var{kind} 36725@itemx Z4,@var{addr},@var{kind} 36726@cindex @samp{z4} packet 36727@cindex @samp{Z4} packet 36728Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint at @var{addr}. 36729@var{kind} is interpreted as the number of bytes to watch. 36730 36731Reply: 36732@table @samp 36733@item OK 36734success 36735@item @w{} 36736not supported 36737@item E @var{NN} 36738for an error 36739@end table 36740 36741@end table 36742 36743@node Stop Reply Packets 36744@section Stop Reply Packets 36745@cindex stop reply packets 36746 36747The @samp{C}, @samp{c}, @samp{S}, @samp{s}, @samp{vCont}, 36748@samp{vAttach}, @samp{vRun}, @samp{vStopped}, and @samp{?} packets can 36749receive any of the below as a reply. Except for @samp{?} 36750and @samp{vStopped}, that reply is only returned 36751when the target halts. In the below the exact meaning of @dfn{signal 36752number} is defined by the header @file{include/gdb/signals.h} in the 36753@value{GDBN} source code. 36754 36755As in the description of request packets, we include spaces in the 36756reply templates for clarity; these are not part of the reply packet's 36757syntax. No @value{GDBN} stop reply packet uses spaces to separate its 36758components. 36759 36760@table @samp 36761 36762@item S @var{AA} 36763The program received signal number @var{AA} (a two-digit hexadecimal 36764number). This is equivalent to a @samp{T} response with no 36765@var{n}:@var{r} pairs. 36766 36767@item T @var{AA} @var{n1}:@var{r1};@var{n2}:@var{r2};@dots{} 36768@cindex @samp{T} packet reply 36769The program received signal number @var{AA} (a two-digit hexadecimal 36770number). This is equivalent to an @samp{S} response, except that the 36771@samp{@var{n}:@var{r}} pairs can carry values of important registers 36772and other information directly in the stop reply packet, reducing 36773round-trip latency. Single-step and breakpoint traps are reported 36774this way. Each @samp{@var{n}:@var{r}} pair is interpreted as follows: 36775 36776@itemize @bullet 36777@item 36778If @var{n} is a hexadecimal number, it is a register number, and the 36779corresponding @var{r} gives that register's value. @var{r} is a 36780series of bytes in target byte order, with each byte given by a 36781two-digit hex number. 36782 36783@item 36784If @var{n} is @samp{thread}, then @var{r} is the @var{thread-id} of 36785the stopped thread, as specified in @ref{thread-id syntax}. 36786 36787@item 36788If @var{n} is @samp{core}, then @var{r} is the hexadecimal number of 36789the core on which the stop event was detected. 36790 36791@item 36792If @var{n} is a recognized @dfn{stop reason}, it describes a more 36793specific event that stopped the target. The currently defined stop 36794reasons are listed below. @var{aa} should be @samp{05}, the trap 36795signal. At most one stop reason should be present. 36796 36797@item 36798Otherwise, @value{GDBN} should ignore this @samp{@var{n}:@var{r}} pair 36799and go on to the next; this allows us to extend the protocol in the 36800future. 36801@end itemize 36802 36803The currently defined stop reasons are: 36804 36805@table @samp 36806@item watch 36807@itemx rwatch 36808@itemx awatch 36809The packet indicates a watchpoint hit, and @var{r} is the data address, in 36810hex. 36811 36812@cindex shared library events, remote reply 36813@item library 36814The packet indicates that the loaded libraries have changed. 36815@value{GDBN} should use @samp{qXfer:libraries:read} to fetch a new 36816list of loaded libraries. @var{r} is ignored. 36817 36818@cindex replay log events, remote reply 36819@item replaylog 36820The packet indicates that the target cannot continue replaying 36821logged execution events, because it has reached the end (or the 36822beginning when executing backward) of the log. The value of @var{r} 36823will be either @samp{begin} or @samp{end}. @xref{Reverse Execution}, 36824for more information. 36825@end table 36826 36827@item W @var{AA} 36828@itemx W @var{AA} ; process:@var{pid} 36829The process exited, and @var{AA} is the exit status. This is only 36830applicable to certain targets. 36831 36832The second form of the response, including the process ID of the exited 36833process, can be used only when @value{GDBN} has reported support for 36834multiprocess protocol extensions; see @ref{multiprocess extensions}. 36835The @var{pid} is formatted as a big-endian hex string. 36836 36837@item X @var{AA} 36838@itemx X @var{AA} ; process:@var{pid} 36839The process terminated with signal @var{AA}. 36840 36841The second form of the response, including the process ID of the 36842terminated process, can be used only when @value{GDBN} has reported 36843support for multiprocess protocol extensions; see @ref{multiprocess 36844extensions}. The @var{pid} is formatted as a big-endian hex string. 36845 36846@item O @var{XX}@dots{} 36847@samp{@var{XX}@dots{}} is hex encoding of @sc{ascii} data, to be 36848written as the program's console output. This can happen at any time 36849while the program is running and the debugger should continue to wait 36850for @samp{W}, @samp{T}, etc. This reply is not permitted in non-stop mode. 36851 36852@item F @var{call-id},@var{parameter}@dots{} 36853@var{call-id} is the identifier which says which host system call should 36854be called. This is just the name of the function. Translation into the 36855correct system call is only applicable as it's defined in @value{GDBN}. 36856@xref{File-I/O Remote Protocol Extension}, for a list of implemented 36857system calls. 36858 36859@samp{@var{parameter}@dots{}} is a list of parameters as defined for 36860this very system call. 36861 36862The target replies with this packet when it expects @value{GDBN} to 36863call a host system call on behalf of the target. @value{GDBN} replies 36864with an appropriate @samp{F} packet and keeps up waiting for the next 36865reply packet from the target. The latest @samp{C}, @samp{c}, @samp{S} 36866or @samp{s} action is expected to be continued. @xref{File-I/O Remote 36867Protocol Extension}, for more details. 36868 36869@end table 36870 36871@node General Query Packets 36872@section General Query Packets 36873@cindex remote query requests 36874 36875Packets starting with @samp{q} are @dfn{general query packets}; 36876packets starting with @samp{Q} are @dfn{general set packets}. General 36877query and set packets are a semi-unified form for retrieving and 36878sending information to and from the stub. 36879 36880The initial letter of a query or set packet is followed by a name 36881indicating what sort of thing the packet applies to. For example, 36882@value{GDBN} may use a @samp{qSymbol} packet to exchange symbol 36883definitions with the stub. These packet names follow some 36884conventions: 36885 36886@itemize @bullet 36887@item 36888The name must not contain commas, colons or semicolons. 36889@item 36890Most @value{GDBN} query and set packets have a leading upper case 36891letter. 36892@item 36893The names of custom vendor packets should use a company prefix, in 36894lower case, followed by a period. For example, packets designed at 36895the Acme Corporation might begin with @samp{qacme.foo} (for querying 36896foos) or @samp{Qacme.bar} (for setting bars). 36897@end itemize 36898 36899The name of a query or set packet should be separated from any 36900parameters by a @samp{:}; the parameters themselves should be 36901separated by @samp{,} or @samp{;}. Stubs must be careful to match the 36902full packet name, and check for a separator or the end of the packet, 36903in case two packet names share a common prefix. New packets should not begin 36904with @samp{qC}, @samp{qP}, or @samp{qL}@footnote{The @samp{qP} and @samp{qL} 36905packets predate these conventions, and have arguments without any terminator 36906for the packet name; we suspect they are in widespread use in places that 36907are difficult to upgrade. The @samp{qC} packet has no arguments, but some 36908existing stubs (e.g.@: RedBoot) are known to not check for the end of the 36909packet.}. 36910 36911Like the descriptions of the other packets, each description here 36912has a template showing the packet's overall syntax, followed by an 36913explanation of the packet's meaning. We include spaces in some of the 36914templates for clarity; these are not part of the packet's syntax. No 36915@value{GDBN} packet uses spaces to separate its components. 36916 36917Here are the currently defined query and set packets: 36918 36919@table @samp 36920 36921@item QAgent:1 36922@itemx QAgent:0 36923Turn on or off the agent as a helper to perform some debugging operations 36924delegated from @value{GDBN} (@pxref{Control Agent}). 36925 36926@item QAllow:@var{op}:@var{val}@dots{} 36927@cindex @samp{QAllow} packet 36928Specify which operations @value{GDBN} expects to request of the 36929target, as a semicolon-separated list of operation name and value 36930pairs. Possible values for @var{op} include @samp{WriteReg}, 36931@samp{WriteMem}, @samp{InsertBreak}, @samp{InsertTrace}, 36932@samp{InsertFastTrace}, and @samp{Stop}. @var{val} is either 0, 36933indicating that @value{GDBN} will not request the operation, or 1, 36934indicating that it may. (The target can then use this to set up its 36935own internals optimally, for instance if the debugger never expects to 36936insert breakpoints, it may not need to install its own trap handler.) 36937 36938@item qC 36939@cindex current thread, remote request 36940@cindex @samp{qC} packet 36941Return the current thread ID. 36942 36943Reply: 36944@table @samp 36945@item QC @var{thread-id} 36946Where @var{thread-id} is a thread ID as documented in 36947@ref{thread-id syntax}. 36948@item @r{(anything else)} 36949Any other reply implies the old thread ID. 36950@end table 36951 36952@item qCRC:@var{addr},@var{length} 36953@cindex CRC of memory block, remote request 36954@cindex @samp{qCRC} packet 36955Compute the CRC checksum of a block of memory using CRC-32 defined in 36956IEEE 802.3. The CRC is computed byte at a time, taking the most 36957significant bit of each byte first. The initial pattern code 36958@code{0xffffffff} is used to ensure leading zeros affect the CRC. 36959 36960@emph{Note:} This is the same CRC used in validating separate debug 36961files (@pxref{Separate Debug Files, , Debugging Information in Separate 36962Files}). However the algorithm is slightly different. When validating 36963separate debug files, the CRC is computed taking the @emph{least} 36964significant bit of each byte first, and the final result is inverted to 36965detect trailing zeros. 36966 36967Reply: 36968@table @samp 36969@item E @var{NN} 36970An error (such as memory fault) 36971@item C @var{crc32} 36972The specified memory region's checksum is @var{crc32}. 36973@end table 36974 36975@item QDisableRandomization:@var{value} 36976@cindex disable address space randomization, remote request 36977@cindex @samp{QDisableRandomization} packet 36978Some target operating systems will randomize the virtual address space 36979of the inferior process as a security feature, but provide a feature 36980to disable such randomization, e.g.@: to allow for a more deterministic 36981debugging experience. On such systems, this packet with a @var{value} 36982of 1 directs the target to disable address space randomization for 36983processes subsequently started via @samp{vRun} packets, while a packet 36984with a @var{value} of 0 tells the target to enable address space 36985randomization. 36986 36987This packet is only available in extended mode (@pxref{extended mode}). 36988 36989Reply: 36990@table @samp 36991@item OK 36992The request succeeded. 36993 36994@item E @var{nn} 36995An error occurred. @var{nn} are hex digits. 36996 36997@item @w{} 36998An empty reply indicates that @samp{QDisableRandomization} is not supported 36999by the stub. 37000@end table 37001 37002This packet is not probed by default; the remote stub must request it, 37003by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 37004This should only be done on targets that actually support disabling 37005address space randomization. 37006 37007@item qfThreadInfo 37008@itemx qsThreadInfo 37009@cindex list active threads, remote request 37010@cindex @samp{qfThreadInfo} packet 37011@cindex @samp{qsThreadInfo} packet 37012Obtain a list of all active thread IDs from the target (OS). Since there 37013may be too many active threads to fit into one reply packet, this query 37014works iteratively: it may require more than one query/reply sequence to 37015obtain the entire list of threads. The first query of the sequence will 37016be the @samp{qfThreadInfo} query; subsequent queries in the 37017sequence will be the @samp{qsThreadInfo} query. 37018 37019NOTE: This packet replaces the @samp{qL} query (see below). 37020 37021Reply: 37022@table @samp 37023@item m @var{thread-id} 37024A single thread ID 37025@item m @var{thread-id},@var{thread-id}@dots{} 37026a comma-separated list of thread IDs 37027@item l 37028(lower case letter @samp{L}) denotes end of list. 37029@end table 37030 37031In response to each query, the target will reply with a list of one or 37032more thread IDs, separated by commas. 37033@value{GDBN} will respond to each reply with a request for more thread 37034ids (using the @samp{qs} form of the query), until the target responds 37035with @samp{l} (lower-case ell, for @dfn{last}). 37036Refer to @ref{thread-id syntax}, for the format of the @var{thread-id} 37037fields. 37038 37039@item qGetTLSAddr:@var{thread-id},@var{offset},@var{lm} 37040@cindex get thread-local storage address, remote request 37041@cindex @samp{qGetTLSAddr} packet 37042Fetch the address associated with thread local storage specified 37043by @var{thread-id}, @var{offset}, and @var{lm}. 37044 37045@var{thread-id} is the thread ID associated with the 37046thread for which to fetch the TLS address. @xref{thread-id syntax}. 37047 37048@var{offset} is the (big endian, hex encoded) offset associated with the 37049thread local variable. (This offset is obtained from the debug 37050information associated with the variable.) 37051 37052@var{lm} is the (big endian, hex encoded) OS/ABI-specific encoding of the 37053load module associated with the thread local storage. For example, 37054a @sc{gnu}/Linux system will pass the link map address of the shared 37055object associated with the thread local storage under consideration. 37056Other operating environments may choose to represent the load module 37057differently, so the precise meaning of this parameter will vary. 37058 37059Reply: 37060@table @samp 37061@item @var{XX}@dots{} 37062Hex encoded (big endian) bytes representing the address of the thread 37063local storage requested. 37064 37065@item E @var{nn} 37066An error occurred. @var{nn} are hex digits. 37067 37068@item @w{} 37069An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub. 37070@end table 37071 37072@item qGetTIBAddr:@var{thread-id} 37073@cindex get thread information block address 37074@cindex @samp{qGetTIBAddr} packet 37075Fetch address of the Windows OS specific Thread Information Block. 37076 37077@var{thread-id} is the thread ID associated with the thread. 37078 37079Reply: 37080@table @samp 37081@item @var{XX}@dots{} 37082Hex encoded (big endian) bytes representing the linear address of the 37083thread information block. 37084 37085@item E @var{nn} 37086An error occured. This means that either the thread was not found, or the 37087address could not be retrieved. 37088 37089@item @w{} 37090An empty reply indicates that @samp{qGetTIBAddr} is not supported by the stub. 37091@end table 37092 37093@item qL @var{startflag} @var{threadcount} @var{nextthread} 37094Obtain thread information from RTOS. Where: @var{startflag} (one hex 37095digit) is one to indicate the first query and zero to indicate a 37096subsequent query; @var{threadcount} (two hex digits) is the maximum 37097number of threads the response packet can contain; and @var{nextthread} 37098(eight hex digits), for subsequent queries (@var{startflag} is zero), is 37099returned in the response as @var{argthread}. 37100 37101Don't use this packet; use the @samp{qfThreadInfo} query instead (see above). 37102 37103Reply: 37104@table @samp 37105@item qM @var{count} @var{done} @var{argthread} @var{thread}@dots{} 37106Where: @var{count} (two hex digits) is the number of threads being 37107returned; @var{done} (one hex digit) is zero to indicate more threads 37108and one indicates no further threads; @var{argthreadid} (eight hex 37109digits) is @var{nextthread} from the request packet; @var{thread}@dots{} 37110is a sequence of thread IDs from the target. @var{threadid} (eight hex 37111digits). See @code{remote.c:parse_threadlist_response()}. 37112@end table 37113 37114@item qOffsets 37115@cindex section offsets, remote request 37116@cindex @samp{qOffsets} packet 37117Get section offsets that the target used when relocating the downloaded 37118image. 37119 37120Reply: 37121@table @samp 37122@item Text=@var{xxx};Data=@var{yyy}@r{[};Bss=@var{zzz}@r{]} 37123Relocate the @code{Text} section by @var{xxx} from its original address. 37124Relocate the @code{Data} section by @var{yyy} from its original address. 37125If the object file format provides segment information (e.g.@: @sc{elf} 37126@samp{PT_LOAD} program headers), @value{GDBN} will relocate entire 37127segments by the supplied offsets. 37128 37129@emph{Note: while a @code{Bss} offset may be included in the response, 37130@value{GDBN} ignores this and instead applies the @code{Data} offset 37131to the @code{Bss} section.} 37132 37133@item TextSeg=@var{xxx}@r{[};DataSeg=@var{yyy}@r{]} 37134Relocate the first segment of the object file, which conventionally 37135contains program code, to a starting address of @var{xxx}. If 37136@samp{DataSeg} is specified, relocate the second segment, which 37137conventionally contains modifiable data, to a starting address of 37138@var{yyy}. @value{GDBN} will report an error if the object file 37139does not contain segment information, or does not contain at least 37140as many segments as mentioned in the reply. Extra segments are 37141kept at fixed offsets relative to the last relocated segment. 37142@end table 37143 37144@item qP @var{mode} @var{thread-id} 37145@cindex thread information, remote request 37146@cindex @samp{qP} packet 37147Returns information on @var{thread-id}. Where: @var{mode} is a hex 37148encoded 32 bit mode; @var{thread-id} is a thread ID 37149(@pxref{thread-id syntax}). 37150 37151Don't use this packet; use the @samp{qThreadExtraInfo} query instead 37152(see below). 37153 37154Reply: see @code{remote.c:remote_unpack_thread_info_response()}. 37155 37156@item QNonStop:1 37157@itemx QNonStop:0 37158@cindex non-stop mode, remote request 37159@cindex @samp{QNonStop} packet 37160@anchor{QNonStop} 37161Enter non-stop (@samp{QNonStop:1}) or all-stop (@samp{QNonStop:0}) mode. 37162@xref{Remote Non-Stop}, for more information. 37163 37164Reply: 37165@table @samp 37166@item OK 37167The request succeeded. 37168 37169@item E @var{nn} 37170An error occurred. @var{nn} are hex digits. 37171 37172@item @w{} 37173An empty reply indicates that @samp{QNonStop} is not supported by 37174the stub. 37175@end table 37176 37177This packet is not probed by default; the remote stub must request it, 37178by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 37179Use of this packet is controlled by the @code{set non-stop} command; 37180@pxref{Non-Stop Mode}. 37181 37182@item QPassSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{} 37183@cindex pass signals to inferior, remote request 37184@cindex @samp{QPassSignals} packet 37185@anchor{QPassSignals} 37186Each listed @var{signal} should be passed directly to the inferior process. 37187Signals are numbered identically to continue packets and stop replies 37188(@pxref{Stop Reply Packets}). Each @var{signal} list item should be 37189strictly greater than the previous item. These signals do not need to stop 37190the inferior, or be reported to @value{GDBN}. All other signals should be 37191reported to @value{GDBN}. Multiple @samp{QPassSignals} packets do not 37192combine; any earlier @samp{QPassSignals} list is completely replaced by the 37193new list. This packet improves performance when using @samp{handle 37194@var{signal} nostop noprint pass}. 37195 37196Reply: 37197@table @samp 37198@item OK 37199The request succeeded. 37200 37201@item E @var{nn} 37202An error occurred. @var{nn} are hex digits. 37203 37204@item @w{} 37205An empty reply indicates that @samp{QPassSignals} is not supported by 37206the stub. 37207@end table 37208 37209Use of this packet is controlled by the @code{set remote pass-signals} 37210command (@pxref{Remote Configuration, set remote pass-signals}). 37211This packet is not probed by default; the remote stub must request it, 37212by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 37213 37214@item QProgramSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{} 37215@cindex signals the inferior may see, remote request 37216@cindex @samp{QProgramSignals} packet 37217@anchor{QProgramSignals} 37218Each listed @var{signal} may be delivered to the inferior process. 37219Others should be silently discarded. 37220 37221In some cases, the remote stub may need to decide whether to deliver a 37222signal to the program or not without @value{GDBN} involvement. One 37223example of that is while detaching --- the program's threads may have 37224stopped for signals that haven't yet had a chance of being reported to 37225@value{GDBN}, and so the remote stub can use the signal list specified 37226by this packet to know whether to deliver or ignore those pending 37227signals. 37228 37229This does not influence whether to deliver a signal as requested by a 37230resumption packet (@pxref{vCont packet}). 37231 37232Signals are numbered identically to continue packets and stop replies 37233(@pxref{Stop Reply Packets}). Each @var{signal} list item should be 37234strictly greater than the previous item. Multiple 37235@samp{QProgramSignals} packets do not combine; any earlier 37236@samp{QProgramSignals} list is completely replaced by the new list. 37237 37238Reply: 37239@table @samp 37240@item OK 37241The request succeeded. 37242 37243@item E @var{nn} 37244An error occurred. @var{nn} are hex digits. 37245 37246@item @w{} 37247An empty reply indicates that @samp{QProgramSignals} is not supported 37248by the stub. 37249@end table 37250 37251Use of this packet is controlled by the @code{set remote program-signals} 37252command (@pxref{Remote Configuration, set remote program-signals}). 37253This packet is not probed by default; the remote stub must request it, 37254by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 37255 37256@item qRcmd,@var{command} 37257@cindex execute remote command, remote request 37258@cindex @samp{qRcmd} packet 37259@var{command} (hex encoded) is passed to the local interpreter for 37260execution. Invalid commands should be reported using the output 37261string. Before the final result packet, the target may also respond 37262with a number of intermediate @samp{O@var{output}} console output 37263packets. @emph{Implementors should note that providing access to a 37264stubs's interpreter may have security implications}. 37265 37266Reply: 37267@table @samp 37268@item OK 37269A command response with no output. 37270@item @var{OUTPUT} 37271A command response with the hex encoded output string @var{OUTPUT}. 37272@item E @var{NN} 37273Indicate a badly formed request. 37274@item @w{} 37275An empty reply indicates that @samp{qRcmd} is not recognized. 37276@end table 37277 37278(Note that the @code{qRcmd} packet's name is separated from the 37279command by a @samp{,}, not a @samp{:}, contrary to the naming 37280conventions above. Please don't use this packet as a model for new 37281packets.) 37282 37283@item qSearch:memory:@var{address};@var{length};@var{search-pattern} 37284@cindex searching memory, in remote debugging 37285@ifnotinfo 37286@cindex @samp{qSearch:memory} packet 37287@end ifnotinfo 37288@cindex @samp{qSearch memory} packet 37289@anchor{qSearch memory} 37290Search @var{length} bytes at @var{address} for @var{search-pattern}. 37291@var{address} and @var{length} are encoded in hex. 37292@var{search-pattern} is a sequence of bytes, hex encoded. 37293 37294Reply: 37295@table @samp 37296@item 0 37297The pattern was not found. 37298@item 1,address 37299The pattern was found at @var{address}. 37300@item E @var{NN} 37301A badly formed request or an error was encountered while searching memory. 37302@item @w{} 37303An empty reply indicates that @samp{qSearch:memory} is not recognized. 37304@end table 37305 37306@item QStartNoAckMode 37307@cindex @samp{QStartNoAckMode} packet 37308@anchor{QStartNoAckMode} 37309Request that the remote stub disable the normal @samp{+}/@samp{-} 37310protocol acknowledgments (@pxref{Packet Acknowledgment}). 37311 37312Reply: 37313@table @samp 37314@item OK 37315The stub has switched to no-acknowledgment mode. 37316@value{GDBN} acknowledges this reponse, 37317but neither the stub nor @value{GDBN} shall send or expect further 37318@samp{+}/@samp{-} acknowledgments in the current connection. 37319@item @w{} 37320An empty reply indicates that the stub does not support no-acknowledgment mode. 37321@end table 37322 37323@item qSupported @r{[}:@var{gdbfeature} @r{[};@var{gdbfeature}@r{]}@dots{} @r{]} 37324@cindex supported packets, remote query 37325@cindex features of the remote protocol 37326@cindex @samp{qSupported} packet 37327@anchor{qSupported} 37328Tell the remote stub about features supported by @value{GDBN}, and 37329query the stub for features it supports. This packet allows 37330@value{GDBN} and the remote stub to take advantage of each others' 37331features. @samp{qSupported} also consolidates multiple feature probes 37332at startup, to improve @value{GDBN} performance---a single larger 37333packet performs better than multiple smaller probe packets on 37334high-latency links. Some features may enable behavior which must not 37335be on by default, e.g.@: because it would confuse older clients or 37336stubs. Other features may describe packets which could be 37337automatically probed for, but are not. These features must be 37338reported before @value{GDBN} will use them. This ``default 37339unsupported'' behavior is not appropriate for all packets, but it 37340helps to keep the initial connection time under control with new 37341versions of @value{GDBN} which support increasing numbers of packets. 37342 37343Reply: 37344@table @samp 37345@item @var{stubfeature} @r{[};@var{stubfeature}@r{]}@dots{} 37346The stub supports or does not support each returned @var{stubfeature}, 37347depending on the form of each @var{stubfeature} (see below for the 37348possible forms). 37349@item @w{} 37350An empty reply indicates that @samp{qSupported} is not recognized, 37351or that no features needed to be reported to @value{GDBN}. 37352@end table 37353 37354The allowed forms for each feature (either a @var{gdbfeature} in the 37355@samp{qSupported} packet, or a @var{stubfeature} in the response) 37356are: 37357 37358@table @samp 37359@item @var{name}=@var{value} 37360The remote protocol feature @var{name} is supported, and associated 37361with the specified @var{value}. The format of @var{value} depends 37362on the feature, but it must not include a semicolon. 37363@item @var{name}+ 37364The remote protocol feature @var{name} is supported, and does not 37365need an associated value. 37366@item @var{name}- 37367The remote protocol feature @var{name} is not supported. 37368@item @var{name}? 37369The remote protocol feature @var{name} may be supported, and 37370@value{GDBN} should auto-detect support in some other way when it is 37371needed. This form will not be used for @var{gdbfeature} notifications, 37372but may be used for @var{stubfeature} responses. 37373@end table 37374 37375Whenever the stub receives a @samp{qSupported} request, the 37376supplied set of @value{GDBN} features should override any previous 37377request. This allows @value{GDBN} to put the stub in a known 37378state, even if the stub had previously been communicating with 37379a different version of @value{GDBN}. 37380 37381The following values of @var{gdbfeature} (for the packet sent by @value{GDBN}) 37382are defined: 37383 37384@table @samp 37385@item multiprocess 37386This feature indicates whether @value{GDBN} supports multiprocess 37387extensions to the remote protocol. @value{GDBN} does not use such 37388extensions unless the stub also reports that it supports them by 37389including @samp{multiprocess+} in its @samp{qSupported} reply. 37390@xref{multiprocess extensions}, for details. 37391 37392@item xmlRegisters 37393This feature indicates that @value{GDBN} supports the XML target 37394description. If the stub sees @samp{xmlRegisters=} with target 37395specific strings separated by a comma, it will report register 37396description. 37397 37398@item qRelocInsn 37399This feature indicates whether @value{GDBN} supports the 37400@samp{qRelocInsn} packet (@pxref{Tracepoint Packets,,Relocate 37401instruction reply packet}). 37402@end table 37403 37404Stubs should ignore any unknown values for 37405@var{gdbfeature}. Any @value{GDBN} which sends a @samp{qSupported} 37406packet supports receiving packets of unlimited length (earlier 37407versions of @value{GDBN} may reject overly long responses). Additional values 37408for @var{gdbfeature} may be defined in the future to let the stub take 37409advantage of new features in @value{GDBN}, e.g.@: incompatible 37410improvements in the remote protocol---the @samp{multiprocess} feature is 37411an example of such a feature. The stub's reply should be independent 37412of the @var{gdbfeature} entries sent by @value{GDBN}; first @value{GDBN} 37413describes all the features it supports, and then the stub replies with 37414all the features it supports. 37415 37416Similarly, @value{GDBN} will silently ignore unrecognized stub feature 37417responses, as long as each response uses one of the standard forms. 37418 37419Some features are flags. A stub which supports a flag feature 37420should respond with a @samp{+} form response. Other features 37421require values, and the stub should respond with an @samp{=} 37422form response. 37423 37424Each feature has a default value, which @value{GDBN} will use if 37425@samp{qSupported} is not available or if the feature is not mentioned 37426in the @samp{qSupported} response. The default values are fixed; a 37427stub is free to omit any feature responses that match the defaults. 37428 37429Not all features can be probed, but for those which can, the probing 37430mechanism is useful: in some cases, a stub's internal 37431architecture may not allow the protocol layer to know some information 37432about the underlying target in advance. This is especially common in 37433stubs which may be configured for multiple targets. 37434 37435These are the currently defined stub features and their properties: 37436 37437@multitable @columnfractions 0.35 0.2 0.12 0.2 37438@c NOTE: The first row should be @headitem, but we do not yet require 37439@c a new enough version of Texinfo (4.7) to use @headitem. 37440@item Feature Name 37441@tab Value Required 37442@tab Default 37443@tab Probe Allowed 37444 37445@item @samp{PacketSize} 37446@tab Yes 37447@tab @samp{-} 37448@tab No 37449 37450@item @samp{qXfer:auxv:read} 37451@tab No 37452@tab @samp{-} 37453@tab Yes 37454 37455@item @samp{qXfer:btrace:read} 37456@tab No 37457@tab @samp{-} 37458@tab Yes 37459 37460@item @samp{qXfer:features:read} 37461@tab No 37462@tab @samp{-} 37463@tab Yes 37464 37465@item @samp{qXfer:libraries:read} 37466@tab No 37467@tab @samp{-} 37468@tab Yes 37469 37470@item @samp{qXfer:memory-map:read} 37471@tab No 37472@tab @samp{-} 37473@tab Yes 37474 37475@item @samp{qXfer:sdata:read} 37476@tab No 37477@tab @samp{-} 37478@tab Yes 37479 37480@item @samp{qXfer:spu:read} 37481@tab No 37482@tab @samp{-} 37483@tab Yes 37484 37485@item @samp{qXfer:spu:write} 37486@tab No 37487@tab @samp{-} 37488@tab Yes 37489 37490@item @samp{qXfer:siginfo:read} 37491@tab No 37492@tab @samp{-} 37493@tab Yes 37494 37495@item @samp{qXfer:siginfo:write} 37496@tab No 37497@tab @samp{-} 37498@tab Yes 37499 37500@item @samp{qXfer:threads:read} 37501@tab No 37502@tab @samp{-} 37503@tab Yes 37504 37505@item @samp{qXfer:traceframe-info:read} 37506@tab No 37507@tab @samp{-} 37508@tab Yes 37509 37510@item @samp{qXfer:uib:read} 37511@tab No 37512@tab @samp{-} 37513@tab Yes 37514 37515@item @samp{qXfer:fdpic:read} 37516@tab No 37517@tab @samp{-} 37518@tab Yes 37519 37520@item @samp{Qbtrace:off} 37521@tab Yes 37522@tab @samp{-} 37523@tab Yes 37524 37525@item @samp{Qbtrace:bts} 37526@tab Yes 37527@tab @samp{-} 37528@tab Yes 37529 37530@item @samp{QNonStop} 37531@tab No 37532@tab @samp{-} 37533@tab Yes 37534 37535@item @samp{QPassSignals} 37536@tab No 37537@tab @samp{-} 37538@tab Yes 37539 37540@item @samp{QStartNoAckMode} 37541@tab No 37542@tab @samp{-} 37543@tab Yes 37544 37545@item @samp{multiprocess} 37546@tab No 37547@tab @samp{-} 37548@tab No 37549 37550@item @samp{ConditionalBreakpoints} 37551@tab No 37552@tab @samp{-} 37553@tab No 37554 37555@item @samp{ConditionalTracepoints} 37556@tab No 37557@tab @samp{-} 37558@tab No 37559 37560@item @samp{ReverseContinue} 37561@tab No 37562@tab @samp{-} 37563@tab No 37564 37565@item @samp{ReverseStep} 37566@tab No 37567@tab @samp{-} 37568@tab No 37569 37570@item @samp{TracepointSource} 37571@tab No 37572@tab @samp{-} 37573@tab No 37574 37575@item @samp{QAgent} 37576@tab No 37577@tab @samp{-} 37578@tab No 37579 37580@item @samp{QAllow} 37581@tab No 37582@tab @samp{-} 37583@tab No 37584 37585@item @samp{QDisableRandomization} 37586@tab No 37587@tab @samp{-} 37588@tab No 37589 37590@item @samp{EnableDisableTracepoints} 37591@tab No 37592@tab @samp{-} 37593@tab No 37594 37595@item @samp{QTBuffer:size} 37596@tab No 37597@tab @samp{-} 37598@tab No 37599 37600@item @samp{tracenz} 37601@tab No 37602@tab @samp{-} 37603@tab No 37604 37605@item @samp{BreakpointCommands} 37606@tab No 37607@tab @samp{-} 37608@tab No 37609 37610@end multitable 37611 37612These are the currently defined stub features, in more detail: 37613 37614@table @samp 37615@cindex packet size, remote protocol 37616@item PacketSize=@var{bytes} 37617The remote stub can accept packets up to at least @var{bytes} in 37618length. @value{GDBN} will send packets up to this size for bulk 37619transfers, and will never send larger packets. This is a limit on the 37620data characters in the packet, including the frame and checksum. 37621There is no trailing NUL byte in a remote protocol packet; if the stub 37622stores packets in a NUL-terminated format, it should allow an extra 37623byte in its buffer for the NUL. If this stub feature is not supported, 37624@value{GDBN} guesses based on the size of the @samp{g} packet response. 37625 37626@item qXfer:auxv:read 37627The remote stub understands the @samp{qXfer:auxv:read} packet 37628(@pxref{qXfer auxiliary vector read}). 37629 37630@item qXfer:btrace:read 37631The remote stub understands the @samp{qXfer:btrace:read} 37632packet (@pxref{qXfer btrace read}). 37633 37634@item qXfer:features:read 37635The remote stub understands the @samp{qXfer:features:read} packet 37636(@pxref{qXfer target description read}). 37637 37638@item qXfer:libraries:read 37639The remote stub understands the @samp{qXfer:libraries:read} packet 37640(@pxref{qXfer library list read}). 37641 37642@item qXfer:libraries-svr4:read 37643The remote stub understands the @samp{qXfer:libraries-svr4:read} packet 37644(@pxref{qXfer svr4 library list read}). 37645 37646@item qXfer:memory-map:read 37647The remote stub understands the @samp{qXfer:memory-map:read} packet 37648(@pxref{qXfer memory map read}). 37649 37650@item qXfer:sdata:read 37651The remote stub understands the @samp{qXfer:sdata:read} packet 37652(@pxref{qXfer sdata read}). 37653 37654@item qXfer:spu:read 37655The remote stub understands the @samp{qXfer:spu:read} packet 37656(@pxref{qXfer spu read}). 37657 37658@item qXfer:spu:write 37659The remote stub understands the @samp{qXfer:spu:write} packet 37660(@pxref{qXfer spu write}). 37661 37662@item qXfer:siginfo:read 37663The remote stub understands the @samp{qXfer:siginfo:read} packet 37664(@pxref{qXfer siginfo read}). 37665 37666@item qXfer:siginfo:write 37667The remote stub understands the @samp{qXfer:siginfo:write} packet 37668(@pxref{qXfer siginfo write}). 37669 37670@item qXfer:threads:read 37671The remote stub understands the @samp{qXfer:threads:read} packet 37672(@pxref{qXfer threads read}). 37673 37674@item qXfer:traceframe-info:read 37675The remote stub understands the @samp{qXfer:traceframe-info:read} 37676packet (@pxref{qXfer traceframe info read}). 37677 37678@item qXfer:uib:read 37679The remote stub understands the @samp{qXfer:uib:read} 37680packet (@pxref{qXfer unwind info block}). 37681 37682@item qXfer:fdpic:read 37683The remote stub understands the @samp{qXfer:fdpic:read} 37684packet (@pxref{qXfer fdpic loadmap read}). 37685 37686@item QNonStop 37687The remote stub understands the @samp{QNonStop} packet 37688(@pxref{QNonStop}). 37689 37690@item QPassSignals 37691The remote stub understands the @samp{QPassSignals} packet 37692(@pxref{QPassSignals}). 37693 37694@item QStartNoAckMode 37695The remote stub understands the @samp{QStartNoAckMode} packet and 37696prefers to operate in no-acknowledgment mode. @xref{Packet Acknowledgment}. 37697 37698@item multiprocess 37699@anchor{multiprocess extensions} 37700@cindex multiprocess extensions, in remote protocol 37701The remote stub understands the multiprocess extensions to the remote 37702protocol syntax. The multiprocess extensions affect the syntax of 37703thread IDs in both packets and replies (@pxref{thread-id syntax}), and 37704add process IDs to the @samp{D} packet and @samp{W} and @samp{X} 37705replies. Note that reporting this feature indicates support for the 37706syntactic extensions only, not that the stub necessarily supports 37707debugging of more than one process at a time. The stub must not use 37708multiprocess extensions in packet replies unless @value{GDBN} has also 37709indicated it supports them in its @samp{qSupported} request. 37710 37711@item qXfer:osdata:read 37712The remote stub understands the @samp{qXfer:osdata:read} packet 37713((@pxref{qXfer osdata read}). 37714 37715@item ConditionalBreakpoints 37716The target accepts and implements evaluation of conditional expressions 37717defined for breakpoints. The target will only report breakpoint triggers 37718when such conditions are true (@pxref{Conditions, ,Break Conditions}). 37719 37720@item ConditionalTracepoints 37721The remote stub accepts and implements conditional expressions defined 37722for tracepoints (@pxref{Tracepoint Conditions}). 37723 37724@item ReverseContinue 37725The remote stub accepts and implements the reverse continue packet 37726(@pxref{bc}). 37727 37728@item ReverseStep 37729The remote stub accepts and implements the reverse step packet 37730(@pxref{bs}). 37731 37732@item TracepointSource 37733The remote stub understands the @samp{QTDPsrc} packet that supplies 37734the source form of tracepoint definitions. 37735 37736@item QAgent 37737The remote stub understands the @samp{QAgent} packet. 37738 37739@item QAllow 37740The remote stub understands the @samp{QAllow} packet. 37741 37742@item QDisableRandomization 37743The remote stub understands the @samp{QDisableRandomization} packet. 37744 37745@item StaticTracepoint 37746@cindex static tracepoints, in remote protocol 37747The remote stub supports static tracepoints. 37748 37749@item InstallInTrace 37750@anchor{install tracepoint in tracing} 37751The remote stub supports installing tracepoint in tracing. 37752 37753@item EnableDisableTracepoints 37754The remote stub supports the @samp{QTEnable} (@pxref{QTEnable}) and 37755@samp{QTDisable} (@pxref{QTDisable}) packets that allow tracepoints 37756to be enabled and disabled while a trace experiment is running. 37757 37758@item QTBuffer:size 37759The remote stub supports the @samp{QTBuffer:size} (@pxref{QTBuffer-size}) 37760packet that allows to change the size of the trace buffer. 37761 37762@item tracenz 37763@cindex string tracing, in remote protocol 37764The remote stub supports the @samp{tracenz} bytecode for collecting strings. 37765See @ref{Bytecode Descriptions} for details about the bytecode. 37766 37767@item BreakpointCommands 37768@cindex breakpoint commands, in remote protocol 37769The remote stub supports running a breakpoint's command list itself, 37770rather than reporting the hit to @value{GDBN}. 37771 37772@item Qbtrace:off 37773The remote stub understands the @samp{Qbtrace:off} packet. 37774 37775@item Qbtrace:bts 37776The remote stub understands the @samp{Qbtrace:bts} packet. 37777 37778@end table 37779 37780@item qSymbol:: 37781@cindex symbol lookup, remote request 37782@cindex @samp{qSymbol} packet 37783Notify the target that @value{GDBN} is prepared to serve symbol lookup 37784requests. Accept requests from the target for the values of symbols. 37785 37786Reply: 37787@table @samp 37788@item OK 37789The target does not need to look up any (more) symbols. 37790@item qSymbol:@var{sym_name} 37791The target requests the value of symbol @var{sym_name} (hex encoded). 37792@value{GDBN} may provide the value by using the 37793@samp{qSymbol:@var{sym_value}:@var{sym_name}} message, described 37794below. 37795@end table 37796 37797@item qSymbol:@var{sym_value}:@var{sym_name} 37798Set the value of @var{sym_name} to @var{sym_value}. 37799 37800@var{sym_name} (hex encoded) is the name of a symbol whose value the 37801target has previously requested. 37802 37803@var{sym_value} (hex) is the value for symbol @var{sym_name}. If 37804@value{GDBN} cannot supply a value for @var{sym_name}, then this field 37805will be empty. 37806 37807Reply: 37808@table @samp 37809@item OK 37810The target does not need to look up any (more) symbols. 37811@item qSymbol:@var{sym_name} 37812The target requests the value of a new symbol @var{sym_name} (hex 37813encoded). @value{GDBN} will continue to supply the values of symbols 37814(if available), until the target ceases to request them. 37815@end table 37816 37817@item qTBuffer 37818@itemx QTBuffer 37819@itemx QTDisconnected 37820@itemx QTDP 37821@itemx QTDPsrc 37822@itemx QTDV 37823@itemx qTfP 37824@itemx qTfV 37825@itemx QTFrame 37826@itemx qTMinFTPILen 37827 37828@xref{Tracepoint Packets}. 37829 37830@item qThreadExtraInfo,@var{thread-id} 37831@cindex thread attributes info, remote request 37832@cindex @samp{qThreadExtraInfo} packet 37833Obtain a printable string description of a thread's attributes from 37834the target OS. @var{thread-id} is a thread ID; 37835see @ref{thread-id syntax}. This 37836string may contain anything that the target OS thinks is interesting 37837for @value{GDBN} to tell the user about the thread. The string is 37838displayed in @value{GDBN}'s @code{info threads} display. Some 37839examples of possible thread extra info strings are @samp{Runnable}, or 37840@samp{Blocked on Mutex}. 37841 37842Reply: 37843@table @samp 37844@item @var{XX}@dots{} 37845Where @samp{@var{XX}@dots{}} is a hex encoding of @sc{ascii} data, 37846comprising the printable string containing the extra information about 37847the thread's attributes. 37848@end table 37849 37850(Note that the @code{qThreadExtraInfo} packet's name is separated from 37851the command by a @samp{,}, not a @samp{:}, contrary to the naming 37852conventions above. Please don't use this packet as a model for new 37853packets.) 37854 37855@item QTNotes 37856@itemx qTP 37857@itemx QTSave 37858@itemx qTsP 37859@itemx qTsV 37860@itemx QTStart 37861@itemx QTStop 37862@itemx QTEnable 37863@itemx QTDisable 37864@itemx QTinit 37865@itemx QTro 37866@itemx qTStatus 37867@itemx qTV 37868@itemx qTfSTM 37869@itemx qTsSTM 37870@itemx qTSTMat 37871@xref{Tracepoint Packets}. 37872 37873@item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length} 37874@cindex read special object, remote request 37875@cindex @samp{qXfer} packet 37876@anchor{qXfer read} 37877Read uninterpreted bytes from the target's special data area 37878identified by the keyword @var{object}. Request @var{length} bytes 37879starting at @var{offset} bytes into the data. The content and 37880encoding of @var{annex} is specific to @var{object}; it can supply 37881additional details about what data to access. 37882 37883Here are the specific requests of this form defined so far. All 37884@samp{qXfer:@var{object}:read:@dots{}} requests use the same reply 37885formats, listed below. 37886 37887@table @samp 37888@item qXfer:auxv:read::@var{offset},@var{length} 37889@anchor{qXfer auxiliary vector read} 37890Access the target's @dfn{auxiliary vector}. @xref{OS Information, 37891auxiliary vector}. Note @var{annex} must be empty. 37892 37893This packet is not probed by default; the remote stub must request it, 37894by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 37895 37896@item qXfer:btrace:read:@var{annex}:@var{offset},@var{length} 37897@anchor{qXfer btrace read} 37898 37899Return a description of the current branch trace. 37900@xref{Branch Trace Format}. The annex part of the generic @samp{qXfer} 37901packet may have one of the following values: 37902 37903@table @code 37904@item all 37905Returns all available branch trace. 37906 37907@item new 37908Returns all available branch trace if the branch trace changed since 37909the last read request. 37910@end table 37911 37912This packet is not probed by default; the remote stub must request it 37913by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 37914 37915@item qXfer:features:read:@var{annex}:@var{offset},@var{length} 37916@anchor{qXfer target description read} 37917Access the @dfn{target description}. @xref{Target Descriptions}. The 37918annex specifies which XML document to access. The main description is 37919always loaded from the @samp{target.xml} annex. 37920 37921This packet is not probed by default; the remote stub must request it, 37922by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 37923 37924@item qXfer:libraries:read:@var{annex}:@var{offset},@var{length} 37925@anchor{qXfer library list read} 37926Access the target's list of loaded libraries. @xref{Library List Format}. 37927The annex part of the generic @samp{qXfer} packet must be empty 37928(@pxref{qXfer read}). 37929 37930Targets which maintain a list of libraries in the program's memory do 37931not need to implement this packet; it is designed for platforms where 37932the operating system manages the list of loaded libraries. 37933 37934This packet is not probed by default; the remote stub must request it, 37935by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 37936 37937@item qXfer:libraries-svr4:read:@var{annex}:@var{offset},@var{length} 37938@anchor{qXfer svr4 library list read} 37939Access the target's list of loaded libraries when the target is an SVR4 37940platform. @xref{Library List Format for SVR4 Targets}. The annex part 37941of the generic @samp{qXfer} packet must be empty (@pxref{qXfer read}). 37942 37943This packet is optional for better performance on SVR4 targets. 37944@value{GDBN} uses memory read packets to read the SVR4 library list otherwise. 37945 37946This packet is not probed by default; the remote stub must request it, 37947by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 37948 37949@item qXfer:memory-map:read::@var{offset},@var{length} 37950@anchor{qXfer memory map read} 37951Access the target's @dfn{memory-map}. @xref{Memory Map Format}. The 37952annex part of the generic @samp{qXfer} packet must be empty 37953(@pxref{qXfer read}). 37954 37955This packet is not probed by default; the remote stub must request it, 37956by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 37957 37958@item qXfer:sdata:read::@var{offset},@var{length} 37959@anchor{qXfer sdata read} 37960 37961Read contents of the extra collected static tracepoint marker 37962information. The annex part of the generic @samp{qXfer} packet must 37963be empty (@pxref{qXfer read}). @xref{Tracepoint Actions,,Tracepoint 37964Action Lists}. 37965 37966This packet is not probed by default; the remote stub must request it, 37967by supplying an appropriate @samp{qSupported} response 37968(@pxref{qSupported}). 37969 37970@item qXfer:siginfo:read::@var{offset},@var{length} 37971@anchor{qXfer siginfo read} 37972Read contents of the extra signal information on the target 37973system. The annex part of the generic @samp{qXfer} packet must be 37974empty (@pxref{qXfer read}). 37975 37976This packet is not probed by default; the remote stub must request it, 37977by supplying an appropriate @samp{qSupported} response 37978(@pxref{qSupported}). 37979 37980@item qXfer:spu:read:@var{annex}:@var{offset},@var{length} 37981@anchor{qXfer spu read} 37982Read contents of an @code{spufs} file on the target system. The 37983annex specifies which file to read; it must be of the form 37984@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID 37985in the target process, and @var{name} identifes the @code{spufs} file 37986in that context to be accessed. 37987 37988This packet is not probed by default; the remote stub must request it, 37989by supplying an appropriate @samp{qSupported} response 37990(@pxref{qSupported}). 37991 37992@item qXfer:threads:read::@var{offset},@var{length} 37993@anchor{qXfer threads read} 37994Access the list of threads on target. @xref{Thread List Format}. The 37995annex part of the generic @samp{qXfer} packet must be empty 37996(@pxref{qXfer read}). 37997 37998This packet is not probed by default; the remote stub must request it, 37999by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 38000 38001@item qXfer:traceframe-info:read::@var{offset},@var{length} 38002@anchor{qXfer traceframe info read} 38003 38004Return a description of the current traceframe's contents. 38005@xref{Traceframe Info Format}. The annex part of the generic 38006@samp{qXfer} packet must be empty (@pxref{qXfer read}). 38007 38008This packet is not probed by default; the remote stub must request it, 38009by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 38010 38011@item qXfer:uib:read:@var{pc}:@var{offset},@var{length} 38012@anchor{qXfer unwind info block} 38013 38014Return the unwind information block for @var{pc}. This packet is used 38015on OpenVMS/ia64 to ask the kernel unwind information. 38016 38017This packet is not probed by default. 38018 38019@item qXfer:fdpic:read:@var{annex}:@var{offset},@var{length} 38020@anchor{qXfer fdpic loadmap read} 38021Read contents of @code{loadmap}s on the target system. The 38022annex, either @samp{exec} or @samp{interp}, specifies which @code{loadmap}, 38023executable @code{loadmap} or interpreter @code{loadmap} to read. 38024 38025This packet is not probed by default; the remote stub must request it, 38026by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 38027 38028@item qXfer:osdata:read::@var{offset},@var{length} 38029@anchor{qXfer osdata read} 38030Access the target's @dfn{operating system information}. 38031@xref{Operating System Information}. 38032 38033@end table 38034 38035Reply: 38036@table @samp 38037@item m @var{data} 38038Data @var{data} (@pxref{Binary Data}) has been read from the 38039target. There may be more data at a higher address (although 38040it is permitted to return @samp{m} even for the last valid 38041block of data, as long as at least one byte of data was read). 38042@var{data} may have fewer bytes than the @var{length} in the 38043request. 38044 38045@item l @var{data} 38046Data @var{data} (@pxref{Binary Data}) has been read from the target. 38047There is no more data to be read. @var{data} may have fewer bytes 38048than the @var{length} in the request. 38049 38050@item l 38051The @var{offset} in the request is at the end of the data. 38052There is no more data to be read. 38053 38054@item E00 38055The request was malformed, or @var{annex} was invalid. 38056 38057@item E @var{nn} 38058The offset was invalid, or there was an error encountered reading the data. 38059@var{nn} is a hex-encoded @code{errno} value. 38060 38061@item @w{} 38062An empty reply indicates the @var{object} string was not recognized by 38063the stub, or that the object does not support reading. 38064@end table 38065 38066@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{} 38067@cindex write data into object, remote request 38068@anchor{qXfer write} 38069Write uninterpreted bytes into the target's special data area 38070identified by the keyword @var{object}, starting at @var{offset} bytes 38071into the data. @var{data}@dots{} is the binary-encoded data 38072(@pxref{Binary Data}) to be written. The content and encoding of @var{annex} 38073is specific to @var{object}; it can supply additional details about what data 38074to access. 38075 38076Here are the specific requests of this form defined so far. All 38077@samp{qXfer:@var{object}:write:@dots{}} requests use the same reply 38078formats, listed below. 38079 38080@table @samp 38081@item qXfer:siginfo:write::@var{offset}:@var{data}@dots{} 38082@anchor{qXfer siginfo write} 38083Write @var{data} to the extra signal information on the target system. 38084The annex part of the generic @samp{qXfer} packet must be 38085empty (@pxref{qXfer write}). 38086 38087This packet is not probed by default; the remote stub must request it, 38088by supplying an appropriate @samp{qSupported} response 38089(@pxref{qSupported}). 38090 38091@item qXfer:spu:write:@var{annex}:@var{offset}:@var{data}@dots{} 38092@anchor{qXfer spu write} 38093Write @var{data} to an @code{spufs} file on the target system. The 38094annex specifies which file to write; it must be of the form 38095@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID 38096in the target process, and @var{name} identifes the @code{spufs} file 38097in that context to be accessed. 38098 38099This packet is not probed by default; the remote stub must request it, 38100by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 38101@end table 38102 38103Reply: 38104@table @samp 38105@item @var{nn} 38106@var{nn} (hex encoded) is the number of bytes written. 38107This may be fewer bytes than supplied in the request. 38108 38109@item E00 38110The request was malformed, or @var{annex} was invalid. 38111 38112@item E @var{nn} 38113The offset was invalid, or there was an error encountered writing the data. 38114@var{nn} is a hex-encoded @code{errno} value. 38115 38116@item @w{} 38117An empty reply indicates the @var{object} string was not 38118recognized by the stub, or that the object does not support writing. 38119@end table 38120 38121@item qXfer:@var{object}:@var{operation}:@dots{} 38122Requests of this form may be added in the future. When a stub does 38123not recognize the @var{object} keyword, or its support for 38124@var{object} does not recognize the @var{operation} keyword, the stub 38125must respond with an empty packet. 38126 38127@item qAttached:@var{pid} 38128@cindex query attached, remote request 38129@cindex @samp{qAttached} packet 38130Return an indication of whether the remote server attached to an 38131existing process or created a new process. When the multiprocess 38132protocol extensions are supported (@pxref{multiprocess extensions}), 38133@var{pid} is an integer in hexadecimal format identifying the target 38134process. Otherwise, @value{GDBN} will omit the @var{pid} field and 38135the query packet will be simplified as @samp{qAttached}. 38136 38137This query is used, for example, to know whether the remote process 38138should be detached or killed when a @value{GDBN} session is ended with 38139the @code{quit} command. 38140 38141Reply: 38142@table @samp 38143@item 1 38144The remote server attached to an existing process. 38145@item 0 38146The remote server created a new process. 38147@item E @var{NN} 38148A badly formed request or an error was encountered. 38149@end table 38150 38151@item Qbtrace:bts 38152Enable branch tracing for the current thread using bts tracing. 38153 38154Reply: 38155@table @samp 38156@item OK 38157Branch tracing has been enabled. 38158@item E.errtext 38159A badly formed request or an error was encountered. 38160@end table 38161 38162@item Qbtrace:off 38163Disable branch tracing for the current thread. 38164 38165Reply: 38166@table @samp 38167@item OK 38168Branch tracing has been disabled. 38169@item E.errtext 38170A badly formed request or an error was encountered. 38171@end table 38172 38173@end table 38174 38175@node Architecture-Specific Protocol Details 38176@section Architecture-Specific Protocol Details 38177 38178This section describes how the remote protocol is applied to specific 38179target architectures. Also see @ref{Standard Target Features}, for 38180details of XML target descriptions for each architecture. 38181 38182@menu 38183* ARM-Specific Protocol Details:: 38184* MIPS-Specific Protocol Details:: 38185@end menu 38186 38187@node ARM-Specific Protocol Details 38188@subsection @acronym{ARM}-specific Protocol Details 38189 38190@menu 38191* ARM Breakpoint Kinds:: 38192@end menu 38193 38194@node ARM Breakpoint Kinds 38195@subsubsection @acronym{ARM} Breakpoint Kinds 38196@cindex breakpoint kinds, @acronym{ARM} 38197 38198These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets. 38199 38200@table @r 38201 38202@item 2 3820316-bit Thumb mode breakpoint. 38204 38205@item 3 3820632-bit Thumb mode (Thumb-2) breakpoint. 38207 38208@item 4 3820932-bit @acronym{ARM} mode breakpoint. 38210 38211@end table 38212 38213@node MIPS-Specific Protocol Details 38214@subsection @acronym{MIPS}-specific Protocol Details 38215 38216@menu 38217* MIPS Register packet Format:: 38218* MIPS Breakpoint Kinds:: 38219@end menu 38220 38221@node MIPS Register packet Format 38222@subsubsection @acronym{MIPS} Register Packet Format 38223@cindex register packet format, @acronym{MIPS} 38224 38225The following @code{g}/@code{G} packets have previously been defined. 38226In the below, some thirty-two bit registers are transferred as 38227sixty-four bits. Those registers should be zero/sign extended (which?) 38228to fill the space allocated. Register bytes are transferred in target 38229byte order. The two nibbles within a register byte are transferred 38230most-significant -- least-significant. 38231 38232@table @r 38233 38234@item MIPS32 38235All registers are transferred as thirty-two bit quantities in the order: 3823632 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point 38237registers; fsr; fir; fp. 38238 38239@item MIPS64 38240All registers are transferred as sixty-four bit quantities (including 38241thirty-two bit registers such as @code{sr}). The ordering is the same 38242as @code{MIPS32}. 38243 38244@end table 38245 38246@node MIPS Breakpoint Kinds 38247@subsubsection @acronym{MIPS} Breakpoint Kinds 38248@cindex breakpoint kinds, @acronym{MIPS} 38249 38250These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets. 38251 38252@table @r 38253 38254@item 2 3825516-bit @acronym{MIPS16} mode breakpoint. 38256 38257@item 3 3825816-bit @acronym{microMIPS} mode breakpoint. 38259 38260@item 4 3826132-bit standard @acronym{MIPS} mode breakpoint. 38262 38263@item 5 3826432-bit @acronym{microMIPS} mode breakpoint. 38265 38266@end table 38267 38268@node Tracepoint Packets 38269@section Tracepoint Packets 38270@cindex tracepoint packets 38271@cindex packets, tracepoint 38272 38273Here we describe the packets @value{GDBN} uses to implement 38274tracepoints (@pxref{Tracepoints}). 38275 38276@table @samp 38277 38278@item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}[:F@var{flen}][:X@var{len},@var{bytes}]@r{[}-@r{]} 38279@cindex @samp{QTDP} packet 38280Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena} 38281is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then 38282the tracepoint is disabled. @var{step} is the tracepoint's step 38283count, and @var{pass} is its pass count. If an @samp{F} is present, 38284then the tracepoint is to be a fast tracepoint, and the @var{flen} is 38285the number of bytes that the target should copy elsewhere to make room 38286for the tracepoint. If an @samp{X} is present, it introduces a 38287tracepoint condition, which consists of a hexadecimal length, followed 38288by a comma and hex-encoded bytes, in a manner similar to action 38289encodings as described below. If the trailing @samp{-} is present, 38290further @samp{QTDP} packets will follow to specify this tracepoint's 38291actions. 38292 38293Replies: 38294@table @samp 38295@item OK 38296The packet was understood and carried out. 38297@item qRelocInsn 38298@xref{Tracepoint Packets,,Relocate instruction reply packet}. 38299@item @w{} 38300The packet was not recognized. 38301@end table 38302 38303@item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]} 38304Define actions to be taken when a tracepoint is hit. @var{n} and 38305@var{addr} must be the same as in the initial @samp{QTDP} packet for 38306this tracepoint. This packet may only be sent immediately after 38307another @samp{QTDP} packet that ended with a @samp{-}. If the 38308trailing @samp{-} is present, further @samp{QTDP} packets will follow, 38309specifying more actions for this tracepoint. 38310 38311In the series of action packets for a given tracepoint, at most one 38312can have an @samp{S} before its first @var{action}. If such a packet 38313is sent, it and the following packets define ``while-stepping'' 38314actions. Any prior packets define ordinary actions --- that is, those 38315taken when the tracepoint is first hit. If no action packet has an 38316@samp{S}, then all the packets in the series specify ordinary 38317tracepoint actions. 38318 38319The @samp{@var{action}@dots{}} portion of the packet is a series of 38320actions, concatenated without separators. Each action has one of the 38321following forms: 38322 38323@table @samp 38324 38325@item R @var{mask} 38326Collect the registers whose bits are set in @var{mask}. @var{mask} is 38327a hexadecimal number whose @var{i}'th bit is set if register number 38328@var{i} should be collected. (The least significant bit is numbered 38329zero.) Note that @var{mask} may be any number of digits long; it may 38330not fit in a 32-bit word. 38331 38332@item M @var{basereg},@var{offset},@var{len} 38333Collect @var{len} bytes of memory starting at the address in register 38334number @var{basereg}, plus @var{offset}. If @var{basereg} is 38335@samp{-1}, then the range has a fixed address: @var{offset} is the 38336address of the lowest byte to collect. The @var{basereg}, 38337@var{offset}, and @var{len} parameters are all unsigned hexadecimal 38338values (the @samp{-1} value for @var{basereg} is a special case). 38339 38340@item X @var{len},@var{expr} 38341Evaluate @var{expr}, whose length is @var{len}, and collect memory as 38342it directs. @var{expr} is an agent expression, as described in 38343@ref{Agent Expressions}. Each byte of the expression is encoded as a 38344two-digit hex number in the packet; @var{len} is the number of bytes 38345in the expression (and thus one-half the number of hex digits in the 38346packet). 38347 38348@end table 38349 38350Any number of actions may be packed together in a single @samp{QTDP} 38351packet, as long as the packet does not exceed the maximum packet 38352length (400 bytes, for many stubs). There may be only one @samp{R} 38353action per tracepoint, and it must precede any @samp{M} or @samp{X} 38354actions. Any registers referred to by @samp{M} and @samp{X} actions 38355must be collected by a preceding @samp{R} action. (The 38356``while-stepping'' actions are treated as if they were attached to a 38357separate tracepoint, as far as these restrictions are concerned.) 38358 38359Replies: 38360@table @samp 38361@item OK 38362The packet was understood and carried out. 38363@item qRelocInsn 38364@xref{Tracepoint Packets,,Relocate instruction reply packet}. 38365@item @w{} 38366The packet was not recognized. 38367@end table 38368 38369@item QTDPsrc:@var{n}:@var{addr}:@var{type}:@var{start}:@var{slen}:@var{bytes} 38370@cindex @samp{QTDPsrc} packet 38371Specify a source string of tracepoint @var{n} at address @var{addr}. 38372This is useful to get accurate reproduction of the tracepoints 38373originally downloaded at the beginning of the trace run. @var{type} 38374is the name of the tracepoint part, such as @samp{cond} for the 38375tracepoint's conditional expression (see below for a list of types), while 38376@var{bytes} is the string, encoded in hexadecimal. 38377 38378@var{start} is the offset of the @var{bytes} within the overall source 38379string, while @var{slen} is the total length of the source string. 38380This is intended for handling source strings that are longer than will 38381fit in a single packet. 38382@c Add detailed example when this info is moved into a dedicated 38383@c tracepoint descriptions section. 38384 38385The available string types are @samp{at} for the location, 38386@samp{cond} for the conditional, and @samp{cmd} for an action command. 38387@value{GDBN} sends a separate packet for each command in the action 38388list, in the same order in which the commands are stored in the list. 38389 38390The target does not need to do anything with source strings except 38391report them back as part of the replies to the @samp{qTfP}/@samp{qTsP} 38392query packets. 38393 38394Although this packet is optional, and @value{GDBN} will only send it 38395if the target replies with @samp{TracepointSource} @xref{General 38396Query Packets}, it makes both disconnected tracing and trace files 38397much easier to use. Otherwise the user must be careful that the 38398tracepoints in effect while looking at trace frames are identical to 38399the ones in effect during the trace run; even a small discrepancy 38400could cause @samp{tdump} not to work, or a particular trace frame not 38401be found. 38402 38403@item QTDV:@var{n}:@var{value} 38404@cindex define trace state variable, remote request 38405@cindex @samp{QTDV} packet 38406Create a new trace state variable, number @var{n}, with an initial 38407value of @var{value}, which is a 64-bit signed integer. Both @var{n} 38408and @var{value} are encoded as hexadecimal values. @value{GDBN} has 38409the option of not using this packet for initial values of zero; the 38410target should simply create the trace state variables as they are 38411mentioned in expressions. 38412 38413@item QTFrame:@var{n} 38414@cindex @samp{QTFrame} packet 38415Select the @var{n}'th tracepoint frame from the buffer, and use the 38416register and memory contents recorded there to answer subsequent 38417request packets from @value{GDBN}. 38418 38419A successful reply from the stub indicates that the stub has found the 38420requested frame. The response is a series of parts, concatenated 38421without separators, describing the frame we selected. Each part has 38422one of the following forms: 38423 38424@table @samp 38425@item F @var{f} 38426The selected frame is number @var{n} in the trace frame buffer; 38427@var{f} is a hexadecimal number. If @var{f} is @samp{-1}, then there 38428was no frame matching the criteria in the request packet. 38429 38430@item T @var{t} 38431The selected trace frame records a hit of tracepoint number @var{t}; 38432@var{t} is a hexadecimal number. 38433 38434@end table 38435 38436@item QTFrame:pc:@var{addr} 38437Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the 38438currently selected frame whose PC is @var{addr}; 38439@var{addr} is a hexadecimal number. 38440 38441@item QTFrame:tdp:@var{t} 38442Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the 38443currently selected frame that is a hit of tracepoint @var{t}; @var{t} 38444is a hexadecimal number. 38445 38446@item QTFrame:range:@var{start}:@var{end} 38447Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the 38448currently selected frame whose PC is between @var{start} (inclusive) 38449and @var{end} (inclusive); @var{start} and @var{end} are hexadecimal 38450numbers. 38451 38452@item QTFrame:outside:@var{start}:@var{end} 38453Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first 38454frame @emph{outside} the given range of addresses (exclusive). 38455 38456@item qTMinFTPILen 38457@cindex @samp{qTMinFTPILen} packet 38458This packet requests the minimum length of instruction at which a fast 38459tracepoint (@pxref{Set Tracepoints}) may be placed. For instance, on 38460the 32-bit x86 architecture, it is possible to use a 4-byte jump, but 38461it depends on the target system being able to create trampolines in 38462the first 64K of memory, which might or might not be possible for that 38463system. So the reply to this packet will be 4 if it is able to 38464arrange for that. 38465 38466Replies: 38467 38468@table @samp 38469@item 0 38470The minimum instruction length is currently unknown. 38471@item @var{length} 38472The minimum instruction length is @var{length}, where @var{length} is greater 38473or equal to 1. @var{length} is a hexadecimal number. A reply of 1 means 38474that a fast tracepoint may be placed on any instruction regardless of size. 38475@item E 38476An error has occurred. 38477@item @w{} 38478An empty reply indicates that the request is not supported by the stub. 38479@end table 38480 38481@item QTStart 38482@cindex @samp{QTStart} packet 38483Begin the tracepoint experiment. Begin collecting data from 38484tracepoint hits in the trace frame buffer. This packet supports the 38485@samp{qRelocInsn} reply (@pxref{Tracepoint Packets,,Relocate 38486instruction reply packet}). 38487 38488@item QTStop 38489@cindex @samp{QTStop} packet 38490End the tracepoint experiment. Stop collecting trace frames. 38491 38492@item QTEnable:@var{n}:@var{addr} 38493@anchor{QTEnable} 38494@cindex @samp{QTEnable} packet 38495Enable tracepoint @var{n} at address @var{addr} in a started tracepoint 38496experiment. If the tracepoint was previously disabled, then collection 38497of data from it will resume. 38498 38499@item QTDisable:@var{n}:@var{addr} 38500@anchor{QTDisable} 38501@cindex @samp{QTDisable} packet 38502Disable tracepoint @var{n} at address @var{addr} in a started tracepoint 38503experiment. No more data will be collected from the tracepoint unless 38504@samp{QTEnable:@var{n}:@var{addr}} is subsequently issued. 38505 38506@item QTinit 38507@cindex @samp{QTinit} packet 38508Clear the table of tracepoints, and empty the trace frame buffer. 38509 38510@item QTro:@var{start1},@var{end1}:@var{start2},@var{end2}:@dots{} 38511@cindex @samp{QTro} packet 38512Establish the given ranges of memory as ``transparent''. The stub 38513will answer requests for these ranges from memory's current contents, 38514if they were not collected as part of the tracepoint hit. 38515 38516@value{GDBN} uses this to mark read-only regions of memory, like those 38517containing program code. Since these areas never change, they should 38518still have the same contents they did when the tracepoint was hit, so 38519there's no reason for the stub to refuse to provide their contents. 38520 38521@item QTDisconnected:@var{value} 38522@cindex @samp{QTDisconnected} packet 38523Set the choice to what to do with the tracing run when @value{GDBN} 38524disconnects from the target. A @var{value} of 1 directs the target to 38525continue the tracing run, while 0 tells the target to stop tracing if 38526@value{GDBN} is no longer in the picture. 38527 38528@item qTStatus 38529@cindex @samp{qTStatus} packet 38530Ask the stub if there is a trace experiment running right now. 38531 38532The reply has the form: 38533 38534@table @samp 38535 38536@item T@var{running}@r{[};@var{field}@r{]}@dots{} 38537@var{running} is a single digit @code{1} if the trace is presently 38538running, or @code{0} if not. It is followed by semicolon-separated 38539optional fields that an agent may use to report additional status. 38540 38541@end table 38542 38543If the trace is not running, the agent may report any of several 38544explanations as one of the optional fields: 38545 38546@table @samp 38547 38548@item tnotrun:0 38549No trace has been run yet. 38550 38551@item tstop[:@var{text}]:0 38552The trace was stopped by a user-originated stop command. The optional 38553@var{text} field is a user-supplied string supplied as part of the 38554stop command (for instance, an explanation of why the trace was 38555stopped manually). It is hex-encoded. 38556 38557@item tfull:0 38558The trace stopped because the trace buffer filled up. 38559 38560@item tdisconnected:0 38561The trace stopped because @value{GDBN} disconnected from the target. 38562 38563@item tpasscount:@var{tpnum} 38564The trace stopped because tracepoint @var{tpnum} exceeded its pass count. 38565 38566@item terror:@var{text}:@var{tpnum} 38567The trace stopped because tracepoint @var{tpnum} had an error. The 38568string @var{text} is available to describe the nature of the error 38569(for instance, a divide by zero in the condition expression). 38570@var{text} is hex encoded. 38571 38572@item tunknown:0 38573The trace stopped for some other reason. 38574 38575@end table 38576 38577Additional optional fields supply statistical and other information. 38578Although not required, they are extremely useful for users monitoring 38579the progress of a trace run. If a trace has stopped, and these 38580numbers are reported, they must reflect the state of the just-stopped 38581trace. 38582 38583@table @samp 38584 38585@item tframes:@var{n} 38586The number of trace frames in the buffer. 38587 38588@item tcreated:@var{n} 38589The total number of trace frames created during the run. This may 38590be larger than the trace frame count, if the buffer is circular. 38591 38592@item tsize:@var{n} 38593The total size of the trace buffer, in bytes. 38594 38595@item tfree:@var{n} 38596The number of bytes still unused in the buffer. 38597 38598@item circular:@var{n} 38599The value of the circular trace buffer flag. @code{1} means that the 38600trace buffer is circular and old trace frames will be discarded if 38601necessary to make room, @code{0} means that the trace buffer is linear 38602and may fill up. 38603 38604@item disconn:@var{n} 38605The value of the disconnected tracing flag. @code{1} means that 38606tracing will continue after @value{GDBN} disconnects, @code{0} means 38607that the trace run will stop. 38608 38609@end table 38610 38611@item qTP:@var{tp}:@var{addr} 38612@cindex tracepoint status, remote request 38613@cindex @samp{qTP} packet 38614Ask the stub for the current state of tracepoint number @var{tp} at 38615address @var{addr}. 38616 38617Replies: 38618@table @samp 38619@item V@var{hits}:@var{usage} 38620The tracepoint has been hit @var{hits} times so far during the trace 38621run, and accounts for @var{usage} in the trace buffer. Note that 38622@code{while-stepping} steps are not counted as separate hits, but the 38623steps' space consumption is added into the usage number. 38624 38625@end table 38626 38627@item qTV:@var{var} 38628@cindex trace state variable value, remote request 38629@cindex @samp{qTV} packet 38630Ask the stub for the value of the trace state variable number @var{var}. 38631 38632Replies: 38633@table @samp 38634@item V@var{value} 38635The value of the variable is @var{value}. This will be the current 38636value of the variable if the user is examining a running target, or a 38637saved value if the variable was collected in the trace frame that the 38638user is looking at. Note that multiple requests may result in 38639different reply values, such as when requesting values while the 38640program is running. 38641 38642@item U 38643The value of the variable is unknown. This would occur, for example, 38644if the user is examining a trace frame in which the requested variable 38645was not collected. 38646@end table 38647 38648@item qTfP 38649@cindex @samp{qTfP} packet 38650@itemx qTsP 38651@cindex @samp{qTsP} packet 38652These packets request data about tracepoints that are being used by 38653the target. @value{GDBN} sends @code{qTfP} to get the first piece 38654of data, and multiple @code{qTsP} to get additional pieces. Replies 38655to these packets generally take the form of the @code{QTDP} packets 38656that define tracepoints. (FIXME add detailed syntax) 38657 38658@item qTfV 38659@cindex @samp{qTfV} packet 38660@itemx qTsV 38661@cindex @samp{qTsV} packet 38662These packets request data about trace state variables that are on the 38663target. @value{GDBN} sends @code{qTfV} to get the first vari of data, 38664and multiple @code{qTsV} to get additional variables. Replies to 38665these packets follow the syntax of the @code{QTDV} packets that define 38666trace state variables. 38667 38668@item qTfSTM 38669@itemx qTsSTM 38670@anchor{qTfSTM} 38671@anchor{qTsSTM} 38672@cindex @samp{qTfSTM} packet 38673@cindex @samp{qTsSTM} packet 38674These packets request data about static tracepoint markers that exist 38675in the target program. @value{GDBN} sends @code{qTfSTM} to get the 38676first piece of data, and multiple @code{qTsSTM} to get additional 38677pieces. Replies to these packets take the following form: 38678 38679Reply: 38680@table @samp 38681@item m @var{address}:@var{id}:@var{extra} 38682A single marker 38683@item m @var{address}:@var{id}:@var{extra},@var{address}:@var{id}:@var{extra}@dots{} 38684a comma-separated list of markers 38685@item l 38686(lower case letter @samp{L}) denotes end of list. 38687@item E @var{nn} 38688An error occurred. @var{nn} are hex digits. 38689@item @w{} 38690An empty reply indicates that the request is not supported by the 38691stub. 38692@end table 38693 38694@var{address} is encoded in hex. 38695@var{id} and @var{extra} are strings encoded in hex. 38696 38697In response to each query, the target will reply with a list of one or 38698more markers, separated by commas. @value{GDBN} will respond to each 38699reply with a request for more markers (using the @samp{qs} form of the 38700query), until the target responds with @samp{l} (lower-case ell, for 38701@dfn{last}). 38702 38703@item qTSTMat:@var{address} 38704@anchor{qTSTMat} 38705@cindex @samp{qTSTMat} packet 38706This packets requests data about static tracepoint markers in the 38707target program at @var{address}. Replies to this packet follow the 38708syntax of the @samp{qTfSTM} and @code{qTsSTM} packets that list static 38709tracepoint markers. 38710 38711@item QTSave:@var{filename} 38712@cindex @samp{QTSave} packet 38713This packet directs the target to save trace data to the file name 38714@var{filename} in the target's filesystem. @var{filename} is encoded 38715as a hex string; the interpretation of the file name (relative vs 38716absolute, wild cards, etc) is up to the target. 38717 38718@item qTBuffer:@var{offset},@var{len} 38719@cindex @samp{qTBuffer} packet 38720Return up to @var{len} bytes of the current contents of trace buffer, 38721starting at @var{offset}. The trace buffer is treated as if it were 38722a contiguous collection of traceframes, as per the trace file format. 38723The reply consists as many hex-encoded bytes as the target can deliver 38724in a packet; it is not an error to return fewer than were asked for. 38725A reply consisting of just @code{l} indicates that no bytes are 38726available. 38727 38728@item QTBuffer:circular:@var{value} 38729This packet directs the target to use a circular trace buffer if 38730@var{value} is 1, or a linear buffer if the value is 0. 38731 38732@item QTBuffer:size:@var{size} 38733@anchor{QTBuffer-size} 38734@cindex @samp{QTBuffer size} packet 38735This packet directs the target to make the trace buffer be of size 38736@var{size} if possible. A value of @code{-1} tells the target to 38737use whatever size it prefers. 38738 38739@item QTNotes:@r{[}@var{type}:@var{text}@r{]}@r{[};@var{type}:@var{text}@r{]}@dots{} 38740@cindex @samp{QTNotes} packet 38741This packet adds optional textual notes to the trace run. Allowable 38742types include @code{user}, @code{notes}, and @code{tstop}, the 38743@var{text} fields are arbitrary strings, hex-encoded. 38744 38745@end table 38746 38747@subsection Relocate instruction reply packet 38748When installing fast tracepoints in memory, the target may need to 38749relocate the instruction currently at the tracepoint address to a 38750different address in memory. For most instructions, a simple copy is 38751enough, but, for example, call instructions that implicitly push the 38752return address on the stack, and relative branches or other 38753PC-relative instructions require offset adjustment, so that the effect 38754of executing the instruction at a different address is the same as if 38755it had executed in the original location. 38756 38757In response to several of the tracepoint packets, the target may also 38758respond with a number of intermediate @samp{qRelocInsn} request 38759packets before the final result packet, to have @value{GDBN} handle 38760this relocation operation. If a packet supports this mechanism, its 38761documentation will explicitly say so. See for example the above 38762descriptions for the @samp{QTStart} and @samp{QTDP} packets. The 38763format of the request is: 38764 38765@table @samp 38766@item qRelocInsn:@var{from};@var{to} 38767 38768This requests @value{GDBN} to copy instruction at address @var{from} 38769to address @var{to}, possibly adjusted so that executing the 38770instruction at @var{to} has the same effect as executing it at 38771@var{from}. @value{GDBN} writes the adjusted instruction to target 38772memory starting at @var{to}. 38773@end table 38774 38775Replies: 38776@table @samp 38777@item qRelocInsn:@var{adjusted_size} 38778Informs the stub the relocation is complete. @var{adjusted_size} is 38779the length in bytes of resulting relocated instruction sequence. 38780@item E @var{NN} 38781A badly formed request was detected, or an error was encountered while 38782relocating the instruction. 38783@end table 38784 38785@node Host I/O Packets 38786@section Host I/O Packets 38787@cindex Host I/O, remote protocol 38788@cindex file transfer, remote protocol 38789 38790The @dfn{Host I/O} packets allow @value{GDBN} to perform I/O 38791operations on the far side of a remote link. For example, Host I/O is 38792used to upload and download files to a remote target with its own 38793filesystem. Host I/O uses the same constant values and data structure 38794layout as the target-initiated File-I/O protocol. However, the 38795Host I/O packets are structured differently. The target-initiated 38796protocol relies on target memory to store parameters and buffers. 38797Host I/O requests are initiated by @value{GDBN}, and the 38798target's memory is not involved. @xref{File-I/O Remote Protocol 38799Extension}, for more details on the target-initiated protocol. 38800 38801The Host I/O request packets all encode a single operation along with 38802its arguments. They have this format: 38803 38804@table @samp 38805 38806@item vFile:@var{operation}: @var{parameter}@dots{} 38807@var{operation} is the name of the particular request; the target 38808should compare the entire packet name up to the second colon when checking 38809for a supported operation. The format of @var{parameter} depends on 38810the operation. Numbers are always passed in hexadecimal. Negative 38811numbers have an explicit minus sign (i.e.@: two's complement is not 38812used). Strings (e.g.@: filenames) are encoded as a series of 38813hexadecimal bytes. The last argument to a system call may be a 38814buffer of escaped binary data (@pxref{Binary Data}). 38815 38816@end table 38817 38818The valid responses to Host I/O packets are: 38819 38820@table @samp 38821 38822@item F @var{result} [, @var{errno}] [; @var{attachment}] 38823@var{result} is the integer value returned by this operation, usually 38824non-negative for success and -1 for errors. If an error has occured, 38825@var{errno} will be included in the result. @var{errno} will have a 38826value defined by the File-I/O protocol (@pxref{Errno Values}). For 38827operations which return data, @var{attachment} supplies the data as a 38828binary buffer. Binary buffers in response packets are escaped in the 38829normal way (@pxref{Binary Data}). See the individual packet 38830documentation for the interpretation of @var{result} and 38831@var{attachment}. 38832 38833@item @w{} 38834An empty response indicates that this operation is not recognized. 38835 38836@end table 38837 38838These are the supported Host I/O operations: 38839 38840@table @samp 38841@item vFile:open: @var{pathname}, @var{flags}, @var{mode} 38842Open a file at @var{pathname} and return a file descriptor for it, or 38843return -1 if an error occurs. @var{pathname} is a string, 38844@var{flags} is an integer indicating a mask of open flags 38845(@pxref{Open Flags}), and @var{mode} is an integer indicating a mask 38846of mode bits to use if the file is created (@pxref{mode_t Values}). 38847@xref{open}, for details of the open flags and mode values. 38848 38849@item vFile:close: @var{fd} 38850Close the open file corresponding to @var{fd} and return 0, or 38851-1 if an error occurs. 38852 38853@item vFile:pread: @var{fd}, @var{count}, @var{offset} 38854Read data from the open file corresponding to @var{fd}. Up to 38855@var{count} bytes will be read from the file, starting at @var{offset} 38856relative to the start of the file. The target may read fewer bytes; 38857common reasons include packet size limits and an end-of-file 38858condition. The number of bytes read is returned. Zero should only be 38859returned for a successful read at the end of the file, or if 38860@var{count} was zero. 38861 38862The data read should be returned as a binary attachment on success. 38863If zero bytes were read, the response should include an empty binary 38864attachment (i.e.@: a trailing semicolon). The return value is the 38865number of target bytes read; the binary attachment may be longer if 38866some characters were escaped. 38867 38868@item vFile:pwrite: @var{fd}, @var{offset}, @var{data} 38869Write @var{data} (a binary buffer) to the open file corresponding 38870to @var{fd}. Start the write at @var{offset} from the start of the 38871file. Unlike many @code{write} system calls, there is no 38872separate @var{count} argument; the length of @var{data} in the 38873packet is used. @samp{vFile:write} returns the number of bytes written, 38874which may be shorter than the length of @var{data}, or -1 if an 38875error occurred. 38876 38877@item vFile:unlink: @var{pathname} 38878Delete the file at @var{pathname} on the target. Return 0, 38879or -1 if an error occurs. @var{pathname} is a string. 38880 38881@item vFile:readlink: @var{filename} 38882Read value of symbolic link @var{filename} on the target. Return 38883the number of bytes read, or -1 if an error occurs. 38884 38885The data read should be returned as a binary attachment on success. 38886If zero bytes were read, the response should include an empty binary 38887attachment (i.e.@: a trailing semicolon). The return value is the 38888number of target bytes read; the binary attachment may be longer if 38889some characters were escaped. 38890 38891@end table 38892 38893@node Interrupts 38894@section Interrupts 38895@cindex interrupts (remote protocol) 38896 38897When a program on the remote target is running, @value{GDBN} may 38898attempt to interrupt it by sending a @samp{Ctrl-C}, @code{BREAK} or 38899a @code{BREAK} followed by @code{g}, 38900control of which is specified via @value{GDBN}'s @samp{interrupt-sequence}. 38901 38902The precise meaning of @code{BREAK} is defined by the transport 38903mechanism and may, in fact, be undefined. @value{GDBN} does not 38904currently define a @code{BREAK} mechanism for any of the network 38905interfaces except for TCP, in which case @value{GDBN} sends the 38906@code{telnet} BREAK sequence. 38907 38908@samp{Ctrl-C}, on the other hand, is defined and implemented for all 38909transport mechanisms. It is represented by sending the single byte 38910@code{0x03} without any of the usual packet overhead described in 38911the Overview section (@pxref{Overview}). When a @code{0x03} byte is 38912transmitted as part of a packet, it is considered to be packet data 38913and does @emph{not} represent an interrupt. E.g., an @samp{X} packet 38914(@pxref{X packet}), used for binary downloads, may include an unescaped 38915@code{0x03} as part of its packet. 38916 38917@code{BREAK} followed by @code{g} is also known as Magic SysRq g. 38918When Linux kernel receives this sequence from serial port, 38919it stops execution and connects to gdb. 38920 38921Stubs are not required to recognize these interrupt mechanisms and the 38922precise meaning associated with receipt of the interrupt is 38923implementation defined. If the target supports debugging of multiple 38924threads and/or processes, it should attempt to interrupt all 38925currently-executing threads and processes. 38926If the stub is successful at interrupting the 38927running program, it should send one of the stop 38928reply packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result 38929of successfully stopping the program in all-stop mode, and a stop reply 38930for each stopped thread in non-stop mode. 38931Interrupts received while the 38932program is stopped are discarded. 38933 38934@node Notification Packets 38935@section Notification Packets 38936@cindex notification packets 38937@cindex packets, notification 38938 38939The @value{GDBN} remote serial protocol includes @dfn{notifications}, 38940packets that require no acknowledgment. Both the GDB and the stub 38941may send notifications (although the only notifications defined at 38942present are sent by the stub). Notifications carry information 38943without incurring the round-trip latency of an acknowledgment, and so 38944are useful for low-impact communications where occasional packet loss 38945is not a problem. 38946 38947A notification packet has the form @samp{% @var{data} # 38948@var{checksum}}, where @var{data} is the content of the notification, 38949and @var{checksum} is a checksum of @var{data}, computed and formatted 38950as for ordinary @value{GDBN} packets. A notification's @var{data} 38951never contains @samp{$}, @samp{%} or @samp{#} characters. Upon 38952receiving a notification, the recipient sends no @samp{+} or @samp{-} 38953to acknowledge the notification's receipt or to report its corruption. 38954 38955Every notification's @var{data} begins with a name, which contains no 38956colon characters, followed by a colon character. 38957 38958Recipients should silently ignore corrupted notifications and 38959notifications they do not understand. Recipients should restart 38960timeout periods on receipt of a well-formed notification, whether or 38961not they understand it. 38962 38963Senders should only send the notifications described here when this 38964protocol description specifies that they are permitted. In the 38965future, we may extend the protocol to permit existing notifications in 38966new contexts; this rule helps older senders avoid confusing newer 38967recipients. 38968 38969(Older versions of @value{GDBN} ignore bytes received until they see 38970the @samp{$} byte that begins an ordinary packet, so new stubs may 38971transmit notifications without fear of confusing older clients. There 38972are no notifications defined for @value{GDBN} to send at the moment, but we 38973assume that most older stubs would ignore them, as well.) 38974 38975Each notification is comprised of three parts: 38976@table @samp 38977@item @var{name}:@var{event} 38978The notification packet is sent by the side that initiates the 38979exchange (currently, only the stub does that), with @var{event} 38980carrying the specific information about the notification. 38981@var{name} is the name of the notification. 38982@item @var{ack} 38983The acknowledge sent by the other side, usually @value{GDBN}, to 38984acknowledge the exchange and request the event. 38985@end table 38986 38987The purpose of an asynchronous notification mechanism is to report to 38988@value{GDBN} that something interesting happened in the remote stub. 38989 38990The remote stub may send notification @var{name}:@var{event} 38991at any time, but @value{GDBN} acknowledges the notification when 38992appropriate. The notification event is pending before @value{GDBN} 38993acknowledges. Only one notification at a time may be pending; if 38994additional events occur before @value{GDBN} has acknowledged the 38995previous notification, they must be queued by the stub for later 38996synchronous transmission in response to @var{ack} packets from 38997@value{GDBN}. Because the notification mechanism is unreliable, 38998the stub is permitted to resend a notification if it believes 38999@value{GDBN} may not have received it. 39000 39001Specifically, notifications may appear when @value{GDBN} is not 39002otherwise reading input from the stub, or when @value{GDBN} is 39003expecting to read a normal synchronous response or a 39004@samp{+}/@samp{-} acknowledgment to a packet it has sent. 39005Notification packets are distinct from any other communication from 39006the stub so there is no ambiguity. 39007 39008After receiving a notification, @value{GDBN} shall acknowledge it by 39009sending a @var{ack} packet as a regular, synchronous request to the 39010stub. Such acknowledgment is not required to happen immediately, as 39011@value{GDBN} is permitted to send other, unrelated packets to the 39012stub first, which the stub should process normally. 39013 39014Upon receiving a @var{ack} packet, if the stub has other queued 39015events to report to @value{GDBN}, it shall respond by sending a 39016normal @var{event}. @value{GDBN} shall then send another @var{ack} 39017packet to solicit further responses; again, it is permitted to send 39018other, unrelated packets as well which the stub should process 39019normally. 39020 39021If the stub receives a @var{ack} packet and there are no additional 39022@var{event} to report, the stub shall return an @samp{OK} response. 39023At this point, @value{GDBN} has finished processing a notification 39024and the stub has completed sending any queued events. @value{GDBN} 39025won't accept any new notifications until the final @samp{OK} is 39026received . If further notification events occur, the stub shall send 39027a new notification, @value{GDBN} shall accept the notification, and 39028the process shall be repeated. 39029 39030The process of asynchronous notification can be illustrated by the 39031following example: 39032@smallexample 39033<- @code{%%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;} 39034@code{...} 39035-> @code{vStopped} 39036<- @code{T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;} 39037-> @code{vStopped} 39038<- @code{T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;} 39039-> @code{vStopped} 39040<- @code{OK} 39041@end smallexample 39042 39043The following notifications are defined: 39044@multitable @columnfractions 0.12 0.12 0.38 0.38 39045 39046@item Notification 39047@tab Ack 39048@tab Event 39049@tab Description 39050 39051@item Stop 39052@tab vStopped 39053@tab @var{reply}. The @var{reply} has the form of a stop reply, as 39054described in @ref{Stop Reply Packets}. Refer to @ref{Remote Non-Stop}, 39055for information on how these notifications are acknowledged by 39056@value{GDBN}. 39057@tab Report an asynchronous stop event in non-stop mode. 39058 39059@end multitable 39060 39061@node Remote Non-Stop 39062@section Remote Protocol Support for Non-Stop Mode 39063 39064@value{GDBN}'s remote protocol supports non-stop debugging of 39065multi-threaded programs, as described in @ref{Non-Stop Mode}. If the stub 39066supports non-stop mode, it should report that to @value{GDBN} by including 39067@samp{QNonStop+} in its @samp{qSupported} response (@pxref{qSupported}). 39068 39069@value{GDBN} typically sends a @samp{QNonStop} packet only when 39070establishing a new connection with the stub. Entering non-stop mode 39071does not alter the state of any currently-running threads, but targets 39072must stop all threads in any already-attached processes when entering 39073all-stop mode. @value{GDBN} uses the @samp{?} packet as necessary to 39074probe the target state after a mode change. 39075 39076In non-stop mode, when an attached process encounters an event that 39077would otherwise be reported with a stop reply, it uses the 39078asynchronous notification mechanism (@pxref{Notification Packets}) to 39079inform @value{GDBN}. In contrast to all-stop mode, where all threads 39080in all processes are stopped when a stop reply is sent, in non-stop 39081mode only the thread reporting the stop event is stopped. That is, 39082when reporting a @samp{S} or @samp{T} response to indicate completion 39083of a step operation, hitting a breakpoint, or a fault, only the 39084affected thread is stopped; any other still-running threads continue 39085to run. When reporting a @samp{W} or @samp{X} response, all running 39086threads belonging to other attached processes continue to run. 39087 39088In non-stop mode, the target shall respond to the @samp{?} packet as 39089follows. First, any incomplete stop reply notification/@samp{vStopped} 39090sequence in progress is abandoned. The target must begin a new 39091sequence reporting stop events for all stopped threads, whether or not 39092it has previously reported those events to @value{GDBN}. The first 39093stop reply is sent as a synchronous reply to the @samp{?} packet, and 39094subsequent stop replies are sent as responses to @samp{vStopped} packets 39095using the mechanism described above. The target must not send 39096asynchronous stop reply notifications until the sequence is complete. 39097If all threads are running when the target receives the @samp{?} packet, 39098or if the target is not attached to any process, it shall respond 39099@samp{OK}. 39100 39101@node Packet Acknowledgment 39102@section Packet Acknowledgment 39103 39104@cindex acknowledgment, for @value{GDBN} remote 39105@cindex packet acknowledgment, for @value{GDBN} remote 39106By default, when either the host or the target machine receives a packet, 39107the first response expected is an acknowledgment: either @samp{+} (to indicate 39108the package was received correctly) or @samp{-} (to request retransmission). 39109This mechanism allows the @value{GDBN} remote protocol to operate over 39110unreliable transport mechanisms, such as a serial line. 39111 39112In cases where the transport mechanism is itself reliable (such as a pipe or 39113TCP connection), the @samp{+}/@samp{-} acknowledgments are redundant. 39114It may be desirable to disable them in that case to reduce communication 39115overhead, or for other reasons. This can be accomplished by means of the 39116@samp{QStartNoAckMode} packet; @pxref{QStartNoAckMode}. 39117 39118When in no-acknowledgment mode, neither the stub nor @value{GDBN} shall send or 39119expect @samp{+}/@samp{-} protocol acknowledgments. The packet 39120and response format still includes the normal checksum, as described in 39121@ref{Overview}, but the checksum may be ignored by the receiver. 39122 39123If the stub supports @samp{QStartNoAckMode} and prefers to operate in 39124no-acknowledgment mode, it should report that to @value{GDBN} 39125by including @samp{QStartNoAckMode+} in its response to @samp{qSupported}; 39126@pxref{qSupported}. 39127If @value{GDBN} also supports @samp{QStartNoAckMode} and it has not been 39128disabled via the @code{set remote noack-packet off} command 39129(@pxref{Remote Configuration}), 39130@value{GDBN} may then send a @samp{QStartNoAckMode} packet to the stub. 39131Only then may the stub actually turn off packet acknowledgments. 39132@value{GDBN} sends a final @samp{+} acknowledgment of the stub's @samp{OK} 39133response, which can be safely ignored by the stub. 39134 39135Note that @code{set remote noack-packet} command only affects negotiation 39136between @value{GDBN} and the stub when subsequent connections are made; 39137it does not affect the protocol acknowledgment state for any current 39138connection. 39139Since @samp{+}/@samp{-} acknowledgments are enabled by default when a 39140new connection is established, 39141there is also no protocol request to re-enable the acknowledgments 39142for the current connection, once disabled. 39143 39144@node Examples 39145@section Examples 39146 39147Example sequence of a target being re-started. Notice how the restart 39148does not get any direct output: 39149 39150@smallexample 39151-> @code{R00} 39152<- @code{+} 39153@emph{target restarts} 39154-> @code{?} 39155<- @code{+} 39156<- @code{T001:1234123412341234} 39157-> @code{+} 39158@end smallexample 39159 39160Example sequence of a target being stepped by a single instruction: 39161 39162@smallexample 39163-> @code{G1445@dots{}} 39164<- @code{+} 39165-> @code{s} 39166<- @code{+} 39167@emph{time passes} 39168<- @code{T001:1234123412341234} 39169-> @code{+} 39170-> @code{g} 39171<- @code{+} 39172<- @code{1455@dots{}} 39173-> @code{+} 39174@end smallexample 39175 39176@node File-I/O Remote Protocol Extension 39177@section File-I/O Remote Protocol Extension 39178@cindex File-I/O remote protocol extension 39179 39180@menu 39181* File-I/O Overview:: 39182* Protocol Basics:: 39183* The F Request Packet:: 39184* The F Reply Packet:: 39185* The Ctrl-C Message:: 39186* Console I/O:: 39187* List of Supported Calls:: 39188* Protocol-specific Representation of Datatypes:: 39189* Constants:: 39190* File-I/O Examples:: 39191@end menu 39192 39193@node File-I/O Overview 39194@subsection File-I/O Overview 39195@cindex file-i/o overview 39196 39197The @dfn{File I/O remote protocol extension} (short: File-I/O) allows the 39198target to use the host's file system and console I/O to perform various 39199system calls. System calls on the target system are translated into a 39200remote protocol packet to the host system, which then performs the needed 39201actions and returns a response packet to the target system. 39202This simulates file system operations even on targets that lack file systems. 39203 39204The protocol is defined to be independent of both the host and target systems. 39205It uses its own internal representation of datatypes and values. Both 39206@value{GDBN} and the target's @value{GDBN} stub are responsible for 39207translating the system-dependent value representations into the internal 39208protocol representations when data is transmitted. 39209 39210The communication is synchronous. A system call is possible only when 39211@value{GDBN} is waiting for a response from the @samp{C}, @samp{c}, @samp{S} 39212or @samp{s} packets. While @value{GDBN} handles the request for a system call, 39213the target is stopped to allow deterministic access to the target's 39214memory. Therefore File-I/O is not interruptible by target signals. On 39215the other hand, it is possible to interrupt File-I/O by a user interrupt 39216(@samp{Ctrl-C}) within @value{GDBN}. 39217 39218The target's request to perform a host system call does not finish 39219the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action. That means, 39220after finishing the system call, the target returns to continuing the 39221previous activity (continue, step). No additional continue or step 39222request from @value{GDBN} is required. 39223 39224@smallexample 39225(@value{GDBP}) continue 39226 <- target requests 'system call X' 39227 target is stopped, @value{GDBN} executes system call 39228 -> @value{GDBN} returns result 39229 ... target continues, @value{GDBN} returns to wait for the target 39230 <- target hits breakpoint and sends a Txx packet 39231@end smallexample 39232 39233The protocol only supports I/O on the console and to regular files on 39234the host file system. Character or block special devices, pipes, 39235named pipes, sockets or any other communication method on the host 39236system are not supported by this protocol. 39237 39238File I/O is not supported in non-stop mode. 39239 39240@node Protocol Basics 39241@subsection Protocol Basics 39242@cindex protocol basics, file-i/o 39243 39244The File-I/O protocol uses the @code{F} packet as the request as well 39245as reply packet. Since a File-I/O system call can only occur when 39246@value{GDBN} is waiting for a response from the continuing or stepping target, 39247the File-I/O request is a reply that @value{GDBN} has to expect as a result 39248of a previous @samp{C}, @samp{c}, @samp{S} or @samp{s} packet. 39249This @code{F} packet contains all information needed to allow @value{GDBN} 39250to call the appropriate host system call: 39251 39252@itemize @bullet 39253@item 39254A unique identifier for the requested system call. 39255 39256@item 39257All parameters to the system call. Pointers are given as addresses 39258in the target memory address space. Pointers to strings are given as 39259pointer/length pair. Numerical values are given as they are. 39260Numerical control flags are given in a protocol-specific representation. 39261 39262@end itemize 39263 39264At this point, @value{GDBN} has to perform the following actions. 39265 39266@itemize @bullet 39267@item 39268If the parameters include pointer values to data needed as input to a 39269system call, @value{GDBN} requests this data from the target with a 39270standard @code{m} packet request. This additional communication has to be 39271expected by the target implementation and is handled as any other @code{m} 39272packet. 39273 39274@item 39275@value{GDBN} translates all value from protocol representation to host 39276representation as needed. Datatypes are coerced into the host types. 39277 39278@item 39279@value{GDBN} calls the system call. 39280 39281@item 39282It then coerces datatypes back to protocol representation. 39283 39284@item 39285If the system call is expected to return data in buffer space specified 39286by pointer parameters to the call, the data is transmitted to the 39287target using a @code{M} or @code{X} packet. This packet has to be expected 39288by the target implementation and is handled as any other @code{M} or @code{X} 39289packet. 39290 39291@end itemize 39292 39293Eventually @value{GDBN} replies with another @code{F} packet which contains all 39294necessary information for the target to continue. This at least contains 39295 39296@itemize @bullet 39297@item 39298Return value. 39299 39300@item 39301@code{errno}, if has been changed by the system call. 39302 39303@item 39304``Ctrl-C'' flag. 39305 39306@end itemize 39307 39308After having done the needed type and value coercion, the target continues 39309the latest continue or step action. 39310 39311@node The F Request Packet 39312@subsection The @code{F} Request Packet 39313@cindex file-i/o request packet 39314@cindex @code{F} request packet 39315 39316The @code{F} request packet has the following format: 39317 39318@table @samp 39319@item F@var{call-id},@var{parameter@dots{}} 39320 39321@var{call-id} is the identifier to indicate the host system call to be called. 39322This is just the name of the function. 39323 39324@var{parameter@dots{}} are the parameters to the system call. 39325Parameters are hexadecimal integer values, either the actual values in case 39326of scalar datatypes, pointers to target buffer space in case of compound 39327datatypes and unspecified memory areas, or pointer/length pairs in case 39328of string parameters. These are appended to the @var{call-id} as a 39329comma-delimited list. All values are transmitted in ASCII 39330string representation, pointer/length pairs separated by a slash. 39331 39332@end table 39333 39334 39335 39336@node The F Reply Packet 39337@subsection The @code{F} Reply Packet 39338@cindex file-i/o reply packet 39339@cindex @code{F} reply packet 39340 39341The @code{F} reply packet has the following format: 39342 39343@table @samp 39344 39345@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call-specific attachment} 39346 39347@var{retcode} is the return code of the system call as hexadecimal value. 39348 39349@var{errno} is the @code{errno} set by the call, in protocol-specific 39350representation. 39351This parameter can be omitted if the call was successful. 39352 39353@var{Ctrl-C flag} is only sent if the user requested a break. In this 39354case, @var{errno} must be sent as well, even if the call was successful. 39355The @var{Ctrl-C flag} itself consists of the character @samp{C}: 39356 39357@smallexample 39358F0,0,C 39359@end smallexample 39360 39361@noindent 39362or, if the call was interrupted before the host call has been performed: 39363 39364@smallexample 39365F-1,4,C 39366@end smallexample 39367 39368@noindent 39369assuming 4 is the protocol-specific representation of @code{EINTR}. 39370 39371@end table 39372 39373 39374@node The Ctrl-C Message 39375@subsection The @samp{Ctrl-C} Message 39376@cindex ctrl-c message, in file-i/o protocol 39377 39378If the @samp{Ctrl-C} flag is set in the @value{GDBN} 39379reply packet (@pxref{The F Reply Packet}), 39380the target should behave as if it had 39381gotten a break message. The meaning for the target is ``system call 39382interrupted by @code{SIGINT}''. Consequentially, the target should actually stop 39383(as with a break message) and return to @value{GDBN} with a @code{T02} 39384packet. 39385 39386It's important for the target to know in which 39387state the system call was interrupted. There are two possible cases: 39388 39389@itemize @bullet 39390@item 39391The system call hasn't been performed on the host yet. 39392 39393@item 39394The system call on the host has been finished. 39395 39396@end itemize 39397 39398These two states can be distinguished by the target by the value of the 39399returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system 39400call hasn't been performed. This is equivalent to the @code{EINTR} handling 39401on POSIX systems. In any other case, the target may presume that the 39402system call has been finished --- successfully or not --- and should behave 39403as if the break message arrived right after the system call. 39404 39405@value{GDBN} must behave reliably. If the system call has not been called 39406yet, @value{GDBN} may send the @code{F} reply immediately, setting @code{EINTR} as 39407@code{errno} in the packet. If the system call on the host has been finished 39408before the user requests a break, the full action must be finished by 39409@value{GDBN}. This requires sending @code{M} or @code{X} packets as necessary. 39410The @code{F} packet may only be sent when either nothing has happened 39411or the full action has been completed. 39412 39413@node Console I/O 39414@subsection Console I/O 39415@cindex console i/o as part of file-i/o 39416 39417By default and if not explicitly closed by the target system, the file 39418descriptors 0, 1 and 2 are connected to the @value{GDBN} console. Output 39419on the @value{GDBN} console is handled as any other file output operation 39420(@code{write(1, @dots{})} or @code{write(2, @dots{})}). Console input is handled 39421by @value{GDBN} so that after the target read request from file descriptor 394220 all following typing is buffered until either one of the following 39423conditions is met: 39424 39425@itemize @bullet 39426@item 39427The user types @kbd{Ctrl-c}. The behaviour is as explained above, and the 39428@code{read} 39429system call is treated as finished. 39430 39431@item 39432The user presses @key{RET}. This is treated as end of input with a trailing 39433newline. 39434 39435@item 39436The user types @kbd{Ctrl-d}. This is treated as end of input. No trailing 39437character (neither newline nor @samp{Ctrl-D}) is appended to the input. 39438 39439@end itemize 39440 39441If the user has typed more characters than fit in the buffer given to 39442the @code{read} call, the trailing characters are buffered in @value{GDBN} until 39443either another @code{read(0, @dots{})} is requested by the target, or debugging 39444is stopped at the user's request. 39445 39446 39447@node List of Supported Calls 39448@subsection List of Supported Calls 39449@cindex list of supported file-i/o calls 39450 39451@menu 39452* open:: 39453* close:: 39454* read:: 39455* write:: 39456* lseek:: 39457* rename:: 39458* unlink:: 39459* stat/fstat:: 39460* gettimeofday:: 39461* isatty:: 39462* system:: 39463@end menu 39464 39465@node open 39466@unnumberedsubsubsec open 39467@cindex open, file-i/o system call 39468 39469@table @asis 39470@item Synopsis: 39471@smallexample 39472int open(const char *pathname, int flags); 39473int open(const char *pathname, int flags, mode_t mode); 39474@end smallexample 39475 39476@item Request: 39477@samp{Fopen,@var{pathptr}/@var{len},@var{flags},@var{mode}} 39478 39479@noindent 39480@var{flags} is the bitwise @code{OR} of the following values: 39481 39482@table @code 39483@item O_CREAT 39484If the file does not exist it will be created. The host 39485rules apply as far as file ownership and time stamps 39486are concerned. 39487 39488@item O_EXCL 39489When used with @code{O_CREAT}, if the file already exists it is 39490an error and open() fails. 39491 39492@item O_TRUNC 39493If the file already exists and the open mode allows 39494writing (@code{O_RDWR} or @code{O_WRONLY} is given) it will be 39495truncated to zero length. 39496 39497@item O_APPEND 39498The file is opened in append mode. 39499 39500@item O_RDONLY 39501The file is opened for reading only. 39502 39503@item O_WRONLY 39504The file is opened for writing only. 39505 39506@item O_RDWR 39507The file is opened for reading and writing. 39508@end table 39509 39510@noindent 39511Other bits are silently ignored. 39512 39513 39514@noindent 39515@var{mode} is the bitwise @code{OR} of the following values: 39516 39517@table @code 39518@item S_IRUSR 39519User has read permission. 39520 39521@item S_IWUSR 39522User has write permission. 39523 39524@item S_IRGRP 39525Group has read permission. 39526 39527@item S_IWGRP 39528Group has write permission. 39529 39530@item S_IROTH 39531Others have read permission. 39532 39533@item S_IWOTH 39534Others have write permission. 39535@end table 39536 39537@noindent 39538Other bits are silently ignored. 39539 39540 39541@item Return value: 39542@code{open} returns the new file descriptor or -1 if an error 39543occurred. 39544 39545@item Errors: 39546 39547@table @code 39548@item EEXIST 39549@var{pathname} already exists and @code{O_CREAT} and @code{O_EXCL} were used. 39550 39551@item EISDIR 39552@var{pathname} refers to a directory. 39553 39554@item EACCES 39555The requested access is not allowed. 39556 39557@item ENAMETOOLONG 39558@var{pathname} was too long. 39559 39560@item ENOENT 39561A directory component in @var{pathname} does not exist. 39562 39563@item ENODEV 39564@var{pathname} refers to a device, pipe, named pipe or socket. 39565 39566@item EROFS 39567@var{pathname} refers to a file on a read-only filesystem and 39568write access was requested. 39569 39570@item EFAULT 39571@var{pathname} is an invalid pointer value. 39572 39573@item ENOSPC 39574No space on device to create the file. 39575 39576@item EMFILE 39577The process already has the maximum number of files open. 39578 39579@item ENFILE 39580The limit on the total number of files open on the system 39581has been reached. 39582 39583@item EINTR 39584The call was interrupted by the user. 39585@end table 39586 39587@end table 39588 39589@node close 39590@unnumberedsubsubsec close 39591@cindex close, file-i/o system call 39592 39593@table @asis 39594@item Synopsis: 39595@smallexample 39596int close(int fd); 39597@end smallexample 39598 39599@item Request: 39600@samp{Fclose,@var{fd}} 39601 39602@item Return value: 39603@code{close} returns zero on success, or -1 if an error occurred. 39604 39605@item Errors: 39606 39607@table @code 39608@item EBADF 39609@var{fd} isn't a valid open file descriptor. 39610 39611@item EINTR 39612The call was interrupted by the user. 39613@end table 39614 39615@end table 39616 39617@node read 39618@unnumberedsubsubsec read 39619@cindex read, file-i/o system call 39620 39621@table @asis 39622@item Synopsis: 39623@smallexample 39624int read(int fd, void *buf, unsigned int count); 39625@end smallexample 39626 39627@item Request: 39628@samp{Fread,@var{fd},@var{bufptr},@var{count}} 39629 39630@item Return value: 39631On success, the number of bytes read is returned. 39632Zero indicates end of file. If count is zero, read 39633returns zero as well. On error, -1 is returned. 39634 39635@item Errors: 39636 39637@table @code 39638@item EBADF 39639@var{fd} is not a valid file descriptor or is not open for 39640reading. 39641 39642@item EFAULT 39643@var{bufptr} is an invalid pointer value. 39644 39645@item EINTR 39646The call was interrupted by the user. 39647@end table 39648 39649@end table 39650 39651@node write 39652@unnumberedsubsubsec write 39653@cindex write, file-i/o system call 39654 39655@table @asis 39656@item Synopsis: 39657@smallexample 39658int write(int fd, const void *buf, unsigned int count); 39659@end smallexample 39660 39661@item Request: 39662@samp{Fwrite,@var{fd},@var{bufptr},@var{count}} 39663 39664@item Return value: 39665On success, the number of bytes written are returned. 39666Zero indicates nothing was written. On error, -1 39667is returned. 39668 39669@item Errors: 39670 39671@table @code 39672@item EBADF 39673@var{fd} is not a valid file descriptor or is not open for 39674writing. 39675 39676@item EFAULT 39677@var{bufptr} is an invalid pointer value. 39678 39679@item EFBIG 39680An attempt was made to write a file that exceeds the 39681host-specific maximum file size allowed. 39682 39683@item ENOSPC 39684No space on device to write the data. 39685 39686@item EINTR 39687The call was interrupted by the user. 39688@end table 39689 39690@end table 39691 39692@node lseek 39693@unnumberedsubsubsec lseek 39694@cindex lseek, file-i/o system call 39695 39696@table @asis 39697@item Synopsis: 39698@smallexample 39699long lseek (int fd, long offset, int flag); 39700@end smallexample 39701 39702@item Request: 39703@samp{Flseek,@var{fd},@var{offset},@var{flag}} 39704 39705@var{flag} is one of: 39706 39707@table @code 39708@item SEEK_SET 39709The offset is set to @var{offset} bytes. 39710 39711@item SEEK_CUR 39712The offset is set to its current location plus @var{offset} 39713bytes. 39714 39715@item SEEK_END 39716The offset is set to the size of the file plus @var{offset} 39717bytes. 39718@end table 39719 39720@item Return value: 39721On success, the resulting unsigned offset in bytes from 39722the beginning of the file is returned. Otherwise, a 39723value of -1 is returned. 39724 39725@item Errors: 39726 39727@table @code 39728@item EBADF 39729@var{fd} is not a valid open file descriptor. 39730 39731@item ESPIPE 39732@var{fd} is associated with the @value{GDBN} console. 39733 39734@item EINVAL 39735@var{flag} is not a proper value. 39736 39737@item EINTR 39738The call was interrupted by the user. 39739@end table 39740 39741@end table 39742 39743@node rename 39744@unnumberedsubsubsec rename 39745@cindex rename, file-i/o system call 39746 39747@table @asis 39748@item Synopsis: 39749@smallexample 39750int rename(const char *oldpath, const char *newpath); 39751@end smallexample 39752 39753@item Request: 39754@samp{Frename,@var{oldpathptr}/@var{len},@var{newpathptr}/@var{len}} 39755 39756@item Return value: 39757On success, zero is returned. On error, -1 is returned. 39758 39759@item Errors: 39760 39761@table @code 39762@item EISDIR 39763@var{newpath} is an existing directory, but @var{oldpath} is not a 39764directory. 39765 39766@item EEXIST 39767@var{newpath} is a non-empty directory. 39768 39769@item EBUSY 39770@var{oldpath} or @var{newpath} is a directory that is in use by some 39771process. 39772 39773@item EINVAL 39774An attempt was made to make a directory a subdirectory 39775of itself. 39776 39777@item ENOTDIR 39778A component used as a directory in @var{oldpath} or new 39779path is not a directory. Or @var{oldpath} is a directory 39780and @var{newpath} exists but is not a directory. 39781 39782@item EFAULT 39783@var{oldpathptr} or @var{newpathptr} are invalid pointer values. 39784 39785@item EACCES 39786No access to the file or the path of the file. 39787 39788@item ENAMETOOLONG 39789 39790@var{oldpath} or @var{newpath} was too long. 39791 39792@item ENOENT 39793A directory component in @var{oldpath} or @var{newpath} does not exist. 39794 39795@item EROFS 39796The file is on a read-only filesystem. 39797 39798@item ENOSPC 39799The device containing the file has no room for the new 39800directory entry. 39801 39802@item EINTR 39803The call was interrupted by the user. 39804@end table 39805 39806@end table 39807 39808@node unlink 39809@unnumberedsubsubsec unlink 39810@cindex unlink, file-i/o system call 39811 39812@table @asis 39813@item Synopsis: 39814@smallexample 39815int unlink(const char *pathname); 39816@end smallexample 39817 39818@item Request: 39819@samp{Funlink,@var{pathnameptr}/@var{len}} 39820 39821@item Return value: 39822On success, zero is returned. On error, -1 is returned. 39823 39824@item Errors: 39825 39826@table @code 39827@item EACCES 39828No access to the file or the path of the file. 39829 39830@item EPERM 39831The system does not allow unlinking of directories. 39832 39833@item EBUSY 39834The file @var{pathname} cannot be unlinked because it's 39835being used by another process. 39836 39837@item EFAULT 39838@var{pathnameptr} is an invalid pointer value. 39839 39840@item ENAMETOOLONG 39841@var{pathname} was too long. 39842 39843@item ENOENT 39844A directory component in @var{pathname} does not exist. 39845 39846@item ENOTDIR 39847A component of the path is not a directory. 39848 39849@item EROFS 39850The file is on a read-only filesystem. 39851 39852@item EINTR 39853The call was interrupted by the user. 39854@end table 39855 39856@end table 39857 39858@node stat/fstat 39859@unnumberedsubsubsec stat/fstat 39860@cindex fstat, file-i/o system call 39861@cindex stat, file-i/o system call 39862 39863@table @asis 39864@item Synopsis: 39865@smallexample 39866int stat(const char *pathname, struct stat *buf); 39867int fstat(int fd, struct stat *buf); 39868@end smallexample 39869 39870@item Request: 39871@samp{Fstat,@var{pathnameptr}/@var{len},@var{bufptr}}@* 39872@samp{Ffstat,@var{fd},@var{bufptr}} 39873 39874@item Return value: 39875On success, zero is returned. On error, -1 is returned. 39876 39877@item Errors: 39878 39879@table @code 39880@item EBADF 39881@var{fd} is not a valid open file. 39882 39883@item ENOENT 39884A directory component in @var{pathname} does not exist or the 39885path is an empty string. 39886 39887@item ENOTDIR 39888A component of the path is not a directory. 39889 39890@item EFAULT 39891@var{pathnameptr} is an invalid pointer value. 39892 39893@item EACCES 39894No access to the file or the path of the file. 39895 39896@item ENAMETOOLONG 39897@var{pathname} was too long. 39898 39899@item EINTR 39900The call was interrupted by the user. 39901@end table 39902 39903@end table 39904 39905@node gettimeofday 39906@unnumberedsubsubsec gettimeofday 39907@cindex gettimeofday, file-i/o system call 39908 39909@table @asis 39910@item Synopsis: 39911@smallexample 39912int gettimeofday(struct timeval *tv, void *tz); 39913@end smallexample 39914 39915@item Request: 39916@samp{Fgettimeofday,@var{tvptr},@var{tzptr}} 39917 39918@item Return value: 39919On success, 0 is returned, -1 otherwise. 39920 39921@item Errors: 39922 39923@table @code 39924@item EINVAL 39925@var{tz} is a non-NULL pointer. 39926 39927@item EFAULT 39928@var{tvptr} and/or @var{tzptr} is an invalid pointer value. 39929@end table 39930 39931@end table 39932 39933@node isatty 39934@unnumberedsubsubsec isatty 39935@cindex isatty, file-i/o system call 39936 39937@table @asis 39938@item Synopsis: 39939@smallexample 39940int isatty(int fd); 39941@end smallexample 39942 39943@item Request: 39944@samp{Fisatty,@var{fd}} 39945 39946@item Return value: 39947Returns 1 if @var{fd} refers to the @value{GDBN} console, 0 otherwise. 39948 39949@item Errors: 39950 39951@table @code 39952@item EINTR 39953The call was interrupted by the user. 39954@end table 39955 39956@end table 39957 39958Note that the @code{isatty} call is treated as a special case: it returns 399591 to the target if the file descriptor is attached 39960to the @value{GDBN} console, 0 otherwise. Implementing through system calls 39961would require implementing @code{ioctl} and would be more complex than 39962needed. 39963 39964 39965@node system 39966@unnumberedsubsubsec system 39967@cindex system, file-i/o system call 39968 39969@table @asis 39970@item Synopsis: 39971@smallexample 39972int system(const char *command); 39973@end smallexample 39974 39975@item Request: 39976@samp{Fsystem,@var{commandptr}/@var{len}} 39977 39978@item Return value: 39979If @var{len} is zero, the return value indicates whether a shell is 39980available. A zero return value indicates a shell is not available. 39981For non-zero @var{len}, the value returned is -1 on error and the 39982return status of the command otherwise. Only the exit status of the 39983command is returned, which is extracted from the host's @code{system} 39984return value by calling @code{WEXITSTATUS(retval)}. In case 39985@file{/bin/sh} could not be executed, 127 is returned. 39986 39987@item Errors: 39988 39989@table @code 39990@item EINTR 39991The call was interrupted by the user. 39992@end table 39993 39994@end table 39995 39996@value{GDBN} takes over the full task of calling the necessary host calls 39997to perform the @code{system} call. The return value of @code{system} on 39998the host is simplified before it's returned 39999to the target. Any termination signal information from the child process 40000is discarded, and the return value consists 40001entirely of the exit status of the called command. 40002 40003Due to security concerns, the @code{system} call is by default refused 40004by @value{GDBN}. The user has to allow this call explicitly with the 40005@code{set remote system-call-allowed 1} command. 40006 40007@table @code 40008@item set remote system-call-allowed 40009@kindex set remote system-call-allowed 40010Control whether to allow the @code{system} calls in the File I/O 40011protocol for the remote target. The default is zero (disabled). 40012 40013@item show remote system-call-allowed 40014@kindex show remote system-call-allowed 40015Show whether the @code{system} calls are allowed in the File I/O 40016protocol. 40017@end table 40018 40019@node Protocol-specific Representation of Datatypes 40020@subsection Protocol-specific Representation of Datatypes 40021@cindex protocol-specific representation of datatypes, in file-i/o protocol 40022 40023@menu 40024* Integral Datatypes:: 40025* Pointer Values:: 40026* Memory Transfer:: 40027* struct stat:: 40028* struct timeval:: 40029@end menu 40030 40031@node Integral Datatypes 40032@unnumberedsubsubsec Integral Datatypes 40033@cindex integral datatypes, in file-i/o protocol 40034 40035The integral datatypes used in the system calls are @code{int}, 40036@code{unsigned int}, @code{long}, @code{unsigned long}, 40037@code{mode_t}, and @code{time_t}. 40038 40039@code{int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are 40040implemented as 32 bit values in this protocol. 40041 40042@code{long} and @code{unsigned long} are implemented as 64 bit types. 40043 40044@xref{Limits}, for corresponding MIN and MAX values (similar to those 40045in @file{limits.h}) to allow range checking on host and target. 40046 40047@code{time_t} datatypes are defined as seconds since the Epoch. 40048 40049All integral datatypes transferred as part of a memory read or write of a 40050structured datatype e.g.@: a @code{struct stat} have to be given in big endian 40051byte order. 40052 40053@node Pointer Values 40054@unnumberedsubsubsec Pointer Values 40055@cindex pointer values, in file-i/o protocol 40056 40057Pointers to target data are transmitted as they are. An exception 40058is made for pointers to buffers for which the length isn't 40059transmitted as part of the function call, namely strings. Strings 40060are transmitted as a pointer/length pair, both as hex values, e.g.@: 40061 40062@smallexample 40063@code{1aaf/12} 40064@end smallexample 40065 40066@noindent 40067which is a pointer to data of length 18 bytes at position 0x1aaf. 40068The length is defined as the full string length in bytes, including 40069the trailing null byte. For example, the string @code{"hello world"} 40070at address 0x123456 is transmitted as 40071 40072@smallexample 40073@code{123456/d} 40074@end smallexample 40075 40076@node Memory Transfer 40077@unnumberedsubsubsec Memory Transfer 40078@cindex memory transfer, in file-i/o protocol 40079 40080Structured data which is transferred using a memory read or write (for 40081example, a @code{struct stat}) is expected to be in a protocol-specific format 40082with all scalar multibyte datatypes being big endian. Translation to 40083this representation needs to be done both by the target before the @code{F} 40084packet is sent, and by @value{GDBN} before 40085it transfers memory to the target. Transferred pointers to structured 40086data should point to the already-coerced data at any time. 40087 40088 40089@node struct stat 40090@unnumberedsubsubsec struct stat 40091@cindex struct stat, in file-i/o protocol 40092 40093The buffer of type @code{struct stat} used by the target and @value{GDBN} 40094is defined as follows: 40095 40096@smallexample 40097struct stat @{ 40098 unsigned int st_dev; /* device */ 40099 unsigned int st_ino; /* inode */ 40100 mode_t st_mode; /* protection */ 40101 unsigned int st_nlink; /* number of hard links */ 40102 unsigned int st_uid; /* user ID of owner */ 40103 unsigned int st_gid; /* group ID of owner */ 40104 unsigned int st_rdev; /* device type (if inode device) */ 40105 unsigned long st_size; /* total size, in bytes */ 40106 unsigned long st_blksize; /* blocksize for filesystem I/O */ 40107 unsigned long st_blocks; /* number of blocks allocated */ 40108 time_t st_atime; /* time of last access */ 40109 time_t st_mtime; /* time of last modification */ 40110 time_t st_ctime; /* time of last change */ 40111@}; 40112@end smallexample 40113 40114The integral datatypes conform to the definitions given in the 40115appropriate section (see @ref{Integral Datatypes}, for details) so this 40116structure is of size 64 bytes. 40117 40118The values of several fields have a restricted meaning and/or 40119range of values. 40120 40121@table @code 40122 40123@item st_dev 40124A value of 0 represents a file, 1 the console. 40125 40126@item st_ino 40127No valid meaning for the target. Transmitted unchanged. 40128 40129@item st_mode 40130Valid mode bits are described in @ref{Constants}. Any other 40131bits have currently no meaning for the target. 40132 40133@item st_uid 40134@itemx st_gid 40135@itemx st_rdev 40136No valid meaning for the target. Transmitted unchanged. 40137 40138@item st_atime 40139@itemx st_mtime 40140@itemx st_ctime 40141These values have a host and file system dependent 40142accuracy. Especially on Windows hosts, the file system may not 40143support exact timing values. 40144@end table 40145 40146The target gets a @code{struct stat} of the above representation and is 40147responsible for coercing it to the target representation before 40148continuing. 40149 40150Note that due to size differences between the host, target, and protocol 40151representations of @code{struct stat} members, these members could eventually 40152get truncated on the target. 40153 40154@node struct timeval 40155@unnumberedsubsubsec struct timeval 40156@cindex struct timeval, in file-i/o protocol 40157 40158The buffer of type @code{struct timeval} used by the File-I/O protocol 40159is defined as follows: 40160 40161@smallexample 40162struct timeval @{ 40163 time_t tv_sec; /* second */ 40164 long tv_usec; /* microsecond */ 40165@}; 40166@end smallexample 40167 40168The integral datatypes conform to the definitions given in the 40169appropriate section (see @ref{Integral Datatypes}, for details) so this 40170structure is of size 8 bytes. 40171 40172@node Constants 40173@subsection Constants 40174@cindex constants, in file-i/o protocol 40175 40176The following values are used for the constants inside of the 40177protocol. @value{GDBN} and target are responsible for translating these 40178values before and after the call as needed. 40179 40180@menu 40181* Open Flags:: 40182* mode_t Values:: 40183* Errno Values:: 40184* Lseek Flags:: 40185* Limits:: 40186@end menu 40187 40188@node Open Flags 40189@unnumberedsubsubsec Open Flags 40190@cindex open flags, in file-i/o protocol 40191 40192All values are given in hexadecimal representation. 40193 40194@smallexample 40195 O_RDONLY 0x0 40196 O_WRONLY 0x1 40197 O_RDWR 0x2 40198 O_APPEND 0x8 40199 O_CREAT 0x200 40200 O_TRUNC 0x400 40201 O_EXCL 0x800 40202@end smallexample 40203 40204@node mode_t Values 40205@unnumberedsubsubsec mode_t Values 40206@cindex mode_t values, in file-i/o protocol 40207 40208All values are given in octal representation. 40209 40210@smallexample 40211 S_IFREG 0100000 40212 S_IFDIR 040000 40213 S_IRUSR 0400 40214 S_IWUSR 0200 40215 S_IXUSR 0100 40216 S_IRGRP 040 40217 S_IWGRP 020 40218 S_IXGRP 010 40219 S_IROTH 04 40220 S_IWOTH 02 40221 S_IXOTH 01 40222@end smallexample 40223 40224@node Errno Values 40225@unnumberedsubsubsec Errno Values 40226@cindex errno values, in file-i/o protocol 40227 40228All values are given in decimal representation. 40229 40230@smallexample 40231 EPERM 1 40232 ENOENT 2 40233 EINTR 4 40234 EBADF 9 40235 EACCES 13 40236 EFAULT 14 40237 EBUSY 16 40238 EEXIST 17 40239 ENODEV 19 40240 ENOTDIR 20 40241 EISDIR 21 40242 EINVAL 22 40243 ENFILE 23 40244 EMFILE 24 40245 EFBIG 27 40246 ENOSPC 28 40247 ESPIPE 29 40248 EROFS 30 40249 ENAMETOOLONG 91 40250 EUNKNOWN 9999 40251@end smallexample 40252 40253 @code{EUNKNOWN} is used as a fallback error value if a host system returns 40254 any error value not in the list of supported error numbers. 40255 40256@node Lseek Flags 40257@unnumberedsubsubsec Lseek Flags 40258@cindex lseek flags, in file-i/o protocol 40259 40260@smallexample 40261 SEEK_SET 0 40262 SEEK_CUR 1 40263 SEEK_END 2 40264@end smallexample 40265 40266@node Limits 40267@unnumberedsubsubsec Limits 40268@cindex limits, in file-i/o protocol 40269 40270All values are given in decimal representation. 40271 40272@smallexample 40273 INT_MIN -2147483648 40274 INT_MAX 2147483647 40275 UINT_MAX 4294967295 40276 LONG_MIN -9223372036854775808 40277 LONG_MAX 9223372036854775807 40278 ULONG_MAX 18446744073709551615 40279@end smallexample 40280 40281@node File-I/O Examples 40282@subsection File-I/O Examples 40283@cindex file-i/o examples 40284 40285Example sequence of a write call, file descriptor 3, buffer is at target 40286address 0x1234, 6 bytes should be written: 40287 40288@smallexample 40289<- @code{Fwrite,3,1234,6} 40290@emph{request memory read from target} 40291-> @code{m1234,6} 40292<- XXXXXX 40293@emph{return "6 bytes written"} 40294-> @code{F6} 40295@end smallexample 40296 40297Example sequence of a read call, file descriptor 3, buffer is at target 40298address 0x1234, 6 bytes should be read: 40299 40300@smallexample 40301<- @code{Fread,3,1234,6} 40302@emph{request memory write to target} 40303-> @code{X1234,6:XXXXXX} 40304@emph{return "6 bytes read"} 40305-> @code{F6} 40306@end smallexample 40307 40308Example sequence of a read call, call fails on the host due to invalid 40309file descriptor (@code{EBADF}): 40310 40311@smallexample 40312<- @code{Fread,3,1234,6} 40313-> @code{F-1,9} 40314@end smallexample 40315 40316Example sequence of a read call, user presses @kbd{Ctrl-c} before syscall on 40317host is called: 40318 40319@smallexample 40320<- @code{Fread,3,1234,6} 40321-> @code{F-1,4,C} 40322<- @code{T02} 40323@end smallexample 40324 40325Example sequence of a read call, user presses @kbd{Ctrl-c} after syscall on 40326host is called: 40327 40328@smallexample 40329<- @code{Fread,3,1234,6} 40330-> @code{X1234,6:XXXXXX} 40331<- @code{T02} 40332@end smallexample 40333 40334@node Library List Format 40335@section Library List Format 40336@cindex library list format, remote protocol 40337 40338On some platforms, a dynamic loader (e.g.@: @file{ld.so}) runs in the 40339same process as your application to manage libraries. In this case, 40340@value{GDBN} can use the loader's symbol table and normal memory 40341operations to maintain a list of shared libraries. On other 40342platforms, the operating system manages loaded libraries. 40343@value{GDBN} can not retrieve the list of currently loaded libraries 40344through memory operations, so it uses the @samp{qXfer:libraries:read} 40345packet (@pxref{qXfer library list read}) instead. The remote stub 40346queries the target's operating system and reports which libraries 40347are loaded. 40348 40349The @samp{qXfer:libraries:read} packet returns an XML document which 40350lists loaded libraries and their offsets. Each library has an 40351associated name and one or more segment or section base addresses, 40352which report where the library was loaded in memory. 40353 40354For the common case of libraries that are fully linked binaries, the 40355library should have a list of segments. If the target supports 40356dynamic linking of a relocatable object file, its library XML element 40357should instead include a list of allocated sections. The segment or 40358section bases are start addresses, not relocation offsets; they do not 40359depend on the library's link-time base addresses. 40360 40361@value{GDBN} must be linked with the Expat library to support XML 40362library lists. @xref{Expat}. 40363 40364A simple memory map, with one loaded library relocated by a single 40365offset, looks like this: 40366 40367@smallexample 40368<library-list> 40369 <library name="/lib/libc.so.6"> 40370 <segment address="0x10000000"/> 40371 </library> 40372</library-list> 40373@end smallexample 40374 40375Another simple memory map, with one loaded library with three 40376allocated sections (.text, .data, .bss), looks like this: 40377 40378@smallexample 40379<library-list> 40380 <library name="sharedlib.o"> 40381 <section address="0x10000000"/> 40382 <section address="0x20000000"/> 40383 <section address="0x30000000"/> 40384 </library> 40385</library-list> 40386@end smallexample 40387 40388The format of a library list is described by this DTD: 40389 40390@smallexample 40391<!-- library-list: Root element with versioning --> 40392<!ELEMENT library-list (library)*> 40393<!ATTLIST library-list version CDATA #FIXED "1.0"> 40394<!ELEMENT library (segment*, section*)> 40395<!ATTLIST library name CDATA #REQUIRED> 40396<!ELEMENT segment EMPTY> 40397<!ATTLIST segment address CDATA #REQUIRED> 40398<!ELEMENT section EMPTY> 40399<!ATTLIST section address CDATA #REQUIRED> 40400@end smallexample 40401 40402In addition, segments and section descriptors cannot be mixed within a 40403single library element, and you must supply at least one segment or 40404section for each library. 40405 40406@node Library List Format for SVR4 Targets 40407@section Library List Format for SVR4 Targets 40408@cindex library list format, remote protocol 40409 40410On SVR4 platforms @value{GDBN} can use the symbol table of a dynamic loader 40411(e.g.@: @file{ld.so}) and normal memory operations to maintain a list of 40412shared libraries. Still a special library list provided by this packet is 40413more efficient for the @value{GDBN} remote protocol. 40414 40415The @samp{qXfer:libraries-svr4:read} packet returns an XML document which lists 40416loaded libraries and their SVR4 linker parameters. For each library on SVR4 40417target, the following parameters are reported: 40418 40419@itemize @minus 40420@item 40421@code{name}, the absolute file name from the @code{l_name} field of 40422@code{struct link_map}. 40423@item 40424@code{lm} with address of @code{struct link_map} used for TLS 40425(Thread Local Storage) access. 40426@item 40427@code{l_addr}, the displacement as read from the field @code{l_addr} of 40428@code{struct link_map}. For prelinked libraries this is not an absolute 40429memory address. It is a displacement of absolute memory address against 40430address the file was prelinked to during the library load. 40431@item 40432@code{l_ld}, which is memory address of the @code{PT_DYNAMIC} segment 40433@end itemize 40434 40435Additionally the single @code{main-lm} attribute specifies address of 40436@code{struct link_map} used for the main executable. This parameter is used 40437for TLS access and its presence is optional. 40438 40439@value{GDBN} must be linked with the Expat library to support XML 40440SVR4 library lists. @xref{Expat}. 40441 40442A simple memory map, with two loaded libraries (which do not use prelink), 40443looks like this: 40444 40445@smallexample 40446<library-list-svr4 version="1.0" main-lm="0xe4f8f8"> 40447 <library name="/lib/ld-linux.so.2" lm="0xe4f51c" l_addr="0xe2d000" 40448 l_ld="0xe4eefc"/> 40449 <library name="/lib/libc.so.6" lm="0xe4fbe8" l_addr="0x154000" 40450 l_ld="0x152350"/> 40451</library-list-svr> 40452@end smallexample 40453 40454The format of an SVR4 library list is described by this DTD: 40455 40456@smallexample 40457<!-- library-list-svr4: Root element with versioning --> 40458<!ELEMENT library-list-svr4 (library)*> 40459<!ATTLIST library-list-svr4 version CDATA #FIXED "1.0"> 40460<!ATTLIST library-list-svr4 main-lm CDATA #IMPLIED> 40461<!ELEMENT library EMPTY> 40462<!ATTLIST library name CDATA #REQUIRED> 40463<!ATTLIST library lm CDATA #REQUIRED> 40464<!ATTLIST library l_addr CDATA #REQUIRED> 40465<!ATTLIST library l_ld CDATA #REQUIRED> 40466@end smallexample 40467 40468@node Memory Map Format 40469@section Memory Map Format 40470@cindex memory map format 40471 40472To be able to write into flash memory, @value{GDBN} needs to obtain a 40473memory map from the target. This section describes the format of the 40474memory map. 40475 40476The memory map is obtained using the @samp{qXfer:memory-map:read} 40477(@pxref{qXfer memory map read}) packet and is an XML document that 40478lists memory regions. 40479 40480@value{GDBN} must be linked with the Expat library to support XML 40481memory maps. @xref{Expat}. 40482 40483The top-level structure of the document is shown below: 40484 40485@smallexample 40486<?xml version="1.0"?> 40487<!DOCTYPE memory-map 40488 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN" 40489 "http://sourceware.org/gdb/gdb-memory-map.dtd"> 40490<memory-map> 40491 region... 40492</memory-map> 40493@end smallexample 40494 40495Each region can be either: 40496 40497@itemize 40498 40499@item 40500A region of RAM starting at @var{addr} and extending for @var{length} 40501bytes from there: 40502 40503@smallexample 40504<memory type="ram" start="@var{addr}" length="@var{length}"/> 40505@end smallexample 40506 40507 40508@item 40509A region of read-only memory: 40510 40511@smallexample 40512<memory type="rom" start="@var{addr}" length="@var{length}"/> 40513@end smallexample 40514 40515 40516@item 40517A region of flash memory, with erasure blocks @var{blocksize} 40518bytes in length: 40519 40520@smallexample 40521<memory type="flash" start="@var{addr}" length="@var{length}"> 40522 <property name="blocksize">@var{blocksize}</property> 40523</memory> 40524@end smallexample 40525 40526@end itemize 40527 40528Regions must not overlap. @value{GDBN} assumes that areas of memory not covered 40529by the memory map are RAM, and uses the ordinary @samp{M} and @samp{X} 40530packets to write to addresses in such ranges. 40531 40532The formal DTD for memory map format is given below: 40533 40534@smallexample 40535<!-- ................................................... --> 40536<!-- Memory Map XML DTD ................................ --> 40537<!-- File: memory-map.dtd .............................. --> 40538<!-- .................................... .............. --> 40539<!-- memory-map.dtd --> 40540<!-- memory-map: Root element with versioning --> 40541<!ELEMENT memory-map (memory | property)> 40542<!ATTLIST memory-map version CDATA #FIXED "1.0.0"> 40543<!ELEMENT memory (property)> 40544<!-- memory: Specifies a memory region, 40545 and its type, or device. --> 40546<!ATTLIST memory type CDATA #REQUIRED 40547 start CDATA #REQUIRED 40548 length CDATA #REQUIRED 40549 device CDATA #IMPLIED> 40550<!-- property: Generic attribute tag --> 40551<!ELEMENT property (#PCDATA | property)*> 40552<!ATTLIST property name CDATA #REQUIRED> 40553@end smallexample 40554 40555@node Thread List Format 40556@section Thread List Format 40557@cindex thread list format 40558 40559To efficiently update the list of threads and their attributes, 40560@value{GDBN} issues the @samp{qXfer:threads:read} packet 40561(@pxref{qXfer threads read}) and obtains the XML document with 40562the following structure: 40563 40564@smallexample 40565<?xml version="1.0"?> 40566<threads> 40567 <thread id="id" core="0"> 40568 ... description ... 40569 </thread> 40570</threads> 40571@end smallexample 40572 40573Each @samp{thread} element must have the @samp{id} attribute that 40574identifies the thread (@pxref{thread-id syntax}). The 40575@samp{core} attribute, if present, specifies which processor core 40576the thread was last executing on. The content of the of @samp{thread} 40577element is interpreted as human-readable auxilliary information. 40578 40579@node Traceframe Info Format 40580@section Traceframe Info Format 40581@cindex traceframe info format 40582 40583To be able to know which objects in the inferior can be examined when 40584inspecting a tracepoint hit, @value{GDBN} needs to obtain the list of 40585memory ranges, registers and trace state variables that have been 40586collected in a traceframe. 40587 40588This list is obtained using the @samp{qXfer:traceframe-info:read} 40589(@pxref{qXfer traceframe info read}) packet and is an XML document. 40590 40591@value{GDBN} must be linked with the Expat library to support XML 40592traceframe info discovery. @xref{Expat}. 40593 40594The top-level structure of the document is shown below: 40595 40596@smallexample 40597<?xml version="1.0"?> 40598<!DOCTYPE traceframe-info 40599 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN" 40600 "http://sourceware.org/gdb/gdb-traceframe-info.dtd"> 40601<traceframe-info> 40602 block... 40603</traceframe-info> 40604@end smallexample 40605 40606Each traceframe block can be either: 40607 40608@itemize 40609 40610@item 40611A region of collected memory starting at @var{addr} and extending for 40612@var{length} bytes from there: 40613 40614@smallexample 40615<memory start="@var{addr}" length="@var{length}"/> 40616@end smallexample 40617 40618@end itemize 40619 40620The formal DTD for the traceframe info format is given below: 40621 40622@smallexample 40623<!ELEMENT traceframe-info (memory)* > 40624<!ATTLIST traceframe-info version CDATA #FIXED "1.0"> 40625 40626<!ELEMENT memory EMPTY> 40627<!ATTLIST memory start CDATA #REQUIRED 40628 length CDATA #REQUIRED> 40629@end smallexample 40630 40631@node Branch Trace Format 40632@section Branch Trace Format 40633@cindex branch trace format 40634 40635In order to display the branch trace of an inferior thread, 40636@value{GDBN} needs to obtain the list of branches. This list is 40637represented as list of sequential code blocks that are connected via 40638branches. The code in each block has been executed sequentially. 40639 40640This list is obtained using the @samp{qXfer:btrace:read} 40641(@pxref{qXfer btrace read}) packet and is an XML document. 40642 40643@value{GDBN} must be linked with the Expat library to support XML 40644traceframe info discovery. @xref{Expat}. 40645 40646The top-level structure of the document is shown below: 40647 40648@smallexample 40649<?xml version="1.0"?> 40650<!DOCTYPE btrace 40651 PUBLIC "+//IDN gnu.org//DTD GDB Branch Trace V1.0//EN" 40652 "http://sourceware.org/gdb/gdb-btrace.dtd"> 40653<btrace> 40654 block... 40655</btrace> 40656@end smallexample 40657 40658@itemize 40659 40660@item 40661A block of sequentially executed instructions starting at @var{begin} 40662and ending at @var{end}: 40663 40664@smallexample 40665<block begin="@var{begin}" end="@var{end}"/> 40666@end smallexample 40667 40668@end itemize 40669 40670The formal DTD for the branch trace format is given below: 40671 40672@smallexample 40673<!ELEMENT btrace (block)* > 40674<!ATTLIST btrace version CDATA #FIXED "1.0"> 40675 40676<!ELEMENT block EMPTY> 40677<!ATTLIST block begin CDATA #REQUIRED 40678 end CDATA #REQUIRED> 40679@end smallexample 40680 40681@include agentexpr.texi 40682 40683@node Target Descriptions 40684@appendix Target Descriptions 40685@cindex target descriptions 40686 40687One of the challenges of using @value{GDBN} to debug embedded systems 40688is that there are so many minor variants of each processor 40689architecture in use. It is common practice for vendors to start with 40690a standard processor core --- ARM, PowerPC, or @acronym{MIPS}, for example --- 40691and then make changes to adapt it to a particular market niche. Some 40692architectures have hundreds of variants, available from dozens of 40693vendors. This leads to a number of problems: 40694 40695@itemize @bullet 40696@item 40697With so many different customized processors, it is difficult for 40698the @value{GDBN} maintainers to keep up with the changes. 40699@item 40700Since individual variants may have short lifetimes or limited 40701audiences, it may not be worthwhile to carry information about every 40702variant in the @value{GDBN} source tree. 40703@item 40704When @value{GDBN} does support the architecture of the embedded system 40705at hand, the task of finding the correct architecture name to give the 40706@command{set architecture} command can be error-prone. 40707@end itemize 40708 40709To address these problems, the @value{GDBN} remote protocol allows a 40710target system to not only identify itself to @value{GDBN}, but to 40711actually describe its own features. This lets @value{GDBN} support 40712processor variants it has never seen before --- to the extent that the 40713descriptions are accurate, and that @value{GDBN} understands them. 40714 40715@value{GDBN} must be linked with the Expat library to support XML 40716target descriptions. @xref{Expat}. 40717 40718@menu 40719* Retrieving Descriptions:: How descriptions are fetched from a target. 40720* Target Description Format:: The contents of a target description. 40721* Predefined Target Types:: Standard types available for target 40722 descriptions. 40723* Standard Target Features:: Features @value{GDBN} knows about. 40724@end menu 40725 40726@node Retrieving Descriptions 40727@section Retrieving Descriptions 40728 40729Target descriptions can be read from the target automatically, or 40730specified by the user manually. The default behavior is to read the 40731description from the target. @value{GDBN} retrieves it via the remote 40732protocol using @samp{qXfer} requests (@pxref{General Query Packets, 40733qXfer}). The @var{annex} in the @samp{qXfer} packet will be 40734@samp{target.xml}. The contents of the @samp{target.xml} annex are an 40735XML document, of the form described in @ref{Target Description 40736Format}. 40737 40738Alternatively, you can specify a file to read for the target description. 40739If a file is set, the target will not be queried. The commands to 40740specify a file are: 40741 40742@table @code 40743@cindex set tdesc filename 40744@item set tdesc filename @var{path} 40745Read the target description from @var{path}. 40746 40747@cindex unset tdesc filename 40748@item unset tdesc filename 40749Do not read the XML target description from a file. @value{GDBN} 40750will use the description supplied by the current target. 40751 40752@cindex show tdesc filename 40753@item show tdesc filename 40754Show the filename to read for a target description, if any. 40755@end table 40756 40757 40758@node Target Description Format 40759@section Target Description Format 40760@cindex target descriptions, XML format 40761 40762A target description annex is an @uref{http://www.w3.org/XML/, XML} 40763document which complies with the Document Type Definition provided in 40764the @value{GDBN} sources in @file{gdb/features/gdb-target.dtd}. This 40765means you can use generally available tools like @command{xmllint} to 40766check that your feature descriptions are well-formed and valid. 40767However, to help people unfamiliar with XML write descriptions for 40768their targets, we also describe the grammar here. 40769 40770Target descriptions can identify the architecture of the remote target 40771and (for some architectures) provide information about custom register 40772sets. They can also identify the OS ABI of the remote target. 40773@value{GDBN} can use this information to autoconfigure for your 40774target, or to warn you if you connect to an unsupported target. 40775 40776Here is a simple target description: 40777 40778@smallexample 40779<target version="1.0"> 40780 <architecture>i386:x86-64</architecture> 40781</target> 40782@end smallexample 40783 40784@noindent 40785This minimal description only says that the target uses 40786the x86-64 architecture. 40787 40788A target description has the following overall form, with [ ] marking 40789optional elements and @dots{} marking repeatable elements. The elements 40790are explained further below. 40791 40792@smallexample 40793<?xml version="1.0"?> 40794<!DOCTYPE target SYSTEM "gdb-target.dtd"> 40795<target version="1.0"> 40796 @r{[}@var{architecture}@r{]} 40797 @r{[}@var{osabi}@r{]} 40798 @r{[}@var{compatible}@r{]} 40799 @r{[}@var{feature}@dots{}@r{]} 40800</target> 40801@end smallexample 40802 40803@noindent 40804The description is generally insensitive to whitespace and line 40805breaks, under the usual common-sense rules. The XML version 40806declaration and document type declaration can generally be omitted 40807(@value{GDBN} does not require them), but specifying them may be 40808useful for XML validation tools. The @samp{version} attribute for 40809@samp{<target>} may also be omitted, but we recommend 40810including it; if future versions of @value{GDBN} use an incompatible 40811revision of @file{gdb-target.dtd}, they will detect and report 40812the version mismatch. 40813 40814@subsection Inclusion 40815@cindex target descriptions, inclusion 40816@cindex XInclude 40817@ifnotinfo 40818@cindex <xi:include> 40819@end ifnotinfo 40820 40821It can sometimes be valuable to split a target description up into 40822several different annexes, either for organizational purposes, or to 40823share files between different possible target descriptions. You can 40824divide a description into multiple files by replacing any element of 40825the target description with an inclusion directive of the form: 40826 40827@smallexample 40828<xi:include href="@var{document}"/> 40829@end smallexample 40830 40831@noindent 40832When @value{GDBN} encounters an element of this form, it will retrieve 40833the named XML @var{document}, and replace the inclusion directive with 40834the contents of that document. If the current description was read 40835using @samp{qXfer}, then so will be the included document; 40836@var{document} will be interpreted as the name of an annex. If the 40837current description was read from a file, @value{GDBN} will look for 40838@var{document} as a file in the same directory where it found the 40839original description. 40840 40841@subsection Architecture 40842@cindex <architecture> 40843 40844An @samp{<architecture>} element has this form: 40845 40846@smallexample 40847 <architecture>@var{arch}</architecture> 40848@end smallexample 40849 40850@var{arch} is one of the architectures from the set accepted by 40851@code{set architecture} (@pxref{Targets, ,Specifying a Debugging Target}). 40852 40853@subsection OS ABI 40854@cindex @code{<osabi>} 40855 40856This optional field was introduced in @value{GDBN} version 7.0. 40857Previous versions of @value{GDBN} ignore it. 40858 40859An @samp{<osabi>} element has this form: 40860 40861@smallexample 40862 <osabi>@var{abi-name}</osabi> 40863@end smallexample 40864 40865@var{abi-name} is an OS ABI name from the same selection accepted by 40866@w{@code{set osabi}} (@pxref{ABI, ,Configuring the Current ABI}). 40867 40868@subsection Compatible Architecture 40869@cindex @code{<compatible>} 40870 40871This optional field was introduced in @value{GDBN} version 7.0. 40872Previous versions of @value{GDBN} ignore it. 40873 40874A @samp{<compatible>} element has this form: 40875 40876@smallexample 40877 <compatible>@var{arch}</compatible> 40878@end smallexample 40879 40880@var{arch} is one of the architectures from the set accepted by 40881@code{set architecture} (@pxref{Targets, ,Specifying a Debugging Target}). 40882 40883A @samp{<compatible>} element is used to specify that the target 40884is able to run binaries in some other than the main target architecture 40885given by the @samp{<architecture>} element. For example, on the 40886Cell Broadband Engine, the main architecture is @code{powerpc:common} 40887or @code{powerpc:common64}, but the system is able to run binaries 40888in the @code{spu} architecture as well. The way to describe this 40889capability with @samp{<compatible>} is as follows: 40890 40891@smallexample 40892 <architecture>powerpc:common</architecture> 40893 <compatible>spu</compatible> 40894@end smallexample 40895 40896@subsection Features 40897@cindex <feature> 40898 40899Each @samp{<feature>} describes some logical portion of the target 40900system. Features are currently used to describe available CPU 40901registers and the types of their contents. A @samp{<feature>} element 40902has this form: 40903 40904@smallexample 40905<feature name="@var{name}"> 40906 @r{[}@var{type}@dots{}@r{]} 40907 @var{reg}@dots{} 40908</feature> 40909@end smallexample 40910 40911@noindent 40912Each feature's name should be unique within the description. The name 40913of a feature does not matter unless @value{GDBN} has some special 40914knowledge of the contents of that feature; if it does, the feature 40915should have its standard name. @xref{Standard Target Features}. 40916 40917@subsection Types 40918 40919Any register's value is a collection of bits which @value{GDBN} must 40920interpret. The default interpretation is a two's complement integer, 40921but other types can be requested by name in the register description. 40922Some predefined types are provided by @value{GDBN} (@pxref{Predefined 40923Target Types}), and the description can define additional composite types. 40924 40925Each type element must have an @samp{id} attribute, which gives 40926a unique (within the containing @samp{<feature>}) name to the type. 40927Types must be defined before they are used. 40928 40929@cindex <vector> 40930Some targets offer vector registers, which can be treated as arrays 40931of scalar elements. These types are written as @samp{<vector>} elements, 40932specifying the array element type, @var{type}, and the number of elements, 40933@var{count}: 40934 40935@smallexample 40936<vector id="@var{id}" type="@var{type}" count="@var{count}"/> 40937@end smallexample 40938 40939@cindex <union> 40940If a register's value is usefully viewed in multiple ways, define it 40941with a union type containing the useful representations. The 40942@samp{<union>} element contains one or more @samp{<field>} elements, 40943each of which has a @var{name} and a @var{type}: 40944 40945@smallexample 40946<union id="@var{id}"> 40947 <field name="@var{name}" type="@var{type}"/> 40948 @dots{} 40949</union> 40950@end smallexample 40951 40952@cindex <struct> 40953If a register's value is composed from several separate values, define 40954it with a structure type. There are two forms of the @samp{<struct>} 40955element; a @samp{<struct>} element must either contain only bitfields 40956or contain no bitfields. If the structure contains only bitfields, 40957its total size in bytes must be specified, each bitfield must have an 40958explicit start and end, and bitfields are automatically assigned an 40959integer type. The field's @var{start} should be less than or 40960equal to its @var{end}, and zero represents the least significant bit. 40961 40962@smallexample 40963<struct id="@var{id}" size="@var{size}"> 40964 <field name="@var{name}" start="@var{start}" end="@var{end}"/> 40965 @dots{} 40966</struct> 40967@end smallexample 40968 40969If the structure contains no bitfields, then each field has an 40970explicit type, and no implicit padding is added. 40971 40972@smallexample 40973<struct id="@var{id}"> 40974 <field name="@var{name}" type="@var{type}"/> 40975 @dots{} 40976</struct> 40977@end smallexample 40978 40979@cindex <flags> 40980If a register's value is a series of single-bit flags, define it with 40981a flags type. The @samp{<flags>} element has an explicit @var{size} 40982and contains one or more @samp{<field>} elements. Each field has a 40983@var{name}, a @var{start}, and an @var{end}. Only single-bit flags 40984are supported. 40985 40986@smallexample 40987<flags id="@var{id}" size="@var{size}"> 40988 <field name="@var{name}" start="@var{start}" end="@var{end}"/> 40989 @dots{} 40990</flags> 40991@end smallexample 40992 40993@subsection Registers 40994@cindex <reg> 40995 40996Each register is represented as an element with this form: 40997 40998@smallexample 40999<reg name="@var{name}" 41000 bitsize="@var{size}" 41001 @r{[}regnum="@var{num}"@r{]} 41002 @r{[}save-restore="@var{save-restore}"@r{]} 41003 @r{[}type="@var{type}"@r{]} 41004 @r{[}group="@var{group}"@r{]}/> 41005@end smallexample 41006 41007@noindent 41008The components are as follows: 41009 41010@table @var 41011 41012@item name 41013The register's name; it must be unique within the target description. 41014 41015@item bitsize 41016The register's size, in bits. 41017 41018@item regnum 41019The register's number. If omitted, a register's number is one greater 41020than that of the previous register (either in the current feature or in 41021a preceding feature); the first register in the target description 41022defaults to zero. This register number is used to read or write 41023the register; e.g.@: it is used in the remote @code{p} and @code{P} 41024packets, and registers appear in the @code{g} and @code{G} packets 41025in order of increasing register number. 41026 41027@item save-restore 41028Whether the register should be preserved across inferior function 41029calls; this must be either @code{yes} or @code{no}. The default is 41030@code{yes}, which is appropriate for most registers except for 41031some system control registers; this is not related to the target's 41032ABI. 41033 41034@item type 41035The type of the register. @var{type} may be a predefined type, a type 41036defined in the current feature, or one of the special types @code{int} 41037and @code{float}. @code{int} is an integer type of the correct size 41038for @var{bitsize}, and @code{float} is a floating point type (in the 41039architecture's normal floating point format) of the correct size for 41040@var{bitsize}. The default is @code{int}. 41041 41042@item group 41043The register group to which this register belongs. @var{group} must 41044be either @code{general}, @code{float}, or @code{vector}. If no 41045@var{group} is specified, @value{GDBN} will not display the register 41046in @code{info registers}. 41047 41048@end table 41049 41050@node Predefined Target Types 41051@section Predefined Target Types 41052@cindex target descriptions, predefined types 41053 41054Type definitions in the self-description can build up composite types 41055from basic building blocks, but can not define fundamental types. Instead, 41056standard identifiers are provided by @value{GDBN} for the fundamental 41057types. The currently supported types are: 41058 41059@table @code 41060 41061@item int8 41062@itemx int16 41063@itemx int32 41064@itemx int64 41065@itemx int128 41066Signed integer types holding the specified number of bits. 41067 41068@item uint8 41069@itemx uint16 41070@itemx uint32 41071@itemx uint64 41072@itemx uint128 41073Unsigned integer types holding the specified number of bits. 41074 41075@item code_ptr 41076@itemx data_ptr 41077Pointers to unspecified code and data. The program counter and 41078any dedicated return address register may be marked as code 41079pointers; printing a code pointer converts it into a symbolic 41080address. The stack pointer and any dedicated address registers 41081may be marked as data pointers. 41082 41083@item ieee_single 41084Single precision IEEE floating point. 41085 41086@item ieee_double 41087Double precision IEEE floating point. 41088 41089@item arm_fpa_ext 41090The 12-byte extended precision format used by ARM FPA registers. 41091 41092@item i387_ext 41093The 10-byte extended precision format used by x87 registers. 41094 41095@item i386_eflags 4109632bit @sc{eflags} register used by x86. 41097 41098@item i386_mxcsr 4109932bit @sc{mxcsr} register used by x86. 41100 41101@end table 41102 41103@node Standard Target Features 41104@section Standard Target Features 41105@cindex target descriptions, standard features 41106 41107A target description must contain either no registers or all the 41108target's registers. If the description contains no registers, then 41109@value{GDBN} will assume a default register layout, selected based on 41110the architecture. If the description contains any registers, the 41111default layout will not be used; the standard registers must be 41112described in the target description, in such a way that @value{GDBN} 41113can recognize them. 41114 41115This is accomplished by giving specific names to feature elements 41116which contain standard registers. @value{GDBN} will look for features 41117with those names and verify that they contain the expected registers; 41118if any known feature is missing required registers, or if any required 41119feature is missing, @value{GDBN} will reject the target 41120description. You can add additional registers to any of the 41121standard features --- @value{GDBN} will display them just as if 41122they were added to an unrecognized feature. 41123 41124This section lists the known features and their expected contents. 41125Sample XML documents for these features are included in the 41126@value{GDBN} source tree, in the directory @file{gdb/features}. 41127 41128Names recognized by @value{GDBN} should include the name of the 41129company or organization which selected the name, and the overall 41130architecture to which the feature applies; so e.g.@: the feature 41131containing ARM core registers is named @samp{org.gnu.gdb.arm.core}. 41132 41133The names of registers are not case sensitive for the purpose 41134of recognizing standard features, but @value{GDBN} will only display 41135registers using the capitalization used in the description. 41136 41137@menu 41138* AArch64 Features:: 41139* ARM Features:: 41140* i386 Features:: 41141* MIPS Features:: 41142* M68K Features:: 41143* PowerPC Features:: 41144* TIC6x Features:: 41145@end menu 41146 41147 41148@node AArch64 Features 41149@subsection AArch64 Features 41150@cindex target descriptions, AArch64 features 41151 41152The @samp{org.gnu.gdb.aarch64.core} feature is required for AArch64 41153targets. It should contain registers @samp{x0} through @samp{x30}, 41154@samp{sp}, @samp{pc}, and @samp{cpsr}. 41155 41156The @samp{org.gnu.gdb.aarch64.fpu} feature is optional. If present, 41157it should contain registers @samp{v0} through @samp{v31}, @samp{fpsr}, 41158and @samp{fpcr}. 41159 41160@node ARM Features 41161@subsection ARM Features 41162@cindex target descriptions, ARM features 41163 41164The @samp{org.gnu.gdb.arm.core} feature is required for non-M-profile 41165ARM targets. 41166It should contain registers @samp{r0} through @samp{r13}, @samp{sp}, 41167@samp{lr}, @samp{pc}, and @samp{cpsr}. 41168 41169For M-profile targets (e.g. Cortex-M3), the @samp{org.gnu.gdb.arm.core} 41170feature is replaced by @samp{org.gnu.gdb.arm.m-profile}. It should contain 41171registers @samp{r0} through @samp{r13}, @samp{sp}, @samp{lr}, @samp{pc}, 41172and @samp{xpsr}. 41173 41174The @samp{org.gnu.gdb.arm.fpa} feature is optional. If present, it 41175should contain registers @samp{f0} through @samp{f7} and @samp{fps}. 41176 41177The @samp{org.gnu.gdb.xscale.iwmmxt} feature is optional. If present, 41178it should contain at least registers @samp{wR0} through @samp{wR15} and 41179@samp{wCGR0} through @samp{wCGR3}. The @samp{wCID}, @samp{wCon}, 41180@samp{wCSSF}, and @samp{wCASF} registers are optional. 41181 41182The @samp{org.gnu.gdb.arm.vfp} feature is optional. If present, it 41183should contain at least registers @samp{d0} through @samp{d15}. If 41184they are present, @samp{d16} through @samp{d31} should also be included. 41185@value{GDBN} will synthesize the single-precision registers from 41186halves of the double-precision registers. 41187 41188The @samp{org.gnu.gdb.arm.neon} feature is optional. It does not 41189need to contain registers; it instructs @value{GDBN} to display the 41190VFP double-precision registers as vectors and to synthesize the 41191quad-precision registers from pairs of double-precision registers. 41192If this feature is present, @samp{org.gnu.gdb.arm.vfp} must also 41193be present and include 32 double-precision registers. 41194 41195@node i386 Features 41196@subsection i386 Features 41197@cindex target descriptions, i386 features 41198 41199The @samp{org.gnu.gdb.i386.core} feature is required for i386/amd64 41200targets. It should describe the following registers: 41201 41202@itemize @minus 41203@item 41204@samp{eax} through @samp{edi} plus @samp{eip} for i386 41205@item 41206@samp{rax} through @samp{r15} plus @samp{rip} for amd64 41207@item 41208@samp{eflags}, @samp{cs}, @samp{ss}, @samp{ds}, @samp{es}, 41209@samp{fs}, @samp{gs} 41210@item 41211@samp{st0} through @samp{st7} 41212@item 41213@samp{fctrl}, @samp{fstat}, @samp{ftag}, @samp{fiseg}, @samp{fioff}, 41214@samp{foseg}, @samp{fooff} and @samp{fop} 41215@end itemize 41216 41217The register sets may be different, depending on the target. 41218 41219The @samp{org.gnu.gdb.i386.sse} feature is optional. It should 41220describe registers: 41221 41222@itemize @minus 41223@item 41224@samp{xmm0} through @samp{xmm7} for i386 41225@item 41226@samp{xmm0} through @samp{xmm15} for amd64 41227@item 41228@samp{mxcsr} 41229@end itemize 41230 41231The @samp{org.gnu.gdb.i386.avx} feature is optional and requires the 41232@samp{org.gnu.gdb.i386.sse} feature. It should 41233describe the upper 128 bits of @sc{ymm} registers: 41234 41235@itemize @minus 41236@item 41237@samp{ymm0h} through @samp{ymm7h} for i386 41238@item 41239@samp{ymm0h} through @samp{ymm15h} for amd64 41240@end itemize 41241 41242The @samp{org.gnu.gdb.i386.linux} feature is optional. It should 41243describe a single register, @samp{orig_eax}. 41244 41245@node MIPS Features 41246@subsection @acronym{MIPS} Features 41247@cindex target descriptions, @acronym{MIPS} features 41248 41249The @samp{org.gnu.gdb.mips.cpu} feature is required for @acronym{MIPS} targets. 41250It should contain registers @samp{r0} through @samp{r31}, @samp{lo}, 41251@samp{hi}, and @samp{pc}. They may be 32-bit or 64-bit depending 41252on the target. 41253 41254The @samp{org.gnu.gdb.mips.cp0} feature is also required. It should 41255contain at least the @samp{status}, @samp{badvaddr}, and @samp{cause} 41256registers. They may be 32-bit or 64-bit depending on the target. 41257 41258The @samp{org.gnu.gdb.mips.fpu} feature is currently required, though 41259it may be optional in a future version of @value{GDBN}. It should 41260contain registers @samp{f0} through @samp{f31}, @samp{fcsr}, and 41261@samp{fir}. They may be 32-bit or 64-bit depending on the target. 41262 41263The @samp{org.gnu.gdb.mips.dsp} feature is optional. It should 41264contain registers @samp{hi1} through @samp{hi3}, @samp{lo1} through 41265@samp{lo3}, and @samp{dspctl}. The @samp{dspctl} register should 41266be 32-bit and the rest may be 32-bit or 64-bit depending on the target. 41267 41268The @samp{org.gnu.gdb.mips.linux} feature is optional. It should 41269contain a single register, @samp{restart}, which is used by the 41270Linux kernel to control restartable syscalls. 41271 41272@node M68K Features 41273@subsection M68K Features 41274@cindex target descriptions, M68K features 41275 41276@table @code 41277@item @samp{org.gnu.gdb.m68k.core} 41278@itemx @samp{org.gnu.gdb.coldfire.core} 41279@itemx @samp{org.gnu.gdb.fido.core} 41280One of those features must be always present. 41281The feature that is present determines which flavor of m68k is 41282used. The feature that is present should contain registers 41283@samp{d0} through @samp{d7}, @samp{a0} through @samp{a5}, @samp{fp}, 41284@samp{sp}, @samp{ps} and @samp{pc}. 41285 41286@item @samp{org.gnu.gdb.coldfire.fp} 41287This feature is optional. If present, it should contain registers 41288@samp{fp0} through @samp{fp7}, @samp{fpcontrol}, @samp{fpstatus} and 41289@samp{fpiaddr}. 41290@end table 41291 41292@node PowerPC Features 41293@subsection PowerPC Features 41294@cindex target descriptions, PowerPC features 41295 41296The @samp{org.gnu.gdb.power.core} feature is required for PowerPC 41297targets. It should contain registers @samp{r0} through @samp{r31}, 41298@samp{pc}, @samp{msr}, @samp{cr}, @samp{lr}, @samp{ctr}, and 41299@samp{xer}. They may be 32-bit or 64-bit depending on the target. 41300 41301The @samp{org.gnu.gdb.power.fpu} feature is optional. It should 41302contain registers @samp{f0} through @samp{f31} and @samp{fpscr}. 41303 41304The @samp{org.gnu.gdb.power.altivec} feature is optional. It should 41305contain registers @samp{vr0} through @samp{vr31}, @samp{vscr}, 41306and @samp{vrsave}. 41307 41308The @samp{org.gnu.gdb.power.vsx} feature is optional. It should 41309contain registers @samp{vs0h} through @samp{vs31h}. @value{GDBN} 41310will combine these registers with the floating point registers 41311(@samp{f0} through @samp{f31}) and the altivec registers (@samp{vr0} 41312through @samp{vr31}) to present the 128-bit wide registers @samp{vs0} 41313through @samp{vs63}, the set of vector registers for POWER7. 41314 41315The @samp{org.gnu.gdb.power.spe} feature is optional. It should 41316contain registers @samp{ev0h} through @samp{ev31h}, @samp{acc}, and 41317@samp{spefscr}. SPE targets should provide 32-bit registers in 41318@samp{org.gnu.gdb.power.core} and provide the upper halves in 41319@samp{ev0h} through @samp{ev31h}. @value{GDBN} will combine 41320these to present registers @samp{ev0} through @samp{ev31} to the 41321user. 41322 41323@node TIC6x Features 41324@subsection TMS320C6x Features 41325@cindex target descriptions, TIC6x features 41326@cindex target descriptions, TMS320C6x features 41327The @samp{org.gnu.gdb.tic6x.core} feature is required for TMS320C6x 41328targets. It should contain registers @samp{A0} through @samp{A15}, 41329registers @samp{B0} through @samp{B15}, @samp{CSR} and @samp{PC}. 41330 41331The @samp{org.gnu.gdb.tic6x.gp} feature is optional. It should 41332contain registers @samp{A16} through @samp{A31} and @samp{B16} 41333through @samp{B31}. 41334 41335The @samp{org.gnu.gdb.tic6x.c6xp} feature is optional. It should 41336contain registers @samp{TSR}, @samp{ILC} and @samp{RILC}. 41337 41338@node Operating System Information 41339@appendix Operating System Information 41340@cindex operating system information 41341 41342@menu 41343* Process list:: 41344@end menu 41345 41346Users of @value{GDBN} often wish to obtain information about the state of 41347the operating system running on the target---for example the list of 41348processes, or the list of open files. This section describes the 41349mechanism that makes it possible. This mechanism is similar to the 41350target features mechanism (@pxref{Target Descriptions}), but focuses 41351on a different aspect of target. 41352 41353Operating system information is retrived from the target via the 41354remote protocol, using @samp{qXfer} requests (@pxref{qXfer osdata 41355read}). The object name in the request should be @samp{osdata}, and 41356the @var{annex} identifies the data to be fetched. 41357 41358@node Process list 41359@appendixsection Process list 41360@cindex operating system information, process list 41361 41362When requesting the process list, the @var{annex} field in the 41363@samp{qXfer} request should be @samp{processes}. The returned data is 41364an XML document. The formal syntax of this document is defined in 41365@file{gdb/features/osdata.dtd}. 41366 41367An example document is: 41368 41369@smallexample 41370<?xml version="1.0"?> 41371<!DOCTYPE target SYSTEM "osdata.dtd"> 41372<osdata type="processes"> 41373 <item> 41374 <column name="pid">1</column> 41375 <column name="user">root</column> 41376 <column name="command">/sbin/init</column> 41377 <column name="cores">1,2,3</column> 41378 </item> 41379</osdata> 41380@end smallexample 41381 41382Each item should include a column whose name is @samp{pid}. The value 41383of that column should identify the process on the target. The 41384@samp{user} and @samp{command} columns are optional, and will be 41385displayed by @value{GDBN}. The @samp{cores} column, if present, 41386should contain a comma-separated list of cores that this process 41387is running on. Target may provide additional columns, 41388which @value{GDBN} currently ignores. 41389 41390@node Trace File Format 41391@appendix Trace File Format 41392@cindex trace file format 41393 41394The trace file comes in three parts: a header, a textual description 41395section, and a trace frame section with binary data. 41396 41397The header has the form @code{\x7fTRACE0\n}. The first byte is 41398@code{0x7f} so as to indicate that the file contains binary data, 41399while the @code{0} is a version number that may have different values 41400in the future. 41401 41402The description section consists of multiple lines of @sc{ascii} text 41403separated by newline characters (@code{0xa}). The lines may include a 41404variety of optional descriptive or context-setting information, such 41405as tracepoint definitions or register set size. @value{GDBN} will 41406ignore any line that it does not recognize. An empty line marks the end 41407of this section. 41408 41409@c FIXME add some specific types of data 41410 41411The trace frame section consists of a number of consecutive frames. 41412Each frame begins with a two-byte tracepoint number, followed by a 41413four-byte size giving the amount of data in the frame. The data in 41414the frame consists of a number of blocks, each introduced by a 41415character indicating its type (at least register, memory, and trace 41416state variable). The data in this section is raw binary, not a 41417hexadecimal or other encoding; its endianness matches the target's 41418endianness. 41419 41420@c FIXME bi-arch may require endianness/arch info in description section 41421 41422@table @code 41423@item R @var{bytes} 41424Register block. The number and ordering of bytes matches that of a 41425@code{g} packet in the remote protocol. Note that these are the 41426actual bytes, in target order and @value{GDBN} register order, not a 41427hexadecimal encoding. 41428 41429@item M @var{address} @var{length} @var{bytes}... 41430Memory block. This is a contiguous block of memory, at the 8-byte 41431address @var{address}, with a 2-byte length @var{length}, followed by 41432@var{length} bytes. 41433 41434@item V @var{number} @var{value} 41435Trace state variable block. This records the 8-byte signed value 41436@var{value} of trace state variable numbered @var{number}. 41437 41438@end table 41439 41440Future enhancements of the trace file format may include additional types 41441of blocks. 41442 41443@node Index Section Format 41444@appendix @code{.gdb_index} section format 41445@cindex .gdb_index section format 41446@cindex index section format 41447 41448This section documents the index section that is created by @code{save 41449gdb-index} (@pxref{Index Files}). The index section is 41450DWARF-specific; some knowledge of DWARF is assumed in this 41451description. 41452 41453The mapped index file format is designed to be directly 41454@code{mmap}able on any architecture. In most cases, a datum is 41455represented using a little-endian 32-bit integer value, called an 41456@code{offset_type}. Big endian machines must byte-swap the values 41457before using them. Exceptions to this rule are noted. The data is 41458laid out such that alignment is always respected. 41459 41460A mapped index consists of several areas, laid out in order. 41461 41462@enumerate 41463@item 41464The file header. This is a sequence of values, of @code{offset_type} 41465unless otherwise noted: 41466 41467@enumerate 41468@item 41469The version number, currently 8. Versions 1, 2 and 3 are obsolete. 41470Version 4 uses a different hashing function from versions 5 and 6. 41471Version 6 includes symbols for inlined functions, whereas versions 4 41472and 5 do not. Version 7 adds attributes to the CU indices in the 41473symbol table. Version 8 specifies that symbols from DWARF type units 41474(@samp{DW_TAG_type_unit}) refer to the type unit's symbol table and not the 41475compilation unit (@samp{DW_TAG_comp_unit}) using the type. 41476 41477@value{GDBN} will only read version 4, 5, or 6 indices 41478by specifying @code{set use-deprecated-index-sections on}. 41479GDB has a workaround for potentially broken version 7 indices so it is 41480currently not flagged as deprecated. 41481 41482@item 41483The offset, from the start of the file, of the CU list. 41484 41485@item 41486The offset, from the start of the file, of the types CU list. Note 41487that this area can be empty, in which case this offset will be equal 41488to the next offset. 41489 41490@item 41491The offset, from the start of the file, of the address area. 41492 41493@item 41494The offset, from the start of the file, of the symbol table. 41495 41496@item 41497The offset, from the start of the file, of the constant pool. 41498@end enumerate 41499 41500@item 41501The CU list. This is a sequence of pairs of 64-bit little-endian 41502values, sorted by the CU offset. The first element in each pair is 41503the offset of a CU in the @code{.debug_info} section. The second 41504element in each pair is the length of that CU. References to a CU 41505elsewhere in the map are done using a CU index, which is just the 415060-based index into this table. Note that if there are type CUs, then 41507conceptually CUs and type CUs form a single list for the purposes of 41508CU indices. 41509 41510@item 41511The types CU list. This is a sequence of triplets of 64-bit 41512little-endian values. In a triplet, the first value is the CU offset, 41513the second value is the type offset in the CU, and the third value is 41514the type signature. The types CU list is not sorted. 41515 41516@item 41517The address area. The address area consists of a sequence of address 41518entries. Each address entry has three elements: 41519 41520@enumerate 41521@item 41522The low address. This is a 64-bit little-endian value. 41523 41524@item 41525The high address. This is a 64-bit little-endian value. Like 41526@code{DW_AT_high_pc}, the value is one byte beyond the end. 41527 41528@item 41529The CU index. This is an @code{offset_type} value. 41530@end enumerate 41531 41532@item 41533The symbol table. This is an open-addressed hash table. The size of 41534the hash table is always a power of 2. 41535 41536Each slot in the hash table consists of a pair of @code{offset_type} 41537values. The first value is the offset of the symbol's name in the 41538constant pool. The second value is the offset of the CU vector in the 41539constant pool. 41540 41541If both values are 0, then this slot in the hash table is empty. This 41542is ok because while 0 is a valid constant pool index, it cannot be a 41543valid index for both a string and a CU vector. 41544 41545The hash value for a table entry is computed by applying an 41546iterative hash function to the symbol's name. Starting with an 41547initial value of @code{r = 0}, each (unsigned) character @samp{c} in 41548the string is incorporated into the hash using the formula depending on the 41549index version: 41550 41551@table @asis 41552@item Version 4 41553The formula is @code{r = r * 67 + c - 113}. 41554 41555@item Versions 5 to 7 41556The formula is @code{r = r * 67 + tolower (c) - 113}. 41557@end table 41558 41559The terminating @samp{\0} is not incorporated into the hash. 41560 41561The step size used in the hash table is computed via 41562@code{((hash * 17) & (size - 1)) | 1}, where @samp{hash} is the hash 41563value, and @samp{size} is the size of the hash table. The step size 41564is used to find the next candidate slot when handling a hash 41565collision. 41566 41567The names of C@t{++} symbols in the hash table are canonicalized. We 41568don't currently have a simple description of the canonicalization 41569algorithm; if you intend to create new index sections, you must read 41570the code. 41571 41572@item 41573The constant pool. This is simply a bunch of bytes. It is organized 41574so that alignment is correct: CU vectors are stored first, followed by 41575strings. 41576 41577A CU vector in the constant pool is a sequence of @code{offset_type} 41578values. The first value is the number of CU indices in the vector. 41579Each subsequent value is the index and symbol attributes of a CU in 41580the CU list. This element in the hash table is used to indicate which 41581CUs define the symbol and how the symbol is used. 41582See below for the format of each CU index+attributes entry. 41583 41584A string in the constant pool is zero-terminated. 41585@end enumerate 41586 41587Attributes were added to CU index values in @code{.gdb_index} version 7. 41588If a symbol has multiple uses within a CU then there is one 41589CU index+attributes value for each use. 41590 41591The format of each CU index+attributes entry is as follows 41592(bit 0 = LSB): 41593 41594@table @asis 41595 41596@item Bits 0-23 41597This is the index of the CU in the CU list. 41598@item Bits 24-27 41599These bits are reserved for future purposes and must be zero. 41600@item Bits 28-30 41601The kind of the symbol in the CU. 41602 41603@table @asis 41604@item 0 41605This value is reserved and should not be used. 41606By reserving zero the full @code{offset_type} value is backwards compatible 41607with previous versions of the index. 41608@item 1 41609The symbol is a type. 41610@item 2 41611The symbol is a variable or an enum value. 41612@item 3 41613The symbol is a function. 41614@item 4 41615Any other kind of symbol. 41616@item 5,6,7 41617These values are reserved. 41618@end table 41619 41620@item Bit 31 41621This bit is zero if the value is global and one if it is static. 41622 41623The determination of whether a symbol is global or static is complicated. 41624The authorative reference is the file @file{dwarf2read.c} in 41625@value{GDBN} sources. 41626 41627@end table 41628 41629This pseudo-code describes the computation of a symbol's kind and 41630global/static attributes in the index. 41631 41632@smallexample 41633is_external = get_attribute (die, DW_AT_external); 41634language = get_attribute (cu_die, DW_AT_language); 41635switch (die->tag) 41636 @{ 41637 case DW_TAG_typedef: 41638 case DW_TAG_base_type: 41639 case DW_TAG_subrange_type: 41640 kind = TYPE; 41641 is_static = 1; 41642 break; 41643 case DW_TAG_enumerator: 41644 kind = VARIABLE; 41645 is_static = (language != CPLUS && language != JAVA); 41646 break; 41647 case DW_TAG_subprogram: 41648 kind = FUNCTION; 41649 is_static = ! (is_external || language == ADA); 41650 break; 41651 case DW_TAG_constant: 41652 kind = VARIABLE; 41653 is_static = ! is_external; 41654 break; 41655 case DW_TAG_variable: 41656 kind = VARIABLE; 41657 is_static = ! is_external; 41658 break; 41659 case DW_TAG_namespace: 41660 kind = TYPE; 41661 is_static = 0; 41662 break; 41663 case DW_TAG_class_type: 41664 case DW_TAG_interface_type: 41665 case DW_TAG_structure_type: 41666 case DW_TAG_union_type: 41667 case DW_TAG_enumeration_type: 41668 kind = TYPE; 41669 is_static = (language != CPLUS && language != JAVA); 41670 break; 41671 default: 41672 assert (0); 41673 @} 41674@end smallexample 41675 41676@include gpl.texi 41677 41678@node GNU Free Documentation License 41679@appendix GNU Free Documentation License 41680@include fdl.texi 41681 41682@node Concept Index 41683@unnumbered Concept Index 41684 41685@printindex cp 41686 41687@node Command and Variable Index 41688@unnumbered Command, Variable, and Function Index 41689 41690@printindex fn 41691 41692@tex 41693% I think something like @@colophon should be in texinfo. In the 41694% meantime: 41695\long\def\colophon{\hbox to0pt{}\vfill 41696\centerline{The body of this manual is set in} 41697\centerline{\fontname\tenrm,} 41698\centerline{with headings in {\bf\fontname\tenbf}} 41699\centerline{and examples in {\tt\fontname\tentt}.} 41700\centerline{{\it\fontname\tenit\/},} 41701\centerline{{\bf\fontname\tenbf}, and} 41702\centerline{{\sl\fontname\tensl\/}} 41703\centerline{are used for emphasis.}\vfill} 41704\page\colophon 41705% Blame: doc@@cygnus.com, 1991. 41706@end tex 41707 41708@bye 41709