1\input texinfo @c -*-texinfo-*- 2@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 3@c 1999, 2000, 2001, 2002, 2003, 2004 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 Free Software Foundation, Inc. 56 57Permission is granted to copy, distribute and/or modify this document 58under the terms of the GNU Free Documentation License, Version 1.1 or 59any later version published by the Free Software Foundation; with the 60Invariant Sections being ``Free Software'' and ``Free Software Needs 61Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 62and with the Back-Cover Texts as in (a) below. 63 64(a) The Free Software Foundation's Back-Cover Text is: ``You have 65freedom to copy and modify this GNU Manual, like GNU software. Copies 66published by the Free Software Foundation raise funds for GNU 67development.'' 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 Free Software Foundation, Inc. 88@sp 2 89Published by the Free Software Foundation @* 9059 Temple Place - Suite 330, @* 91Boston, MA 02111-1307 USA @* 92ISBN 1-882114-77-9 @* 93 94Permission is granted to copy, distribute and/or modify this document 95under the terms of the GNU Free Documentation License, Version 1.1 or 96any later version published by the Free Software Foundation; with the 97Invariant Sections being ``Free Software'' and ``Free Software Needs 98Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 99and with the Back-Cover Texts as in (a) below. 100 101(a) The Free Software Foundation's Back-Cover Text is: ``You have 102freedom to copy and modify this GNU Manual, like GNU software. Copies 103published by the Free Software Foundation raise funds for GNU 104development.'' 105@end titlepage 106@page 107 108@ifnottex 109@node Top, Summary, (dir), (dir) 110 111@top Debugging with @value{GDBN} 112 113This file describes @value{GDBN}, the @sc{gnu} symbolic debugger. 114 115This is the @value{EDITION} Edition, for @value{GDBN} Version 116@value{GDBVN}. 117 118Copyright (C) 1988-2004 Free Software Foundation, Inc. 119 120@menu 121* Summary:: Summary of @value{GDBN} 122* Sample Session:: A sample @value{GDBN} session 123 124* Invocation:: Getting in and out of @value{GDBN} 125* Commands:: @value{GDBN} commands 126* Running:: Running programs under @value{GDBN} 127* Stopping:: Stopping and continuing 128* Stack:: Examining the stack 129* Source:: Examining source files 130* Data:: Examining data 131* Macros:: Preprocessor Macros 132* Tracepoints:: Debugging remote targets non-intrusively 133* Overlays:: Debugging programs that use overlays 134 135* Languages:: Using @value{GDBN} with different languages 136 137* Symbols:: Examining the symbol table 138* Altering:: Altering execution 139* GDB Files:: @value{GDBN} files 140* Targets:: Specifying a debugging target 141* Remote Debugging:: Debugging remote programs 142* Configurations:: Configuration-specific information 143* Controlling GDB:: Controlling @value{GDBN} 144* Sequences:: Canned sequences of commands 145* TUI:: @value{GDBN} Text User Interface 146* Interpreters:: Command Interpreters 147* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs 148* Annotations:: @value{GDBN}'s annotation interface. 149* GDB/MI:: @value{GDBN}'s Machine Interface. 150 151* GDB Bugs:: Reporting bugs in @value{GDBN} 152* Formatting Documentation:: How to format and print @value{GDBN} documentation 153 154* Command Line Editing:: Command Line Editing 155* Using History Interactively:: Using History Interactively 156* Installing GDB:: Installing GDB 157* Maintenance Commands:: Maintenance Commands 158* Remote Protocol:: GDB Remote Serial Protocol 159* Agent Expressions:: The GDB Agent Expression Mechanism 160* Copying:: GNU General Public License says 161 how you can copy and share GDB 162* GNU Free Documentation License:: The license for this documentation 163* Index:: Index 164@end menu 165 166@end ifnottex 167 168@contents 169 170@node Summary 171@unnumbered Summary of @value{GDBN} 172 173The purpose of a debugger such as @value{GDBN} is to allow you to see what is 174going on ``inside'' another program while it executes---or what another 175program was doing at the moment it crashed. 176 177@value{GDBN} can do four main kinds of things (plus other things in support of 178these) to help you catch bugs in the act: 179 180@itemize @bullet 181@item 182Start your program, specifying anything that might affect its behavior. 183 184@item 185Make your program stop on specified conditions. 186 187@item 188Examine what has happened, when your program has stopped. 189 190@item 191Change things in your program, so you can experiment with correcting the 192effects of one bug and go on to learn about another. 193@end itemize 194 195You can use @value{GDBN} to debug programs written in C and C@t{++}. 196For more information, see @ref{Support,,Supported languages}. 197For more information, see @ref{C,,C and C++}. 198 199@cindex Modula-2 200Support for Modula-2 is partial. For information on Modula-2, see 201@ref{Modula-2,,Modula-2}. 202 203@cindex Pascal 204Debugging Pascal programs which use sets, subranges, file variables, or 205nested functions does not currently work. @value{GDBN} does not support 206entering expressions, printing values, or similar features using Pascal 207syntax. 208 209@cindex Fortran 210@value{GDBN} can be used to debug programs written in Fortran, although 211it may be necessary to refer to some variables with a trailing 212underscore. 213 214@value{GDBN} can be used to debug programs written in Objective-C, 215using either the Apple/NeXT or the GNU Objective-C runtime. 216 217@menu 218* Free Software:: Freely redistributable software 219* Contributors:: Contributors to GDB 220@end menu 221 222@node Free Software 223@unnumberedsec Free software 224 225@value{GDBN} is @dfn{free software}, protected by the @sc{gnu} 226General Public License 227(GPL). The GPL gives you the freedom to copy or adapt a licensed 228program---but every person getting a copy also gets with it the 229freedom to modify that copy (which means that they must get access to 230the source code), and the freedom to distribute further copies. 231Typical software companies use copyrights to limit your freedoms; the 232Free Software Foundation uses the GPL to preserve these freedoms. 233 234Fundamentally, the General Public License is a license which says that 235you have these freedoms and that you cannot take these freedoms away 236from anyone else. 237 238@unnumberedsec Free Software Needs Free Documentation 239 240The biggest deficiency in the free software community today is not in 241the software---it is the lack of good free documentation that we can 242include with the free software. Many of our most important 243programs do not come with free reference manuals and free introductory 244texts. Documentation is an essential part of any software package; 245when an important free software package does not come with a free 246manual and a free tutorial, that is a major gap. We have many such 247gaps today. 248 249Consider Perl, for instance. The tutorial manuals that people 250normally use are non-free. How did this come about? Because the 251authors of those manuals published them with restrictive terms---no 252copying, no modification, source files not available---which exclude 253them from the free software world. 254 255That wasn't the first time this sort of thing happened, and it was far 256from the last. Many times we have heard a GNU user eagerly describe a 257manual that he is writing, his intended contribution to the community, 258only to learn that he had ruined everything by signing a publication 259contract to make it non-free. 260 261Free documentation, like free software, is a matter of freedom, not 262price. The problem with the non-free manual is not that publishers 263charge a price for printed copies---that in itself is fine. (The Free 264Software Foundation sells printed copies of manuals, too.) The 265problem is the restrictions on the use of the manual. Free manuals 266are available in source code form, and give you permission to copy and 267modify. Non-free manuals do not allow this. 268 269The criteria of freedom for a free manual are roughly the same as for 270free software. Redistribution (including the normal kinds of 271commercial redistribution) must be permitted, so that the manual can 272accompany every copy of the program, both on-line and on paper. 273 274Permission for modification of the technical content is crucial too. 275When people modify the software, adding or changing features, if they 276are conscientious they will change the manual too---so they can 277provide accurate and clear documentation for the modified program. A 278manual that leaves you no choice but to write a new manual to document 279a changed version of the program is not really available to our 280community. 281 282Some kinds of limits on the way modification is handled are 283acceptable. For example, requirements to preserve the original 284author's copyright notice, the distribution terms, or the list of 285authors, are ok. It is also no problem to require modified versions 286to include notice that they were modified. Even entire sections that 287may not be deleted or changed are acceptable, as long as they deal 288with nontechnical topics (like this one). These kinds of restrictions 289are acceptable because they don't obstruct the community's normal use 290of the manual. 291 292However, it must be possible to modify all the @emph{technical} 293content of the manual, and then distribute the result in all the usual 294media, through all the usual channels. Otherwise, the restrictions 295obstruct the use of the manual, it is not free, and we need another 296manual to replace it. 297 298Please spread the word about this issue. Our community continues to 299lose manuals to proprietary publishing. If we spread the word that 300free software needs free reference manuals and free tutorials, perhaps 301the next person who wants to contribute by writing documentation will 302realize, before it is too late, that only free manuals contribute to 303the free software community. 304 305If you are writing documentation, please insist on publishing it under 306the GNU Free Documentation License or another free documentation 307license. Remember that this decision requires your approval---you 308don't have to let the publisher decide. Some commercial publishers 309will use a free license if you insist, but they will not propose the 310option; it is up to you to raise the issue and say firmly that this is 311what you want. If the publisher you are dealing with refuses, please 312try other publishers. If you're not sure whether a proposed license 313is free, write to @email{licensing@@gnu.org}. 314 315You can encourage commercial publishers to sell more free, copylefted 316manuals and tutorials by buying them, and particularly by buying 317copies from the publishers that paid for their writing or for major 318improvements. Meanwhile, try to avoid buying non-free documentation 319at all. Check the distribution terms of a manual before you buy it, 320and insist that whoever seeks your business must respect your freedom. 321Check the history of the book, and try to reward the publishers that 322have paid or pay the authors to work on it. 323 324The Free Software Foundation maintains a list of free documentation 325published by other publishers, at 326@url{http://www.fsf.org/doc/other-free-books.html}. 327 328@node Contributors 329@unnumberedsec Contributors to @value{GDBN} 330 331Richard Stallman was the original author of @value{GDBN}, and of many 332other @sc{gnu} programs. Many others have contributed to its 333development. This section attempts to credit major contributors. One 334of the virtues of free software is that everyone is free to contribute 335to it; with regret, we cannot actually acknowledge everyone here. The 336file @file{ChangeLog} in the @value{GDBN} distribution approximates a 337blow-by-blow account. 338 339Changes much prior to version 2.0 are lost in the mists of time. 340 341@quotation 342@emph{Plea:} Additions to this section are particularly welcome. If you 343or your friends (or enemies, to be evenhanded) have been unfairly 344omitted from this list, we would like to add your names! 345@end quotation 346 347So that they may not regard their many labors as thankless, we 348particularly thank those who shepherded @value{GDBN} through major 349releases: 350Andrew Cagney (releases 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); 351Jim Blandy (release 4.18); 352Jason Molenda (release 4.17); 353Stan Shebs (release 4.14); 354Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9); 355Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4); 356John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); 357Jim Kingdon (releases 3.5, 3.4, and 3.3); 358and Randy Smith (releases 3.2, 3.1, and 3.0). 359 360Richard Stallman, assisted at various times by Peter TerMaat, Chris 361Hanson, and Richard Mlynarik, handled releases through 2.8. 362 363Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support 364in @value{GDBN}, with significant additional contributions from Per 365Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++} 366demangler. Early work on C@t{++} was by Peter TerMaat (who also did 367much general update work leading to release 3.0). 368 369@value{GDBN} uses the BFD subroutine library to examine multiple 370object-file formats; BFD was a joint project of David V. 371Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore. 372 373David Johnson wrote the original COFF support; Pace Willison did 374the original support for encapsulated COFF. 375 376Brent Benson of Harris Computer Systems contributed DWARF 2 support. 377 378Adam de Boor and Bradley Davis contributed the ISI Optimum V support. 379Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS 380support. 381Jean-Daniel Fekete contributed Sun 386i support. 382Chris Hanson improved the HP9000 support. 383Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support. 384David Johnson contributed Encore Umax support. 385Jyrki Kuoppala contributed Altos 3068 support. 386Jeff Law contributed HP PA and SOM support. 387Keith Packard contributed NS32K support. 388Doug Rabson contributed Acorn Risc Machine support. 389Bob Rusk contributed Harris Nighthawk CX-UX support. 390Chris Smith contributed Convex support (and Fortran debugging). 391Jonathan Stone contributed Pyramid support. 392Michael Tiemann contributed SPARC support. 393Tim Tucker contributed support for the Gould NP1 and Gould Powernode. 394Pace Willison contributed Intel 386 support. 395Jay Vosburgh contributed Symmetry support. 396Marko Mlinar contributed OpenRISC 1000 support. 397 398Andreas Schwab contributed M68K @sc{gnu}/Linux support. 399 400Rich Schaefer and Peter Schauer helped with support of SunOS shared 401libraries. 402 403Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree 404about several machine instruction sets. 405 406Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop 407remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM 408contributed remote debugging modules for the i960, VxWorks, A29K UDI, 409and RDI targets, respectively. 410 411Brian Fox is the author of the readline libraries providing 412command-line editing and command history. 413 414Andrew Beers of SUNY Buffalo wrote the language-switching code, the 415Modula-2 support, and contributed the Languages chapter of this manual. 416 417Fred Fish wrote most of the support for Unix System Vr4. 418He also enhanced the command-completion support to cover C@t{++} overloaded 419symbols. 420 421Hitachi America (now Renesas America), Ltd. sponsored the support for 422H8/300, H8/500, and Super-H processors. 423 424NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors. 425 426Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D 427processors. 428 429Toshiba sponsored the support for the TX39 Mips processor. 430 431Matsushita sponsored the support for the MN10200 and MN10300 processors. 432 433Fujitsu sponsored the support for SPARClite and FR30 processors. 434 435Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware 436watchpoints. 437 438Michael Snyder added support for tracepoints. 439 440Stu Grossman wrote gdbserver. 441 442Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made 443nearly innumerable bug fixes and cleanups throughout @value{GDBN}. 444 445The following people at the Hewlett-Packard Company contributed 446support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 447(narrow mode), HP's implementation of kernel threads, HP's aC@t{++} 448compiler, and the Text User Interface (nee Terminal User Interface): 449Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, 450Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase 451provided HP-specific information in this manual. 452 453DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project. 454Robert Hoehne made significant contributions to the DJGPP port. 455 456Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its 457development since 1991. Cygnus engineers who have worked on @value{GDBN} 458fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin 459Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim 460Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, 461Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek 462Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In 463addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, 464JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug 465Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff 466Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, 467Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin 468Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela 469Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David 470Zuhn have made contributions both large and small. 471 472Jim Blandy added support for preprocessor macros, while working for Red 473Hat. 474 475@node Sample Session 476@chapter A Sample @value{GDBN} Session 477 478You can use this manual at your leisure to read all about @value{GDBN}. 479However, a handful of commands are enough to get started using the 480debugger. This chapter illustrates those commands. 481 482@iftex 483In this sample session, we emphasize user input like this: @b{input}, 484to make it easier to pick out from the surrounding output. 485@end iftex 486 487@c FIXME: this example may not be appropriate for some configs, where 488@c FIXME...primary interest is in remote use. 489 490One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro 491processor) exhibits the following bug: sometimes, when we change its 492quote strings from the default, the commands used to capture one macro 493definition within another stop working. In the following short @code{m4} 494session, we define a macro @code{foo} which expands to @code{0000}; we 495then use the @code{m4} built-in @code{defn} to define @code{bar} as the 496same thing. However, when we change the open quote string to 497@code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same 498procedure fails to define a new synonym @code{baz}: 499 500@smallexample 501$ @b{cd gnu/m4} 502$ @b{./m4} 503@b{define(foo,0000)} 504 505@b{foo} 5060000 507@b{define(bar,defn(`foo'))} 508 509@b{bar} 5100000 511@b{changequote(<QUOTE>,<UNQUOTE>)} 512 513@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))} 514@b{baz} 515@b{C-d} 516m4: End of input: 0: fatal error: EOF in string 517@end smallexample 518 519@noindent 520Let us use @value{GDBN} to try to see what is going on. 521 522@smallexample 523$ @b{@value{GDBP} m4} 524@c FIXME: this falsifies the exact text played out, to permit smallbook 525@c FIXME... format to come out better. 526@value{GDBN} is free software and you are welcome to distribute copies 527 of it under certain conditions; type "show copying" to see 528 the conditions. 529There is absolutely no warranty for @value{GDBN}; type "show warranty" 530 for details. 531 532@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc... 533(@value{GDBP}) 534@end smallexample 535 536@noindent 537@value{GDBN} reads only enough symbol data to know where to find the 538rest when needed; as a result, the first prompt comes up very quickly. 539We now tell @value{GDBN} to use a narrower display width than usual, so 540that examples fit in this manual. 541 542@smallexample 543(@value{GDBP}) @b{set width 70} 544@end smallexample 545 546@noindent 547We need to see how the @code{m4} built-in @code{changequote} works. 548Having looked at the source, we know the relevant subroutine is 549@code{m4_changequote}, so we set a breakpoint there with the @value{GDBN} 550@code{break} command. 551 552@smallexample 553(@value{GDBP}) @b{break m4_changequote} 554Breakpoint 1 at 0x62f4: file builtin.c, line 879. 555@end smallexample 556 557@noindent 558Using the @code{run} command, we start @code{m4} running under @value{GDBN} 559control; as long as control does not reach the @code{m4_changequote} 560subroutine, the program runs as usual: 561 562@smallexample 563(@value{GDBP}) @b{run} 564Starting program: /work/Editorial/gdb/gnu/m4/m4 565@b{define(foo,0000)} 566 567@b{foo} 5680000 569@end smallexample 570 571@noindent 572To trigger the breakpoint, we call @code{changequote}. @value{GDBN} 573suspends execution of @code{m4}, displaying information about the 574context where it stops. 575 576@smallexample 577@b{changequote(<QUOTE>,<UNQUOTE>)} 578 579Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) 580 at builtin.c:879 581879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) 582@end smallexample 583 584@noindent 585Now we use the command @code{n} (@code{next}) to advance execution to 586the next line of the current function. 587 588@smallexample 589(@value{GDBP}) @b{n} 590882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ 591 : nil, 592@end smallexample 593 594@noindent 595@code{set_quotes} looks like a promising subroutine. We can go into it 596by using the command @code{s} (@code{step}) instead of @code{next}. 597@code{step} goes to the next line to be executed in @emph{any} 598subroutine, so it steps into @code{set_quotes}. 599 600@smallexample 601(@value{GDBP}) @b{s} 602set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 603 at input.c:530 604530 if (lquote != def_lquote) 605@end smallexample 606 607@noindent 608The display that shows the subroutine where @code{m4} is now 609suspended (and its arguments) is called a stack frame display. It 610shows a summary of the stack. We can use the @code{backtrace} 611command (which can also be spelled @code{bt}), to see where we are 612in the stack as a whole: the @code{backtrace} command displays a 613stack frame for each active subroutine. 614 615@smallexample 616(@value{GDBP}) @b{bt} 617#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 618 at input.c:530 619#1 0x6344 in m4_changequote (argc=3, argv=0x33c70) 620 at builtin.c:882 621#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 622#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) 623 at macro.c:71 624#4 0x79dc in expand_input () at macro.c:40 625#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 626@end smallexample 627 628@noindent 629We step through a few more lines to see what happens. The first two 630times, we can use @samp{s}; the next two times we use @code{n} to avoid 631falling into the @code{xstrdup} subroutine. 632 633@smallexample 634(@value{GDBP}) @b{s} 6350x3b5c 532 if (rquote != def_rquote) 636(@value{GDBP}) @b{s} 6370x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ 638def_lquote : xstrdup(lq); 639(@value{GDBP}) @b{n} 640536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 641 : xstrdup(rq); 642(@value{GDBP}) @b{n} 643538 len_lquote = strlen(rquote); 644@end smallexample 645 646@noindent 647The last line displayed looks a little odd; we can examine the variables 648@code{lquote} and @code{rquote} to see if they are in fact the new left 649and right quotes we specified. We use the command @code{p} 650(@code{print}) to see their values. 651 652@smallexample 653(@value{GDBP}) @b{p lquote} 654$1 = 0x35d40 "<QUOTE>" 655(@value{GDBP}) @b{p rquote} 656$2 = 0x35d50 "<UNQUOTE>" 657@end smallexample 658 659@noindent 660@code{lquote} and @code{rquote} are indeed the new left and right quotes. 661To look at some context, we can display ten lines of source 662surrounding the current line with the @code{l} (@code{list}) command. 663 664@smallexample 665(@value{GDBP}) @b{l} 666533 xfree(rquote); 667534 668535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ 669 : xstrdup (lq); 670536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 671 : xstrdup (rq); 672537 673538 len_lquote = strlen(rquote); 674539 len_rquote = strlen(lquote); 675540 @} 676541 677542 void 678@end smallexample 679 680@noindent 681Let us step past the two lines that set @code{len_lquote} and 682@code{len_rquote}, and then examine the values of those variables. 683 684@smallexample 685(@value{GDBP}) @b{n} 686539 len_rquote = strlen(lquote); 687(@value{GDBP}) @b{n} 688540 @} 689(@value{GDBP}) @b{p len_lquote} 690$3 = 9 691(@value{GDBP}) @b{p len_rquote} 692$4 = 7 693@end smallexample 694 695@noindent 696That certainly looks wrong, assuming @code{len_lquote} and 697@code{len_rquote} are meant to be the lengths of @code{lquote} and 698@code{rquote} respectively. We can set them to better values using 699the @code{p} command, since it can print the value of 700any expression---and that expression can include subroutine calls and 701assignments. 702 703@smallexample 704(@value{GDBP}) @b{p len_lquote=strlen(lquote)} 705$5 = 7 706(@value{GDBP}) @b{p len_rquote=strlen(rquote)} 707$6 = 9 708@end smallexample 709 710@noindent 711Is that enough to fix the problem of using the new quotes with the 712@code{m4} built-in @code{defn}? We can allow @code{m4} to continue 713executing with the @code{c} (@code{continue}) command, and then try the 714example that caused trouble initially: 715 716@smallexample 717(@value{GDBP}) @b{c} 718Continuing. 719 720@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))} 721 722baz 7230000 724@end smallexample 725 726@noindent 727Success! The new quotes now work just as well as the default ones. The 728problem seems to have been just the two typos defining the wrong 729lengths. We allow @code{m4} exit by giving it an EOF as input: 730 731@smallexample 732@b{C-d} 733Program exited normally. 734@end smallexample 735 736@noindent 737The message @samp{Program exited normally.} is from @value{GDBN}; it 738indicates @code{m4} has finished executing. We can end our @value{GDBN} 739session with the @value{GDBN} @code{quit} command. 740 741@smallexample 742(@value{GDBP}) @b{quit} 743@end smallexample 744 745@node Invocation 746@chapter Getting In and Out of @value{GDBN} 747 748This chapter discusses how to start @value{GDBN}, and how to get out of it. 749The essentials are: 750@itemize @bullet 751@item 752type @samp{@value{GDBP}} to start @value{GDBN}. 753@item 754type @kbd{quit} or @kbd{C-d} to exit. 755@end itemize 756 757@menu 758* Invoking GDB:: How to start @value{GDBN} 759* Quitting GDB:: How to quit @value{GDBN} 760* Shell Commands:: How to use shell commands inside @value{GDBN} 761* Logging output:: How to log @value{GDBN}'s output to a file 762@end menu 763 764@node Invoking GDB 765@section Invoking @value{GDBN} 766 767Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started, 768@value{GDBN} reads commands from the terminal until you tell it to exit. 769 770You can also run @code{@value{GDBP}} with a variety of arguments and options, 771to specify more of your debugging environment at the outset. 772 773The command-line options described here are designed 774to cover a variety of situations; in some environments, some of these 775options may effectively be unavailable. 776 777The most usual way to start @value{GDBN} is with one argument, 778specifying an executable program: 779 780@smallexample 781@value{GDBP} @var{program} 782@end smallexample 783 784@noindent 785You can also start with both an executable program and a core file 786specified: 787 788@smallexample 789@value{GDBP} @var{program} @var{core} 790@end smallexample 791 792You can, instead, specify a process ID as a second argument, if you want 793to debug a running process: 794 795@smallexample 796@value{GDBP} @var{program} 1234 797@end smallexample 798 799@noindent 800would attach @value{GDBN} to process @code{1234} (unless you also have a file 801named @file{1234}; @value{GDBN} does check for a core file first). 802 803Taking advantage of the second command-line argument requires a fairly 804complete operating system; when you use @value{GDBN} as a remote 805debugger attached to a bare board, there may not be any notion of 806``process'', and there is often no way to get a core dump. @value{GDBN} 807will warn you if it is unable to attach or to read core dumps. 808 809You can optionally have @code{@value{GDBP}} pass any arguments after the 810executable file to the inferior using @code{--args}. This option stops 811option processing. 812@smallexample 813gdb --args gcc -O2 -c foo.c 814@end smallexample 815This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set 816@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}. 817 818You can run @code{@value{GDBP}} without printing the front material, which describes 819@value{GDBN}'s non-warranty, by specifying @code{-silent}: 820 821@smallexample 822@value{GDBP} -silent 823@end smallexample 824 825@noindent 826You can further control how @value{GDBN} starts up by using command-line 827options. @value{GDBN} itself can remind you of the options available. 828 829@noindent 830Type 831 832@smallexample 833@value{GDBP} -help 834@end smallexample 835 836@noindent 837to display all available options and briefly describe their use 838(@samp{@value{GDBP} -h} is a shorter equivalent). 839 840All options and command line arguments you give are processed 841in sequential order. The order makes a difference when the 842@samp{-x} option is used. 843 844 845@menu 846* File Options:: Choosing files 847* Mode Options:: Choosing modes 848@end menu 849 850@node File Options 851@subsection Choosing files 852 853When @value{GDBN} starts, it reads any arguments other than options as 854specifying an executable file and core file (or process ID). This is 855the same as if the arguments were specified by the @samp{-se} and 856@samp{-c} (or @samp{-p} options respectively. (@value{GDBN} reads the 857first argument that does not have an associated option flag as 858equivalent to the @samp{-se} option followed by that argument; and the 859second argument that does not have an associated option flag, if any, as 860equivalent to the @samp{-c}/@samp{-p} option followed by that argument.) 861If the second argument begins with a decimal digit, @value{GDBN} will 862first attempt to attach to it as a process, and if that fails, attempt 863to open it as a corefile. If you have a corefile whose name begins with 864a digit, you can prevent @value{GDBN} from treating it as a pid by 865prefixing it with @file{./}, eg. @file{./12345}. 866 867If @value{GDBN} has not been configured to included core file support, 868such as for most embedded targets, then it will complain about a second 869argument and ignore it. 870 871Many options have both long and short forms; both are shown in the 872following list. @value{GDBN} also recognizes the long forms if you truncate 873them, so long as enough of the option is present to be unambiguous. 874(If you prefer, you can flag option arguments with @samp{--} rather 875than @samp{-}, though we illustrate the more usual convention.) 876 877@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This 878@c way, both those who look for -foo and --foo in the index, will find 879@c it. 880 881@table @code 882@item -symbols @var{file} 883@itemx -s @var{file} 884@cindex @code{--symbols} 885@cindex @code{-s} 886Read symbol table from file @var{file}. 887 888@item -exec @var{file} 889@itemx -e @var{file} 890@cindex @code{--exec} 891@cindex @code{-e} 892Use file @var{file} as the executable file to execute when appropriate, 893and for examining pure data in conjunction with a core dump. 894 895@item -se @var{file} 896@cindex @code{--se} 897Read symbol table from file @var{file} and use it as the executable 898file. 899 900@item -core @var{file} 901@itemx -c @var{file} 902@cindex @code{--core} 903@cindex @code{-c} 904Use file @var{file} as a core dump to examine. 905 906@item -c @var{number} 907@item -pid @var{number} 908@itemx -p @var{number} 909@cindex @code{--pid} 910@cindex @code{-p} 911Connect to process ID @var{number}, as with the @code{attach} command. 912If there is no such process, @value{GDBN} will attempt to open a core 913file named @var{number}. 914 915@item -command @var{file} 916@itemx -x @var{file} 917@cindex @code{--command} 918@cindex @code{-x} 919Execute @value{GDBN} commands from file @var{file}. @xref{Command 920Files,, Command files}. 921 922@item -directory @var{directory} 923@itemx -d @var{directory} 924@cindex @code{--directory} 925@cindex @code{-d} 926Add @var{directory} to the path to search for source files. 927 928@item -m 929@itemx -mapped 930@cindex @code{--mapped} 931@cindex @code{-m} 932@emph{Warning: this option depends on operating system facilities that are not 933supported on all systems.}@* 934If memory-mapped files are available on your system through the @code{mmap} 935system call, you can use this option 936to have @value{GDBN} write the symbols from your 937program into a reusable file in the current directory. If the program you are debugging is 938called @file{/tmp/fred}, the mapped symbol file is @file{/tmp/fred.syms}. 939Future @value{GDBN} debugging sessions notice the presence of this file, 940and can quickly map in symbol information from it, rather than reading 941the symbol table from the executable program. 942 943The @file{.syms} file is specific to the host machine where @value{GDBN} 944is run. It holds an exact image of the internal @value{GDBN} symbol 945table. It cannot be shared across multiple host platforms. 946 947@item -r 948@itemx -readnow 949@cindex @code{--readnow} 950@cindex @code{-r} 951Read each symbol file's entire symbol table immediately, rather than 952the default, which is to read it incrementally as it is needed. 953This makes startup slower, but makes future operations faster. 954 955@end table 956 957You typically combine the @code{-mapped} and @code{-readnow} options in 958order to build a @file{.syms} file that contains complete symbol 959information. (@xref{Files,,Commands to specify files}, for information 960on @file{.syms} files.) A simple @value{GDBN} invocation to do nothing 961but build a @file{.syms} file for future use is: 962 963@smallexample 964gdb -batch -nx -mapped -readnow programname 965@end smallexample 966 967@node Mode Options 968@subsection Choosing modes 969 970You can run @value{GDBN} in various alternative modes---for example, in 971batch mode or quiet mode. 972 973@table @code 974@item -nx 975@itemx -n 976@cindex @code{--nx} 977@cindex @code{-n} 978Do not execute commands found in any initialization files. Normally, 979@value{GDBN} executes the commands in these files after all the command 980options and arguments have been processed. @xref{Command Files,,Command 981files}. 982 983@item -quiet 984@itemx -silent 985@itemx -q 986@cindex @code{--quiet} 987@cindex @code{--silent} 988@cindex @code{-q} 989``Quiet''. Do not print the introductory and copyright messages. These 990messages are also suppressed in batch mode. 991 992@item -batch 993@cindex @code{--batch} 994Run in batch mode. Exit with status @code{0} after processing all the 995command files specified with @samp{-x} (and all commands from 996initialization files, if not inhibited with @samp{-n}). Exit with 997nonzero status if an error occurs in executing the @value{GDBN} commands 998in the command files. 999 1000Batch mode may be useful for running @value{GDBN} as a filter, for 1001example to download and run a program on another computer; in order to 1002make this more useful, the message 1003 1004@smallexample 1005Program exited normally. 1006@end smallexample 1007 1008@noindent 1009(which is ordinarily issued whenever a program running under 1010@value{GDBN} control terminates) is not issued when running in batch 1011mode. 1012 1013@item -nowindows 1014@itemx -nw 1015@cindex @code{--nowindows} 1016@cindex @code{-nw} 1017``No windows''. If @value{GDBN} comes with a graphical user interface 1018(GUI) built in, then this option tells @value{GDBN} to only use the command-line 1019interface. If no GUI is available, this option has no effect. 1020 1021@item -windows 1022@itemx -w 1023@cindex @code{--windows} 1024@cindex @code{-w} 1025If @value{GDBN} includes a GUI, then this option requires it to be 1026used if possible. 1027 1028@item -cd @var{directory} 1029@cindex @code{--cd} 1030Run @value{GDBN} using @var{directory} as its working directory, 1031instead of the current directory. 1032 1033@item -fullname 1034@itemx -f 1035@cindex @code{--fullname} 1036@cindex @code{-f} 1037@sc{gnu} Emacs sets this option when it runs @value{GDBN} as a 1038subprocess. It tells @value{GDBN} to output the full file name and line 1039number in a standard, recognizable fashion each time a stack frame is 1040displayed (which includes each time your program stops). This 1041recognizable format looks like two @samp{\032} characters, followed by 1042the file name, line number and character position separated by colons, 1043and a newline. The Emacs-to-@value{GDBN} interface program uses the two 1044@samp{\032} characters as a signal to display the source code for the 1045frame. 1046 1047@item -epoch 1048@cindex @code{--epoch} 1049The Epoch Emacs-@value{GDBN} interface sets this option when it runs 1050@value{GDBN} as a subprocess. It tells @value{GDBN} to modify its print 1051routines so as to allow Epoch to display values of expressions in a 1052separate window. 1053 1054@item -annotate @var{level} 1055@cindex @code{--annotate} 1056This option sets the @dfn{annotation level} inside @value{GDBN}. Its 1057effect is identical to using @samp{set annotate @var{level}} 1058(@pxref{Annotations}). The annotation @var{level} controls how much 1059information @value{GDBN} prints together with its prompt, values of 1060expressions, source lines, and other types of output. Level 0 is the 1061normal, level 1 is for use when @value{GDBN} is run as a subprocess of 1062@sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs 1063that control @value{GDBN}, and level 2 has been deprecated. 1064 1065The annotation mechanism has largely been superseeded by @sc{gdb/mi} 1066(@pxref{GDB/MI}). 1067 1068@item --args 1069@cindex @code{--args} 1070Change interpretation of command line so that arguments following the 1071executable file are passed as command line arguments to the inferior. 1072This option stops option processing. 1073 1074@item -baud @var{bps} 1075@itemx -b @var{bps} 1076@cindex @code{--baud} 1077@cindex @code{-b} 1078Set the line speed (baud rate or bits per second) of any serial 1079interface used by @value{GDBN} for remote debugging. 1080 1081@item -tty @var{device} 1082@itemx -t @var{device} 1083@cindex @code{--tty} 1084@cindex @code{-t} 1085Run using @var{device} for your program's standard input and output. 1086@c FIXME: kingdon thinks there is more to -tty. Investigate. 1087 1088@c resolve the situation of these eventually 1089@item -tui 1090@cindex @code{--tui} 1091Activate the @dfn{Text User Interface} when starting. The Text User 1092Interface manages several text windows on the terminal, showing 1093source, assembly, registers and @value{GDBN} command outputs 1094(@pxref{TUI, ,@value{GDBN} Text User Interface}). Alternatively, the 1095Text User Interface can be enabled by invoking the program 1096@samp{gdbtui}. Do not use this option if you run @value{GDBN} from 1097Emacs (@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}). 1098 1099@c @item -xdb 1100@c @cindex @code{--xdb} 1101@c Run in XDB compatibility mode, allowing the use of certain XDB commands. 1102@c For information, see the file @file{xdb_trans.html}, which is usually 1103@c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX 1104@c systems. 1105 1106@item -interpreter @var{interp} 1107@cindex @code{--interpreter} 1108Use the interpreter @var{interp} for interface with the controlling 1109program or device. This option is meant to be set by programs which 1110communicate with @value{GDBN} using it as a back end. 1111@xref{Interpreters, , Command Interpreters}. 1112 1113@samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes 1114@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} (@pxref{GDB/MI, , 1115The @sc{gdb/mi} Interface}) included since @var{GDBN} version 6.0. The 1116previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and 1117selected with @samp{--interpreter=mi1}, is deprecated. Earlier 1118@sc{gdb/mi} interfaces are no longer supported. 1119 1120@item -write 1121@cindex @code{--write} 1122Open the executable and core files for both reading and writing. This 1123is equivalent to the @samp{set write on} command inside @value{GDBN} 1124(@pxref{Patching}). 1125 1126@item -statistics 1127@cindex @code{--statistics} 1128This option causes @value{GDBN} to print statistics about time and 1129memory usage after it completes each command and returns to the prompt. 1130 1131@item -version 1132@cindex @code{--version} 1133This option causes @value{GDBN} to print its version number and 1134no-warranty blurb, and exit. 1135 1136@end table 1137 1138@node Quitting GDB 1139@section Quitting @value{GDBN} 1140@cindex exiting @value{GDBN} 1141@cindex leaving @value{GDBN} 1142 1143@table @code 1144@kindex quit @r{[}@var{expression}@r{]} 1145@kindex q @r{(@code{quit})} 1146@item quit @r{[}@var{expression}@r{]} 1147@itemx q 1148To exit @value{GDBN}, use the @code{quit} command (abbreviated 1149@code{q}), or type an end-of-file character (usually @kbd{C-d}). If you 1150do not supply @var{expression}, @value{GDBN} will terminate normally; 1151otherwise it will terminate using the result of @var{expression} as the 1152error code. 1153@end table 1154 1155@cindex interrupt 1156An interrupt (often @kbd{C-c}) does not exit from @value{GDBN}, but rather 1157terminates the action of any @value{GDBN} command that is in progress and 1158returns to @value{GDBN} command level. It is safe to type the interrupt 1159character at any time because @value{GDBN} does not allow it to take effect 1160until a time when it is safe. 1161 1162If you have been using @value{GDBN} to control an attached process or 1163device, you can release it with the @code{detach} command 1164(@pxref{Attach, ,Debugging an already-running process}). 1165 1166@node Shell Commands 1167@section Shell commands 1168 1169If you need to execute occasional shell commands during your 1170debugging session, there is no need to leave or suspend @value{GDBN}; you can 1171just use the @code{shell} command. 1172 1173@table @code 1174@kindex shell 1175@cindex shell escape 1176@item shell @var{command string} 1177Invoke a standard shell to execute @var{command string}. 1178If it exists, the environment variable @code{SHELL} determines which 1179shell to run. Otherwise @value{GDBN} uses the default shell 1180(@file{/bin/sh} on Unix systems, @file{COMMAND.COM} on MS-DOS, etc.). 1181@end table 1182 1183The utility @code{make} is often needed in development environments. 1184You do not have to use the @code{shell} command for this purpose in 1185@value{GDBN}: 1186 1187@table @code 1188@kindex make 1189@cindex calling make 1190@item make @var{make-args} 1191Execute the @code{make} program with the specified 1192arguments. This is equivalent to @samp{shell make @var{make-args}}. 1193@end table 1194 1195@node Logging output 1196@section Logging output 1197@cindex logging @value{GDBN} output 1198 1199You may want to save the output of @value{GDBN} commands to a file. 1200There are several commands to control @value{GDBN}'s logging. 1201 1202@table @code 1203@kindex set logging 1204@item set logging on 1205Enable logging. 1206@item set logging off 1207Disable logging. 1208@item set logging file @var{file} 1209Change the name of the current logfile. The default logfile is @file{gdb.txt}. 1210@item set logging overwrite [on|off] 1211By default, @value{GDBN} will append to the logfile. Set @code{overwrite} if 1212you want @code{set logging on} to overwrite the logfile instead. 1213@item set logging redirect [on|off] 1214By default, @value{GDBN} output will go to both the terminal and the logfile. 1215Set @code{redirect} if you want output to go only to the log file. 1216@kindex show logging 1217@item show logging 1218Show the current values of the logging settings. 1219@end table 1220 1221@node Commands 1222@chapter @value{GDBN} Commands 1223 1224You can abbreviate a @value{GDBN} command to the first few letters of the command 1225name, if that abbreviation is unambiguous; and you can repeat certain 1226@value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB} 1227key to get @value{GDBN} to fill out the rest of a word in a command (or to 1228show you the alternatives available, if there is more than one possibility). 1229 1230@menu 1231* Command Syntax:: How to give commands to @value{GDBN} 1232* Completion:: Command completion 1233* Help:: How to ask @value{GDBN} for help 1234@end menu 1235 1236@node Command Syntax 1237@section Command syntax 1238 1239A @value{GDBN} command is a single line of input. There is no limit on 1240how long it can be. It starts with a command name, which is followed by 1241arguments whose meaning depends on the command name. For example, the 1242command @code{step} accepts an argument which is the number of times to 1243step, as in @samp{step 5}. You can also use the @code{step} command 1244with no arguments. Some commands do not allow any arguments. 1245 1246@cindex abbreviation 1247@value{GDBN} command names may always be truncated if that abbreviation is 1248unambiguous. Other possible command abbreviations are listed in the 1249documentation for individual commands. In some cases, even ambiguous 1250abbreviations are allowed; for example, @code{s} is specially defined as 1251equivalent to @code{step} even though there are other commands whose 1252names start with @code{s}. You can test abbreviations by using them as 1253arguments to the @code{help} command. 1254 1255@cindex repeating commands 1256@kindex RET @r{(repeat last command)} 1257A blank line as input to @value{GDBN} (typing just @key{RET}) means to 1258repeat the previous command. Certain commands (for example, @code{run}) 1259will not repeat this way; these are commands whose unintentional 1260repetition might cause trouble and which you are unlikely to want to 1261repeat. 1262 1263The @code{list} and @code{x} commands, when you repeat them with 1264@key{RET}, construct new arguments rather than repeating 1265exactly as typed. This permits easy scanning of source or memory. 1266 1267@value{GDBN} can also use @key{RET} in another way: to partition lengthy 1268output, in a way similar to the common utility @code{more} 1269(@pxref{Screen Size,,Screen size}). Since it is easy to press one 1270@key{RET} too many in this situation, @value{GDBN} disables command 1271repetition after any command that generates this sort of display. 1272 1273@kindex # @r{(a comment)} 1274@cindex comment 1275Any text from a @kbd{#} to the end of the line is a comment; it does 1276nothing. This is useful mainly in command files (@pxref{Command 1277Files,,Command files}). 1278 1279@cindex repeating command sequences 1280@kindex C-o @r{(operate-and-get-next)} 1281The @kbd{C-o} binding is useful for repeating a complex sequence of 1282commands. This command accepts the current line, like @kbd{RET}, and 1283then fetches the next line relative to the current line from the history 1284for editing. 1285 1286@node Completion 1287@section Command completion 1288 1289@cindex completion 1290@cindex word completion 1291@value{GDBN} can fill in the rest of a word in a command for you, if there is 1292only one possibility; it can also show you what the valid possibilities 1293are for the next word in a command, at any time. This works for @value{GDBN} 1294commands, @value{GDBN} subcommands, and the names of symbols in your program. 1295 1296Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest 1297of a word. If there is only one possibility, @value{GDBN} fills in the 1298word, and waits for you to finish the command (or press @key{RET} to 1299enter it). For example, if you type 1300 1301@c FIXME "@key" does not distinguish its argument sufficiently to permit 1302@c complete accuracy in these examples; space introduced for clarity. 1303@c If texinfo enhancements make it unnecessary, it would be nice to 1304@c replace " @key" by "@key" in the following... 1305@smallexample 1306(@value{GDBP}) info bre @key{TAB} 1307@end smallexample 1308 1309@noindent 1310@value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is 1311the only @code{info} subcommand beginning with @samp{bre}: 1312 1313@smallexample 1314(@value{GDBP}) info breakpoints 1315@end smallexample 1316 1317@noindent 1318You can either press @key{RET} at this point, to run the @code{info 1319breakpoints} command, or backspace and enter something else, if 1320@samp{breakpoints} does not look like the command you expected. (If you 1321were sure you wanted @code{info breakpoints} in the first place, you 1322might as well just type @key{RET} immediately after @samp{info bre}, 1323to exploit command abbreviations rather than command completion). 1324 1325If there is more than one possibility for the next word when you press 1326@key{TAB}, @value{GDBN} sounds a bell. You can either supply more 1327characters and try again, or just press @key{TAB} a second time; 1328@value{GDBN} displays all the possible completions for that word. For 1329example, you might want to set a breakpoint on a subroutine whose name 1330begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN} 1331just sounds the bell. Typing @key{TAB} again displays all the 1332function names in your program that begin with those characters, for 1333example: 1334 1335@smallexample 1336(@value{GDBP}) b make_ @key{TAB} 1337@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see: 1338make_a_section_from_file make_environ 1339make_abs_section make_function_type 1340make_blockvector make_pointer_type 1341make_cleanup make_reference_type 1342make_command make_symbol_completion_list 1343(@value{GDBP}) b make_ 1344@end smallexample 1345 1346@noindent 1347After displaying the available possibilities, @value{GDBN} copies your 1348partial input (@samp{b make_} in the example) so you can finish the 1349command. 1350 1351If you just want to see the list of alternatives in the first place, you 1352can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?} 1353means @kbd{@key{META} ?}. You can type this either by holding down a 1354key designated as the @key{META} shift on your keyboard (if there is 1355one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}. 1356 1357@cindex quotes in commands 1358@cindex completion of quoted strings 1359Sometimes the string you need, while logically a ``word'', may contain 1360parentheses or other characters that @value{GDBN} normally excludes from 1361its notion of a word. To permit word completion to work in this 1362situation, you may enclose words in @code{'} (single quote marks) in 1363@value{GDBN} commands. 1364 1365The most likely situation where you might need this is in typing the 1366name of a C@t{++} function. This is because C@t{++} allows function 1367overloading (multiple definitions of the same function, distinguished 1368by argument type). For example, when you want to set a breakpoint you 1369may need to distinguish whether you mean the version of @code{name} 1370that takes an @code{int} parameter, @code{name(int)}, or the version 1371that takes a @code{float} parameter, @code{name(float)}. To use the 1372word-completion facilities in this situation, type a single quote 1373@code{'} at the beginning of the function name. This alerts 1374@value{GDBN} that it may need to consider more information than usual 1375when you press @key{TAB} or @kbd{M-?} to request word completion: 1376 1377@smallexample 1378(@value{GDBP}) b 'bubble( @kbd{M-?} 1379bubble(double,double) bubble(int,int) 1380(@value{GDBP}) b 'bubble( 1381@end smallexample 1382 1383In some cases, @value{GDBN} can tell that completing a name requires using 1384quotes. When this happens, @value{GDBN} inserts the quote for you (while 1385completing as much as it can) if you do not type the quote in the first 1386place: 1387 1388@smallexample 1389(@value{GDBP}) b bub @key{TAB} 1390@exdent @value{GDBN} alters your input line to the following, and rings a bell: 1391(@value{GDBP}) b 'bubble( 1392@end smallexample 1393 1394@noindent 1395In general, @value{GDBN} can tell that a quote is needed (and inserts it) if 1396you have not yet started typing the argument list when you ask for 1397completion on an overloaded symbol. 1398 1399For more information about overloaded functions, see @ref{C plus plus 1400expressions, ,C@t{++} expressions}. You can use the command @code{set 1401overload-resolution off} to disable overload resolution; 1402see @ref{Debugging C plus plus, ,@value{GDBN} features for C@t{++}}. 1403 1404 1405@node Help 1406@section Getting help 1407@cindex online documentation 1408@kindex help 1409 1410You can always ask @value{GDBN} itself for information on its commands, 1411using the command @code{help}. 1412 1413@table @code 1414@kindex h @r{(@code{help})} 1415@item help 1416@itemx h 1417You can use @code{help} (abbreviated @code{h}) with no arguments to 1418display a short list of named classes of commands: 1419 1420@smallexample 1421(@value{GDBP}) help 1422List of classes of commands: 1423 1424aliases -- Aliases of other commands 1425breakpoints -- Making program stop at certain points 1426data -- Examining data 1427files -- Specifying and examining files 1428internals -- Maintenance commands 1429obscure -- Obscure features 1430running -- Running the program 1431stack -- Examining the stack 1432status -- Status inquiries 1433support -- Support facilities 1434tracepoints -- Tracing of program execution without@* 1435 stopping the program 1436user-defined -- User-defined commands 1437 1438Type "help" followed by a class name for a list of 1439commands in that class. 1440Type "help" followed by command name for full 1441documentation. 1442Command name abbreviations are allowed if unambiguous. 1443(@value{GDBP}) 1444@end smallexample 1445@c the above line break eliminates huge line overfull... 1446 1447@item help @var{class} 1448Using one of the general help classes as an argument, you can get a 1449list of the individual commands in that class. For example, here is the 1450help display for the class @code{status}: 1451 1452@smallexample 1453(@value{GDBP}) help status 1454Status inquiries. 1455 1456List of commands: 1457 1458@c Line break in "show" line falsifies real output, but needed 1459@c to fit in smallbook page size. 1460info -- Generic command for showing things 1461 about the program being debugged 1462show -- Generic command for showing things 1463 about the debugger 1464 1465Type "help" followed by command name for full 1466documentation. 1467Command name abbreviations are allowed if unambiguous. 1468(@value{GDBP}) 1469@end smallexample 1470 1471@item help @var{command} 1472With a command name as @code{help} argument, @value{GDBN} displays a 1473short paragraph on how to use that command. 1474 1475@kindex apropos 1476@item apropos @var{args} 1477The @code{apropos @var{args}} command searches through all of the @value{GDBN} 1478commands, and their documentation, for the regular expression specified in 1479@var{args}. It prints out all matches found. For example: 1480 1481@smallexample 1482apropos reload 1483@end smallexample 1484 1485@noindent 1486results in: 1487 1488@smallexample 1489@c @group 1490set symbol-reloading -- Set dynamic symbol table reloading 1491 multiple times in one run 1492show symbol-reloading -- Show dynamic symbol table reloading 1493 multiple times in one run 1494@c @end group 1495@end smallexample 1496 1497@kindex complete 1498@item complete @var{args} 1499The @code{complete @var{args}} command lists all the possible completions 1500for the beginning of a command. Use @var{args} to specify the beginning of the 1501command you want completed. For example: 1502 1503@smallexample 1504complete i 1505@end smallexample 1506 1507@noindent results in: 1508 1509@smallexample 1510@group 1511if 1512ignore 1513info 1514inspect 1515@end group 1516@end smallexample 1517 1518@noindent This is intended for use by @sc{gnu} Emacs. 1519@end table 1520 1521In addition to @code{help}, you can use the @value{GDBN} commands @code{info} 1522and @code{show} to inquire about the state of your program, or the state 1523of @value{GDBN} itself. Each command supports many topics of inquiry; this 1524manual introduces each of them in the appropriate context. The listings 1525under @code{info} and under @code{show} in the Index point to 1526all the sub-commands. @xref{Index}. 1527 1528@c @group 1529@table @code 1530@kindex info 1531@kindex i @r{(@code{info})} 1532@item info 1533This command (abbreviated @code{i}) is for describing the state of your 1534program. For example, you can list the arguments given to your program 1535with @code{info args}, list the registers currently in use with @code{info 1536registers}, or list the breakpoints you have set with @code{info breakpoints}. 1537You can get a complete list of the @code{info} sub-commands with 1538@w{@code{help info}}. 1539 1540@kindex set 1541@item set 1542You can assign the result of an expression to an environment variable with 1543@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with 1544@code{set prompt $}. 1545 1546@kindex show 1547@item show 1548In contrast to @code{info}, @code{show} is for describing the state of 1549@value{GDBN} itself. 1550You can change most of the things you can @code{show}, by using the 1551related command @code{set}; for example, you can control what number 1552system is used for displays with @code{set radix}, or simply inquire 1553which is currently in use with @code{show radix}. 1554 1555@kindex info set 1556To display all the settable parameters and their current 1557values, you can use @code{show} with no arguments; you may also use 1558@code{info set}. Both commands produce the same display. 1559@c FIXME: "info set" violates the rule that "info" is for state of 1560@c FIXME...program. Ck w/ GNU: "info set" to be called something else, 1561@c FIXME...or change desc of rule---eg "state of prog and debugging session"? 1562@end table 1563@c @end group 1564 1565Here are three miscellaneous @code{show} subcommands, all of which are 1566exceptional in lacking corresponding @code{set} commands: 1567 1568@table @code 1569@kindex show version 1570@cindex version number 1571@item show version 1572Show what version of @value{GDBN} is running. You should include this 1573information in @value{GDBN} bug-reports. If multiple versions of 1574@value{GDBN} are in use at your site, you may need to determine which 1575version of @value{GDBN} you are running; as @value{GDBN} evolves, new 1576commands are introduced, and old ones may wither away. Also, many 1577system vendors ship variant versions of @value{GDBN}, and there are 1578variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well. 1579The version number is the same as the one announced when you start 1580@value{GDBN}. 1581 1582@kindex show copying 1583@item show copying 1584Display information about permission for copying @value{GDBN}. 1585 1586@kindex show warranty 1587@item show warranty 1588Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty, 1589if your version of @value{GDBN} comes with one. 1590 1591@end table 1592 1593@node Running 1594@chapter Running Programs Under @value{GDBN} 1595 1596When you run a program under @value{GDBN}, you must first generate 1597debugging information when you compile it. 1598 1599You may start @value{GDBN} with its arguments, if any, in an environment 1600of your choice. If you are doing native debugging, you may redirect 1601your program's input and output, debug an already running process, or 1602kill a child process. 1603 1604@menu 1605* Compilation:: Compiling for debugging 1606* Starting:: Starting your program 1607* Arguments:: Your program's arguments 1608* Environment:: Your program's environment 1609 1610* Working Directory:: Your program's working directory 1611* Input/Output:: Your program's input and output 1612* Attach:: Debugging an already-running process 1613* Kill Process:: Killing the child process 1614 1615* Threads:: Debugging programs with multiple threads 1616* Processes:: Debugging programs with multiple processes 1617@end menu 1618 1619@node Compilation 1620@section Compiling for debugging 1621 1622In order to debug a program effectively, you need to generate 1623debugging information when you compile it. This debugging information 1624is stored in the object file; it describes the data type of each 1625variable or function and the correspondence between source line numbers 1626and addresses in the executable code. 1627 1628To request debugging information, specify the @samp{-g} option when you run 1629the compiler. 1630 1631Most compilers do not include information about preprocessor macros in 1632the debugging information if you specify the @option{-g} flag alone, 1633because this information is rather large. Version 3.1 of @value{NGCC}, 1634the @sc{gnu} C compiler, provides macro information if you specify the 1635options @option{-gdwarf-2} and @option{-g3}; the former option requests 1636debugging information in the Dwarf 2 format, and the latter requests 1637``extra information''. In the future, we hope to find more compact ways 1638to represent macro information, so that it can be included with 1639@option{-g} alone. 1640 1641Many C compilers are unable to handle the @samp{-g} and @samp{-O} 1642options together. Using those compilers, you cannot generate optimized 1643executables containing debugging information. 1644 1645@value{NGCC}, the @sc{gnu} C compiler, supports @samp{-g} with or 1646without @samp{-O}, making it possible to debug optimized code. We 1647recommend that you @emph{always} use @samp{-g} whenever you compile a 1648program. You may think your program is correct, but there is no sense 1649in pushing your luck. 1650 1651@cindex optimized code, debugging 1652@cindex debugging optimized code 1653When you debug a program compiled with @samp{-g -O}, remember that the 1654optimizer is rearranging your code; the debugger shows you what is 1655really there. Do not be too surprised when the execution path does not 1656exactly match your source file! An extreme example: if you define a 1657variable, but never use it, @value{GDBN} never sees that 1658variable---because the compiler optimizes it out of existence. 1659 1660Some things do not work as well with @samp{-g -O} as with just 1661@samp{-g}, particularly on machines with instruction scheduling. If in 1662doubt, recompile with @samp{-g} alone, and if this fixes the problem, 1663please report it to us as a bug (including a test case!). 1664@xref{Variables}, for more information about debugging optimized code. 1665 1666Older versions of the @sc{gnu} C compiler permitted a variant option 1667@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this 1668format; if your @sc{gnu} C compiler has this option, do not use it. 1669 1670@need 2000 1671@node Starting 1672@section Starting your program 1673@cindex starting 1674@cindex running 1675 1676@table @code 1677@kindex run 1678@kindex r @r{(@code{run})} 1679@item run 1680@itemx r 1681Use the @code{run} command to start your program under @value{GDBN}. 1682You must first specify the program name (except on VxWorks) with an 1683argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of 1684@value{GDBN}}), or by using the @code{file} or @code{exec-file} command 1685(@pxref{Files, ,Commands to specify files}). 1686 1687@end table 1688 1689If you are running your program in an execution environment that 1690supports processes, @code{run} creates an inferior process and makes 1691that process run your program. (In environments without processes, 1692@code{run} jumps to the start of your program.) 1693 1694The execution of a program is affected by certain information it 1695receives from its superior. @value{GDBN} provides ways to specify this 1696information, which you must do @emph{before} starting your program. (You 1697can change it after starting your program, but such changes only affect 1698your program the next time you start it.) This information may be 1699divided into four categories: 1700 1701@table @asis 1702@item The @emph{arguments.} 1703Specify the arguments to give your program as the arguments of the 1704@code{run} command. If a shell is available on your target, the shell 1705is used to pass the arguments, so that you may use normal conventions 1706(such as wildcard expansion or variable substitution) in describing 1707the arguments. 1708In Unix systems, you can control which shell is used with the 1709@code{SHELL} environment variable. 1710@xref{Arguments, ,Your program's arguments}. 1711 1712@item The @emph{environment.} 1713Your program normally inherits its environment from @value{GDBN}, but you can 1714use the @value{GDBN} commands @code{set environment} and @code{unset 1715environment} to change parts of the environment that affect 1716your program. @xref{Environment, ,Your program's environment}. 1717 1718@item The @emph{working directory.} 1719Your program inherits its working directory from @value{GDBN}. You can set 1720the @value{GDBN} working directory with the @code{cd} command in @value{GDBN}. 1721@xref{Working Directory, ,Your program's working directory}. 1722 1723@item The @emph{standard input and output.} 1724Your program normally uses the same device for standard input and 1725standard output as @value{GDBN} is using. You can redirect input and output 1726in the @code{run} command line, or you can use the @code{tty} command to 1727set a different device for your program. 1728@xref{Input/Output, ,Your program's input and output}. 1729 1730@cindex pipes 1731@emph{Warning:} While input and output redirection work, you cannot use 1732pipes to pass the output of the program you are debugging to another 1733program; if you attempt this, @value{GDBN} is likely to wind up debugging the 1734wrong program. 1735@end table 1736 1737When you issue the @code{run} command, your program begins to execute 1738immediately. @xref{Stopping, ,Stopping and continuing}, for discussion 1739of how to arrange for your program to stop. Once your program has 1740stopped, you may call functions in your program, using the @code{print} 1741or @code{call} commands. @xref{Data, ,Examining Data}. 1742 1743If the modification time of your symbol file has changed since the last 1744time @value{GDBN} read its symbols, @value{GDBN} discards its symbol 1745table, and reads it again. When it does this, @value{GDBN} tries to retain 1746your current breakpoints. 1747 1748@table @code 1749@kindex start 1750@item start 1751@cindex run to main procedure 1752The name of the main procedure can vary from language to language. 1753With C or C@t{++}, the main procedure name is always @code{main}, but 1754other languages such as Ada do not require a specific name for their 1755main procedure. The debugger provides a convenient way to start the 1756execution of the program and to stop at the beginning of the main 1757procedure, depending on the language used. 1758 1759The @samp{start} command does the equivalent of setting a temporary 1760breakpoint at the beginning of the main procedure and then invoking 1761the @samp{run} command. 1762 1763Some programs contain an elaboration phase where some startup code is 1764executed before the main program is called. This depends on the 1765languages used to write your program. In C@t{++} for instance, 1766constructors for static and global objects are executed before 1767@code{main} is called. It is therefore possible that the debugger stops 1768before reaching the main procedure. However, the temporary breakpoint 1769will remain to halt execution. 1770 1771Specify the arguments to give to your program as arguments to the 1772@samp{start} command. These arguments will be given verbatim to the 1773underlying @samp{run} command. Note that the same arguments will be 1774reused if no argument is provided during subsequent calls to 1775@samp{start} or @samp{run}. 1776 1777It is sometimes necessary to debug the program during elaboration. In 1778these cases, using the @code{start} command would stop the execution of 1779your program too late, as the program would have already completed the 1780elaboration phase. Under these circumstances, insert breakpoints in your 1781elaboration code before running your program. 1782@end table 1783 1784@node Arguments 1785@section Your program's arguments 1786 1787@cindex arguments (to your program) 1788The arguments to your program can be specified by the arguments of the 1789@code{run} command. 1790They are passed to a shell, which expands wildcard characters and 1791performs redirection of I/O, and thence to your program. Your 1792@code{SHELL} environment variable (if it exists) specifies what shell 1793@value{GDBN} uses. If you do not define @code{SHELL}, @value{GDBN} uses 1794the default shell (@file{/bin/sh} on Unix). 1795 1796On non-Unix systems, the program is usually invoked directly by 1797@value{GDBN}, which emulates I/O redirection via the appropriate system 1798calls, and the wildcard characters are expanded by the startup code of 1799the program, not by the shell. 1800 1801@code{run} with no arguments uses the same arguments used by the previous 1802@code{run}, or those set by the @code{set args} command. 1803 1804@table @code 1805@kindex set args 1806@item set args 1807Specify the arguments to be used the next time your program is run. If 1808@code{set args} has no arguments, @code{run} executes your program 1809with no arguments. Once you have run your program with arguments, 1810using @code{set args} before the next @code{run} is the only way to run 1811it again without arguments. 1812 1813@kindex show args 1814@item show args 1815Show the arguments to give your program when it is started. 1816@end table 1817 1818@node Environment 1819@section Your program's environment 1820 1821@cindex environment (of your program) 1822The @dfn{environment} consists of a set of environment variables and 1823their values. Environment variables conventionally record such things as 1824your user name, your home directory, your terminal type, and your search 1825path for programs to run. Usually you set up environment variables with 1826the shell and they are inherited by all the other programs you run. When 1827debugging, it can be useful to try running your program with a modified 1828environment without having to start @value{GDBN} over again. 1829 1830@table @code 1831@kindex path 1832@item path @var{directory} 1833Add @var{directory} to the front of the @code{PATH} environment variable 1834(the search path for executables) that will be passed to your program. 1835The value of @code{PATH} used by @value{GDBN} does not change. 1836You may specify several directory names, separated by whitespace or by a 1837system-dependent separator character (@samp{:} on Unix, @samp{;} on 1838MS-DOS and MS-Windows). If @var{directory} is already in the path, it 1839is moved to the front, so it is searched sooner. 1840 1841You can use the string @samp{$cwd} to refer to whatever is the current 1842working directory at the time @value{GDBN} searches the path. If you 1843use @samp{.} instead, it refers to the directory where you executed the 1844@code{path} command. @value{GDBN} replaces @samp{.} in the 1845@var{directory} argument (with the current path) before adding 1846@var{directory} to the search path. 1847@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to 1848@c document that, since repeating it would be a no-op. 1849 1850@kindex show paths 1851@item show paths 1852Display the list of search paths for executables (the @code{PATH} 1853environment variable). 1854 1855@kindex show environment 1856@item show environment @r{[}@var{varname}@r{]} 1857Print the value of environment variable @var{varname} to be given to 1858your program when it starts. If you do not supply @var{varname}, 1859print the names and values of all environment variables to be given to 1860your program. You can abbreviate @code{environment} as @code{env}. 1861 1862@kindex set environment 1863@item set environment @var{varname} @r{[}=@var{value}@r{]} 1864Set environment variable @var{varname} to @var{value}. The value 1865changes for your program only, not for @value{GDBN} itself. @var{value} may 1866be any string; the values of environment variables are just strings, and 1867any interpretation is supplied by your program itself. The @var{value} 1868parameter is optional; if it is eliminated, the variable is set to a 1869null value. 1870@c "any string" here does not include leading, trailing 1871@c blanks. Gnu asks: does anyone care? 1872 1873For example, this command: 1874 1875@smallexample 1876set env USER = foo 1877@end smallexample 1878 1879@noindent 1880tells the debugged program, when subsequently run, that its user is named 1881@samp{foo}. (The spaces around @samp{=} are used for clarity here; they 1882are not actually required.) 1883 1884@kindex unset environment 1885@item unset environment @var{varname} 1886Remove variable @var{varname} from the environment to be passed to your 1887program. This is different from @samp{set env @var{varname} =}; 1888@code{unset environment} removes the variable from the environment, 1889rather than assigning it an empty value. 1890@end table 1891 1892@emph{Warning:} On Unix systems, @value{GDBN} runs your program using 1893the shell indicated 1894by your @code{SHELL} environment variable if it exists (or 1895@code{/bin/sh} if not). If your @code{SHELL} variable names a shell 1896that runs an initialization file---such as @file{.cshrc} for C-shell, or 1897@file{.bashrc} for BASH---any variables you set in that file affect 1898your program. You may wish to move setting of environment variables to 1899files that are only run when you sign on, such as @file{.login} or 1900@file{.profile}. 1901 1902@node Working Directory 1903@section Your program's working directory 1904 1905@cindex working directory (of your program) 1906Each time you start your program with @code{run}, it inherits its 1907working directory from the current working directory of @value{GDBN}. 1908The @value{GDBN} working directory is initially whatever it inherited 1909from its parent process (typically the shell), but you can specify a new 1910working directory in @value{GDBN} with the @code{cd} command. 1911 1912The @value{GDBN} working directory also serves as a default for the commands 1913that specify files for @value{GDBN} to operate on. @xref{Files, ,Commands to 1914specify files}. 1915 1916@table @code 1917@kindex cd 1918@item cd @var{directory} 1919Set the @value{GDBN} working directory to @var{directory}. 1920 1921@kindex pwd 1922@item pwd 1923Print the @value{GDBN} working directory. 1924@end table 1925 1926@node Input/Output 1927@section Your program's input and output 1928 1929@cindex redirection 1930@cindex i/o 1931@cindex terminal 1932By default, the program you run under @value{GDBN} does input and output to 1933the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal 1934to its own terminal modes to interact with you, but it records the terminal 1935modes your program was using and switches back to them when you continue 1936running your program. 1937 1938@table @code 1939@kindex info terminal 1940@item info terminal 1941Displays information recorded by @value{GDBN} about the terminal modes your 1942program is using. 1943@end table 1944 1945You can redirect your program's input and/or output using shell 1946redirection with the @code{run} command. For example, 1947 1948@smallexample 1949run > outfile 1950@end smallexample 1951 1952@noindent 1953starts your program, diverting its output to the file @file{outfile}. 1954 1955@kindex tty 1956@cindex controlling terminal 1957Another way to specify where your program should do input and output is 1958with the @code{tty} command. This command accepts a file name as 1959argument, and causes this file to be the default for future @code{run} 1960commands. It also resets the controlling terminal for the child 1961process, for future @code{run} commands. For example, 1962 1963@smallexample 1964tty /dev/ttyb 1965@end smallexample 1966 1967@noindent 1968directs that processes started with subsequent @code{run} commands 1969default to do input and output on the terminal @file{/dev/ttyb} and have 1970that as their controlling terminal. 1971 1972An explicit redirection in @code{run} overrides the @code{tty} command's 1973effect on the input/output device, but not its effect on the controlling 1974terminal. 1975 1976When you use the @code{tty} command or redirect input in the @code{run} 1977command, only the input @emph{for your program} is affected. The input 1978for @value{GDBN} still comes from your terminal. 1979 1980@node Attach 1981@section Debugging an already-running process 1982@kindex attach 1983@cindex attach 1984 1985@table @code 1986@item attach @var{process-id} 1987This command attaches to a running process---one that was started 1988outside @value{GDBN}. (@code{info files} shows your active 1989targets.) The command takes as argument a process ID. The usual way to 1990find out the process-id of a Unix process is with the @code{ps} utility, 1991or with the @samp{jobs -l} shell command. 1992 1993@code{attach} does not repeat if you press @key{RET} a second time after 1994executing the command. 1995@end table 1996 1997To use @code{attach}, your program must be running in an environment 1998which supports processes; for example, @code{attach} does not work for 1999programs on bare-board targets that lack an operating system. You must 2000also have permission to send the process a signal. 2001 2002When you use @code{attach}, the debugger finds the program running in 2003the process first by looking in the current working directory, then (if 2004the program is not found) by using the source file search path 2005(@pxref{Source Path, ,Specifying source directories}). You can also use 2006the @code{file} command to load the program. @xref{Files, ,Commands to 2007Specify Files}. 2008 2009The first thing @value{GDBN} does after arranging to debug the specified 2010process is to stop it. You can examine and modify an attached process 2011with all the @value{GDBN} commands that are ordinarily available when 2012you start processes with @code{run}. You can insert breakpoints; you 2013can step and continue; you can modify storage. If you would rather the 2014process continue running, you may use the @code{continue} command after 2015attaching @value{GDBN} to the process. 2016 2017@table @code 2018@kindex detach 2019@item detach 2020When you have finished debugging the attached process, you can use the 2021@code{detach} command to release it from @value{GDBN} control. Detaching 2022the process continues its execution. After the @code{detach} command, 2023that process and @value{GDBN} become completely independent once more, and you 2024are ready to @code{attach} another process or start one with @code{run}. 2025@code{detach} does not repeat if you press @key{RET} again after 2026executing the command. 2027@end table 2028 2029If you exit @value{GDBN} or use the @code{run} command while you have an 2030attached process, you kill that process. By default, @value{GDBN} asks 2031for confirmation if you try to do either of these things; you can 2032control whether or not you need to confirm by using the @code{set 2033confirm} command (@pxref{Messages/Warnings, ,Optional warnings and 2034messages}). 2035 2036@node Kill Process 2037@section Killing the child process 2038 2039@table @code 2040@kindex kill 2041@item kill 2042Kill the child process in which your program is running under @value{GDBN}. 2043@end table 2044 2045This command is useful if you wish to debug a core dump instead of a 2046running process. @value{GDBN} ignores any core dump file while your program 2047is running. 2048 2049On some operating systems, a program cannot be executed outside @value{GDBN} 2050while you have breakpoints set on it inside @value{GDBN}. You can use the 2051@code{kill} command in this situation to permit running your program 2052outside the debugger. 2053 2054The @code{kill} command is also useful if you wish to recompile and 2055relink your program, since on many systems it is impossible to modify an 2056executable file while it is running in a process. In this case, when you 2057next type @code{run}, @value{GDBN} notices that the file has changed, and 2058reads the symbol table again (while trying to preserve your current 2059breakpoint settings). 2060 2061@node Threads 2062@section Debugging programs with multiple threads 2063 2064@cindex threads of execution 2065@cindex multiple threads 2066@cindex switching threads 2067In some operating systems, such as HP-UX and Solaris, a single program 2068may have more than one @dfn{thread} of execution. The precise semantics 2069of threads differ from one operating system to another, but in general 2070the threads of a single program are akin to multiple processes---except 2071that they share one address space (that is, they can all examine and 2072modify the same variables). On the other hand, each thread has its own 2073registers and execution stack, and perhaps private memory. 2074 2075@value{GDBN} provides these facilities for debugging multi-thread 2076programs: 2077 2078@itemize @bullet 2079@item automatic notification of new threads 2080@item @samp{thread @var{threadno}}, a command to switch among threads 2081@item @samp{info threads}, a command to inquire about existing threads 2082@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}}, 2083a command to apply a command to a list of threads 2084@item thread-specific breakpoints 2085@end itemize 2086 2087@quotation 2088@emph{Warning:} These facilities are not yet available on every 2089@value{GDBN} configuration where the operating system supports threads. 2090If your @value{GDBN} does not support threads, these commands have no 2091effect. For example, a system without thread support shows no output 2092from @samp{info threads}, and always rejects the @code{thread} command, 2093like this: 2094 2095@smallexample 2096(@value{GDBP}) info threads 2097(@value{GDBP}) thread 1 2098Thread ID 1 not known. Use the "info threads" command to 2099see the IDs of currently known threads. 2100@end smallexample 2101@c FIXME to implementors: how hard would it be to say "sorry, this GDB 2102@c doesn't support threads"? 2103@end quotation 2104 2105@cindex focus of debugging 2106@cindex current thread 2107The @value{GDBN} thread debugging facility allows you to observe all 2108threads while your program runs---but whenever @value{GDBN} takes 2109control, one thread in particular is always the focus of debugging. 2110This thread is called the @dfn{current thread}. Debugging commands show 2111program information from the perspective of the current thread. 2112 2113@cindex @code{New} @var{systag} message 2114@cindex thread identifier (system) 2115@c FIXME-implementors!! It would be more helpful if the [New...] message 2116@c included GDB's numeric thread handle, so you could just go to that 2117@c thread without first checking `info threads'. 2118Whenever @value{GDBN} detects a new thread in your program, it displays 2119the target system's identification for the thread with a message in the 2120form @samp{[New @var{systag}]}. @var{systag} is a thread identifier 2121whose form varies depending on the particular system. For example, on 2122LynxOS, you might see 2123 2124@smallexample 2125[New process 35 thread 27] 2126@end smallexample 2127 2128@noindent 2129when @value{GDBN} notices a new thread. In contrast, on an SGI system, 2130the @var{systag} is simply something like @samp{process 368}, with no 2131further qualifier. 2132 2133@c FIXME!! (1) Does the [New...] message appear even for the very first 2134@c thread of a program, or does it only appear for the 2135@c second---i.e.@: when it becomes obvious we have a multithread 2136@c program? 2137@c (2) *Is* there necessarily a first thread always? Or do some 2138@c multithread systems permit starting a program with multiple 2139@c threads ab initio? 2140 2141@cindex thread number 2142@cindex thread identifier (GDB) 2143For debugging purposes, @value{GDBN} associates its own thread 2144number---always a single integer---with each thread in your program. 2145 2146@table @code 2147@kindex info threads 2148@item info threads 2149Display a summary of all threads currently in your 2150program. @value{GDBN} displays for each thread (in this order): 2151 2152@enumerate 2153@item the thread number assigned by @value{GDBN} 2154 2155@item the target system's thread identifier (@var{systag}) 2156 2157@item the current stack frame summary for that thread 2158@end enumerate 2159 2160@noindent 2161An asterisk @samp{*} to the left of the @value{GDBN} thread number 2162indicates the current thread. 2163 2164For example, 2165@end table 2166@c end table here to get a little more width for example 2167 2168@smallexample 2169(@value{GDBP}) info threads 2170 3 process 35 thread 27 0x34e5 in sigpause () 2171 2 process 35 thread 23 0x34e5 in sigpause () 2172* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) 2173 at threadtest.c:68 2174@end smallexample 2175 2176On HP-UX systems: 2177 2178@cindex debugging multithreaded programs (on HP-UX) 2179@cindex thread identifier (GDB), on HP-UX 2180For debugging purposes, @value{GDBN} associates its own thread 2181number---a small integer assigned in thread-creation order---with each 2182thread in your program. 2183 2184@cindex @code{New} @var{systag} message, on HP-UX 2185@cindex thread identifier (system), on HP-UX 2186@c FIXME-implementors!! It would be more helpful if the [New...] message 2187@c included GDB's numeric thread handle, so you could just go to that 2188@c thread without first checking `info threads'. 2189Whenever @value{GDBN} detects a new thread in your program, it displays 2190both @value{GDBN}'s thread number and the target system's identification for the thread with a message in the 2191form @samp{[New @var{systag}]}. @var{systag} is a thread identifier 2192whose form varies depending on the particular system. For example, on 2193HP-UX, you see 2194 2195@smallexample 2196[New thread 2 (system thread 26594)] 2197@end smallexample 2198 2199@noindent 2200when @value{GDBN} notices a new thread. 2201 2202@table @code 2203@kindex info threads (HP-UX) 2204@item info threads 2205Display a summary of all threads currently in your 2206program. @value{GDBN} displays for each thread (in this order): 2207 2208@enumerate 2209@item the thread number assigned by @value{GDBN} 2210 2211@item the target system's thread identifier (@var{systag}) 2212 2213@item the current stack frame summary for that thread 2214@end enumerate 2215 2216@noindent 2217An asterisk @samp{*} to the left of the @value{GDBN} thread number 2218indicates the current thread. 2219 2220For example, 2221@end table 2222@c end table here to get a little more width for example 2223 2224@smallexample 2225(@value{GDBP}) info threads 2226 * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") \@* 2227 at quicksort.c:137 2228 2 system thread 26606 0x7b0030d8 in __ksleep () \@* 2229 from /usr/lib/libc.2 2230 1 system thread 27905 0x7b003498 in _brk () \@* 2231 from /usr/lib/libc.2 2232@end smallexample 2233 2234@table @code 2235@kindex thread @var{threadno} 2236@item thread @var{threadno} 2237Make thread number @var{threadno} the current thread. The command 2238argument @var{threadno} is the internal @value{GDBN} thread number, as 2239shown in the first field of the @samp{info threads} display. 2240@value{GDBN} responds by displaying the system identifier of the thread 2241you selected, and its current stack frame summary: 2242 2243@smallexample 2244@c FIXME!! This example made up; find a @value{GDBN} w/threads and get real one 2245(@value{GDBP}) thread 2 2246[Switching to process 35 thread 23] 22470x34e5 in sigpause () 2248@end smallexample 2249 2250@noindent 2251As with the @samp{[New @dots{}]} message, the form of the text after 2252@samp{Switching to} depends on your system's conventions for identifying 2253threads. 2254 2255@item thread apply [@var{threadno}] [@var{all}] @var{args} 2256The @code{thread apply} command allows you to apply a command to one or 2257more threads. Specify the numbers of the threads that you want affected 2258with the command argument @var{threadno}. @var{threadno} is the internal 2259@value{GDBN} thread number, as shown in the first field of the @samp{info 2260threads} display. To apply a command to all threads, use 2261@code{thread apply all} @var{args}. 2262@end table 2263 2264@cindex automatic thread selection 2265@cindex switching threads automatically 2266@cindex threads, automatic switching 2267Whenever @value{GDBN} stops your program, due to a breakpoint or a 2268signal, it automatically selects the thread where that breakpoint or 2269signal happened. @value{GDBN} alerts you to the context switch with a 2270message of the form @samp{[Switching to @var{systag}]} to identify the 2271thread. 2272 2273@xref{Thread Stops,,Stopping and starting multi-thread programs}, for 2274more information about how @value{GDBN} behaves when you stop and start 2275programs with multiple threads. 2276 2277@xref{Set Watchpoints,,Setting watchpoints}, for information about 2278watchpoints in programs with multiple threads. 2279 2280@node Processes 2281@section Debugging programs with multiple processes 2282 2283@cindex fork, debugging programs which call 2284@cindex multiple processes 2285@cindex processes, multiple 2286On most systems, @value{GDBN} has no special support for debugging 2287programs which create additional processes using the @code{fork} 2288function. When a program forks, @value{GDBN} will continue to debug the 2289parent process and the child process will run unimpeded. If you have 2290set a breakpoint in any code which the child then executes, the child 2291will get a @code{SIGTRAP} signal which (unless it catches the signal) 2292will cause it to terminate. 2293 2294However, if you want to debug the child process there is a workaround 2295which isn't too painful. Put a call to @code{sleep} in the code which 2296the child process executes after the fork. It may be useful to sleep 2297only if a certain environment variable is set, or a certain file exists, 2298so that the delay need not occur when you don't want to run @value{GDBN} 2299on the child. While the child is sleeping, use the @code{ps} program to 2300get its process ID. Then tell @value{GDBN} (a new invocation of 2301@value{GDBN} if you are also debugging the parent process) to attach to 2302the child process (@pxref{Attach}). From that point on you can debug 2303the child process just like any other process which you attached to. 2304 2305On some systems, @value{GDBN} provides support for debugging programs that 2306create additional processes using the @code{fork} or @code{vfork} functions. 2307Currently, the only platforms with this feature are HP-UX (11.x and later 2308only?) and GNU/Linux (kernel version 2.5.60 and later). 2309 2310By default, when a program forks, @value{GDBN} will continue to debug 2311the parent process and the child process will run unimpeded. 2312 2313If you want to follow the child process instead of the parent process, 2314use the command @w{@code{set follow-fork-mode}}. 2315 2316@table @code 2317@kindex set follow-fork-mode 2318@item set follow-fork-mode @var{mode} 2319Set the debugger response to a program call of @code{fork} or 2320@code{vfork}. A call to @code{fork} or @code{vfork} creates a new 2321process. The @var{mode} can be: 2322 2323@table @code 2324@item parent 2325The original process is debugged after a fork. The child process runs 2326unimpeded. This is the default. 2327 2328@item child 2329The new process is debugged after a fork. The parent process runs 2330unimpeded. 2331 2332@end table 2333 2334@item show follow-fork-mode 2335Display the current debugger response to a @code{fork} or @code{vfork} call. 2336@end table 2337 2338If you ask to debug a child process and a @code{vfork} is followed by an 2339@code{exec}, @value{GDBN} executes the new target up to the first 2340breakpoint in the new target. If you have a breakpoint set on 2341@code{main} in your original program, the breakpoint will also be set on 2342the child process's @code{main}. 2343 2344When a child process is spawned by @code{vfork}, you cannot debug the 2345child or parent until an @code{exec} call completes. 2346 2347If you issue a @code{run} command to @value{GDBN} after an @code{exec} 2348call executes, the new target restarts. To restart the parent process, 2349use the @code{file} command with the parent executable name as its 2350argument. 2351 2352You can use the @code{catch} command to make @value{GDBN} stop whenever 2353a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set 2354Catchpoints, ,Setting catchpoints}. 2355 2356@node Stopping 2357@chapter Stopping and Continuing 2358 2359The principal purposes of using a debugger are so that you can stop your 2360program before it terminates; or so that, if your program runs into 2361trouble, you can investigate and find out why. 2362 2363Inside @value{GDBN}, your program may stop for any of several reasons, 2364such as a signal, a breakpoint, or reaching a new line after a 2365@value{GDBN} command such as @code{step}. You may then examine and 2366change variables, set new breakpoints or remove old ones, and then 2367continue execution. Usually, the messages shown by @value{GDBN} provide 2368ample explanation of the status of your program---but you can also 2369explicitly request this information at any time. 2370 2371@table @code 2372@kindex info program 2373@item info program 2374Display information about the status of your program: whether it is 2375running or not, what process it is, and why it stopped. 2376@end table 2377 2378@menu 2379* Breakpoints:: Breakpoints, watchpoints, and catchpoints 2380* Continuing and Stepping:: Resuming execution 2381* Signals:: Signals 2382* Thread Stops:: Stopping and starting multi-thread programs 2383@end menu 2384 2385@node Breakpoints 2386@section Breakpoints, watchpoints, and catchpoints 2387 2388@cindex breakpoints 2389A @dfn{breakpoint} makes your program stop whenever a certain point in 2390the program is reached. For each breakpoint, you can add conditions to 2391control in finer detail whether your program stops. You can set 2392breakpoints with the @code{break} command and its variants (@pxref{Set 2393Breaks, ,Setting breakpoints}), to specify the place where your program 2394should stop by line number, function name or exact address in the 2395program. 2396 2397In HP-UX, SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can set 2398breakpoints in shared libraries before the executable is run. There is 2399a minor limitation on HP-UX systems: you must wait until the executable 2400is run in order to set breakpoints in shared library routines that are 2401not called directly by the program (for example, routines that are 2402arguments in a @code{pthread_create} call). 2403 2404@cindex watchpoints 2405@cindex memory tracing 2406@cindex breakpoint on memory address 2407@cindex breakpoint on variable modification 2408A @dfn{watchpoint} is a special breakpoint that stops your program 2409when the value of an expression changes. You must use a different 2410command to set watchpoints (@pxref{Set Watchpoints, ,Setting 2411watchpoints}), but aside from that, you can manage a watchpoint like 2412any other breakpoint: you enable, disable, and delete both breakpoints 2413and watchpoints using the same commands. 2414 2415You can arrange to have values from your program displayed automatically 2416whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,, 2417Automatic display}. 2418 2419@cindex catchpoints 2420@cindex breakpoint on events 2421A @dfn{catchpoint} is another special breakpoint that stops your program 2422when a certain kind of event occurs, such as the throwing of a C@t{++} 2423exception or the loading of a library. As with watchpoints, you use a 2424different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting 2425catchpoints}), but aside from that, you can manage a catchpoint like any 2426other breakpoint. (To stop when your program receives a signal, use the 2427@code{handle} command; see @ref{Signals, ,Signals}.) 2428 2429@cindex breakpoint numbers 2430@cindex numbers for breakpoints 2431@value{GDBN} assigns a number to each breakpoint, watchpoint, or 2432catchpoint when you create it; these numbers are successive integers 2433starting with one. In many of the commands for controlling various 2434features of breakpoints you use the breakpoint number to say which 2435breakpoint you want to change. Each breakpoint may be @dfn{enabled} or 2436@dfn{disabled}; if disabled, it has no effect on your program until you 2437enable it again. 2438 2439@cindex breakpoint ranges 2440@cindex ranges of breakpoints 2441Some @value{GDBN} commands accept a range of breakpoints on which to 2442operate. A breakpoint range is either a single breakpoint number, like 2443@samp{5}, or two such numbers, in increasing order, separated by a 2444hyphen, like @samp{5-7}. When a breakpoint range is given to a command, 2445all breakpoint in that range are operated on. 2446 2447@menu 2448* Set Breaks:: Setting breakpoints 2449* Set Watchpoints:: Setting watchpoints 2450* Set Catchpoints:: Setting catchpoints 2451* Delete Breaks:: Deleting breakpoints 2452* Disabling:: Disabling breakpoints 2453* Conditions:: Break conditions 2454* Break Commands:: Breakpoint command lists 2455* Breakpoint Menus:: Breakpoint menus 2456* Error in Breakpoints:: ``Cannot insert breakpoints'' 2457* Breakpoint related warnings:: ``Breakpoint address adjusted...'' 2458@end menu 2459 2460@node Set Breaks 2461@subsection Setting breakpoints 2462 2463@c FIXME LMB what does GDB do if no code on line of breakpt? 2464@c consider in particular declaration with/without initialization. 2465@c 2466@c FIXME 2 is there stuff on this already? break at fun start, already init? 2467 2468@kindex break 2469@kindex b @r{(@code{break})} 2470@vindex $bpnum@r{, convenience variable} 2471@cindex latest breakpoint 2472Breakpoints are set with the @code{break} command (abbreviated 2473@code{b}). The debugger convenience variable @samp{$bpnum} records the 2474number of the breakpoint you've set most recently; see @ref{Convenience 2475Vars,, Convenience variables}, for a discussion of what you can do with 2476convenience variables. 2477 2478You have several ways to say where the breakpoint should go. 2479 2480@table @code 2481@item break @var{function} 2482Set a breakpoint at entry to function @var{function}. 2483When using source languages that permit overloading of symbols, such as 2484C@t{++}, @var{function} may refer to more than one possible place to break. 2485@xref{Breakpoint Menus,,Breakpoint menus}, for a discussion of that situation. 2486 2487@item break +@var{offset} 2488@itemx break -@var{offset} 2489Set a breakpoint some number of lines forward or back from the position 2490at which execution stopped in the currently selected @dfn{stack frame}. 2491(@xref{Frames, ,Frames}, for a description of stack frames.) 2492 2493@item break @var{linenum} 2494Set a breakpoint at line @var{linenum} in the current source file. 2495The current source file is the last file whose source text was printed. 2496The breakpoint will stop your program just before it executes any of the 2497code on that line. 2498 2499@item break @var{filename}:@var{linenum} 2500Set a breakpoint at line @var{linenum} in source file @var{filename}. 2501 2502@item break @var{filename}:@var{function} 2503Set a breakpoint at entry to function @var{function} found in file 2504@var{filename}. Specifying a file name as well as a function name is 2505superfluous except when multiple files contain similarly named 2506functions. 2507 2508@item break *@var{address} 2509Set a breakpoint at address @var{address}. You can use this to set 2510breakpoints in parts of your program which do not have debugging 2511information or source files. 2512 2513@item break 2514When called without any arguments, @code{break} sets a breakpoint at 2515the next instruction to be executed in the selected stack frame 2516(@pxref{Stack, ,Examining the Stack}). In any selected frame but the 2517innermost, this makes your program stop as soon as control 2518returns to that frame. This is similar to the effect of a 2519@code{finish} command in the frame inside the selected frame---except 2520that @code{finish} does not leave an active breakpoint. If you use 2521@code{break} without an argument in the innermost frame, @value{GDBN} stops 2522the next time it reaches the current location; this may be useful 2523inside loops. 2524 2525@value{GDBN} normally ignores breakpoints when it resumes execution, until at 2526least one instruction has been executed. If it did not do this, you 2527would be unable to proceed past a breakpoint without first disabling the 2528breakpoint. This rule applies whether or not the breakpoint already 2529existed when your program stopped. 2530 2531@item break @dots{} if @var{cond} 2532Set a breakpoint with condition @var{cond}; evaluate the expression 2533@var{cond} each time the breakpoint is reached, and stop only if the 2534value is nonzero---that is, if @var{cond} evaluates as true. 2535@samp{@dots{}} stands for one of the possible arguments described 2536above (or no argument) specifying where to break. @xref{Conditions, 2537,Break conditions}, for more information on breakpoint conditions. 2538 2539@kindex tbreak 2540@item tbreak @var{args} 2541Set a breakpoint enabled only for one stop. @var{args} are the 2542same as for the @code{break} command, and the breakpoint is set in the same 2543way, but the breakpoint is automatically deleted after the first time your 2544program stops there. @xref{Disabling, ,Disabling breakpoints}. 2545 2546@kindex hbreak 2547@item hbreak @var{args} 2548Set a hardware-assisted breakpoint. @var{args} are the same as for the 2549@code{break} command and the breakpoint is set in the same way, but the 2550breakpoint requires hardware support and some target hardware may not 2551have this support. The main purpose of this is EPROM/ROM code 2552debugging, so you can set a breakpoint at an instruction without 2553changing the instruction. This can be used with the new trap-generation 2554provided by SPARClite DSU and some x86-based targets. These targets 2555will generate traps when a program accesses some data or instruction 2556address that is assigned to the debug registers. However the hardware 2557breakpoint registers can take a limited number of breakpoints. For 2558example, on the DSU, only two data breakpoints can be set at a time, and 2559@value{GDBN} will reject this command if more than two are used. Delete 2560or disable unused hardware breakpoints before setting new ones 2561(@pxref{Disabling, ,Disabling}). @xref{Conditions, ,Break conditions}. 2562@xref{set remote hardware-breakpoint-limit}. 2563 2564 2565@kindex thbreak 2566@item thbreak @var{args} 2567Set a hardware-assisted breakpoint enabled only for one stop. @var{args} 2568are the same as for the @code{hbreak} command and the breakpoint is set in 2569the same way. However, like the @code{tbreak} command, 2570the breakpoint is automatically deleted after the 2571first time your program stops there. Also, like the @code{hbreak} 2572command, the breakpoint requires hardware support and some target hardware 2573may not have this support. @xref{Disabling, ,Disabling breakpoints}. 2574See also @ref{Conditions, ,Break conditions}. 2575 2576@kindex rbreak 2577@cindex regular expression 2578@item rbreak @var{regex} 2579Set breakpoints on all functions matching the regular expression 2580@var{regex}. This command sets an unconditional breakpoint on all 2581matches, printing a list of all breakpoints it set. Once these 2582breakpoints are set, they are treated just like the breakpoints set with 2583the @code{break} command. You can delete them, disable them, or make 2584them conditional the same way as any other breakpoint. 2585 2586The syntax of the regular expression is the standard one used with tools 2587like @file{grep}. Note that this is different from the syntax used by 2588shells, so for instance @code{foo*} matches all functions that include 2589an @code{fo} followed by zero or more @code{o}s. There is an implicit 2590@code{.*} leading and trailing the regular expression you supply, so to 2591match only functions that begin with @code{foo}, use @code{^foo}. 2592 2593@cindex non-member C@t{++} functions, set breakpoint in 2594When debugging C@t{++} programs, @code{rbreak} is useful for setting 2595breakpoints on overloaded functions that are not members of any special 2596classes. 2597 2598@cindex set breakpoints on all functions 2599The @code{rbreak} command can be used to set breakpoints in 2600@strong{all} the functions in a program, like this: 2601 2602@smallexample 2603(@value{GDBP}) rbreak . 2604@end smallexample 2605 2606@kindex info breakpoints 2607@cindex @code{$_} and @code{info breakpoints} 2608@item info breakpoints @r{[}@var{n}@r{]} 2609@itemx info break @r{[}@var{n}@r{]} 2610@itemx info watchpoints @r{[}@var{n}@r{]} 2611Print a table of all breakpoints, watchpoints, and catchpoints set and 2612not deleted, with the following columns for each breakpoint: 2613 2614@table @emph 2615@item Breakpoint Numbers 2616@item Type 2617Breakpoint, watchpoint, or catchpoint. 2618@item Disposition 2619Whether the breakpoint is marked to be disabled or deleted when hit. 2620@item Enabled or Disabled 2621Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints 2622that are not enabled. 2623@item Address 2624Where the breakpoint is in your program, as a memory address. If the 2625breakpoint is pending (see below for details) on a future load of a shared library, the address 2626will be listed as @samp{<PENDING>}. 2627@item What 2628Where the breakpoint is in the source for your program, as a file and 2629line number. For a pending breakpoint, the original string passed to 2630the breakpoint command will be listed as it cannot be resolved until 2631the appropriate shared library is loaded in the future. 2632@end table 2633 2634@noindent 2635If a breakpoint is conditional, @code{info break} shows the condition on 2636the line following the affected breakpoint; breakpoint commands, if any, 2637are listed after that. A pending breakpoint is allowed to have a condition 2638specified for it. The condition is not parsed for validity until a shared 2639library is loaded that allows the pending breakpoint to resolve to a 2640valid location. 2641 2642@noindent 2643@code{info break} with a breakpoint 2644number @var{n} as argument lists only that breakpoint. The 2645convenience variable @code{$_} and the default examining-address for 2646the @code{x} command are set to the address of the last breakpoint 2647listed (@pxref{Memory, ,Examining memory}). 2648 2649@noindent 2650@code{info break} displays a count of the number of times the breakpoint 2651has been hit. This is especially useful in conjunction with the 2652@code{ignore} command. You can ignore a large number of breakpoint 2653hits, look at the breakpoint info to see how many times the breakpoint 2654was hit, and then run again, ignoring one less than that number. This 2655will get you quickly to the last hit of that breakpoint. 2656@end table 2657 2658@value{GDBN} allows you to set any number of breakpoints at the same place in 2659your program. There is nothing silly or meaningless about this. When 2660the breakpoints are conditional, this is even useful 2661(@pxref{Conditions, ,Break conditions}). 2662 2663@cindex pending breakpoints 2664If a specified breakpoint location cannot be found, it may be due to the fact 2665that the location is in a shared library that is yet to be loaded. In such 2666a case, you may want @value{GDBN} to create a special breakpoint (known as 2667a @dfn{pending breakpoint}) that 2668attempts to resolve itself in the future when an appropriate shared library 2669gets loaded. 2670 2671Pending breakpoints are useful to set at the start of your 2672@value{GDBN} session for locations that you know will be dynamically loaded 2673later by the program being debugged. When shared libraries are loaded, 2674a check is made to see if the load resolves any pending breakpoint locations. 2675If a pending breakpoint location gets resolved, 2676a regular breakpoint is created and the original pending breakpoint is removed. 2677 2678@value{GDBN} provides some additional commands for controlling pending 2679breakpoint support: 2680 2681@kindex set breakpoint pending 2682@kindex show breakpoint pending 2683@table @code 2684@item set breakpoint pending auto 2685This is the default behavior. When @value{GDBN} cannot find the breakpoint 2686location, it queries you whether a pending breakpoint should be created. 2687 2688@item set breakpoint pending on 2689This indicates that an unrecognized breakpoint location should automatically 2690result in a pending breakpoint being created. 2691 2692@item set breakpoint pending off 2693This indicates that pending breakpoints are not to be created. Any 2694unrecognized breakpoint location results in an error. This setting does 2695not affect any pending breakpoints previously created. 2696 2697@item show breakpoint pending 2698Show the current behavior setting for creating pending breakpoints. 2699@end table 2700 2701@cindex operations allowed on pending breakpoints 2702Normal breakpoint operations apply to pending breakpoints as well. You may 2703specify a condition for a pending breakpoint and/or commands to run when the 2704breakpoint is reached. You can also enable or disable 2705the pending breakpoint. When you specify a condition for a pending breakpoint, 2706the parsing of the condition will be deferred until the point where the 2707pending breakpoint location is resolved. Disabling a pending breakpoint 2708tells @value{GDBN} to not attempt to resolve the breakpoint on any subsequent 2709shared library load. When a pending breakpoint is re-enabled, 2710@value{GDBN} checks to see if the location is already resolved. 2711This is done because any number of shared library loads could have 2712occurred since the time the breakpoint was disabled and one or more 2713of these loads could resolve the location. 2714 2715@cindex negative breakpoint numbers 2716@cindex internal @value{GDBN} breakpoints 2717@value{GDBN} itself sometimes sets breakpoints in your program for 2718special purposes, such as proper handling of @code{longjmp} (in C 2719programs). These internal breakpoints are assigned negative numbers, 2720starting with @code{-1}; @samp{info breakpoints} does not display them. 2721You can see these breakpoints with the @value{GDBN} maintenance command 2722@samp{maint info breakpoints} (@pxref{maint info breakpoints}). 2723 2724 2725@node Set Watchpoints 2726@subsection Setting watchpoints 2727 2728@cindex setting watchpoints 2729@cindex software watchpoints 2730@cindex hardware watchpoints 2731You can use a watchpoint to stop execution whenever the value of an 2732expression changes, without having to predict a particular place where 2733this may happen. 2734 2735Depending on your system, watchpoints may be implemented in software or 2736hardware. @value{GDBN} does software watchpointing by single-stepping your 2737program and testing the variable's value each time, which is hundreds of 2738times slower than normal execution. (But this may still be worth it, to 2739catch errors where you have no clue what part of your program is the 2740culprit.) 2741 2742On some systems, such as HP-UX, @sc{gnu}/Linux and some other x86-based targets, 2743@value{GDBN} includes support for 2744hardware watchpoints, which do not slow down the running of your 2745program. 2746 2747@table @code 2748@kindex watch 2749@item watch @var{expr} 2750Set a watchpoint for an expression. @value{GDBN} will break when @var{expr} 2751is written into by the program and its value changes. 2752 2753@kindex rwatch 2754@item rwatch @var{expr} 2755Set a watchpoint that will break when watch @var{expr} is read by the program. 2756 2757@kindex awatch 2758@item awatch @var{expr} 2759Set a watchpoint that will break when @var{expr} is either read or written into 2760by the program. 2761 2762@kindex info watchpoints 2763@item info watchpoints 2764This command prints a list of watchpoints, breakpoints, and catchpoints; 2765it is the same as @code{info break}. 2766@end table 2767 2768@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware 2769watchpoints execute very quickly, and the debugger reports a change in 2770value at the exact instruction where the change occurs. If @value{GDBN} 2771cannot set a hardware watchpoint, it sets a software watchpoint, which 2772executes more slowly and reports the change in value at the next 2773statement, not the instruction, after the change occurs. 2774 2775When you issue the @code{watch} command, @value{GDBN} reports 2776 2777@smallexample 2778Hardware watchpoint @var{num}: @var{expr} 2779@end smallexample 2780 2781@noindent 2782if it was able to set a hardware watchpoint. 2783 2784Currently, the @code{awatch} and @code{rwatch} commands can only set 2785hardware watchpoints, because accesses to data that don't change the 2786value of the watched expression cannot be detected without examining 2787every instruction as it is being executed, and @value{GDBN} does not do 2788that currently. If @value{GDBN} finds that it is unable to set a 2789hardware breakpoint with the @code{awatch} or @code{rwatch} command, it 2790will print a message like this: 2791 2792@smallexample 2793Expression cannot be implemented with read/access watchpoint. 2794@end smallexample 2795 2796Sometimes, @value{GDBN} cannot set a hardware watchpoint because the 2797data type of the watched expression is wider than what a hardware 2798watchpoint on the target machine can handle. For example, some systems 2799can only watch regions that are up to 4 bytes wide; on such systems you 2800cannot set hardware watchpoints for an expression that yields a 2801double-precision floating-point number (which is typically 8 bytes 2802wide). As a work-around, it might be possible to break the large region 2803into a series of smaller ones and watch them with separate watchpoints. 2804 2805If you set too many hardware watchpoints, @value{GDBN} might be unable 2806to insert all of them when you resume the execution of your program. 2807Since the precise number of active watchpoints is unknown until such 2808time as the program is about to be resumed, @value{GDBN} might not be 2809able to warn you about this when you set the watchpoints, and the 2810warning will be printed only when the program is resumed: 2811 2812@smallexample 2813Hardware watchpoint @var{num}: Could not insert watchpoint 2814@end smallexample 2815 2816@noindent 2817If this happens, delete or disable some of the watchpoints. 2818 2819The SPARClite DSU will generate traps when a program accesses some data 2820or instruction address that is assigned to the debug registers. For the 2821data addresses, DSU facilitates the @code{watch} command. However the 2822hardware breakpoint registers can only take two data watchpoints, and 2823both watchpoints must be the same kind. For example, you can set two 2824watchpoints with @code{watch} commands, two with @code{rwatch} commands, 2825@strong{or} two with @code{awatch} commands, but you cannot set one 2826watchpoint with one command and the other with a different command. 2827@value{GDBN} will reject the command if you try to mix watchpoints. 2828Delete or disable unused watchpoint commands before setting new ones. 2829 2830If you call a function interactively using @code{print} or @code{call}, 2831any watchpoints you have set will be inactive until @value{GDBN} reaches another 2832kind of breakpoint or the call completes. 2833 2834@value{GDBN} automatically deletes watchpoints that watch local 2835(automatic) variables, or expressions that involve such variables, when 2836they go out of scope, that is, when the execution leaves the block in 2837which these variables were defined. In particular, when the program 2838being debugged terminates, @emph{all} local variables go out of scope, 2839and so only watchpoints that watch global variables remain set. If you 2840rerun the program, you will need to set all such watchpoints again. One 2841way of doing that would be to set a code breakpoint at the entry to the 2842@code{main} function and when it breaks, set all the watchpoints. 2843 2844@quotation 2845@cindex watchpoints and threads 2846@cindex threads and watchpoints 2847@emph{Warning:} In multi-thread programs, watchpoints have only limited 2848usefulness. With the current watchpoint implementation, @value{GDBN} 2849can only watch the value of an expression @emph{in a single thread}. If 2850you are confident that the expression can only change due to the current 2851thread's activity (and if you are also confident that no other thread 2852can become current), then you can use watchpoints as usual. However, 2853@value{GDBN} may not notice when a non-current thread's activity changes 2854the expression. 2855 2856@c FIXME: this is almost identical to the previous paragraph. 2857@emph{HP-UX Warning:} In multi-thread programs, software watchpoints 2858have only limited usefulness. If @value{GDBN} creates a software 2859watchpoint, it can only watch the value of an expression @emph{in a 2860single thread}. If you are confident that the expression can only 2861change due to the current thread's activity (and if you are also 2862confident that no other thread can become current), then you can use 2863software watchpoints as usual. However, @value{GDBN} may not notice 2864when a non-current thread's activity changes the expression. (Hardware 2865watchpoints, in contrast, watch an expression in all threads.) 2866@end quotation 2867 2868@xref{set remote hardware-watchpoint-limit}. 2869 2870@node Set Catchpoints 2871@subsection Setting catchpoints 2872@cindex catchpoints, setting 2873@cindex exception handlers 2874@cindex event handling 2875 2876You can use @dfn{catchpoints} to cause the debugger to stop for certain 2877kinds of program events, such as C@t{++} exceptions or the loading of a 2878shared library. Use the @code{catch} command to set a catchpoint. 2879 2880@table @code 2881@kindex catch 2882@item catch @var{event} 2883Stop when @var{event} occurs. @var{event} can be any of the following: 2884@table @code 2885@item throw 2886@cindex stop on C@t{++} exceptions 2887The throwing of a C@t{++} exception. 2888 2889@item catch 2890The catching of a C@t{++} exception. 2891 2892@item exec 2893@cindex break on fork/exec 2894A call to @code{exec}. This is currently only available for HP-UX. 2895 2896@item fork 2897A call to @code{fork}. This is currently only available for HP-UX. 2898 2899@item vfork 2900A call to @code{vfork}. This is currently only available for HP-UX. 2901 2902@item load 2903@itemx load @var{libname} 2904@cindex break on load/unload of shared library 2905The dynamic loading of any shared library, or the loading of the library 2906@var{libname}. This is currently only available for HP-UX. 2907 2908@item unload 2909@itemx unload @var{libname} 2910The unloading of any dynamically loaded shared library, or the unloading 2911of the library @var{libname}. This is currently only available for HP-UX. 2912@end table 2913 2914@item tcatch @var{event} 2915Set a catchpoint that is enabled only for one stop. The catchpoint is 2916automatically deleted after the first time the event is caught. 2917 2918@end table 2919 2920Use the @code{info break} command to list the current catchpoints. 2921 2922There are currently some limitations to C@t{++} exception handling 2923(@code{catch throw} and @code{catch catch}) in @value{GDBN}: 2924 2925@itemize @bullet 2926@item 2927If you call a function interactively, @value{GDBN} normally returns 2928control to you when the function has finished executing. If the call 2929raises an exception, however, the call may bypass the mechanism that 2930returns control to you and cause your program either to abort or to 2931simply continue running until it hits a breakpoint, catches a signal 2932that @value{GDBN} is listening for, or exits. This is the case even if 2933you set a catchpoint for the exception; catchpoints on exceptions are 2934disabled within interactive calls. 2935 2936@item 2937You cannot raise an exception interactively. 2938 2939@item 2940You cannot install an exception handler interactively. 2941@end itemize 2942 2943@cindex raise exceptions 2944Sometimes @code{catch} is not the best way to debug exception handling: 2945if you need to know exactly where an exception is raised, it is better to 2946stop @emph{before} the exception handler is called, since that way you 2947can see the stack before any unwinding takes place. If you set a 2948breakpoint in an exception handler instead, it may not be easy to find 2949out where the exception was raised. 2950 2951To stop just before an exception handler is called, you need some 2952knowledge of the implementation. In the case of @sc{gnu} C@t{++}, exceptions are 2953raised by calling a library function named @code{__raise_exception} 2954which has the following ANSI C interface: 2955 2956@smallexample 2957 /* @var{addr} is where the exception identifier is stored. 2958 @var{id} is the exception identifier. */ 2959 void __raise_exception (void **addr, void *id); 2960@end smallexample 2961 2962@noindent 2963To make the debugger catch all exceptions before any stack 2964unwinding takes place, set a breakpoint on @code{__raise_exception} 2965(@pxref{Breakpoints, ,Breakpoints; watchpoints; and exceptions}). 2966 2967With a conditional breakpoint (@pxref{Conditions, ,Break conditions}) 2968that depends on the value of @var{id}, you can stop your program when 2969a specific exception is raised. You can use multiple conditional 2970breakpoints to stop your program when any of a number of exceptions are 2971raised. 2972 2973 2974@node Delete Breaks 2975@subsection Deleting breakpoints 2976 2977@cindex clearing breakpoints, watchpoints, catchpoints 2978@cindex deleting breakpoints, watchpoints, catchpoints 2979It is often necessary to eliminate a breakpoint, watchpoint, or 2980catchpoint once it has done its job and you no longer want your program 2981to stop there. This is called @dfn{deleting} the breakpoint. A 2982breakpoint that has been deleted no longer exists; it is forgotten. 2983 2984With the @code{clear} command you can delete breakpoints according to 2985where they are in your program. With the @code{delete} command you can 2986delete individual breakpoints, watchpoints, or catchpoints by specifying 2987their breakpoint numbers. 2988 2989It is not necessary to delete a breakpoint to proceed past it. @value{GDBN} 2990automatically ignores breakpoints on the first instruction to be executed 2991when you continue execution without changing the execution address. 2992 2993@table @code 2994@kindex clear 2995@item clear 2996Delete any breakpoints at the next instruction to be executed in the 2997selected stack frame (@pxref{Selection, ,Selecting a frame}). When 2998the innermost frame is selected, this is a good way to delete a 2999breakpoint where your program just stopped. 3000 3001@item clear @var{function} 3002@itemx clear @var{filename}:@var{function} 3003Delete any breakpoints set at entry to the function @var{function}. 3004 3005@item clear @var{linenum} 3006@itemx clear @var{filename}:@var{linenum} 3007Delete any breakpoints set at or within the code of the specified line. 3008 3009@cindex delete breakpoints 3010@kindex delete 3011@kindex d @r{(@code{delete})} 3012@item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} 3013Delete the breakpoints, watchpoints, or catchpoints of the breakpoint 3014ranges specified as arguments. If no argument is specified, delete all 3015breakpoints (@value{GDBN} asks confirmation, unless you have @code{set 3016confirm off}). You can abbreviate this command as @code{d}. 3017@end table 3018 3019@node Disabling 3020@subsection Disabling breakpoints 3021 3022@cindex enable/disable a breakpoint 3023Rather than deleting a breakpoint, watchpoint, or catchpoint, you might 3024prefer to @dfn{disable} it. This makes the breakpoint inoperative as if 3025it had been deleted, but remembers the information on the breakpoint so 3026that you can @dfn{enable} it again later. 3027 3028You disable and enable breakpoints, watchpoints, and catchpoints with 3029the @code{enable} and @code{disable} commands, optionally specifying one 3030or more breakpoint numbers as arguments. Use @code{info break} or 3031@code{info watch} to print a list of breakpoints, watchpoints, and 3032catchpoints if you do not know which numbers to use. 3033 3034A breakpoint, watchpoint, or catchpoint can have any of four different 3035states of enablement: 3036 3037@itemize @bullet 3038@item 3039Enabled. The breakpoint stops your program. A breakpoint set 3040with the @code{break} command starts out in this state. 3041@item 3042Disabled. The breakpoint has no effect on your program. 3043@item 3044Enabled once. The breakpoint stops your program, but then becomes 3045disabled. 3046@item 3047Enabled for deletion. The breakpoint stops your program, but 3048immediately after it does so it is deleted permanently. A breakpoint 3049set with the @code{tbreak} command starts out in this state. 3050@end itemize 3051 3052You can use the following commands to enable or disable breakpoints, 3053watchpoints, and catchpoints: 3054 3055@table @code 3056@kindex disable 3057@kindex dis @r{(@code{disable})} 3058@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} 3059Disable the specified breakpoints---or all breakpoints, if none are 3060listed. A disabled breakpoint has no effect but is not forgotten. All 3061options such as ignore-counts, conditions and commands are remembered in 3062case the breakpoint is enabled again later. You may abbreviate 3063@code{disable} as @code{dis}. 3064 3065@kindex enable 3066@item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} 3067Enable the specified breakpoints (or all defined breakpoints). They 3068become effective once again in stopping your program. 3069 3070@item enable @r{[}breakpoints@r{]} once @var{range}@dots{} 3071Enable the specified breakpoints temporarily. @value{GDBN} disables any 3072of these breakpoints immediately after stopping your program. 3073 3074@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{} 3075Enable the specified breakpoints to work once, then die. @value{GDBN} 3076deletes any of these breakpoints as soon as your program stops there. 3077@end table 3078 3079@c FIXME: I think the following ``Except for [...] @code{tbreak}'' is 3080@c confusing: tbreak is also initially enabled. 3081Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks, 3082,Setting breakpoints}), breakpoints that you set are initially enabled; 3083subsequently, they become disabled or enabled only when you use one of 3084the commands above. (The command @code{until} can set and delete a 3085breakpoint of its own, but it does not change the state of your other 3086breakpoints; see @ref{Continuing and Stepping, ,Continuing and 3087stepping}.) 3088 3089@node Conditions 3090@subsection Break conditions 3091@cindex conditional breakpoints 3092@cindex breakpoint conditions 3093 3094@c FIXME what is scope of break condition expr? Context where wanted? 3095@c in particular for a watchpoint? 3096The simplest sort of breakpoint breaks every time your program reaches a 3097specified place. You can also specify a @dfn{condition} for a 3098breakpoint. A condition is just a Boolean expression in your 3099programming language (@pxref{Expressions, ,Expressions}). A breakpoint with 3100a condition evaluates the expression each time your program reaches it, 3101and your program stops only if the condition is @emph{true}. 3102 3103This is the converse of using assertions for program validation; in that 3104situation, you want to stop when the assertion is violated---that is, 3105when the condition is false. In C, if you want to test an assertion expressed 3106by the condition @var{assert}, you should set the condition 3107@samp{! @var{assert}} on the appropriate breakpoint. 3108 3109Conditions are also accepted for watchpoints; you may not need them, 3110since a watchpoint is inspecting the value of an expression anyhow---but 3111it might be simpler, say, to just set a watchpoint on a variable name, 3112and specify a condition that tests whether the new value is an interesting 3113one. 3114 3115Break conditions can have side effects, and may even call functions in 3116your program. This can be useful, for example, to activate functions 3117that log program progress, or to use your own print functions to 3118format special data structures. The effects are completely predictable 3119unless there is another enabled breakpoint at the same address. (In 3120that case, @value{GDBN} might see the other breakpoint first and stop your 3121program without checking the condition of this one.) Note that 3122breakpoint commands are usually more convenient and flexible than break 3123conditions for the 3124purpose of performing side effects when a breakpoint is reached 3125(@pxref{Break Commands, ,Breakpoint command lists}). 3126 3127Break conditions can be specified when a breakpoint is set, by using 3128@samp{if} in the arguments to the @code{break} command. @xref{Set 3129Breaks, ,Setting breakpoints}. They can also be changed at any time 3130with the @code{condition} command. 3131 3132You can also use the @code{if} keyword with the @code{watch} command. 3133The @code{catch} command does not recognize the @code{if} keyword; 3134@code{condition} is the only way to impose a further condition on a 3135catchpoint. 3136 3137@table @code 3138@kindex condition 3139@item condition @var{bnum} @var{expression} 3140Specify @var{expression} as the break condition for breakpoint, 3141watchpoint, or catchpoint number @var{bnum}. After you set a condition, 3142breakpoint @var{bnum} stops your program only if the value of 3143@var{expression} is true (nonzero, in C). When you use 3144@code{condition}, @value{GDBN} checks @var{expression} immediately for 3145syntactic correctness, and to determine whether symbols in it have 3146referents in the context of your breakpoint. If @var{expression} uses 3147symbols not referenced in the context of the breakpoint, @value{GDBN} 3148prints an error message: 3149 3150@smallexample 3151No symbol "foo" in current context. 3152@end smallexample 3153 3154@noindent 3155@value{GDBN} does 3156not actually evaluate @var{expression} at the time the @code{condition} 3157command (or a command that sets a breakpoint with a condition, like 3158@code{break if @dots{}}) is given, however. @xref{Expressions, ,Expressions}. 3159 3160@item condition @var{bnum} 3161Remove the condition from breakpoint number @var{bnum}. It becomes 3162an ordinary unconditional breakpoint. 3163@end table 3164 3165@cindex ignore count (of breakpoint) 3166A special case of a breakpoint condition is to stop only when the 3167breakpoint has been reached a certain number of times. This is so 3168useful that there is a special way to do it, using the @dfn{ignore 3169count} of the breakpoint. Every breakpoint has an ignore count, which 3170is an integer. Most of the time, the ignore count is zero, and 3171therefore has no effect. But if your program reaches a breakpoint whose 3172ignore count is positive, then instead of stopping, it just decrements 3173the ignore count by one and continues. As a result, if the ignore count 3174value is @var{n}, the breakpoint does not stop the next @var{n} times 3175your program reaches it. 3176 3177@table @code 3178@kindex ignore 3179@item ignore @var{bnum} @var{count} 3180Set the ignore count of breakpoint number @var{bnum} to @var{count}. 3181The next @var{count} times the breakpoint is reached, your program's 3182execution does not stop; other than to decrement the ignore count, @value{GDBN} 3183takes no action. 3184 3185To make the breakpoint stop the next time it is reached, specify 3186a count of zero. 3187 3188When you use @code{continue} to resume execution of your program from a 3189breakpoint, you can specify an ignore count directly as an argument to 3190@code{continue}, rather than using @code{ignore}. @xref{Continuing and 3191Stepping,,Continuing and stepping}. 3192 3193If a breakpoint has a positive ignore count and a condition, the 3194condition is not checked. Once the ignore count reaches zero, 3195@value{GDBN} resumes checking the condition. 3196 3197You could achieve the effect of the ignore count with a condition such 3198as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that 3199is decremented each time. @xref{Convenience Vars, ,Convenience 3200variables}. 3201@end table 3202 3203Ignore counts apply to breakpoints, watchpoints, and catchpoints. 3204 3205 3206@node Break Commands 3207@subsection Breakpoint command lists 3208 3209@cindex breakpoint commands 3210You can give any breakpoint (or watchpoint or catchpoint) a series of 3211commands to execute when your program stops due to that breakpoint. For 3212example, you might want to print the values of certain expressions, or 3213enable other breakpoints. 3214 3215@table @code 3216@kindex commands 3217@kindex end 3218@item commands @r{[}@var{bnum}@r{]} 3219@itemx @dots{} @var{command-list} @dots{} 3220@itemx end 3221Specify a list of commands for breakpoint number @var{bnum}. The commands 3222themselves appear on the following lines. Type a line containing just 3223@code{end} to terminate the commands. 3224 3225To remove all commands from a breakpoint, type @code{commands} and 3226follow it immediately with @code{end}; that is, give no commands. 3227 3228With no @var{bnum} argument, @code{commands} refers to the last 3229breakpoint, watchpoint, or catchpoint set (not to the breakpoint most 3230recently encountered). 3231@end table 3232 3233Pressing @key{RET} as a means of repeating the last @value{GDBN} command is 3234disabled within a @var{command-list}. 3235 3236You can use breakpoint commands to start your program up again. Simply 3237use the @code{continue} command, or @code{step}, or any other command 3238that resumes execution. 3239 3240Any other commands in the command list, after a command that resumes 3241execution, are ignored. This is because any time you resume execution 3242(even with a simple @code{next} or @code{step}), you may encounter 3243another breakpoint---which could have its own command list, leading to 3244ambiguities about which list to execute. 3245 3246@kindex silent 3247If the first command you specify in a command list is @code{silent}, the 3248usual message about stopping at a breakpoint is not printed. This may 3249be desirable for breakpoints that are to print a specific message and 3250then continue. If none of the remaining commands print anything, you 3251see no sign that the breakpoint was reached. @code{silent} is 3252meaningful only at the beginning of a breakpoint command list. 3253 3254The commands @code{echo}, @code{output}, and @code{printf} allow you to 3255print precisely controlled output, and are often useful in silent 3256breakpoints. @xref{Output, ,Commands for controlled output}. 3257 3258For example, here is how you could use breakpoint commands to print the 3259value of @code{x} at entry to @code{foo} whenever @code{x} is positive. 3260 3261@smallexample 3262break foo if x>0 3263commands 3264silent 3265printf "x is %d\n",x 3266cont 3267end 3268@end smallexample 3269 3270One application for breakpoint commands is to compensate for one bug so 3271you can test for another. Put a breakpoint just after the erroneous line 3272of code, give it a condition to detect the case in which something 3273erroneous has been done, and give it commands to assign correct values 3274to any variables that need them. End with the @code{continue} command 3275so that your program does not stop, and start with the @code{silent} 3276command so that no output is produced. Here is an example: 3277 3278@smallexample 3279break 403 3280commands 3281silent 3282set x = y + 4 3283cont 3284end 3285@end smallexample 3286 3287@node Breakpoint Menus 3288@subsection Breakpoint menus 3289@cindex overloading 3290@cindex symbol overloading 3291 3292Some programming languages (notably C@t{++} and Objective-C) permit a 3293single function name 3294to be defined several times, for application in different contexts. 3295This is called @dfn{overloading}. When a function name is overloaded, 3296@samp{break @var{function}} is not enough to tell @value{GDBN} where you want 3297a breakpoint. If you realize this is a problem, you can use 3298something like @samp{break @var{function}(@var{types})} to specify which 3299particular version of the function you want. Otherwise, @value{GDBN} offers 3300you a menu of numbered choices for different possible breakpoints, and 3301waits for your selection with the prompt @samp{>}. The first two 3302options are always @samp{[0] cancel} and @samp{[1] all}. Typing @kbd{1} 3303sets a breakpoint at each definition of @var{function}, and typing 3304@kbd{0} aborts the @code{break} command without setting any new 3305breakpoints. 3306 3307For example, the following session excerpt shows an attempt to set a 3308breakpoint at the overloaded symbol @code{String::after}. 3309We choose three particular definitions of that function name: 3310 3311@c FIXME! This is likely to change to show arg type lists, at least 3312@smallexample 3313@group 3314(@value{GDBP}) b String::after 3315[0] cancel 3316[1] all 3317[2] file:String.cc; line number:867 3318[3] file:String.cc; line number:860 3319[4] file:String.cc; line number:875 3320[5] file:String.cc; line number:853 3321[6] file:String.cc; line number:846 3322[7] file:String.cc; line number:735 3323> 2 4 6 3324Breakpoint 1 at 0xb26c: file String.cc, line 867. 3325Breakpoint 2 at 0xb344: file String.cc, line 875. 3326Breakpoint 3 at 0xafcc: file String.cc, line 846. 3327Multiple breakpoints were set. 3328Use the "delete" command to delete unwanted 3329 breakpoints. 3330(@value{GDBP}) 3331@end group 3332@end smallexample 3333 3334@c @ifclear BARETARGET 3335@node Error in Breakpoints 3336@subsection ``Cannot insert breakpoints'' 3337@c 3338@c FIXME!! 14/6/95 Is there a real example of this? Let's use it. 3339@c 3340Under some operating systems, breakpoints cannot be used in a program if 3341any other process is running that program. In this situation, 3342attempting to run or continue a program with a breakpoint causes 3343@value{GDBN} to print an error message: 3344 3345@smallexample 3346Cannot insert breakpoints. 3347The same program may be running in another process. 3348@end smallexample 3349 3350When this happens, you have three ways to proceed: 3351 3352@enumerate 3353@item 3354Remove or disable the breakpoints, then continue. 3355 3356@item 3357Suspend @value{GDBN}, and copy the file containing your program to a new 3358name. Resume @value{GDBN} and use the @code{exec-file} command to specify 3359that @value{GDBN} should run your program under that name. 3360Then start your program again. 3361 3362@item 3363Relink your program so that the text segment is nonsharable, using the 3364linker option @samp{-N}. The operating system limitation may not apply 3365to nonsharable executables. 3366@end enumerate 3367@c @end ifclear 3368 3369A similar message can be printed if you request too many active 3370hardware-assisted breakpoints and watchpoints: 3371 3372@c FIXME: the precise wording of this message may change; the relevant 3373@c source change is not committed yet (Sep 3, 1999). 3374@smallexample 3375Stopped; cannot insert breakpoints. 3376You may have requested too many hardware breakpoints and watchpoints. 3377@end smallexample 3378 3379@noindent 3380This message is printed when you attempt to resume the program, since 3381only then @value{GDBN} knows exactly how many hardware breakpoints and 3382watchpoints it needs to insert. 3383 3384When this message is printed, you need to disable or remove some of the 3385hardware-assisted breakpoints and watchpoints, and then continue. 3386 3387@node Breakpoint related warnings 3388@subsection ``Breakpoint address adjusted...'' 3389@cindex breakpoint address adjusted 3390 3391Some processor architectures place constraints on the addresses at 3392which breakpoints may be placed. For architectures thus constrained, 3393@value{GDBN} will attempt to adjust the breakpoint's address to comply 3394with the constraints dictated by the architecture. 3395 3396One example of such an architecture is the Fujitsu FR-V. The FR-V is 3397a VLIW architecture in which a number of RISC-like instructions may be 3398bundled together for parallel execution. The FR-V architecture 3399constrains the location of a breakpoint instruction within such a 3400bundle to the instruction with the lowest address. @value{GDBN} 3401honors this constraint by adjusting a breakpoint's address to the 3402first in the bundle. 3403 3404It is not uncommon for optimized code to have bundles which contain 3405instructions from different source statements, thus it may happen that 3406a breakpoint's address will be adjusted from one source statement to 3407another. Since this adjustment may significantly alter @value{GDBN}'s 3408breakpoint related behavior from what the user expects, a warning is 3409printed when the breakpoint is first set and also when the breakpoint 3410is hit. 3411 3412A warning like the one below is printed when setting a breakpoint 3413that's been subject to address adjustment: 3414 3415@smallexample 3416warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. 3417@end smallexample 3418 3419Such warnings are printed both for user settable and @value{GDBN}'s 3420internal breakpoints. If you see one of these warnings, you should 3421verify that a breakpoint set at the adjusted address will have the 3422desired affect. If not, the breakpoint in question may be removed and 3423other breakpoints may be set which will have the desired behavior. 3424E.g., it may be sufficient to place the breakpoint at a later 3425instruction. A conditional breakpoint may also be useful in some 3426cases to prevent the breakpoint from triggering too often. 3427 3428@value{GDBN} will also issue a warning when stopping at one of these 3429adjusted breakpoints: 3430 3431@smallexample 3432warning: Breakpoint 1 address previously adjusted from 0x00010414 3433to 0x00010410. 3434@end smallexample 3435 3436When this warning is encountered, it may be too late to take remedial 3437action except in cases where the breakpoint is hit earlier or more 3438frequently than expected. 3439 3440@node Continuing and Stepping 3441@section Continuing and stepping 3442 3443@cindex stepping 3444@cindex continuing 3445@cindex resuming execution 3446@dfn{Continuing} means resuming program execution until your program 3447completes normally. In contrast, @dfn{stepping} means executing just 3448one more ``step'' of your program, where ``step'' may mean either one 3449line of source code, or one machine instruction (depending on what 3450particular command you use). Either when continuing or when stepping, 3451your program may stop even sooner, due to a breakpoint or a signal. (If 3452it stops due to a signal, you may want to use @code{handle}, or use 3453@samp{signal 0} to resume execution. @xref{Signals, ,Signals}.) 3454 3455@table @code 3456@kindex continue 3457@kindex c @r{(@code{continue})} 3458@kindex fg @r{(resume foreground execution)} 3459@item continue @r{[}@var{ignore-count}@r{]} 3460@itemx c @r{[}@var{ignore-count}@r{]} 3461@itemx fg @r{[}@var{ignore-count}@r{]} 3462Resume program execution, at the address where your program last stopped; 3463any breakpoints set at that address are bypassed. The optional argument 3464@var{ignore-count} allows you to specify a further number of times to 3465ignore a breakpoint at this location; its effect is like that of 3466@code{ignore} (@pxref{Conditions, ,Break conditions}). 3467 3468The argument @var{ignore-count} is meaningful only when your program 3469stopped due to a breakpoint. At other times, the argument to 3470@code{continue} is ignored. 3471 3472The synonyms @code{c} and @code{fg} (for @dfn{foreground}, as the 3473debugged program is deemed to be the foreground program) are provided 3474purely for convenience, and have exactly the same behavior as 3475@code{continue}. 3476@end table 3477 3478To resume execution at a different place, you can use @code{return} 3479(@pxref{Returning, ,Returning from a function}) to go back to the 3480calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a 3481different address}) to go to an arbitrary location in your program. 3482 3483A typical technique for using stepping is to set a breakpoint 3484(@pxref{Breakpoints, ,Breakpoints; watchpoints; and catchpoints}) at the 3485beginning of the function or the section of your program where a problem 3486is believed to lie, run your program until it stops at that breakpoint, 3487and then step through the suspect area, examining the variables that are 3488interesting, until you see the problem happen. 3489 3490@table @code 3491@kindex step 3492@kindex s @r{(@code{step})} 3493@item step 3494Continue running your program until control reaches a different source 3495line, then stop it and return control to @value{GDBN}. This command is 3496abbreviated @code{s}. 3497 3498@quotation 3499@c "without debugging information" is imprecise; actually "without line 3500@c numbers in the debugging information". (gcc -g1 has debugging info but 3501@c not line numbers). But it seems complex to try to make that 3502@c distinction here. 3503@emph{Warning:} If you use the @code{step} command while control is 3504within a function that was compiled without debugging information, 3505execution proceeds until control reaches a function that does have 3506debugging information. Likewise, it will not step into a function which 3507is compiled without debugging information. To step through functions 3508without debugging information, use the @code{stepi} command, described 3509below. 3510@end quotation 3511 3512The @code{step} command only stops at the first instruction of a source 3513line. This prevents the multiple stops that could otherwise occur in 3514@code{switch} statements, @code{for} loops, etc. @code{step} continues 3515to stop if a function that has debugging information is called within 3516the line. In other words, @code{step} @emph{steps inside} any functions 3517called within the line. 3518 3519Also, the @code{step} command only enters a function if there is line 3520number information for the function. Otherwise it acts like the 3521@code{next} command. This avoids problems when using @code{cc -gl} 3522on MIPS machines. Previously, @code{step} entered subroutines if there 3523was any debugging information about the routine. 3524 3525@item step @var{count} 3526Continue running as in @code{step}, but do so @var{count} times. If a 3527breakpoint is reached, or a signal not related to stepping occurs before 3528@var{count} steps, stepping stops right away. 3529 3530@kindex next 3531@kindex n @r{(@code{next})} 3532@item next @r{[}@var{count}@r{]} 3533Continue to the next source line in the current (innermost) stack frame. 3534This is similar to @code{step}, but function calls that appear within 3535the line of code are executed without stopping. Execution stops when 3536control reaches a different line of code at the original stack level 3537that was executing when you gave the @code{next} command. This command 3538is abbreviated @code{n}. 3539 3540An argument @var{count} is a repeat count, as for @code{step}. 3541 3542 3543@c FIX ME!! Do we delete this, or is there a way it fits in with 3544@c the following paragraph? --- Vctoria 3545@c 3546@c @code{next} within a function that lacks debugging information acts like 3547@c @code{step}, but any function calls appearing within the code of the 3548@c function are executed without stopping. 3549 3550The @code{next} command only stops at the first instruction of a 3551source line. This prevents multiple stops that could otherwise occur in 3552@code{switch} statements, @code{for} loops, etc. 3553 3554@kindex set step-mode 3555@item set step-mode 3556@cindex functions without line info, and stepping 3557@cindex stepping into functions with no line info 3558@itemx set step-mode on 3559The @code{set step-mode on} command causes the @code{step} command to 3560stop at the first instruction of a function which contains no debug line 3561information rather than stepping over it. 3562 3563This is useful in cases where you may be interested in inspecting the 3564machine instructions of a function which has no symbolic info and do not 3565want @value{GDBN} to automatically skip over this function. 3566 3567@item set step-mode off 3568Causes the @code{step} command to step over any functions which contains no 3569debug information. This is the default. 3570 3571@kindex finish 3572@item finish 3573Continue running until just after function in the selected stack frame 3574returns. Print the returned value (if any). 3575 3576Contrast this with the @code{return} command (@pxref{Returning, 3577,Returning from a function}). 3578 3579@kindex until 3580@kindex u @r{(@code{until})} 3581@item until 3582@itemx u 3583Continue running until a source line past the current line, in the 3584current stack frame, is reached. This command is used to avoid single 3585stepping through a loop more than once. It is like the @code{next} 3586command, except that when @code{until} encounters a jump, it 3587automatically continues execution until the program counter is greater 3588than the address of the jump. 3589 3590This means that when you reach the end of a loop after single stepping 3591though it, @code{until} makes your program continue execution until it 3592exits the loop. In contrast, a @code{next} command at the end of a loop 3593simply steps back to the beginning of the loop, which forces you to step 3594through the next iteration. 3595 3596@code{until} always stops your program if it attempts to exit the current 3597stack frame. 3598 3599@code{until} may produce somewhat counterintuitive results if the order 3600of machine code does not match the order of the source lines. For 3601example, in the following excerpt from a debugging session, the @code{f} 3602(@code{frame}) command shows that execution is stopped at line 3603@code{206}; yet when we use @code{until}, we get to line @code{195}: 3604 3605@smallexample 3606(@value{GDBP}) f 3607#0 main (argc=4, argv=0xf7fffae8) at m4.c:206 3608206 expand_input(); 3609(@value{GDBP}) until 3610195 for ( ; argc > 0; NEXTARG) @{ 3611@end smallexample 3612 3613This happened because, for execution efficiency, the compiler had 3614generated code for the loop closure test at the end, rather than the 3615start, of the loop---even though the test in a C @code{for}-loop is 3616written before the body of the loop. The @code{until} command appeared 3617to step back to the beginning of the loop when it advanced to this 3618expression; however, it has not really gone to an earlier 3619statement---not in terms of the actual machine code. 3620 3621@code{until} with no argument works by means of single 3622instruction stepping, and hence is slower than @code{until} with an 3623argument. 3624 3625@item until @var{location} 3626@itemx u @var{location} 3627Continue running your program until either the specified location is 3628reached, or the current stack frame returns. @var{location} is any of 3629the forms of argument acceptable to @code{break} (@pxref{Set Breaks, 3630,Setting breakpoints}). This form of the command uses breakpoints, and 3631hence is quicker than @code{until} without an argument. The specified 3632location is actually reached only if it is in the current frame. This 3633implies that @code{until} can be used to skip over recursive function 3634invocations. For instance in the code below, if the current location is 3635line @code{96}, issuing @code{until 99} will execute the program up to 3636line @code{99} in the same invocation of factorial, i.e. after the inner 3637invocations have returned. 3638 3639@smallexample 364094 int factorial (int value) 364195 @{ 364296 if (value > 1) @{ 364397 value *= factorial (value - 1); 364498 @} 364599 return (value); 3646100 @} 3647@end smallexample 3648 3649 3650@kindex advance @var{location} 3651@itemx advance @var{location} 3652Continue running the program up to the given location. An argument is 3653required, anything of the same form as arguments for the @code{break} 3654command. Execution will also stop upon exit from the current stack 3655frame. This command is similar to @code{until}, but @code{advance} will 3656not skip over recursive function calls, and the target location doesn't 3657have to be in the same frame as the current one. 3658 3659 3660@kindex stepi 3661@kindex si @r{(@code{stepi})} 3662@item stepi 3663@itemx stepi @var{arg} 3664@itemx si 3665Execute one machine instruction, then stop and return to the debugger. 3666 3667It is often useful to do @samp{display/i $pc} when stepping by machine 3668instructions. This makes @value{GDBN} automatically display the next 3669instruction to be executed, each time your program stops. @xref{Auto 3670Display,, Automatic display}. 3671 3672An argument is a repeat count, as in @code{step}. 3673 3674@need 750 3675@kindex nexti 3676@kindex ni @r{(@code{nexti})} 3677@item nexti 3678@itemx nexti @var{arg} 3679@itemx ni 3680Execute one machine instruction, but if it is a function call, 3681proceed until the function returns. 3682 3683An argument is a repeat count, as in @code{next}. 3684@end table 3685 3686@node Signals 3687@section Signals 3688@cindex signals 3689 3690A signal is an asynchronous event that can happen in a program. The 3691operating system defines the possible kinds of signals, and gives each 3692kind a name and a number. For example, in Unix @code{SIGINT} is the 3693signal a program gets when you type an interrupt character (often @kbd{C-c}); 3694@code{SIGSEGV} is the signal a program gets from referencing a place in 3695memory far away from all the areas in use; @code{SIGALRM} occurs when 3696the alarm clock timer goes off (which happens only if your program has 3697requested an alarm). 3698 3699@cindex fatal signals 3700Some signals, including @code{SIGALRM}, are a normal part of the 3701functioning of your program. Others, such as @code{SIGSEGV}, indicate 3702errors; these signals are @dfn{fatal} (they kill your program immediately) if the 3703program has not specified in advance some other way to handle the signal. 3704@code{SIGINT} does not indicate an error in your program, but it is normally 3705fatal so it can carry out the purpose of the interrupt: to kill the program. 3706 3707@value{GDBN} has the ability to detect any occurrence of a signal in your 3708program. You can tell @value{GDBN} in advance what to do for each kind of 3709signal. 3710 3711@cindex handling signals 3712Normally, @value{GDBN} is set up to let the non-erroneous signals like 3713@code{SIGALRM} be silently passed to your program 3714(so as not to interfere with their role in the program's functioning) 3715but to stop your program immediately whenever an error signal happens. 3716You can change these settings with the @code{handle} command. 3717 3718@table @code 3719@kindex info signals 3720@item info signals 3721@itemx info handle 3722Print a table of all the kinds of signals and how @value{GDBN} has been told to 3723handle each one. You can use this to see the signal numbers of all 3724the defined types of signals. 3725 3726@code{info handle} is an alias for @code{info signals}. 3727 3728@kindex handle 3729@item handle @var{signal} @var{keywords}@dots{} 3730Change the way @value{GDBN} handles signal @var{signal}. @var{signal} 3731can be the number of a signal or its name (with or without the 3732@samp{SIG} at the beginning); a list of signal numbers of the form 3733@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the 3734known signals. The @var{keywords} say what change to make. 3735@end table 3736 3737@c @group 3738The keywords allowed by the @code{handle} command can be abbreviated. 3739Their full names are: 3740 3741@table @code 3742@item nostop 3743@value{GDBN} should not stop your program when this signal happens. It may 3744still print a message telling you that the signal has come in. 3745 3746@item stop 3747@value{GDBN} should stop your program when this signal happens. This implies 3748the @code{print} keyword as well. 3749 3750@item print 3751@value{GDBN} should print a message when this signal happens. 3752 3753@item noprint 3754@value{GDBN} should not mention the occurrence of the signal at all. This 3755implies the @code{nostop} keyword as well. 3756 3757@item pass 3758@itemx noignore 3759@value{GDBN} should allow your program to see this signal; your program 3760can handle the signal, or else it may terminate if the signal is fatal 3761and not handled. @code{pass} and @code{noignore} are synonyms. 3762 3763@item nopass 3764@itemx ignore 3765@value{GDBN} should not allow your program to see this signal. 3766@code{nopass} and @code{ignore} are synonyms. 3767@end table 3768@c @end group 3769 3770When a signal stops your program, the signal is not visible to the 3771program until you 3772continue. Your program sees the signal then, if @code{pass} is in 3773effect for the signal in question @emph{at that time}. In other words, 3774after @value{GDBN} reports a signal, you can use the @code{handle} 3775command with @code{pass} or @code{nopass} to control whether your 3776program sees that signal when you continue. 3777 3778The default is set to @code{nostop}, @code{noprint}, @code{pass} for 3779non-erroneous signals such as @code{SIGALRM}, @code{SIGWINCH} and 3780@code{SIGCHLD}, and to @code{stop}, @code{print}, @code{pass} for the 3781erroneous signals. 3782 3783You can also use the @code{signal} command to prevent your program from 3784seeing a signal, or cause it to see a signal it normally would not see, 3785or to give it any signal at any time. For example, if your program stopped 3786due to some sort of memory reference error, you might store correct 3787values into the erroneous variables and continue, hoping to see more 3788execution; but your program would probably terminate immediately as 3789a result of the fatal signal once it saw the signal. To prevent this, 3790you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your 3791program a signal}. 3792 3793@node Thread Stops 3794@section Stopping and starting multi-thread programs 3795 3796When your program has multiple threads (@pxref{Threads,, Debugging 3797programs with multiple threads}), you can choose whether to set 3798breakpoints on all threads, or on a particular thread. 3799 3800@table @code 3801@cindex breakpoints and threads 3802@cindex thread breakpoints 3803@kindex break @dots{} thread @var{threadno} 3804@item break @var{linespec} thread @var{threadno} 3805@itemx break @var{linespec} thread @var{threadno} if @dots{} 3806@var{linespec} specifies source lines; there are several ways of 3807writing them, but the effect is always to specify some source line. 3808 3809Use the qualifier @samp{thread @var{threadno}} with a breakpoint command 3810to specify that you only want @value{GDBN} to stop the program when a 3811particular thread reaches this breakpoint. @var{threadno} is one of the 3812numeric thread identifiers assigned by @value{GDBN}, shown in the first 3813column of the @samp{info threads} display. 3814 3815If you do not specify @samp{thread @var{threadno}} when you set a 3816breakpoint, the breakpoint applies to @emph{all} threads of your 3817program. 3818 3819You can use the @code{thread} qualifier on conditional breakpoints as 3820well; in this case, place @samp{thread @var{threadno}} before the 3821breakpoint condition, like this: 3822 3823@smallexample 3824(@value{GDBP}) break frik.c:13 thread 28 if bartab > lim 3825@end smallexample 3826 3827@end table 3828 3829@cindex stopped threads 3830@cindex threads, stopped 3831Whenever your program stops under @value{GDBN} for any reason, 3832@emph{all} threads of execution stop, not just the current thread. This 3833allows you to examine the overall state of the program, including 3834switching between threads, without worrying that things may change 3835underfoot. 3836 3837@cindex thread breakpoints and system calls 3838@cindex system calls and thread breakpoints 3839@cindex premature return from system calls 3840There is an unfortunate side effect. If one thread stops for a 3841breakpoint, or for some other reason, and another thread is blocked in a 3842system call, then the system call may return prematurely. This is a 3843consequence of the interaction between multiple threads and the signals 3844that @value{GDBN} uses to implement breakpoints and other events that 3845stop execution. 3846 3847To handle this problem, your program should check the return value of 3848each system call and react appropriately. This is good programming 3849style anyways. 3850 3851For example, do not write code like this: 3852 3853@smallexample 3854 sleep (10); 3855@end smallexample 3856 3857The call to @code{sleep} will return early if a different thread stops 3858at a breakpoint or for some other reason. 3859 3860Instead, write this: 3861 3862@smallexample 3863 int unslept = 10; 3864 while (unslept > 0) 3865 unslept = sleep (unslept); 3866@end smallexample 3867 3868A system call is allowed to return early, so the system is still 3869conforming to its specification. But @value{GDBN} does cause your 3870multi-threaded program to behave differently than it would without 3871@value{GDBN}. 3872 3873Also, @value{GDBN} uses internal breakpoints in the thread library to 3874monitor certain events such as thread creation and thread destruction. 3875When such an event happens, a system call in another thread may return 3876prematurely, even though your program does not appear to stop. 3877 3878@cindex continuing threads 3879@cindex threads, continuing 3880Conversely, whenever you restart the program, @emph{all} threads start 3881executing. @emph{This is true even when single-stepping} with commands 3882like @code{step} or @code{next}. 3883 3884In particular, @value{GDBN} cannot single-step all threads in lockstep. 3885Since thread scheduling is up to your debugging target's operating 3886system (not controlled by @value{GDBN}), other threads may 3887execute more than one statement while the current thread completes a 3888single step. Moreover, in general other threads stop in the middle of a 3889statement, rather than at a clean statement boundary, when the program 3890stops. 3891 3892You might even find your program stopped in another thread after 3893continuing or even single-stepping. This happens whenever some other 3894thread runs into a breakpoint, a signal, or an exception before the 3895first thread completes whatever you requested. 3896 3897On some OSes, you can lock the OS scheduler and thus allow only a single 3898thread to run. 3899 3900@table @code 3901@item set scheduler-locking @var{mode} 3902Set the scheduler locking mode. If it is @code{off}, then there is no 3903locking and any thread may run at any time. If @code{on}, then only the 3904current thread may run when the inferior is resumed. The @code{step} 3905mode optimizes for single-stepping. It stops other threads from 3906``seizing the prompt'' by preempting the current thread while you are 3907stepping. Other threads will only rarely (or never) get a chance to run 3908when you step. They are more likely to run when you @samp{next} over a 3909function call, and they are completely free to run when you use commands 3910like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another 3911thread hits a breakpoint during its timeslice, they will never steal the 3912@value{GDBN} prompt away from the thread that you are debugging. 3913 3914@item show scheduler-locking 3915Display the current scheduler locking mode. 3916@end table 3917 3918 3919@node Stack 3920@chapter Examining the Stack 3921 3922When your program has stopped, the first thing you need to know is where it 3923stopped and how it got there. 3924 3925@cindex call stack 3926Each time your program performs a function call, information about the call 3927is generated. 3928That information includes the location of the call in your program, 3929the arguments of the call, 3930and the local variables of the function being called. 3931The information is saved in a block of data called a @dfn{stack frame}. 3932The stack frames are allocated in a region of memory called the @dfn{call 3933stack}. 3934 3935When your program stops, the @value{GDBN} commands for examining the 3936stack allow you to see all of this information. 3937 3938@cindex selected frame 3939One of the stack frames is @dfn{selected} by @value{GDBN} and many 3940@value{GDBN} commands refer implicitly to the selected frame. In 3941particular, whenever you ask @value{GDBN} for the value of a variable in 3942your program, the value is found in the selected frame. There are 3943special @value{GDBN} commands to select whichever frame you are 3944interested in. @xref{Selection, ,Selecting a frame}. 3945 3946When your program stops, @value{GDBN} automatically selects the 3947currently executing frame and describes it briefly, similar to the 3948@code{frame} command (@pxref{Frame Info, ,Information about a frame}). 3949 3950@menu 3951* Frames:: Stack frames 3952* Backtrace:: Backtraces 3953* Selection:: Selecting a frame 3954* Frame Info:: Information on a frame 3955 3956@end menu 3957 3958@node Frames 3959@section Stack frames 3960 3961@cindex frame, definition 3962@cindex stack frame 3963The call stack is divided up into contiguous pieces called @dfn{stack 3964frames}, or @dfn{frames} for short; each frame is the data associated 3965with one call to one function. The frame contains the arguments given 3966to the function, the function's local variables, and the address at 3967which the function is executing. 3968 3969@cindex initial frame 3970@cindex outermost frame 3971@cindex innermost frame 3972When your program is started, the stack has only one frame, that of the 3973function @code{main}. This is called the @dfn{initial} frame or the 3974@dfn{outermost} frame. Each time a function is called, a new frame is 3975made. Each time a function returns, the frame for that function invocation 3976is eliminated. If a function is recursive, there can be many frames for 3977the same function. The frame for the function in which execution is 3978actually occurring is called the @dfn{innermost} frame. This is the most 3979recently created of all the stack frames that still exist. 3980 3981@cindex frame pointer 3982Inside your program, stack frames are identified by their addresses. A 3983stack frame consists of many bytes, each of which has its own address; each 3984kind of computer has a convention for choosing one byte whose 3985address serves as the address of the frame. Usually this address is kept 3986in a register called the @dfn{frame pointer register} while execution is 3987going on in that frame. 3988 3989@cindex frame number 3990@value{GDBN} assigns numbers to all existing stack frames, starting with 3991zero for the innermost frame, one for the frame that called it, 3992and so on upward. These numbers do not really exist in your program; 3993they are assigned by @value{GDBN} to give you a way of designating stack 3994frames in @value{GDBN} commands. 3995 3996@c The -fomit-frame-pointer below perennially causes hbox overflow 3997@c underflow problems. 3998@cindex frameless execution 3999Some compilers provide a way to compile functions so that they operate 4000without stack frames. (For example, the @value{GCC} option 4001@smallexample 4002@samp{-fomit-frame-pointer} 4003@end smallexample 4004generates functions without a frame.) 4005This is occasionally done with heavily used library functions to save 4006the frame setup time. @value{GDBN} has limited facilities for dealing 4007with these function invocations. If the innermost function invocation 4008has no stack frame, @value{GDBN} nevertheless regards it as though 4009it had a separate frame, which is numbered zero as usual, allowing 4010correct tracing of the function call chain. However, @value{GDBN} has 4011no provision for frameless functions elsewhere in the stack. 4012 4013@table @code 4014@kindex frame@r{, command} 4015@cindex current stack frame 4016@item frame @var{args} 4017The @code{frame} command allows you to move from one stack frame to another, 4018and to print the stack frame you select. @var{args} may be either the 4019address of the frame or the stack frame number. Without an argument, 4020@code{frame} prints the current stack frame. 4021 4022@kindex select-frame 4023@cindex selecting frame silently 4024@item select-frame 4025The @code{select-frame} command allows you to move from one stack frame 4026to another without printing the frame. This is the silent version of 4027@code{frame}. 4028@end table 4029 4030@node Backtrace 4031@section Backtraces 4032 4033@cindex backtraces 4034@cindex tracebacks 4035@cindex stack traces 4036A backtrace is a summary of how your program got where it is. It shows one 4037line per frame, for many frames, starting with the currently executing 4038frame (frame zero), followed by its caller (frame one), and on up the 4039stack. 4040 4041@table @code 4042@kindex backtrace 4043@kindex bt @r{(@code{backtrace})} 4044@item backtrace 4045@itemx bt 4046Print a backtrace of the entire stack: one line per frame for all 4047frames in the stack. 4048 4049You can stop the backtrace at any time by typing the system interrupt 4050character, normally @kbd{C-c}. 4051 4052@item backtrace @var{n} 4053@itemx bt @var{n} 4054Similar, but print only the innermost @var{n} frames. 4055 4056@item backtrace -@var{n} 4057@itemx bt -@var{n} 4058Similar, but print only the outermost @var{n} frames. 4059@end table 4060 4061@kindex where 4062@kindex info stack 4063The names @code{where} and @code{info stack} (abbreviated @code{info s}) 4064are additional aliases for @code{backtrace}. 4065 4066Each line in the backtrace shows the frame number and the function name. 4067The program counter value is also shown---unless you use @code{set 4068print address off}. The backtrace also shows the source file name and 4069line number, as well as the arguments to the function. The program 4070counter value is omitted if it is at the beginning of the code for that 4071line number. 4072 4073Here is an example of a backtrace. It was made with the command 4074@samp{bt 3}, so it shows the innermost three frames. 4075 4076@smallexample 4077@group 4078#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) 4079 at builtin.c:993 4080#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242 4081#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) 4082 at macro.c:71 4083(More stack frames follow...) 4084@end group 4085@end smallexample 4086 4087@noindent 4088The display for frame zero does not begin with a program counter 4089value, indicating that your program has stopped at the beginning of the 4090code for line @code{993} of @code{builtin.c}. 4091 4092Most programs have a standard user entry point---a place where system 4093libraries and startup code transition into user code. For C this is 4094@code{main}. When @value{GDBN} finds the entry function in a backtrace 4095it will terminate the backtrace, to avoid tracing into highly 4096system-specific (and generally uninteresting) code. 4097 4098If you need to examine the startup code, or limit the number of levels 4099in a backtrace, you can change this behavior: 4100 4101@table @code 4102@item set backtrace past-main 4103@itemx set backtrace past-main on 4104@kindex set backtrace 4105Backtraces will continue past the user entry point. 4106 4107@item set backtrace past-main off 4108Backtraces will stop when they encounter the user entry point. This is the 4109default. 4110 4111@item show backtrace past-main 4112@kindex show backtrace 4113Display the current user entry point backtrace policy. 4114 4115@item set backtrace limit @var{n} 4116@itemx set backtrace limit 0 4117@cindex backtrace limit 4118Limit the backtrace to @var{n} levels. A value of zero means 4119unlimited. 4120 4121@item show backtrace limit 4122Display the current limit on backtrace levels. 4123@end table 4124 4125@node Selection 4126@section Selecting a frame 4127 4128Most commands for examining the stack and other data in your program work on 4129whichever stack frame is selected at the moment. Here are the commands for 4130selecting a stack frame; all of them finish by printing a brief description 4131of the stack frame just selected. 4132 4133@table @code 4134@kindex frame@r{, selecting} 4135@kindex f @r{(@code{frame})} 4136@item frame @var{n} 4137@itemx f @var{n} 4138Select frame number @var{n}. Recall that frame zero is the innermost 4139(currently executing) frame, frame one is the frame that called the 4140innermost one, and so on. The highest-numbered frame is the one for 4141@code{main}. 4142 4143@item frame @var{addr} 4144@itemx f @var{addr} 4145Select the frame at address @var{addr}. This is useful mainly if the 4146chaining of stack frames has been damaged by a bug, making it 4147impossible for @value{GDBN} to assign numbers properly to all frames. In 4148addition, this can be useful when your program has multiple stacks and 4149switches between them. 4150 4151On the SPARC architecture, @code{frame} needs two addresses to 4152select an arbitrary frame: a frame pointer and a stack pointer. 4153 4154On the MIPS and Alpha architecture, it needs two addresses: a stack 4155pointer and a program counter. 4156 4157On the 29k architecture, it needs three addresses: a register stack 4158pointer, a program counter, and a memory stack pointer. 4159@c note to future updaters: this is conditioned on a flag 4160@c SETUP_ARBITRARY_FRAME in the tm-*.h files. The above is up to date 4161@c as of 27 Jan 1994. 4162 4163@kindex up 4164@item up @var{n} 4165Move @var{n} frames up the stack. For positive numbers @var{n}, this 4166advances toward the outermost frame, to higher frame numbers, to frames 4167that have existed longer. @var{n} defaults to one. 4168 4169@kindex down 4170@kindex do @r{(@code{down})} 4171@item down @var{n} 4172Move @var{n} frames down the stack. For positive numbers @var{n}, this 4173advances toward the innermost frame, to lower frame numbers, to frames 4174that were created more recently. @var{n} defaults to one. You may 4175abbreviate @code{down} as @code{do}. 4176@end table 4177 4178All of these commands end by printing two lines of output describing the 4179frame. The first line shows the frame number, the function name, the 4180arguments, and the source file and line number of execution in that 4181frame. The second line shows the text of that source line. 4182 4183@need 1000 4184For example: 4185 4186@smallexample 4187@group 4188(@value{GDBP}) up 4189#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) 4190 at env.c:10 419110 read_input_file (argv[i]); 4192@end group 4193@end smallexample 4194 4195After such a printout, the @code{list} command with no arguments 4196prints ten lines centered on the point of execution in the frame. 4197You can also edit the program at the point of execution with your favorite 4198editing program by typing @code{edit}. 4199@xref{List, ,Printing source lines}, 4200for details. 4201 4202@table @code 4203@kindex down-silently 4204@kindex up-silently 4205@item up-silently @var{n} 4206@itemx down-silently @var{n} 4207These two commands are variants of @code{up} and @code{down}, 4208respectively; they differ in that they do their work silently, without 4209causing display of the new frame. They are intended primarily for use 4210in @value{GDBN} command scripts, where the output might be unnecessary and 4211distracting. 4212@end table 4213 4214@node Frame Info 4215@section Information about a frame 4216 4217There are several other commands to print information about the selected 4218stack frame. 4219 4220@table @code 4221@item frame 4222@itemx f 4223When used without any argument, this command does not change which 4224frame is selected, but prints a brief description of the currently 4225selected stack frame. It can be abbreviated @code{f}. With an 4226argument, this command is used to select a stack frame. 4227@xref{Selection, ,Selecting a frame}. 4228 4229@kindex info frame 4230@kindex info f @r{(@code{info frame})} 4231@item info frame 4232@itemx info f 4233This command prints a verbose description of the selected stack frame, 4234including: 4235 4236@itemize @bullet 4237@item 4238the address of the frame 4239@item 4240the address of the next frame down (called by this frame) 4241@item 4242the address of the next frame up (caller of this frame) 4243@item 4244the language in which the source code corresponding to this frame is written 4245@item 4246the address of the frame's arguments 4247@item 4248the address of the frame's local variables 4249@item 4250the program counter saved in it (the address of execution in the caller frame) 4251@item 4252which registers were saved in the frame 4253@end itemize 4254 4255@noindent The verbose description is useful when 4256something has gone wrong that has made the stack format fail to fit 4257the usual conventions. 4258 4259@item info frame @var{addr} 4260@itemx info f @var{addr} 4261Print a verbose description of the frame at address @var{addr}, without 4262selecting that frame. The selected frame remains unchanged by this 4263command. This requires the same kind of address (more than one for some 4264architectures) that you specify in the @code{frame} command. 4265@xref{Selection, ,Selecting a frame}. 4266 4267@kindex info args 4268@item info args 4269Print the arguments of the selected frame, each on a separate line. 4270 4271@item info locals 4272@kindex info locals 4273Print the local variables of the selected frame, each on a separate 4274line. These are all variables (declared either static or automatic) 4275accessible at the point of execution of the selected frame. 4276 4277@kindex info catch 4278@cindex catch exceptions, list active handlers 4279@cindex exception handlers, how to list 4280@item info catch 4281Print a list of all the exception handlers that are active in the 4282current stack frame at the current point of execution. To see other 4283exception handlers, visit the associated frame (using the @code{up}, 4284@code{down}, or @code{frame} commands); then type @code{info catch}. 4285@xref{Set Catchpoints, , Setting catchpoints}. 4286 4287@end table 4288 4289 4290@node Source 4291@chapter Examining Source Files 4292 4293@value{GDBN} can print parts of your program's source, since the debugging 4294information recorded in the program tells @value{GDBN} what source files were 4295used to build it. When your program stops, @value{GDBN} spontaneously prints 4296the line where it stopped. Likewise, when you select a stack frame 4297(@pxref{Selection, ,Selecting a frame}), @value{GDBN} prints the line where 4298execution in that frame has stopped. You can print other portions of 4299source files by explicit command. 4300 4301If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may 4302prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using 4303@value{GDBN} under @sc{gnu} Emacs}. 4304 4305@menu 4306* List:: Printing source lines 4307* Edit:: Editing source files 4308* Search:: Searching source files 4309* Source Path:: Specifying source directories 4310* Machine Code:: Source and machine code 4311@end menu 4312 4313@node List 4314@section Printing source lines 4315 4316@kindex list 4317@kindex l @r{(@code{list})} 4318To print lines from a source file, use the @code{list} command 4319(abbreviated @code{l}). By default, ten lines are printed. 4320There are several ways to specify what part of the file you want to print. 4321 4322Here are the forms of the @code{list} command most commonly used: 4323 4324@table @code 4325@item list @var{linenum} 4326Print lines centered around line number @var{linenum} in the 4327current source file. 4328 4329@item list @var{function} 4330Print lines centered around the beginning of function 4331@var{function}. 4332 4333@item list 4334Print more lines. If the last lines printed were printed with a 4335@code{list} command, this prints lines following the last lines 4336printed; however, if the last line printed was a solitary line printed 4337as part of displaying a stack frame (@pxref{Stack, ,Examining the 4338Stack}), this prints lines centered around that line. 4339 4340@item list - 4341Print lines just before the lines last printed. 4342@end table 4343 4344By default, @value{GDBN} prints ten source lines with any of these forms of 4345the @code{list} command. You can change this using @code{set listsize}: 4346 4347@table @code 4348@kindex set listsize 4349@item set listsize @var{count} 4350Make the @code{list} command display @var{count} source lines (unless 4351the @code{list} argument explicitly specifies some other number). 4352 4353@kindex show listsize 4354@item show listsize 4355Display the number of lines that @code{list} prints. 4356@end table 4357 4358Repeating a @code{list} command with @key{RET} discards the argument, 4359so it is equivalent to typing just @code{list}. This is more useful 4360than listing the same lines again. An exception is made for an 4361argument of @samp{-}; that argument is preserved in repetition so that 4362each repetition moves up in the source file. 4363 4364@cindex linespec 4365In general, the @code{list} command expects you to supply zero, one or two 4366@dfn{linespecs}. Linespecs specify source lines; there are several ways 4367of writing them, but the effect is always to specify some source line. 4368Here is a complete description of the possible arguments for @code{list}: 4369 4370@table @code 4371@item list @var{linespec} 4372Print lines centered around the line specified by @var{linespec}. 4373 4374@item list @var{first},@var{last} 4375Print lines from @var{first} to @var{last}. Both arguments are 4376linespecs. 4377 4378@item list ,@var{last} 4379Print lines ending with @var{last}. 4380 4381@item list @var{first}, 4382Print lines starting with @var{first}. 4383 4384@item list + 4385Print lines just after the lines last printed. 4386 4387@item list - 4388Print lines just before the lines last printed. 4389 4390@item list 4391As described in the preceding table. 4392@end table 4393 4394Here are the ways of specifying a single source line---all the 4395kinds of linespec. 4396 4397@table @code 4398@item @var{number} 4399Specifies line @var{number} of the current source file. 4400When a @code{list} command has two linespecs, this refers to 4401the same source file as the first linespec. 4402 4403@item +@var{offset} 4404Specifies the line @var{offset} lines after the last line printed. 4405When used as the second linespec in a @code{list} command that has 4406two, this specifies the line @var{offset} lines down from the 4407first linespec. 4408 4409@item -@var{offset} 4410Specifies the line @var{offset} lines before the last line printed. 4411 4412@item @var{filename}:@var{number} 4413Specifies line @var{number} in the source file @var{filename}. 4414 4415@item @var{function} 4416Specifies the line that begins the body of the function @var{function}. 4417For example: in C, this is the line with the open brace. 4418 4419@item @var{filename}:@var{function} 4420Specifies the line of the open-brace that begins the body of the 4421function @var{function} in the file @var{filename}. You only need the 4422file name with a function name to avoid ambiguity when there are 4423identically named functions in different source files. 4424 4425@item *@var{address} 4426Specifies the line containing the program address @var{address}. 4427@var{address} may be any expression. 4428@end table 4429 4430@node Edit 4431@section Editing source files 4432@cindex editing source files 4433 4434@kindex edit 4435@kindex e @r{(@code{edit})} 4436To edit the lines in a source file, use the @code{edit} command. 4437The editing program of your choice 4438is invoked with the current line set to 4439the active line in the program. 4440Alternatively, there are several ways to specify what part of the file you 4441want to print if you want to see other parts of the program. 4442 4443Here are the forms of the @code{edit} command most commonly used: 4444 4445@table @code 4446@item edit 4447Edit the current source file at the active line number in the program. 4448 4449@item edit @var{number} 4450Edit the current source file with @var{number} as the active line number. 4451 4452@item edit @var{function} 4453Edit the file containing @var{function} at the beginning of its definition. 4454 4455@item edit @var{filename}:@var{number} 4456Specifies line @var{number} in the source file @var{filename}. 4457 4458@item edit @var{filename}:@var{function} 4459Specifies the line that begins the body of the 4460function @var{function} in the file @var{filename}. You only need the 4461file name with a function name to avoid ambiguity when there are 4462identically named functions in different source files. 4463 4464@item edit *@var{address} 4465Specifies the line containing the program address @var{address}. 4466@var{address} may be any expression. 4467@end table 4468 4469@subsection Choosing your editor 4470You can customize @value{GDBN} to use any editor you want 4471@footnote{ 4472The only restriction is that your editor (say @code{ex}), recognizes the 4473following command-line syntax: 4474@smallexample 4475ex +@var{number} file 4476@end smallexample 4477The optional numeric value +@var{number} specifies the number of the line in 4478the file where to start editing.}. 4479By default, it is @file{@value{EDITOR}}, but you can change this 4480by setting the environment variable @code{EDITOR} before using 4481@value{GDBN}. For example, to configure @value{GDBN} to use the 4482@code{vi} editor, you could use these commands with the @code{sh} shell: 4483@smallexample 4484EDITOR=/usr/bin/vi 4485export EDITOR 4486gdb @dots{} 4487@end smallexample 4488or in the @code{csh} shell, 4489@smallexample 4490setenv EDITOR /usr/bin/vi 4491gdb @dots{} 4492@end smallexample 4493 4494@node Search 4495@section Searching source files 4496@cindex searching source files 4497@kindex reverse-search 4498 4499There are two commands for searching through the current source file for a 4500regular expression. 4501 4502@table @code 4503@kindex search 4504@kindex forward-search 4505@item forward-search @var{regexp} 4506@itemx search @var{regexp} 4507The command @samp{forward-search @var{regexp}} checks each line, 4508starting with the one following the last line listed, for a match for 4509@var{regexp}. It lists the line that is found. You can use the 4510synonym @samp{search @var{regexp}} or abbreviate the command name as 4511@code{fo}. 4512 4513@item reverse-search @var{regexp} 4514The command @samp{reverse-search @var{regexp}} checks each line, starting 4515with the one before the last line listed and going backward, for a match 4516for @var{regexp}. It lists the line that is found. You can abbreviate 4517this command as @code{rev}. 4518@end table 4519 4520@node Source Path 4521@section Specifying source directories 4522 4523@cindex source path 4524@cindex directories for source files 4525Executable programs sometimes do not record the directories of the source 4526files from which they were compiled, just the names. Even when they do, 4527the directories could be moved between the compilation and your debugging 4528session. @value{GDBN} has a list of directories to search for source files; 4529this is called the @dfn{source path}. Each time @value{GDBN} wants a source file, 4530it tries all the directories in the list, in the order they are present 4531in the list, until it finds a file with the desired name. 4532 4533For example, suppose an executable references the file 4534@file{/usr/src/foo-1.0/lib/foo.c}, and our source path is 4535@file{/mnt/cross}. The file is first looked up literally; if this 4536fails, @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} is tried; if this 4537fails, @file{/mnt/cross/foo.c} is opened; if this fails, an error 4538message is printed. @value{GDBN} does not look up the parts of the 4539source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}. 4540Likewise, the subdirectories of the source path are not searched: if 4541the source path is @file{/mnt/cross}, and the binary refers to 4542@file{foo.c}, @value{GDBN} would not find it under 4543@file{/mnt/cross/usr/src/foo-1.0/lib}. 4544 4545Plain file names, relative file names with leading directories, file 4546names containing dots, etc.@: are all treated as described above; for 4547instance, if the source path is @file{/mnt/cross}, and the source file 4548is recorded as @file{../lib/foo.c}, @value{GDBN} would first try 4549@file{../lib/foo.c}, then @file{/mnt/cross/../lib/foo.c}, and after 4550that---@file{/mnt/cross/foo.c}. 4551 4552Note that the executable search path is @emph{not} used to locate the 4553source files. Neither is the current working directory, unless it 4554happens to be in the source path. 4555 4556Whenever you reset or rearrange the source path, @value{GDBN} clears out 4557any information it has cached about where source files are found and where 4558each line is in the file. 4559 4560@kindex directory 4561@kindex dir 4562When you start @value{GDBN}, its source path includes only @samp{cdir} 4563and @samp{cwd}, in that order. 4564To add other directories, use the @code{directory} command. 4565 4566@table @code 4567@item directory @var{dirname} @dots{} 4568@item dir @var{dirname} @dots{} 4569Add directory @var{dirname} to the front of the source path. Several 4570directory names may be given to this command, separated by @samp{:} 4571(@samp{;} on MS-DOS and MS-Windows, where @samp{:} usually appears as 4572part of absolute file names) or 4573whitespace. You may specify a directory that is already in the source 4574path; this moves it forward, so @value{GDBN} searches it sooner. 4575 4576@kindex cdir 4577@kindex cwd 4578@vindex $cdir@r{, convenience variable} 4579@vindex $cwdr@r{, convenience variable} 4580@cindex compilation directory 4581@cindex current directory 4582@cindex working directory 4583@cindex directory, current 4584@cindex directory, compilation 4585You can use the string @samp{$cdir} to refer to the compilation 4586directory (if one is recorded), and @samp{$cwd} to refer to the current 4587working directory. @samp{$cwd} is not the same as @samp{.}---the former 4588tracks the current working directory as it changes during your @value{GDBN} 4589session, while the latter is immediately expanded to the current 4590directory at the time you add an entry to the source path. 4591 4592@item directory 4593Reset the source path to empty again. This requires confirmation. 4594 4595@c RET-repeat for @code{directory} is explicitly disabled, but since 4596@c repeating it would be a no-op we do not say that. (thanks to RMS) 4597 4598@item show directories 4599@kindex show directories 4600Print the source path: show which directories it contains. 4601@end table 4602 4603If your source path is cluttered with directories that are no longer of 4604interest, @value{GDBN} may sometimes cause confusion by finding the wrong 4605versions of source. You can correct the situation as follows: 4606 4607@enumerate 4608@item 4609Use @code{directory} with no argument to reset the source path to empty. 4610 4611@item 4612Use @code{directory} with suitable arguments to reinstall the 4613directories you want in the source path. You can add all the 4614directories in one command. 4615@end enumerate 4616 4617@node Machine Code 4618@section Source and machine code 4619@cindex source line and its code address 4620 4621You can use the command @code{info line} to map source lines to program 4622addresses (and vice versa), and the command @code{disassemble} to display 4623a range of addresses as machine instructions. When run under @sc{gnu} Emacs 4624mode, the @code{info line} command causes the arrow to point to the 4625line specified. Also, @code{info line} prints addresses in symbolic form as 4626well as hex. 4627 4628@table @code 4629@kindex info line 4630@item info line @var{linespec} 4631Print the starting and ending addresses of the compiled code for 4632source line @var{linespec}. You can specify source lines in any of 4633the ways understood by the @code{list} command (@pxref{List, ,Printing 4634source lines}). 4635@end table 4636 4637For example, we can use @code{info line} to discover the location of 4638the object code for the first line of function 4639@code{m4_changequote}: 4640 4641@c FIXME: I think this example should also show the addresses in 4642@c symbolic form, as they usually would be displayed. 4643@smallexample 4644(@value{GDBP}) info line m4_changequote 4645Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. 4646@end smallexample 4647 4648@noindent 4649@cindex code address and its source line 4650We can also inquire (using @code{*@var{addr}} as the form for 4651@var{linespec}) what source line covers a particular address: 4652@smallexample 4653(@value{GDBP}) info line *0x63ff 4654Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. 4655@end smallexample 4656 4657@cindex @code{$_} and @code{info line} 4658@cindex @code{x} command, default address 4659@kindex x@r{(examine), and} info line 4660After @code{info line}, the default address for the @code{x} command 4661is changed to the starting address of the line, so that @samp{x/i} is 4662sufficient to begin examining the machine code (@pxref{Memory, 4663,Examining memory}). Also, this address is saved as the value of the 4664convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience 4665variables}). 4666 4667@table @code 4668@kindex disassemble 4669@cindex assembly instructions 4670@cindex instructions, assembly 4671@cindex machine instructions 4672@cindex listing machine instructions 4673@item disassemble 4674This specialized command dumps a range of memory as machine 4675instructions. The default memory range is the function surrounding the 4676program counter of the selected frame. A single argument to this 4677command is a program counter value; @value{GDBN} dumps the function 4678surrounding this value. Two arguments specify a range of addresses 4679(first inclusive, second exclusive) to dump. 4680@end table 4681 4682The following example shows the disassembly of a range of addresses of 4683HP PA-RISC 2.0 code: 4684 4685@smallexample 4686(@value{GDBP}) disas 0x32c4 0x32e4 4687Dump of assembler code from 0x32c4 to 0x32e4: 46880x32c4 <main+204>: addil 0,dp 46890x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 46900x32cc <main+212>: ldil 0x3000,r31 46910x32d0 <main+216>: ble 0x3f8(sr4,r31) 46920x32d4 <main+220>: ldo 0(r31),rp 46930x32d8 <main+224>: addil -0x800,dp 46940x32dc <main+228>: ldo 0x588(r1),r26 46950x32e0 <main+232>: ldil 0x3000,r31 4696End of assembler dump. 4697@end smallexample 4698 4699Some architectures have more than one commonly-used set of instruction 4700mnemonics or other syntax. 4701 4702@table @code 4703@kindex set disassembly-flavor 4704@cindex Intel disassembly flavor 4705@cindex AT&T disassembly flavor 4706@item set disassembly-flavor @var{instruction-set} 4707Select the instruction set to use when disassembling the 4708program via the @code{disassemble} or @code{x/i} commands. 4709 4710Currently this command is only defined for the Intel x86 family. You 4711can set @var{instruction-set} to either @code{intel} or @code{att}. 4712The default is @code{att}, the AT&T flavor used by default by Unix 4713assemblers for x86-based targets. 4714@end table 4715 4716 4717@node Data 4718@chapter Examining Data 4719 4720@cindex printing data 4721@cindex examining data 4722@kindex print 4723@kindex inspect 4724@c "inspect" is not quite a synonym if you are using Epoch, which we do not 4725@c document because it is nonstandard... Under Epoch it displays in a 4726@c different window or something like that. 4727The usual way to examine data in your program is with the @code{print} 4728command (abbreviated @code{p}), or its synonym @code{inspect}. It 4729evaluates and prints the value of an expression of the language your 4730program is written in (@pxref{Languages, ,Using @value{GDBN} with 4731Different Languages}). 4732 4733@table @code 4734@item print @var{expr} 4735@itemx print /@var{f} @var{expr} 4736@var{expr} is an expression (in the source language). By default the 4737value of @var{expr} is printed in a format appropriate to its data type; 4738you can choose a different format by specifying @samp{/@var{f}}, where 4739@var{f} is a letter specifying the format; see @ref{Output Formats,,Output 4740formats}. 4741 4742@item print 4743@itemx print /@var{f} 4744@cindex reprint the last value 4745If you omit @var{expr}, @value{GDBN} displays the last value again (from the 4746@dfn{value history}; @pxref{Value History, ,Value history}). This allows you to 4747conveniently inspect the same value in an alternative format. 4748@end table 4749 4750A more low-level way of examining data is with the @code{x} command. 4751It examines data in memory at a specified address and prints it in a 4752specified format. @xref{Memory, ,Examining memory}. 4753 4754If you are interested in information about types, or about how the 4755fields of a struct or a class are declared, use the @code{ptype @var{exp}} 4756command rather than @code{print}. @xref{Symbols, ,Examining the Symbol 4757Table}. 4758 4759@menu 4760* Expressions:: Expressions 4761* Variables:: Program variables 4762* Arrays:: Artificial arrays 4763* Output Formats:: Output formats 4764* Memory:: Examining memory 4765* Auto Display:: Automatic display 4766* Print Settings:: Print settings 4767* Value History:: Value history 4768* Convenience Vars:: Convenience variables 4769* Registers:: Registers 4770* Floating Point Hardware:: Floating point hardware 4771* Vector Unit:: Vector Unit 4772* Auxiliary Vector:: Auxiliary data provided by operating system 4773* Memory Region Attributes:: Memory region attributes 4774* Dump/Restore Files:: Copy between memory and a file 4775* Character Sets:: Debugging programs that use a different 4776 character set than GDB does 4777@end menu 4778 4779@node Expressions 4780@section Expressions 4781 4782@cindex expressions 4783@code{print} and many other @value{GDBN} commands accept an expression and 4784compute its value. Any kind of constant, variable or operator defined 4785by the programming language you are using is valid in an expression in 4786@value{GDBN}. This includes conditional expressions, function calls, 4787casts, and string constants. It also includes preprocessor macros, if 4788you compiled your program to include this information; see 4789@ref{Compilation}. 4790 4791@cindex arrays in expressions 4792@value{GDBN} supports array constants in expressions input by 4793the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example, 4794you can use the command @code{print @{1, 2, 3@}} to build up an array in 4795memory that is @code{malloc}ed in the target program. 4796 4797Because C is so widespread, most of the expressions shown in examples in 4798this manual are in C. @xref{Languages, , Using @value{GDBN} with Different 4799Languages}, for information on how to use expressions in other 4800languages. 4801 4802In this section, we discuss operators that you can use in @value{GDBN} 4803expressions regardless of your programming language. 4804 4805@cindex casts, in expressions 4806Casts are supported in all languages, not just in C, because it is so 4807useful to cast a number into a pointer in order to examine a structure 4808at that address in memory. 4809@c FIXME: casts supported---Mod2 true? 4810 4811@value{GDBN} supports these operators, in addition to those common 4812to programming languages: 4813 4814@table @code 4815@item @@ 4816@samp{@@} is a binary operator for treating parts of memory as arrays. 4817@xref{Arrays, ,Artificial arrays}, for more information. 4818 4819@item :: 4820@samp{::} allows you to specify a variable in terms of the file or 4821function where it is defined. @xref{Variables, ,Program variables}. 4822 4823@cindex @{@var{type}@} 4824@cindex type casting memory 4825@cindex memory, viewing as typed object 4826@cindex casts, to view memory 4827@item @{@var{type}@} @var{addr} 4828Refers to an object of type @var{type} stored at address @var{addr} in 4829memory. @var{addr} may be any expression whose value is an integer or 4830pointer (but parentheses are required around binary operators, just as in 4831a cast). This construct is allowed regardless of what kind of data is 4832normally supposed to reside at @var{addr}. 4833@end table 4834 4835@node Variables 4836@section Program variables 4837 4838The most common kind of expression to use is the name of a variable 4839in your program. 4840 4841Variables in expressions are understood in the selected stack frame 4842(@pxref{Selection, ,Selecting a frame}); they must be either: 4843 4844@itemize @bullet 4845@item 4846global (or file-static) 4847@end itemize 4848 4849@noindent or 4850 4851@itemize @bullet 4852@item 4853visible according to the scope rules of the 4854programming language from the point of execution in that frame 4855@end itemize 4856 4857@noindent This means that in the function 4858 4859@smallexample 4860foo (a) 4861 int a; 4862@{ 4863 bar (a); 4864 @{ 4865 int b = test (); 4866 bar (b); 4867 @} 4868@} 4869@end smallexample 4870 4871@noindent 4872you can examine and use the variable @code{a} whenever your program is 4873executing within the function @code{foo}, but you can only use or 4874examine the variable @code{b} while your program is executing inside 4875the block where @code{b} is declared. 4876 4877@cindex variable name conflict 4878There is an exception: you can refer to a variable or function whose 4879scope is a single source file even if the current execution point is not 4880in this file. But it is possible to have more than one such variable or 4881function with the same name (in different source files). If that 4882happens, referring to that name has unpredictable effects. If you wish, 4883you can specify a static variable in a particular function or file, 4884using the colon-colon (@code{::}) notation: 4885 4886@cindex colon-colon, context for variables/functions 4887@iftex 4888@c info cannot cope with a :: index entry, but why deprive hard copy readers? 4889@cindex @code{::}, context for variables/functions 4890@end iftex 4891@smallexample 4892@var{file}::@var{variable} 4893@var{function}::@var{variable} 4894@end smallexample 4895 4896@noindent 4897Here @var{file} or @var{function} is the name of the context for the 4898static @var{variable}. In the case of file names, you can use quotes to 4899make sure @value{GDBN} parses the file name as a single word---for example, 4900to print a global value of @code{x} defined in @file{f2.c}: 4901 4902@smallexample 4903(@value{GDBP}) p 'f2.c'::x 4904@end smallexample 4905 4906@cindex C@t{++} scope resolution 4907This use of @samp{::} is very rarely in conflict with the very similar 4908use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++} 4909scope resolution operator in @value{GDBN} expressions. 4910@c FIXME: Um, so what happens in one of those rare cases where it's in 4911@c conflict?? --mew 4912 4913@cindex wrong values 4914@cindex variable values, wrong 4915@cindex function entry/exit, wrong values of variables 4916@cindex optimized code, wrong values of variables 4917@quotation 4918@emph{Warning:} Occasionally, a local variable may appear to have the 4919wrong value at certain points in a function---just after entry to a new 4920scope, and just before exit. 4921@end quotation 4922You may see this problem when you are stepping by machine instructions. 4923This is because, on most machines, it takes more than one instruction to 4924set up a stack frame (including local variable definitions); if you are 4925stepping by machine instructions, variables may appear to have the wrong 4926values until the stack frame is completely built. On exit, it usually 4927also takes more than one machine instruction to destroy a stack frame; 4928after you begin stepping through that group of instructions, local 4929variable definitions may be gone. 4930 4931This may also happen when the compiler does significant optimizations. 4932To be sure of always seeing accurate values, turn off all optimization 4933when compiling. 4934 4935@cindex ``No symbol "foo" in current context'' 4936Another possible effect of compiler optimizations is to optimize 4937unused variables out of existence, or assign variables to registers (as 4938opposed to memory addresses). Depending on the support for such cases 4939offered by the debug info format used by the compiler, @value{GDBN} 4940might not be able to display values for such local variables. If that 4941happens, @value{GDBN} will print a message like this: 4942 4943@smallexample 4944No symbol "foo" in current context. 4945@end smallexample 4946 4947To solve such problems, either recompile without optimizations, or use a 4948different debug info format, if the compiler supports several such 4949formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler, 4950usually supports the @option{-gstabs+} option. @option{-gstabs+} 4951produces debug info in a format that is superior to formats such as 4952COFF. You may be able to use DWARF 2 (@option{-gdwarf-2}), which is also 4953an effective form for debug info. @xref{Debugging Options,,Options 4954for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}. 4955@xref{C, , Debugging C++}, for more info about debug info formats 4956that are best suited to C@t{++} programs. 4957 4958@node Arrays 4959@section Artificial arrays 4960 4961@cindex artificial array 4962@cindex arrays 4963@kindex @@@r{, referencing memory as an array} 4964It is often useful to print out several successive objects of the 4965same type in memory; a section of an array, or an array of 4966dynamically determined size for which only a pointer exists in the 4967program. 4968 4969You can do this by referring to a contiguous span of memory as an 4970@dfn{artificial array}, using the binary operator @samp{@@}. The left 4971operand of @samp{@@} should be the first element of the desired array 4972and be an individual object. The right operand should be the desired length 4973of the array. The result is an array value whose elements are all of 4974the type of the left argument. The first element is actually the left 4975argument; the second element comes from bytes of memory immediately 4976following those that hold the first element, and so on. Here is an 4977example. If a program says 4978 4979@smallexample 4980int *array = (int *) malloc (len * sizeof (int)); 4981@end smallexample 4982 4983@noindent 4984you can print the contents of @code{array} with 4985 4986@smallexample 4987p *array@@len 4988@end smallexample 4989 4990The left operand of @samp{@@} must reside in memory. Array values made 4991with @samp{@@} in this way behave just like other arrays in terms of 4992subscripting, and are coerced to pointers when used in expressions. 4993Artificial arrays most often appear in expressions via the value history 4994(@pxref{Value History, ,Value history}), after printing one out. 4995 4996Another way to create an artificial array is to use a cast. 4997This re-interprets a value as if it were an array. 4998The value need not be in memory: 4999@smallexample 5000(@value{GDBP}) p/x (short[2])0x12345678 5001$1 = @{0x1234, 0x5678@} 5002@end smallexample 5003 5004As a convenience, if you leave the array length out (as in 5005@samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill 5006the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}: 5007@smallexample 5008(@value{GDBP}) p/x (short[])0x12345678 5009$2 = @{0x1234, 0x5678@} 5010@end smallexample 5011 5012Sometimes the artificial array mechanism is not quite enough; in 5013moderately complex data structures, the elements of interest may not 5014actually be adjacent---for example, if you are interested in the values 5015of pointers in an array. One useful work-around in this situation is 5016to use a convenience variable (@pxref{Convenience Vars, ,Convenience 5017variables}) as a counter in an expression that prints the first 5018interesting value, and then repeat that expression via @key{RET}. For 5019instance, suppose you have an array @code{dtab} of pointers to 5020structures, and you are interested in the values of a field @code{fv} 5021in each structure. Here is an example of what you might type: 5022 5023@smallexample 5024set $i = 0 5025p dtab[$i++]->fv 5026@key{RET} 5027@key{RET} 5028@dots{} 5029@end smallexample 5030 5031@node Output Formats 5032@section Output formats 5033 5034@cindex formatted output 5035@cindex output formats 5036By default, @value{GDBN} prints a value according to its data type. Sometimes 5037this is not what you want. For example, you might want to print a number 5038in hex, or a pointer in decimal. Or you might want to view data in memory 5039at a certain address as a character string or as an instruction. To do 5040these things, specify an @dfn{output format} when you print a value. 5041 5042The simplest use of output formats is to say how to print a value 5043already computed. This is done by starting the arguments of the 5044@code{print} command with a slash and a format letter. The format 5045letters supported are: 5046 5047@table @code 5048@item x 5049Regard the bits of the value as an integer, and print the integer in 5050hexadecimal. 5051 5052@item d 5053Print as integer in signed decimal. 5054 5055@item u 5056Print as integer in unsigned decimal. 5057 5058@item o 5059Print as integer in octal. 5060 5061@item t 5062Print as integer in binary. The letter @samp{t} stands for ``two''. 5063@footnote{@samp{b} cannot be used because these format letters are also 5064used with the @code{x} command, where @samp{b} stands for ``byte''; 5065see @ref{Memory,,Examining memory}.} 5066 5067@item a 5068@cindex unknown address, locating 5069@cindex locate address 5070Print as an address, both absolute in hexadecimal and as an offset from 5071the nearest preceding symbol. You can use this format used to discover 5072where (in what function) an unknown address is located: 5073 5074@smallexample 5075(@value{GDBP}) p/a 0x54320 5076$3 = 0x54320 <_initialize_vx+396> 5077@end smallexample 5078 5079@noindent 5080The command @code{info symbol 0x54320} yields similar results. 5081@xref{Symbols, info symbol}. 5082 5083@item c 5084Regard as an integer and print it as a character constant. 5085 5086@item f 5087Regard the bits of the value as a floating point number and print 5088using typical floating point syntax. 5089@end table 5090 5091For example, to print the program counter in hex (@pxref{Registers}), type 5092 5093@smallexample 5094p/x $pc 5095@end smallexample 5096 5097@noindent 5098Note that no space is required before the slash; this is because command 5099names in @value{GDBN} cannot contain a slash. 5100 5101To reprint the last value in the value history with a different format, 5102you can use the @code{print} command with just a format and no 5103expression. For example, @samp{p/x} reprints the last value in hex. 5104 5105@node Memory 5106@section Examining memory 5107 5108You can use the command @code{x} (for ``examine'') to examine memory in 5109any of several formats, independently of your program's data types. 5110 5111@cindex examining memory 5112@table @code 5113@kindex x @r{(examine memory)} 5114@item x/@var{nfu} @var{addr} 5115@itemx x @var{addr} 5116@itemx x 5117Use the @code{x} command to examine memory. 5118@end table 5119 5120@var{n}, @var{f}, and @var{u} are all optional parameters that specify how 5121much memory to display and how to format it; @var{addr} is an 5122expression giving the address where you want to start displaying memory. 5123If you use defaults for @var{nfu}, you need not type the slash @samp{/}. 5124Several commands set convenient defaults for @var{addr}. 5125 5126@table @r 5127@item @var{n}, the repeat count 5128The repeat count is a decimal integer; the default is 1. It specifies 5129how much memory (counting by units @var{u}) to display. 5130@c This really is **decimal**; unaffected by 'set radix' as of GDB 5131@c 4.1.2. 5132 5133@item @var{f}, the display format 5134The display format is one of the formats used by @code{print}, 5135@samp{s} (null-terminated string), or @samp{i} (machine instruction). 5136The default is @samp{x} (hexadecimal) initially. 5137The default changes each time you use either @code{x} or @code{print}. 5138 5139@item @var{u}, the unit size 5140The unit size is any of 5141 5142@table @code 5143@item b 5144Bytes. 5145@item h 5146Halfwords (two bytes). 5147@item w 5148Words (four bytes). This is the initial default. 5149@item g 5150Giant words (eight bytes). 5151@end table 5152 5153Each time you specify a unit size with @code{x}, that size becomes the 5154default unit the next time you use @code{x}. (For the @samp{s} and 5155@samp{i} formats, the unit size is ignored and is normally not written.) 5156 5157@item @var{addr}, starting display address 5158@var{addr} is the address where you want @value{GDBN} to begin displaying 5159memory. The expression need not have a pointer value (though it may); 5160it is always interpreted as an integer address of a byte of memory. 5161@xref{Expressions, ,Expressions}, for more information on expressions. The default for 5162@var{addr} is usually just after the last address examined---but several 5163other commands also set the default address: @code{info breakpoints} (to 5164the address of the last breakpoint listed), @code{info line} (to the 5165starting address of a line), and @code{print} (if you use it to display 5166a value from memory). 5167@end table 5168 5169For example, @samp{x/3uh 0x54320} is a request to display three halfwords 5170(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}), 5171starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four 5172words (@samp{w}) of memory above the stack pointer (here, @samp{$sp}; 5173@pxref{Registers, ,Registers}) in hexadecimal (@samp{x}). 5174 5175Since the letters indicating unit sizes are all distinct from the 5176letters specifying output formats, you do not have to remember whether 5177unit size or format comes first; either order works. The output 5178specifications @samp{4xw} and @samp{4wx} mean exactly the same thing. 5179(However, the count @var{n} must come first; @samp{wx4} does not work.) 5180 5181Even though the unit size @var{u} is ignored for the formats @samp{s} 5182and @samp{i}, you might still want to use a count @var{n}; for example, 5183@samp{3i} specifies that you want to see three machine instructions, 5184including any operands. The command @code{disassemble} gives an 5185alternative way of inspecting machine instructions; see @ref{Machine 5186Code,,Source and machine code}. 5187 5188All the defaults for the arguments to @code{x} are designed to make it 5189easy to continue scanning memory with minimal specifications each time 5190you use @code{x}. For example, after you have inspected three machine 5191instructions with @samp{x/3i @var{addr}}, you can inspect the next seven 5192with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command, 5193the repeat count @var{n} is used again; the other arguments default as 5194for successive uses of @code{x}. 5195 5196@cindex @code{$_}, @code{$__}, and value history 5197The addresses and contents printed by the @code{x} command are not saved 5198in the value history because there is often too much of them and they 5199would get in the way. Instead, @value{GDBN} makes these values available for 5200subsequent use in expressions as values of the convenience variables 5201@code{$_} and @code{$__}. After an @code{x} command, the last address 5202examined is available for use in expressions in the convenience variable 5203@code{$_}. The contents of that address, as examined, are available in 5204the convenience variable @code{$__}. 5205 5206If the @code{x} command has a repeat count, the address and contents saved 5207are from the last memory unit printed; this is not the same as the last 5208address printed if several units were printed on the last line of output. 5209 5210@node Auto Display 5211@section Automatic display 5212@cindex automatic display 5213@cindex display of expressions 5214 5215If you find that you want to print the value of an expression frequently 5216(to see how it changes), you might want to add it to the @dfn{automatic 5217display list} so that @value{GDBN} prints its value each time your program stops. 5218Each expression added to the list is given a number to identify it; 5219to remove an expression from the list, you specify that number. 5220The automatic display looks like this: 5221 5222@smallexample 52232: foo = 38 52243: bar[5] = (struct hack *) 0x3804 5225@end smallexample 5226 5227@noindent 5228This display shows item numbers, expressions and their current values. As with 5229displays you request manually using @code{x} or @code{print}, you can 5230specify the output format you prefer; in fact, @code{display} decides 5231whether to use @code{print} or @code{x} depending on how elaborate your 5232format specification is---it uses @code{x} if you specify a unit size, 5233or one of the two formats (@samp{i} and @samp{s}) that are only 5234supported by @code{x}; otherwise it uses @code{print}. 5235 5236@table @code 5237@kindex display 5238@item display @var{expr} 5239Add the expression @var{expr} to the list of expressions to display 5240each time your program stops. @xref{Expressions, ,Expressions}. 5241 5242@code{display} does not repeat if you press @key{RET} again after using it. 5243 5244@item display/@var{fmt} @var{expr} 5245For @var{fmt} specifying only a display format and not a size or 5246count, add the expression @var{expr} to the auto-display list but 5247arrange to display it each time in the specified format @var{fmt}. 5248@xref{Output Formats,,Output formats}. 5249 5250@item display/@var{fmt} @var{addr} 5251For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a 5252number of units, add the expression @var{addr} as a memory address to 5253be examined each time your program stops. Examining means in effect 5254doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining memory}. 5255@end table 5256 5257For example, @samp{display/i $pc} can be helpful, to see the machine 5258instruction about to be executed each time execution stops (@samp{$pc} 5259is a common name for the program counter; @pxref{Registers, ,Registers}). 5260 5261@table @code 5262@kindex delete display 5263@kindex undisplay 5264@item undisplay @var{dnums}@dots{} 5265@itemx delete display @var{dnums}@dots{} 5266Remove item numbers @var{dnums} from the list of expressions to display. 5267 5268@code{undisplay} does not repeat if you press @key{RET} after using it. 5269(Otherwise you would just get the error @samp{No display number @dots{}}.) 5270 5271@kindex disable display 5272@item disable display @var{dnums}@dots{} 5273Disable the display of item numbers @var{dnums}. A disabled display 5274item is not printed automatically, but is not forgotten. It may be 5275enabled again later. 5276 5277@kindex enable display 5278@item enable display @var{dnums}@dots{} 5279Enable display of item numbers @var{dnums}. It becomes effective once 5280again in auto display of its expression, until you specify otherwise. 5281 5282@item display 5283Display the current values of the expressions on the list, just as is 5284done when your program stops. 5285 5286@kindex info display 5287@item info display 5288Print the list of expressions previously set up to display 5289automatically, each one with its item number, but without showing the 5290values. This includes disabled expressions, which are marked as such. 5291It also includes expressions which would not be displayed right now 5292because they refer to automatic variables not currently available. 5293@end table 5294 5295@cindex display disabled out of scope 5296If a display expression refers to local variables, then it does not make 5297sense outside the lexical context for which it was set up. Such an 5298expression is disabled when execution enters a context where one of its 5299variables is not defined. For example, if you give the command 5300@code{display last_char} while inside a function with an argument 5301@code{last_char}, @value{GDBN} displays this argument while your program 5302continues to stop inside that function. When it stops elsewhere---where 5303there is no variable @code{last_char}---the display is disabled 5304automatically. The next time your program stops where @code{last_char} 5305is meaningful, you can enable the display expression once again. 5306 5307@node Print Settings 5308@section Print settings 5309 5310@cindex format options 5311@cindex print settings 5312@value{GDBN} provides the following ways to control how arrays, structures, 5313and symbols are printed. 5314 5315@noindent 5316These settings are useful for debugging programs in any language: 5317 5318@table @code 5319@kindex set print 5320@item set print address 5321@itemx set print address on 5322@cindex print/don't print memory addresses 5323@value{GDBN} prints memory addresses showing the location of stack 5324traces, structure values, pointer values, breakpoints, and so forth, 5325even when it also displays the contents of those addresses. The default 5326is @code{on}. For example, this is what a stack frame display looks like with 5327@code{set print address on}: 5328 5329@smallexample 5330@group 5331(@value{GDBP}) f 5332#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") 5333 at input.c:530 5334530 if (lquote != def_lquote) 5335@end group 5336@end smallexample 5337 5338@item set print address off 5339Do not print addresses when displaying their contents. For example, 5340this is the same stack frame displayed with @code{set print address off}: 5341 5342@smallexample 5343@group 5344(@value{GDBP}) set print addr off 5345(@value{GDBP}) f 5346#0 set_quotes (lq="<<", rq=">>") at input.c:530 5347530 if (lquote != def_lquote) 5348@end group 5349@end smallexample 5350 5351You can use @samp{set print address off} to eliminate all machine 5352dependent displays from the @value{GDBN} interface. For example, with 5353@code{print address off}, you should get the same text for backtraces on 5354all machines---whether or not they involve pointer arguments. 5355 5356@kindex show print 5357@item show print address 5358Show whether or not addresses are to be printed. 5359@end table 5360 5361When @value{GDBN} prints a symbolic address, it normally prints the 5362closest earlier symbol plus an offset. If that symbol does not uniquely 5363identify the address (for example, it is a name whose scope is a single 5364source file), you may need to clarify. One way to do this is with 5365@code{info line}, for example @samp{info line *0x4537}. Alternately, 5366you can set @value{GDBN} to print the source file and line number when 5367it prints a symbolic address: 5368 5369@table @code 5370@item set print symbol-filename on 5371@cindex closest symbol and offset for an address 5372Tell @value{GDBN} to print the source file name and line number of a 5373symbol in the symbolic form of an address. 5374 5375@item set print symbol-filename off 5376Do not print source file name and line number of a symbol. This is the 5377default. 5378 5379@item show print symbol-filename 5380Show whether or not @value{GDBN} will print the source file name and 5381line number of a symbol in the symbolic form of an address. 5382@end table 5383 5384Another situation where it is helpful to show symbol filenames and line 5385numbers is when disassembling code; @value{GDBN} shows you the line 5386number and source file that corresponds to each instruction. 5387 5388Also, you may wish to see the symbolic form only if the address being 5389printed is reasonably close to the closest earlier symbol: 5390 5391@table @code 5392@item set print max-symbolic-offset @var{max-offset} 5393@cindex maximum value for offset of closest symbol 5394Tell @value{GDBN} to only display the symbolic form of an address if the 5395offset between the closest earlier symbol and the address is less than 5396@var{max-offset}. The default is 0, which tells @value{GDBN} 5397to always print the symbolic form of an address if any symbol precedes it. 5398 5399@item show print max-symbolic-offset 5400Ask how large the maximum offset is that @value{GDBN} prints in a 5401symbolic address. 5402@end table 5403 5404@cindex wild pointer, interpreting 5405@cindex pointer, finding referent 5406If you have a pointer and you are not sure where it points, try 5407@samp{set print symbol-filename on}. Then you can determine the name 5408and source file location of the variable where it points, using 5409@samp{p/a @var{pointer}}. This interprets the address in symbolic form. 5410For example, here @value{GDBN} shows that a variable @code{ptt} points 5411at another variable @code{t}, defined in @file{hi2.c}: 5412 5413@smallexample 5414(@value{GDBP}) set print symbol-filename on 5415(@value{GDBP}) p/a ptt 5416$4 = 0xe008 <t in hi2.c> 5417@end smallexample 5418 5419@quotation 5420@emph{Warning:} For pointers that point to a local variable, @samp{p/a} 5421does not show the symbol name and filename of the referent, even with 5422the appropriate @code{set print} options turned on. 5423@end quotation 5424 5425Other settings control how different kinds of objects are printed: 5426 5427@table @code 5428@item set print array 5429@itemx set print array on 5430@cindex pretty print arrays 5431Pretty print arrays. This format is more convenient to read, 5432but uses more space. The default is off. 5433 5434@item set print array off 5435Return to compressed format for arrays. 5436 5437@item show print array 5438Show whether compressed or pretty format is selected for displaying 5439arrays. 5440 5441@item set print elements @var{number-of-elements} 5442@cindex number of array elements to print 5443Set a limit on how many elements of an array @value{GDBN} will print. 5444If @value{GDBN} is printing a large array, it stops printing after it has 5445printed the number of elements set by the @code{set print elements} command. 5446This limit also applies to the display of strings. 5447When @value{GDBN} starts, this limit is set to 200. 5448Setting @var{number-of-elements} to zero means that the printing is unlimited. 5449 5450@item show print elements 5451Display the number of elements of a large array that @value{GDBN} will print. 5452If the number is 0, then the printing is unlimited. 5453 5454@item set print null-stop 5455@cindex @sc{null} elements in arrays 5456Cause @value{GDBN} to stop printing the characters of an array when the first 5457@sc{null} is encountered. This is useful when large arrays actually 5458contain only short strings. 5459The default is off. 5460 5461@item set print pretty on 5462Cause @value{GDBN} to print structures in an indented format with one member 5463per line, like this: 5464 5465@smallexample 5466@group 5467$1 = @{ 5468 next = 0x0, 5469 flags = @{ 5470 sweet = 1, 5471 sour = 1 5472 @}, 5473 meat = 0x54 "Pork" 5474@} 5475@end group 5476@end smallexample 5477 5478@item set print pretty off 5479Cause @value{GDBN} to print structures in a compact format, like this: 5480 5481@smallexample 5482@group 5483$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \ 5484meat = 0x54 "Pork"@} 5485@end group 5486@end smallexample 5487 5488@noindent 5489This is the default format. 5490 5491@item show print pretty 5492Show which format @value{GDBN} is using to print structures. 5493 5494@item set print sevenbit-strings on 5495@cindex eight-bit characters in strings 5496@cindex octal escapes in strings 5497Print using only seven-bit characters; if this option is set, 5498@value{GDBN} displays any eight-bit characters (in strings or 5499character values) using the notation @code{\}@var{nnn}. This setting is 5500best if you are working in English (@sc{ascii}) and you use the 5501high-order bit of characters as a marker or ``meta'' bit. 5502 5503@item set print sevenbit-strings off 5504Print full eight-bit characters. This allows the use of more 5505international character sets, and is the default. 5506 5507@item show print sevenbit-strings 5508Show whether or not @value{GDBN} is printing only seven-bit characters. 5509 5510@item set print union on 5511@cindex unions in structures, printing 5512Tell @value{GDBN} to print unions which are contained in structures. This 5513is the default setting. 5514 5515@item set print union off 5516Tell @value{GDBN} not to print unions which are contained in structures. 5517 5518@item show print union 5519Ask @value{GDBN} whether or not it will print unions which are contained in 5520structures. 5521 5522For example, given the declarations 5523 5524@smallexample 5525typedef enum @{Tree, Bug@} Species; 5526typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms; 5527typedef enum @{Caterpillar, Cocoon, Butterfly@} 5528 Bug_forms; 5529 5530struct thing @{ 5531 Species it; 5532 union @{ 5533 Tree_forms tree; 5534 Bug_forms bug; 5535 @} form; 5536@}; 5537 5538struct thing foo = @{Tree, @{Acorn@}@}; 5539@end smallexample 5540 5541@noindent 5542with @code{set print union on} in effect @samp{p foo} would print 5543 5544@smallexample 5545$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@} 5546@end smallexample 5547 5548@noindent 5549and with @code{set print union off} in effect it would print 5550 5551@smallexample 5552$1 = @{it = Tree, form = @{...@}@} 5553@end smallexample 5554@end table 5555 5556@need 1000 5557@noindent 5558These settings are of interest when debugging C@t{++} programs: 5559 5560@table @code 5561@cindex demangling C@t{++} names 5562@item set print demangle 5563@itemx set print demangle on 5564Print C@t{++} names in their source form rather than in the encoded 5565(``mangled'') form passed to the assembler and linker for type-safe 5566linkage. The default is on. 5567 5568@item show print demangle 5569Show whether C@t{++} names are printed in mangled or demangled form. 5570 5571@item set print asm-demangle 5572@itemx set print asm-demangle on 5573Print C@t{++} names in their source form rather than their mangled form, even 5574in assembler code printouts such as instruction disassemblies. 5575The default is off. 5576 5577@item show print asm-demangle 5578Show whether C@t{++} names in assembly listings are printed in mangled 5579or demangled form. 5580 5581@cindex C@t{++} symbol decoding style 5582@cindex symbol decoding style, C@t{++} 5583@item set demangle-style @var{style} 5584Choose among several encoding schemes used by different compilers to 5585represent C@t{++} names. The choices for @var{style} are currently: 5586 5587@table @code 5588@item auto 5589Allow @value{GDBN} to choose a decoding style by inspecting your program. 5590 5591@item gnu 5592Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm. 5593This is the default. 5594 5595@item hp 5596Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm. 5597 5598@item lucid 5599Decode based on the Lucid C@t{++} compiler (@code{lcc}) encoding algorithm. 5600 5601@item arm 5602Decode using the algorithm in the @cite{C@t{++} Annotated Reference Manual}. 5603@strong{Warning:} this setting alone is not sufficient to allow 5604debugging @code{cfront}-generated executables. @value{GDBN} would 5605require further enhancement to permit that. 5606 5607@end table 5608If you omit @var{style}, you will see a list of possible formats. 5609 5610@item show demangle-style 5611Display the encoding style currently in use for decoding C@t{++} symbols. 5612 5613@item set print object 5614@itemx set print object on 5615@cindex derived type of an object, printing 5616When displaying a pointer to an object, identify the @emph{actual} 5617(derived) type of the object rather than the @emph{declared} type, using 5618the virtual function table. 5619 5620@item set print object off 5621Display only the declared type of objects, without reference to the 5622virtual function table. This is the default setting. 5623 5624@item show print object 5625Show whether actual, or declared, object types are displayed. 5626 5627@item set print static-members 5628@itemx set print static-members on 5629@cindex static members of C@t{++} objects 5630Print static members when displaying a C@t{++} object. The default is on. 5631 5632@item set print static-members off 5633Do not print static members when displaying a C@t{++} object. 5634 5635@item show print static-members 5636Show whether C@t{++} static members are printed, or not. 5637 5638@c These don't work with HP ANSI C++ yet. 5639@item set print vtbl 5640@itemx set print vtbl on 5641@cindex pretty print C@t{++} virtual function tables 5642Pretty print C@t{++} virtual function tables. The default is off. 5643(The @code{vtbl} commands do not work on programs compiled with the HP 5644ANSI C@t{++} compiler (@code{aCC}).) 5645 5646@item set print vtbl off 5647Do not pretty print C@t{++} virtual function tables. 5648 5649@item show print vtbl 5650Show whether C@t{++} virtual function tables are pretty printed, or not. 5651@end table 5652 5653@node Value History 5654@section Value history 5655 5656@cindex value history 5657Values printed by the @code{print} command are saved in the @value{GDBN} 5658@dfn{value history}. This allows you to refer to them in other expressions. 5659Values are kept until the symbol table is re-read or discarded 5660(for example with the @code{file} or @code{symbol-file} commands). 5661When the symbol table changes, the value history is discarded, 5662since the values may contain pointers back to the types defined in the 5663symbol table. 5664 5665@cindex @code{$} 5666@cindex @code{$$} 5667@cindex history number 5668The values printed are given @dfn{history numbers} by which you can 5669refer to them. These are successive integers starting with one. 5670@code{print} shows you the history number assigned to a value by 5671printing @samp{$@var{num} = } before the value; here @var{num} is the 5672history number. 5673 5674To refer to any previous value, use @samp{$} followed by the value's 5675history number. The way @code{print} labels its output is designed to 5676remind you of this. Just @code{$} refers to the most recent value in 5677the history, and @code{$$} refers to the value before that. 5678@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2} 5679is the value just prior to @code{$$}, @code{$$1} is equivalent to 5680@code{$$}, and @code{$$0} is equivalent to @code{$}. 5681 5682For example, suppose you have just printed a pointer to a structure and 5683want to see the contents of the structure. It suffices to type 5684 5685@smallexample 5686p *$ 5687@end smallexample 5688 5689If you have a chain of structures where the component @code{next} points 5690to the next one, you can print the contents of the next one with this: 5691 5692@smallexample 5693p *$.next 5694@end smallexample 5695 5696@noindent 5697You can print successive links in the chain by repeating this 5698command---which you can do by just typing @key{RET}. 5699 5700Note that the history records values, not expressions. If the value of 5701@code{x} is 4 and you type these commands: 5702 5703@smallexample 5704print x 5705set x=5 5706@end smallexample 5707 5708@noindent 5709then the value recorded in the value history by the @code{print} command 5710remains 4 even though the value of @code{x} has changed. 5711 5712@table @code 5713@kindex show values 5714@item show values 5715Print the last ten values in the value history, with their item numbers. 5716This is like @samp{p@ $$9} repeated ten times, except that @code{show 5717values} does not change the history. 5718 5719@item show values @var{n} 5720Print ten history values centered on history item number @var{n}. 5721 5722@item show values + 5723Print ten history values just after the values last printed. If no more 5724values are available, @code{show values +} produces no display. 5725@end table 5726 5727Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the 5728same effect as @samp{show values +}. 5729 5730@node Convenience Vars 5731@section Convenience variables 5732 5733@cindex convenience variables 5734@value{GDBN} provides @dfn{convenience variables} that you can use within 5735@value{GDBN} to hold on to a value and refer to it later. These variables 5736exist entirely within @value{GDBN}; they are not part of your program, and 5737setting a convenience variable has no direct effect on further execution 5738of your program. That is why you can use them freely. 5739 5740Convenience variables are prefixed with @samp{$}. Any name preceded by 5741@samp{$} can be used for a convenience variable, unless it is one of 5742the predefined machine-specific register names (@pxref{Registers, ,Registers}). 5743(Value history references, in contrast, are @emph{numbers} preceded 5744by @samp{$}. @xref{Value History, ,Value history}.) 5745 5746You can save a value in a convenience variable with an assignment 5747expression, just as you would set a variable in your program. 5748For example: 5749 5750@smallexample 5751set $foo = *object_ptr 5752@end smallexample 5753 5754@noindent 5755would save in @code{$foo} the value contained in the object pointed to by 5756@code{object_ptr}. 5757 5758Using a convenience variable for the first time creates it, but its 5759value is @code{void} until you assign a new value. You can alter the 5760value with another assignment at any time. 5761 5762Convenience variables have no fixed types. You can assign a convenience 5763variable any type of value, including structures and arrays, even if 5764that variable already has a value of a different type. The convenience 5765variable, when used as an expression, has the type of its current value. 5766 5767@table @code 5768@kindex show convenience 5769@item show convenience 5770Print a list of convenience variables used so far, and their values. 5771Abbreviated @code{show conv}. 5772@end table 5773 5774One of the ways to use a convenience variable is as a counter to be 5775incremented or a pointer to be advanced. For example, to print 5776a field from successive elements of an array of structures: 5777 5778@smallexample 5779set $i = 0 5780print bar[$i++]->contents 5781@end smallexample 5782 5783@noindent 5784Repeat that command by typing @key{RET}. 5785 5786Some convenience variables are created automatically by @value{GDBN} and given 5787values likely to be useful. 5788 5789@table @code 5790@vindex $_@r{, convenience variable} 5791@item $_ 5792The variable @code{$_} is automatically set by the @code{x} command to 5793the last address examined (@pxref{Memory, ,Examining memory}). Other 5794commands which provide a default address for @code{x} to examine also 5795set @code{$_} to that address; these commands include @code{info line} 5796and @code{info breakpoint}. The type of @code{$_} is @code{void *} 5797except when set by the @code{x} command, in which case it is a pointer 5798to the type of @code{$__}. 5799 5800@vindex $__@r{, convenience variable} 5801@item $__ 5802The variable @code{$__} is automatically set by the @code{x} command 5803to the value found in the last address examined. Its type is chosen 5804to match the format in which the data was printed. 5805 5806@item $_exitcode 5807@vindex $_exitcode@r{, convenience variable} 5808The variable @code{$_exitcode} is automatically set to the exit code when 5809the program being debugged terminates. 5810@end table 5811 5812On HP-UX systems, if you refer to a function or variable name that 5813begins with a dollar sign, @value{GDBN} searches for a user or system 5814name first, before it searches for a convenience variable. 5815 5816@node Registers 5817@section Registers 5818 5819@cindex registers 5820You can refer to machine register contents, in expressions, as variables 5821with names starting with @samp{$}. The names of registers are different 5822for each machine; use @code{info registers} to see the names used on 5823your machine. 5824 5825@table @code 5826@kindex info registers 5827@item info registers 5828Print the names and values of all registers except floating-point 5829and vector registers (in the selected stack frame). 5830 5831@kindex info all-registers 5832@cindex floating point registers 5833@item info all-registers 5834Print the names and values of all registers, including floating-point 5835and vector registers (in the selected stack frame). 5836 5837@item info registers @var{regname} @dots{} 5838Print the @dfn{relativized} value of each specified register @var{regname}. 5839As discussed in detail below, register values are normally relative to 5840the selected stack frame. @var{regname} may be any register name valid on 5841the machine you are using, with or without the initial @samp{$}. 5842@end table 5843 5844@value{GDBN} has four ``standard'' register names that are available (in 5845expressions) on most machines---whenever they do not conflict with an 5846architecture's canonical mnemonics for registers. The register names 5847@code{$pc} and @code{$sp} are used for the program counter register and 5848the stack pointer. @code{$fp} is used for a register that contains a 5849pointer to the current stack frame, and @code{$ps} is used for a 5850register that contains the processor status. For example, 5851you could print the program counter in hex with 5852 5853@smallexample 5854p/x $pc 5855@end smallexample 5856 5857@noindent 5858or print the instruction to be executed next with 5859 5860@smallexample 5861x/i $pc 5862@end smallexample 5863 5864@noindent 5865or add four to the stack pointer@footnote{This is a way of removing 5866one word from the stack, on machines where stacks grow downward in 5867memory (most machines, nowadays). This assumes that the innermost 5868stack frame is selected; setting @code{$sp} is not allowed when other 5869stack frames are selected. To pop entire frames off the stack, 5870regardless of machine architecture, use @code{return}; 5871see @ref{Returning, ,Returning from a function}.} with 5872 5873@smallexample 5874set $sp += 4 5875@end smallexample 5876 5877Whenever possible, these four standard register names are available on 5878your machine even though the machine has different canonical mnemonics, 5879so long as there is no conflict. The @code{info registers} command 5880shows the canonical names. For example, on the SPARC, @code{info 5881registers} displays the processor status register as @code{$psr} but you 5882can also refer to it as @code{$ps}; and on x86-based machines @code{$ps} 5883is an alias for the @sc{eflags} register. 5884 5885@value{GDBN} always considers the contents of an ordinary register as an 5886integer when the register is examined in this way. Some machines have 5887special registers which can hold nothing but floating point; these 5888registers are considered to have floating point values. There is no way 5889to refer to the contents of an ordinary register as floating point value 5890(although you can @emph{print} it as a floating point value with 5891@samp{print/f $@var{regname}}). 5892 5893Some registers have distinct ``raw'' and ``virtual'' data formats. This 5894means that the data format in which the register contents are saved by 5895the operating system is not the same one that your program normally 5896sees. For example, the registers of the 68881 floating point 5897coprocessor are always saved in ``extended'' (raw) format, but all C 5898programs expect to work with ``double'' (virtual) format. In such 5899cases, @value{GDBN} normally works with the virtual format only (the format 5900that makes sense for your program), but the @code{info registers} command 5901prints the data in both formats. 5902 5903Normally, register values are relative to the selected stack frame 5904(@pxref{Selection, ,Selecting a frame}). This means that you get the 5905value that the register would contain if all stack frames farther in 5906were exited and their saved registers restored. In order to see the 5907true contents of hardware registers, you must select the innermost 5908frame (with @samp{frame 0}). 5909 5910However, @value{GDBN} must deduce where registers are saved, from the machine 5911code generated by your compiler. If some registers are not saved, or if 5912@value{GDBN} is unable to locate the saved registers, the selected stack 5913frame makes no difference. 5914 5915@node Floating Point Hardware 5916@section Floating point hardware 5917@cindex floating point 5918 5919Depending on the configuration, @value{GDBN} may be able to give 5920you more information about the status of the floating point hardware. 5921 5922@table @code 5923@kindex info float 5924@item info float 5925Display hardware-dependent information about the floating 5926point unit. The exact contents and layout vary depending on the 5927floating point chip. Currently, @samp{info float} is supported on 5928the ARM and x86 machines. 5929@end table 5930 5931@node Vector Unit 5932@section Vector Unit 5933@cindex vector unit 5934 5935Depending on the configuration, @value{GDBN} may be able to give you 5936more information about the status of the vector unit. 5937 5938@table @code 5939@kindex info vector 5940@item info vector 5941Display information about the vector unit. The exact contents and 5942layout vary depending on the hardware. 5943@end table 5944 5945@node Auxiliary Vector 5946@section Operating system auxiliary vector 5947@cindex auxiliary vector 5948@cindex vector, auxiliary 5949 5950Some operating systems supply an @dfn{auxiliary vector} to programs at 5951startup. This is akin to the arguments and environment that you 5952specify for a program, but contains a system-dependent variety of 5953binary values that tell system libraries important details about the 5954hardware, operating system, and process. Each value's purpose is 5955identified by an integer tag; the meanings are well-known but system-specific. 5956Depending on the configuration and operating system facilities, 5957@value{GDBN} may be able to show you this information. 5958 5959@table @code 5960@kindex info auxv 5961@item info auxv 5962Display the auxiliary vector of the inferior, which can be either a 5963live process or a core dump file. @value{GDBN} prints each tag value 5964numerically, and also shows names and text descriptions for recognized 5965tags. Some values in the vector are numbers, some bit masks, and some 5966pointers to strings or other data. @value{GDBN} displays each value in the 5967most appropriate form for a recognized tag, and in hexadecimal for 5968an unrecognized tag. 5969@end table 5970 5971@node Memory Region Attributes 5972@section Memory region attributes 5973@cindex memory region attributes 5974 5975@dfn{Memory region attributes} allow you to describe special handling 5976required by regions of your target's memory. @value{GDBN} uses attributes 5977to determine whether to allow certain types of memory accesses; whether to 5978use specific width accesses; and whether to cache target memory. 5979 5980Defined memory regions can be individually enabled and disabled. When a 5981memory region is disabled, @value{GDBN} uses the default attributes when 5982accessing memory in that region. Similarly, if no memory regions have 5983been defined, @value{GDBN} uses the default attributes when accessing 5984all memory. 5985 5986When a memory region is defined, it is given a number to identify it; 5987to enable, disable, or remove a memory region, you specify that number. 5988 5989@table @code 5990@kindex mem 5991@item mem @var{lower} @var{upper} @var{attributes}@dots{} 5992Define memory region bounded by @var{lower} and @var{upper} with 5993attributes @var{attributes}@dots{}. Note that @var{upper} == 0 is a 5994special case: it is treated as the the target's maximum memory address. 5995(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.) 5996 5997@kindex delete mem 5998@item delete mem @var{nums}@dots{} 5999Remove memory regions @var{nums}@dots{}. 6000 6001@kindex disable mem 6002@item disable mem @var{nums}@dots{} 6003Disable memory regions @var{nums}@dots{}. 6004A disabled memory region is not forgotten. 6005It may be enabled again later. 6006 6007@kindex enable mem 6008@item enable mem @var{nums}@dots{} 6009Enable memory regions @var{nums}@dots{}. 6010 6011@kindex info mem 6012@item info mem 6013Print a table of all defined memory regions, with the following columns 6014for each region. 6015 6016@table @emph 6017@item Memory Region Number 6018@item Enabled or Disabled. 6019Enabled memory regions are marked with @samp{y}. 6020Disabled memory regions are marked with @samp{n}. 6021 6022@item Lo Address 6023The address defining the inclusive lower bound of the memory region. 6024 6025@item Hi Address 6026The address defining the exclusive upper bound of the memory region. 6027 6028@item Attributes 6029The list of attributes set for this memory region. 6030@end table 6031@end table 6032 6033 6034@subsection Attributes 6035 6036@subsubsection Memory Access Mode 6037The access mode attributes set whether @value{GDBN} may make read or 6038write accesses to a memory region. 6039 6040While these attributes prevent @value{GDBN} from performing invalid 6041memory accesses, they do nothing to prevent the target system, I/O DMA, 6042etc. from accessing memory. 6043 6044@table @code 6045@item ro 6046Memory is read only. 6047@item wo 6048Memory is write only. 6049@item rw 6050Memory is read/write. This is the default. 6051@end table 6052 6053@subsubsection Memory Access Size 6054The acccess size attributes tells @value{GDBN} to use specific sized 6055accesses in the memory region. Often memory mapped device registers 6056require specific sized accesses. If no access size attribute is 6057specified, @value{GDBN} may use accesses of any size. 6058 6059@table @code 6060@item 8 6061Use 8 bit memory accesses. 6062@item 16 6063Use 16 bit memory accesses. 6064@item 32 6065Use 32 bit memory accesses. 6066@item 64 6067Use 64 bit memory accesses. 6068@end table 6069 6070@c @subsubsection Hardware/Software Breakpoints 6071@c The hardware/software breakpoint attributes set whether @value{GDBN} 6072@c will use hardware or software breakpoints for the internal breakpoints 6073@c used by the step, next, finish, until, etc. commands. 6074@c 6075@c @table @code 6076@c @item hwbreak 6077@c Always use hardware breakpoints 6078@c @item swbreak (default) 6079@c @end table 6080 6081@subsubsection Data Cache 6082The data cache attributes set whether @value{GDBN} will cache target 6083memory. While this generally improves performance by reducing debug 6084protocol overhead, it can lead to incorrect results because @value{GDBN} 6085does not know about volatile variables or memory mapped device 6086registers. 6087 6088@table @code 6089@item cache 6090Enable @value{GDBN} to cache target memory. 6091@item nocache 6092Disable @value{GDBN} from caching target memory. This is the default. 6093@end table 6094 6095@c @subsubsection Memory Write Verification 6096@c The memory write verification attributes set whether @value{GDBN} 6097@c will re-reads data after each write to verify the write was successful. 6098@c 6099@c @table @code 6100@c @item verify 6101@c @item noverify (default) 6102@c @end table 6103 6104@node Dump/Restore Files 6105@section Copy between memory and a file 6106@cindex dump/restore files 6107@cindex append data to a file 6108@cindex dump data to a file 6109@cindex restore data from a file 6110 6111You can use the commands @code{dump}, @code{append}, and 6112@code{restore} to copy data between target memory and a file. The 6113@code{dump} and @code{append} commands write data to a file, and the 6114@code{restore} command reads data from a file back into the inferior's 6115memory. Files may be in binary, Motorola S-record, Intel hex, or 6116Tektronix Hex format; however, @value{GDBN} can only append to binary 6117files. 6118 6119@table @code 6120 6121@kindex dump 6122@item dump @r{[}@var{format}@r{]} memory @var{filename} @var{start_addr} @var{end_addr} 6123@itemx dump @r{[}@var{format}@r{]} value @var{filename} @var{expr} 6124Dump the contents of memory from @var{start_addr} to @var{end_addr}, 6125or the value of @var{expr}, to @var{filename} in the given format. 6126 6127The @var{format} parameter may be any one of: 6128@table @code 6129@item binary 6130Raw binary form. 6131@item ihex 6132Intel hex format. 6133@item srec 6134Motorola S-record format. 6135@item tekhex 6136Tektronix Hex format. 6137@end table 6138 6139@value{GDBN} uses the same definitions of these formats as the 6140@sc{gnu} binary utilities, like @samp{objdump} and @samp{objcopy}. If 6141@var{format} is omitted, @value{GDBN} dumps the data in raw binary 6142form. 6143 6144@kindex append 6145@item append @r{[}binary@r{]} memory @var{filename} @var{start_addr} @var{end_addr} 6146@itemx append @r{[}binary@r{]} value @var{filename} @var{expr} 6147Append the contents of memory from @var{start_addr} to @var{end_addr}, 6148or the value of @var{expr}, to @var{filename}, in raw binary form. 6149(@value{GDBN} can only append data to files in raw binary form.) 6150 6151@kindex restore 6152@item restore @var{filename} @r{[}binary@r{]} @var{bias} @var{start} @var{end} 6153Restore the contents of file @var{filename} into memory. The 6154@code{restore} command can automatically recognize any known @sc{bfd} 6155file format, except for raw binary. To restore a raw binary file you 6156must specify the optional keyword @code{binary} after the filename. 6157 6158If @var{bias} is non-zero, its value will be added to the addresses 6159contained in the file. Binary files always start at address zero, so 6160they will be restored at address @var{bias}. Other bfd files have 6161a built-in location; they will be restored at offset @var{bias} 6162from that location. 6163 6164If @var{start} and/or @var{end} are non-zero, then only data between 6165file offset @var{start} and file offset @var{end} will be restored. 6166These offsets are relative to the addresses in the file, before 6167the @var{bias} argument is applied. 6168 6169@end table 6170 6171@node Character Sets 6172@section Character Sets 6173@cindex character sets 6174@cindex charset 6175@cindex translating between character sets 6176@cindex host character set 6177@cindex target character set 6178 6179If the program you are debugging uses a different character set to 6180represent characters and strings than the one @value{GDBN} uses itself, 6181@value{GDBN} can automatically translate between the character sets for 6182you. The character set @value{GDBN} uses we call the @dfn{host 6183character set}; the one the inferior program uses we call the 6184@dfn{target character set}. 6185 6186For example, if you are running @value{GDBN} on a @sc{gnu}/Linux system, which 6187uses the ISO Latin 1 character set, but you are using @value{GDBN}'s 6188remote protocol (@pxref{Remote,Remote Debugging}) to debug a program 6189running on an IBM mainframe, which uses the @sc{ebcdic} character set, 6190then the host character set is Latin-1, and the target character set is 6191@sc{ebcdic}. If you give @value{GDBN} the command @code{set 6192target-charset EBCDIC-US}, then @value{GDBN} translates between 6193@sc{ebcdic} and Latin 1 as you print character or string values, or use 6194character and string literals in expressions. 6195 6196@value{GDBN} has no way to automatically recognize which character set 6197the inferior program uses; you must tell it, using the @code{set 6198target-charset} command, described below. 6199 6200Here are the commands for controlling @value{GDBN}'s character set 6201support: 6202 6203@table @code 6204@item set target-charset @var{charset} 6205@kindex set target-charset 6206Set the current target character set to @var{charset}. We list the 6207character set names @value{GDBN} recognizes below, but if you type 6208@code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} will 6209list the target character sets it supports. 6210@end table 6211 6212@table @code 6213@item set host-charset @var{charset} 6214@kindex set host-charset 6215Set the current host character set to @var{charset}. 6216 6217By default, @value{GDBN} uses a host character set appropriate to the 6218system it is running on; you can override that default using the 6219@code{set host-charset} command. 6220 6221@value{GDBN} can only use certain character sets as its host character 6222set. We list the character set names @value{GDBN} recognizes below, and 6223indicate which can be host character sets, but if you type 6224@code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} will 6225list the host character sets it supports. 6226 6227@item set charset @var{charset} 6228@kindex set charset 6229Set the current host and target character sets to @var{charset}. As 6230above, if you type @code{set charset} followed by @key{TAB}@key{TAB}, 6231@value{GDBN} will list the name of the character sets that can be used 6232for both host and target. 6233 6234 6235@item show charset 6236@kindex show charset 6237Show the names of the current host and target charsets. 6238 6239@itemx show host-charset 6240@kindex show host-charset 6241Show the name of the current host charset. 6242 6243@itemx show target-charset 6244@kindex show target-charset 6245Show the name of the current target charset. 6246 6247@end table 6248 6249@value{GDBN} currently includes support for the following character 6250sets: 6251 6252@table @code 6253 6254@item ASCII 6255@cindex ASCII character set 6256Seven-bit U.S. @sc{ascii}. @value{GDBN} can use this as its host 6257character set. 6258 6259@item ISO-8859-1 6260@cindex ISO 8859-1 character set 6261@cindex ISO Latin 1 character set 6262The ISO Latin 1 character set. This extends @sc{ascii} with accented 6263characters needed for French, German, and Spanish. @value{GDBN} can use 6264this as its host character set. 6265 6266@item EBCDIC-US 6267@itemx IBM1047 6268@cindex EBCDIC character set 6269@cindex IBM1047 character set 6270Variants of the @sc{ebcdic} character set, used on some of IBM's 6271mainframe operating systems. (@sc{gnu}/Linux on the S/390 uses U.S. @sc{ascii}.) 6272@value{GDBN} cannot use these as its host character set. 6273 6274@end table 6275 6276Note that these are all single-byte character sets. More work inside 6277GDB is needed to support multi-byte or variable-width character 6278encodings, like the UTF-8 and UCS-2 encodings of Unicode. 6279 6280Here is an example of @value{GDBN}'s character set support in action. 6281Assume that the following source code has been placed in the file 6282@file{charset-test.c}: 6283 6284@smallexample 6285#include <stdio.h> 6286 6287char ascii_hello[] 6288 = @{72, 101, 108, 108, 111, 44, 32, 119, 6289 111, 114, 108, 100, 33, 10, 0@}; 6290char ibm1047_hello[] 6291 = @{200, 133, 147, 147, 150, 107, 64, 166, 6292 150, 153, 147, 132, 90, 37, 0@}; 6293 6294main () 6295@{ 6296 printf ("Hello, world!\n"); 6297@} 6298@end smallexample 6299 6300In this program, @code{ascii_hello} and @code{ibm1047_hello} are arrays 6301containing the string @samp{Hello, world!} followed by a newline, 6302encoded in the @sc{ascii} and @sc{ibm1047} character sets. 6303 6304We compile the program, and invoke the debugger on it: 6305 6306@smallexample 6307$ gcc -g charset-test.c -o charset-test 6308$ gdb -nw charset-test 6309GNU gdb 2001-12-19-cvs 6310Copyright 2001 Free Software Foundation, Inc. 6311@dots{} 6312(@value{GDBP}) 6313@end smallexample 6314 6315We can use the @code{show charset} command to see what character sets 6316@value{GDBN} is currently using to interpret and display characters and 6317strings: 6318 6319@smallexample 6320(@value{GDBP}) show charset 6321The current host and target character set is `ISO-8859-1'. 6322(@value{GDBP}) 6323@end smallexample 6324 6325For the sake of printing this manual, let's use @sc{ascii} as our 6326initial character set: 6327@smallexample 6328(@value{GDBP}) set charset ASCII 6329(@value{GDBP}) show charset 6330The current host and target character set is `ASCII'. 6331(@value{GDBP}) 6332@end smallexample 6333 6334Let's assume that @sc{ascii} is indeed the correct character set for our 6335host system --- in other words, let's assume that if @value{GDBN} prints 6336characters using the @sc{ascii} character set, our terminal will display 6337them properly. Since our current target character set is also 6338@sc{ascii}, the contents of @code{ascii_hello} print legibly: 6339 6340@smallexample 6341(@value{GDBP}) print ascii_hello 6342$1 = 0x401698 "Hello, world!\n" 6343(@value{GDBP}) print ascii_hello[0] 6344$2 = 72 'H' 6345(@value{GDBP}) 6346@end smallexample 6347 6348@value{GDBN} uses the target character set for character and string 6349literals you use in expressions: 6350 6351@smallexample 6352(@value{GDBP}) print '+' 6353$3 = 43 '+' 6354(@value{GDBP}) 6355@end smallexample 6356 6357The @sc{ascii} character set uses the number 43 to encode the @samp{+} 6358character. 6359 6360@value{GDBN} relies on the user to tell it which character set the 6361target program uses. If we print @code{ibm1047_hello} while our target 6362character set is still @sc{ascii}, we get jibberish: 6363 6364@smallexample 6365(@value{GDBP}) print ibm1047_hello 6366$4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%" 6367(@value{GDBP}) print ibm1047_hello[0] 6368$5 = 200 '\310' 6369(@value{GDBP}) 6370@end smallexample 6371 6372If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB}, 6373@value{GDBN} tells us the character sets it supports: 6374 6375@smallexample 6376(@value{GDBP}) set target-charset 6377ASCII EBCDIC-US IBM1047 ISO-8859-1 6378(@value{GDBP}) set target-charset 6379@end smallexample 6380 6381We can select @sc{ibm1047} as our target character set, and examine the 6382program's strings again. Now the @sc{ascii} string is wrong, but 6383@value{GDBN} translates the contents of @code{ibm1047_hello} from the 6384target character set, @sc{ibm1047}, to the host character set, 6385@sc{ascii}, and they display correctly: 6386 6387@smallexample 6388(@value{GDBP}) set target-charset IBM1047 6389(@value{GDBP}) show charset 6390The current host character set is `ASCII'. 6391The current target character set is `IBM1047'. 6392(@value{GDBP}) print ascii_hello 6393$6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" 6394(@value{GDBP}) print ascii_hello[0] 6395$7 = 72 '\110' 6396(@value{GDBP}) print ibm1047_hello 6397$8 = 0x4016a8 "Hello, world!\n" 6398(@value{GDBP}) print ibm1047_hello[0] 6399$9 = 200 'H' 6400(@value{GDBP}) 6401@end smallexample 6402 6403As above, @value{GDBN} uses the target character set for character and 6404string literals you use in expressions: 6405 6406@smallexample 6407(@value{GDBP}) print '+' 6408$10 = 78 '+' 6409(@value{GDBP}) 6410@end smallexample 6411 6412The @sc{ibm1047} character set uses the number 78 to encode the @samp{+} 6413character. 6414 6415 6416@node Macros 6417@chapter C Preprocessor Macros 6418 6419Some languages, such as C and C@t{++}, provide a way to define and invoke 6420``preprocessor macros'' which expand into strings of tokens. 6421@value{GDBN} can evaluate expressions containing macro invocations, show 6422the result of macro expansion, and show a macro's definition, including 6423where it was defined. 6424 6425You may need to compile your program specially to provide @value{GDBN} 6426with information about preprocessor macros. Most compilers do not 6427include macros in their debugging information, even when you compile 6428with the @option{-g} flag. @xref{Compilation}. 6429 6430A program may define a macro at one point, remove that definition later, 6431and then provide a different definition after that. Thus, at different 6432points in the program, a macro may have different definitions, or have 6433no definition at all. If there is a current stack frame, @value{GDBN} 6434uses the macros in scope at that frame's source code line. Otherwise, 6435@value{GDBN} uses the macros in scope at the current listing location; 6436see @ref{List}. 6437 6438At the moment, @value{GDBN} does not support the @code{##} 6439token-splicing operator, the @code{#} stringification operator, or 6440variable-arity macros. 6441 6442Whenever @value{GDBN} evaluates an expression, it always expands any 6443macro invocations present in the expression. @value{GDBN} also provides 6444the following commands for working with macros explicitly. 6445 6446@table @code 6447 6448@kindex macro expand 6449@cindex macro expansion, showing the results of preprocessor 6450@cindex preprocessor macro expansion, showing the results of 6451@cindex expanding preprocessor macros 6452@item macro expand @var{expression} 6453@itemx macro exp @var{expression} 6454Show the results of expanding all preprocessor macro invocations in 6455@var{expression}. Since @value{GDBN} simply expands macros, but does 6456not parse the result, @var{expression} need not be a valid expression; 6457it can be any string of tokens. 6458 6459@item macro expand-once @var{expression} 6460@itemx macro exp1 @var{expression} 6461@cindex expand macro once 6462@i{(This command is not yet implemented.)} Show the results of 6463expanding those preprocessor macro invocations that appear explicitly in 6464@var{expression}. Macro invocations appearing in that expansion are 6465left unchanged. This command allows you to see the effect of a 6466particular macro more clearly, without being confused by further 6467expansions. Since @value{GDBN} simply expands macros, but does not 6468parse the result, @var{expression} need not be a valid expression; it 6469can be any string of tokens. 6470 6471@kindex info macro 6472@cindex macro definition, showing 6473@cindex definition, showing a macro's 6474@item info macro @var{macro} 6475Show the definition of the macro named @var{macro}, and describe the 6476source location where that definition was established. 6477 6478@kindex macro define 6479@cindex user-defined macros 6480@cindex defining macros interactively 6481@cindex macros, user-defined 6482@item macro define @var{macro} @var{replacement-list} 6483@itemx macro define @var{macro}(@var{arglist}) @var{replacement-list} 6484@i{(This command is not yet implemented.)} Introduce a definition for a 6485preprocessor macro named @var{macro}, invocations of which are replaced 6486by the tokens given in @var{replacement-list}. The first form of this 6487command defines an ``object-like'' macro, which takes no arguments; the 6488second form defines a ``function-like'' macro, which takes the arguments 6489given in @var{arglist}. 6490 6491A definition introduced by this command is in scope in every expression 6492evaluated in @value{GDBN}, until it is removed with the @command{macro 6493undef} command, described below. The definition overrides all 6494definitions for @var{macro} present in the program being debugged, as 6495well as any previous user-supplied definition. 6496 6497@kindex macro undef 6498@item macro undef @var{macro} 6499@i{(This command is not yet implemented.)} Remove any user-supplied 6500definition for the macro named @var{macro}. This command only affects 6501definitions provided with the @command{macro define} command, described 6502above; it cannot remove definitions present in the program being 6503debugged. 6504 6505@end table 6506 6507@cindex macros, example of debugging with 6508Here is a transcript showing the above commands in action. First, we 6509show our source files: 6510 6511@smallexample 6512$ cat sample.c 6513#include <stdio.h> 6514#include "sample.h" 6515 6516#define M 42 6517#define ADD(x) (M + x) 6518 6519main () 6520@{ 6521#define N 28 6522 printf ("Hello, world!\n"); 6523#undef N 6524 printf ("We're so creative.\n"); 6525#define N 1729 6526 printf ("Goodbye, world!\n"); 6527@} 6528$ cat sample.h 6529#define Q < 6530$ 6531@end smallexample 6532 6533Now, we compile the program using the @sc{gnu} C compiler, @value{NGCC}. 6534We pass the @option{-gdwarf-2} and @option{-g3} flags to ensure the 6535compiler includes information about preprocessor macros in the debugging 6536information. 6537 6538@smallexample 6539$ gcc -gdwarf-2 -g3 sample.c -o sample 6540$ 6541@end smallexample 6542 6543Now, we start @value{GDBN} on our sample program: 6544 6545@smallexample 6546$ gdb -nw sample 6547GNU gdb 2002-05-06-cvs 6548Copyright 2002 Free Software Foundation, Inc. 6549GDB is free software, @dots{} 6550(@value{GDBP}) 6551@end smallexample 6552 6553We can expand macros and examine their definitions, even when the 6554program is not running. @value{GDBN} uses the current listing position 6555to decide which macro definitions are in scope: 6556 6557@smallexample 6558(@value{GDBP}) list main 65593 65604 #define M 42 65615 #define ADD(x) (M + x) 65626 65637 main () 65648 @{ 65659 #define N 28 656610 printf ("Hello, world!\n"); 656711 #undef N 656812 printf ("We're so creative.\n"); 6569(@value{GDBP}) info macro ADD 6570Defined at /home/jimb/gdb/macros/play/sample.c:5 6571#define ADD(x) (M + x) 6572(@value{GDBP}) info macro Q 6573Defined at /home/jimb/gdb/macros/play/sample.h:1 6574 included at /home/jimb/gdb/macros/play/sample.c:2 6575#define Q < 6576(@value{GDBP}) macro expand ADD(1) 6577expands to: (42 + 1) 6578(@value{GDBP}) macro expand-once ADD(1) 6579expands to: once (M + 1) 6580(@value{GDBP}) 6581@end smallexample 6582 6583In the example above, note that @command{macro expand-once} expands only 6584the macro invocation explicit in the original text --- the invocation of 6585@code{ADD} --- but does not expand the invocation of the macro @code{M}, 6586which was introduced by @code{ADD}. 6587 6588Once the program is running, GDB uses the macro definitions in force at 6589the source line of the current stack frame: 6590 6591@smallexample 6592(@value{GDBP}) break main 6593Breakpoint 1 at 0x8048370: file sample.c, line 10. 6594(@value{GDBP}) run 6595Starting program: /home/jimb/gdb/macros/play/sample 6596 6597Breakpoint 1, main () at sample.c:10 659810 printf ("Hello, world!\n"); 6599(@value{GDBP}) 6600@end smallexample 6601 6602At line 10, the definition of the macro @code{N} at line 9 is in force: 6603 6604@smallexample 6605(@value{GDBP}) info macro N 6606Defined at /home/jimb/gdb/macros/play/sample.c:9 6607#define N 28 6608(@value{GDBP}) macro expand N Q M 6609expands to: 28 < 42 6610(@value{GDBP}) print N Q M 6611$1 = 1 6612(@value{GDBP}) 6613@end smallexample 6614 6615As we step over directives that remove @code{N}'s definition, and then 6616give it a new definition, @value{GDBN} finds the definition (or lack 6617thereof) in force at each point: 6618 6619@smallexample 6620(@value{GDBP}) next 6621Hello, world! 662212 printf ("We're so creative.\n"); 6623(@value{GDBP}) info macro N 6624The symbol `N' has no definition as a C/C++ preprocessor macro 6625at /home/jimb/gdb/macros/play/sample.c:12 6626(@value{GDBP}) next 6627We're so creative. 662814 printf ("Goodbye, world!\n"); 6629(@value{GDBP}) info macro N 6630Defined at /home/jimb/gdb/macros/play/sample.c:13 6631#define N 1729 6632(@value{GDBP}) macro expand N Q M 6633expands to: 1729 < 42 6634(@value{GDBP}) print N Q M 6635$2 = 0 6636(@value{GDBP}) 6637@end smallexample 6638 6639 6640@node Tracepoints 6641@chapter Tracepoints 6642@c This chapter is based on the documentation written by Michael 6643@c Snyder, David Taylor, Jim Blandy, and Elena Zannoni. 6644 6645@cindex tracepoints 6646In some applications, it is not feasible for the debugger to interrupt 6647the program's execution long enough for the developer to learn 6648anything helpful about its behavior. If the program's correctness 6649depends on its real-time behavior, delays introduced by a debugger 6650might cause the program to change its behavior drastically, or perhaps 6651fail, even when the code itself is correct. It is useful to be able 6652to observe the program's behavior without interrupting it. 6653 6654Using @value{GDBN}'s @code{trace} and @code{collect} commands, you can 6655specify locations in the program, called @dfn{tracepoints}, and 6656arbitrary expressions to evaluate when those tracepoints are reached. 6657Later, using the @code{tfind} command, you can examine the values 6658those expressions had when the program hit the tracepoints. The 6659expressions may also denote objects in memory---structures or arrays, 6660for example---whose values @value{GDBN} should record; while visiting 6661a particular tracepoint, you may inspect those objects as if they were 6662in memory at that moment. However, because @value{GDBN} records these 6663values without interacting with you, it can do so quickly and 6664unobtrusively, hopefully not disturbing the program's behavior. 6665 6666The tracepoint facility is currently available only for remote 6667targets. @xref{Targets}. In addition, your remote target must know how 6668to collect trace data. This functionality is implemented in the remote 6669stub; however, none of the stubs distributed with @value{GDBN} support 6670tracepoints as of this writing. 6671 6672This chapter describes the tracepoint commands and features. 6673 6674@menu 6675* Set Tracepoints:: 6676* Analyze Collected Data:: 6677* Tracepoint Variables:: 6678@end menu 6679 6680@node Set Tracepoints 6681@section Commands to Set Tracepoints 6682 6683Before running such a @dfn{trace experiment}, an arbitrary number of 6684tracepoints can be set. Like a breakpoint (@pxref{Set Breaks}), a 6685tracepoint has a number assigned to it by @value{GDBN}. Like with 6686breakpoints, tracepoint numbers are successive integers starting from 6687one. Many of the commands associated with tracepoints take the 6688tracepoint number as their argument, to identify which tracepoint to 6689work on. 6690 6691For each tracepoint, you can specify, in advance, some arbitrary set 6692of data that you want the target to collect in the trace buffer when 6693it hits that tracepoint. The collected data can include registers, 6694local variables, or global data. Later, you can use @value{GDBN} 6695commands to examine the values these data had at the time the 6696tracepoint was hit. 6697 6698This section describes commands to set tracepoints and associated 6699conditions and actions. 6700 6701@menu 6702* Create and Delete Tracepoints:: 6703* Enable and Disable Tracepoints:: 6704* Tracepoint Passcounts:: 6705* Tracepoint Actions:: 6706* Listing Tracepoints:: 6707* Starting and Stopping Trace Experiment:: 6708@end menu 6709 6710@node Create and Delete Tracepoints 6711@subsection Create and Delete Tracepoints 6712 6713@table @code 6714@cindex set tracepoint 6715@kindex trace 6716@item trace 6717The @code{trace} command is very similar to the @code{break} command. 6718Its argument can be a source line, a function name, or an address in 6719the target program. @xref{Set Breaks}. The @code{trace} command 6720defines a tracepoint, which is a point in the target program where the 6721debugger will briefly stop, collect some data, and then allow the 6722program to continue. Setting a tracepoint or changing its commands 6723doesn't take effect until the next @code{tstart} command; thus, you 6724cannot change the tracepoint attributes once a trace experiment is 6725running. 6726 6727Here are some examples of using the @code{trace} command: 6728 6729@smallexample 6730(@value{GDBP}) @b{trace foo.c:121} // a source file and line number 6731 6732(@value{GDBP}) @b{trace +2} // 2 lines forward 6733 6734(@value{GDBP}) @b{trace my_function} // first source line of function 6735 6736(@value{GDBP}) @b{trace *my_function} // EXACT start address of function 6737 6738(@value{GDBP}) @b{trace *0x2117c4} // an address 6739@end smallexample 6740 6741@noindent 6742You can abbreviate @code{trace} as @code{tr}. 6743 6744@vindex $tpnum 6745@cindex last tracepoint number 6746@cindex recent tracepoint number 6747@cindex tracepoint number 6748The convenience variable @code{$tpnum} records the tracepoint number 6749of the most recently set tracepoint. 6750 6751@kindex delete tracepoint 6752@cindex tracepoint deletion 6753@item delete tracepoint @r{[}@var{num}@r{]} 6754Permanently delete one or more tracepoints. With no argument, the 6755default is to delete all tracepoints. 6756 6757Examples: 6758 6759@smallexample 6760(@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints 6761 6762(@value{GDBP}) @b{delete trace} // remove all tracepoints 6763@end smallexample 6764 6765@noindent 6766You can abbreviate this command as @code{del tr}. 6767@end table 6768 6769@node Enable and Disable Tracepoints 6770@subsection Enable and Disable Tracepoints 6771 6772@table @code 6773@kindex disable tracepoint 6774@item disable tracepoint @r{[}@var{num}@r{]} 6775Disable tracepoint @var{num}, or all tracepoints if no argument 6776@var{num} is given. A disabled tracepoint will have no effect during 6777the next trace experiment, but it is not forgotten. You can re-enable 6778a disabled tracepoint using the @code{enable tracepoint} command. 6779 6780@kindex enable tracepoint 6781@item enable tracepoint @r{[}@var{num}@r{]} 6782Enable tracepoint @var{num}, or all tracepoints. The enabled 6783tracepoints will become effective the next time a trace experiment is 6784run. 6785@end table 6786 6787@node Tracepoint Passcounts 6788@subsection Tracepoint Passcounts 6789 6790@table @code 6791@kindex passcount 6792@cindex tracepoint pass count 6793@item passcount @r{[}@var{n} @r{[}@var{num}@r{]]} 6794Set the @dfn{passcount} of a tracepoint. The passcount is a way to 6795automatically stop a trace experiment. If a tracepoint's passcount is 6796@var{n}, then the trace experiment will be automatically stopped on 6797the @var{n}'th time that tracepoint is hit. If the tracepoint number 6798@var{num} is not specified, the @code{passcount} command sets the 6799passcount of the most recently defined tracepoint. If no passcount is 6800given, the trace experiment will run until stopped explicitly by the 6801user. 6802 6803Examples: 6804 6805@smallexample 6806(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of 6807@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2} 6808 6809(@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the 6810@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// most recently defined tracepoint.} 6811(@value{GDBP}) @b{trace foo} 6812(@value{GDBP}) @b{pass 3} 6813(@value{GDBP}) @b{trace bar} 6814(@value{GDBP}) @b{pass 2} 6815(@value{GDBP}) @b{trace baz} 6816(@value{GDBP}) @b{pass 1} // Stop tracing when foo has been 6817@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// executed 3 times OR when bar has} 6818@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// been executed 2 times} 6819@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// OR when baz has been executed 1 time.} 6820@end smallexample 6821@end table 6822 6823@node Tracepoint Actions 6824@subsection Tracepoint Action Lists 6825 6826@table @code 6827@kindex actions 6828@cindex tracepoint actions 6829@item actions @r{[}@var{num}@r{]} 6830This command will prompt for a list of actions to be taken when the 6831tracepoint is hit. If the tracepoint number @var{num} is not 6832specified, this command sets the actions for the one that was most 6833recently defined (so that you can define a tracepoint and then say 6834@code{actions} without bothering about its number). You specify the 6835actions themselves on the following lines, one action at a time, and 6836terminate the actions list with a line containing just @code{end}. So 6837far, the only defined actions are @code{collect} and 6838@code{while-stepping}. 6839 6840@cindex remove actions from a tracepoint 6841To remove all actions from a tracepoint, type @samp{actions @var{num}} 6842and follow it immediately with @samp{end}. 6843 6844@smallexample 6845(@value{GDBP}) @b{collect @var{data}} // collect some data 6846 6847(@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data 6848 6849(@value{GDBP}) @b{end} // signals the end of actions. 6850@end smallexample 6851 6852In the following example, the action list begins with @code{collect} 6853commands indicating the things to be collected when the tracepoint is 6854hit. Then, in order to single-step and collect additional data 6855following the tracepoint, a @code{while-stepping} command is used, 6856followed by the list of things to be collected while stepping. The 6857@code{while-stepping} command is terminated by its own separate 6858@code{end} command. Lastly, the action list is terminated by an 6859@code{end} command. 6860 6861@smallexample 6862(@value{GDBP}) @b{trace foo} 6863(@value{GDBP}) @b{actions} 6864Enter actions for tracepoint 1, one per line: 6865> collect bar,baz 6866> collect $regs 6867> while-stepping 12 6868 > collect $fp, $sp 6869 > end 6870end 6871@end smallexample 6872 6873@kindex collect @r{(tracepoints)} 6874@item collect @var{expr1}, @var{expr2}, @dots{} 6875Collect values of the given expressions when the tracepoint is hit. 6876This command accepts a comma-separated list of any valid expressions. 6877In addition to global, static, or local variables, the following 6878special arguments are supported: 6879 6880@table @code 6881@item $regs 6882collect all registers 6883 6884@item $args 6885collect all function arguments 6886 6887@item $locals 6888collect all local variables. 6889@end table 6890 6891You can give several consecutive @code{collect} commands, each one 6892with a single argument, or one @code{collect} command with several 6893arguments separated by commas: the effect is the same. 6894 6895The command @code{info scope} (@pxref{Symbols, info scope}) is 6896particularly useful for figuring out what data to collect. 6897 6898@kindex while-stepping @r{(tracepoints)} 6899@item while-stepping @var{n} 6900Perform @var{n} single-step traces after the tracepoint, collecting 6901new data at each step. The @code{while-stepping} command is 6902followed by the list of what to collect while stepping (followed by 6903its own @code{end} command): 6904 6905@smallexample 6906> while-stepping 12 6907 > collect $regs, myglobal 6908 > end 6909> 6910@end smallexample 6911 6912@noindent 6913You may abbreviate @code{while-stepping} as @code{ws} or 6914@code{stepping}. 6915@end table 6916 6917@node Listing Tracepoints 6918@subsection Listing Tracepoints 6919 6920@table @code 6921@kindex info tracepoints 6922@cindex information about tracepoints 6923@item info tracepoints @r{[}@var{num}@r{]} 6924Display information about the tracepoint @var{num}. If you don't specify 6925a tracepoint number, displays information about all the tracepoints 6926defined so far. For each tracepoint, the following information is 6927shown: 6928 6929@itemize @bullet 6930@item 6931its number 6932@item 6933whether it is enabled or disabled 6934@item 6935its address 6936@item 6937its passcount as given by the @code{passcount @var{n}} command 6938@item 6939its step count as given by the @code{while-stepping @var{n}} command 6940@item 6941where in the source files is the tracepoint set 6942@item 6943its action list as given by the @code{actions} command 6944@end itemize 6945 6946@smallexample 6947(@value{GDBP}) @b{info trace} 6948Num Enb Address PassC StepC What 69491 y 0x002117c4 0 0 <gdb_asm> 69502 y 0x0020dc64 0 0 in g_test at g_test.c:1375 69513 y 0x0020b1f4 0 0 in get_data at ../foo.c:41 6952(@value{GDBP}) 6953@end smallexample 6954 6955@noindent 6956This command can be abbreviated @code{info tp}. 6957@end table 6958 6959@node Starting and Stopping Trace Experiment 6960@subsection Starting and Stopping Trace Experiment 6961 6962@table @code 6963@kindex tstart 6964@cindex start a new trace experiment 6965@cindex collected data discarded 6966@item tstart 6967This command takes no arguments. It starts the trace experiment, and 6968begins collecting data. This has the side effect of discarding all 6969the data collected in the trace buffer during the previous trace 6970experiment. 6971 6972@kindex tstop 6973@cindex stop a running trace experiment 6974@item tstop 6975This command takes no arguments. It ends the trace experiment, and 6976stops collecting data. 6977 6978@strong{Note:} a trace experiment and data collection may stop 6979automatically if any tracepoint's passcount is reached 6980(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full. 6981 6982@kindex tstatus 6983@cindex status of trace data collection 6984@cindex trace experiment, status of 6985@item tstatus 6986This command displays the status of the current trace data 6987collection. 6988@end table 6989 6990Here is an example of the commands we described so far: 6991 6992@smallexample 6993(@value{GDBP}) @b{trace gdb_c_test} 6994(@value{GDBP}) @b{actions} 6995Enter actions for tracepoint #1, one per line. 6996> collect $regs,$locals,$args 6997> while-stepping 11 6998 > collect $regs 6999 > end 7000> end 7001(@value{GDBP}) @b{tstart} 7002 [time passes @dots{}] 7003(@value{GDBP}) @b{tstop} 7004@end smallexample 7005 7006 7007@node Analyze Collected Data 7008@section Using the collected data 7009 7010After the tracepoint experiment ends, you use @value{GDBN} commands 7011for examining the trace data. The basic idea is that each tracepoint 7012collects a trace @dfn{snapshot} every time it is hit and another 7013snapshot every time it single-steps. All these snapshots are 7014consecutively numbered from zero and go into a buffer, and you can 7015examine them later. The way you examine them is to @dfn{focus} on a 7016specific trace snapshot. When the remote stub is focused on a trace 7017snapshot, it will respond to all @value{GDBN} requests for memory and 7018registers by reading from the buffer which belongs to that snapshot, 7019rather than from @emph{real} memory or registers of the program being 7020debugged. This means that @strong{all} @value{GDBN} commands 7021(@code{print}, @code{info registers}, @code{backtrace}, etc.) will 7022behave as if we were currently debugging the program state as it was 7023when the tracepoint occurred. Any requests for data that are not in 7024the buffer will fail. 7025 7026@menu 7027* tfind:: How to select a trace snapshot 7028* tdump:: How to display all data for a snapshot 7029* save-tracepoints:: How to save tracepoints for a future run 7030@end menu 7031 7032@node tfind 7033@subsection @code{tfind @var{n}} 7034 7035@kindex tfind 7036@cindex select trace snapshot 7037@cindex find trace snapshot 7038The basic command for selecting a trace snapshot from the buffer is 7039@code{tfind @var{n}}, which finds trace snapshot number @var{n}, 7040counting from zero. If no argument @var{n} is given, the next 7041snapshot is selected. 7042 7043Here are the various forms of using the @code{tfind} command. 7044 7045@table @code 7046@item tfind start 7047Find the first snapshot in the buffer. This is a synonym for 7048@code{tfind 0} (since 0 is the number of the first snapshot). 7049 7050@item tfind none 7051Stop debugging trace snapshots, resume @emph{live} debugging. 7052 7053@item tfind end 7054Same as @samp{tfind none}. 7055 7056@item tfind 7057No argument means find the next trace snapshot. 7058 7059@item tfind - 7060Find the previous trace snapshot before the current one. This permits 7061retracing earlier steps. 7062 7063@item tfind tracepoint @var{num} 7064Find the next snapshot associated with tracepoint @var{num}. Search 7065proceeds forward from the last examined trace snapshot. If no 7066argument @var{num} is given, it means find the next snapshot collected 7067for the same tracepoint as the current snapshot. 7068 7069@item tfind pc @var{addr} 7070Find the next snapshot associated with the value @var{addr} of the 7071program counter. Search proceeds forward from the last examined trace 7072snapshot. If no argument @var{addr} is given, it means find the next 7073snapshot with the same value of PC as the current snapshot. 7074 7075@item tfind outside @var{addr1}, @var{addr2} 7076Find the next snapshot whose PC is outside the given range of 7077addresses. 7078 7079@item tfind range @var{addr1}, @var{addr2} 7080Find the next snapshot whose PC is between @var{addr1} and 7081@var{addr2}. @c FIXME: Is the range inclusive or exclusive? 7082 7083@item tfind line @r{[}@var{file}:@r{]}@var{n} 7084Find the next snapshot associated with the source line @var{n}. If 7085the optional argument @var{file} is given, refer to line @var{n} in 7086that source file. Search proceeds forward from the last examined 7087trace snapshot. If no argument @var{n} is given, it means find the 7088next line other than the one currently being examined; thus saying 7089@code{tfind line} repeatedly can appear to have the same effect as 7090stepping from line to line in a @emph{live} debugging session. 7091@end table 7092 7093The default arguments for the @code{tfind} commands are specifically 7094designed to make it easy to scan through the trace buffer. For 7095instance, @code{tfind} with no argument selects the next trace 7096snapshot, and @code{tfind -} with no argument selects the previous 7097trace snapshot. So, by giving one @code{tfind} command, and then 7098simply hitting @key{RET} repeatedly you can examine all the trace 7099snapshots in order. Or, by saying @code{tfind -} and then hitting 7100@key{RET} repeatedly you can examine the snapshots in reverse order. 7101The @code{tfind line} command with no argument selects the snapshot 7102for the next source line executed. The @code{tfind pc} command with 7103no argument selects the next snapshot with the same program counter 7104(PC) as the current frame. The @code{tfind tracepoint} command with 7105no argument selects the next trace snapshot collected by the same 7106tracepoint as the current one. 7107 7108In addition to letting you scan through the trace buffer manually, 7109these commands make it easy to construct @value{GDBN} scripts that 7110scan through the trace buffer and print out whatever collected data 7111you are interested in. Thus, if we want to examine the PC, FP, and SP 7112registers from each trace frame in the buffer, we can say this: 7113 7114@smallexample 7115(@value{GDBP}) @b{tfind start} 7116(@value{GDBP}) @b{while ($trace_frame != -1)} 7117> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ 7118 $trace_frame, $pc, $sp, $fp 7119> tfind 7120> end 7121 7122Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 7123Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 7124Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 7125Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 7126Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 7127Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 7128Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 7129Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 7130Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 7131Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 7132Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 7133@end smallexample 7134 7135Or, if we want to examine the variable @code{X} at each source line in 7136the buffer: 7137 7138@smallexample 7139(@value{GDBP}) @b{tfind start} 7140(@value{GDBP}) @b{while ($trace_frame != -1)} 7141> printf "Frame %d, X == %d\n", $trace_frame, X 7142> tfind line 7143> end 7144 7145Frame 0, X = 1 7146Frame 7, X = 2 7147Frame 13, X = 255 7148@end smallexample 7149 7150@node tdump 7151@subsection @code{tdump} 7152@kindex tdump 7153@cindex dump all data collected at tracepoint 7154@cindex tracepoint data, display 7155 7156This command takes no arguments. It prints all the data collected at 7157the current trace snapshot. 7158 7159@smallexample 7160(@value{GDBP}) @b{trace 444} 7161(@value{GDBP}) @b{actions} 7162Enter actions for tracepoint #2, one per line: 7163> collect $regs, $locals, $args, gdb_long_test 7164> end 7165 7166(@value{GDBP}) @b{tstart} 7167 7168(@value{GDBP}) @b{tfind line 444} 7169#0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) 7170at gdb_test.c:444 7171444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) 7172 7173(@value{GDBP}) @b{tdump} 7174Data collected at tracepoint 2, trace frame 1: 7175d0 0xc4aa0085 -995491707 7176d1 0x18 24 7177d2 0x80 128 7178d3 0x33 51 7179d4 0x71aea3d 119204413 7180d5 0x22 34 7181d6 0xe0 224 7182d7 0x380035 3670069 7183a0 0x19e24a 1696330 7184a1 0x3000668 50333288 7185a2 0x100 256 7186a3 0x322000 3284992 7187a4 0x3000698 50333336 7188a5 0x1ad3cc 1758156 7189fp 0x30bf3c 0x30bf3c 7190sp 0x30bf34 0x30bf34 7191ps 0x0 0 7192pc 0x20b2c8 0x20b2c8 7193fpcontrol 0x0 0 7194fpstatus 0x0 0 7195fpiaddr 0x0 0 7196p = 0x20e5b4 "gdb-test" 7197p1 = (void *) 0x11 7198p2 = (void *) 0x22 7199p3 = (void *) 0x33 7200p4 = (void *) 0x44 7201p5 = (void *) 0x55 7202p6 = (void *) 0x66 7203gdb_long_test = 17 '\021' 7204 7205(@value{GDBP}) 7206@end smallexample 7207 7208@node save-tracepoints 7209@subsection @code{save-tracepoints @var{filename}} 7210@kindex save-tracepoints 7211@cindex save tracepoints for future sessions 7212 7213This command saves all current tracepoint definitions together with 7214their actions and passcounts, into a file @file{@var{filename}} 7215suitable for use in a later debugging session. To read the saved 7216tracepoint definitions, use the @code{source} command (@pxref{Command 7217Files}). 7218 7219@node Tracepoint Variables 7220@section Convenience Variables for Tracepoints 7221@cindex tracepoint variables 7222@cindex convenience variables for tracepoints 7223 7224@table @code 7225@vindex $trace_frame 7226@item (int) $trace_frame 7227The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no 7228snapshot is selected. 7229 7230@vindex $tracepoint 7231@item (int) $tracepoint 7232The tracepoint for the current trace snapshot. 7233 7234@vindex $trace_line 7235@item (int) $trace_line 7236The line number for the current trace snapshot. 7237 7238@vindex $trace_file 7239@item (char []) $trace_file 7240The source file for the current trace snapshot. 7241 7242@vindex $trace_func 7243@item (char []) $trace_func 7244The name of the function containing @code{$tracepoint}. 7245@end table 7246 7247Note: @code{$trace_file} is not suitable for use in @code{printf}, 7248use @code{output} instead. 7249 7250Here's a simple example of using these convenience variables for 7251stepping through all the trace snapshots and printing some of their 7252data. 7253 7254@smallexample 7255(@value{GDBP}) @b{tfind start} 7256 7257(@value{GDBP}) @b{while $trace_frame != -1} 7258> output $trace_file 7259> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint 7260> tfind 7261> end 7262@end smallexample 7263 7264@node Overlays 7265@chapter Debugging Programs That Use Overlays 7266@cindex overlays 7267 7268If your program is too large to fit completely in your target system's 7269memory, you can sometimes use @dfn{overlays} to work around this 7270problem. @value{GDBN} provides some support for debugging programs that 7271use overlays. 7272 7273@menu 7274* How Overlays Work:: A general explanation of overlays. 7275* Overlay Commands:: Managing overlays in @value{GDBN}. 7276* Automatic Overlay Debugging:: @value{GDBN} can find out which overlays are 7277 mapped by asking the inferior. 7278* Overlay Sample Program:: A sample program using overlays. 7279@end menu 7280 7281@node How Overlays Work 7282@section How Overlays Work 7283@cindex mapped overlays 7284@cindex unmapped overlays 7285@cindex load address, overlay's 7286@cindex mapped address 7287@cindex overlay area 7288 7289Suppose you have a computer whose instruction address space is only 64 7290kilobytes long, but which has much more memory which can be accessed by 7291other means: special instructions, segment registers, or memory 7292management hardware, for example. Suppose further that you want to 7293adapt a program which is larger than 64 kilobytes to run on this system. 7294 7295One solution is to identify modules of your program which are relatively 7296independent, and need not call each other directly; call these modules 7297@dfn{overlays}. Separate the overlays from the main program, and place 7298their machine code in the larger memory. Place your main program in 7299instruction memory, but leave at least enough space there to hold the 7300largest overlay as well. 7301 7302Now, to call a function located in an overlay, you must first copy that 7303overlay's machine code from the large memory into the space set aside 7304for it in the instruction memory, and then jump to its entry point 7305there. 7306 7307@c NB: In the below the mapped area's size is greater or equal to the 7308@c size of all overlays. This is intentional to remind the developer 7309@c that overlays don't necessarily need to be the same size. 7310 7311@smallexample 7312@group 7313 Data Instruction Larger 7314Address Space Address Space Address Space 7315+-----------+ +-----------+ +-----------+ 7316| | | | | | 7317+-----------+ +-----------+ +-----------+<-- overlay 1 7318| program | | main | .----| overlay 1 | load address 7319| variables | | program | | +-----------+ 7320| and heap | | | | | | 7321+-----------+ | | | +-----------+<-- overlay 2 7322| | +-----------+ | | | load address 7323+-----------+ | | | .-| overlay 2 | 7324 | | | | | | 7325 mapped --->+-----------+ | | +-----------+ 7326 address | | | | | | 7327 | overlay | <-' | | | 7328 | area | <---' +-----------+<-- overlay 3 7329 | | <---. | | load address 7330 +-----------+ `--| overlay 3 | 7331 | | | | 7332 +-----------+ | | 7333 +-----------+ 7334 | | 7335 +-----------+ 7336 7337 @anchor{A code overlay}A code overlay 7338@end group 7339@end smallexample 7340 7341The diagram (@pxref{A code overlay}) shows a system with separate data 7342and instruction address spaces. To map an overlay, the program copies 7343its code from the larger address space to the instruction address space. 7344Since the overlays shown here all use the same mapped address, only one 7345may be mapped at a time. For a system with a single address space for 7346data and instructions, the diagram would be similar, except that the 7347program variables and heap would share an address space with the main 7348program and the overlay area. 7349 7350An overlay loaded into instruction memory and ready for use is called a 7351@dfn{mapped} overlay; its @dfn{mapped address} is its address in the 7352instruction memory. An overlay not present (or only partially present) 7353in instruction memory is called @dfn{unmapped}; its @dfn{load address} 7354is its address in the larger memory. The mapped address is also called 7355the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also 7356called the @dfn{load memory address}, or @dfn{LMA}. 7357 7358Unfortunately, overlays are not a completely transparent way to adapt a 7359program to limited instruction memory. They introduce a new set of 7360global constraints you must keep in mind as you design your program: 7361 7362@itemize @bullet 7363 7364@item 7365Before calling or returning to a function in an overlay, your program 7366must make sure that overlay is actually mapped. Otherwise, the call or 7367return will transfer control to the right address, but in the wrong 7368overlay, and your program will probably crash. 7369 7370@item 7371If the process of mapping an overlay is expensive on your system, you 7372will need to choose your overlays carefully to minimize their effect on 7373your program's performance. 7374 7375@item 7376The executable file you load onto your system must contain each 7377overlay's instructions, appearing at the overlay's load address, not its 7378mapped address. However, each overlay's instructions must be relocated 7379and its symbols defined as if the overlay were at its mapped address. 7380You can use GNU linker scripts to specify different load and relocation 7381addresses for pieces of your program; see @ref{Overlay Description,,, 7382ld.info, Using ld: the GNU linker}. 7383 7384@item 7385The procedure for loading executable files onto your system must be able 7386to load their contents into the larger address space as well as the 7387instruction and data spaces. 7388 7389@end itemize 7390 7391The overlay system described above is rather simple, and could be 7392improved in many ways: 7393 7394@itemize @bullet 7395 7396@item 7397If your system has suitable bank switch registers or memory management 7398hardware, you could use those facilities to make an overlay's load area 7399contents simply appear at their mapped address in instruction space. 7400This would probably be faster than copying the overlay to its mapped 7401area in the usual way. 7402 7403@item 7404If your overlays are small enough, you could set aside more than one 7405overlay area, and have more than one overlay mapped at a time. 7406 7407@item 7408You can use overlays to manage data, as well as instructions. In 7409general, data overlays are even less transparent to your design than 7410code overlays: whereas code overlays only require care when you call or 7411return to functions, data overlays require care every time you access 7412the data. Also, if you change the contents of a data overlay, you 7413must copy its contents back out to its load address before you can copy a 7414different data overlay into the same mapped area. 7415 7416@end itemize 7417 7418 7419@node Overlay Commands 7420@section Overlay Commands 7421 7422To use @value{GDBN}'s overlay support, each overlay in your program must 7423correspond to a separate section of the executable file. The section's 7424virtual memory address and load memory address must be the overlay's 7425mapped and load addresses. Identifying overlays with sections allows 7426@value{GDBN} to determine the appropriate address of a function or 7427variable, depending on whether the overlay is mapped or not. 7428 7429@value{GDBN}'s overlay commands all start with the word @code{overlay}; 7430you can abbreviate this as @code{ov} or @code{ovly}. The commands are: 7431 7432@table @code 7433@item overlay off 7434@kindex overlay 7435Disable @value{GDBN}'s overlay support. When overlay support is 7436disabled, @value{GDBN} assumes that all functions and variables are 7437always present at their mapped addresses. By default, @value{GDBN}'s 7438overlay support is disabled. 7439 7440@item overlay manual 7441@cindex manual overlay debugging 7442Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN} 7443relies on you to tell it which overlays are mapped, and which are not, 7444using the @code{overlay map-overlay} and @code{overlay unmap-overlay} 7445commands described below. 7446 7447@item overlay map-overlay @var{overlay} 7448@itemx overlay map @var{overlay} 7449@cindex map an overlay 7450Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must 7451be the name of the object file section containing the overlay. When an 7452overlay is mapped, @value{GDBN} assumes it can find the overlay's 7453functions and variables at their mapped addresses. @value{GDBN} assumes 7454that any other overlays whose mapped ranges overlap that of 7455@var{overlay} are now unmapped. 7456 7457@item overlay unmap-overlay @var{overlay} 7458@itemx overlay unmap @var{overlay} 7459@cindex unmap an overlay 7460Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay} 7461must be the name of the object file section containing the overlay. 7462When an overlay is unmapped, @value{GDBN} assumes it can find the 7463overlay's functions and variables at their load addresses. 7464 7465@item overlay auto 7466Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN} 7467consults a data structure the overlay manager maintains in the inferior 7468to see which overlays are mapped. For details, see @ref{Automatic 7469Overlay Debugging}. 7470 7471@item overlay load-target 7472@itemx overlay load 7473@cindex reloading the overlay table 7474Re-read the overlay table from the inferior. Normally, @value{GDBN} 7475re-reads the table @value{GDBN} automatically each time the inferior 7476stops, so this command should only be necessary if you have changed the 7477overlay mapping yourself using @value{GDBN}. This command is only 7478useful when using automatic overlay debugging. 7479 7480@item overlay list-overlays 7481@itemx overlay list 7482@cindex listing mapped overlays 7483Display a list of the overlays currently mapped, along with their mapped 7484addresses, load addresses, and sizes. 7485 7486@end table 7487 7488Normally, when @value{GDBN} prints a code address, it includes the name 7489of the function the address falls in: 7490 7491@smallexample 7492(@value{GDBP}) print main 7493$3 = @{int ()@} 0x11a0 <main> 7494@end smallexample 7495@noindent 7496When overlay debugging is enabled, @value{GDBN} recognizes code in 7497unmapped overlays, and prints the names of unmapped functions with 7498asterisks around them. For example, if @code{foo} is a function in an 7499unmapped overlay, @value{GDBN} prints it this way: 7500 7501@smallexample 7502(@value{GDBP}) overlay list 7503No sections are mapped. 7504(@value{GDBP}) print foo 7505$5 = @{int (int)@} 0x100000 <*foo*> 7506@end smallexample 7507@noindent 7508When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's 7509name normally: 7510 7511@smallexample 7512(@value{GDBP}) overlay list 7513Section .ov.foo.text, loaded at 0x100000 - 0x100034, 7514 mapped at 0x1016 - 0x104a 7515(@value{GDBP}) print foo 7516$6 = @{int (int)@} 0x1016 <foo> 7517@end smallexample 7518 7519When overlay debugging is enabled, @value{GDBN} can find the correct 7520address for functions and variables in an overlay, whether or not the 7521overlay is mapped. This allows most @value{GDBN} commands, like 7522@code{break} and @code{disassemble}, to work normally, even on unmapped 7523code. However, @value{GDBN}'s breakpoint support has some limitations: 7524 7525@itemize @bullet 7526@item 7527@cindex breakpoints in overlays 7528@cindex overlays, setting breakpoints in 7529You can set breakpoints in functions in unmapped overlays, as long as 7530@value{GDBN} can write to the overlay at its load address. 7531@item 7532@value{GDBN} can not set hardware or simulator-based breakpoints in 7533unmapped overlays. However, if you set a breakpoint at the end of your 7534overlay manager (and tell @value{GDBN} which overlays are now mapped, if 7535you are using manual overlay management), @value{GDBN} will re-set its 7536breakpoints properly. 7537@end itemize 7538 7539 7540@node Automatic Overlay Debugging 7541@section Automatic Overlay Debugging 7542@cindex automatic overlay debugging 7543 7544@value{GDBN} can automatically track which overlays are mapped and which 7545are not, given some simple co-operation from the overlay manager in the 7546inferior. If you enable automatic overlay debugging with the 7547@code{overlay auto} command (@pxref{Overlay Commands}), @value{GDBN} 7548looks in the inferior's memory for certain variables describing the 7549current state of the overlays. 7550 7551Here are the variables your overlay manager must define to support 7552@value{GDBN}'s automatic overlay debugging: 7553 7554@table @asis 7555 7556@item @code{_ovly_table}: 7557This variable must be an array of the following structures: 7558 7559@smallexample 7560struct 7561@{ 7562 /* The overlay's mapped address. */ 7563 unsigned long vma; 7564 7565 /* The size of the overlay, in bytes. */ 7566 unsigned long size; 7567 7568 /* The overlay's load address. */ 7569 unsigned long lma; 7570 7571 /* Non-zero if the overlay is currently mapped; 7572 zero otherwise. */ 7573 unsigned long mapped; 7574@} 7575@end smallexample 7576 7577@item @code{_novlys}: 7578This variable must be a four-byte signed integer, holding the total 7579number of elements in @code{_ovly_table}. 7580 7581@end table 7582 7583To decide whether a particular overlay is mapped or not, @value{GDBN} 7584looks for an entry in @w{@code{_ovly_table}} whose @code{vma} and 7585@code{lma} members equal the VMA and LMA of the overlay's section in the 7586executable file. When @value{GDBN} finds a matching entry, it consults 7587the entry's @code{mapped} member to determine whether the overlay is 7588currently mapped. 7589 7590In addition, your overlay manager may define a function called 7591@code{_ovly_debug_event}. If this function is defined, @value{GDBN} 7592will silently set a breakpoint there. If the overlay manager then 7593calls this function whenever it has changed the overlay table, this 7594will enable @value{GDBN} to accurately keep track of which overlays 7595are in program memory, and update any breakpoints that may be set 7596in overlays. This will allow breakpoints to work even if the 7597overlays are kept in ROM or other non-writable memory while they 7598are not being executed. 7599 7600@node Overlay Sample Program 7601@section Overlay Sample Program 7602@cindex overlay example program 7603 7604When linking a program which uses overlays, you must place the overlays 7605at their load addresses, while relocating them to run at their mapped 7606addresses. To do this, you must write a linker script (@pxref{Overlay 7607Description,,, ld.info, Using ld: the GNU linker}). Unfortunately, 7608since linker scripts are specific to a particular host system, target 7609architecture, and target memory layout, this manual cannot provide 7610portable sample code demonstrating @value{GDBN}'s overlay support. 7611 7612However, the @value{GDBN} source distribution does contain an overlaid 7613program, with linker scripts for a few systems, as part of its test 7614suite. The program consists of the following files from 7615@file{gdb/testsuite/gdb.base}: 7616 7617@table @file 7618@item overlays.c 7619The main program file. 7620@item ovlymgr.c 7621A simple overlay manager, used by @file{overlays.c}. 7622@item foo.c 7623@itemx bar.c 7624@itemx baz.c 7625@itemx grbx.c 7626Overlay modules, loaded and used by @file{overlays.c}. 7627@item d10v.ld 7628@itemx m32r.ld 7629Linker scripts for linking the test program on the @code{d10v-elf} 7630and @code{m32r-elf} targets. 7631@end table 7632 7633You can build the test program using the @code{d10v-elf} GCC 7634cross-compiler like this: 7635 7636@smallexample 7637$ d10v-elf-gcc -g -c overlays.c 7638$ d10v-elf-gcc -g -c ovlymgr.c 7639$ d10v-elf-gcc -g -c foo.c 7640$ d10v-elf-gcc -g -c bar.c 7641$ d10v-elf-gcc -g -c baz.c 7642$ d10v-elf-gcc -g -c grbx.c 7643$ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ 7644 baz.o grbx.o -Wl,-Td10v.ld -o overlays 7645@end smallexample 7646 7647The build process is identical for any other architecture, except that 7648you must substitute the appropriate compiler and linker script for the 7649target system for @code{d10v-elf-gcc} and @code{d10v.ld}. 7650 7651 7652@node Languages 7653@chapter Using @value{GDBN} with Different Languages 7654@cindex languages 7655 7656Although programming languages generally have common aspects, they are 7657rarely expressed in the same manner. For instance, in ANSI C, 7658dereferencing a pointer @code{p} is accomplished by @code{*p}, but in 7659Modula-2, it is accomplished by @code{p^}. Values can also be 7660represented (and displayed) differently. Hex numbers in C appear as 7661@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}. 7662 7663@cindex working language 7664Language-specific information is built into @value{GDBN} for some languages, 7665allowing you to express operations like the above in your program's 7666native language, and allowing @value{GDBN} to output values in a manner 7667consistent with the syntax of your program's native language. The 7668language you use to build expressions is called the @dfn{working 7669language}. 7670 7671@menu 7672* Setting:: Switching between source languages 7673* Show:: Displaying the language 7674* Checks:: Type and range checks 7675* Support:: Supported languages 7676* Unsupported languages:: Unsupported languages 7677@end menu 7678 7679@node Setting 7680@section Switching between source languages 7681 7682There are two ways to control the working language---either have @value{GDBN} 7683set it automatically, or select it manually yourself. You can use the 7684@code{set language} command for either purpose. On startup, @value{GDBN} 7685defaults to setting the language automatically. The working language is 7686used to determine how expressions you type are interpreted, how values 7687are printed, etc. 7688 7689In addition to the working language, every source file that 7690@value{GDBN} knows about has its own working language. For some object 7691file formats, the compiler might indicate which language a particular 7692source file is in. However, most of the time @value{GDBN} infers the 7693language from the name of the file. The language of a source file 7694controls whether C@t{++} names are demangled---this way @code{backtrace} can 7695show each frame appropriately for its own language. There is no way to 7696set the language of a source file from within @value{GDBN}, but you can 7697set the language associated with a filename extension. @xref{Show, , 7698Displaying the language}. 7699 7700This is most commonly a problem when you use a program, such 7701as @code{cfront} or @code{f2c}, that generates C but is written in 7702another language. In that case, make the 7703program use @code{#line} directives in its C output; that way 7704@value{GDBN} will know the correct language of the source code of the original 7705program, and will display that source code, not the generated C code. 7706 7707@menu 7708* Filenames:: Filename extensions and languages. 7709* Manually:: Setting the working language manually 7710* Automatically:: Having @value{GDBN} infer the source language 7711@end menu 7712 7713@node Filenames 7714@subsection List of filename extensions and languages 7715 7716If a source file name ends in one of the following extensions, then 7717@value{GDBN} infers that its language is the one indicated. 7718 7719@table @file 7720@item .ada 7721@itemx .ads 7722@itemx .adb 7723@itemx .a 7724Ada source file. 7725 7726@item .c 7727C source file 7728 7729@item .C 7730@itemx .cc 7731@itemx .cp 7732@itemx .cpp 7733@itemx .cxx 7734@itemx .c++ 7735C@t{++} source file 7736 7737@item .m 7738Objective-C source file 7739 7740@item .f 7741@itemx .F 7742Fortran source file 7743 7744@item .mod 7745Modula-2 source file 7746 7747@item .s 7748@itemx .S 7749Assembler source file. This actually behaves almost like C, but 7750@value{GDBN} does not skip over function prologues when stepping. 7751@end table 7752 7753In addition, you may set the language associated with a filename 7754extension. @xref{Show, , Displaying the language}. 7755 7756@node Manually 7757@subsection Setting the working language 7758 7759If you allow @value{GDBN} to set the language automatically, 7760expressions are interpreted the same way in your debugging session and 7761your program. 7762 7763@kindex set language 7764If you wish, you may set the language manually. To do this, issue the 7765command @samp{set language @var{lang}}, where @var{lang} is the name of 7766a language, such as 7767@code{c} or @code{modula-2}. 7768For a list of the supported languages, type @samp{set language}. 7769 7770Setting the language manually prevents @value{GDBN} from updating the working 7771language automatically. This can lead to confusion if you try 7772to debug a program when the working language is not the same as the 7773source language, when an expression is acceptable to both 7774languages---but means different things. For instance, if the current 7775source file were written in C, and @value{GDBN} was parsing Modula-2, a 7776command such as: 7777 7778@smallexample 7779print a = b + c 7780@end smallexample 7781 7782@noindent 7783might not have the effect you intended. In C, this means to add 7784@code{b} and @code{c} and place the result in @code{a}. The result 7785printed would be the value of @code{a}. In Modula-2, this means to compare 7786@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value. 7787 7788@node Automatically 7789@subsection Having @value{GDBN} infer the source language 7790 7791To have @value{GDBN} set the working language automatically, use 7792@samp{set language local} or @samp{set language auto}. @value{GDBN} 7793then infers the working language. That is, when your program stops in a 7794frame (usually by encountering a breakpoint), @value{GDBN} sets the 7795working language to the language recorded for the function in that 7796frame. If the language for a frame is unknown (that is, if the function 7797or block corresponding to the frame was defined in a source file that 7798does not have a recognized extension), the current working language is 7799not changed, and @value{GDBN} issues a warning. 7800 7801This may not seem necessary for most programs, which are written 7802entirely in one source language. However, program modules and libraries 7803written in one source language can be used by a main program written in 7804a different source language. Using @samp{set language auto} in this 7805case frees you from having to set the working language manually. 7806 7807@node Show 7808@section Displaying the language 7809 7810The following commands help you find out which language is the 7811working language, and also what language source files were written in. 7812 7813@kindex show language 7814@table @code 7815@item show language 7816Display the current working language. This is the 7817language you can use with commands such as @code{print} to 7818build and compute expressions that may involve variables in your program. 7819 7820@item info frame 7821@kindex info frame@r{, show the source language} 7822Display the source language for this frame. This language becomes the 7823working language if you use an identifier from this frame. 7824@xref{Frame Info, ,Information about a frame}, to identify the other 7825information listed here. 7826 7827@item info source 7828@kindex info source@r{, show the source language} 7829Display the source language of this source file. 7830@xref{Symbols, ,Examining the Symbol Table}, to identify the other 7831information listed here. 7832@end table 7833 7834In unusual circumstances, you may have source files with extensions 7835not in the standard list. You can then set the extension associated 7836with a language explicitly: 7837 7838@kindex set extension-language 7839@kindex info extensions 7840@table @code 7841@item set extension-language @var{.ext} @var{language} 7842Set source files with extension @var{.ext} to be assumed to be in 7843the source language @var{language}. 7844 7845@item info extensions 7846List all the filename extensions and the associated languages. 7847@end table 7848 7849@node Checks 7850@section Type and range checking 7851 7852@quotation 7853@emph{Warning:} In this release, the @value{GDBN} commands for type and range 7854checking are included, but they do not yet have any effect. This 7855section documents the intended facilities. 7856@end quotation 7857@c FIXME remove warning when type/range code added 7858 7859Some languages are designed to guard you against making seemingly common 7860errors through a series of compile- and run-time checks. These include 7861checking the type of arguments to functions and operators, and making 7862sure mathematical overflows are caught at run time. Checks such as 7863these help to ensure a program's correctness once it has been compiled 7864by eliminating type mismatches, and providing active checks for range 7865errors when your program is running. 7866 7867@value{GDBN} can check for conditions like the above if you wish. 7868Although @value{GDBN} does not check the statements in your program, it 7869can check expressions entered directly into @value{GDBN} for evaluation via 7870the @code{print} command, for example. As with the working language, 7871@value{GDBN} can also decide whether or not to check automatically based on 7872your program's source language. @xref{Support, ,Supported languages}, 7873for the default settings of supported languages. 7874 7875@menu 7876* Type Checking:: An overview of type checking 7877* Range Checking:: An overview of range checking 7878@end menu 7879 7880@cindex type checking 7881@cindex checks, type 7882@node Type Checking 7883@subsection An overview of type checking 7884 7885Some languages, such as Modula-2, are strongly typed, meaning that the 7886arguments to operators and functions have to be of the correct type, 7887otherwise an error occurs. These checks prevent type mismatch 7888errors from ever causing any run-time problems. For example, 7889 7890@smallexample 78911 + 2 @result{} 3 7892@exdent but 7893@error{} 1 + 2.3 7894@end smallexample 7895 7896The second example fails because the @code{CARDINAL} 1 is not 7897type-compatible with the @code{REAL} 2.3. 7898 7899For the expressions you use in @value{GDBN} commands, you can tell the 7900@value{GDBN} type checker to skip checking; 7901to treat any mismatches as errors and abandon the expression; 7902or to only issue warnings when type mismatches occur, 7903but evaluate the expression anyway. When you choose the last of 7904these, @value{GDBN} evaluates expressions like the second example above, but 7905also issues a warning. 7906 7907Even if you turn type checking off, there may be other reasons 7908related to type that prevent @value{GDBN} from evaluating an expression. 7909For instance, @value{GDBN} does not know how to add an @code{int} and 7910a @code{struct foo}. These particular type errors have nothing to do 7911with the language in use, and usually arise from expressions, such as 7912the one described above, which make little sense to evaluate anyway. 7913 7914Each language defines to what degree it is strict about type. For 7915instance, both Modula-2 and C require the arguments to arithmetical 7916operators to be numbers. In C, enumerated types and pointers can be 7917represented as numbers, so that they are valid arguments to mathematical 7918operators. @xref{Support, ,Supported languages}, for further 7919details on specific languages. 7920 7921@value{GDBN} provides some additional commands for controlling the type checker: 7922 7923@kindex set check type 7924@kindex show check type 7925@table @code 7926@item set check type auto 7927Set type checking on or off based on the current working language. 7928@xref{Support, ,Supported languages}, for the default settings for 7929each language. 7930 7931@item set check type on 7932@itemx set check type off 7933Set type checking on or off, overriding the default setting for the 7934current working language. Issue a warning if the setting does not 7935match the language default. If any type mismatches occur in 7936evaluating an expression while type checking is on, @value{GDBN} prints a 7937message and aborts evaluation of the expression. 7938 7939@item set check type warn 7940Cause the type checker to issue warnings, but to always attempt to 7941evaluate the expression. Evaluating the expression may still 7942be impossible for other reasons. For example, @value{GDBN} cannot add 7943numbers and structures. 7944 7945@item show type 7946Show the current setting of the type checker, and whether or not @value{GDBN} 7947is setting it automatically. 7948@end table 7949 7950@cindex range checking 7951@cindex checks, range 7952@node Range Checking 7953@subsection An overview of range checking 7954 7955In some languages (such as Modula-2), it is an error to exceed the 7956bounds of a type; this is enforced with run-time checks. Such range 7957checking is meant to ensure program correctness by making sure 7958computations do not overflow, or indices on an array element access do 7959not exceed the bounds of the array. 7960 7961For expressions you use in @value{GDBN} commands, you can tell 7962@value{GDBN} to treat range errors in one of three ways: ignore them, 7963always treat them as errors and abandon the expression, or issue 7964warnings but evaluate the expression anyway. 7965 7966A range error can result from numerical overflow, from exceeding an 7967array index bound, or when you type a constant that is not a member 7968of any type. Some languages, however, do not treat overflows as an 7969error. In many implementations of C, mathematical overflow causes the 7970result to ``wrap around'' to lower values---for example, if @var{m} is 7971the largest integer value, and @var{s} is the smallest, then 7972 7973@smallexample 7974@var{m} + 1 @result{} @var{s} 7975@end smallexample 7976 7977This, too, is specific to individual languages, and in some cases 7978specific to individual compilers or machines. @xref{Support, , 7979Supported languages}, for further details on specific languages. 7980 7981@value{GDBN} provides some additional commands for controlling the range checker: 7982 7983@kindex set check range 7984@kindex show check range 7985@table @code 7986@item set check range auto 7987Set range checking on or off based on the current working language. 7988@xref{Support, ,Supported languages}, for the default settings for 7989each language. 7990 7991@item set check range on 7992@itemx set check range off 7993Set range checking on or off, overriding the default setting for the 7994current working language. A warning is issued if the setting does not 7995match the language default. If a range error occurs and range checking is on, 7996then a message is printed and evaluation of the expression is aborted. 7997 7998@item set check range warn 7999Output messages when the @value{GDBN} range checker detects a range error, 8000but attempt to evaluate the expression anyway. Evaluating the 8001expression may still be impossible for other reasons, such as accessing 8002memory that the process does not own (a typical example from many Unix 8003systems). 8004 8005@item show range 8006Show the current setting of the range checker, and whether or not it is 8007being set automatically by @value{GDBN}. 8008@end table 8009 8010@node Support 8011@section Supported languages 8012 8013@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, assembly, Modula-2, and Ada. 8014@c This is false ... 8015Some @value{GDBN} features may be used in expressions regardless of the 8016language you use: the @value{GDBN} @code{@@} and @code{::} operators, 8017and the @samp{@{type@}addr} construct (@pxref{Expressions, 8018,Expressions}) can be used with the constructs of any supported 8019language. 8020 8021The following sections detail to what degree each source language is 8022supported by @value{GDBN}. These sections are not meant to be language 8023tutorials or references, but serve only as a reference guide to what the 8024@value{GDBN} expression parser accepts, and what input and output 8025formats should look like for different languages. There are many good 8026books written on each of these languages; please look to these for a 8027language reference or tutorial. 8028 8029@menu 8030* C:: C and C@t{++} 8031* Objective-C:: Objective-C 8032* Modula-2:: Modula-2 8033* Ada:: Ada 8034@end menu 8035 8036@node C 8037@subsection C and C@t{++} 8038 8039@cindex C and C@t{++} 8040@cindex expressions in C or C@t{++} 8041 8042Since C and C@t{++} are so closely related, many features of @value{GDBN} apply 8043to both languages. Whenever this is the case, we discuss those languages 8044together. 8045 8046@cindex C@t{++} 8047@cindex @code{g++}, @sc{gnu} C@t{++} compiler 8048@cindex @sc{gnu} C@t{++} 8049The C@t{++} debugging facilities are jointly implemented by the C@t{++} 8050compiler and @value{GDBN}. Therefore, to debug your C@t{++} code 8051effectively, you must compile your C@t{++} programs with a supported 8052C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++} 8053compiler (@code{aCC}). 8054 8055For best results when using @sc{gnu} C@t{++}, use the DWARF 2 debugging 8056format; if it doesn't work on your system, try the stabs+ debugging 8057format. You can select those formats explicitly with the @code{g++} 8058command-line options @option{-gdwarf-2} and @option{-gstabs+}. 8059@xref{Debugging Options,,Options for Debugging Your Program or @sc{gnu} 8060CC, gcc.info, Using @sc{gnu} CC}. 8061 8062@menu 8063* C Operators:: C and C@t{++} operators 8064* C Constants:: C and C@t{++} constants 8065* C plus plus expressions:: C@t{++} expressions 8066* C Defaults:: Default settings for C and C@t{++} 8067* C Checks:: C and C@t{++} type and range checks 8068* Debugging C:: @value{GDBN} and C 8069* Debugging C plus plus:: @value{GDBN} features for C@t{++} 8070@end menu 8071 8072@node C Operators 8073@subsubsection C and C@t{++} operators 8074 8075@cindex C and C@t{++} operators 8076 8077Operators must be defined on values of specific types. For instance, 8078@code{+} is defined on numbers, but not on structures. Operators are 8079often defined on groups of types. 8080 8081For the purposes of C and C@t{++}, the following definitions hold: 8082 8083@itemize @bullet 8084 8085@item 8086@emph{Integral types} include @code{int} with any of its storage-class 8087specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}. 8088 8089@item 8090@emph{Floating-point types} include @code{float}, @code{double}, and 8091@code{long double} (if supported by the target platform). 8092 8093@item 8094@emph{Pointer types} include all types defined as @code{(@var{type} *)}. 8095 8096@item 8097@emph{Scalar types} include all of the above. 8098 8099@end itemize 8100 8101@noindent 8102The following operators are supported. They are listed here 8103in order of increasing precedence: 8104 8105@table @code 8106@item , 8107The comma or sequencing operator. Expressions in a comma-separated list 8108are evaluated from left to right, with the result of the entire 8109expression being the last expression evaluated. 8110 8111@item = 8112Assignment. The value of an assignment expression is the value 8113assigned. Defined on scalar types. 8114 8115@item @var{op}= 8116Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}}, 8117and translated to @w{@code{@var{a} = @var{a op b}}}. 8118@w{@code{@var{op}=}} and @code{=} have the same precedence. 8119@var{op} is any one of the operators @code{|}, @code{^}, @code{&}, 8120@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}. 8121 8122@item ?: 8123The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought 8124of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an 8125integral type. 8126 8127@item || 8128Logical @sc{or}. Defined on integral types. 8129 8130@item && 8131Logical @sc{and}. Defined on integral types. 8132 8133@item | 8134Bitwise @sc{or}. Defined on integral types. 8135 8136@item ^ 8137Bitwise exclusive-@sc{or}. Defined on integral types. 8138 8139@item & 8140Bitwise @sc{and}. Defined on integral types. 8141 8142@item ==@r{, }!= 8143Equality and inequality. Defined on scalar types. The value of these 8144expressions is 0 for false and non-zero for true. 8145 8146@item <@r{, }>@r{, }<=@r{, }>= 8147Less than, greater than, less than or equal, greater than or equal. 8148Defined on scalar types. The value of these expressions is 0 for false 8149and non-zero for true. 8150 8151@item <<@r{, }>> 8152left shift, and right shift. Defined on integral types. 8153 8154@item @@ 8155The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}). 8156 8157@item +@r{, }- 8158Addition and subtraction. Defined on integral types, floating-point types and 8159pointer types. 8160 8161@item *@r{, }/@r{, }% 8162Multiplication, division, and modulus. Multiplication and division are 8163defined on integral and floating-point types. Modulus is defined on 8164integral types. 8165 8166@item ++@r{, }-- 8167Increment and decrement. When appearing before a variable, the 8168operation is performed before the variable is used in an expression; 8169when appearing after it, the variable's value is used before the 8170operation takes place. 8171 8172@item * 8173Pointer dereferencing. Defined on pointer types. Same precedence as 8174@code{++}. 8175 8176@item & 8177Address operator. Defined on variables. Same precedence as @code{++}. 8178 8179For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is 8180allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})} 8181(or, if you prefer, simply @samp{&&@var{ref}}) to examine the address 8182where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is 8183stored. 8184 8185@item - 8186Negative. Defined on integral and floating-point types. Same 8187precedence as @code{++}. 8188 8189@item ! 8190Logical negation. Defined on integral types. Same precedence as 8191@code{++}. 8192 8193@item ~ 8194Bitwise complement operator. Defined on integral types. Same precedence as 8195@code{++}. 8196 8197 8198@item .@r{, }-> 8199Structure member, and pointer-to-structure member. For convenience, 8200@value{GDBN} regards the two as equivalent, choosing whether to dereference a 8201pointer based on the stored type information. 8202Defined on @code{struct} and @code{union} data. 8203 8204@item .*@r{, }->* 8205Dereferences of pointers to members. 8206 8207@item [] 8208Array indexing. @code{@var{a}[@var{i}]} is defined as 8209@code{*(@var{a}+@var{i})}. Same precedence as @code{->}. 8210 8211@item () 8212Function parameter list. Same precedence as @code{->}. 8213 8214@item :: 8215C@t{++} scope resolution operator. Defined on @code{struct}, @code{union}, 8216and @code{class} types. 8217 8218@item :: 8219Doubled colons also represent the @value{GDBN} scope operator 8220(@pxref{Expressions, ,Expressions}). Same precedence as @code{::}, 8221above. 8222@end table 8223 8224If an operator is redefined in the user code, @value{GDBN} usually 8225attempts to invoke the redefined version instead of using the operator's 8226predefined meaning. 8227 8228@menu 8229* C Constants:: 8230@end menu 8231 8232@node C Constants 8233@subsubsection C and C@t{++} constants 8234 8235@cindex C and C@t{++} constants 8236 8237@value{GDBN} allows you to express the constants of C and C@t{++} in the 8238following ways: 8239 8240@itemize @bullet 8241@item 8242Integer constants are a sequence of digits. Octal constants are 8243specified by a leading @samp{0} (i.e.@: zero), and hexadecimal constants 8244by a leading @samp{0x} or @samp{0X}. Constants may also end with a letter 8245@samp{l}, specifying that the constant should be treated as a 8246@code{long} value. 8247 8248@item 8249Floating point constants are a sequence of digits, followed by a decimal 8250point, followed by a sequence of digits, and optionally followed by an 8251exponent. An exponent is of the form: 8252@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another 8253sequence of digits. The @samp{+} is optional for positive exponents. 8254A floating-point constant may also end with a letter @samp{f} or 8255@samp{F}, specifying that the constant should be treated as being of 8256the @code{float} (as opposed to the default @code{double}) type; or with 8257a letter @samp{l} or @samp{L}, which specifies a @code{long double} 8258constant. 8259 8260@item 8261Enumerated constants consist of enumerated identifiers, or their 8262integral equivalents. 8263 8264@item 8265Character constants are a single character surrounded by single quotes 8266(@code{'}), or a number---the ordinal value of the corresponding character 8267(usually its @sc{ascii} value). Within quotes, the single character may 8268be represented by a letter or by @dfn{escape sequences}, which are of 8269the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation 8270of the character's ordinal value; or of the form @samp{\@var{x}}, where 8271@samp{@var{x}} is a predefined special character---for example, 8272@samp{\n} for newline. 8273 8274@item 8275String constants are a sequence of character constants surrounded by 8276double quotes (@code{"}). Any valid character constant (as described 8277above) may appear. Double quotes within the string must be preceded by 8278a backslash, so for instance @samp{"a\"b'c"} is a string of five 8279characters. 8280 8281@item 8282Pointer constants are an integral value. You can also write pointers 8283to constants using the C operator @samp{&}. 8284 8285@item 8286Array constants are comma-separated lists surrounded by braces @samp{@{} 8287and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of 8288integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array, 8289and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers. 8290@end itemize 8291 8292@menu 8293* C plus plus expressions:: 8294* C Defaults:: 8295* C Checks:: 8296 8297* Debugging C:: 8298@end menu 8299 8300@node C plus plus expressions 8301@subsubsection C@t{++} expressions 8302 8303@cindex expressions in C@t{++} 8304@value{GDBN} expression handling can interpret most C@t{++} expressions. 8305 8306@cindex debugging C@t{++} programs 8307@cindex C@t{++} compilers 8308@cindex debug formats and C@t{++} 8309@cindex @value{NGCC} and C@t{++} 8310@quotation 8311@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the 8312proper compiler and the proper debug format. Currently, @value{GDBN} 8313works best when debugging C@t{++} code that is compiled with 8314@value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options 8315@option{-gdwarf-2} or @option{-gstabs+}. DWARF 2 is preferred over 8316stabs+. Most configurations of @value{NGCC} emit either DWARF 2 or 8317stabs+ as their default debug format, so you usually don't need to 8318specify a debug format explicitly. Other compilers and/or debug formats 8319are likely to work badly or not at all when using @value{GDBN} to debug 8320C@t{++} code. 8321@end quotation 8322 8323@enumerate 8324 8325@cindex member functions 8326@item 8327Member function calls are allowed; you can use expressions like 8328 8329@smallexample 8330count = aml->GetOriginal(x, y) 8331@end smallexample 8332 8333@vindex this@r{, inside C@t{++} member functions} 8334@cindex namespace in C@t{++} 8335@item 8336While a member function is active (in the selected stack frame), your 8337expressions have the same namespace available as the member function; 8338that is, @value{GDBN} allows implicit references to the class instance 8339pointer @code{this} following the same rules as C@t{++}. 8340 8341@cindex call overloaded functions 8342@cindex overloaded functions, calling 8343@cindex type conversions in C@t{++} 8344@item 8345You can call overloaded functions; @value{GDBN} resolves the function 8346call to the right definition, with some restrictions. @value{GDBN} does not 8347perform overload resolution involving user-defined type conversions, 8348calls to constructors, or instantiations of templates that do not exist 8349in the program. It also cannot handle ellipsis argument lists or 8350default arguments. 8351 8352It does perform integral conversions and promotions, floating-point 8353promotions, arithmetic conversions, pointer conversions, conversions of 8354class objects to base classes, and standard conversions such as those of 8355functions or arrays to pointers; it requires an exact match on the 8356number of function arguments. 8357 8358Overload resolution is always performed, unless you have specified 8359@code{set overload-resolution off}. @xref{Debugging C plus plus, 8360,@value{GDBN} features for C@t{++}}. 8361 8362You must specify @code{set overload-resolution off} in order to use an 8363explicit function signature to call an overloaded function, as in 8364@smallexample 8365p 'foo(char,int)'('x', 13) 8366@end smallexample 8367 8368The @value{GDBN} command-completion facility can simplify this; 8369see @ref{Completion, ,Command completion}. 8370 8371@cindex reference declarations 8372@item 8373@value{GDBN} understands variables declared as C@t{++} references; you can use 8374them in expressions just as you do in C@t{++} source---they are automatically 8375dereferenced. 8376 8377In the parameter list shown when @value{GDBN} displays a frame, the values of 8378reference variables are not displayed (unlike other variables); this 8379avoids clutter, since references are often used for large structures. 8380The @emph{address} of a reference variable is always shown, unless 8381you have specified @samp{set print address off}. 8382 8383@item 8384@value{GDBN} supports the C@t{++} name resolution operator @code{::}---your 8385expressions can use it just as expressions in your program do. Since 8386one scope may be defined in another, you can use @code{::} repeatedly if 8387necessary, for example in an expression like 8388@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows 8389resolving name scope by reference to source files, in both C and C@t{++} 8390debugging (@pxref{Variables, ,Program variables}). 8391@end enumerate 8392 8393In addition, when used with HP's C@t{++} compiler, @value{GDBN} supports 8394calling virtual functions correctly, printing out virtual bases of 8395objects, calling functions in a base subobject, casting objects, and 8396invoking user-defined operators. 8397 8398@node C Defaults 8399@subsubsection C and C@t{++} defaults 8400 8401@cindex C and C@t{++} defaults 8402 8403If you allow @value{GDBN} to set type and range checking automatically, they 8404both default to @code{off} whenever the working language changes to 8405C or C@t{++}. This happens regardless of whether you or @value{GDBN} 8406selects the working language. 8407 8408If you allow @value{GDBN} to set the language automatically, it 8409recognizes source files whose names end with @file{.c}, @file{.C}, or 8410@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of 8411these files, it sets the working language to C or C@t{++}. 8412@xref{Automatically, ,Having @value{GDBN} infer the source language}, 8413for further details. 8414 8415@c Type checking is (a) primarily motivated by Modula-2, and (b) 8416@c unimplemented. If (b) changes, it might make sense to let this node 8417@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93. 8418 8419@node C Checks 8420@subsubsection C and C@t{++} type and range checks 8421 8422@cindex C and C@t{++} checks 8423 8424By default, when @value{GDBN} parses C or C@t{++} expressions, type checking 8425is not used. However, if you turn type checking on, @value{GDBN} 8426considers two variables type equivalent if: 8427 8428@itemize @bullet 8429@item 8430The two variables are structured and have the same structure, union, or 8431enumerated tag. 8432 8433@item 8434The two variables have the same type name, or types that have been 8435declared equivalent through @code{typedef}. 8436 8437@ignore 8438@c leaving this out because neither J Gilmore nor R Pesch understand it. 8439@c FIXME--beers? 8440@item 8441The two @code{struct}, @code{union}, or @code{enum} variables are 8442declared in the same declaration. (Note: this may not be true for all C 8443compilers.) 8444@end ignore 8445@end itemize 8446 8447Range checking, if turned on, is done on mathematical operations. Array 8448indices are not checked, since they are often used to index a pointer 8449that is not itself an array. 8450 8451@node Debugging C 8452@subsubsection @value{GDBN} and C 8453 8454The @code{set print union} and @code{show print union} commands apply to 8455the @code{union} type. When set to @samp{on}, any @code{union} that is 8456inside a @code{struct} or @code{class} is also printed. Otherwise, it 8457appears as @samp{@{...@}}. 8458 8459The @code{@@} operator aids in the debugging of dynamic arrays, formed 8460with pointers and a memory allocation function. @xref{Expressions, 8461,Expressions}. 8462 8463@menu 8464* Debugging C plus plus:: 8465@end menu 8466 8467@node Debugging C plus plus 8468@subsubsection @value{GDBN} features for C@t{++} 8469 8470@cindex commands for C@t{++} 8471 8472Some @value{GDBN} commands are particularly useful with C@t{++}, and some are 8473designed specifically for use with C@t{++}. Here is a summary: 8474 8475@table @code 8476@cindex break in overloaded functions 8477@item @r{breakpoint menus} 8478When you want a breakpoint in a function whose name is overloaded, 8479@value{GDBN} breakpoint menus help you specify which function definition 8480you want. @xref{Breakpoint Menus,,Breakpoint menus}. 8481 8482@cindex overloading in C@t{++} 8483@item rbreak @var{regex} 8484Setting breakpoints using regular expressions is helpful for setting 8485breakpoints on overloaded functions that are not members of any special 8486classes. 8487@xref{Set Breaks, ,Setting breakpoints}. 8488 8489@cindex C@t{++} exception handling 8490@item catch throw 8491@itemx catch catch 8492Debug C@t{++} exception handling using these commands. @xref{Set 8493Catchpoints, , Setting catchpoints}. 8494 8495@cindex inheritance 8496@item ptype @var{typename} 8497Print inheritance relationships as well as other information for type 8498@var{typename}. 8499@xref{Symbols, ,Examining the Symbol Table}. 8500 8501@cindex C@t{++} symbol display 8502@item set print demangle 8503@itemx show print demangle 8504@itemx set print asm-demangle 8505@itemx show print asm-demangle 8506Control whether C@t{++} symbols display in their source form, both when 8507displaying code as C@t{++} source and when displaying disassemblies. 8508@xref{Print Settings, ,Print settings}. 8509 8510@item set print object 8511@itemx show print object 8512Choose whether to print derived (actual) or declared types of objects. 8513@xref{Print Settings, ,Print settings}. 8514 8515@item set print vtbl 8516@itemx show print vtbl 8517Control the format for printing virtual function tables. 8518@xref{Print Settings, ,Print settings}. 8519(The @code{vtbl} commands do not work on programs compiled with the HP 8520ANSI C@t{++} compiler (@code{aCC}).) 8521 8522@kindex set overload-resolution 8523@cindex overloaded functions, overload resolution 8524@item set overload-resolution on 8525Enable overload resolution for C@t{++} expression evaluation. The default 8526is on. For overloaded functions, @value{GDBN} evaluates the arguments 8527and searches for a function whose signature matches the argument types, 8528using the standard C@t{++} conversion rules (see @ref{C plus plus expressions, ,C@t{++} 8529expressions}, for details). If it cannot find a match, it emits a 8530message. 8531 8532@item set overload-resolution off 8533Disable overload resolution for C@t{++} expression evaluation. For 8534overloaded functions that are not class member functions, @value{GDBN} 8535chooses the first function of the specified name that it finds in the 8536symbol table, whether or not its arguments are of the correct type. For 8537overloaded functions that are class member functions, @value{GDBN} 8538searches for a function whose signature @emph{exactly} matches the 8539argument types. 8540 8541@item @r{Overloaded symbol names} 8542You can specify a particular definition of an overloaded symbol, using 8543the same notation that is used to declare such symbols in C@t{++}: type 8544@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can 8545also use the @value{GDBN} command-line word completion facilities to list the 8546available choices, or to finish the type list for you. 8547@xref{Completion,, Command completion}, for details on how to do this. 8548@end table 8549 8550@node Objective-C 8551@subsection Objective-C 8552 8553@cindex Objective-C 8554This section provides information about some commands and command 8555options that are useful for debugging Objective-C code. 8556 8557@menu 8558* Method Names in Commands:: 8559* The Print Command with Objective-C:: 8560@end menu 8561 8562@node Method Names in Commands, The Print Command with Objective-C, Objective-C, Objective-C 8563@subsubsection Method Names in Commands 8564 8565The following commands have been extended to accept Objective-C method 8566names as line specifications: 8567 8568@kindex clear@r{, and Objective-C} 8569@kindex break@r{, and Objective-C} 8570@kindex info line@r{, and Objective-C} 8571@kindex jump@r{, and Objective-C} 8572@kindex list@r{, and Objective-C} 8573@itemize 8574@item @code{clear} 8575@item @code{break} 8576@item @code{info line} 8577@item @code{jump} 8578@item @code{list} 8579@end itemize 8580 8581A fully qualified Objective-C method name is specified as 8582 8583@smallexample 8584-[@var{Class} @var{methodName}] 8585@end smallexample 8586 8587where the minus sign is used to indicate an instance method and a 8588plus sign (not shown) is used to indicate a class method. The class 8589name @var{Class} and method name @var{methodName} are enclosed in 8590brackets, similar to the way messages are specified in Objective-C 8591source code. For example, to set a breakpoint at the @code{create} 8592instance method of class @code{Fruit} in the program currently being 8593debugged, enter: 8594 8595@smallexample 8596break -[Fruit create] 8597@end smallexample 8598 8599To list ten program lines around the @code{initialize} class method, 8600enter: 8601 8602@smallexample 8603list +[NSText initialize] 8604@end smallexample 8605 8606In the current version of @value{GDBN}, the plus or minus sign is 8607required. In future versions of @value{GDBN}, the plus or minus 8608sign will be optional, but you can use it to narrow the search. It 8609is also possible to specify just a method name: 8610 8611@smallexample 8612break create 8613@end smallexample 8614 8615You must specify the complete method name, including any colons. If 8616your program's source files contain more than one @code{create} method, 8617you'll be presented with a numbered list of classes that implement that 8618method. Indicate your choice by number, or type @samp{0} to exit if 8619none apply. 8620 8621As another example, to clear a breakpoint established at the 8622@code{makeKeyAndOrderFront:} method of the @code{NSWindow} class, enter: 8623 8624@smallexample 8625clear -[NSWindow makeKeyAndOrderFront:] 8626@end smallexample 8627 8628@node The Print Command with Objective-C 8629@subsubsection The Print Command With Objective-C 8630@kindex print-object 8631@kindex po @r{(@code{print-object})} 8632 8633The print command has also been extended to accept methods. For example: 8634 8635@smallexample 8636print -[@var{object} hash] 8637@end smallexample 8638 8639@cindex print an Objective-C object description 8640@cindex @code{_NSPrintForDebugger}, and printing Objective-C objects 8641@noindent 8642will tell @value{GDBN} to send the @code{hash} message to @var{object} 8643and print the result. Also, an additional command has been added, 8644@code{print-object} or @code{po} for short, which is meant to print 8645the description of an object. However, this command may only work 8646with certain Objective-C libraries that have a particular hook 8647function, @code{_NSPrintForDebugger}, defined. 8648 8649@node Modula-2, Ada, Objective-C, Support 8650@subsection Modula-2 8651 8652@cindex Modula-2, @value{GDBN} support 8653 8654The extensions made to @value{GDBN} to support Modula-2 only support 8655output from the @sc{gnu} Modula-2 compiler (which is currently being 8656developed). Other Modula-2 compilers are not currently supported, and 8657attempting to debug executables produced by them is most likely 8658to give an error as @value{GDBN} reads in the executable's symbol 8659table. 8660 8661@cindex expressions in Modula-2 8662@menu 8663* M2 Operators:: Built-in operators 8664* Built-In Func/Proc:: Built-in functions and procedures 8665* M2 Constants:: Modula-2 constants 8666* M2 Defaults:: Default settings for Modula-2 8667* Deviations:: Deviations from standard Modula-2 8668* M2 Checks:: Modula-2 type and range checks 8669* M2 Scope:: The scope operators @code{::} and @code{.} 8670* GDB/M2:: @value{GDBN} and Modula-2 8671@end menu 8672 8673@node M2 Operators 8674@subsubsection Operators 8675@cindex Modula-2 operators 8676 8677Operators must be defined on values of specific types. For instance, 8678@code{+} is defined on numbers, but not on structures. Operators are 8679often defined on groups of types. For the purposes of Modula-2, the 8680following definitions hold: 8681 8682@itemize @bullet 8683 8684@item 8685@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and 8686their subranges. 8687 8688@item 8689@emph{Character types} consist of @code{CHAR} and its subranges. 8690 8691@item 8692@emph{Floating-point types} consist of @code{REAL}. 8693 8694@item 8695@emph{Pointer types} consist of anything declared as @code{POINTER TO 8696@var{type}}. 8697 8698@item 8699@emph{Scalar types} consist of all of the above. 8700 8701@item 8702@emph{Set types} consist of @code{SET} and @code{BITSET} types. 8703 8704@item 8705@emph{Boolean types} consist of @code{BOOLEAN}. 8706@end itemize 8707 8708@noindent 8709The following operators are supported, and appear in order of 8710increasing precedence: 8711 8712@table @code 8713@item , 8714Function argument or array index separator. 8715 8716@item := 8717Assignment. The value of @var{var} @code{:=} @var{value} is 8718@var{value}. 8719 8720@item <@r{, }> 8721Less than, greater than on integral, floating-point, or enumerated 8722types. 8723 8724@item <=@r{, }>= 8725Less than or equal to, greater than or equal to 8726on integral, floating-point and enumerated types, or set inclusion on 8727set types. Same precedence as @code{<}. 8728 8729@item =@r{, }<>@r{, }# 8730Equality and two ways of expressing inequality, valid on scalar types. 8731Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is 8732available for inequality, since @code{#} conflicts with the script 8733comment character. 8734 8735@item IN 8736Set membership. Defined on set types and the types of their members. 8737Same precedence as @code{<}. 8738 8739@item OR 8740Boolean disjunction. Defined on boolean types. 8741 8742@item AND@r{, }& 8743Boolean conjunction. Defined on boolean types. 8744 8745@item @@ 8746The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}). 8747 8748@item +@r{, }- 8749Addition and subtraction on integral and floating-point types, or union 8750and difference on set types. 8751 8752@item * 8753Multiplication on integral and floating-point types, or set intersection 8754on set types. 8755 8756@item / 8757Division on floating-point types, or symmetric set difference on set 8758types. Same precedence as @code{*}. 8759 8760@item DIV@r{, }MOD 8761Integer division and remainder. Defined on integral types. Same 8762precedence as @code{*}. 8763 8764@item - 8765Negative. Defined on @code{INTEGER} and @code{REAL} data. 8766 8767@item ^ 8768Pointer dereferencing. Defined on pointer types. 8769 8770@item NOT 8771Boolean negation. Defined on boolean types. Same precedence as 8772@code{^}. 8773 8774@item . 8775@code{RECORD} field selector. Defined on @code{RECORD} data. Same 8776precedence as @code{^}. 8777 8778@item [] 8779Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}. 8780 8781@item () 8782Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence 8783as @code{^}. 8784 8785@item ::@r{, }. 8786@value{GDBN} and Modula-2 scope operators. 8787@end table 8788 8789@quotation 8790@emph{Warning:} Sets and their operations are not yet supported, so @value{GDBN} 8791treats the use of the operator @code{IN}, or the use of operators 8792@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#}, 8793@code{<=}, and @code{>=} on sets as an error. 8794@end quotation 8795 8796 8797@node Built-In Func/Proc 8798@subsubsection Built-in functions and procedures 8799@cindex Modula-2 built-ins 8800 8801Modula-2 also makes available several built-in procedures and functions. 8802In describing these, the following metavariables are used: 8803 8804@table @var 8805 8806@item a 8807represents an @code{ARRAY} variable. 8808 8809@item c 8810represents a @code{CHAR} constant or variable. 8811 8812@item i 8813represents a variable or constant of integral type. 8814 8815@item m 8816represents an identifier that belongs to a set. Generally used in the 8817same function with the metavariable @var{s}. The type of @var{s} should 8818be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}). 8819 8820@item n 8821represents a variable or constant of integral or floating-point type. 8822 8823@item r 8824represents a variable or constant of floating-point type. 8825 8826@item t 8827represents a type. 8828 8829@item v 8830represents a variable. 8831 8832@item x 8833represents a variable or constant of one of many types. See the 8834explanation of the function for details. 8835@end table 8836 8837All Modula-2 built-in procedures also return a result, described below. 8838 8839@table @code 8840@item ABS(@var{n}) 8841Returns the absolute value of @var{n}. 8842 8843@item CAP(@var{c}) 8844If @var{c} is a lower case letter, it returns its upper case 8845equivalent, otherwise it returns its argument. 8846 8847@item CHR(@var{i}) 8848Returns the character whose ordinal value is @var{i}. 8849 8850@item DEC(@var{v}) 8851Decrements the value in the variable @var{v} by one. Returns the new value. 8852 8853@item DEC(@var{v},@var{i}) 8854Decrements the value in the variable @var{v} by @var{i}. Returns the 8855new value. 8856 8857@item EXCL(@var{m},@var{s}) 8858Removes the element @var{m} from the set @var{s}. Returns the new 8859set. 8860 8861@item FLOAT(@var{i}) 8862Returns the floating point equivalent of the integer @var{i}. 8863 8864@item HIGH(@var{a}) 8865Returns the index of the last member of @var{a}. 8866 8867@item INC(@var{v}) 8868Increments the value in the variable @var{v} by one. Returns the new value. 8869 8870@item INC(@var{v},@var{i}) 8871Increments the value in the variable @var{v} by @var{i}. Returns the 8872new value. 8873 8874@item INCL(@var{m},@var{s}) 8875Adds the element @var{m} to the set @var{s} if it is not already 8876there. Returns the new set. 8877 8878@item MAX(@var{t}) 8879Returns the maximum value of the type @var{t}. 8880 8881@item MIN(@var{t}) 8882Returns the minimum value of the type @var{t}. 8883 8884@item ODD(@var{i}) 8885Returns boolean TRUE if @var{i} is an odd number. 8886 8887@item ORD(@var{x}) 8888Returns the ordinal value of its argument. For example, the ordinal 8889value of a character is its @sc{ascii} value (on machines supporting the 8890@sc{ascii} character set). @var{x} must be of an ordered type, which include 8891integral, character and enumerated types. 8892 8893@item SIZE(@var{x}) 8894Returns the size of its argument. @var{x} can be a variable or a type. 8895 8896@item TRUNC(@var{r}) 8897Returns the integral part of @var{r}. 8898 8899@item VAL(@var{t},@var{i}) 8900Returns the member of the type @var{t} whose ordinal value is @var{i}. 8901@end table 8902 8903@quotation 8904@emph{Warning:} Sets and their operations are not yet supported, so 8905@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as 8906an error. 8907@end quotation 8908 8909@cindex Modula-2 constants 8910@node M2 Constants 8911@subsubsection Constants 8912 8913@value{GDBN} allows you to express the constants of Modula-2 in the following 8914ways: 8915 8916@itemize @bullet 8917 8918@item 8919Integer constants are simply a sequence of digits. When used in an 8920expression, a constant is interpreted to be type-compatible with the 8921rest of the expression. Hexadecimal integers are specified by a 8922trailing @samp{H}, and octal integers by a trailing @samp{B}. 8923 8924@item 8925Floating point constants appear as a sequence of digits, followed by a 8926decimal point and another sequence of digits. An optional exponent can 8927then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where 8928@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the 8929digits of the floating point constant must be valid decimal (base 10) 8930digits. 8931 8932@item 8933Character constants consist of a single character enclosed by a pair of 8934like quotes, either single (@code{'}) or double (@code{"}). They may 8935also be expressed by their ordinal value (their @sc{ascii} value, usually) 8936followed by a @samp{C}. 8937 8938@item 8939String constants consist of a sequence of characters enclosed by a 8940pair of like quotes, either single (@code{'}) or double (@code{"}). 8941Escape sequences in the style of C are also allowed. @xref{C 8942Constants, ,C and C@t{++} constants}, for a brief explanation of escape 8943sequences. 8944 8945@item 8946Enumerated constants consist of an enumerated identifier. 8947 8948@item 8949Boolean constants consist of the identifiers @code{TRUE} and 8950@code{FALSE}. 8951 8952@item 8953Pointer constants consist of integral values only. 8954 8955@item 8956Set constants are not yet supported. 8957@end itemize 8958 8959@node M2 Defaults 8960@subsubsection Modula-2 defaults 8961@cindex Modula-2 defaults 8962 8963If type and range checking are set automatically by @value{GDBN}, they 8964both default to @code{on} whenever the working language changes to 8965Modula-2. This happens regardless of whether you or @value{GDBN} 8966selected the working language. 8967 8968If you allow @value{GDBN} to set the language automatically, then entering 8969code compiled from a file whose name ends with @file{.mod} sets the 8970working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} set 8971the language automatically}, for further details. 8972 8973@node Deviations 8974@subsubsection Deviations from standard Modula-2 8975@cindex Modula-2, deviations from 8976 8977A few changes have been made to make Modula-2 programs easier to debug. 8978This is done primarily via loosening its type strictness: 8979 8980@itemize @bullet 8981@item 8982Unlike in standard Modula-2, pointer constants can be formed by 8983integers. This allows you to modify pointer variables during 8984debugging. (In standard Modula-2, the actual address contained in a 8985pointer variable is hidden from you; it can only be modified 8986through direct assignment to another pointer variable or expression that 8987returned a pointer.) 8988 8989@item 8990C escape sequences can be used in strings and characters to represent 8991non-printable characters. @value{GDBN} prints out strings with these 8992escape sequences embedded. Single non-printable characters are 8993printed using the @samp{CHR(@var{nnn})} format. 8994 8995@item 8996The assignment operator (@code{:=}) returns the value of its right-hand 8997argument. 8998 8999@item 9000All built-in procedures both modify @emph{and} return their argument. 9001@end itemize 9002 9003@node M2 Checks 9004@subsubsection Modula-2 type and range checks 9005@cindex Modula-2 checks 9006 9007@quotation 9008@emph{Warning:} in this release, @value{GDBN} does not yet perform type or 9009range checking. 9010@end quotation 9011@c FIXME remove warning when type/range checks added 9012 9013@value{GDBN} considers two Modula-2 variables type equivalent if: 9014 9015@itemize @bullet 9016@item 9017They are of types that have been declared equivalent via a @code{TYPE 9018@var{t1} = @var{t2}} statement 9019 9020@item 9021They have been declared on the same line. (Note: This is true of the 9022@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.) 9023@end itemize 9024 9025As long as type checking is enabled, any attempt to combine variables 9026whose types are not equivalent is an error. 9027 9028Range checking is done on all mathematical operations, assignment, array 9029index bounds, and all built-in functions and procedures. 9030 9031@node M2 Scope 9032@subsubsection The scope operators @code{::} and @code{.} 9033@cindex scope 9034@cindex @code{.}, Modula-2 scope operator 9035@cindex colon, doubled as scope operator 9036@ifinfo 9037@vindex colon-colon@r{, in Modula-2} 9038@c Info cannot handle :: but TeX can. 9039@end ifinfo 9040@iftex 9041@vindex ::@r{, in Modula-2} 9042@end iftex 9043 9044There are a few subtle differences between the Modula-2 scope operator 9045(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have 9046similar syntax: 9047 9048@smallexample 9049 9050@var{module} . @var{id} 9051@var{scope} :: @var{id} 9052@end smallexample 9053 9054@noindent 9055where @var{scope} is the name of a module or a procedure, 9056@var{module} the name of a module, and @var{id} is any declared 9057identifier within your program, except another module. 9058 9059Using the @code{::} operator makes @value{GDBN} search the scope 9060specified by @var{scope} for the identifier @var{id}. If it is not 9061found in the specified scope, then @value{GDBN} searches all scopes 9062enclosing the one specified by @var{scope}. 9063 9064Using the @code{.} operator makes @value{GDBN} search the current scope for 9065the identifier specified by @var{id} that was imported from the 9066definition module specified by @var{module}. With this operator, it is 9067an error if the identifier @var{id} was not imported from definition 9068module @var{module}, or if @var{id} is not an identifier in 9069@var{module}. 9070 9071@node GDB/M2 9072@subsubsection @value{GDBN} and Modula-2 9073 9074Some @value{GDBN} commands have little use when debugging Modula-2 programs. 9075Five subcommands of @code{set print} and @code{show print} apply 9076specifically to C and C@t{++}: @samp{vtbl}, @samp{demangle}, 9077@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four 9078apply to C@t{++}, and the last to the C @code{union} type, which has no direct 9079analogue in Modula-2. 9080 9081The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available 9082with any language, is not useful with Modula-2. Its 9083intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be 9084created in Modula-2 as they can in C or C@t{++}. However, because an 9085address can be specified by an integral constant, the construct 9086@samp{@{@var{type}@}@var{adrexp}} is still useful. 9087 9088@cindex @code{#} in Modula-2 9089In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is 9090interpreted as the beginning of a comment. Use @code{<>} instead. 9091 9092@node Ada 9093@subsection Ada 9094@cindex Ada 9095 9096The extensions made to @value{GDBN} for Ada only support 9097output from the @sc{gnu} Ada (GNAT) compiler. 9098Other Ada compilers are not currently supported, and 9099attempting to debug executables produced by them is most likely 9100to be difficult. 9101 9102 9103@cindex expressions in Ada 9104@menu 9105* Ada Mode Intro:: General remarks on the Ada syntax 9106 and semantics supported by Ada mode 9107 in @value{GDBN}. 9108* Omissions from Ada:: Restrictions on the Ada expression syntax. 9109* Additions to Ada:: Extensions of the Ada expression syntax. 9110* Stopping Before Main Program:: Debugging the program during elaboration. 9111* Ada Glitches:: Known peculiarities of Ada mode. 9112@end menu 9113 9114@node Ada Mode Intro 9115@subsubsection Introduction 9116@cindex Ada mode, general 9117 9118The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression 9119syntax, with some extensions. 9120The philosophy behind the design of this subset is 9121 9122@itemize @bullet 9123@item 9124That @value{GDBN} should provide basic literals and access to operations for 9125arithmetic, dereferencing, field selection, indexing, and subprogram calls, 9126leaving more sophisticated computations to subprograms written into the 9127program (which therefore may be called from @value{GDBN}). 9128 9129@item 9130That type safety and strict adherence to Ada language restrictions 9131are not particularly important to the @value{GDBN} user. 9132 9133@item 9134That brevity is important to the @value{GDBN} user. 9135@end itemize 9136 9137Thus, for brevity, the debugger acts as if there were 9138implicit @code{with} and @code{use} clauses in effect for all user-written 9139packages, making it unnecessary to fully qualify most names with 9140their packages, regardless of context. Where this causes ambiguity, 9141@value{GDBN} asks the user's intent. 9142 9143The debugger will start in Ada mode if it detects an Ada main program. 9144As for other languages, it will enter Ada mode when stopped in a program that 9145was translated from an Ada source file. 9146 9147While in Ada mode, you may use `@t{--}' for comments. This is useful 9148mostly for documenting command files. The standard @value{GDBN} comment 9149(@samp{#}) still works at the beginning of a line in Ada mode, but not in the 9150middle (to allow based literals). 9151 9152The debugger supports limited overloading. Given a subprogram call in which 9153the function symbol has multiple definitions, it will use the number of 9154actual parameters and some information about their types to attempt to narrow 9155the set of definitions. It also makes very limited use of context, preferring 9156procedures to functions in the context of the @code{call} command, and 9157functions to procedures elsewhere. 9158 9159@node Omissions from Ada 9160@subsubsection Omissions from Ada 9161@cindex Ada, omissions from 9162 9163Here are the notable omissions from the subset: 9164 9165@itemize @bullet 9166@item 9167Only a subset of the attributes are supported: 9168 9169@itemize @minus 9170@item 9171@t{'First}, @t{'Last}, and @t{'Length} 9172 on array objects (not on types and subtypes). 9173 9174@item 9175@t{'Min} and @t{'Max}. 9176 9177@item 9178@t{'Pos} and @t{'Val}. 9179 9180@item 9181@t{'Tag}. 9182 9183@item 9184@t{'Range} on array objects (not subtypes), but only as the right 9185operand of the membership (@code{in}) operator. 9186 9187@item 9188@t{'Access}, @t{'Unchecked_Access}, and 9189@t{'Unrestricted_Access} (a GNAT extension). 9190 9191@item 9192@t{'Address}. 9193@end itemize 9194 9195@item 9196The names in 9197@code{Characters.Latin_1} are not available and 9198concatenation is not implemented. Thus, escape characters in strings are 9199not currently available. 9200 9201@item 9202Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise 9203equality of representations. They will generally work correctly 9204for strings and arrays whose elements have integer or enumeration types. 9205They may not work correctly for arrays whose element 9206types have user-defined equality, for arrays of real values 9207(in particular, IEEE-conformant floating point, because of negative 9208zeroes and NaNs), and for arrays whose elements contain unused bits with 9209indeterminate values. 9210 9211@item 9212The other component-by-component array operations (@code{and}, @code{or}, 9213@code{xor}, @code{not}, and relational tests other than equality) 9214are not implemented. 9215 9216@item 9217There are no record or array aggregates. 9218 9219@item 9220Calls to dispatching subprograms are not implemented. 9221 9222@item 9223The overloading algorithm is much more limited (i.e., less selective) 9224than that of real Ada. It makes only limited use of the context in which a subexpression 9225appears to resolve its meaning, and it is much looser in its rules for allowing 9226type matches. As a result, some function calls will be ambiguous, and the user 9227will be asked to choose the proper resolution. 9228 9229@item 9230The @code{new} operator is not implemented. 9231 9232@item 9233Entry calls are not implemented. 9234 9235@item 9236Aside from printing, arithmetic operations on the native VAX floating-point 9237formats are not supported. 9238 9239@item 9240It is not possible to slice a packed array. 9241@end itemize 9242 9243@node Additions to Ada 9244@subsubsection Additions to Ada 9245@cindex Ada, deviations from 9246 9247As it does for other languages, @value{GDBN} makes certain generic 9248extensions to Ada (@pxref{Expressions}): 9249 9250@itemize @bullet 9251@item 9252If the expression @var{E} is a variable residing in memory 9253(typically a local variable or array element) and @var{N} is 9254a positive integer, then @code{@var{E}@@@var{N}} displays the values of 9255@var{E} and the @var{N}-1 adjacent variables following it in memory as an array. 9256In Ada, this operator is generally not necessary, since its prime use 9257is in displaying parts of an array, and slicing will usually do this in Ada. 9258However, there are occasional uses when debugging programs 9259in which certain debugging information has been optimized away. 9260 9261@item 9262@code{@var{B}::@var{var}} means ``the variable named @var{var} that appears 9263in function or file @var{B}.'' When @var{B} is a file name, you must typically 9264surround it in single quotes. 9265 9266@item 9267The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type 9268@var{type} that appears at address @var{addr}.'' 9269 9270@item 9271A name starting with @samp{$} is a convenience variable 9272(@pxref{Convenience Vars}) or a machine register (@pxref{Registers}). 9273@end itemize 9274 9275In addition, @value{GDBN} provides a few other shortcuts and outright additions specific 9276to Ada: 9277 9278@itemize @bullet 9279@item 9280The assignment statement is allowed as an expression, returning 9281its right-hand operand as its value. Thus, you may enter 9282 9283@smallexample 9284set x := y + 3 9285print A(tmp := y + 1) 9286@end smallexample 9287 9288@item 9289The semicolon is allowed as an ``operator,'' returning as its value 9290the value of its right-hand operand. 9291This allows, for example, 9292complex conditional breaks: 9293 9294@smallexample 9295break f 9296condition 1 (report(i); k += 1; A(k) > 100) 9297@end smallexample 9298 9299@item 9300Rather than use catenation and symbolic character names to introduce special 9301characters into strings, one may instead use a special bracket notation, 9302which is also used to print strings. A sequence of characters of the form 9303@samp{["@var{XX}"]} within a string or character literal denotes the 9304(single) character whose numeric encoding is @var{XX} in hexadecimal. The 9305sequence of characters @samp{["""]} also denotes a single quotation mark 9306in strings. For example, 9307@smallexample 9308 "One line.["0a"]Next line.["0a"]" 9309@end smallexample 9310@noindent 9311contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF}) after each 9312period. 9313 9314@item 9315The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and 9316@t{'Max} is optional (and is ignored in any case). For example, it is valid 9317to write 9318 9319@smallexample 9320print 'max(x, y) 9321@end smallexample 9322 9323@item 9324When printing arrays, @value{GDBN} uses positional notation when the 9325array has a lower bound of 1, and uses a modified named notation otherwise. 9326For example, a one-dimensional array of three integers with a lower bound of 3 might print as 9327 9328@smallexample 9329(3 => 10, 17, 1) 9330@end smallexample 9331 9332@noindent 9333That is, in contrast to valid Ada, only the first component has a @code{=>} 9334clause. 9335 9336@item 9337You may abbreviate attributes in expressions with any unique, 9338multi-character subsequence of 9339their names (an exact match gets preference). 9340For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh} 9341in place of @t{a'length}. 9342 9343@item 9344@cindex quoting Ada internal identifiers 9345Since Ada is case-insensitive, the debugger normally maps identifiers you type 9346to lower case. The GNAT compiler uses upper-case characters for 9347some of its internal identifiers, which are normally of no interest to users. 9348For the rare occasions when you actually have to look at them, 9349enclose them in angle brackets to avoid the lower-case mapping. 9350For example, 9351@smallexample 9352@value{GDBP} print <JMPBUF_SAVE>[0] 9353@end smallexample 9354 9355@item 9356Printing an object of class-wide type or dereferencing an 9357access-to-class-wide value will display all the components of the object's 9358specific type (as indicated by its run-time tag). Likewise, component 9359selection on such a value will operate on the specific type of the 9360object. 9361 9362@end itemize 9363 9364@node Stopping Before Main Program 9365@subsubsection Stopping at the Very Beginning 9366 9367@cindex breakpointing Ada elaboration code 9368It is sometimes necessary to debug the program during elaboration, and 9369before reaching the main procedure. 9370As defined in the Ada Reference 9371Manual, the elaboration code is invoked from a procedure called 9372@code{adainit}. To run your program up to the beginning of 9373elaboration, simply use the following two commands: 9374@code{tbreak adainit} and @code{run}. 9375 9376@node Ada Glitches 9377@subsubsection Known Peculiarities of Ada Mode 9378@cindex Ada, problems 9379 9380Besides the omissions listed previously (@pxref{Omissions from Ada}), 9381we know of several problems with and limitations of Ada mode in 9382@value{GDBN}, 9383some of which will be fixed with planned future releases of the debugger 9384and the GNU Ada compiler. 9385 9386@itemize @bullet 9387@item 9388Currently, the debugger 9389has insufficient information to determine whether certain pointers represent 9390pointers to objects or the objects themselves. 9391Thus, the user may have to tack an extra @code{.all} after an expression 9392to get it printed properly. 9393 9394@item 9395Static constants that the compiler chooses not to materialize as objects in 9396storage are invisible to the debugger. 9397 9398@item 9399Named parameter associations in function argument lists are ignored (the 9400argument lists are treated as positional). 9401 9402@item 9403Many useful library packages are currently invisible to the debugger. 9404 9405@item 9406Fixed-point arithmetic, conversions, input, and output is carried out using 9407floating-point arithmetic, and may give results that only approximate those on 9408the host machine. 9409 9410@item 9411The type of the @t{'Address} attribute may not be @code{System.Address}. 9412 9413@item 9414The GNAT compiler never generates the prefix @code{Standard} for any of 9415the standard symbols defined by the Ada language. @value{GDBN} knows about 9416this: it will strip the prefix from names when you use it, and will never 9417look for a name you have so qualified among local symbols, nor match against 9418symbols in other packages or subprograms. If you have 9419defined entities anywhere in your program other than parameters and 9420local variables whose simple names match names in @code{Standard}, 9421GNAT's lack of qualification here can cause confusion. When this happens, 9422you can usually resolve the confusion 9423by qualifying the problematic names with package 9424@code{Standard} explicitly. 9425@end itemize 9426 9427@node Unsupported languages 9428@section Unsupported languages 9429 9430@cindex unsupported languages 9431@cindex minimal language 9432In addition to the other fully-supported programming languages, 9433@value{GDBN} also provides a pseudo-language, called @code{minimal}. 9434It does not represent a real programming language, but provides a set 9435of capabilities close to what the C or assembly languages provide. 9436This should allow most simple operations to be performed while debugging 9437an application that uses a language currently not supported by @value{GDBN}. 9438 9439If the language is set to @code{auto}, @value{GDBN} will automatically 9440select this language if the current frame corresponds to an unsupported 9441language. 9442 9443@node Symbols 9444@chapter Examining the Symbol Table 9445 9446The commands described in this chapter allow you to inquire about the 9447symbols (names of variables, functions and types) defined in your 9448program. This information is inherent in the text of your program and 9449does not change as your program executes. @value{GDBN} finds it in your 9450program's symbol table, in the file indicated when you started @value{GDBN} 9451(@pxref{File Options, ,Choosing files}), or by one of the 9452file-management commands (@pxref{Files, ,Commands to specify files}). 9453 9454@cindex symbol names 9455@cindex names of symbols 9456@cindex quoting names 9457Occasionally, you may need to refer to symbols that contain unusual 9458characters, which @value{GDBN} ordinarily treats as word delimiters. The 9459most frequent case is in referring to static variables in other 9460source files (@pxref{Variables,,Program variables}). File names 9461are recorded in object files as debugging symbols, but @value{GDBN} would 9462ordinarily parse a typical file name, like @file{foo.c}, as the three words 9463@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize 9464@samp{foo.c} as a single symbol, enclose it in single quotes; for example, 9465 9466@smallexample 9467p 'foo.c'::x 9468@end smallexample 9469 9470@noindent 9471looks up the value of @code{x} in the scope of the file @file{foo.c}. 9472 9473@table @code 9474@kindex info address 9475@cindex address of a symbol 9476@item info address @var{symbol} 9477Describe where the data for @var{symbol} is stored. For a register 9478variable, this says which register it is kept in. For a non-register 9479local variable, this prints the stack-frame offset at which the variable 9480is always stored. 9481 9482Note the contrast with @samp{print &@var{symbol}}, which does not work 9483at all for a register variable, and for a stack local variable prints 9484the exact address of the current instantiation of the variable. 9485 9486@kindex info symbol 9487@cindex symbol from address 9488@item info symbol @var{addr} 9489Print the name of a symbol which is stored at the address @var{addr}. 9490If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the 9491nearest symbol and an offset from it: 9492 9493@smallexample 9494(@value{GDBP}) info symbol 0x54320 9495_initialize_vx + 396 in section .text 9496@end smallexample 9497 9498@noindent 9499This is the opposite of the @code{info address} command. You can use 9500it to find out the name of a variable or a function given its address. 9501 9502@kindex whatis 9503@item whatis @var{expr} 9504Print the data type of expression @var{expr}. @var{expr} is not 9505actually evaluated, and any side-effecting operations (such as 9506assignments or function calls) inside it do not take place. 9507@xref{Expressions, ,Expressions}. 9508 9509@item whatis 9510Print the data type of @code{$}, the last value in the value history. 9511 9512@kindex ptype 9513@item ptype @var{typename} 9514Print a description of data type @var{typename}. @var{typename} may be 9515the name of a type, or for C code it may have the form @samp{class 9516@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union 9517@var{union-tag}} or @samp{enum @var{enum-tag}}. 9518 9519@item ptype @var{expr} 9520@itemx ptype 9521Print a description of the type of expression @var{expr}. @code{ptype} 9522differs from @code{whatis} by printing a detailed description, instead 9523of just the name of the type. 9524 9525For example, for this variable declaration: 9526 9527@smallexample 9528struct complex @{double real; double imag;@} v; 9529@end smallexample 9530 9531@noindent 9532the two commands give this output: 9533 9534@smallexample 9535@group 9536(@value{GDBP}) whatis v 9537type = struct complex 9538(@value{GDBP}) ptype v 9539type = struct complex @{ 9540 double real; 9541 double imag; 9542@} 9543@end group 9544@end smallexample 9545 9546@noindent 9547As with @code{whatis}, using @code{ptype} without an argument refers to 9548the type of @code{$}, the last value in the value history. 9549 9550@kindex info types 9551@item info types @var{regexp} 9552@itemx info types 9553Print a brief description of all types whose names match @var{regexp} 9554(or all types in your program, if you supply no argument). Each 9555complete typename is matched as though it were a complete line; thus, 9556@samp{i type value} gives information on all types in your program whose 9557names include the string @code{value}, but @samp{i type ^value$} gives 9558information only on types whose complete name is @code{value}. 9559 9560This command differs from @code{ptype} in two ways: first, like 9561@code{whatis}, it does not print a detailed description; second, it 9562lists all source files where a type is defined. 9563 9564@kindex info scope 9565@cindex local variables 9566@item info scope @var{addr} 9567List all the variables local to a particular scope. This command 9568accepts a location---a function name, a source line, or an address 9569preceded by a @samp{*}, and prints all the variables local to the 9570scope defined by that location. For example: 9571 9572@smallexample 9573(@value{GDBP}) @b{info scope command_line_handler} 9574Scope for command_line_handler: 9575Symbol rl is an argument at stack/frame offset 8, length 4. 9576Symbol linebuffer is in static storage at address 0x150a18, length 4. 9577Symbol linelength is in static storage at address 0x150a1c, length 4. 9578Symbol p is a local variable in register $esi, length 4. 9579Symbol p1 is a local variable in register $ebx, length 4. 9580Symbol nline is a local variable in register $edx, length 4. 9581Symbol repeat is a local variable at frame offset -8, length 4. 9582@end smallexample 9583 9584@noindent 9585This command is especially useful for determining what data to collect 9586during a @dfn{trace experiment}, see @ref{Tracepoint Actions, 9587collect}. 9588 9589@kindex info source 9590@item info source 9591Show information about the current source file---that is, the source file for 9592the function containing the current point of execution: 9593@itemize @bullet 9594@item 9595the name of the source file, and the directory containing it, 9596@item 9597the directory it was compiled in, 9598@item 9599its length, in lines, 9600@item 9601which programming language it is written in, 9602@item 9603whether the executable includes debugging information for that file, and 9604if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and 9605@item 9606whether the debugging information includes information about 9607preprocessor macros. 9608@end itemize 9609 9610 9611@kindex info sources 9612@item info sources 9613Print the names of all source files in your program for which there is 9614debugging information, organized into two lists: files whose symbols 9615have already been read, and files whose symbols will be read when needed. 9616 9617@kindex info functions 9618@item info functions 9619Print the names and data types of all defined functions. 9620 9621@item info functions @var{regexp} 9622Print the names and data types of all defined functions 9623whose names contain a match for regular expression @var{regexp}. 9624Thus, @samp{info fun step} finds all functions whose names 9625include @code{step}; @samp{info fun ^step} finds those whose names 9626start with @code{step}. If a function name contains characters 9627that conflict with the regular expression language (eg. 9628@samp{operator*()}), they may be quoted with a backslash. 9629 9630@kindex info variables 9631@item info variables 9632Print the names and data types of all variables that are declared 9633outside of functions (i.e.@: excluding local variables). 9634 9635@item info variables @var{regexp} 9636Print the names and data types of all variables (except for local 9637variables) whose names contain a match for regular expression 9638@var{regexp}. 9639 9640@kindex info classes 9641@item info classes 9642@itemx info classes @var{regexp} 9643Display all Objective-C classes in your program, or 9644(with the @var{regexp} argument) all those matching a particular regular 9645expression. 9646 9647@kindex info selectors 9648@item info selectors 9649@itemx info selectors @var{regexp} 9650Display all Objective-C selectors in your program, or 9651(with the @var{regexp} argument) all those matching a particular regular 9652expression. 9653 9654@ignore 9655This was never implemented. 9656@kindex info methods 9657@item info methods 9658@itemx info methods @var{regexp} 9659The @code{info methods} command permits the user to examine all defined 9660methods within C@t{++} program, or (with the @var{regexp} argument) a 9661specific set of methods found in the various C@t{++} classes. Many 9662C@t{++} classes provide a large number of methods. Thus, the output 9663from the @code{ptype} command can be overwhelming and hard to use. The 9664@code{info-methods} command filters the methods, printing only those 9665which match the regular-expression @var{regexp}. 9666@end ignore 9667 9668@cindex reloading symbols 9669Some systems allow individual object files that make up your program to 9670be replaced without stopping and restarting your program. For example, 9671in VxWorks you can simply recompile a defective object file and keep on 9672running. If you are running on one of these systems, you can allow 9673@value{GDBN} to reload the symbols for automatically relinked modules: 9674 9675@table @code 9676@kindex set symbol-reloading 9677@item set symbol-reloading on 9678Replace symbol definitions for the corresponding source file when an 9679object file with a particular name is seen again. 9680 9681@item set symbol-reloading off 9682Do not replace symbol definitions when encountering object files of the 9683same name more than once. This is the default state; if you are not 9684running on a system that permits automatic relinking of modules, you 9685should leave @code{symbol-reloading} off, since otherwise @value{GDBN} 9686may discard symbols when linking large programs, that may contain 9687several modules (from different directories or libraries) with the same 9688name. 9689 9690@kindex show symbol-reloading 9691@item show symbol-reloading 9692Show the current @code{on} or @code{off} setting. 9693@end table 9694 9695@kindex set opaque-type-resolution 9696@item set opaque-type-resolution on 9697Tell @value{GDBN} to resolve opaque types. An opaque type is a type 9698declared as a pointer to a @code{struct}, @code{class}, or 9699@code{union}---for example, @code{struct MyType *}---that is used in one 9700source file although the full declaration of @code{struct MyType} is in 9701another source file. The default is on. 9702 9703A change in the setting of this subcommand will not take effect until 9704the next time symbols for a file are loaded. 9705 9706@item set opaque-type-resolution off 9707Tell @value{GDBN} not to resolve opaque types. In this case, the type 9708is printed as follows: 9709@smallexample 9710@{<no data fields>@} 9711@end smallexample 9712 9713@kindex show opaque-type-resolution 9714@item show opaque-type-resolution 9715Show whether opaque types are resolved or not. 9716 9717@kindex maint print symbols 9718@cindex symbol dump 9719@kindex maint print psymbols 9720@cindex partial symbol dump 9721@item maint print symbols @var{filename} 9722@itemx maint print psymbols @var{filename} 9723@itemx maint print msymbols @var{filename} 9724Write a dump of debugging symbol data into the file @var{filename}. 9725These commands are used to debug the @value{GDBN} symbol-reading code. Only 9726symbols with debugging data are included. If you use @samp{maint print 9727symbols}, @value{GDBN} includes all the symbols for which it has already 9728collected full details: that is, @var{filename} reflects symbols for 9729only those files whose symbols @value{GDBN} has read. You can use the 9730command @code{info sources} to find out which files these are. If you 9731use @samp{maint print psymbols} instead, the dump shows information about 9732symbols that @value{GDBN} only knows partially---that is, symbols defined in 9733files that @value{GDBN} has skimmed, but not yet read completely. Finally, 9734@samp{maint print msymbols} dumps just the minimal symbol information 9735required for each object file from which @value{GDBN} has read some symbols. 9736@xref{Files, ,Commands to specify files}, for a discussion of how 9737@value{GDBN} reads symbols (in the description of @code{symbol-file}). 9738 9739@kindex maint info symtabs 9740@kindex maint info psymtabs 9741@cindex listing @value{GDBN}'s internal symbol tables 9742@cindex symbol tables, listing @value{GDBN}'s internal 9743@cindex full symbol tables, listing @value{GDBN}'s internal 9744@cindex partial symbol tables, listing @value{GDBN}'s internal 9745@item maint info symtabs @r{[} @var{regexp} @r{]} 9746@itemx maint info psymtabs @r{[} @var{regexp} @r{]} 9747 9748List the @code{struct symtab} or @code{struct partial_symtab} 9749structures whose names match @var{regexp}. If @var{regexp} is not 9750given, list them all. The output includes expressions which you can 9751copy into a @value{GDBN} debugging this one to examine a particular 9752structure in more detail. For example: 9753 9754@smallexample 9755(@value{GDBP}) maint info psymtabs dwarf2read 9756@{ objfile /home/gnu/build/gdb/gdb 9757 ((struct objfile *) 0x82e69d0) 9758 @{ psymtab /home/gnu/src/gdb/dwarf2read.c 9759 ((struct partial_symtab *) 0x8474b10) 9760 readin no 9761 fullname (null) 9762 text addresses 0x814d3c8 -- 0x8158074 9763 globals (* (struct partial_symbol **) 0x8507a08 @@ 9) 9764 statics (* (struct partial_symbol **) 0x40e95b78 @@ 2882) 9765 dependencies (none) 9766 @} 9767@} 9768(@value{GDBP}) maint info symtabs 9769(@value{GDBP}) 9770@end smallexample 9771@noindent 9772We see that there is one partial symbol table whose filename contains 9773the string @samp{dwarf2read}, belonging to the @samp{gdb} executable; 9774and we see that @value{GDBN} has not read in any symtabs yet at all. 9775If we set a breakpoint on a function, that will cause @value{GDBN} to 9776read the symtab for the compilation unit containing that function: 9777 9778@smallexample 9779(@value{GDBP}) break dwarf2_psymtab_to_symtab 9780Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, 9781line 1574. 9782(@value{GDBP}) maint info symtabs 9783@{ objfile /home/gnu/build/gdb/gdb 9784 ((struct objfile *) 0x82e69d0) 9785 @{ symtab /home/gnu/src/gdb/dwarf2read.c 9786 ((struct symtab *) 0x86c1f38) 9787 dirname (null) 9788 fullname (null) 9789 blockvector ((struct blockvector *) 0x86c1bd0) (primary) 9790 debugformat DWARF 2 9791 @} 9792@} 9793(@value{GDBP}) 9794@end smallexample 9795@end table 9796 9797 9798@node Altering 9799@chapter Altering Execution 9800 9801Once you think you have found an error in your program, you might want to 9802find out for certain whether correcting the apparent error would lead to 9803correct results in the rest of the run. You can find the answer by 9804experiment, using the @value{GDBN} features for altering execution of the 9805program. 9806 9807For example, you can store new values into variables or memory 9808locations, give your program a signal, restart it at a different 9809address, or even return prematurely from a function. 9810 9811@menu 9812* Assignment:: Assignment to variables 9813* Jumping:: Continuing at a different address 9814* Signaling:: Giving your program a signal 9815* Returning:: Returning from a function 9816* Calling:: Calling your program's functions 9817* Patching:: Patching your program 9818@end menu 9819 9820@node Assignment 9821@section Assignment to variables 9822 9823@cindex assignment 9824@cindex setting variables 9825To alter the value of a variable, evaluate an assignment expression. 9826@xref{Expressions, ,Expressions}. For example, 9827 9828@smallexample 9829print x=4 9830@end smallexample 9831 9832@noindent 9833stores the value 4 into the variable @code{x}, and then prints the 9834value of the assignment expression (which is 4). 9835@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more 9836information on operators in supported languages. 9837 9838@kindex set variable 9839@cindex variables, setting 9840If you are not interested in seeing the value of the assignment, use the 9841@code{set} command instead of the @code{print} command. @code{set} is 9842really the same as @code{print} except that the expression's value is 9843not printed and is not put in the value history (@pxref{Value History, 9844,Value history}). The expression is evaluated only for its effects. 9845 9846If the beginning of the argument string of the @code{set} command 9847appears identical to a @code{set} subcommand, use the @code{set 9848variable} command instead of just @code{set}. This command is identical 9849to @code{set} except for its lack of subcommands. For example, if your 9850program has a variable @code{width}, you get an error if you try to set 9851a new value with just @samp{set width=13}, because @value{GDBN} has the 9852command @code{set width}: 9853 9854@smallexample 9855(@value{GDBP}) whatis width 9856type = double 9857(@value{GDBP}) p width 9858$4 = 13 9859(@value{GDBP}) set width=47 9860Invalid syntax in expression. 9861@end smallexample 9862 9863@noindent 9864The invalid expression, of course, is @samp{=47}. In 9865order to actually set the program's variable @code{width}, use 9866 9867@smallexample 9868(@value{GDBP}) set var width=47 9869@end smallexample 9870 9871Because the @code{set} command has many subcommands that can conflict 9872with the names of program variables, it is a good idea to use the 9873@code{set variable} command instead of just @code{set}. For example, if 9874your program has a variable @code{g}, you run into problems if you try 9875to set a new value with just @samp{set g=4}, because @value{GDBN} has 9876the command @code{set gnutarget}, abbreviated @code{set g}: 9877 9878@smallexample 9879@group 9880(@value{GDBP}) whatis g 9881type = double 9882(@value{GDBP}) p g 9883$1 = 1 9884(@value{GDBP}) set g=4 9885(@value{GDBP}) p g 9886$2 = 1 9887(@value{GDBP}) r 9888The program being debugged has been started already. 9889Start it from the beginning? (y or n) y 9890Starting program: /home/smith/cc_progs/a.out 9891"/home/smith/cc_progs/a.out": can't open to read symbols: 9892 Invalid bfd target. 9893(@value{GDBP}) show g 9894The current BFD target is "=4". 9895@end group 9896@end smallexample 9897 9898@noindent 9899The program variable @code{g} did not change, and you silently set the 9900@code{gnutarget} to an invalid value. In order to set the variable 9901@code{g}, use 9902 9903@smallexample 9904(@value{GDBP}) set var g=4 9905@end smallexample 9906 9907@value{GDBN} allows more implicit conversions in assignments than C; you can 9908freely store an integer value into a pointer variable or vice versa, 9909and you can convert any structure to any other structure that is the 9910same length or shorter. 9911@comment FIXME: how do structs align/pad in these conversions? 9912@comment /doc@cygnus.com 18dec1990 9913 9914To store values into arbitrary places in memory, use the @samp{@{@dots{}@}} 9915construct to generate a value of specified type at a specified address 9916(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers 9917to memory location @code{0x83040} as an integer (which implies a certain size 9918and representation in memory), and 9919 9920@smallexample 9921set @{int@}0x83040 = 4 9922@end smallexample 9923 9924@noindent 9925stores the value 4 into that memory location. 9926 9927@node Jumping 9928@section Continuing at a different address 9929 9930Ordinarily, when you continue your program, you do so at the place where 9931it stopped, with the @code{continue} command. You can instead continue at 9932an address of your own choosing, with the following commands: 9933 9934@table @code 9935@kindex jump 9936@item jump @var{linespec} 9937Resume execution at line @var{linespec}. Execution stops again 9938immediately if there is a breakpoint there. @xref{List, ,Printing 9939source lines}, for a description of the different forms of 9940@var{linespec}. It is common practice to use the @code{tbreak} command 9941in conjunction with @code{jump}. @xref{Set Breaks, ,Setting 9942breakpoints}. 9943 9944The @code{jump} command does not change the current stack frame, or 9945the stack pointer, or the contents of any memory location or any 9946register other than the program counter. If line @var{linespec} is in 9947a different function from the one currently executing, the results may 9948be bizarre if the two functions expect different patterns of arguments or 9949of local variables. For this reason, the @code{jump} command requests 9950confirmation if the specified line is not in the function currently 9951executing. However, even bizarre results are predictable if you are 9952well acquainted with the machine-language code of your program. 9953 9954@item jump *@var{address} 9955Resume execution at the instruction at address @var{address}. 9956@end table 9957 9958@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt. 9959On many systems, you can get much the same effect as the @code{jump} 9960command by storing a new value into the register @code{$pc}. The 9961difference is that this does not start your program running; it only 9962changes the address of where it @emph{will} run when you continue. For 9963example, 9964 9965@smallexample 9966set $pc = 0x485 9967@end smallexample 9968 9969@noindent 9970makes the next @code{continue} command or stepping command execute at 9971address @code{0x485}, rather than at the address where your program stopped. 9972@xref{Continuing and Stepping, ,Continuing and stepping}. 9973 9974The most common occasion to use the @code{jump} command is to back 9975up---perhaps with more breakpoints set---over a portion of a program 9976that has already executed, in order to examine its execution in more 9977detail. 9978 9979@c @group 9980@node Signaling 9981@section Giving your program a signal 9982 9983@table @code 9984@kindex signal 9985@item signal @var{signal} 9986Resume execution where your program stopped, but immediately give it the 9987signal @var{signal}. @var{signal} can be the name or the number of a 9988signal. For example, on many systems @code{signal 2} and @code{signal 9989SIGINT} are both ways of sending an interrupt signal. 9990 9991Alternatively, if @var{signal} is zero, continue execution without 9992giving a signal. This is useful when your program stopped on account of 9993a signal and would ordinary see the signal when resumed with the 9994@code{continue} command; @samp{signal 0} causes it to resume without a 9995signal. 9996 9997@code{signal} does not repeat when you press @key{RET} a second time 9998after executing the command. 9999@end table 10000@c @end group 10001 10002Invoking the @code{signal} command is not the same as invoking the 10003@code{kill} utility from the shell. Sending a signal with @code{kill} 10004causes @value{GDBN} to decide what to do with the signal depending on 10005the signal handling tables (@pxref{Signals}). The @code{signal} command 10006passes the signal directly to your program. 10007 10008 10009@node Returning 10010@section Returning from a function 10011 10012@table @code 10013@cindex returning from a function 10014@kindex return 10015@item return 10016@itemx return @var{expression} 10017You can cancel execution of a function call with the @code{return} 10018command. If you give an 10019@var{expression} argument, its value is used as the function's return 10020value. 10021@end table 10022 10023When you use @code{return}, @value{GDBN} discards the selected stack frame 10024(and all frames within it). You can think of this as making the 10025discarded frame return prematurely. If you wish to specify a value to 10026be returned, give that value as the argument to @code{return}. 10027 10028This pops the selected stack frame (@pxref{Selection, ,Selecting a 10029frame}), and any other frames inside of it, leaving its caller as the 10030innermost remaining frame. That frame becomes selected. The 10031specified value is stored in the registers used for returning values 10032of functions. 10033 10034The @code{return} command does not resume execution; it leaves the 10035program stopped in the state that would exist if the function had just 10036returned. In contrast, the @code{finish} command (@pxref{Continuing 10037and Stepping, ,Continuing and stepping}) resumes execution until the 10038selected stack frame returns naturally. 10039 10040@node Calling 10041@section Calling program functions 10042 10043@cindex calling functions 10044@kindex call 10045@table @code 10046@item call @var{expr} 10047Evaluate the expression @var{expr} without displaying @code{void} 10048returned values. 10049@end table 10050 10051You can use this variant of the @code{print} command if you want to 10052execute a function from your program, but without cluttering the output 10053with @code{void} returned values. If the result is not void, it 10054is printed and saved in the value history. 10055 10056@node Patching 10057@section Patching programs 10058 10059@cindex patching binaries 10060@cindex writing into executables 10061@cindex writing into corefiles 10062 10063By default, @value{GDBN} opens the file containing your program's 10064executable code (or the corefile) read-only. This prevents accidental 10065alterations to machine code; but it also prevents you from intentionally 10066patching your program's binary. 10067 10068If you'd like to be able to patch the binary, you can specify that 10069explicitly with the @code{set write} command. For example, you might 10070want to turn on internal debugging flags, or even to make emergency 10071repairs. 10072 10073@table @code 10074@kindex set write 10075@item set write on 10076@itemx set write off 10077If you specify @samp{set write on}, @value{GDBN} opens executable and 10078core files for both reading and writing; if you specify @samp{set write 10079off} (the default), @value{GDBN} opens them read-only. 10080 10081If you have already loaded a file, you must load it again (using the 10082@code{exec-file} or @code{core-file} command) after changing @code{set 10083write}, for your new setting to take effect. 10084 10085@item show write 10086@kindex show write 10087Display whether executable files and core files are opened for writing 10088as well as reading. 10089@end table 10090 10091@node GDB Files 10092@chapter @value{GDBN} Files 10093 10094@value{GDBN} needs to know the file name of the program to be debugged, 10095both in order to read its symbol table and in order to start your 10096program. To debug a core dump of a previous run, you must also tell 10097@value{GDBN} the name of the core dump file. 10098 10099@menu 10100* Files:: Commands to specify files 10101* Separate Debug Files:: Debugging information in separate files 10102* Symbol Errors:: Errors reading symbol files 10103@end menu 10104 10105@node Files 10106@section Commands to specify files 10107 10108@cindex symbol table 10109@cindex core dump file 10110 10111You may want to specify executable and core dump file names. The usual 10112way to do this is at start-up time, using the arguments to 10113@value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and 10114Out of @value{GDBN}}). 10115 10116Occasionally it is necessary to change to a different file during a 10117@value{GDBN} session. Or you may run @value{GDBN} and forget to specify 10118a file you want to use. In these situations the @value{GDBN} commands 10119to specify new files are useful. 10120 10121@table @code 10122@cindex executable file 10123@kindex file 10124@item file @var{filename} 10125Use @var{filename} as the program to be debugged. It is read for its 10126symbols and for the contents of pure memory. It is also the program 10127executed when you use the @code{run} command. If you do not specify a 10128directory and the file is not found in the @value{GDBN} working directory, 10129@value{GDBN} uses the environment variable @code{PATH} as a list of 10130directories to search, just as the shell does when looking for a program 10131to run. You can change the value of this variable, for both @value{GDBN} 10132and your program, using the @code{path} command. 10133 10134On systems with memory-mapped files, an auxiliary file named 10135@file{@var{filename}.syms} may hold symbol table information for 10136@var{filename}. If so, @value{GDBN} maps in the symbol table from 10137@file{@var{filename}.syms}, starting up more quickly. See the 10138descriptions of the file options @samp{-mapped} and @samp{-readnow} 10139(available on the command line, and with the commands @code{file}, 10140@code{symbol-file}, or @code{add-symbol-file}, described below), 10141for more information. 10142 10143@item file 10144@code{file} with no argument makes @value{GDBN} discard any information it 10145has on both executable file and the symbol table. 10146 10147@kindex exec-file 10148@item exec-file @r{[} @var{filename} @r{]} 10149Specify that the program to be run (but not the symbol table) is found 10150in @var{filename}. @value{GDBN} searches the environment variable @code{PATH} 10151if necessary to locate your program. Omitting @var{filename} means to 10152discard information on the executable file. 10153 10154@kindex symbol-file 10155@item symbol-file @r{[} @var{filename} @r{]} 10156Read symbol table information from file @var{filename}. @code{PATH} is 10157searched when necessary. Use the @code{file} command to get both symbol 10158table and program to run from the same file. 10159 10160@code{symbol-file} with no argument clears out @value{GDBN} information on your 10161program's symbol table. 10162 10163The @code{symbol-file} command causes @value{GDBN} to forget the contents 10164of its convenience variables, the value history, and all breakpoints and 10165auto-display expressions. This is because they may contain pointers to 10166the internal data recording symbols and data types, which are part of 10167the old symbol table data being discarded inside @value{GDBN}. 10168 10169@code{symbol-file} does not repeat if you press @key{RET} again after 10170executing it once. 10171 10172When @value{GDBN} is configured for a particular environment, it 10173understands debugging information in whatever format is the standard 10174generated for that environment; you may use either a @sc{gnu} compiler, or 10175other compilers that adhere to the local conventions. 10176Best results are usually obtained from @sc{gnu} compilers; for example, 10177using @code{@value{GCC}} you can generate debugging information for 10178optimized code. 10179 10180For most kinds of object files, with the exception of old SVR3 systems 10181using COFF, the @code{symbol-file} command does not normally read the 10182symbol table in full right away. Instead, it scans the symbol table 10183quickly to find which source files and which symbols are present. The 10184details are read later, one source file at a time, as they are needed. 10185 10186The purpose of this two-stage reading strategy is to make @value{GDBN} 10187start up faster. For the most part, it is invisible except for 10188occasional pauses while the symbol table details for a particular source 10189file are being read. (The @code{set verbose} command can turn these 10190pauses into messages if desired. @xref{Messages/Warnings, ,Optional 10191warnings and messages}.) 10192 10193We have not implemented the two-stage strategy for COFF yet. When the 10194symbol table is stored in COFF format, @code{symbol-file} reads the 10195symbol table data in full right away. Note that ``stabs-in-COFF'' 10196still does the two-stage strategy, since the debug info is actually 10197in stabs format. 10198 10199@kindex readnow 10200@cindex reading symbols immediately 10201@cindex symbols, reading immediately 10202@kindex mapped 10203@cindex memory-mapped symbol file 10204@cindex saving symbol table 10205@item symbol-file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]} 10206@itemx file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]} 10207You can override the @value{GDBN} two-stage strategy for reading symbol 10208tables by using the @samp{-readnow} option with any of the commands that 10209load symbol table information, if you want to be sure @value{GDBN} has the 10210entire symbol table available. 10211 10212If memory-mapped files are available on your system through the 10213@code{mmap} system call, you can use another option, @samp{-mapped}, to 10214cause @value{GDBN} to write the symbols for your program into a reusable 10215file. Future @value{GDBN} debugging sessions map in symbol information 10216from this auxiliary symbol file (if the program has not changed), rather 10217than spending time reading the symbol table from the executable 10218program. Using the @samp{-mapped} option has the same effect as 10219starting @value{GDBN} with the @samp{-mapped} command-line option. 10220 10221You can use both options together, to make sure the auxiliary symbol 10222file has all the symbol information for your program. 10223 10224The auxiliary symbol file for a program called @var{myprog} is called 10225@samp{@var{myprog}.syms}. Once this file exists (so long as it is newer 10226than the corresponding executable), @value{GDBN} always attempts to use 10227it when you debug @var{myprog}; no special options or commands are 10228needed. 10229 10230The @file{.syms} file is specific to the host machine where you run 10231@value{GDBN}. It holds an exact image of the internal @value{GDBN} 10232symbol table. It cannot be shared across multiple host platforms. 10233 10234@c FIXME: for now no mention of directories, since this seems to be in 10235@c flux. 13mar1992 status is that in theory GDB would look either in 10236@c current dir or in same dir as myprog; but issues like competing 10237@c GDB's, or clutter in system dirs, mean that in practice right now 10238@c only current dir is used. FFish says maybe a special GDB hierarchy 10239@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol 10240@c files. 10241 10242@kindex core-file 10243@item core-file @r{[} @var{filename} @r{]} 10244@itemx core 10245Specify the whereabouts of a core dump file to be used as the ``contents 10246of memory''. Traditionally, core files contain only some parts of the 10247address space of the process that generated them; @value{GDBN} can access the 10248executable file itself for other parts. 10249 10250@code{core-file} with no argument specifies that no core file is 10251to be used. 10252 10253Note that the core file is ignored when your program is actually running 10254under @value{GDBN}. So, if you have been running your program and you 10255wish to debug a core file instead, you must kill the subprocess in which 10256the program is running. To do this, use the @code{kill} command 10257(@pxref{Kill Process, ,Killing the child process}). 10258 10259@kindex add-symbol-file 10260@cindex dynamic linking 10261@item add-symbol-file @var{filename} @var{address} 10262@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]} 10263@itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address} @dots{} 10264The @code{add-symbol-file} command reads additional symbol table 10265information from the file @var{filename}. You would use this command 10266when @var{filename} has been dynamically loaded (by some other means) 10267into the program that is running. @var{address} should be the memory 10268address at which the file has been loaded; @value{GDBN} cannot figure 10269this out for itself. You can additionally specify an arbitrary number 10270of @samp{@r{-s}@var{section} @var{address}} pairs, to give an explicit 10271section name and base address for that section. You can specify any 10272@var{address} as an expression. 10273 10274The symbol table of the file @var{filename} is added to the symbol table 10275originally read with the @code{symbol-file} command. You can use the 10276@code{add-symbol-file} command any number of times; the new symbol data 10277thus read keeps adding to the old. To discard all old symbol data 10278instead, use the @code{symbol-file} command without any arguments. 10279 10280@cindex relocatable object files, reading symbols from 10281@cindex object files, relocatable, reading symbols from 10282@cindex reading symbols from relocatable object files 10283@cindex symbols, reading from relocatable object files 10284@cindex @file{.o} files, reading symbols from 10285Although @var{filename} is typically a shared library file, an 10286executable file, or some other object file which has been fully 10287relocated for loading into a process, you can also load symbolic 10288information from relocatable @file{.o} files, as long as: 10289 10290@itemize @bullet 10291@item 10292the file's symbolic information refers only to linker symbols defined in 10293that file, not to symbols defined by other object files, 10294@item 10295every section the file's symbolic information refers to has actually 10296been loaded into the inferior, as it appears in the file, and 10297@item 10298you can determine the address at which every section was loaded, and 10299provide these to the @code{add-symbol-file} command. 10300@end itemize 10301 10302@noindent 10303Some embedded operating systems, like Sun Chorus and VxWorks, can load 10304relocatable files into an already running program; such systems 10305typically make the requirements above easy to meet. However, it's 10306important to recognize that many native systems use complex link 10307procedures (@code{.linkonce} section factoring and C@t{++} constructor table 10308assembly, for example) that make the requirements difficult to meet. In 10309general, one cannot assume that using @code{add-symbol-file} to read a 10310relocatable object file's symbolic information will have the same effect 10311as linking the relocatable object file into the program in the normal 10312way. 10313 10314@code{add-symbol-file} does not repeat if you press @key{RET} after using it. 10315 10316You can use the @samp{-mapped} and @samp{-readnow} options just as with 10317the @code{symbol-file} command, to change how @value{GDBN} manages the symbol 10318table information for @var{filename}. 10319 10320@kindex add-shared-symbol-file 10321@item add-shared-symbol-file 10322The @code{add-shared-symbol-file} command can be used only under Harris' CXUX 10323operating system for the Motorola 88k. @value{GDBN} automatically looks for 10324shared libraries, however if @value{GDBN} does not find yours, you can run 10325@code{add-shared-symbol-file}. It takes no arguments. 10326 10327@kindex section 10328@item section 10329The @code{section} command changes the base address of section SECTION of 10330the exec file to ADDR. This can be used if the exec file does not contain 10331section addresses, (such as in the a.out format), or when the addresses 10332specified in the file itself are wrong. Each section must be changed 10333separately. The @code{info files} command, described below, lists all 10334the sections and their addresses. 10335 10336@kindex info files 10337@kindex info target 10338@item info files 10339@itemx info target 10340@code{info files} and @code{info target} are synonymous; both print the 10341current target (@pxref{Targets, ,Specifying a Debugging Target}), 10342including the names of the executable and core dump files currently in 10343use by @value{GDBN}, and the files from which symbols were loaded. The 10344command @code{help target} lists all possible targets rather than 10345current ones. 10346 10347@kindex maint info sections 10348@item maint info sections 10349Another command that can give you extra information about program sections 10350is @code{maint info sections}. In addition to the section information 10351displayed by @code{info files}, this command displays the flags and file 10352offset of each section in the executable and core dump files. In addition, 10353@code{maint info sections} provides the following command options (which 10354may be arbitrarily combined): 10355 10356@table @code 10357@item ALLOBJ 10358Display sections for all loaded object files, including shared libraries. 10359@item @var{sections} 10360Display info only for named @var{sections}. 10361@item @var{section-flags} 10362Display info only for sections for which @var{section-flags} are true. 10363The section flags that @value{GDBN} currently knows about are: 10364@table @code 10365@item ALLOC 10366Section will have space allocated in the process when loaded. 10367Set for all sections except those containing debug information. 10368@item LOAD 10369Section will be loaded from the file into the child process memory. 10370Set for pre-initialized code and data, clear for @code{.bss} sections. 10371@item RELOC 10372Section needs to be relocated before loading. 10373@item READONLY 10374Section cannot be modified by the child process. 10375@item CODE 10376Section contains executable code only. 10377@item DATA 10378Section contains data only (no executable code). 10379@item ROM 10380Section will reside in ROM. 10381@item CONSTRUCTOR 10382Section contains data for constructor/destructor lists. 10383@item HAS_CONTENTS 10384Section is not empty. 10385@item NEVER_LOAD 10386An instruction to the linker to not output the section. 10387@item COFF_SHARED_LIBRARY 10388A notification to the linker that the section contains 10389COFF shared library information. 10390@item IS_COMMON 10391Section contains common symbols. 10392@end table 10393@end table 10394@kindex set trust-readonly-sections 10395@item set trust-readonly-sections on 10396Tell @value{GDBN} that readonly sections in your object file 10397really are read-only (i.e.@: that their contents will not change). 10398In that case, @value{GDBN} can fetch values from these sections 10399out of the object file, rather than from the target program. 10400For some targets (notably embedded ones), this can be a significant 10401enhancement to debugging performance. 10402 10403The default is off. 10404 10405@item set trust-readonly-sections off 10406Tell @value{GDBN} not to trust readonly sections. This means that 10407the contents of the section might change while the program is running, 10408and must therefore be fetched from the target when needed. 10409@end table 10410 10411All file-specifying commands allow both absolute and relative file names 10412as arguments. @value{GDBN} always converts the file name to an absolute file 10413name and remembers it that way. 10414 10415@cindex shared libraries 10416@value{GDBN} supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared 10417libraries. 10418 10419@value{GDBN} automatically loads symbol definitions from shared libraries 10420when you use the @code{run} command, or when you examine a core file. 10421(Before you issue the @code{run} command, @value{GDBN} does not understand 10422references to a function in a shared library, however---unless you are 10423debugging a core file). 10424 10425On HP-UX, if the program loads a library explicitly, @value{GDBN} 10426automatically loads the symbols at the time of the @code{shl_load} call. 10427 10428@c FIXME: some @value{GDBN} release may permit some refs to undef 10429@c FIXME...symbols---eg in a break cmd---assuming they are from a shared 10430@c FIXME...lib; check this from time to time when updating manual 10431 10432There are times, however, when you may wish to not automatically load 10433symbol definitions from shared libraries, such as when they are 10434particularly large or there are many of them. 10435 10436To control the automatic loading of shared library symbols, use the 10437commands: 10438 10439@table @code 10440@kindex set auto-solib-add 10441@item set auto-solib-add @var{mode} 10442If @var{mode} is @code{on}, symbols from all shared object libraries 10443will be loaded automatically when the inferior begins execution, you 10444attach to an independently started inferior, or when the dynamic linker 10445informs @value{GDBN} that a new library has been loaded. If @var{mode} 10446is @code{off}, symbols must be loaded manually, using the 10447@code{sharedlibrary} command. The default value is @code{on}. 10448 10449@kindex show auto-solib-add 10450@item show auto-solib-add 10451Display the current autoloading mode. 10452@end table 10453 10454To explicitly load shared library symbols, use the @code{sharedlibrary} 10455command: 10456 10457@table @code 10458@kindex info sharedlibrary 10459@kindex info share 10460@item info share 10461@itemx info sharedlibrary 10462Print the names of the shared libraries which are currently loaded. 10463 10464@kindex sharedlibrary 10465@kindex share 10466@item sharedlibrary @var{regex} 10467@itemx share @var{regex} 10468Load shared object library symbols for files matching a 10469Unix regular expression. 10470As with files loaded automatically, it only loads shared libraries 10471required by your program for a core file or after typing @code{run}. If 10472@var{regex} is omitted all shared libraries required by your program are 10473loaded. 10474@end table 10475 10476On some systems, such as HP-UX systems, @value{GDBN} supports 10477autoloading shared library symbols until a limiting threshold size is 10478reached. This provides the benefit of allowing autoloading to remain on 10479by default, but avoids autoloading excessively large shared libraries, 10480up to a threshold that is initially set, but which you can modify if you 10481wish. 10482 10483Beyond that threshold, symbols from shared libraries must be explicitly 10484loaded. To load these symbols, use the command @code{sharedlibrary 10485@var{filename}}. The base address of the shared library is determined 10486automatically by @value{GDBN} and need not be specified. 10487 10488To display or set the threshold, use the commands: 10489 10490@table @code 10491@kindex set auto-solib-limit 10492@item set auto-solib-limit @var{threshold} 10493Set the autoloading size threshold, in an integral number of megabytes. 10494If @var{threshold} is nonzero and shared library autoloading is enabled, 10495symbols from all shared object libraries will be loaded until the total 10496size of the loaded shared library symbols exceeds this threshold. 10497Otherwise, symbols must be loaded manually, using the 10498@code{sharedlibrary} command. The default threshold is 100 (i.e.@: 100 10499Mb). 10500 10501@kindex show auto-solib-limit 10502@item show auto-solib-limit 10503Display the current autoloading size threshold, in megabytes. 10504@end table 10505 10506Shared libraries are also supported in many cross or remote debugging 10507configurations. A copy of the target's libraries need to be present on the 10508host system; they need to be the same as the target libraries, although the 10509copies on the target can be stripped as long as the copies on the host are 10510not. 10511 10512You need to tell @value{GDBN} where the target libraries are, so that it can 10513load the correct copies---otherwise, it may try to load the host's libraries. 10514@value{GDBN} has two variables to specify the search directories for target 10515libraries. 10516 10517@table @code 10518@kindex set solib-absolute-prefix 10519@item set solib-absolute-prefix @var{path} 10520If this variable is set, @var{path} will be used as a prefix for any 10521absolute shared library paths; many runtime loaders store the absolute 10522paths to the shared library in the target program's memory. If you use 10523@samp{solib-absolute-prefix} to find shared libraries, they need to be laid 10524out in the same way that they are on the target, with e.g.@: a 10525@file{/usr/lib} hierarchy under @var{path}. 10526 10527You can set the default value of @samp{solib-absolute-prefix} by using the 10528configure-time @samp{--with-sysroot} option. 10529 10530@kindex show solib-absolute-prefix 10531@item show solib-absolute-prefix 10532Display the current shared library prefix. 10533 10534@kindex set solib-search-path 10535@item set solib-search-path @var{path} 10536If this variable is set, @var{path} is a colon-separated list of directories 10537to search for shared libraries. @samp{solib-search-path} is used after 10538@samp{solib-absolute-prefix} fails to locate the library, or if the path to 10539the library is relative instead of absolute. If you want to use 10540@samp{solib-search-path} instead of @samp{solib-absolute-prefix}, be sure to 10541set @samp{solib-absolute-prefix} to a nonexistant directory to prevent 10542@value{GDBN} from finding your host's libraries. 10543 10544@kindex show solib-search-path 10545@item show solib-search-path 10546Display the current shared library search path. 10547@end table 10548 10549 10550@node Separate Debug Files 10551@section Debugging Information in Separate Files 10552@cindex separate debugging information files 10553@cindex debugging information in separate files 10554@cindex @file{.debug} subdirectories 10555@cindex debugging information directory, global 10556@cindex global debugging information directory 10557 10558@value{GDBN} allows you to put a program's debugging information in a 10559file separate from the executable itself, in a way that allows 10560@value{GDBN} to find and load the debugging information automatically. 10561Since debugging information can be very large --- sometimes larger 10562than the executable code itself --- some systems distribute debugging 10563information for their executables in separate files, which users can 10564install only when they need to debug a problem. 10565 10566If an executable's debugging information has been extracted to a 10567separate file, the executable should contain a @dfn{debug link} giving 10568the name of the debugging information file (with no directory 10569components), and a checksum of its contents. (The exact form of a 10570debug link is described below.) If the full name of the directory 10571containing the executable is @var{execdir}, and the executable has a 10572debug link that specifies the name @var{debugfile}, then @value{GDBN} 10573will automatically search for the debugging information file in three 10574places: 10575 10576@itemize @bullet 10577@item 10578the directory containing the executable file (that is, it will look 10579for a file named @file{@var{execdir}/@var{debugfile}}, 10580@item 10581a subdirectory of that directory named @file{.debug} (that is, the 10582file @file{@var{execdir}/.debug/@var{debugfile}}, and 10583@item 10584a subdirectory of the global debug file directory that includes the 10585executable's full path, and the name from the link (that is, the file 10586@file{@var{globaldebugdir}/@var{execdir}/@var{debugfile}}, where 10587@var{globaldebugdir} is the global debug file directory, and 10588@var{execdir} has been turned into a relative path). 10589@end itemize 10590@noindent 10591@value{GDBN} checks under each of these names for a debugging 10592information file whose checksum matches that given in the link, and 10593reads the debugging information from the first one it finds. 10594 10595So, for example, if you ask @value{GDBN} to debug @file{/usr/bin/ls}, 10596which has a link containing the name @file{ls.debug}, and the global 10597debug directory is @file{/usr/lib/debug}, then @value{GDBN} will look 10598for debug information in @file{/usr/bin/ls.debug}, 10599@file{/usr/bin/.debug/ls.debug}, and 10600@file{/usr/lib/debug/usr/bin/ls.debug}. 10601 10602You can set the global debugging info directory's name, and view the 10603name @value{GDBN} is currently using. 10604 10605@table @code 10606 10607@kindex set debug-file-directory 10608@item set debug-file-directory @var{directory} 10609Set the directory which @value{GDBN} searches for separate debugging 10610information files to @var{directory}. 10611 10612@kindex show debug-file-directory 10613@item show debug-file-directory 10614Show the directory @value{GDBN} searches for separate debugging 10615information files. 10616 10617@end table 10618 10619@cindex @code{.gnu_debuglink} sections 10620@cindex debug links 10621A debug link is a special section of the executable file named 10622@code{.gnu_debuglink}. The section must contain: 10623 10624@itemize 10625@item 10626A filename, with any leading directory components removed, followed by 10627a zero byte, 10628@item 10629zero to three bytes of padding, as needed to reach the next four-byte 10630boundary within the section, and 10631@item 10632a four-byte CRC checksum, stored in the same endianness used for the 10633executable file itself. The checksum is computed on the debugging 10634information file's full contents by the function given below, passing 10635zero as the @var{crc} argument. 10636@end itemize 10637 10638Any executable file format can carry a debug link, as long as it can 10639contain a section named @code{.gnu_debuglink} with the contents 10640described above. 10641 10642The debugging information file itself should be an ordinary 10643executable, containing a full set of linker symbols, sections, and 10644debugging information. The sections of the debugging information file 10645should have the same names, addresses and sizes as the original file, 10646but they need not contain any data --- much like a @code{.bss} section 10647in an ordinary executable. 10648 10649As of December 2002, there is no standard GNU utility to produce 10650separated executable / debugging information file pairs. Ulrich 10651Drepper's @file{elfutils} package, starting with version 0.53, 10652contains a version of the @code{strip} command such that the command 10653@kbd{strip foo -f foo.debug} removes the debugging information from 10654the executable file @file{foo}, places it in the file 10655@file{foo.debug}, and leaves behind a debug link in @file{foo}. 10656 10657Since there are many different ways to compute CRC's (different 10658polynomials, reversals, byte ordering, etc.), the simplest way to 10659describe the CRC used in @code{.gnu_debuglink} sections is to give the 10660complete code for a function that computes it: 10661 10662@kindex gnu_debuglink_crc32 10663@smallexample 10664unsigned long 10665gnu_debuglink_crc32 (unsigned long crc, 10666 unsigned char *buf, size_t len) 10667@{ 10668 static const unsigned long crc32_table[256] = 10669 @{ 10670 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, 10671 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, 10672 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, 10673 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, 10674 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, 10675 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, 10676 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, 10677 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, 10678 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, 10679 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, 10680 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, 10681 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, 10682 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, 10683 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, 10684 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, 10685 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, 10686 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, 10687 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, 10688 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, 10689 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, 10690 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, 10691 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, 10692 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, 10693 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, 10694 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, 10695 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, 10696 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, 10697 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, 10698 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, 10699 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, 10700 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, 10701 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, 10702 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, 10703 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, 10704 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, 10705 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, 10706 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, 10707 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, 10708 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, 10709 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, 10710 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, 10711 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, 10712 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, 10713 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, 10714 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, 10715 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, 10716 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, 10717 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, 10718 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, 10719 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, 10720 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, 10721 0x2d02ef8d 10722 @}; 10723 unsigned char *end; 10724 10725 crc = ~crc & 0xffffffff; 10726 for (end = buf + len; buf < end; ++buf) 10727 crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); 10728 return ~crc & 0xffffffff; 10729@} 10730@end smallexample 10731 10732 10733@node Symbol Errors 10734@section Errors reading symbol files 10735 10736While reading a symbol file, @value{GDBN} occasionally encounters problems, 10737such as symbol types it does not recognize, or known bugs in compiler 10738output. By default, @value{GDBN} does not notify you of such problems, since 10739they are relatively common and primarily of interest to people 10740debugging compilers. If you are interested in seeing information 10741about ill-constructed symbol tables, you can either ask @value{GDBN} to print 10742only one message about each such type of problem, no matter how many 10743times the problem occurs; or you can ask @value{GDBN} to print more messages, 10744to see how many times the problems occur, with the @code{set 10745complaints} command (@pxref{Messages/Warnings, ,Optional warnings and 10746messages}). 10747 10748The messages currently printed, and their meanings, include: 10749 10750@table @code 10751@item inner block not inside outer block in @var{symbol} 10752 10753The symbol information shows where symbol scopes begin and end 10754(such as at the start of a function or a block of statements). This 10755error indicates that an inner scope block is not fully contained 10756in its outer scope blocks. 10757 10758@value{GDBN} circumvents the problem by treating the inner block as if it had 10759the same scope as the outer block. In the error message, @var{symbol} 10760may be shown as ``@code{(don't know)}'' if the outer block is not a 10761function. 10762 10763@item block at @var{address} out of order 10764 10765The symbol information for symbol scope blocks should occur in 10766order of increasing addresses. This error indicates that it does not 10767do so. 10768 10769@value{GDBN} does not circumvent this problem, and has trouble 10770locating symbols in the source file whose symbols it is reading. (You 10771can often determine what source file is affected by specifying 10772@code{set verbose on}. @xref{Messages/Warnings, ,Optional warnings and 10773messages}.) 10774 10775@item bad block start address patched 10776 10777The symbol information for a symbol scope block has a start address 10778smaller than the address of the preceding source line. This is known 10779to occur in the SunOS 4.1.1 (and earlier) C compiler. 10780 10781@value{GDBN} circumvents the problem by treating the symbol scope block as 10782starting on the previous source line. 10783 10784@item bad string table offset in symbol @var{n} 10785 10786@cindex foo 10787Symbol number @var{n} contains a pointer into the string table which is 10788larger than the size of the string table. 10789 10790@value{GDBN} circumvents the problem by considering the symbol to have the 10791name @code{foo}, which may cause other problems if many symbols end up 10792with this name. 10793 10794@item unknown symbol type @code{0x@var{nn}} 10795 10796The symbol information contains new data types that @value{GDBN} does 10797not yet know how to read. @code{0x@var{nn}} is the symbol type of the 10798uncomprehended information, in hexadecimal. 10799 10800@value{GDBN} circumvents the error by ignoring this symbol information. 10801This usually allows you to debug your program, though certain symbols 10802are not accessible. If you encounter such a problem and feel like 10803debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint 10804on @code{complain}, then go up to the function @code{read_dbx_symtab} 10805and examine @code{*bufp} to see the symbol. 10806 10807@item stub type has NULL name 10808 10809@value{GDBN} could not find the full definition for a struct or class. 10810 10811@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{} 10812The symbol information for a C@t{++} member function is missing some 10813information that recent versions of the compiler should have output for 10814it. 10815 10816@item info mismatch between compiler and debugger 10817 10818@value{GDBN} could not parse a type specification output by the compiler. 10819 10820@end table 10821 10822@node Targets 10823@chapter Specifying a Debugging Target 10824 10825@cindex debugging target 10826@kindex target 10827 10828A @dfn{target} is the execution environment occupied by your program. 10829 10830Often, @value{GDBN} runs in the same host environment as your program; 10831in that case, the debugging target is specified as a side effect when 10832you use the @code{file} or @code{core} commands. When you need more 10833flexibility---for example, running @value{GDBN} on a physically separate 10834host, or controlling a standalone system over a serial port or a 10835realtime system over a TCP/IP connection---you can use the @code{target} 10836command to specify one of the target types configured for @value{GDBN} 10837(@pxref{Target Commands, ,Commands for managing targets}). 10838 10839@menu 10840* Active Targets:: Active targets 10841* Target Commands:: Commands for managing targets 10842* Byte Order:: Choosing target byte order 10843* Remote:: Remote debugging 10844* KOD:: Kernel Object Display 10845 10846@end menu 10847 10848@node Active Targets 10849@section Active targets 10850 10851@cindex stacking targets 10852@cindex active targets 10853@cindex multiple targets 10854 10855There are three classes of targets: processes, core files, and 10856executable files. @value{GDBN} can work concurrently on up to three 10857active targets, one in each class. This allows you to (for example) 10858start a process and inspect its activity without abandoning your work on 10859a core file. 10860 10861For example, if you execute @samp{gdb a.out}, then the executable file 10862@code{a.out} is the only active target. If you designate a core file as 10863well---presumably from a prior run that crashed and coredumped---then 10864@value{GDBN} has two active targets and uses them in tandem, looking 10865first in the corefile target, then in the executable file, to satisfy 10866requests for memory addresses. (Typically, these two classes of target 10867are complementary, since core files contain only a program's 10868read-write memory---variables and so on---plus machine status, while 10869executable files contain only the program text and initialized data.) 10870 10871When you type @code{run}, your executable file becomes an active process 10872target as well. When a process target is active, all @value{GDBN} 10873commands requesting memory addresses refer to that target; addresses in 10874an active core file or executable file target are obscured while the 10875process target is active. 10876 10877Use the @code{core-file} and @code{exec-file} commands to select a new 10878core file or executable target (@pxref{Files, ,Commands to specify 10879files}). To specify as a target a process that is already running, use 10880the @code{attach} command (@pxref{Attach, ,Debugging an already-running 10881process}). 10882 10883@node Target Commands 10884@section Commands for managing targets 10885 10886@table @code 10887@item target @var{type} @var{parameters} 10888Connects the @value{GDBN} host environment to a target machine or 10889process. A target is typically a protocol for talking to debugging 10890facilities. You use the argument @var{type} to specify the type or 10891protocol of the target machine. 10892 10893Further @var{parameters} are interpreted by the target protocol, but 10894typically include things like device names or host names to connect 10895with, process numbers, and baud rates. 10896 10897The @code{target} command does not repeat if you press @key{RET} again 10898after executing the command. 10899 10900@kindex help target 10901@item help target 10902Displays the names of all targets available. To display targets 10903currently selected, use either @code{info target} or @code{info files} 10904(@pxref{Files, ,Commands to specify files}). 10905 10906@item help target @var{name} 10907Describe a particular target, including any parameters necessary to 10908select it. 10909 10910@kindex set gnutarget 10911@item set gnutarget @var{args} 10912@value{GDBN} uses its own library BFD to read your files. @value{GDBN} 10913knows whether it is reading an @dfn{executable}, 10914a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format 10915with the @code{set gnutarget} command. Unlike most @code{target} commands, 10916with @code{gnutarget} the @code{target} refers to a program, not a machine. 10917 10918@quotation 10919@emph{Warning:} To specify a file format with @code{set gnutarget}, 10920you must know the actual BFD name. 10921@end quotation 10922 10923@noindent 10924@xref{Files, , Commands to specify files}. 10925 10926@kindex show gnutarget 10927@item show gnutarget 10928Use the @code{show gnutarget} command to display what file format 10929@code{gnutarget} is set to read. If you have not set @code{gnutarget}, 10930@value{GDBN} will determine the file format for each file automatically, 10931and @code{show gnutarget} displays @samp{The current BDF target is "auto"}. 10932@end table 10933 10934@cindex common targets 10935Here are some common targets (available, or not, depending on the GDB 10936configuration): 10937 10938@table @code 10939@kindex target 10940@item target exec @var{program} 10941@cindex executable file target 10942An executable file. @samp{target exec @var{program}} is the same as 10943@samp{exec-file @var{program}}. 10944 10945@item target core @var{filename} 10946@cindex core dump file target 10947A core dump file. @samp{target core @var{filename}} is the same as 10948@samp{core-file @var{filename}}. 10949 10950@item target remote @var{dev} 10951@cindex remote target 10952Remote serial target in GDB-specific protocol. The argument @var{dev} 10953specifies what serial device to use for the connection (e.g. 10954@file{/dev/ttya}). @xref{Remote, ,Remote debugging}. @code{target remote} 10955supports the @code{load} command. This is only useful if you have 10956some other way of getting the stub to the target system, and you can put 10957it somewhere in memory where it won't get clobbered by the download. 10958 10959@item target sim 10960@cindex built-in simulator target 10961Builtin CPU simulator. @value{GDBN} includes simulators for most architectures. 10962In general, 10963@smallexample 10964 target sim 10965 load 10966 run 10967@end smallexample 10968@noindent 10969works; however, you cannot assume that a specific memory map, device 10970drivers, or even basic I/O is available, although some simulators do 10971provide these. For info about any processor-specific simulator details, 10972see the appropriate section in @ref{Embedded Processors, ,Embedded 10973Processors}. 10974 10975@end table 10976 10977Some configurations may include these targets as well: 10978 10979@table @code 10980 10981@item target nrom @var{dev} 10982@cindex NetROM ROM emulator target 10983NetROM ROM emulator. This target only supports downloading. 10984 10985@end table 10986 10987Different targets are available on different configurations of @value{GDBN}; 10988your configuration may have more or fewer targets. 10989 10990Many remote targets require you to download the executable's code 10991once you've successfully established a connection. 10992 10993@table @code 10994 10995@kindex load @var{filename} 10996@item load @var{filename} 10997Depending on what remote debugging facilities are configured into 10998@value{GDBN}, the @code{load} command may be available. Where it exists, it 10999is meant to make @var{filename} (an executable) available for debugging 11000on the remote system---by downloading, or dynamic linking, for example. 11001@code{load} also records the @var{filename} symbol table in @value{GDBN}, like 11002the @code{add-symbol-file} command. 11003 11004If your @value{GDBN} does not have a @code{load} command, attempting to 11005execute it gets the error message ``@code{You can't do that when your 11006target is @dots{}}'' 11007 11008The file is loaded at whatever address is specified in the executable. 11009For some object file formats, you can specify the load address when you 11010link the program; for other formats, like a.out, the object file format 11011specifies a fixed address. 11012@c FIXME! This would be a good place for an xref to the GNU linker doc. 11013 11014@code{load} does not repeat if you press @key{RET} again after using it. 11015@end table 11016 11017@node Byte Order 11018@section Choosing target byte order 11019 11020@cindex choosing target byte order 11021@cindex target byte order 11022 11023Some types of processors, such as the MIPS, PowerPC, and Renesas SH, 11024offer the ability to run either big-endian or little-endian byte 11025orders. Usually the executable or symbol will include a bit to 11026designate the endian-ness, and you will not need to worry about 11027which to use. However, you may still find it useful to adjust 11028@value{GDBN}'s idea of processor endian-ness manually. 11029 11030@table @code 11031@kindex set endian 11032@item set endian big 11033Instruct @value{GDBN} to assume the target is big-endian. 11034 11035@item set endian little 11036Instruct @value{GDBN} to assume the target is little-endian. 11037 11038@item set endian auto 11039Instruct @value{GDBN} to use the byte order associated with the 11040executable. 11041 11042@item show endian 11043Display @value{GDBN}'s current idea of the target byte order. 11044 11045@end table 11046 11047Note that these commands merely adjust interpretation of symbolic 11048data on the host, and that they have absolutely no effect on the 11049target system. 11050 11051@node Remote 11052@section Remote debugging 11053@cindex remote debugging 11054 11055If you are trying to debug a program running on a machine that cannot run 11056@value{GDBN} in the usual way, it is often useful to use remote debugging. 11057For example, you might use remote debugging on an operating system kernel, 11058or on a small system which does not have a general purpose operating system 11059powerful enough to run a full-featured debugger. 11060 11061Some configurations of @value{GDBN} have special serial or TCP/IP interfaces 11062to make this work with particular debugging targets. In addition, 11063@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN}, 11064but not specific to any particular target system) which you can use if you 11065write the remote stubs---the code that runs on the remote system to 11066communicate with @value{GDBN}. 11067 11068Other remote targets may be available in your 11069configuration of @value{GDBN}; use @code{help target} to list them. 11070 11071@node KOD 11072@section Kernel Object Display 11073@cindex kernel object display 11074@cindex KOD 11075 11076Some targets support kernel object display. Using this facility, 11077@value{GDBN} communicates specially with the underlying operating system 11078and can display information about operating system-level objects such as 11079mutexes and other synchronization objects. Exactly which objects can be 11080displayed is determined on a per-OS basis. 11081 11082@kindex set os 11083Use the @code{set os} command to set the operating system. This tells 11084@value{GDBN} which kernel object display module to initialize: 11085 11086@smallexample 11087(@value{GDBP}) set os cisco 11088@end smallexample 11089 11090@kindex show os 11091The associated command @code{show os} displays the operating system 11092set with the @code{set os} command; if no operating system has been 11093set, @code{show os} will display an empty string @samp{""}. 11094 11095If @code{set os} succeeds, @value{GDBN} will display some information 11096about the operating system, and will create a new @code{info} command 11097which can be used to query the target. The @code{info} command is named 11098after the operating system: 11099 11100@kindex info cisco 11101@smallexample 11102(@value{GDBP}) info cisco 11103List of Cisco Kernel Objects 11104Object Description 11105any Any and all objects 11106@end smallexample 11107 11108Further subcommands can be used to query about particular objects known 11109by the kernel. 11110 11111There is currently no way to determine whether a given operating 11112system is supported other than to try setting it with @kbd{set os 11113@var{name}}, where @var{name} is the name of the operating system you 11114want to try. 11115 11116 11117@node Remote Debugging 11118@chapter Debugging remote programs 11119 11120@menu 11121* Connecting:: Connecting to a remote target 11122* Server:: Using the gdbserver program 11123* NetWare:: Using the gdbserve.nlm program 11124* Remote configuration:: Remote configuration 11125* remote stub:: Implementing a remote stub 11126@end menu 11127 11128@node Connecting 11129@section Connecting to a remote target 11130 11131On the @value{GDBN} host machine, you will need an unstripped copy of 11132your program, since @value{GDBN} needs symobl and debugging information. 11133Start up @value{GDBN} as usual, using the name of the local copy of your 11134program as the first argument. 11135 11136@cindex serial line, @code{target remote} 11137If you're using a serial line, you may want to give @value{GDBN} the 11138@w{@samp{--baud}} option, or use the @code{set remotebaud} command 11139before the @code{target} command. 11140 11141After that, use @code{target remote} to establish communications with 11142the target machine. Its argument specifies how to communicate---either 11143via a devicename attached to a direct serial line, or a TCP or UDP port 11144(possibly to a terminal server which in turn has a serial line to the 11145target). For example, to use a serial line connected to the device 11146named @file{/dev/ttyb}: 11147 11148@smallexample 11149target remote /dev/ttyb 11150@end smallexample 11151 11152@cindex TCP port, @code{target remote} 11153To use a TCP connection, use an argument of the form 11154@code{@var{host}:@var{port}} or @code{tcp:@var{host}:@var{port}}. 11155For example, to connect to port 2828 on a 11156terminal server named @code{manyfarms}: 11157 11158@smallexample 11159target remote manyfarms:2828 11160@end smallexample 11161 11162If your remote target is actually running on the same machine as 11163your debugger session (e.g.@: a simulator of your target running on 11164the same host), you can omit the hostname. For example, to connect 11165to port 1234 on your local machine: 11166 11167@smallexample 11168target remote :1234 11169@end smallexample 11170@noindent 11171 11172Note that the colon is still required here. 11173 11174@cindex UDP port, @code{target remote} 11175To use a UDP connection, use an argument of the form 11176@code{udp:@var{host}:@var{port}}. For example, to connect to UDP port 2828 11177on a terminal server named @code{manyfarms}: 11178 11179@smallexample 11180target remote udp:manyfarms:2828 11181@end smallexample 11182 11183When using a UDP connection for remote debugging, you should keep in mind 11184that the `U' stands for ``Unreliable''. UDP can silently drop packets on 11185busy or unreliable networks, which will cause havoc with your debugging 11186session. 11187 11188Now you can use all the usual commands to examine and change data and to 11189step and continue the remote program. 11190 11191@cindex interrupting remote programs 11192@cindex remote programs, interrupting 11193Whenever @value{GDBN} is waiting for the remote program, if you type the 11194interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the 11195program. This may or may not succeed, depending in part on the hardware 11196and the serial drivers the remote system uses. If you type the 11197interrupt character once again, @value{GDBN} displays this prompt: 11198 11199@smallexample 11200Interrupted while waiting for the program. 11201Give up (and stop debugging it)? (y or n) 11202@end smallexample 11203 11204If you type @kbd{y}, @value{GDBN} abandons the remote debugging session. 11205(If you decide you want to try again later, you can use @samp{target 11206remote} again to connect once more.) If you type @kbd{n}, @value{GDBN} 11207goes back to waiting. 11208 11209@table @code 11210@kindex detach (remote) 11211@item detach 11212When you have finished debugging the remote program, you can use the 11213@code{detach} command to release it from @value{GDBN} control. 11214Detaching from the target normally resumes its execution, but the results 11215will depend on your particular remote stub. After the @code{detach} 11216command, @value{GDBN} is free to connect to another target. 11217 11218@kindex disconnect 11219@item disconnect 11220The @code{disconnect} command behaves like @code{detach}, except that 11221the target is generally not resumed. It will wait for @value{GDBN} 11222(this instance or another one) to connect and continue debugging. After 11223the @code{disconnect} command, @value{GDBN} is again free to connect to 11224another target. 11225@end table 11226 11227@node Server 11228@section Using the @code{gdbserver} program 11229 11230@kindex gdbserver 11231@cindex remote connection without stubs 11232@code{gdbserver} is a control program for Unix-like systems, which 11233allows you to connect your program with a remote @value{GDBN} via 11234@code{target remote}---but without linking in the usual debugging stub. 11235 11236@code{gdbserver} is not a complete replacement for the debugging stubs, 11237because it requires essentially the same operating-system facilities 11238that @value{GDBN} itself does. In fact, a system that can run 11239@code{gdbserver} to connect to a remote @value{GDBN} could also run 11240@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless, 11241because it is a much smaller program than @value{GDBN} itself. It is 11242also easier to port than all of @value{GDBN}, so you may be able to get 11243started more quickly on a new system by using @code{gdbserver}. 11244Finally, if you develop code for real-time systems, you may find that 11245the tradeoffs involved in real-time operation make it more convenient to 11246do as much development work as possible on another system, for example 11247by cross-compiling. You can use @code{gdbserver} to make a similar 11248choice for debugging. 11249 11250@value{GDBN} and @code{gdbserver} communicate via either a serial line 11251or a TCP connection, using the standard @value{GDBN} remote serial 11252protocol. 11253 11254@table @emph 11255@item On the target machine, 11256you need to have a copy of the program you want to debug. 11257@code{gdbserver} does not need your program's symbol table, so you can 11258strip the program if necessary to save space. @value{GDBN} on the host 11259system does all the symbol handling. 11260 11261To use the server, you must tell it how to communicate with @value{GDBN}; 11262the name of your program; and the arguments for your program. The usual 11263syntax is: 11264 11265@smallexample 11266target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ] 11267@end smallexample 11268 11269@var{comm} is either a device name (to use a serial line) or a TCP 11270hostname and portnumber. For example, to debug Emacs with the argument 11271@samp{foo.txt} and communicate with @value{GDBN} over the serial port 11272@file{/dev/com1}: 11273 11274@smallexample 11275target> gdbserver /dev/com1 emacs foo.txt 11276@end smallexample 11277 11278@code{gdbserver} waits passively for the host @value{GDBN} to communicate 11279with it. 11280 11281To use a TCP connection instead of a serial line: 11282 11283@smallexample 11284target> gdbserver host:2345 emacs foo.txt 11285@end smallexample 11286 11287The only difference from the previous example is the first argument, 11288specifying that you are communicating with the host @value{GDBN} via 11289TCP. The @samp{host:2345} argument means that @code{gdbserver} is to 11290expect a TCP connection from machine @samp{host} to local TCP port 2345. 11291(Currently, the @samp{host} part is ignored.) You can choose any number 11292you want for the port number as long as it does not conflict with any 11293TCP ports already in use on the target system (for example, @code{23} is 11294reserved for @code{telnet}).@footnote{If you choose a port number that 11295conflicts with another service, @code{gdbserver} prints an error message 11296and exits.} You must use the same port number with the host @value{GDBN} 11297@code{target remote} command. 11298 11299On some targets, @code{gdbserver} can also attach to running programs. 11300This is accomplished via the @code{--attach} argument. The syntax is: 11301 11302@smallexample 11303target> gdbserver @var{comm} --attach @var{pid} 11304@end smallexample 11305 11306@var{pid} is the process ID of a currently running process. It isn't necessary 11307to point @code{gdbserver} at a binary for the running process. 11308 11309@pindex pidof 11310@cindex attach to a program by name 11311You can debug processes by name instead of process ID if your target has the 11312@code{pidof} utility: 11313 11314@smallexample 11315target> gdbserver @var{comm} --attach `pidof @var{PROGRAM}` 11316@end smallexample 11317 11318In case more than one copy of @var{PROGRAM} is running, or @var{PROGRAM} 11319has multiple threads, most versions of @code{pidof} support the 11320@code{-s} option to only return the first process ID. 11321 11322@item On the host machine, 11323connect to your target (@pxref{Connecting,,Connecting to a remote target}). 11324For TCP connections, you must start up @code{gdbserver} prior to using 11325the @code{target remote} command. Otherwise you may get an error whose 11326text depends on the host system, but which usually looks something like 11327@samp{Connection refused}. You don't need to use the @code{load} 11328command in @value{GDBN} when using gdbserver, since the program is 11329already on the target. 11330 11331@end table 11332 11333@node NetWare 11334@section Using the @code{gdbserve.nlm} program 11335 11336@kindex gdbserve.nlm 11337@code{gdbserve.nlm} is a control program for NetWare systems, which 11338allows you to connect your program with a remote @value{GDBN} via 11339@code{target remote}. 11340 11341@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line, 11342using the standard @value{GDBN} remote serial protocol. 11343 11344@table @emph 11345@item On the target machine, 11346you need to have a copy of the program you want to debug. 11347@code{gdbserve.nlm} does not need your program's symbol table, so you 11348can strip the program if necessary to save space. @value{GDBN} on the 11349host system does all the symbol handling. 11350 11351To use the server, you must tell it how to communicate with 11352@value{GDBN}; the name of your program; and the arguments for your 11353program. The syntax is: 11354 11355@smallexample 11356load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ] 11357 [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ] 11358@end smallexample 11359 11360@var{board} and @var{port} specify the serial line; @var{baud} specifies 11361the baud rate used by the connection. @var{port} and @var{node} default 11362to 0, @var{baud} defaults to 9600@dmn{bps}. 11363 11364For example, to debug Emacs with the argument @samp{foo.txt}and 11365communicate with @value{GDBN} over serial port number 2 or board 1 11366using a 19200@dmn{bps} connection: 11367 11368@smallexample 11369load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt 11370@end smallexample 11371 11372@item 11373On the @value{GDBN} host machine, connect to your target (@pxref{Connecting,, 11374Connecting to a remote target}). 11375 11376@end table 11377 11378@node Remote configuration 11379@section Remote configuration 11380 11381The following configuration options are available when debugging remote 11382programs: 11383 11384@table @code 11385@kindex set remote hardware-watchpoint-limit 11386@kindex set remote hardware-breakpoint-limit 11387@anchor{set remote hardware-watchpoint-limit} 11388@anchor{set remote hardware-breakpoint-limit} 11389@item set remote hardware-watchpoint-limit @var{limit} 11390@itemx set remote hardware-breakpoint-limit @var{limit} 11391Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or 11392watchpoints. A limit of -1, the default, is treated as unlimited. 11393@end table 11394 11395@node remote stub 11396@section Implementing a remote stub 11397 11398@cindex debugging stub, example 11399@cindex remote stub, example 11400@cindex stub example, remote debugging 11401The stub files provided with @value{GDBN} implement the target side of the 11402communication protocol, and the @value{GDBN} side is implemented in the 11403@value{GDBN} source file @file{remote.c}. Normally, you can simply allow 11404these subroutines to communicate, and ignore the details. (If you're 11405implementing your own stub file, you can still ignore the details: start 11406with one of the existing stub files. @file{sparc-stub.c} is the best 11407organized, and therefore the easiest to read.) 11408 11409@cindex remote serial debugging, overview 11410To debug a program running on another machine (the debugging 11411@dfn{target} machine), you must first arrange for all the usual 11412prerequisites for the program to run by itself. For example, for a C 11413program, you need: 11414 11415@enumerate 11416@item 11417A startup routine to set up the C runtime environment; these usually 11418have a name like @file{crt0}. The startup routine may be supplied by 11419your hardware supplier, or you may have to write your own. 11420 11421@item 11422A C subroutine library to support your program's 11423subroutine calls, notably managing input and output. 11424 11425@item 11426A way of getting your program to the other machine---for example, a 11427download program. These are often supplied by the hardware 11428manufacturer, but you may have to write your own from hardware 11429documentation. 11430@end enumerate 11431 11432The next step is to arrange for your program to use a serial port to 11433communicate with the machine where @value{GDBN} is running (the @dfn{host} 11434machine). In general terms, the scheme looks like this: 11435 11436@table @emph 11437@item On the host, 11438@value{GDBN} already understands how to use this protocol; when everything 11439else is set up, you can simply use the @samp{target remote} command 11440(@pxref{Targets,,Specifying a Debugging Target}). 11441 11442@item On the target, 11443you must link with your program a few special-purpose subroutines that 11444implement the @value{GDBN} remote serial protocol. The file containing these 11445subroutines is called a @dfn{debugging stub}. 11446 11447On certain remote targets, you can use an auxiliary program 11448@code{gdbserver} instead of linking a stub into your program. 11449@xref{Server,,Using the @code{gdbserver} program}, for details. 11450@end table 11451 11452The debugging stub is specific to the architecture of the remote 11453machine; for example, use @file{sparc-stub.c} to debug programs on 11454@sc{sparc} boards. 11455 11456@cindex remote serial stub list 11457These working remote stubs are distributed with @value{GDBN}: 11458 11459@table @code 11460 11461@item i386-stub.c 11462@cindex @file{i386-stub.c} 11463@cindex Intel 11464@cindex i386 11465For Intel 386 and compatible architectures. 11466 11467@item m68k-stub.c 11468@cindex @file{m68k-stub.c} 11469@cindex Motorola 680x0 11470@cindex m680x0 11471For Motorola 680x0 architectures. 11472 11473@item sh-stub.c 11474@cindex @file{sh-stub.c} 11475@cindex Renesas 11476@cindex SH 11477For Renesas SH architectures. 11478 11479@item sparc-stub.c 11480@cindex @file{sparc-stub.c} 11481@cindex Sparc 11482For @sc{sparc} architectures. 11483 11484@item sparcl-stub.c 11485@cindex @file{sparcl-stub.c} 11486@cindex Fujitsu 11487@cindex SparcLite 11488For Fujitsu @sc{sparclite} architectures. 11489 11490@end table 11491 11492The @file{README} file in the @value{GDBN} distribution may list other 11493recently added stubs. 11494 11495@menu 11496* Stub Contents:: What the stub can do for you 11497* Bootstrapping:: What you must do for the stub 11498* Debug Session:: Putting it all together 11499@end menu 11500 11501@node Stub Contents 11502@subsection What the stub can do for you 11503 11504@cindex remote serial stub 11505The debugging stub for your architecture supplies these three 11506subroutines: 11507 11508@table @code 11509@item set_debug_traps 11510@findex set_debug_traps 11511@cindex remote serial stub, initialization 11512This routine arranges for @code{handle_exception} to run when your 11513program stops. You must call this subroutine explicitly near the 11514beginning of your program. 11515 11516@item handle_exception 11517@findex handle_exception 11518@cindex remote serial stub, main routine 11519This is the central workhorse, but your program never calls it 11520explicitly---the setup code arranges for @code{handle_exception} to 11521run when a trap is triggered. 11522 11523@code{handle_exception} takes control when your program stops during 11524execution (for example, on a breakpoint), and mediates communications 11525with @value{GDBN} on the host machine. This is where the communications 11526protocol is implemented; @code{handle_exception} acts as the @value{GDBN} 11527representative on the target machine. It begins by sending summary 11528information on the state of your program, then continues to execute, 11529retrieving and transmitting any information @value{GDBN} needs, until you 11530execute a @value{GDBN} command that makes your program resume; at that point, 11531@code{handle_exception} returns control to your own code on the target 11532machine. 11533 11534@item breakpoint 11535@cindex @code{breakpoint} subroutine, remote 11536Use this auxiliary subroutine to make your program contain a 11537breakpoint. Depending on the particular situation, this may be the only 11538way for @value{GDBN} to get control. For instance, if your target 11539machine has some sort of interrupt button, you won't need to call this; 11540pressing the interrupt button transfers control to 11541@code{handle_exception}---in effect, to @value{GDBN}. On some machines, 11542simply receiving characters on the serial port may also trigger a trap; 11543again, in that situation, you don't need to call @code{breakpoint} from 11544your own program---simply running @samp{target remote} from the host 11545@value{GDBN} session gets control. 11546 11547Call @code{breakpoint} if none of these is true, or if you simply want 11548to make certain your program stops at a predetermined point for the 11549start of your debugging session. 11550@end table 11551 11552@node Bootstrapping 11553@subsection What you must do for the stub 11554 11555@cindex remote stub, support routines 11556The debugging stubs that come with @value{GDBN} are set up for a particular 11557chip architecture, but they have no information about the rest of your 11558debugging target machine. 11559 11560First of all you need to tell the stub how to communicate with the 11561serial port. 11562 11563@table @code 11564@item int getDebugChar() 11565@findex getDebugChar 11566Write this subroutine to read a single character from the serial port. 11567It may be identical to @code{getchar} for your target system; a 11568different name is used to allow you to distinguish the two if you wish. 11569 11570@item void putDebugChar(int) 11571@findex putDebugChar 11572Write this subroutine to write a single character to the serial port. 11573It may be identical to @code{putchar} for your target system; a 11574different name is used to allow you to distinguish the two if you wish. 11575@end table 11576 11577@cindex control C, and remote debugging 11578@cindex interrupting remote targets 11579If you want @value{GDBN} to be able to stop your program while it is 11580running, you need to use an interrupt-driven serial driver, and arrange 11581for it to stop when it receives a @code{^C} (@samp{\003}, the control-C 11582character). That is the character which @value{GDBN} uses to tell the 11583remote system to stop. 11584 11585Getting the debugging target to return the proper status to @value{GDBN} 11586probably requires changes to the standard stub; one quick and dirty way 11587is to just execute a breakpoint instruction (the ``dirty'' part is that 11588@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}). 11589 11590Other routines you need to supply are: 11591 11592@table @code 11593@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address}) 11594@findex exceptionHandler 11595Write this function to install @var{exception_address} in the exception 11596handling tables. You need to do this because the stub does not have any 11597way of knowing what the exception handling tables on your target system 11598are like (for example, the processor's table might be in @sc{rom}, 11599containing entries which point to a table in @sc{ram}). 11600@var{exception_number} is the exception number which should be changed; 11601its meaning is architecture-dependent (for example, different numbers 11602might represent divide by zero, misaligned access, etc). When this 11603exception occurs, control should be transferred directly to 11604@var{exception_address}, and the processor state (stack, registers, 11605and so on) should be just as it is when a processor exception occurs. So if 11606you want to use a jump instruction to reach @var{exception_address}, it 11607should be a simple jump, not a jump to subroutine. 11608 11609For the 386, @var{exception_address} should be installed as an interrupt 11610gate so that interrupts are masked while the handler runs. The gate 11611should be at privilege level 0 (the most privileged level). The 11612@sc{sparc} and 68k stubs are able to mask interrupts themselves without 11613help from @code{exceptionHandler}. 11614 11615@item void flush_i_cache() 11616@findex flush_i_cache 11617On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the 11618instruction cache, if any, on your target machine. If there is no 11619instruction cache, this subroutine may be a no-op. 11620 11621On target machines that have instruction caches, @value{GDBN} requires this 11622function to make certain that the state of your program is stable. 11623@end table 11624 11625@noindent 11626You must also make sure this library routine is available: 11627 11628@table @code 11629@item void *memset(void *, int, int) 11630@findex memset 11631This is the standard library function @code{memset} that sets an area of 11632memory to a known value. If you have one of the free versions of 11633@code{libc.a}, @code{memset} can be found there; otherwise, you must 11634either obtain it from your hardware manufacturer, or write your own. 11635@end table 11636 11637If you do not use the GNU C compiler, you may need other standard 11638library subroutines as well; this varies from one stub to another, 11639but in general the stubs are likely to use any of the common library 11640subroutines which @code{@value{GCC}} generates as inline code. 11641 11642 11643@node Debug Session 11644@subsection Putting it all together 11645 11646@cindex remote serial debugging summary 11647In summary, when your program is ready to debug, you must follow these 11648steps. 11649 11650@enumerate 11651@item 11652Make sure you have defined the supporting low-level routines 11653(@pxref{Bootstrapping,,What you must do for the stub}): 11654@display 11655@code{getDebugChar}, @code{putDebugChar}, 11656@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}. 11657@end display 11658 11659@item 11660Insert these lines near the top of your program: 11661 11662@smallexample 11663set_debug_traps(); 11664breakpoint(); 11665@end smallexample 11666 11667@item 11668For the 680x0 stub only, you need to provide a variable called 11669@code{exceptionHook}. Normally you just use: 11670 11671@smallexample 11672void (*exceptionHook)() = 0; 11673@end smallexample 11674 11675@noindent 11676but if before calling @code{set_debug_traps}, you set it to point to a 11677function in your program, that function is called when 11678@code{@value{GDBN}} continues after stopping on a trap (for example, bus 11679error). The function indicated by @code{exceptionHook} is called with 11680one parameter: an @code{int} which is the exception number. 11681 11682@item 11683Compile and link together: your program, the @value{GDBN} debugging stub for 11684your target architecture, and the supporting subroutines. 11685 11686@item 11687Make sure you have a serial connection between your target machine and 11688the @value{GDBN} host, and identify the serial port on the host. 11689 11690@item 11691@c The "remote" target now provides a `load' command, so we should 11692@c document that. FIXME. 11693Download your program to your target machine (or get it there by 11694whatever means the manufacturer provides), and start it. 11695 11696@item 11697Start @value{GDBN} on the host, and connect to the target 11698(@pxref{Connecting,,Connecting to a remote target}). 11699 11700@end enumerate 11701 11702@node Configurations 11703@chapter Configuration-Specific Information 11704 11705While nearly all @value{GDBN} commands are available for all native and 11706cross versions of the debugger, there are some exceptions. This chapter 11707describes things that are only available in certain configurations. 11708 11709There are three major categories of configurations: native 11710configurations, where the host and target are the same, embedded 11711operating system configurations, which are usually the same for several 11712different processor architectures, and bare embedded processors, which 11713are quite different from each other. 11714 11715@menu 11716* Native:: 11717* Embedded OS:: 11718* Embedded Processors:: 11719* Architectures:: 11720@end menu 11721 11722@node Native 11723@section Native 11724 11725This section describes details specific to particular native 11726configurations. 11727 11728@menu 11729* HP-UX:: HP-UX 11730* BSD libkvm Interface:: Debugging BSD kernel memory images 11731* SVR4 Process Information:: SVR4 process information 11732* DJGPP Native:: Features specific to the DJGPP port 11733* Cygwin Native:: Features specific to the Cygwin port 11734@end menu 11735 11736@node HP-UX 11737@subsection HP-UX 11738 11739On HP-UX systems, if you refer to a function or variable name that 11740begins with a dollar sign, @value{GDBN} searches for a user or system 11741name first, before it searches for a convenience variable. 11742 11743@node BSD libkvm Interface 11744@subsection BSD libkvm Interface 11745 11746@cindex libkvm 11747@cindex kernel memory image 11748@cindex kernel crash dump 11749 11750BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory 11751interface that provides a uniform interface for accessing kernel virtual 11752memory images, including live systems and crash dumps. @value{GDBN} 11753uses this interface to allow you to debug live kernels and kernel crash 11754dumps on many native BSD configurations. This is implemented as a 11755special @code{kvm} debugging target. For debugging a live system, load 11756the currently running kernel into @value{GDBN} and connect to the 11757@code{kvm} target: 11758 11759@smallexample 11760(@value{GDBP}) @b{target kvm} 11761@end smallexample 11762 11763For debugging crash dumps, provide the file name of the crash dump as an 11764argument: 11765 11766@smallexample 11767(@value{GDBP}) @b{target kvm /var/crash/bsd.0} 11768@end smallexample 11769 11770Once connected to the @code{kvm} target, the following commands are 11771available: 11772 11773@table @code 11774@kindex kvm 11775@item kvm pcb 11776Set current context from pcb address. 11777 11778@item kvm proc 11779Set current context from proc address. This command isn't available on 11780modern FreeBSD systems. 11781@end table 11782 11783@node SVR4 Process Information 11784@subsection SVR4 process information 11785 11786@kindex /proc 11787@cindex process image 11788 11789Many versions of SVR4 provide a facility called @samp{/proc} that can be 11790used to examine the image of a running process using file-system 11791subroutines. If @value{GDBN} is configured for an operating system with 11792this facility, the command @code{info proc} is available to report on 11793several kinds of information about the process running your program. 11794@code{info proc} works only on SVR4 systems that include the 11795@code{procfs} code. This includes OSF/1 (Digital Unix), Solaris, Irix, 11796and Unixware, but not HP-UX or @sc{gnu}/Linux, for example. 11797 11798@table @code 11799@kindex info proc 11800@item info proc 11801Summarize available information about the process. 11802 11803@kindex info proc mappings 11804@item info proc mappings 11805Report on the address ranges accessible in the program, with information 11806on whether your program may read, write, or execute each range. 11807@ignore 11808@comment These sub-options of 'info proc' were not included when 11809@comment procfs.c was re-written. Keep their descriptions around 11810@comment against the day when someone finds the time to put them back in. 11811@kindex info proc times 11812@item info proc times 11813Starting time, user CPU time, and system CPU time for your program and 11814its children. 11815 11816@kindex info proc id 11817@item info proc id 11818Report on the process IDs related to your program: its own process ID, 11819the ID of its parent, the process group ID, and the session ID. 11820 11821@kindex info proc status 11822@item info proc status 11823General information on the state of the process. If the process is 11824stopped, this report includes the reason for stopping, and any signal 11825received. 11826 11827@item info proc all 11828Show all the above information about the process. 11829@end ignore 11830@end table 11831 11832@node DJGPP Native 11833@subsection Features for Debugging @sc{djgpp} Programs 11834@cindex @sc{djgpp} debugging 11835@cindex native @sc{djgpp} debugging 11836@cindex MS-DOS-specific commands 11837 11838@sc{djgpp} is the port of @sc{gnu} development tools to MS-DOS and 11839MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs 11840that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on 11841top of real-mode DOS systems and their emulations. 11842 11843@value{GDBN} supports native debugging of @sc{djgpp} programs, and 11844defines a few commands specific to the @sc{djgpp} port. This 11845subsection describes those commands. 11846 11847@table @code 11848@kindex info dos 11849@item info dos 11850This is a prefix of @sc{djgpp}-specific commands which print 11851information about the target system and important OS structures. 11852 11853@kindex sysinfo 11854@cindex MS-DOS system info 11855@cindex free memory information (MS-DOS) 11856@item info dos sysinfo 11857This command displays assorted information about the underlying 11858platform: the CPU type and features, the OS version and flavor, the 11859DPMI version, and the available conventional and DPMI memory. 11860 11861@cindex GDT 11862@cindex LDT 11863@cindex IDT 11864@cindex segment descriptor tables 11865@cindex descriptor tables display 11866@item info dos gdt 11867@itemx info dos ldt 11868@itemx info dos idt 11869These 3 commands display entries from, respectively, Global, Local, 11870and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor 11871tables are data structures which store a descriptor for each segment 11872that is currently in use. The segment's selector is an index into a 11873descriptor table; the table entry for that index holds the 11874descriptor's base address and limit, and its attributes and access 11875rights. 11876 11877A typical @sc{djgpp} program uses 3 segments: a code segment, a data 11878segment (used for both data and the stack), and a DOS segment (which 11879allows access to DOS/BIOS data structures and absolute addresses in 11880conventional memory). However, the DPMI host will usually define 11881additional segments in order to support the DPMI environment. 11882 11883@cindex garbled pointers 11884These commands allow to display entries from the descriptor tables. 11885Without an argument, all entries from the specified table are 11886displayed. An argument, which should be an integer expression, means 11887display a single entry whose index is given by the argument. For 11888example, here's a convenient way to display information about the 11889debugged program's data segment: 11890 11891@smallexample 11892@exdent @code{(@value{GDBP}) info dos ldt $ds} 11893@exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)} 11894@end smallexample 11895 11896@noindent 11897This comes in handy when you want to see whether a pointer is outside 11898the data segment's limit (i.e.@: @dfn{garbled}). 11899 11900@cindex page tables display (MS-DOS) 11901@item info dos pde 11902@itemx info dos pte 11903These two commands display entries from, respectively, the Page 11904Directory and the Page Tables. Page Directories and Page Tables are 11905data structures which control how virtual memory addresses are mapped 11906into physical addresses. A Page Table includes an entry for every 11907page of memory that is mapped into the program's address space; there 11908may be several Page Tables, each one holding up to 4096 entries. A 11909Page Directory has up to 4096 entries, one each for every Page Table 11910that is currently in use. 11911 11912Without an argument, @kbd{info dos pde} displays the entire Page 11913Directory, and @kbd{info dos pte} displays all the entries in all of 11914the Page Tables. An argument, an integer expression, given to the 11915@kbd{info dos pde} command means display only that entry from the Page 11916Directory table. An argument given to the @kbd{info dos pte} command 11917means display entries from a single Page Table, the one pointed to by 11918the specified entry in the Page Directory. 11919 11920@cindex direct memory access (DMA) on MS-DOS 11921These commands are useful when your program uses @dfn{DMA} (Direct 11922Memory Access), which needs physical addresses to program the DMA 11923controller. 11924 11925These commands are supported only with some DPMI servers. 11926 11927@cindex physical address from linear address 11928@item info dos address-pte @var{addr} 11929This command displays the Page Table entry for a specified linear 11930address. The argument linear address @var{addr} should already have the 11931appropriate segment's base address added to it, because this command 11932accepts addresses which may belong to @emph{any} segment. For 11933example, here's how to display the Page Table entry for the page where 11934the variable @code{i} is stored: 11935 11936@smallexample 11937@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i} 11938@exdent @code{Page Table entry for address 0x11a00d30:} 11939@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30} 11940@end smallexample 11941 11942@noindent 11943This says that @code{i} is stored at offset @code{0xd30} from the page 11944whose physical base address is @code{0x02698000}, and prints all the 11945attributes of that page. 11946 11947Note that you must cast the addresses of variables to a @code{char *}, 11948since otherwise the value of @code{__djgpp_base_address}, the base 11949address of all variables and functions in a @sc{djgpp} program, will 11950be added using the rules of C pointer arithmetics: if @code{i} is 11951declared an @code{int}, @value{GDBN} will add 4 times the value of 11952@code{__djgpp_base_address} to the address of @code{i}. 11953 11954Here's another example, it displays the Page Table entry for the 11955transfer buffer: 11956 11957@smallexample 11958@exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)} 11959@exdent @code{Page Table entry for address 0x29110:} 11960@exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110} 11961@end smallexample 11962 11963@noindent 11964(The @code{+ 3} offset is because the transfer buffer's address is the 119653rd member of the @code{_go32_info_block} structure.) The output of 11966this command clearly shows that addresses in conventional memory are 11967mapped 1:1, i.e.@: the physical and linear addresses are identical. 11968 11969This command is supported only with some DPMI servers. 11970@end table 11971 11972@node Cygwin Native 11973@subsection Features for Debugging MS Windows PE executables 11974@cindex MS Windows debugging 11975@cindex native Cygwin debugging 11976@cindex Cygwin-specific commands 11977 11978@value{GDBN} supports native debugging of MS Windows programs, including 11979DLLs with and without symbolic debugging information. There are various 11980additional Cygwin-specific commands, described in this subsection. The 11981subsubsection @pxref{Non-debug DLL symbols} describes working with DLLs 11982that have no debugging symbols. 11983 11984 11985@table @code 11986@kindex info w32 11987@item info w32 11988This is a prefix of MS Windows specific commands which print 11989information about the target system and important OS structures. 11990 11991@item info w32 selector 11992This command displays information returned by 11993the Win32 API @code{GetThreadSelectorEntry} function. 11994It takes an optional argument that is evaluated to 11995a long value to give the information about this given selector. 11996Without argument, this command displays information 11997about the the six segment registers. 11998 11999@kindex info dll 12000@item info dll 12001This is a Cygwin specific alias of info shared. 12002 12003@kindex dll-symbols 12004@item dll-symbols 12005This command loads symbols from a dll similarly to 12006add-sym command but without the need to specify a base address. 12007 12008@kindex set new-console 12009@item set new-console @var{mode} 12010If @var{mode} is @code{on} the debuggee will 12011be started in a new console on next start. 12012If @var{mode} is @code{off}i, the debuggee will 12013be started in the same console as the debugger. 12014 12015@kindex show new-console 12016@item show new-console 12017Displays whether a new console is used 12018when the debuggee is started. 12019 12020@kindex set new-group 12021@item set new-group @var{mode} 12022This boolean value controls whether the debuggee should 12023start a new group or stay in the same group as the debugger. 12024This affects the way the Windows OS handles 12025Ctrl-C. 12026 12027@kindex show new-group 12028@item show new-group 12029Displays current value of new-group boolean. 12030 12031@kindex set debugevents 12032@item set debugevents 12033This boolean value adds debug output concerning events seen by the debugger. 12034 12035@kindex set debugexec 12036@item set debugexec 12037This boolean value adds debug output concerning execute events 12038seen by the debugger. 12039 12040@kindex set debugexceptions 12041@item set debugexceptions 12042This boolean value adds debug ouptut concerning exception events 12043seen by the debugger. 12044 12045@kindex set debugmemory 12046@item set debugmemory 12047This boolean value adds debug ouptut concerning memory events 12048seen by the debugger. 12049 12050@kindex set shell 12051@item set shell 12052This boolean values specifies whether the debuggee is called 12053via a shell or directly (default value is on). 12054 12055@kindex show shell 12056@item show shell 12057Displays if the debuggee will be started with a shell. 12058 12059@end table 12060 12061@menu 12062* Non-debug DLL symbols:: Support for DLLs without debugging symbols 12063@end menu 12064 12065@node Non-debug DLL symbols 12066@subsubsection Support for DLLs without debugging symbols 12067@cindex DLLs with no debugging symbols 12068@cindex Minimal symbols and DLLs 12069 12070Very often on windows, some of the DLLs that your program relies on do 12071not include symbolic debugging information (for example, 12072@file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging 12073symbols in a DLL, it relies on the minimal amount of symbolic 12074information contained in the DLL's export table. This subsubsection 12075describes working with such symbols, known internally to @value{GDBN} as 12076``minimal symbols''. 12077 12078Note that before the debugged program has started execution, no DLLs 12079will have been loaded. The easiest way around this problem is simply to 12080start the program --- either by setting a breakpoint or letting the 12081program run once to completion. It is also possible to force 12082@value{GDBN} to load a particular DLL before starting the executable --- 12083see the shared library information in @pxref{Files} or the 12084@code{dll-symbols} command in @pxref{Cygwin Native}. Currently, 12085explicitly loading symbols from a DLL with no debugging information will 12086cause the symbol names to be duplicated in @value{GDBN}'s lookup table, 12087which may adversely affect symbol lookup performance. 12088 12089@subsubsection DLL name prefixes 12090 12091In keeping with the naming conventions used by the Microsoft debugging 12092tools, DLL export symbols are made available with a prefix based on the 12093DLL name, for instance @code{KERNEL32!CreateFileA}. The plain name is 12094also entered into the symbol table, so @code{CreateFileA} is often 12095sufficient. In some cases there will be name clashes within a program 12096(particularly if the executable itself includes full debugging symbols) 12097necessitating the use of the fully qualified name when referring to the 12098contents of the DLL. Use single-quotes around the name to avoid the 12099exclamation mark (``!'') being interpreted as a language operator. 12100 12101Note that the internal name of the DLL may be all upper-case, even 12102though the file name of the DLL is lower-case, or vice-versa. Since 12103symbols within @value{GDBN} are @emph{case-sensitive} this may cause 12104some confusion. If in doubt, try the @code{info functions} and 12105@code{info variables} commands or even @code{maint print msymbols} (see 12106@pxref{Symbols}). Here's an example: 12107 12108@smallexample 12109(@value{GDBP}) info function CreateFileA 12110All functions matching regular expression "CreateFileA": 12111 12112Non-debugging symbols: 121130x77e885f4 CreateFileA 121140x77e885f4 KERNEL32!CreateFileA 12115@end smallexample 12116 12117@smallexample 12118(@value{GDBP}) info function ! 12119All functions matching regular expression "!": 12120 12121Non-debugging symbols: 121220x6100114c cygwin1!__assert 121230x61004034 cygwin1!_dll_crt0@@0 121240x61004240 cygwin1!dll_crt0(per_process *) 12125[etc...] 12126@end smallexample 12127 12128@subsubsection Working with minimal symbols 12129 12130Symbols extracted from a DLL's export table do not contain very much 12131type information. All that @value{GDBN} can do is guess whether a symbol 12132refers to a function or variable depending on the linker section that 12133contains the symbol. Also note that the actual contents of the memory 12134contained in a DLL are not available unless the program is running. This 12135means that you cannot examine the contents of a variable or disassemble 12136a function within a DLL without a running program. 12137 12138Variables are generally treated as pointers and dereferenced 12139automatically. For this reason, it is often necessary to prefix a 12140variable name with the address-of operator (``&'') and provide explicit 12141type information in the command. Here's an example of the type of 12142problem: 12143 12144@smallexample 12145(@value{GDBP}) print 'cygwin1!__argv' 12146$1 = 268572168 12147@end smallexample 12148 12149@smallexample 12150(@value{GDBP}) x 'cygwin1!__argv' 121510x10021610: "\230y\"" 12152@end smallexample 12153 12154And two possible solutions: 12155 12156@smallexample 12157(@value{GDBP}) print ((char **)'cygwin1!__argv')[0] 12158$2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" 12159@end smallexample 12160 12161@smallexample 12162(@value{GDBP}) x/2x &'cygwin1!__argv' 121630x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000 12164(@value{GDBP}) x/x 0x10021608 121650x10021608: 0x0022fd98 12166(@value{GDBP}) x/s 0x0022fd98 121670x22fd98: "/cygdrive/c/mydirectory/myprogram" 12168@end smallexample 12169 12170Setting a break point within a DLL is possible even before the program 12171starts execution. However, under these circumstances, @value{GDBN} can't 12172examine the initial instructions of the function in order to skip the 12173function's frame set-up code. You can work around this by using ``*&'' 12174to set the breakpoint at a raw memory address: 12175 12176@smallexample 12177(@value{GDBP}) break *&'python22!PyOS_Readline' 12178Breakpoint 1 at 0x1e04eff0 12179@end smallexample 12180 12181The author of these extensions is not entirely convinced that setting a 12182break point within a shared DLL like @file{kernel32.dll} is completely 12183safe. 12184 12185@node Embedded OS 12186@section Embedded Operating Systems 12187 12188This section describes configurations involving the debugging of 12189embedded operating systems that are available for several different 12190architectures. 12191 12192@menu 12193* VxWorks:: Using @value{GDBN} with VxWorks 12194@end menu 12195 12196@value{GDBN} includes the ability to debug programs running on 12197various real-time operating systems. 12198 12199@node VxWorks 12200@subsection Using @value{GDBN} with VxWorks 12201 12202@cindex VxWorks 12203 12204@table @code 12205 12206@kindex target vxworks 12207@item target vxworks @var{machinename} 12208A VxWorks system, attached via TCP/IP. The argument @var{machinename} 12209is the target system's machine name or IP address. 12210 12211@end table 12212 12213On VxWorks, @code{load} links @var{filename} dynamically on the 12214current target system as well as adding its symbols in @value{GDBN}. 12215 12216@value{GDBN} enables developers to spawn and debug tasks running on networked 12217VxWorks targets from a Unix host. Already-running tasks spawned from 12218the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on 12219both the Unix host and on the VxWorks target. The program 12220@code{@value{GDBP}} is installed and executed on the Unix host. (It may be 12221installed with the name @code{vxgdb}, to distinguish it from a 12222@value{GDBN} for debugging programs on the host itself.) 12223 12224@table @code 12225@item VxWorks-timeout @var{args} 12226@kindex vxworks-timeout 12227All VxWorks-based targets now support the option @code{vxworks-timeout}. 12228This option is set by the user, and @var{args} represents the number of 12229seconds @value{GDBN} waits for responses to rpc's. You might use this if 12230your VxWorks target is a slow software simulator or is on the far side 12231of a thin network line. 12232@end table 12233 12234The following information on connecting to VxWorks was current when 12235this manual was produced; newer releases of VxWorks may use revised 12236procedures. 12237 12238@findex INCLUDE_RDB 12239To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel 12240to include the remote debugging interface routines in the VxWorks 12241library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the 12242VxWorks configuration file @file{configAll.h} and rebuild your VxWorks 12243kernel. The resulting kernel contains @file{rdb.a}, and spawns the 12244source debugging task @code{tRdbTask} when VxWorks is booted. For more 12245information on configuring and remaking VxWorks, see the manufacturer's 12246manual. 12247@c VxWorks, see the @cite{VxWorks Programmer's Guide}. 12248 12249Once you have included @file{rdb.a} in your VxWorks system image and set 12250your Unix execution search path to find @value{GDBN}, you are ready to 12251run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or 12252@code{vxgdb}, depending on your installation). 12253 12254@value{GDBN} comes up showing the prompt: 12255 12256@smallexample 12257(vxgdb) 12258@end smallexample 12259 12260@menu 12261* VxWorks Connection:: Connecting to VxWorks 12262* VxWorks Download:: VxWorks download 12263* VxWorks Attach:: Running tasks 12264@end menu 12265 12266@node VxWorks Connection 12267@subsubsection Connecting to VxWorks 12268 12269The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the 12270network. To connect to a target whose host name is ``@code{tt}'', type: 12271 12272@smallexample 12273(vxgdb) target vxworks tt 12274@end smallexample 12275 12276@need 750 12277@value{GDBN} displays messages like these: 12278 12279@smallexample 12280Attaching remote machine across net... 12281Connected to tt. 12282@end smallexample 12283 12284@need 1000 12285@value{GDBN} then attempts to read the symbol tables of any object modules 12286loaded into the VxWorks target since it was last booted. @value{GDBN} locates 12287these files by searching the directories listed in the command search 12288path (@pxref{Environment, ,Your program's environment}); if it fails 12289to find an object file, it displays a message such as: 12290 12291@smallexample 12292prog.o: No such file or directory. 12293@end smallexample 12294 12295When this happens, add the appropriate directory to the search path with 12296the @value{GDBN} command @code{path}, and execute the @code{target} 12297command again. 12298 12299@node VxWorks Download 12300@subsubsection VxWorks download 12301 12302@cindex download to VxWorks 12303If you have connected to the VxWorks target and you want to debug an 12304object that has not yet been loaded, you can use the @value{GDBN} 12305@code{load} command to download a file from Unix to VxWorks 12306incrementally. The object file given as an argument to the @code{load} 12307command is actually opened twice: first by the VxWorks target in order 12308to download the code, then by @value{GDBN} in order to read the symbol 12309table. This can lead to problems if the current working directories on 12310the two systems differ. If both systems have NFS mounted the same 12311filesystems, you can avoid these problems by using absolute paths. 12312Otherwise, it is simplest to set the working directory on both systems 12313to the directory in which the object file resides, and then to reference 12314the file by its name, without any path. For instance, a program 12315@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks 12316and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this 12317program, type this on VxWorks: 12318 12319@smallexample 12320-> cd "@var{vxpath}/vw/demo/rdb" 12321@end smallexample 12322 12323@noindent 12324Then, in @value{GDBN}, type: 12325 12326@smallexample 12327(vxgdb) cd @var{hostpath}/vw/demo/rdb 12328(vxgdb) load prog.o 12329@end smallexample 12330 12331@value{GDBN} displays a response similar to this: 12332 12333@smallexample 12334Reading symbol data from wherever/vw/demo/rdb/prog.o... done. 12335@end smallexample 12336 12337You can also use the @code{load} command to reload an object module 12338after editing and recompiling the corresponding source file. Note that 12339this makes @value{GDBN} delete all currently-defined breakpoints, 12340auto-displays, and convenience variables, and to clear the value 12341history. (This is necessary in order to preserve the integrity of 12342debugger's data structures that reference the target system's symbol 12343table.) 12344 12345@node VxWorks Attach 12346@subsubsection Running tasks 12347 12348@cindex running VxWorks tasks 12349You can also attach to an existing task using the @code{attach} command as 12350follows: 12351 12352@smallexample 12353(vxgdb) attach @var{task} 12354@end smallexample 12355 12356@noindent 12357where @var{task} is the VxWorks hexadecimal task ID. The task can be running 12358or suspended when you attach to it. Running tasks are suspended at 12359the time of attachment. 12360 12361@node Embedded Processors 12362@section Embedded Processors 12363 12364This section goes into details specific to particular embedded 12365configurations. 12366 12367 12368@menu 12369* ARM:: ARM 12370* H8/300:: Renesas H8/300 12371* H8/500:: Renesas H8/500 12372* M32R/D:: Renesas M32R/D 12373* M68K:: Motorola M68K 12374* MIPS Embedded:: MIPS Embedded 12375* OpenRISC 1000:: OpenRisc 1000 12376* PA:: HP PA Embedded 12377* PowerPC: PowerPC 12378* SH:: Renesas SH 12379* Sparclet:: Tsqware Sparclet 12380* Sparclite:: Fujitsu Sparclite 12381* ST2000:: Tandem ST2000 12382* Z8000:: Zilog Z8000 12383@end menu 12384 12385@node ARM 12386@subsection ARM 12387 12388@table @code 12389 12390@kindex target rdi 12391@item target rdi @var{dev} 12392ARM Angel monitor, via RDI library interface to ADP protocol. You may 12393use this target to communicate with both boards running the Angel 12394monitor, or with the EmbeddedICE JTAG debug device. 12395 12396@kindex target rdp 12397@item target rdp @var{dev} 12398ARM Demon monitor. 12399 12400@end table 12401 12402@node H8/300 12403@subsection Renesas H8/300 12404 12405@table @code 12406 12407@kindex target hms@r{, with H8/300} 12408@item target hms @var{dev} 12409A Renesas SH, H8/300, or H8/500 board, attached via serial line to your host. 12410Use special commands @code{device} and @code{speed} to control the serial 12411line and the communications speed used. 12412 12413@kindex target e7000@r{, with H8/300} 12414@item target e7000 @var{dev} 12415E7000 emulator for Renesas H8 and SH. 12416 12417@kindex target sh3@r{, with H8/300} 12418@kindex target sh3e@r{, with H8/300} 12419@item target sh3 @var{dev} 12420@itemx target sh3e @var{dev} 12421Renesas SH-3 and SH-3E target systems. 12422 12423@end table 12424 12425@cindex download to H8/300 or H8/500 12426@cindex H8/300 or H8/500 download 12427@cindex download to Renesas SH 12428@cindex Renesas SH download 12429When you select remote debugging to a Renesas SH, H8/300, or H8/500 12430board, the @code{load} command downloads your program to the Renesas 12431board and also opens it as the current executable target for 12432@value{GDBN} on your host (like the @code{file} command). 12433 12434@value{GDBN} needs to know these things to talk to your 12435Renesas SH, H8/300, or H8/500: 12436 12437@enumerate 12438@item 12439that you want to use @samp{target hms}, the remote debugging interface 12440for Renesas microprocessors, or @samp{target e7000}, the in-circuit 12441emulator for the Renesas SH and the Renesas 300H. (@samp{target hms} is 12442the default when @value{GDBN} is configured specifically for the Renesas SH, 12443H8/300, or H8/500.) 12444 12445@item 12446what serial device connects your host to your Renesas board (the first 12447serial device available on your host is the default). 12448 12449@item 12450what speed to use over the serial device. 12451@end enumerate 12452 12453@menu 12454* Renesas Boards:: Connecting to Renesas boards. 12455* Renesas ICE:: Using the E7000 In-Circuit Emulator. 12456* Renesas Special:: Special @value{GDBN} commands for Renesas micros. 12457@end menu 12458 12459@node Renesas Boards 12460@subsubsection Connecting to Renesas boards 12461 12462@c only for Unix hosts 12463@kindex device 12464@cindex serial device, Renesas micros 12465Use the special @code{@value{GDBN}} command @samp{device @var{port}} if you 12466need to explicitly set the serial device. The default @var{port} is the 12467first available port on your host. This is only necessary on Unix 12468hosts, where it is typically something like @file{/dev/ttya}. 12469 12470@kindex speed 12471@cindex serial line speed, Renesas micros 12472@code{@value{GDBN}} has another special command to set the communications 12473speed: @samp{speed @var{bps}}. This command also is only used from Unix 12474hosts; on DOS hosts, set the line speed as usual from outside @value{GDBN} with 12475the DOS @code{mode} command (for instance, 12476@w{@kbd{mode com2:9600,n,8,1,p}} for a 9600@dmn{bps} connection). 12477 12478The @samp{device} and @samp{speed} commands are available only when you 12479use a Unix host to debug your Renesas microprocessor programs. If you 12480use a DOS host, 12481@value{GDBN} depends on an auxiliary terminate-and-stay-resident program 12482called @code{asynctsr} to communicate with the development board 12483through a PC serial port. You must also use the DOS @code{mode} command 12484to set up the serial port on the DOS side. 12485 12486The following sample session illustrates the steps needed to start a 12487program under @value{GDBN} control on an H8/300. The example uses a 12488sample H8/300 program called @file{t.x}. The procedure is the same for 12489the Renesas SH and the H8/500. 12490 12491First hook up your development board. In this example, we use a 12492board attached to serial port @code{COM2}; if you use a different serial 12493port, substitute its name in the argument of the @code{mode} command. 12494When you call @code{asynctsr}, the auxiliary comms program used by the 12495debugger, you give it just the numeric part of the serial port's name; 12496for example, @samp{asyncstr 2} below runs @code{asyncstr} on 12497@code{COM2}. 12498 12499@smallexample 12500C:\H8300\TEST> asynctsr 2 12501C:\H8300\TEST> mode com2:9600,n,8,1,p 12502 12503Resident portion of MODE loaded 12504 12505COM2: 9600, n, 8, 1, p 12506 12507@end smallexample 12508 12509@quotation 12510@emph{Warning:} We have noticed a bug in PC-NFS that conflicts with 12511@code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to 12512disable it, or even boot without it, to use @code{asynctsr} to control 12513your development board. 12514@end quotation 12515 12516@kindex target hms@r{, and serial protocol} 12517Now that serial communications are set up, and the development board is 12518connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with 12519the name of your program as the argument. @code{@value{GDBN}} prompts 12520you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special 12521commands to begin your debugging session: @samp{target hms} to specify 12522cross-debugging to the Renesas board, and the @code{load} command to 12523download your program to the board. @code{load} displays the names of 12524the program's sections, and a @samp{*} for each 2K of data downloaded. 12525(If you want to refresh @value{GDBN} data on symbols or on the 12526executable file without downloading, use the @value{GDBN} commands 12527@code{file} or @code{symbol-file}. These commands, and @code{load} 12528itself, are described in @ref{Files,,Commands to specify files}.) 12529 12530@smallexample 12531(eg-C:\H8300\TEST) @value{GDBP} t.x 12532@value{GDBN} is free software and you are welcome to distribute copies 12533 of it under certain conditions; type "show copying" to see 12534 the conditions. 12535There is absolutely no warranty for @value{GDBN}; type "show warranty" 12536for details. 12537@value{GDBN} @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc... 12538(@value{GDBP}) target hms 12539Connected to remote H8/300 HMS system. 12540(@value{GDBP}) load t.x 12541.text : 0x8000 .. 0xabde *********** 12542.data : 0xabde .. 0xad30 * 12543.stack : 0xf000 .. 0xf014 * 12544@end smallexample 12545 12546At this point, you're ready to run or debug your program. From here on, 12547you can use all the usual @value{GDBN} commands. The @code{break} command 12548sets breakpoints; the @code{run} command starts your program; 12549@code{print} or @code{x} display data; the @code{continue} command 12550resumes execution after stopping at a breakpoint. You can use the 12551@code{help} command at any time to find out more about @value{GDBN} commands. 12552 12553Remember, however, that @emph{operating system} facilities aren't 12554available on your development board; for example, if your program hangs, 12555you can't send an interrupt---but you can press the @sc{reset} switch! 12556 12557Use the @sc{reset} button on the development board 12558@itemize @bullet 12559@item 12560to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has 12561no way to pass an interrupt signal to the development board); and 12562 12563@item 12564to return to the @value{GDBN} command prompt after your program finishes 12565normally. The communications protocol provides no other way for @value{GDBN} 12566to detect program completion. 12567@end itemize 12568 12569In either case, @value{GDBN} sees the effect of a @sc{reset} on the 12570development board as a ``normal exit'' of your program. 12571 12572@node Renesas ICE 12573@subsubsection Using the E7000 in-circuit emulator 12574 12575@kindex target e7000@r{, with Renesas ICE} 12576You can use the E7000 in-circuit emulator to develop code for either the 12577Renesas SH or the H8/300H. Use one of these forms of the @samp{target 12578e7000} command to connect @value{GDBN} to your E7000: 12579 12580@table @code 12581@item target e7000 @var{port} @var{speed} 12582Use this form if your E7000 is connected to a serial port. The 12583@var{port} argument identifies what serial port to use (for example, 12584@samp{com2}). The third argument is the line speed in bits per second 12585(for example, @samp{9600}). 12586 12587@item target e7000 @var{hostname} 12588If your E7000 is installed as a host on a TCP/IP network, you can just 12589specify its hostname; @value{GDBN} uses @code{telnet} to connect. 12590@end table 12591 12592@node Renesas Special 12593@subsubsection Special @value{GDBN} commands for Renesas micros 12594 12595Some @value{GDBN} commands are available only for the H8/300: 12596 12597@table @code 12598 12599@kindex set machine 12600@kindex show machine 12601@item set machine h8300 12602@itemx set machine h8300h 12603Condition @value{GDBN} for one of the two variants of the H8/300 12604architecture with @samp{set machine}. You can use @samp{show machine} 12605to check which variant is currently in effect. 12606 12607@end table 12608 12609@node H8/500 12610@subsection H8/500 12611 12612@table @code 12613 12614@kindex set memory @var{mod} 12615@cindex memory models, H8/500 12616@item set memory @var{mod} 12617@itemx show memory 12618Specify which H8/500 memory model (@var{mod}) you are using with 12619@samp{set memory}; check which memory model is in effect with @samp{show 12620memory}. The accepted values for @var{mod} are @code{small}, 12621@code{big}, @code{medium}, and @code{compact}. 12622 12623@end table 12624 12625@node M32R/D 12626@subsection Renesas M32R/D 12627 12628@table @code 12629 12630@kindex target m32r 12631@item target m32r @var{dev} 12632Renesas M32R/D ROM monitor. 12633 12634@kindex target m32rsdi 12635@item target m32rsdi @var{dev} 12636Renesas M32R SDI server, connected via parallel port to the board. 12637 12638@end table 12639 12640@node M68K 12641@subsection M68k 12642 12643The Motorola m68k configuration includes ColdFire support, and 12644target command for the following ROM monitors. 12645 12646@table @code 12647 12648@kindex target abug 12649@item target abug @var{dev} 12650ABug ROM monitor for M68K. 12651 12652@kindex target cpu32bug 12653@item target cpu32bug @var{dev} 12654CPU32BUG monitor, running on a CPU32 (M68K) board. 12655 12656@kindex target dbug 12657@item target dbug @var{dev} 12658dBUG ROM monitor for Motorola ColdFire. 12659 12660@kindex target est 12661@item target est @var{dev} 12662EST-300 ICE monitor, running on a CPU32 (M68K) board. 12663 12664@kindex target rom68k 12665@item target rom68k @var{dev} 12666ROM 68K monitor, running on an M68K IDP board. 12667 12668@end table 12669 12670@table @code 12671 12672@kindex target rombug 12673@item target rombug @var{dev} 12674ROMBUG ROM monitor for OS/9000. 12675 12676@end table 12677 12678@node MIPS Embedded 12679@subsection MIPS Embedded 12680 12681@cindex MIPS boards 12682@value{GDBN} can use the MIPS remote debugging protocol to talk to a 12683MIPS board attached to a serial line. This is available when 12684you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}. 12685 12686@need 1000 12687Use these @value{GDBN} commands to specify the connection to your target board: 12688 12689@table @code 12690@item target mips @var{port} 12691@kindex target mips @var{port} 12692To run a program on the board, start up @code{@value{GDBP}} with the 12693name of your program as the argument. To connect to the board, use the 12694command @samp{target mips @var{port}}, where @var{port} is the name of 12695the serial port connected to the board. If the program has not already 12696been downloaded to the board, you may use the @code{load} command to 12697download it. You can then use all the usual @value{GDBN} commands. 12698 12699For example, this sequence connects to the target board through a serial 12700port, and loads and runs a program called @var{prog} through the 12701debugger: 12702 12703@smallexample 12704host$ @value{GDBP} @var{prog} 12705@value{GDBN} is free software and @dots{} 12706(@value{GDBP}) target mips /dev/ttyb 12707(@value{GDBP}) load @var{prog} 12708(@value{GDBP}) run 12709@end smallexample 12710 12711@item target mips @var{hostname}:@var{portnumber} 12712On some @value{GDBN} host configurations, you can specify a TCP 12713connection (for instance, to a serial line managed by a terminal 12714concentrator) instead of a serial port, using the syntax 12715@samp{@var{hostname}:@var{portnumber}}. 12716 12717@item target pmon @var{port} 12718@kindex target pmon @var{port} 12719PMON ROM monitor. 12720 12721@item target ddb @var{port} 12722@kindex target ddb @var{port} 12723NEC's DDB variant of PMON for Vr4300. 12724 12725@item target lsi @var{port} 12726@kindex target lsi @var{port} 12727LSI variant of PMON. 12728 12729@kindex target r3900 12730@item target r3900 @var{dev} 12731Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. 12732 12733@kindex target array 12734@item target array @var{dev} 12735Array Tech LSI33K RAID controller board. 12736 12737@end table 12738 12739 12740@noindent 12741@value{GDBN} also supports these special commands for MIPS targets: 12742 12743@table @code 12744@item set processor @var{args} 12745@itemx show processor 12746@kindex set processor @var{args} 12747@kindex show processor 12748Use the @code{set processor} command to set the type of MIPS 12749processor when you want to access processor-type-specific registers. 12750For example, @code{set processor @var{r3041}} tells @value{GDBN} 12751to use the CPU registers appropriate for the 3041 chip. 12752Use the @code{show processor} command to see what MIPS processor @value{GDBN} 12753is using. Use the @code{info reg} command to see what registers 12754@value{GDBN} is using. 12755 12756@item set mipsfpu double 12757@itemx set mipsfpu single 12758@itemx set mipsfpu none 12759@itemx show mipsfpu 12760@kindex set mipsfpu 12761@kindex show mipsfpu 12762@cindex MIPS remote floating point 12763@cindex floating point, MIPS remote 12764If your target board does not support the MIPS floating point 12765coprocessor, you should use the command @samp{set mipsfpu none} (if you 12766need this, you may wish to put the command in your @value{GDBN} init 12767file). This tells @value{GDBN} how to find the return value of 12768functions which return floating point values. It also allows 12769@value{GDBN} to avoid saving the floating point registers when calling 12770functions on the board. If you are using a floating point coprocessor 12771with only single precision floating point support, as on the @sc{r4650} 12772processor, use the command @samp{set mipsfpu single}. The default 12773double precision floating point coprocessor may be selected using 12774@samp{set mipsfpu double}. 12775 12776In previous versions the only choices were double precision or no 12777floating point, so @samp{set mipsfpu on} will select double precision 12778and @samp{set mipsfpu off} will select no floating point. 12779 12780As usual, you can inquire about the @code{mipsfpu} variable with 12781@samp{show mipsfpu}. 12782 12783@item set remotedebug @var{n} 12784@itemx show remotedebug 12785@kindex set remotedebug@r{, MIPS protocol} 12786@kindex show remotedebug@r{, MIPS protocol} 12787@cindex @code{remotedebug}, MIPS protocol 12788@cindex MIPS @code{remotedebug} protocol 12789@c FIXME! For this to be useful, you must know something about the MIPS 12790@c FIXME...protocol. Where is it described? 12791You can see some debugging information about communications with the board 12792by setting the @code{remotedebug} variable. If you set it to @code{1} using 12793@samp{set remotedebug 1}, every packet is displayed. If you set it 12794to @code{2}, every character is displayed. You can check the current value 12795at any time with the command @samp{show remotedebug}. 12796 12797@item set timeout @var{seconds} 12798@itemx set retransmit-timeout @var{seconds} 12799@itemx show timeout 12800@itemx show retransmit-timeout 12801@cindex @code{timeout}, MIPS protocol 12802@cindex @code{retransmit-timeout}, MIPS protocol 12803@kindex set timeout 12804@kindex show timeout 12805@kindex set retransmit-timeout 12806@kindex show retransmit-timeout 12807You can control the timeout used while waiting for a packet, in the MIPS 12808remote protocol, with the @code{set timeout @var{seconds}} command. The 12809default is 5 seconds. Similarly, you can control the timeout used while 12810waiting for an acknowledgement of a packet with the @code{set 12811retransmit-timeout @var{seconds}} command. The default is 3 seconds. 12812You can inspect both values with @code{show timeout} and @code{show 12813retransmit-timeout}. (These commands are @emph{only} available when 12814@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.) 12815 12816The timeout set by @code{set timeout} does not apply when @value{GDBN} 12817is waiting for your program to stop. In that case, @value{GDBN} waits 12818forever because it has no way of knowing how long the program is going 12819to run before stopping. 12820@end table 12821 12822@node OpenRISC 1000 12823@subsection OpenRISC 1000 12824@cindex OpenRISC 1000 12825 12826@cindex or1k boards 12827See OR1k Architecture document (@uref{www.opencores.org}) for more information 12828about platform and commands. 12829 12830@table @code 12831 12832@kindex target jtag 12833@item target jtag jtag://@var{host}:@var{port} 12834 12835Connects to remote JTAG server. 12836JTAG remote server can be either an or1ksim or JTAG server, 12837connected via parallel port to the board. 12838 12839Example: @code{target jtag jtag://localhost:9999} 12840 12841@kindex or1ksim 12842@item or1ksim @var{command} 12843If connected to @code{or1ksim} OpenRISC 1000 Architectural 12844Simulator, proprietary commands can be executed. 12845 12846@kindex info or1k spr 12847@item info or1k spr 12848Displays spr groups. 12849 12850@item info or1k spr @var{group} 12851@itemx info or1k spr @var{groupno} 12852Displays register names in selected group. 12853 12854@item info or1k spr @var{group} @var{register} 12855@itemx info or1k spr @var{register} 12856@itemx info or1k spr @var{groupno} @var{registerno} 12857@itemx info or1k spr @var{registerno} 12858Shows information about specified spr register. 12859 12860@kindex spr 12861@item spr @var{group} @var{register} @var{value} 12862@itemx spr @var{register @var{value}} 12863@itemx spr @var{groupno} @var{registerno @var{value}} 12864@itemx spr @var{registerno @var{value}} 12865Writes @var{value} to specified spr register. 12866@end table 12867 12868Some implementations of OpenRISC 1000 Architecture also have hardware trace. 12869It is very similar to @value{GDBN} trace, except it does not interfere with normal 12870program execution and is thus much faster. Hardware breakpoints/watchpoint 12871triggers can be set using: 12872@table @code 12873@item $LEA/$LDATA 12874Load effective address/data 12875@item $SEA/$SDATA 12876Store effective address/data 12877@item $AEA/$ADATA 12878Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA) 12879@item $FETCH 12880Fetch data 12881@end table 12882 12883When triggered, it can capture low level data, like: @code{PC}, @code{LSEA}, 12884@code{LDATA}, @code{SDATA}, @code{READSPR}, @code{WRITESPR}, @code{INSTR}. 12885 12886@code{htrace} commands: 12887@cindex OpenRISC 1000 htrace 12888@table @code 12889@kindex hwatch 12890@item hwatch @var{conditional} 12891Set hardware watchpoint on combination of Load/Store Effecive Address(es) 12892or Data. For example: 12893 12894@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)} 12895 12896@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)} 12897 12898@kindex htrace 12899@item htrace info 12900Display information about current HW trace configuration. 12901 12902@item htrace trigger @var{conditional} 12903Set starting criteria for HW trace. 12904 12905@item htrace qualifier @var{conditional} 12906Set acquisition qualifier for HW trace. 12907 12908@item htrace stop @var{conditional} 12909Set HW trace stopping criteria. 12910 12911@item htrace record [@var{data}]* 12912Selects the data to be recorded, when qualifier is met and HW trace was 12913triggered. 12914 12915@item htrace enable 12916@itemx htrace disable 12917Enables/disables the HW trace. 12918 12919@item htrace rewind [@var{filename}] 12920Clears currently recorded trace data. 12921 12922If filename is specified, new trace file is made and any newly collected data 12923will be written there. 12924 12925@item htrace print [@var{start} [@var{len}]] 12926Prints trace buffer, using current record configuration. 12927 12928@item htrace mode continuous 12929Set continuous trace mode. 12930 12931@item htrace mode suspend 12932Set suspend trace mode. 12933 12934@end table 12935 12936@node PowerPC 12937@subsection PowerPC 12938 12939@table @code 12940 12941@kindex target dink32 12942@item target dink32 @var{dev} 12943DINK32 ROM monitor. 12944 12945@kindex target ppcbug 12946@item target ppcbug @var{dev} 12947@kindex target ppcbug1 12948@item target ppcbug1 @var{dev} 12949PPCBUG ROM monitor for PowerPC. 12950 12951@kindex target sds 12952@item target sds @var{dev} 12953SDS monitor, running on a PowerPC board (such as Motorola's ADS). 12954 12955@end table 12956 12957@node PA 12958@subsection HP PA Embedded 12959 12960@table @code 12961 12962@kindex target op50n 12963@item target op50n @var{dev} 12964OP50N monitor, running on an OKI HPPA board. 12965 12966@kindex target w89k 12967@item target w89k @var{dev} 12968W89K monitor, running on a Winbond HPPA board. 12969 12970@end table 12971 12972@node SH 12973@subsection Renesas SH 12974 12975@table @code 12976 12977@kindex target hms@r{, with Renesas SH} 12978@item target hms @var{dev} 12979A Renesas SH board attached via serial line to your host. Use special 12980commands @code{device} and @code{speed} to control the serial line and 12981the communications speed used. 12982 12983@kindex target e7000@r{, with Renesas SH} 12984@item target e7000 @var{dev} 12985E7000 emulator for Renesas SH. 12986 12987@kindex target sh3@r{, with SH} 12988@kindex target sh3e@r{, with SH} 12989@item target sh3 @var{dev} 12990@item target sh3e @var{dev} 12991Renesas SH-3 and SH-3E target systems. 12992 12993@end table 12994 12995@node Sparclet 12996@subsection Tsqware Sparclet 12997 12998@cindex Sparclet 12999 13000@value{GDBN} enables developers to debug tasks running on 13001Sparclet targets from a Unix host. 13002@value{GDBN} uses code that runs on 13003both the Unix host and on the Sparclet target. The program 13004@code{@value{GDBP}} is installed and executed on the Unix host. 13005 13006@table @code 13007@item remotetimeout @var{args} 13008@kindex remotetimeout 13009@value{GDBN} supports the option @code{remotetimeout}. 13010This option is set by the user, and @var{args} represents the number of 13011seconds @value{GDBN} waits for responses. 13012@end table 13013 13014@cindex compiling, on Sparclet 13015When compiling for debugging, include the options @samp{-g} to get debug 13016information and @samp{-Ttext} to relocate the program to where you wish to 13017load it on the target. You may also want to add the options @samp{-n} or 13018@samp{-N} in order to reduce the size of the sections. Example: 13019 13020@smallexample 13021sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N 13022@end smallexample 13023 13024You can use @code{objdump} to verify that the addresses are what you intended: 13025 13026@smallexample 13027sparclet-aout-objdump --headers --syms prog 13028@end smallexample 13029 13030@cindex running, on Sparclet 13031Once you have set 13032your Unix execution search path to find @value{GDBN}, you are ready to 13033run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} 13034(or @code{sparclet-aout-gdb}, depending on your installation). 13035 13036@value{GDBN} comes up showing the prompt: 13037 13038@smallexample 13039(gdbslet) 13040@end smallexample 13041 13042@menu 13043* Sparclet File:: Setting the file to debug 13044* Sparclet Connection:: Connecting to Sparclet 13045* Sparclet Download:: Sparclet download 13046* Sparclet Execution:: Running and debugging 13047@end menu 13048 13049@node Sparclet File 13050@subsubsection Setting file to debug 13051 13052The @value{GDBN} command @code{file} lets you choose with program to debug. 13053 13054@smallexample 13055(gdbslet) file prog 13056@end smallexample 13057 13058@need 1000 13059@value{GDBN} then attempts to read the symbol table of @file{prog}. 13060@value{GDBN} locates 13061the file by searching the directories listed in the command search 13062path. 13063If the file was compiled with debug information (option "-g"), source 13064files will be searched as well. 13065@value{GDBN} locates 13066the source files by searching the directories listed in the directory search 13067path (@pxref{Environment, ,Your program's environment}). 13068If it fails 13069to find a file, it displays a message such as: 13070 13071@smallexample 13072prog: No such file or directory. 13073@end smallexample 13074 13075When this happens, add the appropriate directories to the search paths with 13076the @value{GDBN} commands @code{path} and @code{dir}, and execute the 13077@code{target} command again. 13078 13079@node Sparclet Connection 13080@subsubsection Connecting to Sparclet 13081 13082The @value{GDBN} command @code{target} lets you connect to a Sparclet target. 13083To connect to a target on serial port ``@code{ttya}'', type: 13084 13085@smallexample 13086(gdbslet) target sparclet /dev/ttya 13087Remote target sparclet connected to /dev/ttya 13088main () at ../prog.c:3 13089@end smallexample 13090 13091@need 750 13092@value{GDBN} displays messages like these: 13093 13094@smallexample 13095Connected to ttya. 13096@end smallexample 13097 13098@node Sparclet Download 13099@subsubsection Sparclet download 13100 13101@cindex download to Sparclet 13102Once connected to the Sparclet target, 13103you can use the @value{GDBN} 13104@code{load} command to download the file from the host to the target. 13105The file name and load offset should be given as arguments to the @code{load} 13106command. 13107Since the file format is aout, the program must be loaded to the starting 13108address. You can use @code{objdump} to find out what this value is. The load 13109offset is an offset which is added to the VMA (virtual memory address) 13110of each of the file's sections. 13111For instance, if the program 13112@file{prog} was linked to text address 0x1201000, with data at 0x12010160 13113and bss at 0x12010170, in @value{GDBN}, type: 13114 13115@smallexample 13116(gdbslet) load prog 0x12010000 13117Loading section .text, size 0xdb0 vma 0x12010000 13118@end smallexample 13119 13120If the code is loaded at a different address then what the program was linked 13121to, you may need to use the @code{section} and @code{add-symbol-file} commands 13122to tell @value{GDBN} where to map the symbol table. 13123 13124@node Sparclet Execution 13125@subsubsection Running and debugging 13126 13127@cindex running and debugging Sparclet programs 13128You can now begin debugging the task using @value{GDBN}'s execution control 13129commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN} 13130manual for the list of commands. 13131 13132@smallexample 13133(gdbslet) b main 13134Breakpoint 1 at 0x12010000: file prog.c, line 3. 13135(gdbslet) run 13136Starting program: prog 13137Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 131383 char *symarg = 0; 13139(gdbslet) step 131404 char *execarg = "hello!"; 13141(gdbslet) 13142@end smallexample 13143 13144@node Sparclite 13145@subsection Fujitsu Sparclite 13146 13147@table @code 13148 13149@kindex target sparclite 13150@item target sparclite @var{dev} 13151Fujitsu sparclite boards, used only for the purpose of loading. 13152You must use an additional command to debug the program. 13153For example: target remote @var{dev} using @value{GDBN} standard 13154remote protocol. 13155 13156@end table 13157 13158@node ST2000 13159@subsection Tandem ST2000 13160 13161@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's 13162STDBUG protocol. 13163 13164To connect your ST2000 to the host system, see the manufacturer's 13165manual. Once the ST2000 is physically attached, you can run: 13166 13167@smallexample 13168target st2000 @var{dev} @var{speed} 13169@end smallexample 13170 13171@noindent 13172to establish it as your debugging environment. @var{dev} is normally 13173the name of a serial device, such as @file{/dev/ttya}, connected to the 13174ST2000 via a serial line. You can instead specify @var{dev} as a TCP 13175connection (for example, to a serial line attached via a terminal 13176concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}. 13177 13178The @code{load} and @code{attach} commands are @emph{not} defined for 13179this target; you must load your program into the ST2000 as you normally 13180would for standalone operation. @value{GDBN} reads debugging information 13181(such as symbols) from a separate, debugging version of the program 13182available on your host computer. 13183@c FIXME!! This is terribly vague; what little content is here is 13184@c basically hearsay. 13185 13186@cindex ST2000 auxiliary commands 13187These auxiliary @value{GDBN} commands are available to help you with the ST2000 13188environment: 13189 13190@table @code 13191@item st2000 @var{command} 13192@kindex st2000 @var{cmd} 13193@cindex STDBUG commands (ST2000) 13194@cindex commands to STDBUG (ST2000) 13195Send a @var{command} to the STDBUG monitor. See the manufacturer's 13196manual for available commands. 13197 13198@item connect 13199@cindex connect (to STDBUG) 13200Connect the controlling terminal to the STDBUG command monitor. When 13201you are done interacting with STDBUG, typing either of two character 13202sequences gets you back to the @value{GDBN} command prompt: 13203@kbd{@key{RET}~.} (Return, followed by tilde and period) or 13204@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D). 13205@end table 13206 13207@node Z8000 13208@subsection Zilog Z8000 13209 13210@cindex Z8000 13211@cindex simulator, Z8000 13212@cindex Zilog Z8000 simulator 13213 13214When configured for debugging Zilog Z8000 targets, @value{GDBN} includes 13215a Z8000 simulator. 13216 13217For the Z8000 family, @samp{target sim} simulates either the Z8002 (the 13218unsegmented variant of the Z8000 architecture) or the Z8001 (the 13219segmented variant). The simulator recognizes which architecture is 13220appropriate by inspecting the object code. 13221 13222@table @code 13223@item target sim @var{args} 13224@kindex sim 13225@kindex target sim@r{, with Z8000} 13226Debug programs on a simulated CPU. If the simulator supports setup 13227options, specify them via @var{args}. 13228@end table 13229 13230@noindent 13231After specifying this target, you can debug programs for the simulated 13232CPU in the same style as programs for your host computer; use the 13233@code{file} command to load a new program image, the @code{run} command 13234to run your program, and so on. 13235 13236As well as making available all the usual machine registers 13237(@pxref{Registers, ,Registers}), the Z8000 simulator provides three 13238additional items of information as specially named registers: 13239 13240@table @code 13241 13242@item cycles 13243Counts clock-ticks in the simulator. 13244 13245@item insts 13246Counts instructions run in the simulator. 13247 13248@item time 13249Execution time in 60ths of a second. 13250 13251@end table 13252 13253You can refer to these values in @value{GDBN} expressions with the usual 13254conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a 13255conditional breakpoint that suspends only after at least 5000 13256simulated clock ticks. 13257 13258@node Architectures 13259@section Architectures 13260 13261This section describes characteristics of architectures that affect 13262all uses of @value{GDBN} with the architecture, both native and cross. 13263 13264@menu 13265* A29K:: 13266* Alpha:: 13267* MIPS:: 13268@end menu 13269 13270@node A29K 13271@subsection A29K 13272 13273@table @code 13274 13275@kindex set rstack_high_address 13276@cindex AMD 29K register stack 13277@cindex register stack, AMD29K 13278@item set rstack_high_address @var{address} 13279On AMD 29000 family processors, registers are saved in a separate 13280@dfn{register stack}. There is no way for @value{GDBN} to determine the 13281extent of this stack. Normally, @value{GDBN} just assumes that the 13282stack is ``large enough''. This may result in @value{GDBN} referencing 13283memory locations that do not exist. If necessary, you can get around 13284this problem by specifying the ending address of the register stack with 13285the @code{set rstack_high_address} command. The argument should be an 13286address, which you probably want to precede with @samp{0x} to specify in 13287hexadecimal. 13288 13289@kindex show rstack_high_address 13290@item show rstack_high_address 13291Display the current limit of the register stack, on AMD 29000 family 13292processors. 13293 13294@end table 13295 13296@node Alpha 13297@subsection Alpha 13298 13299See the following section. 13300 13301@node MIPS 13302@subsection MIPS 13303 13304@cindex stack on Alpha 13305@cindex stack on MIPS 13306@cindex Alpha stack 13307@cindex MIPS stack 13308Alpha- and MIPS-based computers use an unusual stack frame, which 13309sometimes requires @value{GDBN} to search backward in the object code to 13310find the beginning of a function. 13311 13312@cindex response time, MIPS debugging 13313To improve response time (especially for embedded applications, where 13314@value{GDBN} may be restricted to a slow serial line for this search) 13315you may want to limit the size of this search, using one of these 13316commands: 13317 13318@table @code 13319@cindex @code{heuristic-fence-post} (Alpha, MIPS) 13320@item set heuristic-fence-post @var{limit} 13321Restrict @value{GDBN} to examining at most @var{limit} bytes in its 13322search for the beginning of a function. A value of @var{0} (the 13323default) means there is no limit. However, except for @var{0}, the 13324larger the limit the more bytes @code{heuristic-fence-post} must search 13325and therefore the longer it takes to run. 13326 13327@item show heuristic-fence-post 13328Display the current limit. 13329@end table 13330 13331@noindent 13332These commands are available @emph{only} when @value{GDBN} is configured 13333for debugging programs on Alpha or MIPS processors. 13334 13335 13336@node Controlling GDB 13337@chapter Controlling @value{GDBN} 13338 13339You can alter the way @value{GDBN} interacts with you by using the 13340@code{set} command. For commands controlling how @value{GDBN} displays 13341data, see @ref{Print Settings, ,Print settings}. Other settings are 13342described here. 13343 13344@menu 13345* Prompt:: Prompt 13346* Editing:: Command editing 13347* History:: Command history 13348* Screen Size:: Screen size 13349* Numbers:: Numbers 13350* ABI:: Configuring the current ABI 13351* Messages/Warnings:: Optional warnings and messages 13352* Debugging Output:: Optional messages about internal happenings 13353@end menu 13354 13355@node Prompt 13356@section Prompt 13357 13358@cindex prompt 13359 13360@value{GDBN} indicates its readiness to read a command by printing a string 13361called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You 13362can change the prompt string with the @code{set prompt} command. For 13363instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change 13364the prompt in one of the @value{GDBN} sessions so that you can always tell 13365which one you are talking to. 13366 13367@emph{Note:} @code{set prompt} does not add a space for you after the 13368prompt you set. This allows you to set a prompt which ends in a space 13369or a prompt that does not. 13370 13371@table @code 13372@kindex set prompt 13373@item set prompt @var{newprompt} 13374Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth. 13375 13376@kindex show prompt 13377@item show prompt 13378Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}} 13379@end table 13380 13381@node Editing 13382@section Command editing 13383@cindex readline 13384@cindex command line editing 13385 13386@value{GDBN} reads its input commands via the @dfn{Readline} interface. This 13387@sc{gnu} library provides consistent behavior for programs which provide a 13388command line interface to the user. Advantages are @sc{gnu} Emacs-style 13389or @dfn{vi}-style inline editing of commands, @code{csh}-like history 13390substitution, and a storage and recall of command history across 13391debugging sessions. 13392 13393You may control the behavior of command line editing in @value{GDBN} with the 13394command @code{set}. 13395 13396@table @code 13397@kindex set editing 13398@cindex editing 13399@item set editing 13400@itemx set editing on 13401Enable command line editing (enabled by default). 13402 13403@item set editing off 13404Disable command line editing. 13405 13406@kindex show editing 13407@item show editing 13408Show whether command line editing is enabled. 13409@end table 13410 13411@xref{Command Line Editing}, for more details about the Readline 13412interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are 13413encouraged to read that chapter. 13414 13415@node History 13416@section Command history 13417@cindex command history 13418 13419@value{GDBN} can keep track of the commands you type during your 13420debugging sessions, so that you can be certain of precisely what 13421happened. Use these commands to manage the @value{GDBN} command 13422history facility. 13423 13424@value{GDBN} uses the @sc{gnu} History library, a part of the Readline 13425package, to provide the history facility. @xref{Using History 13426Interactively}, for the detailed description of the History library. 13427 13428Here is the description of @value{GDBN} commands related to command 13429history. 13430 13431@table @code 13432@cindex history substitution 13433@cindex history file 13434@kindex set history filename 13435@cindex @env{GDBHISTFILE}, environment variable 13436@item set history filename @var{fname} 13437Set the name of the @value{GDBN} command history file to @var{fname}. 13438This is the file where @value{GDBN} reads an initial command history 13439list, and where it writes the command history from this session when it 13440exits. You can access this list through history expansion or through 13441the history command editing characters listed below. This file defaults 13442to the value of the environment variable @code{GDBHISTFILE}, or to 13443@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable 13444is not set. 13445 13446@cindex history save 13447@kindex set history 13448@item set history save 13449@itemx set history save on 13450Record command history in a file, whose name may be specified with the 13451@code{set history filename} command. By default, this option is disabled. 13452 13453@item set history save off 13454Stop recording command history in a file. 13455 13456@cindex history size 13457@item set history size @var{size} 13458Set the number of commands which @value{GDBN} keeps in its history list. 13459This defaults to the value of the environment variable 13460@code{HISTSIZE}, or to 256 if this variable is not set. 13461@end table 13462 13463History expansion assigns special meaning to the character @kbd{!}. 13464@xref{Event Designators}, for more details. 13465 13466@cindex history expansion, turn on/off 13467Since @kbd{!} is also the logical not operator in C, history expansion 13468is off by default. If you decide to enable history expansion with the 13469@code{set history expansion on} command, you may sometimes need to 13470follow @kbd{!} (when it is used as logical not, in an expression) with 13471a space or a tab to prevent it from being expanded. The readline 13472history facilities do not attempt substitution on the strings 13473@kbd{!=} and @kbd{!(}, even when history expansion is enabled. 13474 13475The commands to control history expansion are: 13476 13477@table @code 13478@item set history expansion on 13479@itemx set history expansion 13480@kindex set history expansion 13481Enable history expansion. History expansion is off by default. 13482 13483@item set history expansion off 13484Disable history expansion. 13485 13486@c @group 13487@kindex show history 13488@item show history 13489@itemx show history filename 13490@itemx show history save 13491@itemx show history size 13492@itemx show history expansion 13493These commands display the state of the @value{GDBN} history parameters. 13494@code{show history} by itself displays all four states. 13495@c @end group 13496@end table 13497 13498@table @code 13499@kindex shows 13500@item show commands 13501Display the last ten commands in the command history. 13502 13503@item show commands @var{n} 13504Print ten commands centered on command number @var{n}. 13505 13506@item show commands + 13507Print ten commands just after the commands last printed. 13508@end table 13509 13510@node Screen Size 13511@section Screen size 13512@cindex size of screen 13513@cindex pauses in output 13514 13515Certain commands to @value{GDBN} may produce large amounts of 13516information output to the screen. To help you read all of it, 13517@value{GDBN} pauses and asks you for input at the end of each page of 13518output. Type @key{RET} when you want to continue the output, or @kbd{q} 13519to discard the remaining output. Also, the screen width setting 13520determines when to wrap lines of output. Depending on what is being 13521printed, @value{GDBN} tries to break the line at a readable place, 13522rather than simply letting it overflow onto the following line. 13523 13524Normally @value{GDBN} knows the size of the screen from the terminal 13525driver software. For example, on Unix @value{GDBN} uses the termcap data base 13526together with the value of the @code{TERM} environment variable and the 13527@code{stty rows} and @code{stty cols} settings. If this is not correct, 13528you can override it with the @code{set height} and @code{set 13529width} commands: 13530 13531@table @code 13532@kindex set height 13533@kindex set width 13534@kindex show width 13535@kindex show height 13536@item set height @var{lpp} 13537@itemx show height 13538@itemx set width @var{cpl} 13539@itemx show width 13540These @code{set} commands specify a screen height of @var{lpp} lines and 13541a screen width of @var{cpl} characters. The associated @code{show} 13542commands display the current settings. 13543 13544If you specify a height of zero lines, @value{GDBN} does not pause during 13545output no matter how long the output is. This is useful if output is to a 13546file or to an editor buffer. 13547 13548Likewise, you can specify @samp{set width 0} to prevent @value{GDBN} 13549from wrapping its output. 13550@end table 13551 13552@node Numbers 13553@section Numbers 13554@cindex number representation 13555@cindex entering numbers 13556 13557You can always enter numbers in octal, decimal, or hexadecimal in 13558@value{GDBN} by the usual conventions: octal numbers begin with 13559@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers 13560begin with @samp{0x}. Numbers that begin with none of these are, by 13561default, entered in base 10; likewise, the default display for 13562numbers---when no particular format is specified---is base 10. You can 13563change the default base for both input and output with the @code{set 13564radix} command. 13565 13566@table @code 13567@kindex set input-radix 13568@item set input-radix @var{base} 13569Set the default base for numeric input. Supported choices 13570for @var{base} are decimal 8, 10, or 16. @var{base} must itself be 13571specified either unambiguously or using the current default radix; for 13572example, any of 13573 13574@smallexample 13575set radix 012 13576set radix 10. 13577set radix 0xa 13578@end smallexample 13579 13580@noindent 13581sets the base to decimal. On the other hand, @samp{set radix 10} 13582leaves the radix unchanged no matter what it was. 13583 13584@kindex set output-radix 13585@item set output-radix @var{base} 13586Set the default base for numeric display. Supported choices 13587for @var{base} are decimal 8, 10, or 16. @var{base} must itself be 13588specified either unambiguously or using the current default radix. 13589 13590@kindex show input-radix 13591@item show input-radix 13592Display the current default base for numeric input. 13593 13594@kindex show output-radix 13595@item show output-radix 13596Display the current default base for numeric display. 13597@end table 13598 13599@node ABI 13600@section Configuring the current ABI 13601 13602@value{GDBN} can determine the @dfn{ABI} (Application Binary Interface) of your 13603application automatically. However, sometimes you need to override its 13604conclusions. Use these commands to manage @value{GDBN}'s view of the 13605current ABI. 13606 13607@cindex OS ABI 13608@kindex set osabi 13609@kindex show osabi 13610 13611One @value{GDBN} configuration can debug binaries for multiple operating 13612system targets, either via remote debugging or native emulation. 13613@value{GDBN} will autodetect the @dfn{OS ABI} (Operating System ABI) in use, 13614but you can override its conclusion using the @code{set osabi} command. 13615One example where this is useful is in debugging of binaries which use 13616an alternate C library (e.g.@: @sc{uClibc} for @sc{gnu}/Linux) which does 13617not have the same identifying marks that the standard C library for your 13618platform provides. 13619 13620@table @code 13621@item show osabi 13622Show the OS ABI currently in use. 13623 13624@item set osabi 13625With no argument, show the list of registered available OS ABI's. 13626 13627@item set osabi @var{abi} 13628Set the current OS ABI to @var{abi}. 13629@end table 13630 13631@cindex float promotion 13632@kindex set coerce-float-to-double 13633 13634Generally, the way that an argument of type @code{float} is passed to a 13635function depends on whether the function is prototyped. For a prototyped 13636(i.e.@: ANSI/ISO style) function, @code{float} arguments are passed unchanged, 13637according to the architecture's convention for @code{float}. For unprototyped 13638(i.e.@: K&R style) functions, @code{float} arguments are first promoted to type 13639@code{double} and then passed. 13640 13641Unfortunately, some forms of debug information do not reliably indicate whether 13642a function is prototyped. If @value{GDBN} calls a function that is not marked 13643as prototyped, it consults @kbd{set coerce-float-to-double}. 13644 13645@table @code 13646@item set coerce-float-to-double 13647@itemx set coerce-float-to-double on 13648Arguments of type @code{float} will be promoted to @code{double} when passed 13649to an unprototyped function. This is the default setting. 13650 13651@item set coerce-float-to-double off 13652Arguments of type @code{float} will be passed directly to unprototyped 13653functions. 13654@end table 13655 13656@kindex set cp-abi 13657@kindex show cp-abi 13658@value{GDBN} needs to know the ABI used for your program's C@t{++} 13659objects. The correct C@t{++} ABI depends on which C@t{++} compiler was 13660used to build your application. @value{GDBN} only fully supports 13661programs with a single C@t{++} ABI; if your program contains code using 13662multiple C@t{++} ABI's or if @value{GDBN} can not identify your 13663program's ABI correctly, you can tell @value{GDBN} which ABI to use. 13664Currently supported ABI's include ``gnu-v2'', for @code{g++} versions 13665before 3.0, ``gnu-v3'', for @code{g++} versions 3.0 and later, and 13666``hpaCC'' for the HP ANSI C@t{++} compiler. Other C@t{++} compilers may 13667use the ``gnu-v2'' or ``gnu-v3'' ABI's as well. The default setting is 13668``auto''. 13669 13670@table @code 13671@item show cp-abi 13672Show the C@t{++} ABI currently in use. 13673 13674@item set cp-abi 13675With no argument, show the list of supported C@t{++} ABI's. 13676 13677@item set cp-abi @var{abi} 13678@itemx set cp-abi auto 13679Set the current C@t{++} ABI to @var{abi}, or return to automatic detection. 13680@end table 13681 13682@node Messages/Warnings 13683@section Optional warnings and messages 13684 13685By default, @value{GDBN} is silent about its inner workings. If you are 13686running on a slow machine, you may want to use the @code{set verbose} 13687command. This makes @value{GDBN} tell you when it does a lengthy 13688internal operation, so you will not think it has crashed. 13689 13690Currently, the messages controlled by @code{set verbose} are those 13691which announce that the symbol table for a source file is being read; 13692see @code{symbol-file} in @ref{Files, ,Commands to specify files}. 13693 13694@table @code 13695@kindex set verbose 13696@item set verbose on 13697Enables @value{GDBN} output of certain informational messages. 13698 13699@item set verbose off 13700Disables @value{GDBN} output of certain informational messages. 13701 13702@kindex show verbose 13703@item show verbose 13704Displays whether @code{set verbose} is on or off. 13705@end table 13706 13707By default, if @value{GDBN} encounters bugs in the symbol table of an 13708object file, it is silent; but if you are debugging a compiler, you may 13709find this information useful (@pxref{Symbol Errors, ,Errors reading 13710symbol files}). 13711 13712@table @code 13713 13714@kindex set complaints 13715@item set complaints @var{limit} 13716Permits @value{GDBN} to output @var{limit} complaints about each type of 13717unusual symbols before becoming silent about the problem. Set 13718@var{limit} to zero to suppress all complaints; set it to a large number 13719to prevent complaints from being suppressed. 13720 13721@kindex show complaints 13722@item show complaints 13723Displays how many symbol complaints @value{GDBN} is permitted to produce. 13724 13725@end table 13726 13727By default, @value{GDBN} is cautious, and asks what sometimes seems to be a 13728lot of stupid questions to confirm certain commands. For example, if 13729you try to run a program which is already running: 13730 13731@smallexample 13732(@value{GDBP}) run 13733The program being debugged has been started already. 13734Start it from the beginning? (y or n) 13735@end smallexample 13736 13737If you are willing to unflinchingly face the consequences of your own 13738commands, you can disable this ``feature'': 13739 13740@table @code 13741 13742@kindex set confirm 13743@cindex flinching 13744@cindex confirmation 13745@cindex stupid questions 13746@item set confirm off 13747Disables confirmation requests. 13748 13749@item set confirm on 13750Enables confirmation requests (the default). 13751 13752@kindex show confirm 13753@item show confirm 13754Displays state of confirmation requests. 13755 13756@end table 13757 13758@node Debugging Output 13759@section Optional messages about internal happenings 13760@cindex optional debugging messages 13761 13762@table @code 13763@kindex set debug 13764@cindex gdbarch debugging info 13765@item set debug arch 13766Turns on or off display of gdbarch debugging info. The default is off 13767@kindex show debug 13768@item show debug arch 13769Displays the current state of displaying gdbarch debugging info. 13770@item set debug event 13771@cindex event debugging info 13772Turns on or off display of @value{GDBN} event debugging info. The 13773default is off. 13774@item show debug event 13775Displays the current state of displaying @value{GDBN} event debugging 13776info. 13777@item set debug expression 13778@cindex expression debugging info 13779Turns on or off display of @value{GDBN} expression debugging info. The 13780default is off. 13781@item show debug expression 13782Displays the current state of displaying @value{GDBN} expression 13783debugging info. 13784@item set debug frame 13785@cindex frame debugging info 13786Turns on or off display of @value{GDBN} frame debugging info. The 13787default is off. 13788@item show debug frame 13789Displays the current state of displaying @value{GDBN} frame debugging 13790info. 13791@item set debug observer 13792@cindex observer debugging info 13793Turns on or off display of @value{GDBN} observer debugging. This 13794includes info such as the notification of observable events. 13795@item show debug observer 13796Displays the current state of observer debugging. 13797@item set debug overload 13798@cindex C@t{++} overload debugging info 13799Turns on or off display of @value{GDBN} C@t{++} overload debugging 13800info. This includes info such as ranking of functions, etc. The default 13801is off. 13802@item show debug overload 13803Displays the current state of displaying @value{GDBN} C@t{++} overload 13804debugging info. 13805@cindex packets, reporting on stdout 13806@cindex serial connections, debugging 13807@item set debug remote 13808Turns on or off display of reports on all packets sent back and forth across 13809the serial line to the remote machine. The info is printed on the 13810@value{GDBN} standard output stream. The default is off. 13811@item show debug remote 13812Displays the state of display of remote packets. 13813@item set debug serial 13814Turns on or off display of @value{GDBN} serial debugging info. The 13815default is off. 13816@item show debug serial 13817Displays the current state of displaying @value{GDBN} serial debugging 13818info. 13819@item set debug target 13820@cindex target debugging info 13821Turns on or off display of @value{GDBN} target debugging info. This info 13822includes what is going on at the target level of GDB, as it happens. The 13823default is 0. Set it to 1 to track events, and to 2 to also track the 13824value of large memory transfers. Changes to this flag do not take effect 13825until the next time you connect to a target or use the @code{run} command. 13826@item show debug target 13827Displays the current state of displaying @value{GDBN} target debugging 13828info. 13829@item set debug varobj 13830@cindex variable object debugging info 13831Turns on or off display of @value{GDBN} variable object debugging 13832info. The default is off. 13833@item show debug varobj 13834Displays the current state of displaying @value{GDBN} variable object 13835debugging info. 13836@end table 13837 13838@node Sequences 13839@chapter Canned Sequences of Commands 13840 13841Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint 13842command lists}), @value{GDBN} provides two ways to store sequences of 13843commands for execution as a unit: user-defined commands and command 13844files. 13845 13846@menu 13847* Define:: User-defined commands 13848* Hooks:: User-defined command hooks 13849* Command Files:: Command files 13850* Output:: Commands for controlled output 13851@end menu 13852 13853@node Define 13854@section User-defined commands 13855 13856@cindex user-defined command 13857A @dfn{user-defined command} is a sequence of @value{GDBN} commands to 13858which you assign a new name as a command. This is done with the 13859@code{define} command. User commands may accept up to 10 arguments 13860separated by whitespace. Arguments are accessed within the user command 13861via @var{$arg0@dots{}$arg9}. A trivial example: 13862 13863@smallexample 13864define adder 13865 print $arg0 + $arg1 + $arg2 13866@end smallexample 13867 13868@noindent 13869To execute the command use: 13870 13871@smallexample 13872adder 1 2 3 13873@end smallexample 13874 13875@noindent 13876This defines the command @code{adder}, which prints the sum of 13877its three arguments. Note the arguments are text substitutions, so they may 13878reference variables, use complex expressions, or even perform inferior 13879functions calls. 13880 13881@table @code 13882 13883@kindex define 13884@item define @var{commandname} 13885Define a command named @var{commandname}. If there is already a command 13886by that name, you are asked to confirm that you want to redefine it. 13887 13888The definition of the command is made up of other @value{GDBN} command lines, 13889which are given following the @code{define} command. The end of these 13890commands is marked by a line containing @code{end}. 13891 13892@kindex if 13893@kindex else 13894@item if 13895Takes a single argument, which is an expression to evaluate. 13896It is followed by a series of commands that are executed 13897only if the expression is true (nonzero). 13898There can then optionally be a line @code{else}, followed 13899by a series of commands that are only executed if the expression 13900was false. The end of the list is marked by a line containing @code{end}. 13901 13902@kindex while 13903@item while 13904The syntax is similar to @code{if}: the command takes a single argument, 13905which is an expression to evaluate, and must be followed by the commands to 13906execute, one per line, terminated by an @code{end}. 13907The commands are executed repeatedly as long as the expression 13908evaluates to true. 13909 13910@kindex document 13911@item document @var{commandname} 13912Document the user-defined command @var{commandname}, so that it can be 13913accessed by @code{help}. The command @var{commandname} must already be 13914defined. This command reads lines of documentation just as @code{define} 13915reads the lines of the command definition, ending with @code{end}. 13916After the @code{document} command is finished, @code{help} on command 13917@var{commandname} displays the documentation you have written. 13918 13919You may use the @code{document} command again to change the 13920documentation of a command. Redefining the command with @code{define} 13921does not change the documentation. 13922 13923@kindex help user-defined 13924@item help user-defined 13925List all user-defined commands, with the first line of the documentation 13926(if any) for each. 13927 13928@kindex show user 13929@item show user 13930@itemx show user @var{commandname} 13931Display the @value{GDBN} commands used to define @var{commandname} (but 13932not its documentation). If no @var{commandname} is given, display the 13933definitions for all user-defined commands. 13934 13935@kindex show max-user-call-depth 13936@kindex set max-user-call-depth 13937@item show max-user-call-depth 13938@itemx set max-user-call-depth 13939The value of @code{max-user-call-depth} controls how many recursion 13940levels are allowed in user-defined commands before GDB suspects an 13941infinite recursion and aborts the command. 13942 13943@end table 13944 13945When user-defined commands are executed, the 13946commands of the definition are not printed. An error in any command 13947stops execution of the user-defined command. 13948 13949If used interactively, commands that would ask for confirmation proceed 13950without asking when used inside a user-defined command. Many @value{GDBN} 13951commands that normally print messages to say what they are doing omit the 13952messages when used in a user-defined command. 13953 13954@node Hooks 13955@section User-defined command hooks 13956@cindex command hooks 13957@cindex hooks, for commands 13958@cindex hooks, pre-command 13959 13960@kindex hook 13961You may define @dfn{hooks}, which are a special kind of user-defined 13962command. Whenever you run the command @samp{foo}, if the user-defined 13963command @samp{hook-foo} exists, it is executed (with no arguments) 13964before that command. 13965 13966@cindex hooks, post-command 13967@kindex hookpost 13968A hook may also be defined which is run after the command you executed. 13969Whenever you run the command @samp{foo}, if the user-defined command 13970@samp{hookpost-foo} exists, it is executed (with no arguments) after 13971that command. Post-execution hooks may exist simultaneously with 13972pre-execution hooks, for the same command. 13973 13974It is valid for a hook to call the command which it hooks. If this 13975occurs, the hook is not re-executed, thereby avoiding infinte recursion. 13976 13977@c It would be nice if hookpost could be passed a parameter indicating 13978@c if the command it hooks executed properly or not. FIXME! 13979 13980@kindex stop@r{, a pseudo-command} 13981In addition, a pseudo-command, @samp{stop} exists. Defining 13982(@samp{hook-stop}) makes the associated commands execute every time 13983execution stops in your program: before breakpoint commands are run, 13984displays are printed, or the stack frame is printed. 13985 13986For example, to ignore @code{SIGALRM} signals while 13987single-stepping, but treat them normally during normal execution, 13988you could define: 13989 13990@smallexample 13991define hook-stop 13992handle SIGALRM nopass 13993end 13994 13995define hook-run 13996handle SIGALRM pass 13997end 13998 13999define hook-continue 14000handle SIGLARM pass 14001end 14002@end smallexample 14003 14004As a further example, to hook at the begining and end of the @code{echo} 14005command, and to add extra text to the beginning and end of the message, 14006you could define: 14007 14008@smallexample 14009define hook-echo 14010echo <<<--- 14011end 14012 14013define hookpost-echo 14014echo --->>>\n 14015end 14016 14017(@value{GDBP}) echo Hello World 14018<<<---Hello World--->>> 14019(@value{GDBP}) 14020 14021@end smallexample 14022 14023You can define a hook for any single-word command in @value{GDBN}, but 14024not for command aliases; you should define a hook for the basic command 14025name, e.g. @code{backtrace} rather than @code{bt}. 14026@c FIXME! So how does Joe User discover whether a command is an alias 14027@c or not? 14028If an error occurs during the execution of your hook, execution of 14029@value{GDBN} commands stops and @value{GDBN} issues a prompt 14030(before the command that you actually typed had a chance to run). 14031 14032If you try to define a hook which does not match any known command, you 14033get a warning from the @code{define} command. 14034 14035@node Command Files 14036@section Command files 14037 14038@cindex command files 14039A command file for @value{GDBN} is a file of lines that are @value{GDBN} 14040commands. Comments (lines starting with @kbd{#}) may also be included. 14041An empty line in a command file does nothing; it does not mean to repeat 14042the last command, as it would from the terminal. 14043 14044@cindex init file 14045@cindex @file{.gdbinit} 14046@cindex @file{gdb.ini} 14047When you start @value{GDBN}, it automatically executes commands from its 14048@dfn{init files}, normally called @file{.gdbinit}@footnote{The DJGPP 14049port of @value{GDBN} uses the name @file{gdb.ini} instead, due to the 14050limitations of file names imposed by DOS filesystems.}. 14051During startup, @value{GDBN} does the following: 14052 14053@enumerate 14054@item 14055Reads the init file (if any) in your home directory@footnote{On 14056DOS/Windows systems, the home directory is the one pointed to by the 14057@code{HOME} environment variable.}. 14058 14059@item 14060Processes command line options and operands. 14061 14062@item 14063Reads the init file (if any) in the current working directory. 14064 14065@item 14066Reads command files specified by the @samp{-x} option. 14067@end enumerate 14068 14069The init file in your home directory can set options (such as @samp{set 14070complaints}) that affect subsequent processing of command line options 14071and operands. Init files are not executed if you use the @samp{-nx} 14072option (@pxref{Mode Options, ,Choosing modes}). 14073 14074@cindex init file name 14075On some configurations of @value{GDBN}, the init file is known by a 14076different name (these are typically environments where a specialized 14077form of @value{GDBN} may need to coexist with other forms, hence a 14078different name for the specialized version's init file). These are the 14079environments with special init file names: 14080 14081@cindex @file{.vxgdbinit} 14082@itemize @bullet 14083@item 14084VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit} 14085 14086@cindex @file{.os68gdbinit} 14087@item 14088OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit} 14089 14090@cindex @file{.esgdbinit} 14091@item 14092ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit} 14093@end itemize 14094 14095You can also request the execution of a command file with the 14096@code{source} command: 14097 14098@table @code 14099@kindex source 14100@item source @var{filename} 14101Execute the command file @var{filename}. 14102@end table 14103 14104The lines in a command file are executed sequentially. They are not 14105printed as they are executed. An error in any command terminates 14106execution of the command file and control is returned to the console. 14107 14108Commands that would ask for confirmation if used interactively proceed 14109without asking when used in a command file. Many @value{GDBN} commands that 14110normally print messages to say what they are doing omit the messages 14111when called from command files. 14112 14113@value{GDBN} also accepts command input from standard input. In this 14114mode, normal output goes to standard output and error output goes to 14115standard error. Errors in a command file supplied on standard input do 14116not terminate execution of the command file --- execution continues with 14117the next command. 14118 14119@smallexample 14120gdb < cmds > log 2>&1 14121@end smallexample 14122 14123(The syntax above will vary depending on the shell used.) This example 14124will execute commands from the file @file{cmds}. All output and errors 14125would be directed to @file{log}. 14126 14127@node Output 14128@section Commands for controlled output 14129 14130During the execution of a command file or a user-defined command, normal 14131@value{GDBN} output is suppressed; the only output that appears is what is 14132explicitly printed by the commands in the definition. This section 14133describes three commands useful for generating exactly the output you 14134want. 14135 14136@table @code 14137@kindex echo 14138@item echo @var{text} 14139@c I do not consider backslash-space a standard C escape sequence 14140@c because it is not in ANSI. 14141Print @var{text}. Nonprinting characters can be included in 14142@var{text} using C escape sequences, such as @samp{\n} to print a 14143newline. @strong{No newline is printed unless you specify one.} 14144In addition to the standard C escape sequences, a backslash followed 14145by a space stands for a space. This is useful for displaying a 14146string with spaces at the beginning or the end, since leading and 14147trailing spaces are otherwise trimmed from all arguments. 14148To print @samp{@w{ }and foo =@w{ }}, use the command 14149@samp{echo \@w{ }and foo = \@w{ }}. 14150 14151A backslash at the end of @var{text} can be used, as in C, to continue 14152the command onto subsequent lines. For example, 14153 14154@smallexample 14155echo This is some text\n\ 14156which is continued\n\ 14157onto several lines.\n 14158@end smallexample 14159 14160produces the same output as 14161 14162@smallexample 14163echo This is some text\n 14164echo which is continued\n 14165echo onto several lines.\n 14166@end smallexample 14167 14168@kindex output 14169@item output @var{expression} 14170Print the value of @var{expression} and nothing but that value: no 14171newlines, no @samp{$@var{nn} = }. The value is not entered in the 14172value history either. @xref{Expressions, ,Expressions}, for more information 14173on expressions. 14174 14175@item output/@var{fmt} @var{expression} 14176Print the value of @var{expression} in format @var{fmt}. You can use 14177the same formats as for @code{print}. @xref{Output Formats,,Output 14178formats}, for more information. 14179 14180@kindex printf 14181@item printf @var{string}, @var{expressions}@dots{} 14182Print the values of the @var{expressions} under the control of 14183@var{string}. The @var{expressions} are separated by commas and may be 14184either numbers or pointers. Their values are printed as specified by 14185@var{string}, exactly as if your program were to execute the C 14186subroutine 14187@c FIXME: the above implies that at least all ANSI C formats are 14188@c supported, but it isn't true: %E and %G don't work (or so it seems). 14189@c Either this is a bug, or the manual should document what formats are 14190@c supported. 14191 14192@smallexample 14193printf (@var{string}, @var{expressions}@dots{}); 14194@end smallexample 14195 14196For example, you can print two values in hex like this: 14197 14198@smallexample 14199printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo 14200@end smallexample 14201 14202The only backslash-escape sequences that you can use in the format 14203string are the simple ones that consist of backslash followed by a 14204letter. 14205@end table 14206 14207@node Interpreters 14208@chapter Command Interpreters 14209@cindex command interpreters 14210 14211@value{GDBN} supports multiple command interpreters, and some command 14212infrastructure to allow users or user interface writers to switch 14213between interpreters or run commands in other interpreters. 14214 14215@value{GDBN} currently supports two command interpreters, the console 14216interpreter (sometimes called the command-line interpreter or @sc{cli}) 14217and the machine interface interpreter (or @sc{gdb/mi}). This manual 14218describes both of these interfaces in great detail. 14219 14220By default, @value{GDBN} will start with the console interpreter. 14221However, the user may choose to start @value{GDBN} with another 14222interpreter by specifying the @option{-i} or @option{--interpreter} 14223startup options. Defined interpreters include: 14224 14225@table @code 14226@item console 14227@cindex console interpreter 14228The traditional console or command-line interpreter. This is the most often 14229used interpreter with @value{GDBN}. With no interpreter specified at runtime, 14230@value{GDBN} will use this interpreter. 14231 14232@item mi 14233@cindex mi interpreter 14234The newest @sc{gdb/mi} interface (currently @code{mi2}). Used primarily 14235by programs wishing to use @value{GDBN} as a backend for a debugger GUI 14236or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi} 14237Interface}. 14238 14239@item mi2 14240@cindex mi2 interpreter 14241The current @sc{gdb/mi} interface. 14242 14243@item mi1 14244@cindex mi1 interpreter 14245The @sc{gdb/mi} interface included in @value{GDBN} 5.1, 5.2, and 5.3. 14246 14247@end table 14248 14249@cindex invoke another interpreter 14250The interpreter being used by @value{GDBN} may not be dynamically 14251switched at runtime. Although possible, this could lead to a very 14252precarious situation. Consider an IDE using @sc{gdb/mi}. If a user 14253enters the command "interpreter-set console" in a console view, 14254@value{GDBN} would switch to using the console interpreter, rendering 14255the IDE inoperable! 14256 14257@kindex interpreter-exec 14258Although you may only choose a single interpreter at startup, you may execute 14259commands in any interpreter from the current interpreter using the appropriate 14260command. If you are running the console interpreter, simply use the 14261@code{interpreter-exec} command: 14262 14263@smallexample 14264interpreter-exec mi "-data-list-register-names" 14265@end smallexample 14266 14267@sc{gdb/mi} has a similar command, although it is only available in versions of 14268@value{GDBN} which support @sc{gdb/mi} version 2 (or greater). 14269 14270@node TUI 14271@chapter @value{GDBN} Text User Interface 14272@cindex TUI 14273@cindex Text User Interface 14274 14275@menu 14276* TUI Overview:: TUI overview 14277* TUI Keys:: TUI key bindings 14278* TUI Single Key Mode:: TUI single key mode 14279* TUI Commands:: TUI specific commands 14280* TUI Configuration:: TUI configuration variables 14281@end menu 14282 14283The @value{GDBN} Text User Interface, TUI in short, is a terminal 14284interface which uses the @code{curses} library to show the source 14285file, the assembly output, the program registers and @value{GDBN} 14286commands in separate text windows. 14287 14288The TUI is enabled by invoking @value{GDBN} using either 14289@pindex gdbtui 14290@samp{gdbtui} or @samp{gdb -tui}. 14291 14292@node TUI Overview 14293@section TUI overview 14294 14295The TUI has two display modes that can be switched while 14296@value{GDBN} runs: 14297 14298@itemize @bullet 14299@item 14300A curses (or TUI) mode in which it displays several text 14301windows on the terminal. 14302 14303@item 14304A standard mode which corresponds to the @value{GDBN} configured without 14305the TUI. 14306@end itemize 14307 14308In the TUI mode, @value{GDBN} can display several text window 14309on the terminal: 14310 14311@table @emph 14312@item command 14313This window is the @value{GDBN} command window with the @value{GDBN} 14314prompt and the @value{GDBN} outputs. The @value{GDBN} input is still 14315managed using readline but through the TUI. The @emph{command} 14316window is always visible. 14317 14318@item source 14319The source window shows the source file of the program. The current 14320line as well as active breakpoints are displayed in this window. 14321 14322@item assembly 14323The assembly window shows the disassembly output of the program. 14324 14325@item register 14326This window shows the processor registers. It detects when 14327a register is changed and when this is the case, registers that have 14328changed are highlighted. 14329 14330@end table 14331 14332The source and assembly windows show the current program position 14333by highlighting the current line and marking them with the @samp{>} marker. 14334Breakpoints are also indicated with two markers. A first one 14335indicates the breakpoint type: 14336 14337@table @code 14338@item B 14339Breakpoint which was hit at least once. 14340 14341@item b 14342Breakpoint which was never hit. 14343 14344@item H 14345Hardware breakpoint which was hit at least once. 14346 14347@item h 14348Hardware breakpoint which was never hit. 14349 14350@end table 14351 14352The second marker indicates whether the breakpoint is enabled or not: 14353 14354@table @code 14355@item + 14356Breakpoint is enabled. 14357 14358@item - 14359Breakpoint is disabled. 14360 14361@end table 14362 14363The source, assembly and register windows are attached to the thread 14364and the frame position. They are updated when the current thread 14365changes, when the frame changes or when the program counter changes. 14366These three windows are arranged by the TUI according to several 14367layouts. The layout defines which of these three windows are visible. 14368The following layouts are available: 14369 14370@itemize @bullet 14371@item 14372source 14373 14374@item 14375assembly 14376 14377@item 14378source and assembly 14379 14380@item 14381source and registers 14382 14383@item 14384assembly and registers 14385 14386@end itemize 14387 14388On top of the command window a status line gives various information 14389concerning the current process begin debugged. The status line is 14390updated when the information it shows changes. The following fields 14391are displayed: 14392 14393@table @emph 14394@item target 14395Indicates the current gdb target 14396(@pxref{Targets, ,Specifying a Debugging Target}). 14397 14398@item process 14399Gives information about the current process or thread number. 14400When no process is being debugged, this field is set to @code{No process}. 14401 14402@item function 14403Gives the current function name for the selected frame. 14404The name is demangled if demangling is turned on (@pxref{Print Settings}). 14405When there is no symbol corresponding to the current program counter 14406the string @code{??} is displayed. 14407 14408@item line 14409Indicates the current line number for the selected frame. 14410When the current line number is not known the string @code{??} is displayed. 14411 14412@item pc 14413Indicates the current program counter address. 14414 14415@end table 14416 14417@node TUI Keys 14418@section TUI Key Bindings 14419@cindex TUI key bindings 14420 14421The TUI installs several key bindings in the readline keymaps 14422(@pxref{Command Line Editing}). 14423They allow to leave or enter in the TUI mode or they operate 14424directly on the TUI layout and windows. The TUI also provides 14425a @emph{SingleKey} keymap which binds several keys directly to 14426@value{GDBN} commands. The following key bindings 14427are installed for both TUI mode and the @value{GDBN} standard mode. 14428 14429@table @kbd 14430@kindex C-x C-a 14431@item C-x C-a 14432@kindex C-x a 14433@itemx C-x a 14434@kindex C-x A 14435@itemx C-x A 14436Enter or leave the TUI mode. When the TUI mode is left, 14437the curses window management is left and @value{GDBN} operates using 14438its standard mode writing on the terminal directly. When the TUI 14439mode is entered, the control is given back to the curses windows. 14440The screen is then refreshed. 14441 14442@kindex C-x 1 14443@item C-x 1 14444Use a TUI layout with only one window. The layout will 14445either be @samp{source} or @samp{assembly}. When the TUI mode 14446is not active, it will switch to the TUI mode. 14447 14448Think of this key binding as the Emacs @kbd{C-x 1} binding. 14449 14450@kindex C-x 2 14451@item C-x 2 14452Use a TUI layout with at least two windows. When the current 14453layout shows already two windows, a next layout with two windows is used. 14454When a new layout is chosen, one window will always be common to the 14455previous layout and the new one. 14456 14457Think of it as the Emacs @kbd{C-x 2} binding. 14458 14459@kindex C-x o 14460@item C-x o 14461Change the active window. The TUI associates several key bindings 14462(like scrolling and arrow keys) to the active window. This command 14463gives the focus to the next TUI window. 14464 14465Think of it as the Emacs @kbd{C-x o} binding. 14466 14467@kindex C-x s 14468@item C-x s 14469Use the TUI @emph{SingleKey} keymap that binds single key to gdb commands 14470(@pxref{TUI Single Key Mode}). 14471 14472@end table 14473 14474The following key bindings are handled only by the TUI mode: 14475 14476@table @key 14477@kindex PgUp 14478@item PgUp 14479Scroll the active window one page up. 14480 14481@kindex PgDn 14482@item PgDn 14483Scroll the active window one page down. 14484 14485@kindex Up 14486@item Up 14487Scroll the active window one line up. 14488 14489@kindex Down 14490@item Down 14491Scroll the active window one line down. 14492 14493@kindex Left 14494@item Left 14495Scroll the active window one column left. 14496 14497@kindex Right 14498@item Right 14499Scroll the active window one column right. 14500 14501@kindex C-L 14502@item C-L 14503Refresh the screen. 14504 14505@end table 14506 14507In the TUI mode, the arrow keys are used by the active window 14508for scrolling. This means they are available for readline when the 14509active window is the command window. When the command window 14510does not have the focus, it is necessary to use other readline 14511key bindings such as @key{C-p}, @key{C-n}, @key{C-b} and @key{C-f}. 14512 14513@node TUI Single Key Mode 14514@section TUI Single Key Mode 14515@cindex TUI single key mode 14516 14517The TUI provides a @emph{SingleKey} mode in which it installs a particular 14518key binding in the readline keymaps to connect single keys to 14519some gdb commands. 14520 14521@table @kbd 14522@kindex c @r{(SingleKey TUI key)} 14523@item c 14524continue 14525 14526@kindex d @r{(SingleKey TUI key)} 14527@item d 14528down 14529 14530@kindex f @r{(SingleKey TUI key)} 14531@item f 14532finish 14533 14534@kindex n @r{(SingleKey TUI key)} 14535@item n 14536next 14537 14538@kindex q @r{(SingleKey TUI key)} 14539@item q 14540exit the @emph{SingleKey} mode. 14541 14542@kindex r @r{(SingleKey TUI key)} 14543@item r 14544run 14545 14546@kindex s @r{(SingleKey TUI key)} 14547@item s 14548step 14549 14550@kindex u @r{(SingleKey TUI key)} 14551@item u 14552up 14553 14554@kindex v @r{(SingleKey TUI key)} 14555@item v 14556info locals 14557 14558@kindex w @r{(SingleKey TUI key)} 14559@item w 14560where 14561 14562@end table 14563 14564Other keys temporarily switch to the @value{GDBN} command prompt. 14565The key that was pressed is inserted in the editing buffer so that 14566it is possible to type most @value{GDBN} commands without interaction 14567with the TUI @emph{SingleKey} mode. Once the command is entered the TUI 14568@emph{SingleKey} mode is restored. The only way to permanently leave 14569this mode is by hitting @key{q} or @samp{@key{C-x} @key{s}}. 14570 14571 14572@node TUI Commands 14573@section TUI specific commands 14574@cindex TUI commands 14575 14576The TUI has specific commands to control the text windows. 14577These commands are always available, that is they do not depend on 14578the current terminal mode in which @value{GDBN} runs. When @value{GDBN} 14579is in the standard mode, using these commands will automatically switch 14580in the TUI mode. 14581 14582@table @code 14583@item info win 14584@kindex info win 14585List and give the size of all displayed windows. 14586 14587@item layout next 14588@kindex layout 14589Display the next layout. 14590 14591@item layout prev 14592Display the previous layout. 14593 14594@item layout src 14595Display the source window only. 14596 14597@item layout asm 14598Display the assembly window only. 14599 14600@item layout split 14601Display the source and assembly window. 14602 14603@item layout regs 14604Display the register window together with the source or assembly window. 14605 14606@item focus next | prev | src | asm | regs | split 14607@kindex focus 14608Set the focus to the named window. 14609This command allows to change the active window so that scrolling keys 14610can be affected to another window. 14611 14612@item refresh 14613@kindex refresh 14614Refresh the screen. This is similar to using @key{C-L} key. 14615 14616@item tui reg float 14617@kindex tui reg 14618Show the floating point registers in the register window. 14619 14620@item tui reg general 14621Show the general registers in the register window. 14622 14623@item tui reg next 14624Show the next register group. The list of register groups as well as 14625their order is target specific. The predefined register groups are the 14626following: @code{general}, @code{float}, @code{system}, @code{vector}, 14627@code{all}, @code{save}, @code{restore}. 14628 14629@item tui reg system 14630Show the system registers in the register window. 14631 14632@item update 14633@kindex update 14634Update the source window and the current execution point. 14635 14636@item winheight @var{name} +@var{count} 14637@itemx winheight @var{name} -@var{count} 14638@kindex winheight 14639Change the height of the window @var{name} by @var{count} 14640lines. Positive counts increase the height, while negative counts 14641decrease it. 14642 14643@end table 14644 14645@node TUI Configuration 14646@section TUI configuration variables 14647@cindex TUI configuration variables 14648 14649The TUI has several configuration variables that control the 14650appearance of windows on the terminal. 14651 14652@table @code 14653@item set tui border-kind @var{kind} 14654@kindex set tui border-kind 14655Select the border appearance for the source, assembly and register windows. 14656The possible values are the following: 14657@table @code 14658@item space 14659Use a space character to draw the border. 14660 14661@item ascii 14662Use ascii characters + - and | to draw the border. 14663 14664@item acs 14665Use the Alternate Character Set to draw the border. The border is 14666drawn using character line graphics if the terminal supports them. 14667 14668@end table 14669 14670@item set tui active-border-mode @var{mode} 14671@kindex set tui active-border-mode 14672Select the attributes to display the border of the active window. 14673The possible values are @code{normal}, @code{standout}, @code{reverse}, 14674@code{half}, @code{half-standout}, @code{bold} and @code{bold-standout}. 14675 14676@item set tui border-mode @var{mode} 14677@kindex set tui border-mode 14678Select the attributes to display the border of other windows. 14679The @var{mode} can be one of the following: 14680@table @code 14681@item normal 14682Use normal attributes to display the border. 14683 14684@item standout 14685Use standout mode. 14686 14687@item reverse 14688Use reverse video mode. 14689 14690@item half 14691Use half bright mode. 14692 14693@item half-standout 14694Use half bright and standout mode. 14695 14696@item bold 14697Use extra bright or bold mode. 14698 14699@item bold-standout 14700Use extra bright or bold and standout mode. 14701 14702@end table 14703 14704@end table 14705 14706@node Emacs 14707@chapter Using @value{GDBN} under @sc{gnu} Emacs 14708 14709@cindex Emacs 14710@cindex @sc{gnu} Emacs 14711A special interface allows you to use @sc{gnu} Emacs to view (and 14712edit) the source files for the program you are debugging with 14713@value{GDBN}. 14714 14715To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the 14716executable file you want to debug as an argument. This command starts 14717@value{GDBN} as a subprocess of Emacs, with input and output through a newly 14718created Emacs buffer. 14719@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.) 14720 14721Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two 14722things: 14723 14724@itemize @bullet 14725@item 14726All ``terminal'' input and output goes through the Emacs buffer. 14727@end itemize 14728 14729This applies both to @value{GDBN} commands and their output, and to the input 14730and output done by the program you are debugging. 14731 14732This is useful because it means that you can copy the text of previous 14733commands and input them again; you can even use parts of the output 14734in this way. 14735 14736All the facilities of Emacs' Shell mode are available for interacting 14737with your program. In particular, you can send signals the usual 14738way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a 14739stop. 14740 14741@itemize @bullet 14742@item 14743@value{GDBN} displays source code through Emacs. 14744@end itemize 14745 14746Each time @value{GDBN} displays a stack frame, Emacs automatically finds the 14747source file for that frame and puts an arrow (@samp{=>}) at the 14748left margin of the current line. Emacs uses a separate buffer for 14749source display, and splits the screen to show both your @value{GDBN} session 14750and the source. 14751 14752Explicit @value{GDBN} @code{list} or search commands still produce output as 14753usual, but you probably have no reason to use them from Emacs. 14754 14755If you specify an absolute file name when prompted for the @kbd{M-x 14756gdb} argument, then Emacs sets your current working directory to where 14757your program resides. If you only specify the file name, then Emacs 14758sets your current working directory to to the directory associated 14759with the previous buffer. In this case, @value{GDBN} may find your 14760program by searching your environment's @code{PATH} variable, but on 14761some operating systems it might not find the source. So, although the 14762@value{GDBN} input and output session proceeds normally, the auxiliary 14763buffer does not display the current source and line of execution. 14764 14765The initial working directory of @value{GDBN} is printed on the top 14766line of the @value{GDBN} I/O buffer and this serves as a default for 14767the commands that specify files for @value{GDBN} to operate 14768on. @xref{Files, ,Commands to specify files}. 14769 14770By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you 14771need to call @value{GDBN} by a different name (for example, if you 14772keep several configurations around, with different names) you can 14773customize the Emacs variable @code{gud-gdb-command-name} to run the 14774one you want. 14775 14776In the @value{GDBN} I/O buffer, you can use these special Emacs commands in 14777addition to the standard Shell mode commands: 14778 14779@table @kbd 14780@item C-h m 14781Describe the features of Emacs' @value{GDBN} Mode. 14782 14783@item C-c C-s 14784Execute to another source line, like the @value{GDBN} @code{step} command; also 14785update the display window to show the current file and location. 14786 14787@item C-c C-n 14788Execute to next source line in this function, skipping all function 14789calls, like the @value{GDBN} @code{next} command. Then update the display window 14790to show the current file and location. 14791 14792@item C-c C-i 14793Execute one instruction, like the @value{GDBN} @code{stepi} command; update 14794display window accordingly. 14795 14796@item C-c C-f 14797Execute until exit from the selected stack frame, like the @value{GDBN} 14798@code{finish} command. 14799 14800@item C-c C-r 14801Continue execution of your program, like the @value{GDBN} @code{continue} 14802command. 14803 14804@item C-c < 14805Go up the number of frames indicated by the numeric argument 14806(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}), 14807like the @value{GDBN} @code{up} command. 14808 14809@item C-c > 14810Go down the number of frames indicated by the numeric argument, like the 14811@value{GDBN} @code{down} command. 14812@end table 14813 14814In any source file, the Emacs command @kbd{C-x SPC} (@code{gud-break}) 14815tells @value{GDBN} to set a breakpoint on the source line point is on. 14816 14817If you type @kbd{M-x speedbar}, then Emacs displays a separate frame which 14818shows a backtrace when the @value{GDBN} I/O buffer is current. Move 14819point to any frame in the stack and type @key{RET} to make it become the 14820current frame and display the associated source in the source buffer. 14821Alternatively, click @kbd{Mouse-2} to make the selected frame become the 14822current one. 14823 14824If you accidentally delete the source-display buffer, an easy way to get 14825it back is to type the command @code{f} in the @value{GDBN} buffer, to 14826request a frame display; when you run under Emacs, this recreates 14827the source buffer if necessary to show you the context of the current 14828frame. 14829 14830The source files displayed in Emacs are in ordinary Emacs buffers 14831which are visiting the source files in the usual way. You can edit 14832the files with these buffers if you wish; but keep in mind that @value{GDBN} 14833communicates with Emacs in terms of line numbers. If you add or 14834delete lines from the text, the line numbers that @value{GDBN} knows cease 14835to correspond properly with the code. 14836 14837The description given here is for GNU Emacs version 21.3 and a more 14838detailed description of its interaction with @value{GDBN} is given in 14839the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} Emacs Manual}). 14840 14841@c The following dropped because Epoch is nonstandard. Reactivate 14842@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990 14843@ignore 14844@kindex Emacs Epoch environment 14845@kindex Epoch 14846@kindex inspect 14847 14848Version 18 of @sc{gnu} Emacs has a built-in window system 14849called the @code{epoch} 14850environment. Users of this environment can use a new command, 14851@code{inspect} which performs identically to @code{print} except that 14852each value is printed in its own window. 14853@end ignore 14854 14855 14856@node GDB/MI 14857@chapter The @sc{gdb/mi} Interface 14858 14859@unnumberedsec Function and Purpose 14860 14861@cindex @sc{gdb/mi}, its purpose 14862@sc{gdb/mi} is a line based machine oriented text interface to @value{GDBN}. It is 14863specifically intended to support the development of systems which use 14864the debugger as just one small component of a larger system. 14865 14866This chapter is a specification of the @sc{gdb/mi} interface. It is written 14867in the form of a reference manual. 14868 14869Note that @sc{gdb/mi} is still under construction, so some of the 14870features described below are incomplete and subject to change. 14871 14872@unnumberedsec Notation and Terminology 14873 14874@cindex notational conventions, for @sc{gdb/mi} 14875This chapter uses the following notation: 14876 14877@itemize @bullet 14878@item 14879@code{|} separates two alternatives. 14880 14881@item 14882@code{[ @var{something} ]} indicates that @var{something} is optional: 14883it may or may not be given. 14884 14885@item 14886@code{( @var{group} )*} means that @var{group} inside the parentheses 14887may repeat zero or more times. 14888 14889@item 14890@code{( @var{group} )+} means that @var{group} inside the parentheses 14891may repeat one or more times. 14892 14893@item 14894@code{"@var{string}"} means a literal @var{string}. 14895@end itemize 14896 14897@ignore 14898@heading Dependencies 14899@end ignore 14900 14901@heading Acknowledgments 14902 14903In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and 14904Elena Zannoni. 14905 14906@menu 14907* GDB/MI Command Syntax:: 14908* GDB/MI Compatibility with CLI:: 14909* GDB/MI Output Records:: 14910* GDB/MI Command Description Format:: 14911* GDB/MI Breakpoint Table Commands:: 14912* GDB/MI Data Manipulation:: 14913* GDB/MI Program Control:: 14914* GDB/MI Miscellaneous Commands:: 14915@ignore 14916* GDB/MI Kod Commands:: 14917* GDB/MI Memory Overlay Commands:: 14918* GDB/MI Signal Handling Commands:: 14919@end ignore 14920* GDB/MI Stack Manipulation:: 14921* GDB/MI Symbol Query:: 14922* GDB/MI Target Manipulation:: 14923* GDB/MI Thread Commands:: 14924* GDB/MI Tracepoint Commands:: 14925* GDB/MI Variable Objects:: 14926@end menu 14927 14928@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 14929@node GDB/MI Command Syntax 14930@section @sc{gdb/mi} Command Syntax 14931 14932@menu 14933* GDB/MI Input Syntax:: 14934* GDB/MI Output Syntax:: 14935* GDB/MI Simple Examples:: 14936@end menu 14937 14938@node GDB/MI Input Syntax 14939@subsection @sc{gdb/mi} Input Syntax 14940 14941@cindex input syntax for @sc{gdb/mi} 14942@cindex @sc{gdb/mi}, input syntax 14943@table @code 14944@item @var{command} @expansion{} 14945@code{@var{cli-command} | @var{mi-command}} 14946 14947@item @var{cli-command} @expansion{} 14948@code{[ @var{token} ] @var{cli-command} @var{nl}}, where 14949@var{cli-command} is any existing @value{GDBN} CLI command. 14950 14951@item @var{mi-command} @expansion{} 14952@code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )* 14953@code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}} 14954 14955@item @var{token} @expansion{} 14956"any sequence of digits" 14957 14958@item @var{option} @expansion{} 14959@code{"-" @var{parameter} [ " " @var{parameter} ]} 14960 14961@item @var{parameter} @expansion{} 14962@code{@var{non-blank-sequence} | @var{c-string}} 14963 14964@item @var{operation} @expansion{} 14965@emph{any of the operations described in this chapter} 14966 14967@item @var{non-blank-sequence} @expansion{} 14968@emph{anything, provided it doesn't contain special characters such as 14969"-", @var{nl}, """ and of course " "} 14970 14971@item @var{c-string} @expansion{} 14972@code{""" @var{seven-bit-iso-c-string-content} """} 14973 14974@item @var{nl} @expansion{} 14975@code{CR | CR-LF} 14976@end table 14977 14978@noindent 14979Notes: 14980 14981@itemize @bullet 14982@item 14983The CLI commands are still handled by the @sc{mi} interpreter; their 14984output is described below. 14985 14986@item 14987The @code{@var{token}}, when present, is passed back when the command 14988finishes. 14989 14990@item 14991Some @sc{mi} commands accept optional arguments as part of the parameter 14992list. Each option is identified by a leading @samp{-} (dash) and may be 14993followed by an optional argument parameter. Options occur first in the 14994parameter list and can be delimited from normal parameters using 14995@samp{--} (this is useful when some parameters begin with a dash). 14996@end itemize 14997 14998Pragmatics: 14999 15000@itemize @bullet 15001@item 15002We want easy access to the existing CLI syntax (for debugging). 15003 15004@item 15005We want it to be easy to spot a @sc{mi} operation. 15006@end itemize 15007 15008@node GDB/MI Output Syntax 15009@subsection @sc{gdb/mi} Output Syntax 15010 15011@cindex output syntax of @sc{gdb/mi} 15012@cindex @sc{gdb/mi}, output syntax 15013The output from @sc{gdb/mi} consists of zero or more out-of-band records 15014followed, optionally, by a single result record. This result record 15015is for the most recent command. The sequence of output records is 15016terminated by @samp{(@value{GDBP})}. 15017 15018If an input command was prefixed with a @code{@var{token}} then the 15019corresponding output for that command will also be prefixed by that same 15020@var{token}. 15021 15022@table @code 15023@item @var{output} @expansion{} 15024@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(@value{GDBP})" @var{nl}} 15025 15026@item @var{result-record} @expansion{} 15027@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}} 15028 15029@item @var{out-of-band-record} @expansion{} 15030@code{@var{async-record} | @var{stream-record}} 15031 15032@item @var{async-record} @expansion{} 15033@code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}} 15034 15035@item @var{exec-async-output} @expansion{} 15036@code{[ @var{token} ] "*" @var{async-output}} 15037 15038@item @var{status-async-output} @expansion{} 15039@code{[ @var{token} ] "+" @var{async-output}} 15040 15041@item @var{notify-async-output} @expansion{} 15042@code{[ @var{token} ] "=" @var{async-output}} 15043 15044@item @var{async-output} @expansion{} 15045@code{@var{async-class} ( "," @var{result} )* @var{nl}} 15046 15047@item @var{result-class} @expansion{} 15048@code{"done" | "running" | "connected" | "error" | "exit"} 15049 15050@item @var{async-class} @expansion{} 15051@code{"stopped" | @var{others}} (where @var{others} will be added 15052depending on the needs---this is still in development). 15053 15054@item @var{result} @expansion{} 15055@code{ @var{variable} "=" @var{value}} 15056 15057@item @var{variable} @expansion{} 15058@code{ @var{string} } 15059 15060@item @var{value} @expansion{} 15061@code{ @var{const} | @var{tuple} | @var{list} } 15062 15063@item @var{const} @expansion{} 15064@code{@var{c-string}} 15065 15066@item @var{tuple} @expansion{} 15067@code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" } 15068 15069@item @var{list} @expansion{} 15070@code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "[" 15071@var{result} ( "," @var{result} )* "]" } 15072 15073@item @var{stream-record} @expansion{} 15074@code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}} 15075 15076@item @var{console-stream-output} @expansion{} 15077@code{"~" @var{c-string}} 15078 15079@item @var{target-stream-output} @expansion{} 15080@code{"@@" @var{c-string}} 15081 15082@item @var{log-stream-output} @expansion{} 15083@code{"&" @var{c-string}} 15084 15085@item @var{nl} @expansion{} 15086@code{CR | CR-LF} 15087 15088@item @var{token} @expansion{} 15089@emph{any sequence of digits}. 15090@end table 15091 15092@noindent 15093Notes: 15094 15095@itemize @bullet 15096@item 15097All output sequences end in a single line containing a period. 15098 15099@item 15100The @code{@var{token}} is from the corresponding request. If an execution 15101command is interrupted by the @samp{-exec-interrupt} command, the 15102@var{token} associated with the @samp{*stopped} message is the one of the 15103original execution command, not the one of the interrupt command. 15104 15105@item 15106@cindex status output in @sc{gdb/mi} 15107@var{status-async-output} contains on-going status information about the 15108progress of a slow operation. It can be discarded. All status output is 15109prefixed by @samp{+}. 15110 15111@item 15112@cindex async output in @sc{gdb/mi} 15113@var{exec-async-output} contains asynchronous state change on the target 15114(stopped, started, disappeared). All async output is prefixed by 15115@samp{*}. 15116 15117@item 15118@cindex notify output in @sc{gdb/mi} 15119@var{notify-async-output} contains supplementary information that the 15120client should handle (e.g., a new breakpoint information). All notify 15121output is prefixed by @samp{=}. 15122 15123@item 15124@cindex console output in @sc{gdb/mi} 15125@var{console-stream-output} is output that should be displayed as is in the 15126console. It is the textual response to a CLI command. All the console 15127output is prefixed by @samp{~}. 15128 15129@item 15130@cindex target output in @sc{gdb/mi} 15131@var{target-stream-output} is the output produced by the target program. 15132All the target output is prefixed by @samp{@@}. 15133 15134@item 15135@cindex log output in @sc{gdb/mi} 15136@var{log-stream-output} is output text coming from @value{GDBN}'s internals, for 15137instance messages that should be displayed as part of an error log. All 15138the log output is prefixed by @samp{&}. 15139 15140@item 15141@cindex list output in @sc{gdb/mi} 15142New @sc{gdb/mi} commands should only output @var{lists} containing 15143@var{values}. 15144 15145 15146@end itemize 15147 15148@xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more 15149details about the various output records. 15150 15151@node GDB/MI Simple Examples 15152@subsection Simple Examples of @sc{gdb/mi} Interaction 15153@cindex @sc{gdb/mi}, simple examples 15154 15155This subsection presents several simple examples of interaction using 15156the @sc{gdb/mi} interface. In these examples, @samp{->} means that the 15157following line is passed to @sc{gdb/mi} as input, while @samp{<-} means 15158the output received from @sc{gdb/mi}. 15159 15160@subsubheading Target Stop 15161@c Ummm... There is no "-stop" command. This assumes async, no? 15162Here's an example of stopping the inferior process: 15163 15164@smallexample 15165-> -stop 15166<- (@value{GDBP}) 15167@end smallexample 15168 15169@noindent 15170and later: 15171 15172@smallexample 15173<- *stop,reason="stop",address="0x123",source="a.c:123" 15174<- (@value{GDBP}) 15175@end smallexample 15176 15177@subsubheading Simple CLI Command 15178 15179Here's an example of a simple CLI command being passed through 15180@sc{gdb/mi} and on to the CLI. 15181 15182@smallexample 15183-> print 1+2 15184<- &"print 1+2\n" 15185<- ~"$1 = 3\n" 15186<- ^done 15187<- (@value{GDBP}) 15188@end smallexample 15189 15190@subsubheading Command With Side Effects 15191 15192@smallexample 15193-> -symbol-file xyz.exe 15194<- *breakpoint,nr="3",address="0x123",source="a.c:123" 15195<- (@value{GDBP}) 15196@end smallexample 15197 15198@subsubheading A Bad Command 15199 15200Here's what happens if you pass a non-existent command: 15201 15202@smallexample 15203-> -rubbish 15204<- ^error,msg="Undefined MI command: rubbish" 15205<- (@value{GDBP}) 15206@end smallexample 15207 15208@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 15209@node GDB/MI Compatibility with CLI 15210@section @sc{gdb/mi} Compatibility with CLI 15211 15212@cindex compatibility, @sc{gdb/mi} and CLI 15213@cindex @sc{gdb/mi}, compatibility with CLI 15214To help users familiar with @value{GDBN}'s existing CLI interface, @sc{gdb/mi} 15215accepts existing CLI commands. As specified by the syntax, such 15216commands can be directly entered into the @sc{gdb/mi} interface and @value{GDBN} will 15217respond. 15218 15219This mechanism is provided as an aid to developers of @sc{gdb/mi} 15220clients and not as a reliable interface into the CLI. Since the command 15221is being interpreteted in an environment that assumes @sc{gdb/mi} 15222behaviour, the exact output of such commands is likely to end up being 15223an un-supported hybrid of @sc{gdb/mi} and CLI output. 15224 15225@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 15226@node GDB/MI Output Records 15227@section @sc{gdb/mi} Output Records 15228 15229@menu 15230* GDB/MI Result Records:: 15231* GDB/MI Stream Records:: 15232* GDB/MI Out-of-band Records:: 15233@end menu 15234 15235@node GDB/MI Result Records 15236@subsection @sc{gdb/mi} Result Records 15237 15238@cindex result records in @sc{gdb/mi} 15239@cindex @sc{gdb/mi}, result records 15240In addition to a number of out-of-band notifications, the response to a 15241@sc{gdb/mi} command includes one of the following result indications: 15242 15243@table @code 15244@findex ^done 15245@item "^done" [ "," @var{results} ] 15246The synchronous operation was successful, @code{@var{results}} are the return 15247values. 15248 15249@item "^running" 15250@findex ^running 15251@c Is this one correct? Should it be an out-of-band notification? 15252The asynchronous operation was successfully started. The target is 15253running. 15254 15255@item "^error" "," @var{c-string} 15256@findex ^error 15257The operation failed. The @code{@var{c-string}} contains the corresponding 15258error message. 15259@end table 15260 15261@node GDB/MI Stream Records 15262@subsection @sc{gdb/mi} Stream Records 15263 15264@cindex @sc{gdb/mi}, stream records 15265@cindex stream records in @sc{gdb/mi} 15266@value{GDBN} internally maintains a number of output streams: the console, the 15267target, and the log. The output intended for each of these streams is 15268funneled through the @sc{gdb/mi} interface using @dfn{stream records}. 15269 15270Each stream record begins with a unique @dfn{prefix character} which 15271identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output 15272Syntax}). In addition to the prefix, each stream record contains a 15273@code{@var{string-output}}. This is either raw text (with an implicit new 15274line) or a quoted C string (which does not contain an implicit newline). 15275 15276@table @code 15277@item "~" @var{string-output} 15278The console output stream contains text that should be displayed in the 15279CLI console window. It contains the textual responses to CLI commands. 15280 15281@item "@@" @var{string-output} 15282The target output stream contains any textual output from the running 15283target. 15284 15285@item "&" @var{string-output} 15286The log stream contains debugging messages being produced by @value{GDBN}'s 15287internals. 15288@end table 15289 15290@node GDB/MI Out-of-band Records 15291@subsection @sc{gdb/mi} Out-of-band Records 15292 15293@cindex out-of-band records in @sc{gdb/mi} 15294@cindex @sc{gdb/mi}, out-of-band records 15295@dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of 15296additional changes that have occurred. Those changes can either be a 15297consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of 15298target activity (e.g., target stopped). 15299 15300The following is a preliminary list of possible out-of-band records. 15301 15302@table @code 15303@item "*" "stop" 15304@end table 15305 15306 15307@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 15308@node GDB/MI Command Description Format 15309@section @sc{gdb/mi} Command Description Format 15310 15311The remaining sections describe blocks of commands. Each block of 15312commands is laid out in a fashion similar to this section. 15313 15314Note the the line breaks shown in the examples are here only for 15315readability. They don't appear in the real output. 15316Also note that the commands with a non-available example (N.A.@:) are 15317not yet implemented. 15318 15319@subheading Motivation 15320 15321The motivation for this collection of commands. 15322 15323@subheading Introduction 15324 15325A brief introduction to this collection of commands as a whole. 15326 15327@subheading Commands 15328 15329For each command in the block, the following is described: 15330 15331@subsubheading Synopsis 15332 15333@smallexample 15334 -command @var{args}@dots{} 15335@end smallexample 15336 15337@subsubheading @value{GDBN} Command 15338 15339The corresponding @value{GDBN} CLI command. 15340 15341@subsubheading Result 15342 15343@subsubheading Out-of-band 15344 15345@subsubheading Notes 15346 15347@subsubheading Example 15348 15349 15350@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 15351@node GDB/MI Breakpoint Table Commands 15352@section @sc{gdb/mi} Breakpoint table commands 15353 15354@cindex breakpoint commands for @sc{gdb/mi} 15355@cindex @sc{gdb/mi}, breakpoint commands 15356This section documents @sc{gdb/mi} commands for manipulating 15357breakpoints. 15358 15359@subheading The @code{-break-after} Command 15360@findex -break-after 15361 15362@subsubheading Synopsis 15363 15364@smallexample 15365 -break-after @var{number} @var{count} 15366@end smallexample 15367 15368The breakpoint number @var{number} is not in effect until it has been 15369hit @var{count} times. To see how this is reflected in the output of 15370the @samp{-break-list} command, see the description of the 15371@samp{-break-list} command below. 15372 15373@subsubheading @value{GDBN} Command 15374 15375The corresponding @value{GDBN} command is @samp{ignore}. 15376 15377@subsubheading Example 15378 15379@smallexample 15380(@value{GDBP}) 15381-break-insert main 15382^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@} 15383(@value{GDBP}) 15384-break-after 1 3 15385~ 15386^done 15387(@value{GDBP}) 15388-break-list 15389^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 15390hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 15391@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 15392@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 15393@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 15394@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 15395@{width="40",alignment="2",col_name="what",colhdr="What"@}], 15396body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 15397addr="0x000100d0",func="main",file="hello.c",line="5",times="0", 15398ignore="3"@}]@} 15399(@value{GDBP}) 15400@end smallexample 15401 15402@ignore 15403@subheading The @code{-break-catch} Command 15404@findex -break-catch 15405 15406@subheading The @code{-break-commands} Command 15407@findex -break-commands 15408@end ignore 15409 15410 15411@subheading The @code{-break-condition} Command 15412@findex -break-condition 15413 15414@subsubheading Synopsis 15415 15416@smallexample 15417 -break-condition @var{number} @var{expr} 15418@end smallexample 15419 15420Breakpoint @var{number} will stop the program only if the condition in 15421@var{expr} is true. The condition becomes part of the 15422@samp{-break-list} output (see the description of the @samp{-break-list} 15423command below). 15424 15425@subsubheading @value{GDBN} Command 15426 15427The corresponding @value{GDBN} command is @samp{condition}. 15428 15429@subsubheading Example 15430 15431@smallexample 15432(@value{GDBP}) 15433-break-condition 1 1 15434^done 15435(@value{GDBP}) 15436-break-list 15437^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 15438hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 15439@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 15440@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 15441@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 15442@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 15443@{width="40",alignment="2",col_name="what",colhdr="What"@}], 15444body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 15445addr="0x000100d0",func="main",file="hello.c",line="5",cond="1", 15446times="0",ignore="3"@}]@} 15447(@value{GDBP}) 15448@end smallexample 15449 15450@subheading The @code{-break-delete} Command 15451@findex -break-delete 15452 15453@subsubheading Synopsis 15454 15455@smallexample 15456 -break-delete ( @var{breakpoint} )+ 15457@end smallexample 15458 15459Delete the breakpoint(s) whose number(s) are specified in the argument 15460list. This is obviously reflected in the breakpoint list. 15461 15462@subsubheading @value{GDBN} command 15463 15464The corresponding @value{GDBN} command is @samp{delete}. 15465 15466@subsubheading Example 15467 15468@smallexample 15469(@value{GDBP}) 15470-break-delete 1 15471^done 15472(@value{GDBP}) 15473-break-list 15474^done,BreakpointTable=@{nr_rows="0",nr_cols="6", 15475hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 15476@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 15477@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 15478@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 15479@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 15480@{width="40",alignment="2",col_name="what",colhdr="What"@}], 15481body=[]@} 15482(@value{GDBP}) 15483@end smallexample 15484 15485@subheading The @code{-break-disable} Command 15486@findex -break-disable 15487 15488@subsubheading Synopsis 15489 15490@smallexample 15491 -break-disable ( @var{breakpoint} )+ 15492@end smallexample 15493 15494Disable the named @var{breakpoint}(s). The field @samp{enabled} in the 15495break list is now set to @samp{n} for the named @var{breakpoint}(s). 15496 15497@subsubheading @value{GDBN} Command 15498 15499The corresponding @value{GDBN} command is @samp{disable}. 15500 15501@subsubheading Example 15502 15503@smallexample 15504(@value{GDBP}) 15505-break-disable 2 15506^done 15507(@value{GDBP}) 15508-break-list 15509^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 15510hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 15511@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 15512@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 15513@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 15514@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 15515@{width="40",alignment="2",col_name="what",colhdr="What"@}], 15516body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n", 15517addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@} 15518(@value{GDBP}) 15519@end smallexample 15520 15521@subheading The @code{-break-enable} Command 15522@findex -break-enable 15523 15524@subsubheading Synopsis 15525 15526@smallexample 15527 -break-enable ( @var{breakpoint} )+ 15528@end smallexample 15529 15530Enable (previously disabled) @var{breakpoint}(s). 15531 15532@subsubheading @value{GDBN} Command 15533 15534The corresponding @value{GDBN} command is @samp{enable}. 15535 15536@subsubheading Example 15537 15538@smallexample 15539(@value{GDBP}) 15540-break-enable 2 15541^done 15542(@value{GDBP}) 15543-break-list 15544^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 15545hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 15546@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 15547@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 15548@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 15549@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 15550@{width="40",alignment="2",col_name="what",colhdr="What"@}], 15551body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", 15552addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@} 15553(@value{GDBP}) 15554@end smallexample 15555 15556@subheading The @code{-break-info} Command 15557@findex -break-info 15558 15559@subsubheading Synopsis 15560 15561@smallexample 15562 -break-info @var{breakpoint} 15563@end smallexample 15564 15565@c REDUNDANT??? 15566Get information about a single breakpoint. 15567 15568@subsubheading @value{GDBN} command 15569 15570The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}. 15571 15572@subsubheading Example 15573N.A. 15574 15575@subheading The @code{-break-insert} Command 15576@findex -break-insert 15577 15578@subsubheading Synopsis 15579 15580@smallexample 15581 -break-insert [ -t ] [ -h ] [ -r ] 15582 [ -c @var{condition} ] [ -i @var{ignore-count} ] 15583 [ -p @var{thread} ] [ @var{line} | @var{addr} ] 15584@end smallexample 15585 15586@noindent 15587If specified, @var{line}, can be one of: 15588 15589@itemize @bullet 15590@item function 15591@c @item +offset 15592@c @item -offset 15593@c @item linenum 15594@item filename:linenum 15595@item filename:function 15596@item *address 15597@end itemize 15598 15599The possible optional parameters of this command are: 15600 15601@table @samp 15602@item -t 15603Insert a tempoary breakpoint. 15604@item -h 15605Insert a hardware breakpoint. 15606@item -c @var{condition} 15607Make the breakpoint conditional on @var{condition}. 15608@item -i @var{ignore-count} 15609Initialize the @var{ignore-count}. 15610@item -r 15611Insert a regular breakpoint in all the functions whose names match the 15612given regular expression. Other flags are not applicable to regular 15613expresson. 15614@end table 15615 15616@subsubheading Result 15617 15618The result is in the form: 15619 15620@smallexample 15621 ^done,bkptno="@var{number}",func="@var{funcname}", 15622 file="@var{filename}",line="@var{lineno}" 15623@end smallexample 15624 15625@noindent 15626where @var{number} is the @value{GDBN} number for this breakpoint, @var{funcname} 15627is the name of the function where the breakpoint was inserted, 15628@var{filename} is the name of the source file which contains this 15629function, and @var{lineno} is the source line number within that file. 15630 15631Note: this format is open to change. 15632@c An out-of-band breakpoint instead of part of the result? 15633 15634@subsubheading @value{GDBN} Command 15635 15636The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak}, 15637@samp{hbreak}, @samp{thbreak}, and @samp{rbreak}. 15638 15639@subsubheading Example 15640 15641@smallexample 15642(@value{GDBP}) 15643-break-insert main 15644^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} 15645(@value{GDBP}) 15646-break-insert -t foo 15647^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@} 15648(@value{GDBP}) 15649-break-list 15650^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 15651hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 15652@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 15653@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 15654@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 15655@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 15656@{width="40",alignment="2",col_name="what",colhdr="What"@}], 15657body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 15658addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"@}, 15659bkpt=@{number="2",type="breakpoint",disp="del",enabled="y", 15660addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"@}]@} 15661(@value{GDBP}) 15662-break-insert -r foo.* 15663~int foo(int, int); 15664^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@} 15665(@value{GDBP}) 15666@end smallexample 15667 15668@subheading The @code{-break-list} Command 15669@findex -break-list 15670 15671@subsubheading Synopsis 15672 15673@smallexample 15674 -break-list 15675@end smallexample 15676 15677Displays the list of inserted breakpoints, showing the following fields: 15678 15679@table @samp 15680@item Number 15681number of the breakpoint 15682@item Type 15683type of the breakpoint: @samp{breakpoint} or @samp{watchpoint} 15684@item Disposition 15685should the breakpoint be deleted or disabled when it is hit: @samp{keep} 15686or @samp{nokeep} 15687@item Enabled 15688is the breakpoint enabled or no: @samp{y} or @samp{n} 15689@item Address 15690memory location at which the breakpoint is set 15691@item What 15692logical location of the breakpoint, expressed by function name, file 15693name, line number 15694@item Times 15695number of times the breakpoint has been hit 15696@end table 15697 15698If there are no breakpoints or watchpoints, the @code{BreakpointTable} 15699@code{body} field is an empty list. 15700 15701@subsubheading @value{GDBN} Command 15702 15703The corresponding @value{GDBN} command is @samp{info break}. 15704 15705@subsubheading Example 15706 15707@smallexample 15708(@value{GDBP}) 15709-break-list 15710^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 15711hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 15712@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 15713@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 15714@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 15715@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 15716@{width="40",alignment="2",col_name="what",colhdr="What"@}], 15717body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 15718addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}, 15719bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", 15720addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}]@} 15721(@value{GDBP}) 15722@end smallexample 15723 15724Here's an example of the result when there are no breakpoints: 15725 15726@smallexample 15727(@value{GDBP}) 15728-break-list 15729^done,BreakpointTable=@{nr_rows="0",nr_cols="6", 15730hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 15731@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 15732@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 15733@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 15734@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 15735@{width="40",alignment="2",col_name="what",colhdr="What"@}], 15736body=[]@} 15737(@value{GDBP}) 15738@end smallexample 15739 15740@subheading The @code{-break-watch} Command 15741@findex -break-watch 15742 15743@subsubheading Synopsis 15744 15745@smallexample 15746 -break-watch [ -a | -r ] 15747@end smallexample 15748 15749Create a watchpoint. With the @samp{-a} option it will create an 15750@dfn{access} watchpoint, i.e. a watchpoint that triggers either on a 15751read from or on a write to the memory location. With the @samp{-r} 15752option, the watchpoint created is a @dfn{read} watchpoint, i.e. it will 15753trigger only when the memory location is accessed for reading. Without 15754either of the options, the watchpoint created is a regular watchpoint, 15755i.e. it will trigger when the memory location is accessed for writing. 15756@xref{Set Watchpoints, , Setting watchpoints}. 15757 15758Note that @samp{-break-list} will report a single list of watchpoints and 15759breakpoints inserted. 15760 15761@subsubheading @value{GDBN} Command 15762 15763The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and 15764@samp{rwatch}. 15765 15766@subsubheading Example 15767 15768Setting a watchpoint on a variable in the @code{main} function: 15769 15770@smallexample 15771(@value{GDBP}) 15772-break-watch x 15773^done,wpt=@{number="2",exp="x"@} 15774(@value{GDBP}) 15775-exec-continue 15776^running 15777^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@}, 15778value=@{old="-268439212",new="55"@}, 15779frame=@{func="main",args=[],file="recursive2.c",line="5"@} 15780(@value{GDBP}) 15781@end smallexample 15782 15783Setting a watchpoint on a variable local to a function. @value{GDBN} will stop 15784the program execution twice: first for the variable changing value, then 15785for the watchpoint going out of scope. 15786 15787@smallexample 15788(@value{GDBP}) 15789-break-watch C 15790^done,wpt=@{number="5",exp="C"@} 15791(@value{GDBP}) 15792-exec-continue 15793^running 15794^done,reason="watchpoint-trigger", 15795wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@}, 15796frame=@{func="callee4",args=[], 15797file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@} 15798(@value{GDBP}) 15799-exec-continue 15800^running 15801^done,reason="watchpoint-scope",wpnum="5", 15802frame=@{func="callee3",args=[@{name="strarg", 15803value="0x11940 \"A string argument.\""@}], 15804file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} 15805(@value{GDBP}) 15806@end smallexample 15807 15808Listing breakpoints and watchpoints, at different points in the program 15809execution. Note that once the watchpoint goes out of scope, it is 15810deleted. 15811 15812@smallexample 15813(@value{GDBP}) 15814-break-watch C 15815^done,wpt=@{number="2",exp="C"@} 15816(@value{GDBP}) 15817-break-list 15818^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 15819hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 15820@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 15821@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 15822@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 15823@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 15824@{width="40",alignment="2",col_name="what",colhdr="What"@}], 15825body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 15826addr="0x00010734",func="callee4", 15827file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}, 15828bkpt=@{number="2",type="watchpoint",disp="keep", 15829enabled="y",addr="",what="C",times="0"@}]@} 15830(@value{GDBP}) 15831-exec-continue 15832^running 15833^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@}, 15834value=@{old="-276895068",new="3"@}, 15835frame=@{func="callee4",args=[], 15836file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@} 15837(@value{GDBP}) 15838-break-list 15839^done,BreakpointTable=@{nr_rows="2",nr_cols="6", 15840hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 15841@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 15842@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 15843@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 15844@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 15845@{width="40",alignment="2",col_name="what",colhdr="What"@}], 15846body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 15847addr="0x00010734",func="callee4", 15848file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}, 15849bkpt=@{number="2",type="watchpoint",disp="keep", 15850enabled="y",addr="",what="C",times="-5"@}]@} 15851(@value{GDBP}) 15852-exec-continue 15853^running 15854^done,reason="watchpoint-scope",wpnum="2", 15855frame=@{func="callee3",args=[@{name="strarg", 15856value="0x11940 \"A string argument.\""@}], 15857file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} 15858(@value{GDBP}) 15859-break-list 15860^done,BreakpointTable=@{nr_rows="1",nr_cols="6", 15861hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, 15862@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, 15863@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, 15864@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, 15865@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, 15866@{width="40",alignment="2",col_name="what",colhdr="What"@}], 15867body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", 15868addr="0x00010734",func="callee4", 15869file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}]@} 15870(@value{GDBP}) 15871@end smallexample 15872 15873@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 15874@node GDB/MI Data Manipulation 15875@section @sc{gdb/mi} Data Manipulation 15876 15877@cindex data manipulation, in @sc{gdb/mi} 15878@cindex @sc{gdb/mi}, data manipulation 15879This section describes the @sc{gdb/mi} commands that manipulate data: 15880examine memory and registers, evaluate expressions, etc. 15881 15882@c REMOVED FROM THE INTERFACE. 15883@c @subheading -data-assign 15884@c Change the value of a program variable. Plenty of side effects. 15885@c @subsubheading GDB command 15886@c set variable 15887@c @subsubheading Example 15888@c N.A. 15889 15890@subheading The @code{-data-disassemble} Command 15891@findex -data-disassemble 15892 15893@subsubheading Synopsis 15894 15895@smallexample 15896 -data-disassemble 15897 [ -s @var{start-addr} -e @var{end-addr} ] 15898 | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ] 15899 -- @var{mode} 15900@end smallexample 15901 15902@noindent 15903Where: 15904 15905@table @samp 15906@item @var{start-addr} 15907is the beginning address (or @code{$pc}) 15908@item @var{end-addr} 15909is the end address 15910@item @var{filename} 15911is the name of the file to disassemble 15912@item @var{linenum} 15913is the line number to disassemble around 15914@item @var{lines} 15915is the the number of disassembly lines to be produced. If it is -1, 15916the whole function will be disassembled, in case no @var{end-addr} is 15917specified. If @var{end-addr} is specified as a non-zero value, and 15918@var{lines} is lower than the number of disassembly lines between 15919@var{start-addr} and @var{end-addr}, only @var{lines} lines are 15920displayed; if @var{lines} is higher than the number of lines between 15921@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr} 15922are displayed. 15923@item @var{mode} 15924is either 0 (meaning only disassembly) or 1 (meaning mixed source and 15925disassembly). 15926@end table 15927 15928@subsubheading Result 15929 15930The output for each instruction is composed of four fields: 15931 15932@itemize @bullet 15933@item Address 15934@item Func-name 15935@item Offset 15936@item Instruction 15937@end itemize 15938 15939Note that whatever included in the instruction field, is not manipulated 15940directely by @sc{gdb/mi}, i.e. it is not possible to adjust its format. 15941 15942@subsubheading @value{GDBN} Command 15943 15944There's no direct mapping from this command to the CLI. 15945 15946@subsubheading Example 15947 15948Disassemble from the current value of @code{$pc} to @code{$pc + 20}: 15949 15950@smallexample 15951(@value{GDBP}) 15952-data-disassemble -s $pc -e "$pc + 20" -- 0 15953^done, 15954asm_insns=[ 15955@{address="0x000107c0",func-name="main",offset="4", 15956inst="mov 2, %o0"@}, 15957@{address="0x000107c4",func-name="main",offset="8", 15958inst="sethi %hi(0x11800), %o2"@}, 15959@{address="0x000107c8",func-name="main",offset="12", 15960inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@}, 15961@{address="0x000107cc",func-name="main",offset="16", 15962inst="sethi %hi(0x11800), %o2"@}, 15963@{address="0x000107d0",func-name="main",offset="20", 15964inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}] 15965(@value{GDBP}) 15966@end smallexample 15967 15968Disassemble the whole @code{main} function. Line 32 is part of 15969@code{main}. 15970 15971@smallexample 15972-data-disassemble -f basics.c -l 32 -- 0 15973^done,asm_insns=[ 15974@{address="0x000107bc",func-name="main",offset="0", 15975inst="save %sp, -112, %sp"@}, 15976@{address="0x000107c0",func-name="main",offset="4", 15977inst="mov 2, %o0"@}, 15978@{address="0x000107c4",func-name="main",offset="8", 15979inst="sethi %hi(0x11800), %o2"@}, 15980[@dots{}] 15981@{address="0x0001081c",func-name="main",offset="96",inst="ret "@}, 15982@{address="0x00010820",func-name="main",offset="100",inst="restore "@}] 15983(@value{GDBP}) 15984@end smallexample 15985 15986Disassemble 3 instructions from the start of @code{main}: 15987 15988@smallexample 15989(@value{GDBP}) 15990-data-disassemble -f basics.c -l 32 -n 3 -- 0 15991^done,asm_insns=[ 15992@{address="0x000107bc",func-name="main",offset="0", 15993inst="save %sp, -112, %sp"@}, 15994@{address="0x000107c0",func-name="main",offset="4", 15995inst="mov 2, %o0"@}, 15996@{address="0x000107c4",func-name="main",offset="8", 15997inst="sethi %hi(0x11800), %o2"@}] 15998(@value{GDBP}) 15999@end smallexample 16000 16001Disassemble 3 instructions from the start of @code{main} in mixed mode: 16002 16003@smallexample 16004(@value{GDBP}) 16005-data-disassemble -f basics.c -l 32 -n 3 -- 1 16006^done,asm_insns=[ 16007src_and_asm_line=@{line="31", 16008file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ 16009 testsuite/gdb.mi/basics.c",line_asm_insn=[ 16010@{address="0x000107bc",func-name="main",offset="0", 16011inst="save %sp, -112, %sp"@}]@}, 16012src_and_asm_line=@{line="32", 16013file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ 16014 testsuite/gdb.mi/basics.c",line_asm_insn=[ 16015@{address="0x000107c0",func-name="main",offset="4", 16016inst="mov 2, %o0"@}, 16017@{address="0x000107c4",func-name="main",offset="8", 16018inst="sethi %hi(0x11800), %o2"@}]@}] 16019(@value{GDBP}) 16020@end smallexample 16021 16022 16023@subheading The @code{-data-evaluate-expression} Command 16024@findex -data-evaluate-expression 16025 16026@subsubheading Synopsis 16027 16028@smallexample 16029 -data-evaluate-expression @var{expr} 16030@end smallexample 16031 16032Evaluate @var{expr} as an expression. The expression could contain an 16033inferior function call. The function call will execute synchronously. 16034If the expression contains spaces, it must be enclosed in double quotes. 16035 16036@subsubheading @value{GDBN} Command 16037 16038The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and 16039@samp{call}. In @code{gdbtk} only, there's a corresponding 16040@samp{gdb_eval} command. 16041 16042@subsubheading Example 16043 16044In the following example, the numbers that precede the commands are the 16045@dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi} 16046Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its 16047output. 16048 16049@smallexample 16050211-data-evaluate-expression A 16051211^done,value="1" 16052(@value{GDBP}) 16053311-data-evaluate-expression &A 16054311^done,value="0xefffeb7c" 16055(@value{GDBP}) 16056411-data-evaluate-expression A+3 16057411^done,value="4" 16058(@value{GDBP}) 16059511-data-evaluate-expression "A + 3" 16060511^done,value="4" 16061(@value{GDBP}) 16062@end smallexample 16063 16064 16065@subheading The @code{-data-list-changed-registers} Command 16066@findex -data-list-changed-registers 16067 16068@subsubheading Synopsis 16069 16070@smallexample 16071 -data-list-changed-registers 16072@end smallexample 16073 16074Display a list of the registers that have changed. 16075 16076@subsubheading @value{GDBN} Command 16077 16078@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk} 16079has the corresponding command @samp{gdb_changed_register_list}. 16080 16081@subsubheading Example 16082 16083On a PPC MBX board: 16084 16085@smallexample 16086(@value{GDBP}) 16087-exec-continue 16088^running 16089 16090(@value{GDBP}) 16091*stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main", 16092args=[],file="try.c",line="5"@} 16093(@value{GDBP}) 16094-data-list-changed-registers 16095^done,changed-registers=["0","1","2","4","5","6","7","8","9", 16096"10","11","13","14","15","16","17","18","19","20","21","22","23", 16097"24","25","26","27","28","30","31","64","65","66","67","69"] 16098(@value{GDBP}) 16099@end smallexample 16100 16101 16102@subheading The @code{-data-list-register-names} Command 16103@findex -data-list-register-names 16104 16105@subsubheading Synopsis 16106 16107@smallexample 16108 -data-list-register-names [ ( @var{regno} )+ ] 16109@end smallexample 16110 16111Show a list of register names for the current target. If no arguments 16112are given, it shows a list of the names of all the registers. If 16113integer numbers are given as arguments, it will print a list of the 16114names of the registers corresponding to the arguments. To ensure 16115consistency between a register name and its number, the output list may 16116include empty register names. 16117 16118@subsubheading @value{GDBN} Command 16119 16120@value{GDBN} does not have a command which corresponds to 16121@samp{-data-list-register-names}. In @code{gdbtk} there is a 16122corresponding command @samp{gdb_regnames}. 16123 16124@subsubheading Example 16125 16126For the PPC MBX board: 16127@smallexample 16128(@value{GDBP}) 16129-data-list-register-names 16130^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", 16131"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", 16132"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", 16133"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", 16134"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", 16135"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", 16136"", "pc","ps","cr","lr","ctr","xer"] 16137(@value{GDBP}) 16138-data-list-register-names 1 2 3 16139^done,register-names=["r1","r2","r3"] 16140(@value{GDBP}) 16141@end smallexample 16142 16143@subheading The @code{-data-list-register-values} Command 16144@findex -data-list-register-values 16145 16146@subsubheading Synopsis 16147 16148@smallexample 16149 -data-list-register-values @var{fmt} [ ( @var{regno} )*] 16150@end smallexample 16151 16152Display the registers' contents. @var{fmt} is the format according to 16153which the registers' contents are to be returned, followed by an optional 16154list of numbers specifying the registers to display. A missing list of 16155numbers indicates that the contents of all the registers must be returned. 16156 16157Allowed formats for @var{fmt} are: 16158 16159@table @code 16160@item x 16161Hexadecimal 16162@item o 16163Octal 16164@item t 16165Binary 16166@item d 16167Decimal 16168@item r 16169Raw 16170@item N 16171Natural 16172@end table 16173 16174@subsubheading @value{GDBN} Command 16175 16176The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info 16177all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}. 16178 16179@subsubheading Example 16180 16181For a PPC MBX board (note: line breaks are for readability only, they 16182don't appear in the actual output): 16183 16184@smallexample 16185(@value{GDBP}) 16186-data-list-register-values r 64 65 16187^done,register-values=[@{number="64",value="0xfe00a300"@}, 16188@{number="65",value="0x00029002"@}] 16189(@value{GDBP}) 16190-data-list-register-values x 16191^done,register-values=[@{number="0",value="0xfe0043c8"@}, 16192@{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@}, 16193@{number="3",value="0x0"@},@{number="4",value="0xa"@}, 16194@{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@}, 16195@{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@}, 16196@{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@}, 16197@{number="11",value="0x1"@},@{number="12",value="0x0"@}, 16198@{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@}, 16199@{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@}, 16200@{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@}, 16201@{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@}, 16202@{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@}, 16203@{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@}, 16204@{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@}, 16205@{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@}, 16206@{number="29",value="0x0"@},@{number="30",value="0xfe010000"@}, 16207@{number="31",value="0x0"@},@{number="32",value="0x0"@}, 16208@{number="33",value="0x0"@},@{number="34",value="0x0"@}, 16209@{number="35",value="0x0"@},@{number="36",value="0x0"@}, 16210@{number="37",value="0x0"@},@{number="38",value="0x0"@}, 16211@{number="39",value="0x0"@},@{number="40",value="0x0"@}, 16212@{number="41",value="0x0"@},@{number="42",value="0x0"@}, 16213@{number="43",value="0x0"@},@{number="44",value="0x0"@}, 16214@{number="45",value="0x0"@},@{number="46",value="0x0"@}, 16215@{number="47",value="0x0"@},@{number="48",value="0x0"@}, 16216@{number="49",value="0x0"@},@{number="50",value="0x0"@}, 16217@{number="51",value="0x0"@},@{number="52",value="0x0"@}, 16218@{number="53",value="0x0"@},@{number="54",value="0x0"@}, 16219@{number="55",value="0x0"@},@{number="56",value="0x0"@}, 16220@{number="57",value="0x0"@},@{number="58",value="0x0"@}, 16221@{number="59",value="0x0"@},@{number="60",value="0x0"@}, 16222@{number="61",value="0x0"@},@{number="62",value="0x0"@}, 16223@{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@}, 16224@{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@}, 16225@{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@}, 16226@{number="69",value="0x20002b03"@}] 16227(@value{GDBP}) 16228@end smallexample 16229 16230 16231@subheading The @code{-data-read-memory} Command 16232@findex -data-read-memory 16233 16234@subsubheading Synopsis 16235 16236@smallexample 16237 -data-read-memory [ -o @var{byte-offset} ] 16238 @var{address} @var{word-format} @var{word-size} 16239 @var{nr-rows} @var{nr-cols} [ @var{aschar} ] 16240@end smallexample 16241 16242@noindent 16243where: 16244 16245@table @samp 16246@item @var{address} 16247An expression specifying the address of the first memory word to be 16248read. Complex expressions containing embedded white space should be 16249quoted using the C convention. 16250 16251@item @var{word-format} 16252The format to be used to print the memory words. The notation is the 16253same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats, 16254,Output formats}). 16255 16256@item @var{word-size} 16257The size of each memory word in bytes. 16258 16259@item @var{nr-rows} 16260The number of rows in the output table. 16261 16262@item @var{nr-cols} 16263The number of columns in the output table. 16264 16265@item @var{aschar} 16266If present, indicates that each row should include an @sc{ascii} dump. The 16267value of @var{aschar} is used as a padding character when a byte is not a 16268member of the printable @sc{ascii} character set (printable @sc{ascii} 16269characters are those whose code is between 32 and 126, inclusively). 16270 16271@item @var{byte-offset} 16272An offset to add to the @var{address} before fetching memory. 16273@end table 16274 16275This command displays memory contents as a table of @var{nr-rows} by 16276@var{nr-cols} words, each word being @var{word-size} bytes. In total, 16277@code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read 16278(returned as @samp{total-bytes}). Should less than the requested number 16279of bytes be returned by the target, the missing words are identified 16280using @samp{N/A}. The number of bytes read from the target is returned 16281in @samp{nr-bytes} and the starting address used to read memory in 16282@samp{addr}. 16283 16284The address of the next/previous row or page is available in 16285@samp{next-row} and @samp{prev-row}, @samp{next-page} and 16286@samp{prev-page}. 16287 16288@subsubheading @value{GDBN} Command 16289 16290The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has 16291@samp{gdb_get_mem} memory read command. 16292 16293@subsubheading Example 16294 16295Read six bytes of memory starting at @code{bytes+6} but then offset by 16296@code{-6} bytes. Format as three rows of two columns. One byte per 16297word. Display each word in hex. 16298 16299@smallexample 16300(@value{GDBP}) 163019-data-read-memory -o -6 -- bytes+6 x 1 3 2 163029^done,addr="0x00001390",nr-bytes="6",total-bytes="6", 16303next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", 16304prev-page="0x0000138a",memory=[ 16305@{addr="0x00001390",data=["0x00","0x01"]@}, 16306@{addr="0x00001392",data=["0x02","0x03"]@}, 16307@{addr="0x00001394",data=["0x04","0x05"]@}] 16308(@value{GDBP}) 16309@end smallexample 16310 16311Read two bytes of memory starting at address @code{shorts + 64} and 16312display as a single word formatted in decimal. 16313 16314@smallexample 16315(@value{GDBP}) 163165-data-read-memory shorts+64 d 2 1 1 163175^done,addr="0x00001510",nr-bytes="2",total-bytes="2", 16318next-row="0x00001512",prev-row="0x0000150e", 16319next-page="0x00001512",prev-page="0x0000150e",memory=[ 16320@{addr="0x00001510",data=["128"]@}] 16321(@value{GDBP}) 16322@end smallexample 16323 16324Read thirty two bytes of memory starting at @code{bytes+16} and format 16325as eight rows of four columns. Include a string encoding with @samp{x} 16326used as the non-printable character. 16327 16328@smallexample 16329(@value{GDBP}) 163304-data-read-memory bytes+16 x 1 8 4 x 163314^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", 16332next-row="0x000013c0",prev-row="0x0000139c", 16333next-page="0x000013c0",prev-page="0x00001380",memory=[ 16334@{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@}, 16335@{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@}, 16336@{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@}, 16337@{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@}, 16338@{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@}, 16339@{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@}, 16340@{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@}, 16341@{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}] 16342(@value{GDBP}) 16343@end smallexample 16344 16345@subheading The @code{-display-delete} Command 16346@findex -display-delete 16347 16348@subsubheading Synopsis 16349 16350@smallexample 16351 -display-delete @var{number} 16352@end smallexample 16353 16354Delete the display @var{number}. 16355 16356@subsubheading @value{GDBN} Command 16357 16358The corresponding @value{GDBN} command is @samp{delete display}. 16359 16360@subsubheading Example 16361N.A. 16362 16363 16364@subheading The @code{-display-disable} Command 16365@findex -display-disable 16366 16367@subsubheading Synopsis 16368 16369@smallexample 16370 -display-disable @var{number} 16371@end smallexample 16372 16373Disable display @var{number}. 16374 16375@subsubheading @value{GDBN} Command 16376 16377The corresponding @value{GDBN} command is @samp{disable display}. 16378 16379@subsubheading Example 16380N.A. 16381 16382 16383@subheading The @code{-display-enable} Command 16384@findex -display-enable 16385 16386@subsubheading Synopsis 16387 16388@smallexample 16389 -display-enable @var{number} 16390@end smallexample 16391 16392Enable display @var{number}. 16393 16394@subsubheading @value{GDBN} Command 16395 16396The corresponding @value{GDBN} command is @samp{enable display}. 16397 16398@subsubheading Example 16399N.A. 16400 16401 16402@subheading The @code{-display-insert} Command 16403@findex -display-insert 16404 16405@subsubheading Synopsis 16406 16407@smallexample 16408 -display-insert @var{expression} 16409@end smallexample 16410 16411Display @var{expression} every time the program stops. 16412 16413@subsubheading @value{GDBN} Command 16414 16415The corresponding @value{GDBN} command is @samp{display}. 16416 16417@subsubheading Example 16418N.A. 16419 16420 16421@subheading The @code{-display-list} Command 16422@findex -display-list 16423 16424@subsubheading Synopsis 16425 16426@smallexample 16427 -display-list 16428@end smallexample 16429 16430List the displays. Do not show the current values. 16431 16432@subsubheading @value{GDBN} Command 16433 16434The corresponding @value{GDBN} command is @samp{info display}. 16435 16436@subsubheading Example 16437N.A. 16438 16439 16440@subheading The @code{-environment-cd} Command 16441@findex -environment-cd 16442 16443@subsubheading Synopsis 16444 16445@smallexample 16446 -environment-cd @var{pathdir} 16447@end smallexample 16448 16449Set @value{GDBN}'s working directory. 16450 16451@subsubheading @value{GDBN} Command 16452 16453The corresponding @value{GDBN} command is @samp{cd}. 16454 16455@subsubheading Example 16456 16457@smallexample 16458(@value{GDBP}) 16459-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb 16460^done 16461(@value{GDBP}) 16462@end smallexample 16463 16464 16465@subheading The @code{-environment-directory} Command 16466@findex -environment-directory 16467 16468@subsubheading Synopsis 16469 16470@smallexample 16471 -environment-directory [ -r ] [ @var{pathdir} ]+ 16472@end smallexample 16473 16474Add directories @var{pathdir} to beginning of search path for source files. 16475If the @samp{-r} option is used, the search path is reset to the default 16476search path. If directories @var{pathdir} are supplied in addition to the 16477@samp{-r} option, the search path is first reset and then addition 16478occurs as normal. 16479Multiple directories may be specified, separated by blanks. Specifying 16480multiple directories in a single command 16481results in the directories added to the beginning of the 16482search path in the same order they were presented in the command. 16483If blanks are needed as 16484part of a directory name, double-quotes should be used around 16485the name. In the command output, the path will show up separated 16486by the system directory-separator character. The directory-seperator 16487character must not be used 16488in any directory name. 16489If no directories are specified, the current search path is displayed. 16490 16491@subsubheading @value{GDBN} Command 16492 16493The corresponding @value{GDBN} command is @samp{dir}. 16494 16495@subsubheading Example 16496 16497@smallexample 16498(@value{GDBP}) 16499-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb 16500^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" 16501(@value{GDBP}) 16502-environment-directory "" 16503^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" 16504(@value{GDBP}) 16505-environment-directory -r /home/jjohnstn/src/gdb /usr/src 16506^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" 16507(@value{GDBP}) 16508-environment-directory -r 16509^done,source-path="$cdir:$cwd" 16510(@value{GDBP}) 16511@end smallexample 16512 16513 16514@subheading The @code{-environment-path} Command 16515@findex -environment-path 16516 16517@subsubheading Synopsis 16518 16519@smallexample 16520 -environment-path [ -r ] [ @var{pathdir} ]+ 16521@end smallexample 16522 16523Add directories @var{pathdir} to beginning of search path for object files. 16524If the @samp{-r} option is used, the search path is reset to the original 16525search path that existed at gdb start-up. If directories @var{pathdir} are 16526supplied in addition to the 16527@samp{-r} option, the search path is first reset and then addition 16528occurs as normal. 16529Multiple directories may be specified, separated by blanks. Specifying 16530multiple directories in a single command 16531results in the directories added to the beginning of the 16532search path in the same order they were presented in the command. 16533If blanks are needed as 16534part of a directory name, double-quotes should be used around 16535the name. In the command output, the path will show up separated 16536by the system directory-separator character. The directory-seperator 16537character must not be used 16538in any directory name. 16539If no directories are specified, the current path is displayed. 16540 16541 16542@subsubheading @value{GDBN} Command 16543 16544The corresponding @value{GDBN} command is @samp{path}. 16545 16546@subsubheading Example 16547 16548@smallexample 16549(@value{GDBP}) 16550-environment-path 16551^done,path="/usr/bin" 16552(@value{GDBP}) 16553-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin 16554^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" 16555(@value{GDBP}) 16556-environment-path -r /usr/local/bin 16557^done,path="/usr/local/bin:/usr/bin" 16558(@value{GDBP}) 16559@end smallexample 16560 16561 16562@subheading The @code{-environment-pwd} Command 16563@findex -environment-pwd 16564 16565@subsubheading Synopsis 16566 16567@smallexample 16568 -environment-pwd 16569@end smallexample 16570 16571Show the current working directory. 16572 16573@subsubheading @value{GDBN} command 16574 16575The corresponding @value{GDBN} command is @samp{pwd}. 16576 16577@subsubheading Example 16578 16579@smallexample 16580(@value{GDBP}) 16581-environment-pwd 16582^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" 16583(@value{GDBP}) 16584@end smallexample 16585 16586@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 16587@node GDB/MI Program Control 16588@section @sc{gdb/mi} Program control 16589 16590@subsubheading Program termination 16591 16592As a result of execution, the inferior program can run to completion, if 16593it doesn't encounter any breakpoints. In this case the output will 16594include an exit code, if the program has exited exceptionally. 16595 16596@subsubheading Examples 16597 16598@noindent 16599Program exited normally: 16600 16601@smallexample 16602(@value{GDBP}) 16603-exec-run 16604^running 16605(@value{GDBP}) 16606x = 55 16607*stopped,reason="exited-normally" 16608(@value{GDBP}) 16609@end smallexample 16610 16611@noindent 16612Program exited exceptionally: 16613 16614@smallexample 16615(@value{GDBP}) 16616-exec-run 16617^running 16618(@value{GDBP}) 16619x = 55 16620*stopped,reason="exited",exit-code="01" 16621(@value{GDBP}) 16622@end smallexample 16623 16624Another way the program can terminate is if it receives a signal such as 16625@code{SIGINT}. In this case, @sc{gdb/mi} displays this: 16626 16627@smallexample 16628(@value{GDBP}) 16629*stopped,reason="exited-signalled",signal-name="SIGINT", 16630signal-meaning="Interrupt" 16631@end smallexample 16632 16633 16634@subheading The @code{-exec-abort} Command 16635@findex -exec-abort 16636 16637@subsubheading Synopsis 16638 16639@smallexample 16640 -exec-abort 16641@end smallexample 16642 16643Kill the inferior running program. 16644 16645@subsubheading @value{GDBN} Command 16646 16647The corresponding @value{GDBN} command is @samp{kill}. 16648 16649@subsubheading Example 16650N.A. 16651 16652 16653@subheading The @code{-exec-arguments} Command 16654@findex -exec-arguments 16655 16656@subsubheading Synopsis 16657 16658@smallexample 16659 -exec-arguments @var{args} 16660@end smallexample 16661 16662Set the inferior program arguments, to be used in the next 16663@samp{-exec-run}. 16664 16665@subsubheading @value{GDBN} Command 16666 16667The corresponding @value{GDBN} command is @samp{set args}. 16668 16669@subsubheading Example 16670 16671@c FIXME! 16672Don't have one around. 16673 16674 16675@subheading The @code{-exec-continue} Command 16676@findex -exec-continue 16677 16678@subsubheading Synopsis 16679 16680@smallexample 16681 -exec-continue 16682@end smallexample 16683 16684Asynchronous command. Resumes the execution of the inferior program 16685until a breakpoint is encountered, or until the inferior exits. 16686 16687@subsubheading @value{GDBN} Command 16688 16689The corresponding @value{GDBN} corresponding is @samp{continue}. 16690 16691@subsubheading Example 16692 16693@smallexample 16694-exec-continue 16695^running 16696(@value{GDBP}) 16697@@Hello world 16698*stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[], 16699file="hello.c",line="13"@} 16700(@value{GDBP}) 16701@end smallexample 16702 16703 16704@subheading The @code{-exec-finish} Command 16705@findex -exec-finish 16706 16707@subsubheading Synopsis 16708 16709@smallexample 16710 -exec-finish 16711@end smallexample 16712 16713Asynchronous command. Resumes the execution of the inferior program 16714until the current function is exited. Displays the results returned by 16715the function. 16716 16717@subsubheading @value{GDBN} Command 16718 16719The corresponding @value{GDBN} command is @samp{finish}. 16720 16721@subsubheading Example 16722 16723Function returning @code{void}. 16724 16725@smallexample 16726-exec-finish 16727^running 16728(@value{GDBP}) 16729@@hello from foo 16730*stopped,reason="function-finished",frame=@{func="main",args=[], 16731file="hello.c",line="7"@} 16732(@value{GDBP}) 16733@end smallexample 16734 16735Function returning other than @code{void}. The name of the internal 16736@value{GDBN} variable storing the result is printed, together with the 16737value itself. 16738 16739@smallexample 16740-exec-finish 16741^running 16742(@value{GDBP}) 16743*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo", 16744args=[@{name="a",value="1"],@{name="b",value="9"@}@}, 16745file="recursive2.c",line="14"@}, 16746gdb-result-var="$1",return-value="0" 16747(@value{GDBP}) 16748@end smallexample 16749 16750 16751@subheading The @code{-exec-interrupt} Command 16752@findex -exec-interrupt 16753 16754@subsubheading Synopsis 16755 16756@smallexample 16757 -exec-interrupt 16758@end smallexample 16759 16760Asynchronous command. Interrupts the background execution of the target. 16761Note how the token associated with the stop message is the one for the 16762execution command that has been interrupted. The token for the interrupt 16763itself only appears in the @samp{^done} output. If the user is trying to 16764interrupt a non-running program, an error message will be printed. 16765 16766@subsubheading @value{GDBN} Command 16767 16768The corresponding @value{GDBN} command is @samp{interrupt}. 16769 16770@subsubheading Example 16771 16772@smallexample 16773(@value{GDBP}) 16774111-exec-continue 16775111^running 16776 16777(@value{GDBP}) 16778222-exec-interrupt 16779222^done 16780(@value{GDBP}) 16781111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", 16782frame=@{addr="0x00010140",func="foo",args=[],file="try.c",line="13"@} 16783(@value{GDBP}) 16784 16785(@value{GDBP}) 16786-exec-interrupt 16787^error,msg="mi_cmd_exec_interrupt: Inferior not executing." 16788(@value{GDBP}) 16789@end smallexample 16790 16791 16792@subheading The @code{-exec-next} Command 16793@findex -exec-next 16794 16795@subsubheading Synopsis 16796 16797@smallexample 16798 -exec-next 16799@end smallexample 16800 16801Asynchronous command. Resumes execution of the inferior program, stopping 16802when the beginning of the next source line is reached. 16803 16804@subsubheading @value{GDBN} Command 16805 16806The corresponding @value{GDBN} command is @samp{next}. 16807 16808@subsubheading Example 16809 16810@smallexample 16811-exec-next 16812^running 16813(@value{GDBP}) 16814*stopped,reason="end-stepping-range",line="8",file="hello.c" 16815(@value{GDBP}) 16816@end smallexample 16817 16818 16819@subheading The @code{-exec-next-instruction} Command 16820@findex -exec-next-instruction 16821 16822@subsubheading Synopsis 16823 16824@smallexample 16825 -exec-next-instruction 16826@end smallexample 16827 16828Asynchronous command. Executes one machine instruction. If the 16829instruction is a function call continues until the function returns. If 16830the program stops at an instruction in the middle of a source line, the 16831address will be printed as well. 16832 16833@subsubheading @value{GDBN} Command 16834 16835The corresponding @value{GDBN} command is @samp{nexti}. 16836 16837@subsubheading Example 16838 16839@smallexample 16840(@value{GDBP}) 16841-exec-next-instruction 16842^running 16843 16844(@value{GDBP}) 16845*stopped,reason="end-stepping-range", 16846addr="0x000100d4",line="5",file="hello.c" 16847(@value{GDBP}) 16848@end smallexample 16849 16850 16851@subheading The @code{-exec-return} Command 16852@findex -exec-return 16853 16854@subsubheading Synopsis 16855 16856@smallexample 16857 -exec-return 16858@end smallexample 16859 16860Makes current function return immediately. Doesn't execute the inferior. 16861Displays the new current frame. 16862 16863@subsubheading @value{GDBN} Command 16864 16865The corresponding @value{GDBN} command is @samp{return}. 16866 16867@subsubheading Example 16868 16869@smallexample 16870(@value{GDBP}) 16871200-break-insert callee4 16872200^done,bkpt=@{number="1",addr="0x00010734", 16873file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} 16874(@value{GDBP}) 16875000-exec-run 16876000^running 16877(@value{GDBP}) 16878000*stopped,reason="breakpoint-hit",bkptno="1", 16879frame=@{func="callee4",args=[], 16880file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} 16881(@value{GDBP}) 16882205-break-delete 16883205^done 16884(@value{GDBP}) 16885111-exec-return 16886111^done,frame=@{level="0",func="callee3", 16887args=[@{name="strarg", 16888value="0x11940 \"A string argument.\""@}], 16889file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} 16890(@value{GDBP}) 16891@end smallexample 16892 16893 16894@subheading The @code{-exec-run} Command 16895@findex -exec-run 16896 16897@subsubheading Synopsis 16898 16899@smallexample 16900 -exec-run 16901@end smallexample 16902 16903Asynchronous command. Starts execution of the inferior from the 16904beginning. The inferior executes until either a breakpoint is 16905encountered or the program exits. 16906 16907@subsubheading @value{GDBN} Command 16908 16909The corresponding @value{GDBN} command is @samp{run}. 16910 16911@subsubheading Example 16912 16913@smallexample 16914(@value{GDBP}) 16915-break-insert main 16916^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} 16917(@value{GDBP}) 16918-exec-run 16919^running 16920(@value{GDBP}) 16921*stopped,reason="breakpoint-hit",bkptno="1", 16922frame=@{func="main",args=[],file="recursive2.c",line="4"@} 16923(@value{GDBP}) 16924@end smallexample 16925 16926 16927@subheading The @code{-exec-show-arguments} Command 16928@findex -exec-show-arguments 16929 16930@subsubheading Synopsis 16931 16932@smallexample 16933 -exec-show-arguments 16934@end smallexample 16935 16936Print the arguments of the program. 16937 16938@subsubheading @value{GDBN} Command 16939 16940The corresponding @value{GDBN} command is @samp{show args}. 16941 16942@subsubheading Example 16943N.A. 16944 16945@c @subheading -exec-signal 16946 16947@subheading The @code{-exec-step} Command 16948@findex -exec-step 16949 16950@subsubheading Synopsis 16951 16952@smallexample 16953 -exec-step 16954@end smallexample 16955 16956Asynchronous command. Resumes execution of the inferior program, stopping 16957when the beginning of the next source line is reached, if the next 16958source line is not a function call. If it is, stop at the first 16959instruction of the called function. 16960 16961@subsubheading @value{GDBN} Command 16962 16963The corresponding @value{GDBN} command is @samp{step}. 16964 16965@subsubheading Example 16966 16967Stepping into a function: 16968 16969@smallexample 16970-exec-step 16971^running 16972(@value{GDBP}) 16973*stopped,reason="end-stepping-range", 16974frame=@{func="foo",args=[@{name="a",value="10"@}, 16975@{name="b",value="0"@}],file="recursive2.c",line="11"@} 16976(@value{GDBP}) 16977@end smallexample 16978 16979Regular stepping: 16980 16981@smallexample 16982-exec-step 16983^running 16984(@value{GDBP}) 16985*stopped,reason="end-stepping-range",line="14",file="recursive2.c" 16986(@value{GDBP}) 16987@end smallexample 16988 16989 16990@subheading The @code{-exec-step-instruction} Command 16991@findex -exec-step-instruction 16992 16993@subsubheading Synopsis 16994 16995@smallexample 16996 -exec-step-instruction 16997@end smallexample 16998 16999Asynchronous command. Resumes the inferior which executes one machine 17000instruction. The output, once @value{GDBN} has stopped, will vary depending on 17001whether we have stopped in the middle of a source line or not. In the 17002former case, the address at which the program stopped will be printed as 17003well. 17004 17005@subsubheading @value{GDBN} Command 17006 17007The corresponding @value{GDBN} command is @samp{stepi}. 17008 17009@subsubheading Example 17010 17011@smallexample 17012(@value{GDBP}) 17013-exec-step-instruction 17014^running 17015 17016(@value{GDBP}) 17017*stopped,reason="end-stepping-range", 17018frame=@{func="foo",args=[],file="try.c",line="10"@} 17019(@value{GDBP}) 17020-exec-step-instruction 17021^running 17022 17023(@value{GDBP}) 17024*stopped,reason="end-stepping-range", 17025frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",line="10"@} 17026(@value{GDBP}) 17027@end smallexample 17028 17029 17030@subheading The @code{-exec-until} Command 17031@findex -exec-until 17032 17033@subsubheading Synopsis 17034 17035@smallexample 17036 -exec-until [ @var{location} ] 17037@end smallexample 17038 17039Asynchronous command. Executes the inferior until the @var{location} 17040specified in the argument is reached. If there is no argument, the inferior 17041executes until a source line greater than the current one is reached. 17042The reason for stopping in this case will be @samp{location-reached}. 17043 17044@subsubheading @value{GDBN} Command 17045 17046The corresponding @value{GDBN} command is @samp{until}. 17047 17048@subsubheading Example 17049 17050@smallexample 17051(@value{GDBP}) 17052-exec-until recursive2.c:6 17053^running 17054(@value{GDBP}) 17055x = 55 17056*stopped,reason="location-reached",frame=@{func="main",args=[], 17057file="recursive2.c",line="6"@} 17058(@value{GDBP}) 17059@end smallexample 17060 17061@ignore 17062@subheading -file-clear 17063Is this going away???? 17064@end ignore 17065 17066 17067@subheading The @code{-file-exec-and-symbols} Command 17068@findex -file-exec-and-symbols 17069 17070@subsubheading Synopsis 17071 17072@smallexample 17073 -file-exec-and-symbols @var{file} 17074@end smallexample 17075 17076Specify the executable file to be debugged. This file is the one from 17077which the symbol table is also read. If no file is specified, the 17078command clears the executable and symbol information. If breakpoints 17079are set when using this command with no arguments, @value{GDBN} will produce 17080error messages. Otherwise, no output is produced, except a completion 17081notification. 17082 17083@subsubheading @value{GDBN} Command 17084 17085The corresponding @value{GDBN} command is @samp{file}. 17086 17087@subsubheading Example 17088 17089@smallexample 17090(@value{GDBP}) 17091-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 17092^done 17093(@value{GDBP}) 17094@end smallexample 17095 17096 17097@subheading The @code{-file-exec-file} Command 17098@findex -file-exec-file 17099 17100@subsubheading Synopsis 17101 17102@smallexample 17103 -file-exec-file @var{file} 17104@end smallexample 17105 17106Specify the executable file to be debugged. Unlike 17107@samp{-file-exec-and-symbols}, the symbol table is @emph{not} read 17108from this file. If used without argument, @value{GDBN} clears the information 17109about the executable file. No output is produced, except a completion 17110notification. 17111 17112@subsubheading @value{GDBN} Command 17113 17114The corresponding @value{GDBN} command is @samp{exec-file}. 17115 17116@subsubheading Example 17117 17118@smallexample 17119(@value{GDBP}) 17120-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 17121^done 17122(@value{GDBP}) 17123@end smallexample 17124 17125 17126@subheading The @code{-file-list-exec-sections} Command 17127@findex -file-list-exec-sections 17128 17129@subsubheading Synopsis 17130 17131@smallexample 17132 -file-list-exec-sections 17133@end smallexample 17134 17135List the sections of the current executable file. 17136 17137@subsubheading @value{GDBN} Command 17138 17139The @value{GDBN} command @samp{info file} shows, among the rest, the same 17140information as this command. @code{gdbtk} has a corresponding command 17141@samp{gdb_load_info}. 17142 17143@subsubheading Example 17144N.A. 17145 17146 17147@subheading The @code{-file-list-exec-source-file} Command 17148@findex -file-list-exec-source-file 17149 17150@subsubheading Synopsis 17151 17152@smallexample 17153 -file-list-exec-source-file 17154@end smallexample 17155 17156List the line number, the current source file, and the absolute path 17157to the current source file for the current executable. 17158 17159@subsubheading @value{GDBN} Command 17160 17161There's no @value{GDBN} command which directly corresponds to this one. 17162 17163@subsubheading Example 17164 17165@smallexample 17166(@value{GDBP}) 17167123-file-list-exec-source-file 17168123^done,line="1",file="foo.c",fullname="/home/bar/foo.c" 17169(@value{GDBP}) 17170@end smallexample 17171 17172 17173@subheading The @code{-file-list-exec-source-files} Command 17174@findex -file-list-exec-source-files 17175 17176@subsubheading Synopsis 17177 17178@smallexample 17179 -file-list-exec-source-files 17180@end smallexample 17181 17182List the source files for the current executable. 17183 17184It will always output the filename, but only when GDB can find the absolute 17185file name of a source file, will it output the fullname. 17186 17187@subsubheading @value{GDBN} Command 17188 17189There's no @value{GDBN} command which directly corresponds to this one. 17190@code{gdbtk} has an analogous command @samp{gdb_listfiles}. 17191 17192@subsubheading Example 17193@smallexample 17194(@value{GDBP}) 17195-file-list-exec-source-files 17196^done,files=[ 17197@{file=foo.c,fullname=/home/foo.c@}, 17198@{file=/home/bar.c,fullname=/home/bar.c@}, 17199@{file=gdb_could_not_find_fullpath.c@}] 17200(@value{GDBP}) 17201@end smallexample 17202 17203@subheading The @code{-file-list-shared-libraries} Command 17204@findex -file-list-shared-libraries 17205 17206@subsubheading Synopsis 17207 17208@smallexample 17209 -file-list-shared-libraries 17210@end smallexample 17211 17212List the shared libraries in the program. 17213 17214@subsubheading @value{GDBN} Command 17215 17216The corresponding @value{GDBN} command is @samp{info shared}. 17217 17218@subsubheading Example 17219N.A. 17220 17221 17222@subheading The @code{-file-list-symbol-files} Command 17223@findex -file-list-symbol-files 17224 17225@subsubheading Synopsis 17226 17227@smallexample 17228 -file-list-symbol-files 17229@end smallexample 17230 17231List symbol files. 17232 17233@subsubheading @value{GDBN} Command 17234 17235The corresponding @value{GDBN} command is @samp{info file} (part of it). 17236 17237@subsubheading Example 17238N.A. 17239 17240 17241@subheading The @code{-file-symbol-file} Command 17242@findex -file-symbol-file 17243 17244@subsubheading Synopsis 17245 17246@smallexample 17247 -file-symbol-file @var{file} 17248@end smallexample 17249 17250Read symbol table info from the specified @var{file} argument. When 17251used without arguments, clears @value{GDBN}'s symbol table info. No output is 17252produced, except for a completion notification. 17253 17254@subsubheading @value{GDBN} Command 17255 17256The corresponding @value{GDBN} command is @samp{symbol-file}. 17257 17258@subsubheading Example 17259 17260@smallexample 17261(@value{GDBP}) 17262-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 17263^done 17264(@value{GDBP}) 17265@end smallexample 17266 17267@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 17268@node GDB/MI Miscellaneous Commands 17269@section Miscellaneous @value{GDBN} commands in @sc{gdb/mi} 17270 17271@c @subheading -gdb-complete 17272 17273@subheading The @code{-gdb-exit} Command 17274@findex -gdb-exit 17275 17276@subsubheading Synopsis 17277 17278@smallexample 17279 -gdb-exit 17280@end smallexample 17281 17282Exit @value{GDBN} immediately. 17283 17284@subsubheading @value{GDBN} Command 17285 17286Approximately corresponds to @samp{quit}. 17287 17288@subsubheading Example 17289 17290@smallexample 17291(@value{GDBP}) 17292-gdb-exit 17293@end smallexample 17294 17295@subheading The @code{-gdb-set} Command 17296@findex -gdb-set 17297 17298@subsubheading Synopsis 17299 17300@smallexample 17301 -gdb-set 17302@end smallexample 17303 17304Set an internal @value{GDBN} variable. 17305@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ????? 17306 17307@subsubheading @value{GDBN} Command 17308 17309The corresponding @value{GDBN} command is @samp{set}. 17310 17311@subsubheading Example 17312 17313@smallexample 17314(@value{GDBP}) 17315-gdb-set $foo=3 17316^done 17317(@value{GDBP}) 17318@end smallexample 17319 17320 17321@subheading The @code{-gdb-show} Command 17322@findex -gdb-show 17323 17324@subsubheading Synopsis 17325 17326@smallexample 17327 -gdb-show 17328@end smallexample 17329 17330Show the current value of a @value{GDBN} variable. 17331 17332@subsubheading @value{GDBN} command 17333 17334The corresponding @value{GDBN} command is @samp{show}. 17335 17336@subsubheading Example 17337 17338@smallexample 17339(@value{GDBP}) 17340-gdb-show annotate 17341^done,value="0" 17342(@value{GDBP}) 17343@end smallexample 17344 17345@c @subheading -gdb-source 17346 17347 17348@subheading The @code{-gdb-version} Command 17349@findex -gdb-version 17350 17351@subsubheading Synopsis 17352 17353@smallexample 17354 -gdb-version 17355@end smallexample 17356 17357Show version information for @value{GDBN}. Used mostly in testing. 17358 17359@subsubheading @value{GDBN} Command 17360 17361There's no equivalent @value{GDBN} command. @value{GDBN} by default shows this 17362information when you start an interactive session. 17363 17364@subsubheading Example 17365 17366@c This example modifies the actual output from GDB to avoid overfull 17367@c box in TeX. 17368@smallexample 17369(@value{GDBP}) 17370-gdb-version 17371~GNU gdb 5.2.1 17372~Copyright 2000 Free Software Foundation, Inc. 17373~GDB is free software, covered by the GNU General Public License, and 17374~you are welcome to change it and/or distribute copies of it under 17375~ certain conditions. 17376~Type "show copying" to see the conditions. 17377~There is absolutely no warranty for GDB. Type "show warranty" for 17378~ details. 17379~This GDB was configured as 17380 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". 17381^done 17382(@value{GDBP}) 17383@end smallexample 17384 17385@subheading The @code{-interpreter-exec} Command 17386@findex -interpreter-exec 17387 17388@subheading Synopsis 17389 17390@smallexample 17391-interpreter-exec @var{interpreter} @var{command} 17392@end smallexample 17393 17394Execute the specified @var{command} in the given @var{interpreter}. 17395 17396@subheading @value{GDBN} Command 17397 17398The corresponding @value{GDBN} command is @samp{interpreter-exec}. 17399 17400@subheading Example 17401 17402@smallexample 17403(@value{GDBP}) 17404-interpreter-exec console "break main" 17405&"During symbol reading, couldn't parse type; debugger out of date?.\n" 17406&"During symbol reading, bad structure-type format.\n" 17407~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" 17408^done 17409(@value{GDBP}) 17410@end smallexample 17411 17412@ignore 17413@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 17414@node GDB/MI Kod Commands 17415@section @sc{gdb/mi} Kod Commands 17416 17417The Kod commands are not implemented. 17418 17419@c @subheading -kod-info 17420 17421@c @subheading -kod-list 17422 17423@c @subheading -kod-list-object-types 17424 17425@c @subheading -kod-show 17426 17427@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 17428@node GDB/MI Memory Overlay Commands 17429@section @sc{gdb/mi} Memory Overlay Commands 17430 17431The memory overlay commands are not implemented. 17432 17433@c @subheading -overlay-auto 17434 17435@c @subheading -overlay-list-mapping-state 17436 17437@c @subheading -overlay-list-overlays 17438 17439@c @subheading -overlay-map 17440 17441@c @subheading -overlay-off 17442 17443@c @subheading -overlay-on 17444 17445@c @subheading -overlay-unmap 17446 17447@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 17448@node GDB/MI Signal Handling Commands 17449@section @sc{gdb/mi} Signal Handling Commands 17450 17451Signal handling commands are not implemented. 17452 17453@c @subheading -signal-handle 17454 17455@c @subheading -signal-list-handle-actions 17456 17457@c @subheading -signal-list-signal-types 17458@end ignore 17459 17460 17461@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 17462@node GDB/MI Stack Manipulation 17463@section @sc{gdb/mi} Stack Manipulation Commands 17464 17465 17466@subheading The @code{-stack-info-frame} Command 17467@findex -stack-info-frame 17468 17469@subsubheading Synopsis 17470 17471@smallexample 17472 -stack-info-frame 17473@end smallexample 17474 17475Get info on the current frame. 17476 17477@subsubheading @value{GDBN} Command 17478 17479The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame} 17480(without arguments). 17481 17482@subsubheading Example 17483N.A. 17484 17485@subheading The @code{-stack-info-depth} Command 17486@findex -stack-info-depth 17487 17488@subsubheading Synopsis 17489 17490@smallexample 17491 -stack-info-depth [ @var{max-depth} ] 17492@end smallexample 17493 17494Return the depth of the stack. If the integer argument @var{max-depth} 17495is specified, do not count beyond @var{max-depth} frames. 17496 17497@subsubheading @value{GDBN} Command 17498 17499There's no equivalent @value{GDBN} command. 17500 17501@subsubheading Example 17502 17503For a stack with frame levels 0 through 11: 17504 17505@smallexample 17506(@value{GDBP}) 17507-stack-info-depth 17508^done,depth="12" 17509(@value{GDBP}) 17510-stack-info-depth 4 17511^done,depth="4" 17512(@value{GDBP}) 17513-stack-info-depth 12 17514^done,depth="12" 17515(@value{GDBP}) 17516-stack-info-depth 11 17517^done,depth="11" 17518(@value{GDBP}) 17519-stack-info-depth 13 17520^done,depth="12" 17521(@value{GDBP}) 17522@end smallexample 17523 17524@subheading The @code{-stack-list-arguments} Command 17525@findex -stack-list-arguments 17526 17527@subsubheading Synopsis 17528 17529@smallexample 17530 -stack-list-arguments @var{show-values} 17531 [ @var{low-frame} @var{high-frame} ] 17532@end smallexample 17533 17534Display a list of the arguments for the frames between @var{low-frame} 17535and @var{high-frame} (inclusive). If @var{low-frame} and 17536@var{high-frame} are not provided, list the arguments for the whole call 17537stack. 17538 17539The @var{show-values} argument must have a value of 0 or 1. A value of 175400 means that only the names of the arguments are listed, a value of 1 17541means that both names and values of the arguments are printed. 17542 17543@subsubheading @value{GDBN} Command 17544 17545@value{GDBN} does not have an equivalent command. @code{gdbtk} has a 17546@samp{gdb_get_args} command which partially overlaps with the 17547functionality of @samp{-stack-list-arguments}. 17548 17549@subsubheading Example 17550 17551@smallexample 17552(@value{GDBP}) 17553-stack-list-frames 17554^done, 17555stack=[ 17556frame=@{level="0",addr="0x00010734",func="callee4", 17557file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}, 17558frame=@{level="1",addr="0x0001076c",func="callee3", 17559file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}, 17560frame=@{level="2",addr="0x0001078c",func="callee2", 17561file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@}, 17562frame=@{level="3",addr="0x000107b4",func="callee1", 17563file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@}, 17564frame=@{level="4",addr="0x000107e0",func="main", 17565file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}] 17566(@value{GDBP}) 17567-stack-list-arguments 0 17568^done, 17569stack-args=[ 17570frame=@{level="0",args=[]@}, 17571frame=@{level="1",args=[name="strarg"]@}, 17572frame=@{level="2",args=[name="intarg",name="strarg"]@}, 17573frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@}, 17574frame=@{level="4",args=[]@}] 17575(@value{GDBP}) 17576-stack-list-arguments 1 17577^done, 17578stack-args=[ 17579frame=@{level="0",args=[]@}, 17580frame=@{level="1", 17581 args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, 17582frame=@{level="2",args=[ 17583@{name="intarg",value="2"@}, 17584@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, 17585@{frame=@{level="3",args=[ 17586@{name="intarg",value="2"@}, 17587@{name="strarg",value="0x11940 \"A string argument.\""@}, 17588@{name="fltarg",value="3.5"@}]@}, 17589frame=@{level="4",args=[]@}] 17590(@value{GDBP}) 17591-stack-list-arguments 0 2 2 17592^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}] 17593(@value{GDBP}) 17594-stack-list-arguments 1 2 2 17595^done,stack-args=[frame=@{level="2", 17596args=[@{name="intarg",value="2"@}, 17597@{name="strarg",value="0x11940 \"A string argument.\""@}]@}] 17598(@value{GDBP}) 17599@end smallexample 17600 17601@c @subheading -stack-list-exception-handlers 17602 17603 17604@subheading The @code{-stack-list-frames} Command 17605@findex -stack-list-frames 17606 17607@subsubheading Synopsis 17608 17609@smallexample 17610 -stack-list-frames [ @var{low-frame} @var{high-frame} ] 17611@end smallexample 17612 17613List the frames currently on the stack. For each frame it displays the 17614following info: 17615 17616@table @samp 17617@item @var{level} 17618The frame number, 0 being the topmost frame, i.e. the innermost function. 17619@item @var{addr} 17620The @code{$pc} value for that frame. 17621@item @var{func} 17622Function name. 17623@item @var{file} 17624File name of the source file where the function lives. 17625@item @var{line} 17626Line number corresponding to the @code{$pc}. 17627@end table 17628 17629If invoked without arguments, this command prints a backtrace for the 17630whole stack. If given two integer arguments, it shows the frames whose 17631levels are between the two arguments (inclusive). If the two arguments 17632are equal, it shows the single frame at the corresponding level. 17633 17634@subsubheading @value{GDBN} Command 17635 17636The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}. 17637 17638@subsubheading Example 17639 17640Full stack backtrace: 17641 17642@smallexample 17643(@value{GDBP}) 17644-stack-list-frames 17645^done,stack= 17646[frame=@{level="0",addr="0x0001076c",func="foo", 17647 file="recursive2.c",line="11"@}, 17648frame=@{level="1",addr="0x000107a4",func="foo", 17649 file="recursive2.c",line="14"@}, 17650frame=@{level="2",addr="0x000107a4",func="foo", 17651 file="recursive2.c",line="14"@}, 17652frame=@{level="3",addr="0x000107a4",func="foo", 17653 file="recursive2.c",line="14"@}, 17654frame=@{level="4",addr="0x000107a4",func="foo", 17655 file="recursive2.c",line="14"@}, 17656frame=@{level="5",addr="0x000107a4",func="foo", 17657 file="recursive2.c",line="14"@}, 17658frame=@{level="6",addr="0x000107a4",func="foo", 17659 file="recursive2.c",line="14"@}, 17660frame=@{level="7",addr="0x000107a4",func="foo", 17661 file="recursive2.c",line="14"@}, 17662frame=@{level="8",addr="0x000107a4",func="foo", 17663 file="recursive2.c",line="14"@}, 17664frame=@{level="9",addr="0x000107a4",func="foo", 17665 file="recursive2.c",line="14"@}, 17666frame=@{level="10",addr="0x000107a4",func="foo", 17667 file="recursive2.c",line="14"@}, 17668frame=@{level="11",addr="0x00010738",func="main", 17669 file="recursive2.c",line="4"@}] 17670(@value{GDBP}) 17671@end smallexample 17672 17673Show frames between @var{low_frame} and @var{high_frame}: 17674 17675@smallexample 17676(@value{GDBP}) 17677-stack-list-frames 3 5 17678^done,stack= 17679[frame=@{level="3",addr="0x000107a4",func="foo", 17680 file="recursive2.c",line="14"@}, 17681frame=@{level="4",addr="0x000107a4",func="foo", 17682 file="recursive2.c",line="14"@}, 17683frame=@{level="5",addr="0x000107a4",func="foo", 17684 file="recursive2.c",line="14"@}] 17685(@value{GDBP}) 17686@end smallexample 17687 17688Show a single frame: 17689 17690@smallexample 17691(@value{GDBP}) 17692-stack-list-frames 3 3 17693^done,stack= 17694[frame=@{level="3",addr="0x000107a4",func="foo", 17695 file="recursive2.c",line="14"@}] 17696(@value{GDBP}) 17697@end smallexample 17698 17699 17700@subheading The @code{-stack-list-locals} Command 17701@findex -stack-list-locals 17702 17703@subsubheading Synopsis 17704 17705@smallexample 17706 -stack-list-locals @var{print-values} 17707@end smallexample 17708 17709Display the local variable names for the current frame. With an 17710argument of 0 or @code{--no-values}, prints only the names of the variables. 17711With argument of 1 or @code{--all-values}, prints also their values. With 17712argument of 2 or @code{--simple-values}, prints the name, type and value for 17713simple data types and the name and type for arrays, structures and 17714unions. In this last case, the idea is that the user can see the 17715value of simple data types immediately and he can create variable 17716objects for other data types if he wishes to explore their values in 17717more detail. 17718 17719@subsubheading @value{GDBN} Command 17720 17721@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}. 17722 17723@subsubheading Example 17724 17725@smallexample 17726(@value{GDBP}) 17727-stack-list-locals 0 17728^done,locals=[name="A",name="B",name="C"] 17729(@value{GDBP}) 17730-stack-list-locals --all-values 17731^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@}, 17732 @{name="C",value="@{1, 2, 3@}"@}] 17733-stack-list-locals --simple-values 17734^done,locals=[@{name="A",type="int",value="1"@}, 17735 @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}] 17736(@value{GDBP}) 17737@end smallexample 17738 17739 17740@subheading The @code{-stack-select-frame} Command 17741@findex -stack-select-frame 17742 17743@subsubheading Synopsis 17744 17745@smallexample 17746 -stack-select-frame @var{framenum} 17747@end smallexample 17748 17749Change the current frame. Select a different frame @var{framenum} on 17750the stack. 17751 17752@subsubheading @value{GDBN} Command 17753 17754The corresponding @value{GDBN} commands are @samp{frame}, @samp{up}, 17755@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}. 17756 17757@subsubheading Example 17758 17759@smallexample 17760(@value{GDBP}) 17761-stack-select-frame 2 17762^done 17763(@value{GDBP}) 17764@end smallexample 17765 17766@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 17767@node GDB/MI Symbol Query 17768@section @sc{gdb/mi} Symbol Query Commands 17769 17770 17771@subheading The @code{-symbol-info-address} Command 17772@findex -symbol-info-address 17773 17774@subsubheading Synopsis 17775 17776@smallexample 17777 -symbol-info-address @var{symbol} 17778@end smallexample 17779 17780Describe where @var{symbol} is stored. 17781 17782@subsubheading @value{GDBN} Command 17783 17784The corresponding @value{GDBN} command is @samp{info address}. 17785 17786@subsubheading Example 17787N.A. 17788 17789 17790@subheading The @code{-symbol-info-file} Command 17791@findex -symbol-info-file 17792 17793@subsubheading Synopsis 17794 17795@smallexample 17796 -symbol-info-file 17797@end smallexample 17798 17799Show the file for the symbol. 17800 17801@subsubheading @value{GDBN} Command 17802 17803There's no equivalent @value{GDBN} command. @code{gdbtk} has 17804@samp{gdb_find_file}. 17805 17806@subsubheading Example 17807N.A. 17808 17809 17810@subheading The @code{-symbol-info-function} Command 17811@findex -symbol-info-function 17812 17813@subsubheading Synopsis 17814 17815@smallexample 17816 -symbol-info-function 17817@end smallexample 17818 17819Show which function the symbol lives in. 17820 17821@subsubheading @value{GDBN} Command 17822 17823@samp{gdb_get_function} in @code{gdbtk}. 17824 17825@subsubheading Example 17826N.A. 17827 17828 17829@subheading The @code{-symbol-info-line} Command 17830@findex -symbol-info-line 17831 17832@subsubheading Synopsis 17833 17834@smallexample 17835 -symbol-info-line 17836@end smallexample 17837 17838Show the core addresses of the code for a source line. 17839 17840@subsubheading @value{GDBN} Command 17841 17842The corresponding @value{GDBN} command is @samp{info line}. 17843@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands. 17844 17845@subsubheading Example 17846N.A. 17847 17848 17849@subheading The @code{-symbol-info-symbol} Command 17850@findex -symbol-info-symbol 17851 17852@subsubheading Synopsis 17853 17854@smallexample 17855 -symbol-info-symbol @var{addr} 17856@end smallexample 17857 17858Describe what symbol is at location @var{addr}. 17859 17860@subsubheading @value{GDBN} Command 17861 17862The corresponding @value{GDBN} command is @samp{info symbol}. 17863 17864@subsubheading Example 17865N.A. 17866 17867 17868@subheading The @code{-symbol-list-functions} Command 17869@findex -symbol-list-functions 17870 17871@subsubheading Synopsis 17872 17873@smallexample 17874 -symbol-list-functions 17875@end smallexample 17876 17877List the functions in the executable. 17878 17879@subsubheading @value{GDBN} Command 17880 17881@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and 17882@samp{gdb_search} in @code{gdbtk}. 17883 17884@subsubheading Example 17885N.A. 17886 17887 17888@subheading The @code{-symbol-list-lines} Command 17889@findex -symbol-list-lines 17890 17891@subsubheading Synopsis 17892 17893@smallexample 17894 -symbol-list-lines @var{filename} 17895@end smallexample 17896 17897Print the list of lines that contain code and their associated program 17898addresses for the given source filename. The entries are sorted in 17899ascending PC order. 17900 17901@subsubheading @value{GDBN} Command 17902 17903There is no corresponding @value{GDBN} command. 17904 17905@subsubheading Example 17906@smallexample 17907(@value{GDBP}) 17908-symbol-list-lines basics.c 17909^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}] 17910(@value{GDBP}) 17911@end smallexample 17912 17913 17914@subheading The @code{-symbol-list-types} Command 17915@findex -symbol-list-types 17916 17917@subsubheading Synopsis 17918 17919@smallexample 17920 -symbol-list-types 17921@end smallexample 17922 17923List all the type names. 17924 17925@subsubheading @value{GDBN} Command 17926 17927The corresponding commands are @samp{info types} in @value{GDBN}, 17928@samp{gdb_search} in @code{gdbtk}. 17929 17930@subsubheading Example 17931N.A. 17932 17933 17934@subheading The @code{-symbol-list-variables} Command 17935@findex -symbol-list-variables 17936 17937@subsubheading Synopsis 17938 17939@smallexample 17940 -symbol-list-variables 17941@end smallexample 17942 17943List all the global and static variable names. 17944 17945@subsubheading @value{GDBN} Command 17946 17947@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}. 17948 17949@subsubheading Example 17950N.A. 17951 17952 17953@subheading The @code{-symbol-locate} Command 17954@findex -symbol-locate 17955 17956@subsubheading Synopsis 17957 17958@smallexample 17959 -symbol-locate 17960@end smallexample 17961 17962@subsubheading @value{GDBN} Command 17963 17964@samp{gdb_loc} in @code{gdbtk}. 17965 17966@subsubheading Example 17967N.A. 17968 17969 17970@subheading The @code{-symbol-type} Command 17971@findex -symbol-type 17972 17973@subsubheading Synopsis 17974 17975@smallexample 17976 -symbol-type @var{variable} 17977@end smallexample 17978 17979Show type of @var{variable}. 17980 17981@subsubheading @value{GDBN} Command 17982 17983The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has 17984@samp{gdb_obj_variable}. 17985 17986@subsubheading Example 17987N.A. 17988 17989 17990@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 17991@node GDB/MI Target Manipulation 17992@section @sc{gdb/mi} Target Manipulation Commands 17993 17994 17995@subheading The @code{-target-attach} Command 17996@findex -target-attach 17997 17998@subsubheading Synopsis 17999 18000@smallexample 18001 -target-attach @var{pid} | @var{file} 18002@end smallexample 18003 18004Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}. 18005 18006@subsubheading @value{GDBN} command 18007 18008The corresponding @value{GDBN} command is @samp{attach}. 18009 18010@subsubheading Example 18011N.A. 18012 18013 18014@subheading The @code{-target-compare-sections} Command 18015@findex -target-compare-sections 18016 18017@subsubheading Synopsis 18018 18019@smallexample 18020 -target-compare-sections [ @var{section} ] 18021@end smallexample 18022 18023Compare data of section @var{section} on target to the exec file. 18024Without the argument, all sections are compared. 18025 18026@subsubheading @value{GDBN} Command 18027 18028The @value{GDBN} equivalent is @samp{compare-sections}. 18029 18030@subsubheading Example 18031N.A. 18032 18033 18034@subheading The @code{-target-detach} Command 18035@findex -target-detach 18036 18037@subsubheading Synopsis 18038 18039@smallexample 18040 -target-detach 18041@end smallexample 18042 18043Disconnect from the remote target. There's no output. 18044 18045@subsubheading @value{GDBN} command 18046 18047The corresponding @value{GDBN} command is @samp{detach}. 18048 18049@subsubheading Example 18050 18051@smallexample 18052(@value{GDBP}) 18053-target-detach 18054^done 18055(@value{GDBP}) 18056@end smallexample 18057 18058 18059@subheading The @code{-target-disconnect} Command 18060@findex -target-disconnect 18061 18062@subsubheading Synopsis 18063 18064@example 18065 -target-disconnect 18066@end example 18067 18068Disconnect from the remote target. There's no output. 18069 18070@subsubheading @value{GDBN} command 18071 18072The corresponding @value{GDBN} command is @samp{disconnect}. 18073 18074@subsubheading Example 18075 18076@smallexample 18077(@value{GDBP}) 18078-target-disconnect 18079^done 18080(@value{GDBP}) 18081@end smallexample 18082 18083 18084@subheading The @code{-target-download} Command 18085@findex -target-download 18086 18087@subsubheading Synopsis 18088 18089@smallexample 18090 -target-download 18091@end smallexample 18092 18093Loads the executable onto the remote target. 18094It prints out an update message every half second, which includes the fields: 18095 18096@table @samp 18097@item section 18098The name of the section. 18099@item section-sent 18100The size of what has been sent so far for that section. 18101@item section-size 18102The size of the section. 18103@item total-sent 18104The total size of what was sent so far (the current and the previous sections). 18105@item total-size 18106The size of the overall executable to download. 18107@end table 18108 18109@noindent 18110Each message is sent as status record (@pxref{GDB/MI Output Syntax, , 18111@sc{gdb/mi} Output Syntax}). 18112 18113In addition, it prints the name and size of the sections, as they are 18114downloaded. These messages include the following fields: 18115 18116@table @samp 18117@item section 18118The name of the section. 18119@item section-size 18120The size of the section. 18121@item total-size 18122The size of the overall executable to download. 18123@end table 18124 18125@noindent 18126At the end, a summary is printed. 18127 18128@subsubheading @value{GDBN} Command 18129 18130The corresponding @value{GDBN} command is @samp{load}. 18131 18132@subsubheading Example 18133 18134Note: each status message appears on a single line. Here the messages 18135have been broken down so that they can fit onto a page. 18136 18137@smallexample 18138(@value{GDBP}) 18139-target-download 18140+download,@{section=".text",section-size="6668",total-size="9880"@} 18141+download,@{section=".text",section-sent="512",section-size="6668", 18142total-sent="512",total-size="9880"@} 18143+download,@{section=".text",section-sent="1024",section-size="6668", 18144total-sent="1024",total-size="9880"@} 18145+download,@{section=".text",section-sent="1536",section-size="6668", 18146total-sent="1536",total-size="9880"@} 18147+download,@{section=".text",section-sent="2048",section-size="6668", 18148total-sent="2048",total-size="9880"@} 18149+download,@{section=".text",section-sent="2560",section-size="6668", 18150total-sent="2560",total-size="9880"@} 18151+download,@{section=".text",section-sent="3072",section-size="6668", 18152total-sent="3072",total-size="9880"@} 18153+download,@{section=".text",section-sent="3584",section-size="6668", 18154total-sent="3584",total-size="9880"@} 18155+download,@{section=".text",section-sent="4096",section-size="6668", 18156total-sent="4096",total-size="9880"@} 18157+download,@{section=".text",section-sent="4608",section-size="6668", 18158total-sent="4608",total-size="9880"@} 18159+download,@{section=".text",section-sent="5120",section-size="6668", 18160total-sent="5120",total-size="9880"@} 18161+download,@{section=".text",section-sent="5632",section-size="6668", 18162total-sent="5632",total-size="9880"@} 18163+download,@{section=".text",section-sent="6144",section-size="6668", 18164total-sent="6144",total-size="9880"@} 18165+download,@{section=".text",section-sent="6656",section-size="6668", 18166total-sent="6656",total-size="9880"@} 18167+download,@{section=".init",section-size="28",total-size="9880"@} 18168+download,@{section=".fini",section-size="28",total-size="9880"@} 18169+download,@{section=".data",section-size="3156",total-size="9880"@} 18170+download,@{section=".data",section-sent="512",section-size="3156", 18171total-sent="7236",total-size="9880"@} 18172+download,@{section=".data",section-sent="1024",section-size="3156", 18173total-sent="7748",total-size="9880"@} 18174+download,@{section=".data",section-sent="1536",section-size="3156", 18175total-sent="8260",total-size="9880"@} 18176+download,@{section=".data",section-sent="2048",section-size="3156", 18177total-sent="8772",total-size="9880"@} 18178+download,@{section=".data",section-sent="2560",section-size="3156", 18179total-sent="9284",total-size="9880"@} 18180+download,@{section=".data",section-sent="3072",section-size="3156", 18181total-sent="9796",total-size="9880"@} 18182^done,address="0x10004",load-size="9880",transfer-rate="6586", 18183write-rate="429" 18184(@value{GDBP}) 18185@end smallexample 18186 18187 18188@subheading The @code{-target-exec-status} Command 18189@findex -target-exec-status 18190 18191@subsubheading Synopsis 18192 18193@smallexample 18194 -target-exec-status 18195@end smallexample 18196 18197Provide information on the state of the target (whether it is running or 18198not, for instance). 18199 18200@subsubheading @value{GDBN} Command 18201 18202There's no equivalent @value{GDBN} command. 18203 18204@subsubheading Example 18205N.A. 18206 18207 18208@subheading The @code{-target-list-available-targets} Command 18209@findex -target-list-available-targets 18210 18211@subsubheading Synopsis 18212 18213@smallexample 18214 -target-list-available-targets 18215@end smallexample 18216 18217List the possible targets to connect to. 18218 18219@subsubheading @value{GDBN} Command 18220 18221The corresponding @value{GDBN} command is @samp{help target}. 18222 18223@subsubheading Example 18224N.A. 18225 18226 18227@subheading The @code{-target-list-current-targets} Command 18228@findex -target-list-current-targets 18229 18230@subsubheading Synopsis 18231 18232@smallexample 18233 -target-list-current-targets 18234@end smallexample 18235 18236Describe the current target. 18237 18238@subsubheading @value{GDBN} Command 18239 18240The corresponding information is printed by @samp{info file} (among 18241other things). 18242 18243@subsubheading Example 18244N.A. 18245 18246 18247@subheading The @code{-target-list-parameters} Command 18248@findex -target-list-parameters 18249 18250@subsubheading Synopsis 18251 18252@smallexample 18253 -target-list-parameters 18254@end smallexample 18255 18256@c ???? 18257 18258@subsubheading @value{GDBN} Command 18259 18260No equivalent. 18261 18262@subsubheading Example 18263N.A. 18264 18265 18266@subheading The @code{-target-select} Command 18267@findex -target-select 18268 18269@subsubheading Synopsis 18270 18271@smallexample 18272 -target-select @var{type} @var{parameters @dots{}} 18273@end smallexample 18274 18275Connect @value{GDBN} to the remote target. This command takes two args: 18276 18277@table @samp 18278@item @var{type} 18279The type of target, for instance @samp{async}, @samp{remote}, etc. 18280@item @var{parameters} 18281Device names, host names and the like. @xref{Target Commands, , 18282Commands for managing targets}, for more details. 18283@end table 18284 18285The output is a connection notification, followed by the address at 18286which the target program is, in the following form: 18287 18288@smallexample 18289^connected,addr="@var{address}",func="@var{function name}", 18290 args=[@var{arg list}] 18291@end smallexample 18292 18293@subsubheading @value{GDBN} Command 18294 18295The corresponding @value{GDBN} command is @samp{target}. 18296 18297@subsubheading Example 18298 18299@smallexample 18300(@value{GDBP}) 18301-target-select async /dev/ttya 18302^connected,addr="0xfe00a300",func="??",args=[] 18303(@value{GDBP}) 18304@end smallexample 18305 18306@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 18307@node GDB/MI Thread Commands 18308@section @sc{gdb/mi} Thread Commands 18309 18310 18311@subheading The @code{-thread-info} Command 18312@findex -thread-info 18313 18314@subsubheading Synopsis 18315 18316@smallexample 18317 -thread-info 18318@end smallexample 18319 18320@subsubheading @value{GDBN} command 18321 18322No equivalent. 18323 18324@subsubheading Example 18325N.A. 18326 18327 18328@subheading The @code{-thread-list-all-threads} Command 18329@findex -thread-list-all-threads 18330 18331@subsubheading Synopsis 18332 18333@smallexample 18334 -thread-list-all-threads 18335@end smallexample 18336 18337@subsubheading @value{GDBN} Command 18338 18339The equivalent @value{GDBN} command is @samp{info threads}. 18340 18341@subsubheading Example 18342N.A. 18343 18344 18345@subheading The @code{-thread-list-ids} Command 18346@findex -thread-list-ids 18347 18348@subsubheading Synopsis 18349 18350@smallexample 18351 -thread-list-ids 18352@end smallexample 18353 18354Produces a list of the currently known @value{GDBN} thread ids. At the 18355end of the list it also prints the total number of such threads. 18356 18357@subsubheading @value{GDBN} Command 18358 18359Part of @samp{info threads} supplies the same information. 18360 18361@subsubheading Example 18362 18363No threads present, besides the main process: 18364 18365@smallexample 18366(@value{GDBP}) 18367-thread-list-ids 18368^done,thread-ids=@{@},number-of-threads="0" 18369(@value{GDBP}) 18370@end smallexample 18371 18372 18373Several threads: 18374 18375@smallexample 18376(@value{GDBP}) 18377-thread-list-ids 18378^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, 18379number-of-threads="3" 18380(@value{GDBP}) 18381@end smallexample 18382 18383 18384@subheading The @code{-thread-select} Command 18385@findex -thread-select 18386 18387@subsubheading Synopsis 18388 18389@smallexample 18390 -thread-select @var{threadnum} 18391@end smallexample 18392 18393Make @var{threadnum} the current thread. It prints the number of the new 18394current thread, and the topmost frame for that thread. 18395 18396@subsubheading @value{GDBN} Command 18397 18398The corresponding @value{GDBN} command is @samp{thread}. 18399 18400@subsubheading Example 18401 18402@smallexample 18403(@value{GDBP}) 18404-exec-next 18405^running 18406(@value{GDBP}) 18407*stopped,reason="end-stepping-range",thread-id="2",line="187", 18408file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" 18409(@value{GDBP}) 18410-thread-list-ids 18411^done, 18412thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, 18413number-of-threads="3" 18414(@value{GDBP}) 18415-thread-select 3 18416^done,new-thread-id="3", 18417frame=@{level="0",func="vprintf", 18418args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@}, 18419@{name="arg",value="0x2"@}],file="vprintf.c",line="31"@} 18420(@value{GDBP}) 18421@end smallexample 18422 18423@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 18424@node GDB/MI Tracepoint Commands 18425@section @sc{gdb/mi} Tracepoint Commands 18426 18427The tracepoint commands are not yet implemented. 18428 18429@c @subheading -trace-actions 18430 18431@c @subheading -trace-delete 18432 18433@c @subheading -trace-disable 18434 18435@c @subheading -trace-dump 18436 18437@c @subheading -trace-enable 18438 18439@c @subheading -trace-exists 18440 18441@c @subheading -trace-find 18442 18443@c @subheading -trace-frame-number 18444 18445@c @subheading -trace-info 18446 18447@c @subheading -trace-insert 18448 18449@c @subheading -trace-list 18450 18451@c @subheading -trace-pass-count 18452 18453@c @subheading -trace-save 18454 18455@c @subheading -trace-start 18456 18457@c @subheading -trace-stop 18458 18459 18460@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 18461@node GDB/MI Variable Objects 18462@section @sc{gdb/mi} Variable Objects 18463 18464 18465@subheading Motivation for Variable Objects in @sc{gdb/mi} 18466 18467For the implementation of a variable debugger window (locals, watched 18468expressions, etc.), we are proposing the adaptation of the existing code 18469used by @code{Insight}. 18470 18471The two main reasons for that are: 18472 18473@enumerate 1 18474@item 18475It has been proven in practice (it is already on its second generation). 18476 18477@item 18478It will shorten development time (needless to say how important it is 18479now). 18480@end enumerate 18481 18482The original interface was designed to be used by Tcl code, so it was 18483slightly changed so it could be used through @sc{gdb/mi}. This section 18484describes the @sc{gdb/mi} operations that will be available and gives some 18485hints about their use. 18486 18487@emph{Note}: In addition to the set of operations described here, we 18488expect the @sc{gui} implementation of a variable window to require, at 18489least, the following operations: 18490 18491@itemize @bullet 18492@item @code{-gdb-show} @code{output-radix} 18493@item @code{-stack-list-arguments} 18494@item @code{-stack-list-locals} 18495@item @code{-stack-select-frame} 18496@end itemize 18497 18498@subheading Introduction to Variable Objects in @sc{gdb/mi} 18499 18500@cindex variable objects in @sc{gdb/mi} 18501The basic idea behind variable objects is the creation of a named object 18502to represent a variable, an expression, a memory location or even a CPU 18503register. For each object created, a set of operations is available for 18504examining or changing its properties. 18505 18506Furthermore, complex data types, such as C structures, are represented 18507in a tree format. For instance, the @code{struct} type variable is the 18508root and the children will represent the struct members. If a child 18509is itself of a complex type, it will also have children of its own. 18510Appropriate language differences are handled for C, C@t{++} and Java. 18511 18512When returning the actual values of the objects, this facility allows 18513for the individual selection of the display format used in the result 18514creation. It can be chosen among: binary, decimal, hexadecimal, octal 18515and natural. Natural refers to a default format automatically 18516chosen based on the variable type (like decimal for an @code{int}, hex 18517for pointers, etc.). 18518 18519The following is the complete set of @sc{gdb/mi} operations defined to 18520access this functionality: 18521 18522@multitable @columnfractions .4 .6 18523@item @strong{Operation} 18524@tab @strong{Description} 18525 18526@item @code{-var-create} 18527@tab create a variable object 18528@item @code{-var-delete} 18529@tab delete the variable object and its children 18530@item @code{-var-set-format} 18531@tab set the display format of this variable 18532@item @code{-var-show-format} 18533@tab show the display format of this variable 18534@item @code{-var-info-num-children} 18535@tab tells how many children this object has 18536@item @code{-var-list-children} 18537@tab return a list of the object's children 18538@item @code{-var-info-type} 18539@tab show the type of this variable object 18540@item @code{-var-info-expression} 18541@tab print what this variable object represents 18542@item @code{-var-show-attributes} 18543@tab is this variable editable? does it exist here? 18544@item @code{-var-evaluate-expression} 18545@tab get the value of this variable 18546@item @code{-var-assign} 18547@tab set the value of this variable 18548@item @code{-var-update} 18549@tab update the variable and its children 18550@end multitable 18551 18552In the next subsection we describe each operation in detail and suggest 18553how it can be used. 18554 18555@subheading Description And Use of Operations on Variable Objects 18556 18557@subheading The @code{-var-create} Command 18558@findex -var-create 18559 18560@subsubheading Synopsis 18561 18562@smallexample 18563 -var-create @{@var{name} | "-"@} 18564 @{@var{frame-addr} | "*"@} @var{expression} 18565@end smallexample 18566 18567This operation creates a variable object, which allows the monitoring of 18568a variable, the result of an expression, a memory cell or a CPU 18569register. 18570 18571The @var{name} parameter is the string by which the object can be 18572referenced. It must be unique. If @samp{-} is specified, the varobj 18573system will generate a string ``varNNNNNN'' automatically. It will be 18574unique provided that one does not specify @var{name} on that format. 18575The command fails if a duplicate name is found. 18576 18577The frame under which the expression should be evaluated can be 18578specified by @var{frame-addr}. A @samp{*} indicates that the current 18579frame should be used. 18580 18581@var{expression} is any expression valid on the current language set (must not 18582begin with a @samp{*}), or one of the following: 18583 18584@itemize @bullet 18585@item 18586@samp{*@var{addr}}, where @var{addr} is the address of a memory cell 18587 18588@item 18589@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD) 18590 18591@item 18592@samp{$@var{regname}} --- a CPU register name 18593@end itemize 18594 18595@subsubheading Result 18596 18597This operation returns the name, number of children and the type of the 18598object created. Type is returned as a string as the ones generated by 18599the @value{GDBN} CLI: 18600 18601@smallexample 18602 name="@var{name}",numchild="N",type="@var{type}" 18603@end smallexample 18604 18605 18606@subheading The @code{-var-delete} Command 18607@findex -var-delete 18608 18609@subsubheading Synopsis 18610 18611@smallexample 18612 -var-delete @var{name} 18613@end smallexample 18614 18615Deletes a previously created variable object and all of its children. 18616 18617Returns an error if the object @var{name} is not found. 18618 18619 18620@subheading The @code{-var-set-format} Command 18621@findex -var-set-format 18622 18623@subsubheading Synopsis 18624 18625@smallexample 18626 -var-set-format @var{name} @var{format-spec} 18627@end smallexample 18628 18629Sets the output format for the value of the object @var{name} to be 18630@var{format-spec}. 18631 18632The syntax for the @var{format-spec} is as follows: 18633 18634@smallexample 18635 @var{format-spec} @expansion{} 18636 @{binary | decimal | hexadecimal | octal | natural@} 18637@end smallexample 18638 18639 18640@subheading The @code{-var-show-format} Command 18641@findex -var-show-format 18642 18643@subsubheading Synopsis 18644 18645@smallexample 18646 -var-show-format @var{name} 18647@end smallexample 18648 18649Returns the format used to display the value of the object @var{name}. 18650 18651@smallexample 18652 @var{format} @expansion{} 18653 @var{format-spec} 18654@end smallexample 18655 18656 18657@subheading The @code{-var-info-num-children} Command 18658@findex -var-info-num-children 18659 18660@subsubheading Synopsis 18661 18662@smallexample 18663 -var-info-num-children @var{name} 18664@end smallexample 18665 18666Returns the number of children of a variable object @var{name}: 18667 18668@smallexample 18669 numchild=@var{n} 18670@end smallexample 18671 18672 18673@subheading The @code{-var-list-children} Command 18674@findex -var-list-children 18675 18676@subsubheading Synopsis 18677 18678@smallexample 18679 -var-list-children [@var{print-values}] @var{name} 18680@end smallexample 18681 18682Returns a list of the children of the specified variable object. With 18683just the variable object name as an argument or with an optional 18684preceding argument of 0 or @code{--no-values}, prints only the names of the 18685variables. With an optional preceding argument of 1 or @code{--all-values}, 18686also prints their values. 18687 18688@subsubheading Example 18689 18690@smallexample 18691(@value{GDBP}) 18692 -var-list-children n 18693 numchild=@var{n},children=[@{name=@var{name}, 18694 numchild=@var{n},type=@var{type}@},@r{(repeats N times)}] 18695(@value{GDBP}) 18696 -var-list-children --all-values n 18697 numchild=@var{n},children=[@{name=@var{name}, 18698 numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}] 18699@end smallexample 18700 18701 18702@subheading The @code{-var-info-type} Command 18703@findex -var-info-type 18704 18705@subsubheading Synopsis 18706 18707@smallexample 18708 -var-info-type @var{name} 18709@end smallexample 18710 18711Returns the type of the specified variable @var{name}. The type is 18712returned as a string in the same format as it is output by the 18713@value{GDBN} CLI: 18714 18715@smallexample 18716 type=@var{typename} 18717@end smallexample 18718 18719 18720@subheading The @code{-var-info-expression} Command 18721@findex -var-info-expression 18722 18723@subsubheading Synopsis 18724 18725@smallexample 18726 -var-info-expression @var{name} 18727@end smallexample 18728 18729Returns what is represented by the variable object @var{name}: 18730 18731@smallexample 18732 lang=@var{lang-spec},exp=@var{expression} 18733@end smallexample 18734 18735@noindent 18736where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}. 18737 18738@subheading The @code{-var-show-attributes} Command 18739@findex -var-show-attributes 18740 18741@subsubheading Synopsis 18742 18743@smallexample 18744 -var-show-attributes @var{name} 18745@end smallexample 18746 18747List attributes of the specified variable object @var{name}: 18748 18749@smallexample 18750 status=@var{attr} [ ( ,@var{attr} )* ] 18751@end smallexample 18752 18753@noindent 18754where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}. 18755 18756@subheading The @code{-var-evaluate-expression} Command 18757@findex -var-evaluate-expression 18758 18759@subsubheading Synopsis 18760 18761@smallexample 18762 -var-evaluate-expression @var{name} 18763@end smallexample 18764 18765Evaluates the expression that is represented by the specified variable 18766object and returns its value as a string in the current format specified 18767for the object: 18768 18769@smallexample 18770 value=@var{value} 18771@end smallexample 18772 18773Note that one must invoke @code{-var-list-children} for a variable 18774before the value of a child variable can be evaluated. 18775 18776@subheading The @code{-var-assign} Command 18777@findex -var-assign 18778 18779@subsubheading Synopsis 18780 18781@smallexample 18782 -var-assign @var{name} @var{expression} 18783@end smallexample 18784 18785Assigns the value of @var{expression} to the variable object specified 18786by @var{name}. The object must be @samp{editable}. If the variable's 18787value is altered by the assign, the variable will show up in any 18788subsequent @code{-var-update} list. 18789 18790@subsubheading Example 18791 18792@smallexample 18793(@value{GDBP}) 18794-var-assign var1 3 18795^done,value="3" 18796(@value{GDBP}) 18797-var-update * 18798^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}] 18799(@value{GDBP}) 18800@end smallexample 18801 18802@subheading The @code{-var-update} Command 18803@findex -var-update 18804 18805@subsubheading Synopsis 18806 18807@smallexample 18808 -var-update @{@var{name} | "*"@} 18809@end smallexample 18810 18811Update the value of the variable object @var{name} by evaluating its 18812expression after fetching all the new values from memory or registers. 18813A @samp{*} causes all existing variable objects to be updated. 18814 18815 18816@node Annotations 18817@chapter @value{GDBN} Annotations 18818 18819This chapter describes annotations in @value{GDBN}. Annotations were 18820designed to interface @value{GDBN} to graphical user interfaces or other 18821similar programs which want to interact with @value{GDBN} at a 18822relatively high level. 18823 18824The annotation mechanism has largely been superseeded by @sc{gdb/mi} 18825(@pxref{GDB/MI}). 18826 18827@ignore 18828This is Edition @value{EDITION}, @value{DATE}. 18829@end ignore 18830 18831@menu 18832* Annotations Overview:: What annotations are; the general syntax. 18833* Server Prefix:: Issuing a command without affecting user state. 18834* Prompting:: Annotations marking @value{GDBN}'s need for input. 18835* Errors:: Annotations for error messages. 18836* Invalidation:: Some annotations describe things now invalid. 18837* Annotations for Running:: 18838 Whether the program is running, how it stopped, etc. 18839* Source Annotations:: Annotations describing source code. 18840@end menu 18841 18842@node Annotations Overview 18843@section What is an Annotation? 18844@cindex annotations 18845 18846Annotations start with a newline character, two @samp{control-z} 18847characters, and the name of the annotation. If there is no additional 18848information associated with this annotation, the name of the annotation 18849is followed immediately by a newline. If there is additional 18850information, the name of the annotation is followed by a space, the 18851additional information, and a newline. The additional information 18852cannot contain newline characters. 18853 18854Any output not beginning with a newline and two @samp{control-z} 18855characters denotes literal output from @value{GDBN}. Currently there is 18856no need for @value{GDBN} to output a newline followed by two 18857@samp{control-z} characters, but if there was such a need, the 18858annotations could be extended with an @samp{escape} annotation which 18859means those three characters as output. 18860 18861The annotation @var{level}, which is specified using the 18862@option{--annotate} command line option (@pxref{Mode Options}), controls 18863how much information @value{GDBN} prints together with its prompt, 18864values of expressions, source lines, and other types of output. Level 0 18865is for no anntations, level 1 is for use when @value{GDBN} is run as a 18866subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable 18867for programs that control @value{GDBN}, and level 2 annotations have 18868been made obsolete (@pxref{Limitations, , Limitations of the Annotation 18869Interface, annotate, GDB's Obsolete Annotations}). This chapter 18870describes level 3 annotations. 18871 18872A simple example of starting up @value{GDBN} with annotations is: 18873 18874@smallexample 18875$ @kbd{gdb --annotate=3} 18876GNU gdb 6.0 18877Copyright 2003 Free Software Foundation, Inc. 18878GDB is free software, covered by the GNU General Public License, 18879and you are welcome to change it and/or distribute copies of it 18880under certain conditions. 18881Type "show copying" to see the conditions. 18882There is absolutely no warranty for GDB. Type "show warranty" 18883for details. 18884This GDB was configured as "i386-pc-linux-gnu" 18885 18886^Z^Zpre-prompt 18887(@value{GDBP}) 18888^Z^Zprompt 18889@kbd{quit} 18890 18891^Z^Zpost-prompt 18892$ 18893@end smallexample 18894 18895Here @samp{quit} is input to @value{GDBN}; the rest is output from 18896@value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z} 18897denotes a @samp{control-z} character) are annotations; the rest is 18898output from @value{GDBN}. 18899 18900@node Server Prefix 18901@section The Server Prefix 18902@cindex server prefix for annotations 18903 18904To issue a command to @value{GDBN} without affecting certain aspects of 18905the state which is seen by users, prefix it with @samp{server }. This 18906means that this command will not affect the command history, nor will it 18907affect @value{GDBN}'s notion of which command to repeat if @key{RET} is 18908pressed on a line by itself. 18909 18910The server prefix does not affect the recording of values into the value 18911history; to print a value without recording it into the value history, 18912use the @code{output} command instead of the @code{print} command. 18913 18914@node Prompting 18915@section Annotation for @value{GDBN} Input 18916 18917@cindex annotations for prompts 18918When @value{GDBN} prompts for input, it annotates this fact so it is possible 18919to know when to send output, when the output from a given command is 18920over, etc. 18921 18922Different kinds of input each have a different @dfn{input type}. Each 18923input type has three annotations: a @code{pre-} annotation, which 18924denotes the beginning of any prompt which is being output, a plain 18925annotation, which denotes the end of the prompt, and then a @code{post-} 18926annotation which denotes the end of any echo which may (or may not) be 18927associated with the input. For example, the @code{prompt} input type 18928features the following annotations: 18929 18930@smallexample 18931^Z^Zpre-prompt 18932^Z^Zprompt 18933^Z^Zpost-prompt 18934@end smallexample 18935 18936The input types are 18937 18938@table @code 18939@findex pre-prompt 18940@findex prompt 18941@findex post-prompt 18942@item prompt 18943When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt). 18944 18945@findex pre-commands 18946@findex commands 18947@findex post-commands 18948@item commands 18949When @value{GDBN} prompts for a set of commands, like in the @code{commands} 18950command. The annotations are repeated for each command which is input. 18951 18952@findex pre-overload-choice 18953@findex overload-choice 18954@findex post-overload-choice 18955@item overload-choice 18956When @value{GDBN} wants the user to select between various overloaded functions. 18957 18958@findex pre-query 18959@findex query 18960@findex post-query 18961@item query 18962When @value{GDBN} wants the user to confirm a potentially dangerous operation. 18963 18964@findex pre-prompt-for-continue 18965@findex prompt-for-continue 18966@findex post-prompt-for-continue 18967@item prompt-for-continue 18968When @value{GDBN} is asking the user to press return to continue. Note: Don't 18969expect this to work well; instead use @code{set height 0} to disable 18970prompting. This is because the counting of lines is buggy in the 18971presence of annotations. 18972@end table 18973 18974@node Errors 18975@section Errors 18976@cindex annotations for errors, warnings and interrupts 18977 18978@findex quit 18979@smallexample 18980^Z^Zquit 18981@end smallexample 18982 18983This annotation occurs right before @value{GDBN} responds to an interrupt. 18984 18985@findex error 18986@smallexample 18987^Z^Zerror 18988@end smallexample 18989 18990This annotation occurs right before @value{GDBN} responds to an error. 18991 18992Quit and error annotations indicate that any annotations which @value{GDBN} was 18993in the middle of may end abruptly. For example, if a 18994@code{value-history-begin} annotation is followed by a @code{error}, one 18995cannot expect to receive the matching @code{value-history-end}. One 18996cannot expect not to receive it either, however; an error annotation 18997does not necessarily mean that @value{GDBN} is immediately returning all the way 18998to the top level. 18999 19000@findex error-begin 19001A quit or error annotation may be preceded by 19002 19003@smallexample 19004^Z^Zerror-begin 19005@end smallexample 19006 19007Any output between that and the quit or error annotation is the error 19008message. 19009 19010Warning messages are not yet annotated. 19011@c If we want to change that, need to fix warning(), type_error(), 19012@c range_error(), and possibly other places. 19013 19014@node Invalidation 19015@section Invalidation Notices 19016 19017@cindex annotations for invalidation messages 19018The following annotations say that certain pieces of state may have 19019changed. 19020 19021@table @code 19022@findex frames-invalid 19023@item ^Z^Zframes-invalid 19024 19025The frames (for example, output from the @code{backtrace} command) may 19026have changed. 19027 19028@findex breakpoints-invalid 19029@item ^Z^Zbreakpoints-invalid 19030 19031The breakpoints may have changed. For example, the user just added or 19032deleted a breakpoint. 19033@end table 19034 19035@node Annotations for Running 19036@section Running the Program 19037@cindex annotations for running programs 19038 19039@findex starting 19040@findex stopping 19041When the program starts executing due to a @value{GDBN} command such as 19042@code{step} or @code{continue}, 19043 19044@smallexample 19045^Z^Zstarting 19046@end smallexample 19047 19048is output. When the program stops, 19049 19050@smallexample 19051^Z^Zstopped 19052@end smallexample 19053 19054is output. Before the @code{stopped} annotation, a variety of 19055annotations describe how the program stopped. 19056 19057@table @code 19058@findex exited 19059@item ^Z^Zexited @var{exit-status} 19060The program exited, and @var{exit-status} is the exit status (zero for 19061successful exit, otherwise nonzero). 19062 19063@findex signalled 19064@findex signal-name 19065@findex signal-name-end 19066@findex signal-string 19067@findex signal-string-end 19068@item ^Z^Zsignalled 19069The program exited with a signal. After the @code{^Z^Zsignalled}, the 19070annotation continues: 19071 19072@smallexample 19073@var{intro-text} 19074^Z^Zsignal-name 19075@var{name} 19076^Z^Zsignal-name-end 19077@var{middle-text} 19078^Z^Zsignal-string 19079@var{string} 19080^Z^Zsignal-string-end 19081@var{end-text} 19082@end smallexample 19083 19084@noindent 19085where @var{name} is the name of the signal, such as @code{SIGILL} or 19086@code{SIGSEGV}, and @var{string} is the explanation of the signal, such 19087as @code{Illegal Instruction} or @code{Segmentation fault}. 19088@var{intro-text}, @var{middle-text}, and @var{end-text} are for the 19089user's benefit and have no particular format. 19090 19091@findex signal 19092@item ^Z^Zsignal 19093The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is 19094just saying that the program received the signal, not that it was 19095terminated with it. 19096 19097@findex breakpoint 19098@item ^Z^Zbreakpoint @var{number} 19099The program hit breakpoint number @var{number}. 19100 19101@findex watchpoint 19102@item ^Z^Zwatchpoint @var{number} 19103The program hit watchpoint number @var{number}. 19104@end table 19105 19106@node Source Annotations 19107@section Displaying Source 19108@cindex annotations for source display 19109 19110@findex source 19111The following annotation is used instead of displaying source code: 19112 19113@smallexample 19114^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr} 19115@end smallexample 19116 19117where @var{filename} is an absolute file name indicating which source 19118file, @var{line} is the line number within that file (where 1 is the 19119first line in the file), @var{character} is the character position 19120within the file (where 0 is the first character in the file) (for most 19121debug formats this will necessarily point to the beginning of a line), 19122@var{middle} is @samp{middle} if @var{addr} is in the middle of the 19123line, or @samp{beg} if @var{addr} is at the beginning of the line, and 19124@var{addr} is the address in the target program associated with the 19125source which is being displayed. @var{addr} is in the form @samp{0x} 19126followed by one or more lowercase hex digits (note that this does not 19127depend on the language). 19128 19129@node GDB Bugs 19130@chapter Reporting Bugs in @value{GDBN} 19131@cindex bugs in @value{GDBN} 19132@cindex reporting bugs in @value{GDBN} 19133 19134Your bug reports play an essential role in making @value{GDBN} reliable. 19135 19136Reporting a bug may help you by bringing a solution to your problem, or it 19137may not. But in any case the principal function of a bug report is to help 19138the entire community by making the next version of @value{GDBN} work better. Bug 19139reports are your contribution to the maintenance of @value{GDBN}. 19140 19141In order for a bug report to serve its purpose, you must include the 19142information that enables us to fix the bug. 19143 19144@menu 19145* Bug Criteria:: Have you found a bug? 19146* Bug Reporting:: How to report bugs 19147@end menu 19148 19149@node Bug Criteria 19150@section Have you found a bug? 19151@cindex bug criteria 19152 19153If you are not sure whether you have found a bug, here are some guidelines: 19154 19155@itemize @bullet 19156@cindex fatal signal 19157@cindex debugger crash 19158@cindex crash of debugger 19159@item 19160If the debugger gets a fatal signal, for any input whatever, that is a 19161@value{GDBN} bug. Reliable debuggers never crash. 19162 19163@cindex error on valid input 19164@item 19165If @value{GDBN} produces an error message for valid input, that is a 19166bug. (Note that if you're cross debugging, the problem may also be 19167somewhere in the connection to the target.) 19168 19169@cindex invalid input 19170@item 19171If @value{GDBN} does not produce an error message for invalid input, 19172that is a bug. However, you should note that your idea of 19173``invalid input'' might be our idea of ``an extension'' or ``support 19174for traditional practice''. 19175 19176@item 19177If you are an experienced user of debugging tools, your suggestions 19178for improvement of @value{GDBN} are welcome in any case. 19179@end itemize 19180 19181@node Bug Reporting 19182@section How to report bugs 19183@cindex bug reports 19184@cindex @value{GDBN} bugs, reporting 19185 19186A number of companies and individuals offer support for @sc{gnu} products. 19187If you obtained @value{GDBN} from a support organization, we recommend you 19188contact that organization first. 19189 19190You can find contact information for many support companies and 19191individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs 19192distribution. 19193@c should add a web page ref... 19194 19195In any event, we also recommend that you submit bug reports for 19196@value{GDBN}. The prefered method is to submit them directly using 19197@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web 19198page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can 19199be used. 19200 19201@strong{Do not send bug reports to @samp{info-gdb}, or to 19202@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do 19203not want to receive bug reports. Those that do have arranged to receive 19204@samp{bug-gdb}. 19205 19206The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which 19207serves as a repeater. The mailing list and the newsgroup carry exactly 19208the same messages. Often people think of posting bug reports to the 19209newsgroup instead of mailing them. This appears to work, but it has one 19210problem which can be crucial: a newsgroup posting often lacks a mail 19211path back to the sender. Thus, if we need to ask for more information, 19212we may be unable to reach you. For this reason, it is better to send 19213bug reports to the mailing list. 19214 19215The fundamental principle of reporting bugs usefully is this: 19216@strong{report all the facts}. If you are not sure whether to state a 19217fact or leave it out, state it! 19218 19219Often people omit facts because they think they know what causes the 19220problem and assume that some details do not matter. Thus, you might 19221assume that the name of the variable you use in an example does not matter. 19222Well, probably it does not, but one cannot be sure. Perhaps the bug is a 19223stray memory reference which happens to fetch from the location where that 19224name is stored in memory; perhaps, if the name were different, the contents 19225of that location would fool the debugger into doing the right thing despite 19226the bug. Play it safe and give a specific, complete example. That is the 19227easiest thing for you to do, and the most helpful. 19228 19229Keep in mind that the purpose of a bug report is to enable us to fix the 19230bug. It may be that the bug has been reported previously, but neither 19231you nor we can know that unless your bug report is complete and 19232self-contained. 19233 19234Sometimes people give a few sketchy facts and ask, ``Does this ring a 19235bell?'' Those bug reports are useless, and we urge everyone to 19236@emph{refuse to respond to them} except to chide the sender to report 19237bugs properly. 19238 19239To enable us to fix the bug, you should include all these things: 19240 19241@itemize @bullet 19242@item 19243The version of @value{GDBN}. @value{GDBN} announces it if you start 19244with no arguments; you can also print it at any time using @code{show 19245version}. 19246 19247Without this, we will not know whether there is any point in looking for 19248the bug in the current version of @value{GDBN}. 19249 19250@item 19251The type of machine you are using, and the operating system name and 19252version number. 19253 19254@item 19255What compiler (and its version) was used to compile @value{GDBN}---e.g. 19256``@value{GCC}--2.8.1''. 19257 19258@item 19259What compiler (and its version) was used to compile the program you are 19260debugging---e.g. ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP 19261C Compiler''. For GCC, you can say @code{gcc --version} to get this 19262information; for other compilers, see the documentation for those 19263compilers. 19264 19265@item 19266The command arguments you gave the compiler to compile your example and 19267observe the bug. For example, did you use @samp{-O}? To guarantee 19268you will not omit something important, list them all. A copy of the 19269Makefile (or the output from make) is sufficient. 19270 19271If we were to try to guess the arguments, we would probably guess wrong 19272and then we might not encounter the bug. 19273 19274@item 19275A complete input script, and all necessary source files, that will 19276reproduce the bug. 19277 19278@item 19279A description of what behavior you observe that you believe is 19280incorrect. For example, ``It gets a fatal signal.'' 19281 19282Of course, if the bug is that @value{GDBN} gets a fatal signal, then we 19283will certainly notice it. But if the bug is incorrect output, we might 19284not notice unless it is glaringly wrong. You might as well not give us 19285a chance to make a mistake. 19286 19287Even if the problem you experience is a fatal signal, you should still 19288say so explicitly. Suppose something strange is going on, such as, your 19289copy of @value{GDBN} is out of synch, or you have encountered a bug in 19290the C library on your system. (This has happened!) Your copy might 19291crash and ours would not. If you told us to expect a crash, then when 19292ours fails to crash, we would know that the bug was not happening for 19293us. If you had not told us to expect a crash, then we would not be able 19294to draw any conclusion from our observations. 19295 19296@pindex script 19297@cindex recording a session script 19298To collect all this information, you can use a session recording program 19299such as @command{script}, which is available on many Unix systems. 19300Just run your @value{GDBN} session inside @command{script} and then 19301include the @file{typescript} file with your bug report. 19302 19303Another way to record a @value{GDBN} session is to run @value{GDBN} 19304inside Emacs and then save the entire buffer to a file. 19305 19306@item 19307If you wish to suggest changes to the @value{GDBN} source, send us context 19308diffs. If you even discuss something in the @value{GDBN} source, refer to 19309it by context, not by line number. 19310 19311The line numbers in our development sources will not match those in your 19312sources. Your line numbers would convey no useful information to us. 19313 19314@end itemize 19315 19316Here are some things that are not necessary: 19317 19318@itemize @bullet 19319@item 19320A description of the envelope of the bug. 19321 19322Often people who encounter a bug spend a lot of time investigating 19323which changes to the input file will make the bug go away and which 19324changes will not affect it. 19325 19326This is often time consuming and not very useful, because the way we 19327will find the bug is by running a single example under the debugger 19328with breakpoints, not by pure deduction from a series of examples. 19329We recommend that you save your time for something else. 19330 19331Of course, if you can find a simpler example to report @emph{instead} 19332of the original one, that is a convenience for us. Errors in the 19333output will be easier to spot, running under the debugger will take 19334less time, and so on. 19335 19336However, simplification is not vital; if you do not want to do this, 19337report the bug anyway and send us the entire test case you used. 19338 19339@item 19340A patch for the bug. 19341 19342A patch for the bug does help us if it is a good one. But do not omit 19343the necessary information, such as the test case, on the assumption that 19344a patch is all we need. We might see problems with your patch and decide 19345to fix the problem another way, or we might not understand it at all. 19346 19347Sometimes with a program as complicated as @value{GDBN} it is very hard to 19348construct an example that will make the program follow a certain path 19349through the code. If you do not send us the example, we will not be able 19350to construct one, so we will not be able to verify that the bug is fixed. 19351 19352And if we cannot understand what bug you are trying to fix, or why your 19353patch should be an improvement, we will not install it. A test case will 19354help us to understand. 19355 19356@item 19357A guess about what the bug is or what it depends on. 19358 19359Such guesses are usually wrong. Even we cannot guess right about such 19360things without first using the debugger to find the facts. 19361@end itemize 19362 19363@c The readline documentation is distributed with the readline code 19364@c and consists of the two following files: 19365@c rluser.texinfo 19366@c inc-hist.texinfo 19367@c Use -I with makeinfo to point to the appropriate directory, 19368@c environment var TEXINPUTS with TeX. 19369@include rluser.texinfo 19370@include inc-hist.texinfo 19371 19372 19373@node Formatting Documentation 19374@appendix Formatting Documentation 19375 19376@cindex @value{GDBN} reference card 19377@cindex reference card 19378The @value{GDBN} 4 release includes an already-formatted reference card, ready 19379for printing with PostScript or Ghostscript, in the @file{gdb} 19380subdirectory of the main source directory@footnote{In 19381@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN} 19382release.}. If you can use PostScript or Ghostscript with your printer, 19383you can print the reference card immediately with @file{refcard.ps}. 19384 19385The release also includes the source for the reference card. You 19386can format it, using @TeX{}, by typing: 19387 19388@smallexample 19389make refcard.dvi 19390@end smallexample 19391 19392The @value{GDBN} reference card is designed to print in @dfn{landscape} 19393mode on US ``letter'' size paper; 19394that is, on a sheet 11 inches wide by 8.5 inches 19395high. You will need to specify this form of printing as an option to 19396your @sc{dvi} output program. 19397 19398@cindex documentation 19399 19400All the documentation for @value{GDBN} comes as part of the machine-readable 19401distribution. The documentation is written in Texinfo format, which is 19402a documentation system that uses a single source file to produce both 19403on-line information and a printed manual. You can use one of the Info 19404formatting commands to create the on-line version of the documentation 19405and @TeX{} (or @code{texi2roff}) to typeset the printed version. 19406 19407@value{GDBN} includes an already formatted copy of the on-line Info 19408version of this manual in the @file{gdb} subdirectory. The main Info 19409file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to 19410subordinate files matching @samp{gdb.info*} in the same directory. If 19411necessary, you can print out these files, or read them with any editor; 19412but they are easier to read using the @code{info} subsystem in @sc{gnu} 19413Emacs or the standalone @code{info} program, available as part of the 19414@sc{gnu} Texinfo distribution. 19415 19416If you want to format these Info files yourself, you need one of the 19417Info formatting programs, such as @code{texinfo-format-buffer} or 19418@code{makeinfo}. 19419 19420If you have @code{makeinfo} installed, and are in the top level 19421@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of 19422version @value{GDBVN}), you can make the Info file by typing: 19423 19424@smallexample 19425cd gdb 19426make gdb.info 19427@end smallexample 19428 19429If you want to typeset and print copies of this manual, you need @TeX{}, 19430a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the 19431Texinfo definitions file. 19432 19433@TeX{} is a typesetting program; it does not print files directly, but 19434produces output files called @sc{dvi} files. To print a typeset 19435document, you need a program to print @sc{dvi} files. If your system 19436has @TeX{} installed, chances are it has such a program. The precise 19437command to use depends on your system; @kbd{lpr -d} is common; another 19438(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may 19439require a file name without any extension or a @samp{.dvi} extension. 19440 19441@TeX{} also requires a macro definitions file called 19442@file{texinfo.tex}. This file tells @TeX{} how to typeset a document 19443written in Texinfo format. On its own, @TeX{} cannot either read or 19444typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB 19445and is located in the @file{gdb-@var{version-number}/texinfo} 19446directory. 19447 19448If you have @TeX{} and a @sc{dvi} printer program installed, you can 19449typeset and print this manual. First switch to the the @file{gdb} 19450subdirectory of the main source directory (for example, to 19451@file{gdb-@value{GDBVN}/gdb}) and type: 19452 19453@smallexample 19454make gdb.dvi 19455@end smallexample 19456 19457Then give @file{gdb.dvi} to your @sc{dvi} printing program. 19458 19459@node Installing GDB 19460@appendix Installing @value{GDBN} 19461@cindex configuring @value{GDBN} 19462@cindex installation 19463@cindex configuring @value{GDBN}, and source tree subdirectories 19464 19465@value{GDBN} comes with a @code{configure} script that automates the process 19466of preparing @value{GDBN} for installation; you can then use @code{make} to 19467build the @code{gdb} program. 19468@iftex 19469@c irrelevant in info file; it's as current as the code it lives with. 19470@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN}, 19471look at the @file{README} file in the sources; we may have improved the 19472installation procedures since publishing this manual.} 19473@end iftex 19474 19475The @value{GDBN} distribution includes all the source code you need for 19476@value{GDBN} in a single directory, whose name is usually composed by 19477appending the version number to @samp{gdb}. 19478 19479For example, the @value{GDBN} version @value{GDBVN} distribution is in the 19480@file{gdb-@value{GDBVN}} directory. That directory contains: 19481 19482@table @code 19483@item gdb-@value{GDBVN}/configure @r{(and supporting files)} 19484script for configuring @value{GDBN} and all its supporting libraries 19485 19486@item gdb-@value{GDBVN}/gdb 19487the source specific to @value{GDBN} itself 19488 19489@item gdb-@value{GDBVN}/bfd 19490source for the Binary File Descriptor library 19491 19492@item gdb-@value{GDBVN}/include 19493@sc{gnu} include files 19494 19495@item gdb-@value{GDBVN}/libiberty 19496source for the @samp{-liberty} free software library 19497 19498@item gdb-@value{GDBVN}/opcodes 19499source for the library of opcode tables and disassemblers 19500 19501@item gdb-@value{GDBVN}/readline 19502source for the @sc{gnu} command-line interface 19503 19504@item gdb-@value{GDBVN}/glob 19505source for the @sc{gnu} filename pattern-matching subroutine 19506 19507@item gdb-@value{GDBVN}/mmalloc 19508source for the @sc{gnu} memory-mapped malloc package 19509@end table 19510 19511The simplest way to configure and build @value{GDBN} is to run @code{configure} 19512from the @file{gdb-@var{version-number}} source directory, which in 19513this example is the @file{gdb-@value{GDBVN}} directory. 19514 19515First switch to the @file{gdb-@var{version-number}} source directory 19516if you are not already in it; then run @code{configure}. Pass the 19517identifier for the platform on which @value{GDBN} will run as an 19518argument. 19519 19520For example: 19521 19522@smallexample 19523cd gdb-@value{GDBVN} 19524./configure @var{host} 19525make 19526@end smallexample 19527 19528@noindent 19529where @var{host} is an identifier such as @samp{sun4} or 19530@samp{decstation}, that identifies the platform where @value{GDBN} will run. 19531(You can often leave off @var{host}; @code{configure} tries to guess the 19532correct value by examining your system.) 19533 19534Running @samp{configure @var{host}} and then running @code{make} builds the 19535@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty} 19536libraries, then @code{gdb} itself. The configured source files, and the 19537binaries, are left in the corresponding source directories. 19538 19539@need 750 19540@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your 19541system does not recognize this automatically when you run a different 19542shell, you may need to run @code{sh} on it explicitly: 19543 19544@smallexample 19545sh configure @var{host} 19546@end smallexample 19547 19548If you run @code{configure} from a directory that contains source 19549directories for multiple libraries or programs, such as the 19550@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure} 19551creates configuration files for every directory level underneath (unless 19552you tell it not to, with the @samp{--norecursion} option). 19553 19554You should run the @code{configure} script from the top directory in the 19555source tree, the @file{gdb-@var{version-number}} directory. If you run 19556@code{configure} from one of the subdirectories, you will configure only 19557that subdirectory. That is usually not what you want. In particular, 19558if you run the first @code{configure} from the @file{gdb} subdirectory 19559of the @file{gdb-@var{version-number}} directory, you will omit the 19560configuration of @file{bfd}, @file{readline}, and other sibling 19561directories of the @file{gdb} subdirectory. This leads to build errors 19562about missing include files such as @file{bfd/bfd.h}. 19563 19564You can install @code{@value{GDBP}} anywhere; it has no hardwired paths. 19565However, you should make sure that the shell on your path (named by 19566the @samp{SHELL} environment variable) is publicly readable. Remember 19567that @value{GDBN} uses the shell to start your program---some systems refuse to 19568let @value{GDBN} debug child processes whose programs are not readable. 19569 19570@menu 19571* Separate Objdir:: Compiling @value{GDBN} in another directory 19572* Config Names:: Specifying names for hosts and targets 19573* Configure Options:: Summary of options for configure 19574@end menu 19575 19576@node Separate Objdir 19577@section Compiling @value{GDBN} in another directory 19578 19579If you want to run @value{GDBN} versions for several host or target machines, 19580you need a different @code{gdb} compiled for each combination of 19581host and target. @code{configure} is designed to make this easy by 19582allowing you to generate each configuration in a separate subdirectory, 19583rather than in the source directory. If your @code{make} program 19584handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running 19585@code{make} in each of these directories builds the @code{gdb} 19586program specified there. 19587 19588To build @code{gdb} in a separate directory, run @code{configure} 19589with the @samp{--srcdir} option to specify where to find the source. 19590(You also need to specify a path to find @code{configure} 19591itself from your working directory. If the path to @code{configure} 19592would be the same as the argument to @samp{--srcdir}, you can leave out 19593the @samp{--srcdir} option; it is assumed.) 19594 19595For example, with version @value{GDBVN}, you can build @value{GDBN} in a 19596separate directory for a Sun 4 like this: 19597 19598@smallexample 19599@group 19600cd gdb-@value{GDBVN} 19601mkdir ../gdb-sun4 19602cd ../gdb-sun4 19603../gdb-@value{GDBVN}/configure sun4 19604make 19605@end group 19606@end smallexample 19607 19608When @code{configure} builds a configuration using a remote source 19609directory, it creates a tree for the binaries with the same structure 19610(and using the same names) as the tree under the source directory. In 19611the example, you'd find the Sun 4 library @file{libiberty.a} in the 19612directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in 19613@file{gdb-sun4/gdb}. 19614 19615Make sure that your path to the @file{configure} script has just one 19616instance of @file{gdb} in it. If your path to @file{configure} looks 19617like @file{../gdb-@value{GDBVN}/gdb/configure}, you are configuring only 19618one subdirectory of @value{GDBN}, not the whole package. This leads to 19619build errors about missing include files such as @file{bfd/bfd.h}. 19620 19621One popular reason to build several @value{GDBN} configurations in separate 19622directories is to configure @value{GDBN} for cross-compiling (where 19623@value{GDBN} runs on one machine---the @dfn{host}---while debugging 19624programs that run on another machine---the @dfn{target}). 19625You specify a cross-debugging target by 19626giving the @samp{--target=@var{target}} option to @code{configure}. 19627 19628When you run @code{make} to build a program or library, you must run 19629it in a configured directory---whatever directory you were in when you 19630called @code{configure} (or one of its subdirectories). 19631 19632The @code{Makefile} that @code{configure} generates in each source 19633directory also runs recursively. If you type @code{make} in a source 19634directory such as @file{gdb-@value{GDBVN}} (or in a separate configured 19635directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you 19636will build all the required libraries, and then build GDB. 19637 19638When you have multiple hosts or targets configured in separate 19639directories, you can run @code{make} on them in parallel (for example, 19640if they are NFS-mounted on each of the hosts); they will not interfere 19641with each other. 19642 19643@node Config Names 19644@section Specifying names for hosts and targets 19645 19646The specifications used for hosts and targets in the @code{configure} 19647script are based on a three-part naming scheme, but some short predefined 19648aliases are also supported. The full naming scheme encodes three pieces 19649of information in the following pattern: 19650 19651@smallexample 19652@var{architecture}-@var{vendor}-@var{os} 19653@end smallexample 19654 19655For example, you can use the alias @code{sun4} as a @var{host} argument, 19656or as the value for @var{target} in a @code{--target=@var{target}} 19657option. The equivalent full name is @samp{sparc-sun-sunos4}. 19658 19659The @code{configure} script accompanying @value{GDBN} does not provide 19660any query facility to list all supported host and target names or 19661aliases. @code{configure} calls the Bourne shell script 19662@code{config.sub} to map abbreviations to full names; you can read the 19663script, if you wish, or you can use it to test your guesses on 19664abbreviations---for example: 19665 19666@smallexample 19667% sh config.sub i386-linux 19668i386-pc-linux-gnu 19669% sh config.sub alpha-linux 19670alpha-unknown-linux-gnu 19671% sh config.sub hp9k700 19672hppa1.1-hp-hpux 19673% sh config.sub sun4 19674sparc-sun-sunos4.1.1 19675% sh config.sub sun3 19676m68k-sun-sunos4.1.1 19677% sh config.sub i986v 19678Invalid configuration `i986v': machine `i986v' not recognized 19679@end smallexample 19680 19681@noindent 19682@code{config.sub} is also distributed in the @value{GDBN} source 19683directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}). 19684 19685@node Configure Options 19686@section @code{configure} options 19687 19688Here is a summary of the @code{configure} options and arguments that 19689are most often useful for building @value{GDBN}. @code{configure} also has 19690several other options not listed here. @inforef{What Configure 19691Does,,configure.info}, for a full explanation of @code{configure}. 19692 19693@smallexample 19694configure @r{[}--help@r{]} 19695 @r{[}--prefix=@var{dir}@r{]} 19696 @r{[}--exec-prefix=@var{dir}@r{]} 19697 @r{[}--srcdir=@var{dirname}@r{]} 19698 @r{[}--norecursion@r{]} @r{[}--rm@r{]} 19699 @r{[}--target=@var{target}@r{]} 19700 @var{host} 19701@end smallexample 19702 19703@noindent 19704You may introduce options with a single @samp{-} rather than 19705@samp{--} if you prefer; but you may abbreviate option names if you use 19706@samp{--}. 19707 19708@table @code 19709@item --help 19710Display a quick summary of how to invoke @code{configure}. 19711 19712@item --prefix=@var{dir} 19713Configure the source to install programs and files under directory 19714@file{@var{dir}}. 19715 19716@item --exec-prefix=@var{dir} 19717Configure the source to install programs under directory 19718@file{@var{dir}}. 19719 19720@c avoid splitting the warning from the explanation: 19721@need 2000 19722@item --srcdir=@var{dirname} 19723@strong{Warning: using this option requires @sc{gnu} @code{make}, or another 19724@code{make} that implements the @code{VPATH} feature.}@* 19725Use this option to make configurations in directories separate from the 19726@value{GDBN} source directories. Among other things, you can use this to 19727build (or maintain) several configurations simultaneously, in separate 19728directories. @code{configure} writes configuration specific files in 19729the current directory, but arranges for them to use the source in the 19730directory @var{dirname}. @code{configure} creates directories under 19731the working directory in parallel to the source directories below 19732@var{dirname}. 19733 19734@item --norecursion 19735Configure only the directory level where @code{configure} is executed; do not 19736propagate configuration to subdirectories. 19737 19738@item --target=@var{target} 19739Configure @value{GDBN} for cross-debugging programs running on the specified 19740@var{target}. Without this option, @value{GDBN} is configured to debug 19741programs that run on the same machine (@var{host}) as @value{GDBN} itself. 19742 19743There is no convenient way to generate a list of all available targets. 19744 19745@item @var{host} @dots{} 19746Configure @value{GDBN} to run on the specified @var{host}. 19747 19748There is no convenient way to generate a list of all available hosts. 19749@end table 19750 19751There are many other options available as well, but they are generally 19752needed for special purposes only. 19753 19754@node Maintenance Commands 19755@appendix Maintenance Commands 19756@cindex maintenance commands 19757@cindex internal commands 19758 19759In addition to commands intended for @value{GDBN} users, @value{GDBN} 19760includes a number of commands intended for @value{GDBN} developers. 19761These commands are provided here for reference. 19762 19763@table @code 19764@kindex maint info breakpoints 19765@item @anchor{maint info breakpoints}maint info breakpoints 19766Using the same format as @samp{info breakpoints}, display both the 19767breakpoints you've set explicitly, and those @value{GDBN} is using for 19768internal purposes. Internal breakpoints are shown with negative 19769breakpoint numbers. The type column identifies what kind of breakpoint 19770is shown: 19771 19772@table @code 19773@item breakpoint 19774Normal, explicitly set breakpoint. 19775 19776@item watchpoint 19777Normal, explicitly set watchpoint. 19778 19779@item longjmp 19780Internal breakpoint, used to handle correctly stepping through 19781@code{longjmp} calls. 19782 19783@item longjmp resume 19784Internal breakpoint at the target of a @code{longjmp}. 19785 19786@item until 19787Temporary internal breakpoint used by the @value{GDBN} @code{until} command. 19788 19789@item finish 19790Temporary internal breakpoint used by the @value{GDBN} @code{finish} command. 19791 19792@item shlib events 19793Shared library events. 19794 19795@end table 19796 19797@kindex maint internal-error 19798@kindex maint internal-warning 19799@item maint internal-error 19800@itemx maint internal-warning 19801Cause @value{GDBN} to call the internal function @code{internal_error} 19802or @code{internal_warning} and hence behave as though an internal error 19803or internal warning has been detected. In addition to reporting the 19804internal problem, these functions give the user the opportunity to 19805either quit @value{GDBN} or create a core file of the current 19806@value{GDBN} session. 19807 19808@smallexample 19809(@value{GDBP}) @kbd{maint internal-error testing, 1, 2} 19810@dots{}/maint.c:121: internal-error: testing, 1, 2 19811A problem internal to GDB has been detected. Further 19812debugging may prove unreliable. 19813Quit this debugging session? (y or n) @kbd{n} 19814Create a core file? (y or n) @kbd{n} 19815(@value{GDBP}) 19816@end smallexample 19817 19818Takes an optional parameter that is used as the text of the error or 19819warning message. 19820 19821@kindex maint print dummy-frames 19822@item maint print dummy-frames 19823 19824Prints the contents of @value{GDBN}'s internal dummy-frame stack. 19825 19826@smallexample 19827(@value{GDBP}) @kbd{b add} 19828@dots{} 19829(@value{GDBP}) @kbd{print add(2,3)} 19830Breakpoint 2, add (a=2, b=3) at @dots{} 1983158 return (a + b); 19832The program being debugged stopped while in a function called from GDB. 19833@dots{} 19834(@value{GDBP}) @kbd{maint print dummy-frames} 198350x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6 19836 top=0x0200bdd4 id=@{stack=0x200bddc,code=0x101405c@} 19837 call_lo=0x01014000 call_hi=0x01014001 19838(@value{GDBP}) 19839@end smallexample 19840 19841Takes an optional file parameter. 19842 19843@kindex maint print registers 19844@kindex maint print raw-registers 19845@kindex maint print cooked-registers 19846@kindex maint print register-groups 19847@item maint print registers 19848@itemx maint print raw-registers 19849@itemx maint print cooked-registers 19850@itemx maint print register-groups 19851Print @value{GDBN}'s internal register data structures. 19852 19853The command @code{maint print raw-registers} includes the contents of 19854the raw register cache; the command @code{maint print cooked-registers} 19855includes the (cooked) value of all registers; and the command 19856@code{maint print register-groups} includes the groups that each 19857register is a member of. @xref{Registers,, Registers, gdbint, 19858@value{GDBN} Internals}. 19859 19860Takes an optional file parameter. 19861 19862@kindex maint print reggroups 19863@item maint print reggroups 19864Print @value{GDBN}'s internal register group data structures. 19865 19866Takes an optional file parameter. 19867 19868@smallexample 19869(@value{GDBP}) @kbd{maint print reggroups} 19870 Group Type 19871 general user 19872 float user 19873 all user 19874 vector user 19875 system user 19876 save internal 19877 restore internal 19878@end smallexample 19879 19880@kindex maint set profile 19881@kindex maint show profile 19882@cindex profiling GDB 19883@item maint set profile 19884@itemx maint show profile 19885Control profiling of @value{GDBN}. 19886 19887Profiling will be disabled until you use the @samp{maint set profile} 19888command to enable it. When you enable profiling, the system will begin 19889collecting timing and execution count data; when you disable profiling or 19890exit @value{GDBN}, the results will be written to a log file. Remember that 19891if you use profiling, @value{GDBN} will overwrite the profiling log file 19892(often called @file{gmon.out}). If you have a record of important profiling 19893data in a @file{gmon.out} file, be sure to move it to a safe location. 19894 19895Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be 19896compiled with the @samp{-pg} compiler option. 19897 19898@kindex maint set dwarf2 max-cache-age 19899@kindex maint show dwarf2 max-cache-age 19900@item maint set dwarf2 max-cache-age 19901@itemx maint show dwarf2 max-cache-age 19902Control the DWARF 2 compilation unit cache. 19903 19904In object files with inter-compilation-unit references, such as those 19905produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 2 19906reader needs to frequently refer to previously read compilation units. 19907This setting controls how long a compilation unit will remain in the cache 19908if it is not referenced. Setting it to zero disables caching, which will 19909slow down @value{GDBN} startup but reduce memory consumption. 19910 19911@end table 19912 19913 19914@node Remote Protocol 19915@appendix @value{GDBN} Remote Serial Protocol 19916 19917@menu 19918* Overview:: 19919* Packets:: 19920* Stop Reply Packets:: 19921* General Query Packets:: 19922* Register Packet Format:: 19923* Examples:: 19924* File-I/O remote protocol extension:: 19925@end menu 19926 19927@node Overview 19928@section Overview 19929 19930There may be occasions when you need to know something about the 19931protocol---for example, if there is only one serial port to your target 19932machine, you might want your program to do something special if it 19933recognizes a packet meant for @value{GDBN}. 19934 19935In the examples below, @samp{->} and @samp{<-} are used to indicate 19936transmitted and received data respectfully. 19937 19938@cindex protocol, @value{GDBN} remote serial 19939@cindex serial protocol, @value{GDBN} remote 19940@cindex remote serial protocol 19941All @value{GDBN} commands and responses (other than acknowledgments) are 19942sent as a @var{packet}. A @var{packet} is introduced with the character 19943@samp{$}, the actual @var{packet-data}, and the terminating character 19944@samp{#} followed by a two-digit @var{checksum}: 19945 19946@smallexample 19947@code{$}@var{packet-data}@code{#}@var{checksum} 19948@end smallexample 19949@noindent 19950 19951@cindex checksum, for @value{GDBN} remote 19952@noindent 19953The two-digit @var{checksum} is computed as the modulo 256 sum of all 19954characters between the leading @samp{$} and the trailing @samp{#} (an 19955eight bit unsigned checksum). 19956 19957Implementors should note that prior to @value{GDBN} 5.0 the protocol 19958specification also included an optional two-digit @var{sequence-id}: 19959 19960@smallexample 19961@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} 19962@end smallexample 19963 19964@cindex sequence-id, for @value{GDBN} remote 19965@noindent 19966That @var{sequence-id} was appended to the acknowledgment. @value{GDBN} 19967has never output @var{sequence-id}s. Stubs that handle packets added 19968since @value{GDBN} 5.0 must not accept @var{sequence-id}. 19969 19970@cindex acknowledgment, for @value{GDBN} remote 19971When either the host or the target machine receives a packet, the first 19972response expected is an acknowledgment: either @samp{+} (to indicate 19973the package was received correctly) or @samp{-} (to request 19974retransmission): 19975 19976@smallexample 19977-> @code{$}@var{packet-data}@code{#}@var{checksum} 19978<- @code{+} 19979@end smallexample 19980@noindent 19981 19982The host (@value{GDBN}) sends @var{command}s, and the target (the 19983debugging stub incorporated in your program) sends a @var{response}. In 19984the case of step and continue @var{command}s, the response is only sent 19985when the operation has completed (the target has again stopped). 19986 19987@var{packet-data} consists of a sequence of characters with the 19988exception of @samp{#} and @samp{$} (see @samp{X} packet for additional 19989exceptions). 19990 19991Fields within the packet should be separated using @samp{,} @samp{;} or 19992@cindex remote protocol, field separator 19993@samp{:}. Except where otherwise noted all numbers are represented in 19994@sc{hex} with leading zeros suppressed. 19995 19996Implementors should note that prior to @value{GDBN} 5.0, the character 19997@samp{:} could not appear as the third character in a packet (as it 19998would potentially conflict with the @var{sequence-id}). 19999 20000Response @var{data} can be run-length encoded to save space. A @samp{*} 20001means that the next character is an @sc{ascii} encoding giving a repeat count 20002which stands for that many repetitions of the character preceding the 20003@samp{*}. The encoding is @code{n+29}, yielding a printable character 20004where @code{n >=3} (which is where rle starts to win). The printable 20005characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric 20006value greater than 126 should not be used. 20007 20008So: 20009@smallexample 20010"@code{0* }" 20011@end smallexample 20012@noindent 20013means the same as "0000". 20014 20015The error response returned for some packets includes a two character 20016error number. That number is not well defined. 20017 20018For any @var{command} not supported by the stub, an empty response 20019(@samp{$#00}) should be returned. That way it is possible to extend the 20020protocol. A newer @value{GDBN} can tell if a packet is supported based 20021on that response. 20022 20023A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M}, 20024@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are 20025optional. 20026 20027@node Packets 20028@section Packets 20029 20030The following table provides a complete list of all currently defined 20031@var{command}s and their corresponding response @var{data}. 20032 20033@table @r 20034 20035@item @code{!} --- extended mode 20036@cindex @code{!} packet 20037 20038Enable extended mode. In extended mode, the remote server is made 20039persistent. The @samp{R} packet is used to restart the program being 20040debugged. 20041 20042Reply: 20043@table @samp 20044@item OK 20045The remote target both supports and has enabled extended mode. 20046@end table 20047 20048@item @code{?} --- last signal 20049@cindex @code{?} packet 20050 20051Indicate the reason the target halted. The reply is the same as for 20052step and continue. 20053 20054Reply: 20055@xref{Stop Reply Packets}, for the reply specifications. 20056 20057@item @code{a} --- reserved 20058 20059Reserved for future use. 20060 20061@item @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,@dots{}} --- set program arguments @strong{(reserved)} 20062@cindex @code{A} packet 20063 20064Initialized @samp{argv[]} array passed into program. @var{arglen} 20065specifies the number of bytes in the hex encoded byte stream @var{arg}. 20066See @code{gdbserver} for more details. 20067 20068Reply: 20069@table @samp 20070@item OK 20071@item E@var{NN} 20072@end table 20073 20074@item @code{b}@var{baud} --- set baud @strong{(deprecated)} 20075@cindex @code{b} packet 20076 20077Change the serial line speed to @var{baud}. 20078 20079JTC: @emph{When does the transport layer state change? When it's 20080received, or after the ACK is transmitted. In either case, there are 20081problems if the command or the acknowledgment packet is dropped.} 20082 20083Stan: @emph{If people really wanted to add something like this, and get 20084it working for the first time, they ought to modify ser-unix.c to send 20085some kind of out-of-band message to a specially-setup stub and have the 20086switch happen "in between" packets, so that from remote protocol's point 20087of view, nothing actually happened.} 20088 20089@item @code{B}@var{addr},@var{mode} --- set breakpoint @strong{(deprecated)} 20090@cindex @code{B} packet 20091 20092Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a 20093breakpoint at @var{addr}. 20094 20095This packet has been replaced by the @samp{Z} and @samp{z} packets 20096(@pxref{insert breakpoint or watchpoint packet}). 20097 20098@item @code{c}@var{addr} --- continue 20099@cindex @code{c} packet 20100 20101@var{addr} is address to resume. If @var{addr} is omitted, resume at 20102current address. 20103 20104Reply: 20105@xref{Stop Reply Packets}, for the reply specifications. 20106 20107@item @code{C}@var{sig}@code{;}@var{addr} --- continue with signal 20108@cindex @code{C} packet 20109 20110Continue with signal @var{sig} (hex signal number). If 20111@code{;}@var{addr} is omitted, resume at same address. 20112 20113Reply: 20114@xref{Stop Reply Packets}, for the reply specifications. 20115 20116@item @code{d} --- toggle debug @strong{(deprecated)} 20117@cindex @code{d} packet 20118 20119Toggle debug flag. 20120 20121@item @code{D} --- detach 20122@cindex @code{D} packet 20123 20124Detach @value{GDBN} from the remote system. Sent to the remote target 20125before @value{GDBN} disconnects via the @code{detach} command. 20126 20127Reply: 20128@table @samp 20129@item @emph{no response} 20130@value{GDBN} does not check for any response after sending this packet. 20131@end table 20132 20133@item @code{e} --- reserved 20134 20135Reserved for future use. 20136 20137@item @code{E} --- reserved 20138 20139Reserved for future use. 20140 20141@item @code{f} --- reserved 20142 20143Reserved for future use. 20144 20145@item @code{F}@var{RC}@code{,}@var{EE}@code{,}@var{CF}@code{;}@var{XX} --- Reply to target's F packet. 20146@cindex @code{F} packet 20147 20148This packet is send by @value{GDBN} as reply to a @code{F} request packet 20149sent by the target. This is part of the File-I/O protocol extension. 20150@xref{File-I/O remote protocol extension}, for the specification. 20151 20152@item @code{g} --- read registers 20153@anchor{read registers packet} 20154@cindex @code{g} packet 20155 20156Read general registers. 20157 20158Reply: 20159@table @samp 20160@item @var{XX@dots{}} 20161Each byte of register data is described by two hex digits. The bytes 20162with the register are transmitted in target byte order. The size of 20163each register and their position within the @samp{g} @var{packet} are 20164determined by the @value{GDBN} internal macros 20165@var{DEPRECATED_REGISTER_RAW_SIZE} and @var{REGISTER_NAME} macros. The 20166specification of several standard @code{g} packets is specified below. 20167@item E@var{NN} 20168for an error. 20169@end table 20170 20171@item @code{G}@var{XX@dots{}} --- write regs 20172@cindex @code{G} packet 20173 20174@xref{read registers packet}, for a description of the @var{XX@dots{}} 20175data. 20176 20177Reply: 20178@table @samp 20179@item OK 20180for success 20181@item E@var{NN} 20182for an error 20183@end table 20184 20185@item @code{h} --- reserved 20186 20187Reserved for future use. 20188 20189@item @code{H}@var{c}@var{t@dots{}} --- set thread 20190@cindex @code{H} packet 20191 20192Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g}, 20193@samp{G}, et.al.). @var{c} depends on the operation to be performed: it 20194should be @samp{c} for step and continue operations, @samp{g} for other 20195operations. The thread designator @var{t@dots{}} may be -1, meaning all 20196the threads, a thread number, or zero which means pick any thread. 20197 20198Reply: 20199@table @samp 20200@item OK 20201for success 20202@item E@var{NN} 20203for an error 20204@end table 20205 20206@c FIXME: JTC: 20207@c 'H': How restrictive (or permissive) is the thread model. If a 20208@c thread is selected and stopped, are other threads allowed 20209@c to continue to execute? As I mentioned above, I think the 20210@c semantics of each command when a thread is selected must be 20211@c described. For example: 20212@c 20213@c 'g': If the stub supports threads and a specific thread is 20214@c selected, returns the register block from that thread; 20215@c otherwise returns current registers. 20216@c 20217@c 'G' If the stub supports threads and a specific thread is 20218@c selected, sets the registers of the register block of 20219@c that thread; otherwise sets current registers. 20220 20221@item @code{i}@var{addr}@code{,}@var{nnn} --- cycle step @strong{(draft)} 20222@anchor{cycle step packet} 20223@cindex @code{i} packet 20224 20225Step the remote target by a single clock cycle. If @code{,}@var{nnn} is 20226present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle 20227step starting at that address. 20228 20229@item @code{I} --- signal then cycle step @strong{(reserved)} 20230@cindex @code{I} packet 20231 20232@xref{step with signal packet}. @xref{cycle step packet}. 20233 20234@item @code{j} --- reserved 20235 20236Reserved for future use. 20237 20238@item @code{J} --- reserved 20239 20240Reserved for future use. 20241 20242@item @code{k} --- kill request 20243@cindex @code{k} packet 20244 20245FIXME: @emph{There is no description of how to operate when a specific 20246thread context has been selected (i.e.@: does 'k' kill only that 20247thread?)}. 20248 20249@item @code{K} --- reserved 20250 20251Reserved for future use. 20252 20253@item @code{l} --- reserved 20254 20255Reserved for future use. 20256 20257@item @code{L} --- reserved 20258 20259Reserved for future use. 20260 20261@item @code{m}@var{addr}@code{,}@var{length} --- read memory 20262@cindex @code{m} packet 20263 20264Read @var{length} bytes of memory starting at address @var{addr}. 20265Neither @value{GDBN} nor the stub assume that sized memory transfers are 20266assumed using word aligned accesses. FIXME: @emph{A word aligned memory 20267transfer mechanism is needed.} 20268 20269Reply: 20270@table @samp 20271@item @var{XX@dots{}} 20272@var{XX@dots{}} is mem contents. Can be fewer bytes than requested if able 20273to read only part of the data. Neither @value{GDBN} nor the stub assume 20274that sized memory transfers are assumed using word aligned 20275accesses. FIXME: @emph{A word aligned memory transfer mechanism is 20276needed.} 20277@item E@var{NN} 20278@var{NN} is errno 20279@end table 20280 20281@item @code{M}@var{addr},@var{length}@code{:}@var{XX@dots{}} --- write mem 20282@cindex @code{M} packet 20283 20284Write @var{length} bytes of memory starting at address @var{addr}. 20285@var{XX@dots{}} is the data. 20286 20287Reply: 20288@table @samp 20289@item OK 20290for success 20291@item E@var{NN} 20292for an error (this includes the case where only part of the data was 20293written). 20294@end table 20295 20296@item @code{n} --- reserved 20297 20298Reserved for future use. 20299 20300@item @code{N} --- reserved 20301 20302Reserved for future use. 20303 20304@item @code{o} --- reserved 20305 20306Reserved for future use. 20307 20308@item @code{O} --- reserved 20309 20310@item @code{p}@var{hex number of register} --- read register packet 20311@cindex @code{p} packet 20312 20313@xref{read registers packet}, for a description of how the returned 20314register value is encoded. 20315 20316Reply: 20317@table @samp 20318@item @var{XX@dots{}} 20319the register's value 20320@item E@var{NN} 20321for an error 20322@item 20323Indicating an unrecognized @var{query}. 20324@end table 20325 20326@item @code{P}@var{n@dots{}}@code{=}@var{r@dots{}} --- write register 20327@anchor{write register packet} 20328@cindex @code{P} packet 20329 20330Write register @var{n@dots{}} with value @var{r@dots{}}, which contains two hex 20331digits for each byte in the register (target byte order). 20332 20333Reply: 20334@table @samp 20335@item OK 20336for success 20337@item E@var{NN} 20338for an error 20339@end table 20340 20341@item @code{q}@var{query} --- general query 20342@anchor{general query packet} 20343@cindex @code{q} packet 20344 20345Request info about @var{query}. In general @value{GDBN} queries have a 20346leading upper case letter. Custom vendor queries should use a company 20347prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may optionally 20348be followed by a @samp{,} or @samp{;} separated list. Stubs must ensure 20349that they match the full @var{query} name. 20350 20351Reply: 20352@table @samp 20353@item @var{XX@dots{}} 20354Hex encoded data from query. The reply can not be empty. 20355@item E@var{NN} 20356error reply 20357@item 20358Indicating an unrecognized @var{query}. 20359@end table 20360 20361@item @code{Q}@var{var}@code{=}@var{val} --- general set 20362@cindex @code{Q} packet 20363 20364Set value of @var{var} to @var{val}. 20365 20366@xref{general query packet}, for a discussion of naming conventions. 20367 20368@item @code{r} --- reset @strong{(deprecated)} 20369@cindex @code{r} packet 20370 20371Reset the entire system. 20372 20373@item @code{R}@var{XX} --- remote restart 20374@cindex @code{R} packet 20375 20376Restart the program being debugged. @var{XX}, while needed, is ignored. 20377This packet is only available in extended mode. 20378 20379Reply: 20380@table @samp 20381@item @emph{no reply} 20382The @samp{R} packet has no reply. 20383@end table 20384 20385@item @code{s}@var{addr} --- step 20386@cindex @code{s} packet 20387 20388@var{addr} is address to resume. If @var{addr} is omitted, resume at 20389same address. 20390 20391Reply: 20392@xref{Stop Reply Packets}, for the reply specifications. 20393 20394@item @code{S}@var{sig}@code{;}@var{addr} --- step with signal 20395@anchor{step with signal packet} 20396@cindex @code{S} packet 20397 20398Like @samp{C} but step not continue. 20399 20400Reply: 20401@xref{Stop Reply Packets}, for the reply specifications. 20402 20403@item @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} --- search 20404@cindex @code{t} packet 20405 20406Search backwards starting at address @var{addr} for a match with pattern 20407@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes. 20408@var{addr} must be at least 3 digits. 20409 20410@item @code{T}@var{XX} --- thread alive 20411@cindex @code{T} packet 20412 20413Find out if the thread XX is alive. 20414 20415Reply: 20416@table @samp 20417@item OK 20418thread is still alive 20419@item E@var{NN} 20420thread is dead 20421@end table 20422 20423@item @code{u} --- reserved 20424 20425Reserved for future use. 20426 20427@item @code{U} --- reserved 20428 20429Reserved for future use. 20430 20431@item @code{v} --- verbose packet prefix 20432 20433Packets starting with @code{v} are identified by a multi-letter name, 20434up to the first @code{;} or @code{?} (or the end of the packet). 20435 20436@item @code{vCont}[;@var{action}[@code{:}@var{tid}]]... --- extended resume 20437@cindex @code{vCont} packet 20438 20439Resume the inferior. Different actions may be specified for each thread. 20440If an action is specified with no @var{tid}, then it is applied to any 20441threads that don't have a specific action specified; if no default action is 20442specified then other threads should remain stopped. Specifying multiple 20443default actions is an error; specifying no actions is also an error. 20444Thread IDs are specified in hexadecimal. Currently supported actions are: 20445 20446@table @code 20447@item c 20448Continue. 20449@item C@var{sig} 20450Continue with signal @var{sig}. @var{sig} should be two hex digits. 20451@item s 20452Step. 20453@item S@var{sig} 20454Step with signal @var{sig}. @var{sig} should be two hex digits. 20455@end table 20456 20457The optional @var{addr} argument normally associated with these packets is 20458not supported in @code{vCont}. 20459 20460Reply: 20461@xref{Stop Reply Packets}, for the reply specifications. 20462 20463@item @code{vCont?} --- extended resume query 20464@cindex @code{vCont?} packet 20465 20466Query support for the @code{vCont} packet. 20467 20468Reply: 20469@table @samp 20470@item @code{vCont}[;@var{action}]... 20471The @code{vCont} packet is supported. Each @var{action} is a supported 20472command in the @code{vCont} packet. 20473@item 20474The @code{vCont} packet is not supported. 20475@end table 20476 20477@item @code{V} --- reserved 20478 20479Reserved for future use. 20480 20481@item @code{w} --- reserved 20482 20483Reserved for future use. 20484 20485@item @code{W} --- reserved 20486 20487Reserved for future use. 20488 20489@item @code{x} --- reserved 20490 20491Reserved for future use. 20492 20493@item @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX@dots{}} --- write mem (binary) 20494@cindex @code{X} packet 20495 20496@var{addr} is address, @var{length} is number of bytes, @var{XX@dots{}} 20497is binary data. The characters @code{$}, @code{#}, and @code{0x7d} are 20498escaped using @code{0x7d}. 20499 20500Reply: 20501@table @samp 20502@item OK 20503for success 20504@item E@var{NN} 20505for an error 20506@end table 20507 20508@item @code{y} --- reserved 20509 20510Reserved for future use. 20511 20512@item @code{Y} reserved 20513 20514Reserved for future use. 20515 20516@item @code{z}@var{type}@code{,}@var{addr}@code{,}@var{length} --- remove breakpoint or watchpoint @strong{(draft)} 20517@itemx @code{Z}@var{type}@code{,}@var{addr}@code{,}@var{length} --- insert breakpoint or watchpoint @strong{(draft)} 20518@anchor{insert breakpoint or watchpoint packet} 20519@cindex @code{z} packet 20520@cindex @code{Z} packets 20521 20522Insert (@code{Z}) or remove (@code{z}) a @var{type} breakpoint or 20523watchpoint starting at address @var{address} and covering the next 20524@var{length} bytes. 20525 20526Each breakpoint and watchpoint packet @var{type} is documented 20527separately. 20528 20529@emph{Implementation notes: A remote target shall return an empty string 20530for an unrecognized breakpoint or watchpoint packet @var{type}. A 20531remote target shall support either both or neither of a given 20532@code{Z}@var{type}@dots{} and @code{z}@var{type}@dots{} packet pair. To 20533avoid potential problems with duplicate packets, the operations should 20534be implemented in an idempotent way.} 20535 20536@item @code{z}@code{0}@code{,}@var{addr}@code{,}@var{length} --- remove memory breakpoint @strong{(draft)} 20537@item @code{Z}@code{0}@code{,}@var{addr}@code{,}@var{length} --- insert memory breakpoint @strong{(draft)} 20538@cindex @code{z0} packet 20539@cindex @code{Z0} packet 20540 20541Insert (@code{Z0}) or remove (@code{z0}) a memory breakpoint at address 20542@code{addr} of size @code{length}. 20543 20544A memory breakpoint is implemented by replacing the instruction at 20545@var{addr} with a software breakpoint or trap instruction. The 20546@code{length} is used by targets that indicates the size of the 20547breakpoint (in bytes) that should be inserted (e.g., the @sc{arm} and 20548@sc{mips} can insert either a 2 or 4 byte breakpoint). 20549 20550@emph{Implementation note: It is possible for a target to copy or move 20551code that contains memory breakpoints (e.g., when implementing 20552overlays). The behavior of this packet, in the presence of such a 20553target, is not defined.} 20554 20555Reply: 20556@table @samp 20557@item OK 20558success 20559@item 20560not supported 20561@item E@var{NN} 20562for an error 20563@end table 20564 20565@item @code{z}@code{1}@code{,}@var{addr}@code{,}@var{length} --- remove hardware breakpoint @strong{(draft)} 20566@item @code{Z}@code{1}@code{,}@var{addr}@code{,}@var{length} --- insert hardware breakpoint @strong{(draft)} 20567@cindex @code{z1} packet 20568@cindex @code{Z1} packet 20569 20570Insert (@code{Z1}) or remove (@code{z1}) a hardware breakpoint at 20571address @code{addr} of size @code{length}. 20572 20573A hardware breakpoint is implemented using a mechanism that is not 20574dependant on being able to modify the target's memory. 20575 20576@emph{Implementation note: A hardware breakpoint is not affected by code 20577movement.} 20578 20579Reply: 20580@table @samp 20581@item OK 20582success 20583@item 20584not supported 20585@item E@var{NN} 20586for an error 20587@end table 20588 20589@item @code{z}@code{2}@code{,}@var{addr}@code{,}@var{length} --- remove write watchpoint @strong{(draft)} 20590@item @code{Z}@code{2}@code{,}@var{addr}@code{,}@var{length} --- insert write watchpoint @strong{(draft)} 20591@cindex @code{z2} packet 20592@cindex @code{Z2} packet 20593 20594Insert (@code{Z2}) or remove (@code{z2}) a write watchpoint. 20595 20596Reply: 20597@table @samp 20598@item OK 20599success 20600@item 20601not supported 20602@item E@var{NN} 20603for an error 20604@end table 20605 20606@item @code{z}@code{3}@code{,}@var{addr}@code{,}@var{length} --- remove read watchpoint @strong{(draft)} 20607@item @code{Z}@code{3}@code{,}@var{addr}@code{,}@var{length} --- insert read watchpoint @strong{(draft)} 20608@cindex @code{z3} packet 20609@cindex @code{Z3} packet 20610 20611Insert (@code{Z3}) or remove (@code{z3}) a read watchpoint. 20612 20613Reply: 20614@table @samp 20615@item OK 20616success 20617@item 20618not supported 20619@item E@var{NN} 20620for an error 20621@end table 20622 20623@item @code{z}@code{4}@code{,}@var{addr}@code{,}@var{length} --- remove access watchpoint @strong{(draft)} 20624@item @code{Z}@code{4}@code{,}@var{addr}@code{,}@var{length} --- insert access watchpoint @strong{(draft)} 20625@cindex @code{z4} packet 20626@cindex @code{Z4} packet 20627 20628Insert (@code{Z4}) or remove (@code{z4}) an access watchpoint. 20629 20630Reply: 20631@table @samp 20632@item OK 20633success 20634@item 20635not supported 20636@item E@var{NN} 20637for an error 20638@end table 20639 20640@end table 20641 20642@node Stop Reply Packets 20643@section Stop Reply Packets 20644@cindex stop reply packets 20645 20646The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can 20647receive any of the below as a reply. In the case of the @samp{C}, 20648@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned 20649when the target halts. In the below the exact meaning of @samp{signal 20650number} is poorly defined. In general one of the UNIX signal numbering 20651conventions is used. 20652 20653@table @samp 20654 20655@item S@var{AA} 20656@var{AA} is the signal number 20657 20658@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;} 20659@cindex @code{T} packet reply 20660 20661@var{AA} = two hex digit signal number; @var{n...} = register number 20662(hex), @var{r...} = target byte ordered register contents, size defined 20663by @code{DEPRECATED_REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, 20664@var{r...} = thread process ID, this is a hex integer; @var{n...} = 20665(@samp{watch} | @samp{rwatch} | @samp{awatch}, @var{r...} = data 20666address, this is a hex integer; @var{n...} = other string not starting 20667with valid hex digit. @value{GDBN} should ignore this @var{n...}, 20668@var{r...} pair and go on to the next. This way we can extend the 20669protocol. 20670 20671@item W@var{AA} 20672 20673The process exited, and @var{AA} is the exit status. This is only 20674applicable to certain targets. 20675 20676@item X@var{AA} 20677 20678The process terminated with signal @var{AA}. 20679 20680@item O@var{XX@dots{}} 20681 20682@var{XX@dots{}} is hex encoding of @sc{ascii} data. This can happen at 20683any time while the program is running and the debugger should continue 20684to wait for @samp{W}, @samp{T}, etc. 20685 20686@item F@var{call-id}@code{,}@var{parameter@dots{}} 20687 20688@var{call-id} is the identifier which says which host system call should 20689be called. This is just the name of the function. Translation into the 20690correct system call is only applicable as it's defined in @value{GDBN}. 20691@xref{File-I/O remote protocol extension}, for a list of implemented 20692system calls. 20693 20694@var{parameter@dots{}} is a list of parameters as defined for this very 20695system call. 20696 20697The target replies with this packet when it expects @value{GDBN} to call 20698a host system call on behalf of the target. @value{GDBN} replies with 20699an appropriate @code{F} packet and keeps up waiting for the next reply 20700packet from the target. The latest @samp{C}, @samp{c}, @samp{S} or 20701@samp{s} action is expected to be continued. 20702@xref{File-I/O remote protocol extension}, for more details. 20703 20704@end table 20705 20706@node General Query Packets 20707@section General Query Packets 20708 20709The following set and query packets have already been defined. 20710 20711@table @r 20712 20713@item @code{q}@code{C} --- current thread 20714 20715Return the current thread id. 20716 20717Reply: 20718@table @samp 20719@item @code{QC}@var{pid} 20720Where @var{pid} is a HEX encoded 16 bit process id. 20721@item * 20722Any other reply implies the old pid. 20723@end table 20724 20725@item @code{q}@code{fThreadInfo} -- all thread ids 20726 20727@code{q}@code{sThreadInfo} 20728 20729Obtain a list of active thread ids from the target (OS). Since there 20730may be too many active threads to fit into one reply packet, this query 20731works iteratively: it may require more than one query/reply sequence to 20732obtain the entire list of threads. The first query of the sequence will 20733be the @code{qf}@code{ThreadInfo} query; subsequent queries in the 20734sequence will be the @code{qs}@code{ThreadInfo} query. 20735 20736NOTE: replaces the @code{qL} query (see below). 20737 20738Reply: 20739@table @samp 20740@item @code{m}@var{id} 20741A single thread id 20742@item @code{m}@var{id},@var{id}@dots{} 20743a comma-separated list of thread ids 20744@item @code{l} 20745(lower case 'el') denotes end of list. 20746@end table 20747 20748In response to each query, the target will reply with a list of one or 20749more thread ids, in big-endian hex, separated by commas. @value{GDBN} 20750will respond to each reply with a request for more thread ids (using the 20751@code{qs} form of the query), until the target responds with @code{l} 20752(lower-case el, for @code{'last'}). 20753 20754@item @code{q}@code{ThreadExtraInfo}@code{,}@var{id} --- extra thread info 20755 20756Where @var{id} is a thread-id in big-endian hex. Obtain a printable 20757string description of a thread's attributes from the target OS. This 20758string may contain anything that the target OS thinks is interesting for 20759@value{GDBN} to tell the user about the thread. The string is displayed 20760in @value{GDBN}'s @samp{info threads} display. Some examples of 20761possible thread extra info strings are ``Runnable'', or ``Blocked on 20762Mutex''. 20763 20764Reply: 20765@table @samp 20766@item @var{XX@dots{}} 20767Where @var{XX@dots{}} is a hex encoding of @sc{ascii} data, comprising 20768the printable string containing the extra information about the thread's 20769attributes. 20770@end table 20771 20772@item @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread} --- query @var{LIST} or @var{threadLIST} @strong{(deprecated)} 20773 20774Obtain thread information from RTOS. Where: @var{startflag} (one hex 20775digit) is one to indicate the first query and zero to indicate a 20776subsequent query; @var{threadcount} (two hex digits) is the maximum 20777number of threads the response packet can contain; and @var{nextthread} 20778(eight hex digits), for subsequent queries (@var{startflag} is zero), is 20779returned in the response as @var{argthread}. 20780 20781NOTE: this query is replaced by the @code{q}@code{fThreadInfo} query 20782(see above). 20783 20784Reply: 20785@table @samp 20786@item @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread@dots{}} 20787Where: @var{count} (two hex digits) is the number of threads being 20788returned; @var{done} (one hex digit) is zero to indicate more threads 20789and one indicates no further threads; @var{argthreadid} (eight hex 20790digits) is @var{nextthread} from the request packet; @var{thread@dots{}} 20791is a sequence of thread IDs from the target. @var{threadid} (eight hex 20792digits). See @code{remote.c:parse_threadlist_response()}. 20793@end table 20794 20795@item @code{q}@code{CRC:}@var{addr}@code{,}@var{length} --- compute CRC of memory block 20796 20797Reply: 20798@table @samp 20799@item @code{E}@var{NN} 20800An error (such as memory fault) 20801@item @code{C}@var{CRC32} 20802A 32 bit cyclic redundancy check of the specified memory region. 20803@end table 20804 20805@item @code{q}@code{Offsets} --- query sect offs 20806 20807Get section offsets that the target used when re-locating the downloaded 20808image. @emph{Note: while a @code{Bss} offset is included in the 20809response, @value{GDBN} ignores this and instead applies the @code{Data} 20810offset to the @code{Bss} section.} 20811 20812Reply: 20813@table @samp 20814@item @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz} 20815@end table 20816 20817@item @code{q}@code{P}@var{mode}@var{threadid} --- thread info request 20818 20819Returns information on @var{threadid}. Where: @var{mode} is a hex 20820encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID. 20821 20822Reply: 20823@table @samp 20824@item * 20825@end table 20826 20827See @code{remote.c:remote_unpack_thread_info_response()}. 20828 20829@item @code{q}@code{Rcmd,}@var{command} --- remote command 20830 20831@var{command} (hex encoded) is passed to the local interpreter for 20832execution. Invalid commands should be reported using the output string. 20833Before the final result packet, the target may also respond with a 20834number of intermediate @code{O}@var{output} console output packets. 20835@emph{Implementors should note that providing access to a stubs's 20836interpreter may have security implications}. 20837 20838Reply: 20839@table @samp 20840@item OK 20841A command response with no output. 20842@item @var{OUTPUT} 20843A command response with the hex encoded output string @var{OUTPUT}. 20844@item @code{E}@var{NN} 20845Indicate a badly formed request. 20846@item @samp{} 20847When @samp{q}@samp{Rcmd} is not recognized. 20848@end table 20849 20850@item @code{qSymbol::} --- symbol lookup 20851 20852Notify the target that @value{GDBN} is prepared to serve symbol lookup 20853requests. Accept requests from the target for the values of symbols. 20854 20855Reply: 20856@table @samp 20857@item @code{OK} 20858The target does not need to look up any (more) symbols. 20859@item @code{qSymbol:}@var{sym_name} 20860The target requests the value of symbol @var{sym_name} (hex encoded). 20861@value{GDBN} may provide the value by using the 20862@code{qSymbol:}@var{sym_value}:@var{sym_name} message, described below. 20863@end table 20864 20865@item @code{qSymbol:}@var{sym_value}:@var{sym_name} --- symbol value 20866 20867Set the value of @var{sym_name} to @var{sym_value}. 20868 20869@var{sym_name} (hex encoded) is the name of a symbol whose value the 20870target has previously requested. 20871 20872@var{sym_value} (hex) is the value for symbol @var{sym_name}. If 20873@value{GDBN} cannot supply a value for @var{sym_name}, then this field 20874will be empty. 20875 20876Reply: 20877@table @samp 20878@item @code{OK} 20879The target does not need to look up any (more) symbols. 20880@item @code{qSymbol:}@var{sym_name} 20881The target requests the value of a new symbol @var{sym_name} (hex 20882encoded). @value{GDBN} will continue to supply the values of symbols 20883(if available), until the target ceases to request them. 20884@end table 20885 20886@item @code{qPart}:@var{object}:@code{read}:@var{annex}:@var{offset},@var{length} --- read special data 20887 20888Read uninterpreted bytes from the target's special data area 20889identified by the keyword @code{object}. 20890Request @var{length} bytes starting at @var{offset} bytes into the data. 20891The content and encoding of @var{annex} is specific to the object; 20892it can supply additional details about what data to access. 20893 20894Here are the specific requests of this form defined so far. 20895All @samp{@code{qPart}:@var{object}:@code{read}:@dots{}} 20896requests use the same reply formats, listed below. 20897 20898@table @asis 20899@item @code{qPart}:@code{auxv}:@code{read}::@var{offset},@var{length} 20900Access the target's @dfn{auxiliary vector}. @xref{Auxiliary Vector}. 20901Note @var{annex} must be empty. 20902@end table 20903 20904Reply: 20905@table @asis 20906@item @code{OK} 20907The @var{offset} in the request is at the end of the data. 20908There is no more data to be read. 20909 20910@item @var{XX@dots{}} 20911Hex encoded data bytes read. 20912This may be fewer bytes than the @var{length} in the request. 20913 20914@item @code{E00} 20915The request was malformed, or @var{annex} was invalid. 20916 20917@item @code{E}@var{nn} 20918The offset was invalid, or there was an error encountered reading the data. 20919@var{nn} is a hex-encoded @code{errno} value. 20920 20921@item @code{""} (empty) 20922An empty reply indicates the @var{object} or @var{annex} string was not 20923recognized by the stub. 20924@end table 20925 20926@item @code{qPart}:@var{object}:@code{write}:@var{annex}:@var{offset}:@var{data@dots{}} 20927 20928Write uninterpreted bytes into the target's special data area 20929identified by the keyword @code{object}, 20930starting at @var{offset} bytes into the data. 20931@var{data@dots{}} is the hex-encoded data to be written. 20932The content and encoding of @var{annex} is specific to the object; 20933it can supply additional details about what data to access. 20934 20935No requests of this form are presently in use. This specification 20936serves as a placeholder to document the common format that new 20937specific request specifications ought to use. 20938 20939Reply: 20940@table @asis 20941@item @var{nn} 20942@var{nn} (hex encoded) is the number of bytes written. 20943This may be fewer bytes than supplied in the request. 20944 20945@item @code{E00} 20946The request was malformed, or @var{annex} was invalid. 20947 20948@item @code{E}@var{nn} 20949The offset was invalid, or there was an error encountered writing the data. 20950@var{nn} is a hex-encoded @code{errno} value. 20951 20952@item @code{""} (empty) 20953An empty reply indicates the @var{object} or @var{annex} string was not 20954recognized by the stub, or that the object does not support writing. 20955@end table 20956 20957@item @code{qPart}:@var{object}:@var{operation}:@dots{} 20958Requests of this form may be added in the future. When a stub does 20959not recognize the @var{object} keyword, or its support for 20960@var{object} does not recognize the @var{operation} keyword, 20961the stub must respond with an empty packet. 20962@end table 20963 20964@node Register Packet Format 20965@section Register Packet Format 20966 20967The following @samp{g}/@samp{G} packets have previously been defined. 20968In the below, some thirty-two bit registers are transferred as 20969sixty-four bits. Those registers should be zero/sign extended (which?) 20970to fill the space allocated. Register bytes are transfered in target 20971byte order. The two nibbles within a register byte are transfered 20972most-significant - least-significant. 20973 20974@table @r 20975 20976@item MIPS32 20977 20978All registers are transfered as thirty-two bit quantities in the order: 2097932 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point 20980registers; fsr; fir; fp. 20981 20982@item MIPS64 20983 20984All registers are transfered as sixty-four bit quantities (including 20985thirty-two bit registers such as @code{sr}). The ordering is the same 20986as @code{MIPS32}. 20987 20988@end table 20989 20990@node Examples 20991@section Examples 20992 20993Example sequence of a target being re-started. Notice how the restart 20994does not get any direct output: 20995 20996@smallexample 20997-> @code{R00} 20998<- @code{+} 20999@emph{target restarts} 21000-> @code{?} 21001<- @code{+} 21002<- @code{T001:1234123412341234} 21003-> @code{+} 21004@end smallexample 21005 21006Example sequence of a target being stepped by a single instruction: 21007 21008@smallexample 21009-> @code{G1445@dots{}} 21010<- @code{+} 21011-> @code{s} 21012<- @code{+} 21013@emph{time passes} 21014<- @code{T001:1234123412341234} 21015-> @code{+} 21016-> @code{g} 21017<- @code{+} 21018<- @code{1455@dots{}} 21019-> @code{+} 21020@end smallexample 21021 21022@node File-I/O remote protocol extension 21023@section File-I/O remote protocol extension 21024@cindex File-I/O remote protocol extension 21025 21026@menu 21027* File-I/O Overview:: 21028* Protocol basics:: 21029* The F request packet:: 21030* The F reply packet:: 21031* Memory transfer:: 21032* The Ctrl-C message:: 21033* Console I/O:: 21034* The isatty call:: 21035* The system call:: 21036* List of supported calls:: 21037* Protocol specific representation of datatypes:: 21038* Constants:: 21039* File-I/O Examples:: 21040@end menu 21041 21042@node File-I/O Overview 21043@subsection File-I/O Overview 21044@cindex file-i/o overview 21045 21046The File I/O remote protocol extension (short: File-I/O) allows the 21047target to use the hosts file system and console I/O when calling various 21048system calls. System calls on the target system are translated into a 21049remote protocol packet to the host system which then performs the needed 21050actions and returns with an adequate response packet to the target system. 21051This simulates file system operations even on targets that lack file systems. 21052 21053The protocol is defined host- and target-system independent. It uses 21054it's own independent representation of datatypes and values. Both, 21055@value{GDBN} and the target's @value{GDBN} stub are responsible for 21056translating the system dependent values into the unified protocol values 21057when data is transmitted. 21058 21059The communication is synchronous. A system call is possible only 21060when GDB is waiting for the @samp{C}, @samp{c}, @samp{S} or @samp{s} 21061packets. While @value{GDBN} handles the request for a system call, 21062the target is stopped to allow deterministic access to the target's 21063memory. Therefore File-I/O is not interuptible by target signals. It 21064is possible to interrupt File-I/O by a user interrupt (Ctrl-C), though. 21065 21066The target's request to perform a host system call does not finish 21067the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action. That means, 21068after finishing the system call, the target returns to continuing the 21069previous activity (continue, step). No additional continue or step 21070request from @value{GDBN} is required. 21071 21072@smallexample 21073(@value{GDBP}) continue 21074 <- target requests 'system call X' 21075 target is stopped, @value{GDBN} executes system call 21076 -> GDB returns result 21077 ... target continues, GDB returns to wait for the target 21078 <- target hits breakpoint and sends a Txx packet 21079@end smallexample 21080 21081The protocol is only used for files on the host file system and 21082for I/O on the console. Character or block special devices, pipes, 21083named pipes or sockets or any other communication method on the host 21084system are not supported by this protocol. 21085 21086@node Protocol basics 21087@subsection Protocol basics 21088@cindex protocol basics, file-i/o 21089 21090The File-I/O protocol uses the @code{F} packet, as request as well 21091as as reply packet. Since a File-I/O system call can only occur when 21092@value{GDBN} is waiting for the continuing or stepping target, the 21093File-I/O request is a reply that @value{GDBN} has to expect as a result 21094of a former @samp{C}, @samp{c}, @samp{S} or @samp{s} packet. 21095This @code{F} packet contains all information needed to allow @value{GDBN} 21096to call the appropriate host system call: 21097 21098@itemize @bullet 21099@item 21100A unique identifier for the requested system call. 21101 21102@item 21103All parameters to the system call. Pointers are given as addresses 21104in the target memory address space. Pointers to strings are given as 21105pointer/length pair. Numerical values are given as they are. 21106Numerical control values are given in a protocol specific representation. 21107 21108@end itemize 21109 21110At that point @value{GDBN} has to perform the following actions. 21111 21112@itemize @bullet 21113@item 21114If parameter pointer values are given, which point to data needed as input 21115to a system call, @value{GDBN} requests this data from the target with a 21116standard @code{m} packet request. This additional communication has to be 21117expected by the target implementation and is handled as any other @code{m} 21118packet. 21119 21120@item 21121@value{GDBN} translates all value from protocol representation to host 21122representation as needed. Datatypes are coerced into the host types. 21123 21124@item 21125@value{GDBN} calls the system call 21126 21127@item 21128It then coerces datatypes back to protocol representation. 21129 21130@item 21131If pointer parameters in the request packet point to buffer space in which 21132a system call is expected to copy data to, the data is transmitted to the 21133target using a @code{M} or @code{X} packet. This packet has to be expected 21134by the target implementation and is handled as any other @code{M} or @code{X} 21135packet. 21136 21137@end itemize 21138 21139Eventually @value{GDBN} replies with another @code{F} packet which contains all 21140necessary information for the target to continue. This at least contains 21141 21142@itemize @bullet 21143@item 21144Return value. 21145 21146@item 21147@code{errno}, if has been changed by the system call. 21148 21149@item 21150``Ctrl-C'' flag. 21151 21152@end itemize 21153 21154After having done the needed type and value coercion, the target continues 21155the latest continue or step action. 21156 21157@node The F request packet 21158@subsection The @code{F} request packet 21159@cindex file-i/o request packet 21160@cindex @code{F} request packet 21161 21162The @code{F} request packet has the following format: 21163 21164@table @samp 21165 21166@smallexample 21167@code{F}@var{call-id}@code{,}@var{parameter@dots{}} 21168@end smallexample 21169 21170@var{call-id} is the identifier to indicate the host system call to be called. 21171This is just the name of the function. 21172 21173@var{parameter@dots{}} are the parameters to the system call. 21174 21175@end table 21176 21177Parameters are hexadecimal integer values, either the real values in case 21178of scalar datatypes, as pointers to target buffer space in case of compound 21179datatypes and unspecified memory areas or as pointer/length pairs in case 21180of string parameters. These are appended to the call-id, each separated 21181from its predecessor by a comma. All values are transmitted in ASCII 21182string representation, pointer/length pairs separated by a slash. 21183 21184@node The F reply packet 21185@subsection The @code{F} reply packet 21186@cindex file-i/o reply packet 21187@cindex @code{F} reply packet 21188 21189The @code{F} reply packet has the following format: 21190 21191@table @samp 21192 21193@smallexample 21194@code{F}@var{retcode}@code{,}@var{errno}@code{,}@var{Ctrl-C flag}@code{;}@var{call specific attachment} 21195@end smallexample 21196 21197@var{retcode} is the return code of the system call as hexadecimal value. 21198 21199@var{errno} is the errno set by the call, in protocol specific representation. 21200This parameter can be omitted if the call was successful. 21201 21202@var{Ctrl-C flag} is only send if the user requested a break. In this 21203case, @var{errno} must be send as well, even if the call was successful. 21204The @var{Ctrl-C flag} itself consists of the character 'C': 21205 21206@smallexample 21207F0,0,C 21208@end smallexample 21209 21210@noindent 21211or, if the call was interupted before the host call has been performed: 21212 21213@smallexample 21214F-1,4,C 21215@end smallexample 21216 21217@noindent 21218assuming 4 is the protocol specific representation of @code{EINTR}. 21219 21220@end table 21221 21222@node Memory transfer 21223@subsection Memory transfer 21224@cindex memory transfer, in file-i/o protocol 21225 21226Structured data which is transferred using a memory read or write as e.g.@: 21227a @code{struct stat} is expected to be in a protocol specific format with 21228all scalar multibyte datatypes being big endian. This should be done by 21229the target before the @code{F} packet is sent resp.@: by @value{GDBN} before 21230it transfers memory to the target. Transferred pointers to structured 21231data should point to the already coerced data at any time. 21232 21233@node The Ctrl-C message 21234@subsection The Ctrl-C message 21235@cindex ctrl-c message, in file-i/o protocol 21236 21237A special case is, if the @var{Ctrl-C flag} is set in the @value{GDBN} 21238reply packet. In this case the target should behave, as if it had 21239gotten a break message. The meaning for the target is ``system call 21240interupted by @code{SIGINT}''. Consequentially, the target should actually stop 21241(as with a break message) and return to @value{GDBN} with a @code{T02} 21242packet. In this case, it's important for the target to know, in which 21243state the system call was interrupted. Since this action is by design 21244not an atomic operation, we have to differ between two cases: 21245 21246@itemize @bullet 21247@item 21248The system call hasn't been performed on the host yet. 21249 21250@item 21251The system call on the host has been finished. 21252 21253@end itemize 21254 21255These two states can be distinguished by the target by the value of the 21256returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system 21257call hasn't been performed. This is equivalent to the @code{EINTR} handling 21258on POSIX systems. In any other case, the target may presume that the 21259system call has been finished --- successful or not --- and should behave 21260as if the break message arrived right after the system call. 21261 21262@value{GDBN} must behave reliable. If the system call has not been called 21263yet, @value{GDBN} may send the @code{F} reply immediately, setting @code{EINTR} as 21264@code{errno} in the packet. If the system call on the host has been finished 21265before the user requests a break, the full action must be finshed by 21266@value{GDBN}. This requires sending @code{M} or @code{X} packets as they fit. 21267The @code{F} packet may only be send when either nothing has happened 21268or the full action has been completed. 21269 21270@node Console I/O 21271@subsection Console I/O 21272@cindex console i/o as part of file-i/o 21273 21274By default and if not explicitely closed by the target system, the file 21275descriptors 0, 1 and 2 are connected to the @value{GDBN} console. Output 21276on the @value{GDBN} console is handled as any other file output operation 21277(@code{write(1, @dots{})} or @code{write(2, @dots{})}). Console input is handled 21278by @value{GDBN} so that after the target read request from file descriptor 212790 all following typing is buffered until either one of the following 21280conditions is met: 21281 21282@itemize @bullet 21283@item 21284The user presses @kbd{Ctrl-C}. The behaviour is as explained above, the 21285@code{read} 21286system call is treated as finished. 21287 21288@item 21289The user presses @kbd{Enter}. This is treated as end of input with a trailing 21290line feed. 21291 21292@item 21293The user presses @kbd{Ctrl-D}. This is treated as end of input. No trailing 21294character, especially no Ctrl-D is appended to the input. 21295 21296@end itemize 21297 21298If the user has typed more characters as fit in the buffer given to 21299the read call, the trailing characters are buffered in @value{GDBN} until 21300either another @code{read(0, @dots{})} is requested by the target or debugging 21301is stopped on users request. 21302 21303@node The isatty call 21304@subsection The isatty(3) call 21305@cindex isatty call, file-i/o protocol 21306 21307A special case in this protocol is the library call @code{isatty} which 21308is implemented as it's own call inside of this protocol. It returns 213091 to the target if the file descriptor given as parameter is attached 21310to the @value{GDBN} console, 0 otherwise. Implementing through system calls 21311would require implementing @code{ioctl} and would be more complex than 21312needed. 21313 21314@node The system call 21315@subsection The system(3) call 21316@cindex system call, file-i/o protocol 21317 21318The other special case in this protocol is the @code{system} call which 21319is implemented as it's own call, too. @value{GDBN} is taking over the full 21320task of calling the necessary host calls to perform the @code{system} 21321call. The return value of @code{system} is simplified before it's returned 21322to the target. Basically, the only signal transmitted back is @code{EINTR} 21323in case the user pressed @kbd{Ctrl-C}. Otherwise the return value consists 21324entirely of the exit status of the called command. 21325 21326Due to security concerns, the @code{system} call is refused to be called 21327by @value{GDBN} by default. The user has to allow this call explicitly by 21328entering 21329 21330@table @samp 21331@kindex set remote system-call-allowed 1 21332@item @code{set remote system-call-allowed 1} 21333@end table 21334 21335Disabling the @code{system} call is done by 21336 21337@table @samp 21338@kindex set remote system-call-allowed 0 21339@item @code{set remote system-call-allowed 0} 21340@end table 21341 21342The current setting is shown by typing 21343 21344@table @samp 21345@kindex show remote system-call-allowed 21346@item @code{show remote system-call-allowed} 21347@end table 21348 21349@node List of supported calls 21350@subsection List of supported calls 21351@cindex list of supported file-i/o calls 21352 21353@menu 21354* open:: 21355* close:: 21356* read:: 21357* write:: 21358* lseek:: 21359* rename:: 21360* unlink:: 21361* stat/fstat:: 21362* gettimeofday:: 21363* isatty:: 21364* system:: 21365@end menu 21366 21367@node open 21368@unnumberedsubsubsec open 21369@cindex open, file-i/o system call 21370 21371@smallexample 21372@exdent Synopsis: 21373int open(const char *pathname, int flags); 21374int open(const char *pathname, int flags, mode_t mode); 21375 21376@exdent Request: 21377Fopen,pathptr/len,flags,mode 21378@end smallexample 21379 21380@noindent 21381@code{flags} is the bitwise or of the following values: 21382 21383@table @code 21384@item O_CREAT 21385If the file does not exist it will be created. The host 21386rules apply as far as file ownership and time stamps 21387are concerned. 21388 21389@item O_EXCL 21390When used with O_CREAT, if the file already exists it is 21391an error and open() fails. 21392 21393@item O_TRUNC 21394If the file already exists and the open mode allows 21395writing (O_RDWR or O_WRONLY is given) it will be 21396truncated to length 0. 21397 21398@item O_APPEND 21399The file is opened in append mode. 21400 21401@item O_RDONLY 21402The file is opened for reading only. 21403 21404@item O_WRONLY 21405The file is opened for writing only. 21406 21407@item O_RDWR 21408The file is opened for reading and writing. 21409 21410@noindent 21411Each other bit is silently ignored. 21412 21413@end table 21414 21415@noindent 21416@code{mode} is the bitwise or of the following values: 21417 21418@table @code 21419@item S_IRUSR 21420User has read permission. 21421 21422@item S_IWUSR 21423User has write permission. 21424 21425@item S_IRGRP 21426Group has read permission. 21427 21428@item S_IWGRP 21429Group has write permission. 21430 21431@item S_IROTH 21432Others have read permission. 21433 21434@item S_IWOTH 21435Others have write permission. 21436 21437@noindent 21438Each other bit is silently ignored. 21439 21440@end table 21441 21442@smallexample 21443@exdent Return value: 21444open returns the new file descriptor or -1 if an error 21445occured. 21446 21447@exdent Errors: 21448@end smallexample 21449 21450@table @code 21451@item EEXIST 21452pathname already exists and O_CREAT and O_EXCL were used. 21453 21454@item EISDIR 21455pathname refers to a directory. 21456 21457@item EACCES 21458The requested access is not allowed. 21459 21460@item ENAMETOOLONG 21461pathname was too long. 21462 21463@item ENOENT 21464A directory component in pathname does not exist. 21465 21466@item ENODEV 21467pathname refers to a device, pipe, named pipe or socket. 21468 21469@item EROFS 21470pathname refers to a file on a read-only filesystem and 21471write access was requested. 21472 21473@item EFAULT 21474pathname is an invalid pointer value. 21475 21476@item ENOSPC 21477No space on device to create the file. 21478 21479@item EMFILE 21480The process already has the maximum number of files open. 21481 21482@item ENFILE 21483The limit on the total number of files open on the system 21484has been reached. 21485 21486@item EINTR 21487The call was interrupted by the user. 21488@end table 21489 21490@node close 21491@unnumberedsubsubsec close 21492@cindex close, file-i/o system call 21493 21494@smallexample 21495@exdent Synopsis: 21496int close(int fd); 21497 21498@exdent Request: 21499Fclose,fd 21500 21501@exdent Return value: 21502close returns zero on success, or -1 if an error occurred. 21503 21504@exdent Errors: 21505@end smallexample 21506 21507@table @code 21508@item EBADF 21509fd isn't a valid open file descriptor. 21510 21511@item EINTR 21512The call was interrupted by the user. 21513@end table 21514 21515@node read 21516@unnumberedsubsubsec read 21517@cindex read, file-i/o system call 21518 21519@smallexample 21520@exdent Synopsis: 21521int read(int fd, void *buf, unsigned int count); 21522 21523@exdent Request: 21524Fread,fd,bufptr,count 21525 21526@exdent Return value: 21527On success, the number of bytes read is returned. 21528Zero indicates end of file. If count is zero, read 21529returns zero as well. On error, -1 is returned. 21530 21531@exdent Errors: 21532@end smallexample 21533 21534@table @code 21535@item EBADF 21536fd is not a valid file descriptor or is not open for 21537reading. 21538 21539@item EFAULT 21540buf is an invalid pointer value. 21541 21542@item EINTR 21543The call was interrupted by the user. 21544@end table 21545 21546@node write 21547@unnumberedsubsubsec write 21548@cindex write, file-i/o system call 21549 21550@smallexample 21551@exdent Synopsis: 21552int write(int fd, const void *buf, unsigned int count); 21553 21554@exdent Request: 21555Fwrite,fd,bufptr,count 21556 21557@exdent Return value: 21558On success, the number of bytes written are returned. 21559Zero indicates nothing was written. On error, -1 21560is returned. 21561 21562@exdent Errors: 21563@end smallexample 21564 21565@table @code 21566@item EBADF 21567fd is not a valid file descriptor or is not open for 21568writing. 21569 21570@item EFAULT 21571buf is an invalid pointer value. 21572 21573@item EFBIG 21574An attempt was made to write a file that exceeds the 21575host specific maximum file size allowed. 21576 21577@item ENOSPC 21578No space on device to write the data. 21579 21580@item EINTR 21581The call was interrupted by the user. 21582@end table 21583 21584@node lseek 21585@unnumberedsubsubsec lseek 21586@cindex lseek, file-i/o system call 21587 21588@smallexample 21589@exdent Synopsis: 21590long lseek (int fd, long offset, int flag); 21591 21592@exdent Request: 21593Flseek,fd,offset,flag 21594@end smallexample 21595 21596@code{flag} is one of: 21597 21598@table @code 21599@item SEEK_SET 21600The offset is set to offset bytes. 21601 21602@item SEEK_CUR 21603The offset is set to its current location plus offset 21604bytes. 21605 21606@item SEEK_END 21607The offset is set to the size of the file plus offset 21608bytes. 21609@end table 21610 21611@smallexample 21612@exdent Return value: 21613On success, the resulting unsigned offset in bytes from 21614the beginning of the file is returned. Otherwise, a 21615value of -1 is returned. 21616 21617@exdent Errors: 21618@end smallexample 21619 21620@table @code 21621@item EBADF 21622fd is not a valid open file descriptor. 21623 21624@item ESPIPE 21625fd is associated with the @value{GDBN} console. 21626 21627@item EINVAL 21628flag is not a proper value. 21629 21630@item EINTR 21631The call was interrupted by the user. 21632@end table 21633 21634@node rename 21635@unnumberedsubsubsec rename 21636@cindex rename, file-i/o system call 21637 21638@smallexample 21639@exdent Synopsis: 21640int rename(const char *oldpath, const char *newpath); 21641 21642@exdent Request: 21643Frename,oldpathptr/len,newpathptr/len 21644 21645@exdent Return value: 21646On success, zero is returned. On error, -1 is returned. 21647 21648@exdent Errors: 21649@end smallexample 21650 21651@table @code 21652@item EISDIR 21653newpath is an existing directory, but oldpath is not a 21654directory. 21655 21656@item EEXIST 21657newpath is a non-empty directory. 21658 21659@item EBUSY 21660oldpath or newpath is a directory that is in use by some 21661process. 21662 21663@item EINVAL 21664An attempt was made to make a directory a subdirectory 21665of itself. 21666 21667@item ENOTDIR 21668A component used as a directory in oldpath or new 21669path is not a directory. Or oldpath is a directory 21670and newpath exists but is not a directory. 21671 21672@item EFAULT 21673oldpathptr or newpathptr are invalid pointer values. 21674 21675@item EACCES 21676No access to the file or the path of the file. 21677 21678@item ENAMETOOLONG 21679 21680oldpath or newpath was too long. 21681 21682@item ENOENT 21683A directory component in oldpath or newpath does not exist. 21684 21685@item EROFS 21686The file is on a read-only filesystem. 21687 21688@item ENOSPC 21689The device containing the file has no room for the new 21690directory entry. 21691 21692@item EINTR 21693The call was interrupted by the user. 21694@end table 21695 21696@node unlink 21697@unnumberedsubsubsec unlink 21698@cindex unlink, file-i/o system call 21699 21700@smallexample 21701@exdent Synopsis: 21702int unlink(const char *pathname); 21703 21704@exdent Request: 21705Funlink,pathnameptr/len 21706 21707@exdent Return value: 21708On success, zero is returned. On error, -1 is returned. 21709 21710@exdent Errors: 21711@end smallexample 21712 21713@table @code 21714@item EACCES 21715No access to the file or the path of the file. 21716 21717@item EPERM 21718The system does not allow unlinking of directories. 21719 21720@item EBUSY 21721The file pathname cannot be unlinked because it's 21722being used by another process. 21723 21724@item EFAULT 21725pathnameptr is an invalid pointer value. 21726 21727@item ENAMETOOLONG 21728pathname was too long. 21729 21730@item ENOENT 21731A directory component in pathname does not exist. 21732 21733@item ENOTDIR 21734A component of the path is not a directory. 21735 21736@item EROFS 21737The file is on a read-only filesystem. 21738 21739@item EINTR 21740The call was interrupted by the user. 21741@end table 21742 21743@node stat/fstat 21744@unnumberedsubsubsec stat/fstat 21745@cindex fstat, file-i/o system call 21746@cindex stat, file-i/o system call 21747 21748@smallexample 21749@exdent Synopsis: 21750int stat(const char *pathname, struct stat *buf); 21751int fstat(int fd, struct stat *buf); 21752 21753@exdent Request: 21754Fstat,pathnameptr/len,bufptr 21755Ffstat,fd,bufptr 21756 21757@exdent Return value: 21758On success, zero is returned. On error, -1 is returned. 21759 21760@exdent Errors: 21761@end smallexample 21762 21763@table @code 21764@item EBADF 21765fd is not a valid open file. 21766 21767@item ENOENT 21768A directory component in pathname does not exist or the 21769path is an empty string. 21770 21771@item ENOTDIR 21772A component of the path is not a directory. 21773 21774@item EFAULT 21775pathnameptr is an invalid pointer value. 21776 21777@item EACCES 21778No access to the file or the path of the file. 21779 21780@item ENAMETOOLONG 21781pathname was too long. 21782 21783@item EINTR 21784The call was interrupted by the user. 21785@end table 21786 21787@node gettimeofday 21788@unnumberedsubsubsec gettimeofday 21789@cindex gettimeofday, file-i/o system call 21790 21791@smallexample 21792@exdent Synopsis: 21793int gettimeofday(struct timeval *tv, void *tz); 21794 21795@exdent Request: 21796Fgettimeofday,tvptr,tzptr 21797 21798@exdent Return value: 21799On success, 0 is returned, -1 otherwise. 21800 21801@exdent Errors: 21802@end smallexample 21803 21804@table @code 21805@item EINVAL 21806tz is a non-NULL pointer. 21807 21808@item EFAULT 21809tvptr and/or tzptr is an invalid pointer value. 21810@end table 21811 21812@node isatty 21813@unnumberedsubsubsec isatty 21814@cindex isatty, file-i/o system call 21815 21816@smallexample 21817@exdent Synopsis: 21818int isatty(int fd); 21819 21820@exdent Request: 21821Fisatty,fd 21822 21823@exdent Return value: 21824Returns 1 if fd refers to the @value{GDBN} console, 0 otherwise. 21825 21826@exdent Errors: 21827@end smallexample 21828 21829@table @code 21830@item EINTR 21831The call was interrupted by the user. 21832@end table 21833 21834@node system 21835@unnumberedsubsubsec system 21836@cindex system, file-i/o system call 21837 21838@smallexample 21839@exdent Synopsis: 21840int system(const char *command); 21841 21842@exdent Request: 21843Fsystem,commandptr/len 21844 21845@exdent Return value: 21846The value returned is -1 on error and the return status 21847of the command otherwise. Only the exit status of the 21848command is returned, which is extracted from the hosts 21849system return value by calling WEXITSTATUS(retval). 21850In case /bin/sh could not be executed, 127 is returned. 21851 21852@exdent Errors: 21853@end smallexample 21854 21855@table @code 21856@item EINTR 21857The call was interrupted by the user. 21858@end table 21859 21860@node Protocol specific representation of datatypes 21861@subsection Protocol specific representation of datatypes 21862@cindex protocol specific representation of datatypes, in file-i/o protocol 21863 21864@menu 21865* Integral datatypes:: 21866* Pointer values:: 21867* struct stat:: 21868* struct timeval:: 21869@end menu 21870 21871@node Integral datatypes 21872@unnumberedsubsubsec Integral datatypes 21873@cindex integral datatypes, in file-i/o protocol 21874 21875The integral datatypes used in the system calls are 21876 21877@smallexample 21878int@r{,} unsigned int@r{,} long@r{,} unsigned long@r{,} mode_t @r{and} time_t 21879@end smallexample 21880 21881@code{Int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are 21882implemented as 32 bit values in this protocol. 21883 21884@code{Long} and @code{unsigned long} are implemented as 64 bit types. 21885 21886@xref{Limits}, for corresponding MIN and MAX values (similar to those 21887in @file{limits.h}) to allow range checking on host and target. 21888 21889@code{time_t} datatypes are defined as seconds since the Epoch. 21890 21891All integral datatypes transferred as part of a memory read or write of a 21892structured datatype e.g.@: a @code{struct stat} have to be given in big endian 21893byte order. 21894 21895@node Pointer values 21896@unnumberedsubsubsec Pointer values 21897@cindex pointer values, in file-i/o protocol 21898 21899Pointers to target data are transmitted as they are. An exception 21900is made for pointers to buffers for which the length isn't 21901transmitted as part of the function call, namely strings. Strings 21902are transmitted as a pointer/length pair, both as hex values, e.g.@: 21903 21904@smallexample 21905@code{1aaf/12} 21906@end smallexample 21907 21908@noindent 21909which is a pointer to data of length 18 bytes at position 0x1aaf. 21910The length is defined as the full string length in bytes, including 21911the trailing null byte. Example: 21912 21913@smallexample 21914``hello, world'' at address 0x123456 21915@end smallexample 21916 21917@noindent 21918is transmitted as 21919 21920@smallexample 21921@code{123456/d} 21922@end smallexample 21923 21924@node struct stat 21925@unnumberedsubsubsec struct stat 21926@cindex struct stat, in file-i/o protocol 21927 21928The buffer of type struct stat used by the target and @value{GDBN} is defined 21929as follows: 21930 21931@smallexample 21932struct stat @{ 21933 unsigned int st_dev; /* device */ 21934 unsigned int st_ino; /* inode */ 21935 mode_t st_mode; /* protection */ 21936 unsigned int st_nlink; /* number of hard links */ 21937 unsigned int st_uid; /* user ID of owner */ 21938 unsigned int st_gid; /* group ID of owner */ 21939 unsigned int st_rdev; /* device type (if inode device) */ 21940 unsigned long st_size; /* total size, in bytes */ 21941 unsigned long st_blksize; /* blocksize for filesystem I/O */ 21942 unsigned long st_blocks; /* number of blocks allocated */ 21943 time_t st_atime; /* time of last access */ 21944 time_t st_mtime; /* time of last modification */ 21945 time_t st_ctime; /* time of last change */ 21946@}; 21947@end smallexample 21948 21949The integral datatypes are conforming to the definitions given in the 21950approriate section (see @ref{Integral datatypes}, for details) so this 21951structure is of size 64 bytes. 21952 21953The values of several fields have a restricted meaning and/or 21954range of values. 21955 21956@smallexample 21957st_dev: 0 file 21958 1 console 21959 21960st_ino: No valid meaning for the target. Transmitted unchanged. 21961 21962st_mode: Valid mode bits are described in Appendix C. Any other 21963 bits have currently no meaning for the target. 21964 21965st_uid: No valid meaning for the target. Transmitted unchanged. 21966 21967st_gid: No valid meaning for the target. Transmitted unchanged. 21968 21969st_rdev: No valid meaning for the target. Transmitted unchanged. 21970 21971st_atime, st_mtime, st_ctime: 21972 These values have a host and file system dependent 21973 accuracy. Especially on Windows hosts the file systems 21974 don't support exact timing values. 21975@end smallexample 21976 21977The target gets a struct stat of the above representation and is 21978responsible to coerce it to the target representation before 21979continuing. 21980 21981Note that due to size differences between the host and target 21982representation of stat members, these members could eventually 21983get truncated on the target. 21984 21985@node struct timeval 21986@unnumberedsubsubsec struct timeval 21987@cindex struct timeval, in file-i/o protocol 21988 21989The buffer of type struct timeval used by the target and @value{GDBN} 21990is defined as follows: 21991 21992@smallexample 21993struct timeval @{ 21994 time_t tv_sec; /* second */ 21995 long tv_usec; /* microsecond */ 21996@}; 21997@end smallexample 21998 21999The integral datatypes are conforming to the definitions given in the 22000approriate section (see @ref{Integral datatypes}, for details) so this 22001structure is of size 8 bytes. 22002 22003@node Constants 22004@subsection Constants 22005@cindex constants, in file-i/o protocol 22006 22007The following values are used for the constants inside of the 22008protocol. @value{GDBN} and target are resposible to translate these 22009values before and after the call as needed. 22010 22011@menu 22012* Open flags:: 22013* mode_t values:: 22014* Errno values:: 22015* Lseek flags:: 22016* Limits:: 22017@end menu 22018 22019@node Open flags 22020@unnumberedsubsubsec Open flags 22021@cindex open flags, in file-i/o protocol 22022 22023All values are given in hexadecimal representation. 22024 22025@smallexample 22026 O_RDONLY 0x0 22027 O_WRONLY 0x1 22028 O_RDWR 0x2 22029 O_APPEND 0x8 22030 O_CREAT 0x200 22031 O_TRUNC 0x400 22032 O_EXCL 0x800 22033@end smallexample 22034 22035@node mode_t values 22036@unnumberedsubsubsec mode_t values 22037@cindex mode_t values, in file-i/o protocol 22038 22039All values are given in octal representation. 22040 22041@smallexample 22042 S_IFREG 0100000 22043 S_IFDIR 040000 22044 S_IRUSR 0400 22045 S_IWUSR 0200 22046 S_IXUSR 0100 22047 S_IRGRP 040 22048 S_IWGRP 020 22049 S_IXGRP 010 22050 S_IROTH 04 22051 S_IWOTH 02 22052 S_IXOTH 01 22053@end smallexample 22054 22055@node Errno values 22056@unnumberedsubsubsec Errno values 22057@cindex errno values, in file-i/o protocol 22058 22059All values are given in decimal representation. 22060 22061@smallexample 22062 EPERM 1 22063 ENOENT 2 22064 EINTR 4 22065 EBADF 9 22066 EACCES 13 22067 EFAULT 14 22068 EBUSY 16 22069 EEXIST 17 22070 ENODEV 19 22071 ENOTDIR 20 22072 EISDIR 21 22073 EINVAL 22 22074 ENFILE 23 22075 EMFILE 24 22076 EFBIG 27 22077 ENOSPC 28 22078 ESPIPE 29 22079 EROFS 30 22080 ENAMETOOLONG 91 22081 EUNKNOWN 9999 22082@end smallexample 22083 22084 EUNKNOWN is used as a fallback error value if a host system returns 22085 any error value not in the list of supported error numbers. 22086 22087@node Lseek flags 22088@unnumberedsubsubsec Lseek flags 22089@cindex lseek flags, in file-i/o protocol 22090 22091@smallexample 22092 SEEK_SET 0 22093 SEEK_CUR 1 22094 SEEK_END 2 22095@end smallexample 22096 22097@node Limits 22098@unnumberedsubsubsec Limits 22099@cindex limits, in file-i/o protocol 22100 22101All values are given in decimal representation. 22102 22103@smallexample 22104 INT_MIN -2147483648 22105 INT_MAX 2147483647 22106 UINT_MAX 4294967295 22107 LONG_MIN -9223372036854775808 22108 LONG_MAX 9223372036854775807 22109 ULONG_MAX 18446744073709551615 22110@end smallexample 22111 22112@node File-I/O Examples 22113@subsection File-I/O Examples 22114@cindex file-i/o examples 22115 22116Example sequence of a write call, file descriptor 3, buffer is at target 22117address 0x1234, 6 bytes should be written: 22118 22119@smallexample 22120<- @code{Fwrite,3,1234,6} 22121@emph{request memory read from target} 22122-> @code{m1234,6} 22123<- XXXXXX 22124@emph{return "6 bytes written"} 22125-> @code{F6} 22126@end smallexample 22127 22128Example sequence of a read call, file descriptor 3, buffer is at target 22129address 0x1234, 6 bytes should be read: 22130 22131@smallexample 22132<- @code{Fread,3,1234,6} 22133@emph{request memory write to target} 22134-> @code{X1234,6:XXXXXX} 22135@emph{return "6 bytes read"} 22136-> @code{F6} 22137@end smallexample 22138 22139Example sequence of a read call, call fails on the host due to invalid 22140file descriptor (EBADF): 22141 22142@smallexample 22143<- @code{Fread,3,1234,6} 22144-> @code{F-1,9} 22145@end smallexample 22146 22147Example sequence of a read call, user presses Ctrl-C before syscall on 22148host is called: 22149 22150@smallexample 22151<- @code{Fread,3,1234,6} 22152-> @code{F-1,4,C} 22153<- @code{T02} 22154@end smallexample 22155 22156Example sequence of a read call, user presses Ctrl-C after syscall on 22157host is called: 22158 22159@smallexample 22160<- @code{Fread,3,1234,6} 22161-> @code{X1234,6:XXXXXX} 22162<- @code{T02} 22163@end smallexample 22164 22165@include agentexpr.texi 22166 22167@include gpl.texi 22168 22169@raisesections 22170@include fdl.texi 22171@lowersections 22172 22173@node Index 22174@unnumbered Index 22175 22176@printindex cp 22177 22178@tex 22179% I think something like @colophon should be in texinfo. In the 22180% meantime: 22181\long\def\colophon{\hbox to0pt{}\vfill 22182\centerline{The body of this manual is set in} 22183\centerline{\fontname\tenrm,} 22184\centerline{with headings in {\bf\fontname\tenbf}} 22185\centerline{and examples in {\tt\fontname\tentt}.} 22186\centerline{{\it\fontname\tenit\/},} 22187\centerline{{\bf\fontname\tenbf}, and} 22188\centerline{{\sl\fontname\tensl\/}} 22189\centerline{are used for emphasis.}\vfill} 22190\page\colophon 22191% Blame: doc@cygnus.com, 1991. 22192@end tex 22193 22194@bye 22195