1\input texinfo @c -*-texinfo-*- 2@c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 3@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 4@c Free Software Foundation, Inc. 5@c 6@c %**start of header 7@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use 8@c of @set vars. However, you can override filename with makeinfo -o. 9@setfilename gdb.info 10@c 11@include gdb-cfg.texi 12@c 13@settitle Debugging with @value{GDBN} 14@setchapternewpage odd 15@c %**end of header 16 17@iftex 18@c @smallbook 19@c @cropmarks 20@end iftex 21 22@finalout 23@syncodeindex ky cp 24 25@c readline appendices use @vindex, @findex and @ftable, 26@c annotate.texi and gdbmi use @findex. 27@syncodeindex vr cp 28@syncodeindex fn cp 29 30@c !!set GDB manual's edition---not the same as GDB version! 31@c This is updated by GNU Press. 32@set EDITION Ninth 33 34@c !!set GDB edit command default editor 35@set EDITOR /bin/ex 36 37@c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER. 38 39@c This is a dir.info fragment to support semi-automated addition of 40@c manuals to an info tree. 41@dircategory Software development 42@direntry 43* Gdb: (gdb). The GNU debugger. 44@end direntry 45 46@ifinfo 47This file documents the @sc{gnu} debugger @value{GDBN}. 48 49 50This is the @value{EDITION} Edition, of @cite{Debugging with 51@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN} 52Version @value{GDBVN}. 53 54Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@* 55 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006@* 56 Free Software Foundation, Inc. 57 58Permission is granted to copy, distribute and/or modify this document 59under the terms of the GNU Free Documentation License, Version 1.1 or 60any later version published by the Free Software Foundation; with the 61Invariant Sections being ``Free Software'' and ``Free Software Needs 62Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 63and with the Back-Cover Texts as in (a) below. 64 65(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 66this GNU Manual. Buying copies from GNU Press supports the FSF in 67developing GNU and promoting software freedom.'' 68@end ifinfo 69 70@titlepage 71@title Debugging with @value{GDBN} 72@subtitle The @sc{gnu} Source-Level Debugger 73@sp 1 74@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN} 75@author Richard Stallman, Roland Pesch, Stan Shebs, et al. 76@page 77@tex 78{\parskip=0pt 79\hfill (Send bugs and comments on @value{GDBN} to bug-gdb\@gnu.org.)\par 80\hfill {\it Debugging with @value{GDBN}}\par 81\hfill \TeX{}info \texinfoversion\par 82} 83@end tex 84 85@vskip 0pt plus 1filll 86Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 871996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2006 88Free Software Foundation, Inc. 89@sp 2 90Published by the Free Software Foundation @* 9151 Franklin Street, Fifth Floor, 92Boston, MA 02110-1301, USA@* 93ISBN 1-882114-77-9 @* 94 95Permission is granted to copy, distribute and/or modify this document 96under the terms of the GNU Free Documentation License, Version 1.1 or 97any later version published by the Free Software Foundation; with the 98Invariant Sections being ``Free Software'' and ``Free Software Needs 99Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 100and with the Back-Cover Texts as in (a) below. 101 102(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 103this GNU Manual. Buying copies from GNU Press supports the FSF in 104developing GNU and promoting software freedom.'' 105@page 106This edition of the GDB manual is dedicated to the memory of Fred 107Fish. Fred was a long-standing contributor to GDB and to Free 108software in general. We will miss him. 109@end titlepage 110@page 111 112@ifnottex 113@node Top, Summary, (dir), (dir) 114 115@top Debugging with @value{GDBN} 116 117This file describes @value{GDBN}, the @sc{gnu} symbolic debugger. 118 119This is the @value{EDITION} Edition, for @value{GDBN} Version 120@value{GDBVN}. 121 122Copyright (C) 1988-2006 Free Software Foundation, Inc. 123 124This edition of the GDB manual is dedicated to the memory of Fred 125Fish. Fred was a long-standing contributor to GDB and to Free 126software in general. We will miss him. 127 128@menu 129* Summary:: Summary of @value{GDBN} 130* Sample Session:: A sample @value{GDBN} session 131 132* Invocation:: Getting in and out of @value{GDBN} 133* Commands:: @value{GDBN} commands 134* Running:: Running programs under @value{GDBN} 135* Stopping:: Stopping and continuing 136* Stack:: Examining the stack 137* Source:: Examining source files 138* Data:: Examining data 139* Macros:: Preprocessor Macros 140* Tracepoints:: Debugging remote targets non-intrusively 141* Overlays:: Debugging programs that use overlays 142 143* Languages:: Using @value{GDBN} with different languages 144 145* Symbols:: Examining the symbol table 146* Altering:: Altering execution 147* GDB Files:: @value{GDBN} files 148* Targets:: Specifying a debugging target 149* Remote Debugging:: Debugging remote programs 150* Configurations:: Configuration-specific information 151* Controlling GDB:: Controlling @value{GDBN} 152* Sequences:: Canned sequences of commands 153* Interpreters:: Command Interpreters 154* TUI:: @value{GDBN} Text User Interface 155* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs 156* GDB/MI:: @value{GDBN}'s Machine Interface. 157* Annotations:: @value{GDBN}'s annotation interface. 158 159* GDB Bugs:: Reporting bugs in @value{GDBN} 160 161* Command Line Editing:: Command Line Editing 162* Using History Interactively:: Using History Interactively 163* Formatting Documentation:: How to format and print @value{GDBN} documentation 164* Installing GDB:: Installing GDB 165* Maintenance Commands:: Maintenance Commands 166* Remote Protocol:: GDB Remote Serial Protocol 167* Agent Expressions:: The GDB Agent Expression Mechanism 168* Target Descriptions:: How targets can describe themselves to 169 @value{GDBN} 170* Copying:: GNU General Public License says 171 how you can copy and share GDB 172* GNU Free Documentation License:: The license for this documentation 173* Index:: Index 174@end menu 175 176@end ifnottex 177 178@contents 179 180@node Summary 181@unnumbered Summary of @value{GDBN} 182 183The purpose of a debugger such as @value{GDBN} is to allow you to see what is 184going on ``inside'' another program while it executes---or what another 185program was doing at the moment it crashed. 186 187@value{GDBN} can do four main kinds of things (plus other things in support of 188these) to help you catch bugs in the act: 189 190@itemize @bullet 191@item 192Start your program, specifying anything that might affect its behavior. 193 194@item 195Make your program stop on specified conditions. 196 197@item 198Examine what has happened, when your program has stopped. 199 200@item 201Change things in your program, so you can experiment with correcting the 202effects of one bug and go on to learn about another. 203@end itemize 204 205You can use @value{GDBN} to debug programs written in C and C@t{++}. 206For more information, see @ref{Supported Languages,,Supported Languages}. 207For more information, see @ref{C,,C and C++}. 208 209@cindex Modula-2 210Support for Modula-2 is partial. For information on Modula-2, see 211@ref{Modula-2,,Modula-2}. 212 213@cindex Pascal 214Debugging Pascal programs which use sets, subranges, file variables, or 215nested functions does not currently work. @value{GDBN} does not support 216entering expressions, printing values, or similar features using Pascal 217syntax. 218 219@cindex Fortran 220@value{GDBN} can be used to debug programs written in Fortran, although 221it may be necessary to refer to some variables with a trailing 222underscore. 223 224@value{GDBN} can be used to debug programs written in Objective-C, 225using either the Apple/NeXT or the GNU Objective-C runtime. 226 227@menu 228* Free Software:: Freely redistributable software 229* Contributors:: Contributors to GDB 230@end menu 231 232@node Free Software 233@unnumberedsec Free Software 234 235@value{GDBN} is @dfn{free software}, protected by the @sc{gnu} 236General Public License 237(GPL). The GPL gives you the freedom to copy or adapt a licensed 238program---but every person getting a copy also gets with it the 239freedom to modify that copy (which means that they must get access to 240the source code), and the freedom to distribute further copies. 241Typical software companies use copyrights to limit your freedoms; the 242Free Software Foundation uses the GPL to preserve these freedoms. 243 244Fundamentally, the General Public License is a license which says that 245you have these freedoms and that you cannot take these freedoms away 246from anyone else. 247 248@unnumberedsec Free Software Needs Free Documentation 249 250The biggest deficiency in the free software community today is not in 251the software---it is the lack of good free documentation that we can 252include with the free software. Many of our most important 253programs do not come with free reference manuals and free introductory 254texts. Documentation is an essential part of any software package; 255when an important free software package does not come with a free 256manual and a free tutorial, that is a major gap. We have many such 257gaps today. 258 259Consider Perl, for instance. The tutorial manuals that people 260normally use are non-free. How did this come about? Because the 261authors of those manuals published them with restrictive terms---no 262copying, no modification, source files not available---which exclude 263them from the free software world. 264 265That wasn't the first time this sort of thing happened, and it was far 266from the last. Many times we have heard a GNU user eagerly describe a 267manual that he is writing, his intended contribution to the community, 268only to learn that he had ruined everything by signing a publication 269contract to make it non-free. 270 271Free documentation, like free software, is a matter of freedom, not 272price. The problem with the non-free manual is not that publishers 273charge a price for printed copies---that in itself is fine. (The Free 274Software Foundation sells printed copies of manuals, too.) The 275problem is the restrictions on the use of the manual. Free manuals 276are available in source code form, and give you permission to copy and 277modify. Non-free manuals do not allow this. 278 279The criteria of freedom for a free manual are roughly the same as for 280free software. Redistribution (including the normal kinds of 281commercial redistribution) must be permitted, so that the manual can 282accompany every copy of the program, both on-line and on paper. 283 284Permission for modification of the technical content is crucial too. 285When people modify the software, adding or changing features, if they 286are conscientious they will change the manual too---so they can 287provide accurate and clear documentation for the modified program. A 288manual that leaves you no choice but to write a new manual to document 289a changed version of the program is not really available to our 290community. 291 292Some kinds of limits on the way modification is handled are 293acceptable. For example, requirements to preserve the original 294author's copyright notice, the distribution terms, or the list of 295authors, are ok. It is also no problem to require modified versions 296to include notice that they were modified. Even entire sections that 297may not be deleted or changed are acceptable, as long as they deal 298with nontechnical topics (like this one). These kinds of restrictions 299are acceptable because they don't obstruct the community's normal use 300of the manual. 301 302However, it must be possible to modify all the @emph{technical} 303content of the manual, and then distribute the result in all the usual 304media, through all the usual channels. Otherwise, the restrictions 305obstruct the use of the manual, it is not free, and we need another 306manual to replace it. 307 308Please spread the word about this issue. Our community continues to 309lose manuals to proprietary publishing. If we spread the word that 310free software needs free reference manuals and free tutorials, perhaps 311the next person who wants to contribute by writing documentation will 312realize, before it is too late, that only free manuals contribute to 313the free software community. 314 315If you are writing documentation, please insist on publishing it under 316the GNU Free Documentation License or another free documentation 317license. Remember that this decision requires your approval---you 318don't have to let the publisher decide. Some commercial publishers 319will use a free license if you insist, but they will not propose the 320option; it is up to you to raise the issue and say firmly that this is 321what you want. If the publisher you are dealing with refuses, please 322try other publishers. If you're not sure whether a proposed license 323is free, write to @email{licensing@@gnu.org}. 324 325You can encourage commercial publishers to sell more free, copylefted 326manuals and tutorials by buying them, and particularly by buying 327copies from the publishers that paid for their writing or for major 328improvements. Meanwhile, try to avoid buying non-free documentation 329at all. Check the distribution terms of a manual before you buy it, 330and insist that whoever seeks your business must respect your freedom. 331Check the history of the book, and try to reward the publishers that 332have paid or pay the authors to work on it. 333 334The Free Software Foundation maintains a list of free documentation 335published by other publishers, at 336@url{http://www.fsf.org/doc/other-free-books.html}. 337 338@node Contributors 339@unnumberedsec Contributors to @value{GDBN} 340 341Richard Stallman was the original author of @value{GDBN}, and of many 342other @sc{gnu} programs. Many others have contributed to its 343development. This section attempts to credit major contributors. One 344of the virtues of free software is that everyone is free to contribute 345to it; with regret, we cannot actually acknowledge everyone here. The 346file @file{ChangeLog} in the @value{GDBN} distribution approximates a 347blow-by-blow account. 348 349Changes much prior to version 2.0 are lost in the mists of time. 350 351@quotation 352@emph{Plea:} Additions to this section are particularly welcome. If you 353or your friends (or enemies, to be evenhanded) have been unfairly 354omitted from this list, we would like to add your names! 355@end quotation 356 357So that they may not regard their many labors as thankless, we 358particularly thank those who shepherded @value{GDBN} through major 359releases: 360Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); 361Jim Blandy (release 4.18); 362Jason Molenda (release 4.17); 363Stan Shebs (release 4.14); 364Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9); 365Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4); 366John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); 367Jim Kingdon (releases 3.5, 3.4, and 3.3); 368and Randy Smith (releases 3.2, 3.1, and 3.0). 369 370Richard Stallman, assisted at various times by Peter TerMaat, Chris 371Hanson, and Richard Mlynarik, handled releases through 2.8. 372 373Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support 374in @value{GDBN}, with significant additional contributions from Per 375Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++} 376demangler. Early work on C@t{++} was by Peter TerMaat (who also did 377much general update work leading to release 3.0). 378 379@value{GDBN} uses the BFD subroutine library to examine multiple 380object-file formats; BFD was a joint project of David V. 381Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore. 382 383David Johnson wrote the original COFF support; Pace Willison did 384the original support for encapsulated COFF. 385 386Brent Benson of Harris Computer Systems contributed DWARF 2 support. 387 388Adam de Boor and Bradley Davis contributed the ISI Optimum V support. 389Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS 390support. 391Jean-Daniel Fekete contributed Sun 386i support. 392Chris Hanson improved the HP9000 support. 393Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support. 394David Johnson contributed Encore Umax support. 395Jyrki Kuoppala contributed Altos 3068 support. 396Jeff Law contributed HP PA and SOM support. 397Keith Packard contributed NS32K support. 398Doug Rabson contributed Acorn Risc Machine support. 399Bob Rusk contributed Harris Nighthawk CX-UX support. 400Chris Smith contributed Convex support (and Fortran debugging). 401Jonathan Stone contributed Pyramid support. 402Michael Tiemann contributed SPARC support. 403Tim Tucker contributed support for the Gould NP1 and Gould Powernode. 404Pace Willison contributed Intel 386 support. 405Jay Vosburgh contributed Symmetry support. 406Marko Mlinar contributed OpenRISC 1000 support. 407 408Andreas Schwab contributed M68K @sc{gnu}/Linux support. 409 410Rich Schaefer and Peter Schauer helped with support of SunOS shared 411libraries. 412 413Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree 414about several machine instruction sets. 415 416Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop 417remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM 418contributed remote debugging modules for the i960, VxWorks, A29K UDI, 419and RDI targets, respectively. 420 421Brian Fox is the author of the readline libraries providing 422command-line editing and command history. 423 424Andrew Beers of SUNY Buffalo wrote the language-switching code, the 425Modula-2 support, and contributed the Languages chapter of this manual. 426 427Fred Fish wrote most of the support for Unix System Vr4. 428He also enhanced the command-completion support to cover C@t{++} overloaded 429symbols. 430 431Hitachi America (now Renesas America), Ltd. sponsored the support for 432H8/300, H8/500, and Super-H processors. 433 434NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors. 435 436Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D 437processors. 438 439Toshiba sponsored the support for the TX39 Mips processor. 440 441Matsushita sponsored the support for the MN10200 and MN10300 processors. 442 443Fujitsu sponsored the support for SPARClite and FR30 processors. 444 445Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware 446watchpoints. 447 448Michael Snyder added support for tracepoints. 449 450Stu Grossman wrote gdbserver. 451 452Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made 453nearly innumerable bug fixes and cleanups throughout @value{GDBN}. 454 455The following people at the Hewlett-Packard Company contributed 456support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 457(narrow mode), HP's implementation of kernel threads, HP's aC@t{++} 458compiler, and the Text User Interface (nee Terminal User Interface): 459Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, 460Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase 461provided HP-specific information in this manual. 462 463DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project. 464Robert Hoehne made significant contributions to the DJGPP port. 465 466Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its 467development since 1991. Cygnus engineers who have worked on @value{GDBN} 468fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin 469Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim 470Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, 471Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek 472Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In 473addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, 474JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug 475Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff 476Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, 477Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin 478Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela 479Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David 480Zuhn have made contributions both large and small. 481 482Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for 483Cygnus Solutions, implemented the original @sc{gdb/mi} interface. 484 485Jim Blandy added support for preprocessor macros, while working for Red 486Hat. 487 488Andrew Cagney designed @value{GDBN}'s architecture vector. Many 489people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick 490Duffek, Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei 491Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason 492Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped 493with the migration of old architectures to this new framework. 494 495Andrew Cagney completely re-designed and re-implemented @value{GDBN}'s 496unwinder framework, this consisting of a fresh new design featuring 497frame IDs, independent frame sniffers, and the sentinel frame. Mark 498Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the 499libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and 500trad unwinders. The architecture-specific changes, each involving a 501complete rewrite of the architecture's frame code, were carried out by 502Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane 503Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel 504Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei 505Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich 506Weigand. 507 508Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from 509Tensilica, Inc.@: contributed support for Xtensa processors. Others 510who have worked on the Xtensa port of @value{GDBN} in the past include 511Steve Tjiang, John Newlin, and Scott Foehner. 512 513@node Sample Session 514@chapter A Sample @value{GDBN} Session 515 516You can use this manual at your leisure to read all about @value{GDBN}. 517However, a handful of commands are enough to get started using the 518debugger. This chapter illustrates those commands. 519 520@iftex 521In this sample session, we emphasize user input like this: @b{input}, 522to make it easier to pick out from the surrounding output. 523@end iftex 524 525@c FIXME: this example may not be appropriate for some configs, where 526@c FIXME...primary interest is in remote use. 527 528One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro 529processor) exhibits the following bug: sometimes, when we change its 530quote strings from the default, the commands used to capture one macro 531definition within another stop working. In the following short @code{m4} 532session, we define a macro @code{foo} which expands to @code{0000}; we 533then use the @code{m4} built-in @code{defn} to define @code{bar} as the 534same thing. However, when we change the open quote string to 535@code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same 536procedure fails to define a new synonym @code{baz}: 537 538@smallexample 539$ @b{cd gnu/m4} 540$ @b{./m4} 541@b{define(foo,0000)} 542 543@b{foo} 5440000 545@b{define(bar,defn(`foo'))} 546 547@b{bar} 5480000 549@b{changequote(<QUOTE>,<UNQUOTE>)} 550 551@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))} 552@b{baz} 553@b{Ctrl-d} 554m4: End of input: 0: fatal error: EOF in string 555@end smallexample 556 557@noindent 558Let us use @value{GDBN} to try to see what is going on. 559 560@smallexample 561$ @b{@value{GDBP} m4} 562@c FIXME: this falsifies the exact text played out, to permit smallbook 563@c FIXME... format to come out better. 564@value{GDBN} is free software and you are welcome to distribute copies 565 of it under certain conditions; type "show copying" to see 566 the conditions. 567There is absolutely no warranty for @value{GDBN}; type "show warranty" 568 for details. 569 570@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc... 571(@value{GDBP}) 572@end smallexample 573 574@noindent 575@value{GDBN} reads only enough symbol data to know where to find the 576rest when needed; as a result, the first prompt comes up very quickly. 577We now tell @value{GDBN} to use a narrower display width than usual, so 578that examples fit in this manual. 579 580@smallexample 581(@value{GDBP}) @b{set width 70} 582@end smallexample 583 584@noindent 585We need to see how the @code{m4} built-in @code{changequote} works. 586Having looked at the source, we know the relevant subroutine is 587@code{m4_changequote}, so we set a breakpoint there with the @value{GDBN} 588@code{break} command. 589 590@smallexample 591(@value{GDBP}) @b{break m4_changequote} 592Breakpoint 1 at 0x62f4: file builtin.c, line 879. 593@end smallexample 594 595@noindent 596Using the @code{run} command, we start @code{m4} running under @value{GDBN} 597control; as long as control does not reach the @code{m4_changequote} 598subroutine, the program runs as usual: 599 600@smallexample 601(@value{GDBP}) @b{run} 602Starting program: /work/Editorial/gdb/gnu/m4/m4 603@b{define(foo,0000)} 604 605@b{foo} 6060000 607@end smallexample 608 609@noindent 610To trigger the breakpoint, we call @code{changequote}. @value{GDBN} 611suspends execution of @code{m4}, displaying information about the 612context where it stops. 613 614@smallexample 615@b{changequote(<QUOTE>,<UNQUOTE>)} 616 617Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) 618 at builtin.c:879 619879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) 620@end smallexample 621 622@noindent 623Now we use the command @code{n} (@code{next}) to advance execution to 624the next line of the current function. 625 626@smallexample 627(@value{GDBP}) @b{n} 628882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ 629 : nil, 630@end smallexample 631 632@noindent 633@code{set_quotes} looks like a promising subroutine. We can go into it 634by using the command @code{s} (@code{step}) instead of @code{next}. 635@code{step} goes to the next line to be executed in @emph{any} 636subroutine, so it steps into @code{set_quotes}. 637 638@smallexample 639(@value{GDBP}) @b{s} 640set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 641 at input.c:530 642530 if (lquote != def_lquote) 643@end smallexample 644 645@noindent 646The display that shows the subroutine where @code{m4} is now 647suspended (and its arguments) is called a stack frame display. It 648shows a summary of the stack. We can use the @code{backtrace} 649command (which can also be spelled @code{bt}), to see where we are 650in the stack as a whole: the @code{backtrace} command displays a 651stack frame for each active subroutine. 652 653@smallexample 654(@value{GDBP}) @b{bt} 655#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 656 at input.c:530 657#1 0x6344 in m4_changequote (argc=3, argv=0x33c70) 658 at builtin.c:882 659#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 660#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) 661 at macro.c:71 662#4 0x79dc in expand_input () at macro.c:40 663#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 664@end smallexample 665 666@noindent 667We step through a few more lines to see what happens. The first two 668times, we can use @samp{s}; the next two times we use @code{n} to avoid 669falling into the @code{xstrdup} subroutine. 670 671@smallexample 672(@value{GDBP}) @b{s} 6730x3b5c 532 if (rquote != def_rquote) 674(@value{GDBP}) @b{s} 6750x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ 676def_lquote : xstrdup(lq); 677(@value{GDBP}) @b{n} 678536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 679 : xstrdup(rq); 680(@value{GDBP}) @b{n} 681538 len_lquote = strlen(rquote); 682@end smallexample 683 684@noindent 685The last line displayed looks a little odd; we can examine the variables 686@code{lquote} and @code{rquote} to see if they are in fact the new left 687and right quotes we specified. We use the command @code{p} 688(@code{print}) to see their values. 689 690@smallexample 691(@value{GDBP}) @b{p lquote} 692$1 = 0x35d40 "<QUOTE>" 693(@value{GDBP}) @b{p rquote} 694$2 = 0x35d50 "<UNQUOTE>" 695@end smallexample 696 697@noindent 698@code{lquote} and @code{rquote} are indeed the new left and right quotes. 699To look at some context, we can display ten lines of source 700surrounding the current line with the @code{l} (@code{list}) command. 701 702@smallexample 703(@value{GDBP}) @b{l} 704533 xfree(rquote); 705534 706535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ 707 : xstrdup (lq); 708536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 709 : xstrdup (rq); 710537 711538 len_lquote = strlen(rquote); 712539 len_rquote = strlen(lquote); 713540 @} 714541 715542 void 716@end smallexample 717 718@noindent 719Let us step past the two lines that set @code{len_lquote} and 720@code{len_rquote}, and then examine the values of those variables. 721 722@smallexample 723(@value{GDBP}) @b{n} 724539 len_rquote = strlen(lquote); 725(@value{GDBP}) @b{n} 726540 @} 727(@value{GDBP}) @b{p len_lquote} 728$3 = 9 729(@value{GDBP}) @b{p len_rquote} 730$4 = 7 731@end smallexample 732 733@noindent 734That certainly looks wrong, assuming @code{len_lquote} and 735@code{len_rquote} are meant to be the lengths of @code{lquote} and 736@code{rquote} respectively. We can set them to better values using 737the @code{p} command, since it can print the value of 738any expression---and that expression can include subroutine calls and 739assignments. 740 741@smallexample 742(@value{GDBP}) @b{p len_lquote=strlen(lquote)} 743$5 = 7 744(@value{GDBP}) @b{p len_rquote=strlen(rquote)} 745$6 = 9 746@end smallexample 747 748@noindent 749Is that enough to fix the problem of using the new quotes with the 750@code{m4} built-in @code{defn}? We can allow @code{m4} to continue 751executing with the @code{c} (@code{continue}) command, and then try the 752example that caused trouble initially: 753 754@smallexample 755(@value{GDBP}) @b{c} 756Continuing. 757 758@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))} 759 760baz 7610000 762@end smallexample 763 764@noindent 765Success! The new quotes now work just as well as the default ones. The 766problem seems to have been just the two typos defining the wrong 767lengths. We allow @code{m4} exit by giving it an EOF as input: 768 769@smallexample 770@b{Ctrl-d} 771Program exited normally. 772@end smallexample 773 774@noindent 775The message @samp{Program exited normally.} is from @value{GDBN}; it 776indicates @code{m4} has finished executing. We can end our @value{GDBN} 777session with the @value{GDBN} @code{quit} command. 778 779@smallexample 780(@value{GDBP}) @b{quit} 781@end smallexample 782 783@node Invocation 784@chapter Getting In and Out of @value{GDBN} 785 786This chapter discusses how to start @value{GDBN}, and how to get out of it. 787The essentials are: 788@itemize @bullet 789@item 790type @samp{@value{GDBP}} to start @value{GDBN}. 791@item 792type @kbd{quit} or @kbd{Ctrl-d} to exit. 793@end itemize 794 795@menu 796* Invoking GDB:: How to start @value{GDBN} 797* Quitting GDB:: How to quit @value{GDBN} 798* Shell Commands:: How to use shell commands inside @value{GDBN} 799* Logging Output:: How to log @value{GDBN}'s output to a file 800@end menu 801 802@node Invoking GDB 803@section Invoking @value{GDBN} 804 805Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started, 806@value{GDBN} reads commands from the terminal until you tell it to exit. 807 808You can also run @code{@value{GDBP}} with a variety of arguments and options, 809to specify more of your debugging environment at the outset. 810 811The command-line options described here are designed 812to cover a variety of situations; in some environments, some of these 813options may effectively be unavailable. 814 815The most usual way to start @value{GDBN} is with one argument, 816specifying an executable program: 817 818@smallexample 819@value{GDBP} @var{program} 820@end smallexample 821 822@noindent 823You can also start with both an executable program and a core file 824specified: 825 826@smallexample 827@value{GDBP} @var{program} @var{core} 828@end smallexample 829 830You can, instead, specify a process ID as a second argument, if you want 831to debug a running process: 832 833@smallexample 834@value{GDBP} @var{program} 1234 835@end smallexample 836 837@noindent 838would attach @value{GDBN} to process @code{1234} (unless you also have a file 839named @file{1234}; @value{GDBN} does check for a core file first). 840 841Taking advantage of the second command-line argument requires a fairly 842complete operating system; when you use @value{GDBN} as a remote 843debugger attached to a bare board, there may not be any notion of 844``process'', and there is often no way to get a core dump. @value{GDBN} 845will warn you if it is unable to attach or to read core dumps. 846 847You can optionally have @code{@value{GDBP}} pass any arguments after the 848executable file to the inferior using @code{--args}. This option stops 849option processing. 850@smallexample 851@value{GDBP} --args gcc -O2 -c foo.c 852@end smallexample 853This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set 854@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}. 855 856You can run @code{@value{GDBP}} without printing the front material, which describes 857@value{GDBN}'s non-warranty, by specifying @code{-silent}: 858 859@smallexample 860@value{GDBP} -silent 861@end smallexample 862 863@noindent 864You can further control how @value{GDBN} starts up by using command-line 865options. @value{GDBN} itself can remind you of the options available. 866 867@noindent 868Type 869 870@smallexample 871@value{GDBP} -help 872@end smallexample 873 874@noindent 875to display all available options and briefly describe their use 876(@samp{@value{GDBP} -h} is a shorter equivalent). 877 878All options and command line arguments you give are processed 879in sequential order. The order makes a difference when the 880@samp{-x} option is used. 881 882 883@menu 884* File Options:: Choosing files 885* Mode Options:: Choosing modes 886* Startup:: What @value{GDBN} does during startup 887@end menu 888 889@node File Options 890@subsection Choosing Files 891 892When @value{GDBN} starts, it reads any arguments other than options as 893specifying an executable file and core file (or process ID). This is 894the same as if the arguments were specified by the @samp{-se} and 895@samp{-c} (or @samp{-p}) options respectively. (@value{GDBN} reads the 896first argument that does not have an associated option flag as 897equivalent to the @samp{-se} option followed by that argument; and the 898second argument that does not have an associated option flag, if any, as 899equivalent to the @samp{-c}/@samp{-p} option followed by that argument.) 900If the second argument begins with a decimal digit, @value{GDBN} will 901first attempt to attach to it as a process, and if that fails, attempt 902to open it as a corefile. If you have a corefile whose name begins with 903a digit, you can prevent @value{GDBN} from treating it as a pid by 904prefixing it with @file{./}, e.g.@: @file{./12345}. 905 906If @value{GDBN} has not been configured to included core file support, 907such as for most embedded targets, then it will complain about a second 908argument and ignore it. 909 910Many options have both long and short forms; both are shown in the 911following list. @value{GDBN} also recognizes the long forms if you truncate 912them, so long as enough of the option is present to be unambiguous. 913(If you prefer, you can flag option arguments with @samp{--} rather 914than @samp{-}, though we illustrate the more usual convention.) 915 916@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This 917@c way, both those who look for -foo and --foo in the index, will find 918@c it. 919 920@table @code 921@item -symbols @var{file} 922@itemx -s @var{file} 923@cindex @code{--symbols} 924@cindex @code{-s} 925Read symbol table from file @var{file}. 926 927@item -exec @var{file} 928@itemx -e @var{file} 929@cindex @code{--exec} 930@cindex @code{-e} 931Use file @var{file} as the executable file to execute when appropriate, 932and for examining pure data in conjunction with a core dump. 933 934@item -se @var{file} 935@cindex @code{--se} 936Read symbol table from file @var{file} and use it as the executable 937file. 938 939@item -core @var{file} 940@itemx -c @var{file} 941@cindex @code{--core} 942@cindex @code{-c} 943Use file @var{file} as a core dump to examine. 944 945@item -c @var{number} 946@item -pid @var{number} 947@itemx -p @var{number} 948@cindex @code{--pid} 949@cindex @code{-p} 950Connect to process ID @var{number}, as with the @code{attach} command. 951If there is no such process, @value{GDBN} will attempt to open a core 952file named @var{number}. 953 954@item -command @var{file} 955@itemx -x @var{file} 956@cindex @code{--command} 957@cindex @code{-x} 958Execute @value{GDBN} commands from file @var{file}. @xref{Command 959Files,, Command files}. 960 961@item -eval-command @var{command} 962@itemx -ex @var{command} 963@cindex @code{--eval-command} 964@cindex @code{-ex} 965Execute a single @value{GDBN} command. 966 967This option may be used multiple times to call multiple commands. It may 968also be interleaved with @samp{-command} as required. 969 970@smallexample 971@value{GDBP} -ex 'target sim' -ex 'load' \ 972 -x setbreakpoints -ex 'run' a.out 973@end smallexample 974 975@item -directory @var{directory} 976@itemx -d @var{directory} 977@cindex @code{--directory} 978@cindex @code{-d} 979Add @var{directory} to the path to search for source and script files. 980 981@item -r 982@itemx -readnow 983@cindex @code{--readnow} 984@cindex @code{-r} 985Read each symbol file's entire symbol table immediately, rather than 986the default, which is to read it incrementally as it is needed. 987This makes startup slower, but makes future operations faster. 988 989@end table 990 991@node Mode Options 992@subsection Choosing Modes 993 994You can run @value{GDBN} in various alternative modes---for example, in 995batch mode or quiet mode. 996 997@table @code 998@item -nx 999@itemx -n 1000@cindex @code{--nx} 1001@cindex @code{-n} 1002Do not execute commands found in any initialization files. Normally, 1003@value{GDBN} executes the commands in these files after all the command 1004options and arguments have been processed. @xref{Command Files,,Command 1005Files}. 1006 1007@item -quiet 1008@itemx -silent 1009@itemx -q 1010@cindex @code{--quiet} 1011@cindex @code{--silent} 1012@cindex @code{-q} 1013``Quiet''. Do not print the introductory and copyright messages. These 1014messages are also suppressed in batch mode. 1015 1016@item -batch 1017@cindex @code{--batch} 1018Run in batch mode. Exit with status @code{0} after processing all the 1019command files specified with @samp{-x} (and all commands from 1020initialization files, if not inhibited with @samp{-n}). Exit with 1021nonzero status if an error occurs in executing the @value{GDBN} commands 1022in the command files. 1023 1024Batch mode may be useful for running @value{GDBN} as a filter, for 1025example to download and run a program on another computer; in order to 1026make this more useful, the message 1027 1028@smallexample 1029Program exited normally. 1030@end smallexample 1031 1032@noindent 1033(which is ordinarily issued whenever a program running under 1034@value{GDBN} control terminates) is not issued when running in batch 1035mode. 1036 1037@item -batch-silent 1038@cindex @code{--batch-silent} 1039Run in batch mode exactly like @samp{-batch}, but totally silently. All 1040@value{GDBN} output to @code{stdout} is prevented (@code{stderr} is 1041unaffected). This is much quieter than @samp{-silent} and would be useless 1042for an interactive session. 1043 1044This is particularly useful when using targets that give @samp{Loading section} 1045messages, for example. 1046 1047Note that targets that give their output via @value{GDBN}, as opposed to 1048writing directly to @code{stdout}, will also be made silent. 1049 1050@item -return-child-result 1051@cindex @code{--return-child-result} 1052The return code from @value{GDBN} will be the return code from the child 1053process (the process being debugged), with the following exceptions: 1054 1055@itemize @bullet 1056@item 1057@value{GDBN} exits abnormally. E.g., due to an incorrect argument or an 1058internal error. In this case the exit code is the same as it would have been 1059without @samp{-return-child-result}. 1060@item 1061The user quits with an explicit value. E.g., @samp{quit 1}. 1062@item 1063The child process never runs, or is not allowed to terminate, in which case 1064the exit code will be -1. 1065@end itemize 1066 1067This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent}, 1068when @value{GDBN} is being used as a remote program loader or simulator 1069interface. 1070 1071@item -nowindows 1072@itemx -nw 1073@cindex @code{--nowindows} 1074@cindex @code{-nw} 1075``No windows''. If @value{GDBN} comes with a graphical user interface 1076(GUI) built in, then this option tells @value{GDBN} to only use the command-line 1077interface. If no GUI is available, this option has no effect. 1078 1079@item -windows 1080@itemx -w 1081@cindex @code{--windows} 1082@cindex @code{-w} 1083If @value{GDBN} includes a GUI, then this option requires it to be 1084used if possible. 1085 1086@item -cd @var{directory} 1087@cindex @code{--cd} 1088Run @value{GDBN} using @var{directory} as its working directory, 1089instead of the current directory. 1090 1091@item -fullname 1092@itemx -f 1093@cindex @code{--fullname} 1094@cindex @code{-f} 1095@sc{gnu} Emacs sets this option when it runs @value{GDBN} as a 1096subprocess. It tells @value{GDBN} to output the full file name and line 1097number in a standard, recognizable fashion each time a stack frame is 1098displayed (which includes each time your program stops). This 1099recognizable format looks like two @samp{\032} characters, followed by 1100the file name, line number and character position separated by colons, 1101and a newline. The Emacs-to-@value{GDBN} interface program uses the two 1102@samp{\032} characters as a signal to display the source code for the 1103frame. 1104 1105@item -epoch 1106@cindex @code{--epoch} 1107The Epoch Emacs-@value{GDBN} interface sets this option when it runs 1108@value{GDBN} as a subprocess. It tells @value{GDBN} to modify its print 1109routines so as to allow Epoch to display values of expressions in a 1110separate window. 1111 1112@item -annotate @var{level} 1113@cindex @code{--annotate} 1114This option sets the @dfn{annotation level} inside @value{GDBN}. Its 1115effect is identical to using @samp{set annotate @var{level}} 1116(@pxref{Annotations}). The annotation @var{level} controls how much 1117information @value{GDBN} prints together with its prompt, values of 1118expressions, source lines, and other types of output. Level 0 is the 1119normal, level 1 is for use when @value{GDBN} is run as a subprocess of 1120@sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs 1121that control @value{GDBN}, and level 2 has been deprecated. 1122 1123The annotation mechanism has largely been superseded by @sc{gdb/mi} 1124(@pxref{GDB/MI}). 1125 1126@item --args 1127@cindex @code{--args} 1128Change interpretation of command line so that arguments following the 1129executable file are passed as command line arguments to the inferior. 1130This option stops option processing. 1131 1132@item -baud @var{bps} 1133@itemx -b @var{bps} 1134@cindex @code{--baud} 1135@cindex @code{-b} 1136Set the line speed (baud rate or bits per second) of any serial 1137interface used by @value{GDBN} for remote debugging. 1138 1139@item -l @var{timeout} 1140@cindex @code{-l} 1141Set the timeout (in seconds) of any communication used by @value{GDBN} 1142for remote debugging. 1143 1144@item -tty @var{device} 1145@itemx -t @var{device} 1146@cindex @code{--tty} 1147@cindex @code{-t} 1148Run using @var{device} for your program's standard input and output. 1149@c FIXME: kingdon thinks there is more to -tty. Investigate. 1150 1151@c resolve the situation of these eventually 1152@item -tui 1153@cindex @code{--tui} 1154Activate the @dfn{Text User Interface} when starting. The Text User 1155Interface manages several text windows on the terminal, showing 1156source, assembly, registers and @value{GDBN} command outputs 1157(@pxref{TUI, ,@value{GDBN} Text User Interface}). Alternatively, the 1158Text User Interface can be enabled by invoking the program 1159@samp{@value{GDBTUI}}. Do not use this option if you run @value{GDBN} from 1160Emacs (@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}). 1161 1162@c @item -xdb 1163@c @cindex @code{--xdb} 1164@c Run in XDB compatibility mode, allowing the use of certain XDB commands. 1165@c For information, see the file @file{xdb_trans.html}, which is usually 1166@c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX 1167@c systems. 1168 1169@item -interpreter @var{interp} 1170@cindex @code{--interpreter} 1171Use the interpreter @var{interp} for interface with the controlling 1172program or device. This option is meant to be set by programs which 1173communicate with @value{GDBN} using it as a back end. 1174@xref{Interpreters, , Command Interpreters}. 1175 1176@samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes 1177@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} (@pxref{GDB/MI, , 1178The @sc{gdb/mi} Interface}) included since @value{GDBN} version 6.0. The 1179previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and 1180selected with @samp{--interpreter=mi1}, is deprecated. Earlier 1181@sc{gdb/mi} interfaces are no longer supported. 1182 1183@item -write 1184@cindex @code{--write} 1185Open the executable and core files for both reading and writing. This 1186is equivalent to the @samp{set write on} command inside @value{GDBN} 1187(@pxref{Patching}). 1188 1189@item -statistics 1190@cindex @code{--statistics} 1191This option causes @value{GDBN} to print statistics about time and 1192memory usage after it completes each command and returns to the prompt. 1193 1194@item -version 1195@cindex @code{--version} 1196This option causes @value{GDBN} to print its version number and 1197no-warranty blurb, and exit. 1198 1199@end table 1200 1201@node Startup 1202@subsection What @value{GDBN} Does During Startup 1203@cindex @value{GDBN} startup 1204 1205Here's the description of what @value{GDBN} does during session startup: 1206 1207@enumerate 1208@item 1209Sets up the command interpreter as specified by the command line 1210(@pxref{Mode Options, interpreter}). 1211 1212@item 1213@cindex init file 1214Reads the @dfn{init file} (if any) in your home directory@footnote{On 1215DOS/Windows systems, the home directory is the one pointed to by the 1216@code{HOME} environment variable.} and executes all the commands in 1217that file. 1218 1219@item 1220Processes command line options and operands. 1221 1222@item 1223Reads and executes the commands from init file (if any) in the current 1224working directory. This is only done if the current directory is 1225different from your home directory. Thus, you can have more than one 1226init file, one generic in your home directory, and another, specific 1227to the program you are debugging, in the directory where you invoke 1228@value{GDBN}. 1229 1230@item 1231Reads command files specified by the @samp{-x} option. @xref{Command 1232Files}, for more details about @value{GDBN} command files. 1233 1234@item 1235Reads the command history recorded in the @dfn{history file}. 1236@xref{Command History}, for more details about the command history and the 1237files where @value{GDBN} records it. 1238@end enumerate 1239 1240Init files use the same syntax as @dfn{command files} (@pxref{Command 1241Files}) and are processed by @value{GDBN} in the same way. The init 1242file in your home directory can set options (such as @samp{set 1243complaints}) that affect subsequent processing of command line options 1244and operands. Init files are not executed if you use the @samp{-nx} 1245option (@pxref{Mode Options, ,Choosing Modes}). 1246 1247@cindex init file name 1248@cindex @file{.gdbinit} 1249@cindex @file{gdb.ini} 1250The @value{GDBN} init files are normally called @file{.gdbinit}. 1251The DJGPP port of @value{GDBN} uses the name @file{gdb.ini}, due to 1252the limitations of file names imposed by DOS filesystems. The Windows 1253ports of @value{GDBN} use the standard name, but if they find a 1254@file{gdb.ini} file, they warn you about that and suggest to rename 1255the file to the standard name. 1256 1257 1258@node Quitting GDB 1259@section Quitting @value{GDBN} 1260@cindex exiting @value{GDBN} 1261@cindex leaving @value{GDBN} 1262 1263@table @code 1264@kindex quit @r{[}@var{expression}@r{]} 1265@kindex q @r{(@code{quit})} 1266@item quit @r{[}@var{expression}@r{]} 1267@itemx q 1268To exit @value{GDBN}, use the @code{quit} command (abbreviated 1269@code{q}), or type an end-of-file character (usually @kbd{Ctrl-d}). If you 1270do not supply @var{expression}, @value{GDBN} will terminate normally; 1271otherwise it will terminate using the result of @var{expression} as the 1272error code. 1273@end table 1274 1275@cindex interrupt 1276An interrupt (often @kbd{Ctrl-c}) does not exit from @value{GDBN}, but rather 1277terminates the action of any @value{GDBN} command that is in progress and 1278returns to @value{GDBN} command level. It is safe to type the interrupt 1279character at any time because @value{GDBN} does not allow it to take effect 1280until a time when it is safe. 1281 1282If you have been using @value{GDBN} to control an attached process or 1283device, you can release it with the @code{detach} command 1284(@pxref{Attach, ,Debugging an Already-running Process}). 1285 1286@node Shell Commands 1287@section Shell Commands 1288 1289If you need to execute occasional shell commands during your 1290debugging session, there is no need to leave or suspend @value{GDBN}; you can 1291just use the @code{shell} command. 1292 1293@table @code 1294@kindex shell 1295@cindex shell escape 1296@item shell @var{command string} 1297Invoke a standard shell to execute @var{command string}. 1298If it exists, the environment variable @code{SHELL} determines which 1299shell to run. Otherwise @value{GDBN} uses the default shell 1300(@file{/bin/sh} on Unix systems, @file{COMMAND.COM} on MS-DOS, etc.). 1301@end table 1302 1303The utility @code{make} is often needed in development environments. 1304You do not have to use the @code{shell} command for this purpose in 1305@value{GDBN}: 1306 1307@table @code 1308@kindex make 1309@cindex calling make 1310@item make @var{make-args} 1311Execute the @code{make} program with the specified 1312arguments. This is equivalent to @samp{shell make @var{make-args}}. 1313@end table 1314 1315@node Logging Output 1316@section Logging Output 1317@cindex logging @value{GDBN} output 1318@cindex save @value{GDBN} output to a file 1319 1320You may want to save the output of @value{GDBN} commands to a file. 1321There are several commands to control @value{GDBN}'s logging. 1322 1323@table @code 1324@kindex set logging 1325@item set logging on 1326Enable logging. 1327@item set logging off 1328Disable logging. 1329@cindex logging file name 1330@item set logging file @var{file} 1331Change the name of the current logfile. The default logfile is @file{gdb.txt}. 1332@item set logging overwrite [on|off] 1333By default, @value{GDBN} will append to the logfile. Set @code{overwrite} if 1334you want @code{set logging on} to overwrite the logfile instead. 1335@item set logging redirect [on|off] 1336By default, @value{GDBN} output will go to both the terminal and the logfile. 1337Set @code{redirect} if you want output to go only to the log file. 1338@kindex show logging 1339@item show logging 1340Show the current values of the logging settings. 1341@end table 1342 1343@node Commands 1344@chapter @value{GDBN} Commands 1345 1346You can abbreviate a @value{GDBN} command to the first few letters of the command 1347name, if that abbreviation is unambiguous; and you can repeat certain 1348@value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB} 1349key to get @value{GDBN} to fill out the rest of a word in a command (or to 1350show you the alternatives available, if there is more than one possibility). 1351 1352@menu 1353* Command Syntax:: How to give commands to @value{GDBN} 1354* Completion:: Command completion 1355* Help:: How to ask @value{GDBN} for help 1356@end menu 1357 1358@node Command Syntax 1359@section Command Syntax 1360 1361A @value{GDBN} command is a single line of input. There is no limit on 1362how long it can be. It starts with a command name, which is followed by 1363arguments whose meaning depends on the command name. For example, the 1364command @code{step} accepts an argument which is the number of times to 1365step, as in @samp{step 5}. You can also use the @code{step} command 1366with no arguments. Some commands do not allow any arguments. 1367 1368@cindex abbreviation 1369@value{GDBN} command names may always be truncated if that abbreviation is 1370unambiguous. Other possible command abbreviations are listed in the 1371documentation for individual commands. In some cases, even ambiguous 1372abbreviations are allowed; for example, @code{s} is specially defined as 1373equivalent to @code{step} even though there are other commands whose 1374names start with @code{s}. You can test abbreviations by using them as 1375arguments to the @code{help} command. 1376 1377@cindex repeating commands 1378@kindex RET @r{(repeat last command)} 1379A blank line as input to @value{GDBN} (typing just @key{RET}) means to 1380repeat the previous command. Certain commands (for example, @code{run}) 1381will not repeat this way; these are commands whose unintentional 1382repetition might cause trouble and which you are unlikely to want to 1383repeat. User-defined commands can disable this feature; see 1384@ref{Define, dont-repeat}. 1385 1386The @code{list} and @code{x} commands, when you repeat them with 1387@key{RET}, construct new arguments rather than repeating 1388exactly as typed. This permits easy scanning of source or memory. 1389 1390@value{GDBN} can also use @key{RET} in another way: to partition lengthy 1391output, in a way similar to the common utility @code{more} 1392(@pxref{Screen Size,,Screen Size}). Since it is easy to press one 1393@key{RET} too many in this situation, @value{GDBN} disables command 1394repetition after any command that generates this sort of display. 1395 1396@kindex # @r{(a comment)} 1397@cindex comment 1398Any text from a @kbd{#} to the end of the line is a comment; it does 1399nothing. This is useful mainly in command files (@pxref{Command 1400Files,,Command Files}). 1401 1402@cindex repeating command sequences 1403@kindex Ctrl-o @r{(operate-and-get-next)} 1404The @kbd{Ctrl-o} binding is useful for repeating a complex sequence of 1405commands. This command accepts the current line, like @key{RET}, and 1406then fetches the next line relative to the current line from the history 1407for editing. 1408 1409@node Completion 1410@section Command Completion 1411 1412@cindex completion 1413@cindex word completion 1414@value{GDBN} can fill in the rest of a word in a command for you, if there is 1415only one possibility; it can also show you what the valid possibilities 1416are for the next word in a command, at any time. This works for @value{GDBN} 1417commands, @value{GDBN} subcommands, and the names of symbols in your program. 1418 1419Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest 1420of a word. If there is only one possibility, @value{GDBN} fills in the 1421word, and waits for you to finish the command (or press @key{RET} to 1422enter it). For example, if you type 1423 1424@c FIXME "@key" does not distinguish its argument sufficiently to permit 1425@c complete accuracy in these examples; space introduced for clarity. 1426@c If texinfo enhancements make it unnecessary, it would be nice to 1427@c replace " @key" by "@key" in the following... 1428@smallexample 1429(@value{GDBP}) info bre @key{TAB} 1430@end smallexample 1431 1432@noindent 1433@value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is 1434the only @code{info} subcommand beginning with @samp{bre}: 1435 1436@smallexample 1437(@value{GDBP}) info breakpoints 1438@end smallexample 1439 1440@noindent 1441You can either press @key{RET} at this point, to run the @code{info 1442breakpoints} command, or backspace and enter something else, if 1443@samp{breakpoints} does not look like the command you expected. (If you 1444were sure you wanted @code{info breakpoints} in the first place, you 1445might as well just type @key{RET} immediately after @samp{info bre}, 1446to exploit command abbreviations rather than command completion). 1447 1448If there is more than one possibility for the next word when you press 1449@key{TAB}, @value{GDBN} sounds a bell. You can either supply more 1450characters and try again, or just press @key{TAB} a second time; 1451@value{GDBN} displays all the possible completions for that word. For 1452example, you might want to set a breakpoint on a subroutine whose name 1453begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN} 1454just sounds the bell. Typing @key{TAB} again displays all the 1455function names in your program that begin with those characters, for 1456example: 1457 1458@smallexample 1459(@value{GDBP}) b make_ @key{TAB} 1460@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see: 1461make_a_section_from_file make_environ 1462make_abs_section make_function_type 1463make_blockvector make_pointer_type 1464make_cleanup make_reference_type 1465make_command make_symbol_completion_list 1466(@value{GDBP}) b make_ 1467@end smallexample 1468 1469@noindent 1470After displaying the available possibilities, @value{GDBN} copies your 1471partial input (@samp{b make_} in the example) so you can finish the 1472command. 1473 1474If you just want to see the list of alternatives in the first place, you 1475can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?} 1476means @kbd{@key{META} ?}. You can type this either by holding down a 1477key designated as the @key{META} shift on your keyboard (if there is 1478one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}. 1479 1480@cindex quotes in commands 1481@cindex completion of quoted strings 1482Sometimes the string you need, while logically a ``word'', may contain 1483parentheses or other characters that @value{GDBN} normally excludes from 1484its notion of a word. To permit word completion to work in this 1485situation, you may enclose words in @code{'} (single quote marks) in 1486@value{GDBN} commands. 1487 1488The most likely situation where you might need this is in typing the 1489name of a C@t{++} function. This is because C@t{++} allows function 1490overloading (multiple definitions of the same function, distinguished 1491by argument type). For example, when you want to set a breakpoint you 1492may need to distinguish whether you mean the version of @code{name} 1493that takes an @code{int} parameter, @code{name(int)}, or the version 1494that takes a @code{float} parameter, @code{name(float)}. To use the 1495word-completion facilities in this situation, type a single quote 1496@code{'} at the beginning of the function name. This alerts 1497@value{GDBN} that it may need to consider more information than usual 1498when you press @key{TAB} or @kbd{M-?} to request word completion: 1499 1500@smallexample 1501(@value{GDBP}) b 'bubble( @kbd{M-?} 1502bubble(double,double) bubble(int,int) 1503(@value{GDBP}) b 'bubble( 1504@end smallexample 1505 1506In some cases, @value{GDBN} can tell that completing a name requires using 1507quotes. When this happens, @value{GDBN} inserts the quote for you (while 1508completing as much as it can) if you do not type the quote in the first 1509place: 1510 1511@smallexample 1512(@value{GDBP}) b bub @key{TAB} 1513@exdent @value{GDBN} alters your input line to the following, and rings a bell: 1514(@value{GDBP}) b 'bubble( 1515@end smallexample 1516 1517@noindent 1518In general, @value{GDBN} can tell that a quote is needed (and inserts it) if 1519you have not yet started typing the argument list when you ask for 1520completion on an overloaded symbol. 1521 1522For more information about overloaded functions, see @ref{C Plus Plus 1523Expressions, ,C@t{++} Expressions}. You can use the command @code{set 1524overload-resolution off} to disable overload resolution; 1525see @ref{Debugging C Plus Plus, ,@value{GDBN} Features for C@t{++}}. 1526 1527 1528@node Help 1529@section Getting Help 1530@cindex online documentation 1531@kindex help 1532 1533You can always ask @value{GDBN} itself for information on its commands, 1534using the command @code{help}. 1535 1536@table @code 1537@kindex h @r{(@code{help})} 1538@item help 1539@itemx h 1540You can use @code{help} (abbreviated @code{h}) with no arguments to 1541display a short list of named classes of commands: 1542 1543@smallexample 1544(@value{GDBP}) help 1545List of classes of commands: 1546 1547aliases -- Aliases of other commands 1548breakpoints -- Making program stop at certain points 1549data -- Examining data 1550files -- Specifying and examining files 1551internals -- Maintenance commands 1552obscure -- Obscure features 1553running -- Running the program 1554stack -- Examining the stack 1555status -- Status inquiries 1556support -- Support facilities 1557tracepoints -- Tracing of program execution without 1558 stopping the program 1559user-defined -- User-defined commands 1560 1561Type "help" followed by a class name for a list of 1562commands in that class. 1563Type "help" followed by command name for full 1564documentation. 1565Command name abbreviations are allowed if unambiguous. 1566(@value{GDBP}) 1567@end smallexample 1568@c the above line break eliminates huge line overfull... 1569 1570@item help @var{class} 1571Using one of the general help classes as an argument, you can get a 1572list of the individual commands in that class. For example, here is the 1573help display for the class @code{status}: 1574 1575@smallexample 1576(@value{GDBP}) help status 1577Status inquiries. 1578 1579List of commands: 1580 1581@c Line break in "show" line falsifies real output, but needed 1582@c to fit in smallbook page size. 1583info -- Generic command for showing things 1584 about the program being debugged 1585show -- Generic command for showing things 1586 about the debugger 1587 1588Type "help" followed by command name for full 1589documentation. 1590Command name abbreviations are allowed if unambiguous. 1591(@value{GDBP}) 1592@end smallexample 1593 1594@item help @var{command} 1595With a command name as @code{help} argument, @value{GDBN} displays a 1596short paragraph on how to use that command. 1597 1598@kindex apropos 1599@item apropos @var{args} 1600The @code{apropos} command searches through all of the @value{GDBN} 1601commands, and their documentation, for the regular expression specified in 1602@var{args}. It prints out all matches found. For example: 1603 1604@smallexample 1605apropos reload 1606@end smallexample 1607 1608@noindent 1609results in: 1610 1611@smallexample 1612@c @group 1613set symbol-reloading -- Set dynamic symbol table reloading 1614 multiple times in one run 1615show symbol-reloading -- Show dynamic symbol table reloading 1616 multiple times in one run 1617@c @end group 1618@end smallexample 1619 1620@kindex complete 1621@item complete @var{args} 1622The @code{complete @var{args}} command lists all the possible completions 1623for the beginning of a command. Use @var{args} to specify the beginning of the 1624command you want completed. For example: 1625 1626@smallexample 1627complete i 1628@end smallexample 1629 1630@noindent results in: 1631 1632@smallexample 1633@group 1634if 1635ignore 1636info 1637inspect 1638@end group 1639@end smallexample 1640 1641@noindent This is intended for use by @sc{gnu} Emacs. 1642@end table 1643 1644In addition to @code{help}, you can use the @value{GDBN} commands @code{info} 1645and @code{show} to inquire about the state of your program, or the state 1646of @value{GDBN} itself. Each command supports many topics of inquiry; this 1647manual introduces each of them in the appropriate context. The listings 1648under @code{info} and under @code{show} in the Index point to 1649all the sub-commands. @xref{Index}. 1650 1651@c @group 1652@table @code 1653@kindex info 1654@kindex i @r{(@code{info})} 1655@item info 1656This command (abbreviated @code{i}) is for describing the state of your 1657program. For example, you can list the arguments given to your program 1658with @code{info args}, list the registers currently in use with @code{info 1659registers}, or list the breakpoints you have set with @code{info breakpoints}. 1660You can get a complete list of the @code{info} sub-commands with 1661@w{@code{help info}}. 1662 1663@kindex set 1664@item set 1665You can assign the result of an expression to an environment variable with 1666@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with 1667@code{set prompt $}. 1668 1669@kindex show 1670@item show 1671In contrast to @code{info}, @code{show} is for describing the state of 1672@value{GDBN} itself. 1673You can change most of the things you can @code{show}, by using the 1674related command @code{set}; for example, you can control what number 1675system is used for displays with @code{set radix}, or simply inquire 1676which is currently in use with @code{show radix}. 1677 1678@kindex info set 1679To display all the settable parameters and their current 1680values, you can use @code{show} with no arguments; you may also use 1681@code{info set}. Both commands produce the same display. 1682@c FIXME: "info set" violates the rule that "info" is for state of 1683@c FIXME...program. Ck w/ GNU: "info set" to be called something else, 1684@c FIXME...or change desc of rule---eg "state of prog and debugging session"? 1685@end table 1686@c @end group 1687 1688Here are three miscellaneous @code{show} subcommands, all of which are 1689exceptional in lacking corresponding @code{set} commands: 1690 1691@table @code 1692@kindex show version 1693@cindex @value{GDBN} version number 1694@item show version 1695Show what version of @value{GDBN} is running. You should include this 1696information in @value{GDBN} bug-reports. If multiple versions of 1697@value{GDBN} are in use at your site, you may need to determine which 1698version of @value{GDBN} you are running; as @value{GDBN} evolves, new 1699commands are introduced, and old ones may wither away. Also, many 1700system vendors ship variant versions of @value{GDBN}, and there are 1701variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well. 1702The version number is the same as the one announced when you start 1703@value{GDBN}. 1704 1705@kindex show copying 1706@kindex info copying 1707@cindex display @value{GDBN} copyright 1708@item show copying 1709@itemx info copying 1710Display information about permission for copying @value{GDBN}. 1711 1712@kindex show warranty 1713@kindex info warranty 1714@item show warranty 1715@itemx info warranty 1716Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty, 1717if your version of @value{GDBN} comes with one. 1718 1719@end table 1720 1721@node Running 1722@chapter Running Programs Under @value{GDBN} 1723 1724When you run a program under @value{GDBN}, you must first generate 1725debugging information when you compile it. 1726 1727You may start @value{GDBN} with its arguments, if any, in an environment 1728of your choice. If you are doing native debugging, you may redirect 1729your program's input and output, debug an already running process, or 1730kill a child process. 1731 1732@menu 1733* Compilation:: Compiling for debugging 1734* Starting:: Starting your program 1735* Arguments:: Your program's arguments 1736* Environment:: Your program's environment 1737 1738* Working Directory:: Your program's working directory 1739* Input/Output:: Your program's input and output 1740* Attach:: Debugging an already-running process 1741* Kill Process:: Killing the child process 1742 1743* Threads:: Debugging programs with multiple threads 1744* Processes:: Debugging programs with multiple processes 1745* Checkpoint/Restart:: Setting a @emph{bookmark} to return to later 1746@end menu 1747 1748@node Compilation 1749@section Compiling for Debugging 1750 1751In order to debug a program effectively, you need to generate 1752debugging information when you compile it. This debugging information 1753is stored in the object file; it describes the data type of each 1754variable or function and the correspondence between source line numbers 1755and addresses in the executable code. 1756 1757To request debugging information, specify the @samp{-g} option when you run 1758the compiler. 1759 1760Programs that are to be shipped to your customers are compiled with 1761optimizations, using the @samp{-O} compiler option. However, many 1762compilers are unable to handle the @samp{-g} and @samp{-O} options 1763together. Using those compilers, you cannot generate optimized 1764executables containing debugging information. 1765 1766@value{NGCC}, the @sc{gnu} C/C@t{++} compiler, supports @samp{-g} with or 1767without @samp{-O}, making it possible to debug optimized code. We 1768recommend that you @emph{always} use @samp{-g} whenever you compile a 1769program. You may think your program is correct, but there is no sense 1770in pushing your luck. 1771 1772@cindex optimized code, debugging 1773@cindex debugging optimized code 1774When you debug a program compiled with @samp{-g -O}, remember that the 1775optimizer is rearranging your code; the debugger shows you what is 1776really there. Do not be too surprised when the execution path does not 1777exactly match your source file! An extreme example: if you define a 1778variable, but never use it, @value{GDBN} never sees that 1779variable---because the compiler optimizes it out of existence. 1780 1781Some things do not work as well with @samp{-g -O} as with just 1782@samp{-g}, particularly on machines with instruction scheduling. If in 1783doubt, recompile with @samp{-g} alone, and if this fixes the problem, 1784please report it to us as a bug (including a test case!). 1785@xref{Variables}, for more information about debugging optimized code. 1786 1787Older versions of the @sc{gnu} C compiler permitted a variant option 1788@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this 1789format; if your @sc{gnu} C compiler has this option, do not use it. 1790 1791@value{GDBN} knows about preprocessor macros and can show you their 1792expansion (@pxref{Macros}). Most compilers do not include information 1793about preprocessor macros in the debugging information if you specify 1794the @option{-g} flag alone, because this information is rather large. 1795Version 3.1 and later of @value{NGCC}, the @sc{gnu} C compiler, 1796provides macro information if you specify the options 1797@option{-gdwarf-2} and @option{-g3}; the former option requests 1798debugging information in the Dwarf 2 format, and the latter requests 1799``extra information''. In the future, we hope to find more compact 1800ways to represent macro information, so that it can be included with 1801@option{-g} alone. 1802 1803@need 2000 1804@node Starting 1805@section Starting your Program 1806@cindex starting 1807@cindex running 1808 1809@table @code 1810@kindex run 1811@kindex r @r{(@code{run})} 1812@item run 1813@itemx r 1814Use the @code{run} command to start your program under @value{GDBN}. 1815You must first specify the program name (except on VxWorks) with an 1816argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of 1817@value{GDBN}}), or by using the @code{file} or @code{exec-file} command 1818(@pxref{Files, ,Commands to Specify Files}). 1819 1820@end table 1821 1822If you are running your program in an execution environment that 1823supports processes, @code{run} creates an inferior process and makes 1824that process run your program. (In environments without processes, 1825@code{run} jumps to the start of your program.) 1826 1827The execution of a program is affected by certain information it 1828receives from its superior. @value{GDBN} provides ways to specify this 1829information, which you must do @emph{before} starting your program. (You 1830can change it after starting your program, but such changes only affect 1831your program the next time you start it.) This information may be 1832divided into four categories: 1833 1834@table @asis 1835@item The @emph{arguments.} 1836Specify the arguments to give your program as the arguments of the 1837@code{run} command. If a shell is available on your target, the shell 1838is used to pass the arguments, so that you may use normal conventions 1839(such as wildcard expansion or variable substitution) in describing 1840the arguments. 1841In Unix systems, you can control which shell is used with the 1842@code{SHELL} environment variable. 1843@xref{Arguments, ,Your Program's Arguments}. 1844 1845@item The @emph{environment.} 1846Your program normally inherits its environment from @value{GDBN}, but you can 1847use the @value{GDBN} commands @code{set environment} and @code{unset 1848environment} to change parts of the environment that affect 1849your program. @xref{Environment, ,Your Program's Environment}. 1850 1851@item The @emph{working directory.} 1852Your program inherits its working directory from @value{GDBN}. You can set 1853the @value{GDBN} working directory with the @code{cd} command in @value{GDBN}. 1854@xref{Working Directory, ,Your Program's Working Directory}. 1855 1856@item The @emph{standard input and output.} 1857Your program normally uses the same device for standard input and 1858standard output as @value{GDBN} is using. You can redirect input and output 1859in the @code{run} command line, or you can use the @code{tty} command to 1860set a different device for your program. 1861@xref{Input/Output, ,Your Program's Input and Output}. 1862 1863@cindex pipes 1864@emph{Warning:} While input and output redirection work, you cannot use 1865pipes to pass the output of the program you are debugging to another 1866program; if you attempt this, @value{GDBN} is likely to wind up debugging the 1867wrong program. 1868@end table 1869 1870When you issue the @code{run} command, your program begins to execute 1871immediately. @xref{Stopping, ,Stopping and Continuing}, for discussion 1872of how to arrange for your program to stop. Once your program has 1873stopped, you may call functions in your program, using the @code{print} 1874or @code{call} commands. @xref{Data, ,Examining Data}. 1875 1876If the modification time of your symbol file has changed since the last 1877time @value{GDBN} read its symbols, @value{GDBN} discards its symbol 1878table, and reads it again. When it does this, @value{GDBN} tries to retain 1879your current breakpoints. 1880 1881@table @code 1882@kindex start 1883@item start 1884@cindex run to main procedure 1885The name of the main procedure can vary from language to language. 1886With C or C@t{++}, the main procedure name is always @code{main}, but 1887other languages such as Ada do not require a specific name for their 1888main procedure. The debugger provides a convenient way to start the 1889execution of the program and to stop at the beginning of the main 1890procedure, depending on the language used. 1891 1892The @samp{start} command does the equivalent of setting a temporary 1893breakpoint at the beginning of the main procedure and then invoking 1894the @samp{run} command. 1895 1896@cindex elaboration phase 1897Some programs contain an @dfn{elaboration} phase where some startup code is 1898executed before the main procedure is called. This depends on the 1899languages used to write your program. In C@t{++}, for instance, 1900constructors for static and global objects are executed before 1901@code{main} is called. It is therefore possible that the debugger stops 1902before reaching the main procedure. However, the temporary breakpoint 1903will remain to halt execution. 1904 1905Specify the arguments to give to your program as arguments to the 1906@samp{start} command. These arguments will be given verbatim to the 1907underlying @samp{run} command. Note that the same arguments will be 1908reused if no argument is provided during subsequent calls to 1909@samp{start} or @samp{run}. 1910 1911It is sometimes necessary to debug the program during elaboration. In 1912these cases, using the @code{start} command would stop the execution of 1913your program too late, as the program would have already completed the 1914elaboration phase. Under these circumstances, insert breakpoints in your 1915elaboration code before running your program. 1916@end table 1917 1918@node Arguments 1919@section Your Program's Arguments 1920 1921@cindex arguments (to your program) 1922The arguments to your program can be specified by the arguments of the 1923@code{run} command. 1924They are passed to a shell, which expands wildcard characters and 1925performs redirection of I/O, and thence to your program. Your 1926@code{SHELL} environment variable (if it exists) specifies what shell 1927@value{GDBN} uses. If you do not define @code{SHELL}, @value{GDBN} uses 1928the default shell (@file{/bin/sh} on Unix). 1929 1930On non-Unix systems, the program is usually invoked directly by 1931@value{GDBN}, which emulates I/O redirection via the appropriate system 1932calls, and the wildcard characters are expanded by the startup code of 1933the program, not by the shell. 1934 1935@code{run} with no arguments uses the same arguments used by the previous 1936@code{run}, or those set by the @code{set args} command. 1937 1938@table @code 1939@kindex set args 1940@item set args 1941Specify the arguments to be used the next time your program is run. If 1942@code{set args} has no arguments, @code{run} executes your program 1943with no arguments. Once you have run your program with arguments, 1944using @code{set args} before the next @code{run} is the only way to run 1945it again without arguments. 1946 1947@kindex show args 1948@item show args 1949Show the arguments to give your program when it is started. 1950@end table 1951 1952@node Environment 1953@section Your Program's Environment 1954 1955@cindex environment (of your program) 1956The @dfn{environment} consists of a set of environment variables and 1957their values. Environment variables conventionally record such things as 1958your user name, your home directory, your terminal type, and your search 1959path for programs to run. Usually you set up environment variables with 1960the shell and they are inherited by all the other programs you run. When 1961debugging, it can be useful to try running your program with a modified 1962environment without having to start @value{GDBN} over again. 1963 1964@table @code 1965@kindex path 1966@item path @var{directory} 1967Add @var{directory} to the front of the @code{PATH} environment variable 1968(the search path for executables) that will be passed to your program. 1969The value of @code{PATH} used by @value{GDBN} does not change. 1970You may specify several directory names, separated by whitespace or by a 1971system-dependent separator character (@samp{:} on Unix, @samp{;} on 1972MS-DOS and MS-Windows). If @var{directory} is already in the path, it 1973is moved to the front, so it is searched sooner. 1974 1975You can use the string @samp{$cwd} to refer to whatever is the current 1976working directory at the time @value{GDBN} searches the path. If you 1977use @samp{.} instead, it refers to the directory where you executed the 1978@code{path} command. @value{GDBN} replaces @samp{.} in the 1979@var{directory} argument (with the current path) before adding 1980@var{directory} to the search path. 1981@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to 1982@c document that, since repeating it would be a no-op. 1983 1984@kindex show paths 1985@item show paths 1986Display the list of search paths for executables (the @code{PATH} 1987environment variable). 1988 1989@kindex show environment 1990@item show environment @r{[}@var{varname}@r{]} 1991Print the value of environment variable @var{varname} to be given to 1992your program when it starts. If you do not supply @var{varname}, 1993print the names and values of all environment variables to be given to 1994your program. You can abbreviate @code{environment} as @code{env}. 1995 1996@kindex set environment 1997@item set environment @var{varname} @r{[}=@var{value}@r{]} 1998Set environment variable @var{varname} to @var{value}. The value 1999changes for your program only, not for @value{GDBN} itself. @var{value} may 2000be any string; the values of environment variables are just strings, and 2001any interpretation is supplied by your program itself. The @var{value} 2002parameter is optional; if it is eliminated, the variable is set to a 2003null value. 2004@c "any string" here does not include leading, trailing 2005@c blanks. Gnu asks: does anyone care? 2006 2007For example, this command: 2008 2009@smallexample 2010set env USER = foo 2011@end smallexample 2012 2013@noindent 2014tells the debugged program, when subsequently run, that its user is named 2015@samp{foo}. (The spaces around @samp{=} are used for clarity here; they 2016are not actually required.) 2017 2018@kindex unset environment 2019@item unset environment @var{varname} 2020Remove variable @var{varname} from the environment to be passed to your 2021program. This is different from @samp{set env @var{varname} =}; 2022@code{unset environment} removes the variable from the environment, 2023rather than assigning it an empty value. 2024@end table 2025 2026@emph{Warning:} On Unix systems, @value{GDBN} runs your program using 2027the shell indicated 2028by your @code{SHELL} environment variable if it exists (or 2029@code{/bin/sh} if not). If your @code{SHELL} variable names a shell 2030that runs an initialization file---such as @file{.cshrc} for C-shell, or 2031@file{.bashrc} for BASH---any variables you set in that file affect 2032your program. You may wish to move setting of environment variables to 2033files that are only run when you sign on, such as @file{.login} or 2034@file{.profile}. 2035 2036@node Working Directory 2037@section Your Program's Working Directory 2038 2039@cindex working directory (of your program) 2040Each time you start your program with @code{run}, it inherits its 2041working directory from the current working directory of @value{GDBN}. 2042The @value{GDBN} working directory is initially whatever it inherited 2043from its parent process (typically the shell), but you can specify a new 2044working directory in @value{GDBN} with the @code{cd} command. 2045 2046The @value{GDBN} working directory also serves as a default for the commands 2047that specify files for @value{GDBN} to operate on. @xref{Files, ,Commands to 2048Specify Files}. 2049 2050@table @code 2051@kindex cd 2052@cindex change working directory 2053@item cd @var{directory} 2054Set the @value{GDBN} working directory to @var{directory}. 2055 2056@kindex pwd 2057@item pwd 2058Print the @value{GDBN} working directory. 2059@end table 2060 2061It is generally impossible to find the current working directory of 2062the process being debugged (since a program can change its directory 2063during its run). If you work on a system where @value{GDBN} is 2064configured with the @file{/proc} support, you can use the @code{info 2065proc} command (@pxref{SVR4 Process Information}) to find out the 2066current working directory of the debuggee. 2067 2068@node Input/Output 2069@section Your Program's Input and Output 2070 2071@cindex redirection 2072@cindex i/o 2073@cindex terminal 2074By default, the program you run under @value{GDBN} does input and output to 2075the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal 2076to its own terminal modes to interact with you, but it records the terminal 2077modes your program was using and switches back to them when you continue 2078running your program. 2079 2080@table @code 2081@kindex info terminal 2082@item info terminal 2083Displays information recorded by @value{GDBN} about the terminal modes your 2084program is using. 2085@end table 2086 2087You can redirect your program's input and/or output using shell 2088redirection with the @code{run} command. For example, 2089 2090@smallexample 2091run > outfile 2092@end smallexample 2093 2094@noindent 2095starts your program, diverting its output to the file @file{outfile}. 2096 2097@kindex tty 2098@cindex controlling terminal 2099Another way to specify where your program should do input and output is 2100with the @code{tty} command. This command accepts a file name as 2101argument, and causes this file to be the default for future @code{run} 2102commands. It also resets the controlling terminal for the child 2103process, for future @code{run} commands. For example, 2104 2105@smallexample 2106tty /dev/ttyb 2107@end smallexample 2108 2109@noindent 2110directs that processes started with subsequent @code{run} commands 2111default to do input and output on the terminal @file{/dev/ttyb} and have 2112that as their controlling terminal. 2113 2114An explicit redirection in @code{run} overrides the @code{tty} command's 2115effect on the input/output device, but not its effect on the controlling 2116terminal. 2117 2118When you use the @code{tty} command or redirect input in the @code{run} 2119command, only the input @emph{for your program} is affected. The input 2120for @value{GDBN} still comes from your terminal. @code{tty} is an alias 2121for @code{set inferior-tty}. 2122 2123@cindex inferior tty 2124@cindex set inferior controlling terminal 2125You can use the @code{show inferior-tty} command to tell @value{GDBN} to 2126display the name of the terminal that will be used for future runs of your 2127program. 2128 2129@table @code 2130@item set inferior-tty /dev/ttyb 2131@kindex set inferior-tty 2132Set the tty for the program being debugged to /dev/ttyb. 2133 2134@item show inferior-tty 2135@kindex show inferior-tty 2136Show the current tty for the program being debugged. 2137@end table 2138 2139@node Attach 2140@section Debugging an Already-running Process 2141@kindex attach 2142@cindex attach 2143 2144@table @code 2145@item attach @var{process-id} 2146This command attaches to a running process---one that was started 2147outside @value{GDBN}. (@code{info files} shows your active 2148targets.) The command takes as argument a process ID. The usual way to 2149find out the @var{process-id} of a Unix process is with the @code{ps} utility, 2150or with the @samp{jobs -l} shell command. 2151 2152@code{attach} does not repeat if you press @key{RET} a second time after 2153executing the command. 2154@end table 2155 2156To use @code{attach}, your program must be running in an environment 2157which supports processes; for example, @code{attach} does not work for 2158programs on bare-board targets that lack an operating system. You must 2159also have permission to send the process a signal. 2160 2161When you use @code{attach}, the debugger finds the program running in 2162the process first by looking in the current working directory, then (if 2163the program is not found) by using the source file search path 2164(@pxref{Source Path, ,Specifying Source Directories}). You can also use 2165the @code{file} command to load the program. @xref{Files, ,Commands to 2166Specify Files}. 2167 2168The first thing @value{GDBN} does after arranging to debug the specified 2169process is to stop it. You can examine and modify an attached process 2170with all the @value{GDBN} commands that are ordinarily available when 2171you start processes with @code{run}. You can insert breakpoints; you 2172can step and continue; you can modify storage. If you would rather the 2173process continue running, you may use the @code{continue} command after 2174attaching @value{GDBN} to the process. 2175 2176@table @code 2177@kindex detach 2178@item detach 2179When you have finished debugging the attached process, you can use the 2180@code{detach} command to release it from @value{GDBN} control. Detaching 2181the process continues its execution. After the @code{detach} command, 2182that process and @value{GDBN} become completely independent once more, and you 2183are ready to @code{attach} another process or start one with @code{run}. 2184@code{detach} does not repeat if you press @key{RET} again after 2185executing the command. 2186@end table 2187 2188If you exit @value{GDBN} while you have an attached process, you detach 2189that process. If you use the @code{run} command, you kill that process. 2190By default, @value{GDBN} asks for confirmation if you try to do either of these 2191things; you can control whether or not you need to confirm by using the 2192@code{set confirm} command (@pxref{Messages/Warnings, ,Optional Warnings and 2193Messages}). 2194 2195@node Kill Process 2196@section Killing the Child Process 2197 2198@table @code 2199@kindex kill 2200@item kill 2201Kill the child process in which your program is running under @value{GDBN}. 2202@end table 2203 2204This command is useful if you wish to debug a core dump instead of a 2205running process. @value{GDBN} ignores any core dump file while your program 2206is running. 2207 2208On some operating systems, a program cannot be executed outside @value{GDBN} 2209while you have breakpoints set on it inside @value{GDBN}. You can use the 2210@code{kill} command in this situation to permit running your program 2211outside the debugger. 2212 2213The @code{kill} command is also useful if you wish to recompile and 2214relink your program, since on many systems it is impossible to modify an 2215executable file while it is running in a process. In this case, when you 2216next type @code{run}, @value{GDBN} notices that the file has changed, and 2217reads the symbol table again (while trying to preserve your current 2218breakpoint settings). 2219 2220@node Threads 2221@section Debugging Programs with Multiple Threads 2222 2223@cindex threads of execution 2224@cindex multiple threads 2225@cindex switching threads 2226In some operating systems, such as HP-UX and Solaris, a single program 2227may have more than one @dfn{thread} of execution. The precise semantics 2228of threads differ from one operating system to another, but in general 2229the threads of a single program are akin to multiple processes---except 2230that they share one address space (that is, they can all examine and 2231modify the same variables). On the other hand, each thread has its own 2232registers and execution stack, and perhaps private memory. 2233 2234@value{GDBN} provides these facilities for debugging multi-thread 2235programs: 2236 2237@itemize @bullet 2238@item automatic notification of new threads 2239@item @samp{thread @var{threadno}}, a command to switch among threads 2240@item @samp{info threads}, a command to inquire about existing threads 2241@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}}, 2242a command to apply a command to a list of threads 2243@item thread-specific breakpoints 2244@end itemize 2245 2246@quotation 2247@emph{Warning:} These facilities are not yet available on every 2248@value{GDBN} configuration where the operating system supports threads. 2249If your @value{GDBN} does not support threads, these commands have no 2250effect. For example, a system without thread support shows no output 2251from @samp{info threads}, and always rejects the @code{thread} command, 2252like this: 2253 2254@smallexample 2255(@value{GDBP}) info threads 2256(@value{GDBP}) thread 1 2257Thread ID 1 not known. Use the "info threads" command to 2258see the IDs of currently known threads. 2259@end smallexample 2260@c FIXME to implementors: how hard would it be to say "sorry, this GDB 2261@c doesn't support threads"? 2262@end quotation 2263 2264@cindex focus of debugging 2265@cindex current thread 2266The @value{GDBN} thread debugging facility allows you to observe all 2267threads while your program runs---but whenever @value{GDBN} takes 2268control, one thread in particular is always the focus of debugging. 2269This thread is called the @dfn{current thread}. Debugging commands show 2270program information from the perspective of the current thread. 2271 2272@cindex @code{New} @var{systag} message 2273@cindex thread identifier (system) 2274@c FIXME-implementors!! It would be more helpful if the [New...] message 2275@c included GDB's numeric thread handle, so you could just go to that 2276@c thread without first checking `info threads'. 2277Whenever @value{GDBN} detects a new thread in your program, it displays 2278the target system's identification for the thread with a message in the 2279form @samp{[New @var{systag}]}. @var{systag} is a thread identifier 2280whose form varies depending on the particular system. For example, on 2281@sc{gnu}/Linux, you might see 2282 2283@smallexample 2284[New Thread 46912507313328 (LWP 25582)] 2285@end smallexample 2286 2287@noindent 2288when @value{GDBN} notices a new thread. In contrast, on an SGI system, 2289the @var{systag} is simply something like @samp{process 368}, with no 2290further qualifier. 2291 2292@c FIXME!! (1) Does the [New...] message appear even for the very first 2293@c thread of a program, or does it only appear for the 2294@c second---i.e.@: when it becomes obvious we have a multithread 2295@c program? 2296@c (2) *Is* there necessarily a first thread always? Or do some 2297@c multithread systems permit starting a program with multiple 2298@c threads ab initio? 2299 2300@cindex thread number 2301@cindex thread identifier (GDB) 2302For debugging purposes, @value{GDBN} associates its own thread 2303number---always a single integer---with each thread in your program. 2304 2305@table @code 2306@kindex info threads 2307@item info threads 2308Display a summary of all threads currently in your 2309program. @value{GDBN} displays for each thread (in this order): 2310 2311@enumerate 2312@item 2313the thread number assigned by @value{GDBN} 2314 2315@item 2316the target system's thread identifier (@var{systag}) 2317 2318@item 2319the current stack frame summary for that thread 2320@end enumerate 2321 2322@noindent 2323An asterisk @samp{*} to the left of the @value{GDBN} thread number 2324indicates the current thread. 2325 2326For example, 2327@end table 2328@c end table here to get a little more width for example 2329 2330@smallexample 2331(@value{GDBP}) info threads 2332 3 process 35 thread 27 0x34e5 in sigpause () 2333 2 process 35 thread 23 0x34e5 in sigpause () 2334* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) 2335 at threadtest.c:68 2336@end smallexample 2337 2338On HP-UX systems: 2339 2340@cindex debugging multithreaded programs (on HP-UX) 2341@cindex thread identifier (GDB), on HP-UX 2342For debugging purposes, @value{GDBN} associates its own thread 2343number---a small integer assigned in thread-creation order---with each 2344thread in your program. 2345 2346@cindex @code{New} @var{systag} message, on HP-UX 2347@cindex thread identifier (system), on HP-UX 2348@c FIXME-implementors!! It would be more helpful if the [New...] message 2349@c included GDB's numeric thread handle, so you could just go to that 2350@c thread without first checking `info threads'. 2351Whenever @value{GDBN} detects a new thread in your program, it displays 2352both @value{GDBN}'s thread number and the target system's identification for the thread with a message in the 2353form @samp{[New @var{systag}]}. @var{systag} is a thread identifier 2354whose form varies depending on the particular system. For example, on 2355HP-UX, you see 2356 2357@smallexample 2358[New thread 2 (system thread 26594)] 2359@end smallexample 2360 2361@noindent 2362when @value{GDBN} notices a new thread. 2363 2364@table @code 2365@kindex info threads (HP-UX) 2366@item info threads 2367Display a summary of all threads currently in your 2368program. @value{GDBN} displays for each thread (in this order): 2369 2370@enumerate 2371@item the thread number assigned by @value{GDBN} 2372 2373@item the target system's thread identifier (@var{systag}) 2374 2375@item the current stack frame summary for that thread 2376@end enumerate 2377 2378@noindent 2379An asterisk @samp{*} to the left of the @value{GDBN} thread number 2380indicates the current thread. 2381 2382For example, 2383@end table 2384@c end table here to get a little more width for example 2385 2386@smallexample 2387(@value{GDBP}) info threads 2388 * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") \@* 2389 at quicksort.c:137 2390 2 system thread 26606 0x7b0030d8 in __ksleep () \@* 2391 from /usr/lib/libc.2 2392 1 system thread 27905 0x7b003498 in _brk () \@* 2393 from /usr/lib/libc.2 2394@end smallexample 2395 2396On Solaris, you can display more information about user threads with a 2397Solaris-specific command: 2398 2399@table @code 2400@item maint info sol-threads 2401@kindex maint info sol-threads 2402@cindex thread info (Solaris) 2403Display info on Solaris user threads. 2404@end table 2405 2406@table @code 2407@kindex thread @var{threadno} 2408@item thread @var{threadno} 2409Make thread number @var{threadno} the current thread. The command 2410argument @var{threadno} is the internal @value{GDBN} thread number, as 2411shown in the first field of the @samp{info threads} display. 2412@value{GDBN} responds by displaying the system identifier of the thread 2413you selected, and its current stack frame summary: 2414 2415@smallexample 2416@c FIXME!! This example made up; find a @value{GDBN} w/threads and get real one 2417(@value{GDBP}) thread 2 2418[Switching to process 35 thread 23] 24190x34e5 in sigpause () 2420@end smallexample 2421 2422@noindent 2423As with the @samp{[New @dots{}]} message, the form of the text after 2424@samp{Switching to} depends on your system's conventions for identifying 2425threads. 2426 2427@kindex thread apply 2428@cindex apply command to several threads 2429@item thread apply [@var{threadno}] [@var{all}] @var{command} 2430The @code{thread apply} command allows you to apply the named 2431@var{command} to one or more threads. Specify the numbers of the 2432threads that you want affected with the command argument 2433@var{threadno}. It can be a single thread number, one of the numbers 2434shown in the first field of the @samp{info threads} display; or it 2435could be a range of thread numbers, as in @code{2-4}. To apply a 2436command to all threads, type @kbd{thread apply all @var{command}}. 2437@end table 2438 2439@cindex automatic thread selection 2440@cindex switching threads automatically 2441@cindex threads, automatic switching 2442Whenever @value{GDBN} stops your program, due to a breakpoint or a 2443signal, it automatically selects the thread where that breakpoint or 2444signal happened. @value{GDBN} alerts you to the context switch with a 2445message of the form @samp{[Switching to @var{systag}]} to identify the 2446thread. 2447 2448@xref{Thread Stops,,Stopping and Starting Multi-thread Programs}, for 2449more information about how @value{GDBN} behaves when you stop and start 2450programs with multiple threads. 2451 2452@xref{Set Watchpoints,,Setting Watchpoints}, for information about 2453watchpoints in programs with multiple threads. 2454 2455@node Processes 2456@section Debugging Programs with Multiple Processes 2457 2458@cindex fork, debugging programs which call 2459@cindex multiple processes 2460@cindex processes, multiple 2461On most systems, @value{GDBN} has no special support for debugging 2462programs which create additional processes using the @code{fork} 2463function. When a program forks, @value{GDBN} will continue to debug the 2464parent process and the child process will run unimpeded. If you have 2465set a breakpoint in any code which the child then executes, the child 2466will get a @code{SIGTRAP} signal which (unless it catches the signal) 2467will cause it to terminate. 2468 2469However, if you want to debug the child process there is a workaround 2470which isn't too painful. Put a call to @code{sleep} in the code which 2471the child process executes after the fork. It may be useful to sleep 2472only if a certain environment variable is set, or a certain file exists, 2473so that the delay need not occur when you don't want to run @value{GDBN} 2474on the child. While the child is sleeping, use the @code{ps} program to 2475get its process ID. Then tell @value{GDBN} (a new invocation of 2476@value{GDBN} if you are also debugging the parent process) to attach to 2477the child process (@pxref{Attach}). From that point on you can debug 2478the child process just like any other process which you attached to. 2479 2480On some systems, @value{GDBN} provides support for debugging programs that 2481create additional processes using the @code{fork} or @code{vfork} functions. 2482Currently, the only platforms with this feature are HP-UX (11.x and later 2483only?) and GNU/Linux (kernel version 2.5.60 and later). 2484 2485By default, when a program forks, @value{GDBN} will continue to debug 2486the parent process and the child process will run unimpeded. 2487 2488If you want to follow the child process instead of the parent process, 2489use the command @w{@code{set follow-fork-mode}}. 2490 2491@table @code 2492@kindex set follow-fork-mode 2493@item set follow-fork-mode @var{mode} 2494Set the debugger response to a program call of @code{fork} or 2495@code{vfork}. A call to @code{fork} or @code{vfork} creates a new 2496process. The @var{mode} argument can be: 2497 2498@table @code 2499@item parent 2500The original process is debugged after a fork. The child process runs 2501unimpeded. This is the default. 2502 2503@item child 2504The new process is debugged after a fork. The parent process runs 2505unimpeded. 2506 2507@end table 2508 2509@kindex show follow-fork-mode 2510@item show follow-fork-mode 2511Display the current debugger response to a @code{fork} or @code{vfork} call. 2512@end table 2513 2514@cindex debugging multiple processes 2515On Linux, if you want to debug both the parent and child processes, use the 2516command @w{@code{set detach-on-fork}}. 2517 2518@table @code 2519@kindex set detach-on-fork 2520@item set detach-on-fork @var{mode} 2521Tells gdb whether to detach one of the processes after a fork, or 2522retain debugger control over them both. 2523 2524@table @code 2525@item on 2526The child process (or parent process, depending on the value of 2527@code{follow-fork-mode}) will be detached and allowed to run 2528independently. This is the default. 2529 2530@item off 2531Both processes will be held under the control of @value{GDBN}. 2532One process (child or parent, depending on the value of 2533@code{follow-fork-mode}) is debugged as usual, while the other 2534is held suspended. 2535 2536@end table 2537 2538@kindex show detach-on-follow 2539@item show detach-on-follow 2540Show whether detach-on-follow mode is on/off. 2541@end table 2542 2543If you choose to set @var{detach-on-follow} mode off, then 2544@value{GDBN} will retain control of all forked processes (including 2545nested forks). You can list the forked processes under the control of 2546@value{GDBN} by using the @w{@code{info forks}} command, and switch 2547from one fork to another by using the @w{@code{fork}} command. 2548 2549@table @code 2550@kindex info forks 2551@item info forks 2552Print a list of all forked processes under the control of @value{GDBN}. 2553The listing will include a fork id, a process id, and the current 2554position (program counter) of the process. 2555 2556 2557@kindex fork @var{fork-id} 2558@item fork @var{fork-id} 2559Make fork number @var{fork-id} the current process. The argument 2560@var{fork-id} is the internal fork number assigned by @value{GDBN}, 2561as shown in the first field of the @samp{info forks} display. 2562 2563@end table 2564 2565To quit debugging one of the forked processes, you can either detach 2566from it by using the @w{@code{detach fork}} command (allowing it to 2567run independently), or delete (and kill) it using the 2568@w{@code{delete fork}} command. 2569 2570@table @code 2571@kindex detach fork @var{fork-id} 2572@item detach fork @var{fork-id} 2573Detach from the process identified by @value{GDBN} fork number 2574@var{fork-id}, and remove it from the fork list. The process will be 2575allowed to run independently. 2576 2577@kindex delete fork @var{fork-id} 2578@item delete fork @var{fork-id} 2579Kill the process identified by @value{GDBN} fork number @var{fork-id}, 2580and remove it from the fork list. 2581 2582@end table 2583 2584If you ask to debug a child process and a @code{vfork} is followed by an 2585@code{exec}, @value{GDBN} executes the new target up to the first 2586breakpoint in the new target. If you have a breakpoint set on 2587@code{main} in your original program, the breakpoint will also be set on 2588the child process's @code{main}. 2589 2590When a child process is spawned by @code{vfork}, you cannot debug the 2591child or parent until an @code{exec} call completes. 2592 2593If you issue a @code{run} command to @value{GDBN} after an @code{exec} 2594call executes, the new target restarts. To restart the parent process, 2595use the @code{file} command with the parent executable name as its 2596argument. 2597 2598You can use the @code{catch} command to make @value{GDBN} stop whenever 2599a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set 2600Catchpoints, ,Setting Catchpoints}. 2601 2602@node Checkpoint/Restart 2603@section Setting a @emph{Bookmark} to Return to Later 2604 2605@cindex checkpoint 2606@cindex restart 2607@cindex bookmark 2608@cindex snapshot of a process 2609@cindex rewind program state 2610 2611On certain operating systems@footnote{Currently, only 2612@sc{gnu}/Linux.}, @value{GDBN} is able to save a @dfn{snapshot} of a 2613program's state, called a @dfn{checkpoint}, and come back to it 2614later. 2615 2616Returning to a checkpoint effectively undoes everything that has 2617happened in the program since the @code{checkpoint} was saved. This 2618includes changes in memory, registers, and even (within some limits) 2619system state. Effectively, it is like going back in time to the 2620moment when the checkpoint was saved. 2621 2622Thus, if you're stepping thru a program and you think you're 2623getting close to the point where things go wrong, you can save 2624a checkpoint. Then, if you accidentally go too far and miss 2625the critical statement, instead of having to restart your program 2626from the beginning, you can just go back to the checkpoint and 2627start again from there. 2628 2629This can be especially useful if it takes a lot of time or 2630steps to reach the point where you think the bug occurs. 2631 2632To use the @code{checkpoint}/@code{restart} method of debugging: 2633 2634@table @code 2635@kindex checkpoint 2636@item checkpoint 2637Save a snapshot of the debugged program's current execution state. 2638The @code{checkpoint} command takes no arguments, but each checkpoint 2639is assigned a small integer id, similar to a breakpoint id. 2640 2641@kindex info checkpoints 2642@item info checkpoints 2643List the checkpoints that have been saved in the current debugging 2644session. For each checkpoint, the following information will be 2645listed: 2646 2647@table @code 2648@item Checkpoint ID 2649@item Process ID 2650@item Code Address 2651@item Source line, or label 2652@end table 2653 2654@kindex restart @var{checkpoint-id} 2655@item restart @var{checkpoint-id} 2656Restore the program state that was saved as checkpoint number 2657@var{checkpoint-id}. All program variables, registers, stack frames 2658etc.@: will be returned to the values that they had when the checkpoint 2659was saved. In essence, gdb will ``wind back the clock'' to the point 2660in time when the checkpoint was saved. 2661 2662Note that breakpoints, @value{GDBN} variables, command history etc. 2663are not affected by restoring a checkpoint. In general, a checkpoint 2664only restores things that reside in the program being debugged, not in 2665the debugger. 2666 2667@kindex delete checkpoint @var{checkpoint-id} 2668@item delete checkpoint @var{checkpoint-id} 2669Delete the previously-saved checkpoint identified by @var{checkpoint-id}. 2670 2671@end table 2672 2673Returning to a previously saved checkpoint will restore the user state 2674of the program being debugged, plus a significant subset of the system 2675(OS) state, including file pointers. It won't ``un-write'' data from 2676a file, but it will rewind the file pointer to the previous location, 2677so that the previously written data can be overwritten. For files 2678opened in read mode, the pointer will also be restored so that the 2679previously read data can be read again. 2680 2681Of course, characters that have been sent to a printer (or other 2682external device) cannot be ``snatched back'', and characters received 2683from eg.@: a serial device can be removed from internal program buffers, 2684but they cannot be ``pushed back'' into the serial pipeline, ready to 2685be received again. Similarly, the actual contents of files that have 2686been changed cannot be restored (at this time). 2687 2688However, within those constraints, you actually can ``rewind'' your 2689program to a previously saved point in time, and begin debugging it 2690again --- and you can change the course of events so as to debug a 2691different execution path this time. 2692 2693@cindex checkpoints and process id 2694Finally, there is one bit of internal program state that will be 2695different when you return to a checkpoint --- the program's process 2696id. Each checkpoint will have a unique process id (or @var{pid}), 2697and each will be different from the program's original @var{pid}. 2698If your program has saved a local copy of its process id, this could 2699potentially pose a problem. 2700 2701@subsection A Non-obvious Benefit of Using Checkpoints 2702 2703On some systems such as @sc{gnu}/Linux, address space randomization 2704is performed on new processes for security reasons. This makes it 2705difficult or impossible to set a breakpoint, or watchpoint, on an 2706absolute address if you have to restart the program, since the 2707absolute location of a symbol will change from one execution to the 2708next. 2709 2710A checkpoint, however, is an @emph{identical} copy of a process. 2711Therefore if you create a checkpoint at (eg.@:) the start of main, 2712and simply return to that checkpoint instead of restarting the 2713process, you can avoid the effects of address randomization and 2714your symbols will all stay in the same place. 2715 2716@node Stopping 2717@chapter Stopping and Continuing 2718 2719The principal purposes of using a debugger are so that you can stop your 2720program before it terminates; or so that, if your program runs into 2721trouble, you can investigate and find out why. 2722 2723Inside @value{GDBN}, your program may stop for any of several reasons, 2724such as a signal, a breakpoint, or reaching a new line after a 2725@value{GDBN} command such as @code{step}. You may then examine and 2726change variables, set new breakpoints or remove old ones, and then 2727continue execution. Usually, the messages shown by @value{GDBN} provide 2728ample explanation of the status of your program---but you can also 2729explicitly request this information at any time. 2730 2731@table @code 2732@kindex info program 2733@item info program 2734Display information about the status of your program: whether it is 2735running or not, what process it is, and why it stopped. 2736@end table 2737 2738@menu 2739* Breakpoints:: Breakpoints, watchpoints, and catchpoints 2740* Continuing and Stepping:: Resuming execution 2741* Signals:: Signals 2742* Thread Stops:: Stopping and starting multi-thread programs 2743@end menu 2744 2745@node Breakpoints 2746@section Breakpoints, Watchpoints, and Catchpoints 2747 2748@cindex breakpoints 2749A @dfn{breakpoint} makes your program stop whenever a certain point in 2750the program is reached. For each breakpoint, you can add conditions to 2751control in finer detail whether your program stops. You can set 2752breakpoints with the @code{break} command and its variants (@pxref{Set 2753Breaks, ,Setting Breakpoints}), to specify the place where your program 2754should stop by line number, function name or exact address in the 2755program. 2756 2757On some systems, you can set breakpoints in shared libraries before 2758the executable is run. There is a minor limitation on HP-UX systems: 2759you must wait until the executable is run in order to set breakpoints 2760in shared library routines that are not called directly by the program 2761(for example, routines that are arguments in a @code{pthread_create} 2762call). 2763 2764@cindex watchpoints 2765@cindex data breakpoints 2766@cindex memory tracing 2767@cindex breakpoint on memory address 2768@cindex breakpoint on variable modification 2769A @dfn{watchpoint} is a special breakpoint that stops your program 2770when the value of an expression changes. The expression may be a value 2771of a variable, or it could involve values of one or more variables 2772combined by operators, such as @samp{a + b}. This is sometimes called 2773@dfn{data breakpoints}. You must use a different command to set 2774watchpoints (@pxref{Set Watchpoints, ,Setting Watchpoints}), but aside 2775from that, you can manage a watchpoint like any other breakpoint: you 2776enable, disable, and delete both breakpoints and watchpoints using the 2777same commands. 2778 2779You can arrange to have values from your program displayed automatically 2780whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,, 2781Automatic Display}. 2782 2783@cindex catchpoints 2784@cindex breakpoint on events 2785A @dfn{catchpoint} is another special breakpoint that stops your program 2786when a certain kind of event occurs, such as the throwing of a C@t{++} 2787exception or the loading of a library. As with watchpoints, you use a 2788different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting 2789Catchpoints}), but aside from that, you can manage a catchpoint like any 2790other breakpoint. (To stop when your program receives a signal, use the 2791@code{handle} command; see @ref{Signals, ,Signals}.) 2792 2793@cindex breakpoint numbers 2794@cindex numbers for breakpoints 2795@value{GDBN} assigns a number to each breakpoint, watchpoint, or 2796catchpoint when you create it; these numbers are successive integers 2797starting with one. In many of the commands for controlling various 2798features of breakpoints you use the breakpoint number to say which 2799breakpoint you want to change. Each breakpoint may be @dfn{enabled} or 2800@dfn{disabled}; if disabled, it has no effect on your program until you 2801enable it again. 2802 2803@cindex breakpoint ranges 2804@cindex ranges of breakpoints 2805Some @value{GDBN} commands accept a range of breakpoints on which to 2806operate. A breakpoint range is either a single breakpoint number, like 2807@samp{5}, or two such numbers, in increasing order, separated by a 2808hyphen, like @samp{5-7}. When a breakpoint range is given to a command, 2809all breakpoints in that range are operated on. 2810 2811@menu 2812* Set Breaks:: Setting breakpoints 2813* Set Watchpoints:: Setting watchpoints 2814* Set Catchpoints:: Setting catchpoints 2815* Delete Breaks:: Deleting breakpoints 2816* Disabling:: Disabling breakpoints 2817* Conditions:: Break conditions 2818* Break Commands:: Breakpoint command lists 2819* Breakpoint Menus:: Breakpoint menus 2820* Error in Breakpoints:: ``Cannot insert breakpoints'' 2821* Breakpoint-related Warnings:: ``Breakpoint address adjusted...'' 2822@end menu 2823 2824@node Set Breaks 2825@subsection Setting Breakpoints 2826 2827@c FIXME LMB what does GDB do if no code on line of breakpt? 2828@c consider in particular declaration with/without initialization. 2829@c 2830@c FIXME 2 is there stuff on this already? break at fun start, already init? 2831 2832@kindex break 2833@kindex b @r{(@code{break})} 2834@vindex $bpnum@r{, convenience variable} 2835@cindex latest breakpoint 2836Breakpoints are set with the @code{break} command (abbreviated 2837@code{b}). The debugger convenience variable @samp{$bpnum} records the 2838number of the breakpoint you've set most recently; see @ref{Convenience 2839Vars,, Convenience Variables}, for a discussion of what you can do with 2840convenience variables. 2841 2842You have several ways to say where the breakpoint should go. 2843 2844@table @code 2845@item break @var{function} 2846Set a breakpoint at entry to function @var{function}. 2847When using source languages that permit overloading of symbols, such as 2848C@t{++}, @var{function} may refer to more than one possible place to break. 2849@xref{Breakpoint Menus,,Breakpoint Menus}, for a discussion of that situation. 2850 2851@item break +@var{offset} 2852@itemx break -@var{offset} 2853Set a breakpoint some number of lines forward or back from the position 2854at which execution stopped in the currently selected @dfn{stack frame}. 2855(@xref{Frames, ,Frames}, for a description of stack frames.) 2856 2857@item break @var{linenum} 2858Set a breakpoint at line @var{linenum} in the current source file. 2859The current source file is the last file whose source text was printed. 2860The breakpoint will stop your program just before it executes any of the 2861code on that line. 2862 2863@item break @var{filename}:@var{linenum} 2864Set a breakpoint at line @var{linenum} in source file @var{filename}. 2865 2866@item break @var{filename}:@var{function} 2867Set a breakpoint at entry to function @var{function} found in file 2868@var{filename}. Specifying a file name as well as a function name is 2869superfluous except when multiple files contain similarly named 2870functions. 2871 2872@item break *@var{address} 2873Set a breakpoint at address @var{address}. You can use this to set 2874breakpoints in parts of your program which do not have debugging 2875information or source files. 2876 2877@item break 2878When called without any arguments, @code{break} sets a breakpoint at 2879the next instruction to be executed in the selected stack frame 2880(@pxref{Stack, ,Examining the Stack}). In any selected frame but the 2881innermost, this makes your program stop as soon as control 2882returns to that frame. This is similar to the effect of a 2883@code{finish} command in the frame inside the selected frame---except 2884that @code{finish} does not leave an active breakpoint. If you use 2885@code{break} without an argument in the innermost frame, @value{GDBN} stops 2886the next time it reaches the current location; this may be useful 2887inside loops. 2888 2889@value{GDBN} normally ignores breakpoints when it resumes execution, until at 2890least one instruction has been executed. If it did not do this, you 2891would be unable to proceed past a breakpoint without first disabling the 2892breakpoint. This rule applies whether or not the breakpoint already 2893existed when your program stopped. 2894 2895@item break @dots{} if @var{cond} 2896Set a breakpoint with condition @var{cond}; evaluate the expression 2897@var{cond} each time the breakpoint is reached, and stop only if the 2898value is nonzero---that is, if @var{cond} evaluates as true. 2899@samp{@dots{}} stands for one of the possible arguments described 2900above (or no argument) specifying where to break. @xref{Conditions, 2901,Break Conditions}, for more information on breakpoint conditions. 2902 2903@kindex tbreak 2904@item tbreak @var{args} 2905Set a breakpoint enabled only for one stop. @var{args} are the 2906same as for the @code{break} command, and the breakpoint is set in the same 2907way, but the breakpoint is automatically deleted after the first time your 2908program stops there. @xref{Disabling, ,Disabling Breakpoints}. 2909 2910@kindex hbreak 2911@cindex hardware breakpoints 2912@item hbreak @var{args} 2913Set a hardware-assisted breakpoint. @var{args} are the same as for the 2914@code{break} command and the breakpoint is set in the same way, but the 2915breakpoint requires hardware support and some target hardware may not 2916have this support. The main purpose of this is EPROM/ROM code 2917debugging, so you can set a breakpoint at an instruction without 2918changing the instruction. This can be used with the new trap-generation 2919provided by SPARClite DSU and most x86-based targets. These targets 2920will generate traps when a program accesses some data or instruction 2921address that is assigned to the debug registers. However the hardware 2922breakpoint registers can take a limited number of breakpoints. For 2923example, on the DSU, only two data breakpoints can be set at a time, and 2924@value{GDBN} will reject this command if more than two are used. Delete 2925or disable unused hardware breakpoints before setting new ones 2926(@pxref{Disabling, ,Disabling Breakpoints}). 2927@xref{Conditions, ,Break Conditions}. 2928For remote targets, you can restrict the number of hardware 2929breakpoints @value{GDBN} will use, see @ref{set remote 2930hardware-breakpoint-limit}. 2931 2932 2933@kindex thbreak 2934@item thbreak @var{args} 2935Set a hardware-assisted breakpoint enabled only for one stop. @var{args} 2936are the same as for the @code{hbreak} command and the breakpoint is set in 2937the same way. However, like the @code{tbreak} command, 2938the breakpoint is automatically deleted after the 2939first time your program stops there. Also, like the @code{hbreak} 2940command, the breakpoint requires hardware support and some target hardware 2941may not have this support. @xref{Disabling, ,Disabling Breakpoints}. 2942See also @ref{Conditions, ,Break Conditions}. 2943 2944@kindex rbreak 2945@cindex regular expression 2946@cindex breakpoints in functions matching a regexp 2947@cindex set breakpoints in many functions 2948@item rbreak @var{regex} 2949Set breakpoints on all functions matching the regular expression 2950@var{regex}. This command sets an unconditional breakpoint on all 2951matches, printing a list of all breakpoints it set. Once these 2952breakpoints are set, they are treated just like the breakpoints set with 2953the @code{break} command. You can delete them, disable them, or make 2954them conditional the same way as any other breakpoint. 2955 2956The syntax of the regular expression is the standard one used with tools 2957like @file{grep}. Note that this is different from the syntax used by 2958shells, so for instance @code{foo*} matches all functions that include 2959an @code{fo} followed by zero or more @code{o}s. There is an implicit 2960@code{.*} leading and trailing the regular expression you supply, so to 2961match only functions that begin with @code{foo}, use @code{^foo}. 2962 2963@cindex non-member C@t{++} functions, set breakpoint in 2964When debugging C@t{++} programs, @code{rbreak} is useful for setting 2965breakpoints on overloaded functions that are not members of any special 2966classes. 2967 2968@cindex set breakpoints on all functions 2969The @code{rbreak} command can be used to set breakpoints in 2970@strong{all} the functions in a program, like this: 2971 2972@smallexample 2973(@value{GDBP}) rbreak . 2974@end smallexample 2975 2976@kindex info breakpoints 2977@cindex @code{$_} and @code{info breakpoints} 2978@item info breakpoints @r{[}@var{n}@r{]} 2979@itemx info break @r{[}@var{n}@r{]} 2980@itemx info watchpoints @r{[}@var{n}@r{]} 2981Print a table of all breakpoints, watchpoints, and catchpoints set and 2982not deleted. Optional argument @var{n} means print information only 2983about the specified breakpoint (or watchpoint or catchpoint). For 2984each breakpoint, following columns are printed: 2985 2986@table @emph 2987@item Breakpoint Numbers 2988@item Type 2989Breakpoint, watchpoint, or catchpoint. 2990@item Disposition 2991Whether the breakpoint is marked to be disabled or deleted when hit. 2992@item Enabled or Disabled 2993Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints 2994that are not enabled. 2995@item Address 2996Where the breakpoint is in your program, as a memory address. If the 2997breakpoint is pending (see below for details) on a future load of a shared library, the address 2998will be listed as @samp{<PENDING>}. 2999@item What 3000Where the breakpoint is in the source for your program, as a file and 3001line number. For a pending breakpoint, the original string passed to 3002the breakpoint command will be listed as it cannot be resolved until 3003the appropriate shared library is loaded in the future. 3004@end table 3005 3006@noindent 3007If a breakpoint is conditional, @code{info break} shows the condition on 3008the line following the affected breakpoint; breakpoint commands, if any, 3009are listed after that. A pending breakpoint is allowed to have a condition 3010specified for it. The condition is not parsed for validity until a shared 3011library is loaded that allows the pending breakpoint to resolve to a 3012valid location. 3013 3014@noindent 3015@code{info break} with a breakpoint 3016number @var{n} as argument lists only that breakpoint. The 3017convenience variable @code{$_} and the default examining-address for 3018the @code{x} command are set to the address of the last breakpoint 3019listed (@pxref{Memory, ,Examining Memory}). 3020 3021@noindent 3022@code{info break} displays a count of the number of times the breakpoint 3023has been hit. This is especially useful in conjunction with the 3024@code{ignore} command. You can ignore a large number of breakpoint 3025hits, look at the breakpoint info to see how many times the breakpoint 3026was hit, and then run again, ignoring one less than that number. This 3027will get you quickly to the last hit of that breakpoint. 3028@end table 3029 3030@value{GDBN} allows you to set any number of breakpoints at the same place in 3031your program. There is nothing silly or meaningless about this. When 3032the breakpoints are conditional, this is even useful 3033(@pxref{Conditions, ,Break Conditions}). 3034 3035@cindex pending breakpoints 3036If a specified breakpoint location cannot be found, it may be due to the fact 3037that the location is in a shared library that is yet to be loaded. In such 3038a case, you may want @value{GDBN} to create a special breakpoint (known as 3039a @dfn{pending breakpoint}) that 3040attempts to resolve itself in the future when an appropriate shared library 3041gets loaded. 3042 3043Pending breakpoints are useful to set at the start of your 3044@value{GDBN} session for locations that you know will be dynamically loaded 3045later by the program being debugged. When shared libraries are loaded, 3046a check is made to see if the load resolves any pending breakpoint locations. 3047If a pending breakpoint location gets resolved, 3048a regular breakpoint is created and the original pending breakpoint is removed. 3049 3050@value{GDBN} provides some additional commands for controlling pending 3051breakpoint support: 3052 3053@kindex set breakpoint pending 3054@kindex show breakpoint pending 3055@table @code 3056@item set breakpoint pending auto 3057This is the default behavior. When @value{GDBN} cannot find the breakpoint 3058location, it queries you whether a pending breakpoint should be created. 3059 3060@item set breakpoint pending on 3061This indicates that an unrecognized breakpoint location should automatically 3062result in a pending breakpoint being created. 3063 3064@item set breakpoint pending off 3065This indicates that pending breakpoints are not to be created. Any 3066unrecognized breakpoint location results in an error. This setting does 3067not affect any pending breakpoints previously created. 3068 3069@item show breakpoint pending 3070Show the current behavior setting for creating pending breakpoints. 3071@end table 3072 3073@cindex operations allowed on pending breakpoints 3074Normal breakpoint operations apply to pending breakpoints as well. You may 3075specify a condition for a pending breakpoint and/or commands to run when the 3076breakpoint is reached. You can also enable or disable 3077the pending breakpoint. When you specify a condition for a pending breakpoint, 3078the parsing of the condition will be deferred until the point where the 3079pending breakpoint location is resolved. Disabling a pending breakpoint 3080tells @value{GDBN} to not attempt to resolve the breakpoint on any subsequent 3081shared library load. When a pending breakpoint is re-enabled, 3082@value{GDBN} checks to see if the location is already resolved. 3083This is done because any number of shared library loads could have 3084occurred since the time the breakpoint was disabled and one or more 3085of these loads could resolve the location. 3086 3087@cindex automatic hardware breakpoints 3088For some targets, @value{GDBN} can automatically decide if hardware or 3089software breakpoints should be used, depending on whether the 3090breakpoint address is read-only or read-write. This applies to 3091breakpoints set with the @code{break} command as well as to internal 3092breakpoints set by commands like @code{next} and @code{finish}. For 3093breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware 3094breakpoints. 3095 3096You can control this automatic behaviour with the following commands:: 3097 3098@kindex set breakpoint auto-hw 3099@kindex show breakpoint auto-hw 3100@table @code 3101@item set breakpoint auto-hw on 3102This is the default behavior. When @value{GDBN} sets a breakpoint, it 3103will try to use the target memory map to decide if software or hardware 3104breakpoint must be used. 3105 3106@item set breakpoint auto-hw off 3107This indicates @value{GDBN} should not automatically select breakpoint 3108type. If the target provides a memory map, @value{GDBN} will warn when 3109trying to set software breakpoint at a read-only address. 3110@end table 3111 3112 3113@cindex negative breakpoint numbers 3114@cindex internal @value{GDBN} breakpoints 3115@value{GDBN} itself sometimes sets breakpoints in your program for 3116special purposes, such as proper handling of @code{longjmp} (in C 3117programs). These internal breakpoints are assigned negative numbers, 3118starting with @code{-1}; @samp{info breakpoints} does not display them. 3119You can see these breakpoints with the @value{GDBN} maintenance command 3120@samp{maint info breakpoints} (@pxref{maint info breakpoints}). 3121 3122 3123@node Set Watchpoints 3124@subsection Setting Watchpoints 3125 3126@cindex setting watchpoints 3127You can use a watchpoint to stop execution whenever the value of an 3128expression changes, without having to predict a particular place where 3129this may happen. (This is sometimes called a @dfn{data breakpoint}.) 3130The expression may be as simple as the value of a single variable, or 3131as complex as many variables combined by operators. Examples include: 3132 3133@itemize @bullet 3134@item 3135A reference to the value of a single variable. 3136 3137@item 3138An address cast to an appropriate data type. For example, 3139@samp{*(int *)0x12345678} will watch a 4-byte region at the specified 3140address (assuming an @code{int} occupies 4 bytes). 3141 3142@item 3143An arbitrarily complex expression, such as @samp{a*b + c/d}. The 3144expression can use any operators valid in the program's native 3145language (@pxref{Languages}). 3146@end itemize 3147 3148@cindex software watchpoints 3149@cindex hardware watchpoints 3150Depending on your system, watchpoints may be implemented in software or 3151hardware. @value{GDBN} does software watchpointing by single-stepping your 3152program and testing the variable's value each time, which is hundreds of 3153times slower than normal execution. (But this may still be worth it, to 3154catch errors where you have no clue what part of your program is the 3155culprit.) 3156 3157On some systems, such as HP-UX, @sc{gnu}/Linux and most other 3158x86-based targets, @value{GDBN} includes support for hardware 3159watchpoints, which do not slow down the running of your program. 3160 3161@table @code 3162@kindex watch 3163@item watch @var{expr} 3164Set a watchpoint for an expression. @value{GDBN} will break when the 3165expression @var{expr} is written into by the program and its value 3166changes. The simplest (and the most popular) use of this command is 3167to watch the value of a single variable: 3168 3169@smallexample 3170(@value{GDBP}) watch foo 3171@end smallexample 3172 3173@kindex rwatch 3174@item rwatch @var{expr} 3175Set a watchpoint that will break when the value of @var{expr} is read 3176by the program. 3177 3178@kindex awatch 3179@item awatch @var{expr} 3180Set a watchpoint that will break when @var{expr} is either read from 3181or written into by the program. 3182 3183@kindex info watchpoints @r{[}@var{n}@r{]} 3184@item info watchpoints 3185This command prints a list of watchpoints, breakpoints, and catchpoints; 3186it is the same as @code{info break} (@pxref{Set Breaks}). 3187@end table 3188 3189@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware 3190watchpoints execute very quickly, and the debugger reports a change in 3191value at the exact instruction where the change occurs. If @value{GDBN} 3192cannot set a hardware watchpoint, it sets a software watchpoint, which 3193executes more slowly and reports the change in value at the next 3194@emph{statement}, not the instruction, after the change occurs. 3195 3196@cindex use only software watchpoints 3197You can force @value{GDBN} to use only software watchpoints with the 3198@kbd{set can-use-hw-watchpoints 0} command. With this variable set to 3199zero, @value{GDBN} will never try to use hardware watchpoints, even if 3200the underlying system supports them. (Note that hardware-assisted 3201watchpoints that were set @emph{before} setting 3202@code{can-use-hw-watchpoints} to zero will still use the hardware 3203mechanism of watching expression values.) 3204 3205@table @code 3206@item set can-use-hw-watchpoints 3207@kindex set can-use-hw-watchpoints 3208Set whether or not to use hardware watchpoints. 3209 3210@item show can-use-hw-watchpoints 3211@kindex show can-use-hw-watchpoints 3212Show the current mode of using hardware watchpoints. 3213@end table 3214 3215For remote targets, you can restrict the number of hardware 3216watchpoints @value{GDBN} will use, see @ref{set remote 3217hardware-breakpoint-limit}. 3218 3219When you issue the @code{watch} command, @value{GDBN} reports 3220 3221@smallexample 3222Hardware watchpoint @var{num}: @var{expr} 3223@end smallexample 3224 3225@noindent 3226if it was able to set a hardware watchpoint. 3227 3228Currently, the @code{awatch} and @code{rwatch} commands can only set 3229hardware watchpoints, because accesses to data that don't change the 3230value of the watched expression cannot be detected without examining 3231every instruction as it is being executed, and @value{GDBN} does not do 3232that currently. If @value{GDBN} finds that it is unable to set a 3233hardware breakpoint with the @code{awatch} or @code{rwatch} command, it 3234will print a message like this: 3235 3236@smallexample 3237Expression cannot be implemented with read/access watchpoint. 3238@end smallexample 3239 3240Sometimes, @value{GDBN} cannot set a hardware watchpoint because the 3241data type of the watched expression is wider than what a hardware 3242watchpoint on the target machine can handle. For example, some systems 3243can only watch regions that are up to 4 bytes wide; on such systems you 3244cannot set hardware watchpoints for an expression that yields a 3245double-precision floating-point number (which is typically 8 bytes 3246wide). As a work-around, it might be possible to break the large region 3247into a series of smaller ones and watch them with separate watchpoints. 3248 3249If you set too many hardware watchpoints, @value{GDBN} might be unable 3250to insert all of them when you resume the execution of your program. 3251Since the precise number of active watchpoints is unknown until such 3252time as the program is about to be resumed, @value{GDBN} might not be 3253able to warn you about this when you set the watchpoints, and the 3254warning will be printed only when the program is resumed: 3255 3256@smallexample 3257Hardware watchpoint @var{num}: Could not insert watchpoint 3258@end smallexample 3259 3260@noindent 3261If this happens, delete or disable some of the watchpoints. 3262 3263Watching complex expressions that reference many variables can also 3264exhaust the resources available for hardware-assisted watchpoints. 3265That's because @value{GDBN} needs to watch every variable in the 3266expression with separately allocated resources. 3267 3268The SPARClite DSU will generate traps when a program accesses some data 3269or instruction address that is assigned to the debug registers. For the 3270data addresses, DSU facilitates the @code{watch} command. However the 3271hardware breakpoint registers can only take two data watchpoints, and 3272both watchpoints must be the same kind. For example, you can set two 3273watchpoints with @code{watch} commands, two with @code{rwatch} commands, 3274@strong{or} two with @code{awatch} commands, but you cannot set one 3275watchpoint with one command and the other with a different command. 3276@value{GDBN} will reject the command if you try to mix watchpoints. 3277Delete or disable unused watchpoint commands before setting new ones. 3278 3279If you call a function interactively using @code{print} or @code{call}, 3280any watchpoints you have set will be inactive until @value{GDBN} reaches another 3281kind of breakpoint or the call completes. 3282 3283@value{GDBN} automatically deletes watchpoints that watch local 3284(automatic) variables, or expressions that involve such variables, when 3285they go out of scope, that is, when the execution leaves the block in 3286which these variables were defined. In particular, when the program 3287being debugged terminates, @emph{all} local variables go out of scope, 3288and so only watchpoints that watch global variables remain set. If you 3289rerun the program, you will need to set all such watchpoints again. One 3290way of doing that would be to set a code breakpoint at the entry to the 3291@code{main} function and when it breaks, set all the watchpoints. 3292 3293@quotation 3294@cindex watchpoints and threads 3295@cindex threads and watchpoints 3296@emph{Warning:} In multi-thread programs, watchpoints have only limited 3297usefulness. With the current watchpoint implementation, @value{GDBN} 3298can only watch the value of an expression @emph{in a single thread}. If 3299you are confident that the expression can only change due to the current 3300thread's activity (and if you are also confident that no other thread 3301can become current), then you can use watchpoints as usual. However, 3302@value{GDBN} may not notice when a non-current thread's activity changes 3303the expression. 3304 3305@c FIXME: this is almost identical to the previous paragraph. 3306@emph{HP-UX Warning:} In multi-thread programs, software watchpoints 3307have only limited usefulness. If @value{GDBN} creates a software 3308watchpoint, it can only watch the value of an expression @emph{in a 3309single thread}. If you are confident that the expression can only 3310change due to the current thread's activity (and if you are also 3311confident that no other thread can become current), then you can use 3312software watchpoints as usual. However, @value{GDBN} may not notice 3313when a non-current thread's activity changes the expression. (Hardware 3314watchpoints, in contrast, watch an expression in all threads.) 3315@end quotation 3316 3317@xref{set remote hardware-watchpoint-limit}. 3318 3319@node Set Catchpoints 3320@subsection Setting Catchpoints 3321@cindex catchpoints, setting 3322@cindex exception handlers 3323@cindex event handling 3324 3325You can use @dfn{catchpoints} to cause the debugger to stop for certain 3326kinds of program events, such as C@t{++} exceptions or the loading of a 3327shared library. Use the @code{catch} command to set a catchpoint. 3328 3329@table @code 3330@kindex catch 3331@item catch @var{event} 3332Stop when @var{event} occurs. @var{event} can be any of the following: 3333@table @code 3334@item throw 3335@cindex stop on C@t{++} exceptions 3336The throwing of a C@t{++} exception. 3337 3338@item catch 3339The catching of a C@t{++} exception. 3340 3341@item exception 3342@cindex Ada exception catching 3343@cindex catch Ada exceptions 3344An Ada exception being raised. If an exception name is specified 3345at the end of the command (eg @code{catch exception Program_Error}), 3346the debugger will stop only when this specific exception is raised. 3347Otherwise, the debugger stops execution when any Ada exception is raised. 3348 3349@item exception unhandled 3350An exception that was raised but is not handled by the program. 3351 3352@item assert 3353A failed Ada assertion. 3354 3355@item exec 3356@cindex break on fork/exec 3357A call to @code{exec}. This is currently only available for HP-UX. 3358 3359@item fork 3360A call to @code{fork}. This is currently only available for HP-UX. 3361 3362@item vfork 3363A call to @code{vfork}. This is currently only available for HP-UX. 3364 3365@item load 3366@itemx load @var{libname} 3367@cindex break on load/unload of shared library 3368The dynamic loading of any shared library, or the loading of the library 3369@var{libname}. This is currently only available for HP-UX. 3370 3371@item unload 3372@itemx unload @var{libname} 3373The unloading of any dynamically loaded shared library, or the unloading 3374of the library @var{libname}. This is currently only available for HP-UX. 3375@end table 3376 3377@item tcatch @var{event} 3378Set a catchpoint that is enabled only for one stop. The catchpoint is 3379automatically deleted after the first time the event is caught. 3380 3381@end table 3382 3383Use the @code{info break} command to list the current catchpoints. 3384 3385There are currently some limitations to C@t{++} exception handling 3386(@code{catch throw} and @code{catch catch}) in @value{GDBN}: 3387 3388@itemize @bullet 3389@item 3390If you call a function interactively, @value{GDBN} normally returns 3391control to you when the function has finished executing. If the call 3392raises an exception, however, the call may bypass the mechanism that 3393returns control to you and cause your program either to abort or to 3394simply continue running until it hits a breakpoint, catches a signal 3395that @value{GDBN} is listening for, or exits. This is the case even if 3396you set a catchpoint for the exception; catchpoints on exceptions are 3397disabled within interactive calls. 3398 3399@item 3400You cannot raise an exception interactively. 3401 3402@item 3403You cannot install an exception handler interactively. 3404@end itemize 3405 3406@cindex raise exceptions 3407Sometimes @code{catch} is not the best way to debug exception handling: 3408if you need to know exactly where an exception is raised, it is better to 3409stop @emph{before} the exception handler is called, since that way you 3410can see the stack before any unwinding takes place. If you set a 3411breakpoint in an exception handler instead, it may not be easy to find 3412out where the exception was raised. 3413 3414To stop just before an exception handler is called, you need some 3415knowledge of the implementation. In the case of @sc{gnu} C@t{++}, exceptions are 3416raised by calling a library function named @code{__raise_exception} 3417which has the following ANSI C interface: 3418 3419@smallexample 3420 /* @var{addr} is where the exception identifier is stored. 3421 @var{id} is the exception identifier. */ 3422 void __raise_exception (void **addr, void *id); 3423@end smallexample 3424 3425@noindent 3426To make the debugger catch all exceptions before any stack 3427unwinding takes place, set a breakpoint on @code{__raise_exception} 3428(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Exceptions}). 3429 3430With a conditional breakpoint (@pxref{Conditions, ,Break Conditions}) 3431that depends on the value of @var{id}, you can stop your program when 3432a specific exception is raised. You can use multiple conditional 3433breakpoints to stop your program when any of a number of exceptions are 3434raised. 3435 3436 3437@node Delete Breaks 3438@subsection Deleting Breakpoints 3439 3440@cindex clearing breakpoints, watchpoints, catchpoints 3441@cindex deleting breakpoints, watchpoints, catchpoints 3442It is often necessary to eliminate a breakpoint, watchpoint, or 3443catchpoint once it has done its job and you no longer want your program 3444to stop there. This is called @dfn{deleting} the breakpoint. A 3445breakpoint that has been deleted no longer exists; it is forgotten. 3446 3447With the @code{clear} command you can delete breakpoints according to 3448where they are in your program. With the @code{delete} command you can 3449delete individual breakpoints, watchpoints, or catchpoints by specifying 3450their breakpoint numbers. 3451 3452It is not necessary to delete a breakpoint to proceed past it. @value{GDBN} 3453automatically ignores breakpoints on the first instruction to be executed 3454when you continue execution without changing the execution address. 3455 3456@table @code 3457@kindex clear 3458@item clear 3459Delete any breakpoints at the next instruction to be executed in the 3460selected stack frame (@pxref{Selection, ,Selecting a Frame}). When 3461the innermost frame is selected, this is a good way to delete a 3462breakpoint where your program just stopped. 3463 3464@item clear @var{function} 3465@itemx clear @var{filename}:@var{function} 3466Delete any breakpoints set at entry to the named @var{function}. 3467 3468@item clear @var{linenum} 3469@itemx clear @var{filename}:@var{linenum} 3470Delete any breakpoints set at or within the code of the specified 3471@var{linenum} of the specified @var{filename}. 3472 3473@cindex delete breakpoints 3474@kindex delete 3475@kindex d @r{(@code{delete})} 3476@item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} 3477Delete the breakpoints, watchpoints, or catchpoints of the breakpoint 3478ranges specified as arguments. If no argument is specified, delete all 3479breakpoints (@value{GDBN} asks confirmation, unless you have @code{set 3480confirm off}). You can abbreviate this command as @code{d}. 3481@end table 3482 3483@node Disabling 3484@subsection Disabling Breakpoints 3485 3486@cindex enable/disable a breakpoint 3487Rather than deleting a breakpoint, watchpoint, or catchpoint, you might 3488prefer to @dfn{disable} it. This makes the breakpoint inoperative as if 3489it had been deleted, but remembers the information on the breakpoint so 3490that you can @dfn{enable} it again later. 3491 3492You disable and enable breakpoints, watchpoints, and catchpoints with 3493the @code{enable} and @code{disable} commands, optionally specifying one 3494or more breakpoint numbers as arguments. Use @code{info break} or 3495@code{info watch} to print a list of breakpoints, watchpoints, and 3496catchpoints if you do not know which numbers to use. 3497 3498A breakpoint, watchpoint, or catchpoint can have any of four different 3499states of enablement: 3500 3501@itemize @bullet 3502@item 3503Enabled. The breakpoint stops your program. A breakpoint set 3504with the @code{break} command starts out in this state. 3505@item 3506Disabled. The breakpoint has no effect on your program. 3507@item 3508Enabled once. The breakpoint stops your program, but then becomes 3509disabled. 3510@item 3511Enabled for deletion. The breakpoint stops your program, but 3512immediately after it does so it is deleted permanently. A breakpoint 3513set with the @code{tbreak} command starts out in this state. 3514@end itemize 3515 3516You can use the following commands to enable or disable breakpoints, 3517watchpoints, and catchpoints: 3518 3519@table @code 3520@kindex disable 3521@kindex dis @r{(@code{disable})} 3522@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} 3523Disable the specified breakpoints---or all breakpoints, if none are 3524listed. A disabled breakpoint has no effect but is not forgotten. All 3525options such as ignore-counts, conditions and commands are remembered in 3526case the breakpoint is enabled again later. You may abbreviate 3527@code{disable} as @code{dis}. 3528 3529@kindex enable 3530@item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} 3531Enable the specified breakpoints (or all defined breakpoints). They 3532become effective once again in stopping your program. 3533 3534@item enable @r{[}breakpoints@r{]} once @var{range}@dots{} 3535Enable the specified breakpoints temporarily. @value{GDBN} disables any 3536of these breakpoints immediately after stopping your program. 3537 3538@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{} 3539Enable the specified breakpoints to work once, then die. @value{GDBN} 3540deletes any of these breakpoints as soon as your program stops there. 3541Breakpoints set by the @code{tbreak} command start out in this state. 3542@end table 3543 3544@c FIXME: I think the following ``Except for [...] @code{tbreak}'' is 3545@c confusing: tbreak is also initially enabled. 3546Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks, 3547,Setting Breakpoints}), breakpoints that you set are initially enabled; 3548subsequently, they become disabled or enabled only when you use one of 3549the commands above. (The command @code{until} can set and delete a 3550breakpoint of its own, but it does not change the state of your other 3551breakpoints; see @ref{Continuing and Stepping, ,Continuing and 3552Stepping}.) 3553 3554@node Conditions 3555@subsection Break Conditions 3556@cindex conditional breakpoints 3557@cindex breakpoint conditions 3558 3559@c FIXME what is scope of break condition expr? Context where wanted? 3560@c in particular for a watchpoint? 3561The simplest sort of breakpoint breaks every time your program reaches a 3562specified place. You can also specify a @dfn{condition} for a 3563breakpoint. A condition is just a Boolean expression in your 3564programming language (@pxref{Expressions, ,Expressions}). A breakpoint with 3565a condition evaluates the expression each time your program reaches it, 3566and your program stops only if the condition is @emph{true}. 3567 3568This is the converse of using assertions for program validation; in that 3569situation, you want to stop when the assertion is violated---that is, 3570when the condition is false. In C, if you want to test an assertion expressed 3571by the condition @var{assert}, you should set the condition 3572@samp{! @var{assert}} on the appropriate breakpoint. 3573 3574Conditions are also accepted for watchpoints; you may not need them, 3575since a watchpoint is inspecting the value of an expression anyhow---but 3576it might be simpler, say, to just set a watchpoint on a variable name, 3577and specify a condition that tests whether the new value is an interesting 3578one. 3579 3580Break conditions can have side effects, and may even call functions in 3581your program. This can be useful, for example, to activate functions 3582that log program progress, or to use your own print functions to 3583format special data structures. The effects are completely predictable 3584unless there is another enabled breakpoint at the same address. (In 3585that case, @value{GDBN} might see the other breakpoint first and stop your 3586program without checking the condition of this one.) Note that 3587breakpoint commands are usually more convenient and flexible than break 3588conditions for the 3589purpose of performing side effects when a breakpoint is reached 3590(@pxref{Break Commands, ,Breakpoint Command Lists}). 3591 3592Break conditions can be specified when a breakpoint is set, by using 3593@samp{if} in the arguments to the @code{break} command. @xref{Set 3594Breaks, ,Setting Breakpoints}. They can also be changed at any time 3595with the @code{condition} command. 3596 3597You can also use the @code{if} keyword with the @code{watch} command. 3598The @code{catch} command does not recognize the @code{if} keyword; 3599@code{condition} is the only way to impose a further condition on a 3600catchpoint. 3601 3602@table @code 3603@kindex condition 3604@item condition @var{bnum} @var{expression} 3605Specify @var{expression} as the break condition for breakpoint, 3606watchpoint, or catchpoint number @var{bnum}. After you set a condition, 3607breakpoint @var{bnum} stops your program only if the value of 3608@var{expression} is true (nonzero, in C). When you use 3609@code{condition}, @value{GDBN} checks @var{expression} immediately for 3610syntactic correctness, and to determine whether symbols in it have 3611referents in the context of your breakpoint. If @var{expression} uses 3612symbols not referenced in the context of the breakpoint, @value{GDBN} 3613prints an error message: 3614 3615@smallexample 3616No symbol "foo" in current context. 3617@end smallexample 3618 3619@noindent 3620@value{GDBN} does 3621not actually evaluate @var{expression} at the time the @code{condition} 3622command (or a command that sets a breakpoint with a condition, like 3623@code{break if @dots{}}) is given, however. @xref{Expressions, ,Expressions}. 3624 3625@item condition @var{bnum} 3626Remove the condition from breakpoint number @var{bnum}. It becomes 3627an ordinary unconditional breakpoint. 3628@end table 3629 3630@cindex ignore count (of breakpoint) 3631A special case of a breakpoint condition is to stop only when the 3632breakpoint has been reached a certain number of times. This is so 3633useful that there is a special way to do it, using the @dfn{ignore 3634count} of the breakpoint. Every breakpoint has an ignore count, which 3635is an integer. Most of the time, the ignore count is zero, and 3636therefore has no effect. But if your program reaches a breakpoint whose 3637ignore count is positive, then instead of stopping, it just decrements 3638the ignore count by one and continues. As a result, if the ignore count 3639value is @var{n}, the breakpoint does not stop the next @var{n} times 3640your program reaches it. 3641 3642@table @code 3643@kindex ignore 3644@item ignore @var{bnum} @var{count} 3645Set the ignore count of breakpoint number @var{bnum} to @var{count}. 3646The next @var{count} times the breakpoint is reached, your program's 3647execution does not stop; other than to decrement the ignore count, @value{GDBN} 3648takes no action. 3649 3650To make the breakpoint stop the next time it is reached, specify 3651a count of zero. 3652 3653When you use @code{continue} to resume execution of your program from a 3654breakpoint, you can specify an ignore count directly as an argument to 3655@code{continue}, rather than using @code{ignore}. @xref{Continuing and 3656Stepping,,Continuing and Stepping}. 3657 3658If a breakpoint has a positive ignore count and a condition, the 3659condition is not checked. Once the ignore count reaches zero, 3660@value{GDBN} resumes checking the condition. 3661 3662You could achieve the effect of the ignore count with a condition such 3663as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that 3664is decremented each time. @xref{Convenience Vars, ,Convenience 3665Variables}. 3666@end table 3667 3668Ignore counts apply to breakpoints, watchpoints, and catchpoints. 3669 3670 3671@node Break Commands 3672@subsection Breakpoint Command Lists 3673 3674@cindex breakpoint commands 3675You can give any breakpoint (or watchpoint or catchpoint) a series of 3676commands to execute when your program stops due to that breakpoint. For 3677example, you might want to print the values of certain expressions, or 3678enable other breakpoints. 3679 3680@table @code 3681@kindex commands 3682@kindex end@r{ (breakpoint commands)} 3683@item commands @r{[}@var{bnum}@r{]} 3684@itemx @dots{} @var{command-list} @dots{} 3685@itemx end 3686Specify a list of commands for breakpoint number @var{bnum}. The commands 3687themselves appear on the following lines. Type a line containing just 3688@code{end} to terminate the commands. 3689 3690To remove all commands from a breakpoint, type @code{commands} and 3691follow it immediately with @code{end}; that is, give no commands. 3692 3693With no @var{bnum} argument, @code{commands} refers to the last 3694breakpoint, watchpoint, or catchpoint set (not to the breakpoint most 3695recently encountered). 3696@end table 3697 3698Pressing @key{RET} as a means of repeating the last @value{GDBN} command is 3699disabled within a @var{command-list}. 3700 3701You can use breakpoint commands to start your program up again. Simply 3702use the @code{continue} command, or @code{step}, or any other command 3703that resumes execution. 3704 3705Any other commands in the command list, after a command that resumes 3706execution, are ignored. This is because any time you resume execution 3707(even with a simple @code{next} or @code{step}), you may encounter 3708another breakpoint---which could have its own command list, leading to 3709ambiguities about which list to execute. 3710 3711@kindex silent 3712If the first command you specify in a command list is @code{silent}, the 3713usual message about stopping at a breakpoint is not printed. This may 3714be desirable for breakpoints that are to print a specific message and 3715then continue. If none of the remaining commands print anything, you 3716see no sign that the breakpoint was reached. @code{silent} is 3717meaningful only at the beginning of a breakpoint command list. 3718 3719The commands @code{echo}, @code{output}, and @code{printf} allow you to 3720print precisely controlled output, and are often useful in silent 3721breakpoints. @xref{Output, ,Commands for Controlled Output}. 3722 3723For example, here is how you could use breakpoint commands to print the 3724value of @code{x} at entry to @code{foo} whenever @code{x} is positive. 3725 3726@smallexample 3727break foo if x>0 3728commands 3729silent 3730printf "x is %d\n",x 3731cont 3732end 3733@end smallexample 3734 3735One application for breakpoint commands is to compensate for one bug so 3736you can test for another. Put a breakpoint just after the erroneous line 3737of code, give it a condition to detect the case in which something 3738erroneous has been done, and give it commands to assign correct values 3739to any variables that need them. End with the @code{continue} command 3740so that your program does not stop, and start with the @code{silent} 3741command so that no output is produced. Here is an example: 3742 3743@smallexample 3744break 403 3745commands 3746silent 3747set x = y + 4 3748cont 3749end 3750@end smallexample 3751 3752@node Breakpoint Menus 3753@subsection Breakpoint Menus 3754@cindex overloading 3755@cindex symbol overloading 3756 3757Some programming languages (notably C@t{++} and Objective-C) permit a 3758single function name 3759to be defined several times, for application in different contexts. 3760This is called @dfn{overloading}. When a function name is overloaded, 3761@samp{break @var{function}} is not enough to tell @value{GDBN} where you want 3762a breakpoint. If you realize this is a problem, you can use 3763something like @samp{break @var{function}(@var{types})} to specify which 3764particular version of the function you want. Otherwise, @value{GDBN} offers 3765you a menu of numbered choices for different possible breakpoints, and 3766waits for your selection with the prompt @samp{>}. The first two 3767options are always @samp{[0] cancel} and @samp{[1] all}. Typing @kbd{1} 3768sets a breakpoint at each definition of @var{function}, and typing 3769@kbd{0} aborts the @code{break} command without setting any new 3770breakpoints. 3771 3772For example, the following session excerpt shows an attempt to set a 3773breakpoint at the overloaded symbol @code{String::after}. 3774We choose three particular definitions of that function name: 3775 3776@c FIXME! This is likely to change to show arg type lists, at least 3777@smallexample 3778@group 3779(@value{GDBP}) b String::after 3780[0] cancel 3781[1] all 3782[2] file:String.cc; line number:867 3783[3] file:String.cc; line number:860 3784[4] file:String.cc; line number:875 3785[5] file:String.cc; line number:853 3786[6] file:String.cc; line number:846 3787[7] file:String.cc; line number:735 3788> 2 4 6 3789Breakpoint 1 at 0xb26c: file String.cc, line 867. 3790Breakpoint 2 at 0xb344: file String.cc, line 875. 3791Breakpoint 3 at 0xafcc: file String.cc, line 846. 3792Multiple breakpoints were set. 3793Use the "delete" command to delete unwanted 3794 breakpoints. 3795(@value{GDBP}) 3796@end group 3797@end smallexample 3798 3799@c @ifclear BARETARGET 3800@node Error in Breakpoints 3801@subsection ``Cannot insert breakpoints'' 3802@c 3803@c FIXME!! 14/6/95 Is there a real example of this? Let's use it. 3804@c 3805Under some operating systems, breakpoints cannot be used in a program if 3806any other process is running that program. In this situation, 3807attempting to run or continue a program with a breakpoint causes 3808@value{GDBN} to print an error message: 3809 3810@smallexample 3811Cannot insert breakpoints. 3812The same program may be running in another process. 3813@end smallexample 3814 3815When this happens, you have three ways to proceed: 3816 3817@enumerate 3818@item 3819Remove or disable the breakpoints, then continue. 3820 3821@item 3822Suspend @value{GDBN}, and copy the file containing your program to a new 3823name. Resume @value{GDBN} and use the @code{exec-file} command to specify 3824that @value{GDBN} should run your program under that name. 3825Then start your program again. 3826 3827@item 3828Relink your program so that the text segment is nonsharable, using the 3829linker option @samp{-N}. The operating system limitation may not apply 3830to nonsharable executables. 3831@end enumerate 3832@c @end ifclear 3833 3834A similar message can be printed if you request too many active 3835hardware-assisted breakpoints and watchpoints: 3836 3837@c FIXME: the precise wording of this message may change; the relevant 3838@c source change is not committed yet (Sep 3, 1999). 3839@smallexample 3840Stopped; cannot insert breakpoints. 3841You may have requested too many hardware breakpoints and watchpoints. 3842@end smallexample 3843 3844@noindent 3845This message is printed when you attempt to resume the program, since 3846only then @value{GDBN} knows exactly how many hardware breakpoints and 3847watchpoints it needs to insert. 3848 3849When this message is printed, you need to disable or remove some of the 3850hardware-assisted breakpoints and watchpoints, and then continue. 3851 3852@node Breakpoint-related Warnings 3853@subsection ``Breakpoint address adjusted...'' 3854@cindex breakpoint address adjusted 3855 3856Some processor architectures place constraints on the addresses at 3857which breakpoints may be placed. For architectures thus constrained, 3858@value{GDBN} will attempt to adjust the breakpoint's address to comply 3859with the constraints dictated by the architecture. 3860 3861One example of such an architecture is the Fujitsu FR-V. The FR-V is 3862a VLIW architecture in which a number of RISC-like instructions may be 3863bundled together for parallel execution. The FR-V architecture 3864constrains the location of a breakpoint instruction within such a 3865bundle to the instruction with the lowest address. @value{GDBN} 3866honors this constraint by adjusting a breakpoint's address to the 3867first in the bundle. 3868 3869It is not uncommon for optimized code to have bundles which contain 3870instructions from different source statements, thus it may happen that 3871a breakpoint's address will be adjusted from one source statement to 3872another. Since this adjustment may significantly alter @value{GDBN}'s 3873breakpoint related behavior from what the user expects, a warning is 3874printed when the breakpoint is first set and also when the breakpoint 3875is hit. 3876 3877A warning like the one below is printed when setting a breakpoint 3878that's been subject to address adjustment: 3879 3880@smallexample 3881warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. 3882@end smallexample 3883 3884Such warnings are printed both for user settable and @value{GDBN}'s 3885internal breakpoints. If you see one of these warnings, you should 3886verify that a breakpoint set at the adjusted address will have the 3887desired affect. If not, the breakpoint in question may be removed and 3888other breakpoints may be set which will have the desired behavior. 3889E.g., it may be sufficient to place the breakpoint at a later 3890instruction. A conditional breakpoint may also be useful in some 3891cases to prevent the breakpoint from triggering too often. 3892 3893@value{GDBN} will also issue a warning when stopping at one of these 3894adjusted breakpoints: 3895 3896@smallexample 3897warning: Breakpoint 1 address previously adjusted from 0x00010414 3898to 0x00010410. 3899@end smallexample 3900 3901When this warning is encountered, it may be too late to take remedial 3902action except in cases where the breakpoint is hit earlier or more 3903frequently than expected. 3904 3905@node Continuing and Stepping 3906@section Continuing and Stepping 3907 3908@cindex stepping 3909@cindex continuing 3910@cindex resuming execution 3911@dfn{Continuing} means resuming program execution until your program 3912completes normally. In contrast, @dfn{stepping} means executing just 3913one more ``step'' of your program, where ``step'' may mean either one 3914line of source code, or one machine instruction (depending on what 3915particular command you use). Either when continuing or when stepping, 3916your program may stop even sooner, due to a breakpoint or a signal. (If 3917it stops due to a signal, you may want to use @code{handle}, or use 3918@samp{signal 0} to resume execution. @xref{Signals, ,Signals}.) 3919 3920@table @code 3921@kindex continue 3922@kindex c @r{(@code{continue})} 3923@kindex fg @r{(resume foreground execution)} 3924@item continue @r{[}@var{ignore-count}@r{]} 3925@itemx c @r{[}@var{ignore-count}@r{]} 3926@itemx fg @r{[}@var{ignore-count}@r{]} 3927Resume program execution, at the address where your program last stopped; 3928any breakpoints set at that address are bypassed. The optional argument 3929@var{ignore-count} allows you to specify a further number of times to 3930ignore a breakpoint at this location; its effect is like that of 3931@code{ignore} (@pxref{Conditions, ,Break Conditions}). 3932 3933The argument @var{ignore-count} is meaningful only when your program 3934stopped due to a breakpoint. At other times, the argument to 3935@code{continue} is ignored. 3936 3937The synonyms @code{c} and @code{fg} (for @dfn{foreground}, as the 3938debugged program is deemed to be the foreground program) are provided 3939purely for convenience, and have exactly the same behavior as 3940@code{continue}. 3941@end table 3942 3943To resume execution at a different place, you can use @code{return} 3944(@pxref{Returning, ,Returning from a Function}) to go back to the 3945calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a 3946Different Address}) to go to an arbitrary location in your program. 3947 3948A typical technique for using stepping is to set a breakpoint 3949(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Catchpoints}) at the 3950beginning of the function or the section of your program where a problem 3951is believed to lie, run your program until it stops at that breakpoint, 3952and then step through the suspect area, examining the variables that are 3953interesting, until you see the problem happen. 3954 3955@table @code 3956@kindex step 3957@kindex s @r{(@code{step})} 3958@item step 3959Continue running your program until control reaches a different source 3960line, then stop it and return control to @value{GDBN}. This command is 3961abbreviated @code{s}. 3962 3963@quotation 3964@c "without debugging information" is imprecise; actually "without line 3965@c numbers in the debugging information". (gcc -g1 has debugging info but 3966@c not line numbers). But it seems complex to try to make that 3967@c distinction here. 3968@emph{Warning:} If you use the @code{step} command while control is 3969within a function that was compiled without debugging information, 3970execution proceeds until control reaches a function that does have 3971debugging information. Likewise, it will not step into a function which 3972is compiled without debugging information. To step through functions 3973without debugging information, use the @code{stepi} command, described 3974below. 3975@end quotation 3976 3977The @code{step} command only stops at the first instruction of a source 3978line. This prevents the multiple stops that could otherwise occur in 3979@code{switch} statements, @code{for} loops, etc. @code{step} continues 3980to stop if a function that has debugging information is called within 3981the line. In other words, @code{step} @emph{steps inside} any functions 3982called within the line. 3983 3984Also, the @code{step} command only enters a function if there is line 3985number information for the function. Otherwise it acts like the 3986@code{next} command. This avoids problems when using @code{cc -gl} 3987on MIPS machines. Previously, @code{step} entered subroutines if there 3988was any debugging information about the routine. 3989 3990@item step @var{count} 3991Continue running as in @code{step}, but do so @var{count} times. If a 3992breakpoint is reached, or a signal not related to stepping occurs before 3993@var{count} steps, stepping stops right away. 3994 3995@kindex next 3996@kindex n @r{(@code{next})} 3997@item next @r{[}@var{count}@r{]} 3998Continue to the next source line in the current (innermost) stack frame. 3999This is similar to @code{step}, but function calls that appear within 4000the line of code are executed without stopping. Execution stops when 4001control reaches a different line of code at the original stack level 4002that was executing when you gave the @code{next} command. This command 4003is abbreviated @code{n}. 4004 4005An argument @var{count} is a repeat count, as for @code{step}. 4006 4007 4008@c FIX ME!! Do we delete this, or is there a way it fits in with 4009@c the following paragraph? --- Vctoria 4010@c 4011@c @code{next} within a function that lacks debugging information acts like 4012@c @code{step}, but any function calls appearing within the code of the 4013@c function are executed without stopping. 4014 4015The @code{next} command only stops at the first instruction of a 4016source line. This prevents multiple stops that could otherwise occur in 4017@code{switch} statements, @code{for} loops, etc. 4018 4019@kindex set step-mode 4020@item set step-mode 4021@cindex functions without line info, and stepping 4022@cindex stepping into functions with no line info 4023@itemx set step-mode on 4024The @code{set step-mode on} command causes the @code{step} command to 4025stop at the first instruction of a function which contains no debug line 4026information rather than stepping over it. 4027 4028This is useful in cases where you may be interested in inspecting the 4029machine instructions of a function which has no symbolic info and do not 4030want @value{GDBN} to automatically skip over this function. 4031 4032@item set step-mode off 4033Causes the @code{step} command to step over any functions which contains no 4034debug information. This is the default. 4035 4036@item show step-mode 4037Show whether @value{GDBN} will stop in or step over functions without 4038source line debug information. 4039 4040@kindex finish 4041@item finish 4042Continue running until just after function in the selected stack frame 4043returns. Print the returned value (if any). 4044 4045Contrast this with the @code{return} command (@pxref{Returning, 4046,Returning from a Function}). 4047 4048@kindex until 4049@kindex u @r{(@code{until})} 4050@cindex run until specified location 4051@item until 4052@itemx u 4053Continue running until a source line past the current line, in the 4054current stack frame, is reached. This command is used to avoid single 4055stepping through a loop more than once. It is like the @code{next} 4056command, except that when @code{until} encounters a jump, it 4057automatically continues execution until the program counter is greater 4058than the address of the jump. 4059 4060This means that when you reach the end of a loop after single stepping 4061though it, @code{until} makes your program continue execution until it 4062exits the loop. In contrast, a @code{next} command at the end of a loop 4063simply steps back to the beginning of the loop, which forces you to step 4064through the next iteration. 4065 4066@code{until} always stops your program if it attempts to exit the current 4067stack frame. 4068 4069@code{until} may produce somewhat counterintuitive results if the order 4070of machine code does not match the order of the source lines. For 4071example, in the following excerpt from a debugging session, the @code{f} 4072(@code{frame}) command shows that execution is stopped at line 4073@code{206}; yet when we use @code{until}, we get to line @code{195}: 4074 4075@smallexample 4076(@value{GDBP}) f 4077#0 main (argc=4, argv=0xf7fffae8) at m4.c:206 4078206 expand_input(); 4079(@value{GDBP}) until 4080195 for ( ; argc > 0; NEXTARG) @{ 4081@end smallexample 4082 4083This happened because, for execution efficiency, the compiler had 4084generated code for the loop closure test at the end, rather than the 4085start, of the loop---even though the test in a C @code{for}-loop is 4086written before the body of the loop. The @code{until} command appeared 4087to step back to the beginning of the loop when it advanced to this 4088expression; however, it has not really gone to an earlier 4089statement---not in terms of the actual machine code. 4090 4091@code{until} with no argument works by means of single 4092instruction stepping, and hence is slower than @code{until} with an 4093argument. 4094 4095@item until @var{location} 4096@itemx u @var{location} 4097Continue running your program until either the specified location is 4098reached, or the current stack frame returns. @var{location} is any of 4099the forms of argument acceptable to @code{break} (@pxref{Set Breaks, 4100,Setting Breakpoints}). This form of the command uses breakpoints, and 4101hence is quicker than @code{until} without an argument. The specified 4102location is actually reached only if it is in the current frame. This 4103implies that @code{until} can be used to skip over recursive function 4104invocations. For instance in the code below, if the current location is 4105line @code{96}, issuing @code{until 99} will execute the program up to 4106line @code{99} in the same invocation of factorial, i.e., after the inner 4107invocations have returned. 4108 4109@smallexample 411094 int factorial (int value) 411195 @{ 411296 if (value > 1) @{ 411397 value *= factorial (value - 1); 411498 @} 411599 return (value); 4116100 @} 4117@end smallexample 4118 4119 4120@kindex advance @var{location} 4121@itemx advance @var{location} 4122Continue running the program up to the given @var{location}. An argument is 4123required, which should be of the same form as arguments for the @code{break} 4124command. Execution will also stop upon exit from the current stack 4125frame. This command is similar to @code{until}, but @code{advance} will 4126not skip over recursive function calls, and the target location doesn't 4127have to be in the same frame as the current one. 4128 4129 4130@kindex stepi 4131@kindex si @r{(@code{stepi})} 4132@item stepi 4133@itemx stepi @var{arg} 4134@itemx si 4135Execute one machine instruction, then stop and return to the debugger. 4136 4137It is often useful to do @samp{display/i $pc} when stepping by machine 4138instructions. This makes @value{GDBN} automatically display the next 4139instruction to be executed, each time your program stops. @xref{Auto 4140Display,, Automatic Display}. 4141 4142An argument is a repeat count, as in @code{step}. 4143 4144@need 750 4145@kindex nexti 4146@kindex ni @r{(@code{nexti})} 4147@item nexti 4148@itemx nexti @var{arg} 4149@itemx ni 4150Execute one machine instruction, but if it is a function call, 4151proceed until the function returns. 4152 4153An argument is a repeat count, as in @code{next}. 4154@end table 4155 4156@node Signals 4157@section Signals 4158@cindex signals 4159 4160A signal is an asynchronous event that can happen in a program. The 4161operating system defines the possible kinds of signals, and gives each 4162kind a name and a number. For example, in Unix @code{SIGINT} is the 4163signal a program gets when you type an interrupt character (often @kbd{Ctrl-c}); 4164@code{SIGSEGV} is the signal a program gets from referencing a place in 4165memory far away from all the areas in use; @code{SIGALRM} occurs when 4166the alarm clock timer goes off (which happens only if your program has 4167requested an alarm). 4168 4169@cindex fatal signals 4170Some signals, including @code{SIGALRM}, are a normal part of the 4171functioning of your program. Others, such as @code{SIGSEGV}, indicate 4172errors; these signals are @dfn{fatal} (they kill your program immediately) if the 4173program has not specified in advance some other way to handle the signal. 4174@code{SIGINT} does not indicate an error in your program, but it is normally 4175fatal so it can carry out the purpose of the interrupt: to kill the program. 4176 4177@value{GDBN} has the ability to detect any occurrence of a signal in your 4178program. You can tell @value{GDBN} in advance what to do for each kind of 4179signal. 4180 4181@cindex handling signals 4182Normally, @value{GDBN} is set up to let the non-erroneous signals like 4183@code{SIGALRM} be silently passed to your program 4184(so as not to interfere with their role in the program's functioning) 4185but to stop your program immediately whenever an error signal happens. 4186You can change these settings with the @code{handle} command. 4187 4188@table @code 4189@kindex info signals 4190@kindex info handle 4191@item info signals 4192@itemx info handle 4193Print a table of all the kinds of signals and how @value{GDBN} has been told to 4194handle each one. You can use this to see the signal numbers of all 4195the defined types of signals. 4196 4197@item info signals @var{sig} 4198Similar, but print information only about the specified signal number. 4199 4200@code{info handle} is an alias for @code{info signals}. 4201 4202@kindex handle 4203@item handle @var{signal} @r{[}@var{keywords}@dots{}@r{]} 4204Change the way @value{GDBN} handles signal @var{signal}. @var{signal} 4205can be the number of a signal or its name (with or without the 4206@samp{SIG} at the beginning); a list of signal numbers of the form 4207@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the 4208known signals. Optional arguments @var{keywords}, described below, 4209say what change to make. 4210@end table 4211 4212@c @group 4213The keywords allowed by the @code{handle} command can be abbreviated. 4214Their full names are: 4215 4216@table @code 4217@item nostop 4218@value{GDBN} should not stop your program when this signal happens. It may 4219still print a message telling you that the signal has come in. 4220 4221@item stop 4222@value{GDBN} should stop your program when this signal happens. This implies 4223the @code{print} keyword as well. 4224 4225@item print 4226@value{GDBN} should print a message when this signal happens. 4227 4228@item noprint 4229@value{GDBN} should not mention the occurrence of the signal at all. This 4230implies the @code{nostop} keyword as well. 4231 4232@item pass 4233@itemx noignore 4234@value{GDBN} should allow your program to see this signal; your program 4235can handle the signal, or else it may terminate if the signal is fatal 4236and not handled. @code{pass} and @code{noignore} are synonyms. 4237 4238@item nopass 4239@itemx ignore 4240@value{GDBN} should not allow your program to see this signal. 4241@code{nopass} and @code{ignore} are synonyms. 4242@end table 4243@c @end group 4244 4245When a signal stops your program, the signal is not visible to the 4246program until you 4247continue. Your program sees the signal then, if @code{pass} is in 4248effect for the signal in question @emph{at that time}. In other words, 4249after @value{GDBN} reports a signal, you can use the @code{handle} 4250command with @code{pass} or @code{nopass} to control whether your 4251program sees that signal when you continue. 4252 4253The default is set to @code{nostop}, @code{noprint}, @code{pass} for 4254non-erroneous signals such as @code{SIGALRM}, @code{SIGWINCH} and 4255@code{SIGCHLD}, and to @code{stop}, @code{print}, @code{pass} for the 4256erroneous signals. 4257 4258You can also use the @code{signal} command to prevent your program from 4259seeing a signal, or cause it to see a signal it normally would not see, 4260or to give it any signal at any time. For example, if your program stopped 4261due to some sort of memory reference error, you might store correct 4262values into the erroneous variables and continue, hoping to see more 4263execution; but your program would probably terminate immediately as 4264a result of the fatal signal once it saw the signal. To prevent this, 4265you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your 4266Program a Signal}. 4267 4268@node Thread Stops 4269@section Stopping and Starting Multi-thread Programs 4270 4271When your program has multiple threads (@pxref{Threads,, Debugging 4272Programs with Multiple Threads}), you can choose whether to set 4273breakpoints on all threads, or on a particular thread. 4274 4275@table @code 4276@cindex breakpoints and threads 4277@cindex thread breakpoints 4278@kindex break @dots{} thread @var{threadno} 4279@item break @var{linespec} thread @var{threadno} 4280@itemx break @var{linespec} thread @var{threadno} if @dots{} 4281@var{linespec} specifies source lines; there are several ways of 4282writing them, but the effect is always to specify some source line. 4283 4284Use the qualifier @samp{thread @var{threadno}} with a breakpoint command 4285to specify that you only want @value{GDBN} to stop the program when a 4286particular thread reaches this breakpoint. @var{threadno} is one of the 4287numeric thread identifiers assigned by @value{GDBN}, shown in the first 4288column of the @samp{info threads} display. 4289 4290If you do not specify @samp{thread @var{threadno}} when you set a 4291breakpoint, the breakpoint applies to @emph{all} threads of your 4292program. 4293 4294You can use the @code{thread} qualifier on conditional breakpoints as 4295well; in this case, place @samp{thread @var{threadno}} before the 4296breakpoint condition, like this: 4297 4298@smallexample 4299(@value{GDBP}) break frik.c:13 thread 28 if bartab > lim 4300@end smallexample 4301 4302@end table 4303 4304@cindex stopped threads 4305@cindex threads, stopped 4306Whenever your program stops under @value{GDBN} for any reason, 4307@emph{all} threads of execution stop, not just the current thread. This 4308allows you to examine the overall state of the program, including 4309switching between threads, without worrying that things may change 4310underfoot. 4311 4312@cindex thread breakpoints and system calls 4313@cindex system calls and thread breakpoints 4314@cindex premature return from system calls 4315There is an unfortunate side effect. If one thread stops for a 4316breakpoint, or for some other reason, and another thread is blocked in a 4317system call, then the system call may return prematurely. This is a 4318consequence of the interaction between multiple threads and the signals 4319that @value{GDBN} uses to implement breakpoints and other events that 4320stop execution. 4321 4322To handle this problem, your program should check the return value of 4323each system call and react appropriately. This is good programming 4324style anyways. 4325 4326For example, do not write code like this: 4327 4328@smallexample 4329 sleep (10); 4330@end smallexample 4331 4332The call to @code{sleep} will return early if a different thread stops 4333at a breakpoint or for some other reason. 4334 4335Instead, write this: 4336 4337@smallexample 4338 int unslept = 10; 4339 while (unslept > 0) 4340 unslept = sleep (unslept); 4341@end smallexample 4342 4343A system call is allowed to return early, so the system is still 4344conforming to its specification. But @value{GDBN} does cause your 4345multi-threaded program to behave differently than it would without 4346@value{GDBN}. 4347 4348Also, @value{GDBN} uses internal breakpoints in the thread library to 4349monitor certain events such as thread creation and thread destruction. 4350When such an event happens, a system call in another thread may return 4351prematurely, even though your program does not appear to stop. 4352 4353@cindex continuing threads 4354@cindex threads, continuing 4355Conversely, whenever you restart the program, @emph{all} threads start 4356executing. @emph{This is true even when single-stepping} with commands 4357like @code{step} or @code{next}. 4358 4359In particular, @value{GDBN} cannot single-step all threads in lockstep. 4360Since thread scheduling is up to your debugging target's operating 4361system (not controlled by @value{GDBN}), other threads may 4362execute more than one statement while the current thread completes a 4363single step. Moreover, in general other threads stop in the middle of a 4364statement, rather than at a clean statement boundary, when the program 4365stops. 4366 4367You might even find your program stopped in another thread after 4368continuing or even single-stepping. This happens whenever some other 4369thread runs into a breakpoint, a signal, or an exception before the 4370first thread completes whatever you requested. 4371 4372On some OSes, you can lock the OS scheduler and thus allow only a single 4373thread to run. 4374 4375@table @code 4376@item set scheduler-locking @var{mode} 4377@cindex scheduler locking mode 4378@cindex lock scheduler 4379Set the scheduler locking mode. If it is @code{off}, then there is no 4380locking and any thread may run at any time. If @code{on}, then only the 4381current thread may run when the inferior is resumed. The @code{step} 4382mode optimizes for single-stepping. It stops other threads from 4383``seizing the prompt'' by preempting the current thread while you are 4384stepping. Other threads will only rarely (or never) get a chance to run 4385when you step. They are more likely to run when you @samp{next} over a 4386function call, and they are completely free to run when you use commands 4387like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another 4388thread hits a breakpoint during its timeslice, they will never steal the 4389@value{GDBN} prompt away from the thread that you are debugging. 4390 4391@item show scheduler-locking 4392Display the current scheduler locking mode. 4393@end table 4394 4395 4396@node Stack 4397@chapter Examining the Stack 4398 4399When your program has stopped, the first thing you need to know is where it 4400stopped and how it got there. 4401 4402@cindex call stack 4403Each time your program performs a function call, information about the call 4404is generated. 4405That information includes the location of the call in your program, 4406the arguments of the call, 4407and the local variables of the function being called. 4408The information is saved in a block of data called a @dfn{stack frame}. 4409The stack frames are allocated in a region of memory called the @dfn{call 4410stack}. 4411 4412When your program stops, the @value{GDBN} commands for examining the 4413stack allow you to see all of this information. 4414 4415@cindex selected frame 4416One of the stack frames is @dfn{selected} by @value{GDBN} and many 4417@value{GDBN} commands refer implicitly to the selected frame. In 4418particular, whenever you ask @value{GDBN} for the value of a variable in 4419your program, the value is found in the selected frame. There are 4420special @value{GDBN} commands to select whichever frame you are 4421interested in. @xref{Selection, ,Selecting a Frame}. 4422 4423When your program stops, @value{GDBN} automatically selects the 4424currently executing frame and describes it briefly, similar to the 4425@code{frame} command (@pxref{Frame Info, ,Information about a Frame}). 4426 4427@menu 4428* Frames:: Stack frames 4429* Backtrace:: Backtraces 4430* Selection:: Selecting a frame 4431* Frame Info:: Information on a frame 4432 4433@end menu 4434 4435@node Frames 4436@section Stack Frames 4437 4438@cindex frame, definition 4439@cindex stack frame 4440The call stack is divided up into contiguous pieces called @dfn{stack 4441frames}, or @dfn{frames} for short; each frame is the data associated 4442with one call to one function. The frame contains the arguments given 4443to the function, the function's local variables, and the address at 4444which the function is executing. 4445 4446@cindex initial frame 4447@cindex outermost frame 4448@cindex innermost frame 4449When your program is started, the stack has only one frame, that of the 4450function @code{main}. This is called the @dfn{initial} frame or the 4451@dfn{outermost} frame. Each time a function is called, a new frame is 4452made. Each time a function returns, the frame for that function invocation 4453is eliminated. If a function is recursive, there can be many frames for 4454the same function. The frame for the function in which execution is 4455actually occurring is called the @dfn{innermost} frame. This is the most 4456recently created of all the stack frames that still exist. 4457 4458@cindex frame pointer 4459Inside your program, stack frames are identified by their addresses. A 4460stack frame consists of many bytes, each of which has its own address; each 4461kind of computer has a convention for choosing one byte whose 4462address serves as the address of the frame. Usually this address is kept 4463in a register called the @dfn{frame pointer register} 4464(@pxref{Registers, $fp}) while execution is going on in that frame. 4465 4466@cindex frame number 4467@value{GDBN} assigns numbers to all existing stack frames, starting with 4468zero for the innermost frame, one for the frame that called it, 4469and so on upward. These numbers do not really exist in your program; 4470they are assigned by @value{GDBN} to give you a way of designating stack 4471frames in @value{GDBN} commands. 4472 4473@c The -fomit-frame-pointer below perennially causes hbox overflow 4474@c underflow problems. 4475@cindex frameless execution 4476Some compilers provide a way to compile functions so that they operate 4477without stack frames. (For example, the @value{NGCC} option 4478@smallexample 4479@samp{-fomit-frame-pointer} 4480@end smallexample 4481generates functions without a frame.) 4482This is occasionally done with heavily used library functions to save 4483the frame setup time. @value{GDBN} has limited facilities for dealing 4484with these function invocations. If the innermost function invocation 4485has no stack frame, @value{GDBN} nevertheless regards it as though 4486it had a separate frame, which is numbered zero as usual, allowing 4487correct tracing of the function call chain. However, @value{GDBN} has 4488no provision for frameless functions elsewhere in the stack. 4489 4490@table @code 4491@kindex frame@r{, command} 4492@cindex current stack frame 4493@item frame @var{args} 4494The @code{frame} command allows you to move from one stack frame to another, 4495and to print the stack frame you select. @var{args} may be either the 4496address of the frame or the stack frame number. Without an argument, 4497@code{frame} prints the current stack frame. 4498 4499@kindex select-frame 4500@cindex selecting frame silently 4501@item select-frame 4502The @code{select-frame} command allows you to move from one stack frame 4503to another without printing the frame. This is the silent version of 4504@code{frame}. 4505@end table 4506 4507@node Backtrace 4508@section Backtraces 4509 4510@cindex traceback 4511@cindex call stack traces 4512A backtrace is a summary of how your program got where it is. It shows one 4513line per frame, for many frames, starting with the currently executing 4514frame (frame zero), followed by its caller (frame one), and on up the 4515stack. 4516 4517@table @code 4518@kindex backtrace 4519@kindex bt @r{(@code{backtrace})} 4520@item backtrace 4521@itemx bt 4522Print a backtrace of the entire stack: one line per frame for all 4523frames in the stack. 4524 4525You can stop the backtrace at any time by typing the system interrupt 4526character, normally @kbd{Ctrl-c}. 4527 4528@item backtrace @var{n} 4529@itemx bt @var{n} 4530Similar, but print only the innermost @var{n} frames. 4531 4532@item backtrace -@var{n} 4533@itemx bt -@var{n} 4534Similar, but print only the outermost @var{n} frames. 4535 4536@item backtrace full 4537@itemx bt full 4538@itemx bt full @var{n} 4539@itemx bt full -@var{n} 4540Print the values of the local variables also. @var{n} specifies the 4541number of frames to print, as described above. 4542@end table 4543 4544@kindex where 4545@kindex info stack 4546The names @code{where} and @code{info stack} (abbreviated @code{info s}) 4547are additional aliases for @code{backtrace}. 4548 4549@cindex multiple threads, backtrace 4550In a multi-threaded program, @value{GDBN} by default shows the 4551backtrace only for the current thread. To display the backtrace for 4552several or all of the threads, use the command @code{thread apply} 4553(@pxref{Threads, thread apply}). For example, if you type @kbd{thread 4554apply all backtrace}, @value{GDBN} will display the backtrace for all 4555the threads; this is handy when you debug a core dump of a 4556multi-threaded program. 4557 4558Each line in the backtrace shows the frame number and the function name. 4559The program counter value is also shown---unless you use @code{set 4560print address off}. The backtrace also shows the source file name and 4561line number, as well as the arguments to the function. The program 4562counter value is omitted if it is at the beginning of the code for that 4563line number. 4564 4565Here is an example of a backtrace. It was made with the command 4566@samp{bt 3}, so it shows the innermost three frames. 4567 4568@smallexample 4569@group 4570#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) 4571 at builtin.c:993 4572#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242 4573#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) 4574 at macro.c:71 4575(More stack frames follow...) 4576@end group 4577@end smallexample 4578 4579@noindent 4580The display for frame zero does not begin with a program counter 4581value, indicating that your program has stopped at the beginning of the 4582code for line @code{993} of @code{builtin.c}. 4583 4584@cindex value optimized out, in backtrace 4585@cindex function call arguments, optimized out 4586If your program was compiled with optimizations, some compilers will 4587optimize away arguments passed to functions if those arguments are 4588never used after the call. Such optimizations generate code that 4589passes arguments through registers, but doesn't store those arguments 4590in the stack frame. @value{GDBN} has no way of displaying such 4591arguments in stack frames other than the innermost one. Here's what 4592such a backtrace might look like: 4593 4594@smallexample 4595@group 4596#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) 4597 at builtin.c:993 4598#1 0x6e38 in expand_macro (sym=<value optimized out>) at macro.c:242 4599#2 0x6840 in expand_token (obs=0x0, t=<value optimized out>, td=0xf7fffb08) 4600 at macro.c:71 4601(More stack frames follow...) 4602@end group 4603@end smallexample 4604 4605@noindent 4606The values of arguments that were not saved in their stack frames are 4607shown as @samp{<value optimized out>}. 4608 4609If you need to display the values of such optimized-out arguments, 4610either deduce that from other variables whose values depend on the one 4611you are interested in, or recompile without optimizations. 4612 4613@cindex backtrace beyond @code{main} function 4614@cindex program entry point 4615@cindex startup code, and backtrace 4616Most programs have a standard user entry point---a place where system 4617libraries and startup code transition into user code. For C this is 4618@code{main}@footnote{ 4619Note that embedded programs (the so-called ``free-standing'' 4620environment) are not required to have a @code{main} function as the 4621entry point. They could even have multiple entry points.}. 4622When @value{GDBN} finds the entry function in a backtrace 4623it will terminate the backtrace, to avoid tracing into highly 4624system-specific (and generally uninteresting) code. 4625 4626If you need to examine the startup code, or limit the number of levels 4627in a backtrace, you can change this behavior: 4628 4629@table @code 4630@item set backtrace past-main 4631@itemx set backtrace past-main on 4632@kindex set backtrace 4633Backtraces will continue past the user entry point. 4634 4635@item set backtrace past-main off 4636Backtraces will stop when they encounter the user entry point. This is the 4637default. 4638 4639@item show backtrace past-main 4640@kindex show backtrace 4641Display the current user entry point backtrace policy. 4642 4643@item set backtrace past-entry 4644@itemx set backtrace past-entry on 4645Backtraces will continue past the internal entry point of an application. 4646This entry point is encoded by the linker when the application is built, 4647and is likely before the user entry point @code{main} (or equivalent) is called. 4648 4649@item set backtrace past-entry off 4650Backtraces will stop when they encounter the internal entry point of an 4651application. This is the default. 4652 4653@item show backtrace past-entry 4654Display the current internal entry point backtrace policy. 4655 4656@item set backtrace limit @var{n} 4657@itemx set backtrace limit 0 4658@cindex backtrace limit 4659Limit the backtrace to @var{n} levels. A value of zero means 4660unlimited. 4661 4662@item show backtrace limit 4663Display the current limit on backtrace levels. 4664@end table 4665 4666@node Selection 4667@section Selecting a Frame 4668 4669Most commands for examining the stack and other data in your program work on 4670whichever stack frame is selected at the moment. Here are the commands for 4671selecting a stack frame; all of them finish by printing a brief description 4672of the stack frame just selected. 4673 4674@table @code 4675@kindex frame@r{, selecting} 4676@kindex f @r{(@code{frame})} 4677@item frame @var{n} 4678@itemx f @var{n} 4679Select frame number @var{n}. Recall that frame zero is the innermost 4680(currently executing) frame, frame one is the frame that called the 4681innermost one, and so on. The highest-numbered frame is the one for 4682@code{main}. 4683 4684@item frame @var{addr} 4685@itemx f @var{addr} 4686Select the frame at address @var{addr}. This is useful mainly if the 4687chaining of stack frames has been damaged by a bug, making it 4688impossible for @value{GDBN} to assign numbers properly to all frames. In 4689addition, this can be useful when your program has multiple stacks and 4690switches between them. 4691 4692On the SPARC architecture, @code{frame} needs two addresses to 4693select an arbitrary frame: a frame pointer and a stack pointer. 4694 4695On the MIPS and Alpha architecture, it needs two addresses: a stack 4696pointer and a program counter. 4697 4698On the 29k architecture, it needs three addresses: a register stack 4699pointer, a program counter, and a memory stack pointer. 4700 4701@kindex up 4702@item up @var{n} 4703Move @var{n} frames up the stack. For positive numbers @var{n}, this 4704advances toward the outermost frame, to higher frame numbers, to frames 4705that have existed longer. @var{n} defaults to one. 4706 4707@kindex down 4708@kindex do @r{(@code{down})} 4709@item down @var{n} 4710Move @var{n} frames down the stack. For positive numbers @var{n}, this 4711advances toward the innermost frame, to lower frame numbers, to frames 4712that were created more recently. @var{n} defaults to one. You may 4713abbreviate @code{down} as @code{do}. 4714@end table 4715 4716All of these commands end by printing two lines of output describing the 4717frame. The first line shows the frame number, the function name, the 4718arguments, and the source file and line number of execution in that 4719frame. The second line shows the text of that source line. 4720 4721@need 1000 4722For example: 4723 4724@smallexample 4725@group 4726(@value{GDBP}) up 4727#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) 4728 at env.c:10 472910 read_input_file (argv[i]); 4730@end group 4731@end smallexample 4732 4733After such a printout, the @code{list} command with no arguments 4734prints ten lines centered on the point of execution in the frame. 4735You can also edit the program at the point of execution with your favorite 4736editing program by typing @code{edit}. 4737@xref{List, ,Printing Source Lines}, 4738for details. 4739 4740@table @code 4741@kindex down-silently 4742@kindex up-silently 4743@item up-silently @var{n} 4744@itemx down-silently @var{n} 4745These two commands are variants of @code{up} and @code{down}, 4746respectively; they differ in that they do their work silently, without 4747causing display of the new frame. They are intended primarily for use 4748in @value{GDBN} command scripts, where the output might be unnecessary and 4749distracting. 4750@end table 4751 4752@node Frame Info 4753@section Information About a Frame 4754 4755There are several other commands to print information about the selected 4756stack frame. 4757 4758@table @code 4759@item frame 4760@itemx f 4761When used without any argument, this command does not change which 4762frame is selected, but prints a brief description of the currently 4763selected stack frame. It can be abbreviated @code{f}. With an 4764argument, this command is used to select a stack frame. 4765@xref{Selection, ,Selecting a Frame}. 4766 4767@kindex info frame 4768@kindex info f @r{(@code{info frame})} 4769@item info frame 4770@itemx info f 4771This command prints a verbose description of the selected stack frame, 4772including: 4773 4774@itemize @bullet 4775@item 4776the address of the frame 4777@item 4778the address of the next frame down (called by this frame) 4779@item 4780the address of the next frame up (caller of this frame) 4781@item 4782the language in which the source code corresponding to this frame is written 4783@item 4784the address of the frame's arguments 4785@item 4786the address of the frame's local variables 4787@item 4788the program counter saved in it (the address of execution in the caller frame) 4789@item 4790which registers were saved in the frame 4791@end itemize 4792 4793@noindent The verbose description is useful when 4794something has gone wrong that has made the stack format fail to fit 4795the usual conventions. 4796 4797@item info frame @var{addr} 4798@itemx info f @var{addr} 4799Print a verbose description of the frame at address @var{addr}, without 4800selecting that frame. The selected frame remains unchanged by this 4801command. This requires the same kind of address (more than one for some 4802architectures) that you specify in the @code{frame} command. 4803@xref{Selection, ,Selecting a Frame}. 4804 4805@kindex info args 4806@item info args 4807Print the arguments of the selected frame, each on a separate line. 4808 4809@item info locals 4810@kindex info locals 4811Print the local variables of the selected frame, each on a separate 4812line. These are all variables (declared either static or automatic) 4813accessible at the point of execution of the selected frame. 4814 4815@kindex info catch 4816@cindex catch exceptions, list active handlers 4817@cindex exception handlers, how to list 4818@item info catch 4819Print a list of all the exception handlers that are active in the 4820current stack frame at the current point of execution. To see other 4821exception handlers, visit the associated frame (using the @code{up}, 4822@code{down}, or @code{frame} commands); then type @code{info catch}. 4823@xref{Set Catchpoints, , Setting Catchpoints}. 4824 4825@end table 4826 4827 4828@node Source 4829@chapter Examining Source Files 4830 4831@value{GDBN} can print parts of your program's source, since the debugging 4832information recorded in the program tells @value{GDBN} what source files were 4833used to build it. When your program stops, @value{GDBN} spontaneously prints 4834the line where it stopped. Likewise, when you select a stack frame 4835(@pxref{Selection, ,Selecting a Frame}), @value{GDBN} prints the line where 4836execution in that frame has stopped. You can print other portions of 4837source files by explicit command. 4838 4839If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may 4840prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using 4841@value{GDBN} under @sc{gnu} Emacs}. 4842 4843@menu 4844* List:: Printing source lines 4845* Edit:: Editing source files 4846* Search:: Searching source files 4847* Source Path:: Specifying source directories 4848* Machine Code:: Source and machine code 4849@end menu 4850 4851@node List 4852@section Printing Source Lines 4853 4854@kindex list 4855@kindex l @r{(@code{list})} 4856To print lines from a source file, use the @code{list} command 4857(abbreviated @code{l}). By default, ten lines are printed. 4858There are several ways to specify what part of the file you want to print. 4859 4860Here are the forms of the @code{list} command most commonly used: 4861 4862@table @code 4863@item list @var{linenum} 4864Print lines centered around line number @var{linenum} in the 4865current source file. 4866 4867@item list @var{function} 4868Print lines centered around the beginning of function 4869@var{function}. 4870 4871@item list 4872Print more lines. If the last lines printed were printed with a 4873@code{list} command, this prints lines following the last lines 4874printed; however, if the last line printed was a solitary line printed 4875as part of displaying a stack frame (@pxref{Stack, ,Examining the 4876Stack}), this prints lines centered around that line. 4877 4878@item list - 4879Print lines just before the lines last printed. 4880@end table 4881 4882@cindex @code{list}, how many lines to display 4883By default, @value{GDBN} prints ten source lines with any of these forms of 4884the @code{list} command. You can change this using @code{set listsize}: 4885 4886@table @code 4887@kindex set listsize 4888@item set listsize @var{count} 4889Make the @code{list} command display @var{count} source lines (unless 4890the @code{list} argument explicitly specifies some other number). 4891 4892@kindex show listsize 4893@item show listsize 4894Display the number of lines that @code{list} prints. 4895@end table 4896 4897Repeating a @code{list} command with @key{RET} discards the argument, 4898so it is equivalent to typing just @code{list}. This is more useful 4899than listing the same lines again. An exception is made for an 4900argument of @samp{-}; that argument is preserved in repetition so that 4901each repetition moves up in the source file. 4902 4903@cindex linespec 4904In general, the @code{list} command expects you to supply zero, one or two 4905@dfn{linespecs}. Linespecs specify source lines; there are several ways 4906of writing them, but the effect is always to specify some source line. 4907Here is a complete description of the possible arguments for @code{list}: 4908 4909@table @code 4910@item list @var{linespec} 4911Print lines centered around the line specified by @var{linespec}. 4912 4913@item list @var{first},@var{last} 4914Print lines from @var{first} to @var{last}. Both arguments are 4915linespecs. 4916 4917@item list ,@var{last} 4918Print lines ending with @var{last}. 4919 4920@item list @var{first}, 4921Print lines starting with @var{first}. 4922 4923@item list + 4924Print lines just after the lines last printed. 4925 4926@item list - 4927Print lines just before the lines last printed. 4928 4929@item list 4930As described in the preceding table. 4931@end table 4932 4933Here are the ways of specifying a single source line---all the 4934kinds of linespec. 4935 4936@table @code 4937@item @var{number} 4938Specifies line @var{number} of the current source file. 4939When a @code{list} command has two linespecs, this refers to 4940the same source file as the first linespec. 4941 4942@item +@var{offset} 4943Specifies the line @var{offset} lines after the last line printed. 4944When used as the second linespec in a @code{list} command that has 4945two, this specifies the line @var{offset} lines down from the 4946first linespec. 4947 4948@item -@var{offset} 4949Specifies the line @var{offset} lines before the last line printed. 4950 4951@item @var{filename}:@var{number} 4952Specifies line @var{number} in the source file @var{filename}. 4953 4954@item @var{function} 4955Specifies the line that begins the body of the function @var{function}. 4956For example: in C, this is the line with the open brace. 4957 4958@item @var{filename}:@var{function} 4959Specifies the line of the open-brace that begins the body of the 4960function @var{function} in the file @var{filename}. You only need the 4961file name with a function name to avoid ambiguity when there are 4962identically named functions in different source files. 4963 4964@item *@var{address} 4965Specifies the line containing the program address @var{address}. 4966@var{address} may be any expression. 4967@end table 4968 4969@node Edit 4970@section Editing Source Files 4971@cindex editing source files 4972 4973@kindex edit 4974@kindex e @r{(@code{edit})} 4975To edit the lines in a source file, use the @code{edit} command. 4976The editing program of your choice 4977is invoked with the current line set to 4978the active line in the program. 4979Alternatively, there are several ways to specify what part of the file you 4980want to print if you want to see other parts of the program. 4981 4982Here are the forms of the @code{edit} command most commonly used: 4983 4984@table @code 4985@item edit 4986Edit the current source file at the active line number in the program. 4987 4988@item edit @var{number} 4989Edit the current source file with @var{number} as the active line number. 4990 4991@item edit @var{function} 4992Edit the file containing @var{function} at the beginning of its definition. 4993 4994@item edit @var{filename}:@var{number} 4995Specifies line @var{number} in the source file @var{filename}. 4996 4997@item edit @var{filename}:@var{function} 4998Specifies the line that begins the body of the 4999function @var{function} in the file @var{filename}. You only need the 5000file name with a function name to avoid ambiguity when there are 5001identically named functions in different source files. 5002 5003@item edit *@var{address} 5004Specifies the line containing the program address @var{address}. 5005@var{address} may be any expression. 5006@end table 5007 5008@subsection Choosing your Editor 5009You can customize @value{GDBN} to use any editor you want 5010@footnote{ 5011The only restriction is that your editor (say @code{ex}), recognizes the 5012following command-line syntax: 5013@smallexample 5014ex +@var{number} file 5015@end smallexample 5016The optional numeric value +@var{number} specifies the number of the line in 5017the file where to start editing.}. 5018By default, it is @file{@value{EDITOR}}, but you can change this 5019by setting the environment variable @code{EDITOR} before using 5020@value{GDBN}. For example, to configure @value{GDBN} to use the 5021@code{vi} editor, you could use these commands with the @code{sh} shell: 5022@smallexample 5023EDITOR=/usr/bin/vi 5024export EDITOR 5025gdb @dots{} 5026@end smallexample 5027or in the @code{csh} shell, 5028@smallexample 5029setenv EDITOR /usr/bin/vi 5030gdb @dots{} 5031@end smallexample 5032 5033@node Search 5034@section Searching Source Files 5035@cindex searching source files 5036 5037There are two commands for searching through the current source file for a 5038regular expression. 5039 5040@table @code 5041@kindex search 5042@kindex forward-search 5043@item forward-search @var{regexp} 5044@itemx search @var{regexp} 5045The command @samp{forward-search @var{regexp}} checks each line, 5046starting with the one following the last line listed, for a match for 5047@var{regexp}. It lists the line that is found. You can use the 5048synonym @samp{search @var{regexp}} or abbreviate the command name as 5049@code{fo}. 5050 5051@kindex reverse-search 5052@item reverse-search @var{regexp} 5053The command @samp{reverse-search @var{regexp}} checks each line, starting 5054with the one before the last line listed and going backward, for a match 5055for @var{regexp}. It lists the line that is found. You can abbreviate 5056this command as @code{rev}. 5057@end table 5058 5059@node Source Path 5060@section Specifying Source Directories 5061 5062@cindex source path 5063@cindex directories for source files 5064Executable programs sometimes do not record the directories of the source 5065files from which they were compiled, just the names. Even when they do, 5066the directories could be moved between the compilation and your debugging 5067session. @value{GDBN} has a list of directories to search for source files; 5068this is called the @dfn{source path}. Each time @value{GDBN} wants a source file, 5069it tries all the directories in the list, in the order they are present 5070in the list, until it finds a file with the desired name. 5071 5072For example, suppose an executable references the file 5073@file{/usr/src/foo-1.0/lib/foo.c}, and our source path is 5074@file{/mnt/cross}. The file is first looked up literally; if this 5075fails, @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} is tried; if this 5076fails, @file{/mnt/cross/foo.c} is opened; if this fails, an error 5077message is printed. @value{GDBN} does not look up the parts of the 5078source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}. 5079Likewise, the subdirectories of the source path are not searched: if 5080the source path is @file{/mnt/cross}, and the binary refers to 5081@file{foo.c}, @value{GDBN} would not find it under 5082@file{/mnt/cross/usr/src/foo-1.0/lib}. 5083 5084Plain file names, relative file names with leading directories, file 5085names containing dots, etc.@: are all treated as described above; for 5086instance, if the source path is @file{/mnt/cross}, and the source file 5087is recorded as @file{../lib/foo.c}, @value{GDBN} would first try 5088@file{../lib/foo.c}, then @file{/mnt/cross/../lib/foo.c}, and after 5089that---@file{/mnt/cross/foo.c}. 5090 5091Note that the executable search path is @emph{not} used to locate the 5092source files. 5093 5094Whenever you reset or rearrange the source path, @value{GDBN} clears out 5095any information it has cached about where source files are found and where 5096each line is in the file. 5097 5098@kindex directory 5099@kindex dir 5100When you start @value{GDBN}, its source path includes only @samp{cdir} 5101and @samp{cwd}, in that order. 5102To add other directories, use the @code{directory} command. 5103 5104The search path is used to find both program source files and @value{GDBN} 5105script files (read using the @samp{-command} option and @samp{source} command). 5106 5107In addition to the source path, @value{GDBN} provides a set of commands 5108that manage a list of source path substitution rules. A @dfn{substitution 5109rule} specifies how to rewrite source directories stored in the program's 5110debug information in case the sources were moved to a different 5111directory between compilation and debugging. A rule is made of 5112two strings, the first specifying what needs to be rewritten in 5113the path, and the second specifying how it should be rewritten. 5114In @ref{set substitute-path}, we name these two parts @var{from} and 5115@var{to} respectively. @value{GDBN} does a simple string replacement 5116of @var{from} with @var{to} at the start of the directory part of the 5117source file name, and uses that result instead of the original file 5118name to look up the sources. 5119 5120Using the previous example, suppose the @file{foo-1.0} tree has been 5121moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell 5122@value{GDBN} to replace @file{/usr/src} in all source path names with 5123@file{/mnt/cross}. The first lookup will then be 5124@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location 5125of @file{/usr/src/foo-1.0/lib/foo.c}. To define a source path 5126substitution rule, use the @code{set substitute-path} command 5127(@pxref{set substitute-path}). 5128 5129To avoid unexpected substitution results, a rule is applied only if the 5130@var{from} part of the directory name ends at a directory separator. 5131For instance, a rule substituting @file{/usr/source} into 5132@file{/mnt/cross} will be applied to @file{/usr/source/foo-1.0} but 5133not to @file{/usr/sourceware/foo-2.0}. And because the substitution 5134is applied only at the beginning of the directory name, this rule will 5135not be applied to @file{/root/usr/source/baz.c} either. 5136 5137In many cases, you can achieve the same result using the @code{directory} 5138command. However, @code{set substitute-path} can be more efficient in 5139the case where the sources are organized in a complex tree with multiple 5140subdirectories. With the @code{directory} command, you need to add each 5141subdirectory of your project. If you moved the entire tree while 5142preserving its internal organization, then @code{set substitute-path} 5143allows you to direct the debugger to all the sources with one single 5144command. 5145 5146@code{set substitute-path} is also more than just a shortcut command. 5147The source path is only used if the file at the original location no 5148longer exists. On the other hand, @code{set substitute-path} modifies 5149the debugger behavior to look at the rewritten location instead. So, if 5150for any reason a source file that is not relevant to your executable is 5151located at the original location, a substitution rule is the only 5152method available to point @value{GDBN} at the new location. 5153 5154@table @code 5155@item directory @var{dirname} @dots{} 5156@item dir @var{dirname} @dots{} 5157Add directory @var{dirname} to the front of the source path. Several 5158directory names may be given to this command, separated by @samp{:} 5159(@samp{;} on MS-DOS and MS-Windows, where @samp{:} usually appears as 5160part of absolute file names) or 5161whitespace. You may specify a directory that is already in the source 5162path; this moves it forward, so @value{GDBN} searches it sooner. 5163 5164@kindex cdir 5165@kindex cwd 5166@vindex $cdir@r{, convenience variable} 5167@vindex $cwd@r{, convenience variable} 5168@cindex compilation directory 5169@cindex current directory 5170@cindex working directory 5171@cindex directory, current 5172@cindex directory, compilation 5173You can use the string @samp{$cdir} to refer to the compilation 5174directory (if one is recorded), and @samp{$cwd} to refer to the current 5175working directory. @samp{$cwd} is not the same as @samp{.}---the former 5176tracks the current working directory as it changes during your @value{GDBN} 5177session, while the latter is immediately expanded to the current 5178directory at the time you add an entry to the source path. 5179 5180@item directory 5181Reset the source path to its default value (@samp{$cdir:$cwd} on Unix systems). This requires confirmation. 5182 5183@c RET-repeat for @code{directory} is explicitly disabled, but since 5184@c repeating it would be a no-op we do not say that. (thanks to RMS) 5185 5186@item show directories 5187@kindex show directories 5188Print the source path: show which directories it contains. 5189 5190@anchor{set substitute-path} 5191@item set substitute-path @var{from} @var{to} 5192@kindex set substitute-path 5193Define a source path substitution rule, and add it at the end of the 5194current list of existing substitution rules. If a rule with the same 5195@var{from} was already defined, then the old rule is also deleted. 5196 5197For example, if the file @file{/foo/bar/baz.c} was moved to 5198@file{/mnt/cross/baz.c}, then the command 5199 5200@smallexample 5201(@value{GDBP}) set substitute-path /usr/src /mnt/cross 5202@end smallexample 5203 5204@noindent 5205will tell @value{GDBN} to replace @samp{/usr/src} with 5206@samp{/mnt/cross}, which will allow @value{GDBN} to find the file 5207@file{baz.c} even though it was moved. 5208 5209In the case when more than one substitution rule have been defined, 5210the rules are evaluated one by one in the order where they have been 5211defined. The first one matching, if any, is selected to perform 5212the substitution. 5213 5214For instance, if we had entered the following commands: 5215 5216@smallexample 5217(@value{GDBP}) set substitute-path /usr/src/include /mnt/include 5218(@value{GDBP}) set substitute-path /usr/src /mnt/src 5219@end smallexample 5220 5221@noindent 5222@value{GDBN} would then rewrite @file{/usr/src/include/defs.h} into 5223@file{/mnt/include/defs.h} by using the first rule. However, it would 5224use the second rule to rewrite @file{/usr/src/lib/foo.c} into 5225@file{/mnt/src/lib/foo.c}. 5226 5227 5228@item unset substitute-path [path] 5229@kindex unset substitute-path 5230If a path is specified, search the current list of substitution rules 5231for a rule that would rewrite that path. Delete that rule if found. 5232A warning is emitted by the debugger if no rule could be found. 5233 5234If no path is specified, then all substitution rules are deleted. 5235 5236@item show substitute-path [path] 5237@kindex show substitute-path 5238If a path is specified, then print the source path substitution rule 5239which would rewrite that path, if any. 5240 5241If no path is specified, then print all existing source path substitution 5242rules. 5243 5244@end table 5245 5246If your source path is cluttered with directories that are no longer of 5247interest, @value{GDBN} may sometimes cause confusion by finding the wrong 5248versions of source. You can correct the situation as follows: 5249 5250@enumerate 5251@item 5252Use @code{directory} with no argument to reset the source path to its default value. 5253 5254@item 5255Use @code{directory} with suitable arguments to reinstall the 5256directories you want in the source path. You can add all the 5257directories in one command. 5258@end enumerate 5259 5260@node Machine Code 5261@section Source and Machine Code 5262@cindex source line and its code address 5263 5264You can use the command @code{info line} to map source lines to program 5265addresses (and vice versa), and the command @code{disassemble} to display 5266a range of addresses as machine instructions. When run under @sc{gnu} Emacs 5267mode, the @code{info line} command causes the arrow to point to the 5268line specified. Also, @code{info line} prints addresses in symbolic form as 5269well as hex. 5270 5271@table @code 5272@kindex info line 5273@item info line @var{linespec} 5274Print the starting and ending addresses of the compiled code for 5275source line @var{linespec}. You can specify source lines in any of 5276the ways understood by the @code{list} command (@pxref{List, ,Printing 5277Source Lines}). 5278@end table 5279 5280For example, we can use @code{info line} to discover the location of 5281the object code for the first line of function 5282@code{m4_changequote}: 5283 5284@c FIXME: I think this example should also show the addresses in 5285@c symbolic form, as they usually would be displayed. 5286@smallexample 5287(@value{GDBP}) info line m4_changequote 5288Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. 5289@end smallexample 5290 5291@noindent 5292@cindex code address and its source line 5293We can also inquire (using @code{*@var{addr}} as the form for 5294@var{linespec}) what source line covers a particular address: 5295@smallexample 5296(@value{GDBP}) info line *0x63ff 5297Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. 5298@end smallexample 5299 5300@cindex @code{$_} and @code{info line} 5301@cindex @code{x} command, default address 5302@kindex x@r{(examine), and} info line 5303After @code{info line}, the default address for the @code{x} command 5304is changed to the starting address of the line, so that @samp{x/i} is 5305sufficient to begin examining the machine code (@pxref{Memory, 5306,Examining Memory}). Also, this address is saved as the value of the 5307convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience 5308Variables}). 5309 5310@table @code 5311@kindex disassemble 5312@cindex assembly instructions 5313@cindex instructions, assembly 5314@cindex machine instructions 5315@cindex listing machine instructions 5316@item disassemble 5317This specialized command dumps a range of memory as machine 5318instructions. The default memory range is the function surrounding the 5319program counter of the selected frame. A single argument to this 5320command is a program counter value; @value{GDBN} dumps the function 5321surrounding this value. Two arguments specify a range of addresses 5322(first inclusive, second exclusive) to dump. 5323@end table 5324 5325The following example shows the disassembly of a range of addresses of 5326HP PA-RISC 2.0 code: 5327 5328@smallexample 5329(@value{GDBP}) disas 0x32c4 0x32e4 5330Dump of assembler code from 0x32c4 to 0x32e4: 53310x32c4 <main+204>: addil 0,dp 53320x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 53330x32cc <main+212>: ldil 0x3000,r31 53340x32d0 <main+216>: ble 0x3f8(sr4,r31) 53350x32d4 <main+220>: ldo 0(r31),rp 53360x32d8 <main+224>: addil -0x800,dp 53370x32dc <main+228>: ldo 0x588(r1),r26 53380x32e0 <main+232>: ldil 0x3000,r31 5339End of assembler dump. 5340@end smallexample 5341 5342Some architectures have more than one commonly-used set of instruction 5343mnemonics or other syntax. 5344 5345For programs that were dynamically linked and use shared libraries, 5346instructions that call functions or branch to locations in the shared 5347libraries might show a seemingly bogus location---it's actually a 5348location of the relocation table. On some architectures, @value{GDBN} 5349might be able to resolve these to actual function names. 5350 5351@table @code 5352@kindex set disassembly-flavor 5353@cindex Intel disassembly flavor 5354@cindex AT&T disassembly flavor 5355@item set disassembly-flavor @var{instruction-set} 5356Select the instruction set to use when disassembling the 5357program via the @code{disassemble} or @code{x/i} commands. 5358 5359Currently this command is only defined for the Intel x86 family. You 5360can set @var{instruction-set} to either @code{intel} or @code{att}. 5361The default is @code{att}, the AT&T flavor used by default by Unix 5362assemblers for x86-based targets. 5363 5364@kindex show disassembly-flavor 5365@item show disassembly-flavor 5366Show the current setting of the disassembly flavor. 5367@end table 5368 5369 5370@node Data 5371@chapter Examining Data 5372 5373@cindex printing data 5374@cindex examining data 5375@kindex print 5376@kindex inspect 5377@c "inspect" is not quite a synonym if you are using Epoch, which we do not 5378@c document because it is nonstandard... Under Epoch it displays in a 5379@c different window or something like that. 5380The usual way to examine data in your program is with the @code{print} 5381command (abbreviated @code{p}), or its synonym @code{inspect}. It 5382evaluates and prints the value of an expression of the language your 5383program is written in (@pxref{Languages, ,Using @value{GDBN} with 5384Different Languages}). 5385 5386@table @code 5387@item print @var{expr} 5388@itemx print /@var{f} @var{expr} 5389@var{expr} is an expression (in the source language). By default the 5390value of @var{expr} is printed in a format appropriate to its data type; 5391you can choose a different format by specifying @samp{/@var{f}}, where 5392@var{f} is a letter specifying the format; see @ref{Output Formats,,Output 5393Formats}. 5394 5395@item print 5396@itemx print /@var{f} 5397@cindex reprint the last value 5398If you omit @var{expr}, @value{GDBN} displays the last value again (from the 5399@dfn{value history}; @pxref{Value History, ,Value History}). This allows you to 5400conveniently inspect the same value in an alternative format. 5401@end table 5402 5403A more low-level way of examining data is with the @code{x} command. 5404It examines data in memory at a specified address and prints it in a 5405specified format. @xref{Memory, ,Examining Memory}. 5406 5407If you are interested in information about types, or about how the 5408fields of a struct or a class are declared, use the @code{ptype @var{exp}} 5409command rather than @code{print}. @xref{Symbols, ,Examining the Symbol 5410Table}. 5411 5412@menu 5413* Expressions:: Expressions 5414* Variables:: Program variables 5415* Arrays:: Artificial arrays 5416* Output Formats:: Output formats 5417* Memory:: Examining memory 5418* Auto Display:: Automatic display 5419* Print Settings:: Print settings 5420* Value History:: Value history 5421* Convenience Vars:: Convenience variables 5422* Registers:: Registers 5423* Floating Point Hardware:: Floating point hardware 5424* Vector Unit:: Vector Unit 5425* OS Information:: Auxiliary data provided by operating system 5426* Memory Region Attributes:: Memory region attributes 5427* Dump/Restore Files:: Copy between memory and a file 5428* Core File Generation:: Cause a program dump its core 5429* Character Sets:: Debugging programs that use a different 5430 character set than GDB does 5431* Caching Remote Data:: Data caching for remote targets 5432@end menu 5433 5434@node Expressions 5435@section Expressions 5436 5437@cindex expressions 5438@code{print} and many other @value{GDBN} commands accept an expression and 5439compute its value. Any kind of constant, variable or operator defined 5440by the programming language you are using is valid in an expression in 5441@value{GDBN}. This includes conditional expressions, function calls, 5442casts, and string constants. It also includes preprocessor macros, if 5443you compiled your program to include this information; see 5444@ref{Compilation}. 5445 5446@cindex arrays in expressions 5447@value{GDBN} supports array constants in expressions input by 5448the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example, 5449you can use the command @code{print @{1, 2, 3@}} to build up an array in 5450memory that is @code{malloc}ed in the target program. 5451 5452Because C is so widespread, most of the expressions shown in examples in 5453this manual are in C. @xref{Languages, , Using @value{GDBN} with Different 5454Languages}, for information on how to use expressions in other 5455languages. 5456 5457In this section, we discuss operators that you can use in @value{GDBN} 5458expressions regardless of your programming language. 5459 5460@cindex casts, in expressions 5461Casts are supported in all languages, not just in C, because it is so 5462useful to cast a number into a pointer in order to examine a structure 5463at that address in memory. 5464@c FIXME: casts supported---Mod2 true? 5465 5466@value{GDBN} supports these operators, in addition to those common 5467to programming languages: 5468 5469@table @code 5470@item @@ 5471@samp{@@} is a binary operator for treating parts of memory as arrays. 5472@xref{Arrays, ,Artificial Arrays}, for more information. 5473 5474@item :: 5475@samp{::} allows you to specify a variable in terms of the file or 5476function where it is defined. @xref{Variables, ,Program Variables}. 5477 5478@cindex @{@var{type}@} 5479@cindex type casting memory 5480@cindex memory, viewing as typed object 5481@cindex casts, to view memory 5482@item @{@var{type}@} @var{addr} 5483Refers to an object of type @var{type} stored at address @var{addr} in 5484memory. @var{addr} may be any expression whose value is an integer or 5485pointer (but parentheses are required around binary operators, just as in 5486a cast). This construct is allowed regardless of what kind of data is 5487normally supposed to reside at @var{addr}. 5488@end table 5489 5490@node Variables 5491@section Program Variables 5492 5493The most common kind of expression to use is the name of a variable 5494in your program. 5495 5496Variables in expressions are understood in the selected stack frame 5497(@pxref{Selection, ,Selecting a Frame}); they must be either: 5498 5499@itemize @bullet 5500@item 5501global (or file-static) 5502@end itemize 5503 5504@noindent or 5505 5506@itemize @bullet 5507@item 5508visible according to the scope rules of the 5509programming language from the point of execution in that frame 5510@end itemize 5511 5512@noindent This means that in the function 5513 5514@smallexample 5515foo (a) 5516 int a; 5517@{ 5518 bar (a); 5519 @{ 5520 int b = test (); 5521 bar (b); 5522 @} 5523@} 5524@end smallexample 5525 5526@noindent 5527you can examine and use the variable @code{a} whenever your program is 5528executing within the function @code{foo}, but you can only use or 5529examine the variable @code{b} while your program is executing inside 5530the block where @code{b} is declared. 5531 5532@cindex variable name conflict 5533There is an exception: you can refer to a variable or function whose 5534scope is a single source file even if the current execution point is not 5535in this file. But it is possible to have more than one such variable or 5536function with the same name (in different source files). If that 5537happens, referring to that name has unpredictable effects. If you wish, 5538you can specify a static variable in a particular function or file, 5539using the colon-colon (@code{::}) notation: 5540 5541@cindex colon-colon, context for variables/functions 5542@ifnotinfo 5543@c info cannot cope with a :: index entry, but why deprive hard copy readers? 5544@cindex @code{::}, context for variables/functions 5545@end ifnotinfo 5546@smallexample 5547@var{file}::@var{variable} 5548@var{function}::@var{variable} 5549@end smallexample 5550 5551@noindent 5552Here @var{file} or @var{function} is the name of the context for the 5553static @var{variable}. In the case of file names, you can use quotes to 5554make sure @value{GDBN} parses the file name as a single word---for example, 5555to print a global value of @code{x} defined in @file{f2.c}: 5556 5557@smallexample 5558(@value{GDBP}) p 'f2.c'::x 5559@end smallexample 5560 5561@cindex C@t{++} scope resolution 5562This use of @samp{::} is very rarely in conflict with the very similar 5563use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++} 5564scope resolution operator in @value{GDBN} expressions. 5565@c FIXME: Um, so what happens in one of those rare cases where it's in 5566@c conflict?? --mew 5567 5568@cindex wrong values 5569@cindex variable values, wrong 5570@cindex function entry/exit, wrong values of variables 5571@cindex optimized code, wrong values of variables 5572@quotation 5573@emph{Warning:} Occasionally, a local variable may appear to have the 5574wrong value at certain points in a function---just after entry to a new 5575scope, and just before exit. 5576@end quotation 5577You may see this problem when you are stepping by machine instructions. 5578This is because, on most machines, it takes more than one instruction to 5579set up a stack frame (including local variable definitions); if you are 5580stepping by machine instructions, variables may appear to have the wrong 5581values until the stack frame is completely built. On exit, it usually 5582also takes more than one machine instruction to destroy a stack frame; 5583after you begin stepping through that group of instructions, local 5584variable definitions may be gone. 5585 5586This may also happen when the compiler does significant optimizations. 5587To be sure of always seeing accurate values, turn off all optimization 5588when compiling. 5589 5590@cindex ``No symbol "foo" in current context'' 5591Another possible effect of compiler optimizations is to optimize 5592unused variables out of existence, or assign variables to registers (as 5593opposed to memory addresses). Depending on the support for such cases 5594offered by the debug info format used by the compiler, @value{GDBN} 5595might not be able to display values for such local variables. If that 5596happens, @value{GDBN} will print a message like this: 5597 5598@smallexample 5599No symbol "foo" in current context. 5600@end smallexample 5601 5602To solve such problems, either recompile without optimizations, or use a 5603different debug info format, if the compiler supports several such 5604formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler, 5605usually supports the @option{-gstabs+} option. @option{-gstabs+} 5606produces debug info in a format that is superior to formats such as 5607COFF. You may be able to use DWARF 2 (@option{-gdwarf-2}), which is also 5608an effective form for debug info. @xref{Debugging Options,,Options 5609for Debugging Your Program or GCC, gcc.info, Using the @sc{gnu} 5610Compiler Collection (GCC)}. 5611@xref{C, ,C and C@t{++}}, for more information about debug info formats 5612that are best suited to C@t{++} programs. 5613 5614If you ask to print an object whose contents are unknown to 5615@value{GDBN}, e.g., because its data type is not completely specified 5616by the debug information, @value{GDBN} will say @samp{<incomplete 5617type>}. @xref{Symbols, incomplete type}, for more about this. 5618 5619Strings are identified as arrays of @code{char} values without specified 5620signedness. Arrays of either @code{signed char} or @code{unsigned char} get 5621printed as arrays of 1 byte sized integers. @code{-fsigned-char} or 5622@code{-funsigned-char} @value{NGCC} options have no effect as @value{GDBN} 5623defines literal string type @code{"char"} as @code{char} without a sign. 5624For program code 5625 5626@smallexample 5627char var0[] = "A"; 5628signed char var1[] = "A"; 5629@end smallexample 5630 5631You get during debugging 5632@smallexample 5633(gdb) print var0 5634$1 = "A" 5635(gdb) print var1 5636$2 = @{65 'A', 0 '\0'@} 5637@end smallexample 5638 5639@node Arrays 5640@section Artificial Arrays 5641 5642@cindex artificial array 5643@cindex arrays 5644@kindex @@@r{, referencing memory as an array} 5645It is often useful to print out several successive objects of the 5646same type in memory; a section of an array, or an array of 5647dynamically determined size for which only a pointer exists in the 5648program. 5649 5650You can do this by referring to a contiguous span of memory as an 5651@dfn{artificial array}, using the binary operator @samp{@@}. The left 5652operand of @samp{@@} should be the first element of the desired array 5653and be an individual object. The right operand should be the desired length 5654of the array. The result is an array value whose elements are all of 5655the type of the left argument. The first element is actually the left 5656argument; the second element comes from bytes of memory immediately 5657following those that hold the first element, and so on. Here is an 5658example. If a program says 5659 5660@smallexample 5661int *array = (int *) malloc (len * sizeof (int)); 5662@end smallexample 5663 5664@noindent 5665you can print the contents of @code{array} with 5666 5667@smallexample 5668p *array@@len 5669@end smallexample 5670 5671The left operand of @samp{@@} must reside in memory. Array values made 5672with @samp{@@} in this way behave just like other arrays in terms of 5673subscripting, and are coerced to pointers when used in expressions. 5674Artificial arrays most often appear in expressions via the value history 5675(@pxref{Value History, ,Value History}), after printing one out. 5676 5677Another way to create an artificial array is to use a cast. 5678This re-interprets a value as if it were an array. 5679The value need not be in memory: 5680@smallexample 5681(@value{GDBP}) p/x (short[2])0x12345678 5682$1 = @{0x1234, 0x5678@} 5683@end smallexample 5684 5685As a convenience, if you leave the array length out (as in 5686@samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill 5687the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}: 5688@smallexample 5689(@value{GDBP}) p/x (short[])0x12345678 5690$2 = @{0x1234, 0x5678@} 5691@end smallexample 5692 5693Sometimes the artificial array mechanism is not quite enough; in 5694moderately complex data structures, the elements of interest may not 5695actually be adjacent---for example, if you are interested in the values 5696of pointers in an array. One useful work-around in this situation is 5697to use a convenience variable (@pxref{Convenience Vars, ,Convenience 5698Variables}) as a counter in an expression that prints the first 5699interesting value, and then repeat that expression via @key{RET}. For 5700instance, suppose you have an array @code{dtab} of pointers to 5701structures, and you are interested in the values of a field @code{fv} 5702in each structure. Here is an example of what you might type: 5703 5704@smallexample 5705set $i = 0 5706p dtab[$i++]->fv 5707@key{RET} 5708@key{RET} 5709@dots{} 5710@end smallexample 5711 5712@node Output Formats 5713@section Output Formats 5714 5715@cindex formatted output 5716@cindex output formats 5717By default, @value{GDBN} prints a value according to its data type. Sometimes 5718this is not what you want. For example, you might want to print a number 5719in hex, or a pointer in decimal. Or you might want to view data in memory 5720at a certain address as a character string or as an instruction. To do 5721these things, specify an @dfn{output format} when you print a value. 5722 5723The simplest use of output formats is to say how to print a value 5724already computed. This is done by starting the arguments of the 5725@code{print} command with a slash and a format letter. The format 5726letters supported are: 5727 5728@table @code 5729@item x 5730Regard the bits of the value as an integer, and print the integer in 5731hexadecimal. 5732 5733@item d 5734Print as integer in signed decimal. 5735 5736@item u 5737Print as integer in unsigned decimal. 5738 5739@item o 5740Print as integer in octal. 5741 5742@item t 5743Print as integer in binary. The letter @samp{t} stands for ``two''. 5744@footnote{@samp{b} cannot be used because these format letters are also 5745used with the @code{x} command, where @samp{b} stands for ``byte''; 5746see @ref{Memory,,Examining Memory}.} 5747 5748@item a 5749@cindex unknown address, locating 5750@cindex locate address 5751Print as an address, both absolute in hexadecimal and as an offset from 5752the nearest preceding symbol. You can use this format used to discover 5753where (in what function) an unknown address is located: 5754 5755@smallexample 5756(@value{GDBP}) p/a 0x54320 5757$3 = 0x54320 <_initialize_vx+396> 5758@end smallexample 5759 5760@noindent 5761The command @code{info symbol 0x54320} yields similar results. 5762@xref{Symbols, info symbol}. 5763 5764@item c 5765Regard as an integer and print it as a character constant. This 5766prints both the numerical value and its character representation. The 5767character representation is replaced with the octal escape @samp{\nnn} 5768for characters outside the 7-bit @sc{ascii} range. 5769 5770Without this format, @value{GDBN} displays @code{char}, 5771@w{@code{unsigned char}}, and @w{@code{signed char}} data as character 5772constants. Single-byte members of vectors are displayed as integer 5773data. 5774 5775@item f 5776Regard the bits of the value as a floating point number and print 5777using typical floating point syntax. 5778 5779@item s 5780@cindex printing strings 5781@cindex printing byte arrays 5782Regard as a string, if possible. With this format, pointers to single-byte 5783data are displayed as null-terminated strings and arrays of single-byte data 5784are displayed as fixed-length strings. Other values are displayed in their 5785natural types. 5786 5787Without this format, @value{GDBN} displays pointers to and arrays of 5788@code{char}, @w{@code{unsigned char}}, and @w{@code{signed char}} as 5789strings. Single-byte members of a vector are displayed as an integer 5790array. 5791@end table 5792 5793For example, to print the program counter in hex (@pxref{Registers}), type 5794 5795@smallexample 5796p/x $pc 5797@end smallexample 5798 5799@noindent 5800Note that no space is required before the slash; this is because command 5801names in @value{GDBN} cannot contain a slash. 5802 5803To reprint the last value in the value history with a different format, 5804you can use the @code{print} command with just a format and no 5805expression. For example, @samp{p/x} reprints the last value in hex. 5806 5807@node Memory 5808@section Examining Memory 5809 5810You can use the command @code{x} (for ``examine'') to examine memory in 5811any of several formats, independently of your program's data types. 5812 5813@cindex examining memory 5814@table @code 5815@kindex x @r{(examine memory)} 5816@item x/@var{nfu} @var{addr} 5817@itemx x @var{addr} 5818@itemx x 5819Use the @code{x} command to examine memory. 5820@end table 5821 5822@var{n}, @var{f}, and @var{u} are all optional parameters that specify how 5823much memory to display and how to format it; @var{addr} is an 5824expression giving the address where you want to start displaying memory. 5825If you use defaults for @var{nfu}, you need not type the slash @samp{/}. 5826Several commands set convenient defaults for @var{addr}. 5827 5828@table @r 5829@item @var{n}, the repeat count 5830The repeat count is a decimal integer; the default is 1. It specifies 5831how much memory (counting by units @var{u}) to display. 5832@c This really is **decimal**; unaffected by 'set radix' as of GDB 5833@c 4.1.2. 5834 5835@item @var{f}, the display format 5836The display format is one of the formats used by @code{print} 5837(@samp{x}, @samp{d}, @samp{u}, @samp{o}, @samp{t}, @samp{a}, @samp{c}, 5838@samp{f}, @samp{s}), and in addition @samp{i} (for machine instructions). 5839The default is @samp{x} (hexadecimal) initially. The default changes 5840each time you use either @code{x} or @code{print}. 5841 5842@item @var{u}, the unit size 5843The unit size is any of 5844 5845@table @code 5846@item b 5847Bytes. 5848@item h 5849Halfwords (two bytes). 5850@item w 5851Words (four bytes). This is the initial default. 5852@item g 5853Giant words (eight bytes). 5854@end table 5855 5856Each time you specify a unit size with @code{x}, that size becomes the 5857default unit the next time you use @code{x}. (For the @samp{s} and 5858@samp{i} formats, the unit size is ignored and is normally not written.) 5859 5860@item @var{addr}, starting display address 5861@var{addr} is the address where you want @value{GDBN} to begin displaying 5862memory. The expression need not have a pointer value (though it may); 5863it is always interpreted as an integer address of a byte of memory. 5864@xref{Expressions, ,Expressions}, for more information on expressions. The default for 5865@var{addr} is usually just after the last address examined---but several 5866other commands also set the default address: @code{info breakpoints} (to 5867the address of the last breakpoint listed), @code{info line} (to the 5868starting address of a line), and @code{print} (if you use it to display 5869a value from memory). 5870@end table 5871 5872For example, @samp{x/3uh 0x54320} is a request to display three halfwords 5873(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}), 5874starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four 5875words (@samp{w}) of memory above the stack pointer (here, @samp{$sp}; 5876@pxref{Registers, ,Registers}) in hexadecimal (@samp{x}). 5877 5878Since the letters indicating unit sizes are all distinct from the 5879letters specifying output formats, you do not have to remember whether 5880unit size or format comes first; either order works. The output 5881specifications @samp{4xw} and @samp{4wx} mean exactly the same thing. 5882(However, the count @var{n} must come first; @samp{wx4} does not work.) 5883 5884Even though the unit size @var{u} is ignored for the formats @samp{s} 5885and @samp{i}, you might still want to use a count @var{n}; for example, 5886@samp{3i} specifies that you want to see three machine instructions, 5887including any operands. For convenience, especially when used with 5888the @code{display} command, the @samp{i} format also prints branch delay 5889slot instructions, if any, beyond the count specified, which immediately 5890follow the last instruction that is within the count. The command 5891@code{disassemble} gives an alternative way of inspecting machine 5892instructions; see @ref{Machine Code,,Source and Machine Code}. 5893 5894All the defaults for the arguments to @code{x} are designed to make it 5895easy to continue scanning memory with minimal specifications each time 5896you use @code{x}. For example, after you have inspected three machine 5897instructions with @samp{x/3i @var{addr}}, you can inspect the next seven 5898with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command, 5899the repeat count @var{n} is used again; the other arguments default as 5900for successive uses of @code{x}. 5901 5902@cindex @code{$_}, @code{$__}, and value history 5903The addresses and contents printed by the @code{x} command are not saved 5904in the value history because there is often too much of them and they 5905would get in the way. Instead, @value{GDBN} makes these values available for 5906subsequent use in expressions as values of the convenience variables 5907@code{$_} and @code{$__}. After an @code{x} command, the last address 5908examined is available for use in expressions in the convenience variable 5909@code{$_}. The contents of that address, as examined, are available in 5910the convenience variable @code{$__}. 5911 5912If the @code{x} command has a repeat count, the address and contents saved 5913are from the last memory unit printed; this is not the same as the last 5914address printed if several units were printed on the last line of output. 5915 5916@cindex remote memory comparison 5917@cindex verify remote memory image 5918When you are debugging a program running on a remote target machine 5919(@pxref{Remote Debugging}), you may wish to verify the program's image in the 5920remote machine's memory against the executable file you downloaded to 5921the target. The @code{compare-sections} command is provided for such 5922situations. 5923 5924@table @code 5925@kindex compare-sections 5926@item compare-sections @r{[}@var{section-name}@r{]} 5927Compare the data of a loadable section @var{section-name} in the 5928executable file of the program being debugged with the same section in 5929the remote machine's memory, and report any mismatches. With no 5930arguments, compares all loadable sections. This command's 5931availability depends on the target's support for the @code{"qCRC"} 5932remote request. 5933@end table 5934 5935@node Auto Display 5936@section Automatic Display 5937@cindex automatic display 5938@cindex display of expressions 5939 5940If you find that you want to print the value of an expression frequently 5941(to see how it changes), you might want to add it to the @dfn{automatic 5942display list} so that @value{GDBN} prints its value each time your program stops. 5943Each expression added to the list is given a number to identify it; 5944to remove an expression from the list, you specify that number. 5945The automatic display looks like this: 5946 5947@smallexample 59482: foo = 38 59493: bar[5] = (struct hack *) 0x3804 5950@end smallexample 5951 5952@noindent 5953This display shows item numbers, expressions and their current values. As with 5954displays you request manually using @code{x} or @code{print}, you can 5955specify the output format you prefer; in fact, @code{display} decides 5956whether to use @code{print} or @code{x} depending your format 5957specification---it uses @code{x} if you specify either the @samp{i} 5958or @samp{s} format, or a unit size; otherwise it uses @code{print}. 5959 5960@table @code 5961@kindex display 5962@item display @var{expr} 5963Add the expression @var{expr} to the list of expressions to display 5964each time your program stops. @xref{Expressions, ,Expressions}. 5965 5966@code{display} does not repeat if you press @key{RET} again after using it. 5967 5968@item display/@var{fmt} @var{expr} 5969For @var{fmt} specifying only a display format and not a size or 5970count, add the expression @var{expr} to the auto-display list but 5971arrange to display it each time in the specified format @var{fmt}. 5972@xref{Output Formats,,Output Formats}. 5973 5974@item display/@var{fmt} @var{addr} 5975For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a 5976number of units, add the expression @var{addr} as a memory address to 5977be examined each time your program stops. Examining means in effect 5978doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining Memory}. 5979@end table 5980 5981For example, @samp{display/i $pc} can be helpful, to see the machine 5982instruction about to be executed each time execution stops (@samp{$pc} 5983is a common name for the program counter; @pxref{Registers, ,Registers}). 5984 5985@table @code 5986@kindex delete display 5987@kindex undisplay 5988@item undisplay @var{dnums}@dots{} 5989@itemx delete display @var{dnums}@dots{} 5990Remove item numbers @var{dnums} from the list of expressions to display. 5991 5992@code{undisplay} does not repeat if you press @key{RET} after using it. 5993(Otherwise you would just get the error @samp{No display number @dots{}}.) 5994 5995@kindex disable display 5996@item disable display @var{dnums}@dots{} 5997Disable the display of item numbers @var{dnums}. A disabled display 5998item is not printed automatically, but is not forgotten. It may be 5999enabled again later. 6000 6001@kindex enable display 6002@item enable display @var{dnums}@dots{} 6003Enable display of item numbers @var{dnums}. It becomes effective once 6004again in auto display of its expression, until you specify otherwise. 6005 6006@item display 6007Display the current values of the expressions on the list, just as is 6008done when your program stops. 6009 6010@kindex info display 6011@item info display 6012Print the list of expressions previously set up to display 6013automatically, each one with its item number, but without showing the 6014values. This includes disabled expressions, which are marked as such. 6015It also includes expressions which would not be displayed right now 6016because they refer to automatic variables not currently available. 6017@end table 6018 6019@cindex display disabled out of scope 6020If a display expression refers to local variables, then it does not make 6021sense outside the lexical context for which it was set up. Such an 6022expression is disabled when execution enters a context where one of its 6023variables is not defined. For example, if you give the command 6024@code{display last_char} while inside a function with an argument 6025@code{last_char}, @value{GDBN} displays this argument while your program 6026continues to stop inside that function. When it stops elsewhere---where 6027there is no variable @code{last_char}---the display is disabled 6028automatically. The next time your program stops where @code{last_char} 6029is meaningful, you can enable the display expression once again. 6030 6031@node Print Settings 6032@section Print Settings 6033 6034@cindex format options 6035@cindex print settings 6036@value{GDBN} provides the following ways to control how arrays, structures, 6037and symbols are printed. 6038 6039@noindent 6040These settings are useful for debugging programs in any language: 6041 6042@table @code 6043@kindex set print 6044@item set print address 6045@itemx set print address on 6046@cindex print/don't print memory addresses 6047@value{GDBN} prints memory addresses showing the location of stack 6048traces, structure values, pointer values, breakpoints, and so forth, 6049even when it also displays the contents of those addresses. The default 6050is @code{on}. For example, this is what a stack frame display looks like with 6051@code{set print address on}: 6052 6053@smallexample 6054@group 6055(@value{GDBP}) f 6056#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") 6057 at input.c:530 6058530 if (lquote != def_lquote) 6059@end group 6060@end smallexample 6061 6062@item set print address off 6063Do not print addresses when displaying their contents. For example, 6064this is the same stack frame displayed with @code{set print address off}: 6065 6066@smallexample 6067@group 6068(@value{GDBP}) set print addr off 6069(@value{GDBP}) f 6070#0 set_quotes (lq="<<", rq=">>") at input.c:530 6071530 if (lquote != def_lquote) 6072@end group 6073@end smallexample 6074 6075You can use @samp{set print address off} to eliminate all machine 6076dependent displays from the @value{GDBN} interface. For example, with 6077@code{print address off}, you should get the same text for backtraces on 6078all machines---whether or not they involve pointer arguments. 6079 6080@kindex show print 6081@item show print address 6082Show whether or not addresses are to be printed. 6083@end table 6084 6085When @value{GDBN} prints a symbolic address, it normally prints the 6086closest earlier symbol plus an offset. If that symbol does not uniquely 6087identify the address (for example, it is a name whose scope is a single 6088source file), you may need to clarify. One way to do this is with 6089@code{info line}, for example @samp{info line *0x4537}. Alternately, 6090you can set @value{GDBN} to print the source file and line number when 6091it prints a symbolic address: 6092 6093@table @code 6094@item set print symbol-filename on 6095@cindex source file and line of a symbol 6096@cindex symbol, source file and line 6097Tell @value{GDBN} to print the source file name and line number of a 6098symbol in the symbolic form of an address. 6099 6100@item set print symbol-filename off 6101Do not print source file name and line number of a symbol. This is the 6102default. 6103 6104@item show print symbol-filename 6105Show whether or not @value{GDBN} will print the source file name and 6106line number of a symbol in the symbolic form of an address. 6107@end table 6108 6109Another situation where it is helpful to show symbol filenames and line 6110numbers is when disassembling code; @value{GDBN} shows you the line 6111number and source file that corresponds to each instruction. 6112 6113Also, you may wish to see the symbolic form only if the address being 6114printed is reasonably close to the closest earlier symbol: 6115 6116@table @code 6117@item set print max-symbolic-offset @var{max-offset} 6118@cindex maximum value for offset of closest symbol 6119Tell @value{GDBN} to only display the symbolic form of an address if the 6120offset between the closest earlier symbol and the address is less than 6121@var{max-offset}. The default is 0, which tells @value{GDBN} 6122to always print the symbolic form of an address if any symbol precedes it. 6123 6124@item show print max-symbolic-offset 6125Ask how large the maximum offset is that @value{GDBN} prints in a 6126symbolic address. 6127@end table 6128 6129@cindex wild pointer, interpreting 6130@cindex pointer, finding referent 6131If you have a pointer and you are not sure where it points, try 6132@samp{set print symbol-filename on}. Then you can determine the name 6133and source file location of the variable where it points, using 6134@samp{p/a @var{pointer}}. This interprets the address in symbolic form. 6135For example, here @value{GDBN} shows that a variable @code{ptt} points 6136at another variable @code{t}, defined in @file{hi2.c}: 6137 6138@smallexample 6139(@value{GDBP}) set print symbol-filename on 6140(@value{GDBP}) p/a ptt 6141$4 = 0xe008 <t in hi2.c> 6142@end smallexample 6143 6144@quotation 6145@emph{Warning:} For pointers that point to a local variable, @samp{p/a} 6146does not show the symbol name and filename of the referent, even with 6147the appropriate @code{set print} options turned on. 6148@end quotation 6149 6150Other settings control how different kinds of objects are printed: 6151 6152@table @code 6153@item set print array 6154@itemx set print array on 6155@cindex pretty print arrays 6156Pretty print arrays. This format is more convenient to read, 6157but uses more space. The default is off. 6158 6159@item set print array off 6160Return to compressed format for arrays. 6161 6162@item show print array 6163Show whether compressed or pretty format is selected for displaying 6164arrays. 6165 6166@cindex print array indexes 6167@item set print array-indexes 6168@itemx set print array-indexes on 6169Print the index of each element when displaying arrays. May be more 6170convenient to locate a given element in the array or quickly find the 6171index of a given element in that printed array. The default is off. 6172 6173@item set print array-indexes off 6174Stop printing element indexes when displaying arrays. 6175 6176@item show print array-indexes 6177Show whether the index of each element is printed when displaying 6178arrays. 6179 6180@item set print elements @var{number-of-elements} 6181@cindex number of array elements to print 6182@cindex limit on number of printed array elements 6183Set a limit on how many elements of an array @value{GDBN} will print. 6184If @value{GDBN} is printing a large array, it stops printing after it has 6185printed the number of elements set by the @code{set print elements} command. 6186This limit also applies to the display of strings. 6187When @value{GDBN} starts, this limit is set to 200. 6188Setting @var{number-of-elements} to zero means that the printing is unlimited. 6189 6190@item show print elements 6191Display the number of elements of a large array that @value{GDBN} will print. 6192If the number is 0, then the printing is unlimited. 6193 6194@item set print repeats 6195@cindex repeated array elements 6196Set the threshold for suppressing display of repeated array 6197elements. When the number of consecutive identical elements of an 6198array exceeds the threshold, @value{GDBN} prints the string 6199@code{"<repeats @var{n} times>"}, where @var{n} is the number of 6200identical repetitions, instead of displaying the identical elements 6201themselves. Setting the threshold to zero will cause all elements to 6202be individually printed. The default threshold is 10. 6203 6204@item show print repeats 6205Display the current threshold for printing repeated identical 6206elements. 6207 6208@item set print null-stop 6209@cindex @sc{null} elements in arrays 6210Cause @value{GDBN} to stop printing the characters of an array when the first 6211@sc{null} is encountered. This is useful when large arrays actually 6212contain only short strings. 6213The default is off. 6214 6215@item show print null-stop 6216Show whether @value{GDBN} stops printing an array on the first 6217@sc{null} character. 6218 6219@item set print pretty on 6220@cindex print structures in indented form 6221@cindex indentation in structure display 6222Cause @value{GDBN} to print structures in an indented format with one member 6223per line, like this: 6224 6225@smallexample 6226@group 6227$1 = @{ 6228 next = 0x0, 6229 flags = @{ 6230 sweet = 1, 6231 sour = 1 6232 @}, 6233 meat = 0x54 "Pork" 6234@} 6235@end group 6236@end smallexample 6237 6238@item set print pretty off 6239Cause @value{GDBN} to print structures in a compact format, like this: 6240 6241@smallexample 6242@group 6243$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \ 6244meat = 0x54 "Pork"@} 6245@end group 6246@end smallexample 6247 6248@noindent 6249This is the default format. 6250 6251@item show print pretty 6252Show which format @value{GDBN} is using to print structures. 6253 6254@item set print sevenbit-strings on 6255@cindex eight-bit characters in strings 6256@cindex octal escapes in strings 6257Print using only seven-bit characters; if this option is set, 6258@value{GDBN} displays any eight-bit characters (in strings or 6259character values) using the notation @code{\}@var{nnn}. This setting is 6260best if you are working in English (@sc{ascii}) and you use the 6261high-order bit of characters as a marker or ``meta'' bit. 6262 6263@item set print sevenbit-strings off 6264Print full eight-bit characters. This allows the use of more 6265international character sets, and is the default. 6266 6267@item show print sevenbit-strings 6268Show whether or not @value{GDBN} is printing only seven-bit characters. 6269 6270@item set print union on 6271@cindex unions in structures, printing 6272Tell @value{GDBN} to print unions which are contained in structures 6273and other unions. This is the default setting. 6274 6275@item set print union off 6276Tell @value{GDBN} not to print unions which are contained in 6277structures and other unions. @value{GDBN} will print @code{"@{...@}"} 6278instead. 6279 6280@item show print union 6281Ask @value{GDBN} whether or not it will print unions which are contained in 6282structures and other unions. 6283 6284For example, given the declarations 6285 6286@smallexample 6287typedef enum @{Tree, Bug@} Species; 6288typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms; 6289typedef enum @{Caterpillar, Cocoon, Butterfly@} 6290 Bug_forms; 6291 6292struct thing @{ 6293 Species it; 6294 union @{ 6295 Tree_forms tree; 6296 Bug_forms bug; 6297 @} form; 6298@}; 6299 6300struct thing foo = @{Tree, @{Acorn@}@}; 6301@end smallexample 6302 6303@noindent 6304with @code{set print union on} in effect @samp{p foo} would print 6305 6306@smallexample 6307$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@} 6308@end smallexample 6309 6310@noindent 6311and with @code{set print union off} in effect it would print 6312 6313@smallexample 6314$1 = @{it = Tree, form = @{...@}@} 6315@end smallexample 6316 6317@noindent 6318@code{set print union} affects programs written in C-like languages 6319and in Pascal. 6320@end table 6321 6322@need 1000 6323@noindent 6324These settings are of interest when debugging C@t{++} programs: 6325 6326@table @code 6327@cindex demangling C@t{++} names 6328@item set print demangle 6329@itemx set print demangle on 6330Print C@t{++} names in their source form rather than in the encoded 6331(``mangled'') form passed to the assembler and linker for type-safe 6332linkage. The default is on. 6333 6334@item show print demangle 6335Show whether C@t{++} names are printed in mangled or demangled form. 6336 6337@item set print asm-demangle 6338@itemx set print asm-demangle on 6339Print C@t{++} names in their source form rather than their mangled form, even 6340in assembler code printouts such as instruction disassemblies. 6341The default is off. 6342 6343@item show print asm-demangle 6344Show whether C@t{++} names in assembly listings are printed in mangled 6345or demangled form. 6346 6347@cindex C@t{++} symbol decoding style 6348@cindex symbol decoding style, C@t{++} 6349@kindex set demangle-style 6350@item set demangle-style @var{style} 6351Choose among several encoding schemes used by different compilers to 6352represent C@t{++} names. The choices for @var{style} are currently: 6353 6354@table @code 6355@item auto 6356Allow @value{GDBN} to choose a decoding style by inspecting your program. 6357 6358@item gnu 6359Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm. 6360This is the default. 6361 6362@item hp 6363Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm. 6364 6365@item lucid 6366Decode based on the Lucid C@t{++} compiler (@code{lcc}) encoding algorithm. 6367 6368@item arm 6369Decode using the algorithm in the @cite{C@t{++} Annotated Reference Manual}. 6370@strong{Warning:} this setting alone is not sufficient to allow 6371debugging @code{cfront}-generated executables. @value{GDBN} would 6372require further enhancement to permit that. 6373 6374@end table 6375If you omit @var{style}, you will see a list of possible formats. 6376 6377@item show demangle-style 6378Display the encoding style currently in use for decoding C@t{++} symbols. 6379 6380@item set print object 6381@itemx set print object on 6382@cindex derived type of an object, printing 6383@cindex display derived types 6384When displaying a pointer to an object, identify the @emph{actual} 6385(derived) type of the object rather than the @emph{declared} type, using 6386the virtual function table. 6387 6388@item set print object off 6389Display only the declared type of objects, without reference to the 6390virtual function table. This is the default setting. 6391 6392@item show print object 6393Show whether actual, or declared, object types are displayed. 6394 6395@item set print static-members 6396@itemx set print static-members on 6397@cindex static members of C@t{++} objects 6398Print static members when displaying a C@t{++} object. The default is on. 6399 6400@item set print static-members off 6401Do not print static members when displaying a C@t{++} object. 6402 6403@item show print static-members 6404Show whether C@t{++} static members are printed or not. 6405 6406@item set print pascal_static-members 6407@itemx set print pascal_static-members on 6408@cindex static members of Pascal objects 6409@cindex Pascal objects, static members display 6410Print static members when displaying a Pascal object. The default is on. 6411 6412@item set print pascal_static-members off 6413Do not print static members when displaying a Pascal object. 6414 6415@item show print pascal_static-members 6416Show whether Pascal static members are printed or not. 6417 6418@c These don't work with HP ANSI C++ yet. 6419@item set print vtbl 6420@itemx set print vtbl on 6421@cindex pretty print C@t{++} virtual function tables 6422@cindex virtual functions (C@t{++}) display 6423@cindex VTBL display 6424Pretty print C@t{++} virtual function tables. The default is off. 6425(The @code{vtbl} commands do not work on programs compiled with the HP 6426ANSI C@t{++} compiler (@code{aCC}).) 6427 6428@item set print vtbl off 6429Do not pretty print C@t{++} virtual function tables. 6430 6431@item show print vtbl 6432Show whether C@t{++} virtual function tables are pretty printed, or not. 6433@end table 6434 6435@node Value History 6436@section Value History 6437 6438@cindex value history 6439@cindex history of values printed by @value{GDBN} 6440Values printed by the @code{print} command are saved in the @value{GDBN} 6441@dfn{value history}. This allows you to refer to them in other expressions. 6442Values are kept until the symbol table is re-read or discarded 6443(for example with the @code{file} or @code{symbol-file} commands). 6444When the symbol table changes, the value history is discarded, 6445since the values may contain pointers back to the types defined in the 6446symbol table. 6447 6448@cindex @code{$} 6449@cindex @code{$$} 6450@cindex history number 6451The values printed are given @dfn{history numbers} by which you can 6452refer to them. These are successive integers starting with one. 6453@code{print} shows you the history number assigned to a value by 6454printing @samp{$@var{num} = } before the value; here @var{num} is the 6455history number. 6456 6457To refer to any previous value, use @samp{$} followed by the value's 6458history number. The way @code{print} labels its output is designed to 6459remind you of this. Just @code{$} refers to the most recent value in 6460the history, and @code{$$} refers to the value before that. 6461@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2} 6462is the value just prior to @code{$$}, @code{$$1} is equivalent to 6463@code{$$}, and @code{$$0} is equivalent to @code{$}. 6464 6465For example, suppose you have just printed a pointer to a structure and 6466want to see the contents of the structure. It suffices to type 6467 6468@smallexample 6469p *$ 6470@end smallexample 6471 6472If you have a chain of structures where the component @code{next} points 6473to the next one, you can print the contents of the next one with this: 6474 6475@smallexample 6476p *$.next 6477@end smallexample 6478 6479@noindent 6480You can print successive links in the chain by repeating this 6481command---which you can do by just typing @key{RET}. 6482 6483Note that the history records values, not expressions. If the value of 6484@code{x} is 4 and you type these commands: 6485 6486@smallexample 6487print x 6488set x=5 6489@end smallexample 6490 6491@noindent 6492then the value recorded in the value history by the @code{print} command 6493remains 4 even though the value of @code{x} has changed. 6494 6495@table @code 6496@kindex show values 6497@item show values 6498Print the last ten values in the value history, with their item numbers. 6499This is like @samp{p@ $$9} repeated ten times, except that @code{show 6500values} does not change the history. 6501 6502@item show values @var{n} 6503Print ten history values centered on history item number @var{n}. 6504 6505@item show values + 6506Print ten history values just after the values last printed. If no more 6507values are available, @code{show values +} produces no display. 6508@end table 6509 6510Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the 6511same effect as @samp{show values +}. 6512 6513@node Convenience Vars 6514@section Convenience Variables 6515 6516@cindex convenience variables 6517@cindex user-defined variables 6518@value{GDBN} provides @dfn{convenience variables} that you can use within 6519@value{GDBN} to hold on to a value and refer to it later. These variables 6520exist entirely within @value{GDBN}; they are not part of your program, and 6521setting a convenience variable has no direct effect on further execution 6522of your program. That is why you can use them freely. 6523 6524Convenience variables are prefixed with @samp{$}. Any name preceded by 6525@samp{$} can be used for a convenience variable, unless it is one of 6526the predefined machine-specific register names (@pxref{Registers, ,Registers}). 6527(Value history references, in contrast, are @emph{numbers} preceded 6528by @samp{$}. @xref{Value History, ,Value History}.) 6529 6530You can save a value in a convenience variable with an assignment 6531expression, just as you would set a variable in your program. 6532For example: 6533 6534@smallexample 6535set $foo = *object_ptr 6536@end smallexample 6537 6538@noindent 6539would save in @code{$foo} the value contained in the object pointed to by 6540@code{object_ptr}. 6541 6542Using a convenience variable for the first time creates it, but its 6543value is @code{void} until you assign a new value. You can alter the 6544value with another assignment at any time. 6545 6546Convenience variables have no fixed types. You can assign a convenience 6547variable any type of value, including structures and arrays, even if 6548that variable already has a value of a different type. The convenience 6549variable, when used as an expression, has the type of its current value. 6550 6551@table @code 6552@kindex show convenience 6553@cindex show all user variables 6554@item show convenience 6555Print a list of convenience variables used so far, and their values. 6556Abbreviated @code{show conv}. 6557 6558@kindex init-if-undefined 6559@cindex convenience variables, initializing 6560@item init-if-undefined $@var{variable} = @var{expression} 6561Set a convenience variable if it has not already been set. This is useful 6562for user-defined commands that keep some state. It is similar, in concept, 6563to using local static variables with initializers in C (except that 6564convenience variables are global). It can also be used to allow users to 6565override default values used in a command script. 6566 6567If the variable is already defined then the expression is not evaluated so 6568any side-effects do not occur. 6569@end table 6570 6571One of the ways to use a convenience variable is as a counter to be 6572incremented or a pointer to be advanced. For example, to print 6573a field from successive elements of an array of structures: 6574 6575@smallexample 6576set $i = 0 6577print bar[$i++]->contents 6578@end smallexample 6579 6580@noindent 6581Repeat that command by typing @key{RET}. 6582 6583Some convenience variables are created automatically by @value{GDBN} and given 6584values likely to be useful. 6585 6586@table @code 6587@vindex $_@r{, convenience variable} 6588@item $_ 6589The variable @code{$_} is automatically set by the @code{x} command to 6590the last address examined (@pxref{Memory, ,Examining Memory}). Other 6591commands which provide a default address for @code{x} to examine also 6592set @code{$_} to that address; these commands include @code{info line} 6593and @code{info breakpoint}. The type of @code{$_} is @code{void *} 6594except when set by the @code{x} command, in which case it is a pointer 6595to the type of @code{$__}. 6596 6597@vindex $__@r{, convenience variable} 6598@item $__ 6599The variable @code{$__} is automatically set by the @code{x} command 6600to the value found in the last address examined. Its type is chosen 6601to match the format in which the data was printed. 6602 6603@item $_exitcode 6604@vindex $_exitcode@r{, convenience variable} 6605The variable @code{$_exitcode} is automatically set to the exit code when 6606the program being debugged terminates. 6607@end table 6608 6609On HP-UX systems, if you refer to a function or variable name that 6610begins with a dollar sign, @value{GDBN} searches for a user or system 6611name first, before it searches for a convenience variable. 6612 6613@node Registers 6614@section Registers 6615 6616@cindex registers 6617You can refer to machine register contents, in expressions, as variables 6618with names starting with @samp{$}. The names of registers are different 6619for each machine; use @code{info registers} to see the names used on 6620your machine. 6621 6622@table @code 6623@kindex info registers 6624@item info registers 6625Print the names and values of all registers except floating-point 6626and vector registers (in the selected stack frame). 6627 6628@kindex info all-registers 6629@cindex floating point registers 6630@item info all-registers 6631Print the names and values of all registers, including floating-point 6632and vector registers (in the selected stack frame). 6633 6634@item info registers @var{regname} @dots{} 6635Print the @dfn{relativized} value of each specified register @var{regname}. 6636As discussed in detail below, register values are normally relative to 6637the selected stack frame. @var{regname} may be any register name valid on 6638the machine you are using, with or without the initial @samp{$}. 6639@end table 6640 6641@cindex stack pointer register 6642@cindex program counter register 6643@cindex process status register 6644@cindex frame pointer register 6645@cindex standard registers 6646@value{GDBN} has four ``standard'' register names that are available (in 6647expressions) on most machines---whenever they do not conflict with an 6648architecture's canonical mnemonics for registers. The register names 6649@code{$pc} and @code{$sp} are used for the program counter register and 6650the stack pointer. @code{$fp} is used for a register that contains a 6651pointer to the current stack frame, and @code{$ps} is used for a 6652register that contains the processor status. For example, 6653you could print the program counter in hex with 6654 6655@smallexample 6656p/x $pc 6657@end smallexample 6658 6659@noindent 6660or print the instruction to be executed next with 6661 6662@smallexample 6663x/i $pc 6664@end smallexample 6665 6666@noindent 6667or add four to the stack pointer@footnote{This is a way of removing 6668one word from the stack, on machines where stacks grow downward in 6669memory (most machines, nowadays). This assumes that the innermost 6670stack frame is selected; setting @code{$sp} is not allowed when other 6671stack frames are selected. To pop entire frames off the stack, 6672regardless of machine architecture, use @code{return}; 6673see @ref{Returning, ,Returning from a Function}.} with 6674 6675@smallexample 6676set $sp += 4 6677@end smallexample 6678 6679Whenever possible, these four standard register names are available on 6680your machine even though the machine has different canonical mnemonics, 6681so long as there is no conflict. The @code{info registers} command 6682shows the canonical names. For example, on the SPARC, @code{info 6683registers} displays the processor status register as @code{$psr} but you 6684can also refer to it as @code{$ps}; and on x86-based machines @code{$ps} 6685is an alias for the @sc{eflags} register. 6686 6687@value{GDBN} always considers the contents of an ordinary register as an 6688integer when the register is examined in this way. Some machines have 6689special registers which can hold nothing but floating point; these 6690registers are considered to have floating point values. There is no way 6691to refer to the contents of an ordinary register as floating point value 6692(although you can @emph{print} it as a floating point value with 6693@samp{print/f $@var{regname}}). 6694 6695Some registers have distinct ``raw'' and ``virtual'' data formats. This 6696means that the data format in which the register contents are saved by 6697the operating system is not the same one that your program normally 6698sees. For example, the registers of the 68881 floating point 6699coprocessor are always saved in ``extended'' (raw) format, but all C 6700programs expect to work with ``double'' (virtual) format. In such 6701cases, @value{GDBN} normally works with the virtual format only (the format 6702that makes sense for your program), but the @code{info registers} command 6703prints the data in both formats. 6704 6705@cindex SSE registers (x86) 6706@cindex MMX registers (x86) 6707Some machines have special registers whose contents can be interpreted 6708in several different ways. For example, modern x86-based machines 6709have SSE and MMX registers that can hold several values packed 6710together in several different formats. @value{GDBN} refers to such 6711registers in @code{struct} notation: 6712 6713@smallexample 6714(@value{GDBP}) print $xmm1 6715$1 = @{ 6716 v4_float = @{0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044@}, 6717 v2_double = @{9.92129282474342e-303, 2.7585945287983262e-313@}, 6718 v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000", 6719 v8_int16 = @{0, 0, 14072, 315, 11, 0, 13, 0@}, 6720 v4_int32 = @{0, 20657912, 11, 13@}, 6721 v2_int64 = @{88725056443645952, 55834574859@}, 6722 uint128 = 0x0000000d0000000b013b36f800000000 6723@} 6724@end smallexample 6725 6726@noindent 6727To set values of such registers, you need to tell @value{GDBN} which 6728view of the register you wish to change, as if you were assigning 6729value to a @code{struct} member: 6730 6731@smallexample 6732 (@value{GDBP}) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF 6733@end smallexample 6734 6735Normally, register values are relative to the selected stack frame 6736(@pxref{Selection, ,Selecting a Frame}). This means that you get the 6737value that the register would contain if all stack frames farther in 6738were exited and their saved registers restored. In order to see the 6739true contents of hardware registers, you must select the innermost 6740frame (with @samp{frame 0}). 6741 6742However, @value{GDBN} must deduce where registers are saved, from the machine 6743code generated by your compiler. If some registers are not saved, or if 6744@value{GDBN} is unable to locate the saved registers, the selected stack 6745frame makes no difference. 6746 6747@node Floating Point Hardware 6748@section Floating Point Hardware 6749@cindex floating point 6750 6751Depending on the configuration, @value{GDBN} may be able to give 6752you more information about the status of the floating point hardware. 6753 6754@table @code 6755@kindex info float 6756@item info float 6757Display hardware-dependent information about the floating 6758point unit. The exact contents and layout vary depending on the 6759floating point chip. Currently, @samp{info float} is supported on 6760the ARM and x86 machines. 6761@end table 6762 6763@node Vector Unit 6764@section Vector Unit 6765@cindex vector unit 6766 6767Depending on the configuration, @value{GDBN} may be able to give you 6768more information about the status of the vector unit. 6769 6770@table @code 6771@kindex info vector 6772@item info vector 6773Display information about the vector unit. The exact contents and 6774layout vary depending on the hardware. 6775@end table 6776 6777@node OS Information 6778@section Operating System Auxiliary Information 6779@cindex OS information 6780 6781@value{GDBN} provides interfaces to useful OS facilities that can help 6782you debug your program. 6783 6784@cindex @code{ptrace} system call 6785@cindex @code{struct user} contents 6786When @value{GDBN} runs on a @dfn{Posix system} (such as GNU or Unix 6787machines), it interfaces with the inferior via the @code{ptrace} 6788system call. The operating system creates a special sata structure, 6789called @code{struct user}, for this interface. You can use the 6790command @code{info udot} to display the contents of this data 6791structure. 6792 6793@table @code 6794@item info udot 6795@kindex info udot 6796Display the contents of the @code{struct user} maintained by the OS 6797kernel for the program being debugged. @value{GDBN} displays the 6798contents of @code{struct user} as a list of hex numbers, similar to 6799the @code{examine} command. 6800@end table 6801 6802@cindex auxiliary vector 6803@cindex vector, auxiliary 6804Some operating systems supply an @dfn{auxiliary vector} to programs at 6805startup. This is akin to the arguments and environment that you 6806specify for a program, but contains a system-dependent variety of 6807binary values that tell system libraries important details about the 6808hardware, operating system, and process. Each value's purpose is 6809identified by an integer tag; the meanings are well-known but system-specific. 6810Depending on the configuration and operating system facilities, 6811@value{GDBN} may be able to show you this information. For remote 6812targets, this functionality may further depend on the remote stub's 6813support of the @samp{qXfer:auxv:read} packet, see 6814@ref{qXfer auxiliary vector read}. 6815 6816@table @code 6817@kindex info auxv 6818@item info auxv 6819Display the auxiliary vector of the inferior, which can be either a 6820live process or a core dump file. @value{GDBN} prints each tag value 6821numerically, and also shows names and text descriptions for recognized 6822tags. Some values in the vector are numbers, some bit masks, and some 6823pointers to strings or other data. @value{GDBN} displays each value in the 6824most appropriate form for a recognized tag, and in hexadecimal for 6825an unrecognized tag. 6826@end table 6827 6828 6829@node Memory Region Attributes 6830@section Memory Region Attributes 6831@cindex memory region attributes 6832 6833@dfn{Memory region attributes} allow you to describe special handling 6834required by regions of your target's memory. @value{GDBN} uses 6835attributes to determine whether to allow certain types of memory 6836accesses; whether to use specific width accesses; and whether to cache 6837target memory. By default the description of memory regions is 6838fetched from the target (if the current target supports this), but the 6839user can override the fetched regions. 6840 6841Defined memory regions can be individually enabled and disabled. When a 6842memory region is disabled, @value{GDBN} uses the default attributes when 6843accessing memory in that region. Similarly, if no memory regions have 6844been defined, @value{GDBN} uses the default attributes when accessing 6845all memory. 6846 6847When a memory region is defined, it is given a number to identify it; 6848to enable, disable, or remove a memory region, you specify that number. 6849 6850@table @code 6851@kindex mem 6852@item mem @var{lower} @var{upper} @var{attributes}@dots{} 6853Define a memory region bounded by @var{lower} and @var{upper} with 6854attributes @var{attributes}@dots{}, and add it to the list of regions 6855monitored by @value{GDBN}. Note that @var{upper} == 0 is a special 6856case: it is treated as the target's maximum memory address. 6857(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.) 6858 6859@item mem auto 6860Discard any user changes to the memory regions and use target-supplied 6861regions, if available, or no regions if the target does not support. 6862 6863@kindex delete mem 6864@item delete mem @var{nums}@dots{} 6865Remove memory regions @var{nums}@dots{} from the list of regions 6866monitored by @value{GDBN}. 6867 6868@kindex disable mem 6869@item disable mem @var{nums}@dots{} 6870Disable monitoring of memory regions @var{nums}@dots{}. 6871A disabled memory region is not forgotten. 6872It may be enabled again later. 6873 6874@kindex enable mem 6875@item enable mem @var{nums}@dots{} 6876Enable monitoring of memory regions @var{nums}@dots{}. 6877 6878@kindex info mem 6879@item info mem 6880Print a table of all defined memory regions, with the following columns 6881for each region: 6882 6883@table @emph 6884@item Memory Region Number 6885@item Enabled or Disabled. 6886Enabled memory regions are marked with @samp{y}. 6887Disabled memory regions are marked with @samp{n}. 6888 6889@item Lo Address 6890The address defining the inclusive lower bound of the memory region. 6891 6892@item Hi Address 6893The address defining the exclusive upper bound of the memory region. 6894 6895@item Attributes 6896The list of attributes set for this memory region. 6897@end table 6898@end table 6899 6900 6901@subsection Attributes 6902 6903@subsubsection Memory Access Mode 6904The access mode attributes set whether @value{GDBN} may make read or 6905write accesses to a memory region. 6906 6907While these attributes prevent @value{GDBN} from performing invalid 6908memory accesses, they do nothing to prevent the target system, I/O DMA, 6909etc.@: from accessing memory. 6910 6911@table @code 6912@item ro 6913Memory is read only. 6914@item wo 6915Memory is write only. 6916@item rw 6917Memory is read/write. This is the default. 6918@end table 6919 6920@subsubsection Memory Access Size 6921The access size attribute tells @value{GDBN} to use specific sized 6922accesses in the memory region. Often memory mapped device registers 6923require specific sized accesses. If no access size attribute is 6924specified, @value{GDBN} may use accesses of any size. 6925 6926@table @code 6927@item 8 6928Use 8 bit memory accesses. 6929@item 16 6930Use 16 bit memory accesses. 6931@item 32 6932Use 32 bit memory accesses. 6933@item 64 6934Use 64 bit memory accesses. 6935@end table 6936 6937@c @subsubsection Hardware/Software Breakpoints 6938@c The hardware/software breakpoint attributes set whether @value{GDBN} 6939@c will use hardware or software breakpoints for the internal breakpoints 6940@c used by the step, next, finish, until, etc. commands. 6941@c 6942@c @table @code 6943@c @item hwbreak 6944@c Always use hardware breakpoints 6945@c @item swbreak (default) 6946@c @end table 6947 6948@subsubsection Data Cache 6949The data cache attributes set whether @value{GDBN} will cache target 6950memory. While this generally improves performance by reducing debug 6951protocol overhead, it can lead to incorrect results because @value{GDBN} 6952does not know about volatile variables or memory mapped device 6953registers. 6954 6955@table @code 6956@item cache 6957Enable @value{GDBN} to cache target memory. 6958@item nocache 6959Disable @value{GDBN} from caching target memory. This is the default. 6960@end table 6961 6962@subsection Memory Access Checking 6963@value{GDBN} can be instructed to refuse accesses to memory that is 6964not explicitly described. This can be useful if accessing such 6965regions has undesired effects for a specific target, or to provide 6966better error checking. The following commands control this behaviour. 6967 6968@table @code 6969@kindex set mem inaccessible-by-default 6970@item set mem inaccessible-by-default [on|off] 6971If @code{on} is specified, make @value{GDBN} treat memory not 6972explicitly described by the memory ranges as non-existent and refuse accesses 6973to such memory. The checks are only performed if there's at least one 6974memory range defined. If @code{off} is specified, make @value{GDBN} 6975treat the memory not explicitly described by the memory ranges as RAM. 6976The default value is @code{off}. 6977@kindex show mem inaccessible-by-default 6978@item show mem inaccessible-by-default 6979Show the current handling of accesses to unknown memory. 6980@end table 6981 6982 6983@c @subsubsection Memory Write Verification 6984@c The memory write verification attributes set whether @value{GDBN} 6985@c will re-reads data after each write to verify the write was successful. 6986@c 6987@c @table @code 6988@c @item verify 6989@c @item noverify (default) 6990@c @end table 6991 6992@node Dump/Restore Files 6993@section Copy Between Memory and a File 6994@cindex dump/restore files 6995@cindex append data to a file 6996@cindex dump data to a file 6997@cindex restore data from a file 6998 6999You can use the commands @code{dump}, @code{append}, and 7000@code{restore} to copy data between target memory and a file. The 7001@code{dump} and @code{append} commands write data to a file, and the 7002@code{restore} command reads data from a file back into the inferior's 7003memory. Files may be in binary, Motorola S-record, Intel hex, or 7004Tektronix Hex format; however, @value{GDBN} can only append to binary 7005files. 7006 7007@table @code 7008 7009@kindex dump 7010@item dump @r{[}@var{format}@r{]} memory @var{filename} @var{start_addr} @var{end_addr} 7011@itemx dump @r{[}@var{format}@r{]} value @var{filename} @var{expr} 7012Dump the contents of memory from @var{start_addr} to @var{end_addr}, 7013or the value of @var{expr}, to @var{filename} in the given format. 7014 7015The @var{format} parameter may be any one of: 7016@table @code 7017@item binary 7018Raw binary form. 7019@item ihex 7020Intel hex format. 7021@item srec 7022Motorola S-record format. 7023@item tekhex 7024Tektronix Hex format. 7025@end table 7026 7027@value{GDBN} uses the same definitions of these formats as the 7028@sc{gnu} binary utilities, like @samp{objdump} and @samp{objcopy}. If 7029@var{format} is omitted, @value{GDBN} dumps the data in raw binary 7030form. 7031 7032@kindex append 7033@item append @r{[}binary@r{]} memory @var{filename} @var{start_addr} @var{end_addr} 7034@itemx append @r{[}binary@r{]} value @var{filename} @var{expr} 7035Append the contents of memory from @var{start_addr} to @var{end_addr}, 7036or the value of @var{expr}, to the file @var{filename}, in raw binary form. 7037(@value{GDBN} can only append data to files in raw binary form.) 7038 7039@kindex restore 7040@item restore @var{filename} @r{[}binary@r{]} @var{bias} @var{start} @var{end} 7041Restore the contents of file @var{filename} into memory. The 7042@code{restore} command can automatically recognize any known @sc{bfd} 7043file format, except for raw binary. To restore a raw binary file you 7044must specify the optional keyword @code{binary} after the filename. 7045 7046If @var{bias} is non-zero, its value will be added to the addresses 7047contained in the file. Binary files always start at address zero, so 7048they will be restored at address @var{bias}. Other bfd files have 7049a built-in location; they will be restored at offset @var{bias} 7050from that location. 7051 7052If @var{start} and/or @var{end} are non-zero, then only data between 7053file offset @var{start} and file offset @var{end} will be restored. 7054These offsets are relative to the addresses in the file, before 7055the @var{bias} argument is applied. 7056 7057@end table 7058 7059@node Core File Generation 7060@section How to Produce a Core File from Your Program 7061@cindex dump core from inferior 7062 7063A @dfn{core file} or @dfn{core dump} is a file that records the memory 7064image of a running process and its process status (register values 7065etc.). Its primary use is post-mortem debugging of a program that 7066crashed while it ran outside a debugger. A program that crashes 7067automatically produces a core file, unless this feature is disabled by 7068the user. @xref{Files}, for information on invoking @value{GDBN} in 7069the post-mortem debugging mode. 7070 7071Occasionally, you may wish to produce a core file of the program you 7072are debugging in order to preserve a snapshot of its state. 7073@value{GDBN} has a special command for that. 7074 7075@table @code 7076@kindex gcore 7077@kindex generate-core-file 7078@item generate-core-file [@var{file}] 7079@itemx gcore [@var{file}] 7080Produce a core dump of the inferior process. The optional argument 7081@var{file} specifies the file name where to put the core dump. If not 7082specified, the file name defaults to @file{core.@var{pid}}, where 7083@var{pid} is the inferior process ID. 7084 7085Note that this command is implemented only for some systems (as of 7086this writing, @sc{gnu}/Linux, FreeBSD, Solaris, Unixware, and S390). 7087@end table 7088 7089@node Character Sets 7090@section Character Sets 7091@cindex character sets 7092@cindex charset 7093@cindex translating between character sets 7094@cindex host character set 7095@cindex target character set 7096 7097If the program you are debugging uses a different character set to 7098represent characters and strings than the one @value{GDBN} uses itself, 7099@value{GDBN} can automatically translate between the character sets for 7100you. The character set @value{GDBN} uses we call the @dfn{host 7101character set}; the one the inferior program uses we call the 7102@dfn{target character set}. 7103 7104For example, if you are running @value{GDBN} on a @sc{gnu}/Linux system, which 7105uses the ISO Latin 1 character set, but you are using @value{GDBN}'s 7106remote protocol (@pxref{Remote Debugging}) to debug a program 7107running on an IBM mainframe, which uses the @sc{ebcdic} character set, 7108then the host character set is Latin-1, and the target character set is 7109@sc{ebcdic}. If you give @value{GDBN} the command @code{set 7110target-charset EBCDIC-US}, then @value{GDBN} translates between 7111@sc{ebcdic} and Latin 1 as you print character or string values, or use 7112character and string literals in expressions. 7113 7114@value{GDBN} has no way to automatically recognize which character set 7115the inferior program uses; you must tell it, using the @code{set 7116target-charset} command, described below. 7117 7118Here are the commands for controlling @value{GDBN}'s character set 7119support: 7120 7121@table @code 7122@item set target-charset @var{charset} 7123@kindex set target-charset 7124Set the current target character set to @var{charset}. We list the 7125character set names @value{GDBN} recognizes below, but if you type 7126@code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} will 7127list the target character sets it supports. 7128@end table 7129 7130@table @code 7131@item set host-charset @var{charset} 7132@kindex set host-charset 7133Set the current host character set to @var{charset}. 7134 7135By default, @value{GDBN} uses a host character set appropriate to the 7136system it is running on; you can override that default using the 7137@code{set host-charset} command. 7138 7139@value{GDBN} can only use certain character sets as its host character 7140set. We list the character set names @value{GDBN} recognizes below, and 7141indicate which can be host character sets, but if you type 7142@code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} will 7143list the host character sets it supports. 7144 7145@item set charset @var{charset} 7146@kindex set charset 7147Set the current host and target character sets to @var{charset}. As 7148above, if you type @code{set charset} followed by @key{TAB}@key{TAB}, 7149@value{GDBN} will list the name of the character sets that can be used 7150for both host and target. 7151 7152 7153@item show charset 7154@kindex show charset 7155Show the names of the current host and target charsets. 7156 7157@itemx show host-charset 7158@kindex show host-charset 7159Show the name of the current host charset. 7160 7161@itemx show target-charset 7162@kindex show target-charset 7163Show the name of the current target charset. 7164 7165@end table 7166 7167@value{GDBN} currently includes support for the following character 7168sets: 7169 7170@table @code 7171 7172@item ASCII 7173@cindex ASCII character set 7174Seven-bit U.S. @sc{ascii}. @value{GDBN} can use this as its host 7175character set. 7176 7177@item ISO-8859-1 7178@cindex ISO 8859-1 character set 7179@cindex ISO Latin 1 character set 7180The ISO Latin 1 character set. This extends @sc{ascii} with accented 7181characters needed for French, German, and Spanish. @value{GDBN} can use 7182this as its host character set. 7183 7184@item EBCDIC-US 7185@itemx IBM1047 7186@cindex EBCDIC character set 7187@cindex IBM1047 character set 7188Variants of the @sc{ebcdic} character set, used on some of IBM's 7189mainframe operating systems. (@sc{gnu}/Linux on the S/390 uses U.S. @sc{ascii}.) 7190@value{GDBN} cannot use these as its host character set. 7191 7192@end table 7193 7194Note that these are all single-byte character sets. More work inside 7195@value{GDBN} is needed to support multi-byte or variable-width character 7196encodings, like the UTF-8 and UCS-2 encodings of Unicode. 7197 7198Here is an example of @value{GDBN}'s character set support in action. 7199Assume that the following source code has been placed in the file 7200@file{charset-test.c}: 7201 7202@smallexample 7203#include <stdio.h> 7204 7205char ascii_hello[] 7206 = @{72, 101, 108, 108, 111, 44, 32, 119, 7207 111, 114, 108, 100, 33, 10, 0@}; 7208char ibm1047_hello[] 7209 = @{200, 133, 147, 147, 150, 107, 64, 166, 7210 150, 153, 147, 132, 90, 37, 0@}; 7211 7212main () 7213@{ 7214 printf ("Hello, world!\n"); 7215@} 7216@end smallexample 7217 7218In this program, @code{ascii_hello} and @code{ibm1047_hello} are arrays 7219containing the string @samp{Hello, world!} followed by a newline, 7220encoded in the @sc{ascii} and @sc{ibm1047} character sets. 7221 7222We compile the program, and invoke the debugger on it: 7223 7224@smallexample 7225$ gcc -g charset-test.c -o charset-test 7226$ gdb -nw charset-test 7227GNU gdb 2001-12-19-cvs 7228Copyright 2001 Free Software Foundation, Inc. 7229@dots{} 7230(@value{GDBP}) 7231@end smallexample 7232 7233We can use the @code{show charset} command to see what character sets 7234@value{GDBN} is currently using to interpret and display characters and 7235strings: 7236 7237@smallexample 7238(@value{GDBP}) show charset 7239The current host and target character set is `ISO-8859-1'. 7240(@value{GDBP}) 7241@end smallexample 7242 7243For the sake of printing this manual, let's use @sc{ascii} as our 7244initial character set: 7245@smallexample 7246(@value{GDBP}) set charset ASCII 7247(@value{GDBP}) show charset 7248The current host and target character set is `ASCII'. 7249(@value{GDBP}) 7250@end smallexample 7251 7252Let's assume that @sc{ascii} is indeed the correct character set for our 7253host system --- in other words, let's assume that if @value{GDBN} prints 7254characters using the @sc{ascii} character set, our terminal will display 7255them properly. Since our current target character set is also 7256@sc{ascii}, the contents of @code{ascii_hello} print legibly: 7257 7258@smallexample 7259(@value{GDBP}) print ascii_hello 7260$1 = 0x401698 "Hello, world!\n" 7261(@value{GDBP}) print ascii_hello[0] 7262$2 = 72 'H' 7263(@value{GDBP}) 7264@end smallexample 7265 7266@value{GDBN} uses the target character set for character and string 7267literals you use in expressions: 7268 7269@smallexample 7270(@value{GDBP}) print '+' 7271$3 = 43 '+' 7272(@value{GDBP}) 7273@end smallexample 7274 7275The @sc{ascii} character set uses the number 43 to encode the @samp{+} 7276character. 7277 7278@value{GDBN} relies on the user to tell it which character set the 7279target program uses. If we print @code{ibm1047_hello} while our target 7280character set is still @sc{ascii}, we get jibberish: 7281 7282@smallexample 7283(@value{GDBP}) print ibm1047_hello 7284$4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%" 7285(@value{GDBP}) print ibm1047_hello[0] 7286$5 = 200 '\310' 7287(@value{GDBP}) 7288@end smallexample 7289 7290If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB}, 7291@value{GDBN} tells us the character sets it supports: 7292 7293@smallexample 7294(@value{GDBP}) set target-charset 7295ASCII EBCDIC-US IBM1047 ISO-8859-1 7296(@value{GDBP}) set target-charset 7297@end smallexample 7298 7299We can select @sc{ibm1047} as our target character set, and examine the 7300program's strings again. Now the @sc{ascii} string is wrong, but 7301@value{GDBN} translates the contents of @code{ibm1047_hello} from the 7302target character set, @sc{ibm1047}, to the host character set, 7303@sc{ascii}, and they display correctly: 7304 7305@smallexample 7306(@value{GDBP}) set target-charset IBM1047 7307(@value{GDBP}) show charset 7308The current host character set is `ASCII'. 7309The current target character set is `IBM1047'. 7310(@value{GDBP}) print ascii_hello 7311$6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" 7312(@value{GDBP}) print ascii_hello[0] 7313$7 = 72 '\110' 7314(@value{GDBP}) print ibm1047_hello 7315$8 = 0x4016a8 "Hello, world!\n" 7316(@value{GDBP}) print ibm1047_hello[0] 7317$9 = 200 'H' 7318(@value{GDBP}) 7319@end smallexample 7320 7321As above, @value{GDBN} uses the target character set for character and 7322string literals you use in expressions: 7323 7324@smallexample 7325(@value{GDBP}) print '+' 7326$10 = 78 '+' 7327(@value{GDBP}) 7328@end smallexample 7329 7330The @sc{ibm1047} character set uses the number 78 to encode the @samp{+} 7331character. 7332 7333@node Caching Remote Data 7334@section Caching Data of Remote Targets 7335@cindex caching data of remote targets 7336 7337@value{GDBN} can cache data exchanged between the debugger and a 7338remote target (@pxref{Remote Debugging}). Such caching generally improves 7339performance, because it reduces the overhead of the remote protocol by 7340bundling memory reads and writes into large chunks. Unfortunately, 7341@value{GDBN} does not currently know anything about volatile 7342registers, and thus data caching will produce incorrect results when 7343volatile registers are in use. 7344 7345@table @code 7346@kindex set remotecache 7347@item set remotecache on 7348@itemx set remotecache off 7349Set caching state for remote targets. When @code{ON}, use data 7350caching. By default, this option is @code{OFF}. 7351 7352@kindex show remotecache 7353@item show remotecache 7354Show the current state of data caching for remote targets. 7355 7356@kindex info dcache 7357@item info dcache 7358Print the information about the data cache performance. The 7359information displayed includes: the dcache width and depth; and for 7360each cache line, how many times it was referenced, and its data and 7361state (dirty, bad, ok, etc.). This command is useful for debugging 7362the data cache operation. 7363@end table 7364 7365 7366@node Macros 7367@chapter C Preprocessor Macros 7368 7369Some languages, such as C and C@t{++}, provide a way to define and invoke 7370``preprocessor macros'' which expand into strings of tokens. 7371@value{GDBN} can evaluate expressions containing macro invocations, show 7372the result of macro expansion, and show a macro's definition, including 7373where it was defined. 7374 7375You may need to compile your program specially to provide @value{GDBN} 7376with information about preprocessor macros. Most compilers do not 7377include macros in their debugging information, even when you compile 7378with the @option{-g} flag. @xref{Compilation}. 7379 7380A program may define a macro at one point, remove that definition later, 7381and then provide a different definition after that. Thus, at different 7382points in the program, a macro may have different definitions, or have 7383no definition at all. If there is a current stack frame, @value{GDBN} 7384uses the macros in scope at that frame's source code line. Otherwise, 7385@value{GDBN} uses the macros in scope at the current listing location; 7386see @ref{List}. 7387 7388At the moment, @value{GDBN} does not support the @code{##} 7389token-splicing operator, the @code{#} stringification operator, or 7390variable-arity macros. 7391 7392Whenever @value{GDBN} evaluates an expression, it always expands any 7393macro invocations present in the expression. @value{GDBN} also provides 7394the following commands for working with macros explicitly. 7395 7396@table @code 7397 7398@kindex macro expand 7399@cindex macro expansion, showing the results of preprocessor 7400@cindex preprocessor macro expansion, showing the results of 7401@cindex expanding preprocessor macros 7402@item macro expand @var{expression} 7403@itemx macro exp @var{expression} 7404Show the results of expanding all preprocessor macro invocations in 7405@var{expression}. Since @value{GDBN} simply expands macros, but does 7406not parse the result, @var{expression} need not be a valid expression; 7407it can be any string of tokens. 7408 7409@kindex macro exp1 7410@item macro expand-once @var{expression} 7411@itemx macro exp1 @var{expression} 7412@cindex expand macro once 7413@i{(This command is not yet implemented.)} Show the results of 7414expanding those preprocessor macro invocations that appear explicitly in 7415@var{expression}. Macro invocations appearing in that expansion are 7416left unchanged. This command allows you to see the effect of a 7417particular macro more clearly, without being confused by further 7418expansions. Since @value{GDBN} simply expands macros, but does not 7419parse the result, @var{expression} need not be a valid expression; it 7420can be any string of tokens. 7421 7422@kindex info macro 7423@cindex macro definition, showing 7424@cindex definition, showing a macro's 7425@item info macro @var{macro} 7426Show the definition of the macro named @var{macro}, and describe the 7427source location where that definition was established. 7428 7429@kindex macro define 7430@cindex user-defined macros 7431@cindex defining macros interactively 7432@cindex macros, user-defined 7433@item macro define @var{macro} @var{replacement-list} 7434@itemx macro define @var{macro}(@var{arglist}) @var{replacement-list} 7435@i{(This command is not yet implemented.)} Introduce a definition for a 7436preprocessor macro named @var{macro}, invocations of which are replaced 7437by the tokens given in @var{replacement-list}. The first form of this 7438command defines an ``object-like'' macro, which takes no arguments; the 7439second form defines a ``function-like'' macro, which takes the arguments 7440given in @var{arglist}. 7441 7442A definition introduced by this command is in scope in every expression 7443evaluated in @value{GDBN}, until it is removed with the @command{macro 7444undef} command, described below. The definition overrides all 7445definitions for @var{macro} present in the program being debugged, as 7446well as any previous user-supplied definition. 7447 7448@kindex macro undef 7449@item macro undef @var{macro} 7450@i{(This command is not yet implemented.)} Remove any user-supplied 7451definition for the macro named @var{macro}. This command only affects 7452definitions provided with the @command{macro define} command, described 7453above; it cannot remove definitions present in the program being 7454debugged. 7455 7456@kindex macro list 7457@item macro list 7458@i{(This command is not yet implemented.)} List all the macros 7459defined using the @code{macro define} command. 7460@end table 7461 7462@cindex macros, example of debugging with 7463Here is a transcript showing the above commands in action. First, we 7464show our source files: 7465 7466@smallexample 7467$ cat sample.c 7468#include <stdio.h> 7469#include "sample.h" 7470 7471#define M 42 7472#define ADD(x) (M + x) 7473 7474main () 7475@{ 7476#define N 28 7477 printf ("Hello, world!\n"); 7478#undef N 7479 printf ("We're so creative.\n"); 7480#define N 1729 7481 printf ("Goodbye, world!\n"); 7482@} 7483$ cat sample.h 7484#define Q < 7485$ 7486@end smallexample 7487 7488Now, we compile the program using the @sc{gnu} C compiler, @value{NGCC}. 7489We pass the @option{-gdwarf-2} and @option{-g3} flags to ensure the 7490compiler includes information about preprocessor macros in the debugging 7491information. 7492 7493@smallexample 7494$ gcc -gdwarf-2 -g3 sample.c -o sample 7495$ 7496@end smallexample 7497 7498Now, we start @value{GDBN} on our sample program: 7499 7500@smallexample 7501$ gdb -nw sample 7502GNU gdb 2002-05-06-cvs 7503Copyright 2002 Free Software Foundation, Inc. 7504GDB is free software, @dots{} 7505(@value{GDBP}) 7506@end smallexample 7507 7508We can expand macros and examine their definitions, even when the 7509program is not running. @value{GDBN} uses the current listing position 7510to decide which macro definitions are in scope: 7511 7512@smallexample 7513(@value{GDBP}) list main 75143 75154 #define M 42 75165 #define ADD(x) (M + x) 75176 75187 main () 75198 @{ 75209 #define N 28 752110 printf ("Hello, world!\n"); 752211 #undef N 752312 printf ("We're so creative.\n"); 7524(@value{GDBP}) info macro ADD 7525Defined at /home/jimb/gdb/macros/play/sample.c:5 7526#define ADD(x) (M + x) 7527(@value{GDBP}) info macro Q 7528Defined at /home/jimb/gdb/macros/play/sample.h:1 7529 included at /home/jimb/gdb/macros/play/sample.c:2 7530#define Q < 7531(@value{GDBP}) macro expand ADD(1) 7532expands to: (42 + 1) 7533(@value{GDBP}) macro expand-once ADD(1) 7534expands to: once (M + 1) 7535(@value{GDBP}) 7536@end smallexample 7537 7538In the example above, note that @command{macro expand-once} expands only 7539the macro invocation explicit in the original text --- the invocation of 7540@code{ADD} --- but does not expand the invocation of the macro @code{M}, 7541which was introduced by @code{ADD}. 7542 7543Once the program is running, @value{GDBN} uses the macro definitions in 7544force at the source line of the current stack frame: 7545 7546@smallexample 7547(@value{GDBP}) break main 7548Breakpoint 1 at 0x8048370: file sample.c, line 10. 7549(@value{GDBP}) run 7550Starting program: /home/jimb/gdb/macros/play/sample 7551 7552Breakpoint 1, main () at sample.c:10 755310 printf ("Hello, world!\n"); 7554(@value{GDBP}) 7555@end smallexample 7556 7557At line 10, the definition of the macro @code{N} at line 9 is in force: 7558 7559@smallexample 7560(@value{GDBP}) info macro N 7561Defined at /home/jimb/gdb/macros/play/sample.c:9 7562#define N 28 7563(@value{GDBP}) macro expand N Q M 7564expands to: 28 < 42 7565(@value{GDBP}) print N Q M 7566$1 = 1 7567(@value{GDBP}) 7568@end smallexample 7569 7570As we step over directives that remove @code{N}'s definition, and then 7571give it a new definition, @value{GDBN} finds the definition (or lack 7572thereof) in force at each point: 7573 7574@smallexample 7575(@value{GDBP}) next 7576Hello, world! 757712 printf ("We're so creative.\n"); 7578(@value{GDBP}) info macro N 7579The symbol `N' has no definition as a C/C++ preprocessor macro 7580at /home/jimb/gdb/macros/play/sample.c:12 7581(@value{GDBP}) next 7582We're so creative. 758314 printf ("Goodbye, world!\n"); 7584(@value{GDBP}) info macro N 7585Defined at /home/jimb/gdb/macros/play/sample.c:13 7586#define N 1729 7587(@value{GDBP}) macro expand N Q M 7588expands to: 1729 < 42 7589(@value{GDBP}) print N Q M 7590$2 = 0 7591(@value{GDBP}) 7592@end smallexample 7593 7594 7595@node Tracepoints 7596@chapter Tracepoints 7597@c This chapter is based on the documentation written by Michael 7598@c Snyder, David Taylor, Jim Blandy, and Elena Zannoni. 7599 7600@cindex tracepoints 7601In some applications, it is not feasible for the debugger to interrupt 7602the program's execution long enough for the developer to learn 7603anything helpful about its behavior. If the program's correctness 7604depends on its real-time behavior, delays introduced by a debugger 7605might cause the program to change its behavior drastically, or perhaps 7606fail, even when the code itself is correct. It is useful to be able 7607to observe the program's behavior without interrupting it. 7608 7609Using @value{GDBN}'s @code{trace} and @code{collect} commands, you can 7610specify locations in the program, called @dfn{tracepoints}, and 7611arbitrary expressions to evaluate when those tracepoints are reached. 7612Later, using the @code{tfind} command, you can examine the values 7613those expressions had when the program hit the tracepoints. The 7614expressions may also denote objects in memory---structures or arrays, 7615for example---whose values @value{GDBN} should record; while visiting 7616a particular tracepoint, you may inspect those objects as if they were 7617in memory at that moment. However, because @value{GDBN} records these 7618values without interacting with you, it can do so quickly and 7619unobtrusively, hopefully not disturbing the program's behavior. 7620 7621The tracepoint facility is currently available only for remote 7622targets. @xref{Targets}. In addition, your remote target must know 7623how to collect trace data. This functionality is implemented in the 7624remote stub; however, none of the stubs distributed with @value{GDBN} 7625support tracepoints as of this writing. The format of the remote 7626packets used to implement tracepoints are described in @ref{Tracepoint 7627Packets}. 7628 7629This chapter describes the tracepoint commands and features. 7630 7631@menu 7632* Set Tracepoints:: 7633* Analyze Collected Data:: 7634* Tracepoint Variables:: 7635@end menu 7636 7637@node Set Tracepoints 7638@section Commands to Set Tracepoints 7639 7640Before running such a @dfn{trace experiment}, an arbitrary number of 7641tracepoints can be set. Like a breakpoint (@pxref{Set Breaks}), a 7642tracepoint has a number assigned to it by @value{GDBN}. Like with 7643breakpoints, tracepoint numbers are successive integers starting from 7644one. Many of the commands associated with tracepoints take the 7645tracepoint number as their argument, to identify which tracepoint to 7646work on. 7647 7648For each tracepoint, you can specify, in advance, some arbitrary set 7649of data that you want the target to collect in the trace buffer when 7650it hits that tracepoint. The collected data can include registers, 7651local variables, or global data. Later, you can use @value{GDBN} 7652commands to examine the values these data had at the time the 7653tracepoint was hit. 7654 7655This section describes commands to set tracepoints and associated 7656conditions and actions. 7657 7658@menu 7659* Create and Delete Tracepoints:: 7660* Enable and Disable Tracepoints:: 7661* Tracepoint Passcounts:: 7662* Tracepoint Actions:: 7663* Listing Tracepoints:: 7664* Starting and Stopping Trace Experiments:: 7665@end menu 7666 7667@node Create and Delete Tracepoints 7668@subsection Create and Delete Tracepoints 7669 7670@table @code 7671@cindex set tracepoint 7672@kindex trace 7673@item trace 7674The @code{trace} command is very similar to the @code{break} command. 7675Its argument can be a source line, a function name, or an address in 7676the target program. @xref{Set Breaks}. The @code{trace} command 7677defines a tracepoint, which is a point in the target program where the 7678debugger will briefly stop, collect some data, and then allow the 7679program to continue. Setting a tracepoint or changing its commands 7680doesn't take effect until the next @code{tstart} command; thus, you 7681cannot change the tracepoint attributes once a trace experiment is 7682running. 7683 7684Here are some examples of using the @code{trace} command: 7685 7686@smallexample 7687(@value{GDBP}) @b{trace foo.c:121} // a source file and line number 7688 7689(@value{GDBP}) @b{trace +2} // 2 lines forward 7690 7691(@value{GDBP}) @b{trace my_function} // first source line of function 7692 7693(@value{GDBP}) @b{trace *my_function} // EXACT start address of function 7694 7695(@value{GDBP}) @b{trace *0x2117c4} // an address 7696@end smallexample 7697 7698@noindent 7699You can abbreviate @code{trace} as @code{tr}. 7700 7701@vindex $tpnum 7702@cindex last tracepoint number 7703@cindex recent tracepoint number 7704@cindex tracepoint number 7705The convenience variable @code{$tpnum} records the tracepoint number 7706of the most recently set tracepoint. 7707 7708@kindex delete tracepoint 7709@cindex tracepoint deletion 7710@item delete tracepoint @r{[}@var{num}@r{]} 7711Permanently delete one or more tracepoints. With no argument, the 7712default is to delete all tracepoints. 7713 7714Examples: 7715 7716@smallexample 7717(@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints 7718 7719(@value{GDBP}) @b{delete trace} // remove all tracepoints 7720@end smallexample 7721 7722@noindent 7723You can abbreviate this command as @code{del tr}. 7724@end table 7725 7726@node Enable and Disable Tracepoints 7727@subsection Enable and Disable Tracepoints 7728 7729@table @code 7730@kindex disable tracepoint 7731@item disable tracepoint @r{[}@var{num}@r{]} 7732Disable tracepoint @var{num}, or all tracepoints if no argument 7733@var{num} is given. A disabled tracepoint will have no effect during 7734the next trace experiment, but it is not forgotten. You can re-enable 7735a disabled tracepoint using the @code{enable tracepoint} command. 7736 7737@kindex enable tracepoint 7738@item enable tracepoint @r{[}@var{num}@r{]} 7739Enable tracepoint @var{num}, or all tracepoints. The enabled 7740tracepoints will become effective the next time a trace experiment is 7741run. 7742@end table 7743 7744@node Tracepoint Passcounts 7745@subsection Tracepoint Passcounts 7746 7747@table @code 7748@kindex passcount 7749@cindex tracepoint pass count 7750@item passcount @r{[}@var{n} @r{[}@var{num}@r{]]} 7751Set the @dfn{passcount} of a tracepoint. The passcount is a way to 7752automatically stop a trace experiment. If a tracepoint's passcount is 7753@var{n}, then the trace experiment will be automatically stopped on 7754the @var{n}'th time that tracepoint is hit. If the tracepoint number 7755@var{num} is not specified, the @code{passcount} command sets the 7756passcount of the most recently defined tracepoint. If no passcount is 7757given, the trace experiment will run until stopped explicitly by the 7758user. 7759 7760Examples: 7761 7762@smallexample 7763(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of 7764@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2} 7765 7766(@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the 7767@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// most recently defined tracepoint.} 7768(@value{GDBP}) @b{trace foo} 7769(@value{GDBP}) @b{pass 3} 7770(@value{GDBP}) @b{trace bar} 7771(@value{GDBP}) @b{pass 2} 7772(@value{GDBP}) @b{trace baz} 7773(@value{GDBP}) @b{pass 1} // Stop tracing when foo has been 7774@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// executed 3 times OR when bar has} 7775@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// been executed 2 times} 7776@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// OR when baz has been executed 1 time.} 7777@end smallexample 7778@end table 7779 7780@node Tracepoint Actions 7781@subsection Tracepoint Action Lists 7782 7783@table @code 7784@kindex actions 7785@cindex tracepoint actions 7786@item actions @r{[}@var{num}@r{]} 7787This command will prompt for a list of actions to be taken when the 7788tracepoint is hit. If the tracepoint number @var{num} is not 7789specified, this command sets the actions for the one that was most 7790recently defined (so that you can define a tracepoint and then say 7791@code{actions} without bothering about its number). You specify the 7792actions themselves on the following lines, one action at a time, and 7793terminate the actions list with a line containing just @code{end}. So 7794far, the only defined actions are @code{collect} and 7795@code{while-stepping}. 7796 7797@cindex remove actions from a tracepoint 7798To remove all actions from a tracepoint, type @samp{actions @var{num}} 7799and follow it immediately with @samp{end}. 7800 7801@smallexample 7802(@value{GDBP}) @b{collect @var{data}} // collect some data 7803 7804(@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data 7805 7806(@value{GDBP}) @b{end} // signals the end of actions. 7807@end smallexample 7808 7809In the following example, the action list begins with @code{collect} 7810commands indicating the things to be collected when the tracepoint is 7811hit. Then, in order to single-step and collect additional data 7812following the tracepoint, a @code{while-stepping} command is used, 7813followed by the list of things to be collected while stepping. The 7814@code{while-stepping} command is terminated by its own separate 7815@code{end} command. Lastly, the action list is terminated by an 7816@code{end} command. 7817 7818@smallexample 7819(@value{GDBP}) @b{trace foo} 7820(@value{GDBP}) @b{actions} 7821Enter actions for tracepoint 1, one per line: 7822> collect bar,baz 7823> collect $regs 7824> while-stepping 12 7825 > collect $fp, $sp 7826 > end 7827end 7828@end smallexample 7829 7830@kindex collect @r{(tracepoints)} 7831@item collect @var{expr1}, @var{expr2}, @dots{} 7832Collect values of the given expressions when the tracepoint is hit. 7833This command accepts a comma-separated list of any valid expressions. 7834In addition to global, static, or local variables, the following 7835special arguments are supported: 7836 7837@table @code 7838@item $regs 7839collect all registers 7840 7841@item $args 7842collect all function arguments 7843 7844@item $locals 7845collect all local variables. 7846@end table 7847 7848You can give several consecutive @code{collect} commands, each one 7849with a single argument, or one @code{collect} command with several 7850arguments separated by commas: the effect is the same. 7851 7852The command @code{info scope} (@pxref{Symbols, info scope}) is 7853particularly useful for figuring out what data to collect. 7854 7855@kindex while-stepping @r{(tracepoints)} 7856@item while-stepping @var{n} 7857Perform @var{n} single-step traces after the tracepoint, collecting 7858new data at each step. The @code{while-stepping} command is 7859followed by the list of what to collect while stepping (followed by 7860its own @code{end} command): 7861 7862@smallexample 7863> while-stepping 12 7864 > collect $regs, myglobal 7865 > end 7866> 7867@end smallexample 7868 7869@noindent 7870You may abbreviate @code{while-stepping} as @code{ws} or 7871@code{stepping}. 7872@end table 7873 7874@node Listing Tracepoints 7875@subsection Listing Tracepoints 7876 7877@table @code 7878@kindex info tracepoints 7879@kindex info tp 7880@cindex information about tracepoints 7881@item info tracepoints @r{[}@var{num}@r{]} 7882Display information about the tracepoint @var{num}. If you don't specify 7883a tracepoint number, displays information about all the tracepoints 7884defined so far. For each tracepoint, the following information is 7885shown: 7886 7887@itemize @bullet 7888@item 7889its number 7890@item 7891whether it is enabled or disabled 7892@item 7893its address 7894@item 7895its passcount as given by the @code{passcount @var{n}} command 7896@item 7897its step count as given by the @code{while-stepping @var{n}} command 7898@item 7899where in the source files is the tracepoint set 7900@item 7901its action list as given by the @code{actions} command 7902@end itemize 7903 7904@smallexample 7905(@value{GDBP}) @b{info trace} 7906Num Enb Address PassC StepC What 79071 y 0x002117c4 0 0 <gdb_asm> 79082 y 0x0020dc64 0 0 in g_test at g_test.c:1375 79093 y 0x0020b1f4 0 0 in get_data at ../foo.c:41 7910(@value{GDBP}) 7911@end smallexample 7912 7913@noindent 7914This command can be abbreviated @code{info tp}. 7915@end table 7916 7917@node Starting and Stopping Trace Experiments 7918@subsection Starting and Stopping Trace Experiments 7919 7920@table @code 7921@kindex tstart 7922@cindex start a new trace experiment 7923@cindex collected data discarded 7924@item tstart 7925This command takes no arguments. It starts the trace experiment, and 7926begins collecting data. This has the side effect of discarding all 7927the data collected in the trace buffer during the previous trace 7928experiment. 7929 7930@kindex tstop 7931@cindex stop a running trace experiment 7932@item tstop 7933This command takes no arguments. It ends the trace experiment, and 7934stops collecting data. 7935 7936@strong{Note}: a trace experiment and data collection may stop 7937automatically if any tracepoint's passcount is reached 7938(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full. 7939 7940@kindex tstatus 7941@cindex status of trace data collection 7942@cindex trace experiment, status of 7943@item tstatus 7944This command displays the status of the current trace data 7945collection. 7946@end table 7947 7948Here is an example of the commands we described so far: 7949 7950@smallexample 7951(@value{GDBP}) @b{trace gdb_c_test} 7952(@value{GDBP}) @b{actions} 7953Enter actions for tracepoint #1, one per line. 7954> collect $regs,$locals,$args 7955> while-stepping 11 7956 > collect $regs 7957 > end 7958> end 7959(@value{GDBP}) @b{tstart} 7960 [time passes @dots{}] 7961(@value{GDBP}) @b{tstop} 7962@end smallexample 7963 7964 7965@node Analyze Collected Data 7966@section Using the Collected Data 7967 7968After the tracepoint experiment ends, you use @value{GDBN} commands 7969for examining the trace data. The basic idea is that each tracepoint 7970collects a trace @dfn{snapshot} every time it is hit and another 7971snapshot every time it single-steps. All these snapshots are 7972consecutively numbered from zero and go into a buffer, and you can 7973examine them later. The way you examine them is to @dfn{focus} on a 7974specific trace snapshot. When the remote stub is focused on a trace 7975snapshot, it will respond to all @value{GDBN} requests for memory and 7976registers by reading from the buffer which belongs to that snapshot, 7977rather than from @emph{real} memory or registers of the program being 7978debugged. This means that @strong{all} @value{GDBN} commands 7979(@code{print}, @code{info registers}, @code{backtrace}, etc.) will 7980behave as if we were currently debugging the program state as it was 7981when the tracepoint occurred. Any requests for data that are not in 7982the buffer will fail. 7983 7984@menu 7985* tfind:: How to select a trace snapshot 7986* tdump:: How to display all data for a snapshot 7987* save-tracepoints:: How to save tracepoints for a future run 7988@end menu 7989 7990@node tfind 7991@subsection @code{tfind @var{n}} 7992 7993@kindex tfind 7994@cindex select trace snapshot 7995@cindex find trace snapshot 7996The basic command for selecting a trace snapshot from the buffer is 7997@code{tfind @var{n}}, which finds trace snapshot number @var{n}, 7998counting from zero. If no argument @var{n} is given, the next 7999snapshot is selected. 8000 8001Here are the various forms of using the @code{tfind} command. 8002 8003@table @code 8004@item tfind start 8005Find the first snapshot in the buffer. This is a synonym for 8006@code{tfind 0} (since 0 is the number of the first snapshot). 8007 8008@item tfind none 8009Stop debugging trace snapshots, resume @emph{live} debugging. 8010 8011@item tfind end 8012Same as @samp{tfind none}. 8013 8014@item tfind 8015No argument means find the next trace snapshot. 8016 8017@item tfind - 8018Find the previous trace snapshot before the current one. This permits 8019retracing earlier steps. 8020 8021@item tfind tracepoint @var{num} 8022Find the next snapshot associated with tracepoint @var{num}. Search 8023proceeds forward from the last examined trace snapshot. If no 8024argument @var{num} is given, it means find the next snapshot collected 8025for the same tracepoint as the current snapshot. 8026 8027@item tfind pc @var{addr} 8028Find the next snapshot associated with the value @var{addr} of the 8029program counter. Search proceeds forward from the last examined trace 8030snapshot. If no argument @var{addr} is given, it means find the next 8031snapshot with the same value of PC as the current snapshot. 8032 8033@item tfind outside @var{addr1}, @var{addr2} 8034Find the next snapshot whose PC is outside the given range of 8035addresses. 8036 8037@item tfind range @var{addr1}, @var{addr2} 8038Find the next snapshot whose PC is between @var{addr1} and 8039@var{addr2}. @c FIXME: Is the range inclusive or exclusive? 8040 8041@item tfind line @r{[}@var{file}:@r{]}@var{n} 8042Find the next snapshot associated with the source line @var{n}. If 8043the optional argument @var{file} is given, refer to line @var{n} in 8044that source file. Search proceeds forward from the last examined 8045trace snapshot. If no argument @var{n} is given, it means find the 8046next line other than the one currently being examined; thus saying 8047@code{tfind line} repeatedly can appear to have the same effect as 8048stepping from line to line in a @emph{live} debugging session. 8049@end table 8050 8051The default arguments for the @code{tfind} commands are specifically 8052designed to make it easy to scan through the trace buffer. For 8053instance, @code{tfind} with no argument selects the next trace 8054snapshot, and @code{tfind -} with no argument selects the previous 8055trace snapshot. So, by giving one @code{tfind} command, and then 8056simply hitting @key{RET} repeatedly you can examine all the trace 8057snapshots in order. Or, by saying @code{tfind -} and then hitting 8058@key{RET} repeatedly you can examine the snapshots in reverse order. 8059The @code{tfind line} command with no argument selects the snapshot 8060for the next source line executed. The @code{tfind pc} command with 8061no argument selects the next snapshot with the same program counter 8062(PC) as the current frame. The @code{tfind tracepoint} command with 8063no argument selects the next trace snapshot collected by the same 8064tracepoint as the current one. 8065 8066In addition to letting you scan through the trace buffer manually, 8067these commands make it easy to construct @value{GDBN} scripts that 8068scan through the trace buffer and print out whatever collected data 8069you are interested in. Thus, if we want to examine the PC, FP, and SP 8070registers from each trace frame in the buffer, we can say this: 8071 8072@smallexample 8073(@value{GDBP}) @b{tfind start} 8074(@value{GDBP}) @b{while ($trace_frame != -1)} 8075> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ 8076 $trace_frame, $pc, $sp, $fp 8077> tfind 8078> end 8079 8080Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 8081Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 8082Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 8083Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 8084Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 8085Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 8086Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 8087Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 8088Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 8089Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 8090Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 8091@end smallexample 8092 8093Or, if we want to examine the variable @code{X} at each source line in 8094the buffer: 8095 8096@smallexample 8097(@value{GDBP}) @b{tfind start} 8098(@value{GDBP}) @b{while ($trace_frame != -1)} 8099> printf "Frame %d, X == %d\n", $trace_frame, X 8100> tfind line 8101> end 8102 8103Frame 0, X = 1 8104Frame 7, X = 2 8105Frame 13, X = 255 8106@end smallexample 8107 8108@node tdump 8109@subsection @code{tdump} 8110@kindex tdump 8111@cindex dump all data collected at tracepoint 8112@cindex tracepoint data, display 8113 8114This command takes no arguments. It prints all the data collected at 8115the current trace snapshot. 8116 8117@smallexample 8118(@value{GDBP}) @b{trace 444} 8119(@value{GDBP}) @b{actions} 8120Enter actions for tracepoint #2, one per line: 8121> collect $regs, $locals, $args, gdb_long_test 8122> end 8123 8124(@value{GDBP}) @b{tstart} 8125 8126(@value{GDBP}) @b{tfind line 444} 8127#0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) 8128at gdb_test.c:444 8129444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) 8130 8131(@value{GDBP}) @b{tdump} 8132Data collected at tracepoint 2, trace frame 1: 8133d0 0xc4aa0085 -995491707 8134d1 0x18 24 8135d2 0x80 128 8136d3 0x33 51 8137d4 0x71aea3d 119204413 8138d5 0x22 34 8139d6 0xe0 224 8140d7 0x380035 3670069 8141a0 0x19e24a 1696330 8142a1 0x3000668 50333288 8143a2 0x100 256 8144a3 0x322000 3284992 8145a4 0x3000698 50333336 8146a5 0x1ad3cc 1758156 8147fp 0x30bf3c 0x30bf3c 8148sp 0x30bf34 0x30bf34 8149ps 0x0 0 8150pc 0x20b2c8 0x20b2c8 8151fpcontrol 0x0 0 8152fpstatus 0x0 0 8153fpiaddr 0x0 0 8154p = 0x20e5b4 "gdb-test" 8155p1 = (void *) 0x11 8156p2 = (void *) 0x22 8157p3 = (void *) 0x33 8158p4 = (void *) 0x44 8159p5 = (void *) 0x55 8160p6 = (void *) 0x66 8161gdb_long_test = 17 '\021' 8162 8163(@value{GDBP}) 8164@end smallexample 8165 8166@node save-tracepoints 8167@subsection @code{save-tracepoints @var{filename}} 8168@kindex save-tracepoints 8169@cindex save tracepoints for future sessions 8170 8171This command saves all current tracepoint definitions together with 8172their actions and passcounts, into a file @file{@var{filename}} 8173suitable for use in a later debugging session. To read the saved 8174tracepoint definitions, use the @code{source} command (@pxref{Command 8175Files}). 8176 8177@node Tracepoint Variables 8178@section Convenience Variables for Tracepoints 8179@cindex tracepoint variables 8180@cindex convenience variables for tracepoints 8181 8182@table @code 8183@vindex $trace_frame 8184@item (int) $trace_frame 8185The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no 8186snapshot is selected. 8187 8188@vindex $tracepoint 8189@item (int) $tracepoint 8190The tracepoint for the current trace snapshot. 8191 8192@vindex $trace_line 8193@item (int) $trace_line 8194The line number for the current trace snapshot. 8195 8196@vindex $trace_file 8197@item (char []) $trace_file 8198The source file for the current trace snapshot. 8199 8200@vindex $trace_func 8201@item (char []) $trace_func 8202The name of the function containing @code{$tracepoint}. 8203@end table 8204 8205Note: @code{$trace_file} is not suitable for use in @code{printf}, 8206use @code{output} instead. 8207 8208Here's a simple example of using these convenience variables for 8209stepping through all the trace snapshots and printing some of their 8210data. 8211 8212@smallexample 8213(@value{GDBP}) @b{tfind start} 8214 8215(@value{GDBP}) @b{while $trace_frame != -1} 8216> output $trace_file 8217> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint 8218> tfind 8219> end 8220@end smallexample 8221 8222@node Overlays 8223@chapter Debugging Programs That Use Overlays 8224@cindex overlays 8225 8226If your program is too large to fit completely in your target system's 8227memory, you can sometimes use @dfn{overlays} to work around this 8228problem. @value{GDBN} provides some support for debugging programs that 8229use overlays. 8230 8231@menu 8232* How Overlays Work:: A general explanation of overlays. 8233* Overlay Commands:: Managing overlays in @value{GDBN}. 8234* Automatic Overlay Debugging:: @value{GDBN} can find out which overlays are 8235 mapped by asking the inferior. 8236* Overlay Sample Program:: A sample program using overlays. 8237@end menu 8238 8239@node How Overlays Work 8240@section How Overlays Work 8241@cindex mapped overlays 8242@cindex unmapped overlays 8243@cindex load address, overlay's 8244@cindex mapped address 8245@cindex overlay area 8246 8247Suppose you have a computer whose instruction address space is only 64 8248kilobytes long, but which has much more memory which can be accessed by 8249other means: special instructions, segment registers, or memory 8250management hardware, for example. Suppose further that you want to 8251adapt a program which is larger than 64 kilobytes to run on this system. 8252 8253One solution is to identify modules of your program which are relatively 8254independent, and need not call each other directly; call these modules 8255@dfn{overlays}. Separate the overlays from the main program, and place 8256their machine code in the larger memory. Place your main program in 8257instruction memory, but leave at least enough space there to hold the 8258largest overlay as well. 8259 8260Now, to call a function located in an overlay, you must first copy that 8261overlay's machine code from the large memory into the space set aside 8262for it in the instruction memory, and then jump to its entry point 8263there. 8264 8265@c NB: In the below the mapped area's size is greater or equal to the 8266@c size of all overlays. This is intentional to remind the developer 8267@c that overlays don't necessarily need to be the same size. 8268 8269@smallexample 8270@group 8271 Data Instruction Larger 8272Address Space Address Space Address Space 8273+-----------+ +-----------+ +-----------+ 8274| | | | | | 8275+-----------+ +-----------+ +-----------+<-- overlay 1 8276| program | | main | .----| overlay 1 | load address 8277| variables | | program | | +-----------+ 8278| and heap | | | | | | 8279+-----------+ | | | +-----------+<-- overlay 2 8280| | +-----------+ | | | load address 8281+-----------+ | | | .-| overlay 2 | 8282 | | | | | | 8283 mapped --->+-----------+ | | +-----------+ 8284 address | | | | | | 8285 | overlay | <-' | | | 8286 | area | <---' +-----------+<-- overlay 3 8287 | | <---. | | load address 8288 +-----------+ `--| overlay 3 | 8289 | | | | 8290 +-----------+ | | 8291 +-----------+ 8292 | | 8293 +-----------+ 8294 8295 @anchor{A code overlay}A code overlay 8296@end group 8297@end smallexample 8298 8299The diagram (@pxref{A code overlay}) shows a system with separate data 8300and instruction address spaces. To map an overlay, the program copies 8301its code from the larger address space to the instruction address space. 8302Since the overlays shown here all use the same mapped address, only one 8303may be mapped at a time. For a system with a single address space for 8304data and instructions, the diagram would be similar, except that the 8305program variables and heap would share an address space with the main 8306program and the overlay area. 8307 8308An overlay loaded into instruction memory and ready for use is called a 8309@dfn{mapped} overlay; its @dfn{mapped address} is its address in the 8310instruction memory. An overlay not present (or only partially present) 8311in instruction memory is called @dfn{unmapped}; its @dfn{load address} 8312is its address in the larger memory. The mapped address is also called 8313the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also 8314called the @dfn{load memory address}, or @dfn{LMA}. 8315 8316Unfortunately, overlays are not a completely transparent way to adapt a 8317program to limited instruction memory. They introduce a new set of 8318global constraints you must keep in mind as you design your program: 8319 8320@itemize @bullet 8321 8322@item 8323Before calling or returning to a function in an overlay, your program 8324must make sure that overlay is actually mapped. Otherwise, the call or 8325return will transfer control to the right address, but in the wrong 8326overlay, and your program will probably crash. 8327 8328@item 8329If the process of mapping an overlay is expensive on your system, you 8330will need to choose your overlays carefully to minimize their effect on 8331your program's performance. 8332 8333@item 8334The executable file you load onto your system must contain each 8335overlay's instructions, appearing at the overlay's load address, not its 8336mapped address. However, each overlay's instructions must be relocated 8337and its symbols defined as if the overlay were at its mapped address. 8338You can use GNU linker scripts to specify different load and relocation 8339addresses for pieces of your program; see @ref{Overlay Description,,, 8340ld.info, Using ld: the GNU linker}. 8341 8342@item 8343The procedure for loading executable files onto your system must be able 8344to load their contents into the larger address space as well as the 8345instruction and data spaces. 8346 8347@end itemize 8348 8349The overlay system described above is rather simple, and could be 8350improved in many ways: 8351 8352@itemize @bullet 8353 8354@item 8355If your system has suitable bank switch registers or memory management 8356hardware, you could use those facilities to make an overlay's load area 8357contents simply appear at their mapped address in instruction space. 8358This would probably be faster than copying the overlay to its mapped 8359area in the usual way. 8360 8361@item 8362If your overlays are small enough, you could set aside more than one 8363overlay area, and have more than one overlay mapped at a time. 8364 8365@item 8366You can use overlays to manage data, as well as instructions. In 8367general, data overlays are even less transparent to your design than 8368code overlays: whereas code overlays only require care when you call or 8369return to functions, data overlays require care every time you access 8370the data. Also, if you change the contents of a data overlay, you 8371must copy its contents back out to its load address before you can copy a 8372different data overlay into the same mapped area. 8373 8374@end itemize 8375 8376 8377@node Overlay Commands 8378@section Overlay Commands 8379 8380To use @value{GDBN}'s overlay support, each overlay in your program must 8381correspond to a separate section of the executable file. The section's 8382virtual memory address and load memory address must be the overlay's 8383mapped and load addresses. Identifying overlays with sections allows 8384@value{GDBN} to determine the appropriate address of a function or 8385variable, depending on whether the overlay is mapped or not. 8386 8387@value{GDBN}'s overlay commands all start with the word @code{overlay}; 8388you can abbreviate this as @code{ov} or @code{ovly}. The commands are: 8389 8390@table @code 8391@item overlay off 8392@kindex overlay 8393Disable @value{GDBN}'s overlay support. When overlay support is 8394disabled, @value{GDBN} assumes that all functions and variables are 8395always present at their mapped addresses. By default, @value{GDBN}'s 8396overlay support is disabled. 8397 8398@item overlay manual 8399@cindex manual overlay debugging 8400Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN} 8401relies on you to tell it which overlays are mapped, and which are not, 8402using the @code{overlay map-overlay} and @code{overlay unmap-overlay} 8403commands described below. 8404 8405@item overlay map-overlay @var{overlay} 8406@itemx overlay map @var{overlay} 8407@cindex map an overlay 8408Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must 8409be the name of the object file section containing the overlay. When an 8410overlay is mapped, @value{GDBN} assumes it can find the overlay's 8411functions and variables at their mapped addresses. @value{GDBN} assumes 8412that any other overlays whose mapped ranges overlap that of 8413@var{overlay} are now unmapped. 8414 8415@item overlay unmap-overlay @var{overlay} 8416@itemx overlay unmap @var{overlay} 8417@cindex unmap an overlay 8418Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay} 8419must be the name of the object file section containing the overlay. 8420When an overlay is unmapped, @value{GDBN} assumes it can find the 8421overlay's functions and variables at their load addresses. 8422 8423@item overlay auto 8424Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN} 8425consults a data structure the overlay manager maintains in the inferior 8426to see which overlays are mapped. For details, see @ref{Automatic 8427Overlay Debugging}. 8428 8429@item overlay load-target 8430@itemx overlay load 8431@cindex reloading the overlay table 8432Re-read the overlay table from the inferior. Normally, @value{GDBN} 8433re-reads the table @value{GDBN} automatically each time the inferior 8434stops, so this command should only be necessary if you have changed the 8435overlay mapping yourself using @value{GDBN}. This command is only 8436useful when using automatic overlay debugging. 8437 8438@item overlay list-overlays 8439@itemx overlay list 8440@cindex listing mapped overlays 8441Display a list of the overlays currently mapped, along with their mapped 8442addresses, load addresses, and sizes. 8443 8444@end table 8445 8446Normally, when @value{GDBN} prints a code address, it includes the name 8447of the function the address falls in: 8448 8449@smallexample 8450(@value{GDBP}) print main 8451$3 = @{int ()@} 0x11a0 <main> 8452@end smallexample 8453@noindent 8454When overlay debugging is enabled, @value{GDBN} recognizes code in 8455unmapped overlays, and prints the names of unmapped functions with 8456asterisks around them. For example, if @code{foo} is a function in an 8457unmapped overlay, @value{GDBN} prints it this way: 8458 8459@smallexample 8460(@value{GDBP}) overlay list 8461No sections are mapped. 8462(@value{GDBP}) print foo 8463$5 = @{int (int)@} 0x100000 <*foo*> 8464@end smallexample 8465@noindent 8466When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's 8467name normally: 8468 8469@smallexample 8470(@value{GDBP}) overlay list 8471Section .ov.foo.text, loaded at 0x100000 - 0x100034, 8472 mapped at 0x1016 - 0x104a 8473(@value{GDBP}) print foo 8474$6 = @{int (int)@} 0x1016 <foo> 8475@end smallexample 8476 8477When overlay debugging is enabled, @value{GDBN} can find the correct 8478address for functions and variables in an overlay, whether or not the 8479overlay is mapped. This allows most @value{GDBN} commands, like 8480@code{break} and @code{disassemble}, to work normally, even on unmapped 8481code. However, @value{GDBN}'s breakpoint support has some limitations: 8482 8483@itemize @bullet 8484@item 8485@cindex breakpoints in overlays 8486@cindex overlays, setting breakpoints in 8487You can set breakpoints in functions in unmapped overlays, as long as 8488@value{GDBN} can write to the overlay at its load address. 8489@item 8490@value{GDBN} can not set hardware or simulator-based breakpoints in 8491unmapped overlays. However, if you set a breakpoint at the end of your 8492overlay manager (and tell @value{GDBN} which overlays are now mapped, if 8493you are using manual overlay management), @value{GDBN} will re-set its 8494breakpoints properly. 8495@end itemize 8496 8497 8498@node Automatic Overlay Debugging 8499@section Automatic Overlay Debugging 8500@cindex automatic overlay debugging 8501 8502@value{GDBN} can automatically track which overlays are mapped and which 8503are not, given some simple co-operation from the overlay manager in the 8504inferior. If you enable automatic overlay debugging with the 8505@code{overlay auto} command (@pxref{Overlay Commands}), @value{GDBN} 8506looks in the inferior's memory for certain variables describing the 8507current state of the overlays. 8508 8509Here are the variables your overlay manager must define to support 8510@value{GDBN}'s automatic overlay debugging: 8511 8512@table @asis 8513 8514@item @code{_ovly_table}: 8515This variable must be an array of the following structures: 8516 8517@smallexample 8518struct 8519@{ 8520 /* The overlay's mapped address. */ 8521 unsigned long vma; 8522 8523 /* The size of the overlay, in bytes. */ 8524 unsigned long size; 8525 8526 /* The overlay's load address. */ 8527 unsigned long lma; 8528 8529 /* Non-zero if the overlay is currently mapped; 8530 zero otherwise. */ 8531 unsigned long mapped; 8532@} 8533@end smallexample 8534 8535@item @code{_novlys}: 8536This variable must be a four-byte signed integer, holding the total 8537number of elements in @code{_ovly_table}. 8538 8539@end table 8540 8541To decide whether a particular overlay is mapped or not, @value{GDBN} 8542looks for an entry in @w{@code{_ovly_table}} whose @code{vma} and 8543@code{lma} members equal the VMA and LMA of the overlay's section in the 8544executable file. When @value{GDBN} finds a matching entry, it consults 8545the entry's @code{mapped} member to determine whether the overlay is 8546currently mapped. 8547 8548In addition, your overlay manager may define a function called 8549@code{_ovly_debug_event}. If this function is defined, @value{GDBN} 8550will silently set a breakpoint there. If the overlay manager then 8551calls this function whenever it has changed the overlay table, this 8552will enable @value{GDBN} to accurately keep track of which overlays 8553are in program memory, and update any breakpoints that may be set 8554in overlays. This will allow breakpoints to work even if the 8555overlays are kept in ROM or other non-writable memory while they 8556are not being executed. 8557 8558@node Overlay Sample Program 8559@section Overlay Sample Program 8560@cindex overlay example program 8561 8562When linking a program which uses overlays, you must place the overlays 8563at their load addresses, while relocating them to run at their mapped 8564addresses. To do this, you must write a linker script (@pxref{Overlay 8565Description,,, ld.info, Using ld: the GNU linker}). Unfortunately, 8566since linker scripts are specific to a particular host system, target 8567architecture, and target memory layout, this manual cannot provide 8568portable sample code demonstrating @value{GDBN}'s overlay support. 8569 8570However, the @value{GDBN} source distribution does contain an overlaid 8571program, with linker scripts for a few systems, as part of its test 8572suite. The program consists of the following files from 8573@file{gdb/testsuite/gdb.base}: 8574 8575@table @file 8576@item overlays.c 8577The main program file. 8578@item ovlymgr.c 8579A simple overlay manager, used by @file{overlays.c}. 8580@item foo.c 8581@itemx bar.c 8582@itemx baz.c 8583@itemx grbx.c 8584Overlay modules, loaded and used by @file{overlays.c}. 8585@item d10v.ld 8586@itemx m32r.ld 8587Linker scripts for linking the test program on the @code{d10v-elf} 8588and @code{m32r-elf} targets. 8589@end table 8590 8591You can build the test program using the @code{d10v-elf} GCC 8592cross-compiler like this: 8593 8594@smallexample 8595$ d10v-elf-gcc -g -c overlays.c 8596$ d10v-elf-gcc -g -c ovlymgr.c 8597$ d10v-elf-gcc -g -c foo.c 8598$ d10v-elf-gcc -g -c bar.c 8599$ d10v-elf-gcc -g -c baz.c 8600$ d10v-elf-gcc -g -c grbx.c 8601$ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ 8602 baz.o grbx.o -Wl,-Td10v.ld -o overlays 8603@end smallexample 8604 8605The build process is identical for any other architecture, except that 8606you must substitute the appropriate compiler and linker script for the 8607target system for @code{d10v-elf-gcc} and @code{d10v.ld}. 8608 8609 8610@node Languages 8611@chapter Using @value{GDBN} with Different Languages 8612@cindex languages 8613 8614Although programming languages generally have common aspects, they are 8615rarely expressed in the same manner. For instance, in ANSI C, 8616dereferencing a pointer @code{p} is accomplished by @code{*p}, but in 8617Modula-2, it is accomplished by @code{p^}. Values can also be 8618represented (and displayed) differently. Hex numbers in C appear as 8619@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}. 8620 8621@cindex working language 8622Language-specific information is built into @value{GDBN} for some languages, 8623allowing you to express operations like the above in your program's 8624native language, and allowing @value{GDBN} to output values in a manner 8625consistent with the syntax of your program's native language. The 8626language you use to build expressions is called the @dfn{working 8627language}. 8628 8629@menu 8630* Setting:: Switching between source languages 8631* Show:: Displaying the language 8632* Checks:: Type and range checks 8633* Supported Languages:: Supported languages 8634* Unsupported Languages:: Unsupported languages 8635@end menu 8636 8637@node Setting 8638@section Switching Between Source Languages 8639 8640There are two ways to control the working language---either have @value{GDBN} 8641set it automatically, or select it manually yourself. You can use the 8642@code{set language} command for either purpose. On startup, @value{GDBN} 8643defaults to setting the language automatically. The working language is 8644used to determine how expressions you type are interpreted, how values 8645are printed, etc. 8646 8647In addition to the working language, every source file that 8648@value{GDBN} knows about has its own working language. For some object 8649file formats, the compiler might indicate which language a particular 8650source file is in. However, most of the time @value{GDBN} infers the 8651language from the name of the file. The language of a source file 8652controls whether C@t{++} names are demangled---this way @code{backtrace} can 8653show each frame appropriately for its own language. There is no way to 8654set the language of a source file from within @value{GDBN}, but you can 8655set the language associated with a filename extension. @xref{Show, , 8656Displaying the Language}. 8657 8658This is most commonly a problem when you use a program, such 8659as @code{cfront} or @code{f2c}, that generates C but is written in 8660another language. In that case, make the 8661program use @code{#line} directives in its C output; that way 8662@value{GDBN} will know the correct language of the source code of the original 8663program, and will display that source code, not the generated C code. 8664 8665@menu 8666* Filenames:: Filename extensions and languages. 8667* Manually:: Setting the working language manually 8668* Automatically:: Having @value{GDBN} infer the source language 8669@end menu 8670 8671@node Filenames 8672@subsection List of Filename Extensions and Languages 8673 8674If a source file name ends in one of the following extensions, then 8675@value{GDBN} infers that its language is the one indicated. 8676 8677@table @file 8678@item .ada 8679@itemx .ads 8680@itemx .adb 8681@itemx .a 8682Ada source file. 8683 8684@item .c 8685C source file 8686 8687@item .C 8688@itemx .cc 8689@itemx .cp 8690@itemx .cpp 8691@itemx .cxx 8692@itemx .c++ 8693C@t{++} source file 8694 8695@item .m 8696Objective-C source file 8697 8698@item .f 8699@itemx .F 8700Fortran source file 8701 8702@item .mod 8703Modula-2 source file 8704 8705@item .s 8706@itemx .S 8707Assembler source file. This actually behaves almost like C, but 8708@value{GDBN} does not skip over function prologues when stepping. 8709@end table 8710 8711In addition, you may set the language associated with a filename 8712extension. @xref{Show, , Displaying the Language}. 8713 8714@node Manually 8715@subsection Setting the Working Language 8716 8717If you allow @value{GDBN} to set the language automatically, 8718expressions are interpreted the same way in your debugging session and 8719your program. 8720 8721@kindex set language 8722If you wish, you may set the language manually. To do this, issue the 8723command @samp{set language @var{lang}}, where @var{lang} is the name of 8724a language, such as 8725@code{c} or @code{modula-2}. 8726For a list of the supported languages, type @samp{set language}. 8727 8728Setting the language manually prevents @value{GDBN} from updating the working 8729language automatically. This can lead to confusion if you try 8730to debug a program when the working language is not the same as the 8731source language, when an expression is acceptable to both 8732languages---but means different things. For instance, if the current 8733source file were written in C, and @value{GDBN} was parsing Modula-2, a 8734command such as: 8735 8736@smallexample 8737print a = b + c 8738@end smallexample 8739 8740@noindent 8741might not have the effect you intended. In C, this means to add 8742@code{b} and @code{c} and place the result in @code{a}. The result 8743printed would be the value of @code{a}. In Modula-2, this means to compare 8744@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value. 8745 8746@node Automatically 8747@subsection Having @value{GDBN} Infer the Source Language 8748 8749To have @value{GDBN} set the working language automatically, use 8750@samp{set language local} or @samp{set language auto}. @value{GDBN} 8751then infers the working language. That is, when your program stops in a 8752frame (usually by encountering a breakpoint), @value{GDBN} sets the 8753working language to the language recorded for the function in that 8754frame. If the language for a frame is unknown (that is, if the function 8755or block corresponding to the frame was defined in a source file that 8756does not have a recognized extension), the current working language is 8757not changed, and @value{GDBN} issues a warning. 8758 8759This may not seem necessary for most programs, which are written 8760entirely in one source language. However, program modules and libraries 8761written in one source language can be used by a main program written in 8762a different source language. Using @samp{set language auto} in this 8763case frees you from having to set the working language manually. 8764 8765@node Show 8766@section Displaying the Language 8767 8768The following commands help you find out which language is the 8769working language, and also what language source files were written in. 8770 8771@table @code 8772@item show language 8773@kindex show language 8774Display the current working language. This is the 8775language you can use with commands such as @code{print} to 8776build and compute expressions that may involve variables in your program. 8777 8778@item info frame 8779@kindex info frame@r{, show the source language} 8780Display the source language for this frame. This language becomes the 8781working language if you use an identifier from this frame. 8782@xref{Frame Info, ,Information about a Frame}, to identify the other 8783information listed here. 8784 8785@item info source 8786@kindex info source@r{, show the source language} 8787Display the source language of this source file. 8788@xref{Symbols, ,Examining the Symbol Table}, to identify the other 8789information listed here. 8790@end table 8791 8792In unusual circumstances, you may have source files with extensions 8793not in the standard list. You can then set the extension associated 8794with a language explicitly: 8795 8796@table @code 8797@item set extension-language @var{ext} @var{language} 8798@kindex set extension-language 8799Tell @value{GDBN} that source files with extension @var{ext} are to be 8800assumed as written in the source language @var{language}. 8801 8802@item info extensions 8803@kindex info extensions 8804List all the filename extensions and the associated languages. 8805@end table 8806 8807@node Checks 8808@section Type and Range Checking 8809 8810@quotation 8811@emph{Warning:} In this release, the @value{GDBN} commands for type and range 8812checking are included, but they do not yet have any effect. This 8813section documents the intended facilities. 8814@end quotation 8815@c FIXME remove warning when type/range code added 8816 8817Some languages are designed to guard you against making seemingly common 8818errors through a series of compile- and run-time checks. These include 8819checking the type of arguments to functions and operators, and making 8820sure mathematical overflows are caught at run time. Checks such as 8821these help to ensure a program's correctness once it has been compiled 8822by eliminating type mismatches, and providing active checks for range 8823errors when your program is running. 8824 8825@value{GDBN} can check for conditions like the above if you wish. 8826Although @value{GDBN} does not check the statements in your program, 8827it can check expressions entered directly into @value{GDBN} for 8828evaluation via the @code{print} command, for example. As with the 8829working language, @value{GDBN} can also decide whether or not to check 8830automatically based on your program's source language. 8831@xref{Supported Languages, ,Supported Languages}, for the default 8832settings of supported languages. 8833 8834@menu 8835* Type Checking:: An overview of type checking 8836* Range Checking:: An overview of range checking 8837@end menu 8838 8839@cindex type checking 8840@cindex checks, type 8841@node Type Checking 8842@subsection An Overview of Type Checking 8843 8844Some languages, such as Modula-2, are strongly typed, meaning that the 8845arguments to operators and functions have to be of the correct type, 8846otherwise an error occurs. These checks prevent type mismatch 8847errors from ever causing any run-time problems. For example, 8848 8849@smallexample 88501 + 2 @result{} 3 8851@exdent but 8852@error{} 1 + 2.3 8853@end smallexample 8854 8855The second example fails because the @code{CARDINAL} 1 is not 8856type-compatible with the @code{REAL} 2.3. 8857 8858For the expressions you use in @value{GDBN} commands, you can tell the 8859@value{GDBN} type checker to skip checking; 8860to treat any mismatches as errors and abandon the expression; 8861or to only issue warnings when type mismatches occur, 8862but evaluate the expression anyway. When you choose the last of 8863these, @value{GDBN} evaluates expressions like the second example above, but 8864also issues a warning. 8865 8866Even if you turn type checking off, there may be other reasons 8867related to type that prevent @value{GDBN} from evaluating an expression. 8868For instance, @value{GDBN} does not know how to add an @code{int} and 8869a @code{struct foo}. These particular type errors have nothing to do 8870with the language in use, and usually arise from expressions, such as 8871the one described above, which make little sense to evaluate anyway. 8872 8873Each language defines to what degree it is strict about type. For 8874instance, both Modula-2 and C require the arguments to arithmetical 8875operators to be numbers. In C, enumerated types and pointers can be 8876represented as numbers, so that they are valid arguments to mathematical 8877operators. @xref{Supported Languages, ,Supported Languages}, for further 8878details on specific languages. 8879 8880@value{GDBN} provides some additional commands for controlling the type checker: 8881 8882@kindex set check type 8883@kindex show check type 8884@table @code 8885@item set check type auto 8886Set type checking on or off based on the current working language. 8887@xref{Supported Languages, ,Supported Languages}, for the default settings for 8888each language. 8889 8890@item set check type on 8891@itemx set check type off 8892Set type checking on or off, overriding the default setting for the 8893current working language. Issue a warning if the setting does not 8894match the language default. If any type mismatches occur in 8895evaluating an expression while type checking is on, @value{GDBN} prints a 8896message and aborts evaluation of the expression. 8897 8898@item set check type warn 8899Cause the type checker to issue warnings, but to always attempt to 8900evaluate the expression. Evaluating the expression may still 8901be impossible for other reasons. For example, @value{GDBN} cannot add 8902numbers and structures. 8903 8904@item show type 8905Show the current setting of the type checker, and whether or not @value{GDBN} 8906is setting it automatically. 8907@end table 8908 8909@cindex range checking 8910@cindex checks, range 8911@node Range Checking 8912@subsection An Overview of Range Checking 8913 8914In some languages (such as Modula-2), it is an error to exceed the 8915bounds of a type; this is enforced with run-time checks. Such range 8916checking is meant to ensure program correctness by making sure 8917computations do not overflow, or indices on an array element access do 8918not exceed the bounds of the array. 8919 8920For expressions you use in @value{GDBN} commands, you can tell 8921@value{GDBN} to treat range errors in one of three ways: ignore them, 8922always treat them as errors and abandon the expression, or issue 8923warnings but evaluate the expression anyway. 8924 8925A range error can result from numerical overflow, from exceeding an 8926array index bound, or when you type a constant that is not a member 8927of any type. Some languages, however, do not treat overflows as an 8928error. In many implementations of C, mathematical overflow causes the 8929result to ``wrap around'' to lower values---for example, if @var{m} is 8930the largest integer value, and @var{s} is the smallest, then 8931 8932@smallexample 8933@var{m} + 1 @result{} @var{s} 8934@end smallexample 8935 8936This, too, is specific to individual languages, and in some cases 8937specific to individual compilers or machines. @xref{Supported Languages, , 8938Supported Languages}, for further details on specific languages. 8939 8940@value{GDBN} provides some additional commands for controlling the range checker: 8941 8942@kindex set check range 8943@kindex show check range 8944@table @code 8945@item set check range auto 8946Set range checking on or off based on the current working language. 8947@xref{Supported Languages, ,Supported Languages}, for the default settings for 8948each language. 8949 8950@item set check range on 8951@itemx set check range off 8952Set range checking on or off, overriding the default setting for the 8953current working language. A warning is issued if the setting does not 8954match the language default. If a range error occurs and range checking is on, 8955then a message is printed and evaluation of the expression is aborted. 8956 8957@item set check range warn 8958Output messages when the @value{GDBN} range checker detects a range error, 8959but attempt to evaluate the expression anyway. Evaluating the 8960expression may still be impossible for other reasons, such as accessing 8961memory that the process does not own (a typical example from many Unix 8962systems). 8963 8964@item show range 8965Show the current setting of the range checker, and whether or not it is 8966being set automatically by @value{GDBN}. 8967@end table 8968 8969@node Supported Languages 8970@section Supported Languages 8971 8972@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, Pascal, 8973assembly, Modula-2, and Ada. 8974@c This is false ... 8975Some @value{GDBN} features may be used in expressions regardless of the 8976language you use: the @value{GDBN} @code{@@} and @code{::} operators, 8977and the @samp{@{type@}addr} construct (@pxref{Expressions, 8978,Expressions}) can be used with the constructs of any supported 8979language. 8980 8981The following sections detail to what degree each source language is 8982supported by @value{GDBN}. These sections are not meant to be language 8983tutorials or references, but serve only as a reference guide to what the 8984@value{GDBN} expression parser accepts, and what input and output 8985formats should look like for different languages. There are many good 8986books written on each of these languages; please look to these for a 8987language reference or tutorial. 8988 8989@menu 8990* C:: C and C@t{++} 8991* Objective-C:: Objective-C 8992* Fortran:: Fortran 8993* Pascal:: Pascal 8994* Modula-2:: Modula-2 8995* Ada:: Ada 8996@end menu 8997 8998@node C 8999@subsection C and C@t{++} 9000 9001@cindex C and C@t{++} 9002@cindex expressions in C or C@t{++} 9003 9004Since C and C@t{++} are so closely related, many features of @value{GDBN} apply 9005to both languages. Whenever this is the case, we discuss those languages 9006together. 9007 9008@cindex C@t{++} 9009@cindex @code{g++}, @sc{gnu} C@t{++} compiler 9010@cindex @sc{gnu} C@t{++} 9011The C@t{++} debugging facilities are jointly implemented by the C@t{++} 9012compiler and @value{GDBN}. Therefore, to debug your C@t{++} code 9013effectively, you must compile your C@t{++} programs with a supported 9014C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++} 9015compiler (@code{aCC}). 9016 9017For best results when using @sc{gnu} C@t{++}, use the DWARF 2 debugging 9018format; if it doesn't work on your system, try the stabs+ debugging 9019format. You can select those formats explicitly with the @code{g++} 9020command-line options @option{-gdwarf-2} and @option{-gstabs+}. 9021@xref{Debugging Options,,Options for Debugging Your Program or GCC, 9022gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}. 9023 9024@menu 9025* C Operators:: C and C@t{++} operators 9026* C Constants:: C and C@t{++} constants 9027* C Plus Plus Expressions:: C@t{++} expressions 9028* C Defaults:: Default settings for C and C@t{++} 9029* C Checks:: C and C@t{++} type and range checks 9030* Debugging C:: @value{GDBN} and C 9031* Debugging C Plus Plus:: @value{GDBN} features for C@t{++} 9032@end menu 9033 9034@node C Operators 9035@subsubsection C and C@t{++} Operators 9036 9037@cindex C and C@t{++} operators 9038 9039Operators must be defined on values of specific types. For instance, 9040@code{+} is defined on numbers, but not on structures. Operators are 9041often defined on groups of types. 9042 9043For the purposes of C and C@t{++}, the following definitions hold: 9044 9045@itemize @bullet 9046 9047@item 9048@emph{Integral types} include @code{int} with any of its storage-class 9049specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}. 9050 9051@item 9052@emph{Floating-point types} include @code{float}, @code{double}, and 9053@code{long double} (if supported by the target platform). 9054 9055@item 9056@emph{Pointer types} include all types defined as @code{(@var{type} *)}. 9057 9058@item 9059@emph{Scalar types} include all of the above. 9060 9061@end itemize 9062 9063@noindent 9064The following operators are supported. They are listed here 9065in order of increasing precedence: 9066 9067@table @code 9068@item , 9069The comma or sequencing operator. Expressions in a comma-separated list 9070are evaluated from left to right, with the result of the entire 9071expression being the last expression evaluated. 9072 9073@item = 9074Assignment. The value of an assignment expression is the value 9075assigned. Defined on scalar types. 9076 9077@item @var{op}= 9078Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}}, 9079and translated to @w{@code{@var{a} = @var{a op b}}}. 9080@w{@code{@var{op}=}} and @code{=} have the same precedence. 9081@var{op} is any one of the operators @code{|}, @code{^}, @code{&}, 9082@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}. 9083 9084@item ?: 9085The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought 9086of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an 9087integral type. 9088 9089@item || 9090Logical @sc{or}. Defined on integral types. 9091 9092@item && 9093Logical @sc{and}. Defined on integral types. 9094 9095@item | 9096Bitwise @sc{or}. Defined on integral types. 9097 9098@item ^ 9099Bitwise exclusive-@sc{or}. Defined on integral types. 9100 9101@item & 9102Bitwise @sc{and}. Defined on integral types. 9103 9104@item ==@r{, }!= 9105Equality and inequality. Defined on scalar types. The value of these 9106expressions is 0 for false and non-zero for true. 9107 9108@item <@r{, }>@r{, }<=@r{, }>= 9109Less than, greater than, less than or equal, greater than or equal. 9110Defined on scalar types. The value of these expressions is 0 for false 9111and non-zero for true. 9112 9113@item <<@r{, }>> 9114left shift, and right shift. Defined on integral types. 9115 9116@item @@ 9117The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}). 9118 9119@item +@r{, }- 9120Addition and subtraction. Defined on integral types, floating-point types and 9121pointer types. 9122 9123@item *@r{, }/@r{, }% 9124Multiplication, division, and modulus. Multiplication and division are 9125defined on integral and floating-point types. Modulus is defined on 9126integral types. 9127 9128@item ++@r{, }-- 9129Increment and decrement. When appearing before a variable, the 9130operation is performed before the variable is used in an expression; 9131when appearing after it, the variable's value is used before the 9132operation takes place. 9133 9134@item * 9135Pointer dereferencing. Defined on pointer types. Same precedence as 9136@code{++}. 9137 9138@item & 9139Address operator. Defined on variables. Same precedence as @code{++}. 9140 9141For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is 9142allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})} 9143(or, if you prefer, simply @samp{&&@var{ref}}) to examine the address 9144where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is 9145stored. 9146 9147@item - 9148Negative. Defined on integral and floating-point types. Same 9149precedence as @code{++}. 9150 9151@item ! 9152Logical negation. Defined on integral types. Same precedence as 9153@code{++}. 9154 9155@item ~ 9156Bitwise complement operator. Defined on integral types. Same precedence as 9157@code{++}. 9158 9159 9160@item .@r{, }-> 9161Structure member, and pointer-to-structure member. For convenience, 9162@value{GDBN} regards the two as equivalent, choosing whether to dereference a 9163pointer based on the stored type information. 9164Defined on @code{struct} and @code{union} data. 9165 9166@item .*@r{, }->* 9167Dereferences of pointers to members. 9168 9169@item [] 9170Array indexing. @code{@var{a}[@var{i}]} is defined as 9171@code{*(@var{a}+@var{i})}. Same precedence as @code{->}. 9172 9173@item () 9174Function parameter list. Same precedence as @code{->}. 9175 9176@item :: 9177C@t{++} scope resolution operator. Defined on @code{struct}, @code{union}, 9178and @code{class} types. 9179 9180@item :: 9181Doubled colons also represent the @value{GDBN} scope operator 9182(@pxref{Expressions, ,Expressions}). Same precedence as @code{::}, 9183above. 9184@end table 9185 9186If an operator is redefined in the user code, @value{GDBN} usually 9187attempts to invoke the redefined version instead of using the operator's 9188predefined meaning. 9189 9190@node C Constants 9191@subsubsection C and C@t{++} Constants 9192 9193@cindex C and C@t{++} constants 9194 9195@value{GDBN} allows you to express the constants of C and C@t{++} in the 9196following ways: 9197 9198@itemize @bullet 9199@item 9200Integer constants are a sequence of digits. Octal constants are 9201specified by a leading @samp{0} (i.e.@: zero), and hexadecimal constants 9202by a leading @samp{0x} or @samp{0X}. Constants may also end with a letter 9203@samp{l}, specifying that the constant should be treated as a 9204@code{long} value. 9205 9206@item 9207Floating point constants are a sequence of digits, followed by a decimal 9208point, followed by a sequence of digits, and optionally followed by an 9209exponent. An exponent is of the form: 9210@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another 9211sequence of digits. The @samp{+} is optional for positive exponents. 9212A floating-point constant may also end with a letter @samp{f} or 9213@samp{F}, specifying that the constant should be treated as being of 9214the @code{float} (as opposed to the default @code{double}) type; or with 9215a letter @samp{l} or @samp{L}, which specifies a @code{long double} 9216constant. 9217 9218@item 9219Enumerated constants consist of enumerated identifiers, or their 9220integral equivalents. 9221 9222@item 9223Character constants are a single character surrounded by single quotes 9224(@code{'}), or a number---the ordinal value of the corresponding character 9225(usually its @sc{ascii} value). Within quotes, the single character may 9226be represented by a letter or by @dfn{escape sequences}, which are of 9227the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation 9228of the character's ordinal value; or of the form @samp{\@var{x}}, where 9229@samp{@var{x}} is a predefined special character---for example, 9230@samp{\n} for newline. 9231 9232@item 9233String constants are a sequence of character constants surrounded by 9234double quotes (@code{"}). Any valid character constant (as described 9235above) may appear. Double quotes within the string must be preceded by 9236a backslash, so for instance @samp{"a\"b'c"} is a string of five 9237characters. 9238 9239@item 9240Pointer constants are an integral value. You can also write pointers 9241to constants using the C operator @samp{&}. 9242 9243@item 9244Array constants are comma-separated lists surrounded by braces @samp{@{} 9245and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of 9246integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array, 9247and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers. 9248@end itemize 9249 9250@node C Plus Plus Expressions 9251@subsubsection C@t{++} Expressions 9252 9253@cindex expressions in C@t{++} 9254@value{GDBN} expression handling can interpret most C@t{++} expressions. 9255 9256@cindex debugging C@t{++} programs 9257@cindex C@t{++} compilers 9258@cindex debug formats and C@t{++} 9259@cindex @value{NGCC} and C@t{++} 9260@quotation 9261@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the 9262proper compiler and the proper debug format. Currently, @value{GDBN} 9263works best when debugging C@t{++} code that is compiled with 9264@value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options 9265@option{-gdwarf-2} or @option{-gstabs+}. DWARF 2 is preferred over 9266stabs+. Most configurations of @value{NGCC} emit either DWARF 2 or 9267stabs+ as their default debug format, so you usually don't need to 9268specify a debug format explicitly. Other compilers and/or debug formats 9269are likely to work badly or not at all when using @value{GDBN} to debug 9270C@t{++} code. 9271@end quotation 9272 9273@enumerate 9274 9275@cindex member functions 9276@item 9277Member function calls are allowed; you can use expressions like 9278 9279@smallexample 9280count = aml->GetOriginal(x, y) 9281@end smallexample 9282 9283@vindex this@r{, inside C@t{++} member functions} 9284@cindex namespace in C@t{++} 9285@item 9286While a member function is active (in the selected stack frame), your 9287expressions have the same namespace available as the member function; 9288that is, @value{GDBN} allows implicit references to the class instance 9289pointer @code{this} following the same rules as C@t{++}. 9290 9291@cindex call overloaded functions 9292@cindex overloaded functions, calling 9293@cindex type conversions in C@t{++} 9294@item 9295You can call overloaded functions; @value{GDBN} resolves the function 9296call to the right definition, with some restrictions. @value{GDBN} does not 9297perform overload resolution involving user-defined type conversions, 9298calls to constructors, or instantiations of templates that do not exist 9299in the program. It also cannot handle ellipsis argument lists or 9300default arguments. 9301 9302It does perform integral conversions and promotions, floating-point 9303promotions, arithmetic conversions, pointer conversions, conversions of 9304class objects to base classes, and standard conversions such as those of 9305functions or arrays to pointers; it requires an exact match on the 9306number of function arguments. 9307 9308Overload resolution is always performed, unless you have specified 9309@code{set overload-resolution off}. @xref{Debugging C Plus Plus, 9310,@value{GDBN} Features for C@t{++}}. 9311 9312You must specify @code{set overload-resolution off} in order to use an 9313explicit function signature to call an overloaded function, as in 9314@smallexample 9315p 'foo(char,int)'('x', 13) 9316@end smallexample 9317 9318The @value{GDBN} command-completion facility can simplify this; 9319see @ref{Completion, ,Command Completion}. 9320 9321@cindex reference declarations 9322@item 9323@value{GDBN} understands variables declared as C@t{++} references; you can use 9324them in expressions just as you do in C@t{++} source---they are automatically 9325dereferenced. 9326 9327In the parameter list shown when @value{GDBN} displays a frame, the values of 9328reference variables are not displayed (unlike other variables); this 9329avoids clutter, since references are often used for large structures. 9330The @emph{address} of a reference variable is always shown, unless 9331you have specified @samp{set print address off}. 9332 9333@item 9334@value{GDBN} supports the C@t{++} name resolution operator @code{::}---your 9335expressions can use it just as expressions in your program do. Since 9336one scope may be defined in another, you can use @code{::} repeatedly if 9337necessary, for example in an expression like 9338@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows 9339resolving name scope by reference to source files, in both C and C@t{++} 9340debugging (@pxref{Variables, ,Program Variables}). 9341@end enumerate 9342 9343In addition, when used with HP's C@t{++} compiler, @value{GDBN} supports 9344calling virtual functions correctly, printing out virtual bases of 9345objects, calling functions in a base subobject, casting objects, and 9346invoking user-defined operators. 9347 9348@node C Defaults 9349@subsubsection C and C@t{++} Defaults 9350 9351@cindex C and C@t{++} defaults 9352 9353If you allow @value{GDBN} to set type and range checking automatically, they 9354both default to @code{off} whenever the working language changes to 9355C or C@t{++}. This happens regardless of whether you or @value{GDBN} 9356selects the working language. 9357 9358If you allow @value{GDBN} to set the language automatically, it 9359recognizes source files whose names end with @file{.c}, @file{.C}, or 9360@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of 9361these files, it sets the working language to C or C@t{++}. 9362@xref{Automatically, ,Having @value{GDBN} Infer the Source Language}, 9363for further details. 9364 9365@c Type checking is (a) primarily motivated by Modula-2, and (b) 9366@c unimplemented. If (b) changes, it might make sense to let this node 9367@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93. 9368 9369@node C Checks 9370@subsubsection C and C@t{++} Type and Range Checks 9371 9372@cindex C and C@t{++} checks 9373 9374By default, when @value{GDBN} parses C or C@t{++} expressions, type checking 9375is not used. However, if you turn type checking on, @value{GDBN} 9376considers two variables type equivalent if: 9377 9378@itemize @bullet 9379@item 9380The two variables are structured and have the same structure, union, or 9381enumerated tag. 9382 9383@item 9384The two variables have the same type name, or types that have been 9385declared equivalent through @code{typedef}. 9386 9387@ignore 9388@c leaving this out because neither J Gilmore nor R Pesch understand it. 9389@c FIXME--beers? 9390@item 9391The two @code{struct}, @code{union}, or @code{enum} variables are 9392declared in the same declaration. (Note: this may not be true for all C 9393compilers.) 9394@end ignore 9395@end itemize 9396 9397Range checking, if turned on, is done on mathematical operations. Array 9398indices are not checked, since they are often used to index a pointer 9399that is not itself an array. 9400 9401@node Debugging C 9402@subsubsection @value{GDBN} and C 9403 9404The @code{set print union} and @code{show print union} commands apply to 9405the @code{union} type. When set to @samp{on}, any @code{union} that is 9406inside a @code{struct} or @code{class} is also printed. Otherwise, it 9407appears as @samp{@{...@}}. 9408 9409The @code{@@} operator aids in the debugging of dynamic arrays, formed 9410with pointers and a memory allocation function. @xref{Expressions, 9411,Expressions}. 9412 9413@node Debugging C Plus Plus 9414@subsubsection @value{GDBN} Features for C@t{++} 9415 9416@cindex commands for C@t{++} 9417 9418Some @value{GDBN} commands are particularly useful with C@t{++}, and some are 9419designed specifically for use with C@t{++}. Here is a summary: 9420 9421@table @code 9422@cindex break in overloaded functions 9423@item @r{breakpoint menus} 9424When you want a breakpoint in a function whose name is overloaded, 9425@value{GDBN} breakpoint menus help you specify which function definition 9426you want. @xref{Breakpoint Menus,,Breakpoint Menus}. 9427 9428@cindex overloading in C@t{++} 9429@item rbreak @var{regex} 9430Setting breakpoints using regular expressions is helpful for setting 9431breakpoints on overloaded functions that are not members of any special 9432classes. 9433@xref{Set Breaks, ,Setting Breakpoints}. 9434 9435@cindex C@t{++} exception handling 9436@item catch throw 9437@itemx catch catch 9438Debug C@t{++} exception handling using these commands. @xref{Set 9439Catchpoints, , Setting Catchpoints}. 9440 9441@cindex inheritance 9442@item ptype @var{typename} 9443Print inheritance relationships as well as other information for type 9444@var{typename}. 9445@xref{Symbols, ,Examining the Symbol Table}. 9446 9447@cindex C@t{++} symbol display 9448@item set print demangle 9449@itemx show print demangle 9450@itemx set print asm-demangle 9451@itemx show print asm-demangle 9452Control whether C@t{++} symbols display in their source form, both when 9453displaying code as C@t{++} source and when displaying disassemblies. 9454@xref{Print Settings, ,Print Settings}. 9455 9456@item set print object 9457@itemx show print object 9458Choose whether to print derived (actual) or declared types of objects. 9459@xref{Print Settings, ,Print Settings}. 9460 9461@item set print vtbl 9462@itemx show print vtbl 9463Control the format for printing virtual function tables. 9464@xref{Print Settings, ,Print Settings}. 9465(The @code{vtbl} commands do not work on programs compiled with the HP 9466ANSI C@t{++} compiler (@code{aCC}).) 9467 9468@kindex set overload-resolution 9469@cindex overloaded functions, overload resolution 9470@item set overload-resolution on 9471Enable overload resolution for C@t{++} expression evaluation. The default 9472is on. For overloaded functions, @value{GDBN} evaluates the arguments 9473and searches for a function whose signature matches the argument types, 9474using the standard C@t{++} conversion rules (see @ref{C Plus Plus 9475Expressions, ,C@t{++} Expressions}, for details). 9476If it cannot find a match, it emits a message. 9477 9478@item set overload-resolution off 9479Disable overload resolution for C@t{++} expression evaluation. For 9480overloaded functions that are not class member functions, @value{GDBN} 9481chooses the first function of the specified name that it finds in the 9482symbol table, whether or not its arguments are of the correct type. For 9483overloaded functions that are class member functions, @value{GDBN} 9484searches for a function whose signature @emph{exactly} matches the 9485argument types. 9486 9487@kindex show overload-resolution 9488@item show overload-resolution 9489Show the current setting of overload resolution. 9490 9491@item @r{Overloaded symbol names} 9492You can specify a particular definition of an overloaded symbol, using 9493the same notation that is used to declare such symbols in C@t{++}: type 9494@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can 9495also use the @value{GDBN} command-line word completion facilities to list the 9496available choices, or to finish the type list for you. 9497@xref{Completion,, Command Completion}, for details on how to do this. 9498@end table 9499 9500@node Objective-C 9501@subsection Objective-C 9502 9503@cindex Objective-C 9504This section provides information about some commands and command 9505options that are useful for debugging Objective-C code. See also 9506@ref{Symbols, info classes}, and @ref{Symbols, info selectors}, for a 9507few more commands specific to Objective-C support. 9508 9509@menu 9510* Method Names in Commands:: 9511* The Print Command with Objective-C:: 9512@end menu 9513 9514@node Method Names in Commands 9515@subsubsection Method Names in Commands 9516 9517The following commands have been extended to accept Objective-C method 9518names as line specifications: 9519 9520@kindex clear@r{, and Objective-C} 9521@kindex break@r{, and Objective-C} 9522@kindex info line@r{, and Objective-C} 9523@kindex jump@r{, and Objective-C} 9524@kindex list@r{, and Objective-C} 9525@itemize 9526@item @code{clear} 9527@item @code{break} 9528@item @code{info line} 9529@item @code{jump} 9530@item @code{list} 9531@end itemize 9532 9533A fully qualified Objective-C method name is specified as 9534 9535@smallexample 9536-[@var{Class} @var{methodName}] 9537@end smallexample 9538 9539where the minus sign is used to indicate an instance method and a 9540plus sign (not shown) is used to indicate a class method. The class 9541name @var{Class} and method name @var{methodName} are enclosed in 9542brackets, similar to the way messages are specified in Objective-C 9543source code. For example, to set a breakpoint at the @code{create} 9544instance method of class @code{Fruit} in the program currently being 9545debugged, enter: 9546 9547@smallexample 9548break -[Fruit create] 9549@end smallexample 9550 9551To list ten program lines around the @code{initialize} class method, 9552enter: 9553 9554@smallexample 9555list +[NSText initialize] 9556@end smallexample 9557 9558In the current version of @value{GDBN}, the plus or minus sign is 9559required. In future versions of @value{GDBN}, the plus or minus 9560sign will be optional, but you can use it to narrow the search. It 9561is also possible to specify just a method name: 9562 9563@smallexample 9564break create 9565@end smallexample 9566 9567You must specify the complete method name, including any colons. If 9568your program's source files contain more than one @code{create} method, 9569you'll be presented with a numbered list of classes that implement that 9570method. Indicate your choice by number, or type @samp{0} to exit if 9571none apply. 9572 9573As another example, to clear a breakpoint established at the 9574@code{makeKeyAndOrderFront:} method of the @code{NSWindow} class, enter: 9575 9576@smallexample 9577clear -[NSWindow makeKeyAndOrderFront:] 9578@end smallexample 9579 9580@node The Print Command with Objective-C 9581@subsubsection The Print Command With Objective-C 9582@cindex Objective-C, print objects 9583@kindex print-object 9584@kindex po @r{(@code{print-object})} 9585 9586The print command has also been extended to accept methods. For example: 9587 9588@smallexample 9589print -[@var{object} hash] 9590@end smallexample 9591 9592@cindex print an Objective-C object description 9593@cindex @code{_NSPrintForDebugger}, and printing Objective-C objects 9594@noindent 9595will tell @value{GDBN} to send the @code{hash} message to @var{object} 9596and print the result. Also, an additional command has been added, 9597@code{print-object} or @code{po} for short, which is meant to print 9598the description of an object. However, this command may only work 9599with certain Objective-C libraries that have a particular hook 9600function, @code{_NSPrintForDebugger}, defined. 9601 9602@node Fortran 9603@subsection Fortran 9604@cindex Fortran-specific support in @value{GDBN} 9605 9606@value{GDBN} can be used to debug programs written in Fortran, but it 9607currently supports only the features of Fortran 77 language. 9608 9609@cindex trailing underscore, in Fortran symbols 9610Some Fortran compilers (@sc{gnu} Fortran 77 and Fortran 95 compilers 9611among them) append an underscore to the names of variables and 9612functions. When you debug programs compiled by those compilers, you 9613will need to refer to variables and functions with a trailing 9614underscore. 9615 9616@menu 9617* Fortran Operators:: Fortran operators and expressions 9618* Fortran Defaults:: Default settings for Fortran 9619* Special Fortran Commands:: Special @value{GDBN} commands for Fortran 9620@end menu 9621 9622@node Fortran Operators 9623@subsubsection Fortran Operators and Expressions 9624 9625@cindex Fortran operators and expressions 9626 9627Operators must be defined on values of specific types. For instance, 9628@code{+} is defined on numbers, but not on characters or other non- 9629arithmetic types. Operators are often defined on groups of types. 9630 9631@table @code 9632@item ** 9633The exponentiation operator. It raises the first operand to the power 9634of the second one. 9635 9636@item : 9637The range operator. Normally used in the form of array(low:high) to 9638represent a section of array. 9639@end table 9640 9641@node Fortran Defaults 9642@subsubsection Fortran Defaults 9643 9644@cindex Fortran Defaults 9645 9646Fortran symbols are usually case-insensitive, so @value{GDBN} by 9647default uses case-insensitive matches for Fortran symbols. You can 9648change that with the @samp{set case-insensitive} command, see 9649@ref{Symbols}, for the details. 9650 9651@node Special Fortran Commands 9652@subsubsection Special Fortran Commands 9653 9654@cindex Special Fortran commands 9655 9656@value{GDBN} has some commands to support Fortran-specific features, 9657such as displaying common blocks. 9658 9659@table @code 9660@cindex @code{COMMON} blocks, Fortran 9661@kindex info common 9662@item info common @r{[}@var{common-name}@r{]} 9663This command prints the values contained in the Fortran @code{COMMON} 9664block whose name is @var{common-name}. With no argument, the names of 9665all @code{COMMON} blocks visible at the current program location are 9666printed. 9667@end table 9668 9669@node Pascal 9670@subsection Pascal 9671 9672@cindex Pascal support in @value{GDBN}, limitations 9673Debugging Pascal programs which use sets, subranges, file variables, or 9674nested functions does not currently work. @value{GDBN} does not support 9675entering expressions, printing values, or similar features using Pascal 9676syntax. 9677 9678The Pascal-specific command @code{set print pascal_static-members} 9679controls whether static members of Pascal objects are displayed. 9680@xref{Print Settings, pascal_static-members}. 9681 9682@node Modula-2 9683@subsection Modula-2 9684 9685@cindex Modula-2, @value{GDBN} support 9686 9687The extensions made to @value{GDBN} to support Modula-2 only support 9688output from the @sc{gnu} Modula-2 compiler (which is currently being 9689developed). Other Modula-2 compilers are not currently supported, and 9690attempting to debug executables produced by them is most likely 9691to give an error as @value{GDBN} reads in the executable's symbol 9692table. 9693 9694@cindex expressions in Modula-2 9695@menu 9696* M2 Operators:: Built-in operators 9697* Built-In Func/Proc:: Built-in functions and procedures 9698* M2 Constants:: Modula-2 constants 9699* M2 Types:: Modula-2 types 9700* M2 Defaults:: Default settings for Modula-2 9701* Deviations:: Deviations from standard Modula-2 9702* M2 Checks:: Modula-2 type and range checks 9703* M2 Scope:: The scope operators @code{::} and @code{.} 9704* GDB/M2:: @value{GDBN} and Modula-2 9705@end menu 9706 9707@node M2 Operators 9708@subsubsection Operators 9709@cindex Modula-2 operators 9710 9711Operators must be defined on values of specific types. For instance, 9712@code{+} is defined on numbers, but not on structures. Operators are 9713often defined on groups of types. For the purposes of Modula-2, the 9714following definitions hold: 9715 9716@itemize @bullet 9717 9718@item 9719@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and 9720their subranges. 9721 9722@item 9723@emph{Character types} consist of @code{CHAR} and its subranges. 9724 9725@item 9726@emph{Floating-point types} consist of @code{REAL}. 9727 9728@item 9729@emph{Pointer types} consist of anything declared as @code{POINTER TO 9730@var{type}}. 9731 9732@item 9733@emph{Scalar types} consist of all of the above. 9734 9735@item 9736@emph{Set types} consist of @code{SET} and @code{BITSET} types. 9737 9738@item 9739@emph{Boolean types} consist of @code{BOOLEAN}. 9740@end itemize 9741 9742@noindent 9743The following operators are supported, and appear in order of 9744increasing precedence: 9745 9746@table @code 9747@item , 9748Function argument or array index separator. 9749 9750@item := 9751Assignment. The value of @var{var} @code{:=} @var{value} is 9752@var{value}. 9753 9754@item <@r{, }> 9755Less than, greater than on integral, floating-point, or enumerated 9756types. 9757 9758@item <=@r{, }>= 9759Less than or equal to, greater than or equal to 9760on integral, floating-point and enumerated types, or set inclusion on 9761set types. Same precedence as @code{<}. 9762 9763@item =@r{, }<>@r{, }# 9764Equality and two ways of expressing inequality, valid on scalar types. 9765Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is 9766available for inequality, since @code{#} conflicts with the script 9767comment character. 9768 9769@item IN 9770Set membership. Defined on set types and the types of their members. 9771Same precedence as @code{<}. 9772 9773@item OR 9774Boolean disjunction. Defined on boolean types. 9775 9776@item AND@r{, }& 9777Boolean conjunction. Defined on boolean types. 9778 9779@item @@ 9780The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}). 9781 9782@item +@r{, }- 9783Addition and subtraction on integral and floating-point types, or union 9784and difference on set types. 9785 9786@item * 9787Multiplication on integral and floating-point types, or set intersection 9788on set types. 9789 9790@item / 9791Division on floating-point types, or symmetric set difference on set 9792types. Same precedence as @code{*}. 9793 9794@item DIV@r{, }MOD 9795Integer division and remainder. Defined on integral types. Same 9796precedence as @code{*}. 9797 9798@item - 9799Negative. Defined on @code{INTEGER} and @code{REAL} data. 9800 9801@item ^ 9802Pointer dereferencing. Defined on pointer types. 9803 9804@item NOT 9805Boolean negation. Defined on boolean types. Same precedence as 9806@code{^}. 9807 9808@item . 9809@code{RECORD} field selector. Defined on @code{RECORD} data. Same 9810precedence as @code{^}. 9811 9812@item [] 9813Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}. 9814 9815@item () 9816Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence 9817as @code{^}. 9818 9819@item ::@r{, }. 9820@value{GDBN} and Modula-2 scope operators. 9821@end table 9822 9823@quotation 9824@emph{Warning:} Set expressions and their operations are not yet supported, so @value{GDBN} 9825treats the use of the operator @code{IN}, or the use of operators 9826@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#}, 9827@code{<=}, and @code{>=} on sets as an error. 9828@end quotation 9829 9830 9831@node Built-In Func/Proc 9832@subsubsection Built-in Functions and Procedures 9833@cindex Modula-2 built-ins 9834 9835Modula-2 also makes available several built-in procedures and functions. 9836In describing these, the following metavariables are used: 9837 9838@table @var 9839 9840@item a 9841represents an @code{ARRAY} variable. 9842 9843@item c 9844represents a @code{CHAR} constant or variable. 9845 9846@item i 9847represents a variable or constant of integral type. 9848 9849@item m 9850represents an identifier that belongs to a set. Generally used in the 9851same function with the metavariable @var{s}. The type of @var{s} should 9852be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}). 9853 9854@item n 9855represents a variable or constant of integral or floating-point type. 9856 9857@item r 9858represents a variable or constant of floating-point type. 9859 9860@item t 9861represents a type. 9862 9863@item v 9864represents a variable. 9865 9866@item x 9867represents a variable or constant of one of many types. See the 9868explanation of the function for details. 9869@end table 9870 9871All Modula-2 built-in procedures also return a result, described below. 9872 9873@table @code 9874@item ABS(@var{n}) 9875Returns the absolute value of @var{n}. 9876 9877@item CAP(@var{c}) 9878If @var{c} is a lower case letter, it returns its upper case 9879equivalent, otherwise it returns its argument. 9880 9881@item CHR(@var{i}) 9882Returns the character whose ordinal value is @var{i}. 9883 9884@item DEC(@var{v}) 9885Decrements the value in the variable @var{v} by one. Returns the new value. 9886 9887@item DEC(@var{v},@var{i}) 9888Decrements the value in the variable @var{v} by @var{i}. Returns the 9889new value. 9890 9891@item EXCL(@var{m},@var{s}) 9892Removes the element @var{m} from the set @var{s}. Returns the new 9893set. 9894 9895@item FLOAT(@var{i}) 9896Returns the floating point equivalent of the integer @var{i}. 9897 9898@item HIGH(@var{a}) 9899Returns the index of the last member of @var{a}. 9900 9901@item INC(@var{v}) 9902Increments the value in the variable @var{v} by one. Returns the new value. 9903 9904@item INC(@var{v},@var{i}) 9905Increments the value in the variable @var{v} by @var{i}. Returns the 9906new value. 9907 9908@item INCL(@var{m},@var{s}) 9909Adds the element @var{m} to the set @var{s} if it is not already 9910there. Returns the new set. 9911 9912@item MAX(@var{t}) 9913Returns the maximum value of the type @var{t}. 9914 9915@item MIN(@var{t}) 9916Returns the minimum value of the type @var{t}. 9917 9918@item ODD(@var{i}) 9919Returns boolean TRUE if @var{i} is an odd number. 9920 9921@item ORD(@var{x}) 9922Returns the ordinal value of its argument. For example, the ordinal 9923value of a character is its @sc{ascii} value (on machines supporting the 9924@sc{ascii} character set). @var{x} must be of an ordered type, which include 9925integral, character and enumerated types. 9926 9927@item SIZE(@var{x}) 9928Returns the size of its argument. @var{x} can be a variable or a type. 9929 9930@item TRUNC(@var{r}) 9931Returns the integral part of @var{r}. 9932 9933@item VAL(@var{t},@var{i}) 9934Returns the member of the type @var{t} whose ordinal value is @var{i}. 9935@end table 9936 9937@quotation 9938@emph{Warning:} Sets and their operations are not yet supported, so 9939@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as 9940an error. 9941@end quotation 9942 9943@cindex Modula-2 constants 9944@node M2 Constants 9945@subsubsection Constants 9946 9947@value{GDBN} allows you to express the constants of Modula-2 in the following 9948ways: 9949 9950@itemize @bullet 9951 9952@item 9953Integer constants are simply a sequence of digits. When used in an 9954expression, a constant is interpreted to be type-compatible with the 9955rest of the expression. Hexadecimal integers are specified by a 9956trailing @samp{H}, and octal integers by a trailing @samp{B}. 9957 9958@item 9959Floating point constants appear as a sequence of digits, followed by a 9960decimal point and another sequence of digits. An optional exponent can 9961then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where 9962@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the 9963digits of the floating point constant must be valid decimal (base 10) 9964digits. 9965 9966@item 9967Character constants consist of a single character enclosed by a pair of 9968like quotes, either single (@code{'}) or double (@code{"}). They may 9969also be expressed by their ordinal value (their @sc{ascii} value, usually) 9970followed by a @samp{C}. 9971 9972@item 9973String constants consist of a sequence of characters enclosed by a 9974pair of like quotes, either single (@code{'}) or double (@code{"}). 9975Escape sequences in the style of C are also allowed. @xref{C 9976Constants, ,C and C@t{++} Constants}, for a brief explanation of escape 9977sequences. 9978 9979@item 9980Enumerated constants consist of an enumerated identifier. 9981 9982@item 9983Boolean constants consist of the identifiers @code{TRUE} and 9984@code{FALSE}. 9985 9986@item 9987Pointer constants consist of integral values only. 9988 9989@item 9990Set constants are not yet supported. 9991@end itemize 9992 9993@node M2 Types 9994@subsubsection Modula-2 Types 9995@cindex Modula-2 types 9996 9997Currently @value{GDBN} can print the following data types in Modula-2 9998syntax: array types, record types, set types, pointer types, procedure 9999types, enumerated types, subrange types and base types. You can also 10000print the contents of variables declared using these type. 10001This section gives a number of simple source code examples together with 10002sample @value{GDBN} sessions. 10003 10004The first example contains the following section of code: 10005 10006@smallexample 10007VAR 10008 s: SET OF CHAR ; 10009 r: [20..40] ; 10010@end smallexample 10011 10012@noindent 10013and you can request @value{GDBN} to interrogate the type and value of 10014@code{r} and @code{s}. 10015 10016@smallexample 10017(@value{GDBP}) print s 10018@{'A'..'C', 'Z'@} 10019(@value{GDBP}) ptype s 10020SET OF CHAR 10021(@value{GDBP}) print r 1002221 10023(@value{GDBP}) ptype r 10024[20..40] 10025@end smallexample 10026 10027@noindent 10028Likewise if your source code declares @code{s} as: 10029 10030@smallexample 10031VAR 10032 s: SET ['A'..'Z'] ; 10033@end smallexample 10034 10035@noindent 10036then you may query the type of @code{s} by: 10037 10038@smallexample 10039(@value{GDBP}) ptype s 10040type = SET ['A'..'Z'] 10041@end smallexample 10042 10043@noindent 10044Note that at present you cannot interactively manipulate set 10045expressions using the debugger. 10046 10047The following example shows how you might declare an array in Modula-2 10048and how you can interact with @value{GDBN} to print its type and contents: 10049 10050@smallexample 10051VAR 10052 s: ARRAY [-10..10] OF CHAR ; 10053@end smallexample 10054 10055@smallexample 10056(@value{GDBP}) ptype s 10057ARRAY [-10..10] OF CHAR 10058@end smallexample 10059 10060Note that the array handling is not yet complete and although the type 10061is printed correctly, expression handling still assumes that all 10062arrays have a lower bound of zero and not @code{-10} as in the example 10063above. Unbounded arrays are also not yet recognized in @value{GDBN}. 10064 10065Here are some more type related Modula-2 examples: 10066 10067@smallexample 10068TYPE 10069 colour = (blue, red, yellow, green) ; 10070 t = [blue..yellow] ; 10071VAR 10072 s: t ; 10073BEGIN 10074 s := blue ; 10075@end smallexample 10076 10077@noindent 10078The @value{GDBN} interaction shows how you can query the data type 10079and value of a variable. 10080 10081@smallexample 10082(@value{GDBP}) print s 10083$1 = blue 10084(@value{GDBP}) ptype t 10085type = [blue..yellow] 10086@end smallexample 10087 10088@noindent 10089In this example a Modula-2 array is declared and its contents 10090displayed. Observe that the contents are written in the same way as 10091their @code{C} counterparts. 10092 10093@smallexample 10094VAR 10095 s: ARRAY [1..5] OF CARDINAL ; 10096BEGIN 10097 s[1] := 1 ; 10098@end smallexample 10099 10100@smallexample 10101(@value{GDBP}) print s 10102$1 = @{1, 0, 0, 0, 0@} 10103(@value{GDBP}) ptype s 10104type = ARRAY [1..5] OF CARDINAL 10105@end smallexample 10106 10107The Modula-2 language interface to @value{GDBN} also understands 10108pointer types as shown in this example: 10109 10110@smallexample 10111VAR 10112 s: POINTER TO ARRAY [1..5] OF CARDINAL ; 10113BEGIN 10114 NEW(s) ; 10115 s^[1] := 1 ; 10116@end smallexample 10117 10118@noindent 10119and you can request that @value{GDBN} describes the type of @code{s}. 10120 10121@smallexample 10122(@value{GDBP}) ptype s 10123type = POINTER TO ARRAY [1..5] OF CARDINAL 10124@end smallexample 10125 10126@value{GDBN} handles compound types as we can see in this example. 10127Here we combine array types, record types, pointer types and subrange 10128types: 10129 10130@smallexample 10131TYPE 10132 foo = RECORD 10133 f1: CARDINAL ; 10134 f2: CHAR ; 10135 f3: myarray ; 10136 END ; 10137 10138 myarray = ARRAY myrange OF CARDINAL ; 10139 myrange = [-2..2] ; 10140VAR 10141 s: POINTER TO ARRAY myrange OF foo ; 10142@end smallexample 10143 10144@noindent 10145and you can ask @value{GDBN} to describe the type of @code{s} as shown 10146below. 10147 10148@smallexample 10149(@value{GDBP}) ptype s 10150type = POINTER TO ARRAY [-2..2] OF foo = RECORD 10151 f1 : CARDINAL; 10152 f2 : CHAR; 10153 f3 : ARRAY [-2..2] OF CARDINAL; 10154END 10155@end smallexample 10156 10157@node M2 Defaults 10158@subsubsection Modula-2 Defaults 10159@cindex Modula-2 defaults 10160 10161If type and range checking are set automatically by @value{GDBN}, they 10162both default to @code{on} whenever the working language changes to 10163Modula-2. This happens regardless of whether you or @value{GDBN} 10164selected the working language. 10165 10166If you allow @value{GDBN} to set the language automatically, then entering 10167code compiled from a file whose name ends with @file{.mod} sets the 10168working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} 10169Infer the Source Language}, for further details. 10170 10171@node Deviations 10172@subsubsection Deviations from Standard Modula-2 10173@cindex Modula-2, deviations from 10174 10175A few changes have been made to make Modula-2 programs easier to debug. 10176This is done primarily via loosening its type strictness: 10177 10178@itemize @bullet 10179@item 10180Unlike in standard Modula-2, pointer constants can be formed by 10181integers. This allows you to modify pointer variables during 10182debugging. (In standard Modula-2, the actual address contained in a 10183pointer variable is hidden from you; it can only be modified 10184through direct assignment to another pointer variable or expression that 10185returned a pointer.) 10186 10187@item 10188C escape sequences can be used in strings and characters to represent 10189non-printable characters. @value{GDBN} prints out strings with these 10190escape sequences embedded. Single non-printable characters are 10191printed using the @samp{CHR(@var{nnn})} format. 10192 10193@item 10194The assignment operator (@code{:=}) returns the value of its right-hand 10195argument. 10196 10197@item 10198All built-in procedures both modify @emph{and} return their argument. 10199@end itemize 10200 10201@node M2 Checks 10202@subsubsection Modula-2 Type and Range Checks 10203@cindex Modula-2 checks 10204 10205@quotation 10206@emph{Warning:} in this release, @value{GDBN} does not yet perform type or 10207range checking. 10208@end quotation 10209@c FIXME remove warning when type/range checks added 10210 10211@value{GDBN} considers two Modula-2 variables type equivalent if: 10212 10213@itemize @bullet 10214@item 10215They are of types that have been declared equivalent via a @code{TYPE 10216@var{t1} = @var{t2}} statement 10217 10218@item 10219They have been declared on the same line. (Note: This is true of the 10220@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.) 10221@end itemize 10222 10223As long as type checking is enabled, any attempt to combine variables 10224whose types are not equivalent is an error. 10225 10226Range checking is done on all mathematical operations, assignment, array 10227index bounds, and all built-in functions and procedures. 10228 10229@node M2 Scope 10230@subsubsection The Scope Operators @code{::} and @code{.} 10231@cindex scope 10232@cindex @code{.}, Modula-2 scope operator 10233@cindex colon, doubled as scope operator 10234@ifinfo 10235@vindex colon-colon@r{, in Modula-2} 10236@c Info cannot handle :: but TeX can. 10237@end ifinfo 10238@iftex 10239@vindex ::@r{, in Modula-2} 10240@end iftex 10241 10242There are a few subtle differences between the Modula-2 scope operator 10243(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have 10244similar syntax: 10245 10246@smallexample 10247 10248@var{module} . @var{id} 10249@var{scope} :: @var{id} 10250@end smallexample 10251 10252@noindent 10253where @var{scope} is the name of a module or a procedure, 10254@var{module} the name of a module, and @var{id} is any declared 10255identifier within your program, except another module. 10256 10257Using the @code{::} operator makes @value{GDBN} search the scope 10258specified by @var{scope} for the identifier @var{id}. If it is not 10259found in the specified scope, then @value{GDBN} searches all scopes 10260enclosing the one specified by @var{scope}. 10261 10262Using the @code{.} operator makes @value{GDBN} search the current scope for 10263the identifier specified by @var{id} that was imported from the 10264definition module specified by @var{module}. With this operator, it is 10265an error if the identifier @var{id} was not imported from definition 10266module @var{module}, or if @var{id} is not an identifier in 10267@var{module}. 10268 10269@node GDB/M2 10270@subsubsection @value{GDBN} and Modula-2 10271 10272Some @value{GDBN} commands have little use when debugging Modula-2 programs. 10273Five subcommands of @code{set print} and @code{show print} apply 10274specifically to C and C@t{++}: @samp{vtbl}, @samp{demangle}, 10275@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four 10276apply to C@t{++}, and the last to the C @code{union} type, which has no direct 10277analogue in Modula-2. 10278 10279The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available 10280with any language, is not useful with Modula-2. Its 10281intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be 10282created in Modula-2 as they can in C or C@t{++}. However, because an 10283address can be specified by an integral constant, the construct 10284@samp{@{@var{type}@}@var{adrexp}} is still useful. 10285 10286@cindex @code{#} in Modula-2 10287In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is 10288interpreted as the beginning of a comment. Use @code{<>} instead. 10289 10290@node Ada 10291@subsection Ada 10292@cindex Ada 10293 10294The extensions made to @value{GDBN} for Ada only support 10295output from the @sc{gnu} Ada (GNAT) compiler. 10296Other Ada compilers are not currently supported, and 10297attempting to debug executables produced by them is most likely 10298to be difficult. 10299 10300 10301@cindex expressions in Ada 10302@menu 10303* Ada Mode Intro:: General remarks on the Ada syntax 10304 and semantics supported by Ada mode 10305 in @value{GDBN}. 10306* Omissions from Ada:: Restrictions on the Ada expression syntax. 10307* Additions to Ada:: Extensions of the Ada expression syntax. 10308* Stopping Before Main Program:: Debugging the program during elaboration. 10309* Ada Glitches:: Known peculiarities of Ada mode. 10310@end menu 10311 10312@node Ada Mode Intro 10313@subsubsection Introduction 10314@cindex Ada mode, general 10315 10316The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression 10317syntax, with some extensions. 10318The philosophy behind the design of this subset is 10319 10320@itemize @bullet 10321@item 10322That @value{GDBN} should provide basic literals and access to operations for 10323arithmetic, dereferencing, field selection, indexing, and subprogram calls, 10324leaving more sophisticated computations to subprograms written into the 10325program (which therefore may be called from @value{GDBN}). 10326 10327@item 10328That type safety and strict adherence to Ada language restrictions 10329are not particularly important to the @value{GDBN} user. 10330 10331@item 10332That brevity is important to the @value{GDBN} user. 10333@end itemize 10334 10335Thus, for brevity, the debugger acts as if there were 10336implicit @code{with} and @code{use} clauses in effect for all user-written 10337packages, making it unnecessary to fully qualify most names with 10338their packages, regardless of context. Where this causes ambiguity, 10339@value{GDBN} asks the user's intent. 10340 10341The debugger will start in Ada mode if it detects an Ada main program. 10342As for other languages, it will enter Ada mode when stopped in a program that 10343was translated from an Ada source file. 10344 10345While in Ada mode, you may use `@t{--}' for comments. This is useful 10346mostly for documenting command files. The standard @value{GDBN} comment 10347(@samp{#}) still works at the beginning of a line in Ada mode, but not in the 10348middle (to allow based literals). 10349 10350The debugger supports limited overloading. Given a subprogram call in which 10351the function symbol has multiple definitions, it will use the number of 10352actual parameters and some information about their types to attempt to narrow 10353the set of definitions. It also makes very limited use of context, preferring 10354procedures to functions in the context of the @code{call} command, and 10355functions to procedures elsewhere. 10356 10357@node Omissions from Ada 10358@subsubsection Omissions from Ada 10359@cindex Ada, omissions from 10360 10361Here are the notable omissions from the subset: 10362 10363@itemize @bullet 10364@item 10365Only a subset of the attributes are supported: 10366 10367@itemize @minus 10368@item 10369@t{'First}, @t{'Last}, and @t{'Length} 10370 on array objects (not on types and subtypes). 10371 10372@item 10373@t{'Min} and @t{'Max}. 10374 10375@item 10376@t{'Pos} and @t{'Val}. 10377 10378@item 10379@t{'Tag}. 10380 10381@item 10382@t{'Range} on array objects (not subtypes), but only as the right 10383operand of the membership (@code{in}) operator. 10384 10385@item 10386@t{'Access}, @t{'Unchecked_Access}, and 10387@t{'Unrestricted_Access} (a GNAT extension). 10388 10389@item 10390@t{'Address}. 10391@end itemize 10392 10393@item 10394The names in 10395@code{Characters.Latin_1} are not available and 10396concatenation is not implemented. Thus, escape characters in strings are 10397not currently available. 10398 10399@item 10400Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise 10401equality of representations. They will generally work correctly 10402for strings and arrays whose elements have integer or enumeration types. 10403They may not work correctly for arrays whose element 10404types have user-defined equality, for arrays of real values 10405(in particular, IEEE-conformant floating point, because of negative 10406zeroes and NaNs), and for arrays whose elements contain unused bits with 10407indeterminate values. 10408 10409@item 10410The other component-by-component array operations (@code{and}, @code{or}, 10411@code{xor}, @code{not}, and relational tests other than equality) 10412are not implemented. 10413 10414@item 10415@cindex array aggregates (Ada) 10416@cindex record aggregates (Ada) 10417@cindex aggregates (Ada) 10418There is limited support for array and record aggregates. They are 10419permitted only on the right sides of assignments, as in these examples: 10420 10421@smallexample 10422set An_Array := (1, 2, 3, 4, 5, 6) 10423set An_Array := (1, others => 0) 10424set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) 10425set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) 10426set A_Record := (1, "Peter", True); 10427set A_Record := (Name => "Peter", Id => 1, Alive => True) 10428@end smallexample 10429 10430Changing a 10431discriminant's value by assigning an aggregate has an 10432undefined effect if that discriminant is used within the record. 10433However, you can first modify discriminants by directly assigning to 10434them (which normally would not be allowed in Ada), and then performing an 10435aggregate assignment. For example, given a variable @code{A_Rec} 10436declared to have a type such as: 10437 10438@smallexample 10439type Rec (Len : Small_Integer := 0) is record 10440 Id : Integer; 10441 Vals : IntArray (1 .. Len); 10442end record; 10443@end smallexample 10444 10445you can assign a value with a different size of @code{Vals} with two 10446assignments: 10447 10448@smallexample 10449set A_Rec.Len := 4 10450set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) 10451@end smallexample 10452 10453As this example also illustrates, @value{GDBN} is very loose about the usual 10454rules concerning aggregates. You may leave out some of the 10455components of an array or record aggregate (such as the @code{Len} 10456component in the assignment to @code{A_Rec} above); they will retain their 10457original values upon assignment. You may freely use dynamic values as 10458indices in component associations. You may even use overlapping or 10459redundant component associations, although which component values are 10460assigned in such cases is not defined. 10461 10462@item 10463Calls to dispatching subprograms are not implemented. 10464 10465@item 10466The overloading algorithm is much more limited (i.e., less selective) 10467than that of real Ada. It makes only limited use of the context in 10468which a subexpression appears to resolve its meaning, and it is much 10469looser in its rules for allowing type matches. As a result, some 10470function calls will be ambiguous, and the user will be asked to choose 10471the proper resolution. 10472 10473@item 10474The @code{new} operator is not implemented. 10475 10476@item 10477Entry calls are not implemented. 10478 10479@item 10480Aside from printing, arithmetic operations on the native VAX floating-point 10481formats are not supported. 10482 10483@item 10484It is not possible to slice a packed array. 10485@end itemize 10486 10487@node Additions to Ada 10488@subsubsection Additions to Ada 10489@cindex Ada, deviations from 10490 10491As it does for other languages, @value{GDBN} makes certain generic 10492extensions to Ada (@pxref{Expressions}): 10493 10494@itemize @bullet 10495@item 10496If the expression @var{E} is a variable residing in memory (typically 10497a local variable or array element) and @var{N} is a positive integer, 10498then @code{@var{E}@@@var{N}} displays the values of @var{E} and the 10499@var{N}-1 adjacent variables following it in memory as an array. In 10500Ada, this operator is generally not necessary, since its prime use is 10501in displaying parts of an array, and slicing will usually do this in 10502Ada. However, there are occasional uses when debugging programs in 10503which certain debugging information has been optimized away. 10504 10505@item 10506@code{@var{B}::@var{var}} means ``the variable named @var{var} that 10507appears in function or file @var{B}.'' When @var{B} is a file name, 10508you must typically surround it in single quotes. 10509 10510@item 10511The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type 10512@var{type} that appears at address @var{addr}.'' 10513 10514@item 10515A name starting with @samp{$} is a convenience variable 10516(@pxref{Convenience Vars}) or a machine register (@pxref{Registers}). 10517@end itemize 10518 10519In addition, @value{GDBN} provides a few other shortcuts and outright 10520additions specific to Ada: 10521 10522@itemize @bullet 10523@item 10524The assignment statement is allowed as an expression, returning 10525its right-hand operand as its value. Thus, you may enter 10526 10527@smallexample 10528set x := y + 3 10529print A(tmp := y + 1) 10530@end smallexample 10531 10532@item 10533The semicolon is allowed as an ``operator,'' returning as its value 10534the value of its right-hand operand. 10535This allows, for example, 10536complex conditional breaks: 10537 10538@smallexample 10539break f 10540condition 1 (report(i); k += 1; A(k) > 100) 10541@end smallexample 10542 10543@item 10544Rather than use catenation and symbolic character names to introduce special 10545characters into strings, one may instead use a special bracket notation, 10546which is also used to print strings. A sequence of characters of the form 10547@samp{["@var{XX}"]} within a string or character literal denotes the 10548(single) character whose numeric encoding is @var{XX} in hexadecimal. The 10549sequence of characters @samp{["""]} also denotes a single quotation mark 10550in strings. For example, 10551@smallexample 10552 "One line.["0a"]Next line.["0a"]" 10553@end smallexample 10554@noindent 10555contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF}) 10556after each period. 10557 10558@item 10559The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and 10560@t{'Max} is optional (and is ignored in any case). For example, it is valid 10561to write 10562 10563@smallexample 10564print 'max(x, y) 10565@end smallexample 10566 10567@item 10568When printing arrays, @value{GDBN} uses positional notation when the 10569array has a lower bound of 1, and uses a modified named notation otherwise. 10570For example, a one-dimensional array of three integers with a lower bound 10571of 3 might print as 10572 10573@smallexample 10574(3 => 10, 17, 1) 10575@end smallexample 10576 10577@noindent 10578That is, in contrast to valid Ada, only the first component has a @code{=>} 10579clause. 10580 10581@item 10582You may abbreviate attributes in expressions with any unique, 10583multi-character subsequence of 10584their names (an exact match gets preference). 10585For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh} 10586in place of @t{a'length}. 10587 10588@item 10589@cindex quoting Ada internal identifiers 10590Since Ada is case-insensitive, the debugger normally maps identifiers you type 10591to lower case. The GNAT compiler uses upper-case characters for 10592some of its internal identifiers, which are normally of no interest to users. 10593For the rare occasions when you actually have to look at them, 10594enclose them in angle brackets to avoid the lower-case mapping. 10595For example, 10596@smallexample 10597@value{GDBP} print <JMPBUF_SAVE>[0] 10598@end smallexample 10599 10600@item 10601Printing an object of class-wide type or dereferencing an 10602access-to-class-wide value will display all the components of the object's 10603specific type (as indicated by its run-time tag). Likewise, component 10604selection on such a value will operate on the specific type of the 10605object. 10606 10607@end itemize 10608 10609@node Stopping Before Main Program 10610@subsubsection Stopping at the Very Beginning 10611 10612@cindex breakpointing Ada elaboration code 10613It is sometimes necessary to debug the program during elaboration, and 10614before reaching the main procedure. 10615As defined in the Ada Reference 10616Manual, the elaboration code is invoked from a procedure called 10617@code{adainit}. To run your program up to the beginning of 10618elaboration, simply use the following two commands: 10619@code{tbreak adainit} and @code{run}. 10620 10621@node Ada Glitches 10622@subsubsection Known Peculiarities of Ada Mode 10623@cindex Ada, problems 10624 10625Besides the omissions listed previously (@pxref{Omissions from Ada}), 10626we know of several problems with and limitations of Ada mode in 10627@value{GDBN}, 10628some of which will be fixed with planned future releases of the debugger 10629and the GNU Ada compiler. 10630 10631@itemize @bullet 10632@item 10633Currently, the debugger 10634has insufficient information to determine whether certain pointers represent 10635pointers to objects or the objects themselves. 10636Thus, the user may have to tack an extra @code{.all} after an expression 10637to get it printed properly. 10638 10639@item 10640Static constants that the compiler chooses not to materialize as objects in 10641storage are invisible to the debugger. 10642 10643@item 10644Named parameter associations in function argument lists are ignored (the 10645argument lists are treated as positional). 10646 10647@item 10648Many useful library packages are currently invisible to the debugger. 10649 10650@item 10651Fixed-point arithmetic, conversions, input, and output is carried out using 10652floating-point arithmetic, and may give results that only approximate those on 10653the host machine. 10654 10655@item 10656The type of the @t{'Address} attribute may not be @code{System.Address}. 10657 10658@item 10659The GNAT compiler never generates the prefix @code{Standard} for any of 10660the standard symbols defined by the Ada language. @value{GDBN} knows about 10661this: it will strip the prefix from names when you use it, and will never 10662look for a name you have so qualified among local symbols, nor match against 10663symbols in other packages or subprograms. If you have 10664defined entities anywhere in your program other than parameters and 10665local variables whose simple names match names in @code{Standard}, 10666GNAT's lack of qualification here can cause confusion. When this happens, 10667you can usually resolve the confusion 10668by qualifying the problematic names with package 10669@code{Standard} explicitly. 10670@end itemize 10671 10672@node Unsupported Languages 10673@section Unsupported Languages 10674 10675@cindex unsupported languages 10676@cindex minimal language 10677In addition to the other fully-supported programming languages, 10678@value{GDBN} also provides a pseudo-language, called @code{minimal}. 10679It does not represent a real programming language, but provides a set 10680of capabilities close to what the C or assembly languages provide. 10681This should allow most simple operations to be performed while debugging 10682an application that uses a language currently not supported by @value{GDBN}. 10683 10684If the language is set to @code{auto}, @value{GDBN} will automatically 10685select this language if the current frame corresponds to an unsupported 10686language. 10687 10688@node Symbols 10689@chapter Examining the Symbol Table 10690 10691The commands described in this chapter allow you to inquire about the 10692symbols (names of variables, functions and types) defined in your 10693program. This information is inherent in the text of your program and 10694does not change as your program executes. @value{GDBN} finds it in your 10695program's symbol table, in the file indicated when you started @value{GDBN} 10696(@pxref{File Options, ,Choosing Files}), or by one of the 10697file-management commands (@pxref{Files, ,Commands to Specify Files}). 10698 10699@cindex symbol names 10700@cindex names of symbols 10701@cindex quoting names 10702Occasionally, you may need to refer to symbols that contain unusual 10703characters, which @value{GDBN} ordinarily treats as word delimiters. The 10704most frequent case is in referring to static variables in other 10705source files (@pxref{Variables,,Program Variables}). File names 10706are recorded in object files as debugging symbols, but @value{GDBN} would 10707ordinarily parse a typical file name, like @file{foo.c}, as the three words 10708@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize 10709@samp{foo.c} as a single symbol, enclose it in single quotes; for example, 10710 10711@smallexample 10712p 'foo.c'::x 10713@end smallexample 10714 10715@noindent 10716looks up the value of @code{x} in the scope of the file @file{foo.c}. 10717 10718@table @code 10719@cindex case-insensitive symbol names 10720@cindex case sensitivity in symbol names 10721@kindex set case-sensitive 10722@item set case-sensitive on 10723@itemx set case-sensitive off 10724@itemx set case-sensitive auto 10725Normally, when @value{GDBN} looks up symbols, it matches their names 10726with case sensitivity determined by the current source language. 10727Occasionally, you may wish to control that. The command @code{set 10728case-sensitive} lets you do that by specifying @code{on} for 10729case-sensitive matches or @code{off} for case-insensitive ones. If 10730you specify @code{auto}, case sensitivity is reset to the default 10731suitable for the source language. The default is case-sensitive 10732matches for all languages except for Fortran, for which the default is 10733case-insensitive matches. 10734 10735@kindex show case-sensitive 10736@item show case-sensitive 10737This command shows the current setting of case sensitivity for symbols 10738lookups. 10739 10740@kindex info address 10741@cindex address of a symbol 10742@item info address @var{symbol} 10743Describe where the data for @var{symbol} is stored. For a register 10744variable, this says which register it is kept in. For a non-register 10745local variable, this prints the stack-frame offset at which the variable 10746is always stored. 10747 10748Note the contrast with @samp{print &@var{symbol}}, which does not work 10749at all for a register variable, and for a stack local variable prints 10750the exact address of the current instantiation of the variable. 10751 10752@kindex info symbol 10753@cindex symbol from address 10754@cindex closest symbol and offset for an address 10755@item info symbol @var{addr} 10756Print the name of a symbol which is stored at the address @var{addr}. 10757If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the 10758nearest symbol and an offset from it: 10759 10760@smallexample 10761(@value{GDBP}) info symbol 0x54320 10762_initialize_vx + 396 in section .text 10763@end smallexample 10764 10765@noindent 10766This is the opposite of the @code{info address} command. You can use 10767it to find out the name of a variable or a function given its address. 10768 10769@kindex whatis 10770@item whatis [@var{arg}] 10771Print the data type of @var{arg}, which can be either an expression or 10772a data type. With no argument, print the data type of @code{$}, the 10773last value in the value history. If @var{arg} is an expression, it is 10774not actually evaluated, and any side-effecting operations (such as 10775assignments or function calls) inside it do not take place. If 10776@var{arg} is a type name, it may be the name of a type or typedef, or 10777for C code it may have the form @samp{class @var{class-name}}, 10778@samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or 10779@samp{enum @var{enum-tag}}. 10780@xref{Expressions, ,Expressions}. 10781 10782@kindex ptype 10783@item ptype [@var{arg}] 10784@code{ptype} accepts the same arguments as @code{whatis}, but prints a 10785detailed description of the type, instead of just the name of the type. 10786@xref{Expressions, ,Expressions}. 10787 10788For example, for this variable declaration: 10789 10790@smallexample 10791struct complex @{double real; double imag;@} v; 10792@end smallexample 10793 10794@noindent 10795the two commands give this output: 10796 10797@smallexample 10798@group 10799(@value{GDBP}) whatis v 10800type = struct complex 10801(@value{GDBP}) ptype v 10802type = struct complex @{ 10803 double real; 10804 double imag; 10805@} 10806@end group 10807@end smallexample 10808 10809@noindent 10810As with @code{whatis}, using @code{ptype} without an argument refers to 10811the type of @code{$}, the last value in the value history. 10812 10813@cindex incomplete type 10814Sometimes, programs use opaque data types or incomplete specifications 10815of complex data structure. If the debug information included in the 10816program does not allow @value{GDBN} to display a full declaration of 10817the data type, it will say @samp{<incomplete type>}. For example, 10818given these declarations: 10819 10820@smallexample 10821 struct foo; 10822 struct foo *fooptr; 10823@end smallexample 10824 10825@noindent 10826but no definition for @code{struct foo} itself, @value{GDBN} will say: 10827 10828@smallexample 10829 (@value{GDBP}) ptype foo 10830 $1 = <incomplete type> 10831@end smallexample 10832 10833@noindent 10834``Incomplete type'' is C terminology for data types that are not 10835completely specified. 10836 10837@kindex info types 10838@item info types @var{regexp} 10839@itemx info types 10840Print a brief description of all types whose names match the regular 10841expression @var{regexp} (or all types in your program, if you supply 10842no argument). Each complete typename is matched as though it were a 10843complete line; thus, @samp{i type value} gives information on all 10844types in your program whose names include the string @code{value}, but 10845@samp{i type ^value$} gives information only on types whose complete 10846name is @code{value}. 10847 10848This command differs from @code{ptype} in two ways: first, like 10849@code{whatis}, it does not print a detailed description; second, it 10850lists all source files where a type is defined. 10851 10852@kindex info scope 10853@cindex local variables 10854@item info scope @var{location} 10855List all the variables local to a particular scope. This command 10856accepts a @var{location} argument---a function name, a source line, or 10857an address preceded by a @samp{*}, and prints all the variables local 10858to the scope defined by that location. For example: 10859 10860@smallexample 10861(@value{GDBP}) @b{info scope command_line_handler} 10862Scope for command_line_handler: 10863Symbol rl is an argument at stack/frame offset 8, length 4. 10864Symbol linebuffer is in static storage at address 0x150a18, length 4. 10865Symbol linelength is in static storage at address 0x150a1c, length 4. 10866Symbol p is a local variable in register $esi, length 4. 10867Symbol p1 is a local variable in register $ebx, length 4. 10868Symbol nline is a local variable in register $edx, length 4. 10869Symbol repeat is a local variable at frame offset -8, length 4. 10870@end smallexample 10871 10872@noindent 10873This command is especially useful for determining what data to collect 10874during a @dfn{trace experiment}, see @ref{Tracepoint Actions, 10875collect}. 10876 10877@kindex info source 10878@item info source 10879Show information about the current source file---that is, the source file for 10880the function containing the current point of execution: 10881@itemize @bullet 10882@item 10883the name of the source file, and the directory containing it, 10884@item 10885the directory it was compiled in, 10886@item 10887its length, in lines, 10888@item 10889which programming language it is written in, 10890@item 10891whether the executable includes debugging information for that file, and 10892if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and 10893@item 10894whether the debugging information includes information about 10895preprocessor macros. 10896@end itemize 10897 10898 10899@kindex info sources 10900@item info sources 10901Print the names of all source files in your program for which there is 10902debugging information, organized into two lists: files whose symbols 10903have already been read, and files whose symbols will be read when needed. 10904 10905@kindex info functions 10906@item info functions 10907Print the names and data types of all defined functions. 10908 10909@item info functions @var{regexp} 10910Print the names and data types of all defined functions 10911whose names contain a match for regular expression @var{regexp}. 10912Thus, @samp{info fun step} finds all functions whose names 10913include @code{step}; @samp{info fun ^step} finds those whose names 10914start with @code{step}. If a function name contains characters 10915that conflict with the regular expression language (e.g.@: 10916@samp{operator*()}), they may be quoted with a backslash. 10917 10918@kindex info variables 10919@item info variables 10920Print the names and data types of all variables that are declared 10921outside of functions (i.e.@: excluding local variables). 10922 10923@item info variables @var{regexp} 10924Print the names and data types of all variables (except for local 10925variables) whose names contain a match for regular expression 10926@var{regexp}. 10927 10928@kindex info classes 10929@cindex Objective-C, classes and selectors 10930@item info classes 10931@itemx info classes @var{regexp} 10932Display all Objective-C classes in your program, or 10933(with the @var{regexp} argument) all those matching a particular regular 10934expression. 10935 10936@kindex info selectors 10937@item info selectors 10938@itemx info selectors @var{regexp} 10939Display all Objective-C selectors in your program, or 10940(with the @var{regexp} argument) all those matching a particular regular 10941expression. 10942 10943@ignore 10944This was never implemented. 10945@kindex info methods 10946@item info methods 10947@itemx info methods @var{regexp} 10948The @code{info methods} command permits the user to examine all defined 10949methods within C@t{++} program, or (with the @var{regexp} argument) a 10950specific set of methods found in the various C@t{++} classes. Many 10951C@t{++} classes provide a large number of methods. Thus, the output 10952from the @code{ptype} command can be overwhelming and hard to use. The 10953@code{info-methods} command filters the methods, printing only those 10954which match the regular-expression @var{regexp}. 10955@end ignore 10956 10957@cindex reloading symbols 10958Some systems allow individual object files that make up your program to 10959be replaced without stopping and restarting your program. For example, 10960in VxWorks you can simply recompile a defective object file and keep on 10961running. If you are running on one of these systems, you can allow 10962@value{GDBN} to reload the symbols for automatically relinked modules: 10963 10964@table @code 10965@kindex set symbol-reloading 10966@item set symbol-reloading on 10967Replace symbol definitions for the corresponding source file when an 10968object file with a particular name is seen again. 10969 10970@item set symbol-reloading off 10971Do not replace symbol definitions when encountering object files of the 10972same name more than once. This is the default state; if you are not 10973running on a system that permits automatic relinking of modules, you 10974should leave @code{symbol-reloading} off, since otherwise @value{GDBN} 10975may discard symbols when linking large programs, that may contain 10976several modules (from different directories or libraries) with the same 10977name. 10978 10979@kindex show symbol-reloading 10980@item show symbol-reloading 10981Show the current @code{on} or @code{off} setting. 10982@end table 10983 10984@cindex opaque data types 10985@kindex set opaque-type-resolution 10986@item set opaque-type-resolution on 10987Tell @value{GDBN} to resolve opaque types. An opaque type is a type 10988declared as a pointer to a @code{struct}, @code{class}, or 10989@code{union}---for example, @code{struct MyType *}---that is used in one 10990source file although the full declaration of @code{struct MyType} is in 10991another source file. The default is on. 10992 10993A change in the setting of this subcommand will not take effect until 10994the next time symbols for a file are loaded. 10995 10996@item set opaque-type-resolution off 10997Tell @value{GDBN} not to resolve opaque types. In this case, the type 10998is printed as follows: 10999@smallexample 11000@{<no data fields>@} 11001@end smallexample 11002 11003@kindex show opaque-type-resolution 11004@item show opaque-type-resolution 11005Show whether opaque types are resolved or not. 11006 11007@kindex maint print symbols 11008@cindex symbol dump 11009@kindex maint print psymbols 11010@cindex partial symbol dump 11011@item maint print symbols @var{filename} 11012@itemx maint print psymbols @var{filename} 11013@itemx maint print msymbols @var{filename} 11014Write a dump of debugging symbol data into the file @var{filename}. 11015These commands are used to debug the @value{GDBN} symbol-reading code. Only 11016symbols with debugging data are included. If you use @samp{maint print 11017symbols}, @value{GDBN} includes all the symbols for which it has already 11018collected full details: that is, @var{filename} reflects symbols for 11019only those files whose symbols @value{GDBN} has read. You can use the 11020command @code{info sources} to find out which files these are. If you 11021use @samp{maint print psymbols} instead, the dump shows information about 11022symbols that @value{GDBN} only knows partially---that is, symbols defined in 11023files that @value{GDBN} has skimmed, but not yet read completely. Finally, 11024@samp{maint print msymbols} dumps just the minimal symbol information 11025required for each object file from which @value{GDBN} has read some symbols. 11026@xref{Files, ,Commands to Specify Files}, for a discussion of how 11027@value{GDBN} reads symbols (in the description of @code{symbol-file}). 11028 11029@kindex maint info symtabs 11030@kindex maint info psymtabs 11031@cindex listing @value{GDBN}'s internal symbol tables 11032@cindex symbol tables, listing @value{GDBN}'s internal 11033@cindex full symbol tables, listing @value{GDBN}'s internal 11034@cindex partial symbol tables, listing @value{GDBN}'s internal 11035@item maint info symtabs @r{[} @var{regexp} @r{]} 11036@itemx maint info psymtabs @r{[} @var{regexp} @r{]} 11037 11038List the @code{struct symtab} or @code{struct partial_symtab} 11039structures whose names match @var{regexp}. If @var{regexp} is not 11040given, list them all. The output includes expressions which you can 11041copy into a @value{GDBN} debugging this one to examine a particular 11042structure in more detail. For example: 11043 11044@smallexample 11045(@value{GDBP}) maint info psymtabs dwarf2read 11046@{ objfile /home/gnu/build/gdb/gdb 11047 ((struct objfile *) 0x82e69d0) 11048 @{ psymtab /home/gnu/src/gdb/dwarf2read.c 11049 ((struct partial_symtab *) 0x8474b10) 11050 readin no 11051 fullname (null) 11052 text addresses 0x814d3c8 -- 0x8158074 11053 globals (* (struct partial_symbol **) 0x8507a08 @@ 9) 11054 statics (* (struct partial_symbol **) 0x40e95b78 @@ 2882) 11055 dependencies (none) 11056 @} 11057@} 11058(@value{GDBP}) maint info symtabs 11059(@value{GDBP}) 11060@end smallexample 11061@noindent 11062We see that there is one partial symbol table whose filename contains 11063the string @samp{dwarf2read}, belonging to the @samp{gdb} executable; 11064and we see that @value{GDBN} has not read in any symtabs yet at all. 11065If we set a breakpoint on a function, that will cause @value{GDBN} to 11066read the symtab for the compilation unit containing that function: 11067 11068@smallexample 11069(@value{GDBP}) break dwarf2_psymtab_to_symtab 11070Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, 11071line 1574. 11072(@value{GDBP}) maint info symtabs 11073@{ objfile /home/gnu/build/gdb/gdb 11074 ((struct objfile *) 0x82e69d0) 11075 @{ symtab /home/gnu/src/gdb/dwarf2read.c 11076 ((struct symtab *) 0x86c1f38) 11077 dirname (null) 11078 fullname (null) 11079 blockvector ((struct blockvector *) 0x86c1bd0) (primary) 11080 debugformat DWARF 2 11081 @} 11082@} 11083(@value{GDBP}) 11084@end smallexample 11085@end table 11086 11087 11088@node Altering 11089@chapter Altering Execution 11090 11091Once you think you have found an error in your program, you might want to 11092find out for certain whether correcting the apparent error would lead to 11093correct results in the rest of the run. You can find the answer by 11094experiment, using the @value{GDBN} features for altering execution of the 11095program. 11096 11097For example, you can store new values into variables or memory 11098locations, give your program a signal, restart it at a different 11099address, or even return prematurely from a function. 11100 11101@menu 11102* Assignment:: Assignment to variables 11103* Jumping:: Continuing at a different address 11104* Signaling:: Giving your program a signal 11105* Returning:: Returning from a function 11106* Calling:: Calling your program's functions 11107* Patching:: Patching your program 11108@end menu 11109 11110@node Assignment 11111@section Assignment to Variables 11112 11113@cindex assignment 11114@cindex setting variables 11115To alter the value of a variable, evaluate an assignment expression. 11116@xref{Expressions, ,Expressions}. For example, 11117 11118@smallexample 11119print x=4 11120@end smallexample 11121 11122@noindent 11123stores the value 4 into the variable @code{x}, and then prints the 11124value of the assignment expression (which is 4). 11125@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more 11126information on operators in supported languages. 11127 11128@kindex set variable 11129@cindex variables, setting 11130If you are not interested in seeing the value of the assignment, use the 11131@code{set} command instead of the @code{print} command. @code{set} is 11132really the same as @code{print} except that the expression's value is 11133not printed and is not put in the value history (@pxref{Value History, 11134,Value History}). The expression is evaluated only for its effects. 11135 11136If the beginning of the argument string of the @code{set} command 11137appears identical to a @code{set} subcommand, use the @code{set 11138variable} command instead of just @code{set}. This command is identical 11139to @code{set} except for its lack of subcommands. For example, if your 11140program has a variable @code{width}, you get an error if you try to set 11141a new value with just @samp{set width=13}, because @value{GDBN} has the 11142command @code{set width}: 11143 11144@smallexample 11145(@value{GDBP}) whatis width 11146type = double 11147(@value{GDBP}) p width 11148$4 = 13 11149(@value{GDBP}) set width=47 11150Invalid syntax in expression. 11151@end smallexample 11152 11153@noindent 11154The invalid expression, of course, is @samp{=47}. In 11155order to actually set the program's variable @code{width}, use 11156 11157@smallexample 11158(@value{GDBP}) set var width=47 11159@end smallexample 11160 11161Because the @code{set} command has many subcommands that can conflict 11162with the names of program variables, it is a good idea to use the 11163@code{set variable} command instead of just @code{set}. For example, if 11164your program has a variable @code{g}, you run into problems if you try 11165to set a new value with just @samp{set g=4}, because @value{GDBN} has 11166the command @code{set gnutarget}, abbreviated @code{set g}: 11167 11168@smallexample 11169@group 11170(@value{GDBP}) whatis g 11171type = double 11172(@value{GDBP}) p g 11173$1 = 1 11174(@value{GDBP}) set g=4 11175(@value{GDBP}) p g 11176$2 = 1 11177(@value{GDBP}) r 11178The program being debugged has been started already. 11179Start it from the beginning? (y or n) y 11180Starting program: /home/smith/cc_progs/a.out 11181"/home/smith/cc_progs/a.out": can't open to read symbols: 11182 Invalid bfd target. 11183(@value{GDBP}) show g 11184The current BFD target is "=4". 11185@end group 11186@end smallexample 11187 11188@noindent 11189The program variable @code{g} did not change, and you silently set the 11190@code{gnutarget} to an invalid value. In order to set the variable 11191@code{g}, use 11192 11193@smallexample 11194(@value{GDBP}) set var g=4 11195@end smallexample 11196 11197@value{GDBN} allows more implicit conversions in assignments than C; you can 11198freely store an integer value into a pointer variable or vice versa, 11199and you can convert any structure to any other structure that is the 11200same length or shorter. 11201@comment FIXME: how do structs align/pad in these conversions? 11202@comment /doc@cygnus.com 18dec1990 11203 11204To store values into arbitrary places in memory, use the @samp{@{@dots{}@}} 11205construct to generate a value of specified type at a specified address 11206(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers 11207to memory location @code{0x83040} as an integer (which implies a certain size 11208and representation in memory), and 11209 11210@smallexample 11211set @{int@}0x83040 = 4 11212@end smallexample 11213 11214@noindent 11215stores the value 4 into that memory location. 11216 11217@node Jumping 11218@section Continuing at a Different Address 11219 11220Ordinarily, when you continue your program, you do so at the place where 11221it stopped, with the @code{continue} command. You can instead continue at 11222an address of your own choosing, with the following commands: 11223 11224@table @code 11225@kindex jump 11226@item jump @var{linespec} 11227Resume execution at line @var{linespec}. Execution stops again 11228immediately if there is a breakpoint there. @xref{List, ,Printing 11229Source Lines}, for a description of the different forms of 11230@var{linespec}. It is common practice to use the @code{tbreak} command 11231in conjunction with @code{jump}. @xref{Set Breaks, ,Setting 11232Breakpoints}. 11233 11234The @code{jump} command does not change the current stack frame, or 11235the stack pointer, or the contents of any memory location or any 11236register other than the program counter. If line @var{linespec} is in 11237a different function from the one currently executing, the results may 11238be bizarre if the two functions expect different patterns of arguments or 11239of local variables. For this reason, the @code{jump} command requests 11240confirmation if the specified line is not in the function currently 11241executing. However, even bizarre results are predictable if you are 11242well acquainted with the machine-language code of your program. 11243 11244@item jump *@var{address} 11245Resume execution at the instruction at address @var{address}. 11246@end table 11247 11248@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt. 11249On many systems, you can get much the same effect as the @code{jump} 11250command by storing a new value into the register @code{$pc}. The 11251difference is that this does not start your program running; it only 11252changes the address of where it @emph{will} run when you continue. For 11253example, 11254 11255@smallexample 11256set $pc = 0x485 11257@end smallexample 11258 11259@noindent 11260makes the next @code{continue} command or stepping command execute at 11261address @code{0x485}, rather than at the address where your program stopped. 11262@xref{Continuing and Stepping, ,Continuing and Stepping}. 11263 11264The most common occasion to use the @code{jump} command is to back 11265up---perhaps with more breakpoints set---over a portion of a program 11266that has already executed, in order to examine its execution in more 11267detail. 11268 11269@c @group 11270@node Signaling 11271@section Giving your Program a Signal 11272@cindex deliver a signal to a program 11273 11274@table @code 11275@kindex signal 11276@item signal @var{signal} 11277Resume execution where your program stopped, but immediately give it the 11278signal @var{signal}. @var{signal} can be the name or the number of a 11279signal. For example, on many systems @code{signal 2} and @code{signal 11280SIGINT} are both ways of sending an interrupt signal. 11281 11282Alternatively, if @var{signal} is zero, continue execution without 11283giving a signal. This is useful when your program stopped on account of 11284a signal and would ordinary see the signal when resumed with the 11285@code{continue} command; @samp{signal 0} causes it to resume without a 11286signal. 11287 11288@code{signal} does not repeat when you press @key{RET} a second time 11289after executing the command. 11290@end table 11291@c @end group 11292 11293Invoking the @code{signal} command is not the same as invoking the 11294@code{kill} utility from the shell. Sending a signal with @code{kill} 11295causes @value{GDBN} to decide what to do with the signal depending on 11296the signal handling tables (@pxref{Signals}). The @code{signal} command 11297passes the signal directly to your program. 11298 11299 11300@node Returning 11301@section Returning from a Function 11302 11303@table @code 11304@cindex returning from a function 11305@kindex return 11306@item return 11307@itemx return @var{expression} 11308You can cancel execution of a function call with the @code{return} 11309command. If you give an 11310@var{expression} argument, its value is used as the function's return 11311value. 11312@end table 11313 11314When you use @code{return}, @value{GDBN} discards the selected stack frame 11315(and all frames within it). You can think of this as making the 11316discarded frame return prematurely. If you wish to specify a value to 11317be returned, give that value as the argument to @code{return}. 11318 11319This pops the selected stack frame (@pxref{Selection, ,Selecting a 11320Frame}), and any other frames inside of it, leaving its caller as the 11321innermost remaining frame. That frame becomes selected. The 11322specified value is stored in the registers used for returning values 11323of functions. 11324 11325The @code{return} command does not resume execution; it leaves the 11326program stopped in the state that would exist if the function had just 11327returned. In contrast, the @code{finish} command (@pxref{Continuing 11328and Stepping, ,Continuing and Stepping}) resumes execution until the 11329selected stack frame returns naturally. 11330 11331@node Calling 11332@section Calling Program Functions 11333 11334@table @code 11335@cindex calling functions 11336@cindex inferior functions, calling 11337@item print @var{expr} 11338Evaluate the expression @var{expr} and display the resulting value. 11339@var{expr} may include calls to functions in the program being 11340debugged. 11341 11342@kindex call 11343@item call @var{expr} 11344Evaluate the expression @var{expr} without displaying @code{void} 11345returned values. 11346 11347You can use this variant of the @code{print} command if you want to 11348execute a function from your program that does not return anything 11349(a.k.a.@: @dfn{a void function}), but without cluttering the output 11350with @code{void} returned values that @value{GDBN} will otherwise 11351print. If the result is not void, it is printed and saved in the 11352value history. 11353@end table 11354 11355It is possible for the function you call via the @code{print} or 11356@code{call} command to generate a signal (e.g., if there's a bug in 11357the function, or if you passed it incorrect arguments). What happens 11358in that case is controlled by the @code{set unwindonsignal} command. 11359 11360@table @code 11361@item set unwindonsignal 11362@kindex set unwindonsignal 11363@cindex unwind stack in called functions 11364@cindex call dummy stack unwinding 11365Set unwinding of the stack if a signal is received while in a function 11366that @value{GDBN} called in the program being debugged. If set to on, 11367@value{GDBN} unwinds the stack it created for the call and restores 11368the context to what it was before the call. If set to off (the 11369default), @value{GDBN} stops in the frame where the signal was 11370received. 11371 11372@item show unwindonsignal 11373@kindex show unwindonsignal 11374Show the current setting of stack unwinding in the functions called by 11375@value{GDBN}. 11376@end table 11377 11378@cindex weak alias functions 11379Sometimes, a function you wish to call is actually a @dfn{weak alias} 11380for another function. In such case, @value{GDBN} might not pick up 11381the type information, including the types of the function arguments, 11382which causes @value{GDBN} to call the inferior function incorrectly. 11383As a result, the called function will function erroneously and may 11384even crash. A solution to that is to use the name of the aliased 11385function instead. 11386 11387@node Patching 11388@section Patching Programs 11389 11390@cindex patching binaries 11391@cindex writing into executables 11392@cindex writing into corefiles 11393 11394By default, @value{GDBN} opens the file containing your program's 11395executable code (or the corefile) read-only. This prevents accidental 11396alterations to machine code; but it also prevents you from intentionally 11397patching your program's binary. 11398 11399If you'd like to be able to patch the binary, you can specify that 11400explicitly with the @code{set write} command. For example, you might 11401want to turn on internal debugging flags, or even to make emergency 11402repairs. 11403 11404@table @code 11405@kindex set write 11406@item set write on 11407@itemx set write off 11408If you specify @samp{set write on}, @value{GDBN} opens executable and 11409core files for both reading and writing; if you specify @samp{set write 11410off} (the default), @value{GDBN} opens them read-only. 11411 11412If you have already loaded a file, you must load it again (using the 11413@code{exec-file} or @code{core-file} command) after changing @code{set 11414write}, for your new setting to take effect. 11415 11416@item show write 11417@kindex show write 11418Display whether executable files and core files are opened for writing 11419as well as reading. 11420@end table 11421 11422@node GDB Files 11423@chapter @value{GDBN} Files 11424 11425@value{GDBN} needs to know the file name of the program to be debugged, 11426both in order to read its symbol table and in order to start your 11427program. To debug a core dump of a previous run, you must also tell 11428@value{GDBN} the name of the core dump file. 11429 11430@menu 11431* Files:: Commands to specify files 11432* Separate Debug Files:: Debugging information in separate files 11433* Symbol Errors:: Errors reading symbol files 11434@end menu 11435 11436@node Files 11437@section Commands to Specify Files 11438 11439@cindex symbol table 11440@cindex core dump file 11441 11442You may want to specify executable and core dump file names. The usual 11443way to do this is at start-up time, using the arguments to 11444@value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and 11445Out of @value{GDBN}}). 11446 11447Occasionally it is necessary to change to a different file during a 11448@value{GDBN} session. Or you may run @value{GDBN} and forget to 11449specify a file you want to use. Or you are debugging a remote target 11450via @code{gdbserver} (@pxref{Server, file, Using the @code{gdbserver} 11451Program}). In these situations the @value{GDBN} commands to specify 11452new files are useful. 11453 11454@table @code 11455@cindex executable file 11456@kindex file 11457@item file @var{filename} 11458Use @var{filename} as the program to be debugged. It is read for its 11459symbols and for the contents of pure memory. It is also the program 11460executed when you use the @code{run} command. If you do not specify a 11461directory and the file is not found in the @value{GDBN} working directory, 11462@value{GDBN} uses the environment variable @code{PATH} as a list of 11463directories to search, just as the shell does when looking for a program 11464to run. You can change the value of this variable, for both @value{GDBN} 11465and your program, using the @code{path} command. 11466 11467@cindex unlinked object files 11468@cindex patching object files 11469You can load unlinked object @file{.o} files into @value{GDBN} using 11470the @code{file} command. You will not be able to ``run'' an object 11471file, but you can disassemble functions and inspect variables. Also, 11472if the underlying BFD functionality supports it, you could use 11473@kbd{gdb -write} to patch object files using this technique. Note 11474that @value{GDBN} can neither interpret nor modify relocations in this 11475case, so branches and some initialized variables will appear to go to 11476the wrong place. But this feature is still handy from time to time. 11477 11478@item file 11479@code{file} with no argument makes @value{GDBN} discard any information it 11480has on both executable file and the symbol table. 11481 11482@kindex exec-file 11483@item exec-file @r{[} @var{filename} @r{]} 11484Specify that the program to be run (but not the symbol table) is found 11485in @var{filename}. @value{GDBN} searches the environment variable @code{PATH} 11486if necessary to locate your program. Omitting @var{filename} means to 11487discard information on the executable file. 11488 11489@kindex symbol-file 11490@item symbol-file @r{[} @var{filename} @r{]} 11491Read symbol table information from file @var{filename}. @code{PATH} is 11492searched when necessary. Use the @code{file} command to get both symbol 11493table and program to run from the same file. 11494 11495@code{symbol-file} with no argument clears out @value{GDBN} information on your 11496program's symbol table. 11497 11498The @code{symbol-file} command causes @value{GDBN} to forget the contents of 11499some breakpoints and auto-display expressions. This is because they may 11500contain pointers to the internal data recording symbols and data types, 11501which are part of the old symbol table data being discarded inside 11502@value{GDBN}. 11503 11504@code{symbol-file} does not repeat if you press @key{RET} again after 11505executing it once. 11506 11507When @value{GDBN} is configured for a particular environment, it 11508understands debugging information in whatever format is the standard 11509generated for that environment; you may use either a @sc{gnu} compiler, or 11510other compilers that adhere to the local conventions. 11511Best results are usually obtained from @sc{gnu} compilers; for example, 11512using @code{@value{NGCC}} you can generate debugging information for 11513optimized code. 11514 11515For most kinds of object files, with the exception of old SVR3 systems 11516using COFF, the @code{symbol-file} command does not normally read the 11517symbol table in full right away. Instead, it scans the symbol table 11518quickly to find which source files and which symbols are present. The 11519details are read later, one source file at a time, as they are needed. 11520 11521The purpose of this two-stage reading strategy is to make @value{GDBN} 11522start up faster. For the most part, it is invisible except for 11523occasional pauses while the symbol table details for a particular source 11524file are being read. (The @code{set verbose} command can turn these 11525pauses into messages if desired. @xref{Messages/Warnings, ,Optional 11526Warnings and Messages}.) 11527 11528We have not implemented the two-stage strategy for COFF yet. When the 11529symbol table is stored in COFF format, @code{symbol-file} reads the 11530symbol table data in full right away. Note that ``stabs-in-COFF'' 11531still does the two-stage strategy, since the debug info is actually 11532in stabs format. 11533 11534@kindex readnow 11535@cindex reading symbols immediately 11536@cindex symbols, reading immediately 11537@item symbol-file @var{filename} @r{[} -readnow @r{]} 11538@itemx file @var{filename} @r{[} -readnow @r{]} 11539You can override the @value{GDBN} two-stage strategy for reading symbol 11540tables by using the @samp{-readnow} option with any of the commands that 11541load symbol table information, if you want to be sure @value{GDBN} has the 11542entire symbol table available. 11543 11544@c FIXME: for now no mention of directories, since this seems to be in 11545@c flux. 13mar1992 status is that in theory GDB would look either in 11546@c current dir or in same dir as myprog; but issues like competing 11547@c GDB's, or clutter in system dirs, mean that in practice right now 11548@c only current dir is used. FFish says maybe a special GDB hierarchy 11549@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol 11550@c files. 11551 11552@kindex core-file 11553@item core-file @r{[}@var{filename}@r{]} 11554@itemx core 11555Specify the whereabouts of a core dump file to be used as the ``contents 11556of memory''. Traditionally, core files contain only some parts of the 11557address space of the process that generated them; @value{GDBN} can access the 11558executable file itself for other parts. 11559 11560@code{core-file} with no argument specifies that no core file is 11561to be used. 11562 11563Note that the core file is ignored when your program is actually running 11564under @value{GDBN}. So, if you have been running your program and you 11565wish to debug a core file instead, you must kill the subprocess in which 11566the program is running. To do this, use the @code{kill} command 11567(@pxref{Kill Process, ,Killing the Child Process}). 11568 11569@kindex add-symbol-file 11570@cindex dynamic linking 11571@item add-symbol-file @var{filename} @var{address} 11572@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} 11573@itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address} @dots{} 11574The @code{add-symbol-file} command reads additional symbol table 11575information from the file @var{filename}. You would use this command 11576when @var{filename} has been dynamically loaded (by some other means) 11577into the program that is running. @var{address} should be the memory 11578address at which the file has been loaded; @value{GDBN} cannot figure 11579this out for itself. You can additionally specify an arbitrary number 11580of @samp{@r{-s}@var{section} @var{address}} pairs, to give an explicit 11581section name and base address for that section. You can specify any 11582@var{address} as an expression. 11583 11584The symbol table of the file @var{filename} is added to the symbol table 11585originally read with the @code{symbol-file} command. You can use the 11586@code{add-symbol-file} command any number of times; the new symbol data 11587thus read keeps adding to the old. To discard all old symbol data 11588instead, use the @code{symbol-file} command without any arguments. 11589 11590@cindex relocatable object files, reading symbols from 11591@cindex object files, relocatable, reading symbols from 11592@cindex reading symbols from relocatable object files 11593@cindex symbols, reading from relocatable object files 11594@cindex @file{.o} files, reading symbols from 11595Although @var{filename} is typically a shared library file, an 11596executable file, or some other object file which has been fully 11597relocated for loading into a process, you can also load symbolic 11598information from relocatable @file{.o} files, as long as: 11599 11600@itemize @bullet 11601@item 11602the file's symbolic information refers only to linker symbols defined in 11603that file, not to symbols defined by other object files, 11604@item 11605every section the file's symbolic information refers to has actually 11606been loaded into the inferior, as it appears in the file, and 11607@item 11608you can determine the address at which every section was loaded, and 11609provide these to the @code{add-symbol-file} command. 11610@end itemize 11611 11612@noindent 11613Some embedded operating systems, like Sun Chorus and VxWorks, can load 11614relocatable files into an already running program; such systems 11615typically make the requirements above easy to meet. However, it's 11616important to recognize that many native systems use complex link 11617procedures (@code{.linkonce} section factoring and C@t{++} constructor table 11618assembly, for example) that make the requirements difficult to meet. In 11619general, one cannot assume that using @code{add-symbol-file} to read a 11620relocatable object file's symbolic information will have the same effect 11621as linking the relocatable object file into the program in the normal 11622way. 11623 11624@code{add-symbol-file} does not repeat if you press @key{RET} after using it. 11625 11626@kindex add-symbol-file-from-memory 11627@cindex @code{syscall DSO} 11628@cindex load symbols from memory 11629@item add-symbol-file-from-memory @var{address} 11630Load symbols from the given @var{address} in a dynamically loaded 11631object file whose image is mapped directly into the inferior's memory. 11632For example, the Linux kernel maps a @code{syscall DSO} into each 11633process's address space; this DSO provides kernel-specific code for 11634some system calls. The argument can be any expression whose 11635evaluation yields the address of the file's shared object file header. 11636For this command to work, you must have used @code{symbol-file} or 11637@code{exec-file} commands in advance. 11638 11639@kindex add-shared-symbol-files 11640@kindex assf 11641@item add-shared-symbol-files @var{library-file} 11642@itemx assf @var{library-file} 11643The @code{add-shared-symbol-files} command can currently be used only 11644in the Cygwin build of @value{GDBN} on MS-Windows OS, where it is an 11645alias for the @code{dll-symbols} command (@pxref{Cygwin Native}). 11646@value{GDBN} automatically looks for shared libraries, however if 11647@value{GDBN} does not find yours, you can invoke 11648@code{add-shared-symbol-files}. It takes one argument: the shared 11649library's file name. @code{assf} is a shorthand alias for 11650@code{add-shared-symbol-files}. 11651 11652@kindex section 11653@item section @var{section} @var{addr} 11654The @code{section} command changes the base address of the named 11655@var{section} of the exec file to @var{addr}. This can be used if the 11656exec file does not contain section addresses, (such as in the 11657@code{a.out} format), or when the addresses specified in the file 11658itself are wrong. Each section must be changed separately. The 11659@code{info files} command, described below, lists all the sections and 11660their addresses. 11661 11662@kindex info files 11663@kindex info target 11664@item info files 11665@itemx info target 11666@code{info files} and @code{info target} are synonymous; both print the 11667current target (@pxref{Targets, ,Specifying a Debugging Target}), 11668including the names of the executable and core dump files currently in 11669use by @value{GDBN}, and the files from which symbols were loaded. The 11670command @code{help target} lists all possible targets rather than 11671current ones. 11672 11673@kindex maint info sections 11674@item maint info sections 11675Another command that can give you extra information about program sections 11676is @code{maint info sections}. In addition to the section information 11677displayed by @code{info files}, this command displays the flags and file 11678offset of each section in the executable and core dump files. In addition, 11679@code{maint info sections} provides the following command options (which 11680may be arbitrarily combined): 11681 11682@table @code 11683@item ALLOBJ 11684Display sections for all loaded object files, including shared libraries. 11685@item @var{sections} 11686Display info only for named @var{sections}. 11687@item @var{section-flags} 11688Display info only for sections for which @var{section-flags} are true. 11689The section flags that @value{GDBN} currently knows about are: 11690@table @code 11691@item ALLOC 11692Section will have space allocated in the process when loaded. 11693Set for all sections except those containing debug information. 11694@item LOAD 11695Section will be loaded from the file into the child process memory. 11696Set for pre-initialized code and data, clear for @code{.bss} sections. 11697@item RELOC 11698Section needs to be relocated before loading. 11699@item READONLY 11700Section cannot be modified by the child process. 11701@item CODE 11702Section contains executable code only. 11703@item DATA 11704Section contains data only (no executable code). 11705@item ROM 11706Section will reside in ROM. 11707@item CONSTRUCTOR 11708Section contains data for constructor/destructor lists. 11709@item HAS_CONTENTS 11710Section is not empty. 11711@item NEVER_LOAD 11712An instruction to the linker to not output the section. 11713@item COFF_SHARED_LIBRARY 11714A notification to the linker that the section contains 11715COFF shared library information. 11716@item IS_COMMON 11717Section contains common symbols. 11718@end table 11719@end table 11720@kindex set trust-readonly-sections 11721@cindex read-only sections 11722@item set trust-readonly-sections on 11723Tell @value{GDBN} that readonly sections in your object file 11724really are read-only (i.e.@: that their contents will not change). 11725In that case, @value{GDBN} can fetch values from these sections 11726out of the object file, rather than from the target program. 11727For some targets (notably embedded ones), this can be a significant 11728enhancement to debugging performance. 11729 11730The default is off. 11731 11732@item set trust-readonly-sections off 11733Tell @value{GDBN} not to trust readonly sections. This means that 11734the contents of the section might change while the program is running, 11735and must therefore be fetched from the target when needed. 11736 11737@item show trust-readonly-sections 11738Show the current setting of trusting readonly sections. 11739@end table 11740 11741All file-specifying commands allow both absolute and relative file names 11742as arguments. @value{GDBN} always converts the file name to an absolute file 11743name and remembers it that way. 11744 11745@cindex shared libraries 11746@value{GDBN} supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, 11747and IBM RS/6000 AIX shared libraries. 11748 11749@value{GDBN} automatically loads symbol definitions from shared libraries 11750when you use the @code{run} command, or when you examine a core file. 11751(Before you issue the @code{run} command, @value{GDBN} does not understand 11752references to a function in a shared library, however---unless you are 11753debugging a core file). 11754 11755On HP-UX, if the program loads a library explicitly, @value{GDBN} 11756automatically loads the symbols at the time of the @code{shl_load} call. 11757 11758@c FIXME: some @value{GDBN} release may permit some refs to undef 11759@c FIXME...symbols---eg in a break cmd---assuming they are from a shared 11760@c FIXME...lib; check this from time to time when updating manual 11761 11762There are times, however, when you may wish to not automatically load 11763symbol definitions from shared libraries, such as when they are 11764particularly large or there are many of them. 11765 11766To control the automatic loading of shared library symbols, use the 11767commands: 11768 11769@table @code 11770@kindex set auto-solib-add 11771@item set auto-solib-add @var{mode} 11772If @var{mode} is @code{on}, symbols from all shared object libraries 11773will be loaded automatically when the inferior begins execution, you 11774attach to an independently started inferior, or when the dynamic linker 11775informs @value{GDBN} that a new library has been loaded. If @var{mode} 11776is @code{off}, symbols must be loaded manually, using the 11777@code{sharedlibrary} command. The default value is @code{on}. 11778 11779@cindex memory used for symbol tables 11780If your program uses lots of shared libraries with debug info that 11781takes large amounts of memory, you can decrease the @value{GDBN} 11782memory footprint by preventing it from automatically loading the 11783symbols from shared libraries. To that end, type @kbd{set 11784auto-solib-add off} before running the inferior, then load each 11785library whose debug symbols you do need with @kbd{sharedlibrary 11786@var{regexp}}, where @var{regexp} is a regular expression that matches 11787the libraries whose symbols you want to be loaded. 11788 11789@kindex show auto-solib-add 11790@item show auto-solib-add 11791Display the current autoloading mode. 11792@end table 11793 11794@cindex load shared library 11795To explicitly load shared library symbols, use the @code{sharedlibrary} 11796command: 11797 11798@table @code 11799@kindex info sharedlibrary 11800@kindex info share 11801@item info share 11802@itemx info sharedlibrary 11803Print the names of the shared libraries which are currently loaded. 11804 11805@kindex sharedlibrary 11806@kindex share 11807@item sharedlibrary @var{regex} 11808@itemx share @var{regex} 11809Load shared object library symbols for files matching a 11810Unix regular expression. 11811As with files loaded automatically, it only loads shared libraries 11812required by your program for a core file or after typing @code{run}. If 11813@var{regex} is omitted all shared libraries required by your program are 11814loaded. 11815 11816@item nosharedlibrary 11817@kindex nosharedlibrary 11818@cindex unload symbols from shared libraries 11819Unload all shared object library symbols. This discards all symbols 11820that have been loaded from all shared libraries. Symbols from shared 11821libraries that were loaded by explicit user requests are not 11822discarded. 11823@end table 11824 11825Sometimes you may wish that @value{GDBN} stops and gives you control 11826when any of shared library events happen. Use the @code{set 11827stop-on-solib-events} command for this: 11828 11829@table @code 11830@item set stop-on-solib-events 11831@kindex set stop-on-solib-events 11832This command controls whether @value{GDBN} should give you control 11833when the dynamic linker notifies it about some shared library event. 11834The most common event of interest is loading or unloading of a new 11835shared library. 11836 11837@item show stop-on-solib-events 11838@kindex show stop-on-solib-events 11839Show whether @value{GDBN} stops and gives you control when shared 11840library events happen. 11841@end table 11842 11843Shared libraries are also supported in many cross or remote debugging 11844configurations. A copy of the target's libraries need to be present on the 11845host system; they need to be the same as the target libraries, although the 11846copies on the target can be stripped as long as the copies on the host are 11847not. 11848 11849@cindex where to look for shared libraries 11850For remote debugging, you need to tell @value{GDBN} where the target 11851libraries are, so that it can load the correct copies---otherwise, it 11852may try to load the host's libraries. @value{GDBN} has two variables 11853to specify the search directories for target libraries. 11854 11855@table @code 11856@cindex prefix for shared library file names 11857@cindex system root, alternate 11858@kindex set solib-absolute-prefix 11859@kindex set sysroot 11860@item set sysroot @var{path} 11861Use @var{path} as the system root for the program being debugged. Any 11862absolute shared library paths will be prefixed with @var{path}; many 11863runtime loaders store the absolute paths to the shared library in the 11864target program's memory. If you use @code{set sysroot} to find shared 11865libraries, they need to be laid out in the same way that they are on 11866the target, with e.g.@: a @file{/lib} and @file{/usr/lib} hierarchy 11867under @var{path}. 11868 11869The @code{set solib-absolute-prefix} command is an alias for @code{set 11870sysroot}. 11871 11872@cindex default system root 11873@cindex @samp{--with-sysroot} 11874You can set the default system root by using the configure-time 11875@samp{--with-sysroot} option. If the system root is inside 11876@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or 11877@samp{--exec-prefix}), then the default system root will be updated 11878automatically if the installed @value{GDBN} is moved to a new 11879location. 11880 11881@kindex show sysroot 11882@item show sysroot 11883Display the current shared library prefix. 11884 11885@kindex set solib-search-path 11886@item set solib-search-path @var{path} 11887If this variable is set, @var{path} is a colon-separated list of 11888directories to search for shared libraries. @samp{solib-search-path} 11889is used after @samp{sysroot} fails to locate the library, or if the 11890path to the library is relative instead of absolute. If you want to 11891use @samp{solib-search-path} instead of @samp{sysroot}, be sure to set 11892@samp{sysroot} to a nonexistent directory to prevent @value{GDBN} from 11893finding your host's libraries. @samp{sysroot} is preferred; setting 11894it to a nonexistent directory may interfere with automatic loading 11895of shared library symbols. 11896 11897@kindex show solib-search-path 11898@item show solib-search-path 11899Display the current shared library search path. 11900@end table 11901 11902 11903@node Separate Debug Files 11904@section Debugging Information in Separate Files 11905@cindex separate debugging information files 11906@cindex debugging information in separate files 11907@cindex @file{.debug} subdirectories 11908@cindex debugging information directory, global 11909@cindex global debugging information directory 11910@cindex build ID, and separate debugging files 11911@cindex @file{.build-id} directory 11912 11913@value{GDBN} allows you to put a program's debugging information in a 11914file separate from the executable itself, in a way that allows 11915@value{GDBN} to find and load the debugging information automatically. 11916Since debugging information can be very large---sometimes larger 11917than the executable code itself---some systems distribute debugging 11918information for their executables in separate files, which users can 11919install only when they need to debug a problem. 11920 11921@value{GDBN} supports two ways of specifying the separate debug info 11922file: 11923 11924@itemize @bullet 11925@item 11926The executable contains a @dfn{debug link} that specifies the name of 11927the separate debug info file. The separate debug file's name is 11928usually @file{@var{executable}.debug}, where @var{executable} is the 11929name of the corresponding executable file without leading directories 11930(e.g., @file{ls.debug} for @file{/usr/bin/ls}). In addition, the 11931debug link specifies a CRC32 checksum for the debug file, which 11932@value{GDBN} uses to validate that the executable and the debug file 11933came from the same build. 11934 11935@item 11936The executable contains a @dfn{build ID}, a unique signature that is 11937also present in the corresponding debug info file. (This is supported 11938only on some operating systems, notably on @sc{gnu}/Linux. For more 11939details about this feature, see 11940@uref{http://fedoraproject.org/wiki/Releases/FeatureBuildId, the 11941Fedora Project's description of the buid ID feature}.) The debug info 11942file's name is not specified explicitly by the build ID, but can be 11943computed from the build ID, see below. 11944@end itemize 11945 11946Depending on the way the debug info file is specified, @value{GDBN} 11947uses two different methods of looking for the debug file: 11948 11949@itemize @bullet 11950@item 11951For the ``debug link'' method, @value{GDBN} looks up the named file in 11952the directory of the executable file, then in a subdirectory of that 11953directory named @file{.debug}, and finally under the global debug 11954directory, in a subdirectory whose name is identical to the leading 11955directories of the executable's absolute file name. 11956 11957@item 11958For the ``build ID'' method, @value{GDBN} looks in the 11959@file{.build-id} subdirectory of the global debug directory for a file 11960named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the 11961first 2 hex characters of the build ID signature, and @var{nnnnnnnn} 11962are the rest of the signature. (Real signatures are 32 or more 11963characters, not 10.) 11964@end itemize 11965 11966So, for example, suppose you ask @value{GDBN} to debug 11967@file{/usr/bin/ls}, which has a @dfn{debug link} that specifies the 11968file @file{ls.debug}, and a @dfn{build id} whose value in hex is 11969@code{abcdef1234}. If the global debug directory is 11970@file{/usr/lib/debug}, then @value{GDBN} will look for the following 11971debug information files, in the indicated order: 11972 11973@itemize @minus 11974@item 11975@file{/usr/lib/debug/.build-id/ab/cdef1234.debug} 11976@item 11977@file{/usr/bin/ls.debug} 11978@item 11979@file{/usr/bin/.debug/ls.debug} 11980@item 11981@file{/usr/lib/debug/usr/bin/ls.debug}. 11982@end itemize 11983 11984You can set the global debugging info directory's name, and view the 11985name @value{GDBN} is currently using. 11986 11987@table @code 11988 11989@kindex set debug-file-directory 11990@item set debug-file-directory @var{directory} 11991Set the directory which @value{GDBN} searches for separate debugging 11992information files to @var{directory}. 11993 11994@kindex show debug-file-directory 11995@item show debug-file-directory 11996Show the directory @value{GDBN} searches for separate debugging 11997information files. 11998 11999@end table 12000 12001@cindex @code{.gnu_debuglink} sections 12002@cindex debug link sections 12003A debug link is a special section of the executable file named 12004@code{.gnu_debuglink}. The section must contain: 12005 12006@itemize 12007@item 12008A filename, with any leading directory components removed, followed by 12009a zero byte, 12010@item 12011zero to three bytes of padding, as needed to reach the next four-byte 12012boundary within the section, and 12013@item 12014a four-byte CRC checksum, stored in the same endianness used for the 12015executable file itself. The checksum is computed on the debugging 12016information file's full contents by the function given below, passing 12017zero as the @var{crc} argument. 12018@end itemize 12019 12020Any executable file format can carry a debug link, as long as it can 12021contain a section named @code{.gnu_debuglink} with the contents 12022described above. 12023 12024@cindex @code{.note.gnu.build-id} sections 12025@cindex build ID sections 12026A build ID is a special section of the executable file named 12027@code{.note.gnu.build-id}. This section contains unique 12028identification for the built files---it remains the same across 12029multiple builds of the same build tree. The default algorithm SHA1 12030produces 160 bits (40 hexadecimal characters) of the content. The 12031same section with an identical value is present in the original built 12032binary with symbols, in its stripped variant, and in the separate 12033debugging information file. 12034 12035The debugging information file itself should be an ordinary 12036executable, containing a full set of linker symbols, sections, and 12037debugging information. The sections of the debugging information file 12038should have the same names, addresses, and sizes as the original file, 12039but they need not contain any data---much like a @code{.bss} section 12040in an ordinary executable. 12041 12042@sc{gnu} binary utilities (Binutils) package includes the 12043@samp{objcopy} utility that can produce 12044the separated executable / debugging information file pairs using the 12045following commands: 12046 12047@smallexample 12048@kbd{objcopy --only-keep-debug foo foo.debug} 12049@kbd{strip -g foo} 12050@end smallexample 12051 12052@noindent 12053These commands remove the debugging 12054information from the executable file @file{foo} and place it in the file 12055@file{foo.debug}. You can use the first, second or both methods to link the 12056two files: 12057 12058@itemize @bullet 12059@item 12060The debug link method needs the following additional command to also leave 12061behind a debug link in @file{foo}: 12062 12063@smallexample 12064@kbd{objcopy --add-gnu-debuglink=foo.debug foo} 12065@end smallexample 12066 12067Ulrich Drepper's @file{elfutils} package, starting with version 0.53, contains 12068a version of the @code{strip} command such that the command @kbd{strip foo -f 12069foo.debug} has the same functionality as the two @code{objcopy} commands and 12070the @code{ln -s} command above, together. 12071 12072@item 12073Build ID gets embedded into the main executable using @code{ld --build-id} or 12074the @value{NGCC} counterpart @code{gcc -Wl,--build-id}. Build ID support plus 12075compatibility fixes for debug files separation are present in @sc{gnu} binary 12076utilities (Binutils) since version 2.18. 12077@end itemize 12078 12079@noindent 12080 12081Since there are many different ways to compute CRC's for the debug 12082link (different polynomials, reversals, byte ordering, etc.), the 12083simplest way to describe the CRC used in @code{.gnu_debuglink} 12084sections is to give the complete code for a function that computes it: 12085 12086@kindex gnu_debuglink_crc32 12087@smallexample 12088unsigned long 12089gnu_debuglink_crc32 (unsigned long crc, 12090 unsigned char *buf, size_t len) 12091@{ 12092 static const unsigned long crc32_table[256] = 12093 @{ 12094 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, 12095 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, 12096 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, 12097 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, 12098 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, 12099 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, 12100 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, 12101 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, 12102 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, 12103 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, 12104 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, 12105 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, 12106 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, 12107 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, 12108 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, 12109 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, 12110 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, 12111 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, 12112 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, 12113 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, 12114 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, 12115 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, 12116 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, 12117 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, 12118 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, 12119 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, 12120 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, 12121 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, 12122 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, 12123 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, 12124 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, 12125 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, 12126 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, 12127 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, 12128 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, 12129 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, 12130 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, 12131 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, 12132 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, 12133 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, 12134 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, 12135 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, 12136 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, 12137 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, 12138 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, 12139 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, 12140 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, 12141 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, 12142 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, 12143 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, 12144 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, 12145 0x2d02ef8d 12146 @}; 12147 unsigned char *end; 12148 12149 crc = ~crc & 0xffffffff; 12150 for (end = buf + len; buf < end; ++buf) 12151 crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); 12152 return ~crc & 0xffffffff; 12153@} 12154@end smallexample 12155 12156@noindent 12157This computation does not apply to the ``build ID'' method. 12158 12159 12160@node Symbol Errors 12161@section Errors Reading Symbol Files 12162 12163While reading a symbol file, @value{GDBN} occasionally encounters problems, 12164such as symbol types it does not recognize, or known bugs in compiler 12165output. By default, @value{GDBN} does not notify you of such problems, since 12166they are relatively common and primarily of interest to people 12167debugging compilers. If you are interested in seeing information 12168about ill-constructed symbol tables, you can either ask @value{GDBN} to print 12169only one message about each such type of problem, no matter how many 12170times the problem occurs; or you can ask @value{GDBN} to print more messages, 12171to see how many times the problems occur, with the @code{set 12172complaints} command (@pxref{Messages/Warnings, ,Optional Warnings and 12173Messages}). 12174 12175The messages currently printed, and their meanings, include: 12176 12177@table @code 12178@item inner block not inside outer block in @var{symbol} 12179 12180The symbol information shows where symbol scopes begin and end 12181(such as at the start of a function or a block of statements). This 12182error indicates that an inner scope block is not fully contained 12183in its outer scope blocks. 12184 12185@value{GDBN} circumvents the problem by treating the inner block as if it had 12186the same scope as the outer block. In the error message, @var{symbol} 12187may be shown as ``@code{(don't know)}'' if the outer block is not a 12188function. 12189 12190@item block at @var{address} out of order 12191 12192The symbol information for symbol scope blocks should occur in 12193order of increasing addresses. This error indicates that it does not 12194do so. 12195 12196@value{GDBN} does not circumvent this problem, and has trouble 12197locating symbols in the source file whose symbols it is reading. (You 12198can often determine what source file is affected by specifying 12199@code{set verbose on}. @xref{Messages/Warnings, ,Optional Warnings and 12200Messages}.) 12201 12202@item bad block start address patched 12203 12204The symbol information for a symbol scope block has a start address 12205smaller than the address of the preceding source line. This is known 12206to occur in the SunOS 4.1.1 (and earlier) C compiler. 12207 12208@value{GDBN} circumvents the problem by treating the symbol scope block as 12209starting on the previous source line. 12210 12211@item bad string table offset in symbol @var{n} 12212 12213@cindex foo 12214Symbol number @var{n} contains a pointer into the string table which is 12215larger than the size of the string table. 12216 12217@value{GDBN} circumvents the problem by considering the symbol to have the 12218name @code{foo}, which may cause other problems if many symbols end up 12219with this name. 12220 12221@item unknown symbol type @code{0x@var{nn}} 12222 12223The symbol information contains new data types that @value{GDBN} does 12224not yet know how to read. @code{0x@var{nn}} is the symbol type of the 12225uncomprehended information, in hexadecimal. 12226 12227@value{GDBN} circumvents the error by ignoring this symbol information. 12228This usually allows you to debug your program, though certain symbols 12229are not accessible. If you encounter such a problem and feel like 12230debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint 12231on @code{complain}, then go up to the function @code{read_dbx_symtab} 12232and examine @code{*bufp} to see the symbol. 12233 12234@item stub type has NULL name 12235 12236@value{GDBN} could not find the full definition for a struct or class. 12237 12238@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{} 12239The symbol information for a C@t{++} member function is missing some 12240information that recent versions of the compiler should have output for 12241it. 12242 12243@item info mismatch between compiler and debugger 12244 12245@value{GDBN} could not parse a type specification output by the compiler. 12246 12247@end table 12248 12249@node Targets 12250@chapter Specifying a Debugging Target 12251 12252@cindex debugging target 12253A @dfn{target} is the execution environment occupied by your program. 12254 12255Often, @value{GDBN} runs in the same host environment as your program; 12256in that case, the debugging target is specified as a side effect when 12257you use the @code{file} or @code{core} commands. When you need more 12258flexibility---for example, running @value{GDBN} on a physically separate 12259host, or controlling a standalone system over a serial port or a 12260realtime system over a TCP/IP connection---you can use the @code{target} 12261command to specify one of the target types configured for @value{GDBN} 12262(@pxref{Target Commands, ,Commands for Managing Targets}). 12263 12264@cindex target architecture 12265It is possible to build @value{GDBN} for several different @dfn{target 12266architectures}. When @value{GDBN} is built like that, you can choose 12267one of the available architectures with the @kbd{set architecture} 12268command. 12269 12270@table @code 12271@kindex set architecture 12272@kindex show architecture 12273@item set architecture @var{arch} 12274This command sets the current target architecture to @var{arch}. The 12275value of @var{arch} can be @code{"auto"}, in addition to one of the 12276supported architectures. 12277 12278@item show architecture 12279Show the current target architecture. 12280 12281@item set processor 12282@itemx processor 12283@kindex set processor 12284@kindex show processor 12285These are alias commands for, respectively, @code{set architecture} 12286and @code{show architecture}. 12287@end table 12288 12289@menu 12290* Active Targets:: Active targets 12291* Target Commands:: Commands for managing targets 12292* Byte Order:: Choosing target byte order 12293@end menu 12294 12295@node Active Targets 12296@section Active Targets 12297 12298@cindex stacking targets 12299@cindex active targets 12300@cindex multiple targets 12301 12302There are three classes of targets: processes, core files, and 12303executable files. @value{GDBN} can work concurrently on up to three 12304active targets, one in each class. This allows you to (for example) 12305start a process and inspect its activity without abandoning your work on 12306a core file. 12307 12308For example, if you execute @samp{gdb a.out}, then the executable file 12309@code{a.out} is the only active target. If you designate a core file as 12310well---presumably from a prior run that crashed and coredumped---then 12311@value{GDBN} has two active targets and uses them in tandem, looking 12312first in the corefile target, then in the executable file, to satisfy 12313requests for memory addresses. (Typically, these two classes of target 12314are complementary, since core files contain only a program's 12315read-write memory---variables and so on---plus machine status, while 12316executable files contain only the program text and initialized data.) 12317 12318When you type @code{run}, your executable file becomes an active process 12319target as well. When a process target is active, all @value{GDBN} 12320commands requesting memory addresses refer to that target; addresses in 12321an active core file or executable file target are obscured while the 12322process target is active. 12323 12324Use the @code{core-file} and @code{exec-file} commands to select a new 12325core file or executable target (@pxref{Files, ,Commands to Specify 12326Files}). To specify as a target a process that is already running, use 12327the @code{attach} command (@pxref{Attach, ,Debugging an Already-running 12328Process}). 12329 12330@node Target Commands 12331@section Commands for Managing Targets 12332 12333@table @code 12334@item target @var{type} @var{parameters} 12335Connects the @value{GDBN} host environment to a target machine or 12336process. A target is typically a protocol for talking to debugging 12337facilities. You use the argument @var{type} to specify the type or 12338protocol of the target machine. 12339 12340Further @var{parameters} are interpreted by the target protocol, but 12341typically include things like device names or host names to connect 12342with, process numbers, and baud rates. 12343 12344The @code{target} command does not repeat if you press @key{RET} again 12345after executing the command. 12346 12347@kindex help target 12348@item help target 12349Displays the names of all targets available. To display targets 12350currently selected, use either @code{info target} or @code{info files} 12351(@pxref{Files, ,Commands to Specify Files}). 12352 12353@item help target @var{name} 12354Describe a particular target, including any parameters necessary to 12355select it. 12356 12357@kindex set gnutarget 12358@item set gnutarget @var{args} 12359@value{GDBN} uses its own library BFD to read your files. @value{GDBN} 12360knows whether it is reading an @dfn{executable}, 12361a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format 12362with the @code{set gnutarget} command. Unlike most @code{target} commands, 12363with @code{gnutarget} the @code{target} refers to a program, not a machine. 12364 12365@quotation 12366@emph{Warning:} To specify a file format with @code{set gnutarget}, 12367you must know the actual BFD name. 12368@end quotation 12369 12370@noindent 12371@xref{Files, , Commands to Specify Files}. 12372 12373@kindex show gnutarget 12374@item show gnutarget 12375Use the @code{show gnutarget} command to display what file format 12376@code{gnutarget} is set to read. If you have not set @code{gnutarget}, 12377@value{GDBN} will determine the file format for each file automatically, 12378and @code{show gnutarget} displays @samp{The current BDF target is "auto"}. 12379@end table 12380 12381@cindex common targets 12382Here are some common targets (available, or not, depending on the GDB 12383configuration): 12384 12385@table @code 12386@kindex target 12387@item target exec @var{program} 12388@cindex executable file target 12389An executable file. @samp{target exec @var{program}} is the same as 12390@samp{exec-file @var{program}}. 12391 12392@item target core @var{filename} 12393@cindex core dump file target 12394A core dump file. @samp{target core @var{filename}} is the same as 12395@samp{core-file @var{filename}}. 12396 12397@item target remote @var{medium} 12398@cindex remote target 12399A remote system connected to @value{GDBN} via a serial line or network 12400connection. This command tells @value{GDBN} to use its own remote 12401protocol over @var{medium} for debugging. @xref{Remote Debugging}. 12402 12403For example, if you have a board connected to @file{/dev/ttya} on the 12404machine running @value{GDBN}, you could say: 12405 12406@smallexample 12407target remote /dev/ttya 12408@end smallexample 12409 12410@code{target remote} supports the @code{load} command. This is only 12411useful if you have some other way of getting the stub to the target 12412system, and you can put it somewhere in memory where it won't get 12413clobbered by the download. 12414 12415@item target sim 12416@cindex built-in simulator target 12417Builtin CPU simulator. @value{GDBN} includes simulators for most architectures. 12418In general, 12419@smallexample 12420 target sim 12421 load 12422 run 12423@end smallexample 12424@noindent 12425works; however, you cannot assume that a specific memory map, device 12426drivers, or even basic I/O is available, although some simulators do 12427provide these. For info about any processor-specific simulator details, 12428see the appropriate section in @ref{Embedded Processors, ,Embedded 12429Processors}. 12430 12431@end table 12432 12433Some configurations may include these targets as well: 12434 12435@table @code 12436 12437@item target nrom @var{dev} 12438@cindex NetROM ROM emulator target 12439NetROM ROM emulator. This target only supports downloading. 12440 12441@end table 12442 12443Different targets are available on different configurations of @value{GDBN}; 12444your configuration may have more or fewer targets. 12445 12446Many remote targets require you to download the executable's code once 12447you've successfully established a connection. You may wish to control 12448various aspects of this process. 12449 12450@table @code 12451 12452@item set hash 12453@kindex set hash@r{, for remote monitors} 12454@cindex hash mark while downloading 12455This command controls whether a hash mark @samp{#} is displayed while 12456downloading a file to the remote monitor. If on, a hash mark is 12457displayed after each S-record is successfully downloaded to the 12458monitor. 12459 12460@item show hash 12461@kindex show hash@r{, for remote monitors} 12462Show the current status of displaying the hash mark. 12463 12464@item set debug monitor 12465@kindex set debug monitor 12466@cindex display remote monitor communications 12467Enable or disable display of communications messages between 12468@value{GDBN} and the remote monitor. 12469 12470@item show debug monitor 12471@kindex show debug monitor 12472Show the current status of displaying communications between 12473@value{GDBN} and the remote monitor. 12474@end table 12475 12476@table @code 12477 12478@kindex load @var{filename} 12479@item load @var{filename} 12480Depending on what remote debugging facilities are configured into 12481@value{GDBN}, the @code{load} command may be available. Where it exists, it 12482is meant to make @var{filename} (an executable) available for debugging 12483on the remote system---by downloading, or dynamic linking, for example. 12484@code{load} also records the @var{filename} symbol table in @value{GDBN}, like 12485the @code{add-symbol-file} command. 12486 12487If your @value{GDBN} does not have a @code{load} command, attempting to 12488execute it gets the error message ``@code{You can't do that when your 12489target is @dots{}}'' 12490 12491The file is loaded at whatever address is specified in the executable. 12492For some object file formats, you can specify the load address when you 12493link the program; for other formats, like a.out, the object file format 12494specifies a fixed address. 12495@c FIXME! This would be a good place for an xref to the GNU linker doc. 12496 12497Depending on the remote side capabilities, @value{GDBN} may be able to 12498load programs into flash memory. 12499 12500@code{load} does not repeat if you press @key{RET} again after using it. 12501@end table 12502 12503@node Byte Order 12504@section Choosing Target Byte Order 12505 12506@cindex choosing target byte order 12507@cindex target byte order 12508 12509Some types of processors, such as the MIPS, PowerPC, and Renesas SH, 12510offer the ability to run either big-endian or little-endian byte 12511orders. Usually the executable or symbol will include a bit to 12512designate the endian-ness, and you will not need to worry about 12513which to use. However, you may still find it useful to adjust 12514@value{GDBN}'s idea of processor endian-ness manually. 12515 12516@table @code 12517@kindex set endian 12518@item set endian big 12519Instruct @value{GDBN} to assume the target is big-endian. 12520 12521@item set endian little 12522Instruct @value{GDBN} to assume the target is little-endian. 12523 12524@item set endian auto 12525Instruct @value{GDBN} to use the byte order associated with the 12526executable. 12527 12528@item show endian 12529Display @value{GDBN}'s current idea of the target byte order. 12530 12531@end table 12532 12533Note that these commands merely adjust interpretation of symbolic 12534data on the host, and that they have absolutely no effect on the 12535target system. 12536 12537 12538@node Remote Debugging 12539@chapter Debugging Remote Programs 12540@cindex remote debugging 12541 12542If you are trying to debug a program running on a machine that cannot run 12543@value{GDBN} in the usual way, it is often useful to use remote debugging. 12544For example, you might use remote debugging on an operating system kernel, 12545or on a small system which does not have a general purpose operating system 12546powerful enough to run a full-featured debugger. 12547 12548Some configurations of @value{GDBN} have special serial or TCP/IP interfaces 12549to make this work with particular debugging targets. In addition, 12550@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN}, 12551but not specific to any particular target system) which you can use if you 12552write the remote stubs---the code that runs on the remote system to 12553communicate with @value{GDBN}. 12554 12555Other remote targets may be available in your 12556configuration of @value{GDBN}; use @code{help target} to list them. 12557 12558@menu 12559* Connecting:: Connecting to a remote target 12560* Server:: Using the gdbserver program 12561* Remote Configuration:: Remote configuration 12562* Remote Stub:: Implementing a remote stub 12563@end menu 12564 12565@node Connecting 12566@section Connecting to a Remote Target 12567 12568On the @value{GDBN} host machine, you will need an unstripped copy of 12569your program, since @value{GDBN} needs symbol and debugging information. 12570Start up @value{GDBN} as usual, using the name of the local copy of your 12571program as the first argument. 12572 12573@cindex @code{target remote} 12574@value{GDBN} can communicate with the target over a serial line, or 12575over an @acronym{IP} network using @acronym{TCP} or @acronym{UDP}. In 12576each case, @value{GDBN} uses the same protocol for debugging your 12577program; only the medium carrying the debugging packets varies. The 12578@code{target remote} command establishes a connection to the target. 12579Its arguments indicate which medium to use: 12580 12581@table @code 12582 12583@item target remote @var{serial-device} 12584@cindex serial line, @code{target remote} 12585Use @var{serial-device} to communicate with the target. For example, 12586to use a serial line connected to the device named @file{/dev/ttyb}: 12587 12588@smallexample 12589target remote /dev/ttyb 12590@end smallexample 12591 12592If you're using a serial line, you may want to give @value{GDBN} the 12593@w{@samp{--baud}} option, or use the @code{set remotebaud} command 12594(@pxref{Remote Configuration, set remotebaud}) before the 12595@code{target} command. 12596 12597@item target remote @code{@var{host}:@var{port}} 12598@itemx target remote @code{tcp:@var{host}:@var{port}} 12599@cindex @acronym{TCP} port, @code{target remote} 12600Debug using a @acronym{TCP} connection to @var{port} on @var{host}. 12601The @var{host} may be either a host name or a numeric @acronym{IP} 12602address; @var{port} must be a decimal number. The @var{host} could be 12603the target machine itself, if it is directly connected to the net, or 12604it might be a terminal server which in turn has a serial line to the 12605target. 12606 12607For example, to connect to port 2828 on a terminal server named 12608@code{manyfarms}: 12609 12610@smallexample 12611target remote manyfarms:2828 12612@end smallexample 12613 12614If your remote target is actually running on the same machine as your 12615debugger session (e.g.@: a simulator for your target running on the 12616same host), you can omit the hostname. For example, to connect to 12617port 1234 on your local machine: 12618 12619@smallexample 12620target remote :1234 12621@end smallexample 12622@noindent 12623 12624Note that the colon is still required here. 12625 12626@item target remote @code{udp:@var{host}:@var{port}} 12627@cindex @acronym{UDP} port, @code{target remote} 12628Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to 12629connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}: 12630 12631@smallexample 12632target remote udp:manyfarms:2828 12633@end smallexample 12634 12635When using a @acronym{UDP} connection for remote debugging, you should 12636keep in mind that the `U' stands for ``Unreliable''. @acronym{UDP} 12637can silently drop packets on busy or unreliable networks, which will 12638cause havoc with your debugging session. 12639 12640@item target remote | @var{command} 12641@cindex pipe, @code{target remote} to 12642Run @var{command} in the background and communicate with it using a 12643pipe. The @var{command} is a shell command, to be parsed and expanded 12644by the system's command shell, @code{/bin/sh}; it should expect remote 12645protocol packets on its standard input, and send replies on its 12646standard output. You could use this to run a stand-alone simulator 12647that speaks the remote debugging protocol, to make net connections 12648using programs like @code{ssh}, or for other similar tricks. 12649 12650If @var{command} closes its standard output (perhaps by exiting), 12651@value{GDBN} will try to send it a @code{SIGTERM} signal. (If the 12652program has already exited, this will have no effect.) 12653 12654@end table 12655 12656Once the connection has been established, you can use all the usual 12657commands to examine and change data and to step and continue the 12658remote program. 12659 12660@cindex interrupting remote programs 12661@cindex remote programs, interrupting 12662Whenever @value{GDBN} is waiting for the remote program, if you type the 12663interrupt character (often @kbd{Ctrl-c}), @value{GDBN} attempts to stop the 12664program. This may or may not succeed, depending in part on the hardware 12665and the serial drivers the remote system uses. If you type the 12666interrupt character once again, @value{GDBN} displays this prompt: 12667 12668@smallexample 12669Interrupted while waiting for the program. 12670Give up (and stop debugging it)? (y or n) 12671@end smallexample 12672 12673If you type @kbd{y}, @value{GDBN} abandons the remote debugging session. 12674(If you decide you want to try again later, you can use @samp{target 12675remote} again to connect once more.) If you type @kbd{n}, @value{GDBN} 12676goes back to waiting. 12677 12678@table @code 12679@kindex detach (remote) 12680@item detach 12681When you have finished debugging the remote program, you can use the 12682@code{detach} command to release it from @value{GDBN} control. 12683Detaching from the target normally resumes its execution, but the results 12684will depend on your particular remote stub. After the @code{detach} 12685command, @value{GDBN} is free to connect to another target. 12686 12687@kindex disconnect 12688@item disconnect 12689The @code{disconnect} command behaves like @code{detach}, except that 12690the target is generally not resumed. It will wait for @value{GDBN} 12691(this instance or another one) to connect and continue debugging. After 12692the @code{disconnect} command, @value{GDBN} is again free to connect to 12693another target. 12694 12695@cindex send command to remote monitor 12696@cindex extend @value{GDBN} for remote targets 12697@cindex add new commands for external monitor 12698@kindex monitor 12699@item monitor @var{cmd} 12700This command allows you to send arbitrary commands directly to the 12701remote monitor. Since @value{GDBN} doesn't care about the commands it 12702sends like this, this command is the way to extend @value{GDBN}---you 12703can add new commands that only the external monitor will understand 12704and implement. 12705@end table 12706 12707@node Server 12708@section Using the @code{gdbserver} Program 12709 12710@kindex gdbserver 12711@cindex remote connection without stubs 12712@code{gdbserver} is a control program for Unix-like systems, which 12713allows you to connect your program with a remote @value{GDBN} via 12714@code{target remote}---but without linking in the usual debugging stub. 12715 12716@code{gdbserver} is not a complete replacement for the debugging stubs, 12717because it requires essentially the same operating-system facilities 12718that @value{GDBN} itself does. In fact, a system that can run 12719@code{gdbserver} to connect to a remote @value{GDBN} could also run 12720@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless, 12721because it is a much smaller program than @value{GDBN} itself. It is 12722also easier to port than all of @value{GDBN}, so you may be able to get 12723started more quickly on a new system by using @code{gdbserver}. 12724Finally, if you develop code for real-time systems, you may find that 12725the tradeoffs involved in real-time operation make it more convenient to 12726do as much development work as possible on another system, for example 12727by cross-compiling. You can use @code{gdbserver} to make a similar 12728choice for debugging. 12729 12730@value{GDBN} and @code{gdbserver} communicate via either a serial line 12731or a TCP connection, using the standard @value{GDBN} remote serial 12732protocol. 12733 12734@table @emph 12735@item On the target machine, 12736you need to have a copy of the program you want to debug. 12737@code{gdbserver} does not need your program's symbol table, so you can 12738strip the program if necessary to save space. @value{GDBN} on the host 12739system does all the symbol handling. 12740 12741To use the server, you must tell it how to communicate with @value{GDBN}; 12742the name of your program; and the arguments for your program. The usual 12743syntax is: 12744 12745@smallexample 12746target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ] 12747@end smallexample 12748 12749@var{comm} is either a device name (to use a serial line) or a TCP 12750hostname and portnumber. For example, to debug Emacs with the argument 12751@samp{foo.txt} and communicate with @value{GDBN} over the serial port 12752@file{/dev/com1}: 12753 12754@smallexample 12755target> gdbserver /dev/com1 emacs foo.txt 12756@end smallexample 12757 12758@code{gdbserver} waits passively for the host @value{GDBN} to communicate 12759with it. 12760 12761To use a TCP connection instead of a serial line: 12762 12763@smallexample 12764target> gdbserver host:2345 emacs foo.txt 12765@end smallexample 12766 12767The only difference from the previous example is the first argument, 12768specifying that you are communicating with the host @value{GDBN} via 12769TCP. The @samp{host:2345} argument means that @code{gdbserver} is to 12770expect a TCP connection from machine @samp{host} to local TCP port 2345. 12771(Currently, the @samp{host} part is ignored.) You can choose any number 12772you want for the port number as long as it does not conflict with any 12773TCP ports already in use on the target system (for example, @code{23} is 12774reserved for @code{telnet}).@footnote{If you choose a port number that 12775conflicts with another service, @code{gdbserver} prints an error message 12776and exits.} You must use the same port number with the host @value{GDBN} 12777@code{target remote} command. 12778 12779On some targets, @code{gdbserver} can also attach to running programs. 12780This is accomplished via the @code{--attach} argument. The syntax is: 12781 12782@smallexample 12783target> gdbserver @var{comm} --attach @var{pid} 12784@end smallexample 12785 12786@var{pid} is the process ID of a currently running process. It isn't necessary 12787to point @code{gdbserver} at a binary for the running process. 12788 12789@pindex pidof 12790@cindex attach to a program by name 12791You can debug processes by name instead of process ID if your target has the 12792@code{pidof} utility: 12793 12794@smallexample 12795target> gdbserver @var{comm} --attach `pidof @var{program}` 12796@end smallexample 12797 12798In case more than one copy of @var{program} is running, or @var{program} 12799has multiple threads, most versions of @code{pidof} support the 12800@code{-s} option to only return the first process ID. 12801 12802@item On the host machine, 12803first make sure you have the necessary symbol files. Load symbols for 12804your application using the @code{file} command before you connect. Use 12805@code{set sysroot} to locate target libraries (unless your @value{GDBN} 12806was compiled with the correct sysroot using @code{--with-system-root}). 12807 12808The symbol file and target libraries must exactly match the executable 12809and libraries on the target, with one exception: the files on the host 12810system should not be stripped, even if the files on the target system 12811are. Mismatched or missing files will lead to confusing results 12812during debugging. On @sc{gnu}/Linux targets, mismatched or missing 12813files may also prevent @code{gdbserver} from debugging multi-threaded 12814programs. 12815 12816Connect to your target (@pxref{Connecting,,Connecting to a Remote Target}). 12817For TCP connections, you must start up @code{gdbserver} prior to using 12818the @code{target remote} command. Otherwise you may get an error whose 12819text depends on the host system, but which usually looks something like 12820@samp{Connection refused}. You don't need to use the @code{load} 12821command in @value{GDBN} when using @code{gdbserver}, since the program is 12822already on the target. 12823 12824@end table 12825 12826@subsection Monitor Commands for @code{gdbserver} 12827@cindex monitor commands, for @code{gdbserver} 12828 12829During a @value{GDBN} session using @code{gdbserver}, you can use the 12830@code{monitor} command to send special requests to @code{gdbserver}. 12831Here are the available commands; they are only of interest when 12832debugging @value{GDBN} or @code{gdbserver}. 12833 12834@table @code 12835@item monitor help 12836List the available monitor commands. 12837 12838@item monitor set debug 0 12839@itemx monitor set debug 1 12840Disable or enable general debugging messages. 12841 12842@item monitor set remote-debug 0 12843@itemx monitor set remote-debug 1 12844Disable or enable specific debugging messages associated with the remote 12845protocol (@pxref{Remote Protocol}). 12846 12847@end table 12848 12849@node Remote Configuration 12850@section Remote Configuration 12851 12852@kindex set remote 12853@kindex show remote 12854This section documents the configuration options available when 12855debugging remote programs. For the options related to the File I/O 12856extensions of the remote protocol, see @ref{system, 12857system-call-allowed}. 12858 12859@table @code 12860@item set remoteaddresssize @var{bits} 12861@cindex address size for remote targets 12862@cindex bits in remote address 12863Set the maximum size of address in a memory packet to the specified 12864number of bits. @value{GDBN} will mask off the address bits above 12865that number, when it passes addresses to the remote target. The 12866default value is the number of bits in the target's address. 12867 12868@item show remoteaddresssize 12869Show the current value of remote address size in bits. 12870 12871@item set remotebaud @var{n} 12872@cindex baud rate for remote targets 12873Set the baud rate for the remote serial I/O to @var{n} baud. The 12874value is used to set the speed of the serial port used for debugging 12875remote targets. 12876 12877@item show remotebaud 12878Show the current speed of the remote connection. 12879 12880@item set remotebreak 12881@cindex interrupt remote programs 12882@cindex BREAK signal instead of Ctrl-C 12883@anchor{set remotebreak} 12884If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote 12885when you type @kbd{Ctrl-c} to interrupt the program running 12886on the remote. If set to off, @value{GDBN} sends the @samp{Ctrl-C} 12887character instead. The default is off, since most remote systems 12888expect to see @samp{Ctrl-C} as the interrupt signal. 12889 12890@item show remotebreak 12891Show whether @value{GDBN} sends @code{BREAK} or @samp{Ctrl-C} to 12892interrupt the remote program. 12893 12894@item set remoteflow on 12895@itemx set remoteflow off 12896@kindex set remoteflow 12897Enable or disable hardware flow control (@code{RTS}/@code{CTS}) 12898on the serial port used to communicate to the remote target. 12899 12900@item show remoteflow 12901@kindex show remoteflow 12902Show the current setting of hardware flow control. 12903 12904@item set remotelogbase @var{base} 12905Set the base (a.k.a.@: radix) of logging serial protocol 12906communications to @var{base}. Supported values of @var{base} are: 12907@code{ascii}, @code{octal}, and @code{hex}. The default is 12908@code{ascii}. 12909 12910@item show remotelogbase 12911Show the current setting of the radix for logging remote serial 12912protocol. 12913 12914@item set remotelogfile @var{file} 12915@cindex record serial communications on file 12916Record remote serial communications on the named @var{file}. The 12917default is not to record at all. 12918 12919@item show remotelogfile. 12920Show the current setting of the file name on which to record the 12921serial communications. 12922 12923@item set remotetimeout @var{num} 12924@cindex timeout for serial communications 12925@cindex remote timeout 12926Set the timeout limit to wait for the remote target to respond to 12927@var{num} seconds. The default is 2 seconds. 12928 12929@item show remotetimeout 12930Show the current number of seconds to wait for the remote target 12931responses. 12932 12933@cindex limit hardware breakpoints and watchpoints 12934@cindex remote target, limit break- and watchpoints 12935@anchor{set remote hardware-watchpoint-limit} 12936@anchor{set remote hardware-breakpoint-limit} 12937@item set remote hardware-watchpoint-limit @var{limit} 12938@itemx set remote hardware-breakpoint-limit @var{limit} 12939Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or 12940watchpoints. A limit of -1, the default, is treated as unlimited. 12941@end table 12942 12943@cindex remote packets, enabling and disabling 12944The @value{GDBN} remote protocol autodetects the packets supported by 12945your debugging stub. If you need to override the autodetection, you 12946can use these commands to enable or disable individual packets. Each 12947packet can be set to @samp{on} (the remote target supports this 12948packet), @samp{off} (the remote target does not support this packet), 12949or @samp{auto} (detect remote target support for this packet). They 12950all default to @samp{auto}. For more information about each packet, 12951see @ref{Remote Protocol}. 12952 12953During normal use, you should not have to use any of these commands. 12954If you do, that may be a bug in your remote debugging stub, or a bug 12955in @value{GDBN}. You may want to report the problem to the 12956@value{GDBN} developers. 12957 12958For each packet @var{name}, the command to enable or disable the 12959packet is @code{set remote @var{name}-packet}. The available settings 12960are: 12961 12962@multitable @columnfractions 0.28 0.32 0.25 12963@item Command Name 12964@tab Remote Packet 12965@tab Related Features 12966 12967@item @code{fetch-register} 12968@tab @code{p} 12969@tab @code{info registers} 12970 12971@item @code{set-register} 12972@tab @code{P} 12973@tab @code{set} 12974 12975@item @code{binary-download} 12976@tab @code{X} 12977@tab @code{load}, @code{set} 12978 12979@item @code{read-aux-vector} 12980@tab @code{qXfer:auxv:read} 12981@tab @code{info auxv} 12982 12983@item @code{symbol-lookup} 12984@tab @code{qSymbol} 12985@tab Detecting multiple threads 12986 12987@item @code{verbose-resume} 12988@tab @code{vCont} 12989@tab Stepping or resuming multiple threads 12990 12991@item @code{software-breakpoint} 12992@tab @code{Z0} 12993@tab @code{break} 12994 12995@item @code{hardware-breakpoint} 12996@tab @code{Z1} 12997@tab @code{hbreak} 12998 12999@item @code{write-watchpoint} 13000@tab @code{Z2} 13001@tab @code{watch} 13002 13003@item @code{read-watchpoint} 13004@tab @code{Z3} 13005@tab @code{rwatch} 13006 13007@item @code{access-watchpoint} 13008@tab @code{Z4} 13009@tab @code{awatch} 13010 13011@item @code{target-features} 13012@tab @code{qXfer:features:read} 13013@tab @code{set architecture} 13014 13015@item @code{library-info} 13016@tab @code{qXfer:libraries:read} 13017@tab @code{info sharedlibrary} 13018 13019@item @code{memory-map} 13020@tab @code{qXfer:memory-map:read} 13021@tab @code{info mem} 13022 13023@item @code{read-spu-object} 13024@tab @code{qXfer:spu:read} 13025@tab @code{info spu} 13026 13027@item @code{write-spu-object} 13028@tab @code{qXfer:spu:write} 13029@tab @code{info spu} 13030 13031@item @code{get-thread-local-@*storage-address} 13032@tab @code{qGetTLSAddr} 13033@tab Displaying @code{__thread} variables 13034 13035@item @code{supported-packets} 13036@tab @code{qSupported} 13037@tab Remote communications parameters 13038 13039@item @code{pass-signals} 13040@tab @code{QPassSignals} 13041@tab @code{handle @var{signal}} 13042 13043@end multitable 13044 13045@node Remote Stub 13046@section Implementing a Remote Stub 13047 13048@cindex debugging stub, example 13049@cindex remote stub, example 13050@cindex stub example, remote debugging 13051The stub files provided with @value{GDBN} implement the target side of the 13052communication protocol, and the @value{GDBN} side is implemented in the 13053@value{GDBN} source file @file{remote.c}. Normally, you can simply allow 13054these subroutines to communicate, and ignore the details. (If you're 13055implementing your own stub file, you can still ignore the details: start 13056with one of the existing stub files. @file{sparc-stub.c} is the best 13057organized, and therefore the easiest to read.) 13058 13059@cindex remote serial debugging, overview 13060To debug a program running on another machine (the debugging 13061@dfn{target} machine), you must first arrange for all the usual 13062prerequisites for the program to run by itself. For example, for a C 13063program, you need: 13064 13065@enumerate 13066@item 13067A startup routine to set up the C runtime environment; these usually 13068have a name like @file{crt0}. The startup routine may be supplied by 13069your hardware supplier, or you may have to write your own. 13070 13071@item 13072A C subroutine library to support your program's 13073subroutine calls, notably managing input and output. 13074 13075@item 13076A way of getting your program to the other machine---for example, a 13077download program. These are often supplied by the hardware 13078manufacturer, but you may have to write your own from hardware 13079documentation. 13080@end enumerate 13081 13082The next step is to arrange for your program to use a serial port to 13083communicate with the machine where @value{GDBN} is running (the @dfn{host} 13084machine). In general terms, the scheme looks like this: 13085 13086@table @emph 13087@item On the host, 13088@value{GDBN} already understands how to use this protocol; when everything 13089else is set up, you can simply use the @samp{target remote} command 13090(@pxref{Targets,,Specifying a Debugging Target}). 13091 13092@item On the target, 13093you must link with your program a few special-purpose subroutines that 13094implement the @value{GDBN} remote serial protocol. The file containing these 13095subroutines is called a @dfn{debugging stub}. 13096 13097On certain remote targets, you can use an auxiliary program 13098@code{gdbserver} instead of linking a stub into your program. 13099@xref{Server,,Using the @code{gdbserver} Program}, for details. 13100@end table 13101 13102The debugging stub is specific to the architecture of the remote 13103machine; for example, use @file{sparc-stub.c} to debug programs on 13104@sc{sparc} boards. 13105 13106@cindex remote serial stub list 13107These working remote stubs are distributed with @value{GDBN}: 13108 13109@table @code 13110 13111@item i386-stub.c 13112@cindex @file{i386-stub.c} 13113@cindex Intel 13114@cindex i386 13115For Intel 386 and compatible architectures. 13116 13117@item m68k-stub.c 13118@cindex @file{m68k-stub.c} 13119@cindex Motorola 680x0 13120@cindex m680x0 13121For Motorola 680x0 architectures. 13122 13123@item sh-stub.c 13124@cindex @file{sh-stub.c} 13125@cindex Renesas 13126@cindex SH 13127For Renesas SH architectures. 13128 13129@item sparc-stub.c 13130@cindex @file{sparc-stub.c} 13131@cindex Sparc 13132For @sc{sparc} architectures. 13133 13134@item sparcl-stub.c 13135@cindex @file{sparcl-stub.c} 13136@cindex Fujitsu 13137@cindex SparcLite 13138For Fujitsu @sc{sparclite} architectures. 13139 13140@end table 13141 13142The @file{README} file in the @value{GDBN} distribution may list other 13143recently added stubs. 13144 13145@menu 13146* Stub Contents:: What the stub can do for you 13147* Bootstrapping:: What you must do for the stub 13148* Debug Session:: Putting it all together 13149@end menu 13150 13151@node Stub Contents 13152@subsection What the Stub Can Do for You 13153 13154@cindex remote serial stub 13155The debugging stub for your architecture supplies these three 13156subroutines: 13157 13158@table @code 13159@item set_debug_traps 13160@findex set_debug_traps 13161@cindex remote serial stub, initialization 13162This routine arranges for @code{handle_exception} to run when your 13163program stops. You must call this subroutine explicitly near the 13164beginning of your program. 13165 13166@item handle_exception 13167@findex handle_exception 13168@cindex remote serial stub, main routine 13169This is the central workhorse, but your program never calls it 13170explicitly---the setup code arranges for @code{handle_exception} to 13171run when a trap is triggered. 13172 13173@code{handle_exception} takes control when your program stops during 13174execution (for example, on a breakpoint), and mediates communications 13175with @value{GDBN} on the host machine. This is where the communications 13176protocol is implemented; @code{handle_exception} acts as the @value{GDBN} 13177representative on the target machine. It begins by sending summary 13178information on the state of your program, then continues to execute, 13179retrieving and transmitting any information @value{GDBN} needs, until you 13180execute a @value{GDBN} command that makes your program resume; at that point, 13181@code{handle_exception} returns control to your own code on the target 13182machine. 13183 13184@item breakpoint 13185@cindex @code{breakpoint} subroutine, remote 13186Use this auxiliary subroutine to make your program contain a 13187breakpoint. Depending on the particular situation, this may be the only 13188way for @value{GDBN} to get control. For instance, if your target 13189machine has some sort of interrupt button, you won't need to call this; 13190pressing the interrupt button transfers control to 13191@code{handle_exception}---in effect, to @value{GDBN}. On some machines, 13192simply receiving characters on the serial port may also trigger a trap; 13193again, in that situation, you don't need to call @code{breakpoint} from 13194your own program---simply running @samp{target remote} from the host 13195@value{GDBN} session gets control. 13196 13197Call @code{breakpoint} if none of these is true, or if you simply want 13198to make certain your program stops at a predetermined point for the 13199start of your debugging session. 13200@end table 13201 13202@node Bootstrapping 13203@subsection What You Must Do for the Stub 13204 13205@cindex remote stub, support routines 13206The debugging stubs that come with @value{GDBN} are set up for a particular 13207chip architecture, but they have no information about the rest of your 13208debugging target machine. 13209 13210First of all you need to tell the stub how to communicate with the 13211serial port. 13212 13213@table @code 13214@item int getDebugChar() 13215@findex getDebugChar 13216Write this subroutine to read a single character from the serial port. 13217It may be identical to @code{getchar} for your target system; a 13218different name is used to allow you to distinguish the two if you wish. 13219 13220@item void putDebugChar(int) 13221@findex putDebugChar 13222Write this subroutine to write a single character to the serial port. 13223It may be identical to @code{putchar} for your target system; a 13224different name is used to allow you to distinguish the two if you wish. 13225@end table 13226 13227@cindex control C, and remote debugging 13228@cindex interrupting remote targets 13229If you want @value{GDBN} to be able to stop your program while it is 13230running, you need to use an interrupt-driven serial driver, and arrange 13231for it to stop when it receives a @code{^C} (@samp{\003}, the control-C 13232character). That is the character which @value{GDBN} uses to tell the 13233remote system to stop. 13234 13235Getting the debugging target to return the proper status to @value{GDBN} 13236probably requires changes to the standard stub; one quick and dirty way 13237is to just execute a breakpoint instruction (the ``dirty'' part is that 13238@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}). 13239 13240Other routines you need to supply are: 13241 13242@table @code 13243@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address}) 13244@findex exceptionHandler 13245Write this function to install @var{exception_address} in the exception 13246handling tables. You need to do this because the stub does not have any 13247way of knowing what the exception handling tables on your target system 13248are like (for example, the processor's table might be in @sc{rom}, 13249containing entries which point to a table in @sc{ram}). 13250@var{exception_number} is the exception number which should be changed; 13251its meaning is architecture-dependent (for example, different numbers 13252might represent divide by zero, misaligned access, etc). When this 13253exception occurs, control should be transferred directly to 13254@var{exception_address}, and the processor state (stack, registers, 13255and so on) should be just as it is when a processor exception occurs. So if 13256you want to use a jump instruction to reach @var{exception_address}, it 13257should be a simple jump, not a jump to subroutine. 13258 13259For the 386, @var{exception_address} should be installed as an interrupt 13260gate so that interrupts are masked while the handler runs. The gate 13261should be at privilege level 0 (the most privileged level). The 13262@sc{sparc} and 68k stubs are able to mask interrupts themselves without 13263help from @code{exceptionHandler}. 13264 13265@item void flush_i_cache() 13266@findex flush_i_cache 13267On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the 13268instruction cache, if any, on your target machine. If there is no 13269instruction cache, this subroutine may be a no-op. 13270 13271On target machines that have instruction caches, @value{GDBN} requires this 13272function to make certain that the state of your program is stable. 13273@end table 13274 13275@noindent 13276You must also make sure this library routine is available: 13277 13278@table @code 13279@item void *memset(void *, int, int) 13280@findex memset 13281This is the standard library function @code{memset} that sets an area of 13282memory to a known value. If you have one of the free versions of 13283@code{libc.a}, @code{memset} can be found there; otherwise, you must 13284either obtain it from your hardware manufacturer, or write your own. 13285@end table 13286 13287If you do not use the GNU C compiler, you may need other standard 13288library subroutines as well; this varies from one stub to another, 13289but in general the stubs are likely to use any of the common library 13290subroutines which @code{@value{NGCC}} generates as inline code. 13291 13292 13293@node Debug Session 13294@subsection Putting it All Together 13295 13296@cindex remote serial debugging summary 13297In summary, when your program is ready to debug, you must follow these 13298steps. 13299 13300@enumerate 13301@item 13302Make sure you have defined the supporting low-level routines 13303(@pxref{Bootstrapping,,What You Must Do for the Stub}): 13304@display 13305@code{getDebugChar}, @code{putDebugChar}, 13306@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}. 13307@end display 13308 13309@item 13310Insert these lines near the top of your program: 13311 13312@smallexample 13313set_debug_traps(); 13314breakpoint(); 13315@end smallexample 13316 13317@item 13318For the 680x0 stub only, you need to provide a variable called 13319@code{exceptionHook}. Normally you just use: 13320 13321@smallexample 13322void (*exceptionHook)() = 0; 13323@end smallexample 13324 13325@noindent 13326but if before calling @code{set_debug_traps}, you set it to point to a 13327function in your program, that function is called when 13328@code{@value{GDBN}} continues after stopping on a trap (for example, bus 13329error). The function indicated by @code{exceptionHook} is called with 13330one parameter: an @code{int} which is the exception number. 13331 13332@item 13333Compile and link together: your program, the @value{GDBN} debugging stub for 13334your target architecture, and the supporting subroutines. 13335 13336@item 13337Make sure you have a serial connection between your target machine and 13338the @value{GDBN} host, and identify the serial port on the host. 13339 13340@item 13341@c The "remote" target now provides a `load' command, so we should 13342@c document that. FIXME. 13343Download your program to your target machine (or get it there by 13344whatever means the manufacturer provides), and start it. 13345 13346@item 13347Start @value{GDBN} on the host, and connect to the target 13348(@pxref{Connecting,,Connecting to a Remote Target}). 13349 13350@end enumerate 13351 13352@node Configurations 13353@chapter Configuration-Specific Information 13354 13355While nearly all @value{GDBN} commands are available for all native and 13356cross versions of the debugger, there are some exceptions. This chapter 13357describes things that are only available in certain configurations. 13358 13359There are three major categories of configurations: native 13360configurations, where the host and target are the same, embedded 13361operating system configurations, which are usually the same for several 13362different processor architectures, and bare embedded processors, which 13363are quite different from each other. 13364 13365@menu 13366* Native:: 13367* Embedded OS:: 13368* Embedded Processors:: 13369* Architectures:: 13370@end menu 13371 13372@node Native 13373@section Native 13374 13375This section describes details specific to particular native 13376configurations. 13377 13378@menu 13379* HP-UX:: HP-UX 13380* BSD libkvm Interface:: Debugging BSD kernel memory images 13381* SVR4 Process Information:: SVR4 process information 13382* DJGPP Native:: Features specific to the DJGPP port 13383* Cygwin Native:: Features specific to the Cygwin port 13384* Hurd Native:: Features specific to @sc{gnu} Hurd 13385* Neutrino:: Features specific to QNX Neutrino 13386@end menu 13387 13388@node HP-UX 13389@subsection HP-UX 13390 13391On HP-UX systems, if you refer to a function or variable name that 13392begins with a dollar sign, @value{GDBN} searches for a user or system 13393name first, before it searches for a convenience variable. 13394 13395 13396@node BSD libkvm Interface 13397@subsection BSD libkvm Interface 13398 13399@cindex libkvm 13400@cindex kernel memory image 13401@cindex kernel crash dump 13402 13403BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory 13404interface that provides a uniform interface for accessing kernel virtual 13405memory images, including live systems and crash dumps. @value{GDBN} 13406uses this interface to allow you to debug live kernels and kernel crash 13407dumps on many native BSD configurations. This is implemented as a 13408special @code{kvm} debugging target. For debugging a live system, load 13409the currently running kernel into @value{GDBN} and connect to the 13410@code{kvm} target: 13411 13412@smallexample 13413(@value{GDBP}) @b{target kvm} 13414@end smallexample 13415 13416For debugging crash dumps, provide the file name of the crash dump as an 13417argument: 13418 13419@smallexample 13420(@value{GDBP}) @b{target kvm /var/crash/bsd.0} 13421@end smallexample 13422 13423Once connected to the @code{kvm} target, the following commands are 13424available: 13425 13426@table @code 13427@kindex kvm 13428@item kvm pcb 13429Set current context from the @dfn{Process Control Block} (PCB) address. 13430 13431@item kvm proc 13432Set current context from proc address. This command isn't available on 13433modern FreeBSD systems. 13434@end table 13435 13436@node SVR4 Process Information 13437@subsection SVR4 Process Information 13438@cindex /proc 13439@cindex examine process image 13440@cindex process info via @file{/proc} 13441 13442Many versions of SVR4 and compatible systems provide a facility called 13443@samp{/proc} that can be used to examine the image of a running 13444process using file-system subroutines. If @value{GDBN} is configured 13445for an operating system with this facility, the command @code{info 13446proc} is available to report information about the process running 13447your program, or about any process running on your system. @code{info 13448proc} works only on SVR4 systems that include the @code{procfs} code. 13449This includes, as of this writing, @sc{gnu}/Linux, OSF/1 (Digital 13450Unix), Solaris, Irix, and Unixware, but not HP-UX, for example. 13451 13452@table @code 13453@kindex info proc 13454@cindex process ID 13455@item info proc 13456@itemx info proc @var{process-id} 13457Summarize available information about any running process. If a 13458process ID is specified by @var{process-id}, display information about 13459that process; otherwise display information about the program being 13460debugged. The summary includes the debugged process ID, the command 13461line used to invoke it, its current working directory, and its 13462executable file's absolute file name. 13463 13464On some systems, @var{process-id} can be of the form 13465@samp{[@var{pid}]/@var{tid}} which specifies a certain thread ID 13466within a process. If the optional @var{pid} part is missing, it means 13467a thread from the process being debugged (the leading @samp{/} still 13468needs to be present, or else @value{GDBN} will interpret the number as 13469a process ID rather than a thread ID). 13470 13471@item info proc mappings 13472@cindex memory address space mappings 13473Report the memory address space ranges accessible in the program, with 13474information on whether the process has read, write, or execute access 13475rights to each range. On @sc{gnu}/Linux systems, each memory range 13476includes the object file which is mapped to that range, instead of the 13477memory access rights to that range. 13478 13479@item info proc stat 13480@itemx info proc status 13481@cindex process detailed status information 13482These subcommands are specific to @sc{gnu}/Linux systems. They show 13483the process-related information, including the user ID and group ID; 13484how many threads are there in the process; its virtual memory usage; 13485the signals that are pending, blocked, and ignored; its TTY; its 13486consumption of system and user time; its stack size; its @samp{nice} 13487value; etc. For more information, see the @samp{proc} man page 13488(type @kbd{man 5 proc} from your shell prompt). 13489 13490@item info proc all 13491Show all the information about the process described under all of the 13492above @code{info proc} subcommands. 13493 13494@ignore 13495@comment These sub-options of 'info proc' were not included when 13496@comment procfs.c was re-written. Keep their descriptions around 13497@comment against the day when someone finds the time to put them back in. 13498@kindex info proc times 13499@item info proc times 13500Starting time, user CPU time, and system CPU time for your program and 13501its children. 13502 13503@kindex info proc id 13504@item info proc id 13505Report on the process IDs related to your program: its own process ID, 13506the ID of its parent, the process group ID, and the session ID. 13507@end ignore 13508 13509@item set procfs-trace 13510@kindex set procfs-trace 13511@cindex @code{procfs} API calls 13512This command enables and disables tracing of @code{procfs} API calls. 13513 13514@item show procfs-trace 13515@kindex show procfs-trace 13516Show the current state of @code{procfs} API call tracing. 13517 13518@item set procfs-file @var{file} 13519@kindex set procfs-file 13520Tell @value{GDBN} to write @code{procfs} API trace to the named 13521@var{file}. @value{GDBN} appends the trace info to the previous 13522contents of the file. The default is to display the trace on the 13523standard output. 13524 13525@item show procfs-file 13526@kindex show procfs-file 13527Show the file to which @code{procfs} API trace is written. 13528 13529@item proc-trace-entry 13530@itemx proc-trace-exit 13531@itemx proc-untrace-entry 13532@itemx proc-untrace-exit 13533@kindex proc-trace-entry 13534@kindex proc-trace-exit 13535@kindex proc-untrace-entry 13536@kindex proc-untrace-exit 13537These commands enable and disable tracing of entries into and exits 13538from the @code{syscall} interface. 13539 13540@item info pidlist 13541@kindex info pidlist 13542@cindex process list, QNX Neutrino 13543For QNX Neutrino only, this command displays the list of all the 13544processes and all the threads within each process. 13545 13546@item info meminfo 13547@kindex info meminfo 13548@cindex mapinfo list, QNX Neutrino 13549For QNX Neutrino only, this command displays the list of all mapinfos. 13550@end table 13551 13552@node DJGPP Native 13553@subsection Features for Debugging @sc{djgpp} Programs 13554@cindex @sc{djgpp} debugging 13555@cindex native @sc{djgpp} debugging 13556@cindex MS-DOS-specific commands 13557 13558@cindex DPMI 13559@sc{djgpp} is a port of the @sc{gnu} development tools to MS-DOS and 13560MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs 13561that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on 13562top of real-mode DOS systems and their emulations. 13563 13564@value{GDBN} supports native debugging of @sc{djgpp} programs, and 13565defines a few commands specific to the @sc{djgpp} port. This 13566subsection describes those commands. 13567 13568@table @code 13569@kindex info dos 13570@item info dos 13571This is a prefix of @sc{djgpp}-specific commands which print 13572information about the target system and important OS structures. 13573 13574@kindex sysinfo 13575@cindex MS-DOS system info 13576@cindex free memory information (MS-DOS) 13577@item info dos sysinfo 13578This command displays assorted information about the underlying 13579platform: the CPU type and features, the OS version and flavor, the 13580DPMI version, and the available conventional and DPMI memory. 13581 13582@cindex GDT 13583@cindex LDT 13584@cindex IDT 13585@cindex segment descriptor tables 13586@cindex descriptor tables display 13587@item info dos gdt 13588@itemx info dos ldt 13589@itemx info dos idt 13590These 3 commands display entries from, respectively, Global, Local, 13591and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor 13592tables are data structures which store a descriptor for each segment 13593that is currently in use. The segment's selector is an index into a 13594descriptor table; the table entry for that index holds the 13595descriptor's base address and limit, and its attributes and access 13596rights. 13597 13598A typical @sc{djgpp} program uses 3 segments: a code segment, a data 13599segment (used for both data and the stack), and a DOS segment (which 13600allows access to DOS/BIOS data structures and absolute addresses in 13601conventional memory). However, the DPMI host will usually define 13602additional segments in order to support the DPMI environment. 13603 13604@cindex garbled pointers 13605These commands allow to display entries from the descriptor tables. 13606Without an argument, all entries from the specified table are 13607displayed. An argument, which should be an integer expression, means 13608display a single entry whose index is given by the argument. For 13609example, here's a convenient way to display information about the 13610debugged program's data segment: 13611 13612@smallexample 13613@exdent @code{(@value{GDBP}) info dos ldt $ds} 13614@exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)} 13615@end smallexample 13616 13617@noindent 13618This comes in handy when you want to see whether a pointer is outside 13619the data segment's limit (i.e.@: @dfn{garbled}). 13620 13621@cindex page tables display (MS-DOS) 13622@item info dos pde 13623@itemx info dos pte 13624These two commands display entries from, respectively, the Page 13625Directory and the Page Tables. Page Directories and Page Tables are 13626data structures which control how virtual memory addresses are mapped 13627into physical addresses. A Page Table includes an entry for every 13628page of memory that is mapped into the program's address space; there 13629may be several Page Tables, each one holding up to 4096 entries. A 13630Page Directory has up to 4096 entries, one each for every Page Table 13631that is currently in use. 13632 13633Without an argument, @kbd{info dos pde} displays the entire Page 13634Directory, and @kbd{info dos pte} displays all the entries in all of 13635the Page Tables. An argument, an integer expression, given to the 13636@kbd{info dos pde} command means display only that entry from the Page 13637Directory table. An argument given to the @kbd{info dos pte} command 13638means display entries from a single Page Table, the one pointed to by 13639the specified entry in the Page Directory. 13640 13641@cindex direct memory access (DMA) on MS-DOS 13642These commands are useful when your program uses @dfn{DMA} (Direct 13643Memory Access), which needs physical addresses to program the DMA 13644controller. 13645 13646These commands are supported only with some DPMI servers. 13647 13648@cindex physical address from linear address 13649@item info dos address-pte @var{addr} 13650This command displays the Page Table entry for a specified linear 13651address. The argument @var{addr} is a linear address which should 13652already have the appropriate segment's base address added to it, 13653because this command accepts addresses which may belong to @emph{any} 13654segment. For example, here's how to display the Page Table entry for 13655the page where a variable @code{i} is stored: 13656 13657@smallexample 13658@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i} 13659@exdent @code{Page Table entry for address 0x11a00d30:} 13660@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30} 13661@end smallexample 13662 13663@noindent 13664This says that @code{i} is stored at offset @code{0xd30} from the page 13665whose physical base address is @code{0x02698000}, and shows all the 13666attributes of that page. 13667 13668Note that you must cast the addresses of variables to a @code{char *}, 13669since otherwise the value of @code{__djgpp_base_address}, the base 13670address of all variables and functions in a @sc{djgpp} program, will 13671be added using the rules of C pointer arithmetics: if @code{i} is 13672declared an @code{int}, @value{GDBN} will add 4 times the value of 13673@code{__djgpp_base_address} to the address of @code{i}. 13674 13675Here's another example, it displays the Page Table entry for the 13676transfer buffer: 13677 13678@smallexample 13679@exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)} 13680@exdent @code{Page Table entry for address 0x29110:} 13681@exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110} 13682@end smallexample 13683 13684@noindent 13685(The @code{+ 3} offset is because the transfer buffer's address is the 136863rd member of the @code{_go32_info_block} structure.) The output 13687clearly shows that this DPMI server maps the addresses in conventional 13688memory 1:1, i.e.@: the physical (@code{0x00029000} + @code{0x110}) and 13689linear (@code{0x29110}) addresses are identical. 13690 13691This command is supported only with some DPMI servers. 13692@end table 13693 13694@cindex DOS serial data link, remote debugging 13695In addition to native debugging, the DJGPP port supports remote 13696debugging via a serial data link. The following commands are specific 13697to remote serial debugging in the DJGPP port of @value{GDBN}. 13698 13699@table @code 13700@kindex set com1base 13701@kindex set com1irq 13702@kindex set com2base 13703@kindex set com2irq 13704@kindex set com3base 13705@kindex set com3irq 13706@kindex set com4base 13707@kindex set com4irq 13708@item set com1base @var{addr} 13709This command sets the base I/O port address of the @file{COM1} serial 13710port. 13711 13712@item set com1irq @var{irq} 13713This command sets the @dfn{Interrupt Request} (@code{IRQ}) line to use 13714for the @file{COM1} serial port. 13715 13716There are similar commands @samp{set com2base}, @samp{set com3irq}, 13717etc.@: for setting the port address and the @code{IRQ} lines for the 13718other 3 COM ports. 13719 13720@kindex show com1base 13721@kindex show com1irq 13722@kindex show com2base 13723@kindex show com2irq 13724@kindex show com3base 13725@kindex show com3irq 13726@kindex show com4base 13727@kindex show com4irq 13728The related commands @samp{show com1base}, @samp{show com1irq} etc.@: 13729display the current settings of the base address and the @code{IRQ} 13730lines used by the COM ports. 13731 13732@item info serial 13733@kindex info serial 13734@cindex DOS serial port status 13735This command prints the status of the 4 DOS serial ports. For each 13736port, it prints whether it's active or not, its I/O base address and 13737IRQ number, whether it uses a 16550-style FIFO, its baudrate, and the 13738counts of various errors encountered so far. 13739@end table 13740 13741 13742@node Cygwin Native 13743@subsection Features for Debugging MS Windows PE Executables 13744@cindex MS Windows debugging 13745@cindex native Cygwin debugging 13746@cindex Cygwin-specific commands 13747 13748@value{GDBN} supports native debugging of MS Windows programs, including 13749DLLs with and without symbolic debugging information. There are various 13750additional Cygwin-specific commands, described in this section. 13751Working with DLLs that have no debugging symbols is described in 13752@ref{Non-debug DLL Symbols}. 13753 13754@table @code 13755@kindex info w32 13756@item info w32 13757This is a prefix of MS Windows-specific commands which print 13758information about the target system and important OS structures. 13759 13760@item info w32 selector 13761This command displays information returned by 13762the Win32 API @code{GetThreadSelectorEntry} function. 13763It takes an optional argument that is evaluated to 13764a long value to give the information about this given selector. 13765Without argument, this command displays information 13766about the six segment registers. 13767 13768@kindex info dll 13769@item info dll 13770This is a Cygwin-specific alias of @code{info shared}. 13771 13772@kindex dll-symbols 13773@item dll-symbols 13774This command loads symbols from a dll similarly to 13775add-sym command but without the need to specify a base address. 13776 13777@kindex set cygwin-exceptions 13778@cindex debugging the Cygwin DLL 13779@cindex Cygwin DLL, debugging 13780@item set cygwin-exceptions @var{mode} 13781If @var{mode} is @code{on}, @value{GDBN} will break on exceptions that 13782happen inside the Cygwin DLL. If @var{mode} is @code{off}, 13783@value{GDBN} will delay recognition of exceptions, and may ignore some 13784exceptions which seem to be caused by internal Cygwin DLL 13785``bookkeeping''. This option is meant primarily for debugging the 13786Cygwin DLL itself; the default value is @code{off} to avoid annoying 13787@value{GDBN} users with false @code{SIGSEGV} signals. 13788 13789@kindex show cygwin-exceptions 13790@item show cygwin-exceptions 13791Displays whether @value{GDBN} will break on exceptions that happen 13792inside the Cygwin DLL itself. 13793 13794@kindex set new-console 13795@item set new-console @var{mode} 13796If @var{mode} is @code{on} the debuggee will 13797be started in a new console on next start. 13798If @var{mode} is @code{off}i, the debuggee will 13799be started in the same console as the debugger. 13800 13801@kindex show new-console 13802@item show new-console 13803Displays whether a new console is used 13804when the debuggee is started. 13805 13806@kindex set new-group 13807@item set new-group @var{mode} 13808This boolean value controls whether the debuggee should 13809start a new group or stay in the same group as the debugger. 13810This affects the way the Windows OS handles 13811@samp{Ctrl-C}. 13812 13813@kindex show new-group 13814@item show new-group 13815Displays current value of new-group boolean. 13816 13817@kindex set debugevents 13818@item set debugevents 13819This boolean value adds debug output concerning kernel events related 13820to the debuggee seen by the debugger. This includes events that 13821signal thread and process creation and exit, DLL loading and 13822unloading, console interrupts, and debugging messages produced by the 13823Windows @code{OutputDebugString} API call. 13824 13825@kindex set debugexec 13826@item set debugexec 13827This boolean value adds debug output concerning execute events 13828(such as resume thread) seen by the debugger. 13829 13830@kindex set debugexceptions 13831@item set debugexceptions 13832This boolean value adds debug output concerning exceptions in the 13833debuggee seen by the debugger. 13834 13835@kindex set debugmemory 13836@item set debugmemory 13837This boolean value adds debug output concerning debuggee memory reads 13838and writes by the debugger. 13839 13840@kindex set shell 13841@item set shell 13842This boolean values specifies whether the debuggee is called 13843via a shell or directly (default value is on). 13844 13845@kindex show shell 13846@item show shell 13847Displays if the debuggee will be started with a shell. 13848 13849@end table 13850 13851@menu 13852* Non-debug DLL Symbols:: Support for DLLs without debugging symbols 13853@end menu 13854 13855@node Non-debug DLL Symbols 13856@subsubsection Support for DLLs without Debugging Symbols 13857@cindex DLLs with no debugging symbols 13858@cindex Minimal symbols and DLLs 13859 13860Very often on windows, some of the DLLs that your program relies on do 13861not include symbolic debugging information (for example, 13862@file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging 13863symbols in a DLL, it relies on the minimal amount of symbolic 13864information contained in the DLL's export table. This section 13865describes working with such symbols, known internally to @value{GDBN} as 13866``minimal symbols''. 13867 13868Note that before the debugged program has started execution, no DLLs 13869will have been loaded. The easiest way around this problem is simply to 13870start the program --- either by setting a breakpoint or letting the 13871program run once to completion. It is also possible to force 13872@value{GDBN} to load a particular DLL before starting the executable --- 13873see the shared library information in @ref{Files}, or the 13874@code{dll-symbols} command in @ref{Cygwin Native}. Currently, 13875explicitly loading symbols from a DLL with no debugging information will 13876cause the symbol names to be duplicated in @value{GDBN}'s lookup table, 13877which may adversely affect symbol lookup performance. 13878 13879@subsubsection DLL Name Prefixes 13880 13881In keeping with the naming conventions used by the Microsoft debugging 13882tools, DLL export symbols are made available with a prefix based on the 13883DLL name, for instance @code{KERNEL32!CreateFileA}. The plain name is 13884also entered into the symbol table, so @code{CreateFileA} is often 13885sufficient. In some cases there will be name clashes within a program 13886(particularly if the executable itself includes full debugging symbols) 13887necessitating the use of the fully qualified name when referring to the 13888contents of the DLL. Use single-quotes around the name to avoid the 13889exclamation mark (``!'') being interpreted as a language operator. 13890 13891Note that the internal name of the DLL may be all upper-case, even 13892though the file name of the DLL is lower-case, or vice-versa. Since 13893symbols within @value{GDBN} are @emph{case-sensitive} this may cause 13894some confusion. If in doubt, try the @code{info functions} and 13895@code{info variables} commands or even @code{maint print msymbols} 13896(@pxref{Symbols}). Here's an example: 13897 13898@smallexample 13899(@value{GDBP}) info function CreateFileA 13900All functions matching regular expression "CreateFileA": 13901 13902Non-debugging symbols: 139030x77e885f4 CreateFileA 139040x77e885f4 KERNEL32!CreateFileA 13905@end smallexample 13906 13907@smallexample 13908(@value{GDBP}) info function ! 13909All functions matching regular expression "!": 13910 13911Non-debugging symbols: 139120x6100114c cygwin1!__assert 139130x61004034 cygwin1!_dll_crt0@@0 139140x61004240 cygwin1!dll_crt0(per_process *) 13915[etc...] 13916@end smallexample 13917 13918@subsubsection Working with Minimal Symbols 13919 13920Symbols extracted from a DLL's export table do not contain very much 13921type information. All that @value{GDBN} can do is guess whether a symbol 13922refers to a function or variable depending on the linker section that 13923contains the symbol. Also note that the actual contents of the memory 13924contained in a DLL are not available unless the program is running. This 13925means that you cannot examine the contents of a variable or disassemble 13926a function within a DLL without a running program. 13927 13928Variables are generally treated as pointers and dereferenced 13929automatically. For this reason, it is often necessary to prefix a 13930variable name with the address-of operator (``&'') and provide explicit 13931type information in the command. Here's an example of the type of 13932problem: 13933 13934@smallexample 13935(@value{GDBP}) print 'cygwin1!__argv' 13936$1 = 268572168 13937@end smallexample 13938 13939@smallexample 13940(@value{GDBP}) x 'cygwin1!__argv' 139410x10021610: "\230y\"" 13942@end smallexample 13943 13944And two possible solutions: 13945 13946@smallexample 13947(@value{GDBP}) print ((char **)'cygwin1!__argv')[0] 13948$2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" 13949@end smallexample 13950 13951@smallexample 13952(@value{GDBP}) x/2x &'cygwin1!__argv' 139530x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000 13954(@value{GDBP}) x/x 0x10021608 139550x10021608: 0x0022fd98 13956(@value{GDBP}) x/s 0x0022fd98 139570x22fd98: "/cygdrive/c/mydirectory/myprogram" 13958@end smallexample 13959 13960Setting a break point within a DLL is possible even before the program 13961starts execution. However, under these circumstances, @value{GDBN} can't 13962examine the initial instructions of the function in order to skip the 13963function's frame set-up code. You can work around this by using ``*&'' 13964to set the breakpoint at a raw memory address: 13965 13966@smallexample 13967(@value{GDBP}) break *&'python22!PyOS_Readline' 13968Breakpoint 1 at 0x1e04eff0 13969@end smallexample 13970 13971The author of these extensions is not entirely convinced that setting a 13972break point within a shared DLL like @file{kernel32.dll} is completely 13973safe. 13974 13975@node Hurd Native 13976@subsection Commands Specific to @sc{gnu} Hurd Systems 13977@cindex @sc{gnu} Hurd debugging 13978 13979This subsection describes @value{GDBN} commands specific to the 13980@sc{gnu} Hurd native debugging. 13981 13982@table @code 13983@item set signals 13984@itemx set sigs 13985@kindex set signals@r{, Hurd command} 13986@kindex set sigs@r{, Hurd command} 13987This command toggles the state of inferior signal interception by 13988@value{GDBN}. Mach exceptions, such as breakpoint traps, are not 13989affected by this command. @code{sigs} is a shorthand alias for 13990@code{signals}. 13991 13992@item show signals 13993@itemx show sigs 13994@kindex show signals@r{, Hurd command} 13995@kindex show sigs@r{, Hurd command} 13996Show the current state of intercepting inferior's signals. 13997 13998@item set signal-thread 13999@itemx set sigthread 14000@kindex set signal-thread 14001@kindex set sigthread 14002This command tells @value{GDBN} which thread is the @code{libc} signal 14003thread. That thread is run when a signal is delivered to a running 14004process. @code{set sigthread} is the shorthand alias of @code{set 14005signal-thread}. 14006 14007@item show signal-thread 14008@itemx show sigthread 14009@kindex show signal-thread 14010@kindex show sigthread 14011These two commands show which thread will run when the inferior is 14012delivered a signal. 14013 14014@item set stopped 14015@kindex set stopped@r{, Hurd command} 14016This commands tells @value{GDBN} that the inferior process is stopped, 14017as with the @code{SIGSTOP} signal. The stopped process can be 14018continued by delivering a signal to it. 14019 14020@item show stopped 14021@kindex show stopped@r{, Hurd command} 14022This command shows whether @value{GDBN} thinks the debuggee is 14023stopped. 14024 14025@item set exceptions 14026@kindex set exceptions@r{, Hurd command} 14027Use this command to turn off trapping of exceptions in the inferior. 14028When exception trapping is off, neither breakpoints nor 14029single-stepping will work. To restore the default, set exception 14030trapping on. 14031 14032@item show exceptions 14033@kindex show exceptions@r{, Hurd command} 14034Show the current state of trapping exceptions in the inferior. 14035 14036@item set task pause 14037@kindex set task@r{, Hurd commands} 14038@cindex task attributes (@sc{gnu} Hurd) 14039@cindex pause current task (@sc{gnu} Hurd) 14040This command toggles task suspension when @value{GDBN} has control. 14041Setting it to on takes effect immediately, and the task is suspended 14042whenever @value{GDBN} gets control. Setting it to off will take 14043effect the next time the inferior is continued. If this option is set 14044to off, you can use @code{set thread default pause on} or @code{set 14045thread pause on} (see below) to pause individual threads. 14046 14047@item show task pause 14048@kindex show task@r{, Hurd commands} 14049Show the current state of task suspension. 14050 14051@item set task detach-suspend-count 14052@cindex task suspend count 14053@cindex detach from task, @sc{gnu} Hurd 14054This command sets the suspend count the task will be left with when 14055@value{GDBN} detaches from it. 14056 14057@item show task detach-suspend-count 14058Show the suspend count the task will be left with when detaching. 14059 14060@item set task exception-port 14061@itemx set task excp 14062@cindex task exception port, @sc{gnu} Hurd 14063This command sets the task exception port to which @value{GDBN} will 14064forward exceptions. The argument should be the value of the @dfn{send 14065rights} of the task. @code{set task excp} is a shorthand alias. 14066 14067@item set noninvasive 14068@cindex noninvasive task options 14069This command switches @value{GDBN} to a mode that is the least 14070invasive as far as interfering with the inferior is concerned. This 14071is the same as using @code{set task pause}, @code{set exceptions}, and 14072@code{set signals} to values opposite to the defaults. 14073 14074@item info send-rights 14075@itemx info receive-rights 14076@itemx info port-rights 14077@itemx info port-sets 14078@itemx info dead-names 14079@itemx info ports 14080@itemx info psets 14081@cindex send rights, @sc{gnu} Hurd 14082@cindex receive rights, @sc{gnu} Hurd 14083@cindex port rights, @sc{gnu} Hurd 14084@cindex port sets, @sc{gnu} Hurd 14085@cindex dead names, @sc{gnu} Hurd 14086These commands display information about, respectively, send rights, 14087receive rights, port rights, port sets, and dead names of a task. 14088There are also shorthand aliases: @code{info ports} for @code{info 14089port-rights} and @code{info psets} for @code{info port-sets}. 14090 14091@item set thread pause 14092@kindex set thread@r{, Hurd command} 14093@cindex thread properties, @sc{gnu} Hurd 14094@cindex pause current thread (@sc{gnu} Hurd) 14095This command toggles current thread suspension when @value{GDBN} has 14096control. Setting it to on takes effect immediately, and the current 14097thread is suspended whenever @value{GDBN} gets control. Setting it to 14098off will take effect the next time the inferior is continued. 14099Normally, this command has no effect, since when @value{GDBN} has 14100control, the whole task is suspended. However, if you used @code{set 14101task pause off} (see above), this command comes in handy to suspend 14102only the current thread. 14103 14104@item show thread pause 14105@kindex show thread@r{, Hurd command} 14106This command shows the state of current thread suspension. 14107 14108@item set thread run 14109This command sets whether the current thread is allowed to run. 14110 14111@item show thread run 14112Show whether the current thread is allowed to run. 14113 14114@item set thread detach-suspend-count 14115@cindex thread suspend count, @sc{gnu} Hurd 14116@cindex detach from thread, @sc{gnu} Hurd 14117This command sets the suspend count @value{GDBN} will leave on a 14118thread when detaching. This number is relative to the suspend count 14119found by @value{GDBN} when it notices the thread; use @code{set thread 14120takeover-suspend-count} to force it to an absolute value. 14121 14122@item show thread detach-suspend-count 14123Show the suspend count @value{GDBN} will leave on the thread when 14124detaching. 14125 14126@item set thread exception-port 14127@itemx set thread excp 14128Set the thread exception port to which to forward exceptions. This 14129overrides the port set by @code{set task exception-port} (see above). 14130@code{set thread excp} is the shorthand alias. 14131 14132@item set thread takeover-suspend-count 14133Normally, @value{GDBN}'s thread suspend counts are relative to the 14134value @value{GDBN} finds when it notices each thread. This command 14135changes the suspend counts to be absolute instead. 14136 14137@item set thread default 14138@itemx show thread default 14139@cindex thread default settings, @sc{gnu} Hurd 14140Each of the above @code{set thread} commands has a @code{set thread 14141default} counterpart (e.g., @code{set thread default pause}, @code{set 14142thread default exception-port}, etc.). The @code{thread default} 14143variety of commands sets the default thread properties for all 14144threads; you can then change the properties of individual threads with 14145the non-default commands. 14146@end table 14147 14148 14149@node Neutrino 14150@subsection QNX Neutrino 14151@cindex QNX Neutrino 14152 14153@value{GDBN} provides the following commands specific to the QNX 14154Neutrino target: 14155 14156@table @code 14157@item set debug nto-debug 14158@kindex set debug nto-debug 14159When set to on, enables debugging messages specific to the QNX 14160Neutrino support. 14161 14162@item show debug nto-debug 14163@kindex show debug nto-debug 14164Show the current state of QNX Neutrino messages. 14165@end table 14166 14167 14168@node Embedded OS 14169@section Embedded Operating Systems 14170 14171This section describes configurations involving the debugging of 14172embedded operating systems that are available for several different 14173architectures. 14174 14175@menu 14176* VxWorks:: Using @value{GDBN} with VxWorks 14177@end menu 14178 14179@value{GDBN} includes the ability to debug programs running on 14180various real-time operating systems. 14181 14182@node VxWorks 14183@subsection Using @value{GDBN} with VxWorks 14184 14185@cindex VxWorks 14186 14187@table @code 14188 14189@kindex target vxworks 14190@item target vxworks @var{machinename} 14191A VxWorks system, attached via TCP/IP. The argument @var{machinename} 14192is the target system's machine name or IP address. 14193 14194@end table 14195 14196On VxWorks, @code{load} links @var{filename} dynamically on the 14197current target system as well as adding its symbols in @value{GDBN}. 14198 14199@value{GDBN} enables developers to spawn and debug tasks running on networked 14200VxWorks targets from a Unix host. Already-running tasks spawned from 14201the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on 14202both the Unix host and on the VxWorks target. The program 14203@code{@value{GDBP}} is installed and executed on the Unix host. (It may be 14204installed with the name @code{vxgdb}, to distinguish it from a 14205@value{GDBN} for debugging programs on the host itself.) 14206 14207@table @code 14208@item VxWorks-timeout @var{args} 14209@kindex vxworks-timeout 14210All VxWorks-based targets now support the option @code{vxworks-timeout}. 14211This option is set by the user, and @var{args} represents the number of 14212seconds @value{GDBN} waits for responses to rpc's. You might use this if 14213your VxWorks target is a slow software simulator or is on the far side 14214of a thin network line. 14215@end table 14216 14217The following information on connecting to VxWorks was current when 14218this manual was produced; newer releases of VxWorks may use revised 14219procedures. 14220 14221@findex INCLUDE_RDB 14222To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel 14223to include the remote debugging interface routines in the VxWorks 14224library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the 14225VxWorks configuration file @file{configAll.h} and rebuild your VxWorks 14226kernel. The resulting kernel contains @file{rdb.a}, and spawns the 14227source debugging task @code{tRdbTask} when VxWorks is booted. For more 14228information on configuring and remaking VxWorks, see the manufacturer's 14229manual. 14230@c VxWorks, see the @cite{VxWorks Programmer's Guide}. 14231 14232Once you have included @file{rdb.a} in your VxWorks system image and set 14233your Unix execution search path to find @value{GDBN}, you are ready to 14234run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or 14235@code{vxgdb}, depending on your installation). 14236 14237@value{GDBN} comes up showing the prompt: 14238 14239@smallexample 14240(vxgdb) 14241@end smallexample 14242 14243@menu 14244* VxWorks Connection:: Connecting to VxWorks 14245* VxWorks Download:: VxWorks download 14246* VxWorks Attach:: Running tasks 14247@end menu 14248 14249@node VxWorks Connection 14250@subsubsection Connecting to VxWorks 14251 14252The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the 14253network. To connect to a target whose host name is ``@code{tt}'', type: 14254 14255@smallexample 14256(vxgdb) target vxworks tt 14257@end smallexample 14258 14259@need 750 14260@value{GDBN} displays messages like these: 14261 14262@smallexample 14263Attaching remote machine across net... 14264Connected to tt. 14265@end smallexample 14266 14267@need 1000 14268@value{GDBN} then attempts to read the symbol tables of any object modules 14269loaded into the VxWorks target since it was last booted. @value{GDBN} locates 14270these files by searching the directories listed in the command search 14271path (@pxref{Environment, ,Your Program's Environment}); if it fails 14272to find an object file, it displays a message such as: 14273 14274@smallexample 14275prog.o: No such file or directory. 14276@end smallexample 14277 14278When this happens, add the appropriate directory to the search path with 14279the @value{GDBN} command @code{path}, and execute the @code{target} 14280command again. 14281 14282@node VxWorks Download 14283@subsubsection VxWorks Download 14284 14285@cindex download to VxWorks 14286If you have connected to the VxWorks target and you want to debug an 14287object that has not yet been loaded, you can use the @value{GDBN} 14288@code{load} command to download a file from Unix to VxWorks 14289incrementally. The object file given as an argument to the @code{load} 14290command is actually opened twice: first by the VxWorks target in order 14291to download the code, then by @value{GDBN} in order to read the symbol 14292table. This can lead to problems if the current working directories on 14293the two systems differ. If both systems have NFS mounted the same 14294filesystems, you can avoid these problems by using absolute paths. 14295Otherwise, it is simplest to set the working directory on both systems 14296to the directory in which the object file resides, and then to reference 14297the file by its name, without any path. For instance, a program 14298@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks 14299and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this 14300program, type this on VxWorks: 14301 14302@smallexample 14303-> cd "@var{vxpath}/vw/demo/rdb" 14304@end smallexample 14305 14306@noindent 14307Then, in @value{GDBN}, type: 14308 14309@smallexample 14310(vxgdb) cd @var{hostpath}/vw/demo/rdb 14311(vxgdb) load prog.o 14312@end smallexample 14313 14314@value{GDBN} displays a response similar to this: 14315 14316@smallexample 14317Reading symbol data from wherever/vw/demo/rdb/prog.o... done. 14318@end smallexample 14319 14320You can also use the @code{load} command to reload an object module 14321after editing and recompiling the corresponding source file. Note that 14322this makes @value{GDBN} delete all currently-defined breakpoints, 14323auto-displays, and convenience variables, and to clear the value 14324history. (This is necessary in order to preserve the integrity of 14325debugger's data structures that reference the target system's symbol 14326table.) 14327 14328@node VxWorks Attach 14329@subsubsection Running Tasks 14330 14331@cindex running VxWorks tasks 14332You can also attach to an existing task using the @code{attach} command as 14333follows: 14334 14335@smallexample 14336(vxgdb) attach @var{task} 14337@end smallexample 14338 14339@noindent 14340where @var{task} is the VxWorks hexadecimal task ID. The task can be running 14341or suspended when you attach to it. Running tasks are suspended at 14342the time of attachment. 14343 14344@node Embedded Processors 14345@section Embedded Processors 14346 14347This section goes into details specific to particular embedded 14348configurations. 14349 14350@cindex send command to simulator 14351Whenever a specific embedded processor has a simulator, @value{GDBN} 14352allows to send an arbitrary command to the simulator. 14353 14354@table @code 14355@item sim @var{command} 14356@kindex sim@r{, a command} 14357Send an arbitrary @var{command} string to the simulator. Consult the 14358documentation for the specific simulator in use for information about 14359acceptable commands. 14360@end table 14361 14362 14363@menu 14364* ARM:: ARM RDI 14365* M32R/D:: Renesas M32R/D 14366* M68K:: Motorola M68K 14367* MIPS Embedded:: MIPS Embedded 14368* OpenRISC 1000:: OpenRisc 1000 14369* PA:: HP PA Embedded 14370* PowerPC:: PowerPC 14371* Sparclet:: Tsqware Sparclet 14372* Sparclite:: Fujitsu Sparclite 14373* Z8000:: Zilog Z8000 14374* AVR:: Atmel AVR 14375* CRIS:: CRIS 14376* Super-H:: Renesas Super-H 14377@end menu 14378 14379@node ARM 14380@subsection ARM 14381@cindex ARM RDI 14382 14383@table @code 14384@kindex target rdi 14385@item target rdi @var{dev} 14386ARM Angel monitor, via RDI library interface to ADP protocol. You may 14387use this target to communicate with both boards running the Angel 14388monitor, or with the EmbeddedICE JTAG debug device. 14389 14390@kindex target rdp 14391@item target rdp @var{dev} 14392ARM Demon monitor. 14393 14394@end table 14395 14396@value{GDBN} provides the following ARM-specific commands: 14397 14398@table @code 14399@item set arm disassembler 14400@kindex set arm 14401This commands selects from a list of disassembly styles. The 14402@code{"std"} style is the standard style. 14403 14404@item show arm disassembler 14405@kindex show arm 14406Show the current disassembly style. 14407 14408@item set arm apcs32 14409@cindex ARM 32-bit mode 14410This command toggles ARM operation mode between 32-bit and 26-bit. 14411 14412@item show arm apcs32 14413Display the current usage of the ARM 32-bit mode. 14414 14415@item set arm fpu @var{fputype} 14416This command sets the ARM floating-point unit (FPU) type. The 14417argument @var{fputype} can be one of these: 14418 14419@table @code 14420@item auto 14421Determine the FPU type by querying the OS ABI. 14422@item softfpa 14423Software FPU, with mixed-endian doubles on little-endian ARM 14424processors. 14425@item fpa 14426GCC-compiled FPA co-processor. 14427@item softvfp 14428Software FPU with pure-endian doubles. 14429@item vfp 14430VFP co-processor. 14431@end table 14432 14433@item show arm fpu 14434Show the current type of the FPU. 14435 14436@item set arm abi 14437This command forces @value{GDBN} to use the specified ABI. 14438 14439@item show arm abi 14440Show the currently used ABI. 14441 14442@item set debug arm 14443Toggle whether to display ARM-specific debugging messages from the ARM 14444target support subsystem. 14445 14446@item show debug arm 14447Show whether ARM-specific debugging messages are enabled. 14448@end table 14449 14450The following commands are available when an ARM target is debugged 14451using the RDI interface: 14452 14453@table @code 14454@item rdilogfile @r{[}@var{file}@r{]} 14455@kindex rdilogfile 14456@cindex ADP (Angel Debugger Protocol) logging 14457Set the filename for the ADP (Angel Debugger Protocol) packet log. 14458With an argument, sets the log file to the specified @var{file}. With 14459no argument, show the current log file name. The default log file is 14460@file{rdi.log}. 14461 14462@item rdilogenable @r{[}@var{arg}@r{]} 14463@kindex rdilogenable 14464Control logging of ADP packets. With an argument of 1 or @code{"yes"} 14465enables logging, with an argument 0 or @code{"no"} disables it. With 14466no arguments displays the current setting. When logging is enabled, 14467ADP packets exchanged between @value{GDBN} and the RDI target device 14468are logged to a file. 14469 14470@item set rdiromatzero 14471@kindex set rdiromatzero 14472@cindex ROM at zero address, RDI 14473Tell @value{GDBN} whether the target has ROM at address 0. If on, 14474vector catching is disabled, so that zero address can be used. If off 14475(the default), vector catching is enabled. For this command to take 14476effect, it needs to be invoked prior to the @code{target rdi} command. 14477 14478@item show rdiromatzero 14479@kindex show rdiromatzero 14480Show the current setting of ROM at zero address. 14481 14482@item set rdiheartbeat 14483@kindex set rdiheartbeat 14484@cindex RDI heartbeat 14485Enable or disable RDI heartbeat packets. It is not recommended to 14486turn on this option, since it confuses ARM and EPI JTAG interface, as 14487well as the Angel monitor. 14488 14489@item show rdiheartbeat 14490@kindex show rdiheartbeat 14491Show the setting of RDI heartbeat packets. 14492@end table 14493 14494 14495@node M32R/D 14496@subsection Renesas M32R/D and M32R/SDI 14497 14498@table @code 14499@kindex target m32r 14500@item target m32r @var{dev} 14501Renesas M32R/D ROM monitor. 14502 14503@kindex target m32rsdi 14504@item target m32rsdi @var{dev} 14505Renesas M32R SDI server, connected via parallel port to the board. 14506@end table 14507 14508The following @value{GDBN} commands are specific to the M32R monitor: 14509 14510@table @code 14511@item set download-path @var{path} 14512@kindex set download-path 14513@cindex find downloadable @sc{srec} files (M32R) 14514Set the default path for finding downloadable @sc{srec} files. 14515 14516@item show download-path 14517@kindex show download-path 14518Show the default path for downloadable @sc{srec} files. 14519 14520@item set board-address @var{addr} 14521@kindex set board-address 14522@cindex M32-EVA target board address 14523Set the IP address for the M32R-EVA target board. 14524 14525@item show board-address 14526@kindex show board-address 14527Show the current IP address of the target board. 14528 14529@item set server-address @var{addr} 14530@kindex set server-address 14531@cindex download server address (M32R) 14532Set the IP address for the download server, which is the @value{GDBN}'s 14533host machine. 14534 14535@item show server-address 14536@kindex show server-address 14537Display the IP address of the download server. 14538 14539@item upload @r{[}@var{file}@r{]} 14540@kindex upload@r{, M32R} 14541Upload the specified @sc{srec} @var{file} via the monitor's Ethernet 14542upload capability. If no @var{file} argument is given, the current 14543executable file is uploaded. 14544 14545@item tload @r{[}@var{file}@r{]} 14546@kindex tload@r{, M32R} 14547Test the @code{upload} command. 14548@end table 14549 14550The following commands are available for M32R/SDI: 14551 14552@table @code 14553@item sdireset 14554@kindex sdireset 14555@cindex reset SDI connection, M32R 14556This command resets the SDI connection. 14557 14558@item sdistatus 14559@kindex sdistatus 14560This command shows the SDI connection status. 14561 14562@item debug_chaos 14563@kindex debug_chaos 14564@cindex M32R/Chaos debugging 14565Instructs the remote that M32R/Chaos debugging is to be used. 14566 14567@item use_debug_dma 14568@kindex use_debug_dma 14569Instructs the remote to use the DEBUG_DMA method of accessing memory. 14570 14571@item use_mon_code 14572@kindex use_mon_code 14573Instructs the remote to use the MON_CODE method of accessing memory. 14574 14575@item use_ib_break 14576@kindex use_ib_break 14577Instructs the remote to set breakpoints by IB break. 14578 14579@item use_dbt_break 14580@kindex use_dbt_break 14581Instructs the remote to set breakpoints by DBT. 14582@end table 14583 14584@node M68K 14585@subsection M68k 14586 14587The Motorola m68k configuration includes ColdFire support, and a 14588target command for the following ROM monitor. 14589 14590@table @code 14591 14592@kindex target dbug 14593@item target dbug @var{dev} 14594dBUG ROM monitor for Motorola ColdFire. 14595 14596@end table 14597 14598@node MIPS Embedded 14599@subsection MIPS Embedded 14600 14601@cindex MIPS boards 14602@value{GDBN} can use the MIPS remote debugging protocol to talk to a 14603MIPS board attached to a serial line. This is available when 14604you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}. 14605 14606@need 1000 14607Use these @value{GDBN} commands to specify the connection to your target board: 14608 14609@table @code 14610@item target mips @var{port} 14611@kindex target mips @var{port} 14612To run a program on the board, start up @code{@value{GDBP}} with the 14613name of your program as the argument. To connect to the board, use the 14614command @samp{target mips @var{port}}, where @var{port} is the name of 14615the serial port connected to the board. If the program has not already 14616been downloaded to the board, you may use the @code{load} command to 14617download it. You can then use all the usual @value{GDBN} commands. 14618 14619For example, this sequence connects to the target board through a serial 14620port, and loads and runs a program called @var{prog} through the 14621debugger: 14622 14623@smallexample 14624host$ @value{GDBP} @var{prog} 14625@value{GDBN} is free software and @dots{} 14626(@value{GDBP}) target mips /dev/ttyb 14627(@value{GDBP}) load @var{prog} 14628(@value{GDBP}) run 14629@end smallexample 14630 14631@item target mips @var{hostname}:@var{portnumber} 14632On some @value{GDBN} host configurations, you can specify a TCP 14633connection (for instance, to a serial line managed by a terminal 14634concentrator) instead of a serial port, using the syntax 14635@samp{@var{hostname}:@var{portnumber}}. 14636 14637@item target pmon @var{port} 14638@kindex target pmon @var{port} 14639PMON ROM monitor. 14640 14641@item target ddb @var{port} 14642@kindex target ddb @var{port} 14643NEC's DDB variant of PMON for Vr4300. 14644 14645@item target lsi @var{port} 14646@kindex target lsi @var{port} 14647LSI variant of PMON. 14648 14649@kindex target r3900 14650@item target r3900 @var{dev} 14651Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. 14652 14653@kindex target array 14654@item target array @var{dev} 14655Array Tech LSI33K RAID controller board. 14656 14657@end table 14658 14659 14660@noindent 14661@value{GDBN} also supports these special commands for MIPS targets: 14662 14663@table @code 14664@item set mipsfpu double 14665@itemx set mipsfpu single 14666@itemx set mipsfpu none 14667@itemx set mipsfpu auto 14668@itemx show mipsfpu 14669@kindex set mipsfpu 14670@kindex show mipsfpu 14671@cindex MIPS remote floating point 14672@cindex floating point, MIPS remote 14673If your target board does not support the MIPS floating point 14674coprocessor, you should use the command @samp{set mipsfpu none} (if you 14675need this, you may wish to put the command in your @value{GDBN} init 14676file). This tells @value{GDBN} how to find the return value of 14677functions which return floating point values. It also allows 14678@value{GDBN} to avoid saving the floating point registers when calling 14679functions on the board. If you are using a floating point coprocessor 14680with only single precision floating point support, as on the @sc{r4650} 14681processor, use the command @samp{set mipsfpu single}. The default 14682double precision floating point coprocessor may be selected using 14683@samp{set mipsfpu double}. 14684 14685In previous versions the only choices were double precision or no 14686floating point, so @samp{set mipsfpu on} will select double precision 14687and @samp{set mipsfpu off} will select no floating point. 14688 14689As usual, you can inquire about the @code{mipsfpu} variable with 14690@samp{show mipsfpu}. 14691 14692@item set timeout @var{seconds} 14693@itemx set retransmit-timeout @var{seconds} 14694@itemx show timeout 14695@itemx show retransmit-timeout 14696@cindex @code{timeout}, MIPS protocol 14697@cindex @code{retransmit-timeout}, MIPS protocol 14698@kindex set timeout 14699@kindex show timeout 14700@kindex set retransmit-timeout 14701@kindex show retransmit-timeout 14702You can control the timeout used while waiting for a packet, in the MIPS 14703remote protocol, with the @code{set timeout @var{seconds}} command. The 14704default is 5 seconds. Similarly, you can control the timeout used while 14705waiting for an acknowledgement of a packet with the @code{set 14706retransmit-timeout @var{seconds}} command. The default is 3 seconds. 14707You can inspect both values with @code{show timeout} and @code{show 14708retransmit-timeout}. (These commands are @emph{only} available when 14709@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.) 14710 14711The timeout set by @code{set timeout} does not apply when @value{GDBN} 14712is waiting for your program to stop. In that case, @value{GDBN} waits 14713forever because it has no way of knowing how long the program is going 14714to run before stopping. 14715 14716@item set syn-garbage-limit @var{num} 14717@kindex set syn-garbage-limit@r{, MIPS remote} 14718@cindex synchronize with remote MIPS target 14719Limit the maximum number of characters @value{GDBN} should ignore when 14720it tries to synchronize with the remote target. The default is 10 14721characters. Setting the limit to -1 means there's no limit. 14722 14723@item show syn-garbage-limit 14724@kindex show syn-garbage-limit@r{, MIPS remote} 14725Show the current limit on the number of characters to ignore when 14726trying to synchronize with the remote system. 14727 14728@item set monitor-prompt @var{prompt} 14729@kindex set monitor-prompt@r{, MIPS remote} 14730@cindex remote monitor prompt 14731Tell @value{GDBN} to expect the specified @var{prompt} string from the 14732remote monitor. The default depends on the target: 14733@table @asis 14734@item pmon target 14735@samp{PMON} 14736@item ddb target 14737@samp{NEC010} 14738@item lsi target 14739@samp{PMON>} 14740@end table 14741 14742@item show monitor-prompt 14743@kindex show monitor-prompt@r{, MIPS remote} 14744Show the current strings @value{GDBN} expects as the prompt from the 14745remote monitor. 14746 14747@item set monitor-warnings 14748@kindex set monitor-warnings@r{, MIPS remote} 14749Enable or disable monitor warnings about hardware breakpoints. This 14750has effect only for the @code{lsi} target. When on, @value{GDBN} will 14751display warning messages whose codes are returned by the @code{lsi} 14752PMON monitor for breakpoint commands. 14753 14754@item show monitor-warnings 14755@kindex show monitor-warnings@r{, MIPS remote} 14756Show the current setting of printing monitor warnings. 14757 14758@item pmon @var{command} 14759@kindex pmon@r{, MIPS remote} 14760@cindex send PMON command 14761This command allows sending an arbitrary @var{command} string to the 14762monitor. The monitor must be in debug mode for this to work. 14763@end table 14764 14765@node OpenRISC 1000 14766@subsection OpenRISC 1000 14767@cindex OpenRISC 1000 14768 14769@cindex or1k boards 14770See OR1k Architecture document (@uref{www.opencores.org}) for more information 14771about platform and commands. 14772 14773@table @code 14774 14775@kindex target jtag 14776@item target jtag jtag://@var{host}:@var{port} 14777 14778Connects to remote JTAG server. 14779JTAG remote server can be either an or1ksim or JTAG server, 14780connected via parallel port to the board. 14781 14782Example: @code{target jtag jtag://localhost:9999} 14783 14784@kindex or1ksim 14785@item or1ksim @var{command} 14786If connected to @code{or1ksim} OpenRISC 1000 Architectural 14787Simulator, proprietary commands can be executed. 14788 14789@kindex info or1k spr 14790@item info or1k spr 14791Displays spr groups. 14792 14793@item info or1k spr @var{group} 14794@itemx info or1k spr @var{groupno} 14795Displays register names in selected group. 14796 14797@item info or1k spr @var{group} @var{register} 14798@itemx info or1k spr @var{register} 14799@itemx info or1k spr @var{groupno} @var{registerno} 14800@itemx info or1k spr @var{registerno} 14801Shows information about specified spr register. 14802 14803@kindex spr 14804@item spr @var{group} @var{register} @var{value} 14805@itemx spr @var{register @var{value}} 14806@itemx spr @var{groupno} @var{registerno @var{value}} 14807@itemx spr @var{registerno @var{value}} 14808Writes @var{value} to specified spr register. 14809@end table 14810 14811Some implementations of OpenRISC 1000 Architecture also have hardware trace. 14812It is very similar to @value{GDBN} trace, except it does not interfere with normal 14813program execution and is thus much faster. Hardware breakpoints/watchpoint 14814triggers can be set using: 14815@table @code 14816@item $LEA/$LDATA 14817Load effective address/data 14818@item $SEA/$SDATA 14819Store effective address/data 14820@item $AEA/$ADATA 14821Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA) 14822@item $FETCH 14823Fetch data 14824@end table 14825 14826When triggered, it can capture low level data, like: @code{PC}, @code{LSEA}, 14827@code{LDATA}, @code{SDATA}, @code{READSPR}, @code{WRITESPR}, @code{INSTR}. 14828 14829@code{htrace} commands: 14830@cindex OpenRISC 1000 htrace 14831@table @code 14832@kindex hwatch 14833@item hwatch @var{conditional} 14834Set hardware watchpoint on combination of Load/Store Effective Address(es) 14835or Data. For example: 14836 14837@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)} 14838 14839@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)} 14840 14841@kindex htrace 14842@item htrace info 14843Display information about current HW trace configuration. 14844 14845@item htrace trigger @var{conditional} 14846Set starting criteria for HW trace. 14847 14848@item htrace qualifier @var{conditional} 14849Set acquisition qualifier for HW trace. 14850 14851@item htrace stop @var{conditional} 14852Set HW trace stopping criteria. 14853 14854@item htrace record [@var{data}]* 14855Selects the data to be recorded, when qualifier is met and HW trace was 14856triggered. 14857 14858@item htrace enable 14859@itemx htrace disable 14860Enables/disables the HW trace. 14861 14862@item htrace rewind [@var{filename}] 14863Clears currently recorded trace data. 14864 14865If filename is specified, new trace file is made and any newly collected data 14866will be written there. 14867 14868@item htrace print [@var{start} [@var{len}]] 14869Prints trace buffer, using current record configuration. 14870 14871@item htrace mode continuous 14872Set continuous trace mode. 14873 14874@item htrace mode suspend 14875Set suspend trace mode. 14876 14877@end table 14878 14879@node PowerPC 14880@subsection PowerPC 14881 14882@table @code 14883@kindex target dink32 14884@item target dink32 @var{dev} 14885DINK32 ROM monitor. 14886 14887@kindex target ppcbug 14888@item target ppcbug @var{dev} 14889@kindex target ppcbug1 14890@item target ppcbug1 @var{dev} 14891PPCBUG ROM monitor for PowerPC. 14892 14893@kindex target sds 14894@item target sds @var{dev} 14895SDS monitor, running on a PowerPC board (such as Motorola's ADS). 14896@end table 14897 14898@cindex SDS protocol 14899The following commands specific to the SDS protocol are supported 14900by@value{GDBN}: 14901 14902@table @code 14903@item set sdstimeout @var{nsec} 14904@kindex set sdstimeout 14905Set the timeout for SDS protocol reads to be @var{nsec} seconds. The 14906default is 2 seconds. 14907 14908@item show sdstimeout 14909@kindex show sdstimeout 14910Show the current value of the SDS timeout. 14911 14912@item sds @var{command} 14913@kindex sds@r{, a command} 14914Send the specified @var{command} string to the SDS monitor. 14915@end table 14916 14917 14918@node PA 14919@subsection HP PA Embedded 14920 14921@table @code 14922 14923@kindex target op50n 14924@item target op50n @var{dev} 14925OP50N monitor, running on an OKI HPPA board. 14926 14927@kindex target w89k 14928@item target w89k @var{dev} 14929W89K monitor, running on a Winbond HPPA board. 14930 14931@end table 14932 14933@node Sparclet 14934@subsection Tsqware Sparclet 14935 14936@cindex Sparclet 14937 14938@value{GDBN} enables developers to debug tasks running on 14939Sparclet targets from a Unix host. 14940@value{GDBN} uses code that runs on 14941both the Unix host and on the Sparclet target. The program 14942@code{@value{GDBP}} is installed and executed on the Unix host. 14943 14944@table @code 14945@item remotetimeout @var{args} 14946@kindex remotetimeout 14947@value{GDBN} supports the option @code{remotetimeout}. 14948This option is set by the user, and @var{args} represents the number of 14949seconds @value{GDBN} waits for responses. 14950@end table 14951 14952@cindex compiling, on Sparclet 14953When compiling for debugging, include the options @samp{-g} to get debug 14954information and @samp{-Ttext} to relocate the program to where you wish to 14955load it on the target. You may also want to add the options @samp{-n} or 14956@samp{-N} in order to reduce the size of the sections. Example: 14957 14958@smallexample 14959sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N 14960@end smallexample 14961 14962You can use @code{objdump} to verify that the addresses are what you intended: 14963 14964@smallexample 14965sparclet-aout-objdump --headers --syms prog 14966@end smallexample 14967 14968@cindex running, on Sparclet 14969Once you have set 14970your Unix execution search path to find @value{GDBN}, you are ready to 14971run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} 14972(or @code{sparclet-aout-gdb}, depending on your installation). 14973 14974@value{GDBN} comes up showing the prompt: 14975 14976@smallexample 14977(gdbslet) 14978@end smallexample 14979 14980@menu 14981* Sparclet File:: Setting the file to debug 14982* Sparclet Connection:: Connecting to Sparclet 14983* Sparclet Download:: Sparclet download 14984* Sparclet Execution:: Running and debugging 14985@end menu 14986 14987@node Sparclet File 14988@subsubsection Setting File to Debug 14989 14990The @value{GDBN} command @code{file} lets you choose with program to debug. 14991 14992@smallexample 14993(gdbslet) file prog 14994@end smallexample 14995 14996@need 1000 14997@value{GDBN} then attempts to read the symbol table of @file{prog}. 14998@value{GDBN} locates 14999the file by searching the directories listed in the command search 15000path. 15001If the file was compiled with debug information (option @samp{-g}), source 15002files will be searched as well. 15003@value{GDBN} locates 15004the source files by searching the directories listed in the directory search 15005path (@pxref{Environment, ,Your Program's Environment}). 15006If it fails 15007to find a file, it displays a message such as: 15008 15009@smallexample 15010prog: No such file or directory. 15011@end smallexample 15012 15013When this happens, add the appropriate directories to the search paths with 15014the @value{GDBN} commands @code{path} and @code{dir}, and execute the 15015@code{target} command again. 15016 15017@node Sparclet Connection 15018@subsubsection Connecting to Sparclet 15019 15020The @value{GDBN} command @code{target} lets you connect to a Sparclet target. 15021To connect to a target on serial port ``@code{ttya}'', type: 15022 15023@smallexample 15024(gdbslet) target sparclet /dev/ttya 15025Remote target sparclet connected to /dev/ttya 15026main () at ../prog.c:3 15027@end smallexample 15028 15029@need 750 15030@value{GDBN} displays messages like these: 15031 15032@smallexample 15033Connected to ttya. 15034@end smallexample 15035 15036@node Sparclet Download 15037@subsubsection Sparclet Download 15038 15039@cindex download to Sparclet 15040Once connected to the Sparclet target, 15041you can use the @value{GDBN} 15042@code{load} command to download the file from the host to the target. 15043The file name and load offset should be given as arguments to the @code{load} 15044command. 15045Since the file format is aout, the program must be loaded to the starting 15046address. You can use @code{objdump} to find out what this value is. The load 15047offset is an offset which is added to the VMA (virtual memory address) 15048of each of the file's sections. 15049For instance, if the program 15050@file{prog} was linked to text address 0x1201000, with data at 0x12010160 15051and bss at 0x12010170, in @value{GDBN}, type: 15052 15053@smallexample 15054(gdbslet) load prog 0x12010000 15055Loading section .text, size 0xdb0 vma 0x12010000 15056@end smallexample 15057 15058If the code is loaded at a different address then what the program was linked 15059to, you may need to use the @code{section} and @code{add-symbol-file} commands 15060to tell @value{GDBN} where to map the symbol table. 15061 15062@node Sparclet Execution 15063@subsubsection Running and Debugging 15064 15065@cindex running and debugging Sparclet programs 15066You can now begin debugging the task using @value{GDBN}'s execution control 15067commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN} 15068manual for the list of commands. 15069 15070@smallexample 15071(gdbslet) b main 15072Breakpoint 1 at 0x12010000: file prog.c, line 3. 15073(gdbslet) run 15074Starting program: prog 15075Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 150763 char *symarg = 0; 15077(gdbslet) step 150784 char *execarg = "hello!"; 15079(gdbslet) 15080@end smallexample 15081 15082@node Sparclite 15083@subsection Fujitsu Sparclite 15084 15085@table @code 15086 15087@kindex target sparclite 15088@item target sparclite @var{dev} 15089Fujitsu sparclite boards, used only for the purpose of loading. 15090You must use an additional command to debug the program. 15091For example: target remote @var{dev} using @value{GDBN} standard 15092remote protocol. 15093 15094@end table 15095 15096@node Z8000 15097@subsection Zilog Z8000 15098 15099@cindex Z8000 15100@cindex simulator, Z8000 15101@cindex Zilog Z8000 simulator 15102 15103When configured for debugging Zilog Z8000 targets, @value{GDBN} includes 15104a Z8000 simulator. 15105 15106For the Z8000 family, @samp{target sim} simulates either the Z8002 (the 15107unsegmented variant of the Z8000 architecture) or the Z8001 (the 15108segmented variant). The simulator recognizes which architecture is 15109appropriate by inspecting the object code. 15110 15111@table @code 15112@item target sim @var{args} 15113@kindex sim 15114@kindex target sim@r{, with Z8000} 15115Debug programs on a simulated CPU. If the simulator supports setup 15116options, specify them via @var{args}. 15117@end table 15118 15119@noindent 15120After specifying this target, you can debug programs for the simulated 15121CPU in the same style as programs for your host computer; use the 15122@code{file} command to load a new program image, the @code{run} command 15123to run your program, and so on. 15124 15125As well as making available all the usual machine registers 15126(@pxref{Registers, ,Registers}), the Z8000 simulator provides three 15127additional items of information as specially named registers: 15128 15129@table @code 15130 15131@item cycles 15132Counts clock-ticks in the simulator. 15133 15134@item insts 15135Counts instructions run in the simulator. 15136 15137@item time 15138Execution time in 60ths of a second. 15139 15140@end table 15141 15142You can refer to these values in @value{GDBN} expressions with the usual 15143conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a 15144conditional breakpoint that suspends only after at least 5000 15145simulated clock ticks. 15146 15147@node AVR 15148@subsection Atmel AVR 15149@cindex AVR 15150 15151When configured for debugging the Atmel AVR, @value{GDBN} supports the 15152following AVR-specific commands: 15153 15154@table @code 15155@item info io_registers 15156@kindex info io_registers@r{, AVR} 15157@cindex I/O registers (Atmel AVR) 15158This command displays information about the AVR I/O registers. For 15159each register, @value{GDBN} prints its number and value. 15160@end table 15161 15162@node CRIS 15163@subsection CRIS 15164@cindex CRIS 15165 15166When configured for debugging CRIS, @value{GDBN} provides the 15167following CRIS-specific commands: 15168 15169@table @code 15170@item set cris-version @var{ver} 15171@cindex CRIS version 15172Set the current CRIS version to @var{ver}, either @samp{10} or @samp{32}. 15173The CRIS version affects register names and sizes. This command is useful in 15174case autodetection of the CRIS version fails. 15175 15176@item show cris-version 15177Show the current CRIS version. 15178 15179@item set cris-dwarf2-cfi 15180@cindex DWARF-2 CFI and CRIS 15181Set the usage of DWARF-2 CFI for CRIS debugging. The default is @samp{on}. 15182Change to @samp{off} when using @code{gcc-cris} whose version is below 15183@code{R59}. 15184 15185@item show cris-dwarf2-cfi 15186Show the current state of using DWARF-2 CFI. 15187 15188@item set cris-mode @var{mode} 15189@cindex CRIS mode 15190Set the current CRIS mode to @var{mode}. It should only be changed when 15191debugging in guru mode, in which case it should be set to 15192@samp{guru} (the default is @samp{normal}). 15193 15194@item show cris-mode 15195Show the current CRIS mode. 15196@end table 15197 15198@node Super-H 15199@subsection Renesas Super-H 15200@cindex Super-H 15201 15202For the Renesas Super-H processor, @value{GDBN} provides these 15203commands: 15204 15205@table @code 15206@item regs 15207@kindex regs@r{, Super-H} 15208Show the values of all Super-H registers. 15209@end table 15210 15211 15212@node Architectures 15213@section Architectures 15214 15215This section describes characteristics of architectures that affect 15216all uses of @value{GDBN} with the architecture, both native and cross. 15217 15218@menu 15219* i386:: 15220* A29K:: 15221* Alpha:: 15222* MIPS:: 15223* HPPA:: HP PA architecture 15224* SPU:: Cell Broadband Engine SPU architecture 15225@end menu 15226 15227@node i386 15228@subsection x86 Architecture-specific Issues 15229 15230@table @code 15231@item set struct-convention @var{mode} 15232@kindex set struct-convention 15233@cindex struct return convention 15234@cindex struct/union returned in registers 15235Set the convention used by the inferior to return @code{struct}s and 15236@code{union}s from functions to @var{mode}. Possible values of 15237@var{mode} are @code{"pcc"}, @code{"reg"}, and @code{"default"} (the 15238default). @code{"default"} or @code{"pcc"} means that @code{struct}s 15239are returned on the stack, while @code{"reg"} means that a 15240@code{struct} or a @code{union} whose size is 1, 2, 4, or 8 bytes will 15241be returned in a register. 15242 15243@item show struct-convention 15244@kindex show struct-convention 15245Show the current setting of the convention to return @code{struct}s 15246from functions. 15247@end table 15248 15249@node A29K 15250@subsection A29K 15251 15252@table @code 15253 15254@kindex set rstack_high_address 15255@cindex AMD 29K register stack 15256@cindex register stack, AMD29K 15257@item set rstack_high_address @var{address} 15258On AMD 29000 family processors, registers are saved in a separate 15259@dfn{register stack}. There is no way for @value{GDBN} to determine the 15260extent of this stack. Normally, @value{GDBN} just assumes that the 15261stack is ``large enough''. This may result in @value{GDBN} referencing 15262memory locations that do not exist. If necessary, you can get around 15263this problem by specifying the ending address of the register stack with 15264the @code{set rstack_high_address} command. The argument should be an 15265address, which you probably want to precede with @samp{0x} to specify in 15266hexadecimal. 15267 15268@kindex show rstack_high_address 15269@item show rstack_high_address 15270Display the current limit of the register stack, on AMD 29000 family 15271processors. 15272 15273@end table 15274 15275@node Alpha 15276@subsection Alpha 15277 15278See the following section. 15279 15280@node MIPS 15281@subsection MIPS 15282 15283@cindex stack on Alpha 15284@cindex stack on MIPS 15285@cindex Alpha stack 15286@cindex MIPS stack 15287Alpha- and MIPS-based computers use an unusual stack frame, which 15288sometimes requires @value{GDBN} to search backward in the object code to 15289find the beginning of a function. 15290 15291@cindex response time, MIPS debugging 15292To improve response time (especially for embedded applications, where 15293@value{GDBN} may be restricted to a slow serial line for this search) 15294you may want to limit the size of this search, using one of these 15295commands: 15296 15297@table @code 15298@cindex @code{heuristic-fence-post} (Alpha, MIPS) 15299@item set heuristic-fence-post @var{limit} 15300Restrict @value{GDBN} to examining at most @var{limit} bytes in its 15301search for the beginning of a function. A value of @var{0} (the 15302default) means there is no limit. However, except for @var{0}, the 15303larger the limit the more bytes @code{heuristic-fence-post} must search 15304and therefore the longer it takes to run. You should only need to use 15305this command when debugging a stripped executable. 15306 15307@item show heuristic-fence-post 15308Display the current limit. 15309@end table 15310 15311@noindent 15312These commands are available @emph{only} when @value{GDBN} is configured 15313for debugging programs on Alpha or MIPS processors. 15314 15315Several MIPS-specific commands are available when debugging MIPS 15316programs: 15317 15318@table @code 15319@item set mips abi @var{arg} 15320@kindex set mips abi 15321@cindex set ABI for MIPS 15322Tell @value{GDBN} which MIPS ABI is used by the inferior. Possible 15323values of @var{arg} are: 15324 15325@table @samp 15326@item auto 15327The default ABI associated with the current binary (this is the 15328default). 15329@item o32 15330@item o64 15331@item n32 15332@item n64 15333@item eabi32 15334@item eabi64 15335@item auto 15336@end table 15337 15338@item show mips abi 15339@kindex show mips abi 15340Show the MIPS ABI used by @value{GDBN} to debug the inferior. 15341 15342@item set mipsfpu 15343@itemx show mipsfpu 15344@xref{MIPS Embedded, set mipsfpu}. 15345 15346@item set mips mask-address @var{arg} 15347@kindex set mips mask-address 15348@cindex MIPS addresses, masking 15349This command determines whether the most-significant 32 bits of 64-bit 15350MIPS addresses are masked off. The argument @var{arg} can be 15351@samp{on}, @samp{off}, or @samp{auto}. The latter is the default 15352setting, which lets @value{GDBN} determine the correct value. 15353 15354@item show mips mask-address 15355@kindex show mips mask-address 15356Show whether the upper 32 bits of MIPS addresses are masked off or 15357not. 15358 15359@item set remote-mips64-transfers-32bit-regs 15360@kindex set remote-mips64-transfers-32bit-regs 15361This command controls compatibility with 64-bit MIPS targets that 15362transfer data in 32-bit quantities. If you have an old MIPS 64 target 15363that transfers 32 bits for some registers, like @sc{sr} and @sc{fsr}, 15364and 64 bits for other registers, set this option to @samp{on}. 15365 15366@item show remote-mips64-transfers-32bit-regs 15367@kindex show remote-mips64-transfers-32bit-regs 15368Show the current setting of compatibility with older MIPS 64 targets. 15369 15370@item set debug mips 15371@kindex set debug mips 15372This command turns on and off debugging messages for the MIPS-specific 15373target code in @value{GDBN}. 15374 15375@item show debug mips 15376@kindex show debug mips 15377Show the current setting of MIPS debugging messages. 15378@end table 15379 15380 15381@node HPPA 15382@subsection HPPA 15383@cindex HPPA support 15384 15385When @value{GDBN} is debugging the HP PA architecture, it provides the 15386following special commands: 15387 15388@table @code 15389@item set debug hppa 15390@kindex set debug hppa 15391This command determines whether HPPA architecture-specific debugging 15392messages are to be displayed. 15393 15394@item show debug hppa 15395Show whether HPPA debugging messages are displayed. 15396 15397@item maint print unwind @var{address} 15398@kindex maint print unwind@r{, HPPA} 15399This command displays the contents of the unwind table entry at the 15400given @var{address}. 15401 15402@end table 15403 15404 15405@node SPU 15406@subsection Cell Broadband Engine SPU architecture 15407@cindex Cell Broadband Engine 15408@cindex SPU 15409 15410When @value{GDBN} is debugging the Cell Broadband Engine SPU architecture, 15411it provides the following special commands: 15412 15413@table @code 15414@item info spu event 15415@kindex info spu 15416Display SPU event facility status. Shows current event mask 15417and pending event status. 15418 15419@item info spu signal 15420Display SPU signal notification facility status. Shows pending 15421signal-control word and signal notification mode of both signal 15422notification channels. 15423 15424@item info spu mailbox 15425Display SPU mailbox facility status. Shows all pending entries, 15426in order of processing, in each of the SPU Write Outbound, 15427SPU Write Outbound Interrupt, and SPU Read Inbound mailboxes. 15428 15429@item info spu dma 15430Display MFC DMA status. Shows all pending commands in the MFC 15431DMA queue. For each entry, opcode, tag, class IDs, effective 15432and local store addresses and transfer size are shown. 15433 15434@item info spu proxydma 15435Display MFC Proxy-DMA status. Shows all pending commands in the MFC 15436Proxy-DMA queue. For each entry, opcode, tag, class IDs, effective 15437and local store addresses and transfer size are shown. 15438 15439@end table 15440 15441 15442@node Controlling GDB 15443@chapter Controlling @value{GDBN} 15444 15445You can alter the way @value{GDBN} interacts with you by using the 15446@code{set} command. For commands controlling how @value{GDBN} displays 15447data, see @ref{Print Settings, ,Print Settings}. Other settings are 15448described here. 15449 15450@menu 15451* Prompt:: Prompt 15452* Editing:: Command editing 15453* Command History:: Command history 15454* Screen Size:: Screen size 15455* Numbers:: Numbers 15456* ABI:: Configuring the current ABI 15457* Messages/Warnings:: Optional warnings and messages 15458* Debugging Output:: Optional messages about internal happenings 15459@end menu 15460 15461@node Prompt 15462@section Prompt 15463 15464@cindex prompt 15465 15466@value{GDBN} indicates its readiness to read a command by printing a string 15467called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You 15468can change the prompt string with the @code{set prompt} command. For 15469instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change 15470the prompt in one of the @value{GDBN} sessions so that you can always tell 15471which one you are talking to. 15472 15473@emph{Note:} @code{set prompt} does not add a space for you after the 15474prompt you set. This allows you to set a prompt which ends in a space 15475or a prompt that does not. 15476 15477@table @code 15478@kindex set prompt 15479@item set prompt @var{newprompt} 15480Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth. 15481 15482@kindex show prompt 15483@item show prompt 15484Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}} 15485@end table 15486 15487@node Editing 15488@section Command Editing 15489@cindex readline 15490@cindex command line editing 15491 15492@value{GDBN} reads its input commands via the @dfn{Readline} interface. This 15493@sc{gnu} library provides consistent behavior for programs which provide a 15494command line interface to the user. Advantages are @sc{gnu} Emacs-style 15495or @dfn{vi}-style inline editing of commands, @code{csh}-like history 15496substitution, and a storage and recall of command history across 15497debugging sessions. 15498 15499You may control the behavior of command line editing in @value{GDBN} with the 15500command @code{set}. 15501 15502@table @code 15503@kindex set editing 15504@cindex editing 15505@item set editing 15506@itemx set editing on 15507Enable command line editing (enabled by default). 15508 15509@item set editing off 15510Disable command line editing. 15511 15512@kindex show editing 15513@item show editing 15514Show whether command line editing is enabled. 15515@end table 15516 15517@xref{Command Line Editing}, for more details about the Readline 15518interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are 15519encouraged to read that chapter. 15520 15521@node Command History 15522@section Command History 15523@cindex command history 15524 15525@value{GDBN} can keep track of the commands you type during your 15526debugging sessions, so that you can be certain of precisely what 15527happened. Use these commands to manage the @value{GDBN} command 15528history facility. 15529 15530@value{GDBN} uses the @sc{gnu} History library, a part of the Readline 15531package, to provide the history facility. @xref{Using History 15532Interactively}, for the detailed description of the History library. 15533 15534To issue a command to @value{GDBN} without affecting certain aspects of 15535the state which is seen by users, prefix it with @samp{server } 15536(@pxref{Server Prefix}). This 15537means that this command will not affect the command history, nor will it 15538affect @value{GDBN}'s notion of which command to repeat if @key{RET} is 15539pressed on a line by itself. 15540 15541@cindex @code{server}, command prefix 15542The server prefix does not affect the recording of values into the value 15543history; to print a value without recording it into the value history, 15544use the @code{output} command instead of the @code{print} command. 15545 15546Here is the description of @value{GDBN} commands related to command 15547history. 15548 15549@table @code 15550@cindex history substitution 15551@cindex history file 15552@kindex set history filename 15553@cindex @env{GDBHISTFILE}, environment variable 15554@item set history filename @var{fname} 15555Set the name of the @value{GDBN} command history file to @var{fname}. 15556This is the file where @value{GDBN} reads an initial command history 15557list, and where it writes the command history from this session when it 15558exits. You can access this list through history expansion or through 15559the history command editing characters listed below. This file defaults 15560to the value of the environment variable @code{GDBHISTFILE}, or to 15561@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable 15562is not set. 15563 15564@cindex save command history 15565@kindex set history save 15566@item set history save 15567@itemx set history save on 15568Record command history in a file, whose name may be specified with the 15569@code{set history filename} command. By default, this option is disabled. 15570 15571@item set history save off 15572Stop recording command history in a file. 15573 15574@cindex history size 15575@kindex set history size 15576@cindex @env{HISTSIZE}, environment variable 15577@item set history size @var{size} 15578Set the number of commands which @value{GDBN} keeps in its history list. 15579This defaults to the value of the environment variable 15580@code{HISTSIZE}, or to 256 if this variable is not set. 15581@end table 15582 15583History expansion assigns special meaning to the character @kbd{!}. 15584@xref{Event Designators}, for more details. 15585 15586@cindex history expansion, turn on/off 15587Since @kbd{!} is also the logical not operator in C, history expansion 15588is off by default. If you decide to enable history expansion with the 15589@code{set history expansion on} command, you may sometimes need to 15590follow @kbd{!} (when it is used as logical not, in an expression) with 15591a space or a tab to prevent it from being expanded. The readline 15592history facilities do not attempt substitution on the strings 15593@kbd{!=} and @kbd{!(}, even when history expansion is enabled. 15594 15595The commands to control history expansion are: 15596 15597@table @code 15598@item set history expansion on 15599@itemx set history expansion 15600@kindex set history expansion 15601Enable history expansion. History expansion is off by default. 15602 15603@item set history expansion off 15604Disable history expansion. 15605 15606@c @group 15607@kindex show history 15608@item show history 15609@itemx show history filename 15610@itemx show history save 15611@itemx show history size 15612@itemx show history expansion 15613These commands display the state of the @value{GDBN} history parameters. 15614@code{show history} by itself displays all four states. 15615@c @end group 15616@end table 15617 15618@table @code 15619@kindex show commands 15620@cindex show last commands 15621@cindex display command history 15622@item show commands 15623Display the last ten commands in the command history. 15624 15625@item show commands @var{n} 15626Print ten commands centered on command number @var{n}. 15627 15628@item show commands + 15629Print ten commands just after the commands last printed. 15630@end table 15631 15632@node Screen Size 15633@section Screen Size 15634@cindex size of screen 15635@cindex pauses in output 15636 15637Certain commands to @value{GDBN} may produce large amounts of 15638information output to the screen. To help you read all of it, 15639@value{GDBN} pauses and asks you for input at the end of each page of 15640output. Type @key{RET} when you want to continue the output, or @kbd{q} 15641to discard the remaining output. Also, the screen width setting 15642determines when to wrap lines of output. Depending on what is being 15643printed, @value{GDBN} tries to break the line at a readable place, 15644rather than simply letting it overflow onto the following line. 15645 15646Normally @value{GDBN} knows the size of the screen from the terminal 15647driver software. For example, on Unix @value{GDBN} uses the termcap data base 15648together with the value of the @code{TERM} environment variable and the 15649@code{stty rows} and @code{stty cols} settings. If this is not correct, 15650you can override it with the @code{set height} and @code{set 15651width} commands: 15652 15653@table @code 15654@kindex set height 15655@kindex set width 15656@kindex show width 15657@kindex show height 15658@item set height @var{lpp} 15659@itemx show height 15660@itemx set width @var{cpl} 15661@itemx show width 15662These @code{set} commands specify a screen height of @var{lpp} lines and 15663a screen width of @var{cpl} characters. The associated @code{show} 15664commands display the current settings. 15665 15666If you specify a height of zero lines, @value{GDBN} does not pause during 15667output no matter how long the output is. This is useful if output is to a 15668file or to an editor buffer. 15669 15670Likewise, you can specify @samp{set width 0} to prevent @value{GDBN} 15671from wrapping its output. 15672 15673@item set pagination on 15674@itemx set pagination off 15675@kindex set pagination 15676Turn the output pagination on or off; the default is on. Turning 15677pagination off is the alternative to @code{set height 0}. 15678 15679@item show pagination 15680@kindex show pagination 15681Show the current pagination mode. 15682@end table 15683 15684@node Numbers 15685@section Numbers 15686@cindex number representation 15687@cindex entering numbers 15688 15689You can always enter numbers in octal, decimal, or hexadecimal in 15690@value{GDBN} by the usual conventions: octal numbers begin with 15691@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers 15692begin with @samp{0x}. Numbers that neither begin with @samp{0} or 15693@samp{0x}, nor end with a @samp{.} are, by default, entered in base 1569410; likewise, the default display for numbers---when no particular 15695format is specified---is base 10. You can change the default base for 15696both input and output with the commands described below. 15697 15698@table @code 15699@kindex set input-radix 15700@item set input-radix @var{base} 15701Set the default base for numeric input. Supported choices 15702for @var{base} are decimal 8, 10, or 16. @var{base} must itself be 15703specified either unambiguously or using the current input radix; for 15704example, any of 15705 15706@smallexample 15707set input-radix 012 15708set input-radix 10. 15709set input-radix 0xa 15710@end smallexample 15711 15712@noindent 15713sets the input base to decimal. On the other hand, @samp{set input-radix 10} 15714leaves the input radix unchanged, no matter what it was, since 15715@samp{10}, being without any leading or trailing signs of its base, is 15716interpreted in the current radix. Thus, if the current radix is 16, 15717@samp{10} is interpreted in hex, i.e.@: as 16 decimal, which doesn't 15718change the radix. 15719 15720@kindex set output-radix 15721@item set output-radix @var{base} 15722Set the default base for numeric display. Supported choices 15723for @var{base} are decimal 8, 10, or 16. @var{base} must itself be 15724specified either unambiguously or using the current input radix. 15725 15726@kindex show input-radix 15727@item show input-radix 15728Display the current default base for numeric input. 15729 15730@kindex show output-radix 15731@item show output-radix 15732Display the current default base for numeric display. 15733 15734@item set radix @r{[}@var{base}@r{]} 15735@itemx show radix 15736@kindex set radix 15737@kindex show radix 15738These commands set and show the default base for both input and output 15739of numbers. @code{set radix} sets the radix of input and output to 15740the same base; without an argument, it resets the radix back to its 15741default value of 10. 15742 15743@end table 15744 15745@node ABI 15746@section Configuring the Current ABI 15747 15748@value{GDBN} can determine the @dfn{ABI} (Application Binary Interface) of your 15749application automatically. However, sometimes you need to override its 15750conclusions. Use these commands to manage @value{GDBN}'s view of the 15751current ABI. 15752 15753@cindex OS ABI 15754@kindex set osabi 15755@kindex show osabi 15756 15757One @value{GDBN} configuration can debug binaries for multiple operating 15758system targets, either via remote debugging or native emulation. 15759@value{GDBN} will autodetect the @dfn{OS ABI} (Operating System ABI) in use, 15760but you can override its conclusion using the @code{set osabi} command. 15761One example where this is useful is in debugging of binaries which use 15762an alternate C library (e.g.@: @sc{uClibc} for @sc{gnu}/Linux) which does 15763not have the same identifying marks that the standard C library for your 15764platform provides. 15765 15766@table @code 15767@item show osabi 15768Show the OS ABI currently in use. 15769 15770@item set osabi 15771With no argument, show the list of registered available OS ABI's. 15772 15773@item set osabi @var{abi} 15774Set the current OS ABI to @var{abi}. 15775@end table 15776 15777@cindex float promotion 15778 15779Generally, the way that an argument of type @code{float} is passed to a 15780function depends on whether the function is prototyped. For a prototyped 15781(i.e.@: ANSI/ISO style) function, @code{float} arguments are passed unchanged, 15782according to the architecture's convention for @code{float}. For unprototyped 15783(i.e.@: K&R style) functions, @code{float} arguments are first promoted to type 15784@code{double} and then passed. 15785 15786Unfortunately, some forms of debug information do not reliably indicate whether 15787a function is prototyped. If @value{GDBN} calls a function that is not marked 15788as prototyped, it consults @kbd{set coerce-float-to-double}. 15789 15790@table @code 15791@kindex set coerce-float-to-double 15792@item set coerce-float-to-double 15793@itemx set coerce-float-to-double on 15794Arguments of type @code{float} will be promoted to @code{double} when passed 15795to an unprototyped function. This is the default setting. 15796 15797@item set coerce-float-to-double off 15798Arguments of type @code{float} will be passed directly to unprototyped 15799functions. 15800 15801@kindex show coerce-float-to-double 15802@item show coerce-float-to-double 15803Show the current setting of promoting @code{float} to @code{double}. 15804@end table 15805 15806@kindex set cp-abi 15807@kindex show cp-abi 15808@value{GDBN} needs to know the ABI used for your program's C@t{++} 15809objects. The correct C@t{++} ABI depends on which C@t{++} compiler was 15810used to build your application. @value{GDBN} only fully supports 15811programs with a single C@t{++} ABI; if your program contains code using 15812multiple C@t{++} ABI's or if @value{GDBN} can not identify your 15813program's ABI correctly, you can tell @value{GDBN} which ABI to use. 15814Currently supported ABI's include ``gnu-v2'', for @code{g++} versions 15815before 3.0, ``gnu-v3'', for @code{g++} versions 3.0 and later, and 15816``hpaCC'' for the HP ANSI C@t{++} compiler. Other C@t{++} compilers may 15817use the ``gnu-v2'' or ``gnu-v3'' ABI's as well. The default setting is 15818``auto''. 15819 15820@table @code 15821@item show cp-abi 15822Show the C@t{++} ABI currently in use. 15823 15824@item set cp-abi 15825With no argument, show the list of supported C@t{++} ABI's. 15826 15827@item set cp-abi @var{abi} 15828@itemx set cp-abi auto 15829Set the current C@t{++} ABI to @var{abi}, or return to automatic detection. 15830@end table 15831 15832@node Messages/Warnings 15833@section Optional Warnings and Messages 15834 15835@cindex verbose operation 15836@cindex optional warnings 15837By default, @value{GDBN} is silent about its inner workings. If you are 15838running on a slow machine, you may want to use the @code{set verbose} 15839command. This makes @value{GDBN} tell you when it does a lengthy 15840internal operation, so you will not think it has crashed. 15841 15842Currently, the messages controlled by @code{set verbose} are those 15843which announce that the symbol table for a source file is being read; 15844see @code{symbol-file} in @ref{Files, ,Commands to Specify Files}. 15845 15846@table @code 15847@kindex set verbose 15848@item set verbose on 15849Enables @value{GDBN} output of certain informational messages. 15850 15851@item set verbose off 15852Disables @value{GDBN} output of certain informational messages. 15853 15854@kindex show verbose 15855@item show verbose 15856Displays whether @code{set verbose} is on or off. 15857@end table 15858 15859By default, if @value{GDBN} encounters bugs in the symbol table of an 15860object file, it is silent; but if you are debugging a compiler, you may 15861find this information useful (@pxref{Symbol Errors, ,Errors Reading 15862Symbol Files}). 15863 15864@table @code 15865 15866@kindex set complaints 15867@item set complaints @var{limit} 15868Permits @value{GDBN} to output @var{limit} complaints about each type of 15869unusual symbols before becoming silent about the problem. Set 15870@var{limit} to zero to suppress all complaints; set it to a large number 15871to prevent complaints from being suppressed. 15872 15873@kindex show complaints 15874@item show complaints 15875Displays how many symbol complaints @value{GDBN} is permitted to produce. 15876 15877@end table 15878 15879By default, @value{GDBN} is cautious, and asks what sometimes seems to be a 15880lot of stupid questions to confirm certain commands. For example, if 15881you try to run a program which is already running: 15882 15883@smallexample 15884(@value{GDBP}) run 15885The program being debugged has been started already. 15886Start it from the beginning? (y or n) 15887@end smallexample 15888 15889If you are willing to unflinchingly face the consequences of your own 15890commands, you can disable this ``feature'': 15891 15892@table @code 15893 15894@kindex set confirm 15895@cindex flinching 15896@cindex confirmation 15897@cindex stupid questions 15898@item set confirm off 15899Disables confirmation requests. 15900 15901@item set confirm on 15902Enables confirmation requests (the default). 15903 15904@kindex show confirm 15905@item show confirm 15906Displays state of confirmation requests. 15907 15908@end table 15909 15910@cindex command tracing 15911If you need to debug user-defined commands or sourced files you may find it 15912useful to enable @dfn{command tracing}. In this mode each command will be 15913printed as it is executed, prefixed with one or more @samp{+} symbols, the 15914quantity denoting the call depth of each command. 15915 15916@table @code 15917@kindex set trace-commands 15918@cindex command scripts, debugging 15919@item set trace-commands on 15920Enable command tracing. 15921@item set trace-commands off 15922Disable command tracing. 15923@item show trace-commands 15924Display the current state of command tracing. 15925@end table 15926 15927@node Debugging Output 15928@section Optional Messages about Internal Happenings 15929@cindex optional debugging messages 15930 15931@value{GDBN} has commands that enable optional debugging messages from 15932various @value{GDBN} subsystems; normally these commands are of 15933interest to @value{GDBN} maintainers, or when reporting a bug. This 15934section documents those commands. 15935 15936@table @code 15937@kindex set exec-done-display 15938@item set exec-done-display 15939Turns on or off the notification of asynchronous commands' 15940completion. When on, @value{GDBN} will print a message when an 15941asynchronous command finishes its execution. The default is off. 15942@kindex show exec-done-display 15943@item show exec-done-display 15944Displays the current setting of asynchronous command completion 15945notification. 15946@kindex set debug 15947@cindex gdbarch debugging info 15948@cindex architecture debugging info 15949@item set debug arch 15950Turns on or off display of gdbarch debugging info. The default is off 15951@kindex show debug 15952@item show debug arch 15953Displays the current state of displaying gdbarch debugging info. 15954@item set debug aix-thread 15955@cindex AIX threads 15956Display debugging messages about inner workings of the AIX thread 15957module. 15958@item show debug aix-thread 15959Show the current state of AIX thread debugging info display. 15960@item set debug event 15961@cindex event debugging info 15962Turns on or off display of @value{GDBN} event debugging info. The 15963default is off. 15964@item show debug event 15965Displays the current state of displaying @value{GDBN} event debugging 15966info. 15967@item set debug expression 15968@cindex expression debugging info 15969Turns on or off display of debugging info about @value{GDBN} 15970expression parsing. The default is off. 15971@item show debug expression 15972Displays the current state of displaying debugging info about 15973@value{GDBN} expression parsing. 15974@item set debug frame 15975@cindex frame debugging info 15976Turns on or off display of @value{GDBN} frame debugging info. The 15977default is off. 15978@item show debug frame 15979Displays the current state of displaying @value{GDBN} frame debugging 15980info. 15981@item set debug infrun 15982@cindex inferior debugging info 15983Turns on or off display of @value{GDBN} debugging info for running the inferior. 15984The default is off. @file{infrun.c} contains GDB's runtime state machine used 15985for implementing operations such as single-stepping the inferior. 15986@item show debug infrun 15987Displays the current state of @value{GDBN} inferior debugging. 15988@item set debug lin-lwp 15989@cindex @sc{gnu}/Linux LWP debug messages 15990@cindex Linux lightweight processes 15991Turns on or off debugging messages from the Linux LWP debug support. 15992@item show debug lin-lwp 15993Show the current state of Linux LWP debugging messages. 15994@item set debug observer 15995@cindex observer debugging info 15996Turns on or off display of @value{GDBN} observer debugging. This 15997includes info such as the notification of observable events. 15998@item show debug observer 15999Displays the current state of observer debugging. 16000@item set debug overload 16001@cindex C@t{++} overload debugging info 16002Turns on or off display of @value{GDBN} C@t{++} overload debugging 16003info. This includes info such as ranking of functions, etc. The default 16004is off. 16005@item show debug overload 16006Displays the current state of displaying @value{GDBN} C@t{++} overload 16007debugging info. 16008@cindex packets, reporting on stdout 16009@cindex serial connections, debugging 16010@cindex debug remote protocol 16011@cindex remote protocol debugging 16012@cindex display remote packets 16013@item set debug remote 16014Turns on or off display of reports on all packets sent back and forth across 16015the serial line to the remote machine. The info is printed on the 16016@value{GDBN} standard output stream. The default is off. 16017@item show debug remote 16018Displays the state of display of remote packets. 16019@item set debug serial 16020Turns on or off display of @value{GDBN} serial debugging info. The 16021default is off. 16022@item show debug serial 16023Displays the current state of displaying @value{GDBN} serial debugging 16024info. 16025@item set debug solib-frv 16026@cindex FR-V shared-library debugging 16027Turns on or off debugging messages for FR-V shared-library code. 16028@item show debug solib-frv 16029Display the current state of FR-V shared-library code debugging 16030messages. 16031@item set debug target 16032@cindex target debugging info 16033Turns on or off display of @value{GDBN} target debugging info. This info 16034includes what is going on at the target level of GDB, as it happens. The 16035default is 0. Set it to 1 to track events, and to 2 to also track the 16036value of large memory transfers. Changes to this flag do not take effect 16037until the next time you connect to a target or use the @code{run} command. 16038@item show debug target 16039Displays the current state of displaying @value{GDBN} target debugging 16040info. 16041@item set debugvarobj 16042@cindex variable object debugging info 16043Turns on or off display of @value{GDBN} variable object debugging 16044info. The default is off. 16045@item show debugvarobj 16046Displays the current state of displaying @value{GDBN} variable object 16047debugging info. 16048@item set debug xml 16049@cindex XML parser debugging 16050Turns on or off debugging messages for built-in XML parsers. 16051@item show debug xml 16052Displays the current state of XML debugging messages. 16053@end table 16054 16055@node Sequences 16056@chapter Canned Sequences of Commands 16057 16058Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint 16059Command Lists}), @value{GDBN} provides two ways to store sequences of 16060commands for execution as a unit: user-defined commands and command 16061files. 16062 16063@menu 16064* Define:: How to define your own commands 16065* Hooks:: Hooks for user-defined commands 16066* Command Files:: How to write scripts of commands to be stored in a file 16067* Output:: Commands for controlled output 16068@end menu 16069 16070@node Define 16071@section User-defined Commands 16072 16073@cindex user-defined command 16074@cindex arguments, to user-defined commands 16075A @dfn{user-defined command} is a sequence of @value{GDBN} commands to 16076which you assign a new name as a command. This is done with the 16077@code{define} command. User commands may accept up to 10 arguments 16078separated by whitespace. Arguments are accessed within the user command 16079via @code{$arg0@dots{}$arg9}. A trivial example: 16080 16081@smallexample 16082define adder 16083 print $arg0 + $arg1 + $arg2 16084end 16085@end smallexample 16086 16087@noindent 16088To execute the command use: 16089 16090@smallexample 16091adder 1 2 3 16092@end smallexample 16093 16094@noindent 16095This defines the command @code{adder}, which prints the sum of 16096its three arguments. Note the arguments are text substitutions, so they may 16097reference variables, use complex expressions, or even perform inferior 16098functions calls. 16099 16100@cindex argument count in user-defined commands 16101@cindex how many arguments (user-defined commands) 16102In addition, @code{$argc} may be used to find out how many arguments have 16103been passed. This expands to a number in the range 0@dots{}10. 16104 16105@smallexample 16106define adder 16107 if $argc == 2 16108 print $arg0 + $arg1 16109 end 16110 if $argc == 3 16111 print $arg0 + $arg1 + $arg2 16112 end 16113end 16114@end smallexample 16115 16116@table @code 16117 16118@kindex define 16119@item define @var{commandname} 16120Define a command named @var{commandname}. If there is already a command 16121by that name, you are asked to confirm that you want to redefine it. 16122 16123The definition of the command is made up of other @value{GDBN} command lines, 16124which are given following the @code{define} command. The end of these 16125commands is marked by a line containing @code{end}. 16126 16127@kindex document 16128@kindex end@r{ (user-defined commands)} 16129@item document @var{commandname} 16130Document the user-defined command @var{commandname}, so that it can be 16131accessed by @code{help}. The command @var{commandname} must already be 16132defined. This command reads lines of documentation just as @code{define} 16133reads the lines of the command definition, ending with @code{end}. 16134After the @code{document} command is finished, @code{help} on command 16135@var{commandname} displays the documentation you have written. 16136 16137You may use the @code{document} command again to change the 16138documentation of a command. Redefining the command with @code{define} 16139does not change the documentation. 16140 16141@kindex dont-repeat 16142@cindex don't repeat command 16143@item dont-repeat 16144Used inside a user-defined command, this tells @value{GDBN} that this 16145command should not be repeated when the user hits @key{RET} 16146(@pxref{Command Syntax, repeat last command}). 16147 16148@kindex help user-defined 16149@item help user-defined 16150List all user-defined commands, with the first line of the documentation 16151(if any) for each. 16152 16153@kindex show user 16154@item show user 16155@itemx show user @var{commandname} 16156Display the @value{GDBN} commands used to define @var{commandname} (but 16157not its documentation). If no @var{commandname} is given, display the 16158definitions for all user-defined commands. 16159 16160@cindex infinite recursion in user-defined commands 16161@kindex show max-user-call-depth 16162@kindex set max-user-call-depth 16163@item show max-user-call-depth 16164@itemx set max-user-call-depth 16165The value of @code{max-user-call-depth} controls how many recursion 16166levels are allowed in user-defined commands before @value{GDBN} suspects an 16167infinite recursion and aborts the command. 16168@end table 16169 16170In addition to the above commands, user-defined commands frequently 16171use control flow commands, described in @ref{Command Files}. 16172 16173When user-defined commands are executed, the 16174commands of the definition are not printed. An error in any command 16175stops execution of the user-defined command. 16176 16177If used interactively, commands that would ask for confirmation proceed 16178without asking when used inside a user-defined command. Many @value{GDBN} 16179commands that normally print messages to say what they are doing omit the 16180messages when used in a user-defined command. 16181 16182@node Hooks 16183@section User-defined Command Hooks 16184@cindex command hooks 16185@cindex hooks, for commands 16186@cindex hooks, pre-command 16187 16188@kindex hook 16189You may define @dfn{hooks}, which are a special kind of user-defined 16190command. Whenever you run the command @samp{foo}, if the user-defined 16191command @samp{hook-foo} exists, it is executed (with no arguments) 16192before that command. 16193 16194@cindex hooks, post-command 16195@kindex hookpost 16196A hook may also be defined which is run after the command you executed. 16197Whenever you run the command @samp{foo}, if the user-defined command 16198@samp{hookpost-foo} exists, it is executed (with no arguments) after 16199that command. Post-execution hooks may exist simultaneously with 16200pre-execution hooks, for the same command. 16201 16202It is valid for a hook to call the command which it hooks. If this 16203occurs, the hook is not re-executed, thereby avoiding infinite recursion. 16204 16205@c It would be nice if hookpost could be passed a parameter indicating 16206@c if the command it hooks executed properly or not. FIXME! 16207 16208@kindex stop@r{, a pseudo-command} 16209In addition, a pseudo-command, @samp{stop} exists. Defining 16210(@samp{hook-stop}) makes the associated commands execute every time 16211execution stops in your program: before breakpoint commands are run, 16212displays are printed, or the stack frame is printed. 16213 16214For example, to ignore @code{SIGALRM} signals while 16215single-stepping, but treat them normally during normal execution, 16216you could define: 16217 16218@smallexample 16219define hook-stop 16220handle SIGALRM nopass 16221end 16222 16223define hook-run 16224handle SIGALRM pass 16225end 16226 16227define hook-continue 16228handle SIGALRM pass 16229end 16230@end smallexample 16231 16232As a further example, to hook at the beginning and end of the @code{echo} 16233command, and to add extra text to the beginning and end of the message, 16234you could define: 16235 16236@smallexample 16237define hook-echo 16238echo <<<--- 16239end 16240 16241define hookpost-echo 16242echo --->>>\n 16243end 16244 16245(@value{GDBP}) echo Hello World 16246<<<---Hello World--->>> 16247(@value{GDBP}) 16248 16249@end smallexample 16250 16251You can define a hook for any single-word command in @value{GDBN}, but 16252not for command aliases; you should define a hook for the basic command 16253name, e.g.@: @code{backtrace} rather than @code{bt}. 16254@c FIXME! So how does Joe User discover whether a command is an alias 16255@c or not? 16256If an error occurs during the execution of your hook, execution of 16257@value{GDBN} commands stops and @value{GDBN} issues a prompt 16258(before the command that you actually typed had a chance to run). 16259 16260If you try to define a hook which does not match any known command, you 16261get a warning from the @code{define} command. 16262 16263@node Command Files 16264@section Command Files 16265 16266@cindex command files 16267@cindex scripting commands 16268A command file for @value{GDBN} is a text file made of lines that are 16269@value{GDBN} commands. Comments (lines starting with @kbd{#}) may 16270also be included. An empty line in a command file does nothing; it 16271does not mean to repeat the last command, as it would from the 16272terminal. 16273 16274You can request the execution of a command file with the @code{source} 16275command: 16276 16277@table @code 16278@kindex source 16279@cindex execute commands from a file 16280@item source [@code{-v}] @var{filename} 16281Execute the command file @var{filename}. 16282@end table 16283 16284The lines in a command file are generally executed sequentially, 16285unless the order of execution is changed by one of the 16286@emph{flow-control commands} described below. The commands are not 16287printed as they are executed. An error in any command terminates 16288execution of the command file and control is returned to the console. 16289 16290@value{GDBN} searches for @var{filename} in the current directory and then 16291on the search path (specified with the @samp{directory} command). 16292 16293If @code{-v}, for verbose mode, is given then @value{GDBN} displays 16294each command as it is executed. The option must be given before 16295@var{filename}, and is interpreted as part of the filename anywhere else. 16296 16297Commands that would ask for confirmation if used interactively proceed 16298without asking when used in a command file. Many @value{GDBN} commands that 16299normally print messages to say what they are doing omit the messages 16300when called from command files. 16301 16302@value{GDBN} also accepts command input from standard input. In this 16303mode, normal output goes to standard output and error output goes to 16304standard error. Errors in a command file supplied on standard input do 16305not terminate execution of the command file---execution continues with 16306the next command. 16307 16308@smallexample 16309gdb < cmds > log 2>&1 16310@end smallexample 16311 16312(The syntax above will vary depending on the shell used.) This example 16313will execute commands from the file @file{cmds}. All output and errors 16314would be directed to @file{log}. 16315 16316Since commands stored on command files tend to be more general than 16317commands typed interactively, they frequently need to deal with 16318complicated situations, such as different or unexpected values of 16319variables and symbols, changes in how the program being debugged is 16320built, etc. @value{GDBN} provides a set of flow-control commands to 16321deal with these complexities. Using these commands, you can write 16322complex scripts that loop over data structures, execute commands 16323conditionally, etc. 16324 16325@table @code 16326@kindex if 16327@kindex else 16328@item if 16329@itemx else 16330This command allows to include in your script conditionally executed 16331commands. The @code{if} command takes a single argument, which is an 16332expression to evaluate. It is followed by a series of commands that 16333are executed only if the expression is true (its value is nonzero). 16334There can then optionally be an @code{else} line, followed by a series 16335of commands that are only executed if the expression was false. The 16336end of the list is marked by a line containing @code{end}. 16337 16338@kindex while 16339@item while 16340This command allows to write loops. Its syntax is similar to 16341@code{if}: the command takes a single argument, which is an expression 16342to evaluate, and must be followed by the commands to execute, one per 16343line, terminated by an @code{end}. These commands are called the 16344@dfn{body} of the loop. The commands in the body of @code{while} are 16345executed repeatedly as long as the expression evaluates to true. 16346 16347@kindex loop_break 16348@item loop_break 16349This command exits the @code{while} loop in whose body it is included. 16350Execution of the script continues after that @code{while}s @code{end} 16351line. 16352 16353@kindex loop_continue 16354@item loop_continue 16355This command skips the execution of the rest of the body of commands 16356in the @code{while} loop in whose body it is included. Execution 16357branches to the beginning of the @code{while} loop, where it evaluates 16358the controlling expression. 16359 16360@kindex end@r{ (if/else/while commands)} 16361@item end 16362Terminate the block of commands that are the body of @code{if}, 16363@code{else}, or @code{while} flow-control commands. 16364@end table 16365 16366 16367@node Output 16368@section Commands for Controlled Output 16369 16370During the execution of a command file or a user-defined command, normal 16371@value{GDBN} output is suppressed; the only output that appears is what is 16372explicitly printed by the commands in the definition. This section 16373describes three commands useful for generating exactly the output you 16374want. 16375 16376@table @code 16377@kindex echo 16378@item echo @var{text} 16379@c I do not consider backslash-space a standard C escape sequence 16380@c because it is not in ANSI. 16381Print @var{text}. Nonprinting characters can be included in 16382@var{text} using C escape sequences, such as @samp{\n} to print a 16383newline. @strong{No newline is printed unless you specify one.} 16384In addition to the standard C escape sequences, a backslash followed 16385by a space stands for a space. This is useful for displaying a 16386string with spaces at the beginning or the end, since leading and 16387trailing spaces are otherwise trimmed from all arguments. 16388To print @samp{@w{ }and foo =@w{ }}, use the command 16389@samp{echo \@w{ }and foo = \@w{ }}. 16390 16391A backslash at the end of @var{text} can be used, as in C, to continue 16392the command onto subsequent lines. For example, 16393 16394@smallexample 16395echo This is some text\n\ 16396which is continued\n\ 16397onto several lines.\n 16398@end smallexample 16399 16400produces the same output as 16401 16402@smallexample 16403echo This is some text\n 16404echo which is continued\n 16405echo onto several lines.\n 16406@end smallexample 16407 16408@kindex output 16409@item output @var{expression} 16410Print the value of @var{expression} and nothing but that value: no 16411newlines, no @samp{$@var{nn} = }. The value is not entered in the 16412value history either. @xref{Expressions, ,Expressions}, for more information 16413on expressions. 16414 16415@item output/@var{fmt} @var{expression} 16416Print the value of @var{expression} in format @var{fmt}. You can use 16417the same formats as for @code{print}. @xref{Output Formats,,Output 16418Formats}, for more information. 16419 16420@kindex printf 16421@item printf @var{string}, @var{expressions}@dots{} 16422Print the values of the @var{expressions} under the control of 16423@var{string}. The @var{expressions} are separated by commas and may be 16424either numbers or pointers. Their values are printed as specified by 16425@var{string}, exactly as if your program were to execute the C 16426subroutine 16427@c FIXME: the above implies that at least all ANSI C formats are 16428@c supported, but it isn't true: %E and %G don't work (or so it seems). 16429@c Either this is a bug, or the manual should document what formats are 16430@c supported. 16431 16432@smallexample 16433printf (@var{string}, @var{expressions}@dots{}); 16434@end smallexample 16435 16436For example, you can print two values in hex like this: 16437 16438@smallexample 16439printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo 16440@end smallexample 16441 16442The only backslash-escape sequences that you can use in the format 16443string are the simple ones that consist of backslash followed by a 16444letter. 16445@end table 16446 16447@node Interpreters 16448@chapter Command Interpreters 16449@cindex command interpreters 16450 16451@value{GDBN} supports multiple command interpreters, and some command 16452infrastructure to allow users or user interface writers to switch 16453between interpreters or run commands in other interpreters. 16454 16455@value{GDBN} currently supports two command interpreters, the console 16456interpreter (sometimes called the command-line interpreter or @sc{cli}) 16457and the machine interface interpreter (or @sc{gdb/mi}). This manual 16458describes both of these interfaces in great detail. 16459 16460By default, @value{GDBN} will start with the console interpreter. 16461However, the user may choose to start @value{GDBN} with another 16462interpreter by specifying the @option{-i} or @option{--interpreter} 16463startup options. Defined interpreters include: 16464 16465@table @code 16466@item console 16467@cindex console interpreter 16468The traditional console or command-line interpreter. This is the most often 16469used interpreter with @value{GDBN}. With no interpreter specified at runtime, 16470@value{GDBN} will use this interpreter. 16471 16472@item mi 16473@cindex mi interpreter 16474The newest @sc{gdb/mi} interface (currently @code{mi2}). Used primarily 16475by programs wishing to use @value{GDBN} as a backend for a debugger GUI 16476or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi} 16477Interface}. 16478 16479@item mi2 16480@cindex mi2 interpreter 16481The current @sc{gdb/mi} interface. 16482 16483@item mi1 16484@cindex mi1 interpreter 16485The @sc{gdb/mi} interface included in @value{GDBN} 5.1, 5.2, and 5.3. 16486 16487@end table 16488 16489@cindex invoke another interpreter 16490The interpreter being used by @value{GDBN} may not be dynamically 16491switched at runtime. Although possible, this could lead to a very 16492precarious situation. Consider an IDE using @sc{gdb/mi}. If a user 16493enters the command "interpreter-set console" in a console view, 16494@value{GDBN} would switch to using the console interpreter, rendering 16495the IDE inoperable! 16496 16497@kindex interpreter-exec 16498Although you may only choose a single interpreter at startup, you may execute 16499commands in any interpreter from the current interpreter using the appropriate 16500command. If you are running the console interpreter, simply use the 16501@code{interpreter-exec} command: 16502 16503@smallexample 16504interpreter-exec mi "-data-list-register-names" 16505@end smallexample 16506 16507@sc{gdb/mi} has a similar command, although it is only available in versions of 16508@value{GDBN} which support @sc{gdb/mi} version 2 (or greater). 16509 16510@node TUI 16511@chapter @value{GDBN} Text User Interface 16512@cindex TUI 16513@cindex Text User Interface 16514 16515@menu 16516* TUI Overview:: TUI overview 16517* TUI Keys:: TUI key bindings 16518* TUI Single Key Mode:: TUI single key mode 16519* TUI Commands:: TUI-specific commands 16520* TUI Configuration:: TUI configuration variables 16521@end menu 16522 16523The @value{GDBN} Text User Interface (TUI) is a terminal 16524interface which uses the @code{curses} library to show the source 16525file, the assembly output, the program registers and @value{GDBN} 16526commands in separate text windows. The TUI mode is supported only 16527on platforms where a suitable version of the @code{curses} library 16528is available. 16529 16530@pindex @value{GDBTUI} 16531The TUI mode is enabled by default when you invoke @value{GDBN} as 16532either @samp{@value{GDBTUI}} or @samp{@value{GDBP} -tui}. 16533You can also switch in and out of TUI mode while @value{GDBN} runs by 16534using various TUI commands and key bindings, such as @kbd{C-x C-a}. 16535@xref{TUI Keys, ,TUI Key Bindings}. 16536 16537@node TUI Overview 16538@section TUI Overview 16539 16540In TUI mode, @value{GDBN} can display several text windows: 16541 16542@table @emph 16543@item command 16544This window is the @value{GDBN} command window with the @value{GDBN} 16545prompt and the @value{GDBN} output. The @value{GDBN} input is still 16546managed using readline. 16547 16548@item source 16549The source window shows the source file of the program. The current 16550line and active breakpoints are displayed in this window. 16551 16552@item assembly 16553The assembly window shows the disassembly output of the program. 16554 16555@item register 16556This window shows the processor registers. Registers are highlighted 16557when their values change. 16558@end table 16559 16560The source and assembly windows show the current program position 16561by highlighting the current line and marking it with a @samp{>} marker. 16562Breakpoints are indicated with two markers. The first marker 16563indicates the breakpoint type: 16564 16565@table @code 16566@item B 16567Breakpoint which was hit at least once. 16568 16569@item b 16570Breakpoint which was never hit. 16571 16572@item H 16573Hardware breakpoint which was hit at least once. 16574 16575@item h 16576Hardware breakpoint which was never hit. 16577@end table 16578 16579The second marker indicates whether the breakpoint is enabled or not: 16580 16581@table @code 16582@item + 16583Breakpoint is enabled. 16584 16585@item - 16586Breakpoint is disabled. 16587@end table 16588 16589The source, assembly and register windows are updated when the current 16590thread changes, when the frame changes, or when the program counter 16591changes. 16592 16593These windows are not all visible at the same time. The command 16594window is always visible. The others can be arranged in several 16595layouts: 16596 16597@itemize @bullet 16598@item 16599source only, 16600 16601@item 16602assembly only, 16603 16604@item 16605source and assembly, 16606 16607@item 16608source and registers, or 16609 16610@item 16611assembly and registers. 16612@end itemize 16613 16614A status line above the command window shows the following information: 16615 16616@table @emph 16617@item target 16618Indicates the current @value{GDBN} target. 16619(@pxref{Targets, ,Specifying a Debugging Target}). 16620 16621@item process 16622Gives the current process or thread number. 16623When no process is being debugged, this field is set to @code{No process}. 16624 16625@item function 16626Gives the current function name for the selected frame. 16627The name is demangled if demangling is turned on (@pxref{Print Settings}). 16628When there is no symbol corresponding to the current program counter, 16629the string @code{??} is displayed. 16630 16631@item line 16632Indicates the current line number for the selected frame. 16633When the current line number is not known, the string @code{??} is displayed. 16634 16635@item pc 16636Indicates the current program counter address. 16637@end table 16638 16639@node TUI Keys 16640@section TUI Key Bindings 16641@cindex TUI key bindings 16642 16643The TUI installs several key bindings in the readline keymaps 16644(@pxref{Command Line Editing}). The following key bindings 16645are installed for both TUI mode and the @value{GDBN} standard mode. 16646 16647@table @kbd 16648@kindex C-x C-a 16649@item C-x C-a 16650@kindex C-x a 16651@itemx C-x a 16652@kindex C-x A 16653@itemx C-x A 16654Enter or leave the TUI mode. When leaving the TUI mode, 16655the curses window management stops and @value{GDBN} operates using 16656its standard mode, writing on the terminal directly. When reentering 16657the TUI mode, control is given back to the curses windows. 16658The screen is then refreshed. 16659 16660@kindex C-x 1 16661@item C-x 1 16662Use a TUI layout with only one window. The layout will 16663either be @samp{source} or @samp{assembly}. When the TUI mode 16664is not active, it will switch to the TUI mode. 16665 16666Think of this key binding as the Emacs @kbd{C-x 1} binding. 16667 16668@kindex C-x 2 16669@item C-x 2 16670Use a TUI layout with at least two windows. When the current 16671layout already has two windows, the next layout with two windows is used. 16672When a new layout is chosen, one window will always be common to the 16673previous layout and the new one. 16674 16675Think of it as the Emacs @kbd{C-x 2} binding. 16676 16677@kindex C-x o 16678@item C-x o 16679Change the active window. The TUI associates several key bindings 16680(like scrolling and arrow keys) with the active window. This command 16681gives the focus to the next TUI window. 16682 16683Think of it as the Emacs @kbd{C-x o} binding. 16684 16685@kindex C-x s 16686@item C-x s 16687Switch in and out of the TUI SingleKey mode that binds single 16688keys to @value{GDBN} commands (@pxref{TUI Single Key Mode}). 16689@end table 16690 16691The following key bindings only work in the TUI mode: 16692 16693@table @asis 16694@kindex PgUp 16695@item @key{PgUp} 16696Scroll the active window one page up. 16697 16698@kindex PgDn 16699@item @key{PgDn} 16700Scroll the active window one page down. 16701 16702@kindex Up 16703@item @key{Up} 16704Scroll the active window one line up. 16705 16706@kindex Down 16707@item @key{Down} 16708Scroll the active window one line down. 16709 16710@kindex Left 16711@item @key{Left} 16712Scroll the active window one column left. 16713 16714@kindex Right 16715@item @key{Right} 16716Scroll the active window one column right. 16717 16718@kindex C-L 16719@item @kbd{C-L} 16720Refresh the screen. 16721@end table 16722 16723Because the arrow keys scroll the active window in the TUI mode, they 16724are not available for their normal use by readline unless the command 16725window has the focus. When another window is active, you must use 16726other readline key bindings such as @kbd{C-p}, @kbd{C-n}, @kbd{C-b} 16727and @kbd{C-f} to control the command window. 16728 16729@node TUI Single Key Mode 16730@section TUI Single Key Mode 16731@cindex TUI single key mode 16732 16733The TUI also provides a @dfn{SingleKey} mode, which binds several 16734frequently used @value{GDBN} commands to single keys. Type @kbd{C-x s} to 16735switch into this mode, where the following key bindings are used: 16736 16737@table @kbd 16738@kindex c @r{(SingleKey TUI key)} 16739@item c 16740continue 16741 16742@kindex d @r{(SingleKey TUI key)} 16743@item d 16744down 16745 16746@kindex f @r{(SingleKey TUI key)} 16747@item f 16748finish 16749 16750@kindex n @r{(SingleKey TUI key)} 16751@item n 16752next 16753 16754@kindex q @r{(SingleKey TUI key)} 16755@item q 16756exit the SingleKey mode. 16757 16758@kindex r @r{(SingleKey TUI key)} 16759@item r 16760run 16761 16762@kindex s @r{(SingleKey TUI key)} 16763@item s 16764step 16765 16766@kindex u @r{(SingleKey TUI key)} 16767@item u 16768up 16769 16770@kindex v @r{(SingleKey TUI key)} 16771@item v 16772info locals 16773 16774@kindex w @r{(SingleKey TUI key)} 16775@item w 16776where 16777@end table 16778 16779Other keys temporarily switch to the @value{GDBN} command prompt. 16780The key that was pressed is inserted in the editing buffer so that 16781it is possible to type most @value{GDBN} commands without interaction 16782with the TUI SingleKey mode. Once the command is entered the TUI 16783SingleKey mode is restored. The only way to permanently leave 16784this mode is by typing @kbd{q} or @kbd{C-x s}. 16785 16786 16787@node TUI Commands 16788@section TUI-specific Commands 16789@cindex TUI commands 16790 16791The TUI has specific commands to control the text windows. 16792These commands are always available, even when @value{GDBN} is not in 16793the TUI mode. When @value{GDBN} is in the standard mode, most 16794of these commands will automatically switch to the TUI mode. 16795 16796@table @code 16797@item info win 16798@kindex info win 16799List and give the size of all displayed windows. 16800 16801@item layout next 16802@kindex layout 16803Display the next layout. 16804 16805@item layout prev 16806Display the previous layout. 16807 16808@item layout src 16809Display the source window only. 16810 16811@item layout asm 16812Display the assembly window only. 16813 16814@item layout split 16815Display the source and assembly window. 16816 16817@item layout regs 16818Display the register window together with the source or assembly window. 16819 16820@item focus next 16821@kindex focus 16822Make the next window active for scrolling. 16823 16824@item focus prev 16825Make the previous window active for scrolling. 16826 16827@item focus src 16828Make the source window active for scrolling. 16829 16830@item focus asm 16831Make the assembly window active for scrolling. 16832 16833@item focus regs 16834Make the register window active for scrolling. 16835 16836@item focus cmd 16837Make the command window active for scrolling. 16838 16839@item refresh 16840@kindex refresh 16841Refresh the screen. This is similar to typing @kbd{C-L}. 16842 16843@item tui reg float 16844@kindex tui reg 16845Show the floating point registers in the register window. 16846 16847@item tui reg general 16848Show the general registers in the register window. 16849 16850@item tui reg next 16851Show the next register group. The list of register groups as well as 16852their order is target specific. The predefined register groups are the 16853following: @code{general}, @code{float}, @code{system}, @code{vector}, 16854@code{all}, @code{save}, @code{restore}. 16855 16856@item tui reg system 16857Show the system registers in the register window. 16858 16859@item update 16860@kindex update 16861Update the source window and the current execution point. 16862 16863@item winheight @var{name} +@var{count} 16864@itemx winheight @var{name} -@var{count} 16865@kindex winheight 16866Change the height of the window @var{name} by @var{count} 16867lines. Positive counts increase the height, while negative counts 16868decrease it. 16869 16870@item tabset @var{nchars} 16871@kindex tabset 16872Set the width of tab stops to be @var{nchars} characters. 16873@end table 16874 16875@node TUI Configuration 16876@section TUI Configuration Variables 16877@cindex TUI configuration variables 16878 16879Several configuration variables control the appearance of TUI windows. 16880 16881@table @code 16882@item set tui border-kind @var{kind} 16883@kindex set tui border-kind 16884Select the border appearance for the source, assembly and register windows. 16885The possible values are the following: 16886@table @code 16887@item space 16888Use a space character to draw the border. 16889 16890@item ascii 16891Use @sc{ascii} characters @samp{+}, @samp{-} and @samp{|} to draw the border. 16892 16893@item acs 16894Use the Alternate Character Set to draw the border. The border is 16895drawn using character line graphics if the terminal supports them. 16896@end table 16897 16898@item set tui border-mode @var{mode} 16899@kindex set tui border-mode 16900@itemx set tui active-border-mode @var{mode} 16901@kindex set tui active-border-mode 16902Select the display attributes for the borders of the inactive windows 16903or the active window. The @var{mode} can be one of the following: 16904@table @code 16905@item normal 16906Use normal attributes to display the border. 16907 16908@item standout 16909Use standout mode. 16910 16911@item reverse 16912Use reverse video mode. 16913 16914@item half 16915Use half bright mode. 16916 16917@item half-standout 16918Use half bright and standout mode. 16919 16920@item bold 16921Use extra bright or bold mode. 16922 16923@item bold-standout 16924Use extra bright or bold and standout mode. 16925@end table 16926@end table 16927 16928@node Emacs 16929@chapter Using @value{GDBN} under @sc{gnu} Emacs 16930 16931@cindex Emacs 16932@cindex @sc{gnu} Emacs 16933A special interface allows you to use @sc{gnu} Emacs to view (and 16934edit) the source files for the program you are debugging with 16935@value{GDBN}. 16936 16937To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the 16938executable file you want to debug as an argument. This command starts 16939@value{GDBN} as a subprocess of Emacs, with input and output through a newly 16940created Emacs buffer. 16941@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.) 16942 16943Running @value{GDBN} under Emacs can be just like running @value{GDBN} normally except for two 16944things: 16945 16946@itemize @bullet 16947@item 16948All ``terminal'' input and output goes through an Emacs buffer, called 16949the GUD buffer. 16950 16951This applies both to @value{GDBN} commands and their output, and to the input 16952and output done by the program you are debugging. 16953 16954This is useful because it means that you can copy the text of previous 16955commands and input them again; you can even use parts of the output 16956in this way. 16957 16958All the facilities of Emacs' Shell mode are available for interacting 16959with your program. In particular, you can send signals the usual 16960way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a 16961stop. 16962 16963@item 16964@value{GDBN} displays source code through Emacs. 16965 16966Each time @value{GDBN} displays a stack frame, Emacs automatically finds the 16967source file for that frame and puts an arrow (@samp{=>}) at the 16968left margin of the current line. Emacs uses a separate buffer for 16969source display, and splits the screen to show both your @value{GDBN} session 16970and the source. 16971 16972Explicit @value{GDBN} @code{list} or search commands still produce output as 16973usual, but you probably have no reason to use them from Emacs. 16974@end itemize 16975 16976We call this @dfn{text command mode}. Emacs 22.1, and later, also uses 16977a graphical mode, enabled by default, which provides further buffers 16978that can control the execution and describe the state of your program. 16979@xref{GDB Graphical Interface,,, Emacs, The @sc{gnu} Emacs Manual}. 16980 16981If you specify an absolute file name when prompted for the @kbd{M-x 16982gdb} argument, then Emacs sets your current working directory to where 16983your program resides. If you only specify the file name, then Emacs 16984sets your current working directory to to the directory associated 16985with the previous buffer. In this case, @value{GDBN} may find your 16986program by searching your environment's @code{PATH} variable, but on 16987some operating systems it might not find the source. So, although the 16988@value{GDBN} input and output session proceeds normally, the auxiliary 16989buffer does not display the current source and line of execution. 16990 16991The initial working directory of @value{GDBN} is printed on the top 16992line of the GUD buffer and this serves as a default for the commands 16993that specify files for @value{GDBN} to operate on. @xref{Files, 16994,Commands to Specify Files}. 16995 16996By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you 16997need to call @value{GDBN} by a different name (for example, if you 16998keep several configurations around, with different names) you can 16999customize the Emacs variable @code{gud-gdb-command-name} to run the 17000one you want. 17001 17002In the GUD buffer, you can use these special Emacs commands in 17003addition to the standard Shell mode commands: 17004 17005@table @kbd 17006@item C-h m 17007Describe the features of Emacs' GUD Mode. 17008 17009@item C-c C-s 17010Execute to another source line, like the @value{GDBN} @code{step} command; also 17011update the display window to show the current file and location. 17012 17013@item C-c C-n 17014Execute to next source line in this function, skipping all function 17015calls, like the @value{GDBN} @code{next} command. Then update the display window 17016to show the current file and location. 17017 17018@item C-c C-i 17019Execute one instruction, like the @value{GDBN} @code{stepi} command; update 17020display window accordingly. 17021 17022@item C-c C-f 17023Execute until exit from the selected stack frame, like the @value{GDBN} 17024@code{finish} command. 17025 17026@item C-c C-r 17027Continue execution of your program, like the @value{GDBN} @code{continue} 17028command. 17029 17030@item C-c < 17031Go up the number of frames indicated by the numeric argument 17032(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}), 17033like the @value{GDBN} @code{up} command. 17034 17035@item C-c > 17036Go down the number of frames indicated by the numeric argument, like the 17037@value{GDBN} @code{down} command. 17038@end table 17039 17040In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break}) 17041tells @value{GDBN} to set a breakpoint on the source line point is on. 17042 17043In text command mode, if you type @kbd{M-x speedbar}, Emacs displays a 17044separate frame which shows a backtrace when the GUD buffer is current. 17045Move point to any frame in the stack and type @key{RET} to make it 17046become the current frame and display the associated source in the 17047source buffer. Alternatively, click @kbd{Mouse-2} to make the 17048selected frame become the current one. In graphical mode, the 17049speedbar displays watch expressions. 17050 17051If you accidentally delete the source-display buffer, an easy way to get 17052it back is to type the command @code{f} in the @value{GDBN} buffer, to 17053request a frame display; when you run under Emacs, this recreates 17054the source buffer if necessary to show you the context of the current 17055frame. 17056 17057The source files displayed in Emacs are in ordinary Emacs buffers 17058which are visiting the source files in the usual way. You can edit 17059the files with these buffers if you wish; but keep in mind that @value{GDBN} 17060communicates with Emacs in terms of line numbers. If you add or 17061delete lines from the text, the line numbers that @value{GDBN} knows cease 17062to correspond properly with the code. 17063 17064A more detailed description of Emacs' interaction with @value{GDBN} is 17065given in the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} 17066Emacs Manual}). 17067 17068@c The following dropped because Epoch is nonstandard. Reactivate 17069@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990 17070@ignore 17071@kindex Emacs Epoch environment 17072@kindex Epoch 17073@kindex inspect 17074 17075Version 18 of @sc{gnu} Emacs has a built-in window system 17076called the @code{epoch} 17077environment. Users of this environment can use a new command, 17078@code{inspect} which performs identically to @code{print} except that 17079each value is printed in its own window. 17080@end ignore 17081 17082 17083@node GDB/MI 17084@chapter The @sc{gdb/mi} Interface 17085 17086@unnumberedsec Function and Purpose 17087 17088@cindex @sc{gdb/mi}, its purpose 17089@sc{gdb/mi} is a line based machine oriented text interface to 17090@value{GDBN} and is activated by specifying using the 17091@option{--interpreter} command line option (@pxref{Mode Options}). It 17092is specifically intended to support the development of systems which 17093use the debugger as just one small component of a larger system. 17094 17095This chapter is a specification of the @sc{gdb/mi} interface. It is written 17096in the form of a reference manual. 17097 17098Note that @sc{gdb/mi} is still under construction, so some of the 17099features described below are incomplete and subject to change 17100(@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}). 17101 17102@unnumberedsec Notation and Terminology 17103 17104@cindex notational conventions, for @sc{gdb/mi} 17105This chapter uses the following notation: 17106 17107@itemize @bullet 17108@item 17109@code{|} separates two alternatives. 17110 17111@item 17112@code{[ @var{something} ]} indicates that @var{something} is optional: 17113it may or may not be given. 17114 17115@item 17116@code{( @var{group} )*} means that @var{group} inside the parentheses 17117may repeat zero or more times. 17118 17119@item 17120@code{( @var{group} )+} means that @var{group} inside the parentheses 17121may repeat one or more times. 17122 17123@item 17124@code{"@var{string}"} means a literal @var{string}. 17125@end itemize 17126 17127@ignore 17128@heading Dependencies 17129@end ignore 17130 17131@menu 17132* GDB/MI Command Syntax:: 17133* GDB/MI Compatibility with CLI:: 17134* GDB/MI Development and Front Ends:: 17135* GDB/MI Output Records:: 17136* GDB/MI Simple Examples:: 17137* GDB/MI Command Description Format:: 17138* GDB/MI Breakpoint Commands:: 17139* GDB/MI Program Context:: 17140* GDB/MI Thread Commands:: 17141* GDB/MI Program Execution:: 17142* GDB/MI Stack Manipulation:: 17143* GDB/MI Variable Objects:: 17144* GDB/MI Data Manipulation:: 17145* GDB/MI Tracepoint Commands:: 17146* GDB/MI Symbol Query:: 17147* GDB/MI File Commands:: 17148@ignore 17149* GDB/MI Kod Commands:: 17150* GDB/MI Memory Overlay Commands:: 17151* GDB/MI Signal Handling Commands:: 17152@end ignore 17153* GDB/MI Target Manipulation:: 17154* GDB/MI Miscellaneous Commands:: 17155@end menu 17156 17157@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 17158@node GDB/MI Command Syntax 17159@section @sc{gdb/mi} Command Syntax 17160 17161@menu 17162* GDB/MI Input Syntax:: 17163* GDB/MI Output Syntax:: 17164@end menu 17165 17166@node GDB/MI Input Syntax 17167@subsection @sc{gdb/mi} Input Syntax 17168 17169@cindex input syntax for @sc{gdb/mi} 17170@cindex @sc{gdb/mi}, input syntax 17171@table @code 17172@item @var{command} @expansion{} 17173@code{@var{cli-command} | @var{mi-command}} 17174 17175@item @var{cli-command} @expansion{} 17176@code{[ @var{token} ] @var{cli-command} @var{nl}}, where 17177@var{cli-command} is any existing @value{GDBN} CLI command. 17178 17179@item @var{mi-command} @expansion{} 17180@code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )* 17181@code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}} 17182 17183@item @var{token} @expansion{} 17184"any sequence of digits" 17185 17186@item @var{option} @expansion{} 17187@code{"-" @var{parameter} [ " " @var{parameter} ]} 17188 17189@item @var{parameter} @expansion{} 17190@code{@var{non-blank-sequence} | @var{c-string}} 17191 17192@item @var{operation} @expansion{} 17193@emph{any of the operations described in this chapter} 17194 17195@item @var{non-blank-sequence} @expansion{} 17196@emph{anything, provided it doesn't contain special characters such as 17197"-", @var{nl}, """ and of course " "} 17198 17199@item @var{c-string} @expansion{} 17200@code{""" @var{seven-bit-iso-c-string-content} """} 17201 17202@item @var{nl} @expansion{} 17203@code{CR | CR-LF} 17204@end table 17205 17206@noindent 17207Notes: 17208 17209@itemize @bullet 17210@item 17211The CLI commands are still handled by the @sc{mi} interpreter; their 17212output is described below. 17213 17214@item 17215The @code{@var{token}}, when present, is passed back when the command 17216finishes. 17217 17218@item 17219Some @sc{mi} commands accept optional arguments as part of the parameter 17220list. Each option is identified by a leading @samp{-} (dash) and may be 17221followed by an optional argument parameter. Options occur first in the 17222parameter list and can be delimited from normal parameters using 17223@samp{--} (this is useful when some parameters begin with a dash). 17224@end itemize 17225 17226Pragmatics: 17227 17228@itemize @bullet 17229@item 17230We want easy access to the existing CLI syntax (for debugging). 17231 17232@item 17233We want it to be easy to spot a @sc{mi} operation. 17234@end itemize 17235 17236@node GDB/MI Output Syntax 17237@subsection @sc{gdb/mi} Output Syntax 17238 17239@cindex output syntax of @sc{gdb/mi} 17240@cindex @sc{gdb/mi}, output syntax 17241The output from @sc{gdb/mi} consists of zero or more out-of-band records 17242followed, optionally, by a single result record. This result record 17243is for the most recent command. The sequence of output records is 17244terminated by @samp{(gdb)}. 17245 17246If an input command was prefixed with a @code{@var{token}} then the 17247corresponding output for that command will also be prefixed by that same 17248@var{token}. 17249 17250@table @code 17251@item @var{output} @expansion{} 17252@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}} 17253 17254@item @var{result-record} @expansion{} 17255@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}} 17256 17257@item @var{out-of-band-record} @expansion{} 17258@code{@var{async-record} | @var{stream-record}} 17259 17260@item @var{async-record} @expansion{} 17261@code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}} 17262 17263@item @var{exec-async-output} @expansion{} 17264@code{[ @var{token} ] "*" @var{async-output}} 17265 17266@item @var{status-async-output} @expansion{} 17267@code{[ @var{token} ] "+" @var{async-output}} 17268 17269@item @var{notify-async-output} @expansion{} 17270@code{[ @var{token} ] "=" @var{async-output}} 17271 17272@item @var{async-output} @expansion{} 17273@code{@var{async-class} ( "," @var{result} )* @var{nl}} 17274 17275@item @var{result-class} @expansion{} 17276@code{"done" | "running" | "connected" | "error" | "exit"} 17277 17278@item @var{async-class} @expansion{} 17279@code{"stopped" | @var{others}} (where @var{others} will be added 17280depending on the needs---this is still in development). 17281 17282@item @var{result} @expansion{} 17283@code{ @var{variable} "=" @var{value}} 17284 17285@item @var{variable} @expansion{} 17286@code{ @var{string} } 17287 17288@item @var{value} @expansion{} 17289@code{ @var{const} | @var{tuple} | @var{list} } 17290 17291@item @var{const} @expansion{} 17292@code{@var{c-string}} 17293 17294@item @var{tuple} @expansion{} 17295@code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" } 17296 17297@item @var{list} @expansion{} 17298@code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "[" 17299@var{result} ( "," @var{result} )* "]" } 17300 17301@item @var{stream-record} @expansion{} 17302@code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}} 17303 17304@item @var{console-stream-output} @expansion{} 17305@code{"~" @var{c-string}} 17306 17307@item @var{target-stream-output} @expansion{} 17308@code{"@@" @var{c-string}} 17309 17310@item @var{log-stream-output} @expansion{} 17311@code{"&" @var{c-string}} 17312 17313@item @var{nl} @expansion{} 17314@code{CR | CR-LF} 17315 17316@item @var{token} @expansion{} 17317@emph{any sequence of digits}. 17318@end table 17319 17320@noindent 17321Notes: 17322 17323@itemize @bullet 17324@item 17325All output sequences end in a single line containing a period. 17326 17327@item 17328The @code{@var{token}} is from the corresponding request. If an execution 17329command is interrupted by the @samp{-exec-interrupt} command, the 17330@var{token} associated with the @samp{*stopped} message is the one of the 17331original execution command, not the one of the interrupt command. 17332 17333@item 17334@cindex status output in @sc{gdb/mi} 17335@var{status-async-output} contains on-going status information about the 17336progress of a slow operation. It can be discarded. All status output is 17337prefixed by @samp{+}. 17338 17339@item 17340@cindex async output in @sc{gdb/mi} 17341@var{exec-async-output} contains asynchronous state change on the target 17342(stopped, started, disappeared). All async output is prefixed by 17343@samp{*}. 17344 17345@item 17346@cindex notify output in @sc{gdb/mi} 17347@var{notify-async-output} contains supplementary information that the 17348client should handle (e.g., a new breakpoint information). All notify 17349output is prefixed by @samp{=}. 17350 17351@item 17352@cindex console output in @sc{gdb/mi} 17353@var{console-stream-output} is output that should be displayed as is in the 17354console. It is the textual response to a CLI command. All the console 17355output is prefixed by @samp{~}. 17356 17357@item 17358@cindex target output in @sc{gdb/mi} 17359@var{target-stream-output} is the output produced by the target program. 17360All the target output is prefixed by @samp{@@}. 17361 17362@item 17363@cindex log output in @sc{gdb/mi} 17364@var{log-stream-output} is output text coming from @value{GDBN}'s internals, for 17365instance messages that should be displayed as part of an error log. All 17366the log output is prefixed by @samp{&}. 17367 17368@item 17369@cindex list output in @sc{gdb/mi} 17370New @sc{gdb/mi} commands should only output @var{lists} containing 17371@var{values}. 17372 17373 17374@end itemize 17375 17376@xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more 17377details about the various output records. 17378 17379@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 17380@node GDB/MI Compatibility with CLI 17381@section @sc{gdb/mi} Compatibility with CLI 17382 17383@cindex compatibility, @sc{gdb/mi} and CLI 17384@cindex @sc{gdb/mi}, compatibility with CLI 17385 17386For the developers convenience CLI commands can be entered directly, 17387but there may be some unexpected behaviour. For example, commands 17388that query the user will behave as if the user replied yes, breakpoint 17389command lists are not executed and some CLI commands, such as 17390@code{if}, @code{when} and @code{define}, prompt for further input with 17391@samp{>}, which is not valid MI output. 17392 17393This feature may be removed at some stage in the future and it is 17394recommended that front ends use the @code{-interpreter-exec} command 17395(@pxref{-interpreter-exec}). 17396 17397@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 17398@node GDB/MI Development and Front Ends 17399@section @sc{gdb/mi} Development and Front Ends 17400@cindex @sc{gdb/mi} development 17401 17402The application which takes the MI output and presents the state of the 17403program being debugged to the user is called a @dfn{front end}. 17404 17405Although @sc{gdb/mi} is still incomplete, it is currently being used 17406by a variety of front ends to @value{GDBN}. This makes it difficult 17407to introduce new functionality without breaking existing usage. This 17408section tries to minimize the problems by describing how the protocol 17409might change. 17410 17411Some changes in MI need not break a carefully designed front end, and 17412for these the MI version will remain unchanged. The following is a 17413list of changes that may occur within one level, so front ends should 17414parse MI output in a way that can handle them: 17415 17416@itemize @bullet 17417@item 17418New MI commands may be added. 17419 17420@item 17421New fields may be added to the output of any MI command. 17422 17423@item 17424The range of values for fields with specified values, e.g., 17425@code{in_scope} (@pxref{-var-update}) may be extended. 17426 17427@c The format of field's content e.g type prefix, may change so parse it 17428@c at your own risk. Yes, in general? 17429 17430@c The order of fields may change? Shouldn't really matter but it might 17431@c resolve inconsistencies. 17432@end itemize 17433 17434If the changes are likely to break front ends, the MI version level 17435will be increased by one. This will allow the front end to parse the 17436output according to the MI version. Apart from mi0, new versions of 17437@value{GDBN} will not support old versions of MI and it will be the 17438responsibility of the front end to work with the new one. 17439 17440@c Starting with mi3, add a new command -mi-version that prints the MI 17441@c version? 17442 17443The best way to avoid unexpected changes in MI that might break your front 17444end is to make your project known to @value{GDBN} developers and 17445follow development on @email{gdb@@sourceware.org} and 17446@email{gdb-patches@@sourceware.org}. There is also the mailing list 17447@email{dmi-discuss@@lists.freestandards.org}, hosted by the Free Standards 17448Group, which has the aim of creating a more general MI protocol 17449called Debugger Machine Interface (DMI) that will become a standard 17450for all debuggers, not just @value{GDBN}. 17451@cindex mailing lists 17452 17453@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 17454@node GDB/MI Output Records 17455@section @sc{gdb/mi} Output Records 17456 17457@menu 17458* GDB/MI Result Records:: 17459* GDB/MI Stream Records:: 17460* GDB/MI Out-of-band Records:: 17461@end menu 17462 17463@node GDB/MI Result Records 17464@subsection @sc{gdb/mi} Result Records 17465 17466@cindex result records in @sc{gdb/mi} 17467@cindex @sc{gdb/mi}, result records 17468In addition to a number of out-of-band notifications, the response to a 17469@sc{gdb/mi} command includes one of the following result indications: 17470 17471@table @code 17472@findex ^done 17473@item "^done" [ "," @var{results} ] 17474The synchronous operation was successful, @code{@var{results}} are the return 17475values. 17476 17477@item "^running" 17478@findex ^running 17479@c Is this one correct? Should it be an out-of-band notification? 17480The asynchronous operation was successfully started. The target is 17481running. 17482 17483@item "^connected" 17484@findex ^connected 17485@value{GDBN} has connected to a remote target. 17486 17487@item "^error" "," @var{c-string} 17488@findex ^error 17489The operation failed. The @code{@var{c-string}} contains the corresponding 17490error message. 17491 17492@item "^exit" 17493@findex ^exit 17494@value{GDBN} has terminated. 17495 17496@end table 17497 17498@node GDB/MI Stream Records 17499@subsection @sc{gdb/mi} Stream Records 17500 17501@cindex @sc{gdb/mi}, stream records 17502@cindex stream records in @sc{gdb/mi} 17503@value{GDBN} internally maintains a number of output streams: the console, the 17504target, and the log. The output intended for each of these streams is 17505funneled through the @sc{gdb/mi} interface using @dfn{stream records}. 17506 17507Each stream record begins with a unique @dfn{prefix character} which 17508identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output 17509Syntax}). In addition to the prefix, each stream record contains a 17510@code{@var{string-output}}. This is either raw text (with an implicit new 17511line) or a quoted C string (which does not contain an implicit newline). 17512 17513@table @code 17514@item "~" @var{string-output} 17515The console output stream contains text that should be displayed in the 17516CLI console window. It contains the textual responses to CLI commands. 17517 17518@item "@@" @var{string-output} 17519The target output stream contains any textual output from the running 17520target. This is only present when GDB's event loop is truly 17521asynchronous, which is currently only the case for remote targets. 17522 17523@item "&" @var{string-output} 17524The log stream contains debugging messages being produced by @value{GDBN}'s 17525internals. 17526@end table 17527 17528@node GDB/MI Out-of-band Records 17529@subsection @sc{gdb/mi} Out-of-band Records 17530 17531@cindex out-of-band records in @sc{gdb/mi} 17532@cindex @sc{gdb/mi}, out-of-band records 17533@dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of 17534additional changes that have occurred. Those changes can either be a 17535consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of 17536target activity (e.g., target stopped). 17537 17538The following is a preliminary list of possible out-of-band records. 17539In particular, the @var{exec-async-output} records. 17540 17541@table @code 17542@item *stopped,reason="@var{reason}" 17543@end table 17544 17545@var{reason} can be one of the following: 17546 17547@table @code 17548@item breakpoint-hit 17549A breakpoint was reached. 17550@item watchpoint-trigger 17551A watchpoint was triggered. 17552@item read-watchpoint-trigger 17553A read watchpoint was triggered. 17554@item access-watchpoint-trigger 17555An access watchpoint was triggered. 17556@item function-finished 17557An -exec-finish or similar CLI command was accomplished. 17558@item location-reached 17559An -exec-until or similar CLI command was accomplished. 17560@item watchpoint-scope 17561A watchpoint has gone out of scope. 17562@item end-stepping-range 17563An -exec-next, -exec-next-instruction, -exec-step, -exec-step-instruction or 17564similar CLI command was accomplished. 17565@item exited-signalled 17566The inferior exited because of a signal. 17567@item exited 17568The inferior exited. 17569@item exited-normally 17570The inferior exited normally. 17571@item signal-received 17572A signal was received by the inferior. 17573@end table 17574 17575 17576@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 17577@node GDB/MI Simple Examples 17578@section Simple Examples of @sc{gdb/mi} Interaction 17579@cindex @sc{gdb/mi}, simple examples 17580 17581This subsection presents several simple examples of interaction using 17582the @sc{gdb/mi} interface. In these examples, @samp{->} means that the 17583following line is passed to @sc{gdb/mi} as input, while @samp{<-} means 17584the output received from @sc{gdb/mi}. 17585 17586Note the line breaks shown in the examples are here only for 17587readability, they don't appear in the real output. 17588 17589@subheading Setting a Breakpoint 17590 17591Setting a breakpoint generates synchronous output which contains detailed 17592information of the breakpoint. 17593 17594@smallexample 17595-> -break-insert main 17596<- ^done,bkpt=@{number="1",type="breakpoint",disp="keep", 17597 enabled="y",addr="0x08048564",func="main",file="myprog.c", 17598 fullname="/home/nickrob/myprog.c",line="68",times="0"@} 17599<- (gdb) 17600@end smallexample 17601 17602@subheading Program Execution 17603 17604Program execution generates asynchronous records and MI gives the 17605reason that execution stopped. 17606 17607@smallexample 17608-> -exec-run 17609<- ^running 17610<- (gdb) 17611<- *stopped,reason="breakpoint-hit",bkptno="1",thread-id="0", 17612 frame=@{addr="0x08048564",func="main", 17613 args=[@{name="argc",value="1"@},@{name="argv",value="0xbfc4d4d4"@}], 17614 file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"@} 17615<- (gdb) 17616-> -exec-continue 17617<- ^running 17618<- (gdb) 17619<- *stopped,reason="exited-normally" 17620<- (gdb) 17621@end smallexample 17622 17623@subheading Quitting @value{GDBN} 17624 17625Quitting @value{GDBN} just prints the result class @samp{^exit}. 17626 17627@smallexample 17628-> (gdb) 17629<- -gdb-exit 17630<- ^exit 17631@end smallexample 17632 17633@subheading A Bad Command 17634 17635Here's what happens if you pass a non-existent command: 17636 17637@smallexample 17638-> -rubbish 17639<- ^error,msg="Undefined MI command: rubbish" 17640<- (gdb) 17641@end smallexample 17642 17643 17644@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 17645@node GDB/MI Command Description Format 17646@section @sc{gdb/mi} Command Description Format 17647 17648The remaining sections describe blocks of commands. Each block of 17649commands is laid out in a fashion similar to this section. 17650 17651@subheading Motivation 17652 17653The motivation for this collection of commands. 17654 17655@subheading Introduction 17656 17657A brief introduction to this collection of commands as a whole. 17658 17659@subheading Commands 17660 17661For each command in the block, the following is described: 17662 17663@subsubheading Synopsis 17664 17665@smallexample 17666 -command @var{args}@dots{} 17667@end smallexample 17668 17669@subsubheading Result 17670 17671@subsubheading @value{GDBN} Command 17672 17673The corresponding @value{GDBN} CLI command(s), if any. 17674 17675@subsubheading Example 17676 17677Example(s) formatted for readability. Some of the described commands have 17678not been implemented yet and these are labeled N.A.@: (not available). 17679 17680 17681@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 17682@node GDB/MI Breakpoint Commands 17683@section @sc{gdb/mi} Breakpoint Commands 17684 17685@cindex breakpoint commands for @sc{gdb/mi} 17686@cindex @sc{gdb/mi}, breakpoint commands 17687This section documents @sc{gdb/mi} commands for manipulating 17688breakpoints. 17689 17690@subheading The @code{-break-after} Command 17691@findex -break-after 17692 17693@subsubheading Synopsis 17694 17695@smallexample 17696 -break-after @var{number} @var{count} 17697@end smallexample 17698 17699The breakpoint number @var{number} is not in effect until it has been 17700hit @var{count} times. To see how this is reflected in the output of 17701the @samp{-break-list} command, see the description of the 17702@samp{-break-list} command below. 17703 17704@subsubheading @value{GDBN} Command 17705 17706The corresponding @value{GDBN} command is @samp{ignore}. 17707 17708@subsubheading Example 17709 17710@smallexample 17711(gdb) 17712-break-insert main 17713^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c", 17714fullname="/home/foo/hello.c",line="5",times="0"@} 17715(gdb) 17716-break-after 1 3 17717~ 17718^done 17719(gdb) 17720-break-list 17721^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 17722hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 17723@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 17724@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 17725@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 17726@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 17727@{width="40",alignment="2",col_name="what",colhdr="What"@}], 17728body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 17729addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 17730line="5",times="0",ignore="3"@}]@} 17731(gdb) 17732@end smallexample 17733 17734@ignore 17735@subheading The @code{-break-catch} Command 17736@findex -break-catch 17737 17738@subheading The @code{-break-commands} Command 17739@findex -break-commands 17740@end ignore 17741 17742 17743@subheading The @code{-break-condition} Command 17744@findex -break-condition 17745 17746@subsubheading Synopsis 17747 17748@smallexample 17749 -break-condition @var{number} @var{expr} 17750@end smallexample 17751 17752Breakpoint @var{number} will stop the program only if the condition in 17753@var{expr} is true. The condition becomes part of the 17754@samp{-break-list} output (see the description of the @samp{-break-list} 17755command below). 17756 17757@subsubheading @value{GDBN} Command 17758 17759The corresponding @value{GDBN} command is @samp{condition}. 17760 17761@subsubheading Example 17762 17763@smallexample 17764(gdb) 17765-break-condition 1 1 17766^done 17767(gdb) 17768-break-list 17769^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 17770hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 17771@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 17772@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 17773@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 17774@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 17775@{width="40",alignment="2",col_name="what",colhdr="What"@}], 17776body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 17777addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 17778line="5",cond="1",times="0",ignore="3"@}]@} 17779(gdb) 17780@end smallexample 17781 17782@subheading The @code{-break-delete} Command 17783@findex -break-delete 17784 17785@subsubheading Synopsis 17786 17787@smallexample 17788 -break-delete ( @var{breakpoint} )+ 17789@end smallexample 17790 17791Delete the breakpoint(s) whose number(s) are specified in the argument 17792list. This is obviously reflected in the breakpoint list. 17793 17794@subsubheading @value{GDBN} Command 17795 17796The corresponding @value{GDBN} command is @samp{delete}. 17797 17798@subsubheading Example 17799 17800@smallexample 17801(gdb) 17802-break-delete 1 17803^done 17804(gdb) 17805-break-list 17806^done,BreakpointTable=@{nr_rows="0",nr_cols="6", 17807hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 17808@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 17809@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 17810@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 17811@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 17812@{width="40",alignment="2",col_name="what",colhdr="What"@}], 17813body=[]@} 17814(gdb) 17815@end smallexample 17816 17817@subheading The @code{-break-disable} Command 17818@findex -break-disable 17819 17820@subsubheading Synopsis 17821 17822@smallexample 17823 -break-disable ( @var{breakpoint} )+ 17824@end smallexample 17825 17826Disable the named @var{breakpoint}(s). The field @samp{enabled} in the 17827break list is now set to @samp{n} for the named @var{breakpoint}(s). 17828 17829@subsubheading @value{GDBN} Command 17830 17831The corresponding @value{GDBN} command is @samp{disable}. 17832 17833@subsubheading Example 17834 17835@smallexample 17836(gdb) 17837-break-disable 2 17838^done 17839(gdb) 17840-break-list 17841^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 17842hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 17843@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 17844@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 17845@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 17846@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 17847@{width="40",alignment="2",col_name="what",colhdr="What"@}], 17848body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n", 17849addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 17850line="5",times="0"@}]@} 17851(gdb) 17852@end smallexample 17853 17854@subheading The @code{-break-enable} Command 17855@findex -break-enable 17856 17857@subsubheading Synopsis 17858 17859@smallexample 17860 -break-enable ( @var{breakpoint} )+ 17861@end smallexample 17862 17863Enable (previously disabled) @var{breakpoint}(s). 17864 17865@subsubheading @value{GDBN} Command 17866 17867The corresponding @value{GDBN} command is @samp{enable}. 17868 17869@subsubheading Example 17870 17871@smallexample 17872(gdb) 17873-break-enable 2 17874^done 17875(gdb) 17876-break-list 17877^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 17878hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 17879@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 17880@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 17881@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 17882@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 17883@{width="40",alignment="2",col_name="what",colhdr="What"@}], 17884body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", 17885addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 17886line="5",times="0"@}]@} 17887(gdb) 17888@end smallexample 17889 17890@subheading The @code{-break-info} Command 17891@findex -break-info 17892 17893@subsubheading Synopsis 17894 17895@smallexample 17896 -break-info @var{breakpoint} 17897@end smallexample 17898 17899@c REDUNDANT??? 17900Get information about a single breakpoint. 17901 17902@subsubheading @value{GDBN} Command 17903 17904The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}. 17905 17906@subsubheading Example 17907N.A. 17908 17909@subheading The @code{-break-insert} Command 17910@findex -break-insert 17911 17912@subsubheading Synopsis 17913 17914@smallexample 17915 -break-insert [ -t ] [ -h ] [ -r ] 17916 [ -c @var{condition} ] [ -i @var{ignore-count} ] 17917 [ -p @var{thread} ] [ @var{line} | @var{addr} ] 17918@end smallexample 17919 17920@noindent 17921If specified, @var{line}, can be one of: 17922 17923@itemize @bullet 17924@item function 17925@c @item +offset 17926@c @item -offset 17927@c @item linenum 17928@item filename:linenum 17929@item filename:function 17930@item *address 17931@end itemize 17932 17933The possible optional parameters of this command are: 17934 17935@table @samp 17936@item -t 17937Insert a temporary breakpoint. 17938@item -h 17939Insert a hardware breakpoint. 17940@item -c @var{condition} 17941Make the breakpoint conditional on @var{condition}. 17942@item -i @var{ignore-count} 17943Initialize the @var{ignore-count}. 17944@item -r 17945Insert a regular breakpoint in all the functions whose names match the 17946given regular expression. Other flags are not applicable to regular 17947expressions. 17948@end table 17949 17950@subsubheading Result 17951 17952The result is in the form: 17953 17954@smallexample 17955^done,bkpt=@{number="@var{number}",type="@var{type}",disp="del"|"keep", 17956enabled="y"|"n",addr="@var{hex}",func="@var{funcname}",file="@var{filename}", 17957fullname="@var{full_filename}",line="@var{lineno}",[thread="@var{threadno},] 17958times="@var{times}"@} 17959@end smallexample 17960 17961@noindent 17962where @var{number} is the @value{GDBN} number for this breakpoint, 17963@var{funcname} is the name of the function where the breakpoint was 17964inserted, @var{filename} is the name of the source file which contains 17965this function, @var{lineno} is the source line number within that file 17966and @var{times} the number of times that the breakpoint has been hit 17967(always 0 for -break-insert but may be greater for -break-info or -break-list 17968which use the same output). 17969 17970Note: this format is open to change. 17971@c An out-of-band breakpoint instead of part of the result? 17972 17973@subsubheading @value{GDBN} Command 17974 17975The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak}, 17976@samp{hbreak}, @samp{thbreak}, and @samp{rbreak}. 17977 17978@subsubheading Example 17979 17980@smallexample 17981(gdb) 17982-break-insert main 17983^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c", 17984fullname="/home/foo/recursive2.c,line="4",times="0"@} 17985(gdb) 17986-break-insert -t foo 17987^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c", 17988fullname="/home/foo/recursive2.c,line="11",times="0"@} 17989(gdb) 17990-break-list 17991^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 17992hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 17993@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 17994@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 17995@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 17996@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 17997@{width="40",alignment="2",col_name="what",colhdr="What"@}], 17998body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 17999addr="0x0001072c", func="main",file="recursive2.c", 18000fullname="/home/foo/recursive2.c,"line="4",times="0"@}, 18001bkpt=@{number="2",type="breakpoint",disp="del",enabled="y", 18002addr="0x00010774",func="foo",file="recursive2.c", 18003fullname="/home/foo/recursive2.c",line="11",times="0"@}]@} 18004(gdb) 18005-break-insert -r foo.* 18006~int foo(int, int); 18007^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c, 18008"fullname="/home/foo/recursive2.c",line="11",times="0"@} 18009(gdb) 18010@end smallexample 18011 18012@subheading The @code{-break-list} Command 18013@findex -break-list 18014 18015@subsubheading Synopsis 18016 18017@smallexample 18018 -break-list 18019@end smallexample 18020 18021Displays the list of inserted breakpoints, showing the following fields: 18022 18023@table @samp 18024@item Number 18025number of the breakpoint 18026@item Type 18027type of the breakpoint: @samp{breakpoint} or @samp{watchpoint} 18028@item Disposition 18029should the breakpoint be deleted or disabled when it is hit: @samp{keep} 18030or @samp{nokeep} 18031@item Enabled 18032is the breakpoint enabled or no: @samp{y} or @samp{n} 18033@item Address 18034memory location at which the breakpoint is set 18035@item What 18036logical location of the breakpoint, expressed by function name, file 18037name, line number 18038@item Times 18039number of times the breakpoint has been hit 18040@end table 18041 18042If there are no breakpoints or watchpoints, the @code{BreakpointTable} 18043@code{body} field is an empty list. 18044 18045@subsubheading @value{GDBN} Command 18046 18047The corresponding @value{GDBN} command is @samp{info break}. 18048 18049@subsubheading Example 18050 18051@smallexample 18052(gdb) 18053-break-list 18054^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 18055hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 18056@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 18057@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 18058@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 18059@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 18060@{width="40",alignment="2",col_name="what",colhdr="What"@}], 18061body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 18062addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}, 18063bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", 18064addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c", 18065line="13",times="0"@}]@} 18066(gdb) 18067@end smallexample 18068 18069Here's an example of the result when there are no breakpoints: 18070 18071@smallexample 18072(gdb) 18073-break-list 18074^done,BreakpointTable=@{nr_rows="0",nr_cols="6", 18075hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 18076@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 18077@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 18078@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 18079@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 18080@{width="40",alignment="2",col_name="what",colhdr="What"@}], 18081body=[]@} 18082(gdb) 18083@end smallexample 18084 18085@subheading The @code{-break-watch} Command 18086@findex -break-watch 18087 18088@subsubheading Synopsis 18089 18090@smallexample 18091 -break-watch [ -a | -r ] 18092@end smallexample 18093 18094Create a watchpoint. With the @samp{-a} option it will create an 18095@dfn{access} watchpoint, i.e., a watchpoint that triggers either on a 18096read from or on a write to the memory location. With the @samp{-r} 18097option, the watchpoint created is a @dfn{read} watchpoint, i.e., it will 18098trigger only when the memory location is accessed for reading. Without 18099either of the options, the watchpoint created is a regular watchpoint, 18100i.e., it will trigger when the memory location is accessed for writing. 18101@xref{Set Watchpoints, , Setting Watchpoints}. 18102 18103Note that @samp{-break-list} will report a single list of watchpoints and 18104breakpoints inserted. 18105 18106@subsubheading @value{GDBN} Command 18107 18108The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and 18109@samp{rwatch}. 18110 18111@subsubheading Example 18112 18113Setting a watchpoint on a variable in the @code{main} function: 18114 18115@smallexample 18116(gdb) 18117-break-watch x 18118^done,wpt=@{number="2",exp="x"@} 18119(gdb) 18120-exec-continue 18121^running 18122(gdb) 18123*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@}, 18124value=@{old="-268439212",new="55"@}, 18125frame=@{func="main",args=[],file="recursive2.c", 18126fullname="/home/foo/bar/recursive2.c",line="5"@} 18127(gdb) 18128@end smallexample 18129 18130Setting a watchpoint on a variable local to a function. @value{GDBN} will stop 18131the program execution twice: first for the variable changing value, then 18132for the watchpoint going out of scope. 18133 18134@smallexample 18135(gdb) 18136-break-watch C 18137^done,wpt=@{number="5",exp="C"@} 18138(gdb) 18139-exec-continue 18140^running 18141(gdb) 18142*stopped,reason="watchpoint-trigger", 18143wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@}, 18144frame=@{func="callee4",args=[], 18145file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 18146fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@} 18147(gdb) 18148-exec-continue 18149^running 18150(gdb) 18151*stopped,reason="watchpoint-scope",wpnum="5", 18152frame=@{func="callee3",args=[@{name="strarg", 18153value="0x11940 \"A string argument.\""@}], 18154file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 18155fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} 18156(gdb) 18157@end smallexample 18158 18159Listing breakpoints and watchpoints, at different points in the program 18160execution. Note that once the watchpoint goes out of scope, it is 18161deleted. 18162 18163@smallexample 18164(gdb) 18165-break-watch C 18166^done,wpt=@{number="2",exp="C"@} 18167(gdb) 18168-break-list 18169^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 18170hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 18171@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 18172@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 18173@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 18174@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 18175@{width="40",alignment="2",col_name="what",colhdr="What"@}], 18176body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 18177addr="0x00010734",func="callee4", 18178file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 18179fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"@}, 18180bkpt=@{number="2",type="watchpoint",disp="keep", 18181enabled="y",addr="",what="C",times="0"@}]@} 18182(gdb) 18183-exec-continue 18184^running 18185(gdb) 18186*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@}, 18187value=@{old="-276895068",new="3"@}, 18188frame=@{func="callee4",args=[], 18189file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 18190fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@} 18191(gdb) 18192-break-list 18193^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 18194hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 18195@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 18196@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 18197@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 18198@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 18199@{width="40",alignment="2",col_name="what",colhdr="What"@}], 18200body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 18201addr="0x00010734",func="callee4", 18202file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 18203fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}, 18204bkpt=@{number="2",type="watchpoint",disp="keep", 18205enabled="y",addr="",what="C",times="-5"@}]@} 18206(gdb) 18207-exec-continue 18208^running 18209^done,reason="watchpoint-scope",wpnum="2", 18210frame=@{func="callee3",args=[@{name="strarg", 18211value="0x11940 \"A string argument.\""@}], 18212file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 18213fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} 18214(gdb) 18215-break-list 18216^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 18217hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 18218@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 18219@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 18220@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 18221@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 18222@{width="40",alignment="2",col_name="what",colhdr="What"@}], 18223body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 18224addr="0x00010734",func="callee4", 18225file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 18226fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8", 18227times="1"@}]@} 18228(gdb) 18229@end smallexample 18230 18231@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 18232@node GDB/MI Program Context 18233@section @sc{gdb/mi} Program Context 18234 18235@subheading The @code{-exec-arguments} Command 18236@findex -exec-arguments 18237 18238 18239@subsubheading Synopsis 18240 18241@smallexample 18242 -exec-arguments @var{args} 18243@end smallexample 18244 18245Set the inferior program arguments, to be used in the next 18246@samp{-exec-run}. 18247 18248@subsubheading @value{GDBN} Command 18249 18250The corresponding @value{GDBN} command is @samp{set args}. 18251 18252@subsubheading Example 18253 18254@c FIXME! 18255Don't have one around. 18256 18257 18258@subheading The @code{-exec-show-arguments} Command 18259@findex -exec-show-arguments 18260 18261@subsubheading Synopsis 18262 18263@smallexample 18264 -exec-show-arguments 18265@end smallexample 18266 18267Print the arguments of the program. 18268 18269@subsubheading @value{GDBN} Command 18270 18271The corresponding @value{GDBN} command is @samp{show args}. 18272 18273@subsubheading Example 18274N.A. 18275 18276 18277@subheading The @code{-environment-cd} Command 18278@findex -environment-cd 18279 18280@subsubheading Synopsis 18281 18282@smallexample 18283 -environment-cd @var{pathdir} 18284@end smallexample 18285 18286Set @value{GDBN}'s working directory. 18287 18288@subsubheading @value{GDBN} Command 18289 18290The corresponding @value{GDBN} command is @samp{cd}. 18291 18292@subsubheading Example 18293 18294@smallexample 18295(gdb) 18296-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb 18297^done 18298(gdb) 18299@end smallexample 18300 18301 18302@subheading The @code{-environment-directory} Command 18303@findex -environment-directory 18304 18305@subsubheading Synopsis 18306 18307@smallexample 18308 -environment-directory [ -r ] [ @var{pathdir} ]+ 18309@end smallexample 18310 18311Add directories @var{pathdir} to beginning of search path for source files. 18312If the @samp{-r} option is used, the search path is reset to the default 18313search path. If directories @var{pathdir} are supplied in addition to the 18314@samp{-r} option, the search path is first reset and then addition 18315occurs as normal. 18316Multiple directories may be specified, separated by blanks. Specifying 18317multiple directories in a single command 18318results in the directories added to the beginning of the 18319search path in the same order they were presented in the command. 18320If blanks are needed as 18321part of a directory name, double-quotes should be used around 18322the name. In the command output, the path will show up separated 18323by the system directory-separator character. The directory-separator 18324character must not be used 18325in any directory name. 18326If no directories are specified, the current search path is displayed. 18327 18328@subsubheading @value{GDBN} Command 18329 18330The corresponding @value{GDBN} command is @samp{dir}. 18331 18332@subsubheading Example 18333 18334@smallexample 18335(gdb) 18336-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb 18337^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" 18338(gdb) 18339-environment-directory "" 18340^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" 18341(gdb) 18342-environment-directory -r /home/jjohnstn/src/gdb /usr/src 18343^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" 18344(gdb) 18345-environment-directory -r 18346^done,source-path="$cdir:$cwd" 18347(gdb) 18348@end smallexample 18349 18350 18351@subheading The @code{-environment-path} Command 18352@findex -environment-path 18353 18354@subsubheading Synopsis 18355 18356@smallexample 18357 -environment-path [ -r ] [ @var{pathdir} ]+ 18358@end smallexample 18359 18360Add directories @var{pathdir} to beginning of search path for object files. 18361If the @samp{-r} option is used, the search path is reset to the original 18362search path that existed at gdb start-up. If directories @var{pathdir} are 18363supplied in addition to the 18364@samp{-r} option, the search path is first reset and then addition 18365occurs as normal. 18366Multiple directories may be specified, separated by blanks. Specifying 18367multiple directories in a single command 18368results in the directories added to the beginning of the 18369search path in the same order they were presented in the command. 18370If blanks are needed as 18371part of a directory name, double-quotes should be used around 18372the name. In the command output, the path will show up separated 18373by the system directory-separator character. The directory-separator 18374character must not be used 18375in any directory name. 18376If no directories are specified, the current path is displayed. 18377 18378 18379@subsubheading @value{GDBN} Command 18380 18381The corresponding @value{GDBN} command is @samp{path}. 18382 18383@subsubheading Example 18384 18385@smallexample 18386(gdb) 18387-environment-path 18388^done,path="/usr/bin" 18389(gdb) 18390-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin 18391^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" 18392(gdb) 18393-environment-path -r /usr/local/bin 18394^done,path="/usr/local/bin:/usr/bin" 18395(gdb) 18396@end smallexample 18397 18398 18399@subheading The @code{-environment-pwd} Command 18400@findex -environment-pwd 18401 18402@subsubheading Synopsis 18403 18404@smallexample 18405 -environment-pwd 18406@end smallexample 18407 18408Show the current working directory. 18409 18410@subsubheading @value{GDBN} Command 18411 18412The corresponding @value{GDBN} command is @samp{pwd}. 18413 18414@subsubheading Example 18415 18416@smallexample 18417(gdb) 18418-environment-pwd 18419^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" 18420(gdb) 18421@end smallexample 18422 18423@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 18424@node GDB/MI Thread Commands 18425@section @sc{gdb/mi} Thread Commands 18426 18427 18428@subheading The @code{-thread-info} Command 18429@findex -thread-info 18430 18431@subsubheading Synopsis 18432 18433@smallexample 18434 -thread-info 18435@end smallexample 18436 18437@subsubheading @value{GDBN} Command 18438 18439No equivalent. 18440 18441@subsubheading Example 18442N.A. 18443 18444 18445@subheading The @code{-thread-list-all-threads} Command 18446@findex -thread-list-all-threads 18447 18448@subsubheading Synopsis 18449 18450@smallexample 18451 -thread-list-all-threads 18452@end smallexample 18453 18454@subsubheading @value{GDBN} Command 18455 18456The equivalent @value{GDBN} command is @samp{info threads}. 18457 18458@subsubheading Example 18459N.A. 18460 18461 18462@subheading The @code{-thread-list-ids} Command 18463@findex -thread-list-ids 18464 18465@subsubheading Synopsis 18466 18467@smallexample 18468 -thread-list-ids 18469@end smallexample 18470 18471Produces a list of the currently known @value{GDBN} thread ids. At the 18472end of the list it also prints the total number of such threads. 18473 18474@subsubheading @value{GDBN} Command 18475 18476Part of @samp{info threads} supplies the same information. 18477 18478@subsubheading Example 18479 18480No threads present, besides the main process: 18481 18482@smallexample 18483(gdb) 18484-thread-list-ids 18485^done,thread-ids=@{@},number-of-threads="0" 18486(gdb) 18487@end smallexample 18488 18489 18490Several threads: 18491 18492@smallexample 18493(gdb) 18494-thread-list-ids 18495^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, 18496number-of-threads="3" 18497(gdb) 18498@end smallexample 18499 18500 18501@subheading The @code{-thread-select} Command 18502@findex -thread-select 18503 18504@subsubheading Synopsis 18505 18506@smallexample 18507 -thread-select @var{threadnum} 18508@end smallexample 18509 18510Make @var{threadnum} the current thread. It prints the number of the new 18511current thread, and the topmost frame for that thread. 18512 18513@subsubheading @value{GDBN} Command 18514 18515The corresponding @value{GDBN} command is @samp{thread}. 18516 18517@subsubheading Example 18518 18519@smallexample 18520(gdb) 18521-exec-next 18522^running 18523(gdb) 18524*stopped,reason="end-stepping-range",thread-id="2",line="187", 18525file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" 18526(gdb) 18527-thread-list-ids 18528^done, 18529thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, 18530number-of-threads="3" 18531(gdb) 18532-thread-select 3 18533^done,new-thread-id="3", 18534frame=@{level="0",func="vprintf", 18535args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@}, 18536@{name="arg",value="0x2"@}],file="vprintf.c",line="31"@} 18537(gdb) 18538@end smallexample 18539 18540@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 18541@node GDB/MI Program Execution 18542@section @sc{gdb/mi} Program Execution 18543 18544These are the asynchronous commands which generate the out-of-band 18545record @samp{*stopped}. Currently @value{GDBN} only really executes 18546asynchronously with remote targets and this interaction is mimicked in 18547other cases. 18548 18549@subheading The @code{-exec-continue} Command 18550@findex -exec-continue 18551 18552@subsubheading Synopsis 18553 18554@smallexample 18555 -exec-continue 18556@end smallexample 18557 18558Resumes the execution of the inferior program until a breakpoint is 18559encountered, or until the inferior exits. 18560 18561@subsubheading @value{GDBN} Command 18562 18563The corresponding @value{GDBN} corresponding is @samp{continue}. 18564 18565@subsubheading Example 18566 18567@smallexample 18568-exec-continue 18569^running 18570(gdb) 18571@@Hello world 18572*stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[], 18573file="hello.c",fullname="/home/foo/bar/hello.c",line="13"@} 18574(gdb) 18575@end smallexample 18576 18577 18578@subheading The @code{-exec-finish} Command 18579@findex -exec-finish 18580 18581@subsubheading Synopsis 18582 18583@smallexample 18584 -exec-finish 18585@end smallexample 18586 18587Resumes the execution of the inferior program until the current 18588function is exited. Displays the results returned by the function. 18589 18590@subsubheading @value{GDBN} Command 18591 18592The corresponding @value{GDBN} command is @samp{finish}. 18593 18594@subsubheading Example 18595 18596Function returning @code{void}. 18597 18598@smallexample 18599-exec-finish 18600^running 18601(gdb) 18602@@hello from foo 18603*stopped,reason="function-finished",frame=@{func="main",args=[], 18604file="hello.c",fullname="/home/foo/bar/hello.c",line="7"@} 18605(gdb) 18606@end smallexample 18607 18608Function returning other than @code{void}. The name of the internal 18609@value{GDBN} variable storing the result is printed, together with the 18610value itself. 18611 18612@smallexample 18613-exec-finish 18614^running 18615(gdb) 18616*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo", 18617args=[@{name="a",value="1"],@{name="b",value="9"@}@}, 18618file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 18619gdb-result-var="$1",return-value="0" 18620(gdb) 18621@end smallexample 18622 18623 18624@subheading The @code{-exec-interrupt} Command 18625@findex -exec-interrupt 18626 18627@subsubheading Synopsis 18628 18629@smallexample 18630 -exec-interrupt 18631@end smallexample 18632 18633Interrupts the background execution of the target. Note how the token 18634associated with the stop message is the one for the execution command 18635that has been interrupted. The token for the interrupt itself only 18636appears in the @samp{^done} output. If the user is trying to 18637interrupt a non-running program, an error message will be printed. 18638 18639@subsubheading @value{GDBN} Command 18640 18641The corresponding @value{GDBN} command is @samp{interrupt}. 18642 18643@subsubheading Example 18644 18645@smallexample 18646(gdb) 18647111-exec-continue 18648111^running 18649 18650(gdb) 18651222-exec-interrupt 18652222^done 18653(gdb) 18654111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", 18655frame=@{addr="0x00010140",func="foo",args=[],file="try.c", 18656fullname="/home/foo/bar/try.c",line="13"@} 18657(gdb) 18658 18659(gdb) 18660-exec-interrupt 18661^error,msg="mi_cmd_exec_interrupt: Inferior not executing." 18662(gdb) 18663@end smallexample 18664 18665 18666@subheading The @code{-exec-next} Command 18667@findex -exec-next 18668 18669@subsubheading Synopsis 18670 18671@smallexample 18672 -exec-next 18673@end smallexample 18674 18675Resumes execution of the inferior program, stopping when the beginning 18676of the next source line is reached. 18677 18678@subsubheading @value{GDBN} Command 18679 18680The corresponding @value{GDBN} command is @samp{next}. 18681 18682@subsubheading Example 18683 18684@smallexample 18685-exec-next 18686^running 18687(gdb) 18688*stopped,reason="end-stepping-range",line="8",file="hello.c" 18689(gdb) 18690@end smallexample 18691 18692 18693@subheading The @code{-exec-next-instruction} Command 18694@findex -exec-next-instruction 18695 18696@subsubheading Synopsis 18697 18698@smallexample 18699 -exec-next-instruction 18700@end smallexample 18701 18702Executes one machine instruction. If the instruction is a function 18703call, continues until the function returns. If the program stops at an 18704instruction in the middle of a source line, the address will be 18705printed as well. 18706 18707@subsubheading @value{GDBN} Command 18708 18709The corresponding @value{GDBN} command is @samp{nexti}. 18710 18711@subsubheading Example 18712 18713@smallexample 18714(gdb) 18715-exec-next-instruction 18716^running 18717 18718(gdb) 18719*stopped,reason="end-stepping-range", 18720addr="0x000100d4",line="5",file="hello.c" 18721(gdb) 18722@end smallexample 18723 18724 18725@subheading The @code{-exec-return} Command 18726@findex -exec-return 18727 18728@subsubheading Synopsis 18729 18730@smallexample 18731 -exec-return 18732@end smallexample 18733 18734Makes current function return immediately. Doesn't execute the inferior. 18735Displays the new current frame. 18736 18737@subsubheading @value{GDBN} Command 18738 18739The corresponding @value{GDBN} command is @samp{return}. 18740 18741@subsubheading Example 18742 18743@smallexample 18744(gdb) 18745200-break-insert callee4 18746200^done,bkpt=@{number="1",addr="0x00010734", 18747file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} 18748(gdb) 18749000-exec-run 18750000^running 18751(gdb) 18752000*stopped,reason="breakpoint-hit",bkptno="1", 18753frame=@{func="callee4",args=[], 18754file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 18755fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} 18756(gdb) 18757205-break-delete 18758205^done 18759(gdb) 18760111-exec-return 18761111^done,frame=@{level="0",func="callee3", 18762args=[@{name="strarg", 18763value="0x11940 \"A string argument.\""@}], 18764file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 18765fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} 18766(gdb) 18767@end smallexample 18768 18769 18770@subheading The @code{-exec-run} Command 18771@findex -exec-run 18772 18773@subsubheading Synopsis 18774 18775@smallexample 18776 -exec-run 18777@end smallexample 18778 18779Starts execution of the inferior from the beginning. The inferior 18780executes until either a breakpoint is encountered or the program 18781exits. In the latter case the output will include an exit code, if 18782the program has exited exceptionally. 18783 18784@subsubheading @value{GDBN} Command 18785 18786The corresponding @value{GDBN} command is @samp{run}. 18787 18788@subsubheading Examples 18789 18790@smallexample 18791(gdb) 18792-break-insert main 18793^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} 18794(gdb) 18795-exec-run 18796^running 18797(gdb) 18798*stopped,reason="breakpoint-hit",bkptno="1", 18799frame=@{func="main",args=[],file="recursive2.c", 18800fullname="/home/foo/bar/recursive2.c",line="4"@} 18801(gdb) 18802@end smallexample 18803 18804@noindent 18805Program exited normally: 18806 18807@smallexample 18808(gdb) 18809-exec-run 18810^running 18811(gdb) 18812x = 55 18813*stopped,reason="exited-normally" 18814(gdb) 18815@end smallexample 18816 18817@noindent 18818Program exited exceptionally: 18819 18820@smallexample 18821(gdb) 18822-exec-run 18823^running 18824(gdb) 18825x = 55 18826*stopped,reason="exited",exit-code="01" 18827(gdb) 18828@end smallexample 18829 18830Another way the program can terminate is if it receives a signal such as 18831@code{SIGINT}. In this case, @sc{gdb/mi} displays this: 18832 18833@smallexample 18834(gdb) 18835*stopped,reason="exited-signalled",signal-name="SIGINT", 18836signal-meaning="Interrupt" 18837@end smallexample 18838 18839 18840@c @subheading -exec-signal 18841 18842 18843@subheading The @code{-exec-step} Command 18844@findex -exec-step 18845 18846@subsubheading Synopsis 18847 18848@smallexample 18849 -exec-step 18850@end smallexample 18851 18852Resumes execution of the inferior program, stopping when the beginning 18853of the next source line is reached, if the next source line is not a 18854function call. If it is, stop at the first instruction of the called 18855function. 18856 18857@subsubheading @value{GDBN} Command 18858 18859The corresponding @value{GDBN} command is @samp{step}. 18860 18861@subsubheading Example 18862 18863Stepping into a function: 18864 18865@smallexample 18866-exec-step 18867^running 18868(gdb) 18869*stopped,reason="end-stepping-range", 18870frame=@{func="foo",args=[@{name="a",value="10"@}, 18871@{name="b",value="0"@}],file="recursive2.c", 18872fullname="/home/foo/bar/recursive2.c",line="11"@} 18873(gdb) 18874@end smallexample 18875 18876Regular stepping: 18877 18878@smallexample 18879-exec-step 18880^running 18881(gdb) 18882*stopped,reason="end-stepping-range",line="14",file="recursive2.c" 18883(gdb) 18884@end smallexample 18885 18886 18887@subheading The @code{-exec-step-instruction} Command 18888@findex -exec-step-instruction 18889 18890@subsubheading Synopsis 18891 18892@smallexample 18893 -exec-step-instruction 18894@end smallexample 18895 18896Resumes the inferior which executes one machine instruction. The 18897output, once @value{GDBN} has stopped, will vary depending on whether 18898we have stopped in the middle of a source line or not. In the former 18899case, the address at which the program stopped will be printed as 18900well. 18901 18902@subsubheading @value{GDBN} Command 18903 18904The corresponding @value{GDBN} command is @samp{stepi}. 18905 18906@subsubheading Example 18907 18908@smallexample 18909(gdb) 18910-exec-step-instruction 18911^running 18912 18913(gdb) 18914*stopped,reason="end-stepping-range", 18915frame=@{func="foo",args=[],file="try.c", 18916fullname="/home/foo/bar/try.c",line="10"@} 18917(gdb) 18918-exec-step-instruction 18919^running 18920 18921(gdb) 18922*stopped,reason="end-stepping-range", 18923frame=@{addr="0x000100f4",func="foo",args=[],file="try.c", 18924fullname="/home/foo/bar/try.c",line="10"@} 18925(gdb) 18926@end smallexample 18927 18928 18929@subheading The @code{-exec-until} Command 18930@findex -exec-until 18931 18932@subsubheading Synopsis 18933 18934@smallexample 18935 -exec-until [ @var{location} ] 18936@end smallexample 18937 18938Executes the inferior until the @var{location} specified in the 18939argument is reached. If there is no argument, the inferior executes 18940until a source line greater than the current one is reached. The 18941reason for stopping in this case will be @samp{location-reached}. 18942 18943@subsubheading @value{GDBN} Command 18944 18945The corresponding @value{GDBN} command is @samp{until}. 18946 18947@subsubheading Example 18948 18949@smallexample 18950(gdb) 18951-exec-until recursive2.c:6 18952^running 18953(gdb) 18954x = 55 18955*stopped,reason="location-reached",frame=@{func="main",args=[], 18956file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"@} 18957(gdb) 18958@end smallexample 18959 18960@ignore 18961@subheading -file-clear 18962Is this going away???? 18963@end ignore 18964 18965@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 18966@node GDB/MI Stack Manipulation 18967@section @sc{gdb/mi} Stack Manipulation Commands 18968 18969 18970@subheading The @code{-stack-info-frame} Command 18971@findex -stack-info-frame 18972 18973@subsubheading Synopsis 18974 18975@smallexample 18976 -stack-info-frame 18977@end smallexample 18978 18979Get info on the selected frame. 18980 18981@subsubheading @value{GDBN} Command 18982 18983The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame} 18984(without arguments). 18985 18986@subsubheading Example 18987 18988@smallexample 18989(gdb) 18990-stack-info-frame 18991^done,frame=@{level="1",addr="0x0001076c",func="callee3", 18992file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 18993fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@} 18994(gdb) 18995@end smallexample 18996 18997@subheading The @code{-stack-info-depth} Command 18998@findex -stack-info-depth 18999 19000@subsubheading Synopsis 19001 19002@smallexample 19003 -stack-info-depth [ @var{max-depth} ] 19004@end smallexample 19005 19006Return the depth of the stack. If the integer argument @var{max-depth} 19007is specified, do not count beyond @var{max-depth} frames. 19008 19009@subsubheading @value{GDBN} Command 19010 19011There's no equivalent @value{GDBN} command. 19012 19013@subsubheading Example 19014 19015For a stack with frame levels 0 through 11: 19016 19017@smallexample 19018(gdb) 19019-stack-info-depth 19020^done,depth="12" 19021(gdb) 19022-stack-info-depth 4 19023^done,depth="4" 19024(gdb) 19025-stack-info-depth 12 19026^done,depth="12" 19027(gdb) 19028-stack-info-depth 11 19029^done,depth="11" 19030(gdb) 19031-stack-info-depth 13 19032^done,depth="12" 19033(gdb) 19034@end smallexample 19035 19036@subheading The @code{-stack-list-arguments} Command 19037@findex -stack-list-arguments 19038 19039@subsubheading Synopsis 19040 19041@smallexample 19042 -stack-list-arguments @var{show-values} 19043 [ @var{low-frame} @var{high-frame} ] 19044@end smallexample 19045 19046Display a list of the arguments for the frames between @var{low-frame} 19047and @var{high-frame} (inclusive). If @var{low-frame} and 19048@var{high-frame} are not provided, list the arguments for the whole 19049call stack. If the two arguments are equal, show the single frame 19050at the corresponding level. It is an error if @var{low-frame} is 19051larger than the actual number of frames. On the other hand, 19052@var{high-frame} may be larger than the actual number of frames, in 19053which case only existing frames will be returned. 19054 19055The @var{show-values} argument must have a value of 0 or 1. A value of 190560 means that only the names of the arguments are listed, a value of 1 19057means that both names and values of the arguments are printed. 19058 19059@subsubheading @value{GDBN} Command 19060 19061@value{GDBN} does not have an equivalent command. @code{gdbtk} has a 19062@samp{gdb_get_args} command which partially overlaps with the 19063functionality of @samp{-stack-list-arguments}. 19064 19065@subsubheading Example 19066 19067@smallexample 19068(gdb) 19069-stack-list-frames 19070^done, 19071stack=[ 19072frame=@{level="0",addr="0x00010734",func="callee4", 19073file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 19074fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}, 19075frame=@{level="1",addr="0x0001076c",func="callee3", 19076file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 19077fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}, 19078frame=@{level="2",addr="0x0001078c",func="callee2", 19079file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 19080fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"@}, 19081frame=@{level="3",addr="0x000107b4",func="callee1", 19082file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 19083fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"@}, 19084frame=@{level="4",addr="0x000107e0",func="main", 19085file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 19086fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}] 19087(gdb) 19088-stack-list-arguments 0 19089^done, 19090stack-args=[ 19091frame=@{level="0",args=[]@}, 19092frame=@{level="1",args=[name="strarg"]@}, 19093frame=@{level="2",args=[name="intarg",name="strarg"]@}, 19094frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@}, 19095frame=@{level="4",args=[]@}] 19096(gdb) 19097-stack-list-arguments 1 19098^done, 19099stack-args=[ 19100frame=@{level="0",args=[]@}, 19101frame=@{level="1", 19102 args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, 19103frame=@{level="2",args=[ 19104@{name="intarg",value="2"@}, 19105@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, 19106@{frame=@{level="3",args=[ 19107@{name="intarg",value="2"@}, 19108@{name="strarg",value="0x11940 \"A string argument.\""@}, 19109@{name="fltarg",value="3.5"@}]@}, 19110frame=@{level="4",args=[]@}] 19111(gdb) 19112-stack-list-arguments 0 2 2 19113^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}] 19114(gdb) 19115-stack-list-arguments 1 2 2 19116^done,stack-args=[frame=@{level="2", 19117args=[@{name="intarg",value="2"@}, 19118@{name="strarg",value="0x11940 \"A string argument.\""@}]@}] 19119(gdb) 19120@end smallexample 19121 19122@c @subheading -stack-list-exception-handlers 19123 19124 19125@subheading The @code{-stack-list-frames} Command 19126@findex -stack-list-frames 19127 19128@subsubheading Synopsis 19129 19130@smallexample 19131 -stack-list-frames [ @var{low-frame} @var{high-frame} ] 19132@end smallexample 19133 19134List the frames currently on the stack. For each frame it displays the 19135following info: 19136 19137@table @samp 19138@item @var{level} 19139The frame number, 0 being the topmost frame, i.e., the innermost function. 19140@item @var{addr} 19141The @code{$pc} value for that frame. 19142@item @var{func} 19143Function name. 19144@item @var{file} 19145File name of the source file where the function lives. 19146@item @var{line} 19147Line number corresponding to the @code{$pc}. 19148@end table 19149 19150If invoked without arguments, this command prints a backtrace for the 19151whole stack. If given two integer arguments, it shows the frames whose 19152levels are between the two arguments (inclusive). If the two arguments 19153are equal, it shows the single frame at the corresponding level. It is 19154an error if @var{low-frame} is larger than the actual number of 19155frames. On the other hand, @var{high-frame} may be larger than the 19156actual number of frames, in which case only existing frames will be returned. 19157 19158@subsubheading @value{GDBN} Command 19159 19160The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}. 19161 19162@subsubheading Example 19163 19164Full stack backtrace: 19165 19166@smallexample 19167(gdb) 19168-stack-list-frames 19169^done,stack= 19170[frame=@{level="0",addr="0x0001076c",func="foo", 19171 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"@}, 19172frame=@{level="1",addr="0x000107a4",func="foo", 19173 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 19174frame=@{level="2",addr="0x000107a4",func="foo", 19175 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 19176frame=@{level="3",addr="0x000107a4",func="foo", 19177 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 19178frame=@{level="4",addr="0x000107a4",func="foo", 19179 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 19180frame=@{level="5",addr="0x000107a4",func="foo", 19181 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 19182frame=@{level="6",addr="0x000107a4",func="foo", 19183 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 19184frame=@{level="7",addr="0x000107a4",func="foo", 19185 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 19186frame=@{level="8",addr="0x000107a4",func="foo", 19187 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 19188frame=@{level="9",addr="0x000107a4",func="foo", 19189 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 19190frame=@{level="10",addr="0x000107a4",func="foo", 19191 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 19192frame=@{level="11",addr="0x00010738",func="main", 19193 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"@}] 19194(gdb) 19195@end smallexample 19196 19197Show frames between @var{low_frame} and @var{high_frame}: 19198 19199@smallexample 19200(gdb) 19201-stack-list-frames 3 5 19202^done,stack= 19203[frame=@{level="3",addr="0x000107a4",func="foo", 19204 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 19205frame=@{level="4",addr="0x000107a4",func="foo", 19206 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}, 19207frame=@{level="5",addr="0x000107a4",func="foo", 19208 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}] 19209(gdb) 19210@end smallexample 19211 19212Show a single frame: 19213 19214@smallexample 19215(gdb) 19216-stack-list-frames 3 3 19217^done,stack= 19218[frame=@{level="3",addr="0x000107a4",func="foo", 19219 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}] 19220(gdb) 19221@end smallexample 19222 19223 19224@subheading The @code{-stack-list-locals} Command 19225@findex -stack-list-locals 19226 19227@subsubheading Synopsis 19228 19229@smallexample 19230 -stack-list-locals @var{print-values} 19231@end smallexample 19232 19233Display the local variable names for the selected frame. If 19234@var{print-values} is 0 or @code{--no-values}, print only the names of 19235the variables; if it is 1 or @code{--all-values}, print also their 19236values; and if it is 2 or @code{--simple-values}, print the name, 19237type and value for simple data types and the name and type for arrays, 19238structures and unions. In this last case, a frontend can immediately 19239display the value of simple data types and create variable objects for 19240other data types when the user wishes to explore their values in 19241more detail. 19242 19243@subsubheading @value{GDBN} Command 19244 19245@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}. 19246 19247@subsubheading Example 19248 19249@smallexample 19250(gdb) 19251-stack-list-locals 0 19252^done,locals=[name="A",name="B",name="C"] 19253(gdb) 19254-stack-list-locals --all-values 19255^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@}, 19256 @{name="C",value="@{1, 2, 3@}"@}] 19257-stack-list-locals --simple-values 19258^done,locals=[@{name="A",type="int",value="1"@}, 19259 @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}] 19260(gdb) 19261@end smallexample 19262 19263 19264@subheading The @code{-stack-select-frame} Command 19265@findex -stack-select-frame 19266 19267@subsubheading Synopsis 19268 19269@smallexample 19270 -stack-select-frame @var{framenum} 19271@end smallexample 19272 19273Change the selected frame. Select a different frame @var{framenum} on 19274the stack. 19275 19276@subsubheading @value{GDBN} Command 19277 19278The corresponding @value{GDBN} commands are @samp{frame}, @samp{up}, 19279@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}. 19280 19281@subsubheading Example 19282 19283@smallexample 19284(gdb) 19285-stack-select-frame 2 19286^done 19287(gdb) 19288@end smallexample 19289 19290@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 19291@node GDB/MI Variable Objects 19292@section @sc{gdb/mi} Variable Objects 19293 19294@ignore 19295 19296@subheading Motivation for Variable Objects in @sc{gdb/mi} 19297 19298For the implementation of a variable debugger window (locals, watched 19299expressions, etc.), we are proposing the adaptation of the existing code 19300used by @code{Insight}. 19301 19302The two main reasons for that are: 19303 19304@enumerate 1 19305@item 19306It has been proven in practice (it is already on its second generation). 19307 19308@item 19309It will shorten development time (needless to say how important it is 19310now). 19311@end enumerate 19312 19313The original interface was designed to be used by Tcl code, so it was 19314slightly changed so it could be used through @sc{gdb/mi}. This section 19315describes the @sc{gdb/mi} operations that will be available and gives some 19316hints about their use. 19317 19318@emph{Note}: In addition to the set of operations described here, we 19319expect the @sc{gui} implementation of a variable window to require, at 19320least, the following operations: 19321 19322@itemize @bullet 19323@item @code{-gdb-show} @code{output-radix} 19324@item @code{-stack-list-arguments} 19325@item @code{-stack-list-locals} 19326@item @code{-stack-select-frame} 19327@end itemize 19328 19329@end ignore 19330 19331@subheading Introduction to Variable Objects 19332 19333@cindex variable objects in @sc{gdb/mi} 19334 19335Variable objects are "object-oriented" MI interface for examining and 19336changing values of expressions. Unlike some other MI interfaces that 19337work with expressions, variable objects are specifically designed for 19338simple and efficient presentation in the frontend. A variable object 19339is identified by string name. When a variable object is created, the 19340frontend specifies the expression for that variable object. The 19341expression can be a simple variable, or it can be an arbitrary complex 19342expression, and can even involve CPU registers. After creating a 19343variable object, the frontend can invoke other variable object 19344operations---for example to obtain or change the value of a variable 19345object, or to change display format. 19346 19347Variable objects have hierarchical tree structure. Any variable object 19348that corresponds to a composite type, such as structure in C, has 19349a number of child variable objects, for example corresponding to each 19350element of a structure. A child variable object can itself have 19351children, recursively. Recursion ends when we reach 19352leaf variable objects, which always have built-in types. Child variable 19353objects are created only by explicit request, so if a frontend 19354is not interested in the children of a particular variable object, no 19355child will be created. 19356 19357For a leaf variable object it is possible to obtain its value as a 19358string, or set the value from a string. String value can be also 19359obtained for a non-leaf variable object, but it's generally a string 19360that only indicates the type of the object, and does not list its 19361contents. Assignment to a non-leaf variable object is not allowed. 19362 19363A frontend does not need to read the values of all variable objects each time 19364the program stops. Instead, MI provides an update command that lists all 19365variable objects whose values has changed since the last update 19366operation. This considerably reduces the amount of data that must 19367be transferred to the frontend. As noted above, children variable 19368objects are created on demand, and only leaf variable objects have a 19369real value. As result, gdb will read target memory only for leaf 19370variables that frontend has created. 19371 19372The automatic update is not always desirable. For example, a frontend 19373might want to keep a value of some expression for future reference, 19374and never update it. For another example, fetching memory is 19375relatively slow for embedded targets, so a frontend might want 19376to disable automatic update for the variables that are either not 19377visible on the screen, or ``closed''. This is possible using so 19378called ``frozen variable objects''. Such variable objects are never 19379implicitly updated. 19380 19381The following is the complete set of @sc{gdb/mi} operations defined to 19382access this functionality: 19383 19384@multitable @columnfractions .4 .6 19385@item @strong{Operation} 19386@tab @strong{Description} 19387 19388@item @code{-var-create} 19389@tab create a variable object 19390@item @code{-var-delete} 19391@tab delete the variable object and/or its children 19392@item @code{-var-set-format} 19393@tab set the display format of this variable 19394@item @code{-var-show-format} 19395@tab show the display format of this variable 19396@item @code{-var-info-num-children} 19397@tab tells how many children this object has 19398@item @code{-var-list-children} 19399@tab return a list of the object's children 19400@item @code{-var-info-type} 19401@tab show the type of this variable object 19402@item @code{-var-info-expression} 19403@tab print parent-relative expression that this variable object represents 19404@item @code{-var-info-path-expression} 19405@tab print full expression that this variable object represents 19406@item @code{-var-show-attributes} 19407@tab is this variable editable? does it exist here? 19408@item @code{-var-evaluate-expression} 19409@tab get the value of this variable 19410@item @code{-var-assign} 19411@tab set the value of this variable 19412@item @code{-var-update} 19413@tab update the variable and its children 19414@item @code{-var-set-frozen} 19415@tab set frozeness attribute 19416@end multitable 19417 19418In the next subsection we describe each operation in detail and suggest 19419how it can be used. 19420 19421@subheading Description And Use of Operations on Variable Objects 19422 19423@subheading The @code{-var-create} Command 19424@findex -var-create 19425 19426@subsubheading Synopsis 19427 19428@smallexample 19429 -var-create @{@var{name} | "-"@} 19430 @{@var{frame-addr} | "*"@} @var{expression} 19431@end smallexample 19432 19433This operation creates a variable object, which allows the monitoring of 19434a variable, the result of an expression, a memory cell or a CPU 19435register. 19436 19437The @var{name} parameter is the string by which the object can be 19438referenced. It must be unique. If @samp{-} is specified, the varobj 19439system will generate a string ``varNNNNNN'' automatically. It will be 19440unique provided that one does not specify @var{name} on that format. 19441The command fails if a duplicate name is found. 19442 19443The frame under which the expression should be evaluated can be 19444specified by @var{frame-addr}. A @samp{*} indicates that the current 19445frame should be used. 19446 19447@var{expression} is any expression valid on the current language set (must not 19448begin with a @samp{*}), or one of the following: 19449 19450@itemize @bullet 19451@item 19452@samp{*@var{addr}}, where @var{addr} is the address of a memory cell 19453 19454@item 19455@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD) 19456 19457@item 19458@samp{$@var{regname}} --- a CPU register name 19459@end itemize 19460 19461@subsubheading Result 19462 19463This operation returns the name, number of children and the type of the 19464object created. Type is returned as a string as the ones generated by 19465the @value{GDBN} CLI: 19466 19467@smallexample 19468 name="@var{name}",numchild="N",type="@var{type}" 19469@end smallexample 19470 19471 19472@subheading The @code{-var-delete} Command 19473@findex -var-delete 19474 19475@subsubheading Synopsis 19476 19477@smallexample 19478 -var-delete [ -c ] @var{name} 19479@end smallexample 19480 19481Deletes a previously created variable object and all of its children. 19482With the @samp{-c} option, just deletes the children. 19483 19484Returns an error if the object @var{name} is not found. 19485 19486 19487@subheading The @code{-var-set-format} Command 19488@findex -var-set-format 19489 19490@subsubheading Synopsis 19491 19492@smallexample 19493 -var-set-format @var{name} @var{format-spec} 19494@end smallexample 19495 19496Sets the output format for the value of the object @var{name} to be 19497@var{format-spec}. 19498 19499The syntax for the @var{format-spec} is as follows: 19500 19501@smallexample 19502 @var{format-spec} @expansion{} 19503 @{binary | decimal | hexadecimal | octal | natural@} 19504@end smallexample 19505 19506The natural format is the default format choosen automatically 19507based on the variable type (like decimal for an @code{int}, hex 19508for pointers, etc.). 19509 19510For a variable with children, the format is set only on the 19511variable itself, and the children are not affected. 19512 19513@subheading The @code{-var-show-format} Command 19514@findex -var-show-format 19515 19516@subsubheading Synopsis 19517 19518@smallexample 19519 -var-show-format @var{name} 19520@end smallexample 19521 19522Returns the format used to display the value of the object @var{name}. 19523 19524@smallexample 19525 @var{format} @expansion{} 19526 @var{format-spec} 19527@end smallexample 19528 19529 19530@subheading The @code{-var-info-num-children} Command 19531@findex -var-info-num-children 19532 19533@subsubheading Synopsis 19534 19535@smallexample 19536 -var-info-num-children @var{name} 19537@end smallexample 19538 19539Returns the number of children of a variable object @var{name}: 19540 19541@smallexample 19542 numchild=@var{n} 19543@end smallexample 19544 19545 19546@subheading The @code{-var-list-children} Command 19547@findex -var-list-children 19548 19549@subsubheading Synopsis 19550 19551@smallexample 19552 -var-list-children [@var{print-values}] @var{name} 19553@end smallexample 19554@anchor{-var-list-children} 19555 19556Return a list of the children of the specified variable object and 19557create variable objects for them, if they do not already exist. With 19558a single argument or if @var{print-values} has a value for of 0 or 19559@code{--no-values}, print only the names of the variables; if 19560@var{print-values} is 1 or @code{--all-values}, also print their 19561values; and if it is 2 or @code{--simple-values} print the name and 19562value for simple data types and just the name for arrays, structures 19563and unions. 19564 19565@subsubheading Example 19566 19567@smallexample 19568(gdb) 19569 -var-list-children n 19570 ^done,numchild=@var{n},children=[@{name=@var{name}, 19571 numchild=@var{n},type=@var{type}@},@r{(repeats N times)}] 19572(gdb) 19573 -var-list-children --all-values n 19574 ^done,numchild=@var{n},children=[@{name=@var{name}, 19575 numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}] 19576@end smallexample 19577 19578 19579@subheading The @code{-var-info-type} Command 19580@findex -var-info-type 19581 19582@subsubheading Synopsis 19583 19584@smallexample 19585 -var-info-type @var{name} 19586@end smallexample 19587 19588Returns the type of the specified variable @var{name}. The type is 19589returned as a string in the same format as it is output by the 19590@value{GDBN} CLI: 19591 19592@smallexample 19593 type=@var{typename} 19594@end smallexample 19595 19596 19597@subheading The @code{-var-info-expression} Command 19598@findex -var-info-expression 19599 19600@subsubheading Synopsis 19601 19602@smallexample 19603 -var-info-expression @var{name} 19604@end smallexample 19605 19606Returns a string that is suitable for presenting this 19607variable object in user interface. The string is generally 19608not valid expression in the current language, and cannot be evaluated. 19609 19610For example, if @code{a} is an array, and variable object 19611@code{A} was created for @code{a}, then we'll get this output: 19612 19613@smallexample 19614(gdb) -var-info-expression A.1 19615^done,lang="C",exp="1" 19616@end smallexample 19617 19618@noindent 19619Here, the values of @code{lang} can be @code{@{"C" | "C++" | "Java"@}}. 19620 19621Note that the output of the @code{-var-list-children} command also 19622includes those expressions, so the @code{-var-info-expression} command 19623is of limited use. 19624 19625@subheading The @code{-var-info-path-expression} Command 19626@findex -var-info-path-expression 19627 19628@subsubheading Synopsis 19629 19630@smallexample 19631 -var-info-path-expression @var{name} 19632@end smallexample 19633 19634Returns an expression that can be evaluated in the current 19635context and will yield the same value that a variable object has. 19636Compare this with the @code{-var-info-expression} command, which 19637result can be used only for UI presentation. Typical use of 19638the @code{-var-info-path-expression} command is creating a 19639watchpoint from a variable object. 19640 19641For example, suppose @code{C} is a C@t{++} class, derived from class 19642@code{Base}, and that the @code{Base} class has a member called 19643@code{m_size}. Assume a variable @code{c} is has the type of 19644@code{C} and a variable object @code{C} was created for variable 19645@code{c}. Then, we'll get this output: 19646@smallexample 19647(gdb) -var-info-path-expression C.Base.public.m_size 19648^done,path_expr=((Base)c).m_size) 19649@end smallexample 19650 19651@subheading The @code{-var-show-attributes} Command 19652@findex -var-show-attributes 19653 19654@subsubheading Synopsis 19655 19656@smallexample 19657 -var-show-attributes @var{name} 19658@end smallexample 19659 19660List attributes of the specified variable object @var{name}: 19661 19662@smallexample 19663 status=@var{attr} [ ( ,@var{attr} )* ] 19664@end smallexample 19665 19666@noindent 19667where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}. 19668 19669@subheading The @code{-var-evaluate-expression} Command 19670@findex -var-evaluate-expression 19671 19672@subsubheading Synopsis 19673 19674@smallexample 19675 -var-evaluate-expression @var{name} 19676@end smallexample 19677 19678Evaluates the expression that is represented by the specified variable 19679object and returns its value as a string. The format of the 19680string can be changed using the @code{-var-set-format} command. 19681 19682@smallexample 19683 value=@var{value} 19684@end smallexample 19685 19686Note that one must invoke @code{-var-list-children} for a variable 19687before the value of a child variable can be evaluated. 19688 19689@subheading The @code{-var-assign} Command 19690@findex -var-assign 19691 19692@subsubheading Synopsis 19693 19694@smallexample 19695 -var-assign @var{name} @var{expression} 19696@end smallexample 19697 19698Assigns the value of @var{expression} to the variable object specified 19699by @var{name}. The object must be @samp{editable}. If the variable's 19700value is altered by the assign, the variable will show up in any 19701subsequent @code{-var-update} list. 19702 19703@subsubheading Example 19704 19705@smallexample 19706(gdb) 19707-var-assign var1 3 19708^done,value="3" 19709(gdb) 19710-var-update * 19711^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}] 19712(gdb) 19713@end smallexample 19714 19715@subheading The @code{-var-update} Command 19716@findex -var-update 19717 19718@subsubheading Synopsis 19719 19720@smallexample 19721 -var-update [@var{print-values}] @{@var{name} | "*"@} 19722@end smallexample 19723 19724Reevaluate the expressions corresponding to the variable object 19725@var{name} and all its direct and indirect children, and return the 19726list of variable objects whose values have changed; @var{name} must 19727be a root variable object. Here, ``changed'' means that the result of 19728@code{-var-evaluate-expression} before and after the 19729@code{-var-update} is different. If @samp{*} is used as the variable 19730object names, all existing variable objects are updated, except 19731for frozen ones (@pxref{-var-set-frozen}). The option 19732@var{print-values} determines whether both names and values, or just 19733names are printed. The possible values of this options are the same 19734as for @code{-var-list-children} (@pxref{-var-list-children}). It is 19735recommended to use the @samp{--all-values} option, to reduce the 19736number of MI commands needed on each program stop. 19737 19738 19739@subsubheading Example 19740 19741@smallexample 19742(gdb) 19743-var-assign var1 3 19744^done,value="3" 19745(gdb) 19746-var-update --all-values var1 19747^done,changelist=[@{name="var1",value="3",in_scope="true", 19748type_changed="false"@}] 19749(gdb) 19750@end smallexample 19751 19752@anchor{-var-update} 19753The field in_scope may take three values: 19754 19755@table @code 19756@item "true" 19757The variable object's current value is valid. 19758 19759@item "false" 19760The variable object does not currently hold a valid value but it may 19761hold one in the future if its associated expression comes back into 19762scope. 19763 19764@item "invalid" 19765The variable object no longer holds a valid value. 19766This can occur when the executable file being debugged has changed, 19767either through recompilation or by using the @value{GDBN} @code{file} 19768command. The front end should normally choose to delete these variable 19769objects. 19770@end table 19771 19772In the future new values may be added to this list so the front should 19773be prepared for this possibility. @xref{GDB/MI Development and Front Ends, ,@sc{GDB/MI} Development and Front Ends}. 19774 19775@subheading The @code{-var-set-frozen} Command 19776@findex -var-set-frozen 19777@anchor{-var-set-frozen} 19778 19779@subsubheading Synopsis 19780 19781@smallexample 19782 -var-set-frozen @var{name} @var{flag} 19783@end smallexample 19784 19785Set the frozenness flag on the variable object @var{name}. The 19786@var{flag} parameter should be either @samp{1} to make the variable 19787frozen or @samp{0} to make it unfrozen. If a variable object is 19788frozen, then neither itself, nor any of its children, are 19789implicitly updated by @code{-var-update} of 19790a parent variable or by @code{-var-update *}. Only 19791@code{-var-update} of the variable itself will update its value and 19792values of its children. After a variable object is unfrozen, it is 19793implicitly updated by all subsequent @code{-var-update} operations. 19794Unfreezing a variable does not update it, only subsequent 19795@code{-var-update} does. 19796 19797@subsubheading Example 19798 19799@smallexample 19800(gdb) 19801-var-set-frozen V 1 19802^done 19803(gdb) 19804@end smallexample 19805 19806 19807@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 19808@node GDB/MI Data Manipulation 19809@section @sc{gdb/mi} Data Manipulation 19810 19811@cindex data manipulation, in @sc{gdb/mi} 19812@cindex @sc{gdb/mi}, data manipulation 19813This section describes the @sc{gdb/mi} commands that manipulate data: 19814examine memory and registers, evaluate expressions, etc. 19815 19816@c REMOVED FROM THE INTERFACE. 19817@c @subheading -data-assign 19818@c Change the value of a program variable. Plenty of side effects. 19819@c @subsubheading GDB Command 19820@c set variable 19821@c @subsubheading Example 19822@c N.A. 19823 19824@subheading The @code{-data-disassemble} Command 19825@findex -data-disassemble 19826 19827@subsubheading Synopsis 19828 19829@smallexample 19830 -data-disassemble 19831 [ -s @var{start-addr} -e @var{end-addr} ] 19832 | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ] 19833 -- @var{mode} 19834@end smallexample 19835 19836@noindent 19837Where: 19838 19839@table @samp 19840@item @var{start-addr} 19841is the beginning address (or @code{$pc}) 19842@item @var{end-addr} 19843is the end address 19844@item @var{filename} 19845is the name of the file to disassemble 19846@item @var{linenum} 19847is the line number to disassemble around 19848@item @var{lines} 19849is the number of disassembly lines to be produced. If it is -1, 19850the whole function will be disassembled, in case no @var{end-addr} is 19851specified. If @var{end-addr} is specified as a non-zero value, and 19852@var{lines} is lower than the number of disassembly lines between 19853@var{start-addr} and @var{end-addr}, only @var{lines} lines are 19854displayed; if @var{lines} is higher than the number of lines between 19855@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr} 19856are displayed. 19857@item @var{mode} 19858is either 0 (meaning only disassembly) or 1 (meaning mixed source and 19859disassembly). 19860@end table 19861 19862@subsubheading Result 19863 19864The output for each instruction is composed of four fields: 19865 19866@itemize @bullet 19867@item Address 19868@item Func-name 19869@item Offset 19870@item Instruction 19871@end itemize 19872 19873Note that whatever included in the instruction field, is not manipulated 19874directly by @sc{gdb/mi}, i.e., it is not possible to adjust its format. 19875 19876@subsubheading @value{GDBN} Command 19877 19878There's no direct mapping from this command to the CLI. 19879 19880@subsubheading Example 19881 19882Disassemble from the current value of @code{$pc} to @code{$pc + 20}: 19883 19884@smallexample 19885(gdb) 19886-data-disassemble -s $pc -e "$pc + 20" -- 0 19887^done, 19888asm_insns=[ 19889@{address="0x000107c0",func-name="main",offset="4", 19890inst="mov 2, %o0"@}, 19891@{address="0x000107c4",func-name="main",offset="8", 19892inst="sethi %hi(0x11800), %o2"@}, 19893@{address="0x000107c8",func-name="main",offset="12", 19894inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@}, 19895@{address="0x000107cc",func-name="main",offset="16", 19896inst="sethi %hi(0x11800), %o2"@}, 19897@{address="0x000107d0",func-name="main",offset="20", 19898inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}] 19899(gdb) 19900@end smallexample 19901 19902Disassemble the whole @code{main} function. Line 32 is part of 19903@code{main}. 19904 19905@smallexample 19906-data-disassemble -f basics.c -l 32 -- 0 19907^done,asm_insns=[ 19908@{address="0x000107bc",func-name="main",offset="0", 19909inst="save %sp, -112, %sp"@}, 19910@{address="0x000107c0",func-name="main",offset="4", 19911inst="mov 2, %o0"@}, 19912@{address="0x000107c4",func-name="main",offset="8", 19913inst="sethi %hi(0x11800), %o2"@}, 19914[@dots{}] 19915@{address="0x0001081c",func-name="main",offset="96",inst="ret "@}, 19916@{address="0x00010820",func-name="main",offset="100",inst="restore "@}] 19917(gdb) 19918@end smallexample 19919 19920Disassemble 3 instructions from the start of @code{main}: 19921 19922@smallexample 19923(gdb) 19924-data-disassemble -f basics.c -l 32 -n 3 -- 0 19925^done,asm_insns=[ 19926@{address="0x000107bc",func-name="main",offset="0", 19927inst="save %sp, -112, %sp"@}, 19928@{address="0x000107c0",func-name="main",offset="4", 19929inst="mov 2, %o0"@}, 19930@{address="0x000107c4",func-name="main",offset="8", 19931inst="sethi %hi(0x11800), %o2"@}] 19932(gdb) 19933@end smallexample 19934 19935Disassemble 3 instructions from the start of @code{main} in mixed mode: 19936 19937@smallexample 19938(gdb) 19939-data-disassemble -f basics.c -l 32 -n 3 -- 1 19940^done,asm_insns=[ 19941src_and_asm_line=@{line="31", 19942file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ 19943 testsuite/gdb.mi/basics.c",line_asm_insn=[ 19944@{address="0x000107bc",func-name="main",offset="0", 19945inst="save %sp, -112, %sp"@}]@}, 19946src_and_asm_line=@{line="32", 19947file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ 19948 testsuite/gdb.mi/basics.c",line_asm_insn=[ 19949@{address="0x000107c0",func-name="main",offset="4", 19950inst="mov 2, %o0"@}, 19951@{address="0x000107c4",func-name="main",offset="8", 19952inst="sethi %hi(0x11800), %o2"@}]@}] 19953(gdb) 19954@end smallexample 19955 19956 19957@subheading The @code{-data-evaluate-expression} Command 19958@findex -data-evaluate-expression 19959 19960@subsubheading Synopsis 19961 19962@smallexample 19963 -data-evaluate-expression @var{expr} 19964@end smallexample 19965 19966Evaluate @var{expr} as an expression. The expression could contain an 19967inferior function call. The function call will execute synchronously. 19968If the expression contains spaces, it must be enclosed in double quotes. 19969 19970@subsubheading @value{GDBN} Command 19971 19972The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and 19973@samp{call}. In @code{gdbtk} only, there's a corresponding 19974@samp{gdb_eval} command. 19975 19976@subsubheading Example 19977 19978In the following example, the numbers that precede the commands are the 19979@dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi} 19980Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its 19981output. 19982 19983@smallexample 19984211-data-evaluate-expression A 19985211^done,value="1" 19986(gdb) 19987311-data-evaluate-expression &A 19988311^done,value="0xefffeb7c" 19989(gdb) 19990411-data-evaluate-expression A+3 19991411^done,value="4" 19992(gdb) 19993511-data-evaluate-expression "A + 3" 19994511^done,value="4" 19995(gdb) 19996@end smallexample 19997 19998 19999@subheading The @code{-data-list-changed-registers} Command 20000@findex -data-list-changed-registers 20001 20002@subsubheading Synopsis 20003 20004@smallexample 20005 -data-list-changed-registers 20006@end smallexample 20007 20008Display a list of the registers that have changed. 20009 20010@subsubheading @value{GDBN} Command 20011 20012@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk} 20013has the corresponding command @samp{gdb_changed_register_list}. 20014 20015@subsubheading Example 20016 20017On a PPC MBX board: 20018 20019@smallexample 20020(gdb) 20021-exec-continue 20022^running 20023 20024(gdb) 20025*stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main", 20026args=[],file="try.c",fullname="/home/foo/bar/try.c",line="5"@} 20027(gdb) 20028-data-list-changed-registers 20029^done,changed-registers=["0","1","2","4","5","6","7","8","9", 20030"10","11","13","14","15","16","17","18","19","20","21","22","23", 20031"24","25","26","27","28","30","31","64","65","66","67","69"] 20032(gdb) 20033@end smallexample 20034 20035 20036@subheading The @code{-data-list-register-names} Command 20037@findex -data-list-register-names 20038 20039@subsubheading Synopsis 20040 20041@smallexample 20042 -data-list-register-names [ ( @var{regno} )+ ] 20043@end smallexample 20044 20045Show a list of register names for the current target. If no arguments 20046are given, it shows a list of the names of all the registers. If 20047integer numbers are given as arguments, it will print a list of the 20048names of the registers corresponding to the arguments. To ensure 20049consistency between a register name and its number, the output list may 20050include empty register names. 20051 20052@subsubheading @value{GDBN} Command 20053 20054@value{GDBN} does not have a command which corresponds to 20055@samp{-data-list-register-names}. In @code{gdbtk} there is a 20056corresponding command @samp{gdb_regnames}. 20057 20058@subsubheading Example 20059 20060For the PPC MBX board: 20061@smallexample 20062(gdb) 20063-data-list-register-names 20064^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", 20065"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", 20066"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", 20067"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", 20068"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", 20069"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", 20070"", "pc","ps","cr","lr","ctr","xer"] 20071(gdb) 20072-data-list-register-names 1 2 3 20073^done,register-names=["r1","r2","r3"] 20074(gdb) 20075@end smallexample 20076 20077@subheading The @code{-data-list-register-values} Command 20078@findex -data-list-register-values 20079 20080@subsubheading Synopsis 20081 20082@smallexample 20083 -data-list-register-values @var{fmt} [ ( @var{regno} )*] 20084@end smallexample 20085 20086Display the registers' contents. @var{fmt} is the format according to 20087which the registers' contents are to be returned, followed by an optional 20088list of numbers specifying the registers to display. A missing list of 20089numbers indicates that the contents of all the registers must be returned. 20090 20091Allowed formats for @var{fmt} are: 20092 20093@table @code 20094@item x 20095Hexadecimal 20096@item o 20097Octal 20098@item t 20099Binary 20100@item d 20101Decimal 20102@item r 20103Raw 20104@item N 20105Natural 20106@end table 20107 20108@subsubheading @value{GDBN} Command 20109 20110The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info 20111all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}. 20112 20113@subsubheading Example 20114 20115For a PPC MBX board (note: line breaks are for readability only, they 20116don't appear in the actual output): 20117 20118@smallexample 20119(gdb) 20120-data-list-register-values r 64 65 20121^done,register-values=[@{number="64",value="0xfe00a300"@}, 20122@{number="65",value="0x00029002"@}] 20123(gdb) 20124-data-list-register-values x 20125^done,register-values=[@{number="0",value="0xfe0043c8"@}, 20126@{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@}, 20127@{number="3",value="0x0"@},@{number="4",value="0xa"@}, 20128@{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@}, 20129@{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@}, 20130@{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@}, 20131@{number="11",value="0x1"@},@{number="12",value="0x0"@}, 20132@{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@}, 20133@{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@}, 20134@{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@}, 20135@{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@}, 20136@{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@}, 20137@{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@}, 20138@{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@}, 20139@{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@}, 20140@{number="29",value="0x0"@},@{number="30",value="0xfe010000"@}, 20141@{number="31",value="0x0"@},@{number="32",value="0x0"@}, 20142@{number="33",value="0x0"@},@{number="34",value="0x0"@}, 20143@{number="35",value="0x0"@},@{number="36",value="0x0"@}, 20144@{number="37",value="0x0"@},@{number="38",value="0x0"@}, 20145@{number="39",value="0x0"@},@{number="40",value="0x0"@}, 20146@{number="41",value="0x0"@},@{number="42",value="0x0"@}, 20147@{number="43",value="0x0"@},@{number="44",value="0x0"@}, 20148@{number="45",value="0x0"@},@{number="46",value="0x0"@}, 20149@{number="47",value="0x0"@},@{number="48",value="0x0"@}, 20150@{number="49",value="0x0"@},@{number="50",value="0x0"@}, 20151@{number="51",value="0x0"@},@{number="52",value="0x0"@}, 20152@{number="53",value="0x0"@},@{number="54",value="0x0"@}, 20153@{number="55",value="0x0"@},@{number="56",value="0x0"@}, 20154@{number="57",value="0x0"@},@{number="58",value="0x0"@}, 20155@{number="59",value="0x0"@},@{number="60",value="0x0"@}, 20156@{number="61",value="0x0"@},@{number="62",value="0x0"@}, 20157@{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@}, 20158@{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@}, 20159@{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@}, 20160@{number="69",value="0x20002b03"@}] 20161(gdb) 20162@end smallexample 20163 20164 20165@subheading The @code{-data-read-memory} Command 20166@findex -data-read-memory 20167 20168@subsubheading Synopsis 20169 20170@smallexample 20171 -data-read-memory [ -o @var{byte-offset} ] 20172 @var{address} @var{word-format} @var{word-size} 20173 @var{nr-rows} @var{nr-cols} [ @var{aschar} ] 20174@end smallexample 20175 20176@noindent 20177where: 20178 20179@table @samp 20180@item @var{address} 20181An expression specifying the address of the first memory word to be 20182read. Complex expressions containing embedded white space should be 20183quoted using the C convention. 20184 20185@item @var{word-format} 20186The format to be used to print the memory words. The notation is the 20187same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats, 20188,Output Formats}). 20189 20190@item @var{word-size} 20191The size of each memory word in bytes. 20192 20193@item @var{nr-rows} 20194The number of rows in the output table. 20195 20196@item @var{nr-cols} 20197The number of columns in the output table. 20198 20199@item @var{aschar} 20200If present, indicates that each row should include an @sc{ascii} dump. The 20201value of @var{aschar} is used as a padding character when a byte is not a 20202member of the printable @sc{ascii} character set (printable @sc{ascii} 20203characters are those whose code is between 32 and 126, inclusively). 20204 20205@item @var{byte-offset} 20206An offset to add to the @var{address} before fetching memory. 20207@end table 20208 20209This command displays memory contents as a table of @var{nr-rows} by 20210@var{nr-cols} words, each word being @var{word-size} bytes. In total, 20211@code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read 20212(returned as @samp{total-bytes}). Should less than the requested number 20213of bytes be returned by the target, the missing words are identified 20214using @samp{N/A}. The number of bytes read from the target is returned 20215in @samp{nr-bytes} and the starting address used to read memory in 20216@samp{addr}. 20217 20218The address of the next/previous row or page is available in 20219@samp{next-row} and @samp{prev-row}, @samp{next-page} and 20220@samp{prev-page}. 20221 20222@subsubheading @value{GDBN} Command 20223 20224The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has 20225@samp{gdb_get_mem} memory read command. 20226 20227@subsubheading Example 20228 20229Read six bytes of memory starting at @code{bytes+6} but then offset by 20230@code{-6} bytes. Format as three rows of two columns. One byte per 20231word. Display each word in hex. 20232 20233@smallexample 20234(gdb) 202359-data-read-memory -o -6 -- bytes+6 x 1 3 2 202369^done,addr="0x00001390",nr-bytes="6",total-bytes="6", 20237next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", 20238prev-page="0x0000138a",memory=[ 20239@{addr="0x00001390",data=["0x00","0x01"]@}, 20240@{addr="0x00001392",data=["0x02","0x03"]@}, 20241@{addr="0x00001394",data=["0x04","0x05"]@}] 20242(gdb) 20243@end smallexample 20244 20245Read two bytes of memory starting at address @code{shorts + 64} and 20246display as a single word formatted in decimal. 20247 20248@smallexample 20249(gdb) 202505-data-read-memory shorts+64 d 2 1 1 202515^done,addr="0x00001510",nr-bytes="2",total-bytes="2", 20252next-row="0x00001512",prev-row="0x0000150e", 20253next-page="0x00001512",prev-page="0x0000150e",memory=[ 20254@{addr="0x00001510",data=["128"]@}] 20255(gdb) 20256@end smallexample 20257 20258Read thirty two bytes of memory starting at @code{bytes+16} and format 20259as eight rows of four columns. Include a string encoding with @samp{x} 20260used as the non-printable character. 20261 20262@smallexample 20263(gdb) 202644-data-read-memory bytes+16 x 1 8 4 x 202654^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", 20266next-row="0x000013c0",prev-row="0x0000139c", 20267next-page="0x000013c0",prev-page="0x00001380",memory=[ 20268@{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@}, 20269@{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@}, 20270@{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@}, 20271@{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@}, 20272@{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@}, 20273@{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@}, 20274@{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@}, 20275@{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}] 20276(gdb) 20277@end smallexample 20278 20279@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 20280@node GDB/MI Tracepoint Commands 20281@section @sc{gdb/mi} Tracepoint Commands 20282 20283The tracepoint commands are not yet implemented. 20284 20285@c @subheading -trace-actions 20286 20287@c @subheading -trace-delete 20288 20289@c @subheading -trace-disable 20290 20291@c @subheading -trace-dump 20292 20293@c @subheading -trace-enable 20294 20295@c @subheading -trace-exists 20296 20297@c @subheading -trace-find 20298 20299@c @subheading -trace-frame-number 20300 20301@c @subheading -trace-info 20302 20303@c @subheading -trace-insert 20304 20305@c @subheading -trace-list 20306 20307@c @subheading -trace-pass-count 20308 20309@c @subheading -trace-save 20310 20311@c @subheading -trace-start 20312 20313@c @subheading -trace-stop 20314 20315 20316@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 20317@node GDB/MI Symbol Query 20318@section @sc{gdb/mi} Symbol Query Commands 20319 20320 20321@subheading The @code{-symbol-info-address} Command 20322@findex -symbol-info-address 20323 20324@subsubheading Synopsis 20325 20326@smallexample 20327 -symbol-info-address @var{symbol} 20328@end smallexample 20329 20330Describe where @var{symbol} is stored. 20331 20332@subsubheading @value{GDBN} Command 20333 20334The corresponding @value{GDBN} command is @samp{info address}. 20335 20336@subsubheading Example 20337N.A. 20338 20339 20340@subheading The @code{-symbol-info-file} Command 20341@findex -symbol-info-file 20342 20343@subsubheading Synopsis 20344 20345@smallexample 20346 -symbol-info-file 20347@end smallexample 20348 20349Show the file for the symbol. 20350 20351@subsubheading @value{GDBN} Command 20352 20353There's no equivalent @value{GDBN} command. @code{gdbtk} has 20354@samp{gdb_find_file}. 20355 20356@subsubheading Example 20357N.A. 20358 20359 20360@subheading The @code{-symbol-info-function} Command 20361@findex -symbol-info-function 20362 20363@subsubheading Synopsis 20364 20365@smallexample 20366 -symbol-info-function 20367@end smallexample 20368 20369Show which function the symbol lives in. 20370 20371@subsubheading @value{GDBN} Command 20372 20373@samp{gdb_get_function} in @code{gdbtk}. 20374 20375@subsubheading Example 20376N.A. 20377 20378 20379@subheading The @code{-symbol-info-line} Command 20380@findex -symbol-info-line 20381 20382@subsubheading Synopsis 20383 20384@smallexample 20385 -symbol-info-line 20386@end smallexample 20387 20388Show the core addresses of the code for a source line. 20389 20390@subsubheading @value{GDBN} Command 20391 20392The corresponding @value{GDBN} command is @samp{info line}. 20393@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands. 20394 20395@subsubheading Example 20396N.A. 20397 20398 20399@subheading The @code{-symbol-info-symbol} Command 20400@findex -symbol-info-symbol 20401 20402@subsubheading Synopsis 20403 20404@smallexample 20405 -symbol-info-symbol @var{addr} 20406@end smallexample 20407 20408Describe what symbol is at location @var{addr}. 20409 20410@subsubheading @value{GDBN} Command 20411 20412The corresponding @value{GDBN} command is @samp{info symbol}. 20413 20414@subsubheading Example 20415N.A. 20416 20417 20418@subheading The @code{-symbol-list-functions} Command 20419@findex -symbol-list-functions 20420 20421@subsubheading Synopsis 20422 20423@smallexample 20424 -symbol-list-functions 20425@end smallexample 20426 20427List the functions in the executable. 20428 20429@subsubheading @value{GDBN} Command 20430 20431@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and 20432@samp{gdb_search} in @code{gdbtk}. 20433 20434@subsubheading Example 20435N.A. 20436 20437 20438@subheading The @code{-symbol-list-lines} Command 20439@findex -symbol-list-lines 20440 20441@subsubheading Synopsis 20442 20443@smallexample 20444 -symbol-list-lines @var{filename} 20445@end smallexample 20446 20447Print the list of lines that contain code and their associated program 20448addresses for the given source filename. The entries are sorted in 20449ascending PC order. 20450 20451@subsubheading @value{GDBN} Command 20452 20453There is no corresponding @value{GDBN} command. 20454 20455@subsubheading Example 20456@smallexample 20457(gdb) 20458-symbol-list-lines basics.c 20459^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}] 20460(gdb) 20461@end smallexample 20462 20463 20464@subheading The @code{-symbol-list-types} Command 20465@findex -symbol-list-types 20466 20467@subsubheading Synopsis 20468 20469@smallexample 20470 -symbol-list-types 20471@end smallexample 20472 20473List all the type names. 20474 20475@subsubheading @value{GDBN} Command 20476 20477The corresponding commands are @samp{info types} in @value{GDBN}, 20478@samp{gdb_search} in @code{gdbtk}. 20479 20480@subsubheading Example 20481N.A. 20482 20483 20484@subheading The @code{-symbol-list-variables} Command 20485@findex -symbol-list-variables 20486 20487@subsubheading Synopsis 20488 20489@smallexample 20490 -symbol-list-variables 20491@end smallexample 20492 20493List all the global and static variable names. 20494 20495@subsubheading @value{GDBN} Command 20496 20497@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}. 20498 20499@subsubheading Example 20500N.A. 20501 20502 20503@subheading The @code{-symbol-locate} Command 20504@findex -symbol-locate 20505 20506@subsubheading Synopsis 20507 20508@smallexample 20509 -symbol-locate 20510@end smallexample 20511 20512@subsubheading @value{GDBN} Command 20513 20514@samp{gdb_loc} in @code{gdbtk}. 20515 20516@subsubheading Example 20517N.A. 20518 20519 20520@subheading The @code{-symbol-type} Command 20521@findex -symbol-type 20522 20523@subsubheading Synopsis 20524 20525@smallexample 20526 -symbol-type @var{variable} 20527@end smallexample 20528 20529Show type of @var{variable}. 20530 20531@subsubheading @value{GDBN} Command 20532 20533The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has 20534@samp{gdb_obj_variable}. 20535 20536@subsubheading Example 20537N.A. 20538 20539 20540@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 20541@node GDB/MI File Commands 20542@section @sc{gdb/mi} File Commands 20543 20544This section describes the GDB/MI commands to specify executable file names 20545and to read in and obtain symbol table information. 20546 20547@subheading The @code{-file-exec-and-symbols} Command 20548@findex -file-exec-and-symbols 20549 20550@subsubheading Synopsis 20551 20552@smallexample 20553 -file-exec-and-symbols @var{file} 20554@end smallexample 20555 20556Specify the executable file to be debugged. This file is the one from 20557which the symbol table is also read. If no file is specified, the 20558command clears the executable and symbol information. If breakpoints 20559are set when using this command with no arguments, @value{GDBN} will produce 20560error messages. Otherwise, no output is produced, except a completion 20561notification. 20562 20563@subsubheading @value{GDBN} Command 20564 20565The corresponding @value{GDBN} command is @samp{file}. 20566 20567@subsubheading Example 20568 20569@smallexample 20570(gdb) 20571-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 20572^done 20573(gdb) 20574@end smallexample 20575 20576 20577@subheading The @code{-file-exec-file} Command 20578@findex -file-exec-file 20579 20580@subsubheading Synopsis 20581 20582@smallexample 20583 -file-exec-file @var{file} 20584@end smallexample 20585 20586Specify the executable file to be debugged. Unlike 20587@samp{-file-exec-and-symbols}, the symbol table is @emph{not} read 20588from this file. If used without argument, @value{GDBN} clears the information 20589about the executable file. No output is produced, except a completion 20590notification. 20591 20592@subsubheading @value{GDBN} Command 20593 20594The corresponding @value{GDBN} command is @samp{exec-file}. 20595 20596@subsubheading Example 20597 20598@smallexample 20599(gdb) 20600-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 20601^done 20602(gdb) 20603@end smallexample 20604 20605 20606@subheading The @code{-file-list-exec-sections} Command 20607@findex -file-list-exec-sections 20608 20609@subsubheading Synopsis 20610 20611@smallexample 20612 -file-list-exec-sections 20613@end smallexample 20614 20615List the sections of the current executable file. 20616 20617@subsubheading @value{GDBN} Command 20618 20619The @value{GDBN} command @samp{info file} shows, among the rest, the same 20620information as this command. @code{gdbtk} has a corresponding command 20621@samp{gdb_load_info}. 20622 20623@subsubheading Example 20624N.A. 20625 20626 20627@subheading The @code{-file-list-exec-source-file} Command 20628@findex -file-list-exec-source-file 20629 20630@subsubheading Synopsis 20631 20632@smallexample 20633 -file-list-exec-source-file 20634@end smallexample 20635 20636List the line number, the current source file, and the absolute path 20637to the current source file for the current executable. 20638 20639@subsubheading @value{GDBN} Command 20640 20641The @value{GDBN} equivalent is @samp{info source} 20642 20643@subsubheading Example 20644 20645@smallexample 20646(gdb) 20647123-file-list-exec-source-file 20648123^done,line="1",file="foo.c",fullname="/home/bar/foo.c" 20649(gdb) 20650@end smallexample 20651 20652 20653@subheading The @code{-file-list-exec-source-files} Command 20654@findex -file-list-exec-source-files 20655 20656@subsubheading Synopsis 20657 20658@smallexample 20659 -file-list-exec-source-files 20660@end smallexample 20661 20662List the source files for the current executable. 20663 20664It will always output the filename, but only when @value{GDBN} can find 20665the absolute file name of a source file, will it output the fullname. 20666 20667@subsubheading @value{GDBN} Command 20668 20669The @value{GDBN} equivalent is @samp{info sources}. 20670@code{gdbtk} has an analogous command @samp{gdb_listfiles}. 20671 20672@subsubheading Example 20673@smallexample 20674(gdb) 20675-file-list-exec-source-files 20676^done,files=[ 20677@{file=foo.c,fullname=/home/foo.c@}, 20678@{file=/home/bar.c,fullname=/home/bar.c@}, 20679@{file=gdb_could_not_find_fullpath.c@}] 20680(gdb) 20681@end smallexample 20682 20683@subheading The @code{-file-list-shared-libraries} Command 20684@findex -file-list-shared-libraries 20685 20686@subsubheading Synopsis 20687 20688@smallexample 20689 -file-list-shared-libraries 20690@end smallexample 20691 20692List the shared libraries in the program. 20693 20694@subsubheading @value{GDBN} Command 20695 20696The corresponding @value{GDBN} command is @samp{info shared}. 20697 20698@subsubheading Example 20699N.A. 20700 20701 20702@subheading The @code{-file-list-symbol-files} Command 20703@findex -file-list-symbol-files 20704 20705@subsubheading Synopsis 20706 20707@smallexample 20708 -file-list-symbol-files 20709@end smallexample 20710 20711List symbol files. 20712 20713@subsubheading @value{GDBN} Command 20714 20715The corresponding @value{GDBN} command is @samp{info file} (part of it). 20716 20717@subsubheading Example 20718N.A. 20719 20720 20721@subheading The @code{-file-symbol-file} Command 20722@findex -file-symbol-file 20723 20724@subsubheading Synopsis 20725 20726@smallexample 20727 -file-symbol-file @var{file} 20728@end smallexample 20729 20730Read symbol table info from the specified @var{file} argument. When 20731used without arguments, clears @value{GDBN}'s symbol table info. No output is 20732produced, except for a completion notification. 20733 20734@subsubheading @value{GDBN} Command 20735 20736The corresponding @value{GDBN} command is @samp{symbol-file}. 20737 20738@subsubheading Example 20739 20740@smallexample 20741(gdb) 20742-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 20743^done 20744(gdb) 20745@end smallexample 20746 20747@ignore 20748@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 20749@node GDB/MI Memory Overlay Commands 20750@section @sc{gdb/mi} Memory Overlay Commands 20751 20752The memory overlay commands are not implemented. 20753 20754@c @subheading -overlay-auto 20755 20756@c @subheading -overlay-list-mapping-state 20757 20758@c @subheading -overlay-list-overlays 20759 20760@c @subheading -overlay-map 20761 20762@c @subheading -overlay-off 20763 20764@c @subheading -overlay-on 20765 20766@c @subheading -overlay-unmap 20767 20768@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 20769@node GDB/MI Signal Handling Commands 20770@section @sc{gdb/mi} Signal Handling Commands 20771 20772Signal handling commands are not implemented. 20773 20774@c @subheading -signal-handle 20775 20776@c @subheading -signal-list-handle-actions 20777 20778@c @subheading -signal-list-signal-types 20779@end ignore 20780 20781 20782@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 20783@node GDB/MI Target Manipulation 20784@section @sc{gdb/mi} Target Manipulation Commands 20785 20786 20787@subheading The @code{-target-attach} Command 20788@findex -target-attach 20789 20790@subsubheading Synopsis 20791 20792@smallexample 20793 -target-attach @var{pid} | @var{file} 20794@end smallexample 20795 20796Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}. 20797 20798@subsubheading @value{GDBN} Command 20799 20800The corresponding @value{GDBN} command is @samp{attach}. 20801 20802@subsubheading Example 20803N.A. 20804 20805 20806@subheading The @code{-target-compare-sections} Command 20807@findex -target-compare-sections 20808 20809@subsubheading Synopsis 20810 20811@smallexample 20812 -target-compare-sections [ @var{section} ] 20813@end smallexample 20814 20815Compare data of section @var{section} on target to the exec file. 20816Without the argument, all sections are compared. 20817 20818@subsubheading @value{GDBN} Command 20819 20820The @value{GDBN} equivalent is @samp{compare-sections}. 20821 20822@subsubheading Example 20823N.A. 20824 20825 20826@subheading The @code{-target-detach} Command 20827@findex -target-detach 20828 20829@subsubheading Synopsis 20830 20831@smallexample 20832 -target-detach 20833@end smallexample 20834 20835Detach from the remote target which normally resumes its execution. 20836There's no output. 20837 20838@subsubheading @value{GDBN} Command 20839 20840The corresponding @value{GDBN} command is @samp{detach}. 20841 20842@subsubheading Example 20843 20844@smallexample 20845(gdb) 20846-target-detach 20847^done 20848(gdb) 20849@end smallexample 20850 20851 20852@subheading The @code{-target-disconnect} Command 20853@findex -target-disconnect 20854 20855@subsubheading Synopsis 20856 20857@smallexample 20858 -target-disconnect 20859@end smallexample 20860 20861Disconnect from the remote target. There's no output and the target is 20862generally not resumed. 20863 20864@subsubheading @value{GDBN} Command 20865 20866The corresponding @value{GDBN} command is @samp{disconnect}. 20867 20868@subsubheading Example 20869 20870@smallexample 20871(gdb) 20872-target-disconnect 20873^done 20874(gdb) 20875@end smallexample 20876 20877 20878@subheading The @code{-target-download} Command 20879@findex -target-download 20880 20881@subsubheading Synopsis 20882 20883@smallexample 20884 -target-download 20885@end smallexample 20886 20887Loads the executable onto the remote target. 20888It prints out an update message every half second, which includes the fields: 20889 20890@table @samp 20891@item section 20892The name of the section. 20893@item section-sent 20894The size of what has been sent so far for that section. 20895@item section-size 20896The size of the section. 20897@item total-sent 20898The total size of what was sent so far (the current and the previous sections). 20899@item total-size 20900The size of the overall executable to download. 20901@end table 20902 20903@noindent 20904Each message is sent as status record (@pxref{GDB/MI Output Syntax, , 20905@sc{gdb/mi} Output Syntax}). 20906 20907In addition, it prints the name and size of the sections, as they are 20908downloaded. These messages include the following fields: 20909 20910@table @samp 20911@item section 20912The name of the section. 20913@item section-size 20914The size of the section. 20915@item total-size 20916The size of the overall executable to download. 20917@end table 20918 20919@noindent 20920At the end, a summary is printed. 20921 20922@subsubheading @value{GDBN} Command 20923 20924The corresponding @value{GDBN} command is @samp{load}. 20925 20926@subsubheading Example 20927 20928Note: each status message appears on a single line. Here the messages 20929have been broken down so that they can fit onto a page. 20930 20931@smallexample 20932(gdb) 20933-target-download 20934+download,@{section=".text",section-size="6668",total-size="9880"@} 20935+download,@{section=".text",section-sent="512",section-size="6668", 20936total-sent="512",total-size="9880"@} 20937+download,@{section=".text",section-sent="1024",section-size="6668", 20938total-sent="1024",total-size="9880"@} 20939+download,@{section=".text",section-sent="1536",section-size="6668", 20940total-sent="1536",total-size="9880"@} 20941+download,@{section=".text",section-sent="2048",section-size="6668", 20942total-sent="2048",total-size="9880"@} 20943+download,@{section=".text",section-sent="2560",section-size="6668", 20944total-sent="2560",total-size="9880"@} 20945+download,@{section=".text",section-sent="3072",section-size="6668", 20946total-sent="3072",total-size="9880"@} 20947+download,@{section=".text",section-sent="3584",section-size="6668", 20948total-sent="3584",total-size="9880"@} 20949+download,@{section=".text",section-sent="4096",section-size="6668", 20950total-sent="4096",total-size="9880"@} 20951+download,@{section=".text",section-sent="4608",section-size="6668", 20952total-sent="4608",total-size="9880"@} 20953+download,@{section=".text",section-sent="5120",section-size="6668", 20954total-sent="5120",total-size="9880"@} 20955+download,@{section=".text",section-sent="5632",section-size="6668", 20956total-sent="5632",total-size="9880"@} 20957+download,@{section=".text",section-sent="6144",section-size="6668", 20958total-sent="6144",total-size="9880"@} 20959+download,@{section=".text",section-sent="6656",section-size="6668", 20960total-sent="6656",total-size="9880"@} 20961+download,@{section=".init",section-size="28",total-size="9880"@} 20962+download,@{section=".fini",section-size="28",total-size="9880"@} 20963+download,@{section=".data",section-size="3156",total-size="9880"@} 20964+download,@{section=".data",section-sent="512",section-size="3156", 20965total-sent="7236",total-size="9880"@} 20966+download,@{section=".data",section-sent="1024",section-size="3156", 20967total-sent="7748",total-size="9880"@} 20968+download,@{section=".data",section-sent="1536",section-size="3156", 20969total-sent="8260",total-size="9880"@} 20970+download,@{section=".data",section-sent="2048",section-size="3156", 20971total-sent="8772",total-size="9880"@} 20972+download,@{section=".data",section-sent="2560",section-size="3156", 20973total-sent="9284",total-size="9880"@} 20974+download,@{section=".data",section-sent="3072",section-size="3156", 20975total-sent="9796",total-size="9880"@} 20976^done,address="0x10004",load-size="9880",transfer-rate="6586", 20977write-rate="429" 20978(gdb) 20979@end smallexample 20980 20981 20982@subheading The @code{-target-exec-status} Command 20983@findex -target-exec-status 20984 20985@subsubheading Synopsis 20986 20987@smallexample 20988 -target-exec-status 20989@end smallexample 20990 20991Provide information on the state of the target (whether it is running or 20992not, for instance). 20993 20994@subsubheading @value{GDBN} Command 20995 20996There's no equivalent @value{GDBN} command. 20997 20998@subsubheading Example 20999N.A. 21000 21001 21002@subheading The @code{-target-list-available-targets} Command 21003@findex -target-list-available-targets 21004 21005@subsubheading Synopsis 21006 21007@smallexample 21008 -target-list-available-targets 21009@end smallexample 21010 21011List the possible targets to connect to. 21012 21013@subsubheading @value{GDBN} Command 21014 21015The corresponding @value{GDBN} command is @samp{help target}. 21016 21017@subsubheading Example 21018N.A. 21019 21020 21021@subheading The @code{-target-list-current-targets} Command 21022@findex -target-list-current-targets 21023 21024@subsubheading Synopsis 21025 21026@smallexample 21027 -target-list-current-targets 21028@end smallexample 21029 21030Describe the current target. 21031 21032@subsubheading @value{GDBN} Command 21033 21034The corresponding information is printed by @samp{info file} (among 21035other things). 21036 21037@subsubheading Example 21038N.A. 21039 21040 21041@subheading The @code{-target-list-parameters} Command 21042@findex -target-list-parameters 21043 21044@subsubheading Synopsis 21045 21046@smallexample 21047 -target-list-parameters 21048@end smallexample 21049 21050@c ???? 21051 21052@subsubheading @value{GDBN} Command 21053 21054No equivalent. 21055 21056@subsubheading Example 21057N.A. 21058 21059 21060@subheading The @code{-target-select} Command 21061@findex -target-select 21062 21063@subsubheading Synopsis 21064 21065@smallexample 21066 -target-select @var{type} @var{parameters @dots{}} 21067@end smallexample 21068 21069Connect @value{GDBN} to the remote target. This command takes two args: 21070 21071@table @samp 21072@item @var{type} 21073The type of target, for instance @samp{async}, @samp{remote}, etc. 21074@item @var{parameters} 21075Device names, host names and the like. @xref{Target Commands, , 21076Commands for Managing Targets}, for more details. 21077@end table 21078 21079The output is a connection notification, followed by the address at 21080which the target program is, in the following form: 21081 21082@smallexample 21083^connected,addr="@var{address}",func="@var{function name}", 21084 args=[@var{arg list}] 21085@end smallexample 21086 21087@subsubheading @value{GDBN} Command 21088 21089The corresponding @value{GDBN} command is @samp{target}. 21090 21091@subsubheading Example 21092 21093@smallexample 21094(gdb) 21095-target-select async /dev/ttya 21096^connected,addr="0xfe00a300",func="??",args=[] 21097(gdb) 21098@end smallexample 21099 21100@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 21101@node GDB/MI Miscellaneous Commands 21102@section Miscellaneous @sc{gdb/mi} Commands 21103 21104@c @subheading -gdb-complete 21105 21106@subheading The @code{-gdb-exit} Command 21107@findex -gdb-exit 21108 21109@subsubheading Synopsis 21110 21111@smallexample 21112 -gdb-exit 21113@end smallexample 21114 21115Exit @value{GDBN} immediately. 21116 21117@subsubheading @value{GDBN} Command 21118 21119Approximately corresponds to @samp{quit}. 21120 21121@subsubheading Example 21122 21123@smallexample 21124(gdb) 21125-gdb-exit 21126^exit 21127@end smallexample 21128 21129 21130@subheading The @code{-exec-abort} Command 21131@findex -exec-abort 21132 21133@subsubheading Synopsis 21134 21135@smallexample 21136 -exec-abort 21137@end smallexample 21138 21139Kill the inferior running program. 21140 21141@subsubheading @value{GDBN} Command 21142 21143The corresponding @value{GDBN} command is @samp{kill}. 21144 21145@subsubheading Example 21146N.A. 21147 21148 21149@subheading The @code{-gdb-set} Command 21150@findex -gdb-set 21151 21152@subsubheading Synopsis 21153 21154@smallexample 21155 -gdb-set 21156@end smallexample 21157 21158Set an internal @value{GDBN} variable. 21159@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ????? 21160 21161@subsubheading @value{GDBN} Command 21162 21163The corresponding @value{GDBN} command is @samp{set}. 21164 21165@subsubheading Example 21166 21167@smallexample 21168(gdb) 21169-gdb-set $foo=3 21170^done 21171(gdb) 21172@end smallexample 21173 21174 21175@subheading The @code{-gdb-show} Command 21176@findex -gdb-show 21177 21178@subsubheading Synopsis 21179 21180@smallexample 21181 -gdb-show 21182@end smallexample 21183 21184Show the current value of a @value{GDBN} variable. 21185 21186@subsubheading @value{GDBN} Command 21187 21188The corresponding @value{GDBN} command is @samp{show}. 21189 21190@subsubheading Example 21191 21192@smallexample 21193(gdb) 21194-gdb-show annotate 21195^done,value="0" 21196(gdb) 21197@end smallexample 21198 21199@c @subheading -gdb-source 21200 21201 21202@subheading The @code{-gdb-version} Command 21203@findex -gdb-version 21204 21205@subsubheading Synopsis 21206 21207@smallexample 21208 -gdb-version 21209@end smallexample 21210 21211Show version information for @value{GDBN}. Used mostly in testing. 21212 21213@subsubheading @value{GDBN} Command 21214 21215The @value{GDBN} equivalent is @samp{show version}. @value{GDBN} by 21216default shows this information when you start an interactive session. 21217 21218@subsubheading Example 21219 21220@c This example modifies the actual output from GDB to avoid overfull 21221@c box in TeX. 21222@smallexample 21223(gdb) 21224-gdb-version 21225~GNU gdb 5.2.1 21226~Copyright 2000 Free Software Foundation, Inc. 21227~GDB is free software, covered by the GNU General Public License, and 21228~you are welcome to change it and/or distribute copies of it under 21229~ certain conditions. 21230~Type "show copying" to see the conditions. 21231~There is absolutely no warranty for GDB. Type "show warranty" for 21232~ details. 21233~This GDB was configured as 21234 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". 21235^done 21236(gdb) 21237@end smallexample 21238 21239@subheading The @code{-interpreter-exec} Command 21240@findex -interpreter-exec 21241 21242@subheading Synopsis 21243 21244@smallexample 21245-interpreter-exec @var{interpreter} @var{command} 21246@end smallexample 21247@anchor{-interpreter-exec} 21248 21249Execute the specified @var{command} in the given @var{interpreter}. 21250 21251@subheading @value{GDBN} Command 21252 21253The corresponding @value{GDBN} command is @samp{interpreter-exec}. 21254 21255@subheading Example 21256 21257@smallexample 21258(gdb) 21259-interpreter-exec console "break main" 21260&"During symbol reading, couldn't parse type; debugger out of date?.\n" 21261&"During symbol reading, bad structure-type format.\n" 21262~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" 21263^done 21264(gdb) 21265@end smallexample 21266 21267@subheading The @code{-inferior-tty-set} Command 21268@findex -inferior-tty-set 21269 21270@subheading Synopsis 21271 21272@smallexample 21273-inferior-tty-set /dev/pts/1 21274@end smallexample 21275 21276Set terminal for future runs of the program being debugged. 21277 21278@subheading @value{GDBN} Command 21279 21280The corresponding @value{GDBN} command is @samp{set inferior-tty} /dev/pts/1. 21281 21282@subheading Example 21283 21284@smallexample 21285(gdb) 21286-inferior-tty-set /dev/pts/1 21287^done 21288(gdb) 21289@end smallexample 21290 21291@subheading The @code{-inferior-tty-show} Command 21292@findex -inferior-tty-show 21293 21294@subheading Synopsis 21295 21296@smallexample 21297-inferior-tty-show 21298@end smallexample 21299 21300Show terminal for future runs of program being debugged. 21301 21302@subheading @value{GDBN} Command 21303 21304The corresponding @value{GDBN} command is @samp{show inferior-tty}. 21305 21306@subheading Example 21307 21308@smallexample 21309(gdb) 21310-inferior-tty-set /dev/pts/1 21311^done 21312(gdb) 21313-inferior-tty-show 21314^done,inferior_tty_terminal="/dev/pts/1" 21315(gdb) 21316@end smallexample 21317 21318@subheading The @code{-enable-timings} Command 21319@findex -enable-timings 21320 21321@subheading Synopsis 21322 21323@smallexample 21324-enable-timings [yes | no] 21325@end smallexample 21326 21327Toggle the printing of the wallclock, user and system times for an MI 21328command as a field in its output. This command is to help frontend 21329developers optimize the performance of their code. No argument is 21330equivalent to @samp{yes}. 21331 21332@subheading @value{GDBN} Command 21333 21334No equivalent. 21335 21336@subheading Example 21337 21338@smallexample 21339(gdb) 21340-enable-timings 21341^done 21342(gdb) 21343-break-insert main 21344^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 21345addr="0x080484ed",func="main",file="myprog.c", 21346fullname="/home/nickrob/myprog.c",line="73",times="0"@}, 21347time=@{wallclock="0.05185",user="0.00800",system="0.00000"@} 21348(gdb) 21349-enable-timings no 21350^done 21351(gdb) 21352-exec-run 21353^running 21354(gdb) 21355*stopped,reason="breakpoint-hit",bkptno="1",thread-id="0", 21356frame=@{addr="0x080484ed",func="main",args=[@{name="argc",value="1"@}, 21357@{name="argv",value="0xbfb60364"@}],file="myprog.c", 21358fullname="/home/nickrob/myprog.c",line="73"@} 21359(gdb) 21360@end smallexample 21361 21362@node Annotations 21363@chapter @value{GDBN} Annotations 21364 21365This chapter describes annotations in @value{GDBN}. Annotations were 21366designed to interface @value{GDBN} to graphical user interfaces or other 21367similar programs which want to interact with @value{GDBN} at a 21368relatively high level. 21369 21370The annotation mechanism has largely been superseded by @sc{gdb/mi} 21371(@pxref{GDB/MI}). 21372 21373@ignore 21374This is Edition @value{EDITION}, @value{DATE}. 21375@end ignore 21376 21377@menu 21378* Annotations Overview:: What annotations are; the general syntax. 21379* Server Prefix:: Issuing a command without affecting user state. 21380* Prompting:: Annotations marking @value{GDBN}'s need for input. 21381* Errors:: Annotations for error messages. 21382* Invalidation:: Some annotations describe things now invalid. 21383* Annotations for Running:: 21384 Whether the program is running, how it stopped, etc. 21385* Source Annotations:: Annotations describing source code. 21386@end menu 21387 21388@node Annotations Overview 21389@section What is an Annotation? 21390@cindex annotations 21391 21392Annotations start with a newline character, two @samp{control-z} 21393characters, and the name of the annotation. If there is no additional 21394information associated with this annotation, the name of the annotation 21395is followed immediately by a newline. If there is additional 21396information, the name of the annotation is followed by a space, the 21397additional information, and a newline. The additional information 21398cannot contain newline characters. 21399 21400Any output not beginning with a newline and two @samp{control-z} 21401characters denotes literal output from @value{GDBN}. Currently there is 21402no need for @value{GDBN} to output a newline followed by two 21403@samp{control-z} characters, but if there was such a need, the 21404annotations could be extended with an @samp{escape} annotation which 21405means those three characters as output. 21406 21407The annotation @var{level}, which is specified using the 21408@option{--annotate} command line option (@pxref{Mode Options}), controls 21409how much information @value{GDBN} prints together with its prompt, 21410values of expressions, source lines, and other types of output. Level 0 21411is for no annotations, level 1 is for use when @value{GDBN} is run as a 21412subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable 21413for programs that control @value{GDBN}, and level 2 annotations have 21414been made obsolete (@pxref{Limitations, , Limitations of the Annotation 21415Interface, annotate, GDB's Obsolete Annotations}). 21416 21417@table @code 21418@kindex set annotate 21419@item set annotate @var{level} 21420The @value{GDBN} command @code{set annotate} sets the level of 21421annotations to the specified @var{level}. 21422 21423@item show annotate 21424@kindex show annotate 21425Show the current annotation level. 21426@end table 21427 21428This chapter describes level 3 annotations. 21429 21430A simple example of starting up @value{GDBN} with annotations is: 21431 21432@smallexample 21433$ @kbd{gdb --annotate=3} 21434GNU gdb 6.0 21435Copyright 2003 Free Software Foundation, Inc. 21436GDB is free software, covered by the GNU General Public License, 21437and you are welcome to change it and/or distribute copies of it 21438under certain conditions. 21439Type "show copying" to see the conditions. 21440There is absolutely no warranty for GDB. Type "show warranty" 21441for details. 21442This GDB was configured as "i386-pc-linux-gnu" 21443 21444^Z^Zpre-prompt 21445(@value{GDBP}) 21446^Z^Zprompt 21447@kbd{quit} 21448 21449^Z^Zpost-prompt 21450$ 21451@end smallexample 21452 21453Here @samp{quit} is input to @value{GDBN}; the rest is output from 21454@value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z} 21455denotes a @samp{control-z} character) are annotations; the rest is 21456output from @value{GDBN}. 21457 21458@node Server Prefix 21459@section The Server Prefix 21460@cindex server prefix 21461 21462If you prefix a command with @samp{server } then it will not affect 21463the command history, nor will it affect @value{GDBN}'s notion of which 21464command to repeat if @key{RET} is pressed on a line by itself. This 21465means that commands can be run behind a user's back by a front-end in 21466a transparent manner. 21467 21468The server prefix does not affect the recording of values into the value 21469history; to print a value without recording it into the value history, 21470use the @code{output} command instead of the @code{print} command. 21471 21472@node Prompting 21473@section Annotation for @value{GDBN} Input 21474 21475@cindex annotations for prompts 21476When @value{GDBN} prompts for input, it annotates this fact so it is possible 21477to know when to send output, when the output from a given command is 21478over, etc. 21479 21480Different kinds of input each have a different @dfn{input type}. Each 21481input type has three annotations: a @code{pre-} annotation, which 21482denotes the beginning of any prompt which is being output, a plain 21483annotation, which denotes the end of the prompt, and then a @code{post-} 21484annotation which denotes the end of any echo which may (or may not) be 21485associated with the input. For example, the @code{prompt} input type 21486features the following annotations: 21487 21488@smallexample 21489^Z^Zpre-prompt 21490^Z^Zprompt 21491^Z^Zpost-prompt 21492@end smallexample 21493 21494The input types are 21495 21496@table @code 21497@findex pre-prompt annotation 21498@findex prompt annotation 21499@findex post-prompt annotation 21500@item prompt 21501When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt). 21502 21503@findex pre-commands annotation 21504@findex commands annotation 21505@findex post-commands annotation 21506@item commands 21507When @value{GDBN} prompts for a set of commands, like in the @code{commands} 21508command. The annotations are repeated for each command which is input. 21509 21510@findex pre-overload-choice annotation 21511@findex overload-choice annotation 21512@findex post-overload-choice annotation 21513@item overload-choice 21514When @value{GDBN} wants the user to select between various overloaded functions. 21515 21516@findex pre-query annotation 21517@findex query annotation 21518@findex post-query annotation 21519@item query 21520When @value{GDBN} wants the user to confirm a potentially dangerous operation. 21521 21522@findex pre-prompt-for-continue annotation 21523@findex prompt-for-continue annotation 21524@findex post-prompt-for-continue annotation 21525@item prompt-for-continue 21526When @value{GDBN} is asking the user to press return to continue. Note: Don't 21527expect this to work well; instead use @code{set height 0} to disable 21528prompting. This is because the counting of lines is buggy in the 21529presence of annotations. 21530@end table 21531 21532@node Errors 21533@section Errors 21534@cindex annotations for errors, warnings and interrupts 21535 21536@findex quit annotation 21537@smallexample 21538^Z^Zquit 21539@end smallexample 21540 21541This annotation occurs right before @value{GDBN} responds to an interrupt. 21542 21543@findex error annotation 21544@smallexample 21545^Z^Zerror 21546@end smallexample 21547 21548This annotation occurs right before @value{GDBN} responds to an error. 21549 21550Quit and error annotations indicate that any annotations which @value{GDBN} was 21551in the middle of may end abruptly. For example, if a 21552@code{value-history-begin} annotation is followed by a @code{error}, one 21553cannot expect to receive the matching @code{value-history-end}. One 21554cannot expect not to receive it either, however; an error annotation 21555does not necessarily mean that @value{GDBN} is immediately returning all the way 21556to the top level. 21557 21558@findex error-begin annotation 21559A quit or error annotation may be preceded by 21560 21561@smallexample 21562^Z^Zerror-begin 21563@end smallexample 21564 21565Any output between that and the quit or error annotation is the error 21566message. 21567 21568Warning messages are not yet annotated. 21569@c If we want to change that, need to fix warning(), type_error(), 21570@c range_error(), and possibly other places. 21571 21572@node Invalidation 21573@section Invalidation Notices 21574 21575@cindex annotations for invalidation messages 21576The following annotations say that certain pieces of state may have 21577changed. 21578 21579@table @code 21580@findex frames-invalid annotation 21581@item ^Z^Zframes-invalid 21582 21583The frames (for example, output from the @code{backtrace} command) may 21584have changed. 21585 21586@findex breakpoints-invalid annotation 21587@item ^Z^Zbreakpoints-invalid 21588 21589The breakpoints may have changed. For example, the user just added or 21590deleted a breakpoint. 21591@end table 21592 21593@node Annotations for Running 21594@section Running the Program 21595@cindex annotations for running programs 21596 21597@findex starting annotation 21598@findex stopping annotation 21599When the program starts executing due to a @value{GDBN} command such as 21600@code{step} or @code{continue}, 21601 21602@smallexample 21603^Z^Zstarting 21604@end smallexample 21605 21606is output. When the program stops, 21607 21608@smallexample 21609^Z^Zstopped 21610@end smallexample 21611 21612is output. Before the @code{stopped} annotation, a variety of 21613annotations describe how the program stopped. 21614 21615@table @code 21616@findex exited annotation 21617@item ^Z^Zexited @var{exit-status} 21618The program exited, and @var{exit-status} is the exit status (zero for 21619successful exit, otherwise nonzero). 21620 21621@findex signalled annotation 21622@findex signal-name annotation 21623@findex signal-name-end annotation 21624@findex signal-string annotation 21625@findex signal-string-end annotation 21626@item ^Z^Zsignalled 21627The program exited with a signal. After the @code{^Z^Zsignalled}, the 21628annotation continues: 21629 21630@smallexample 21631@var{intro-text} 21632^Z^Zsignal-name 21633@var{name} 21634^Z^Zsignal-name-end 21635@var{middle-text} 21636^Z^Zsignal-string 21637@var{string} 21638^Z^Zsignal-string-end 21639@var{end-text} 21640@end smallexample 21641 21642@noindent 21643where @var{name} is the name of the signal, such as @code{SIGILL} or 21644@code{SIGSEGV}, and @var{string} is the explanation of the signal, such 21645as @code{Illegal Instruction} or @code{Segmentation fault}. 21646@var{intro-text}, @var{middle-text}, and @var{end-text} are for the 21647user's benefit and have no particular format. 21648 21649@findex signal annotation 21650@item ^Z^Zsignal 21651The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is 21652just saying that the program received the signal, not that it was 21653terminated with it. 21654 21655@findex breakpoint annotation 21656@item ^Z^Zbreakpoint @var{number} 21657The program hit breakpoint number @var{number}. 21658 21659@findex watchpoint annotation 21660@item ^Z^Zwatchpoint @var{number} 21661The program hit watchpoint number @var{number}. 21662@end table 21663 21664@node Source Annotations 21665@section Displaying Source 21666@cindex annotations for source display 21667 21668@findex source annotation 21669The following annotation is used instead of displaying source code: 21670 21671@smallexample 21672^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr} 21673@end smallexample 21674 21675where @var{filename} is an absolute file name indicating which source 21676file, @var{line} is the line number within that file (where 1 is the 21677first line in the file), @var{character} is the character position 21678within the file (where 0 is the first character in the file) (for most 21679debug formats this will necessarily point to the beginning of a line), 21680@var{middle} is @samp{middle} if @var{addr} is in the middle of the 21681line, or @samp{beg} if @var{addr} is at the beginning of the line, and 21682@var{addr} is the address in the target program associated with the 21683source which is being displayed. @var{addr} is in the form @samp{0x} 21684followed by one or more lowercase hex digits (note that this does not 21685depend on the language). 21686 21687@node GDB Bugs 21688@chapter Reporting Bugs in @value{GDBN} 21689@cindex bugs in @value{GDBN} 21690@cindex reporting bugs in @value{GDBN} 21691 21692Your bug reports play an essential role in making @value{GDBN} reliable. 21693 21694Reporting a bug may help you by bringing a solution to your problem, or it 21695may not. But in any case the principal function of a bug report is to help 21696the entire community by making the next version of @value{GDBN} work better. Bug 21697reports are your contribution to the maintenance of @value{GDBN}. 21698 21699In order for a bug report to serve its purpose, you must include the 21700information that enables us to fix the bug. 21701 21702@menu 21703* Bug Criteria:: Have you found a bug? 21704* Bug Reporting:: How to report bugs 21705@end menu 21706 21707@node Bug Criteria 21708@section Have You Found a Bug? 21709@cindex bug criteria 21710 21711If you are not sure whether you have found a bug, here are some guidelines: 21712 21713@itemize @bullet 21714@cindex fatal signal 21715@cindex debugger crash 21716@cindex crash of debugger 21717@item 21718If the debugger gets a fatal signal, for any input whatever, that is a 21719@value{GDBN} bug. Reliable debuggers never crash. 21720 21721@cindex error on valid input 21722@item 21723If @value{GDBN} produces an error message for valid input, that is a 21724bug. (Note that if you're cross debugging, the problem may also be 21725somewhere in the connection to the target.) 21726 21727@cindex invalid input 21728@item 21729If @value{GDBN} does not produce an error message for invalid input, 21730that is a bug. However, you should note that your idea of 21731``invalid input'' might be our idea of ``an extension'' or ``support 21732for traditional practice''. 21733 21734@item 21735If you are an experienced user of debugging tools, your suggestions 21736for improvement of @value{GDBN} are welcome in any case. 21737@end itemize 21738 21739@node Bug Reporting 21740@section How to Report Bugs 21741@cindex bug reports 21742@cindex @value{GDBN} bugs, reporting 21743 21744A number of companies and individuals offer support for @sc{gnu} products. 21745If you obtained @value{GDBN} from a support organization, we recommend you 21746contact that organization first. 21747 21748You can find contact information for many support companies and 21749individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs 21750distribution. 21751@c should add a web page ref... 21752 21753In any event, we also recommend that you submit bug reports for 21754@value{GDBN}. The preferred method is to submit them directly using 21755@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web 21756page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can 21757be used. 21758 21759@strong{Do not send bug reports to @samp{info-gdb}, or to 21760@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do 21761not want to receive bug reports. Those that do have arranged to receive 21762@samp{bug-gdb}. 21763 21764The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which 21765serves as a repeater. The mailing list and the newsgroup carry exactly 21766the same messages. Often people think of posting bug reports to the 21767newsgroup instead of mailing them. This appears to work, but it has one 21768problem which can be crucial: a newsgroup posting often lacks a mail 21769path back to the sender. Thus, if we need to ask for more information, 21770we may be unable to reach you. For this reason, it is better to send 21771bug reports to the mailing list. 21772 21773The fundamental principle of reporting bugs usefully is this: 21774@strong{report all the facts}. If you are not sure whether to state a 21775fact or leave it out, state it! 21776 21777Often people omit facts because they think they know what causes the 21778problem and assume that some details do not matter. Thus, you might 21779assume that the name of the variable you use in an example does not matter. 21780Well, probably it does not, but one cannot be sure. Perhaps the bug is a 21781stray memory reference which happens to fetch from the location where that 21782name is stored in memory; perhaps, if the name were different, the contents 21783of that location would fool the debugger into doing the right thing despite 21784the bug. Play it safe and give a specific, complete example. That is the 21785easiest thing for you to do, and the most helpful. 21786 21787Keep in mind that the purpose of a bug report is to enable us to fix the 21788bug. It may be that the bug has been reported previously, but neither 21789you nor we can know that unless your bug report is complete and 21790self-contained. 21791 21792Sometimes people give a few sketchy facts and ask, ``Does this ring a 21793bell?'' Those bug reports are useless, and we urge everyone to 21794@emph{refuse to respond to them} except to chide the sender to report 21795bugs properly. 21796 21797To enable us to fix the bug, you should include all these things: 21798 21799@itemize @bullet 21800@item 21801The version of @value{GDBN}. @value{GDBN} announces it if you start 21802with no arguments; you can also print it at any time using @code{show 21803version}. 21804 21805Without this, we will not know whether there is any point in looking for 21806the bug in the current version of @value{GDBN}. 21807 21808@item 21809The type of machine you are using, and the operating system name and 21810version number. 21811 21812@item 21813What compiler (and its version) was used to compile @value{GDBN}---e.g.@: 21814``@value{GCC}--2.8.1''. 21815 21816@item 21817What compiler (and its version) was used to compile the program you are 21818debugging---e.g.@: ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP 21819C Compiler''. For @value{NGCC}, you can say @kbd{@value{GCC} --version} 21820to get this information; for other compilers, see the documentation for 21821those compilers. 21822 21823@item 21824The command arguments you gave the compiler to compile your example and 21825observe the bug. For example, did you use @samp{-O}? To guarantee 21826you will not omit something important, list them all. A copy of the 21827Makefile (or the output from make) is sufficient. 21828 21829If we were to try to guess the arguments, we would probably guess wrong 21830and then we might not encounter the bug. 21831 21832@item 21833A complete input script, and all necessary source files, that will 21834reproduce the bug. 21835 21836@item 21837A description of what behavior you observe that you believe is 21838incorrect. For example, ``It gets a fatal signal.'' 21839 21840Of course, if the bug is that @value{GDBN} gets a fatal signal, then we 21841will certainly notice it. But if the bug is incorrect output, we might 21842not notice unless it is glaringly wrong. You might as well not give us 21843a chance to make a mistake. 21844 21845Even if the problem you experience is a fatal signal, you should still 21846say so explicitly. Suppose something strange is going on, such as, your 21847copy of @value{GDBN} is out of synch, or you have encountered a bug in 21848the C library on your system. (This has happened!) Your copy might 21849crash and ours would not. If you told us to expect a crash, then when 21850ours fails to crash, we would know that the bug was not happening for 21851us. If you had not told us to expect a crash, then we would not be able 21852to draw any conclusion from our observations. 21853 21854@pindex script 21855@cindex recording a session script 21856To collect all this information, you can use a session recording program 21857such as @command{script}, which is available on many Unix systems. 21858Just run your @value{GDBN} session inside @command{script} and then 21859include the @file{typescript} file with your bug report. 21860 21861Another way to record a @value{GDBN} session is to run @value{GDBN} 21862inside Emacs and then save the entire buffer to a file. 21863 21864@item 21865If you wish to suggest changes to the @value{GDBN} source, send us context 21866diffs. If you even discuss something in the @value{GDBN} source, refer to 21867it by context, not by line number. 21868 21869The line numbers in our development sources will not match those in your 21870sources. Your line numbers would convey no useful information to us. 21871 21872@end itemize 21873 21874Here are some things that are not necessary: 21875 21876@itemize @bullet 21877@item 21878A description of the envelope of the bug. 21879 21880Often people who encounter a bug spend a lot of time investigating 21881which changes to the input file will make the bug go away and which 21882changes will not affect it. 21883 21884This is often time consuming and not very useful, because the way we 21885will find the bug is by running a single example under the debugger 21886with breakpoints, not by pure deduction from a series of examples. 21887We recommend that you save your time for something else. 21888 21889Of course, if you can find a simpler example to report @emph{instead} 21890of the original one, that is a convenience for us. Errors in the 21891output will be easier to spot, running under the debugger will take 21892less time, and so on. 21893 21894However, simplification is not vital; if you do not want to do this, 21895report the bug anyway and send us the entire test case you used. 21896 21897@item 21898A patch for the bug. 21899 21900A patch for the bug does help us if it is a good one. But do not omit 21901the necessary information, such as the test case, on the assumption that 21902a patch is all we need. We might see problems with your patch and decide 21903to fix the problem another way, or we might not understand it at all. 21904 21905Sometimes with a program as complicated as @value{GDBN} it is very hard to 21906construct an example that will make the program follow a certain path 21907through the code. If you do not send us the example, we will not be able 21908to construct one, so we will not be able to verify that the bug is fixed. 21909 21910And if we cannot understand what bug you are trying to fix, or why your 21911patch should be an improvement, we will not install it. A test case will 21912help us to understand. 21913 21914@item 21915A guess about what the bug is or what it depends on. 21916 21917Such guesses are usually wrong. Even we cannot guess right about such 21918things without first using the debugger to find the facts. 21919@end itemize 21920 21921@c The readline documentation is distributed with the readline code 21922@c and consists of the two following files: 21923@c rluser.texinfo 21924@c inc-hist.texinfo 21925@c Use -I with makeinfo to point to the appropriate directory, 21926@c environment var TEXINPUTS with TeX. 21927@include rluser.texi 21928@include inc-hist.texinfo 21929 21930 21931@node Formatting Documentation 21932@appendix Formatting Documentation 21933 21934@cindex @value{GDBN} reference card 21935@cindex reference card 21936The @value{GDBN} 4 release includes an already-formatted reference card, ready 21937for printing with PostScript or Ghostscript, in the @file{gdb} 21938subdirectory of the main source directory@footnote{In 21939@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN} 21940release.}. If you can use PostScript or Ghostscript with your printer, 21941you can print the reference card immediately with @file{refcard.ps}. 21942 21943The release also includes the source for the reference card. You 21944can format it, using @TeX{}, by typing: 21945 21946@smallexample 21947make refcard.dvi 21948@end smallexample 21949 21950The @value{GDBN} reference card is designed to print in @dfn{landscape} 21951mode on US ``letter'' size paper; 21952that is, on a sheet 11 inches wide by 8.5 inches 21953high. You will need to specify this form of printing as an option to 21954your @sc{dvi} output program. 21955 21956@cindex documentation 21957 21958All the documentation for @value{GDBN} comes as part of the machine-readable 21959distribution. The documentation is written in Texinfo format, which is 21960a documentation system that uses a single source file to produce both 21961on-line information and a printed manual. You can use one of the Info 21962formatting commands to create the on-line version of the documentation 21963and @TeX{} (or @code{texi2roff}) to typeset the printed version. 21964 21965@value{GDBN} includes an already formatted copy of the on-line Info 21966version of this manual in the @file{gdb} subdirectory. The main Info 21967file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to 21968subordinate files matching @samp{gdb.info*} in the same directory. If 21969necessary, you can print out these files, or read them with any editor; 21970but they are easier to read using the @code{info} subsystem in @sc{gnu} 21971Emacs or the standalone @code{info} program, available as part of the 21972@sc{gnu} Texinfo distribution. 21973 21974If you want to format these Info files yourself, you need one of the 21975Info formatting programs, such as @code{texinfo-format-buffer} or 21976@code{makeinfo}. 21977 21978If you have @code{makeinfo} installed, and are in the top level 21979@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of 21980version @value{GDBVN}), you can make the Info file by typing: 21981 21982@smallexample 21983cd gdb 21984make gdb.info 21985@end smallexample 21986 21987If you want to typeset and print copies of this manual, you need @TeX{}, 21988a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the 21989Texinfo definitions file. 21990 21991@TeX{} is a typesetting program; it does not print files directly, but 21992produces output files called @sc{dvi} files. To print a typeset 21993document, you need a program to print @sc{dvi} files. If your system 21994has @TeX{} installed, chances are it has such a program. The precise 21995command to use depends on your system; @kbd{lpr -d} is common; another 21996(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may 21997require a file name without any extension or a @samp{.dvi} extension. 21998 21999@TeX{} also requires a macro definitions file called 22000@file{texinfo.tex}. This file tells @TeX{} how to typeset a document 22001written in Texinfo format. On its own, @TeX{} cannot either read or 22002typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB 22003and is located in the @file{gdb-@var{version-number}/texinfo} 22004directory. 22005 22006If you have @TeX{} and a @sc{dvi} printer program installed, you can 22007typeset and print this manual. First switch to the @file{gdb} 22008subdirectory of the main source directory (for example, to 22009@file{gdb-@value{GDBVN}/gdb}) and type: 22010 22011@smallexample 22012make gdb.dvi 22013@end smallexample 22014 22015Then give @file{gdb.dvi} to your @sc{dvi} printing program. 22016 22017@node Installing GDB 22018@appendix Installing @value{GDBN} 22019@cindex installation 22020 22021@menu 22022* Requirements:: Requirements for building @value{GDBN} 22023* Running Configure:: Invoking the @value{GDBN} @file{configure} script 22024* Separate Objdir:: Compiling @value{GDBN} in another directory 22025* Config Names:: Specifying names for hosts and targets 22026* Configure Options:: Summary of options for configure 22027@end menu 22028 22029@node Requirements 22030@section Requirements for Building @value{GDBN} 22031@cindex building @value{GDBN}, requirements for 22032 22033Building @value{GDBN} requires various tools and packages to be available. 22034Other packages will be used only if they are found. 22035 22036@heading Tools/Packages Necessary for Building @value{GDBN} 22037@table @asis 22038@item ISO C90 compiler 22039@value{GDBN} is written in ISO C90. It should be buildable with any 22040working C90 compiler, e.g.@: GCC. 22041 22042@end table 22043 22044@heading Tools/Packages Optional for Building @value{GDBN} 22045@table @asis 22046@item Expat 22047@anchor{Expat} 22048@value{GDBN} can use the Expat XML parsing library. This library may be 22049included with your operating system distribution; if it is not, you 22050can get the latest version from @url{http://expat.sourceforge.net}. 22051The @file{configure} script will search for this library in several 22052standard locations; if it is installed in an unusual path, you can 22053use the @option{--with-libexpat-prefix} option to specify its location. 22054 22055Expat is used for remote protocol memory maps (@pxref{Memory Map Format}) 22056and for target descriptions (@pxref{Target Descriptions}). 22057 22058@end table 22059 22060@node Running Configure 22061@section Invoking the @value{GDBN} @file{configure} Script 22062@cindex configuring @value{GDBN} 22063@value{GDBN} comes with a @file{configure} script that automates the process 22064of preparing @value{GDBN} for installation; you can then use @code{make} to 22065build the @code{gdb} program. 22066@iftex 22067@c irrelevant in info file; it's as current as the code it lives with. 22068@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN}, 22069look at the @file{README} file in the sources; we may have improved the 22070installation procedures since publishing this manual.} 22071@end iftex 22072 22073The @value{GDBN} distribution includes all the source code you need for 22074@value{GDBN} in a single directory, whose name is usually composed by 22075appending the version number to @samp{gdb}. 22076 22077For example, the @value{GDBN} version @value{GDBVN} distribution is in the 22078@file{gdb-@value{GDBVN}} directory. That directory contains: 22079 22080@table @code 22081@item gdb-@value{GDBVN}/configure @r{(and supporting files)} 22082script for configuring @value{GDBN} and all its supporting libraries 22083 22084@item gdb-@value{GDBVN}/gdb 22085the source specific to @value{GDBN} itself 22086 22087@item gdb-@value{GDBVN}/bfd 22088source for the Binary File Descriptor library 22089 22090@item gdb-@value{GDBVN}/include 22091@sc{gnu} include files 22092 22093@item gdb-@value{GDBVN}/libiberty 22094source for the @samp{-liberty} free software library 22095 22096@item gdb-@value{GDBVN}/opcodes 22097source for the library of opcode tables and disassemblers 22098 22099@item gdb-@value{GDBVN}/readline 22100source for the @sc{gnu} command-line interface 22101 22102@item gdb-@value{GDBVN}/glob 22103source for the @sc{gnu} filename pattern-matching subroutine 22104 22105@item gdb-@value{GDBVN}/mmalloc 22106source for the @sc{gnu} memory-mapped malloc package 22107@end table 22108 22109The simplest way to configure and build @value{GDBN} is to run @file{configure} 22110from the @file{gdb-@var{version-number}} source directory, which in 22111this example is the @file{gdb-@value{GDBVN}} directory. 22112 22113First switch to the @file{gdb-@var{version-number}} source directory 22114if you are not already in it; then run @file{configure}. Pass the 22115identifier for the platform on which @value{GDBN} will run as an 22116argument. 22117 22118For example: 22119 22120@smallexample 22121cd gdb-@value{GDBVN} 22122./configure @var{host} 22123make 22124@end smallexample 22125 22126@noindent 22127where @var{host} is an identifier such as @samp{sun4} or 22128@samp{decstation}, that identifies the platform where @value{GDBN} will run. 22129(You can often leave off @var{host}; @file{configure} tries to guess the 22130correct value by examining your system.) 22131 22132Running @samp{configure @var{host}} and then running @code{make} builds the 22133@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty} 22134libraries, then @code{gdb} itself. The configured source files, and the 22135binaries, are left in the corresponding source directories. 22136 22137@need 750 22138@file{configure} is a Bourne-shell (@code{/bin/sh}) script; if your 22139system does not recognize this automatically when you run a different 22140shell, you may need to run @code{sh} on it explicitly: 22141 22142@smallexample 22143sh configure @var{host} 22144@end smallexample 22145 22146If you run @file{configure} from a directory that contains source 22147directories for multiple libraries or programs, such as the 22148@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, 22149@file{configure} 22150creates configuration files for every directory level underneath (unless 22151you tell it not to, with the @samp{--norecursion} option). 22152 22153You should run the @file{configure} script from the top directory in the 22154source tree, the @file{gdb-@var{version-number}} directory. If you run 22155@file{configure} from one of the subdirectories, you will configure only 22156that subdirectory. That is usually not what you want. In particular, 22157if you run the first @file{configure} from the @file{gdb} subdirectory 22158of the @file{gdb-@var{version-number}} directory, you will omit the 22159configuration of @file{bfd}, @file{readline}, and other sibling 22160directories of the @file{gdb} subdirectory. This leads to build errors 22161about missing include files such as @file{bfd/bfd.h}. 22162 22163You can install @code{@value{GDBP}} anywhere; it has no hardwired paths. 22164However, you should make sure that the shell on your path (named by 22165the @samp{SHELL} environment variable) is publicly readable. Remember 22166that @value{GDBN} uses the shell to start your program---some systems refuse to 22167let @value{GDBN} debug child processes whose programs are not readable. 22168 22169@node Separate Objdir 22170@section Compiling @value{GDBN} in Another Directory 22171 22172If you want to run @value{GDBN} versions for several host or target machines, 22173you need a different @code{gdb} compiled for each combination of 22174host and target. @file{configure} is designed to make this easy by 22175allowing you to generate each configuration in a separate subdirectory, 22176rather than in the source directory. If your @code{make} program 22177handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running 22178@code{make} in each of these directories builds the @code{gdb} 22179program specified there. 22180 22181To build @code{gdb} in a separate directory, run @file{configure} 22182with the @samp{--srcdir} option to specify where to find the source. 22183(You also need to specify a path to find @file{configure} 22184itself from your working directory. If the path to @file{configure} 22185would be the same as the argument to @samp{--srcdir}, you can leave out 22186the @samp{--srcdir} option; it is assumed.) 22187 22188For example, with version @value{GDBVN}, you can build @value{GDBN} in a 22189separate directory for a Sun 4 like this: 22190 22191@smallexample 22192@group 22193cd gdb-@value{GDBVN} 22194mkdir ../gdb-sun4 22195cd ../gdb-sun4 22196../gdb-@value{GDBVN}/configure sun4 22197make 22198@end group 22199@end smallexample 22200 22201When @file{configure} builds a configuration using a remote source 22202directory, it creates a tree for the binaries with the same structure 22203(and using the same names) as the tree under the source directory. In 22204the example, you'd find the Sun 4 library @file{libiberty.a} in the 22205directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in 22206@file{gdb-sun4/gdb}. 22207 22208Make sure that your path to the @file{configure} script has just one 22209instance of @file{gdb} in it. If your path to @file{configure} looks 22210like @file{../gdb-@value{GDBVN}/gdb/configure}, you are configuring only 22211one subdirectory of @value{GDBN}, not the whole package. This leads to 22212build errors about missing include files such as @file{bfd/bfd.h}. 22213 22214One popular reason to build several @value{GDBN} configurations in separate 22215directories is to configure @value{GDBN} for cross-compiling (where 22216@value{GDBN} runs on one machine---the @dfn{host}---while debugging 22217programs that run on another machine---the @dfn{target}). 22218You specify a cross-debugging target by 22219giving the @samp{--target=@var{target}} option to @file{configure}. 22220 22221When you run @code{make} to build a program or library, you must run 22222it in a configured directory---whatever directory you were in when you 22223called @file{configure} (or one of its subdirectories). 22224 22225The @code{Makefile} that @file{configure} generates in each source 22226directory also runs recursively. If you type @code{make} in a source 22227directory such as @file{gdb-@value{GDBVN}} (or in a separate configured 22228directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you 22229will build all the required libraries, and then build GDB. 22230 22231When you have multiple hosts or targets configured in separate 22232directories, you can run @code{make} on them in parallel (for example, 22233if they are NFS-mounted on each of the hosts); they will not interfere 22234with each other. 22235 22236@node Config Names 22237@section Specifying Names for Hosts and Targets 22238 22239The specifications used for hosts and targets in the @file{configure} 22240script are based on a three-part naming scheme, but some short predefined 22241aliases are also supported. The full naming scheme encodes three pieces 22242of information in the following pattern: 22243 22244@smallexample 22245@var{architecture}-@var{vendor}-@var{os} 22246@end smallexample 22247 22248For example, you can use the alias @code{sun4} as a @var{host} argument, 22249or as the value for @var{target} in a @code{--target=@var{target}} 22250option. The equivalent full name is @samp{sparc-sun-sunos4}. 22251 22252The @file{configure} script accompanying @value{GDBN} does not provide 22253any query facility to list all supported host and target names or 22254aliases. @file{configure} calls the Bourne shell script 22255@code{config.sub} to map abbreviations to full names; you can read the 22256script, if you wish, or you can use it to test your guesses on 22257abbreviations---for example: 22258 22259@smallexample 22260% sh config.sub i386-linux 22261i386-pc-linux-gnu 22262% sh config.sub alpha-linux 22263alpha-unknown-linux-gnu 22264% sh config.sub hp9k700 22265hppa1.1-hp-hpux 22266% sh config.sub sun4 22267sparc-sun-sunos4.1.1 22268% sh config.sub sun3 22269m68k-sun-sunos4.1.1 22270% sh config.sub i986v 22271Invalid configuration `i986v': machine `i986v' not recognized 22272@end smallexample 22273 22274@noindent 22275@code{config.sub} is also distributed in the @value{GDBN} source 22276directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}). 22277 22278@node Configure Options 22279@section @file{configure} Options 22280 22281Here is a summary of the @file{configure} options and arguments that 22282are most often useful for building @value{GDBN}. @file{configure} also has 22283several other options not listed here. @inforef{What Configure 22284Does,,configure.info}, for a full explanation of @file{configure}. 22285 22286@smallexample 22287configure @r{[}--help@r{]} 22288 @r{[}--prefix=@var{dir}@r{]} 22289 @r{[}--exec-prefix=@var{dir}@r{]} 22290 @r{[}--srcdir=@var{dirname}@r{]} 22291 @r{[}--norecursion@r{]} @r{[}--rm@r{]} 22292 @r{[}--target=@var{target}@r{]} 22293 @var{host} 22294@end smallexample 22295 22296@noindent 22297You may introduce options with a single @samp{-} rather than 22298@samp{--} if you prefer; but you may abbreviate option names if you use 22299@samp{--}. 22300 22301@table @code 22302@item --help 22303Display a quick summary of how to invoke @file{configure}. 22304 22305@item --prefix=@var{dir} 22306Configure the source to install programs and files under directory 22307@file{@var{dir}}. 22308 22309@item --exec-prefix=@var{dir} 22310Configure the source to install programs under directory 22311@file{@var{dir}}. 22312 22313@c avoid splitting the warning from the explanation: 22314@need 2000 22315@item --srcdir=@var{dirname} 22316@strong{Warning: using this option requires @sc{gnu} @code{make}, or another 22317@code{make} that implements the @code{VPATH} feature.}@* 22318Use this option to make configurations in directories separate from the 22319@value{GDBN} source directories. Among other things, you can use this to 22320build (or maintain) several configurations simultaneously, in separate 22321directories. @file{configure} writes configuration-specific files in 22322the current directory, but arranges for them to use the source in the 22323directory @var{dirname}. @file{configure} creates directories under 22324the working directory in parallel to the source directories below 22325@var{dirname}. 22326 22327@item --norecursion 22328Configure only the directory level where @file{configure} is executed; do not 22329propagate configuration to subdirectories. 22330 22331@item --target=@var{target} 22332Configure @value{GDBN} for cross-debugging programs running on the specified 22333@var{target}. Without this option, @value{GDBN} is configured to debug 22334programs that run on the same machine (@var{host}) as @value{GDBN} itself. 22335 22336There is no convenient way to generate a list of all available targets. 22337 22338@item @var{host} @dots{} 22339Configure @value{GDBN} to run on the specified @var{host}. 22340 22341There is no convenient way to generate a list of all available hosts. 22342@end table 22343 22344There are many other options available as well, but they are generally 22345needed for special purposes only. 22346 22347@node Maintenance Commands 22348@appendix Maintenance Commands 22349@cindex maintenance commands 22350@cindex internal commands 22351 22352In addition to commands intended for @value{GDBN} users, @value{GDBN} 22353includes a number of commands intended for @value{GDBN} developers, 22354that are not documented elsewhere in this manual. These commands are 22355provided here for reference. (For commands that turn on debugging 22356messages, see @ref{Debugging Output}.) 22357 22358@table @code 22359@kindex maint agent 22360@item maint agent @var{expression} 22361Translate the given @var{expression} into remote agent bytecodes. 22362This command is useful for debugging the Agent Expression mechanism 22363(@pxref{Agent Expressions}). 22364 22365@kindex maint info breakpoints 22366@item @anchor{maint info breakpoints}maint info breakpoints 22367Using the same format as @samp{info breakpoints}, display both the 22368breakpoints you've set explicitly, and those @value{GDBN} is using for 22369internal purposes. Internal breakpoints are shown with negative 22370breakpoint numbers. The type column identifies what kind of breakpoint 22371is shown: 22372 22373@table @code 22374@item breakpoint 22375Normal, explicitly set breakpoint. 22376 22377@item watchpoint 22378Normal, explicitly set watchpoint. 22379 22380@item longjmp 22381Internal breakpoint, used to handle correctly stepping through 22382@code{longjmp} calls. 22383 22384@item longjmp resume 22385Internal breakpoint at the target of a @code{longjmp}. 22386 22387@item until 22388Temporary internal breakpoint used by the @value{GDBN} @code{until} command. 22389 22390@item finish 22391Temporary internal breakpoint used by the @value{GDBN} @code{finish} command. 22392 22393@item shlib events 22394Shared library events. 22395 22396@end table 22397 22398@kindex maint check-symtabs 22399@item maint check-symtabs 22400Check the consistency of psymtabs and symtabs. 22401 22402@kindex maint cplus first_component 22403@item maint cplus first_component @var{name} 22404Print the first C@t{++} class/namespace component of @var{name}. 22405 22406@kindex maint cplus namespace 22407@item maint cplus namespace 22408Print the list of possible C@t{++} namespaces. 22409 22410@kindex maint demangle 22411@item maint demangle @var{name} 22412Demangle a C@t{++} or Objective-C mangled @var{name}. 22413 22414@kindex maint deprecate 22415@kindex maint undeprecate 22416@cindex deprecated commands 22417@item maint deprecate @var{command} @r{[}@var{replacement}@r{]} 22418@itemx maint undeprecate @var{command} 22419Deprecate or undeprecate the named @var{command}. Deprecated commands 22420cause @value{GDBN} to issue a warning when you use them. The optional 22421argument @var{replacement} says which newer command should be used in 22422favor of the deprecated one; if it is given, @value{GDBN} will mention 22423the replacement as part of the warning. 22424 22425@kindex maint dump-me 22426@item maint dump-me 22427@cindex @code{SIGQUIT} signal, dump core of @value{GDBN} 22428Cause a fatal signal in the debugger and force it to dump its core. 22429This is supported only on systems which support aborting a program 22430with the @code{SIGQUIT} signal. 22431 22432@kindex maint internal-error 22433@kindex maint internal-warning 22434@item maint internal-error @r{[}@var{message-text}@r{]} 22435@itemx maint internal-warning @r{[}@var{message-text}@r{]} 22436Cause @value{GDBN} to call the internal function @code{internal_error} 22437or @code{internal_warning} and hence behave as though an internal error 22438or internal warning has been detected. In addition to reporting the 22439internal problem, these functions give the user the opportunity to 22440either quit @value{GDBN} or create a core file of the current 22441@value{GDBN} session. 22442 22443These commands take an optional parameter @var{message-text} that is 22444used as the text of the error or warning message. 22445 22446Here's an example of using @code{internal-error}: 22447 22448@smallexample 22449(@value{GDBP}) @kbd{maint internal-error testing, 1, 2} 22450@dots{}/maint.c:121: internal-error: testing, 1, 2 22451A problem internal to GDB has been detected. Further 22452debugging may prove unreliable. 22453Quit this debugging session? (y or n) @kbd{n} 22454Create a core file? (y or n) @kbd{n} 22455(@value{GDBP}) 22456@end smallexample 22457 22458@kindex maint packet 22459@item maint packet @var{text} 22460If @value{GDBN} is talking to an inferior via the serial protocol, 22461then this command sends the string @var{text} to the inferior, and 22462displays the response packet. @value{GDBN} supplies the initial 22463@samp{$} character, the terminating @samp{#} character, and the 22464checksum. 22465 22466@kindex maint print architecture 22467@item maint print architecture @r{[}@var{file}@r{]} 22468Print the entire architecture configuration. The optional argument 22469@var{file} names the file where the output goes. 22470 22471@kindex maint print dummy-frames 22472@item maint print dummy-frames 22473Prints the contents of @value{GDBN}'s internal dummy-frame stack. 22474 22475@smallexample 22476(@value{GDBP}) @kbd{b add} 22477@dots{} 22478(@value{GDBP}) @kbd{print add(2,3)} 22479Breakpoint 2, add (a=2, b=3) at @dots{} 2248058 return (a + b); 22481The program being debugged stopped while in a function called from GDB. 22482@dots{} 22483(@value{GDBP}) @kbd{maint print dummy-frames} 224840x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6 22485 top=0x0200bdd4 id=@{stack=0x200bddc,code=0x101405c@} 22486 call_lo=0x01014000 call_hi=0x01014001 22487(@value{GDBP}) 22488@end smallexample 22489 22490Takes an optional file parameter. 22491 22492@kindex maint print registers 22493@kindex maint print raw-registers 22494@kindex maint print cooked-registers 22495@kindex maint print register-groups 22496@item maint print registers @r{[}@var{file}@r{]} 22497@itemx maint print raw-registers @r{[}@var{file}@r{]} 22498@itemx maint print cooked-registers @r{[}@var{file}@r{]} 22499@itemx maint print register-groups @r{[}@var{file}@r{]} 22500Print @value{GDBN}'s internal register data structures. 22501 22502The command @code{maint print raw-registers} includes the contents of 22503the raw register cache; the command @code{maint print cooked-registers} 22504includes the (cooked) value of all registers; and the command 22505@code{maint print register-groups} includes the groups that each 22506register is a member of. @xref{Registers,, Registers, gdbint, 22507@value{GDBN} Internals}. 22508 22509These commands take an optional parameter, a file name to which to 22510write the information. 22511 22512@kindex maint print reggroups 22513@item maint print reggroups @r{[}@var{file}@r{]} 22514Print @value{GDBN}'s internal register group data structures. The 22515optional argument @var{file} tells to what file to write the 22516information. 22517 22518The register groups info looks like this: 22519 22520@smallexample 22521(@value{GDBP}) @kbd{maint print reggroups} 22522 Group Type 22523 general user 22524 float user 22525 all user 22526 vector user 22527 system user 22528 save internal 22529 restore internal 22530@end smallexample 22531 22532@kindex flushregs 22533@item flushregs 22534This command forces @value{GDBN} to flush its internal register cache. 22535 22536@kindex maint print objfiles 22537@cindex info for known object files 22538@item maint print objfiles 22539Print a dump of all known object files. For each object file, this 22540command prints its name, address in memory, and all of its psymtabs 22541and symtabs. 22542 22543@kindex maint print statistics 22544@cindex bcache statistics 22545@item maint print statistics 22546This command prints, for each object file in the program, various data 22547about that object file followed by the byte cache (@dfn{bcache}) 22548statistics for the object file. The objfile data includes the number 22549of minimal, partial, full, and stabs symbols, the number of types 22550defined by the objfile, the number of as yet unexpanded psym tables, 22551the number of line tables and string tables, and the amount of memory 22552used by the various tables. The bcache statistics include the counts, 22553sizes, and counts of duplicates of all and unique objects, max, 22554average, and median entry size, total memory used and its overhead and 22555savings, and various measures of the hash table size and chain 22556lengths. 22557 22558@kindex maint print target-stack 22559@cindex target stack description 22560@item maint print target-stack 22561A @dfn{target} is an interface between the debugger and a particular 22562kind of file or process. Targets can be stacked in @dfn{strata}, 22563so that more than one target can potentially respond to a request. 22564In particular, memory accesses will walk down the stack of targets 22565until they find a target that is interested in handling that particular 22566address. 22567 22568This command prints a short description of each layer that was pushed on 22569the @dfn{target stack}, starting from the top layer down to the bottom one. 22570 22571@kindex maint print type 22572@cindex type chain of a data type 22573@item maint print type @var{expr} 22574Print the type chain for a type specified by @var{expr}. The argument 22575can be either a type name or a symbol. If it is a symbol, the type of 22576that symbol is described. The type chain produced by this command is 22577a recursive definition of the data type as stored in @value{GDBN}'s 22578data structures, including its flags and contained types. 22579 22580@kindex maint set dwarf2 max-cache-age 22581@kindex maint show dwarf2 max-cache-age 22582@item maint set dwarf2 max-cache-age 22583@itemx maint show dwarf2 max-cache-age 22584Control the DWARF 2 compilation unit cache. 22585 22586@cindex DWARF 2 compilation units cache 22587In object files with inter-compilation-unit references, such as those 22588produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 2 22589reader needs to frequently refer to previously read compilation units. 22590This setting controls how long a compilation unit will remain in the 22591cache if it is not referenced. A higher limit means that cached 22592compilation units will be stored in memory longer, and more total 22593memory will be used. Setting it to zero disables caching, which will 22594slow down @value{GDBN} startup, but reduce memory consumption. 22595 22596@kindex maint set profile 22597@kindex maint show profile 22598@cindex profiling GDB 22599@item maint set profile 22600@itemx maint show profile 22601Control profiling of @value{GDBN}. 22602 22603Profiling will be disabled until you use the @samp{maint set profile} 22604command to enable it. When you enable profiling, the system will begin 22605collecting timing and execution count data; when you disable profiling or 22606exit @value{GDBN}, the results will be written to a log file. Remember that 22607if you use profiling, @value{GDBN} will overwrite the profiling log file 22608(often called @file{gmon.out}). If you have a record of important profiling 22609data in a @file{gmon.out} file, be sure to move it to a safe location. 22610 22611Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be 22612compiled with the @samp{-pg} compiler option. 22613 22614@kindex maint show-debug-regs 22615@cindex x86 hardware debug registers 22616@item maint show-debug-regs 22617Control whether to show variables that mirror the x86 hardware debug 22618registers. Use @code{ON} to enable, @code{OFF} to disable. If 22619enabled, the debug registers values are shown when @value{GDBN} inserts or 22620removes a hardware breakpoint or watchpoint, and when the inferior 22621triggers a hardware-assisted breakpoint or watchpoint. 22622 22623@kindex maint space 22624@cindex memory used by commands 22625@item maint space 22626Control whether to display memory usage for each command. If set to a 22627nonzero value, @value{GDBN} will display how much memory each command 22628took, following the command's own output. This can also be requested 22629by invoking @value{GDBN} with the @option{--statistics} command-line 22630switch (@pxref{Mode Options}). 22631 22632@kindex maint time 22633@cindex time of command execution 22634@item maint time 22635Control whether to display the execution time for each command. If 22636set to a nonzero value, @value{GDBN} will display how much time it 22637took to execute each command, following the command's own output. 22638This can also be requested by invoking @value{GDBN} with the 22639@option{--statistics} command-line switch (@pxref{Mode Options}). 22640 22641@kindex maint translate-address 22642@item maint translate-address @r{[}@var{section}@r{]} @var{addr} 22643Find the symbol stored at the location specified by the address 22644@var{addr} and an optional section name @var{section}. If found, 22645@value{GDBN} prints the name of the closest symbol and an offset from 22646the symbol's location to the specified address. This is similar to 22647the @code{info address} command (@pxref{Symbols}), except that this 22648command also allows to find symbols in other sections. 22649 22650@end table 22651 22652The following command is useful for non-interactive invocations of 22653@value{GDBN}, such as in the test suite. 22654 22655@table @code 22656@item set watchdog @var{nsec} 22657@kindex set watchdog 22658@cindex watchdog timer 22659@cindex timeout for commands 22660Set the maximum number of seconds @value{GDBN} will wait for the 22661target operation to finish. If this time expires, @value{GDBN} 22662reports and error and the command is aborted. 22663 22664@item show watchdog 22665Show the current setting of the target wait timeout. 22666@end table 22667 22668@node Remote Protocol 22669@appendix @value{GDBN} Remote Serial Protocol 22670 22671@menu 22672* Overview:: 22673* Packets:: 22674* Stop Reply Packets:: 22675* General Query Packets:: 22676* Register Packet Format:: 22677* Tracepoint Packets:: 22678* Interrupts:: 22679* Examples:: 22680* File-I/O Remote Protocol Extension:: 22681* Library List Format:: 22682* Memory Map Format:: 22683@end menu 22684 22685@node Overview 22686@section Overview 22687 22688There may be occasions when you need to know something about the 22689protocol---for example, if there is only one serial port to your target 22690machine, you might want your program to do something special if it 22691recognizes a packet meant for @value{GDBN}. 22692 22693In the examples below, @samp{->} and @samp{<-} are used to indicate 22694transmitted and received data, respectively. 22695 22696@cindex protocol, @value{GDBN} remote serial 22697@cindex serial protocol, @value{GDBN} remote 22698@cindex remote serial protocol 22699All @value{GDBN} commands and responses (other than acknowledgments) are 22700sent as a @var{packet}. A @var{packet} is introduced with the character 22701@samp{$}, the actual @var{packet-data}, and the terminating character 22702@samp{#} followed by a two-digit @var{checksum}: 22703 22704@smallexample 22705@code{$}@var{packet-data}@code{#}@var{checksum} 22706@end smallexample 22707@noindent 22708 22709@cindex checksum, for @value{GDBN} remote 22710@noindent 22711The two-digit @var{checksum} is computed as the modulo 256 sum of all 22712characters between the leading @samp{$} and the trailing @samp{#} (an 22713eight bit unsigned checksum). 22714 22715Implementors should note that prior to @value{GDBN} 5.0 the protocol 22716specification also included an optional two-digit @var{sequence-id}: 22717 22718@smallexample 22719@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} 22720@end smallexample 22721 22722@cindex sequence-id, for @value{GDBN} remote 22723@noindent 22724That @var{sequence-id} was appended to the acknowledgment. @value{GDBN} 22725has never output @var{sequence-id}s. Stubs that handle packets added 22726since @value{GDBN} 5.0 must not accept @var{sequence-id}. 22727 22728@cindex acknowledgment, for @value{GDBN} remote 22729When either the host or the target machine receives a packet, the first 22730response expected is an acknowledgment: either @samp{+} (to indicate 22731the package was received correctly) or @samp{-} (to request 22732retransmission): 22733 22734@smallexample 22735-> @code{$}@var{packet-data}@code{#}@var{checksum} 22736<- @code{+} 22737@end smallexample 22738@noindent 22739 22740The host (@value{GDBN}) sends @var{command}s, and the target (the 22741debugging stub incorporated in your program) sends a @var{response}. In 22742the case of step and continue @var{command}s, the response is only sent 22743when the operation has completed (the target has again stopped). 22744 22745@var{packet-data} consists of a sequence of characters with the 22746exception of @samp{#} and @samp{$} (see @samp{X} packet for additional 22747exceptions). 22748 22749@cindex remote protocol, field separator 22750Fields within the packet should be separated using @samp{,} @samp{;} or 22751@samp{:}. Except where otherwise noted all numbers are represented in 22752@sc{hex} with leading zeros suppressed. 22753 22754Implementors should note that prior to @value{GDBN} 5.0, the character 22755@samp{:} could not appear as the third character in a packet (as it 22756would potentially conflict with the @var{sequence-id}). 22757 22758@cindex remote protocol, binary data 22759@anchor{Binary Data} 22760Binary data in most packets is encoded either as two hexadecimal 22761digits per byte of binary data. This allowed the traditional remote 22762protocol to work over connections which were only seven-bit clean. 22763Some packets designed more recently assume an eight-bit clean 22764connection, and use a more efficient encoding to send and receive 22765binary data. 22766 22767The binary data representation uses @code{7d} (@sc{ascii} @samp{@}}) 22768as an escape character. Any escaped byte is transmitted as the escape 22769character followed by the original character XORed with @code{0x20}. 22770For example, the byte @code{0x7d} would be transmitted as the two 22771bytes @code{0x7d 0x5d}. The bytes @code{0x23} (@sc{ascii} @samp{#}), 22772@code{0x24} (@sc{ascii} @samp{$}), and @code{0x7d} (@sc{ascii} 22773@samp{@}}) must always be escaped. Responses sent by the stub 22774must also escape @code{0x2a} (@sc{ascii} @samp{*}), so that it 22775is not interpreted as the start of a run-length encoded sequence 22776(described next). 22777 22778Response @var{data} can be run-length encoded to save space. A @samp{*} 22779means that the next character is an @sc{ascii} encoding giving a repeat count 22780which stands for that many repetitions of the character preceding the 22781@samp{*}. The encoding is @code{n+29}, yielding a printable character 22782where @code{n >=3} (which is where rle starts to win). The printable 22783characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric 22784value greater than 126 should not be used. 22785 22786So: 22787@smallexample 22788"@code{0* }" 22789@end smallexample 22790@noindent 22791means the same as "0000". 22792 22793The error response returned for some packets includes a two character 22794error number. That number is not well defined. 22795 22796@cindex empty response, for unsupported packets 22797For any @var{command} not supported by the stub, an empty response 22798(@samp{$#00}) should be returned. That way it is possible to extend the 22799protocol. A newer @value{GDBN} can tell if a packet is supported based 22800on that response. 22801 22802A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M}, 22803@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are 22804optional. 22805 22806@node Packets 22807@section Packets 22808 22809The following table provides a complete list of all currently defined 22810@var{command}s and their corresponding response @var{data}. 22811@xref{File-I/O Remote Protocol Extension}, for details about the File 22812I/O extension of the remote protocol. 22813 22814Each packet's description has a template showing the packet's overall 22815syntax, followed by an explanation of the packet's meaning. We 22816include spaces in some of the templates for clarity; these are not 22817part of the packet's syntax. No @value{GDBN} packet uses spaces to 22818separate its components. For example, a template like @samp{foo 22819@var{bar} @var{baz}} describes a packet beginning with the three ASCII 22820bytes @samp{foo}, followed by a @var{bar}, followed directly by a 22821@var{baz}. @value{GDBN} does not transmit a space character between the 22822@samp{foo} and the @var{bar}, or between the @var{bar} and the 22823@var{baz}. 22824 22825Note that all packet forms beginning with an upper- or lower-case 22826letter, other than those described here, are reserved for future use. 22827 22828Here are the packet descriptions. 22829 22830@table @samp 22831 22832@item ! 22833@cindex @samp{!} packet 22834Enable extended mode. In extended mode, the remote server is made 22835persistent. The @samp{R} packet is used to restart the program being 22836debugged. 22837 22838Reply: 22839@table @samp 22840@item OK 22841The remote target both supports and has enabled extended mode. 22842@end table 22843 22844@item ? 22845@cindex @samp{?} packet 22846Indicate the reason the target halted. The reply is the same as for 22847step and continue. 22848 22849Reply: 22850@xref{Stop Reply Packets}, for the reply specifications. 22851 22852@item A @var{arglen},@var{argnum},@var{arg},@dots{} 22853@cindex @samp{A} packet 22854Initialized @code{argv[]} array passed into program. @var{arglen} 22855specifies the number of bytes in the hex encoded byte stream 22856@var{arg}. See @code{gdbserver} for more details. 22857 22858Reply: 22859@table @samp 22860@item OK 22861The arguments were set. 22862@item E @var{NN} 22863An error occurred. 22864@end table 22865 22866@item b @var{baud} 22867@cindex @samp{b} packet 22868(Don't use this packet; its behavior is not well-defined.) 22869Change the serial line speed to @var{baud}. 22870 22871JTC: @emph{When does the transport layer state change? When it's 22872received, or after the ACK is transmitted. In either case, there are 22873problems if the command or the acknowledgment packet is dropped.} 22874 22875Stan: @emph{If people really wanted to add something like this, and get 22876it working for the first time, they ought to modify ser-unix.c to send 22877some kind of out-of-band message to a specially-setup stub and have the 22878switch happen "in between" packets, so that from remote protocol's point 22879of view, nothing actually happened.} 22880 22881@item B @var{addr},@var{mode} 22882@cindex @samp{B} packet 22883Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a 22884breakpoint at @var{addr}. 22885 22886Don't use this packet. Use the @samp{Z} and @samp{z} packets instead 22887(@pxref{insert breakpoint or watchpoint packet}). 22888 22889@item c @r{[}@var{addr}@r{]} 22890@cindex @samp{c} packet 22891Continue. @var{addr} is address to resume. If @var{addr} is omitted, 22892resume at current address. 22893 22894Reply: 22895@xref{Stop Reply Packets}, for the reply specifications. 22896 22897@item C @var{sig}@r{[};@var{addr}@r{]} 22898@cindex @samp{C} packet 22899Continue with signal @var{sig} (hex signal number). If 22900@samp{;@var{addr}} is omitted, resume at same address. 22901 22902Reply: 22903@xref{Stop Reply Packets}, for the reply specifications. 22904 22905@item d 22906@cindex @samp{d} packet 22907Toggle debug flag. 22908 22909Don't use this packet; instead, define a general set packet 22910(@pxref{General Query Packets}). 22911 22912@item D 22913@cindex @samp{D} packet 22914Detach @value{GDBN} from the remote system. Sent to the remote target 22915before @value{GDBN} disconnects via the @code{detach} command. 22916 22917Reply: 22918@table @samp 22919@item OK 22920for success 22921@item E @var{NN} 22922for an error 22923@end table 22924 22925@item F @var{RC},@var{EE},@var{CF};@var{XX} 22926@cindex @samp{F} packet 22927A reply from @value{GDBN} to an @samp{F} packet sent by the target. 22928This is part of the File-I/O protocol extension. @xref{File-I/O 22929Remote Protocol Extension}, for the specification. 22930 22931@item g 22932@anchor{read registers packet} 22933@cindex @samp{g} packet 22934Read general registers. 22935 22936Reply: 22937@table @samp 22938@item @var{XX@dots{}} 22939Each byte of register data is described by two hex digits. The bytes 22940with the register are transmitted in target byte order. The size of 22941each register and their position within the @samp{g} packet are 22942determined by the @value{GDBN} internal gdbarch functions 22943@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}. The 22944specification of several standard @samp{g} packets is specified below. 22945@item E @var{NN} 22946for an error. 22947@end table 22948 22949@item G @var{XX@dots{}} 22950@cindex @samp{G} packet 22951Write general registers. @xref{read registers packet}, for a 22952description of the @var{XX@dots{}} data. 22953 22954Reply: 22955@table @samp 22956@item OK 22957for success 22958@item E @var{NN} 22959for an error 22960@end table 22961 22962@item H @var{c} @var{t} 22963@cindex @samp{H} packet 22964Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g}, 22965@samp{G}, et.al.). @var{c} depends on the operation to be performed: it 22966should be @samp{c} for step and continue operations, @samp{g} for other 22967operations. The thread designator @var{t} may be @samp{-1}, meaning all 22968the threads, a thread number, or @samp{0} which means pick any thread. 22969 22970Reply: 22971@table @samp 22972@item OK 22973for success 22974@item E @var{NN} 22975for an error 22976@end table 22977 22978@c FIXME: JTC: 22979@c 'H': How restrictive (or permissive) is the thread model. If a 22980@c thread is selected and stopped, are other threads allowed 22981@c to continue to execute? As I mentioned above, I think the 22982@c semantics of each command when a thread is selected must be 22983@c described. For example: 22984@c 22985@c 'g': If the stub supports threads and a specific thread is 22986@c selected, returns the register block from that thread; 22987@c otherwise returns current registers. 22988@c 22989@c 'G' If the stub supports threads and a specific thread is 22990@c selected, sets the registers of the register block of 22991@c that thread; otherwise sets current registers. 22992 22993@item i @r{[}@var{addr}@r{[},@var{nnn}@r{]]} 22994@anchor{cycle step packet} 22995@cindex @samp{i} packet 22996Step the remote target by a single clock cycle. If @samp{,@var{nnn}} is 22997present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle 22998step starting at that address. 22999 23000@item I 23001@cindex @samp{I} packet 23002Signal, then cycle step. @xref{step with signal packet}. @xref{cycle 23003step packet}. 23004 23005@item k 23006@cindex @samp{k} packet 23007Kill request. 23008 23009FIXME: @emph{There is no description of how to operate when a specific 23010thread context has been selected (i.e.@: does 'k' kill only that 23011thread?)}. 23012 23013@item m @var{addr},@var{length} 23014@cindex @samp{m} packet 23015Read @var{length} bytes of memory starting at address @var{addr}. 23016Note that @var{addr} may not be aligned to any particular boundary. 23017 23018The stub need not use any particular size or alignment when gathering 23019data from memory for the response; even if @var{addr} is word-aligned 23020and @var{length} is a multiple of the word size, the stub is free to 23021use byte accesses, or not. For this reason, this packet may not be 23022suitable for accessing memory-mapped I/O devices. 23023@cindex alignment of remote memory accesses 23024@cindex size of remote memory accesses 23025@cindex memory, alignment and size of remote accesses 23026 23027Reply: 23028@table @samp 23029@item @var{XX@dots{}} 23030Memory contents; each byte is transmitted as a two-digit hexadecimal 23031number. The reply may contain fewer bytes than requested if the 23032server was able to read only part of the region of memory. 23033@item E @var{NN} 23034@var{NN} is errno 23035@end table 23036 23037@item M @var{addr},@var{length}:@var{XX@dots{}} 23038@cindex @samp{M} packet 23039Write @var{length} bytes of memory starting at address @var{addr}. 23040@var{XX@dots{}} is the data; each byte is transmitted as a two-digit 23041hexadecimal number. 23042 23043Reply: 23044@table @samp 23045@item OK 23046for success 23047@item E @var{NN} 23048for an error (this includes the case where only part of the data was 23049written). 23050@end table 23051 23052@item p @var{n} 23053@cindex @samp{p} packet 23054Read the value of register @var{n}; @var{n} is in hex. 23055@xref{read registers packet}, for a description of how the returned 23056register value is encoded. 23057 23058Reply: 23059@table @samp 23060@item @var{XX@dots{}} 23061the register's value 23062@item E @var{NN} 23063for an error 23064@item 23065Indicating an unrecognized @var{query}. 23066@end table 23067 23068@item P @var{n@dots{}}=@var{r@dots{}} 23069@anchor{write register packet} 23070@cindex @samp{P} packet 23071Write register @var{n@dots{}} with value @var{r@dots{}}. The register 23072number @var{n} is in hexadecimal, and @var{r@dots{}} contains two hex 23073digits for each byte in the register (target byte order). 23074 23075Reply: 23076@table @samp 23077@item OK 23078for success 23079@item E @var{NN} 23080for an error 23081@end table 23082 23083@item q @var{name} @var{params}@dots{} 23084@itemx Q @var{name} @var{params}@dots{} 23085@cindex @samp{q} packet 23086@cindex @samp{Q} packet 23087General query (@samp{q}) and set (@samp{Q}). These packets are 23088described fully in @ref{General Query Packets}. 23089 23090@item r 23091@cindex @samp{r} packet 23092Reset the entire system. 23093 23094Don't use this packet; use the @samp{R} packet instead. 23095 23096@item R @var{XX} 23097@cindex @samp{R} packet 23098Restart the program being debugged. @var{XX}, while needed, is ignored. 23099This packet is only available in extended mode. 23100 23101The @samp{R} packet has no reply. 23102 23103@item s @r{[}@var{addr}@r{]} 23104@cindex @samp{s} packet 23105Single step. @var{addr} is the address at which to resume. If 23106@var{addr} is omitted, resume at same address. 23107 23108Reply: 23109@xref{Stop Reply Packets}, for the reply specifications. 23110 23111@item S @var{sig}@r{[};@var{addr}@r{]} 23112@anchor{step with signal packet} 23113@cindex @samp{S} packet 23114Step with signal. This is analogous to the @samp{C} packet, but 23115requests a single-step, rather than a normal resumption of execution. 23116 23117Reply: 23118@xref{Stop Reply Packets}, for the reply specifications. 23119 23120@item t @var{addr}:@var{PP},@var{MM} 23121@cindex @samp{t} packet 23122Search backwards starting at address @var{addr} for a match with pattern 23123@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes. 23124@var{addr} must be at least 3 digits. 23125 23126@item T @var{XX} 23127@cindex @samp{T} packet 23128Find out if the thread XX is alive. 23129 23130Reply: 23131@table @samp 23132@item OK 23133thread is still alive 23134@item E @var{NN} 23135thread is dead 23136@end table 23137 23138@item v 23139Packets starting with @samp{v} are identified by a multi-letter name, 23140up to the first @samp{;} or @samp{?} (or the end of the packet). 23141 23142@item vCont@r{[};@var{action}@r{[}:@var{tid}@r{]]}@dots{} 23143@cindex @samp{vCont} packet 23144Resume the inferior, specifying different actions for each thread. 23145If an action is specified with no @var{tid}, then it is applied to any 23146threads that don't have a specific action specified; if no default action is 23147specified then other threads should remain stopped. Specifying multiple 23148default actions is an error; specifying no actions is also an error. 23149Thread IDs are specified in hexadecimal. Currently supported actions are: 23150 23151@table @samp 23152@item c 23153Continue. 23154@item C @var{sig} 23155Continue with signal @var{sig}. @var{sig} should be two hex digits. 23156@item s 23157Step. 23158@item S @var{sig} 23159Step with signal @var{sig}. @var{sig} should be two hex digits. 23160@end table 23161 23162The optional @var{addr} argument normally associated with these packets is 23163not supported in @samp{vCont}. 23164 23165Reply: 23166@xref{Stop Reply Packets}, for the reply specifications. 23167 23168@item vCont? 23169@cindex @samp{vCont?} packet 23170Request a list of actions supported by the @samp{vCont} packet. 23171 23172Reply: 23173@table @samp 23174@item vCont@r{[};@var{action}@dots{}@r{]} 23175The @samp{vCont} packet is supported. Each @var{action} is a supported 23176command in the @samp{vCont} packet. 23177@item 23178The @samp{vCont} packet is not supported. 23179@end table 23180 23181@item vFlashErase:@var{addr},@var{length} 23182@cindex @samp{vFlashErase} packet 23183Direct the stub to erase @var{length} bytes of flash starting at 23184@var{addr}. The region may enclose any number of flash blocks, but 23185its start and end must fall on block boundaries, as indicated by the 23186flash block size appearing in the memory map (@pxref{Memory Map 23187Format}). @value{GDBN} groups flash memory programming operations 23188together, and sends a @samp{vFlashDone} request after each group; the 23189stub is allowed to delay erase operation until the @samp{vFlashDone} 23190packet is received. 23191 23192Reply: 23193@table @samp 23194@item OK 23195for success 23196@item E @var{NN} 23197for an error 23198@end table 23199 23200@item vFlashWrite:@var{addr}:@var{XX@dots{}} 23201@cindex @samp{vFlashWrite} packet 23202Direct the stub to write data to flash address @var{addr}. The data 23203is passed in binary form using the same encoding as for the @samp{X} 23204packet (@pxref{Binary Data}). The memory ranges specified by 23205@samp{vFlashWrite} packets preceding a @samp{vFlashDone} packet must 23206not overlap, and must appear in order of increasing addresses 23207(although @samp{vFlashErase} packets for higher addresses may already 23208have been received; the ordering is guaranteed only between 23209@samp{vFlashWrite} packets). If a packet writes to an address that was 23210neither erased by a preceding @samp{vFlashErase} packet nor by some other 23211target-specific method, the results are unpredictable. 23212 23213 23214Reply: 23215@table @samp 23216@item OK 23217for success 23218@item E.memtype 23219for vFlashWrite addressing non-flash memory 23220@item E @var{NN} 23221for an error 23222@end table 23223 23224@item vFlashDone 23225@cindex @samp{vFlashDone} packet 23226Indicate to the stub that flash programming operation is finished. 23227The stub is permitted to delay or batch the effects of a group of 23228@samp{vFlashErase} and @samp{vFlashWrite} packets until a 23229@samp{vFlashDone} packet is received. The contents of the affected 23230regions of flash memory are unpredictable until the @samp{vFlashDone} 23231request is completed. 23232 23233@item X @var{addr},@var{length}:@var{XX@dots{}} 23234@anchor{X packet} 23235@cindex @samp{X} packet 23236Write data to memory, where the data is transmitted in binary. 23237@var{addr} is address, @var{length} is number of bytes, 23238@samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}). 23239 23240Reply: 23241@table @samp 23242@item OK 23243for success 23244@item E @var{NN} 23245for an error 23246@end table 23247 23248@item z @var{type},@var{addr},@var{length} 23249@itemx Z @var{type},@var{addr},@var{length} 23250@anchor{insert breakpoint or watchpoint packet} 23251@cindex @samp{z} packet 23252@cindex @samp{Z} packets 23253Insert (@samp{Z}) or remove (@samp{z}) a @var{type} breakpoint or 23254watchpoint starting at address @var{address} and covering the next 23255@var{length} bytes. 23256 23257Each breakpoint and watchpoint packet @var{type} is documented 23258separately. 23259 23260@emph{Implementation notes: A remote target shall return an empty string 23261for an unrecognized breakpoint or watchpoint packet @var{type}. A 23262remote target shall support either both or neither of a given 23263@samp{Z@var{type}@dots{}} and @samp{z@var{type}@dots{}} packet pair. To 23264avoid potential problems with duplicate packets, the operations should 23265be implemented in an idempotent way.} 23266 23267@item z0,@var{addr},@var{length} 23268@itemx Z0,@var{addr},@var{length} 23269@cindex @samp{z0} packet 23270@cindex @samp{Z0} packet 23271Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address 23272@var{addr} of size @var{length}. 23273 23274A memory breakpoint is implemented by replacing the instruction at 23275@var{addr} with a software breakpoint or trap instruction. The 23276@var{length} is used by targets that indicates the size of the 23277breakpoint (in bytes) that should be inserted (e.g., the @sc{arm} and 23278@sc{mips} can insert either a 2 or 4 byte breakpoint). 23279 23280@emph{Implementation note: It is possible for a target to copy or move 23281code that contains memory breakpoints (e.g., when implementing 23282overlays). The behavior of this packet, in the presence of such a 23283target, is not defined.} 23284 23285Reply: 23286@table @samp 23287@item OK 23288success 23289@item 23290not supported 23291@item E @var{NN} 23292for an error 23293@end table 23294 23295@item z1,@var{addr},@var{length} 23296@itemx Z1,@var{addr},@var{length} 23297@cindex @samp{z1} packet 23298@cindex @samp{Z1} packet 23299Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at 23300address @var{addr} of size @var{length}. 23301 23302A hardware breakpoint is implemented using a mechanism that is not 23303dependant on being able to modify the target's memory. 23304 23305@emph{Implementation note: A hardware breakpoint is not affected by code 23306movement.} 23307 23308Reply: 23309@table @samp 23310@item OK 23311success 23312@item 23313not supported 23314@item E @var{NN} 23315for an error 23316@end table 23317 23318@item z2,@var{addr},@var{length} 23319@itemx Z2,@var{addr},@var{length} 23320@cindex @samp{z2} packet 23321@cindex @samp{Z2} packet 23322Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint. 23323 23324Reply: 23325@table @samp 23326@item OK 23327success 23328@item 23329not supported 23330@item E @var{NN} 23331for an error 23332@end table 23333 23334@item z3,@var{addr},@var{length} 23335@itemx Z3,@var{addr},@var{length} 23336@cindex @samp{z3} packet 23337@cindex @samp{Z3} packet 23338Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint. 23339 23340Reply: 23341@table @samp 23342@item OK 23343success 23344@item 23345not supported 23346@item E @var{NN} 23347for an error 23348@end table 23349 23350@item z4,@var{addr},@var{length} 23351@itemx Z4,@var{addr},@var{length} 23352@cindex @samp{z4} packet 23353@cindex @samp{Z4} packet 23354Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint. 23355 23356Reply: 23357@table @samp 23358@item OK 23359success 23360@item 23361not supported 23362@item E @var{NN} 23363for an error 23364@end table 23365 23366@end table 23367 23368@node Stop Reply Packets 23369@section Stop Reply Packets 23370@cindex stop reply packets 23371 23372The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can 23373receive any of the below as a reply. In the case of the @samp{C}, 23374@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned 23375when the target halts. In the below the exact meaning of @dfn{signal 23376number} is defined by the header @file{include/gdb/signals.h} in the 23377@value{GDBN} source code. 23378 23379As in the description of request packets, we include spaces in the 23380reply templates for clarity; these are not part of the reply packet's 23381syntax. No @value{GDBN} stop reply packet uses spaces to separate its 23382components. 23383 23384@table @samp 23385 23386@item S @var{AA} 23387The program received signal number @var{AA} (a two-digit hexadecimal 23388number). This is equivalent to a @samp{T} response with no 23389@var{n}:@var{r} pairs. 23390 23391@item T @var{AA} @var{n1}:@var{r1};@var{n2}:@var{r2};@dots{} 23392@cindex @samp{T} packet reply 23393The program received signal number @var{AA} (a two-digit hexadecimal 23394number). This is equivalent to an @samp{S} response, except that the 23395@samp{@var{n}:@var{r}} pairs can carry values of important registers 23396and other information directly in the stop reply packet, reducing 23397round-trip latency. Single-step and breakpoint traps are reported 23398this way. Each @samp{@var{n}:@var{r}} pair is interpreted as follows: 23399 23400@itemize @bullet 23401@item 23402If @var{n} is a hexadecimal number, it is a register number, and the 23403corresponding @var{r} gives that register's value. @var{r} is a 23404series of bytes in target byte order, with each byte given by a 23405two-digit hex number. 23406 23407@item 23408If @var{n} is @samp{thread}, then @var{r} is the thread process ID, in 23409hex. 23410 23411@item 23412If @var{n} is a recognized @dfn{stop reason}, it describes a more 23413specific event that stopped the target. The currently defined stop 23414reasons are listed below. @var{aa} should be @samp{05}, the trap 23415signal. At most one stop reason should be present. 23416 23417@item 23418Otherwise, @value{GDBN} should ignore this @samp{@var{n}:@var{r}} pair 23419and go on to the next; this allows us to extend the protocol in the 23420future. 23421@end itemize 23422 23423The currently defined stop reasons are: 23424 23425@table @samp 23426@item watch 23427@itemx rwatch 23428@itemx awatch 23429The packet indicates a watchpoint hit, and @var{r} is the data address, in 23430hex. 23431 23432@cindex shared library events, remote reply 23433@item library 23434The packet indicates that the loaded libraries have changed. 23435@value{GDBN} should use @samp{qXfer:libraries:read} to fetch a new 23436list of loaded libraries. @var{r} is ignored. 23437@end table 23438 23439@item W @var{AA} 23440The process exited, and @var{AA} is the exit status. This is only 23441applicable to certain targets. 23442 23443@item X @var{AA} 23444The process terminated with signal @var{AA}. 23445 23446@item O @var{XX}@dots{} 23447@samp{@var{XX}@dots{}} is hex encoding of @sc{ascii} data, to be 23448written as the program's console output. This can happen at any time 23449while the program is running and the debugger should continue to wait 23450for @samp{W}, @samp{T}, etc. 23451 23452@item F @var{call-id},@var{parameter}@dots{} 23453@var{call-id} is the identifier which says which host system call should 23454be called. This is just the name of the function. Translation into the 23455correct system call is only applicable as it's defined in @value{GDBN}. 23456@xref{File-I/O Remote Protocol Extension}, for a list of implemented 23457system calls. 23458 23459@samp{@var{parameter}@dots{}} is a list of parameters as defined for 23460this very system call. 23461 23462The target replies with this packet when it expects @value{GDBN} to 23463call a host system call on behalf of the target. @value{GDBN} replies 23464with an appropriate @samp{F} packet and keeps up waiting for the next 23465reply packet from the target. The latest @samp{C}, @samp{c}, @samp{S} 23466or @samp{s} action is expected to be continued. @xref{File-I/O Remote 23467Protocol Extension}, for more details. 23468 23469@end table 23470 23471@node General Query Packets 23472@section General Query Packets 23473@cindex remote query requests 23474 23475Packets starting with @samp{q} are @dfn{general query packets}; 23476packets starting with @samp{Q} are @dfn{general set packets}. General 23477query and set packets are a semi-unified form for retrieving and 23478sending information to and from the stub. 23479 23480The initial letter of a query or set packet is followed by a name 23481indicating what sort of thing the packet applies to. For example, 23482@value{GDBN} may use a @samp{qSymbol} packet to exchange symbol 23483definitions with the stub. These packet names follow some 23484conventions: 23485 23486@itemize @bullet 23487@item 23488The name must not contain commas, colons or semicolons. 23489@item 23490Most @value{GDBN} query and set packets have a leading upper case 23491letter. 23492@item 23493The names of custom vendor packets should use a company prefix, in 23494lower case, followed by a period. For example, packets designed at 23495the Acme Corporation might begin with @samp{qacme.foo} (for querying 23496foos) or @samp{Qacme.bar} (for setting bars). 23497@end itemize 23498 23499The name of a query or set packet should be separated from any 23500parameters by a @samp{:}; the parameters themselves should be 23501separated by @samp{,} or @samp{;}. Stubs must be careful to match the 23502full packet name, and check for a separator or the end of the packet, 23503in case two packet names share a common prefix. New packets should not begin 23504with @samp{qC}, @samp{qP}, or @samp{qL}@footnote{The @samp{qP} and @samp{qL} 23505packets predate these conventions, and have arguments without any terminator 23506for the packet name; we suspect they are in widespread use in places that 23507are difficult to upgrade. The @samp{qC} packet has no arguments, but some 23508existing stubs (e.g.@: RedBoot) are known to not check for the end of the 23509packet.}. 23510 23511Like the descriptions of the other packets, each description here 23512has a template showing the packet's overall syntax, followed by an 23513explanation of the packet's meaning. We include spaces in some of the 23514templates for clarity; these are not part of the packet's syntax. No 23515@value{GDBN} packet uses spaces to separate its components. 23516 23517Here are the currently defined query and set packets: 23518 23519@table @samp 23520 23521@item qC 23522@cindex current thread, remote request 23523@cindex @samp{qC} packet 23524Return the current thread id. 23525 23526Reply: 23527@table @samp 23528@item QC @var{pid} 23529Where @var{pid} is an unsigned hexadecimal process id. 23530@item @r{(anything else)} 23531Any other reply implies the old pid. 23532@end table 23533 23534@item qCRC:@var{addr},@var{length} 23535@cindex CRC of memory block, remote request 23536@cindex @samp{qCRC} packet 23537Compute the CRC checksum of a block of memory. 23538Reply: 23539@table @samp 23540@item E @var{NN} 23541An error (such as memory fault) 23542@item C @var{crc32} 23543The specified memory region's checksum is @var{crc32}. 23544@end table 23545 23546@item qfThreadInfo 23547@itemx qsThreadInfo 23548@cindex list active threads, remote request 23549@cindex @samp{qfThreadInfo} packet 23550@cindex @samp{qsThreadInfo} packet 23551Obtain a list of all active thread ids from the target (OS). Since there 23552may be too many active threads to fit into one reply packet, this query 23553works iteratively: it may require more than one query/reply sequence to 23554obtain the entire list of threads. The first query of the sequence will 23555be the @samp{qfThreadInfo} query; subsequent queries in the 23556sequence will be the @samp{qsThreadInfo} query. 23557 23558NOTE: This packet replaces the @samp{qL} query (see below). 23559 23560Reply: 23561@table @samp 23562@item m @var{id} 23563A single thread id 23564@item m @var{id},@var{id}@dots{} 23565a comma-separated list of thread ids 23566@item l 23567(lower case letter @samp{L}) denotes end of list. 23568@end table 23569 23570In response to each query, the target will reply with a list of one or 23571more thread ids, in big-endian unsigned hex, separated by commas. 23572@value{GDBN} will respond to each reply with a request for more thread 23573ids (using the @samp{qs} form of the query), until the target responds 23574with @samp{l} (lower-case el, for @dfn{last}). 23575 23576@item qGetTLSAddr:@var{thread-id},@var{offset},@var{lm} 23577@cindex get thread-local storage address, remote request 23578@cindex @samp{qGetTLSAddr} packet 23579Fetch the address associated with thread local storage specified 23580by @var{thread-id}, @var{offset}, and @var{lm}. 23581 23582@var{thread-id} is the (big endian, hex encoded) thread id associated with the 23583thread for which to fetch the TLS address. 23584 23585@var{offset} is the (big endian, hex encoded) offset associated with the 23586thread local variable. (This offset is obtained from the debug 23587information associated with the variable.) 23588 23589@var{lm} is the (big endian, hex encoded) OS/ABI-specific encoding of the 23590the load module associated with the thread local storage. For example, 23591a @sc{gnu}/Linux system will pass the link map address of the shared 23592object associated with the thread local storage under consideration. 23593Other operating environments may choose to represent the load module 23594differently, so the precise meaning of this parameter will vary. 23595 23596Reply: 23597@table @samp 23598@item @var{XX}@dots{} 23599Hex encoded (big endian) bytes representing the address of the thread 23600local storage requested. 23601 23602@item E @var{nn} 23603An error occurred. @var{nn} are hex digits. 23604 23605@item 23606An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub. 23607@end table 23608 23609@item qL @var{startflag} @var{threadcount} @var{nextthread} 23610Obtain thread information from RTOS. Where: @var{startflag} (one hex 23611digit) is one to indicate the first query and zero to indicate a 23612subsequent query; @var{threadcount} (two hex digits) is the maximum 23613number of threads the response packet can contain; and @var{nextthread} 23614(eight hex digits), for subsequent queries (@var{startflag} is zero), is 23615returned in the response as @var{argthread}. 23616 23617Don't use this packet; use the @samp{qfThreadInfo} query instead (see above). 23618 23619Reply: 23620@table @samp 23621@item qM @var{count} @var{done} @var{argthread} @var{thread}@dots{} 23622Where: @var{count} (two hex digits) is the number of threads being 23623returned; @var{done} (one hex digit) is zero to indicate more threads 23624and one indicates no further threads; @var{argthreadid} (eight hex 23625digits) is @var{nextthread} from the request packet; @var{thread}@dots{} 23626is a sequence of thread IDs from the target. @var{threadid} (eight hex 23627digits). See @code{remote.c:parse_threadlist_response()}. 23628@end table 23629 23630@item qOffsets 23631@cindex section offsets, remote request 23632@cindex @samp{qOffsets} packet 23633Get section offsets that the target used when relocating the downloaded 23634image. 23635 23636Reply: 23637@table @samp 23638@item Text=@var{xxx};Data=@var{yyy}@r{[};Bss=@var{zzz}@r{]} 23639Relocate the @code{Text} section by @var{xxx} from its original address. 23640Relocate the @code{Data} section by @var{yyy} from its original address. 23641If the object file format provides segment information (e.g.@: @sc{elf} 23642@samp{PT_LOAD} program headers), @value{GDBN} will relocate entire 23643segments by the supplied offsets. 23644 23645@emph{Note: while a @code{Bss} offset may be included in the response, 23646@value{GDBN} ignores this and instead applies the @code{Data} offset 23647to the @code{Bss} section.} 23648 23649@item TextSeg=@var{xxx}@r{[};DataSeg=@var{yyy}@r{]} 23650Relocate the first segment of the object file, which conventionally 23651contains program code, to a starting address of @var{xxx}. If 23652@samp{DataSeg} is specified, relocate the second segment, which 23653conventionally contains modifiable data, to a starting address of 23654@var{yyy}. @value{GDBN} will report an error if the object file 23655does not contain segment information, or does not contain at least 23656as many segments as mentioned in the reply. Extra segments are 23657kept at fixed offsets relative to the last relocated segment. 23658@end table 23659 23660@item qP @var{mode} @var{threadid} 23661@cindex thread information, remote request 23662@cindex @samp{qP} packet 23663Returns information on @var{threadid}. Where: @var{mode} is a hex 23664encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID. 23665 23666Don't use this packet; use the @samp{qThreadExtraInfo} query instead 23667(see below). 23668 23669Reply: see @code{remote.c:remote_unpack_thread_info_response()}. 23670 23671@item QPassSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{} 23672@cindex pass signals to inferior, remote request 23673@cindex @samp{QPassSignals} packet 23674@anchor{QPassSignals} 23675Each listed @var{signal} should be passed directly to the inferior process. 23676Signals are numbered identically to continue packets and stop replies 23677(@pxref{Stop Reply Packets}). Each @var{signal} list item should be 23678strictly greater than the previous item. These signals do not need to stop 23679the inferior, or be reported to @value{GDBN}. All other signals should be 23680reported to @value{GDBN}. Multiple @samp{QPassSignals} packets do not 23681combine; any earlier @samp{QPassSignals} list is completely replaced by the 23682new list. This packet improves performance when using @samp{handle 23683@var{signal} nostop noprint pass}. 23684 23685Reply: 23686@table @samp 23687@item OK 23688The request succeeded. 23689 23690@item E @var{nn} 23691An error occurred. @var{nn} are hex digits. 23692 23693@item 23694An empty reply indicates that @samp{QPassSignals} is not supported by 23695the stub. 23696@end table 23697 23698Use of this packet is controlled by the @code{set remote pass-signals} 23699command (@pxref{Remote Configuration, set remote pass-signals}). 23700This packet is not probed by default; the remote stub must request it, 23701by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 23702 23703@item qRcmd,@var{command} 23704@cindex execute remote command, remote request 23705@cindex @samp{qRcmd} packet 23706@var{command} (hex encoded) is passed to the local interpreter for 23707execution. Invalid commands should be reported using the output 23708string. Before the final result packet, the target may also respond 23709with a number of intermediate @samp{O@var{output}} console output 23710packets. @emph{Implementors should note that providing access to a 23711stubs's interpreter may have security implications}. 23712 23713Reply: 23714@table @samp 23715@item OK 23716A command response with no output. 23717@item @var{OUTPUT} 23718A command response with the hex encoded output string @var{OUTPUT}. 23719@item E @var{NN} 23720Indicate a badly formed request. 23721@item 23722An empty reply indicates that @samp{qRcmd} is not recognized. 23723@end table 23724 23725(Note that the @code{qRcmd} packet's name is separated from the 23726command by a @samp{,}, not a @samp{:}, contrary to the naming 23727conventions above. Please don't use this packet as a model for new 23728packets.) 23729 23730@item qSupported @r{[}:@var{gdbfeature} @r{[};@var{gdbfeature}@r{]}@dots{} @r{]} 23731@cindex supported packets, remote query 23732@cindex features of the remote protocol 23733@cindex @samp{qSupported} packet 23734@anchor{qSupported} 23735Tell the remote stub about features supported by @value{GDBN}, and 23736query the stub for features it supports. This packet allows 23737@value{GDBN} and the remote stub to take advantage of each others' 23738features. @samp{qSupported} also consolidates multiple feature probes 23739at startup, to improve @value{GDBN} performance---a single larger 23740packet performs better than multiple smaller probe packets on 23741high-latency links. Some features may enable behavior which must not 23742be on by default, e.g.@: because it would confuse older clients or 23743stubs. Other features may describe packets which could be 23744automatically probed for, but are not. These features must be 23745reported before @value{GDBN} will use them. This ``default 23746unsupported'' behavior is not appropriate for all packets, but it 23747helps to keep the initial connection time under control with new 23748versions of @value{GDBN} which support increasing numbers of packets. 23749 23750Reply: 23751@table @samp 23752@item @var{stubfeature} @r{[};@var{stubfeature}@r{]}@dots{} 23753The stub supports or does not support each returned @var{stubfeature}, 23754depending on the form of each @var{stubfeature} (see below for the 23755possible forms). 23756@item 23757An empty reply indicates that @samp{qSupported} is not recognized, 23758or that no features needed to be reported to @value{GDBN}. 23759@end table 23760 23761The allowed forms for each feature (either a @var{gdbfeature} in the 23762@samp{qSupported} packet, or a @var{stubfeature} in the response) 23763are: 23764 23765@table @samp 23766@item @var{name}=@var{value} 23767The remote protocol feature @var{name} is supported, and associated 23768with the specified @var{value}. The format of @var{value} depends 23769on the feature, but it must not include a semicolon. 23770@item @var{name}+ 23771The remote protocol feature @var{name} is supported, and does not 23772need an associated value. 23773@item @var{name}- 23774The remote protocol feature @var{name} is not supported. 23775@item @var{name}? 23776The remote protocol feature @var{name} may be supported, and 23777@value{GDBN} should auto-detect support in some other way when it is 23778needed. This form will not be used for @var{gdbfeature} notifications, 23779but may be used for @var{stubfeature} responses. 23780@end table 23781 23782Whenever the stub receives a @samp{qSupported} request, the 23783supplied set of @value{GDBN} features should override any previous 23784request. This allows @value{GDBN} to put the stub in a known 23785state, even if the stub had previously been communicating with 23786a different version of @value{GDBN}. 23787 23788No values of @var{gdbfeature} (for the packet sent by @value{GDBN}) 23789are defined yet. Stubs should ignore any unknown values for 23790@var{gdbfeature}. Any @value{GDBN} which sends a @samp{qSupported} 23791packet supports receiving packets of unlimited length (earlier 23792versions of @value{GDBN} may reject overly long responses). Values 23793for @var{gdbfeature} may be defined in the future to let the stub take 23794advantage of new features in @value{GDBN}, e.g.@: incompatible 23795improvements in the remote protocol---support for unlimited length 23796responses would be a @var{gdbfeature} example, if it were not implied by 23797the @samp{qSupported} query. The stub's reply should be independent 23798of the @var{gdbfeature} entries sent by @value{GDBN}; first @value{GDBN} 23799describes all the features it supports, and then the stub replies with 23800all the features it supports. 23801 23802Similarly, @value{GDBN} will silently ignore unrecognized stub feature 23803responses, as long as each response uses one of the standard forms. 23804 23805Some features are flags. A stub which supports a flag feature 23806should respond with a @samp{+} form response. Other features 23807require values, and the stub should respond with an @samp{=} 23808form response. 23809 23810Each feature has a default value, which @value{GDBN} will use if 23811@samp{qSupported} is not available or if the feature is not mentioned 23812in the @samp{qSupported} response. The default values are fixed; a 23813stub is free to omit any feature responses that match the defaults. 23814 23815Not all features can be probed, but for those which can, the probing 23816mechanism is useful: in some cases, a stub's internal 23817architecture may not allow the protocol layer to know some information 23818about the underlying target in advance. This is especially common in 23819stubs which may be configured for multiple targets. 23820 23821These are the currently defined stub features and their properties: 23822 23823@multitable @columnfractions 0.35 0.2 0.12 0.2 23824@c NOTE: The first row should be @headitem, but we do not yet require 23825@c a new enough version of Texinfo (4.7) to use @headitem. 23826@item Feature Name 23827@tab Value Required 23828@tab Default 23829@tab Probe Allowed 23830 23831@item @samp{PacketSize} 23832@tab Yes 23833@tab @samp{-} 23834@tab No 23835 23836@item @samp{qXfer:auxv:read} 23837@tab No 23838@tab @samp{-} 23839@tab Yes 23840 23841@item @samp{qXfer:features:read} 23842@tab No 23843@tab @samp{-} 23844@tab Yes 23845 23846@item @samp{qXfer:libraries:read} 23847@tab No 23848@tab @samp{-} 23849@tab Yes 23850 23851@item @samp{qXfer:memory-map:read} 23852@tab No 23853@tab @samp{-} 23854@tab Yes 23855 23856@item @samp{qXfer:spu:read} 23857@tab No 23858@tab @samp{-} 23859@tab Yes 23860 23861@item @samp{qXfer:spu:write} 23862@tab No 23863@tab @samp{-} 23864@tab Yes 23865 23866@item @samp{QPassSignals} 23867@tab No 23868@tab @samp{-} 23869@tab Yes 23870 23871@end multitable 23872 23873These are the currently defined stub features, in more detail: 23874 23875@table @samp 23876@cindex packet size, remote protocol 23877@item PacketSize=@var{bytes} 23878The remote stub can accept packets up to at least @var{bytes} in 23879length. @value{GDBN} will send packets up to this size for bulk 23880transfers, and will never send larger packets. This is a limit on the 23881data characters in the packet, including the frame and checksum. 23882There is no trailing NUL byte in a remote protocol packet; if the stub 23883stores packets in a NUL-terminated format, it should allow an extra 23884byte in its buffer for the NUL. If this stub feature is not supported, 23885@value{GDBN} guesses based on the size of the @samp{g} packet response. 23886 23887@item qXfer:auxv:read 23888The remote stub understands the @samp{qXfer:auxv:read} packet 23889(@pxref{qXfer auxiliary vector read}). 23890 23891@item qXfer:features:read 23892The remote stub understands the @samp{qXfer:features:read} packet 23893(@pxref{qXfer target description read}). 23894 23895@item qXfer:libraries:read 23896The remote stub understands the @samp{qXfer:libraries:read} packet 23897(@pxref{qXfer library list read}). 23898 23899@item qXfer:memory-map:read 23900The remote stub understands the @samp{qXfer:memory-map:read} packet 23901(@pxref{qXfer memory map read}). 23902 23903@item qXfer:spu:read 23904The remote stub understands the @samp{qXfer:spu:read} packet 23905(@pxref{qXfer spu read}). 23906 23907@item qXfer:spu:write 23908The remote stub understands the @samp{qXfer:spu:write} packet 23909(@pxref{qXfer spu write}). 23910 23911@item QPassSignals 23912The remote stub understands the @samp{QPassSignals} packet 23913(@pxref{QPassSignals}). 23914 23915@end table 23916 23917@item qSymbol:: 23918@cindex symbol lookup, remote request 23919@cindex @samp{qSymbol} packet 23920Notify the target that @value{GDBN} is prepared to serve symbol lookup 23921requests. Accept requests from the target for the values of symbols. 23922 23923Reply: 23924@table @samp 23925@item OK 23926The target does not need to look up any (more) symbols. 23927@item qSymbol:@var{sym_name} 23928The target requests the value of symbol @var{sym_name} (hex encoded). 23929@value{GDBN} may provide the value by using the 23930@samp{qSymbol:@var{sym_value}:@var{sym_name}} message, described 23931below. 23932@end table 23933 23934@item qSymbol:@var{sym_value}:@var{sym_name} 23935Set the value of @var{sym_name} to @var{sym_value}. 23936 23937@var{sym_name} (hex encoded) is the name of a symbol whose value the 23938target has previously requested. 23939 23940@var{sym_value} (hex) is the value for symbol @var{sym_name}. If 23941@value{GDBN} cannot supply a value for @var{sym_name}, then this field 23942will be empty. 23943 23944Reply: 23945@table @samp 23946@item OK 23947The target does not need to look up any (more) symbols. 23948@item qSymbol:@var{sym_name} 23949The target requests the value of a new symbol @var{sym_name} (hex 23950encoded). @value{GDBN} will continue to supply the values of symbols 23951(if available), until the target ceases to request them. 23952@end table 23953 23954@item QTDP 23955@itemx QTFrame 23956@xref{Tracepoint Packets}. 23957 23958@item qThreadExtraInfo,@var{id} 23959@cindex thread attributes info, remote request 23960@cindex @samp{qThreadExtraInfo} packet 23961Obtain a printable string description of a thread's attributes from 23962the target OS. @var{id} is a thread-id in big-endian hex. This 23963string may contain anything that the target OS thinks is interesting 23964for @value{GDBN} to tell the user about the thread. The string is 23965displayed in @value{GDBN}'s @code{info threads} display. Some 23966examples of possible thread extra info strings are @samp{Runnable}, or 23967@samp{Blocked on Mutex}. 23968 23969Reply: 23970@table @samp 23971@item @var{XX}@dots{} 23972Where @samp{@var{XX}@dots{}} is a hex encoding of @sc{ascii} data, 23973comprising the printable string containing the extra information about 23974the thread's attributes. 23975@end table 23976 23977(Note that the @code{qThreadExtraInfo} packet's name is separated from 23978the command by a @samp{,}, not a @samp{:}, contrary to the naming 23979conventions above. Please don't use this packet as a model for new 23980packets.) 23981 23982@item QTStart 23983@itemx QTStop 23984@itemx QTinit 23985@itemx QTro 23986@itemx qTStatus 23987@xref{Tracepoint Packets}. 23988 23989@item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length} 23990@cindex read special object, remote request 23991@cindex @samp{qXfer} packet 23992@anchor{qXfer read} 23993Read uninterpreted bytes from the target's special data area 23994identified by the keyword @var{object}. Request @var{length} bytes 23995starting at @var{offset} bytes into the data. The content and 23996encoding of @var{annex} is specific to @var{object}; it can supply 23997additional details about what data to access. 23998 23999Here are the specific requests of this form defined so far. All 24000@samp{qXfer:@var{object}:read:@dots{}} requests use the same reply 24001formats, listed below. 24002 24003@table @samp 24004@item qXfer:auxv:read::@var{offset},@var{length} 24005@anchor{qXfer auxiliary vector read} 24006Access the target's @dfn{auxiliary vector}. @xref{OS Information, 24007auxiliary vector}. Note @var{annex} must be empty. 24008 24009This packet is not probed by default; the remote stub must request it, 24010by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 24011 24012@item qXfer:features:read:@var{annex}:@var{offset},@var{length} 24013@anchor{qXfer target description read} 24014Access the @dfn{target description}. @xref{Target Descriptions}. The 24015annex specifies which XML document to access. The main description is 24016always loaded from the @samp{target.xml} annex. 24017 24018This packet is not probed by default; the remote stub must request it, 24019by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 24020 24021@item qXfer:libraries:read:@var{annex}:@var{offset},@var{length} 24022@anchor{qXfer library list read} 24023Access the target's list of loaded libraries. @xref{Library List Format}. 24024The annex part of the generic @samp{qXfer} packet must be empty 24025(@pxref{qXfer read}). 24026 24027Targets which maintain a list of libraries in the program's memory do 24028not need to implement this packet; it is designed for platforms where 24029the operating system manages the list of loaded libraries. 24030 24031This packet is not probed by default; the remote stub must request it, 24032by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 24033 24034@item qXfer:memory-map:read::@var{offset},@var{length} 24035@anchor{qXfer memory map read} 24036Access the target's @dfn{memory-map}. @xref{Memory Map Format}. The 24037annex part of the generic @samp{qXfer} packet must be empty 24038(@pxref{qXfer read}). 24039 24040This packet is not probed by default; the remote stub must request it, 24041by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 24042 24043@item qXfer:spu:read:@var{annex}:@var{offset},@var{length} 24044@anchor{qXfer spu read} 24045Read contents of an @code{spufs} file on the target system. The 24046annex specifies which file to read; it must be of the form 24047@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID 24048in the target process, and @var{name} identifes the @code{spufs} file 24049in that context to be accessed. 24050 24051This packet is not probed by default; the remote stub must request it, 24052by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 24053@end table 24054 24055Reply: 24056@table @samp 24057@item m @var{data} 24058Data @var{data} (@pxref{Binary Data}) has been read from the 24059target. There may be more data at a higher address (although 24060it is permitted to return @samp{m} even for the last valid 24061block of data, as long as at least one byte of data was read). 24062@var{data} may have fewer bytes than the @var{length} in the 24063request. 24064 24065@item l @var{data} 24066Data @var{data} (@pxref{Binary Data}) has been read from the target. 24067There is no more data to be read. @var{data} may have fewer bytes 24068than the @var{length} in the request. 24069 24070@item l 24071The @var{offset} in the request is at the end of the data. 24072There is no more data to be read. 24073 24074@item E00 24075The request was malformed, or @var{annex} was invalid. 24076 24077@item E @var{nn} 24078The offset was invalid, or there was an error encountered reading the data. 24079@var{nn} is a hex-encoded @code{errno} value. 24080 24081@item 24082An empty reply indicates the @var{object} string was not recognized by 24083the stub, or that the object does not support reading. 24084@end table 24085 24086@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{} 24087@cindex write data into object, remote request 24088Write uninterpreted bytes into the target's special data area 24089identified by the keyword @var{object}, starting at @var{offset} bytes 24090into the data. @var{data}@dots{} is the binary-encoded data 24091(@pxref{Binary Data}) to be written. The content and encoding of @var{annex} 24092is specific to @var{object}; it can supply additional details about what data 24093to access. 24094 24095Here are the specific requests of this form defined so far. All 24096@samp{qXfer:@var{object}:write:@dots{}} requests use the same reply 24097formats, listed below. 24098 24099@table @samp 24100@item qXfer:@var{spu}:write:@var{annex}:@var{offset}:@var{data}@dots{} 24101@anchor{qXfer spu write} 24102Write @var{data} to an @code{spufs} file on the target system. The 24103annex specifies which file to write; it must be of the form 24104@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID 24105in the target process, and @var{name} identifes the @code{spufs} file 24106in that context to be accessed. 24107 24108This packet is not probed by default; the remote stub must request it, 24109by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). 24110@end table 24111 24112Reply: 24113@table @samp 24114@item @var{nn} 24115@var{nn} (hex encoded) is the number of bytes written. 24116This may be fewer bytes than supplied in the request. 24117 24118@item E00 24119The request was malformed, or @var{annex} was invalid. 24120 24121@item E @var{nn} 24122The offset was invalid, or there was an error encountered writing the data. 24123@var{nn} is a hex-encoded @code{errno} value. 24124 24125@item 24126An empty reply indicates the @var{object} string was not 24127recognized by the stub, or that the object does not support writing. 24128@end table 24129 24130@item qXfer:@var{object}:@var{operation}:@dots{} 24131Requests of this form may be added in the future. When a stub does 24132not recognize the @var{object} keyword, or its support for 24133@var{object} does not recognize the @var{operation} keyword, the stub 24134must respond with an empty packet. 24135 24136@end table 24137 24138@node Register Packet Format 24139@section Register Packet Format 24140 24141The following @code{g}/@code{G} packets have previously been defined. 24142In the below, some thirty-two bit registers are transferred as 24143sixty-four bits. Those registers should be zero/sign extended (which?) 24144to fill the space allocated. Register bytes are transferred in target 24145byte order. The two nibbles within a register byte are transferred 24146most-significant - least-significant. 24147 24148@table @r 24149 24150@item MIPS32 24151 24152All registers are transferred as thirty-two bit quantities in the order: 2415332 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point 24154registers; fsr; fir; fp. 24155 24156@item MIPS64 24157 24158All registers are transferred as sixty-four bit quantities (including 24159thirty-two bit registers such as @code{sr}). The ordering is the same 24160as @code{MIPS32}. 24161 24162@end table 24163 24164@node Tracepoint Packets 24165@section Tracepoint Packets 24166@cindex tracepoint packets 24167@cindex packets, tracepoint 24168 24169Here we describe the packets @value{GDBN} uses to implement 24170tracepoints (@pxref{Tracepoints}). 24171 24172@table @samp 24173 24174@item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}@r{[}-@r{]} 24175Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena} 24176is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then 24177the tracepoint is disabled. @var{step} is the tracepoint's step 24178count, and @var{pass} is its pass count. If the trailing @samp{-} is 24179present, further @samp{QTDP} packets will follow to specify this 24180tracepoint's actions. 24181 24182Replies: 24183@table @samp 24184@item OK 24185The packet was understood and carried out. 24186@item 24187The packet was not recognized. 24188@end table 24189 24190@item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]} 24191Define actions to be taken when a tracepoint is hit. @var{n} and 24192@var{addr} must be the same as in the initial @samp{QTDP} packet for 24193this tracepoint. This packet may only be sent immediately after 24194another @samp{QTDP} packet that ended with a @samp{-}. If the 24195trailing @samp{-} is present, further @samp{QTDP} packets will follow, 24196specifying more actions for this tracepoint. 24197 24198In the series of action packets for a given tracepoint, at most one 24199can have an @samp{S} before its first @var{action}. If such a packet 24200is sent, it and the following packets define ``while-stepping'' 24201actions. Any prior packets define ordinary actions --- that is, those 24202taken when the tracepoint is first hit. If no action packet has an 24203@samp{S}, then all the packets in the series specify ordinary 24204tracepoint actions. 24205 24206The @samp{@var{action}@dots{}} portion of the packet is a series of 24207actions, concatenated without separators. Each action has one of the 24208following forms: 24209 24210@table @samp 24211 24212@item R @var{mask} 24213Collect the registers whose bits are set in @var{mask}. @var{mask} is 24214a hexadecimal number whose @var{i}'th bit is set if register number 24215@var{i} should be collected. (The least significant bit is numbered 24216zero.) Note that @var{mask} may be any number of digits long; it may 24217not fit in a 32-bit word. 24218 24219@item M @var{basereg},@var{offset},@var{len} 24220Collect @var{len} bytes of memory starting at the address in register 24221number @var{basereg}, plus @var{offset}. If @var{basereg} is 24222@samp{-1}, then the range has a fixed address: @var{offset} is the 24223address of the lowest byte to collect. The @var{basereg}, 24224@var{offset}, and @var{len} parameters are all unsigned hexadecimal 24225values (the @samp{-1} value for @var{basereg} is a special case). 24226 24227@item X @var{len},@var{expr} 24228Evaluate @var{expr}, whose length is @var{len}, and collect memory as 24229it directs. @var{expr} is an agent expression, as described in 24230@ref{Agent Expressions}. Each byte of the expression is encoded as a 24231two-digit hex number in the packet; @var{len} is the number of bytes 24232in the expression (and thus one-half the number of hex digits in the 24233packet). 24234 24235@end table 24236 24237Any number of actions may be packed together in a single @samp{QTDP} 24238packet, as long as the packet does not exceed the maximum packet 24239length (400 bytes, for many stubs). There may be only one @samp{R} 24240action per tracepoint, and it must precede any @samp{M} or @samp{X} 24241actions. Any registers referred to by @samp{M} and @samp{X} actions 24242must be collected by a preceding @samp{R} action. (The 24243``while-stepping'' actions are treated as if they were attached to a 24244separate tracepoint, as far as these restrictions are concerned.) 24245 24246Replies: 24247@table @samp 24248@item OK 24249The packet was understood and carried out. 24250@item 24251The packet was not recognized. 24252@end table 24253 24254@item QTFrame:@var{n} 24255Select the @var{n}'th tracepoint frame from the buffer, and use the 24256register and memory contents recorded there to answer subsequent 24257request packets from @value{GDBN}. 24258 24259A successful reply from the stub indicates that the stub has found the 24260requested frame. The response is a series of parts, concatenated 24261without separators, describing the frame we selected. Each part has 24262one of the following forms: 24263 24264@table @samp 24265@item F @var{f} 24266The selected frame is number @var{n} in the trace frame buffer; 24267@var{f} is a hexadecimal number. If @var{f} is @samp{-1}, then there 24268was no frame matching the criteria in the request packet. 24269 24270@item T @var{t} 24271The selected trace frame records a hit of tracepoint number @var{t}; 24272@var{t} is a hexadecimal number. 24273 24274@end table 24275 24276@item QTFrame:pc:@var{addr} 24277Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the 24278currently selected frame whose PC is @var{addr}; 24279@var{addr} is a hexadecimal number. 24280 24281@item QTFrame:tdp:@var{t} 24282Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the 24283currently selected frame that is a hit of tracepoint @var{t}; @var{t} 24284is a hexadecimal number. 24285 24286@item QTFrame:range:@var{start}:@var{end} 24287Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the 24288currently selected frame whose PC is between @var{start} (inclusive) 24289and @var{end} (exclusive); @var{start} and @var{end} are hexadecimal 24290numbers. 24291 24292@item QTFrame:outside:@var{start}:@var{end} 24293Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first 24294frame @emph{outside} the given range of addresses. 24295 24296@item QTStart 24297Begin the tracepoint experiment. Begin collecting data from tracepoint 24298hits in the trace frame buffer. 24299 24300@item QTStop 24301End the tracepoint experiment. Stop collecting trace frames. 24302 24303@item QTinit 24304Clear the table of tracepoints, and empty the trace frame buffer. 24305 24306@item QTro:@var{start1},@var{end1}:@var{start2},@var{end2}:@dots{} 24307Establish the given ranges of memory as ``transparent''. The stub 24308will answer requests for these ranges from memory's current contents, 24309if they were not collected as part of the tracepoint hit. 24310 24311@value{GDBN} uses this to mark read-only regions of memory, like those 24312containing program code. Since these areas never change, they should 24313still have the same contents they did when the tracepoint was hit, so 24314there's no reason for the stub to refuse to provide their contents. 24315 24316@item qTStatus 24317Ask the stub if there is a trace experiment running right now. 24318 24319Replies: 24320@table @samp 24321@item T0 24322There is no trace experiment running. 24323@item T1 24324There is a trace experiment running. 24325@end table 24326 24327@end table 24328 24329 24330@node Interrupts 24331@section Interrupts 24332@cindex interrupts (remote protocol) 24333 24334When a program on the remote target is running, @value{GDBN} may 24335attempt to interrupt it by sending a @samp{Ctrl-C} or a @code{BREAK}, 24336control of which is specified via @value{GDBN}'s @samp{remotebreak} 24337setting (@pxref{set remotebreak}). 24338 24339The precise meaning of @code{BREAK} is defined by the transport 24340mechanism and may, in fact, be undefined. @value{GDBN} does 24341not currently define a @code{BREAK} mechanism for any of the network 24342interfaces. 24343 24344@samp{Ctrl-C}, on the other hand, is defined and implemented for all 24345transport mechanisms. It is represented by sending the single byte 24346@code{0x03} without any of the usual packet overhead described in 24347the Overview section (@pxref{Overview}). When a @code{0x03} byte is 24348transmitted as part of a packet, it is considered to be packet data 24349and does @emph{not} represent an interrupt. E.g., an @samp{X} packet 24350(@pxref{X packet}), used for binary downloads, may include an unescaped 24351@code{0x03} as part of its packet. 24352 24353Stubs are not required to recognize these interrupt mechanisms and the 24354precise meaning associated with receipt of the interrupt is 24355implementation defined. If the stub is successful at interrupting the 24356running program, it is expected that it will send one of the Stop 24357Reply Packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result 24358of successfully stopping the program. Interrupts received while the 24359program is stopped will be discarded. 24360 24361@node Examples 24362@section Examples 24363 24364Example sequence of a target being re-started. Notice how the restart 24365does not get any direct output: 24366 24367@smallexample 24368-> @code{R00} 24369<- @code{+} 24370@emph{target restarts} 24371-> @code{?} 24372<- @code{+} 24373<- @code{T001:1234123412341234} 24374-> @code{+} 24375@end smallexample 24376 24377Example sequence of a target being stepped by a single instruction: 24378 24379@smallexample 24380-> @code{G1445@dots{}} 24381<- @code{+} 24382-> @code{s} 24383<- @code{+} 24384@emph{time passes} 24385<- @code{T001:1234123412341234} 24386-> @code{+} 24387-> @code{g} 24388<- @code{+} 24389<- @code{1455@dots{}} 24390-> @code{+} 24391@end smallexample 24392 24393@node File-I/O Remote Protocol Extension 24394@section File-I/O Remote Protocol Extension 24395@cindex File-I/O remote protocol extension 24396 24397@menu 24398* File-I/O Overview:: 24399* Protocol Basics:: 24400* The F Request Packet:: 24401* The F Reply Packet:: 24402* The Ctrl-C Message:: 24403* Console I/O:: 24404* List of Supported Calls:: 24405* Protocol-specific Representation of Datatypes:: 24406* Constants:: 24407* File-I/O Examples:: 24408@end menu 24409 24410@node File-I/O Overview 24411@subsection File-I/O Overview 24412@cindex file-i/o overview 24413 24414The @dfn{File I/O remote protocol extension} (short: File-I/O) allows the 24415target to use the host's file system and console I/O to perform various 24416system calls. System calls on the target system are translated into a 24417remote protocol packet to the host system, which then performs the needed 24418actions and returns a response packet to the target system. 24419This simulates file system operations even on targets that lack file systems. 24420 24421The protocol is defined to be independent of both the host and target systems. 24422It uses its own internal representation of datatypes and values. Both 24423@value{GDBN} and the target's @value{GDBN} stub are responsible for 24424translating the system-dependent value representations into the internal 24425protocol representations when data is transmitted. 24426 24427The communication is synchronous. A system call is possible only when 24428@value{GDBN} is waiting for a response from the @samp{C}, @samp{c}, @samp{S} 24429or @samp{s} packets. While @value{GDBN} handles the request for a system call, 24430the target is stopped to allow deterministic access to the target's 24431memory. Therefore File-I/O is not interruptible by target signals. On 24432the other hand, it is possible to interrupt File-I/O by a user interrupt 24433(@samp{Ctrl-C}) within @value{GDBN}. 24434 24435The target's request to perform a host system call does not finish 24436the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action. That means, 24437after finishing the system call, the target returns to continuing the 24438previous activity (continue, step). No additional continue or step 24439request from @value{GDBN} is required. 24440 24441@smallexample 24442(@value{GDBP}) continue 24443 <- target requests 'system call X' 24444 target is stopped, @value{GDBN} executes system call 24445 -> @value{GDBN} returns result 24446 ... target continues, @value{GDBN} returns to wait for the target 24447 <- target hits breakpoint and sends a Txx packet 24448@end smallexample 24449 24450The protocol only supports I/O on the console and to regular files on 24451the host file system. Character or block special devices, pipes, 24452named pipes, sockets or any other communication method on the host 24453system are not supported by this protocol. 24454 24455@node Protocol Basics 24456@subsection Protocol Basics 24457@cindex protocol basics, file-i/o 24458 24459The File-I/O protocol uses the @code{F} packet as the request as well 24460as reply packet. Since a File-I/O system call can only occur when 24461@value{GDBN} is waiting for a response from the continuing or stepping target, 24462the File-I/O request is a reply that @value{GDBN} has to expect as a result 24463of a previous @samp{C}, @samp{c}, @samp{S} or @samp{s} packet. 24464This @code{F} packet contains all information needed to allow @value{GDBN} 24465to call the appropriate host system call: 24466 24467@itemize @bullet 24468@item 24469A unique identifier for the requested system call. 24470 24471@item 24472All parameters to the system call. Pointers are given as addresses 24473in the target memory address space. Pointers to strings are given as 24474pointer/length pair. Numerical values are given as they are. 24475Numerical control flags are given in a protocol-specific representation. 24476 24477@end itemize 24478 24479At this point, @value{GDBN} has to perform the following actions. 24480 24481@itemize @bullet 24482@item 24483If the parameters include pointer values to data needed as input to a 24484system call, @value{GDBN} requests this data from the target with a 24485standard @code{m} packet request. This additional communication has to be 24486expected by the target implementation and is handled as any other @code{m} 24487packet. 24488 24489@item 24490@value{GDBN} translates all value from protocol representation to host 24491representation as needed. Datatypes are coerced into the host types. 24492 24493@item 24494@value{GDBN} calls the system call. 24495 24496@item 24497It then coerces datatypes back to protocol representation. 24498 24499@item 24500If the system call is expected to return data in buffer space specified 24501by pointer parameters to the call, the data is transmitted to the 24502target using a @code{M} or @code{X} packet. This packet has to be expected 24503by the target implementation and is handled as any other @code{M} or @code{X} 24504packet. 24505 24506@end itemize 24507 24508Eventually @value{GDBN} replies with another @code{F} packet which contains all 24509necessary information for the target to continue. This at least contains 24510 24511@itemize @bullet 24512@item 24513Return value. 24514 24515@item 24516@code{errno}, if has been changed by the system call. 24517 24518@item 24519``Ctrl-C'' flag. 24520 24521@end itemize 24522 24523After having done the needed type and value coercion, the target continues 24524the latest continue or step action. 24525 24526@node The F Request Packet 24527@subsection The @code{F} Request Packet 24528@cindex file-i/o request packet 24529@cindex @code{F} request packet 24530 24531The @code{F} request packet has the following format: 24532 24533@table @samp 24534@item F@var{call-id},@var{parameter@dots{}} 24535 24536@var{call-id} is the identifier to indicate the host system call to be called. 24537This is just the name of the function. 24538 24539@var{parameter@dots{}} are the parameters to the system call. 24540Parameters are hexadecimal integer values, either the actual values in case 24541of scalar datatypes, pointers to target buffer space in case of compound 24542datatypes and unspecified memory areas, or pointer/length pairs in case 24543of string parameters. These are appended to the @var{call-id} as a 24544comma-delimited list. All values are transmitted in ASCII 24545string representation, pointer/length pairs separated by a slash. 24546 24547@end table 24548 24549 24550 24551@node The F Reply Packet 24552@subsection The @code{F} Reply Packet 24553@cindex file-i/o reply packet 24554@cindex @code{F} reply packet 24555 24556The @code{F} reply packet has the following format: 24557 24558@table @samp 24559 24560@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call-specific attachment} 24561 24562@var{retcode} is the return code of the system call as hexadecimal value. 24563 24564@var{errno} is the @code{errno} set by the call, in protocol-specific 24565representation. 24566This parameter can be omitted if the call was successful. 24567 24568@var{Ctrl-C flag} is only sent if the user requested a break. In this 24569case, @var{errno} must be sent as well, even if the call was successful. 24570The @var{Ctrl-C flag} itself consists of the character @samp{C}: 24571 24572@smallexample 24573F0,0,C 24574@end smallexample 24575 24576@noindent 24577or, if the call was interrupted before the host call has been performed: 24578 24579@smallexample 24580F-1,4,C 24581@end smallexample 24582 24583@noindent 24584assuming 4 is the protocol-specific representation of @code{EINTR}. 24585 24586@end table 24587 24588 24589@node The Ctrl-C Message 24590@subsection The @samp{Ctrl-C} Message 24591@cindex ctrl-c message, in file-i/o protocol 24592 24593If the @samp{Ctrl-C} flag is set in the @value{GDBN} 24594reply packet (@pxref{The F Reply Packet}), 24595the target should behave as if it had 24596gotten a break message. The meaning for the target is ``system call 24597interrupted by @code{SIGINT}''. Consequentially, the target should actually stop 24598(as with a break message) and return to @value{GDBN} with a @code{T02} 24599packet. 24600 24601It's important for the target to know in which 24602state the system call was interrupted. There are two possible cases: 24603 24604@itemize @bullet 24605@item 24606The system call hasn't been performed on the host yet. 24607 24608@item 24609The system call on the host has been finished. 24610 24611@end itemize 24612 24613These two states can be distinguished by the target by the value of the 24614returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system 24615call hasn't been performed. This is equivalent to the @code{EINTR} handling 24616on POSIX systems. In any other case, the target may presume that the 24617system call has been finished --- successfully or not --- and should behave 24618as if the break message arrived right after the system call. 24619 24620@value{GDBN} must behave reliably. If the system call has not been called 24621yet, @value{GDBN} may send the @code{F} reply immediately, setting @code{EINTR} as 24622@code{errno} in the packet. If the system call on the host has been finished 24623before the user requests a break, the full action must be finished by 24624@value{GDBN}. This requires sending @code{M} or @code{X} packets as necessary. 24625The @code{F} packet may only be sent when either nothing has happened 24626or the full action has been completed. 24627 24628@node Console I/O 24629@subsection Console I/O 24630@cindex console i/o as part of file-i/o 24631 24632By default and if not explicitly closed by the target system, the file 24633descriptors 0, 1 and 2 are connected to the @value{GDBN} console. Output 24634on the @value{GDBN} console is handled as any other file output operation 24635(@code{write(1, @dots{})} or @code{write(2, @dots{})}). Console input is handled 24636by @value{GDBN} so that after the target read request from file descriptor 246370 all following typing is buffered until either one of the following 24638conditions is met: 24639 24640@itemize @bullet 24641@item 24642The user types @kbd{Ctrl-c}. The behaviour is as explained above, and the 24643@code{read} 24644system call is treated as finished. 24645 24646@item 24647The user presses @key{RET}. This is treated as end of input with a trailing 24648newline. 24649 24650@item 24651The user types @kbd{Ctrl-d}. This is treated as end of input. No trailing 24652character (neither newline nor @samp{Ctrl-D}) is appended to the input. 24653 24654@end itemize 24655 24656If the user has typed more characters than fit in the buffer given to 24657the @code{read} call, the trailing characters are buffered in @value{GDBN} until 24658either another @code{read(0, @dots{})} is requested by the target, or debugging 24659is stopped at the user's request. 24660 24661 24662@node List of Supported Calls 24663@subsection List of Supported Calls 24664@cindex list of supported file-i/o calls 24665 24666@menu 24667* open:: 24668* close:: 24669* read:: 24670* write:: 24671* lseek:: 24672* rename:: 24673* unlink:: 24674* stat/fstat:: 24675* gettimeofday:: 24676* isatty:: 24677* system:: 24678@end menu 24679 24680@node open 24681@unnumberedsubsubsec open 24682@cindex open, file-i/o system call 24683 24684@table @asis 24685@item Synopsis: 24686@smallexample 24687int open(const char *pathname, int flags); 24688int open(const char *pathname, int flags, mode_t mode); 24689@end smallexample 24690 24691@item Request: 24692@samp{Fopen,@var{pathptr}/@var{len},@var{flags},@var{mode}} 24693 24694@noindent 24695@var{flags} is the bitwise @code{OR} of the following values: 24696 24697@table @code 24698@item O_CREAT 24699If the file does not exist it will be created. The host 24700rules apply as far as file ownership and time stamps 24701are concerned. 24702 24703@item O_EXCL 24704When used with @code{O_CREAT}, if the file already exists it is 24705an error and open() fails. 24706 24707@item O_TRUNC 24708If the file already exists and the open mode allows 24709writing (@code{O_RDWR} or @code{O_WRONLY} is given) it will be 24710truncated to zero length. 24711 24712@item O_APPEND 24713The file is opened in append mode. 24714 24715@item O_RDONLY 24716The file is opened for reading only. 24717 24718@item O_WRONLY 24719The file is opened for writing only. 24720 24721@item O_RDWR 24722The file is opened for reading and writing. 24723@end table 24724 24725@noindent 24726Other bits are silently ignored. 24727 24728 24729@noindent 24730@var{mode} is the bitwise @code{OR} of the following values: 24731 24732@table @code 24733@item S_IRUSR 24734User has read permission. 24735 24736@item S_IWUSR 24737User has write permission. 24738 24739@item S_IRGRP 24740Group has read permission. 24741 24742@item S_IWGRP 24743Group has write permission. 24744 24745@item S_IROTH 24746Others have read permission. 24747 24748@item S_IWOTH 24749Others have write permission. 24750@end table 24751 24752@noindent 24753Other bits are silently ignored. 24754 24755 24756@item Return value: 24757@code{open} returns the new file descriptor or -1 if an error 24758occurred. 24759 24760@item Errors: 24761 24762@table @code 24763@item EEXIST 24764@var{pathname} already exists and @code{O_CREAT} and @code{O_EXCL} were used. 24765 24766@item EISDIR 24767@var{pathname} refers to a directory. 24768 24769@item EACCES 24770The requested access is not allowed. 24771 24772@item ENAMETOOLONG 24773@var{pathname} was too long. 24774 24775@item ENOENT 24776A directory component in @var{pathname} does not exist. 24777 24778@item ENODEV 24779@var{pathname} refers to a device, pipe, named pipe or socket. 24780 24781@item EROFS 24782@var{pathname} refers to a file on a read-only filesystem and 24783write access was requested. 24784 24785@item EFAULT 24786@var{pathname} is an invalid pointer value. 24787 24788@item ENOSPC 24789No space on device to create the file. 24790 24791@item EMFILE 24792The process already has the maximum number of files open. 24793 24794@item ENFILE 24795The limit on the total number of files open on the system 24796has been reached. 24797 24798@item EINTR 24799The call was interrupted by the user. 24800@end table 24801 24802@end table 24803 24804@node close 24805@unnumberedsubsubsec close 24806@cindex close, file-i/o system call 24807 24808@table @asis 24809@item Synopsis: 24810@smallexample 24811int close(int fd); 24812@end smallexample 24813 24814@item Request: 24815@samp{Fclose,@var{fd}} 24816 24817@item Return value: 24818@code{close} returns zero on success, or -1 if an error occurred. 24819 24820@item Errors: 24821 24822@table @code 24823@item EBADF 24824@var{fd} isn't a valid open file descriptor. 24825 24826@item EINTR 24827The call was interrupted by the user. 24828@end table 24829 24830@end table 24831 24832@node read 24833@unnumberedsubsubsec read 24834@cindex read, file-i/o system call 24835 24836@table @asis 24837@item Synopsis: 24838@smallexample 24839int read(int fd, void *buf, unsigned int count); 24840@end smallexample 24841 24842@item Request: 24843@samp{Fread,@var{fd},@var{bufptr},@var{count}} 24844 24845@item Return value: 24846On success, the number of bytes read is returned. 24847Zero indicates end of file. If count is zero, read 24848returns zero as well. On error, -1 is returned. 24849 24850@item Errors: 24851 24852@table @code 24853@item EBADF 24854@var{fd} is not a valid file descriptor or is not open for 24855reading. 24856 24857@item EFAULT 24858@var{bufptr} is an invalid pointer value. 24859 24860@item EINTR 24861The call was interrupted by the user. 24862@end table 24863 24864@end table 24865 24866@node write 24867@unnumberedsubsubsec write 24868@cindex write, file-i/o system call 24869 24870@table @asis 24871@item Synopsis: 24872@smallexample 24873int write(int fd, const void *buf, unsigned int count); 24874@end smallexample 24875 24876@item Request: 24877@samp{Fwrite,@var{fd},@var{bufptr},@var{count}} 24878 24879@item Return value: 24880On success, the number of bytes written are returned. 24881Zero indicates nothing was written. On error, -1 24882is returned. 24883 24884@item Errors: 24885 24886@table @code 24887@item EBADF 24888@var{fd} is not a valid file descriptor or is not open for 24889writing. 24890 24891@item EFAULT 24892@var{bufptr} is an invalid pointer value. 24893 24894@item EFBIG 24895An attempt was made to write a file that exceeds the 24896host-specific maximum file size allowed. 24897 24898@item ENOSPC 24899No space on device to write the data. 24900 24901@item EINTR 24902The call was interrupted by the user. 24903@end table 24904 24905@end table 24906 24907@node lseek 24908@unnumberedsubsubsec lseek 24909@cindex lseek, file-i/o system call 24910 24911@table @asis 24912@item Synopsis: 24913@smallexample 24914long lseek (int fd, long offset, int flag); 24915@end smallexample 24916 24917@item Request: 24918@samp{Flseek,@var{fd},@var{offset},@var{flag}} 24919 24920@var{flag} is one of: 24921 24922@table @code 24923@item SEEK_SET 24924The offset is set to @var{offset} bytes. 24925 24926@item SEEK_CUR 24927The offset is set to its current location plus @var{offset} 24928bytes. 24929 24930@item SEEK_END 24931The offset is set to the size of the file plus @var{offset} 24932bytes. 24933@end table 24934 24935@item Return value: 24936On success, the resulting unsigned offset in bytes from 24937the beginning of the file is returned. Otherwise, a 24938value of -1 is returned. 24939 24940@item Errors: 24941 24942@table @code 24943@item EBADF 24944@var{fd} is not a valid open file descriptor. 24945 24946@item ESPIPE 24947@var{fd} is associated with the @value{GDBN} console. 24948 24949@item EINVAL 24950@var{flag} is not a proper value. 24951 24952@item EINTR 24953The call was interrupted by the user. 24954@end table 24955 24956@end table 24957 24958@node rename 24959@unnumberedsubsubsec rename 24960@cindex rename, file-i/o system call 24961 24962@table @asis 24963@item Synopsis: 24964@smallexample 24965int rename(const char *oldpath, const char *newpath); 24966@end smallexample 24967 24968@item Request: 24969@samp{Frename,@var{oldpathptr}/@var{len},@var{newpathptr}/@var{len}} 24970 24971@item Return value: 24972On success, zero is returned. On error, -1 is returned. 24973 24974@item Errors: 24975 24976@table @code 24977@item EISDIR 24978@var{newpath} is an existing directory, but @var{oldpath} is not a 24979directory. 24980 24981@item EEXIST 24982@var{newpath} is a non-empty directory. 24983 24984@item EBUSY 24985@var{oldpath} or @var{newpath} is a directory that is in use by some 24986process. 24987 24988@item EINVAL 24989An attempt was made to make a directory a subdirectory 24990of itself. 24991 24992@item ENOTDIR 24993A component used as a directory in @var{oldpath} or new 24994path is not a directory. Or @var{oldpath} is a directory 24995and @var{newpath} exists but is not a directory. 24996 24997@item EFAULT 24998@var{oldpathptr} or @var{newpathptr} are invalid pointer values. 24999 25000@item EACCES 25001No access to the file or the path of the file. 25002 25003@item ENAMETOOLONG 25004 25005@var{oldpath} or @var{newpath} was too long. 25006 25007@item ENOENT 25008A directory component in @var{oldpath} or @var{newpath} does not exist. 25009 25010@item EROFS 25011The file is on a read-only filesystem. 25012 25013@item ENOSPC 25014The device containing the file has no room for the new 25015directory entry. 25016 25017@item EINTR 25018The call was interrupted by the user. 25019@end table 25020 25021@end table 25022 25023@node unlink 25024@unnumberedsubsubsec unlink 25025@cindex unlink, file-i/o system call 25026 25027@table @asis 25028@item Synopsis: 25029@smallexample 25030int unlink(const char *pathname); 25031@end smallexample 25032 25033@item Request: 25034@samp{Funlink,@var{pathnameptr}/@var{len}} 25035 25036@item Return value: 25037On success, zero is returned. On error, -1 is returned. 25038 25039@item Errors: 25040 25041@table @code 25042@item EACCES 25043No access to the file or the path of the file. 25044 25045@item EPERM 25046The system does not allow unlinking of directories. 25047 25048@item EBUSY 25049The file @var{pathname} cannot be unlinked because it's 25050being used by another process. 25051 25052@item EFAULT 25053@var{pathnameptr} is an invalid pointer value. 25054 25055@item ENAMETOOLONG 25056@var{pathname} was too long. 25057 25058@item ENOENT 25059A directory component in @var{pathname} does not exist. 25060 25061@item ENOTDIR 25062A component of the path is not a directory. 25063 25064@item EROFS 25065The file is on a read-only filesystem. 25066 25067@item EINTR 25068The call was interrupted by the user. 25069@end table 25070 25071@end table 25072 25073@node stat/fstat 25074@unnumberedsubsubsec stat/fstat 25075@cindex fstat, file-i/o system call 25076@cindex stat, file-i/o system call 25077 25078@table @asis 25079@item Synopsis: 25080@smallexample 25081int stat(const char *pathname, struct stat *buf); 25082int fstat(int fd, struct stat *buf); 25083@end smallexample 25084 25085@item Request: 25086@samp{Fstat,@var{pathnameptr}/@var{len},@var{bufptr}}@* 25087@samp{Ffstat,@var{fd},@var{bufptr}} 25088 25089@item Return value: 25090On success, zero is returned. On error, -1 is returned. 25091 25092@item Errors: 25093 25094@table @code 25095@item EBADF 25096@var{fd} is not a valid open file. 25097 25098@item ENOENT 25099A directory component in @var{pathname} does not exist or the 25100path is an empty string. 25101 25102@item ENOTDIR 25103A component of the path is not a directory. 25104 25105@item EFAULT 25106@var{pathnameptr} is an invalid pointer value. 25107 25108@item EACCES 25109No access to the file or the path of the file. 25110 25111@item ENAMETOOLONG 25112@var{pathname} was too long. 25113 25114@item EINTR 25115The call was interrupted by the user. 25116@end table 25117 25118@end table 25119 25120@node gettimeofday 25121@unnumberedsubsubsec gettimeofday 25122@cindex gettimeofday, file-i/o system call 25123 25124@table @asis 25125@item Synopsis: 25126@smallexample 25127int gettimeofday(struct timeval *tv, void *tz); 25128@end smallexample 25129 25130@item Request: 25131@samp{Fgettimeofday,@var{tvptr},@var{tzptr}} 25132 25133@item Return value: 25134On success, 0 is returned, -1 otherwise. 25135 25136@item Errors: 25137 25138@table @code 25139@item EINVAL 25140@var{tz} is a non-NULL pointer. 25141 25142@item EFAULT 25143@var{tvptr} and/or @var{tzptr} is an invalid pointer value. 25144@end table 25145 25146@end table 25147 25148@node isatty 25149@unnumberedsubsubsec isatty 25150@cindex isatty, file-i/o system call 25151 25152@table @asis 25153@item Synopsis: 25154@smallexample 25155int isatty(int fd); 25156@end smallexample 25157 25158@item Request: 25159@samp{Fisatty,@var{fd}} 25160 25161@item Return value: 25162Returns 1 if @var{fd} refers to the @value{GDBN} console, 0 otherwise. 25163 25164@item Errors: 25165 25166@table @code 25167@item EINTR 25168The call was interrupted by the user. 25169@end table 25170 25171@end table 25172 25173Note that the @code{isatty} call is treated as a special case: it returns 251741 to the target if the file descriptor is attached 25175to the @value{GDBN} console, 0 otherwise. Implementing through system calls 25176would require implementing @code{ioctl} and would be more complex than 25177needed. 25178 25179 25180@node system 25181@unnumberedsubsubsec system 25182@cindex system, file-i/o system call 25183 25184@table @asis 25185@item Synopsis: 25186@smallexample 25187int system(const char *command); 25188@end smallexample 25189 25190@item Request: 25191@samp{Fsystem,@var{commandptr}/@var{len}} 25192 25193@item Return value: 25194If @var{len} is zero, the return value indicates whether a shell is 25195available. A zero return value indicates a shell is not available. 25196For non-zero @var{len}, the value returned is -1 on error and the 25197return status of the command otherwise. Only the exit status of the 25198command is returned, which is extracted from the host's @code{system} 25199return value by calling @code{WEXITSTATUS(retval)}. In case 25200@file{/bin/sh} could not be executed, 127 is returned. 25201 25202@item Errors: 25203 25204@table @code 25205@item EINTR 25206The call was interrupted by the user. 25207@end table 25208 25209@end table 25210 25211@value{GDBN} takes over the full task of calling the necessary host calls 25212to perform the @code{system} call. The return value of @code{system} on 25213the host is simplified before it's returned 25214to the target. Any termination signal information from the child process 25215is discarded, and the return value consists 25216entirely of the exit status of the called command. 25217 25218Due to security concerns, the @code{system} call is by default refused 25219by @value{GDBN}. The user has to allow this call explicitly with the 25220@code{set remote system-call-allowed 1} command. 25221 25222@table @code 25223@item set remote system-call-allowed 25224@kindex set remote system-call-allowed 25225Control whether to allow the @code{system} calls in the File I/O 25226protocol for the remote target. The default is zero (disabled). 25227 25228@item show remote system-call-allowed 25229@kindex show remote system-call-allowed 25230Show whether the @code{system} calls are allowed in the File I/O 25231protocol. 25232@end table 25233 25234@node Protocol-specific Representation of Datatypes 25235@subsection Protocol-specific Representation of Datatypes 25236@cindex protocol-specific representation of datatypes, in file-i/o protocol 25237 25238@menu 25239* Integral Datatypes:: 25240* Pointer Values:: 25241* Memory Transfer:: 25242* struct stat:: 25243* struct timeval:: 25244@end menu 25245 25246@node Integral Datatypes 25247@unnumberedsubsubsec Integral Datatypes 25248@cindex integral datatypes, in file-i/o protocol 25249 25250The integral datatypes used in the system calls are @code{int}, 25251@code{unsigned int}, @code{long}, @code{unsigned long}, 25252@code{mode_t}, and @code{time_t}. 25253 25254@code{int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are 25255implemented as 32 bit values in this protocol. 25256 25257@code{long} and @code{unsigned long} are implemented as 64 bit types. 25258 25259@xref{Limits}, for corresponding MIN and MAX values (similar to those 25260in @file{limits.h}) to allow range checking on host and target. 25261 25262@code{time_t} datatypes are defined as seconds since the Epoch. 25263 25264All integral datatypes transferred as part of a memory read or write of a 25265structured datatype e.g.@: a @code{struct stat} have to be given in big endian 25266byte order. 25267 25268@node Pointer Values 25269@unnumberedsubsubsec Pointer Values 25270@cindex pointer values, in file-i/o protocol 25271 25272Pointers to target data are transmitted as they are. An exception 25273is made for pointers to buffers for which the length isn't 25274transmitted as part of the function call, namely strings. Strings 25275are transmitted as a pointer/length pair, both as hex values, e.g.@: 25276 25277@smallexample 25278@code{1aaf/12} 25279@end smallexample 25280 25281@noindent 25282which is a pointer to data of length 18 bytes at position 0x1aaf. 25283The length is defined as the full string length in bytes, including 25284the trailing null byte. For example, the string @code{"hello world"} 25285at address 0x123456 is transmitted as 25286 25287@smallexample 25288@code{123456/d} 25289@end smallexample 25290 25291@node Memory Transfer 25292@unnumberedsubsubsec Memory Transfer 25293@cindex memory transfer, in file-i/o protocol 25294 25295Structured data which is transferred using a memory read or write (for 25296example, a @code{struct stat}) is expected to be in a protocol-specific format 25297with all scalar multibyte datatypes being big endian. Translation to 25298this representation needs to be done both by the target before the @code{F} 25299packet is sent, and by @value{GDBN} before 25300it transfers memory to the target. Transferred pointers to structured 25301data should point to the already-coerced data at any time. 25302 25303 25304@node struct stat 25305@unnumberedsubsubsec struct stat 25306@cindex struct stat, in file-i/o protocol 25307 25308The buffer of type @code{struct stat} used by the target and @value{GDBN} 25309is defined as follows: 25310 25311@smallexample 25312struct stat @{ 25313 unsigned int st_dev; /* device */ 25314 unsigned int st_ino; /* inode */ 25315 mode_t st_mode; /* protection */ 25316 unsigned int st_nlink; /* number of hard links */ 25317 unsigned int st_uid; /* user ID of owner */ 25318 unsigned int st_gid; /* group ID of owner */ 25319 unsigned int st_rdev; /* device type (if inode device) */ 25320 unsigned long st_size; /* total size, in bytes */ 25321 unsigned long st_blksize; /* blocksize for filesystem I/O */ 25322 unsigned long st_blocks; /* number of blocks allocated */ 25323 time_t st_atime; /* time of last access */ 25324 time_t st_mtime; /* time of last modification */ 25325 time_t st_ctime; /* time of last change */ 25326@}; 25327@end smallexample 25328 25329The integral datatypes conform to the definitions given in the 25330appropriate section (see @ref{Integral Datatypes}, for details) so this 25331structure is of size 64 bytes. 25332 25333The values of several fields have a restricted meaning and/or 25334range of values. 25335 25336@table @code 25337 25338@item st_dev 25339A value of 0 represents a file, 1 the console. 25340 25341@item st_ino 25342No valid meaning for the target. Transmitted unchanged. 25343 25344@item st_mode 25345Valid mode bits are described in @ref{Constants}. Any other 25346bits have currently no meaning for the target. 25347 25348@item st_uid 25349@itemx st_gid 25350@itemx st_rdev 25351No valid meaning for the target. Transmitted unchanged. 25352 25353@item st_atime 25354@itemx st_mtime 25355@itemx st_ctime 25356These values have a host and file system dependent 25357accuracy. Especially on Windows hosts, the file system may not 25358support exact timing values. 25359@end table 25360 25361The target gets a @code{struct stat} of the above representation and is 25362responsible for coercing it to the target representation before 25363continuing. 25364 25365Note that due to size differences between the host, target, and protocol 25366representations of @code{struct stat} members, these members could eventually 25367get truncated on the target. 25368 25369@node struct timeval 25370@unnumberedsubsubsec struct timeval 25371@cindex struct timeval, in file-i/o protocol 25372 25373The buffer of type @code{struct timeval} used by the File-I/O protocol 25374is defined as follows: 25375 25376@smallexample 25377struct timeval @{ 25378 time_t tv_sec; /* second */ 25379 long tv_usec; /* microsecond */ 25380@}; 25381@end smallexample 25382 25383The integral datatypes conform to the definitions given in the 25384appropriate section (see @ref{Integral Datatypes}, for details) so this 25385structure is of size 8 bytes. 25386 25387@node Constants 25388@subsection Constants 25389@cindex constants, in file-i/o protocol 25390 25391The following values are used for the constants inside of the 25392protocol. @value{GDBN} and target are responsible for translating these 25393values before and after the call as needed. 25394 25395@menu 25396* Open Flags:: 25397* mode_t Values:: 25398* Errno Values:: 25399* Lseek Flags:: 25400* Limits:: 25401@end menu 25402 25403@node Open Flags 25404@unnumberedsubsubsec Open Flags 25405@cindex open flags, in file-i/o protocol 25406 25407All values are given in hexadecimal representation. 25408 25409@smallexample 25410 O_RDONLY 0x0 25411 O_WRONLY 0x1 25412 O_RDWR 0x2 25413 O_APPEND 0x8 25414 O_CREAT 0x200 25415 O_TRUNC 0x400 25416 O_EXCL 0x800 25417@end smallexample 25418 25419@node mode_t Values 25420@unnumberedsubsubsec mode_t Values 25421@cindex mode_t values, in file-i/o protocol 25422 25423All values are given in octal representation. 25424 25425@smallexample 25426 S_IFREG 0100000 25427 S_IFDIR 040000 25428 S_IRUSR 0400 25429 S_IWUSR 0200 25430 S_IXUSR 0100 25431 S_IRGRP 040 25432 S_IWGRP 020 25433 S_IXGRP 010 25434 S_IROTH 04 25435 S_IWOTH 02 25436 S_IXOTH 01 25437@end smallexample 25438 25439@node Errno Values 25440@unnumberedsubsubsec Errno Values 25441@cindex errno values, in file-i/o protocol 25442 25443All values are given in decimal representation. 25444 25445@smallexample 25446 EPERM 1 25447 ENOENT 2 25448 EINTR 4 25449 EBADF 9 25450 EACCES 13 25451 EFAULT 14 25452 EBUSY 16 25453 EEXIST 17 25454 ENODEV 19 25455 ENOTDIR 20 25456 EISDIR 21 25457 EINVAL 22 25458 ENFILE 23 25459 EMFILE 24 25460 EFBIG 27 25461 ENOSPC 28 25462 ESPIPE 29 25463 EROFS 30 25464 ENAMETOOLONG 91 25465 EUNKNOWN 9999 25466@end smallexample 25467 25468 @code{EUNKNOWN} is used as a fallback error value if a host system returns 25469 any error value not in the list of supported error numbers. 25470 25471@node Lseek Flags 25472@unnumberedsubsubsec Lseek Flags 25473@cindex lseek flags, in file-i/o protocol 25474 25475@smallexample 25476 SEEK_SET 0 25477 SEEK_CUR 1 25478 SEEK_END 2 25479@end smallexample 25480 25481@node Limits 25482@unnumberedsubsubsec Limits 25483@cindex limits, in file-i/o protocol 25484 25485All values are given in decimal representation. 25486 25487@smallexample 25488 INT_MIN -2147483648 25489 INT_MAX 2147483647 25490 UINT_MAX 4294967295 25491 LONG_MIN -9223372036854775808 25492 LONG_MAX 9223372036854775807 25493 ULONG_MAX 18446744073709551615 25494@end smallexample 25495 25496@node File-I/O Examples 25497@subsection File-I/O Examples 25498@cindex file-i/o examples 25499 25500Example sequence of a write call, file descriptor 3, buffer is at target 25501address 0x1234, 6 bytes should be written: 25502 25503@smallexample 25504<- @code{Fwrite,3,1234,6} 25505@emph{request memory read from target} 25506-> @code{m1234,6} 25507<- XXXXXX 25508@emph{return "6 bytes written"} 25509-> @code{F6} 25510@end smallexample 25511 25512Example sequence of a read call, file descriptor 3, buffer is at target 25513address 0x1234, 6 bytes should be read: 25514 25515@smallexample 25516<- @code{Fread,3,1234,6} 25517@emph{request memory write to target} 25518-> @code{X1234,6:XXXXXX} 25519@emph{return "6 bytes read"} 25520-> @code{F6} 25521@end smallexample 25522 25523Example sequence of a read call, call fails on the host due to invalid 25524file descriptor (@code{EBADF}): 25525 25526@smallexample 25527<- @code{Fread,3,1234,6} 25528-> @code{F-1,9} 25529@end smallexample 25530 25531Example sequence of a read call, user presses @kbd{Ctrl-c} before syscall on 25532host is called: 25533 25534@smallexample 25535<- @code{Fread,3,1234,6} 25536-> @code{F-1,4,C} 25537<- @code{T02} 25538@end smallexample 25539 25540Example sequence of a read call, user presses @kbd{Ctrl-c} after syscall on 25541host is called: 25542 25543@smallexample 25544<- @code{Fread,3,1234,6} 25545-> @code{X1234,6:XXXXXX} 25546<- @code{T02} 25547@end smallexample 25548 25549@node Library List Format 25550@section Library List Format 25551@cindex library list format, remote protocol 25552 25553On some platforms, a dynamic loader (e.g.@: @file{ld.so}) runs in the 25554same process as your application to manage libraries. In this case, 25555@value{GDBN} can use the loader's symbol table and normal memory 25556operations to maintain a list of shared libraries. On other 25557platforms, the operating system manages loaded libraries. 25558@value{GDBN} can not retrieve the list of currently loaded libraries 25559through memory operations, so it uses the @samp{qXfer:libraries:read} 25560packet (@pxref{qXfer library list read}) instead. The remote stub 25561queries the target's operating system and reports which libraries 25562are loaded. 25563 25564The @samp{qXfer:libraries:read} packet returns an XML document which 25565lists loaded libraries and their offsets. Each library has an 25566associated name and one or more segment base addresses, which report 25567where the library was loaded in memory. The segment bases are start 25568addresses, not relocation offsets; they do not depend on the library's 25569link-time base addresses. 25570 25571A simple memory map, with one loaded library relocated by a single 25572offset, looks like this: 25573 25574@smallexample 25575<library-list> 25576 <library name="/lib/libc.so.6"> 25577 <segment address="0x10000000"/> 25578 </library> 25579</library-list> 25580@end smallexample 25581 25582The format of a library list is described by this DTD: 25583 25584@smallexample 25585<!-- library-list: Root element with versioning --> 25586<!ELEMENT library-list (library)*> 25587<!ATTLIST library-list version CDATA #FIXED "1.0"> 25588<!ELEMENT library (segment)*> 25589<!ATTLIST library name CDATA #REQUIRED> 25590<!ELEMENT segment EMPTY> 25591<!ATTLIST segment address CDATA #REQUIRED> 25592@end smallexample 25593 25594@node Memory Map Format 25595@section Memory Map Format 25596@cindex memory map format 25597 25598To be able to write into flash memory, @value{GDBN} needs to obtain a 25599memory map from the target. This section describes the format of the 25600memory map. 25601 25602The memory map is obtained using the @samp{qXfer:memory-map:read} 25603(@pxref{qXfer memory map read}) packet and is an XML document that 25604lists memory regions. The top-level structure of the document is shown below: 25605 25606@smallexample 25607<?xml version="1.0"?> 25608<!DOCTYPE memory-map 25609 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN" 25610 "http://sourceware.org/gdb/gdb-memory-map.dtd"> 25611<memory-map> 25612 region... 25613</memory-map> 25614@end smallexample 25615 25616Each region can be either: 25617 25618@itemize 25619 25620@item 25621A region of RAM starting at @var{addr} and extending for @var{length} 25622bytes from there: 25623 25624@smallexample 25625<memory type="ram" start="@var{addr}" length="@var{length}"/> 25626@end smallexample 25627 25628 25629@item 25630A region of read-only memory: 25631 25632@smallexample 25633<memory type="rom" start="@var{addr}" length="@var{length}"/> 25634@end smallexample 25635 25636 25637@item 25638A region of flash memory, with erasure blocks @var{blocksize} 25639bytes in length: 25640 25641@smallexample 25642<memory type="flash" start="@var{addr}" length="@var{length}"> 25643 <property name="blocksize">@var{blocksize}</property> 25644</memory> 25645@end smallexample 25646 25647@end itemize 25648 25649Regions must not overlap. @value{GDBN} assumes that areas of memory not covered 25650by the memory map are RAM, and uses the ordinary @samp{M} and @samp{X} 25651packets to write to addresses in such ranges. 25652 25653The formal DTD for memory map format is given below: 25654 25655@smallexample 25656<!-- ................................................... --> 25657<!-- Memory Map XML DTD ................................ --> 25658<!-- File: memory-map.dtd .............................. --> 25659<!-- .................................... .............. --> 25660<!-- memory-map.dtd --> 25661<!-- memory-map: Root element with versioning --> 25662<!ELEMENT memory-map (memory | property)> 25663<!ATTLIST memory-map version CDATA #FIXED "1.0.0"> 25664<!ELEMENT memory (property)> 25665<!-- memory: Specifies a memory region, 25666 and its type, or device. --> 25667<!ATTLIST memory type CDATA #REQUIRED 25668 start CDATA #REQUIRED 25669 length CDATA #REQUIRED 25670 device CDATA #IMPLIED> 25671<!-- property: Generic attribute tag --> 25672<!ELEMENT property (#PCDATA | property)*> 25673<!ATTLIST property name CDATA #REQUIRED> 25674@end smallexample 25675 25676@include agentexpr.texi 25677 25678@node Target Descriptions 25679@appendix Target Descriptions 25680@cindex target descriptions 25681 25682@strong{Warning:} target descriptions are still under active development, 25683and the contents and format may change between @value{GDBN} releases. 25684The format is expected to stabilize in the future. 25685 25686One of the challenges of using @value{GDBN} to debug embedded systems 25687is that there are so many minor variants of each processor 25688architecture in use. It is common practice for vendors to start with 25689a standard processor core --- ARM, PowerPC, or MIPS, for example --- 25690and then make changes to adapt it to a particular market niche. Some 25691architectures have hundreds of variants, available from dozens of 25692vendors. This leads to a number of problems: 25693 25694@itemize @bullet 25695@item 25696With so many different customized processors, it is difficult for 25697the @value{GDBN} maintainers to keep up with the changes. 25698@item 25699Since individual variants may have short lifetimes or limited 25700audiences, it may not be worthwhile to carry information about every 25701variant in the @value{GDBN} source tree. 25702@item 25703When @value{GDBN} does support the architecture of the embedded system 25704at hand, the task of finding the correct architecture name to give the 25705@command{set architecture} command can be error-prone. 25706@end itemize 25707 25708To address these problems, the @value{GDBN} remote protocol allows a 25709target system to not only identify itself to @value{GDBN}, but to 25710actually describe its own features. This lets @value{GDBN} support 25711processor variants it has never seen before --- to the extent that the 25712descriptions are accurate, and that @value{GDBN} understands them. 25713 25714@value{GDBN} must be compiled with Expat support to support XML target 25715descriptions. @xref{Expat}. 25716 25717@menu 25718* Retrieving Descriptions:: How descriptions are fetched from a target. 25719* Target Description Format:: The contents of a target description. 25720* Predefined Target Types:: Standard types available for target 25721 descriptions. 25722* Standard Target Features:: Features @value{GDBN} knows about. 25723@end menu 25724 25725@node Retrieving Descriptions 25726@section Retrieving Descriptions 25727 25728Target descriptions can be read from the target automatically, or 25729specified by the user manually. The default behavior is to read the 25730description from the target. @value{GDBN} retrieves it via the remote 25731protocol using @samp{qXfer} requests (@pxref{General Query Packets, 25732qXfer}). The @var{annex} in the @samp{qXfer} packet will be 25733@samp{target.xml}. The contents of the @samp{target.xml} annex are an 25734XML document, of the form described in @ref{Target Description 25735Format}. 25736 25737Alternatively, you can specify a file to read for the target description. 25738If a file is set, the target will not be queried. The commands to 25739specify a file are: 25740 25741@table @code 25742@cindex set tdesc filename 25743@item set tdesc filename @var{path} 25744Read the target description from @var{path}. 25745 25746@cindex unset tdesc filename 25747@item unset tdesc filename 25748Do not read the XML target description from a file. @value{GDBN} 25749will use the description supplied by the current target. 25750 25751@cindex show tdesc filename 25752@item show tdesc filename 25753Show the filename to read for a target description, if any. 25754@end table 25755 25756 25757@node Target Description Format 25758@section Target Description Format 25759@cindex target descriptions, XML format 25760 25761A target description annex is an @uref{http://www.w3.org/XML/, XML} 25762document which complies with the Document Type Definition provided in 25763the @value{GDBN} sources in @file{gdb/features/gdb-target.dtd}. This 25764means you can use generally available tools like @command{xmllint} to 25765check that your feature descriptions are well-formed and valid. 25766However, to help people unfamiliar with XML write descriptions for 25767their targets, we also describe the grammar here. 25768 25769Target descriptions can identify the architecture of the remote target 25770and (for some architectures) provide information about custom register 25771sets. @value{GDBN} can use this information to autoconfigure for your 25772target, or to warn you if you connect to an unsupported target. 25773 25774Here is a simple target description: 25775 25776@smallexample 25777<target version="1.0"> 25778 <architecture>i386:x86-64</architecture> 25779</target> 25780@end smallexample 25781 25782@noindent 25783This minimal description only says that the target uses 25784the x86-64 architecture. 25785 25786A target description has the following overall form, with [ ] marking 25787optional elements and @dots{} marking repeatable elements. The elements 25788are explained further below. 25789 25790@smallexample 25791<?xml version="1.0"?> 25792<!DOCTYPE target SYSTEM "gdb-target.dtd"> 25793<target version="1.0"> 25794 @r{[}@var{architecture}@r{]} 25795 @r{[}@var{feature}@dots{}@r{]} 25796</target> 25797@end smallexample 25798 25799@noindent 25800The description is generally insensitive to whitespace and line 25801breaks, under the usual common-sense rules. The XML version 25802declaration and document type declaration can generally be omitted 25803(@value{GDBN} does not require them), but specifying them may be 25804useful for XML validation tools. The @samp{version} attribute for 25805@samp{<target>} may also be omitted, but we recommend 25806including it; if future versions of @value{GDBN} use an incompatible 25807revision of @file{gdb-target.dtd}, they will detect and report 25808the version mismatch. 25809 25810@subsection Inclusion 25811@cindex target descriptions, inclusion 25812@cindex XInclude 25813@ifnotinfo 25814@cindex <xi:include> 25815@end ifnotinfo 25816 25817It can sometimes be valuable to split a target description up into 25818several different annexes, either for organizational purposes, or to 25819share files between different possible target descriptions. You can 25820divide a description into multiple files by replacing any element of 25821the target description with an inclusion directive of the form: 25822 25823@smallexample 25824<xi:include href="@var{document}"/> 25825@end smallexample 25826 25827@noindent 25828When @value{GDBN} encounters an element of this form, it will retrieve 25829the named XML @var{document}, and replace the inclusion directive with 25830the contents of that document. If the current description was read 25831using @samp{qXfer}, then so will be the included document; 25832@var{document} will be interpreted as the name of an annex. If the 25833current description was read from a file, @value{GDBN} will look for 25834@var{document} as a file in the same directory where it found the 25835original description. 25836 25837@subsection Architecture 25838@cindex <architecture> 25839 25840An @samp{<architecture>} element has this form: 25841 25842@smallexample 25843 <architecture>@var{arch}</architecture> 25844@end smallexample 25845 25846@var{arch} is an architecture name from the same selection 25847accepted by @code{set architecture} (@pxref{Targets, ,Specifying a 25848Debugging Target}). 25849 25850@subsection Features 25851@cindex <feature> 25852 25853Each @samp{<feature>} describes some logical portion of the target 25854system. Features are currently used to describe available CPU 25855registers and the types of their contents. A @samp{<feature>} element 25856has this form: 25857 25858@smallexample 25859<feature name="@var{name}"> 25860 @r{[}@var{type}@dots{}@r{]} 25861 @var{reg}@dots{} 25862</feature> 25863@end smallexample 25864 25865@noindent 25866Each feature's name should be unique within the description. The name 25867of a feature does not matter unless @value{GDBN} has some special 25868knowledge of the contents of that feature; if it does, the feature 25869should have its standard name. @xref{Standard Target Features}. 25870 25871@subsection Types 25872 25873Any register's value is a collection of bits which @value{GDBN} must 25874interpret. The default interpretation is a two's complement integer, 25875but other types can be requested by name in the register description. 25876Some predefined types are provided by @value{GDBN} (@pxref{Predefined 25877Target Types}), and the description can define additional composite types. 25878 25879Each type element must have an @samp{id} attribute, which gives 25880a unique (within the containing @samp{<feature>}) name to the type. 25881Types must be defined before they are used. 25882 25883@cindex <vector> 25884Some targets offer vector registers, which can be treated as arrays 25885of scalar elements. These types are written as @samp{<vector>} elements, 25886specifying the array element type, @var{type}, and the number of elements, 25887@var{count}: 25888 25889@smallexample 25890<vector id="@var{id}" type="@var{type}" count="@var{count}"/> 25891@end smallexample 25892 25893@cindex <union> 25894If a register's value is usefully viewed in multiple ways, define it 25895with a union type containing the useful representations. The 25896@samp{<union>} element contains one or more @samp{<field>} elements, 25897each of which has a @var{name} and a @var{type}: 25898 25899@smallexample 25900<union id="@var{id}"> 25901 <field name="@var{name}" type="@var{type}"/> 25902 @dots{} 25903</union> 25904@end smallexample 25905 25906@subsection Registers 25907@cindex <reg> 25908 25909Each register is represented as an element with this form: 25910 25911@smallexample 25912<reg name="@var{name}" 25913 bitsize="@var{size}" 25914 @r{[}regnum="@var{num}"@r{]} 25915 @r{[}save-restore="@var{save-restore}"@r{]} 25916 @r{[}type="@var{type}"@r{]} 25917 @r{[}group="@var{group}"@r{]}/> 25918@end smallexample 25919 25920@noindent 25921The components are as follows: 25922 25923@table @var 25924 25925@item name 25926The register's name; it must be unique within the target description. 25927 25928@item bitsize 25929The register's size, in bits. 25930 25931@item regnum 25932The register's number. If omitted, a register's number is one greater 25933than that of the previous register (either in the current feature or in 25934a preceeding feature); the first register in the target description 25935defaults to zero. This register number is used to read or write 25936the register; e.g.@: it is used in the remote @code{p} and @code{P} 25937packets, and registers appear in the @code{g} and @code{G} packets 25938in order of increasing register number. 25939 25940@item save-restore 25941Whether the register should be preserved across inferior function 25942calls; this must be either @code{yes} or @code{no}. The default is 25943@code{yes}, which is appropriate for most registers except for 25944some system control registers; this is not related to the target's 25945ABI. 25946 25947@item type 25948The type of the register. @var{type} may be a predefined type, a type 25949defined in the current feature, or one of the special types @code{int} 25950and @code{float}. @code{int} is an integer type of the correct size 25951for @var{bitsize}, and @code{float} is a floating point type (in the 25952architecture's normal floating point format) of the correct size for 25953@var{bitsize}. The default is @code{int}. 25954 25955@item group 25956The register group to which this register belongs. @var{group} must 25957be either @code{general}, @code{float}, or @code{vector}. If no 25958@var{group} is specified, @value{GDBN} will not display the register 25959in @code{info registers}. 25960 25961@end table 25962 25963@node Predefined Target Types 25964@section Predefined Target Types 25965@cindex target descriptions, predefined types 25966 25967Type definitions in the self-description can build up composite types 25968from basic building blocks, but can not define fundamental types. Instead, 25969standard identifiers are provided by @value{GDBN} for the fundamental 25970types. The currently supported types are: 25971 25972@table @code 25973 25974@item int8 25975@itemx int16 25976@itemx int32 25977@itemx int64 25978Signed integer types holding the specified number of bits. 25979 25980@item uint8 25981@itemx uint16 25982@itemx uint32 25983@itemx uint64 25984Unsigned integer types holding the specified number of bits. 25985 25986@item code_ptr 25987@itemx data_ptr 25988Pointers to unspecified code and data. The program counter and 25989any dedicated return address register may be marked as code 25990pointers; printing a code pointer converts it into a symbolic 25991address. The stack pointer and any dedicated address registers 25992may be marked as data pointers. 25993 25994@item ieee_single 25995Single precision IEEE floating point. 25996 25997@item ieee_double 25998Double precision IEEE floating point. 25999 26000@item arm_fpa_ext 26001The 12-byte extended precision format used by ARM FPA registers. 26002 26003@end table 26004 26005@node Standard Target Features 26006@section Standard Target Features 26007@cindex target descriptions, standard features 26008 26009A target description must contain either no registers or all the 26010target's registers. If the description contains no registers, then 26011@value{GDBN} will assume a default register layout, selected based on 26012the architecture. If the description contains any registers, the 26013default layout will not be used; the standard registers must be 26014described in the target description, in such a way that @value{GDBN} 26015can recognize them. 26016 26017This is accomplished by giving specific names to feature elements 26018which contain standard registers. @value{GDBN} will look for features 26019with those names and verify that they contain the expected registers; 26020if any known feature is missing required registers, or if any required 26021feature is missing, @value{GDBN} will reject the target 26022description. You can add additional registers to any of the 26023standard features --- @value{GDBN} will display them just as if 26024they were added to an unrecognized feature. 26025 26026This section lists the known features and their expected contents. 26027Sample XML documents for these features are included in the 26028@value{GDBN} source tree, in the directory @file{gdb/features}. 26029 26030Names recognized by @value{GDBN} should include the name of the 26031company or organization which selected the name, and the overall 26032architecture to which the feature applies; so e.g.@: the feature 26033containing ARM core registers is named @samp{org.gnu.gdb.arm.core}. 26034 26035The names of registers are not case sensitive for the purpose 26036of recognizing standard features, but @value{GDBN} will only display 26037registers using the capitalization used in the description. 26038 26039@menu 26040* ARM Features:: 26041* M68K Features:: 26042@end menu 26043 26044 26045@node ARM Features 26046@subsection ARM Features 26047@cindex target descriptions, ARM features 26048 26049The @samp{org.gnu.gdb.arm.core} feature is required for ARM targets. 26050It should contain registers @samp{r0} through @samp{r13}, @samp{sp}, 26051@samp{lr}, @samp{pc}, and @samp{cpsr}. 26052 26053The @samp{org.gnu.gdb.arm.fpa} feature is optional. If present, it 26054should contain registers @samp{f0} through @samp{f7} and @samp{fps}. 26055 26056The @samp{org.gnu.gdb.xscale.iwmmxt} feature is optional. If present, 26057it should contain at least registers @samp{wR0} through @samp{wR15} and 26058@samp{wCGR0} through @samp{wCGR3}. The @samp{wCID}, @samp{wCon}, 26059@samp{wCSSF}, and @samp{wCASF} registers are optional. 26060 26061@subsection MIPS Features 26062@cindex target descriptions, MIPS features 26063 26064The @samp{org.gnu.gdb.mips.cpu} feature is required for MIPS targets. 26065It should contain registers @samp{r0} through @samp{r31}, @samp{lo}, 26066@samp{hi}, and @samp{pc}. They may be 32-bit or 64-bit depending 26067on the target. 26068 26069The @samp{org.gnu.gdb.mips.cp0} feature is also required. It should 26070contain at least the @samp{status}, @samp{badvaddr}, and @samp{cause} 26071registers. They may be 32-bit or 64-bit depending on the target. 26072 26073The @samp{org.gnu.gdb.mips.fpu} feature is currently required, though 26074it may be optional in a future version of @value{GDBN}. It should 26075contain registers @samp{f0} through @samp{f31}, @samp{fcsr}, and 26076@samp{fir}. They may be 32-bit or 64-bit depending on the target. 26077 26078The @samp{org.gnu.gdb.mips.linux} feature is optional. It should 26079contain a single register, @samp{restart}, which is used by the 26080Linux kernel to control restartable syscalls. 26081 26082@node M68K Features 26083@subsection M68K Features 26084@cindex target descriptions, M68K features 26085 26086@table @code 26087@item @samp{org.gnu.gdb.m68k.core} 26088@itemx @samp{org.gnu.gdb.coldfire.core} 26089@itemx @samp{org.gnu.gdb.fido.core} 26090One of those features must be always present. 26091The feature that is present determines which flavor of m86k is 26092used. The feature that is present should contain registers 26093@samp{d0} through @samp{d7}, @samp{a0} through @samp{a5}, @samp{fp}, 26094@samp{sp}, @samp{ps} and @samp{pc}. 26095 26096@item @samp{org.gnu.gdb.coldfire.fp} 26097This feature is optional. If present, it should contain registers 26098@samp{fp0} through @samp{fp7}, @samp{fpcontrol}, @samp{fpstatus} and 26099@samp{fpiaddr}. 26100@end table 26101 26102@include gpl.texi 26103 26104@raisesections 26105@include fdl.texi 26106@lowersections 26107 26108@node Index 26109@unnumbered Index 26110 26111@printindex cp 26112 26113@tex 26114% I think something like @colophon should be in texinfo. In the 26115% meantime: 26116\long\def\colophon{\hbox to0pt{}\vfill 26117\centerline{The body of this manual is set in} 26118\centerline{\fontname\tenrm,} 26119\centerline{with headings in {\bf\fontname\tenbf}} 26120\centerline{and examples in {\tt\fontname\tentt}.} 26121\centerline{{\it\fontname\tenit\/},} 26122\centerline{{\bf\fontname\tenbf}, and} 26123\centerline{{\sl\fontname\tensl\/}} 26124\centerline{are used for emphasis.}\vfill} 26125\page\colophon 26126% Blame: doc@cygnus.com, 1991. 26127@end tex 26128 26129@bye 26130